Overview

The IIH Essentials Connector module facilitates a seamless integration of Industrial Information Hub (IH) Essentials into your Mendix application developed for Siemens Industrial Edge (IE) devices.

This connector serves as key component to implement your Industrial Edge use cases. IIH Essentials is a data service used to acquire, store, manage, and synchronize your IoT data on Industrial Edge. This connector communicates with IIH Essentials via its REST API.

Documentation

Introduction

The IIH Essentials Connector module facilitates a seamless integration of IIH Essentials into your Mendix application developed for Siemens Industrial Edge (IE) devices.

Typical usage cases

This connector serves as key component to implement your Industrial Edge use cases. IIH Essentials is a data service used to acquire, store, manage, and synchronize your IoT data on Industrial Edge. The connector allows your Mendix app to interact with this service via its REST API, so you can bring the data structures and data from IIH Essentials to your Mendix app or change them from your Mendix app.

This allows for a magnitude of use cases. For example:

• Dynamically configuring data structures in IIH according to logic defined in Mendix.
• Mendix IoT dashboards displaying data and aggregations, e.g. for monitoring temperatures in your production line.
• Analytics with business logic defined in Mendix, e.g. cycle time analysis.
• Writing data from your Mendix app to IIH Essentials.

Features and limitations

Currently, only operations for the following resources of IIH version 1.8.0 are available:

• Adapters
• Aspects
• Assets
• Calculate
• Data
• Variables

Due to the IIH Essentials API’s backwards compatibility, the operations can also be used for IIH Essentials 1.9.0 to 1.11.0. However, they do not support newly added attributes of those versions.

Prerequisites

• Prerequisites of Industrial Edge according to the Mendix on Edge documentation
• IIH Essentials version 1.8.0 or higher
• Optional but recommended: you have the Device API Connector or an own implementation in your Mendix project.

Dependencies

There are no hard dependencies on other modules in this connector.

However, this connector requires the Device API Connector if  the Mendix application using this connector and the IIH Essentials IE app are not deployed on the same Industrial Edge device.

In such a case, the operations require a valid token that can be retrieved from the IE Device API’s login endpoint (c.f. configuration). This is typically the case during development if you press “Run locally” in Studio Pro. The Mendix app is then deployed on your local Windows or iOS machine while IIH Essentials may run in a virtual testing environment or an Industrial Edge device in the same network.

Installation

Follow the instructions in Using Marketplace Content to import the IIH Essentials connector into your app.

Follow the same instructions to import the Device API Connector into your app in order to login to IIH running on an external device.

Configuration

After you install the connector, you can find it in the App Explorer under Marketplace modules, named IIHEssentialsConnector. The connector provides a domain model and several activities that you can use to connect your app to IIH Essentials. Each activity can be implemented by using it in a microflow.

To ensure that your app can connect to the IIH Essentials service deployed on a different device where your Mendix app is hosted, you must provide the API URL of IIH Essentials and a valid login token to the operation microflows. To get this information, follow the documentation of the Device API Connector to configure a device. 

Module Structure

This section provides an overview of the module's structure and its components.

Domain Model

The domain model within the IIH Essentials Connector module is fully non-persistent with no module roles and entity access rules. This design choice is made for the following reasons:

• Avoiding redundancy: By keeping the domain model non-persistent, it is ensured that IIH Essentials remains the single source of truth for your data and data structures. Persisting IIH objects in the Mendix database leads to redundancy which can quickly blow up your device storage. Further, it adds the need to keep both states in sync. By being non-persistent, the domain model serves as a lightweight representation of IIH. If your use case requires persisting IIH objects in the Mendix database regardless, add a copy of the respective entity of the connector in your implementation module and change the entity type to persistent.
• Permission management: Since this is a generic connector, its module roles and entity access rules cannot account for the magnitude of use cases requiring different security configurations. Hence, it is your responsibility as developer to configure the entity and microflow access according to your needs. To do so, create specializations of the entities in this connector in your implementation module or copies of it. If you only use the entities of this connector in microflows with “Apply entity access” set to ‘No’ and not on pages, you can use the connectors entities directly.

_Docs Folder

The _Docs folder contains information about the IIH Essentials Connector module. Besides stating the connector’s version number, it includes a READ_ME document providing an overview of the module, its features, usage guidelines, and any other relevant information for developers and stakeholders.

_USE_ME Folder

The _USE_ME folder is dedicated to everything needed for the implementation of the IIH Essentials Connector module. Hence, it includes the microflows for all available REST operations currently supported by the connector. It also includes an “ExampleImplementations” folder which contains examples for commonly used logic, e.g. to get the Variables for a given Aspect ID.

Private Folder

