API reference

Enable and disable the UDT-to-JSON service

Navigate to the config folder.
Open the services.json configuration file.
Enable or disable the UDT-to-JSON service by editing the "siemensUDT2JSON" block of the "transformServices" object.
1. Set the "enabled" property to true to enable the UDT-to-JSON service.
  OR set the "enabled" property to false to disable the UDT-to-JSON service.
```
{
	"serviceName": "siemensUDTServiceopcua",
	"serviceLibrary": "siemensudtservice.dllopcservice.dll",
	"enabled": true
}
```
2. Save any changes.
3. Restart the server for the changes to take effect.

Request examples

Note

The listed examples require a UDT schema that matches the serialized data structure that your PLC is publishing to an MQTT topic, see Obtain and convert the UDT schema.

For a list and detailed description of the specific properties in the "createTransform" action, see createTransform.

The Siemens UDT-to-JSON transform does not have "target" parameters because it writes to the same integration table that it reads from. The table is specified by the "configureTopic", "alterInput", or "alterIntegrationTable" actions which invoke this transformation.

The Seimens UDT-to-JSON transform reads binary data from one field (column) and writes JSON data to a different field of that table. Both the "inputFields" and "outputFields" arrays should contain exactly one field each, and those two fields should be different from each other.

Minimal request example

{
    "authToken": "ReplaceWithValidToken",
    "api": "hub",
    "apiVersion": "1.0",
    "action": "createTransform",
    "params": {
        "transformName": "PLCData_transform",
        "transformActions": [
            {
                "transformService": "siemensUDT2JSON",
                "transformActionName": "siemensUdtPayloadToJSON",
                "inputFields": [
                    "source_payload"
                ],
                "outputFields": [
                    "aValidFieldName"
                ],
                "transformParams": {
                    "schema": "ReplaceWithConvertedUDTSchema",
                    "rootTypeName": "ReplaceWithRootName"
                }
            }
        ]
    }
}

Maximal request example

{
    "authToken": "ReplaceWithValidToken",
    "api": "hub",
    "apiVersion": "1.0",
    "action": "createTransform",
    "params": {
        "transformName": "PLCData_transform",
        "transformActions": [
            {
                "transformService": "siemensUDT2JSON",
                "transformActionName": "siemensUdtPayloadToJSON",
                "inputFields": [
                    "source_payload"
                ],
                "outputFields": [
                    "temperature"
                ],
                "transformParams": {
                    "schema": "ReplaceWithConvertedUDTSchema",
                    "udtDebugTracing": false,
                    "rootTypeName": "ReplaceWithRootName"
                }
            }
        ]
    }
}

Response examples

Minimal response example

{
    "result": {},
    "requestId": "00000007",
    "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.

Property summary

Table 1. "params" property summaries

Property

Description

Default

Type

Limits

"transformActions"

contains "transformAction" objects

Required - No default value

array of objects

"transformName"

contains the name of a transform process

Required - No default value

string

Minimum length: 1

Maximum length: 64

`"transformActions"`

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

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

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

Table 3. "transformParams" property summaries

Property

Description

Default

Type

Limits (inclusive)

"mapOfPropertiesToFields"

contains "mapOfPropertyToField" objects

[ ]

array

"rootTypeName"

contains the name of data type that is the schema root

Required - No default value

string

"schema"

adds new fields to the table and specifies their properties

Required - No default value

array of objects

"targetDatabaseName"

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

"ctreeSQL"

string

"targetTableName"

contains 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

"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

"mapOfPropertiesToFields"

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

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

Table 4. "mapOfPropertiesToFields" Property Summaries

Property

Description

Default

Type

Limits (inclusive)

"name"

contains the name of a field

Required - No default value

string

Minimum length: 1

Maximum length: 64

"propertyPath"

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

string

Minimum length: 0

Maximum length: 256

"type"

defines the JSON type of the property

Required - No default value

string

See Data types