Interoperability Toolkit Notifications Additional Functional Module Requirements

Transcription

1 Interoperability Toolkit Notifications - Additional Functional Module Requirements Directorate Tech Office Document Record ID Key Division ITK NPFIT-ELIBR-AREL-DST Chief Technology Officer Paul Jones Status Draft Owner Adam Hatherly Version 0.5 Author Adam Hatherly Version Date 22 January 2013 Interoperability Toolkit Notifications Additional Functional Module Requirements Crown Copyright 2013

2 Amendment History: Version Date Amendment History /12/2012 Draft /12/2012 Updated following internal review /12/2012 Updated following internal review /01/2013 Added a requirement that WS-BaseNotification elements are used /01/2013 Changed could to may to align with other ITK specs Reviewers: This document must be reviewed by the following: Name Title / Responsibility Date Adam Hatherly Damian Murphy Technical Architect Technical Architect Mike Odling-Smee Technical Architect George Hope Technical Architect Approvals: This document must be approved by the following: Name Title / Responsibility Date Keith Naylor Head of Data Standards Implementation and Outreach Group Distribution: ITK Community Crown Copyright 2013 Page 2 of 21

3 Document Status: This is a controlled document. Whilst this document may be printed, the electronic version maintained in FileCM is the controlled copy. Any printed copies of the document are not controlled. Related Documents: These documents will provide additional information. Ref no Doc Reference Number Title Version 1 NPFIT-ELIBR-AREL-DST-0422 ITK Specifications Overview Latest 2 NPFIT-ELIBR-AREL-DST-0433 ITK Messaging Architecture Requirements Latest 3 NPFIT-ELIBR-AREL-DST-0418 ITK Addressing and Routing Requirements Latest 4 NPFIT-ELIBR-AREL-DST-0434 ITK Supporting Infrastructure Requirements Latest 5 NPFIT-ELIBR-AREL-DST-0424 ITK Additional Module Requirements Latest 6 NPFIT-ELIBR-AREL-DST-0430 ITK Web Services Transport Specification Latest 7 RFC2046: MIME Media Types Latest 8 OASIS WS-BaseNotification Specification Latest 9 TBC Notifications Domain Message Specification 1.0 Glossary of Terms: Please see ITK 2.0 Specifications Overview (See Related Document 1) for a consolidated glossary of terms used in the ITK documents Other terms acronyms and abbreviations commonly used with NHS CFH can be found in the Acronyms Guide Crown Copyright 2013 Page 3 of 21

4 Contents 1 Introduction Document Purpose Audience Document Scope Document Overview Module: Notifications Introduction Notification Transport Requirements Notification Sender Requirements General Notification Sender Requirements Links to Supporting Documents Notification Sender Requirements Document Metadata Notification Receiver Requirements General Notification Receiver Requirements Configurable Behaviours Error Scenarios Appendix A Example Notification Message Crown Copyright 2013 Page 4 of 21

5 1 Introduction 1.1 Document Purpose This document defines additional functionality which is required to gain ITK accreditation for sending and receiving of patient event notifications. It provides a mechanism for the QIPP Digital Technology team to define specifications to support care co-ordination, to define specialisations or additional functional requirements over and above the baseline ITK interface specifications. 1.2 Audience The primary audience are technical and product development staff within software suppliers who are interested in developing an ITK compliant application. A further intended audience are technical staff within an implementing organisation - who wish to understand the selection criteria for procuring an ITK compliant application. 1.3 Document Scope This document is part of a set of technical specifications relating to implementing ITK specifications. See the Toolkit Specifications Overview (related document 1) for more about other documents in the set. Messaging Architecture Service Interfaces Distribution Infrastructure Transport Patterns and Features Addressing and Routing Other Core Features Other Core Features Supporting Infrastructure Application Specific Common Middleware Specific Additional Modules Web Services DTS Transports (Other Transport) Crown Copyright 2013 Page 5 of 21

6 1.4 Document Overview The rest of this document covers a number of functional add-on modules. Within each module a number of requirements are listed in bold type, with additional detail provided in smaller type below this. MOD-xxx-xxx: Formal requirements statements are highlighted in bold boxes The accompanying text provides supporting detail, background and rationale Crown Copyright 2013 Page 6 of 21

