Users assigned the right to "View management reports" can view any users' time entries. Other users can only view their own time entries.

Users can not create, update or delete another user's time entries.

Classifications

Each time entry may be associated with one activity and one project or task. Classifications, including activities and tasks, can be enabled by an Administrator using LiveTimer's web interface.

Time Data

There are two types of time entries:

• Start / end time entries - Start and end times must be specified, and should each include a time zone offset (e.g. UTC-5 should be specified as -05:00). The duration will be calculated as the difference between these times.
• Duration-only time entries - A start date and duration must be specified.

Durations are in minutes. If seconds are specified in start or end times, they will be truncated rather than rounded.

Show

Request

GET /time_entries/#{time-entry-id}.xml

Optional parameters

Resources related to time entries, including users, activities, clients, projects and tasks, can be included in the response. For example:

GET /time_entries/#{time-entry-id}.xml?include=users,activities,clients,projects,tasks

Response

Status: 200 OK

<time-entry>
  <id type="integer">3864</id>
  <!-- if start / end time entry -->
  <start-time type="datetime">2007-08-30T08:28:00-04:00</start-time>
  <end-time type="datetime">2007-08-30T13:24:00-04:00</end-time>
  <!-- else if duration-only time entry -->
  <start-date type="date">2007-08-30</start-date>
  <!-- end -->
  <duration type="integer">296</duration>
  <note/>
  <created-at type="datetime">2007-08-30T12:28:00Z</created-at>
  <updated-at type="datetime">2007-12-20T06:55:23Z</updated-at>
  <!-- if include=users -->
  <user>
    ...
  </user>
  <!-- else -->
  <user-id type="integer">25</user-id>
  <!-- end -->
  <!-- if include=projects -->
  <project>
    ...
  </project>
  <!-- else -->
  <project-id type="integer">29</project-id>
  <!-- end -->
  <!-- if include=activities -->
  <activity>
    ...
  </activity>
  <!-- else -->
  <activity-id type="integer">16</activity-id>
  <!-- end -->
</time-entry>

List

Request

To request all time entries:

GET /time_entries.xml

As mentioned above, this request will return all the time entries in your account (or the first 50, whichever is less) if you've been assigned the right to "View management reports". Other users will only see their own time entries.

Optional parameters

The following parameters may be combined in any order to filter and customize the listing of time entries:

start=#{starting offset in array}

end=#{starting offset in array}

include=[users,
         activities,
         clients,
         projects,
         tasks]

