Skip to content

Getting started

Prerequisites

  • Java 8
  • Gradle or Maven as build tool
  • User authorization token or service credentials with required scopes for APIs
  • Environment variable HOST_ENVIRONMENT set to current region. When hosting an application in Cloud Foundry, the variable must be added in the manifest file:

    1
    2
    env:
      HOST_ENVIRONMENT: eu1
    

    If not specified, HOST_ENVIRONMENT will default to eu1.

  • In case you are using service credentials, they can be set as environment variables, so the client can fetch a token itself.

    • MINDSPHERE_CLIENT_ID
      Specify service credential ID

    • MINDSPHERE_CLIENT_SECRET
      Specify service credential

    • MINDSPHERE_TENANT
      Specify tenant name

    Note

    Setting environment variables for service credentials is not mandatory. Service credentials or user tokens can be set as parameters in the MindsphereCredentials object as explained below in API client and credentials configuration.

    Attention

    The developer/customer is responsible for keeping the credentials safe. It is the decision of the developer/customer, whether it is safe enough to supply the credentials via environment variables.

    Requesting service credentials

    For requesting service credentials, see Create Service Credentials.

Installation instructions

Downloading the MindSphere SDK

Download the MindSphere SDK for Java from the Siemens Industry Online Support (SIOS) Portal. The jar and pom files of the downloaded archive have the following structure:

1
2
3
  mindsphere\mindsphere-sdk\x.y.z\mindsphere-sdk-x.y.z.jar
  mindsphere\mindsphere-sdk\x.y.z\mindsphere-sdk-x.y.z-javadoc.jar
  mindsphere\mindsphere-sdk\x.y.z\mindsphere-sdk-x.y.z.pom

Note

x.y.z is the version number of the MindSphere SDK for Java (e.g. 1.0.0).

The file mindsphere-sdk-x.y.z.pom is required for downloading the transitive dependencies of the MindSphere SDK for Java.

Adding SDK dependency for projects using Maven as a build tool

  • Create SDK folder structure in your local Maven repository:

    1
    2
    3
    $PATH\mindsphere\mindsphere-sdk\x.y.z\mindsphere-sdk-x.y.z.jar
    $PATH\mindsphere\mindsphere-sdk\x.y.z\mindsphere-sdk-x.y.z-javadoc.jar
    $PATH\mindsphere\mindsphere-sdk\x.y.z\mindsphere-sdk-x.y.z.pom
    

    where $PATH is:

    • On Mac : ~/.m2/repository
    • On Windows : C:\Users\{username}\.m2\repository
    • On Linux : /home/{User_Name}/.m2/repository
  • Add dependency in pom.xml:

    1
    2
    3
    4
    5
    <dependency>
        <groupId>mindsphere</groupId>
        <artifactId>mindsphere-sdk</artifactId>
        <version>x.y.z</version>
    </dependency>
    

Adding SDK dependency for projects using Gradle as a build tool

  • Create SDK folder structure in your local Maven repository or create a similar folder structure anywhere in your system:

    1
    2
    3
    $PATH\mindsphere\mindsphere-sdk\x.y.z\mindsphere-sdk-x.y.z.jar
    $PATH\mindsphere\mindsphere-sdk\x.y.z\mindsphere-sdk-x.y.z-javadoc.jar
    $PATH\mindsphere\mindsphere-sdk\x.y.z\mindsphere-sdk-x.y.z.pom
    

    where $PATH is:

    • On Mac : ~/.m2/repository
    • On Windows : C:\Users\{username}\.m2\repository
    • On Linux : /home/{User_Name}/.m2/repository
  • Advice gradle to look at the local Maven repository in build.gradle of your project as follows:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    repositories {
        mavenLocal()
        mavenCentral()
    
        // Use this if SDK jars are not placed in local maven repository.
        maven {
            url file('{Absolute path of the created repository folder}')
        }
    }
    
  • Add dependency in build.gradle:

    1
        compile 'mindsphere:mindsphere-sdk:x.y.z'
    

Once the build is complete, all transitive dependencies of the MindSphere SDK for Java are downloaded to your application.

API client and credentials configuration

The lowest-level building blocks of the API are RestClientConfig and MindsphereCredentials. These objects will be created and shared between client instances. A builder pattern is used to instantiate them.

Client Configuration

The RestClientConfig object can be built using configuration parameters. Currently all parameters are optional.

1
2
3
4
5
RestClientConfig config = RestClientConfig.builder()
                              .connectionTimeoutInSeconds(100)
                              .proxyHost("host")
                              .proxyPort(8080)
                              .build();

The following parameters can be configured for the RestClientConfig object:

Name Description Type Default value
connectionTimeoutInSeconds Connection timeout in seconds Integer 100
socketTimeoutInSeconds Socket timeout in seconds Integer 100
proxyHost Host address of proxy String
proxyPort Proxy port Integer
proxyUsername Username to login to the proxy String
proxyPassword Password to login to the proxy String
proxySchema Schema used by the proxy String http

Credentials Configuration

The MindsphereCredentials object can be built directly with the user token or with the technical token credentials. If credentials are set via environment variables, there is no need to build the MindsphereCredentials object.

A code sample with user authorization token:

1
2
3
MindsphereCredentials credentials = MindsphereCredentials.builder()
                                        .authorization("usertokenFromRequestHeader")
                                        .build();

A code sample with service credentials:

1
2
3
4
5
MindsphereCredentials credentials = MindsphereCredentials.builder()
                                        .clientId("ClientId")
                                        .clientSecret("ClientSecret")
                                        .tenant("TenantName")
                                        .build();

The following parameters can be configured for the MindsphereCredentials object:

Name Description Type Mandatory
authorization Bearer token, if developer application already generated it. String Required for user token
clientId Service credential Id String Required for user with service credential
clientSecret Service credential String Required for user with service credential
tenant Name of the developer tenant String Required for user with service credential

API client instantiation and usage

An API client instance requires a RestClientConfig and a MindsphereCredentials instance passed as parameters using a builder pattern.

A code sample using the IoT Time Series API client:

 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
@RequestMapping(method = RequestMethod.GET, value = "/{entity}/{propertySetName}")
public TimeseriesData getTimeSeriesAsObject(@PathVariable("entity") String entity,
    @PathVariable("propertySetName") String propertySetName,
    @RequestHeader("Authorization") String token) throws MindsphereException
{

    MindsphereCredentials credentials = MindsphereCredentials.builder()
                                            .authorization(token)
                                            .build();

    RestClientConfig config = RestClientConfig.builder()
                                  .connectionTimeoutInSeconds(100)
                                  .proxyHost("host")
                                  .proxyPort(portnumber)
                                  .build();

    TimeseriesClient timeseriesClient = TimeseriesClient.builder()
                                            .mindsphereCredentials(credentials)
                                            .restClientConfig(config)
                                            .build();

    TimeseriesData timeseriesData = null;
    try {
      timeseriesData = timeseriesClient.getLatestTimeseries(entity, propertySetName);
    } catch (MindsphereException e) {
      // Exception handling
    }

    return timeseriesData;
}

Any questions left?

Ask the community


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