MTConnect API reference

MTConnect connector specifications for FairCom Edge

FairCom provides special API actions for the MTConnect connector. The MTConnect service must be enabled in order to complete FairCom MTConnect API actions.

 

Request examples

Minimal

{
  "action": "createInput",
  "params": {
    "inputName": "mymtconnect",
    "serviceName": "mtconnect",
    "settings": {
      "host": "195.167.1.5:5000",
      "propertyMapList": [
        {
      "propertyPath": "device1Action1PositionInMillimeters",
      "mtconnectDeviceUuid": "Device1",
      "mtconnectDataItemId": "Device1_Act1_1",
      "dataType": "string"
        }
      ]
    },

    "tableName": "mtconnectTable"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Maximal

{
  "api": "hub",
  "action": "createInput",
  "params": {
    "inputName": "mymtconnect",
    "serviceName": "mtconnect",
    "settings": {
      "host": "195.167.1.5:5000",
      "dataCollectionIntervalMilliseconds": 5000,
      "propertyMapList": [
        {
          "propertyPath": "temperature.value",
          "dataType": "string",
          "defaultValue": "-1",
          "mtconnectDeviceUuid": "X1_373f-4ab9-9c7a-173edd23e4f3",
          "mtconnectDataItemId": "X1_Stamper1_Temperature",

          "mtconnectCategoryPropertyPath": "temperature.category",
          "mtconnectComponentNamePropertyPath": "temperature.component",
          "mtconnectDataItemIdPropertyPath": "temperature.dataItemId",
          "mtconnectDataNamePropertyPath": "temperature.dataName",
          "mtconnectDataTypePropertyPath": "temperature.dataType",
          "mtconnectDeviceNamePropertyPath": "temperature.device",
          "mtconnectDeviceUuidPropertyPath": "temperature.deviceUuid",
          "mtconnectSequencePropertyPath": "temperature.sequence",
          "mtconnectTimestampPropertyPath": "temperature.timestamp"
        }
      ]
    },
    "ownerName": "admin",
    "tableName": "mtconnectTable",
    "retentionPolicy": "autoPurge",
    "retentionPeriod": 30,
    "retentionUnit": "day",
    "metadata": {
    }
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

 

Response examples

Success

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

Failure

{
  "result": {},
  "requestId": "00000002",
  "debugInfo": {
    "request": {
      "api": "hub",
      "action": "createInput",
      "params": {
        "inputName": "MTConnect2",
        "serviceName": "mtconnect",
        "settings": {
          "host": "195.167.1.5:5000",
          "dataCollectionIntervalMilliseconds": 5000,
          "propertyMapList": [
            {
              "propertyPath": "temperature",
              "mtconnectDeviceUuid": "9617890b-7526-9f6b-214f-0c860ace6485",
              "mtconnectDataItemId": "rf",
              "dataType": "integer",
              "defaultValue": 0
            }
          ]
        },
        "ownerName": "admin",
        "tableName": "mtconnectTable",
        "dataBase": "faircom",
        "retentionPolicy": "autoPurge",
        "retentionPeriod": 30,
        "retentionUnit": "day",
        "metadata": {}
      },
      "requestId": "00000002",
      "debug": "max",
      "authToken": "replaceWithAuthTokenFromCreateSession"
    }
  },
  "errorCode": 12012,
  "errorMessage": "Not possible to start MTConnect service instance [MTConnect2] - Not able to load MTConnect property mapping. Invalid property dataType value 'integer' [9617890b-7526-9f6b-214f-0c860ace6485/temperature]. Possible values are 'boolean' and 'string'.",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

 

Properties

Request properties ("params")

Property Description Defualt Type Limits (inclusive)

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

enabledFilter

 The "enabledFilter" property returns input connections that are enabled or not. Omit or set to null to match all connections. Optional with default of null Boolean

true

false

inputName

The "inputName" property specifies the unique name of an input. A FairCom generated name follows the pattern "Input #n from <pluginName> to <databaseName>.<ownerName>.<tableName>".

"params": {
    "inputName": "modbusTCP",
    "serviceName": "modbus"
}

Required - No default value

 string 1 to 100 bytes

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

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

retentionPeriod

The "retentionPeriod" property specifies how many units of data to retain. It refers to the unit of time specified by the "retentionUnit" property. For more details, see "retentionPeriod".

Optional with default of 30

 integer 1 to 100

retentionPolicy

The "retentionPolicy" property controls how messages are persisted. 

If not specified, the default found in the services.json file is used. Initially, it is "autoPurge".

 

retentionPolicy values:
  • "autoPurge"
    • This is the default. It is automatically applied when a new topic is created. It is preferred because it allows FairCom's servers to automatically remove messages that are older than the retention time. This helps ensure message data does not consume all storage space. It also minimizes storage costs and speeds up data access. The server partitions a table into multiple files so it can efficiently delete expired files.
  • "neverPurge"
    • This stores messages on disk and never removes them. This is useful when you need the entire history of the message stream. If message velocity is high, this can consume all storage space and cause an outage. The server creates a non-partitioned table, which is slightly faster than a partitioned table because it stores all records in one file.

Optional with default of "autoPurge"

 string

"autoPurge"

"neverPurge"

retentionUnit

The "retentionUnit" property specifies a unit of time that the server will use to purge expired messages. For example, if you want a week's worth of messages to be purged once a week, set "retentionUnit" to "week". This property is optional.

If not specified, the default found in the services.json file is used. Initially, it is "week". 

  • This property is used in concert with "retentionPeriod" to determine retention time.
  • "retentionUnit" values:
    • "minute"
    • "hour"
    • "day"
    • "week"
    • "month"
    • "year"
    • "forever"

Note 

  • For best performance, set the "retentionUnit" to a value that keeps "retentionPeriod" between 5 and 30. 
  • When you set "retentionUnit" property to "forever" the server will not purge messages. This setting is the same as setting "retentionPolicy" to "neverPurge".
  • The "retentionUnit" and "retentionPeriod" properties are used only when the "retentionPolicy" is set to "autoPurge".

Optional with default of "day"

string

"minute"

"hour"

"day"

"week"

"month"

"year"

runningFilter

 The "runningFilter" property returns input connections that are running or not. Omit or set to null to match all connections. Optional with default of null Boolean

true

false

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"

settings

.dataCollectionIntervalMilliseconds

The "dataCollectionIntervalMilliseconds" property schedules the connector to collect data periodically using the specified number of milliseconds. 

 Optional with default of 10000 (10 seconds). integer 0 and negative values are invalid.

settings

.host

 The "host" property specifies the IP or hostname of the Rest resource, including the port. Required - No default string 1 to 1024 bytes

settings

.propertyMapList

 The "propertyMapList" property specifies which data the connector requests and where to put it in the generated JSON. Required - No default value array of objects

zero or more objects containing zero or more of the following properties:

"dataType" "defaultValue" "mtconnectCategoryPropertyPath" "mtconnectComponentNamePropertyPath" "mtconnectDataItemId" "mtconnectDataItemIdPropertyPath" "mtconnectDataNamePropertyPath" "mtconnectDataTypePropertyPath" "mtconnectDeviceNamePropertyPath" "mtconnectDeviceUuid" "mtconnectDeviceUuidPropertyPath" "mtconnectSequencePropertyPath" "mtconnectTimestampPropertyPath"

"propertyPath"

settings

propertyMapList

.dataType

The "dataType" property specifies the data type of memory retrieved by the connector.

If "memoryArea":"ct", "dataType" must be "counter". 

If "memoryArea":"tm", "dataType" must be "timer".

 Required - No default value string
  • "bit" - inside a byte
  • "byte" - 8-bit integer
  • "ubyte" - unsigned 8-bit integer
  • "word" - 16-bit integer
  • "uword" - unsigned 16-bit integer
  • "doubleword" - 32-bit integer
  • "udoubleword" - unsigned 32-bit integer
  • "real" - 32-bit float
  • "counter" - 16-bit integer
  • "timer" - 16-bit integer

settings

propertyMapList

.defaultValue

 The "defaultValue" property specifies the default value of a field. It is used when a record is inserted without specifying a value for the field. The server coerces the string value into the proper field type.  Optional with default of "" string 0 to 65,500 bytes

settings

propertyMapList

.mtconnectCategoryPropertyPath

The "mtconnectDeviceUuid" property specifies the identifier of the device that supplies data to the connector. For more details, see "mtconnectDeviceUuid".

 Required - No default value string No limit

settings

propertyMapList

.mtconnectComponentNamePropertyPath

 The "mtconnectDataItemId" property specifies the identifier of the data that the MTConnect connector collects. For more details, see "mtconnectDataItemId". Required - No default value string No limit

settings

propertyMapList

.mtconnectDataItemId

The "mtconnectCategoryPropertyPath" property specifies the location in the JSON document to store the MTConnect category of the data item. For more details, see "mtconnectCategoryPropertyPath".

 Optional with default of null string JSON path

settings

propertyMapList

.mtconnectDataItemIdPropertyPath

The "mtconnectComponentNamePropertyPath" property specifies the location in the JSON document to store the MTConnect component name of the data item. For more details, see "mtconnectComponentNamePropertyPath".

 Optional with default of null string JSON path

settings

propertyMapList

.mtconnectDataNamePropertyPath

The "mtconnectDataItemIdPropertyPath" property specifies the location in the JSON document to store the MTConnect dataItemID of the data item. For more details, see "mtconnectDataItemIdPropertyPath".

 Optional with default of null string JSON path

settings

propertyMapList

.mtconnectDataTypePropertyPath

The "mtconnectDataNamePropertyPath" property specifies the location in the JSON document to store the MTConnect data name of the data item. For more details, see "mtconnectDataNamePropertyPath".

 Optional with default of null string JSON path

settings

propertyMapList

.mtconnectDeviceNamePropertyPath

The "mtconnectDataTypePropertyPath" property specifies the location in the JSON document to store the MTConnect data type of the data item. For more details, see "mtconnectDataTypePropertyPath".

 Optional with default of null string JSON path

settings

propertyMapList

.mtconnectDeviceUuid

The "mtconnectDeviceNamePropertyPath" property specifies the location in the JSON document to store the MTConnect device name that provides the data item. For more details, see "mtconnectDeviceNamePropertyPath".

 Optional with default of null string JSON path

settings

propertyMapList

.mtconnectDeviceUuidPropertyPath

The "mtconnectDeviceUuidPropertyPath" property specifies the location in the JSON document to store the MTConnect deviceUuid of the device that provides the data item. For more details, see "mtconnectDeviceUuidPropertyPath".

 Optional with default of null string JSON path

settings

propertyMapList

.mtconnectSequencePropertyPath

The "mtconnectSequencePropertyPath" property specifies the location in the JSON document to store the integer sequence number of the data item. For more details, see "mtconnectSequencePropertyPath".

 Optional with default of null string JSON path

settings

propertyMapList

.mtconnectTimestampPropertyPath

The "mtconnectTimestampPropertyPath" property specifies the location in the JSON document to store the timestamp of when the device collects the data item. In contrast, the timestamp built into FairCom's integration table tracks when the FairCom connector collects the data. When a device collects data infrequently, the device timestamp is more accurate than FairCom's built-in timestamp. For more details, see "mtconnectTimestampPropertyPath".

 Optional with default of null string JSON path

settings

propertyMapList

.propertyPath

 The "propertyPath" property specifies the name of the data to be defined by "propertyValue". Required - No default value string 0 to 256 bytes

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

 

 
mtconnect api documentation

Was this article helpful?

Give feedback about this article

Related Articles