Projo FHIR Documentation
0.1.0 - ci-build Switzerland flag

Projo FHIR Documentation - Local Development build (v0.1.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

Developer Reference

Developer Reference

FHIRPath evaluation (ADR 0008)

fhirpath.js v4.11.0 with R4 model context, used by sidecar to evaluate sdc-questionnaire-constraint extensions before recording answers. Trust boundary: FHIRPath expressions are authored by clinical staff on the trusted Questionnaire; patient input never constructs or modifies expressions.

SDC constraint validation

sdc-questionnaire-constraint extension on Questionnaire items. Sub-extensions: key, severity (error/warning), expression (text/fhirpath), human, _human (translation). Engine: fhirpath (HL7/fhirpath.js). Fail-safe: error-severity evaluator exception treated as failed; answer rejected, patient re-prompted.

Idempotency patterns

  • Deterministic identifiers on extracted/routing resources + If-None-Exist conditional creates
  • Provenance meta.tag + entity query as idempotency key (R4 Provenance has no identifier)
  • If-Match optimistic locking on all updateWithRetry paths (refetch on 412)
  • If-None-Exist conditional creates for reverse CRs, reminder CRs, inbound Communications

Transaction bundle shapes

  • Outbound CR+Task: POST CommunicationRequest (urn:uuid fullUrl) + PUT Task (with If-Match and CR urn:uuid in output[])
  • Extraction: POST {Type} with If-None-Exist per resource + POST Provenance + PATCH Binary (for writeback)
  • Inbound+reverseCR: POST Communication + POST CommunicationRequest (If-None-Exist)
  • Inbound+answer: PUT QR (If-Match) + POST Communication

Configurable namespace

EXTENSION_BASE_URL (default https://firearrow.io/fhir/StructureDefinition) controls the transport extension namespace. Projo-owned extensions (delivery-time, web-answer-token, next-reminder-timestamp, default-plan, plan-slot, preferred-language, extraction-writeback) are hardcoded to https://projo.evoleen.com/fhir/StructureDefinition and are NOT configurable.

Environment variables (selected)

Table of key env vars:

  • FHIR_BASE_URL: Fire Arrow endpoint
  • FIRE_ARROW_IDENTIFIER_URI: Azure AD identifier URI for auth
  • EXTENSION_BASE_URL: Transport extension namespace (default firearrow.io)
  • COMMUNICATION_MEDIUM_SYSTEM/CODE: Medium code system + code
  • DEFAULT_IDENTITY_RESOURCE_TYPE: Patient (default)
  • TASK_MAX_DELIVERY_GRACE_MINUTES: 10080 (7 days)
  • TASK_DEFAULT_RESPONSE_WINDOW_MINUTES: 1440 (24h)
  • CLINICAL_EXTRACTION_RECONCILE_WINDOW_HOURS: 168 (7 days)
  • WEB_ANSWER_BASE_URL: Web channel URL (empty = disabled)
  • WEBHOOK_INLINE_TIMEOUT_MS: 8000
  • WEBHOOK_CB_COOLDOWN_MS: 60000

Standard HL7 extensions consumed

  • http://hl7.org/fhir/StructureDefinition/timezone (on CarePlan, Patient)
  • http://hl7.org/fhir/StructureDefinition/translation (localized text)
  • http://hl7.org/fhir/StructureDefinition/ordinalValue (scoring)
  • http://hl7.org/fhir/StructureDefinition/questionnaire-hidden (hidden pre-populated items)
  • http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaire-* (extraction, constraints, media, calculatedExpression)