Siemens Insights Hub

Introduction

Insights Hub is the cloud-based, open IoT operating system from Siemens that lets you connect your machines and physical infrastructure to the digital world. It lets you harness big data from billions of intelligent devices, enabling you to uncover transformational insights across your entire business.

This documentation is meant for Mendix developers who want to deploy, register and run a Mendix app on Insights Hub.

You can easily copy code examples shown within grey blocks into the clipboard. Hover the cursor over the code block and click the copy button which appears.

To help you with your first Insights Hub apps, there is also an example app which contains modules which call the Insights Hub APIs. See How to Use the Siemens Insights Hub Monitor Example App for more information.

Prerequisites

To deploy and register your app within Insights Hub you need the following prerequisites.

• An Insights Hub user account on a Developer or a Start for Free tenant
• An Insights Hub developer role: either mdsp:core:Developer or mdsp:core:DeveloperAdmin — these are already granted on Start for Free tenants.
• Mendix Studio Pro

The following are also required if you want to deploy and run the Mendix app on Insights Hub Cloud Foundry:

• Cloud Foundry Command Line Interface (CF CLI)
• A Cloud Foundry role which allows you to push apps, such as SpaceDeveloper

Including Required Insights Hub Modules

You must customize your app to allow it to be deployed, registered, and shown in the launchpad. This is done through Insights Hub customization modules. There are two ways to include the customization you need in your app.

Option A: Using the Insights Hub App Template

The Siemens Insights Hub Starter Application in the Mendix Marketplace contains all the modules and styling which you need to create an app you want to deploy to Insights Hub.

Open Studio Pro (version 7.22.2 or above) and follow these steps:

1. Start your browser and open the Mendix Marketplace.

2. Enter Insights Hub in the search box, and press Enter.

3. Select Siemens Insights Hub Starter Application in the search results.

4. Click Download to create a new app using this app as the template.

   

5. Open your Mendix Studio Pro and select the Import App Package on the Open App dialog.

   

6. Select you just downloaded starter template package

7. To start the new app, confirm where to store the app, the app name, and the app directory, then click OK.

   

Option B: Customizing an Existing App

If you have an existing app which was not based on the Insights Hub app template, you must import the required customization. The three modules which must be imported are:

• Siemens Insights Hub SSO from the Mendix Marketplace here: Siemens Insights Hub SSO

  This module enables users who are logged in to Insights Hub to use your app without having to sign in again. It also enables you to test your app locally. For more information, see the Single Sign-On section of Insights Hub Module Details.

• Siemens Insights Hub OS Bar Connector from the Mendix Marketplace here: Siemens Insights Hub OS Bar Connector

  This integrates the mandatory Insights Hub OS Bar with your app. For more information, see the Siemens Insights Hub OS Bar section of Insights Hub Module Details.

• Siemens Insights Hub Web Content from the Mendix Marketplace here: Siemens Insights Hub Web Content

  This applies Insights Hub styling to your app and includes some additional custom files which are required for the correct operation of your app. For more information, see the Siemens Insights Hub Web Content section of Insights Hub Module Details.

Configuring the Modules

Now that you have your new app, or have imported the Insights Hub modules into an existing app, you need to configure the modules to allow your app to work with Insights Hub.

Configuring Single Sign-On (SiemensInsightsHubSingleSignOn)

The following items in the SiemensInsightsHubSingleSignOn module need to be configured.

CockpitApplicationName

Enter the name of your app as registered in the Insights Hub Mendix Portal as the value of CockpitApplicationName.

These two values must be identical and must, therefore, fit the constraints listed in the App Name section of Insights Hub Development Considerations.

GatewayURL

This is the URL of the Insights Hub gateway and is of the following format:

https://gateway.{Region}.mindsphere.io

This needs to be changed depending on the {Region} your app is running. The default value is for Insights Hub running on AWS:

https://gateway.eu1.mindsphere.io

PublicKeyURL

The value of this constant is shown below:

https://core.piam.{Region}.eu1.mindsphere.io/token_keys

This needs to be changed depending on the {Region} your app is running. The default value is for Insights Hub running on AWS:

https://core.piam.eu1.mindsphere.io/token_keys

RegisterSingleSignOn

Add the RegisterSingleSignOn microflow as the After startup microflow or added as a sub-microflow of an existing after startup microflow.

If you are modifying an existing app, you can do this on the Runtime tab of the App > Settings dialog box accessed through the App Explorer.

