Deploy and register Mendix Apps¶

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

Prerequisites¶

• A tenant including "Developer Cockpit"
• A user with assigned developer role: either mdsp:core:Developer or mdsp:core:DeveloperAdmin - these are already granted on Insights Hub Start for Free tenants.
• Mendix Studio Pro

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

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

Preparing the Mendix App for Insights Hub¶

Option A: Using the Insights Hub Starter App¶

Use the Insights Hub Starter App when developing a new Mendix app for Insights Hub. This contains all building blocks required for deploying and run apps on Insights Hub.

1. Open the Mendix Studio Pro.

2. Click on the icon at the top-right of the menu bar to open the Mendix App Store.

   

3. Enter "Insights Hub Starter Application" and press enter.

4. Select the Insights Hub Starter Application from the search results.

   

5. Click "Download" to create a new app project using this app.

   

6. Select where to store the app and enter an app name and the project directory. Then click "OK".

   

   App name

   If you want to keep your app name on Mendix and on Insights Hub consistent, use an app name that will be accepted by Developer Cockpit.

Option B: Integrating the Insights Hub Theme Pack and Modules¶

Mendix apps have to integrate the Insights Hub Theme Pack, the Single Sign-On module and the Insights Hub Bar Connector. Download these mandatory elements using following links to integrate them a posteriori into existing Mendix apps.

• Insights Hub Theme Pack in the Mendix App Store
  This theme pack adjusts the styling of Mendix apps and includes a general patch to run Mendix applications on Insights Hub as well as changes to the index.html required for the Insights Hub modules. For detailed information about the theme pack, refer to the Mendix documentation.
• Insights Hub Single Sign-On module in the Mendix App Store
  This module enables Mendix apps to use Insights Hub Single Sign-On which allows logged in Insights Hub users to access the app without another login. In addition, it enables developers to test their app locally. For detailed information about the module, refer to the Mendix documentation.

• Insights Hub Bar module in the Mendix App Store
  This module integrates the OS Bar, which is mandatory for every Insights Hub app. It connects all Insights Hub apps on a UI level, displays app information as shown below, routes back to the Launchpad, and logs the user out of Insights Hub. For detailed information about the module, refer to the Mendix documentation.

  

  Insights Hub Bar download ___location

  The Insights Hub Bar will be downloaded by default from EU1. If you are working on EU2 or any other platform, you can change this in the Insights Hub Bar module or just use the Insights Hub Bar from EU1. The bar provided on EU1 is compatible to all other target platforms.

Configuring the Modules¶

Configuring the Insights Hub Single Sign-On¶

1. Double click on the CockpitApplicationName constant.

   

2. Replace the Default value Change me in the "Value" section by the name you will use for configuring your app using the Developer Cockpit.

   

   Info

   Do not change the Name field at the top of this dialogue.

   The following constraints apply for app names when registering apps in Insights Hub:

   • Only lowercase alphanumeric characters are allowed and special characters such as -, _ and . are not allowed.
   • Starts with a letter
   • Length does not exceed 20 characters
   • The application name should be unique within your tenant environment

3. If your tenant is not in region Europe 1, adjust the MindSphereGatewayURL and the PublicKeyURL constants.

   • The MindSphereGatewayURL specifies the base URL for all requests to Industrial IoT APIs.
   • The PublicKeyURL defines the ___location of the public key, which is used for token validation during the login process.

Configuring the App Information (optional)¶

The app information is displayed if the user clicks on the app name in the OS Bar. Configure the app information by following the instructions below.

1. Double-click the string constant Config of the "MindSphereOSBarConfig" module.

2. Enter the app information as a JSON object into the "Default value" field:

   For a description of the available configuration parameters and a sample JSON object, refer to the OS Bar.

Deploying the Mendix 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 can then use the auto-registration process. Note that the auto-registration process is only available on region Europe 1.

Option A: Deploy with Mendix Studio to the Mendix Cloud¶

Click the "Run" 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 Cloud Foundry¶

1. Open the app in the Mendix Studio Pro.

2. Select "Project" and click "Create Deployment Package".

   

3. Select the desired "Development line" and "Revision" and set the version number.

4. (Optional) Add a description and adjust the path for the deployment package if desired. By default, the deployment package is created in the "releases" folder of your project.
5. Click "OK".

The ___location of the new deployment package will be displayed in an information window.

Deploying the App to Cloud Foundry via CF CLI¶

1. Open a command line interface (CLI) inside the folder with the deployment package.

2. Configure the proxy settings, if necessary.

   Click here for detailed information on proxy settings

   If you are in a company network behind a proxy, you may have to set the proxies to reach the Cloud Foundry endpoints. Contact your administrator, if you face any timeouts or connectivity problems.

   Set the proxies for the Cloud Foundry CLI as shown below:

   CMDBASH

     set http_proxy=http://PROXY_IP:PROXY_PORT
     set https_proxy=http://PROXY_IP:PROXY_PORT
   

     export http_proxy=http://PROXY_IP:PROXY_PORT
     export https_proxy=http://PROXY_IP:PROXY_PORT
   

3. Log in to CF using CF CLI. Enter cf login -a https://api.cf.{region}.{mindsphere-___domain} --sso.

4. Open the URL printed by the CLI and log in using your Insights Hub or Siemens ID credentials to get a one-time code.
5. Enter the one-time code in the CLI.

