Compose a launch

The launch steps on this page are the same for HTI as SHOF

To perform the launch, the following steps must be performed for both HTI and SHOF:

1. Create Koppeltaal context claims

Koppeltaal supports the following claims:

HTI claim	Type	Required	Description
resource	string	yes	The identifier of the task to be executed by the person in the sub field.
definition	url	no	A Reference that refers to the FHIR ActivityDefinition. The reference can be found on the Task.instantiates extension.
sub	reference	yes	This is a person reference to the patient, practitioner or related person.
patient	reference	no	This is a person reference to the patient, only used when the 'sub' is not a patient
intent	string	no	The intention of the launch, this field should be used to provide the intention of the launch such as the preparation, performance or review of the resource, is used, a value from the FHIR value set RequestIntent
idp_hint	string	no	Informs the auth server to use a specific IdP for the user authentication. Should be filled with the logical identifier of the IdP. See the IG for more information.

An example of the resulting HTI claims:

{
    "resource": "Task/5f684c5f-2837-4505-a534-365431912f37",
    "definition": "ActivityDefinition/d76ba97b-bfce-4a75-8e7a-2133778d1089",
    "sub": "Practitioner/225d67a7-69b9-4343-b488-064945fe3fd3",
    "patient" : "Patient/b592f103-f75b-4a63-a5dd-b75799775258",
    "intent": "plan",
    "idp_hint": "primary-practitioner-idp"
}

2. Create the JWT

The HTI:core v2.0 profile also contains claims that are always set on a JWT:

Description	Field	Value
Issuer	iss	The client_id van het portaal
Audience	aud	The device id of the module provider. This can be found via the ActivityDefinition.resource-origin extension.
Unique message id	jti	A unique identifier for this message. This value MUST be treated as a NONCE, a subsequent message with an identical jti MUST be rejected. The jti value must be a random or pseudo number, the jti MUST contain enough entropy to block brute-force attacks.
Issue time	iat	The timestamp of generating the JWT token, the value of this field MUST be validated by the module provider to not be in the future.
Expiration time	exp	The "exp" (expiration time) claim identifies the expiration time on or after which the JWT MUST NOT be accepted for processing. The value MUST be limited to 5 minutes. This value MUST be validated by the module provider, any value that exceeds the timeout MUST be rejected.

These two sets of claims should be combined to form a valid HTI v2.0 JWT. For example:

{
  "iat": 1585564845,
  "aud": "Device/123",
  "iss": "portal-client-id",
  "exp": 1585565745,
  "jti": "679e1e4c-bcb9-4fcc-80c4-f36e7063545c"
  "sub" : "Practitioner/225d67a7-69b9-4343-b488-064945fe3fd3",
  "resource" : "Task/5f684c5f-2837-4505-a534-365431912f37",
  "definition" : "ActivityDefinition/d76ba97b-bfce-4a75-8e7a-2133778d1089",
  "patient" : "Patient/b592f103-f75b-4a63-a5dd-b75799775258",
  "intent": "plan"
}

The timestamps follows the "UNIX time" convention, being the number of seconds since the epoch.

3. Sign the JWT

After the JWT is completely filled, it must be signed. For this, Signing the JWT can be followed.

4. Launch

The signed token can now be launched to the client. To find the endpoint to be launched to, the ActivityDefinition.endpoint extension can be used. The correct ActivityDefinition can be found using Task.instantiates extension (see Retrieve specific Resource).

There are minimal differences between sending via HTI and SHOF.

Topics

TOP-KT-007 - Koppeltaal Launch