Présentation
############

Le composant hello-world-plugin est un exemple qui montre comment développer un plugin custom.
Il suffit donc de prendre ce projet maven comme exemple et d'adapter le plugin à souhait.


.. note:: Sur le **pom** de ce module, seule la dépendance vers ``common-plugin`` est nécessaire.

.. sourcecode:: xml

  <dependency>
      <groupId>fr.gouv.vitam</groupId>
      <artifactId>common-plugin</artifactId>
      <version>${vitam.version}</version>
  </dependency>


Vous pouvez bien sûr ajouter d'autres dépendances qui servent à votre `plugin` `custom`.

Comment intégrer votre plugins dans vitam ?
============================================

Après avoir développé votre `plugin` en suivant les consignes ci-dessus, il faut faire ce qui suit:

-   Générer votre jar
-   Copier votre jar manuellement dans le dossier ``/vitam/conf/worker/plugins-workspace/``, ou bien copier le dans le dossier de déploiement ansible ``~/vitam/deployment/ansible-vitam/roles/vitam/files/worker/plugins-workspace/``
-   Modifier le fichier plugins.json qui se trouve soit dans le dossier ``/vitam/conf/worker/plugins.json`` en production, ou bien dans le dossier de déploiement ansible qui se trouve :``vitam/deployment/ansible-vitam/roles/vitam/files/worker/plugins.json``, comme suit :

      .. sourcecode:: xml

        "HELLO_WORLD_PLUGIN": {
          "className": "fr.vitam.plugin.custom.HelloWorldPlugin",
          "propertiesFile": "hello_world_plugin.properties",
          "jarName": "hello-world-plugin-1.14.0-SNAPSHOT.jar"
        }

.. warning:: jarName doit contenir uniquement le nom du jar avec extension '.jar'

A présent sur n'importe quel workflow, vous pouvez ajouter une action ayant comme "actionKey" la clé de votre plugin. Dans cet exemple: actionKey=HELLO_WORLD_PLUGIN

Créer un nouveau `workflow`
============================

Tout d'abord création d'un nouveau workflow:

- Créer un nouveau `workflow` peut se résumer juste à copier un `workflow` existant et modifier son `identifier` et son `workerGroupId` pour, par exemple, utiliser des machines plus puissantes pour ce `workflow`
- L'identifier d'un `workflow` doit être UNIQUE, sinon un `workflow` existant portant le même `identifier` sera remplacé par le nouveau.
- La valeur de ``typeProc`` n'est pas actuellement dynamique (veuillez vous référer à l'enum **LogbookTypeProcess** pour voir les différentes valeurs possibles)
- La valeur ``actionKey`` doit être soit le `handler name` d'un `plugin` ou `handler` existant, soit celui d'un nouveau `plugin`.

Exemple d'un `workflow` :

.. sourcecode:: xml

  {
    "id": "SampleIngestWorkflow",
    "name": "Sample Ingest Workflow",
    "identifier": "SAMPLE_PROCESS_SIP_UNITARY",
    "typeProc": "INGEST",
    "comment": "Sample Ingest Workflow V6",
    "steps": [
      {
        "workerGroupId": "DefaultWorker",
        "stepName": "STP_INGEST_CONTROL_SIP",
        "behavior": "BLOCKING",
        "distribution": {
          "kind": "REF"
        },
        "actions": [
          {
            "action": {
              "actionKey": "HELLO_WORLD_PLUGIN",
              "behavior": "BLOCKING",
              "in": [
                {
                  "name": "var_name",
                  "uri": "VALUE:Hello World"
                }
              ]
            }
          }
        ]
      }
    ]
  }

.. warning:: Le fichier `workflow` doit être un fichier json avec comme extension (``.json``) sinon le fichier ne sera pas pris en compte.


Comment ajouter un nouveau workflow dans vitam ?
*************************************************

Il tout d'abord créer un fichier json avec un nom de votre choix et ayant la forme de l'exemple ci-dessus.
Veuillez vous référer au différents workflow existants pour avoir plus d'information.

Il faut ensuite copier ce fichier (``CustomWorkflow.json``) dans :

  - En production : Manuellement dans le dossier ``/vitam/conf/processing/workflows/``
  - Via ansible: Dans le dossier ``~/vitam/deployment/ansible-vitam/roles/vitam/files/processing/workflows/``


Comment ajouter la traduction de clés des Plugins ?
***************************************************

On peut dans n'importe quel service vitam ajouter dans le dossier conf les deux fichiers suivants:
- ``vitam-logbook-messages_fr.properties``
- ``vitam-error-messages.properties``

Ces deux fichiers garantissent la traduction des clés.

Pour le nouveau plugins ajouté, le fichier properties qui est à l'intérieur du jar n'est visible que par le service (worker).
Pour qu'on puisse avoir ces clés traduites,le fichier ``vitam-logbook-messages_fr.properties`` doit contenir les traductions des clés de ce nouveau `plugin`.
Il faut  copier ce fichier dans le dossier de conf de processing s'il n'existe pas.

  .. sourcecode:: text

     HELLO_WORLD_PLUGIN=Test d''un plugin Hello World
     HELLO_WORLD_PLUGIN.OK=Test d''un plugin Hello World réalisé avec succès
     HELLO_WORLD_PLUGIN.KO=Échec lors du test d''un plugin Hello World
     HELLO_WORLD_PLUGIN.FATAL=Erreur fatale lors du test d''un plugin Hello World
     HELLO_WORLD_PLUGIN.WARNING=Avertissement lors du test d''un plugin Hello World


Comment appeler le nouveau workflow ?
*************************************

En utilisant l'API d'`ingest` et en passant les paramètres suivants :

- ``X_CONTEXT_ID`` : l'identifier de votre workflow (dans l'exemple ci-dessus SAMPLE_PROCESS_SIP_UNITARY)
- ``X_ACTION``: votre action (RESUME, NEXT)

Le reste se fait automatiquement par le `back office`.


Remarques
**********
- L'ajout d'un `workflow` dans processing en production ne nécessite pas de redémarrage. Un thread passe chaque heure configurale pour recharger les derniers workflow (ajoutés ou modifiés)
- L'ajout d'un jar dans les workers et les fichiers properties nécessitent, cependant, le redémarrage des workers et des services concernés.

Securité
**********
Les plugins externes sont exécutés au même niveau de sécurité que ceux interne à :term:`VITAM`.
L'isolation de l'exécution des plugins externes n'est pas assurée par  :term:`VITAM`.
C'est donc à l'exploitant de garantir la sécurité des plugins intégrés.

