Prashank Singh

CA PPM REST API

Blog Post created by Prashank Singh on May 30, 2017

With Version 14.3 CA has introduced new web service i.e. REST API for resource retrieving and modifying PPM data, this new web service is powerful to achieve integration with other application, interactive interfaces, easy business automation and other stuff, before these advance development we need to first understand how to use them. So 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, payoad 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 Attribute

    Out-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 

                        Request Payload  {  "name": "ProjectNameChange" }

         4) Creating New Project

                        URL /projects

                        Method POST

                        Response Document Type application/json 

                        Request Document Type application/json 

                        Request Payload  {  "code": "P0000001",  "name": "ProjectNameChange" }

         5) Creating Multiple new Projects

                        URL /projects

                        Method POST

                        Response Document Type application/json 

                        Request Document Type application/json 

                        Request 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 

                        Request Payload { "adjustedTimesheetId": 5000000 }

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

 

  • Filter Expressions & Some Query Parameters

 

offsetprojects?offset=100
limitprojects?limit=50
sortprojects?sort=code desc

 

projects?sort=name,code desc
fieldsprojects?fields=name,isActive
filterprojects?filter=(isActive = true)
linksprojects?links=true
expandprojects?expand=(tasks=(fields=(code,startDate,costType)),teams)
OperatorTitleExample
=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')
startsWithString Starts With(name startsWith 'abc')
endsWithString Ends With(name endsWith 'xyx')
andLogical AND((name = 'project1') and (isActive = true))
orLogical 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.

 

cappm ca ppm rest ca ppm*

Outcomes