Reports REST API

/reports/search GET

New

Replaces /entries/search POST.

When requesting a set of entries from Tempo via search, you must provide a Context XML document. This is basically a set of parameters telling Tempo which entries you want. It allows you to specify which users to look at, projects, tags, and the date range.

Things of note:

  • There is a default context, meaning you do not have to supply a context document
  • Supplying a context document sets those parameters for your session
  • The entries for the current context are returned if no context is supplied
  • To clear the current context and revert to default, use “/reports/reset GET”
  • The default context filters for the current user, for the ‘last7days’ date range

Here’s an example showing all the options used together:

<?xml version="1.0" encoding="UTF-8"?>
<context>
  <interval>last7days</interval>
  <start-date>2008-01-01</start-date>
  <end-date>2008-06-01</end-date>
  <project-ids type="array">
    <project-id type="integer">1024</project-id>
    <project-id type="integer">2048</project-id>
    <project-id type="integer">8192</project-id>
  </project-ids>
  <user-ids type="array">
    <user-id type="integer">1024</user-id>
    <user-id type="integer">2048</user-id>
  </user-ids>
  <tags type="array">
    <tag>tempo</tag>
    <tag>support</tag>
  </tags>
  <exclude-tags type="array">
    <exclude-tag>discovery</exclude-tag>
    <exclude-tag>internal</exclude-tag>
  </exclude-tags>
  <limit>20</limit>
  <offset>1</offset>
</context>

Note: It’s important that you specify the attribute type="array" for the following grouped attributes:
user-ids, project-ids, tags and exclude-tags.

If limit is not supplied, the list of entries returned is an initial page of 10 entries. Subsequent entries can be retrieved by requesting the next page (the offset parameter) or by upping the page count (the offset parameter). However, this doesn’t have to be part of the XML document, you could alternatively supply page and per_page in the request URI to do the same thing (e.g. https://app.keeptempo.com/reports/search?page=1&per_page=20).

Here’s an example of how you’d execute the search using curl, assuming you saved your XML in a file called ‘context.xml’:

curl -k -X GET -T context.xml -H 'Content-Type:application/xml' \
  -H 'Accept:application/xml' --user login:password \
  https://hotdogzllc.keeptempo.com/reports/search

Parameters

start-date

Date string field, will be parsed by Ruby and Rails’ to_date methods. Recommended format is YYYY-MM-DD.

end-date

Date string field, will be parsed by Ruby and Rails’ to_date methods. Recommended format is YYYY-MM-DD.

interval

The presence of this option causes start-date and end-date to be ignored. Provides a number of
convenient short cuts for dynamic date ranges:

  • today
  • yesterday
  • thisweek
  • lastweek
  • last7days
  • thismonth
  • lastmonth
  • thisquarter
  • lastquarter
  • thisyear
  • lastyear
  • alltime
project-ids

An array of project-id elements, each containing the ID of a project to include in this search.

user-ids

An array of user-id elements, each containing the ID of a user to include in this search.

tags

An array of tag elements, each containing the name of a tag to include in this search.

exclude-tags

An array of exclude-tag elements, each containing the name of a tag to exclude in this search.

exclude-locked

Boolean value indicating whether search should exclude locked entries, defaults to true. Use 1 and 0 for true and false.

include-inactive

Determines whether or not to include inactive users and inactive projects in the search. defaults to false. Use 1 and 0 for true and false.

/reports GET

Beta – New

This is a new method, only available under the beta API.

Provides a listing of all saved reports. Saved reports are returned as SavedContext entities (saved-context in XML). Eventually this will be updated to provide Report entities.

Parameters

id[]

This parameter allows you to request specific entries by ID. Repeat parameter once for each ID, like so:

/reports/?id[]=1&id[]=2&id[]=3

/reports/:id GET

Beta – New

This is a new method, only available under the beta API.

Provides details on a saved report. Returns a SavedContext entity. This will eventually be updated to return Report entities.

Coming Soon

We don’t have any firm dates in mind, but the Reports API will switch over to Report entities, instead of SavedContext, after some good re-writing on our back-end. Once that happens, we’ll be able to provide some new methods here for manipulating saved reports over the API, as well as allowing you to GET a report directly from the API, with its entries in the response data.

The methods we expect to implement still:

  • /reports/new POST
  • /reports/:id/edit GET
  • /reports/:id PUT
  • /reports/:id DELETE

/reports/clear GET

Beta – New

Only available from the beta API, replaces /entries/search POST.

Allows the user to clear the current context filter in his session. See /reports/search GET for more information.