@gsb-core/mcp-docs/src/docs/iterateTask.ts

Documentation for GSB MCP implementations

/**
 * Documentation for the iterateTask operation
 */

/**
 * Returns documentation for the iterateTask operation
 * @return {string} markdown documentation
 */
export function iterateTaskDocs(): string {
  return `
# IterateTask Operation

## 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

\`\`\`json
{
    "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

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

## Example Usage

### Approve a Task

\`\`\`typescript
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

\`\`\`typescript
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

\`\`\`typescript
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.
`;
}

/**
 * Returns a brief summary of the iterateTask operation.
 * @return {string} A short description of the function.
 */
export function iterateTaskSummary(): string {
  return `
**Purpose**: Advances or provides input to tasks within running workflows.

**When to use**:
- Approving/rejecting workflow tasks
- Providing data to waiting tasks
- Human interaction points in workflows
- Controlling workflow execution paths

**Inputs**:
- request: Object with taskId, action, and optional input data
- token (optional)
- tenantCode (optional)

**Returns**: Updated task and workflow status.

**Effects**: Changes task state, may affect workflow progression.
`;
}

export default iterateTaskDocs;