Skip navigation
All People > Prashank Singh > Prashank Singh's Blog > 2017 > May
2017

Prashank Singh's Blog

May 2017 Previous month Next month
Prashank Singh

CA PPM REST API

Posted by Prashank Singh Champion 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*

We have already achieved Rendering HTML inside CA PPM via Lookup, if you have not viewed my previous blog on html lookup then i will recommend you to first go through HTML Fancy Lookups: Getting Started

 

There are few clients where they want to view different sub-object data inside their master object and they want to create new instance or navigate into that instance for updating data from single view. 

 

For example, A client wants to view Top 5 Status Report with its Top Risk, Issue & Change with Projects Overall Status Indicators with task timeline along with Financial Data with some interactive Jasper reports to run from dashbaord type view. I have created a similar layout for Project as shown below: 

 

               <---------------------------------- Screenshot go here ----------------------------------->

Screen #1

           

 

Now how to achieve inline list inside Master Object sub-pages, lets start with our first inline list.

1) Create a Html file and javascript file, which is going to bring your dynamic id and other parameters from url, and place them in Knowledge Store. From Html you need to call JSP which is placed in CA PPM server inside custom folder. JSP page is going to query from CA PPM Database for dynamic inline table. 

2) Create a Dynamic Lookup with html page link from Knowledge store as Html_dsiplay.
3) Create an attribute in custom Object with this Lookup
4) Set Lookups Default Value
5) Set Lookup to Read Only
6) Set "Populate default where null", in case you have already created instance before this attribute creation.
7) Place this Attribute in Create, Edit, filter layout (Note: it won't work in List).
8) From Fields set this Attribute to Pull-Down instead of Browse.

 

Please provide your feedback/comment/concerns over html lookup for health discussion.

 

html lookups cappm ppm lookupslookup

CA PPM Lookups are powerful and widely used while achieving customization from getting dynamic values based on user login to parameter mapping or cascaded value into different lookup etc. Today we are going to learn how to leverage Lookups power to render Html into CA PPM pages to achieve some fancy stuffs.

 

Before we go into code, here are some examples of fancy html lookups.

 

               <------------------------------------- Screenshots go here ---------------------------------->

 

Screen#1 Video saved in Knowledge Store and embedding Youtube Video - used in organizations for communication  and trainings purpose and help videos for Project / Approval Process.

 

 

Screen#2 Images linked to JasperReport - For running jasper report inside instance,

example: running Project Status Report from Project general page.

 

sample backend URL: /reportservice/flow.html?_flowId=viewReportFlow&reportUnit=/shared/reports/ProfileReport&standAlone=true&decorate=no&ParentFolderUri=/shared/reports&ResourceId=5001005&output=pdf

Jasper report Output:

 

 

Screen#3 Interactive web page with Canvas and input control - For creative UI and input controls for changing view.

               

 

Possible benefit in CA PPM:

1) More flexible view with better user experience

2) Interactive data input based on dynamic parameters passed to html.

3) Knowledge Store for saving html and javascript for easy administration.

 

How can we achieve Html inside lookup?

 

For any CA PPM Lookup to render html inside page via lookup you need to set following lookup properties.

 

1) Create a Dynamic Lookup with some html data to display.
      For example:
               <------------------------------------- Code goes here ------------------------------------------->
                     SELECT
                             @select:1:id@
                            ,@select:html_display:html_display@
                     FROM
                           (SELECT
                                 '<!DOCTYPE html>
                                          <html>
                                             <body>
                                                  <div id="page">
                                                  <div id="logo">
                                                <h1><a href="/" id="logoLink">My First Website</a></h1>
                                                   </div>
                                                <div id="nav">
                                                <ul>
                                                <li><a href="#/home.html">Home</a></li>
                                                <li><a href="#/about.html">About</a></li>
                                                <li><a href="#/contact.html">Contact</a></li>
                                                </ul>
                                             </div>
                                       <div id="content">
                                       <h2>Home</h2>
                                           <p>
                                               This is my first webpage! I was able to code all the HTML and CSS in order to make it. Watch out world of web design here I come!
                                          </p>
                                          <p>
                                                   I can use my skills here to create websites for my business, my friends and family, my C.V, blog or articles. As well as any games or more experiment stuff (which is what the web is really all about).
                                          </p>
                                         </div>
                                 <div id="footer">
                                       <p>Webpage made by <a href="/" target="_blank">[your name]</a> </p>
                                 </div>
                                 </div>
                              </body>
                              </html>' as html_display
                           FROM DUAL) Html_sql
               <------------------------------------- Code Ends ----------------------------------------->


2) Create an attribute in custom Object with this Lookup
3) Set Lookup Default Value
4) Set Lookup to Read Only
5) Set "Populate default where null", in case you have already created instance before this attribute creation.
6) Place this Attribute in Create, Edit, filter layout (Note: It does not work in List).
7) Set this Attribute to Pull-Down instead of Browse from Fields 

Let's Check how our First Html Lookup looks like:
               <---------------------------------- Screenshots go here ---------------------------------->

Screen#1 Filter Layout
                  

 

Screen#2 Create Layout

 

Screen#3 Edit Layout


                

However, Lookup has some limitations. We can not put large sql inside dynamic lookup as it has restrictions. So, this leads to use of knowledge store to save web documents and images, which we can call in our query to achieve better dynamic approach and easy administration.

Let's achieve some HTML rendering via Knowledge Store.

Please find attached Timeline.html file as an attachment, this file need to be placed in KS and link needs to be modified in code as highlighted in bold.

 

1) Create a Dynamic Lookup with some html data to display.
For example:
               <--------------------------------- Code goes here --------------------------------------------->

        SELECT
           @select:1:id@
          ,@select:Html_display:Html_display@
       FROM
       ( SELECT
         ' <iframe
         src = "../niku/app?action=dms.viewFile&RhXm0r7tSeUqEr=true&fileId=5000039&fileName=Timeline.html"
                  width = "400%"
                   height = "300"
                   scrolling = "yes" />' as Html_display

         FROM DUAL ) Html_SQL


               <--------------------------------- Code Ends ---------------------------------------------->
2) Create an attribute in custom Object with this Lookup.
3) Set Lookup Default Value.
4) Set Lookup to Read Only.
5) Set "Populate default where null", in case you have already created instance before this attribute creation.
6) Place this Attribute in Create, Edit, filter layout (Note: It does not work in List).
7) Set this Attribute to Pull-Down instead of Browse from Fields.

Lets Check how our First Html Lookup collaborated with Knowledge Store is looking Now.
               <------------------------------------ Screenshots go here ---------------------------------->

             

By using these fancy lookups, you can also achieve Project Task interactive Timelining, Status Indicator over Project, Inline of Sub Object inside Master Object, Navigation with Status Indicator. Also, lot of other stuff  can be achieved as your creative thinking goes.

 

 

Upcoming Post:

Next Blog will be on Inline view of sub-object inside Master Object with Project Phase indicator and task timeline, stay connected