MPF Pipeline

An optional module of the FHIR App Portal, built into its image and enabled with MPF_ENABLED=true. It builds a CMS Plan-Net provider directory and publishes it as static FHIR Bundle files for the CMS Medicare Plan Finder (MPF) crawler.

Data flow:

All bucket access goes through Aidbox-signed URLs, so neither bucket needs to be public. The pipeline is triggered over HTTP, typically by a daily Kubernetes CronJob. A production-scale run takes upwards of half an hour. Endpoint details live in the API reference.

This page covers the one-time technical setup. Which contracts, contract years, and plans get published is configured afterwards in the Admin portal, see MPF Publications.

Prerequisites

• Aidbox access (Payerbox's FHIR engine).
• Two buckets: a source bucket for $export output and a storage bucket for the final files.
• Aidbox connected to both buckets. All bucket access goes through it. GCP and Azure use workload identity, AWS an AwsAccount resource. File storage in the Aidbox docs covers the setups and IAM roles. Step 4 verifies the setup.

Set up

{
  "resourceType": "Client",
  "id": "mpf-sync",
  "secret": "<secret>",
  "grant_types": ["client_credentials"],
  "auth": { "client_credentials": { "access_token_expiration": 3600 } }
}

{
  "resourceType": "AccessPolicy",
  "id": "mpf-sync-policy",
  "engine": "matcho",
  "matcho": {
    "$one-of": [
      { "client": { "id": "mpf-sync" }, "request-method": "get",    "uri": "#^/fhir/\\$export(\\?|$)" },
      { "client": { "id": "mpf-sync" }, "request-method": "get",    "uri": "#^/fhir/\\$export-status/" },
      { "client": { "id": "mpf-sync" }, "request-method": "put",    "uri": "#^/Notification/" },
      { "client": { "id": "mpf-sync" }, "request-method": "post",   "uri": "#^/Notification/[^/]+/\\$send$" },
      { "client": { "id": "mpf-sync" }, "request-method": "post",   "uri": "#^/gcp/workload-identity/storage/" },
      { "client": { "id": "mpf-sync" }, "request-method": "get",    "uri": "#^/gcp/workload-identity/storage/" },
      { "client": { "id": "mpf-sync" }, "request-method": "delete", "uri": "#^/gcp/workload-identity/storage/" },
      { "client": { "id": "mpf-sync" }, "request-method": "post",   "uri": "#^/aws/storage/" },
      { "client": { "id": "mpf-sync" }, "request-method": "get",    "uri": "#^/aws/storage/" },
      { "client": { "id": "mpf-sync" }, "request-method": "delete", "uri": "#^/aws/storage/" },
      { "client": { "id": "mpf-sync" }, "request-method": "post",   "uri": "#^/azure/workload-identity/storage/" },
      { "client": { "id": "mpf-sync" }, "request-method": "get",    "uri": "#^/azure/workload-identity/storage/" },
      { "client": { "id": "mpf-sync" }, "request-method": "delete", "uri": "#^/azure/workload-identity/storage/" }
    ]
  }
}

# get a token
TOKEN=$(curl -s -X POST https://<aidbox>/auth/token \
  -H 'Content-Type: application/json' \
  -d '{"grant_type":"client_credentials","client_id":"mpf-sync","client_secret":"<secret>"}' \
  | jq -r .access_token)

# get a presigned upload URL
URL=$(curl -s -X POST https://<aidbox>/gcp/workload-identity/storage/<storage bucket> \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"filename":"_probe.json"}' | jq -r .url)

# put data through it
curl -i -X PUT "$URL" \
  -H 'Content-Type: application/json' -d '{"probe":true}'

TOKEN=$(curl -s -X POST https://<aidbox>/auth/token \
  -H 'Content-Type: application/json' \
  -d '{"grant_type":"client_credentials","client_id":"mpf-sync","client_secret":"<secret>"}' \
  | jq -r .access_token)

curl -X POST https://<portal>/admin/mpf/sync \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{}'

Operate publications

Day-to-day publication changes (contracts, contract years, plan scope) are made in the Admin portal, see MPF Publications. The tasks below are the terminal-side counterparts.

Sync one publication

The daily CronJob posts an empty body and regenerates every publication. To run a subset, pass a selector, using a token minted as in step 5:

curl -X POST https://<portal>/admin/mpf/sync \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"contract":"H2168","year":2027}'

A selector that matches nothing configured in MPF Publications 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.

Delete a retired publication's files

Removing a publication in the Admin portal stops future syncs from regenerating it, but deliberately leaves the already-published files in the storage bucket, because CMS may still be crawling that URL. Once CMS has been told the directory is retired, delete the folder by hand:

gsutil -m rm -r gs://<storage bucket>/<contract>/<year>/

On AWS or Azure use the equivalent aws s3 rm --recursive or az storage blob delete-batch command.

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.

Custom export flow

The prebuilt pipeline covers the whole path out of the box. A custom flow (different scope, resource types, or post-processing) can reuse the same $export, client, policy, and storage setup. A runnable example lives in the Aidbox examples repository.

Related