Skip to content

Developing Mendix Apps for Insights Hub

This non-exhaustive list gives you an overview of important aspects and limitations to be considered for successfully developing a Mendix app to be integrated into Insights Hub. For information about how to deploy Mendix apps to Insights Hub, refer to the step-by-step instructions.

App name

In contrast to Mendix, Insights Hub imposes multiple restrictions on app names. Consider the following constraints when naming your Mendix app to ensure consistency with names in Insights Hub and Mendix.

  • Contains only lowercase alphanumeric characters and special characters -, _ and . are not allowed
  • Starts with a letter
  • Length does not exceed 20 characters
  • Is unique within your tenant

Authorizing Industrial IoT REST Calls

REST calls to Industrial IoT APIs require an access token to be sent with the request. Create a workflow using the Access token connector provided in the Single Sign-On module for these calls, which includes the following items:

  • A split after the Access token item that leads to abort the workflow properly if the token is empty.
  • Deletion of the access token after receiving the response to the REST call. Otherwise, the complete token is transferred to the user's browser which should be avoided.

The following diagram shows an example workflow:

Access Token Workflow

For more information on how to perform REST calls, refer the video tutorial.

Perform Rest Calls in Mendix

Authorizing Industrial IoT REST Calls from within 'Scheduled Events'

The Access token connector cannot be used for calling any Industrial IoT API in a microflow which is executed without a user context. For example, called from a scheduled event. Therefore, the MindSphereSingleSignOn module offers a microflow DS_GetAccessTokenForScheduledEvents that returns a Token for a given Tenant.

The following diagram shows the flow:

DS_GetAccessTokenForScheduledEvents

The microflow uses the Application Credentials functionality to fetch a token and uses different environment variables depending on the location where the app is running. The app could be running in any of the following locations:

  • Local: The microflow uses the Application Credentials that you entered at startup to fetch a token. See also Application Credentials.

  • Developer Tenant: The following Cloud Foundry environment variables must be set for the app:

Developer Tenant
MDSP_KEY_STORE_CLIENT_ID Enable Application Credentials in Developer Cockpit for your app and use the Client ID
MDSP_KEY_STORE_CLIENT_SECRET Enable Application Credentials in Developer Cockpit for your app and use the Client Secret
MDSP_OS_VM_APP_NAME Enter the name of your app in Developer Cockpit
MDSP_OS_VM_APP_VERSION Enter the version of your app in Developer Cockpit
  • Operator Tenant: The following environment variables must be available for the app and some of them are set automatically.
Operator Tenant
MDSP_KEY_STORE_CLIENT_ID Created automatically on an Operator Tenant when Application Credentials are enabled for the app
MDSP_KEY_STORE_CLIENT_SECRET Created automatically on an Operator Tenant when Application Credentials are enabled for the app
MDSP_OS_VM_APP_NAME Name of your app
MDSP_OS_VM_APP_VERSION Version of your app

Use the returned Token in your REST calls to Industrial IoT.

Info

Do not delete the Token after usage. The Token is not transferred to the client but is cached in MindSphereSingleSignOn module.

The following example shows how to use the microflow DS_GetAccessTokenForScheduledEvents. The sample retrieves a list of all Tenants from the database and fetches a token for each tenant. With the token, you can proceed with your custom application logic.

Hint

Do not create a Tenant object by yourself as this is done automatically during login.

DS_GetAccessTokenForScheduledEvents

Cloud Foundry Stacks

Make sure to always use the latest available Cloud Foundry stack available in Insights Hub. Apps pushed to Insights Hub before the end of April 2019 may have used the stack cflinuxfs2 and must be migrated.

To check the stack utilized by your application, use cf app {app_name} command.

Local Testing

When testing your app locally, i.e. outside the Industrial IoT environment, you do not automatically have a valid access token for accessing Industrial IoT APIs. For this use case, the Single Sign-On module provides the Local Development folder.

Constants

Commit Changes

If you are working on a project hosted on the Mendix TeamServer, you need to commit your changes first before creating the deployment package. This is due to the fact that Mendix will always create the deployment package from the version on the TeamServer. Your changes will be included only if you have committed your local changes to the server.

Credentials

When running your app locally, your credentials cannot be obtained via SSO. Instead, you are logged in as MxAdmin and asked to manually enter credentials via a login screen. The Single Sign-On module can be configured to use either application or service credentials.

Application Credentials

If the Single Sign-On module is configured to use application credentials, the following login screen is opened when running your app locally:

Login Screen Application Credentials

