`"runTransform"`

JSON transform `"runTransform"` action runs a transform and returns the transformed data

The "runTransform" action runs a transform and returns the transformed data.

Essential information

The "runTransform" action can run a previously created transform or run a transform defined locally in the "transformActions" property.
This action runs a transform and returns the result. Running a transform on demand is useful for quickly testing a transform process.
The transform may be a previously saved transform or a new transform specified in the request. The request specifies the transform's source data using the "fieldData" property and the response puts the resulting data in the "fieldData" property.
The transform process follows the same rules that it uses when it modifies the transform fields in an integration table. Thus, each step of a transform process may read any property in "fieldData" and the response adds one JSON property to the "fieldData" property for each output field that it creates.
The "runTransform" action sends the "fieldData" property to the specified transform process as if it were a row in an integration table. The transform process transforms the data and returns the results in a "fieldData" property. In the request, the "fieldData" property may contain the value for any field in an integration table, such as "id", "source_payload", "create_ts", "error", and "log". If the request does not include a value for a field that the transform uses as input, the transform uses a null value for that field. The fields in a request typically include the "source_payload" field, other built-in fields, and may also include user-defined fields. The value of each field included in the request cannot be changed by the transform.
In the response, the "fieldData" property contains all additional fields and values created by the transform. Following these fields, it also contains all the fields in the request, which makes it easy to see the complete input and output of a transform. The response always contains the "error" and "log" fields because this is where transform problems are recorded.
A transform requires specific fields to contain specific types of data. If the data in a field does not match its requirements, the "runTransform" action returns an error.
The "fieldValue" property for each field is encoded using the "binaryFormat" setting defined in the request. The default setting for "binaryFormat" is the value of "defaultBinaryFormat". When you want to use a different encoding for a field, include a "binaryFormat" property in the "field" object in "fieldData". You can include "field" objects in "fieldData" solely for the purpose of defining their binary format in the response.

Request examples

Run a previously created transform request

{
  "api": "transform",
  "action": "runTransform",
  "authToken": "replaceWithAuthTokenFromCreateSession",
  "params": {
    "transformName": "FieldToField",
    "fieldData": [
      {
        "name": "source_payload",
        "type": "json",
        "value": {
          "example": "jsonObject"
        }
      }
    ]
  }
}

Run a locally defined transform request

{
  "api": "transform",
  "action": "runTransform",
  "authToken": "replaceWithAuthTokenFromCreateSession",
  "params": {
    "fieldData": [
      {
        "name": "t1",
        "value": {
          "example": "jsonObject"
        },
        "type": "json"
      },
      {
        "name": "t2",
        "value": "binaryValueEncodedUsingBinaryFormatSpecifiedBelow",
        "type": "lvarbinary",
        "format": null
      },
      {
        "name": "t3",
        "value": "string value",
        "type": "lvarchar"
      },
      {
        "name": "t4",
        "value": -1.23,
        "type": "number"
      },
      {
        "name": "t5",
        "value": -53,
        "type": "integer"
      },
      {
        "name": "t6",
        "value": "2023-07-11T10:27:03",
        "type": "timestamp"
      }
    ],
    "outputFields": [
      {
        "name": "t1",
        "type": "json"
      },
      {
        "name": "t2",
        "type": "integer"
      }
    ],
    "transformActions": [
      {
        "inputFields": [
          "source_payload"
        ],
        "outputFields": [
          "t1"
        ],
        "transformActionName": "tableFieldsToJson",
        "transformService": "siemensUDT2JSON",
        "transformServiceVersion": "1.0",
        "transformParams": {}
      }
    ]
  },
  "apiVersion": "1.0",
  "requestId": "2",
  "debug": "max"
}

Response examples

Run a previously created transform response

{
  "requestId": "clientRequestId",

  "result": 
  {
    "fieldData": 
    [
      {
        "name": "source_payload", 
        "value": { "example": "jsonObject" },
        "type": "json"
      },
      {
        "name": "id", 
        "value": 1,
        "type": "bigint"
      },
      {
        "name": "create_ts", 
        "value": "2023-07-11T10:27:03",
        "type": "timestamp"
      },
      {
        "name": "t1", 
        "value": 
        [
          { 
            "propertyName": "example",
            "propertyValue": "jsonObject"
          }
        ],
        "type": "json"
      }
    ]
  },
  "errorCode": 0,
  "errorMessage": "",
  "debugInfo": {}
}

Run a locally defined transform response

Use the runTransform JSON API action to run a transform and return the transformed data

JSON transform APIAPI actionsjsonActiontransform actionsrun transformrunTransform

`"params"`

The "params" property is an object that contains an action's parameters. Each action defines its own required and optional properties.

Properties summary

Table 1. "params" properties summary

Property

Description

Default

Type

Limits (inclusive)

fieldData

specifies values that would normally be provided by the fields of a record in an integration table

Required - No default value

array of objects

fieldData

.binaryFormat

specifies how binary values are returned

"base64"

string

"base64"

"hex"

fieldData

.name

specifies the name of a field

Required - No default value

string

fieldData

.type

