JSON Templating

JSON Templating engine is commonly used to configure many of our extensions.

JSON Templating Syntax

The basic and most commonly used syntax is for getting values from the annotation object:

{
  "some_field": "@{schema_id_of_datapoint}"
}

See also the $DATAPOINT_VALUE$ section below for more verbose syntax.

JSON Templating Operators

Operators are a special syntax that can be used to perform various complex operations when working with JSON.

$DATAPOINT_MAPPING$

Returns rendered template specified in mapping for certain value of schema_id.

Example

{
  "_ns_type": {
    "$DATAPOINT_MAPPING$": {
      "schema_id": "document_type",
      "mapping": {
        "tax_credit": "VendorCredit",
        "tax_invoice": "VendorBill"
      },
      "fallback_mapping": "Vendor" // optional
    }
  }
}

This template will return the following for document_type with value tax_credit:

{ "_ns_type": "VendorCredit" }

Similarly, this template will return the following for tax_invoice value:

{ "_ns_type": "VendorBill" }

Finally, the template will return the _ns_type of Vendor if no other value is found. This value can be omitted which will default to null.

Available configuration options

$DATAPOINT_VALUE$

$DATAPOINT_VALUE$ is a more verbose syntax for @{schema_id}. In other words, the following examples are identical:

{
  "externalId": "@{ns_external_id_generated}"
}

Identical to:

{
  "externalId": {
    "$DATAPOINT_VALUE$": {
      "schema_id": "ns_external_id_generated",
      "value_type": "string"
    }
  }
}

While the latter might seem unnecessary, it is needed when we want to cast the value to a certain type. For example:

{
  "tranDate": {
    "$DATAPOINT_VALUE$": {
      "schema_id": "date_issue",
      "value_type": "iso_datetime"
    }
  }
}

Available configuration options

$FOR_EACH_SCHEMA_ID$

Iterates over multiline schema IDs, typically line items.

Example

{
  "items": {
    "$FOR_EACH_SCHEMA_ID$": {
      "schema_id": "line_item",
      "mapping": {
        "_ns_type": "VendorBillItem",
        "quantity": "@{item_quantity}",
        "description": "@{item_description}"
      }
    }
  }
}

Will render:

{
  "items": [
    {
      "_ns_type": "VendorBillItem",
      "quantity": "1",
      "description": "Some description 1"
    },
    {
      "_ns_type": "VendorBillItem",
      "quantity": "2",
      "description": "Some description 2"
    }
    // …
  ]
}

Inside the for-loop block, you can access a special variables (schema_loop):

• schema_loop.index for current iteration of the loop indexed from 1

• schema_loop.index0 for current iteration of the loop indexed from 0

Available configuration options

$IF_DATAPOINT_VALUE$

Renders the provided mapping template if the value of the given schema_id is equal to value. Otherwise, the whole parent key is skipped.

Note that if element with given schema_id is not found or multiple with the same schema_id is found an exception is raised.

Example

{
  "Other_Field": 123,
  "Company_Reference": {
    "$IF_DATAPOINT_VALUE": {
      "schema_id": "company_match",
      "value": "my_company",
      "mapping": {
        "field_1": 456,
        "field_2": 789
      }
    }
  }
}

If company_match has value my_company the output will be:

{
  "Other_Field": 123,
  "Company_Reference": {
    "field_1": 456,
    "field_2": 789
  }
}

If company_match has value that is different from my_company the output will be:

{
  "Other_Field": 123
}

Available configuration options

$IF_SCHEMA_ID$

Similar to $FOR_EACH_SCHEMA_ID$ operation: it checks the existence of schema_id, and it either outputs mapping if the schema_id points to a non-empty value or fallback_mapping otherwise.

Note that if you don't specify the fallback_mapping, it will skip the whole parent key!

Example

{
  "dueDate": {
    "$IF_SCHEMA_ID$": {
      "schema_id": "date_due",
      "mapping": {
        "$DATAPOINT_VALUE$": {
          "schema_id": "date_due",
          "value_type": "iso_datetime"
        }
      }
    }
  }
}

Available configuration options