OpenScope’s MailTrix E-Mail Metric System is a complete, turnkey solution for collecting, managing, and publishing statistical information about your Lotus Notes e-mail environment.These instructions have been designed to help you install and configure the MailTrix software system for use in your Notes environment in under an hour. If MailTrix is already installed at your site, and you are performing an upgrade, please follow the upgrade instructions in this document.

Requirements

The MailTrix system consists of several components, and will require the following items:

A pre-existing Lotus Notes messaging infrastructure which is to be tracked. Lotus Notes version 4.x and higher are currently supported. Earlier versions may produce unexpected results and are not guaranteed to be reliable.
A Notes administrator account from which to install the software. Installation will require that several Notes databases be copied to each Notes Mail server and that a single Agent Manager task be scheduled. The admin account must have access control rights to perform these functions.
Access and the ability to adjust server configuration parameters and notes.ini parameters on each of your Notes Mail server. To operate at optimal ability, MailTrix requires adjusting the logging levels of the standard Notes log.nsf file. While MailTrix will gather a subset of data (most notably disk usage and user activity) without these adjustments, most sites prefer to make the changes to take advantage of the complete capabilities of the application.
Approximately 3 megabytes of disk space for every 100 users on each Notes mail server that will be running MailTrix. Approximately 5 megabytes of disk space for every 100 users in your Notes Mail environment on a Notes application server that will host the primary MailTrix software data warehouse.

Installation and setup of the MailTrix e-mail metric system involves performing the following tasks:

Requesting and receiving an evaluation license for the MailTrix software.
Properly configuring the logging levels and configuration values on each Notes mail server in your network.
Downloading and extracting the necessary software archives from the OpenScope Web site.
Using MailTrix’s configuration utility to identify each Notes mail server in your network, as well as designate a “master” Notes server which is to serve as the central collection and reporting point for the MailTrix system.
Use MailTrix’s auto-setup procedure to replicate MailTrix to each Notes mail server and the “master” Notes server. This procedure will also schedule a single Agent Manager task that operates MailTrix.
Manually set the replication formula on each MailTrix Data database for optimal performance and data throughput.

The entire installation process is dependent on the number of Notes mail servers you plan to track, but should take no more than an hour for moderate size installations.

Step 1: Request an Evaluation License

Before you can install and use the MailTrix system, you must first obtain an evaluation license for the product. OpenScope offers organizations the ability to try the MailTrix software for a period of time (usually a month or two) before making a purchase decision. If you’ve already requested and obtained an evaluation license, you can skip to Step 2. To request a license, please complete the form on the Evaluate page.

Within 24 hours of submission of your request, OpenScope will contact you via e-mail regarding your evaluation. Most organizations will be provided with an evaluation license string that will “unlock” the MailTrix software for a period of 2-3 months. Extensions to the evaluation period will be accommodated for those organizations that require more time to make a purchase decision.

While you are waiting for an evaluation license, you may wish to get started on some preparatory work for the MailTrix system. You should first decide on an architecture for the system. Essentially, MailTrix will be installed on each of your Notes Mail servers so that it can collect messaging data from your Notes environment. The main decision comes with regards to whether or not you wish to designate a non-Mail, application server, as the install point for the MailTrix “Master” server. The master server will serve as the central collection point for all messaging data and will be where data for all e-mail accounts will be aggregated and reported. It is recommended that this “master” server be a non-Mail server (for performance reasons), but MailTrix can support a server that acts as both “master” and mail server. Once a decision has been made, you could begin to perform steps 2 and 3 below so that you will be ready to complete installation upon receipt of your evaluation license.

Step 2: Configure Logging Levels & Agent Properties

MailTrix for Notes gathers most if its information from the standard Notes log file “log.nsf”. Unfortunately, the default logging levels and configuration settings for the Notes log file do not provide the level of detail MailTrix is capable of gathering, particularly in the area of messaging statistics. As a result, two minor adjustments should be made to the Notes logging process to optimize messaging statistics. Additionally, the MailTrix application runs as a standard Notes Agent, and as such is subject to restrictions placed on all Notes Agent’s that run on a particular server. Certain adjustments to agent restrictions will need to be made on each Notes mail server and the “master” server so that MailTrix will be granted a larger time window in which to perform its functions.

