SAP MII Integration

How to integrate SAP Manufacturing Integration and Intelligence (SAP MII) with Connectware, including basic authentication, running MII transactions with shop floor data, and polling query templates.

This guide describes how to integrate SAP Manufacturing Integration and Intelligence (SAP MII) with Connectware. You configure a service commissioning file that sends shop floor data to a SAP MII transaction and reads data from SAP MII query templates over HTTP. A complete example file is available at the end of this guide.

Objectives

• Establishing a basic-authenticated HTTP connection between Connectware and the SAP MII server.

• Running a SAP MII transaction with shop floor data through the Runner servlet.

• Polling a SAP MII query template into the MQTT topic hierarchy.

• Running a query template on demand with dynamic parameters.

Prerequisites

To follow this guide, you will need the following:

• A running instance of Cybus Connectware.

• Access to a SAP MII installation, including a SAP NetWeaver user with the permissions to run the transaction and the query template.

• A transaction created in the SAP MII Workbench, and its full path in the form <project>/<folder>/<transaction>.

• A query template created in the SAP MII Workbench, and its full path.

• 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 SAP MII Integration

SAP MII runs on the SAP NetWeaver Application Server Java and exposes its runtime over HTTP below the /XMII root path. Connectware communicates with these interfaces through the HTTP/REST connector, which supports continuous polling, on-demand requests, and pushing data.

This guide uses the two interfaces that cover most integration scenarios:

• Runner servlet (/XMII/Runner): Runs one execution of a SAP MII transaction per request. The transaction is identified by the Transaction query parameter, and input parameters are passed as further query parameters or as the request body. Inside the transaction, you decide what happens with the data. For all parameters, see Transaction Calls Using URLs in the SAP MII documentation.

• Illuminator servlet (/XMII/Illuminator): Runs query templates and MII services. The Content-Type query parameter selects the output format, including text/json for JSON instead of the XML default. For the available services and output formats, see Services in the SAP MII documentation.

The JSON output format is only available on the Illuminator servlet. The Runner servlet responds with an XML document, which Connectware publishes as a string.

Both servlets authenticate the caller against the SAP NetWeaver user management with basic authentication. Basic authentication transports the credentials with every request, so use the https scheme to protect them in transit.

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

SAP MII Connection Properties

The connection to SAP MII requires the hostname and port of the SAP NetWeaver server, the user credentials, and the paths of the transaction and the query template. 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.

• sapMiiHost: The hostname of the SAP NetWeaver server that runs SAP MII, without the scheme. For example, sap-mii.example.com.

• sapMiiPort: The HTTPS port of the SAP NetWeaver instance. The port follows the pattern 5<instance number>01. For example, 50001 for instance 00.

• miiUsername and miiPassword: The credentials of a SAP NetWeaver user with the SAP MII permissions to run the transaction and the query template.

• transactionPath: The full path of the transaction to run, as shown in the SAP MII Workbench. For example, Default/ShopFloor/ProcessMachineData.

• queryTemplatePath: The full path of the query template to run. For example, Default/ShopFloor/ProductionOrders.

• pollInterval: The polling interval in milliseconds. Defaults to 60000.

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

parameters:
  sapMiiHost:
    description: Hostname of the SAP NetWeaver server that runs SAP MII
    type: string
    default: sap-mii.example.com

  sapMiiPort:
    description: HTTPS port of the SAP NetWeaver instance
    type: integer
    default: 50001

  miiUsername:
    description: Name of the SAP MII service user
    type: string

  miiPassword:
    description: Password of the SAP MII service user
    type: string

  transactionPath:
    description: Full path of the SAP MII transaction to run
    type: string
    default: Default/ShopFloor/ProcessMachineData

  queryTemplatePath:
    description: Full path of the SAP MII query template to run
    type: string
    default: Default/ShopFloor/ProductionOrders

  pollInterval:
    description: Polling interval for the query template in milliseconds
    type: integer
    default: 60000

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

SAP MII Connection

To connect to SAP MII, we set up a Cybus::Connection resource that uses the HTTP/REST connector with basic authentication. The prefix property applies the /XMII root path to all endpoints of this connection, so the endpoints only configure the servlet paths.

