​
Purpose

The Tasks resource represents an individual unit of work that progresses through a series of steps in a workflow. Tasks move from step to step within the workflow, similar to how tasks progress across columns on a Kanban board. The same task advances as the workflow executes, and its state (e.g., the current step, status, and context) is updated either automatically by the Copilotz agent or programmatically via the API. A workflow can contain multiple tasks, each following its unique progression through the workflow’s steps.

​
Resource Overview

A Task represents a work item that progresses through multiple steps within a workflow. It tracks the current state, such as the currentStep, status, and any context information required for processing. The task moves forward as each step is completed, updating its state along the way. You can programmatically update the task’s status, currentStep, and context via the API, or these fields can be managed automatically by the Copilotz agent as it executes the workflow.

​
Key Concepts

  • Workflow ID: The ID of the workflow in which the task is progressing.
  • Current Step: The ID of the step the task is currently in.
  • Task Status: The current status of the task as it progresses through the workflow.
  • External ID (extId): Optionally links the task to an external system via an external ID.
  • Context: Stores arbitrary data related to the task that can be used throughout the workflow.

​
Example

A sample Task for managing a customer support workflow, which progresses through multiple steps, might look like this:

{
  "extId": "SUPPORT_56789",  // External ID linking the task to an external support system
  "workflow": 2,  // ID of the workflow the task belongs to
  "currentStep": 1,  // Step the task is currently on
  "status": "active",  // Status of the task (active, pending, failed, etc.)
  "name": "Resolve Customer Issue",  // Name of the task
  "description": "Task to resolve a customer support issue.",
  "context": {
    "customer": "John Doe",
    "issue": "Account locked",
    "priority": "high"
  }  // Arbitrary data stored with the task, can be updated at each step
}

​
Fields

  • extId (string, optional) – The external ID for the task, used to link the task to external systems.
  • workflow (integer) – The ID of the workflow that this task belongs to.
  • currentStep (integer) – The ID of the step the task is currently in. This field progresses as the task moves through the workflow steps.
  • status (string) – The current status of the task. Possible values include:
    • active: The task is currently in progress.
    • pending: The task is waiting for a condition to be met or for an external action.
    • failed: The task encountered an error and has not been completed successfully.
    • completed: The task has been successfully completed.
  • name (string) – A human-readable name for the task, used to describe the task’s purpose.
  • description (string) – A brief explanation of the task’s objective.
  • context (object, optional) – Stores arbitrary data related to the task. The context is mutable and can be updated as the task progresses through the workflow. This field is useful for keeping track of state across multiple steps or for passing information to external systems.

​
Behavior

  • Task Progression through Steps: A task progresses through multiple steps in a workflow, similar to how tasks move across columns on a Kanban board. Each task advances based on the workflow’s logic, with the currentStep field updating accordingly. The task remains the same but moves through different steps in the workflow.

  • Automatic and Programmatic Updates: The task’s status, currentStep, and context can be updated either automatically by the Copilotz agent as the workflow progresses or manually via the API. This flexibility allows developers to manage task progression programmatically when needed.

  • Task Status: A task can transition between different statuses based on its progression through the workflow. For example, a task might move from active to pending if it requires user input or external validation, and it may move to completed when the workflow finishes successfully.

​
Usage

  • Managing Tasks Programmatically: You can update a task’s status, currentStep, and context via the API. This allows for fine-grained control over task progression and enables external systems to interact with the workflow by updating task state.

  • Automatic Task Updates by Copilotz Agent: The Copilotz agent will automatically update the task as it moves through the steps of a workflow. For example, when a step is completed, the agent will update the currentStep to the next step and adjust the status based on the outcome of the step.

  • Handling Workflow Errors: If a task encounters an error (e.g., a failed API request or invalid user input), its status can be set to failed, allowing the workflow to either retry the task or move to a designated error-handling step.

​
Example of Task Execution Across Multiple Steps

Here’s how a Task would progress through a workflow consisting of multiple steps, similar to how tasks move across columns in a Kanban board:

  1. Step 1: Gather User Information
  • Workflow: Customer Onboarding
  • Current Step: Step 1 (Collecting user information)
  • Status: Active
  • Context: Stores the user’s name and contact details.
  1. Step 2: Send Confirmation Email
  • Workflow: Customer Onboarding
  • Current Step: Step 2 (Sending confirmation email)
  • Status: Pending (waiting for email response)
  • Context: Updates to store the email confirmation status.
  1. Step 3: Complete Onboarding
  • Workflow: Customer Onboarding
  • Current Step: Step 3 (Finalizing onboarding)
  • Status: Active
  • Context: Final onboarding details.

​
Example of Creating and Updating a Task

const createTask = async (accessToken, taskData) => {
  const response = await fetch(`https://copilotz.com/rest/tasks`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${accessToken}`,
    },
    body: JSON.stringify(taskData),
  });

  if (response.ok) {
    const createdTask = await response.json();
    console.log("Task created successfully:", createdTask);
  } else {
    const error = await response.json();
    console.error("Failed to create task:", error.error.message);
  }
};

// Example task data
const taskData = {
  extId: "SUPPORT_56789",  // External ID for linking the task to external systems
  workflow: 2,  // Associated workflow ID
  currentStep: 1,  // Current step in the workflow
  status: "active",  // Initial status of the task
  name: "Resolve Customer Issue",  // Task name
  description: "Task to resolve a customer support issue.",
  context: {
    issue: "Account locked",
    priority: "high"
  }  // Arbitrary data for task context
};

createTask("your_access_token", taskData);

// Example of updating a task programmatically
const updateTask = async (accessToken, taskId, updateData) => {
  const response = await fetch(`https://copilotz.com/rest/tasks/${taskId}`, {
    method: "PUT",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${accessToken}`,
    },
    body: JSON.stringify(updateData),
  });

  if (response.ok) {
    const updatedTask = await response.json();
    console.log("Task updated successfully:", updatedTask);
  } else {
    const error = await response.json();
    console.error("Failed to update task:", error.error.message);
  }
};

// Example update data for progressing a task
const updateData = {
  currentStep: 2,  // Move to the next step
  status: "pending",  // Waiting for external action
  context: {
    emailSent: true
  }  // Update context with new information
};

updateTask("your_access_token", taskId, updateData);

​
Key Use Cases

  • Progressing Tasks Through a Workflow: Tasks automatically or programmatically progress through the workflow’s steps, with the currentStep and status fields updating to reflect their position in the process.

  • Context Management: Tasks can carry important data throughout the workflow via the context field. This data can be updated at each step to reflect the current state of the task, making it easier to track progress and pass information between steps.

  • Handling Multiple Tasks: Multiple tasks can be running simultaneously within a workflow, each at a different step. This allows for complex workflows that manage multiple independent or dependent tasks at the same time.

  • **Programmatic Updates

:** Developers can control task progression via the API, manually updating the task’s state as needed. This is useful in cases where external systems need to trigger progress or handle errors.

​
Best Practices

  • Use Context to Store Task-Specific Data: The context field should be used to store data that is important for the task’s progression. This could include user input, API responses, or any other data required for subsequent steps.

  • Handle Failures Gracefully: Ensure that tasks have error-handling logic in place. Use the status field to mark tasks as failed when errors occur and define retry or alternative steps in the workflow.

  • Monitor Task Progression: Regularly check and update the currentStep field to track task progression. This ensures that tasks move smoothly through the workflow and that any issues are detected early.