Even if the below adjustments are not made in a timely fashion, MailTrix will still properly function within your environment. The product is intelligent enough to detect what level of detail is available and to work with what the Notes logs provide. Therefore it is perfectly acceptable to run MailTrix prior to a rebuild of the Notes log files — the product will simply provide statistical information at a level commensurate with what is provided by the Notes log file. This may be necessary if recycling your servers must wait for a scheduled downtime.

Increase Mail Logging Level

By default, the logging level for mail routing within the Notes log file is set to only provide basic information. For gathering a more detailed analysis of messaging statistics (i.e. Size of Messages), MailTrix needs the administrator to increase the logging level for mail routing events. There is a minimal server performance increase generated by this additional logging, however, it should be unnoticed by end-users. You will also see a Notes log size increase of approximately 30%. To this date, all MailTrix for Notes customers have found that the detailed knowledge of user messaging activity provided by MailTrix is worth the maintenance of a relatively small increase in disk space consumption.

To make the necessary change, launch the Domino Administrator and select the “Configuration” tab for each mail server. Then select the “Configurations” view under the “Server” navigator:

Now click the “Add Configuration” action button and click the “NOTES.INI Settings” tab:

Click the “Set/Modify Parameters” button to reveal the adjustment dialog box. Click the drop down button next the the Item field to select “LOG_MAILROUTING” and enter “30” into the Value field. The input box should look like the following:

Be sure to press “Next” to add LOG_MAILROUTING to the Server Configuration box and then OK to transfer the changes from the dialog box to the Configuration document. It configuration settings document should look like the following:

Click the “Save and Close” button to save your changes. Make the same addition to all Notes mail servers you will be measuring.

Reset Notes Log File Parameters

MailTrix is a native Lotus Notes application written in Lotuscript, which is somewhat constrained when dealing with large data elements. Lotuscript has placed a limit of 32K on the size of data objects it can access, and the default configuration for the Notes log file allows for data elements of up to 40K in size. The net effect is that certain log elements that MailTrix uses to measure messaging traffic cannot be accessed by the software, resulting in limited collection of message traffic details. To address this limitation, Lotus has enabled administrators to adjust the maximum size of a data element that will appear in the Notes log file through a simple Notes INI file adjustment. To make the change, simply edit the Log= parameter in the Notes INI file so that it appears like the following:

Log=log.nsf,1,0,7,30000

This change, completely supported by Lotus Development Corporation, will set a 30K limit of data element sizes in the log file, and will not effect the performance or operation of the Notes logging process. The 30K setting enables MailTrix to properly collect very detailed messaging statistics about your users. In order for the change to take effect, the Notes server will need to be recycled and log file rebuilt. MailTrix will operate properly in the meantime, but simply be unable to provide the full level of detail it is capable of providing until your servers can be recycled.

This method of adjusting the log file build parameters is similar to what was done above with the LOG_MAILROUTING parameter. Simply add another configuration and “Set/Modify Parameters” to bring up the dialog box to add another INI parameter. Enter “LOG” in the item field and “log.nsf,1,0,7,30000” in the value field. Save the parameter by clicking the “NEXT” button and then “OK”. Here’s a sample screen shot:

Remember to make this change to all Notes mail servers that are to be measured.

Adjust Agent Manager Allowable Execution Time

By default the Agent Manager only allows Lotuscript agents to run for 15 minutes during nighttime hours and 10 minutes during daytime hours. The MailTrix agent, which run during the nighttime, on average require 30 to 60 minutes to complete messaging data extraction for a single day. When the messaging extract agent runs the first time on a server it will attempt to calculate the messaging statistics for every entry in the Notes log file. Depending on the number of days stored in the server log file this processing could take over 60 minutes to complete. For this reason it is best to configure the Agent Manager settings in the server configuration document to allow Lotuscript agents to run for 120 minutes during off hours:

