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 .
  • Starts with a letter
  • Length does not exceed 40 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

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

Application Credentials

When running your app locally, you have to provide application credentials so the MindSphere Single Sign-On module can generate a token for accessing MindSphere APIs. For that the following login screen is opened:

Login Screen

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

Configuration

The following constants need to be set in the Local Development folder:

Constant Description
AskForAppCredsOnStartUp 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.
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, redeploy, and log in again.

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

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:

  • You can have a maximum of ten users.
  • The app goes into sleep mode after 1-2 hours.

For more information refer to the MindSphere Development Considerations on Mendix.

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 {iconName}
    

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 assets that you need to store persistently in the database. You then want to get a list of all your assets.

  1. Create the domain model with the Asset entity being a specialization of MindSphereSingleSignOn.TenantObject. create domain model
  2. Implement a sub-microflow which returns a list of all assets.
  3. Apply the XPath constraint to the Retrieve Objects action of the microflow. access token
  4. When you want to retrieve the list of assets, call this microflow instead of using the retrieve objects action. This ensures 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 {appName}.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.

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 currently only supports two roles. This should be taken into account when designing security within your Mendix app.

Any questions left?

Ask the community


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