Batch Invocation

Introduction

It is possible to invoke an endpoint multiple times by using AireGlu's asynchronous batch processing functionality. You submit a list of inputs in a single request, and each one is run against the endpoint independently in the background.

You can optionally be notified:

• per item, through a callback endpoint that is invoked once for every input as it finishes, and/or
• once for the whole batch, through a completion callback endpoint that is invoked after every item has finished, with the outcome of all of them.

Currently only endpoints with a JSON input type are supported.

Access to this feature

Your tenant/username must be added to the ALLOWED_ASYNC_USERS environment variable, you can add multiple users as a semicolon separated list.

How to invoke

Within your endpoint, add a HTTP Request Task. Make a POST request to the AireGlu Async Service - https://glu-async.aireinnovate.com/Api/batch/{username}/{endpointName}/{environmentOrVersion}

The request body is a JSON object:

{
  "request": [
    { "test": "first" },
    { "test": "second" }
  ],
  "callbackEndpoint": "async-callback-test",
  "callbackEnvironmentOrVersion": "1",
  "completionCallbackEndpoint": "batch-complete-test",
  "completionCallbackEnvironmentOrVersion": "1"
}

Field	Required	Description
request	Yes	Array of inputs. Each one is passed as the input to a separate invocation of the endpoint.
callbackEndpoint	No	Endpoint invoked once per item with that item's outcome. See Per-item callback.
callbackEnvironmentOrVersion	No	Environment or version of the callback endpoint. Defaults to the default version.
completionCallbackEndpoint	No	Endpoint invoked once, after every item has finished, with the outcome of all items. See Completion callback.
completionCallbackEnvironmentOrVersion	No	Environment or version of the completion callback endpoint. Defaults to the default version.

Both callbacks are optional and independent - you can use either, both, or neither. With neither, the items are still run but you won't be notified of their outcome.

With a valid payload, the Async API responds with a 202 Accepted, including the id of the batch:

{
  "batchId": "6b0d2f5e-…",
  "total": 2,
  "items": [
    { "index": 0, "status": "Pending", "errors": [] },
    { "index": 1, "status": "Pending", "errors": [] }
  ]
}

An item's index is its position in the request array.

Per-item callback

The callback endpoint is invoked once for every item, whether that item succeeded or failed. Its input mode must be Callback. It receives:

{
  "success": true,
  "errors": [],
  "originalInput": { "test": "first" },
  "endpointOutput": { "test": "first" },
  "transactionId": "…",
  "correlationId": "…"
}

• success and errors describe the outcome of the batched endpoint for this item.
• originalInput is the item's input from the request array, and endpointOutput is the batched endpoint's response. A value that isn't JSON (for example XML) is wrapped as { "value": "<raw string>" }.

Completion callback

The completion callback endpoint is invoked once, after every item in the batch has finished (including its per-item callback, if one is configured). It receives the outcome of every item in a single request.

To create one, set the endpoint's input Format to Batch Complete (under Batch Processing). This configures the expected input schema for you. A completion callback endpoint not configured this way is rejected when the batch is submitted.

It receives:

{
  "batchId": "6b0d2f5e-…",
  "total": 2,
  "transactionId": "…",
  "correlationId": "…",
  "items": [
    { "index": 0, "status": "Succeeded", "errors": [], "originalInput": { "test": "first" }, "endpointOutput": { "test": "first" } },
    { "index": 1, "status": "Failed", "errors": ["…"], "originalInput": { "test": "" }, "endpointOutput": { "value": "" } }
  ]
}

• batchId matches the id returned when the batch was submitted.
• Each item's status is Succeeded or Failed, and originalInput/endpointOutput follow the same rules as the per-item callback. endpointOutput is included for failed items too.
• Every item's full input and output is included, so the payload grows with the size of the batch.

Callback retries

If a callback endpoint fails, AireGlu retries it:

• Per-item callback: retried up to 3 times, with an increasing delay between attempts.
• Completion callback: retried several times over roughly an hour, after which it is not retried again.

Because of these retries, a callback may be invoked more than once for the same item or batch. Callback endpoints should be idempotent - for example, use batchId to detect a completion callback you have already processed.

