# Projman user manual

## Installation

### Downloads

First of all, since &projman; is a &python; script, you must have &python; installed !

&projman; requires the mx.DateTime package.

&projman; itself may be found here. The package contains the &projman; librairies and a command line tool, an example, the strptime.py module for M$ Windows unfortunate users and this documentation page. The main site is at &logilab;.

If you want to obtain another rendering than HTML or SVG, you must download the Pythonware's Python Imaging Library (PIL) available here

### Note for happy debian users

&projman; is available as a debian package. You can retreive it by adding "deb ftp://ftp.logilab.org/pub/debian unstable" to your `/etc/apt/sources.list` file.

### Install

Projman is a &python; script and provides distutils facilities. To install it, just extract it, enter in the extracted directory and run `python setup.py install`. It should be the same thing for all dependancy packages.

### Contribute!

Please consider contributing anything useful to this package.

## The projman files

You will find here a description of the different files that maybe found in &projman; description. Indeed, &projman; describes at least three files: one for the project description, one for the resources description and last for the activities (past or future) description. This is the minimal requirements for &projman; description. The other component that can compose &projman; is the result of scheduling. All the files used for &projman; description are independant from each other.

### Projman file

#### The DTD for the &projman; element

              <!ELEMENT projman (import-tasks | import-activities |
                                 import-resources | import-schedule)*)>
              <!ELEMENT import-tasks EMPTY>
              <!ATTLIST import-tasks
                        file          CDATA                   #REQUIRED>

              <!ELEMENT import-activities EMPTY>
              <!ATTLIST import-activities
                        file          CDATA                   #REQUIRED>

              <!ELEMENT import-schedule EMPTY>
              <!ATTLIST import-schedule
                        file          CDATA                   #REQUIRED>

              <!ELEMENT import-resources EMPTY>
              <!ATTLIST import-resources
                        file          CDATA                   #REQUIRED>

The &projmantag; node is the root of a &projman; description. You can import a resources file by adding a &importresources; child to this node which has the file attribute set to the file name. You can import too, an activities file, a project file, and finally a schedule file by adding a &importactivities;, &importtasks; or &importschedule; child to this node with as file name, the file attribute.

### Project file

#### Project

##### Portion of the DTD for the &project; element

                <!ELEMENT task (label?,link?,
                               (constraint-date | constraint-task)*,
                               constraint-resource+,
                               (task|import-project|milestone)+)>
                <!ATTLIST project
                          id            ID                      #REQUIRED>

                <!-- project from file -->
                <!ELEMENT import-project EMPTY>
                <!ATTLIST import-project
                          file          CDATA                   #REQUIRED>

The &project; node is the root of a project file description.

The &importtasks; node allows the project to be composed of multiple other projects. Everything will work as if this node was replaced by the content of this imported project file.

The &constraintres; is required in the main task. It describe the set of disponible resources for the project according to the resource descriptions file.

The &constraintdate;, &constrainttask; and &constraintint; nodes are all the possible constraints that can be set on a project. See constraintsgen for how to describe constraints.

#### Milestone

##### Portion of the DTD for the &milestone; element

                <!ELEMENT milestone (label?, link?, (constraint-date |
                                     constraint-task)*,
                                     (task|import-project|milestone)+)*)>
                <!ATTLIST milestone
                          id            ID                      #REQUIRED >

The &milestone; node is the atomic element that can compose a project. This is related to an events which takes place at a specific date but without any duration or timing information. Task and Project node inherits from Milestone.

#### Task

