Some of the services provided by Basiq are quite resource intensive, and may take a little time to process. To ensure that we provide a pleasant experience to you and your end-users, and that we avoid timeouts of long running connections to our server - we will handle these processes (jobs) asynchronously.

Asynchronous operations are great as they enable us to return an immediate result when an endpoint is queried, and also enable us to scale the requests optimally behind the scenes.

When an asynchronous operation is initiated (e.g. refreshing a connection) the Basiq server will create a job resource and return a status code of 202 - Accepted along with the job details (in the body). You can then query the job url to track its progress.

Tracking the status of a job

Every step of the job has a status property that depicts its current state. The possible status values for each step are as follows:

  • pending - The job has been created and is waiting to be started.
  • in-progress - The job has started and is currently processing.
  • success - The job has successfully completed.
  • failed - The job has failed.

Find out what steps have been completed

Depending on the job being executed, some jobs will have multiple steps which need to be executed, for e.g. refreshing a connection requires the following steps to be completed:

  1. Establish successful authentication with institution
  2. Fetch latest list of accounts
  3. Fetch latest list of transactions

You can keep track of the steps that have been completed by observing the results array property. As each step is successfully completed, its status will be updated and a result object with the link to the affected resource will be present. In the event that a step has failed, the result object will contain an embedded error object.

Attributes

type

Value is "job".

id

A string that uniquely identifies the job.

created

The date time when the job was created.

updated

The date time when the job was last updated.

steps

List of steps that need to be completed. With the following properties:

  • title - Name of the step the job needs to complete.

  • status - Step status: pending, in-progress, success, failed.

  • result - Object containing updated (or created) resources. Otherwise if a step failed contains an error response

links

Links to the following resources:

  • self - URL of job resource

  • source - Resource that initiated creation of this Job. For example, for operations on Connection, this is a Connection URL. This is only returned for Connection jobs and not for Statement jobs.

{
  "type": "job",
  "id": "61723",
  "created": "2016-06-08T09:10:32.000Z",
  "updated": "2016-06-08T09:14:28.000Z",
  "steps": [
    {
      "title": "verify-credentials",
      "status": "success",
      "result": 
        {
          "type": "link",
          "url": "/users/ea3a81/connections/8fce3b"
        }
    },
    {
      "title": "retrieve-accounts",
      "status": "success",
      "result": 
        {
          "type": "link",
          "url": "/users/ea3a81/accounts?filter=institution.id.eq('AU00000')"
        }
    },
    {
      "title": "retrieve-transactions",
      "status": "in-progress",
      "result": null
    }
  ],
  "links": {
    "self": "/jobs/61723",
    "source": "/users/ea3a81/connections/8fce3b"
  }
}