Maarch Communauté Forum Documentation Contact : info@maarch.org +33 1 47 24 51 59

Maarch Framework 3/Setup and configuration guide

De Maarch Wiki.

< Maarch Framework 3
Version du 17 septembre 2009 à 09:19 par Bca (discuter | contributions)
(diff) ← Version précédente | Voir la version courante (diff) | Version suivante → (diff)

Sommaire

Pre-requisites

  1. Maarch Framework can be installed on a Unix/Linux OS or Windows OS (client or server).
  2. An Apache 2.2.x or IIS server
  3. PHP 5.2.x
  4. Mysql 5.x, Postgres 8.3.x, MS SQL Server 2005
  5. To view PDF in Firefox, you have to install Acrobat Reader and PDFESCAPE (extension of firefox) or install Firefox 3 and Acrobat Reader.
  6. To be able to send alerts and notification by emails, you need either sendmail or any SMTP server (do not forget to specify it in the php.ini).
  7. To generate charts (for example in the stats module), PHP must be compiled with libGD (or even better libGD2). This is the standard configuration on windows, but not on all linux distributions.

Server configuration

PHP5 configuration

Maarch Framework requires PHP 5.2.x or later.

The php.ini file must follow these recommendations :

Error Handling and Logging

error_reporting  = E_ALL & ~E_NOTICE
display_errors = on

Data Handling

register_globals = Off

Session

session.auto_start = 0

Dynamic Extensions

Extension to enable :

  • mysqli, postgres or mssql (depending on which database management system you plan to use)
  • graphical library GD or GD2.

Allow Short Tags

short_open_tag = On

Html Charset

default_charset = "UTF-8"

Magic Quotes

magic_quotes_gpc = off
magic_quotes_runtime = off
magic_quotes_sybase = off

Smtp server

smtp = your_smtp_server
smtp_port = 25

For Win32 only : 

sendmail_from = sender_mail@your_adress.com

Installation Maarch Framework

Database Setup

Manually

The core, the apps and each modules has its own SQL scripts in an "sql" folder.

Here are the steps to setup the database :

  1. Create the base (ex : CREATE DATABASE maarch;).
  2. in this base, execute each "structure" sql script in this order :
    1. core
    2. every module you are planning to use
    3. apps
  3. repeat with every "data" sql scripts in the same order.

With create_sql_script.php

To make things faster, we provide a script called create_sql_script.php. It parses your config.xml file to get the list of enabled modules and generate to files, db_structure_v3.sql and db_values_v3.sql. These files cover sql scripts from the core, selected modules and the app in this order.

Just execute the script : 

php "/path/to/maarch"

If you are using windows, you may have to specify the path to php.exe: 

"c:\path\to\php.exe" "path\to\maarch"

You then have to :

  1. create the database
  2. execute db_structure_v3.sql in this base
  3. execute db_data_v3.sql in this base

Configuration of the docservers

Create the docserver Folder

Maarch Archive every documents in a special folder, called the document server (docserver).

The critical point is that the HTTP server must have write/read access to this folder. Under windows, this user is the system user. Under Unix/Linux, it is usually www-data or apache (depending on your distribution), and set up this folder permission accordingly.

A docserver can be any local or distant folder.

Examples of a docserver :

  • /var/maarch/docserver/
  • \\ServerName\DocServer\


Configuration of Permissions the docservers (Unix/Linux only)

As the user running apache must have right/read access to docservers, we recommpand the following Permissions under Linux (set the owner according to your configuration).

Path Owner Rights
/var/www/maarch_v3/ www-data or apache 700
/var/www/docserver/ www-data or apache 700

Configure the docservers in Maarch Database

Once you have installed the database, you must configure the docservers in the database. In the table docservers of Maarch database, there must be one line per docserver you want to use.

Be sure to fill the field path_template with the physical path to the docserver. The values must be reals paths (UNC compliance) to your docservers.

Here is an example of minimal information needed in the docservers table : 


INSERT INTO docservers (docserver_id, path_template,  size_limit, creation_date, coll_id, priority)
VALUES ('mydocserver','/var/maarch/docserver/', 10000000000, now(),'coll_1', 10);


You can find details about the table docservers here.

Maarch Configuration

All the label in xml config file are variabilized

Core Configuration

Path to the file: maarch_v3/core/xml/config.xml.

Picto infos.gif This section only shows the main configuration option of the config.xml file. More detailed information for advanced configuration may be found here

Main Configuration options

The main configuration options for the business app are found between the tags <CONFIG> and </CONFIG>.

