Skip to main content
Ask ChatGPT

Working With Tasks

Simple Tasks - Overview​

Simple Tasks are tasks created using the POST /api/simple-tasks route. This API supports creating normal tasks (not review tasks) for a project and replicates the functionality of the "New Simple Task" button in the UI.

Supported Fields​

FieldRequiredDefault ValueDescription
ProjectIdYesN/AID of the project for the task.
TitleNo"New Task"Name of the task.
DescriptionNonullDescription of the task.
Begin DateYes (2/3)*Project timezone date 9:00 AMStart date/time (YYYY-MM-DDThh:mm:ss).
End DateYes (2/3)*Project timezone date 5:00 PMEnd date/time (YYYY-MM-DDThh:mm:ss).
Estimated DurationYes (2/3)*1 dayDuration between begin and end dates.
Start TypeNoASAPTask start type (e.g., FixedBegin, FixedEnd).
Task StatusNoProjectedStatus of the task (e.g., Draft, Assigned).
Work ScheduleNoDefault CalendarWork schedule for the task.
Auto CloseNoNoAutomatically close the task.
Allow RemoveNoYesAllow removing the task.
Allow DelegateNoNoDetermines if the task is allowed to be delegated to other people.
AssigneeYesN/AUser or role assigned to the task.

At least two of the following fields must be provided: Begin Date, End Date, or Estimated Duration.

Additional Details​

Required Fields​

  • Fields not marked as required will default to their respective values if not specified.
  • Invalid or missing required fields will result in errors.

Limitations​

  • The predecessor task is always set to "start".
  • Attributes like "insert before" or "insert after" are not supported.

Domain Rights​

To use this API, users must have one of the following:

  1. Project Rights: Edit, Task Insert, View, and Activity Edit Access.
  2. Integration Rights: Edit, Task Insert, View, and API Access.
  3. System Administration Access.

Field-Specific Details​

Task Status​

  • Field Name: workFlowTaskStatus.
  • Default Value: Projected.
  • Values:
    • Draft (1), Projected (2), Pending (3), Assigned (4), InProcess (5), Closed (7), Cancelled (8).
  • Status restrictions depend on the project status.
    • For example, Draft projects only allow task statuses Draft, Cancelled, or Removed.

Begin Date / End Date​

  • Field Names: beginDate / endDate.
  • Default:
    • Begin: Project timezone date 9:00 AM.
    • End: Project timezone date 5:00 PM.
  • Validation:
    • At least two fields (Begin Date, End Date, or Duration) must be specified.
    • Invalid date formats or endDate < beginDate will result in errors.

Estimated Duration​

  • Field Name: EstimatedDuration.
  • Default Value: 1 day (8 hours).
  • Formats Supported:
    1. Total minutes (e.g., "EstimatedDuration": 1200).
    2. Days, hours, and minutes (e.g., "enteredEstimatedDurationDay": 1, "enteredEstimatedDurationHour": 2).

Example Errors​

  • Missing ProjectId: "ProjectId cannot be null".
  • Negative duration: "EnteredEstimatedDurationMinute contains an invalid value".
  • Mismatch in BeginDate, EndDate, and EstimatedDuration: "The input BeginDate, EndDate, and EstimatedDuration do not match!".

Example Request​

{
    "ProjectId": 12345,
    "Title": "New Task",
    "description": "Task description",
    "beginDate": "2023-07-10T09:00:00",
    "endDate": "2023-07-10T17:00:00",
    "EstimatedDuration": 480,
    "startType": 1,
    "workFlowTaskStatus": 2,
    "Assignee": {
        "UserId": 67890,
        "EstimatedWork": "1:0:0"
    }
}
warning

If the request contains a negative estimated Duration, the route will throw an exception. For example, the following data would result in the response containing an error that reads “EnteredEstimatedDurationMinute contains an invalid value. Only positive numbers are allowed”:

{
    "enteredEstimatedDurationHour": 5,
    "enteredEstimatedDurationMinute": -2,
    "enteredEstimatedDurationDay": 2
}

