1. Preamble

document presents all the APIs (Application Programming Interfaces) made available by Project Monitor.

Editorial agreement / Glossary

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 recommended by 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
• an HTTP verb, e.g. POST
• information in the HTTP header, e.g. 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

1. 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.
2. HTTP parameters. Example: /projects?country=Germany&year=2012 Parameters are named (key = value). They are separated from the "path" by ? and separated by &. The order of the parameters is not important.
3. "Matrix parameter Example: /projects/;year=2012;country=germany Parameters 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 is the DNS name of the Project Monitor installation 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

Copy 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:

Copy #/ 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:

1. In the specific HTTP header via the key : X-PM-API-KEY
2. In the 'BASIC' HTTP Authorization header: the apikey replaces the login and the password field can be filled with any value.
3. 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:

Copy Accept: application/json

HTTP header for responses

Web services systematically return json encoded in UTF-8 :

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

Cross domain access

It is possible to access Project Monitor webservices from HTML + javascript pages in domains other than Project Monitor. To achieve this, Project Monitor offers two techniques.

JSON-P

Project Monitor implements the json-p technique(http://en.wikipedia.org/wiki/JSONP) and proposes a global parameter for each webservice: jsoncallback.

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

Copy <!—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 (or CORS, http://en.wikipedia.org/wiki/Cross-origin_resource_sharing) is a standard mechanism for sharing information between websites. Project Monitor supports this mechanism on the server side. This mechanism depends on the browser running the calling html page: http: //en.wikipedia.org/wiki/Cross-origin_resource_sharing#Browser_support

Errors

Errors are reported via status HTTP

3. API (HTTP verb: GET)

/templates: project templates

/currentuser : project filters

/currentuser : authorization rights

/roles

/roles/hierarchical: user roles on all projects

/users

/users: user details

/lists

/projects

/projects attributes : value of a project attribute

/projects forms: attribute values for a project form

/projects: list of projects

/projects: identification of the "model" project

/projects: retrieve the value of attachments to hierarchies

/projects: retrieve the value of attachments to a structure

/hierarchies: project links

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

/team

/reports

/phases

/phases: data recovery

/phases: dependency recovery

/phases attributes : value of a attribute type phase

/admin

4. API (HTTP verbs: POST/DELETE)

/projects: creation or modification

/projects: list of projects

/phases: creation or modification

/tasks

/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.
• You can only add/remove a document on an object if it is attached to a project/action or is itself a project/action. Consequently, these webservices do not work with templates.

/echange : creation or modification

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

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

🚩

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:

Copy 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:

Copy 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:

Copy 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:

Copy $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 :