Maarch Framework 3/Developer handbook/Core

De Maarch Wiki.

Summary

Overview of Core Classes

The core is composed of components that are essential to the performance of the applications built upon Maarch Framework and their modules.

In the core, there is no CSS and image. The graphical part is processed by the application (found in the apps directory).

Some features are managed by the core (classes and data model):

• Database access management (class_db.php)
• Queries generation (class_request.php)
• Connexion to the business application (identification + authentification : class_security.php)
• Storage management (class_docserver.php)
• Standardized methods to insert, update and delete a resource (class_resource.php)
• Portal management
• Management of connection and event logging (class_history.php)
• Common functions to all the applications : tool box (class_functions.php)

The philosophy is simple: process every fundamental mechanisms in the core.

Core Structure

 /core
   /class
     class_core_tools.php
     class_db.php
     class_docserver.php
     class_functions.php
     class_history.php
     class_portal.php
     class_request.php
     class_resource.php
     class_security.php
   /js
   /sql
     /data
       core.mysql.sql
       core.postgresql.sql
     /structure
       core.mysql.sql
       core.postgresql.sql
   /xml
     actions_page.xml
     config.xml
   manage_action.php

Security schema

Restricting parts of the archive for a user group

A common issue with standard DMS is that they put access control lists (ACL) on a document per document basis. This is very consuming in terms of resources, and not versatile enough for an archive. Indeed, if you need to modify access control rules on your dcument repository, it's important that it could be done easily an quickly, without modifying all the resources indexes.

Maarch security schema is suited to archives. It is based on filtering on a user group basis : each group has the right to see a set of the archive, because each result set is filtered with documents that can be viewed by the group. Filters are applied each time one has access to a Maarch collection.

Data model for applying security on resources

Here is described the data structure (DB tables and configuration files) used to apply Maarch security mechanisms.

First of all, users needs to be declared into users table :

• USER_ID varchar(32)
• PASSWORD varchar(255) /* encrypted */
• FIRSTNAME varchar(255)
• LASTNAME varchar(255)
• PHONE varchar(15)
• MAIL varchar(255) /* mandatory for notification */
• DEPARTMENT varchar(50)
• CUSTOM_T1 varchar(50) /* custom fields not used by standard release */
• CUSTOM_T2 varchar(50)
• CUSTOM_T3 varchar(50)
• COOKIE_KEY varchar(255)
• COOKIE_DATE
• ENABLED char(1)
• CHANGE_PASSWORD char(1)
• DELAY datetime

At the same time, groups are declared into usergroups table, and then users are attached to those groups using usergroup_content :

usergroups :

• GROUP_ID varchar(32)
• GROUP_DESC varchar(255)
• ADMINISTRATOR char(1)
• CUSTOM_RIGHT1 char(1)
• CUSTOM_RIGHT2 char(1)
• CUSTOM_RIGHT3 char(1)
• CUSTOM_RIGHT4 char(1)
• ENABLED char(1)

usergroup_content :

• USER_ID varchar(32)
• GROUP_ID varchar(32)
• PRIMARY_GROUP char(1)
• ROLE varchar(255)

Now let's see how resources are described.

In Maarch, electronic resources indexes are placed into res_x table. However, from the user and administrator point of view, resources are known as Maarch 'Collections'. A Collection is an abstraction for a resource repository; it is composed of a table where data is stored, a view from where the data is retrieved, as well as a description and id.

Collections are defined into <application>/xml/config.xml :

<COLLECTION>
 <COLLECTION_ID>COLL_INVOICE_2008</COLLECTION_ID>
 <COLLECTION_TABLE>res_invoice_2008</COLLECTION_TABLE>
 <VIEW>view_invoice_2008</VIEW>
 <LABEL>Invoices year 2008</LABEL>
</COLLECTION>
<COLLECTION>
 <COLLECTION_ID>COLL_INVOICE_2009</COLLECTION_ID>
 <COLLECTION_TABLE>res_invoice_2009</COLLECTION_TABLE>
 <VIEW>view_invoice_2009</VIEW>
 <LABEL>Invoices year 2009</LABEL>
</COLLECTION>

In this example, Collection 'COLL_INVOICE_2008' refers to data stored into res_invoice_2008 table. Because data for a resource can use external references to display labels, searches and result lists use SQL views that solve all references (for example, get the CUSTOMER_NAME from CUSTOMER_ID). When defining the SQL view, always put in the Select list a column called 'COLLECTION_ID', set with the id of the collection needed to access and update the resource. This column is used to know which table is to be updated, in the case of a multitable collection.

