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.