Skip to main content

"alterTransform" (JSON Action)

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

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

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

Maximal

{
    "api": "transform",
    "apiVersion": "1.0",
    "requestId": "00000016",
    "action": "alterTransform",
    "params": {
        "transformName": "transform_opc2",
        "newTransformName": "transform_opc5",
        "transformActions": [
        {
                "inputFields": [
                    "source_payload"
                ],
                "transformStepMethod": "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"
                        }
                    ]
                }
            }
        ]
    },
    "authToken": "replaceWithAuthTokenFromCreateSession"
}

Response examples

Minimal

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

Maximal

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

Use the alterTransform JSON API action to alter a transform in FairCom Edge and MQ

JSON transform APIAPI actionsJSON Actiontransform actionsalter transformalterTransform

"params"

The "params" property is an object that contains an action's parameters. Each action defines its own required and optional properties. See System limits for a comprehensive look at property requirements and limitations.

Table 1. "params" property summaries

Property

Description

Default

Type

Limits (inclusive)

metadata

(optional) exists primarily for the user interface to find integration information

{}

object

May contain any number and type of user-defined properties

newTransformName

(optional) specifies the name of a transform. The name cannot be one of the FairCom-provided transform names

""

string

0 to 256 bytes

transformActions

(optional) 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
.transformService

(optional) specifies the name of the transform service

Required when "transformStepMethod" is "javascript"; otherwise, it is optional with no default value

string

"javascript"
"siemensUdtPayloadToJson"
"v8TransformService"
transformActions
.transformStepMethod

specifies the name of the transform action

Required - No default value

string

"javascript"
"jsonToTableFields"
"tableFieldsToJson"
"jsonToDifferentTableFields"
"siemensUdtPayloadToJson"
transformActions
.transformStepName

(optional) allows the user to assign a name to each transform step

""

string

0 to 250 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

(optional) 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

(optional) 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

(optional) specifies the name of the database where the table will be created

"ctreeSQL"

string

transformActions
.transformParams
.targetTableName

(optional) 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

(optional) 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

(optional) specifies the service that contains the transform

""

string

Any previously defined name of a transform service

transformName

(optional) specifies the name of a transform process you have created. See the "createTransform" and "alterTransform" actions

""

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.

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

Note

An action and a step in this context are synonymous.

"transformActions"."inputFields"

"transformActions"."outputFields"

"transformActions"."transformParams"."mapOfPropertiesToFields"

"transformActions"."transformParams"."mapOfPropertiesToFields"."propertyPath"

"transformActions"."transformService"

The "transformService" property is an optional string that specifies the name of the transform service.

Note

If the "transformStepMethod" property is set to "javascript", the "transformService" property must be set to "v8TransformService".

"transformActions"."transformStepMethod"

The "transformStepMethod" property is a required string that specifies the type of transform, such as the "javascript" transform method that runs JavaScript to change the table's data or the "jsonToTableFields" transform method that extracts values from properties in a JSON field and stores them in other fields.

Note

The "transformStepMethod" property replaces the deprecated "transformActionName" property.

The value of the "transformStepMethod" affects the value of the "transformService" property. The following table defines the possible values of the "transformService" property when combined with the "transformStepMethod". Notice that some transform step methods are built into the server and do not require you to specify the "transformService".

"transformStepMethod" value

"transformService" value

Definition

"jsonToTableFields"

null or omitted

"tableFieldsToJson"

null or omitted

"jsonToDifferentTableFields"

null or omitted

"javascript"

"v8TransformService"

The "javascript" transform method runs JavaScript code each time a record is inserted into an Integration table. The code can read the value of any field and write values to any field except the built-in fields, such as source_payload. See this tutorial.

"siemensUdtPayloadToJson"

"siemensUdtPayloadToJson"

Note

If the "transformStepMethod" property is set to "javascript", the "transformService" property must be set to "v8TransformService".

"transformActions"."transformStepName"

The "transformStepName" property is an optional string that allows the user to assign a name to each transform step.

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

The value of "transformName" must be the name of a transform process you created. It cannot be the name of a FairCom-provided transform method.

You must create a transform before you can assign it to an integration table. See the "createTransform" and "alterTransform" actions.

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

    • "createIntegrationTable"

    • "alterIntegrationTable"

FairCom APIs typically provide an action to alter an existing item. An "alter" action alters, changes, modifies, updates, and configures an item that was previously created. It returns an error if the item does not exist. For example, you can alter a table in a database, and alter inputs, outputs, and transforms in FairCom Edge. The term "alter" comes from SQL where it is used to modify the properties of a table.

Some FairCom APIs have actions that begin with the term "configure". A "configure" action also alters, changes, modifies, updates, upserts, or configures an existing item. Unlike "alter", "configure" creates an item if it does not already exist. For example, you can configure an MQTT topic and connections to other brokers. If the specified topic or broker connection name does not already exist, the broker creates it.

JavaScript Object Notation (JSON) is a simple format for representing data. It requires very little markup and is flexible enough to represent the majority of data structures. It is self-describing, which makes it ideal for schemaless applications and search. It can optionally be paired with a schema to define an expected structure.