External References

​

Reference Types

• Order IDs - E-commerce order numbers
• Customer IDs - Customer account identifiers
• Support Tickets - Zendesk, Jira, Salesforce ticket numbers
• Transaction IDs - Payment processor transaction IDs
• Application IDs - Loan applications, insurance claims
• Custom IDs - Any business-relevant identifier

​

Reference Properties

• Key - The reference type (e.g., “order_id”)
• Value - The actual identifier (e.g., “ORD-789”)
• Thread association - Links to a specific thread
• Queryable - Can be used to find threads

​

Adding References

const payment = await processStripePayment();

// Add references at thread level
await thread.addRefs({
  stripe_payment_id: payment.id,
  stripe_customer_id: payment.customer,
  order_id: 'ORD-12345'
});

// Then record the step
await thread.step('process_payment')
  .addContext({ amount: 299.99, currency: 'USD' })
  .success();

​

Querying by Reference

const threads = await connection.getThreadsByRef({
  refKey: 'stripe_payment_id',
  refValue: 'pi_1234567890'
});

​

Query Options

​

Linking Threads

// Link to parent thread
await childThread.linkThread(parentThread.threadId, 'parent');

// Link to related thread
await thread.linkThread(relatedThread.threadId, 'related');

// Link to child thread
await parentThread.linkThread(childThread.threadId, 'child');

​

Relationship Types

​

Use Cases

​

Customer Support

• Support agent gets ticket: “Where’s my order?”
• Query by order ID → Find thread → Show complete execution

​

Operations

• Monitor specific high-value orders
• Track problematic customer accounts
• Investigate transaction failures

​

Analytics

• Correlate thread data with business metrics
• Link execution patterns to customer behavior

​

Best Practices

• Add early - Add references as soon as they’re available
• Use consistent keys - Standardize reference names across services
• Multiple references - Add all relevant identifiers
• Business context - Use IDs that teams already recognize

​

Next Steps