# transaction-bundles

Canonical page: https://docs.ovok.com/settings-and-features/features/transaction-bundles

Makes a `Bundle` of type `transaction` atomic: every entry is applied, or none is. Without the feature, the same request is accepted but runs as a batch.

| | |
| --- | --- |
| Type | Project feature |
| Value in `features` | `transaction-bundles` |
| Change with | `PATCH /v1/projects/me/features` (replaces the whole list) |
| Who can change it | Project admin. Any practitioner can read the list. |
| On for new projects | Yes |
| When off | A transaction Bundle runs as a batch: entries succeed or fail independently |

## What it does [#what-it-does]

Send a [Bundle](/api/fhir/r4/bundle) whose `type` is `transaction` to the FHIR base:

```bash
curl --request POST \
  --url 'https://api.sandbox.ovok.com/fhir/R4' \
  --header "Authorization: Bearer ${OVOK_TOKEN}" \
  --header 'Content-Type: application/fhir+json' \
  --data @transaction-bundle.json
```

Example `transaction-bundle.json`. The Observation refers to the new Patient through a temporary `urn:uuid` id:

```json
{
  "resourceType": "Bundle",
  "type": "transaction",
  "entry": [
    {
      "fullUrl": "urn:uuid:5b1f0c0e-6f43-4c55-9d1a-0a6c2f6d1a11",
      "resource": { "resourceType": "Patient", "name": [{ "family": "Example" }] },
      "request": { "method": "POST", "url": "Patient" }
    },
    {
      "resource": {
        "resourceType": "Observation",
        "status": "final",
        "code": { "coding": [{ "system": "http://loinc.org", "code": "8867-4" }] },
        "subject": { "reference": "urn:uuid:5b1f0c0e-6f43-4c55-9d1a-0a6c2f6d1a11" },
        "valueQuantity": { "value": 72, "unit": "beats/minute" }
      },
      "request": { "method": "POST", "url": "Observation" }
    }
  ]
}
```

## What you get back [#what-you-get-back]

| Feature | Outcome |
| --- | --- |
| On, all entries succeed | `200` with a `transaction-response` Bundle. |
| On, one entry fails | The whole request is rejected with an `OperationOutcome` and **nothing is written**. The HTTP status is the failing entry's own (for example `404` when an entry reads a resource that does not exist). |
| Off, all entries succeed | `200` with a `transaction-response` Bundle. |
| Off, one entry fails | `200` with a `transaction-response` Bundle. **The other entries are still written**; read each entry's `response.status`. |

When the feature is on, expect these statuses for a rolled-back transaction: `412` when an entry's `If-Match` is stale, `409` when the database could not serialise concurrent writes, and `400` with a deadlock message when it detected a deadlock. Retry `409` and a deadlock `400`; re-read before retrying `412`.

## Limits when it is on [#limits-when-it-is-on]

| Limit | Result |
| --- | --- |
| More than 50 update (`PUT`) entries | `400` `Transaction contains more update operations than allowed` |
| A conditional create (`ifNoneExist`), conditional update or conditional delete with more than 8 entries in the Bundle | `400` `Transaction requires strict isolation but has too many entries` |
| `Prefer: respond-async` on a transaction | `400` `Transaction batches cannot be executed asynchronously` |

Split work that exceeds the limits into several transactions, and keep each one a single logical change.

## Turn it on [#turn-it-on]

```bash
curl --request PATCH \
  --url 'https://api.sandbox.ovok.com/v1/projects/me/features' \
  --header "Authorization: Bearer ${OVOK_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '{"features":["bots","cron","email","transaction-bundles","websocket-subscriptions"]}'
```

## Gotchas [#gotchas]

- **Off is silent.** With the feature off, a transaction Bundle still returns `200`, and the response `type` is still `transaction-response`, so nothing in the response tells you it ran as a batch. A client that treats `200` as "everything was saved" can lose writes. Check `transaction-bundles` in the features list, and check each entry's `response.status` when you are not sure.
- **The flag is read from the project of the token that sends the Bundle**, not from the project that owns the data.
- **Projects created before this was a default can lack it.** Call `GET /v1/projects/me/features` and check.

## Related [#related]

- [Bundle](/api/fhir/r4/bundle)
- [Extract Observations from a QuestionnaireResponse](/primitives/extract-observations), which returns a transaction Bundle you can post
- [Check an async job's status](/primitives/check-async-job-status)