7 2 Module: Notifications 2.1 Introduction The development of this specification forms part of a suite of interoperability capabilities defined as part of work being managed by the QIPP Digital Technology team to support electronic care co-ordination. As part of co-ordinating care for patients with complex care needs, there is a need to notify others caring for the patient when key events occur such as the publication of a new EPaCCS document The ITK notification message described in this document was designed to support these QIPP requirements. Additionally the ITK notification was also designed to be generic enough to be used for other forms or patient notification as other use-cases are identified by local teams. As a general principle it is expected that ITK notifications will be sent for information to augment existing information flows, rather than replace existing clinical communications. There would generally be no explicit expectation of specific actions being carried out by the recipient of a notification, and this mechanism should not be used to transfer care, or to act as a referral to another care setting. Where a recipient is not using a system that can receive an electronic notification message, consideration should be given to the use of other mechanisms for sending notifications to that recipient (e.g. NHSMail) subject to relevant IG controls being in place. This should then allow an upgrade-path over time for recipients migrating over to using the ITK notification mechanism. The Notifications Domain Message Specification provides a specification of a message that can be delivered over a range of transport mechanisms. It is however anticipated that ITK Web Services will be the primary transport mechanism and this MUST be supported by the sender. The message specification also provides details on how the messages must be constructed using a set of supplied schemas and the individual messages wrapped with the standard ITK distribution envelope before submission to the Message Handling System and Transport. In addition, for notification messages, the OASIS WS-BaseNotification standards will also be used to provide a mechanism for managing subscriptions (see below). Crown Copyright 2013 Page 7 of 21

8 2.2 Notification Transport Requirements Part of the wider requirements for managing notifications are likely to incorporate some form of publish/subscribe mechanism to allow systems to subscribe to receive notifications on specific topics. At this stage, this mechanism has not been defined within ITK, but existing OASIS specifications exist that cover this capability. Given that this is an existing, proven international specification, it has been adopted by ITK to provide a mechanism for managing subscriptions for ITK notifications. This specification also aligns with IHE, who also use the OASIS standard for notifications as defined in the IHE DSUB (Document Subscription) profile. The specific ITK requirements for publish/subscribe will be developed further in future ITK releases, but in this release, the WS-BaseNotification standard will be used for describing appropriate subscription metadata within ITK notification messages. The below diagram shows how the OASIS WS-BaseNotification section will be held within the existing ITK message structure. An example of an ITK notification message including the below elements can be found in Appendix A. HTTP Header SOAP Header Message Identification Technical Addressing Security Toolkit Custom SOAP Body Distribution Envelope Header Payloads Payload OASIS WS-BaseNotification content (see related document 8) WS-BaseNotification Subscription Reference Topic Dialect Producer Reference Message Standard ITK message structure taken from the ITK Web Services Transport Specification (related document 6) Message payload as defined in Notification Domain Message Specification (DMS) There are no ITK-specific requirements for how the WS-BaseNotification should be used beyond the standard requirements defined by OASIS. Over time, the ITK team will work with local teams to understand how best to make use of the OASIS notification standards, and decide if any additional constraints or guidance need to be defined as part of future ITK specifications. A simple implementation of this ITK Notification specification might involve configuration driven topics and subscriptions without the ability for notification recipients to directly subscribe/unsubscribe at run-time. For instance there might be a topic called epaccs-document-updates with a configuration file containing the Crown Copyright 2013 Page 8 of 21

9 systems in the locality that receive ITK notifications when a new EPaCCS document is created or updated. Should local teams wish to explore dynamic publish/subscribe we would encourage the use of the other OASIS specifications for managing topics and subscriptions this experience is likely to be extremely valuable for future incorporation of a publish / subscribe mechanism in ITK. NOT-OAS-01: Notification payloads MUST be wrapped in WS-BaseNotification elements The notification payload MUST be contained within appropriate elements as defined in the OASIS WS-BaseNotification standard. Crown Copyright 2013 Page 9 of 21

