Configure 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

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

}

]

The following discovery query searches Outstation1 and Outstation2 for any available data items. Since auto-select is set to true, all items is automatically added to the data selection. For additional information, see Data source discovery query parameter.

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

Result:

[

{

"id": "SampleA",

"query": "OutstationIds=Outstation1,Outstation2",

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

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

"progress": 100,

"itemsFound": 700,

"newItems": 200,

"resultUrl": http://127.0.0.1:5590/api/v1/Configuration/DNP3-1/Discoveries/SampleA/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.