Using the Time Series Client Library

The Time Series client must be included in your project.

1. Update your Maven settings to use the Predix platform Artifactory by copying the following into the <servers> block of your settings.xml file, located in your ~/.m2 folder:

   <server>
       <id>artifactory.external</id>
       <username><predix-user-name></username>
       <password><predix-password></password>
   </server>

   where <predix-user-name> and <predix-password> are your Predix.io user name and password.
   Optionally, you can encrypt your password instead of using plain text. See Password Encryption.
2. Add the repository to the POM file located in your project's root directory:

   <repositories>
         <repository>
            <id>artifactory.external</id>
            <name>GE external repository</name>
            <url>https://artifactory.predix.io/artifactory/PREDIX-EXT</url>
         </repository>
   </repositories>

3. Add the Time Series client as a dependency in your POM file:

   <dependency>
       <groupId>com.ge.predix.timeseries</groupId>
       <artifactId>timeseries-client</artifactId>
       <version>0.0.2-SNAPSHOT</version>
   </dependency>
   

1. Provide the configuration information to use the Time Series client library.
   1. Bind your application to your Time Series service instance (tss-setup-configure.html#task_fac802b9-5075-41dd-bd90-2a5bc261f998).
   2. To retrieve the values needed to configure the Time Series client library, enter the following command at the Cloud Foundry CLI:

      cf env <application_name>

      The environment variables for your application (including the ingestion and query URLs) are returned to you. Make note of the environment variables.
   3. Create a file called predix-timeseries.properties and add the configuration information retrieved in the previous step.
      Note: The predix-timeseries.properties file is required to use the Time Series client library. However, if you are using the createTenantContextFromProvidedProperties method (shown in Step 2), the URIs, client id, and secrets properties in the "Execution properties" section are not used.

      # Predix Timeseries configuration. >>>>>
      # DO NOT MODIFY WITHOUT CONSULTING PREDIX SUPPORT
      predix.timeseries.maxTagsPerQuery=5
      predix.timeseries.maxIngestionMessageSize=512000
      # Predix Timeseries configuration. <<<<<
      
      #Purchased Plan restrictions. >>>>>
      # MODIFY TO SUIT YOUR PLAN. GOING OVER MIGHT RESULT IN ADDED CHARGES
      plan.ingestion.concurrent.connections.max=100
      plan.query.concurrent.connections.max=100
      #Purchased Plan restrictions. <<<<<
      
      #Execution properties. >>>>>
      # MODIFY AS APPROPRIATE
      
      #Execution properties. <<<<<
      
      uaa.uri=<your uaa uri. (without the /oauth/token)>
      ingestion.uri=<ingestion uri obtained from the binding to Predix time-series>
      ingestion.zone-http-header-name=Predix-Zone-Id
      ingestion.client.id=<the client id that has scope access to 'timeseries.zones.<your zone id>.ingest'>
      ingestion.client.secret.env.variable=<environment variable that contains the ingestion client secret>
      query.uri=<query uri obtained from the binding to Predix time-series>
      query.zone-http-header-name=Predix-Zone-Id
      query.client.id=<client id that has scope access to 'timeseries.zones.<your zone id>.query'>
      query.client.secret.env.variable=<environment variable that contains the query client secret>
      

      Note: The client secret is an environment variable that you set on your local machine, which contains a password that you set. Add the name of the environment variable you created as the client secret. If you have two different client IDs (one for ingestion, one for querying), create two different environment variables with two different passwords.
   4. Save the predix-timeseries.properties file and add it to your project.
   5. To provide the path to the predix-timeseries.properties file, add the following line to your code:

      TenantContext tenant=TenantContextFactory.createTenantContextFromPropertiesFile<propertiesPath>;

2. If you already have the Time Series URLs and authorization tokens available in your code, you can directly provide the configuration information programatically.
   To use both the ingestion and query client, add the following code:

   TenantContext tenant=TenantContextFactory.createTenantContextFromProvidedProperties<queryUri, queryAccessToken, ingestionUri, ingestionAccessToken, zoneHeaderName, zoneId>

   To use the ingestion client only, add the following code:

   TenantContext tenant = TenantContextFactory.createIngestionTenantContextFromProvidedProperties(ingestionUrl, authToken, predixZoneIdHeaderName, predixZoneIdHeaderValue);

   To use the query client only, add the following code:

   TenantContext tenant = TenantContextFactory.createQueryTenantContextFromProvidedProperties(queryUrl, authToken, predixZoneIdHeaderName, predixZoneIdHeaderValue);
   

Learn how to create a time series data ingestion request using the example in this topic.

Integer sensorValueAsInt = (int) Math.random();
Double sensorValueAsDouble = Math.random();
IngestionRequestBuilder ingestionBuilder = IngestionRequestBuilder.createIngestionRequest()
        .withMessageId("<MessageID>")
        .addIngestionTag(IngestionTag.Builder.createIngestionTag()
                .withTagName("TagName")
                .addDataPoints(
                        Arrays.asList(
                                new DataPoint(new Date().getTime(), sensorValueAsInt, Quality.GOOD),
                                new DataPoint(new Date().getTime(), sensorValueAsDouble, Quality.NOT_APPLICABLE),
                                new DataPoint(new Date().getTime(), "Bad Value", Quality.BAD),
                                new DataPoint(new Date().getTime(), null, Quality.UNCERTAIN)
                        )
                )
                .addAttribute("AttributeKey", "AttributeValue")
                .addAttribute("AttributeKey2", "AttributeValue2")
                .build());

String json = ingestionBuilder.build().get(0);
IngestionResponse response = ClientFactory.ingestionClientForTenant(ingestionTenant).ingest(json);
String responseStr = response.getMessageId() + response.getStatusCode();

The client library also offers a Query Builder that interfaces with the Time Series service and return a QueryResponse object.

QueryBuilder builder = QueryBuilder.createQuery()
        .withStartAbs(1427463525000L)
        .withEndAbs(1427483525000L)
        .addTags(
                QueryTag.Builder.createQueryTag()
                        .withTagNames(Arrays.asList("ALT_SENSOR", "TEMP_SENSOR"))
                        .withLimit(1000)
                        .addAggregation(Aggregation.Builder.averageWithInterval(1, TimeUnit.HOURS))
                        .addFilters(FilterBuilder.getInstance()
                                .addAttributeFilter("host", Arrays.asList("<host>")).build())
                        .addFilters(FilterBuilder.getInstance()
                                .addAttributeFilter("type", Arrays.asList("<type>")).build())
                        .addFilters(FilterBuilder.getInstance()
                                .addMeasurementFilter(FilterBuilder.Condition.GREATER_THAN_OR_EQUALS, Arrays.asList("23.1")).build())
                        .addFilters(FilterBuilder.getInstance()
                                .withQualitiesFilter(Arrays.asList(Quality.BAD, Quality.GOOD)).build())
                        .build());
QueryResponse response = ClientFactory.queryClientForTenant(tenant).queryAll(builder.build());