The Private folder contains internal logic required by the connector to implement the operation microflows. The folder includes core functionalities, and other sensitive logic essential for the operation of the IIH Essentials Connector module. Developers should refrain from making changes to files within this folder to maintain the stability and integrity of the module.

Using the REST Operation Microflows

Every operation implemented by the connector is exposed as a microflow action. This means that they are available in the developer’s Toolbox, alphabetically ordered by resource. From here, drag ‘n drop them into your implementation microflows. Alternatively, you can use the App Explorer view of this module (_USE_ME > Operations).

Every operation has the following parameters:

• IIHEssentialsURL_RequiredIfExternal: If the Mendix app and the called IIH Essentials service are installed on the same IE device, you can leave this empty. The default docker container URL (http://edgeappdataservice:4203) of the service will be used by the operation. If the Mendix app calls an IIH Essentials service installed on a different IE device than the Mendix app is deployed, you need to pass ‘http:///iih-essentials’. Devices can be managed using the Mendix Device API Connector. Using this connector, configure a device on which IIH Essentials is installed, retrieve in from DB and pass the attribute of DeviceAPIConnector.Device[IIHEssentialsURL] to this microflow.
• DecryptedDeviceToken_RequiredIfExternal: If the Mendix app and the called IIH Essentials service are installed on the same IE device, you can leave this empty. If the Mendix app calls an IIH Essentials service installed on a different IE device, a login token needs to be retrieved from the DeviceAPI login endpoint. This is implemented by the Mendix Device API Connector's operation IEDeviceAPIConnector.POST_v2_Device_Login. Using this connector, configure a device on which IIH Essentials is installed, retrieve in from DB, call IEDeviceAPIConnector.POST_v2_Device_Login, and pass the (decrypted) attribute of DeviceAPIConnector.Device[Token] to this microflow. Ensure the Token is decrypted by calling IEDeviceAPIConnector.Device_DecryptToken.
• Required or optional query parameters: Depending on the REST operation, there are required (marked by QueryParamName_Required) or optional query parameters (marked by QueryParamName_Optional) that may be passed to the microflow. For more about the individual operations and their parameters, please consult the IIH Essentials API documentation or check the documentation fields of these microflows.

Note that you cannot return the objects returned from these microflows directly to the user interface. I.e. you cannot directly use them on your pages because the module has no module roles and not entity access rules required to display them on pages. The reasons for this are explained above under Domain Model. To display the data received from IIH Essentials on your pages, copy the contents of the IIHEssentialsConnector entities to your own entities according to your needs.

Persisting data

Make an informed decision about what needs to be persisted in your Mendix app as this will introduce redundancy and the need to keep the data in IIH and the Mendix database in sync.

If you only need to display data structures and data from IIH, it is advised to keep your domain model non-persistent. However, if you want to enrich e.g. Aspects and Variables with other custom attributes according to your use case, introducing persistent entities for those may be a valid use case. This comes with the added benefit that you can use Mendix’ out-of-the-box features for retrieving and filtering data retrieved from the database.

Make sure to add logic to keep both states, in the Mendix DB and IIH, in sync. For example, if a new variable is added in IIH, this change should be reflected in your Mendix DB and vice versa.

Error Handling

The Connector module is capable of mapping errors returned by the REST service to the Mendix domain model. There are two different types of errors: the HttpError and the BulkError.

HttpError

These errors are the most common in the REST Service, meaning they can occur in most operations. For example, the POST Adapter operation returns an error with Http status code 400 (bad request) if a POST request is made with an empty body (c.f. screenshot 9 swagger documentation).

It is a best practice for the implementing developer to validate the inputs of the operation microflows to avoid such bad requests.

It is also a best practice to always check if such an error has occurred after calling each operation and to handle it according to your needs, e.g. by displaying the custom error message back to the user. To do so, retrieve the HttpError from the IIHMessage object (and its specializations AssetMessage, DataMessage etc.) and display the attributes in a client message. Check the microflow “IIHEssentialsConnector.Aspect_GetData” for an example.

BulkError

BulkErrors can occur in Bulk operations that allow the user to POST, PUT or DELETE multiple objects at once. These errors work differently than HttpErrors.

Imagine a user updating 2 Assets using the Assets Bulk Update operation, and for one of these Assets the id could not be found. In that case, a BulkError will be returned for that specific Asset. For the other Asset however, the operation will be successful. Therefore, a status 200 will be the overall result of the operation (c.f. screenshot swagger documentation)

Here, the errors are returned in an array within the rest of the response. Therefore, it is recommended to always check for BulkErrors after calling a bulk operation in your implementation microflow. Check the microflow “IIHEssentialsConnector. VariableList_BulkUpdate_CheckForBulkErrors” for an example.