Skip to main content

Provenance

Overview​

The Provenance resource provides "a record that describes entities and processes involved in producing and delivering or otherwise influencing that resource". Provenance is important as it provides "a critical foundation for assessing authenticity, enabling trust, and allowing reproducibility." (HL7 FHIR R4 Provenance)

Key Use Cases:

  • Track the source and history of clinical data
  • Provide audit trails for regulatory compliance
  • Support data integrity and authenticity verification
  • Enable trust in shared health information

Relationships to Other Resources:

  • Target Resources - References any FHIR resource that this provenance describes
  • Agent - Identifies who was responsible for the activity
  • Entity - Describes what was used to create or update the target resource

Resource Schema​

Key fields in the Provenance resource:

{
  "resourceType": "Provenance",
  "id": "string",
  "target": [
    {
      "reference": "ResourceType/resource-id"
    }
  ],
  "occurredDateTime": "YYYY-MM-DDTHH:mm:ssZ",
  "recorded": "YYYY-MM-DDTHH:mm:ssZ",
  "activity": {
    "coding": [
      {
        "system": "http://terminology.hl7.org/CodeSystem/v3-DataOperation",
        "code": "CREATE",
        "display": "create"
      }
    ]
  },
  "agent": [
    {
      "type": {
        "coding": [
          {
            "system": "http://terminology.hl7.org/CodeSystem/provenance-participant-type",
            "code": "author",
            "display": "Author"
          }
        ]
      },
      "who": {
        "reference": "Practitioner/practitioner-id"
      }
    }
  ],
  "entity": [
    {
      "role": "source",
      "what": {
        "reference": "DocumentReference/document-id"
      }
    }
  ]
}

Key Fields:

  • id - Unique identifier using delimited format (e.g., "ALG..123", "CLI..456")
  • target - References to the resources this provenance describes
  • occurredDateTime - When the activity occurred
  • recorded - When this provenance record was created
  • activity - What activity occurred (create, update, delete, etc.)
  • agent - Who was involved in the activity
  • entity - What was used to create or derive the target resource

Operations​

The Provider System Access Provenance resource supports the following operations:

CareRecord / SolutionCreateReadUpdateSearch
GEHRIMED-Yes--
myAvatar-Yes--
myEvolv-Yes--
myUnity-Yes--
TheraOffice-Yes--

Read​

Retrieve a specific Provenance resource by its delimited ID. The ID format includes the entity type and resource ID separated by ".." (e.g., "ALG..123").

GET /Provenance/{delimited-id}
Example Request
curl -X GET https://fhir.netsmartcloud.com/provider/system-access/v2/{tenant-id}/Provenance/ALG..12345 \
    -H "Accept: application/fhir+json"

Examples​

Request Examples​

Read Provenance for AllergyIntolerance
curl -X GET https://fhir.netsmartcloud.com/provider/system-access/v2/{tenant-id}/Provenance/ALG..12345 \
    -H "Accept: application/fhir+json"
Read Provenance for Patient
curl -X GET https://fhir.netsmartcloud.com/provider/system-access/v2/{tenant-id}/Provenance/CLI..67890 \
    -H "Accept: application/fhir+json"
Read Provenance for Observation
curl -X GET https://fhir.netsmartcloud.com/provider/system-access/v2/{tenant-id}/Provenance/OBS..11223 \
    -H "Accept: application/fhir+json"

Response Examples​

Successful Provenance Response​

