AWS healthlake documentation change
Summary
Expanded documentation for the $davinci-data-export operation to support multiple export types (ATR, PDex Provider Access, Payer-to-Payer, Member Access), added detailed profile support logic, financial data transformation options, temporal filtering rules, and updated error handling and best practices.
Security assessment
The changes primarily expand functionality and clarify operational details rather than address a specific security vulnerability. However, they add security-related documentation about financial data removal (privacy protection), IAM role permissions for data access, and explicit guidance on securing export operations. The addition of the _includeEOB2xWoFinancial parameter and financial data transformation details demonstrates enhanced privacy controls for sensitive claims data, which is a security feature.
Diff
diff --git a/healthlake/latest/devguide/reference-fhir-operations-davinci-data-export.md b/healthlake/latest/devguide/reference-fhir-operations-davinci-data-export.md index 39149ab5b..387836d2d 100644 --- a//healthlake/latest/devguide/reference-fhir-operations-davinci-data-export.md +++ b//healthlake/latest/devguide/reference-fhir-operations-davinci-data-export.md @@ -5 +5 @@ -Key FeaturesOperation EndpointRequest ParametersSample RequestResource RelationshipsJob ManagementOutput FormatError HandlingSecurity and AuthorizationBest PracticesLimitations +Key FeaturesOperation EndpointRequest ParametersExport TypesProfile Support and Inclusion LogicFive-Year Temporal Filtering for PDex ExportsSample RequestsSample ResponseResource RelationshipsJob ManagementOutput FormatError HandlingSecurity and AuthorizationBest PracticesLimitationsAdditional Resources @@ -9 +9 @@ Key FeaturesOperation EndpointRequest ParametersSample RequestResource Relations -The `$davinci-data-export` operation is an asynchronous FHIR operation that enables the export of Member Attribution List data from AWS HealthLake. This operation is a specialized version of the standard FHIR `$export` operation, designed specifically to meet the requirements of the DaVinci Member Attribution (ATR) List Implementation Guide. +The `$davinci-data-export` operation is an asynchronous FHIR operation that you can use to export healthcare data from AWS HealthLake. This operation supports multiple export types, including Member Attribution (ATR), PDex Provider Access, Payer-to-Payer, and Member Access APIs. It is a specialized version of the standard FHIR `$export` operation, designed to meet the requirements of the DaVinci implementation guides. @@ -15 +15 @@ The `$davinci-data-export` operation is an asynchronous FHIR operation that enab - * _Group-Level Export_ : Exports data for members within a specific attribution list (Group) + * _Group-Level Export_ : Exports data for members within a specific Group resource @@ -17 +17,3 @@ The `$davinci-data-export` operation is an asynchronous FHIR operation that enab - * _Specialized Resource Handling_ : Focuses on attribution-related resources + * _Multiple Export Types_ : Supports ATR (Member Attribution), PDex Provider Access, Payer-to-Payer, and Member Access APIs + + * _Comprehensive Profile Support_ : Includes US Core, CARIN Blue Button, and PDex profiles @@ -36,5 +38,6 @@ Parameter | Cardinality | Description -patient | 0..* | Specific members whose data should be exported. When omitted, all members in the Group are exported -_type | 0..1 | Comma-delimited list of FHIR resource types to export -_since | 0..1 | Only include resources updated after this date/time -_until | 0..1 | Only include resources updated until this date/time -exportType | 0..1 | Type of export to perform (default: hl7.fhir.us.davinci-atr) +`patient` | 0..* | Specific members whose data to export. When omitted, all members in the Group are exported. +`_type` | 0..1 | Comma-delimited list of FHIR resource types to export. +`_since` | 0..1 | Only include resources updated after this date and time. +`_until` | 0..1 | Only include resources updated before this date and time. +`exportType` | 0..1 | Type of export to perform. Valid values: `hl7.fhir.us.davinci-atr`, `hl7.fhir.us.davinci-pdex`, `hl7.fhir.us.davinci-pdex.p2p`, `hl7.fhir.us.davinci-pdex.member`. Default: `hl7.fhir.us.davinci-atr`. +`_includeEOB2xWoFinancial` | 0..1 | Specifies whether to include CARIN BB 2.x ExplanationOfBenefit resources with financial data removed. Default: `false`. @@ -44 +47,104 @@ exportType | 0..1 | Type of export to perform (default: hl7.fhir.us.davinci-atr) -When using the `_type` parameter, only the following resource types are supported: +The supported resource types depend on the export type you specify. For ATR exports, the following resource types are supported: + + * `Group` + + * `Patient` + + * `Coverage` + + * `RelatedPerson` + + * `Practitioner` + + * `PractitionerRole` + + * `Organization` + + * `Location` + + + + +For PDex exports (Provider Access, Payer-to-Payer, and Member Access), all clinical and claims resource types are supported in addition to the preceding types. For a complete list of supported resource types, see the [US Core Implementation Guide (STU 6.1)](https://hl7.org/fhir/us/core/STU6.1/), the [CARIN Blue Button Implementation Guide](https://hl7.org/fhir/us/carin-bb/), and the [Da Vinci Prior Authorization Support Implementation Guide](https://hl7.org/fhir/us/davinci-pas/). + +## Export Types + +The `$davinci-data-export` operation supports the following export types. You specify the export type by using the `exportType` parameter. + +Export Type | Purpose | Data Scope | Temporal Limit +---|---|---|--- +`hl7.fhir.us.davinci-atr` | Member Attribution List | Attribution-related resources | None +`hl7.fhir.us.davinci-pdex` | Provider Access API | Clinical and claims data for attributed patients | 5 years +`hl7.fhir.us.davinci-pdex.p2p` | Payer-to-Payer Exchange | Historical member data for insurance transitions | 5 years +`hl7.fhir.us.davinci-pdex.member` | Member Access API | Member's own health data | 5 years + +###### Note + +For PDex exports, the 5-year temporal limit does not apply to ATR resource types (`Group`, `Patient`, `Coverage`, `RelatedPerson`, `Practitioner`, `PractitionerRole`, `Organization`, `Location`). These resources are always included regardless of age. + +### ATR (hl7.fhir.us.davinci-atr) + +With the ATR export type, you can export Member Attribution List data. Use this export type to retrieve attribution-related resources for members within a Group. For more information, see the [Da Vinci ATR Export Operation](https://build.fhir.org/ig/HL7/davinci-atr/OperationDefinition-davinci-data-export.html). + +Supported Resource Types + + +`Group`, `Patient`, `Coverage`, `RelatedPerson`, `Practitioner`, `PractitionerRole`, `Organization`, `Location` + +Temporal Filtering + + +No temporal filtering is applied. All matching resources are exported regardless of date. + +### PDex Export Types + +All PDex export types share the same supported profiles and filtering logic. For more information, see the [Da Vinci PDex Provider Access API](https://build.fhir.org/ig/HL7/davinci-epdx/provider-access-api.html). The following profiles are supported: + + * US Core 3.1.1, 6.1.0, and 7.0.0 + + * PDex Prior Authorization (not supported for Member Access) + + * CARIN BB 2.x Basis profiles: Inpatient Institutional, Outpatient Institutional, Professional NonClinician, Oral, Pharmacy + + + + +Provider Access (`hl7.fhir.us.davinci-pdex`) + + +Enables in-network providers to retrieve patient data for attributed patients. + +Payer-to-Payer (`hl7.fhir.us.davinci-pdex.p2p`) + + +Enables data exchange between payers when a patient changes insurance. + +Member Access (`hl7.fhir.us.davinci-pdex.member`) + + +Enables members to access their own health data. This export type may include financial data in claims resources. + +## Profile Support and Inclusion Logic + +For PDex exports, the `$davinci-data-export` operation uses profile declarations in the `meta.profile` element to determine which resources to include in the export. + +### ExplanationOfBenefit Resource Handling + +`ExplanationOfBenefit` (EOB) resources are included or excluded from PDex exports based on their `meta.profile` declarations: + + * ExplanationOfBenefit resources with a CARIN BB 1.x profile are excluded from the export. + + * ExplanationOfBenefit resources with no `meta.profile` set are excluded from the export. + + * ExplanationOfBenefit resources with a CARIN BB 2.x Basis profile are always included. + + * ExplanationOfBenefit resources with a CARIN BB 2.x profile that contains financial data are excluded by default. When `_includeEOB2xWoFinancial=true` is set, they are included with financial data stripped and the resource is transformed to the corresponding Basis profile. + + * ExplanationOfBenefit resources with a PDex Prior Authorization profile are always included. + + + + +### Financial Data Transformation + +When you set `_includeEOB2xWoFinancial=true`, the operation transforms [CARIN BB 2.x](https://hl7.org/fhir/us/carin-bb/) ExplanationOfBenefit resources to their corresponding Basis profiles by removing financial data. For example, a `C4BB ExplanationOfBenefit Oral` resource is transformed to `C4BB ExplanationOfBenefit Oral Basis`, which strips financial data from the record per the FHIR specification. @@ -46 +152 @@ When using the `_type` parameter, only the following resource types are supporte - * Group +The following financial data elements are removed during transformation: @@ -48 +154 @@ When using the `_type` parameter, only the following resource types are supporte - * Patient + * All slicing on `total` elements @@ -50 +156 @@ When using the `_type` parameter, only the following resource types are supporte - * Coverage + * All `adjudication` elements with `amounttype` slice @@ -52 +158 @@ When using the `_type` parameter, only the following resource types are supporte - * RelatedPerson + * All `item.adjudication` elements with amount information @@ -54 +159,0 @@ When using the `_type` parameter, only the following resource types are supporte - * Practitioner @@ -56 +160,0 @@ When using the `_type` parameter, only the following resource types are supporte - * PractitionerRole @@ -58 +161,0 @@ When using the `_type` parameter, only the following resource types are supporte - * Organization @@ -60 +163 @@ When using the `_type` parameter, only the following resource types are supporte - * Location +The operation also updates profile metadata during transformation: @@ -61,0 +165 @@ When using the `_type` parameter, only the following resource types are supporte + * `meta.profile` is updated to the Basis profile canonical URL @@ -62,0 +167 @@ When using the `_type` parameter, only the following resource types are supporte + * Version is updated to the CARIN BB 2.x Basis version @@ -63,0 +169 @@ When using the `_type` parameter, only the following resource types are supporte + * Existing resources in the data store are not modified @@ -65 +171 @@ When using the `_type` parameter, only the following resource types are supporte -## Sample Request + * Exported resources are not persisted back to the data store @@ -67 +172,0 @@ When using the `_type` parameter, only the following resource types are supporte -### Starting an Export Job @@ -70 +174,0 @@ When using the `_type` parameter, only the following resource types are supporte - GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Group/example-group/$davinci-data-export?_type=Group,Patient,Coverage&exportType=hl7.fhir.us.davinci-atr @@ -72 +176 @@ When using the `_type` parameter, only the following resource types are supporte - or +### Profile Detection Rules @@ -74 +178,46 @@ When using the `_type` parameter, only the following resource types are supporte - POST https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Group/example-group/$davinci-data-export?_type=Group,Patient,Coverage&exportType=hl7.fhir.us.davinci-atr +The operation uses the following rules to detect and validate profiles: + + * Version detection is based on the `meta.profile` canonical URLs + + * A resource is included if ANY of its declared profiles match the export criteria + + * Profile validation occurs during export processing + + + + +## Five-Year Temporal Filtering for PDex Exports + +For all PDex export types, HealthLake applies a 5-year temporal filter based on when the resource was last updated. The temporal filter applies to all resources except the following core attribution resource types, which are always exported regardless of age: + + * `Patient` + + * `Coverage` + + * `Organization` + + * `Practitioner` + + * `PractitionerRole` +