One approval engine for the whole platform
HR requests could easily have shipped with their own little approval engine — a status column, a manager field, an email. Almost every HR product does exactly that. DWPlatform does not, and the reason is worth stating before anything else on this page makes sense.
DWPlatform HR
- The request data — what was asked for, by whom, for which dates or amount
- The validation — balance, overlaps, statutory caps and ceilings
- The effects — posting to the leave ledger, building an instalment schedule, opening an assignment row
DWPlatform WorkFlow
- The approval chain — the stages, who sits at each, and in what order
- The inbox — one place where every pending decision in the platform lands
- The designer — where a tenant reshapes a chain without a developer
A second approval engine inside HR would give the platform two inboxes. A manager would check one place for purchase approvals and correspondence, and a different place for their team's leave — and would miss things in whichever one they check less. It would also give the platform two sets of routing bugs, two delegation implementations, two escalation timers and two audit formats, all of which have to be fixed twice and will drift. So HR ships the chains it needs, and then hands ownership of them over.
The nine seeded chains
A new tenant does not start with a blank workflow designer and a request form that goes nowhere. Nine default chains are seeded, verified live, and immediately usable — then handed to the tenant to reshape.
| Chain | Stages | Covers |
|---|---|---|
HR_LEAVE | 3 | Leave and leave cancellation (إجازة) |
HR_LOAN | 4 | Advances (سلفة) — money leaves the company, so finance is in the chain |
HR_AID | 3 | Aid grants (إعانة) |
HR_LETTER | 2 | Letters and certificates (خطاب) — no manager stage; HR issues them |
HR_MISSION | 4 | Missions and business travel (مأمورية) |
HR_ATTENDANCE_ADJUSTMENT | 3 | Corrections to attendance records |
HR_RESIGNATION | 3 | Resignation |
HR_TRANSFER | 2 | Transfer (نقل) |
HR_PERSONAL_DATA | 2 | Changes to personal data, bank account, marital status |
The shape they all share
Read the stage counts and one pattern falls out. Every chain begins with a submission stage. Most then go to the direct manager, because the person who has to cover the absence should know about it first. Then HR, who check the rules and hold the record. And where money moves, a fourth stage adds finance — which is exactly why HR_LOAN and HR_MISSION have four stages and HR_LEAVE has three.
The two-stage chains drop the manager rather than HR: a letter request (خطاب) or a bank-account change does not need a manager's opinion, it needs HR to act.
These are defaults, not rules. Every one of the nine is edited in the WorkFlow back office like any other chain — add a department-head stage, remove finance, change who counts as the approver, add an escalation. HR seeds the chain it needs on day one so nothing is broken out of the box, and then never owns it again. A tenant whose leave approvals go straight to HR with no manager stage is not fighting the product; they are configuring it.
Why every chain starts with an explicit submission stage
The first stage of all nine chains does nothing. It has no approver, it makes no decision, and it exists entirely because of how the engine behaves on creation.
When a workflow instance is created, the engine auto-applies the first stage's default action. That is sensible behaviour — it is what lets a chain start moving without an extra click. But it means the first stage in the list gets resolved the instant the request is created, before any human has seen it.
Without a submission stage
Stage 1 is Direct manager. The engine auto-applies its default action on create. The manager's stage is approved at the moment of submission, by nobody, and the request lands on HR's desk already carrying a manager's approval that never happened.
With a submission stage
Stage 1 is Submission. The engine auto-applies that — which is correct, because submitting is exactly what the employee just did. The request then advances to the manager's stage and waits for a human, which is the entire point of an approval chain.
It is a one-row difference in a seed script and it is the difference between an approval chain and a rubber stamp. It is also the first thing to check when a tenant redesigns a chain in the workflow back office: delete the submission stage and the first real approver is silently skipped.
The five states of a request
A request is not "pending" then "done". It moves through five states, and each one exists because something can go wrong between it and the next.
Being filled in. Belongs to the employee; nobody else can see it.
Validated and handed to the workflow engine. مقدّم
Sitting at a stage, waiting for a person. قيد الاعتماد
The decision is made. Nothing has happened to the data yet.
The effect has actually been written. The request is finished.
An approver sends it back rather than rejecting it. The employee fixes and resubmits — the history of who asked for what stays attached.
A terminal decision. The request keeps its full trail; nothing is applied.
HR_LEAVE instance; choosing سلفة starts an HR_LOAN one, with its extra finance stage.Why Approved and Applied are different states
This is the state pair people want to collapse, and collapsing it is how requests get lost. A decision and its consequence happen at different times, in different services, and either one can succeed while the other has not yet.
- The final approver taps approve.
The workflow engine records the decision and marks the request Approved. That is a fact about a human, and it is now permanent.
- An approval event is published.
Durable, on the bus — not an inline call into HR.
- An idempotent consumer applies the effect.
Post the days to the leave ledger; build the loan's instalment schedule; close one assignment row and open the next. Idempotent matters: if the event is delivered twice — and at-least-once delivery means it can be — the second attempt changes nothing.
- The request becomes Applied.
Only now is it finished, and only now does a balance actually move.
- A reconcile pass retries anything stuck.
Requests sitting in Approved longer than they should are picked up and re-applied.
The payoff: a failed apply leaves the request visibly unfinished rather than silently lost. If Approved and Applied were one state, a consumer that crashed mid-write would leave a request marked done with a balance that never moved — invisible until an employee notices their leave was never deducted, months later, with no evidence of what happened. Two states make the gap a queryable condition: approved, not yet applied, and the reconcile pass is looking at it.
Why the outcome travels as a durable bus event
The workflow engine could simply call HR's API the moment a chain completes. It does not. The outcome is published as a durable event and consumed asynchronously — and the reason is the one that decides most integration arguments: what happens if the other side is down?
An inline call
The manager taps approve at 22:40, during the HR service's deploy window. The call fails. Now the platform must choose between two bad outcomes: lose the decision, or fail the approval and ask the manager to make it again tomorrow — having already told them it went through.
A durable event
The decision is recorded and published. The broker holds it. HR comes back up, consumes it, applies the effect, and the request moves to Applied. The manager's evening is unaffected and nobody is asked to decide anything twice.
Put as a principle: a decision that was made must not be lost, and the approver must not be asked to make it again. Those two constraints together rule out the inline call, because an inline call can only satisfy one of them at a time. The same reasoning is why the consumer is idempotent and why the reconcile pass exists — a durable event guarantees delivery at least once, so the receiving side has to be built to tolerate exactly that.
The request matrix
Every request type the module handles, the chain that routes it, and — the column that matters most — what actually changes when it is approved. If a row's effect column is empty, the request is a message rather than a transaction; none of them are.
| Request | Arabic | Chain | What approval changes |
|---|---|---|---|
| Leave | إجازة | HR_LEAVE | Days are posted to the leave ledger and deducted from the balance for that leave year |
| Leave cancellation | إلغاء إجازة | HR_LEAVE | The original posting is reversed and the days return to the balance |
| Hour permission | إذن | HR_LEAVE | Hours away are authorised, so attendance does not record them as lateness or absence |
| Attendance adjustment | تسوية حضور | HR_ATTENDANCE_ADJUSTMENT | The attendance record is corrected — which changes the overtime and absence figures payroll reads |
| Loan / advance | سلفة | HR_LOAN | A loan is opened with an instalment schedule; payroll begins deducting, capped at 25% of wage |
| Aid grant | إعانة | HR_AID | A grant is recorded and paid through payroll as an earning |
| Letters & certificates | خطاب | HR_LETTER | The letter is issued to the employee — salary certificate, employment letter, bank letter |
| Mission / business travel | مأمورية | HR_MISSION | The days are marked as mission rather than absence, and any entitlement is passed to payroll |
| Education allowance | بدل تعليم | HR_AID | The allowance is attached to the employee as a pay element |
| Bank-account change | تغيير الحساب البنكي | HR_PERSONAL_DATA | The bank and IBAN on the employee file are updated — so the next run pays a different account |
| Marital-status change | تغيير الحالة الاجتماعية | HR_PERSONAL_DATA | Marital status and dependants are updated |
| Overtime pre-approval | عمل إضافي | HR_ATTENDANCE_ADJUSTMENT | The extra hours become payable overtime; hours worked without it are not automatically paid |
| Personal-data change | تعديل البيانات الشخصية | HR_PERSONAL_DATA | The requested fields on the employee file are updated, with the request as the evidence |
| Resignation | استقالة | HR_RESIGNATION | An end-of-service case (إنهاء الخدمة) is opened; the employment period is closed on its date |
| Transfer | نقل | HR_TRANSFER | The current assignment row is closed and a new one opened from the effective date |
| Custody | عهدة | HR_PERSONAL_DATA | An asset is booked to the employee — and becomes an item to be cleared at end of service |
| Mission allowance | بدل مهمة | HR_MISSION_ALLOWANCE | The allowance for an already-approved mission is released to payroll as an earning |
| Expense claim | استرداد مصروفات | HR_EXPENSE | A payable is raised and reimbursed through a non-taxable element — repaying a cost is not income |
| Penalty objection | تظلم من جزاء | HR_PENALTY_OBJECTION | Upholding it annuls the sanction — except one already carried into a payslip, which is a retro adjustment rather than a status flip |
| Manpower request | طلب احتياج | HR_MANPOWER | A job requisition is created, already Approved — so a requisition can never exist without the authorisation that produced it |
Read the effect column top to bottom and the pattern is that approval is never the end of the story — every row writes into a ledger, a schedule, a file or a payroll input. That is precisely why the Applied state exists.
Where to go next: the employee's side of these requests — the wizard, the validation and the status view — is covered in Employee Self-Service. The rules the effects have to respect, from leave tiers to the 25% deduction ceiling, are in the HR field guide.