Home / Marketing Operations / REST API / Routes / Working with Tasks

Marketing Operations

Working with Tasks

Simple Tasks - Overview

Simple Tasks are a specific type of Task available in the UI. The POST api/simple-tasks route is used to create a normal task (NOT a review task) for a project. It can do almost all work of the NEW SIMPLE TASK button on task worksheet or task list.

Fields Supported by POST api/simple-tasks:

  • ProjectId — Required
  • Title (Default: New Task)
  • description (Default: null)
  • Begin Date (Default: Project timezone’s date 9AM) — Required
  • End Date (Default: Project timezone’s date 5PM)– Required
  • Estimated Duration (Default: 1:0:0 1 day 0 hour 0 minutes)– Required
  • Start Type (Default: ASAP)
  • Task Status (Default: Projected )
  • work Schedule (Default : Default Calendar)
  • Auto Close (Default: No)
  • Allow Remove (Default: Yes)
  • Workgroup Action (Default: Any May Close)
  • Auto Accept (Default: No)
  • Allow Delegation (Default: No)
  • Assignee– Required
  • The following are fields inside Assignee
  • Estimated Work (Default: 0:0:0 0 day 0 hour 0 minutes)
  • UserID or RoleID

About required fields and Default values
The required fields must be input in the request body. Unrequired fields will be defaulted if not specified. Note: For required fields beginDate, endDate, and duration, at least two of three are required.

Limitations
The predecessor task will always be “start”. This API does not support “insert before” or “insert after”. If the ‘predTaskID’ attribute is specified, it will be ignored.

Domain Rights
To use this API, user must at least have one of the three rights in the following:

  • “Project, Edit” AND “Project, Task Insert”, AND “Project, View”, AND be included on the Activity Edit Access List
  • “Project, Edit” AND “Project, Task Insert”, AND “Project, View”, AND have “Integration API, Access” right
  • System Administration Access

Simple Tasks - Field Details

ProjectId — Required

Field Name as it appears in input body: “ProjectId”

Description: This is the ID of the project you want to create the simple task within. Project Status is not required, because project status is associated with the ProjectId. Even though you do not need to specify Project Status, it’s important to know what it is, because this partly determines which fields can be updated.

Details:

  • ProjectId is required field in the input body. There are projects with various statuses in Aprimo Marketing: Draft, In Process, Pause, Cancelled, Removed, Closed, and Initialize failed.
  • If ProjectId is not specified, the “ProjectId cannot be null” exception is thrown.
  • The value of the Project Status is as follows:
    • Draft = 1
    • InProcess = 2
    • Paused = 3
    • Closed = 4
    • Cancelled = 5
    • InitializeFailed = 7

canSkip

Field Name as it appears in input body: “canSkip”

Details:

    • Input “canSkip:0” corresponds to Allow Remove = NO on UI

 

    Input “canSkip:1”, corresponds to Allow Remove=YES on UI

Task Status (Default: Projected )

Field Name as it appears in input body: “workFlowTaskStatus”

Description: the status of the created task. Its values are as follows:

  • Draft = 1
  • Projected = 2
  • Pending = 3
  • Assigned = 4
  • InProcess = 5
  • Closed = 7
  • Cancelled = 8

Details:
Task status has close relationship with Project status. The relationships are as follows:

  • For Draft project, you can only create a simple task with Task Statuses Draft, Cancelled, or Removed. You cannot create Projected, Assigned, or Pending” tasks. If you specify an illegal status, the “Only the following Workflow Task Status are allowed for new simple-tasks with a Draft Project: ‘Draft’ (1), ‘Canceled’ (8), ‘Removed’ (9)” exception is thrown.
  • For an InProcess or Paused project, you can only create simple task with Task Statuses Cancelled, Removed, Projected, Assigned, or Pending. You cannot create a Draft task. If you specify an illegal status, the “Only the following Workflow Task Status are allowed for new simple-tasks with a InProcess Project: ‘Projected’ (2), ‘Assigned’ (4), ‘Canceled’ (8), ‘Removed’ (9)” exception is thrown.
  • For a Cancelled or Removed or Initialize Failed project, you can not create simple task. If you try to create a simple task on one of these projects, the “You cannot add Task to Project that has the status of Closed or Cancelled or InitializeFailed or Initializing or StartFailed or Starting” exception is thrown.

Task Start Type (Default: ASAP)

Field Name as it appears in input body: “startType”

Description: The start type of the create task, as follows:

  • FixedBegin = 2
  • ASAP = 1
  • FixedEnd = 3
  • StartNoEarlierThan = 4
  • StartNoLaterThan = 6

Details: Task Start Type has a close relationship with the Task status. The relationships are as follows:

  • For a Projected task, a Simple Task can only be created with the following start types: As soon as possible, Start No Earlier Than, and Start No Later Than.
  • For an Assigned, Cancelled, or Removed task, a Simple Task can only be created with the following start types: As soon as possible, Fixed Begin, Fixed End, Start No Earlier Than, and Start No Later Than.
  • For a Pending task, a Simple Task can only be created with the following start types: Fixed Begin, and Fixed End.

