====================================================================
Alfresco Workdesk
Copyright (c) Alfresco Software, Inc. All Rights Reserved.
====================================================================

 *******************************************************************
 *      Sample Application: Human Resources Application v 2.7     *
 *******************************************************************

====================================================================
Setting up the Human Resources Application
====================================================================

Alfresco Workdesk Community Edition can be transformed to a 
fully-functioning Human Resources (HR) application. In order to do this,
your in-house Alfresco repository will need be filled with a data model 
and exemplary documents, and the configuration inside Alfresco Workdesk
Community Edition will need to be slightly adapted.

Based on:
- Alfresco Workdesk Community - AWC
- Alfresco Workdesk CMIS Adaptor
- Alfresco (Community Edition) - ACE

Prerequisites: 
- Java JDK 1.6 should be installed on your machine 
(to check type ">java -version" into your console window)

It was tested successfully with Alfresco Workdesk Community Edition 4.x and with Alfresco 
Community Edition 4.x (last test with alfresco-community-4.2.a-installer-win-x32.exe edition).
  
The Alfresco Workdesk Community Edition should be deployed and executed on the same machine
on which the Alfresco deployment is located.

Windows usage example: 

- run "install-workdesk-hr.bat" from the \bin\SamplApplication\HumanResourcesApplication\ folder

    install-workdesk-hr.bat -ap <alfresco_path> -u <alfresco_user_name> -p <alfresco_password> [-cp <alfresco_cmis_ws_port>]
        
        <alfresco_path> path of the Alfresco deployment
    
        <alfresco_user_name>     administrator user name for the Alfresco deployment
    
        <alfresco_password>      administrator password for the Alfresco deployment
        
        <alfresco_cmis_ws_port>  alfresco CMIS web service port (if absent port 8080 will be used) 
Example:

    >install-workdesk-hr.bat -ap C:\Alfresco -u admin -p admin
    >install-workdesk-hr.bat -ap c:\Progra~1\Alfresco -u admin -p admin
    or
    >install-workdesk-hr.bat -ap "c:\Program Files\Alfresco" -u admin -p admin
    (if you installed the Alfresco application under C:\Program Files\Alfresco)

Linux usage example: 

- run "sh install-workdesk-hr.sh" from the \bin\SampleApplication\HumanResourcesApplication\ folder
   or "chmod +x install-workdesk-hr.sh"
      "install-workdesk-hr.sh" 
      
   sudo install-workdesk-hr.sh -ap <alfresco_path> -u <alfresco_user_name> -p <alfresco_password> [-cp <alfresco_cmis_ws_port>]
        
        <alfresco_path> path of the Alfresco deployment
    
        <alfresco_user_name>     administrator user name for the Alfresco deployment
    
        <alfresco_password>      administrator password for the Alfresco deployment
        
        <alfresco_cmis_ws_port>  alfresco CMIS web service port (if absent port 8080 will be used)
        
Example:

    >sh install-workdesk-hr.sh -ap /opt/alfresco -u admin -p admin
    
    or
    
    >chmod +x install-workdesk-hr.sh      
    >sh install-workdesk-hr.sh -ap /opt/alfresco -u admin -p admin 
     
    (if you have installed the Alfresco application under /opt/alfresco)


Remarks:

    The parameter "-i <install_path>", of the install-workdesk-hr.bat, can be used to
	set the location of the data model that should be used for the HR scenario. 
	If the parameter is not used, the Open Air Installer tool is using the 
	default folder (\samples\workdesk-hr).


