Clinical pathway custom metadata

Summary

Clinical pathways now support custom metadata (key/value pairs), consistent with contacts, products, and invoices:

• ClinicalPathway.metadata — read entries as [MetadataEntry] (key, value) on clinicalPathway and clinicalPathways.
• createClinicalPathway — optional metadata on clinicalPathwayData when creating a pathway.
• updatePathwayMetadata — batch upsert of one or more entries on an existing pathway.

Limits match other metadata APIs: max key length 40, max value length 500, up to 50 keys per pathway.

This release is additive for existing pathway clients. Omit metadata from queries and inputs if you do not use it.

Access requires the EPISODES_OF_CARE feature segment and the usual pathway permissions (seePathways to read, editPathways to write).

There is no deletePathwayMetadata mutation and no metadata filter on pathway list queries. Values must be non-empty after sanitisation, so you cannot clear a key by sending an empty string.

What changed

Read on ClinicalPathway:

query ClinicalPathwayMetadata($pathwayId: ID!) {
  clinicalPathway(id: $pathwayId) {
    id
    metadata {
      key
      value
    }
  }
}

Write on create:

mutation CreatePathwayWithMetadata(
  $episodeId: ID!
  $clinicalPathwayData: CreateClinicalPathwayDataInput!
) {
  createClinicalPathway(
    episodeId: $episodeId
    clinicalPathwayData: $clinicalPathwayData
  ) {
    data {
      id
      metadata {
        key
        value
      }
    }
    error
  }
}

Pass optional metadata: [{ key: "…", value: "…" }, …] inside clinicalPathwayData.

Batch upsert on an existing pathway:

mutation UpdatePathwayMetadata(
  $pathwayId: ID!
  $metadata: [MetadataEntryInput!]!
) {
  updatePathwayMetadata(pathwayId: $pathwayId, metadata: $metadata) {
    data {
      id
      metadata {
        key
        value
      }
    }
    error
  }
}

MetadataEntryInput:

• key: String!
• value: String!

Integration guidance

• Reading metadata: Request metadata { key value } on clinicalPathway or clinicalPathways.
• Setting metadata at create: Include metadata in createClinicalPathway input when you already create pathways via the Public API.
• Updating metadata: Call updatePathwayMetadata with pathwayId and at least one { key, value } entry. Keys in the request are upserted (inserted or updated). Keys not included in the request are left unchanged — the mutation does not clear omitted keys.
• Duplicate keys in one request: The batch is rejected (for example with a message containing duplicate). No partial apply; existing stored metadata remains as before the failed call.
• Key limit: You cannot exceed 50 distinct keys per pathway. Adding keys that would exceed the limit returns an error in the mutation payload.
• Sanitisation: Keys and values are sanitised using the same rules as contact, product, and invoice metadata before storage.
• updateClinicalPathway does not accept metadata. Use updatePathwayMetadata for changes after create.

Mutation errors: Validation failures and missing pathways return HTTP 4xx responses with error populated in the GraphQL payload (for example 400 for validation problems and 404 when the pathway is not found), instead of surfacing only as GraphQL 500 errors.

Example response

{
  "data": {
    "updatePathwayMetadata": {
      "data": {
        "id": "507f1f77bcf86cd799439011",
        "metadata": [
          { "key": "policy_code", "value": "POL-001" },
          { "key": "scheme_code", "value": "SCH-99" }
        ]
      },
      "error": null
    }
  }
}

Migration

No breaking schema changes for existing clinicalPathway / clinicalPathways clients that do not use metadata. If you store partner references on pathways only in Semble today, you can now read them via metadata and upsert them with updatePathwayMetadata instead of maintaining a separate id map outside Semble.