The Bulk Process

info

This new feature is available to try out, with developer support - on request (via support ticket or your account manager).

Overview

When a bulk of operations are submitted, they become part of a Bulk Process. The Bulk Process is managed through one set of Bulk Process management endpoints regardless of what kind of operations it contains. In summary:

1. Your application will need to group together many requests from the in-session end-customer and submit them as bulk operations. This will initiate the Bulk Process.
2. You will need to execute the Bulk Process to instruct Weavr to start the processing of the operations - the execution can be paused and resumed, and even cancelled; upon instruction by an Authorised User of the end-customer.
3. You can access information about the overall state of the Bulk Process or about individual operations.

caution

The system is configured to accept bulk requests to process up to a maximum of 10,000 bulk operations.

The lifecycle of a Bulk Process is as tracked across the states illustrated below:

• When Weavr receives a valid request for a set of bulk operations, we initiate the Bulk Process, beginning in the start status of 'SUBMITTED'.
• You then need to to execute the Bulk Process, which sets it in ‘RUNNING’ state.
• For a Bulk Process that is in ‘RUNNING’ state, you can instruct for it to be ‘PAUSED’ and also resumed back to ‘RUNNING’ state.
• For a Bulk Process that is in ‘SUBMITTED’, ‘PAUSED’, or ‘RUNNING’ state, you can instruct for it to be 'CANCELLED' (final state).
• When execution finishes, the Bulk Process can be in any one of three final states:
  • COMPLETED: the execution of the Bulk Process is complete and all bulk operations were executed successfully.
  • FAILED: none of the operations of the Bulk Process have executed.
  • PARTIALLY COMPLETED: the execution of the Bulk Process is complete and some of the bulk operations of the Bulk Process failed, details of which can be retrieved by calling the "Get all operations in a bulk" endpoint.

Managing a Bulk Process

A submitted Bulk Process can be managed (executed, accessed, paused, resumed and cancelled) by any Authorised User belonging to the same Corporate Identity subject to the Bulk Process. The steps in managing a Bulk Process are:

1. Submit operations to be performed in a Bulk Process
2. Execute Bulk Process
3. (optionally) Pause and resume Bulk Process
4. Get Bulk Process status and details

1. Submit operations to be included in a Bulk Process

Refer to the Bulk Operations section for the list of supported operation types.

Upon submission of the information required to execute the bulk operations, the Weavr Multi API returns a bulkId which can subsequently be used to manage all aspects of the Bulk Process.

The status of the Bulk Process after execution of this operation is set to ‘SUBMITTED’.

The submitted data in a Bulk Process does not expire but it can be cancelled through "Cancel bulk process".

2. Execute a Bulk Process

POST/bulks/{bulk_id}/executeTry it

Launches the execution of operations in a Bulk Process, identified by the bulk_id parameter.

The status of the Bulk Process has to be in a ‘SUBMITTED’ state, and after execution is initiated, the Bulk Process state is set to ‘RUNNING’.

The final state of execution can be any of:

• COMPLETED: the execution of the Bulk Process is complete and all bulk operations of the Bulk Process were executed successfully.
• FAILED: none of the operations of the bulk process have executed.
• PARTIALLY_COMPLETED: the execution of the Bulk Process is complete and some of the bulk operations failed.

The operation is asynchronous and will not return a response immediately. You can track the status of the execution of the Bulk Process through "Get bulk process". You can also pause execution through "Pause bulk process".

3. Pause and resume a Bulk Process

A Bulk Process that is in state ‘RUNNING’ can be paused - the status of the Bulk Process after pausing is ‘PAUSED’.

POST/bulks/{bulk_id}/pauseTry it

A paused Bulk Process can be resumed through the "Resume bulk" process. The status of the Bulk Process after execution of this operation is set back to ‘RUNNING’.

POST/bulks/{bulk_id}/resumeTry it

4. Get Bulk Process details

You can retrieve information about the status of a Bulk Process as well as about the statuses of the bulk operations within it.

"Get bulk process" returns the status of the Bulk Process and the number of operations in the Bulk Process

GET/bulksTry it

"Get all operations in a bulk" returns information about the individual operations being executed as part of a Bulk Process. You can specify filters to manage the range of operations.

