36.0.1System to System Data Exchange ModuleExperimental
This module is used to facilitate server to server operations.
The operations that this module supports are listed below.
36.0.1.1Payer to Payer
Patient data can be transferred from an old system to a new system in a payer-to-payer transfer.
Smile can be configured to act as both the old system (which will be called source from here on out) or the new system (which will be called target from here on out).
Our quick start guide provides configuration instructions for a basic setup.
36.0.1.2Invoke Export
The $sdh.s2s.invoke-export endpoint allows a health provider to kick off the process of a server-to-server exchange of patient records between 2 PDex compliant servers.
This operation initiates a payer-to-payer request for the target system. It orchestrates the following activities:
- Authentication and authorization with source system
- Querying
$member-matchoperation for patient match - Executing a bulk data export for matched members via the
$exportoperation - Storing and linking retrieved files to local patient record
- Creating a task resource that provides basic status on the
$invoke-exportoperation
36.0.1.2.1Request Payload for `$invoke-export`
| Name | Type | Cardinality | Description |
|---|---|---|---|
| export | Parameter | 1..1 | The input parameters to be used in the $export operation at the source. |
| memberMatch | Parameter | 1..1 | The input parameters to be used in the $member-match operation at the source. |
| localPatient | reference | 1..1 | The resource ID for the patient on the target server. Used by the system to integrate imported resources into the patient record. |
| sourceIssuerUrl | string | 1..1 | The URL documented in the issuer field of the OIDC server definition on the target. This is used to look up the definition and retrieve authentication credentials. |
This operation, if successful, will return with a status of 200 (OK) and a Content-Location pointing to a Task resource containing basic status information for the operation.
Because $export jobs can take a while to process, it's not advisable to query the Task resource more frequently than once a minute.
36.0.1.2.2Example
The following is an example of a payload for $invoke-export.
http://example.com/Patient/$sdh.s2s.invoke-export
{
"resourceType": "Parameters",
"parameter": [
{
"name": "export",
"resource": {
"resourceType": "Parameters",
"parameter": [
{
"name": "_outputFormat",
"valueString": "application/fhir+ndjson"
},
{
"name": "_type",
"valueString": "Patient, Observation, Person"
},
{
"name": "patient",
"valueReference": "Patient/M123"
}
]
}
},
{
"name": "sourceIssuerUrl",
"valueString": "http://localhost:9200/smartauth"
},
{
"name": "localPatient",
"valueReference": {
"reference": "Patient/P123"
}
},
{
"name": "memberMatch",
"resource": {
"resourceType": "Parameters",
"parameter": [
{
"name": "MemberPatient",
"resource": {
"resourceType": "Patient",
"id": "M123",
"identifier": [
{
"type": {
"coding": [
{
"system": "http://hl7.davinci.org",
"code": "MB"
}
]
},
"system": "http://oldhealthplan.example.com",
"value": "55678",
"assigner": {
"reference": "Organization/org2",
"_reference": {
"fhir_comments": [
"MB is passed from coverage card by new health plan."
]
}
}
}
],
"name": [
{
"use": "official",
"family": "Person",
"given": [
"Patricia",
"Ann"
]
}
],
"gender": "female",
"birthDate": "1974-12-25"
}
},
{
"name": "CoverageToMatch",
"resource": {
"resourceType": "Coverage",
"id": "cov1",
"text": {
"status": "generated",
"div": "<div xmlns=\"http://www.w3.org/1999/xhtml\">A human-readable rendering of the coverage</div>"
},
"contained": [
{
"resourceType": "Organization",
"id": "Organization/org2",
"name": "Old Health Plan",
"endpoint": [
{
"reference": "http://www.oldhealthplan.com"
}
]
}
],
"identifier": [
{
"system": "http://oldhealthplan.example.com",
"value": "OLD_IDENTIFIER"
}
],
"status": "draft",
"beneficiary": {
"reference": "Patient/M123"
},
"period": {
"start": "2011-05-23",
"end": "2012-05-23"
},
"payor": [
{
"reference": "Organization/org2"
}
],
"class": [
{
"type": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/coverage-class",
"code": "group"
}
]
},
"value": "CB135"
},
{
"type": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/coverage-class",
"code": "plan"
}
]
},
"value": "B37FC"
},
{
"type": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/coverage-class",
"code": "subplan"
}
]
},
"value": "P7"
},
{
"type": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/coverage-class",
"code": "class"
}
]
},
"value": "SILVER"
}
]
}
},
{
"name": "CoverageToLink",
"resource": {
"resourceType": "Coverage",
"id": "cov2",
"contained": [
{
"resourceType": "Organization",
"id": "Organization/org3",
"name": "New Health Plan",
"endpoint": [
{
"reference": "http://www.newhealthplan.com"
}
]
}
],
"identifier": [
{
"system": "http://newealthplan.example.com",
"value": "234567"
}
],
"status": "active",
"beneficiary": {
"reference": "Patient/P123"
},
"period": {
"start": "2020-04-01",
"end": "2021-03-31"
},
"payor": [
{
"reference": "Organization/org3"
}
],
"class": [
{
"type": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/coverage-class",
"code": "group"
}
]
},
"value": "A55521",
"name": "New Health Plan Group"
},
{
"type": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/coverage-class",
"code": "subgroup"
}
]
},
"value": "456"
},
{
"type": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/coverage-class",
"code": "plan"
}
]
},
"value": "99012"
},
{
"type": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/coverage-class",
"code": "subplan"
}
]
},
"value": "A4"
},
{
"type": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/coverage-class",
"code": "class"
}
]
},
"value": "GOLD"
}
]
}
},
{
"name": "Consent",
"resource": {
"resourceType": "Consent",
"status": "active",
"scope": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/consentscope",
"code": "patient-privacy"
}
]
},
"category": [
{
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/v3-ActCode",
"code": "IDSCL"
}
]
}
],
"patient": {
"reference": "Patient/P123"
},
"performer": [
{
"reference": "Patient/P123"
}
],
"policy": [
{
"uri": "http://hl7.org/fhir/us/davinci-hrex/StructureDefinition-hrex-consent.html#regular"
}
],
"provision": {
"type": "permit",
"period": {
"start": "2024-01-01",
"end": "2024-12-31"
},
"actor": [
{
"role": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/provenance-participant-type",
"code": "performer"
}
]
},
"reference": {
"identifier": {
"system": "http://hl7.org/fhir/sid/us-npi",
"value": "9876543210"
},
"display": "Old Health Plan"
}
},
{
"role": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/v3-ParticipationType",
"code": "IRCP"
}
]
},
"reference": {
"identifier": {
"system": "http://hl7.org/fhir/sid/us-npi",
"value": "0123456789"
},
"display": "New Health Plan"
}
}
],
"action": [
{
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/consentaction",
"code": "disclose"
}
]
}
]
}
}
}
]
}
}
]
}
36.0.1.3Member Match
The $member-match operation allows one health plan (target) to retrieve a unique identifier for a member from another health plan (source) using a member's demographic and coverage information. The identifier returned from the operation can then be used to perform subsequent queries and operations.
Please refer to the Smile CDR Payer to Payer Quickstart Guide to enable the $member-match operation on Smile CDR (acting as a source server). It is part of the System to System Data Exchange Module.
36.0.1.3.1Implementation
Smile CDR supports the HRex Implementation of the $member-match operation.
| Use | Name | Type | Cardinality | Description |
|---|---|---|---|---|
| IN | MemberPatient | Patient | 1..1 | The target of the operation. It contains member patient demographics for the matching process. |
| IN | Consent | Consent | 1..1 | Consent held by the requester that grants permission to access the patient information on the receiving system for whom a patient is sought. |
| IN | CoverageToMatch | Coverage | 1..1 | Parameter that identifies the coverage to be matched by the receiving system. It contains the coverage details of health plan coverage provided by the member, typically from their health plan coverage card. |
| IN | CoverageToLink | Coverage | 1..1 | Parameter that identifies the coverage information of the member as they are known by the requesting system. This information allows the receiving system to link their member coverage information to that of the requesting system to ease subsequent exchanges, including evaluating authorization to share information in subsequent queries. This parameter is optional as this operation may be invoked by non-payer systems. However, If the system invoking the operation is a payer, they SHALL include their coverage information for the member when invoking the operation. |
| OUT | MemberIdentifier | Identifier | 1..1 | This is the Patient FHIR ID for the patient as known by the receiving system. If the $member-match operation is successful, it will be returned to the caller. |
| OUT | MemberId | Reference | 0..1 | This is the RESTful identity for the patient as known by the server that is the target of the operation. Note that while this is optional in the specification, the Smile $member-match operation will return the reference. |
An example payload for the request can be found under the $invoke-export documentation. It is embedded in the memberMatch parameter for that operation.
36.0.1.3.2Response Example
The $member-match operation returns a Parameters resource that includes a business identifier for the member as known by the source system. Smile's implementation of the operation will also return the reference to the Patient ID.
http://example.com/Patient/$member-match
{
"resourceType": "Parameters",
"parameter": [
{
"name": "MemberPatient",
"resource": {
"resourceType": "Patient",
"id": "1",
"identifier": [
{
"type": {
"coding": [
{
"system": "http://hl7.davinci.org",
"code": "MB"
}
]
},
"system": "http://oldhealthplan.example.com",
"value": "55678",
"assigner": {
"reference": "Organization/2",
"_reference": {
"fhir_comments": [
"MB is passed from coverage card by new health plan."
]
}
}
}
],
"name": [
{
"use": "official",
"family": "Person",
"given": [
"Patricia",
"Ann"
]
}
],
"gender": "female",
"birthDate": "1974-12-25"
}
},
{
"name": "CoverageToMatch",
"resource": {
"resourceType": "Coverage",
"id": "OLD_COVERAGE_ID",
"text": {
"status": "generated",
"div": "<div xmlns=\"http://www.w3.org/1999/xhtml\">A human-readable rendering of the coverage</div>"
},
"contained": [
{
"resourceType": "Organization",
"id": "Organization/2",
"name": "Old Health Plan",
"endpoint": [
{
"reference": "http://www.oldhealthplan.com"
}
]
}
],
"identifier": [
{
"system": "http://oldhealthplan.example.com",
"value": "DH10001235"
}
],
"status": "draft",
"beneficiary": {
"reference": "BENEFICIARY_PATIENT_ID"
},
"period": {
"start": "2011-05-23",
"end": "2012-05-23"
},
"payor": [
{
"reference": "#Organization/2"
}
],
"class": [
{
"type": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/coverage-class",
"code": "group"
}
]
},
"value": "CB135"
},
{
"type": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/coverage-class",
"code": "plan"
}
]
},
"value": "B37FC"
},
{
"type": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/coverage-class",
"code": "subplan"
}
]
},
"value": "P7"
},
{
"type": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/coverage-class",
"code": "class"
}
]
},
"value": "SILVER"
}
]
}
},
{
"name": "CoverageToLink",
"resource": {
"resourceType": "Coverage",
"id": "AA87654",
"contained": [
{
"resourceType": "Organization",
"id": "Organization/3",
"name": "New Health Plan",
"endpoint": [
{
"reference": "http://www.newhealthplan.com"
}
]
}
],
"identifier": [
{
"system": "http://newealthplan.example.com",
"value": "234567"
}
],
"status": "active",
"beneficiary": {
"reference": "BENEFICIARY_PATIENT_ID"
},
"period": {
"start": "2020-04-01",
"end": "2021-03-31"
},
"payor": [
{
"reference": "#Organization/3"
}
],
"class": [
{
"type": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/coverage-class",
"code": "group"
}
]
},
"value": "A55521",
"name": "New Health Plan Group"
},
{
"type": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/coverage-class",
"code": "subgroup"
}
]
},
"value": "456"
},
{
"type": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/coverage-class",
"code": "plan"
}
]
},
"value": "99012"
},
{
"type": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/coverage-class",
"code": "subplan"
}
]
},
"value": "A4"
},
{
"type": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/coverage-class",
"code": "class"
}
]
},
"value": "GOLD"
}
]
}
},
{
"name": "Consent",
"resource": {
"resourceType": "Consent",
"status": "active",
"scope": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/consentscope",
"code": "patient-privacy"
}
]
},
"category": [
{
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/v3-ActCode",
"code": "IDSCL"
}
]
}
],
"patient": {
"reference": "BENEFICIARY_PATIENT_ID"
},
"performer": [
{
"reference": "BENEFICIARY_PATIENT_ID"
}
],
"policy": [
{
"uri": "http://hl7.org/fhir/us/davinci-hrex/StructureDefinition-hrex-consent.html#regular"
}
],
"provision": {
"type": "permit",
"period": {
"start": "2022-01-01"
},
"actor": [
{
"role": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/provenance-participant-type",
"code": "performer"
}
]
},
"reference": {
"identifier": {
"system": "http://hl7.org/fhir/sid/us-npi",
"value": "9876543210"
},
"display": "Old Health Plan"
}
},
{
"role": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/v3-ParticipationType",
"code": "IRCP"
}
]
},
"reference": {
"identifier": {
"system": "http://hl7.org/fhir/sid/us-npi",
"value": "0123456789"
},
"display": "New Health Plan"
}
}
],
"action": [
{
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/consentaction",
"code": "disclose"
}
]
}
]
}
}
}
]
}
This operation returns a Parameters resource that includes the Patient FHIR ID for the patient as known by the receiving system:
Note: the structure of the return value is subject to change as the PDex specification continues to evolve.
{
"resourceType": "Parameters",
"meta": {
"profile": [ "http://hl7.org/fhir/us/davinci-hrex/StructureDefinition/hrex-parameters-member-match-out" ]
},
"parameter": [ {
"name": "MemberIdentifier",
"valueIdentifier": {
"type": {
"coding": [ {
"system": "http://hl7.org/fhir/us/davinci-hrex/CodeSystem/hrex-temp",
"code": "UMB"
} ]
},
"value": "P0001",
"assigner": {
"reference": "http://sourceServ.org/referenceAssigner"
}
}
}, {
"name": "MemberId",
"valueReference": {
"reference": "Patient/test1326"
}
} ]
}
36.0.1.4Consent Service Interceptors
In order to support $member-match operations, all that is required is to add and configure this module (the System to System Data Exchange
module) to the current Smile CDR server.
A default implementation of $member-match will allow the export of all resources associated with the member (Patient) used when invoking the operation to begin with.
Additional filtering of exported resources can be done by registering a storage module consent service and implementing either the willSeeResource method in a Java consent interceptor, or providing a consentWillSeeResource JavaScript function.
This method will be invoked for all bulk data export jobs ($export operations invoked on System, Type, or Instance). But if a System to System Data Exchange module is also present, the RequestDetails object will contain user data that will include a serialized Consent resource for $member-match invoked bulk export operations.
The Consent resource can be found at userData['consentResource'] and can be deserialized using a parser created from the Fhir context.
The following script is an example of a JavaScript Consent Script:
function consentWillSeeResource(theRequestDetails, theUserSession, theContext, theResource, theClientSession) {
var resourceType = theResource.resourceType;
var userData = theRequestDetails.getUserData();
if (userData) {
var consentResourceStr = userData['consentResource'];
if (consentResourceStr) {
var consentResource = Fhir.getContext()
.newJsonParser()
.parseResource(consentResourceStr);
if (consentResource.status != "ACTIVE") {
theContext.reject();
return;
}
}
}
theContext.proceed();
}