TimeEntry

IMPORTANT  The SOAP API entered a limited enhancement phase in Q4 2020. Access deactivation for version 1.5 began in Q1 2022 and will enter its concluding phases in October 2022. Access to version 1.6 will be deactivated in Q4 2024. Visit our SOAP API lifecycle FAQ article to learn more.

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
ContractID

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
ContractID
NonBillable
ShowOnInvoice

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
BillingApprovalLevelMostRecent
BillingApprovalResourceID

The TimeEntry fields BillingApprovalDateTime, BillingApprovalLevelMostRecent, and BillingApprovalResourceID are updated automatically on creation of a new BillingItemApprovalLevel entity row that references TimeEntry.id.

BillingApprovalResourceID
BillingApprovalDateTime

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
  • On a General TimeEntry (not for task/tickets) the InternalAllocationCodeID value must be present and it must be of type "InternalActivity" or "GeneralActivity".
  • "Floating Holiday" time is allowed only if the Floating Holidays system setting is enabled and the Floating Holiday internal allocation code is set to Display in Regular Time (Admin > Site Setup > Company Setup > Internal Allocation Codes tab > Display in Regular Time is selected for Floating Holiday)
  • "Personal Time" time is allowed only if the Personal Time system setting is enabled and the Personal Time internal allocation code is set to Display in Regular Time (Admin > Site Setup > Company Setup > Internal Allocation Codes tab > Display in Regular Time is selected for Personal Time)
  • "Sick Time" time is allowed only if the Sick Time system setting is enabled and the Sick Time internal allocation code is set to Display in Regular Time (Admin > Site Setup > Company Setup > Internal Allocation Codes tab > Display in Regular Time is selected for Sick Time)
  • "Vacation Time" time is allowed only if the Vacation Time system setting is enabled and the Vacation Time internal allocation code is set to Display in Regular Time (Admin > Site Setup > Company Setup > Internal Allocation Codes tab > Display in Regular Time is selected Vacation Time)

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
RoleID
  • An attempt to create a TimeEntry using a Resource + Role combination with an inactive Role will trigger an error.

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
EndDateTime

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:

Allow time entry on completed tasks

Allow time entry on completed tickets

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