Difference between revisions of "201709 Consumer Centered Data Exchange"
Line 132: | Line 132: | ||
<Consent xmlns="http://hl7.org/fhir"> | <Consent xmlns="http://hl7.org/fhir"> | ||
<id value="[id from api]"/> | <id value="[id from api]"/> | ||
− | <text> | + | <text> // as appropriate // </text> |
− | <status value="active"/> | + | <status value="active"/> // can only perform $getToken on active consent statements // |
− | <patient> | + | <patient>// patient data to be shared //</patient> |
− | <period> | + | <period>// optional period //</period> |
<dateTime value="[optional]"/> | <dateTime value="[optional]"/> | ||
<consentingParty> | <consentingParty> | ||
− | + | // | |
text/code description of who's going to be granted access. | text/code description of who's going to be granted access. | ||
This is useful for describing the recipient, but won't have | This is useful for describing the recipient, but won't have | ||
any computed meaning | any computed meaning | ||
− | + | // | |
</consentingParty> | </consentingParty> | ||
− | <organization> | + | <organization>// good to fill this out for consumption, but not important //</organization> |
<policyRule value="http://hl7.org/fhir/ConsentDefinition/simple-oauth"> | <policyRule value="http://hl7.org/fhir/ConsentDefinition/simple-oauth"> | ||
− | <purpose> | + | <purpose> // optional but not processed //</purpose> |
− | <dataPeriod> | + | <dataPeriod>// optional, enforced if present //</dataPeriod> |
− | <data> | + | <data> // don't use this //</data> |
<except> | <except> | ||
− | + | // the definition of http://hl7.org/fhir/ConsentDefinition/simple-oauth is | |
that only this consent statement is granted access. Anything else is | that only this consent statement is granted access. Anything else is | ||
− | granted access by exception | + | granted access by exception // |
<type value="permit"/> | <type value="permit"/> | ||
− | + | // not used <period/>, <actor/> // | |
<action> | <action> | ||
− | + | // this consent grants the right to access data // | |
<coding> | <coding> | ||
<system value="http://hl7.org/fhir/consentaction"/> | <system value="http://hl7.org/fhir/consentaction"/> | ||
Line 162: | Line 162: | ||
</coding> | </coding> | ||
</action> | </action> | ||
− | + | // not used <securityLabel/>, <purpose/> // | |
− | + | // repeat class for each Smart on FHIR scope // | |
<class> | <class> | ||
<system value="http://smarthealthit.org/fhir/scopes"/> | <system value="http://smarthealthit.org/fhir/scopes"/> | ||
<code value="[scope value e.g. Patient/read]"/> | <code value="[scope value e.g. Patient/read]"/> | ||
</class> | </class> | ||
− | + | // not used <code/>, <dataPeriod/>, <data/> // | |
</except> | </except> | ||
</Consent> | </Consent> | ||
+ | |||
Notes: | Notes: |
Revision as of 05:19, 10 June 2017
Consumer Centered Data Exchange
Submitting WG/Project/Implementer Group
FHIR Product Director, in association with Society for Participatory Medicine, MIHIN, NATE, DXC. Interested committees: FHIR-I, CBCC, Security, PA, PC, OO
Justification
In the connectathon process, we've tested narrow scenarios around data exchange, but interest is growing quickly in understanding what issues arise around the wide area testing across enterprises, and including the patient directly, and understanding what - if anything - the main specification or the US core IG should say about them
Proposed Track Lead
Grahame Grieve (but mentoring someone to take over after this)
Expected participants
NATE MIHIN DXC (others: add your self here!)
Scenario
Paul is a VA beneficiary living in Alaska. Because of the remoteness of his location, there aren’t a lot of specialists at VA facilities for him to see. These get outsourced to civilian specialists, so there is a need to transfer information from the specialists back to the patient's VA record.
Paul would like an app that allows him to authorize and cause relevant EMR data to be exchanged between the VA and specialist systems.
Assumption: for this connectathon stream, we will build on the Argonaut interface - that is, a pull of the data from an EMR that provides an Argonaut based patient portal.
Roles
- Client application developer : the client application that allows Paul to authorise data transfer
- Source EMR system: the provider of data that will be made available
- Target EMR system: the VA or equivalent system that will acquire the data
Authorization pattern
There are 4 possible patterns for Authorising/Managing the data flow
- Application Managed API
- Consent based tokens
- Full UMA
- Direct-based Push
1. Application Managed API
Data is made available by the normal Smart-on-FHIR interface that is, an Argonaut/S4S interface. In this scenario:
- Paul logs into the target EMR app (mobile/website), and informs the ap that he wants to connect it to the source EMR (how this is done is outside the scope of the connectathon)
- The target EMR app (re)directs Paul to the authorization URL on the source EMR
- Paul authorises the application as he wants
- the target EMR makes requests of the source system in an ongoing fashion per Smart-on-FHIR
- Paul connects to the source EMR to revoke his authorization when he wants the data flow to end
This scenario requires Paul to know the URLs for both source and target, and to deal with multiple applications, and for trust relationships to exist in the background between the source and target.
Note: there is no new API/interface in this arrangement - all of this is as described today, with additional application work.
2. Consent based Smart-On-FHIR
Data is made available by the normal Smart-on-FHIR interface that is, an Argonaut/S4S interface, with a consent layer. In this scenario:
- Paul authorises an app to the source EMR (standard Smart-On-FHIR)
- Paul posts a Consent resource to the server, or choose an existing consent statement
- Paul asks the source server for an API token based on the consent (see 'Acquiring an API token' below)
- Paul authorises with the target server, and gives it the API token (see 'Providing API token' below)
- the target EMR makes requests of the source system in an ongoing fashion using the API token
- Paul can revoke the authorise by revoking the token (see 'Revoking an API token' below)
This scenario requires Paul to know the URLs for both source and target, and to have apps authorized to both of them (could be the same app) but he doesn't have to deal with multiple applications, and trust relationships between them are not required
3. Full UMA
Data is made available by the normal Smart-on-FHIR interface that is, an Argonaut/S4S interface, but the authorization is delegated to a central server that manages the patient Authorization per the Heart/UMA specification
(todo: fill out more details)
Note: this builds on the argonaut interface by adding Heart support to it.
4. Direct-based Push
In this scenario, data is made available in the same format as Argonaut, but instead of a Pull based API, a push using Direct is used instead. In this scenario:
- Paul authorises an app to the source EMR (standard Smart-On-FHIR)
- Paul posts a Consent resource to the server, or choose an existing consent statement
- Paul asks the source server to start pushing the data based on the consent (see 'Starting push' below)
- the source system sends data to the target system using direct based push
- Paul can stop the sending through the app (see 'Stopping push' below)
This scenario requires Paul to know the URLs for the source, and the right direct email address for the target, and direct support must exist for the transfer between source and target. Paul doesn't have to have any relationship with the target, deal with multiple applications, and trust relationships between them are not required
Todo: is there interest in this?
Interfaces
Acquiring an API token
POST [base]/Consent/[id]/$getToken
Inbound Parameters:
- duration : Duration - how long the token should be good for. (optional: system default time limit if not provided)
Response: 200 ok with Parameters, or an error with an operation outcome. Outbound Parameters:
- token : string - a magic API Key that can be used to get data as specified in the Consent statement
- duration : Duration - maximum length of time that the token is going to be honored
The server returns an error if it is not able to understand the consent resource fully, or if it is not prepared to honor the consent statement (e.g. it probably won't agree to a consent that grants more than the granting application itself has been authorized to have). For the purposes of this connectathon, this is the suggest profile on the Consent Statement:
<Consent xmlns="http://hl7.org/fhir"> <id value="[id from api]"/> <text> // as appropriate // </text> <status value="active"/> // can only perform $getToken on active consent statements // <patient>// patient data to be shared //</patient> <period>// optional period //</period> <dateTime value="[optional]"/> <consentingParty> // text/code description of who's going to be granted access. This is useful for describing the recipient, but won't have any computed meaning // </consentingParty> <organization>// good to fill this out for consumption, but not important //</organization> <policyRule value="http://hl7.org/fhir/ConsentDefinition/simple-oauth"> <purpose> // optional but not processed //</purpose> <dataPeriod>// optional, enforced if present //</dataPeriod> // don't use this // <except> // the definition of http://hl7.org/fhir/ConsentDefinition/simple-oauth is that only this consent statement is granted access. Anything else is granted access by exception // <type value="permit"/> // not used <period/>, <actor/> // <action> // this consent grants the right to access data // <coding> <system value="http://hl7.org/fhir/consentaction"/></coding> </action> // not used <securityLabel/>, <purpose/> // // repeat class for each Smart on FHIR scope // <class> <system value="http://smarthealthit.org/fhir/scopes"/>
</class> // not used
, <dataPeriod/>, // </except> </Consent>
Notes:
- Systems that don't allow upload of consent, but allow $getToken, can do whatever consent they can understand - the client does not need to understand the consent details to call $getToken. This profile is a restricted form of the Consent resource that allows the user to consent using Smart on FHIR scopes
- this connectathon defines the special Smart on FHIR scope "Consent/token" that a client can ask for to indicate that it wishes to use the token management API described here in addition to read and/or write of Consent resources
- the token returned is a secret that gives access to a patient's health data. Anyone that gets the secret has access, so it must be handled accordingly.
Providing API token
A user users a token as prepared by $getToken above by the following operation:
POST [base]/$authorizeSource
Inbound parameters:
- token : string - a magic API Key that can be used to get data as specified in the Consent statement
- duration : Duration - maximum length of time that the token is going to be honored
- url: the URL for the Argonaut end-point of the application that will honor the token
- consent: id: the resource id of the consent statement on the source system. Required read-only access, so the target knows what is authorized (todo: is this necessary/ok?)
- patient : id: the resource id of the patient that the data is for (optional; default is the single patient associated with the Authorization - it's an error if there's more than one)
Response: 200 ok or an error with an operation outcome
Notes:
- the API token only grants access by the consent resource. Searching on Patient on the source system using this API token will only match the Consent.patient
- the token is used as a bearer token in the HTTP header (Authorization: bearer [token])
Revoking an API token
getting a list of tokens:
GET [base]/Consent/[id]/$listTokens
Response 200 ok with parameters:
- token - tuple
- token : string - previously issued token
- duration : Duration - how long the token is good for
Revoking a Token:
POST [base]/Consent/[id]/$revokeToken
Inbound parameters:
- token : string - a magic API Key that can be used to get data as specified in the Consent statement
Response: 200 ok or an error with an operation outcome
Note: any further use of the token will result in a 404 unauthorized response
Starting push
[todo]
Stopping push
[todo]