Get Started

When creating or updating an Analytics Framework service instance, you can pass the configuration parameters in a file instead of as a single line.

{
  "trustedIssuerIds": [
    "<uaa_instance_issuerId>"
  ],
  "runtimeClientId": "<my_runtime_client_id>",
  "runtimeClientSecret": "<my_runtime_client_secret>",
  "predixAssetZoneId": "<my_predix_asset_zone_id>",
  "predixTimeseriesZoneId": "<my_predix_timeseries_zone_id>"
}

cf update-service <my_service_instance> -c myFile.txt

Create a new service using Predix console as follows. Alternatively, you can create the service from the command line.

1. Sign into your Predix account, then navigate to Catalog > Services > Analytics Framework tile.
2. Select the desired plan and click Subscribe.

   The New service instance page displays. Complete the fields in this form to create a new Analytics Framework service instance. Required fields are noted by an asterisk (*).

3. Select the desired Org, then the Space, from list. Once the creation process is completed, the new service instance will reside in selected location in Predix cloud.
4. From the User Account & Authentication (UAA) field, select the UAA instance to act as the authenticator for the service instance.
   • Select existing UAA: Select the UAA instance name from the list. You can create or modify OAuth2 clients using the Client Management tab in the UAA Dashboard.
   • Subscribe to New UAA: Select to create a new UAA instance. Click the plus (+) symbol for instructions.
5. Complete the configuration fields as follows. Save the values you provide for future use.

   Feature	Field	Description
   Scheduler	Runtime client id	Provide a non-admin UAA client id to be used for running scheduled jobs. Note: It is recommended that the client have a non-expiring refresh token to accommodate long running scheduled jobs.
   Scheduler	Runtime client secret	Provide the UAA client secret. If you have forgotten this value, you can create a new UAA Client and save the client secret for future use.

6. Click Create Service.

   The service instance is created in the Org and Space specified.

Create a new service instance using the command line as follows. Alternatively, you can create the service from Predix Console using the New service instance page.

cf create-service predix-analytics-framework <plan> <my_framework_instance> -c '{ "trustedIssuerIds": [ "<uaa_instance_issuerId>" ], "runtimeClientId": "<my_runtime_client_id>", "runtimeClientSecret": "<my_runtime_client_secret>", "predixAssetZoneId": "<my_predix_asset_zone_id>", "predixTimeseriesZoneId": "<my_predix_timeseries_zone_id>"}'

Analytics Framework requires three dedicated OAuth2 clients to fully manage all service features. Configure the OAuth2 clients to manage authentication for the service.

1. In Predix Console, navigate to the UAA instance managing your Analytics Framework service instance.
2. Log into UAA Dashboard, then navigate to the Client Management tab.
3. Choose an existing client from the list or choose the Add a new client option. If you chose to add a new client, follow the steps in Creating an OAuth2 Client.
4. Configure each of the clients as follows.

   Configuration Field	Value	Description
   Authorized Grant Types	Analytics Framework client: Select either client_credentials or password, according to your needs. Scheduler client: Select password and refresh_token.	Minimum values required. You can add additional values as needed.
   Scope	Both clients require the following scope: analytics.zones.<service_instance_guid>.user	When a service is protected by UAA, the scope controls what type of access is allowed to the service. The service scope must be registered with UAA. To enable applications to access the Analytics Framework service, your JSON Web Token (JWT) must contain the correct scopes.
   Authorities	Both clients require the following authority: analytics.zones.<service_instance_guid>.user
   Refresh Token Validity	Analytics Framework client: Any value is acceptable. Scheduler: Provide a non-expiring token value.

5. Clients who use the password grant type or refresh token grant type (Scheduler clients) require a UAA user who is a member of the analytics.zones.<service_instance_guid>.user group.
   To create the group, follow the steps in the Creating Groups in a UAA Instance documentation. To create a user and add the user as a member of the group, follow the steps in the Creating Users in a UAA Instance documentation.

1. Create or configure an OAuth2 client, preferably a dedicated client.

   It is recommended that you create a dedicated OAuth2 client for this purpose in order to give minimum privileges to this client, though you can use an existing client if desired. In either case, this client must be properly set up with the following requirements.

   1. The client must be authorized with the refresh_token and password grant types. The client must also have the necessary scopes to authorize with the job execution endpoint. For example, in the case where the job execution endpoint is the orchestration execution service, the refresh token must have the analytics.zones.<analytics-framework-instance-id>.user scope.

      For more information, see Creating an OAuth2 Client and Updating the OAuth2 Client that uses Other Authorization Grant Types.

   2. The refresh_token_validity attribute for the client must be configured to validate the refresh token for the duration of the job being scheduled. For example, if you are scheduling the job to run an orchestration for one year, the refresh token must be valid for one year. This can be configured by running the following uaac command: "uaac client update <client-id> --refresh_token_validity <seconds>".
2. Create a UAA user who is a member of the group analytics.zones.<service_instance_guid>.user. Follow the steps in the Using UAAC to Create Users in a UAA Instance documentation.
3. Ensure your OAuth2 client and user are set up properly. Follow the steps in Validating an OAuth2 Client for Scheduler.
4. Configure your existing Analytics Framework instance to enable scheduler. You must provide the values of "trustedClientCredential" configuration with the client credential of the dedicated OAuth2 client. Follow the steps in Updating an Analytics Framework Service Instance.

