MTConnect API reference

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

{
  "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",
              "deviceUuid": "9617890b-7526-9f6b-214f-0c860ace6485",
              "dataItemId": "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"
}

The "dataCollectionIntervalMilliseconds" property schedules the connector to collect data periodically using the specified number of milliseconds. It defaults to 10000, which is ten seconds. It must be an integer number >= 1.

The optional "dataType" property specifies the JSON data type the connector uses to encode the data value it retrieves from MTConnect. It defaults to "string".

The MTConnect protocol uses XML to deliver data and XML stores data as string values. By default, the FairCom MTConnect Connector converts XML data into a JSON string because it can represent any data value. For example, the value 20.32 is stored in JSON as the string "20.32". A string is the safe way to encode a number in JSON because many JSON parsers convert JSON numbers into IEEE Floating point numbers, which are approximate numbers with rounding and base-two conversion problems. 

If you set the "dataType" property to "boolean", the connector converts the XML data value to true or false.

MTConnect often returns a data item with the value of "UNAVAILABLE" when the device cannot retrieve the data. The FairCom MTConnect connector converts a value of "UNAVAILABLE" into null.

The optional "defaultValue" property specifies the default value if MTConnect does not return a value or returns "UNAVAILABLE" as the value of the specified data item. It defaults to null. You can specify any JSON value to be used as the default value.

Data is unavailable if the connector cannot find an MTConnect element with a matching dataItemId attribute or the element contains the text "UNAVAILABLE".

The optional "mtconnectCategoryPropertyPath" property specifies the location in the JSON document to store the MTConnect category of the data item. Omit this property to omit it from the JSON document.

When the FairCom MTConnect connector collects data, it generates a JSON document and stores it in the database. The connector extracts the name of the parent element that contains the data item. The parent element may be <Samples>, <Events>, or <Condition>. The connector maps the element name to one of the following category strings:  "SAMPLE", "EVENT", or "CONDITION". It then puts the category string in the JSON document at the location specified by this property. You may use a simple property name, such as "temperatureCategory", or a complex JSON path, such as "temperature.category". For examples, see Example property paths that group related properties.

In the following MTConnectStreams XML document returned over the MTConnect protocol, the data element has a dataItemId of "X1_Stamper1_Temperature". The element is named <Samples>, which maps to the category of "SAMPLE".

<MTConnectStreams>
  <Streams>
    <DeviceStream 
      name="X1" 
      uuid="X1_373f-4ab9-9c7a-173edd23e4f3">
      <ComponentStream 
        component="Device" 
        name="Stamper1" 
        componentId="X1_Stamper1">
        <Samples>
          <REAL 
            dataItemId="X1_Stamper1_Temperature"
            name="Temperature"
            sequence="5" 
            timestamp="2010-04-06T06:19:35.153141"
            >20.1</REAL>
        </Samples>
      </ComponentStream>
    </DeviceStream>
  </Streams>
</MTConnectStreams>

The optional "mtconnectComponentNamePropertyPath" property specifies the location in the JSON document to store the MTConnect component name of the data item. Omit this property to omit it from the JSON document.

When the FairCom MTConnect connector collects data, it generates a JSON document and stores it in the database. The connector extracts the value of the name attribute of the <ComponentStream> element that contains the data item. It puts the component name in the JSON document at the location specified by this property. You may use a simple property name, such as "temperatureComponent", or a complex JSON path, such as "temperature.component". For examples, see Example property paths that group related properties.

In the following MTConnectStreams XML document returned over the MTConnect protocol, the data element has a dataItemId of "X1_Stamper1_Temperature". The <componentStream> element containing the data element has a name attribute of "Stamper1", which is the component name.

<MTConnectStreams>
  <Streams>
    <DeviceStream 
      name="X1" 
      uuid="X1_373f-4ab9-9c7a-173edd23e4f3">
      <ComponentStream 
        name="Stamper1" 
        component="Device" 
        componentId="X1_Stamper1">
        <Samples>
          <REAL 
            dataItemId="X1_Stamper1_Temperature"
            name="Temperature"
            sequence="5" 
            timestamp="2010-04-06T06:19:35.153141"
            >20.1</REAL>
        </Samples>
      </ComponentStream>
    </DeviceStream>
  </Streams>
