Task

A time entry [Task] is a time slot worked by an employee on a work package.

Review the Usage Guidelines for the Task object.

—	XML	SOAP	REST	Database table
Object	`Task`	`oaTask`	`TimeEntry`	`task`
Supported Commands	`Add`, `Read`, `Modify`, `Delete`, `Reject`	`add()`, `read()`, `modify()`, `upsert()`, `delete()`, `reject()`	See Time Entries	—

—

XML

SOAP

REST

Database table

Object

Task

oaTask

TimeEntry

task

Supported Commands

Add, Read, Modify, Delete, Reject

add(), read(), modify(), upsert(), delete(), reject()

See Time Entries

—

The Task object has the following standard properties:

Note:

Task object properties may also include custom fields. The object type supports the custom equal to read method and the enable_custom read attribute.

XML / SOAP	REST	Database	Description
`acct_date`	`accountingDate`	`acct_date`	The accounting period date of the time entry. See Date Fields
`categoryid`	`categoryId`	`category_id`	The internal ID of the associated service (category).
`category_<N>id` where `<N>` is an integer from 1 to 5	`category<N>Id` where `<N>` is an integer from `1` to `5`	`category_<N>id` where `<N>` is an integer from 1 to 5	The internal ID of the associated service line `<N>` [`category_<N>`].
`cost_centerid`	`costCenterId`	`cost_center_id`	The internal ID of the associated cost center.
`created`	`created`	`created`	[Read-only] The date the time entry was created. See Date Fields
`customerid`	`customerId`	`customer_id`	The internal ID of the associated customer. Determined automatically from `projectid` if not set when adding a time entry.
`date`	`date`	`date`	[Required] The date of the time entry. See Date Fields
`decimal_hours`	`decimalHours`	—	The number of decimal hours for the time entry. If the Use Days Instead of Hours for All Time Entries feature is not enabled for your account: `decimal_hours` accepts decimal values and the decimal part is converted to minutes. For example, `decimal_hours ="5.5"` is equivalent to `hours ="5"` and `minutes ="30"`. The integer part of `decimal_hours` is ignored if a value is set for `hours`. The decimal part of `decimal_hours` is ignored if a value is set for `minutes`. If values are set for both `decimal_hours` and `hours` but not for `minutes`, the decimal parts of `decimal_hours` and `hours` are added and converted to minutes. For example, `decimal_hours ="5.5"` and h `ours ="2.1"` is equivalent to `hours ="2"` and `minutes ="36"`. See also Usage Guidelines.
`description`	`description`	`description`	The description of the time entry.
`end_time`	`endTime`	`end_time`	The time entry end time.
—	`exported`	`exported`	Date and time the time entry was marked as "exported".
`hours`	`hour`	`hour`	The number of hours for the time entry. If the Use Days Instead of Hours for All Time Entries feature is not enabled for your account: `hours` accepts decimal values and the decimal part is converted to minutes and added to the `minutes` value to obtain the total number of minutes for the time entry. The total number of minutes for the time entry is `({hours} ×60 ÷100) +minutes`, where `{hours}` is the decimal part of `hours`. For example, `hours ="5.5"` and `minutes ="6"` is equivalent to `hours ="5"` and `minutes ="36"`. If values are set for both `decimal_hours` and `hours` but not for `minutes`, the decimal parts of `decimal_hours` and `hours` are added and converted to minutes. For example, `decimal_hours ="5.5"` and h `ours ="2.1"` is equivalent to `hours ="2"` and `minutes ="36"`. See also Usage Guidelines.
—	`hoursRemaining`	—	The number of hours remaining of the associated project task.
`id`	`id`	`id`	[Read-only] The unique internal identifier of the time entry . Assigned by SuiteProjects Pro.
`job_codeid`	`jobCodeId`	`job_code_id`	The internal ID of the associated job code.
`loaded_cost`	—	`loaded_cost.cost`	The loaded cost for the associated resource, using the forex future rate from the exchange rate table.
`loaded_cost_2`	—	`loaded_cost.cost`	User's second level loaded cost, using the forex future rate from the exchange rate table.
`loaded_cost_3`	—	`loaded_cost.cost`	User's third level loaded cost, using the forex future rate from the exchange rate table.
`minutes`	`minute`	`minute`	The number of minutes for the time entry. Important: `minutes` does not accept values with a decimal part.
`notes`	`notes`	`notes`	Notes about the time entry.
`payroll_typeid`	`payrollTypeId`	`payroll_type_id`	The internal ID of the associated payroll type.
`project_loaded_cost`	—	`loaded_cost.cost`	User's project cost override in project currency. Uses the future rate from the exchange rate table.
`project_loaded_cost_2`	—	`loaded_cost.cost`	User's project second cost in project currency. Uses the future rate from the exchange rate table.
`project_loaded_cost_3`	—	`loaded_cost.cost`	User's project third cost in project currency. Uses the future rate from the exchange rate table.
`projectid`	`projectId`	`project_id`	The internal ID of the associated project.
`projecttask_typeid`	`projectTaskId`	`projecttask_type_id`	The internal ID of the project task type of the associated project task.
`projecttaskid`	`projectTaskTypeId`	`projecttask_id`	The internal ID of the task within the associated project.
—	`scheduleRequestItemId`	`schedule_request_item_id`	The internal ID of the schedule change item from a schedule request.
`slipid`	`slipId`	`slipid`	The internal ID of the associated slip if this task was billed.
`start_time`	`startTime`	`start_time`	The time entry start time.
`thin_client_id`	`thinClientId`	`thin_client_id`	Used by thin clients to reconcile imported records.
`timesheetid`	`timesheetId`	`timesheet_id`	The internal ID of the associated timesheet. Set automatically to the internal ID matching the time entry `date`, if one exists, or that of a new timesheet (created automatically), otherwise, when adding a time entry. Cannot be modified.
`timetypeid`	`timeTypeId`	`timetype_id`	The internal ID of the associated time type.
`updated`	`updated`	`updated`	[Read-only] The date the time entry was last updated or modified.
`userid`	`userId`	`user_id`	[Required] The internal ID of the associated employee. The user must exist, must not be marked as deleted, must be active and must not be a generic user.

