Use Case 1: Trigger ADT Intent and Get Results
Users can call APIs from the 3rd-party system to trigger a network intent, and get the task status; When the task is completed, send an API call to obtain the execution result.
3rd-Party API Call Trigger Intent Execution
An API call sent from the external system calls NetBrain TAF Lite to trigger the network intent(s) located in a specific ADT view and retrieve the execution result.
- API URL: API/V3/TAF/Lite/run
- Description: The API is for triggering intent execution.
- Method: Post
-
Input Parameters
ParameterTypeRequiredDescriptionendpoint string Yes The endpoint generated by the system when users add an ADT view to TAF Lite. passKey string Yes To authenticate access to the ADT view. filterDevices array No A list of device names to filter out rows in the ADT view.
Define a list of device names. A row matches if the device name in the device column is in the list.
intentColumns array To execute a certain NI column, users need to input the display name list for ADT’s NI column.
When the value is empty, all NI columns will be executed.
-
Optional Parameters for Advanced Settings
Parameter Type Required Value/Description option.rawData bool No Whether to save raw data.
- False (default): Do not save raw data.
- True: Save raw data.
option.dataSource int No To use which data source to execute the network intent.
- 0 (default): Execute the network intent with live data.
- 1: Execute the network intent with baseline data.
option.rowFilter object No columnName: value
Multiple values are combined using AND logic.
option.maxExecuteNIColumn int No The maximum NI columns allowed in this execution.
The default value is 1.
- Output. taskId. The Id for this execution task.
Sample Input and Output:
Input
Output
Call API to Obtain Task Results
Intent execution takes time to complete; therefore, the execution result might not be available immediately. When an intent is triggered, the API will return a task id and use it to query if the execution has been completed.
When the execution is ongoing, the API will obtain the task status periodically until the execution is finished. If the execution is completed, the API will return the ‘Finished’ status, along with the ResultID for the execution.
- API URL: API/V3/TAF/Lite/result
- Description: The API is for retrieving Trigger Intent List and Intent Execution Result Id.
- Method: Post
-
Input Parameters:
Parameter Type Required Description endpoint string Yes The endpoint generated by the system when users add an ADT view to TAF Lite. taskId string Yes This value is mandatory and can be found in the response from the API used to trigger intent.
-
Output:
Field Value/Description taskId The task Id for the intent execution status The task status:
- 0: Pending
- 1: Running
- 2: Finished
intents (Filled when the status is ‘Finished’)
The list of triggered network intents.
intents[].id (Filled when the status is ‘Finished’)
The intent Ids.
intents[].name (Filled when the status is ‘Finished’)
The intent names
intents[].resultId (Filled when the status is ‘Finished’)
The intent result Id
intents[].hasAlert If there’s any alert status code in the NI execution result.
- false: No alert.
- true: There is at least one alert.
Sample Input and Output:
Input
Output
Call API to Obtain Intent Execution Results
When the intent execution is finished, users can send an API call to obtain intent execution result data.
- API URL: API/V3/TAF/Lite/result/datas
- Description: This API is for obtaining the list of triggered intents and the execution results.
- Method: Post
-
Input Parameter:
Parameter Type Required Description endpoint string Yes The endpoint generated by the system when users add an ADT view to TAF Lite. niResultId string Yes The intent result Id output array Yes The result type returned to the 3rd-party system.
- 0: return all types of data
- 1: return status code and messages.
- 2: return raw data
- 3: return a CSV file type
- 4: return map id, map name, and map link.
-
Output:
Field Value/Description [].niId Intent Id [].niName Intent name [].timePoint The time when the NI was executed. [].statusCodes NI status codes [].csvs NI results displayed in CSV format [].rawDatas Results obtained from executing commands on each device [].rawDatas[].deviceName device name [].rawDatas[].command The command executed on the device [].rawDatas[].rawData Raw text data [].maps Map results
Sample Input and Output:
Input:
Output:
Call API to Download Results
When the intent result data is too large to return, a downloadTicketId will be returned instead, which can be used to download the result zip file.
- API URL: API/V3/download?dl_ticket={downloadTicketId}
- Description: This API is for downloading the result data.
- Method: Get
-
Input Parameter:
Parameter Type Required Description downloadTicketId string Yes The ID returned by the system when the result data is too large.
Call API to Obtain the Latest NI Execution Results
Users can call an API to obtain the latest execution result data.
- API URL: API/V3/CMDB/NI/result
- Description: This API is for obtaining the latest execution information.
- Method: Post
-
Input Parameter:
Parameter Type Required Description niIdOrPath String Yes The Id or path of the intent. startTime dateTime No The time when the intent execution started endTime dateTime No The time when the intent execution ended output Array Yes The result type returned to the 3rd-party system.
- 0: return all types of data
- 1: return raw data
- 2: return status code and messages
- 3: return a CSV file type
- 4: return intent maps and external maps
-
Output:
Field Value/Description [].niId Intent Id [].niName Intent name [].timePoint The time when the NI was executed. [].statusCodes NI status codes [].csvs NI results displayed in CSV format [].rawDatas Results obtained from executing commands on each device [].rawDatas[].deviceName device name [].rawDatas[].command The command executed on the device [].rawDatas[].rawData Raw text data [].maps Map results
Sample Input and Output:
Input:
Output:
