{
  "resourceType": "OperationDefinition",
  "id": "index-search-parameter",
  "url": "https://fhir.apps.health/OperationDefinition/index-search-parameter",
  "title": "Index search parameter",
  "description": "Start a background job that makes one search parameter usable for search on the store this tenant is\nbound to.\n\n    POST [base]/$index-search-parameter\n\n**This is an administrative operation**, and a heavy one. The right that admits it is granted to an\nadministrative role, not to an integration. It is the counterpart to\n[`$indexing-status`](OperationDefinition-indexing-status.md), which names the parameters a store\ncannot yet answer for; this is what does something about one of them.\n\n**`affectsState` is `true`, in two separate ways.** For a parameter declared by this estate, the\noperation first creates or updates that `SearchParameter` on the store: a write to the store's own\nconformance surface, performed before any indexing begins and not undone if the indexing that\nfollows fails. It then starts a rebuild that reads every resource of the affected types. For a base\nspecification parameter the definitional write does not happen and only the rebuild is started.\n\n### The reply says a job was accepted, and nothing more\n\n`jobStarted` is `true` on every reply that exists at all. It is not a completion, not a promise of\ncompletion, and not a claim that the store can perform the work:\n\n- The rebuild runs in the background after the reply is sent, one parameter at a time, with a\n  ceiling of four hours per parameter.\n- If the store turns out not to support reindexing, **the job is discarded and nothing is\n  reported**. The caller still holds a `200` saying it started.\n- A rebuild that fails partway is logged where the platform is operated, not returned here.\n\nPoll [`$indexing-status`](OperationDefinition-indexing-status.md) to learn what actually happened.\nThere is no published operation to cancel a job, and no job identifier is returned that could name\none.\n\n### Indexing is serialised per tenant\n\nWhile any job is running for this tenant, a request to start another is refused at `409`, **even for\na different search parameter**. Read `isIndexing` from `$indexing-status` before asking, and treat\nthe `409` as \"come back later\" rather than as an error in the request.\n\nChoose the intensity deliberately. `High` loads the store hard enough to be felt by everything else\nusing it, and is not a daytime setting on a store in clinical use.\n\n### Reading a refusal\n\nEvery refusal is an [`OperationOutcome`](https://hl7.org/fhir/R4/operationoutcome.html):\n\n| HTTP | when |\n|---|---|\n| `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. |\n| `409` | A job is already running for this tenant. |\n| `500` | Anything else, including a failure to write the definition. |\n\n**Match on the HTTP status.** `issue.code` is `exception` on all three, so it separates nothing, and\n`issue.diagnostics` is a developer-facing sentence that quotes what was sent and is not a stable\ncontract.",
  "name": "IndexSearchParameter",
  "status": "draft",
  "kind": "operation",
  "experimental": false,
  "publisher": "WELLSTAR Technologies Corp.",
  "affectsState": true,
  "code": "index-search-parameter",
  "system": true,
  "type": false,
  "instance": false,
  "parameter": [
    {
      "name": "searchParameterUrl",
      "use": "in",
      "min": 1,
      "max": "1",
      "type": "string",
      "documentation": "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`."
    },
    {
      "name": "intensity",
      "use": "in",
      "min": 0,
      "max": "1",
      "type": "string",
      "documentation": "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."
    },
    {
      "name": "jobStarted",
      "use": "out",
      "min": 1,
      "max": "1",
      "type": "boolean",
      "documentation": "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."
    },
    {
      "name": "searchParameterUrl",
      "use": "out",
      "min": 1,
      "max": "1",
      "type": "string",
      "documentation": "The canonical the job was accepted for, echoed back exactly as sent."
    },
    {
      "name": "intensity",
      "use": "out",
      "min": 1,
      "max": "1",
      "type": "string",
      "documentation": "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`."
    },
    {
      "name": "message",
      "use": "out",
      "min": 1,
      "max": "1",
      "type": "string",
      "documentation": "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."
    }
  ]
}