Medplum Upsert Patient

arazzo: 1.0.1
info:
  title: Medplum Upsert Patient
  summary: Update a Patient matched by identifier, or create it, in one FHIR conditional update.
  description: >-
    A common master-patient-index pattern, done in a single call. FHIR conditional
    update (PUT /fhir/R4/Patient?identifier=...) updates the one Patient that
    matches the search criteria, or creates it when nothing matches. Medplum's
    OpenAPI declares it as operationId conditionalUpdate on
    PUT /fhir/R4/{resourceType} with a form-exploded `criteria` query parameter:
    200 when a match was updated, 201 when the resource was created, 412 when the
    criteria match more than one resource (nothing is written).
  version: 2.0.0
  x-realizes-capability-ids:
  - BC-2900.60
  x-capability-derivation:
    method: 'deterministic join: sourceDescriptions -> per-tag OpenAPI -> tag/capability edge. No classification at this step.'
    min_confidence: 0.7
    sources:
    - capability_id: BC-2900.60
      capability_name: Healthcare Interoperability Operations
      spec: medplum-fhir-api-openapi.yml
      confidence: 0.7
    model: Turbo EA Capabilities by Vincent Verdet — Turbo EA, https://github.com/vincentmakes/turbo-ea-capabilities, CC BY 4.0
sourceDescriptions:
- name: fhirApi
  url: ../openapi/medplum-fhir-api-openapi.yml
  type: openapi
workflows:
- workflowId: upsert-patient
  summary: Upsert a Patient keyed on a business identifier with FHIR conditional update.
  description: >-
    Sends PUT /fhir/R4/Patient?identifier=<system>|<value>. Medplum updates the
    matching Patient (200) or creates a new one (201); multiple matches return 412.
  inputs:
    type: object
    required:
    - identifierSystem
    - identifierValue
    - familyName
    - givenName
    properties:
      identifierSystem:
        type: string
        description: The identifier system URI (for example an MRN namespace).
      identifierValue:
        type: string
        description: The identifier value within that system.
      familyName:
        type: string
        description: The patient's family (last) name to write.
      givenName:
        type: string
        description: The patient's given (first) name to write.
      birthDate:
        type: string
        description: The patient's date of birth in YYYY-MM-DD form.
  steps:
  - stepId: upsertPatient
    description: >-
      Conditional update of Patient on identifier. The body carries the same
      identifier so a created Patient matches the criteria next time.
    operationId: conditionalUpdate
    parameters:
    - name: resourceType
      in: path
      value: Patient
    - name: criteria
      in: query
      value:
        identifier: '{$inputs.identifierSystem}|{$inputs.identifierValue}'
    requestBody:
      contentType: application/fhir+json
      payload:
        resourceType: Patient
        identifier:
        - system: $inputs.identifierSystem
          value: $inputs.identifierValue
        name:
        - family: $inputs.familyName
          given:
          - $inputs.givenName
        birthDate: $inputs.birthDate
    successCriteria:
    - condition: $statusCode == 200 || $statusCode == 201
    outputs:
      patientId: $response.body#/id
      created: $statusCode == 201
  outputs:
    patientId: $steps.upsertPatient.outputs.patientId