Tiro.health Implementation Guide
0.1.0 - ci-build

Tiro.health Implementation Guide - Local Development build (v0.1.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

Provenance

Data Provenance Tracking

Overview

Atticus uses FHIR Provenance resources to track the origin and lifecycle of data entered into forms. This enables full auditability and transparency about how each data field was populated, whether by manual user input, AI algorithms, calculations, or data imports.

Architecture

Core Concepts

  1. Provenance Resource: A FHIR resource that records the origin and changes to data
  2. Target Element: Links provenance to specific QuestionnaireResponse items using extensions
  3. Activity Codes: Describe what type of operation was performed
  4. Agents: Identify who or what performed the action

Key Components

  • CodeSystem: FormActivity (http://fhir.tiro.health/CodeSystem/form-activity) - Activities specific to form field population
  • CodeSystem: ISO 21089 Lifecycle (http://terminology.hl7.org/CodeSystem/iso-21089-lifecycle) - Standard lifecycle events
  • Extension: targetElement (http://hl7.org/fhir/StructureDefinition/targetElement) - Links provenance to specific response items

Activity Types

User Input Activities

Code Display Description
user User input Manually entered data by the user
manual Manual input Manually entered data without system assistance

Static Value Activities

Code Display Description
static Static value Preconfigured value picked by a user
preset Preset Populated by a preset configuration
initial-value Initial value Populated by an initial value definition

Calculation Activities

Code Display Description
calculation Calculation A calculation has been performed based on an expression
fhirpath FHIRPath calculation A calculation performed using FHIRPath expression

AI-Powered Activities

Code Display Description
ai AI population An AI algorithm has generated field values
speech-population Speech-based population Speech-to-text solution generated the values
ai-clipboard AI Clipboard AI engine processed clipboard content

Data Import Activities

Code Display Description
data-import Data Import Values imported from other resources or external servers

Lifecycle Activities

Code Display Description
submit Submit Form submitted for review or final processing
amend Amend Form amended or updated after initial submission

ISO 21089 Lifecycle Events

Atticus uses standard ISO 21089 lifecycle events in combination with form-specific activities:

  • originate: Initial creation of data (most form population activities)
  • amend: Modification of existing data
  • merge: Combining data from multiple sources

Implementation

Creating Provenance Records

When a form field is populated, a Provenance resource is created with:

  1. Target: Reference to the QuestionnaireResponse with targetElement extension pointing to the specific item.id
  2. Activity: Coding array combining form-specific activity and ISO 21089 lifecycle event
  3. Recorded: Timestamp when the activity occurred
  4. Agent: Who or what performed the action

Example: User Input

{
  "resourceType" : "Provenance",
  "id" : "prov-001",
  "meta" : {
    "profile" : [
      🔗 "http://fhir.tiro.health/StructureDefinition/form-provenance"
    ]
  },
  "text" : {
    "status" : "generated",
    "div" : "<div xmlns=\"http://www.w3.org/1999/xhtml\"><p class=\"res-header-id\"><b>Generated Narrative: Provenance prov-001</b></p><a name=\"prov-001\"> </a><a name=\"hcprov-001\"> </a><div style=\"display: inline-block; background-color: #d9e0e7; padding: 6px; margin: 4px; border: 1px solid #8da1b4; border-radius: 5px; line-height: 60%\"><p style=\"margin-bottom: 0px\"/><p style=\"margin-bottom: 0px\">Profile: <a href=\"StructureDefinition-form-provenance.html\">Form Provenance</a></p></div><p>Provenance for <a href=\"QuestionnaireResponse/qr-123\">QuestionnaireResponse/qr-123</a></p><p>Summary</p><table class=\"grid\"><tr><td>Recorded</td><td>2025-10-29 10:30:00+0000</td></tr><tr><td>Activity</td><td><span title=\"Codes:{http://fhir.tiro.health/CodeSystem/form-activity user}, {http://terminology.hl7.org/CodeSystem/iso-21089-lifecycle originate}\">Manually entered data by the user</span></td></tr></table><p><b>Agents</b></p><table class=\"grid\"><tr><td><b>who</b></td></tr><tr><td><a href=\"Practitioner/pract-789\">Practitioner/pract-789</a></td></tr></table></div>"
  },
  "target" : [
    {
      "extension" : [
        {
          "url" : "http://hl7.org/fhir/StructureDefinition/targetElement",
          "valueUri" : "item-456"
        }
      ],
      "reference" : "QuestionnaireResponse/qr-123"
    }
  ],
  "recorded" : "2025-10-29T10:30:00Z",
  "activity" : {
    "coding" : [
      {
        "system" : "http://fhir.tiro.health/CodeSystem/form-activity",
        "code" : "user",
        "display" : "User input"
      },
      {
        "system" : "http://terminology.hl7.org/CodeSystem/iso-21089-lifecycle",
        "code" : "originate",
        "display" : "Originate/Retain Record Lifecycle Event"
      }
    ],
    "text" : "Manually entered data by the user"
  },
  "agent" : [
    {
      "who" : {
        "reference" : "Practitioner/pract-789"
      }
    }
  ]
}

Example: AI Clipboard Population

{
  "resourceType" : "Provenance",
  "id" : "prov-002",
  "meta" : {
    "profile" : [
      🔗 "http://fhir.tiro.health/StructureDefinition/form-provenance"
    ]
  },
  "text" : {
    "status" : "generated",
    "div" : "<div xmlns=\"http://www.w3.org/1999/xhtml\"><p class=\"res-header-id\"><b>Generated Narrative: Provenance prov-002</b></p><a name=\"prov-002\"> </a><a name=\"hcprov-002\"> </a><div style=\"display: inline-block; background-color: #d9e0e7; padding: 6px; margin: 4px; border: 1px solid #8da1b4; border-radius: 5px; line-height: 60%\"><p style=\"margin-bottom: 0px\"/><p style=\"margin-bottom: 0px\">Profile: <a href=\"StructureDefinition-form-provenance.html\">Form Provenance</a></p></div><p>Provenance for <a href=\"QuestionnaireResponse/qr-123\">QuestionnaireResponse/qr-123</a></p><p>Summary</p><table class=\"grid\"><tr><td>Recorded</td><td>2025-10-29 10:32:00+0000</td></tr><tr><td>Activity</td><td><span title=\"Codes:{http://fhir.tiro.health/CodeSystem/form-activity ai-clipboard}, {http://terminology.hl7.org/CodeSystem/iso-21089-lifecycle originate}\">An AI-engine has processed clipboard content</span></td></tr></table><p><b>Agents</b></p><table class=\"grid\"><tr><td><b>who</b></td><td><b>On Behalf Of</b></td></tr><tr><td>AI Engine</td><td><a href=\"Practitioner/pract-789\">Practitioner/pract-789</a></td></tr></table></div>"
  },
  "target" : [
    {
      "extension" : [
        {
          "url" : "http://hl7.org/fhir/StructureDefinition/targetElement",
          "valueUri" : "item-789"
        }
      ],
      "reference" : "QuestionnaireResponse/qr-123"
    }
  ],
  "recorded" : "2025-10-29T10:32:00Z",
  "activity" : {
    "coding" : [
      {
        "system" : "http://fhir.tiro.health/CodeSystem/form-activity",
        "code" : "ai-clipboard",
        "display" : "AI Clipboard"
      },
      {
        "system" : "http://terminology.hl7.org/CodeSystem/iso-21089-lifecycle",
        "code" : "originate",
        "display" : "Originate/Retain Record Lifecycle Event"
      }
    ],
    "text" : "An AI-engine has processed clipboard content"
  },
  "agent" : [
    {
      "who" : {
        "display" : "AI Engine"
      },
      "onBehalfOf" : {
        "reference" : "Practitioner/pract-789"
      }
    }
  ]
}

Example: FHIRPath Calculation

{
  "resourceType" : "Provenance",
  "id" : "prov-003",
  "meta" : {
    "profile" : [
      🔗 "http://fhir.tiro.health/StructureDefinition/form-provenance"
    ]
  },
  "text" : {
    "status" : "generated",
    "div" : "<div xmlns=\"http://www.w3.org/1999/xhtml\"><p class=\"res-header-id\"><b>Generated Narrative: Provenance prov-003</b></p><a name=\"prov-003\"> </a><a name=\"hcprov-003\"> </a><div style=\"display: inline-block; background-color: #d9e0e7; padding: 6px; margin: 4px; border: 1px solid #8da1b4; border-radius: 5px; line-height: 60%\"><p style=\"margin-bottom: 0px\"/><p style=\"margin-bottom: 0px\">Profile: <a href=\"StructureDefinition-form-provenance.html\">Form Provenance</a></p></div><p>Provenance for <a href=\"QuestionnaireResponse/qr-123\">QuestionnaireResponse/qr-123</a></p><p>Summary</p><table class=\"grid\"><tr><td>Recorded</td><td>2025-10-29 10:33:00+0000</td></tr><tr><td>Activity</td><td><span title=\"Codes:{http://fhir.tiro.health/CodeSystem/form-activity fhirpath}, {http://terminology.hl7.org/CodeSystem/iso-21089-lifecycle originate}\">A calculation has been performed using a FHIRPath expression</span></td></tr></table><p><b>Agents</b></p><table class=\"grid\"><tr><td><b>Type</b></td><td><b>who</b></td></tr><tr><td><span title=\"Codes:{http://fhir.tiro.health/CodeSystem/agent-types fhirpath-engine}\">FHIRPath Engine</span></td><td>FHIRPath.js</td></tr></table></div>"
  },
  "target" : [
    {
      "extension" : [
        {
          "url" : "http://hl7.org/fhir/StructureDefinition/targetElement",
          "valueUri" : "item-999"
        }
      ],
      "reference" : "QuestionnaireResponse/qr-123"
    }
  ],
  "recorded" : "2025-10-29T10:33:00Z",
  "activity" : {
    "coding" : [
      {
        "system" : "http://fhir.tiro.health/CodeSystem/form-activity",
        "code" : "fhirpath",
        "display" : "FHIRPath calculation"
      },
      {
        "system" : "http://terminology.hl7.org/CodeSystem/iso-21089-lifecycle",
        "code" : "originate",
        "display" : "Originate/Retain Record Lifecycle Event"
      }
    ],
    "text" : "A calculation has been performed using a FHIRPath expression"
  },
  "agent" : [
    {
      "type" : {
        "coding" : [
          {
            "system" : "http://fhir.tiro.health/CodeSystem/agent-types",
            "code" : "fhirpath-engine",
            "display" : "FHIRPath Engine"
          }
        ]
      },
      "who" : {
        "display" : "FHIRPath.js"
      }
    }
  ]
}

Agent Types

Agents represent actors that perform or participate in actions:

Type Display Description
fhirpath-engine FHIRPath Engine FHIRPath expression evaluation engine
population-engine Population Engine Engine that populates forms from external data
preset-engine Preset Engine Engine that applies preset configurations

Agent Structure

Agents can include:

  • type: Classification of the agent (using agent-types CodeSystem)
  • role: Specific roles the agent played in the activity
  • who: Reference or display name identifying the agent
  • onBehalfOf: Reference to who the agent was acting on behalf of (e.g., AI acting on behalf of a practitioner)

Best Practices

  1. Always Record Provenance: Every data modification should have associated provenance
  2. Use Hierarchical Codes: Combine specific codes with parent codes (e.g., ai-clipboard with ai)
  3. Include Timestamps: Always populate the recorded field
  4. Link to Specific Items: Use targetElement extension to point to exact QuestionnaireResponse.item.id
  5. Preserve Agents: Include both automated agents and the user they're acting on behalf of
  6. Track Amendments: Use amend activity and ISO 21089 lifecycle when updating existing data

Use Cases

Audit Trail

Track who entered what data and when, providing complete transparency for regulatory compliance.

Data Quality Assessment

Identify fields populated by AI vs. manual entry to assess confidence levels.

Workflow Optimization

Analyze which fields are frequently manually corrected after AI population to improve algorithms.

Regulatory Compliance

Demonstrate compliance with requirements for tracking data provenance in clinical systems.

Data Lineage

Trace data back to its source through the entity array with role "source" or "derivation".