GET/bulks/{bulk_id}Try it

Operations

The Multi Weavr API currently supports these bulk operations.

Endpoint	Description
Authorised Users
POST bulks/users	Bulk create Corporate Authorised Users
POST bulks/user/_user_id_/invite	Bulk invite Corporate Authorised Users
Managed Cards
POST bulks/managed_cards/_id_/spend_rules	Bulk update spend rules for managed cards of an Corporate Identity
Transactions
POST bulks/outgoing_wire_transfers	Create OWTs in bulk. Once the Bulk Process has been executed, the OWTs will require a transaction confirmation challenge to be completed, as described below.
POST bulks/sends	Create Sends in bulk. Once the Bulk Process has been executed, the Sends will require a transaction confirmation challenge to be completed, as described below.

Bulk Processing Operations that require a Transaction Confirmation

There are certain operations, mostly related to fund movements (such as Send and Outgoing Wire Transfer transactions) which require a transaction confirmation (via two factor authentication) before they can be fully processed. When first created, these transactions are set in a PENDING_CHALLENGE state, indicating that a transaction confirmation challenge needs to be completed.

When managing these type of operations through the Bulk Processor:

1. Submit operations to be performed in a Bulk Process (e.g. a bulk of Send transactions)
2. Execute Bulk Process
3. Get Bulk Process status and details. The response of the Get All Operations in a Bulk contains an array of all the transactions that were created, each with an id (resource identifier) and each with the state ‘PENDING_CHALLENGE’. (e.g. an array of Send Transactions, each with a resource identifier)

info

For all of the transactions that are created successfully, you will also receive a webhook with an id and the state of the transaction.

4. Use this list of resource identifiers to complete a transaction confirmation by sending and verifying a challenge. All challenge management operations (endpoints) can handle multiple resource identifiers (as an array) so that multiple transactions can be verified in a single challenge. For example, send a single challenge for multiple Send transactions that were created via a Bulk Process, and then verify this individual challenge.

The handling of the transaction confirmation for operations that were executed as part of a Bulk Process, is the same as if these transactions were created individually, but then grouped together to complete a single challenge.

Bulk Processing of Scheduled Operations

There are certain operations, mostly related to fund movements (such as Transfer, Send and Outgoing Wire Transfer transactions) that can be created and scheduled for a later execution.

When managing these type of operations through the Bulk Processor:

1. Set the ‘scheduledTimestamp’ for each of the individual operations that is to be executed via the Bulk Process

2. Submit operations to be performed in a Bulk Process (e.g. a bulk of Send transactions each with a ‘scheduledTimestamp’)

3. Execute Bulk Process. The Bulk Process will execute the operations; resulting in the creation of each resource (transaction), each with the ‘scheduledTimestamp’ set.

4. Get Bulk Process status and details. The response of the Get All Operations in a Bulk contains an array of all the resources (transactions) that were created, each with an id (resource identifier). The initial state of the resource depends on what it is.

   • If the resource does not require the completion of a transaction confirmation, it will be immediately set to the state SCHEDULED
   • If the resource requires the completion of a transaction confirmation challenge then the resource will be in a state PENDING_CHALLENGE. The transaction confirmation can be completed for multiple transactions in a single challenge. After the completion of the challenge the state of the resources will transition’ to SCHEDULED.

5. In due course, the operation will be executed according to the ‘scheduledTimestamp’

Handling the scheduling of an operation that is part of a Bulk Process is the same as managing the scheduling of an individual operation.

Idempotency in the Bulk Processor

The submission of data for a Bulk Process is an idempotent operation - if the Bulk Process information is submitted and the request times out, you can safely resubmit the information using the same idempotent identifier. The submitted data will be considered as part of the same bulk as the original request that had the same idempotency ref.

The Bulk Process actions (execute bulk, pause and resume bulk, cancel bulk etc.) are not idempotent as the Bulk Process uses the bulk states to ensure the integrity of the bulk during its execution. For instance, a bulk process that is in RUNNING state cannot be executed again.

During the execution of a Bulk Process there might be situations when the Bulk Process attempts an operation more than once (e.g. an individual bulk operation times out internally). In such situations, the Bulk Process uses the underlying idempotency-ref of the operation to ensure consistency.