The ipf-commons-audit module contains a reimplementation and improvement of the ATNA functionality contained in the ipf-oht-atna-* modules that originate from the Eclipse OpenHealthTools project. This includes building DICOM/ATNA-compliant Audit Records as well as queueing and sending them to an Audit Repository.

The most important improvements are:

  • type-safe Audit Event builders, that enforce setting mandatory members and avoid setting coded values into the wrong places (e.g. accidentally setting a ParticipantObjectTypeCodeRole code as ParticipantObjectTypeCode code).
  • possibility to select an Audit Message XML schema that belongs to a specific DICOM version
  • possibility to plug-in your own exception handler in case the Audit Repository is not reachable
  • configuration is done via an AuditContext bean instead of a static global class. You can create and use as many AuditContext configuration beans as you wish.

Constructing an Audit Message

All of the IHE components implemented by IPF automatically use the audit support of this module for ATNA auditing. You only need to configure an AuditContext bean. When you use one of the Spring Boot starter modules, this bean is already provided for you.

In order to create and submit your own Audit Message, perform the following steps

  1. Construct your Audit Message by using one of the builder classes contained in the org.openehealth.ipf.commons.audit.event package. Note that the IHE modules (such as ipf-commons-ihe-core or ipf-commons-ihe-xds) inherit from some of these builders to create IHE-style ATNA-compliant Audit messages more easily.
  2. Call the getMessage or getMessages method to obtain the AuditMessage from the builder.
  3. Submit the Audit Message to the configured destination by calling AuditContext#audit(AuditMessage...) method.

Every Audit Message and Audit Message builder also has a validate method that check basic restrictions defined by DICOM or IHE.

The AuditMessageBuilder implementations are modelled corresponding to the definitions of the DICOM Specific Audit Messages.

The delegate builder class IHEAuditMessageBuilder has builder sub classes that correspond with the IHE ITI specification, Volume 2a, section

The DICOM serialization strategies produce XML files that validate against the schema of the respective revision of the DICOM Audit Message Schema.

For more details on the API, please study the javadocs.


Auditing an application start event

    new ApplicationActivityBuilder.ApplicationStart(EventOutcomeIndicator.Success)

Auditing a change to a user account:

new SecurityAlertBuilder(EventOutcomeIndicator.Success, null, EventTypeCode.UserSecurityAttributesChanged)
                .addActiveParticipant(adminUserId, null, adminUserName, true, null, networkId)
                        null, null)


  • The org.openehealth.ipf.commons.audit.utils.AuditUtils class contains static methods to obtain runtime information like process ID, current user, local host and IP address.


The AuditContext interface (and its DefaultAuditContext implementation) is the only place to configure static details for auditing, e.g. whether auditing is activated, the location of the Audit Repository, or the transmission protocol. It also allows to setup strategies for serialization, whether to send synchronously or asynchronously, and how errors are handled.

Generic properties

Property Default Description
auditEnabled false Whether audit is sent to the repository or not
auditRepositoryHost localhost Host name of the audit repository where audit records are sent to
auditRepositoryPort 514 Port of the the audit repository where audit records are sent to
auditRepositoryTransport UDP Transport protocol. One of UDP, TLS. Experimental: NIO-TLS (requires Vert.x lib dependency)

Content properties

Property Default Description
sendingApplication IPF sending application for the Syslog header info
auditSourceId IPF audit source ID for the source identification of the audit message
auditEnterpriseSiteId IPF audit enterprise site ID for the source identification of the audit message
auditSource 9 (Other) audit source type for the source identification of the audit message
includeParticipantsFromResponse false whether to include participant objects from a response into the audit message

Advanced properties

Property Default Description
auditTransmissionProtocol instance of UDPSyslogSenderImpl Transport implementation. Overrules auditRepositoryTransport
auditMessageQueue instance of SynchronousAuditMessageQueue Audit message dispatcher implementation
serializationStrategy instance of Current (i.e. DICOM2017c) Serialization implementation
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

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 a TLS connection to a remote Audit Repository and some decent strategy for handling failed connections to the Audit Repository.

Back to top

Version: 3.5-SNAPSHOT. Last Published: 2018-04-20.

Reflow Maven skin by Andrius Velykis.