> 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/configuration-avancee.md).

# Configuration Avancée

Ce guide couvre les aspects avancés de la configuration de l'intégration entre Efalia Process et Efalia Doc : choix du mode d'authentification, propriété `impersonate`, activation des journaux de débogage et bonnes pratiques de sécurité.

***

## Types d'Authentification

L'intégration Efalia Doc prend en charge deux modes d'authentification, configurables dans l'administration (**Efalia Docs > Paramètres**).

{% tabs %}
{% tab title="Compte de service" %}
**Comment ça fonctionne :**

Toutes les actions effectuées par les connecteurs dans Efalia Doc sont attribuées à un **compte de service unique** (login + mot de passe).

**Caractéristiques :**

* Simple à mettre en place
* Toutes les opérations apparaissent sous l'identité du compte de service dans les journaux Efalia Doc
* Le compte de service doit avoir les habilitations nécessaires dans toutes les armoires concernées
* La propriété `impersonate` doit **ne pas être utilisée** dans les JSON de configuration des connecteurs

**Configuration dans `Paramètres` :**

1. Type d'authentification : `Compte de service`
2. Login : identifiant du compte de service Efalia Doc
3. Mot de passe : mot de passe du compte de service
   {% endtab %}

{% tab title="Clé d" %}
**Comment ça fonctionne :**

L'intégration utilise une **clé d'API** Efalia Doc. Le comportement dépend ensuite de la propriété `impersonate` définie dans chaque connecteur.

**Caractéristiques :**

* Permet de choisir, connecteur par connecteur, si les actions sont tracées sous l'identité de l'utilisateur connecté ou sous celle de l'application Process
* Nécessite une clé d'API valide générée dans Efalia Doc
* Offre plus de granularité pour la traçabilité des actions

**Configuration dans `Paramètres` :**

1. Type d'authentification : `Clé d'API`
2. Clé d'API : valeur de la clé générée dans Efalia Doc

**Comportement selon `impersonate` :**

| Valeur `impersonate` | Utilisateur réalisant l'action dans Doc |
| -------------------- | --------------------------------------- |
| Absent (non défini)  | Compte de service (rétrocompatibilité)  |
| `false`              | L'application Efalia Process            |
| `true`               | L'utilisateur connecté dans Process     |
| {% endtab %}         |                                         |
| {% endtabs %}        |                                         |

***

## La Propriété `impersonate`

### Présentation

La propriété `impersonate` est un booléen **optionnel** présent dans le JSON de configuration des connecteurs Efalia Doc. Elle contrôle sous quelle identité les opérations sont effectuées dans Efalia Doc.

```json
{
    "gabarit": "id_externe_gabarit",
    "mapping": {
        "Champ_Process": "id_externe_meta"
    },
    "impersonate": true
}
```

### Les trois cas possibles

{% hint style="warning" %}
**Règle critique**

Le comportement de `impersonate` dépend du **type d'authentification configuré** dans l'administration. Ne pas ignorer le cas 2 ci-dessous.
{% endhint %}

**Cas 1 — Propriété absente (comportement par défaut)**

Quel que soit le type d'authentification configuré, c'est le **compte de service** qui est utilisé. Ce comportement garantit la rétrocompatibilité des configurations existantes lors d'une migration vers la Clé d'API.

**Cas 2 — Authentification `Compte de service` + `impersonate` défini**

À **proscrire**. Si le type d'authentification est modifié ultérieurement (passage à Clé d'API), les workflows existants changeront d'utilisateur pour les actions Doc, ce qui risque d'engendrer des problèmes de droits.

**Cas 3 — Authentification `Clé d'API`**

| Valeur                 | Effet                                                                                  |
| ---------------------- | -------------------------------------------------------------------------------------- |
| `"impersonate": true`  | L'utilisateur connecté dans Process réalise l'action dans Doc (traçabilité nominative) |
| `"impersonate": false` | L'application Process réalise l'action dans Doc                                        |

### Quand utiliser `impersonate: true` ?

