Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/api-reference/operations/mpf-pipeline-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`.

<table>
<thead><tr><th width="140">Field</th><th>Description</th></tr></thead>
Expand Down
26 changes: 19 additions & 7 deletions docs/fhir-app-portal/mpf-publications.md
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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 + `/<ResourceType>/<id>`. Enter the public FHIR base URL of this installation, e.g. `https://fhir.<payer-domain>/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` + `/<contract>/<year>/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. |

Expand All @@ -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.

Expand All @@ -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).
Expand Down
17 changes: 8 additions & 9 deletions docs/run-payerbox/provider-directory-pipeline.md
Original file line number Diff line number Diff line change
Expand Up @@ -119,18 +119,17 @@ 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://<portal>/mpf-provider-directory`) or a public bucket. |
| `MPF_FULL_URL_BASE` (required) | FHIR base URL for bundle entries' `fullUrl`, e.g. `https://fhir.<payer-domain>/fhir`. |
| `MPF_PUBLIC_BASE_URL` | Prefix for the bundle links in `index.json`: the portal's public endpoint (`https://<portal>/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. |
| `MPF_BUNDLE_SIZE` | Max entries per bundle. Default `1000`. |
| `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 %}
Expand Down Expand Up @@ -165,7 +164,7 @@ On AWS or Azure, the endpoint prefix is `/aws/storage/<account>/` 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
Expand Down Expand Up @@ -206,17 +205,17 @@ The daily CronJob posts an empty body and regenerates every publication. To run
curl -X POST https://<portal>/admin/mpf/sync \
-H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' \
-d '{"contract":"H2168","year":2027}'
-d '{"contract":"H1234","year":2027}'
```
{% endcode %}

| Body | Runs |
|---|---|
| `{}` | 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

Expand All @@ -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

Expand Down
Loading