Insights Hub Development Considerations

1 Introduction

When developing a Mendix app which will be deployed to Insights Hub, there are a number of extra things you need to take into consideration. The following subjects are discussed below:

• Authorizing Insights Hub REST Calls
• Cloud Foundry Environment Variables
• Licensing Your App
• Local Testing
• Insights Hub Icons
• Multi-Tenancy
• Validation

Finally, there is a section on some Limitations which apply to Mendix apps deployed to Insights Hub.

2 Authorizing Insights Hub REST Calls

The AccessToken entity contains the Access_token attribute which needs to be passed as the Authorization header in REST calls to Insights Hub APIs.

To improve security of your app, it is recommended that you delete the AccessToken object returned by the Access token action, provided by the Siemens Insights Hub SSO module, before showing a page or reaching the end of the microflow.

2.1 Authorizing Insights Hub REST Calls from within Scheduled Events

The access token connector cannot be used for calling an Insights Hub API in a microflow which is executed without a user context – for example, called from a scheduled event. Therefore the SiemensInsightsHubSingleSignOn module offers a microflow, DS_GetAccessTokenForScheduledEvents, that returns a Token for a given Tenant. This microflow is also exposed in the toolbox on the right side:

The microflow uses the Insights Hub Application Credentials functionality to fetch a token, and uses different environment variables depending on the location where the app is running:

1. Local:

   The microflow uses the application credentials you entered at startup to fetch a token. See also Application Credentials.

2. Developer Tenant:

   The following cloud foundry environment variables must be set for the app:

   Developer Tenant	Description
   MDSP_KEY_STORE_CLIENT_ID	enable Application Credentials in the Developer Cockpit for your app and use the Client ID
   MDSP_KEY_STORE_CLIENT_SECRET	enable Application Credentials in the 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

3. Operator Tenant:

   Some of the following environment variables are set automatically:

   Operator Tenant	Description
   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

Make sure these environment variables exists. Use the returned token as usual in your REST calls to Insights Hub. Do not delete the token after usage as it is not transferred to the client and it is cached in SiemensInsightsHubSingleSignOn 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.

For more information on how to perform REST calls see the Importing and Exporting Your Data learning path (you must be signed in to the Mendix Platform to see this learning path).

3 Cloud Foundry Environment Variables

If you need to set or change the value of any Cloud Foundry Environment Variables, you will have to do this using the Cloud Foundry Command Line Interface (CF CLI).

1. Use cf set-env {app_name} {environment_variable_name} {value}
2. You will need to restage the app to use the new value. Use cf restage {app_name}

Mendix Constants

Your app will define the default values for constants. You can override these default values with Cloud Foundry environment variables. To do this, you need to replace the dot with an underscore and prefix the name with MX_. For example, a constant MyConstant in module MyModule (that is, MyModule.MyConstant), in app MyApp could be set to ABC123 like this:

    cf set-env MyApp MX_MyModule_MyConstant "ABC123"

4 Licensing Your App

When you initially deploy a Mendix App, it is treated as a Free App. For an Insights Hub app the most important restriction is that the app will go into sleep mode after 1-2 hours: this could cause the Cloud Foundry environment to be restarted and pick up the latest values of environment variables.

To license your app, you need to obtain a license key from Mendix Support.

Instructions for licensing apps are available in the License Activation section of the Mendix Cloud Foundry Buildpack Readme. Refer to Cloud Foundry Environment Variables, above, for instructions on changing Cloud Foundry environment variables.

5 Local Testing

5.1 Corporate Proxies

If you need to use a corporate web proxy, the following settings must be applied in Mendix Studio Pro to allow communication with Insights Hub during local development.

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

5.2 Application Credentials

The SSO module supports you in getting a valid Insights Hub token locally via Application Credentials.

When you run your app locally, you will not be able to use SSO to get your credentials. You will be logged in as MxAdmin and will be presented with a login screen on app startup if the constant AskForCredentialsOnStartUp is true - otherwise communication to Insights Hub is not possible.

This will use the credentials you have set up under App Credentials in the Authorization Management tab of the Insights Hub Developer Cockpit for this application.

Tip: Use the autofill feature based on a local environment variable for the Client Secret.

Storing the Client Secret inside the app is, from a security perspective, not a good idea. A better approach is to use a local environment variable. Create a user-specific environment variable with Variable name equal to your Client ID value and the Variable value equal to your Client Secret value. See step 6 below for information on how to get these values.

On startup, the system checks if there is an environment variable present with the name equal to your Client ID value and uses its value as ClientSecret. The ClientID is built from the combination of:

