AddFlowTaskDef

# AddFlowTaskDef API

Adds a task definition to a specified step of an existing workflow definition. The entire task configuration — name, deadline, assignees, permissions, requirements, and instructions — is passed as a single XML string in the TaskDefXML parameter.

The workflow definition must be in inactive (deactivated) state. Multiple tasks can be added to the same step; each call adds one task to the step.

Endpoint¶

/srv.asmx/AddFlowTaskDef

Methods¶

• GET /srv.asmx/AddFlowTaskDef?authenticationTicket=...&DomainName=...&FlowName=...&StepNumber=...&TaskDefXML=...
• POST /srv.asmx/AddFlowTaskDef (form data)
• SOAP Action: http://tempuri.org/AddFlowTaskDef

Parameters¶

TaskDefXML Structure¶

The TaskDefXML parameter must be a valid XML document whose 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¶

<root success="true" />

Error Response¶

<root success="false" error="[901] Session expired or Invalid ticket" />

Required Permissions¶

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

Example¶

POST Request¶

POST /srv.asmx/AddFlowTaskDef 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
&TaskDefXML=%3Ctaskdef+TaskName%3D%22LegalReview%22+DeadLine%3D%2272%22+...%2F%3E

GET Request¶

GET /srv.asmx/AddFlowTaskDef
    ?authenticationTicket=3f7a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c
    &DomainName=Corporate
    &FlowName=Document+Approval
    &StepNumber=1
    &TaskDefXML=%3Ctaskdef+TaskName%3D%22LegalReview%22+DeadLine%3D%2272%22+...%2F%3E
HTTP/1.1
Host: yourserver

Notes¶

• The workflow definition must be inactive before task definitions can be added. Use DeactivateFlowDef if the workflow is currently active.
• The TaskDefXML value must be URL-encoded when sent via GET or form-encoded POST.
• TaskName follows the same validation rules as step names: alphanumeric only, maximum 32 characters.
• DeadLine is required and must be greater than 0. The API will return an error if DeadLine is 0.
• instruction is required and must not be empty.
• SupervisorNotificationOnDue (in hours) combined with ReminderTimeSpan must not exceed the DeadLine value, otherwise validation will fail.
• If StepNumber does not match any existing step, the API returns success but no task is added (the loop finds no matching step). Always verify step numbers with GetFlowDef first.
• Multiple tasks can be added to the same step by calling this API repeatedly.

Related APIs¶

• AddFlowStepDef – Add a step to the workflow definition before adding tasks.
• AddFlowStepDef1 – Add a step with an on-start folder move.
• CreateFlowDef – Create the workflow definition.
• DeactivateFlowDef – Deactivate an active workflow before modifying it.
• DeleteFlowTaskDef – Delete a task definition from a workflow step.
• GetFlowDef – Retrieve the full workflow definition including steps and tasks.

Error Codes¶