Moving Client Sites to a new Region (in bulk using /batch/file)

Identify the source and destination Region IDs

The first step to take is to identify the ID of source and destination Regions. This source Region ID will help you in your next step of generating a list of Client IDs, and the destination Region ID will help you build the inter-region move requests.

It's easy to search for the Region by the name that you're already familiar with. Let's say that the name contains the initials "AB". You can use our :CONTAINS filter mechanism to perform a string search.

[GET] /regions?name:contains=AB

{
        "customId": "19185",
        "name": "AB Demo",
        "company": "",
        "firstName": "",
        "lastName": "",
        "primaryPhone": "",
        "email": "",
        "address": 47175,
        "parentRegion": 548,
  ===>  "id": 19185,
        "logo": "http://presales.qa.staffr.net/rest/v1/media/regions/19185/logo_invoice"
},

Take note of the value of "id" : 19185

Now you can perform this step again while identifying the destination Region and taking note of it's ID. Let's say for this tutorial that it's 42.

Generate a list of Client IDs

The next step is to identify which Client Sites need to be moved from the source Region. This is easily done by requesting a list of sites in the source Region, using its ID:

[GET] /clients?region=19185&fields=id,region

{
           "id": 19187,
           "region": 19185
       },
       {
           "id": 19188,
           "region": 19185
       },
       {
           "id": 19189,
           "region": 19185
       },
       {
           "id": 19190,
           "region": 19185
       },
       {
           "id": 19191,
           "region": 19185
}

Notice all the "id" values, that are the Client ID values for Client Sites in the Region identified by the Region ID 19185.

Two methods of moving multiple Client Sites between Regions

Now you need to decide how you want to iterate through each of those Client IDs to make API calls to move them one by one to the destination Region. Your solution implementation options are either to:

   (1) Iterate through Client IDs, and for each Client ID call the /clients/{id}/actions/move-to-region action.

   (2) Begin a /batch/file request payload targeting the Clients resource with action move-to-region, and iterate through Client IDs for one call to /clients/{id}/actions/move-to-region each

#2 Is the preferred choice

The TrackTik API will execute a series of calls more quickly as a /batch/file request since it will build an internal queue to perform updates without needing the public endpoints, while still executing the same mechanisms that the public endpoints. Anytime you have two or more API requests to make, please take advantage of the /batch/file endpoint.

Using the /batch/file endpoint for a bulk operation (like moving Client Sites to a different Region)

To use the /batch/file endpoint and queue up a series of separate calls, you need to plan to specify four things:

1. How you want the /batch/file steps to run in the event of a failure at any point (abort on any failure, or skip a step that fails and keep going.
2. Which data entity/resource you'll be working with (Clients in our example)
3. What kind of action one of the steps in the batch will be performing ("REPLACE" "CREATE" "UPDATE" "EXECUTE")
4. The data payload of the batch step that you're submitted to the endpoint of the data entity

Using what we've found so far, a destination Region ID, and a list of Client IDs, that means we will plan to:

• ABORT is fine. We'll choose not to continue if we're doing something wrong and our batch steps are failing.
• Clients. We want to work with Clients.
• EXECUTE. We'll be performing an ACTION, the move-to-region action, not a PATCH or PUT.
• The payload will simply be the destination Region ID.

We're ready! Let's build for the /batch/file request with placeholder variables where applicable to show you what you'll need to procedurally generate since you're iterating through a list of Client IDs:

[POST] /batch/file

Header of /batch/file request:

{
"onFailure": "ABORT",
"operations":[

Next, iterate through each Client ID to produce lookup/action/data blocks like these:

{
           "lookup": {
               "id": 19187
           },
           "actionName": "move-to-region",
           "action": "EXECUTE",
           "resource": "clients",
           "data": {
               "id": 19187,
               "region": 42
           }
},
{
           "lookup": {
               "id": 19188
           },
           "actionName": "move-to-region",
           "action": "EXECUTE",
           "resource": "clients",
           "data": {
               "id": 19188,
               "region": 42
           }
},

...

And then end the /batch/file request:

   ],
   "responseData": null
}

Once complete, the /batch/file process will let you know which Clients were moved, and if there were any errors:

{
   "data": {
==>    "hasErrors": false,
       "success": [
           {
               "resource": "clients",
               "resourceId": "19187",
               "data": null
           },
           {
               "resource": "clients",
               "resourceId": "19188",
               "data": null
           }
       ],
==>    "processErrors": [],
==>    "validationErrors": []
   }
}

That's how you move Clients to a new Region using the /batch/file endpoint. If you've given it a go and are still having difficulties, be sure to reach out for help.