A Journey Step is a single, atomic user action within a Journey. Steps are the building blocks of journey analysis — every click, navigation, form input, wait, and error recovery gets recorded as an individual step, complete with timing, friction assessment, and traceability links.
What a Step Represents
A step should represent one user-meaningful action. The goal is to group micro-actions (e.g., “clicked field” + “typed text” + “pressed Enter”) into a single logical step (e.g., “Searched for invoice by number”). This level of granularity keeps journeys manageable while preserving enough detail for analysis.
Key Fields
| Field | Purpose |
|---|---|
| step_order | Sequence position within the journey (1, 2, 3…) |
| description | What the user did in plain language |
| step_type | Action classification (see below) |
| screen_name | The screen or page where the action occurred |
| element_identifier | The UI element interacted with (button name, field label, etc.) |
| duration_ms | How long this step took in milliseconds |
| friction_level | Observed friction: none, low, medium, high |
| friction_notes | Free text describing the friction source |
| ai_suggested | Whether this step was auto-detected by AI capture |
| ai_friction_suggested | Whether friction was AI-identified |
| impact_narrative | AI-generated business impact statement for the friction |
| journey_id | The parent Journey |
| requirement_id | Optional link to a Requirement for traceability |
Step Types
Catalio classifies steps into five types:
| Type | Description | Example |
|---|---|---|
| navigation | Moving between screens or sections | “Navigated to AP Invoice module” |
| input | Entering data into a field | “Entered invoice number in search field” |
| action | Clicking a button or triggering an operation | “Clicked ‘Submit for Approval’” |
| wait | Waiting for the system to respond | “Waited for search results (8 seconds)” |
| error | Encountering an error state | “Received ‘Record locked by another user’ error” |
The wait and error types are particularly important — they are where systemic friction concentrates. A journey with 12 navigation steps and 3 error steps tells a very different story than one with 12 navigation steps and no errors.
Friction Classification
Every step carries a friction level. This is the most analytically valuable field in journey capture because it enables aggregated friction scoring.
none — The step completed smoothly without confusion or delay beyond normal system response time.
low — Minor friction: a slightly non-intuitive label, a brief wait, or a small extra click. Annoying but not workflow-blocking.
medium — Meaningful friction: the user had to think, backtrack, or use a workaround. Adds meaningful time to the workflow.
high — Severe friction: the user was blocked, confused, or required assistance. In many cases, high-friction steps are where users abandon workflows or call for help.
Example friction annotation:
Step: "Located vendor record in AP module"
Type: navigation
Duration: 4 minutes 12 seconds
Friction: high
Friction Notes: "Search does not support partial name matching. User had to scroll
through 340 vendor records alphabetically to find 'Smith & Co. LLC' because
searching for 'Smith' returned no results."
AI-Generated Impact Narratives
For high-friction steps, Catalio can generate an impact narrative — a plain-language description of the business cost of the friction. This is generated via Catalio.Journeys.generate_impact_narrative/2 and stored in the impact_narrative field.
Impact narratives translate friction into business language:
“This step forces users to manually scroll through hundreds of vendor records because the search system does not support partial name matching. For AP clerks processing 50+ invoices per day, this single friction point consumes an estimated 2-3 hours of productive time daily across the department.”
These narratives are purpose-built for inclusion in modernization business cases.
Traceability: Linking Steps to Requirements
Journey Steps can be linked to Requirements via the RequirementStepLink join resource. This creates bidirectional traceability:
- From a Requirement: “Which journey steps validate this requirement?”
- From a Journey Step: “Which requirement does this action implement?”
Links have a link_type field with values:
- supports — The step demonstrates that the requirement is being met
- blocks — The step reveals a barrier to meeting the requirement
- validates — The step is a direct test of the requirement’s acceptance criteria
Links also have a link_source field: manual (human-created), ai_suggested (AI proposed, pending review), or human_confirmed (AI proposed and human-approved).
Steps and Capability Traceability
Similarly, steps can be linked to Capabilities via CapabilityStepLink. Each link carries a maturity_level:
- planned — The capability is intended but not yet operational in this step
- developing — The capability is partially operational
- operational — The capability is fully operational
- optimized — The capability is efficient and measured
This enables a bottom-up capability maturity picture derived from real user behavior.
Step Ordering and Journey Integrity
Steps are ordered by step_order within their Journey. When you add a step at position 3, subsequent steps shift to maintain a continuous sequence. The total step count and step sequence are key metrics in Journey Comparisons.
Best Practices
Capture waiting time as explicit wait steps.
Waiting is friction. A user waiting 30 seconds for a screen to load while performing an “action” step loses the wait time in the data. Separate waits into explicit wait steps with accurate duration.
Group micro-actions into one logical step.
“Moved mouse to field, clicked, typed invoice number, pressed Tab” should be one step: “Entered invoice number.” Over-granular steps make journeys hard to read and analyze.
Annotate friction notes with observable evidence.
“User seemed confused” is unhelpful. “User clicked the wrong button twice before finding the correct action — the button labels ‘Process’ and ‘Process Invoice’ are visually identical” is actionable.
Link high-value steps to requirements immediately.
Don’t defer requirement linking. Do it during the journey review session while the context is fresh. Links created immediately after capture are higher quality than links added weeks later.
Use ai_suggested flags to track AI confidence.
When AI capture suggests steps, review ai_suggested steps carefully. AI capture is fast but may merge or split steps in ways that don’t match actual user intent.
Relationships at a Glance
| Related Concept | Relationship |
|---|---|
| Journey | Steps belong to a Journey |
| Requirements | Steps link to Requirements via RequirementStepLink |
| Capabilities | Steps link to Capabilities via CapabilityStepLink |
| JTBD | Steps contribute to the JTBD friction score (via Journey) |
Next Steps
- Understand Journeys — Learn the overall journey capture model
- Explore JTBD — Understand what motivates the journeys you capture
- Add Requirements — Link steps to requirements for traceability
Pro Tip: Review every high friction step as a potential requirement. The existence of severe friction in a step is almost always evidence that a requirement is either missing, poorly specified, or not being met.
Support
- Documentation: Continue reading about Journeys and Friction
- Email: support@catalio.ai
- Community: Share step capture patterns with other Catalio users