.. include:: ImageReplacement.txt

.. title:: Administration

.. index:: Administration console

.. _admin-console:

######################
Administration Console
######################

.. figure:: /images/GUI/ADMIN_SCR_Console.png
   :alt: Administration screen
   :align: center
   
   Administration screen

.. note::

  The screens described below are restricted to users with administrator profile.
   
  Users with other profiles can not access it, whether display or access rights are granted or not.   

Administration console allows to execute administration tasks on application.

.. index:: Background tasks

.. _background-task:

Background tasks
################


the CRON
********

The :term:`CRON` program starts and stops background jobs that process and periodically check indicators to generate the corresponding alerts, warnings or even automatic imports if necessary.

This program automatically runs scripts, commands, or software at a specified date and time, or a pre-defined cycle.

.. figure:: /images/GUI/ADMIN_ZONE_BackgroundTask.png
   :alt: Background tasks in Admin
   
   Background tasks is running in Administration console
   
You can activate or deactivate CRON directly from the info bar. 


.. figure:: /images/GUI/ADMIN_ZONE_ButtonCRON.png
   :alt: CRON Button
   
   CRON activation button

.. seealso:: 

   :ref:`The CRON button<cron-button>`




.. index:: Internal alert, Background tasks

Send an internal alert
######################

Allows to send an internal alert to users.

.. figure:: /images/GUI/ADMIN_ZONE_SendAlertIntern.png
   :alt: Internal Alert
   
   Internal Alert
   
   
Internal alerts can be sent to users. 

You can define a date and time for sending, specific adressees or all users, the type of message that users will receive: information, an alert or a warning...

This can be a good step to warn users before a temporary shutdown of ProjeQtOr for update for example.    

An internal alert can be sent by the administrator or by monitoring indicators.

.. rubric:: By the administrator

The administrator can send internal alert by administration console.
    
The message will be received by user via message pop-up.
    
    

.. rubric:: Monitoring indicators   

Monitoring indicators send only warning and alert message.
    
The message contains information that explains the alert:

* Item id and type.  
* Indicator description. 
* Target value.
* Alert or warning value.


.. seealso:: 

   The indicators are defined in :ref:`Indicators screen<indicator>` .    

   

.. index:: Connection Management

.. _manage_connection:

Manage connections
##################


.. figure:: /images/GUI/ADMIN_ZONE_ManageConnection.png
   :alt: Manage connections
   
   Manage connections

Allows to force disconnection of active users and close the application for new connections.

.. rubric:: Disconnect all users

* The button :kbd:`Disconnect all users` allows to disconnect all connected users except your own connection.
* The application status is displayed below.
* Disconnection will be effective for each user when his browser will ckeck for alerts to be displayed.
* The delay for the effective disconnection of users will depend on the parameter “delay (in second) to check alerts” in :ref:`Global parameters<automated-service>` screen.

.. rubric:: Open/Close application

* The button :kbd:`Open/Close application`
* Allows to open and close application.
* When the application is closed the message below will appear on login screen.

.. index:: Consistency check

Consistency check
#################


.. figure:: /images/GUI/ADMIN_ConstencyCheck.png
   :alt: constancy check
   :align: center
   
   consistency check
   
   
* on the WBS sequence search for duplicates, sequence holes, incorrect order
* on the presence of one and only one line of "PlanningElement" for the planifiable elements
* on the consolidation of ticket work
* on consolidation of work on activities
* on assignments

You can program the search for the consistency check as well as its execution.

Set the desired frequency settings and activate the service.


.. index:: Maintenance of Data (Email)
.. index:: Maintenance of Data (Internal alert)
.. index:: Maintenance of Data (Connection)

Maintenance of Data
###################
 
The administrator has the possibility to:


.. figure:: /images/GUI/ADMIN_ZONE_DataMaintenance.png
   :alt: Maintenance of datas
   
   Maintenance of datas
   
* Close and delete sent emails and alerts. 
* Delete history of connections. 
* Updating references for any kind of element.
   
You can automate these cleanings by activating them using the corresponding buttons.

