Archived #

These concept articles were consolidated here for reference. Content may be reorganized later.

What is a Step? #

Definition #

A Step is a single interaction point in a Journey.

Each Step presents one clear action to the candidate, such as reading information, selecting options, submitting a form, signing a document, or confirming details.

Key parts #

Step type
Determines behavior (form, text confirmation, options, signing, etc.).
Widget configuration
Controls what is rendered and how input is validated.
Save behavior
Defines where responses are stored (candidate fields, metadata, workflow variables).
Progression rule
Defines what happens when the step is completed.

Why it matters #

Step quality directly impacts completion rate, data quality, and candidate clarity.

Design tip #

Keep one decision or task per step. If a step asks for too many things, split it into multiple focused steps.

What is a Path? #

Overview #

A Path is an ordered sequence of stages inside an Agent.
It represents a specific flow track that guides candidates from entry to a defined outcome.

Why Paths matter #

Paths help teams break complex journeys into manageable, intentional tracks.
Instead of one linear flow for everyone, you can design paths for different candidate contexts.

Core structure of a Path #

Entry point #

Defines where candidates enter this flow segment.

Ordered stages #

A Path is made of staged progression, where each stage has a purpose.

Exit condition #

Defines how candidates leave the Path (completion, reroute, or stop).

What belongs in a Path #

Use a Path for:

collecting information in sequence
presenting progressive steps
preparing candidates for a decision point
handling a specific lifecycle segment

Do not use a Path as a generic catch-all bucket.

Path design principles #

Single intent per Path #

A strong Path answers one question, for example:

Is the candidate qualified?
Is the candidate ready to proceed?
Is additional documentation required?

Progressive clarity #

Each stage should reduce uncertainty and move toward an explicit decision.

Minimize friction #

Keep interactions concise and relevant to the Path objective.

Path and Gate interaction #

Paths often end in a Gate, where routing happens based on candidate data or outcomes.

Typical pattern:

Candidate completes Path stages.
Gate evaluates conditions.
Candidate is routed to next Path or terminal outcome.

Example pattern #

Qualification Path #

collect baseline profile
gather eligibility data
confirm intent and availability

Next step #

Send candidate to a Gate that routes to:

fast-track path
nurture path
disqualification path

Common mistakes #

Path has no clear objective
Stages are in random order
Too many optional steps with no routing value
Duplicated steps across many paths without reuse strategy

Quality checklist #

A Path is healthy when:

objective is explicit
stage order supports decision quality
completion criteria are clear
handoff to Gate is well-defined
drop-off points are monitored

What is a Journey? #

Definition #

A Journey is the full candidate experience from entry to completion inside Zirpa.

It combines routing logic and interaction steps into one connected flow so candidates move through the right path based on rules, responses, and outcomes.

Key parts #

Entry point
Where a candidate starts the flow.
Paths and Gates
Paths define stages, Gates decide direction.
Steps and Widgets
Steps contain user-facing actions and data collection.
Outcomes
Final business result for reporting or automation.

Why it matters #

A clear Journey design makes candidate experiences predictable, measurable, and easier to optimize over time.

Design tip #

Design each Journey around one business objective (for example: qualify, schedule, or complete onboarding), then keep every step aligned to that objective.

What is an Agent? #

Overview #

An Agent is the top-level container for a candidate journey in Zirpa.
It defines the journey's identity, structure, and behavior, then coordinates how candidates move through Paths, Gates, and Widgets.

If you think in product terms, an Agent is the experience unit you publish and operate.

Need foundation context first? Read What is Zirpa? and then continue with Paths & Gates.

Why Agents exist #

Without Agents, journey logic, branding, and routing rules would be fragmented across disconnected components.
Agents provide a single control layer so teams can:

model one business flow end-to-end
keep all step logic grouped in one place
apply consistent branding and appearance
monitor and improve performance over time

What an Agent controls #

Journey structure #

An Agent contains journey components such as:

Paths (ordered flow segments)
Gates (decision/routing points)
Steps (execution points)
Widgets (UI/interaction blocks inside steps)

Candidate progression #

It controls when a candidate:

enters a flow
advances to the next step
branches into another route
exits or completes the journey

Experience configuration #