resources:
  sapMiiConnection:
    type: Cybus::Connection
    properties:
      protocol: Http
      connection:
        scheme: https
        host: !ref sapMiiHost
        port: !ref sapMiiPort
        prefix: /XMII
        auth:
          username: !ref miiUsername
          password: !ref miiPassword

For an overview of all connection properties, see HTTP Connection Properties.

Running a SAP MII Transaction with Shop Floor Data

To send shop floor data to SAP MII, we define a write endpoint for the Runner servlet and a mapping that feeds it from the MQTT topic hierarchy. The query property adds the static query parameters that every request carries:

• Transaction: The full path of the transaction to run.

• InputParameter: The name of the transaction input property that receives the body of the POST request. The transaction must define an input property with this name, for example a string property named IncomingData that the transaction parses as JSON.

• OutputParameter: The output properties to return in the response. The wildcard * returns all non-XML output properties.

You can pass fixed input values as additional query parameters. Any further name-value pair in the query property is assigned to the transaction input property of the same name.

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.

transactionRunnerEndpoint:
  type: Cybus::Endpoint
  properties:
    protocol: Http
    connection: !ref sapMiiConnection
    write:
      path: /Runner
      query:
        Transaction: !ref transactionPath
        InputParameter: IncomingData
        OutputParameter: '*'

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

Any message published to a matching topic, for example enterprise/hamburg/assembly/line-1/press-01/machine-data, now starts one execution of the transaction. The payload structure is up to you, the transaction receives it as the value of its input property:

{
  "machine": "PRESS-01",
  "temperature": 42.1,
  "cycleTime": 12.7
}

The Runner servlet responds with an XML document that contains the requested output properties. Connectware publishes the result to the /res topic of the endpoint (see Operation results).

Polling a SAP MII Query Template

To read data from SAP MII at a regular interval, we define an endpoint that polls the Illuminator servlet (see Subscribing to Data). The QueryTemplate query parameter identifies the query template, and Content-Type=text/json requests JSON output. Content-Type is a query parameter of the Illuminator servlet that selects the output format, not an HTTP header.

queryPollEndpoint:
  type: Cybus::Endpoint
  properties:
    protocol: Http
    connection: !ref sapMiiConnection
    subscribe:
      path: /Illuminator
      interval: !ref pollInterval
      query:
        QueryTemplate: !ref queryTemplatePath
        Content-Type: text/json

queryPollMapping:
  type: Cybus::Mapping
  properties:
    mappings:
      - subscribe:
          endpoint: !ref queryPollEndpoint
        publish:
          topic: !sub '${topicRoot}/sap-mii/production-orders'

The HTTP/REST connector wraps every response in a JSON structure with a timestamp and a value property (see Response Message Format). The value property contains the result document of the query template with its rowset structure. You can add a transform rule to the mapping if downstream consumers only need parts of it.

To fix query template parameters for every poll, add them to the query property as Param.1, Param.2, and so on. The numbered parameters override the values that are configured in the query template.

Running a Query Template on Demand

Polling is not always the right pattern, for example when a dashboard or an edge application needs current values with parameters that change per request. For this case, we define a read endpoint for the same query template (see Reading Data).

queryReadEndpoint:
  type: Cybus::Endpoint
  properties:
    protocol: Http
    connection: !ref sapMiiConnection
    read:
      path: /Illuminator
      query:
        QueryTemplate: !ref queryTemplatePath
        Content-Type: text/json

A message to the /req topic of the endpoint triggers one request, and the response is published to the /res topic. The message can carry dynamic query parameters that are merged with the configured query property, with the message parameters taking precedence. This way, one endpoint serves any parameter combination of the query template:

{
  "query": {
    "Param.1": "PRESS-01"
  }
}

Dynamic query parameters are available for read endpoints. Write endpoints instead forward the message body as the request body, which is why the transaction endpoint in this guide passes its per-message data as the POST body.

Verifying the Integration

1. Install the service and set the parameters to the values of your SAP MII installation.

2. Check that the connection is in the Connected state on the service details page in the Admin UI. The state reflects that the server is reachable. Wrong credentials do not prevent the connected state, they surface as 401 Unauthorized errors on the /res topics.

