getTasks API

Returns a filtered list of workflow tasks based on XML search criteria. Tasks can be filtered by completion status, priority, date range, assignee, supervisor, workflow definition, document, and more. Results can be sorted by various task properties in ascending or descending order.

Endpoint

/srv.asmx/getTasks

Methods

• GET /srv.asmx/getTasks?AuthenticationTicket=...&xmlcriteria=...&SortBy=...&AscendingOrder=...
• POST /srv.asmx/getTasks (form data)
• SOAP Action: http://tempuri.org/getTasks

Parameters

XML Criteria Format

The xmlcriteria parameter accepts an XML string with <param> elements, each specifying a NAME and VALUE attribute. All filter parameters are optional - omit a parameter to skip that filter.

<criteria>
  <param NAME="TASKCOMPLETIONSTATUS" VALUE="Due" />
  <param NAME="PRIORITY" VALUE="High" />
  <param NAME="STARTDATE" VALUE="2026-01-01" />
  <param NAME="ENDDATE" VALUE="2026-12-31" />
  <param NAME="DOMAINID" VALUE="1" />
  <param NAME="ASSIGNEEID" VALUE="42" />
  <param NAME="ASSIGNEDBYID" VALUE="15" />
  <param NAME="SUPERVISORID" VALUE="10" />
  <param NAME="WORKFLOWDEFID" VALUE="5" />
  <param NAME="DOCUMENTID" VALUE="100" />
  <param NAME="FLOWID" VALUE="200" />
  <param NAME="DOCUMENTTYPE" VALUE="Invoice" />
</criteria>

Filter Parameters

TaskCompletionStatus Values

TaskPriority Values

Sort Options

The SortBy parameter accepts one of the following TaskSortOption values:

Response Structure

Success Response

<response success="true">
  <tasks>
    <Task>
      <TaskID>301</TaskID>
      <TaskName>Review Document</TaskName>
      <ShortInstruction>Please review and approve this document.</ShortInstruction>
      <StepNumber>2</StepNumber>
      <StepName>Review Step</StepName>
      <FlowID>50</FlowID>
      <FlowName>Document Approval</FlowName>
      <FlowDefID>5</FlowDefID>
      <Priority>High</Priority>
      <TaskStatus>InProgress</TaskStatus>
      <ApprovalStatus>Pending</ApprovalStatus>
      <StartDtae>2026-02-01 09:00:00</StartDtae>
      <FinishDate></FinishDate>
      <DueDate>2026-02-15 17:00:00</DueDate>
      <ShortComments></ShortComments>
      <TaskDefID>101</TaskDefID>
      <LinkedTaskID>0</LinkedTaskID>
      <AssigneeID>42</AssigneeID>
      <AssigneeType>User</AssigneeType>
      <AssigneeName>John Smith</AssigneeName>
      <AssignedByID>15</AssignedByID>
      <AssignedByName>Jane Doe</AssignedByName>
      <SuperVisorID>10</SuperVisorID>
      <SupervisorName>Admin User</SupervisorName>
      <DocumentID>1234</DocumentID>
      <DocumentName>Q1_Report.docx</DocumentName>
      <StartVersionNumber>1.0</StartVersionNumber>
      <EndVersionNumber>0.0</EndVersionNumber>
      <DocumentTypeId>3</DocumentTypeId>
      <DocumentTypeName>Report</DocumentTypeName>
      <DocumentFolderID>500</DocumentFolderID>
      <DocumentLibraryID>1</DocumentLibraryID>
      <DocumentLibraryName>Main Library</DocumentLibraryName>
      <DocumentCheckedOutByID>0</DocumentCheckedOutByID>
      <DocumentCheckedOutByName></DocumentCheckedOutByName>
      <DocumentTemplateID>0</DocumentTemplateID>
      <RedirectedFrom_UserID>0</RedirectedFrom_UserID>
      <RedirectedFrom_UserName></RedirectedFrom_UserName>
      <AdHoc>false</AdHoc>
      <DeadLine>14</DeadLine>
      <RequirementDetails>
        <Requirement>
          <Name>Approval Required</Name>
          <RequirementType>Approval</RequirementType>
          <Definition>Manager approval needed</Definition>
          <ObjectId>1</ObjectId>
        </Requirement>
      </RequirementDetails>
      <Requirements></Requirements>
      <Supervisor_NotificationOnDue>1</Supervisor_NotificationOnDue>
      <SupervisorNotificationDate>2026-02-14 09:00:00</SupervisorNotificationDate>
      <AllowedStartTimeSpan>0</AllowedStartTimeSpan>
      <AllowedStartDate></AllowedStartDate>
      <ReminderTimeSpan>1</ReminderTimeSpan>
      <ReminderDate>2026-02-14 09:00:00</ReminderDate>
      <Attachments>
        <Attachment>
          <AttachmentDate>2026-02-05 10:30:00</AttachmentDate>
          <DocumentId>1235</DocumentId>
          <WorkflowId>50</WorkflowId>
          <StepNumber>1</StepNumber>
          <StepName>Submit Step</StepName>
          <UserId>15</UserId>
        </Attachment>
      </Attachments>
    </Task>
    <!-- ... additional tasks ... -->
  </tasks>
