Hp Man PPM9.20 RESTful Web Services Guide

HP Project and Portfolio Management CenterSoftware Version: 9.20

RESTful Web Services Guide

Docume

Softwarnt Release Date: February 2013

e Release Date: February 2013

Legal Notic

Warranty

The only warranproducts and seliable for techni

The information

Restricted Right

Confidential co12.211 and 12.2Commercial Ite

Copyright Noti

Copyright 19

Trademark Not

Adobe is a tra

Intel, Intel Icountries.

Microsoft, WCorporation.

Oracle and Java

UNIX is a reg

2es

ties for HP products and services are set forth in the express warranty statements accompanying such rvices. Nothing herein should be construed as constituting an additional warranty. HP shall not be cal or editorial errors or omissions contained herein.

contained herein is subject to change without notice.

s Legend

mputer software. Valid license from HP required for possession, use or copying. Consistent with FAR 12, Commercial Computer Software, Computer Software Documentation, and Technical Data for ms are licensed to the U.S. Government under vendor's standard commercial license.

ces

97-2013 Hewlett-Packard Development Company, L.P.

ices

demark of Adobe Systems Incorporated.

tanium, Intel Xeon, and Pentium are trademarks of Intel Corporation in the U.S. and other

indows, Windows XP, and Windows Vista are U.S. registered trademarks of Microsoft

are registered trademarks of Oracle and/or its affiliates.

istered trademark of The Open Group.

Documenta

This manuals t

Software v Document Software reTo check for re

h20230.www2.

You will also reyour HP sales rtion Updates

itle page contains the following identifying information:

ersion number, which indicates the software version

release date, which changes each time the document is updated

lease date, which indicates the release date of this version of the software

cent updates, or to verify that you are using the most recent edition of a document, go to:

hp.com/selfsolve/manuals

ceive updated or new editions if you subscribe to the appropriate product support service. Contact epresentative for details.

3

Support

You can visit th

hp.com/go/hpso

HP Software Susupport custom

Search for Submit and Download Manage su Look up H Review inf Enter into d Research aMost of the supcontract.

To find more in

h20230.www2.

To register for a

h20229.www2.

4e HP Software Support Web site at:

ftwaresupport

pport Online provides an efficient way to access interactive technical support tools. As a valued er, you can benefit by using the support site to:

knowledge documents of interest

track support cases and enhancement requests

software patches

pport contracts

P support contacts

ormation about available services

iscussions with other software customers

nd register for software training

port areas require that you register as an HP Passport user and sign in. Many also require a support

formation about access levels, go to:

hp.com/new_access_levels.jsp

n HP Passport ID, go to:

hp.com/passport-registration.html

Contents

1 GeOvCoAuMe

2 HPOvDa

Entting Started with HP RESTful Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9erview of PPM Center RESTful Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9nfiguration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9thentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10ssaging Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Demand Management RESTful Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13erview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13ta Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14Requests. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16RequestType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16RequestTypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18RequestField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

RequestField.TableValue. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19RequestField.TableValue.ColumnTokens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19RequestField.TableValue.Row . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19RequestField.TableValue.Row.Columns. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20RequestField.TableValue.Row.Columns.Column. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Reference. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Note . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

tities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23Get Enabled Request Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23Returns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24Message Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24Errors and Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255

6Get a Request Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26Returns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26Message Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26Errors and Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Get Requests of a Certain Type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

3 HPOvDaFunction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36Returns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36Message Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37Errors and Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Get Details of a Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39Returns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39Message Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40Errors and Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Create/Update a Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45Returns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45Message Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46Errors and Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Time Management RESTful Web Services (Time Sheets) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49erview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49ta Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49TimeSheet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51TimeSheets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52TimePeriod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52TimePeriods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53WorkItem. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53WorkItems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54TimeSheetLine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54TimeSheetLines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55Policy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55Policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56Approver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56Actual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56Actuals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

Efforts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58Note . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58WorkUnit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

Entities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61Get Time Sheets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 627

Returns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62Message Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62Errors and Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

Get a Time Sheet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65Returns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65Message Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65Errors and Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

Get Time Periods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68Returns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68Message Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68Errors and Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

Get a Time Period . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70Returns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70Message Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70Errors and Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

Get Work Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72Returns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72Message Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72Errors and Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

Get Time Sheet Lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74Returns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74Message Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74Errors and Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

Get a Time Sheet Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79Returns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79Message Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

8Errors and Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81Get Time Sheet Policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82Returns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82Message Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82Errors and Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

4 REOvDa

En

Index . Create a Time Sheet. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85Message Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86Errors and Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

Update a Time Sheet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90Message Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91Errors and Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

Submit a Time Sheet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95Errors and Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

STful Web Services for PPM Center Solution Integrations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97erview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97ta Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97MACConfigs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98MACConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98FieldMapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100ValueMapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

tities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101Create/Update a MACConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102Message Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103Errors and Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

Get MACConfigs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105Message Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

1 Getting Started with HP RESTful Web Services

Ove

Con9rview of PPM Center RESTful Web Services

PPM Center includes RESTful Web services support for the following application modules:

HP Demand Management

HP Time Management

PPM Center Solution Integrations

The Web Application Description Language (WADL) descriptor that lists all supported PPM Center RESTful Web services can be found at the following location:http(s)://server:port/itg/rest/service.

figuration

Starting from PPM Center version 9.13, the following line is added to the websecurity.conf file to enable RESTful web services:

/rest=com.kintana.core.web.servlet.AllAccessURLSecurity

Check and make sure whether the above line is already there. If not, simply copy and paste it to the websecurity.conf file, which is located in the /conf directory.

10

Authentication

All requests to the RESTful Web services interfaces (URLs) must be authenticated. PPM Center supports the following three authentication types for RESTful Web services:Chapter 1

HTTP Basic Access Authentication

When you use the HTTP Basic Access Authentication, an authorization HTTP header is sent along with the request, containing the base64-encoded username and password.

For example:Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

For more information about HTTP Basic Access Authentication, see RFC 2617.

HTTP Request Query String

When you use the HTTP Request Query String, you must specify the username and password parameters in the URL.

For example:http://:/itg/rest/dm/requestTypes?username=admin&password=admin

Lightweight Single Sign-on (LWSSO)

For details, see the Installation and Administration Guide

HTTPS is preferred whenever you use RESTful Web services by Basic Access Authentication or Request Query String authentication in order to prevent username and password to be transmitted over the network.

