Skip to end of metadata
Go to start of metadata

This is just a proposal at this point in time and has not been validated with the project team

Summary of Provenance

  • http://hl7.org/implement/standards/fhir/provenance.html
  • Highlights from the resource description:
    • Provenance of a resource is a record that describes entities and processes involved in producing and delivering or otherwise influencing that resource.
    • The Provenance resource tracks information about the activity that created, revised, deleted, or signed a version of a resource, describing the entities and agents involved. 
    • Provenance resources are prepared by the application that initiates the create/update etc. of the resource
    • Many other FHIR resources contain some elements that represent information about how the resource was obtained, and therefore they overlap with the functionality of the Provenance resource. These properties in other resources should always be used in preference to the Provenance resource, and the Provenance resource should be used where additional information is required, or explicit record or provenance is desired.
    • There may be multiple provenance records for a given resource or version of a resource.
    • The Provenance resource corresponds to a single activity that identifies a set of resources (target) generated by the activity.
    • To record multiple activities that resulted in one (target), record each (activity) in independent Provenance records all pointing at that (target).
    • If a resource, entity, or agent can have different versions that must be identified, then the Reference must have versioning information included.
    • Versioning and unique identification are not mandated for all systems that provide Resources, entities, and agents. But, inclusion of Provenance requirements may introduce requirements for versioning and unique identification on those systems
    • Provenance records must have:
      • Target - Reference(Any)
      • Recorded - instance
      • Agent.who
    • When used in a document bundle, the references are often not explicitly versioned, but they always implicitly pertain to the version of the resource found in the document.
    • A Provenance record can be recorded to indicate who deleted a Resource. If versioning is supported, the version that was deleted is referenced in Provenance.target; if versioning is not supported then Provenance.target contains the non-version reference. Provenance.entity is not used unless there is a business requirement to do so.
    • Provenance can be used to record activities of an automaton that transforms input. Such as middleware that extracts information from a HL7 v2 message and creates FHIR resources, or middleware that extracts information from an HL7 CDA document and creates FHIR resources, etc. The Provenance in these cases is recording the activity of the middleware. The middleware in this case would, in addition to creating the target resources, create a Provenance resource that indicates all the target resources (using Provenance.target). The middleware is identified as one of the Provenance.agent elements, with the Provenance.agent.role of assembler. The middleware may record the source as another Provenance.agent element. The original content is optionally saved. This might be as a DocumentReference, or Binary. The Provenance.entity would then point at this original content. The original source might include some form of 'provenance' to cover the history of the original content prior to the import transformation. This original source 'provenance' should be converted into FHIR Provenance records as appropriate.

Provenance Types

Provenance Related Zulip Threads

https://chat.fhir.org/#narrow/stream/179166-implementers/topic/Provenance.20period.20vs.20recorded

https://chat.fhir.org/#narrow/stream/179166-implementers/topic/Source.20of.20information

https://chat.fhir.org/#narrow/stream/179188-v2-to.20FHIR/topic/v2.20version.20in.20a.20FHIR.20resource

https://chat.fhir.org/#narrow/stream/179166-implementers/topic/Provenance.2Eagent.2Erole

General (origin) Provenance

