ERA FHIR specification - Local Development build (v1.0.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

Appointment Guidance

This page describes how Kanta appointments are created, archived, searched, replaced, and invalidated through the ERA FHIR interface.

Create an appointment

This section describes how an Appointment resource is created and stored in ERA.

Creating an appointment does not archive it to Kanta. Archiving is performed separately with the $archive-to-Kanta operation.

An appointment can be stored in:

1. The client's own register.
2. A service purchase context, in the organizer's register.

Request

POST [base]/Appointment

The request body is an Appointment resource conforming to EraAppointmentAppointment.

Processing

ERA:

1. Validates the Appointment resource.
2. Generates the display narrative.
3. Generates an appointment identifier if the client did not provide one.
4. Stores the appointment in ERA.
5. Returns operation outcome to the client.

Result

The appointment is stored in ERA.

Archive appointments

This section describes how appointments stored in ERA are archived to Kanta.

Appointment archiving is performed with the custom $archive-to-Kanta operation.

The same archiving operation can also be used for appointment replacement and invalidation. ERA determines the operation type from the appointment's logical identifier and from the provided Provenance's activity field.

Request

POST [base]/$archive-to-Kanta

The operation input is a Parameters resource containing a Provenance resource.

For appointments, the Provenance resource must conform to the EraAppointmentProvenance profile. It must contain the appointment metadata that ERA cannot determine automatically.

Processing

ERA:

1. Receives the archiving request.
2. Completes metadata that can be resolved by ERA.
3. Builds a transaction Bundle containing the Appointment and Provenance resources.
4. Signs the bundle with a system signature.
5. Attempts to send the signed bundle to Kanta.
6. Returns operation outcome to the client.

ERA determines the operation type as follows:

• If the appointment does not have a logical identifier created by Kanta, the operation is a new appointment archive.
• If the appointment already has a logical identifier created by Kanta, the operation is either a replacement or invalidation.
• For replacement and invalidation, the operation type is determined from Provenance.activity, which must contain a value from the "eArkisto - Asiakirjan korvauksen syy" code system.

Result

If Kanta accepts the appointment synchronously, ERA adds the Kanta-generated logical identifier of the appointment (Appointment.id) to Appointment.identifier.

The appointment uses the EraAppointmentAppointment profile so that multiple identifiers can be included.

ERA returns a response indicating that archiving succeeded.

If the appointment cannot be archived synchronously, ERA returns an error and instructs the client to retry the archiving operation.

If the first archiving attempt fails, the process retries archiving soon after the failure.

Search appointments from Kanta Patient Data Repository

This section describes how appointments are searched from the Kanta Patient Data Repository.

Request

Latest appointment versions can be searched with the $search-from-Kanta operation.

POST [base]/Appointment/$search-from-Kanta

Supported search cases include:

• Disclosure search across all registers.
• Search in a service purchase context across all registers.
• Search in the client's own register.
• Emergency search.
• Preliminary search.

All appointment versions can be searched with the $history-from-kanta operation.

POST [base]/Appointment/history-from-Kanta

Supported history search cases include:

• Search in the client's own register.
• Search in a service purchase context from the organizer's register.

Processing

ERA:

1. Receives the search request.
2. Validates the search parameters and required request headers.
3. Sends the search request to Kanta.
4. Receives the matching appointment data from Kanta.
5. Returns the search result to the client.

Result

ERA returns a Bundle containing the found appointments and provenances.

For $search-from-Kanta, the response contains the latest matching appointment versions.

For $history-from-kanta, the response contains matching appointment versions from appointment history. Invalidated appointments are also included.

In case of error, response contains HTTP status code and OperationOutCome resource-instance.

Replace an appointment

This section describes how an appointment stored in ERA is replaced and how the replacement is archived to Kanta.

An appointment can be replaced from:

• The client's own register.
• The organizer's register in a service purchase context.

A producer can also replace appointments created by the organizer when the service purchase context allows it.

Replacing an appointment is a two-step process:

1. Update the Appointment resource in ERA.
2. Archive the updated appointment with $archive-to-Kanta.

The replacement must target the latest appointment version. The appointment must use the Kanta-generated appointment instance id.

Request

Update the appointment in ERA:

PUT [base]/Appointment/[id]

The request body is the updated Appointment resource conforming to EraAppointmentAppointment.

The If-Match header is required. If the given version does not match the latest stored version, ERA rejects the update.

Archive the replacement to Kanta:

POST [base]/$archive-to-Kanta

The operation input contains a Provenance resource conforming to EraAppointmentProvenance.

The Provenance.activity value indicates that the archived document is a replacement.

Processing

ERA:

1. Receives the updated Appointment resource.
2. Validates that the update targets the latest stored appointment version.
3. Validates that forbidden appointment information has not been changed.
4. Stores the updated appointment in ERA.
5. Returns operation outcome to the client.
6. Receives the replacement archiving request.
7. Builds and signs the Kanta transaction bundle.
8. Sends the replacement to Kanta.
9. Returns operation outcome to the client.

Result

If the update succeeds, the updated appointment version is stored in ERA.

If Kanta accepts the replacement, the replacement becomes the active appointment version in Kanta.

If the update or archiving fails, ERA returns an error response describing the failure.

Replacement restrictions

The following appointment information must not be changed by replacing the appointment:

Information	Rule
Patient	Changing the patient (personal identification number compared to previous document version) requires invalidating the old appointment and creating a new appointment.
Healthcare service or booked service product	Changing the booked service product requires cancellation and creating a new appointment.
Appointment identifier	Must remain the same unless the service-providing unit changes within the same responsible unit and resource management scope.
Service-providing unit	Can be changed for an existing appointment only when the appointment remains within the same responsible unit and the same resource management scope.
Register holder, register, or register specifier	Changing these requires invalidating the affected documents by storing new empty documents that invalidate the documents being changed, and then creating new documents with the correct metadata.

ERA prevents forbidden changes during the Appointment update.

Appointment mutability deadline

The Appointment.extension:AppointmentMutabilityNotAfter extension can define the latest time when cancellation or rescheduling is allowed.

ERA must consider this value when the modifier is:

• The customer.
• A person acting on behalf of the customer.
• A professional who does not work for the service provider or the service-providing unit.

Invalidate an appointment

This section describes how an appointment is invalidated from Kanta.

Invalidating an appointment removes the appointment document from active use in Kanta.

An appointment can be invalidated from:

• The client's own register.
• The organizer's register in a service purchase context.

A producer can also invalidate appointments created by the organizer when the service purchase context allows it.

The appointment must use the Kanta-generated appointment instance id.

Request

Invalidation is performed with the $archive-to-Kanta operation.

POST [base]/$archive-to-Kanta

The operation input contains a Provenance resource conforming to the invalidation Provenance profile.

The Provenance resource refers to the Appointment resource that is invalidated.

Processing

ERA:

1. Receives the invalidation Provenance.
2. Builds a transaction Bundle for Kanta.
3. Adds the Provenance resource to the bundle.
4. Adds a reference to the invalidated Appointment resource to the bundle. The Appointment resource itself is not included.
5. Sets the bundle request method to POST for the Provenance.
6. Sets the bundle request method to DELETE for the Appointment reference.
7. Signs the bundle with a system signature.
8. Sends the signed bundle to Kanta.
9. Returns operation outcome to the client.

The bundle type is transaction, which means that Kanta stores both bundle entries or rejects both.

The invalidation uses the invalidation Provenance profile.

Result

If Kanta accepts the invalidation, ERA adds the deletion time to the appointment resource (FhirResource.DeleteTime). The deletion time indicates that the resource has been deleted.

The appointment resource and its earlier versions remain stored in the ERA database.

Normal read and search operations do not return invalidated appointments in the current implementation.

Kanta returns a Bundle response containing:

• For the Provenance: status, identifier, and version information.
• For the Appointment reference: status only.

If invalidation fails, ERA returns an error response describing the failure.