> 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/parametrage-connecteurs.md).

# Paramétrage des Connecteurs

Les **connecteurs** sont des composants Java qui s'exécutent côté serveur lors d'une opération de workflow. Ils permettent d'automatiser des traitements : génération de documents, appels à des services externes, synchronisation de données, manipulation des acteurs et des droits d'accès.

***

## Principe de Fonctionnement

Un connecteur est associé à une **opération** dans le Designer HTML. Il est exécuté automatiquement lors du déclenchement de cette opération par un utilisateur ou par le moteur de workflow.

**Architecture d'un connecteur :**

```
Opération déclenchée
       ↓
  [Connecteur Java]
  ┌────────────────────────────────────┐
  │ Entrées (champs du document)       │
  │         ↓                         │
  │ Traitement (logique Java / Groovy) │
  │         ↓                         │
  │ Sorties (mise à jour des champs)   │
  └────────────────────────────────────┘
       ↓
  Document mis à jour
```

Les connecteurs lisent des **champs en entrée** et écrivent dans des **champs en sortie** du document. Le mapping entrée/sortie est configuré dans les propriétés du connecteur dans le Designer.

***

## Ajouter un Connecteur à une Opération

{% stepper %}
{% step %}

#### Ouvrir l'opération dans le Designer

Dans le Designer HTML, sélectionnez l'opération sur laquelle vous souhaitez attacher un connecteur.
{% endstep %}

{% step %}

#### Accéder aux connecteurs de l'opération

Dans les propriétés de l'opération, naviguez vers l'onglet **Connecteurs**. Cliquez sur **Ajouter un connecteur**.

📸 **CAPTURE : admin-tech-connecteurs-01-ajout-connecteur.png**

> Interface des propriétés d'une opération avec l'onglet Connecteurs et le bouton d'ajout
> {% endstep %}

{% step %}

#### Sélectionner le connecteur

Saisissez le **nom de classe Java complet** du connecteur (ex : `com.clog.workey.connectors.AutoNumbering`) dans le champ classe.
{% endstep %}

{% step %}

#### Configurer les paramètres d'entrée et de sortie

Mappez les champs d'entrée et de sortie du connecteur avec les champs du document. L'ordre des paramètres est important : il correspond à l'ordre déclaré dans la documentation de chaque connecteur.

📸 **CAPTURE : admin-tech-connecteurs-02-mapping-champs.png**

> Configuration des entrées/sorties d'un connecteur avec le mapping des champs du document
> {% endstep %}

{% step %}

#### Déployer et tester

Déployez le processus et testez l'opération pour vérifier que le connecteur s'exécute correctement. Consultez les logs Tomcat (`catalina.out`) en cas d'erreur.
{% endstep %}
{% endstepper %}

***

## Connecteurs Standard

### Gestion des Acteurs et des Droits

| Connecteur                        | Classe Java                                                | Description                                                                                                  |
| --------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| **ActorsOuMembers**               | `com.clog.workey.connectors.ActorsOuMembers`               | Retourne les acteurs appartenant aux unités et/ou rôles spécifiés (intersection si les deux sont renseignés) |
| **ActorsUnitHierarchy**           | `com.clog.workey.connectors.ActorsUnitHierarchy`           | Retourne les unités dans un intervalle hiérarchique par rapport à l'unité d'un acteur donné                  |
| **AddReadersFromUo**              | `com.clog.workey.connectors.AddReadersFromUo`              | Ajoute les membres d'une unité organisationnelle en tant que lecteurs du document courant                    |
| **SameUnitActorsAsReaders**       | `com.clog.workey.connectors.SameUnitActorsAsReaders`       | Ajoute tous les acteurs de l'unité de l'acteur courant comme lecteurs (propagé aux documents fils)           |
| **SearchUserAttributesConnector** | `com.clog.workey.connectors.SearchUserAttributesConnector` | Recherche des attributs utilisateur dans l'annuaire LDAP                                                     |
| **LdapConnector**                 | `com.clog.workey.connectors.LdapConnector`                 | Récupère des informations directement dans l'annuaire LDAP à partir d'un DN de base et d'un filtre           |

#### ActorsOuMembers — Détail

**Entrées :**

1. DN des unités organisationnelles (multi-valué, peut être vide)
2. Noms internes des rôles (multi-valué, peut être vide)
3. *(optionnel)* Propriété LDAP pour le nom d'affichage
4. *(optionnel)* Mettre à `1` si utilisé pour alimenter un domaine de valeur

**Sortie :** Liste des DNs des acteurs correspondant aux critères

{% hint style="info" %}
💡 Si les deux paramètres (unités et rôles) sont vides, **l'ensemble des acteurs** de la base est retourné.
{% endhint %}

***

### Copie de Champs entre Documents