</MTConnectStreams>

The required "mtconnectDataItemId" property specifies the identifier of the data that the MTConnect connector collects. 

When the FairCom MTConnect Connector requests data over the MTConnect protocol, the device returns an <MTConnectStreams> XML document. Data is located in elements containing the dataItemId attribute. The element's name is its data type and its value is the data. The "mtconnectDataItemId" property identifies a data item by specifying the value of the data element's dataItemId attribute.

If the MTConnect protocol returned the following <MTConnectStreams> XML document, you should set the "mtconnectDataItemId" property to "X1_Stamper1_Temperature". The data element is named REAL, which is its data type, and has a data value of "20.1".

<MTConnectStreams>
  <Streams>
    <DeviceStream 
      name="X1" 
      uuid="X1_373f-4ab9-9c7a-173edd23e4f3">
      <ComponentStream 
        component="Device" 
        name="Stamper1" 
        componentId="X1_Stamper1">
        <Samples>
          <REAL 
            dataItemId="X1_Stamper1_Temperature"
            name="Temperature"
            sequence="5" 
            timestamp="2010-04-06T06:19:35.153141"
            >20.1</REAL>
        </Samples>
      </ComponentStream>
    </DeviceStream>
  </Streams>
</MTConnectStreams>

The optional "mtconnectDataItemIdPropertyPath" property specifies the location in the JSON document to store the MTConnect dataItemID of the data item. Omit this property to omit it from the JSON document.

When the FairCom MTConnect connector collects data, it generates a JSON document and stores it in the database. The connector extracts the value of the dataItemID attribute of the element that contains the data item. It puts the dataItemID value in the JSON document at the location specified by this property. You may use a simple property name, such as "temperatureDataItemID", or a complex JSON path, such as "temperature.dataItemID". For examples, see Example property paths that group related properties.

In the following MTConnectStreams XML document returned over the MTConnect protocol, the data element has a dataItemId of "X1_Stamper1_Temperature".

<MTConnectStreams>
  <Streams>
    <DeviceStream 
      name="X1" 
      uuid="X1_373f-4ab9-9c7a-173edd23e4f3">
      <ComponentStream 
        name="Stamper1" 
        component="Device" 
        componentId="X1_Stamper1">
        <Samples>
          <REAL 
            dataItemId="X1_Stamper1_Temperature"
            name="Temperature"
            sequence="5" 
            timestamp="2010-04-06T06:19:35.153141"
            >20.1</REAL>
        </Samples>
      </ComponentStream>
    </DeviceStream>
  </Streams>
</MTConnectStreams>

The optional "mtconnectDataNamePropertyPath" property specifies the location in the JSON document to store the MTConnect data name of the data item. Omit this property to omit it from the JSON document.

When the FairCom MTConnect connector collects data, it generates a JSON document and stores it in the database. The connector extracts the value of the name attribute of the element that contains the data item. It puts the data name in the JSON document at the location specified by this property. You may use a simple property name, such as "temperatureDataName", or a complex JSON path, such as "temperature.dataName". For examples, see Example property paths that group related properties.

In the following MTConnectStreams XML document returned over the MTConnect protocol, the data element has a dataItemId of "X1_Stamper1_Temperature". The element containing the data item has a name attribute of "Temperature", which is the data name.

<MTConnectStreams>
  <Streams>
    <DeviceStream 
      name="X1" 
      uuid="X1_373f-4ab9-9c7a-173edd23e4f3">
      <ComponentStream 
        name="Stamper1" 
        component="Device" 
        componentId="X1_Stamper1">
        <Samples>
          <REAL 
            dataItemId="X1_Stamper1_Temperature"
            name="Temperature"
            sequence="5" 
            timestamp="2010-04-06T06:19:35.153141"
            >20.1</REAL>
        </Samples>
      </ComponentStream>
    </DeviceStream>
  </Streams>
</MTConnectStreams>

The optional "mtconnectDataTypePropertyPath" property specifies the location in the JSON document to store the MTConnect data type of the data item. Omit this property to omit it from the JSON document.

When the FairCom MTConnect connector collects data, it generates a JSON document and stores it in the database. The connector extracts the name of the element that contains the data item and puts it in the JSON document at the location specified by this property. You may use a simple property name, such as "temperatureDataType", or a complex JSON path, such as "temperature.dataType". For examples, see Example property paths that group related properties.

