8.2.7.1. 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.

<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.

8.2.7.1.1. 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 :

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

Avertissement

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

8.2.7.1.2. 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 :

{
  "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"
              }
            ]
          }
        }
      ]
    }
  ]
}

Avertissement

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

8.2.7.1.2.1. 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/

8.2.7.1.2.2. 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.

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

8.2.7.1.2.3. 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.

8.2.7.1.2.4. 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.

8.2.7.1.2.5. Securité

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