Descriptions

input/pagecontent/Bookanappointment.md

@@ -0,0 +1,145 @@
+# Book an appointment
+
+When booking a new appointment, the appointment resource is posted without an ID. The ID of the created Appointment is returned in response to the request.
+
+```
+POST [base]/Appointment
+Content-Type: application/fhir+json
+```
+
+```json
+{
+  "resourceType": "Appointment",
+  "status": "booked",
+  "serviceCategory": [
+    {
+      "coding": [
+        {
+          "system": "urn:oid:1.2.246.537.6.50.201801",
+          "code": "SOTE19",
+          "display": "Perheoikeudelliset palvelut"
+        }
+      ]
+    }
+  ],
+  "serviceType": [
+    {
+      "coding": [
+        {
+          "system": "urn:oid:1.2.246.537.6.49.201501",
+          "code": "NC",
+          "display": "Isyyden selvittämispalvelu"
+        }
+      ]
+    }
+  ],
+  "appointmentType": {
+    "coding": [
+      {
+        "system": "urn:oid:1.2.246.537.6.884.2015",
+        "code": "10",
+        "display": "Kertakäynti toimipaikassa"
+      }
+    ]
+  },
+  "start": "2020-01-01T12:00:00+02:00",
+  "end": "2020-01-01T12:30:00+02:00",
+  "slot": [
+    {
+      "reference": "Slot/123456789"
+    }
+  ],
+  "comment": "Äidillä ei ole virallista henkilöllisyystodistusta",
+  "participant": [
+    {
+      "actor": {
+        "identifier": {
+          "value": "010101-123N",
+          "system": "urn:oid:1.2.246.21"
+        },
+        "display": "Pentti Potilas"
+      },
+      "status": "accepted",
+      "type": [
+        {
+          "coding": [
+            {
+              "system": "http://terminology.hl7.org/CodeSystem/v3-ParticipationType",
+              "code": "SBJ",
+              "display": "subject"
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "actor": {
+        "identifier": {
+          "value": "1.2.246.10.10303777.10.777"
+        },
+        "display": "Vastaanotto"
+      },
+      "status": "accepted",
+      "type": [
+        {
+          "coding": [
+            {
+              "system": "http://terminology.hl7.org/CodeSystem/v3-ParticipationType",
+              "code": "LOC",
+              "display": "location"
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "actor": {
+        "reference": "HealthcareService/234567890",
+        "display": "Lastenvalvojan vastaanotto"
+      },
+      "status": "accepted"
+    }
+  ],
+  "extension": [
+    {
+      "url": "http://hl7.fi/fhir/StructureDefinition/NotificationInfoExtension",
+      "valueContactPoint": {
+        "system": "sms",
+        "value": "+3581234567"
+      }
+    }
+  ]
+}
+```
+
+## Response
+If the appointment is created successfully, the server responds with a `201 Created` and a Location header with the id of the appointment, e.g. `Location: [base]/Appointment/605790`.
+
+The full resource can also be returned. See more: http://www.hl7.org/fhir/http.html#ops
+
+## Implementation example
+Example client call when using [HAPI FHIR](https://hapifhir.io/)
+```java
+    public void bookAppointment() {
+        Appointment appointment = new Appointment();
+        appointment.addSlot(new Reference(new IdDt(ResourceTypes.SLOT.toCode(), "123456789")));
+        appointment.setStart(Date.from(Instant.parse("2020-01-01T12:00:00+02:00")));
+        appointment.setEnd(Date.from(Instant.parse("2020-01-01T12:30:00+02:00")));
+        appointment.setStatus(Appointment.AppointmentStatus.BOOKED);
+        // fill in rest of contents
+
+        String baseUrl = "http://example.com/fhir";
+        FhirContext fhirContext = FhirContext.forR4();
+        IGenericClient client = fhirContext.newRestfulGenericClient(baseUrl);
+
+        client
+                .create()
+                .resource(appointment)
+                .execute();
+    }
+```
+
+## Error handling
+The create should be rejected with a `400 Bad Request` if the resource cannot be created (syntax error etc.) or with a `422 Unprocessable Entity` if the resource will not be created (business logic reasons).
+
+See more: http://www.hl7.org/fhir/http.html#create

input/pagecontent/Bookanappointment2.md

@@ -0,0 +1,28 @@
+### HL7fiSched_REQ2: Book an appointment
+
+This operation documentation is for a large part based on the one defined in [US Argonaut Scheduling implementation guide](http://www.fhir.org/guides/argonaut/scheduling/index.html). 
+
+An appointment can be stored either by providing (as a parameter):
+
+1. an appointment id for an appointment with suitable status (eg. proposed) already created and stored on the server or 
+2. an actual constructed appointment resource proposal that is negotiable based on the resources needed (TO-BE-DEVELOPED). 
+
+The primary usage pattern is 1 after free appointments have been queried (ie. fetching proposed appointments). 
+
+The proper usage depends on the model of implementation (may support either or both). 
+
+Parameters
+
+|  **Use**  |  **Name**  |  **Cardinality**  |  **Type**  |  **Binding**  |  **Documentation** | 
+| --- | --- | --- | --- | --- | --- | 
+| IN |  appt-id |  0..1 |  URI |   | A resource id for one of proposed Appointments returned by a prior Query for free appointments operation. Either this or appt-resource SHALL be provided  |
+| IN |  appt-resource |  0..1 | [FinnishSchedulingAppointment](https://simplifier.net/finnishschedulingr4/finnishschedulingappointment) resource |   | AS A PLACEHOLDER CURRENTLY, to be defined. Either this or appt-id SHALL be provided |  
+| IN |  cancelled-appt-id |  0..* |  URI  |  | For signifying rescheduling of appointment (instead of just cancellation). There may be technical checks on the client or server side whether the new appointment may be seen as corresponding to previously cancelled appointment in order to define the status to "siirretty" (moved) instead of "peruttu" (cancelled). |  
+| OUT |  return |  0..1 |  Bundle (base [Bundle](https://simplifier.net/simplifier.core.r4.resources/bundle) profile) |   | Bundle of type searchset of requested FinnishSchedulingAppointment resource. If the booking is accepted, the FinnishSchedulingAppointment resource will have an updated status of "booked" and the participants element updated to include the participants. If the booking is rejected, the FinnishSchedulingAppointment resource will have an updated status of "cancelled". | 
+
+Book an appointment is always HTTP POST operation as it aims to alter the resources in question.
+
+Using `POST` Syntax the operation can be invoked as follows:
+
+`POST [base]/FinnishSchedulingAppointment/[id]/$book` when using appt-id as an input parameter <br>
+`POST [base]/FinnishSchedulingAppointment/$book` when using appt-resource as an input parameter

input/pagecontent/Cancelanappointment.md

@@ -0,0 +1,77 @@
+# Cancel an appointment
+
+## Citizen cancels
+
+An appointment is cancelled by updating the Appointment resource. The appointment and patient participant statuses are changed.
+
+* Appointment status => cancelled
+* Patient actor status => declined
+
+```
+PUT [base]/Appointment/605790
+Content-Type: application/fhir+json
+```
+
+```json
+{
+  "resourceType": "Appointment",
+  "id": "605790",
+  "status": "cancelled",
+  ...
+  "participant": [
+    {
+      "actor": {
+        "identifier": {
+          "value": "010101-123N",
+          "system": "urn:oid:1.2.246.21"
+        },
+        "display": "Pentti Potilas"
+      },
+      "status": "declined",
+      "type": [
+        {
+          "coding": [
+            {
+              "system": "http://terminology.hl7.org/CodeSystem/v3-ParticipationType",
+              "code": "SBJ",
+              "display": "subject"
+            }
+          ]
+        }
+      ]      
+    },
+    ...
+  ]
+}
+```
+
+## Response
+If the appointment is created successfully, the server responds with a `200 OK`.
+
+The full resource can also be returned. See more: http://www.hl7.org/fhir/http.html#ops
+
+## Implementation example
+Example client call when using [HAPI FHIR](https://hapifhir.io/)
+```java
+    public void cancelAppointment(FinnishAppointmentAppointment appointment) {
+        appointment.setStatus(Appointment.AppointmentStatus.CANCELLED);
+        appointment.getParticipant()
+                .stream()
+                .filter(p -> p.getActor().getType().equals(ResourceTypes.PATIENT.toCode()))
+                .findFirst()
+                .ifPresent(p -> p.setStatus(Appointment.ParticipationStatus.DECLINED));
+
+        String baseUrl = "http://example.com/fhir";
+        FhirContext fhirContext = FhirContext.forR4();
+        IGenericClient client = fhirContext.newRestfulGenericClient(baseUrl);
+
+        client.update()
+                .resource(appointment)
+                .execute();
+    }
+```
+
+## Error handling
+The update should be rejected with a `400 Bad Request` if the resource id in the URL and JSON body do not match.
+
+See more: http://www.hl7.org/fhir/http.html#rejecting-updates

input/pagecontent/Cancelanappointment2.md

@@ -0,0 +1,18 @@
+### HL7fiSched_REQ4: Cancel appointment
+
+An appointment can be cancelled by providing an appointment id for an appointment with suitable status (booked) already created and stored on the server.
+
+
+
+Parameters
+
+|  **Use**  |  **Name**  |  **Cardinality**  |  **Type**  |  **Binding**  |  **Documentation** | 
+| --- | --- | --- | --- | --- | --- | 
+| IN |  appt-id |  0..1 |  URI |   | A resource id for one of proposed Appointments returned by a prior Query for free appointments operation. Either this or appt-resource SHALL be provided  |
+| OUT |  return |  0..1 |  Bundle (base [Bundle](https://simplifier.net/simplifier.core.r4.resources/bundle) profile) |   | Bundle of type searchset of requested FinnishSchedulingAppointment resource. If the booking is cancelled successfully, the FinnishSchedulingAppointment resource will have an updated status of "cancelled" and the participants element updated to include the participants. If the booking cancellation is rejected, the FinnishSchedulingAppointment resource will keep its original status and the return message will inform that the cancellation was not successful. | 
+
+Cancellation is always a HTTP POST operation as it aims to alter the resources in question.
+
+Using `POST` Syntax the operation can be invoked as follows:
+
+`POST [base]/FinnishSchedulingAppointment/[id]/$cancel` when using appt-id as an input parameter

input/pagecontent/Case-Patientdrivenscheduling.md

@@ -0,0 +1,23 @@
+## Case - Patient driven scheduling
+
+
+### About
+The scenarios described here borrow actual implementations done in Omaolo symptom check-up service and Palveluohjain scheduling service. All interactions are done with default HTTP methods, no custom operations used.
+
+### Narrative
+No specific instructions given for narrative, which is not considered as essential for scheduling purposes.
+
+### Patient driven scheduling
+Patient driven scheduling enables a patient to use an organization’s on-line service (“patient portal”) or a third-party application to search for available appointments (free slots). The result set is based on the search criteria set on:
+* available times
+* practitioner
+* location (either as a resource reference or a string)
+* specialty
+* healthcare service type (based on Finnish codesystem THL - Sosiaali- ja terveysalan palvelunimikkeistö [1.2.246.537.6.49.201501])
+
+Other interactions
+* Patient books an appointment through a patient portal or a third-party application.
+
+* Patient re-schedules or cancels an appointment through a patient portal or a third-party application.
+
+* Patient retrieves their scheduled appointments through a patient portal or a third-party application.

input/pagecontent/Conventionsandcodesets.md

@@ -0,0 +1,27 @@
+## Conventions and codesets
+
+### Specific conventions 
+
+Resource profile elements that are related to The Finnish Institute for Health and Welfare (THL) content specification are marked in the field Reason for Inclusion and Constrainment (Requirements tag). The number preceding the name of the element is related to the id field in the content specification. The current content specification for Ajanvaraus/Tietosisältö - Ajanvarausasiakirja (1.2.246.537.6.880.201801) is dated 11.12.2019.
+
+Appointment has multiple extensions which are also based on the THL content specification.
+
+### Codesystems used
+
+- Hilmo - Terveydenhuollon erikoisalat (1.2.246.537.6.24.2003)
+- Ajanvaraus - Ajanvarauksen tila (1.2.246.537.6.881.201501)
+- THL - SOTE-organisaatiorekisteri (1.2.246.537.6.202.2008)
+- Valvira - Terveydenhuollon itsenäiset ammatinharjoittajat 2014 (1.2.246.537.6.203.2014)
+- Hilmo - Yhteystapa (1.2.246.537.6.127.201801)
+- THL - Palvelutapahtuman peruuntumisen syy (1.2.246.537.6.126.2008)
+- VRK/THL - Kuntakoodit (1.2.246.537.6.21.2003)
+- SFS - Kielikoodisto (1.2.246.537.5.40175) 
+- THL - Sosiaali- ja terveysalan palvelunimikkeistö (1.2.246.537.6.49.201501) 
+- THL - Asiointitapa (1.2.246.537.6.884.2015)
+- AR/YDIN - Sukupuoli (1.2.246.537.5.1.1997)
+- THL - Viestintäkanava (1.2.246.537.6.883.201501)
+- AR/YDIN - Palvelutapahtumaluokitus (1.2.246.537.6.88.2008)
+
+FinnishSchedulingAppointment status is mapped to Ajanvaraus - Ajanvarauksen tila (1.2.246.537.6.881.201501) code system. There is no direct mapping for statuses "siirretty" (entered-in-error?) and "suunniteltu".  
+
+

input/pagecontent/Exampleinteractions.md

@@ -0,0 +1 @@
+## Operations

input/pagecontent/FinnishAppointmentAppointment.md

@@ -0,0 +1,2 @@
+## {{link:http://hl7.fi/fhir/StructureDefinition/FinnishAppointmentAppointment}}
+{{tree:http://hl7.fi/fhir/StructureDefinition/FinnishAppointmentAppointment}}

input/pagecontent/FinnishAppointmentHealthcareService.md

@@ -0,0 +1,2 @@
+## {{link:http://hl7.fi/fhir/StructureDefinition/FinnishAppointmentHealthcareService}}
+{{tree:http://hl7.fi/fhir/StructureDefinition/FinnishAppointmentHealthcareService}}

input/pagecontent/FinnishAppointmentLocation.md

@@ -0,0 +1,2 @@
+## {{link:http://hl7.fi/fhir/StructureDefinition/FinnishAppointmentLocation}}
+{{tree:http://hl7.fi/fhir/StructureDefinition/FinnishAppointmentLocation}}

input/pagecontent/FinnishAppointmentPatient.md

@@ -0,0 +1,2 @@
+## {{link:http://hl7.fi/fhir/StructureDefinition/FinnishAppointmentPatient}}
+{{tree:http://hl7.fi/fhir/StructureDefinition/FinnishAppointmentPatient}}

input/pagecontent/FinnishAppointmentPractitioner.md

@@ -0,0 +1,2 @@
+## {{link:http://hl7.fi/fhir/StructureDefinition/FinnishSchedulingPractitioner}}
+{{tree:http://hl7.fi/fhir/StructureDefinition/FinnishAppointmentPatient}}

input/pagecontent/FinnishAppointmentSchedule.md

@@ -0,0 +1,2 @@
+## {{link:http://hl7.fi/fhir/StructureDefinition/FinnishAppointmentSchedule}}
+{{tree:http://hl7.fi/fhir/StructureDefinition/FinnishAppointmentSchedule}}

input/pagecontent/FinnishAppointmentSlot.md

@@ -0,0 +1,2 @@
+## {{link:http://hl7.fi/fhir/StructureDefinition/FinnishAppointmentSlot}}
+{{tree:http://hl7.fi/fhir/StructureDefinition/FinnishAppointmentSlot}}

input/pagecontent/FinnishSchedulingAppointment.md

@@ -0,0 +1,10 @@
+### {{link:FinnishSchedulingAppointment}} 
+
+#### Structure Definition
+
+{{tree:FinnishSchedulingAppointment}}
+
+
+
+
+

input/pagecontent/FinnishSchedulingHealthcareService.md

@@ -0,0 +1,6 @@
+### {{link:FinnishSchedulingHealthcareService}} 
+
+#### Structure Definition
+
+{{tree:FinnishSchedulingHealthcareService, snapshot}}
+

input/pagecontent/FinnishSchedulingLocation.md

@@ -0,0 +1,6 @@
+### {{link:FinnishSchedulingLocation}} 
+
+#### Structure Definition
+
+{{tree:FinnishSchedulingLocation, snapshot}}
+

input/pagecontent/FinnishSchedulingPatient.md

@@ -0,0 +1,6 @@
+### {{link:FinnishSchedulingPatient}} 
+
+#### Structure Definition
+
+{{tree:FinnishSchedulingPatient, snapshot}}
+

input/pagecontent/FinnishSchedulingPractitioner.md

@@ -0,0 +1,6 @@
+### {{link:FinnishSchedulingPractitioner}} 
+
+#### Structure Definition
+
+{{tree:FinnishSchedulingPractitioner, snapshot}}
+