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
    Specifies service credentials ID

  • MINDSPHERE_CLIENT_SECRET
    Specify service credentials secret

  • MINDSPHERE_TENANT
    Specifies the tenant name

Attention

You are responsible for keeping the credentials safe. You decide whether it is safe 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\{service_name}-sdk\{x.y}\{service_name}-sdk-{x.y}.jar
com\siemens\mindsphere\{service_name}-sdk\{x.y}\{service_name}-sdk-{x.y}-javadoc.jar
com\siemens\mindsphere\{service_name}-sdk\{x.y}\{service_name}-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 {service_name}-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 {service_name}-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\{service_name}-sdk\{x.y}\{service_name}-sdk-{x.y}.jar
    $PATH\com\siemens\mindsphere\{service_name}-sdk\{x.y}\{service_name}-sdk-{x.y}-javadoc.jar
    $PATH\com\siemens\mindsphere\{service_name}-sdk\{x.y}\{service_name}-sdk-{x.y}.pom
    

    where $PATH is:

    • On Mac: ~/.m2/repository
    • On Windows: C:\Users\{user_name}\.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>{service_name}-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:{service_name}-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 with a user token or with service credentials to fetch a technical token.

The following configuration parameters are available for the MindsphereCredentials object:

Name Description Type Use Case
authorization Bearer token, if available. String user token
keyStoreClientId App service credential ID String technical token
keyStoreClientSecret App service credential secret String technical token
appName Application name String technical token
appVersion Application version String technical token
hostTenant Host tenant String technical token
userTenant User tenant String technical token
clientId Tenant service credentials ID String technical token
clientSecret Tenant service credentials secret String technical token
tenant Tenant String technical token

Refer to the code samples for creating MindsphereCredentials objects for more information.

API Client Instantiation and Usage

An API client instance using RestClientConfig and MindsphereCredentials objects passed as (optional) parameters using a builder pattern.

Code sample using the IoT TimeSeries API client, placeholders are indicated by angluar brackets < >:

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

    //Construct MindsphereCredentials object
    MindsphereCredentials credentials = MindsphereCredentials.userTokenBuilder()
                                            .authorization(token)
                                            .build();

    //Construct RestClientConfig object
    RestClientConfig config = RestClientConfig.builder()
                                  .connectionTimeoutInSeconds(100)
                                  .proxyHost("my.proxy.host")
                                  .proxyPort("1.2.3.4")
                                  .hostEnvironment("eu1")
                                  .build();

    //Construct TimeSeriesClient object
    TimeSeriesClient timeseries_client = TimeSeriesClient.builder()
                                            .mindsphereCredentials(credentials)
                                            .restClientConfig(config)
                                            .build();

    //Construct GetTimeseriesRequest object
    GetTimeseriesRequest request_object = new GetTimeseriesRequest();
    request_object.setEntity(entity);
    request_object.setPropertysetname(propertySetName);
    request_object.setFrom(<from_time>);
    request_object.setTo(<to_time>);

    List<TimeseriesData> timeseries_data_list = null;
    try {
        timeseries_data_list = timeseries_client.getTimeseries(request_object);
    } catch (MindsphereException e) {
        // Exception handling
    }

    return timeseries_data_list;
}

Any questions left?

Ask the community


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