Bulk operations

Creating and polling asynchronous tasks

  1. Bulk update
  2. Polling tasks
  3. Remove done tasks

1. Bulk update

Zefort API can do some larger tasks for you, for example delete, update or tag a great amount of contracts with certain attributes at the same time. There is more information on search parameters on Searching and queries

Let's say we need to set all contracts under the contracts of service tag to end on 15.2.2023 and be reviewed. Here is what we need to do:

import requests

ZEFORT_APIKEY = 'ySLE1mhh6lfRsYa...'
payload = {
    "attributes": {
        "end_date": "2023-02-15"
    },
    "status": "done",
    "search": {
        "q_tags": "contracts of service"
    } 
}

response = requests.post('https://sandbox.zefort.com/api/contracts/bulk_update/', 
                         auth=(ZEFORT_APIKEY, ''),
                         json=payload)
print(response.json())

ZEFORT_APIKEY="ySLE1mhh6lfRsYa..."

curl -X POST https://sandbox.zefort.com/api/contracts/bulk_update/ \
     -u $ZEFORT_APIKEY: \
     -H "Content-Type: application/json" \
     -d '{"attributes": {"end_date": "2023-02-15"}, "status": "done", "search": {"q_tags": "contracts of service"}}'

This time the API will respond with a task: 

{"id": "task_1JgdgKhoZqSWVUIzgL",
 "details": {"query_params": {},
             "data": {"attributes": {"end_date": "2023-02-15"},
                      "status": "done",
                      "search": {"q_tags": "contracts of service"}}},
 "backend_status": "pending",
 "backend_status_info": "",
 "frontend_status": "pending",
 "description": "Contract Bulk operation"}

2. Polling tasks

While this kind of large bulk operations might take a while, your program should be kept on track which tasks have been finished and which are still running. Task polling is an operation that lets your program know what's happening right now in the backend side.

For polling a task, you'll need a task id, which is to be placed in the end of the url endpoint.

import requests

ZEFORT_APIKEY = 'ySLE1mhh6lfRsYa...'
TASK_ID = 'task_1K8WmjFq1eqaeawrUi'

request = requests.get(f"https://sandbox.zefort.com/api/tasks/{TASK_ID}/",
                       auth=(ZEFORT_APIKEY, ''))
print(request.json())

ZEFORT_APIKEY="ySLE1mhh6lfRsYa..."
TASK_ID="task_1K8WmjFq1eqaeawrUi"

curl -X GET https://sandbox.zefort.com/api/tasks/$TASK_ID/ \
     -u $ZEFORT_APIKEY:

Response: 

{
    "id": "task_1K8WmjFq1eqaeawrUi",
    "details": {"data": {"contracts": ["ct_1KmjVahd4Hg6W7l18c",  
                                       "ct_1JXncwxR5skmpC4dDB"]},
                "query_params": {}},
    "backend_status": "done",
    "backend_status_info": "",
    "frontend_status": "pending",
    "description": "Contract Bulk operation"
}

In the response, you are mostly interested in backend_status attribute. When it changes from pending to done, it means the operation is completed.

3. Remove done tasks

Now to remove the task from the pending tasks list, you need to patch the frontend_status to done.

Here is how to do it:

import requests

ZEFORT_APIKEY = 'ySLE1mhh6lfRsYa...'
TASK_ID = 'task_1K8WmjFq1eqaeawrUi'

request = requests.patch(f"https://sandbox.zefort.com/api/tasks/{TASK_ID}/",
                         auth=(ZEFORT_APIKEY, ''),
                         json={'frontend_status': 'done'})
print(request.json())

ZEFORT_APIKEY="ySLE1mhh6lfRsYa..."
TASK_ID="task_1K8WmjFq1eqaeawrUi"

curl -X PATCH "https://sandbox.zefort.com/api/tasks/$TASK_ID/" \
     -u $ZEFORT_APIKEY: \
     -H "Content-Type: application/json" \
     -d '{"frontend_status": "done"}'

Response: 

{
    "id": "task_1K8WmjFq1eqaeawrUi",
    "details": {"data": {"contracts": ["ct_1KmjVahd4Hg6W7l18c",  
                                       "ct_1JXncwxR5skmpC4dDB"]},
                "query_params": {}},
    "backend_status": "done",
    "backend_status_info": "",
    "frontend_status": "done",
    "description": "Contract Bulk operation"
}
After this final response, the task can no longer be found when reading /tasks/.