YaMma Use Case: Yet another Mail management application
Methodology to build an Alfresco application in 10 steps
Introduction
This tutorial aims at providing the Alfresco developer a methodology to build powerful Alfresco application in 10 steps, and in 10 days. The project developed hereafter to explain this methodology is the track of a real one which consisted in digitizing paper documents into digitized documents with added information for a better use.
Methodology
A methodology is interesting if:
- it's easy to use
- it helps to produce sustainable software
- it's reproductible
Development is a repetitive and iterative scenario which can be modelized like this very simple process:
10 Steps
Step 1 / Think: Define User Requirements
At first, we need to define user requirements. We don't want the big picture immediately, we prefer a thinking process which can evolve.
The goal is to develop a project to attach metadata to scanned or uploaded document through adaptative forms and multi-role workflows. Moreover, according the chosen content type, used workflows may vary. This application can be used with any scanner, with Alfresco and the resulting application is finally a kind of digitization chain.
All type of documents may be processed. For the sake of the demonstration, we can imagine to process following kind of documents:
- outBoxMail, RIB
- car, entity
- mails, documents
Step 2 / Think: Stabilize Use Case
The user needs to digitize, to type, to share, to stock mail documents through a complex process, according its skills and access rights. Here are the five main features:
- 1/dematerialize file (scan documents)
- 2/store dematerialized documents
- 3/specify document type (associate meta data to content types)
- 4/process documents associated to these content types
- 5/file documents in the right place (in the classification scheme)
The following picture gives an overview of the modeling requirements diagram, composed of three categories of concepts:
- agent, like Vehicles, Administration Service or Administration Management
- goal, like manage dematerialized vehicles, mails, Store/Check documents, Approve mails
- entity, like vehicles or mails
Figure 4.1. Requirements Diagram
To address these features we follow the previous methodology by working on Input phase:
- design content types and metadata to generate the Alfresco repository configuration
- design forms to input data
We use Side-Labs as the IDE to design and finally produce the Alfresco application.
Step 3 / Input: Design Content Type
We define the following content types in only one data diagram titled "Digitization". It includes following content types:
- Document: name, comments, digitizationDate and author
- Annex: title
- Entity: name, denomination, dnb
- InBoxMail: date, destinationService, otherDestination, dateOf
You finally get the following data diagram with Side-Labs.
Figure 4.2. Digitization Data Model
Step 4 / Input: Design forms
The form diagram is built from the class model. The 'Load Resource' feature enables to retrieve the classes and properties contained in the data models. It is possible to load many data models, as in this tutorial. For example,'Document' class is composed of many properties (name, comments, author, …) assemble into two groups: Info and Digitization.
Moreover, the form modeler enables to organize classes and properties into various forms, either for usage concerns (beginner, normal or expert forms) or visual appearances (horizontal, vertical, tabbed and borderless presentation).
On the picture below, you can see the tree model followed by its outline view.
Figure 4.3. DataForm Model
Step 5 / Input: Test Form
The form diagram designed, we have to generate and deploy it with Side-Labs, which can be described as a 'super configurator' for Alfresco.
Model .application
First, it is nesessary to create an '.application' model to configure the options of generation and deployment. A documentation is available to guide the different scales http://www.side-labs.org/wiki/index.php/Documentation:User:GettingStarted.Here form has been obtained by choosing for:
- model: data and form models
- generation: KSR400 Form > SIDE Chiba Form Generator for Alfresco and KSR500 Data > SIDE Content Model Generator for Alfresco
- deployment: XForms > SIDE Chiba X-Forms Direct Deployer and > Alfresco > SIDE Alfresco Direct Deployer
The model results can be accessed via an index page which lists links pointing to the different forms produced, as illustrated on the pictures below.
Index forms
Figure 4.4. Index Forms
InBoxMail form
Figure 4.5. InBoxMail Form
Step 6 / Process: Workflow
Still using Side-Labs, configuration tool for Alfresco, the workflow's modeling involves creating the model of the same name .workflowdi.
Workflow model
As requirements and data models, we have three categories of objects:
- actors: DigitizationSystem, Car, Mail, Manager
- tasks and properties: SpecifyDocumentType, ManageCar, ManageMail, Approve
- links between different tasks: TypeDocument, ValidateDocumentType, ValidateCar, AskApproval, toComplete, ...
Figure 4.6. Workflow Model
Add actions
Moreover, the workflow modeler enables to add 'Actions' as in blue rectangles on the model below. An action fits on a transition by right clicking on it and choosing 'Add an action' > Alfresco. Four choices are possible as :
- send e-mail
- import PDF
- export PDF
- create new content
For example, the code corresponding to the action 'send e-mail' is ever written, so it is just necessary to click on it in the menu, and the Action's window will open, as shown below in the screenshot.
Figure 4.7. Action's code for sending automatically an email
Step 7 / Process: Form and Workflow integration
It is possible to start a workflow from a Form just by clicking on buttons. This way envolves to create a Form Workflow, which is a form model. A command exists to automate the creation of this form : open the workflow model and click right on it > choose SIDE > 'Initialize from model'. All Form Workflow have to be linked to a Data Form in the 'Properties' Field, that is the only one constraint of success. The same options as Form are useable (Group in a new group, tabbed presentation ...). Other features are specific on Form Workflow as editing an attribute in a task and seeing it in another, but most of the time a simple initialization is sufficient !
As the Form model, the Form Workflow model is a tree, as seen below.
Figure 4.8. Form-Workflow Model
Step 8 / Process: Test
To test the integration Form-Workflow we use a webapp by adding 'demo' at the end of thehttp://localhost:8080/xforms/demo/. This webapp is separated into five areas among which are 'Actions' for changing the parameters as Chiba URL, and 'Configuration' where it is possible to observe the different parameters of connexion.
Figure 4.9. Webapp Demo
But the two most important one are :
- 'Launch a new instance of workflow': to start the workflow choosen and the first task associated;
- 'Pooled tasks': to move from one task to another by validating them.
Figure 4.10. FormWorkflow
Step 9 / View: Browse
The view model enables to design exactly what you want to see from your data model to your Alfresco/Share application. As the form model, with a 'Load Ressource' and an 'Initialized from class', you retrieve the class data. Moreother, this model is easy to use, because it corresponds to a tree model whith which you structure informations by using drags and drops commands.
Figure 4.11. DataForm Model
The result on Alfresco Share appears as this:
Figure 4.12. First View of Metadata on Share
Figure 4.13. Second View of Metadata on Share
Step 10 / That's it !
As a conclusion we can present YaMma as an open source project to build a mail management system, which is easy to adapt to other projects. In terms of project management, it is:
- 10 models (data, form, workflow, view)
- 5 days of modeling including tests, alternatives solutions, prototypes and discussions with the end users
- 150 directories and files,
Of course, enhancement are possible. For example:
- it is possible to add new content type and metada associated
- it would be a good feature to add select list included on Form-Workflow for choosing between different content as 'Car' or 'Mail'for this project.
- it is possible to document all levels of the application. For data model, by right clicking on a class, the last tab of the window offers an area to write the concept description, and the .odt file is automatically generated at the same time as other amp. files.
Conclusion
Important links:
- update site for source models
http://www.side-labs.org/svn/models/SIDE-2/IS/ECM/Alfresco/3.2Labs/
- documentation to understand YaMma:
- documentation to replay YaMma: