1. Introduction

Alerts within the OpenHIE interoperability layer can be published and retrieved from a "Alert Repository" hosted by the IL. This service exposes a virtual "bucket" of alerts. Services "above the IL" and "below the IL" (that is infrastructure, and point of care) may use the Alert Repository to:

• Post (publish) alerts
• Query (poll) for alerts
• Deactivate alerts which have been acknowledged

This wiki article describes the "alert repository" as a series of interface requirements, and does not describe the mechanism used to store those alerts within implementations.

Use cases of this profile are:

1. An ICP which periodically checks patient profiles, in the course of its application logic, discovers that a clinical protocol is not being followed publishes a reminder alert to the attending clinician.
2. An administrative service that requires the .
3. TODO: Add more use cases here.

Mis-use cases of this profile:

1. Any alert which requires "real time" stoppage/modification of a clinical workflow. For example: In the course of prescribing a drug a decision support system discovers the patient has an allergy/intolerance to the prescribed drug.  

2. Actors / Transactions

2.1. Use Case Roles

2.2. Referenced Standards

HL7 Fast Healthcare Interoperability Resource (FHIR) DSTU 0.80
RFC4287 The Atom Syndication Format
RFC2616 IETF Hypertext Transfer Protocol - HTTP/1.1 
RFC3986 IETF Uniform Resource Identifier (URI): Generic Syntax

2.3. Interaction Diagram 

NB: Alert Repository should read "Alert Manager"

2.3.1. Alert Manager in the Context of the IL

This profile is intended to express the mechanism of alerting from the perspective of the Alert Publisher, Consumer and Manager. The IL is expected to expose the interface to the Alert Manager and perform any resolution of provider/patient/location identifiers contained within the received alerts prior to conveying them to the Alert Manager.

TODO: Add a sequence diagram showing alerts within the context of the IL

In the context of the IL and OpenHIE, the Alert Manager actor can be equated to the "IL" as the IL would be exposing the interface to its backing manager implementation.

The Alert Consumer in the context of OpenHIE would most likely be an edge system responsible for interpreting the structured alert from the Alert Manager and formatting it appropriately. For example, a clinical EMR system could format the message as an inbox item whereas an SMS package would represent the structured data as a text-message.

2.4. Publish Alert Message

This message represents an HTTP POST from the Alert Publisher actor to the Alert Manager actor containing a profiled FHIR Alert resource.

2.4.1. Trigger Events 

When the Alert Publisher actor wishes to make known to Alert Consumer actors, via the Alert Manager, some statement of clinical fact, administrative, or other message.

2.4.2. Message Semantics

The Publish Alert Message is conducted by the Alert Publisher by executing an HTTP POST against the Alert Manager's Alert Resource URL. The URL is formatted as:

http[s]://<authority>/<path>/Alert

This URL is configurable by the Alert Manager and is subject to the following constraints:

• The <authority> shall be represented as a host (either DNS name or IP address) followed optionally by a port.
• The Alert Manager may use the <path> to segregate its implementation of the actor from other REST-based services.
• The <path>, if present, represents the path from which all resources related to a Alert Manager are located (Conformance, Profile, and Alert) and shall not contain a '?'.

2.4.2.1. Content-Type HTTP Header

The Publish Alert Message shall contain a content-type HTTP header, the value of which shall be drawn from Table 2.4.2.1-1 and shall accurately represent the format of the message.

Table 2.4.2.1-1 - Content-Type

2.4.2.2. HTTP Payload