It also owns visual and communication-related settings, such as:

runner appearance
labels and messaging
button behavior
integrated interaction patterns

Agent lifecycle #

Draft phase #

During setup, the Agent is configured with initial Paths, Gates, and Widgets.
Teams iterate quickly in this phase.

Active phase #

Once published, candidates can progress through the Agent's logic in production.

Optimization phase #

The Agent is refined over time by:

adjusting decision rules
simplifying steps
improving prompts and forms
reducing drop-off points

How Agents relate to other concepts #

Agent vs Path

Agent is the full journey container, while Path is one flow track inside it.

Agent vs Gate

Agent owns orchestration globally, while Gate executes local decision routing.

Agent vs Widget

Agent is orchestration layer, while Widget is interaction unit inside a step.

Agent in Zirpa context

See how Agent fits into the full Zirpa architecture and lifecycle.

Example (mental model) #

Imagine a franchise recruitment process:

Candidate starts in an Agent.
A Path collects profile and qualification data.
A Gate routes candidates by readiness.
Each step uses Widgets (forms, options, confirmations, signatures).
Candidate completes or exits based on outcomes.

That full orchestration is the Agent.

Best practices #

Keep one Agent focused on one business objective #

Avoid mixing unrelated goals (for example, recruitment + onboarding in one Agent).

Design routing intentionally #

Use Gates to clarify decisions, not to hide complexity.

Make steps measurable #

Each Path/step should have a clear purpose and expected signal.

Version safely #

When making big changes, test with controlled traffic before full rollout.

Common mistakes #

Building one giant Agent with too many unrelated branches
Overusing Gates without clear decision criteria
Embedding business logic in widget text instead of explicit routing
Changing structure frequently without tracking performance impact

Quick checklist #

Before publishing an Agent, confirm:

objective is clearly defined
paths are logically separated
gate rules are explicit
steps are minimal and purposeful
completion outcomes are clear

What is a Gate? #

Overview #

A Gate is a decision point in Zirpa that routes a candidate to the next branch of a journey.
It evaluates defined conditions, then sends the candidate to the most appropriate path or outcome.

Why Gates matter #

Gates make journeys adaptive.
Instead of forcing every candidate through one track, Gates enable controlled branching.

What a Gate evaluates #

A Gate can evaluate signals such as:

form responses
option selections
metadata and captured attributes
completion status from prior steps
rule outcomes from previous stages

Gate outcomes #

A Gate typically routes to one of:

another Path
a specialized branch
a completion/exit outcome
a fallback/default route

Types of routing logic #

Deterministic routing #

Clear yes/no or threshold-based logic.
Example: if eligibility criteria are met, route to next qualification stage.

Priority-based routing #

Multiple conditions are possible; highest-priority match wins.

Default fallback routing #

If no rule matches, candidate goes to a safe default branch.

Designing reliable Gates #

Keep rules explicit #

Avoid hidden or implied logic.
Rules should be readable and testable by non-developers.

Prevent ambiguous overlaps #

If two rules can match the same candidate, define priority clearly.

Always include fallback #

A candidate should never get stuck because no rule matched.

Gate quality checklist #

A Gate is production-ready when:

each condition is specific and testable
rule priority is documented
fallback route exists
outcomes are intentional and measurable
edge cases are covered

Common mistakes #

too many conditions in one Gate
overlapping rules without precedence
missing default path
routing based on unstable or incomplete signals

Example scenario #

A readiness Gate checks:

required profile data completeness
budget readiness signal
timing signal

Then routes candidate to:

Fast Track (high readiness)
Nurture (medium readiness)
Not Suitable (fails mandatory criteria)

What is an Outcome? #

Definition #

An Outcome is the final result assigned to a candidate journey after routing and step completion.

It represents the business meaning of the journey result, such as qualified, follow-up required, or not eligible.

Key parts #

Outcome label
Human-readable business result.
Trigger condition
Rule or path completion condition that sets the outcome.
Post-outcome behavior
Follow-up actions such as notifications, handoffs, or reporting updates.

Why it matters #

Outcomes turn workflow activity into business decisions that teams can track and act on.

Design tip #

Use a small, consistent set of outcomes across Agents so dashboards and operational actions stay comparable.