Specifies the type of the field

"json"

string

fieldData

.value

specifies the value of a field

Required - No default value

integer

object

string

format

specifies the format of data embedded in a string so it can be converted properly into another form

""

string

outputFields

specifies one element which is the name of the field that will receive the JSON generated by the transform

Required - No default value

array

outputFields

.name

specifies the name of a field

Required - No default value

string

outputFields

.type

Specifies the type of the field

"json"

string

transformActions

specifies "transformAction" objects

[]

array of objects

transformActions

.inputFields

specifies one or more of the fields in the integration table where the value of each of these fields is sent to the transform action as its primary input

Required - No default value

array

transformActions

.outputFields

specifies one element which is the name of the field that will receive the JSON generated by the transform

Required - No default value

array

transformActions

.transformActionName

specifies the name of the transform action. For example -- "siemensUdtPayloadToJSON", "jsonPropertiesToTableFields", "tableFieldsToJson", "jsonToDifferentTableFields"

Required - No default value

string

1 to 64 bytes

transformActions

.transformParams

specifies a unique set of parameters that configure its transformation process. It may be an empty object or contain one or more properties needed by the "transformAction"

Required - No default value

object

0 to 65,500 bytes

transformActions

.transformParams

.mapOfPropertiesToFields

specifies "mapOfPropertyToField" objects

[]

array

transformActions

.transformParams

.mapOfPropertiesToFields

.name

specifies the name of a field

Required - No default value

string

1 to 64 bytes

transformActions

.transformParams

.mapOfPropertiesToFields

.propertyPath

specifies the path in the JSON document where the property is located.

string

0 to 256 bytes

transformActions

.transformParams

.mapOfPropertiesToFields

.type

specifies the JSON type of the property

Required - No default value

string

See Data types

transformActions

.transformParams

.rootTypeName

specifies the name of data type that is the schema root

Required - No default value

string

transformActions

.transformParams

.schema

adds new fields to the table and specifies their properties

Required - No default value

array of objects

transformActions

.transformParams

.targetDatabaseName

specifies the name of the database where the table will be created

"ctreeSQL"

string

transformActions

.transformParams

.targetTableName

specifies the name of the table where c-tree will store the data that it extracts for incoming data messages

Defaults to the topic name with underscores removed

string

transformActions

.transformParams

.udtDebugTracing

checks for any inconsistencies when true. If some are found while extracting the information, a new object named "errorList" is added to the target payload with a list of inconsistency errors that were found

false

Boolean

true

false

transformActions

.transformService

specifies the service that contains the transform

""

string

Any previously defined name of a transform service

transformName

specifies the name of a transform process. The name cannot be one of the FairCom-provided transform names

""

string

1 to 64 bytes

`"fieldData"`

The "fieldData" array is a required property that provides values that would normally be provided by the fields of a record in an integration table.

Essential information

The transform process uses the fields in the "fieldData" array and their values as inputs to the transform process.
If a field is required by the transform and is not included in "fieldData", the server returns an error stating, "The transform requires field XXX as an input. You must include it in the "fieldData" property."

"binaryFormat"

The "binaryFormat" property controls how binary values are formatted in the JSON request and JSON response message. The default value is "base64".

Note

Unlike most other response options, the "binaryFormat" property applies to both the request and response. This is special because response options typically apply only to the server’s response.

The "binaryFormat" property may occur inside "params", "responseOptions", and "result".
When "binaryFormat" occurs in "params" it specifies how the sender encodes binary values.
For example, when "binaryFormat" is set to "hex", the FairCom server expects the binary values of fields and keys to be embedded in strings and encoded in hexadecimal format.
When "binaryFormat" occurs in "responseOptions" or "defaultResponseOptions" specifies how the FairCom server should encode binary values in the response.
For example, when "binaryFormat" is set to "hex", the FairCom server embeds binary values in strings and encodes them in hexadecimal format.
When "binaryFormat" occurs in "result" signifies how it has encoded binary values that are embedded in strings.
For example, when "binaryFormat" is set to "base64", the FairCom server has encoded binary values in the response in base64 format.
Possible values include:
- The following are the possible values for each format.
  - "base64"
    When the server reads and writes from a binary field, it represents the binary value as a base64 string.
    Base64 is harder for people to read and convert to binary.
    Base64 creates the smallest payload for the most efficient data transmission in JSON.
    "base64" strings contain the characters 0 - 9 , A - Z, a - z, +, /, and =.
  - "hex"
    When the server reads and writes from a binary field, it represents the binary value as a hexadecimal string.
    Hexadecimal is easier for people to read and convert to binary.
    Hexadecimal creates a 30% larger payload than "base64", which makes it less efficient for data transmission.
    Hexadecimal strings contain the characters 0 - 9 and A - F.
  - "byteArray"
    When the server reads and writes from a binary field, it represents the binary value as an array of bytes.
    An array of bytes is easiest for a program to manipulate.
    An array of bytes creates a larger payload than "base64" and "hex", which makes it less efficient for data transmission.
    An array of bytes returns a JSON array containing one integer number between 0 and 255 for each byte in the binary value:
    "aBinaryField": [ 255, 0, 255 ]

