Siemens MindSphere

Last update: Edit

1 Introduction

MindSphere 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 MindSphere.

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

2 Prerequisites

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

  • A MindSphere user account on a Developer or a Start for Free tenant
  • A MindSphere 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 MindSphere Cloud Foundry:

The following are also required if you want to deploy and run as a self-host app, for example an app running on Mendix Cloud:

3 Including Required MindSphere Modules

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

3.1 Option A: Using the MindSphere App Template

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

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

  1. Click the icon in the top-right of the menu bar to open the Mendix Marketplace.

  2. Enter MindSphere in the search box, and press Enter.

  3. Select MindSphere Starter Application in the search results.

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

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

3.2 Option B: Customizing an Existing App

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

  • Siemens MindSphere SSO from the Mendix Marketplace here: Siemens MindSphere SSO

    This module enables users who are logged in to MindSphere 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 MindSphere Module Details.

  • MindSphere OS Bar Connector from the Mendix Marketplace here: Siemens MindSphere OS Bar Connector

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

  • Siemens MindSphere Web Content from the Mendix Marketplace here: Siemens MindSphere Web Content

    This applies MindSphere 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 MindSphere Web Content section of MindSphere Module Details.

4 Configuring the Modules

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

4.1 Configuring Single Sign-On (MindSphereSingleSignOn)

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

Folder structure of the MindSphereSingleSignOn module

4.1.1 CockpitApplicationName

Enter the name of your app as registered in the MindSphere developer 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 MindSphere Development Considerations.

4.1.2 MindSphereGatewayURL

This is the URL of the MindSphere gateway and is of the following format:


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

If your app is running on MindSphere on Azure change this constant to:

4.1.3 PublicKeyURL

The value of this constant is shown below:


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

If your app is running on MindSphere on Azure change this constant to:

4.1.4 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 are modifying an existing app, you can do this on the Runtime tab of the App > Settings dialog box accessed through the App Explorer.

App settings dialog

4.2 Configuring the MindSphere OS Bar (MindSphereOSBarConfig)

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

Example of the information in the OS Bar

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

Dialog for setting the Config constant for the OS Bar

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 MindSphere developer site.

5 Deploying Your App

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

5.1 Option A: Deploy with Mendix Studio Pro to the Mendix Cloud

Just click the Publish Button in Mendix Studio Pro.

Deploy to Mendix

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

5.2 Option B: Creating a Mendix Deployment Package and deploy it to MindSphere Cloud Foundry

5.2.1 Pushing to Cloud Foundry

Before you continue, ensure you have fulfilled the prerequisites described in the section Prerequisites and configured the MindSphere 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 MindSphere CF CLI using a one-time code:

    • Enter cf login -a{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
  2. Select your org and space using the command:

    cf target –o {org_name} -s {space_name}
  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 MindSphere developers site.

  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:

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

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

  7. Push your app to MindSphere 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 MindSphere is cflinuxfs3. Apps pushed to MindSphere 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 cflinuxfs3

For more information about Cloud Foundry stacks on MindSphere, see How Can I Find the Stack my App is using? in Cloud Foundry How Tos on the MindSphere 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.

5.3 Setting up MindSphere Launchpad

You have to register your application for it to work and appear on the MindSphere 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 MindSphere, you have to register manually via the Developer Cockpit (Option B).

5.3.1 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 the 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:

Login to Siemens Digital Industry Software

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.

5.3.2 Option B: Configuring the Mendix App in the Developer Cockpit Creating a New Application

To create a new app manually in the MindSphere 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 MindSphere 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 MindSphere on AWS use Region eu1:

      default-src 'self' 'unsafe-inline' 'unsafe-eval';
      font-src 'self';
      script-src 'self' 'unsafe-inline' 'unsafe-eval';
      style-src 'self' 'unsafe-inline';
      img-src * data:;
      connect-src 'self' 'unsafe-inline'  *;

    If your app is running on MindSphere on Azure use Region eu2:

      default-src 'self' 'unsafe-inline' 'unsafe-eval';
      font-src 'self' data: *;
      script-src 'self' 'unsafe-inline' 'unsafe-eval' *;
      style-src 'self' 'unsafe-inline' *;
      img-src 'self' data:;
      connect-src 'self' 'unsafe-inline' *;

  15. Click Save to save these details.

  16. Click Register to register your app with the MindSphere launchpad. Setting Application Scopes in Developer Cockpit

To set up the appropriate scopes in MindSphere, do the following:

  1. Go to Developer Cockpit > Authorization Management > App Roles from the MindSphere launchpad.
  2. Enter the Scope Name.
  3. Associate it with the MindSphere default roles USER and/or ADMIN. Or associate it with one of your self created MindSphere roles. MindSphere supports up to five application roles.
  4. Click Save.

For an explanation of the relationship between Mendix roles and MindSphere roles, see section Roles & Scopes in MindSphere 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 MindSphere launchpad.

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

  3. Click Edit user assignment.

  4. Assign Available users to Assigned users using the assignment symbols (for example > to assign a user).

  5. Click Close.

6 Development Considerations

See MindSphere Development Considerations for additional help on such things as:

  • local testing
  • multi-tenancy
  • limitations