Title (Default: New Task)

Field Name as it appears in input body: “name”

Description: The task name.

Description (Default: null)

Field Name as it appears in input body: “description”.

Description: The description of the task.

Begin Date (Default: Project timezone’s date 9:00 AM. Required)

Field Name as it appears in input body:”beginDate”. The format should be “YYYY-MM-DDThh:mm:ss”. e.g.”beginDate”: “2018-07-10T09:00:00”

Description: The begin date of the task.

Details:

    • duration = end Date – begin Date.
    • For an Assigned task, the beginDate and endDate are always current date/time.
    • For a Cancelled or Removed task, the beginDate = endDate, and the date of the task is the project date.
    • For a Projected, Draft or Pending tasks with startType=ASAP, the beginDate is the project start date/time. endDate is calculated as beginDate + duration.
    • For a Projected or Draft task, when startType is something other than ASAP, the beginDate and endDate take their values from the API request body.
    • In the request body, at least two of the fields beginDate/endDate/duration must be specified. The third field is calculated from the two specified as follows:
      • If the request contains beginDate and duration, the endDate = beginDate + duration
      • If the request contains beginDate and endDate, the duration = endDate – beginDate
      • If the request contains beginDate, endDate, and duration, the values must satisfy the equation: endDate = beginDate + duration. If the input does not satisfy this equation, the default task will be created, but the route will return a response that reads “The input BeginDate, EndDate and EstimatedDuration do not match!”

End Date (Default: Project timezone’s date 5:00 PM. Required)

Field Name as it appears in input body: “endDate”. The format should be “YYYY-MM-DDThh:mm:ss”, e.g.”endDate”: “2018-07-11T17:00:00”

Description: The end date of the task