clients=[none,
         active,
         inactive,
         #{any-client-id}]

projects=[none,
          active,
          inactive,
          my_assignments,
          my_active_assignments,
          my_inactive_assignments,
          #{any-project-id}]
	
tasks=[none,
       active,
       inactive,
       #{any-task-id}]

activities=[none,
            active,
            inactive,
            my_assignments,
            my_active_assignments,
            my_inactive_assignments,
            #{any-activity-id}]

users=[me,
       active,
       inactive,
       #{any-user-id}]

start_date=#{date in the format YYYYMMDD}

end_date=#{date in the format YYYYMMDD}

utc_offset=#{UTC offset in minutes (assumes 0 if not set)}

Specify start and end to request a specific range of items. For example:

GET /time_entries.xml?start=1&end=4

Resources related to time entries, including users, activities, clients, projects and tasks, can be included in the response. For example:

GET /time_entries.xml?include=users,activities,clients,projects,tasks

This example should find all of the current user's time entries associated with clients 1 or 2:

GET /time_entries.xml?clients=1,2&users=me

Note that parameters of the same filter type are combined with a logical OR, and filters of different types are combined with a logical AND. Therefore, the conditions in the above example could be written in pseudo-code as ((client = 1) OR (client = 2)) AND (user = me).

When specifying a start_date and / or end_date, also specify utc_offset if you want those dates to start at a time other than midnight UTC. The following example requests time entries started on or after midnight, January 1, 2008, UTC-5:00 (i.e. -300 minutes offset from UTC):

GET /time_entries.xml?start_date=20080101&utc_offset=-300

The reason that filtering is done at the date level instead of at a finer scale of hours or minutes is so that "duration only" time entries can be included in the results in a logical manner. As discussed above, these time entries are only associated with a date, and don't have a time zone association.

Response

Status: 200 OK

<time-entries total="11" end="11" start="1">
  <time-entry>
    ...
  </time-entry>
  ...
</time-entries>

Time Summary

Time summaries return the total duration of time entries, filtered and grouped as specified below.

Request

To request a time summary:

GET /time_entries/summary.xml

Optional parameters

The following parameters may be combined in any order to filter and customize time summaries (note: filters match the filters documented above under List):

# Note: a maximum of 2 groupings can be specified
group_by=[users,
          activities,
          clients | projects | tasks]

clients=[none,
         active,
         inactive,
         #{any-client-id}]

projects=[none,
          active,
          inactive,
          my_assignments,
          my_active_assignments,
          my_inactive_assignments,
          #{any-project-id}]
	
tasks=[none,
       active,
       inactive,
       #{any-task-id}]

activities=[none,
            active,
            inactive,
            my_assignments,
            my_active_assignments,
            my_inactive_assignments,
            #{any-activity-id}]

users=[me,
       active,
       inactive,
       #{any-user-id}]

start_date=#{date in the format YYYYMMDD}

end_date=#{date in the format YYYYMMDD}

utc_offset=#{UTC offset in minutes (assumes 0 if not set)}

Time summaries can be grouped using the group_by parameter. A maximum of two groupings can be specified. If a hierarchical grouping, such as tasks, is specified then the report will automatically be grouped by its parents as well (i.e. clients and projects). For example, the following request should return a report grouped by clients, projects, tasks and then users:

GET /time_entries/summary.xml?group_by=tasks,users

This example should return a summary of the current user's time entries associated with clients 1 or 2, grouped by clients and projects:

GET /time_entries/summary.xml?clients=1,2&users=me&group_by=projects

If you haven't done so already, please read the List section above to understand the nuances of the filters.

Response

Responses will vary in structure depending upon the group_by parameter specified. Without specifying any grouping, results will be similar to the following:

Status: 200 OK

<time-summary>
  <duration type="integer">11653</duration>
</time-summary>

The following response is to a request with group_by=projects:

Status: 200 OK

<time-summary>
  <clients>
    <client>  
      <id type="integer"></id>
      <name></name>
      <code></code>
      <projects>  
        <project>
          <id type="integer"></id>
          <duration type="integer">840</duration>
          <name></name>
          <code></code>
        </project>
      </projects>  
      <duration type="integer">840</duration>
    </client>
    <client>  
      <id type="integer">24</id>
      <name>American UFO Association</name>
      <code></code>
      <projects>  
        <project>
          <id type="integer">30</id>
          <duration type="integer">3329</duration>
          <name>Area 51 project</name>
          <code></code>
        </project>
        <project>
          <id type="integer">31</id>
          <duration type="integer">524</duration>
          <name>UFO #7856</name>
          <code></code>
        </project>
      </projects>  
      <duration type="integer">3853</duration>
    </client>
    ...
  </clients>  
  <duration type="integer">11653</duration>
</time-summary>

As shown above, unclassified time will be returned with a blank name and id.

Create "Start / Stop" Time Entry

Request

POST /time_entries.xml

Include the following data with your request:

<time-entry>
  <!-- start and end times (REQUIRED) -->
  <!-- NOTE: specify time zone -->
  <start-time>2008-01-08T16:01:00-05:00</start-time>
  <end-time>2008-01-08T16:11:00-05:00</end-time>
  <!-- project-id OR task-id (optional)-->
  <project-id>28</project-id>
  <!-- activity-id (optional)-->
  <activity-id>16</activity-id>
  <!-- note (optional)-->
  <note>
    <![CDATA[Phone call from June.]]>
  </note>
</time-entry>

Response

Status: 201 Created

<time-entry>
  <id type="integer">#{new-time-entry-id}</id>
  <user-id type="integer">25</user-id>
  <start-time type="datetime">2008-01-08T16:01:00-05:00</start-time>
  <end-time type="datetime">2008-01-08T16:11:00-05:00</end-time>
  <duration type="integer">10</duration>
  <project-id type="integer">28</project-id>
  <activity-id type="integer">16</activity-id>
  <note>
    <![CDATA[Phone call from June.]]>
  </note>
  <created-at type="datetime">2008-01-08T18:27:39Z</created-at>
  <updated-at type="datetime">2008-01-08T18:27:39Z</updated-at>
</time-entry>

Create "Duration Only" Time Entry

Request

POST /time_entries.xml

Include the following data with your request:

<time-entry>
  <!-- start date (REQUIRED) -->
  <start-date>2008-01-08</start-date>
  <!-- duration in minutes (REQUIRED) -->
  <duration>10</duration>
  <!-- project-id OR task-id (optional)-->
  <project-id>28</project-id>
  <!-- activity-id (optional)-->
  <activity-id>16</activity-id>
  <!-- note (optional)-->
  <note>
    <![CDATA[Phone call from June.]]>
  </note>
</time-entry>

Response

Status: 201 Created

<time-entry>
  <id type="integer">#{new-time-entry-id}</id>
  <user-id type="integer">25</user-id>
  <start-date type="date">2008-01-08</start-date>
  <duration type="integer">10</duration>
  <project-id type="integer">28</project-id>
  <activity-id type="integer">16</activity-id>
  <note>
    <![CDATA[Phone call from June.]]>
  </note>
  <created-at type="datetime">2008-01-08T18:39:56Z</created-at>
  <updated-at type="datetime">2008-01-08T18:39:56Z</updated-at>
</time-entry>

Update

Request

PUT /time_entries/#{time-entry-id}.xml

Include ANY of the following data with your request:

<time-entry>
  <!-- if "start / end" time entry -->
  <start-time>2008-01-08T16:01:00-05:00</start-time>
  <end-time>2008-01-08T16:11:00-05:00</end-time>
  <!-- end -->
  <!-- if "duration-only" time entry -->
  <start-date>2008-01-08</start-date>
  <duration>10</duration>
  <!-- end -->
  <project-id>28</project-id>
  <activity-id>16</activity-id>
  <note>
    <![CDATA[Phone call from June.]]>
  </note>
</time-entry>

In order to change a "duration-only" time entry into a "start / end" time entry, specify an empty start-date and a valid start-time and end-time. In order to do the reverse, specify a valid start-date and duration.

Response

Status: 200 OK

Delete

Request

DELETE /time_entries/#{time-entry-id}.xml

Response

Status: 200 OK