Resource IDs - Smile CDR Documentation

Client Assigned IDs

The FHIR specification allows clients to supply IDs for newly created resources as well (reference).

Client assigned IDs are performed using an HTTP PUT (i.e. a FHIR "update"). Note that when using an HTTP POST (i.e. a FHIR "create") the server will always assign the resource ID.

For example, consider the following client operation:

PUT /Patient/A123 Content-Type: application/fhir+json { "resourceType": "Patient", "id":"A123" }

In this example, if a resource already exists on the server with the ID A123 then it will be updated. If no resource already exists on the server with the ID A123 then a new resource will be created with this ID.

Client ID Mode

Note that this setting should not be changed for a repository that already contains data. Changing it may cause FHIR resource IDs to change, resources to become inaccessible, or the module to fail to start.

The dao_config.client_id_mode property may be set to control what IDs are allowable as client assigned IDs.

Mode: `NONE`

In this mode, clients may not assign a resource ID. Attempts to write to a resource ID that does not already exist will result in an HTTP 412 Precondition Failed.

Mode: `ANY`

In this mode, clients may assign IDs and there is no restriction on what these IDs may be, aside from the FHIR rules for valid resource IDs. If this mode is selected, it is highly recommended to use the UUID Server ID Mode if this is selected, in order to avoid any potential conflicts between client assigned numeric IDs, and IDs that are automatically generated by the server using a database sequence.

Mode: `ALPHANUMERIC` (Default)

In alphanumeric mode, clients may assign any ID except for purely numeric IDs. Purely numeric IDs are reserved for assignment by the server. This mode is the default.

In other words, a client will not be allowed to create a new resource with the ID Patient/123, as this ID is reserved in the pool of IDs used by the server when it assigns IDs. A client will be permitted to create a resource with any of the following IDs: Patient/P123, Patient/ABC, Patient/1.2.3, etc.

This behaviour has implications if you are synchronizing or replicating resources between two FHIR servers since IDs generated in the source repository may not be acceptable in the target repository.

When replicating, there are several common approaches to ensuring that resources can replicate successfully:

• Adding prefixes in the client (e.g. replacing Patient/123 with patient Patient/ACME-123) is acceptable, and can also provide a hint to the provenance of the source resource. See the note on ID prefixes in REST Hook Subscriptions for one example of how to achieve this.
• In the source server, if the UUID server ID mode is selected (see above) then there will be no issue using server generated IDs in the target server.

This setting is the default because it provides slightly better performance than the ANY setting in environments where most IDs are server-assigned. You should change this only if you do not want to allow client-assigned IDs or if you need to be able to handle client-assigned IDs that are purely numeric.

Value: `NOT_ALLOWED`

Clients are not permitted to assign IDs. If an update (HTTP PUT) is performed against an ID that does not exist on the server, the client will receive an HTTP 404 Not Found.

Value: `ANY`

Clients are allowed to assign any valid FHIR IDs. This means that clients may use both alphanumeric IDs (e.g. "A100" and "ABC") as well as purely numeric IDs such as "1234".

When this value is used, it is highly recommended to set the Server Assigned IDs mode to UUID in order to avoid any possibility of conflicts.