Connect IoT - MES Interoperability Scenarios Tutorial#

Estimated time to read: 13 minutes

Critical Manufacturing MES provides a set of out-of-the-box interoperability scenarios between the MES and Connect IoT. When a scenario is enabled on a Resource, the corresponding MES transaction sends a request to the Automation Controller instance associated with the Resource and waits for the equipment confirmation before completing. This request and reply exchange is called interlocking.

The available scenarios are:

• Resource setup - the begin setup transaction waits for the equipment confirmation.
• Material dispatch, track-in, and track-out - the material transactions wait for the equipment confirmation.
• Container dock and undock - the container transactions wait for the equipment confirmation.
• Recipe list, download, and upload - the MES lists the recipes at the equipment, downloads recipes from the equipment, and uploads recipes to the equipment.

This tutorial shows how to enable the scenarios on a Resource and how to build the equipment-side workflows that answer the MES requests. The material dispatch scenario is used as the working example; all other scenarios follow the same pattern.

Prerequisites#

This tutorial assumes a working Connect IoT setup:

• An Automation Controller with a controller instance associated with the Resource used in the scenarios. If you are not familiar with these entities, complete the Basic Configuration Tutorial first and see How to Create a Controller Instance.
• Familiarity with Data Flow or Control Flow workflows. See the Control Flow Configuration Tutorial for the Control Flow approach.

How the Scenarios Work#

The diagram below shows the interlocking exchange for the material dispatch scenario. The same sequence applies to all scenarios, only the transaction and the tasks change.

sequenceDiagram
    actor Operator
    participant MES
    participant Controller as Controller Instance
    participant Equipment
    Operator->>MES: Perform dispatch
    MES->>MES: Check the Resource automation properties
    MES->>Controller: Material Dispatch request
    activate MES
    Note over MES: Transaction blocked, waiting for the reply
    Controller->>Equipment: Equipment-side handling
    Equipment-->>Controller: Confirmation
    Controller-->>MES: Material Dispatch reply
    deactivate MES
    MES-->>Operator: Dispatch completed

Each MES transaction covered by a scenario checks the automation properties of the Resource involved in the operation:

1. If Enable Automation Scenarios is false, or the property of the specific scenario is not enabled, the transaction executes as usual and no request is sent.
2. If the scenario is enabled, the MES retrieves the Automation Controller instance of the Resource or, when defined, of its Automation Scenarios Owner Entity.
3. The MES sends the request to the controller instance and stays blocked waiting for the reply.
4. The workflow handles the request on the equipment side and sends the reply back.
5. If the reply carries an exception, or no reply arrives within the reply timeout, the MES transaction fails. See Connect IoT Administration for the interlocking timeout configuration.

flowchart TD
    A[MES transaction starts] --> B{Enable Automation Scenarios}
    B -- disabled --> F[Transaction executes without a request]
    B -- enabled --> C{Scenario property}
    C -- disabled --> F
    C -- enabled --> D{Controller instance associated}
    D -- no --> W[Warning appended to the feedback messages] --> F
    D -- yes --> E[Request sent, transaction waits for the reply]
    E --> G{Reply arrives within the timeout and without exception}
    G -- yes --> H[Transaction completes]
    G -- no --> I[Transaction fails]

Each scenario pairs an MES operation with a trigger task and, in Data Flow workflows, a reply task:

Table: Out-of-the-box MES interoperability scenarios

The setup, material, and container scenarios interlock an MES transaction: the transaction waits for the equipment confirmation. The recipe scenarios exchange recipe data instead: the MES requests the recipe list, a recipe body, or delivers an uploaded recipe, and the workflow replies with the data or the confirmation.

What MES Sends and Expects#

Each setup, material, and container scenario is a system DEE action that runs in the Post step of its MES service, for example MaterialManagement.MaterialManagementOrchestration.TrackInMaterials.Post for track-in. MES sends the request after the service has done its work, and the service call ends only when the reply arrives or the timeout passes.

Table: What each scenario sends and expects

For the setup, material, and container scenarios:

