Skip to Content
BridgesTasks

Bridge Tasks

Tasks are the units of work a bridge performs. Each task has a category that defines its data flow direction and behavior.

Task Categories

CategoryDirectionSchedulableDescription
syncExternal → OrderlyYesFetches data from the external platform
pushOrderly → ExternalVariesSends data to the external platform
webhookExternal → OrderlyNoHandles real-time incoming events
dispatchOrderly → ExternalNoRoutes data based on dispatcher rules

Task Execution Lifecycle

queued
running
success

Tasks go through the following states:

  1. queued — Task is waiting to be picked up by the execution engine
  2. running — Task is actively executing
  3. success / failed — Task has completed

Writing a Task

Each task is an async function that receives context and input:

async function grabOrders(
  context: BridgeTaskContext,
  input: Record<string, unknown>
): Promise<BridgeTaskResult> {
  const { config, logger, storage } = context;
 
  // Use storage for incremental sync
  const lastSync = await storage.get<string>('lastSync');
 
  // Call external API
  const orders = await fetchOrders(config.credentials, lastSync);
 
  // Update cursor
  await storage.set('lastSync', new Date().toISOString());
 
  return {
    success: true,
    data: orders,
    metrics: {
      recordsProcessed: orders.length,
      recordsCreated: orders.length,
    },
  };
}

Input Schemas

Tasks can declare inputSchema in the manifest to define expected parameters:

{
  name: 'grab-orders',
  inputSchema: {
    type: 'object',
    properties: {
      since: { type: 'string', format: 'date-time', description: 'Fetch orders since this date' },
      status: { type: 'string', description: 'Filter by order status' },
      limit: { type: 'number', default: 100, description: 'Maximum orders to fetch' },
    },
  },
}

Scheduled Tasks

Tasks with supportsSchedule: true can be configured to run on a cron schedule. The schedule is configured per-bridge instance in the portal under Bridges > [Bridge] > Schedules.

Metrics

Return metrics in your BridgeTaskResult to track processing stats:

return {
  success: true,
  data: results,
  metrics: {
    recordsProcessed: 150,
    recordsCreated: 120,
    recordsUpdated: 25,
    recordsSkipped: 3,
    recordsFailed: 2,
  },
};

These metrics are displayed in the portal’s task execution history.

Pagination

For large datasets, return pagination info and Orderly will re-invoke the task:

return {
  success: true,
  data: orders,
  pagination: {
    hasMore: true,
    cursor: 'next_page_token',
    total: 5000,
  },
};

When hasMore is true, the execution engine will call the task again with the cursor as input.

DeployWebhooks