Time-Track Resource

The following requests are supported for operations with time-track records via actiTIME API:

GET/timetrack
GET/timetrack/{userId}/{date}/{taskId}
PATCH/timetrack/{userId}/{date}/{taskId}
PATCH/timetrack/{userId}/{date}/{taskId}/time

Time-Track Record Properties

Time-track record properties available via API:

Property Description
taskId Unique identifier of the task the time is tracked for.
time Tracked time (in minutes).
comment Optional comment for the time-track record.

Required Permissions

Users’ time-track records that can be retrieved are defined by users and tasks available to the authorized user under their permissions.

Permission Available Users Available Tasks
Enter Time-Track Authorized User Only Work Assignments
Manage Accounts & Permissions All Users All Tasks
Modify & Approve Users’ Time-Track Assigned Team Scope of Work
Manage Scope of Work Assigned Team Scope of Work
Manage Cost & Billing Data Assigned Team Scope of Work

Users’ time-track records that can be modified are defined by users and tasks available to the authorized user under their permissions.

Permission Available Users Available Tasks
Enter Time-Track Authorized User Only Work Assignments
Modify & Approve Users’ Time-Track with Manage Scope of Work Assigned Team Scope of Work
Modify & Approve Users’ Time-Track without Manage Scope of Work Assigned Team Only tasks from Scope of Work of the authorized user that are also included in Work Assignments of the team user.

Note that:

1. If a user has several permissions, available objects are summarized.
For example, a user with the ‘Enter Time-Track’ and the ‘Manage Scope of Work’ permissions can retrieve time tracked for the user’s work assignments by the user themselves and their assigned team.

2. If a user is included in the list of ‘Allow selected users to see all users’ data in reports, charts and task details tab’ setting (‘Data Access Restrictions’ section of General Settings interface), then this user can retrieve time-track of any user in the system.

Retrieve Users’ Time-Track

Use one of the following requests to retrieve users’ work time tracked for available tasks:

GET/timetrack
GET/timetrack/{userId}/{date}/{taskId}

 
The GET/timetrack request allows to get time-track of all available users for all available tasks at once as well as get more specific time-track if provided filtering parameters. Also related objects’ info can be included into response.

The GET/timetrack request can be specified with several parameters:

Parameter Description
userIds If provided, only time-track of users with given IDs will be returned.
If not provided, time-track of all available users will be returned.
taskIds If provided, only time tracked for tasks with given IDs will be returned.
If not provided, time tracked for all available tasks will be returned.
projectIds If provided, only time tracked for all available tasks of projects with given IDs will be returned.
If not provided, time tracked for all available tasks will be returned.
customerIds If provided, only time tracked for all available tasks of customers with given IDs will be returned.
If not provided, time tracked for all available tasks will be returned.
dateFrom Required parameter.
Only time tracked after this date will be returned.
dateTo If provided, only time tracked before this date will be returned.
If not provided, all time tracked from [dateFrom] to last tracked date (with time-track) will be returned.
stopAfter If provided, n time-track records will be returned (approximately). The maximum value is 1000.
If not provided, the default value (1000) is applied.
The numbers are approximate because all available time-track records for each day are returned. When the ‘stopAfter’ limit is reached on a specific day, the entire time-track for that day is shown. Time records for remaining days are not included in the response.
includeReferenced Additional data that can also be included in the response:
– time-track comments (if there is no comment for the record, ‘comment’ field will not be returned);
– tasks properties;
– projects properties;
– customers properties;
– users properties;
– departments properties;
– time zone groups properties;
– types of work properties.

Example Request:

curl -X GET "<actiTIME URL>/api/v1/timetrack?userIds=1&taskIds=95&dateFrom=2019-03-01&stopAfter=1000&includeReferenced=comments%2Cusers%2Ctasks%2Cprojects%2Ccustomers" -H "accept: application/json; charset=UTF-8" -u "username:password"

Example Response

