Particle Health Clinical Document Exchange

arazzo: 1.0.1
info:
  title: Particle Health Clinical Document Exchange
  summary: Submit a clinical document to the network, then retrieve it and list all documents on file for the patient.
  description: >-
    A clinical document exchange flow aligned with the HL7 Da Vinci Clinical Data
    Exchange (CDex) pattern. A document (for example a C-CDA, referral, or
    discharge summary) is pushed to the network, the stored document is read back
    by id to confirm receipt, and the full set of documents on file for the
    patient is listed. Each step inlines its request so the flow is self-contained.
  version: 1.0.0
  x-realizes-capability-ids:
  - BC-2900
  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
      capability_name: Health Information Management
      spec: particle-health-documents-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: authenticationApi
  url: ../openapi/particle-health-authentication-api-openapi.yml
  type: openapi
- name: documentsApi
  url: ../openapi/particle-health-documents-api-openapi.yml
  type: openapi
workflows:
- workflowId: clinical-document-exchange
  summary: Push a clinical document and confirm it by reading it back and listing the patient's documents.
  description: >-
    Submits a clinical document, reads the stored document by id, and lists all
    documents available for the patient.
  inputs:
    type: object
    required:
    - clientId
    - clientSecret
    - particlePatientId
    - document
    properties:
      clientId:
        type: string
        description: Particle client id used to obtain a bearer token.
      clientSecret:
        type: string
        description: Particle client secret used to obtain a bearer token.
      particlePatientId:
        type: string
        description: The Particle patient id the document belongs to.
      document:
        type: object
        description: The clinical document payload (content, type, and metadata) to submit.
  steps:
  - stepId: authenticate
    description: Exchange the client credentials for a bearer token used by every subsequent call.
    operationId: getAuthToken
    parameters:
    - name: client_id
      in: header
      value: $inputs.clientId
    - name: client_secret
      in: header
      value: $inputs.clientSecret
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      token: $response.body#/token
  - stepId: submitDocument
    description: Push the clinical document into the network for the patient.
    operationId: submitDocument
    requestBody:
      contentType: application/json
      payload: $inputs.document
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      documentId: $response.body#/id
  - stepId: readDocument
    description: Read the stored document back by id to confirm it was received and indexed.
    operationId: getDocument
    parameters:
    - name: id
      in: path
      value: $steps.submitDocument.outputs.documentId
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      document: $response.body
  - stepId: listPatientDocuments
    description: List every document currently on file for the patient.
    operationId: getPatientDocuments
    parameters:
    - name: id
      in: path
      value: $inputs.particlePatientId
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      documents: $response.body
  outputs:
    documentId: $steps.submitDocument.outputs.documentId
    documents: $steps.listPatientDocuments.outputs.documents