The batched endpoint itself is not retried. If it fails, the item is recorded as failed and that outcome is passed to the callbacks.

Data retention

AireGlu keeps each item's input and output only for as long as it needs them to deliver the callbacks - 24 hours by default. They are encrypted while stored. If a completion callback is still failing when that period ends, it is not delivered.

How authentication works

The endpoint to be invoked via batch, should be authenticated as you would normally for any other endpoint. The callback and completion callback endpoints will be run by the batch functionality regardless of their authentication status, however, they should have authentication set so that they are protected from someone running them directly.

How will I monitor the requests?

Usage data will be populated but it will be very difficult to follow. We strongly recommend ensuring that debug mode is turned off for the batch invoke and callback endpoints to minimise the amount of usage data (transaction data) stored when an endpoint is batch-invoked. The callbacks can be used to collect information about what the outcome of each invocation was. When calling the Async API you have the option to supply a batch transaction id with the transactionId query parameter (if none is supplied an id is automatically generated). The transaction id is made available in the input of both callbacks.

Example endpoint definitions

Here are example endpoint definitions that you can use to experiment with.

Batch endpoint

Versions:
- Input:
  Method: POST
  InputMode: JSON
  InputSource: Body
  Schema: >-
    {
      "$schema": "http://json-schema.org/draft-04/schema#",
      "description": "",
      "type": "object",
      "properties": {
        "test": {
          "type": "string",
          "minLength": 1
        }
      },
      "required": [
        "test"
      ]
    }
  XmlSchemas:
  ErrorEmail: ''
  StopOnTaskFailure: true
  Tasks:
  - Behaviour: Response
    RequestContext:
    ResponseHandlerContext:
    EmailContext:
    FaxContext:
    MeshContext:
    SmsContext:
    JobContext:
    ResponseContext:
      OutputMode: JSON
      MapType: Path
      XsltParameters: []
      StatusCode: 200
      RetainStatusCode: false
      Template: >-
        {
          "test": "--*test*--"
        }
      Paths:
        test: $.test
      PathOrigins: {}
      Functions: {}
      FunctionLocations:
    RedirectContext:
    MappingContext:
    PdfContext:
    AdapterContext:
    SftpContext:
    JwtContext:
    Tests: []
    Filters: []
    Label: ''
    DataOrigin: -1
    UseCRLFLineEndings: false
  AuthenticationContexts: []
  Version: 1
  Active: true
  PersistTransactionData: false
Name: batch-test
DefaultVersion: 1

Callback endpoint

Versions:
- Input: >-
    {
      "success": true,
      "errors": [],
      "originalInput": {},
      "endpointOutput": {}
    }
  Method: POST
  InputMode: Callback
  InputSource: Body
  Schema: >-
    {
      "$schema": "http://json-schema.org/draft-04/schema#",
      "description": "",
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "errors": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "originalInput": {
          "type": "object",
          "properties": {},
          "required": []
        },
        "endpointOutput": {
          "type": "object",
          "properties": {},
          "required": []
        }
      },
      "required": [
        "success",
        "originalInput"
      ]
    }
  XmlSchemas:
  ErrorEmail: ''
  StopOnTaskFailure: true
  Tasks:
  - Behaviour: Response
    RequestContext:
    ResponseHandlerContext:
    EmailContext:
    FaxContext:
    MeshContext:
    SmsContext:
    JobContext:
    ResponseContext:
      OutputMode: JSON
      MapType: Path
      XsltParameters: []
      StatusCode: 200
      RetainStatusCode: false
      Template: >-
        {
          "success": "--*success*--"
        }
      Paths:
        success: $.success
      PathOrigins: {}
      Functions: {}
      FunctionLocations:
    RedirectContext:
    MappingContext:
    PdfContext:
    AdapterContext:
    SftpContext:
    JwtContext:
    Tests: []
    Filters: []
    Label: ''
    DataOrigin: -1
    UseCRLFLineEndings: false
  AuthenticationContexts: []
  Version: 1
  Active: true
  PersistTransactionData: false
Name: async-callback-test
DefaultVersion: 1

Completion callback endpoint

Create a new endpoint with its input Format set to Batch Complete, and add a Response task. The example request body above expects it to be called batch-complete-test.