| Connecteur                  | Classe Java                                          | Description                                                                              |
| --------------------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| **CopyFieldsToChildren**    | `com.clog.workey.connectors.CopyFieldsToChildren`    | Copie les valeurs des champs du document père vers ses fils (mêmes noms internes requis) |
| **CopyFieldsToDescendants** | `com.clog.workey.connectors.CopyFieldsToDescendants` | Copie les champs vers tous les descendants (fils, petits-fils…)                          |
| **CopyFieldsToFather**      | `com.clog.workey.connectors.CopyFieldsToFather`      | Copie les champs d'un document fils vers son document père                               |

**Paramètre d'entrée commun :** Liste des noms internes des champs à copier (multi-valué)

{% hint style="warning" %}
⚠️ Les champs doivent avoir **exactement le même nom interne** dans le document source et le document cible.
{% endhint %}

***

### Génération de Documents

| Connecteur                    | Classe Java                                            | Description                                                                      |
| ----------------------------- | ------------------------------------------------------ | -------------------------------------------------------------------------------- |
| **DocxMergeConnector**        | `com.clog.workey.connectors.DocxMergeConnector`        | Génère un fichier `.docx` à partir d'un modèle Word et des données du formulaire |
| **DocxToPdfConnector**        | `com.clog.workey.connectors.DocxToPdfConnector`        | Convertit des fichiers `.docx` en pièces jointes au format `.pdf`                |
| **PdfMergeConnector**         | `com.clog.workey.connectors.PdfMergeConnector`         | Génère un fichier `.pdf` à partir d'un modèle PDF et des données du formulaire   |
| **MergePdfFiles**             | `com.clog.workey.connectors.MergePdfFiles`             | Fusionne plusieurs fichiers PDF en un seul                                       |
| **FicheCirculationConnector** | `com.clog.workey.connectors.FicheCirculationConnector` | Génère une fiche de circulation (historique des états) au format PDF             |

#### DocxMergeConnector — Configuration JSON (v6.10.7+)

Depuis la version 6.10.7, le connecteur accepte un paramètre JSON en second paramètre :

```json
{
  "templateDir": "../workey/docx/templates",
  "mergeDir": "../workey/docx/merge",
  "output": "docx",
  "attachmentFilename": "document_genere.docx",
  "hasAttachment": "true"
}
```

| Propriété            | Description                                                       |
| -------------------- | ----------------------------------------------------------------- |
| `templateDir`        | Répertoire contenant les modèles `.docx`                          |
| `mergeDir`           | Répertoire de sortie des fichiers générés                         |
| `output`             | Format de sortie (`docx` ou `pdf`)                                |
| `attachmentFilename` | Nom du fichier généré                                             |
| `hasAttachment`      | `"true"` pour attacher le fichier au champ pièce jointe de sortie |

#### MergePdfFiles — Configuration JSON

```json
{
  "destinationFileName": "document_fusion.pdf",
  "prependFiles": ["/chemin/vers/couverture.pdf"],
  "appendFiles": ["/chemin/vers/annexe.pdf"],
  "sortOrder": "DATE",
  "mergeMode": "SINGLE"
}
```

| Propriété             | Valeurs                       | Description                                                                                   |
| --------------------- | ----------------------------- | --------------------------------------------------------------------------------------------- |
| `destinationFileName` | —                             | Nom du fichier PDF résultant (défaut : `merge.pdf`)                                           |
| `sortOrder`           | `NAME` (défaut), `DATE`       | Ordre de tri des pièces jointes en entrée                                                     |
| `mergeMode`           | `SINGLE` (défaut), `MULTIPLE` | `SINGLE` : un seul PDF résultant / `MULTIPLE` : chaque PDF reçoit les fichiers prepend/append |

***

### Numérotation Automatique

**Connecteur :** `com.clog.workey.connectors.AutoNumbering`

Retourne une valeur auto-incrémentée à partir d'une table externe (`INCREMENT`). Utile pour générer des numéros de référence uniques.

**Configuration dans `catalina.properties` :**

```properties
# Source de données utilisée (défaut : workey-incrmt-ds)
com.clog.workey.connectors.AutoNumbering.datasource=workey-incrmt-ds

# Nom de la table (défaut : INCREMENT)
com.clog.workey.connectors.AutoNumbering.tableName=INCREMENT

# Nom de la colonne ID (défaut : ID)
com.clog.workey.connectors.AutoNumbering.idField=ID

# Nom de la colonne clé (défaut : KEY_VALUE)
com.clog.workey.connectors.AutoNumbering.keyField=KEY_VALUE
```

**Création de la table (MySQL) :**

```sql
CREATE TABLE INCREMENT (
    ID INT(11) NOT NULL,
    KEY_VALUE TEXT
);
INSERT INTO INCREMENT (ID, KEY_VALUE) VALUES (0, 'ma_cle');
```