What is the Runner? #

Definition #

The Runner is the front-end experience where candidates complete Journey steps.

It renders configured content, captures responses, and moves candidates through paths based on workflow logic.

Key parts #

Step renderer
Displays each configured widget and interaction.
State handling
Tracks progress, values, and completion behavior.
Data sync
Persists candidate responses and refreshes step context.
Completion flow
Shows completion messages and final actions.

Why it matters #

The Runner is where workflow design becomes real user experience, so performance and clarity directly affect conversion and completion.

Design tip #

Optimize Runner steps for clarity first: short prompts, clear actions, and immediate feedback after each submission.

What are Merge Fields? #

Definition #

Merge Fields are placeholders that are replaced with live data at runtime.

They allow content to be personalized using candidate attributes, metadata, and workflow context.

Key parts #

Token format
A placeholder string (for example candidate or metadata fields).
Data source
Candidate record, metadata, workflow variables, or context values.
Render context
The point in the flow where values are resolved and shown.

Why it matters #

Merge Fields reduce manual edits, improve personalization, and keep messages consistent at scale.

Design tip #

Always define fallback-friendly content so screens remain clear even if an optional value is missing.

What is Compatibility Match? #

Definition #

Compatibility Match is a scoring mechanism that estimates candidate fit based on configured criteria.

It combines selected signals and weights to produce a structured fit indication used during journey decisions.

Key parts #

Criteria inputs
The candidate responses used for fit evaluation.
Weighting model
Relative importance of each criterion.
Score interpretation
How score bands map to decisions or paths.
Operational use
How teams use score outputs for qualification or routing.

Why it matters #

It helps teams make fit decisions more consistently and transparently across high candidate volume.

Design tip #

Start with a simple scoring model, validate against real outcomes, then tune weights gradually.

Overview #

A Widget is the execution unit inside a step.
It is the actual interaction component candidates see and use in the runner.

If Paths and Gates define flow logic, Widgets define the interaction experience.

Why Widgets matter #

Widgets convert journey design into real candidate actions, such as:

reading guidance
submitting data
choosing options
confirming details
completing signatures
triggering downstream actions

Input widgets #

Collect candidate data through forms, options, and structured responses.

Content widgets #

Display text, guidance, and contextual instructions.

Action widgets #

Trigger side effects such as notifications, webhooks, scheduling, or document flows.

Verification widgets #

Confirm identity, details, or required completion criteria.

Purpose-first configuration #

Each widget should have one clear job in the step.

Keep content actionable #

Candidates should know exactly what to do next.

Validate only what matters #

Avoid excessive required fields that do not affect routing or decisions.

Do not use a complex widget when a simple one is enough.

A widget can affect:

candidate-visible UI
saved response data
merge-field rendering in subsequent steps
routing decisions through downstream Gates
external integrations through actions/webhooks

Collect key profile signals required for a Gate decision.

Capture preference choices and map them to internal values.

Capture consent/approval as a signed artifact in the workflow.

Send structured payloads to external systems at controlled points.

Before publishing a widget, verify:

label and prompts are clear
required fields are justified
validation is correct but not excessive
output data structure is predictable
downstream dependencies are tested

Common mistakes #

overloading one widget with multiple goals
writing unclear prompts with no action direction
collecting data that is never used
inconsistent output structure between similar widgets

Design tip #

Design widgets as reusable interaction patterns, not one-off UI blocks.
This keeps journeys easier to scale, maintain, and optimize.

What is Zirpa? #

Zirpa is a workflow platform for building guided candidate journeys from first interaction to final outcome.
It helps teams design a process once, run it consistently, and improve it over time using real operational data.

Need setup help first? Start with the Getting Started docs or explore Core Concepts.

Logo

Why Zirpa exists #

Many teams run candidate journeys through disconnected tools (forms, email, chat, spreadsheets, manual follow-ups).
This creates inconsistent experiences, slower response times, and limited visibility.

Zirpa solves this by putting journey logic, step configuration, and candidate interaction flow in one system.

Common problems Zirpa addresses #

Inconsistent process across brands or recruiters
Manual handoffs between teams
Delayed follow-up actions
Missing audit trail for decisions and status changes
Difficulty scaling without lowering quality

