feat: Use `RoutingTraceService` to write assignment reasons #27225

joeauyeung · 2026-01-26T02:28:15Z

What does this PR do?

This PR introduces a RoutingTraceService to track routing decisions and write assignment reasons for bookings, replacing the previous approach that relied on URL params or post-processing after booking creation.

Key Changes

New Database Models:

PendingRoutingTraces - Stores routing trace data temporarily between form submission and booking creation
RoutingTrace - Permanent storage linked to bookings, form responses, and assignment reasons

New Service Architecture:

RoutingTraceService - Core service that collects routing steps and processes them into assignment reasons
Repository pattern with IPendingRoutingTraceRepository and IRoutingTraceRepository interfaces
DI container setup in RoutingTraceService.container.ts

Integration Points:

handleResponse now accepts a traceService parameter to track routing form decisions
findTeamMembersMatchingAttributeLogic records attribute logic evaluation steps
routerGetCrmContactOwnerEmail records CRM assignment steps
RegularBookingService uses RoutingTraceService.processForBooking() instead of AssignmentReasonRecorder

Trace Steps Recorded:

routing_form domain: attribute-logic-evaluated step with route name, fallback status, and attribute details
CRM domain (e.g., salesforce): {appSlug}_assignment step with contact owner details

Updates since last revision

Added comprehensive unit tests for the new routing trace functionality:
- RoutingTraceService.test.ts - 20 tests covering step tracking, pending trace saving, and assignment reason extraction
- PrismaPendingRoutingTraceRepository.test.ts - 7 tests for pending trace CRUD operations
- PrismaRoutingTraceRepository.test.ts - 5 tests for permanent trace creation

Mandatory Tasks (DO NOT REMOVE)

I have self-reviewed the code (A decent size PR without self-review might be rejected).
I have updated the developer docs in /docs if this PR makes changes that would require a documentation change. N/A - internal service change.
I confirm automated tests are in place that prove my fix is effective or that my feature works.

How should this be tested?

Create a routing form with attribute-based routing logic
Submit the form and complete a booking
Verify that:
- A PendingRoutingTraces record is created after form submission
- A RoutingTrace record is created after booking completion
- The AssignmentReason is correctly populated based on the routing trace

For CRM routing:

Configure Salesforce CRM integration with round-robin lead skip
Submit a routing form where the contact owner is a team member
Verify the assignment reason reflects the CRM ownership

Human Review Checklist

Verify the extractAssignmentReasonFromTrace logic correctly prioritizes CRM over routing form assignment
Confirm the CRM assignment check (organizer email must match contact owner) is the intended behavior
Review error handling in RegularBookingService - failures are logged as warnings but don't block booking
Ensure database migration is correct for new PendingRoutingTraces and RoutingTrace tables
Verify no edge cases are missed from the removed AssignmentReasonRecorder logic

Checklist

I have read the contributing guide
My code follows the style guidelines of this project
I have checked if my changes generate no new warnings
My PR is not too large (>500 lines or >10 files) - This PR is larger due to new service architecture

Link to Devin run: https://app.devin.ai/sessions/1f674b7b8e4747249113cc2da6142b24
Requested by: joe@cal.com (@joeauyeung)

…tingTraceRepository

Co-Authored-By: joe@cal.com <j.auyeung419@gmail.com>

Also fix pre-existing lint issues in the test file: - Add explicit types to mockForm and mockSerializableForm variables - Add explicit type to url parameter in mockContext - Replace 'as any' with 'as unknown as InstanceType<typeof UserRepository>' Co-Authored-By: joe@cal.com <j.auyeung419@gmail.com>

joeauyeung · 2026-01-26T02:30:15Z

packages/app-store/routing-forms/lib/crmRouting/routerGetCrmContactOwnerEmail.ts