Configuring the Insights Hub OS Bar (SiemensInsightsHubOSBarConnector)

Change the OS Bar to show information about the app you are running.

This is configured as a JSON object held as the default value of the string constant Config in the SiemensOSBarConfig module. The imported module has a correctly formatted set of example values.

Change the JSON to contain appropriate values for the following information:

• displayName – the display name of your app
• appVersion – the version number of your app
• appCopyright – app owner’s name and year of publication
• links – links to additional information about the app

More information on the structure and content of this JSON object, together with sample JSON, can be found in App Information, on the Insights Hub developer site.

Deploying Your App

A Mendix based application for Insights Hub can be deployed to Mendix or to Insights Hub. Deploying to Mendix is quite easy and is the preferred option as you than also can use the Auto Registration process.

Option A: Deploy with Mendix Studio Pro to Mendix Cloud

Just click the Publish Button in Mendix Studio Pro.

Once your app is deployed you can automatically register the app in your Insights Hub tenant.

Option B: Creating a Mendix Deployment Package and deploy it to Insights Hub Cloud Foundry

Pushing to Cloud Foundry

Before you continue, ensure you have fulfilled the prerequisites described in the section Prerequisites and configured the Insights Hub modules as described in the section Configuring the Modules, above.

Creating a Mendix Deployment Package

To create a Mendix deployment package from your app, do the following:

1. Open your app in Studio Pro.

2. Select App > Create Deployment Package.

   

3. Select the correct Development line and Revision.

4. Set the New version number and add a Description if required.

5. Change the path and File name if necessary.

Your deployment package will be created, and its location displayed in an information message.

Deploying the Application to Cloud Foundry using CF CLI

To deploy your deployment package, do the following:

1. Sign in to Insights Hub CF CLI using a one-time code:

   • Enter cf login -a https://api.cf.{Region}.{mindsphere-domain} --sso

   • Open the URL printed by the CLI and sign in using your WebKey credentials to get a One Time Code

   • Enter the One Time Code in the CLI

     If you need to configure proxies for Cloud Foundry, use the Windows set command. For example, set http_proxy=http://my.proxy.ip:1234.

2. Select your org and space using the command:

   cf target –o {org_name} -s {space_name}
   

   If you cannot target your org or space, you probably need to be added to your org. See Cloud Foundry How Tos in the Insights Hub documentation.

3. Create a PostgreSQL instance using the command:

   cf create-service postgresql10 {plan} {service_instance} [-c {parameters_as_JSON}] [-t {tags}]
   

   For example: cf create-service postgresql10 postgresql-xs myapp-db

   For more information see Using the a9s PostgreSQL on the Insights Hub developers site.

   Each Mendix app needs its own database. Do not bind more than one app to a database as both apps will not work properly. Create a new database instance instead.

4. Depending on your infrastructure and service broker usage, it may take several minutes to create the service instance. Check if your PostgreSQL service has been created successfully using the following command:

   cf services Your service should be listed, and the last operation should be ‘create succeeded’.

5. Ensure you are in the same folder as the package you wish to deploy.

6. Create a manifest.yml file with at least the following content:

       applications:
       - name: {app_name}
         disk_quota: {disk_quota_size}
         memory: {memory_size}
       services:
         - {service_instance}
   

   disk_quota_size and memory_size must be at least 512M to enable a Mendix app to run.
   See the Cloud Foundry App Manifest Attribute Reference for more information on valid specifications for memory and disk quota sizes.
   Each Mendix app needs its own database. Do not bind more than one app to a database as both apps will not work properly. Create a new database instance instead.

   For more information on the configuration of manifest files, see Configuring the manifest file on the Insights Hub developers site.

7. Push your app to Insights Hub using the command:

   cf push -p "{deployment_package_name}"
   

   For example: cf push -p "myapp.mda"

Cloud Foundry Stack

You should always use the latest available Cloud Foundry stack. The latest stack in Insights Hub is cflinuxfs4. Apps pushed to Insights Hub will use this stack.

You can specify that your app uses a specific stack using the following command line option when you push your app:

cf push -p "{deployment_package_name}" -s {stack_name}

For example: cf push -p "myapp.mda" -s cflinuxfs4

For more information about Cloud Foundry stacks on Insights Hub, see How Can I Find the Stack my App is using? in Cloud Foundry How Tos on the Insights Hub Developer site.

Troubleshooting

If you have issues with deploying your app to Cloud Foundry, you can find additional information in Running a Cloud Foundry-Hosted Application – for Java Developers. Note that this is not written from the point of view of a Mendix developer, so some information may not be relevant.

