> 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/connecteurs/connecteurs-metiers/eksae.md).
# Eksaé
## Introduction
Le connecteur Eksaé pour Efalia Doc permet de déposer et de mettre à jour des documents dans la GED Efalia Doc depuis Eksaé. Contrairement au connecteur PCRM Rio (lecture seule), il expose 4 WebServices permettant respectivement de déposer un document (avec classement direct ou pré-classement en bannette), de mettre à jour ses métadonnées (avec classement ou reclassement), de le télécharger et de le supprimer. Chaque WebService utilise le protocole REST avec un retour JSON.
Cette page s'adresse aux chefs de projet techniques en charge de l'installation du connecteur chez un client, et détaille le paramétrage — notamment les tables de correspondance entre les types Eksaé et les gabarits Efalia Doc —, les WebServices exposés et les vérifications post-installation.
## Architecture du connecteur
Le connecteur est un module déployé sur la plateforme Efalia Utilities. Eksaé lui transmet directement ses documents par appel HTTP (multipart), avec les métadonnées associées en paramètres ; le module traduit ces informations vers les gabarits et métadonnées Efalia Doc grâce à des tables de correspondance définies en configuration, puis classe ou pré-classe le document dans Efalia Doc.
{% hint style="info" %}
Selon ses métadonnées, un document déposé est soit classé directement dans le dossier cible, soit pré-classé dans une bannette de dépôt en attendant un classement manuel.
{% endhint %}
### Synthèse des flux techniques
| Flux | Source | Destination | Protocole / port | Contenu |
| -------------------------------- | ----------------------------------- | ----------------------------------- | -------------------------------------- | ------------------------------------------------------------ |
| Dépôt / mise à jour de documents | Eksaé | Connecteur Eksaé (Efalia Utilities) | REST (JSON), appel HTTP POST multipart | Fichier et métadonnées (paires clé/valeur) |
| Classement des documents | Connecteur Eksaé (Efalia Utilities) | Efalia Doc (API) | REST (JSON) / port 1202 | Création, mise à jour et classement de dossiers et documents |
### WebServices exposés
| WebService | URL | Méthode | Propriétés | Description |
| ---------------------------- | -------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Dépôt d'un document | `/srv/eksae/document` | POST | `fichier` (document à importer), `typeDossier` (identifiant Eksaé du type de dossier), `typeDoc` (identifiant Eksaé du type de document), `aClasser` (`true`/`false`), `meta` (tableau de paires `cle`/`valeur`) | Envoie un document vers la GED. Recherche le dossier de l'armoire de destination (créé s'il n'existe pas ; déposé en bannette de rejet si plusieurs dossiers correspondent). Si `aClasser` est vrai, le document est classé directement ; sinon il est déposé en bannette de dépôt, pré-classé. Retourne le statut de l'opération et l'identifiant Efalia Doc du document créé. |
| Mise à jour d'un document | `/srv/eksae/document/{idDoc}` | POST | `typeDossier`, `typeDoc`, `aClasser`, `meta` (mêmes formats que ci-dessus) | Met à jour les métadonnées d'un document déjà présent en GED. Selon `aClasser` et l'état du document, il est conservé en bannette, classé, ou reclassé d'un dossier vers un autre ; en cas de dossier ambigu, le document est déposé en bannette de rejet. |
| Téléchargement d'un document | `/srv/eksae/document/{idDoc}/download` | GET | — | Retourne le flux binaire du document. |
| Suppression d'un document | `/srv/eksae/document/{idDoc}/delete` | DELETE | — | Retourne un booléen confirmant la suppression. |
Une interface Web (`/eksae/home`) liste ces WebServices et leurs paramètres ; seule l'action de téléchargement y est réellement opérationnelle, les autres actions ne peuvent pas être déclenchées depuis cette interface.
Interface listant les WebServices exposés par le connecteur Eksaé
## Pré-requis techniques et plan de classement type
### Versions logicielles requises
Le document source ne précise pas de version minimale d'Efalia Doc ou d'Efalia Utilities pour ce connecteur ; il indique seulement que le connecteur est intégré au dépôt Efalia Utilities.
### Droits et accès nécessaires
* **Efalia Doc** : créer un utilisateur technique ayant accès aux armoires et bannettes du projet. Vérifier que son rôle Efalia Doc autorise la lecture et l'écriture sur les gabarits identifiés.
* Deux bannettes doivent exister et être accessibles au compte technique : une **bannette de dépôt** (pré-classement des documents non classés) et une **bannette de rejet** (documents en erreur, notamment en cas de dossier ambigu).
### Plan de classement et tables de correspondance
Le paramétrage du connecteur repose sur 4 tables de correspondance à définir dans `config.php`, entre les identifiants Eksaé et les identifiants externes Efalia Doc :
* **`gabaritsDossiers`** : correspondance entre chaque type de dossier Eksaé et le gabarit de dossier Efalia Doc cible (identifiant externe).
* **`gabaritsDocuments`** : correspondance entre chaque type de document Eksaé et le gabarit de document Efalia Doc cible.
* **`metadatas`** : correspondance entre chaque métadonnée envoyée par Eksaé et la métadonnée Efalia Doc cible (identifiant externe).
* **`folderIdentifier`** : pour chaque gabarit de dossier ou de document, liste des métadonnées (identifiants externes Efalia Doc) permettant de retrouver un dossier existant ; plusieurs métadonnées possibles, séparées par une virgule.
{% hint style="warning" %}
🚧 À valider avec l'équipe projet : les valeurs exactes de ces 4 tables (types de dossier et de document Eksaé, métadonnées transmises, plan de classement Efalia Doc) dépendent du projet client et doivent être définies au cas par cas — le document source ne fournit qu'un exemple de structure, pas de valeurs génériques.
{% endhint %}
### Sécurité et flux réseau
* **Eksaé → Connecteur (Efalia Utilities)** : appels HTTP multipart sur `/srv/eksae/document` (POST, dépôt), `/srv/eksae/document/{idDoc}` (POST, mise à jour), `/srv/eksae/document/{idDoc}/download` (GET) et `/srv/eksae/document/{idDoc}/delete` (DELETE). Le document source ne précise pas de port dédié pour ce flux.
* **Connecteur (Efalia Utilities) → Efalia Doc** : API REST JSON sur le port 1202 (HTTPS), via l'URL définie dans `apiURL`.
## Installation du connecteur
{% stepper %}
{% step %}
## Préparation dans Efalia Doc
1. Créer un utilisateur technique ayant accès aux armoires et bannettes du projet, avec un rôle Efalia Doc autorisant la lecture et l'écriture sur les gabarits identifiés.
2. Créer la bannette de dépôt (pré-classement) et la bannette de rejet attendues par le connecteur, et vérifier que le compte technique y a accès.
3. Définir le plan de classement (gabarits de dossiers, gabarits de documents, métadonnées) qui servira de base aux tables de correspondance du connecteur.
{% endstep %}
{% step %}
## Déploiement du code
Le connecteur est intégré au dépôt Efalia Utilities. Se reporter à la procédure d'installation d'une machine virtuelle Utilities.
{% endstep %}
{% step %}
## Paramétrage (config.php)
Après installation du code, copier `config-dist.php` en `config.php` à la racine du projet (ce fichier est ignoré par les mises à jour de livraison). Exemple de configuration :
```php
"name" => "efaliaDocEksaé",
"apiURL" => "https://connectorhub-doc.efalia.net:1202",
"authenticationMode" => "login/password",
"userLogin" => "xxxx",
"userPassword" => "yyyy",
"fileIdentifier" => "fichier",
"externalIdBannetteDepot" => "aaaaa",
"externalIdBannetteRejet" => "bbbbb",
"logs" => [
"path" => "/logs",
"journal" => 1,
"debug" => false,
],
"gabaritsDossiers" => [
"EKSAE_TYPEDOSSIER_1" => "efaliadoc_gabaritdossier_1",
"EKSAE_TYPEDOSSIER_2" => "efaliadoc_gabaritdossier_2",
],
"gabaritsDocuments" => [
"EKSAE_TYPEDOCUMENT_1" => "efaliadoc_gabaritdocmnet_1",
"EKSAE_TYPEDOCUMENT_2" => "efaliadoc_gabaritdocmnet_2",
],
"metadatas" => [
"EKSAE_METADATA_1" => "efaliadoc_mdexternalid_1",
"EKSAE_METADATA_2" => "efaliadoc_mdexternalid_2",
"EKSAE_METADATA_3" => "efaliadoc_mdexternalid_3",
],
"folderIdentifier" => [
"efaliadoc_gabaritdossier_1" => ["efaliadoc_mdexternalid_1"],
"efaliadoc_gabaritdocment_2" => ["efaliadoc_mdexternalid_2", "efaliadoc_mdexternalid_3"],
]
```
* `name` : nom du projet — ne pas modifier.
* `apiUrl` : lien d'accès à l'API Efalia Doc.
* `authenticationMode` : mode d'authentification à l'API Efalia Doc, `login/password` par défaut.
* `userLogin` / `userPassword` : identifiants du compte technique transmis pour l'authentification.
* `fileIdentifier` : clé d'identification de la propriété utilisée pour l'envoi du fichier (`fichier` dans les exemples d'appel).
* `externalIdBannetteDepot` / `externalIdBannetteRejet` : identifiants externes de la bannette de dépôt (documents pré-classés) et de la bannette de rejet.
* `logs.journal` : `0` désactivé, `1` erreurs seulement, `2` tous les appels ; `logs.debug` recommandé à `false` en production.
* `gabaritsDossiers` / `gabaritsDocuments` / `metadatas` / `folderIdentifier` : tables de correspondance décrites ci-dessus.
Exemple d'appel pour le dépôt d'un document :
```
curl --location 'http://localhost/eksae/document' \
--form 'meta[0][cle]="MATRICULE_AGENT"' \
--form 'meta[0][valeur]="ABC-123"' \
--form 'meta[1][cle]="NOM_USUEL"' \
--form 'meta[1][valeur]="MARTIN"' \
--form 'fichier=@"/Users/Tests/pdfTest.pdf"' \
--form 'typeDossier="AGENT"' \
--form 'typeDoc="CONTRAT"' \
--form 'aClasser="true"'
```
{% endstep %}
{% endstepper %}
## Vérifications post-installation
* Utilisateur technique créé avec accès en lecture/écriture sur les armoires, bannettes et gabarits concernés.
* Bannette de dépôt et bannette de rejet accessibles au compte technique.
* Tables de correspondance (`gabaritsDossiers`, `gabaritsDocuments`, `metadatas`, `folderIdentifier`) alignées avec le plan de classement Efalia Doc et les types transmis par Eksaé.
* Test de dépôt d'un document avec `aClasser=true` : classement direct vérifié dans le bon dossier.
* Test de dépôt d'un document avec `aClasser=false` : présence vérifiée en bannette de dépôt.
* Test de dépôt créant un conflit (plusieurs dossiers correspondants) : document bien redirigé vers la bannette de rejet.
* Test de mise à jour des métadonnées d'un document existant, y compris reclassement d'un dossier vers un autre.
* Test de téléchargement et de suppression d'un document.
* Niveau de logs vérifié (`journal`) et mode debug désactivé en production.
## Glossaire
| Terme | Définition |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Bannette de dépôt | Bannette où sont pré-classés les documents envoyés sans classement immédiat (`aClasser = false`), en attente de classement. |
| Bannette de rejet | Bannette recevant les documents dont le dossier cible est ambigu (plusieurs correspondances) ou en erreur. |
| Gabarit de dossier / document | Modèle de dossier ou de document défini dans Efalia Doc, identifié par son identifiant externe. |
| `idDoc` | Identifiant Efalia Doc du document, retourné lors du dépôt et utilisé pour les opérations de mise à jour, téléchargement et suppression. |
| Compte technique | Utilisateur dédié utilisé par le connecteur pour accéder à la GED via l'API. |
---
# 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/connecteurs/connecteurs-metiers/eksae.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.