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,
});
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
- UUID v7 in Microservices — correlation IDs
- UUID as Idempotency Keys
- UUID v5 — Deterministic Namespace-Based UUIDs
- UUID v7 in Distributed Systems
- UUID v7 in Event Sourcing
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.