This transaction supports the retrieval of CA:Aud audit record from the Audit Record Repository in accordance with a set of search parameters that determine the retrieved event reports.

This transaction enables an Audit Consumer to search audit events that an Audit Record Repository created via the Record Audit Event [ITI-20] FHIR Feed transaction. If the Audit Record Repository stores audit messages in other formats, it should map the audit messages into the FHIR format that can be consumed by the Retrieve ATNA Audit Event [ITI-81] transaction.

This transaction is a profiling of a standard FHIR search of the AuditEvent Resource.

Scope

The Retrieve ATNA Audit Event transaction is used to search CA:Aud events recorded in an CA:Aud Audit Record Repository. The result of this retrieval is a FHIR bundle of AuditEvent Resources that match with a set of search parameters.

Actor Roles

Actor

Role

Audit Record Repository

Provides storage for CA:Aud audit events and responds to queries for a portion of the stored records.

Audit Consumer

Queries for CA:Aud audit records.

Referenced Standards

RFC2616

IETF Hypertext Transfer Protocol – HTTP/1.1

RFC4627

The application/json Media Type for JavaScript Object Notation (JSON)

RFC6585

IETF Additional HTTP Status Codes

RFC3339

Date and Time on the Internet: Timestamps

HL7 FHIR

Release 4 http://hl7.org/fhir/R4/index.html

Messages

Retrieve ATNA Audit Events Request Message

This is an HTTP GET parameterized search from an Audit Consumer to an Audit Record Repository. The Audit Record Repository has stored CA:Aud audit records received via Record Audit Event [ITI-20] transactions. Those messages, which are stored within a data-store, can be retrieved in accordance with specific search parameters.

Trigger Events

The Audit Consumer sends a Retrieve ATNA Audit Events message when it needs to process or analyze CA:Aud audit records.

Message Semantics

