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:


cp /var/opt/mailarchiva/tomcat/webapps/ROOT/WEB-INF/classes/config_category_email.xml /etc/opt/mailarchiva/ROOT


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" />



The above XML definition deserves an explanation:


Element Example Description
name to field name
type string field type 
resource field_label_to resource name in file
use   what the field is used for. 
usage property custom defined email header




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


Usage   Description  
export   Allow field to be exported  
basicheaderview   Display field in basic header view  
advancedheaderview   Display field in advanced header view  
archiverule   Allow field to be used in archive rules  

Allow field to be used in search queries

retention   Allow field to be used in definition of retention rules  
searchresults   Display field in search results  
index_tokenized   Tokenize and index the field in the search index  
index_stored   Store and index the field in the search index  
index_tokenized_and_stored   Tokenize, store and index the field in search index  
ldap   Retrieve from ldap [currently not supported]  
download   Allow field to be downloaded  
viewsource   Allow display of field in view source  
print   Show field in print view  
view   Display field in main view  
stubrule   Allow field to be displayed in stubbing rule  
property   custom defined email header  




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

Data type   Description  
string   text string  
integer   integer value  
long   long value  
float   floating point value  

double value

boolean   true/false  
date   date time  
emailaddress   email address  
size   size in kb/mb/gb/tb  


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" />



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 -->



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 resource file:




The 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. 



© 2005 - 2024 ProProfs

Found this information useful? Visit to learn more about MailArchiva.