Skip to content

$doc.cancelStateTransition

Alias: $doc.cancelStateChange

Description

Cette méthode sert à annuler un changement d'état de dossier. Elle n'a d'utilité qu'au sein d'un script déclenché par une notification doc-enterstate ou doc-leavestate, ou des événements d'états tels que onleave, onenter ou ontransition.

Différence par rapport à $thread.abortNotifiedAction()

Un changement d'état peut également être annulé avec la méthode $thread.abortNotifiedAction(). Il y a toutefois des nuances entre les deux méthodes.

$thread.abortNotifiedAction() est destiné à annuler une action, c'est-à-dire une instruction passée au moteur via une commande envoyée dans une requête HTTP. Si l'action en question est un setState, le changement d'état demandé sera bien annulé. Cependant, imaginons le cas du modèle d'états suivants:

1
2
3
4
5
6
7
8
9
...
<state name="attente_paiement">
    <transition name="autorisation.confirmer" target="paye"/>
</state>
<state name="paye" onenter="onEnterPaye">
    <transition name="autorisation.activer" target="traitement"/>
</state>
<state name="traitement" onenter="onEnterTraitement"/>
...

L'état paye ici est un état intermédiaire: lorsque le paiement est confirmé, le dossier passe dans l'état paye. L'événement onenter déclenche l'exécution du script onEnterPaye. Ce dernier inscrit une entrée dans un journal pour reporter l'indication du paiement et enchaîne immédiatement avec une transition vers l'état traitement via un appel à $doc.setState(). L'événement onenter de l'état traitement est à son tour déclenché et lance l'exécution du script onEnterTraitement. Si pour une raison quelconque, ce dernier doit empêcher le changement d'état, il aura le choix entre les méthodes $thread.abortNotifiedAction() et $doc.cancelStateTransition. Le comportement du moteur ne sera alors pas le même dans le deux cas:

  • $thread.abortNotifiedAction() aurait pour effet d'annuler l'action dans son ensemble, ce qui fait que le dossier, en fin de traitement, se retrouverait dans l'état attente_paiement initial. C'est un problème car dans ce cas on a perdu l'information que le paiement a été fait.

  • $doc.cancelStateTransition a pour effet d'annuler uniquement le passage à l'état traitement, sans annuler l'état paye. Le dossier restera alors dans l'état paye.

Syntaxe

$doc.cancelStateTransition( [ levels ] )

Paramètres

levels number / string

Nombre de niveaux à invalider.

En cas de changements d'états enchaînés de façon récusive au niveau d'événements ou de notifications, le paramètre permet d'indiquer le nombre de niveaux à invalider.

Peut valoir * pour désigner tous les niveaux.

Il est possible d'indiquer une valeur négative pour indiquer le nombre de niveaux à conserver plutôt que le nombre de niveaux à invalider.

Si on reprend l'exemple donnée en note plus haut, le fait d'invoquer la méthode avec levels défini à 2 (ou *, ou -1) permettrait d'avoir le même résultat que l'appel à $thread.abortNotifiedAction() : les deux changements d'états seraient annulés et le dossier se retrouverait dans l'état attente_paiement.

Si la valeur est invalide ou non définie, elle prend la valeur 1.

Retour

Retourne toujours null

Exemple

1
$doc.cancelStateTransition();