Examples of WS API queris on Timesheet related objects

Products

• Rally On-Premise
• Rally SaaS

Issue/Introduction

How to query on Timesheet related objects in Web Services API?

Resolution

There are two objects in Web Services API that are relevant to Time Tracker: TimeEntryItem and TimeEntryValue.

Example of a query on TimeEntryItem based on a Worproduct.Name:

https://rally1.rallydev.com/slm/webservice/v2.0/timeentryitem?workspace=https://rally1.rallydev.com/slm/webservice/v2.0/workspace/<WORKSPACE_OID>&query=(WorkProduct.Name = us1)&start=1&pagesize=20&fetch=WorkProductDisplayString,TaskDisplayString,Values

and the relevant part of a result:

{
??????? "_rallyAPIMajor": "2",
??????? "_rallyAPIMinor": "0",
??????? "_ref": "https://rally1.rallydev.com/slm/webservice/v2.0/timeentryitem/<OBJECT_OID>",
??????? "_objectVersion": "3",
??????? "TaskDisplayString": "TA1: ta1",
??????? "Values": {
????????? "_rallyAPIMajor": "2",
????????? "_rallyAPIMinor": "0",
????????? "_ref": "https://rally1.rallydev.com/slm/webservice/v2.0/TimeEntryItem/<OBJECT_OID>/Values",
????????? "_type": "TimeEntryValue",
????????? "Count": 2
??????? },
??????? "WorkProductDisplayString": "US1: us1",
??????? "_type": "TimeEntryItem"
????? },

Example of a query on TimeEntryValue filtered by DateVal field, that fetches Hours,TimeEntryItem,Task,WorkProduct,User,Project:

https://rally1.rallydev.com/slm/webservice/v2.0/timeentryvalue?workspace=https://rally1.rallydev.com/slm/webservice/v2.0/workspace/<WORKSPACE_OID>&query=(DateVal%20%3E%202010-01-01)&fetch=Hours,TimeEntryItem,Task,WorkProduct,User,Project&start=1&pagesize=20

Example of a query on TimeEntryValue filtered by WeekStartDate that will return a reference to a Project,WorkProduct,Task,User,Values, and the CreationDate:

https://rally1.rallydev.com/slm/webservice/v2.0/timeentryitem?workspace=https://rally1.rallydev.com/slm/webservice/v2.0/workspace/<WORKSPACE_OID>&query=(WeekStartDate > 2013-09-01)&start=1&pagesize=20&fetch=Project,WorkProduct,Task,User,Values,CreationDate

Per Web Services API object model, there is a WeekStartDate attribute on TimeEntryItem, and it's being used in this query. But it is also possible to user CreationDate which is inherited fromPersistableObject.
Here are a couple of examples of valid query syntax:

(WeekStartDate > 2012-01-01)
(CreationDate > 2012-01-01)
(CreationDate = 2012-02-14T00:30:28.593Z)

Example of Values endpoint:

Vaues is a collection on TimeEntryItem.

https://rally1.rallydev.com/slm/webservice/v2.0/TimeEntryItem/<OBJECT_OID>/Values

Example of Collection Summaries specific to v2.0 of WS API:

WS API documentation has an example of Getting Collection Summaries. That example is adapted below to be used with Values . Here the collection is summarized by LastUpdated and Hours. Both are attributes of Values object.

https://rally1.rallydev.com/slm/webservice/v2.0/timeentryitem/<OBJECT_OID>?fetch=values:summary[LastUpdated;Hours]&pagesize=200

Example of a query that filters on UserName:

It is possible to narrow the query with two conditions, including the UserName

((User.UserName = <User>@<Company.com>) AND (WeekStartDate > 2013-07-20))

https://rally1.rallydev.com/slm/webservice/v2.0/timeentryitem?workspace=https://rally1.rallydev.com/slm/webservice/v2.0/workspace/<WORKSPACE_OID>&query=((User.UserName = <User>@<Company.com>) AND (WeekStartDate > 2013-07-20))&start=1&pagesize=20&fetch=Project,WorkProduct,Task,User,Values,CreationDate,WeekStartDate

It is possible to add User specific attributes to the fetch and they will be fetched. In the query below DisplayName,Disabled are added:

https://rally1.rallydev.com/slm/webservice/v2.0/timeentryitem?workspace=https://rally1.rallydev.com/slm/webservice/v2.0/workspace/<WORKSPACE_OID>&query=((User.UserName = <User>@<Company.com>) AND (WeekStartDate > 2013-07-20))&start=1&pagesize=20&fetch=Project,WorkProduct,Task,User,Values,CreationDate,WeekStartDate,DisplayName,Disabled

Example of a query on TimeEntryValue filtered by TimeEntryItem:

It is possible to query TimeEntryValue based on TimeEntryItem, e.g.

(TimeEntryItem = "/timeentryitem/<OBJECT_OID>")

and also add TimeEntryItem attributes to the fetch, including those related to User object:

https://rally1.rallydev.com/slm/webservice/v2.0/timeentryvalue?workspace=https://rally1.rallydev.com/slm/webservice/v2.0/workspace/<WORKSPACE_OID>&query=(TimeEntryItem = "/timeentryitem/<OBJECT_OID>")&start=1&pagesize=200&fetch=DateVal,Hours,LastUpdated,TimeEntryItem,Task,Project,WorkProduct,User,Disabled

Here is an example of a more specific query directly entered in the browser:

https://rally1.rallydev.com/slm/webservice/v2.0/timeentryitem?workspace=https://rally1.rallydev.com/slm/webservice/v2.0/workspace/<WORKSPACE_OID>&query=(WeekStartDate > 2013-11-01)&start=1&pagesize=20&fetch=Project,WorkProduct,Task,User,Values,CreationDate

A few details of the response are noted below:

a. Total result count:

TotalResultCount: 2,

b. Task is identified:

Task:
{
_rallyAPIMajor: "2",
_rallyAPIMinor: "0",
_ref: "https://rally1.rallydev.com/slm/webservice/v2.0/task/<OBJECT_OID>",
_objectVersion: "1",
_refObjectName: "task1 of leaf1",


c. WorkProduct is identified:

WorkProduct:
{
_rallyAPIMajor: "2",
_rallyAPIMinor: "0",
_ref: "https://rally1.rallydev.com/slm/webservice/v2.0/hierarchicalrequirement/<STORY_OID>",
_objectVersion: "5",
_refObjectName: "leaf1",


d. Number of values endpionts in the returned json:

https://rally1.rallydev.com/slm/webservice/v2.0/TimeEntryItem/<OBJECT_OID>/Values

To continue with this example, next week the first user updated the timesheet. The same query on TimeEntryItem filtered by (WeekStartDate > 2013-11-01)will reuturn 3 results, and the third result will include a new Values endpoint:

https://rally1.rallydev.com/slm/webservice/v2.0/TimeEntryItem/<OBJECT_OID>/Values

e. Example of a query on TimeEntryItem filtered by CreationDate:

The filter below applies to TimeEntryitem, and not to the Task or WorkItem. This query returns only one result: a time entry created by this user on 2013-11-13:

https://rally1.rallydev.com/slm/webservice/v2.0/timeentryitem?fetch=Project,WorkProduct,Task,User,Values,CreationDate&pagesize=100&query=((CreationDate >= 2013-11-13T00:00:00.000Z) AND (CreationDate < 2013-11-13T23:59:59.999Z))