Ensure that you have configured your proxy settings if these are required.

Setting up Insights Hub Launchpad

You have to register your application for it to work and appear on the Insights Hub Launchpad. If you have deployed your application to Mendix you can use either of the following two options (where Option A is preferred). Deployed to Insights Hub, you have to register manually via the Developer Cockpit (Option B).

Option A: Using the Auto Registration Process

To start the Auto Registration process click the View Button in Mendix Studio Pro once your app is deployed to Mendix Cloud. Your default browser will open and your app will start the process.

Click Start Auto Registration. The process now tries to figure out on which tenant your app should be registered. Therefore you have to login:

Give a name, internal name, and, optionally, a description in order to register your app.

If you are on a Developer tenant you also have to select at least one application role which will be assigned to your account automatically.

On a Start for Free tenant the admin role will be assigned automatically to your account.

Click Register to start the registration process on your tenant. After a few seconds, a summary page is shown and you are able to navigate directly to your app.

Please note, for further configuration of your registration, for example, CSPs or additional roles, please use the Developer Cockpit.

Option B: Configuring the Mendix App in the Developer Cockpit

Creating a New Application

To create a new app manually in the Insights Hub launchpad, do the following:

1. Go to the Developer Cockpit > Dashboard.

2. Click Create new application.

3. Set the Type to Standard.

4. Set the Infrastructure to Cloud Foundry.

5. Fill in the Display Name of your app, as you want it shown in the Launchpad.

6. Fill in the Internal Name of your app. This must be identical to the value of CockpitApplicationName which you set in the SSO module of your app.

7. Fill in a Version for your app.

8. Fill in a Description of your app, if required.

9. Click Edit icon to upload an App Icon for your app.

10. Fill in the Component > Name. This must be identical to the {app_name} you set in the manifest.yml file.

11. Click the + next to the component to add Endpoints.

12. Specify /** as the endpoint to allow you to access all endpoints relevant to your application, and click Save.

13. Fill in the Cloud Foundry Direct URL. This can be found using the Cloud Foundry command cf app {app_name}.

14. Set the Configurations > content-security-policy Value to the following (hover your mouse over the text and you will be able to copy the contents to your clipboard):

    If your app is running on Insights Hub on AWS use Region eu1:

    default-src 'self' 'unsafe-inline' 'unsafe-eval' static.eu1.mindsphere.io feedback-static.mendix.com home.mendix.com;
    font-src 'self' static.eu1.mindsphere.io fonts.gstatic.com;
    script-src 'self' 'unsafe-inline' 'unsafe-eval' static.eu1.mindsphere.io feedback-static.mendix.com home.mendix.com;
    style-src 'self' 'unsafe-inline' static.eu1.mindsphere.io feedback-static.mendix.com home.mendix.com fonts.googleapis.com;
    img-src * data:;
    connect-src 'self' 'unsafe-inline'  *;
    

    These content security policy (CSP) settings are needed to ensure that the Insights Hub OS Bar and the Mendix Feedback widget are loaded correctly. You may need to set additional CSP settings if you make additional calls to other domains (for example, if you use Google maps from maps.googleapi.com).

    

15. Click Save to save these details.

16. Click Register to register your app with the Insights Hub launchpad.

    If the app has not been pushed yet, there will be no route set up for the app and you will get an error message. This will be resolved once you have pushed your app to Cloud Foundry.

Setting Application Scopes in Developer Cockpit

To set up the appropriate scopes in Insights Hub, do the following:

1. Go to Developer Cockpit > Authorization Management > App Roles from the Insights Hub launchpad.

2. Enter the Scope Name.

3. Associate it with the Insights Hub default roles user and/or admin. Or associate it with one of your self created Insights Hub roles. Insights Hub supports up to five application roles.

4. Click Save.

   

For an explanation of the relationship between Mendix roles and Insights Hub roles, see section Roles and Scopes in Insights Hub Module Details.

Assigning User Roles

Once you have created the scopes for your app, you will need to assign them to the users who you want to have access to the app.

1. Go to Settings > Roles from the Insights Hub launchpad.

   

2. Choose the app role (scope) you want to assign from the list of Roles.

3. Click Edit assignment.

4. Select the user you like to assign the role

5. Click Next and Save.

Development Considerations

See Insights Hub Development Considerations for additional help on such things as:

• local testing
• multi-tenancy
• limitations