Configure data selection

Save PDF

Last UpdatedSep 04, 2025
5 minute read

In addition to the data source configuration, you need to provide a data selection configuration to specify the data you want the adapter to collect from the data sources.

To configure data selection

Complete the following steps to configure an adapter data selection. Use the PUT method in conjunction with the api/v1/configuration/<ComponentId>/DataSelection REST endpoint to initialize the configuration.

Using a text editor, create an empty text file.
Copy and paste an example configuration for an adapter data selection into the file.

For sample JSON, see the data selection examples.
Update the example JSON parameters for your environment.

For a table of all available parameters, see the data selection parameters below.
Save the file. For example, as ConfigureDataSelection.json.
Open a command line session. Change the directory to the location of ConfigureDataSelection.json.
Enter the following cURL command (which uses the PUT method) to initialize the client settings configuration.

curl -d "@ConfigureDataSelection.json" -H "Content-Type: application/json" -X PUT "http://localhost:5590/api/v1/configuration/AzureEventHubs1/DataSelection"

Note: If you installed the adapter to listen on a non-default port, update 5590 to the port number you used.

If you use a component ID other than adapter1, update the endpoint with your chosen component ID.

For a list of other REST operations you can perform, like updating or deleting a data selection configuration, see the REST URLs below.

Data selection schema

The full schema definition for the adapter data selection configuration is in the EventHubs_DataSelection_schema.json file located in one of the following folders:

Windows: %ProgramFiles%\osisoft\Adapters\EventHubs\Schemas
Linux: /opt/osisoft/Adapters/EventHubs/Schemas

Data selection parameters

Parameter	Required	Type	Description
Selected	Optional	boolean	Selects or clears a measurement. To select an item, set to true. To remove an item, leave the field empty or set to false. Allowed value: true or false Default value: false
Name	Optional	string	The optional friendly name of the data item collected from the data source Allowed value: any string Default value: null
StreamId	Optional	string	The custom identifier used to create the streams. If you do not specify the StreamID or define it as null, the adapter generates a default StreamId based on the measurement configuration. Additionally, within this default StreamId value, the text parser replaces any automatically generated special characters with a replacement character. You can override these replacement characters by manually editing the data selection configuration. For more information on character replacement, see Text parser. A properly configured custom identifier follows the stream ID rules: Is not case-sensitive Can contain spaces Cannot start with two underscores ("__") Can contain a maximum of 100 characters Cannot start or end with a period Cannot contain consecutive periods Cannot consist of only periods. The default ID automatically updates when there are changes to the measurement and follows the format of <Id>.<ValueField>. Note: At time of data egress, the adapter encodes any invalid characters within the StreamId. For more information, see Egress endpoints.
DataFilterId	Optional	string	The ID of the data filter Allowed value: any string Default value: null Note: If the specified DataFilterId does not exist, unfiltered data is sent until that DataFilterId is created.
EventHubName	Required	string	The name of the event hub to collect data from Allowed value: Maximum of 256 characters per Azure limits Default value: {EventHubName}
ValueField	1	string	The JSONPath expression2 to take value from a property
DataFields	1	string	A ComplexTypeMapping that maps JSONPath expressions of fields to property names. Supported complex data types are Coordinates (x, y, and z) or Geolocation (latitude and longitude). For more information, see the Complex data type field mapping examples section below.
IndexField	Optional	string	The JSONPath expression2 to take value to use as a timestamp from a property. Note: The adapter generates a timestamp when null is specified.
DeviceId	Optional	string	The device Id associated with the IoT Hub. If specified, the event is sent only if it originated from the specified device. If omitted, the event is sent to all streams that match the selection.
DataType	Required	string	The expected data type of the values for the specified field. Supported Azure Event Hub data types include: Boolean, Int64, Int32, Int16, UInt64, UInt32, UInt16, Float64, Float32, Float16, Date-Time, String. For more information, see Principles of operation.
IndexFormat	Optional	string	The time format of the timestamp value specified in the IndexField property. Allowed value: Any string that can be used as a DateTime format in the .NET DateTime.TryParseExact() method, for example 01/30/2021. For more information, see Text parser.2 Note: If you specify null, the adapter parses the timestamp identified in IndexField as a DateTime supporting ISO 8601 formats.

1: DataFields and ValueField are mutually exclusive. You must define one or the other, but not both.
2: JSONPath expressions can be expensive to evaluate. For the best performance, avoid complicated expressions in favor of direct references to data.

Data selection examples

The following are examples of valid adapter data selection configurations:

Minimal data selection configuration

[

{

"EventHubName" : "SampleEventHubName",

"ValueField" : "$.TestNode[:1].Value",

"DataType" : "uint64"

}

]

Complete data selection configuration

[

{

"Selected" : true,

"Name" : null,

"StreamId" : "SampleStreamId",

"DataFilterId" : null,

"Topic" : "RandomTopic",

"ValueField": "null",

"IndexField": "$.TimeStamp",

"IndexFormat" : null,

"DeviceId" : "EventHub3",

"DataType" : "Geolocation",

"Datafields" : { "latitude" : "AssetLatitude", "Longitude" : "AssetLongitude" }

{

"Selected" : true,

"Name" : null,

"StreamId" : "SampleStreamId",

"DataFilterId" : null,

"Topic" : "RandomTopic",

"ValueField": "null",

"IndexField": "$.TimeStamp",

"IndexFormat" : null,

"DeviceId" : "EventHub3",

"DataType" : "Coordinates",

"Datafields" : { "x" : "Assetx", "y" : "Assety", "z" : "Assetz" }

}

]

Note: Both ValueField and IndexField require the correct structure of the JSON payload to be specified. The previous examples use the following JSON payload structure:

{

"TimeStamp": "02/17/2021 12:01:36 AM PST",

"Events": [

{

"Value": "4578",

"DataType": "int"

}

]

}

Complex data type field mapping examples

When working with the DataFields or DataTypedata selection parameters, you can provide complex data types field mappings as JSONPath expressions. The adapter supports the following complex data types: Coordinates and Geolocation.

Coordinates example

{"X": "$['xValue']", "Y": "$['yValue']", "Z": "$['zValue']"}

Geolocation example

{"Latitude": "$['latitudeValue']", "Longitude": "$['longitudeValue']"}

REST URLs

Relative URL	HTTP verb	Action
api/v1/configuration/<ComponentId>/DataSelection	GET	Retrieves the data selection configuration, including all data selection items.
api/v1/configuration/<ComponentId>/DataSelection	PUT	Configures or updates the data selection configuration. The adapter starts collecting data for each data selection item when the following conditions are met: The data selection configuration PUT request is received. A data source configuration is active.
api/v1/configuration/<ComponentId>/DataSelection	POST	Allows new items to be appended to the data selection without having to pass the entire data selection.
api/v1/configuration/<ComponentId>/DataSelection	DELETE	Deletes the active data selection configuration. The adapter stops collecting data.
api/v1/configuration/<ComponentId>/DataSelection	PATCH	Allows partial updates of configured data selection items. Note: The request must be an array containing one or more data selection items. Each item in the array must include its StreamId.
api/v1/configuration/<ComponentId>/DataSelection/<StreamId>	PUT	Updates or creates a new data selection item by StreamId. For new items, the adapter starts collecting data after the request is received.
api/v1/configuration/<ComponentId>/DataSelection/<StreamId>	DELETE	Deletes a data selection item from the configuration by StreamId. The adapter stops collecting data for the deleted item.

Note: Replace <ComponentId> with the Id of your adapter component, for example adapter1.

AVEVA™ Adapter for Azure Event Hubs