3. Features

Tigase Unified Archive Component contains few additional features useful for working with archives containing not only messages but also other informations.

3.1. Archive of Jingle call events

For instructions on how to enable Jingle call archive see Enabling Jingle call archive section.

3.1.1. Retrieving a list of collections

To retrieve collections with informations about Jingle call events item-type attribute needs to be added to <list/> element from section 7.1 Retrieving a List of Collections of XEP-0136 specification with value set to call.

A result it will be returned as specified in XEP-0136, but <list/> element will contain <events/> element for each collections instead of <chat/> element. Additionally <list/> element will have item-type attribute set to call.

Example

Request to retrieve collection of calls with juliet@capulet.com between 2014-01-01 00:00:00 and 2014-05-01 00:00:00

<iq type="get" id="query1">
    <list xmlns='urn:xmpp:archive'
      with='[email protected]'
      start='2014-01-01T00:00:00Z'
      end='2014-05-01T00:00:00Z'
      item-type='call'/>
</iq>

Response with single collection starting at 2014-02-01 13:01:34

<iq type="result" id="query2">
    <list xmlns='urn:xmpp:archive' item-type='call'>
        <events with='[email protected]' start='2014-02-01T13:01:34Z'/>
        <set xmlns="http://jabber.org/protocol/rsm">
            <first index='0'>0</first>
            <last>0</last>
            <count>1</count>
        </set>
    </events>
</iq>

3.1.2. Retrieve a list of entries from collection

To retrieve items with informations about Jingle call from collection item-type attribute needs to be added to <retrieve/> element from section 7.2 Retrieving a Collection of XEP-0136 specification with value set to call.

A result will be returned as specified in XEP-0136, but instead of <chat/> element <events/> element will be returned. Moreover instead of message subelements in <from/> and <to/> elements, there will be custom element containing information about call, ie. Jingle session ID - <sid/>.

Example

Request to retrieve calls events with juliet@capulet.com between 2014-02-01 13:00:00 and 2014-05-01 00:00:00

<iq type="get" id="query1">
    <retrieve xmlns='urn:xmpp:archive'
      with='[email protected]'
      start='2014-02-01T13:00:00Z'
      end='2014-05-01T00:00:00Z'
      item-type='call'/>
</iq>

Response with single entry of incoming call at 2014-02-01 13:01:34 with call SID.

<iq type="result" id="query2">
    <events xmlns='urn:xmpp:archive' with='[email protected]' start='2014-02-01T13:00:00Z' item-type='call'>
        <from secs='94' item-type='call'><sid>SID_OF_CALL</sid></from>
        <set xmlns="http://jabber.org/protocol/rsm">
            <first index='0'>0</first>
            <last>0</last>
            <count>1</count>
        </set>
    </events>
</iq>

3.2. Archive of login/logout events

For instructions on how to enable login history please see Enabling login history section.

3.2.1. Retrieving a list of collections

To retrieve collections with informations about user logins item-type attribute needs to be added to <list/> element from section 7.1 Retrieving a List of Collections of XEP-0136 specification with value set to login.

A result it will be returned as specified in XEP-0136, but <list/> element will contain <events/> element for each collections instead of <chat/> element. Additionally <list/> element will have item-type attribute set to login.

Example

Request to retrieve collection of login events of juliet@capulet.com between 2014-01-01 00:00:00 and 2014-05-01 00:00:00 (sent from juliet@capilet.com account)

<iq type="get" id="query1">
    <list xmlns='urn:xmpp:archive'
      with='[email protected]'
      start='2014-01-01T00:00:00Z'
      end='2014-05-01T00:00:00Z'
      item-type='login'/>
</iq>

Response with single collection starting at 2014-02-01 13:01:34

<iq type="result" id="query2">
    <list xmlns='urn:xmpp:archive' item-type='login'>
        <events with='[email protected]' start='2014-02-01T13:01:34Z'/>
        <set xmlns="http://jabber.org/protocol/rsm">
            <first index='0'>0</first>
            <last>0</last>
            <count>1</count>
        </set>
    </events>
</iq>

3.2.2. Retrieve a list of entries from collection

To retrieve items with informations about user logins from collection item-type attribute needs to be added to <retrieve/> element from section 7.2 Retrieving a Collection of XEP-0136 specification with value set to login.

A result will be returned as specified in XEP-0136, but instead of <chat/> element <events/> element will be returned. Moreover instead of message subelements in <from/> element, there will be custom element containing information about session, ie. <bind/> element with connection resource set as a value. There will be also type attribute added to <from/> element with value set to login to mark that this is login event.

