RenJuan/TASKPM
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

user-manual: connectors user manual

Browse source
This commit is contained in:
miciele Ghiorghis 2013-04-25 16:43:08 +02:00 • committed by Lorenzo Tilve Álvaro
parent 95a5052463
commit 55c1bb7903
1 changed files with 215 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

215
doc/src/user/en/18-connectors.rst Normal file
View file

@ -0,0 +1,215 @@
Connectors
##################
.. contents::
Connectors are Libreplan client applications that could be used to communicate with (web) servers to get
data, process and store them. At this moment there are two connectors, JIRA connector and Tim Enterprise Connector.
Configuration
=============
Connectors should be configured properly before being used. They can be configured from configuration's ``Main Setting``
screen, the tab ``Connectors``.
The connector screen comprises:
* ``Pull-down list``: a list of available connectors
* ``Properties edit screen``: a property ``edit form`` for the selected connector
* ``Test connection button``: to test the connection with the connectors
Select the connector you would like to configure from the ``pull-down`` list of connectors. A ``property editor form``
for the selected connector will be shown. In the ``property editor form`` you can change the values of the properties
to your likes and test your configurations using the ``Test connection`` button.
.. NOTE::
The properties are configured with default values. The most important one is the property ``Activated``. By
default it is set to ``N``. This indicates that the connector would not be used unless you change the value to ``Y``
and save the changes.
JIRA connector
==============
JIRA is an issue and project tracking system.
JIRA connector is an application that can be used to request JIRA web server for JIRA issues and process the response.
The request is based on ``JIRA labels``. In JIRA, labels can be used to categorize issues.
So the request is simple like this: get all issues that are categorized by this ``label-name``.
The connector gets the response, in this case the issues and convert them to Libreplan's ``Order elements`` and ``Time sheets``.
The *JIRA connector* should be configured properly before being used.
Configuration
-------------
From the configuration's ``Main Setting screen`` choose the tab ``Connectors``.
In the connectors screen select the JIRA connector from the ``pull-down`` list. A ``property editor screen``
is displayed now.
In this screen you can configure the following property values:
* ``Activated``: Y/N, whether you want to use the JIRA connector or not. Default is ``N``.
* ``Server URL``: the absolute path to the JIRA web server.
* ``user name and password``: the user credentials for authorization
* ``JIRA labels: comma-separated list of labels or URL``: Either you enter the label URL or a comma separated labels.
* ``Hours type``: type of work hours. Default is ``Default``
.. NOTE::
JIRA labels: At this moment JIRA web server doesn't support to provide a list of all available labels. As work around
we have being developed a simple PHP script that does a simple SQL query in JIRA database to fetch all distinct labels.
You can either use this PHP script as ``JIRA labels url`` or enter the labels you want as comma separated texts
in the field of JIRA labels.
Finally click the ``Test connection`` button to test if you are able to connect to JIRA web server and that
your configurations are right.
Synchronization
---------------
From the project window ``General data`` you are able to start synchronizing order elements with JIRA issues.
Click the button ``Sync with JIRA`` to start the synchronization.
* If it is for the first time a ``pop-up`` window(with auto completed list of labels) will be shown.
In this window you can select a ``label`` to sync with and click the button ``Start sync`` to start the
synchronization process, or click the ``Cancel`` button to cancel it.
* If label is already synchronized, the ``last synchronized date`` and the ``label`` are displayed in the JIRA screen.
In this case no ``pop-up`` window to select label will be shown. Instead synchronization process will be started directly
for that displayed(already synchronized) label.
.. NOTE::
The relation between ``Order`` and ``label`` is one-to-one. Only one ``label`` is allowed to sync with one ``Order``
.. NOTE::
On the successful (re)synchronization, the information would be written to the database and the JIRA screen would
be updated with the last synchronized -``date`` and -``label``.
(Re)synchronization process is performed in two phases:
* phase-1: Synchronizing order elements including progress assignment and measurements.
* phase-2: Synchronizing time sheets.
.. NOTE::
if phase-1 fails, phase-2 will not be performed and no information will be written to the database.
.. NOTE::
The success or failure information would be displayed in pop-up window.
On successful completing of synchronization, the result would be displayed in ``Work Breakdown Structure(WBS tasks)`` tab of the
``Project details`` screen. In this UI there are two changes from the standard ``WBS``:
* The ``Total task hours`` column is unmodifiable (read-only) as the synchronization is one way. Task hours can be only updated in
in JIRA web server
* The ``Code`` column shows the ``JIRA issue keys`` and as the same time they are ``Hyperlinks`` to the JIRA issues. Click the
desired key if you want to go to the document of that key(JIRA issue)
Scheduling
----------
Re-synchronization of JIRA issues can also take place through the scheduler. Go to ``Job scheduling`` screen.
In that screen you can configure a JIRA ``job`` to do synchronization. The ``job`` searches for last synchronized
``labels`` in the database and re-synchronize them accordingly. see also the scheduler Manual.
Tim Enterprise connector
========================
Tim Enterprise is a Dutch product from Aenova. It is a web based application for the administration
of time spent on projects and tasks.
Tim connector is an application that can be used to communicate with Tim Enterprise server to:
* export all hours spent by worker(user) on a project that could be registered in Tim Enterprise.
* import all rosters of the worker(user) in order to plan the resource effectively.
The *Tim connector* should be configured properly before being used.
Configuration
-------------
From the configuration's ``Main Setting`` screen choose the tab ``Connectors``.
In the connectors screen select the Tim connector from the ``pull-down`` list. A ``property editor screen``
is displayed now.
In this screen you can configure the following property values:
* ``Activated``: Y/N, whether you want to use the Tim connector or not. Default is ``N``.
* ``Server URL``: the absolute path to the Tim Enterprise server.
* ``user name and password``: the user credentials for authorization
* ``Number of days timesheet to Tim``: how many days back you want to export the times heets
* ``Number of days roster from Tim``: how many days forward you want to import the rosters
* ``Productivity factor``: Effective working hours in percentage. Default is ``100%``
* ``Department IDs to import roster``: comma separated department IDs.
Finally click the ``Test connection`` button to test if you are able to connect to
Tim Enterprise server and that your configurations are right.
Export
------
From the project window ``General data`` you are able to start exporting time sheets to Tim Enterprise server.
Enter the ``Tim product code`` and click the button ``Exprot to Tim`` to start the Export.
The Tim connector adds the following fields along with the product code:
* The Worker/user full name
* The Date worked on a task by worker
* The Effort, hours worked on task
* and an option whether Tim Enterprise should update the registration or inserts a new one
The Tim Enterprise *response* contains only a list of ``record-IDs(integers)``. This is the difficult part to see what is
go wrong as the response list contains only numbers not related to the request fields.
The *Export* request(registration in Tim) assumed to be succeeded if all the list entries doesn't contain ``0`` values. Otherwise
the *Export* request is failed for those entries which contains ``0`` values. So, you can't see here which
request is failed as the list entries contains only the value ``0``. The only way to figure out this is to look at the log file
in Tim Enterprise server.
.. NOTE::
On the successful exporting, the information would be written to the database and the Tim screen would be updated
with last exported -``date`` -``product code``.
.. NOTE::
The success or failure information would be displayed in pop-up window.
Scheduling export
------------------
Export process can also take place through the scheduler. Go to ``Job scheduling`` screen.
In that screen you can configure a Tim Export ``job``. The ``job`` searches for last exported
time sheets in the database and re-export them accordingly. see also the Scheduler manual.
Import
------
Importing of rosters works only with the help of the *Scheduler*. There is no user-interface designed for as
no input is needed from the user.
Go to ``Job scheduling`` screen and configure Tim Import ``job``. The ``job`` loops through all departments
configured in *connectors property* and import all rosters for each department. See also the scheduler Manual.
For import, the Tim connector adds the following fields in the *request*:
* Period: The period(date from - date to) you want import the roster. This can be provided as a filter criteria
* Department: For which department you want to import the roster. Departments are configurable.
* The fields you are interested in(like Person info, RosterCategory etc) that the Tim server should include in its response.
The import *response* contains the following fields, which is enough to manage the ``exception days`` in Libreplan:
* Person info: name and network name
* Department: The department the worker working in
* Roster category: Information on the presence/absence(Aanwzig/afwezig) of the worker and the reason(Libreplan exception type)
in case that the worker is absent
* Date: The Date worker is present/absent
* Time: The Start time of present/absent, for example 08:00
* duration: Number of hours that the worker is present/absent
By converting the import *response* to Libreplan's ``Exception day`` the following translations takes into account:
* If the roster category contains the name ``Vakantie`` it would be translated to ``RESOURCE HOLIDAY``
* The Roster category, ``Feestdag`` would be translated to ``BANK HOLIDAY``
* All the rest like ``Jus uren``, ``PLB uren`` etc should be added to the ``Calendar Exception Days`` manually
Moreover the import *response*, the roster is divided into two or three parts per day: For example roster-morning,
roster-afternoon and roster-evening. But Libreplan allows only one ``Exception type`` per day. The Tim connector is then
responsible for merging these parts as one ``exception type``. That is, the roster category with the highest ``duration`` is
assumed to be a valid ``Exception type`` but the total duration is the sum of all durations of these category parts.
Contrary to the Libreplan, in Tim Enterprise, the ``total duration`` in case that the worker is on holiday means the worker is
not available for that ``total duration``. But in Libreplan if the worker is on holiday the total duration should be ``Zero``.
The Tim connector also takes care of this translation.