Skip to content
This repository was archived by the owner on Mar 17, 2026. It is now read-only.

Commit fe12290

Browse files
AitemAitem
committed
[#6973] Big bunch of documentation fixes
1 parent ef36918 commit fe12290

File tree

5 files changed

+240
-6
lines changed

5 files changed

+240
-6
lines changed

‎docs/SUMMARY.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -156,6 +156,7 @@
156156
* [Configure Aidbox and Multibox](configuration/configure-aidbox-and-multibox.md)
157157
* [External Secrets](configuration/secret-files.md)
158158
* [Init Bundle](configuration/init-bundle.md)
159+
* [Migrations](configuration/migrations.md)
159160

160161
## API
161162

‎docs/access-control/audit-and-logging.md‎

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -70,7 +70,7 @@ When you update a Patient resource, the generated AuditEvent uses the `IHE.Basic
7070
"type": {
7171
"system": "http://terminology.hl7.org/CodeSystem/audit-event-type",
7272
"code": "rest",
73-
"display": "RESTful Operation"
73+
"display": "Restful Operation"
7474
},
7575
"subtype": [
7676
{
@@ -102,8 +102,13 @@ When you update a Patient resource, the generated AuditEvent uses the `IHE.Basic
102102
},
103103
"role": {
104104
"system": "http://terminology.hl7.org/CodeSystem/object-role",
105-
"code": "1",
106-
"display": "Patient"
105+
"code": "4",
106+
"display": "Domain Resource"
107+
},
108+
"type": {
109+
"system": "http://terminology.hl7.org/CodeSystem/audit-entity-type",
110+
"code": "2",
111+
"display": "System Object"
107112
}
108113
}
109114
]

‎docs/access-control/authorization/access-policies.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -108,7 +108,7 @@ See tutorials:
108108
109109
Aidbox provides several ways to specify rules for AccessPolicy resources — so-called evaluation engines. They come with their syntax and offer varying degrees of flexibility and convenience for writing those rules.
110110
111-
There are five evaluation engines:
111+
There are seven evaluation engines:
112112
113113
| Engine | Description | Use Cases |
114114
| ----------- | ----------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
@@ -117,6 +117,8 @@ There are five evaluation engines:
117117
| JSON Schema | Uses JSON Schema validation for request objects | - For those familiar with JSON Schema |
118118
| SQL | Uses SQL queries for access control logic | <p>- Complex data-dependent rules<br>- When you need to join multiple tables<br>- Performance-critical scenarios</p> |
119119
| Complex | Combines multiple engines and conditions | <p>- Multi-step validation workflows<br>- When you need to combine different types of checks<br>- Advanced access control scenarios</p> |
120+
| Allow-RPC | Like Allow, but only for RPC endpoints | - Granting unrestricted access to specific RPC operations |
121+
| Matcho-RPC | Like Matcho, but only for RPC endpoints | - Pattern-based access control for RPC operations |
120122

121123
It is recommended to pick the Matcho engine. In 90% of cases, it is enough. Sometimes, the complex access policy can only be written by SQL or Complex engines.
122124

‎docs/configuration/migrations.md‎