@@ -10,10 +11,12 @@ export default async function routerGetCrmContactOwnerEmail({
  attributeRoutingConfig,
  identifierKeyedResponse,
  action,
+  routingTraceService,


We need to pass the routingTraceService down from getRoutedURL down to the actual functions that handle the routing. getRoutedMembers is wrapped using Sentry's withReporting which creates it's own async context so we cannot rely on AsyncLocalStorage for the RoutingTraceService

joeauyeung · 2026-01-26T02:30:56Z

packages/app-store/routing-forms/lib/crmRouting/routerGetCrmContactOwnerEmail.ts

+  if (!eventType.hosts.some((host) => host.user.email === contactOwner.email))
+    return null;
+
+  if (routingTraceService && contactOwner.email && contactOwner.crmAppSlug) {


Change to the file is here, we're recording the routing trace step. With these values stored, we don't have to rely on these values being passed through URL params to generate the assignment reason.

joeauyeung · 2026-01-26T02:34:20Z

packages/features/bookings/lib/service/RegularBookingService.ts

Since we're using the PendingRoutingTrace we don't need to rely on URL params being passed.

joeauyeung · 2026-01-26T02:38:25Z

packages/features/routing-forms/lib/findTeamMembersMatchingAttributeLogic.ts

+    routingTraceService.addStep({
+      domain: "routing_form",
+      step: "attribute-logic-evaluated",
+      data: {
+        routeName,
+        routeIsFallback,
+        attributeRoutingDetails,
+      },


With this data stored, we don't need to do the calculation to get the name value pairs of the attributes used to route in RegularBookingService when recording the assignment reason.

joeauyeung · 2026-01-26T03:10:13Z

packages/features/routing-trace/services/RoutingTraceService.ts

+  /**
+   * Process pending routing trace for a booking.
+   * Looks up the pending trace, extracts assignment reason, creates permanent trace.
+   */
+  async processForBooking(args: {


Phase 1 of the routing trace project is to replace how we're recording the assignment reason with the stored pending routing trace.

This method will change as we continue to work on the routing trace.

joeauyeung · 2026-01-26T03:16:15Z

packages/features/routing-trace/services/RoutingTraceService.ts

+          reasonString: this.buildSalesforceReasonString({
+            email,
+            recordType: recordType ?? "Contact", // Default to Contact if not specified
+            recordId,


One advantage of taking this approach is we can pass the Salesforce record id around without exposing it in URL params

github-actions · 2026-01-26T15:42:29Z

E2E results are ready!

Workflow #101090.1 latest results

joeauyeung added 21 commits January 22, 2026 22:54

Add DB schema

05953ac

Init zod schema

0a4750a

Init RoutingTrace and PendingRoutingTrace repository interfaces

a5097c4

Create PrismaPendingRoutingTraceRepository

18eec22

Init RoutingTraceService

81adb22

Create RoutingTraceService container

47579a1

User routing trace service in routing

8e1c029

Create RoutingTraceRepository and PrismaRoutingTraceRepoistory

97b12e8

Add findByFormResponseId and findByQueuedFormResponseId to PendingRou…

54dcb34

…tingTraceRepository

Update DI containers

760cfac

RoutingTraceService create process booking method

2b3ed7d

Use pending routing trace rather than URL params

56957cd

Fix schema

6aeba7b

Fix writing assignment reason for routed booking

ff170cd

Remove from service

de1eeea

Refactor RoutingTraceService to not rely on async local storage

5178195

Pass RoutingTraceService through routing call

ed84965

Add attribute-logic-evaluated to routing trace step

4db3a96

Add routing trace to trpc endpoint

35cc488

Add CRM routing trace step

3ce4b4a

Fix extracting routing trace to assignment reason

0aa6fb5

pull-request-size bot added the size/XL label Jan 26, 2026

joeauyeung and others added 2 commits January 25, 2026 21:50

Add back CRM params to prevent refetching

84f16ec

test: Add unit tests for RoutingTraceService and repositories

3f6dbc6

Co-Authored-By: joe@cal.com <j.auyeung419@gmail.com>

pull-request-size bot added size/XXL and removed size/XL labels Jan 26, 2026

joeauyeung commented Jan 26, 2026

View reviewed changes

Merge branch 'main' into init-routing-trace

fb93b06

joeauyeung added the ready-for-e2e label Jan 26, 2026

joeauyeung added 3 commits January 26, 2026 10:31

Link pending form submission to routing trace

4b95272

Clean up

75c425a

Add lookup field assignment reasons

64baa06

Rename to PendingRoutingTrace

9145113

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: Use `RoutingTraceService` to write assignment reasons #27225

feat: Use `RoutingTraceService` to write assignment reasons #27225

Uh oh!

joeauyeung commented Jan 26, 2026 •

edited by devin-ai-integration bot

Loading

Uh oh!

joeauyeung Jan 26, 2026

Uh oh!

joeauyeung Jan 26, 2026

Uh oh!

joeauyeung Jan 26, 2026

Uh oh!

joeauyeung Jan 26, 2026

Uh oh!

joeauyeung Jan 26, 2026

Uh oh!

joeauyeung Jan 26, 2026

Uh oh!

github-actions bot commented Jan 26, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

feat: Use RoutingTraceService to write assignment reasons #27225

Are you sure you want to change the base?

feat: Use RoutingTraceService to write assignment reasons #27225

Uh oh!

Conversation

joeauyeung commented Jan 26, 2026 • edited by devin-ai-integration bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What does this PR do?

Key Changes

Updates since last revision

Mandatory Tasks (DO NOT REMOVE)

How should this be tested?

Human Review Checklist

Checklist

Uh oh!

joeauyeung Jan 26, 2026

Choose a reason for hiding this comment

Uh oh!

joeauyeung Jan 26, 2026

Choose a reason for hiding this comment

Uh oh!

joeauyeung Jan 26, 2026

Choose a reason for hiding this comment

Uh oh!

joeauyeung Jan 26, 2026

Choose a reason for hiding this comment

Uh oh!

joeauyeung Jan 26, 2026

Choose a reason for hiding this comment

Uh oh!

joeauyeung Jan 26, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Jan 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

E2E results are ready!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

feat: Use `RoutingTraceService` to write assignment reasons #27225

feat: Use `RoutingTraceService` to write assignment reasons #27225

joeauyeung commented Jan 26, 2026 •

edited by devin-ai-integration bot

Loading

github-actions bot commented Jan 26, 2026 •

edited

Loading