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	—

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 OpenAir.
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.

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 OpenAir 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 OpenAir Customer 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 OpenAir, 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”;.