Skip to content

Developing Mendix Apps for MindSphere

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 MindSphere. For information about how to deploy Mendix Apps to MindSphere, refer to the step-by-step instructions.

App name

In contrast to Mendix, MindSphere imposes multiple restrictions on app names:

  • 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

Bear these constraints in mind when naming your Mendix app, if you want to keep your names in MindSphere and Mendix consistent.

Authorizing MindSphere REST Calls

REST calls to MindSphere APIs require an access token to be sent with the request. Create a workflow using the Access token connector provided in the MindSphere 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 MindSphere REST Calls from within 'Scheduled Events'

The Access token connector cannot be used for calling any MindSphere 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 MindSphere 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 MindSphere.

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 MindSphere. Apps pushed to MindSphere before the end of April 2019 may have used the stack cflinuxfs2 and must be migrated.

Find out which stack your application is using via cf app {app_name}.

Local Testing

When testing your app locally, i.e. outside the MindSphere environment, you don't automatically have a valid access token for accessing MindSphere APIs. For this use case, the MindSphere 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 will 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 MindSphere Single Sign-On module can be configured to use either application or service credentials.

Application Credentials

If the MindSphere 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 the MindSphere Developer Cockpit as follows:

  1. Register the application and make sure the application name equals the constant CockpitApplicationName.
  2. Open the Developer Cockpit.
  3. Navigate to the App Credentials page in the Authorization Management tab.
  4. Select the desired 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 MindSphere 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 MindSphere API calls.
CockpitApplicationVersion Specifies the version of the Mendix app as registered in the Developer Cockpit on MindSphere. 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 MindSphere token. Otherwise, a login screen for entering service credentials will be openend.
Default: TRUE
EnableLocalMindSphereApiReverseProxy Enables a reverse proxy for MindSphere API calls by adding a new endpoint /api/** to the app. This endpoint adds a MindSphere token to direct calls to MindSphere APIs which are not part of a microflow, but inside JavaScript code, e.g. when using the MindSphere 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 in MindSphere correctly. Instead, allocate the role to MxAdmin, restart and log in again.

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

Corporate Proxy

For corporate web proxy, the following settings must be applied in Mendix Studio Pro in order to communicate with MindSphere 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 conrol 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 MindSphere 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:

1
2
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 MindSphere 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

MindSphere Icons

The MindSphere Theme Pack provides MindSphere 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:

MindSphere Icons

The MindSphere 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:

    1
    iconMdsp {icon_name}
    

MindSphere Icon Font

Multi-Tenancy

MindSphere 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 MindSphere's Identity and Access Management.

Access Control by MindSphere Gateway

An authorization HTTP header is passed in every MindSphere API call. The MindSphere 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 in MindSphere. The following instructions explain how to use the tenant name provided by the MindSphere 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 MindSphere use roles for managing access permissions of application users. This requires a mapping of Mendix user roles to MindSphere application scopes, which is implemented in the MindSphere 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 MindSphere application scopes and Mendix user roles. For example, a MindSphere application scope {app_name}.customScope1 is mapped to the Mendix roles CUSTOMscope1 and / or customscope1.

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

Preconfigured Roles in the Starter App

In the starter app the Mendix user roles Admin and User are preconfigured.

Mendix Roles

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

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

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

Binary File Storage

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

Cloud Services Platform

Mendix apps can currently only be deployed to MindSphere in region Europe 1 and Europe 2.

Logout from MindSphere

When the user logs out from MindSphere, 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

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

Any questions left?

Ask the community


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