Workflows Overview¶

Workflows are the heart of Zenzero ZAI's automation capabilities. They combine multiple actions into repeatable, reliable sequences that handle complex IT tasks with minimal manual intervention.

What is a Workflow?¶

A workflow is a predefined sequence of actions that automates a business process or IT operation. Instead of manually performing each step, you trigger the workflow and let ZAI execute all steps automatically.

Workflow vs. Individual Actions¶

How Workflows Work¶

graph TB
    A[User Triggers Workflow] --> B[AI Detects Intent]
    B --> C[Load Workflow Definition]
    C --> D[Gather Required Parameters]
    D --> E{All Parameters Available?}
    E -->|No| F[Ask User for Missing Info]
    F --> D
    E -->|Yes| G[Show Approval Card]
    G --> H{User Approves?}
    H -->|No| I[Cancel Workflow]
    H -->|Yes| J[Execute Step 1]
    J --> K{Step Success?}
    K -->|Yes| L{More Steps?}
    L -->|Yes| M[Execute Next Step]
    M --> K
    L -->|No| N[Workflow Complete]
    K -->|No| O[Stop & Report Error]

    style A fill:#4285f4,color:#fff
    style G fill:#f4b400,color:#000
    style N fill:#0f9d58,color:#fff
    style O fill:#ea4335,color:#fff

Workflow Components¶

Every workflow consists of:

Workflow Types¶

1. User Management Workflows¶

Purpose: Create, modify, and manage M365 users

2. License Management Workflows¶

Purpose: Assign and manage M365 licenses

3. Group Management Workflows¶

Purpose: Manage M365 and security groups

4. Mailbox Operations Workflows¶

Purpose: Manage Exchange mailboxes

5. Composite Workflows¶

Purpose: Multi-step business processes

Workflow States¶

Workflows progress through several states across their full lifecycle - from creation through to execution:

Design & Approval States¶

Before a workflow can be triggered by users, it goes through a design and approval lifecycle:

stateDiagram-v2
    [*] --> Draft: Created / Edited
    Draft --> AwaitingReview: Submit for Review
    AwaitingReview --> Approved: Reviewers Approve
    AwaitingReview --> ChangesRequested: Changes Requested
    ChangesRequested --> Draft: Edit in Designer
    Approved --> Active: Admin Activates
    Active --> Draft: Edit in Designer (new draft)

Execution States¶

When a user triggers an active workflow, it progresses through execution states:

stateDiagram-v2
    [*] --> Pending: Workflow Triggered
    Pending --> Approved: User Approves
    Pending --> Cancelled: User Cancels
    Approved --> Running: Execution Started
    Running --> Running: Processing Steps
    Running --> Completed: All Steps Success
    Running --> Failed: Step Error
    Running --> PartialSuccess: Some Steps Failed
    Completed --> [*]
    Failed --> [*]
    PartialSuccess --> [*]
    Cancelled --> [*]

    note right of Running
        Step 1: ✅ Complete
        Step 2: ⏳ Running
        Step 3: ⏹️ Pending
    end note

State Descriptions¶

Step Execution¶

Each workflow step executes sequentially:

Step States¶

graph LR
    A[Pending] -->|Start| B[Running]
    B -->|Success| C[Completed]
    B -->|Error| D[Failed]
    B -->|Timeout| E[Failed]

    style A fill:#ffa500,color:#000
    style B fill:#4285f4,color:#fff
    style C fill:#0f9d58,color:#fff
    style D fill:#ea4335,color:#fff
    style E fill:#ea4335,color:#fff

Step Information¶

For each step, you can see:

• Step Name - What action is being performed
• Status - Pending, Running, Completed, Failed
• Inputs - Parameters passed to the action
• Outputs - Results returned from the action
• Duration - How long the step took
• Error Details - If step failed, why it failed

Example step display:

✅ Step 1: Create M365 User
   Status: Completed
   Duration: 2.3 seconds

   Inputs:
   • tenant_id: ca735f40-c2de-4ec8-9b6f-c96fd3dee932
   • user_principal_name: jane.smith@contoso.com
   • display_name: Jane Smith
   • password: ●●●●●●●●

   Outputs:
   • user_id: 5c3102ee-ec2e-4885-8959-32d739cb90fd
   • user_principal_name: jane.smith@contoso.com
   • password: TempPass123!

Parameter Resolution¶

Workflows intelligently resolve parameters:

Resolution Methods¶

You: Create user jane.smith@contoso.com

Workflow gets:
• user_principal_name: jane.smith@contoso.com ✓

Working in Contoso ticket

Workflow gets:
• tenant_id: ca735f40... ✓ (from ticket)
• company_id: 123 ✓ (from ticket)

Step 1 Output: user_id = abc-123

Step 2 Input:
• user_id: abc-123 ✓ (from step 1)

Workflow Definition:
• force_change_password: true ✓ (default)
• usage_location: GB ✓ (default)

Parameter Flow Example¶

graph LR
    A[User Input:<br/>email, name] --> B[Step 1:<br/>Create User]
    B --> C[Output:<br/>user_id]
    C --> D[Step 2:<br/>Assign License]

    E[Context:<br/>tenant_id] --> B
    E --> D

    F[Defaults:<br/>usage_location] --> B

    style A fill:#4285f4,color:#fff
    style E fill:#f4b400,color:#000
    style F fill:#34a853,color:#fff
    style C fill:#fbbc04,color:#000

