Asynchronous Operations

When the Catalyst Center platform returns a 202 (Accepted) HTTP status code, the result body includes a task ID and a URL that you can use to query for more information about the asynchronous task that your original request spawned. 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. In some cases, 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. As before, you get a 202 Accepted response from the Catalyst Center platform, but when you use the GET /task API to investigate the status of the discovery task, you find that it has 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"
}

However, you can use the Intent API to restart or stop an existing discovery; it just requires a different approach than creating a new discovery. The next topic in this guide describes how to start and stop existing discoveries.