Skip to content
Book a build

How do you document your HubSpot workflow architecture?

Document HubSpot workflow architecture in two layers: an inventory of every workflow (purpose, owner, object, triggers, the properties it writes, status) and a map of how workflows connect through enrollment actions and shared properties. HubSpot gives you names, descriptions, folders, a spreadsheet export of the workflow list and PNG exports of single workflows, but no portal-wide map, so the connections are the part you build yourself.

On this page

What HubSpot supports natively

HubSpot stores some documentation for you, but only per workflow.

Native featureWhat it gives youWhat it doesn’t
Name and descriptionA searchable label per workflow (dashboard search matches both)Any structure: it’s free text
Folders and saved viewsGrouping by team, object or processRelationships between workflows
Export view on the workflows dashboardA spreadsheet of the workflow list, with some metrics such as enrollmentsTriggers, actions or what each workflow writes
Export as .PNG in a workflowAn image of one workflow, with branchesPerformance data, history, other workflows
Connections tabThe lists, properties and other assets one workflow usesA portal-wide view
Revision historyWhat changed, when, and by whomWhy it changed

So the per-workflow facts are available. The architecture, meaning how 200 workflows depend on each other, is not.

How to document HubSpot workflow architecture

  1. Export the inventory. Use Export view on the workflows dashboard as your starting sheet. See getting a report of all workflows.
  2. Add the columns HubSpot doesn’t export. For each workflow: business purpose (one sentence), owner, object type, enrollment trigger in plain words, properties it writes, workflows it enrolls records into, and a keep / fix / retire decision.
  3. Group by process, not by team. Lead capture, lifecycle and routing, onboarding, renewals. A process page lists its workflows in order and the property that hands a record from one to the next.
  4. Map the connections. Draw two kinds of edges: one workflow enrolling records into another (the “Go to workflow” action), and one workflow writing a property that another reads. The second kind is the one people miss, and the one behind most surprises.
  5. Record the single owner of each key property. Lifecycle stage, lead status, owner. If more than one workflow writes it, note why.
  6. Link back from HubSpot. Put the doc link and the owner in each workflow’s description.
  7. Review on a schedule. Use revision history and the Unused tab on the dashboard to find what changed or stopped running since the last review.

Common mistakes

  • Screenshots as documentation. An image of one workflow goes stale on the next edit and says nothing about what else depends on it.
  • Documenting actions, not intent. “Sets lead status to Open” is in the workflow already. “Hands new inbound leads to SDRs” is what the next admin needs.
  • No naming convention. Documentation is much easier to keep current when names follow a pattern. See HubSpot workflow naming conventions.

Where Jetstack AI fits

A Jetstack AI Workflow Audit builds the inventory and the connection map from the portal itself: a plain-language brief per workflow, the assets each one reads and writes, explicit enrollment paths, and shared writers. Your team can save notes and keep / improve / investigate / retirement-candidate decisions against each workflow, and they carry over to the next audit of the same portal. See how to read the dependency map.

Sources

Checked October 29, 2026. HubSpot changes its products often; tell us at team@jetstack.ai if something here is out of date.

Workflows & automation

See what needs work before you change it.

A read-only Portal Audit and Workflow Audit score the portal, trace dependencies and turn findings into a branded report.

Explore Portal Audit

Workflows & automation

Related questions.

How do you document your HubSpot workflow architecture?

Document HubSpot workflow architecture in two layers: an inventory of every workflow (purpose, owner, object, triggers, the properties it writes, status) and a map of how workflows connect through enrollment actions and shared properties. HubSpot gives you names, descriptions, folders, a spreadsheet export of the workflow list and PNG exports of single workflows, but no portal-wide map, so the connections are the part you build yourself.

Where should workflow documentation live?

Somewhere the whole team can edit and search, next to the portal it describes: a shared sheet for the inventory and a doc or wiki page for each process. Put a link to it in each workflow's description so the person editing the workflow finds it.

How do agencies handle portal documentation across clients?

Most keep one standard template (inventory columns, naming convention, process pages) and fill it per client. The template matters more than the tool: the same columns in every portal make handoffs and audits faster.

How often should the documentation be updated?

Whenever a workflow is created, turned off or changes what it writes, and in a scheduled review each quarter. HubSpot's revision history shows who changed a workflow and when, which helps you catch changes the docs missed.