updateTaskStatus

The updateTaskStatus method reports the outcome of one taskRunner invocation back to the platform. Call it before returning from your handler. The platform uses this to surface task health in the connector UI and to decide whether to retry the task.

For failures, choose the failureReason that best describes the cause. The platform may treat different reasons differently: authentication-related reasons typically surface as admin-actionable errors in the connector UI, while retryable reasons trigger silent retries.

Method signature

1
2
updateTaskStatus(request: TaskStatusUpdateRequest): Promise<TaskStatusUpdateResponse>

Parameter: request

• Type: TaskStatusUpdateRequest
• Required: Yes
• Description: The status update request, threaded with the current scan and execution context.

1
2
{
  scanId: string;            // From the current TaskRunnerPayload
  taskExecutionId: string;   // From the current TaskRunnerPayload
  status: 'success' | 'failure';
  task: TaskStatusUpdateTask;
  failureReason?: FailureReason; // Required when status is 'failure'
  connectionId: string;      // From the current TaskRunnerPayload
}

TaskStatusUpdateTask

1
2
{
  taskId: string;            // From the current TaskRunnerPayload
}

failureReason values

The retry and escalation behavior is decided by the platform based on the failureReason you submit. The connector's responsibility is to pick the value that best describes what went wrong; use the description column in the table above as your guide.

Usage examples

Reporting success

1
2
import { graph } from '@forge/teamwork-graph';

export async function taskRunner(request: TaskRunnerPayload) {
  await doTheWork(request);

  await graph.updateTaskStatus({
    scanId: request.scanId,
    taskExecutionId: request.taskExecutionId,
    connectionId: request.connectionId,
    status: 'success',
    task: { taskId: request.taskId },
  });

  return { success: true };
}

Reporting failure with a reason

1
2
import { graph, types } from '@forge/teamwork-graph';

export async function taskRunner(request: TaskRunnerPayload) {
  try {
    await doTheWork(request);
    await graph.updateTaskStatus({
      scanId: request.scanId,
      taskExecutionId: request.taskExecutionId,
      connectionId: request.connectionId,
      status: 'success',
      task: { taskId: request.taskId },
    });
    return { success: true };
  } catch (error) {
    await graph.updateTaskStatus({
      scanId: request.scanId,
      taskExecutionId: request.taskExecutionId,
      connectionId: request.connectionId,
      status: 'failure',
      failureReason: classify(error),
      task: { taskId: request.taskId },
    });
    return { success: false, message: String(error) };
  }
}

function classify(error: unknown): types.TaskStatusUpdateRequest['failureReason'] {
  if (isHttp(error, 401)) return 'UNAUTHORIZED';
  if (isHttp(error, 403)) return 'UNAUTHORIZED';
  if (isHttp(error, 404)) return 'ENTITY_NOT_FOUND';
  if (isHttp(error, 429)) return 'RATE_LIMITED';
  return 'RETRYABLE_ERROR';
}

Request validation

The method validates the following:

• connectionId: Required, must be a non-empty string.
• status: Must be exactly 'success' or 'failure'.
• task.taskId: Required, must be a valid UUID.
• failureReason: When provided, must be one of the eight values listed above.

The scanId and taskExecutionId fields are not validated client-side; pass them through unchanged from the current TaskRunnerPayload.

Error handling

Response

The method returns a promise that resolves to a TaskStatusUpdateResponse.

1
2
{
  status: string;          // Status string from the platform (e.g. "ACCEPTED")
  message: string;         // Human-readable status message
  error?: string;          // Error message if the request failed
  originalError?: unknown; // Original platform error object, when available
}

On success, the response carries status and message. On failure, the SDK returns an object with error and originalError populated. Branch on response.error to detect failures.

Type safety

The SDK provides type-safe request and response objects that ensure compile-time validation:

1
2
import { graph, types } from '@forge/teamwork-graph';

const request: types.TaskStatusUpdateRequest = {
  scanId: incomingPayload.scanId,
  taskExecutionId: incomingPayload.taskExecutionId,
  connectionId: incomingPayload.connectionId,
  status: 'failure',
  failureReason: 'RATE_LIMITED',
  task: { taskId: incomingPayload.taskId },
};

const response: types.TaskStatusUpdateResponse = await graph.updateTaskStatus(request);

if (response.error) {
  console.error('Failed to update task status:', response.error);
}

The type system ensures:

• status is restricted to 'success' | 'failure'.
• failureReason is constrained to the eight supported values.
• request has the correct TaskStatusUpdateRequest structure.
• response is properly typed as TaskStatusUpdateResponse with optional error and originalError.