The flexibility of Blueprints sits on the ability of being agnostic to the structure of the payload sent. This page describes the syntax of our dynamic value engine which enables interopolation, short-circut evaluation, static values and mutation of data via functions.

Interpolation

Anywhere within the value side of the JSON, within a Blueprint, you can interpolate data from the provided payload. To declare the interpolation use the $ symbol followed by curly braces {} like ${}. Inside the curly braces, define the variable (s) (and functions) according to your business needs.

So if you had an expected payload of { "foo": "bar" } an example of defining a dynamic variable for 'foo' would be the following.

{
   "name" : "${foo}"
}

The resulting output will be:

{
   "name" : "bar""
}

Short-Circuit Evaluation

You can provide more than one value within any interpolation declaration using comma-separated values. The first non-falsy value will be used.

So given the following declaration ${amount,amountDue,amountToPay} and then given the payload of {"amountDue": 100 } the interpolated value will be 100. But since possible values can be found from amount and amountToPay the same Blueprint can be fed payloads from various sources and still work as expected.

Static Values

Pretty straightforward, you can define a static value in quotes and it will always be true. So make it the last value in your declaration and you won't ever have to worry about a value being undefined. For example, ${amount,100} will be 100 when the payload provided does not have an amount attribute.

Data Casting

By default, when dynamic variables are interpolated, the resulting value is a string defined within double quotes, such as "Authvia" or "100". In some cases, when we need a numeric or boolean value, we can use formatting like the one defined in the Blueprint Example, such as ${amount:number}, which converts the interpolated value to a number.

Here are some available type formattings -

1. :number - When defined at the end, it converts the resulting value to a number, for example, from "100" to 100.
2. :string - When defined at the end, it converts the resulting value to a string, for example, from 100 to "100".
3. :boolean - When defined at the end, it converts the resulting value to a boolean, for example, from "true" to true or "false" to false.

Real-ish Example

So, in the example below, we have two dynamic variables: ${amount:number} and ${ref}. These variables will be stored under Account (merchant) when creating a Blueprint.

Example Blueprint:

{
  "actions": [
    {
      "context": {
        "amount": "${amount:number}"
      },
      "features": {
        "description": "12 Dozen Roses"
      },
      "type": "payment"
    }
  ],
  "name": "Payment [Blueprint](blueprints)",
  "description": "Sending a payment [Business Process](business-processes) request to [Customer](customers) using [Blueprint](blueprints)",
  "customer": "${ref}",
  "expiration": "30d"
}

When executing the above Blueprint using execute Blueprint, we provide the following payload with dynamic variables mentioned in the Blueprint example.

Example of a [Blueprint](blueprints) Execution Payload:
{
   "ref": "CUSTOMER_REFERENCE",
   "amount": 1000
}

The ref serves as a Customer reference within an Account (merchant), created through create customer. We specify a payment action where the amount must be provided as a numerical value.

Let's observe how interpolation affects the Blueprint example before submitting it to create Business Process

Example of Interpolation Result:
{
  "actions": [
    {
      "context": {
        "amount": 1000
      },
      "features": {
        "description": "12 Dozen Roses"
      },
      "type": "payment"
    }
  ],
  "name": "Payment [Blueprint](blueprints)",
  "description": "Sending a payment [Business Process](business-processes) request to [Customer](customers) using [Blueprint](blueprints)",
  "customer": "CUSTOMER_REFERENCE",
  "expiration": "30d"
}

During execution, there might be cases where an incorrect value is provided that does not conform to the respective [Action Catalog.

📘

Info

Creating a Trigger with an AJV schema to provide data validation for a Blueprint is an excellent approach to building a business using Blueprints.

With an AJV schema, Merchants can define dynamic variables as input with validations to receive and provide them with the Blueprint for interpolation.

Functions

It's not always the case that your data in the payload is exactly how you need it. So we have a handful of functions you can use to mutate your data so that what is passed into the Business Process is exactly what you want it to be. Data casting happens after function execution and the output of each function is always a string.

1. ${padleft(prefixValue,limit):month} - The padleft function allows adding additional value at the start of the provided month value, limiting its length to the defined length. For example -

Request -
{
   "month" : "${padleft(0,2):month}"
}
Input - 
{
   "month" : 4
}
Result - 
{
   "month" : "04"
}

1. ${pad(suffix,limit):month} - The padleft function allows adding additional value at the end of the provided month value, limiting its length to the defined length. For example -

Request -
{
   "month" : "${padleft(0,2):month}"
}
Input - 
{
   "month" : 1
}
Result - 
{
   "month" : "10"
}

1. ${substring(from,to):name} - The substring function enables selecting a specific segment from a given value by defining start and end points within the string. For example -

Request -
{
   "name" : "${substring(0,4):name}"
}
Input - 
{
   "name" : "Authvia"
}
Result - 
{
   "name" : "Auth"
}

1. ${replace(toBeReplace, replaceWith):value} - The replace function allows you to replace a specific segment of a given value by specifying the segment to be replaced and the value to replace it with. For example -

Request -
{
   "name" : "${replace(n,T):value}"
}
Input - 
{
   "value" : "nest"
}
Result - 
{
   "name" : "Test"
}

1. ${minus(subtractValue):amount} - The minus function allows you to subtract a specific value from a given input. For example -

Request -
{
   "value" : "${minus(4):amount}"
}
Input - 
{
   "amount" : 10
}
Result - 
{
   "value" : "6"
}

1. ${uppercase:credentials} - The uppercase function allows you to convert a given value to a UPPERCASE format. For example -

Request -
{
   "value" : "${minus(4):name}"
}
Input - 
{
   "name" : "Authvia"
}
Result - 
{
   "value" : "AUTHVIA"
}