# 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. ![Receive Workflow](images/asys_receive_flow.png) ## 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: | Name | Description | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | `MSGTYPE_REQ_useService` | Specifies the Service to be called when a message of type `MSGTYPE_REQ` is received. | | `MSGTYPE_REQ_useDEE` | Specifies the DEE to be called when a message of type `MSGTYPE_REQ` is received, passing the full message to the DEE. | | `MSGTYPE_REQ_ParamListToDEE` | Specifies the DEE to be called when a message of type `MSGTYPE_REQ` is received, passing only the specified message parameters to the DEE. | ### _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`. ??? Example "ORDER_REQ_useService" | Resource | Name | Value | | ------------ | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | MES Resource | `ORDER_REQ_useService` | `Cmf.Custom.Preh.Orchestration.InputObjects.OrderReqInput, Cmf.Custom.Preh.Orchestration | api/Preh/OrderRequest | inpKey,outKey,resKey` | ### _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`. ??? Example "ORDER_REQ_useDEE" | Resource | Name | Value | | ------------ | ------------------ | ---------------------------------------------- | | MES Resource | `ORDER_REQ_useDEE` | `CustomIoTOrderReq | 1 | inpKey,outKey,resKey` | ### _ParamListToDEE Allows the specified parameters to be collected and passed to a DEE, on reception of the message specified in `MSGTYPE_REQ`. !!! Warning "Can only be used to collect data on XML elements with attribute `name`." **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`. ??? Example "AUTOMATIC_START_REQ_ParamListToDEE" To collect the parameter `SolderPaste` sent by an `AUTOMATIC_START_REQ` message and pass it to the DEE `CustomIoTSetPrinterSolderPaste`: | Resource | Name | Value | | ------------ | ------------------------------------ | ------------------------------------------------------------------------- | | MES Resource | `AUTOMATIC_START_REQ_ParamListToDEE` | `CustomIoTSetPrinterSolderPaste | 1 | SolderPaste | 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: ```json [ { "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 **_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 **_useService** (`KeyList -> OutputKey`). !!! warning "If the expected output key, defined in IoTMetadataDefinition, is not received as the output of the Service call an error will be thrown and sent as a response to the received request." ### 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 **_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 "` !!! info "When any of these errors is encountered the process will sleep for 100ms and then try again until a maximum of 4 times."