hello@pemari.com 0844 736 2500

CA PPM REST API

15 Jun, 2017
Spread the love ...

With Version 14.3 CA have introduced a new web service i.e. REST API for data retrieving and modifying PPM data. This new web service is a powerful way to achieve integration with other applications, interactive interfaces, easy business automation among others. So we need to first understand how to use them therefore lets get started with CA PPM’s new web service authentications, resource data access and some basics.

REST API URL:

URL structure to access the REST APIs: https://<hostname>:<port>/<context>/rest/<api-version>/<resource-name>

Examplehttps://samplehost:8080/ppm/rest/v1/projects

Where

  • ppm is the default web context for the REST APIs
  • “v1” is the only supported API version for the current release
  • projects is the CA PPM object that the REST API is accessing

 Resource and Operations (Version 15.2):

  • Create, update, or retrieve projects
  • Create, update, retrieve, or delete tasks
  • Create, update, retrieve, or delete teams
  • Create, update, retrieve, or delete assignments
  • Retrieve resources
  • Create, update, retrieve, or delete timesheets, time entries, timesheet notes, and time entry notes
  • Retrieve time periods
  • Create, update, or retrieve project status reports
  • Create or update integration instances
  • Retrieve values from lookups

Authorize and Authenticate for the APIs

To authorize to use the REST APIs, verify that you have the API – Access right assigned. In addition, verify that you have the appropriate application rights to view or update the specific functional areas in the product. For example, a specific user has the API – Access right but does not have the project create access right. When this user makes a POST request for projects, the user gets a “401 unauthorized” error message.

The REST APIs support the following methods for authenticating user requests:

  • Basic Authentication that is based on an encoded username and password
  • Session or cookie based

Tools: For developing code surrounded by restful web services, you need to test your method, payload and its possible response. For consuming restful web services there are number of tools available like: Insomnia Rest Client, Paw, HTTpie.

I’m using Postman and did some basic project fetch and update.

Get data for all project from CA PPM

  • Adding New Custom AttributeOut-of-the-box, only some of the project and task attributes are currently enabled for the APIs. In addition, you can enable custom attributes of specific data types for projects and tasks for the APIs. To enable these custom project and task attributes for the APIs, specify their API Attribute ID values as described in the following procedure.Follow these steps:
    1. Open Administration, and from Studio, click Objects.
    2. Select the object (project or task).
    3. Click Attributes.
    4. Select the attribute that you want to enable for the APIs.
    5. Enter a value in the API Attribute ID field.
    6. Verify that the ID value meets the following requirements:
      • Contains lowercase or uppercase letters or numeric digits only
      • Is unique for an object
        To uniquely identify your custom attributes, we recommend that you prefix your API Attribute IDs with specific letters (for example, with your organization name). Making your API Attribute IDs unique prevents conflicts during a future upgrade when new attributes are introduced. For example, an organization such as ACME Corporation can assign the following unique API Attribute ID to their Compliance attribute: “acmeCompliance”. We also recommend that you use Camel Case notation to name your custom attributes.
    7. Click Save and Return.

    The API Attribute ID is the reference key for an attribute that appears in the result set of an API call.

    The following custom attribute data types are not supported for the REST APIs:

    • Large String
    • Money
    • Multi Valued Lookup
    • Attachment
    • Time Varying

    The interactive REST API reference documentation allows you to query the attributes that the REST APIs support, You can also query your custom attributes.

  • Project Read and Write 

         1) All Project Read

                     URL /projects

                     Method GET

                     Response Document Type application/json

2) One Project Read

                      URL /projects/{project_internal_id}

                      Method GET

                      Response Document Type application/json

3) Updating Project Name

                        URL /projects/{project_internal_id}

Method PATCH

Response Document Type application/json

Request Document Type application/json

                        Response Payload  {  “name”: “ProjectNameChange” }

4) Creating New Project

                        URL /projects

Method POST

Response Document Type application/json

Request Document Type application/json

                        Response Payload  {  “code”: “P0000001”,  “name”: “ProjectNameChange” }

5) Creating Multiple new Projects

                        URL /projects

Method POST

Response Document Type application/json

Request Document Type application/json

                        Response Payload {

“d”: [{ “code”: “PRJ001”, “name”: “PPM Project 1”},

{“code”: “PRJ002”, “name”: PPM Project 2″}]

}

  • Timesheet adjustment

                        URL /timesheets

Method POST

Response Document Type application/json

Request Document Type application/json

                        Response Payload { “adjustedTimesheetId”: 5000000 }

Note: you need to pass timesheet id need to be adjusted

 

  • Filter Expressions & Some Query Parameters

 

offset projects?offset=100
limit projects?limit=50
sort projects?sort=code desc

projects?sort=name,code desc

fields projects?fields=name,isActive
filter projects?filter=(isActive = true)
links projects?links=true
expand projects?expand=(tasks=(fields=(code,startDate,costType)),teams)
Operator Title Example
= Equal (name = ‘project1’)
!= Not Equal (isActive != false)
> Greater Than (scheduleStart > ‘2015-08-18T11:00:00’)
>= Greater Than or Equal To (scheduleStart >= ‘2015-07-15T08:00:00’)
< Less Than (scheduleFinish < ‘2015-11-18T19:00:00’)
<= Less Than or Equal To (scheduleFinish <= ‘2015-12-31T19:00:00’)
startsWith String Starts With (name startsWith ‘abc’)
endsWith String Ends With (name endsWith ‘xyx’)
and Logical AND ((name = ‘project1’) and (isActive = true))
or Logical OR ((name startsWith ‘proj’) or (isApproved = true))

 

Example 

1) Get Project start with Name T

                    URL /projects?filter=(name startsWith’T’)

                     Method GET

                     Response Document Type application/json

2) Increasing Project list limit

                     URL /projects?limit=75

                     Method GET

                     Response Document Type application/json

 

You can further use https://<hostname>:<port>/<context>/rest/describe/index.html#/ URL for API Documentation and reference provided by CA.The API documentation contains all the sample requests for each endpoint.

Prashank Singh

Senior CA PPM Consultant


Spread the love ...

Leave a comment:

Your email address will not be published. Required fields are marked *