Synchronize System Clocks on Mail Servers

Version 2.0 of MailTrix for Notes introduced message delivery time metrics to the MailTrix solution. To ensure that delivery times are properly calculated, it is imperative that you synchronize the system clocks on all of your mail servers. The clocks do not need to be synchronized to the same time zone, but the Greenwich Mean Time on the servers should be as close to synchronized as possible. This is because MailTrix will compare time stamps for messages passed from server to server, and any time skew, even of a few minutes, will result in skewed delivery time measurements.

Step 3: Download & Extract the Software

MailTrix for Notes is delivered as a standard ZIP file. To obtain the software archive, click on the following button:

Download Mailtrix for Notes

The archive should be copied to a Lotus Notes work station that will act as the installation and upgrade point for all future releases of the software. The software archive includes the following zipped files:

mtapp.ntf
mtdata.ntf
mtrep.ntf
mtreg.ntf
mtlog.ntf
mthelp.ntf
mtinstall\mtapp.nsf
mtinstall\mtdata.nsf
mtinstall\mtrep.nsf
mtinstall\mtreg.nsf
mtinstall\mtlog.nsf
mtinstall\mthelp.nsf

The archive should be extracted into the Lotus Notes document root directory (usually notes\data) on the workstation.

Once the files have been extracted, you will need to rename the “mtinstall” directory to “MailTrix”, which is the standard directory in which MailTrix resides (the software is delivered into the “mtinstall” directory so as not to overwrite previous installation upon a software upgrade.)

Adding the MailTrix Databases to the Workspace

As you may have noted from the composition of the software install archive, MailTrix is composed of six Lotus Notes databases that are located in the “MailTrix” directory off the Lotus Notes data directory (the software also includes six corresponding design template files that are installed into the root data directory.) The first order of business is to add the databases to your Notes workspace of your Notes client.

You now should be ready to begin configuring MailTrix.

Step 4: Configuring MailTrix for Notes

Before your can begin to configure MailTrix you must have requested and received an evaluation license from OpenScope. Once you have obtained the license, you will need to keep it at your disposal during the initial configuration of MailTrix.

Signing the Databases and Templates

The first task at hand is to sign all the MailTrix databases and templates so that they are authorized to operate within your environment. OpenScope recommends using a generic, administrator Notes ID for signing and installation since personal ID’s are tied to a specific individual who may eventually leave the organization, at which time their ID may be deactivated and which in turn may deactivate the MailTrix software since it will be operating under the installation ID. Use the Domino Administrator to sign all six MailTrix templates (mtapp.ntf, mtdata.ntf, mtrep.ntf, mtlog.ntf, mtreg.ntf, mthelp.ntf) and databases (mailtrix/mtapp.nsf, mailtrix/mtdata.nsf, mailtrix/mtrep.nsf, mailtirx/mtlog.nsf, mailtrix/mtreg.nsf, mailtrix/mthelp.nsf) on your local workstation.

Setting Proper Access Control Permissions

In order for MailTrix to install and operate properly, you must also set-up the access control properties on each MailTrix database and template. Access control properties are accessed by selecting a database icon on the work space, right mouse clicking, and selecting “Access Control…”. This will bring up the Access Control dialog:

Each MailTrix database comes pre-configured with an administrator Person Group called “NotesAdmin”, and administrator Server Group called “NotesAdminServers”. These control groups have been granted Manager access to each MailTrix database so that when the databases are placed into service on your Notes Mail servers, they can be administered by persons named by the “NotesAdmin” group and servers named by the “NotesAdminServers” group. If your Notes environment already has a Person Group that lists all valid Notes Administration accounts as well as a Server Group that lists all admin servers, you should now rename the pre-configured “NotesAdmin” and “NotesAdminServers” to correspond to your existing groups. Otherwise, you should create a “NotesAdmin” Person Group and a “NotesAdminServers” Server Group in the NAB, listing the appropriate entries so that when MailTrix is setup on each Notes Mail server, the databases can be appropriately accessed and administered.