In the following MTConnectStreams XML document returned over the MTConnect protocol, the data element has a dataItemId of "X1_Stamper1_Temperature". The element is named REAL, which is the data type of the data value.

<MTConnectStreams>
  <Streams>
    <DeviceStream 
      name="X1" 
      uuid="X1_373f-4ab9-9c7a-173edd23e4f3">
      <ComponentStream 
        component="Device" 
        name="Stamper1" 
        componentId="X1_Stamper1">
        <Samples>
          <REAL 
            dataItemId="X1_Stamper1_Temperature"
            name="Temperature"
            sequence="5" 
            timestamp="2010-04-06T06:19:35.153141"
            >20.1</REAL>
        </Samples>
      </ComponentStream>
    </DeviceStream>
  </Streams>
</MTConnectStreams>

The optional "mtconnectDeviceNamePropertyPath" property specifies the location in the JSON document to store the MTConnect device name that provides the data item. Omitting this property removes it from the JSON document.

When the FairCom MTConnect connector collects data, it generates a JSON document and stores it in the database. The connector extracts the value of the name attribute of the <DeviceStream> element that contains the data item. It puts the device name in the JSON document at the location specified by this property. You may use a simple property name, such as "temperatureDevice", or a complex JSON path, such as "temperature.device". For examples, see Example property paths that group related properties.

In the following MTConnectStreams XML document returned over the MTConnect protocol, the data element has a dataItemId of "X1_Stamper1_Temperature". The <DeviceStream> element containing the data element has a name attribute of "X1", which is the device name.

<MTConnectStreams>
  <Streams>
    <DeviceStream 
      name="X1" 
      uuid="X1_373f-4ab9-9c7a-173edd23e4f3">
      <ComponentStream 
        component="Device" 
        name="Stamper1" 
        componentId="X1_Stamper1">
        <Samples>
          <REAL 
            dataItemId="X1_Stamper1_Temperature"
            name="Temperature"
            sequence="5" 
            timestamp="2010-04-06T06:19:35.153141"
            >20.1</REAL>
        </Samples>
      </ComponentStream>
    </DeviceStream>
  </Streams>
</MTConnectStreams>

The required "mtconnectDeviceUuid" property specifies the identifier of the device that supplies data to the connector. When the FairCom MTConnect Connector requests data over the MTConnect protocol, the device returns an <MTConnectStreams> XML document, which contains data from one or more devices. The "mtconnectDeviceUuid" property uniquely identifies the data stream the FairCom connector should use to gather data.

The device identifier is located in the uuid attribute of the <DeviceStream> element in an <MTConnectStreams> XML document returned from the MTConnect protocol. 

If the MTConnect protocol returns the following MTConnectStreams XML, you should set the "deviceUuid" property to "X1_373f-4ab9-9c7a-173edd23e4f3".

<MTConnectStreams>
  <Streams>
    <DeviceStream 
      name="X1" 
      uuid="X1_373f-4ab9-9c7a-173edd23e4f3">
      <ComponentStream 
        component="Device" 
        name="Stamper1" 
        componentId="X1_Stamper1">
        <Samples>
          <REAL 
            dataItemId="X1_Stamper1_Temperature"
            name="Temperature"
            sequence="5" 
            timestamp="2010-04-06T06:19:35.153141"
            >20.1</REAL>
        </Samples>
      </ComponentStream>
    </DeviceStream>
  </Streams>
</MTConnectStreams>

The optional "mtconnectDeviceUuidPropertyPath" property specifies the location in the JSON document to store the MTConnect deviceUuid of the device that provides the data item. Omit this property to omit it from the JSON document.

When the FairCom MTConnect connector collects data, it generates a JSON document and stores it in the database. The connector extracts the value of the deviceUuid attribute of the <DeviceStream> element that contains the data item. It puts the deviceUuid in the JSON document at the location specified by this property. You may use a simple property name, such as "temperatureDeviceUuid", or a complex JSON path, such as "temperature.deviceUuid". For examples, see Example property paths that group related properties.

