Skip to content

Add an application

Adding an application in Developer Cockpit is the first step to start your journey with MindSphere. You can add different types of application based on the app and hosting type. For more information on the supported application types and infrastructures, see "Application types and specifications".

Pre-requisites for creating an application

The following requirements apply for integrating your application into MindSphere:

  • Your self-hosted application is reachable via DNS and a valid SSL certificate (self-signed certificates are not allowed).
  • Your self-hosted application exposes one health endpoint for MindSphere's internal monitoring.
  • Your mobile application without backend must be installable on a mobile device.

User Interface

"Create Application" screen:

You can add your application to Developer Cockpit by filling the below fields.

Create Application

① "Back to Overview" button: Navigates the dashboard

② Enter field parameters

③ "Save" and "Reset" Buttons to save or reset the changes

Parameter Description
Type You can create four types of applications: Standard, Fleet Manager Plugin, Operations Insight Plugin, Mobile, and API.
Infrastructure Three types of infrastructures are available: Self-hosted and None (valid for mobile apps).
Note:
Cloud Foundry infrastructure is available to host your application in MindSphere environment. To activate this feature, you need to buy from IIoT Data Resource package.
Display Name Enter the name of the application that you want to display on the Launchpad. Also, this name is displayed to the Operator. This field does not support any special characters and it is limited to 50 characters only.
Internal Name By default, the "Internal Name" is auto-filled by entering the display name in lower case and without special characters.
The internal name is used later in the URL and must be unique for your tenant. Enter the name for the application with the following conditions:
- The name must start with an alphabet.
- Only lower-case letters are allowed.
- A maximum of 20 alphanumeric characters is allowed.
Version By default, "v1.0.0" version is auto-filled in the version field and it can be changed as per the requirement.
The version supports alphanumeric string data. Spaces in between the nomenclature format are not supported. A maximum of 30 alphanumeric characters is allowed. Use of capital letters for naming versions is not allowed.
However, it supports the following special characters:
- #
- $
- .
- ;
- +
- -
- _
- @
In the version field in Developer Cockpit, if there are any special characters (except "@", "."), the provisioning workflow fails in Operator Cockpit.
For API applications, the following format needs to be followed:
v<version>.<revision>.<patch>-<label(optional)>
e.g. v1.0.0, v2.1.0-alpha
- <version> is version, number with range 1-9.
- <revision> is revision, number with range 0-99.
- <patch> is patch number, number with range 0-99.
- <label> is label and optional, case insensitive alphabet.
Mendix-based application This check box is used to notify the operators that a Mendix license is needed to run the app.
Description Add a description for the application. This is an optional field. This provides information about the application and will be visible to the operator.
Icon Icon of the application is displayed in Developer Cockpit dashboard screen, Launchpad and will later also be visible to an Operator and IoT customers.
By default, an application icon is loaded. Upload a different image to represent the application according to your suitability. The recommended resolution of 512x512 is suitable for both high and low-resolution screens.

"Components" screen:

You can add multiple components based on the complexity of your application, for example, you can add the components as shown in the following figure:

Components screen

① Name the component

② Application URL in Self-hosted server

③ Add or edit endpoint configuration of the component

④ Delete the component

⑤ Re-order the component

Parameter Description
Components Adding components to your application are used to structure your application and register it accordingly in the MindSphere Gateway. However, it is mandatory to have a minimum of one component with one endpoint for an application. Add at least one component to your application, if the application is a self-hosted based application. If you select the infrastructure as "None", then the component field will be disabled.
Component Name Enter the name of the component.
The following conditions hold while naming a component:
- It should not include alphanumeric and '-', '_', '.' special characters.
- A maximum of 40 characters are allowed.
- The "Name" field of the application in the component tab supports only lower-case letters.
URL - Enter the direct URL for each of the components for a self hosted application. The URL format should be valid in the format and not malicious: https://apps.example.com/<ContextPath>.
Endpoints The endpoints section will remain disabled until "Name" and Self-hosted direct URL's have values.

"Configurations" screen:

For Standard, Fleet Manager Plugin, Operations Insight Plugin, and API applications

Configurations screen

For Mobile applications

Mobile applications