Lines changed: 226 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,226 @@
1+
---
2+
description: Run one-time migrations at startup — install FHIR packages or execute SQL using AidboxMigration and Init Bundle.
3+
---
4+
5+
# Migrations
6+
7+
Aidbox supports one-time migrations that run exactly once during startup. Migrations are useful for:
8+
9+
* Installing FHIR Implementation Guide packages
10+
* Running SQL statements (creating indexes, tables, seed data)
11+
12+
Migrations use the `AidboxMigration` resource combined with [Init Bundle](init-bundle.md) for declarative, idempotent execution.
13+
14+
## How it works
15+
16+
1. You define an `AidboxMigration` resource with an action and parameters
17+
2. You wrap it in an Init Bundle with `ifNoneExist` to ensure it runs only once
18+
3. On startup, Aidbox executes the bundle — if the migration already exists, it is skipped
19+
20+
## Install a FHIR package
21+
22+
Use the `far-migration-fhir-package-install` action to install a FHIR IG package from the registry.
23+
24+
```json
25+
{
26+
"type": "transaction",
27+
"resourceType": "Bundle",
28+
"entry": [
29+
{
30+
"request": {
31+
"method": "POST",
32+
"url": "AidboxMigration",
33+
"ifNoneExist": "id=us-core-install"
34+
},
35+
"resource": {
36+
"resourceType": "AidboxMigration",
37+
"id": "us-core-install",
38+
"action": "far-migration-fhir-package-install",
39+
"status": "to-run",
40+
"params": {
41+
"resourceType": "Parameters",
42+
"parameter": [
43+
{
44+
"name": "package",
45+
"valueString": "hl7.fhir.us.core@3.1.1"
46+
}
47+
]
48+
}
49+
}
50+
}
51+
]
52+
}
53+
```
54+
55+
The `package` parameter value follows the format `<package-name>@<version>`.
56+
57+
After execution, the migration status changes to `done` and the `result` field contains the number of installed canonicals.
58+
59+
### Uninstall a FHIR package
60+
61+
Use `far-migration-fhir-package-uninstall` to remove a previously installed package:
62+
63+
```json
64+
{
65+
"resourceType": "AidboxMigration",
66+
"id": "us-core-uninstall",
67+
"action": "far-migration-fhir-package-uninstall",
68+
"status": "to-run",
69+
"params": {
70+
"resourceType": "Parameters",
71+
"parameter": [
72+
{
73+
"name": "package",
74+
"valueString": "hl7.fhir.us.core@3.1.1"
75+
}
76+
]
77+
}
78+
}
79+
```
80+
81+
## Run a SQL migration
82+
83+
Use the `aidbox-migration-run-sql` action to execute arbitrary SQL statements.
84+
85+
{% hint style="info" %}
86+
Available since the 2602 release.
87+
{% endhint %}
88+
89+
```json
90+
{
91+
"type": "transaction",
92+
"resourceType": "Bundle",
93+
"entry": [
94+
{
95+
"request": {
96+
"method": "POST",
97+
"url": "AidboxMigration",
98+
"ifNoneExist": "id=create-encounter-index"
99+
},
100+
"resource": {
101+
"resourceType": "AidboxMigration",
102+
"id": "create-encounter-index",
103+
"action": "aidbox-migration-run-sql",
104+
"status": "to-run",
105+
"params": {
106+
"resourceType": "Parameters",
107+
"parameter": [
108+
{
109+
"name": "sql",
110+
"valueString": "CREATE INDEX IF NOT EXISTS encounter_subject_id ON encounter ((resource #>> '{subject, id}'));"
111+
}
112+
]
113+
}
114+
}
115+
}
116+
]
117+
}
118+
```
119+
120+
After execution, the migration status changes to `done` and `result.valueBoolean` is `true`.
121+
122+
{% hint style="warning" %}
123+
Invalid SQL causes the migration to fail with a 422 error. In a transaction bundle, this rolls back the entire transaction and prevents Aidbox from starting.
124+
{% endhint %}
125+
126+
## Using with Init Bundle
127+
128+
Set the `BOX_INIT_BUNDLE` environment variable to load migrations on startup:
129+
130+
```yaml
131+
volumes:
132+
- ./init-bundle.json:/tmp/init-bundle.json
133+
environment:
134+
BOX_INIT_BUNDLE: file:///tmp/init-bundle.json
135+
```
136+
137+
{% hint style="info" %}
138+
The `ifNoneExist` parameter in the bundle entry ensures idempotency — if a migration with the same `id` already exists, it is skipped. Without `ifNoneExist`, a repeated POST returns a 409 duplicate key error.
139+
{% endhint %}
140+
141+
## Combining multiple migrations
142+
143+
You can include multiple migrations in a single Init Bundle:
144+
145+
```json
146+
{
147+
"type": "transaction",
148+
"resourceType": "Bundle",
149+
"entry": [
150+
{
151+
"request": {
152+
"method": "POST",
153+
"url": "AidboxMigration",
154+
"ifNoneExist": "id=install-us-core"
155+
},
156+
"resource": {
157+
"resourceType": "AidboxMigration",
158+
"id": "install-us-core",
159+
"action": "far-migration-fhir-package-install",
160+
"status": "to-run",
161+
"params": {
162+
"resourceType": "Parameters",
163+
"parameter": [
164+
{ "name": "package", "valueString": "hl7.fhir.us.core@3.1.1" }
165+
]
166+
}
167+
}
168+
},
169+
{
170+
"request": {
171+
"method": "POST",
172+
"url": "AidboxMigration",
173+
"ifNoneExist": "id=create-custom-index"
174+
},
175+
"resource": {
176+
"resourceType": "AidboxMigration",
177+
"id": "create-custom-index",
178+
"action": "aidbox-migration-run-sql",
179+
"status": "to-run",
180+
"params": {
181+
"resourceType": "Parameters",
182+
"parameter": [
183+
{
184+
"name": "sql",
185+
"valueString": "CREATE INDEX IF NOT EXISTS patient_birthdate ON patient ((resource #>> '{birthDate}'));"
186+
}
187+
]
188+
}
189+
}
190+
}
191+
]
192+
}
193+
```
194+
195+
## Checking migration status
196+
197+
List all migrations:
198+
199+
```http
200+
GET /fhir/AidboxMigration
201+
```
202+
203+
Each migration has a `status` field:
204+
205+
| Status | Description |
206+
|--------|-------------|
207+
| `to-run` | Migration is queued for execution |
208+
| `done` | Migration completed successfully |
209+
210+
## See also
211+
212+
{% content-ref url="init-bundle.md" %}
213+
[init-bundle.md](init-bundle.md)
214+
{% endcontent-ref %}
215+
216+
{% content-ref url="../reference/system-resources-reference/core-module-resources.md" %}
217+
[AidboxMigration resource reference](../reference/system-resources-reference/core-module-resources.md)
218+
{% endcontent-ref %}
219+
220+
{% content-ref url="../tutorials/artifact-registry-tutorials/upload-fhir-implementation-guide/how-to-load-fhir-ig-with-init-bundle.md" %}
221+
[Tutorial: Load FHIR IG with Init Bundle](../tutorials/artifact-registry-tutorials/upload-fhir-implementation-guide/how-to-load-fhir-ig-with-init-bundle.md)
222+
{% endcontent-ref %}
223+
224+
{% content-ref url="../tutorials/other-tutorials/how-to-run-sql-via-init-bundle.md" %}
225+
[Tutorial: Run SQL statements via Init Bundle](../tutorials/other-tutorials/how-to-run-sql-via-init-bundle.md)
226+
{% endcontent-ref %}

‎docs/modules/profiling-and-validation/fhir-schema-validator/setup-aidbox-with-fhir-schema-validation-engine.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -59,13 +59,13 @@ If you don't specify the `BOX_FHIR_TERMINOLOGY_SERVICE_BASE_URL` environment var
5959
Extensions referenced in data instances must be known to Aidbox. If Aidbox encounters an unknown extension during validation, it will raise a validation error.
6060

6161
```
62-
BOX_FHIR_VALIDATOR_STRICT_EXTENSION_RESOLUTION_ENABLED=true
62+
BOX_FHIR_VALIDATOR_STRICT_EXTENSION_RESOLUTION=true
6363
```
6464

6565
#### FHIRSchema Validator Strict Profile Resolution
6666

6767
Profiles referenced in data instances _(e.g. meta.profile)_ must be known to Aidbox. If Aidbox encounters an unknown profile during validation, it will raise a validation error.
6868

6969
```
70-
BOX_FHIR_VALIDATOR_STRICT_PROFILE_RESOLUTION_ENABLED=true
70+
BOX_FHIR_VALIDATOR_STRICT_PROFILE_RESOLUTION=true
7171
```

0 commit comments

Comments
 (0)