> For the complete documentation index, see [llms.txt](https://documentation.efalia.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.efalia.com/documentations/efalia-process/administration/administration-technique/agents-process.md).
# Agents Process
Les **Agents Process** sont des tâches automatiques planifiées qui s'exécutent sur le serveur Efalia Process sans intervention humaine. Ils permettent d'automatiser des opérations récurrentes : envoi d'emails, synchronisation de données, exécution de commandes externes, archivage…
***
## Concept et Architecture
Un agent est une **tâche serveur planifiée** qui s'exécute selon un calendrier défini (planification de type cron). Contrairement aux opérations de workflow qui nécessitent une action humaine, les agents agissent automatiquement.
**Cas d'usage typiques :**
* Envoi d'emails de rappel ou de notification
* Extraction et transformation de données
* Archivage automatique des documents en fin de vie
* Lancement de processus ou de commandes externes
* Synchronisation avec des systèmes tiers
***
## Types d'Agents Disponibles
Efalia Process propose plusieurs types d'agents selon la licence activée :
| Type d'Agent | Classe Java | Description |
| ---------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Archiveur** | *(interne)* | Archivage automatique des documents en fin de vie — voir [Module d'Archivage](/documentations/efalia-process/administration/administration-technique/module-archivage.md) |
| **Lancement de processus externe** | `com.clog.workey.agents.tasks.ExecProcess` | Exécute une commande système sur le serveur |
***
## Agent de Lancement de Processus Externes
Cet agent permet d'**exécuter une commande externe** présente sur le serveur. Il est utile pour déclencher des scripts batch, des outils de traitement de données, ou des intégrations système.
{% hint style="warning" %}
⚠️ **Restriction importante**
Il est **fortement déconseillé** de modifier directement les données Efalia Process (base de données ou système de fichiers) lors de l'exécution de cet agent. Utilisez l'API REST d'Efalia Process pour les interactions avec les données applicatives.
{% endhint %}
### Paramètres
| Paramètre | Obligatoire | Description |
| ---------------- | ----------- | ---------------------------------------------------------------- |
| `processCommand` | ✅ | Chemin complet de la commande ou du script à exécuter |
| `processEnv` | ❌ | Variables d'environnement séparées par `\|`, format `clé=valeur` |
| `processExecDir` | ❌ | Répertoire de travail pour l'exécution de la commande |
### Exemple de Configuration
```
processCommand = /opt/scripts/sync-erp.sh
processEnv = HOME=/home/efalia|VERSION=6.14.2|ENV=PROD
processExecDir = /opt/scripts
```
### Exemple de Variables d'Environnement
```
HOME=/home/workey|VERSION=6.12.5|LOG_LEVEL=INFO
```
Chaque variable est au format `clé=valeur`, séparées par le caractère `|`.
***
## Créer et Configurer un Agent
{% stepper %}
{% step %}
#### Accéder à la gestion des agents
Depuis la **console d'administration** (`/workey/admin`), naviguez vers la section **Agents**.
📸 **CAPTURE : admin-tech-agents-01-liste-agents.png**
> Vue d'ensemble de la liste des agents avec leurs types, statuts et dernière exécution
> {% endstep %}
{% step %}
#### Créer un nouvel agent
Cliquez sur **"Créer nouvel Agent"** et sélectionnez le type d'agent dans la liste déroulante.
{% endstep %}
{% step %}
#### Configurer les paramètres de l'agent
Renseignez les paramètres spécifiques au type d'agent sélectionné (voir ci-dessus pour l'agent ExecProcess).
{% endstep %}
{% step %}
#### Définir la planification (Cron)
Configurez le **calendrier d'exécution** de l'agent en utilisant la syntaxe cron.
**Format Spring (6 colonnes) :**
```
secondes minutes heures jour-du-mois mois jour-de-semaine
```
**Exemples courants :**
| Expression | Signification |
| -------------------- | ------------------------------ |
| `0 0 2 * * *` | Tous les jours à 2h du matin |
| `0 0 */6 * * *` | Toutes les 6 heures |
| `0 30 8 * * MON-FRI` | Du lundi au vendredi à 8h30 |
| `0 0 0 1 * *` | Le 1er de chaque mois à minuit |
| {% endstep %} | |
{% step %}
#### Activer et tester l'agent
Activez l'agent et vérifiez son exécution dans la section **Historique/Journalisation** de l'agent.
📸 **CAPTURE : admin-tech-agents-02-historique-agent.png**
> Historique d'exécution d'un agent avec les logs de chaque instanciation
> {% endstep %}
> {% endstepper %}
***
## Options de Configuration Communes
| Option | Description |
| -------------------------- | -------------------------------------------------------------------------- |
| **Journalisation** | Active l'enregistrement des logs d'exécution pour chaque instanciation |
| **Instances multiples** | Autorise ou non plusieurs exécutions simultanées du même agent |
| **Calendrier d'exclusion** | Définit des plages horaires ou des dates où l'agent ne doit pas s'exécuter |
| **Acteur de substitution** | Identité utilisée par l'agent pour les opérations Efalia Process |
***
## ⚠️ Limitations
{% hint style="warning" %}
**Agent d'archivage — Unicité obligatoire**
L'agent d'archivage ne doit être créé qu'**une seule fois** sur un serveur Efalia Process. Voir [Module d'Archivage](/documentations/efalia-process/administration/administration-technique/module-archivage.md) pour plus de détails.
{% endhint %}
{% hint style="warning" %}
**Commandes externes — Sécurité**
L'agent `ExecProcess` exécute des commandes avec les droits du **processus Tomcat**. Assurez-vous que :
* Seuls les scripts nécessaires sont accessibles
* Les chemins de commande sont absolus et vérifiés
* Les variables d'environnement ne contiennent pas de données sensibles en clair
{% endhint %}
***
## Bonnes Pratiques
{% hint style="success" %}
**✅ À faire :**
* Activer la **journalisation** sur tous les agents en production pour faciliter le diagnostic
* Planifier les agents pendant les **heures creuses** (nuit, week-end)
* Configurer un **calendrier d'exclusion** pour les périodes de maintenance
* Tester les agents manuellement avant leur activation en production
* Documenter le rôle et la configuration de chaque agent
{% endhint %}
{% hint style="danger" %}
**❌ À éviter :**
* Modifier directement la base de données Efalia Process depuis un agent externe
* Créer plusieurs agents d'archivage
* Utiliser des chemins relatifs dans `processCommand`
* Autoriser les instances multiples sans vérifier les conflits potentiels
{% endhint %}
***
## Questions Fréquentes
Un agent peut-il déclencher une opération de workflow (faire avancer un document) ?
Oui. Un agent peut interagir avec Efalia Process via l'**API REST** pour déclencher des opérations sur des documents. Cette approche est recommandée plutôt que la manipulation directe de la base de données.
Consultez la section [Développeurs > API REST](/documentations/efalia-process/vue-ensemble-api/documentation-api-rest.md) pour les endpoints disponibles.
Comment surveiller l'exécution des agents en production ?
Activez la **journalisation** sur chaque agent. L'historique d'exécution est consultable depuis la console d'administration (section Agents > Historique de l'agent). Vous pouvez également consulter les logs Tomcat pour les erreurs système.
L'agent peut-il s'exécuter même si le serveur Efalia Process est en mode maintenance ?
Oui. Le mode maintenance bloque l'accès des utilisateurs à l'application web mais n'interrompt pas l'exécution des agents planifiés.
Peut-on déclencher un agent manuellement depuis l'administration ?
Oui. Depuis la console d'administration, dans le détail d'un agent, un bouton permet de déclencher manuellement une exécution immédiate. Cela est utile pour tester un agent ou pour forcer un traitement en dehors de son planning habituel.
***
Pour aller plus loin :
* [Module d'Archivage](/documentations/efalia-process/administration/administration-technique/module-archivage.md)
* [API REST](/documentations/efalia-process/vue-ensemble-api/documentation-api-rest.md)
* [Remarques et Limitations](/documentations/efalia-process/administration/administration-technique/remarques-limitations.md)
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://documentation.efalia.com/documentations/efalia-process/administration/administration-technique/agents-process.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.