10 2.3 Notification Sender Requirements General The author and recipients of the notification should be identified in the message: NOT-SND-01: Author details should provide a human contact point The author details SHOULD provide the recipient with an appropriate human contact to gain further information about the event (e.g. The details of the clinician who updated a care plan). Notifications will often be addressed to individuals, but the organisation that the recipient works in must also be specified: NOT-SND-02: The recipient organisation(s) MUST be identified The notification MUST specify the recipient organisation(s) that it is intended for. A workgroup MAY also be specified where this is required to route the notification to the correct service or team. [Subject to minor change to draft DMS] In some cases, it may not be possible to identify an individual within the organisation or team as a specific recipient. This may be because the sender does not have (or does not want to maintain) a list of the specific individuals within the recipient organisation. In this case, the name of the recipient may be omitted. In cases where there is a desire not to divulge details of one or more recipients to the other recipients of the notification, consideration could be given to generating a separate notification specifically for the party/parties whose details should not be divulged to others. NOT-SND-03: All recipients SHOULD be identified The notification SHOULD include details of all recipients of the notification where the sender is able to provide this information. The overall solution will need to have some mechanism for resolving an end-point address to route messages to. In some cases this may involve some form of routing - see the Addressing and Routing Requirements document for more details and potential approaches for this (related document 3). It is likely that this would be linked with a subscription mechanism see previous sections of this document for further details of potential subscription mechanisms using the OASIS standard. NOT-SND-04: A sending system MUST allow for multiple copies of a notification to be sent to different recipients. Where a notification is being sent to multiple recipient systems, the sender MUST allow multiple copies of the notification to be sent to each of the recipient systems, so they can be routed to the correct recipients within those systems. Crown Copyright 2013 Page 10 of 21

11 The NotificationEventType and NotificationEventSubtype provide a standard set of nationally agreed events which can be used in local implementations: NOT-SND-05: Nationally defined event types MUST be used where appropriate Where a suitable NotificationEventType and NotificationEventSubtype exists in the published ITK vocabularies, this MUST be used. It SHOULD however also be possible to include locally agreed event types and subtypes where no suitable nationally agreed type exists. The subject of the notification (i.e. the patient) must be clearly identified in the message, in a way that is suitable for matching with patient records in various clinical systems, including those that do not use an NHS number (e.g. ambulance services who may want to match against addresses): NOT-SND-06: Appropriate patient identifiers MUST be included The notification MUST include basic patient demographic information, including Surname, Gender, Date of Birth, House Number and Postcode. NOTE: The notification MUST also include a traced NHS number where one is available in the sending system (as per requirement MOD-AIG-09 within the additional module requirements related document 5). A notification is intended primarily as a for information communication to augment existing care provision: NOT-SND-07: Notifications MUST not be used to transfer care or report errors The sending of a notification MUST NOT be used as a mechanism for transferring care of a patient to the recipient, or to communicate technical errors. If there is a specific local use-case that requires that a human acknowledges that a notification has been received, an ITK business acknowledgement MAY be used for this, but this should only be used when an agreement exists between the sender and the recipient as to the implications of receiving or not receiving an acknowledgement, what would trigger the acknowledgement, and what it actually means in a business context. Where a business acknowledgement has been requested in the absence of such a local agreement, the recipient may return an error (see NOT-REC-03 below). NOT-SND-08: Notifications MAY request business acknowledgement If there is a specific local use-case, and local agreement between the sender and receiver, the sender MAY request a business acknowledgement for the notification. This will use the ITK Handling Specifications. Crown Copyright 2013 Page 11 of 21

12 Note: The ITK handling specifications are defined within the Addressing and Routing Requirements document (related document 3). Notifications are expected to provide real-time information about patient events: NOT-SND-09: Notifications MUST be sent within an agreed timeframe Where a system is configured to send a notification of an event, the notification MUST be sent within a timescale agreed with the local organisation (for example within one minute of the system recording / being aware that the event has occurred). Crown Copyright 2013 Page 12 of 21

