diff --git a/docs/api-reference/operations/bulk-member-match.md b/docs/api-reference/operations/bulk-member-match.md index bc4bcb0..0a15114 100644 --- a/docs/api-reference/operations/bulk-member-match.md +++ b/docs/api-reference/operations/bulk-member-match.md @@ -470,9 +470,9 @@ URL comes from `output[0].url` in the manifest. Body is a single ndjson line — | Direction | Parameter | Type | Cardinality | Description | |---|---|---|---|---| -| OUT | `MatchedMembers` | Group | 1..1 | [`pdex-member-match-group`](https://build.fhir.org/ig/HL7/davinci-epdx/StructureDefinition-pdex-member-match-group.html); members matched, consent passed, opt-out clear, and the submitted Consent persisted. Group id is the input to [`$davinci-data-export`](davinci-data-export.md) with `exportType = hl7.fhir.us.davinci-pdex#payertopayer`. Each member links to the Patient the requesting payer submitted, carried in `Group.contained[]`, through the `base-ext-match-parameters` extension on `member.entity`. `quantity = 0` and `member` omitted when empty. | +| OUT | `MatchedMembers` | Group | 1..1 | [`pdex-member-match-group`](https://build.fhir.org/ig/HL7/davinci-epdx/StructureDefinition-pdex-member-match-group.html); members matched, consent passed, and the submitted Consent persisted. Group id is the input to [`$davinci-data-export`](davinci-data-export.md) with `exportType = hl7.fhir.us.davinci-pdex#payertopayer`. Each member links to the Patient the requesting payer submitted, carried in `Group.contained[]`, through the `base-ext-match-parameters` extension on `member.entity`. `quantity = 0` and `member` omitted when empty. | | OUT | `NonMatchedMembers` | Group | 0..1 | [`pdex-member-no-match-group`](https://build.fhir.org/ig/HL7/davinci-epdx/StructureDefinition-pdex-member-no-match-group.html); no match found. Submitted Patients are carried in `Group.contained[]` (fragment refs `#submitted-1`, `#submitted-2`, …). | -| OUT | `ConsentConstrainedMembers` | Group | 0..1 | [`pdex-member-no-match-group`](https://build.fhir.org/ig/HL7/davinci-epdx/StructureDefinition-pdex-member-no-match-group.html) with code `consentconstraint`; matched member whose Consent failed a match-time check, has an active opt-out, or whose Consent could not be persisted. | +| OUT | `ConsentConstrainedMembers` | Group | 0..1 | [`pdex-member-no-match-group`](https://build.fhir.org/ig/HL7/davinci-epdx/StructureDefinition-pdex-member-no-match-group.html) with code `consentconstraint`; matched member whose Consent failed a match-time check or could not be persisted. | ### Example @@ -632,7 +632,7 @@ Each submitted member is evaluated independently. Per-member failures never fail **Demographic match.** Same algorithm as [`$provider-member-match`](provider-member-match.md#matching-behavior): all four of `family`, `given[0]`, `birthDate`, `gender` are required and queried against payer Patients. `Patient.identifier` entries become `identifier` search tokens (FHIR AND semantics — every submitted identifier must match). Identifier-AND is bulk-specific: [`$provider-member-match`](provider-member-match.md#matching-behavior) ignores submitted `Patient.identifier` entries, because provider-side systems carry MRNs the payer does not store. `Coverage.subscriberId`, when present, becomes `_has:Coverage:beneficiary:subscriber-id`. Zero or ambiguous (>1) results route to `NonMatchedMembers`. -**Match-time consent checks.** A matched member is moved to `ConsentConstrainedMembers` if **any** of the following is true (the opt-out category code below uses the `pdex-consent-api-purpose` CodeSystem from PDex 2.2.0): +**Match-time consent checks.** A matched member is moved to `ConsentConstrainedMembers` if **any** of the following is true: | Check | Constrains when | |---|---| @@ -640,13 +640,12 @@ Each submitted member is evaluated independently. Per-member failures never fail | `Consent.provision.period` | absent, unparseable, or does not cover the current time | | `Consent.provision.actor[role=IRCP]` recipient | does not resolve to the requesting payer's `Organization/` reference | | `Consent.policy[*].uri` | not `#sensitive` — `#regular` and missing/unknown policy URIs both constrain (fail-safe; Payerbox does not yet redact sensitive data, so non-`#sensitive` consents cannot be honored) | -| Active `provider-access` deny `Consent` on the matched Patient (opt-out) | any active hit; a failing opt-out query (non-2xx) fails safe to constrained | -The opt-out check reuses the same Aidbox search as [`$provider-member-match`](provider-member-match.md#matching-behavior): `Consent?patient=&status=active&category=http://hl7.org/fhir/us/davinci-pdex/CodeSystem/pdex-consent-api-purpose|provider-access&provision-type=deny`. +A Provider Access opt-out on the matched Patient is not checked: it is the member's choice about sharing with providers, separate from the Payer-to-Payer permission the submitted Consent carries. **Consent persistence.** For each remaining matched member the submitted `Consent` is upserted into Aidbox with a deterministic id (`SHA-1(payer-org-id|patient-id)`); `Consent.patient` is rewritten to the matched payer Patient and `Consent.organization` to the requesting payer's Organization (FHIR shape is `0..*`; today exactly one element is written). The persisted Consent is what the later `$davinci-data-export?exportType=payertopayer` query reads against. If persistence fails — including the case where the requesting payer's identifier has no `Organization` registered in the responding payer's Aidbox — the member is re-bucketed to `ConsentConstrainedMembers`. -**Stale Consent removal.** If a later `$bulk-member-match` for the same `(matched-patient, requesting-payer)` lands the member in `ConsentConstrainedMembers` (failed match-time check, opt-out hit, or persistence failure), the prior persisted `Consent` at the deterministic id is deleted (one batch `Bundle` for all pairs). Deleted rather than deactivated: the HRex Consent profile fixes `status = active`, so a status flip would `422`. `$davinci-data-export?exportType=payertopayer` fails closed on the missing permit. +**Stale Consent removal.** If a later `$bulk-member-match` for the same `(matched-patient, requesting-payer)` lands the member in `ConsentConstrainedMembers` (failed match-time check or persistence failure), the prior persisted `Consent` at the deterministic id is deleted (one batch `Bundle` for all pairs). Deleted rather than deactivated: the HRex Consent profile fixes `status = active`, so a status flip would `422`. `$davinci-data-export?exportType=payertopayer` fails closed on the missing permit. ## Group lifecycle diff --git a/docs/api-reference/operations/davinci-data-export.md b/docs/api-reference/operations/davinci-data-export.md index 675eafd..0384046 100644 --- a/docs/api-reference/operations/davinci-data-export.md +++ b/docs/api-reference/operations/davinci-data-export.md @@ -157,6 +157,19 @@ Content-Type: application/fhir+json {% endtab %} {% endtabs %} +## Export tracking + +After each kick-off, Payerbox records the export on the `Group` with the PDex 2.1.0 tracking extensions: + +| Extension | On | Value | +|---|---|---| +| [`base-ext-members-opted-out`](https://hl7.org/fhir/us/davinci-pdex/STU2.1/StructureDefinition-base-ext-members-opted-out.html) | `Group` | Members left out by the consent rule: opted out for `provider-download`, no valid opt-in for `payertopayer` | +| [`base-ext-last-transmission`](https://hl7.org/fhir/us/davinci-pdex/STU2.1/StructureDefinition-base-ext-last-transmission.html) | each exported `Group.member` | The request's `_until`, or the kick-off time | +| [`base-ext-last-types`](https://hl7.org/fhir/us/davinci-pdex/STU2.1/StructureDefinition-base-ext-last-types.html) | each exported `Group.member` | The request's `_type`, when present | +| [`base-ext-last-typefilter`](https://hl7.org/fhir/us/davinci-pdex/STU2.1/StructureDefinition-base-ext-last-typefilter.html) | each exported `Group.member` | The request's `_typeFilter`, when present | + +An opt-out counts only while its `provision.period` is in force. Members left out by the consent rule, or outside the requested `patient` subset, keep their previous values. Tracking is written after the `202`; a failure there does not affect the export. + ## Status polling ### Endpoint diff --git a/docs/fhir-app-portal/developer-portal.md b/docs/fhir-app-portal/developer-portal.md index e6eab1e..bf1dc95 100644 --- a/docs/fhir-app-portal/developer-portal.md +++ b/docs/fhir-app-portal/developer-portal.md @@ -35,7 +35,7 @@ The dashboard splits registration into two sections. Pick by how the client auth | OAuth grant | `authorization_code` | `client_credentials` | | Register under | **Smart Apps** | **Backend Services** | | Auth | Public or confidential; redirect + launch URL | JWKS URI or client secret | -| Scopes | `patient/*`, `user/*`, launch, OIDC | `system/*` only | +| Scopes | `patient/` read, launch, OIDC | `system/*` only | | Use for | Patient- or provider-facing apps | Bulk export, server-to-server APIs | Each client-type page covers its own registration, testing, submission, and status. diff --git a/docs/fhir-app-portal/smart-app.md b/docs/fhir-app-portal/smart-app.md index d14847a..135e12d 100644 --- a/docs/fhir-app-portal/smart-app.md +++ b/docs/fhir-app-portal/smart-app.md @@ -16,7 +16,7 @@ A SMART App is an interactive SMART on FHIR client: a user launches it in a brow * **Confidentiality**: public or confidential; a confidential client is issued a secret * **Redirect URL**: where users return after authorization * **Launch URL**: your app's SMART launch endpoint -3. Set the **SMART on FHIR scopes** the app requests (`patient/*`, `user/*`, plus launch and OIDC scopes) +3. Set the **SMART on FHIR scopes** the app requests (`patient/` read scopes, plus launch and OIDC scopes) 4. Click **Create App** You're redirected to the app's draft page to review, edit, or delete it. diff --git a/docs/interop-apis/payer-to-payer.md b/docs/interop-apis/payer-to-payer.md index ff5a397..f73f08e 100644 --- a/docs/interop-apis/payer-to-payer.md +++ b/docs/interop-apis/payer-to-payer.md @@ -104,9 +104,9 @@ Three buckets in the response: | Group | Profile | Contents | |---|---|---| -| `MatchedMembers` | [`pdex-member-match-group`](https://build.fhir.org/ig/HL7/davinci-epdx/StructureDefinition-pdex-member-match-group.html) | Members matched, consent valid, opt-out clear; submitted `Consent` is persisted by the responding payer | +| `MatchedMembers` | [`pdex-member-match-group`](https://build.fhir.org/ig/HL7/davinci-epdx/StructureDefinition-pdex-member-match-group.html) | Members matched, consent valid; submitted `Consent` is persisted by the responding payer | | `NonMatchedMembers` | [`pdex-member-no-match-group`](https://build.fhir.org/ig/HL7/davinci-epdx/StructureDefinition-pdex-member-no-match-group.html) | No match found | -| `ConsentConstrainedMembers` | [`pdex-member-no-match-group`](https://build.fhir.org/ig/HL7/davinci-epdx/StructureDefinition-pdex-member-no-match-group.html) (code `consentconstraint`) | Matched member with active opt-out, expired consent, or consent that could not be persisted | +| `ConsentConstrainedMembers` | [`pdex-member-no-match-group`](https://build.fhir.org/ig/HL7/davinci-epdx/StructureDefinition-pdex-member-no-match-group.html) (code `consentconstraint`) | Matched member with expired consent or consent that could not be persisted | `$bulk-member-match` rejects non-admin callers whose access token lacks the hl7-b2b `organization_id` claim with `403`. diff --git a/docs/prior-auth/crd.md b/docs/prior-auth/crd.md index a2414f7..a40e8b8 100644 --- a/docs/prior-auth/crd.md +++ b/docs/prior-auth/crd.md @@ -66,7 +66,15 @@ Hook-context resources (context and prefetch content) are validated before they FHIR_VALIDATION_LENIENT=true ``` -In lenient mode, terminology display-name mismatches, referenced-resource profile mismatches, and context references that cannot be resolved (the referenced resources may exist only in the EHR's own store) are logged as warnings and the hook proceeds; only structural and profile errors fail the request. Default (unset) — strict. The same flag also controls [PAS submission validation](pas.md#validation-strictness). +In lenient mode, terminology display-name mismatches and referenced-resource profile mismatches are logged as warnings and the hook proceeds; only structural and profile errors fail the request. Default (unset) — strict. The same flag also controls [PAS submission validation](pas.md#validation-strictness). + +Context references that cannot be resolved, even from the EHR's `fhirServer` (the referenced resources may exist only in the EHR's own store), fail the hook request unless a separate flag is set: + +``` +FHIR_VALIDATION_LENIENT_REFERENCES=true +``` + +With it, the hook proceeds without the unresolved references. Off by default. ## Supported hooks diff --git a/docs/releases.md b/docs/releases.md index fc0db20..92dbc3c 100644 --- a/docs/releases.md +++ b/docs/releases.md @@ -6,6 +6,38 @@ description: "Notable changes across Payerbox: the Interop APIs, the Prior Auth This page tracks notable changes across Payerbox: the Interop APIs, the Prior Auth (ePA) APIs, and the FHIR App Portal. Releases are listed newest first. The apps run on an Aidbox FHIR server; each component heading links to its image on Docker Hub. +## October 2026 (`2610`) + +### Interop APIs [`2610`](https://hub.docker.com/r/healthsamurai/interop) + +**Provider Access** + +- [`$provider-member-match`](api-reference/operations/provider-member-match.md) now recognizes `IDSCL` opt-outs. +- Member matching and [export tracking](api-reference/operations/davinci-data-export.md#export-tracking) now ignore opt-outs that have expired or have not started. + +### Prior Auth (ePA) APIs [`2610`](https://hub.docker.com/r/healthsamurai/prior-auth) + +**PAS** + +- Files attached inside a submitted questionnaire can now be stored in S3 instead of inside the request, and attachments can be sent as a link instead of the file itself. Set `SUBMIT_ATTACHMENT_OFFLOAD_QUESTIONNAIRE_RESPONSE=true` and `SUBMIT_ATTACHMENT_ACCEPT_URL=true` to enable them (off by default). See [`$submit-attachment`](api-reference/operations/submit-attachment.md). + +**CRD** + +- Lenient validation is now split in two. `FHIR_VALIDATION_LENIENT` still relaxes minor data mismatches. Accepting references to records Payerbox can't find now needs a separate setting, `FHIR_VALIDATION_LENIENT_REFERENCES=true`. If you relied on the old behavior, set both. See [CRD validation strictness](prior-auth/crd.md#validation-strictness). + +### FHIR App Portal [`2610`](https://hub.docker.com/r/healthsamurai/fhir-app-portal) + +**Member consent** + +- The **Data sharing** page was redesigned: each choice is a card that shows its current state and opens its form in place, one at a time. See [Consent Panel](fhir-app-portal/member-portal/consent-panel.md). +- Completing the forms as an authorized representative is opt-in per deployment: set `MEMBER_CONSENT_REPRESENTATIVES_ENABLED=true` on the portal backend. Off by default: members complete the forms themselves, representative submissions and document uploads are refused, and Member Details shows no reviews. In `2609` it was always on. See [Authorized representatives](fhir-app-portal/member-portal/consent-panel.md#authorized-representatives) and [Consent Reviews](fhir-app-portal/consent-reviews.md). +- **Settings → Consent** was rebuilt for the plan administrator: one card holds the plan, the date Payer-to-Payer permissions end, and whether members can exclude sensitive records; an administrator whose plan is not in Aidbox yet can add it from the picker with a NAIC company code or a TIN. See [Consent Settings](fhir-app-portal/consent-settings.md). +- Other health plans that members can pick on the Payer-to-Payer form are registered by NAIC company code or TIN instead of NPI. + +**MPF pipeline** + +- The Bundle `entry.fullUrl` base is an admin setting in **Settings → MPF**, saved with the publications; unset, it resolves to the admin Aidbox public URL plus `/fhir`. With no publications saved, nothing is published. See [MPF Publications](fhir-app-portal/mpf-publications.md). + ## September 2026 (`2609`) - The [Data Integration Reference](data-integration/README.md) adds four feeds: [Claims](data-integration/carin-bb/README.md) (CARIN BB 2.1.0), [Prior Authorizations](data-integration/prior-auth/README.md) (PDex 2.1.0), [Drug Formulary](data-integration/drug-formulary/README.md) (PDex US Drug Formulary 2.1.0), and [Member Consent](data-integration/consent/README.md).