De Maarch Wiki.

Installation & configuration

Prerequisites

PHP5 configuration

Maarch LetterBox needs PHP 5.0 or later. PHP config file is php.ini.

Error Handling

 error_reporting = E_ALL
 display_errors = on

PHP will display every error that occur during the execution of the scripts.Once is production, set display_errors to off.

Data Handling

 register_globals = Off

For security matters, it is recommended to set register_globals to Off.

Session

 session.save_path = "T:\TEMP\SessionsPHP"
 session.auto_start = 0

Set here the folder where session files wil be saved (adapt the path to your configuration). By default, php manage sessions with files. auto_start defaults to false, it is better to leave it this way.

Enabling PHP short tags

 short_open_tag = On

It enables the use of short tags (<?) as well as traditional tags (<?php). If this option is turned to off, Maarch LetterBox can't run.

Magic Quotes

Magic_quote_gpc = On

if magic_quotes_gpc is set to Off, Maarch LetterBox won't run.

Configuration Apache Web Server

Maarch LetterBox needs Apache 2.2 or later. Apache config file is httpd.conf.

Load PHP 5 module (Windows only)

 LoadModule php5_module "D:/Apps/php-5.2.0/php5apache2_2.dll"
 PHPIniDir "D:/apps/php-5.2.0"

Make sure PHP5 module is enabled in Apache web server

Defining root folder

 DocumentRoot "D:/Datas/wwwroot" 

All PHP files must be located in this folder. The path must be adapted to your local administration.

Configuration of MySQL Server

Maarch LetterBox runs withMysql from version 4.x. The ODBC connector for MySQL must be installed on the host server. Auto import module is necessary for loading scripts to work.

Installation of Maarch LetterBox

Creating the DocServer

The DocServer is the folder where all the files registered in Maarch Letterbox are stored. By consequence, it must be readable and writable by Apache. It means the owner of the folder must be the user who runs Apache (he must at least belong to Apche group). When in network, this folder must be shared.

Creating and Configuring the Data Base

Creating the Data Base

Import structure.sql in your MySQL manager to create the database and data table, and then import data_minimal_en.sql ou data_demo_en.sql (data_minimal adds just an admin while data_demo inserts a set of users and groups for an immediate use).

You must be allowed to create a database and to modify it to run those scripts. Otherwise, delete the two first instructions (creating and selecting the database) in structure.sql.

You can do it in CLI mode or by using a web manager, such as PHPMyAdmin