The following must be edited according to your configuration and environment: 

<CONFIG>
  <corename>maarch_v3</corename><!-- same name as the main directory -->
  <corepath>/var/www/maarch_v3/</corepath><!-- link to the core path -->
  <tmppath>/var/www/maarch_v3/tmp/</tmppath><!-- link to the tmp path -->
  <defaultpage>/var/www/maarch_v3/index.php</defaultpage><!-- link to the welcome page of the framework -->
  <defaultlanguage>en</defaultlanguage><!-- default language of the framework, en or fr -->
  <coreurl>http://127.0.0.1/maarch_v3/</coreurl><!-- URL of the framework -->
</CONFIG>

Business App Registering

At least one business app must be declared in your core. An app is plugged in the core by adding a <BUSINESSAPPS> and </BUSINESSAPPS> bloc. Here is an example: 

<BUSINESSAPPS>
  <appid>maarch_sample</appid><!-- same name as the app directory -->
  <comment>_MAARCH_SAMPLE</comment>
</BUSINESSAPPS>

Business Application Configuration

Application Configuration : config.xml

Path to the file : maarch_v3/apps/APP_NAME/xml/config.xml.

Picto infos.gif This section only shows the main configuration option of the config.xml file. More detailed information for advanced configuration may be found here
Main Configuration of the apps

The main configuration options for the business app are found between the tags <CONFIG> and </CONFIG>.

The following must be edited according to your configuration and environment:

  • Details about the apps: 
<businessappname>APP_NAME</businessappname><!-- the name of the directory containing the business app -->
<businessapppath>/var/www/maarch_v3/apps/APP_NAME/</businessapppath><!-- the path to the business application-->
<businessappurl>http://127.0.0.1/maarch_v3/apps/APP_NAME/</businessappurl><!-- the url of the business application -->
<applicationname>Name of the App</applicationname><!-- the name of the business application -->
<tmppath>/var/www/maarch_v3/apps/APP_NAME/tmp/</tmppath><!-- tmp path -->
<lang>fr</lang><!-- lang the business application, currently en/fr -->


  • Configuration of your database server: 
<databaseserver>127.0.0.1</databaseserver><!-- ip or name of the database server -->
<databaseserverport>3306</databaseserverport><!-- port of the database server -->
<databasetype>MYSQL</databasetype><!-- type the database server: MYSQL/POSTGRES/MSSQL-->
<databasename>maarch</databasename><!-- name of the database -->
<databaseuser>the_user</databaseuser><!-- user of the database -->
<databasepassword>the_pwd</databasepassword><!-- password of the database -->
Definition of the Document Collections used in the App

Each collection must be defined between <COLLECTION> and </COLLECTION>. Here is an example: 

<COLLECTION><!-- one of the collection used in Maarch -->
  <id>coll_1</id><!-- id of the collection -->
  <label>_DOCUMENTS</label><!-- label of the collection : var defined in apps/APP_NAME/fr.php -->
  <table>res_x</table><!-- db table of the collection -->
  <view>res_view</view><!-- db view of the collection -->
  <index_file>index.xml</index_file><!-- file of the custom index for the collection-->
  <script_add>index_documents.php</script_add><!-- script to add a document to the collection -->
  <script_search>search_with_folder.php</script_search><!-- script to search the collection -->
  <script_search_result>list_results_documents.php</script_search_result><!-- script to show the list of search results -->
  <script_details>details_documents.php</script_details><!-- script to show the details page -->
</COLLECTION>
Which Actions appear in Logs

Between the tags <HISTORY> and </HISTORY>, there is a set of tags describing events that occurs during the execution of the application (this list is not complete, as each modules brings its own events).

You can enable or disable the logging of each event separately by setting them at true or false.

Enabling modules

Modules are enabled in this file. Every module you want to use must be declared with a <MODULES>...</MODULES> bloc.

For example: 

  <MODULES>
    <moduleid>autofoldering</moduleid>
    <comment>_AUTOFOLDERING</comment>
  </MODULES>

Tips to Configure Application

  • Scripts declared in collections : The configuration file tells which script is used for indexing, searching, result list and details for each collection. Those scripts are present in Indexing & Searching module. When you customize an existing script or create your own, think about changing its name from the original, so future Maarch versions won't override with your developments.

Configuration of the tmp directory (Linux/Unix only)

As for the docservers, the HTTP Server must have read/write access to the tmp directory. Permissions on this folder must be set the same way.

menu.xml