XML / SOAP

REST

Database

Description

acct_date

accountingDate

acct_date

The accounting period date of the time entry.

See Date Fields

categoryid

categoryId

category_id

The internal ID of the associated service (category).

category_<N>id where <N> is an integer from 1 to 5

category<N>Id where <N> is an integer from 1 to 5

category_<N>id where <N> is an integer from 1 to 5

The internal ID of the associated service line <N> [category_<N>].

cost_centerid

costCenterId

cost_center_id

The internal ID of the associated cost center.

created

[Read-only] The date the time entry was created.

See Date Fields

customerid

customerId

customer_id

The internal ID of the associated customer. Determined automatically from projectid if not set when adding a time entry.

date

[Required] The date of the time entry.

See Date Fields

decimal_hours

decimalHours

—

The number of decimal hours for the time entry.

If the Use Days Instead of Hours for All Time Entries feature is not enabled for your account:

decimal_hours accepts decimal values and the decimal part is converted to minutes. For example, decimal_hours ="5.5" is equivalent to hours ="5" and minutes ="30".
The integer part of decimal_hours is ignored if a value is set for hours.
The decimal part of decimal_hours is ignored if a value is set for minutes.
If values are set for both decimal_hours and hours but not for minutes, the decimal parts of decimal_hours and hours are added and converted to minutes. For example, decimal_hours ="5.5" and h ours ="2.1" is equivalent to hours ="2" and minutes ="36".

Usage Guidelines

Review the following guidelines:

