Mémo Webservices

‣

Table des matières

1. Préambule

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

Convention de rédaction / Glossaire

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

Principe d’architecture

Ces APIs sont basées sur :

le principe d’architecture REST (Representational State Transfer),
le protocole HTTP (hyper text transfer protocol),
le format de données JSON (JavaScript Object Notation).

Outils de test

Pour tester les API de manière interactive, il est recommandé d’utiliser l’un des plug-ins suivants :

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/

🚨

Attention, concernant les fichiers xls renvoyés, le plug-in « restclient » essaye d’afficher directement les fichiers téléchargés plutôt que de proposer de les ouvrir avec l’application dédiée.

Pour obtenir le bon format de date, il est possible d’utiliser un des convertisseurs suivants :

http://www.ruddwire.com/handy-code/date-to-millisecond-calculators/
www.timestamp.fr qui permet de traduire une date en seconde ou inversement

2. Informations générales

Syntaxe

Principe

Conformément au protocole HTTP, chaque API est une requête HTTP composée des éléments suivants :

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

La requête peut être complétée d’élément au format JSON (JavaScript Object Notation), http://www.json.org/, ex : {"libelle":"monProjet","code":"mon_projet"...} L’API retourne par défaut des données au format JSON.

Certains appels peuvent retourner des fichiers de type ms-excel ou csv.

🚩

N.B. : Les dates JSON sont indiquées avec des timestamps. C'est à dire en nombre de seconde depuis le 1er janvier 1970. Ex : le 22 août 2012 est représenté par 1345586400000

Format de date lisible