6. Select your Cloud Foundry org and space using the following command:

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

   No Cloud Foundry Orgs displayed

   If you do not see any Cloud Foundry orgs, you need to be added to your org. Refer to the How Tos for Cloud Foundry.

7. Create a PostgreSQL Service instance. Note that it takes some time until the instance is up and running.

   TemplateExample

   cf create-service {service_plan} {instance_name}
   

   cf create-service postgresql10 postgresql-xs my-postgreSQL
   

   Attention

   Each mendix app needs its own database. Do not bind more than one mendix app to a database. Create a new database instance instead.

   Service plans

   With the command cf marketplace, you can checkout which version of the postgres service is available e.g. postgresql94 or postgresql10

8. Check if your service instance is running using the following command:

   cf services
   

9. Create a manifest.yml file inside the folder with the deployment package with at least the following content:

   TemplateExample

   applications:
   - name: {app_name}
   disk_quota: {required_quota}
   memory: {required_memory}
   services:
   - {instance_name}
   

   applications:
   - name: my-app
   disk_quota: 512M
   memory: 512M
   services:
   - my-postgreSQL
   

1. Push the application to your Cloud Foundry space using:

   cf push -p "{deployment_package_name}"
   

Configuring the Mendix App in Insights Hub¶

Option A: Use the Auto Registration process - recommended if your app is deployed to the Mendix Cloud¶

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

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

Specify 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 Insights Hub 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.

For further configuration of your registration, e.g. CSPs or additional roles, use the Developer Cockpit.

Option B: Configuring the Mendix App in the Developer Cockpit¶

1. Open the Developer Cockpit from the Launchpad and select the Dashboard tab.
2. Click on Create new application.
3. Select Type Standard and Infrastructure Cloud Foundry.

4. Enter an arbitrary Display Name and an Internal Name which will be part of the application URL. The Internal Name cannot be changed after initial creation!

   Internal Name

   The Internal Name must be equal to the CockpitApplicationName configured in the Single Sign-On module.

5. Enter a version number.

   • Major.Minor.Patch scheme is supported.
   • Versions must start with a major number >= 1.
   • The version cannot be changed after saving.
6. Upload an icon for your application.

7. Enter the component name.

   Component Names

   Component names must match the names of the Cloud Foundry applications in the manifest.yml. Otherwise, the automatic registration in the production system will fail.

8. Add an endpoint for your component and use /** to match all of your application paths as shown below.

   Info

   For more details refer to Running a Cloud Foundry Application.

9. Enter the Cloud Foundry URL of your application.

   • Use cf app {app_name} to get the URL for your deployed application and prefix it with https://.

10. Set the following content security policy to ensure that the Insights Hub Bar and the Mendix Feedback widget (use at least version 7.0.6) are loaded correctly:

    yml tab="Europe 1" 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' *;

    Info

    These content security policy settings are needed to ensure that the Insights Hub 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).

11. Click Save.

You are redirected to the application details. Your application is in the In-Development state and is ready for registration.

Configuring the Mendix App Roles & Scopes¶

Every application in Insights Hub is protected from unauthorized access by specific [roles and scopes]. Insights Hub automatically creates two default roles for new applications:

• admin (mdsp:{tenant_name}:{app_name}.admin)
• user (mdsp:{tenant_name}:{app_name}.user)

For creating custom application roles, refer to [Securing your own Application]. The permissions for these roles are configured using the Developer Cockpit. You can assign Core roles, which grant access to Industrial IoT APIs, and define application scopes:

1. Switch to the Authorization Management tab.
2. Select the application.
3. Create an application scope and select which roles it is assigned to.
4. Add a Core role, that enables access to the respective API (optional). The image below shows how to get reading access to the Time Series APIs.

5. Saving is not required, unless you change one of the associations to the application specific roles afterwards.

   Authorization Management for Applications

   The roles and scopes configuration for applications is not specific for an application version.

6. Create an application scope and select which Insights Hub roles it is assigned to.

   Info

   The application scope must be named so that it can be mapped to a Mendix user role via case-insensitive comparison of the names. For detailed information refer to the roles and scopes information for developing Mendix apps.

   

   If you are using the starter app, create a user scope and an admin scope as shown below:

   

Registering the Mendix App¶

An application must be registered at the Industrial IoT Gateway to access it from the Launchpad. This enables the route from the tenant-specific Insights Hub URL to your internal Cloud Foundry application. The registration process follows a positive security concept, which requires every endpoint of the application to be explicitly registered.

1. Switch to the Dashboard tab.
2. Open the application details.
3. Click on Register.

The applications are registered using the following scheme: {tenant_name}-{app_name}-{tenant_name}.{region}.mindsphere.io

For more information regarding the registration scheme, refer Gateway-URL-schemas.

Assigning the Mendix App Roles¶

Applications only appear on the Launchpad, if one of the application scopes is present in the user's OAuth token. This is the case, if the user is assigned one of the application roles:

1. Open the Settings app from the Launchpad and switch to the Roles tab.
2. Select an application role and click on Edit assignments.
3. Assign one or more users to the application role.
4. Click on End editing.
5. Log out of from Insights Hub and log in again.

Your application is now available in your Launchpad. Your OAuth token contains all scopes and Core Roles defined in the application role. If you do not see the application, verify that you have assigned yourself the application specific role.

Related Links¶

• Mendix Academy
• Module and Theme Pack details
• Example app on Mendix

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