This article will show you how to use the PPM Cloud REST API, illustrating how it can used to automate a manual task.
One of the challenges in Oracle PPM is maintaining worker assignments to projects - with a small number of workers and a handful of projects, this is simple, but can more onerous in larger organizations.
The PPM REST API allows you to assign workers to projects from the command line. This gives the potential to script multiple updates, saving time navigating in and out of each project’s team member list to perform manual assignments.
The first thing required is an ERP Cloud user account with the "Projects Integration Specialist" role - this allows the PPM REST APIs to be called.
You will also need the base URL for your cloud instance, which is in the form:
For example, if your pod is abcd-dev1, and the region is em3 then the base url is:
We will use URL in the examples below.
Retrieving The Project Id
The Team Members REST API is driven by the Project Id and not the Project Number or Project Name. So if we want to assign someone to project 1100100, we need to know Oracle’s internal ID for this project.
One way to find this out would be to use Oracle BI Publisher to create a custom Data Model with a simple SQL statement such as:
When run, this would return the Project Id and Project Number.
Alternatively, sticking to our theme of running from the command line, we can use the PPM REST web service to do the same thing. To call a REST web service from the command line, we’ll use cURL.
The Projects GET URL is constructed from the following elements:
These are then used in the cURL command below.
This gives returns the Project Id for the Project Number.
One thing to add here is that you can run this without the "q" query parameter - and this will then return ALL projects and their IDs, which can be handy.
Assigning the Worker to the Project
Armed with the Project Id, we can derive the URL needed to add a team member to the project:
Notice that the unique identifier of the worker is the email address. This implies that there must be one and only worker in the system using that email address - otherwise the API cannot identify which worker to assign and will raise an error. The start date is also critical - the worker and project must be effective as of that date.
The API returns a message that is compressed using gzip - so we have to pipe the cURL output through gunzip to review it.
The full cURL command then looks like this:
When run successfully, we see a simple (nearly) empty return message:
As always, it is as important to check failure responses to understand what messages will be returned and how they can be handled.
Here is a sample error message. There are in an XML-like format.
Checking the Results
To check the successful addition, we can list the Team Members on the project by calling the same URL with a GET request.
The curl command becomes:
And we can see from the output that the team member has been added:
Adding an End-Date
To remove a team-member from a project, we add an end-date using the PATCH method. We need the internal team member id - fortunately we have this from the prior step.
The cURL command is:
This returns an unzipped response containing the TeamMember JSON item, confirming the update:
Note that at this stage you’re limited to updating the Start Date and Finish Date - you can’t update the team member’s role, see example below:
This returns gzipped output, with the following error.
Armed with the PPM REST API, we can list projects and their ids, create and update PPM team members. Using cURL, we can execute these REST APIs from the command line, which gives us the ability to script mass updates.
As always, pay careful attention to error trapping and handling - and make sure that you full test the functionality before production deployment.
Oracle are progressively expanding their REST API catalog for ERP Cloud. For example, in R12, you can report on and update Project Progress using REST.
I’d encourage you to review the full PPM REST API catalog which for R12 can be found here: http://docs.oracle.com/cloud/farel12/projectcs_gs/FAPAP/