A multitable collection allows to browse and select resources across distinct primary collections. In the definition file, tag COLLECTION_TABLE is not filled, and the view definition implies more than one table.

If we had to make a search on all invoices, collection definition is defined as :

<COLLECTION>
 <COLLECTION_ID>COLL_INVOICE_ALL</COLLECTION_ID>
 <COLLECTION_TABLE></COLLECTION_TABLE>
 <VIEW>view_invoice_all</VIEW>
 <LABEL>All invoices</LABEL>
</COLLECTION>

view_invoice_all is a union of res_invoice_2008 and res_invoice_2009 :

SELECT "COLL_INVOICE_2008" as COLLECTION_ID, DOCDATE, ...
FROM res_invoice_2008
UNION
SELECT "COLL_INVOICE_2009" as COLLECTION_ID, DOCDATE, ...
FROM res_invoice_2009

Now that we have defined our resource repositories, we just have to filter group access, through table security :

• GROUP_ID varchar(32)
• COLLECTION_ID varchar(32)
• WHERE_CLAUSE varchar(255) /* filtering on collection */
• COMMENT text
• CAN_INSERT char(1)
• CAN_UPDATE char(1)
• CAN_DELETE char(1)

This internal schema is mostly managed through administration screens :

• Users management : define users and group appartenance
• Group management : define groups and access policy

Collections definition is made through xml config file.

Settings

config.xml

core/xml/config.xml

<?xml version="1.0" encoding="utf-8"?>
<ROOT>
	<CONFIG>
		<corename>maarch_v3</corename> <!-- same name as the main directory -->
		<corepath>C:\xampp\htdocs\maarch_v3\</corepath><!-- link to the core path-->
		<tmppath>C:\xampp\htdocs\maarch_v3\tmp\</tmppath> <!-- link to the tmp path-->
		<defaultpage>C:\xampp\htdocs\maarch_v3\index.php</defaultpage> <!-- link to the welcome page of the framework-->
		<defaultlanguage>fr</defaultlanguage> <!--default language of the framework, en or fr -->
 
		<coreurl>http://127.0.0.1/maarch_v3/</coreurl><!-- URL of the framework -->
 
	</CONFIG>
	<BUSINESSAPPS>
		<appid>maarch_sample</appid> <!-- same name as the application directory -->
		<comment>_MAARCH_V3</comment>
	</BUSINESSAPPS>
	<TABLENAME> <!-- list of the table used by the core -->
		<actions>actions</actions>
		<authors>authors</authors>
		<docservers>docservers</docservers>
		<doctypes>doctypes</doctypes>
		<extdocserver>ext_docserver</extdocserver>
		<fulltext>fulltext</fulltext>
		<groupsecurity>groupsecurity</groupsecurity>
		<history>history</history>
		<param>parameters</param>
		<resgroups>resgroups</resgroups>
		<resgroupcontent>resgroup_content</resgroupcontent>
		<security>security</security>
		<status>status</status>
		<usergroups>usergroups</usergroups>
		<usergroupcontent>usergroup_content</usergroupcontent>
		<usergroups_services>usergroups_services</usergroups_services>
		<users>users</users>
	</TABLENAME>
</ROOT>

actions_pages.xml

core/xml/actions_pages.xml

<?xml version="1.0" encoding="utf-8"?>
<ROOT>
     <ACTIONPAGE> 
	<ID>redirect</ID> <!-- Action identifier -->
	<LABEL>_REDIRECTION</LABEL> <!-- Action label : defined in the apps/app_name/lang/lang_file.php -->
    	<NAME>redirect</NAME> <!-- Action name -->
        <ORIGIN>module</ORIGIN> <!-- Where the action is defined : apps or module -->
	<MODULE>basket</MODULE> <!-- If the action is defined in a module, module identifier -->
    </ACTIONPAGE>
    <ACTIONPAGE>
	<ID>confirm_status</ID>
	<LABEL>_SIMPLE_CONFIRM</LABEL>
    	<NAME>confirm_status</NAME>
        <ORIGIN>module</ORIGIN> <!-- apps or module -->
	<MODULE>basket</MODULE>
    </ACTIONPAGE>
    <ACTIONPAGE>
	<ID>check_invoice_action</ID>
	<LABEL>_CHECK_INVOICE</LABEL>
    	<NAME>check_invoice_action</NAME>
        <ORIGIN>apps</ORIGIN> <!-- apps or module -->
	<MODULE></MODULE>
    </ACTIONPAGE>
</ROOT>

This file contains the actions pages, the scripts used as results when calling an action. Each ACTIONPAGE tag corresponds to an action page.

The labels are defined in the application languages files.