> For the complete documentation index, see [llms.txt](https://docs.cybus.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cybus.io/2-4-2/guides/system-connectivity/mes-erp-business-systems/sap-mii-integration.md). # SAP MII Integration 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 `//`. * A query template created in the SAP MII Workbench, and its full path. * Access to the [Admin UI](/2-4-2/access/admin-ui.md) with sufficient [user permissions](/2-4-2/access/user-management.md). * Basic knowledge of MQTT and the Connectware [services](/2-4-2/data-flows/services.md) concept (for example, [service commissioning files](/2-4-2/data-flows/service-commissioning-files.md), [connections](/2-4-2/data-flows/service-commissioning-files/resources/cybus-connection.md), and [endpoints](/2-4-2/data-flows/service-commissioning-files/resources/cybus-endpoint.md)). ## 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](/2-4-2/connectors/enterprise-connectors/http-rest.md), 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](https://help.sap.com/saphelp_mii150sp03/helpdata/en/4c/c8e2a88e9b60c5e10000000a15822d/content.htm) 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](https://help.sap.com/doc/saphelp_mii140sp04/14.0.4/en-US/92/af0bee70604f258024a646b560d3c5/content.htm) 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 (`////`). 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 `501`. 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`. {% code lineNumbers="true" %} ```yaml 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 ``` {% endcode %} ### 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. {% code lineNumbers="true" %} ```yaml 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 ``` {% endcode %} For an overview of all connection properties, see [HTTP Connection Properties](/2-4-2/connectors/enterprise-connectors/http-rest/httpconnection.md). ### 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](/2-4-2/connectors/enterprise-connectors/http-rest.md#publishing-data-to-rest-servers)). The `transform` rule wraps the incoming payload accordingly, so machines can publish their data without knowing about this convention. {% code lineNumbers="true" %} ```yaml 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": $ }' ``` {% endcode %} 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: {% code lineNumbers="true" %} ```json { "machine": "PRESS-01", "temperature": 42.1, "cycleTime": 12.7 } ``` {% endcode %} 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](/2-4-2/data-flows/service-commissioning-files/resources/cybus-endpoint.md#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](/2-4-2/connectors/enterprise-connectors/http-rest.md#subscribing-to-data-continuous-polling)). 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. {% code lineNumbers="true" %} ```yaml 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' ``` {% endcode %} The HTTP/REST connector wraps every response in a JSON structure with a `timestamp` and a `value` property (see [Response Message Format](/2-4-2/connectors/enterprise-connectors/http-rest.md#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](/2-4-2/connectors/enterprise-connectors/http-rest.md#reading-data-event-driven-polling)). {% code lineNumbers="true" %} ```yaml queryReadEndpoint: type: Cybus::Endpoint properties: protocol: Http connection: !ref sapMiiConnection read: path: /Illuminator query: QueryTemplate: !ref queryTemplatePath Content-Type: text/json ``` {% endcode %} 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](/2-4-2/connectors/enterprise-connectors/http-rest.md#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: {% code lineNumbers="true" %} ```json { "query": { "Param.1": "PRESS-01" } } ``` {% endcode %} 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](/2-4-2/monitoring/data-explorer.md) 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 {% file src="/files/PaTcjhxMkLf6lgdiCCID" %} {% code title="sap-mii-example.yml" lineNumbers="true" expandable="true" %} ```yaml --- # ---------------------------------------------------------------------------- # Service Commissioning File # ---------------------------------------------------------------------------- # Copyright: Cybus GmbH # Contact: support@cybus.io # ---------------------------------------------------------------------------- # 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 ``` {% endcode %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.cybus.io/2-4-2/guides/system-connectivity/mes-erp-business-systems/sap-mii-integration.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.