The Client ID and Client Secret are the aforementioned application credentials which are issued using Developer Cockpit as follows:

  1. Register the application and make sure the application name equals the constant CockpitApplicationName.
  2. Open "Developer Cockpit" from Launchpad.
  3. Navigate to the "App Credentials" page in the "Authorization Management" tab.
  4. Select the required app and app version.
  5. Click "Issue access" to obtain a token.

    Issue Access

  6. Select the access level and click "Submit".

    Access Level

  7. Make a note of the "Client ID" and "Client Secret".

    Credentials

Service Credentials

Info

It is recommended to use application credentials, if possible.

If application credentials are not available, you can configure the Single-Sign On module to use service credentials as a backup. In that case, the following login screen is opened when running your app locally:

Login Screen Service Credentials

The "Credentials ID" and "Password" are the aforementioned service credentials which can be requested via a service request to the Global Technical Access Center GTAC, refer to here.

Configuration

The following constants need to be set in the Local Development folder:

Constant Description
AskForCredentialsOnStartUp If set to TRUE, the user is presented with a login screen to enter the application credentials before the app starts up. If set to FALSE, this login screen appears the first time the SSO module attempts to retrieve an access token for Industrial IoT API calls.
CockpitApplicationVersion Specifies the version of the Mendix app as registered in Developer Cockpit. The application credentials entered in the login screen are only accepted if they have been generated for this version.
CredentialsType If set to TRUE, a login screen for entering application credentials will be opened to request a Industrial IoT token. Otherwise, a login screen for entering service credentials will be openend.
Default: TRUE
EnableLocalMindSphereApiReverseProxy Enables a reverse proxy for Industrial IoT API calls by adding a new endpoint /api/** to the app. This endpoint adds a Industrial IoT token to direct calls to Industrial IoT APIs which are not part of a microflow, but inside JavaScript code, e.g. when using the OS Bar.
HostTenant Specifies the name of the tenant where the app is registered and the service credentials have been issued.
UserTenant Specifies the name of the tenant who uses the app. If the app is registered on a developer tenant, this must be the same as above. If the app is registered on an operator tenant, you can enter a different tenant who has been granted access to the application to test multi-tenancy.

User Roles

Do not use the demo users when testing different roles in your app. This does not populate the tenant and role information correctly. Instead, allocate the role to MxAdmin, restart and log in again.

Do not create local users for your app as these cannot be properly mapped to the scopes.

Corporate Proxy

For corporate web proxy, the following settings must be applied in Mendix Studio Pro in order to communicate with Insights Hub during local development.

Proxy settings

Contact your local IT-department for the proxyHost and proxyPort values.

Proxy settings for version control used in Mendix Studio Pro

For more information about the version control used in Mendix Studio Pro, see Using Version Control in Mendix Studio Pro. Depending on your local development, you have to configure your version control client to use a proxy as well. This might be necessary if you have to solve a merge conflict manually.

Mendix App Licensing

Mendix applies a licensing model when deploying apps. By default, apps are treated as Free App, which imposes the restrictions listed in the Mendix Cloud documentation. Note that some restrictions only apply to apps deployed to the Mendix Cloud. The most important restrictions for apps deployed to Insights Hub via Cloud Foundry are:

  • The app restarts after 1-2 hours.

Enable continuous operation (i.e., without sleep mode) of your app on operator tenants using the subscription secret. The subscription secret must be added to the Cloud Foundry environment variables during app deployment via the following commands:

cf set-env {app_name} LICENSE_ID {UUID}
cf set-env {app_name} LICENSE_KEY {license_key}

For details on how to deploy an application for productive use on an operator tenant refer to the section "Manual deployment of an application" in the Operator Cockpit manual.

Mendix Password Policy

When a new user is identified during SSO, the SSO process generates a random password of a fixed length for the user. The password policy is set up to accept these passwords in the Insights Hub starter and example apps and should not be changed. If you are developing your app from scratch, refer to the Mendix documentation about Project Security to set up an appropriate password policy.

Mendix Password Policy

Insights Hub Icons

The Insights Hub Theme Pack provides icons and icon font for use in your app. The icons are automatically listed in the "Select Icon" dialogue and can be identified by their Module origin MindSphere_UI_Resources:

Insights Hub Icons

The Insights Hub icon font can be used on Mendix UI elements where a CSS class can be assigned, e.g. buttons, text, menus. Use this font as follows:

  1. Open the properties dialogue by double-clicking on the UI element.
  2. Select (none) in the "Icon" properties.
  3. Add the following definition to the "Class" property:

    iconMdsp {icon_name}
    

Insights Hub Icon Font

Multi-Tenancy

Insights Hub apps are usually designed to be multi-tenant compatible, meaning that a single instance of the app serves multiple tenants. Access to tenant specific data is controlled by Identity and Access Management.

Access Control by Industrial IoT Gateway

An authorization HTTP header is passed in every Industrial IoT API call. The Industrial IoT Gateway verifies that the user has permission to obtain the requested data.

Control within a Mendix App

Mendix apps support persistent entities which can be accessed by all users (subject to access granted by their user role). Thus, an additional access control is required to make Mendix apps compatible with the multi-tenant concept. The following instructions explain how to use the tenant name provided by the Single Sign-On module to enable multi-tenancy in Mendix apps.

  1. Make all persistent entities which have a TenantId attribute a specialization of the MindSphereSingleSignOn.TenantObject entity.
    This ensures that they are associated with the user's tenant.
  2. Every action on this object must have the following XPath constraint:
    [MindSphereSingleSignOn.TenantObject_Tenant/MindSphereSingleSignOn.Tenant/MindSphereSingleSignOn.MindSphereAccount_Tenant='[%CurrentUser%]']
    This ensures that the user can only access tenant specific entities with their TenantId.

Tip

For consistency, it is recommended to always access persistent entities with a TenantId attribute using a sub-microflow which contains the XPath constraint. This enforces multi-tenant security.

Info

Currently, it is not possible to apply these access restrictions automatically.
They are only required for persistent entities which have a TenantId attribute.

Example

You have some limits which are set for the user’s tenant to be applied to a time series. You then want to get a list of all these so that you can display the values to the user.

  1. Create the domain model with the LimitConfig entity being a specialization of MindSphereSingleSignOn.TenantObject. create domain model
  2. Write a sub-microflow which returns a list of all limits.
  3. Apply the XPath constraint to the Retrieve Objects action of the microflow. access token
  4. When you want to retrieve the list of limits, call this microflow instead of using the retrieve objects action. This will ensure that tenant-based security is applied.

Roles and Scopes

Both Mendix and Insights Hub use roles for managing access permissions of application users. This requires a mapping of Mendix user roles to Insights Hub application scopes, which is implemented in the Single Sign-On module. It reads the user token provided with every HTTP request, extracts the application scopes and maps them to Mendix user roles to log into the app. This mapping is defined as a case-insensitive comparison of the names of Insights Hub application scopes and Mendix user roles. For example, a Insights Hub application scope {app_name}.customScope1 is mapped to the Mendix roles CUSTOMscope1 and / or customscope1.

Make sure to define Mendix user roles and Insights Hub application scopes such that this mapping succeeds.

Pre-configured Roles in the Starter App

In the starter app the Mendix user roles Admin and User are pre-configured.

Mendix Roles

The application scopes for the starter app should be defined in Insights Hub as shown below. Note that the application scopes and Mendix user roles must be named identically as explained above:

Insights Hub Scopes

Validation

Your app must at least meet the requirements listed at Get your Application Ready for Productive Use.

Limitations

The following limitations apply to Mendix apps which are deployed to Insights Hub.

If these limitations affect the design of your app, you can alternatively run your Mendix app outside Insights Hub and call Industrial IoT APIs using service credentials. However, you cannot easily integrate it into the Launchpad or use single sign-on.

Binary File Storage

Insights Hub does not currently have a compatible file service available to its Cloud Foundry stack. Therefore, you cannot use any Mendix features which rely on having a file service. This means that you cannot any specializations of the System.FileDocument entity, which includes all specializations of the System.Image entity.

You can store small amounts of binary information in persistable entities. However, the database management system has strict limits on the size of binary attributes and using them as a replacement for FileDocument entities can lead to performance issues.

Alternatively, you can use a separate AWS S3 bucket. See Configuring External Filestore in the Mendix Cloud Foundry Buildpack GitHub Repository. This requires setting Cloud Foundry environment variables using the Cloud Foundry Command Line Interface.

Logout from Insights Hub

When the user logs out from Insights Hub, the Mendix app will not delete the session cookie. If another user reopens the app in the same browser on the same computer before the cookie has expired, the session from the previous user is picked up.

Logout

Roles and Scopes

Insights Hub supports up to five application roles. This should be taken into account when designing security within your Mendix app.

Native Mobile

With Mendix Studio Pro V8.0.0, Mendix supports the development of native mobile apps. However, this is currently not yet supported together with Insights Hub.


Last update: August 2, 2024

Except where otherwise noted, content on this site is licensed under the Development License Agreement.