UpdateRunningWorkflowTaskDef API¶

Updates a task definition on a currently executing (running) workflow step. The entire updated task configuration — deadline, assignees, permissions, requirements, and instructions — is passed as a single XML string in the taskDefXML parameter, replacing the current values.

The workflow must be actively running on the document. Use UpdateWorkflowTaskDef to update task definitions on inactive workflow definitions.

Endpoint¶

/srv.asmx/UpdateRunningWorkflowTaskDef

Methods¶

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

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.

<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>
    <role RoleId="1" />
  </SpecialUserRoles>
</AssigneeList>

<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 one of:

• the supervisor of the task definition being edited (its SuperVisorId);
• a library manager of the document's library;
• an assignee with an open task in this workflow that carries EditNextStep (for the step right after that task's step) or EditAllSteps (for any later step).

Anyone else is refused with 4030. Being the workflow's supervisor, its submitter, or the system administrator does not by itself allow the edit; the system administrator can make it where they manage the library.

Example¶

POST Request¶

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

authenticationTicket=3f7a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c
&documentPath=%2FCorporate%2FContracts%2Fagreement.pdf
&workflowId=42
&stepNumber=1
&taskDefId=305
&taskDefXML=%3Ctaskdef+TaskName%3D%22LegalReview%22+DeadLine%3D%2272%22+...%2F%3E

GET Request¶

GET /srv.asmx/UpdateRunningWorkflowTaskDef
    ?authenticationTicket=3f7a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c
    &documentPath=%2FCorporate%2FContracts%2Fagreement.pdf
    &workflowId=42
    &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;
}

Rewrites a task definition of a workflow that is already running. The caller needs a task in an earlier step carrying EditNextStep or EditAllSteps - without one even the system administrator who submitted the document is refused with 4030.

await call('UpdateRunningWorkflowTaskDef', {
  authenticationTicket: ticket,
  documentPath: '/Public/Invoices/inv-1001.pdf',
  workflowId: 7332,
  stepNumber: 2,
  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 document must have an actively running workflow. Use UpdateWorkflowTaskDef to modify task definitions on inactive workflow definitions.
• The DeadLine field in taskDefXML is required and must be greater than 0.
• taskDefId must refer to a task definition in the specified stepNumber of the running workflow. Use the running workflow data to identify valid IDs.
• The entire task definition is replaced by the supplied taskDefXML. Any attributes or child elements omitted from the XML will revert to their defaults.
• SupervisorNotificationOnDue is in days relative to the task due date (negative = before due, 0 = at the due date, positive = after); it is not limited by DeadLine. ReminderTimeSpan must not exceed the DeadLine value.

Related APIs¶

• UpdateWorkflowTaskDef - Update a task definition on an inactive workflow definition.
• StopCurrentWorkflow - Gracefully stop a running workflow with notifications.
• SubmitDocumentToFlow - Submit a document to a workflow definition.
• AddFlowTaskDef - Add a new task definition to a workflow step.
• GetFlowDef - Retrieve the full workflow definition including task definition IDs.

Error Codes¶

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