**Entrée :** Clé à utiliser pour distinguer les différents compteurs (optionnel) **Sortie :** Nouvelle valeur incrémentée

{% hint style="warning" %}
⚠️ **Depuis v6.11.3** : sans clé, `NULL` est utilisé comme valeur de clé. Pour revenir à l'ancien comportement (incrément de tous les ID), activez : `com.clog.workey.connectors.AutoNumbering.incrementAll=true`
{% endhint %}

***

### Opérations sur Documents Fils

| Connecteur                    | Classe Java                                            | Description                                            |
| ----------------------------- | ------------------------------------------------------ | ------------------------------------------------------ |
| **LaunchOperationOnChildren** | `com.clog.workey.connectors.LaunchOperationOnChildren` | Lance des opérations modélisées sur les documents fils |

**Entrées :**

1. Liste des triplets `Rôle;Opération;État d'arrivée` (multi-valué)
2. Liste des états éligibles en entrée du document fils (multi-valué)

***

### Connecteur Groovy (Script)

**Connecteur :** `com.clog.workey.connectors.ScriptConnector`

Permet d'exécuter un script **Groovy** sans nécessiter de compilation Java et redémarrage serveur. Idéal pour les logiques métier personnalisées.

**Emplacement des scripts :** `$WORKEY_DATA/scripts/`

**Variables disponibles dans le script :**

| Variable   | Description                                       |
| ---------- | ------------------------------------------------- |
| `params`   | Tableau des champs passés en entrée au connecteur |
| `document` | Document Workey courant                           |
| `api`      | Instance de l'API Workey (non transactionnelle)   |
| `logger`   | Logger pour écrire dans `catalina.out`            |
| `result`   | Variable de retour (`String[]`)                   |

**Exemple minimal :**

```groovy
// Script: calcul_ttc.groovy
def montantHT = Float.parseFloat(params[1].stringValue())
def tva = 20.0
def totalTTC = montantHT * (1 + tva / 100)

logger.debug("Calcul TTC: ${montantHT} * 1.20 = ${totalTTC}")

result = [String.valueOf(totalTTC)] as String[]
```

**Entrée du connecteur dans le Designer :**

1. Nom du script (ex : `calcul_ttc.groovy`)
2. Champ Montant\_HT

**Sortie :** Champ Total\_TTC

***

### Connecteur API REST

**Connecteur :** `com.clog.workey.connectors.ApiRest`

Permet d'effectuer des requêtes HTTP vers des services REST externes.

Pour la documentation complète de ce connecteur, consultez l'article [Développeurs > Connecteur API REST](/documentations/efalia-process/vue-ensemble-api/connecteur-api-rest.md).

***

## Connecteurs d'Événements (preNotification)

Les connecteurs d'événements s'exécutent **avant l'envoi d'une notification email**. Ils permettent de personnaliser le contenu, le sujet ou les destinataires des emails envoyés par Efalia Process.

**Configuration dans `catalina.properties` :**

```properties
com.clog.workey.events.preNotification=com.clog.workey.connectors.events.VelocityMailConnector
```

| Connecteur                | Description                                                                                        |
| ------------------------- | -------------------------------------------------------------------------------------------------- |
| **VelocityMailConnector** | Transforme le contenu de la notification via un template Velocity (HTML ou texte)                  |
| **MailConnectorSaveMail** | Enregistre les emails de notification sur disque (archivage)                                       |
| **GroovyMailConnector**   | Modifie les notifications via un script Groovy (sujet, expéditeur, destinataires, pièces jointes…) |
| **HTMLMailConnector**     | Convertit le type de contenu d'un email texte en HTML                                              |

### VelocityMailConnector — Personnalisation des emails

**Emplacement des templates :** `$WORKEY_DATA/velocity-templates/mail/`

**Règle de nommage des templates :**

1. `{Process}-{Doctype}-{State}.vml` — Template spécifique à un état
2. `{Process}-{Doctype}.vml` — Template pour tout l'état du document
3. Si aucun fichier trouvé : notification originale envoyée

**Variables Velocity disponibles :**

| Variable                                     | Description                                   |
| -------------------------------------------- | --------------------------------------------- |
| `$Workey_Notification_URL`                   | URL d'accès au document                       |
| `$Workey_Notification_Body`                  | Texte de notification saisi par l'utilisateur |
| `$Workey_Document.id`                        | Identifiant du document                       |
| `$Workey_Document.process.designerName`      | Nom interne du processus                      |
| `$Workey_Document.currentState.designerName` | Nom interne de l'état courant                 |
| `$Workey_Process_label`                      | Nom localisé du processus                     |
| `$Workey_State_label`                        | Nom localisé de l'état courant                |
| `$Workey_Message.subject`                    | Sujet du mail                                 |

**Personnalisation du sujet** via `mail_subjects.properties` dans le répertoire des templates :