</response>

Error Response

<response success="false" error="[ErrorCode] Error message" />

Task Element Properties

Required Permissions

• User must be authenticated (valid authentication ticket required)
• Anonymous users cannot call this API (returns insufficient rights error)
• Tasks returned are scoped to the authenticated user's permissions

Use Cases

1. Task Dashboard

   • Display all due tasks assigned to the current user
   • Show overdue tasks requiring attention

2. Workflow Monitoring

   • List all tasks for a specific workflow definition
   • Filter tasks by document or library

3. Workload Management

   • Review tasks assigned by or to a specific user
   • Filter by priority to focus on urgent items

4. Reporting

   • Query completed tasks within a date range
   • Analyze task distribution across supervisors

Example Requests

Request (GET)

GET /srv.asmx/getTasks?AuthenticationTicket=abc123-def456&xmlcriteria=%3Ccriteria%3E%3Cparam%20NAME%3D%22TASKCOMPLETIONSTATUS%22%20VALUE%3D%22Due%22%20%2F%3E%3C%2Fcriteria%3E&SortBy=DueDate&AscendingOrder=true HTTP/1.1
Host: server.example.com

Request (POST)

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

AuthenticationTicket=abc123-def456&xmlcriteria=<criteria><param NAME="TASKCOMPLETIONSTATUS" VALUE="Due" /></criteria>&SortBy=DueDate&AscendingOrder=true

Request (SOAP 1.1)

POST /srv.asmx HTTP/1.1
Content-Type: text/xml; charset=utf-8
SOAPAction: "http://tempuri.org/getTasks"

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <getTasks xmlns="http://tempuri.org/">
      <AuthenticationTicket>abc123-def456</AuthenticationTicket>
      <xmlcriteria><![CDATA[<criteria><param NAME="TASKCOMPLETIONSTATUS" VALUE="Due" /><param NAME="PRIORITY" VALUE="High" /></criteria>]]></xmlcriteria>
      <SortBy>DueDate</SortBy>
      <AscendingOrder>true</AscendingOrder>
    </getTasks>
  </soap:Body>
</soap:Envelope>

Integration Examples

JavaScript/Client-Side

async function getTasks(filters, sortBy = "DueDate", ascending = true) {
    const ticket = getUserAuthTicket();

    // Build XML criteria
    let xmlCriteria = "<criteria>";
    for (const [name, value] of Object.entries(filters)) {
        xmlCriteria += `<param NAME="${name}" VALUE="${value}" />`;
    }
    xmlCriteria += "</criteria>";

    const response = await fetch("/srv.asmx/getTasks", {
        method: "POST",
        headers: { "Content-Type": "application/x-www-form-urlencoded" },
        body: `AuthenticationTicket=${encodeURIComponent(ticket)}&xmlcriteria=${encodeURIComponent(xmlCriteria)}&SortBy=${sortBy}&AscendingOrder=${ascending}`
    });

    const xmlText = await response.text();
    const parser = new DOMParser();
    const xmlDoc = parser.parseFromString(xmlText, "text/xml");

    const root = xmlDoc.querySelector("response");
    if (root.getAttribute("success") === "true") {
        const tasks = [];
        xmlDoc.querySelectorAll("Task").forEach(task => {
            tasks.push({
                taskId: parseInt(task.querySelector("TaskID").textContent),
                taskName: task.querySelector("TaskName").textContent,
                flowName: task.querySelector("FlowName").textContent,
                priority: task.querySelector("Priority").textContent,
                taskStatus: task.querySelector("TaskStatus").textContent,
                dueDate: task.querySelector("DueDate").textContent,
                assigneeName: task.querySelector("AssigneeName").textContent,
                supervisorName: task.querySelector("SupervisorName").textContent,
                documentName: task.querySelector("DocumentName").textContent,
                instruction: task.querySelector("ShortInstruction").textContent
            });
        });
        return tasks;
    } else {
        const error = root.getAttribute("error");
        throw new Error(error);
    }
}

// Usage examples
async function displayDueTasks() {
    try {
        const tasks = await getTasks({ TASKCOMPLETIONSTATUS: "Due" }, "DueDate", true);

        console.log(`Due tasks: ${tasks.length}`);
        tasks.forEach(task => {
            console.log(`[${task.priority}] ${task.taskName} - ${task.flowName} (Due: ${task.dueDate})`);
        });
    } catch (error) {
        console.error("Failed to get tasks:", error);
    }
}

async function getHighPriorityOverdueTasks() {
    try {
        const tasks = await getTasks({
            TASKCOMPLETIONSTATUS: "OverDue",
            PRIORITY: "High"
        }, "Priority", false);

        console.log(`High priority overdue tasks: ${tasks.length}`);
        tasks.forEach(task => {
            console.log(`${task.taskName} assigned to ${task.assigneeName} (Due: ${task.dueDate})`);
        });
    } catch (error) {
        console.error("Failed to get tasks:", error);
    }
}

C# Client Usage

using (var client = new SrvSoapClient())
{
    try
    {
        // Build XML criteria for due tasks in a specific library
        string xmlCriteria = @"<criteria>
            <param NAME=""TASKCOMPLETIONSTATUS"" VALUE=""Due"" />
            <param NAME=""DOMAINID"" VALUE=""1"" />
        </criteria>";

        var response = await client.getTasksAsync(authTicket, xmlCriteria, "DueDate", true);
        var root = XElement.Parse(response.ToString());

        if (root.Attribute("success")?.Value == "true")
        {
            var tasks = root.Descendants("Task")
                .Select(t => new
                {
                    TaskId = int.Parse(t.Element("TaskID")?.Value ?? "0"),
                    TaskName = t.Element("TaskName")?.Value ?? "",
                    FlowName = t.Element("FlowName")?.Value ?? "",
                    Priority = t.Element("Priority")?.Value ?? "",
                    TaskStatus = t.Element("TaskStatus")?.Value ?? "",
                    DueDate = t.Element("DueDate")?.Value ?? "",
                    AssigneeName = t.Element("AssigneeName")?.Value ?? "",
                    DocumentName = t.Element("DocumentName")?.Value ?? ""
                })
                .ToList();

            Console.WriteLine($"Found {tasks.Count} tasks");
            foreach (var task in tasks)
            {
                Console.WriteLine($"[{task.Priority}] {task.TaskName} - {task.FlowName}");
                Console.WriteLine($"  Assignee: {task.AssigneeName} | Document: {task.DocumentName}");
                Console.WriteLine($"  Due: {task.DueDate} | Status: {task.TaskStatus}");
            }
        }
        else
        {
            var error = root.Attribute("error")?.Value;
            Console.WriteLine($"Error: {error}");
        }
    }
    catch (Exception ex)
    {
        Console.WriteLine($"Exception: {ex.Message}");
    }
}

Notes

• The xmlcriteria parameter must be valid XML. An empty criteria element <criteria></criteria> returns all tasks visible to the authenticated user.
• Filter parameters are case-insensitive for the NAME attribute (internally converted to uppercase).
• Unrecognized parameter names in xmlcriteria will cause an error response.
• Invalid enum values for SortBy, TASKCOMPLETIONSTATUS, or PRIORITY will return a descriptive error.
• The StartDtae element name in the response contains a known typo (retained for backward compatibility).
• Task requirements and attachments are dynamically loaded for each task in the result set.
• Version numbers are returned in external format (e.g., 1.0, 2.0).

Error Codes

Common error responses:

Related APIs

• getTask - Get a single task by task ID
• GetUsersTaskPerformance - Get user task performance statistics (due and overdue task counts)
• GetWorkflowStatistics - Get workflow performance statistics
• GetUsersWorkflowRoles - Get workflow roles assigned to a user
• ActivateFlowDef - Activate a workflow definition
• AuthenticateUser - Authenticate and obtain a ticket

Version History

• Available to all authenticated users
• Supports comprehensive filtering via XML criteria for flexible task queries