##### Portion of the DTD for the &task; element

                <!ELEMENT task (label?, link?, (constraint-date | constraint-task)*,
                                constraint-interruptible?,
                                (task|milestone|import-project)*)>
                <!ATTLIST task
                         id        ID                            #REQUIRED
                         load-type (shared | sameforall | oneof) #REQUIRED
                         load      float                         #REQUIRED
                         resource-role IDREF                     #REQUIRED>

                <!-- label and progress of the task -->

                <!ELEMENT label (#PCDATA)>

                <!ELEMENT progress (#PCDATA)>

                <!ELEMENT link>
                <! ATTLIST link
                        url      #PCDATA                          #REQUIRED>

The &task; node describes a given task, identified by its "id" attribute. A task maybe a container (i.e. contains some other tasks and/or milestone and/or imported projects) or a leaf. If it's a leaf, the &load; and &load-type; are required to indicate the number of days of work needed by this task and the number of resources associated.

The &progress; gives the percentage of work done for this task. A leaf task is considered as finished when its progress is 100%. Note that if you have a task with 2 days as duration and a 50% progress, &projman; will consider that this task needs one more day of work.

The node &priority; has value in range from 0 (lowest) to 9. By default, all tasks are considered as if they had a 5 priority. You can ordering task by setting this attribute. If a task t1 has a lower priority than a task t2, it's equivalent to having a task constraint "t1 begin after begin of t2". Note that if no "priority" attribute is present, a task will inherit from its parent priority.

The &resource-role; permits to assign one or more resource to a task. It design the profile of the resources needed to complete the task.

The &link; permit to associate an URL to a task. The link will be use after generation of gantt diagram, see renderinggen for uses of &link;

See constraintsgen for how to describing constraints. Another way to give constraint between task is to use the task's "priority" attribute.

### Constraints : date constraint, task constraint and interruptible constraint.

#### Portion of the DTD for the &constraintdate; &constrainttask; and &constraintint; element

              <!-- constraint between tasks  -->
              <!ELEMENT constraint-task EMPTY>
              <!ATTLIST constraint-task
                        idref    IDREF                          #REQUIRED
                        type     (begin-after-end|begin-after-begin|
                                 end-after-end|end-after-begin) #REQUIRED>
                        priority float                          #REQUIRED

              <!-- constraint on date for a task  -->
              <!ELEMENT constraint-date (#PCDATA)>
              <!ATTLIST constraint-date
                        type     (begin-after-date|begin-at-date|begin-before-date|
                                 end-after-date|end-at-date|end-before-date)
                                                              #REQUIRED
                        priority  int                         #REQUIRED>

              <!-- constraint on interruptible tasks -->
              <!ELEMENT constraint-interruptible EMPTY>
              <!ATTLIST constraint-interruptible
                        type          CDATA                   #REQUIRED
                        prority       int                     #REQUIRED>

You can chose a priority on each constraint. If all constraint can not be respected (no valid solution with them), the constraints of less priority will be dropped (best priority is 1, worse priority is 3)

#### Date constraints

The possible date constraint are the following : begin before date, begin at date, begin after date, end before date, end at date and end after date. The value of the &constraintdate; element must be in the standard date format.

#### Task constraints

A task constraint permits to give an order between tasks execution. The following type are possible : begin after end, begin after begin, end after begin and end after end. The most used is the begin after end constraint. The value of the &constrainttask; element must be a task id.

#### Interruptible constraints

This constraint is used to say that the task must be realized in consecutive days.

### Resources file

#### Resources-list

##### Portion of the DTD for the &resourceslist; element

                <!ELEMENT resources-list (resource|calendar)+ >
                <!ATTLIST resources-list
                          id        ID          #IMPLIED>

The &resourceslist; node is the root of resources file.

#### Resource

##### Portion of the DTD for the &resource; element

                <!ELEMENT resource (label)?, (use-calendar)*, (role)+>
                <!ATTLIST resource
                          id       CDATA             #REQUIRED

                <!-- time table of a resource -->
                <!ELEMENT use-calendar EMPTY>
                <!ATTLIST use-calendar
                          idref    CDATA             #REQUIRED>

                <!-- label of a resource -->
                <!ELEMENT label (#PCDATA)>

                <!-- role of a resource -->
                <!ELEMENT role
                          idref    CDATA             #REQUIRED>

The &resource; node describe a resource, identified by its "id" attribute. Usual resource "type" attribute are "worker", "computer"...

The &resource-role; describe skills of a &resource;, and its &hourly-cost;.

You can link a resource to its calendar with the &usecalendar; element. A calendar indicates when this resource is (not) available (see below for further description of calendar). If a resource is not linked to any calendar, the resource will be considered as available every day.

#### Calendar

##### Portion of the DTD for the &calendar; element

                <!ELEMENT calendar (label?, day-types, default-working,
                                    default-nonworking, (day|timeperiod)*, start-on?,
                                    stop-on?, calendar*)>
                <!ATTLIST calendar
                          id       CDATA             #REQUIRED>

                <!-- YYYY/MM/DD -->
                <!ELEMENT start-on (#PCDATA)>
                <!ELEMENT stop-on  (#PCDATA)>

                <!-- day covers two types of days: day of week {mon,
                tue, wed, ...etc}, the national days (holidays which takes
                place each year) mm/dd. -->
                <!ELEMENT day (#PCDATA)>
                <!ATTLIST day
                          type     CDATA             #REQUIRED>

                <!-- from YYYY/MM/DD to YYYY/MM/DD -->
                <!ELEMENT timeperiod EMPTY>
                <!ATTLIST timeperiod
                          from     CDATA             #REQUIRED
                          to       CDATA	         #REQUIRED
                          type     CDATA             #REQUIRED>

                <!ELEMENT default-working (#PCDATA)>
                <!ELEMENT default-nonworking (#PCDATA)>

The &calendar; node is done to define the resources availability. By default, every days are considered as worked. You can then add to a calendar some not worked days with the following nodes:

- &starton; indicates that days before this date are not worked.

- &stopon; indicates that days after this date are not worked.

- &day; indicates with the attribute "type", the type of the given day. "type"'s value is referered to the type of days declared in the node &daytypes;. The given day can be a day of the week taken in {mon, tue, wed, thu, fri, sat, sun} or a date , in short format MM/DD for the national day (e.g. day of nonworking type which take place each year).

- &timeperiod; indicates that days between "from" date and "to" date are of type indicated by the attributes "type". You can specify period of working type or non working type.

##### Portion of the DTD for the &daytypes; element

                <!ELEMENT day-types (day-type*)>

                <!ELEMENT day-type (label?, interval*)>
                <!ATTLIST day-type
                          id       CDATA         #REQUIRED>

                <!-- Interval of time for day-type -->
                <!ELEMENT interval EMPTY>
                <!ATTLIST interval
                          start     CDATA         #REQUIRED
                          end       CDATA         #REQUIRED>

The &daytypes; node defines the root of the description of all the type of days that the calendar could use to describe the resource unavailability.

The &daytype; node define a type of day. A type of day is defined by a label (e.g. the name of the day type) and an interval of working time. If a &daytype; node doesn't have a child node &interval;, that means that the type of day defined is a non working type. The attribute "start" and "end" of &interval; is a time in format HHMM.

For example, look at the following time table:

                <calendar id="c_john">
                <label>John's calendar </label>
                  <day-types>
                    <day-type id="work_day">
                      <label>Usual working</label>
                      <intervalstart="0800" end="1200"/>
                      <intervalstart="1300" end="1700"/>
                    </day-type>
                    <day-type id="day_off">
                      <label>Holiday</label>
                    </day-type>
                   </day-types>
                  <default-working
                idref="work_day"/>
                  <default-nonworking
                idref="day_off"/>
                  <day type="day_off">"sat"</day>
                  <day type="day_off">"sun"</day>
                  <timeperiodto="2004-06-12" from="2004-06-05" type="day_off"/>
                </calendar>

This table means that resources linked to this table won't work :

- every week on sunday and saturday

- the january 1 of every year

- from june 5 to june 12 of year 2004

This calendar means that a resource works from 8 a.m. to 12 a.m. and from 1 p.m. to 5 p.m..

#### Resource role

##### Portion of the DTD for the &resource-role; element

                <!ELEMENT resource-role (label)?>
                <!ATTLIST resource-role
                          id             CDATA             #REQUIRED
                          hourly-cost    int               #REQUIRED
                          cost-unit      CDATA             #REQUIRED>

### Scheduling file

#### Portion of the DTD for the &schedule; element

              <!ELEMENT schedule (constraint-date*, (task|milestone))>
              <!ATTLIST schedule
                        id            ID                      #REQUIRED">

              <!ELEMENT task (constraint-date*, priority, status?,
                              reports-list?)>

The &schedule; node is the root of the results from the scheduling. Each node &task; and &milestone; are element already existing in the project description. This file contains all the informations generated during the scheduling. That's why &task; and &milestone; can only have as children elements &constraintdate;, &priority;, &reportslist; and &status;. The &constraintdate; are essentialy of type "begin-at-date" and "end-at-date". The &status; is computed according to past and planned activities for this task. The &reportslist; contains &report; elements and describes the planned activties. (See activitiesgen for more informations on activities description.). The attribute "id" is a reference to the project associated to this results.

### Activities file

#### Portion of the DTD for the &activities; element

              <!ELEMENT activities ((task|milestone)*) >
              <!ATTLIST activities
                        id            ID                      #REQUIRED">

              <!ELEMENT task (reports-list)>

              <!ELEMENT reports-list (report)+>

              <!ELEMENT report EMPTY>
              <!ATTLIST report
                        idref         IDREF                   #REQUIRED
                        from          CDATA                   #REQUIRED
                        to            CDATA                   #REQUIRED
                        usage         CDATA                   #REQUIRED>

The &activities; node is the root of the registered activities (past and future) associated to the project as id the attribute "id".

A &report; node is a detailled description of an activity. The attribute "from" indicates the begin date of the activities and the attribute "to" indicates the end date. The attribute "idref" is a reference to the resource id which is linked to this report activity. The attribute "usage" describes the percentage of time the resource will spend on the task during this activity.

## Scheduling and rendering

As we said at the beginning, three functionnalities exists for &projman;. Also, there is three ways of using &projman;. Here is the synopsis of the &projman; command line possibilities:

        usage:
           1) To check problem:
           projman --check [--arg=value] <xml_input_file> <xml_output_file>

           2) To schedule the project:
           projman schedule [--arg=value]

           3) To render diagrams:
           projman diagram [--arg=value] diagram-type

           4) To generate XML documents for call for tenders:
           projman view [--arg=value] type

This can first schedule the project (by using schedule) and then generate the wanted diagrams (by using diagram). The specificity of &projman; is that you can schedule a project a single time and then generate the diagrams from the scheduling results. Each result of this operation are stored in XML files. You can choose the command check to validate your projman problem: the checker detect more usual errors in the problem description (malformed xml file, bad usage of tasks constaint, ...). The checker is automatically run before to schedule.

Now, we will describe how works each of &projman; functionnalities and all the options available for each mode.

### Converting

The different options available to convert file are the following ones:

              --in-format / -i
                         specifies the format of the input.
                         - planner
                         - pygantt
                         - projman

              --out-format / -o
                         specifies the output format.
                         - projman [default]
                           Generate activities_description.0.xml,
                           resources_description.0.xml and
                           project_description.0.xml if --project,
                           --resources and --activities
                           options are omitted.
                         - planner
                         - pygantt

              --project / -p
                         specifies the dest file path for the description
                         of the project

              --resources / -r
                         specifies the dest file path for the description
                         of the resources

              --activity / -a
                         specifies the dest file path for the description
                         of the activities

If <xml_input_file> contains more than one project description, the conversion will generate an output file for each project description.

### Checking

Before trying to schedule the projman problem, you can check it, and detect some inconsistancity (tasks cycle, incoherent constraints, ...)

The option avaliable for the checker mode are:

            --project-file
                    specify the project description file to use

              --verbose
                         display additional information during execution of projman

### Scheduling

You will find in this section some things that you should know about those differents algorithm.

&projman; provides two way to schedule a project : the standard (old) algorithm or another algorithm using constraint programming. Each algorithm try do reduce the end of the project.

The options available for the scheduling mode are:

              --project-file
                         specify the project description file to use

             --verbose
                         display additional information during execution of projman

              --time
                         stop the scheduling compute after time

              --type
                         scheduling method (csp or simple)

              --factorized_days
                         choose a step to schedule (1 is day, 2 is half a day,
                         4 is quater of day)

Be carefull: if you choose to use the factorized_days option, you will also have to use it for futur uses of projaman. For example, if you choose to schedule on half days, you will use the diagram command with the option --factorized_days=2

#### Default scheduling

The default algorithm is the fastest of both and will surely found a solution for a scheduling, even if all constraints are not satisfied. However, this algorithm handles resources assigments and resources calendar.

#### Constraint scheduling

This algorith will try to satisfy all the constraints described in the project file. If some constraints are unsatisfable, it won't find any solution. You should then correct your project file to make it find a solution.

Here are some hypothesis made by this algorithm :

- a resource work on a single task per day.

- a task is performed by a single resource. This means that if a task has more than one used resources, it will choose only one of these resources to work on this task.

- a task which doesn't have some used resources specified (nor its ancestors) is not affected by the tow previous point.

### Rendering

&projman; is able to draw the Gantt diagram in format svg.

The differents options available are:

             diagram-type
                          specifies the type of diagram to generate
                          this option is required
                          - resources (describes resources activities
                            in past and future)
                          - gantt
                          - gantt-resources (both)

              --verbose
    	              display additional information during execution of projman

              --project-file
    	              specify the project description file to use

              --output
                          specifie output file to use when a single diagram is
                          generated

              --selected-resource
                          specifies the id of the resource to take
                          in account for resources diagrams
                          [default=all resources]

              --format
                          specifies the output renderering for resources
                          diagram [default=svg] use only with schedule input
                          - html (bugs)
                          - png  (bugs)
                          - svg

              --timestep
                          timeline increment (day, week, month) for diagram
                          [default=day]

              --depth
                          specifies the depth to visualisate for diagrams
                          [default=0, this means all the tree]

              --view-begin
                          begin date for diagram view [default=date begin project]
                          ex: yyyy/mm/dd

              --view-end
                          end date for diagram view [default=date end project]
                          ex: yyyy/mm/dd

              --factorized_days
                         choose a step to schedule (1 is day, 2 is half a day,
                         4 is quater of day). If you scheduled with it, this option is required

The gantt diagram is a visualisation of project tasks along the time. If you use the &link; element in tasks file description, it will be possible to link an URL on tasks in the graph.

### XML documents

This mode of action proposes views to answer to call for tenders. Each view is an XML file which can be included in a global answer to call for tenders.

The differents options available are:

    	        type
                  	      Specify the type of view generated (not updated, cf manual)
                   	      - costs-table:  Will create a table in which the project's
                            tasks are listed with all costs informations
                          - tasks-list-section: Will dump tasks information and tables of
    		      main informations.
                          - duration-table: Will dump begin, end date of each tasks.
    		      - cost-para: Dump a summerization of the cost of the project
    		      - duration-para: Dump a summerization of dates of the project

              --project-file
    	              specify the project description file to use

              --verbose
                          display additional information during execution of projman

              --factorized_days
                          choose a step to schedule (1 is day, 2 is half a day,
                          4 is quater of day). If you scheduled with it, this option is required

              --output
    	              specifie output file to use when a single diagram is
                          generated

              display-date
                         display task's begin and end date (y or n)

          	  --format
                          set output format.
                          - [docbook]: respectful of format dockbook 4.2.
                          - html: NOT IMPLEMENTED YET
                          - csv: plain text with separator NOT IMPLEMENTED YET

## Annexes

### Related programs

If you're looking for GPL'd project management software, you should try ToutDoux, that aims to be a complete tool and needs Gnome libraries or Mr Project, a M$ Project clone (needs Gnome libraries too). Another possibility is TUTOS, written in PHP and which provide a bunch of others functionalities like a bug tracking system, an address book...

If you only want to draw Gantt diagram, try QtGantt, that needs Qt or JGantt, a Java component.