PICA

Short Description

The purpose of this track is to test the Process Conformance IG PICA. You can upload Audit Events in R4 or R5 and then view Processes via the $dfg operation on a provided test server.

Long Description

The PICA Hapi Fhir server provides additional extensions to the base functionally. The idea is to provide a multi perspective process mining possibility on audit logs. For this purpose `AuditEvents` are utilized. We differ between R4 and R5 implementations and provide functionality for both of them.

The server has additional operations defined on `AuditEvents` than enable to retrieve these logs in either `xes` or
`ocel`, both process mining compatible formats. In addition, the `xes` log can further be used to transform the logs
into a graphical representation called a Directly-Follows Graph (DFG). This results in the following additional 
operations provided on AuditEvents:

 - `[ServerBaseURL]/fhir/AuditEvent/$xes`: to retrieve the audit logs in the XES format.
   - **grouping**: The grouping parameter can specific the method, that should be used to group the audit events into
                   traces. This parameter is reflection based, and executes the method calls on an Audit R5 event. (Note:
                   It is always an R5 AuditEvent, independent of the server configuration.) e.g. `getPatient.getReference`.
                   Please be award that the grouping may fail with an NullPointerException, if an AuditEvent does not
                   contain the resource, for which the grouping is performed.
 - `[ServerBaseURL]/fhir/AuditEvent/$ocel`: to retrieve the audit logs in the OCEL format.
 - `[ServerBaseURL]/fhir/AuditEvent/$dfg`: to retrieve the audit logs in form of a DFG graph.
   - **grouping**: See grouping of $xes. 

We expect and hope to achieve:

  • understanding which audit events are relevant for process conformance (AuditEvents have different granularities)
  • feedback regarding design choices which parts of the Audit Events are used for process reconstruction
  • feedback on what additional information is relevant in conformance checking that is not yet presented

Type

Test a specific Implemenation Guide (IG)

Submitting Work Group/
Project/
Accelerator/
Affiliate/
Implementer Group  

FH OÖ - Research Group AIST

Track Lead(s)

Oliver Krauss 

Track Lead Email(s)

oliver.krauss@fh-hagenberg.at

Related Tracks

None directly

All Implementers that write Audit Logs can provide them to this track

FHIR Version

FHIR R4 and FHIR R5

Specification(s) this track uses

- https://fhir.hl7.at/r5-pica-5-deployment/overview.html (Implementation Guide)

- Pointner, A., Krauss, O., Schuler, A., & Helm, E. (2022). Transformation from HL7® FHIR® AuditEvent to XES (Version 1.0.0) [Computer software]. https://doi.org/10.5281/zenodo.6901825
   - https://github.com/FHOOEAIST/FhirAuditEvent2XES
   - https://github.aist.science/FhirAuditEvent2XES/
- Pointner, A., Krauss, O., Schuler, A., & Helm, E. (2022). Transformation from HL7® FHIR® AuditEvent to OCEL (Version 1.0.0) [Computer software]. https://doi.org/10.5281/zenodo.6901919
   - https://github.com/FHOOEAIST/FhirAuditEvent2OCEL
   - https://github.aist.science/FhirAuditEvent2OCEL/
- Pointner, A., Krauss, O., Schuler, A., & Helm, E. (2022). Transformation from XES to GraphViz (Version 1.0.0) [Computer software]. https://doi.org/10.5281/zenodo.7185725
   - https://github.com/FHOOEAIST/XES2GraphViz
   - https://github.aist.science/XES2GraphViz/
- Pointner, A. (2022). xes-model (Version 1.0.0) [Computer software]. https://doi.org/10.5281/zenodo.6760266
   - https://github.com/FHOOEAIST/xes-model
   - https://github.aist.science/xes-model/
- Pointner, A. (2022). ocel-model (Version 1.0.0) [Computer software]. https://doi.org/10.5281/zenodo.6861508
   - https://github.com/FHOOEAIST/ocel-model
   - https://github.aist.science/ocel-model/
- https://github.com/FHOOEAIST/pica-hapi-fhir-jpaserver-starter (Reference Implemenation)

Artifacts of focus

AuditEvent R4

AuditEvent R5

Expected participants

Oliver Krauss 