======================================================================
Update History
======================================================================
1.0 First version 
1.1 Generate multiple documents (Bulk import generation) 
1.2 Bug fixed: also supports Alfresco installations in other folders than C:\Alfresco
1.3 also support for Alfresco Community Edition 3.4.a and 3.4.b
1.4 Linux support for Alfresco Community Edition 3.4.b
1.5 support for multi-value choice list, tested with Alfresco Community Edition 3.4.d
1.6 file extension is now part of document title, tested with Alfresco Community Edition 3.4.e
1.7 support for Alfresco Community Edition 4.0.a
1.8 Extended Alfresco data model with Mandatory Aspects for HR Dossiers, Alfresco Community Edition 4.0.d
1.9 Fixed problem: Installer is not running in some time zones
2.0 Released and tested for Alfresco Workdesk Community 4.x and Alfresco Community Edition 4.0.e
2.1 Released and tested for Alfresco Workdesk Community 4.x and Alfresco Community Edition 4.2.a
2.2 Rebrand (WeWebU -> Alfresco) & extended data model (task management) 
2.3 Released and tested for Alfresco Workdesk Community 4.x and Alfresco Community Edition 4.2.c
2.4 Bug fixed: import now works on clients without internet connection, tested for AWC 4.x and ACE 4.2.e
2.5/2.6 Allow installation on Mac OS X too (just a Linux flavour), tested with AWC 4.2 and ACE 4.2.f
2.7 updated execution rights for Linux scripts

======================================================================
Additional Information
======================================================================
> For more information on Alfresco see: 
http://www.alfresco.com/
http://wiki.alfresco.com/wiki/Step-By-Step:_Creating_A_Custom_Model
http://wiki.alfresco.com/wiki/Data_Dictionary_Guide    

> For more information on Alfresco Workdesk Community Edition see: 
http://wiki.alfresco.com/

======================================================================
Short Install Descriptor Documentation
======================================================================
1. The descriptor XML root 
    <openair descriptor="descriptor-name">
        ...
    </openair>
   
   Contains a sequence of install actions.

2. Install actions 

2.1 Start alfresco 
    
    <startAlfresco/>
    
    Starts the alfresco deployment indicated by the command line arguments.
    
2.2. Stop alfresco
    
    <stopAlfresco/>
    
    Stops the currently running alfresco deployment indicated by the command 
    line arguments.
    
2.3 Import context based data 
    
    <importContext name="context-file-name"/>
    
    Imports the given model defining context from the install directory  
    to the alfresco deployment indicated by the command line arguments.
    The inner referred model will be also imported. 

2.4 Data Batch 
    
    <dataBatch forEach="collection-id" data="data-cursor" fork="5">
    ...
    </dataBatch>
    
    A sequence of data jobs executed for each data in the data collection indicated 
    by the 'forEach' attribute with the current data referred by the cursor 
    defined by the 'data' attribute. The fork attribute indicates the number 
    of threads used to process the current data batch.
    The 'forEach' and 'data' attribute should be used together and are optional.
    The 'fork' attribute is optional.
    
2.5 Data Jobs

2.5.1 Add Job
      
      <add repository="repository-name" path="path">
         ...
      </add>
      
      Contains a sequence of object definitions that will be added to the given 
      CMIS repository at the indicated path.

2.5.2 Set Job
        
      <set repository="repository-name">
        ...
      </set>   
         
      Contains a sequence of folder references whose properties will be set to the 
      given values.

2.5.2 Data Batch Job

      <dataBatch forEach="collection-id" data="data-cursor" fork="10">
            ...
            <dataBatch forEach="inner-data-cursor-collection-id" data="inner-data-cursor">
            
            </dataBatch>
            ...
      </dataBatch>

      A data-batch can be used as composite job.          

2.5.3 CMIS Object Definitions and References

     <document type="object-type">
        <content file="install-relative-content-file-path" mime="content-MIME"/>
        <property name="property-name">
            <values type="value-type">
                <value data="value-string-literal" />
             </values>
         </property>
         ...
     </document>
        
     Defines a new CMIS document object of the given cmis:document inheriting object-type.
     The content points to a content file with the given MIME.
     The document definition contains a sequence of property descriptions that will be set 
     for the newly created document.
     Property descriptions define the CMIS property name and contain its values as sequence 
     of value elements that define each value as a string literal through the data attribute. 
     The type of the value must  be specified by the values/@type attribute. The following 
     value types are accepted :
        - integer
        - string
        - decimal
        - boolean
        - datetime
        - id
        
     <folder [path="folder-path" | type="folder-type"]>
       <property name="property-name">
            <values type="value-type">
                <value data="value-string-literal" />
             </values>
         </property>
     </folder>

     Defines a new CMIS folder object of the given cmis:folder inheriting object-type if 
     the type attribute is present or a folder reference if the path attribute is present.  
     The folder definition or reference contains a sequence of property descriptions that will 
     be set for the newly created folder or for the one that is referred.