Whichever configuration you choose, be sure to apply the appropriate changes to all six MailTrix for Notes databases and the corresponding six templates.

Initializing MailTrix

When first installing MailTrix, you will need to perform a one-time-only initialization to set some configuration parameters that are pertinent to your Domino environment. Currently, this involves installing a license to “unlock” the software and identifying the Internet domain names that are considered “internal” to your organization.

MailTrix for Notes is proprietary software developed by OpenScope, Inc. As such, it has been developed with a protection scheme to prevent unauthorized use via a textual license string mechanism that “unlocks” the software for a specific number of e-mail accounts for a specific network environment or period of time. To assist organizations in their decision to use the MailTrix metric solution in their messaging environment, OpenScope makes evaluation licenses available for a trial period of usually 30-60 days. If you have not done so already, you can request an evaluation license via our Evaluate page.

Once you have obtained a license string from OpenScope, you can unlock and initialize the software with it by performing the following:

Copy the provided license string (without any additional line feeds or carriage returns) to the clipboard.
Open the “MailTrix for Notes” database that you have extracted and added to your Notes workspace.
The default view is known as the “Servers” view and it will eventually provide a listing of all the Domino mail servers that you wish to track.
Press the “Initialize MailTrix” action button at the top of the view:
A dialog box will further explain the initialization procedure — click OK to continue.
The first configuration option is the license string. Manually enter or paste the license that you copied to the clipboard into the dialog box and click the OK button.
The second question asks you to specify the Internet domains that are considered “internal” to your organization. v2.3 of MailTrix introduced the ability for MailTrix to differentiate between internal Internet traffic, known as “Intranet” traffic, and external Internet e-mail traffic. So, if you wish to separate our traffic that is bound for or originated from internal Internet mail accounts, you should specify your internal Internet domains, separated by spaces. For example, OpenScope uses two domains — “openscope.com” and “mailtrix.com” so we would enter “openscope.com mailtrix.com” into the dialog box (without the quotes). Once you have listed all of your internal domains, click OK.
A final dialog box will display summarizing the configuration you have specified. Click OK to accept it.

Once MailTrix has been initialized and the license string has been configured, it is time to define your Notes mail environment and replicate MailTrix to the proper Notes servers.

Setting Up MailTrix on the “Master Server”

As described previously within these installation instructions, one of the Notes servers in your environment will be designated as the “master” server. The master MailTrix server will act as the central collection point for all messaging data and will be responsible for all report generation and data linking. Although it is recommend that the “master” server NOT be a Notes mail server (for performance reasons), the software will support either an independent or shared Notes server.

You will also need to allocate approximately 5 megabytes of disk space for every 100 users in your Notes Mail environment on the chosen “master” MailTrix server. For example, if your entire Notes messaging environment serves 5,000 accounts, plan to have 5,000 / 100 * 5 = 250 megs available for a mature implementation.

Once the server has been identified, it must be configured via MailTrix’s Server Configuration process. This process will be similarly performed for each Notes mail server within your Notes messaging environment.

Open the “MailTrix for Notes” database on your Notes workspace.
Select the “Servers” navigation item on left side of the view screen to bring up all Server Configuration documents.
Click the “Register New Server” button to create a new Server Configuration document.
In the Server field, enter the fully qualified Notes server name for the “master” server (i.e. “server1/domain”). Do not use quotes when specifying field values.
Click “Yes” option for Master Server? field.
If the master server is NOT a Notes mail server, select “Master” under the Config Doc field. If the master is a shared Notes mail server, select “Master-Mail”.
Enter “*” for the Cluster Servers field.
Click the “Save Server Configuration” action button at the top of the form to save the configuration.

Once the master server configuration document has been configured, it is time to install and setup the MailTrix software on the remote server. To accomplish this, you must be currently logged into Notes with a user ID that has administrator access to the master server so that several Notes databases can be replicated to the MailTrix directory under the data directory of the master server. Also, this user ID must be authorized to schedule an Agent task on the master server, since MailTrix requires a single automated Agent. Once these items are verified, click the “Setup Server” action button at the top of the Server Configuration form.

