Configure data discovery

You can perform a data discovery for existing data items on demand. Data discovery is initiated through REST calls, and it is tied to a specific discovery Id, which you can either specify or let the adapter generate it.

Data discovery includes different routes. For example, you can choose to do the following:

• Retrieve the discovery results

• Query the discovery status

• Cancel or delete discoveries

• Merge discovery results with the data selection configuration

• Retrieve results from a current discovery and compare it with results from a previous discovery

• Retrieve results from a current discovery and compare it with results from a current data selection configuration

Configuration steps

1. Start any of the Configuration tools capable of making HTTP requests.

2. Run a POST command with the Id of the discovery and autoSelect set to either true or false to the following endpoint.

   For this example, 5590 is the default port number. If you selected a different port number, replace it with that value:

   http://localhost:5590/api/v1/configuration/<ComponentId>/Discoveries.

   Note: Including an Id is optional. If you do not include one, the adapter automatically generates one.

   Example using curl:

   curl -d "{ \"Id\":\"TestDiscovery\", \"autoSelect\":true }" -H "Content-Type:application/json" -X POST http://localhost:5590/api/v1/configuration/<ComponentId>/Discoveries"

Discovery parameters

The following table lists all available discovery parameters and describes what inputs are permitted for a discovery query.

Examples

Discoveries status

The following example shows the status of all discoveries. The discovery id in this example was auto-generated. Refer to the table below for a description of each parameter.

[

{

"id": "8ff855f1-a636-490a-bb31-207410a6e607",

"query": null,

"startTime": "2020-09-30T19:34:01.8180401+02:00",

"endTime": "2020-09-30T19:34:01.8368776+02:00",

"progress": 30,

"itemsFound": 4,

"newItems": 0,

"resultUrl": "http://127.0.0.1:5590/api/v1/Configuration/<ComponentId>/Discoveries/8ff855f1-a636-490a-bb31-207410a6e607/result",

"autoSelect": false,

"status": "Complete",

"errors": null

}

]

This following table lists all attributes of a discovery status, as displayed in the previous example. After a discovery has been initiated, you can query the status of the discovery at any time to see discovery attributes, such as progress, data items found, and result URL.

Discovery query syntax

Use the query property to limit discovery to specific BACnet devices. If no query is specified, the adapter discovers all devices that are available through the configured BACnet network. The discovery request supports filtering by device ID, MAC address, or both. The query string consists of semicolon-separated name=value pairs.

Supported query names are:

• DeviceIds - A comma-separated list of BACnet device IDs.

• MacAddresses - A comma-separated list of BACnet MAC addresses.

For example:

DeviceIds=1,2

MacAddresses=00:1D:DC:B7:6A:D4,00:1D:DC:B8:6B:D5

Multiple filters can be combined in a single query:

DeviceIds=1,2;MacAddresses=00:1D:DC:B7:6A:D4

The following example starts a discovery operation for devices with BACnet device IDs 1 and 2 and automatically adds discovered items to the data selection configuration:

curl -d "{ \"Id\":\"SampleA\",\"query\":\"DeviceIds=1,2\", \"autoSelect\":true }" -H "Content-Type:application/json" -X POST http://localhost:5590/api/v1/configuration/<ComponentId>/Discoveries

Discovery

The following discovery query searches the entire data source for data items on every configured outstation. Since auto-select is set to true, all items will automatically be added to the data selection.

curl -d "{ \"Id\":\"TestDiscovery\", \"autoSelect\":true }" -H "Content-Type:application/json" -X POST http://localhost:5590/api/v1/configuration/<ComponentId>/Discoveries

Result:

[

{

"id": "TestDiscovery",

"query": null,

"startTime": "2020-09-30T19:34:01.8180401+02:00",

"endTime": "2020-09-30T19:34:01.8368776+02:00",

"progress": 100,

"itemsFound": 400,

"newItems": 124,

"resultUrl": http://127.0.0.1:5590/api/v1/Configuration/DNP3-1/Discoveries/TestDiscovery/result,

"autoSelect": true,

"status": "Complete",

"errors": null

}

]

REST URLs

Note: Replace <componentId> with the Id of your adapter component and replace <discoveryId> with the Id of the discovery for which you want to perform the action.