Skip to content
Last updated

Operation Result Tokens

Updatable entity APIs in the integration platform are executed asynchronously due to Vista Cloud's distributed architecture and performance considerations.

As a result, these APIs do not return immediate outcomes. Instead, they provide a placeholder operation result token, which can be used to retrieve the operation result later.

operation
result token(s)

no

yes

try again

Call Update Entity API

Call Resolve Token API

Result(s)
available?

Wait few seconds

Done

Example

Using the Stock Vendor Receipts API as an example, a request is sent as follows:

curl -X 'POST' \
  'https://integration.app.vista.co/api/v1/stock-management/vendor-receipts' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <JWT>' \
  -d '{ "siteId": "1", "requests": [ ... ]}'

Since the integration platform processes requests asynchronously, it will generate a response as soon as the request is accepted by the down stream business domain services:

{
  "responses": [
    {
      "operationResultToken": "Vm91Y2hlck9yZGVyRGlzdHJpYnV0aW9uOjpEaXNjb3ZlcldhcmVob3VzZTo6OWM1NjQ0MWYtMWYxOS00OTBmLThlNTMtMTJlNTM5OTk3Mzc4Ojo2Nw==.CNuRQf0XSKqfpcGkpTSnkRyHx1t3Pqq1s7obqVfSSZM="
      ...
    },
    ...
  ]
}

The response always consists of an array of response objects, each corresponding to a request. While different APIs may include additional properties, every response object contains an operationResultToken property.

Resolving the Operation Result Token

To retrieve the status and result values of an operation, send the operationResultToken to the /identity-resolution/from-operation-result-tokens API endpoint.

curl -X 'POST' \
  'https://integration.app.vista.co/api/v1/identity-resolution/from-operation-result-tokens' \
  -H 'accept: */*' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <JWT>' \
  -d '[ "<RESULT TOKEN 1>", "<RESULT TOKEN 2>" ]'

For example, a typical entity creation operation result token can resolve to following four pieces of information:

  • operationResultToken - The original token.
  • status - The processing status of the original request, will be null if the entity is not found.
  • entityId - The ID the created entity, will be null if the entity is not found.
  • entityType - The type of entity created.

Example JSON response:

[
  {
    "operationResultToken": "<RESULT TOKEN 1>",
    "status": "Queued",
    "entityId": "1633",
    "entityType": "StockReceipt"
  },
  {
    "operationResultToken": "<RESULT TOKEN 2>",
    "status": "Success",
    "entityId": "1634",
    "entityType": "StockReceipt"
  }
]

Resolution responses for operation result tokens from different endpoints may include additional details beyond these four basic fields.