In the following MTConnectStreams XML document returned over the MTConnect protocol, the data element has a dataItemId of "X1_Stamper1_Temperature". The <DeviceStream> element containing the data element has a deviceUuid attribute of "X1_373f-4ab9-9c7a-173edd23e4f3", which is the deviceUuid.

<MTConnectStreams>
  <Streams>
    <DeviceStream 
      name="X1" 
      uuid="X1_373f-4ab9-9c7a-173edd23e4f3">
      <ComponentStream 
        component="Device" 
        name="Stamper1" 
        componentId="X1_Stamper1">
        <Samples>
          <REAL 
            dataItemId="X1_Stamper1_Temperature"
            name="Temperature"
            sequence="5" 
            timestamp="2010-04-06T06:19:35.153141"
            >20.1</REAL>
        </Samples>
      </ComponentStream>
    </DeviceStream>
  </Streams>
</MTConnectStreams>

The optional "mtconnectSequencePropertyPath" property specifies the location in the JSON document to store the integer sequence number of the data item. Omit this property to omit it from the JSON document.

When the FairCom MTConnect connector collects data, it generates a JSON document and stores it in the database. The connector puts the value of the MTConnect sequence attribute in the JSON document at the location specified by this property. You may use a simple property name, such as "temperatureSequence", or a complex JSON path, such as "temperature.sequence". For examples, see Example property paths that group related properties.

When the FairCom MTConnect Connector requests data over the MTConnect protocol, the device returns an <MTConnectStreams> XML document, which contains data elements. A data element contains the dataItemId and sequence attributes. The sequence attribute identifies the device's sequence number of the data value.

In the following MTConnectStreams XML document returned over the MTConnect protocol, the data element has a dataItemId of "X1_Stamper1_Temperature". The element is named REAL. The value of the sequence attribute is 5. The MTConnect connector converts the sequence number into a JSON integer.

<MTConnectStreams>
  <Streams>
    <DeviceStream 
      name="X1" 
      uuid="X1_373f-4ab9-9c7a-173edd23e4f3">
      <ComponentStream 
        component="Device" 
        name="Stamper1" 
        componentId="X1_Stamper1">
        <Samples>
          <REAL 
            dataItemId="X1_Stamper1_Temperature"
            name="Temperature"
            sequence="5" 
            timestamp="2010-04-06T06:19:35.153141"
            >20.1</REAL>
        </Samples>
      </ComponentStream>
    </DeviceStream>
  </Streams>
</MTConnectStreams>

The optional "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. Omit this property to omit it from the JSON document.

When the FairCom MTConnect connector collects data, it generates a JSON document and stores it in the database. The connector puts the value of the MTConnect timestamp in the JSON document at the location specified by this property. You may use a simple property name, such as "temperatureTimestamp", or a complex JSON path, such as "temperature.timestamp".  For examples, see Example property paths that group related properties.

When the FairCom MTConnect Connector requests data over the MTConnect protocol, the device returns an <MTConnectStreams> XML document, which contains data elements. A data element contains the dataItemId and timestamp attributes. The timestamp attribute identifies when the device collected the element's data value.

In the following MTConnectStreams XML document returned over the MTConnect protocol, the data element has a dataItemId of "X1_Stamper1_Temperature". The element is named REAL. The value of the timestamp attribute is "2010-04-06T06:19:35.153141", which is formatted in ISO8601 format.

<MTConnectStreams>
  <Streams>
    <DeviceStream 
      name="X1" 
      uuid="X1_373f-4ab9-9c7a-173edd23e4f3">
      <ComponentStream 
        component="Device" 
        name="Stamper1" 
        componentId="X1_Stamper1">
        <Samples>
          <REAL 
            dataItemId="X1_Stamper1_Temperature"
            name="Temperature"
            sequence="5" 
            timestamp="2010-04-06T06:19:35.153141"
            >20.1</REAL>
        </Samples>
      </ComponentStream>
    </DeviceStream>
  </Streams>
</MTConnectStreams>

The required "propertyPath" property specifies the JSON path in the JSON document where the connector puts the data it collects. It is the tag name of the data being collected. You can use this property to take collected data and store it in any location in the JSON document generated by the connector. For example, the setting "propertyPath": "temperature" causes the server to take a value it collects, such as 20.1, and store it in a "temperature" property, such as { "temperature": 20.1 }.