The Retrieve ATNA Audit Event message shall be an HTTP GET request sent to the Audit Record Repository. This message is a FHIR search (see http://hl7.org/fhir/R4/search.html) on AuditEvent Resources (see http://hl7.org/fhir/R4/auditevent.html).

This “search” target is formatted as:

<scheme>://<authority>/<path>/AuditEvent?date=ge[start-time]&date=le[stop-time]&<query>

where:

  • <scheme> shall be either http or https. The use of http or https is a policy decision, but https is usually appropriate due to confidentiality of CA:Aud audit record content.
  • <authority> shall be represented as a host (either IP address or DNS name) followed optionally by a colon and port number.
  • The Audit Record Repository may use <path> to segregate the HTTP search service for AuditEvent implementation from other REST-based services.
  • At least one date search parameter is required. See section Date Search Parameters.
  • “&” is a conditional parameter that shall be present if the <query> parameter is present.
  • <query>, if present, represents a series of encoded name-value pairs representing filters for the search. See section Additional Search Parameters.
Date Search Parameters

The date parameter shall be used to specify an upper and/or lower bound for the search. At least one date parameter shall be present. Two date parameters are recommended in every search by the Audit Consumer and shall be supported by the Audit Record Repository in order to avoid overloading the Audit Consumer. These parameters allow the Audit Consumer to specify the time frame of creation of audit records of interest and enable the Audit Consumer to constrain the number of audit records returned. The values for the date search parameters shall be in RFC3339 format.

Note: RFC3339 format is the format mandated by Syslog for time stamps and is a sub-set of the XML date-time data format used by FHIR.

For example, to search AuditEvent Resources created during the whole day of January 5, 2013:

http://example.com/ARRservice/AuditEvent?date=ge2013-01-05&date=le2013-01-05

The Audit Record Repository shall apply matching criteria to AuditEvent Resources characterized by AuditEvent.recorded field valued within the time frame specified in the Request message.

The Audit Record Repository shall apply other date matching criteria following rules defined by FHIR specification (http://hl7.org/fhir/R4/search.html).

Additional Search Parameters

The search parameters in this section may be supported by the Audit Consumer and shall be supported by the Audit Record Repository. These parameters can be used by the Audit Consumer to refine search requests.

The Audit Consumer shall encode all search parameters per RFC3986 “percent” encoding rules. Although FHIR allows unconstrained use of AND OR operators to make queries of unlimited complexity, this transaction constrains the queries allowed:

  • Multiple search parameters shall only be combined using AND “&” operator.
  • The OR “,” operator shall be used only within a single search parameter that has multiple values.

Additional search parameters are listed below:

  • address is a parameter of string type. This parameter specifies the identifier of the network access point (NetworkAccessPointID) of the user device that creates the audit record (this could be a device id, IP address, or some other identifier associated with a device).

The value of this parameter shall contain the substring to match.

For example:

http://example.com/ARRservice/AuditEvent?date=ge2013-01-01&date=le2013-01-02&address=192.168.0.1

The Audit Record Repository shall match this parameter with the AuditEvent.agent.network.address.

  • agent.identifier is a parameter of token type. This parameter identifies the user that participated in the event that originates the audit record.

For example, to search AuditEvent Resources related to the user “admin”:

http://example.com/ARRservice/AuditEvent?date=ge2013-01-01&date=le2013-01-02&agent.identifier=admin

The Audit Record Repository shall match this parameter with the AuditEvent.agent.who.identifier field.

If a patient identifier it is used, the Audit Record Repository will return only the audit records where the patient is involved in the event as a user.

  • patient.identifier is a parameter of token type. This parameter specifies the identifier of the patient involved in the event as a participant or as a user. The value of this parameter can contain the namespace URI (that represents the assigning authority for the identifier) and the identifier.

For example:

http://example.com/ARRservice/AuditEvent?date=ge2013-01-01&date=le2013-01-02&patient.identifier=urn:oid:1.2.3.4|5678

The Audit Record Repository shall match this parameter with the AuditEvent.agent.who.identifier and AuditEvent.entity.what.identifier where the reference resolve to a Patient.

  • entity.identifier is a parameter of token type. This parameter specifies unique identifier for the object. The parameter value should be identified in accordance to the entity type.

For example:

  • ?entity.identifier=urn:oid:1.2.3.4.5|123-203-FJ
  • ?entity.identifier=|123-203-FJ.

The Audit Record Repository shall match this parameter with the AuditEvent.entity.what.identifier field that is of type identifier. If a patient identifier is used the Audit Record Repository will return only audit records where the patient is involved in the event as a participant.

The Audit Record Repository shall match this parameter with the AuditEvent.entity.type field.

For example, to search all the audit records related to the document entity (Report=”3”) with the unique id 12345^1.2.3.4.5 a fully specified request would be: http://example.com/ARRservice/AuditEvent?date=ge2013-01-01&date=le2013-01-02&entity-role=http://hl7.org/fhir/object-role|3&entity-id=urn:oid:1.2.3.4.5|12345

The Audit Record Repository shall match this parameter with the AuditEvent.entity.role field.

  • source.identifier is a parameter of token type. This parameter identifies the source of the audit event.

For example, to search AuditEvent Resources produced by the audit source application characterized by unique ID: 1234:

http://example.com/ARRservice/AuditEvent?date=ge2013-01-01&date=le2013-01-02&source=1234

The Audit Record Repository shall match this parameter with the AuditEvent.source.observer.identifier field.

  • type is a parameter of token type. This parameter represents the identifier of the specific type of event audited. The parameter value shall contain the namespace URI http://dicom.nema.org/resources/ontology/DCM and a coded value. Codes available are defined by IHE (see Record Audit Event [ITI-20] section Send Audit Resource Request Message, Trigger Events.

For example, to search AuditEvent Resources related to PHI Export Events:

http://example.com/ARRservice/AuditEvent?date=ge2013-01-01&date=le2013-01-02&type=http://dicom.nema.org/resources/ontology/DCM|110106

The Audit Record Repository shall match this parameter with the AuditEvent.type field.

  • subtype is parameter of token type. This parameter identifies the specific IHE transaction that originates the audit record. The parameter value can contain the namespace URI urn:ihe:event-type-code to search for audit messages triggered by IHE transactions with the defined audit message. Each IHE transaction that defines an CA:Aud messages, specifies a code identifying the transaction itself, and assigns this code to the EventTypeCode element within the [ITI-20] audit record.

For example, to search AuditEvent Resources related to Retrieve Document Set [ITI-43] transactions:

http://example.com/ARRservice/AuditEvent?date=ge2013-01-01&date=le2013-01-02&subtype=urn:ihe:event-type-code|ITI-43

The Audit Record Repository shall match this parameter with the AuditEvent.subtype field.

To search AuditEvent Resources related to failed events:

http://example.com/ARRservice/AuditEvent?date=ge2013-01-01&date=le2013-01-02&outcome=http://hl7.org/fhir/audit-event-outcome|4,8,12

The Audit Record Repository shall match this parameter with the AuditEvent.outcome field.

The HL7® FHIR® standard provides additional search parameters. This transaction does not define specific behavior on those parameters (such as _sort, _include, etc.). See http://hl7.org/fhir/R4/search.html for details about available parameters.

Populating Expected Response Format

The HL7® FHIR® standard provides encodings for responses as either XML or JSON. The Audit Record Repository shall support both message encodings. The Audit Consumer shall support one and may optionally support both encodings. For Desired Response Encoding and format negotiation see ITI TF-2: Appendix Z.6.

Expected Actions

The Audit Record Repository (ARR) maintains a database of audit events. The Audit Record Repository retains data according to local policies, and some data may be deleted.

The Audit Record Repository shall return all the audit events stored in its database that match the query parameters, and which the requester is authorized to view (see CA:Aud Overview for further details).

When performing matching based on the search parameters, the Audit Record Repository shall:

  • Select all audit records that have a time interval specified in the request URL.
  • If search parameters other than those defined in section Additional Search Parameters (e.g., _sort, _include FHIR search result parameters) are specified in the request URL, then

o If the Audit Record Repository does not support the parameter, it shall be ignored;

o If the Audit Record Repository supports the parameter, the matching or other behavior shall comply with the matching rules for its datatype in FHIR.

The Audit Record Repository shall return matching resources using the Retrieve ATNA Audit Event Response Message. See section Retrieve ATNA Audit Event Response Message.

Retrieve ATNA Audit Event Response Message

The Audit Record Repository sends the Retrieve ATNA Audit Event Response message in response to a query from an Audit Consumer

Trigger Events

The Audit Record Repository creates this message when it receives and processes a Retrieve ATNA Audit Event message.

Message Semantics

When the Audit Record Repository successfully processes the search request, it shall return the matching AuditEvent Resources inside a FHIR Bundle Resource.

The “Content-Type” of the response will depend upon the response format negotiation described in ITI TF-2: Appendix Z.6.

If the date search parameter is missing (see section Date Search Parameters), the Audit Record Repository may return HTTP response code 400 - Bad Request.

If the specified search parameters do not result in any matching audit record, the Audit Record Repository shall return HTTP response of success 200, with an empty FHIR bundle.

If the requested data size is considered excessive by the Audit Record Repository, it may choose to return the results in a series of pages (see https://www.hl7.org/fhir/R4/http.html#paging).

Other HTTP response codes may be returned by the Audit Record Repository. See ITI TF-2: Appendix Z.7 Guidance on Access Denied Results.

The Audit Record Repository should complement the returned error code with a human readable description of the error condition.

Audit Record Repository may return HTTP redirect responses (responses with values of 301, 302, 303, or 307) in response to a request. Audit Consumers must follow redirects, but if a loop is detected, it may report an error.

FHIR Bundle of Audit Events Messages

When the search is successful, the body of the Response message shall contain a FHIR Bundle of AuditEvent Resources.

Example XML format:

<Bundle> 
    <type>searchset</type> 
    <total>3</total> 
    <link>
        <relation value="self"/>
        <url value="http://example.com/ARRservice/AuditEvent?date=&gt;2013-01-01&date=&lt;2013-01-02"/>
    </link>  
    <entry> 
        <fullUrl value="http://example.com/ARRservice/AuditEvent/23#"/> 
        <resource> <AuditEvent> .....  </AuditEvent> </resource> 
    </entry> 
    <entry> 
        <fullUrl value="http://example.com/ARRservice/AuditEvent/564#"/>  
        <resource> <AuditEvent> ..... </AuditEvent> </resource>  
    </entry> 
    <entry> 
        <fullUrl value="http://example.com/ARRservice/AuditEvent/3446#"/> 
        <resource> <AuditEvent>  ..... </AuditEvent> </resource> 
    </entry>
</Bundle>
Expected Actions

The Audit Consumer may further analyze the data received within the FHIR Bundle of AuditEvent Resources.

Security Considerations

See the general Security Considerations.

Audit Considerations

This transaction may involve the disclosure of sensitive information. Logging these retrieval transactions as a query event is appropriate.

However, CA:Aud does not require the Audit Record Repository to be able to send audit records using the Record Audit Event [ITI-20] transaction.

The following notation is used for optionality:

M

This field is mandatory.

U

The optionality of this field is unspecialized. The optionality of the underlying standard applies.

C

This field is mandatory if a specified condition is true.

The Audit Record Repository shall create and store locally an audit event as follows:

 

Field Name

Opt

Value Constraints

Event
AuditMessage/ EventIdentification

EventID

M

EV (110101, DCM, "Audit Log Used")

EventActionCode

M

“R” (Read)

EventDateTime

U

not specialized

EventOutcomeIndicator

U

not specialized

EventTypeCode

M

EV(“ITI-81”, “IHE Transactions”, “Retrieve ATNA AuditEvent”)

Source (Document Administrator) (1)

Human Requestor (0..1)

Destination (Document Registry) (1)

Audit Source (Document Administrator) (1)

AuditEvent Message (0..n)

Where:

Source
AuditMessage/ ActiveParticipant

UserID

U

not specialized

AlternativeUserID

M

The process ID as used within the local operating system in the local system logs.

UserName

U

not specialized

UserIsRequestor

U

not specialized

RoleIDCode

M

EV(110153, DCM, “Source”)

NetworkAccessPointTypeCode

M

“1” for machine (DNS) name, “2” for IP address

NetworkAccessPointID

M

The machine name or IP address.

Human Requestor
(if known)
AuditMessage/ ActiveParticipant

UserID

M

Identity of the human that initiated the transaction.

AlternativeUserID

U

not specialized

UserName

U

not specialized

UserIsRequestor

U

not specialized

RoleIDCode

M

Access Control role(s) the user holds that allows this transaction.

NetworkAccessPointTypeCode

U

not specialized

NetworkAccessPointID

U

not specialized

Destination
AuditMessage/ ActiveParticipant

UserID

M

SOAP endpoint URI.

AlternativeUserID

U

not specialized

UserName

U

not specialized

UserIsRequestor

U

not specialized

RoleIDCode

M

EV(110152, DCM, “Destination”)

NetworkAccessPointTypeCode

M

“1” for machine (DNS) name, “2” for IP address

NetworkAccessPointID

M

The machine name or IP address.

Audit Source
AuditMessage/AuditSourceIdentification

AuditSourceID

U

not specialized

AuditEnterpriseSiteID

U

not specialized

AuditSourceTypeCode

U

not specialized

AuditEvent Message
AuditMessage/ ParticipantObjectIdentification

ParticipantObjectTypeCode

M

“2” (System object)

ParticipantObjectTypeCodeRole

M

“13” (Security Resource)

ParticipantObjectDataLifeCycle

U

not specialized

ParticipantObjectIDTypeCode

M

EV(“12”, “RFC-3881”, "URI")

ParticipantObjectSensitivity

U

not specialized

ParticipantObjectID

M

The URI of the Audit log

ParticipantObjectName

M

“Security Audit Log”

ParticipantObjectQuery

U

not specialized

ParticipantObjectDetail

U

not specialized

  • No labels