Webservices memo

‣

Table of contents

1. Preamble

Ce document présente l’ensemble des APIs (Application Programming Interface) mises à disposition par Project Monitor.

Editorial agreement / Glossary

Term	Description
PM	Project Monitor
API	Application Programming Interface
REST	Representation State Transfer
HTTP	HyperText Transfer Protocol

Architecture principle

These APIs are based on :

the principle of REST (Representational State Transfer) architecture,
HTTP (hyper text transfer protocol),
JSON (JavaScript Object Notation) data format.

Test tools

To test APIs interactively, we recommend using one of the following plug-ins:

Postman recommandé par Virage Group: https://www.postman.com/downloads/
Firefox REST Client: https: //addons.mozilla.org/fr/firefox/addon/restclient/
Chrome Advanced REST Client: https: //chrome.google.com/webstore/detail/advanced-rest-client/

🚨

Please note that when xls files are returned, the "restclient" plug-in tries to display the downloaded files directly, rather than offering to open them with the dedicated application.

To obtain the correct date format, you can use one of the following converters:

http://www.ruddwire.com/handy-code/date-to-millisecond-calculators/
www.timestamp.fr translates dates into seconds and vice versa

2. General information

Syntax

Principle

In accordance with the HTTP protocol, each API is an HTTP request composed of the following elements:

a URL, e.g. https://monprojectmonitor/MonitorMakerWeb/api/projects
un verbe HTTP, ex : POST
des informations dans le header HTTP, ex : X-PM-LOGIN : monLogin

The request can be completed with elements in JSON (JavaScript Object Notation) format, http://www.json.org/ex : {"libelle":"monProjet","code":"mon_projet"...} By default, the API returns data in JSON format.

Some calls may return ms-excel or csv files.

🚩

N.B.: JSON dates are indicated with timestamps. That is, in number of seconds since January 1, 1970. Ex: August 22, 2012 is represented by 1345586400000

Legible date format

