Temporal is a durable workflow execution platform — workflows are long-running functions that survive process restarts, network failures, and deployments. Workflow IDs, activity IDs, and signal names are all strings in Temporal. Using UUID v7 for workflow IDs gives time-sorted identifiers that correlate naturally with application logs and trace spans. See UUID v7 in Microservices for the correlation ID pattern.

Starting a workflow with UUID v7 ID

import { Client, Connection } from '@temporalio/client';
import { v7 as uuidv7 } from 'uuid';

const connection = await Connection.connect();
const client = new Client({ connection });

// Start a workflow with UUID v7 as the workflow ID
const workflowId = uuidv7();

const handle = await client.workflow.start('processOrder', {
  taskQueue: 'orders',
  workflowId,            // UUID v7 — time-sortable, globally unique
  args: [{ orderId: workflowId, customerId: 'cust-123', total: 99.99 }],
});

console.log(`Started workflow: ${workflowId}`);
// workflowId = 018fbe3a-4c5d-7b12-8f3e-1a2b3c4d5e6f
// First 12 hex chars encode start time

Workflow definition with UUID v7 activity IDs

// src/workflows/processOrder.ts
import { proxyActivities, ActivityOptions } from '@temporalio/workflow';
import { v7 as uuidv7 } from 'uuid';

const { chargePayment, fulfillOrder, sendConfirmation } = proxyActivities<{
  chargePayment(args: { paymentId: string; amount: number }): Promise<void>;
  fulfillOrder(args: { fulfillmentId: string; orderId: string }): Promise<void>;
  sendConfirmation(args: { messageId: string; orderId: string }): Promise<void>;
}>({
  startToCloseTimeout: '5 minutes',
  retry: { maximumAttempts: 3 },
});

export async function processOrder(order: { orderId: string; total: number }) {
  // Each activity gets a UUID v7 ID for idempotency
  // These are deterministic within the workflow because Temporal replays history
  // but for external systems (payment gateway), UUID v5 is safer for replay safety
  await chargePayment({ paymentId: uuidv7(), amount: order.total });
  await fulfillOrder({ fulfillmentId: uuidv7(), orderId: order.orderId });
  await sendConfirmation({ messageId: uuidv7(), orderId: order.orderId });
}

Important: For activity IDs passed to external systems (payment gateways, email providers), use UUID v5 derived from the workflow ID + activity name — this ensures the same ID is generated on replay, making retries idempotent. See UUID v5 — Deterministic UUIDs.

Deterministic child workflow IDs with UUID v5

import { v5 as uuidv5 } from 'uuid';

// Derive child workflow ID from parent — deterministic on replay
function childWorkflowId(parentId: string, childName: string): string {
  // Use parent workflow's UUID v7 as the namespace
  return uuidv5(childName, parentId);
}

// In a parent workflow:
const childId = childWorkflowId(workflowInfo().workflowId, 'send-email');
await startChildWorkflow('sendEmail', {
  workflowId: childId,  // same on every replay
  args: [{ orderId: workflowInfo().workflowId }],
});

This pattern ensures child workflows are not duplicated on Temporal replay — the same UUID v5 value is derived from the same inputs. See UUID v5.

Signal deduplication with UUID v7

// src/workflows/processOrder.ts
import { defineSignal, setHandler } from '@temporalio/workflow';

const paymentConfirmedSignal = defineSignal<[{ signalId: string; amount: number }]>(
  'paymentConfirmed'
);

export async function processOrder() {
  const processedSignals = new Set<string>();

  setHandler(paymentConfirmedSignal, ({ signalId, amount }) => {
    if (processedSignals.has(signalId)) {
      return; // deduplicate — UUID v7 signal ID already processed
    }
    processedSignals.add(signalId);
    // process payment confirmation...
  });
  // ... workflow logic
}
// Sending the signal from outside the workflow:
await handle.signal(paymentConfirmedSignal, {
  signalId: uuidv7(),  // unique per signal send
  amount: 99.99,
});

See UUID as Idempotency Keys.

Querying workflows by UUID v7 time range

// Temporal's list API supports workflow ID filters
// UUID v7 IDs sort chronologically — no separate startTime filter needed
const workflows = client.workflow.list({
  query: `WorkflowId >= "${startUUID}" AND WorkflowId <= "${endUUID}"`,
});

See UUID v7 in Distributed Systems for the broader time-range query pattern.

Further reading

External references

Frequently asked questions

How do I use UUID v7 as a Temporal workflow ID?

Pass a UUID v7 string as the workflowId when starting a workflow with client.workflow.start(). Temporal workflow IDs are arbitrary strings — UUID v7 provides global uniqueness with embedded timestamp for log correlation. For deterministic child workflow IDs, use UUID v5 derived from the parent workflow ID and a child name. See UUID v5 — Deterministic Namespace-Based UUIDs.

Can I use UUID v7 for Temporal activity heartbeat IDs?

Activity heartbeats in Temporal don't have their own IDs — you pass arbitrary details to heartbeat(). You can include a UUID v7 in the heartbeat details for correlation. The activity's workflowId and activityId are sufficient for Temporal's own tracking; UUID v7 in heartbeat details is useful for correlating with external systems.

How does UUID v7 help with Temporal signal deduplication?

When sending signals from multiple sources to a workflow, include a UUID v7 signalId in the signal payload. The workflow can maintain a set of seen signal IDs to deduplicate — UUID v7's monotonic order ensures the deduplication set can be pruned by timestamp prefix (drop IDs older than the processing window). See UUID as Idempotency Keys.