Self-Hosted Application – Integration into Insights Hub¶

It is possible to integrate the applications hosted outside of Insights Hub. They are called self-hosted applications, as Insights Hub does not manage and operate the infrastructure that powers them. This section illustrates how to develop such an application and integrate it into Insights Hub.

Requirements for Self-Hosted Applications¶

The following requirements apply for integrating your self-hosted 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 Insights Hub's internal monitoring.
• Your self-hosted application uses the Insights Hub Identity Management.
• Your self-hosted application is registered in the Gateway.

Preparing the Application¶

Prerequisites¶

• You need access to some infrastructure, e.g. server, which is accessible from the internet
• The hosted application must be available via a DNS name and must be secured with SSL (no self-signed certificates)

Deploying the application¶

1. Connect to the infrastructure on which you want to deploy the application.

2. Make sure that your application is available in the infrastructure. Alternatively, copy the following python example into a suitable place:

   Python Example

   from flask import Flask, request, jsonify
   import requests
   import os
   from datetime import datetime
   
   # Read MDSP environment from environment variables
   ENV = os.getenv("MDSP-ENV", 'eu1')
   ASSET_PATH = 'https://gateway.{0}.mindsphere.io/api/assetmanagement/v3/assets'.format(ENV)
   
   app = Flask(__name__)
   
   # Get port from environment variable or use default
   port = int(os.getenv("PORT", 80))
   
   @app.route('/')
   def hello_world():
       auth_header = request.headers.get('Authorization', None)
   
       if auth_header is not None:
           # Add headers for authorization (use token from requesting user) and the accept type
           headers = {'Authorization': auth_header, 'Accept': 'application/hal+json'}
           try:
               r = requests.get(ASSET_PATH, headers=headers)
               resp = r.json() # response as json
           except Exception as err:
               resp = str(err)
   
           try:
               return jsonify(resp) # return json response from MindSphere API
           except Exception as err:
               print('Failed to jsonify', err)
       else:
           return 'Retrieved no authorization header'
   
   @app.route('/health')
   def health_check():
       # do some checks and then return the result
       health = {
           'healthStatus': 'green',
           'time': datetime.utcnow().replace(tzinfo=datetime.timezone.utc).isoformat()
       }
   
       return jsonify(health)
   
   if __name__ == '__main__':
       app.run(host='0.0.0.0', port=port)
   

3. Start the application using the following command:

   python <filename>.py
   

4. Ensure that your application is reachable from the internet, e.g. by configuring security policies.

5. Try calling the application via https:\\{dnsname}\. You should receive the following error:

   Retrieved no authorization header
   

In this example, the application expects that the Insights Hub authorization header is present in the request. The authorization header is used for identifying the accessing user and related tenant from which to retrieve data. Next, the application has to be configured in Developer Cockpit to integrate with Insights Hub's Identity and Access Management Roles & Scopes.

Configuring your Self-Hosted Application in the Developer Cockpit¶

Prerequisites¶

• Your self-hosted application has been successfully deployed as described in the above section.
• Your self-hosted application is running and reachable from the internet.

Creating the Application¶

1. Open the "Dashboard" tab of Developer Cockpit.
2. Click "Create new application".
3. Enter the mandatory inputs (e.g., Name, Display Name, Version and App Icon).
4. Check the "Self Hosted Application" checkbox.
5. Add at least one component with an external URL, e.g. https://myapplication-123456789.eu-west-1.elb.amazonaws.com.
6. Click "Save" to create the application.

Registering the Application¶

1. Navigate to the "Roles & Scopes" tab.
2. Select your application.
3. Add at least one default scope, e.g. myselfhosted.default.
4. Add the core role mdsp:core:assetmanagement:standarduser (required for the python example).
5. Navigate back to the "Application Details" screen for your application.
6. Click on the "Register" button for your application.

Testing the Application¶

1. Open the "Settings" application.
2. Search and select your user name and click "Edit role assignment".
3. Search for the role mdsp:<tenant>:<application>.<role> (in this example mdsp:<tenant>:myselfhosted.user).
4. Log out and log in again.

Your application icon is now shown on the Launchpad and opens the application. If you are using the example application, the application shows a list of all assets available in your tenant.

Submitting your Self-Hosted Application to the Industrial IoT Store¶

Prerequisites¶

• Your application is configured and registered in Developer Cockpit.
• The OS Bar is integrated into your application.
• You have prepared a screenshot of your application showing the top-level site including the OS Bar.
• You have prepared a description of the application.
• You have the role mdsp:core:DeveloperAdmin.

Prepare Release¶

1. Navigate to the details view of your application.
2. Click "Prepare release".
3. Select a screenshot of your application and then click on "Upload".
4. Enter the application description.
5. Click "Submit".

Approve Upload¶

1. Navigate to the details view of your application.
2. Click "Approve Upload".
3. Enter an "Alternate Email" address of your substitute.
4. Read and accept the IMPORTANT NOTICE information.
5. Click "Approve".

Your application has been successfully submitted to the application repository. You and your alternate contact are notified once the application is ready for assignment or if it does not fulfill the Insights Hub requirements.

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