Skip to content

Self-Hosted Application – Integration into MindSphere

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

Requirements for Self-Hosted Applications

The following requirements apply for integrating your self-hosted application into MindSphere:

  • You have the Outbound Traffic Upgrade (Contact Sales for this upgrade.)
  • 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 self-hosted application uses the MindSphere Identity Management.
  • Your self-hosted application is registered in the MindSphere 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)

Creating a Health Endpoint

MindSphere expects your application to provide a health endpoint, so that it can periodically perform checks, e.g. whether your application is up and running.

GET /health/

Responses

HTTP Status Description Content
200 OK Response content type: application/json
Model: see below
401 Unauthorized None
426 Update Required None

Schema

Property Type Values Example
healthStatus string enumeration: [green, yellow, red] green
time string ISO-8601 timestamp in the following format: YYYY-MM-DDTHH:mm:ss.sssZ "2018-10-04T07:58:49.369Z"

The following snippet shows an example response:

1
{'healthStatus': 'green', 'time': '2018-09-21 08:56:24'}

Health Endpoint

At the moment, the health endpoint cannot be configured in the Developer Cockpit, but will be mandatory in the future.

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
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    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:

    1
    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:

    1
    Retrieved no authorization header
    

In this example, the application expects that the MindSphere 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 the Developer Cockpit to integrate with MindSphere's Identity and Access Management Roles & Scopes.

Productive Usage

The process described above is not suitable for production. We advise to use a suitable concept to host and run your application.

Configuring your Self-Hosted Application in the Developer Cockpit

Prerequisites

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

Creating the Application

  1. Open the "Dashboard" tab of the Developer Cockpit.
  2. Click on "Create new application".
  3. Fill in 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 on "Save" to create the application.

Filled in form for self-hosted applications in Developer Cockpit

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 on "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.

Firewall Settings

MindSphere applications running on Cloud Foundry access the internet via a NAT gateway. If you want to enable these applications to access your application server, your inbound firewall must allow the NAT gateway's IP addresses:

1
2
3
35.156.223.10
18.194.162.141
18.194.195.179

Submitting your Self-Hosted Application to the MindSphere Store

Prerequisites

  • Your application is configured and registered in the Developer Cockpit.
  • The MindSphere OS Bar is integrated into your application.
  • You have prepared a screenshot of your application showing the top-level site including the MindSphere 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 on "Prepare release".
  3. Select a screenshot of your application and then click on "Upload".
  4. Fill in the application description.
  5. Click on "Submit".

Fill in Prepare Release dialogue for self-hosted applications in Developer Cockpit

Approve Upload

  1. Navigate to the details view of your application.
  2. Click on "Approve Upload".
  3. Enter an "Alternate Email" address of your substitute.
  4. Read and accept the IMPORTANT NOTICE information.
  5. Click on "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 MindSphere requirements.

Any questions left?

Ask the community


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