A workflow's diagram can show what is connected without explaining why it exists. The next administrator needs to know which business rule it implements, what it can change and which failure would make it unsafe to leave running.
TLDR: Document purpose, ownership, enrollment, reenrollment, actions, dependencies, exceptions and stop conditions. Link the explanation to the actual workflow and its change history. Keep intended behavior separate from observed execution evidence.
We recommend a short purpose statement that a business owner can approve. For example, a synthetic workflow might identify eligible consultation requests that have no owner and create an internal review step. It should not quietly add outreach or change qualification rules that were never approved.
Name the business owner, administrator and person authorized to approve changes. Record the process the workflow supports and what it explicitly does not do.
If the purpose is unclear, documenting every branch will preserve the confusion rather than resolve it. The portal audit checklist can help place the workflow in its wider context.
We recommend recording the enrolled object, trigger, filters, exclusions and reenrollment settings. Include how existing records are handled when the workflow is activated or changed.
Avoid shorthand such as “all new leads” unless the document defines “new” and “lead.” Record the relevant properties and approved values, including what happens when data is missing.
As checked on August 28, 2026, HubSpot documents workflow actions with action-specific subscription and permission requirements. A document should name the actual action and its eligibility rather than imply that all accounts can implement the same diagram. HubSpot workflow action reference
This example is fictional and is not an installable workflow recipe. It does not enroll or change any production records.
The document should name the exact configured properties and actions in a real implementation. The generic labels above are deliberately illustrative.
We recommend listing every object, field, message, integration and downstream workflow the automation can affect. Include branches that do nothing, waits that can become stale and actions that depend on another system.
If a step can overwrite an owner or send an external message, make that visible in the documentation. A small-looking configuration change can have a broader effect than its position in the diagram suggests.
Document how the team identifies repeated enrollment or conflicting workflows. Do not assume the absence of a visible error means the business outcome was correct.
HubSpot documents workflow enrollment history and individual record paths. Use the available history to inspect what happened, while keeping its scope and retention limits in mind. HubSpot enrollment-history documentation
We recommend retaining dated acceptance evidence appropriate to your governance process. Include the configuration version, test record reference, expected result, observed result and reviewer. Remove private record data from broadly shared documentation.
Execution history is evidence of actions, not a substitute for the approved purpose or business rule. If behavior changes, update both the configuration record and the plain-language explanation.
Use a change log with the reason, approver, effective date and affected tests. Explain how an administrator should report an issue and who decides whether to pause the workflow.
Your document should remain usable by someone who did not attend the original build meetings. Ask a second administrator to explain the entry rule and stop condition from the document alone.
For broader examples, the sales automation article is historical context, not current product-eligibility evidence. Use the HubSpot troubleshooting guide for adjacent issues. For help establishing documentation and ownership, explore HubSpot operations support or request a scoped review.
Copy the following structure into the documentation system your team already maintains. This is a writing template, not an installable HubSpot workflow or a claim that a particular action is included in your account.
Record the workflow name, direct link, enrolled object, business purpose, accountable owner and maintainer. Include the related policy or decision record. State whether the automation supports customer onboarding, lead assignment, lifecycle management or another defined process.
Explain its boundary in a sentence. For example, an internal exception workflow can create a review task without being authorized to send a marketing email. Keeping that distinction visible helps the next administrator understand the consequences of changing it.
Document the actual entry conditions, exclusions, reenrollment rules and handling of existing records. Include the exact property names and accepted values. A contact-based workflow and a deal-based workflow may be supporting related work while acting on different records; the document should make the affected record clear.
Write a plain-language example that qualifies and one that does not. If a form submission starts the process, distinguish the submission event from a later change to a contact property. If a deal stage matters, record the intended stage and what happens when the record moves backward.
List each action in order, including branches, delays and actions that intentionally do nothing. Record which properties can change, which tasks can be created and which messages can leave the account. Identify any integration or other workflow that depends on those changes.
For each consequential action, add the expected result and a failure response. If the action cannot complete, who reviews it? If a delayed record is no longer eligible, what should happen before the next action? Document the actual supported behavior rather than assuming the diagram enforces the business rule.
Keep the test date, configuration version, expected result, observed result and approval reference together. Include a duplicate or repeated-entry case when it matters to the process. Retain only the private record information required by your organization.
When the workflow changes, update the explanation and affected tests. A change history entry should say why the rule changed and when it took effect. A screenshot of the workflow editor can support that record, but it should not be the only explanation.
Ask a receiving administrator to locate the entry conditions, identify an external side effect and explain how to stop an unsafe run. If those answers require a meeting with the original builder, revise the document.
Review the document when a dependency, business rule or action changes. Documentation is part of maintaining the automation, not a separate deliverable that becomes permanently complete on launch day.