1. Make a call to the OAuth2 token issuer to get an OAuth2 access token with a Password grant type. For more information, see Obtaining an OAuth2 Access Token for Analytics Services.
2. Using the "access_token" element of the response, ensure that the job execution endpoint can be invoked successfully.
3. Using the "refresh_token" element of the response, ensure that you can obtain a new access token by making a new call to the OAuth2 token issuer with the following parameters.
   • HTTP Method: POST
   • HTTP Endpoint: <OAuth2 token issuer>
   • HTTP Header: Key = Authorization, Value = basic <base 64-encoded string of client-id:client-secret>. For example, Authorization: basic bXktY2xpZW50LWlkOm15LWNsaWVudC1zZWNyZXQ=.
4. Using the “access_token” element of the newly acquired OAuth2 token, ensure that the job execution endpoint can be invoked successfully.

You can update your Analytics Framework service instance to add functionality by running the cf update-service command with the new configuration parameters.

You can create service keys in order to retrieve service details needed to access the Analytics Framework APIs from outside the Cloud Foundry environment.

1. Run the following command to create a service key.

   cf create-service-key <service-instance-name> <service-key-name>

2. Run the following command to print out the service key.

   cf service-key <service-instance-name> <service-key-name>

   The output lists the service details needed to access the API from outside of the Predix Cloud. Messages similar to the following are returned, depending upon how your service instance is configured.

   {
    "catalog_uri": "<catalog_uri>",
    "config_uri": “<config_uri>",
    "configurations": {
     "predix_asset_zone_id": "<my_asset_zone_id>",
     "predix_timeseries_zone_id": "<my_timeseries_zone_id>",
     "runtime_client_id": "<my_runtime_client_id>",
     "trusted_issuer_ids": "<my_trusted_issuer_id>"
    },
    "execution_uri": "<execution_uri>",
    "monitoring_uri": "<monitoring_uri>",
    "scheduler_uri": "<scheduler_uri>",
    "zone-http-header-name": "Predix-Zone-Id",
    "zone-http-header-value": "<my_predix_zone_id>",
    "zone-oauth-scope": "analytics.zones.<my_predix_zone_id>.user"
   }

Binding your Analytics Framework service instance to your application provisions connection details in the VCAP_SERVICES environment variable. Cloud Foundry runtime uses VCAP_SERVICES environment variable to communicate with a deployed application about its environment.

cf bind-service <app_name> <my-framework-instance>

Binding service <my-framework-instance> to app <app_name> in org <org_name> / space <space_name> as [email protected]...
OK
TIP: Use 'cf restage' to ensure your env variable changes take effect

cf unbind-service <app_name> <my-framework-instance>

After an application is bound to the service, you can retrieve details about the instance from VCAP_SERVICES environmental variable.

cf env <app_name>

System-Provided:
{
 "VCAP_SERVICES": {
  "predix-analytics-framework": [
   {
    "credentials": {
     "catalog_uri": "<catalog_uri>",
     "config_uri": "<config_uri",
     "configurations": {
      "predix_asset_zone_id": "<my_asset_zone_id>",
      "predix_timeseries_zone_id": "<my_timeseries_zone_id>",
      "runtime_client_id": "<my_runtime_client_id>",
      "trusted_issuer_ids": "<my_trusted_issuer_id>"
     },
     "execution_uri": "<execution_uri>",
     "monitoring_uri": "<monitoring_uri>",
     "scheduler_uri": "<scheduler_uri>",
     "zone-http-header-name": "Predix-Zone-Id",
     "zone-http-header-value": "<my_predix_zone_id>",
     "zone-oauth-scope": "analytics.zones.<my_predix_zone_id>.user"
    },
    "label": "predix-analytics-framework",
    "name": "<my_framework_instance>",
    "plan": "Tiered",
    "provider": null,
    "syslog_drain_url": null,
    "tags": [],
    "volume_mounts": []
   }
  ]
 }
}

Predix services are protected by UAA. You must use an Authorization header to pass the OAuth2 access token when issuing REST requests to your service instance. Follow this process to obtain an OAuth2 access token.

POST <uaa_instance_issuerId>

{
  "access_token":<generated_access_token>,
  "token_type":"bearer",
  "expires_in":3600
}

The Analytics Framework service REST API endpoints provide a JSON interface for passing data. The application makes HTTPS requests to these API interfaces.

UAA Authorization

• Header name: "Authorization"
• Header value: "Bearer <token obtained from trusted issuer>". For more information, see Obtaining an OAuth2 Access Token for Analytics Services.

Predix Zone

• Header name: The zone-http-header-name from the VCAP_SERVICES environment variable for your Analytics Framework instance. For example, Predix-Zone-Id.
• Header value: The zone-http-header-value from the VCAP_SERVICES environment variable for your Analytics Framework instance. For example, ba99ab7b-172f-4fe4-8ce9-45afa8a4ab0c.

The following figure shows an example of how to set up the headers for a REST request in Postman.

For information about retrieving VCAP environment variables, see Verifying the Binding.

You must first delete all subscription analytics from the Analytics Catalog before you delete the Analytics Framework service instance.

1. Required: Delete all subscription analytics from the Analytics Catalog. This removes them from future subscription billing.

   You can delete the analytics using either the REST API call method or the UI method.

2. Delete the Analytics Framework service instance by issuing the following REST API call.

   cf delete-service <my-service-instance>

   Where <my-service-instance> is the name of your Analytics Framework service instance.

   Note: The delete action will fail with an error message if any subscription analytics still remain in the catalog. In this case, delete any subscription analytics and try again.