The “Setup Server” process performs the following tasks on the master server:

Copies the MailTrix design templates mtapp.ntf, mtdata.ntf, mtrep.ntf, mtreg.net, and mtlog.ntf to the master server.
Replicates or copies the production MailTrix databases MailTrix/mtapp.nsf, MailTrix/mtdata.nsf, MailTrix/mtrep.nsf, MailTrix/mtreg.nsf, and MailTrix/mtlog.nsf to the master server.
Schedules a single Agent task call MailTrixExec to run on an hourly basis from within the MailTrix/mtapp.nsf database.

If you encounter problems performing the server setup, check to make sure that your Notes ID has the proper authorization to perform the administrative tasks described above. Once setup is complete, your should add the database icons for all MailTrix databases on the master server to your work space. The databases on the master server will serve as the primary MailTrix environment to access data reports.

Setting Up MailTrix on Each Notes Mail Server

Once the master server has been configured, you must then configure each Notes mail server in your messaging environment. The configuration steps are very similar to those performed when configuring the master server with the notable exception of manually configuring the replication formula for the MailTrix Data database.

You will need to allocate approximately 3 megabytes of disk space for every 100 accounts on a particular Notes Mail server. For example, if a Notes mail server has 1,000 configured accounts, plan to have 1,000 / 100 * 3 = 30 megs available for a mature implementation.

Perform the following steps for each Notes mail server in your network:

Open the “MailTrix for Notes” database on your Notes workspace.
Select the “Servers” navigation item on left side of the view screen to bring up all Server Configuration documents.
Click the “Register New Server” button to create a new Server Configuration document.
In the Server field, enter the fully qualified Notes server name for the Notes mail server to be configured (i.e. “mail1/domain”). Do not use quotes when specifying field values.
Click “No” option for Master Server? field.
Select “*” for the Config Doc field.
If the Notes mail server that is being configured is part of a cluster of other Notes mail servers that provide fail over services for one another, MailTrix can be configured to properly handle data collection if such situations occur. This is accomplished by specifying the clustered servers in the Cluster Servers field. Each server that is part of the cluster should be listed, separated by semi-colons (;). Be sure to specify only the common name of each clustered server (i.e. “mail1”, not “mail1/domain”) and use only lower case.
Click the “Save Server Configuration” action button at the top of the form to save the configuration.
Click the “Setup Server” button to begin the installation and configuration process on the specified server. The setup process performs the following:
- Copies the MailTrix design templates mtapp.ntf, mtdata.ntf, and mtlog.ntf to the master server.
- Replicates or copies the production MailTrix databases MailTrix/mtapp.nsf, MailTrix/mtdata.nsf, and MailTrix/mtlog.nsf to the Notes mail server.
- Schedules a single Agent task call MailTrixExec to run on an hourly basis from within the MailTrix/mtapp.nsf database.

Once the mail server has been setup, it is important to manually set the replication formula for the MailTrix Data database. This database stores and maintains statistical documents for each Notes mail user on the server and replicates those to the master server, where the data can be used to generate reports. If a selective replication formula is not applied, each replica of the MailTrix Data database will maintain a complete document set for the entire Notes mail environment, resulting in a lot of wasted disk space and considerable amount of unnecessary replication traffic. By applying a selective replication formula, we can restrict the MailTrix Data database on each Notes server only contain documents particular to its Notes mail users.

To specify a selective replication formula on the MailTrix Data database, perform the following in your Notes client:

Click “File\Database\Open…” menu option on the Notes client (CTRL-O)
Specify the “Server” name of the server that has just been configured
Select the “Database” “MailTrix/MailTrix Data”
Click “Add Icon” to your workspace
Click “Cancel”
Select the newly added MailTrix Data icon
Right mouse-click, and chose “Replication Settings…”
Click the “Replicate a subset of documents” checkbox
Click the “Select by formula” checkbox

