createOutput

JSON hub "createOutput" action creates a new FairCom Edge integration

The "createOutput" action creates a new integration.

An integration connects data in the server to an output plugin that delivers tags from the server to external systems, such as connecting the integration table populated by OPC UA to the ThingWorx connector.

The data source for an output definition is an integration table.

An output plugin delivers tags from an integration table in FairCom Edge over an external protocol, such as OPC UA, to an external system, such as a device or Manufacturing Execution System (MES).

Each integration table can have zero or more integrations assigned to it. Thus, multiple plugins can read from the same integration table. For example, the MQTT and THINGWORX plugins can use the same integration table.

Note Use the "configureTopic" action in the MQ API to connect MQTT to an existing integration table.

A tag is a piece of named data with an associated value. For example, the tag temperature 70 includes both the named data temperature and the value 70. In JSON, a tag is a JSON property, such as "temperature": 70. In a SQL table, a tag is a data field, such as a field named temperature with a value of 70.

 

Request examples

Important The "createOutput" action does NOT create an integration table. You must create an integration table with the "createIntegrationTable" action before calling "createOutput".

Minimal

{
  "action":    "createOutput",
  "params":    {
    "outputName":   "writeEverythingToModbus",
    "serviceName":  "modbus",
    "databaseName": "faircom",
    "tableName":    "modbusTableTCP",
    "settings":     {
      "modbusProtocol":   "TCP",
      "modbusServer":     "127.0.0.1",
      "modbusServerPort": 502,
      "propertyMapList":  [
        {
          "propertyPath":      "source_payload",
          "modbusDataAddress": 1199,
          "modbusDataAccess":  "holdingregister",
          "modbusUnitId":      5,
          "modbusDataLen":     1
        }
      ]
    }
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Maximal

{
  "api":             "hub",
  "action":          "createOutput",
  "params":          {
    "outputName":   "writeTemperatureToModbus",
    "serviceName":  "modbus",
    "databaseName": "faircom",
    "tableName":    "modbusTableTCPTemp",
    "ownerName":    "admin",
    "sourceFields": [
      "source_payload"
    ],
    "settings":     {
      "modbusProtocol":   "TCP",
      "modbusServer":     "127.0.0.1",
      "modbusServerPort": 502,
      "propertyMapList":  [
        {
          "propertyPath":      "source_payload.temperature",
          "modbusDataAddress": 1199,
          "modbusDataAccess":  "holdingregister",
          "modbusUnitId":      5,
          "modbusDataLen":     1
        }
      ],
      "sourceDataField":  "source_payload",
      "sourceDataFormat": "JSON"
    },
    "metadata":     {
      "description": "This output copies the source_payload.temperature property to the Modbus listener at 127.0.0.1.",
      "tags":        [ "temperature" ]
    }
  },
  "responseOptions": {
    "binaryFormat":  "hex",
    "dataFormat":    "objects",
    "numberFormat":  "string",
    "includeFields": [ ],
    "excludeFields": [ ]
  },
  "authToken":       "replaceWithAuthTokenFromCreateSession",
  "requestId":       "2",
  "debug":           "max"
}
 
 

 

Response example

Success

{
  "result": {},
  "requestId": "00000004",
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

 

Properties

Request properties ("params")

Property Description Default Type Limits (inclusive)

databaseName

The "databaseName" property specifies the database that contains an object, such as a table or code package. If it is set to null or is omitted, it defaults to the default database of the JSON Action session, see "createSession" and the "defaultDatabaseName" property. 

You specify this property when you want to use a different database instead of the default. 

This property is useful because objects, such as tables and code packages, can have the same name in multiple databases. This feature allows you to create multiple environments in the same server and reuse the same JSON actions in each environment. For example, you can create "dev", "test", "stage", and "prod" databases on the same server and use the "defaultDatabaseName" or "databaseName" properties to specify the desired environment.

It is an error to set "databaseName" to the empty string "".

If no default database is specified during "createSession", the server sets the "defaultDatabaseName" to the "defaultDatabaseName" value specified in the services.json file.

 Defaults to the session's "defaultDatabaseName" property string 1 to 64 bytes

enabled

 The "enabled" property turns on or off an input or output connector. Thus, it pauses or starts data collection or delivery. Optional with default of true Boolean

true

false

metadata

 The "metadata" property contains user-defined properties that add keywords and tags about the code package. The server indexes this field with a full-text index so you can search for any word or phrase to find code packages. Optional with default of {} object 0 or more key/value pairs

outputName

The "outputNames" property specifies the names of outputs to be used to filter the response. The response will include details about all outputs with an "outputName" that matches one of the strings in the array.

 Optional with default of []

array

 1 or more strings

ownerName

The "ownerName" property specifies the account that owns an object, such as a table or code package. See "createSession" and the "defaultOwnerName" property for more details. 

You specify this property when you want to use a different account instead of the default. Your session's account must have the appropriate privileges to access the code package. 

This property is useful because objects, such as tables and code packages, can have the same name in the same database as long as different accounts own each object. This feature allows you to create duplicate objects for different users on the same server and reuse the same JSON actions on those objects. For example, an administrator can copy objects from a production environment to her account so she can troubleshoot an issue using the same JSON actions, JavaScript, and SQL code.

It is an error to set "ownerName" to the empty string "".

If no default owner is specified during "createSession", the server sets the "defaultOwnerName" to the "defaultOwnerName" value specified in the services.json file.

 Optional with default of the session's "defaultOwnerName" property string 1 to 64 bytes

serviceName

The "serviceName" property contains the name of a FairCom input or output service. 

See the "params" topic of each specific service for the requirements of this property.

The following services are available as of the V5 release:
  • "MODBUS"
  • "SIEMENSUDT2JSON"
  • "OPCUA"

Note The SQL, JSON RPC, and REST services can automatically query any integration table in FairCom's servers without requiring configuration.

MQTT always represents both input and output services. This is because once a topic is created and assigned to an integration table, any MQTT client can publish messages to it and subscribe to those messages.

 Required - No default value string 1 to 64 bytes

settings

The "settings" property contains properties that are specific for each connector type. Settings for Modbus are different than settings for OPC UA, and so forth. See the API reference "params" property of each connector for details of the "settings" property for that connector.

Connector-specific "settings"

 Optional with default of {} object

Allen-Bradley "params"

Modbus "params"

OPC UA "settings"

Siemens S7 "params"

sourceFields

The "sourceFields" property specifies the fields the FairCom server makes available to the output connector. The server creates a JSON object from the fields you specify, and the output connector uses it as its source data. If "sourceFields" is omitted, set to null or [], the FairCom server defaults to creating a JSON document that contains all fields from the integration table. This default allows the output connector to send data to a device from any field in the table.

An integration table has many fields, such as fields populated by transforms and MQTT. Converting all fields into JSON is slower than converting only the fields needed by the output connector. For example, input connectors and MQTT messages store their data in the source_payload field. You can use "sourceFields": ["source_payload"] to make only the source_payload field available to the output connector.

When you configure an output connector, you add propertyMap objects to the "propertyMapList". Each propertyMap object extracts data from one field and writes that data to the connected device. The value of the "propertyPath" property is a string containing the path of the data. It always starts with a field name in the "sourceFields" property. For example, if "sourceFields" is set to ["pressure"], then you must set "propertyPath" to "pressure" to use the pressure field’s value in your output. If the value you want to extract is a JSON property nested inside a field, you must add its full path to the "propertyPath". For example, if "sourceFields" is set to ["source_payload"] and source payload contains a JSON object with a "temperature" property, then you must set "propertyPath" to "source_payload.temperature".

 Optional with default of [] array One or more fields form the integration table.

tableName

The "tableName" property contains the unique, user-defined name of a table.

See table name in System limits for the table naming requirements and limitations.

 

"params": {
  "tableName": "ctreeTable"
}
 Required - No default value string 1 to 64 bytes

 

Response properties ("result")

Property Description Type Limits (inclusive)

data

The "data" property contains a response message. Its contents are defined by the action. It is an empty array when no results are available. The following is an example of the data property from a code package action.

  "result": {
    "data": [
      {
        "codeId": 6,
        "databaseName": "faircom",
        "ownerName": "admin",
        "codeName": "convertAndCategorizeTemperature",
        "codeVersion": 1,
        "clonedCodeId": 1,
        "codeStatus": "active",
        "codeLanguage": "javascript",
        "serviceName": "javascript",
        "codeType": "module",
        "description": "optional new description",
        "metadata": {},
        "createdBy": "ADMIN",
        "createdOn": "2025-08-25T21:48:38.109",
        "updatedBy": "ADMIN",
        "updatedOn": "2025-08-25T21:48:38.109",
        "comment": "Cloned from convertTemperature",
        "codeFormat": "utf8"
      },
    ]
 array of objects The action determines its contents.

data

.enabled


The "enabled" property is true when a connector is allowed to connect to a device. It is false when a connector will not attempt to connect to the device.

 

 boolean true
false

data

.running

 The "running" property is true when an input connector is collecting data or an output connector is delivering data; otherwise, it is false. A disabled connector will never be running. An enabled connector may or may not be running. Boolean

true

false

data

.stopCode

 The "stopCode" property is 0 when the connector is successfully connected to its device or software; otherwise, it is non-zero. integer -2147483648 to 2147483647

data

.stopReason

 The "stopReason" property is "" when the input connector is collecting data; otherwise, it is a non-empty string. string 0 to 256 bytes

 

Was this article helpful?

Give feedback about this article

Related Articles