We recommand not to use phpmyadmin for that, as it does not handle utf-8 very well (a fix can be found here: http://www.developpez.net/forums/showpost.php?p=1222765&postcount=15).

To improve the management of utf-8 in phpMyAdmin, a solution seems to edit the [mysqld] section of my.cnf as explained in the forum ubuntu and ensure that the character set is utf8_unicode_ci : 1. With Notepad + +, encode both structure.sql and data_minimal_en.sql with 'UTF-8 files without BOM ' format. 2. In strucutre.sql, specifie for each table created : ENGINE=MyISAM DEFAULT CHARSET=utf8 COLLATE=utf8_unicode_ci 3. Edit my.cnf and add in the [mysqld] section : # utf8 init-connect='SET NAMES utf8' character-set-server=utf8 collation-server=utf8_unicode_ci 4. Restart apache and mysql servers 5. Choose UTF-8 on the logon screen of phpmyadmin 6. Once connected, select utf8_unicode_ci interclassement 7. Import the .sql files, ensuring that the character set of the file is utf-8

Configuring the Data Base

You have to modify the path to the DocServer in the data base. Update the field PATH_TEMPLATE in the docserver table.

NB: The path must end with slash (/).

Copying PHP Files

Copy the folder letterbox in the root folder of your web server. This folder contains all PHP and config files of Maarch LetterBox.

As for the DocServer, make sure that the folder letterbox/tmp is shared. If Maarch LetterBox runs on Linux, Apache must have reading and writing access to this folder.

Configuration of Maarch LetterBox

config.xml

It is located in the folder letterbox/xml : rename file config.xml.default to config.xml.

To make a quick install, just fill in the parameters to access the data base(databaseserver, databasename, databaseuser et databasepassword).

Description of config.xml tags :

• Databaseserver : name or IP address of your data base server
• databasename : name of the database used for Maarch LetterBox
• databaseuser : the name of the user who has acces to the data base used for LetterBox
• databasepassword : the password of this user
• nblinetoshow : number of lines to show in the different lists (Search, Admin panel,...)
• limitcharsearch : minimum number of character for a word to perform a search on
• lang : Default language used for Maarch LetterBox (only fr and en are currently available)
• adminmail : email address of Maarch LetterBOx admin
• adminname : name of Maarch LetterBOx admin
• enabledadvsearch : enables or disables Advanced search (true or false)
• enabledindexfile : enables or disables Indexation (true or false)
• enabledvideo : enables or disables videocoding(true or false) [not implemented in Maarch LetterBox: it MUST be set to false]
• enabledvalidation : enables or disables Mail validating (true or false)
• enabledprocess : enables or disables Processing mails (true or false)
• enablestats : enables or disables statistics viewing (true or false)
• xmlpath : folder in which XML config Files are stored
• debug : enables or disables debugging mode (true or false)
• applicationname : name of the aplication. It is displayed in the browser.
• css : relative path to the css file for Maarch LetterBox
• css_ie : relative path to Internet Explorer css file for Maarch LetterBox
• css_ie7 : relative path to Internet Explorer 7 css file for Maarch LetterBox
• img : relative path to Maarch LetterBox image folder
• MaarchURL : Url to access Maarch LetterBox (used in warning mails)
• DefaultPage : Default page for Maarch LetterBox modules
• exportlist : path where csv filses are saved
• CookieTime : Durée de la session Maarch LetterBox en minutes
• RESOURCES : name of resources tables. If you modify anything here, make sure to also modify access rights to resources in the administration panel of Maarch LetterBox.
  • Tablename : identifyier of the table.
  • Comment : comments associated to the table. it is used in the collection dropdown menu in advanced search.

to make sure your application is well configured, go to the URL for Maarch LetterBox in your Browser. You must see the login page.

history.xml

In this file, you can set up which events will be logged. By default, all events are. You can disable some here.

fichier features.xml

Here you can activate additional functionalities :

• enablechangenotif: Enable mail notifications when a folder is reassigned
• redirect_list: Give users the ability to edit the mailing list when reassigning a folder to another department
• gdi_index: Add a field to report an external identifier to a mail.
• mail_for_answer_by_index_file: Send a mail to a folder's main recipient when an answer is attached for indexing for
• show_welcome_graph: Disable the chart on welcome page (set this to false if it is too slow to display this page)
• search_max_size: Maximum number of results returned by searches
• printsep: Department seperator pages printing. Useful for mass digitisation.
• modifycopylist: When a folder is reassigned, the main recipient is set in the copy. It also gives the possibility to add users to copy list from processing form.
• update_limit_date: Allow to edit a folders processing deadline when joining a new document to it.
• tag100_for_copy: When reassigning a mail, old main recipient's number of view is set to 100. A new basket can be created to view those mail only.
• collectivities: Enable management of several public administrations. Actually, it allows grouping departments in higher level entities.
• action_waitingdoc: Makes it possile to put a document on hold from processing form.
• before_waiting_doc: Makes it possile to put a document on hold from qualification form.
• mail_for_new_note: Enable mail notifications when a new comment is added on a folder

extensions.xml

Here are defined all document format that can be recorded in the application. By default, MS Office, OpenOffice and main media formats are enabled.

Example of configuration for PDF:

<FORMAT>
  <name>PDF</name> 
  <mime>application/pdf</mime> 
</FORMAT>

letterbox.xml

This file is divided in several section to define:

• titles (Mr, Mrs, etc.)
  • Ex : <CIV>Mr</CIV>
• natures of mail (postal, courier, etc.)
  • Ex : <NAT>postal</NAT>
• Neighbourhoods (Mainly used by public administration, it is used in a folder's additional information).
  • Ex : <QUA>SoHo</QUA>

Administration of Maarch LetterBox

To access Maarch LetterBox Admin panel, click on "Administration", then "Summary" in the "Menu".

Departments

List of departments

There are two ways to access the list of departments:

• Select "Manage departments" in the dropdown box
• Follow the link "Manage departments" in the administration panel

Departments are sorted by identifier in alphabetical order. Clicking on the letters in the alphabet will show only the departments whose identifier begins by the letter you clicked.

If you know the identifier of a specific departments, you can look for it by entering its id in the search box.

The following actions on departments are available :

• Modifying a group information
• Remove a group
• Add a new group

Add/modify a Department

Mandatory fields are identifier and description.

Once a department is created, its id cannot be changed. The id can only be composed of alphabetical and numerical characters.

You can optionally associate a template of mailing list to each department. This list will be proposed on indexation page when selecting the department (you still can modify the mailing list while indexing).

To create or modify a mailing list click on "create a mailing list" or "modify the list".

To add new users to the list, click on "Add" on the line of the user you want to add. You can the same way remove a user from the list or modify the order of users in the list.

Removing a Department

You can't remove a department that owns at least one document. You first have to give ownership of these documents to another department. As a matter of fact, documents must belong to a department to be viewed.

User Groups

List of User Groups

There are two ways to access the list of user groups:

• Select "Manage user groups" in the dropdown box
• Follow the link "Manage user groups" in the administration panel

Groups are sorted by identifier in alphabetical order. Clicking on the letters in the alphabet will show only the groups whose identifier begins by the letter you clicked.

If you know the identifier of a specific group, you can look for it by entering its id in the search box.

The following actions on groups are available :

• Modifying a group information
• Suspend/Authorize a group
• Remove a group
• Add a new group

Modifying/Adding a Group

Modifying/Adding a Group: simple mode:

Modifying/Adding a Group: advanced mode:

Mandatory fields are the group (its id) and at least one defined access.

Once a group is created, its id cannot be changed. the id can only be composed of alphabetical and numerical characters (a-z, A-Z and 0-9).

the description may contain the role of the group. While filling it is not mandatory, it might be very useful.

Checkboxes stands for fonctionnal rights:

• Administration right: allow the access to the "Administration" panel
• Configuration right: allow the access to the "Configuration" panel
• Satistics viewing right: allow the access to statistics
• Late mail viewing right: adds two mail statuses in the advanced search: "first warning" and "late mail"
• Modifying right : allows modifying some indexes in a mails detailed page.
• Exporting rights : allows the export of search results in CSV
• Printing rights : allows printing search results, lists of documents in baskets, and docuiments details form
• Deleting rights : allows deleting a document

"Resource access" is actually a restriction on documents contained in the data base. An access is composed of the name of a table from the database and a WHERE clause, and of the rights of insertion and update if necessary.

there is two modes to create access :

• Simple mode : Automatic creation through the use of lists of Department (« Droits de consultation Â» checked)
• Advanced mode : see below.

The simple mode allows quick creation of groups whose rights are abouts recipient departments. The advanced mode enables a more precise right management. ("Other rights" checked)

Advanced mode

the WHERE clause is an SQL restriction clause without using the word "where". If it is left empty, the group will have access to ALL the document in the base. Once an access is created, you cannot modify it.

The following actions on access are available :

• Remove
• Add
• Update the rights

Each time insertion and/or update rights are modified on one or several access, click on "Update the rights" to take the changes into account.

Once all changes are done, click on "Accept the changes". To validate the creation of a new group, click on "Add a new"

Users

List of users

There are two ways to access the list of users

• select "Manage users" in the dropdown box
• Follow the link "Manage users" on the administration panel

Users are sorted by identifier in alphabetical order. Clicking on the letters in the alphabet will show only the users whose name begins by the letter you clicked.

If you know the identifyer of a specific user, you can look for it by entering his/her name in the search box.

Following actions on users are available :

• Modify a user's information
• Suspend/Authorize a user
• Remove a user
• Add a new user

Add/Modify a user

Mandatory fields are identifier, name, first name, department, email address, and primary group.

Once a user is created, it is impossible to change its id. Identifiers must only contain alphabetical and numerical characters.

The other fields are optional. The "department" field is displayed between parenthesis next to the name of the user up right on the screen and in the situation bar on the home page.

A user can belong to more than one group. It is then important to select its primary group.

Following actions on users are available:

• Remove a user from a group
• Add the user to an existing group
• Choose the primary group of the user
• Manage vacancies (for an already existing user)

When a new user is created, its password is 'demo'. The user will be asked to change it on its first login.

To reset a user's password, just click on the button "Reset password". The new password will be 'demo'. then again, the user will be asked to change it on its next login.

Once the changes are done, click on the button "modify the user" to validate them.

Baskets

List of baskets

There are two ways to access the list of baskets:

• Select "Manage baskets" in the dropdown box
• Follow the link "Manage baskets" in the administration panel

Baskets are sorted by identifier in alphabetical order. Clicking on the letters in the alphabet will show only the baskets whose identifier begins by the letter you clicked.

If you know the identifier of a specific basket, you can look for it by entering its id in the search box.

The following actions on baskets are available :

• Modify information of a basket
• Remove a basket
• Add a new basket

Add/ Modify a Basket

Once a basket is created, its id cannot be changed. The id can only be composed of alphabetical and numerical characters

The basket is the name of a basket which will be displayed in the whole application. It is then mandatory.

Description, however, is not mandatory

"Table" is linked to the collection. By default, Maarch LetterBox only has one collection, "mail".

The field "View on the table" is actually an SQL restriction clause without using the word "where" (as for the advanced edit mode in the administration of groups). If it is left empty, the basket will show every document recorded in the table.

Two internal variables can be used in the where clause :

• @user : stands for the identifier of the current user
• @groupuser : stands for the identifier of the primary group of the current user.
• @entities : stands for the department of the current user
• @my_entity : stands for the list of departments the current user has access to.

Finally, to be efficient, a basket must be associated to user groups. As a matter of fact, a user has access to any basket associated to its primary group.

To associate a group to a basket, click on "Associate a new group to a basket".

You first have to choose the group in the drop down menu. Then, choose to authorize or not redirection in this basket. If the "redirection" checkbox is checked, choose towards which departments or users the redirection can be done. Finally, choose the page that will be used to display the basket.

Four pages are currently available:

• Mail Processing
• Mail validation
• Mail in copy
• Authorized departments.

Once all your changes are made, click "Add the group" to validate"

The name of the group then shows in the list of associated groups. To modify the parameters of a group, click on the name of the group.

Once the configuration is over, click "Modify the basket" to validate.

Logs

There are two ways to access to this page:

• select "View logs" in the dropdown menu
• follow the link "View logs" in the administration panel

All events logged are those selected in config.xml.

The list of events can be sorted by date, user, affected table, type of action. by consequence, it is possible to find quickly any event.

Reopening a Mail

If a user closed a mail by error, he/she still can ask the administrator to reopen it. The administrator have to enter the GED number of the mail and click "Modify the Status".

Configuration of Maarch LetterBox

Document types

list of document types

There are two ways to access the list of document types:

• Select "Manage document types" in the dropdown box
• Follow the link "Manage document types" in the administration panel

Types are sorted by identifier in alphabetical order. Clicking on the letters in the alphabet will show only the types whose identifier begins by the letter you clicked.

If you know the identifier of a specific type, you can look for it by entering its id in the search box.

The following actions on document types are available :

• Modify information of a type
• Remove a type
• Add a new type

Add/Modify a document type

EVERY field is mandatory.

Once a type is created, its id cannot be changed. The id can only be composed of alphabetical and numerical characters

Document types depend on documentary collections. By default, Maarch LetterBox only has one collection, "mail". If you have added other collection, make sure to select here to which collection does the type belong.

The field "Processing deadline" is the maximum amount of days available to process a mail of this type. It is computed from the registering date of the mail.

The field "time before first warning" is used for notifications. It is the number of days before the deadline when the first warning will be sent.

The field "time before second warning" is used for "late" notification. It is the number of days after the deadline when the notification will be sent.

Templates

Document templates are useful to generate answers while processing mail.

List ofTemplates

There are two ways to access to this page :

• Select "Manage the baskets" in the dropdown menu
• Follow the link "Manage the baskets" on the administration panel

Templates are sorted by identifier in alphabetical order. Clicking on the letters in the alphabet will show only the templates whose name begins by the letter you clicked.

If you know the identifier of a specific template, you can look for it by entering his/her name in the search box.

Following actions are available:

• Modify the information of a template
• Remove a template
• Add a template

Add/Modify a Template

The name of the template will show when generating an answer on the indexation page. It is then mandatory.

You can also add optional comments.

Maarch Letterbox uses a slightly modified version of the open source editor TinyMCE. You can add custom dynamic fields through the menu "Maarch options". Elements of this list refer to indexes that were filled in while indexing the mail. They will automatically be replaced by matching data when the answer will be generated.

Templates are associated to at least one department. If it is not attached to any department, it will never be shown during processing.

While processing a mail, the list of templates will display all the templates associated with the recipient department.

Once all changes are done, click on "Validate the changes".

Administration of Senders/Shippers

First are the senders of mail you receive. You can define a list of predefined sender that write to you very frequently.

Shippers are the persons or institutions who your outgoing mail comes from.

These two sections have been merge in this doc, as they are working exactly the same.

Liste of senders

There are two ways to access this page :

• Select "Manage senders" in the dropdown box
• Follow the link "Manage senders" on the administration panel

Senders are sorted by identifier in alphabetical order. Clicking on the letters in the alphabet will show only the senders whose identifier begins by the letter you clicked.

If you know the identifier of a specific sender, you can look for it by entering its id in the search box.

Following actions are available:

• Modify the information of a sender
• Remove a sender
• Add a new sender

Add/Modify a new sender

The only mandatory field is the name. all others are optional.

Default users

Several users are configured in a fresh install of Maarch LetterBox to enable immediate use of the application.

Additional configuration: extensions.xml and letterbox.xml files

Extensions.xml

You can find this file in maarch_letterbox/xml<tt>. it contains every format of allowed document and their associated MIME type. If you want to allow new formats, just add a format tag in this file. For example :

 <FORMAT>
   <name>PDF</name> 
   <mime>application/pdf</mime> 
 </FORMAT> 

<tt>Letterbox.xml

This file is also located in maarch_letterbox/xml. It contains information displayed in several dropdown boxes. Add or remove a tag to respectively add or remove an entry.

• <CIVILITE>: regroups all civilities.
  • Ex : <CIV>Mr</CIV>
• <NATURE>: regroups all possible type of mail.
  • Ex : <NAT>Simple mail</NAT>
• <QUARTIERS>: regroups all neighborhoods, used in mail processing.
  • Ex : <QUA>SoHo</QUA>

Using notification scripts

Maarch LetterBox proposes three level of notification:

• New incoming mail to process or in copy (notif.php)
• First warning, to alert of the remaining time to process a mail (relance1.php)
• Notification of late mail (relance2.php)

For each kind of alert, there is a script you can enable or disable according to your needs. those are batch scripts to be run daily.

To activate a notification, you MUST have an active outgoing mail server (SMTP).

Configuration of scripts: config_notif.xml file

config_notif.xml file enables to configure all notification scripts. It is designed the same way as config.xml.

• <CONFIG>
  • <databaseserver>: Address of your database server
  • <databasename>: name of the data base used by Maarch LetterBox
  • <databaseuser>: user of the data base
  • <databasepassword>: password for the data base
  • <lang>: chosen language (currently, only Franch is available)
  • <mailfrom>: email address used to send configuration
  • <debug>: activation of debug mode (true/false)
  • <UNIXserver>: whether it is a unix server or not (true/false)
  • <MaarchDirectory>: path to Maarch LetterBox (must end with a slash)
  • <MaarchURL>: URL to access Maarch LetterBox
• <TABLENAME>
  • <doctypes>: table containing the type of handled documents (meeting,...)
  • <history>: Log table for access to the data base (think about emptying it when it becomes too big)
  • <listinstance>: the table containing the different mailing lists according to the type of documents
  • <users>: User table
  • <services>: Departments table
• <RESOURCES>
  • <tablename>: table with information on documents
  • <comment> : Comment on the table

Enabling scripts on Windows

On Windows, the easier way is to create a scheduled task.

Step 1 : Create a bat file

This file will run a php command line to run the notification script

Open a text editor (notepad for example) and enter this (all on the same line, it is here wrapped for readability reasons):

 path\to\your\php.exe
       "Path to Maarch Letterbox\scripts connexions\name of the script to run"
       "Path to Maarch LetterBox\scripts connexions\config_notif.xml"

Example with xampp (All must be on the same line !):

 C:\ProgramsFiles\xampp\php\php.exe
       "C:\ProgramsFiles\xampp\htdocs\maarch_letterbox\scripts connexions\notif.php"
       "C:\ProgramsFiles\xampp\htdocs\maarch_letterbox\scripts connexions\config_notif.php"

Save this file with the extension .bat ex : script_notif.bat

Step 2: Create a scheduled task

A scheduled task is a windows tool to... schedule the run of an application or of a script.

Open Windows "Control Panel", then choose "Task Scheduler", and "create a scheduled task".

Click on "Browse" and choose the .bat file you just create.

Name the new task as you wish and choose "every day".

Choose the time when the new task must begin. We advise you to run the task at a specific time when you are certain no new mail will be added. Then choose when you want to run it from.

Then click on "Next" and do what you are asked to do.

Start the whole process again for every notification you want to activate.

Enabling script on Linux/Unix

On Linux, you don't need to make a .bat file and to create a scheduled task. You can run the PHP script from crontab.

To access crontab configuration, open a terminal of your choice and enter :

 ~ $ crontab -e

In the editor that opened, add a line such as:

 50 23 * * * Chemin_de_l'exe_php Chemin_script_à_lancer (avec d'éventuels arguments)
 

In this case, the script is the script is run every day at 11:50 PM.

You need to add a line in the crontab for every script you want to run.

To have more information about crontab or about its syntax, consult cron manpage.