Release planning

This technical design has been written to describe the technical scope of Koppeltaal 1.2.1.

The concept of the Koppeltaal Server is created to support the interaction between portals and e-interventions via a standard protocol.

The Koppeltaal Server is a system that works like a mailbox. All the registered applications (e-interventions and portals) can drop messages in the mailbox. The Koppeltaal Server routes the message to the subscribed application queues. The subscribed applications can take the messages for their own use.

Contents

1 Introduction

2 Ontology

3 Interface description

4 Security

5 Sequence diagrams

6 Message definitions

7 Message Routing

8 Proposed functionality for phase 2 and later

2. Ontology

Koppeltaal talks about information on two levels. On the higher level, Koppeltaal defines entities in health care, describing the content of the messages that are sent through the Koppeltaal Server. This level is described in the message content ontology.

On the lower level, Koppeltaal defines an infrastructure for exchanging messages between the various connected applications. This level is described in the infrastructure ontology.

2.1 Message content ontology

Message content ontology

The information that is sent through the Koppeltaal Server can be broken down in so-called resources. Each resource contains a structured set of data that describes a concept or entity about which information needs to be exchanged.

Resources are described using the FHIR standard. FHIR is a specification of entities often used in healthcare and a protocol to exchange information about these entities between systems.

Read more about FHIR

The table below shows the mapping from the entities described in the functional ontology to the available FHIR resources.

Koppeltaal FD entity FHIR resource
Activity Other(CarePlanActivity)
ActivityProvider Not mapped. Any application can provide activities. This is specified by the ActivityDefinitions an application makes available.
Application Device
Caregiver Practitioner
Carepath CarePlan
Client Patient
Intervention Not mapped. An intervention is a type of activity.
Person Not mapped. Information about people is sent as one of the specific roles: Patient, Practitioner or RelatedPerson.
Portal Not mapped. A portal is kind of application.
Related person RelatedPerson
Result DiagnosticReport (but significantly extended. See CarePlanActivityResult)
Role Not mapped. A person’s role is implied by the type of resource used. I.e., a person acting in the role of caregiver will be sent as a resource of type Practitioner.
ROM Not mapped. A ROM is a kind of activity.
Screener Not mapped. A screener is a kind of activity.
Treatment Not mapped. The treatment is implicit in the CarePlans assigned to a Patient.

Note that in the ontology below some concepts from the full functional ontology have been omitted because they are implicit. In particular, the different types of activity that are known have been abstracted into ‘ActivityDefinition’. This allows the Koppeltaal Server to relay information about any type of activity, including any future activity types.

2.2 Infrastructure ontology

Infrastructure ontology

The Koppeltaal Server acts only as a message router and filter. This means that the domain model can be very simple.

There are four entities in the ontology:

  • Application
    • A party that wishes to communicate through the Koppeltaal Server.
  • Domain
    • Each application is part of one or more domains. The domain is mainly added to the domain model for security reasons. This is explained in the paragraph ‘Security
  • Message
    • A message can be published in a domain. Only applications in that domain can receive the message.
  • MessageType
    • Each message has a type. An application will not receive messages of a type they have not registered for.

3. Interface description

Interface description

At the most basic level, applications communicate with the Koppeltaal Server using a REST interface. The interaction between applications and the Koppeltaal Server is described in the diagram below.

The interface consists of the following operations:

3.1 Retrieving the conformance statement

The conformance statement of the Koppeltaal Server is retrieved through a GET request to [Koppeltaal Server]/FHIR/Koppeltaal/metadata.

General information about the FHIR conformance statement can be found at the FHIR website.

The conformance statement of the Koppeltaal Server contains information required for the OAuth2 implementation for the single sign on. See this page for more information. This list of endpoints has been extended with a Launch Endpoint. This is the complete overview of used extensions that Koppeltaal uses for OAuth2:

Extension URI Description
http://fhir.vitalhealthsoftware.com/Profile/Conformance#Launch Identifies the OAuth2 "launch" endpoint for the server.
http://fhir-registry.smarthealthit.org/Profile/oauth-uris#authorize Identifies the OAuth2 "authorize" endpoint for the server.
http://fhir-registry.smarthealthit.org/Profile/oauth-uris#token Identifies the OAuth2 "token" endpoint for the server.

In addition, the Koppeltaal Server defines 4 extensions that control validation of requests and replies:

Extension URI Type Description
http://fhir.vitalhealthsoftware.com/Profile/Conformance#ValidateRequestsAgainstSchema Boolean If true, tells the server to validate requests against the XML Schema
http://fhir.vitalhealthsoftware.com/Profile/Conformance#ValidateRepliesAgainstSchema Boolean If true, tells the server to validate replies against the XML Schema
http://fhir.vitalhealthsoftware.com/Profile/Conformance#ValidateRequestsAgainstProfile Boolean If true, tells the server to validate requests against the FHIR Profile
http://fhir.vitalhealthsoftware.com/Profile/Conformance#ValidateRepliesAgainstProfile Boolean If true, tells the server to validate replies against the FHIR Profile

3.2 Retrieving and updating activity definitions

An application GETs activity definitions from https://koppeltaal.nl/FHIR/Koppeltaal/Other/_search?code=ActivityDefini…]. All ActivityDefinitions that are available in the application's domain are returned. These ActivityDefinitions can subsequently be assigned as ActivityDefinition in a CarePlan.activity. If the argument 'includearchived' is set to 'yes' any ActivityDefinitions that were archived are also returned.

To create or update an ActivityDefintion, an application should POST or PUT an ActivityDefinition to https://koppeltaal.nl/FHIR/Koppeltaal/Other. Do not send a CreateOrUpdateActivityDefinition back to the Koppeltaal Server, this will not work because the Koppeltaal Server does not do any functional processing of incoming messages.

3.3 Publishing a message

  1. The application POSTs a message bundle to https://koppeltaal.nl/FHIR/Koppeltaal/Mailbox.
  2. See General FHIR Resources for details about the content of a message.

3.4 Retrieving messages

There are 3 supported interactions:

  1. https://koppeltaal.nl/FHIR/Koppeltaal/MessageHeader/_search?_query=Mess… - This will find the next message with ProcessingStatus= “New”, set its ProcessingStatus to “Claimed”, and returns the complete Bundle for that Message. This must always be followed by an update of the Message status.
  2. https://koppeltaal.nl/FHIR/Koppeltaal/MessageHeader/_search?_summary=tr…] - This will return a Bundle of MessageHeaders, allowing an application to browse the available messages. A pagesize can be specified in the _count parameter, up to a maximum of 1000.
  3. https://koppeltaal.nl/FHIR/Koppeltaal/MessageHeader/_search?_id=[id] - This can be used to fetch the complete Bundle for a single Message for which the MessageHeader was retrieved through the previous action.

The following additional query parameters can be specified:

  1. Patient: Filters on the Patient dossier this message belongs
  2. event: Filters on the message type
  3. ProcessingStatus: Filters on the ProcessingStatus (New|Claimed|Success|Failed). This query parameter cannot be passed to the named query used in interaction 1.

3.5 Updating the ProcessingStatus for a Message

After a message has been successfully processed, the application must update its ProcessingStatus to “Success” on URL https://koppeltaal.nl/FHIR/Koppeltaal/MessageHeader/[id] (that is, the URL returned as id link in the for the MessageHeader in the bundle.) In case of a transient failure, the message should be put back to ProcessingStatus=“New”, allowing it to be reprocessed later. In case of a permanent failure (e.g. message content was incorrect), the ProcessingStatus should be updated to “Failed”, and an Exception description must be passed.

3.6 Subscribing to receive messages

  1. Not part of the scope for phase 1
  2. The application POSTs a Subscription resource to https://koppeltaal.nl/FHIR/Koppeltaal/Subscription.

When an application publishes a message the Koppeltaal Server will check the message against the existing subscriptions. The message will then be made available for retrieval by the applications that are subscribed to it.

3.7 Storing data in the storage service

If an application does not have its own back end and database it can use the Storage Service that has been configured for the domain it is in. To store or retrieve, the endpoint https://koppeltaal.nl/FHIR/Koppeltaal/Other?code=StorageItem can be used.

This endpoint supports the following operations:

POST [Koppeltaal Server]/FHIR/Koppeltaal/Other?code=StorageItem 
Stores a new item. The body of the request must contain a StorageItem resource.
PUT [Koppeltaal Server]/FHIR/Koppeltaal/Other/[id]?code=StorageItem 
Updates an existing entry. The argument 'id' must be the server-generated id of the stored item. The body of the request must contain a StorageItem resource.
GET [Koppeltaal Server]/FHIR/Koppeltaal/Other/{[id]}?code=StorageItem&patient=[patient-id]{&search-arguments} 
Gets any stored items that match the given id or the search arguments.

The following arguments are supported:

  1. _id (system assigned ID) - is equal to
  2. Object Type - is equal to
  3. Object Key - is equal to / starts with / contains
  4. LastUpdated (filter) - is equal to / is greater than / is greater than or equal / is less than / is less than or equal
  5. LastUpdated (sort ascending or descending)
DELETE [Koppeltaal Server]/FHIR/Koppeltaal/Other/StorageItem:{[id]} 
Deletes any stored items that match the given id.

3.8 Receiving a notification when a new message becomes available

The Koppeltaal Server offers a SignalR hub that sends a notification when a new message becomes available.

To connect:

  • Create a HubConnection to the Koppeltaal Server. The server URL can be used as the hub URL, i.e. https://edgekoppeltaal.vhscloud.nl. Both basic and token authentication can be used.
  • Create a HubProxy for the hub named 'KoppeltaalHub'.
  • Subscribe to the 'NewMessage' event.
  • Send event 'StartPush' to the hub to begin receiving new message notifications.

The event only informs the application that there is a new message, the message must be retrieved using the existing GetNextAndClaim functionality.

Security

4.1 Authentication

Phase 1:

Basic authentication using username/password, defined on the ApplicationInstances level.

After successful authentication, it will be verified that the Domain specified in the message is the same Domain as the authenticated user is assigned to.

Phase 2 or later:

OAuth

4.2 Data access across domains

Data is nearly always specific to a domain. An application should not republish any received messages in another domain. Any information received through messages in a given domain should only be published within the same domain.

4.3 Single-Sign On

4.3.1 Koppeltaal SSO Requirements

  1. Koppeltaal should provide an SSO mechanism that makes it unnecessary for portal applications to implement specific logic for each intervention it needs to work with.
  2. Applications should not be required to maintain specific configuration for each application that they access via SSO.
  3. SSO must be based on accepted standards like OAuth2.

4.3.2 Logical SSO flow

Patient clicks a button in the patient portal to open a game. The Patient Portal will open a URL on the Koppeltaal Server, passing sufficient information for Koppeltaal so that it can redirect the request to the actual application. This is the information that must be provided:

  1. ActivityDefinition identifier (linking it to a specific Application) – needed for Koppeltaal Server to lookup the publishing application and its URL
  2. CarePlanActivity identifier – needed in the target game to locate the specific activity.
  3. Patient identifier – needed in the target game to know in which Patient context the game is played
  4. User identifier – needed in the target application to be able to determine which views are going to be shown
  5. Optional additional application information, e.g. specifying that a specific page must be opened.
  6. An agreed security token that will allow the Koppeltaal Server to verify that the calling application is a known application that can be trusted. This should include at least a hash of the URL (avoiding someone to change the URL and resubmit), and some kind of shared secret, and possibly a nonce making the URL be only usable once

