> 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/vue-ensemble/mise-en-oeuvre/troubleshooting.md).
# Troubleshooting
Ce guide recense les problèmes les plus fréquents rencontrés lors de la mise en œuvre ou de l'utilisation de l'intégration Efalia Doc, avec leurs causes et solutions.
***
## Diagnostic Initial
Avant d'investiguer un problème spécifique, commencez par vérifier l'état de la connexion.
{% stepper %}
{% step %}
#### Vérifier le statut de connexion
Dans l'administration Efalia Process (`/workey/admin`), naviguez vers **Efalia Docs > Paramètres**.
Le panneau affiche le **statut de connexion** en temps réel. Si la connexion est en erreur, le message d'erreur précis est affiché.
📸 **CAPTURE : troubleshooting-01-statut-connexion.png**
> Panneau de paramétrage avec le statut de connexion et le message d'erreur
> {% endstep %}
{% step %}
#### Activer les journaux de débogage
Si le problème ne se manifeste que lors de l'exécution des connecteurs (et non au niveau de la connexion), activez les journaux de débogage dans **Efalia Docs > Paramètres**.
Consultez ensuite `catalina.out` :
```bash
grep -i "mgx\|efalia doc\|multigest" $CATALINA_HOME/logs/catalina.out | tail -200
```
{% endstep %}
{% step %}
#### Tester la connectivité réseau
Vérifiez que le serveur Efalia Process peut joindre l'API Efalia Doc :
```bash
curl -v https://docs.efalia.demo:1202/api/health
```
Un code HTTP 200 confirme la connectivité. Un timeout indique un problème réseau (pare-feu, proxy, résolution DNS).
{% endstep %}
{% endstepper %}
***
## Problèmes de Connexion
### La connexion échoue avec "Unauthorized" ou code 401
**Causes possibles :**
* Identifiants du compte de service incorrects
* Clé d'API expirée ou révoquée
* Le compte de service est verrouillé ou désactivé dans Efalia Doc
**Solutions :**
1. Vérifiez les identifiants dans **Efalia Docs > Paramètres**
2. Régénérez la clé d'API dans Efalia Doc si nécessaire
3. Vérifiez que le compte de service est actif dans la console d'administration Efalia Doc
4. Testez les identifiants directement via l'API Efalia Doc :
```bash
curl -u login:password https://docs.efalia.demo:1202/api/auth/test
```
***
### La connexion échoue avec "Connection refused" ou timeout
**Causes possibles :**
* URL de l'API incorrecte (mauvais port, mauvais protocole)
* Service Efalia Doc arrêté
* Pare-feu bloquant la connexion
* Certificat SSL invalide ou non approuvé
**Solutions :**
1. Vérifiez l'URL configurée dans **Efalia Docs > Paramètres** (format : `https://host:port`)
2. Vérifiez que le service Efalia Doc est démarré
3. Vérifiez les règles de pare-feu entre les serveurs Process et Doc
4. Pour les certificats auto-signés, ajoutez le certificat au truststore Java :
```bash
keytool -importcert -file efalia-doc.crt \
-keystore $JAVA_HOME/jre/lib/security/cacerts \
-alias efalia-doc -storepass changeit
```
***
## Problèmes de Plan de Classement
### Un gabarit n'apparaît pas dans la liste de sélection des mappages
**Cause :** L'élément du Plan de Classement n'a pas d'ID externe défini dans Efalia Doc.
**Solution :**
1. Dans Efalia Doc, accédez au Plan de Classement et définissez un ID externe pour le gabarit concerné
2. Dans Process, lancez une synchronisation manuelle : **Efalia Docs > Plan de classement > Synchroniser**
3. Le gabarit doit maintenant apparaître dans la liste
{% hint style="warning" %}
Seuls les éléments avec un **ID externe renseigné** peuvent être sélectionnés pour les mappages et les connecteurs.
{% endhint %}
***
### Les connecteurs retournent une erreur "Élément PDC introuvable"
**Cause :** L'ID externe référencé dans le JSON de configuration du connecteur n'existe plus dans Efalia Doc (renommage, suppression) ou le PDC n'a pas été resynchronisé après une modification.
**Solutions :**
1. Vérifiez que les IDs externes dans le JSON du connecteur correspondent bien aux IDs définis dans Efalia Doc
2. Resynchronisez le PDC manuellement : **Efalia Docs > Plan de classement > Synchroniser**
3. Si l'ID externe a été modifié, mettez à jour le JSON du connecteur dans le Designer
***
### Le PDC synchronisé automatiquement semble obsolète
**Cause :** La synchronisation automatique nocturne (01:00 par défaut) n'a pas encore été effectuée depuis la dernière modification dans Efalia Doc.
**Solution :** Forcez une synchronisation manuelle immédiate : **Efalia Docs > Plan de classement > Synchroniser**.
***
## Problèmes de Connecteurs
### Un connecteur ne s'exécute pas (aucun log, aucun effet)
**Causes possibles :**
* Le connecteur est configuré sur une opération qui ne s'est pas déclenchée
* Un champ d'entrée obligatoire est vide
**Solutions :**
1. Vérifiez dans le Designer que le connecteur est bien attaché à l'opération attendue
2. Contrôlez que tous les champs d'entrée obligatoires sont renseignés dans le document Process
3. Activez les journaux de débogage et relancez l'opération
***
### `DocumentCreateAndClassifyConnector` ne dépose pas les fichiers
**Causes possibles :**
* Le champ pièce jointe source est vide
* L'UUID du dossier cible est invalide ou non résolu
* Habilitations insuffisantes pour le gabarit cible
**Solutions :**
1. Vérifiez que le champ pièce jointe contient bien des fichiers avant l'exécution du connecteur
2. Si vous utilisez `"dossier": {"uuid": "champ_uuid"}`, vérifiez que `champ_uuid` est renseigné
3. Vérifiez que le compte de service (ou l'utilisateur connecté si `impersonate: true`) a les droits de dépôt dans l'armoire cible
***
### `DocumentUpdateBinaryConnector` ne s'exécute pas
**Cause connue :** Le nombre d'éléments dans le champ des UUIDs GED et le champ des pièces jointes Process n'est pas identique.
**Solution :** Assurez-vous que les deux champs d'entrée contiennent le même nombre d'éléments. Le connecteur n'effectue aucune opération si les comptages diffèrent.
***
### Les métadonnées ne sont pas mises à jour par `DocumentMetadataUpdaterConnector`
**Causes possibles :**
* L'UUID du document GED est incorrect ou vide
* L'ID externe de la métadonnée dans le JSON est erroné
* Le gabarit du document ne contient pas la métadonnée référencée
**Solutions :**
1. Vérifiez que le champ contenant l'UUID GED est correctement renseigné
2. Vérifiez la correspondance entre les IDs externes utilisés et ceux définis dans Efalia Doc
3. Consultez les journaux de débogage pour le message d'erreur précis
***
## Problèmes de Lancement de Workflow depuis Efalia Doc
### Le bouton "Lancer un workflow" n'apparaît pas dans Efalia Doc
**Causes possibles :**
* Aucun mappage n'est défini pour ce gabarit de document
* L'utilisateur n'a pas les habilitations pour lancer un workflow depuis Doc
**Solutions :**
1. Créez un mappage dans **Efalia Docs > Mappage** pour le gabarit concerné
2. Vérifiez les habilitations de l'utilisateur dans Efalia Doc
***
### Le workflow se lance mais les métadonnées ne sont pas transmises
**Causes possibles :**
* Le mappage ne couvre pas toutes les métadonnées souhaitées
* Le champ Process cible n'est pas du bon type
**Solutions :**
1. Vérifiez la configuration du mappage dans **Efalia Docs > Mappage**
2. Assurez-vous que les types de champs Process sont compatibles avec les métadonnées Doc (texte → texte, date → date…)
***
## Problèmes avec l'Agent `ImportMGXAgent`
### L'agent ne traite pas les documents de la bannette
**Causes possibles :**
* Paramètres `mgx.bannette.in` incorrects dans `catalina.properties`
* L'agent n'est pas activé ou sa planification est incorrecte
* Problème de connexion à l'API Process (`workey.api.url`)
**Solutions :**
1. Vérifiez les paramètres dans `catalina.properties` :
```properties
workey.api.url=http://workey/api
workey.api.login=workey_service
workey.api.password=votre_mot_de_passe
mgx.bannette.in=Bannette In
mgx.bannette.out=Bannette Out
```
2. Vérifiez que l'agent est bien configuré et planifié dans l'administration Process
3. Testez la connectivité vers l'API Process depuis le serveur
***
## Questions Fréquentes
Comment savoir si la synchronisation du PDC a réussi ?
Dans **Efalia Docs > Plan de classement**, la date et l'heure de la **dernière synchronisation réussie** sont affichées. Si la synchronisation a échoué, un message d'erreur est affiché à la place de la date.
Un connecteur peut-il échouer silencieusement (sans bloquer l'opération) ?
Par défaut, un connecteur en erreur fait échouer l'opération et affiche un message d'erreur à l'utilisateur. Il n'y a pas de mode "silencieux" natif. Vérifiez toujours les journaux si une opération semble ne pas avoir d'effet.
Comment tester un connecteur sans affecter les données de production ?
Configurez un environnement de **recette** connecté à une instance Efalia Doc de test. Utilisez des armoires et gabarits dédiés avec des données de test. Ne testez jamais directement en production.
Que faire si un ID externe est modifié en production ?
1. Identifiez tous les connecteurs utilisant cet ID externe (recherchez dans le Designer de chaque processus concerné)
2. Planifiez une fenêtre de maintenance
3. Modifiez l'ID externe dans Efalia Doc
4. Resynchronisez immédiatement le PDC dans Process
5. Mettez à jour les JSON de configuration de tous les connecteurs impactés
6. Testez les workflows concernés avant de remettre en production
Les erreurs de connecteur apparaissent-elles dans les logs Efalia Doc ?
Les erreurs côté connecteur apparaissent dans les journaux Efalia Process (`catalina.out`). Les erreurs côté GED (habilitations, document introuvable…) peuvent également générer des entrées dans les journaux Efalia Doc selon sa configuration.
***
Pour aller plus loin :
* [Configuration Avancée](/documentations/efalia-process/vue-ensemble/mise-en-oeuvre/configuration-avancee.md)
* [Mise en Œuvre](/documentations/efalia-process/vue-ensemble/mise-en-oeuvre.md)
* [Connecteurs Efalia Doc](/documentations/efalia-process/vue-ensemble/mise-en-oeuvre/connecteurs-efalia-doc.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/vue-ensemble/mise-en-oeuvre/troubleshooting.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.