Define the Data Transformation Schemas

The Synchronization tab should be used in order to convert a JSON object from the  third party system to inteworks.cloud JSON object and vice versa. Each object must contain a brief description, the module type that will be synced and the push or pull action. Push is for sending data to the third party system and Pull for receiving data.

In addition pre and/or post synchronization actions can be enabled for each synchronization action. These actions give the ability to the developer to retrieve data (i.e Synchronization token) from the external API system or sync a different module  prior or after the actual synchronization. The data retrieved from an external API system can be set as a Header or as a property in the module that will be synced.

Transformation example for Invoice module
{
  "synchronization": {
     "Invoice": {
        "description": "Synchronize Invoices with 3rd party system",
        "module": "Invoices",
        "push": {
           "create": "/SalesInvoice/post",
           "update": "/SalesInvoice(No='{IntegrationId}',Document_Type='Invoice')/put",
           "preSynchronizationAction": {
                    "ETag": {
                       "type": "ApiPath",
                       "path": "/SalesInvoice(No='{IntegrationId}',Document_Type='Invoice')/get",
                       "schema": {
                             "type": "String",
                             "ETag": "ETag"
                         },
                        "in": "Body"
                     },
                     "HeaderETag": {
                        "type": "ApiPath",
                        "path": "/SalesInvoice(No='{IntegrationId}',Document_Type='Invoice')/get",
                        "schema": {
                             "type": "String",
                              "header": "If-Match",
                               "headerValue": "@odata.etag"
                       },
                       "in": "Header"
                     }
           },
           "postSynchronizationAction": {
                  "InvoiceItems": {
                      "type": "ApiSynchronization",
                      "path": "InvoiceItems",
                      "schema": {
                            "type": "String",
                            "ETag": "ETag"
                      },
                      "in": "Body"
                   }
           },
          "schemasTransformer": { 
                  "invoiceRequest":  {   
                         "Document_Type": "Invoice",
                         "Sell_to_Customer_Name": "#valueof($.account.name)",
                         "Sell_to_Address": "#valueof($.account.addresses[?(@.isBilling==true)].address1)",
                         "Sell_to_Address_2": "#valueof($.account.addresses[?(@.isBilling==true)].address2)",
                         "Sell_to_Post_Code": "#valueof($.account.addresses[?(@.isBilling==true)].postCode)",
                         "Sell_to_City": "#valueof($.account.addresses[?(@.isBilling==true)].city)",
                         "Document_Date": "#valueof($.createdAt)",
                         "Due_Date": "#valueof($.dueDate)"
                   },
                  "invoiceUpdateRequest":  {   
                         "ETag": "#valueof($.eTag)",
                         "Document_Type": "Invoice",
                         "Sell_to_Customer_Name": "#valueof($.account.name)",
                         "Sell_to_Address": "#valueof($.account.addresses[?(@.isBilling==true)].address1)",
                         "Sell_to_Address_2": "#valueof($.account.addresses[?(@.isBilling==true)].address2)",
                         "Sell_to_Post_Code": "#valueof($.account.addresses[?(@.isBilling==true)].postCode)",
                         "Sell_to_City": "#valueof($.account.addresses[?(@.isBilling==true)].city)",
                         "Document_Date": "#valueof($.createdAt)",
                         "Due_Date": "#valueof($.dueDate)"
                   },
     }
  }
}

Push and Pull Methods


Push can have 3 paths: createupdate and delete and Pull can have 2 paths: batchRead and read. For each path, the API URL and the verb must be specified  as string with the format "ApiUrl/verb". A Push or Pull method includes paths, the transformation for each path, Pre/Post synchronization actions and/or statements.

SchemasTransformer


SchemasTransformer should contain one transformation for each path. If the schema will be for request, the name should be {schema}Request. If the schema will be for the response the name should be {schema}Response.

This example is using a simple transformation to convert a BSS invoice to a 3party system invoice.

Pre/Post Synchronization actions 


Pre/Post Synchronization actions are defined as an object "preSynchronizationAction"/ "postSynchronizationAction" and can have the following properties:

  • Type: The type of action (Valid values: ApiPath, ApiSynchronization)
  • Path: The URL path for the defined action (URL or the name of transformation object that will be synced)
  • Schema
    • If schema is used to store a value in header then type, header and headerValue are needed.
    • If schema is used to store a value in body then type and variable name are needed.
  • In: where the value should be saved. (Valid values: Body, Header)

Below, is an example of preSynchronizationAction

Statements


For each push/pull event several statements can be enabled. Statements are executed prior to Synchronization for push event and after Synchronization for pull event.

Statements have the following properties:

  • Description: A brief description of the statement
  • Priority: Priority of the statement (Valid values: Lowest, Low, Normal, High, Highest)
  • Conditions: An object that contain all the rules of the statement
  • OnFailure: The action what will be triggered if conditions inside statement are false (Valid values: StopProcess)
  • OnSuccess: The action what will be triggered if conditions inside statement are true (Valid values: StopProcess)

Conditions / Rules


These elements consist from the following properties:

  • Type: The type of condition/rule. (Valid values: Combination, Condition)
  • LogicalExpression *Required when Type is Combination. The logical expression check between the rules (Valid values: OR, AND)
  • Rules: Consist from an array of rules
  • Variable *Required when Type is Condition. The Variable that will be checked against the given value
  • Operator *Required when Type is Condition. The type of operator that will be used for the condition (Valid values: NotEqual, Equal, LessThan, LessOrEqualThan, GreaterThan, GreaterOrEqualThan, Like, StartsWith, EndsWith)
  • Value *Required when Type is Condition. The value that will determine the result of the condition

Example of statement for Account Type and another Combination of rules.



You can proceed by learning how to create an integration instance Next