PPM Pro provides a Web Service Application Programming Interface (WS API) to allow you to integrate the PPM Pro application with other hosted, SaaS, or on-premise applications for seamless data transfer between the applications.
PPM Pro's WSAPI is SOAP-based; SOAP (Simple Object Access Protocol) is a type of API that uses XML over http(s). The SOAP API is published in a Web Serve Definition Language (WDSL) file. The WSDL describes the specific set of functions (and data to be exchanged) that are available. It is a "contract" (formal specification) that developers and programming tools use to understand how to work with a specific product. You can view the PPM Pro WSDL at: https://<yourcompanysubdomain>.ppmpro.com/services/MainService?wsdl.
PPM Pro provides a set of generic web service operations that are called through a secure HTTPS address. These services, when used in conjunction with one another, can accomplish creates, reads, updates, and deletes on any web service enabled entity in the PPM Pro application. The web services can also be used to move data into (create, update and delete) and out of (read) the PPM Pro application.
The Admin/WebServices API page displays a list of web-service-enabled entities and their corresponding entity IDs, which are used with the API. In addition, every entity has a Fields link, which displays a list of all fields on an entity that can be accessed using the API. (If you do not see this page, then Web Services are not enabled for your organization and you should enter a Community case to request it.)
Who can Use the WS API?
To use the WS API, you'll need access to the credentials of a WS API user that is set up in your PPM Pro instance (ask your PPM Pro administrator to create this user). You (the person performing the integration) will use the login credentials of that WS API user to code against the API. A WS API user is a special PPM Pro user type that:
can log into PPM Pro using web service calls
has the ability to perform create, read, update, and delete actions on web-service enabled entities
cannot log in to the PPM Pro (GUI) application - must have a separate login/user type
If you will be developing PPM Pro API integrations, ask your administrator to create a WS API user account for you - even if you already have a non-API account.
The preferred method for programmatic authentication is to use an authentication token generating for WS API users by a PPM Pro admin. You can still authenticate with username/password credentials, but this technique is deprecated and supported only for backward compatibility.
Once your admin generates the token (see below), there are several approaches for implementing, which are described below in Using the Authentication Token.
Generating the Authentication Token
Note: This is not to be confused with the OAuth token, which is used by non-WS API users to access OData feeds. For information about accessing OData, see OData Setup.
A PPM Pro admin can generate an authentication token for any WS API user. This token is used with the user's username to access PPM Pro programmatically. After generating the token the system will display the token in a modal from which you can copy the code and send it to the user. If the token is lost, your admin can create another but cannot retrieve the original token. Currently the WS API user must exist (be saved) before generating the token; also, bulk editing/generating is not supported.
To create an authentication token:
- Navigate to Admin/Users and select the WS API user.
- Choose Actions > Generate Token.
- A modal appears displaying the token.
- Copy the token and send to the WS API user. If the token is misplaced you can simply regenerate another token and send to the user. Generating a new token will invalidate the old token.
API requests can be authenticated with the password of the WSAPI user. This is supported for backward-compatibility with integrations but is no longer recommended. Authentication tokens are both more secure and more efficient. Customers currently using WSAPI user passwords should begin migrating to API tokens as soon as possible. This should be a matter of generating a token and using that token wherever you are currently using a WSAPI user password.
Using the Authentication Token
You can use the auth token as described below (order of preference: BAsic Auth, SOAP body, Login method call)
HTTP Header (Basic Auth)
Usually the simplest way of authenticating a WSAPI request is by HTTP Header, also known as HTTP “Basic Authentication”. This is supported by a variety of SOAP clients. For example, if using SoapUI by SmartBear:
- Set the “Authorization” to “Basic”
- Enter the WSAPI username in the “Username” field
- Enter the API Token in the “Password” field (please avoid using an actual password as this approach is deprecated)
- Select “Authenticate Pre-emptively"
If you are developing your own client, the specifics of the Authorization header can be found at https://tools.ietf.org/html/rfc7617
If your SOAP client does not support Basic Authentication, you can pass the WSAPI username and API token in the SOAP body itself:
You do not need to include the sessionId element when providing username and token in the SOAP body.
Login Method / SessionId
This process is deprecated. It remains supported to provide backward-compatibility with older integrations but is no longer recommended. It requires the client to be able to store a sessionId and handle session expirations and requires additional SOAP requests.
To authenticate with Login Method and SessionId, first call the login method, providing the WSAPI username and token (or password*):
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://services">
The response will contain a sessionId:
This sessionId is valid for 10 minutes and can be passed to other WSAPI methods in the <session> element of the request body for subsequent requests. After 10 minutes, you will need to call the login method again to obtain a new sessionId.
Or, if you're comfortable with WSDLs:
ensure you have a WS API user set up and an authentication token generated
familiarize yourself with the PPM Pro WSDL at: https://<yourcompanysubdomain>.ppmpro.com/services/MainService?wsdl
view the javadoc on Admin/Web Services - click the View API Documentation button
start gathering WS-enabled entity information by visiting the Admin/Web Services API page of the PPM Pro application
run getEntityFields on the entity to validate the current fields
browse the examples