Utilisez `impersonate: true` (avec Clé d'API) lorsque :

* La traçabilité des actions par utilisateur est requise (conformité, audit)
* Les habilitations Doc doivent être vérifiées par utilisateur (certains utilisateurs ne doivent pas pouvoir classer dans certaines armoires)
* Les règles métier dans Efalia Doc dépendent de l'identité de l'utilisateur

Utilisez `impersonate: false` (ou absent) lorsque :

* Les actions doivent toujours réussir indépendamment des droits des utilisateurs individuels
* Une seule entité applicative doit apparaître dans les journaux Doc

***

## Journaux de Débogage

### Activation

En cas de problème avec les connecteurs ou la connexion Efalia Doc, activez les journaux de débogage dans l'administration.

{% stepper %}
{% step %}

#### Accéder aux paramètres

Dans l'administration Efalia Process (`/workey/admin`), naviguez vers **Efalia Docs > Paramètres**.

📸 **CAPTURE : config-avancee-01-parametres.png**

> Panneau de paramétrage avec le bouton d'activation des journaux de débogage
> {% endstep %}

{% step %}

#### Activer le mode débogage

Cochez l'option **Activer les journaux de débogage** et sauvegardez.

Les journaux apparaissent ensuite dans `catalina.out` avec le niveau `DEBUG` pour les composants Efalia Doc.
{% endstep %}

{% step %}

#### Analyser les journaux

Recherchez dans `catalina.out` les entrées liées aux connecteurs MGX :

```bash
grep "mgx\|MGX\|Efalia Doc" $CATALINA_HOME/logs/catalina.out | tail -100
```

Les erreurs courantes sont accompagnées d'un message explicite indiquant la cause (erreur d'authentification, élément PDC introuvable, habilitations insuffisantes...).
{% endstep %}

{% step %}

#### Désactiver après résolution

Désactivez les journaux de débogage une fois le problème résolu. Les journaux détaillés peuvent rapidement augmenter la taille des fichiers de log en production.
{% endstep %}
{% endstepper %}

### Niveaux de journalisation personnalisés

Pour un contrôle plus fin, modifiez `log4j.properties` dans le répertoire de configuration Tomcat :

```properties
# Journaux détaillés pour l'intégration Efalia Doc
log4j.logger.com.clog.workey.mgx=DEBUG

# Journaux pour les agents Multigest v2
log4j.logger.com.clog.workey.mg.agents=DEBUG

# Journaux pour les connecteurs Multigest v2
log4j.logger.com.clog.workey.mg.connectors=DEBUG
```

***

## Sécurité et Bonnes Pratiques

{% hint style="success" %}
**✅ Recommandations**

* Utiliser la **Clé d'API** plutôt que le Compte de service pour les nouvelles installations (meilleure traçabilité et flexibilité)
* Créer un compte de service dédié à Efalia Process dans Efalia Doc, avec les droits **strictement nécessaires** (principe du moindre privilège)
* Stocker les identifiants dans `catalina.properties` et non dans les formulaires Process
* Renouveler régulièrement la clé d'API ou le mot de passe du compte de service
* Tester la connexion après chaque modification de paramètre dans l'onglet Paramètres (le statut affiché confirme la connexion ou indique l'erreur)
  {% endhint %}

{% hint style="danger" %}
**❌ À éviter**

* Utiliser un compte utilisateur nominatif comme compte de service
* Partager la clé d'API entre plusieurs applications
* Laisser le mode débogage activé en production
* Définir `impersonate` dans les connecteurs si l'authentification est en mode `Compte de service`
  {% endhint %}

***

## Matrice de Décision : Quel Mode Choisir ?

| Critère                       | Compte de service    | Clé d'API                        |
| ----------------------------- | -------------------- | -------------------------------- |
| Simplicité de configuration   | ✅ Très simple        | ⬜ Simple                         |
| Traçabilité nominative        | ❌ Non                | ✅ Oui (avec `impersonate: true`) |
| Habilitations par utilisateur | ❌ Ignorées           | ✅ Respectées                     |
| Rétrocompatibilité            | ✅ Totale             | ✅ (avec `impersonate` absent)    |
| Recommandation                | Existant / migration | Nouvelles installations          |

***

Pour aller plus loin :

* [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)
* [Dépannage](/documentations/efalia-process/vue-ensemble/mise-en-oeuvre/troubleshooting.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/configuration-avancee.md?ask=<question>&goal=<endgoal>
```

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