إنتقل إلى المحتوى الرئيسي

Workflow Specification Template

Status: ✅ ACTIVE Purpose: Standard template for documenting all workflows in workflows/ folder

Purpose​

This template ensures consistency across all workflow specifications. Each workflow in workflows/ should follow this structure.

Template Structure​

# [Workflow Name]

## Metadata
- **Phase:** [Phase number]
- **FWCR Category:** [Invoice-to-Cash | Expense-to-Pay | PO-to-Payment]
- **Owner:** [Team]
- **Status:** [Planned | In Progress | Complete]

## Overview
[2-3 sentence description of what this workflow accomplishes]

## Actors
| Role | Description |
|------|-------------|
| [Role 1] | [Brief description] |
| [Role 2] | [Brief description] |

## Preconditions
- [ ] [Prerequisite 1]
- [ ] [Prerequisite 2]

## Postconditions
- [ ] [Outcome 1]
- [ ] [Outcome 2]

## User Flow

### Happy Path
1. [Step 1 - Action]
2. [Step 2 - System Response]
3. [Step 3 - Action]
...

### Error Scenarios
| Scenario | Handling |
|----------|----------|
| [Error 1] | [Resolution] |
| [Error 2] | [Resolution] |

## Acceptance Criteria
| # | Criteria | Test Scenario |
|---|----------|---------------|
| 1 | [Criteria 1] | [Given/When/Then] |
| 2 | [Criteria 2] | [Given/When/Then] |

## Compliance Requirements
- [ ] [ZATCA field mapping]
- [ ] [PDPL considerations]
- [ ] [Audit trail requirements]

## Technical Notes
| Component | Implementation |
|-----------|----------------|
| [Frontend] | [Notes] |
| [API/Middleware] | [Notes] |
| [ERPNext] | [Notes] |
| [AI] | [Notes] |

## Metrics
| Metric | Target | Measurement |
|--------|--------|-------------|
| [Metric 1] | [Target] | [How to measure] |

## Dependencies
| Dependency | Status | Notes |
|------------|--------|-------|
| [Dep 1] | [Ready/Planned] | [Notes] |

## Related Documents
| Document | Link |
|----------|------|
| [Doc 1] | [Link] |

---

## Example: Completed Workflow

```markdown
# Invoice-to-Cash Workflow

## Metadata
- **Phase:** Phase 2
- **FWCR Category:** Invoice-to-Cash
- **Owner:** Product Team
- **Status:** Planned

## Overview
This workflow handles the complete sales order-to-ZATCA clearance cycle,
ensuring all invoices are cryptographically stamped before delivery.

## Actors
| Role | Description |
|------|-------------|
| Sales Rep | Creates quotations and sales orders |
| Accountant | Reviews and submits for ZATCA clearance |
| System | Generates XML, calls ZATCA API, attaches stamp |

## Preconditions
- [ ] Customer master exists
- [ ] Product/pricing configured
- [ ] ZATCA credentials configured

## Postconditions
- [ ] Invoice cleared by ZATCA
- [ ] PDF with stamp attached
- [ ] AR entry created

Writing Guidelines​

Use Active Voice​

"The system generates XML" not "XML is generated by the system"

Be Specific​

"Invoice rejected due to missing buyer's building number" not "Invoice error"

Include System Responses​

User actions + System responses = Complete flow

Every financial workflow must reference relevant ZATCA/PDPL requirements

Keep Testable​

Every acceptance criterion should be testable with Given/When/Then

Checklist for New Workflow​

Before marking a workflow as complete, verify:

  • All actors identified
  • Happy path has no gaps
  • Error scenarios cover edge cases
  • Acceptance criteria are testable
  • Compliance requirements mapped
  • Technical notes reviewed with Engineering
  • Metrics defined with measurable targets
  • Cross-references to related documents

Document Status​

Status: ✅ ACTIVE Last Updated: May 2026 Next Review: Annually or on workflow redesign