Field Definition

MailArchiva supports the flexible definition of email fields. Email fields refer to items such as To, From, Subject, etc. 

By editing the field definition file, one can change which fields are indexed, exportable, viewable, etc.

Modify Field Definition

To modify the field definition, first copy a file called config_blob_email.xml to the configuration path. The source file is located at:

Refer to File System Layout for the exact location on your platform.

For example, on Linux copy as follows:

Thereafter, edit the config_blob_email.xml in the destination path using a Text editor. The structure of this file is described further below. After changing the field definition text file, to pick up the changes, the MailArchiva server must be restarted. The server will attempt to load the configuration from the configuration folder on startup.

Field Specification

Inside the XML file, all email related fields are defined. For example, the definition for the to field is as follows:

    <Field name="special" type="string" resource="field_label_special">

        <Use usage="property" param="name=X-Special" />

        <Use usage="export" />

        <Use usage="archiverule" /> 

        <Use usage="contentfilter" />

        <Use usage="stubrule" />

        <Use usage="searchquery" />

        <Use usage="retention" />

        <Use usage="index_tokenized_and_stored" param="name=special" />

        <Use usage="retention" />

        <Use usage="advancedheaderview" />

        <Use usage="basicheaderview" />

    </Field>

The above XML definition deserves an explanation:

Usages

These usages define what the field can be used for (for example, indexing, returning in search results, etc.)

Types

These data types define how the field data is stored in the index and how the field data is presented to the user.

Composite Fields

Composite fields are fields that are comprised of other fields. An example composite field is anyaddress. It is defined as follows:

<Field name="anyaddress" type="composite" resource="field_label_anyaddress">

        <FieldRef name="to" />

        <FieldRef name="from" />

        <FieldRef name="cc" />

        <FieldRef name="bcc" />

        <FieldRef name="deliveredto" />

        <FieldRef name="sender" />

        <FieldRef name="recipient" />

        <!--  <FieldRef name="rcptto" />

        <FieldRef name="mailfrom" /> -->

        <FieldRef name="journalrecipients" />

        <FieldRef name="journalsender" />

        <FieldRef name="journalto" />

        <FieldRef name="journalcc" />

        <FieldRef name="journalbcc" />

        <Use usage="archiverule" />

        <Use usage="stubrule" />

        <Use usage="searchquery" />

        <Use usage="retention" />

    </Field>

The field ref tag defines the fields that the container field anyaddress refers to. Thus, when one searches using anyaddress, all the fields it contains will be searched too.

Dynamic Fields

Using dynamic fields, one can configure MailArchiva to support any custom email header. For example, say your company's mailer set's the mime header X-Privilege. When

an X-Privilege dynamic field is added to the field configuration (i.e. config_category_email.xml), MailArchiva will retrieve the contents of the header and perform all the defined usages.  

For example, the X-Privilege dynamic field may be defined as follows:

 <Field name="xprivilege" type="string" resource="field_label_xprivilege">

        <Use usage="property" param="name=X-Privilege" /> <!-- INDICATES DYNAMIC RULE -->

        <Use usage="export" />  <!-- ADDS FIELD TO CSV EXPORT -->

        <Use usage="archiverule" /> <!- ADDS FIELD TO CONFIG-ARCHIVE RULE FIELD SELECTION -->

        <Use usage="contentfilter" /> <!- ADDS FIELD TO CONFIG-CONTENT FILTER SELECTION -->

        <Use usage="searchquery" /> <!-- ADDS FIELD TO SEARCH DROP DOWN -->

        <Use usage="retention" /> <!- ADDS FIELD TO CONFIG-RETENTION SELECTION -->

        <Use usage="index_tokenized_and_stored" param="name=xprivilege" /> <!- ADDS FIELD TO INDEX -->

        <Use usage="advancedheaderview" /> <-!-- INSERTS FIELD IN ADVANCED HEADER VIEW -->

        <Use usage="basicheaderview" /> <!-- INSERTS FIELD IN BASIC HEADER VIEW -->

        <Use usage="searchresults" param="colsize=20" /> <-- INSERTS FIELD INTO SEARCH RESULT -->

    </Field>

The name of the field must be equivalent to the name of the mime header.

If the field name must be translated into different languages, add the following line to the end of MailArchiva's application.properties resource file:

 field_label_privilege=Privilege

The application.properties file is located as follows:

Thereafter, MailArchiva must be restarted. In the example above, when a new email is encountered, the custom email header field "X-Privilege" should be extracted, indexed and stored. The field should also appear in the list of available fields in the search dropdown.