At this point you can specify a formula to restrict the amount of data being replicated between MailTrix Data databases. OpenScope recommends the following formula:

SELECT ServerID = “SERVERNAME”

where SERVERNAME is the lower case, common server name (i.e. “mail1”, not “mail1/domain”) of the Notes mail server on which the database is located. If the Notes server is clustered with other mail servers, the formula needs to specify those clustered server names as in the following:

SELECT ServerID = “SERVERNAME” | ServerID = “CLUSTER1” | ServerID = “CLUSTER2” …

Once again, all SERVERNAME and CLUSTER names should be lower case, common server names.

It is very important that you DO NOT set any selective replication on the MailTrix Data replica on your master server. This replica needs to contain data records from all mail servers so that MailTrix can properly report across your entire enterprise.

Verify Replication Settings

As alluded to previously, MailTrix operates by collecting e-mail usage data on each of your mail servers, storing the collected data in the MailTrix Data database. MailTrix then relies on Domino replication to synchronize the collected data on each mail server with the MailTrix Data replica on the master server, where the system can report against all e-mail statistical data collected for the enterprise. Therefore, for proper operation, it is imperative that replication is enabled to occur between each mail server and the master server. This replication can occur directly or it can be multi-tiered via hubs. You can also choose to restrict replication to only the MailTrix Data database (mailtrix/mtdata.nsf) if so desired. Domino replication is controlled via connection records in the NAB, which can be configured via the Domino administrator.

By default, replication is expected to occur on a daily basis. Statistical data collection is scheduled to occur during the 9 PM hour (local time) on each of your mail servers, and typically completes in an hour or two, depending on the number of mail files hosted by the server. Reporting on the master server is scheduled to kick of during the 1 AM hour (local time), so for fluid operation, replication between mail servers and the master server should be allowed to occur between 10 PM and 1 AM. You may need to adjust your connection records to allow for this replication to occur.

MailTrix daily collection and reporting cycle is completely adjustable and can even be moved to a weekly cycle, which is recommended for environments of 10,000 mail files or more. Should your environment require adjustments, please contact OpenScope for assistance.

Step 5: Verifying Correct Operation

To verify and validate that MailTrix is operating properly, you can check the MailTrix Log database for logging entries after a server has been setup. To do so, open the MailTrix/MailTrix Log database on a particular server and check the “MailTrix Executive” process entries. You should see “Begin MailTrix Execution” and “Complete MailTrix Execution” entries that will verify that the software has been installed and scheduled to run correctly. A definitive test is to peruse the databases on the MailTrix master server the day following your installation to verify that data has been collected and processed correctly.

Upgrading MailTrix for Notes

If you’ve already installed and configured MailTrix for Notes for your messaging environment and wish to upgrade the software to the latest version, perform the following steps:

Always backup the existing installation and configuration information on your Notes administrative work station. It should only be necessary to backup the contents of the MailTrix directory in the Notes data directory.
Download the latest version of the software from the OpenScope Web site via the following URL:
Download Latest Version of Mailtrix for Notes
Unzip the software into the Notes data directory on your administration work station
Sign the MailTrix templates with your generic admin ID and check the ACL settings on the extracted template files. Make sure they are consistent with the settings already on your existing databases in the MailTrix subdirectory.
Update the designs for each MailTrix database using the following steps on each database found in the MailTrix data directory:
- Select the “MailTrix for Notes” database on the work space.
- Click “File\Database\Refresh Design…” menu option from the Notes client menu.
- Make sure “Local” is selected, and click OK.
- Repeat the above process for each MailTrix database: MailTrix Data, MailTrix Reports, MailTrix Registry, MailTrix Log, and MailTrix Help.
Open the MailTrix for Notes database and select the “Servers” navigation link on the left side of the view.
Click “Edit\Select All” (CTRL-A) to select all server configuration documents.
Click the “Update Selected Servers” action button at the top of the view to replicate the new MailTrix software to all pre-configured servers running MailTrix.