*Host tenant*-*Cockpit application name*-*Cockpit application version*

Ensure you have filled these constants correctly. If everything is setup correctly the form is auto filled and submitted.

Don’t forget to restart Studio Pro after you change / add the environment variable.

To create the app credentials:

1. Register this application using the identical application name as that set in the constant CockpitApplicationName, and a valid version number which is the same as the one you set in CockpitApplicationVersion, below . See also, Insights Hub Launchpad Setup in Siemens Insights Hub – deployment.

2. Go to the App Credentials page in the Authorization Management tab of the Insights Hub Developer Cockpit.

3. Choose your app.

4. Click Issue access to obtain a token.

   

5. Select the access level and click Submit

   

6. Make a note of the Client ID and Client Secret

   

For more information about creating app credentials, see the documentation on the Insights Hub website here: Self-Hosted Application – Access Insights Hub APIs.

To ensure that the correct application credentials are requested, you have to set the following constants in the LocalDevelopment folder of the SiemensInsightsHubSingleSignOn module in addition to the other configuration constants.

5.3 Configuration

AskForCredentialsOnStartUp

Set this to True if you want your app to ask for credentials as soon as it starts up, before the first page is displayed. If this is set to False then the app will ask for credentials the first time that it attempts to retrieve your access token.

If you trigger microflows consuming Insights Hub APIs on the home page, setting this to True ensures that they will work the first time the page is displayed.

CockpitApplicationVersion

This is the version of the Insights Hub app linked to the application credentials, as registered in the Developer Cockpit under the name CockpitApplicationName.

EnableLocalApiReverseProxy

Set this to True to enable a reverse proxy for Insights Hub API calls which are made directly from the html pages (for example, the calls from the Insights Hub OS Bar).

This endpoint forwards all calls to \api… from within native HTML pages, and adds an Insights Hub token to them. For example, the calls from the Insights Hub OS Bar or the Siemens Insights Hub Widgets.

HostTenant

This should be the tenant where your credentials are stored. It is needed when retrieving your Service Credentials.

The definition of a tenant on Insights Hub is available in the Insights Hub document Definition of Tenant.

UserTenant

This should be the tenant that the user has access to in a multi-tenant environment. For a developer tenant, this must be the same as the HostTenant. In an operator or iot plan tenant, you can change this to allow you to test multi-tenant apps.

UserEmail

Specify the email used for the local MxAdmin user account. Default value “max.mustermann@email.com” is used in case no value is provided.

5.4 User Roles

If you are testing different roles in your app, do not use the demo users. If you switch between demo users, this will not correctly populate the tenant and role information from Insights Hub. To test different roles, allocate the role to MxAdmin, redeploy, and sign in again.

The MxAdmin role is found In the Administrator tab of the Security settings of your app.

5.5 Local User Passwords

Local users should not be created for your Insights Hub app.

When a new user is identified during SSO, the SSO process generates a random password for the user. The password policy for your app needs to accept these randomly generated passwords. The password generation algorithm generates passwords of a fixed length, so the password policy should not be set to require more characters.

6 Insights Hub Icons

The Siemens Insights Hub Web Content module includes two ways of including Insights Hub icons in your app.

6.1 Insights Hub Icons as ‘glyphicons’

You can select Insights Hub icons from Siemens Insights Hub Web Content to be displayed in your application.

1. Open the properties of a widget which can display an icon (for example a button).
2. Click Select… next to Icon.
3. Choose the Insights Hub tab.
4. Find the image that you want and click Select. The Insights Hub icons are in the module SiemensInsightsHubWebContent.

6.2 Insights Hub Icons via CSS

Siemens Insights Hub Web Content provides a font which contains icons. This means that you can use an Insights Hub icon in any page element where you can assign a class.

To do this:

1. Find the icon you wish to use. These have the same names as the icons in Siemens Insights Hub Web Content and are listed in the App Explorer dock under App > Marketplace modules > SiemensInsightsHubWebContent > InsightsHub.

   

2. Open the properties of the element to which you wish to add an icon.

3. Set Icon to (none).

4. Add the class iconUxt {icon-name}.

   

7 Multi-Tenancy

In Insights Hub, apps are usually designed to be multi-tenant, meaning that a single instance of the app serves multiple tenants. A tenant is a representation of a real-world organization. It groups users, data, assets, entities, and many kinds of other properties. Access to these resources for users of the same tenant is controlled via the authorization management system.

