documented changes in WS audit dataset enrichment

oehf · Aug 1, 2024 · 4f10063 · 4f10063
1 parent 7cf35a7
commit 4f10063
Show file tree

Hide file tree

Showing 3 changed files with 43 additions and 50 deletions.
diff --git a/_pages/audit.md b/_pages/audit.md
@@ -131,7 +131,9 @@ the transmission protocol. It also allows to setup strategies for serialization,
 | `auditMetadataProvider` (3.7) | Instance of DefaultAuditMetadataProvider | Provider for header data used for SYSLOG-based transmission |
 | `auditMessagePostProcessor` | no-op | Audit Message Postprocessing, called before audit message is dispatched |
 | `auditExceptionHandler` | Instance of `LoggingAuditExceptionHandler` | Handler to be called if the delivery of audit message to the audit repository has failed |
-| `auditValueIfMissing` | `MISSING` | Value used if a mandatory audit attribute is not present
+| `auditValueIfMissing` | `UNKNOWN` | Value used if a mandatory audit attribute is not present |
+| `wsAuditDatasetEnricher` | no-op | Audit dataset enricher for Web Service based transactions (IPF 5.0+) | 
+| `fhirAuditDatasetEnricher` | no-op | Audit dataset enricher for FHIR based transactions (IPF 5.0+) | 
 
 The default setup is to send Audit Messages via UDP to `localhost:514`, and handle delivery errors by just logging them.
 For production usage, it is usually required to configure:
@@ -146,11 +148,11 @@ The transmission protocol determines the network protocol used for sending an au
 
 | `auditRepositoryTransport` | `auditTransmissionProtocol` class | Description |
 |-----------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------| ------------------------------------------------------------ |
-| `UDP` | [UDPSyslogSenderImpl](apidocs/org/openehealth/ipf/commons/audit/protocol/UDPSyslogSenderImpl.html) | UDP transport as SYSLOG record without delivery guarantee. Failed delivery is ignored.
-| `TLS` | [TLSSyslogSenderImpl](apidocs/org/openehealth/ipf/commons/audit/protocol/TLSSyslogSenderImpl.html) | Blocking TLS transport as SYSLOG record
-| `NIO-TLS` or `NETTY-TLS` | [NettyTLSSyslogSenderImpl](apidocs/org/openehealth/ipf/commons/audit/protocol/NettyTLSSyslogSenderImpl.html) | Non-blocking TLS transport as SYSLOG record. Requires Netty library on the classpath
-| `REACTOR-NETTY-TLS` | [ReactorNettyTLSSyslogSenderImpl](apidocs/org/openehealth/ipf/commons/audit/protocol/ReactorNettyTLSSyslogSenderImpl.html) | Reactive TLS transport as SYSLOG record. Requires Reactor-Netty library on the classpath
-| `FHIR_REST-TLS` | [ApacheFhirRestTLSAuditRecordSender](apidocs/org/openehealth/ipf/commons/ihe/fhir/audit/protocol/ApacheFhirRestTLSAuditRecordSender.html) | *as of IPF 4.8.0*: Blocking HTTPS transport as FHIR R4 AuditEvent resource
+| `UDP` | [UDPSyslogSenderImpl](apidocs/org/openehealth/ipf/commons/audit/protocol/UDPSyslogSenderImpl.html) | UDP transport as SYSLOG record without delivery guarantee. Failed delivery is ignored. |
+| `TLS` | [TLSSyslogSenderImpl](apidocs/org/openehealth/ipf/commons/audit/protocol/TLSSyslogSenderImpl.html) | Blocking TLS transport as SYSLOG record |
+| `NIO-TLS` or `NETTY-TLS` | [NettyTLSSyslogSenderImpl](apidocs/org/openehealth/ipf/commons/audit/protocol/NettyTLSSyslogSenderImpl.html) | Non-blocking TLS transport as SYSLOG record. Requires Netty library on the classpath |
+| `REACTOR-NETTY-TLS` | [ReactorNettyTLSSyslogSenderImpl](apidocs/org/openehealth/ipf/commons/audit/protocol/ReactorNettyTLSSyslogSenderImpl.html) | Reactive TLS transport as SYSLOG record. Requires Reactor-Netty library on the classpath |
+| `FHIR_REST-TLS` | [ApacheFhirRestTLSAuditRecordSender](apidocs/org/openehealth/ipf/commons/ihe/fhir/audit/protocol/ApacheFhirRestTLSAuditRecordSender.html) | *as of IPF 4.8.0*: Blocking HTTPS transport as FHIR R4 AuditEvent resource |
 
 
 ### Audit Message Queues
@@ -160,13 +162,31 @@ Audit Transmission Protocol.
 
 | `auditMessageQueue` class | Description |
 | --------------------------- | ------------------------------------------------------------ |