Since Request Query String authentication requires your username and password as the parameters in the URL, your username and password will be logged in the log file if the web server is configured to log URLs. This will cause a security flaw.

Getting

Messaging Type

PPM Center supports the following two messaging types for RESTful Web services: Started with HP RESTful Web Services 11

XML (default)

JSON

To enable JSON messaging type, you have to append the string alt=application/json to the parameter list of the URL.

For example: http://:/itg/rest/dm/requestTypes?username=admin&password=admin&alt=application/json

12 Chapter 1

1 HP Demand Management RESTful Web Services

Ove

Data13rview

The implementation of HP Demand Management RESTful Web services contains a set of operations to read request types and read & write requests in the HP Demand Management module.

Types

RESTful Web services for PPM Requests include the following data types:

Request

Requests

RequestType

RequestTypes

Field

RequestField

Reference

Note

14

Request

The Request data type represents the detailed information about a request in the system. Chapter 1

HP Dem

Table 1-1. Request

Property Type Description Required? Default Value

Request ID and Management RESTful Web Services 15

id String (system-generated unique identifier)

Yes N/A

description String Brief description of the request No N/A

requestType StringName of the request type to which the request belongs

Yes N/A

sourceType String

Indicates the type of external update, such as specific interface or migrator name, etc.

No N/A

source String

Used by records that are updated by an interface or migrator. Provides additional information about the source of the external update.

No N/A

16

Re

Re

List of elements of the RequestField data type.

Table 1-1. Request

Property Type Description Required? Default ValueChapter 1

quests

The Requests data type represents a list of requests in the system.

questType

The RequestType data type represents a list of requests in the system.

fields List Contains information about all individual fields of the request.

Yes N/A

notes List

List of elements of the Note data type.Contains user notes of the request. Field change notes are not included.

No N/A

references List

List of elements of the Reference data type.Describes reference entities linked to the request through reference relationships.

No N/A

Table 1-2. Requests


Request List List of the Request elements. Yes N/A

HP Dem

Table 1-3. RequestType


Request type ID (system-and Management RESTful Web Services 17

id String generated unique identifier).

No N/A

name String Name of the request type Yes N/A

description String Description of the request type No N/A

referenceCode String Reference code of the request type No N/A

fields List List of the Field elements No N/A

18

RequestTypes

The RequestTypes data type represents a list of RequestType elements.

Fi

Re

Table 1-4. RequestsChapter 1

eld

The Field data type represents the detailed information about a request field in a request.

questField

The RequestField data type represents the data of a table field in a request. This data type contains the following inner data types:

RequestField.TableValue

RequestField.TableValue.ColumnTokens

RequestField.TableValue.Row


RequestTypes ListList of the RequestType elements. Yes N/A

Table 1-5. Field


token String Token value of the field Yes N/A

prompt String Prompt name of the field Yes N/A

dataType String Data type of the field Yes N/A

defaultValue String Default value of the field Yes N/A

required boolean Indicates whether the field is required. No false

HP Dem

RequestField.TableValue.Row.Columns

RequestField.TableValue.Row.Columns.Column

RequestField.TableValueand Management RESTful Web Services 19

The RequestField.TableValue data type represents the data of a table component field in the request.

RequestField.TableValue.ColumnTokens

The RequestField.TableValue.ColumnTokens data type represents the tokens for various columns in the table component.

RequestField.TableValue.Row

The RequestField.TableValue.Row data type represents the information about a row in the table component.

Table 1-6. RequestField.TableValue


columnTokenList

List of tokens for the various columns in the table component

Yes N/A

row List

List of the Row elements. Contains the information for each row of the table component.

Yes N/A

Table 1-7. RequestField.TableValue.ColumnTokens


columnTokens ListList of tokens for the various columns in the table component.

Yes N/A

20

Table 1-8. RequestField.TableValue.Row


RequestField.TablColumns data type. Chapter 1

RequestField.TableValue.Row.Columns

The RequestField.TableValue.Row.Columns data type represents the data of an individual cell in the table component.

RequestField.TableValue.Row.Columns.Column

The RequestField.TableValue.Row.Columns.Column data type describes the Column elements for a particular row in the table component,

columns eValue.Row.Columns

Contains the value of each column for a row in the table component.

Yes N/A

Table 1-9. RequestField.TableValue.Row.Columns


ColumnList

List containing the Column elements for a particular row in the table component.

Yes N/A

Table 1-10. RequestField.TableValue.Row.Columns.Column


dateValue XMLGregorianCalendarValue of the field if the type is Date No N/A

StringValue String Value of the field if the type is not Date No N/A

HP Dem

Reference

The Reference data type represents detailed information about a reference in a request.

Table 1-11. Referenceand Management RESTful Web Services 21


addedBy String User who added this reference to the request Yes N/A

creationDate XMLGregorianCalendar

Date-time value when this reference was added to the request

Yes N/A

description StringDescription of the relationship between the reference and the request

Yes N/A

name String Name of the reference Yes N/A

refURL String URL of the reference No N/A

22

Note

The Note data type represents detailed information about a note field in a request.

Table 1-12. NoteChapter 1


addedBy String User who added this note to the request Yes N/A

creationDate XMLGregorianCalendar

Date-time value when this note was added to the request

Yes N/A

formattedCreationDate String