How Zirpa works #

At a high level, Zirpa has two connected layers: configuration and execution.

Configuration layer (Brand) #

Teams configure:

Journey structure
Decision points and routing rules
Step content and widgets
Branding and appearance
Integrations and outbound actions

For integration examples, see Integrations docs.

Execution layer (Runner) #

Candidates complete the journey through a guided runner that:

Presents each step in sequence
Captures structured responses
Applies validation and conditions
Moves candidates through defined outcomes

For troubleshooting real journeys, visit Troubleshooting.

Core concepts #

What is an Agent?

Top-level container for one journey design, settings, and path logic.

What is a Path?

Ordered flow a candidate follows for a specific business goal.

What is a Gate?

Decision point that routes candidates based on rules and responses.

What is a Widget?

Functional building block used in each step, including forms and actions.

Forgot Password #

Definition #

Forgot Password is the recovery flow for users who cannot access their account with current credentials.

Why it matters #

Fast and secure recovery reduces downtime and support dependency.

How it works #

Open Forgot Password.
Submit account email.
Receive reset instructions.
Set a new password and sign in.

Configuration fields #

Account email
New password
Confirm password

Example scenario #

A support user resets access after password expiry and resumes operational tasks.

Common mistakes #

Using unregistered email
Expired reset link
Password policy mismatch

Troubleshooting checklist #

Request a fresh reset email
Complete reset immediately after receiving link
Ensure new password meets policy
Contact admin if lockout persists

Create an Account #

Definition #

Create an Account is the first step to access Zirpa and start building journeys.

Why it matters #

A correct account setup ensures proper access, email verification, and role assignment from day one.

How it works #

Open the sign-up page.
Enter name, email, and password.
Verify your email.
Sign in and continue onboarding.

Configuration fields #

Full name
Work email
Password
Terms acceptance

Example scenario #

A new operations manager signs up with a company email, verifies account ownership, and receives access to the team workspace.

Common mistakes #

Using an invalid email domain
Weak password format
Skipping email verification

Troubleshooting checklist #

Check spam/junk folder for verification email
Confirm email is typed correctly
Request a new verification link
Contact admin if domain is restricted

Account and Access Basics #

Definition #

Account and Access Basics explains the minimum account concepts users need before working with agents and journeys.

Why it matters #

Users who understand access scope avoid permission confusion and reduce setup delays.

How it works #

Access depends on account identity, role assignment, and workspace/brand scope.

Configuration fields #

User profile
Role type
Brand scope
Access level

Example scenario #

A support user can inspect workflows but cannot perform restricted production changes without elevated permission.

Common mistakes #

Assuming all users have identical access
Not switching to correct brand/workspace context
Misunderstanding role limitations

Troubleshooting checklist #

Confirm active role
Confirm current workspace/brand
Check action-level permission required
Ask admin for role update if needed

First-Time Onboarding #

Definition #

First-Time Onboarding is the guided setup sequence shown after initial access to help users become productive quickly.

Why it matters #

Good onboarding reduces setup errors and shortens time-to-first-agent.

How it works #

Confirm profile details.
Select brand/workspace context.
Review default settings.
Create first agent draft.
Run a basic test flow.

Configuration fields #

Profile name and contact
Default workspace/brand
Notification preferences
Starter template selection

Example scenario #

A new team member completes onboarding, creates a starter agent, and shares it for review on the same day.

Common mistakes #

Skipping default workspace selection
Starting with complex agent design too early
No test run before sharing

Troubleshooting checklist #

Verify onboarding completion status
Revisit skipped setup sections
Start from a minimal template
Test one simple journey before scaling

Path Steps #

Definition #

Path Steps are the ordered units of interaction inside a Path.
Each step defines what the candidate sees, what data is collected, and how progression moves forward.

Why it matters #

Step order directly impacts completion rate, clarity, and data quality.
Well-structured steps reduce friction and improve decision confidence in later routing.

How it works #

Candidate enters a Path.
Steps are rendered in configured order.
Each step captures or confirms data.
Saved values become input for next steps or gates.
Path exits when completion or routing condition is met.

Configuration fields #

Step label and type
Step order
Required vs optional behavior
Data save target (field, metadata, variable)
Validation rules
Display and prompt content
Forward/backward navigation behavior

