TimeEntry
IMPORTANT The SOAP API entered a limited enhancement phase in Q4 2020. Access to version 1.6 will be deactivated.
This entity describes an Autotask Time Entry. A time entry allows an Autotask resource to enter time against a Ticket or Task and to enter General or Regular time, for example, in-house meeting, travel, or training time. Users enter time through a number of modules including Home, Contracts, CRM, Projects, Service Desk, and Timesheets.
Entity details
You can also retrieve this information with the Web Services API call The getEntityInfo() SOAP API call.
Entity Name: | TimeEntry |
Can Create: | |
Can Update: | |
Can Query: | |
Can Delete: | |
Can Have UDFs: |
Conditions and requirements
General
- The Autotask API measures date-time values in UTC. As a result, entries for some zones will frequently overlap UTC midnight. You may need to enable the Allow time entries to span over midnight system setting to prevent errors for these zones.
- TimeEntry respects Autotask Proxy Time Entry; that is, when Proxy Time Entry is enabled, TimeEntry create() and update() are not limited to the TimeEntry resource.
When the Proxy Time Entry system setting is set to Enabled for timesheet approvers, a timesheet approver for the TimeEntry Resource can create and update a TimeEntry.
When the system setting is set to Enabled for timesheet approvers and Administrators, timesheet approvers can create and update Time Entries for those resources whose timesheets they approve, and Administrators can create and update Time Entries for any active resource.
When the Proxy Time Entry setting is disabled, only TimeEntry.ResourceID may edit his or her TimeEntry.
- The entity will respect any After Hours work type conditions enforced in the Autotask GUI.
- You cannot create time entries that are equal to or greater than 24 hours in length. The TimeEntry.HoursWorked value must be > 0 and <= 24.
- A TimeEntry may only be added to a timesheet with the status of New or Rejected (not Submitted, Approved. etc.).
- A TimeEntry cannot be updated if it has been approved and posted.
- A TimeEntry will be rounded if the system settings governing rounding are enabled.
- TimeEntry entities can be deleted as long as all the following conditions apply:
- The time entry is not a Taskfire time entry
- The time entry is not yet posted
- The timesheet the time entry appears on is unsubmitted
- The time entry is not a time off request subject to pre-approval
- The API user created the time entry on another user's behalf.
- Resources without access to the Service Desk module can only create or update TimeEntries for the tickets assigned to them.
- A resource can enter time on a task based on the permission granted by the resource's security level; that is, the assigned security level's Projects permission setting "Can enter time on." Security levels are assigned via the Security tab of the Resource Management page.In the Autotask Onlne Help, refer to Configure Custom Security Levels. and Add, Edit or Copy a Resource.
- A TimeEntry cannot be created for a task associated with a Project where Project.Type = Template (3).
- All TimeEntries made through the API are in Eastern Standard Time (EST).
- The Web Services TimeEntry entity does not support the Autotask interface feature "Bill Immediately". All task and ticket time entries created and updated through the Web Services API must be approved and posted.
- In the Autotask interface, you cannot enter time on Projects of Type = Archived, Template, Baseline. Although currently the Web Services API allows this, it will be prohibited in the future. We strongly recommend that API users not allow time entry on Archived, Template, or Baseline project types.
Special field attributes
Field | Conditions and Requirements |
---|---|
AllocationCodeID |
AllocationCodeID must reference an active Work Type (General) allocation code. A General TimeEntry cannot be created with an AllocationCodeID unless that AllocationCodeID matches the InternalAllocationCodeID. If no AllocationCodeID is provided for a TimeEntry of type GeneralActivity or InternalActivity, or the AllocationCodeID does not equal an InternalAllocationCodeID, the API will set the AllocationCodeID to the InternalAllocationCodeID. |
AllocationCodeID |
An AllocationCodeID and/or ContractID value requires a TicketID or TaskID value. Allocation Codes (Work Type) and Contracts must be associated with a task or ticket. A TimeEntry cannot be created without an AllocationCodeID and/or ContractID if its associated task, issue or ticket has one; the TimeEntry will automatically inherit the values. If the intention is to have a TimeEntry without an AllocationCodeID or ContractID, it must be updated after it is created. |
AllocationCodeID |
On create(), if no value is provided for the AllocationCodeID, ContractID, NonBillable, or ShowOnInvoice fields, the field will be populated by the value inherited from the associated task, issue, or ticket. On update(), if no value is provided for AllocationCodeID, ContractID, NonBillable, or ShowOnInvoice fields, the fields do not inherit the value from the associated task, issue, or ticket. It is presumed that they were changed to show no value. User cannot pass through AllocationCodeID, Contract, NonBillable, or ShowOnInvoice values without the required Security Level permissions. No permissions are required to leave any of the four fields blank. |
BillingApprovalDateTime |
The TimeEntry fields BillingApprovalDateTime, BillingApprovalLevelMostRecent, and BillingApprovalResourceID are updated automatically on creation of a new BillingItemApprovalLevel entity row that references TimeEntry.id. |
BillingApprovalResourceID |
BillingApprovalResourceID and BillingApprovalDateTime must both either be null or contain a value at the same time. One cannot be populated without the other having a value. |
ContractID |
ContractID must reference a contract that is active for the associated account or its parent. If the Contract specified on the TimeEntry excludes a Role or AllocationCodeID (Work Type) specified on the TimeEntry, the default exclusion contract is applied. If the original contract does not specify a default exclusion contract, no contract will be applied. If a time entry is created or updated with a ContractID and the ticket's sub-issue type is excluded on the contract, then the time entry's ContractID will be updated to that of the exclusion contract, if it exists. If it does not exist, the ContractID will be set to null. |
DateWorked |
The DateWorked field is required if no value is supplied for the StartDateTime field. If the StartDateTime is provided without a DateWorked value, the DateWorked value will equal the StartDateTime value (converted to the time zone of the resource associated with the ResourceID). If the user viewing through the UI has a different timezone than the resource associated to the TimeEntry (TimeEntry.ResourceID), the Time Entry History DateWorked value may not appear to be correct. This behavior also occurs when time entries are made by the resource via the UI. The API will set this field's value to midnight for create and update calls. |
DdateWorked, EndDateTime, HoursWorked, ResourceID, RoleID, ShowOnInvoice, StartDateTime, TaskID, TicketID |
These ticket time entry fields are not editable when the timesheet is in a submitted status. Other fields can still be edited if the user has access to edit time entries from the Approve & Post page in the Autotask UI. |
HoursWorked |
If TimeEntry.HoursWorked is left empty, the API calculates a value from the start & end times; that is, the value of TimeEntry.HoursWorked = TimeEntry.EndDateTime – TimeEntry.StartDateTime. |
ImpersonatorUpdaterResourceID |
Even impersonating an administrator, the API user cannot delete a time entry the administrator created via proxy time entry for a third user. |
InternalAllocationCodeID |
|
InternalNotes |
When you use the API to update this field, the REST API will return the text-only version of its content. If you send the content back, the Rich Text and all images that it contains will be lost. You cannot use the API to create items that contain Rich Text, but you can add Rich Text later via a supported method. To learn more, refer to The Rich Text editor. |
Non-Billable |
General time (not customer facing) will always be Non-Billable and will never show on invoice. |
NonBillable |
A False value for TimeEntry.NonBillable requires a TimeEntry.TicketID or TimeEntry.TaskID value. Time entries that are not associated with a Task or Ticket must be non-billable. |
ResourceID |
You can update an existing TimeEntry that has a Resource + Role combination that uses an inactive Role. |
RoleID |
On General TimeEntry (not for task/tickets) the RoleID will always be the default role for the resource, regardless of what value is provided. For General TimeEntry (not for task/tickets) the RoleID defaults to the resource’s default RoleID. A Task TimeEntry must have a valid RoleID for the Resource and Task. Ticket and Task Time Entries must include a RoleID that is valid for the ResourceID. The RoleID must be the same as TicketID.AssignedResourceRoleID or TaskID.AssignedResourceRoleID except when the system setting to "Allow users to modify Role when creating/editing time entries on tickets" is enabled. |
ShowOnInvoice |
A True value for ShowOnInvoice requires a TicketID or TaskID value. Time entries that are not associated with a Task or Ticket cannot display on an invoice. ShowOnInvoice cannot = True if the ContractID references a Flat Rate or Recurring Service type contract. |
StartDateTime |
Task TimeEntries must have TimeEntry.StartDateTime and TimeEntry.EndDateTime values, that is, they must use start and stop time, when the associated Project is set to "Requires Start/Stop Times". TimeEntry.StartDateTime must be < TimeEntry.EndDateTime. |
Status |
TimeEntry may not be created for a TicketID whereTicket.Status = Complete if the Service Desk system setting "Prohibit time entry on tickets whose status is Complete" is enabled. |
SummaryNotes |
A Ticket TimeEntry must have SummaryNotes. The SummaryNotes field is required on tasks when the system setting "Require user to enter summary notes when entering project task time and regular time" is enabled. When you use the API to update this field, the REST API will return the text-only version of its content. If you send the content back, the Rich Text and all images that it contains will be lost. You cannot use the API to create items that contain Rich Text, but you can add Rich Text later via a supported method. To learn more, refer to The Rich Text editor. |
TaskID, TicketID |
If the time entry is associated with a task or ticket that has been completed, your permission to add or edit a time entry is governed by the following system settings: |
Type |
To limit the return to only ticket time entries or only task time entries, you must specify a Type value. Picklist values for Type equal 2 (ITServiceRequest) for use with TicketID or 6 (ProjectTask) for use with TaskID. |
Field definitions
The following table describes the standard Autotask field objects for this entity.
- To retrieve more detailed information specific to a particular Autotask implementation, use the Web Services API call The getFieldInfo() SOAP API call.
- For information on entity UDFs, use getUDFInfo().
- For String datatypes, the number in parentheses ( ) indicates the maximum number of characters allowed.
- LT indicates Local Term.
For more information about fields marked as picklists, review our Understanding picklists article.
NOTE The AllocationCodeID field represents the value displayed as "Work Type" in the Autotask interface.
Field Name | Label | Datatype | Read Only | Is Required | Reference Name | Picklist |
---|---|---|---|---|---|---|
AllocationCodeID | Allocation Code ID | integer | AllocationCode | |||
BillingApprovalDateTime | Billing Approval Date Time | datetime | ||||
BillingApproval LevelMostRecent |
Billing Approval Level Most Recent | integer | ||||
BillingApprovalResourceID | Billing Approval Resource ID | integer | Resource | |||
ContractID | Contract ID | integer | Contract | |||
ContractServiceBundleID | Contract Service Bundle ID | long | ContractServiceBundle | |||
ContractServiceID | Contract Service ID | long | ContractService | |||
CreateDateTime | Create Date Time | datetime | ||||
CreatorUserID | Creator User ID | integer | ||||
DateWorked | Date | datetime | ||||
EndDateTime | End Date Time | datetime | ||||
HoursToBill | Hours To Bill | double | ||||
HoursWorked | Hours Worked | double | ||||
id | Time Entry ID | long | ||||
ImpersonatorCreatorResourceID | Impersonator Creator Resource ID | integer | Resource | |||
ImpersonatorUpdaterResourceID | Impersonator Updater Resource ID | integer | Resource | |||
InternalAllocationCodeID | Internal Allocation Code ID | integer | AllocationCode | |||
InternalNotes | Internal Notes | string (32000) | ||||
LastModifiedDateTime | Last Modified Datetime | datetime | ||||
LastModifiedUserID | Last Modified User ID | integer | ||||
NonBillable | Non-Billable | boolean | ||||
OffsetHours | Offset Hours | double | ||||
ResourceID | Resource ID | integer | Resource | |||
RoleID | Role ID | integer | Role | |||
ShowOnInvoice | Show On Invoice | boolean | ||||
StartDateTime | Start Date Time | datetime | ||||
SummaryNotes | Summary Notes | string (32000) | ||||
TaskID | Task ID | integer | Task | |||
TicketID | Ticket ID | integer | Ticket | |||
Type | Task Type Link | integer |