13 2.4 Notification Sender Requirements Links to Supporting Documents A notification contains minimal information about an event, but will generally also provide a mechanism for the recipient to obtain further information. This may include one or more of: Document ID / Document Set ID URLs To support Get Document To support one or more of: Click-Through to other system Direct HTTP GET of document NOT-LNK-01: Notifications SHOULD provide document identifiers Where the sending system is able to provide a document identifier and document set identifier, it SHOULD be included. This may be an identifier for an actual document, or may be an identifier that can be used to generate a document on-demand when another system requests it. The document identifier MUST relate to the document version at the time of the event the notification pertains to. The document set identifier MUST also be provided: this is an identifier for the set of all versions of the document, such that the latest version of the document can be requested regardless of when the notification was sent. NOT-LNK-02: Notifications SHOULD support click-through Where the sending system supports click-through functionality to view additional information about the notification, any notifications generated SHOULD provide a URL to allow access to that information. The appropriate NotificationURLType defined in the published ITK vocabulary should be used to indicate that it is a URL for remote system access. NOT-LNK-03: Notifications SHOULD provide document URLs Where the sending system allows an associated document to be retrieved electronically via a simple HTTP(S) GET request, the URL for the document SHOULD be included. The appropriate NotificationURLType defined in the published ITK vocabulary should be used to indicate whether the URL is for the latest version of the document or the version of the document at the time of the event the notification pertains to. Crown Copyright 2013 Page 13 of 21

14 2.5 Notification Sender Requirements Document Metadata In addition to providing a URL and/or identifier that can be used to retrieve a document, there is a need to provide some additional metadata about the document, to allow the notification recipient system to decide what actions to take. The specification contains a NotificationDocumentType vocabulary to identify the type of document from a business perspective (e.g. End of Life Care Co-Ordination Document, LTC Personalised Care Plan, etc). The ITK vocabulary should be used where a matching document type exists, but locally defined document types can also be used if required (see the Notifications Domain Message Specification for details of the document types in this vocabulary related document 9). The message can also contain a DocumentFormatType which identifies the format of the document (e.g. PDF, Word, HL7v3 CDA, etc): NOT-FMT-01: Document formats MUST use MIME types Where a DocumentFormatType is specified in a notification, this MUST be a standard MIME type as defined in RFC2046 (related document 7). Where the document is a HL7 CDA document, the MIME type MUST be specified as text/xml, with the specific type of CDA document defined in the profile ID field. The specific document template (including the version and specific configuration of that template) should be specified in the Profile ID field: NOT-FMT-02: The document template SHOULD be specified using a ProfileID Where a CDA document is being referenced from a notification, the ProfileID MUST be provided to indicate the specific template that the CDA document conforms to. This will match the ProfileID that would be provided in the distribution envelope when that document is sent in an ITK message (see the messaging architecture requirements related document 2). A ProfileID MAY also be used to specify locally-defined document profiles, and may also be used for non-cda documents where a local agreement has been reached over the composition of such local ProfileIDs. Crown Copyright 2013 Page 14 of 21

15 2.6 Notification Receiver Requirements General All messages should be acknowledged at a system level by the receiving system: NOT-REC-01: Notifications MUST be acknowledged by receiving system When a notification is received in a system, the receiver system must acknowledge back to the sender that the message was received. This does not require that the notification has been acted upon simply that it was received by the system. In certain cases, the sender of the recipient may request a business acknowledgement be returned. This is subject to agreement between the sender and receiver as to the meaning of the business acknowledgement. NOT-REC-02: A business acknowledgement SHOULD be returned if requested When a notification is received that requires a business acknowledgement, the receiving system SHOULD allow for an acknowledgement to be returned to the sender once a recipient has viewed the notification. The precise conditions for when this acknowledgement is returned MUST be defined and agreed with the local sending and receiving organisations. In cases where there is no agreement between the sending and receiving organisations as to the conditions and meaning of a business acknowledgement, or it is not possible to acknowledge the notification for any reason, the receiver can return an error to the sender: NOT-REC-03: Where business acknowledgement is not possible, and error MAY be returned Where a receiving system cannot support returning a business acknowledgement, the system MAY return an error to the sender, specifying that an acknowledgement is not possible. This would take the form of an ITK Business NACK (i.e. a Business Acknowledgement containing a DetectedIssueEvent). This refusal to return a business acknowledgement may be because there was no agreement in place between the two parties in advance, and therefore the meaning of such an acknowledgement could not be relied upon. It is also possible that an organisation may not want to support this behaviour at all due to the potential complexity in establishing and governing such agreements between senders and receivers in which case they may choose to return this error for any notification that requests a business acknowledgement. Crown Copyright 2013 Page 15 of 21