In this file, you can specify the functionalities of the business application you want to see in the Maarch menu. 

  <?xml version="1.0" encoding="utf-8"?>
  <ROOT>
  <MENU>
    <id>admin</id><!-- part menu id -->
    <libconst>_ADMIN</libconst><!-- part menu label --> 
    <url>index.php?page=admin</url><!-- part menu url -->
    <style>admin</style><!-- part menu css style-->
  </MENU>
  </ROOT>

services.xml

Services provided by the business application are defined in the service.xml.
We identified for the moment three pages potentially using the services modules : indexing, details and welcome page.
There is two type of service : administration or use.
The nature of service execution may be a frame, a popup, a tab, a background execution (put background in nature) or a button (put button in nature) to launch the service.
Its pages will be waiting for services of various modules.
We have some examples of services that may appear on these pages:

  • choose the good human resource folder on indexing page,
  • view the Missing pieces of a folder on the indexing page,
  • storing a document...

with the tag nature, you can used those keywords :

  • frame
  • popup
  • button
  • include
  • tab
  • listelement

you can also declare services which can launched in background during treatment such as the indexing. You can declare a preprocess service and/or postprocess a service.
Use this example : 

 <PROCESSINBACKGROUND>
   <page>file_index.php</page>
   <processorder>2</processorder>
   <preprocess>select_folder_result_preprocess.php</preprocess>
   <postprocess>select_folder_result_postprocess.php</postprocess>
 </PROCESSINBACKGROUND>

maarch_v3/apps/maarch_costes/xml/services.xml : 

 <?xml version="1.0" encoding="utf-8"?>
 <root>
    <SERVICE>
      <id>admin</id><== id of the service ==>
      <name>_ADMIN</name><== label of the service ==>
      <comment>_ADMIN</comment><== comment of the service ==>
      <servicetype>menu</servicetype><== if servicetype = menu, this id must be equal to the id of the menu item ==>
      <enabled>true</enabled><== put true if you want to enable the service ==>
   </SERVICE>
   <SERVICE>
     <id>admin_users</id>
     <name>_ADMIN_USERS</name>
     <comment>_ADMIN_USERS_DESC</comment>
     <servicepage>index.php?page=users&admin=users</servicepage><== script page of the service ==>
     <servicetype>admin</servicetype>
     <style>admin_users</style><== css style of the service ==>
     <enabled>true</enabled>
     <WHEREAMIUSED><== you can specify here where you want to use the service ==>
       <page>admin/admin.php</page>
       <nature>listelement</nature><== keyword of the service nature ==>
     </WHEREAMIUSED>
   </SERVICE>
   <SERVICE>
     <id>admin_groups</id>
     <name>_ADMIN_GROUPS</name>
     <comment>_ADMIN_GROUPS_DESC</comment>
     <servicepage>index.php?page=groups&admin=groups</servicepage>
     <servicetype>admin</servicetype>
     <style>admin_groups</style>
     <enabled>true</enabled>
     <WHEREAMIUSED>
       <page>admin.php</page>
       <nature>listelement</nature>
     </WHEREAMIUSED>
   </SERVICE>
   <SERVICE>
     <id>admin_architecture</id>
     <name>_ADMIN_ARCHITECTURE</name>
     <comment>_ADMIN_ARCHITECTURE_DESC</comment>
     <servicepage>index?page=admin_archi&admin=architecture</servicepage>
     <servicetype>admin</servicetype>
     <style>admin_architecture</style>
     <enabled>true</enabled>
     <WHEREAMIUSED>
       <page>admin.php</page>
       <nature>listelement</nature>
     </WHEREAMIUSED>
   </SERVICE>
   <SERVICE>
     <id>manage_diploma</id>
     <name>_MANAGE_DIPLOMA</name>
     <comment>_MANAGE_DIPLOMA_DESC</comment>
     <servicepage>index.php?page=diploma&admin=diploma</servicepage>
     <servicetype>admin</servicetype>
     <style>manage_diploma</style>
     <enabled>true</enabled>
     <WHEREAMIUSED>
       <page>admin.php</page>
       <nature>listelement</nature>
     </WHEREAMIUSED>
   </SERVICE>
   <SERVICE>
     <id>manage_contracts</id>
     <name>_MANAGE_CONTRACTS</name>
     <comment>_MANAGE_CONTRACTS_DESC</comment>
     <servicepage>index.php?page=contract&admin=contracts</servicepage>
     <servicetype>admin</servicetype>
     <style>manage_contracts</style>
     <enabled>true</enabled>
     <WHEREAMIUSED>
       <page>admin.php</page>
       <nature>listelement</nature>
     </WHEREAMIUSED>
   </SERVICE>
   <SERVICE>
     <id>view_history</id>
     <name>_VIEW_HISTORY</name>
     <comment>_VIEW_HISTORY_DESC</comment>
     <servicepage>index.php?page=history&admin=history</servicepage>
     <servicetype>admin</servicetype>
     <style>view_history</style>
     <enabled>true</enabled>
     <WHEREAMIUSED>
       <page>admin.php</page>
       <nature>listelement</nature>
     </WHEREAMIUSED>
   </SERVICE>
   <SERVICE>
     <id>show_contract_history</id>
     <name>_CONTRACT_HISTORY</name>
     <comment>_CONTRACT_HISTORY</comment>
     <servicepage>contract_history.php</servicepage>
     <servicetype>use</servicetype>
     <enabled>true</enabled>
     <WHEREAMIUSED>
       <page>index.php?page=salary_sheet</page>
       <nature>frame</nature>
       <width>400</width><== here you can specify the properties of you frame webparts) ==>
       <height>100</height>
       <scrolling>auto</scrolling>
       <border>0</border>
     </WHEREAMIUSED>
   </SERVICE>
 </root>