Example

Request to retrieve login events of juliet@capulet.com between 2014-02-01 13:00:00 and 2014-05-01 00:00:00 (sent from juliet@capilet.com account)

<iq type="get" id="query1">
    <retrieve xmlns='urn:xmpp:archive'
      with='[email protected]'
      start='2014-02-01T13:00:00Z'
      end='2014-05-01T00:00:00Z'
      item-type='login'/>
</iq>

Response with single login entry at 2014-02-01 13:01:34 with call SID.

<iq type="result" id="query2">
    <events xmlns='urn:xmpp:archive' with='[email protected]' start='2014-02-01T13:00:00Z' item-type='login'>
        <from secs='94' item-type='login'><bind>balcony</bind></from>
        <set xmlns="http://jabber.org/protocol/rsm">
            <first index='0'>0</first>
            <last>0</last>
            <count>1</count>
        </set>
    </events>
</iq>

3.3. Retrieval of all events and messages

It is also possible to retrieve full history of login/logout events, and history of Jingle calls and messages.

3.3.1. Retrieve a list of entries

To retrieve items with informations about every archived entry item-type attribute needs to be added to <retrieve/> element from section 7.2 Retrieving a Collection of XEP-0136 specification with value set to any.

A result will be returned as specified in XEP-0136, but instead of <chat/> element <events/> element will be returned. <from/> and <to/> elements will have item-type attribute set to message, login, logout or call depending on type of returned event. Subelements of <from/> and <to/> elements will depend on type of archived event it represents.

Example

Request to retrieve events of juliet@capulet.com between 2014-02-01 13:00:00 and 2014-05-01 00:00:00 (sent from juliet@capilet.com account)

<iq type="get" id="query1">
    <retrieve xmlns='urn:xmpp:archive'
      with='[email protected]'
      start='2014-02-01T13:00:00Z'
      end='2014-05-01T00:00:00Z'
      item-type='any'/>
</iq>

Response with single login entry at 2014-02-01 13:01:34 with call SID.

<iq type="result" id="query2">
    <events xmlns='urn:xmpp:archive' with='[email protected]' start='2014-02-01T13:00:00Z'>
        <from secs='34' item-type='message'><body>Example message</body></from>
        <from secs='64' item-type='call'><sid>SID_OF_CALL</sid></from>
        <from secs='94' item-type='login'><bind>balcony</bind></from>
        <set xmlns="http://jabber.org/protocol/rsm">
            <first index='0'>0</first>
            <last>2</last>
            <count>3</count>
        </set>
    </events>
</iq>

3.4. Retrieval of recent events

It is now possible to retrieve list of last logged events (chat, calls, groupchats) for every bare jid with which archive owner communicated with. As this collection may be rather big, we added support for XEP-0059: Result Set Management to make it possible to request part of a list (ie. first 100 entries). For now it is only possible to request next entries of a list by providing offset/index at which next result should start at.

Warning

There is no support for RSM pagination done using <before/> and <after/>.

3.4.1. Retrieval of list of all recent events

In this example we will request and receive recent events of any type or condition from whole time for which we have entries in an archive.

Example request to retrieve full list of all recent events.

<iq type="get" id="query1">
    <query xmlns="urn:xmpp:tigase:recent"/>
</iq>

Example response to retrieval of all recent events.

<iq id="1" xmlns="jabber:client" type="result">
    <events xmlns="urn:xmpp:tigase:recent">
        <event
               with="[email protected]"
               type="call"
               direction="from"
               condition="success"
               time="2017-01-21T10:06:10Z" />
        <event
               with="[email protected]"
               type="groupchat"
               direction="from"
               body="Welcome to our groupchat"
               time="2017-01-20T10:08:12Z"/>
        <event
               with="[email protected]"
               type="chat"
               direction="to"
               body="Hello world"
               time="2017-01-19T17:20:51Z" />
    </events>
</iq>

3.4.2. Retrieval of list of all recent events in specified time period

In this example we will request and receive recent events of any type or condition which occurred within specified time frame.

Example request to retrieve full list of all recent events.

<iq type="get" id="query1">
    <query xmlns="urn:xmpp:tigase:recent" start="2017-01-20T00:00:00Z" end="2017-01-31T00:00:00Z"/>
</iq>

Example response to retrieval of all recent events.

