Index search parameter Operation¶

Canonical	`../OperationDefinition/index-search-parameter`
Status	draft · 1.26.0
Invocation	`POST [base]/$index-search-parameter`
Level	system
Affects state	yes -- not safe to repeat
Source	FSH · JSON

Start a background job that makes one search parameter usable for search on the store this tenant is bound to.

POST [base]/$index-search-parameter

This is an administrative operation, and a heavy one. The right that admits it is granted to an administrative role, not to an integration. It is the counterpart to $indexing-status, which names the parameters a store cannot yet answer for; this is what does something about one of them.

affectsState is true, in two separate ways. For a parameter declared by this estate, the operation first creates or updates that SearchParameter on the store: a write to the store's own conformance surface, performed before any indexing begins and not undone if the indexing that follows fails. It then starts a rebuild that reads every resource of the affected types. For a base specification parameter the definitional write does not happen and only the rebuild is started.

The reply says a job was accepted, and nothing more¶

jobStarted is true on every reply that exists at all. It is not a completion, not a promise of completion, and not a claim that the store can perform the work:

The rebuild runs in the background after the reply is sent, one parameter at a time, with a ceiling of four hours per parameter.
If the store turns out not to support reindexing, the job is discarded and nothing is reported. The caller still holds a 200 saying it started.
A rebuild that fails partway is logged where the platform is operated, not returned here.

Poll $indexing-status to learn what actually happened. There is no published operation to cancel a job, and no job identifier is returned that could name one.

Indexing is serialised per tenant¶

While any job is running for this tenant, a request to start another is refused at 409, even for a different search parameter. Read isIndexing from $indexing-status before asking, and treat the 409 as "come back later" rather than as an error in the request.

Choose the intensity deliberately. High loads the store hard enough to be felt by everything else using it, and is not a daytime setting on a store in clinical use.

Reading a refusal¶

Every refusal is an OperationOutcome:

HTTP	when
`400`	The body is not a `Parameters`, `searchParameterUrl` is absent or empty, `intensity` names no known level, or the canonical matches no parameter this store knows.
`409`	A job is already running for this tenant.
`500`	Anything else, including a failure to write the definition.

Match on the HTTP status. issue.code is exception on all three, so it separates nothing, and issue.diagnostics is a developer-facing sentence that quotes what was sent and is not a stable contract.

Request parameters¶

Parameter	Card.	Type	Documentation
`searchParameterUrl`	1..1	`string`	The canonical of the parameter to make usable, published and read as a `valueString` rather than a `uri`. It must EXACTLY equal the canonical of a parameter this store knows -- one declared by this estate, or one the store reports as built in. There is no wildcard, no prefix rule and no way to name a set: one call indexes one parameter. Take the value from a `searchParameterUrl` part of an `$indexing-status` reply rather than composing one. An absent part, a part carrying an empty string, and a part of any other type are each refused at `400`.
`intensity`	0..1	`string`	How hard the rebuild is allowed to push the store: `Low`, `Medium` or `High`, sent as a `valueString`. Omitted reads as `Low`. THE MATCH IS EXACT AND CASE-SENSITIVE -- `low` is refused at `400`. A part of any type other than a string is NOT refused: it is silently read as `Low`, so send a string and read the `intensity` echoed on the reply rather than assuming the level asked for is the level granted. `High` is not a daytime setting on a store in clinical use.

Response parameters¶

Parameter	Card.	Type	Documentation
`jobStarted`	1..1	`boolean`	That a job was accepted. It is `true` on every reply, because a request that is not accepted answers with an OperationOutcome instead. IT IS NOT A COMPLETION and not a claim that the work can be performed: a store that does not support reindexing has its job discarded afterwards, and this reply is unchanged. Ask `$indexing-status` for the outcome.
`searchParameterUrl`	1..1	`string`	The canonical the job was accepted for, echoed back exactly as sent.
`intensity`	1..1	`string`	The intensity the job was accepted at, as `Low`, `Medium` or `High`. This is the EFFECTIVE level, not an echo of the request: a caller that omitted the parameter, or sent it in a form that could not be read as a level, learns here that it got `Low`.
`message`	1..1	`string`	Fixed display words confirming the job was accepted. It carries no information the other three parameters do not. Display it; do not branch on it.