Andreas Pointner (FH OOE)

Clara Diesenreiter (FH OOE)

Date / Time

Monday March 13, 09:00am-03:30pm CET

Test Servers

See Test Servers

(FH OÖ R4 and R5)

Track Details

Prerequisites (recommended)
  • Basic knowledge of FHIR 
  • A process that you want to reconstruct via Audit Events (optional, simulator tool below)
System roles
FHIR Actor (any actor writing audit events) in R4 or R5

For Actors you simple need to create Audit Events, either in FHIR R4 (needs Extensions!) or FHIR R5 (vanilla). See Scenarios R4 1-3 and R5 1+2 for this role.

Process Auditor in R4 or R5

A process auditor simply needs to call one of three available FHIR Operations on the FHIR Server and then view the results. The options are:

  • $xes - Returns the Audit Log in the Extensible Event Log standard XES
  • $ocel (only R5) - Returns the Audit log in the Object Centric Log standard OCEL
  • $dfg - Returns a visual representation, in the form of a Directly follows Graph DFG

See Scenarios R4 4 and R5 3 for this role.

Scenarios

Note: all of the following scenarios are independent from each other. You can implement only one, or multiple ones

Quick overview:

ScenarioR4R5Involved roles
Create process via FHIR resources1not supportedFHIR Actor
Transform from R4 audit log to R5 audit lognot supported1FHIR Actor
Simulating process via synthea2not supportedFHIR Actor (no implementation needed)
Creating audit events manually32FHIR Actor
Generation of standardized process logs43Process Auditor (can be done via browser or implementation)


FHIR R4 Scenarios:

For these scenarios please use the endpoint https://aist-partner.projekte.fh-hagenberg.at/pica-r4/fhir

1 - Creating a process via FHIR resources (complex)

We have extended functionality for R4. We support the automated creation of AuditEvent, when creating specific resources on the server. At the moment the following resources are supported:

 - CarePlan
 - Condition
 - DiagnosticReport
 - ImagingStudy
 - Immunization
 - MedicationAdministration
 - MedicationRequest
 - Observation
 - Procedure

The `AuditEvents` are created based on the values of the these resources. That means, that the auditing will not track 
e.g. the timestamp of the creation of the resource, but the value that is stored in the resource. Overall four properties
are set in the generated `AuditEvents`. All of them are going to be created as extensions to the Base R4 resource:

 - **occurredDateTime**: The timestamp of the resource as a `DateTimeType`.
 - **patient**: The reference to a patient resource as a `Reference`.
 - **encounter**: The reference to an encounter resource as a `Reference`.
 - **code**: The action that occurred for the resource as a `Coding`.

2 - Simulating a process via the Synthea tool (simple)