16 2.7 Notification Receiver Requirements Configurable Behaviours There is a need for systems receiving notifications to have flexible configurable rules to allow for a variety of actions to be performed on receipt of different types of notifications. This is important to avoid notification overload, which could occur if all notifications require human action to be processed: NOT-BEH-01: Notification handling MUST be configurable A receiving system MUST allow the behaviour for handling notifications to be configurable for an individual user or group of users, and should have sensible default behaviours as agreed with the local organisation. NOT- BEH-02: Notification handling SHOULD be driven by configurable criteria Configurable system behaviours for handling notifications SHOULD allow different behaviours for different event types, specific senders, or other criteria as agreed with the local organisation. NOT- BEH-03: Notification handling MAY differ for specific patient cohorts For specific users or workgroups within a system, there MAY be the capability to specify certain patients, or patient cohorts for whom they want a different notification handling behaviour. This should be easy to maintain by suitably trained users. NOT- BEH-04: Multiple notification behaviours SHOULD be supported The system SHOULD provide multiple configurable system behaviours for handling notifications, which could include: - Adding a flag or note against the patient's record - Adding a task to a user or team's work list or inbox - Actively notifying the user (either in the system or via SMS/ ) NOT- BEH-05: Unrecognised notification event types SHOULD be handled A system receiving a notification for an event type it does not understand MUST provide default behaviour to ensure a human is able to review the notification and act upon it if required. Crown Copyright 2013 Page 16 of 21

17 2.8 Error Scenarios The below table summarises some of the possible error scenarios relating to the sending and receiving of ITK notifications, with some guidance on how each should be handled: Error Type Potential Error Scenario Technical Failure 1 System error at recipient Malformed or Invalid request Recipient system does not understand message type Validation Business Process Issues Connection drop/timeout Recipient does not recognise event type Notification sent to wrong recipient Patient not known in recipient system Business acknowledgement requested but recipient is unable to verify receipt. Business acknowledgement requested and recipient wants to indicate that they have rejected the notification and not acted on it. Recommended Action Error handling will be specific to transport and interaction pattern. For Web Services, this could be a HTTP error or a SOAP Fault see the Web Services Transport Specifications (related document 6). For DTS see the DTS Transport Specification (related document 5). In some cases, where the message can be processed and a meaningful error can be sensibly generated providing more information, an ITK Infrastructure NACK may be used. Sender system to handle, and may retry. See requirement COR-REL-02 within the messaging architecture requirements (related document 2) No error returned. Recipient to handle accordingly (see requirement NOT-BEH-05 above) No error returned. Recipient to handle accordingly preferably by contacting the sender to inform them of the error so they can update their local directory/address book. No error returned. Recipient to handle accordingly options could be: Create new skeleton record for patient automatically and import/attach information from message Store message for human checking/matching Store message in a queue for matching against future patient registrations (i.e. trigger appropriate behaviour when patient is registered). Use a Business Acknowledgement with a DetectedIssueEvent to return error (see requirement NOT-REC-03 above). Use a Business Acknowldgement with a DetectedIssueEvent to return error (see requirement NOT-REC-03 above). 1 Note: In a multi-hop scenario, errors passed back via intermediary middleware will be transformed into an ITK Infrastructure NACK. Crown Copyright 2013 Page 17 of 21

18 3 Appendix A Example Notification Message The below example shows how a notification message sent over an ITK web service transport might look on-the-wire. The actual HL7v3 notification payload is defined in the notification DMS, which also contains an example of the serialised payload this has not been reproduced here to allow DMS changes to be made independently of this document: <?xml version="1.0" encoding="utf-8"?> <!-- Overall SOAP message as defined in the Web Services Transport Specification Document --> <!-- WSDL for the SOAP message is provided in the Notification Domain Message Specification --> <soap:envelope xmlns:soap=" xmlns:wsa=" xmlns:wsnt=" xmlns:itk="urn:nhs-itk:ns:201005"> <soap:header> <!-- The MessageID field MUST be populated with a unique uuid for each message instance - may differ from IDs used in the SOAP body --> <wsa:messageid>498fea e2-b005-cb431dafbc8f</wsa:messageid> <! As per the soapaction defined in the WSDL see WS-ADR-04 in the Web Services Transport Specification --> <wsa:action>urn:nhs-itk:services:201005:sendeventnotification-v1-0</wsa:action> <!-- URL of endpoint this message is being sent to --> <wsa:to> <!-- This example assumes no header signing, so no wsse:security element, use TLS MA instead to secure interaction --> <! No need for a from element see WS-ADR-05 in the Web Services Transport Specification --> <!-- The ReplyTo is only required for asynchronous invocation see WS-ADR-06 --> <!-- The RelatesTo is only required for asynchronous invocation see WS-ADR-07 --> </soap:header> Crown Copyright 2013 Page 18 of 21