Parameter Description
Content-Security-Header Configuring Content Security Policy header, prevents from possible attacks and execution of malicious content or code and makes your application more secure. For more information, see "Configuring Content Security Policy".
By default, the configuration value is taken for the content security policy. The content security policy header value can be only 1000 characters long, rest of the characters will be discarded.
The field cannot be empty. If you try to save the application by keeping the field empty, backend service will set the default values.
Cache control With Cache control, each cache will be revalidated before using a cached response to capture the uncacheable responses.
By default, the configuration value is taken for the cache control. The cache control value can be only 255 characters long, rest of the characters will be discarded.
The field cannot be empty. If you try to save the application by keeping the field empty, backend service will set the default values.
Configurations for applications (For Mobile applications) Enter the Android App Links and Universal Links configuration information for "Android" and "iOS" respectively as per the specified format.
These links seamlessly link to content inside your application. Using these links, you can always give users the most integrated mobile experience, even when your application is not installed on the device.
The link configurations are the special URLs which invokes specific screen of native mobile application. These links can be non-HTTP(S) based URLs (called as custom links) or strictly HTTP(S) based URLs. Mobile OS allows multiple applications to register with the same link. Whenever user navigates to any of such links, mobile OS allows the registered user to select one of the applications.
For more information on "Android" and "iOS" application links, see "Mobile Application Developer Documentation".
Hosting of assetlinks.json and AASA files: In configurations, the field user can provide the link to the "apple-app-site-association file" or to "assetlinks.json" file which is either hosted in user’s domain or storage. Each application can have only one assetlinks.json and one AASA file. The maximum size of each file is 2kb.
Note:
The "Configurations" and "Icon" fields for mobile applications are optional.
Android Domain validation is performed by Android, and it expects a special file assetlinks. json to be hosted under https://<domain>/.well-known/ folder.
The field value can be only 255 characters long.
iOS Apple expects a special file apple-app-site-association (AASA) under https://<domain>/. well-known or directly under https://<domain>.
The field value can be only 255 characters long.
Custom-scheme Domain validation is performed by customized scheme like, "https://<domain>/." or "mobile://<domain>/."

"API dependencies" screen:

For adding API dependencies, click the "Add API Dependency" button. Add the API dependencies for the application from the "API dependencies" pop-up screen.

API dependencies

Parameter Description
API dependencies for applications (for standard, Fleet Manager Plugin, Operations Insight Plugin, and mobile applications) MindSphere allows a user to develop backend applications, to support single or multiple UI apps. These applications are called API type apps. The developer can re-use the functional logic in multiple applications.
API dependencies for applications enables you to build UI applications on top of already existing API applications from other developers. To use this new functionality, an operator will provision the API app to your developer tenant, and you can continue to use the provided functionality. Currently provisioned apps can be used only with Custom App Credentials and by using Advanced Token Exchange. To learn more about the Advanced Token Exchange, see Accessing MindSphere /Token APIs.
Add API Dependency Add the API from the list. Maximum 5 dependencies can be added for an application.
Name Name of the API dependency
Type Select "Internal" or "External" or both
Version Version of the API dependency
Operator Operator name who provides the API app to you.
Registered State of the API dependency application is registered or not registered.

Procedure for adding an application

To add an application, follow the steps:

  1. Login to Developer Cockpit.
  2. In "Dashboard", click “Add application”.
  3. Enter the field parameters as per the parameters table.
  4. Upload the icon in the "App icon" field.
  5. In the "Component" tab, enter the component's name and URL and click "Add/Edit Component" to add the component.
  6. In "Modify Component Endpoints" pop-up, select the default "/" endpoint or enter the new endpoint and click "Add".
  7. In the "Configuration" tab, verify the configurations of the application.
  8. In the "API dependencies" tab, click the "Add API Dependency" and select the API dependency and then click "Add" (optional).
  9. Click "Save" to add the application in the "Dashboard" tab.

Note

  • The name and the version of the application cannot be changed after its creation. However, you can change the Application Icon, Display Name, Description and endpoint configuration.
  • The configuration of an application can only be changed when it is not registered in the Gateway.
  • Only "Third Party API Roles" section is not applicable in API "Authorization Management" tab as APIs cannot access other API applications.

Result

The application is saved successfully and will be available in the "Dashboard" tab.

Dashboard

Next steps

  • Register the application. For more information on registering applications, see Register an application in MindSphere.
  • Configure your application specific Roles and Scopes to provide access to the application. For more information on assigning roles, see Assign roles and scopes.
  • Assign yourself at least one application specific role in order to access it. For more information on roles, see Roles chapter in Settings application.
  • If you need to create a new version/revision for an application in Developer Cockpit, see New version of an application.

Any questions left?

Ask the community


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


Last update: May 19, 2022