Asynchronous Operations

A 202 Accepted response from Catalyst Center includes a task ID and URL to track the asynchronous task. For example, you can use this information to determine whether a lengthy task has completed.

Continuing the previous example, if your POST /discovery request did not fail immediately, Catalyst Center returned a response similar to the following:

    "response": {
        "taskId": "85c95140-50fc-4a57-994d-db58d3afe6b3",
        "url": "dna/intent/api/v1/task/85c95140-50fc-4a57-994d-db58d3afe6b3"
    },
    "version": "1.0"
    }

The taskID value identifies this task uniquely system-wide. To retrieve additional information about the operation that the taskId value identifies, GET the url value from Catalyst Center, as the following example shows: https://fqdnOrIPofDnaCenterPlatformdna/intent/api/v1/task/85c95140-50fc-4a57-994d-db58d3afe6b

In the following example response listing, the isError value of false indicates that the operation succeeded. The presence of an endTime value also implies that the operation completed. Sometimes, a human-readable progress value may provide further information:

{
  "response": {
    "startTime": 1524880285900,
    "endTime": 1524880286849,
    "version": 1524880286621,
    "serviceType": "Discovery Service",
    "isError": false,
    "lastUpdate": 1524880286621,
    "progress": "1",
    "rootId": "9dee6883-4028-4879-b4d6-44c86849429b",
    "instanceTenantId": "5ae2347239dfc600df3bb7eb",
    "id": "9dee6883-4028-4879-b4d6-44c86849429b"
  },
  "version": "1.0"
}

Note: Using the url parameter returns the same information that issuing your own GET /task/taskID request does.

The url parameter is a convenience: it simply provides a ready-made URL that you can use to issue the GET /task/taskID request. Some environments, like Postman, present this parameter as a clickable item that issues the request.

If you choose to use this feature, remember to add a valid X-Auth-Token header to the new request. It is important to understand that 202 Accepted does not necessarily imply success of the task that the request created.

For example, if you post a discovery with the same name as an existing discovery, the system accepts your POST /discovery request, but the discovery task fails. To see this for yourself, issue your previous discovery request again, without making any changes. The platform returns a 202 Accepted response, but the GET /task operation shows that the discovery task failed.

{
  "response": {
    "startTime": 1524880671753,
    "endTime": 1524880671799,
    "version": 1524880671790,
    "errorCode": "Discovery name is duplicate",
    "serviceType": "Discovery Service",
    "isError": true,
    "lastUpdate": 1524880671790,
    "progress": "Failed to create discovery",
    "rootId": "a8805e89-b400-40a2-b6a2-49a9d8330629",
    "failureReason": "Discovery name is duplicate",
    "instanceTenantId": "5ae2347239dfc600df3bb7eb",
    "id": "a8805e89-b400-40a2-b6a2-49a9d8330629"
  },
  "version": "1.0"
}

The Intent API allows you to restart or stop existing discoveries. This process differs from creating a new discovery. See the next topic for details on how to manage these tasks.