19 <soap:body> <itk:distributionenvelope xmlns:xsi=" xmlns:itk="urn:nhs-itk:ns:201005"> <!-- The service name is the SOAP service name as defined in the WSDL included with the DMS (see COR-DEH-01 in the Messaging Architecture Requirements) --> <!-- The tracking UUID for the end-to-end request (see COR-DEH-02 in the Messaging Architecture Requirements) --> <itk:header service="urn:nhs-itk:services:201005:sendeventnotification-v1-0" trackingid="2d37d9ca c7-a159-f33d5a914eb5"> <!-- MANDATORY: Manifest lists payloads - see the Messaging Architecture Requirements Document for details --> <itk:manifest count="1"> <!-- The profile ID is defined within the DMS (Message Definitions > Configuration Profiles) --> <!-- The manifestitem id is a uuid that links the manifest item with the payload item in the body --> <itk:manifestitem id="uuid_808a967-49b2-498b-ad75-1d7a0f1262d7" mimetype="text/xml" profileid="urn:nhs-en:profile:eventnotification-v1-0" base64="false" compressed="false" encrypted="false"/> </itk:manifest> <!-- OPTIONAL: Address list contains all recipient logical addresses - see the Addressing and Routing Requirements Document for details --> <itk:addresslist> <itk:address uri="urn:nhs-uk:addressing:ods:x0912"/> </itk:addresslist> <!-- OPTIONAL: Audit identity of the sender - see the Addressing and Routing Requirements Document for details --> <itk:auditidentity> <itk:id type=" " uri="urn:nhs-uk:identity:cfh:architecture:handcrafted:qippdtteam"/> </itk:auditidentity> <!-- OPTIONAL: Sender address - see the Addressing and Routing Requirements Document for details --> <itk:senderaddress uri="urn:nhs-uk:identity:cfh:architecture:handcrafted:qippdtteam"/> Crown Copyright 2013 Page 19 of 21

20 <!-- OPTIONAL: Handling specifications - see the Addressing and Routing Requirements Document for details --> <itk:handlingspecification> <!-- Business acknowledgement requested, only to be used where local agreement exists between parties --> <itk:spec value="true" key="urn:nhs-itk:ns:201005:ackrequested"/> <!-- OPTIONAL: Interaction ID as defined in the Domain Message Specification ITK Implementation tab --> <itk:spec value="urn:nhs-itk:interaction:primaryrecipienteventnotification-v1-0" key="urn:nhs-itk:ns:201005:interaction"/> </itk:handlingspecification> </itk:header> <itk:payloads count="1"> <!-- Payload ID will match the ID in the manifest --> <itk:payload id="uuid_808a967-49b2-498b-ad75-1d7a0f1262d7"> <!-- The OASIS WS-BaseNotification metadata is the first thing in the payload --> <wsnt:notify> <wsnt:notificationmessage> <!-- The content of the below should be as per the OASIS standard, and is not constrained within the current ITK release --> <!-- OASIS define some options attributes that could be used to manage topics and subscriptions: 1) A SubscriptionReference - An EndpointReference to the Subscription that is associated with the Notify message 2) A Topic describing exactly one Topic, which MUST be the Topic that is associated with the Notification. This element describes the Topic that matched to a subscription, causing the NotificationProducer to send the Notify message to the NotificationConsumer. 3) A ProducerReference - An EndpointReference to the NotificationProducer that produced the Notification artefact --> Crown Copyright 2013 Page 20 of 21

21 <!-- This is the element defined in the OASIS standard to contain the actual notification payload --> <wsnt:message> <!-- HL7v3 Notification payload as defined in Notification Domain Message Specification Note: The actual HL7v3 payload has not been reproduced here, but an example can be found within the Notification Domain Message Specification. --> </wsnt:message> </wsnt:notificationmessage> </wsnt:notify> </itk:payload> </itk:payloads> </itk:distributionenvelope> </soap:body> </soap:envelope> Crown Copyright 2013 Page 21 of 21