fhirseed

Documentation

Overview

Package fhirseed is the partner/Kit FHIR seed LOADER: a small HTTP client that drives a HAPI FHIR server through the seed sequence a partner (or the desktop Kit's shnkitd) needs before running scenarios — wait for readiness, create tenant partitions, install the operated-CQL prepop Library fixtures, warm the $populate engine, load provider-data persona bundles, and write/poll the seed-complete marker. It is deliberately thin: the heavy sandbox persona builders (full PersonaSet seeding, CQL Library construction) stay in the private canonical seeder; this package only carries the wire-level steps that are safe to publish.

Index

• func CRPrepopLibraries() map[string][]byte
• func ConformantSeedBundle() []byte
• func FreshenObservations(bundleJSON []byte) ([]byte, error)
• func ProviderDataSeedBundle() []byte
• func PutGlobalArtifact(ctx context.Context, base string, v shnsdk.Validator, rtype, id string, ...) error
• func SandboxLumbarLibrary() ([]byte, error)
• func SandboxProviderPersonasBundle() []byte
• type Client
  • func (c *Client) CreatePartitions(ctx context.Context, names []string) error
  • func (c *Client) InstallCRLibraries(ctx context.Context) error
  • func (c *Client) LoadProviderDataBundles(ctx context.Context, tenant string) error
  • func (c *Client) PostTransaction(ctx context.Context, tenant string, bundle []byte) error
  • func (c *Client) WaitForSeedMarker(ctx context.Context, tenant string, timeout time.Duration) error
  • func (c *Client) WaitReady(ctx context.Context, timeout time.Duration) error
  • func (c *Client) WarmUpPopulate(ctx context.Context) error
  • func (c *Client) WriteSeedMarker(ctx context.Context, tenant string) error

Functions

func CRPrepopLibraries

func CRPrepopLibraries() map[string][]byte

CRPrepopLibraries returns the operated-$populate prepop CQL Libraries, keyed by Library id (the filename's "Library-<id>.json" stem), with the file bytes as value. These are installed into the CR HAPI DEFAULT partition (HAPI-1318: a Library cannot live in a tenant partition); HAPI CR compiles each text/cql → ELM on first $populate reference. Single source of truth shared with the live conformance gate's stack orchestration, which installs the same files. Cribbed from br-payer a8bece4 (MIT).

func ConformantSeedBundle

func ConformantSeedBundle() []byte

ConformantSeedBundle returns a copy of the baked conformant Patient roster as a FHIR transaction Bundle (idempotent PUT entries). Patient-only: the ingress subject-bind reads only Patient by member identifier. Returns plain []byte (no error) like SandboxProviderPersonasBundle — it copies embedded bytes and cannot fail.

func FreshenObservations

func FreshenObservations(bundleJSON []byte) ([]byte, error)

FreshenObservations rewrites effectiveDateTime to now (UTC RFC3339) on every Observation entry of a transaction Bundle, leaving all other entries byte-identical (re-marshalled). This exists because prepop CQL enforces a 3-month ObservationLookBack: a fixture's static timestamp would age out and silently empty the QuestionnaireResponse, so freshening to now keeps the loaded data honestly recent.

func ProviderDataSeedBundle

func ProviderDataSeedBundle() []byte

ProviderDataSeedBundle returns a copy of the baked provider-data seed Bundle as a FHIR transaction Bundle (idempotent PUT entries). Like ConformantSeedBundle it copies embedded bytes and cannot fail — the published module never recomputes against its shn-sdk pin, so the downloadable seed/provider-personas.json and this output are the same frozen artifact.

func PutGlobalArtifact

func PutGlobalArtifact(ctx context.Context, base string, v shnsdk.Validator, rtype, id string, body []byte) error

PutGlobalArtifact $validates (FR-36; warnings OK — Valid counts only error/fatal) then PUTs a non-partitionable knowledge artifact (e.g. Library) to the given base, typically …/fhir/DEFAULT. Sibling of (*Client).InstallCRLibraries for artifacts callers build themselves, such as SandboxLumbarLibrary. No scoped id: DEFAULT is not partitioned, so the usual cross-partition id-uniqueness concern does not apply.

func SandboxLumbarLibrary

func SandboxLumbarLibrary() ([]byte, error)

SandboxLumbarLibrary builds the operated-$populate prepop CQL Library the sandbox DTR questionnaire's cqf-library canonical points at (http://smarthealth.network/fhir/Library/LumbarMRICQL — see the SDK's sandbox questionnaire). Deployments running native DTR (PROVIDER_DTR_NATIVE) against the sandbox questionnaire world must install it into the engine's DEFAULT partition (a Library is a non-partitionable knowledge artifact) or $populate fails with "Could not load source for library LumbarMRICQL". The name/version/canonical tail MUST equal the CQL header `library LumbarMRICQL version '1.0.0'` or the clinical-reasoning engine cannot load the source. Distinct from CRPrepopLibraries(): those are the payer-engine prepop set, installed wholesale by existing consumers; this is the provider-tenant operated-CQL library.

The retrieve uses a codesystem/code declaration (a direct code, not a ValueSet — no terminology expansion, so evaluation stays deterministic), built from the same shnsdk constants as the seeded Observations/Procedures/DiagnosticReports. Direct navigation (First([Resource: code]).value) is used throughout; the query-comprehension form (`First(...) O return …`) does not survive HAPI's CQL translator, so it is avoided everywhere. PriorSurgery covers every code in shnsdk.ProcedureValueSet by iteration, so a future additional SNOMED code is automatically included without a manual CQL edit.

func SandboxProviderPersonasBundle

func SandboxProviderPersonasBundle() []byte

SandboxProviderPersonasBundle returns a copy of the baked provider-tenant persona transaction Bundle (PUT entries — idempotent to re-POST).

Types

type Client

type Client struct {
	// Base is the FHIR base URL WITHOUT a tenant, e.g. http://localhost:8080/fhir. Tenant-taking
	// methods address {Base}/{tenant}; never pass a tenant-qualified Base.
	Base string
	// HTTP is the client used for all requests. nil uses http.DefaultClient.
	HTTP *http.Client
	// Logf receives progress/log lines. nil is silent.
	Logf func(format string, args ...any)
}

Client drives a HAPI FHIR server through the seed-loader flow.

func (*Client) CreatePartitions

func (c *Client) CreatePartitions(ctx context.Context, names []string) error

CreatePartitions POSTs $partition-management-create-partition for each named partition, using stable deterministic integer ids starting at 101.

Operation path: POST {Base}/DEFAULT/$partition-management-create-partition Payload: {"resourceType":"Parameters","parameter":[{"name":"id","valueInteger":<n>},{"name":"name","valueCode":<name>}]}

func (*Client) InstallCRLibraries

func (c *Client) InstallCRLibraries(ctx context.Context) error

InstallCRLibraries PUTs the embedded prepop CQL Libraries (CRPrepopLibraries) into DEFAULT (HAPI-1318: a Library cannot live in a tenant partition). HAPI CR compiles each text/cql → ELM on first $populate reference. Idempotent (PUT by id).

func (*Client) LoadProviderDataBundles

func (c *Client) LoadProviderDataBundles(ctx context.Context, tenant string) error

LoadProviderDataBundles loads every shnsdk.ProviderDataPersonas() transaction Bundle into the given tenant by POSTing the published bytes as a FHIR transaction — the SAME bytes a partner would POST to their own SoR. Each bundle is freshened (FreshenObservations) before the POST.

func (*Client) PostTransaction

func (c *Client) PostTransaction(ctx context.Context, tenant string, bundle []byte) error

PostTransaction POSTs a FHIR transaction Bundle to {Base}/{tenant} and fails on a non-2xx.

func (*Client) WaitForSeedMarker

func (c *Client) WaitForSeedMarker(ctx context.Context, tenant string, timeout time.Duration) error

WaitForSeedMarker blocks until the tenant's Basic/seed-complete marker is present — the signal that seeding finished. Polls every 5s up to timeout.

func (*Client) WaitReady

func (c *Client) WaitReady(ctx context.Context, timeout time.Duration) error

WaitReady polls {Base}/DEFAULT/metadata with GET until it returns HTTP 200, or timeout elapses. A cold HAPI boot (including US Core IG download) can take several minutes. Progress is logged every 10 seconds.

func (*Client) WarmUpPopulate

func (c *Client) WarmUpPopulate(ctx context.Context) error

WarmUpPopulate compiles each prepop library's ELM so the first real $populate is not the cold compile. Measured: GET DEFAULT/Library/<id>/$evaluate (no subject) compiles + caches the canonical-keyed ELM that $populate reuses (cold first $populate 5.37s → 4.38s after warm-up). A non-2xx is a hard failure (the engine is known-broken before scenarios run).

func (*Client) WriteSeedMarker

func (c *Client) WriteSeedMarker(ctx context.Context, tenant string) error

WriteSeedMarker PUTs a Basic/seed-complete resource into the tenant partition. Its presence is the "all seeding done" signal a readiness probe polls for (WaitForSeedMarker) — distinct from "seeding started", which a per-partition data check would falsely report. Basic is profile-free, so no $validate.