The Require a task on time entries setting for the Timesheets application (Administration > Application Settings > Timesheets > Other settings) is not supported. The API lets you add or modify time entries without an associated projecttask (projecttaskid) even if a task is required on time entries in the SuiteProjects Pro UI.
If a projecttaskid is specified and time entry is restricted to the date range covered by that project task, the API returns an error (error code 888) if the time entry date is outside the project task date range.
By default, the loaded cost [loaded_cost] and project loaded cost override [project_loaded_cost] in the time entry [Task] object use the future currency exchange rate from the foreign exchange conversion table [forex]. To force these values to use the exchange rate at the date of the time entry instead of the future exchange rate, contact SuiteProjects Pro Support and request the following account configuration setting to be enabled: API to Respect Time Entry Date for Currency Conversion in Loaded Costs.
You cannot modify a time entry if the authenticated user cannot modify the associated timesheet, or if the Signers feature is enabled and the time entry has been accepted (signed off).
You can enter decimal values for the number of hours [hours] if the Use Days Instead of Hours for All Time Entries feature is not enabled for your account. See Decimal time entry (hours).
You can read and modify the start time [start_time] and end time [end_time] for time entries using the XML API or SOAP API. To modify start_time and [end_time], start and end time entry on timesheets must be enabled for your account. See Modifying the Time Entry Start and End Times.

Important:
You should not use Enable start and end time entry on timesheets and Use Days Instead of Hours for All Time Entries in conjunction.

When Enable start and end time entry on timesheets is enabled and a user enters a start time and end time in SuiteProjects Pro, the duration is calculated in hours and not converted to days.

If both features are enabled, the API returns an error (error code 1407) if you set both decimal_hours and minutes but not hours in the request.

Modifying the Time Entry Start and End Times

You can read and modify the start time [start_time] and end time [end_time] for time entries using the XML API or SOAP API.

Review the following requirements to modify start_time and end_time:

Start and end time entry on timesheets must be enabled. The Enable start and end time entry on timesheets box must be checked on the Administration > Application Settings > Timesheets > Other settings form. The API returns an error (error code: 1406) if you attempt to edit the start or end times and the functionality is not enabled.
The format for start_time and end_time must be hh:mm:ss. The API returns an error (error code: 1404) if either properties are set to an invalid value or a value with the wrong format.

The following examples are valid values: 10:30:15, 2:30 (equivalent to 02:30:00)), 2:30:15 (equivalent to 02:30:15)), 2:3 (equivalent to 02:03:00)), 2:3:4 (equivalent to 02:03:04)).
The start_time value must be before the end_time value. The API returns an error (error code: 1405) if an invalid time range is passed.
When setting start_time and end_time, you must also set the duration using either decimal_hours or hours and minutes.

Note:
The duration is not calculated when you set start_time and end_time. However, the duration is validated. The API returns an error (error code: 1407) if the duration does not match the period between start_time and end_time.
To clear the start_time or end_time, set it to 00:00:00. Setting both start_time and end_time to 00:00:00 sets decimal_hours, hours and minutes to 0 automatically.

Decimal time entry (hours)

Decimal time entry for the number of hours is supported if the feature Use Days Instead of Hours for All Time Entries is disabled for your account:

hours accepts decimal part and the decimal part is converted to minutes. For example, if task.hours = “5.5”; is equivalent to task.hours = “5”; task.minutes = “30”;.
Minutes passed as the decimal part of hours and minutes are added. For example, task.hours = “5.5”; task.minutes = “6”; is equivalent to task.hours = “5”; task.minutes = “36”;.
decimal_hours accepts decimal part and the decimal part is converted to minutes. For example, task.decimal_hours = “5.5”; is equivalent to task.hours = “5”; task.minutes = “30”;.
Minutes passed as the decimal part of decimal_hours are ignored if minutes is also passed. For example, task.decimal_hours = “5.5”; task.minutes = “6”; is equivalent to task.hours = “5”; task.minutes = “36”;.
If both decimal_hours and hours are passed, the integer part of decimal_hours is ignored and only the integer part of hours is used. However, the decimal parts of decimal_hours and hours are added. For example, task.decimal_hours = “5.5”; task.hours = “2.1”; is equivalent to task.hours = “2”; task.minutes = “36”;.
If decimal_hours, hours and minutes are passed, both the decimal and integer parts of decimal_hours are ignored. Minutes passed as the decimal part of hours and minutes are added. For example, task.decimal_hours = “5.5”; task.hours = “2.1”; task.minutes = “20”; is equivalent to task.hours = “2”; task.minutes = “26”;.