Stream: subscriptions
Topic: email
Michele Mottini (May 05 2019 at 14:07):
This is what we send in an email notification:
<div xmlns='http://www.w3.org/1999/xhtml'><table style=\"border: 1px solid black;\"><tr style=\"border: 1px solid black;\"><th style=\"background-color: #bbbbff; border: 1px solid black;\">Name</th><th style=\"background-color: #bbbbff; border: 1px solid black;\">DOB and Age</th><th style=\"background-color: #bbbbff; border: 1px solid black;\">DOB</th><th style=\"background-color: #bbbbff; border: 1px solid black;\">Age</th><th style=\"background-color: #bbbbff; border: 1px solid black;\">Gender</th><th style=\"background-color: #bbbbff; border: 1px solid black;\">Demographic</th><th style=\"background-color: #bbbbff; border: 1px solid black;\">MRN</th><th style=\"background-color: #bbbbff; border: 1px solid black;\">Admit Date (Day)</th><th style=\"background-color: #bbbbff; border: 1px solid black;\">Admit Date</th><th style=\"background-color: #bbbbff; border: 1px solid black;\">Location</th><th style=\"background-color: #bbbbff; border: 1px solid black;\">Chief Complaint</th></tr><tr style=\"border: 1px solid black;\"><td style=\"\">Demoski, Fran</td><td style=\"\">09/05/1998 (20 yo)</td><td style=\"\">09/05/1998</td><td style=\"\">20 yo</td><td style=\"\">F</td><td style=\"\">09/05/1998 (20 yo F)</td><td style=\"\">123456781</td><td style=\"\">05/05/2019 (Day 1)</td><td style=\"\">05/05/2019</td><td style=\"\"></td><td style=\"\"></td></tr></table></div>
Michele Mottini (May 05 2019 at 14:21):
(basically a table with some details on each resource in the list)
Jenni Syed (May 05 2019 at 15:04):
So, if we were wanting to get to a more common behavior defined by the spec...
Jenni Syed (May 05 2019 at 15:04):
I feel like the spec is trying to handle 2 specific use cases:
- Human recipient
- Machine recipient
Jenni Syed (May 05 2019 at 15:05):
But there's no good way to define that described in the spec, and it leaves it up to the server to decide what to do. For example, @Grahame Grieve server adds the FHIR data as an attachement
Jenni Syed (May 05 2019 at 15:05):
The HAPI implementation sounded like it puts the FHIR resource in the body
Jenni Syed (May 05 2019 at 15:06):
and @Michele Mottini server produces nice human readable body only
Jenni Syed (May 05 2019 at 15:06):
Do we have any opinions on how to make this more predictable?
Jenni Syed (May 05 2019 at 15:06):
or for the subscriber to be able to specify some expectations?
Jenni Syed (May 05 2019 at 15:07):
(this is logged as GF#21286 )
Grahame Grieve (May 05 2019 at 15:29):
I'm going to defend my choice, naturally ;-) - can message human or machine...
Grahame Grieve (May 05 2019 at 15:29):
including by #Direct/Certificates
Jenni Syed (May 05 2019 at 18:19):
I think it's important to allow for both. I think the gotcha is that right now it doesn't describe how a server should achieve that so that a subscriber has consistent expectations
Jenni Syed (May 05 2019 at 18:20):
Or really the way a subscriber should indicate that a human or machine is watching
Michele Mottini (May 06 2019 at 17:02):
There is payload: text/html = human readable, application/fhir+json = machine
Lloyd McKenzie (Sep 09 2019 at 20:38):
Question from FHIR-I call: are there use-cases where you'd ever want a channel to deliver both - i.e. human readable and computable?
Lloyd McKenzie (Sep 09 2019 at 20:39):
Is the expectation that if the human-readable content is delivered that it would always be the resource narrative?
Josh Mandel (Sep 09 2019 at 20:41):
Connecting dots: @Gino Canessa note that @Rick Geimer will be at the connectathon on Subscriptions track and we can talk through requirements / desiderata.
Gino Canessa (Sep 09 2019 at 20:45):
From what I remember of the last time it was discussed on an Argonaut call, there were people expecting the resource and people expecting an email to the patient that they have new health data.
The idea that I've been mulling over is to offer guidance that it should be based off the contentType of the email... if you ask for an email with application/fhir+json, you are obviously expecting the resource while asking for a text/html message would expect something patient-facing. Can honor the payload types within that for more flexibility (e.g., patient email with full-resource vs. patient email with empty).
Was going to bring it up last call, but figured it would be easier to talk through in Atlanta.
Lloyd McKenzie (Sep 09 2019 at 21:34):
contentType is fine - if we only one one of the two. However if you want the human-friendly HTML and the JSON attachment, you'd need two contentTypes
Josh Mandel (Sep 09 2019 at 21:35):
Oh, that's fun -- so presentationContentType (which wouldn't be used by most channels; might be an extension) and a contentType. Or reversing the roles, a contentType and an attachmentContentType (which wouldn't be used by most channels; might be an extension).
Gino Canessa (Sep 09 2019 at 22:07):
I'm not sure I follow the use-case where an email would need to be patient-friendly AND needed the attachment which couldn't be handled by including a link to the resource, but:
-extensions could work (a la Josh)
-a mutlipart content type could work (e.g., multipart/message)
-a parameter could work (e.g., text/html;attach=fhir+json)
I was hoping to get a pass of some of this up prior to Atlanta, but I'm still unclear what people have been doing so far with it.
Lloyd McKenzie (Sep 09 2019 at 22:16):
In theory, a patient might want to receive something that made sense to them - and something they could suck into their phone. I have no clue if that's a "real" use-case though.
Rick Geimer (Sep 12 2019 at 18:56):
Yes, I will be at the Connectathon in the Subscriptions track.
Rick Geimer (Sep 14 2019 at 15:30):
Initial Connectathon discussion around email channel (track attendees, please review/correct if I got any of this wrong).
- All agree that sending the raw resource XML/JSON in the body of an email is bad. The body of the email should be for human facing content.
- If the payload is omitted, the server will send a server-specific text notification in the body of the email (i.e. "Subscription X was executed")
- We discussed the possibility of an extension to Subscription that would allow a client to specify the desired notification text.
- If payload.contentType is text/html, the XHTML content Resource.text will be sent in the body of the email.
- If payload.contentType is text/plain, the text equivalient of the XHTML content Resource.text will be sent in the body of the email.
- If payload.contentType is application/fhir+xml or application/fhir+json, the resource XML or JSON will be sent as an attachment to the email with a server specific notification in the email body (i.e. "Subscription X was executed")
- If you want both human facing content with an XML/JSON attachment, use something like this in payload.contentType: text/html;attach=application/fhir+json
Jenni Syed (Sep 14 2019 at 15:39):
I like everything I think but the last one so far. Struggling with what that means for the required mime binding, wondering if there's a better way.
Grahame Grieve (Sep 14 2019 at 15:40):
what's the issue with it?
Jenni Syed (Sep 14 2019 at 15:41):
the attach part isn't in the mime binding :)
Jenni Syed (Sep 14 2019 at 15:41):
In email, this would be done with multi-part mime. But the spec doesn't handle that as it is today
Gino Canessa (Sep 14 2019 at 15:42):
The issue we are discussing is that adding the parameter to the MIME type breaks the binding to the value set.
Latest idea is add another field for MimeParameters... would allow for things like asking for a zip file with a json in it
Grahame Grieve (Sep 14 2019 at 15:43):
it's the FHIR spec that's the problem?
Grahame Grieve (Sep 14 2019 at 15:44):
It certainly shouldn't prevent parameters ,but I can see that it does
Jenni Syed (Sep 14 2019 at 15:45):
It also feels awkward to me, but I'm not sure why (just a "smell" - may not be accurate, trying to absorb)
Josh Mandel (Sep 14 2019 at 18:05):
A couple of notes from this discussion:
-
Anytime we're talking about "Resource.text" we should make this plural, since a subscription notification can be about >1 event. And we should also say something about the case where a notification is about a deletion rather than an update to resource(s).
-
Re: e-mail bodies, I think trying to depend too much on semantics of the payload type is going to get us in trouble. We might do well to simplify into some explicit notion of what goes into the body, plus maybe a standard extension to specify what goes in the attachment.
Josh Mandel (Sep 14 2019 at 18:19):
Use cases from @Rick Geimer , for email channel type:
-
Subscribing to updates on "knowledge distribution artifacts," e.g. a PlanDefinition with a series of value sets that get updated over time. Here, when a new emerging condition gets added to trigger codes ValueSet, a bunch of systems want to know this ValueSet has been updated. Some people want to receive this update as an email (whether to handle manually or to feed into an automated processor). Here, we'd want the body to be human-readable and present; and attachments (optionally) with FHIR data.
-
HIE supports Direct messaging and wants to also get US Core clinical notes, subscribing to DocumentReference resources. Here, the attached FHIR data would be most important.
-
(May not need to support e-mail). Public health agencies want to subscribe to Conditions or Observations on a "watch list" (e.g., for reportable conditions).
Josh Mandel (Sep 14 2019 at 21:40):
And an update from Rick: at least one of the use cases above actually expects Direct protocol support, not regular e-mail.
Joel Schneider (Sep 15 2019 at 13:42):
Any thoughts about using encryption with regular e-mail? For cases requiring encryption, use Direct (or something similar)? S/MIME? PGP?
Sean McIlvenna (Sep 15 2019 at 13:58):
Grahame Grieve: it's the FHIR spec that's the problem?
Grahame Grieve: It certainly shouldn't prevent parameters ,but I can see that it does
Where does it limit mime-type properties from being used? All I see is this:
"The payload mimetype and content. If the payload is not present, then there is no payload in the notification, just a notification."
This doesn't say that mime-type properties can't be used...???
@Grahame Grieve
Sean McIlvenna (Sep 15 2019 at 14:00):
...must be referring to
The mime type to send the payload in - either application/fhir+xml, or application/fhir+json. The mime type "text/plain" may also be used for Email and SMS subscriptions.
Sean McIlvenna (Sep 15 2019 at 14:00):
The way that constraint is written seems weird to me...
SHALL X or Y.
MAY Z.
Sean McIlvenna (Sep 15 2019 at 14:01):
So we're saying this text is preventing us from using mime-type properties?
Sean McIlvenna (Sep 15 2019 at 14:03):
I would say that
"application/fhir+xml;attachment=true,bodyText=SOME TEXT"
still conforms to that constraint text...
In the above example, the mimetype of the payload IS application/fhir+xml
Sean McIlvenna (Sep 15 2019 at 14:04):
it just happens to have some properties with it as well
Grahame Grieve (Sep 15 2019 at 14:06):
All I see is this
right
Grahame Grieve (Sep 15 2019 at 14:07):
I was going by memory. But it doesn't say what I thought. Any valid mime type is ok including parameters
Sean McIlvenna (Sep 15 2019 at 14:07):
phew
Sean McIlvenna (Sep 15 2019 at 14:07):
was just working on modifications to HAPI to support mime-type parameters to indicate that the resource should be attached to the email instead of the body of the email
Sean McIlvenna (Sep 15 2019 at 14:08):
so, was worried I'd have to undo it all
Sean McIlvenna (Sep 15 2019 at 14:08):
lol
Sean McIlvenna (Sep 15 2019 at 14:08):
@Rick Geimer
Jenni Syed (Sep 15 2019 at 14:12):
Isn't there a required value set on Mime type? That doesn't include the full set of properties.
Sean McIlvenna (Sep 15 2019 at 14:25):
I haven't been able to find anything that says properties have to be specific keys/values
Sean McIlvenna (Sep 15 2019 at 14:26):
I found this:
pasted image
Sean McIlvenna (Sep 15 2019 at 14:26):
but, that just shows an example of a property... it doesn't say the property has to be X, Y or Z for given mime-types
Sean McIlvenna (Sep 15 2019 at 14:27):
if mime-type properties were enforced, I would think it would be easier to find a table of expected properties/values
Jenni Syed (Sep 15 2019 at 14:28):
So, the field has a required binding to: https://tools.ietf.org/rfc/bcp/bcp13.txt
Jenni Syed (Sep 15 2019 at 14:28):
which I don't think includes properties. But maybe this is a semantics thing and the mime binding is a mess? :)
Jenni Syed (Sep 15 2019 at 14:29):
https://www.iana.org/assignments/media-types/media-types.xhtml
Jenni Syed (Sep 15 2019 at 14:30):
that does list properties for some of the mimes...
Grahame Grieve (Sep 15 2019 at 14:31):
it's just 'any valid mime type', which includes properties, since their syntax is defined in bcp13
Jenni Syed (Sep 15 2019 at 14:33):
https://www.iana.org/assignments/media-types/application/fhir+json we're missing our fhirVersion
(waiting for Grahame to throw something towards me)
Grahame Grieve (Sep 15 2019 at 14:34):
yes I should. I just don't have the energy to get it updated for that
Sean McIlvenna (Sep 15 2019 at 15:08):
so, are we saying mime-type properties ARE ok, still?
Sean McIlvenna (Sep 15 2019 at 15:08):
further-more, any mime-type properties are OK?
(up to the implementation?)
Jenni Syed (Sep 15 2019 at 15:14):
In this case, the weirdness is that the mime type we're using (or considering using) doesn't have this as a property/it would be something we would be creating ourselves
Jenni Syed (Sep 15 2019 at 15:14):
But in general, yes, properties would be allowable
Grahame Grieve (Sep 15 2019 at 16:32):
we'll take it as read that fhirVersion is valid
Last updated: Apr 12 2022 at 19:14 UTC
