Jobs

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:

Establish successful authentication with institution
Fetch latest list of accounts
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 e.g. "verify-credentials" `status` - Step status: `pending`, `in-progress`, `success`, `failed`. `result` - List of URLs of the updated (or created) resources. - `type` :e.g. "link" - `url`: url to resource 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"
  }
}

📘
Alternate flow with MFA challenge step
Below is detailed the list of resources relating to the mfa-challenge step to engage rendering of challenge and completion of connection.

Result (type = mfa)
`type`	Type of resource e.g. "mfa"

`method`	This will list out the type of mfa challenge presented to the user. The values can include:

	`token` - The user is asked to enter the token associated with the account. This token may be generated by an app like Google Authenticator or delivered to the user via email, SMS or phone. `security-questions` - Security questions are a type of knowledge-based authentication (KBA) where the user is presented with a series of personal questions that they are meant to answer.

`description`	A description to be presented to the user that includes instructions e.g. "An SMS code has been sent to your device, please enter valid number"

`input`	An array of inputs (mfa challenges) that he end-user must complete. e.g. "OTP Password"

`expiryMs`	Maximum time to enter MFA before expiry e.g. 3600

`links`	Array of links to the following resources:

	`response` The URL where the input responses must be submitted.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "type": "job",
  "id": "61723",
  "created": "2021-06-08T09:10:32.000Z",
  "updated": "2021-06-08T09:14:28.000Z",
  "steps": [
    {
      "title": "verify-credentials",
      "status": "success",
      "result": [
        {
          "type": "link",
          "url": "/users/ea3a81/connections/8fce3b"
        }
      ]
    },
    {
      "title": "mfa-challenge",
      "status": "in-progress",
      "result": [
        {
          "type": "mfa",
          "method": "token",
          "description": "A SMS code has been sent to your device, please enter valid number",
          "input": [
            "OTP Password"
          ],
          "expiryMs": 3600,
          "links": {
            "response": "/jobs/61723/mfa"
          }
        }
      ]
    },
    {
      "title": "retrieve-accounts",
      "status": "pending",
      "result": null
    },
    {
      "title": "retrieve-transactions",
      "status": "pending",
      "result": null
    }
  ],
  "links": {
    "self": "/jobs/61723",
    "source": "/users/ea3a81/connections/8fce3b"
  }
}