2.6 Data Collections
    
    Data named/identifiable collections are sequences of data elements , merger elements or 
    extension elements.
    
    <collection id="collection-id">
        ...
        <data>
           <field id="field-id" value=""/>
           ...
           <collection id="data-collection-id">
           
           </collection>   
        </data>
        ...
        <merger>
        
        </merger>
        ...
    </collection>
        
    Data elements define data-structure collection elements.
    Data structure entries are fields defined by field elements and other collections.      
    
    Example: 
    
    <data>
        <field id="firstName" value="John"/>
        <field id="lastName" value="Doe"/>
        <collection id="documents">
            ...
            <data>
                ...
            </data>
            ...
        </collection>
    </data>
           
    Merger elements define multiple data entries based on all combinations of field 
    value ranges.
    A field value range is defined using the range element specifying the values range as 
    separator delimited string : 
    
    <range id="fruit" values="apple,pear,plum" separator="," />
    
    Example: 
    
    <collection>
       <merger>  
         <range id="firstName" values="Martin,Rainer" separator="," />
         <range id="lastName" values="Bachtal,Koch" separator=","/>
       </merger>    
    </collection> 
  
    is equivalent with :
    
    <collection>
       <data>  
         <field id="firstName" value="Martin"/>
         <field id="lastName" value="Bachtal"/>
       </data>
       <data>  
         <field id="firstName" value="Rainer"/>
         <field id="lastName" value="Bachtal"/>
       </data>    
       <data>  
         <field id="firstName" value="Martin"/>
         <field id="lastName" value="Koch"/>
       </data>
       <data>  
         <field id="firstName" value="Rainer"/>
         <field id="lastName" value="Koch"/>
       </data>  
    </collection>

    Extension elements allow the merger or the decoration of existing collections.
    
    Example :   
           
    <collection id="employees">
        <extension collection="hardCodedEmployees" data="employee" index="index">
            <field id="name" value="{employee.firstName} {employee.lastName}" />
        </extension>
        <extension collection="largeEmployeeCollection" data="employee" index="index">
            <field id="name" value="{employee.firstName} {employee.lastName}{employee.multiplicator}" />
        </extension>
    </collection>
    

2.8 Data Collection Reference Language 
    
    Data batch defined string attribute string literals can make reference to already defined 
    collection data through curly-bracketed expression that will be replaced by the data field values 
    from the current collection definition context data.
    
    The following example will add a folder for each combination of first and last names defined in
    the persons collection. The following folders will be added /MartinBachtal, /RainerBachtal, /MartinKoch 
    and /RainerKoch.    
    
    <collection id="persons">
        <merger>  
         <range id="firstName" values="Martin,Rainer" separator="," />
         <range id="lastName" values="Bachtal,Koch" separator=","/>
       </merger> 
    </collection>
    <dataBatch forEach="persons" data="person">
        <add repository="Main Repository" path="/">
            <folder type="cmis:folder">
                <property name="cmis:name">
                    <values type="string">
                        <value data="{person.firstName}{person.lastName}" />
                    </values>
                </property>
            </folder>
       </add>
    </dataBatch>
    
    Please note that not all attributes of data batch contained elements can configured. 
    The following attributes of data batch contained elements support the data collection reference language:
    
    - data attribute of value elements  : <value data="{field-id}"/>  
    - path attribute of add job element : <add repository="Main Repository" path="/HR/{field-id}">
    - path attribute of folder element  : <folder path="/HR/Dossiers/{field-id}">
    - file and mime attributes of 
      document content  element         : <content file="{filed-id-file}/{document.resource}" mime="{filed-id-file}" /> 
      