getWorkflowMetadata

Get metadata about the current workflow run

Returns metadata about the current workflow run, including the run ID, start time, and trigger URL.

Signature

function getWorkflowMetadata(): WorkflowMetadata

Returns

WorkflowMetadata · WorkflowMetadata

Metadata about the current workflow run.

Show properties

workflowRunId · string

Unique identifier for the workflow run.

workflowStartedAt · Date

Timestamp when the workflow run started.

url · string

The URL where the workflow can be triggered.

Usage

Basic Usage

Get workflow metadata inside a workflow function:

import { getWorkflowMetadata } from 'workflow';

export async function workflowWithMetadata() {
  "use workflow";

  const metadata = getWorkflowMetadata();
  
  console.log('Run ID:', metadata.workflowRunId);
  console.log('Started at:', metadata.workflowStartedAt);
  console.log('Trigger URL:', metadata.url);
}

Use in Step Functions

Access workflow metadata from within a step:

import { step, getWorkflowMetadata } from 'workflow';

export async function workflowWithStepMetadata() {
  "use workflow";

  await step(async () => {
    "use step";
    
    const { workflowRunId } = getWorkflowMetadata();
    
    console.log('Processing in run:', workflowRunId);
    await processData(workflowRunId);
  });
}

Track Workflow Duration

Calculate how long a workflow has been running:

import { getWorkflowMetadata, sleep } from 'workflow';

export async function workflowWithDuration() {
  "use workflow";

  const { workflowStartedAt } = getWorkflowMetadata();
  
  await performWork();
  
  const duration = Date.now() - workflowStartedAt.getTime();
  console.log(`Workflow has been running for ${duration}ms`);
}

Include Run ID in External Requests

Pass the run ID to external systems:

import { step, getWorkflowMetadata, fetch } from 'workflow';

export async function notifyExternalSystem() {
  "use workflow";

  const { workflowRunId } = getWorkflowMetadata();

  await fetch('https://api.example.com/notify', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      runId: workflowRunId,
      message: 'Workflow started',
    }),
  });
}

Create Webhook URLs

The url property is used internally by createWebhook():

import { getWorkflowMetadata, createHook } from 'workflow';

export async function workflowWithCustomWebhook() {
  "use workflow";

  const { url } = getWorkflowMetadata();
  const hook = createHook();
  
  // Construct custom webhook URL
  const webhookUrl = `${url}/.well-known/workflow/v1/webhook/${hook.token}`;
  
  console.log('Send requests to:', webhookUrl);
  
  const request = await hook;
}

Logging and Observability

Include workflow context in logs:

import { getWorkflowMetadata } from 'workflow';

export async function workflowWithLogging() {
  "use workflow";

  const { workflowRunId, workflowStartedAt } = getWorkflowMetadata();
  
  console.log({
    runId: workflowRunId,
    startedAt: workflowStartedAt.toISOString(),
    event: 'workflow_started',
  });
  
  await doWork();
  
  console.log({
    runId: workflowRunId,
    event: 'workflow_completed',
  });
}

Correlation with External Systems

Use run ID for correlation:

import { step, getWorkflowMetadata } from 'workflow';

export async function workflowWithCorrelation() {
  "use workflow";

  const { workflowRunId } = getWorkflowMetadata();

  await step(async () => {
    "use step";
    
    // Use run ID as correlation ID in external systems
    await sendToMessageQueue({
      correlationId: workflowRunId,
      data: { /* ... */ },
    });
  });
}

Unique Resource Names

Generate unique resource identifiers:

import { getWorkflowMetadata } from 'workflow';

export async function workflowWithUniqueResources() {
  "use workflow";

  const { workflowRunId } = getWorkflowMetadata();
  
  const bucketName = `workflow-${workflowRunId}`;
  const queueName = `queue-${workflowRunId}`;
  
  await createResources(bucketName, queueName);
}

Scheduled Workflow Info

Combine with other metadata for scheduling:

import { getWorkflowMetadata, sleep } from 'workflow';

export async function scheduledWorkflow(scheduleTime: Date) {
  "use workflow";

  const { workflowStartedAt } = getWorkflowMetadata();
  
  // Calculate delay from when workflow started to scheduled time
  const delay = scheduleTime.getTime() - workflowStartedAt.getTime();
  
  if (delay > 0) {
    console.log(`Waiting ${delay}ms until scheduled time`);
    await sleep(delay);
  }
  
  await executeScheduledTask();
}

Notes

• Can be called from both workflow functions and step functions
• Throws an error if called outside a workflow or step function
• The workflowRunId is guaranteed to be unique for each workflow run
• The workflowStartedAt timestamp represents when the workflow run was first started
• The url property contains the base URL for the workflow deployment
• Uses a symbol-based storage mechanism internally for context retrieval

Related

• getStepMetadata - Get current step metadata
• createWebhook - Create a webhook (uses the url property)
• getWritable - Get a writable stream for the workflow