Skip to main content

"alterInput" (jsonAction)

JSON hub "alterInput" action modifies an existing FairCom Edge input

The "alterInput" action alters an existing input connector in FairCom Edge to collect tags automatically from a device or software system. Before you can alter an input, you must use "createInput" 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.

Essential information

  • "alterInput" modifies how an input service collects data from a data source, transforms it, and inserts it into an integration table.

    For example, an input can configure the OPC UA service to collect data from an external source and write that data to an integration table in FairCom Edge.

  • You can do the following:

    • You can change the settings of an input.

    • You can change the retention policy of the input’s integration table.

    • You can change the transforms applied to the data when it is inserted into the integration table.

    • You can change metadata about the input to make it easier to locate.

  • You cannot do the following:

    • You cannot change the mapping between the service and the integration table. To do this, you need to create a new input and delete the old one.

    • You cannot remap a connector service to a different integration table because this mapping is fundamental to the nature of the input. In the future, we may enhance this action to be able to remap the connector service to a different integration table, or we may provide a special action just for this purpose.

      The action, "alterInput", is the only way to configure an existing input. If the specified value of "inputName" does not find an existing input, this action returns an error. To create an input, use the "createInput" action.

Request examples

Minimal

{
  "api":        "hub",
  "apiVersion": "1.0",
  "requestId":  "optionalUniquerequestIdFromTheClient",
  "action":     "alterInput",
  "params":     {
    "inputName":       "AcmefactoryLine1Station1AcidbathTelemetry"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Maximal

{
  "api":        "hub",
  "apiVersion": "1.0",
  "requestId":  "optionalUniquerequestIdFromTheClient",
  "action":     "alterInput",
  "params":     {
    "inputName":       "AcmefactoryLine1Station1AcidbathTelemetry",
    "metadata":        {
      "description": "a description of what this ",
      "tags":        [ "" ]
    },
    "transformNames":  [ "" ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Response examples

Minimal

{
    "resulet":{},
    "requestId":"00000005",
    "errorCode": 0,
    "errorMessage":""
}

Maximal

{
    "resulet":{},
    "requestId":"00000005",
    "errorCode": 0,
    "errorMessage":""
}

Use the alterInput JSON API action to alter an existing input connector in FairCom edge

API actionsJSON hub APIjsonActioninput actionsalter inputalterInput

"params"

The "params" property is an object that contains an action's parameters. Each action defines its own required and optional properties.

Table 1. "params" property summaries

Property

Description

Default

Type

Limits (inclusive)

dataCollectionIntervalMilliseconds

(optional) specifies the number of milliseconds to wait until reading PLC data again. For example, 15000 means 15 seconds

10000

integer

0 and negative values are invalid.

dataCollectionBufferCount

(optional) specifies the number of times the collector retrieves and caches data from the device before writing the data to the integration table

1

integer

1 to 65535

dataPersistenceStrategy

(optional) specifies when the connector writes collected data to the specified table

"onSchedule"

string

"onSchedule"
"onChange"

immediatelyCollectDataOnStart

(optional) configures the input to collect data immediately when the server or connector starts. This occurs even if the data persistence strategy is to collect data changes

false

Boolean

true
false

inputName

(optional) contains a unique name for the mapping of a data source to an input plugin to an integration table

A FairCom generated name that follows the pattern "Input #n from <pluginName> to <databaseName>.<ownerName>.<tableName>"

string

1 to 100 bytes

metadata

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

{}

object

May contain any number and type of user-defined properties

settings

(optional) contains properties needed to configure the data source of the specified plugin

{}

object

sourcePayloadFormat

(optional) specifies the variant type format of the "source_payload" field

"binary"

string

"json"
"xml"
"binary"
"jpeg"
"siemensUdt"
"utf8"

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

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

"sourcePayloadFormat"

The "sourcePayloadFormat" property is an optional string that defines the variant type format of the "source_payload" field. When omitted or set to null, it defaults to "binary".

  • This property is a string containing the following enumerated values:

    •  "binary"

    • "json"

    • "utf8"

    • "siemensUDT"

    • "jpeg"

    • "xml"

  • This property is a hint to the server about the format and type of the MQTT message payload.

  • This property does not cause server to validate the MQTT payload to see if it matches the type you set. The server stores the payload as is without validation. For example, if you set the type to "json", it does not stop the server from receiving and storing a non-JSON value or invalid JSON document in the source payload.

  • The FairCom Edge Explorer application may use the value of this property to determine the default way to display a topic's payload.

  • The transform engine may use the value of this property to help it transform the source payload.

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

Would you like to provide feedback?