README.md 4.56 KB
Newer Older
Marcello Pivanti's avatar
Marcello Pivanti committed
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
Amos Workflow
========

The module Workflow is used in order to manage workflow status transitions on records useing a workflow.
Amos Workflow is based on:
- raoul2000/yii2-workflow
- cornernote/yii2-workflow-manager

Installation
------------

1. The preferred way to install this extension is through [composer](http://getcomposer.org/download/).

Either run

```bash
Aster's avatar
Aster committed
17
composer require arter/amos-workflow
Marcello Pivanti's avatar
Marcello Pivanti committed
18
19
20
21
22
```

or add this row

```
Aster's avatar
Aster committed
23
"arter/amos-workflow": "dev-master"
Marcello Pivanti's avatar
Marcello Pivanti committed
24
25
26
27
28
29
30
31
32
33
```

to the require section of your `composer.json` file.

2. Add module to your modules config in backend:
	
    ```php
    
    'modules' => [
        'workflow' => [
Aster's avatar
Aster committed
34
           'class' => 'arter\amos\workflow\AmosWorkflow',
Marcello Pivanti's avatar
Marcello Pivanti committed
35
36
37
38
39
40
41
42
        ],
    ],
    ```

3. Apply migrations

    a. amos-workflow migrations
    ```bash
Aster's avatar
Aster committed
43
    php yii migrate/up --migrationPath=@vendor/arter/amos-workflow/src/migrations
Marcello Pivanti's avatar
Marcello Pivanti committed
44
45
46
47
48
49
50
51
52
    ```
    
    or add this row to your migrations config in console:
    
    ```php
    return [
        .
        .
        .
Aster's avatar
Aster committed
53
        '@vendor/arter/amos-workflow/src/migrations',
Marcello Pivanti's avatar
Marcello Pivanti committed
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
        .
        .
        .
    ];
    ```
    
Configuration
------------

//TODO translate-fix this section

Ogni cambio di stato del workflow viene intercettato come evento e viene scritta un record di log nella tabella workflow_transition_log (vedere *WorkflowLogFunctionsBehavior*).

**Define model workflow**  
Il workflow classico in amos4 comprende gli stati:

* bozza /draft
* da validare/richiesta pubblicazione
* validato/pubblicato

Per automatizzare/standardizzare alcune operazioni è stata creata in amos-core l'interfaccia WorkflowModelInterface che è bene implementare, insieme ad estendere NotifyRecord per beneficiare ad esempio delle mail automatiche alla richiesta di validazione del modello.

Il workflow del model viene definito tramite il popolamento delle tabelle:

* sw_workflow: 
definizione id del workflow, per convenzione in amos 4 è il nome del model seguito da 'Workflow' es. 'NewsWorkflow'. 
Definizione dello stato iniziale di default, eventualmente modificabile da interfaccia o tramite migration. Es initial_status_id = 'DRAFT'

* sw_status: 
Definizione degli stati del workflow. Lo stato verrà salvato (come convenzione) nel campo status del model concatendo Workflow_id / status_id ad esempio 'NewsWorkflow/BOZZA'

* sw_transition:
definizione delle transizioni, ossia di tutti i possibili passaggi di stato. 
IMPORTANTE: l'errore non esiste la transizione tra stato A e stato B che potreste riscontrare, se avete definito la transizione è in realtà dovuto alla mancanza del permesso dell'utente salvare il modello in quello stato.

* sw_metadata:
per ogni stato del workflow definisce label sui bottoni di cambio stato, testi dei popup, classi css, ecc.
E' possibile anche commentare il passaggio di stato e salvare tale nota/commento nei log di passaggio di stato.

To enable workflow event behavior, insert in your model behavior array eg.

```php
 public function behaviors()
{
    return ArrayHelper::merge(parent::behaviors(), [
        .
        .
        .
        'workflow' => [
            'class' => SimpleWorkflowBehavior::className(),
            'defaultWorkflowId' => self::NEWS_WORKFLOW,
            'propagateErrorsToModel' => true
        ]
    ];
}
```
Widgets
-----------

Amos Workflow provides three Widgets:

* **WorkflowTransitionButtonsWidget** 
* **WorkflowTransitionStateDescriptorWidget**

//TODO explain/example of use for new widgets above

Aster's avatar
Aster committed
120
* **WorkflowTransitionWidget** *arter\amos\workflow\widgets\WorkflowTransitionWidget*  
Marcello Pivanti's avatar
Marcello Pivanti committed
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
Draws a section containing model current status and the buttons with possible status to change starting from the current one (reading from sw_metadata).  
***Comment / notes on status change***  
If needed, it is possible to show a popup to insert comment/notes on status change; to enable the functionality add in sw_metadata for the transition final status the metadata: key ='comment', value = 1

It is possible to use a global parameter to hide all transition widgets, if the model workflows are bypassed.
Insert between your application backend params array:
```php
    return [
        .
        .
        .
        'hideWorkflowTransitionWidget' => true
        .
        .
        .
    ];
    ```



example of use in a form:
```php
    <?= WorkflowTransitionWidget::widget([
        'form' => $form,
        'model' => $model,
        'workflowId' => ShowcaseProject::SHOWCASEPROJECT_WORKFLOW,
        'classDivIcon' => 'pull-left',
        'classDivMessage' => 'pull-left message',
        'viewWidgetOnNewRecord' => true,
        'translationCategory' => 'amosshowcaseprojects'
    ]); ?>
```