Critical Manufacturing MES Integration

How to integrate Critical Manufacturing MES with Connectware, including Security Portal authentication, posting data collection results, polling business objects, and receiving workflow data.

This guide describes how to integrate Critical Manufacturing MES (CM MES) with Connectware. You configure a service commissioning file that sends shop floor data to CM MES through its REST API and receives data from MES workflows in return. A complete example file is available at the end of this guide.

Objectives

• Establishing an OAuth-authenticated connection between Connectware and the CM MES REST API through the Security Portal.

• Posting data collection results from the shop floor to CM MES.

• Polling a MES business object at a regular interval.

• Calling any CM MES service operation on demand.

• Receiving data from CM MES workflows in Connectware.

Prerequisites

To follow this guide, you will need the following:

• A running instance of Cybus Connectware.

• Access to a CM MES instance, including its hostname and the tenant name configured for the environment.

• A client ID and client secret registered in the Critical Manufacturing Security Portal for the OAuth 2.0 client credentials flow, or a long-term access token such as a Personal Access Token (PAT). The MES user behind the credentials needs the roles required for the services you call.

• Access to the REST API catalog of your CM MES installation, which contains the OpenAPI specification of every service. A public version is available in the CM MES REST API Reference.

• Access to the Admin UI with sufficient user permissions.

• Basic knowledge of MQTT and the Connectware services concept (for example, service commissioning files, connections, and endpoints).

Connectware and CM MES Integration

CM MES exposes all of its functionality as REST services under the /api path of the MES instance, following the pattern https://<mesHost>/api/<ServiceName>/<Operation>. For example, the DataCollection service lives under /api/DataCollection. Connectware communicates with these services through the HTTP/REST connector.

The CM MES REST API is remote-procedure style. Almost every operation is an HTTP POST request that takes a JSON input object and returns a JSON output object. A few lookup operations, such as GetObjectByName of the GenericService, are HTTP GET requests with query parameters. This shape determines which Connectware endpoint operation you use:

• write endpoints send POST requests and cover the vast majority of MES operations, both commands and queries.

• subscribe endpoints poll GET operations at a regular interval.

Authentication is handled by the Critical Manufacturing Security Portal, an OAuth 2.0 identity provider that is part of every MES installation. Connectware retrieves a bearer token with the OAuth 2.0 Client Credentials Grant and renews it automatically. For details on the flow, see How the Security Portal works in the Critical Manufacturing documentation.

The input and output objects of the MES services are versioned business object structures that differ between MES versions and installations. Take the exact request schema for each operation from the REST API catalog of your installation. To discover which service the MES UI calls for a given task, record the network traffic in your browser developer tools while performing the task and look for requests with the /api/ prefix.

The MQTT topics in this guide follow an ISA-95-style equipment hierarchy (<enterprise>/<site>/<area>/<line>/<cell>). The mappings subscribe with wildcards across all levels, so any machine in the hierarchy is picked up without changing the integration.

CM MES Connection Properties

The connection to CM MES requires the hostname, the tenant name, and the OAuth client credentials. We add them as parameters to the service commissioning file, so you can set them when you install the service.

Do not worry about copying the service commissioning file snippets together into one, the complete example file is available at the end of this guide.

• mesHost: The hostname of your CM MES instance, without the scheme. For example, mes.example.com.

• mesTenant: The tenant name configured on your MES environment. It is part of the Security Portal token URL.

• oauthClientId and oauthClientSecret: The client credentials registered in the Security Portal.

• mesObjectType and mesObjectName: The type and name of the MES business object that the polling example reads. Defaults to the Material named LOT-0001.

• pollInterval: The polling interval for MES object data in milliseconds.

• topicRoot: The root of the MQTT topic hierarchy. Defaults to enterprise.

parameters:
  mesHost:
    description: Hostname of your Critical Manufacturing MES instance
    type: string
    default: mes.example.com

  mesTenant:
    description: Tenant name configured on your MES environment
    type: string
    default: ExampleTenant

  oauthClientId:
    description: Client ID registered in the Security Portal
    type: string

  oauthClientSecret:
    description: Client secret registered in the Security Portal
    type: string

  mesObjectType:
    description: Object type of the MES business object to poll
    type: string
    default: Material

  mesObjectName:
    description: Name of the MES business object to poll
    type: string
    default: LOT-0001

  pollInterval:
    description: Polling interval for MES object data in milliseconds
    type: integer
    default: 60000

  topicRoot:
    description: Root of the MQTT topic hierarchy
    type: string
    default: enterprise

CM MES Connection

To connect to the CM MES REST API, we set up a Cybus::Connection resource that uses the HTTP/REST connector with the OAuth 2.0 client credentials flow. The token endpoint of the Security Portal is https://<mesHost>/SecurityPortal/api/tenant/<mesTenant>/oauth2/token. Connectware fetches the bearer token from this endpoint, sends it in the Authorization header of every request, and refreshes it before it expires. The endpoints that use this connection do not need any authentication configuration of their own.

