Tasks

Tasks are activities that need to be completed. Use the task record to add new tasks for individuals, companies or contacts and to modify those records. For information about working with tasks in the UI, see Creating a Project Task Record.

The task record is defined in the actSched (scheduling) XSD.

Supported Operations

The following operations can be used with task records.

add | addList | attach / detach | delete | deleteList | get | getDeleted | getList | getSavedSearch | getSelectValue | search | update | updateList | upsert | upsertList

Field Definitions

The SOAP Schema Browser includes definitions for all body fields, sublist fields, search filters, and search joins available to this record. For details, see the SOAP Schema Browser’s task reference page.

Usage Notes

In SOAP web services tasks are ordered by creation date. In the UI, tasks can be ordered by specifying an Insert Before parameter that places the current task before an existing task assigned to the same user. This functionality is NOT available through SOAP web services.

Identifying Unique TaskContact List Records

Entries in the TaskContact list are identified by unique combinations of the customer/contact pairing. Therefore, if you have multiple entries in the TaskContact list with the same customer, the contact is also needed to further identify the record. In the event that two or more entries have the same customer/contact pairing, these entries are treated as a single unit.

Time Tracking Sublist

When the Time Tracking feature is enabled, the TimeItemList sublist is available. This list is used to track employee time associated with the task, including payroll, billing, and project fields.

Restricting Time Entry on Tasks

Unless the SOAP web services user is an administrator or the employee specified on the task, the user will not be able to set the reminderType and reminderMinutes fields on a task record. If the user attempts to set these fields, the values specified will not be saved.

In the UI, you can set the Check the Limit Time to Assignees box to restrict time entry against this job. When you check this box, only assigned resources can enter time for this job's tasks.

Setting Start and End Times for Timed Tasks

In SOAP web services the startTime and endTime field are not exposed. Therefore, to set start and end times for a timed task, users must first set the timedEvent field to TRUE. Then the time component of the DateTime value that is specified in startDate will be set for startTime, and the time component of the DateTime value that is specified in endDate will be set for endTime.

Note that the fields reminderMinutes and reminderType are also only settable if timedEvent is set to TRUE.

Contacts Sublist

TaskContactList, which lists contacts and companies related to each task, does not have a unique key field, so it can include duplicated values.

If you set the ReplaceAll preference to True for a write to the sublist, and a value that you submit matches two nonunique existing values, an error is thrown, because it is not clear which existing value to match. If a value you submit matches a unique row, the row is preserved and no error is thrown.

Code Sample

The following sample shows how to add a task to a job record.

Java

          public void addTaskToJob() throws RemoteException {
                this.login(true);
 
                RecordRef custRef = new RecordRef();
                custRef.setInternalId("95");
                custRef.setType(RecordType.job);
 
                Task task = new Task();
                task.setCompany(custRef);
                task.setTitle("Race Car Tuning");
                task.setMessage("Includes baseline dyno, 5 hours tuning session & turbo upgrade.");
 
                WriteResponse response = _port.add(task);
                
                if (response.getStatus().isIsSuccess()) {
                        _console.info("\nThe following task was added successfully: " + ((RecordRef) response.getBaseRef()).getInternalId());
                } else {
                        _console.error("The task was not added:", true);
                        _console.error(getStatusDetails(response.getStatus()));
                }
        } 

        

General Notices