---
pdfexport: true
alias: tutorials-connectiot-mes-interop-scenarios
timetoread: true
tutorial: full
module: Connect IoT (Equipment Integration)
description: "Enable and use the out-of-the-box MES and Connect IoT interoperability scenarios, from Resource configuration to the equipment-side workflows"
---

# Connect IoT - MES Interoperability Scenarios Tutorial

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](connectiot_configuration_basic.md) first and see [How to Create a Controller Instance](../how-to/howto_createautomationcontrollerinstance.md).
- Familiarity with Data Flow or Control Flow workflows. See the [Control Flow Configuration Tutorial](connectiot_configuration_controlflow.md) 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.

```mermaid
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 [[operation-guide-connectiotadministration]] for the interlocking timeout configuration.

```mermaid
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]
```

!!! note
    If a scenario is enabled but the Resource has no associated controller instance, the transaction does not fail. The MES appends a warning to the transaction feedback messages instead.

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

| Scenario | MES operation | Resource property | Trigger task | Reply task |
|----------|---------------|-------------------|--------------|------------|
| Resource setup | [[user-guide-begin-setup]] | Resource Setup Interlocking | [[user-guide-automation-task-mes-resourcebeginsetuprequest]] | [[user-guide-automation-task-mes-resourcebeginsetupreply]] |
| Material dispatch | [[user-guide-dispatch-material]] | Material Dispatch Interlocking | [[user-guide-automation-task-mes-materialdispatchrequest]] | [[user-guide-automation-task-mes-materialdispatchreply]] |
| Material track-in | [[user-guide-track-in-material]] | Material Track-In Interlocking | [[user-guide-automation-task-mes-materialtrackinrequest]] | [[user-guide-automation-task-mes-materialtrackinreply]] |
| Material track-out | [[user-guide-track-out-material]] | Material Track-Out Interlocking | [[user-guide-automation-task-mes-materialtrackoutrequest]] | [[user-guide-automation-task-mes-materialtrackoutreply]] |
| Container dock | [[user-guide-dock-container]] | Container Dock Interlocking | [[user-guide-automation-task-mes-containerdockrequest]] | [[user-guide-automation-task-mes-containerdockreply]] |
| Container undock | [[user-guide-undock-container]] | Container Undock Interlocking | [[user-guide-automation-task-mes-containerundockrequest]] | [[user-guide-automation-task-mes-containerundockreply]] |
| Recipe list | Get recipes at the equipment | Recipe List Support | [[user-guide-automation-task-mes-recipelistrequested]] | [[user-guide-automation-task-mes-recipelistreply]] |
| Recipe download | Download recipe from the equipment | Recipe Download Support | [[user-guide-automation-task-mes-recipebodyrequested]] | [[user-guide-automation-task-mes-recipebodyreply]] |
| Recipe upload | Upload recipes to the equipment | Automation Upload Support | [[user-guide-automation-task-mes-recipeuploadrequest]] | [[user-guide-automation-task-mes-recipeuploadreply]] |

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.

| Scenario | Requests MES sends | Outputs of the trigger task | What the reply must carry |
|----------|------------------------|-----------------------------|---------------------------|
| Resource setup | One per **Resource** of the operation | `resource` | Anything: any reply confirms the setup |
| Material dispatch, track-in, and track-out | One per **Material** of the operation, one after the other. For track-out, the **Resource** is the last processed **Resource** of the **Material** | `resource`, `material` | Anything: any reply confirms the operation |
| Container dock and undock | One per operation | `resource`, `container` | Anything: any reply confirms the operation |
| Recipe list | One each time the recipes at the equipment are requested | None besides `Success` | A list of recipe names, or of objects with a non-empty `Name` |
| Recipe download | One per recipe, with the recipe name at the equipment | `recipeName` | The recipe content in `body`, base64-encoded, and its file name in `filename` |
| Recipe upload | One per recipe and **Resource** | `recipeName`, `recipeIsBinary`, `recipeBody` | Anything confirms the upload; an `Error` reports it as failed |

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 [[operation-guide-connectiotadministration#interlocking-timeouts]].
- **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 [[tutorials-connectiot-talking-to-mes]].

## 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 [[user-guide-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**.

![Screenshot of the Automation step of the Edit Resource wizard showing the Enable Automation Scenarios property and the interlocking and recipe support properties.](../../../images/connectiot_mesinterop_resource_automation.png)

!!! note
    Recipe List Support, Recipe Download Support, and Automation Upload Support all require the Recipe Management Enabled property of the Resource.

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**.

!!! info
    The previous automation properties (Mode, Address, and the automation capabilities) are deprecated and grouped in the Deprecated section of the Automation step. Use the new properties for all new integrations.

## 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.

    ![On Material Dispatch Request task in the Data Flow designer, with the resource and material outputs and the Success and Error paths.](../../../images/connectiot_mesinterop_dispatch_request_task.png)

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.

    ![Send Material Dispatch Reply task in the Data Flow designer, with the reply and Activate inputs and the Success and Error paths.](../../../images/connectiot_mesinterop_dispatch_reply_task.png)

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:

![Data Flow workflow with the On Material Dispatch Request trigger connected through a Log Message placeholder task to the Send Material Dispatch Reply task.](../../../images/connectiot_mesinterop_dispatch_workflow.png)

!!! warning
    The reply task must run in the same workflow branch as the request it answers. The request and reply tasks share context through a structure called `zone`; a reply task activated outside the zone of the request emits an error instead of unblocking the MES. See [[user-guide-automation-zones]] for more information.

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.

![Settings of the On Material Dispatch Request task, showing the Auto Enable toggle, the mandatory Reply Timeout of 60,000 milliseconds, and the read-only request subject.](../../../images/connectiot_mesinterop_dispatch_request_settings.png)

## 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`.

    ![Control Flow workflow showing the When a Resource performs Material Dispatch trigger block, with the details panel showing the Auto Enable and Reply Timeout settings.](../../../images/connectiot_mesinterop_controlflow_trigger.png)

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 [[user-guide-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.