Dates can be supplied in a readable format: YYYY-MM-DDT00:00:00 (RFC-1123, ISO-8601 : http://wiki.fasterxml.com/JacksonFAQDateHandling)

Example: "dateDebut": "2016-12-31T00:00:00" is accepted but "attributs": { "ATT_IMPLEMENTATION_END_DATE": "2018-12-31T00:00:00"} is not.

Query parameters

Query parameters can be passed using a variety of syntaxes.

🚨

Please follow this documentation carefully, as notations are not interchangeable unless otherwise indicated.

The first two syntaxes are based on the URL standard: http: //fr.wikipedia.org/wiki/Uniform_Resource_Locator#URL_absolue

Parameter integrated into the "path". Example: /projects/2012/germany The order is important, since the API implicitly expects this parameter in this place. Parameters are not named.
HTTP parameters. Example: /projects?country=Germany&year=2012Parameters are named (key = value). They are separated from the "path" by ? and separated by &. The order of the parameters is not important.
"Matrix parameter Example: /projects/;year=2012;country=germanyParameters are named (key = value). They are not separated from the "path" and are prefixed by ;. The order of the parameters is not important. This notation is not linked to the URL standard.

Finally, these different syntaxes are not incompatible within the same query. It is possible to have parameters in one syntax and others in another. On the other hand, a parameter is expected by the API in a particular syntax.

If the following query is possible : /projects/closed;year=2012?country=Germany&login=mdupont

The following query is not its equivalent: /projects/2012;country=Germany?status=closed&login=mdupont

URLS root

All Webservices are available from the following URL: https://{UrlProjectMonitor}/MonitorMakerWeb/api where UrlProjectMonitor est le nom DNS de l’installation de Project Monitor Example: https://projectmonitor/MonitorMakerWeb/api

Authentication

JWT token

🚨

Important! The JWT token authentication mode is deployed on all Saas infrastructure and is strongly recommended for OnPremise installations.

Acquisition

Unlike the api key, the JWT token is generated directly by an acquisition web service (api/auth/jwt/token). This web service takes as parameters the login and password with which you wish to authenticate.

Example with cURL

curl --location '' --header 'X-PM-LOGIN: monlogin' --header 'X-PM-PASSWORD: monmotdepasse'

API Key deactivation

Properties can be used to disable api key operation, so token mode is the only authorized mode. If the property is not defined, then either api key or token will be used, and the 2 modes can coexist. Unlike the api key, the token has an expiry date, so it's possible to change the token's default lifetime (24h).

API Key (Depreciated)

Each call to a webservice must be accompanied by an apikey. An apikey is a large string of meaningless characters that authenticates the calling service. The apikey can be generated in the platform's administration screen or specified in the parameters file. <XXX>.monitormaker.properties via the com.vc.mm.webservice.apikey

Example:

#/ com.vc.mm.webservice.apikey (replaces com.vc.mm.commande.exec.auth)
#/ authentication string (api key) for executing web services
# since 5.4.1
#/ required: no
#/ default: nothing (execution impossible)
com.vc.mm.webservice.apikey= BkBUlBLMl4y66kW10M1aRdrGiGn1yO3S

Or via the administration screen :

The administration screen lets you define several apikey, name them and, above all, restrict their use to a given IP address. In the example above, the apikey can only be used for requests originating from the IP address 192.168.0.80. The apikey must then be sent for each web service call by one of the following means, in order of verification:

In the specific HTTP header via the key : X-PM-API-KEY
In the 'BASIC' HTTP Authorization header: the apikey replaces the login and the password field can be filled with any value.
In the query parameters with the parameter: apikey

Example: https: //projectmonitor/MonitorMakerWeb/api/templates?apikey=BkBUlBLMl4y66kW10M1aRdrGiGn1yO3S

The latter method is insecure (the apikey appears in the URL in clear text, and can therefore typically appear in log files that are themselves insecure).

It should only be used in an internal context (behind a DMZ, for example).

Headers

HTTP request header

In addition to the authentication elements described above, we need to add the following header:

Accept: application/json

HTTP header for responses

Web services systematically return json encoded in UTF-8 :

Content-Type: application/json;charset=UTF-8

Cross domain access

Il est possible d’accéder aux webservices de Project Monitor à partir de page HTML + javascript d’un autre domaine que celui de Project Monitor. Pour cela, il existe deux techniques.

JSON-P

Project Monitor implémente la technique json-p (http://en.wikipedia.org/wiki/JSONP) et propose un paramètre global pour chaque webservice : jsoncallback.

This parameter must be supplied as a query parameter. Example:

<!—requête envoyée par une balise ‘script’ -->
<script src="<http://projectmonitor/MonitorMakerWeb/api/templates?login=jdupont&jsoncallback=myCallBack>"></script>
<!— résultat du web service reçues en paramètre de la fonction callback. -->
<script>function myCallBack(data) {console.log(data.value);}</script>

🚩

Nota Bene: The very principle of JSON-P does not allow information to be supplied to the web service via the http header.

Cross-Origin Resource Sharing

Cross-Origin Resource Sharing (ou CORS, http://en.wikipedia.org/wiki/Cross-origin_resource_sharing) est un mécanisme standard permettant le partage d’information entre sites web. Project Monitor prend en charge ce mécanisme côté serveur. Ce mécanisme dépend du navigateur exécutant la page html appelante : http://en.wikipedia.org/wiki/Cross-origin_resource_sharing#Browser_support

Errors

Errors are reported via status HTTP

Code	Description
400	Wrong request. The parameters supplied are not correct. In this case, the body of the response contains functional code as well as message in plain text, all sent in JSON format. Warning: there may be 400 errors without message functionality. The most common example is a call without passing the expected parameters. Ces messages ne sont pas générés directement par Project Monitor mais par le serveur Wildfly. Le contenu est en général du `Content-Type: text/html`. Example: Request to create a project without passing the json parameter as input
401	Current user identification problem
403	Forbidden - The current user does not have the right to use this API. Example: "Project creation" rights are required to POST the URL https://projectmonitor/MonitorMakerWeb/api/projects/
415	It is certainly missing `Content-Type: application/json` in the header.
500	Internal server error

3. API (HTTP verb: GET)

/templates: project templates

Description	List of project templates
Webservice code	/templates
Management rules	Right ACT_UTILISER_GABARIT Using templates in projects
Example	https://projectmonitor/MonitorMakerWeb/api/templates
Bean Sortie	Bean IdLibelle
Body Sortie	{ "id": 255527, "libelle": "le libellé de mon objet", "description": "une description plus longue souvent facultative", "designation": "éventuellement un libellé alternatif" }
Results	JSON

/currentuser : project filters

Description	List of project filters accessible to the current user
Webservice code	/currentuser/filters
Management rules	Right ACT_UTILISER_FILTRES_PUB_PROJET Using public project filters in the filter selector
Example	https://projectmonitor/MonitorMakerWeb/api/currentuser/filters
Bean Sortie	Bean IdLibelle
Body Sortie	{ "id": 255527, "libelle": "le libellé de mon objet", "description": "une description plus longue souvent facultative", "designation": "éventuellement un libellé alternatif" }
Results	JSON

/currentuser : authorization rights

Description	List of user rights codes. All rights on all hierarchies are considered. In other words, you only need to have the right once somewhere.
Webservice code	/currentuser/permissions
Management rules
Example	https://projectmonitor/MonitorMakerWeb/api/currentuser/permissions
Bean Sortie	Channel
Body Sortie	[ string1, string2.... ]
Results	JSON

Description	Returns true/false if the right is authorized or not. All rights on all hierarchies are considered. In other words, you only need to have the right once somewhere.
Webservice code	/currentuser/permissions/{permissionsCode}
Management rules
Example	https://projectmonitor/MonitorMakerWeb/api/currentuse/permissions/{permissionsCode}
Bean Sortie	True/False
Body Sortie	True/False
Results	JSON

Description	Retourne « TRUE » ou « FALSE » si l’utilisateur dispose ou non d’un droit. L’ « actionCode » correspond au code du droit (ex : ACT_MODIFIER_PROJET). L’« id » correspond à l’id de l’objet (du projet, d’un utilisateur) (ex : 553615)
Webservice code	/currentuser/rights/{actionCode}?objectid={id}
Management rules
Example	https://projectmonitor/MonitorMakerWeb/api/currentuser/rights/ACT_MODIFIER_PROJET?objectId=553615
Bean Sortie	True/False
Body Sortie	True/False
Results	JSON

/roles

Description	List project roles
Webservice code	/roles
Management rules	Right ACT_CONSULTER_ROLE Consult platform administration roles
Example	https://projectmonitor/MonitorMakerWeb/api/roles
Bean Sortie	Bean RoleValue
Body Sortie	[{ "id": 123, "libelle": "Chef de projet", "description": "Responsable de projet", "key": "246703” }, ...]
Results	JSON

/roles/hierarchical: user roles on all projects

Description	Lists the " structure profile roles" codes and the users making up these roles for all projects. If no code " role de profil de structure " is entered for role, it will not be included in the response.
Webservice code	/roles/hierarchical
Management rules
Example	https://projectmonitor/MonitorMakerWeb/api/roles/hierarchical
Bean Sortie	Channel
Body Sortie	{ "ID_PROJET_1": { "CODE_ROLE_1": [userId_1,userId2], "CODE_ROLE_2": [userId_3,userId4], }, "ID_PROJET_2": { "CODE_ROLE_1": [userId_1,userId2], "CODE_ROLE_2": [userId_3,userId4], }, }
Results	JSON

/users

Description	Lists user information
Webservice code	/users/{userId}
Management rules
Example	https://projectmonitor/MonitorMakerWeb/api/users/266414
Bean Sortie	Bean User file
Body Sortie	{ "id": "12345", "libelle":"test web service 1","description": "", "index": 188534, "login": "adm","nom": "adm", "prenom": "adm","telephoneBureau": "", "mail": "adm@adm.fr","nomP": "adm a.", "actif": true,"formatCalendrier": "fr_FR", "ressourceSuivie": false,"niveauLicence": null, "idSMM": 1225, "idUP": 155245,"motDePasse": "", "sexe": null,"langue": { "id": 1, "libelle": "Français","description": "","code": "fr", "key": "1" }, "titre": "", "societe": "","telephoneAssistance": "", "telephoneStandard": "","telephoneMobile": "", "adresse1": "", "codePostal1": "","ville1": "", "adresse2": "", "codePostal2": "", "ville2": "","region": "", "parametres": { "pageAccueil":{ "id": -1, "libelle": "", "description": "", "key": "-1" },"filtreProjetParDefaut": { "id": -1, "libelle": "", "description": "", "key": "-1" },"filtreRessourceParDefaut": { "id": -1, "libelle": "","description": "", "key": "-1" } },"dateOuverture": 1516662000000, "dateFermeture": null,"dateFermetureOrigine": null, "alertModifParMail": false,"synchroDatesUP": false, "forceLienRessourceParLibelle": false,"image": null, "abonnements": null, "identifiantLDAP": "","ressource": { "id": -1, "libelle": "", "description": "", "key": "-1" }, "dateDerniereModificationMdp": null,"dateCreation": 1516715245593, "invite": false,"cache": false, "roles":[..]"arbreProfilsHierarchies": null,"abonnementsCharges": false, "profilsProjets": null,"motDePasseGereParMM": true, "userLDAP": false,"ligneRoles": "1 - Administrateur<br/>","libelleLong": "adm adm", "codeObjetType": "UTILISATEUR", "key": "315563" }
Results	JSON

/users: user details

Description	Returns a paginated list of active users, ordered by first and last name. The result can be filtered using query parameters: ➢ `contains` filter users by value. This value is searched for in the user's "login", "last name" and "first name". If the value is found, the user is displayed, otherwise not. ➢ `globalRole` Possible values: true or false If `true` this indicates that we are looking for a user with a role on the "General roles" perimeter. If `false` this perimeter is not taken into account ➢ `hierarchicalRole` Possible values: true or false If `true` this indicates that we are looking for a user with a role on the " role de structure " perimeter. If `false` this perimeter is not taken into account ➢ `projectRole` Possible values: true or false If `true` this indicates that we are looking for a user with a role on the "Project roles" perimeter. If `false` this perimeter is not taken into account ➢ `roleCodes` Role filtering: allows users to be filtered by role (role code) and scope ("General roles", "Project roles" and " structure roles"). If no perimeter is activated, then the role filter does not apply. Example: `/users?projectRole=true&roleCodes=ROL_RESPONSABLE_PROJECT&roleCodes=ROL_TEAM_MEMBER` In this example, we display users with a "global" role and who have the role "manager project" OR team member status on at least one project. It is also possible to set the pagination: ➢ `page` specifies the desired page number (starts at 1) default=1 ➢ `perPage` number of items per page (must be less than 200) default=25 The WS returns the list of items corresponding to the requested page. The header `X-PM-TOTAL-COUNT` contains the total number of items (excluding pagination).
Webservice code	/users
Management rules
Example	https://projectmonitor/MonitorMakerWeb/api/users
Bean Sortie	Bean IdLibelle
Body Sortie	{ "id": 255527, "libelle": "le libellé de mon objet", "description": "une description plus longue souvent facultative", "designation": "éventuellement un libellé alternatif" }
Results	JSON

/lists

Description	List of possible values for the givenattribute of the given object type.
Webservice code	/lists/{objectTypeCode}/{attributeCode}
Management rules
Example	https://projectmonitor/MonitorMakerWeb/api/lists/projet/status_PROJET https://projectmonitor/MonitorMakerWeb/api/lists/tache/Categorie
Bean Sortie	Bean ListValue
Body Sortie	{ "id": 82418, "libelle": "le libellé de ma valeur de liste", "description": "une description plus longue souvent facultative", "couleur": "#FF0000", "defaut": false, "beanIcone": { "id": 287447, "libelle": "Brouillon.jpg", "nomFichier": "Brouillon.jpg", "urlFichier": "http://projectmonitor/MonitorMakerWeb /doc/1225/2204/2012/4/26/287447/term ine16.jpg"}, "ponderation": 0, "code": "STATUT_BROUILLON", "ordre": 0, "designation": "Brouillon" }
Results	JSON

/projects

Description	Project information by ID Returns the information for the given project. But without the following information: attachments, team, attributes, etc.
Webservice code	/projects/{projectId}
Management rules
Example	https://projectmonitor/MonitorMakerWeb/api/projects/3025
Bean Sortie	Bean WSProjet
Body Sortie	{ "id": "12345", "libelle":"test web service 1", "description":"", "code":"test-ws1", "libelleLong":"test web service", "statut": { "id": 246721, "libelle": "En cours", "description": "", "code": "CODE_STATUT" } "idGabarit": -1, "codeGabarit": "CODE_GABARIT" "dateDebut":1072911600000, "dateFin":1167519600000, "loginChefDeProjet": "ngavard", "rattachements": {"CODE_HIERARCHIE1": ["CODE_VN1"], "CODE_HIERARCHIE2": ["CODE_VN2", CODE_VN3]}, "equipe": {"CODE_ROLE1": ["login1", " login2"], "CODE_ROLE2": ["login3"]}, "attributs": {"CODE_ATTRIBUT1_CHAINE": "ma valeur" , " CODE_ATTRIBUT2_VALEUR_NUM": 55.5, "CODE_ATTRIBUT3_VALEUR_LISTE":"CODE_VALEUR_LISTE"} }
Results	JSON

/projects attributes : value of a project attribute

Description	Returns the value to date of theattribute of "codeAttributes" on the project identified by "projectId".
Webservice code	/projects/{projectId}/attributes/{codeAttributes}
Management rules
Example	https://projectmonitor/MonitorMakerWeb/api/projects/327905/attributes/DESCRIPTION_PROJET
Bean Sortie	Channel
Body Sortie	{ codeAttribut1:valeurAttribut1 }
Results	JSON

/projects forms: attribute values for a project form

Description	Returns all values to date of the form codeForm attributes on the project identified by "projectId".
Webservice code	/projects/{projectId}/forms/{codeForm}
Management rules
Example	https://projectmonitor/MonitorMakerWeb/api/projects/327905/forms/TEST
Bean Sortie	Channel
Body Sortie	{ codeAttribut1:valeurAttribut1, codeAttribut2:valeurAttribut2, ...}
Results	JSON

/projects: list of projects

Description	Returns a list of projects filtered by the supplied filter "filterId" corresponds to a persistent project filter.
Webservice code	/projects;filterId={filterId}
Management rules	Right ACT_CONSULTER_PROJECT_AFFECTE Consultation of a project to which the user is assigned
Example	https://projectmonitor/MonitorMakerWeb/api/projects;filterId=426 https://projectmonitor/MonitorMakerWeb/api/projects
Bean Sortie	Bean IDLibelle
Body Sortie	[{ "id": 255527, "libelle": "le libellé de mon objet", "description": "une description plus longue souvent facultative", "designation": "éventuellement un libellé alternatif" }, { "id": 255523, "libelle": "le libellé de mon objet 3", "description": "une description plus longue souvent facultative", "designation": "éventuellement un libellé alternatif" }]
Results	JSON

/projects: identification of the "model" project

Description	Returns the id of the "template" project used to duplicate the "projectId" project.
Webservice code	/projects/{projectId}/copiedfrom
Management rules
Example	https://projectmonitor/MonitorMakerWeb/api/projects/156381/copiedfrom
Bean Sortie	Channel
Body Sortie	{ "id": 156381, //id du projet « modèle » "libelle": "", "description": "", "key": "156381" }
Results	JSON

/projects: retrieve the value of attachments to hierarchies

Description	Returns all hierarchy information and level values to which the project is attached.
Webservice code	/projects/{projectId}/hierarchies
Management rules
Example	https://projectmonitor/MonitorMakerWeb/api/projects/{projectId}/hierarchies
Bean Sortie	Channel
Body Sortie	{ "codeOuLibelléHiérarchie 1" : BeanValeurNiveau }
Results	JSON

/projects: retrieve the value of attachments to a structure

Description	Returns all information about a defined structure (hierarchyCode) and the level values to which the project is linked.
Webservice code	/projects/{projectId}/hierarchies/{hierarchyCode}
Management rules
Example	https://projectmonitor/MonitorMakerWeb/api/projects/331356/hierarchies/HIER_ORGA_MOE
Bean Sortie	BeanValueLevel
Body Sortie	[{ "id": 123, "libelle": "valeurRattachée", "description": "", "code": "", "hierarchiePrincipale": { "id": 456, "libelle": "hiérarchie" }, "niveau": { "id": 789, "libelle": "Niveau 2", "code": "", "dateModification": 1302881673810, "codeObjetType": "NIVEAU" } }, ...]
Results	JSON

/hierarchies: project links

Description	Returns the list of hierarchical level values to which the project (code {projectid}) is attached and corresponding to the code {hierarchyCode}.
Webservice code	/hierarchies/project/{projectId};hierarchyCode={hierarchyCode}
Management rules
Example	https://projectmonitor/MonitorMakerWeb/api/hierarchies;projectId=426;hierarchyCode=HIER_MODE
Bean Sortie	Bean IDLibelle
Body Sortie	{ "id": 255527, "libelle": "le libellé de mon objet", "description": "une description plus longue souvent facultative", "designation": "éventuellement un libellé alternatif" }
Results	JSON

/hierarchies values: retrieve the levels and level values of a structure

Description	Returns the levels and level values of a structure (codeHierarchy) without taking the project into account
Webservice code	/hierarchies/values/{Hierarchiecode}
Management rules
Example	https://projectmonitor/MonitorMakerWeb/api/hierarchies/values/HIER_ORGA_MOE
Bean Sortie	Channel
Body Sortie	{ libelle : "...", code : "...", niveaux : [ niveau 1 : { libelle : "...", code : "...", valeursNiveaux : [ ... idNiveaupere : ... , .... ] }, niveau 2 : { libelle : "...", code : "...", valeursNiveaux : [ ... idNiveaupere : ... , .... ] } ] }
Results	JSON

/team

Description	Lists the people making up a project team
Webservice code	/projects/{projectId}/team
Management rules	Right ACT_CONSULTER_PROJECT_AFFECTE Consultation of a project to which the user is assigned
Example	https://projectmonitor/MonitorMakerWeb/api/projects/3025/team
Bean Sortie	Bean WSProjet
Body Sortie	{ "id": "12345", "libelle":"test web service 1", "description":"", "code":"test-ws1", "libelleLong":"test web service", "statut": { "id": 246721, "libelle": "En cours", "description": "", "code": "CODE_STATUT", "equipe": {"CODE_ROLE1": ["login1", " login2"] } }
Results	JSON

/reports

Description	Runs the selected report with the corresponding view . Applies the indicated project filter and the period given for reports using a period parameter. The period is defined relative to the current month: if the "from" parameter is specified but without "to", this indicates the number of months to be taken in the past relative to the current date. Ex: from=5 indicates to take 5 months back Similarly, if the "to" parameter is specified but without "from", this indicates the number of months in the future. Ex: to=3 indicates 3 months in the future. Finally, if neither the "from" nor the "to" parameters are specified, this indicates project periods. Possible formats are: csv, excel, csvemail and excelemail. If you use the "csv" or "csvemail" format, please update the "HTTP REQUEST HEADER" header with : - Accept : text/csv;application/json If you use the "excel" or "excelemail" format, please update the "HTTP REQUEST HEADER" header with : - Accept : application/vnd.ms-excel;application/json Calling the web service is subject to having one of two rights: ACT_CONSULTER_STATUS_MULTIPROJECT or ACT_CONSULTER_STATUS_MEASURES. The reports currently authorized are : - EXPORT_RESSOURCE_PROJET: Export of project resource data (except planned) - EXPORT_PHASE: Export of project phases. - EXPORT_TASK: Export project tasks. - EXPORT_JALON: Export project milestones. - EXPORT_RESSOURCE: Export of resource data (label, profile, capacity, code...). This export is not subject to project filters, views or period selection. Indicating them in the query will have no impact. - EXPORT_ECHANGE: Export of project exchanges - EXPORT_INDICATOR_UP: Export of platform indicators - EXPORT_INDICATOR: Export of indicators - EXPORT_PROJET: Export projects - EXPORT_BUDGET: Export project budget data
Webservice code	/reports/{format}/{report}/{viewCode};filterCode={filterCode};from={from};to={to}
Management rules
Example	https://projectmonitor/MonitorMakerWeb/api/reports/excel/EXPORT_RESSOURCE/VUE_SIMPLE;filterCode=2014rd;from=6;to=0
Bean Sortie	Excel or CSV file in the requested format
Results	Excel or CSV file in the requested format

/phases

Description	Returns the list of phases associated with the project.
Webservice code	/phases?projectId={projectId}
Management rules	Right ACT_CONSULTER_OBJET_PLANNING Consultation of a schedule object
Example	https://projectmonitor/MonitorMakerWeb/api/phases?projectId=426
Bean Sortie	Bean WSPhase
Body Sortie	{ "id": 520454, "libelle": "Expression des Besoins","description": "", "code": "", "type": {beanValeurListe},"etat": {beanValeurListe}, "message": "","parent": { "id": 520455, "libelle": "Lot 1", "description": "","key": "520455" }, "loginResponsable": "jdupont", "debutEstime": 1521216000000,"finEstime": 1530975600000,"debutCible": 1521216000000,"finCible": 1530975600000,"projet":{"id": 520451} }
Results	JSON

/phases: data recovery

Description	Returns the properties of a phase without dependencies.
Webservice code	/phases/{phaseID}
Management rules	Right ACT_CONSULTER_OBJET_PLANNING Consultation of a schedule object
Example	https://projectmonitor/MonitorMakerWeb/api/phases/331359
Bean Sortie	Bean WSPhase
Body Sortie	{ "id": 520454, "libelle": "Expression des Besoins","description": "", "code": "", "type": {beanIdOuCode},"etat": {beanIdLibelle}, "dateDebut": null,"message": "", "parent": { "id": 520455, "libelle": "Lot 1","description": "", "key": "520455" },"loginResponsable": "jdupont", "codeStatut": "A_VALIDER","debutEstime": 1521216000000, "finEstime": 1530975600000,"debutCible": 1521216000000, "finCible": 1530975600000 }
Results	JSON

/phases: dependency recovery

Description	Returns properties on the dependencies of a phase
Webservice code	/phases/{phaseID}/dependencies
Management rules	Right ACT_CONSULTER_OBJET_PLANNING Consultation of a schedule object
Example	https://projectmonitor/MonitorMakerWeb/api/phases/331359/dependencies
Bean Sortie	Bean WS Dependency
Body Sortie	[{ "predecesseur":{ "id": 520453, "libelle": "Conduite du projet","description": null, "key": "520453" },"projetPredecesseur": { "id": 520452,"libelle": "DP - AREA PRE SORT", "description": "","key": "520452" },"type": "REL_TYPE_FINISH_TO_START", "valeur": 0 }, ...]
Results	JSON

/phases attributes : value of a attribute type phase

Description	Returns the value to date of theattribute of "codeAttributes" on the phase identified by "phasesId".
Webservice code	/phases/{phasesId}/attributes/{codeAttributes}
Management rules
Example	https://projectmonitor/MonitorMakerWeb/api/phases/331359/DESCRIPTION_PHASE
Bean Sortie	Channel
Body Sortie
Results	JSON

/admin

Description	Renvoie des informations sur la version de Project Monitor et des scripts exécutés sur la base de données.
Webservice code	Right ACT_AFFICHER_ETAT_ADMIN Display administration reports
Management rules	https://projectmonitor/MonitorMakerWeb/api/admin/about
Example	/admin/about
Bean Sortie	Channel
Body Sortie	{ "version": "v5.4.0.3", "database": { "productName": "SQL server", "base": "projmon", "userName": "projmon"}, "scripts":[ { "datePassage":1317765600000, "RCSfile" : "G_libelles_v_5_4_0_1.sql" "revision" : " 1.1" "commentaire" : ""} ... ] }
Results	JSON

Description	Synchronous execution of the batch command supplied as a parameter
Webservice code	/admin/exec/{commandName}
Management rules	Law ACT_CONFIG_TECHNIQUE Configure the application's technical parameters
Example	https://projectmonitor/MonitorMakerWeb/api/admin/admin/exec/IndexerProjetCommand
Bean Entrée
Body Input
Bean Sortie	Channel
Body Sortie	200 OK
Results	JSON

4. API (HTTP verbs: POST/DELETE)

/projects: creation or modification

Description	Creating or modifying one or more projects To modify a project, pass its id to the input BeanWsProject. The web service accepts as input a simple BeanWsProjet or an array of BeanWsProjets (creation/modification). Notes : - The "id" field only needs to be filled in when updating a project. When a project is created, an id is automatically generated. - For attributes of the "List value" type, it is the code of the list value that must be sent, not its label. - The "idStatus" and "idGabarit" properties have priority over "codeStatus" and "codeGabarit". You can set either one or the other, but if both are present, only the id will be taken into account. - MOD_INDICATOR" is a fixed value that does not apply to modules other than indicator. Multiple categories can be entered by separating blocks with commas. - Accepted representation codes are : REP_REALISE and REP_PLANIFIE_REPARTI
Webservice code	/projects
Management rules	Droits ACT_CONSULTER_PROJET_AFFECTE Consultation of a project to which the user is assigned ACT_CREER_PROJET Project creation ACT_MODIFY_PROJECT Project modification
Example	https://projectmonitor/MonitorMakerWeb/api/projects
Bean Entrée	WsProjet bean or array of WsProjet beans
Body Input	{ "id": "12345", "libelle":"test web service 1", "description":"", "code":"test-ws1", "libelleLong":"test web service", "statut": { "id": 246721, "libelle": "En cours", "description": "", "code": "CODE_STATUT" } "idGabarit": -1, "codeGabarit": "CODE_GABARIT" "dateDebut":1072911600000, "dateFin":1167519600000, "loginChefDeProjet": "ngavard", "rattachements": {"CODE_HIERARCHIE1": ["CODE_VN1"], "CODE_HIERARCHIE2": ["CODE_VN2", CODE_VN3]}, "equipe": {"CODE_ROLE1": ["login1", " login2"], "CODE_ROLE2": ["login3"]}, "attributs": {"CODE_ATTRIBUT1_CHAINE": "ma valeur" , " CODE_ATTRIBUT2_VALEUR_NUM": 55.5, " CODE_ATTRIBUT3_VALEUR_LISTE":"CODE_VALEUR_LISTE"} }
Bean Sortie	Bean WSRetour
Body Sortie	{ "beanWsErreur" : { "code" : "LBL_RATTACHEMENTS_PROJET_HIERARCHIES_INCOMPLETE", "message" : "Toutes les hiérarchies ne sont pas affectées" }, "beanWsItem" : { "id" : 12345, "code" : "test-ws1", "libelle" : "test web service 1" } }
Results	JSON

/projects: list of projects

Description	Advanced project search based on filter and json parameter criteria. "filterId" corresponds to a persistent project filter. NB: For the "codeVue" field, only " dashboard (piloting)" views will work.
Webservice code	/projects/query
Management rules	Right ACT_CONSULTER_PROJECT_AFFECTE Consultation of a project to which the user is assigned
Example	https://projectmonitor/MonitorMakerWeb/api/projects;filterId=426/query https://projectmonitor/MonitorMakerWeb/api/projects/query
Bean Entrée	BeanFilterProjectParam
Body Input	{ "loginUser":"loginUser", "codeRoles":["CODE_ROLE1", "CODE_ROLE2",...], "codeAttributListe":"CODE_ATTRIBUT_LISTE", "idValeurAttributListe":128824, "jalonEnRetard": "false", "idProjets": [244071, 290590, ...], "codeVue": "CODE_VUE", "idProjetPere" : 200115 }
Bean Sortie	BeanWSCockpit
Body Sortie	{ "projet": {}, "valeurCockpits": { "CODE_COCKPIT1": {"feux": {"code": "VERT"}, "iconeName": "BallGreen.png"}, "CODE_COCKPIT2": {"feux": {"code": "GRIS"}, "iconeName": "BallGrey.png"}, ... } }
Results	JSON

/phases: creation or modification

Description	Creation or modification of one or more phase and milestone If the phase or milestone sent contains an id or code that already exists, we modify the existing object. Otherwise we create a new object, using the information received.
Webservice code	/phases
Management rules
Example	https://projectmonitor/MonitorMakerWeb/api/phases
Bean Entrée	beanWsPhaseEntrée
Body Input	dans le cas d’une PHASE : { "id": 520454, "libelle": "Expression des Besoins", //obligatoire en création, facultatif en modification "gabarit": {beanIdOuCode}, "projet" : {beanIdOuCode},//obligatoire en création, facultatif en modification "idPhaseParente" : "", //si non précisé en création alors la tache devient une tache parente. En modification l’id de la phase parente doit correspondre à une phase du projet indiqué par le paramètre "projet" "etat": {beanIdOuCode}, //si non précisé en création alors état par défaut "type": {beanIdOuCode}, //si non précisé en création alors type par défaut "code" : "", "debutEstime": 1521216000000, "finEstime": 1530975600000, "debutCible": 1521216000000, "finCible": 1530975600000, "attributs": {"CODE_ATTRIBUT1_CHAINE": "ma valeur", "CODE_ATTRIBUT2_VALEUR_NUM": 55.5, "CODE_ATTRIBUT3_VALEUR_LISTE":"CODE_VALEUR_LISTE"} } Ou dans le cas d’un JALON : { "projet": {"id": 457219}, "libelle": "nouveau", "type": {"code":"GENRE_PLANNING_NOUVEAU"}, "jalon": true, "finCible" : "2022-01-13" } En modification : { "projet": {"id": 457219}, "code": "jalonwkf", "fait": true }
Bean Sortie	BeanWSBack
Body Sortie
Results	JSON

/tasks

Description	Advanced search of task based on json parameter criteria. "filterId" corresponds to a persistent project filter.
Webservice code	/tasks;filterId={filterId}/query
Management rules
Example	https://projectmonitor/MonitorMakerWeb/api/tasks/query https://projectmonitor/MonitorMakerWeb/api/tasks;filterId=426/query
Bean Entrée	BeanWsFiltreTacheParam
Body Input	{ "loginEmetteur": "loginUser1", "loginAssigne": "loginUser2", "dateFinSuperieureA":1072911600000, "dateFinInferieureA":1072911600000, "dateEcheanceSuperieureA":1072911600000, "dateEcheanceInferieureA":1072911600000, "listeIdsStatut": [123, 466], "listeIdsCategorie": [987, ...] "beanFiltreProjetParam": { "idProjets": [244071, 290590, ...] "loginUser":"loginUser", "codeRoles":["CODE_ROLE1", "CODE_ROLE2"] } }
Bean Sortie	BeanWsTacheOut
Body Sortie	{ "id": 22709, "libelle": "libellé de la tâche", "code": "22709", "dateModification": 1338274295973, "projet": {beanObjet}, "message": "Contenu HTML <b> de la tâche</b>", "saisissable": true, "loginEmetteur": "loginUser1", "loginAssigne": " loginUser2", "dateDebut": null, "dateDebutPrevue": null, "dateFin": null, "dateEcheance": null, "etat": {beanIdLibelle}, "type": {beanIdLibelle}, "urlTache": "http://projectmonitor/MonitorMakerWeb/connexion.jsf?NumEcran=351&IdSMM=12 25&IdUP=2204&IdObjet=22709", "urlProjet": "http:// projectmonitor/MonitorMakerWeb/connexion.jsf?NumEcran=351&IdSMM=1225&IdUP= 2204&IdObjet=290354" }
Results	JSON

Description	Creating or modifying a task or a set of tasks If the task sent contains an id or code that already exists: the existing task is modified. Otherwise, a new task is created using the information received. Mandatory fields for creation are : - label: subject of the task - project: identified by its id or code The mandatory fields for modification are: - id or code (of the task)
Webservice code	/tasks;
Verb	POST
Management rules
Example	https://projectmonitor/MonitorMakerWeb/api/tasks
Bean Entrée	Bean WsTacheEntréeOu array[BeanWsTacheEntrée1, BeanWsTacheEntrée2,BeanWsTacheEntrée3
Body Entrée (si création)	{ "libelle": "Mettre à jour l’univers BO pour CASSIOPEE", "projet": { "id": 573456 }, "message": "Demande du service BCU. Merci de mettre à jour l’univers BO pour <b>cassiopée</b>. <br/> Avertir le service Facturation quand la demande sera realisée.", "loginEmetteur": "blopez", "etat": { "code": "ETAT_A_DEBUTER" }, "categorie": { "code": "CAT_BI" }, "gabarit": { "code": "GAB_TACHE_DSI" }, "priorite": { beanIdOuCode }, "phase": { "code": "CODE_PHASE"}, "loginAssigne": "Severin.prin", "loginsParticipants": ["pierre.visualiseur","julie.cheffep"], "roleAssigne": "ROL_CP_MOE”, "roleParticipants" : "ROL_MEMBRE_EQUIPE”, "envoyerMail" : true, (mail à tous assigné, chef de projet et participants), "envoyerMailChefDeProjet" : true (mail au chef de projet), "envoyerMailAssigne" : true, (mail à assigné) "envoyerMailParticipants" : true (mail à participants) }
Body Entrée (si modification)	{ "id": 12345, "loginAssigne": "jmchevillot", "statut": { "code": "ETAT_A_FACTURER" }, "attributs": { "NUM_BON_FACTU": "2017_BCU_12345", "NB_HEURES_PASSEES": 10.5 }, "phase": { "code": "CODE_PHASE"}, "loginsParticipants": ["pierre.visualiseur","julie.cheffep"], "roleParticipants" : "ROL_MEMBRE_EQUIPE” }
Bean Sortie	BeanWSBack
Body Sortie	Renvoyé par Project Monitor : tableau de BeanWsRetour. Un BeanWsRetour est composé d’un BeanWsErreur portant le code et le message de l’erreur (champs vides si pas d’erreur), et un BeanWsItem portant les informations du projet concerné. { "beanWsErreur" : { "code" : "LBL_RATTACHEMENTS_PROJET_HIERARCHIES_INCOMPLETE", "message" : "Toutes les hiérarchies ne sont pas affectées" }, "beanWsItem" : { "id" : 12345, "code" : "test-ws1", "libelle" : "test web service 1" } }
Results	JSON

/documents

A document can be associated with an object or a attribute object (in the case of creation AND deletion). If the call concerns a attribute, theattribute code must be supplied.
If a document is attached to an object, a default structure link type is used. The default type is "Attachment" in most cases, and "Deliverable" for phases and milestones.
On ne peut ajouter/supprimer un document sur un objet que si celui-ci est rattaché à un projet ou est lui-même un projet. Par conséquent, ces webservices ne fonctionnent pas avec des gabarits.

Description	Creation of a document. - `Id` document identifier, used only for deletion. - `idObject / codeObject` : identifier and code of the object to which the document is attached. There's no need to fill in both fields at the same time; one or the other will suffice. By default, idObject will be taken into account if both are indicated. - `codeAttribute`attribute code if the document is to be attached to a attribute object (project/task). If not supplied, the document will be attached directly to the object. - `url` url of document. Currently only "URL" documents are accepted. - `version` document version. - idStatut/codeStatut: status (status) of document. As with the attached object, there's no need to specify both.
Webservice code	/documents
Management rules	Creation is subject to ACT_MODIFIER_* and ACT_MODIFIER_MES_* rights (depending on the type of object attached, e.g. "ACT_MODIFIER_TACHE"). To create document, you must have the right to modify the object attached to document . In the case of a document attribute , you must also have the "ACT_UTILISER_ATTRIBUT" right.
Example	https://projectmonitor/MonitorMakerWeb/api/documents
Bean Entrée	beanWsDocument
Body Input	Pour créer un document, il faut au minimum les paramètres suivants dans le beanWsProjet en entrée : • idObjet OU codeObjet • url • [codeAttribut] (si le document est rattaché à un attribut) Les autres propriétés du BeanWsDocument sont optionnelles. Ex de BeanWsDocument en entrée : { « IdObjet » : 12345,“Url” : “https://upload.wikimedia.org/wikipedia/commons/2C_Scotland.jpg” } { "id":333417, "idObjet":45338, "codeObjet":"THE_CODE", "codeAttribut":"DOC_CONTRAT", "url":"http://exemple.icone.fr", "version":"VERSION 1.2", "idStatut":3432, "codeStatut":"EST_ACTIF" }
Bean Sortie	Channel
Body Sortie	New user ID document
Results

Description	Récupérations d’informations de document
Webservice code	/documents/idDocument
Management rules
Example
Bean Entrée	IDDocument
Body Input
Bean Sortie
Body Sortie	- ID + Chemin physique du document + Taille + Extension + Etat document (ID + Code + Libellé statut) + Version document - ID + Code + Libellé du projet sur lequel se trouve le document - ID + Code + Libellé du conteneur + Type du conteneur (attribut, tâche, échange, phase, jalon, pièce financière)
Results	JSON

Description	Removal of document
Webservice code	/documents
Management rules	Deletion is subject to ACT_MODIFY_* and ACT_MODIFY_MES_* rights (depending on the type of object attached, e.g. "ACT_MODIFY_TACHE"). To delete document, you must have the right to modify the object attached to document . In the case of a document attribute , you must also have the "ACT_UTILISER_ATTRIBUT" right.
Example	https://projectmonitor/MonitorMakerWeb/api/documents
Bean Entrée	beanWsDocument
Body Input	Pour supprimer un document, il faut au minimum les paramètres suivants dans le beanWsProjet en entrée : • id • [codeAttribut] (si le document est rattaché à un attribut) OU • idObjet OU codeObjet • url • [codeAttribut] (si le document est rattaché à un attribut) Ex de BeanWsDocument en entrée : { « id » : 12346, « codeAttribut » : « ICONE_TACHE » } { "id":333417, "idObjet":45338, "codeObjet":"THE_CODE", "codeAttribut":"DOC_CONTRAT", "url":"http://exemple.icone.fr", "version":"VERSION 1.2", "idStatut":3432, "codeStatut":"EST_ACTIF" }
Bean Sortie	Channel
Body Sortie	true if successful, otherwise an error is returned
Results	JSON

/echange : creation or modification

Description	Creation or modification of one or moreexchange If theexchange sent contains an id or code that already exists: we modify the existingexchange . Otherwise we create a new exchange with the information received.
Webservice code	/exchanges
Management rules
Example	https://projectmonitor/MonitorMakerWeb/api/exchanges
Bean Entrée	BeanWsExchangeInputOor array[BeanWsExchangeInput1,BeanWsExchangeInput2,BeanWsExchangeInput3]
Body Input	Les champs obligatoires en création sont : - libellé : sujet de l’échange - projet : identifié par son id ou son code Le champ obligatoire en modification est : - id (de l’échange) { "libelle": "libellé de l’échange", //obligatoire en création, facultatif en modification "id": 22709, //uniquement en modification "projet": {beanIdOuCode}, //obligatoire en création, facultatif en modification "message": "Contenu HTML <b> de la tâche</b>", "loginEmetteur": "loginUser1", //facultatif en création, ignoré en modification "loginAssigne": "loginUser2", "type": { beanIdOuCode }, //si non précisé en création alors type par défut "gabarit": { beanIdOuCode }, "echangePrecedent": { beanIdOuCode }, "gabarit": { beanIdOuCode }, "dateEdition": 1338274295973, "dateDeclare": 1338274295973, "envoiParMailAlAssigne":{"true" or "false"}, //obligatoire si le champ LoginAssigne est renseigné "attributs": {"CODE_ATTRIBUT1_CHAINE": "ma valeur", "CODE_ATTRIBUT2_VALEUR_NUM": 55.5, "CODE_ATTRIBUT3_VALEUR_LISTE":"CODE_VALEUR_LISTE"} }
Bean Sortie	BeanWSBack
Body Sortie
Results	JSON

5. cURL import method

Presentation

These Webservices can be used to send import or synchronization files. Their syntax is specific and not based on what has been seen previously. The cURL tool is supplied in p-monitor's "install" directory. It calls p-monitor via HTTP and transmits a CSV file to be imported. If the platform is to import data via its HTTP interface, a platform-specific user must exist and have the right rights to execute the import.

Import identifier

Identifier	PM rights	Note
TEST	#NA	This special import is used to test the technical chain. It simply mails the file sent by cURL back to the authenticated user.
IMPORT_PROJET	#NA	Import via Excel import files (see Import memo for expected file syntax).
IMPORT_INVOICE	ACT_EXECUTE_SYNCHROFACTURE Synchronize invoices
IMPORT_DEVIS	ACT_EXECUTE_SYNCHRODEVIS Synchronize quotes
IMPORT_TACHE	ACT_CREER_TACHE Add a task	Import via Excel import files (see Import memo for expected file syntax).
ACTIVITY_ENTRY	ACT_EXECUTE_SYNCHROACTIVITY Synchronize timesheet
ENTRY_ACTIVITY_RAF	ACT_EXECUTE_SYNCHROACTIVITY Synchronize timesheet
ACTIVITY_ENTRY_RAF_DETAIL	ACT_EXECUTE_SYNCHROACTIVITY Synchronize timesheet
MEASURES_UP	#NA
SYNCHROPROJET	ACT_EXECUTE_SYNCHROPROJECT Synchronize projects
SYNCHROENVELOPPE	#NA
SYNCHROFINANCIERE (2)	#NA	This import represents the generic import of financial documents: you must specify the financial document type code as a query parameter.
SYNCHROAFFECTATION	#NA
SYNCHROENGAGEMENT	#NA
SYNCHROMANDATTING	#NA
SYNCHROBUDGET	#NA
ENTRY_PROVISIONAL_REPARTITIONED_BUDGET_1	#NA	Import of forecast total distributed 1
ENTRY_PROVISIONAL_REPARTIED_BUDGET_2	#NA	Import of forecast total distributed 2
ENTRY_PROVISIONAL_REPARED_BUDGET_3	#NA	Import of forecast total distributed 3

New cURL launch method

To launch a cURL import, use the following syntax in a batch : curl -H "Accept:application/json" -H "Authorization: montoken" -silent -F

`Accept :application/json`	header d’entête pour se connecter à Project Monitor
`LOGINUSERPM`	Login de l’utilisateur spécifique de Project Monitor
`APIKEYSERVEUR`	(si authentification par apikey uniquement) : api key du serveur ou de l’up, configurée dans l’administration Project Monitor ou dans le FICHIER de configuration (*.properties)
`fileSend.txt`	name of the file to be sent to p-monitor. This must be in the current directory
`url.de.projectmonitor`	L’URL de l’instance de Project Monitor qui doit recevoir le fichier.
`IMPORT_ID`	import type identifier. See list above.

🚩

Please refer to http://curl.haxx.se/ for more information on how to use the cURL tool.

To wait for the end of the command to continue processing in your batch file once the import is complete, use the wait option:

curl -H "Accept:application/json" -H "Authorization: montoken" -silent -F wait=true -F attachment=@fichierAEnvoyer.txt
"http://url.de.projectmonitor/MonitorMakerWeb/api/import/IDENTIFIANT_IMPORT?login=LOGINUSERPM"

To find out whether a cURL import is in progress, use the isrunning option:

curl -H "Accept:application/json" -H "Authorization: montoken" -silent -F isrunning=true -F attachment=@fichierAEnvoyer.txt
"http://url.de.projectmonitor/MonitorMakerWeb/api/import/IDENTIFIANT_IMPORT?login=LOGINUSERPM"

🚨

Warning: if isrunning is passed as a parameter with a value other than "true", the webservice will return a 400 error code.

To specify the type of financial document when importing SYNCHROFINANCIERE, use the mandatory importType option:

curl -H "Accept:application/json" -H "Authorization: montoken" -silent -F attachment=@fichierAEnvoyer.txt
"http://url.de.projectmonitor/MonitorMakerWeb/api/import/SYNCHROFINANCIERE/importType/TYPE_PIECE_FINANC_REALISE?login=LOGINUSERPM"

🚨

Please note: to correctly interpret the "&" character used to specify the two options in the URL, you must enclose the URL in quotation marks. Otherwise, the request will be launched with the first parameter only.

🚨

Please note that an incompatibility has been detected when calling this web service via PowerShell. If this command interface is used, then the Curl process should be called directly and not via the "Invoke-WebRequest" keyword, as in the example below:

$headersToken = New- Object "System.Collections.Generic.Dictionary[[String],[String]]"
$headersToken.Add('X-PM-LOGIN',$login)
$headersToken.Add('X-PM-PASSWORD',$password)
echo "Tentative d'authentification pour l'utilisateur $login et son mot de passe est $password"
try{$response = Invoke-WebRequest -Headers $headersToken - URI "" | ConvertFrom-Json} 
catch [System.Net.WebException] {echo "Impossible d'obtenir le token (verifiez votre login/mot de passe)"
return} echo "Appel du web service d'export projet"
$token = $response.token
curl.exe -X POST -k -H Authorization:$token -H Accept:application/json -F attachment=@ImportPF.csv 
"https://pmdemo.p-monitor.com/MonitorMakerWeb/api/import/SYNCHROFINANCIERE/importType/TYPE_PIECE_FINANC_REALISE/"

The user specified by the login parameter receives an e-mail summarizing the import process.

The http return codes visible to curl are :

200	OK
204	no import in progress (isrunning)
302	an import is in progress (isrunning)
400	functional error: refer to the e-mail sent OR if isrunning option requested, parameter other than "true".
401	user specified by "login" parameter does not exist or password is incorrect
403	the user specified by the "login" parameter does not have sufficient rights to launch the import.
405	the application server rejects the HTTP method used in the request sent
500	a technical error has occurred. Contact your administrator
503	command interrupted by a user