Modules configuration

Generic configuration of a module

global configuration

maarch_v3/modules/module_name/xml/config.xml : 

 <?xml version="1.0" encoding="utf-8"?>
 <root>
 <CONFIG>
   <name>basket</name><== name of the module, corresponds of the name of the folder ==>
   <comment>_BASKET</comment><== label of the module ==>
   <file_prefix>bask</file_prefix><== prefix file name of the module ==>
   <loaded>true</loaded><== put true if you want to load the module ==>
 </CONFIG>
 <TABLENAME><== list of the tables used in the module ==>
   <bask_baskets>baskets</bask_baskets>
   <bask_groupbasket>groupbasket</bask_groupbasket>
 </TABLENAME>
 <HISTORY>
   <basketadd>true</basketadd>
   <basketup>true</basketup>
   <basketdel>true</basketdel>
 </HISTORY>
 </root>

services provided by the module

maarch_v3/modules/module_name/xml/services.xml : 

 <?xml version="1.0" encoding="utf-8"?>
 <root>
 <SERVICE>
   <id>admin_baskets</id><== id of the service ==>
   <name>_ADMIN_BASKETS</name><== label of the service ==>
   <comment>_ADMIN_BASKETS_DESC</comment><== comment of the service ==>
   <servicepage>index.php?page=basket&module=basket</servicepage><== script page of the service ==>
   <servicetype>admin</servicetype><== if servicetype = menu, this id must be equal to the id of the menu item ==>
   <style>bask_admin_baskets</style><== css style of the service ==>
   <enabled>true</enabled><== put true if you want to enable the service ==>
   <WHEREAMIUSED><== you can specify here where you want to use the service ==>
     <page>admin.php</page>
     <nature>listelement</nature><== keyword of the service nature ==>
   </WHEREAMIUSED>
 </SERVICE>
 <SERVICE>
   <id>use_baskets</id>
   <name>_USE_BASKETS</name>
   <servicepage>use_baskets.php</servicepage>
   <servicetype>use</servicetype>
   <enabled>true</enabled>
   <WHEREAMIUSED>
     <page>welcome.php</page>
     <nature>include</nature>
     <width>1020</width>
     <height>750</height>
   </WHEREAMIUSED>
   <PROCESSINBACKGROUND>
     <page>file_index.php</page>
     <preprocess>select_folder_result_preprocess.php</preprocess>
     <postprocess>select_folder_result_postprocess.php</postprocess>
   </PROCESSINBACKGROUND>
 </SERVICE>
 </root>

menu of the module

maarch_v3/modules/module_name/xml/menu.xml : 

 <?xml version="1.0" encoding="utf-8"?>
 <root>
 <MENU>
   <id>indexing</id><== part menu id ==>
   <libconst>_INDEXING</libconst><== part menu label ==> 
   <url>//127.0.0.1/maarch_v3/modules/indexing_searching/index_file.php</url><== part menu url ==>
   <target>_blank</target><== html target link ==>
   <style>indexing</style><== part menu css style ==>
 </MENU>
 <MENU>
   <id>adv_search</id>
   <libconst>_ADV_SEARCH</libconst>
   <url>index.php?page=search_adv&module=indexing_searching</url>
   <style>searching</style>
 </MENU>
 </root>

