In situations where you need to run many successive API operations to create or update records, the /batch/file endpoint exists for doing batches of 20-60 operations each (depending on the failure handling specified). 

The payload to send to the /batch/file endpoint is a JSON that is is comprised of the following parts:

1. An onFailure definition of either ABORT, CONTINUE or ROLLBACK.
2. Array of Operations. Operations are separate API calls, and their comprised of:
   a) An Entity (employees, shifts, etc.)
   b) An Action CREATE|UPDATE|EXECUTE (for API actions)
   c) OPTIONAL (EXECUTE action only) : An Action Name
   c) OPTIONAL (updates only): a LOOKUP of one or many uniqueness forming values to locate a record to update
   d) data JSON object (payload)

Operations and Operations Counts Limits

ABORT: the /batch/files operations will not continue if there is an error in the previous operation

CONTINUE: the full list of operations will be attempted regardless of errors in previous operations

ROLLBACK: as soon as a failure occurs, no further operations will be processed and previous work performed by previous operations will be reverted. This is a database heavy activity, and therefore the Operations Limit is lower. 

WARNING

We don't currently count nor enforce the operations limit and will accept however many you send. But you put yourself at risk of timeouts and uncertainty in the states of data from which you'll need to recover unaided because with timeouts there won't be a Response payload to guide you. 

Example

Imagine you need to move many Employees to a different region. When doing this individually as separate direct calls, you would:

[POST] /employees/{id}/actions/move-to-region

{
  "region" : 123
}

In the above the {id} is the unique identifier for the employee, its employee.id value. 

The "move-to-region" is the name of the action to execute. 

The payload is a JSON object that contains the ID of the Region that employee {id} should be moved to.

In this example, you can see that for each of these calls that can be made individually, there will be different {id} values for each call, and the Region value may differ as well. 

To perform many of these operations as a list of operations in a single POST to /batch/file, you would need to produce the following JSON payload:

{
    "onFailure": "CONTINUE",
    "operations": 
[
{
   "action": "EXECUTE",
   "resource": "employees",
   "actionName": "move-to-region",
   "lookup": {
      "id": 100
   },
   "data": {
      "region": 12
   }
},
{
   "action": "EXECUTE",
   "resource": "employees",
   "actionName": "move-to-region",
   "lookup": {
      "id": 101
   },
   "data": {
      "region": 12
   }
},
{
   "action": "EXECUTE",
   "resource": "employees",
   "actionName": "move-to-region",
   "lookup": {
      "id": 102
   },
   "data": {
      "region": 12
   }
},
etc.

 Anatomy of this call:

1. onFailure definition of CONTINUE
2. Array of operations [ ]
3. Three operations objects of:
   a) action EXECUTE
   b) the action's name of move-to-region
   b) resource employees
   c) a lookup on the employee.id value
   d) a data object which is the same payload as if you had made a direct single API call yourself (region who's id is 12)

How to build operations the easy way

You might be asking how you're supposed to compose such a large JSON payload which could have 50 operations in it. One of the easiest ways that we use internally at TrackTik which doesn't require much tooling, is to use a spreadsheet tool to produce a CSV, where each column of the spreadsheet is one of the keys used in operations. Then we convert it to JSON. 

First, create a CSV like this:

Each of these columns will create a "key" : "value" pair when the CSV saved from this is converted to JSON. You'll quickly notice which cells are repeatable data and which are dynamic.

For sub-objects that need to be nested, you simply add a / character between them, like in column D where you see "lookup/id". That will produce a "lookup": {"id": 100} at time of conversion.

When you save the above as CSV, you get the following:

action,resource,actionName,lookup/id,data/region

EXECUTE,employees,move-to-region,100,12

EXECUTE,employees,move-to-region,101,12

EXECUTE,employees,move-to-region,102,12

EXECUTE,employees,move-to-region,103,12

EXECUTE,employees,move-to-region,104,12

And you can convert this into a JSON array with any tool from a software framework, or third party tool like https://www.convertcsv.com/csv-to-json.htm

The end result will be an array of operations, which you will paste right after the "operations" : key declaration of the /batch/file payload.

Responses

A happy path response for a POST to /batch/file will look like the following:

{
    "data": {
        "hasErrors": false,
        "success": [
            {
                "resource": "employees",
                "resourceId": "100",
                "data": null
            },
            {
                "resource": "employees",
                "resourceId": "101",
                "data": null
            },
Etc.
        ],
        "processErrors": [],
        "validationErrors": []
    }
}

Troubleshooting

If you keep having errors and you're not sure why, a great way to investigate is to take one of the operations, and try it manually as a direct API call. The errors of individual API calls are typically more informative. 

Main problems to look for:

• You're attempting to CREATE new data and are re-using typically uniqueness enforced values like customId.  
• You're attempting to UPDATE data where the PATCH method is not implemented for that API entity. Be sure to refer to the https://portal/rest/v1 API documentation for reminders. 
• The LOOKUP section that tries to locate a record to UPDATE is failing and not finding what needs updating.
• You have two conflicting operations, or they are out of order, like if you're trying to update a record before it gets created as a later operation. 
• The action definition is missing from an EXECUTE operation.