Add an application¶
Adding an application in Developer Cockpit is the first step to start your journey. You can add different types of application based on their 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 Insights Hub:
- 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 internal monitoring.
- Your Cloud Foundry hosted application must have the deployable Cloud Foundry application ready.
- 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.
| Parameter | Description |
|---|---|
| Type | You can create four types of applications: Standard, Insights Hub Monitor Plugin, Mobile and API. |
| Infrastructure | Three types of infrastructures are available: Cloud Foundry, Self-hosted and None (valid for mobile apps). |
| 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:
| Parameter | Description |
|---|---|
| Components | Adding components to your application are used to structure your application and register it accordingly in the Industrial IoT 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 CF or 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. - The component name should be same as the application name in the .yml file. Accordingly, the name your application in the manifest file, or during the push operation. Otherwise, the upload of the application will fail. This is applicable for Cloud Foundry application only. |
| URL | - Enter the URL for the component for a CF application. The URL format should be valid in the format: https://<name>.apps.<region>-dev.mindsphere.io. - 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 Cloud Foundry or Self-hosted direct URL's have values. For new application, the "Edit" button will remain disabled since a new application is being added. |
| Matching Order | The Industrial IoT Gateway selects the first matching endpoint based on the request URL. Currently, there is no proximity matching available. You can add arbitrary paths including wildcards here except /api, as this is reserved for calling the APIs from the browser client of your application. The mapping matches URLs using the following rules: ?matches one character **matches zero or more directories in a path a specific path, e.g./machines a path with wildcard/machines/* a patch with general wildcard/**that matches also zero or more sub paths. Examples /machines/drill-? matches machines/drill-1 but also machines/drill-2 or machines/drill-a /monitoring/machines/drill-* - matches all drill-* endpoints in the /monitoring/machines endpoint /machines/**/list matches all list endpoints underneath the /machines path. |
"Configurations" screen:
For Standard, Insights Hub Monitor Plugin, and API applications
For 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. |
| Deep link 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.
| Parameter | Description |
|---|---|
| API dependencies for applications (for standard, Insights Hub Monitor Plugin, and mobile applications) | A user can 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 /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:
- Log in to Developer Cockpit.
- In "Dashboard", click “Add application”.
- Enter the field parameters as per the parameters table.
- Upload the icon in the "App icon" field.
- In the "Component" tab, enter the component's name and URL and click "Add Endpoint" to add the component.
- In the "Configuration" tab, verify the configurations of the application.
- In the "API dependencies" tab, click the "Add API Dependency" and select the API dependency and then click "Add" (optional).
- 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.
Next steps¶
- Register the application. For more information on registering applications, see Register an application.
- 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.
Last update: January 22, 2024