resources:
  mesConnection:
    type: Cybus::Connection
    properties:
      protocol: Http
      connection:
        scheme: https
        host: !ref mesHost
        port: 443
        oauthClientCredentials:
          auth_url: !sub 'https://${mesHost}/SecurityPortal/api/tenant/${mesTenant}/oauth2/token'
          client_id: !ref oauthClientId
          client_secret: !ref oauthClientSecret

If you cannot register a client for the client credentials flow, you can authenticate with a long-term access token instead, for example a PAT created in the MES. In this case, replace the oauthClientCredentials property with a static headers property:

connection:
  scheme: https
  host: !ref mesHost
  port: 443
  headers:
    Authorization: !sub 'Bearer ${mesAccessToken}'

Connectware does not renew a static header token. Use a token with a sufficient lifetime and rotate it before it expires.

Posting Data Collection Results

The PostDataCollectionPoints operation of the DataCollection service writes collected values, such as measurements or test results, against a data collection instance in the MES.

We define a write endpoint for the operation path and a mapping that feeds it from the MQTT topic hierarchy. The HTTP/REST connector expects the request body in the body property of the message (see Publishing Data to REST Servers). The transform rule wraps the incoming payload accordingly, so machines can publish their data without knowing about this convention.

dataCollectionEndpoint:
  type: Cybus::Endpoint
  properties:
    protocol: Http
    connection: !ref mesConnection
    write:
      path: /api/DataCollection/PostDataCollectionPoints

dataCollectionMapping:
  type: Cybus::Mapping
  properties:
    mappings:
      - subscribe:
          topic: !sub '${topicRoot}/+site/+area/+line/+cell/data-collection'
        publish:
          endpoint: !ref dataCollectionEndpoint
        rules:
          - transform:
              expression: '{ "body": $ }'

Any message published to a matching topic, for example enterprise/hamburg/assembly/line-1/press-01/data-collection, now results in one POST request to the MES. The payload must match the PostDataCollectionPointsInput object of your MES version, which references the data collection instance and the points to add. The following structure is a placeholder that shows the general shape, take the exact schema and the required references from the REST API catalog of your installation:

{
  "DataCollectionInstance": {
    "...": "reference to the open data collection instance"
  },
  "DataCollectionPoints": [{ "Name": "TEMPERATURE", "Value": 42.1 }]
}

Polling MES Object Data

For reading MES data continuously, the GenericService provides the GET operation GetObjectByName, which loads any MES business object by its type and name. A subscribe endpoint polls this operation at a regular interval and a mapping publishes the response to an MQTT topic.

objectInfoEndpoint:
  type: Cybus::Endpoint
  properties:
    protocol: Http
    connection: !ref mesConnection
    subscribe:
      path: /api/GenericService/GetObjectByName
      interval: !ref pollInterval
      query:
        Type: !ref mesObjectType
        Name: !ref mesObjectName

objectInfoMapping:
  type: Cybus::Mapping
  properties:
    mappings:
      - subscribe:
          endpoint: !ref objectInfoEndpoint
        publish:
          topic: !sub '${topicRoot}/mes/object-info'

With the default parameters, Connectware requests the Material object named LOT-0001 every 60 seconds and publishes the response, wrapped in a timestamp and value structure, to enterprise/mes/object-info.

Calling Any MES Service Operation

CM MES exposes hundreds of operations across its services, and defining one endpoint per operation does not scale for integrations that call many of them. Since the HTTP/REST connector supports dynamic paths for publishing, one generic write endpoint on the /api base path covers them all. The message provides the operation path in the pathAppend property and the input object in the body property.

mesRequestEndpoint:
  type: Cybus::Endpoint
  properties:
    protocol: Http
    connection: !ref mesConnection
    write:
      path: /api

mesRequestMapping:
  type: Cybus::Mapping
  properties:
    mappings:
      - subscribe:
          topic: !sub '${topicRoot}/mes/request'
        publish:
          endpoint: !ref mesRequestEndpoint

For example, the following message published to enterprise/mes/request calls the LogObjectEvent operation of the GenericService. The MES response is published to the /res topic of the endpoint.

{
  "pathAppend": "/GenericService/LogObjectEvent",
  "body": {
    "...": "input object of the operation"
  }
}

Receiving Data from the MES

For the return direction, Connectware hosts an HTTP route using the Cybus::Server::Http and Cybus::Node::Http resources. A mapping publishes every request body that arrives on this route to an MQTT topic, where any other Connectware service can pick it up, for example to write an acknowledgment back to a PLC.

mesEventServer:
  type: Cybus::Server::Http
  properties:
    basePath: /cm-mes

mesEventRoute:
  type: Cybus::Node::Http
  properties:
    parent: !ref mesEventServer
    method: POST
    route: /events

mesEventMapping:
  type: Cybus::Mapping
  properties:
    mappings:
      - subscribe:
          endpoint: !ref mesEventRoute
        publish:
          topic: !sub '${topicRoot}/cm-mes/events'

The route is served under the /data prefix of your Connectware instance: https://<connectware>/data/cm-mes/events. On the MES side, any mechanism that sends HTTP POST requests can call this route, for example a Dynamic Execution Engine (DEE) action or the REST client driver of Connect IoT. Send the requests with the Content-Type: application/json header.

