Suivi des Workflows
###################

La solution logicielle :term:`VITAM` intègre une solution de suivi et de gestion des `Workflows`.
Elle permet entre autres de :

* Relancer un Workflow arrêté
* Mettre en pause un Workflow démarré
* Rejouer une étape d'un Workflow
* Annuler un workflow

Suivi
=====

Le suivi peut être réalisé via :term:`IHM`, par des appels :term:`REST` ou par un playbook ansible.

IHM
---

Il existe une page dans l':term:`IHM` de démonstration, permettant d'influer sur les processus en cours.
Tous les processus mis en pause, automatiquement (lors d'un FATAL) ou bien manuellement (Mode pas à pas) apparaissent sur cette :term:`IHM`.
Il est également possible, à partir de cette :term:`IHM`, de relancer le processus ou bien de rejouer une étape, après action d'exploitation.

Appels REST
-----------

Il est possible d'exécuter ces différentes actions sur l':term:`API` en direct, via des appels ``curl`` par exemple sur le composant access-external :

 - PUT sur le endpoint /operations/GUID avec comme header X-Action:RESUME par exemple.

Pour plus d'information, consulter la documentation des :term:`API` externes.

Playbook ansible
----------------

Lancer le script suivant ::

    ansible-playbook ansible-vitam-exploitation/check_workflow_status.yml -i environments/hosts.<environnement> --ask-vault-pass -e '{"vitam_tenant_ids":[0,1,2], "states":[PAUSE,RUNNING,COMPLETED], "statuses":[UNKNOWN, STARTED, OK, WARNING, KO, FATAL]}'

 Paramètres optionnels:

* vitam_tenant_ids: Pour spécifier la liste des tenants à interroger (default values = variable vitam_tenant_ids defined in environments/ files)
* states: Pour filter sur l'état des process (valid values = [RUNNING, PAUSE, COMPLETED])
* statuses: Pour filtrer sur le status des process (valid values = [UNKNOWN, STARTED, OK, WARNING, KO, FATAL])

.. warning:: Le playbook ansible ne peut être exécuté que dans le cas où une installation a déjà été effectuée, et que la :term:`PKI` n'a pas été rejouée (les certificats présents dans ``environments/certs`` doivent être ceux mis en place dans :term:`VITAM`).


Cas des `worklows` en FATAL
===========================

Un *workflow* se met en pause dès qu'il se retrouve en statut **FATAL**. Plusieurs causes peuvent expliquer un tel état.

Plugins et Handlers
-------------------

Plusieurs problèmes peuvent expliquer qu'un `Handler` ou un `plugin` retourne une erreur "FATAL" et donc provoque la mise en pause du `Worfklow`.


Si le composant workspace est défectueux ou ne répond plus, alors un FATAL pourra être obtenu pour tous les `Handlers` et `plugins`.

Si le composant logbook est défectueux ou ne répond plus, alors un FATAL pourra être obtenu pour les `handlers` suivants :

 - CommitLifeCycleActionHandler
 - CommitLifeCycleObjectGroupActionHandler
 - CommitLifeCycleUnitActionHandler
 - ListLifecycleTraceabilityActionHandler
 - FinalizeLifecycleTraceabilityActionHandler
 - RollBackActionHandler

Si le composant functional-administration est défectueux ou ne répond plus, alors un FATAL pourra être obtenu pour les Handlers suivants :

 - CheckArchiveProfileRelationActionHandler
 - CheckArchiveProfileActionHandler
 - GenerateAuditReportActionHandler
 - PrepareAuditActionHandler

Si le composant metadata est défectueux ou ne répond plus, alors un FATAL pourra être obtenu pour les Handlers suivants :

 - AccessionRegisterActionHandler
 - ListArchiveUnitsActionHandler
 - PrepareAuditActionHandler
 - ArchiveUnitRulesUpdateActionPlugin
 - AuditCheckObjectPlugin
 - IndexObjectGroupActionPlugin
 - IndexUnitActionPlugin
 - RunningIngestsUpdateActionPlugin

Si le composant storage est défectueux ou ne répond plus, alors un FATAL pourra être obtenu pour les Handlers suivants :

 - CheckStorageAvailabilityActionHandler
 - FinalizeLifecycleTraceabilityActionHandler
 - GenerateAuditReportActionHandler
 - PrepareTraceabilityCheckProcessActionHandler
 - PutBinaryOnWorkspace
 - CheckIntegrityObjectPlugin
 - CheckExistenceObjectPlugin
 - StoreMetaDataObjectGroupActionPlugin
 - StoreMetaDataUnitActionPlugin
 - StoreObjectActionHandler
 - StoreObjectGroupActionPlugin

Si le composant processing est défectueux ou ne répond plus, alors un FATAL pourra être obtenu pour les Handlers suivants :

 - ListRunningIngestsActionHandler

Si le composant FormatIdentifier est défectueux et ne répond plus, alors un FATAL pourra être obtenu pour le Handler suivant :

 - FormatIdentificationActionPlugin

Distributor
-----------

Plusieurs cas peuvent provoquer un FATAL au niveau du processing :

 - si metadata ou workspace est injoignable
 - si un `handler` (ou plugin) inexistant est appelé.
 - si le distributeur tente d'appeler une famille de worker inexistante


Processing - State Machine
--------------------------

Dans le cas ou le Processing ne parvient pas à enregistrer l'état du workflow sur le workspace, un FATAL est provoqué.
Il en va de même si le composant logbook est défectueux.


Redémarrer un processus en cas de pause
=======================================

Trouver la cause
----------------

De manière générale, il convient d'identifier le composant (ou les composants) posant problème.
Il s'agira majoritairement de metadata, de logbook, du storage ou encore du workspace.

A partir du Guid de l'opération mise en pause, il est facilement possible de voir, dans les logs du processing ou des workers quels sont les composants incriminés.


Relancer le Workflow
--------------------

A partir du Guid de l'opération mise en pause et une fois le composant redémarré, il est possible de relancer le workflow.

Vérifier les inputs
*******************

S'assurer à partir du GUID de l'opération que l'on nommera X la présence :
 - d'un fichier X.json dans /vitam/data/workspace/process/distributorIndex/
 - d'un répertoire X dans ``/vitam/data/workspace/`` contenant à minima une liste de sous-répertoires (et notamment le :term:`SIP` décompressé dans le sous répertoire ``SIP``).

Rejouer une étape
*****************

Depuis l':term:`IHM`, relancer l'étape précédente en cliquant sur l'icône "Replay".
Via les :term:`API`, il suffit de lancer un appel ``curl`` sur le composant access external : PUT sur le endpoint /operations/GUID avec comme header X-Action:REPLAY.

Cette action aura pour résultat d'exécuter une deuxième fois l'étape qui a échoué. En sortie de ce replay, le statut du workflow doit passer à OK et l'état à PAUSE.

Prochaine étape
***************

Depuis l':term:`IHM`, exécuter l'étape suivante en cliquant sur l'icône "Next".
Via les :term:`API`, il suffit de lancer un appel curl sur le composant "access-external" : PUT sur le endpoint /operations/GUID avec comme header X-Action:NEXT.

Cette action aura pour résultat d'exécuter l'étape suivante. En sortie de ce replay, le statut du workflow doit passer à OK et l'état à PAUSE.

Finaliser le workflow
*********************

Il est possible de poursuivre le workflow jusqu'à son terme.

Depuis l':term:`IHM`, finaliser le workflow en cliquant sur l'icône "Fast Forward".

Via les :term:`API`, il suffit de lancer un appel curl sur le composant ``access-external`` : PUT sur le endpoint /operations/GUID avec comme header X-Action:RESUME.
