From 27cd8bb17f0275545c6e96e25bfc8df944a642aa Mon Sep 17 00:00:00 2001 From: glebmark <87950237+glebmark@users.noreply.github.com> Date: Mon, 9 Nov 2026 16:59:21 +0400 Subject: [PATCH] [misc] service acc to WI + custom fullUrl --- .../operations/mpf-pipeline-api.md | 2 +- docs/fhir-app-portal/mpf-publications.md | 26 ++++++++++++++----- .../provider-directory-pipeline.md | 17 ++++++------ 3 files changed, 28 insertions(+), 17 deletions(-) diff --git a/docs/api-reference/operations/mpf-pipeline-api.md b/docs/api-reference/operations/mpf-pipeline-api.md index a32e882..5b37143 100644 --- a/docs/api-reference/operations/mpf-pipeline-api.md +++ b/docs/api-reference/operations/mpf-pipeline-api.md @@ -23,7 +23,7 @@ The full run: export, filter, bundle, publish. CMS crawls the registered URLs da ### Body -All fields are optional. Together they select which of the publications configured under **Settings → MPF** (see [MPF Publications](../../fhir-app-portal/mpf-publications.md)) to regenerate. An empty body regenerates all of them; a selector that matches no configured publication is rejected with `400`. +All fields are optional. Together they select which of the publications configured under **Settings → MPF** (see [MPF Publications](../../fhir-app-portal/mpf-publications.md)) to regenerate. An empty body regenerates all of them; a selector that matches no configured publication, or any request while no publication has been saved yet, is rejected with `400`. diff --git a/docs/fhir-app-portal/mpf-publications.md b/docs/fhir-app-portal/mpf-publications.md index 882356d..d2c5b30 100644 --- a/docs/fhir-app-portal/mpf-publications.md +++ b/docs/fhir-app-portal/mpf-publications.md @@ -1,7 +1,8 @@ --- description: >- Configure which CMS contracts, contract years, and InsurancePlans the MPF - pipeline publishes, from the Admin Portal's Settings → MPF tab. + pipeline publishes, and the FHIR base URL of the published bundles, from + the Admin Portal's Settings → MPF tab. --- # MPF Publications @@ -10,16 +11,26 @@ The **Settings → MPF** tab of the Admin Portal controls what the [MPF Pipeline Open **Settings → MPF** (`/dashboard/settings/mpf`). The tab is shown only when the portal runs with the module enabled (see [Configure the environment](../run-payerbox/provider-directory-pipeline.md#configure-the-environment)); otherwise the page says *MPF is not enabled on this installation*. -Until something is saved, the page shows one built-in publication seeded from `MPF_DEFAULT_CONTRACT` and `MPF_DEFAULT_YEAR` and notes that it is *currently using the built-in defaults*. **Save** stores the whole page as an override in Aidbox (`DocumentReference/mpf-export-scope` on the admin box). The next sync reads it; no restart or redeploy is needed. +Until something is saved, the page has no contract year and notes that *nothing is configured yet*: the daily sync publishes nothing, and a manual trigger is rejected with `400`. There is no built-in publication. **Save** stores the whole page in Aidbox (`DocumentReference/mpf-export-scope` on the admin box). The next sync reads it; no restart or redeploy is needed. ![MPF settings tab with one contract year card holding a single contract and its CMS crawler URL](../../assets/run-payerbox/mpf-settings-publication.avif) +## Directory-wide settings + +The card above the contract years holds the one value that applies to every publication: + +| Field | What to enter | +|---|---| +| **FHIR base URL for entry.fullUrl** | Every entry of a published bundle carries `fullUrl` = this base + `//`. Enter the public FHIR base URL of this installation, e.g. `https://fhir./fhir`. Leave it empty to use the admin Aidbox's public URL followed by `/fhir`; the card shows the resulting value. | + ## Fields +Each contract year card holds one or more contracts with these fields: + | Field | What to enter | |---|---| | **Contract year** | The CMS contract year the directory is for, `2024`–`2099`. One card per year; a year cannot appear twice. | -| **Contract ID** | The CMS contract number: `H` followed by digits, e.g. `H2168`. Unique within a year. It becomes the first path segment of the crawler URL. | +| **Contract ID** | The CMS contract number: `H` followed by digits, e.g. `H1234`. Unique within a year. It becomes the first path segment of the crawler URL. | | **InsurancePlan IDs** | Aidbox resource ids (not business identifiers) of the `InsurancePlan` resources that belong to this contract, one per line. Letters, digits, `-`, `.` and `_`, up to 64 characters; at least one id; duplicates are dropped. Only plans with `status=active` and the Plan-Net profile are exported. The in-scope network `Organization`s are derived from each plan's `network` references on every run, so there is nothing else to list. | | **CMS crawler URL** | Read-only: `MPF_PUBLIC_BASE_URL` + `///index.json`. **Copy** copies it. It is marked as a preview until the publication is saved and a sync has run. This is the URL to register with CMS. | @@ -29,7 +40,7 @@ Limits: 10 contract years, 20 contracts per year, 500 plan ids per contract. 1. In the year card, click **Add contract**. 2. Fill in **Contract ID** and **InsurancePlan IDs**. -3. Click **Save**. The toast *MPF publications updated* confirms the write. +3. Click **Save**. The toast *MPF settings updated* confirms the write. 4. Wait for the daily sync, or have an operator [trigger one](../run-payerbox/provider-directory-pipeline.md#sync-one-publication), then open the crawler URL and check that `index.json` lists bundle files. 5. Register the crawler URL with CMS. @@ -53,10 +64,11 @@ Each year publishes into its own folder, so publishing 2027 never touches the 20 **Save** is enabled only after a change. The page is checked before it is sent, and the first problem is shown as an error toast, for example: +- `"fhir.example.org/fhir" is not an absolute URL (e.g. https://fhir.example.org/fhir)` - `"20a7" is not a valid contract year (2024–2099)` -- `"h2168" is not a valid contract id (H followed by digits, e.g. H2168)` -- `Contract H2168 appears twice in year 2026` -- `H2168/2026: add at least one InsurancePlan id` +- `"h1234" is not a valid contract id (H followed by digits, e.g. H1234)` +- `Contract H1234 appears twice in year 2026` +- `H1234/2026: add at least one InsurancePlan id` - `"plan 1" is not a valid id (letters, digits, "-", ".", "_" — max 64 chars)` A save rejected with an access error is a deployment issue, not an input problem, see [Save fails with an access error](../run-payerbox/provider-directory-pipeline.md#save-fails-with-an-access-error). diff --git a/docs/run-payerbox/provider-directory-pipeline.md b/docs/run-payerbox/provider-directory-pipeline.md index 1327893..60a8f55 100644 --- a/docs/run-payerbox/provider-directory-pipeline.md +++ b/docs/run-payerbox/provider-directory-pipeline.md @@ -119,10 +119,9 @@ On the **portal**: | `MPF_EXPORT_CLIENT_ID`, `MPF_EXPORT_CLIENT_SECRET` (required) | `mpf-sync` and the secret from [step 1](#create-the-sync-client). | | `MPF_STORAGE_PROVIDER` (required) | Same provider as Aidbox's bulk storage. | | `MPF_STORAGE_BUCKET` (required) | The bucket the bundles and `index.json` are published to. | -| `MPF_PUBLIC_BASE_URL` (required) | Prefix for the bundle links in `index.json`: the portal's public endpoint (`https:///mpf-provider-directory`) or a public bucket. | -| `MPF_FULL_URL_BASE` (required) | FHIR base URL for bundle entries' `fullUrl`, e.g. `https://fhir./fhir`. | +| `MPF_PUBLIC_BASE_URL` | Prefix for the bundle links in `index.json`: the portal's public endpoint (`https:///mpf-provider-directory`) or a public bucket. Defaults to the portal's own public endpoint. | | `MPF_TRIGGER_CLIENT_IDS` (required) | Clients allowed to trigger runs. Set `admin-api,mpf-sync` (the default lacks `mpf-sync`). | -| `MPF_DEFAULT_CONTRACT`, `MPF_DEFAULT_YEAR` | Seed for the single built-in publication the pipeline uses until publications are saved in the [Admin portal](../fhir-app-portal/mpf-publications.md). Defaults: `H2168` and the current year. | +| `MPF_DEFAULT_CONTRACT`, `MPF_DEFAULT_YEAR` | Legacy. Read only to migrate settings saved by portal versions that predate contract years (one implicit publication). Not needed on a new installation: there is no built-in contract, and the year defaults to the current one. | | `MPF_BUCKET_PREFIX` | Source bucket root URL. Only `folder` refresh uses it. | | `MPF_ALERT_EMAIL_TO` | Failure-alert recipients via Aidbox `Notification` (needs its email provider configured). Unset: log-only. | | `MPF_STORAGE_ACCOUNT_ID` | On AWS: the `AwsAccount` resource id. On Azure: the storage account name. Not used on GCP. | @@ -130,7 +129,7 @@ On the **portal**: | `MPF_MAX_BUNDLE_BYTES` | Max bytes per bundle before rolling to a new file. Default 250 MB. | | `MPF_OUTPUT_DIR` | Local directory where bundles are staged. Default `./mpf-output`. | -Resource types and profile filters are fixed in the portal image. Changing them is a portal release (coordinate with Health Samurai), or use the [Custom export flow](#custom-export-flow). Contracts, contract years, and the `InsurancePlan` scope are configured in the [Admin portal](../fhir-app-portal/mpf-publications.md). +Resource types and profile filters are fixed in the portal image. Changing them is a portal release (coordinate with Health Samurai), or use the [Custom export flow](#custom-export-flow). Contracts, contract years, the `InsurancePlan` scope, and the FHIR base URL written into every bundle entry's `fullUrl` are configured in the [Admin portal](../fhir-app-portal/mpf-publications.md); nothing specific to one payer is built into the image. {% endstep %} {% step %} @@ -165,7 +164,7 @@ On AWS or Azure, the endpoint prefix is `/aws/storage//` or `/azure/wor ### Run and verify -Trigger a sync as `mpf-sync` (listed in `MPF_TRIGGER_CLIENT_IDS`, [step 3](#configure-the-environment)). An empty body regenerates every publication configured in the [Admin portal](../fhir-app-portal/mpf-publications.md); before the first save that is the one seeded from `MPF_DEFAULT_CONTRACT` and `MPF_DEFAULT_YEAR`. +First configure at least one publication in the [Admin portal](../fhir-app-portal/mpf-publications.md): a fresh installation has none, and a sync is rejected with `400` until one is saved. Then trigger a sync as `mpf-sync` (listed in `MPF_TRIGGER_CLIENT_IDS`, [step 3](#configure-the-environment)). An empty body regenerates every configured publication. {% code title="First run" %} ```bash @@ -206,7 +205,7 @@ The daily CronJob posts an empty body and regenerates every publication. To run curl -X POST https:///admin/mpf/sync \ -H "Authorization: Bearer $TOKEN" \ -H 'Content-Type: application/json' \ - -d '{"contract":"H2168","year":2027}' + -d '{"contract":"H1234","year":2027}' ``` {% endcode %} @@ -214,9 +213,9 @@ curl -X POST https:///admin/mpf/sync \ |---|---| | `{}` | Every configured publication. | | `{"year": 2027}` | Every contract of that year. | -| `{"contract": "H2168", "year": 2027}` | That one publication. | +| `{"contract": "H1234", "year": 2027}` | That one publication. | -A selector that matches nothing configured in [MPF Publications](../fhir-app-portal/mpf-publications.md) is rejected with `400` and the message *Add the contract year under Settings → MPF first*. One `$export` covers all selected publications; each is then filtered, bundled, and published separately, so one failing publication does not block the others. Details in the [API reference](../api-reference/operations/mpf-pipeline-api.md#post-adminmpfsync). +A selector that matches nothing configured in [MPF Publications](../fhir-app-portal/mpf-publications.md) is rejected with `400` and the message *Add the contract year under Settings → MPF first*; with nothing configured at all, the message is *MPF is not configured on this install yet*. One `$export` covers all selected publications; each is then filtered, bundled, and published separately, so one failing publication does not block the others. Details in the [API reference](../api-reference/operations/mpf-pipeline-api.md#post-adminmpfsync). ### Delete a retired publication's files @@ -230,7 +229,7 @@ On AWS or Azure use the equivalent `aws s3 rm --recursive` or `az storage blob d ### Save fails with an access error -The Admin portal stores publications as `DocumentReference/mpf-export-scope` on the admin Aidbox, written by the portal's `admin-api` client. If **Save** is rejected by Aidbox with an access error, `AccessPolicy/admin-api-document-reference` does not list `mpf-export-scope` among the allowed `DocumentReference` ids. Add it to the admin init bundle and re-apply. +The Admin portal stores the MPF settings as `DocumentReference/mpf-export-scope` on the admin Aidbox, written by the portal's `admin-api` client. If **Save** is rejected by Aidbox with an access error, `AccessPolicy/admin-api-document-reference` does not list `mpf-export-scope` among the allowed `DocumentReference` ids. Add it to the admin init bundle and re-apply. ## Custom export flow
FieldDescription