Task Configuration Fields​

Work Schedule (Default: Default Calendar)​

  • Field Name: workScheduleId
  • Description: The calendar ID used for the task.
  • Details:
    • Default: Default Calendar (ID = 1).
    • Custom calendar IDs can be created in the Aprimo UI under Work Schedules.
    • If an invalid calendar ID is provided, the API will return:
      "The 'WorkScheduleID(xxxx)' specified does not exist."

Auto Close (Default: No)​

  • Field Name: autoClose
  • Description: Determines if a task automatically closes upon assignment.
  • Values:
    • autoClose: 0 → Auto Close = No
    • autoClose: 1 → Auto Close = Yes
  • Details:
    • If autoClose = 1, the fields Workgroup Action, Auto Accept, Allow Delegation, and Assignees are ignored.
    • Valid values: 0 or 1. Invalid values return:
      "AutoClose contains an invalid value. Only 'No' (0) and 'Yes' (1) are allowed."

Workgroup Action (Default: Any May Close)​

  • Field Name: workGroupActionID
  • Description: Defines the close pattern for the task.
  • Values:
    • 1 → One Must Close
    • 2 → Any May Close
    • 3 → All Must Close
  • Details:
    • If workGroupAction = One Must Close, Auto Accept should not be specified.
    • If workGroupAction = Any May Close or All Must Close, Auto Accept can be specified.

Auto Accept (Default: No)​

  • Field Name: autoAccept
  • Description: Determines if the task is automatically accepted by the assignee.
  • Values:
    • autoAccept: 0 → Auto Accept = No
    • autoAccept: 1 → Auto Accept = Yes
  • Details:
    • Valid values: 0 or 1. Invalid values return:
      "AutoAccept contains an invalid value. Only 'No' (0) and 'Yes' (1) are allowed."

Allow Delegation (Default: No)​

  • Field Name: canDelegate
  • Description: Specifies if the task can be delegated to others.
  • Values:
    • true → Delegation Allowed
    • false → Delegation Not Allowed
  • Details:
    • If canDelegate: false, the response always returns canDelegate: false.
    • If canDelegate: true, it will return true only if the user is an assignee and the task is in Assigned or In Process status.

Allow Remove (Default: Yes)​

  • Details:
    • Read-only field.
    • Always returns 1 (Allow Remove).

Assignee (Required)​

  • Field Name: Assignee
  • Description: A collection specifying the users, groups, or roles assigned to the task.
  • Details:
    • Supported formats:
      1. "taskRoles": [] → Supports roleID and userID.
      2. "assignees": [] → Supports only userID.
    • Only one format can be used per request. If both are specified, the API will return:
      "Only one of the following Task fields is allowed: Assignees and TaskRoles."
    • Each assignee must include:
      • Estimated Work (Default: 0 days, 0 hours, 0 minutes).
      • userID or roleID.

Estimated Work Formats​

  1. Total Minutes:
   "estimatedWork": 630
  1. Days, Hours, Minutes
"enteredEstWorkDay": 1,
"enteredEstWorkHour": 2,
"enteredEstWorkMin": 30

Invalid values (e.g., negative durations) will result in errors: "EnteredEstimatedDurationMinute contains an invalid value. Only positive numbers are allowed."

Simple Tasks - Sample JSON​

Below is an example of a request body to create a task with all fields specified:

{
   "name": "NAMESimple-NonDefault-AssignedTask",
   "description": "DESSimple-NonDefault-AssignedTask",
   "ProjectId": "{{InProcessProjectId}}",
   "startType": "{{startTypeASAP}}",
   "workFlowTaskStatus": "{{taskStatusAssigned}}",
   "workScheduleId": 1,
   "autoClose": 1,
   "workGroupActionId": 1,
   "autoAccept": 0,
   "canDelegate": false,
   "canSkip": 0,
   "taskRoles": [
      {
         "userId": "{{userId}}",
         "enteredEstWorkDay": "{{enteredEstWorkDay1}}",
         "enteredEstWorkHour": "{{enteredEstWorkHour1}}",
         "enteredEstWorkMin": "{{enteredEstWorkMin1}}"
      },
      {
         "userId": "{{groupId}}",
         "enteredEstWorkDay": "{{enteredEstWorkDay2}}",
         "enteredEstWorkHour": "{{enteredEstWorkHour2}}",
         "enteredEstWorkMin": "{{enteredEstWorkMin2}}"
      }
   ],
   "beginDate": "2018-07-10T09:00:00",
   "enteredEstimatedDurationHour": 2,
   "enteredEstimatedDurationMinute": 2,
   "enteredEstimatedDurationDay": 2
}

