Controllo di flusso predefinito (Default Workflow)

Nel Capitolo 3 abbiamo trattato il controllo di flusso e le impostazioni della pubblicazione dei contenuti predefiniti. Abbiamo discusso di ciascuno stato del controllo di flusso. Comunque una immagine è meglio di migliaia di parole così la Figura 8-2 mostra gli stati del controllo di flusso predefinito fornito con Plone.

Figura 8-2. Il Controllo di Flusso predefinito fornito con Plone

La Figura 8-2 mostra i principali stati e transizioni. Questa immagine ha una linea grigia punteggiata che rappresenta una sorta di divisione della sicurezza. A sinistra della linea è la parte dove normalmente i possessori del contenuto interagiscono con il contenuto stesso. A destra di quella linea c'è la parte dove sono i revisori che interagiscono con i contenuti.

Come nell'esempio della carta di credito, esiste un insieme di impostazioni di permessi per il controllo di flusso predefinito. La Tabella 8-4 mostra tutti i permessi e gli stati.

Tabella 8-4. I Permessi predefiniti del Controllo di Flusso

View fa riferimento ai seguenti permessi: Access Contents Information e View

Edit fa riferimento al seguente permesso: Modify Portal Content

Come si può vedere nella Tabella 8-4, l'impostazione predefinita è che solo quando un contenuto è nello stato privato è certamente nascosto a qualsiasi altra persona. Quando un contenuto è nello stato Pubblicato solo un manager può modificarlo. In una prossima sezione, Modificare i permessi, vedremo come cambiare facilmente questi permessi via web.

Controllo di Flusso delle Cartelle

Abbiamo trattato anche il controllo di flusso delle cartelle nel Capitolo 3 quando abbiamo parlato la pubblicazione dei contenuti. Comunque, come abbiamo notato in quel capitolo, non esiste lo stato Proposto (Pending) per le cartelle. Abbiamo invece un controllo di flusso più semplice, come mostra la Figura 8-3.

Figura 8-3. Il Controllo di Flusso predefinito per le cartelle fornito con Plone

Altri Controlli di Flusso

In un sito Plone sono disponibili numerosi controlli di flusso, inclusi controlli privati, controlli per comunità, controlli per la pubblicazione diretta (one-step workflow n.d.t.) e così via. ZopeZen ha un suo controllo di flusso come pure PloneCollectorNG. DCWorkflow ha ben quattro controlli di flusso.