<iq id="1" xmlns="jabber:client" type="result">
    <events xmlns="urn:xmpp:tigase:recent">
        <event
               with="[email protected]"
               type="call"
               direction="from"
               condition="success"
               time="2017-01-21T10:06:10Z" />
        <event
               with="[email protected]"
               type="groupchat"
               direction="from"
               body="Welcome to our groupchat"
               time="2017-01-20T10:08:12Z"/>
    </events>
</iq>

3.4.3. Requesting filtered list of recent events

It is also possible to filter list of recent events by event type

  • chat

  • groupchat

  • call (and call status)

    • success (successful call)

    • missed (missed call)

    • canceled (canceled call)

Requesting only recent chat events

Example request to retrieve full list of all recent chat events.

<iq type="get" id="query1">
    <query xmlns="urn:xmpp:tigase:recent">
        <event-types>
            <chat/>
        </event-types>
    </query>
</iq>

Example response to retrieval of recent chat events.

<iq id="1" xmlns="jabber:client" type="result">
    <events xmlns="urn:xmpp:tigase:recent">
        <event
               with="[email protected]"
               type="chat"
               direction="from"
               condition="success"
               time="2017-01-21T09:06:10Z" />
        <event
               with="[email protected]"
               type="chat"
               direction="to"
               body="Hello world"
               time="2017-01-19T17:20:51Z" />
    </events>
</iq>

Requesting only recent missed or canceled call events

Example request to retrieve list fo recent missed or canceled call events.

<iq type="get" id="query1">
    <query xmlns="urn:xmpp:tigase:recent">
        <event-types>
            <call>
                <missed/>
                <canceled/>
            </call>
        </event-types>
    </query>
</iq>

Example response to retrieval of recent missed or canceled call events.

<iq id="1" xmlns="jabber:client" type="result">
    <events xmlns="urn:xmpp:tigase:recent">
        <event
               with="[email protected]"
               type="call"
               direction="from"
               condition="missed"
               time="2017-01-20T10:06:10Z" />
        <event
               with="[email protected]"
               type="call"
               direction="to"
               condition="canceled"
               time="2017-01-18T17:20:51Z" />
    </events>
</iq>

3.5. Retrieval of transferred files metadata

It is also possible to query metadata of archived messages containing details of a transferred files. This metadata may be retrieved/queried by:

  • archive owner (by default)

  • admin owner (if ``allow-admin-querying-users-data`` is set to ``true``)

As returned result set may be quite large, mechanism supports XEP-0059: Result Set Management for pagination.

Note

All timestamps sent to the server or returned by the server using this extension are compatible with DataTime profile defined in XMPP Data and Time Profiles (XEP-0082)

Returned result set may be filtered with use of the following fields.

Name

Field type

Expected value

Description

Access

domain

list-single

Domain for which request sender is an admin

Return only files sent to/from a domain

Admin

owner

jid-single

User from a domain for which request sender is an admin

Return only files sent to/from a user

Admin

after

text-single

Timestamp

Returns only files sent after this timestamp

User / Admin

before

text-single

Timestamp

Returns only files sent before this timestamp

User / Admin

contains

text-single

Text

Returns only files for which name, description or url contain this text

User / Admin

media-type

text-single

Text

Returns only files for which media type contain this text

User / Admin

smaller-than

text-single

Number

Returns only files for which size is smaller than

User / Admin

bigger-than

text-single

Number

Returns only files for which size is bigger than

User / Admin

Note

If field will not be set, then its value will not be used to filter results.

Tip

If owner field is set, then domain field may be left empty.

Warning

If admin of a domain will not pass domain or owner it will receive results only from his own archive (files sent to or by him).

3.5.1. Retrieval of form fields

To know which fields you may specify to query archived files metadata, send following query:

Example request to retrieve form fields.

<iq type="get" id="queryForm1">
    <query xmlns="urn:xmpp:tigase:file:metadata"/>
</iq>

The server replies with all the form fields it support in queries:

Example response on form fields retrieval.

<iq type="result" id="queryForm1">
    <query xmlns="urn:xmpp:tigase:file:metadata">
        <x xmlns="jabber:x:data" type="form">
            <field var="FORM_TYPE" type="hidden">
                <value>urn:xmpp:tigase:file:metadata</value>
            </field>
            <field var="domain" type="list-single" label="Domain">
                <option>example.com</option>
            </field>
            <field var="owner" type="jid-single" label="Owner"/>
            <field var="after" type="text-single" label="After timestamp"/>
            <field var="before" type="text-single" label="Before timestamp"/>
            <field var="contains" type="text-single" label="Text to search for in name, description or url"/>
            <field var="media-type" type="text-single" label="Part of media type (MimeType)"/>
            <field var="smaller-than" type="text-single" label="Maximal size of a file"/>
            <field var="bigger-then" type="text-single" label="Minimal size of a file"/>
        </x>
    </query>