```properties
Mon_Processus-Mon_Document=Demande #{Workey_Document.id} : ${Champ_Sujet}
```

***

## Connecteurs Multigest 9

Ces connecteurs permettent la synchronisation entre Efalia Process et Efalia Doc (Multigest 9).

| Connecteur                      | Description                                                                                   |
| ------------------------------- | --------------------------------------------------------------------------------------------- |
| **CreateFolderFromAttachments** | Crée un dossier dans Efalia Doc à partir d'une pièce jointe                                   |
| **SyncAttachments**             | Synchronise les pièces jointes d'un document vers un dossier Efalia Doc                       |
| **SyncFields**                  | Synchronise les valeurs des champs d'un document vers les métadonnées d'un dossier Efalia Doc |

Pour la documentation complète, consultez [Intégrations > Efalia Doc](/documentations/efalia-process/vue-ensemble/mise-en-oeuvre/connecteurs-efalia-doc.md).

***

## Développer un Connecteur Personnalisé

Pour des besoins non couverts par les connecteurs standard, il est possible de développer un connecteur Java personnalisé.

{% hint style="info" %}
💡 Avant de développer un connecteur Java, évaluez si le **ScriptConnector** (Groovy) ne répond pas à votre besoin — il est plus rapide à mettre en œuvre et ne nécessite pas de redémarrage serveur.
{% endhint %}

Pour la documentation de développement, consultez [Développeurs > Développer un Connecteur Personnalisé](/documentations/efalia-process/vue-ensemble-api/developper-connecteur-custom.md).

***

## Bonnes Pratiques

{% hint style="success" %}
**✅ À faire :**

* Tester les connecteurs en **recette** avant la production
* Activer les logs `DEBUG` temporairement pour diagnostiquer un connecteur défaillant
* Utiliser le **ScriptConnector** pour la logique personnalisée (plus facile à modifier)
* Documenter le rôle de chaque connecteur dans la description de l'opération du Designer
* Gérer les erreurs dans les scripts Groovy (`try/catch`) pour éviter de bloquer le workflow
  {% endhint %}

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

* Modifier directement la base de données Efalia Process depuis un connecteur (utiliser l'API)
* Exécuter des requêtes SQL lourdes synchrones depuis un connecteur (impact sur les performances)
* Oublier de supprimer les logs `DEBUG` en production
* Laisser des fichiers temporaires non nettoyés (ex : ScriptConnector générant des fichiers)
  {% endhint %}

***

## Questions Fréquentes

<details>

<summary>Comment déboguer un connecteur qui ne s'exécute pas ?</summary>

1. Vérifiez que le **nom de classe Java** du connecteur est correct (sensible à la casse)
2. Vérifiez que l'ordre des **paramètres d'entrée** correspond à la documentation
3. Activez le niveau `DEBUG` dans `log4j.properties` pour voir les messages du moteur de connecteurs
4. Consultez `catalina.out` pour les messages `[User: xxx] Connect to class...` et les erreurs associées
5. Pour les ScriptConnectors, vérifiez que le fichier `.groovy` est dans le bon répertoire (`$WORKEY_DATA/scripts/`)

</details>

<details>

<summary>Peut-on enchaîner plusieurs connecteurs sur une même opération ?</summary>

Oui. Il est possible d'attacher **plusieurs connecteurs** à une même opération dans le Designer. Ils sont exécutés dans l'**ordre défini** dans la liste des connecteurs. Le résultat d'un connecteur peut ainsi être utilisé en entrée du suivant.

</details>

<details>

<summary>Le ScriptConnector peut-il utiliser des bibliothèques Java externes ?</summary>

Oui. Placez les fichiers `.jar` dans `<CATALINA_HOME>/workey/libs/` et chargez-les dynamiquement dans le script Groovy :

```groovy
def myLib = new File("../workey/libs/ma-librairie.jar").toURI().toURL()
Thread.currentThread().getContextClassLoader().addURL(myLib)
```

</details>

<details>

<summary>Comment personnaliser les emails de notification sans redéployer le processus ?</summary>

Utilisez le **VelocityMailConnector** : les templates Velocity (fichiers `.vml`) sont chargés dynamiquement à chaque envoi d'email. Vous pouvez modifier un template sans redémarrer le serveur ni redéployer le processus.

</details>

***

Pour aller plus loin :

* [Langages de Processus (STalk, WKYJS)](/documentations/efalia-process/administration/administration-fonctionnelle/langages-process.md)
* [Développeurs > Connecteur API REST](/documentations/efalia-process/vue-ensemble-api/connecteur-api-rest.md)
* [Intégrations > Efalia Doc](/documentations/efalia-process/vue-ensemble/mise-en-oeuvre/connecteurs-efalia-doc.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/parametrage-connecteurs.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.