A simple way to generate R4 resource to test the R4 hapi fhir server configuration, is to use the 
[synthea](https://github.com/synthetichealth/synthea) patient generator. To do so, simply 
[download](https://github.com/synthetichealth/synthea/releases/download/v3.1.1/synthea-with-dependencies.jar) the
sythea jar-file. Then you can run the patient generator using the following command:

```shell
java -jar synthea-with-dependencies.jar -p 50
```

The value after the `-p` flag will specify how many patients you want to create. For every patient a number of resources
for the whole patient journey will be created. The data is then stored in a `./output/fhir` folder on the same level as
you executed the command.

The folder will then contain the following files:

 - hospitalInformation*.json
 - practitionerInformation*.json
 - number of patient in the format firstname_lastname_uuid.json

These files can then be sent to a fhir server using a command tooling like [curl](https://curl.se/). First you need to
upload the hospitalInformation*.json and practitionerInformation*.json files. After that you are able to upload the
patients. A command to upload the files could have the following structure:

```shell
curl -X POST \ 
     --location "base fhir url of server" \
     -H "Content-Type: application/fhir+json" \
     -d @filepath
```

e.g. 

```shell
curl -X POST \ 
     --location "http://localhost:8080/fhir/" \
     -H "Content-Type: application/fhir+json" \
     -d @C:\public\git\_github\synthea\output\fhir\practitionerInformation1673264100656.json
```

All the files from synthea are bundled Fhir files, which means there is no need to send them to a specific resource, 
instead you can always use the base fhir url of the Fhir server.

3 - Creating Audit Events manually (medium complexity due to necessary extensions)

You are also allowed to upload your own resources on the server, which will result in creating own AuditEvents. Please 
make sure to not stress the server with a too high amount of resources, as we are running on limited storage capacities.
In addition, please note, that when using references to other resources, that these resources have to exist on the server
as well. If you do not want to create all these resources, our server allows to link to external resources. The following
JSON example of an R4 AuditEvent, would for example be a valid input on our server:

```json
{
  "resourceType": "AuditEvent",
  "id": "283",
  "meta": {
    "versionId": "1",
    "lastUpdated": "2023-01-09T11:43:57.495+00:00"
  },
  "extension": [
    {
      "url": "http://fhir.r5.extensions/occurredDateTime",
      "valueDateTime": "2013-06-06T00:16:47+02:00"
    },
    {
      "url": "http://fhir.r5.extensions/patient",
      "valueReference": {
        "reference": "https://hapi.fhir.org/baseR4/Patient/1853"
      }
    },
    {
      "url": "http://fhir.r5.extensions/encounter",
      "valueReference": {
        "reference": "https://hapi.fhir.org/baseR4/Encounter/1853"
      }
    },
    {
      "url": "http://fhir.r5.extensions/code",
      "valueCoding": {
        "system": "http://snomed.info/sct",
        "code": "53741008",
        "display": "Coronary Heart Disease"
      }
    }
  ]
}
```

4 - Generation of standardized process logs (simple)

You can generate process logs with the following Operations directly on endpoint/AuditEvent/$OPERATION, with some filter options:

 - $xes | $dfg

   - reasonCode: Filtering based on the code value of the first reasonCode inside the encounter

   - patient: Filtering based on the reference value of the patient 

Warning: If you also implement this scenario in R5, the available operations and filters are different!

FHIR R5 Scenarios:

For these scenarios please use the endpoint https://aist-partner.projekte.fh-hagenberg.at/pica-r5/fhir

1 - Creating a process from R4 resources (medium complexity)

As already stated, the R4 AuditEvents are creating using a few extensions to the Base R4 resource. These fields are 
already in the standard in R5, allowing us to transform them accordingly:

 - **R4 AuditEvent** → **R5 AuditEvent**
 - ext.occurredDateTime → occurred
 - ext.encounter → encounter
 - ext.code → code
 - ext.patient → patient

This also means, that in R4 we have a reduced set of elements that can be used in the mapping to XES/DFG, as only the
fields occurred, encounter, code and patient are available.

2 - Creating audit events manually (simple)


You are also able to upload your own resources on the server, which will result in creating own AuditEvents. Please
make sure to not stress the server with a too high amount of resources, as we are running on limited storage capacities.
In addition, please note, that when using references to other resources, that these resources have to exist on the server
as well. If you do not want to create all these resources, our server allows to link to external resources. The following
JSON example of an R5 AuditEvent, would for example be a valid input on our server:

```json
{
  "resourceType": "AuditEvent",
  "code": {
    "coding": [
      {
        "system": "RadLex",
        "code": "RID45814",
        "display": "Appointment Time Scheduled 2"
      }
    ],
    "text": "Schedule appointment 2"
  },
  "occurredDateTime": "2019-10-07T12:58:09+02:00",
  "basedOn": [
    {
      "reference": "https://externalserver/CarePlan/2"
    }
  ],
  "encounter": {
    "reference": "https://externalserver/Encounter/2"
  },
  "patient": {
    "reference": "https://externalserver/Patient/2"
  },
  "agent": [
    {
      "who": {
        "reference": "https://externalserver/Device/2"
      }
    }
  ]
}
```

3 - Generation of standardized process logs (simple)

You can generate process logs with the following Operations directly on endpoint/AuditEvent/$OPERATION, with some filter options:

- $xes |  $ocel | $dfg

   - patient: Filtering based on the reference value of the patient

   - basedOn: Filtering based on the reference value of the basedOn element

   - encounter: Filtering based on the reference value of the encounter element

   - agent: Filtering based on the reference value of the agent element

Warning: If you also implement this scenario in R4, the available operations and filters are different!