# Workflows and reporting

Facts checked against HubSpot's live docs on 2026-10-17. Routing policy depth belongs to the lead-routing-and-speed-to-lead skill and scoring to lead-scoring-model, if installed.

## Write the policy before the workflow

For each workflow in the first release, write in plain language:

- Trigger and eligible population, including exclusions (existing customers, partners, test records, a running import or backfill batch).
- How an import batch is kept out: by a batch tag while the batch runs, removed when the batch is reconciled. Never by Record Source: it is set once at creation, so the exclusion would drop every later request from an imported contact. A form-submission trigger is not met by an import at all.
- Precedence, most specific first. An illustrative order for inbound sales requests:
  1. Reject confirmed spam with a recorded reason.
  2. Recognise a repeated delivery and keep the earlier outcome.
  3. Send support and billing intent to their own process.
  4. Keep the owner of a matching open deal or managed account.
  5. Check eligibility and required routing fields.
  6. Choose the territory or segment pool.
  7. Distribute among eligible, available reps.
  8. Send everything else to a monitored fallback owner.
- Fallback owner, the status that marks a record as needing review, and the escalation deadline.
- Audit properties: `routing_rule_id`, `routing_reason`, `routing_status`, original receipt time.
- What happens on re-entry: a company-size update must not reassign an accepted request.

## HubSpot behaviour that shapes the design

- Enrolment: records enrol only the first time they meet the triggers unless re-enrolment is set up. A record can re-enrol only after it has exited or been unenrolled from the workflow.
- Turning a workflow on asks whether to enrol existing records that meet the triggers now, or only records that meet them after it is turned on. Choose the second unless a backfill is intended, approved and tested. Turning re-enrolment on later does not retroactively enrol records; those need manual enrolment.
- Scheduled workflows: existing records not enrolled at activation can still enrol on the next scheduled run if they still meet the criteria. Add an exclusion if they must not.
- Owner rotation ("Rotate record to owner"): Sales Hub or Service Hub Professional or Enterprise. Assigns only users with paid Sales or Service seats; greys out core and view-only seats and users who have not accepted the invite. Adding or removing owners resets the assignment counts. "Assign to available users only" skips users set to Away; if all are away, the record stays unowned, so the fallback must catch it. Lead and ticket workflows have their own distribution options. Salesforce owner sync can write the previous owner back.
- The overwrite option ("Overwrite if [object] has an existing owner") decides whether existing ownership survives. Keep it off for flows that must protect account owners, and write the choice into the brief for every owner-setting action.
- HubSpot Credits: usage-based features pause by default when included credits are used up and no capacity pack was bought. Purchased packs default to auto-upgrade or pay-as-you-go depending on purchase date (before or after 16 September 2026). Only Super Admins and billing admins turn on overages. A routing or alerting step that must always run needs a non-credit fallback.

## Testing workflows

- Test with controlled records while external email is limited to test recipients, or in a standard sandbox (Enterprise; sandbox email only reaches contacts sharing an address with sandbox users; 100,000 enrolments per day across all sandbox workflows).
- Cases: eligible new request, existing customer, open deal owner on leave, missing routing field, duplicate delivery, two simultaneous requests, a historical imported record that meets the trigger during the import, a historical imported contact who submits the form after launch (routed normally), a record that should exit mid-flow.
- Check enrolment, re-enrolment, exclusions, delays, owner changes and exits in the workflow history for each case.
- For credit-consuming steps, test the fallback by pausing the feature.

## Reporting

Before building any report, write for each metric:

- The counting unit (contacts, companies, deals, workspaces).
- The timestamp that counts (create date, "Date entered [stage]", close date) and the time zone (account time zone).
- Re-entry treatment for lifecycle stages.
- Currency policy for deal amounts.
- Exclusions and an explicit unknown group. Test and internal submissions are excluded by one documented rule applied in HubSpot and in analytics.
- Restatement rule for a reopened closed-won deal: whether the original close date and amount stand, or the report restates the period, and who approves.

Grain traps:

- Joining deals to contacts and summing amount repeats a deal's value per contact. Fictional example: deals of 24,000, 10,000 and 10,000, where the first has two contacts, sum to 68,000 after a join; the correct total is 44,000. `SUM(DISTINCT amount)` gives 34,000 and is also wrong, because two different deals share an amount. Deduplicate on deal ID.
- One commercial amount associated with several workspaces is still one amount.
- Contact-level source fields hold one current value. A deal's acquisition context needs a snapshot taken when the deal was created.
- Imported contacts have no web history; attribution reports will show them under offline or unknown sources. Report that group rather than reassigning it.
- Deal create and deal revenue attribution reports need Marketing Hub Enterprise. Below that, report deal source from a snapshot property set at deal creation.
- A request report counts requests, not contacts: one contact can submit several. Give each request a key, such as the contact Record ID plus the submission time.

Reconciliation gate: every number on the launch dashboard can be reproduced from a list of record IDs, and the list matches the report.

## Observation period

Default length: 30 days from launch, extended while any defect stays open. One named owner checks daily:

- Records in the routing fallback and their age.
- Failed syncs, Salesforce Sync Health, and the integration review queues.
- Unexpected enrolments: records from an import or backfill batch (by tag or a Record ID segment) or created by an integration, in a fresh-request workflow.
- Marketing contact count against tier and cap, before and after each form or import change.
- The per-stage views of deals missing required properties.
- Report discrepancies against record lists.
- The restore window: for each new writer (import, integration, workflow), the date its 14-day Restore CRM changes window closes, and a named Super Admin.

Defect queue: each entry has a reproducible case (record IDs and steps), owner, impact and next review date.

Change control during observation:

- Any workflow or property added goes through the same register row and controlled-record tests as the release. No unreviewed workflows.
- Changes from a second agency or team go through the same queue.
- Training records are labelled (a test flag or `example.com` addresses) and excluded from live outreach and reports.
- Record whether the first workflows need historical activity migrated (emails, calls, notes), and if not, what users will not see.

Fix causes, not records, while the scope is still small.