Example scenario #

A qualification path uses:

contact confirmation
options selection (territory)
form completion
final confirmation before routing to the next path.

Common mistakes #

Putting multiple decisions in one step
Saving values to inconsistent targets
Breaking progression with incorrect order
Missing validation for required fields
Not testing back-navigation behavior

Troubleshooting checklist #

Verify step order in path configuration
Confirm each step saves expected values
Validate merge rendering on next step
Reproduce with clean candidate data
Check required fields and validation results
Confirm progression API response behavior

Gate Routing Rules #

Definition #

Gate Routing Rules determine which path a candidate enters next based on defined conditions and available signals.

Why it matters #

Gates are the core of dynamic journeys.
Without clear routing rules, candidates can be misrouted, outcomes become unreliable, and reporting loses meaning.

How it works #

A candidate reaches a Gate checkpoint.
The system evaluates configured conditions in order.
First matching rule (or highest priority rule) is applied.
Candidate is routed to the target path/outcome.
If no rule matches, fallback logic is used.

Configuration fields #

Gate rule priority/order
Condition source (field/metadata/variable)
Operator (equals, contains, range, etc.)
Expected value(s)
Target path/outcome
Fallback route
Rule status (enabled/disabled)

Example scenario #

A Gate evaluates budget and territory readiness:

If budget >= threshold and territory confirmed → Path A
If partially ready → Path B
Else → Nurture Path

Common mistakes #

Overlapping rules with unclear priority
No fallback route defined
Comparing mismatched data types
Referencing wrong metadata keys
Updating rules without regression tests

Troubleshooting checklist #

List all active rules and their order
Confirm actual runtime input values
Validate operator/value compatibility
Check which rule matched in logs
Verify fallback execution when no match
Re-test with controlled candidate payloads

Path Outcomes #

Definition #

Path Outcomes are the business results assigned when a candidate finishes a path or satisfies defined routing conditions.

Why it matters #

Outcomes convert journey behavior into actionable business states.
They drive operational follow-up, analytics, and downstream automation.

How it works #

Candidate progresses through a path.
Completion or gate conditions are evaluated.
Outcome is assigned based on configured logic.
Post-outcome actions (notifications, handoff, reporting) run.
Journey continues or ends depending on design.

Configuration fields #

Outcome label
Trigger condition
Priority (if multiple outcomes possible)
Target next path (optional)
Completion behavior (end/continue)
Notification or integration hooks
Visibility in reporting dashboards

Example scenario #

At end of path:

“Qualified” → schedule next engagement
“Needs Follow-up” → route to nurture path
“Not Eligible” → complete journey with specific completion message

Common mistakes #

Too many similar outcomes
Missing trigger precedence
No clear mapping to operational actions
Inconsistent outcome naming between agents
Skipping verification after path edits

Troubleshooting checklist #

Verify expected outcome per scenario
Check condition inputs at decision time
Confirm outcome assignment in logs/data
Validate post-outcome action execution
Compare staging vs production behavior
Re-run end-to-end tests after fixes

Path and Gate Design Patterns #

Definition #

Path and Gate Design Patterns are reusable journey structures for common routing and qualification needs.

Why it matters #

Patterns reduce design mistakes, speed up implementation, and make maintenance easier across multiple agents.

How it works #

Teams apply a selected pattern, then customize rule thresholds, path content, and outcomes for their business context.

Configuration fields #

Pattern type (linear, branch, funnel, recovery)
Gate checkpoints
Path depth and split count
Fallback and re-entry behavior
Outcome map
Monitoring signals per branch

Example scenario #

A “Qualification Funnel” pattern:

Path 1: baseline checks
Gate 1: fit decision
Path 2A: fast-track qualified
Path 2B: nurture for partial fit
Path 2C: close-out for non-fit

Common mistakes #

Over-branching too early
Deep nesting without fallback paths
Reusing gates with conflicting logic
No documentation for branch intent
Ignoring branch-level analytics

Troubleshooting checklist #

Visualize current path/gate map
Validate each branch purpose
Ensure every gate has deterministic fallback
Test one scenario per branch minimum
Track drop-off point by branch
Simplify branches with low operational value