3. Open the Data Explorer and subscribe to enterprise/sap-mii/production-orders. After the polling interval has passed, the query template result appears.

4. Publish a test payload, for example the one shown in this guide, to enterprise/hamburg/assembly/line-1/press-01/machine-data with an MQTT client or the Admin UI.

5. Check the result on the /res topic of the transaction endpoint in the Data Explorer. On success, the message contains a result property with the XML response of the Runner servlet. If SAP MII rejects the request, the message contains an error property with the HTTP status.

6. In SAP MII, check the transaction execution in the transaction monitoring of the System Management menu.

7. Publish the dynamic query message shown in this guide to the /req topic of the read endpoint and check the response on its /res topic.

Service Commissioning File Example

sap-mii-example.yml

4KB

Open

sap-mii-example.yml

---
# ----------------------------------------------------------------------------
# Service Commissioning File
# ----------------------------------------------------------------------------
# Copyright: Cybus GmbH
# Contact: [e-mail]
# ----------------------------------------------------------------------------
# SAP MII Integration (Example)
# ----------------------------------------------------------------------------

description: >
  Service commissioning file for exchanging data between Connectware and
  SAP Manufacturing Integration and Intelligence (SAP MII) over HTTP (Example)

metadata:
  name: SAP MII Integration
  provider: cybus
  homepage: https://www.cybus.io
  version: 1.0.0

parameters:
  sapMiiHost:
    description: Hostname of the SAP NetWeaver server that runs SAP MII
    type: string
    default: sap-mii.example.com

  sapMiiPort:
    description: HTTPS port of the SAP NetWeaver instance
    type: integer
    default: 50001

  miiUsername:
    description: Name of the SAP MII service user
    type: string

  miiPassword:
    description: Password of the SAP MII service user
    type: string

  transactionPath:
    description: Full path of the SAP MII transaction to run
    type: string
    default: Default/ShopFloor/ProcessMachineData

  queryTemplatePath:
    description: Full path of the SAP MII query template to run
    type: string
    default: Default/ShopFloor/ProductionOrders

  pollInterval:
    description: Polling interval for the query template in milliseconds
    type: integer
    default: 60000

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

resources:
  # Connection to the SAP MII server using basic authentication
  sapMiiConnection:
    type: Cybus::Connection
    properties:
      protocol: Http
      connection:
        scheme: https
        host: !ref sapMiiHost
        port: !ref sapMiiPort
        # The SAP MII servlets are served below the /XMII root path
        prefix: /XMII
        auth:
          username: !ref miiUsername
          password: !ref miiPassword

  # Runs one execution of a SAP MII transaction per message
  transactionRunnerEndpoint:
    type: Cybus::Endpoint
    properties:
      protocol: Http
      connection: !ref sapMiiConnection
      write:
        path: /Runner
        query:
          Transaction: !ref transactionPath
          # Name of the transaction input property that receives the body
          # of the POST request
          InputParameter: IncomingData
          # Returns all non-XML output properties of the transaction
          OutputParameter: '*'

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

  # Polls a SAP MII query template at a regular interval
  queryPollEndpoint:
    type: Cybus::Endpoint
    properties:
      protocol: Http
      connection: !ref sapMiiConnection
      subscribe:
        path: /Illuminator
        interval: !ref pollInterval
        query:
          QueryTemplate: !ref queryTemplatePath
          # Content-Type is a query parameter of the Illuminator servlet
          # that selects the output format, not an HTTP header
          Content-Type: text/json

  queryPollMapping:
    type: Cybus::Mapping
    properties:
      mappings:
        - subscribe:
            endpoint: !ref queryPollEndpoint
          publish:
            topic: !sub '${topicRoot}/sap-mii/production-orders'

  # Runs the query template on demand via the /req topic of the endpoint,
  # for example with dynamic query template parameters
  queryReadEndpoint:
    type: Cybus::Endpoint
    properties:
      protocol: Http
      connection: !ref sapMiiConnection
      read:
        path: /Illuminator
        query:
          QueryTemplate: !ref queryTemplatePath
          Content-Type: text/json