Šablóny workflow

Opakovane používané nastavenie pravidla, kvóra, stupňov a expirácie uložte do config('approvals.workflows') a volania zostanú krátke. Šablóna je jednostupňová (jedno pravidlo) alebo viacstupňová (zoznam stages):

use RoundlyConsulting\Approvals\Enums\ApprovalRule;

'workflows' => [
    'payout' => [
        'rule' => ApprovalRule::Quorum->value,
        'quorum' => 2,
        'required_approvers' => 3,
        'expiry' => 86400,
    ],
    'release' => [
        'reject_on_stage_rejection' => true,
        'stages' => [
            ['rule' => ApprovalRule::Unanimous->value, 'required_approvers' => 2, 'name' => 'engineering'],
            ['rule' => ApprovalRule::Any->value,       'required_approvers' => 1, 'name' => 'product'],
        ],
    ],
],

Otvorenie žiadosti zo šablóny

use RoundlyConsulting\Approvals\Facades\Approvals;

// Flat preset: a single approver list.
Approvals::request($budget)->workflow('payout')->open([$a, $b, $c]);

// Staged preset: one approver group per stage, in order.
Approvals::request($release)->workflow('release')->open([[$eng1, $eng2], [$product]]);

// Read a validated preset without opening anything.
Approvals::preset('payout');   // WorkflowPreset

open() vráti otvorenú ApprovalRequest. Žiadosť uloží názov šablóny do stĺpca workflow a expirácia zo šablóny nechá žiadosť vypršať rovnako ako expiresIn().

Kľúče šablóny

Nastavenia, ktoré definuje šablóna

Šablóna definuje pravidlo kola, kvórum, stupne aj správanie pri zamietnutom stupni a schvaľovateľov prijíma v open(). Preto workflow() vyhodí InvalidApprovalRequestException, ak ste na builderi žiadosti predtým zavolali from(), rule(), any(), quorum(), weighted(), stages() alebo continueOnRejection() — aj s predvolenou hodnotou. Správa vymenuje každé z nich a nič sa neotvorí:

// Refused: the preset would ignore from(), so none of them would be a named approver.
Approvals::request($payout)->from([$cfo, $controller, $treasurer])->workflow('payout')->open();
// InvalidApprovalRequestException: The approval workflow preset [payout] defines the rule, quorum,
// stages and stage rejection itself and takes its approvers in open(), so [from()] cannot be set
// before workflow(). Pass the approvers to open($approvers) instead of from().

// Supported: name the approvers in open().
Approvals::request($payout)->workflow('payout')->open([$cfo, $controller, $treasurer]);

Pred verziou 1.2.1 workflow() tieto nastavenia potichu zahodil: kolo otvorené cez ->from([...])->workflow('payout')->open() nemalo menovaných schvaľovateľov, takže pri pravidle šablóny, ktoré mená nepotrebuje (any, kvórum či required_approvers), oň mohol rozhodnúť ktorýkoľvek schvaľovateľ. Kolá otvorené takto pred aktualizáciou menovaných schvaľovateľov stále nemajú — skontrolujte tie, ktoré sú ešte otvorené.

Vlastný termín kola

Od verzie 1.2.0 môže kolo otvorené zo šablóny dostať vlastný termín. Nastavíte ho na builderi šablóny alebo na builderi žiadosti pred workflow() — expirácia je jediné nastavenie buildera žiadosti, ktoré sa prenesie:

// On the workflow builder.
Approvals::request($payout)->workflow('payout')->expiresIn(3600)->open([$a, $b, $c]);
Approvals::request($release)->workflow('release')->expiringAt(now()->addWeek())->open([[$eng1, $eng2], [$pm]]);

// On the request builder, before workflow(); the expiry carries over.
Approvals::request($payout)->expiresIn(3600)->workflow('payout')->open([$a, $b, $c]);

• Termín volajúceho má prednosť — nahradí expiry šablóny len pre toto kolo; šablóna sama sa nemení. Ak expiráciu nastavíte viackrát, pred workflow() či po ňom, platí posledná.
• Bez neho sa nič nemení — kolo dostane expiry šablóny, rátané od otvorenia, alebo žiadny termín, ak ho šablóna nemá.
• Jeden termín na kolo, viacstupňové či nie — je to expires_at žiadosti. Stupeň, ktorý sa otvorí neskôr, ho zdieľa a nezačína odznova; po jeho uplynutí sa celá žiadosť číta ako expirovaná, nech je otvorený ktorýkoľvek stupeň.
• Každé kolo sa otvára samostatne — ďalšie kolo z tej istej šablóny dostane opäť expiry šablóny, ak si volanie nenastaví vlastný termín.
• expiresIn($seconds) sa ráta od okamihu volania, rovnako ako na builderi žiadosti. Akcia prijíma termín ako štvrtý argument — OpenWorkflowRequestAction::execute($subject, $preset, $approvers, $expiresAt) — kde null ponechá expiry šablóny.

Zoznamy schvaľovateľov

• Jednostupňová šablóna — odovzdajte plochý zoznam schvaľovateľov; tí sa stanú menovanými schvaľovateľmi žiadosti. required_approvers šablóny je počet potrebných schválení, ak je nastavené, inak jedno na schvaľovateľa.
• Viacstupňová šablóna — odovzdajte jednu skupinu schvaľovateľov na stupeň, v poradí stupňov; počet skupín sa musí rovnať počtu stupňov. required_approvers stupňa je počet schválení, ktoré potrebuje, preto ich jeho skupina musí vymenovať aspoň toľko.
• Zoznam, ktorý vymenuje menej schvaľovateľov, než je required_approvers, vyhodí pri otvorení žiadosti InvalidApprovalRequestException.
• O jednostupňovej šablóne otvorenej cez open([]) môže rozhodnúť ktokoľvek, ak sa jej pravidlo dá splniť aj bez mien — cez required_approvers, kvórum alebo pravidlo any. Inak otvorenie vyhodí InvalidApprovalRequestException.

Validácia

Neznáma alebo chybná šablóna vyhodí UnknownWorkflowException — chýbajúci názov, šablóna, ktorá nie je pole, prázdny zoznam stages, stupeň bez kladného celočíselného required_approvers, neceločíselné quorum, required_approvers či expiry, expiry menšie ako 1, nereťazcový name stupňa, reject_on_stage_rejection, ktoré nie je booleanom ani jeho textovým zápisom, neznáme pravidlo alebo viacstupňová šablóna otvorená s nesprávnym počtom skupín. Voliteľný kľúč šablóny ponechaný prázdny ('') sa považuje za nenastavený a dostane predvolenú hodnotu: unanimous pre rule, žiadnu pre quorum, expiry a name, true pre reject_on_stage_rejection. Hodnota workflows, ktorá nie je pole, namiesto toho vyhodí InvalidConfigurationException.