4.4 OAuth2 Specs driving the distributed authentication

Koppeltaal Single Sign-On is based on the OAuth2 standard, and implemented as recommended by the SMART-on-FHIR initiative (see http://docs.smartplatforms.org/)

In the context of OAuth2 two types of clients are defined:

  • "Public Client" refers to applications that run entirely on an end-user's device (e.g. JavaScript app in the browser), meaning that the application is unable to protect a "client secret". The Ranj Kick ASS game is an example of a Public Client.
  • "Confidential Client" are applications that are able to protect the "client secret", usually because the app has server-side business logic.

The only real difference between the implementation for Public and Confidential clients is in step 6, when the client accesses the Token endpoint, where the Confidential client must pass the client_id and client_secret in a Basic Authentication header. It is configured at the client level if public token requests are allowed.

4.5 Web Launch Sequence

Web Launch Sequence

Web Launch Sequence

4.5.1 Portal initiates launch sequence

Portal is already authenticated and has valid credentials. This could be:

  • The Koppeltaal username and password assigned to the Portal application to retrieve and send messages, passed in the Authorization header as "Basic" in a base64 encoded form
  • An OAuth2 bearer token retrieved by the Portal application in an earlier handshake with the Koppeltaal Server, passed in the Authorization header as "Bearer"


Portal launches a new browser widget, window, or iframe on the launch URL of the Koppeltaal server with at minimum the the following URL parameters:

  • client_id - The identifier of the Application as defined in the ActivityDefinition that is being launched
  • patient - A reference to the Patient resource reflecting the dossier in which context the activity is launched. This must be have the same value as the MessageHeader.patient attribute (extension with URL [1]) for the CarePlan.Activity that is launched.
  • user - If the currently logged on user is not the patient, but a RelatedPerson or Practitioner, this should be the resource reference to that
  • resource - Indicates the identifier of the CarePlanActivity to be started.

The portal may include any other parameters as defined in the section "Launch context arrives with your access_token" on http://docs.smartplatforms.org/authorization/scopes-and-launch-context/, or any other parameters that it wishes to include.


In the following example, the MindDistrict Client Portal wants to start the Ranj Kick ASS game for patient with identifier 72308. The user logged in is a peer with identifier 452:

https://ggz.koppeltaal.nl/OAuth2/Koppeltaal/Launch?client_id=RANJKA&patient=https%3A%2F%2Fggzeindhoven.minddistrict.com%2FPatient%2F72308&user=https%3A%2F%2Fggzeindhoven.minddistrict.com%2FRelatedPerson%2F452&resource=RANJKA

4.5.2 Koppeltaal Server redirects to the Launch URL as registered for the application

When receiving the Launch request, Koppeltaal Server will authenticate the request based on the Authorization header present. Next, the server will lookup the application based on the specified client_id, and redirect to the Launch URL as configured for that application, passing the following parameters:

  • iss - FHIR base URL of EHR responsible for "issuing" the launch notification
  • launch - Unique string identifying the launch context

So to Ranj Kick ASS game, if configured with Launch URL "http://test.kickass.ranjgames.com/builds/rev-1005/index-game.html?iss={FHIRBase}&launch={LaunchRequestId}&client_id={ClientId}&domain={TargetDomain}" will be redirected to:

Location: http://test.kickass.ranjgames.com/builds/rev-1005/index-game.html?iss=https://ggz.koppeltaal.nl/FHIR/Koppetaal&launch=xyz123&client_id=RANJKA&domain=GGZEindhoven

4.5.3 Game retrieves Authorization endpoint from Koppeltaal server

On receiving the launch notification, the uses its FHIR client to retrieves the Conformance statement from Koppeltaal server:

GET https://ggz.koppeltaal.nl/FHIR/Koppeltaal/metadata
Accept: application/json

Koppeltaal server publishes a set of OAuth2 endpoint URLs inside its conformance statement using a pair of extensions on the Conformance.rest.security element.

 

 {
 "resourceType": "Conformance",
  ...
 "rest": {
  ...
     "security": {
       "extension": [
         {
           "url": "http://fhir-registry.smartplatforms.org/Profile/oauth-uris#authorize",
           "valueUri": "https://ggz.koppeltaal.nl/Outh2/Authorize"
         },
         {
           "url": "http://fhir-registry.smartplatforms.org/Profile/oauth-uris#token",
           "valueUri": "https://ggz.koppeltaal.nl/Outh2/Token"
         }
       ],
     ...


N.B. The retrieving of the Authorization endpoint via the Conformance seems like a fairly heavy solution. Instead, the Authorization URI could be passed via the Application Launch as a parameter.

4.5.4 Game asks Koppeltaal Server for Authorization

For an application to use OAuth2 Authorization requests, it must specify the scope for which it requests authorization. For Koppeltaal version 1, there is only one agreed scope, which is "patient/*.*", which means that the game requests access to all messages for a patient to which this application is subscribed.

The game will now redirect to the Authorization endpoint as retrieved from the Koppeltaal server, passing the following information:

  • response_type - Must be filled with 'code' to indicate the application wants to receive an authorization code
  • client_id - Must be set to the assigned identifier for the game
  • scope - will contain the scopes "patient/*.read" and "launch:xyz123", binding to the existing Koppeltaal server context of this launch notification.
  • redirect_uri - The URL where to redirect to when successfully authorized.
  • state - An optional state value that the game may use for tracking the request

The game then redirects the browser to the Koppeltaal authorization URL as determined above:

Location: https://ggz.koppeltaal.nl/FHIR/Authorize?
response_type=code&
client_id=RANJKA&
redirect_uri=http%3A%2F%2Ftest.kickass.ranjgames.com%2Fbuilds%2Frev-1005%2Findex-game.html%2FAfter-Auth&
scope=patient%2F*.read%20launch%3Axyz123&
state=98wrghuwuogerg97

4.5.5 Koppeltaal server approves Authorization and redirects back to Game

When it receives an Authorization request, Koppeltaal server will check if there is an Authorization in place for the requested application, scope, and redirect URI. If found, and if the Authorization is still valid, the specified redirect URI will be called with the following parameters:

  • code - The unique Authorization Code assigned to the Authorization request
  • state - The State provided as input in the Authorization request

Following the previous example, the redirect would be as follows

Location: http://test.kickass.ranjgames.com/builds/rev-1005/index-game.html/After-Auth?code=e7f3bcf4-aeb3-449e-bfd3-e09a414536cc&state=98wrghuwuogerg97

4.5.6 Game retrieves an Access token

Next, the Game can exchange the Authorization Code for an access token by posting the following parameters to the the Koppeltaal Server Token endpoint:

  • grant_type - Must have value "authorization_code"
  • code - The Authorization code that was passed to the Game via the Authorization redirect
  • redirect_uri - Mandatory, but not further used

Confidential clients must include an Authorization header for HTTP Basic authentication, where the username is the app's client_id and the password is the app's client_secret. Public clients must leave that out.

This is an example request:

POST /OAuth2/Koppeltaal/Token HTTP/1.1
 Host: ggz.koppeltaal.nl
 Authorization: Basic bXktYXBwOm15LWFwcC1zZWNyZXQtMTIz
 Content-Type: application/x-www-form-urlencoded/token
 
 grant_type=authorization_code&
 code=e7f3bcf4-aeb3-449e-bfd3-e09a414536cc&
 redirect_uri=https%3A%2F%2Fapp%2Fafter-auth

The Koppeltaal Server will check the Authorization code, and if still valid, send the following reply:

{ "access_token": "f3d421f4-d036-468a-b9aa-de9c777ede95", "token_type": "Bearer", "expires_in": 3600, "scope": "patient/*.*", "patient": "https://ggzeindhoven.minddistrict.com/Patient/72308", "resource": "https://ggzeindhoven.minddistrict.com/RelatedPerson/452" }

Note that any additional parameters passed in the launch request would be appended to this reply.

4.5.7 Game retrieves Messages from Koppeltaal server using the acquired Bearer token

Now the Game can retrieve Messages from Koppeltaal Server using the returned Bearer token:

GET https://ggz.koppeltaal.nl/FHIR/Koppeltaal/MessageHeader/_search?_query=…
Authorization: Bearer f3d421f4-d036-468a-b9aa-de9c777ede95

4.6 Mobile Launch Sequence

Mobile Launch Sequence

The Koppeltaal Mobile Launch sequence has a lot of similarities with the Web Launch sequence described above, but has some subtle differences:

  • The initial call is made to the MobileLaunch endpoint, and is used to retrieve a Mobile Activation Code.

This call must also be made with the credentials of the calling application.

https://ggz.koppeltaal.nl/OAuth2/Koppeltaal/MobileLaunch?client_id=RANJKA&patient=https%3A%2F%2Fggzeindhoven.minddistrict.com%2FPatient%2F72308&user=https%3A%2F%2Fggzeindhoven.minddistrict.com%2FRelatedPerson%2F452&resource=RANJKA

For a detailed description of the URL and is parameters, see the description of the Web Launch Sequence above.

The response will be an activation code and the expiry time of the activation code in days:

{"activation_code":"593740","expires_in":7}

This activation code must be provided to the person that wants to use the mobile game app.

    When the Mobile App starts, it will prompt the user for an activation code

    The Mobile App must have a hard-coded or configurable FHIR Base URL for the Koppeltaal Server, since it cannot be passed in the initial launch call.

    The app should retrieve the Authorize and Token endpoints from the Koppeltaal Server by retrieving the Conformance from the Koppeltaal Server, as described above.

    The Mobile app will call the Authorize endpoint with the Mobile Activation Code as Launch Code:

    https://ggz.koppeltaal.nl/FHIR/Authorize?

        response_type=code&
        client_id=RANJKA&
        redirect_uri=http%3A%2F%2Ftest.kickass.ranjgames.com%2Fbuilds%2Frev-1005%2Findex-game.html%2FAfter-Auth&
        scope=patient%2F*.read%20launch%3A593740&
        state=98wrghuwuogerg97

The Koppeltaal server will return an authorization_code as a JSON response:

   {"authorization_code":"0db34c09-201b-41da-af41-deee89302f4b"}

    Finally, the Mobile App will retrieve a token from the Koppeltaal Server in exactly the same way as it is done in the Web Launch Sequence. The returned Access Token can subsequently be used to receive message from and submit messages to the Koppeltaal Server.

    A mobile launch code can only be used once.

 

 

4.7 Use of Refresh Tokens

If configured in the Koppeltaal server for a specific ClientId, the Koppeltaal Server will also return a refresh_token in the reply to the token request:

{
       "access_token": "f3d421f4-d036-468a-b9aa-de9c777ede95",
       "token_type": "Bearer",
       "expires_in": 900,
       "refresh_token": "e54a2533-df44-4e32-bc4d-820c05b2aed0",
       "scope": "patient/*.*",
       "patient": "https://ggzeindhoven.minddistrict.com/Patient/72308",
       "resource": "https://ggzeindhoven.minddistrict.com/RelatedPerson/452"
   }

The expiry time specified in the attribute expires_in will usually be 15 minutes or shorter, indicating that the access_token will expire sooner, and will need to be refreshed after it has expired. The client will be informed about an expired access_token through the code "expired" in the OperationOutcome:

xml:

 <OperationOutcome xmlns="http://hl7.org/fhir">
     <issue>
       <type>
         <system value="http://hl7.org/fhir/issue-type" />
         <code value="expired" />
       </type>
       <details value="Authentication failed: Bearer token 98510180-8d78-4987-9e27-c958c449f383 has expired at 2016/02/10 22:54:51" />
     </issue>
   </OperationOutcome>

json:

{
       "resourceType": "OperationOutcome",
       "issue": [{
           "type": {
               "system": "http://hl7.org/fhir/issue-type",
               "code": "expired"
           },
           "details": "Authentication failed: Bearer token 98510180-8d78-4987-9e27-c958c449f383 has expired at 2016/02/10 22:54:51"
       }]
   }

After receiving this reply, the client must get a new access_token and refresh_token from the Token-endpoint as retrieved in the Conformance, using the refresh_token that was previously received:

POST https://localhost/Petrel244/OAuth2/VHProvisioning/Token Authorization: Basic UU1OYXRpdmVBcHA6V2hvQHJlVTEyMz8= Content-Type: application/x-www-form-urlencoded grant_type=refresh_token&refresh_token=e54a2533-df44-4e32-bc4d-820c05b2aed0

The Koppeltaal Server will reply with a token response with the same fields as the original token response, containing a new Access_token as well as a new refresh_token:

 {
       "access_token": "41aeeebe-14d3-46e9-a994-54e9b5028140",
       "token_type": "Bearer",
       "expires_in": 900,
       "refresh_token": "c9141239-aec5-4e0a-af51-7c307d559184"
   }
 

Possible error codes:

Status code Issue code Description
400 invalid_request The request is missing a required parameter, includes an unsupported parameter value (other than grant type), repeats a parameter, includes multiple credentials, utilizes more than one mechanism for authenticating the client, or is otherwise malformed.
400 or 401 invalid_client Client authentication failed (e.g., unknown client, no client authentication included, or unsupported authentication method). The authorization server MAY return an HTTP 401 (Unauthorized) status code to indicatewhich HTTP authentication schemes are supported. If the client attempted to authenticate via the "Authorization" request header field, the authorization server MUST respond with an HTTP 401 (Unauthorized) status code and include the "WWW-Authenticate" response header field matching the authentication scheme used by the client.
400 or 401 invalid_grant The provided authorization grant (e.g., authorization code, resource owner credentials) or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client.
401 unauthorized_client The authenticated client is not authorized to use this authorization grant type.
401 unsupported_grant_type The authorization grant type is not supported by the authorization server.
400 invalid_scope The requested scope is invalid, unknown, malformed, or exceeds the scope granted by the resource owner.
400 unsupported_token_type The authorization server does not support the revocation of the presented token type. That is, the client tried to revoke an access token on a server not supporting this feature.

4.8 Deployment of Secure context

Deployment of Secure context

Based on the ActivityDefinition, Koppeltaal Server will:

  • Verify the token
  • If valid, lookup the associated application, and retrieve its SSO Target URL, and redirect the user to the registered URL in the target game, passing the CarePlanActivity identifier, Patient identifier, User identifier, other Application information, and an agreed security token as query parameters

On entry, the game will verify the token. If the token is valid, the game page that the user is associated with will be opened.

5. Sequence diagrams

Sequence diagrams

This chapter shows a schematic representation of the interaction between the Koppeltaal and the connected applications. Per message there is a sequence diagram that shows how the interaction will be. The first paragraph show an user interface flow chart of registering a new application in Koppeltaal .

Domain based deployment: all the integration is part of a specific domain:

5.1 Registering an application with Koppeltaal

Registering an application with Koppeltaal

In phase 1 registering applications will be done using a registration screen in the admin portal of the Koppeltaal . In a future version a message type may be defined for this functionality.

5.2 Retrieving the list of activities

Retrieving the list of activities

In phase 1 retrieving activities list will be done using a dedicated API call. The REQUEST for getting the list of Activities available as part of the application integration setup flow.

 

5.3 Tracking CarePlan Activity Status and Results

Tracking CarePlan Activity Status and Results

One of the central concepts of Koppeltaal is the CarePlan. It describes the treatment process of a Patient and the individual activities therein.

Several messages are defined to keep track of the status of the CarePlan Activities.

First and foremost is the CreateOrUpdateCarePlan message. This message conveys information about a single Patient’s CarePlan as a whole. When a Practitioner assigns one or more CarePlanActivities to a user the CarePlan will be created (or extended) with the new CarePlanActivities. An update of the complete CarePlan will be distributed through the Koppeltaal Server to subscribed applications, who can then update their internal data.

Second is the UpdateCarePlanActivityStatus message. As the name indicates, this message is sent when the status of a CarePlanActivity that is part of a CarePlan changes. For example, when the Patient starts performing a CarePlanActivity its status changes from ‘available’ to ‘in progress’.

A message of type UpdateCarePlanActivityStatus is then sent, containing the CarePlanActivity whose status changed. This message is meant to inform the application that owns the CarePlan of the change in status. The responsible application may then sent a message of type CreateOrUpdateCarePlan in turn, to inform all applications that are interested in the CarePlan as a whole (rather than specific CarePlanActivity within the CarePlan) of the change.

Note that a change in status of one CarePlanActivity may trigger a change in status in another CarePlanActivity. For example, if a CarePlanActivity is dependent on another, finishing one may cause any dependent CarePlanActivities to become available.

As soon as a CarePlanActivity is in progress results may be generated. Results are communicated using the CreateOrUpdateCarePlanActivityResult message. Results may be intermediate results and as such subject to change.

An important thing to note is that only the application that has created the CarePlan (from here on called the CarePlan’s ‘owner’) should need to be subscribed to UpdateCarePlanActivityStatus messages. This is because activities within a CarePlan can be dependent on one another. The owner of the CarePlan is responsible for accepting status updates for specific activities and sending out updates of the entire CarePlan in response.

5.4 Versioning

In Koppeltaal, all messages indicate an update to or creation of a resource. Since multiple applications may have an internal copy of a resource, applications must be aware of which version of the resource they are updating. Otherwise they risk overwriting changes made by another application. In order to guard against this type of error Koppeltaal uses a versioning system.

Koppeltaal will override any unprocessed older versions of messages that are still in a queue when a new version is received. This is done to reduce the number of messages an application has to parse.

Note that this means that an application can not rely on receiving any intermediate messages. For example, it is not guaranteed that a client portal receives status updates of an activity for each change from ‘available’ to ‘in progress’ to ‘finished’. If the activity is started and finished before the client portal retrieves its messages, any UpdateCarePlanActivityStatus messages (as well as any triggered CreateOrUpdateCarePlan messages) will list the activity status as ‘finished’ instead of ‘in progress’.

5.4.1 Sending a message

Each message received by the Koppeltaal is given a version. Any other applications that sends the same type of message for a resource must subscribe to that type of message in order to keep the internally stored resource up to date.

Each message must specify what version is the latest known to the sending application. The Koppeltaal will check this version against the latest version that is has received and reject a message if the versions do not match. This is known as a concurrent modification error.

5.4.2 Obtaining the current version number

An application must provide the version of the resource that the update was based on when sending a message. There are two ways to obtain this number, each for a different situation.

When sending a message, the Koppeltaal Server will return the generated version number as part of the reply. The application may store the returned version number to re-use later.

If there are multiple applications that may send messages with the same focal resource, each will have to subscribe to the message type in order to receive updates (and their version numbers) from the other applications.

When a resource is updated for the first time the sending application should specify no version number. When a resource is first created the sending application does not yet know a version. In that case the sending application should not specify the version number and the Koppeltaal will generate the first version. If another version is already known the Koppeltaal will reject the message in the same way as if an out-of-date version was given.

5.5 Sending of basic messages

Sending of basic messages

The basic messages can be used by all applications to interact between Practitioners and clients.

6. Message definitions

This chapter describes the definitions of all the messages which are available in ‘Koppeltaal’, the ‘language’ of the Koppeltaal Server. All these messages will be based on HL7 FHIR Resources. A Koppeltaal message will always be a bundle of general resources. The first part of this chapter describes the individual resources, the second part describes the messages.

    6.1 Guiding principles

    Each message must be self-contained; no references will be made to external resources. The primary reason is that a new Application should not need to re-query older messages in order to get up-to-date. At the same time, this way we avoid:

    • The need to store copies of all data across all applications
    • The use of external links, because this will complicate the architecture

    All resources that the sending application is owner of should be included in the message bundle. Any resources that the sending application is not owner of (for example, the ActivityDefinition for each activity in a CreateOrUpdateCarePlan message) may be referenced by their url (See FHIR - basic rules).

      6.2 Resource attribute categories

      Resource have attributes. Each attribute is in one of the following categories:

      Koppeltaal required - Applications that construct a Koppeltaal Message must provide the attributes in this category, and receiving applications must understand these attributes.

      Required attributes are marked in the with ‘Koppeltaal required: true’.

      Koppeltaal optional - Application that send and receive Koppeltaal messages should try to fill and must understand these attributes.

      Optional attributes are all attributes defined in this document that are not marked as required.

      Available in FHIR - All other attributes that are in defined in the FHIR Resource definitions

      All other attributes that are available in FHIR can be found in the FHIR resource definitions: http://www.hl7.org/implement/standards/fhir/resourcelist.html.

      FHIR Extensions - Additional attributes that are added through the FHIR Extension mechanism.

        6.3 FHIR - basic rules

        Every Application must define a unique FHIR Base URL, which is the basis on which resource URLs are created, for example https://xxx.jouwomgeving.nl/fhir .

        Every resource added to a message must have a unique Url, which is constructed as follows:

        FHIR Base Url + “/” + Resource Type + “/” + id + “/_history/” + version id

        Bijvoorbeeld https://xxx.jouwomgeving.nl/fhir/Patient/32324/_history/812909

        The version id can be an automatically incremented number, but this is not required.

        Koppeltaal FHIR profiles

        Koppeltaal will define a FHIR Profile for each defined message event, where the verb-part is left out. In other words, the profile for CreateOrUpdatecarePlan will have as identifier http://ggz.koppeltaal.nl/fhir/Koppeltaal/Profile/CarePlan. Furthermore, a profile will be defined for common parts like MessageHeader, Patient, Practictioner and Relatedperson, since these are reused over multiple messages. This leads to the following list of profiles for Koppeltaal:

        [[#|]][[#|]]

         

        Normally, FHIR requires clients to indicate which profile is intended to be used. for Koppeltaal, the Koppeltaal Server will validate messages against the profiles defined here independent of the profiles a resource is tagged with.

          6.4 Message structure

          TODO: Add diagram (Theo)

            6.5 General FHIR Resources

            There are a number of general resources that are reused between different messages. These are described below.

             

              6.5.1 (Message) Bundle

              Definition A Bundle is a container resource containing one or more FHIR resources that represent the information relevant for the processing of the event.
              Control 1..1
              Bundle.id
              Definition A unique URI for this bundle.
              Control 1..1
              Type Uri
              Bundle.title
              Definition Text statement of purpose.
              Control 1..1
              Type string
              Bundle.updated
              Definition When the bundle was built.
              Control 1..1
              Type instant
              Comments Only for Koppeltaal server outgoing messages
              Bundle.tag
              Required true
              Definition Tags can be used to add extra context information to a message. Most importantly, it is used to indicate which domain the message is part of.
              Control 2..*
              Type Tag
              Comments It is required to always add a domain tag and a message tag:
              Message tag
              Term http://hl7.org/fhir/tag
              Scheme http://hl7.org/fhir/tag/security
              Label [Domain]

              Adding the Domain security tag may seem redundant, since the Domain can also be determined from the credentials passed by the source application. However, for applications that operate in multiple domains, this is an extra check that the message is sent with credentials that match the intended domain. http://hl7.org/fhir/tag Note: The ValidateOnly tag indicates that the server should not actually process the message, but only check whether or not the message is valid.

              Bundle.entries
              Definition A bundle contains one entry for each resource that is part of the message. There is one focal resource (the resource referenced by MessageHeader.data) and zero or more resources that are referenced by the focal resource.
              Control 1..*
              Comments It is not necessary for all resources referenced by the focal resource to be included in the bundle, so long as they are not integral to understanding the content of the message.
              Bundle.entries.title
              Definition Text summary of resource content
              Control 1..1
              Type string
              Bundle.entries.updated
              Definition The moment that the resource was last updated.
              Control 1..1
              Type Instant
              Bundle.entries.content
              Definition The resource object.
              Control 1..1
              Type Resource(Any)

               

                6.5.2 MessageHeader

                Definition The header for a message exchange that is either requesting or responding to an action. The resource(s) that are the subject of the action as well as other Information related to the action are typically transmitted in a bundle in which the MessageHeader resource instance is the first resource in the bundle.
                Control 1..1
                Comments The MessageHeader must be the first resource in every Message Bundle.
                MessageHeader.identifier
                Definition The identifier of this message.
                Control 1..1
                Type id
                Comments An id is a whole number in the range 0 to 2^64-1 (optionally represented in hex), a uuid, an oid, or any other combination of lowercase letters, numerals, "-" and ".", with a length limit of 36 characters.Regex: [a-z0-9\-\.]{1,36}
                MessageHeader.timestamp
                Definition The time that the message was sent.
                Control 1..1
                Type instant
                MessageHeader.event
                Definition Code that identifies the event this message represents and connects it with it's definition.
                Control 1..1
                Binding MessageEvents
                MessageHeader.source
                Definition The source application from which this message originated.
                Control 1..1
                Requirements Allows replies, supports audit.
                MessageHeader.source.name
                Definition Human-readable name for the source application.
                Control 0..1
                Type string
                MessageHeader.source.software
                Definition Name of the software of the source application. May include configuration or other information useful in debugging.
                Control 1..1
                Type string
                Comments Not specifically used in Koppeltaal, but must be present because FHIR mandates it.
                MessageHeader.source.version
                Definition Version of the software of the source application.
                Control 0..1
                Type string
                Requirements Supports audit and possibly interface engine behavior.
                MessageHeader.source.endpoint
                Definition Identifies the endpoint of the source application
                Control 1..1
                Type uri
                Comments Not used in Koppeltaal, but must be present because FHIR mandates it. Recommended value is the FHIR Base URL of the source system also used in resource identifiers.
                MessageHeader.data
                Definition The actual data of the message - a reference to the root/focus resource of the event.
                Control 0..*
                Type Resource(Any)
                Comments Koppeltaal defines per message type what type the focus resource should have. This is also defined in the Conformance.
                MessageHeader.patient
                Definition Reference to the Patient resource reflecting the dossier this message belongs to.
                Control 0..1
                Type Resource(Patient)
                Extension http://ggz.koppeltaal.nl/fhir/Koppeltaal/Profile/MessageHeader#Patient
                Comments This field is required for all message types, except those that have no patient context. The message without patient context are CreateOrUpdatePractitioner and CreateOrUpdateActivityDefinition.
                MessageHeader.processingStatus
                Definition The status of the message with regards to the processing cycle.
                Control 0..1
                Extension http://ggz.koppeltaal.nl/fhir/Koppeltaal/Profile/MessageHeader#Processi…
                MessageHeader.processingStatus.status
                Definition The status that the message is currently in.
                Control 0..1
                Type Code
                Binding ProcessingStatus
                Extension http://ggz.koppeltaal.nl/fhir/Koppeltaal/Profile/MessageHeader#Processi…
                MessageHeader.processingStatus.statusLastChanged
                Definition The time that the message’s status was last changed.
                Control 1..1
                Type instant
                Extension http://ggz.koppeltaal.nl/fhir/Koppeltaal/Profile/MessageHeader#Processi…
                Comments Only for Koppeltaal server outgoing messages
                MessageHeader.processingStatus.exception
                Definition Details of the exception that occurred.
                Control 0..1
                Type string
                Extension http://ggz.koppeltaal.nl/fhir/Koppeltaal/Profile/MessageHeader#Processi…
                MessageHeader.isExpired
                Definition Indicates whether or not the message has expired.
                Control 0..1
                Type Boolean
                Extension http://ggz.koppeltaal.nl/fhir/Koppeltaal/Profile/MessageHeader#IsExpired
                Notes When empty, 'false' is assumed.

                 

                  6.5.3 Subscription

                  Phase 1:

                  A subscription resource details which messages an application is interested in. The assumption right now is that subscriptions are the same for all domains. In Phase 1, subscriptions will be entered by an Administrator.

                  Phase 2 or later

                  Subscription resources can be created, modified and deleted using the FHIR REST protocol. This implies that subscriptions will be maintained per ApplicationInstance.

                  • Criteria: MessageHeader(?params)
                  • Change: Reason: not required
                  • Status: Active | Off
                  • Channel
                  • Type: extension: outbox

                  6.5.4 Organization

                  Definition A formally or informally recognized grouping of people or organizations formed for the purpose of achieving some form of collective action. Includes companies, institutions, corporations, departments, community groups, healthcare practice groups, etc.
                  Control 1..1
                  Invariants Inv-1: The organization SHALL at least have a name or an id, and possibly more than one (xpath: count(f:identifier | f:name) > 0)
                  Organization.name
                  Koppeltaal required true
                  Definition A name associated with the organization.
                  Control 1..1
                  Type String
                  Invariants Inv-1: The organization SHALL at least have a name or an id, and possibly more than one (xpath: count(f:identifier | f:name) > 0)
                  Organization.identifier
                  Definition Identifier for the organization that is used to identify the organization across multiple disparate systems
                  Control 0..*
                  Type Identifier
                  Invariants Inv-1: The organization SHALL at least have a name or an id, and possibly more than one (xpath: count(f:identifier | f:name) > 0)
                  Comments All known identifiers shall be given. A typical identifier for an organization is the AGB code. If no other identifier is known, a system specific identifier can be given. (See Identifiers for information on formatting.)

                    6.5.5 Practitioner

                    Definition A person who is directly or indirectly involved in the provisioning of healthcare.
                    Control 1..1
                    Practitioner.name
                    Koppeltaal required true
                    Definition A name associated with the person.
                    Control 0..1
                    Type HumanName
                    Practitioner.identifier
                    Definition An identifier that applies to this person in this role.
                    Control 0..*
                    Type Identifier
                    Comments All known identifiers shall be given. A typical identifier for a Practitioner is the AGB or UZI code. If no other identifier is known, a system specific identifier can be given. (See Identifiers for information on formatting.)
                    Practitioner.organization
                    Definition The organization that the practitioner represents.
                    Control 0..1
                    Type Resource(Organization)

                      6.5.6 Patient

                      Definition Demographics and other administrative information about a person receiving care or other health-related services.
                      Control 1..1
                      Patient.identifier
                      Definition An identifier that applies to this person as a Patient.
                      Control 0..*
                      Type Identifier
                      Comments All known identifiers shall be given. A typical identifier for a Patient is the BSN. If no other identifier is known, a system specific identifier can be given. (See Identifiers for information on formatting.)
                      Patient.name
                      Koppeltaal required true
                      Definition A list of names associated with the person.
                      Control 1..*
                      Type HumanName
                      Comments The person may have multiple names with different uses or applicable periods. In the Koppeltaal context, a Patient must have at least one name, which can be a nickname.
                      Patient.telecom
                      Definition A contact detail (e.g. a telephone number or an email address) by which the individual may be contacted.
                      Control 0..*
                      Type Contact
                      Patient.gender
                      Definition Administrative Gender - the gender that the Patient is considered to have for administration and record keeping purposes.
                      Control 0..1
                      Binding AdministrativeGender: (http://hl7.org/fhir/vs/administrative-gender)
                      Type CodeableConcept
                      Patient.birthDate
                      Definition The date of birth for the individual.
                      Control 0..1
                      Type dateTime
                      Patient.age
                      Definition The age of the individual.
                      Control 0..1
                      Type integer
                      Extension http://ggz.koppeltaal.nl/fhir/Koppeltaal/Profile/Patient#Age
                      Patient.address
                      Definition Addresses for the individual.
                      Control 0..*
                      Type Address
                      Comments Person may have multiple addresses with different uses or applicable periods. Only applicable when a Patient is not anonymous.

                        6.5.7 RelatedPerson

                        Definition Information about a person that is involved in the care for a Patient, but who is not the target of healthcare, nor has a formal responsibility in the care process.
                        Control 1..1
                        RelatedPerson.identifier
                        Definition Identifier for a person within a particular scope.
                        Control 0..*
                        Type Identifier
                        Comments All known identifiers shall be given. A typical identifier for a person is the BSN. If no other identifier is known, a system specific identifier can be given. (See Identifiers for information on formatting.)
                        RelatedPerson.patient
                        Definition The Patient this person is related to.
                        Control 1..1
                        Type Resource(Patient)
                        RelatedPerson.relationship
                        Definition The nature of the relationship between a Patient and the related person.
                        Control 0..1
                        Binding PatientRelationshipType: (see http://hl7.org/fhir/vs/relatedperson-relationshiptype)
                        Type CodeableConcept
                        RelatedPerson.name
                        Definition A name associated with the person.
                        Control 0..1
                        Type HumanName
                        RelatedPerson.telecom
                        Definition A contact detail (e.g. a telephone number or an email address) by which the individual may be contacted.
                        Control 0..*
                        Type Contact
                        RelatedPerson.gender
                        Definition Administrative Gender - the gender that the person is considered to have for administration and record keeping purposes.
                        Control 0..1
                        Binding AdministrativeGender: (http://hl7.org/fhir/vs/administrative-gender)
                        Type CodeableConcept
                        RelatedPerson.age
                        Definition The age of the individual.
                        Control 0..1
                        Type integer
                        Extension http://ggz.koppeltaal.nl/fhir/Koppeltaal/Profile/Person#Age

                          6.5.8 Application

                          Definition An application is a portal, intervention or any other type of service available through Koppeltaal. It may provide a list of ActivityDefinitions with optional subactivities.Application is a profile on the FHIR Device resource.
                          Control 1..1
                          Application.identifier
                          Definition Identifiers assigned to this application by various organizations. The most likely organizations to assign identifiers are the manufacturer and the owner, though regulatory agencies may also assign an identifier. The identifiers identify the particular device, not the kind of device.
                          Control 0..1
                          Type Identifier
                          Application.type
                          Definition The kind of device.
                          Control 1..1
                          Binding DeviceKind
                          Type CodeableConcept
                          Application.url
                          Definition A network address on which the device may be contacted directly.
                          Control 0..1
                          Type uri
                          Comments If the device is running a FHIR server, the network address should be the root URL from which a conformance statement may be retrieved.
                          Application.roles
                          Definition The roles this application has.
                          Control 0..*
                          Binding ApplicationRoles
                          Type CodeableConcept
                          Extension http://ggz.koppeltaal.nl/fhir/Koppeltaal/Profile/Application#ApplicationRoles

                            6.5.9 ActivityDefinition

                            Definition An activity definition describes an activity that is made available by a Device. ActivityDefinition is mapped to a FHIR resource of type Other.
                            Control 1..1
                            ActivityDefinition.code
                            Definition Allows Koppeltaal to recognize the Other resource as an ActivityDefinition.
                            Control 1..1
                            Type CodeableConcept
                            Binding OtherResourceUsage
                            ActivityDefinition.application
                            Definition The application that this ApplicationDefinition is available in.
                            Control 1..1
                            Type Resource(Application)
                            Extension http://ggz.koppeltaal.nl/fhir/Koppeltaal/Profile/ActivityDefinition#App…
                            Notes The DisplayName of this relation is the Application's identifier. This value should be used in the SSO sequence as ClientID.
                            ActivityDefinition.name
                            Definition Name of the game, questionnaire, etc. A single application may provide multiple activities, e.g. a ROM provider will provide several different questionnaires.
                            Type string
                            Control 1..1
                            Extension http://ggz.koppeltaal.nl/fhir/Koppeltaal/Profile/ActivityDefinition#Act…
                            ActivityDefinition.activityDefinitionIdentifier
                            Definition A unique identifier for this activity definition.
                            Control 0..1
                            Type Identifier
                            Extension http://ggz.koppeltaal.nl/fhir/Koppeltaal/Profile/ActivityDefinition#Act…
                            ActivityDefinition.identifier
                            Definition One or more unique identifier for this activity definition.
                            Control 0..*
                            Type Identifier
                            Notes Deprecated
                            ActivityDefinition.description
                            Definition A description of the activity. May be used to judge the intended use of an activity.
                            Type string
                            Control 0..1
                            Extension http://ggz.koppeltaal.nl/fhir/Koppeltaal/Profile/ActivityDefinition#Act…
                            ActivityDefinition.type
                            Definition The type of activity.
                            Control 1..1
                            Type CodeableConcept
                            Binding ActivityKind
                            Extension http://ggz.koppeltaal.nl/fhir/Koppeltaal/Profile/ActivityDefinition#Act…
                            ActivityDefinition.subActivity
                            Definition A list of available modules within the activity.
                            Control 0..*
                            Comments For example, within the KickAss game, subactivities may be defined as the missions that are available in the game.
                            Extension http://ggz.koppeltaal.nl/fhir/Koppeltaal/Profile/CarePlan#SubActivity
                            ActivityDefinition.subActivity.name
                            Definition The name of the subactivity.
                            Control 1..1
                            Type string
                            Extension http://ggz.koppeltaal.nl/fhir/Koppeltaal/Profile/ActivityDefinition#Sub…
                            ActivityDefinition.subActivity.identifier
                            Definition An identifier for this specific subactivity.
                            Control 1..1
                            Type string
                            Extension http://ggz.koppeltaal.nl/fhir/Koppeltaal/Profile/ActivityDefinition#Sub…
                            ActivityDefinition.subActivity.description
                            Definition A description of the subactivity that can be used to judge the intended use of the subactvity.
                            Control 0..1
                            Type string
                            Extension http://ggz.koppeltaal.nl/fhir/Koppeltaal/Profile/ActivityDefinition#Sub…
                            ActivityDefinition.subActivity.isActive
                            Definition Indicates if the sub activity is active
                            Control 0..1
                            Type boolean
                            Extension http://ggz.koppeltaal.nl/fhir/Koppeltaal/Profile/ActivityDefinition#Sub…
                            Comments If no value is specified, value 'true' is assumed. This is to preserve backwards compatibility.
                            ActivityDefinition.defaultPerformer
                            Definition The person that is normally responsible for performing this activity.
                            Control 0..1
                            Type Code
                            Binding ActivityPerformer
                            Extension http://ggz.koppeltaal.nl/fhir/Koppeltaal/Profile/ActivityDefinition#Def…
                            ActivityDefinition.isActive
                            Definition The person that is normally responsible for performing this activity.
                            Control 0..1
                            Type boolean
                            Extension http://ggz.koppeltaal.nl/fhir/Koppeltaal/Profile/ActivityDefinition#IsA…
                            Comments If no value is specified, value 'true' is assumed. This is to preserve backwards compatibility.
                            ActivityDefinition.isDomainSpecific
                            Definition Indicates whether this domain is only available in the current domain or available in all domains that the providing application is part of.
                            Control 0..1
                            Type boolean
                            Extension http://ggz.koppeltaal.nl/fhir/Koppeltaal/Profile/ActivityDefinition#IsD…
                            ActivityDefinition.launchType
                            Definition Indicates how activities of this type should be launched.
                            Control 0..1
                            Type code
                            Binding ActivityDefinitionLaunchType
                            Extension http://ggz.koppeltaal.nl/fhir/Koppeltaal/Profile/ActivityDefinition#Lau…
                            Notes When this field is empty, value 'Web' is assumed.
                            ActivityDefinition.isArchived
                            Definition Indicates if the activity is archived.
                            Control 0..1
                            Type boolean
                            Extension http://ggz.koppeltaal.nl/fhir/Koppeltaal/Profile/ActivityDefinition#IsA…
                            Comments Archived ActivityDefinitions are by default not returned when GET-ting ActivityDefinitions. If no value is specified, value 'false' is assumed. This is to preserve backwards compatibility.

                              6.5.10 CarePlan

                              Definition The Careplan is a group of activities assigned in the context of care to a single Patient. CarePlanActivities can be assigned to the client, the client’s Practitioner, or a person related to the client.
                              Control 1..1
                              CarePlan.patient
                              Definition Identifies the Patient whose intended care is described by the plan.
                              Control 0..1
                              Type Resource(Patient)
                              CarePlan.status
                              Definition Indicates whether the plan is currently being acted upon, represents future intentions or is now just historical record.
                              Control 1..1
                              Binding CarePlanStatus: Indicates whether the plan is currently being acted upon, represents future intentions or is now just historical record. (See http://hl7.org/fhir/care-plan-status for values.)
                              Type Code
                              Is modifier true
                              CarePlan.participant
                              Definition Identifies all people and organizations who are expected to be involved in the care envisioned by this plan.
                              Control 0..*
                              Comments Within the context of Koppeltaal, it is expected that at least the requester of the careplan is given as a participant with role ‘Requester’.
                              CarePlan.participant.role
                              Control 0..1
                              Binding CarePlanParticipantRole
                              Type CodeableConcept
                              Comments For the Practitioner that is has requested (‘assigned’) the careplan the role should be ‘Requester’.
                              CarePlan.participant.member
                              Definition The specific person or organization who is participating/expected to participate in the CarePlan.
                              Control 1..1
                              Type Resource(Organization)
                              CarePlan.goal
                              Definition Describes the intended objective(s) of carrying out the Care Plan.
                              Control 0..*
                              Comments Goal can be achieving a particular change or merely maintaining a current state or even slowing a decline.
                              CarePlan.goal.description
                              Definition Human-readable description of a specific desired objective of the care plan.
                              Control 1..1
                              Type string
                              CarePlan.goal.status
                              Definition Indicates whether the goal has been reached and is still considered relevant.
                              Control 0..1
                              Binding CarePlanGoalStatus: Indicates whether the goal has been met and is still being targeted (see http://hl7.org/fhir/care-plan-goal-status for values).
                              Type Code
                              CarePlan.goal.notes
                              Definition Any comments related to the goal.
                              Control 0..1
                              Type string
                              Comments May be used for progress notes, concerns or other related information that doesn't actually describe the goal itself.
                              CarePlan.activity
                              Definition A list of actions to occur as part of the plan. In effect, a CarePlanActivity is an instance of an ActivityDefinition, meaning that it has been assigned to a Pratitioner, RelatedPerson or Patient to be performed.
                              Control 0..*
                              CarePlan.activity.id
                              Koppeltaal required true
                              Definition An id used to identify this activity in subsequent status updates.
                              Control 1..1
                              Type string
                              Extension http://ggz.koppeltaal.nl/fhir/Koppeltaal/Profile/CarePlan#ActivityID
                              CarePlan.activity.identifier
                              Definition An identifier for this activity. Used when sending an ActivityStatusUpdate.
                              Control 0..1
                              Type string
                              Extension http://ggz.koppeltaal.nl/fhir/Koppeltaal/Profile/CarePlan#ActivityIdent…
                              CarePlan.activity.definition
                              Definition The identifier of the ActivityDefinition that describes the activity to be performed.
                              Control 0..1
                              Type string
                              Extension http://ggz.koppeltaal.nl/fhir/Koppeltaal/Profile/CarePlan#ActivityDefin…
                              Comments The ActivityDefinition identified by this field may be located either directly in the bundle or in the set of ActivityDefinitions available at the Koppeltaal Server.
                              CarePlan.activity.type
                              Definition The type of activity.
                              Control 1..1
                              Type Coding
                              Binding ActivityKind
                              Extension http://ggz.koppeltaal.nl/fhir/Koppeltaal/Profile/CarePlan#ActivityKind
                              Comments Obsolete! Use the description of Activity Definition refered to by CarePlan.Activity.Definition instead. Needed for activities that are not defined by an ActvityDefinition; copied from ActivityDefinition otherwise.
                              CarePlan.activity.description
                              Definition Description of the activity.
                              Control 0..1
                              Type string
                              Extension http://ggz.koppeltaal.nl/fhir/Koppeltaal/CarePlan#ActivityDescription
                              Comments Obsolete! Use the description of Activity Definition refered to by CarePlan.Activity.Definition instead. Needed for activities that are not defined by an ActvityDefinition; copied from ActivityDefinition.description otherwise.
                              CarePlan.activity.subactivity
                              Definition A list of subactivities that shoould be performed.
                              Control 0..*
                              Extension http://ggz.koppeltaal.nl/fhir/Koppeltaal/CarePlan#SubActivity
                              CarePlan.activity.subactivity
                              Definition A list of subactivities that should be performed.
                              Control 0..*
                              Extension http://ggz.koppeltaal.nl/fhir/Koppeltaal/CarePlan#SubActivity
                              CarePlan.activity.subactivity.identifier
                              Definition The identifier of the subactivity.
                              Type string
                              Control 1..1
                              Extension http://ggz.koppeltaal.nl/fhir/Koppeltaal/CarePlan#SubActivityIdentifier
                              CarePlan.activity.subactivity.status
                              Definition The status of the subactivity.
                              Control 0..1
                              Extension http://ggz.koppeltaal.nl/fhir/Koppeltaal/CarePlan#SubActivityStatus
                              Comments Note that the list of assigned subactivities may differ from the list of subactivities available in the ActivityDefinition. This means that the assigner of the careplan has chosen to not let the performer perform all subactivities. The list of assigned subactivities should be a subset of the subactivites available in the ActivityDefinition.
                              Binding CarePlanActivityStatus
                              Type Code
                              CarePlan.activity.goal
                              Definition Describes the intended objective(s) of carrying out this activity.
                              Control 0..*
                              Comments The goal of an activity should be a reference to the ID of a goal in the CarePlan this activity is a part of.
                              CarePlan.activity.simple.performer
                              Definition Identifies who's expected to be involved in the activity.
                              Control 0..*
                              Type Resource (Patient)
                              CarePlan.activity.participant
                              Definition Identifies all people and organizations who are involved in the activity.
                              Control 0..*
                              Extension http://ggz.koppeltaal.nl/fhir/Koppeltaal/CarePlan#Participant
                              CarePlan.activity.participant.role
                              Control 0..1
                              Binding CarePlanParticipantRole
                              Type CodeableConcept
                              Extension http://ggz.koppeltaal.nl/fhir/Koppeltaal/CarePlan#ParticipantRole
                              Comments Note that ‘performer’ is not a separate role, but instead is specified in the field CarePlan.activity.simple.performer.
                              CarePlan.activity.participant.member
                              Definition The specific person or organization who is participating/expected to participate in the activity.
                              Control 1..1
                              Type Resource(Organization)
                              Extension http://ggz.koppeltaal.nl/fhir/Koppeltaal/CarePlan#ParticipantMember
                              CarePlan.activity.startDate
                              Definition The date that this activity should be started.
                              Control 1..1
                              Type dateTime
                              Extension http://ggz.koppeltaal.nl/fhir/Koppeltaal/CarePlan#StartDate
                              CarePlan.activity.CarePlanActivityStatus
                              Definition Identifies what progress is being made for the specific activity.
                              Control 1..1
                              Binding CarePlanActivityStatus
                              Type Coding
                              Extension http://ggz.koppeltaal.nl/fhir/Koppeltaal/CarePlan#ActivityStatus
                              CarePlan.activity.notes
                              Definition Any notes that are entered for this activity.
                              Control 0..1
                              Type string
                              CarePlan.activity.started
                              Definition The date and time when the activity was started.
                              Control 0..1
                              Type instant
                              Extension http://ggz.koppeltaal.nl/fhir/Koppeltaal/CarePlan#Started
                              CarePlan.activity.finished
                              Definition The date and time when the activity was completed.
                              Control 0..1
                              Type instant
                              Extension http://ggz.koppeltaal.nl/fhir/Koppeltaal/CarePlan#Finished
                              CarePlan.activity.cancelled
                              Definition The date and time when the activity was cancelled or skipped.
                              Control 0..1
                              Type instant
                              Extension http://ggz.koppeltaal.nl/fhir/Koppeltaal/CarePlan#Cancelled
                              CarePlan.activity.endDate
                              Definition The date and time after which the activity will no longer be available.
                              Control 0..1
                              Type dateTime
                              Extension http://ggz.koppeltaal.nl/fhir/Koppeltaal/CarePlan#EndDate
                              CarePlan.relation
                              Extension http://ggz.koppeltaal.nl/fhir/Koppeltaal/CarePlan#Relation
                              Definition Identifies any relations this careplan may have.
                              Control 0..*
                              CarePlan.relation.type
                              Extension http://ggz.koppeltaal.nl/fhir/Koppeltaal/CarePlan#RelationType
                              Definition The type of the relation.
                              Control 1..1
                              Binding CarePlanRelationTypes
                              CarePlan.relation.reference
                              Extension http://ggz.koppeltaal.nl/fhir/Koppeltaal/CarePlan#RelationReference
                              Definition The related object.
                              Control 1..1
                              Type Resource(Any)

                                6.5.11 CarePlanActivityStatus

                                Definition Describes the status of a CarePlanActivity in detail.
                                Control 1..1
                                Comments CarePlanActivityStatus maps to a resource of type Other.
                                CarePlanActivityStatus.activity
                                Definition The ID of the activity that is the subject of this message.
                                Control 1..1
                                Type string
                                Extension http://ggz.koppeltaal.nl/fhir/Koppeltaal/CarePlanActivityStatus#Activit…
                                Notes This must have the same value as CarePlan.activity.identifier for that activity in the CreateOrUpdateCarePlan message.
                                CarePlanActivityStatus.activityStatus
                                Definition Identifies what progress is being made for the specific CarePlanActivity.
                                Control 1..1
                                Binding CarePlanActivityStatus
                                Type Coding
                                Extension http://ggz.koppeltaal.nl/fhir/Koppeltaal/Profile/CarePlanActivityStatus…
                                CarePlanActivityStatus.subactivity
                                Definition The subactivities assigned as part of this activity.
                                Control 0..*
                                Extension http://ggz.koppeltaal.nl/fhir/Koppeltaal/Profile/CarePlanActivityStatus…
                                Comments Note that the list of assigned subactivities may differ from the list of subactivities available in the ActivityDefinition. This means that the assigner of the careplan has chosen to not let the performer perform all subactivities. The list of assigned subactivities should be a subset of the subactivites available in the ActivityDefinition.
                                CarePlanActivityStatus.subactivity.identifier
                                Definition The identifier of this subactivity.
                                Control 1..1
                                Type string
                                Extension http://ggz.koppeltaal.nl/fhir/Koppeltaal/CarePlanActivityStatus#SubActi…
                                Comments Must match the identifier of a subactivity as defined in the ActivityDefinition.
                                CarePlanActivityStatus.subactivity.status
                                Definition Identifies what progress is being made for this subactivity.
                                Control 1..1
                                Extension http://ggz.koppeltaal.nl/fhir/Koppeltaal/CarePlanActivityStatus#SubActi…
                                Binding CarePlanActivityStatuses
                                Type Coding
                                CarePlanActivityStatus.percentageCompleted
                                Definition An indication of the progress made on the CarePlanActivity.
                                Control 0..1
                                Type integer
                                Extension http://ggz.koppeltaal.nl/fhir/Koppeltaal/Profile/CarePlanActivityStatus…
                                CarePlanActivityStatus.blackBoxState
                                Definition BlackBoxState allows applications using Koppeltaal to extend messages with information that is not necessarily understood by other applications. The application including BlackBoxState must subscribe to the message to which the BlackBoxState is attached, allowing the application to reload the BlackBoxState next time the application starts for a certain user. BlackBoxState is implemented using the FHIR extension mechanism. Extensions can be nested. For an example, look at how the ProcessingStatus extension is defined for the MessageHeader resource. Applications using BlackBoxState must create a FHIR profile that describes their extension(s).
                                Control 0..1
                                Type Base64Binary
                                Extension Profile#Field as defined by application that owns this
                                Comments This extension must be further defined in a profile by the owner.

                                  6.5.12 CarePlanActivityResult

                                  Definition The outcome of a CarePlanActivity, including any answers given and calculated scores. The CarePlanActivityResult groups a set of Observation resources and may have a Resource reference to a Questionnaire that holds the answers to questions as entered by the Patient, RelatedPerson or Practitioner.

                                  The CarePlanActivityResult resource is an extension of the FHIR resource DiagnosticReport.

                                  Control 1..1
                                  Invariants diagnosticDateTime or a diagnosticPerod, but not both.
                                  Comments The CarePlanActivity does not have to be finished in order to have a CarePlanActivityResult. In such cases the CarePlanActivityResult describes the results obtained so far, for example, the scores calculated for the subsections of the questionnaire that have been finished so far.
                                  CarePlanActivityResult.activity
                                  Definition The id of the activity that this resource is the outcome of.
                                  Control 1..1
                                  Type string
                                  Extension http://ggz.koppeltaal.nl/fhir/Koppeltaal/CarePlanActivityResult#Activity
                                  CarePlanActivityResult.status
                                  Definition The status of the result.
                                  Control 1..1
                                  Binding CarePlanActivityResultStatus
                                  Type code
                                  Is modifier true
                                  Comments This is labeled as "Is Modifier" because applications need to take appropriate action if a report is withdrawn.
                                  CarePlanActivityResult.name
                                  Definition A code or name that describes this diagnostic report.
                                  Control 1..1
                                  Type string
                                  CarePlanActivityResult.issued
                                  Definition The date and/or time that this version of the report was released from the source diagnostic service.
                                  Control 1..1
                                  Type dateTime
                                  CarePlanActivityResult.subject
                                  Definition The subject of the report.
                                  Control 1..1
                                  Type Resource(Patient)
                                  CarePlanActivityResult.performer
                                  Definition The diagnostic service that is responsible for issuing the report.
                                  Control 1..1
                                  Resource Resource(Organization)
                                  Comments This is not necessarily the source of the atomic data items - it is the entity that takes responsibility for the clinical report.
                                  CarePlanActivityResult.diagnosticDateTime
                                  Definition The date and time at which the observations were made, e.g. date a questionnaire was filled.
                                  Control 0..1
                                  Type dateTime
                                  Invariants diagnosticDateTime or a diagnosticPerod, but not both.
                                  CarePlanActivityResult.diagnosticPeriod
                                  Definition The period during which the observations were made, e.g. the time period over which a mission in a game was completed.
                                  Control 0..1
                                  Type Period
                                  Invariants diagnosticDateTime or a diagnosticPerod, but not both.
                                  CarePlanActivityResult.result
                                  Definition Observations that are part of this diagnostic report. Observations can be simple name/value pairs (e.g. "atomic" results), or they can be grouping observations that include references to other members of the group (e.g. "panels").
                                  Control 0..*
                                  Type Resource(Observation)
                                  CarePlanActivityResult.presentedForm
                                  Definition Rich text representation of the entire result as issued by the diagnostic service. Multiple formats are allowed but they SHALL be semantically equivalent.
                                  Control 0..*
                                  Type Attachment
                                  CarePlanActivityResult.questionnaire
                                  Definition The answers given by the performer.
                                  Control 0..*
                                  Extension http://ggz.koppeltaal.nl/fhir/Koppeltaal/CarePlanActivityResult#Questio…
                                  Type Resource(Questionnaire)

                                    6.5.13 Questionnaire

                                    Definition The Questionnaire is used to convey the choices made while playing a game or answering a ROM questionnaire.
                                    Questionnaire.name
                                    Koppeltaal required true
                                    Definition Structured name for a predefined list of questions this questionnaire is responding to. May not be defined for choices made in a game.
                                    Control 0..1
                                    Type CodeableConcept
                                    Binding Defined by Application
                                    Questionnaire.status
                                    Koppeltaal required true
                                    Definition The lifecycle status of the questionnaire as a whole.
                                    Control 1..1
                                    Type CodeableConcept
                                    Binding QuestionnaireStatus
                                    Comments For phase 1, it is recommended to only sent results when the activity has been completed. This is because not all applications support recalling/cancelling of intermediate results.
                                    Questionnaire.authored
                                    Koppeltaal required true
                                    Definition The date and/or time that this the questionnaire was authored.
                                    Control 1..1
                                    Type dateTime
                                    Comments This field is required by FHIR. It can be used to differentiate different versions of the questionnaire.
                                    Questionnaire.group
                                    Koppeltaal required true
                                    Definition A group of questions
                                    Control 0..1
                                    Comments The Questionnaire itself has one "root" group with the actual contents of the Questionnaire.
                                    Questionnaire.group.question
                                    Koppeltaal required true
                                    Definition Questions within the group. The order of questions within the group is relevant.
                                    Control 0..*
                                    Requirements Must register answers to questions.
                                    Comments The Questionnaire itself has one "root" group with the actual contents of the Questionnaire.
                                    Questionnaire.group.question.name
                                    Koppeltaal required true
                                    Definition Structured name for the question that identifies this question within the Questionnaire or Group.
                                    Control 0..1
                                    Type CodeableConcept
                                    Binding Is defined by Application
                                    Requirements Structured name identifies the question so the answers can be extracted and used.
                                    Questionnaire.answer[x] (most likely answerString)
                                    Definition Single-valued answer to the question.
                                    Control 0..1
                                    Type string
                                    Comments Only one of answer[x] or choice can be provided
                                    Questionnaire.group.question.choice
                                    Definition Selections made by the user from the list of options.
                                    Control 0..*
                                    Type Coding
                                    Comments Only one of answer[x] or choice can be provided
                                    Questionnaire.group.question.options
                                    Definition Reference to a valueset containing the possible options.
                                    Control 0..1
                                    Type Resource(ValueSet)

                                      6.5.14 Observation

                                      Definition The Observation provides a single score for a certain aspect of an intervention.
                                      Observation.name
                                      Koppeltaal required true
                                      Definition Describes what was observed. Sometimes this is called the observation "code".
                                      Control 1..1
                                      Type CodeableConcept
                                      Binding ActivityDefinition.observation
                                      Observation.status
                                      Koppeltaal required true
                                      Definition The status of the result value.
                                      Control 1..1
                                      Type code
                                      Binding http://www.hl7.org/implement/standards/fhir/observation-status.html
                                      Observation.reliability
                                      Koppeltaal required true
                                      Definition An estimate of the degree to which quality issues have impacted on the value reported.
                                      Control 1..1
                                      Type code
                                      Binding http://hl7.org/fhir/observation-reliability
                                      Comments Will usually have the value “ok”.
                                      Observation.value[x]
                                      Koppeltaal required true
                                      Definition The score for the specific observation.
                                      Control 0..1
                                      Type CodeableConcept|Attachment|Ratio|Period|SampledData|string

                                        6.5.15 UserMessage

                                        Definition A message sent from a user or device to a user.
                                        Control 1..1
                                        UserMessage.context
                                        Definition An uri that describes the context of the message.
                                        Control 0..1
                                        Type Uri
                                        Extension http://ggz.koppeltaal.nl/fhir/Koppeltaal/Profile/UserMessage#Context
                                        UserMessage.code
                                        Definition Allows Koppeltaal to recognize the Other resource as a UserMessage.
                                        Control 1..1
                                        Type CodeableConcept
                                        Binding OtherResourceUsage
                                        UserMessage.from
                                        Definition The sender of the message.
                                        Control 1..1
                                        Type Resource(Device)
                                        Extension http://ggz.koppeltaal.nl/fhir/Koppeltaal/Profile/UserMessage#From
                                        UserMessage.to
                                        Definition The intended receiver of the message.
                                        Control 1..1
                                        Type Resource(Patient)
                                        Extension http://ggz.koppeltaal.nl/fhir/Koppeltaal/Profile/UserMessage#To
                                        UserMessage.messageKind
                                        Definition Which kind of message this represents.
                                        Control 1..1
                                        Type CodeableConcept
                                        Binding MessageKind
                                        Extension http://ggz.koppeltaal.nl/fhir/Koppeltaal/Profile/UserMessage#MessageKind
                                        UserMessage.subjectString
                                        Definition A short description of the content of the message.
                                        Control 1..1
                                        Type string
                                        Extension http://ggz.koppeltaal.nl/fhir/Koppeltaal/Profile/UserMessage#SubjectStr…
                                        Comments This attribute is not called ‘subject’ because FHIR already defines an attribute with that name for a different purpose.
                                        UserMessage.content
                                        Definition The text content of the message. Can be rich text.
                                        Control 1..1
                                        Type string
                                        Extension http://ggz.koppeltaal.nl/fhir/Koppeltaal/Profile/UserMessage#Content

                                          6.5.16 StorageItem

                                          Definition A piece of arbitrary data that can be stored through the Koppeltaal Server Storage API. Based on the Other FHIR resource.
                                          Control 1..1
                                          StorageItem.code
                                          Definition Allows Koppeltaal to recognize the Other resource as a StorageItem.
                                          Control 1..1
                                          Type CodeableConcept
                                          Binding OtherResourceUsage
                                          StorageItem.contentType
                                          Definition MimeType of the binary content represented as a standard MimeType (BCP 13).
                                          Binding Required: BCP 13 (RFCs 2045, 2046, 2047, 4288, 4289 and 2049)] (The mime type of an attachment)
                                          Control 1..1
                                          Type Code
                                          Extension http://ggz.koppeltaal.nl/fhir/Koppeltaal/Profile/StorageItem#ContentType
                                          StorageItem.content
                                          Definition The actual content, base64 encoded.
                                          Control 1..1
                                          Type base64Binary
                                          Extension http://ggz.koppeltaal.nl/fhir/Koppeltaal/Profile/StorageItem#Content
                                          StorageItem.patientIdentifier
                                          Definition The patient in whose context this data belongs.
                                          Control 1..1
                                          Type Resource(Patient)
                                          Extension http://ggz.koppeltaal.nl/fhir/Koppeltaal/Profile/StorageItem#PatientIde…
                                          StorageItem.objectType
                                          Definition The type of the object being stored.
                                          Control 1..1
                                          Type String
                                          Extension http://ggz.koppeltaal.nl/fhir/Koppeltaal/Profile/StorageItem#ObjectType
                                          StorageItem.objectKey
                                          Definition The key of the object. Should be unique for (at least) the combination of PatientIdentifier and ObjectType.
                                          Control 1..1
                                          Type String
                                          Extension http://ggz.koppeltaal.nl/fhir/Koppeltaal/Profile/StorageItem#ObjectKey
                                          StorageItem.lastModified
                                          Definition The instant this object was last modified.
                                          Control 1..1
                                          Type Instant
                                          Extension http://ggz.koppeltaal.nl/fhir/Koppeltaal/Profile/StorageItem#LastModifi…
                                          StorageItem.ApplicationIdentifier
                                          Definition Indicates which application stored this item.
                                          Control 1..1
                                          Type String
                                          Comments The Koppeltaal Server ensures this field is filled. It is not possible to set your own value or update it.
                                          StorageItem.DomainName
                                          Definition Indicates which domain this item is part of.
                                          Control 1..1
                                          Type String
                                          Comments The Koppeltaal Server ensures this field is filled. It is not possible to set your own value or update it.

                                            6.6 Identifiers

                                            In the context of health care there are a number of widely used types of identifiers for both organizations and persons. The list below shows how to represent these in Koppeltaal messages.

                                            Note that it is not allowed to use ‘placeholder’ identifiers, such as x’s or all 9’s; If an identifier is given it must be a unique identifier for the entity within the given system. In other words, there may never be two entities of the same type that have the exact same identifier.

                                              6.6.1 Common identifiers

                                              The below identifier systems are commonly used in Health Care in the Netherlands. In order to standardize their use, please use the below format information wherever any of these identifiers are used.

                                              Note: the System Uri’s can be found at http://fhir.nl/fhir/NamingSystem/[SystemUri].

                                              Identifier type Use Label SystemUri Identifies
                                              AGB Official AGB agb-z Organization | Practitioner
                                              BSN Official BSN bsn Patient | RelatedPerson
                                              UZI Secondary UZI Person uzi-nr-pers Practitioner
                                              UZI Secondary UZI Device uzi-nr-sys Device
                                              System-specific Secondary [System name]   Any

                                                6.7 Koppeltaal value sets

                                                  6.7.1 CarePlanActivityResultStatus

                                                  Code system URL: http://ggz.koppeltaal.nl/fhir/Koppeltaal/CarePlanActivityResultStatus
                                                  Value set URL: http://ggz.koppeltaal.nl/fhir/Koppeltaal/ValueSet/CarePlanActivityResul…
                                                  Definition: The possible statuses that a CarePlanActivityResult can have.

                                                   

                                                  Code Display Definition
                                                  Achieved Achieved The CarePlanActivityctivity that the result belongs to has been completed, the result will not change anymore.
                                                  Failed Failed Performing the CarePlanActivityhas failed. The result should not be considered valid.
                                                  Open Open The CarePlanActivitythat the result belongs to is still in progress. The result is an intermediate result and may still change.

                                                    6.7.2 MessageEvents

                                                    Code system URL: http://ggz.koppeltaal.nl/fhir/Koppeltaal/MessageEvents
                                                    Value set URL: http://ggz.koppeltaal.nl/fhir/Koppeltaal/ValueSet/MessageEvents
                                                    Definition: The type of event that a message represents.

                                                     

                                                    Code Display Definition
                                                    CreateOrUpdateUser CreateOrUpdateUser Message that updates user information.
                                                    CreateOrUpdateCarePlan CreateOrUpdateCarePlan Message that updates a careplan.
                                                    UpdateCarePlanActivityStatus UpdateCarePlanActivityStatus Message that updates the status of an activity.
                                                    CreateOrUpdateCarePlanActivityResult CreateOrUpdateCarePlanActivityResult Message that updates the result of an activity.
                                                    CreateOrUpdateUserMessage CreateOrUpdateUserMessage Message that sends a message to a user.

                                                     

                                                      6.7.3 ApplicationRoles

                                                      Code system URL: http://ggz.koppeltaal.nl/fhir/Koppeltaal/ApplicationRoles
                                                      Value set URL: http://ggz.koppeltaal.nl/fhir/Koppeltaal/ValueSet/ApplicationRoles
                                                      Definition: The Roles that a Koppeltaal Application can have.

                                                       

                                                      Code Display Definition
                                                      PractitionerPortal Practitioner Portal  
                                                      PatientPortal Patient Portal  
                                                      RelatedPersonPortal Related Person Portal  
                                                      Game Game  
                                                      ELearning E-Learning  
                                                      ROM ROM  

                                                        6.7.4 DeviceKind

                                                        Code system URL: http://ggz.koppeltaal.nl/fhir/Koppeltaal/DeviceKind
                                                        Value set URL: http://ggz.koppeltaal.nl/fhir/Koppeltaal/ValueSet/DeviceKind
                                                        Definition: The type of a device. In Koppeltaal we only support ‘Application’.

                                                         

                                                        Code Display Definition
                                                        Application Application The device is a kind of application.

                                                          6.7.5 ActivityKind

                                                           

                                                          Code Display Definition
                                                          Game Game An intervention that can be played like a game.
                                                          ELearning E-Learning An intervention that works through E-learning.
                                                          Questionnaire Questionnaire Questionnaire for ROM or screening.
                                                          Meeting Meeting A meeting between two or more participants. For example, a consult between the Patient and a Practitioner.
                                                          MultipleActivityTemplate Multiple activity template An 'activity' that represents multiple activities; for example a ROM measuring cycle.

                                                            6.7.6 MessageKind

                                                            Code system URL: http://ggz.koppeltaal.nl/fhir/Koppeltaal/UserMessageKind
                                                            Value set URL: http://ggz.koppeltaal.nl/fhir/Koppeltaal/ValueSet/UserMessageKind
                                                            Definition: The type of the UserMessage. Receiving applications may use the given value as an indication of how to process and/or display this message, e.g. marking urgent messages red, displaying them on a Practitioner’s home page or sending an email notification.

                                                             

                                                            Code Display Definition
                                                            Alert Alert A notification of an urgent event, usually requiring immediate action.
                                                            Advice Advice Advice given, usually from a Practitioner to a Patient.
                                                            Question Question A question asked, usually from a Patient to a Practitioner.
                                                            Answer Answer An answer to a question asked.
                                                            Notification Notification A notification of an event.
                                                            Message Message A simple message without additional meaning.
                                                            Request Request A request of some type. For example, a request from the Patient to a Practitioner to have a face to face meeting.

                                                              6.7.7 CarePlanActivityStatus

                                                              Code system URL: http://ggz.koppeltaal.nl/fhir/Koppeltaal/CarePlanActivityStatus
                                                              Value set URL: http://ggz.koppeltaal.nl/fhir/Koppeltaal/ValueSet/CarePlanActivityStatus
                                                              Definition: The possible statuses that a CarePlanActivity can have.
                                                              Code Display Definition
                                                              Waiting Waiting The CarePlanActivity has been defined as being part of the careplan, but can not yet be performed. It may be dependent on the completion of another task, earlier in the careplan.
                                                              Available Available The CarePlanActivity can be performed by the Patient, but has not yet been started.
                                                              InProgress InProgress The CarePlanActivity has been started by the Patient, but has not yet been finished.
                                                              Completed Completed The CarePlanActivity has been finished by the Patient.
                                                              Cancelled Cancelled The Practitioner has decided that the CarePlanActivity does not need to be performed (anymore).
                                                              Expired Expired The time period in which the CarePlanActivity could be performed has expired and the activity can no longer be performed.
                                                              SkippedByUser SkippedByUser The Patient has indicated that he or she does not wish to perform this CarePlanActivity.

                                                                6.7.8 OtherResourceUsage

                                                                Code system URL: http://ggz.koppeltaal.nl/fhir/Koppeltaal/OtherResourceUsage

                                                                Value set URL: http://ggz.koppeltaal.nl/fhir/Koppeltaal/ValuSet/OtherResourceUsage

                                                                Definition: Used to identify the different types of Other resources used in Koppeltaal.

                                                                Code Display Definition
                                                                ActivityDefinition ActivityDefinition Used to identify the Koppeltaal resource ActivityDefinition.
                                                                UserMessage UserMessage Used to identify the Koppeltaal resource UserMessage.
                                                                CarePlanActivityStatus CarePlanActivityStatus Used to identify the Koppeltaal resource CarePlanActivityStatus.
                                                                StorageItem StorageItem Used to identify the Koppeltaal resource StorageItem.

                                                                  6.7.9 QuestionnaireStatus

                                                                  Code system URL: http://ggz.koppeltaal.nl/fhir/Koppeltaal/QuestionnaireStatus
                                                                  Value set URL: http://ggz.koppeltaal.nl/fhir/Koppeltaal/ValueSet/QuestionnaireStatus
                                                                  Definition: The different statuses a questionnaire can have.

                                                                   

                                                                  Code Display Definition
                                                                  Open Open Not yet answered.
                                                                  InProgress InProgress Assigned user started answering.
                                                                  Completed Completed The questionnaire has been answered.
                                                                  Amended Amended A Practitioner has amended some answers.
                                                                  Expired Expired The questionnaire expired before it was answered.

                                                                    6.7.10 CarePlanParticipantRole

                                                                    Code system URL: http://ggz.koppeltaal.nl/fhir/Koppeltaal/CarePlanParticipantRole
                                                                    Value set URL: http://ggz.koppeltaal.nl/fhir/Koppeltaal/ValueSet/CarePlanParticipantRo…
                                                                    Definition: A person can participate in a CarePlan or CarePlanActivity in different roles.

                                                                     

                                                                    Code Display Definition
                                                                    Requester Requester The person that requested the careplan or activity to be performed.
                                                                    Supervisor Supervisor Provides overall monitoring.
                                                                    Thirdparty Thirdparty A person related to the patient, but not acting in the role of patient themselves.
                                                                    Caregiver Caregiver Treats patients.
                                                                    Secretary Secretary Performs administrative functions.
                                                                    Analyst Analyst Uses aggregate data to perform research.

                                                                      6.7.11 ProcessingStatus

                                                                      Code system URL: http://ggz.koppeltaal.nl/fhir/Koppeltaal/ProcessingStatus
                                                                      Value set URL: http://ggz.koppeltaal.nl/fhir/Koppeltaal/ValueSet/ProcessingStatus
                                                                      Definition: The processing status of a message.
                                                                      Code Display Definition
                                                                      New New The message has not yet been retrieved by the subscribed application.
                                                                      Claimed Claimed he subscribed application has claimed the message for processing. No other processes should handle this message.
                                                                      Success Success The message has been processed successfully.
                                                                      Failed Failed An error has occurred during processing.
                                                                      ReplacedByNewVersion Old A newer version of the message was received before this message was processed.
                                                                      MaximumRetriesExceeded MaximumRetriesExceeded The application has claimed this message, but failed to update the status to 'Success' or 'Failed' several times.

                                                                        6.7.12 ActivityPerformer

                                                                        Code system URL: http://ggz.koppeltaal.nl/fhir/Koppeltaal/ActivityPerformer
                                                                        Value set URL: http://ggz.koppeltaal.nl/fhir/Koppeltaal/ValueSet/ActivityPerformer
                                                                        Definition: Types of persons that can perform activities.

                                                                         

                                                                        Code Display Definition
                                                                        Patient Patient A patient; the person under treatment.
                                                                        Practitioner Practitioner A practitioner; the person giving treatment.
                                                                        RelatedPerson RelatedPerson A related person; a person related to the patient..

                                                                         

                                                                         

                                                                        Code Display Definition
                                                                        Web Web The activity is reachable by navigating to the URL returned by the Web Launch Sequence.
                                                                        Mobile Mobile The activity must be activated by using the code returned by the Mobile Launch Sequence.
                                                                        None None The activity cannot be started.

                                                                          6.7.13 CarePlanRelationTypes

                                                                          Code system URL: http://ggz.koppeltaal.nl/fhir/Koppeltaal/CarePlanRelationTypes
                                                                          Value set URL: http://ggz.koppeltaal.nl/fhir/Koppeltaal/ValueSet/CarePlanRelationTypes
                                                                          Definition: The kind of relation that a CarePlan has with the referred object.

                                                                           

                                                                          Code Display Definition
                                                                          Parent Parent This CarePlan is a part of the given CarePlan.

                                                                            6.8 Messages

                                                                            Each message is sent as a bundle of resources, containing exactly one MessageHeader. The message type must be specified in the ‘event’ attribute of the MessageHeader.

                                                                             

                                                                              6.8.1 CreateOrUpdatePatient

                                                                              Definition: This message is sent when the data of a Patient changed. It allows subscribed applications to either update their internally stored data or create a new record if necessary.

                                                                              Event: CreateOrUpdatePatient

                                                                              Focal resource: The user to be updated: Resource(Patient)

                                                                               

                                                                                6.8.2 CreateOrUpdatePractitioner

                                                                                Definition: This message is sent when the data of a Practitioner changed. It allows subscribed applications to either update their internally stored data or create a new record if necessary.

                                                                                Event: CreateOrUpdatePractitioner

                                                                                Focal resource: The user to be updated: Resource(Practitioner)

                                                                                  6.8.3 CreateOrUpdateRelatedPerson

                                                                                  Definition: This message is sent when the data of a RelatedPerson changed. It allows subscribed applications to either update their internally stored data or create a new record if necessary.

                                                                                  Event: CreateOrUpdateRelatedPerson

                                                                                  Focal resource: The user to be updated: Resource(RelatedPerson)

                                                                                    6.8.4 CreateOrUpdateCarePlan

                                                                                    Definition: This message is sent when a careplan or one of its contained activities has been changed. This may also mean that the status of one of the contained activities changed.

                                                                                    Event: CreateOrUpdateCarePlan

                                                                                    Focal resource: The careplan that was created or updated: Resource(CarePlan)

                                                                                    Comments: This message is closely linked with the UpdateCarePlanActivityStatus message. When the status of an activity changes, the careplan changes as well.

                                                                                      6.8.5 UpdateCarePlanActivityStatus

                                                                                      Definition: This message is sent when the status of an activity changes. Note that this message does not include the result of the activity.

                                                                                      Event: UpdateCarePlanActivityStatus

                                                                                      Focal resource: The changed status: Resource(CarePlanActivityStatus)

                                                                                        6.8.6 CreateOrUpdateCarePlanActivityResult

                                                                                        Definition: This message is sent when a result for a CarePlan activity becomes available or is changed.

                                                                                        Event: CreateOrUpdateCarePlanActivityResultFocal resource: The result of the activity: Resource(CarePlanActivityResult)

                                                                                          6.8.7 CreateOrUpdateUserMessage

                                                                                          Definition: This message represents a text message sent from one user to another.

                                                                                          Event: CreateOrUpdateUserMessageFocal resource: The message that was sent: Resource(UserMessage)

                                                                                            6.7.8 CreateOrUpdateActivityDefinition

                                                                                            Definition: This message represents a change in the available ActivityDefinitions within a domain.

                                                                                            Event: CreateOrUpdateActivityDefinition

                                                                                            Focal resource: The activity definition that was created or updated: Resource(ActivityDefinition)

                                                                                            Message Routing[edit]

                                                                                              7.1 ERD

                                                                                              The diagram below shows the database structure which will be used for Koppeltaal, based on the domain model.

                                                                                               

                                                                                               

                                                                                                7.2 Message flow

                                                                                                Applications that are connected to Koppeltaal are able to send messages and retrieve messages. In phase 2 or later dynamically registering of subscriptions will be added.

                                                                                                When a message is sent to Koppeltaal it is placed in an inbound queue. Each message is then processed by the router to match it against the existing subscriptions. If a message matches a subscription the message is copied to an outbound queue for that application for later retrieval.

                                                                                                  7.2.1 Subscriptions

                                                                                                  By registering a subscription an application only receives the subset of data that is relevant.

                                                                                                  • In phase 1 only subscribing to specific message types is supported.
                                                                                                  • In phase 2 or later it will become possible to subscribe to messages based on the message’s content.

                                                                                                  8. Proposed functionality for phase 2 and later

                                                                                                  The functionality described below are ideas and requests that fall outside the scope for phase 1. These will be evaluated and discussed in a later phase.

                                                                                                    8.1 Patient groups

                                                                                                    In some cases treatment is performed with groups of patients. In these cases there is no single patient to assign a careplan or activity to.

                                                                                                      8.2 Caregiver groups

                                                                                                      In some cases a group of caregivers is responsible for treatment of a patient or group of patients. In these cases there is no main caregiver responsible for the caregiver.

                                                                                                        8.3 Organization levels

                                                                                                        Organizations can be structured hierarchically. For purposes of, for exampe, evaluation of performance of parts of an organization, it is interesting to keep track of the structure of organizations.