"params" and "responseOptions" as "hex" request example

This example shows how how the "binaryFormat" property can occur in the "params" and "responseOptions" properties and how the "value" property is a string value that contains a hexadecimal encoded binary value. To use these examples, you should first use FairCom's Data Explorer to create the "all_types" table, its indexes, and insert at least one record.

{
  "requestId": "1",
  "authToken": "replaceWithAuthTokenFromCreateSession",
  "api": "db",
  "apiVersion": "1.0",
  "action": "getRecordsStartingAtKey",
  "params": {
    "databaseName": "ctreeSQL",
    "tableName": "all_types",
    "binaryFormat": "hex",
    "indexFilter": {
      "indexName": "fixed_binary_10bytes",
      "operator": "=",
      "indexFields": [
        {
          "fieldName": "fixed_binary_10bytes",
          "value": "FF00FF00000000000000"
        }
      ]
    }
  },
  "responseOptions": {
    "dataFormat": "objects",
    "binaryFormat": "hex"
  }
}

"params" as "base64" & "responseOptions" as "hex" request example

This example shows how the "binaryFormat" property can be set to different values in the "params" and "responseOptions" properties. This allows you to submit binary values in one encoding and retrieve binary values in another encoding.

{
  "requestId": "2",
  "authToken": "replaceWithAuthTokenFromCreateSession",
  "api": "db",
  "apiVersion": "1.0",
  "action": "getRecordsStartingAtKey",
  "params": {
    "databaseName": "ctreeSQL",
    "tableName": "all_types",
    "binaryFormat": "base64",
    "indexFilter": {
      "indexName": "fixed_binary_10bytes",
      "operator": "=",
      "indexFields": [
        {
          "fieldName": "fixed_binary_10bytes",
          "value": "/wD/AAAAAAAAAA=="
        }
      ]
    }
  },
  "responseOptions": {
    "dataFormat": "objects",
    "binaryFormat": "hex"
  }
}

"binaryFormat" in "result" response example

This example shows that the server response always includes a "binaryFormat" property inside the "result" property. It indicates how it encoded binary values in the response. Note that this response has been edited for brevity.

{
    "authToken": "replaceWithAuthTokenFromCreateSession",
    "result": {
        "dataFormat": "objects",
        "binaryFormat": "base64",
        "fields": [],
        "data": [],
        "primaryKeyFields": ["id"],
        "changeIdField": "changeId",
        "moreRecords": false,
        "requestedRecordCount": 20,
        "returnedRecordCount": 4,
        "totalRecordCount": 4
    },
    "requestId": "1",
    "errorCode": 0,
    "errorMessage": ""
}

`"outputFields"`

The "outputFields" property is an optional array of field objects. The transform process uses these fields and their values as inputs to the transform process.

Essential information

Each field object contains the name of a field and its type.
When present, it specifies the field type of one or more output fields.
When omitted, fields created by the transform will have a field type of JSON.
When one or more fields created by a transform are not included in "outputFields", the omitted fields will have a field type of JSON.

`"transformActions"`

The "transformActions" property is an optional array of "transformAction" objects. It defaults to an empty array.

"inputFields"

The "inputFields" property is a required array containing one or more of the fields in the integration table. The FairCom server sends the value of each of these fields to the transform action as its primary input.

Typically a transform action only needs one input field and the most common input field is "source_payload".
When a transform is applied to an integration table, the server automatically adds missing fields to the table. Thus, any field can be the source of a transform. A transform can only put the result of a transform in a field specially created to hold the transform's output value. In other words, a transform's output field cannot be a field that is built into the table or a field that is being used by another transform.
When a transform has multiple transform actions, you typically daisy chain the "output" field of one transform action to be either the input field of another transform or the field that is being written to by another transform.

"mapOfFieldsToProperties"

The "mapOfFieldsToProperties" property is a required array of "mapOfFieldsToProperties" objects. It defaults to an empty array.

        "mapOfFieldsToProperties": 
        [
        {
          "propertyPath": "In1",
          "fieldName": "In1"
        }
        ]

`"transformName"`

The "transformName" property is an optional string that contains the unique name of a transform process, which consists of one or more transform steps.

Essential information

A transform is a process that works like a pipeline where the output of one transformation can become the input for another transformation.
The following actions use the "transformName" property to assign a transform to an integration table:
- "configureTopic"
- "createInput"
- "alterInput"
- "alterIntegrationTable"

"runTransform"

JSON transform "runTransform" action runs a transform and returns the transformed data

Essential information

Request examples

Run a previously created transform request

Run a locally defined transform request

Response examples

Run a previously created transform response

Run a locally defined transform response

Use the runTransform JSON API action to run a transform and return the transformed data

"params"

Properties summary

"fieldData"

Essential information

Note

"outputFields"

Essential information

"transformActions"

"transformName"

Essential information

`"runTransform"`

JSON transform `"runTransform"` action runs a transform and returns the transformed data

`"params"`

`"fieldData"`

`"outputFields"`

`"transformActions"`

`"transformName"`