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

Note A connector is a bridge between a device/software and an integration table.

Request examples

Minimal

{
  "action": "createInput",
  "params": {
    "inputName": "mymtconnect",
    "serviceName": "mtconnect",
    "thingName": "PLC 74",
    "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",
    "thingName": "PLC 74",
    "settings": {
      "host": "195.167.1.5:5000",
      "dataCollectionIntervalMilliseconds": 5000,
      "propertyMapList": [
        {
          "propertyPath": "temperature.value",  //Deprecated
          "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"
        },
        {
          "tagName": "device1Action1PositionInMillimeters",
          "mtconnectDeviceUuid": "Device2",
          "mtconnectDataItemId": "Device2_Act1_1",
          "dataType": "string"
        },
        {
          "tagId": 18,
          "mtconnectDeviceUuid": "Device3",
          "mtconnectDataItemId": "Device3_Act1_1",
          "dataType": "string"
        }
      ]
    },
    "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)
description	The `"description"` property assigns a description to a connector.	Optional with default of `""`	string	1 to 512 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`
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
purpose	The `"purpose"` property specifies the purpose of the thing. You can use it for fast partial lookups and filtering.	Optional with default of `"unknown"`	string	1 to 64 bytes Values are managed in the Label API with the group `"faircom/edge/purpose"`.
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.	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 JSON path in the JSON document where the connector puts the data it collects. It is mutually exclusive with the `"tagName"` and `"tagId"` properties.	Required - No default value	string	JSON path
settings propertyMapList .tagId	The `"tagId"` property associates a tag with a value being collected by a connector. It is mutually exclusive with the `"tagName"` and `"propertyPath"` properties. See tagId for more details.	Conditional - No default value	integer	If present, it must contain the ID of an existing tag, which is an integer from `0` to `9223372036854770000`. Note FairCom recommends using this property instead of `"propertyPath"`.
settings propertyMapList .tagName	The `"tagName"` property associates a tag with a value being collected by a connector. It is mutually exclusive with the `"tagId"` and `"propertyPath"` properties. See tagName for more details.	Conditional - No default value	string	If present, it must contain the name of an existing tag. Note FairCom recommends using this property instead of `"propertyPath"`.
status	The `"status"` property assigns an active or inactive status to a thing. An inactive status is like a soft delete.	Optional with default of "active"	string enum	`"active"` `"inactive"`
tableName	The `"tableName"` property contains the unique, user-defined name of a table. The table name must start with an upper or lowercase letter, must not contain special characters other than underscore `"_"`, and can include a mix of upper-lower case characters, but are treated as case-insensitive. "params": { "tableName": "ctreeTable" }	Required - No default value	string	1 to 64 bytes
thingId	The `"thingId"` property associates a connector with a device or software application. It is mutually exclusive with the `"thingName"` property. See thingId for more details.	Optional with default of `null`	integer	If present, it must contain the ID of an existing thing, which is an integer form `0` to `9223372036854770000`.
thingName	The `"thingName"` property associates a connector with a device or software application. It is mutually exclusive with the `"thingId"` property. See thingName for more details.	Optional with default of `null`	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 .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.	object	See these pages for connector specific properties: Allen-Bradley "params" Modbus "params" OPC UA "settings" Siemens S7 "params"
data settings .propertyMapList	The `"propertyMapList"` property specifies which data the connector requests and where to put it in the generated JSON.	array of objects	See these pages for connector specific properties: Allen-Bradley "params" Modbus "params" OPC UA "settings" Siemens S7 "params"
data settings propertyMapList .propertyPath	The `"propertyPath"` property specifies the JSON path in the JSON document where the connector puts the data it collects. It is mutually exclusive with the `"tagName"` and `"tagId"` properties.	string	JSON path
data settings propertyMapList .tagId	The `"tagId"` property associates a tag with a value being collected by a connector. It is mutually exclusive with the `"tagName"` and `"propertyPath"` properties. See tagId for more details.	integer	If present, it must contain the ID of an existing tag, which is an integer from `0` to `9223372036854770000`. Note FairCom recommends using this property instead of `"propertyPath"`.
data settings propertyMapList .tagName	The `"tagName"` property associates a tag with a value being collected by a connector. It is mutually exclusive with the `"tagId"` and `"propertyPath"` properties. See tagName for more details.	string	If present, it must contain the name of an existing tag. Note FairCom recommends using this property instead of `"propertyPath"`.
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
data .thingId	The `"thingId"` property associates a connector with a device or software application. It is mutually exclusive with the `"thingName"` property. See thingId for more details.	integer	If present, it must contain the ID of an existing thing, which is an integer form `0` to `9223372036854770000`.
data .thingName	The `"thingName"` property associates a connector with a device or software application. It is mutually exclusive with the `"thingId"` property. See thingName for more details.	string	1 to 64 bytes

MTConnect API reference

Request examples

Minimal

Maximal

Response examples

Success

Failure

Properties

Request properties ("params")

description

enabled

enabledFilter

inputName

metadata

ownerName

purpose

retentionPeriod

retentionPolicy

retentionUnit

runningFilter

serviceName

settings

.dataCollectionIntervalMilliseconds

.host

.propertyMapList

.dataType

.defaultValue

.mtconnectCategoryPropertyPath

.mtconnectComponentNamePropertyPath

.mtconnectDataItemId

.mtconnectDataItemIdPropertyPath

.mtconnectDataNamePropertyPath

.mtconnectDataTypePropertyPath

.mtconnectDeviceNamePropertyPath

.mtconnectDeviceUuid

.mtconnectDeviceUuidPropertyPath

.mtconnectSequencePropertyPath

.mtconnectTimestampPropertyPath

.propertyPath

.tagId

.tagName

status

tableName

thingId

thingName

Response properties ("result")

data

.enabled

.running

.settings

.propertyMapList

.propertyPath

.tagId

.tagName

.stopCode

.stopReason

.thingId

.thingName

Was this article helpful?

Related Articles

MTConnect connector

MTConnect Tutorials

Request properties (`"params"`)

Response properties (`"result"`)