UpdateWorkflowTaskDef API¶

Updates an existing task definition within a step of an inactive workflow definition. The entire updated task configuration — name, deadline, assignees, permissions, requirements, and instructions — is passed as a single XML string in the TaskDefXML parameter, replacing the current values.

The workflow definition must be in inactive (deactivated) state. Use DeactivateFlowDef first if the workflow is currently active.

Endpoint¶

/srv.asmx/UpdateWorkflowTaskDef

Methods¶

• GET /srv.asmx/UpdateWorkflowTaskDef?authenticationTicket=...&domainName=...&flowName=...&stepNumber=...&taskDefId=...&taskDefXML=...
• POST /srv.asmx/UpdateWorkflowTaskDef (form data)
• SOAP Action: http://tempuri.org/UpdateWorkflowTaskDef

Parameters¶

TaskDefXML Structure¶

The taskDefXML parameter uses the same XML format as AddFlowTaskDef. The root element carries the task attributes and may contain child elements for permissions, requirements, the instruction text, and the assignee list.

Root element attributes¶

Child elements¶

<instruction> (required) Contains the plain-text instructions shown to the assignee.

<instruction>Please review and approve the document before the deadline.</instruction>

<Permissions> (optional) Grants the assignee additional task-level permissions beyond simple completion. Rows that are omitted, or have an unreadable Value, are treated as not granted.

<Permissions>
  <Permission Name="EditDocument"    Value="True" />
  <Permission Name="Postpone"        Value="True" />
  <Permission Name="ChangeFinishdate" Value="False" />
  <Permission Name="ChangePriority"  Value="False" />
  <Permission Name="EditNextStep"    Value="False" />
  <Permission Name="EditAllSteps"    Value="False" />
</Permissions>

<AssigneeList> (optional) Specifies users, user groups, and/or special roles assigned to the task.

<AssigneeList>
  <Users>
    <user UserID="101" />
    <user UserID="102" />
  </Users>
  <UserGroups>
    <group GroupID="55" />
  </UserGroups>
  <SpecialUserRoles>
    <SpecialUserRole RoleId="-5" />
  </SpecialUserRoles>
</AssigneeList>

Only -5 (document owner at submit time) and -8 (submitter) are accepted; other ids are silently ignored. Only children of <SpecialUserRoles> are read; the element name does not matter.

<Requirements> (optional) Specifies additional actions the assignee must complete before the task can be marked as done.

<Requirements>
  <Requirement Name="Approval" RefObjectId="0" Definition="" />
  <Requirement Name="LastestVersionRead" RefObjectId="0" Definition="" />
</Requirements>

Valid Name values for requirements:

Complete TaskDefXML example¶

<taskdef
    TaskName="LegalReview"
    DeadLine="72"
    RequiredAssigneeCount="0"
    SuperVisorId="0"
    SupervisorNotificationOnDue="0"
    Priority="5"
    AllowedStartTimeSpan="0"
    ReminderTimeSpan="24"
    righttype="2"
    OnCompleteNotice="False">
  <instruction>Please review the document for legal compliance and approve or reject it before the deadline.</instruction>
  <Permissions>
    <Permission Name="EditDocument"    Value="False" />
    <Permission Name="Postpone"        Value="True"  />
    <Permission Name="ChangeFinishdate" Value="False" />
    <Permission Name="ChangePriority"  Value="False" />
    <Permission Name="EditNextStep"    Value="False" />
    <Permission Name="EditAllSteps"    Value="False" />
  </Permissions>
  <AssigneeList>
    <Users>
      <user UserID="101" />
    </Users>
  </AssigneeList>
  <Requirements>
    <Requirement Name="Approval" RefObjectId="0" Definition="" />
  </Requirements>
</taskdef>

Response¶

Success Response¶

<response success="true" error="" errorCode="0" />

Error Response¶

<response success="false" error="Session expired or invalid ticket" errorCode="4010" />

Required Permissions¶

The calling user must be a workflow supervisor, a domain/library manager, or a system administrator.

Example¶

POST Request¶

POST /srv.asmx/UpdateWorkflowTaskDef HTTP/1.1
Host: yourserver
Content-Type: application/x-www-form-urlencoded

authenticationTicket=3f7a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c
&domainName=Corporate
&flowName=Document+Approval
&stepNumber=1
&taskDefId=305
&taskDefXML=%3Ctaskdef+TaskName%3D%22LegalReview%22+DeadLine%3D%2272%22+...%2F%3E

GET Request¶

GET /srv.asmx/UpdateWorkflowTaskDef
    ?authenticationTicket=3f7a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c
    &domainName=Corporate
    &flowName=Document+Approval
    &stepNumber=1
    &taskDefId=305
    &taskDefXML=%3Ctaskdef+TaskName%3D%22LegalReview%22+DeadLine%3D%2272%22+...%2F%3E
HTTP/1.1
Host: yourserver

JavaScript¶

Every call answers XML with HTTP 200, success or not, so success is the thing to branch on and errorCode is the number to report.

async function call(action, params) {
  const response = await fetch(`/srv.asmx/${action}?${new URLSearchParams(params)}`);
  const root = new DOMParser()
    .parseFromString(await response.text(), 'text/xml')
    .documentElement;

  if (root.getAttribute('success') !== 'true') {
    throw new Error(`${root.getAttribute('errorCode')}: ${root.getAttribute('error')}`);
  }
  return root;
}

Replaces a task definition in place, keeping its TaskDefId. taskDefXML takes exactly the shape AddFlowTaskDef documents, six <Permission> rows included.

await call('UpdateWorkflowTaskDef', {
  authenticationTicket: ticket,
  domainName: 'Public',
  flowName: 'Invoice approval',
  stepNumber: 1,
  taskDefId: 7331,
  taskDefXML: taskDef            // the document AddFlowTaskDef shows
});

Notes¶

• Length limits in the task definition xml: TaskName 32 characters, and the Definition of each Requirement 255. A longer value is refused with 4000.
• The workflow definition must be inactive before task definitions can be updated. Use DeactivateFlowDef if the workflow is currently active.
• Use GetFlowDef to retrieve existing taskDefId values and current task configuration before calling this API.
• The taskDefXML value must be URL-encoded when sent via GET or form-encoded POST.
• The entire task definition is replaced by the supplied taskDefXML. Any attributes or child elements omitted from the XML will revert to their defaults. In particular OnCompleteNotice resets to false and righttype to 0 (No access) when omitted. GetFlowDef does not return OnCompleteNotice, and returns the right as a <RightType RightTypeId> element rather than a righttype attribute.
• DeadLine is required and must be greater than 0.
• instruction is required and must not be empty.
• SupervisorNotificationOnDue is in days relative to the task due date when the task supervisor (SuperVisorId) is notified: negative = before due (-1 = one day before), 0 = at the due date, positive = after. Only sent if SuperVisorId > 0. The same notice also goes to the workflow's supervisors (users and group members). A task without its own supervisor sends none.

Related APIs¶

• AddFlowTaskDef - Add a new task definition to a workflow step.
• DeleteFlowTaskDef - Delete a task definition from a workflow step.
• GetFlowDef - Retrieve the full workflow definition including task definition IDs.
• DeactivateFlowDef - Deactivate an active workflow before modifying it.
• ActivateFlowDef - Activate the workflow after modifications are complete.
• UpdateWorkflowStepDef - Update the name and on-start folder of a workflow step.

Error Codes¶

The errorCode values this operation returns, checked against a running server: