iterateTask() — Workflow Service

General Description

The iterateTask operation advances a workflow task to its next state or provides input to a waiting task.

Detailed Description

This operation allows you to interact with tasks in running workflows, particularly human tasks or tasks that require external input. It can be used to approve or reject tasks, provide data to waiting tasks, or trigger the next step in a workflow. This is essential for workflows that include human approvals, decision points, or tasks that need to wait for external events.

Input Parameters

Parameter	Type	Required	Description
request	object	Yes	The task iteration request object specifying the task to interact with and the action to take.
token	string	No	Authentication token for your request. If not provided, the system will use the default API key from environment variables.
tenantCode	string	No	Tenant code to specify which tenant's data to access. If not provided, the system will extract it from the token or use the default tenant code from environment variables.

Request Object Structure

Property	Type	Required	Description
taskId	string	Yes	The ID of the task to iterate.
action	string	Yes	The action to perform on the task (e.g., "approve", "reject", "complete", "skip").
input	object	No	Optional input data for the task. The structure depends on what the task expects.

Response

Success Response

{
    "success": true,
    "data": {
        "taskStatus": "string",  // New status of the task
        "workflowStatus": "string",  // Current status of the parent workflow
        // Additional task-specific result data
    }
}

Error Response

{
    "success": false,
    "error": "Error message describing what went wrong"
}

Example Usage

Approve a Task

const result = await iterateTask({
  request: {
    taskId: "task-123",
    action: "approve",
    input: {
      comments: "Looks good, approved.",
      approvedBy: "user-456"
    }
  },
  token: "your-auth-token"
});

if (result.success) {
  console.log("Task approved successfully");
  console.log("Task status:", result.data.taskStatus);
  console.log("Workflow status:", result.data.workflowStatus);
} else {
  console.error("Error:", result.error);
}

Reject a Task with Reason

const result = await iterateTask({
  request: {
    taskId: "task-123",
    action: "reject",
    input: {
      reason: "Budget exceeds department limit",
      suggestedChanges: "Please reduce the amount or get additional approval",
      rejectedBy: "user-456"
    }
  },
  token: "your-auth-token"
});

Provide Data to a Waiting Task

const result = await iterateTask({
  request: {
    taskId: "task-456",
    action: "complete",
    input: {
      shippingCarrier: "FedEx",
      trackingNumber: "1234567890",
      estimatedDelivery: "2023-12-15"
    }
  },
  token: "your-auth-token"
});

Additional Information

• The iterateTask operation is used to interact with tasks in running workflows.
• Common actions include:
  • "approve": Approve a task that requires approval
  • "reject": Reject a task that requires approval
  • "complete": Mark a task as completed and provide any required data
  • "skip": Skip a task (if allowed by the workflow)
  • "reassign": Reassign the task to another user or role
• The available actions and required input depend on the specific task type and configuration.
• Tasks can be part of:
  • Approval workflows
  • Multi-step business processes
  • Data collection workflows
  • Decision workflows
• The operation returns the new status of the task and the current status of the parent workflow.
• Access permissions are enforced based on the provided token.
• Users can only iterate tasks they have permission to access.
• For starting new workflows, use the startWorkflow operation instead.
• For running simple workflows synchronously, use the runWorkflow operation instead.