Businesses often face challenges integrating time tracking data with their existing project management, HR, and accounting systems. Time tracking API will help to integrate seamlessly with other tools, enabling data synchronization across platforms and reducing data silos.
How to Generate API Token
Access to the API is granted via personal tokens.
To create a personal token with the scopes you need in PPM Express, follow the steps below:
1. Open the Automation settings.
2. Click the New API Token button under the Personal Access Tokens section.
3. Provide the name of your token and select the expiration date and scopes.
4. Select Time Tracking scope: Read and Read & Write for Time Tracking:
Time Tracking Read Permission allows the following actions:
- Retrieve existing time entries.
- Retrieve a list of existing Administrative Categories.
- Retrieve an existing external smart suggestions list.
Time Tracking Read & Write Permission grants additional capabilities:
- Create new time entries.
- Update existing time entries.
- Delete time entries.
- Add external smart suggestions to PPM Express.
- Delete external smart suggestions.
5. Click the Generate Token button. As the token is created, copy it.
Key API Endpoints
Time Entries:
- CREATE: Create a new time entry.
- GET: Retrieve existing time entries for the specific period – day, week, month.
- UPDATE: Update a specific time entry.
- DELETE: Remove a time entry/-s.
Administrative categories:
- GET: Retrieve a list of existing Administrative Categories.
External smart suggestions:
- CREATE: Import new external smart suggestions into PPM Express. So later, tenant users can report time using this suggestion in the Import External panel on the My Time page.
- GET: Retrieve the existing external smart suggestions list for the specific period, day, week, or month.
- DELETE: Remove a smart suggestion/-s.
Functionality Overview
The Time Tracking API supports the following actions:
Time Entry Requests Scope:
- ‘Me’: Retrieve time entries for the resource whose personal access token is used.
-
Another Resource: Retrieve time entries by Resource ID.
Note: The user making the API request must have Manage Resource permission.
Time Entry Types:
The API allows creating, reading, updating, or deleting the following types of time entries:
- Project-level time entries.
- Custom time entries.
- Administrative time entries.
Rules for Time Entry Creation and Updates
During Create and Update requests, the synchronization rules for Billable and Cost Type fields are taken into account based on the PPM Express tenant settings. For example, if Use Cost Type from Project is enabled, the Cost Type value from the Project will be applied when creating a time entry for a task using the API.
Other Time Tracking settings that affect time entry creation include:
- Report Time on Unassigned Tasks: If disabled, time entries cannot be created for tasks not assigned to the resource for whom the entry is being created.
- Enable Custom Time Entries: If disabled, creating a time entry for a custom task is impossible.
- Override Cost Type Value: If disabled, creating a time entry with a Cost Type value other than the one defined by rules is not allowed.
- Override Billable Type Value: If disabled, creating a time entry with a Billable value other than the one defined by rules is not allowed.
- Cut-Off Date for Time Reporting Lock: Time entries cannot be created for locked dates.
- Time Entry Minimum Duration: If the duration is less than the minimum allowed, it will be automatically rounded to the minimum value.
- Administrative Categories: Time entries cannot be created for inactive categories.
For the Time Tracking and Time Tracking Suggestions API Requests, please refer to this article.