Data Access Publisher Endpoint .NET Example

.NET Core project to demonstrate how to interact with the Data Access Publisher endpoint for data reingestion

Brief Synopsis

The ABB Ability™ Platform provides a way to publish alarms, events, and telemetry/variable data to the Platform using the Data Access API Publishers endpoint. This provides a way to reingest data using web APIs from the cloud side of the platform instance. This can be accomplished via a client or server side application leveraging this endpoint.

This application uses the Publishers endpoint in the Data Access API to send telemetry data into the Platform. A publisher token can be created, and its corresponding connection URL can be retrieved via this endpoint based on token ID. For the scope of this tutorial, a publisher is created and run for the life of a SAS token used to authorize access to the publishing endpoint.

In this tutorial, the application functions as follows:

1. The application reads a configuration file containing the data access endpoint url, the publisher endpoint, the identifying name of the publisher token that will be created, the lifetime of the publisher SAS token, the objectId of the information model object to push variable data against, the name of the specific variable, the lifetime of the application, and the frequency that data will be pushed in over this lifetime.

2. The application requests a publisher token via POST request.

3. The application uses information from the json response to the publisher token POST request to reingest data via a connection url and echos this to the console output.

4. The application runs for a specified duration. When it completes, the application stop sending data and waits for user input before closing.

Prerequisites

The tutorial is written in C# using the .NET Core framework. A basic console application will be created. Familiarity with the basics of .NET application development is recommended. A basic knowledge of the the Ability Platform, and the Data Access API is assumed.

The corresponding code for this tutorial can be found at this ABB Codebits repository.

The application can be run and compiled using Visual Studio or Visual Studio code with the .NET Core SDK, or run from the command line.

Run Data Publisher Application

Example Configuration File

{
  "managementApiUrl": "https://ADDRESS.abilityplatform.app/v1/", // Fill in your Management gateway url",
  "managementApiKey": "5ece30eda47F45G99017fbf91099b279", //Azure API Management Service Key (if needed)
  "tokenId": "myToken8456734", //Unique ID for your Publisher SAS token. This GUID must match the client ID of your background application
  "sasTokenTtl": "60", // Duration of the life of your SAS token in minutes (Min: 5)
  "objectId": "019939e7-e853-459c-aeac-abd53b04e19d", // ObjectID of Information Model Object instance to push data into
  "variableName": "randomVariable", // Name of variable in Information Model object to push telemetry in against
  "duration": "60", // Lifetime of the application to publish data in minutes
  "publishInterval": "5000", // Frequency of publishing data, in milliseconds. 
  "accessToken": "" //User generated token from background application
}

WARNING

Note that publisher endpoint can be used ONLY in the context of a background application. User delegation token will not be accepted. Additionally, tokenId has to be exactly the same as clientId of your application registration in the Ability Management Portal

Request Publisher Endpoint Token

Publishers Endpoint Token Response

After performing a POST to the publishers/{id}/token endpoint, the application will parse the json response for data needed to publish data into the Platform.

Response Body

{
"SasToken": "<Example SAS Token>", // Used to authorize data reingestiation with ConnectionUrl
"ConnectionUrl": "<URL>" // Endpoint to POST data to.
}

Publish Data

The application will send data into the platform until the CancellationToken object signals the end of the application run, when the duration specified in the configuration file has elapsed. Each message pushed into the platform is represented by a TelemetryMessage object.

private static async Task StartPublishingVariableTelemetry(PublisherResponse publisherResponse, CancellationToken ct)
{
    try
    {
        var random = new Random();
        var objectId = Guid.Parse(_config.ObjectId);

        while (!ct.IsCancellationRequested)
        {
            //Create a new telemetry message and generate a double in a range of 0-99 for its variable value. 
            var msg = JsonSerializer.Serialize(
                new TelemetryMessage<double>(
                    objectId,
                    _config.VariableName,
                    Math.Round(random.NextDouble() * 100, 2)));

            var request = GenerateTelemetryHttpRequest(publisherResponse, msg);
            var response = await _httpClient.SendAsync(request, ct);
            response.EnsureSuccessStatusCode();

            //Display published message
            Console.WriteLine(msg);
            await Task.Delay(_config.PublishInterval);
        }
    }
    catch (Exception ex)
    {
        Console.WriteLine(ex.Message + " " + ex.InnerException);
    }
}

Note that the application is designed to publish 'timeSeries' data.. Publishing alarm and event data is also supported by the platform.

SAS Token Lifetime

When the Publisher SAS token expires, the application will no longer be able to publish data.

If the specified duration of the application exceeds the lifetime of

the SAS Token, the application will no longer be able to reingest data once the SAS token has expired.

Running the Application

The application can be run from Visual Studio, or from the command line from the root directory of the application using the commands below

dotnet build
dotnet run

Validate the Application is Publishing Data

• An application using the Hot Path Subscription Example project to verify that data is being published into the platform.
• A curl command using the "warm" data path endpoint for variable data:

curl -X POST \
  https://api-xxxxx.abilityplatform.abb/v1/Data/<DataType, usually 'variables'> \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache' \
  -d '{
  "date": {
    "from": "<Timestamp using ISO 8601 Round-trip Format Specifier>",
    "to": "<Timestamp using ISO 8601 Round-trip Format Specifier>"
  },
  "filter": "objectId='\''<ObjectId>'\''",
  "select": {
    "properties": "variable, timestamp, value"
  },
  "orderBy": {
    "property": "timestamp",
    "order": "desc"
  },
  "limit": 10
}'

Next Steps

• Validate with a Postman request (Instructions pending)
• Publish alarm and event data (Instructions pending)