.. index:: Log file Maintenance   

Log files maintenance
#####################

.. figure:: /images/GUI/ADMIN_Zone_LogFiles.png
   :alt: Log files maintenance
   :align: center
   
   Log files maintenance

The administrator has the possibility to choose the level of the log files among debug, trace, script and errors.

* delete files on a given number of days.
* Show the list of logs
* Show the last logs list.
  
  
.. figure:: /images/GUI/ADMIN_BOX_LogfilesList.png 
   :alt: Log files maintenance
   :align: center
   
   Log files list
  
 
 
 
 

Ordering projects by priority
#############################

.. figure:: /images/GUI/OrderingProjectPrio.png
   :alt: Log files maintenance
   :align: center
   
   Ordering project by priority

You can list projects in priority order rather than WBS order across a set of reports using this administration feature.

This reordering can only be performed within the same project level.

Reports that can benefit from priority ordering include: 

   * Workload plans (weekly, monthly), 
   * Planning reports (monthly and annual, project resources and project resources), 
   * Monthly planning colored by resource (fixed or not).
  
  
  
  

.. index:: API

.. _API:


##########
API REST 2
##########
ProjeQtOr provides an API to interact with its elements. It is provided as a REST web service.

The GET, PUT, POST and DELETE methods are used for elements.

For security reasons, the API is not enabled by default.

Generate a .htpasswd file to see related topics on the net. A template is provided in /api/.htpasswd, referencing the user projeqtor and password projeqtor.

It is provided for testing purposes only. Do not use it in a production environment as it will expose all your data.

Update the .htaccess file to specify the location of your .htpasswd file:

**AuthUserFile "/pathToFile/.htpasswd"** The default location is the Apache directory.

How the API works
#################

The user used, the one defined in. htpassword, must exist as a user in the database. The access rights: read, create, update, delete, must be defined for this user. This allows you to provide some access to external users and control the visibility they get on your data.

**METHODS**

* GET : read
* PUT : create and update
* POST : create, update
* DELETE : delete

.. important:: 

   For PUT, PUSH and DELETE methods, the data must be encrypted with the AES-256 algorithm, with the key as the API key defined for the user.

   The administrator must provide this API key to the API consumer. You can use the AESCRT library provided in the /external directory for encryption.

PUT and PUSH methods are similar and can both be used to create or update items. 

The only difference is in the way of sending data: as a Post table for POST, as a file for PUT.

The DELETE method requires data, formatted as for a PUT, but only the ID is required.

For PUT, POST and DELETE, you can provide:

* A single element: {"id": "1",…}
* A list of elements: {"identified": "id", "elements": [{"id": "1",…}, {"id": "2",…}]}
* The Json format retrieved from GET can be used for PUT, POST and DELETE.



Queries in Json
###############

Some examples of queries in Json format.


.. rubric:: GET


* **URL: http://myserver/api/{objectclass}/{objectid}** - *(EX: http://myserver/api/Project/1)*
   
   Full description of the object of the given class with the given ID




* **URL: http://myserver/api/{objectclass}/all** - *(EX: http://myserver/api/Project/all)*
   
   Full description of all objects of the given class




* **URL: http://myserver/api/{objectclass}/filter/{filterid}** - *(EX: http://myserver/api/Project/filter/1)*
   
   Full description of all objects of the given class matching the given stored filter. Filter id can be retrieved when saving the filter. Using a filter of a different class may lead to unexpected results




* **URL: http://myserver/api/{objectclass}/search/{crit1}/{critN}** - *(EX: http://myserver/api/Activity/search/idProject=1/name like '%error%')*
   
   Full description of all objects of the given class matching the given criteria. You can provide as many criteria as you want, they will be included in the where clause with the AND operator. Unlike the example, the criteria must be "url encoded" use the PHP function urlencode() for example




* **URL: http://myserver/api/{objetcclass}/updated/{start date}/{end date}** - *(EX: http://myserver/api/Project/updated/20231101000000/20231231235959)*
   
   Full description of all objects updated between start date and end date. Date format is YYYYMMDDHHMMSS. Date> = "date stard" and date < "end date"

   
   
