API Reference
Start typing to search…
  1. Accounts
  2. Blueprints

Value Interpolation and Functions

How you use the values provided to create a Business Process through a Blueprint.

The flexibility of Blueprints lies in its agnosticism to the structure of the payload sent. This page describes the syntax of our dynamic value engine, which enables interpolation, short-circuit evaluation, static values, and data mutation 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.

Given the following declaration ${amount,amountDue,amountToPay} and 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

You can define a static value in quotes, and it will always be true. 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, ${amount:number}, which converts the interpolated value to a number.

Here are some available type formattings -

  • :number - When defined at the end, it converts the resulting value to a number, for example, from "100" to 100.
  • :string - When defined at the end, it converts the resulting value to a string, for example, from 100 to "100".
  • :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

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 in which the amount must be provided as a numeric 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 process 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 what you need. So we have a handful of functions you can use to mutate your data so that what is passed to the Business Process is exactly what you want. Data casting happens after function execution, and the output of each function is always a string.

Pad Left

${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.

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

Pad

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

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

Substring

${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.

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

Replace

${replace(toBeReplaced, 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.

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

Minus

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

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

Uppercase

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

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