Every transformation of a v2 message like warrants the inclusion of a general Provenance resource that records the details of the origin of the v2 message. 

  • General Provenance resource relating to the transformation process:
    • Provenance.target points to the Bundle and MessageHeader (if it exists) resources (and potentially to individual resources contained in the bundle)
    • Provenance.recorded contains the value from MSH-7
    • Provenance.policy may point to the rules used for message creation (possibly drawn from MSH-21?)
    • Provenance.agent occurrence for sending application Namespace
      • Provenance.agent.type = "informant" or "author" or maybe a new value (value set is extensible) for "originator"
      • Provenance.agent.who references the Device represented in MSH-3 (Sending Application)
        • Provenance.agent.who.identifier.value contains the namespace from MSH-3.1
        • Provenance.agent.who.identifier.system is NOT valued
    • Provenance.agent occurrence for sending application Universal ID
      • Provenance.agent.type = "informant" or "author" or maybe a new value (value set is extensible) for "originator"
      • Provenance.agent.who references the Device represented in MSH-3 (Sending Application)
        • Provenance.agent.who.identifier.value contains the namespace from MSH-3.2
        • Provenance.agent.who.identifier.system contains the appropriate string for the Universal ID type (see guidance for the Identifier data type)
    • Provenance.agent occurrence for sending facility Namespace
      • Provenance.agent.type = "informant" or "author" or maybe a new value (value set is extensible) for "originator"
      • Provenance.agent.who references the Organization represented in MSH-4 (Sending Facility)
        • Provenance.agent.who.identifier.value contains the namespace from MSH-4.1
        • Provenance.agent.who.identifier.system is NOT valued
    • Provenance.agent occurrence for sending facility Universal ID
      • Provenance.agent.type = "informant" or "author" or maybe a new value (value set is extensible) for "originator"
      • Provenance.agent.who references the Organization represented in MSH-4 (Sending Facility)
        • Provenance.agent.who.identifier.value contains the namespace from MSH-4.2
        • Provenance.agent.who.identifier.system contains the appropriate string for the Universal ID type (see guidance for the Identifier data type)
    • Provenance.agent occurrence for sending responsible organization
      • Provenance.agent.type = "informant" or "author" or maybe a new value (value set is extensible) for "originator"
      • Provenance.agent.role = "RESPRSN"
      • Provenance.agent.who references the Organization represented in MSH-22 (Sending Responsible Organization)
        • see mapping of XON to Organization
    • Potentially other Provenance.agent occurrences 
      • MSH-12 version ID
      • MSH-21 profile ID (noted above)
      • MSH-24 sending network address (may go into one of the agent repetitions (sending facility or sending responsible organization)
    • Provenance.entity can optionally contain the whole v2 message as a Binary or DocumentReference in .what and a .role of "derivation" (or maybe "source"?)

General (transformation) Provenance

Every transformation of a v2 message likely warrants the inclusion of a general Provenance resource that records the details of the transformation. 

  • General Provenance resource relating to the transformation process:
    • Provenance.target points to all resources in the bundle
    • Provenance.recorded indicates the instant the v2 message was transformed to FHIR resources
    • Provenance.policy may point to the rules used for the transformation
    • Provenance.agent.type = "assembler"
    • Provenance.agent.who references the Organization or Device performing the transformation
    • Provenance.entity can optionally contain the whole v2 message as a Binary or DocumentReference in .what and a .role of "derivation" (or maybe "source"?)

SFT Provenance

If the original v2 message contains SFT segments, it may be appropriate to create a Provenance record for each SFT segment (see the SFT mapping page). The Provenance record should point to the MessageHeader resource (if it exists) and potentially every other resource created from the v2 message.

Message Specific Provenance

For specific message types it may be appropriate to generate additional Provenance resources to indicate the ownership of certain activities such as creation, update, authentication, etc. 

  • Possible VXU message Provenance resources:
    • Provenance.target points to the Immunization resource and the ServiceRequest if it exists in the Bundle
    • Provenance.occurredDateTime taken from RXA-3 (Note that this implies that the immunization event happened at the same time as the provenance activity - this may not be the best interpretation)
    • Provenance.recorded taken from either RXA-22 or MSH-7
    • Provenance.activity = "CREATE" if RXA-21 is "A" or = "UPDATE" if RXA-21 is "U" or "D" (note that I'm assuming a "delete" action code doesn't equate to an activity of "DELETE" because even if we update the resource, it's not actually removed from the database)
    • Provenance.agent would be needed but there isn't really any information about who recorded the event (unless we assume the administering provider documented the administration)
    • Note that we are not populating Provenance.location with the administered-at-location from RXA because that is the event location, not (necessarily) the entering location nor are we populating it with ORC-13 (Enterer's location) because that is (presumably) linked to the order for the immunization and not the actual immunization event
    • Anything to do with the add/update of the patient
      • While the patient may be new to the receiving system, there is no expectation that a change to the patient was performed as part of the activity which triggered the v2 message
    • Anything to do with the add/update of the encounter, next of kin, organization, practitioner content
      • Similar rationale as for the Patient resource
    • The whole message results in a general "transformation" Provenance resource as described above
    • Immunization event (add/update/delete) - do we really need this? Do we have the necessary info?
    • Provenance resources not created
  • Possible ORC message Provenance resources:
    • Provenance.target points to the ServiceRequest resource
    • Provenance.occurredDateTime taken from ORC-9??
    • Provenance.recorded taken from ORC-9 (Date/Time of Transaction) or should this be the date/time the v2 message is transformed
    • Provenance.location taken from ORC-13 (Enterer's Location)  (this is opposed to using a .activity type of ELOC)
    • Provenance.activity = "CREATE" if ORC-1 is "NW" or "SN" or = "UPDATE" if ORC-1 is "SC", "HD", "CA", "DC" or "OC"
      • The expectation is that if the control code is not NW or SN, then this isn't the first time this order has been sent to the receiving system
      • This assumes that an activity of "DELETE" or "NULLIFY" should not be used, even for CA, DC or OC control codes because we are not actually removing data from the data base (really just updating a status on a resource that is going to persist)
      • That that we don't use several other activity types such as DEV, AUT, LOC, ELOC
    • Provenance.agent (repeating depending on if ORC-10, ORC-17 and/or ORC-18 are populated)
      • Provenance.agent.type = "enterer" (all occurrences)  (this is opposed to using a .activity type of ENT)
      • Provenance.agent.who taken from ORC-10 as a Reference to a Practitioner or PractitionerRole
      • Provenance.agent.who taken from ORC-17 as a Reference to an Organization
      • Provenance.agent.who taken from ORC-18 as a Reference to a Device (this is opposed to using a .activity type of DEV)
    • Provenance.target points to the ServiceRequest resource
    • Provenance.occurredDateTime taken from ORC-9??
    • Provenance.recorded taken from ORC-9 (Date/Time of Transaction) or should this be the date/time the v2 message is transformed
    • Provenance.activity = "CALLBCK"
      • This assumes that callback provenance is independent of any creation or update of the order itself
    • Provenance.agent
      • Provenance.agent.who taken from ORC-14 as a Reference to a Practitioner or PractitionerRole or Organization that contains telecom data (or can we just use Reference.display as a text representation of the telecom information?)
    • Provenance.target points to the ServiceRequest resource
    • Provenance.occurredDateTime taken from ORC-9??
    • Provenance.recorded taken from ORC-9 (Date/Time of Transaction) or should this be the date/time the v2 message is transformed
    • Provenance.activity = "VRF"
    • Provenance.agent
      • Provenance.agent.type = "verifier"
      • Provenance.agent.who taken from ORC-11 as a Reference to a Practitioner or PractitionerRole
    • The whole message results in a general "transformation" Provenance resource as described above
    • ServiceRequest (create/update) if ORC-1 is NW, SN, SC, HD, CA, DC or OC and any of ORC-10 ORC-17 and/or ORC-18 are populated
    • ServiceRequest (callback) if ORC-14 is populated (or are we going to go with a ServiceRequest extension?)
    • ServiceRequest (verification) if ORC-11 is populated

Outstanding Questions

  • Given that most messages contain a PID segment but most triggering events (other than for ADT messages) likely don't relate to changes in the patient data, when should Provenance resources pointing the Patient resource be created? Only by ADT messages (perhaps based on the trigger event)? How about visits, next of kin, etc? For example should Encounter resources ever be the target of a Provenance resource for any message type other than ADT?
  • How do we populate Provenance.id? How does this impact the scenario where an order, immunization, problem, etc can be present in multiple messages? For example, should a "CREATE" Provenance resource only be created for order messages with a control code of NW or SN?
  • When, if ever, is an activity of DELETE or NULLIFY appropriate to use given that we don't really want to remove data, just mostly update the status to something like "entered-in-error"?
  • No labels