</iq>

Note

Fields domain and owner will available only when query would be executed by a user which is a domain administrator of any vhost at the installation.

3.5.2. Retrieval of transferred files metadata

To do that we send <iq/> of type set with <query/> element qualified with by namespace urn:xmpp:tigase:file:metadata which must contain data form with FORM_TYPE field set to urn:xmpp:tigase:file:metadata. The form may contains additional fields, but we may skip those fields for which we do not wish to provide values.

Optionally, to paginate or limit number of results, we may add <set/> qualified by namespace http://jabber.org/protocol/rsm as specified in XEP-0059: Result Set Management.

Example request to retrieve first page of results..

<iq type="set" id="query1">
    <query xmlns="urn:xmpp:tigase:file:metadata">
        <x xmlns="jabber:x:data" type="submit">
            <field var="FORM_TYPE" type="hidden">
                <value>urn:xmpp:tigase:file:metadata</value>
            </field>
        </x>
        <set xmlns='http://jabber.org/protocol/rsm'>
            <max>10</max>
        </set>
    </query>
</iq>

In the response server will return a <list/> element qualified by namespace urn:xmpp:tigase:file:metadata. In this element there will be a <set/> element qualified by http://jabber.org/protocol/rsm (see XEP-0059: Result Set Management) containing pagination details and a list of <item/> elements. Each <item/> element will contain following attributes: - id - ID of the message containing metadata - with - bare jid of a sender/recipient of a file - stamp - timestamp of a message - url - link to download the file

Additionally, domain admin will receive owner attribute which will contain bare jid of the owner of the archive in which result was found.

Each <item/> element will contain file element qualified by namespace urn:xmpp:jingle:apps:file-transfer:5 which may contain following elements:

  • media-type

  • name

  • desc

  • size

The <file/> element format is described in XEP-0234: Jingle File Transfer - 5. Application Format.

Warning

<file/> element will contains <name/>, <desc/>, <size/> and <media-type/> elements only if file transfer was initiated with XMPP <message/> containing description of a transferred file specified in XEP-0385: SIMS

Example response with first page of results.

<iq type="set" id="query1">
    <list xmlns="urn:xmpp:tigase:file:metadata">
        <item id="dcbb06cb-1d41-41bf-a4f3-396af26d0509"
            with="[email protected]"
            stamp="2021-04-28T08:15:04.063Z"
            url="https://example.com/uploaded/b2718a48-ed88-4afe-99c2-ee99219d896f/first.jpg">
            <file xmlns="urn:xmpp:jingle:apps:file-transfer:5">
                <media-type>image/jpeg</media-type>
                <name>first.jpg</name>
                <desc>First shared image</desc>
                <size>1334232</size>
            </file>
        </item>
        <item id="a8c131e8-5ed5-46dd-aef7-871fd88531ab"
            with="[email protected]"
            stamp="2021-04-28T09:25:04.563Z"
            url="https://example.com/uploaded/c5d0bc87-b3ef-4846-aee9-2855e067f03a/second.jpg">
            <file xmlns="urn:xmpp:jingle:apps:file-transfer:5"/>
        </item>
        ...
        <item id="f4805382-da50-46e5-a683-70dbd214a0cb"
            with="[email protected]"
            stamp="2021-04-28T12:53:14.862Z"
            url="https://example.com/uploaded/19d07312-6c10-40c0-b185-735fed7d452e/flower.jpg">
            <file xmlns="urn:xmpp:jingle:apps:file-transfer:5">
                <media-type>image/jpeg</media-type>
                <name>flower.jpg</name>
                <desc>Image of a flowers</desc>
                <size>1274422</size>
            </file>
        </item>
        <set xmlns='http://jabber.org/protocol/rsm'>
            <first index="0">dcbb06cb-1d41-41bf-a4f3-396af26d0509</first>
            <last>f4805382-da50-46e5-a683-70dbd214a0cb</last>
            <count>123</count>
        </set>
    </query>
</iq>

Tip

To retrieve next page of the results, send request with the same query but add <after/> or <before/> elements with proper values to the set element of the request.