> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Budget Creation Wizard - Admin Guide

> This guide covers configuration and administration for the Budget Creation Wizard.

## Overview

This guide covers configuration and administration for the FA-UX-03 Budget Creation Wizard.

## Permission Requirements

| Permission          | Description        | Required For                |
| ------------------- | ------------------ | --------------------------- |
| `fa.budget.create`  | Create new budgets | Accessing the wizard        |
| `fa.budget.view`    | View budgets       | Viewing budget list         |
| `fa.budget.edit`    | Edit budgets       | Modifying draft budgets     |
| `fa.budget.approve` | Approve budgets    | Approving submitted budgets |
| `fa.budget.delete`  | Delete budgets     | Removing draft budgets      |

### Assigning Permissions

1. Navigate to **Platform Settings → Roles & Permissions**
2. Select or create a role (e.g., "Budget Manager")
3. Enable the `fa.budget.*` permissions as needed
4. Assign the role to appropriate users

***

## Configuration

### Module Settings

The wizard uses PF-41 Configurable Module Wizards infrastructure. No separate module settings are required.

Standard FA module settings that affect budgets:

* **Default Budget Version Type**: Set in FA Module Settings
* **Fiscal Year Configuration**: Required before creating budgets

### Wizard Template

The wizard template is stored in `pf_wizard_templates` with:

* **Module**: `fa`
* **Wizard Type**: `budget_creation`
* **Steps**: 4 steps (header, template, lines, review)

***

## Customization (Future)

Once PF-41 wizard builder is fully deployed, organizations can customize:

| Customization    | Status     | Description                        |
| ---------------- | ---------- | ---------------------------------- |
| Step order       | 🔜 Planned | Reorder or hide steps              |
| Required fields  | 🔜 Planned | Mark additional fields as required |
| Validation rules | 🔜 Planned | Add custom validation              |
| Default values   | 🔜 Planned | Pre-populate fields                |

***

## Monitoring

### Viewing Wizard Drafts

Wizard drafts are stored in the PF-41 infrastructure:

1. Navigate to **Platform Admin → Wizards**
2. Filter by module: `fa`
3. View active drafts and their status

### Draft Expiration

* **Default expiration**: 30 days
* Drafts older than 30 days are automatically cleaned up
* Users will see a resume prompt when returning to the wizard

### Audit Trail

Budget creation actions are logged:

| Event                  | Log Location              | Details               |
| ---------------------- | ------------------------- | --------------------- |
| Wizard started         | `fa_activity_log`         | User, timestamp       |
| Draft saved            | `pf_wizard_drafts`        | Step progress, values |
| Budget created         | `fa_budgets`              | Full record           |
| Lines created          | `fa_budget_lines`         | Line items            |
| Submitted for approval | `fa_budgets.submitted_at` | Submission timestamp  |

***

## Best Practices

### Before Budget Season

1. **Configure Fiscal Years**
   * Ensure next fiscal year is created in FA-01
   * Verify fiscal periods are generated

2. **Approve Prior Year Budgets**
   * Only approved budgets can be used as templates
   * Review and approve any pending budgets

3. **Verify Chart of Accounts**
   * Ensure all needed accounts are active
   * Add any new expense/revenue accounts

### Training Recommendations

1. **For Finance Controllers**
   * Template copying with growth percentages
   * Scenario planning (Best Case / Worst Case)
   * Multi-department budget entry

2. **For Department Managers**
   * Basic budget line entry
   * Saving and resuming drafts
   * Understanding approval workflow

### Performance Considerations

For large budgets (500+ lines):

* Consider using the bulk import feature (FA-08) instead
* Template copying is optimized for large line counts
* Growth calculations happen on the server side

***

## Troubleshooting

### Common Admin Issues

#### Users Can't Access Wizard

**Check:**

1. User has `fa.budget.create` permission
2. User is in the correct organization context
3. Route is properly configured in navigation

#### Template Budgets Not Appearing

**Check:**

1. Source budgets have status `approved`
2. Source budgets belong to the same organization
3. RLS policies are correctly configured

#### Approval Submission Fails

**Check:**

1. FW-03 approval workflow is configured
2. Budget approvers are assigned
3. User has `fa.budget.approve` or is in approval chain

### Database Verification

```sql theme={null}
-- Check wizard template exists
SELECT * FROM pf_wizard_templates 
WHERE module = 'fa' AND wizard_type = 'budget_creation';

-- Check approved budgets available as templates
SELECT id, version_name, status, fiscal_year_id 
FROM fa_budgets 
WHERE organization_id = '<org_id>' 
AND status = 'approved';

-- Check recent wizard drafts
SELECT * FROM pf_wizard_drafts 
WHERE module = 'fa' 
ORDER BY updated_at DESC 
LIMIT 10;
```

***

## Security Considerations

### Data Access

* All budget queries include `organization_id` filter (defense-in-depth)
* RLS policies enforce tenant isolation
* Template copying only works within same organization

### PHI/PII

* Budget data does not contain PHI
* User IDs are stored for audit (created\_by, approved\_by)
* No external data transmission

### Audit Requirements

For SOX compliance:

1. All budget modifications are timestamped
2. Approval chain is documented in `fa_budgets`
3. Changes after approval require new version

***

## Integration Points

### FA-01: Chart of Accounts

* Provides accounts, funds, departments, programs
* Fiscal year and period definitions

### FA-08: Budget Management

* `useCreateBudget` hook for budget creation
* `useBulkCreateBudgetLines` for line insertion
* `useSubmitBudgetForApproval` for workflow

### FW-03: Approval Workflows

* Budget submission triggers approval workflow
* Approvers receive notifications
* Status updates flow back to budget

### PF-41: Configurable Wizards

* Step rendering and navigation
* Draft persistence
* Progress tracking

***

## Related Documentation

* [Budget Creation Wizard - User Guide](/fa/budget-creation-wizard-user-guide)
* [FA Module Settings](/fa/module-settings)
* [Chart of Accounts Guide](/fa/chart-of-accounts-guide)
* [FA Security Considerations](/fa/security-considerations)