alterOutput

JSON hub "alterOutput" action modifies a FairCom Edge output

The "alterOutput" action alters an existing output connector in FairCom Edge to deliver tags automatically to a device or software system. Before you can change an output, you must use "createOutput" to create it.

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

  • You can change the source field of the integration table that supplies the data for the plugin.
  • You can change the data format of the source field.
  • You can change the settings of an integration.
  • You can change metadata to make the integration easier to locate.
  • You cannot change the plugin or the integration table.
    • You will need to create a new integration.
  • An integration connects data in the server to a plugin that delivers data from the server to external systems, such as connecting the integration table populated by OPC UA to the ThingWorx connector.

Note Use"configureTopic" to connect MQTT to an existing integration table.

 

Request examples

Minimal

{
  "action":    "alterOutput",
  "params":    {
    "outputName": "writeEverythingToModbus",
    "settings":   {
      "modbusProtocol":  "TCP",
      "modbusServer":    "localhost",
      "propertyMapList": [
        {
          "propertyPath":      "source_payload.temperature",
          "modbusDataAddress": 1199,
          "modbusDataAccess":  "holdingregister",
          "modbusUnitId":      5,
          "modbusDataLen":     1
        }
      ]
    }
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Maximal

{
  "api":             "hub",
  "action":          "alterOutput",
  "params":          {
    "outputName":   "writeTemperatureToModbus",
    "databaseName": "faircom",
    "sourceFields": [
      "source_payload"
    ],
    "settings":     {
      "modbusProtocol":   "TCP",
      "modbusServer":     "localhost",
      "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 localhost.",
      "tags":        [
        "temperature"
      ]
    }
  },
  "responseOptions": {
    "binaryFormat": "hex",
    "dataFormat":   "objects",
    "numberFormat": "string"
  },
  "authToken":       "replaceWithAuthTokenFromCreateSession",
  "requestId":       "2",
  "debug":           "max"
}
 
 

 

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 "outputName" property specifies a unique name for mapping an integration table to an output plugin to an external system. A FairCom generated name follows the pattern "Output #n from <databaseName>.<schemaName>.<tableName> to <pluginName>".

Optional with default of ""

 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.

 

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