Message Handling#

Overview#

The XML messages received from the equipment are converted to JSON and routed to a MES Service or to a DEE (Generic Action), according to the configuration set in the IoTMetadataDefinition Smart Table.

The STATE_CHANGE and ALIVE_REQ messages have dedicated sub-workflows. Every other message is dispatched to a specialized sub-workflow for further processing.

How To Configure#

For each message type that must be handled by MES, define one of the following entries in IoTMetadataDefinition, where MSGTYPE_REQ is replaced by the name of the actual XML message:

<MSGTYPE_REQ>_useService#

Entry name: MSGTYPE_REQ_useService — MSGTYPE_REQ is the message that will trigger the Service. If the received message matches the one specified, the Service will be called.

Entry value format: InputObject,OrchestrationNamespace | ServiceURL | KeyList

• InputObject: Service input object, namespace included.
• OrchestrationNamespace: Service namespace.
• ServiceURL: Service URL.
• KeyList: List of the keys to be used at the service input/output dictionaries, separated by commas: InputKey,OutputKey,ResourceKey. Defaults to MessageReceived,MessageToSend,ResourceName.

<MSGTYPE_REQ>_useDEE#

Entry name: MSGTYPE_REQ_useDEE — MSGTYPE_REQ is the message that will trigger the DEE.

Entry value format: DEEName | Order | KeyList

• DEEName: DEE name to be executed.
• Order: DEE execution sequence number. Use 1 if only one DEE is specified for the message.
• KeyList: List of the keys to be used at the DEE input/output dictionaries, separated by commas: InputKey,OutputKey,ResourceKey. Defaults to MessageReceived,MessageToSend,ResourceName.

<MSGTYPE_REQ>_ParamListToDEE#

Allows the specified parameters to be collected and passed to a DEE, on reception of the message specified in MSGTYPE_REQ.

Entry value format: DEEName | Order | ParameterList | TagList

• DEEName: DEE name to be executed.
• Order: DEE execution sequence number. Use 1 if only one DEE is specified for the message.
• ParameterList: List of parameter names to be collected. Separate multiple values with a comma.
• TagList: Name of the XML elements containing the parameters to be collected, separated by a comma.
  • For ITEM_OUT_REQ messages use CUSTOMS,CUSTOM.
  • For every other message use the name of the node you want to collect data from ex.: PARAMETERS,PARAMETER.

DEE Signature for ParamListToDEE Entries#

When using ParamListToDEE, the DEE receives the following Inputs:

• ParamList: Array containing the parameters specified in ParameterList inside elements TagList, together with any other attributes collected:

  [
    { "name": "Param1", "value": "ValueParam1" },
    { "name": "ParamN", "value": "ValueParamN" }
  ]
  

• ResourceName: IoT instance Resource name.

If needed, the attributes existing on the message header element can also be collected.

Use the key useHeaderAttributes with the following value syntax: DeeName | attribute1, attribute2, ..., attributeN. A new Input will be generated for each defined attribute in this key:

• attribute1: Value of attribute1 in message content.
• attribute2: Value of attribute2 in message content.
• (...)
• attributeN: value of attributeN in message content.

And, finally, the following Outputs should be returned:

• Result: DEE processing result. For a successful processing, the value must be true (Boolean) or "Success" (String).
• Message: In case of no success, this message is passed to the equipment using the XML tag error_text. If no message is specified, "Error collecting data" is used.

How It Works#

Calling Services#

• Only one service can be called per message type.
• The message content will be sent as an input to the Service call, can be defined in the IoTMetadataDefinition entry <MSGTYPE_REQ>_useService (KeyList -> inputKey).
• After the received message is processed a reply must be sent in JSON format, compatible with ASYS specification, in the output of the service call, the name of this output can be defined in the IoTMetadataDefinition entry <MSGTYPE_REQ>_useService (KeyList -> OutputKey).

Calling DEEs#

• One or more DEEs can be called by the specified order.
• If using ParamListToDEE:
  • After the received message is processed no message response is expected.
• If using useDEE:
  • After the received message is processed a reply must be sent in JSON format, compatible with ASYS specification, in the output of the service call, the name of this output can be defined in the IoTMetadataDefinition entry <MSGTYPE_REQ>_useDEE (KeyList -> OutputKey).
• If a DEE fails by throwing an error, the execution of the list is interrupted and the error message is returned to the equipment in the XML tag error_text, together with a state tag of value 0. If no error message is specified by the DEE's Message output:
  • Using ParamListToDEE, the default "Error collecting data" is used.
  • Using useDEE, "DEE returned a false Result value" is used.
• A DEE can fail either by throwing an error or by setting the key Result to false (any value other than true or "Success").

DEEs Retry logic#

There is a retry mechanism set for DEE calls where for the following errors we will try to execute the current DEE again:

• "The data for object (...) has changed since last viewed. Please refresh the object."
• "(...)was deadlocked on lock resources with another process and has been chosen as the deadlock victim"
• "The number of associated (...) does not match the number of UsedPositions"
• "Error: connect ECONNREFUSED "