Adding contextual data with the REST API

Contextual data plays a vital role in enhancing the intelligence and functionality of IoT devices. This section explains how to add contextual data to BMC Helix Edge devices. You can access insights in BMC Helix Dashboards and allow the development of rules and Machine Learning models.

You must build an Application Programming Interface (API) by using Swagger to add contextual data. Swagger is an OpenAI suite for API developers.

What is contextual data?

Contextual data refers to additional information that provides a broader understanding of the circumstances or environment in which something exists. In BMC Helix Edge, contextual data enhances the interpretation of metrics, events, or actions by providing relevant details about the surroundings, conditions, or configurations.

With contextual data, you analyze the information devices generate for better decision-making and insights into the overall operational context.

The examples of contextual data in the context of BMC Helix Edge might include:

Location information	Latitude and longitude of the device. Geographical address or region.
Environmental conditions	Temperature and humidity levels. Atmospheric pressure. Presence of specific gases or pollutants.
Device metadata	Serial number or unique identifier. Firmware version. Device type or model
Operational context	Current mode or status of the device. For example, operational, standby, and maintenance. Power source information. For example, battery level, plugged into the mains.
Time-related data	Time stamps indicate when a specific event or metric was recorded. Time zone information.
Usage patterns	Historical data on device usage or patterns. Peak usage times or intervals.
Security and access information	User access logs or details. Security protocols or encryption methods in use.

Exercise caution when creating contextual attributes. After you create contextual attributes, do not alter the attribute name. Changing the contextual attribute name post-metric ingestion with the old name might result in unforeseen behavior and system failures.

Previous metrics were enriched with a distinct name, and when new metrics are introduced, the system applies a new name. Such changes can disrupt integrations in other areas of the system, including Machine Learning algorithms, rules engines, and other functionalities.

Use the following steps to integrate and ingest contextual data for BMC Helix Edge to provide this data for device management, rule creation, and machine learning model development.

Preparing an API request

Before ingesting contextual data, prepare an API request by using the Curl tool or other programming languages capable of making HTTP requests.

Here is an example by using the curl tool:

Prepare an API request

bash
curl --location --request POST 'http:// <<HelixEdgeServerCore>>-vpn3l3:8000/hedge/api/v2/metadata/device/biz/AltaNS12' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic YWRtaW46YWRtaW4=' \
--data '{
    "last_refilled_qty_liters": 92,
    "last_refilled_date": 1691047381,
    "last_refilled_cost_inr": 90000
}'

Replace the URL in the API request with the appropriate BMC Helix Edge installation endpoint.
Make sure that the Authorization header is set based on your system's integration with BMC Helix Single Sign-On (Remote Server Sign-On).
Make sure that the authorization method is configured accordingly.

Include the contextual data specific to your use case in the API request payload (the data part). In the example above, we included data related to a vehicle's fuel refill:

last_refilled_qty_liters represents the quantity of fuel in liters from the last refill.
last_refilled_date indicates the time stamp of the last refill.
last_refilled_cost_inr specifies the cost of the last refill in Indian Rupees (INR).

Sending the API request

Run the curl command or make the corresponding API call by using your chosen programming language. This request sends the contextual data to BMC Helix Edge for ingestion.

The authorization method might vary depending on your system's integration with BMC Helix Single Sign-On. Contact your system administrator or support team for assistance if you require a programmatic way to ingest data or have specific authentication requirements.

GET /contextual data

Retrievie contextual data

Request URL

http
GET {{hedgeURL}}/hedge/api/v2/metadata/device/biz/{{deviceName}}

API request example

Example request URL

bash
curl --location --request GET '{{hedgeURL}}/hedge/api/v2/metadata/device/biz/{{deviceName}}' \
--header 'Authorization: Basic YWRtaW46YWRtaW4='

In this example,

Replace {{hedgeURL}} the placeholder with the appropriate URL or IP address where BMC Helix Edge is hosted.
Replace {{deviceName}} the placeholder with the name or identifier of the specific device instance to retrieve contextual data.
Include the necessary Authorization header. You must configure this header based on your system's authentication mechanism, such as Basic Authentication.

Response

After successful integration, the device sends the contextual data to BMC Helix Edge, which is integrated with the field names in the device profile.