{
  "users": {
    "1": {
      "id": 1,
      "username": "admin",
      "active": true,
      "firstName": "John",
      "middleName": "",
      "lastName": "Doe",
      "departmentId": 5,
      "timeZoneGroupId": -1,
      "hired": "2018-11-28",
      "email": "demodata@actitime.com",
      "fullName": "John Doe"
    }
  },
  "dateFrom": "2019-03-01",
  "dateTo": "2019-03-05",
  "customers": {
    "6": {
      "id": 6,
      "name": "Big Bang Company",
      "archived": false,
      "created": 1543352400000,
      "description": "Building and testing a new generation spaceship"
    }
  },
  "projects": {
    "15": {
      "id": 15,
      "customerId": 6,
      "name": "Flight operations",
      "archived": false,
      "created": 1543352400000,
      "description": null
    }
  },
  "tasks": {
    "95": {
      "id": 95,
      "name": "NASA negotiations",
      "description": null,
      "created": 1543352400000,
      "status": "open",
      "workflowStatusId": 4,
      "customerId": 6,
      "projectId": 15,
      "typeOfWorkId": 15,
      "deadline": null,
      "estimatedTime": null
    }
  },
  "data": [
    {
      "userId": 1,
      "records": [
        {
          "taskId": 95,
          "time": 135,
          "comment": "lala"
        }
      ],
      "dayOffset": 3
    },
    {
      "userId": 1,
      "records": [
        {
          "taskId": 95,
          "time": 120
        }
      ],
      "dayOffset": 4
    }
  ]
}

Note that:

1. Users’ IDs are always included in the response in order to identify time-track records.

2. Time-track date is not provided directly in the response. Instead, the ‘dayOffset’ parameter is used. Time-Track Date = dateFrom + dayOffset.

3. If customers’, projects’ and tasks’ IDs are specified in one request, the following priority order is applied: tasks, projects, customers.

4. If the number of time-track records to be returned is more than has been specified in the ‘stopAfter’ parameter, then the ‘nextDateFrom’ parameter is included in the response. Use the value of this parameter as the value for the ‘dateFrom’ parameter in the next request if you want to get all time-track records.

More info on using this request is available in our detailed documentation

 
The GET/timetrack/{userId}/{date}/{taskId} request allows to get only time-track of specified user for specified task on specified date.

Note that:

  • {userId} – user’s id OR username;
  • {date} – date is specified in the following format: ‘YYYY-MM-DD’ OR ‘today’;
  • {taskId} – task’s id.

Example Request:

curl -X GET "<actiTIME URL>/api/v1/timetrack/14/2019-04-01/104" -H "accept: application/json; charset=UTF-8" -u "username:password"

Example Response:

{
  "taskId": 104,
  "time": 150
}

More info on using this request is available in our detailed documentation

Modify Users’ Time-Track

Use one of the following requests to modify users’ time-track:

PATCH/timetrack/{userId}/{date}/{taskId}
PATCH/timetrack/{userId}/{date}/{taskId}/time

 
The PATCH/timetrack/{userId}/{date}/{taskId} request allows to enter tracked time or modify it by replacing the existing value with a specified one. You can also enter or modify time-track comment using this request.

The ‘time’ (in minutes) and ‘comment’ values can be specified in the request body.
If ‘time’ value is set to 0, then the time-track record will be deleted.

Note that:

  • {userId} – user’s id OR username;
  • {date} – date is specified in the following format: ‘YYYY-MM-DD’ OR ‘today’;
  • {taskId} – task’s id.

Example Request:

curl -X PATCH "<actiTIME URL>/api/v1/timetrack/18/2019-05-08/108" -H "accept: application/json; charset=UTF-8" -H "Content-Type: application/json"  -u "username:password" -d "{\"time\": \"120\", \"comment\": \"completed the task\"}"

Example Response:

{
  "taskId": 108,
  "time": 120,
  "comment": "completed the task"
}

More info on using this request is available in our detailed documentation

 
The PATCH/timetrack/{userId}/{date}/{taskId}/time request allows to increase or decrease tracked time only. In order to do this, the ‘delta’ value (in minutes) should be provided in request body. The ‘delta’ value is the difference between wishing record time and the existing one.

  • If the ‘delta’ is positive number, then this value will be added to existing time.
  • If the ‘delta’ is negative number, then this value will be deducted from existing time.
  • If the ‘delta’ is 0, then the existing value will not be changed.

Note that:

  • {userId} – user’s id OR username;
  • {date} – date is specified in the following format: ‘YYYY-MM-DD’ OR ‘today’;
  • {taskId} – task’s id.

Example Request:

curl -X PATCH "<actiTIME URL>/api/v1/timetrack/18/2019-05-08/108/time" -H "accept: application/json; charset=UTF-8" -H "Content-Type: application/json"  -u "username:password" -d "{ \"delta\": -20}"

Example Response:

{
  "taskId": 108,
  "time": 100,
  "comment": "completed the task"
}

More info on using this request is available in our detailed documentation