`"alterTransform"`

The JSON Edge API `"alterTransform"` action modifies a transform in FairCom MQ and FairCom Edge

Abstract

The "alterTransform" action alters, changes, modifies, updates, or configures an existing transform in FairCom Edge and FairCom MQ. A transform is a process that transforms incoming data before it is inserted as a record in an integration table.

The "alterTransform" action alters an existing transform in FairCom Edge and FairCom MQ. A transform is a process that transforms incoming data before it is inserted as a record in an integration table. Before you can change a transform, you must first create it using "createTransform".

Request examples

Minimal request example

{
    "api": "hub",
    "apiVersion": "1.0",
    "requestId": "00000022",
    "authToken": "anAuthorizationTokenFromTheServer ",
    "action": "alterTransform",
    "params": {
        "transformName": "opc_transform2",
        "newTransformName": "opc_transform8",
        "transformActions": []
    }
}

Maximal request example

{
    "api": "hub",
    "apiVersion": "1.0",
    "requestId": "00000016",
    "authToken": "anAuthorizationTokenFromTheServer ",
    "action": "alterTransform",
    "params": {
        "transformName": "transform_opc2",
        "newTransformName": "transform_opc5",
        "transformActions": [
        {
                "inputFields": [
                    "source_payload"
                ],
                "transformActionName": "jsonToTableFields",
                "transformParams": {
                    "targetDatabaseName": "ctreeSQL",
                    "targetTableName": "opc_sensor2",
                    "mapOfPropertiesToFields": [
                        {
                            "propertyPath": "temperature",
                            "name": "temperature",
                            "type": "REAL"
                        },
                        {
                            "propertyPath": "humidity",
                            "name": "humidity",
                            "type": "REAL"
                        },
                        {
                            "propertyPath": "pressure",
                            "name": "pressure",
                            "type": "REAL"
                        },
                        {
                            "propertyPath": "quality",
                            "name": "quality",
                            "type": "REAL"
                        }
                    ]
                }
            }
        ]
    }
}

Response examples

Minimal response example

{
    "result": {},
    "requestId": "00000022",
    "errorCode": 0,
    "errorMessage": ""
}

Maximal response example

{
    "result": {},
    "requestId": "00000016",
    "errorCode": 0,
    "errorMessage": ""
}

`"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)

metadata

exists primarily for the user interface to find integration information

{}

object

May contain any number and type of user-defined properties

newTransformName

specifies the name of a transform

Note

Cannot be one of the FairCom-provided transform names.

""

string

0 to 256 bytes

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

Note

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 ta4get 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

Note

Cannot be one of the FairCom-provided transform names.

""

string

1 to 64 bytes

`"metadata"`

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.

Things to know:

It contains a flexible set of properties.
It typically contains tags and description properties.

Example

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

`"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.

Things to know:

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 the input field of another.

"outputFields"

The "outputFields" property is a required array containing one or more of the fields in the integration table. The transform action writes its output to these fields.

Things to know:

Typically a transform action only needs one output field.
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 field that is 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.
It is an error for the "source_payload" field to be an output field because it always contains the payload from the input service or MQTT topic.
It is also an error for multiple transform actions to write to the same output field because they would overwrite each other’s results.
When a transform has multiple transform actions, you typically daisy chain the output field of one transform action to be the input field of another.

"transformParams"

The "transformParams" property is a required object that can be an empty object or contain one or more properties needed by the "transformAction"

"mapOfPropertiesToFields"

The "mapOfPropertiesToFields" property is an optional array of "mapOfPropertyToField" objects. It defaults to an empty array.

        "mapOfPropertiesToFields": 
        [
          {
            "propertyPath": "",
            "type": "",
            "name": ""
          }
        ],

`"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.

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"

"alterTransform"

The JSON Edge API "alterTransform" action modifies a transform in FairCom MQ and FairCom Edge

Request examples

Minimal request example

Maximal request example

Response examples

Minimal response example

Maximal response example

"params"

Properties summary

Note

Note

Note

"metadata"

Example

"transformActions"

"transformName"

`"alterTransform"`

The JSON Edge API `"alterTransform"` action modifies a transform in FairCom MQ and FairCom Edge

`"params"`

`"metadata"`

`"transformActions"`

`"transformName"`