• Any reply confirms the operation. MES does not read the content, so {}, false, and {"accepted": false} all confirm it.
• An error refuses the operation with a reason. In Data Flow, link an Error into the reply input of the reply task, for example the Error output of the task that checks the equipment. In Control Flow, an error that nothing catches in the handler branch, for example one thrown by a Code task, has the same effect. The workflow sends {"__cmf_type__": "Error", "message": "<message>"}, and MES fails the operation with that message, which the operator sees. An error with an empty message confirms the operation.
• A missing reply fails the operation. When the Reply Timeout of the trigger task passes first, the workflow answers with the error Request for '<subject>' timed out while waiting for a reply!, and MES fails the operation with that message. When the MES timeout passes first, or the instance is not running and nothing answers, MES fails the operation with its own timeout message. See Connect IoT Administration.
• Each request has its own timeout. MES sends the requests of one operation one after the other, so a track-in of 25 Materials can wait up to 25 times the timeout.
• One refused request undoes the whole operation. MES runs each service call in one transaction, so when one request fails, the operation is rolled back for every Material, including those whose requests the workflow already confirmed. The equipment has already received those requests, so do not let a confirmation start work that a later refusal cannot undo.
• Other entry points send the same requests. The services ComplexTrackInMaterials and ComplexDispatchAndTrackInMaterials run TrackInMaterials, and ComplexDispatchAndTrackInMaterials also runs DispatchMaterials. A Dispatch and Track-In therefore sends the requests of both the dispatch and the track-in scenarios.

For the recipe scenarios:

• Recipe list - link an array to the reply task. The trigger turns each recipe name into {"Name": "<name>"}. A text is sent as one item without a name, and an item without a name fails the request.
• Recipe download - MES decodes body from base64. A buffer is encoded for you; a text must already be base64-encoded. In Control Flow, return an object with body and filename.
• Recipe upload - for any reply except an error, MES records the upload on the recipe of the Resource, with its last upload version and date. An Error linked into Failure Reason adds its message to the feedback of the upload, and a request without a reply adds a timeout message. The upload operation itself does not fail.
• When no reply arrives for a recipe list or a recipe download, MES fails the request with Failed to get recipe list. No reply to get recipe list request. or Failed to get recipe body. No reply to get recipe body request.

To keep MES running while the equipment or its instance is down, set the property of the scenario to false on the Resource. The transaction then runs without a request until you enable the property again.

For how each designer turns a value into a reply, see Connect IoT - Talking to MES Tutorial.

Enable the Scenarios on the Resource#

The scenarios are configured on the Automation step of the Resource wizard. For the full description of the automation properties, see Create Resource.

1. Go to Business Data > Resource and select the Resource to integrate.
2. Select Edit.
3. Go to the Automation step.
4. Set Enable Automation Scenarios to true.
5. Enable the properties of the scenarios that the equipment supports. For this tutorial, enable Material Dispatch Interlocking.
6. Select Save.

If the Automation Controller instance that handles the requests belongs to another entity, for example an Area that groups several Resources, define the Automation Scenario Owner Entity Type and the Automation Scenarios Owner Entity properties. The requests are then handled by the controller instance of that entity instead of the controller instance of the Resource.

Build the Equipment-Side Workflow (Data Flow)#

With the scenario enabled, the MES blocks the dispatch transaction until the workflow replies. Build a workflow that receives the request, performs the equipment-side handling, and sends the reply.

1. Open the Automation Controller associated with the Resource and create a new Data Flow workflow.

2. Add the On Material Dispatch Request task, available in the System / MES category, under Triggers. This task emits the resource and the material involved in the operation when a request arrives.

   

3. Connect the task outputs to the logic that prepares the equipment, for example writing the material identifier to a device variable and waiting for an acknowledgment.

4. Add the Send Material Dispatch Reply task, available in the System / MES category, under Actions, and activate it when the equipment-side handling completes.

   

5. Deploy the workflow changes and start the Automation Manager.

The resulting workflow follows this shape, with a Log Message task standing in for the equipment-side logic:

The trigger task has a Reply Timeout setting, with a default value of 60000 milliseconds. If the workflow does not reply within this time, the trigger emits Error and the MES transaction fails. Adjust the timeout to the time the equipment needs to confirm the operation.

Build the Equipment-Side Workflow (Control Flow)#

In a Control Flow workflow, the request and reply pair is represented by a single Start trigger, named When a Resource performs Material Dispatch for the dispatch scenario. The result of the handler branch is sent back to the MES as the reply, so no reply task is needed.

1. Open the Automation Controller and create a new Control Flow workflow.

2. Add a Start trigger and select When a Resource performs Material Dispatch.

   

3. Implement the handler with the equipment-side logic. When the handler finishes, the reply is sent automatically.

Test the Scenario#

1. Go to a Material that can be dispatched to the integrated Resource and perform Dispatch Material.
2. Observe the running Automation Manager. The workflow receives the request, executes the equipment-side logic, and sends the reply.
3. The dispatch transaction completes in the MES after the reply arrives.

To confirm the interlocking behavior, stop the Automation Manager and dispatch another Material. The transaction stays blocked and fails when the reply timeout expires, showing that the MES only completes the operation with the equipment confirmation.

Next Steps#

• Enable the remaining scenarios that the equipment supports and add the corresponding trigger and reply tasks to the workflow. All scenarios follow the pattern shown in this tutorial.
• See the reference pages listed in the scenarios table for the inputs, outputs, and settings of each task.