Les dates peuvent être fournies avec un format lisible : AAAA-MM-JJT00:00:00 (RFC-1123, ISO-8601 : http://wiki.fasterxml.com/JacksonFAQDateHandling)

Exemple : "dateDebut": "2016-12-31T00:00:00" est accepté mais "attributs": { "ATT_IMPLEMENTATION_END_DATE": "2018-12-31T00:00:00"} ne l’est pas.

Paramètres des requêtes

Les paramètres des requêtes peuvent être passés selon plusieurs syntaxes.

🚨

Attention à bien suivre cette documentation car les notations ne sont pas interchangeables sauf indications contraires.

Les deux premières syntaxes s’appuient sur le standard des URLs : http://fr.wikipedia.org/wiki/Uniform_Resource_Locator#URL_absolue

Paramètre intégré dans le « chemin ». Exemple : /projects/2012/germany L’ordre est important puisque l’API attend, implicitement, tel paramètre à telle place. Les paramètres ne sont pas nommés.
Paramètres HTTP. Exemple : /projects?country=Germany&year=2012Les paramètres sont nommés (clé = valeur). Ils sont séparés du “chemin” par ? et séparé entre eux par &. L’ordre des paramètres n’est pas important.
“Matrix parameter”. Exemple : /projects/;year=2012;country=germanyLes paramètres sont nommés (clé = valeur). Ils ne sont pas séparés du “chemin” et sont préfixés par ;. L’ordre des paramètres n’est pas important. Cette notation n’est pas liée au standard URL.

Enfin, ces différentes syntaxes ne sont pas incompatibles dans une même requête. Il est possible d’avoir des paramètres dans une syntaxe et d’autres dans une autre. Par contre, un paramètre est bien attendu dans une syntaxe particulière par l’API.

Si la requête suivante est possible : /projects/closed;year=2012?country=Germany&login=mdupont

La requête ci-après n’est pas son équivalent : /projects/2012;country=Germany?status=closed&login=mdupont

Racine des URLS

Les Webservices sont disponibles à partir des URL suivantes :

https://{UrlProjectMonitor}/MonitorMakerWeb/api où UrlProjectMonitor est le nom DNS de l’installation de Project Monitor Exemple : https://projectmonitor/MonitorMakerWeb/api

https://{UrlProjectMonitor}/monitorupgrade où UrlProjectMonitor est le nom DNS de l’installation de Project Monitor Exemple : https://projectmonitor/monitorupgrade/

Authentification

Jeton JWT

🚨

Important ! Le mode d’authentification par jeton JWT est déployé sur toutes l’infrastructure Saas et fortement recommandée sur les installations OnPremise.

Acquisition

À la différence de l’api key, le jeton JWT se génère directement par un web service d’acquisition (api/auth/jwt/token). Ce web service prend en paramètre le login et le mot de passe avec lequel on souhaite s’authentifier.

Exemple avec cURL

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

Désactivation de l’API Key

Des propriétés permettent de désactiver le fonctionnement par api key, le mode token sera donc le seul autorisé. Si la propriété est non définie, alors on utilisera l’api key ou le token, les 2 modes peuvent cohabiter. Contrairement à l’api key, le token possède une date d’expiration, il est donc possible de changer la durée de vie par defaut du token (24h).

API Key (Déprécié)

Chaque appel aux webservices doit être accompagné d'une apikey. Une apikey est une grande suite de caractères sans signification qui authentifie le service appelant. L'apikey peut être générée dans l'écran d'administration de la plateforme ou bien indiquée dans le fichier de paramétrage <XXX>.monitormaker.properties via la propriété com.vc.mm.webservice.apikey

Exemple :

#/ com.vc.mm.webservice.apikey (remplace com.vc.mm.commande.exec.auth)
#/ chaine d'authentification (api key) pour executer des web services
# depuis 5.4.1
#/ obligatoire : non
#/ defaut : rien (execution impossible)
com.vc.mm.webservice.apikey= BkBUlBLMl4y66kW10M1aRdrGiGn1yO3S

Ou bien via l’écran d’administration :

L’écran d’administration permet de définir plusieurs apikey, de les nommer et surtout d’en restreindre l’usage à une adresse IP donnée. Dans l’exemple ci-dessus, la clé ne pourra être utilisée que dans des requêtes provenant de l’adresse IP 192.168.0.80. L’apikey doit ensuite être envoyée à chaque appel de web service selon un des moyens suivants par ordre de vérification :

Dans le header HTTP spécifique via la clé : X-PM-API-KEY
Dans le header HTTP Authorization de type ‘BASIC’ : l’apikey remplace le login et le champ mot de passe peut être rempli avec n’importe quelle valeur.
Dans les paramètres (query parameter) de la requête avec le paramètre : apikey

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

Cette dernière méthode est non sécurisée (l’apikey apparait en clair dans l’URL et donc peut apparaître typiquement dans des fichiers de logs eux-mêmes non sécurisés).

Elle ne devrait être utilisée que dans un contexte interne (derrière une DMZ par exemple).

Headers

Header Http des requêtes

En plus des éléments d’authentification vus ci-avant, il est nécessaire de rajouter l’header suivant :

Accept: application/json

Header Http des réponses

Les web services renvoient systématiquement du json encodé en UTF-8 :

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

Accès cross domain

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.

Ce paramètre doit être fourni sous forme de paramètre de requête (query parameter). Exemple :

<!—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 : Le principe même de JSON-P ne permet pas de fournir des informations via le header http au web service.

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

Erreurs

Les erreurs sont remontées via un statut HTTP

Code	Description
400	Mauvaise requête. Les paramètres fournis ne sont pas correctes. Dans ce cas le corps de la réponse contient un code fonctionnel ainsi qu’un message en clair, le tout envoyé au format JSON. Attention, il peut y avoir des erreurs 400 sans message fonctionnel. L’exemple le plus courant étant un appel sans passer les paramètres attendus. 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`. Exemple : Demande de création de projet mais sans passer le paramètre json en entrée
401	Problème d’identification de l’utilisateur courant
403	Interdit - L’utilisateur courant n’a pas les droits d’utiliser cette API. Exemple : Il faut le droit de “Création de projet” pour appeler en POST l’URL https://projectmonitor/MonitorMakerWeb/api/projects/
415	Il manque très certainement `Content-Type: application/json` dans le header.
500	Erreur interne au serveur

3. API (Verbe HTTP : GET)

/templates : gabarits de projet

Description	Liste des gabarits de projet
Code webservice	/templates
Règles de gestion	Droit ACT_UTILISER_GABARIT Utilisation de gabarits dans les projets
Exemple	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" }
Résultat	JSON

/currentuser : filtres projet

Description	Liste des filtres projets accessibles à l’utilisateur courant
Code webservice	/currentuser/filters
Règles de gestion	Droit ACT_UTILISER_FILTRES_PUB_PROJET Utilisation des filtres publics de projet dans le sélecteur de filtre
Exemple	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" }
Résultat	JSON

/currentuser : droits autorisations

Description	Liste des codes des droits de l’utilisateur. On considère tous les droits sur toutes les hiérarchies. Autrement dit, il suffit d'avoir le droit une fois quelque part.
Code webservice	/currentuser/permissions
Règles de gestion
Exemple	https://projectmonitor/MonitorMakerWeb/api/currentuser/permissions
Bean Sortie	Chaine
Body Sortie	[ chaine1, chaine2.... ]
Résultat	JSON

Description	Renvoie true/false si le droit est autorisé ou non On considère tous les droits sur toutes les hiérarchies. Autrement dit, il suffit d'avoir le droit une fois quelque part.
Code webservice	/currentuser/permissions/{permissionsCode}
Règles de gestion
Exemple	https://projectmonitor/MonitorMakerWeb/api/currentuse/permissions/{permissionsCode}
Bean Sortie	True/False
Body Sortie	True/False
Résultat	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)
Code webservice	/currentuser/rights/{actionCode}?objectid={id}
Règles de gestion
Exemple	https://projectmonitor/MonitorMakerWeb/api/currentuser/rights/ACT_MODIFIER_PROJET?objectId=553615
Bean Sortie	True/False
Body Sortie	True/False
Résultat	JSON

/roles

Description	Liste les rôles projets
Code webservice	/roles
Règles de gestion	Droit ACT_CONSULTER_ROLE Consulter des rôles dans l'administration de la plateforme
Exemple	https://projectmonitor/MonitorMakerWeb/api/roles
Bean Sortie	Bean ValeurRole
Body Sortie	[{ "id": 123, "libelle": "Chef de projet", "description": "Responsable de projet", "key": "246703” }, ...]
Résultat	JSON

/roles/hierarchical : rôles des utilisateurs sur tous les projets

Description	Liste les codes « rôles de profil de hiérarchie » et les utilisateurs composant ces rôles de tous les projets. Si aucun code « rôle de profil de hiérarchie » n’est renseigné pour le rôle, il ne sera pas inclus dans la réponse.
Code webservice	/roles/hierarchical
Règles de gestion
Exemple	https://projectmonitor/MonitorMakerWeb/api/roles/hierarchical
Bean Sortie	Chaine
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], }, }
Résultat	JSON

/users

Description	Liste les informations d’un utilisateur
Code webservice	/users/{userId}
Règles de gestion
Exemple	https://projectmonitor/MonitorMakerWeb/api/users/266414
Bean Sortie	Bean Dossier Utilisateur
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" }
Résultat	JSON

/users : détails des utilisateurs

Description	Renvoie une liste paginée des utilisateurs actifs ordonnée par nom puis prénom. Il y a la possibilité de filtrer le résultat via des « query param » : ➢ `contains` : permet de filtrer les utilisateurs en fonction d’une valeur. Cette valeur est recherchée dans le « login »,le « nom » et le « prénom » de l’utilisateur. Si la valeur est retrouvée alors l’utilisateur est affiché, sinon non. ➢ `globalRole` : Valeurs possibles : true ou false Si `true` cela indique que nous recherchons un utilisateur disposant d’un rôle sur le périmètre « Rôles généraux ». Si `false` ce périmètre n’est pas pris en compte ➢ `hierarchicalRole` : Valeurs possibles : true ou false Si `true` cela indique que nous recherchons un utilisateur disposant d’un rôle sur le périmètre « rôle de hiérarchie ». Si `false` ce périmètre n’est pas pris en compte ➢ `projectRole` : Valeurs possibles : true ou false Si `true` cela indique que nous recherchons un utilisateur disposant d’un rôle sur le périmètre « Rôles projets ». Si `false` ce périmètre n’est pas pris en compte ➢ `roleCodes` : permet de filtrer les utilisateurs en fonction de leurs rôles (code du/des rôles) et de leurs périmètres (« Rôles généraux », « Rôles projets » et « Rôles de hiérarchie ») Si aucun périmètre n’est activé alors le filtre sur les rôles ne s’applique pas Exemple : `/users?projectRole=true&roleCodes=ROL_RESPONSABLE_PROJET&roleCodes=ROL_ MEMBRE_EQUIPE` Dans cet exemple nous affichons les utilisateurs disposant d’un rôle « global » et qui ont le rôle "Responsable projet" OU membre d'équipe sur au moins un projet. Il est possible également de paramétrer la pagination : ➢ `page` : précise le numéro de page voulu (commence à 1) défaut=1 ➢ `perPage` : nombre d'item par page (doit être inférieur à 200) défaut=25 Le WS renvoie la liste d'item correspondant à la page demandée. Le header `X-PM-TOTAL-COUNT` contient le nombre total d'items (hors pagination).
Code webservice	/users
Règles de gestion
Exemple	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" }
Résultat	JSON

/lists

Description	Liste des valeurs possibles pour l’attribut donné du type d’objet donné
Code webservice	/lists/{objectTypeCode}/{attributeCode}
Règles de gestion
Exemple	https://projectmonitor/MonitorMakerWeb/api/lists/projet/STATUT_PROJET https://projectmonitor/MonitorMakerWeb/api/lists/tache/Categorie
Bean Sortie	Bean ValeurListe
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" }
Résultat	JSON

/projects

Description	Information d’un projet par son ID Renvoie les informations du projet donné. Mais sans les informations suivantes : rattachements, équipe, attributs
Code webservice	/projects/{projectId}
Règles de gestion
Exemple	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"} }
Résultat	JSON

/projects attributes : valeur d’un attribut du projet

Description	Retourne la valeur à date de l’attribut de « codeAttributes » sur le projet identifié par « projectId »
Code webservice	/projects/{projectId}/attributes/{codeAttributes}
Règles de gestion
Exemple	https://projectmonitor/MonitorMakerWeb/api/projects/327905/attributes/DESCRIPTION_PROJET
Bean Sortie	Chaine
Body Sortie	{ codeAttribut1:valeurAttribut1 }
Résultat	JSON

/projects forms : valeur des attributs d’un formulaire du projet

Description	Retourne toutes les valeurs à date des attributs du formulaire de code « codeForm » sur le projet identifié par « projectId »
Code webservice	/projects/{projectId}/forms/{codeForm}
Règles de gestion
Exemple	https://projectmonitor/MonitorMakerWeb/api/projects/327905/forms/TEST
Bean Sortie	Chaine
Body Sortie	{ codeAttribut1:valeurAttribut1, codeAttribut2:valeurAttribut2, ...}
Résultat	JSON

/projects : liste de projets

Description	Renvoie une liste de projet filtrée par le filtre fourni « filterId» correspond à un filtre projet persistant.
Code webservice	/projects;filterId={filterId}
Règles de gestion	Droit ACT_CONSULTER_PROJET_AFFECTE Consultation d'un projet auquel l'utilisateur est affecté
Exemple	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" }]
Résultat	JSON

/projects : identification du projet “modèle”

Description	Retourne l’id du projet « modèle » qui a servi dupliquer le projet « projectId ».
Code webservice	/projects/{projectId}/copiedfrom
Règles de gestion
Exemple	https://projectmonitor/MonitorMakerWeb/api/projects/156381/copiedfrom
Bean Sortie	Chaine
Body Sortie	{ "id": 156381, //id du projet « modèle » "libelle": "", "description": "", "key": "156381" }
Résultat	JSON

/projects : récupération de la valeur des rattachements aux hiérarchies

Description	Retourne toutes les informations des hiérarchies et des valeurs de niveaux sur lequel est rattaché le projet.
Code webservice	/projects/{projectId}/hierarchies
Règles de gestion
Exemple	https://projectmonitor/MonitorMakerWeb/api/projects/{projectId}/hierarchies
Bean Sortie	Chaine
Body Sortie	{ "codeOuLibelléHiérarchie 1" : BeanValeurNiveau }
Résultat	JSON

/projects : récupération de la valeur des rattachements à une hiérarchie

Description	Retourne toutes les informations d’une hiérarchie défini (hierarchyCode) et des valeurs de niveaux sur lequel est rattaché le projet.
Code webservice	/projects/{projectId}/hierarchies/{hierarchyCode}
Règles de gestion
Exemple	https://projectmonitor/MonitorMakerWeb/api/projects/331356/hierarchies/HIER_ORGA_MOE
Bean Sortie	BeanValeurNiveau
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" } }, ...]
Résultat	JSON

/hierarchies : rattachements du projet

Description	Renvoie la liste des valeurs de niveaux hiérarchiques sur lesquels le projet (code {projectid}) est rattaché et correspondant au code {hierarchyCode}.
Code webservice	/hierarchies/project/{projectId};hierarchyCode={hierarchyCode}
Règles de gestion
Exemple	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" }
Résultat	JSON

/hierarchies values : récupérer les niveaux et les valeurs de niveaux d’une hiérarchie

Description	Retourne les niveaux et les valeurs de niveau d'une hiérarchie (codeHierarchie) sans prendre en compte le projet
Code webservice	/hierarchies/values/{codeHierarchie}
Règles de gestion
Exemple	https://projectmonitor/MonitorMakerWeb/api/hierarchies/values/HIER_ORGA_MOE
Bean Sortie	Chaine
Body Sortie	{ libelle : "...", code : "...", niveaux : [ niveau 1 : { libelle : "...", code : "...", valeursNiveaux : [ ... idNiveaupere : ... , .... ] }, niveau 2 : { libelle : "...", code : "...", valeursNiveaux : [ ... idNiveaupere : ... , .... ] } ] }
Résultat	JSON

/team

Description	Liste les personnes composant l’équipe d’un projet
Code webservice	/projects/{projectId}/team
Règles de gestion	Droit ACT_CONSULTER_PROJET_AFFECTE Consultation d'un projet auquel l'utilisateur est affecté
Exemple	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"] } }
Résultat	JSON

/reports

Description	Exécute le rapport choisi avec la vue correspondante. Applique le filtre projet indiqué ainsi que la période donnée pour les rapports utilisant une période en paramètre. La période est définie en relatif par rapport au mois en cours : Si le paramètre « from » est précisé mais sans « to » cela indique le nombre de mois à prendre dans le passé par rapport à la date courante. Ex : from=5 indique de prendre 5 mois en arrière De même, si le paramètre « to » est précisé mais sans « from » cela indique le nombre de mois dans le futur. Ex : to=3 indique de prendre 3 mois dans le futur. Enfin si ni le paramètre « from » et ni le paramètre « to » ne sont précisés cela indique les périodes des projets. Les formats possibles sont : csv, excel, csvemail et excelemail. Si vous utilisez le format « csv » ou « csvemail », veuillez à mettre à jour le header « HEADER HTTP DES REQUETES » par : • Accept : text/csv;application/json Si vous utilisez le format « excel » ou « excelemail », veuillez mettre à jour le header « HEADER HTTP DES REQUETES » par : • Accept : application/vnd.ms-excel;application/json L’appel au web service est soumis au fait d’avoir un des deux droits : ACT_CONSULTER_ETAT_MULTIPROJET ou ACT_CONSULTER_ETAT_MESURES Les rapports actuellement autorisés sont : • EXPORT_RESSOURCE_PROJET : Export des données ressources du projet (à l’exception du planifié) • EXPORT_PHASE : Export des phases des projets. • EXPORT_TACHE : Export des taches des projets. • EXPORT_JALON : Export des jalons des projets. • EXPORT_RESSOURCE : Export des données ressources (Libellé, profil, capacité, code...). Cet export n’est pas soumis aux filtres projets, aux vues ou à la sélection des périodes. Les indiquer dans la requête n’aura aucun impact. • EXPORT_ECHANGE : Export des échanges des projets • EXPORT_INDICATEUR_UP : Export des indicateurs plateforme • EXPORT_INDICATEUR : Export des indicateurs • EXPORT_PROJET : Export des projets • EXPORT_BUDGET : Export des données budgets des projets
Code webservice	/reports/{format}/{report}/{viewCode};filterCode={filterCode};from={from};to={to}
Règles de gestion
Exemple	https://projectmonitor/MonitorMakerWeb/api/reports/excel/EXPORT_RESSOURCE/VUE_SIMPLE;filterCode=2014rd;from=6;to=0
Bean Sortie	Fichier Excel ou CSV selon le format demandé
Résultat	Fichier Excel ou CSV selon le format demandé

/phases

Description	Renvoie la liste des phases associées au projet.
Code webservice	/phases?projectId={projectId}
Règles de gestion	Droit ACT_CONSULTER_OBJET_PLANNING Consultation d'un objet du planning
Exemple	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} }
Résultat	JSON

/phases : récupération des données

Description	Renvoie les propriétés d’une phase sans les dépendances.
Code webservice	/phases/{phaseID}
Règles de gestion	Droit ACT_CONSULTER_OBJET_PLANNING Consultation d'un objet du planning
Exemple	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 }
Résultat	JSON

/phases : récupération des dépendances

Description	Renvoie les propriétés sur les dépendances d'une phase
Code webservice	/phases/{phaseID}/dependencies
Règles de gestion	Droit ACT_CONSULTER_OBJET_PLANNING Consultation d'un objet du planning
Exemple	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 }, ...]
Résultat	JSON

/phases attributes : valeur d’un attribut de type phase

Description	Retourne la valeur à date de l’attribut de « codeAttributes » sur la phase identifiée par « phasesId »
Code webservice	/phases/{phasesId}/attributes/{codeAttributes}
Règles de gestion
Exemple	https://projectmonitor/MonitorMakerWeb/api/phases/331359/DESCRIPTION_PHASE
Bean Sortie	Chaine
Body Sortie
Résultat	JSON

/admin

Description	Renvoie des informations sur la version de Project Monitor et des scripts exécutés sur la base de données.
Code webservice	Droit ACT_AFFICHER_ETAT_ADMIN Afficher les états d'administration
Règles de gestion	https://projectmonitor/MonitorMakerWeb/api/admin/about
Exemple	/admin/about
Bean Sortie	Chaine
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" : ""} ... ] }
Résultat	JSON

Description	Exécution synchrone de la commande batch fournie en paramètre
Code webservice	/admin/exec/{commandName}
Règles de gestion	Droit ACT_CONFIG_TECHNIQUE Configurer les paramètres techniques de l'application
Exemple	https://projectmonitor/MonitorMakerWeb/api/admin/admin/exec/IndexerProjetCommand
Bean Entrée
Body Entrée
Bean Sortie	Chaine
Body Sortie	200 OK
Résultat	JSON

4. API (Verbes HTTP : POST/DELETE)

/projets : création ou modification

Description	Création ou modification d’un projet ou plusieurs projets Pour modifier un projet, il faut passer son id dans le beanWsProjet en entrée. Le web service accepte en entrée un simple BeanWsProjet ou un tableau de BeanWsProjet (création/modifcation). Notes : • Le champ « id » n’est à renseigner que lors d’une mise à jour. Lors de la création d’un projet, un id sera généré automatiquement. • Pour les attributs de type « Valeur de liste », c’est le code de la valeur de liste qui doit être envoyé et non son libellé. • Les propriétés « idStatut » et « idGabarit » sont prioritaires par rapport à « codeStatut » et « codeGabarit ». On peut mettre l’un ou l’autre mais si les 2 sont présents, seul l’id sera pris en compte. • « MOD_INDICATEUR » est une valeur fixe qui ne s’applique pas pour les modules autres que le module indicateur. On peut mettre plusieurs catégories en séparant les blocs par des virgules. • Les codes représentations acceptés sont : REP_REALISE et REP_PLANIFIE_REPARTI
Code webservice	/projects
Règles de gestion	Droits ACT_CONSULTER_PROJET_AFFECTE Consultation d'un projet auquel l'utilisateur est affecté ACT_CREER_PROJET Création de projet ACT_MODIFIER_PROJET Modification de projet
Exemple	https://projectmonitor/MonitorMakerWeb/api/projects
Bean Entrée	bean WsProjet ou tableau de bean WsProjet
Body Entrée	{ "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" } }
Résultat	JSON

/projects : liste de projets

Description	Recherche avancée de projet en fonction du filtre et de critère en paramètre json. « filterId » correspond à un filtre projet persistant. NB : Pour le champ de « codeVue », seules les vues de type « Tableau de bord (pilotage) » fonctionnent.
Code webservice	/projects/query
Règles de gestion	Droit ACT_CONSULTER_PROJET_AFFECTE Consultation d'un projet auquel l'utilisateur est affecté
Exemple	https://projectmonitor/MonitorMakerWeb/api/projects;filterId=426/query https://projectmonitor/MonitorMakerWeb/api/projects/query
Bean Entrée	BeanFiltreProjetParam
Body Entrée	{ "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"}, ... } }
Résultat	JSON

/phases : création ou modification

Description	Création ou modification d’une ou d’un ensemble de phase et de jalon Si la phase ou le jalon envoyé comporte un id ou un code qui existe déjà : nous faisons la modification de l’objet existant. Sinon nous créons un nouvel objet, avec les informations reçues.
Code webservice	/phases
Règles de gestion
Exemple	https://projectmonitor/MonitorMakerWeb/api/phases
Bean Entrée	beanWsPhaseEntrée
Body Entrée	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	BeanWSRetour
Body Sortie
Résultat	JSON

/tasks

Description	Recherche avancée de tâche en fonction de critère en paramètre json. « filterId » correspond à un filtre projet persistant.
Code webservice	/tasks;filterId={filterId}/query
Règles de gestion
Exemple	https://projectmonitor/MonitorMakerWeb/api/tasks/query https://projectmonitor/MonitorMakerWeb/api/tasks;filterId=426/query
Bean Entrée	BeanWsFiltreTacheParam
Body Entrée	{ "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	BeanWsTacheSortie
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" }
Résultat	JSON

Description	Création ou modification d’une tâche ou d’un ensemble de tâches Si la tâche envoyée comporte un id ou un code qui existe déjà : on fait la modification de la tâche existante. Sinon on créée une nouvelle tâche avec les informations reçues. Les champs obligatoires en création sont : - libellé : sujet de la tâche - projet : identifié par son id ou son code Le champ obligatoire en modification est : - id ou code (de la tâche)
Code webservice	/tasks;
Verbe	POST
Règles de gestion
Exemple	https://projectmonitor/MonitorMakerWeb/api/tasks
Bean Entrée	Bean WsTacheEntréeOu tableau[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	BeanWSRetour
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" } }
Résultat	JSON

/documents

Un document peut être associé à un objet ou à un attribut d’objet (dans le cas de la création ET de la suppression). Si l’appel concerne un attribut, le code de l’attribut doit obligatoirement être fourni.
Si un document est rattaché à un objet, un type de rattachement par défaut est utilisé. « Pièce jointe » dans la plupart des cas et « Livrable » pour les phases et les jalons.
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	Création d’un document. • `Id` : identifiant du document, que l’on indique uniquement pour la suppression. • `idObjet / codeObjet` : identifiant et code de l’objet auquel le document est rattaché, il est inutile de remplir ces deux champs à la fois, l’un ou l’autre suffit. Par défaut idObjet sera pris en compte si les deux sont indiqués. • `codeAttribut`: code de l’attribut si le document doit être attaché à un attribut d’objet (projet/tâche). Si non fourni, le document sera joint directement à l'objet. • `url` : url du document. Actuellement seus les documents de type « URL » sont acceptés • `version` : version du document. • idStatut/codeStatut : statut (état) du document. De même que pour l’objet rattaché, il est inutile d’indiquer les deux.
Code webservice	/documents
Règles de gestion	La création est soumise aux droits ACT_MODIFIER_* et ACT_MODIFIER_MES_* (en fonction du type d’objet rattaché, par exemple : « ACT_MODIFIER_TACHE »). Il faut avoir le droit de modifier l’objet attaché au document pour pouvoir créer le document. Dans le cas d’un attribut de type document il faut également posséder le droit « ACT_UTILISER_ATTRIBUT ».
Exemple	https://projectmonitor/MonitorMakerWeb/api/documents
Bean Entrée	beanWsDocument
Body Entrée	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	Chaine
Body Sortie	Identifiant du nouveau document
Résultat

Description	Récupérations d’informations de document
Code webservice	/documents/idDocument
Règles de gestion
Exemple
Bean Entrée	IDDocument
Body Entrée
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)
Résultat	JSON

Description	Suppression de document
Code webservice	/documents
Règles de gestion	La suppression est soumise aux droits ACT_MODIFIER_* et ACT_MODIFIER_MES_* (en fonction du type d’objet rattaché, par exemple : « ACT_MODIFIER_TACHE »). Il faut avoir le droit de modifier l’objet attaché au document pour pouvoir supprimer le document. Dans le cas d’un attribut de type document il faut également posséder le droit « ACT_UTILISER_ATTRIBUT ».
Exemple	https://projectmonitor/MonitorMakerWeb/api/documents
Bean Entrée	beanWsDocument
Body Entrée	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	Chaine
Body Sortie	true si réussite, sinon une erreur est retournée
Résultat	JSON

/echange : création ou modification

Description	Création ou modification d’une ou d’un ensemble d’échange Si l’échange envoyée comporte un id ou un code qui existe déjà : nous faisons la modification de l’échange existant. Sinon nous créons un nouvel échange avec les informations reçues.
Code webservice	/exchanges
Règles de gestion
Exemple	https://projectmonitor/MonitorMakerWeb/api/exchanges
Bean Entrée	BeanWsEchangeEntréeOu tableau[BeanWsEchangeEntrée1,BeanWsEchangeEntrée2,BeanWsEchangeEntrée3]
Body Entrée	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	BeanWSRetour
Body Sortie
Résultat	JSON

4. API (Verbes HTTP : PUT)

/resources/{id} : Modification d’une ressource

Description	Permet la mise à jour d’informations relative à une ressource
Code webservice	/monitorupgrade/resources/{id} (Attention le endpoint est bien /monitorupgrade/resources/{id} et pas /MonitorMakerWeb/api/resources/{id}
Règles de gestion	Droits ACT_MODIFIER_RESSOURCE “Modifier les ressources”. Le paramètre d’URL {id} correspond à l’identifiant de la ressource Les informations modifiables sont : code : code de la ressource label : libellé de la ressources longLabel : libellé long de la ressource description : description de la ressource hierarchiesValues: rattachements hiérarchiques de la ressource (ajouté en v7.7) category : identifiant de la catégorie type : identifiant du type de ressource profil : identifiant du type de profil Recommandation : Il est recommandé de récupérer initialement le flux en appelant au préalable les service de récupération de ressource /monitorupgrade/ressources/{id} (où {id} est l’identifiant de la ressource. Chaque champ d’une ressource qui ne sera pas renvoyé dans son état original sera supprimé.
Exemple	https://projectmonitor/monitorupgrade/888589
Body Entrée	`{ "id": 899895, "code": "Maeva.cdp", "label": "Maëva CDP", "longLabel":` `null, "description":` `null, "order": -1,` `"hierarchiesValues": [ { "hierarchy": { "id": 88878, "code": "string", "label": "string", "longLabel": "string", "description": "string", "order": 0 }, "values": [ { "id": 987678, "code": "string", "label": "string", "longLabel": "string", "description": "string", "order": 0 } ] } ],"category": { "id": 700627, "code": "CAT_JH", "label": "Ress.", "longLabel":` `null, "description":` `null, "order": -1 }, "type": { "id": 700686, "code": "TYP_RESS_INTERNE", "label": "Interne", "longLabel":` `null, "description":` `null, "order": 0 }, "profile":` `null}`
Body Sortie	`{ "id": 899895, "code": "Maeva.cdp", "label": "Maëva CDP", "longLabel":` `null, "description":` `null, "order": -1,` `"hierarchiesValues": [ { "hierarchy": { "id": 88878, "code": "string", "label": "string", "longLabel": "string", "description": "string", "order": 0 }, "values": [ { "id": 987678, "code": "string", "label": "string", "longLabel": "string", "description": "string", "order": 0 } ] } ],"category": { "id": 700627, "code": "CAT_JH", "label": "Ress.", "longLabel":` `null, "description":` `null, "order": -1 }, "type": { "id": 700686, "code": "TYP_RESS_INTERNE", "label": "Interne", "longLabel":` `null, "description":` `null, "order": 0 }, "profile":` `null}`

/users (ajouté en v7.7)

Description	Permet la mise à jour d’informations d’un utilisateur
Code webservice	/users/{userId}
Règles de gestion	Droit ACT_MODIFIER_UTILISATEUR Pour modifier des informations concernant un utilisateur Pour modifier les rôle hiérarchiques, le paramètre du Webservice saveAssignment doit être à true Le paramètre d’URL {id} correspond à l’identifiant de l’utilisateur. hierarchicalRoles : rôles hiérarchiques de l’utilisateur. L’extrait doit comprendre impérativement l’id de la hiérarchie avec l’id de la valeur de niveau associé (values) ainsi que l’id du rôle accordé. hierarchiesValues : rattachements hiérarchiques de l’utilisateur Il est indispensable de récupérer initialement le flux en appelant au préalable les service de récupération de ressource /monitormaker/user/{id} (où {id} est l’identifiant de l’utilisateur. Chaque champ d’un utilisateur qui ne sera pas renvoyé dans son état original sera supprimé.
Exemple	https://projectmonitor/MonitorMakerWeb/api/users/266414
Bean Sortie	Bean Dossier Utilisateur
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, "hierarchicalRoles": [ { "hierarchy": { "id": 700821, "code": "HIER_DIRECTION_METIER", "label": "Direction(s) bénéficiaire(s)", "longLabel": null, "description": null, "order": 2 }, "values": [ { "id": 701784, "code": "701784", "label": "Direction Générale", "longLabel": "Direction GénéraleDirection Générale", "description": "Direction GénéraleDirection Générale", "order": -1 } ], "role": { "id": 701430, "code": "ROL_DIRECTEUR", "label": "Directeur", "longLabel": null, "description": "Directeur", "order": -1 } } ], "hierarchiesValues": [ { "hierarchy": { "id": 894224, "code": "HIER_INTERNEPARCOURS", "label": "INTERNE - Parcours", "longLabel": null, "description": null, "order": 99 }, "values": [ { "id": 901449, "code": null, "label": "English", "longLabel": null, "description": null, "order": -1 } ] } ],"abonnementsCharges": false, "profilsProjets": null,"motDePasseGereParMM": true, "userLDAP": false,"ligneRoles": "1 - Administrateur<br/>","libelleLong": "adm adm", "codeObjetType": "UTILISATEUR", "key": "315563" }
Résultat	JSON

5. Méthode import par cURL

Présentation

Ces Webservices permettent d'envoyer des fichiers d'import ou de synchronisation. Leur syntaxe est spécifique et ne s'appuie pas sur ce qui a été vu précédemment. L’outil cURL est fourni dans le répertoire « install » de p-monitor. Il permet d’appeler p-monitor en HTTP et de transmettre un fichier CSV à importer. Si la plateforme doit importer des données via son interface HTTP, un utilisateur spécifique à la plateforme doit exister et posséder les bons droits pour exécuter l’import.

Identifiant d’import

Identifiant	Droit PM	Remarque
TEST	#NA	Cet import spécial permet de tester la chaîne technique. Il ne fait que renvoyer par mail à l’utilisateur authentifié le fichier envoyé par cURL.
IMPORT_PROJET	#NA	Import via les fichiers Excel d'import (cf. Mémo d'import pour la syntaxe attendue du fichier).
IMPORT_FACTURE	ACT_EXECUTER_SYNCHROFACTURE Synchroniser les factures
IMPORT_DEVIS	ACT_EXECUTER_SYNCHRODEVIS Synchroniser les devis
IMPORT_TACHE	ACT_CREER_TACHE Ajouter une tâche	Import via les fichiers Excel d’import (cf. Mémo d’import pour la syntaxe attendue du fichier).
SAISIE_ACTIVITE	ACT_EXECUTER_SYNCHROACTIVITE Synchroniser la saisie d'activité
SAISIE_ACTIVITE_RAF	ACT_EXECUTER_SYNCHROACTIVITE Synchroniser la saisie d'activité
SAISIE_ACTIVITE_RAF_DETAIL	ACT_EXECUTER_SYNCHROACTIVITE Synchroniser la saisie d'activité
MESURES_UP	#NA
SYNCHROPROJET	ACT_EXECUTER_SYNCHROPROJET Synchroniser les projets
SYNCHROENVELOPPE	#NA
SYNCHROFINANCIERE (2)	#NA	Cet import représente l’import générique des pièces financières : vous devez préciser le code du type de la pièce financière en paramètre de la requête
SYNCHROAFFECTATION	#NA
SYNCHROENGAGEMENT	#NA
SYNCHROMANDATEMENT	#NA
SYNCHROBUDGET	#NA
SAISIE_BUDGET_PREVISIONNEL_REPARTI_1	#NA	Import du prévisionnel réparti 1
SAISIE_BUDGET_PREVISIONNEL_REPARTI_2	#NA	Import du prévisionnel réparti 2
SAISIE_BUDGET_PREVISIONNEL_REPARTI_3	#NA	Import du prévisionnel réparti 3

Nouvelle méthode de lancement cURL

Pour lancer un import cURL, utilisez la syntaxe suivante dans un 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)
`fichierAEnvoyer.txt`	nom du fichier à envoyer à p-monitor. Celui-ci doit se trouver dans le répertoire courant
`url.de.projectmonitor`	L’URL de l’instance de Project Monitor qui doit recevoir le fichier.
`IDENTIFIANT_IMPORT`	identifiant du type d’import. Voir liste ci-dessus.

🚩

Se référer à http://curl.haxx.se/ pour une utilisation plus précise de l’outil cURL.

Pour attendre la fin de la commande afin de continuer le traitement dans votre fichier batch une fois que l’import est terminé, utilisez l’option wait :

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"

Pour connaitre si un import cURL est en cours, utiliser l’option isrunning :

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"

🚨

Attention : si isrunning est passé en paramètre avec une autre valeur que « true », le webservice renverra un code d’erreur 400.

Pour préciser le type de la pièce financière lors de l’import SYNCHROFINANCIERE, utiliser l’option obligatoire importType :

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"

🚨

Attention, pour bien interpréter le caractère « & » permettant de spécifier les deux options dans l’URL, vous devez bien entourer l’url de guillemets. Sans cela, la requête sera lancée uniquement avec le premier paramètre.

🚨

Attention, une incompatibilité a été détectée lors de l’appel à ce web service via PowerShell. Si cette interface de commande est utilisée, alors il convient de faire appel directement au processus Curl et non pas via le mot clé « Invoke-WebRequest », comme sur l’exemple ci-dessous :

$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/"

L’utilisateur spécifié par le paramètre login reçoit un mail résumant le déroulement de cet import.

Les codes retours http visibles par curl sont :

200	OK
204	il n'y a pas d'import en cours (isrunning)
302	un import est en cours (isrunning)
400	erreur fonctionnelle : se référer au mail envoyé OU si option isrunning demandée, paramètre différent de « true »
401	utilisateur spécifié par le paramètre « login » inexistant ou mot de passe incorrect
403	l’utilisateur spécifié par le paramètre « login » ne possède pas de droits suffisants pour lancer l’import.
405	le serveur de l’application rejette la méthode HTTP utilisée lors de la requête envoyée
500	une erreur technique est survenue. Contacter votre administrateur
503	commande interrompue par un utilisateur