Details:

      • If endDate < beginDate, the call will fail with the error “BeginDate() should not be greater than EndDate().”

 

      • If endDate or beginDate are specified with an invalid format, the call will fail with the error：“Please check the data sent. (, .”

Estimated Duration (Default: 1 day 0 hour 0 minutes. Required)

Field Name as it appears in input body: two methods, see below.

Description: The duration between the begin date and of the task. This is different than estimated work.

Details:
The API support two formats of this field in the input body:

      • The total minutes of the duration. EstimatedDuration = enteredEstimatedDurationDay * 8 +enteredEstimatedDurationHour * 60 + enteredEstimatedDurationMinute （assumes one day contains 8 hours. E.g. “EstimatedDuration”：1200
      • The days, hours, and minutes of the duration.
	"enteredEstimatedDurationHour": 2,
	"enteredEstimatedDurationMinute": 1,
	"enteredEstimatedDurationDay": 2

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

work Schedule (Default : Default Calendar)

Field Name as it appears in input body: “workScheduleId”

Description: The calendar ID the program uses.

Details:

      • The default is the the Default Calendar, CalendarID = 1.
      • A new calendar ID can be created with the Aprimo UI by viewing the details of a Project, selecting Work Schedules, then clicking NEW.
      • Valid values of this field are calendar IDs from the project under which the task is created. If an invalid calendar ID is specified in the request, an exception is thrown that reads：”The ‘WorkScheduleID(xxxx)’ specified does not exist.”

Auto Close (Default: No)

Field Name as it appears in input body: “autoClose”

Description: If autoclose = yes, the task will be closed immediately once the task is assigned. Input is as follows:

      • “autoclose:0”. In the UI, this is equivalent to autoclose = NO
      • “autoclose:1”. In the UI, this is equivalent to autoclose = YES

Details:

      • When autoclose = yes in the UI, Workgroup Action, Auto Accept, Allow Task Delegation, and Assignees are not displayed. Thus, these fields will be ignored if specified in the request body.
      • When auto close = no in the UI, Workgroup Action, Auto Accept, Allow Task Delegation, and Assignees are displayed. Thus, these fields should be specified in the request body.
      • The valid value of this field is either 0 or 1. If an invalid value is specified, an exception is thrown that reads “AutoClose contains an invalid value. Only the following values are allowed: ‘No’ (0), ‘Yes’ (1), ‘Milestone’ (2)”. ‘Milestone’ is unused.

Workgroup Action (Default: Any May Close)

Field Name as it appears in input body: “workGroupActionID”

Description: The close pattern of the task. Valid values are as follows:

      • OneMustClose = 1
      • AnyMayClose = 2
      • AllMustClose = 3

Details:

      • When the workgroup action = One Must Close in the UI, the Auto Accept field is not displayed. Thus, Auto Accept should not be specified on the request.
      • When the workgroup action = All Must Close or Any May Close in the UI, the Auto Accept field is displayed. Thus AutoAccept should be specifed on the request if something other than the default is desired.

Auto Accept (Default: No)

Field Name as it appears in input body: “autoAccept”

Description: If autoAccept = yes, the assignee will accept the task automatically once the task is assigned. Valid values are:

      • autoAccept:0. In the UI, this is equivalent to autoAccept = NO
      • autoAccept:1. In the UI, this is equivalent to autoAccept = YES

Details:

      • The valid value of this field is either 0 or 1. If an invalid value is specified, an exception is thrown that reads “AutoAccept contains an invalid value. Only the following values are allowed: ‘No’ (0), ‘Yes’ (1).”

Allow Delegation (Default: No)

Field Name as it appears in input body: “canDelegate”

Description: Determines if the task is allowed to be delegated to other people. Valid values are true and false.

Details:

      • Valid values of this field are true and false. If an invalid value is specified on the request, the value will be ignored.
      • If “canDelegate:false” is specified in the request, the response always returns “canDelegate:false”.
      • If “canDelegate:true” is specified in the request, the response only returns “canDelegate:true” when the API user is an assignee of the task and the workstatus is assigned or in process. Otherwise, it returns “canDelegate:false”.

Allow Remove (Default: Yes)

Details:
This is readonly field, so will be ignore if included in the request. The value will always be 1 (allow removal).

Assignee — Required

Field Name as it appears in input body: “Assignee”

Description:
Assignee is a required field in the request body. It is a collection which specifies users, groups or roles. This route supports two formats for the Assignee field: “taskRoles”:[] or “assignees”:[]. You must input only one of the two.

This route also supports two formats for specifying estimated work.

      • The total minutes of the estimatedWork. estimatedWork is calculated as = enteredEstWorkDay * 8 +enteredEstWorkHour * 60 + enteredEstWorkMin （the assumption is that one day has 8 hours）
        “estimatedWork”：630
      • The day, hour, minutes of the Estimated Work.
"enteredEstWorkDay": 1,
"enteredEstWorkHour": 2,
"enteredEstWorkMin": 30

Field meaning:
Assignee is a required field in the input body. It is a collection which includes a user or a group or a role. Each specifc user or group or role must include the following two parts.

        • Estimated Work (Default: 0 day 0 hour 0 minutes)
        • UserId or RoleId

Details:

      • The field name for user and group are both “userID”. The field name for role is “roleID”
      • “taskRoles”:[] supports “roleID” and “userID”. “assignees”:[] only supports “userID”.
      • “taskRoles”:[] and “assignees”:[] can NOT both be specified on the same request.
        • if “taskRoles”:[] and “assignees”:[] are both specified on one request, the following exception is thrown: “Only one of the following Task fields is allowed: Assignees and TaskRoles”.
        • If neither “taskRoles”:[] nor “assignees”: [] is specified in the request, the following exception is thrown: “The Assignees or TaskRoles specified does not exist”.

Simple Tasks - Sample JSON

To create a task with all fields in the input body:

{
   "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
}

Task Delegation

In order to delegate a task, call the POST /api/tasks/{taskid}/delegate route.

The body must be in the following format:

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

The taskAssigneeId can be found via the GET /api/tasks/{taskid} route.

 

Task Uploads - Attachments

Uploading attachments to a task is a multi-step process involving multiple routes detailed out below. These steps assume you are working with a task that is already in an In Process status and has a slot for an attachment upload.

Step 1: Get the documentId for the upload slot.

When a task is created with an open upload slot, the slot is represented by a documentId. This documentId will be needed in a later call to associate a file upload to the task.

Perform a GET /api/tasks/{taskId}/document-uploads call to find the documentId needed.

Step 2: Upload your file to Aprimo by following the instructions on the File Upload Process article through the Combining File Chunks step. Note the fileId and filename you used.

Step 3: Create the attachment for the task.

Rather than using the /api/attachments route to create the attachment, use the POST /api/tasks/{taskId}/document-uploads/{documentId}/attachments route, which will automatically set information for you such as the activityId, simplifying the data you need to pass in to create the attachment.

In the body, at a minimum, pass in the title field. Other fields may be passed in, such as Description. Do not pass in objectId or objectTypeId, as these will be automatically set by the API. Additional attachment fields are defined at /api/attachments/metadata.

{
    "title": "Task Document Upload - Tarun 2",
}

Note the resulting attachment Id.

Step 4: Create the attachment version

Rather than calling the /api/attachment/{id}/versions route to create the version, call POST /api/tasks/{taskId}/document-uploads/{documentId}/attachments/{attachmentId}/versions to create the attachment version.  At a minimum, pass in the FileId and FileName used during Step 2, for example:

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

Note the version Id from the response.

Step 5: Associate the attachment version to the upload document slot.

Finally, call PUT /api/tasks/{taskId}/document-uploads/{documentId}/upload-document with a body of

{
	"versionId": <<attachmentVersionId>>
}

This will associate the document upload with the task.