Actors, Roles & Data Scope
There are two parties for each exchange:
| Actor | Description | Alternative Names |
|---|---|---|
| Requesting Payer | The payer organization receiving data in an exchange transaction | Target, Client, "New" Payer |
| Responding Payer | The payer organization sharing data in an exchange transaction | Source, Server, "Old" Payer |
All exchanges are initiated by the Requesting Payer.
The PDex Implementation Guide supports two modes for data exchange:
Requesting data for a single member via the following request methods:
| Method | Type | Description |
|---|---|---|
Bulk export via $export | Asynchronous | Recommended for most use cases |
Real-time export via $everything | Synchronous | For immediate data needs |
| Standard FHIR queries | Synchronous | For individual resources |
Group-based exchange, also referred to as "bulk" exchange:
| Method | Type | Description |
|---|---|---|
$davinci-data-export | Asynchronous | Export data for multiple members in a Group |
Here is a short overview of the key activities part of any transaction and where Smile fits in. Implementation details for each are explored in other sections of this guide.
| Phase | Description | Primary Actor |
|---|---|---|
| Registration | Establish secure authentication credentials | Both payers |
| Opt-In | Members trigger the exchange by giving consent | Requesting payer |
| Requesting Data | Initiate exchange via $invoke-export | Requesting payer |
| Authentication and Authorization | Insert security credentials and validate access | Both payers |
| Patient Matching | Submit demographics and locate patient record | Both payers |
| Data Export | Export and transfer member health records | Both payers |
| Data Storage | Store and integrate retrieved records | Requesting payer |
| Phase | Smile CDR Role |
|---|---|
| Registration | Create OIDC definitions and Organization resources |
| Authentication | SMART Outbound Security module handles token management |
| Patient Matching | Execute $member-match with custom or default matching logic |
| Data Export | Perform $export or $everything operations |
| Data Storage | Store DocumentReference, create Provenance, transform and link resources |
These activities occur largely outside of Smile:
Prior to any exchange, two payer actors register their P2P applications with the primary objective of establishing secure authentication credentials. Payers may choose to create vetting processes through developer portals for processing applications.
While this process occurs largely outside of Smile CDR, registration artifacts may need to be created in Smile CDR software, such as OIDC client/server definitions and FHIR Organization resources.
Members trigger the exchange by giving consent to the Requesting Payer to retrieve their health records. This opt-in process, including delivering education materials, occurs outside of Smile CDR. Information gathered from the member about the other payer feeds into the next phase of the transaction.
Requesting Payers initiate exchanges via the $sdh.s2s.invoke-export operation, which automates the request and retrieval of data from the Responding Payer.
Note: This operation is currently supported only for single-member exchange.
$sdh.s2s.invoke-export operation inserts the necessary security credentials to request access to server-side resources.$sdh.s2s.invoke-export operation submits patient and coverage information to facilitate record location in the source server.$member-match (for single member) and $bulk-member-match (for multi member) operations to return matching patient record locations.Successful member match allows the requester to initiate a data export using the returned patient IDs. The $sdh.s2s.invoke-export operation makes a request on the bulk $export endpoint.
The Responding Payer configures Smile CDR to define the scope of resources to share, using the CMS mandate as its primary guide.
Once retrieved, records are stored in the repository through several stages:
This separation into distinct Patient compartments supports querying for only pre-existing data or collating pre-existing and imported records when other payers request member data.
| Data | DocumentReference field | Notes |
|---|---|---|
| Document creation date | DocumentReference.meta.lastUpdated | Timestamp |
| Document status | DocumentReference.status | Fixed value: current |
| Content type | DocumentReference.content.attachment.contentType | Fixed value: application/fhir+ndjson |
| Data | DocumentReference.content.attachment.data | Base 64 encoded Binary Resource. The original ndjson files are also Base 64 encoded in Binary.data field. |
| Data | Provenance field | Notes |
|---|---|---|
| Created resource | Provenance.target.reference | Reference to the created resource |
| Creation date | Provenance.recorded | Timestamp |
| Source payer | Provenance.agent.who.reference | Points to an Organization resource that represents the source payer. This will require: 1. An Organization resource has been created for the source payer on the target system, such as during registration 2. The coverage.payor field is properly configured |
| Target patient | Provenance.agent.onBehalfOf.reference | Reference to the target patient on behalf of whom the data was transmitted |
A tag of "migrated" is added to imported resources to clearly identify them as originating from an external payer system.
{
"meta": {
"tag": [
{
"system": "http://smilecdr.com/fhir/tags",
"code": "migrated",
"display": "Resource imported from external payer"
}
]
}
}
You are about to leave the Smile Digital Health documentation and navigate to the Open Source HAPI-FHIR Documentation.