Date-time (formatted as per the user's regional settings) when this note was added to the request

Yes N/A

content String Content of the note Yes N/A

requestStatus StringStatus of the request when this note was added

Yes N/A

HP Dem

Entities

RESTful Web services for PPM Requests enables you to do the followings:

Get Enabled Request Types

Gand Management RESTful Web Services 23

Get a Request Type

Get Requests of a Certain Type

Get Details of a Request

Create/Update a Request

et Enabled Request Types

Function

This operation returns a list of all the enabled request types in the system. To perform this operation, you must have the Demand Management license and one of the following access grants:

Demand Mgmt: Edit Requests

Table 1-13. Operation Overview

URL http://:/itg/rest/dm/requestTypes

HTTP Method GET

FunctionThis operation retrieves a list of all enabled request types.For more information, see the Function section.

ReturnsThis operation returns an object of the RequestTypes data structure.For more information, see Returns on page 24.

Message Examples See Message Example on page 24.

Errors and Exceptions See Errors and Exceptions on page 25.

24

Demand Mgmt: Edit All Requests

Demand Mgmt: View Requests

ReturnsChapter 1

This operation returns an object of the RequestTypes data structure, which contains a list of RequestType objects.

Message Example

Method URL: http://:/itg/rest/dm/requestTypes

Message in XML:

31060DEM - Application Bug Application bugs should be used to report

problems in current IT applications.

31120DEM - Database Refresh Database refresh requests can be made for

all IT Ops applications in the testing phase. Standard IT Ops service levels apply.

31150DEM - Initiative Initiative request should be used to

request key projects for future quarters. Provided approval from key stakeholders, Initiative requests will be reviewed in the third week of each quarter.

31430testBug Request type

HP Dem

Errors and Exceptions

G

Table 1-14. Errors and Exceptionsand Management RESTful Web Services 25

et a Request Type

Message Code Message Cause Possible Corrective Action

PPM_WSE000 Internal Error

There was an internal error when you executed the operation.

N/A

PPM_WSE001Cannot Get Internal Server Connection

There was an error when you tried to connect to the PPM server.

N/A

PPM_WSE021You do not have access to view Request Types

The user executing this operation does not have the required access grants.

Verify that the user has the required access grants. For more information, see Function.


URL http://:/itg/rest/dm/requestTypes/{id}

HTTP Method GET

FunctionThis operation retrieves a specific request type.For more information, see the Function section.

26

ReturnsThis operation returns an object of the RequestType data structure.For more information, see the Returns section.

Message Examples See the Message Example section.

Table 1-15. Operation OverviewChapter 1

Function

This operation returns a request type specified by the request type ID in the system. To perform this operation, you must have the Demand Management License. Additionally, one of the following conditions must be met:

You have the Demand Mgmt: Override Demand Management Participant Restriction access grant

You are in one or more of the authorized security groups under the Ownership tab of the request type in Workbench.

Returns

This operation returns an object of the RequestType data structure, which contains information about the RequestType object.

Message Example

Method URL: http://:/itg/rest/dm/requestTypes/31430

Message in XML:

31430testBug Request typeTEST

REQ.REQUEST_ID


HP Dem

Request No.:

Summary1027Text200

falseand Management RESTful Web Services 27

falsetruetruetruefalsefalsefalsefalsefalse

REQ.REQUEST_TYPE_NAMERequest Type:

Summary2001Text200

falsefalsetruefalsetruefalsefalsefalsefalsefalse

REQ.CREATED_BYCreated By:

Summary1065Text200

falsefalsetruetruetruefalsefalse

28

truefalsefalse

REQ.DEPARTMENT_NAMEDepartment:

Chapter 1

Summary1156Text200

falsefalsetruefalsefalsefalsefalsefalsefalsefalse

REQ.REQUEST_SUB_TYPE_NAMESub-Type:

Summary1068Text200


REQ.CREATION_DATECreated On:

Summary1028Date200

false

HP Dem

falsetruetruetruefalsefalsetruefalseand Management RESTful Web Services 29

false

REQ.WORKFLOW_NAMEWorkflow:

Summary2003Text200


REQ.STATUS_NAMERequest Status:

Summary1036Text200

falsefalsetruetruetruefalsefalsefalsefalsefalse

REQ.PRIORITY_NAMEPriority:

30

Summary1063Text200

falsefalsetrueChapter 1

falsefalsefalsefalsefalsefalsefalse

REQ.APPLICATION_NAMEApplication:

Summary1064Text200


REQ.CONTACT_NAMEContact Name:

Summary130Text200

falsefalsetruefalsefalsefalsefalsefalsefalse

HP Dem

false

REQ.ASSIGNED_TO_NAMEAssigned To:

Summary2004and Management RESTful Web Services 31

Text200


REQ.ASSIGNED_TO_GROUP_NAMEAssigned Group:

Summary2005Text200


REQ.CONTACT_PHONE_NUMBERContact Phone:

Summary2024Text200

falsefalsetrue

32

falsetruefalsefalsefalsefalsefalse

Chapter 1

REQ.REQUEST_GROUP_NAMERequest Group:

Summary1440Text200


REQ.CONTACT_EMAILContact Email:

Summary2022Text200


REQ.DESCRIPTIONDescription:

Summary1069

HP Dem

Text200

falsefalsetruefalsefalseand Management RESTful Web Services 33

falsefalsefalsefalsefalse

REQ.PERCENT_COMPLETE% Complete:Percent Complete FieldSummary1027Text200

falsefalsefalsetruefalsefalsefalsefalsefalsefalse

REQD.TABLE_TESTtablecomponent

Bug32863Table200


34

T.TABLE_TEST.IDID

1027Text40

Chapter 1


T.TABLE_TEST.NAMEName

1027Text40


T.TABLE_TEST.GENDERgender

32864Text200

falsefalsetruefalsefalsefalsefalsefalse

HP Dem

falsefalse

and Management RESTful Web Services 35


Table 1-16. Errors and Exceptions




N/A



N/A

PPM_WSE020The Request Type {0} doesn't exist

The request type that the user tried to access does not exist.

Correct the Request Type ID in the URL.




PPM_WSE023The request type with ID {0} is not enabled

The request type that the user tried to access is not enabled.

Enable the request type.

36

Get Requests of a Certain Type


URL http://:/itg/rest/dm/Chapter 1

Function

This operation returns a list of requests of a certain request type, specified by the request type ID. To perform this operation, you must have the Demand Management License and one or more of the following access grants:




Returns

This operation returns an object of the Requests data structure, which contains a list of Request objects. The value for the last update field is formatted according to the user's regional settings.

requestTypes/{id}/requests

HTTP Method GET

FunctionThis operation retrieves a list of requests of a certain request type.For more information, see the Function section.

ReturnsThis operation returns an object of the Requests data structure.For more information, see Returns on page 36.



HP Dem

Message Example

Method URL: http://:/itg/rest/dm/requestTypes/31430/requests

Message in XML:and Management RESTful Web Services 37

30332WebService Test

30182Test SOAP web service






N/A



N/A

38

G

The Request The request type that the user tried to Correct the Request


Message Code Message Cause Possible Corrective ActionChapter 1

et Details of a Request

PPM_WSE020 Type {0} doesn't exist access does not exist.

Type ID in the URL.




PPM_WSE023The request type with Id {0} is not enabled

The request type that the user tried to access is not enabled.

Enable the request type.


URL http://:/itg/rest/dm/requests/{reqId}

HTTP Method GET

FunctionThis operation retrieves the detailed information about a request.For more information, see the Function section.

ReturnsThis operation returns an object of the Request data structure.For more information, see Returns on page 39.

HP Dem



Table 1-19. Operation Overviewand Management RESTful Web Services 39

Function

This operation returns a request, specified by the request ID. To perform this operation, you must have the Demand Management License and be a participant on the request. Alternatively, you must have one or more of the following access grants:




Project Mgmt: View All Projects

Demand Mgmt: Override Demand Management Participant Restriction

Returns

This operation returns an object of the Request data structure, which contains the information about the request.

The values for the fields of the following types are formatted according to the user's regional settings:

Date

Numeric text field

Percentage field

Limitation

This operation returns the visual field values instead of the parameter values. It does not return all the types fields, such as financial summary, staffing profile, attachment, and etc.

40

Currency field

Message Example

Method URL: http://:/itg/rest/dm/requests/30362Chapter 1

Message in XML:

30362This is a test requesttest

REQD.LINK

17.11.http://www.hp.com.HP web site

REQ.REQUEST_GROUP_NAME

REQ.STATUS_NAMENew

REQ.PERCENT_COMPLETE0

REQ.PRIORITY_NAME

REQD.RESOL_SUM

REQ.DEPARTMENT_NAMEFinance

REQ.WORKFLOW_NAMEBug Request Type Workflow

REQ.CONTACT_EMAIL

HP Dem

REQ.REQUEST_ID30362

REQ.DESCRIPTIONThis is a test requestand Management RESTful Web Services 41

REQ.ASSIGNED_TO_NAME

REQ.CREATED_BYAdmin User

REQ.STATUS_CODEIN_PROGRESS

REQ.LAST_UPDATE_DATE2012-08-29T15:41:55.000+08:00

REQD.MODULEModule B

REQ.ASSIGNED_TO_GROUP_NAME

REQ.REQUEST_TYPE_NAMEtest

REQ.REQUEST_SUB_TYPE_NAME

REQ.CONTACT_NAME

REQ.CONTACT_PHONE_NUMBER

REQ.ENTITY_LAST_UPDATE_DATE2012-08-29T15:41:55.000+08:00

42

REQ.CREATION_DATE2012-08-29T15:41:54.000+08:00

REQ.APPLICATION_NAME

Chapter 1

REQD.TABLE_TEST

T.TABLE_TEST.IDT.TABLE_TEST.NAMET.TABLE_TEST.GENDER

1000

Alexander

male/man

1001

Beetle

male/man

HP Dem



Message Code Message Cause Possible Corrective Actionand Management RESTful Web Services 43



N/A



N/A

PPM_WSE101Error when trying to read request with id {0}

There was some error when the system tried to read the request.

N/A

PPM_WSE108 The request {0} does not exist

The request ID you entered does not exist.

Correct the request ID in the URL

PPM_SWE209No eligible actions for this request

The request you tried to access does not have any eligible actions for the you.

Add the user to the workflow step security.

44

Create/Update a Request


URL http://:/itg/rest/dm/Chapter 1

Function

This operation creates/updates a request, specified by the request type. This depends on whether you specify a request ID. If you specify a request ID, this operation will update a request. Otherwise, it will create a request.

To perform this operation, you must be in one or more of the authorized security groups for the create/update action.

requests

HTTP Method POST

Function

This operation creates/updates a request, depending on whether you specify a request ID. If you specify a request ID, this operation will update a request. Otherwise, it will create a request. For more information, see the Function section.

ParametersThis operation contains 8 parameters.For more information, see the Parameters section.

ReturnsThis operation returns an object of the Request data structure.For more information, see Returns on page 45.



Limitation

This operation supports field security check, but it ignores user interface (UI) rules or status dependency. Such constraints have to be validated and enforced on the client side before this operation is invoked.

HP Dem

Parameters

This operation contains the following parameters:

Table 1-22. Parameters

Parameter Descriptionand Management RESTful Web Services 45

Returns

This operation returns an object of the Request data structure, which contains the information about the request.

The values for the fields of the following types are formatted according to the user's regional settings:

Date

Numeric text field

Percentage field

id

Request ID. Indicates whether this operation will update or create a request. If you specify a request ID, this operation will update a request.If you do not specify a request ID, this operation will create a request.

description Brief description of the request

requestType Name of the request type to which the request belongs

sourceType Indicates the type of external update, such as specific interface or migrator name, etc.

source Provides additional information about the source of the external update.

fields Contains information about all individual fields of the request.

notes Contains user notes of the request.

references Describes reference entities linked to the request through reference relationships.

46

Currency field

Message Example

Method URL: http://:/itg/rest/dm/requestsChapter 1

Message in XML:

32412 description Project Issue sourceType source REQ.DESCRIPTION My Sample REQ.PRIORITY_NAME Normal

HP Dem



Message Code Message Cause Possible Corrective Actionand Management RESTful Web Services 47



N/A

PPM_WSE107This request already exists in PPM

There was an error when you tried to create a request.

N/A

PPM_WSE109The request type of request cannot be empty

The request type of request is empty.

Specify a request type for the request.

PPM_SWE117 Invalid workflow stepThe workflow step is not valid. N/A

48 Chapter 1

2 HP Time Management RESTful Web Services (Time Sheets)

Ove

Data49rview

The implementation of HP Time Management RESTful Web services contains a set of operations to read, create, update, and submit time sheets in the HP Time Management module.

Types

RESTful Web services for Time Management include the following data types:

TimeSheet

TimeSheets

TimePeriod

TimePeriods

WorkItem

WorkItems

TimeSheetLine

TimeSheetLines

Policy

50

Policies

Actual

Actuals

ActivityChapter 2

Efforts

Note

WorkUnit

HP Time

TimeSheet

The TimeSheet data type represents detailed information about a time sheet.

Table 2-1. TimeSheet Management RESTful Web Services (Time Sheets) 51


id LongTime sheet ID (system-generated unique identifier)

Yes N/A

periodId Long Period ID of the time sheet Yes N/A

resourceId Long Resource ID of the time sheet Yes M/A

sequence Int Sequence number of the time sheet Yes N/A

status Int Status of the time sheet Yes N/A

description String Description of the time sheet No N/A

policies List Policies applied to the time sheet No N/A

lastUpdatedDateXML Gregorian Calendar

Last updated time of the time sheet No N/A

creationDateXML Gregorian Calendar

Creation date of the time sheet Yes N/A

notes List Notes of the time sheet No N/A

createdBy Long User ID of the time sheet creator Yes N/A

lastUpdatedBy LongUser ID of the last modifier of the time sheet

Yes N/A

52

TimeSheets

The TimeSheets data type represents a list of TimeSheet elements.

Ti

Table 2-2. TimeSheetsChapter 2

mePeriod

The TimePeriod data type represents detailed information about a time period.


timeSheets List List of TimeSheet elements Yes N/A

Table 2-3. TimePeriod


id LongTime period ID (system-generated unique identifier).

Yes N/A

sequence Long Sequence of the time period Yes N/A

type Int

ID of the time period type: 1: Weekly 2: Bi-Weekly 3: Semi-Monthly 4: Monthly

Yes N/A

name String Name of the time period Yes N/A

startDateXML Gregorian Calendar

Start date of the time period Yes N/A

endDateXML Gregorian Calendar

End date of the time period Yes N/A

HP Time

TimePeriods

The TimePeriods data type represents a list of TimePeriod elements.

W

Table 2-4. TimePeriods Management RESTful Web Services (Time Sheets) 53

orkItem

The WorkItem data type represents detailed information about a work item of a time sheet.


timePeriods List List of TimePeriod elements Yes N/A

Table 2-5. WorkItem


id StringWork item ID (system-generated unique identifier)

Yes N/A

type String

Enumeration of: REQUEST PACKAGE TASK PROJECT MISC

Yes N/A

setId String SetID of the work item Yes N/A

name String Name of the work item Yes N/A

description String Description of the work item No N/A

activities List The activities in the work item No N/A

54

WorkItems

The WorkItems data type represents a list of WorkItem elements.

Ti

Table 2-6. WorkItemsChapter 2

meSheetLine

The TimeSheetLine data type represents detailed information about a time sheet line.


workItems List List of WorkItem elements Yes N/A

Table 2-7. TimeSheetLine


id Long ID of the time sheet line Yes N/A

workItemId String ID of the work item Yes N/A

workItemType String Type of the work item Yes N/A

workItemName String Name of the work item No N/A

workItemDescription String Description of the work item No N/A

status Int Status of the time sheet line No 1

approver ListApprovers of the time sheet line

No N/A

actuals List Actuals of time sheet lines No N/A

HP Time

Ti

Po

workUnit WorkUnit Work unit of the time sheet No N/A

Table 2-7. TimeSheetLine

Property Type Description Required? Default Value Management RESTful Web Services (Time Sheets) 55

meSheetLines

The TimeSheetLines data type represents a list of TimeSheetLine elements.

licy

The Policy data type represents detailed information of a time sheet policy.

workItemSetId String SetId of the work item Yes N/A

notes List Notes of time sheet lines No N/A

Table 2-8. TimeSheetLines


timesheetlines ListList of TimeSheetLine elements

Yes N/A

Table 2-9. Policy


name String The name of the time sheet policy Yes N/A

value String The value of the time sheet policy No empty

56

Policies

The Policies data type represents a list of Policy elements.

A

A

Table 2-10. PoliciesChapter 2

pprover

The Approver data type represents the time sheet approver information.

ctual

The Actual data type represents the actual time logged against a time sheet line.


policies List List of the Policy elements Yes N/A

type EnumEnumerationn of: Global User

Yes Global

Table 2-11. Approver


id Long The time sheet approver id Yes N/A

type Enum

Enumeration of: UserBillingApprover ParticipantGroupBillingApprover SecurityGroupBillingApprover UserTimeApprover ParticipantGroupTime Approver SecurityGroupTimeApprover

Yes N/A

HP Time

A

A

Table 2-12. Actual


activityId Long Activity ID No N/A Management RESTful Web Services (Time Sheets) 57

ctuals

The Actuals data type represents the actual time logged against a time sheet.

ctivity

The Activity data type represents detailed inforamtion about an activity in a work item.

activityName String Activity name No N/A

activityType EnumEnumeration of: added inherited

No N/A

efforts List List of Efforts elements No N/A

Table 2-13. Actuals


actual List Actual time logged against a time sheet line Yes N/A

actualType EnumEnumeration of: activity common

Yes N/A

58

Ef

N

Table 2-14. Activity


id Long Activity ID Yes N/AChapter 2

forts

The Efforts data type represents the detailed information about the time logged against a time sheet line per day.

ote

The Note data type represents the detailed information about the Note field of a time sheet line.

description String Activity description Yes N/A

name String Activity name No N/A

category String Activity category No N/A

enable BooleamIndicate whether or not activity is enabled

No false

Table 2-15. Efforts


dayNum IntOrdinal number of the day in the time period.

Yes N/A

effort DoubleHours logged against a day of a time sheet line

Yes N/A

HP Time

W

Table 2-16. Efforts


id Long ID of the note of Yes N/A Management RESTful Web Services (Time Sheets) 59

orkUnit

The WorkUnit data type represents the detailed information about work unit of a time sheet line.

the time sheet

description StringDescription of the note of the time sheet

Yes N/A

type String Type of the note of the time sheet No N/A

createdBy String User ID of the the note creator No N/A

creationDateXML Gregorian Calendar

Creation date of the note No N/A

lastUpdatedBy String User who last updates the note No N/A

lastUpdatedDateXML Gregorian Calendar

Last update date of the note No N/A

60

Table 2-17. WorkUnit


id Long Work unit ID No N/AChapter 2

atualStartXML Gregorian Calendar

Earliest date for which you enter time on any time sheet for the item

No N/A

actualFinishXML Gregorian Calendar

Latest date for which you enter time on any time sheet for your assignment on the item

No N/A

actualEffort double

Total effort you have contributed to a task or request for the cumulative time you have reported on time sheets

No N/A

percentageComplete double

Your personal total percentage contribution towards completing a task or request

No N/A

estimatedFinishXML Gregorian Calendar

Estimated finish date for a task No N/A

HP Time

Entities

RESTful Web services for Time Sheets enables you to do the following:

Get Time Sheets

G Management RESTful Web Services (Time Sheets) 61

Get a Time Sheet

Get Time Periods

Get a Time Period

Get Work Items

Get Time Sheet Lines

Get a Time Sheet Line

Get Time Sheet Policies

Create a Time Sheet

Update a Time Sheet

Submit a Time Sheet

et Time Sheets


URL http://:/itg/rest/tm/timeSheets

HTTP Method GET

Query Parameters ownerUserId: ID of the time sheet owner periodId: the time period ID

FunctionThis operation retrieves a list of time sheetsFor more information, see the Function section.

62

ReturnsThis operation returns an object of the TimeSheets data structure.For more information, see the Returns section.

Message Examples See Message Example.


Function

This operation returns a list of time sheets. To perform this operation, you must have the Time Management License and the access grant: Time Mgmt: View Time Sheets.

Returns

This operation returns an object of the TimeSheets data structure, which contains a list of TimeSheet objects.

If only the query parameter ownerUserId is provided, this operation returns the top 15 time sheets owned by the user.

Message Example

Method URL: http://:/itg/rest/tm/timeSheets/

Message in XML:

44636330277111User, Admin - 11/5/12 - 11/11/12

AllowMultipleTimeSheets false


HP Time

MaximumHoursPerDay false

BucketShowLevel DAY Management RESTful Web Services (Time Sheets) 63

BucketReportMethod HOUR

HourInPeriodType Fixed

ReqActivitiesRequiredFlag true

30180test11111TS12013-01-23T21:02:42.000-8:00

12013-01-23T21:02:42.000-8:00

11

30222102463110User, Admin-11/5/12-11/11/12

BucketShowLevel DAY

BucketReportMethod

64

HOUR

HourInPeriodType Fixed

ReqActivitiesRequiredFlag

Messa

PPMC

PPMC

PPMCChapter 2

true

11



ge Code HTTP Return Code Message CausePossible Corrective Action

_WSE507 400

Error when trying to get time sheets. The operation to get time sheets is supported by two APIs: (1)get a time sheet by id (URL: itg/rest/tm/timeSheets/id); (2) get time sheets by periodId and ownerUserId (URL: itg/rest/tm/timeSheets?periodId=1&ownerUserId=1).

Query parameters are incorrect.

Input correct query parameters.

_WSE006 403The user does not have the access grant to perform this action.

The user does not have the required access grant.

Get the access grant.

_WSE007 403 The user does not have access to this resource.

The user has no access to this resource.

N/A

HP Time

Get a Time Sheet


URL http://:/itg/rest/tm/ Management RESTful Web Services (Time Sheets) 65

Function

This operation retrieves a specific time sheet, specified by the time sheet ID. To perform this operation, you must have the Time Management License and the access grant: Time Mgmt: View Time Sheets.

Returns

This operation returns an object of the TimeSheet data structure, which contains the information about the time sheet.

Message Example

Method URL: http://:/itg/rest/tm/timeSheets/id

Message in XML:

44636330277

timeSheets/id

HTTP Method GET

FunctionThis operation retrieves a specific time sheet.For more information, see the Function section.

ReturnsThis operation returns an object of the TimeSheet data structure.For more information, see the Returns section.



66

111User, Admin - 11/5/12 - 11/11/12

AllowMultipleTimeSheets falseChapter 2

BucketShowLevel DAY

BucketReportMethod HOURS

HoursInPeriodType true

MaximumHoursPerTimeSheet 20.0

EnforcementLevelError false

ReqActivitiesRequiredFlag true

TskActivitiesRequiredFlag true

PrjActivitiesRequiredFlag true

PkgActivitiesRequiredFlag true

MiscActivitiesRequiredFlag true

159463

HP Time

wwwwwwTS12012-12-24T00:00:00.000-08:00

12012-12-24T00:00:00.000-08:00

Mes

PPM

PPM

PPM Management RESTful Web Services (Time Sheets) 67



sage Code HTTP Return Code Message CausePossible Corrective Action

C_WSE507 400

Error when trying to get time sheets. The operation to get time sheets is supported by two APIs: (1)get a time sheet by id (URL: itg/rest/tm/timeSheets/id); (2) get time sheets by periodId and ownerUserId (URL: itg/rest/tm/timeSheets?periodId=1&ownerUserId=1).

The query parameters are incorrect.


C_WSE006 403The user does not have the access grant to perform this action.



C_WSE007 403 The user does not have access to this resource.


N/A

68

Get Time Periods


URL http://:/itg/rest/tm/Chapter 2

Function

This operation retrieves a list of time periods. To perform this operation, you must have the Time Management License.

Returns

This operation returns an object of the TimePeriods data structure, which contains a list of TimePeriod objects.

Message Example

Method URL: http://:/itg/rest/tm/timePeriods

Message in XML:

timePeriods

HTTP Method GET

Query Parameters type: the type of the time period date: the date you want to check. The format of the date

should be yyyy-MM-ddTHH:mm:ssZ.

FunctionThis operation retrieves a list of time periods.For more information, see the Function section.

ReturnsThis operation returns an objects of the TimePeriods data structure.For more information, see the Returns section.


Errors and Exceptions See Errors and Exceptions.

HP Time

10232113122012-12-24T00:00:00.000-08:00 2013-01-06T23:59:59.000-08:00

Messa

PPM_

PPM_

PPM_ Management RESTful Web Services (Time Sheets) 69




WSE000 500 Internal Error


N/A

WSE001 503 Cannot Get Internal Server Connection.


N/A

WSE506 400

The input date or type is invalid, for the data supports the format yyyy-MM-ddTHH:mm:ssZ, and the type is defined as 1, 2, 3, or 4.

The input date or type is invalid


70

Get a Time Period



Function

This operation retrieves a specific time period, specified by time period ID. To perform this operation, you must have the Time Management License.

Returns

This operation returns an object of the TimePeriod data structure, which contains detailed information about the TimePeriod object.

Message Example

Method URL: http://:/itg/rest/tm/Periods/id/30274

Message in XML:

302742751

Periods/id

HTTP Method GET

FunctionThis operation retrieves a specific time period.For more information, see the Function section.

ReturnsThis operation returns an object of the TimePeriod data structure.For more information, see the Returns section.



HP Time

1350230400000 1350835199000


G

Messa

PPM_

PPM_

PPM_ Management RESTful Web Services (Time Sheets) 71

et Work Items



WSE000 500 Internal Error


N/A

WSE001 503 Cannot Get Internal Server Connection.

There was an error when you tried to connect to PPM Server.

N/A

WSE506 400

The input date or type is invalid, for the data supports the format yyyy-MM-ddTHH:mm:ssZ, and the type is defined as 1, 2, 3, or 4.

The input date or type is incorrect.



URL http://:/itg/rest/tm/workItems

HTTP Method GET

FunctionThis operation retrieves a list of work items.For more information, see the Function section.

72

Query Parameters type: [REQUEST, PACKAGE, TASK, PROJECT,

MISC] ownerUserId: the user ID of the work items owner

This operation returns an object of WorkItems data


Function

This operation retrieves a list of work items. To perform this operation, you must have the Time Management License.

Returns

This operation returns an object of WorkItems data structure, which contain a list of WorkItem objects.

Message Example

Method URL:http://:/itg/rest/tm/workItems

Message in XML:

217037TASK31600IPS - Interest Rate Risk Management Processing

System (R20)(D791)ESO PBS GMGI BB-Flexi Loan R20 > IPS -

Interest Rate Risk Management Processing System (R20) (D791)

Returns structure.For more information, see the Returns section.



HP Time

3282935PROJECT60000MS Mail Strategy MS Mail Strategy

Mess

PPM

PPM

PPM

PPM

PPM Management RESTful Web Services (Time Sheets) 73



age Code HTTP Return Code Message CausePossible Corrective Action

C_WSE502 400The owner user id is invalid. Please input correct owner user id.

The owner user ID should be more than 0.

Input correct owner user ID.

C_WSE006 403

The user does not have the access grant to perform this action.


Get the required access grant.

C_WSE007 403The user does not have access to this resource.

The user does not have access to this resource.

N/A

C_WSE508 400Cannot find the resource with the owner user id.

The owner user ID is not correct.

Correct the owner user ID.

C_WSE000 500 Internal error

There was an internal error when you executed this operation.

N/A

74

Get Time Sheet Lines


URL http://:/itg/Chapter 2

Function

This operation retrieves a list of time sheet lines of a time sheet. To perform this operation, you must have the Time Management License and the access grant: View Time Sheets.

Returns

This operation returns an object of the TimeSheetLines data structure, which contains a list of the TimeSheetLine objects.

Message Example

Method URL:http://:/itg/rest/tm/timeSheets/id/timeSheetLines

Message in XML:

1467001

rest/tm/timeSheets/id/timeSheetLines

HTTP Method GET

FunctionThis operation retrieves a list of time sheet lines.For more information, see the Function section.

ReturnsThe operation returns an object of the TimeSheetLines data structure.For more information, see the Returns section.



HP Time

3282935 PROJECT MS Mail Strategy MS Mail Strategy1

33877 Management RESTful Web Services (Time Sheets) 75

UsersTimeApprover

31448 UsersTimeApprover


31446UsersTimeApprover




30131 914 upgrade act1 added

3 4.0

activity

1719041357459200000 0 2222.0 0 true

76

60000

159801vincent testing line details.

TSL 1 Chapter 2

1

1467004 217037TASK IPS - Interest Rate Risk Management

Processing System (R20) (D791)TASK IPS - Interest Rate Risk Management

Processing System (R20) (D791)ESO PBS GMGI BB-Flexi Loan R20

> IPS - Interest Rate Risk Management Processing System (R20) (D791)

1







30078

HP Time

Close - Project Closure inherited

2 3.0

Management RESTful Web Services (Time Sheets) 77

4 5.0

30131 914 upgrade act1

activity

172244 1357977600000 0 2248.8 0 true

31600

78


G


Message Code HTTP Return Code Message CausePossible Corrective ActionChapter 2

et a Time Sheet Line

PPMC_WSE005 404 Not found The time sheet does not exist. N/A

PPMC_WSE000 500 Internal error


N/A

PPMC_WSE509 500

Error when trying to convert the time sheet attributes.

There was a data issue when converting the time sheet attributes.

Fix the data issue


URL http://:/itg/rest/tm/timeSheetLines/id

HTTP Method GET

FunctionThis operation retrieves a specific time sheet line.For more information, see the Function section.

Query Parameters timeSheetLineId

ReturnsThis operation returns an object of the TimeSheetLine data structure.For more information, see the Returns section.



HP Time

Function

This operation retrieves a specific time sheet line of a time sheet, specified by the time sheet line ID. To perform this operation, you must have the Time Management License and the access grant: View Time Sheet. Management RESTful Web Services (Time Sheets) 79

Returns

This operation returns an object of the TimeSheetLine data structure, which contains detailed information of the TimeSheetLine object.

Message Example

Method URL:http://:/itg/rest/tm/timeSheetLines/id

Message in XML:

1467001 3282935 PROJECT MS Mail Strategy MS Mail Strategy 1






80



Chapter 2

30131 914 upgrade act1 added

3 4.0

activity

171904 1357459200000 0 2222.0 0 true

60000

159801 vincent testing line details.

TSL 1 1

HP Time



Message Code HTTP Return Code Message CausePossible Corrective Action

P

P

P Management RESTful Web Services (Time Sheets) 81

PMC_WSE005 404 Not found The time sheet does not exist. N/A

PMC_WSE000 500 Internal error


N/A

PMC_WSE509 500

Error when trying to convert the time sheet attributes.

There was a data issue when converting the time sheet attributes.

Fix the data issue.

82

Get Time Sheet Policies



Function

This operation retrieves a list of time sheet policies. To perform this operation, you must have the Time Management License.

Returns

This operation returns an object of the Policies data structure, which contains a list of Policy objects.

Message Example

Method URL: http://:/itg/rest/tm/policies

Message in XML:

policies

HTTP Method GET

FunctionThis operation retrieves a list of policies.For more information, see the Function section.

Query Parameters ownerUsreId: user ID of the time sheet owner.

ReturnsThis operation returns an object of the Policies data structure.For more information, see the Returns section.



HP Time

BucketShowLevelDAY

BucketReportMethodHOUR

Management RESTful Web Services (Time Sheets) 83

HourInPeriodTypeFIXED

AllowMultipleTimeSheetsfalse

NotifyDelinquentTimeSheettrue

MaximumHourPerTimeSheet20.0

EnforcementLevelErrorfalse

OverrideWorkAllocationFlagfalse

AutoApprovalFlagfalse

ReqActivitiesRequiredFlagtrue

TskActivitiesRequiredFlagtrue

PrjActivitiesRequiredFlagtrue

PkgActivitiesRequiredFlagtrue

MiscActivitiesRequiredFlagtrue

84

ActivitiesDisplayFlagtrue

ExpHrsDisplayFlagtrue

M

PP

PPChapter 2

ReqWorkItemEnabledFlagtrue

TskWorkItemEnabledFlagtrue

PrjWorkItemEnabledFlagtrue

PkgWorkItemEnabledFlagtrue

MiscWorkItemEnabledFlagtrue

Global



essage Code HTTP Return Code Message CausePossible Corrective Action

MC_WSE502 400

The owner user id is invalid. Please input the correct owner user id.

The owner user ID is invalid.

Input the correct owner user id

MC_WSE508 500

Cannot find the resource with the owner user id.

The owner user ID does not exist. N/A

HP Time

Create a Time Sheet


URL http://:/itg/rest/tm/ Management RESTful Web Services (Time Sheets) 85

Function

This operation creates a time sheet. To perform this operation, you must be in one or more of the authorized security groups for the create action.

Parameters

timeSheets

HTTP Method POST

FunctionThis operation creates a time sheet.For more information, see the Function section.

ParametersThis operation contains five parameters. For more information, see the Parameters section.

Returns This operation returns the time sheet ID and time sheet line IDs.




Parameter Description

periodId Time period ID

resourceId Resource ID

Status Time sheet status

Policies Time sheet policies

timeSheetLines Time sheet lines

86

Message Example

Method URL:http://:/itg/rest/tm/timeSheets

Message in XML:Chapter 2

Request Body:

3007511

BucketReportMethod HOURS

HoursInPeriodType WORKDAY

HoursInPeriod

AllowMultipleTimeSheets true

BucketShowLevel DAY

NotifyDelinquentTimeSheet false

30125 30089 PROJECT

2 8.0

3

HP Time

9.0

common

17 Management RESTful Web Services (Time Sheets) 87

1 MISC

30131 inherited

2 8.0

3 9.0

activity

Response Body:

3029130527

88




PPMC

PPMC

PPMC

PPMC

PPMC

PPMC

PPMC

PPMC

PPMC

PPMCChapter 2

_WSE006 403




_WSE007 403The user does not have access to this resource.


N/A

_WSE513 400 Field {0} cannot be null or empty.Field {0} is or empty. Fill the field with a value.

_WSE514 400 Field {0} should be greater than {1}.Field {0} is less than {1}. Correct the field value.

_WSE515 400Field {0} should be greater than or equal to {1}.

Field {0} is less than {1}. Correct the field value.

_WSE516 400 Field {0} should be less than {1}.Field {0} is not less than {1} Correct the field value.

_WSE517 400Field {0} should be less than or equal to {1}.

Field {0} is greater than {1}. Correct the field value.

_WSE518 400Field {0} should be greater than {1} and less than {2}.

Field {0} is not greater than {1} and less than {2}

Correct the field value.

_WSE519 400

Field {0} should be greater than or equal to {1} and less than or equal to {2}.

Field {0} is not greater than or equal to {1} and less than or equal to {2}.


_WSE520 400

The status can only be UNSIBMITTED when a time sheet is created.

The status is not UNSIBMITTED when a time sheet is created.


HP Time

PPMC_WSE521 400 Fail to pass business Fail to pass business N/A

PPMC

PPMC

PPMC

PPMC

PPMC


Message Code HTTP Return Code Message CausePossible Corrective Action Management RESTful Web Services (Time Sheets) 89

restriction. restriction.

_WSE522 500 Time Management service internal error.

There was an internal error when you executed this operation.

N/A

_WSE523 400 Total actual effort cannot be less than 0.

Total actual effort is less than 0.

Correct the total actual effort.

_WSE524 400

The day number exceeds the time period duration, and the day number {0} cannot be greater than {1}.

The day number exceeds the time period duration, and the day number {0} is greater than {1}.

Correct the day number.

_WSE525 400

Work item type must be one of the following types: [TASK, PROJECT, REQUEST, PACKAGE, MISC].

Work item type is undefined.

Choose the work item type from the [TASK, PROJECT, REQUEST, PACKAGE, MISC] list.

_WSE526 400

The work item [{0}:{1}] is invalid for resource {2} and time period {3}.

The work item [{0}:{1}] is invalid for resource {2} and time period {3}.

Choose a valid work item for resource {2} and time period {3}.

90

Update a Time Sheet



Function

This operation updates a time sheet if you specify the time sheet ID. To perform this operation, you must be in one or more of the authorized security groups for the update action.

Parameters

timeSheets/timeSheetsId

HTTP Method PUT

FunctionThis operation updates a time sheet.For more information, see the Function section.

Parameters This operation contains four parameters. For more information, see the Parameters section.

Returns This operation returns the time sheet ID and time sheet line IDs.




Parameter Description

periodId Time period ID

resourceId Resource ID

Status Time sheet status

timeSheetLines Time sheet lines

HP Time

Message Example

Method URL:http://:/itg/rest/tm/timeSheets

Message in XML: Management RESTful Web Services (Time Sheets) 91

Request Body:

44474530245121First TimeSheet

146508130110 PROJECTCMS-MDLCMS-MDL

1 1.0

common

1720420 0 1.0 0 true

30001

159641 dfsdf TSL 1 1

159642 sdfsdf TSL 1

92

1

1465103 17 MISC Chapter 2

M & S - HR M & S - HR 1

30153 rachel_atv1 added

5 10.0

30213 rachel-0808 added

activity

1

Response Body:

3029130527

HP Time




PPMC

PPMC

PPMC

PPMC

PPMC

PPMC

PPMC

PPMC

PPMC

PPMC Management RESTful Web Services (Time Sheets) 93

_WSE006 403



G

Documents

Hp Man PPM9.20 RESTful Web Services Guide