Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update README.md #1

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Update README.md #1

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
28dd16a
Update README.md
prasannakumarramani Oct 7, 2024
fd7f18f
Update send-appointment-notification.sh
prasannakumarramani Nov 12, 2024
6b74166
Update README.md
prasannakumarramani Nov 12, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
181 changes: 125 additions & 56 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -197,75 +197,144 @@ Alternatively, you can also find your Subscription ID in any subscription notifi

As noted above, we currently support only the `id-only` payload type. This means that events will contain a reference to the focus resource related to the event, but you will need to call back to a FHIR R4 or proprietary athenahealth API endpoint if you want to retrieve the latest content for that resource. While this introduces an extra step, it also reduces the risk of accidental PHI exposure by keeping all access control at the athenahealth API layer. It also helps avoid some ordering-related gotchas (see also [Event Ordering](#event-ordering) below).

In addition to the focus resource ID, some events MAY also contain additional context such as the related Patient ID and/or Department ID (see example below).

As per the Subscriptions R5 Backport IG, the first entry in each notification Bundle will always be a SubscriptionStatus resource which contains metadata about the Subscription associated with the event as well as metadata about the event(s) contained in the Bundle (see `entry[0].resource.notificationEvent[*].focus` below). At present this will be the only entry in the Bundle since `full-resource` payload is not supported at this time.
As per the Subscriptions R5 Backport IG, the first entry in each notification Bundle will always be a SubscriptionStatus resource which contains metadata about the Subscription associated with the event as well as metadata about the event(s) contained in the Bundle (see `entry[0].resource.notificationEvent[*].focus` below). The second entry will be `AuditEvent` resource which will have information about the event. Additional Detail of the event would be part of the `extension[]` array. Note that extensions would be different for different events.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wouldn't say "second entry" here because we want to leave open the expectation that a single Bundle may contain multiple events. I would rephrase along these lines:

The Bundle will also contain one AuditEvent resource corresponding to each entry in the entry[0].resource.notificationEvent array. This resource captures some additional metadata about the event such as the user/agent whose action triggered the event as well as topic-specific extensions (where applicable) with additional context such as the related Patient, Department, etc. For a list of which extensions are provided for each subscription topic, see Subscription Topics below.

(and we should add those details below)

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@prasannakumarramani we should also update the example payloads in the sample code (see https://github.com/athenahealth/aone-fhir-subscriptions/blob/main/samplecode/java/send-appointment-notification.sh for example) to include the new payload structure, i.e. extensions instead of additionalContext.


The `entry[0].resource.notificationEvent` array MAY contain multiple entries if the platform has batched multiple events for this SubscriptionTopic into a single notification. The length of this array will always match the value of `entry[0].resource.eventsInNotification`.

Example request that would be sent to your webhook for a `Patient.update` event notification:
Example request that would be sent to your webhook for a `Appointment.schedule` event notification:
```
curl --request POST https://example.org/your-webhook \
--header 'X-Hub-Signature: sha256=ca876e76c...' \
--data-raw '{
"resourceType": "Bundle",
"id": "3945182f-d315-4dbf-9259-09d863c7e7da",
"type": "history",
"meta": {
"profile": ["http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-subscription-notification"]
"resourceType": "Bundle",
"id": "511f8793-8929-3be9-83ef-37e948669cc8",
"meta": {
"profile": [
"http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-subscription-notification"
]
},
"type": "history",
"timestamp": "2024-09-30T10:01:34.857+00:00", // Note: this is notification timestamp
"entry": [
{
"fullUrl": "urn:uuid:e26e3853-669e-4440-81d9-8c37a0bf22c7",
"resource": {
"resourceType": "SubscriptionStatus",
"id": "e26e3853-669e-4440-81d9-8c37a0bf22c7",
"status": "active",
"type": "event-notification",
"eventsSinceSubscriptionStart": "1",
"eventsInNotification": 1,
"subscription": {
"reference": "Subscription/8a5ce763-4e86-30d2-acbe-80f05d26c633"
},
"notificationEvent": [
{
"id": "cc4cddb7-98f3-33f7-96f4-e5b7f4314748", // Unique UUID for the event
"eventNumber": "1",
"timestamp": "2022-04-02T18:11:33.000+00:00", // Timestamp of the event
"focus": {
// FHIR reference (if available)
"reference": "Appointment/a-432.123",
// Non-FHIR proprietary API reference (if available)
"identifier": {
"system": "urn:athenahealth:athenanet:appointment:432",
"value": "123"
}
}
}
],

"topic": "https://api.fhir.athena.io/fhir/r4/SubscriptionTopic/TestResource.connection-check"
},
"request": {
"method": "GET",
"url": "Subscription/8a5ce763-4e86-30d2-acbe-80f05d26c633/$status"
},
"response": {
"status": "200"
}
},
"timestamp": "2021-03-31T16:20:01.123Z", // Note: this is notification timestamp - see below for event timestamp
"entry": [
{
"fullUrl": "urn:uuid:c144782b-da2f-4125-a9e2-9fa4b9085a40",
"resource": {
"resourceType": "SubscriptionStatus",
"id": "c144782b-da2f-4125-a9e2-9fa4b9085a40",
"status": "active",
"type": "event-notification",
"eventsSinceSubscriptionStart": "1",
"eventsInNotification": 1,
"subscription": {
"reference": "Subscription/a9c3784c-9f56-4b32-95b0-882868d39e58"
{
"fullUrl": "urn:uuid:cc4cddb7-98f3-33f7-96f4-e5b7f4314748",
"resource": {
"resourceType": "AuditEvent",
"id": "cc4cddb7-98f3-33f7-96f4-e5b7f4314748", // Unique UUID for the event
"meta": {
"versionId": "0" // Version of the Event
},
//Extensions give extra information about the event
"extension": [
//Department ID associated with the Appointment
{
"url": "https://fhir.athena.io/StructureDefinition/ah-department",
"valueReference": {
"reference": "Organization/a-432.Department-123444"
}
},
"topic": "https://api.platform.athenahealth.com/fhir/r4/SubscriptionTopic/Patient.update",
"notificationEvent": [
{
"eventNumber": "1",
"id": "cb6cc377-ee38-31ba-9482-f93f821cd169", // Unique UUID for the event
"timestamp": "2021-03-31T16:20:12.000Z", // Timestamp of the event
"focus": {
// FHIR reference (if available)
"reference": "Patient/a-432.E-528595",

// Non-FHIR proprietary API reference (if available)
"identifier": {
"system": "urn:athenahealth:athenanet:patient:432",
"value": "528595"
}
},
"additionalContext": [
{
"reference": "Organization/a-432.Department-123",
"identifier": {
"system": "urn:athenahealth:athenanet:department:432",
"value": "123"
}
}
]
//Patient ID associated with the Event
{
"url": "https://hl7.org/fhir/5.0/StructureDefinition/extension-AuditEvent.patient",
"valueReference": {
"reference": "Patient/a-432.E-123"
}
},
//Chart Sharing Group ID associated with the Event
{
"url": "https://fhir.athena.io/StructureDefinition/ah-chart-sharing-group",
"valueReference": {
"reference": "Organization/a-432.CSG-12345"
}
]
}
],
"type": {
"system": "https://fhir.athena.io/CodeSystem/SubscriptionTopic",
"code": "Appointment.schedule"
},
"request": {
"method": "GET",
"url": "Subscription/a9c3784c-9f56-4b32-95b0-882868d39e58/$status"
"recorded": "2022-04-02T18:11:33Z",
"agent": [
{
"who": {
"identifier": {
"value": "Athena" // Agent who caused the event. Could be user or a an API key
}
},
"requestor": true,
"location": {
"reference": "Organization/a-432.Department-1234" // The Location where the change has happened
}
}
],
"source": {
"observer": {
"reference": "Organization/a-1.Practice-432" // Context where the change has happened
}
},
"response": {
"status" : "200"
}
"entity": [
{
"what": {
//The following information is available in the focus reference as well
// FHIR reference (if available)
"reference": "Appointment/a-432.123",
// Non-FHIR proprietary API reference (if available)
"identifier": {
"system": "urn:athenahealth:athenanet:appointment:432",
"value": "123"
}
}
}
]
},
"request": {
"method": "GET",
"url": "Subscription/8a5ce763-4e86-30d2-acbe-80f05d26c633/$status"
},
"response": {
"status": "200"
}
]
}'
}
]
}'
```

Response expected from your webhook if received successfully:
Expand Down