.. rubric:: POST

* **URL: http://myserver/api/{objectclass}**

   *EX: Data provided in json format as a POST value*
          
   Full description of updated or created objects with 2 additional fields: apiResult: update status and apiResultMessage




.. rubric:: PUT

* **URL: http://myserver/api/{objectclass}**

   *EX: Data provided in json format as a file*
          
   Full description of updated or created objects with 2 additional fields: apiResult: update status and apiResultMessage

.. rubric:: DELETE

* **URL: http://myserver/api/{objectclass}**  

   *EX: Data provided in json format as a file*
   
   Full description of updated or created objects with 2 additional fields: apiResult: update status and apiResultMessage

       
-----
       
       
Here is an example of PHP code calling the API for PUT and POST request (create, update). 

.. note::

   Note that by default ProjeQtOr API uses 128 bits encryption key, that is why in exemples function AesCtr::encrypt uses 128 as last parameter.
  
   It you want to change it, you can force API to use a different encryption key length, just add in parameters.php 
  
   $aesKeyLength=256; // Possible values are 128, 192, 256 

   (256 bits encrypton may be illegal in some countries)


This request lists all Tickets:

.. parsed-literal::

   $fullUrl="http://myserver/api/Ticket/list/all"; 
   $curl = curl_init($fullUrl);
   curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
   curl_setopt($curl, CURLOPT_USERPWD, "projeqtor:projeqtor");
   curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
   curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);
   $curl_response = curl_exec($curl);
   echo $curl_response;
   curl_close($curl);

With DELETE that allows to delete ticket with ID #1 : 

.. parsed-literal::

   $fullUrl="http://myserver/api/Ticket";
   $data='{"id":"1"}';
   $data=AesCtr::encrypt($data, 'ApiKeyForUserProjeqtor', 128);
   $curl = curl_init($fullUrl);
   curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
   curl_setopt($curl, CURLOPT_USERPWD, "projeqtor:projeqtor");
   curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
   curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);
   curl_setopt($curl, CURLOPT_CUSTOMREQUEST, "DELETE");
   curl_setopt($curl, CURLOPT_POST, true);
   curl_setopt($curl, CURLOPT_POSTFIELDS, $data);
   $curl_response = curl_exec($curl);
   echo $curl_response;
   curl_close($curl);

Put PUT and POST (creation or update) th8at allows to update n=ame of ticket with ID #1 : 
   
.. parsed-literal::

   $fullUrl="http://myserver/api/Ticket";
   $data='{"id":"1", "name":"name to be changed for Ticket 1"}';
   $data=AesCtr::encrypt($data, 'ApiKeyForUserProjeqtor', 128);
   $curl = curl_init($fullUrl);
   curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
   curl_setopt($curl, CURLOPT_USERPWD, "projeqtor:projeqtor");
   curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
   curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);
   curl_setopt($curl, CURLOPT_CUSTOMREQUEST, "PUT");
   curl_setopt($curl, CURLOPT_POST, true);
   curl_setopt($curl, CURLOPT_POSTFIELDS, $data);
   $curl_response = curl_exec($curl);
   echo $curl_response;
   curl_close($curl);

.. parsed-literal::

   $fullUrl="http://myserver/api/Ticket";
   $data='{"id":"1", "name":"name to be changed for Ticket 1"}';
   $data=AesCtr::encrypt($data, 'ApiKeyForUserProjeqtor', 256);
   $curl = curl_init($fullUrl);
   curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
   curl_setopt($curl, CURLOPT_USERPWD, "projeqtor:projeqtor");
   curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
   curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);
   curl_setopt($curl, CURLOPT_CUSTOMREQUEST, "POST");
   curl_setopt($curl, CURLOPT_POST, true);
   curl_setopt($curl, CURLOPT_POSTFIELDS, $data);
   $curl_response = curl_exec($curl);
   echo $curl_response;
   curl_close($curl);
