Skip to content

MindSphere SDK V2 for Java – Getting Started

Prerequisites to use the MindSphere SDK V2 for Java

  • Java 8 is available
  • Gradle or Maven is used as build tool
  • User authorization token or service credentials with required scopes for APIs are available
  • Environment variable HOST_ENVIRONMENT is 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 defaults to eu1.

Hint

Service credentials 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

Attention

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

Installation Instructions

Downloading the MindSphere SDK V2 for Java

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

1
2
3
com\siemens\mindsphere\mindsphere-sdk-java-core\{x.y.z}\mindsphere-sdk-java-core-{x.y.z}.jar
com\siemens\mindsphere\mindsphere-sdk-java-core\{x.y.z}\mindsphere-sdk-java-core-javadoc.jar
com\siemens\mindsphere\mindsphere-sdk-java-core\{x.y.z}\mindsphere-sdk-java-core.pom
1
2
3
com\siemens\mindsphere\{serviceName}-sdk\{x.y}\{serviceName}-sdk-{x.y}.jar
com\siemens\mindsphere\{serviceName}-sdk\{x.y}\{serviceName}-sdk-{x.y}-javadoc.jar
com\siemens\mindsphere\{serviceName}-sdk\{x.y}\{serviceName}-sdk-{x.y}.pom

Note

  • {x.y.z} is the version number of the MindSphere Core SDK for Java (e.g. 2.0.0).The file {serviceName}-sdk-{x.y.z}.pom is required for downloading the transitive dependencies of the MindSphere Core SDK for Java.
  • {x.y} is the version number of the API Specification (e.g. 3.0). The file {serviceName}-sdk-{x.y}.pom is required for downloading the transitive dependencies of the MindSphere Service SDK for Java.

Adding MindSphere SDK V2 Dependencies

  1. Create the core and service module folder structure as your local Maven repository :

    1
    2
    3
    $PATH\com\siemens\mindsphere\mindsphere-sdk-java-core\{x.y.z}\mindsphere-sdk-java-core-{x.y.z}.jar
    $PATH\com\siemens\mindsphere\mindsphere-sdk-java-core\{x.y.z}\mindsphere-sdk-java-core-javadoc.jar
    $PATH\com\siemens\mindsphere\mindsphere-sdk-java-core\{x.y.z}\mindsphere-sdk-java-core.pom
    
    1
    2
    3
    $PATH\com\siemens\mindsphere\{serviceName}-sdk\{x.y}\{serviceName}-sdk-{x.y}.jar
    $PATH\com\siemens\mindsphere\{serviceName}-sdk\{x.y}\{serviceName}-sdk-{x.y}-javadoc.jar
    $PATH\com\siemens\mindsphere\{serviceName}-sdk\{x.y}\{serviceName}-sdk-{x.y}.pom
    

    where $PATH is:

    • On Mac: ~/.m2/repository
    • On Windows: C:\Users\{username}\.m2\repository
    • On Linux: /home/{User_Name}/.m2/repository
  2. Register the repository and include dependencies in the build config file of your project.

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    <!-- Modify the following sections of the pom.xml file -->
    <!-- 1. Register the repository in the repositories section -->
    <repositories>
          <repository>
              <id>maven-repository</id>
              <url>file:///{absolute path of the repository folder}</url>
          </repository>
      </repositories>
    
    <!-- 2. Add Core dependency in the dependencies section (optional) -->
    <dependency>
        <groupId>com.siemens.mindsphere</groupId>
        <artifactId>mindsphere-sdk-java-core</artifactId>
        <version>{x.y.z}</version>
    </dependency>
    
    <!-- 3. Add Service dependency in the dependencies section -->
    <dependency>
        <groupId>com.siemens.mindsphere</groupId>
        <artifactId>{serviceName}-sdk</artifactId>
        <version>{x.y}</version>
    </dependency>
    
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    // Modify the following sections of the build.gradle file
    // 1. Register the repository in the repositories section
    repositories {
            maven {
              url file('{Absolute path of the created repository folder}')
            }
            mavenLocal()
            mavenCentral()
    }
    
    // 2. Add Core dependency in the dependencies section (optional)
    compile 'com.siemens.mindsphere:mindsphere-sdk-java-core:{x.y.z}'
    
    // 3. Add Service dependency in the dependencies section
    compile 'com.siemens.mindsphere:{servicename}-sdk:{x.y}'
    

    Note

    All the MindSphere service modules have an implicit dependency on the core module, so adding the core module dependency is optional.

API Client and Credentials Configuration

The lowest-level building blocks of the API are RestClientConfig and MindsphereCredentials. These objects are instantiated using a builder pattern and shared between client instances.

Client Configuration

The following code block shows an example of how to build a RestClientConfig object:

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

The RestClientConfig can be configured using the following optional parameters:

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

Credentials Configuration

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

Code sample with user token:

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

Code sample with technical token credentials:

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

The following configuration parameters are available for the MindsphereCredentials object:

Name Description Type Use Case
authorization Bearer token, if developer application already generated it. String user token
clientId Service credential Id String technical token credentials
clientSecret Service credential String technical token credentials
tenant Name of the developer tenant String technical token credentials

API client instantiation and usage

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

Code sample using the IoT TimeSeries 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
31
@RequestMapping(method = RequestMethod.GET, value = "/{entity}/{propertySetName}")
public Timeseries 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)
                                  .hostEnvironment("host-environment")
                                  .build();

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

    Timeseries timeseriesData = null;
    try {
      timeseriesData = timeseriesClient.getTimeseries(entity, propertySetName, null, null, null, null);
    } 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.