Provenance Resource
{
  "resourceType": "Provenance",
  "id": "ALG..12345",
  "meta": {
    "lastUpdated": "2024-01-15T10:30:00.000Z",
    "profile": [
      "http://hl7.org/fhir/us/core/StructureDefinition/us-core-provenance"
    ]
  },
  "target": [
    {
      "reference": "AllergyIntolerance/12345"
    }
  ],
  "occurredDateTime": "2024-01-15T09:15:00.000Z",
  "recorded": "2024-01-15T09:16:00.000Z",
  "activity": {
    "coding": [
      {
        "system": "http://terminology.hl7.org/CodeSystem/v3-DataOperation",
        "code": "CREATE",
        "display": "create"
      }
    ]
  },
  "agent": [
    {
      "type": {
        "coding": [
          {
            "system": "http://terminology.hl7.org/CodeSystem/provenance-participant-type",
            "code": "author",
            "display": "Author"
          }
        ]
      },
      "who": {
        "reference": "Practitioner/practitioner-789",
        "display": "Dr. Sarah Johnson"
      }
    },
    {
      "type": {
        "coding": [
          {
            "system": "http://terminology.hl7.org/CodeSystem/provenance-participant-type",
            "code": "transmitter",
            "display": "Transmitter"
          }
        ]
      },
      "who": {
        "reference": "Organization/organization-456",
        "display": "Netsmart Technologies, Inc."
      }
    }
  ]
}

Patient Provenance Response​

Patient Provenance Resource
{
  "resourceType": "Provenance",
  "id": "CLI..67890",
  "meta": {
    "lastUpdated": "2024-01-15T14:22:00.000Z",
    "profile": [
      "http://hl7.org/fhir/us/core/StructureDefinition/us-core-provenance"
    ]
  },
  "target": [
    {
      "reference": "Patient/67890"
    }
  ],
  "occurredDateTime": "2024-01-15T14:20:00.000Z",
  "recorded": "2024-01-15T14:21:00.000Z",
  "activity": {
    "coding": [
      {
        "system": "http://terminology.hl7.org/CodeSystem/v3-DataOperation",
        "code": "UPDATE",
        "display": "revise"
      }
    ]
  },
  "agent": [
    {
      "type": {
        "coding": [
          {
            "system": "http://terminology.hl7.org/CodeSystem/provenance-participant-type",
            "code": "author",
            "display": "Author"
          }
        ]
      },
      "who": {
        "reference": "Practitioner/practitioner-321",
        "display": "Nurse Mary Smith"
      }
    }
  ],
  "entity": [
    {
      "role": "source",
      "what": {
        "reference": "Patient/67890",
        "display": "Previous version of patient record"
      }
    }
  ]
}

Integration Patterns​

Common Workflows​

1. Retrieve Provenance for Clinical Data

# Step 1: Get patient's allergy information
GET /AllergyIntolerance/12345

# Step 2: Get provenance for the allergy record
GET /Provenance/ALG..12345

# Step 3: Verify data source and authenticity
# Review agent and entity information in provenance

2. Audit Trail Investigation

# Step 1: Get observation data
GET /Observation/98765

# Step 2: Get provenance for the observation
GET /Provenance/OBS..98765

# Step 3: Review creation/modification history
# Check recorded timestamp and responsible agents
  • Target Resources - Any FHIR resource that this provenance describes
  • Practitioner - Healthcare providers who authored or transmitted the data
  • Organization - Healthcare organizations involved in data creation/transmission
  • Patient - The subject of the clinical data being tracked

Include Parameters​

Use _revinclude in other resource searches to include provenance:

# Get allergy with its provenance
GET /AllergyIntolerance?patient=Patient/123&_revinclude=Provenance:target

# Get observations with provenance
GET /Observation?patient=Patient/123&_revinclude=Provenance:target

Error Handling​

The Provenance resource follows standard FHIR error handling patterns. For detailed error responses and troubleshooting guidance, see the Common Errors page.

Provenance-Specific Error Scenarios​

  • 404 Not Found: Provenance ID doesn't exist or invalid delimited ID format
  • 400 Bad Request: Malformed delimited ID or unsupported entity type
  • Invalid Entity Type: Entity shortcode not supported by the service

Troubleshooting Tips​

  • Invalid ID Format: Ensure delimited ID uses correct format (EntityType..ResourceId)
  • Unsupported Entity: Verify entity shortcode is in the supported list
  • Missing Provenance: Not all resources may have associated provenance records
  • ID Parsing Issues: Check for proper ".." delimiter in the ID

Supported Profiles​

This API supports the following FHIR profiles: