Skip to main content

UDT to JSON API reference

API reference for Siemens UDT to JSON transform method

Enable and disable the UDT-to-JSON service

  1. Navigate to the config folder.

  2. Open the services.json configuration file.

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

{
    "api": "hub",
    "apiVersion": "1.0",
    "action": "createTransform",
    "params": {
        "transformName": "PlcData_transform",
        "transformActions": [
            {
                "transformService": "siemensUdt2Json",
                "transformStepMethod": "siemensUdtPayloadToJson",
                "inputFields": [
                    "source_payload"
                ],
                "outputFields": [
                    "aValidFieldName"
                ],
                "transformParams": {
                    "schema": "ReplaceWithConvertedUdtSchema",
                    "rootTypeName": "ReplaceWithRootName"
                }
            }
        ]
    },
    "authToken": "replaceWithAuthTokenFromCreateSession"
}

Maximal request

{
    "api": "hub",
    "apiVersion": "1.0",
    "action": "createTransform",
    "params": {
        "transformName": "PlcData_transform",
        "transformActions": [
            {
                "transformService": "siemensUdt2Json",
                "transformStepMethod": "siemensUdtPayloadToJson",
                "inputFields": [
                    "source_payload"
                ],
                "outputFields": [
                    "temperature"
                ],
                "transformParams": {
                    "schema": "ReplaceWithConvertedUdtSchema",
                    "udtDebugTracing": false,
                    "rootTypeName": "ReplaceWithRootName"
                }
            }
        ]
    },
    "authToken": "replaceWithAuthTokenFromCreateSession"
}

Response examples

Minimal response

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

API reference for Siemens UDT to JSON transform method

API referenceJSON hub APIJSON transformsiemens udtudt to json transform

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

Property summary

Table 1. "params" property summaries

Property

Description

Default

Type

Limits

transformActions

specifies "transformAction" objects

Required - No default value

array of objects

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

transformName

specifies the name of a transform process. The name cannot be one of the FairCom-provided transform names

Required - No default value

string

1 to 64 bytes



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