3. Protocol

For communication between processor detecting events and component responsible for logging events special extension of XMPP protocol is used with namespace http://tigase.org/protocol/auditlog which will be passed added as xmlns attribute to action elements of stanza requests. All stanzas will be iq stanzas.

3.1. Entry

Entry is an xml element which contains other elements as properties with values. It is basic element logged by component to audit log.

<entry>
  <whenOccurred>2015-01-15T14:54:04Z</whenOccurred>
  <srcAddress>[email protected]</srcAddress>
  <dstAddress>[email protected]</dstAddress>
  ...
</entry>

In above example we have passed:

whenOccurred

property which contains timestamp of this even,

srcAddress

containing source jid of stanza which triggered event,

dstAddress

containing destination jid of stanza which triggered event.

3.2. Appending entries to log

To append entry to log component which would append entry processor is sending following stanza with proper values set:

<iq type="set" id="auditlog-1">
  <append xmlns="http://tigase.org/protocol/auditlog">
    <entry>
      <whenOccurred>2015-01-15T14:54:04Z</whenOccurred>
      <srcAddress>[email protected]</srcAddress>
      <dstAddress>[email protected]</dstAddress>
      ...
    </entry>
    ...
  </append>
</iq>

This would notify receiver to append (as append is name of action element) entry or entries which are described by inner elements of action element.

3.3. Retrieval of entries

In some cases it will be possible to retrieve entries sent to AuditLog component using XMPP. To retrieve 2 oldest entries (oldest entries from cache) following iq stanza of get type should be sent to AuditLog component:

<iq type="get" id="auditlog-2" from="[email protected]/res-1" to="[email protected]">
  <retrieve xmlns="http://tigase.org/protocol/auditlog" offset="0" limit="2"/>
</iq>

AuditLog component will respond with stanza in following format:

<iq type="result" id="auditlog-2" from="[email protected]" to="[email protected]/res-1">
  <entries xmlns="http://tigase.org/protocol/auditlog" offset="0" limit="2">
    <entry>
      <whenOccurred>2015-01-15T14:54:04Z</whenOccurred>
      <srcAddress>[email protected]</srcAddress>
      <dstAddress>[email protected]</dstAddress>
      ...
    </entry>
    ...
  </entries>
</iq>

in which entries element contains requested entries as subelements in entry XML format.

If there was an error and entries could not be returned due to component not containing cached entries following result will be sent:

<iq type="error" id="auditlog-2" from="[email protected]" to="[email protected]/res-1">
  <error type="cancel">
    <item-not-found xmlns="urn:ietf:params:xml:ns:xmpp-stanzas" />
  </error>
</iq>

Other types of errors specified by XMPP protocol might also be returned by server if during processing of request error occurred.