The calling user must be authenticated and needs write permission on the path data/cm-mes/events. For more information, see HTTP Server Permissions.

Verifying the Integration

1. Install the service and set the parameters with the values of your MES instance.

2. Check that the connection is in the Connected state on the service details page in the Admin UI.

3. Check that the polled object data arrives on enterprise/mes/object-info, for example with the Data Explorer. If the object does not exist in the MES, the response contains an error message from the MES instead of the object data.

4. Publish a test message to enterprise/hamburg/assembly/line-1/press-01/data-collection with a payload that matches your MES schema, and check in the MES UI that the data collection points have been posted.

5. The result of every HTTP request is published to the /res topic of the endpoint. Use the Data Explorer to inspect it. If the MES rejects a request, the message on the /res topic contains an error property with the HTTP status. A 401 status indicates wrong credentials, a 403 status indicates missing roles for the MES user.

Service Commissioning File Example

critical-manufacturing-mes-example.yml

4KB

Open

critical-manufacturing-mes-example.yml

---
# ----------------------------------------------------------------------------
# Service Commissioning File
# ----------------------------------------------------------------------------
# Copyright: Cybus GmbH
# Contact: [e-mail]
# ----------------------------------------------------------------------------
# Critical Manufacturing MES Integration (Example)
# ----------------------------------------------------------------------------

description: >
  Service commissioning file for the bidirectional integration between
  Connectware and Critical Manufacturing MES (Example)

metadata:
  name: Critical Manufacturing MES Integration
  provider: cybus
  homepage: https://www.cybus.io
  version: 1.0.0

parameters:
  mesHost:
    description: Hostname of your Critical Manufacturing MES instance
    type: string
    default: mes.example.com

  mesTenant:
    description: Tenant name configured on your MES environment
    type: string
    default: ExampleTenant

  oauthClientId:
    description: Client ID registered in the Security Portal
    type: string

  oauthClientSecret:
    description: Client secret registered in the Security Portal
    type: string

  mesObjectType:
    description: Object type of the MES business object to poll
    type: string
    default: Material

  mesObjectName:
    description: Name of the MES business object to poll
    type: string
    default: LOT-0001

  pollInterval:
    description: Polling interval for MES object data in milliseconds
    type: integer
    default: 60000

  topicRoot:
    description: Root of the MQTT topic hierarchy
    type: string
    default: enterprise

resources:
  # Connection to the MES REST API, authenticated with the Security Portal
  # OAuth 2.0 client credentials flow
  mesConnection:
    type: Cybus::Connection
    properties:
      protocol: Http
      connection:
        scheme: https
        host: !ref mesHost
        port: 443
        oauthClientCredentials:
          auth_url: !sub 'https://${mesHost}/SecurityPortal/api/tenant/${mesTenant}/oauth2/token'
          client_id: !ref oauthClientId
          client_secret: !ref oauthClientSecret

  # Posts data collection points to the MES, one request per message
  dataCollectionEndpoint:
    type: Cybus::Endpoint
    properties:
      protocol: Http
      connection: !ref mesConnection
      write:
        path: /api/DataCollection/PostDataCollectionPoints

  dataCollectionMapping:
    type: Cybus::Mapping
    properties:
      mappings:
        - subscribe:
            topic: !sub '${topicRoot}/+site/+area/+line/+cell/data-collection'
          publish:
            endpoint: !ref dataCollectionEndpoint
          rules:
            - transform:
                expression: '{ "body": $ }'

  # Polls one MES business object at a regular interval
  objectInfoEndpoint:
    type: Cybus::Endpoint
    properties:
      protocol: Http
      connection: !ref mesConnection
      subscribe:
        path: /api/GenericService/GetObjectByName
        interval: !ref pollInterval
        query:
          Type: !ref mesObjectType
          Name: !ref mesObjectName

  objectInfoMapping:
    type: Cybus::Mapping
    properties:
      mappings:
        - subscribe:
            endpoint: !ref objectInfoEndpoint
          publish:
            topic: !sub '${topicRoot}/mes/object-info'

  # Calls any MES REST operation on demand. The message provides the
  # operation path in "pathAppend" and the input object in "body".
  mesRequestEndpoint:
    type: Cybus::Endpoint
    properties:
      protocol: Http
      connection: !ref mesConnection
      write:
        path: /api

  mesRequestMapping:
    type: Cybus::Mapping
    properties:
      mappings:
        - subscribe:
            topic: !sub '${topicRoot}/mes/request'
          publish:
            endpoint: !ref mesRequestEndpoint

  # HTTP route that MES workflows can call to send data to the shop floor
  mesEventServer:
    type: Cybus::Server::Http
    properties:
      basePath: /cm-mes

  mesEventRoute:
    type: Cybus::Node::Http
    properties:
      parent: !ref mesEventServer
      method: POST
      route: /events

  mesEventMapping:
    type: Cybus::Mapping
    properties:
      mappings:
        - subscribe:
            endpoint: !ref mesEventRoute
          publish:
            topic: !sub '${topicRoot}/cm-mes/events'