Workflow: Create User + Assign License

• User provides: email, display name
• Context provides: tenant_id (from ticket)
• Defaults provide: usage_location = "GB"
• Step 1 provides: user_id (for Step 2)

Workflow Validation¶

Before execution, workflows validate all parameters:

Validation Types¶

Validation Errors¶

If validation fails, you'll see:

❌ Validation Failed

Parameter: user_email
Error: Invalid email format
Value: john.doe (missing domain)
Fix: Provide full email (john.doe@company.com)

Workflow will not execute until fixed.

Real-Time Progress¶

During execution, you see live updates via SignalR:

Progress Indicators¶

⏳ Workflow Running: M365 User Onboarding

✅ Step 1/3: Create M365 User - Completed (2.3s)
⏳ Step 2/3: Assign License - Running...
⏹️ Step 3/3: Add to Groups - Pending

Overall Progress: 33%
Elapsed Time: 5 seconds

Expandable Details¶

Click any step to see:

✅ Step 1: Create M365 User

📥 Inputs:
{
  "tenant_id": "ca735f40...",
  "user_principal_name": "jane.smith@contoso.com",
  "display_name": "Jane Smith",
  "password": "●●●●●●●●"
}

📤 Outputs:
{
  "user_id": "5c3102ee-ec2e-4885-8959-32d739cb90fd",
  "user_principal_name": "jane.smith@contoso.com",
  "password": "TempPass123!",
  "force_change_password_next_sign_in": true
}

⏱️ Duration: 2.3 seconds
✅ Status: Completed successfully

Error Handling¶

Workflows handle errors gracefully:

Error Behaviors¶

Step 1: ✅ Create User
Step 2: ❌ Assign License (error)
Step 3: ⏹️ Add to Group (not executed)

Workflow Status: Failed

Step 1: ✅ Create User
Step 2: ❌ Assign License (error)
Step 3: ✅ Add to Group (executed anyway)

Workflow Status: Partial Success

Error Messages¶

Detailed error information helps troubleshooting:

❌ Step 2 Failed: Assign License

Error Type: Graph API Error
Error Code: Request_BadRequest
Message: License assignment cannot be done for user with invalid usage location

Action: M365_AssignLicense
Step: Assign License
User: jane.smith@contoso.com

Suggestion: Ensure user has usage_location set. Run "Update User Details" first.

📚 Documentation: /docs/troubleshooting#license-assignment

Workflow Outputs¶

Successful workflows return useful data:

Output Types¶

Output Usage¶

You: Create user jane.smith@contoso.com

AI: ✅ Workflow completed!

    Outputs:
    • user_id: 5c3102ee-ec2e-4885-8959-32d739cb90fd
    • password: TempPass123!
    • display_name: Jane Smith

    💡 Tip: Copy the password to share with the user securely.

You: Assign E3 license to that user

AI: Using user_id from previous workflow...
    [Proceeds with jane.smith@contoso.com]

Outputs are remembered in the conversation context.

Common Workflow Patterns¶

Sequential Operations¶

Steps execute in order, each depending on previous:

1. Create User → user_id
2. Assign License (needs user_id)
3. Add to Groups (needs user_id)

Conditional Logic¶

Some workflows have conditional steps:

IF user exists:
    Update user details
ELSE:
    Create new user

THEN:
    Assign license

Parallel Execution¶

Some steps can run simultaneously (future feature):

Step 1a: Assign License 1 ┐
Step 1b: Assign License 2 ├─> All complete
Step 1c: Assign License 3 ┘

Step 2: Add to Groups

Best Practices¶

✅ Do This¶

Review Before Approving

✓ Check all parameters
✓ Verify correct tenant
✓ Confirm user/resource identifiers
✓ Review what will happen

Monitor Execution

✓ Watch progress updates
✓ Review outputs
✓ Check for warnings
✓ Expand failed steps for details

Use Appropriate Workflows

✓ Use composite workflows for common tasks
✓ Chain individual workflows for custom needs
✓ Request new workflows for frequent operations

❌ Avoid This¶

Skipping Validation

✗ Clicking approve without reading
✗ Ignoring warning messages
✗ Not checking tenant context

Abandoning Failed Workflows

✗ Not reading error messages
✗ Retrying without fixing the issue
✗ Not reporting recurring errors

Misusing Workflows

✗ Using workflows for one-off manual changes
✗ Forcing workflows when simple action works
✗ Modifying sensitive parameters without understanding

Workflow vs. Manual Actions¶

When to use each:

Quick Reference¶

Workflow Lifecycle¶

Design: Draft → Review & Approval → Active

Execution: Trigger → Parameter Collection → Approval → Execution → Completion

Common Workflows Quick Access¶

Next Steps¶

Learn more about workflows:

• Running Workflows - Step-by-step guide to executing workflows
• Workflow Review & Approval - Review process, notifications, and approval decisions
• Workflow History - Review past workflow executions
• Common Workflows - Detailed guide to frequently used workflows
• Creating Workflows - Build custom workflows