Tasks

Process large volumes of registry operations efficiently using the bulk API or ensure atomicity with bundle requests

Tasks are a grouping of operations that can be processed together in the registry. There are three common ways tasks are created:

Bulk tasks: Process large volumes of resource or relationship operations asynchronously.
Bundle tasks: Apply resources and relationships atomically in a single transaction.

Bulk tasks are intended to be used for high-throughput operations where you need to create, update, or delete many resources or relationships efficiently. Bundle tasks are useful when you need to ensure that a set of operations either all succeed or all fail together, maintaining data integrity.

Overview

The task API workflow consists of two main steps:

Submit a task request - Send a batch of operations using the bulk endpoints. This returns a task ID.
Check task status - Monitor the progress and retrieve results using the task ID.

There is no way to retrieve the task ID after submitting a bulk request. Make sure to store it for later use!

At a glance

	Bundle API	Bulk API (Resources, Relationships)
Use Case	Multiple operations on Resources and Relationships	Optimizing operations when dealing with large volumes.
Execution	Synchronous	Asynchronous
Supported Operations	`"CREATE"`,`"UPSERT"`, `"DELETE"`	`"CREATE"`,`"UPSERT"`, `"DELETE"`
Atomic Transaction	Yes	No
Maximum Volume per Request	500 KB	5 GB

Supported bulk operations

The registry supports bulk operations for both resources and relationships:

Resource operations: CREATE, UPSERT, or DELETE multiple resources
Relationship operations: CREATE, UPSERT, or DELETE multiple relationships

Both are very similar in structure, but the endpoints and payloads differ.

Creating a bulk request

Bulk resources

Use the bulk resources endpoint to process multiple resource operations:

curl -X POST "https://$CLINIA_WORKSPACE/sources/my-source/v1/resources/bulk" \
  -H "X-Clinia-API-Key: $CLINIA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "operations": [
    {
      "action": "CREATE",
      "create": {
        "type": "patient",
        "id": "patient-123",
        "data": {
          "name": [
            {
              "given": [
                "John"
              ],
              "family": "Doe"
            }
          ]
        }
      }
    }
  ]
}'

{
  "status": "ACCEPTED",
  "taskId": "bk_30yCPmXLjSOokoLC0B9z5Gs1QCa"
}

Bulk relationships

Use the bulk relationships endpoint to process multiple relationship operations:

curl -X POST "https://$CLINIA_WORKSPACE/sources/my-source/v1/relationships/bulk" \\
-H "X-Clinia-API-Key: $CLINIA_TOKEN" \\
-H "Content-Type: application/json" \\
-d '{
  "operations": [
    {
      "action": "CREATE",
      "create": {
        "type": "treats",
        "from": {
          "type": "practitioner",
          "id": "doctor-123"
        },
        "to": {
          "type": "patient",
          "id": "patient-123"
        },
        "data": {}
      }
    }
  ]
}'

{
  "status": "ACCEPTED",
  "taskId": "bk_30yCPmXLjSOokoLC0B9z5Gs1QCa"
}

Bundle operations

Use the bundle endpoint to process resources and relationships atomically. If any operation in the bundle fails, none of the operations are applied.

curl -X POST "https://$CLINIA_WORKSPACE/sources/my-source/v1/bundle" \
  -H "X-Clinia-API-Key: $CLINIA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "resourceOperations": [
    {
      "action": "CREATE",
      "create": {
        "type": "patient",
        "id": "patient-123",
        "data": {
          "name": [
            {
              "given": [
                "John"
              ],
              "family": "Doe"
            }
          ]
        }
      }
    }
  ],
  "relationshipOperations": []
}'

Response format

A successful bulk or bundle operation returns an ACCEPTED status, meaning the task is processed asynchronously in the background.

{
  "status": "ACCEPTED",
  "taskId": "bd_30sSi7otihHAiRpJ8F1YLpw6kfn"
}

Checking task status

Whether you submitted a bulk request or a bundle operation, you can check the status of the task and eventually retrieve the results using the task endpoint.

curl -X GET "https://$CLINIA_WORKSPACE/sources/my-source/v1/tasks/{taskId}?withReceipts=true" \
  -H "X-Clinia-API-Key: $CLINIA_TOKEN"

{
  "id": "bulk_abc123",
  "status": "SUCCESS",
  "createdAt": "2024-01-15T10:00:00Z",
  "completedAt": "2024-01-15T10:05:30Z",
  "operationReceipts": [
    {
      "status": "SUCCESS",
      "action": "CREATE",
      "target": {
        "targetType": "RESOURCE",
        "type": "patient", 
        "id": "patient-123"
      },
      "receivedAt": "2024-01-15T10:00:01Z",
      "processedAt": "2024-01-15T10:01:15Z"
    }
  ]
}

Task statuses

The overall status of the task represents the completion state of all operations in the bulk request. The possible values are:

SUCCESS - All the operations of the task completed successfully
PENDING - At least one operation in the task is still pending
CANCELLED - All the operations in the task were cancelled
FAILURE - At least one operations failed or was cancelled

The CANCELLED status can only occur if the operation was cancelled by the system. There is currently no way to cancel a task or an operation manually.

For instance, if two tasks are submitted to operate on the same record id, the later task will be kept and the earlier one will be cancelled.

Tasks

On this page