-| [SynchronousAuditMessageQueue](apidocs/org/openehealth/ipf/commons/audit/queue/SynchronousAuditMessageQueue.html) | Synchronously pass the audit record to the `auditTransmissionProtocol` instance
-| [AsynchronousAuditMessageQueue](apidocs/org/openehealth/ipf/commons/audit/queue/AsynchronousAuditMessageQueue.html) | Asynchronously pass the audit record to the `auditTransmissionProtocol` instance. Must be initialized with an `ExecutorService`
-| [JMSAuditMessageQueue](apidocs/org/openehealth/ipf/commons/audit/queue/JMSAuditMessageQueue.html) | Send the audit record to a JMS queue. SYSLOG header data is sent as JMS properties. Requires JMS API library.
-| [BasicHttpAuditMessageQueue](apidocs/org/openehealth/ipf/commons/audit/queue/BasicHttpAuditMessageQueue.html) (3.7) | Send the audit record to a HTTP service. SYSLOG header data is sent as HTTP properties.
-| [LoggingAuditMessageQueue](apidocs/org/openehealth/ipf/commons/audit/queue/LoggingAuditMessageQueue.html) | Just log the audit record to an SLF4J logger
-| [CamelAuditMessageQueue](apidocs/org/openehealth/ipf/commons/audit/queue/CamelAuditMessageQueue.html) | Send the audit record via a Camel producer. SYSLOG header data is sent as Camel headers.
-| [CompositeAuditMessageQueue](apidocs/org/openehealth/ipf/commons/audit/queue/CompositeAuditMessageQueue.html) | Send the audit record sequentially using one of the implementations listed above
+| [SynchronousAuditMessageQueue](apidocs/org/openehealth/ipf/commons/audit/queue/SynchronousAuditMessageQueue.html) | Synchronously pass the audit record to the `auditTransmissionProtocol` instance |
+| [AsynchronousAuditMessageQueue](apidocs/org/openehealth/ipf/commons/audit/queue/AsynchronousAuditMessageQueue.html) | Asynchronously pass the audit record to the `auditTransmissionProtocol` instance. Must be initialized with an `ExecutorService` |
+| [JMSAuditMessageQueue](apidocs/org/openehealth/ipf/commons/audit/queue/JMSAuditMessageQueue.html) | Send the audit record to a JMS queue. SYSLOG header data is sent as JMS properties. Requires JMS API library. |
+| [BasicHttpAuditMessageQueue](apidocs/org/openehealth/ipf/commons/audit/queue/BasicHttpAuditMessageQueue.html) (3.7) | Send the audit record to a HTTP service. SYSLOG header data is sent as HTTP properties. |
+| [LoggingAuditMessageQueue](apidocs/org/openehealth/ipf/commons/audit/queue/LoggingAuditMessageQueue.html) | Just log the audit record to an SLF4J logger |
+| [CamelAuditMessageQueue](apidocs/org/openehealth/ipf/commons/audit/queue/CamelAuditMessageQueue.html) | Send the audit record via a Camel producer. SYSLOG header data is sent as Camel headers. |
+| [CompositeAuditMessageQueue](apidocs/org/openehealth/ipf/commons/audit/queue/CompositeAuditMessageQueue.html) | Send the audit record sequentially using one of the implementations listed above |
+
+
+### Audit Dataset Enrichers (5.0)
+
+The following enrichers are provided out of the box.
+
+Enrichers for Web Service based transactions (implementations of [WsAuditDatasetEnricher](apidocs/org/openehealth/ipf/commons/ihe/ws/cxf/audit/WsAuditDatasetEnricher.html)): 
+
+| Audit dataset enricher class | Description |
+|----------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------|
+| [XuaWsAuditDatasetEnricher](apidocs/org/openehealth/ipf/commons/ihe/ws/cxf/audit/XuaWsAuditDatasetEnricher.html) | Fulfills requirements of the IHE [XUA](https://profiles.ihe.net/ITI/TF/Volume2/ITI-40.html) profile |
+| [SwissEprWsAuditDatasetEnricher](apidocs/org/openehealth/ipf/commons/ihe/ws/cxf/audit/SwissEprWsAuditDatasetEnricher.html) | Fulfills both IHE XUA requirements and the requirements of the [Swiss Electronic Patient Record](https://www.e-health-suisse.ch/en/technique/technical-interoperability/specifications-for-the-epr-implementation) |
+
+Enrichers for FHIR based transactions (implementations of [FhirAuditDatasetEnricher](apidocs/org/openehealth/ipf/commons/ihe/fhir/audit/FhirAuditDatasetEnricher.html)):
+
+| Audit dataset enricher class | Description |
+|----------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| [SwissEprFhirAuditDatasetEnricher](apidocs/org/openehealth/ipf/commons/ihe/fhir/audit/SwissEprWsAuditDatasetEnricher.html) | Fulfills the requirements of the [Swiss Electronic Patient Record](https://www.e-health-suisse.ch/en/technique/technical-interoperability/specifications-for-the-epr-implementation) |
 
 
 ### TLS Parameters (3.7)

diff --git a/_pages/boot/boot-atna.md b/_pages/boot/boot-atna.md
@@ -51,9 +51,13 @@ as described [here]({{ site.baseurl }}{% link _pages/ihe/atna.md %}).
 | `audit-sender-class` | as indicated by `audit-repository-transport` | ATNA sender implementation |
 | `audit-exception-handler-class`| `org.openehealth.ipf.commons.audit.handler.LoggingAuditExceptionHandler`| Exception handler impleemntation |
 | `audit-value-if-missing` | `UNKNOWN` | Value used for mandatory audit attributes that are not set |
+| `audit-message-post-processor-class` | none | Class of the audit message post-processor | 
+| `ws-audit-dataset-enricher-class` | none | Class of the audit dataset enricher for Web Service based transactions (IPF 5.0+) | 
+| `fhir-audit-dataset-enricher-class` | none | Class of the audit dataset enricher for FHIR based transactions (IPF 5.0+) |
 
-As of IPF 3.7, you can also provide your own @Beans returning an instance of `AuditMessageQueue`, `AuditMessagePostProcessor`,
-`AuditTransmissionProtocol`, `AuditMetadataProvider`, `AuditExceptionHandler` and `TlsParameters`.
+Instead of specifying class names in configuration properties, you can provide Spring @Beans of the types `AuditMessageQueue`, 
+`AuditMessagePostProcessor`, `AuditTransmissionProtocol`, `AuditMetadataProvider`, `AuditExceptionHandler`, `WsAuditDatasetEnricher`, 
+and `FhirAuditDatasetEnricjer`. Moreover, you can provide an own bean of the type `TlsParameters`.
 
 As of IPF 4.8.0, you can audit following the IHE Basic Audit Log Patterns (BALP). By setting `ipf.atna.balp` properties you can enable FHIR-based auditing.
 

diff --git a/_pages/migration/migration-5.0.md b/_pages/migration/migration-5.0.md
@@ -13,38 +13,7 @@ IPF 5.0 comes with some changes that should be considered when upgrading from ea
 
 Older IPF versions contained the module `ipf-commons-ihe-xua` which provided routines to propagate 
 particular elements of XUA authorization assertions into ATNA audit datasets. In IPF 5.0, this 
-module is not present anymore. Instead, a concept of a "Web Service audit dataset enricher" 
-is introduced. 
-
-IPF provides two enricher implementations out of the box:
-* `org.openehealth.ipf.commons.ihe.ws.cxf.audit.XuaWsAuditDatasetEnricher` — fulfills requirements 
- of the IHE [XUA](https://profiles.ihe.net/ITI/TF/Volume2/ITI-40.html) profile.
-* `org.openehealth.ipf.commons.ihe.ws.cxf.audit.SwissEprWsAuditDatasetEnricher` — fulfills both IHE XUA 
- requirements and the requirements of the 
- [Swiss Electronic Patient Record](https://www.e-health-suisse.ch/en/technique/technical-interoperability/specifications-for-the-epr-implementation).
-
-A Web Service audit dataset enricher can be configured in an Audit Context
-by providing a Spring bean of the type `org.openehealth.ipf.commons.ihe.ws.cxf.audit.WsAuditDatasetEnricher`,
-or by specifying an enricher's class name in the corresponding Spring Boot configuration property.
-
-Example for Spring context XML configuration:
-```xml
-<bean id="auditContext" class="org.openehealth.ipf.commons.audit.DefaultAuditContext">
- <property name="auditEnabled" value="true"/>
- <property name="auditMessageQueue" ref="myMessageQueue"/>
- <property name="auditSourceId" value="ipfapp"/>
- <property name="wsAuditDatasetEnricher">
- <bean class="org.openehealth.ipf.commons.ihe.ws.cxf.audit.SwissEprWsAuditDatasetEnricher"/>
- </property>
-</bean>
-```
-
-Example for Spring Boot YAML configuration:
-```YAML
-ipf:
- atna:
- audit-enabled: true
- audit-queue-class: my.project.atna.DevNullMessageQueue
- audit-source-id: ipfapp
- ws-audit-dataset-enricher-class: org.openehealth.ipf.commons.ihe.ws.cxf.audit.SwissEprWsAuditDatasetEnricher
-```
+module is not present anymore. Instead, a concept of an "audit dataset enricher" is introduced
+for Web Service based and FHIR based transactions. See 
+[here]({{ site.baseurl }}{% link _pages/audit.md %}) and 
+[here]({{ site.baseurl }}{% link _pages/boot/boot-atna.md %}) for details.