Skip to main content

"runTransform"

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

Things to know

  • 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 example

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

Run a locally defined transform request example

{
  "api": "hub",
  "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 example

{
  "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 example

"params"
The "params" property is an object that contains an action's parameters. Each action defines its own required and optional properties.
Property summary
Table 1. "params" property summaries
Property
Description
Default
Type
Limits (inclusive)
"fieldData"
provides values that would normally be provided by the fields of a record in an integration table
Required - No default value
array of objects
"format"
specifies the format of data embedded in a string so it can be converted properly into another form
""
string
"outputFields"
contains one element which is the name of the field that will receive the JSON generated by the transform
Required - No default value
array
"transformActions
contains "transformAction" objects
[]
array of objects
"transformName"
contains the name of a transform process
Note
Cannot be one of the FairCom-provided transform names.
""
string
Minimum length: 1
Maximum length: 64


"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.
Things to know:
  • 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."
Property summary
Table 2. "fieldData" property summaries
Property
Description
Default
Type
Limits (inclusive)
"binaryFormat"
determines how binary values are returned
"base64"
string
"base64"
"hex"
"name"
contains the name of a field
Required - No default value
string
"type"
contains the type of the field
"json"
string
"value"
contains the value of a field
Required - No default value
integer
string
object


"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.
Things to know:
  • 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.
Property sumamry
Table 3. "outputFields" property summaries
Property
Description
Default
Type
Limits (inclusive)
"name"
contains the name of a field
Required - No default value
string
"type"
contains the type of the field
"json"
string


"transformActions"
The "transformActions" property is an optional array of "transformAction" objects. It defaults to an empty array.
Table 4. "transformAction" property summaries
Property
Description
Default
Type
Limits (inclusive)
"inputFields"
contains 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
"outputFields"
contains one element which is the name of the field that will receive the JSON generated by the transform
Required - No default value
array
"transformActionName"
Contains the name of the transform action.  For example — "siemensUdtPayloadToJSON", "jsonPropertiesToTableFields", "tableFieldsToJson", "jsonToDifferentTableFields"
Required - No default value
string
Minimum length: 1
Maximum length: 64
"transformParams"
contains a unique set of parameters that configure its transformation process
Note
It may be an empty object or contain one or more properties needed by the "transformAction".
Required - No default value
object
Minimum length: 0
Maximum length: 65500
"transformService"
specifies the service that contains the transform
""
string
Any previously defined name of a transform service.


"transformName"
The "transformName" property is a required string that contains the unique name of a transform process, which consists of one or more transform steps.
Things to know:
  • 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"