Attualmente vi sono due controlli di flusso nel prodotto PloneWorkflows del progetto collettivo in SourceForge (http://sf.net/projects/collective): il controllo di flusso per comunità e quello per la pubblicazione diretta. Il primo è molto simile al controllo di flusso predefinito di Plone con poche variazioni. Il controllo di flusso per la pubblicazione diretta ha solo due stati: Privato e Pubblicato.

Al momento non è semplice installare e disinstallare i controlli di flusso, e non c'è un modo semplice per far transitare i contenuti da uno stato ad un altro. Per esempio se si installa il controllo di flusso per la pubblicazione diretta su uno stato già esistente, sarà necessario aggiustare gli stati di tutti gli oggetti per metterli in uno degli stati nuovi. Questa è probabilmente una situazione semplice, ogni cosa nello stato Pubblicato può rimanere com'è, mentre tutto il resto deve passare allo stato Privato.

Impostare lo Stato Iniziale

Per impostare lo stato iniziale andiamo nella scheda States dove vediamo gli stati disponibili e dove possiamo notare che, vicino ad uno, c'è un asterisco, come mostra la Figura 8-6.

Figura 8-6. Impostare lo stato iniziale per questo controllo di flusso

Impostiamo lo stato iniziale per il nostro controllo di flusso spuntando il box accanto allo stato e cliccando poi Set Initial State. Qualsiasi contenuto generato con questo controllo di flusso avrà quello stato iniziale. Qualsiasi contenuto già esistente rimane nello stato in cui si trovava; cambiare lo stato iniziale successivamente non modifica lo stato. Per ciascun controllo di flusso è possibile impostare solo lo stato iniziale.

Modificare gli Stati

La scheda States elenca gli stati che sono definiti in questo controllo di flusso. All'inizio del capitolo abbiamo detto che uno stato rappresenta un oggetto in un determinato istante. Ogni stato ha un ID unico che usualmente è un semplice verbo come in revisione o pubblicato (pending, published). Per aggiungere uno stato inserire un ID e cliccare Add in fondo alla pagina.

Sono visibili anche le seguenti opzioni:

Title

Il titolo dello stato viene mostrato nel sito Plone e dev'essere quindi user-friendly.

Description

La descrizione può essere una lunga descrizione dello stato. Non viene attualmente mostrata agli utenti ma potrebbe esserlo in futuro.

Possible transitions

Questa elenca tutte le possibili transizioni che possono intervenire sullo stato. Quest'elenco contiene elementi solo se realmente esiste almeno una transizione nel sistema. Selezionare semplicemente le transizioni di cui abbiamo bisogno per questo stato. Selezionando una transizione per questo stato stiamo scegliendo che il punto iniziale per questa transizione sia questo stato.

Per modificare uno stato, inserire le modifiche e premere Save per confermare. La scheda Permission si aprirà con i permessi che verranno applicati ad un oggetto quando si troverà in questo stato. Ciò può significare il cambiamento dei permessi su un oggetto quando arriva (transiziona) a questo stato. Il modulo è sufficentemente auto esplicativo; per abilitare l'utente anonimo a vedere l'oggetto, spuntare il box che corrisponde a View ed ad Anonimous e cliccare Save, come mostra la Figura 8-7.

Figura 8-7. Pagina dei permessi degli stati

Se si cambiano i permessi per un certo stato del controllo di flusso nasce un problema che è necessario risolvere. Ogni contenuto esistente in quello stato non ha impostati i nuovi permessi. Quel contenuto ha i permessi del vecchio controllo di flusso ed è necessario aggiornarli. Quando abbiamo finito di fare tutte le modifiche andiamo alla pagina principale del controllo di flusso e clicchiamo su Update Security Settings, come mostra la Figura 8-4. Questo aggiornamento può prendere un bel po' di tempo in quanto dipende dal numero di oggetti su cui si interviene.

La scheda Variables consente di assegnare un valore ad una variabile quando l'oggetto è in questo stato. Il controllo di flusso determina l'elenco delle variabili disponibili per ciascun stato. Per maggiori informazioni vedere la sezione Modificare le variabili

Modificare le transazioni

La scheda Transitions elenca le transizioni che esistenti in questo controllo di flusso. All'inizio del capitolo abbiamo detto che una transizione rappresenta i possibili cambiamenti dello stato di un oggetto. Ciascuna transizione ha lcune variabili che sono mostrate nella pagina di sommario. Per aggiungere una transizione inserire un ID e cliccare Add in fondo alla pagina, come mostra la Figura 8-8.

Figura 8-8. Pagina di dettaglio della transizione

Se ora clicchiamo su una transizione apriamo i seguenti dettagli per questa transizione:

Title

È il titolo di questa transizione.

Description

La descrizione dettagliata per questa transizione.

Destination state

È lo stato che sarà raggiunto dopo questa transizione. Lo stato sorgente iniziale è definito assegnando la transizione allo stato.

Trigger type

Indica come verrà svolta questa transizione. Automatic significa che avviene appena un oggetto arriva a questo stato. Initiated by user action è la scelta più comune ed è che un utente debba attivare la transizione cliccando un collegamento.

Script (before)

Esegue questo script prima che avvenga la transizione.

Script (after)

Esegue questo script dopo che la transizione è avvenuta.

Guard

È il grado di sicurezza per questo stato (spiegata brevemente).

Display in actions box

Indica come viene mostrata questa transizione in Plone. Inserendo un valore assicura che la transizione sia inserita come azione. Si potrà quindi ottenere la transizione come azione chiamando le azioni.

Tra questi valori il Destination state è davvero interessante. Anche se abbiamo sostenuto in precedenza che le transizioni normalmente cambiano uno stato, ciò non è richiesto. Siccome ogni transizione è in grado di lanciare script e scrivere qualcosa nella history, a volte è utile non cambiare stato. Per un esempio di questo modo d'uso, vedere la sezione Uso del controllo di flusso per tracciare le modifiche, più avanti in questo capitolo. Se vogliamo che la transizione cambi lo stato, selezioniamo il nuovo stato come stato di destinazione.

Una transizione può avere più punti di partenza ma solo una destinazione; se abbiamo bisogno di avere destinazioni multiple sono necessarie altrettante transizioni. Possiamo specificare script da eseguire prima o dopo la transizione. Due semplici esempi sono muovere un oggetto in un controllo di flusso e inviare una notifica e-mail. La sezione Problemi comuni ed esempi tratta entrambi i casi.

Prima che qualsiasi transizione possa essere eseguita, una sentinella di guardia controlla l'intera transizione assicurando che l'utente che ha lanciato la transizione abbia i diritti per farlo. La sentinella è composta dai seguenti tre componenti:

Permission(s)

Sono i permessi richiesti. Permessi multipli devono essere separati da punti e virgola (;).

Role(s)

Sono i ruoli richiesti. Ruoli multipli devono essere separati da punti e virgola (;).

Expression

È una espressione del controllo di flusso. Per ulteriori informazioni vedere la sezione Modificare le espressioni del controllo di flusso più avanti in questo capitolo. Per ciascun valore specificato la sentinella deve valutarla a true prima di poter continuare. Se la prova con uno di questi valore fallisce, la transizione non viene eseguita. Si noterà che solitamente le sentinelle hanno specificati solo uno o due valori.

Modificare le variabili

La scheda Variables elenca le variabili che sono state create e modificate nel controllo di flusso. Non ne abbiamo parlato molto finora perché ci siamo concentrati sugli stati e sulle transizioni. Questa sezione tratta delle variabili.

Non sempre è possibile, e non si consiglia di provarlo, incapsulare tutte le informazioni necessarie in un controllo di flusso, semplicemente usando gli stati e le transizioni. Ma è possibile usare le variabili per contenere alcune informazioni correlate al controllo di flusso. Come, nel precedente esempio della carta di credito, il conto può essere pagato in svariati modi (Servizio di Internet banking, assegno e così via). È possibile conservare l'ammontare del metodo (100 Euro, per esempio) in una variabile. Ad un rigetto o modifica del conto questo ammontare dovrà essere aggiornato. Lo scopo di una variabile è di avere qualcosa che cambia al cambiare di ogni stato e transizione.

Ritornando alla pagina principale del controllo di flusso, clicchiamo la scheda Variables per vedere l'elenco di tutte le variabili. Per aggiungere una variabile, inserire l'ID per la variabile e premere su Add in fondo alla pagina. Per determinare in qualsiasi momento in quale stato si trovi un oggetto, il DCWorkflow contiene lo stato corrente in una variabile dell'oggetto. Il nome predefinito di questa variabile è review_state.

Ogni variabile del controllo di flusso possiede le seguenti proprietà:

Description

È la descrizione della variabile

Make available to catalog

Queste variabili vengono messe in un'elenco che può essere mostrato al catalogo. Non inserisce indici o metadati nel catalogo, questo dev'essere fatto manualmente.

Store in workflow

Determina se le informazioni debbano essere conservate nel controllo di flusso piuttosto che nell'oggetto.

Variable update mode

Determina quando aggiornare la variabile

Default value

Determina un valore predefinito formato stringa

Default expression

È il valore predefinito tramite una espressione. Se è presente viene usato al posto di Default value (per maggiori informazioni vedere la sezione Modificare le espressioni del controllo di flusso più avanti nel capitolo).

Info. guard

Sono impostazioni di sicurezza per questa variabile. Queste impostazioni di sentinella sono simili a quelle analoghe delle transizioni, comunque qui la sentinella interviene quando si accede alla variabile.

Modificare l'elenco dei lavori

La scheda Worklist consente l'accesso a tutti gli elenchi dei lavori che sono assegnati in questo controllo di flusso. Un elenco lavori (worklist) è un metodo per interrogare il controllo di flusso per informazioni a proposito dei suoi numerosi oggetti. Per esempio, vorremmo chiedere facilmente al controllo di flusso tutti i crediti della nostra carta di credito che non abbiamo ancora pagato .

Per aggiungere un worklist inserire un ID e premere Add. Ciascun elenco lavori ha le seguenti proprietà:

Description

È la descrizione dell'elenco lavori.

Cataloged variable matches

È il valore a cui deve corrispondere la variabile per essere inserita in questo elenco lavori. La variabile corrispondente è la variabile di stato del controllo di flusso contenuta nell'elenco delle variabili (il nome della variabile predefinito per questa variabile è review_state).

Display in actions box

Sono informazioni da mostrare nell'interfaccia utente. l'inserimento di un valore assicura che la transizione sia inserita come azione. Sarà quindi possibile ottenere questa transizione come azione chiamando le azioni.

Guard

È una sentinella all'accesso di quest'elenco lavori.

Ritornando all'esempio della carta di credito, se vogliamo sapere tutti i conti che dobbiamo ancora approvare, potremmo mettere queste informazioni in un worklist. Per prima cosa la variabile review_state dovrà contenere lo stato corrente per ciascun elemento. Tutti i conti della carta di credito che devono essere approvati devono essere nello stato review. Poi aggiungiamo un elenco lavori con il nome di review_queue dove il valore della variabile sia pending. Possiamo quindi chiamare l'elenco di tutti gli elementi in review_queue.

Sebbene l'elenco lavori sia un modo conveniente per conservare informazioni, Plone non lo usa. Plone usa invece ZCatalog per chiamare gli oggetti che sono sottoposti a controllo di flusso. Siccome gli elenchi lavori di DCWorkflow usano lo strumento di catalogazione, il risultato è il medesimo.

Modificare gli Script

La scheda Scripts elenca gli script disponibili in questo controllo di flusso. Questo elenco è una reale cartella standard nella ZMI e vi si può aggiungere quasi ogni cosa. Ma in questa cartella dovremo aggiungere solo script Python e l'unica ragione per farlo dovrebbe essere aggiungere uno script per una gestione avanzate delle transizioni.

Per aggiungere uno script dalla scheda Scripts selezionare Scripts dal menù a cascata e dare un ID allo script. Lo script è passato ad uno ed un solo oggetto, che è l'oggetto base del controllo di flusso delle espressioni; per ulteriori informazioni su questo oggetto vedere la sezione Modificare gli script del Controllo di Flusso più avanti nel capitolo. Per esempio, se vogliamo accedere all'attuale oggetto nel controllo di flusso, possiamo usare uno script Python come il seguente:

##parameters=state_change
obj = state_change.object

Ciò che succede in questo script è cosa da sviluppatori, noi possiamo far girare quasi ogni cosa qui. Possiamo controllare eventi, e accedere ad altri controlli di flusso e transizioni. Per degli esempi di script vedere le sezioni Inviare notifiche via E-Mail e Spostare oggetti più avanti nel capitolo. Quando viene eseguito lo script, viene eseguito con l'utente che avvia la transizione. Se è necessario eseguirlo come qualcun altro, è possibile assegnargli un ruolo proxy. Ritornando alle transizioni, è possibile assegnare questo script ad un numero arbitrario di transizioni nelle opzioni script (after) e script (before). È possibile avviare lo script sia prima che dopo una transizione.

Modificare i Permessi

La scheda Permissions elenca i permessi gestiti da questo controllo di flusso. Abbiamo già visto questi permessi esaminando gli stati. In questa scheda si imposta l'elenco dei permessi gestibili da quegli stati. Per aggiungere un nuovo permesso, selezionare il permesso dall'elenco a cascata e selezionare Add.

Modificare gli script del Controllo di Flusso

Gli script danno allo sviluppatore l'opportunità di intervenire sulla logica di una transizione. Questa logica può essere quasi ogni cosa si desidera. Potremmo controllare che siano rispettate alcune condizioni (per esempio, è stato fatta la correzione degli errori ortografici del documento?) o se sono state effettuate alcune delle azioni speciali. Quando l'oggetto è sottoposto a transizione viene chiamato lo script.

Quando viene chiamato uno script, gli viene passato un parametro extra. Questo parametro extra fornisce l'accesso a tutti i tipi di elementi e attributi correlati alla transizione. Questo parametro è denominato state_change ed ha i seguenti attributi:

status

è lo stato del controllo di flusso

object

È l'oggetto sottoposto a transizione nel controllo di flusso

workflow

È l'oggetto workflow corrente dell'oggetto sottoposto a transizione

transition

È l'oggetto transizione che viene eseguito

old_state

È lo stato originario dell'oggetto

new_state

È lo stato di destinazione dell'oggetto

kwargs

Sono gli argomenti parole-chiave passate al metodo doActionFor

getHistory

È un metodo che non prende parametri e ritorna una copia della history degli oggetti del controllo di flusso.

getPortal

È un metodo che non prende parametri e ritorna l'oggetto Plone root

ObjectDeleted(folder)

Dice al controllo di flusso che l'oggetto che sta per essere sottoposto a transizione è stato cancellato; prende l'oggetto a cui si desidera ritorni l'utente. Passa all'eccezione la cartella a cui si vuol redirigere l'utente (vedere la sezione Spostare oggetti più avanti nel capitolo)

ObjectMoved(newObject, newObject)

Dice al controllo di flusso che l'oggetto che sta per essere sottoposto a transizione è stato spostato. Passa all'eccezione la cartella a cui si vuol redirigere l'utente (vedere la sezione Spostare oggetti più avanti nel capitolo)

getDateTime

È un metodo che non prende parametri e ritorna l'oggetto DateTime relativo alla transizione

Per esempio, per sapere a quale sia lo stato di destinazione della transazione e in che momento, è necessario un oggetto Script (Python) come il seguente, che ci darà proprio questa informazione. Lo script scrive le informazioni relative alla transizione nel file di log:

##parameters=state_change
st = 'From %s to %s on %s' % (
    state_change.old_state,
    state_change.new_state,
    state_change.getDateTime())
context.plone_log(st)

Quando si assegna uno script ad una transizione si hanno due possibilità: before e after (prima e dopo). Come suggeriscono i nomi, uno script impostato a before viene lanciato prima della transizione. Ciò è sfruttabile per script che devono controllare se qualcosa deve avvenire prima che la transizione sia lanciata, come controllare se un altro oggetto o pagina dipendenti siano stati aggiornati o che non vi siano errori ortografici. Uno script impostato ad after viene lanciato una volta che la transizione è stata completata, anche se, in qualsiasi momento, una eccezione inaspettatamente sollevata dallo script, può far fallire la transizione e far rimanere l'oggetto nel suo stato originale, mentre l'eccezione viene mostrata all'utente.

Modificare le espressioni del controllo di flusso

In questo capitolo abbiamo visto valori che possono essere espressi tramite espressioni del controllo di flusso. Per esempio il valore assegnato ad una variabile che è il risultato di una espressione del controllo di flusso. Questa espressione non ha niente di speciale; è semplicemente una espressione TAL (Template Attribute Language) con alcune differenti variabili disponibili. Abbiamo già studiato le espressioni TAL nel Capitolo 5 e quindi dovremmo avere famigliarità con quelle espressioni e le loro opzioni, come del Python, stringhe e path expression.

A differenza delle espressioni TAL standard, alcuni parametri extra vengono passati allo spazio dei nomi (namespace) relativo ad un determinato controllo di flusso. Lo spazio dei nomi di una espressione del controllo di flusso contengono i seguenti parametri:

here

È l'oggetto sottoposto a transizione nel controllo di flusso

container

È il contenitore dell'oggetto sottoposto a transizione nel controllo di flusso

state_change

È l'oggetto del cambiamento di stato referenziato nella sezione Modificare gli script del Controllo di Flusso

transition

È la transizione che viene eseguita, identico a state_change.transition.

status

È lo stato originario dell'oggetto, identico a state_change.old_state.

workflow

È il controllo di flusso per questo oggetto

scripts

Sono gli script disponibili in questo controllo di flusso

user

È l'utente che esegue la transizione

Scrivere tramite la ZMI

Probabilmente scrivere il controllo di flusso tramite la ZMI è il modo più semplice anche se più laborioso. Sebbene la ZMI porti spesso la gente a impazzire, essa rimane la via più semplice per impostare le opzioni. Sfortunatamente una volta che si è iniziato a scrivere il controllo di flusso tramite la ZMI siamo bloccati in quel paradigma. In altre parole non vi è un modo semplice per modificare o alterare quel controllo di flusso sul file system. Ovviamente, abbiamo parlato, precedentemente in questo capitolo, della modifica di un controllo di flusso via web.

Per esportare un controllo di flusso dalla ZMI, cliccare su portal_workflow e selezionare la scheda Contents, selezionare i controlli di flusso che si desidera esportare spuntando i box sulla sinistra nella ZMI cliccando poi import/export. Nella parte in cima della pagina di esportazione, selezionare Download to local machine e cliccare export. Viene creato un file con estensione .zexp che può essere salvato e redistribuito. Selezionando XML Format si ottiene un file nel formato XML (Extensible Markup Language) con estensione .xml.

Se si ha un controllo di flusso in formato .zexp o .xml l'importazione in Plone è assolutamente lineare. Mettere quel file nella cartella di importazione di Zope sul file system. Può essere sia la cartella home dell'istanza sia la cartella Zope.

Clicchiamo poi portal_workflow, scegliamo la scheda Contents e clicchiamo su import/export. Nella parte in cima alla pagina si può vedere un semplice modulo che prende il nome di un file da importare. Inseriamo qui il nome del file e lasciamo selezionato Take ownership of imported objects. Clicchiamo il pulsante Import per importare il controllo di flusso. Il controllo di flusso viene importato e gli viene dato il nome specificato nell'esportazione.

Scrivere un Controllo di Flusso in Python

La maniera preferita dai programmatori per scrivere un controllo di flusso è probabilmente usare Python, in quanto può essere fatto tutto con Python e facilmente distribuito. Primo, facciamo un modulo Python nel file system. In cima al file importiamo gli strumenti necessari, come segue:

from Products.CMFCore.WorkflowTool import addWorkflowFactory
from Products.DCWorkflow.DCWorkflow import DCWorkflowDefinition

Secondo, facciamo una funzione che crei il controllo di flusso. L'Appendice A elenca le API per scrivere un controllo di flusso un po' più in dettaglio. Ma possiamo semplicemente barare e guardare ai numerosi esempi disponibili nel progetto PloneWorkflow nel collective (http://sf.net/projects/collective) o anche in quelli contenuti in Plone. Per esempio:

def sample(id):
    """ Sample workflow """
    ob = DCWorkflowDefinition(id)
    ob.states.addState('private')
    ob.states.addState('public')
    # add transitions
    return ob

Finalmente registriemo il controllo di flusso nel sistema così:

addWorkflowFactory(sample,
                   id='sample_workflow',
                   title='Sample workflow')

Questo script deve far parte della installasione di un prodotto. Il Capitolo 12 tratta dello scrivere ed installare prodotti.

Ora, naturalmente, è disponibile una scorciatoia, che si chiama DCWorkflowDump. Questa prende il codice dalla ZMI e lo sbatte (dump) dentro un modulo Python. Il codice sorgente di DCWorkflowDump è disponibile nel collective (http://sf.net/projects/collective) ma anche nel sito web del manuale Plone all'indirizzo http://plone-book.agmweb.ca si può trovare un file .zip con il codice.

Per installare DCWorkflowDump, decomprimere il file e copiare la cartella denominata DCWorkflowDump nella cartella Products della nostra installazione Plone. Come controllo per sapere se siamo nella cartella giusta, verifichiamo che la stessa cartella contenga, tra le altre cose, una cartella per DCWorkflow. Poi riavviamo l'istanza Plone.

Una volta riavviato Plone, rechiamoci nella ZMI in quel particolare controllo di flusso e noteremo una nuova scheda denominate dump. Scegliamo quella pagina per vedere la schermata di dump e clicchiamo su Dump it! per ottenere il controllo di flusso. Questo prende il nostro controllo di flusso e lo formatta in Python. Salviamo questo file nel nostro prodotto e quindi ora abbiamo un file Python da manipolare. Questo prodotto è un valido strumento poiché consente di creare il controllo di flusso con la ZMI e poi distribuirlo e alterarlo tramite Python.