Key Details:​

  • ProjectId: ID of the project for which the task is created.
  • startType: Specifies when the task starts (e.g., ASAP).
  • workFlowTaskStatus: Task status (e.g., Assigned, Projected).
  • workScheduleId: ID of the work schedule (default = 1 for Default Calendar).
  • autoClose: Automatically close the task upon assignment (1 = Yes, 0 = No).
  • taskRoles: Collection of assignees with estimated work specified as days, hours, and minutes.
  • beginDate: Start date of the task (YYYY-MM-DDThh:mm:ss format).
  • enteredEstimatedDurationDay/Hour/Minute: Duration of the task in days, hours, and minutes.

Task Delegation​

To delegate a task, use the POST /api/tasks/{taskid}/delegate route.

warning

A task can not be delegated to the user making the delegation request.

Request Body Format​

{
   "taskAssigneeId": "{{original_task_assignee_id}}",
   "newUserId": "{{user_id}}"
}

Key Details:​

  • taskAssigneeId: The ID of the original task assignee.
    • This can be retrieved via the GET /api/tasks/{taskid} route.
  • newUserId: The ID of the user to whom the task is being delegated.

Task Uploads - Attachments​

Uploading attachments to a task involves multiple steps. These steps assume the task is in In Process status and has an open upload slot.

Steps to Upload an Attachment​

Step 1: Get the documentId for the Upload Slot​

  • When a task has an open upload slot, it is represented by a documentId.
  • Perform a GET /api/tasks/{taskId}/document-uploads to retrieve the documentId required for the upload.

Step 2: Upload the File to Aprimo​

  • Follow the File Upload Process instructions up to the Combining File Chunks step.
  • Note the fileId and filename used in the upload.

Step 3: Create the Attachment​

  • Use the POST /api/tasks/{taskId}/document-uploads/{documentId}/attachments route to create the attachment.
    • This route automatically sets information such as activityId, simplifying the data required.
  • Request Body:
  {
      "title": "Task Document Upload - Example",
      "description": "Optional description for the task attachment"
  }
warning
  • Do not include objectId or objectTypeId in the request body; these are set automatically by the API.
  • Additional attachment fields can be found at /api/attachments/metadata.

Step 4: Create the Attachment Version​

Instead of using the /api/attachments/{id}/versions route, create the attachment version by calling:
POST /api/tasks/{taskId}/document-uploads/{documentId}/attachments/{attachmentId}/versions

Request Body Example​

{
  "FileName": "blue-earphones-equipment-164880.jpg",
  "FileId": "d4669d44-4335-4d77-acca-67ed4d3142fb",
  "isDefaultVersion": true,
  "versionType": 3
}

Ensure you use the attachmentId retrieved after creating the attachment in Step 3.

Key Details​

  • FileName: The name of the file used in Step 2.
  • FileId: The unique identifier for the file from Step 2.
  • isDefaultVersion: Marks the version as the default (true or false).
  • versionType: Indicates the version type (e.g., 3).

Step 5: Associate the Attachment Version to the Upload Slot​

Use the PUT /api/tasks/{taskId}/document-uploads/{documentId}/upload-document route to associate the uploaded document version with the task.

Request Body Example​

{
  "versionId": "{{attachmentVersionId}}"
}

This call links the document upload slot to the task, completing the attachment process.

Key Details​

  • versionId: The version ID obtained from the response in Step 4.