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`.
| Field | Description |
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.

+## 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