Skip to main content

"createTransform"

JSON transform "createTransform" action creates a new transform and saves it by name for reuse in MQTT topics and inputs in FairCom MQ and FairCom Edge

The "createTransform" action creates a transform and saves it by name for reuse in MQTT topics and inputs.

  • A transform is a process that runs when a record is inserted into an integration table. It allows you to modify the record's data and write the transformed data into user-defined fields in the table. A transform process cannot write to an integration table's built-in fields.

  • You must give each transform a unique name to apply to multiple Integration tables. You can only use a transform with integration tables; it does not work on standard tables.

  • A transform process contains one or more transform steps. Each transform step runs a transform method that modifies data from source fields and stores the result in destination fields.

  • FairCom provides several transform methods in its built-in transformation plugins. You can create additional transform methods by supplying your plugins using the C programming language.

  • You can connect the inputs and outputs of transform steps in any way you desire. The output of one transform step can be the input to another. Once a transform step writes to a field, no other transform step can do so. This ensures transform steps do not overwrite the results of other transform steps, which is essential for auditing and troubleshooting.

  • Each time a record is inserted into an integration table, the server runs each transform step in the "transformActions" property in order from the start of the list to the end.

  • When you apply a transform to an Integration table, the server automatically adds missing output fields. This ensures a transform process has all the fields it needs.

  • When you create or alter a transform process, the server returns an error when a step in a transform process attempts to write its output to the same field that a previous step wrote to.

  • For each transform step, you must set the "inputFields" property to either the "source_payload" or a field that is the output of a previous transform step.

  • Each time you configure an input service, an MQTT topic, or an integration table, you can change the "transformName" property, which changes the transform process for the underlying integration table.

  • Because you can assign the same transform process to many integration tables, be careful when you change a transform process because the change applies to each integration table where it is set. Similarly, the change may affect all output services using the integration table because a transform process writes to an integration table's fields, which output services use to deliver data.

Request examples

Minimal request

{
    "api": "transform",
    "authToken": "aValidAuthToken",
    "action": "createTransform",
    "params": {
        "transformName": "MinWorkingExample",
        "transformActions": [
            {
                "inputFields": [
                    "aValidFieldName"
                ],
                "outputFields": [
                    "aValidFieldName"
                    ],
                "transformActionName": "tableFieldsToJson",
                "transformParams": {
                }
            }
        ]
    }
}
{
    "result": {},
    "requestId": "00000007",
    "errorCode": 0,
    "errorMessage": ""
}

Use the createTransform JSON API action to creates a new transform

JSON transform APIAPI actionsjsonActiontransform actionscreate transformcreateTransform

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)

metadata

exists primarily for the user interface to find integration information

{}

object

May contain any number and type of user-defined properties

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

contains "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 the 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



The "metadata" property is an optional JSON object. It exists primarily for the user interface to find integration information. By default, it is an empty JSON object.

  • It contains a flexible set of properties.

  • It typically contains tags and description properties.

Example

{
  "description": "",
  "tags": [""],
  "yourOwnProperties": "usage, purpose, notes, location, etc.",
}

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

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

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