Bulk Operations

Entities may also support “bulk” operation that allow the same operation to be run on one or more resources within a single request. There are several key differences and additional options that apply to bulk operations.

Parameter Data Filtering

Since bulk operations are capable of acting on one or more objects in a single request, the request body’s “parameter” data is required. This data is a series of one or more filter conditions that will be applied to identify the target list of objects. Each operation may have its own allowed set of filter conditions that can be applied. This may include allowing users to filter on related objects and using complex lookups such as “in” by the same double underscore (“__”) notation as in a GET request’s filters.

Note: all data is still automatically filtered by the user’s eligible facilities and companies and that the user is not permitted to run bulk operations on objects outside their allowed scope.

In general, all bulk operations allow for the filtering of objects by “id”. For example, a JSON request body’s parameters section for filtering on multiple object id’s would be:

{

“paramters”: {

“id__in”: [1, 2, 3]

}

}

Filtering on facility code and company code could be achieved by doing the following (assuming the entity and operation allow it):

{

“parameters”: {

“facility_id__code”: “FAC1”,

“company_id_code”: “COM1”

}

}

The maximum number of objects that may be acted upon in a single request is dictated by the requesting user’s “Rows per Page” attribute. This is configurable per user but also applies in other areas of the application such as how many objects are returned per page in an lgfapi GET request, or in the UI when refreshing a page’s data grid.

Commit Frequency

All bulk operations are provided this additional “options” integer input parameter (default = 0). This parameter allows the requester to dictate at what frequency the changes are applied to each resource or group of resources being processed.

The default value of 0 specifies that no updates are committed unless all resources are processed successfully (all or nothing). All changes are rolled back on the first error, and only the first error is reported back to the user using the stand response.

A value of 1 indicates that the changes should be committed per resource successfully processed. Any error will only cause a failure and roll back of changes for the specific resource that failed. All errors will be accumulated and returned in the standardized bulk response format (see below).

Although a value > 1 is permitted, it is not advised that customers use this unless instructed to do so by support. This is typically only used for more advanced or larger data processing scenarios and for certain performance considerations.

Response Status and Content

When the commit frequency is 0, the bulk operations will give the standard error response format as previously documented, if any error is found. However, a different response status and standardized format is provided on total success or when the commit frequency value is > 0:

A 200 – OK response is returned for bulk operations along with a standardized bulk response having the following attributes:

• record_count – Total number of resources processed in the request.
• success_count – Number of successfully processed resources.
• failure_count – Number of unsuccessfully processed resources.
• details – A nested dictionary (key/value map) that provides additional details for any resources that failed during the processing of the operation.
  • The key to identify each resource and it’s failure is by default the resource’s unique “id” value. However, a different identifying key may be returned per operation, as documented.
  • If no details are provided, the value will be null.

The following is a JSON example where 2 objects were processed, but one (having id=123) failed:

{

“record_count”: 2,

“success_count”: 1,

“failure_count”: 1,

“details”: {

123: “Invalid status.”

}

}