Introduction
This Technical Agreement (TA) specifies a standards-based way to send a referral, order, or transfer from one care organization to another and to keep track of it until the work is done. It is built on COW IG and TA Notifications, and brings existing, separately developed Dutch agreements for this same problem together under a single, shared specification.
The conformance verbs SHALL, SHALL NOT, SHOULD, SHOULD NOT and MAY in this document are to be interpreted as defined in FHIR R4 (Conformance Rules, Conformance Language), when, and only when, they appear in capitals.
Reading this version. Requirements of the underlying specifications are repeated where this helps the reader. Each section separates them, as “Follows from …”, from the requirements that this TA specifies.
Context
Dutch healthcare organizations already exchange referrals, orders, and transfers between systems today, but they do so using at least two separately developed, incompatible mechanisms, and neither fully supports exchanging the status of that work once it is underway. The Technical Agreement Exchanging FHIR Data using a generic Notified Pull mechanism (TA NP) specifies one such mechanism, built for the exchange of the BgZ during a patient referral. The Nuts eOverdracht Bolt specifies another, built independently, on a similar timeline, for the nursing handover, a transfer of care.
Two national specifications, developed independently for closely related problems, cannot both remain the reference every new implementer is pointed to — harmonizing them is worthwhile. Doing so depends on two things being settled at the technical level:
-
TA Notifications specifies the standardized Subscription and notification mechanism by which a party learns that a resource it does not own has changed.
-
The forthcoming TA I&A specifies how the parties to an exchange identify, authenticate, and authorize one another.
Together, these give a harmonized specification the technical building blocks that neither TA NP nor eOverdracht had available when each defined its own mechanism.
These two agreements are not enough on their own. TA NP and eOverdracht each model the clinical workflow itself in their own way: a system built to one specification still cannot exchange a referral or transfer with a system built to the other, and a healthcare organization operating across both domains still needs two separate implementations to do what is, underneath, the same kind of work. The two domains are also not always separate processes: when an admitted patient moves from one hospital to another, the medical handover (TA NP) and the nursing handover (eOverdracht) belong to the same transfer and must be able to run as one integrated flow, yet each specification covers only its own half. Left alone, the divergence between the two specifications would only widen as each specification continues to evolve independently. Harmonizing the workflow model itself — not just the transport it travels over — is what allows an organization to build and maintain one implementation instead of two.
It also does something neither original specification could, precisely because each was written for one use case at a time: a harmonized model is general enough that referral, order, and transfer are simply particular instances of it, so that the next use case this ecosystem needs is described as a profile of something that already exists, rather than specified again from first principles.
This Technical Agreement is that model. It specifies, in one place, a standards-based way to exchange clinical workflow status for orders, referrals, and transfers, so that the agreements currently expressed via TA NP and via eOverdracht can each be specified and implemented as a profile of it.
Scope
In scope
-
Exchanging clinical workflow status between a Placer and a Fulfiller.
-
Hosting, creating, and updating a Coordination Task at the Placer, and the FHIR profile constraining it.
-
The standing Subscription and notification mechanism informing a Fulfiller of relevant Task changes.
-
The payload mode of the notification, and the requirements on the ids of Tasks and Subscriptions.
-
Sharing content in Task.input, including what the Placer makes available of a standard dataset.
-
The Multiple Fulfillers Pattern, including bidding by candidates, and the simpler case of a single, already-known Fulfiller.
-
Conformance to TA Routing.
-
Conformance to GF Addressing, independently of TA Routing.
Out of scope
-
Identification, authentication, and authorization of the parties — the subject of the forthcoming TA I&A.
-
How the Placer learns that a healthcare service is split, merged, renamed or retired. This follows from GF Addressing (see Changes to healthcare services).
-
How a Placer weighs the responses of the candidates and decides which one to select among multiple Fulfillers. Responses of the candidates such as accepting and bidding, and the recording of the decision, are in scope.
-
The SubscriptionTopics of the individual use cases. Each use case that is specified as a profile of this TA defines its own topics (see SubscriptionTopic).
-
Soliciting candidates that the Placer does not know in advance, such as open bids or a patient who takes the Request to a provider of their choice. Every candidate is a HealthcareService with a Subscription (see Multiple Fulfillers Pattern and Subscription).
Vocabulary
|
Term |
Definition |
|
Placer |
The zorgaanbieder that authorizes and initiates a Request. As the party that holds Subscriptions, the Placer is the Subscription Server of TA Notifications. |
|
Fulfiller |
The zorgaanbieder expected to carry out the Request. A Fulfiller receives and handles Tasks through one or more of its HealthcareServices; Task.owner identifies the HealthcareService, not the organization. As the party that receives notifications, the Fulfiller is the Subscription Client of TA Notifications. |
|
zorgaanbieder |
The healthcare provider organization on whose behalf data is exchanged, as defined in TA Notifications. In this TA, “organization” refers to a zorgaanbieder unless stated otherwise. |
|
GTK |
Gekwalificeerd Twiin Knooppunt, as defined in TA Notifications: a node through which a zorgaanbieder takes part in data exchange, which may act on behalf of several zorgaanbieders. |
|
Request |
The FHIR resource representing what is being asked for. Under this TA, the Request is a ServiceRequest (see Request types other than ServiceRequest). |
|
ActivityDefinition, PlanDefinition and CarePlan |
Three FHIR resources that describe care at different levels. An ActivityDefinition is a reusable description of one activity, independent of a patient, for example a type of service that can be requested. A PlanDefinition is a reusable description of a group of actions, which may refer to ActivityDefinitions or describe a protocol of its own. Both are definitions: a Request refers to one of them in instantiatesCanonical to say how the service is requested and what it requires. A CarePlan is a request for one patient or group that describes how care is to be delivered; it can be the higher-level authorization that a Task refers to in Task.basedOn. This TA does not specify the use of the CarePlan. |
|
The code of a ServiceRequest. It states the type of service that is requested (TA Routing). |
|
|
The reference of a ServiceRequest to an ActivityDefinition or a PlanDefinition that describes how the service is requested and what it requires. |
|
|
The party that is to carry out the requested service. In the Multiple Fulfillers Pattern it remains unset until a candidate is selected. |
|
|
Standard dataset |
The set of information that a Fulfiller expects for a requested service, described in the Library of its definition, as a guideline for what the Placer makes available. A Request has one only where its definition describes it (see Resource Definitions → Request). |
|
Coordination Task |
A Task, conforming to the Coordination Task profile of this TA, that tracks one Fulfiller’s handling of one Request from start to finish. |
|
Cancellation Request Task |
A Task, conforming to the Cancellation Request Task profile of this TA, that asks for work that is already under way to be stopped. |
|
Authorization Cancellation Request Task |
A Task, conforming to the Authorization Cancellation Request Task profile of this TA, by which a Fulfiller asks the Placer to withdraw the Request itself. |
|
Bidding task |
A Coordination Task during the phase in which several candidates are invited to accept and, where the Placer wants it, to bid. It is not a separate kind of Task: the Coordination Task of the selected candidate continues after the bidding. |
|
Bid |
A Fulfiller's response to a bidding task that describes what it would offer, such as its availability, a more specific service, or the person who would perform it. |
|
Notified Pull |
Delivery via notification, followed by the Fulfiller retrieving the Task itself. |
|
The FHIR resource to which Task.owner refers: the service of a Fulfiller that is asked to carry out the work, as profiled by GF Addressing (NL-GF-HealthcareService). |
|
|
The FHIR resource to which Task.location refers: the place where the work is to be carried out, as profiled by GF Addressing (NL-GF-Location). |
|
|
Directory |
The register in which care providers publish their Organizations, HealthcareServices, Locations and Endpoints, so that others can find and address them: the Care Service Directory of GF Addressing (see Base Specifications). For the use of the directory in routing, see TA Routing. |
|
Type of work |
The type of use case that a Coordination Task belongs to, such as a referral, an order or a transfer of care, as a code that the use case defines. It is coarser than ServiceRequest.code, which states the type of service, and it differs from Task.code, which states what the owner is expected to do with the Request. A topic narrows on the type of work, and a Fulfiller learns it from the entry with type type-of-work in Task.input, also when it finds the Task by a search (see Type of work on the Task). |
Base Specifications
|
Specification |
Role |
|
COW IG (HL7 Clinical Order Workflows Implementation Guide), version 1.0.0-ballot (STU 1 Ballot 1, May 2025), package hl7.fhir.uv.cow, FHIR R4: hl7.org/fhir/uv/cow/2025May |
Base resource and workflow model. |
|
FHIR R4 (v4.0.1) |
Base standard for resources, interactions and search: hl7.org/fhir/R4. |
|
FHIR Extensions Pack, version 5.3.0, package hl7.fhir.uv.extensions.r4 |
The extension cqf-fhirQueryPattern, for the searches of a dataset (see Retrieving the resources of a dataset). |
|
TA Notifications, version 0.9 |
Base notification mechanism. |
|
TA Routing: Twiin Technical Agreement Routering ("Defining and publishing types of requests for routing requests between care providers"), version 1.3 (trial); a copy is published in the Netherlands Generic Functions IG, package fhir.nl.gf, version 0.3.0: http://nuts-foundation.github.io/nl-generic-functions-ig/routing.html |
Conformance target: internal routing of a Request once received. |
|
GF Addressing: Care Service Directory Implementation Guide (generieke functie Adressering), version 1.0.0, package nl.generiekefuncties.csd: minvws.github.io/generiekefuncties-docs |
Conformance target: registration and discovery of HealthcareService and Location, and their profiles NL-GF-HealthcareService and NL-GF-Location. In scope independently of TA Routing. |
|
TA I&A (forthcoming; no canonical URL available; may also be named TA I&A&A) |
Outside the scope of this TA; covers identification, authentication, authorization. |
|
TA Pull (forthcoming) |
Outside the scope of this TA; covers the retrieval that follows a notification, to which TA Notifications refers. |
|
Evidence for design choices (e.g., Task at Placer); not a base specification. |
|
|
Evidence for design choices (e.g., Multiple Fulfillers); not a base specification. |
Relationship to COW IG
COW IG was chosen as the base resource and workflow model for four reasons: it is generic enough to cover order, referral, and transfer workflows alike, rather than one at a time; complete enough that this TA needs no invented extension to address the core problem; pitched at the right level of detail to be profiled rather than rebuilt; and an international standard, keeping this TA aligned with an ecosystem wider than the Netherlands alone.
COW IG cannot serve as a technical agreement on its own. Its generality is deliberate: it leaves open many of the choices two systems must agree on to actually interoperate, and implementers left free to make those choices differently produce systems that are each individually COW-conformant yet unable to exchange anything with one another.
This TA is a profile of COW IG, not an extension of it. It makes binding choices among the options COW IG already permits — which hosting pattern applies, which values Task.code takes, how cancellation is realized — so that independently built systems converge on one behavior. It does not add resource types, elements, or mechanisms beyond what COW IG itself defines, apart from a code system with nine codes: request-fulfillment for Task.code, selected, awaiting-information and visit-scheduled for Task.businessStatus, not-selected for Task.statusReason, and type-of-work, available-resource, available-query and information-request for Task.input (see Codes of this TA), and the use of the HL7 extension cqf-fhirQueryPattern to describe a standard dataset (see Retrieving the resources of a dataset). Where this TA is silent, COW IG's own guidance applies unmodified.
This TA refers to COW IG version 1.0.0-ballot. A later version of COW IG applies only once a later version of this TA refers to it.
Design Choices
This section states, for each major choice this TA makes within COW IG's model, why it was made this way rather than left to individual implementers.
Task at Placer, not Task at Fulfiller
COW IG names two patterns for where the Coordination Task is hosted. This TA fixes it at the Placer. TA NP's own persistent, status-bearing resource (the Workflow Task) is already hosted at the Sending System — the Placer, in COW IG's terms — and eOverdracht's Task is likewise hosted at the bronhouder (the source holder), for the same reason its own specification gives: keeping data at the source. Both existing agreements, developed independently of each other and of COW IG, already converge on this hosting choice.
The Multiple Fulfillers Pattern is adopted, not only the simpler single-performer case
Some use cases need to offer one patient to several candidate organizations in parallel, for example a transfer of care. A specification that covered only a single performer would leave those use cases out, so this TA adopts the Multiple Fulfillers Pattern as COW IG describes it.
The pattern has two further uses:
-
Bidding. Candidates can do more than accept: they can describe what they would offer, so that the Placer can compare them before one is selected (see Bidding).
-
Negotiation with one candidate. A genuine negotiation before a Request is finalized can be useful even with exactly one Fulfiller under consideration. Many Requests with a single Fulfiller need no negotiation at all (see Single Fulfiller Pattern).
Task.owner and Task.location resolve to HealthcareService and Location, not Organization
Notifications are addressed to the people who must act on them. An organization is too coarse for that. TA Routing allows several kinds of routing label, including (sub-)organizations, but specifies that Task.owner refers to the HealthcareService responsible for carrying out the Request. This TA follows TA Routing and allows only that type of owner, so that the Subscription filter, the notification endpoint and access control each work in one way. An organization or sub-organization that receives Tasks as a whole registers a HealthcareService for that purpose in GF Addressing:
-
Task.owner identifies the HealthcareService that is asked to carry out the work.
-
Task.location identifies the Location at which the work is to be carried out. A HealthcareService can be performed at several physical Locations, and a Placer can request care at a specific one. (TA Routing)
The Subscription follows the service, or the organization that provides it:
-
A Subscription is established per HealthcareService of the Fulfiller, or for all HealthcareServices that one organization provides, per topic and per base URL at which the Placer hosts its Coordination Tasks, and is held on the Placer's server. It has one notification endpoint: that of the service, as in TA Routing, or that of the organization.
-
This TA cannot assume that all services of a Fulfiller share one endpoint, so a Subscription per service is always possible. An organization with many services can instead hold one Subscription for all of them, notified at an endpoint of the organization (see Subscription).
-
TA Routing lets an ActivityDefinition carry an endpoint that takes precedence over the endpoint of the HealthcareService. This TA does not use it: a Subscription filters on Task.owner, and the definition is referred to from the Request, not from the Task, so a Subscription cannot select an endpoint per definition. A Fulfiller that needs a separate endpoint for some of its definitions registers a separate HealthcareService for them in GF Addressing.
-
Task.location plays no part in the Subscription, and the notification endpoint is that of the HealthcareService or of its organization, not of the Location.
Topics are defined per use case, not by this TA
TA Notifications places the definition of a topic in the use-case-specific technical agreement. This TA is the generic layer under several use cases, so it states the requirements that every topic meets, and each use case defines its own topics (see SubscriptionTopic). There are three reasons for topics per use case rather than one topic for all work:
-
Authorization of a notification covers at least its SubscriptionTopic (TA Notifications). Topics per use case allow a different basis for each type of work.
-
A topic per use case lets a candidate know the type of work it is invited for from the notification itself, before it has read anything.
-
TA Notifications foresees specialising a generic Task topic for a use case with a coded trigger condition.
Topics trigger on create and update, not create alone
eOverdracht notifies on every Task change without exception, and TA NP's own mechanisms for both dataset updates and cancellation are update-triggered, not creation events. A topic that only covered create could not be specified as a profile of either.
Task.groupIdentifier is not used to link Tasks to the same Request
TA NP and eOverdracht each attach their own meaning to this element, and those meanings are incompatible with each other, so this TA does not add a further use to it. Linking Tasks to a Request is also unnecessary: Task.focus is mandatory in the profile of this TA, so Coordination Tasks that compete for the same Request can already be recognized by their shared reference to it.
The notification is id-only
The Task is addressed to a single receiver, and for such a resource TA Notifications says that id-only should be used in preference to empty. Full-resource is not used, so that every access to a Task is a read that the Placer authenticates and checks at that moment, and the Placer knows when the Fulfiller has retrieved the Task. Full-resource would save the Fulfiller one read of the Task, but not of the Request or the Patient.
Actors
The obligations of each actor are listed in two groups. The first group follows from COW IG and is repeated here for completeness; this TA adds nothing to it. The second group is specified by this TA: a choice or an addition of this TA, which may build on another specification named in parentheses.
Placer
The Placer:
Follows from COW IG
-
SHALL create the Request, hosted on its own FHIR server, and is the only party that modifies the Request directly.
-
SHALL create a Coordination Task that refers to the Request for each Fulfiller it asks to carry it out (see Multiple Fulfillers Pattern).
-
MAY cancel the Coordination Task before the work has started, and SHALL use a Cancellation Request Task to stop work that has started (see Cancellation (Before in-progress) and Cancellation Request (After in-progress)).
-
SHALL, whenever a Coordination Task reaches an end status (completed, failed, rejected, cancelled or entered-in-error), decide what happens to the Request and update Request.status where required.
-
With several candidates, SHALL select one and cancel the Coordination Tasks of the others (see Multiple Fulfillers Pattern).
Follows from TA Notifications
-
SHALL have the FHIR base URL at which it hosts its Coordination Tasks registered in GF Addressing as an Endpoint of the Placer, with connectionType
hl7-fhir-rest, payloadTypeSubscriptionand a payloadMimeType withfhirVersion=4.0. That base URL MAY be registered for several Placers; a Subscription at that base URL then concerns the Coordination Tasks of each of them.
Specified by this TA
-
SHALL host the Coordination Task on its own FHIR server (COW IG allows either hosting pattern; see Design Choices).
-
SHALL make sure that, when a HealthcareService of a Fulfiller is onboarded, a Subscription is established for that service, or for the organization that provides it, and each topic under which it receives Tasks, at the base URL at which the Placer hosts its Coordination Tasks, by creating it out-of-band or, where the use case specifies in-band creation for the topic, by accepting it in-band (see Subscription). (TA Notifications)
-
SHALL NOT create a Coordination Task for a HealthcareService under a topic unless a Subscription for that service, or for the organization that provides it, and for that topic exists at the base URL at which it hosts that Task, with status active or error (see Subscription).
-
SHALL grant the Fulfiller access to the Coordination Task for which the Fulfiller is accountable, limited to the elements that the Fulfiller may change (see Resource Definitions → Coordination Task → Write access), and SHALL record the identification of the accountable organization when it creates the Task (see Coordination Task).
-
SHALL NOT create a Coordination Task for an owner identifier that does not resolve to exactly one HealthcareService, and SHALL NOT create or accept a Subscription whose filter does not resolve to exactly one HealthcareService or exactly one organization (see Coordination Task and Subscription).
-
SHALL act on the end of a Coordination Task as specified in Handling the End of a Coordination Task.
-
MAY invite bids by creating a bidding task for each candidate (see Bidding).
-
SHALL answer an Authorization Cancellation Request Task by setting its status to accepted or rejected (see Cancellation by the Fulfiller).
Fulfiller
The Fulfiller:
Follows from COW IG
-
SHALL update the Coordination Task on the server of the Placer to report the progress of the work.
-
MAY reject the Coordination Task, with a statusReason.
-
MAY set the Coordination Task to failed when it can no longer carry out the work (see Cancellation by the Fulfiller).
-
SHALL accept or reject a Cancellation Request Task.
-
MAY ask the Placer to cancel the Request itself (see Cancellation by the Fulfiller).
Specified by this TA
-
SHALL have every HealthcareService through which it receives Tasks under this TA registered in GF Addressing, with a notification endpoint for the service or, where it holds one Subscription for all its services, for the organization, and the Locations at which these services are performed. A service that is not registered cannot receive Tasks (see Coordination Task). (GF Addressing)
-
SHALL authenticate to the Placer on every read or write of the Coordination Task.
-
SHALL make its changes as an update (PUT or PATCH) on the Placer's server, changing only status, businessStatus, statusReason, executionPeriod, lastModified and output of the Coordination Task, and the entries with type information-request in its input, and making them version-aware (see Write access).
-
SHALL set the Coordination Task to cancelled after it has accepted a Cancellation Request Task (see After an accepted Cancellation Request).
-
SHOULD support the ActivityDefinitions and PlanDefinitions that its HealthcareService lists (see Routing by the Fulfiller).
-
MAY respond to a bidding task with a bid (see Bidding).
Resource Definitions
Profiles
Task and Subscription profiles
This TA uses the FHIR Task resource, a general-purpose resource for tracking a piece of work. A FHIR profile narrows a general resource for a specific purpose: it states which elements must be filled in, which values are allowed, and how elements are to be used. This TA uses three profiles of Task and one profile of Subscription. A Task that conforms to one of the Task profiles is named after that profile:
-
The Coordination Task follows one Fulfiller's handling of one Request, from the moment the Request is sent until the work ends. It refers to the Request, names the Fulfiller asked to carry it out, and carries the status of the work. The Placer and the Fulfiller both use it to see where the work stands.
-
The Cancellation Request Task is used by the Placer to ask the Fulfiller to stop work that has already started. It refers to the Coordination Task to be cancelled, and the Fulfiller answers by accepting or rejecting it.
-
The Authorization Cancellation Request Task is used by a Fulfiller to ask the Placer to withdraw the Request itself, because it finds the Request inappropriate or even dangerous. It refers to the Request, and the Placer answers by accepting or rejecting it.
-
The Subscription is used by the Fulfiller, through its HealthcareService, to be notified of changes to the Tasks it owns. It refers to the topic of a use case and filters on the HealthcareService. It builds on the Subscription profile of TA Notifications, which builds on that of the Subscriptions R5 Backport IG.
The Coordination Task and the Cancellation Request Task build on the profiles of the same names in COW IG, which define the minimum expectations for these Tasks. COW IG defines no profile for the Authorization Cancellation Request Task; it gives an example, and asks in its ballot whether it should become a separate profile. This TA adds further requirements, described in the sections below.
In addition, this TA uses a profile of ServiceRequest for the Request, which states the requirements of this TA on the ServiceRequest (see Request and Patient context and readability). COW IG defines no profile for the Request.
The formal definitions of these five profiles, of the CapabilityStatement of the Placer’s server, and of the code system and value sets of this TA are published in its implementation guide, package nl.twiin.fhir.r4.workflow, version 0.4.0-draft: https://fhir.twiin.nl/ig/workflow/0.4.0-draft/en/. The implementation guide also contains informative examples of the patterns and transactions of this TA. The implementation guide expresses the requirements of this TA and adds none of its own; where it and this TA differ, this TA applies. The rules that a profile cannot express are text of this TA only.
Summary of the profiles
The tables below summarize the five profiles. Elements that are not listed are not constrained by this TA. The column R4 gives the base definition in FHIR R4, and the column COW IG gives the profile of the same name in COW IG. Some entries leave a value to the use case, such as the type of work, the topic and the heartbeat interval (see Use-case agreements under TA Notifications).
Coordination Task
|
Element |
R4 |
COW IG |
This TA |
Written by |
|
server-assigned |
not constrained |
stable, opaque and unpredictable (see Identifiers of Tasks and Subscriptions) |
Placer |
|
|
0..* |
1.. (must support) |
1.. |
Placer |
|
|
1..1; 12 codes |
not constrained |
requested at creation; afterwards the R4 state machine and the meaning that COW IG gives to each status (see Status of the Coordination Task) |
Fulfiller; Placer for cancelled, before in-progress, and for entered-in-error |
|
|
0..1 CodeableConcept |
not constrained |
SHALL be populated when the status is rejected or failed, or when businessStatus is awaiting-information, and SHOULD be populated when the status is cancelled; when populated, statusReason.text SHOULD be populated, and SHALL be populated for awaiting-information; when the Placer cancels a non-selected candidate, statusReason SHALL carry the code not-selected from the code system of this TA (see Reason for cancelling a non-selected candidate); extensible binding to a value set of this TA that contains not-selected |
Fulfiller (reason for rejecting or failing, and the information it awaits); Placer (reason for cancelling) |
|
|
0..1 |
must support; example binding to the ValueSet of COW IG |
the Placer sets selected at selection; the Fulfiller MAY set a value to report progress (see Business status); extensible binding to a value set of this TA (see Codes of this TA) |
Placer (selected); Fulfiller |
|
|
1..1; required binding |
not constrained |
fixed to order, also for a bidding task (COW IG, Workflow State Overview) |
Placer |
|
|
0..1; example binding |
1.. (must support) |
1..; fulfill or request-fulfillment, bound with a required binding to the value set of this TA (see Codes of this TA and Recognizing the pattern that applies) |
Placer |
|
|
0..1; any resource |
1.. (must support); ServiceRequest only |
1..; refers to the Request, a ServiceRequest |
Placer |
|
|
0..1 |
not constrained |
not used to indicate that Coordination Tasks belong to the same Request |
Placer |
|
|
0..1; any resource |
not constrained |
set by the Placer at creation; refers to the Patient that ServiceRequest.subject refers to, by the id of that Patient, which is not a business identifier. Task.for.identifier MAY carry the same id and SHALL NOT carry a business identifier (see Patient context and readability). |
Placer |
|
|
0..1 Period |
not constrained |
start set when the work starts, end when it completes, fails or is cancelled after it started (see Write access) |
Fulfiller |
|
|
0..1 dateTime |
not constrained |
1..1; the time at which the Placer created the Task |
Placer |
|
|
0..1 dateTime |
not constrained |
the time of the last change, set by the party that makes the change (see Write access) |
Placer; Fulfiller |
|
|
0..1 |
not constrained |
1..1; identifies the Placer by Reference.identifier, carrying its URA (see Search parameters); a literal Reference.reference MAY be added alongside |
Placer |
|
|
0..1; includes HealthcareService |
not constrained |
1..1; Reference.type is HealthcareService; the resource is a HealthcareService as profiled by GF Addressing (NL-GF-HealthcareService), not merely an Organization; identifier from the AssignedId slice of that profile, with the identified Organization as assigner; a literal Reference.reference MAY be added alongside (GF Addressing) |
Placer |
|
|
0..1 |
not constrained |
the Placer SHOULD populate it, and the Fulfiller SHALL process it when present (see Routing by the Fulfiller); the Location profile of GF Addressing (NL-GF-Location), by Reference.identifier from its AssignedId slice |
Placer |
|
|
0..* |
not constrained |
the Fulfiller SHOULD populate it, and the Placer SHALL process it when present (see Handling the End of a Coordination Task); also used for a bid |
Fulfiller |
|
|
0..* |
not constrained |
exactly one entry with type type-of-work, carrying the type of work (see Type of work on the Task); the Fulfiller MAY add entries with type information-request (see Business status); the Placer states in further entries what it makes available, with type available-resource or available-query for data at the Placer, and MAY share other content (see Sharing additional content) |
Placer; Fulfiller (entries with type information-request) |
The Fulfiller may change only status, businessStatus, statusReason, executionPeriod, lastModified and output, and the entries with type information-request in input (see Write access).
Cancellation Request Task
|
Element |
R4 |
COW IG |
This TA |
Written by |
|
server-assigned |
not constrained |
stable, opaque and unpredictable (see Identifiers of Tasks and Subscriptions) |
Placer |
|
|
1..1 |
not constrained |
requested at creation; afterwards accepted or rejected, as an update by the Fulfiller; cancelled by the Placer while the status is requested; entered-in-error by the Placer if it was created by mistake |
Placer at creation; Fulfiller (accepted, rejected); Placer (cancelled, entered-in-error) |
|
|
0..1 |
not constrained |
the Fulfiller’s reason for rejecting; SHOULD be populated when the status is rejected; when populated, statusReason.text SHOULD be populated |
Fulfiller |
|
|
0..1 CodeableConcept |
not constrained |
the Placer’s reason for asking to stop the work; SHOULD be populated; when populated, reasonCode.text SHOULD be populated |
Placer |
|
|
0..1; example binding |
pattern abort |
fixed to abort |
Placer |
|
|
1..1; required binding |
not constrained |
fixed to order |
Placer |
|
|
0..1; any resource |
1.. ; a Request or the Coordination Task |
refers to the Coordination Task to be cancelled |
Placer |
|
|
0..1 |
not constrained |
1..1; identifies the Placer by Reference.identifier, carrying its URA (see Search parameters); a literal Reference.reference MAY be added alongside |
Placer |
|
|
0..1 |
not constrained |
1..1; the same HealthcareService as the Coordination Task, so that the Subscription filter on Task.owner (see Subscription) delivers it as well |
Placer |
|
|
0..* |
not constrained |
exactly one entry with type type-of-work, with the same value as the entry with type type-of-work on the Coordination Task to which Task.focus refers (see Type of work on the Task) |
Placer |
The Fulfiller may change only status and statusReason of a Cancellation Request Task.
Authorization Cancellation Request Task
|
Element |
R4 |
COW IG |
This TA |
Written by |
|
1..1 |
no profile; requested in the example |
requested at creation; afterwards accepted or rejected by the Placer |
Fulfiller at creation; Placer afterwards |
|
|
0..1 |
no profile |
the Placer’s reason for rejecting; SHOULD be populated when the status is rejected; when populated, statusReason.text SHOULD be populated |
Placer |
|
|
0..1 CodeableConcept |
no profile |
1..1; the Fulfiller’s reason for asking to withdraw the Request; reasonCode.text SHOULD be populated |
Fulfiller |
|
|
0..1; example binding |
no profile; abort in the example |
fixed to abort |
Fulfiller |
|
|
1..1; required binding |
no profile; proposal in the example |
fixed to proposal |
Fulfiller |
|
|
0..1; any resource |
no profile; the Request in the example |
1..1; refers to the Request |
Fulfiller |
|
|
0..1 |
no profile |
1..1; the Fulfiller, by Reference.identifier, carrying its URA (see Search parameters); FHIR R4 does not allow Task.requester to refer to a HealthcareService |
Fulfiller |
|
|
0..1 |
no profile |
1..1; the Placer, by Reference.identifier, carrying its URA (see Search parameters) |
Fulfiller |
The Fulfiller sets all elements at creation and does not change them afterwards. The Placer changes only status and statusReason.
ServiceRequest
|
Element |
R4 |
COW IG |
This TA |
Written by |
|
1..1; Patient, Group, Location or Device |
no profile |
1..1; a Patient only; not left out or masked, for example with the extension data-absent-reason; the reference carries the id of the Patient, which is not a business identifier (see Patient context and readability) |
Placer |
|
|
0..*; ActivityDefinition or PlanDefinition |
no profile |
0..*; MAY refer to the ActivityDefinition or PlanDefinition of the requested service; absent where the Request follows no predefined definition (see Request) |
Placer |
|
|
0..1 |
no profile |
1..1; where instantiatesCanonical refers to an ActivityDefinition that has a code, that code (see Request) |
Placer |
|
|
0..1; required binding to RequestPriority |
no profile |
the Placer SHOULD populate it, and the Fulfiller SHALL process it when present, for example to triage the Request; Task.priority is not used |
Placer |
|
|
0..* |
no profile |
unset in the Multiple Fulfillers Pattern until a candidate is selected (see Multiple Fulfillers Pattern) |
Placer |
|
|
note, patientInstruction, reasonCode and other elements with content |
0..* |
no profile |
until a candidate is selected, no data that directly identifies the patient, unless the use case makes the Patient resource readable before selection (see Patient context and readability) |
|
Subscription
|
Element |
R4 |
Backport IG 1.1.0 |
This TA |
Written by |
|
server-assigned |
not constrained |
stable, opaque and unpredictable (see Identifiers of Tasks and Subscriptions) |
Placer |
|
|
1..1 string |
canonical URL of a SubscriptionTopic |
the canonical URL of a topic that a use case under this TA defines |
Placer (out-of-band); Fulfiller (in-band) |
|
|
— |
0..* |
1..1; of the form o |
Placer (out-of-band); Fulfiller (in-band) |
|
|
1..1 |
not constrained |
fixed to |
Placer (out-of-band); Fulfiller (in-band) |
|
|
0..1 |
not constrained |
1..1; begins with the address of an Endpoint with payloadType Notification in |
Placer (out-of-band); Fulfiller (in-band) |
|
|
0..1 |
not constrained |
1..1; application/fhir+json or application/fhir+xml (TA Notifications) |
Placer (out-of-band); Fulfiller (in-band); the Fulfiller MAY change it through Updating a Subscription |
|
|
— |
0..1 |
1..1; fixed to id-only |
Placer (out-of-band); Fulfiller (in-band) |
|
|
— |
0..1 |
1..1; the interval that the use case states for the topic |
Placer (out-of-band); Fulfiller (in-band) |
Rules that a profile cannot express
These rules remain text of this TA, or are declared in the CapabilityStatement of the Placer's server:
-
that an owner identifier resolves to exactly one HealthcareService;
-
that Task.owner and Task.location refer to a HealthcareService and a Location as profiled by GF Addressing (NL-GF-HealthcareService, NL-GF-Location), by the identifier from their AssignedId slice;
-
that a Coordination Task is created only for a HealthcareService and topic with a Subscription, at the base URL at which the Task is hosted, with status active or error;
-
the permitted status changes and who makes them;
-
that updates by the Fulfiller are version-aware;
-
that the Placer’s server rejects a move to in-progress while Task.code is request-fulfillment;
-
that exactly one candidate is selected, and only one whose Coordination Task has the status accepted;
-
that a Cancellation Request Task is created only when the Coordination Task is in-progress;
-
that Task.owner of a Cancellation Request Task is the same HealthcareService as Task.owner of the Coordination Task it refers to;
-
that the entry with type type-of-work of a Cancellation Request Task has the same value as that of the Coordination Task it refers to;
-
that an Authorization Cancellation Request Task is created only by a Fulfiller that has a Coordination Task with Task.code fulfill for the same Request, whose status is not cancelled or entered-in-error;
-
that ServiceRequest.code carries the code of the ActivityDefinition to which ServiceRequest.instantiatesCanonical refers, where that ActivityDefinition has a code;
-
that ServiceRequest.performer remains unset in the Multiple Fulfillers Pattern until a candidate is selected;
-
that the filter of a Subscription identifies exactly one HealthcareService or exactly one organization;
-
that channel.endpoint of a Subscription begins with the address of a notification endpoint of that HealthcareService or organization;
-
that there is one Subscription per HealthcareService, topic and base URL, or one per organization, topic and base URL, and not both for the same organization;
-
that Task.owner.identifier.assigner identifies the organization that provides the HealthcareService;
-
that the patient identifier in ServiceRequest.subject and Task.for is the id of the Patient resource and not a business identifier;
-
that the Request contains no data that directly identifies the patient while a candidate is under consideration, in the Multiple Fulfillers Pattern, unless the use case makes the Patient resource readable before selection;
Coordination Task
The elements of the Coordination Task are restricted as in the table in Summary of the profiles. The following rules apply in addition.
Follows from COW IG
-
A Coordination Task is created by the Placer for the Fulfiller that is to carry out the Request (see Task Creation).
Specified by this TA
-
The Coordination Task is hosted on the Placer's own FHIR server. How the Placer creates it there is not specified by this TA (COW IG allows either hosting pattern; see Design Choices).
-
The Placer SHALL NOT create a Coordination Task for an owner identifier that does not resolve to exactly one HealthcareService in GF Addressing, in the replica of the directory that the Placer uses to select the Fulfiller (see the assumption about GF Addressing under Search parameters). Nor SHALL it create a Coordination Task whose Task.owner.identifier.assigner identifies another organization than the one that provides the HealthcareService, so that a Subscription for that organization delivers the Task.
-
When the Placer creates a Coordination Task, it records the identification of the organization that is accountable for the Task: the organization that provides the HealthcareService it selected as Task.owner. The Placer takes this identification from the directory data at the moment of selection and keeps the record internally; it is not an element of the Task. The Placer applies the same record to the Cancellation Request Task of that Coordination Task. When it decides whether a Fulfiller may read or write a Task, the Placer uses this record and the authentication of the Fulfiller, and SHALL NOT use directory data. How the Fulfiller authenticates is the subject of TA I&A.
Write access
Follows from FHIR R4
-
An update (PUT) replaces the whole resource.
Specified by this TA
-
The Fulfiller SHALL authenticate on every read or write; access is verified per interaction.
-
The Placer SHALL grant the Fulfiller access only to the Coordination Tasks for which the Fulfiller is accountable, and within those only to the elements that the Fulfiller may change (see below). The Fulfiller is accountable for a Coordination Task when the identity of the zorgaanbieder in its authentication is the identity that the Placer recorded for that Task when it created it. The identity of a GTK through which the Fulfiller connects does not suffice, since a GTK may act on behalf of several zorgaanbieders. The Placer SHALL allow the Fulfiller to read every element of its own Coordination Task.
-
The Fulfiller MAY change only the elements marked Fulfiller in the column Written by of the table Coordination Task in Summary of the profiles: status, businessStatus, statusReason, executionPeriod, lastModified and output. In Task.input, the Fulfiller MAY add and remove entries with type information-request, and SHALL NOT change any other entry. All other elements are set by the Placer and SHALL NOT be changed by the Fulfiller. The Placer sets focus, requester, owner and authoredOn once, at creation.
-
The Fulfiller SHOULD set Task.executionPeriod.start when it moves Task.status to in-progress, and Task.executionPeriod.end when it moves Task.status from in-progress to completed, failed or cancelled.
-
A party that changes the Coordination Task MAY set Task.lastModified to the time of that change.
-
Within the writable elements, two values are reserved for the Placer: the code not-selected in Task.statusReason and the code selected in Task.businessStatus (see Reason for cancelling a non-selected candidate and Business status). The type information-request in Task.input is reserved for the Fulfiller.
-
The Fulfiller MAY set Task.businessStatus to report progress within a status (see Business status). The Placer sets selected at selection; a later update by the Fulfiller replaces it, and the Placer recognizes the selected candidate by Task.code fulfill.
-
The Placer's server SHALL check every update by the Fulfiller and reject it if it changes an element other than the ones named above, or changes an element to a reserved value. Sending a reserved value that the Placer has set, unchanged, is not a change.
-
A Fulfiller that uses a full update (PUT) sends the Task with all other elements unchanged.
-
The Fulfiller MAY create an Authorization Cancellation Request Task on the Placer's server. The Placer's server SHALL accept the create only when the identification in the authentication of the Fulfiller equals the identification recorded for a Coordination Task whose Task.focus refers to the same Request, whose Task.code is fulfill, and whose status is not cancelled or entered-in-error, and SHALL check the elements against the table Authorization Cancellation Request Task in Summary of the profiles. The Placer records this identification for the Authorization Cancellation Request Task as well. The Placer SHALL allow the Fulfiller to read the Authorization Cancellation Request Tasks it has created. The Fulfiller SHALL NOT change them after creation.
Concurrent writes
The first three rules below use mechanisms of the RESTful API of FHIR R4 for managing resource contention and for declaring capabilities. Those mechanisms are defined there, and this TA requires their use between the Placer and the Fulfiller. The last rule is an addition of this TA and is not defined by FHIR.
-
An update by the Fulfiller SHALL be version-aware. The Fulfiller reads the Coordination Task, takes its version from the ETag, and sends that version in the If-Match header of its update. The Placer's server SHALL reject an update on a version that is no longer current with 412 Precondition Failed. The Fulfiller then reads the Task again and decides again. (FHIR R4, Managing Resource Contention and update)
-
The Fulfiller MAY change the Coordination Task with PUT or with PATCH. A PATCH document is a JSON Patch (application/json-patch+json) and is version-aware in the same way. (FHIR R4, PATCH) The Placer's server SHALL support JSON Patch.
-
The Placer's server SHALL declare the versioning level versioned-update in its CapabilityStatement (see Placer server capabilities). (FHIR R4, CapabilityStatement)
-
The Placer bases its own updates of a Coordination Task on the current version in the same way, so that it does not overwrite an update by the Fulfiller.
Status of the Coordination Task
Follows from COW IG and FHIR R4
-
The statuses are the codes of the TaskStatus code system of FHIR R4, and the transitions follow the typical state machine of FHIR R4 (see the figure below). The diagram has no move from in-progress to cancelled. (FHIR R4)
-
The workflow meaning of Task.status comes from the Workflow State Overview of COW IG, and the rules for stopping work that has started from the cancellation rules of COW IG. To stop work that has started, the Placer creates a Cancellation Request Task. (COW IG)
Specified by this TA
-
This TA adds no states.
-
The Placer sets entered-in-error only when the Coordination Task itself was created by mistake, for example for the wrong Request or the wrong HealthcareService, and SHALL NOT use it to stop work on a Coordination Task that was created correctly; once that work has started, it uses a Cancellation Request Task (see Cancellation Request (After in-progress)). It MAY set entered-in-error at any status, also after in-progress, since a Task created by mistake gives no basis for the work.
-
The statuses draft, ready and on-hold are not used by this TA.
-
A Fulfiller moves Task.status to accepted before it moves it to in-progress, in every pattern. This TA adds no direct move from requested or received to in-progress.
-
What accepted means depends on Task.code (FHIR R4, TaskStatus). With Task.code fulfill, the Fulfiller will carry out the work. With Task.code request-fulfillment, the candidate states that it can carry out work of this type and would do so if selected; this does not imply selection, and the candidate may not start the work (see Recognizing the pattern that applies and Bidding). When the Placer selects the candidate and sets Task.code to fulfill, the status stays accepted, and the acceptance becomes the agreement to carry out the work (COW IG, Workflow State Overview).
-
Where this TA uses a transition that the diagram does not show, this is stated.
-
A Fulfiller that has accepted, and finds that it can no longer carry out the work, MAY move Task.status from accepted to failed, with statusReason (COW IG, Fulfiller Unable to Perform). The typical state machine of FHIR R4 does not show this move, but FHIR R4 allows workflows to support additional transitions (FHIR R4, Task state machine). The Fulfiller does not set cancelled instead: under this TA cancelled always means that the Placer withdrew the Task, directly before in-progress or through an accepted Cancellation Request Task after that (FHIR R4, Task, The Cancelled state).
-
The move to in-progress has consequences: from then on the Placer cannot cancel the Coordination Task, and uses a Cancellation Request Task instead (see Cancellation Request (After in-progress)), and the Fulfiller sets Task.executionPeriod.start (see Write access). FHIR R4 defines in-progress as a task that has been started but is not yet complete, without stating when work counts as started (FHIR R4, TaskStatus). Each use case SHALL state when the work counts as started for its type of work (see Use-case agreements under TA Notifications). The Fulfiller SHALL NOT move the Coordination Task to in-progress before that point.
|
Status |
Meaning in this TA |
Reached from |
Set by |
Follow-up for the Request |
|
requested |
The Placer has sent the Task. This is the initial status. |
Initial status |
Placer |
None. |
|
received |
The Fulfiller has read the Task but has not yet decided. |
requested |
Fulfiller |
None. |
|
accepted |
The Fulfiller has agreed to do what Task.code asks of it, and has not yet started the work. |
requested, received |
Fulfiller |
None, until a candidate is selected. |
|
rejected |
The Fulfiller declines, giving Task.statusReason. |
requested, received |
Fulfiller |
|
|
in-progress |
The Fulfiller has started the work, as the use case states it. |
accepted |
Fulfiller |
None. |
|
failed |
The Fulfiller accepted or started the work but could not complete it. |
accepted, in-progress |
Fulfiller |
|
|
completed |
The Fulfiller has finished its work. |
in-progress |
Fulfiller |
|
|
cancelled |
The Coordination Task is withdrawn. |
requested, received, accepted, in-progress |
Placer, before in-progress; Fulfiller, from in-progress after accepting a Cancellation Request Task |
|
|
entered-in-error |
The Task was created by mistake. |
Not shown in the diagram of FHIR R4 |
Placer |
Business status
Task.status is deliberately coarse: it follows the state machine of FHIR R4 and says only where the work stands in that general lifecycle. Task.businessStatus lets the parties say more about where the work stands within one of those statuses, in terms that make sense for the care process. It never replaces Task.status and does not change the permitted status changes.
The COW IG suggest these businessStatus codes:
|
businessStatus |
Meaning |
Used with Task.status |
Set by |
Source |
|---|---|---|---|---|
|
selected |
The Placer has selected the owner of this Task (see Multiple Fulfillers Pattern). |
accepted |
Placer |
this TA |
|
awaiting-information |
The Fulfiller needs more information from the Placer to continue or to decide. |
received, accepted, in-progress |
Fulfiller |
COW IG (example code) |
|
visit-scheduled |
A visit with the patient is scheduled. |
accepted, in-progress |
Fulfiller |
COW IG (example code) |
The only value that this TA makes mandatory is selected, which the Placer sets at selection in the Multiple Fulfillers Pattern (see Multiple Fulfillers Pattern). It is reserved for the Placer, and a later update by the Fulfiller replaces it.
All other values are optional. The Fulfiller MAY set a value to report progress, from the values that the use case agrees. A use case MAY use awaiting-information and visit-scheduled from the code system of this TA, and other values from the example value set Business Status of COW IG (http://hl7.org/fhir/uv/cow/ValueSet/business-status) with the code system of COW IG. Besides the two codes of this TA, that value set contains specimen-collected, awaiting-interpretation and preliminary-outcome.
A use case MAY also define values of its own, for a meaning that the values of this TA do not cover.
A Fulfiller that awaits information sets awaiting-information and states what it needs in Task.statusReason.text. Where that is not enough, for example for a structured request, it adds an entry with type information-request to Task.input, with the request in the entry itself, as the use case defines. Where that is not enough, for example for a structured request, it adds an entry to Task.output with the request in the entry itself, as the use case defines (see Sharing additional content). Placer provides the information as the use case defines, for example in Task.input (see Sharing additional content), and the Fulfiller then sets another value or removes it, and removes Task.statusReason.
Cancellation Request Task
The elements of the Cancellation Request Task are restricted as in the table in Summary of the profiles. The following rules apply in addition.
Follows from COW IG
-
A Cancellation Request Task SHALL be created by the Placer when Task.status has already reached in-progress on the Coordination Task it targets.
Specified by this TA
-
The Cancellation Request Task is created on the Placer's own FHIR server.
-
The Coordination Task is in-progress when a Cancellation Request Task is used, so the Placer SHALL NOT set it to cancelled itself: COW IG treats the absence of a move from in-progress to cancelled in the diagram of FHIR R4 as a requirement, which the Cancellation Request Task exists to meet (COW IG, Placer Initiated Cancellations). When the Fulfiller accepts the Cancellation Request Task, it sets the Coordination Task to cancelled (see After an accepted Cancellation Request).
-
The Placer MAY withdraw a Cancellation Request Task that the Fulfiller has not yet answered, by setting its status to cancelled; the work on the Coordination Task then continues. The Placer sets a Cancellation Request Task that it created by mistake to entered-in-error. A Cancellation Request Task takes no other statuses than requested, accepted, rejected, cancelled and entered-in-error.
Request and patient
Request
The Request is the ServiceRequest that states what is being asked for; every Coordination Task refers to one. The requested service is identified by ServiceRequest.code. Where a definition of the service exists, the Request can refer to it, and the definition can describe a standard dataset: the information a Fulfiller expects in order to carry the Request out, as a guideline for what the Placer makes available. A Request needs neither a definition nor a standard dataset.
Follows from COW IG and TA Routing
-
A Request resource SHALL exist for every Coordination Task. (COW IG)
-
Request.status is changed only by the Placer, as the party that created the Request. (COW IG)
-
ServiceRequest.instantiatesCanonical MAY additionally reference an ActivityDefinition or a PlanDefinition, where a bare code is not precise enough. A PlanDefinition is a composite of ActivityDefinitions; the same rules apply to both. (TA Routing)
-
Where a directory defines an ActivityDefinition or PlanDefinition for a service, a receiving server MAY decline a Request that does not reference it via instantiatesCanonical, or that does not adhere to its requirements. (TA Routing)
-
The Request is a ServiceRequest: the Coordination Task profile of COW IG restricts Task.focus to ServiceRequest. (COW IG)
Specified by this TA
-
Where ServiceRequest.instantiatesCanonical refers to an ActivityDefinition that has a code, ServiceRequest.code SHALL carry that code, as applying an ActivityDefinition maps ActivityDefinition.code to ServiceRequest.code (FHIR R4, ActivityDefinition, Applying an ActivityDefinition). A PlanDefinition has no such code; ServiceRequest.code then states the requested service as for any Request.
-
ServiceRequest.performer SHALL remain unset in the Multiple Fulfillers Pattern until a candidate is selected (see Multiple Fulfillers Pattern).
-
ServiceRequest.instantiatesCanonical MAY refer to the ActivityDefinition or PlanDefinition of the requested service, which describes the standard dataset where it has one (see Retrieving the resources of a dataset). A Request that refers to no definition is valid under this TA.
-
ServiceRequest.code SHALL be populated, so that the requested service can be routed also when ServiceRequest.instantiatesCanonical is absent (see Routing by the Fulfiller).
-
Unless the use case makes the Patient resource readable before selection, the Placer keeps data that directly identifies the patient out of the Request until a candidate is selected (see Patient context and readability).
Request types other than ServiceRequest
The narrative of COW IG mentions request types other than ServiceRequest: DeviceRequest, MedicationRequest, NutritionOrder, SupplyRequest and VisionPrescription. Its Coordination Task profile (version 1.0.0-ballot), however, restricts Task.focus to ServiceRequest. This TA builds on that profile, so the Request is a ServiceRequest, and the rules of this TA on specific elements are written for ServiceRequest. Should a later version of COW IG allow other request types, a later version of this TA can reconsider this.
Retrieving the resources of a dataset
A Request has a standard dataset only where the definition in ServiceRequest.instantiatesCanonical describes one (see Request).
The ActivityDefinition or PlanDefinition of the Request refers in its element library to a Library. The dataRequirement of that Library describes the standard dataset, one DataRequirement per part of the dataset. A definition without a library, or a Library without dataRequirement, describes no standard dataset. Each DataRequirement carries one or more searches in the extension cqf-fhirQueryPattern (FHIR Extensions Pack). A search is relative to the FHIR base of the Placer, and the token {{context.patientId}} stands for the id of the Patient that Task.for refers to.
A standard dataset is a guideline, not a requirement: it states what a Fulfiller expects, and neither obliges the Placer to make all of it available nor limits the Placer to it. The Placer states for each Request what it makes available, in entries of Task.input with type available-resource or available-query (see Sharing additional content), and MAY use the searches of the dataset for this. The Fulfiller retrieves what these entries refer to. A Fulfiller that misses information it expects MAY ask for it (see Business status). Where ServiceRequest.instantiatesCanonical is absent, or the definition describes no standard dataset, the Placer states in the same way what it makes available, if anything. A request may need no data at all.
Where ServiceRequest.instantiatesCanonical is absent, or the definition describes no standard dataset, the Request has none. The Placer then shares the data the Fulfiller needs, if any, in Task.input (see Sharing additional content). A request may need no data at all.
Depends on a decision outside this TA. Which resources belong to a standard dataset is defined by the owner of that dataset, in its information standard, not by this TA. The owner also publishes the Library that describes it. This TA only specifies how the definition of a Request refers to that Library, and how the searches are expressed.
Sharing additional content
The Placer shares the content that the Fulfiller needs to carry out the work in Task.input, including what it makes available of a standard dataset (see Retrieving the resources of a dataset). Each entry of Task.input has a type, which says what the content is, and a value, which is the content or a reference to it.
Specified by this TA
-
Content that relates to why the Request was authorized, or what is authorized, belongs to the Request (Request.supportingInfo). Content that relates to how the Request is to be fulfilled belongs to the Task (Task.input). This is a choice of this TA, in line with guidance in the continuous build of COW IG, which the ballot version does not contain.
-
The Placer sets and changes Task.input, apart from entries with type information-request, which only the Fulfiller adds (see Business status and Write access).
-
Before selection, Task.input carries the type of work and entries that contain no business identifier of the patient. These entries carry their content in the entry itself, since a candidate may not read resources at the Placer other than the Request before selection, unless the use case makes the Patient resource readable before selection. Entries with type available-resource or available-query are added when the Placer selects the candidate, or at creation in the Single Fulfiller Pattern or where the use case makes the Patient resource readable before selection (see Patient context and readability). Unless the use case makes the Patient resource readable before selection, data that directly identifies the patient is not shared in the Request or in Task.input before selection. The Placer shares it when it selects the candidate, in the Patient resource or in an entry added at that moment.
-
A change of Task.input is a change of the Coordination Task, and reaches the Fulfiller through the notification of that change, in the same way as any other update by the Placer.
-
The Placer SHALL share data that it holds in entries with one of these types, from the code system of this TA (see Codes of this TA):
-
available-resource, with in valueReference a reference to one resource at the Placer;
-
available-query, with in valueString a search relative to the FHIR base of the Placer.
-
-
These correspond to read-available-resource and query-available-resources of TA NP.
-
Other content, such as instructions, MAY be shared in entries with a type that the care domain defines. What such an entry contains is not defined by this TA. An entry with shared content SHALL NOT use the type type-of-work.
-
The Fulfiller MAY add content during the workflow, not only at its end, by adding entries to Task.output of its Coordination Task, as a Task Update by Fulfiller (see Transactions). Each entry has a type that the care domain defines and carries its content in the entry itself. A bid and the result of the work are entries of the same kind (see Bidding and Handling the End of a Coordination Task).
Patient context and readability
Requirements of COW IG and FHIR R4
-
The Coordination Task refers to the Request in Task.focus, which is mandatory. (COW IG)
-
Task.for is not constrained by COW IG. In FHIR R4 it is optional and can refer to the Patient; Task.for.identifier can carry an identifier of the patient. (COW IG, FHIR R4)
-
Every ServiceRequest has a subject: ServiceRequest.subject is mandatory. (FHIR R4)
Functional requirement
During the preliminary phases of the workflow, a candidate Fulfiller can read the Request, because it needs to know what is actually asked in order to decide whether to accept, to bid, and to route the Request internally (see Routing by the Fulfiller). As ServiceRequest.subject is mandatory, this means that the candidate knows the identifier of the patient before it is selected. This identifier is not a business identifier, and, unless the use case states otherwise, the candidate cannot read the Patient resource. The Request is readable by every candidate, so, unless the use case makes the Patient resource readable before selection, the Placer keeps data that directly identifies the patient out of the Request until a candidate is selected.
Solution, specified by this TA
-
ServiceRequest.subject SHALL reference a Patient. A Group, a Location or a Device is not supported, and neither is leaving out or masking the subject, for example with the extension data-absent-reason.
-
The identifier of the patient that the Request and the Task carry SHALL NOT be a business identifier, such as the BSN. It is the id of the Patient resource at the Placer, and SHALL meet the requirements of Identifiers of Tasks and Subscriptions. Business identifiers of the patient are carried in Patient.identifier of the Patient resource only.
-
The Placer SHALL give a candidate read access to the Request from the creation of its Coordination Task. Read access to the Request does not extend to the resources that it refers to. The Placer SHALL NOT give a candidate read access to the Patient resource until Task.code of its Coordination Task is fulfill, unless the use case states that the Patient resource is readable to candidates before selection, and on what basis (see Use-case agreements under TA Notifications). The Placer then gives each candidate read access to the Patient resource from the creation of its Coordination Task. Access to other resources that the Request refers to is not implied and is granted separately by the Placer.
-
Until a candidate is selected, and unless the use case makes the Patient resource readable before selection, the Placer SHALL NOT include data that directly identifies the patient in the Request, such as a name, an address, contact details or a business identifier. This also applies to free text, for example in Request.note, Request.patientInstruction and Request.reasonCode.text, and to any other element of the Request that carries content itself. Such data is carried in the Patient resource, or shared when the Placer selects the candidate (see Sharing additional content). The Request is shared by all candidates, so the rule applies to the Request as a whole as long as any candidate is under consideration. The Placer MAY add such data to the Request after it has cancelled the Coordination Tasks of the other candidates and withdrawn their read access. When the Placer cancels the Coordination Task of the selected Fulfiller and solicits again (see Cancellation (Before in-progress)), it first removes such data from the Request. In the Single Fulfiller Pattern, where the Fulfiller is selected from creation, this rule does not apply.
-
The Placer SHALL withdraw the read access of a Fulfiller to the Request and the Patient resource when it cancels the Coordination Task of that Fulfiller, before or after selection, unless the Fulfiller has another Coordination Task for the same Request through which it may read them.
-
Task.for SHALL be set at creation and SHALL refer by Reference.reference to the Patient that ServiceRequest.subject refers to. Task.for.identifier MAY carry the same opaque patient identifier and SHALL NOT carry a business identifier. Business identifiers of the patient, including those that the law requires to accompany personal data, are carried in Patient.identifier of the Patient resource to which Task.for refers.
-
Before selection, the Coordination Task carries the identifier and id of the Task, its status and code, the reference to the Request in Task.focus, the reference to the Patient in Task.for, the Placer in Task.requester, the HealthcareService of the candidate in Task.owner, Task.authoredOn, the Location of the service in Task.location, the type of work in Task.input, and the further entries of Task.input that are allowed before selection. These identify the parties, the place and the kind of work, and the patient only by an opaque identifier. The ids are opaque (see Identifiers of Tasks and Subscriptions), so the references in Task.focus and Task.for reveal nothing in themselves: the candidate learns the content of the Request only by reading it, and cannot derive a business identifier of the patient from the patient id. Task.location refers to a Location registered in GF Addressing, not to the address of the patient. What a candidate learns is that the Placer asks for this type of work, for a patient known to it only by an opaque identifier, at this place and time. Where few patients receive a type of work at a place, this, together with the content of the Request, can narrow the patient down, even though the Request contains no directly identifying data; unless the use case makes it readable before selection, the candidate may not read the Patient resource until it is selected.
-
When the Placer selects a candidate, it sets Task.code to fulfill in the same update in which it sets Task.businessStatus to selected. From then on the candidate may read the Patient resource, including Patient.identifier. Read access follows Task.code, not Task.businessStatus, which the Fulfiller may later replace (see Write access).
-
In the Single Fulfiller Pattern the Fulfiller is selected from the creation of the Task, so the Fulfiller may read the Request and the Patient resource from the start.
The patient is referred to in these places:
|
Where |
The patient is referred to by |
Status in this TA |
|
ServiceRequest.subject |
a reference to the Patient (opaque id); mandatory |
SHALL be a Patient; readable by a candidate from the creation of the Task |
|
Task.for |
same opaque id |
set at creation |
|
Task.for.identifier |
same opaque id |
MAY be populated; SHALL NOT be a business identifier |
|
Patient.identifier |
identifiers of the patient |
readable from selection, or from creation in the Single Fulfiller Pattern or where the use case makes the Patient resource readable before selection |
What a candidate may read in each phase:
|
Phase |
Task.status of the candidate |
Request |
Patient resource (name, address) |
|
Invited |
requested, received |
May read. |
May not read, unless the use case identifies the patient before selection. |
|
Accepted, not yet selected |
accepted |
May read. |
May not read, unless the use case identifies the patient before selection. |
|
Selected, work started |
accepted (selected), in-progress |
May read. |
May read. |
|
Not selected |
cancelled |
May not read. |
May not read. |
Routing by the Fulfiller
A notification tells the Fulfiller that a Coordination Task it owns has been created or changed. The topic of the Subscription and the entry with type type-of-work in Task.input indicate the type of work, also before the Fulfiller is selected, but not the details of the work, or where it is to be carried out (see Type of work on the Task). The Fulfiller finds this out after reading the Task, from the Request that Task.focus refers to and from Task.location:
Follows from TA Routing
-
ServiceRequest.code states the type of service that is requested.
-
ServiceRequest.instantiatesCanonical, where present, refers to an ActivityDefinition or a PlanDefinition that describes how the service is requested and what it requires.
-
The HealthcareService that owns the Task publishes the services it supports as codes in HealthcareService.type, and optionally the ActivityDefinitions and PlanDefinitions that describe them, in the extension supportedActivityDefinitions on HealthcareService.type. It lists only the ActivityDefinitions and PlanDefinitions that it supports. (TA Routing; GF Addressing, NL-GF-HealthcareService).
-
Task.location, where present, identifies the Location at which the work is to be carried out. A HealthcareService can be performed at several physical Locations, and a Placer can request care at a specific one.
-
Task.code does not carry the kind of work: it states what the owner is expected to do with the Request (see Task.code under Coordination Task).
Specified by this TA
-
The Fulfiller SHOULD support the ActivityDefinitions and PlanDefinitions that its HealthcareService lists: when a Request refers to such a definition, the Fulfiller SHOULD be able to resolve it and to process a Request according to it.
-
Supporting a definition does not oblige the Fulfiller to accept a Request: the Fulfiller MAY decline any Request, including one that refers to a definition it supports, by rejecting the Coordination Task.
-
The Fulfiller uses the information above to route the Request to the right internal process and, where Task.location is present, to the right Location, or to decline it (see Request).
-
Where the Request refers to no definition, the Fulfiller routes the Request on ServiceRequest.code alone.
Identifiers and search
Search parameters
Tasks are found, and Subscriptions filtered, by the business identifier of Task.owner, by the organization that assigned it, and by the business identifier of Task.requester. This TA uses the search parameters owner and requester that FHIR R4 defines on Task, with the modifier :identifier, and defines one search parameter of its own, owner-assigner.
|
Search |
Used for |
|
owner:identifier |
Filtering a Subscription (see Subscription) and searching for the Tasks of a Fulfiller (see Resynchronization). |
|
requester:identifier |
Searching for the Tasks of a Placer. |
|
owner-assigner |
Filtering a Subscription for all HealthcareServices of one organization (see Subscription) and searching for the Tasks of that organization (see Resynchronization). |
Follows from FHIR R4
-
Task has the search parameters owner, on Task.owner, and requester, on Task.requester, both of type reference. (FHIR R4, Task)
-
The modifier :identifier searches a reference by Reference.identifier instead of by the literal reference. The value is a token of the form <system>|<value>. (FHIR R4, Search)
-
A CapabilityStatement has no element to declare support for a modifier; it is stated in searchParam.documentation. (FHIR R4, CapabilityStatement)
Specified by this TA
-
This TA defines no new identifier systems. Where this TA identifies an Organization by its URA, in Task.requester.identifier and in Task.owner.identifier of an Authorization Cancellation Request Task, it uses the system
http://fhir.nl/fhir/NamingSystem/ura; a party that takes the URA from GF Addressing with another system records it there with this system, and the value is unchanged. A HealthcareService and a Location are identified by the identifier with which they are registered in GF Addressing, from the AssignedId slice of NL-GF-HealthcareService and NL-GF-Location, unchanged, including its assigner; the assigner carries the URA with the system that GF Addressing prescribes. -
Task.owner.identifier.assigner.identifier. Its value is the URA of the organization in the form
<system>|<value>, with the system with which the assigner carries it. It is defined in the implementation guide of this TA. -
A HealthcareService or Location whose AssignedId has an assigner identified otherwise than by a URA, such as by a KvK number, cannot be referred to as the owner or location of a Task under this TA.
-
The Placer:
-
SHALL support the search parameters owner and requester on Task with the modifier :identifier, and declare them in its CapabilityStatement (see Placer server capabilities).
-
SHALL support owner:identifier and owner-assigner in the filter of a Subscription, and owner-assigner as a search parameter on Task (see Subscription and Placer server capabilities).
-
SHALL record in
Task.owner.identifierthe identifier with which the HealthcareService is registered in GF Addressing, and inTask.requester.identifierthe URA of the Placer, as stated above. A Task that carries only a literalReference.referenceis not found by these searches.
-
-
The Fulfiller:
-
SHALL SHALL use in the filter of its Subscription either owner:identifier, with the identifier of its HealthcareService, or owner-assigner, with the URA of its organization, and the same filter when it searches the Placer's server for its Tasks (see Subscription and Resynchronization).
-
SHALL give the value of a search parameter in the form <system>|<value>.
-
MAY use requester:identifier to search for the Tasks of a given Placer.
-
Assumption about GF Addressing. This TA cannot place requirements on GF Addressing. It therefore does not require, but assumes, that GF Addressing ensures that an identifier system can only be used in a registration by the organization that the system refers to, so that a system and value identify one entity. The rules on ambiguous identifiers (see Coordination Task and Subscription) rely on this assumption.
Identifiers of Tasks and Subscriptions
The id of a Coordination Task, the id of a Cancellation Request Task and the id of a Subscription are carried in the notifications, so that every party that handles a notification sees them.
Follows from TA Notifications
-
Each id SHALL be stable, opaque and unpredictable:
-
Stable: the same id on every request for the same resource. Where the source uses per-recipient ids, the id MAY differ between receivers, but SHALL remain the same for each individual receiver.
-
Opaque: the id SHALL NOT reveal creation order, volume, creation time or content.
-
Unpredictable: the id SHALL NOT be guessable, nor computable or confirmable from a real-world identifying number such as the BSN by anyone who does not hold a secret of the Placer. To be not guessable, an id SHALL carry at least 64 bits of entropy, generated by a cryptographically secure random number generator or produced by a keyed transformation with a secret key and an output of at least 64 bits. Only the random or keyed part of an id counts towards this minimum.
-
-
A consumer SHALL treat an id as an opaque string: it SHALL NOT parse it, derive meaning from it, or assume a format when querying.
Specified by this TA
-
These requirements apply to the id of a Coordination Task, of a Cancellation Request Task, of a Subscription, of the Request to which Task.focus refers, and of the Patient to which ServiceRequest.subject and Task.for refer. The value of Task.identifier SHALL meet the requirement of opacity as well.
-
A UUIDv4 generated by a cryptographically secure random number generator meets these requirements. TA Notifications gives examples of constructions that satisfy the requirements and of constructions that do not (TA Notifications, Appendix A).
Notification
SubscriptionTopic
This TA does not define a SubscriptionTopic itself. Each use case that is specified as a profile of this TA defines one or more topics, each with its own canonical URL (see Design Choices). This section states the requirements that every such topic meets. The requirements of TA Notifications on a SubscriptionTopic apply in full, whether or not they are repeated here.
Follows from TA Notifications
-
In FHIR R4 a SubscriptionTopic is not a resource exchanged or stored at runtime: a Subscription refers to the topic by its canonical URL only. The topic is a design-time definition, published in the use-case-specific technical agreement that defines it. (TA Notifications)
-
A topic has a unique canonical URL and monitors a single resource type. (TA Notifications)
-
The definition of a topic specifies which interactions trigger it, and any further trigger condition, such as a coded value. (TA Notifications)
-
The definition of a topic states how the patient that an event concerns is resolved, and, where this differs between events, from which point the patient is resolvable. (TA Notifications)
-
A topic defines the filter parameters that a Subscription may use, with the name and the element of the monitored resource to which each applies. (TA Notifications)
Specified by this TA
Every topic of a use case under this TA:
-
SHALL monitor Task.
-
SHALL be triggered by create and update. create alone is not sufficient: both TA NP and eOverdracht rely on update-triggered notifications (dataset updates, cancellation), so a topic must support create and update to be specifiable as a profile of either.
-
SHALL allow the filter owner:identifier, the search parameter owner of FHIR R4 with the modifier identifier, which applies to Task.owner.identifier, and the filter owner-assigner, which applies to
Task.owner.identifier.assigner.identifier(see Search parameters). -
SHALL resolve the patient via Task.for, which is set at the creation of the Task, so that every event concerns an identified patient(see Patient context and readability).
-
SHALL deliver the Cancellation Request Tasks that refer to the Coordination Tasks it delivers. A Cancellation Request Task carries the same type of work as its Coordination Task (see Type of work on the Task), so a trigger condition that narrows the topic on the type of work admits it as well.
The use case defines the canonical URL of its topic, the trigger condition that narrows the topic to its type of work, and whether Subscriptions for the topic may be created in-band. The trigger condition narrows on the entry with type type-of-work in Task.input (see Type of work on the Task). FHIR R4 defines no search parameter on Task.input, so the trigger condition is expressed in FHIRPath, not as a query.
A use case that also publishes its topic as a SubscriptionTopic resource (TA Notifications) can do so in FHIR R5, not in R4B. In R5, SubscriptionTopic.canFilterBy.modifier is bound to search-modifier-code, which contains identifier; in R4B it is bound to subscription-search-modifier, which does not, so the filter parameter owner with the modifier identifier cannot be expressed there.
Because a Subscription fires on any matching interaction regardless of who performed it, including update in the topic means the Fulfiller is also notified of its own updates to the Coordination Task and to a Cancellation Request Task. A Fulfiller MAY disregard the content of a notification it recognizes as reporting its own prior update. It still accepts the notification with 200 OK and processes its event-number for the continuity check, as TA Notifications requires of a Subscription Client; a rejection would set the Subscription to error. The Placer holds the Subscriptions and receives no notifications under this TA.
Type of work on the Task
A topic of a use case narrows on the type of work (see SubscriptionTopic), and a Fulfiller needs to know the type of work from the Task itself, without reading the Request, for example when it finds the Task by a search. The Request does not state the type of work as such: ServiceRequest.code states the requested service, which is finer.
The Placer carries the type of work in exactly one entry of Task.input, with type type-of-work from the code system of this TA (see Codes of this TA) and a valueCodeableConcept with the code that the use case defines for its type of work. A Cancellation Request Task carries the same entry as the Coordination Task to which it refers, so that a topic and a search treat both alike. That code can be the one a use case already uses, such as SNOMED 308292007 for eOverdracht. The entry carries the type of work only, which is coarser than ServiceRequest.code.
The type of work is not carried in Task.code: Task.code states what the owner is expected to do with the Request, as in COW IG and TA Routing (see Routing by the Fulfiller). An implementation of eOverdracht, whose Task profile fixes Task.code to SNOMED 308292007, carries that code in Task.input instead.
The topic of a notification also indicates the type of work, but the Task states it as well: a Fulfiller that finds a Task by a search, during Resynchronization, has no notification to take the topic from, and a HealthcareService can hold Subscriptions for several topics. FHIR R4 defines no search parameter on Task.input, so a search cannot be narrowed to one topic (see Resynchronization).
Subscription
The requirements of TA Notifications on a Subscription apply in full, whether or not they are repeated here. A Subscription is as defined below, whether it is established out-of-band or in-band. The requirements below are separated into those that follow from TA Notifications and COW IG and those that this TA specifies.
Follows from TA Notifications and COW IG
-
A Subscription informs the Fulfiller of changes to the Coordination Tasks that it owns, and is held by the Placer, as Subscription Server, on its own server. (COW IG, Task at Placer with Subscriptions)
-
A Subscription concerns the events of every zorgaanbieder for which the base URL at which it is held is registered in GF Addressing. (TA Notifications)
-
A Subscription is established out-of-band by the Placer, or in-band by the Fulfiller where the use-case agreement specifies in-band creation for the topic. (TA Notifications)
-
Subscription.criteria SHALL carry the canonical URL of the topic. (TA Notifications)
-
The extension backport-filter-criteria carries the filter, in one of the formats of the Backport IG, which include [filterParameter]:[modifier]=[value], using a filter parameter defined by the topic. (TA Notifications; Subscriptions R5 Backport IG 1.1.0, Components)
-
The extension backport-payload-content sets the payload mode. (TA Notifications)
-
How the notification endpoint of the HealthcareService is discovered is the responsibility of GF Addressing. (GF Addressing; TA Routing)
Specified by this TA
-
A Subscription is established once per HealthcareService of the Fulfiller, per topic under which that service receives Tasks, and per base URL at which Coordination Tasks for that service are hosted, as part of onboarding that service — not per Task — and serves every subsequently created Task at that base URL. Where that base URL is registered for several Placers, one Subscription serves the Coordination Tasks of all of them. Instead of a Subscription per service, an organization MAY hold one Subscription for all HealthcareServices it provides, per topic and base URL, which also serves services it registers later. Per organization, topic and base URL, a Fulfiller has either one Subscription per service or one Subscription for the organization, not both; the Placer SHALL NOT create or accept a Subscription that would combine the two.
-
The Placer SHALL NOT create a Coordination Task for a HealthcareService under a topic unless a Subscription for that service, or for the organization that provides it, and for that topic exists at the base URL at which it hosts that Task, with status active or error.
-
A Fulfiller that sets a Subscription to off, through Updating a Subscription (TA Notifications), ends the onboarding of that service, or of all services of the organization for a Subscription on owner-assigner, for that topic at that base URL. The Placer then SHALL NOT create a new Subscription for that service or organization, topic and base URL unless the Fulfiller has agreed to this outside this TA. (TA Notifications, Replacing a Subscription) Open Coordination Tasks that refer to the service keep their owner, but changes to them are no longer notified; the Fulfiller can retrieve them as described in Resynchronization.
-
Subscription is addressed to a notification endpoint: channel.endpoint begins with the address of an Endpoint with payloadType Notification in HealthcareService.endpoint, or, for a Subscription on owner-assigner, in Organization.endpoint of that organization (TA Notifications, Preconditions). An endpoint of an ActivityDefinition or PlanDefinition is not used under this TA (see Design Choices). When it is established out-of-band, the Placer creates it. When it is established in-band, the Fulfiller creates it with that notification endpoint.
-
The filter SHALL be of the form
owner:identifier=<system>|<value>, in which<system>|<value>is the business identifier of the HealthcareService (seeTask.owner), or of the formowner-assigner=<system>|<value>, in which<system>|<value>is the URA of the organization that provides the HealthcareServices. The topic allows both filters (see SubscriptionTopic). The search in Resynchronization uses the same filter, so that the Subscription and the search select the same Tasks. The examples in TA Notifications, which use a filter parameter owner defined by the topic, without a modifier and with the URA of an organization, do not apply under this TA: Task.owner identifies a HealthcareService, and the URA of the organization is filtered with owner-assigner. -
A filter in backport-filter-criteria SHALL NOT exclude a Cancellation Request Task that is owned by the Fulfiller, for example by filtering on Task.code without admitting abort.
-
The payload mode SHALL be id-only. The payload modes empty and full-resource SHALL NOT be used under this TA.
-
A Subscription SHALL carry the extension backport-heartbeat-period, with the interval that the use case states for the topic. For out-of-band creation the Placer sets it; for in-band creation the Fulfiller requests it, and the Placer SHALL accept it unchanged. The Fulfiller SHALL check at that interval whether a heartbeat was missed, and SHALL compare events-since-subscription-start with the highest event-number it has processed; TA Notifications makes this a SHOULD. Without heartbeats, the Fulfiller would not detect a missed last notification, such as of a Cancellation Request Task or of the cancellation of its Coordination Task (TA Notifications, Heartbeat Notification). The Placer learns that a delivery failed, but the Fulfiller is the party that acts on the Task, so the Fulfiller has to detect the miss itself.
-
The Placer SHALL NOT create or accept a Subscription for an owner identifier that does not resolve to exactly one HealthcareService, or for a URA that does not resolve to exactly one organization, in GF Addressing, in the replica of the directory that the Placer uses to select the Fulfiller (see the assumption about GF Addressing under Search parameters).
On what basis the Placer accepts a Subscription that the Fulfiller creates in-band, or decides to create a Subscription itself out-of-band, is outside the scope of this TA, apart from the rule above on ambiguous identifiers. The notification endpoint is verified as TA Notifications requires. TA Notifications and the generic functions for authorization and consent apply.
Authorization value
TA Notifications allows an event-notification for an out-of-band Subscription to carry an authorization value for the subsequent pull, and does not allow it for an in-band Subscription. Under this TA, whether the Fulfiller may read a Task, the Request or the Patient is decided by its authentication and the identification that the Placer recorded (see Write access), not by a value in the notification.
A notification under this TA SHALL NOT carry an authorization value (authorization-type, authorization-value), for out-of-band and in-band Subscriptions alike, so that access does not depend on how a Subscription was established.
Depends on a decision outside this TA. Should TA I&A introduce an authorization value that is bound to a notification, this TA will reconsider this rule.
Use-case agreements under TA Notifications
A use case that is specified as a profile of this TA is the use-case-specific technical agreement in the sense of TA Notifications, and SHALL meet the requirements that TA Notifications places on such an agreement. This TA settles some of these requirements for every use case; a use case SHALL NOT deviate from what this TA settles. The table lists, for each requirement, what this TA settles and what the use case states.
|
Requirement of TA Notifications |
Settled by this TA |
Stated by the use case |
|
Definition of each SubscriptionTopic |
Monitors Task; triggered by create and update; filter parameters owner with modifier identifier on Task.owner.identifier, and owner-assigner on Task.owner.identifier.assigner.identifier; patient resolved via Task.for, from creation (see SubscriptionTopic) |
Canonical URL, and version where published as a resource; the trigger condition on the type of work |
|
Identification of the patient and readability of the Patient resource before selection |
None: Task.for is set at creation, so every event concerns an identified patient, by an id that is not a business identifier. |
Whether the Patient resource is readable before selection, and on what basis (see Patient context and readability) |
|
Workflow or data resource, and why |
Task, a workflow resource: the Fulfiller acts on the state of the work |
— |
|
Permitted payload modes |
id-only only; no topic is triggered by delete (see Subscription) |
— |
|
In-band, out-of-band or both |
— |
Per topic |
|
Heartbeats and interval |
Heartbeats SHALL be used for every topic, so that the Fulfiller detects a missed last notification, such as of a cancellation (see Subscription) |
The interval, per topic |
|
$events, retention, reconciliation route |
$events not required; the reconciliation route is Resynchronization; no topic is triggered by delete |
Whether $events is nevertheless required; in every case the retention period for replayable events, which also sets how long $status remains available on a Subscription that is set to off or replaced |
|
Maximum retry duration |
— |
For handshake, heartbeat and event notifications |
|
Broadly accessible resources |
Not applicable: a Coordination Task and a Cancellation Request Task each have a single receiver (see Design Choices) |
— |
|
Processing basis and authorization conditions |
— |
Per GF Authorization and GF Toestemming (and, where applicable, EHDS), including the basis on which every candidate reads the Request and receives the patient identifier before selection |
|
Routing information for the receiver |
The type of work in Task.input; routing per TA Routing (see Type of work on the Task and Routing by the Fulfiller) |
The code for its type of work |
In addition to the requirements of TA Notifications, a use case states when the work counts as started, and therefore when the Fulfiller moves the Coordination Task to in-progress (see Status of the Coordination Task).
Healthcare services
Changes to healthcare services
Healthcare services change: they are split, merged, renamed or retired. Each HealthcareService has its own Subscriptions, one per topic and base URL, and open Tasks refer to the service by its identifier. A change to a service therefore calls for maintenance of the Subscriptions of that service and of the Tasks that refer to it. The maintenance concerns at least how the Placer learns of a change to a service, what happens to the Subscriptions of the service, and what happens to the open Tasks that refer to it.
Depends on a decision outside this TA. How the Placer learns that a healthcare service is split, merged, renamed or retired follows from GF Addressing, through the directory data that the Placer synchronizes. This TA does not specify it.
A change that keeps the identifier and the notification endpoint of the service, such as a new name, requires no maintenance. When the notification endpoint of a service changes, each Subscription of that service is replaced by one addressed to the new endpoint: by the Placer for an out-of-band Subscription, and by the Fulfiller for an in-band Subscription (TA Notifications, Replacing a Subscription). The same applies when the notification endpoint of an organization changes, to its Subscriptions on owner-assigner. The endpoint cannot be changed on an existing Subscription (TA Notifications, Updating a Subscription).
Open Coordination Tasks and Cancellation Request Tasks keep their owner. The Placer sets Task.owner once, at creation (see Write access), and does not move an open Task to another service. A Fulfiller whose service can no longer carry out the work rejects the Task or sets it to failed (see Cancellation by the Fulfiller), and the Placer then decides on a new Task (see Handling the End of a Coordination Task).
The Placer SHOULD NOT set a Subscription of a service to off while open Coordination Tasks refer to that service, other than after replacing it, so that every open Task keeps a Subscription through which its notifications are delivered.
The Placer SHALL NOT create a new Coordination Task for a service that no longer resolves in the directory data (see Coordination Task). A successor service, from a split or a merge, gets its own Subscriptions through onboarding, like any other service, unless a Subscription for its organization already covers it (see Subscription).
Transactions
In each transaction and pattern, the rules are separated into those that follow from COW IG, TA Notifications or FHIR, and those that this TA specifies. The requirements of those specifications apply in full, whether or not they are repeated here.
Task lifecycle
Task Creation
-
Trigger: the Placer has authorized a Request and identified one or more candidate Fulfillers.
-
Exchange: none between the parties. The Placer creates the Coordination Task on its own FHIR server, in a way it chooses (see Coordination Task); what the parties exchange is the notification and the read by the Fulfiller.
Follows from COW IG and TA Notifications
-
The Task is delivered as Notified Pull, via the standing Subscription (Resource Definitions → Subscription). The Fulfiller reads the Task from the Placer's server.
-
The reads by the Fulfiller that follow a notification, of the Coordination Task, the Request, the Patient and the resources of the dataset, are the retrieval to which TA Notifications refers; its authorization is governed by TA I&A and TA Pull, not by TA Notifications.
Specified by this TA
-
The notification is id-only: it carries a reference to the Coordination Task and no content. The reference is an absolute URL.
Task Update by Fulfiller
-
Trigger: the Fulfiller updates
Task.status,Task.businessStatus,Task.statusReason,Task.executionPeriod,Task.lastModified, orTask.output, or adds or removes an entry with type information-request inTask.input.
-
Exchange: PUT/PATCH by the Fulfiller on the Placer-hosted Coordination Task.
Follows from COW IG
-
The Fulfiller updates the Coordination Task at the Placer to report the progress of the work, over the Request's lifecycle.
Specified by this TA
-
The update is limited to the elements named in the trigger. The update is version-aware (see Write access).
Task Update by Placer
-
Trigger: the Placer updates the Coordination Task on its own initiative — for example, by cancelling it before in-progress (see Cancellation, below), or by changing any other element.
-
Exchange: none between the parties. The Placer changes its own Coordination Task, in a way it chooses; what the parties exchange is the notification and the read by the Fulfiller.
Follows from COW IG and TA Notifications
-
The update is delivered as Notified Pull: the Fulfiller did not make this change itself and can learn of it only through the notification or by reading the Task.
Handling the End of a Coordination Task
A Coordination Task ends when Task.status becomes completed, failed, rejected, cancelled or entered-in-error. The Placer decides about the Request by looking at all Coordination Tasks that refer to it, not at one Task alone. The column Source shows whether a row follows from COW IG or is specified by this TA.
|
Task.status |
Meaning |
What the Placer does |
Source |
|
completed |
The Fulfiller has finished its work. |
Review Task.output. Normally set Request.status to completed. If more work is needed, keep the Request active and create a new Coordination Task. |
COW IG |
|
failed |
The Fulfiller accepted or started the work but could not complete it. |
Either create a new Coordination Task, for another Fulfiller or the same one, and leave the Request active, or stop and set Request.status to revoked. |
COW IG |
|
rejected |
The Fulfiller declined before starting, giving Task.statusReason. |
If other candidates remain under consideration, leave the Request unchanged. Otherwise create a new Coordination Task for another Fulfiller, or set Request.status to revoked. |
COW IG |
|
cancelled |
The Coordination Task was withdrawn by the Placer, directly before it reached in-progress or through an accepted Cancellation Request Task after that. |
If the Placer is withdrawing the Request, set Request.status to revoked as well as cancelling the Task. If only a non-selected candidate was cancelled, leave the Request unchanged. If the selected Fulfiller was cancelled while the Request continues, leave the Request active and create new Coordination Tasks (see Cancellation (Before in-progress)). After an accepted Cancellation Request Task, Request.status is already revoked. |
COW IG |
|
entered-in-error |
The Task was created by mistake. |
Where the Request is correct, create a new Coordination Task for it, for the right Fulfiller. Change the Request only if it was also wrong. |
This TA |
This TA specifies in addition:
-
While other candidates are still under consideration, the end of one candidate's Task does not change the Request. The Placer SHOULD NOT leave a Request active when no open Coordination Task refers to it, unless it is about to create one.
-
Other Tasks that relate to a Coordination Task, such as a Cancellation Request Task, do not change the Request themselves. The Placer acts on the status of the Coordination Task.
Patterns for several candidates
Multiple Fulfillers Pattern
A Placer solicits one or more candidates at once, lets each respond, and commits to one, without having authorized any other candidate to act on the Request in the meantime. (COW IG, eOverdracht; see Design Choices)
Follows from COW IG
-
One Request SHALL be shared by every candidate under consideration.
-
One Coordination Task SHALL be created per candidate, each referencing the same Request via Task.focus.
-
Each candidate MAY accept, by updating its own Task.status to accepted, as a Task Update by Fulfiller (see Transactions). Acceptance does not imply selection.
-
When a candidate is chosen, the Placer SHALL set that candidate’s Task.code to fulfill and its Task.businessStatus to selected, and SHALL set every other candidate’s Task.status to cancelled with the reason “not selected”.
Specified by this TA
-
The Placer records selected and not selected with the codes selected and not-selected of the code system of this TA (see Reason for cancelling a non-selected candidate).
-
ServiceRequest.performer SHALL remain unset while solicitation is open.
-
ServiceRequest.performer MAY be set to the selected candidate once chosen; Task.owner on the selected Task remains authoritative regardless.
-
The Placer MAY invite several HealthcareServices of the same Fulfiller for the same Request (see Candidates of the same Fulfiller).
-
The Placer SHALL select only a candidate whose Coordination Task has the status accepted.
How the Placer weighs the responses of the candidates and decides which one to select is outside the scope of this TA. This TA specifies responses of the candidates such as accepting and bidding (see Bidding), and how the decision is recorded and communicated once made.
A candidate learns from Task.code request-fulfillment that no candidate has been selected yet and that it may not start the work (see Recognizing the pattern that applies). What a candidate that is not yet selected may read is stated in Patient context and readability.
Nothing in this pattern depends on the transfer-of-care use case that motivated it: the same structure applies to any workflow type this TA covers, wherever a Placer might solicit more than one Fulfiller for the same piece of work.
Candidates of the same Fulfiller
The Multiple Fulfillers Pattern creates one Coordination Task per candidate, and Task.owner identifies a HealthcareService. A Placer can therefore invite two HealthcareServices of the same Fulfiller as candidates for the same Request. Read access, however, is decided by the identification of the Fulfiller (see Write access), not by the HealthcareService. Once one of these services is selected, the other service has the same identification, and may read the Patient resource as well.
This is not a disclosure to another party: both services belong to the same zorgaanbieder, which controls access within its own organization. The Placer MAY therefore invite several HealthcareServices of the same Fulfiller as candidates for the same Request. Two HealthcareServices belong to the same Fulfiller when the Placer records the same identification for them (see Coordination Task). When the Placer cancels the Coordination Task of one of them, the Fulfiller keeps its read access through the other (see Patient context and readability).
Should TA I&A let a Fulfiller authenticate as a HealthcareService, a later version of this TA can grant access per service.
Reason for cancelling a non-selected candidate
When the Placer selects a candidate in the Multiple Fulfillers Pattern, it cancels the Coordination Tasks of the other candidates. COW IG gives these Tasks the reason not selected in Task.statusReason, but defines no code for it, and Task.statusReason has only an example binding in FHIR R4. A candidate that is not selected may not read the Request (see Patient context and readability), so it learns why its Task was cancelled from Task.statusReason alone.
The Placer SHALL set Task.statusReason to the code not-selected from the code system of this TA (see Codes of this TA), and SHOULD add the text not selected in Task.statusReason.text. A candidate recognizes from the code that it was not selected, without reading the Request, and a system that does not know the code can still show the text. The code is defined together with selected, which records the opposite decision.
Bidding
Bidding is a way of using the Multiple Fulfillers Pattern in which candidates do not only accept but also describe what they would offer, so that the Placer, and where relevant the patient, can compare the candidates before one is selected. (COW IG)
Follows from COW IG
-
A candidate describes what it would offer in a bid. What a bid contains depends on the care domain and is not defined by this TA. A bid may describe, for example, the candidate's availability, a more specific service it would perform, the expected cost, or the person who would carry out the work.
Specified by this TA
-
A bidding task is a Coordination Task. The Placer invites bids by creating a Coordination Task for each candidate, all referring to the same Request (see Multiple Fulfillers Pattern). While several candidates are under consideration, these Coordination Tasks are the bidding tasks.
-
A candidate responds with a bid by accepting its bidding task and recording the bid in Task.output, as a Task Update by Fulfiller.
-
A candidate that is not yet selected may read the Request, and may read the Patient resource only where the use case makes it readable before selection (see Patient context and readability). It accepts, and bids, on the basis of the Request, the type of work in Task.input (see Type of work on the Task) and the further entries of Task.input that the Placer shares before selection; what its acceptance means is stated in Status of the Coordination Task. After selection, a Fulfiller that finds, for example from the Patient resource or the data made available, that it cannot carry out the work sets the Coordination Task to failed, with a statusReason (see Status of the Coordination Task). The Coordination Tasks of the other candidates have then been cancelled, and the Placer decides on a new Coordination Task (see Handling the End of a Coordination Task).
-
A candidate that does not want to bid MAY reject its bidding task with a statusReason. A candidate that accepts without a bid makes no offer beyond its acceptance.
-
The Placer reviews the bids received and selects a candidate. How it compares the bids and decides is outside the scope of this TA. The selection is recorded as described in the Multiple Fulfillers Pattern. A bid is not a commitment by the Placer: bidding, like accepting, does not imply selection.
-
The bidding ends when the Placer selects a candidate. The Coordination Task of the selected candidate continues for the work itself, and its Task.output keeps the bid. The Coordination Tasks of the other candidates are cancelled (see Multiple Fulfillers Pattern).
-
Each candidate has its own bidding task, so a candidate's bid is recorded on its own task only. Whether a candidate may see the bids of other candidates is an access-control question, outside the scope of this TA.
Single Fulfiller Pattern
Where a Placer already knows, at the moment the Request is authorized, which single Fulfiller should carry out the work, the Multiple Fulfillers Pattern does not apply. This pattern is specified by this TA.
-
Task.code SHALL be fulfill from creation.
-
Task.owner SHALL identify the HealthcareService of the one Fulfiller directly.
-
The Fulfiller moves Task.status from requested or received to accepted before it starts the work, as in the Multiple Fulfillers Pattern (see Status of the Coordination Task).
-
The Fulfiller MAY decline by moving
Task.statusfrom requested or received to rejected, with statusReason.
This pattern applies only where the Placer and the sole Fulfiller have nothing to negotiate. Where negotiation is wanted — a proposed timing, a different scope, a request for more information — even with only one candidate, the Multiple Fulfillers Pattern applies instead, and the Request is treated as a solicitation of exactly one.
How a Fulfiller recognizes that this pattern applies is described in Recognizing the pattern that applies.
Cancellation
Cancellation (Before in-progress)
This is an instance of Task Update by Placer, above, in which Task.status is set to cancelled.
-
Trigger: the Placer wishes to withdraw the Request, or to withdraw the Coordination Task of a candidate or of the selected Fulfiller while the Request continues; Task.status has not reached in-progress.
-
Exchange: none between the parties. The Placer sets its own Coordination Task to cancelled, in a way it chooses.
Follows from COW IG
-
The update is delivered as Notified Pull and requires no cross-organization write access.
-
When the Placer withdraws the Request, it also sets Request.status to revoked. When only this Coordination Task is cancelled, for example because another candidate was selected, Request.status stays active.
Specified by this TA
-
When the Placer withdraws the Request, it SHOULD state the reason in Task.statusReason.text. A Fulfiller whose Task is cancelled loses its read access to the Request (see Patient context and readability), so it learns from Task.statusReason which of the two applies.
-
When the Placer cancels the Coordination Task of the selected Fulfiller while the Request continues, for example because the patient prefers another Fulfiller, it SHOULD state the reason in
Task.statusReason.text; the codenot-selecteddoes not apply, since no other candidate has been selected. WhereServiceRequest.performerwas set to that Fulfiller, the Placer clears it, and it removes the businessStatus selected from the cancelled Task. The Placer MAY then create new Coordination Tasks for the same Request, for a single Fulfiller or as a new solicitation (see Multiple Fulfillers Pattern), also for a Fulfiller whose earlier Coordination Task for that Request has ended.
Cancellation Request (After in-progress)
-
Trigger: the Placer wishes to withdraw the Request; Task.status has reached in-progress.
-
Exchange: none between the parties. The Placer creates a Cancellation Request Task on its own FHIR server, in a way it chooses; the Fulfiller learns of it through the notification.
Follows from COW IG
-
The Cancellation Request Task is delivered as Notified Pull.
Cancellation Request Response
-
Trigger: the Fulfiller has read a Cancellation Request Task.
-
Exchange: PUT/PATCH by the Fulfiller, updating the Cancellation Request Task's status. When it accepts, the Fulfiller then also updates the Coordination Task to cancelled.
Follows from COW IG
-
The response is an update.
Specified by this TA
-
When the Fulfiller accepts the Cancellation Request Task, the work is stopped, the Fulfiller sets the Coordination Task to cancelled, and the Placer sets Request.status to revoked. When the Fulfiller rejects it, the work continues and Request.status stays active.
After an accepted Cancellation Request
The Placer sets Request.status to revoked when it withdraws the Request (see Cancellation Request Response).
After accepting the Cancellation Request Task, the Fulfiller sets the Coordination Task to cancelled. FHIR R4 allows a Task in any non-terminal state, including in-progress, to be cancelled when it ends due to external forces rather than an error; failed remains for a Fulfiller that can no longer carry out the work (FHIR R4, Task, Tasks State Machine; COW IG, Fulfiller Unable to Perform). COW IG also allows the Fulfiller to set the Coordination Task to on-hold here; this TA does not use on-hold, which in the state machine of FHIR R4 leads only back to in-progress, so the Coordination Task would never reach an end status while the Request is revoked.
A Coordination Task that was cancelled after in-progress is recognized by the accepted Cancellation Request Task whose Task.focus refers to it.
Cancellation by the Fulfiller
A Fulfiller that cannot or does not want to carry out the work has three possibilities. None of them changes the Request itself, which only the Placer modifies. All three follow from COW IG.
-
Declining before starting. The Fulfiller sets the status of its Coordination Task to rejected, with a statusReason. The Request stays active.
-
Unable to complete. A Fulfiller that has accepted or started the work, and finds that it can no longer carry it out, sets the status of its Coordination Task to failed, with a statusReason. The Placer then decides what happens to the Request (see Handling the End of a Coordination Task).
-
Asking the Placer to withdraw the authorization. A Fulfiller that finds that the Request itself is inappropriate or even dangerous, so that no Fulfiller should carry it out, MAY ask the Placer to cancel it, with an Authorization Cancellation Request Task, and then also rejects its Coordination Task or sets it to failed (COW IG, Fulfiller Decline to Perform). Rejecting or failing the Coordination Task alone ends only the involvement of this Fulfiller; the Placer may then create a Coordination Task for another Fulfiller (see Handling the End of a Coordination Task). This Task has the status requested, the code abort, the intent proposal, refers to the Request in Task.focus, and states the reason of the Fulfiller in Task.reasonCode. The Placer decides. When the Placer accepts, it sets Request.status to revoked and ends the Coordination Tasks that refer to the Request and are still open: it sets those that have not reached in-progress to cancelled, and creates a Cancellation Request Task for those that are in-progress (see Cancellation (Before in-progress) and Cancellation Request (After in-progress)).
With the third possibility, the Fulfiller creates the Authorization Cancellation Request Task on the Placer’s server (see Write access), with the elements of the table Authorization Cancellation Request Task in Summary of the profiles. Its owner is the Placer, so the Subscription of the Fulfiller delivers neither this Task nor the answer to it. The Fulfiller learns the answer by reading the Authorization Cancellation Request Task, or by searching with requester:identifier=<system>|<value>&code=abort&intent=proposal.
Depends on a decision outside this TA. COW IG asks in its ballot whether this Task should become a profile of its own. This TA follows the outcome.
Recovery and server behavior
Resynchronization
A Fulfiller that has missed notifications (a gap in the event numbers, a missed heartbeat, or a Subscription that was in error) retrieves the current state by searching the Placer's server. This TA does not require the $events operation. This section is the route for reconciliation that TA Notifications requires of a use-case agreement when $events is not required.
Follows from TA Notifications
-
The period of the search starts before the last processed notification, with a margin, because the time of an event need not equal meta.lastUpdated of the Task (see _lastUpdated). A Task processed twice is processed idempotently.
-
A search for missed changes is subject to data minimization, and SHALL be limited to the monitored resource type, the filter criteria of the Subscription and the period of the gap. (TA Notifications)
Specified by this TA
-
The Fulfiller searches Tasks with the filter of its Subscription over the period of the gap:
GET [base]/Task?owner:identifier=<system>|<value>&_lastUpdated=ge<time>, orGET [base]/Task?owner-assigner=<system>|<value>&_lastUpdated=ge<time>. Every search includes this filter and the period. FHIR R4 defines no search parameter onTask.input, so the search cannot be narrowed to one topic: it can also return Tasks of its HealthcareService or organization under other topics. These are Tasks that the Fulfiller may read in any case (see Write access). The Fulfiller recognizes the type of work of each Task it finds from the entry with type type-of-work (see Type of work on the Task).
-
To find the Coordination Tasks for one Request, the Fulfiller adds focus=<Request>. To find the Cancellation Request Tasks for a Coordination Task, it adds focus=Task/<id>&code=abort.
Placer server capabilities
The server of the Placer SHALL publish a CapabilityStatement (the capabilities interaction) that declares at least the following.
Follows from FHIR R4 and TA Notifications
-
A server publishes a CapabilityStatement through the capabilities interaction. (FHIR R4)
-
For Subscription: read and search with the parameters of TA Notifications, the $status operation, and the $events operation where it is supported. (TA Notifications)
-
Where the server supports in-band creation of Subscriptions, the supported SubscriptionTopics, in the extension capabilitystatement-subscriptiontopic-canonical; this is a SHOULD. (TA Notifications)
-
For Subscription: the interaction update, for in-band and out-of-band Subscriptions alike, accepting only the changes that the transaction Updating a Subscription permits. (TA Notifications)
-
Where in-band creation is specified for a topic: the interaction create on Subscription. (TA Notifications)
Specified by this TA
-
For Task: the interactions read, search, update and patch, and create for the Authorization Cancellation Request Task; the versioning level versioned-update; the search parameters owner and requester, each with the support of the modifier :identifier stated in searchParam.documentation; the search parameter owner-assigner of this TA; and the search parameters focus, code, intent, status, business-status and _lastUpdated.
-
For Subscription: the profile of this TA as supportedProfile.
-
For the Request: the interaction read.
-
For content it shares in Task.input: read on each resource that an entry with type available-resource refers to, and the interactions and search parameters that each search in an entry with type available-query uses (see Sharing additional content).
-
For Patient: the interaction read.
The formal definition of this CapabilityStatement is published in the implementation guide of this TA (see Task and Subscription profiles).
Codes of this TA
This TA defines a code system with nine codes.
It is published in the implementation guide of this TA (package nl.twiin.fhir.r4.workflow), with the canonical URL https://fhir.twiin.nl/ig/workflow/CodeSystem/ta-workflow.
|
Code |
System |
Used in |
Meaning |
|
fulfill |
Task.code |
The owner is asked to carry out the Request. |
|
|
request-fulfillment |
Task.code |
The Multiple Fulfillers Pattern applies and no candidate has been selected yet; the owner is invited to accept and, optionally, to bid, and may not yet start the work. |
|
|
selected |
Task.businessStatus |
The Placer has selected the owner of this Task as the Fulfiller (see Multiple Fulfillers Pattern). |
|
|
not-selected |
Task.statusReason |
The Placer has selected another candidate; the Coordination Task of this candidate is cancelled (see Reason for cancelling a non-selected candidate). |
|
|
type-of-work |
Task.input.type |
The entry carries the type of work (see Type of work on the Task). |
|
|
available-resource |
Task.input.type |
The entry refers, in valueReference, to one resource at the Placer that the Placer makes available to the Fulfiller. |
|
|
available-query |
Task.input.type |
The entry carries, in valueString, a search relative to the FHIR base of the Placer that the Placer makes available to the Fulfiller. |
|
|
visit-scheduled |
Task.businessStatus |
A visit with the patient is scheduled. |
|
|
awaiting-information |
Task.businessStatus |
The Fulfiller needs more information from the Placer to continue or to decide. |
|
|
information-request |
Task.input.type |
The entry carries, in the entry itself, a request from the Fulfiller for information it needs from the Placer (see Business status). |
Follows from FHIR R4 and COW IG
-
The code fulfill is defined by HL7 in the FHIR code system for Task codes. (FHIR R4)
-
The code request-fulfillment is not defined in any published code system. COW IG uses it in its Workflow State Overview for multiple potential performers, but does not define it in its formal artifacts, and the COW IG profile for the Coordination Task accepts any value in Task.code. (COW IG)
-
The code selected is not defined in any published code system either. COW IG uses it in its Workflow State Overview for the selected Fulfiller, but its value set for Task.businessStatus, an example binding, does not contain it. (COW IG)
Specified by this TA
-
This TA defines a code system, which contains request-fulfillment, selected, awaiting-information, visit-scheduled, not-selected, type-of-work, available-resource, available-query and information-request; a value set for Task.code, which contains fulfill from the HL7 code system and request-fulfillment from the code system of this TA; and two value sets bound with an extensible binding: one for Task.statusReason, which contains not-selected, and one for Task.businessStatus, which contains selected, awaiting-information and visit-scheduled.
-
The Coordination Task profile binds Task.code to this value set with a required binding. A Task.code that is not in this value set is not valid under this TA. The HL7 code system is not changed or extended.
The formal definitions of this code system and of the value sets are published in the implementation guide of this TA (see Task and Subscription profiles).
Recognizing the pattern that applies
A Fulfiller that receives a Coordination Task needs to know which pattern applies. In the Single Fulfiller Pattern the Placer has chosen the Fulfiller, nothing is negotiated, and the Fulfiller may start the work. In the Multiple Fulfillers Pattern the Fulfiller is one of several candidates, and it waits until the Placer selects a candidate; a Fulfiller that started the work too early would do work for nothing.
Task.code shows which pattern applies. While the Multiple Fulfillers Pattern applies and no candidate has been selected, also when only one candidate is invited, the Placer sets Task.code to request-fulfillment. In the Single Fulfiller Pattern Task.code is fulfill from creation, and at selection the Placer sets Task.code to fulfill on the Coordination Task of the selected candidate (see Multiple Fulfillers Pattern). COW IG uses the same codes in its Workflow State Overview.
A Fulfiller SHALL NOT start the work while Task.code is request-fulfillment. The Placer’s server SHALL reject an update by the Fulfiller that sets Task.status to in-progress while Task.code is request-fulfillment.
Task.code is used, rather than Task.businessStatus or ServiceRequest.performer, because it is the element that states what the owner is expected to do, and the Fulfiller does not need to read the Request to see it.
Changes since 0.3
-
Scope, Vocabulary, Summary of the profiles, Request, Retrieving the resources of a dataset, Sharing additional content, Placer server capabilities, Codes of this TA. A standard dataset is a guideline for what a Fulfiller expects, not a requirement. The Placer states for each Request what it makes available, in Task.input with type available-resource or available-query (formerly supplemental-resource and supplemental-query), and supports retrieving it. (technical)
-
Relationship to COW IG, Actors, Summary of the profiles, Write access, Business status, Sharing additional content, Task Update by Fulfiller, Codes of this TA. The Fulfiller may add and remove entries with type information-request in Task.input to ask the Placer for information, in line with COW IG. (technical)
-
Design Choices, Actors, Summary of the profiles, Rules that a profile cannot express, Coordination Task, Search parameters, SubscriptionTopic, Subscription, Use-case agreements under TA Notifications, Changes to healthcare services, Resynchronization, Placer server capabilities. Instead of one Subscription per HealthcareService, an organization may hold one Subscription for all its services, filtered with the new search parameter owner-assigner on the URA in Task.owner.identifier.assigner and notified at an endpoint of the organization; not both. The assigner is the organization that provides the HealthcareService. Diagrams show both options. (technical)
-
Actors, Summary of the profiles, Write access, Status of the Coordination Task, Cancellation Request Task, Handling the End of a Coordination Task, Cancellation Request Response, After an accepted Cancellation Request. After an accepted Cancellation Request Task, the Fulfiller sets the Coordination Task to cancelled instead of failed, as FHIR R4 allows, and sets Task.executionPeriod.end. (technical)
-
Summary of the profiles, Rules that a profile cannot express, Request, Sharing additional content, Patient context and readability, Identifiers of Tasks and Subscriptions, SubscriptionTopic, Use-case agreements under TA Notifications, Multiple Fulfillers Pattern. A candidate may read the Request from the creation of its Coordination Task, and the Patient resource only once Task.code is fulfill, unless the use case states otherwise and on what basis. Until selection, the Placer keeps data that directly identifies the patient out of the Request. ServiceRequest.subject and Task.for carry the id of the Patient resource, which is not a business identifier; Task.for is set at creation, and the use case no longer justifies that the Task is not identifying. A Fulfiller whose Coordination Task is cancelled loses its read access to the Request and the Patient resource, also after selection. (technical)
-
Summary of the profiles, Coordination Task, Business status, Cancellation Request Task, Authorization Cancellation Request Task, Cancellation by the Fulfiller. Task.statusReason is required when a Coordination Task is rejected or failed, and, with text, while businessStatus is awaiting-information. The requesting party of a Cancellation Request Task or Authorization Cancellation Request Task gives its reason in Task.reasonCode, so Task.statusReason holds only the answer. (technical)
-
Summary of the profiles. ServiceRequest.priority: the Placer SHOULD populate it and the Fulfiller SHALL process it when present; Task.priority is not used. (technical)
-
Rules that a profile cannot express, Multiple Fulfillers Pattern, Candidates of the same Fulfiller. Several HealthcareServices of the same Fulfiller may be candidates for the same Request; access is per organization. (technical)
-
Coordination Task, Status of the Coordination Task, Handling the End of a Coordination Task. entered-in-error is only for a Coordination Task created by mistake, is written by the Placer, and is followed by a new Coordination Task for the same Request. (technical)
-
Business status. Task.businessStatus reports progress within a Task.status and never replaces it. Only selected is required, set by the Placer at selection; other values, from this TA, from COW IG or of its own, are agreed per use case. (technical)
-
Sharing additional content. The Fulfiller may share content in Task.output during the workflow, not only at its end. (technical)
-
Patient context and readability, Handling the End of a Coordination Task, Cancellation (Before in-progress). Before in-progress, the Placer may cancel the Coordination Task of the selected Fulfiller while the Request continues, clear ServiceRequest.performer and solicit again. (technical)
-
Multiple Fulfillers Pattern. The recommendation to record a selection as one atomic change is removed. (technical)
-
Scope. Soliciting candidates that the Placer does not know in advance, such as open bids, is out of scope. (editorial)
-
Vocabulary, Task and Subscription profiles. The Coordination Task, Cancellation Request Task and Authorization Cancellation Request Task are defined as Tasks that conform to the profile of the same name. The implementation guide contains informative examples. The implementation guide contains informative examples; this version refers to implementation guide 0.4.0-draft. (editorial)
-
Vocabulary, Design Choices, Retrieving the resources of a dataset, Type of work on the Task, Use-case agreements under TA Notifications, Candidates of the same Fulfiller, Bidding, Cancellation (Before in-progress). Wording that assumed a candidate cannot read the Request before selection is aligned with Patient context and readability; the type of work in Task.input is justified by topics and searches only. (editorial)
-
Design Choices. Topics are defined per use case, one or more each. Notifications are id-only so that every access to a Task is a read that the Placer checks, which also tells it when the Fulfiller has retrieved the Task. (editorial)
-
Subscription. Heartbeats are required because the Fulfiller, which acts on the Task, has to detect a missed notification itself. (editorial)