Skip to content

Getting Starting with the KX Insights Platform SDKs

This section aims to provide details on how to get started with the SDKs to ingest or query a KX Insights Platform deployment.

Separate SDKs, including sample programs can be downloaded from the KX Insights Nexus registry.

Authentication & Authorization

An application needs to be authorised to ingest data to and query data from the KX Insights Platform. Keycloak is used as the identity and access management platform for the KX Insights Platform. Before a user can ingest or query a KX Insights Platform deployment, they must:

  1. Login to Keycloak.
  2. Create a client.
  3. Assign roles to this client in Keycloak.
  4. Obtain a client secret (KC_CLIENT_SECRET) for this client.
  5. Obtain a INSIGHTS_ACCESS_TOKEN for this client using the client secret.
  6. Identify the [stream id] from the Sub Topic defined for the externally facing RT (also known as a KX Insights Stream) deployed in the assembly.
  7. With this access token to enrol this client against the client controller and retrieve a KXI_CONFIG_URL as follows:

    curl https://{INSIGHTS_HOSTNAME}/clientcontroller/enrol -H "Authorization: Bearer <INSIGHTS_ACCESS_TOKEN>" -d '{ "name": "client-1", "topics": { "<streamid>": "sdk-sample-assembly", "query": "requests" }}'
    {"message":"success","detail":"Client enrolled","url":"{KC_CLIENT_ID}"}
    

Once the user has the KC_CLIENT_ID the SDKs combine this with the INSIGHTS_HOSTNAME value as follows: https://{INSIGHTS_HOSTNAME}/informationservice/details/{KC_CLIENT_ID}, to find the Information Service which provides details on the SSL certs and the RT endpoints.

Ingesting Data

For a publisher to publish data into the KX Insights Platform using an SDK the following are required:

  • The ability to do HTTP/REST requests.
  • A port to your KX Insights Platform.
  • TLS for all communication.
  • A Publisher (click on the links below for getting started guides):
  • The publisher and subscriber must agree on:
    • stream id and parameter usage.
    • Message format.
  • Sufficient Storage: A client publisher can continue running when an assembly is torn down or the KX Insights Platform is offline. The SDKs regularly poll the Information Service for details on the SSL certs and the RT endpoints. If the Information Service or the endpoints are unavailable the KX Insights SDKs continue to write to the publisher's local disk and they ship the queued data as and when the assembly becomes available. 

In the event of the KX Insights Stream being unavailable

The publisher needs to be aware of the following: Disk space: While the assembly is unavailable, the data will continue to be written to a local log file on the client machine. Therefore there MUST be adequate disk provisioned to handle this build up. Timeout: The SDKs will stop if the Stream has been offline for an hour.

Querying Data

Querying data from a KX Insights Platform over IPC is available in the Java SDK. See here for details on the API calls.

The following sections give examples of how to call the functions available:

getData

$ KXI_QUERY_USER=query_test
KXI_QUERY_SECRET=$KC_CLIENT_SECRET
KXI_CONFIG_URL=https://$INSIGHTS_HOST_URL/informationservice/details/$KC_CLIENT_URL 
RT_LOG_PATH=/tmp/rt-java2 java -jar ./rtdemo.jar --tableName=tablename --getData

getMeta

$ KXI_QUERY_USER=query_test 
KXI_QUERY_SECRET=$KC_CLIENT_SECRET 
KXI_CONFIG_URL=https://$INSIGHTS_HOST_URL/informationservice/details/$KC_CLIENT_URL
RT_LOG_PATH=/tmp/rt-java2 java -jar ./rtdemo.jar --tableName=tablename --getMeta > meta_result.txt