For an Insights Hub app to be multi-tenant, each user can only see the data from a single tenant, defined by their login credentials, and cannot access resources of other tenants.

7.1 Control Through Insights Hub APIs

The Authorization HTTP Header (see DS_AccessToken in the Microflows section of Insights Hub Module Details) which is passed for every Insights Hub API call ensures that the user can only obtain data which is authorized to them via their tenant.

7.2 Control Within a Mendix App

If no security is placed on persistable Mendix entity objects, these are accessible to all users of the app (subject to access granted by their user role). This means that any app which stores data in persistable Mendix entities cannot be made multi-tenant without additional security.

Insights Hub SSO provides the user’s tenant as the Name attribute in the Tenant entity.

In addition, Insights Hub SSO will identify whether the current user is a subtenant using IsSubTenantUser and, if so, will populate the name of the subtenant in SubtenantId. More information about subtenants can be found in the Insights Hub documentation Subtenants.

How To Make Your App Multi-Tenant

By utilizing the Tenant when an entity is accessed, the Mendix app can be made multi-tenant.

To make your Mendix app multi-tenant, do the following:

1. Make all persistable entities which have a TenantId attribute a specialization of the SiemensInsightsHubSingleSignOn.TenantObject entity. This ensures that every object is associated with the Tenant object of the user who creates it.

2. Every microflow action on this object must have the following XPath constraint:

   [SiemensInsightsHubSingleSignOn.TenantObject_Tenant/SiemensInsightsHubSingleSignOn.Tenant/SiemensInsightsHubSingleSignOn.Account_Tenant='$currentUser']
   

   This ensures that the user can only retrieve entities which belong to their tenant, in other words, where their Tenant matches the TenantId of the entity. You can copy and paste this constraint from here (hover your mouse over the text and click the Copy button). You can also copy it from XPath constraint on the TenantObject entity in the SiemensInsightsHubSingleSignOn module. For more information on XPath, see XPath.

   For consistency, it is recommended that all access to these entities is done through a sub-microflow which contains the XPath constraint. This enforces multi-tenant security.

3. Similarly, every data widget on a page (for example a Data view) which retrieves data from the database or via an association must have the following XPath constraint, which works in the same way as the microflow XPath constraint, above:

   [SiemensInsightsHubSingleSignOn.TenantObject_Tenant/SiemensInsightsHubSingleSignOn.Tenant/SiemensInsightsHubSingleSignOn.Account_Tenant='[%CurrentUser%]']
   

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 SiemensInsightsHubSingleSignOn.TenantObject.

   

2. Write a sub-microflow which returns a list of all limits.

3. Apply the XPath constraint to the Retrieve Objects action.

   

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 always applied.

8 Validation

Your app should, as a minimum, meet the requirements of the checklist on the Insights Hub developer site here: Get your Application Ready for Productive Use.

9 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 still create a Mendix app to use Insights Hub APIs from outside Insights Hub.

9.1 Binary File Storage

Insights Hub does not currently have a compatible file service available in its Cloud Foundry stack. Therefore, you cannot use any Mendix features which rely on having a file service.

In particular, this means that you cannot use entities which are specializations of the System.FileDocument entity. This also includes all entities which are specializations of the System.Image entity, as this is also a specialized type of FileDocument.

You can store small amounts of binary information in persistable entities. However, the database management system (DBMS) will have 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 Connect an External Filestore in the Mendix Cloud Foundry Buildpack GitHub Repository. Refer to Cloud Foundry Environment Variables, above, for instructions on changing Cloud Foundry environment variables.

9.2 App Name

There are few limitations on what you call your app within Mendix. However, when you deploy the app to Insights Hub, the app name registered in the Developer Cockpit must have the following characteristics:

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

If you want to use the same app name in both Mendix and Insights Hub, you should bear these constraints in mind when naming your Mendix app.

9.3 Roles and Scopes

Insights Hub supports up to five application roles. You should take this into account when designing security within your Mendix app.

To use these scopes, you must create identically-named scopes for each Insights Hub application role. These scopes will map to identically-name user roles in your Mendix app.

There is a more detailed discussion of Insights Hub and Mendix roles and scopes in the Roles and Scopes section of Insights Hub Module Details.

9.4 Logout from Insights Hub

If the user signs out from Insights Hub, the Mendix app will not delete the session cookie.

9.5 Progressive Web Applications

Mendix Studio Pro version 9 introduced support for developing progressive web apps (PWAs). PWAs are not supported for Mendix on Insights Hub.

10 Read More

• Siemens Insights Hub – deployment
• Insights Hub Module Details