The payload of the HTTP request shall be an HL7 FHIR Alert resource (see http://hl7.org/implement/standards/fhir/alert.html) profiled as described in figure 2.3.2.2-1 and table 2.3.2.2-2.

If the Alert Publisher is incapable of producing a fully qualified URL to a particular resource referenced in the subject or author attributes (example: HIE doesn't expose or have a FHIR based Client Registry), then it shall represent them as contained resources (see http://www.hl7.org/implement/standards/fhir/references.html#contained) which shall contain, at minimum, the "identifier" attribute such that the Alert Manager can use an appropriate mechanism to identify the data for the resource.

2.4.2.2.1 Example

An example alert published instructing any provider to double check the patient's weight during their next care visit in FHIR JSON:

{
    "resourceType": "Alert",
    "contained": [
        {
            "resourceType": "Patient",
            "id": "Patient1",
            "identifier": [
                {
                    "use": "usual",
                    "system": "urn:oid:LOCAL IDENTIFIERS OID",
                    "value": "LOCAL IDENTIFIER"
                }
            ]
        },
        {
            "resourceType": "Device",
            "id": "Device1",
            "identifier": [
                {
                    "use": "usual",
                    "system": "urn:oid:OPENHIE DEVICES OID",
                    "value": "OPENHIE DEVICE ID"
                }
            ],
            "type": {
                "coding": [
                    {
                        "system": "local",
                        "code": "icp",
                        "display": "Integrated Care Pathways Workflow Host"
                    }
                ],
                "text": "ICP Host"
            },
            "manufacturer" : "OpenHIM",
            "model" : "v1.0"
        }
    ],
    "text": {
        "status": "generated",
        "div": "<div><b>From ICP-WHO-304:</b> Patient underweight for this stage of pregnancy, please double check weight next visit"
    },
    "category": {
        "coding": [
        {
            "system": "local",
            "code": "clinical",
            "display": "Clinical Alert"
        }],
        "text": "Clinical Alert"
    },
    "status": "active",
    "subject": {
        "reference": "#Patient1",
        "display": "Mosa M."
    },
    "author": {
        "reference": "#Device1",
        "display": "OpenHIM ICP"
    },
    "note": "Patient underweight for this stage of pregnancy, please double check weight next visit"
}

2.4.2.3. Targeting Alerts

The basic FHIR Alert resource may be a generic Alert about the patient (example: "Someone please verify the Patient's weight") or, for certain alert types, may need to be a targeted alert (example: "CHW X, please see patient Y because they haven't had an antenatal care visit in over 6 months"). In order to facilitate the latter use case, OpenHIE's the Alert Publisher shall convey any intended recipients of the alert in the extension "intendedRecipient" having extension "url" property of http[s]://<authority>/<path>/Profile/ohie-alert#intendedRecipient. The URL shall point to a valid profile definition hosted by the Alert Manager.

The intendedRecipient extension shall contain a value of type Resource and shall point to a Practitioner, Organization or Patient resource indicating the intended recipient of the alert is a provider of care, an entire organization, or patient respectively. The Alert Publisher shall include the referenced resource as a contained resource.

An example of the intendedRecipient extension is defined below:

{
    "resourceType": "Alert",
    "extension": [
        {
            "url": "http[s]://alert-manager/Profile/ohie-alert#intendedRecipient",
            "valueResource": {
                "reference": "#Recipient1",
                "display": "Christy CHW"
            }
        }
    ],
    "contained": [
        {
            "resourceType" : "Practitioner",
            "id" : "Recipient1",
            "identifier" : [
               {
                "use" : "usual",
                "system" : "urn:oid:LOCAL IDENTIFIERS OID",
                "value" : "LOCAL IDENTIFIER"
               }
            ],
            "telecom" : [ 
               {
                 "system" : "phone",
                 "value" : "+1-203-403-2095",
                 "use" : "work"
               }
            ]
        },
        ...
}

Additionally, the Alert Manager actor shall indicate support for the intendedRecipient extension within a Profile resource as illustrated below:

    "extensionDefn": [
        {
            "code": "intendedRecipient",
            "contextType": "resource",
            "context": ["Alert"],
            "definition": {
                "short" : "Intended recipient of the Alert",
                "formal" : "The practitioner, organization, or patient to whom the alert is specifically addressed",
                "min" : 0,
                "max" : "unbounded",
                "type" : [
                    {
                        "code" : "ResourceReference",
                        "profile" : "http://hl7.org/fhir/profiles/Patient"
                    },
                    {
                        "code": "ResourceReference",
                        "profile": "http://hl7.org/fhir/profiles/Practitioner"
                    },
                    {
                        "code": "ResourceReference",
                        "profile": "http://hl7.org/fhir/profiles/Organization"
                    }
                ]
            }
        }
    ]

2.4.3. Expected Behavior

Upon receiving a Publish Alert Message, the Alert Manager shall persist and/or forward the Alert in some manner appropriate to the particular implementation (for example, storing the resource to a MongoDB or forwarding to another alert service).

The Alert Manager may, if it deems necessary, enrich any details of the contained resource, and may store the resources for access via a fully qualified resource URL (as defined in the FHIR standard).

If the Alert Manager receives a Publish Alert Message formatted in a manner which it does not support (for example, submitting XML to a JSON only service) it shall respond with an HTTP 415 error code. Once the alert has been stored, and/or forwarded the Alert Manager shall respond with an HTTP 200 (OK) message.

The Alert Manager shall respond with an appropriate HTTP level 500 error code (server errors) if it was not able to persist or forward the message (for example, due to invalid message parameters). The error message shall be an HL7 FHIR OperationOutcome resource (see: http://www.hl7.org/implement/standards/fhir/operationoutcome.html) indicating the reason for the fault.

The Alert Manager shall only indicate a successful response if the Alert Manager can guarantee delivery of the received alert (i.e. the Alert Manager shall finish committing data to a persistent store prior to responding with OK).

2.5. Publish Alert Response Message

This message is used to acknowledge a Publish Alert Message and is sent from the Alert Manager to the Alert Publisher actor.

2.5.1. Trigger Events 

The Alert Publisher actor has completed the processing and, in the case of a valid message, persistence of an alert and wishes to convey an acknowledgement.

2.5.2. Message Semantics

The Publish Alert Response Message is an HTTP message containing:

• An HTTP status code (drawn from table 2.5.2-1 )
• A location header indicating the fully qualified URL where the Alert can be retrieved.
• An optional OperationOutcome resource indicating details of the processing
• An appropriate Content-type header indicating the format of the OperationOutcome resource (see Table 2.4.2.1-1)

The behaviors for which the following status codes are generated are listed in section 2.4.3.

Table 2.5.2-1 : Publish Alert Response Message HTTP Status Codes

 2.6. Query Alerts Message

This message represents an HTTP GET from the Alert Consumer actor to the Alert Manager actor for the purpose of querying for applicable Alerts.

2.6.1. Trigger Events 

When the Alert Consumer actor wishes to query for all known patient Alerts, it queries the Alert Manager.

2.6.2. Message Semantics

The Query Alert Message is conducted by the Alert Consumer by executing an HTTP GET against the Alert Manager's Alert Resource URL. The URL is formatted as:

http[s]://<authority>/<path>/Alert?<query>&format=<formatId>

This URL is configurable by the Alert Manager and is subject to the following constraints:

• The <authority> shall be represented as a host (either DNS name or IP address) followed optionally by a port.
• The Alert Manager may use the <path> to segregate its implementation of the actor from other REST-based services.
• The <path>, if present, represents the path from which all resources related to a Alert Manager are located (Conformance, Profile, and Alert) and shall not contain a '?'.
• The <query> represents a series of encoded name-value pairs representing the filter for the query specified in 2.6.2.1 as well as control parameters to modify the behavior of the Alert Manager such as response format.

2.6.2.1. Query Parameters

The Alert Consumer may supply and the Alert Manager shall be capable of processing all query parameters listed below. All query parameters should be appropriately encoded using RFC3986 percent encoding rules. Alert Managers may expose additional query parameters which fulfill site specific requirements, however these are out of scope for this resource profile.

_id Query Parameter

The _id query parameter can be used to query for an Alert having a specific resource identifier matching the specified value. This identifier is the local identifier assigned by the Alert Manager.

creationTime Parameter

The creationTime parameter filters results based on the time that the Alert was created in the Alert Manager. The Alert Manager shall, at minimum, support exact and interval matches (defined by FHIR date query parameters at http://hl7.org/implement/standards/fhir/search.html#date) and may support other types of date matching.

identifier Query Parameter

The identifier query parameter filters results based on one or more of the identifiers supplied in the Alert resource and may be used to find a specific instance of an Alert by identifier.

subject.identifier Query Parameter

The subject.identifier parameter filters results based on the identifier of the subject (or patient) for which the alert pertains. This can be used to find all alerts which belong to a particular patient and is of type token. For example, to find all Alerts related to a patient having a US social security identifier of 123456789 the query parameter would be represented as:

?subject.identifier=urn:oid:2.16.840.1.113883.4.1|123456789

author.identifier Query Parameter

The author.identifier parameter filters results based on the identifier of the author (device, patient or practitioner) which created the Alert. This can be used to find all alerts created by a particular actor and is represented as a token query parameter.

intendedRecipient.identifier Query Parameter

The intendedRecipient.identifier parameter filters results based on the identifier of the recipient to which the alert is addressed.

2.6.2.2. Populating Desired Response Format

The FHIR standard provides encodings for responses in either XML or JSON. Actors are expected to support either format, and the Alert Consumer actor shall indicate a desired response encoding vial the _format query parameter.

Table 2.6.2.2-1 - Desired Response Encoding

2.6.3. Expected Behavior

The Alert Manager shall return all alerts matching the query parameters supplied by the Alert Consumer. The Alert Manager shall respond to the query synchronously (i.e. on the same connection as was used to initiate the request). The Alert Manager shall bundle the matching Alerts within a FHIR Resource Bundle (see: http://www.hl7.org/implement/standards/fhir/extras.html#bundle) and shall return these results to the Alert Consumer actor.

If no Alerts were found matching the specified criteria, then the Alert Manager shall return a FHIR Resource Bundle with no matches.

If the Alert Manager was incapable of processing one of the query parameters supplied to it, it shall return an HTTP 400 (bad request) error and convey the parameter in error via an OperationOutcome Resource.