Specific configuration of a module

alert scripts

maarch_v3/modules/script_alerts/config_script.xml : 

 <?xml version="1.0" encoding="UTF-8"?>
 <ROOT>
 <CONFIG>
   <databaseserver>127.0.0.1</databaseserver><== ip or name of the database server ==>
   <databaseserverport>5432</databaseserverport><== port of the database server ==>
   <databasetype>POSTGRESQL</databasetype><== type the database server MYSQL or POSTGRES==>
   <databasename>maarch</databasename><== name of the database ==>
   <databaseschema>public</databaseschema><== schema of the database ==>
   <databaseuser>the_user</databaseuser><== user of the database ==>
   <databasepassword>the_pwd</databasepassword><== password of the database ==>
      <pathtomaarch>/var/www/maarch_v3/</pathtomaarch><== path to maarch ==>
      <businessapppath>/var/www/maarch_v3/apps/maarch_costes/</businessapppath><== path to the business application ==>
      <app>/var/www/maarch_v3/apps/maarch_costes/scripts_alertes/</app><== link to scripts ==> 
      <reportmail>admin@maarch.org</reportmail><== admin mail ==>
      <lang>fr</lang>
 </CONFIG>
 <PARAMDATE><== list of parameters for all the alerts scripts ==>
   <incompletefolder1>15</incompletefolder1><== alert day + 15 after creation date ==>
   <incompletefolder2>30</incompletefolder2><== alert day + 30 after creation date ==>
   <endtrialandcdddate>15</endtrialandcdddate><== alert day - 15 before the end of the trial date of a limited contract ==>
   <emptyfolderdate>5</emptyfolderdate><== alert day + 5 after creation date ==>
   <endvisadate>10</endvisadate><== alert day - 10 before the end of the visa ==>
   <stopdisease>21</stopdisease><== min duration of a stop disease ==>
   <workaccident>8</workaccident><== min duration of a work accident ==>
   <medicalvisit1>90</medicalvisit1><== alert day + 90 after creation date ==>
   <medicalvisit2>365</medicalvisit2><== alert day + 365 after contract date ==>
   <medicalvisit3>730</medicalvisit3><== alert day + 730 after contract date ==>
   <docnotqualified>1</docnotqualified><== alert day + 1 after creation date ==>
 </PARAMDATE>
 <CUSTOM><== list of custom folder fields used in the scripts ==>
   <contractcustomfield>custom_t4</contractcustomfield>
   <folderemploymenttypeid>1</folderemploymenttypeid>
 </CUSTOM> 
 <TABLENAME><== list of the table used in the scripts ==>
   <folders>folders</folders>
   <foldertypes_doctypes>foldertypes_doctypes</foldertypes_doctypes>
   <foldertypes>foldertypes</foldertypes>
   <doctypes>doctypes</doctypes>
   <users>users</users>
 </TABLENAME>
 <RESOURCES><== list of the collection used in the scripts ==>
   <tablename>res_x</tablename>
   <comment>Documents</comment>
 </RESOURCES>
 </ROOT>

list of the alerts scripts :

  • alert_contract_not_signed.php
  • alert_doc_not_qualified.php
  • alert_empty_folders.php
  • alert_end_trial_and_cdd_date.php
  • alert_end_visa_date.php
  • alert_folder_incomplete.php
  • alert_medical_visit.php
  • alert_stop_disease.php
  • alert_work_accident.php

You can launch these scripts with a sh (Linux) or a bat (Windows) script.

SH -> launch_alert_folder_incomplete : 

 #!/bin/bash
 php "/var/www/maarch_v3/apps/maarch_costes/scripts_alertes/alert_folder_incomplete.php" 
 "/var/www/maarch_v3/apps/maarch_costes/scripts_alertes/config_script.xml"

BAT -> launch_alert_folder_incomplete.bat : 

 D:
 cd "D:\Program Files\xampp\php"
 php.exe "D:\ProgramFiles\xampp\htdocs\maarch_v3\apps\maarch_costes\scripts_alerts\alert_folder_incomplete.php" 
 "D:\ProgramFiles\xampp\htdocs\maarch_v3\apps\maarch_costes\scripts_alerts\config_script.xml"

In the directory reporting of the module, you can visualize the backup of sended alerts. We recommend to setup the launching of these scripts with the CRON (Linux) or the Windows scheduler.

Récupérée de « http://wiki.maarch.org/Maarch_Framework_3/Setup_and_configuration_guide »
Language