> 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/produit/efalia-process/administration/parametrage-connecteurs.md).

# Paramétrage des Connecteurs

Ces connecteurs et agents optionnels s'installent et se paramètrent au niveau du serveur, en complément du moteur Efalia Process.

## Connecteur Conversion .docx vers .pdf

`com.clog.workey.connectors.DocxToPdfConnector`

**Action :** transformation de fichiers docx contenus dans un champ pièce-jointe en PDF.

* **En entrée :** un champ de type pièce-jointe (peut être multivalué).
* **En sortie :** la liste des UUID des pièces-jointes converties en PDF, pouvant servir à alimenter un champ pièce-jointe.

## Agent d'Extraction

**Classe de l'agent: `com.clog.workey.agents.extract.ExtractionAgent`**

Cet agent permet l'extraction des documents et de leurs pièces-jointes ayant été modifiés depuis sa dernière exécution.

Par défaut, les documents sont exportés en XML, sous la même forme que l'archiveur ou l'API Rest. Les fichiers XML extraits sont nommés `document-III-yyyyMMddHHmm.xml`, où `III` est l'identifiant du document, suivi du timestamp de l'agent d'exportation. S'il existait un précédent document avec le même identifiant dans le répertoire il sera supprimé, de même que pour le répertoire des pièces-jointes.

Il est également possible d'exécuter d'autres types de traitement sur ces documents à l'aide de classes Java ou de scripts Groovy.

### Installation

Le fichier `workey-agent-extraction-x.y.z.jar` (où x.y.z est le numéro de version) doit être placé dans le répertoire `$TOMCAT_HOME/workey/libs`.

### Paramètres

* **outputDirectory** : Répertoire où seront exportés les documents et les pièces jointes. Ce paramètre est obligatoire si le processeur par défaut est appelé (voir plus bas).
* **processName** : Nom interne du processus à traiter. Si cette valeur est absente, tous les documents, de tous les processus sont pris en compte.
* **doctypeName** : Nom interne du type de document à traiter. Si ce paramètre est rempli, il est nécessaire d'avoir aussi défini le nom du processus.
* **workflowManager** (*obligatoire*) : Identifiant du gestionnaire de workflow qui va extraire les données.
* **processorClass** : Nom d'une classe Java implémentant l'interface `com.clog.workey.agents.extract.ExtractionDocumentProcessor` qui autorise un traitement supplémentaire lors de l'export de chaque document et pièce-jointe. Ce paramètre permet de faciliter l'intégration avec des moteurs de reporting. Plusieurs noms de classes peuvent être indiqués, séparés par les caractères suivants : "`;`", "`:`" ou "`,`". Voir ci-dessous.
* **exportAttachments** : Si la valeur de cette propriété est "`true`", les pièces-jointes seront extraites.
* **dateRange** : Si cette option est activée, le mode de sélection de l'agent n'est plus le mode normal (export des documents modifiés depuis son dernier lancement). Les documents compris entre les dates définies dans ce paramètre seront exportés. Le format de ce paramètre est `yyyyMMddHHmm-yyyyMMddHHmm`. Cette option peut être utile pour faire une exportation globale des documents déjà présent sur le serveur.

*N.B.*: si cette option est utilisée, la date d'exécution de l'agent n'est pas mise à jour afin de ne pas fausser des extractions ultérieures en mode "normal".

### Classes de traitement des documents

#### Traitement par défaut

**Export des documents**

Afin d'éviter de se retrouver avec un trop grand nombre de fichiers par répertoire, les fichiers sont uniformément distribués dans 2\*255 sous-niveaux de répertoire (de `00/` à `ff/`). Si les pièces-jointes sont exportées, elles seront toujours dans la même branche que leur document. Ainsi, un document et ses pièces-jointes seront par exemple exportés ainsi :

```
+ outputDirectory
  +-37
  | +-d2
  | | +-1234
  | | | +-document-1234-202102101145.xml
  |     +-document-1234-attachments/
          +-297e458a76d8ae8c0176d8c0772d0001-fichier.docx
          +-297e458a76f672490176f69c670b000b-facture.pdf
```

*N.B.* les fichiers sont sauvegardés sur disque de cette manière seulement si le processeur par défaut est appelé (dans les cas où le paramètre `processorClass` est vide, ou bien s'il contient la valeur `<D>`).

#### Export des pièces-jointes

Les pièces jointes sont copiées dans un sous-répertoire nommé "`document-{docId}-attachments/`". Le nom des fichiers extrait est constitué de l'identifiant unique de la pièce-jointe (*uuid*) et de son nom original.

#### Appel d'autres classes de traitement

Pour combiner cette classe avec d'autres classes de traitement, vous pouvez utiliser son nom raccourci "`<D>`" dans le paramètre `processorClass`. Également, si le nom de la classe commence par "`P`", le package `com.clog.workey.agents` sera utilisé.

Par exemple pour sauvegarder les fichier et créer un fichier Excel, vous pouvez mettre comme valeur : `<D>;P.ExcelExtractionProcessor` (qui est équivalent à `com.clog.workey.agents.extract.DefaultExtractionProcessor;com.clog.workey.agents.extract.ExcelExtractionProcessor`, mais en plus succinct).

À l'instar des connecteurs Workey, si des classes de traitements externes sont développées, le fichier `.jar` contenant ces classes doit être placé dans le répertoire `$TOMCAT_HOME/workey/libs`.

**ExcelExtractionProcessor – Récapitulatif Excel**

* Classe "`com.clog.workey.agents.extract.ExcelExtractionProcessor`" : Créé un fichier Excel récapitulant les données extraites lors de l'exécution de l'agent, avec une feuille pour les documents exportés et une autre pour les pièces-jointes.

**GroovyExtractionProcessor – Exécution d'un processor par script groovy**

* Classe "`com.clog.workey.agents.extract.GroovyExtractionProcessor`" : Charge un script nommé `ExtractionGroovy.groovy` dans le répertoire de sortie de l'agent, ou le script indiqué par la propriété système `com.clog.workey.agents.extract.GroovyExtractionProcessor.script`. Ce script doit comporter les méthodes suivantes pour fonctionner correctement. Elles seront appelées de la même manière qu'une classe java implémentant l'interface `ExtractionDocumentProcessor` (voir ci-dessous).

```
void initDocumentProcessor(extractionAgent) {
    /* a remplir */
}

void processDocument(documentId, xmlDoc) {
    /* a remplir */
}

void processAttachment(documentId, xmlDoc, attachmentElement, attachment, data) {
    /* a remplir */
}

void closeDocumentProcessor() {
    /* a remplir */
}

boolean filterDocument(documentId, xmlDoc) {
    /* a remplir */
}
```

Voici un autre exemple d'un script insérant des données des documents et des pièces-jointes dans une base de données externe :

```
import javax.naming.InitialContext;
import groovy.sql.Sql;
import java.sql.Timestamp;
import java.util.Date;
import java.text.SimpleDateFormat;

datasource = null;
sql = null;
startTime = null;

/* Exemple de schema mySQL:
 * CREATE TABLE attachments (
 *   uuid char(32) NOT NULL,
 *   doc_id bigint(20) NOT NULL,
 *   file_name text NOT NULL,
 *   extract_time datetime NOT NULL
 * );
 * ALTER TABLE attachments ADD PRIMARY KEY (uuid);
 *
 * CREATE TABLE documents (
 *   id bigint(20) NOT NULL,
 *   current_state text NOT NULL,
 *   title text NOT NULL,
 *   last_modified datetime NOT NULL,
 *   last_actor text NOT NULL,
 *   extract_time datetime DEFAULT NULL
 * );
 * ALTER TABLE documents ADD PRIMARY KEY (id);
 */

void initDocumentProcessor(extractionAgent) {
    startTime = System.currentTimeMillis();

    // Utilisation de la datasource Workey:
    //datasource = new InitialContext().lookup('java:comp/env/WorkeyReportDS');
    //sql = Sql.newInstance(datasource);

    // ou bien d'une connexion directe:
    Map dbConnParams = [
        url: 'jdbc:mysql://localhost/workey-report',
        user: 'root',
        password: '',
        driver: 'com.mysql.jdbc.Driver'
    ];
    sql = Sql.newInstance(dbConnParams);
}

void processDocument(documentId, xmlDoc) {
    sdfTime = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSS");

    // Extraction des données par XPath
    def state = xmlDoc.selectSingleNode(
        "/wky:document/wky:header/wky:state/@name").text;
    def subject = xmlDoc.selectSingleNode(
        "/wky:document/wky:header/wky:subject").text;
    def updateTime = new Timestamp(sdfTime.parse(xmlDoc.selectSingleNode(
        "/wky:document/@update-time").text).time);
    def actor = xmlDoc.selectSingleNode(
        "//wky:history/wky:stamp[position()=last()]/wky:actor/@name").text;
    def extractTime = new Timestamp(System.currentTimeMillis());

    // Insertion dans la base de données
    sql.execute """
        REPLACE INTO documents
            (id, current_state, title, last_modified,
             last_actor, extract_time)
        VALUES (${documentId}, ${state}, ${subject}, ${updateTime},
             ${actor}, ${extractTime})
    """;
}

void processAttachment(documentId, xmlDoc, attachmentElement, attachment, data) {
    def uuid = attachment.UUID;
    def fileName = attachment.fileName;
    def extractTime = new Timestamp(System.currentTimeMillis());

    // Insertion dans la base de données des données de
    // la pièce-jointe.
    sql.execute """
        REPLACE INTO attachments
            (uuid, doc_id, file_name, extract_time)
            VALUES (${uuid}, ${documentId}, ${fileName}, ${extractTime})
    """;
}

void closeDocumentProcessor() {
    sql.close();
    def timeInSec = (System.currentTimeMillis() - startTime) / 1000;
    println("Groovy process done in ${timeInSec} sec.");
}

boolean filterDocument(documentId, xmlDoc) {
    return true;
}
```

Ce script existe également sous forme de classe Java "`com.clog.workey.agents.extract.DatabaseExtractionProcessor`".

**StarpageStart – Démarrage Starpage**

Classe "`com.clog.workey.agents.extract.StarpageStart`" : création d'un fichier "`start`" en fin de traitement de l'agent pour le démarrage automatique du \_daemon\_Starpage.

#### Interface `ExtractionDocumentProcessor`

Cette interface est composée de cinq méthodes :

* `initDocumentProcessor(ExtractionAgent extractionAgent)`: Elle est exécutée avant le traitement des documents. Une instance de l'agent est passée en paramètre, qui permet d'accéder au répertoire de sortie (`getBaseOutputDirectory()`), au timestamp utilisé par cet agent (`getAgentTimestamp()`), aux noms du processus et du type de document le cas échéant (`getProcessName()` et `getDocumentTypeName()`).
* `filterDocument(long docId, Document xmlDoc)` : Cette méthode est appelée après chaque ouverture de document pour savoir s'il doit être inclus dans l'export. Doit renvoyer "`true`" si le document doit être exporté, "`false`" s'il ne doit pas l'être.
* `processDocument(long docId, Document xmlDoc)` : Cette méthode est appelée après l'export de chaque document.
* `processAttachment(long docId, Document xmlDoc, Element attachmentElement, DocumentData attachment, InputStream data)` : Cette méthode est appelée après l'export de chaque pièce-jointe.
* `closeDocumentProcessor()` : Cette méthode est appelé à la fin de l'exécution de l'agent.

De plus, la classe ExtractionAgent dispose d'un méthode `Map<String, Object> getExtractionContext()` qui permet d'échanger des informations entre les différentes classes de traitement. Ainsi, la classe de traitement par défaut inclura le nom du document en cours de traitement dans la clé `DefaultExtractionProcessor.XML_OUTPUT_FILE`, et les fichiers des pièces-jointes sauvegardés dans les clés avec le UUID de la pièce-jointe.

Par exemple une classe minimaliste de traitement pourrait ressemble à :

```
package com.clog.workey.agents.extract;

import java.io.InputStream;

import org.dom4j.Document;
import org.dom4j.Element;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import com.clog.workey.core.DocumentAttachment;

public class DummyExtractionProcessor implements ExtractionDocumentProcessor {
    private static final Logger logger = LoggerFactory.getLogger(DummyExtractionProcessor.class);

    @Override
    public void initDocumentProcessor(ExtractionAgent extractionAgent) throws ExtractionProcessorException {
        logger.info("initDocumentProcessor");
    }

    @Override
    public void processDocument(long documentId, Document xmlDoc) throws ExtractionProcessorException {
        logger.info(String.format("processDocument %d", documentId));
    }

    @Override
    public void processAttachment(long documentId, Document xmlDoc, Element attachmentElement,
            DocumentAttachment attachment, InputStream data) throws ExtractionProcessorException {
        logger.info(String.format("processAttachment %s from doc %d", attachment.getUUID(), documentId));
    }

    @Override
    public void closeDocumentProcessor() throws ExtractionProcessorException {
        logger.info("closeDocumentProcessor");
    }

    @Override
    public boolean filterDocument(long documentId, Document xmlDoc) throws ExtractionProcessorException {
        logger.info(String.format("filterDocument %d", documentId));
        return true;
    }
}
```

## Connecteur CSV Sage

Connecteur permettant la création d'un fichier CSV pour Sage comportant des informations relatives à une facture.

### Format du fichier CSV

Le fichier CSV produit par ce connecteur contient les champs dans l'ordre de la table ci-dessous. Le caractère séparateur de champ est "`;`", sans échappement des chaînes de caractères. Les nombres sont au format français, sans séparateur des milliers ("`1234,56`" par ex).

| Champ CSV             | Description                                                               |
| --------------------- | ------------------------------------------------------------------------- |
| Nom du journal        | Nom du journal à utiliser ("`ACH`", par ex.)                              |
| Date de la facture    | Date de la facture au format `YYYYMMDD`                                   |
| Date d'échéance       | Date d'échéance de la facture au format `YYYYMMDD`                        |
| Numéro chronologique  | Identifiant unique (Id du document Workey, par ex)                        |
| Numéro de la facture  | Numéro indiqué sur la facture                                             |
| Compte à imputer      | Numéro d'imputation comptable                                             |
| Code fournisseur      | Identifiant du fournisseur (présent seulement sur la première ligne)      |
| Libellé de l'écriture | Libellé de l'écriture                                                     |
| Montant TTC           | Montant TTC de l'entrée                                                   |
| Débit/Crédit          | Indique si l'entrée est une opération de débit ou crédit ("`D`" ou "`C`") |
| Moyen de paiement     | Code du moyen de paiement (entier)                                        |
| Devise                | Code de la devise ("`EUR`", par ex)                                       |
| Cours de la devise    | Cours de la devise ("`1`" si aucune conversion n'est nécessaire)          |
| Total devise          | Résultat de l'opération Montant TTC \* Cours devise                       |
| Bon à payer           | Indique si la facture est validée pour paiement ("`OUI`" ou "`NON`")      |

Champs CSV exportés par le connecteur

### Appel du connecteur

Classe : `com.clog.workey.connectors.sage.ExportSage`

#### Paramètres d'entrée

1. Champ ayant comme valeur un objet JSON comportant la configuration (voir [Configuration JSON](#configuration-json)) des différents champs à utiliser.

#### Valeurs de sortie

1. (*Aucune*)

### Configuration

#### Propriétés systèmes

Plusieurs propriétés systèmes peuvent être configurées dans le fichier `$TOMCAT/conf/catalina.properties` pour définir des valeurs par défaut à utiliser :

* `com.clog.workey.connectors.ExportSage.exportDir` : Répertoire où seront créés les fichiers CVS pour Sage (par défaut `$TOMCAT/workey/sage/`)
* `com.clog.workey.connectors.ExportSage.journal` : Nom par défaut du journal si aucun champ journal n'est présent dans le formulaire ("`ACH`", par ex).
* `com.clog.workey.connectors.ExportSage.compteTiers` : Compte tiers par défaut si aucun champ n'est présent dans le formulaire.

#### Configuration JSON

La configuration permet d'effectuer un "mapping" entre les champs présents dans le formulaire Workey et les champs attendus dans le CVS Sage. Pour chaque propriété (voir la liste ci-dessous), il est possible d'indiquer le nom du champ qui lui correspond. Sinon, le nom de champ par défaut et/ou la valeur par défaut sera utilisé.

```
{
  "codeFournisseur": "Fournisseur",
  "compteGeneral": "Compte_debit",
  "devise": "Monnaie"
}
```

**Liste des propriétés**

| Propriété             | Nom du champ par défaut    | Observations                                                     |
| --------------------- | -------------------------- | ---------------------------------------------------------------- |
| journal               | Journal                    | propriété *com.clog.workey.connectors.ExportSage.journal*        |
| compteTiers           | Compte\_tiers              | propriété *com.clog.workey.connectors.ExportSage.compteTiers*    |
| compteGeneral         | Compte\_general            |                                                                  |
| dateFacture           | Date\_facture              |                                                                  |
| dateEcheance          | Date\_echeance             |                                                                  |
| numeroFacture         | Numero\_facture            |                                                                  |
| codeFournisseur       | Code\_fournisseur          |                                                                  |
| libelleEcriture       | Libelle\_ecriture          |                                                                  |
| montant               | Montant\_TTC               | valeur par défaut : `0`                                          |
| detailMontant         | Montant\_net               | champ multivalué                                                 |
| detailCompte          | Compte\_general            | champ multivalué                                                 |
| detailLibelle         | Libelle                    | champ multivalué                                                 |
| modePaiement          | Moyen\_paiement            |                                                                  |
| devise                | Devise                     | valeur par défaut : `EUR`                                        |
| coursDevise           | Cours\_devise              | valeur par défaut : `1`                                          |
| bonAPayer             | Bon\_a\_payer              | valeur par défaut : `false`                                      |
| tvaIntracommunautaire | TVA\_Intracommunautaire    | valeur par défaut : `false`                                      |
| compteTvaIntraCredit  | Compte\_TVA\_intra\_credit |                                                                  |
| compteTvaIntraDebit   | Compte\_TVA\_intra\_debit  |                                                                  |
| typeFacture           | Type\_facture              | valeurs possibles : `INVOICE` (facture) ou `CREDIT NOTE` (avoir) |

Propriétés pour la correspondance Workey/CSV

En plus de ces propriétés utilisées pour la correspondance entre les champs Workey et les champs CSV, il est possible de redéfinir le nom du fichier de sortie avec la propriété "`fileTemplate`". Sa valeur par défaut est "`ExportSage-%s.csv`", où le "`%s`" représente la date (au format `YYYYMMDD`). Par conséquent, un seul fichier d'export par jour est créé, qui va contenir toutes les factures traitées dans la journée.

{% hint style="warning" %}
Si la propriété "`fileTemplate`" est redéfinie, la marque "`%s`" doit toujours être présentes.
{% endhint %}

#### TVA Intracommunautaire

Si la propriété "`tvaIntracommunautaire`" est à "`true`", deux lignes supplémentaires seront créés dans le fichiers CSV : l'une pour l'opération de crédit avec le compte d'imputation indiqué par la propriété "compteTvaIntraCredit" et l

### Limitations

Actuellement, la ventilation de la facture sur plusieurs compte n'est pas supportée.

***

## Statistiques MixPanel

Lorsque la fonctionnalité de suivi MixPanel est activée, certaines actions du moteur vont alimenter de manière anonyme la base d'événement MixPanel.

{% hint style="warning" %}
L'intégration de MixPanel n'est disponible que pour les version **6.11.4** de Workey et suivantes.
{% endhint %}

Afin de minimiser l'impact de la collecte de ces événements, ils sont envoyés dans une queue JMS qui les traitera au fur et à mesure de manière asynchrone. Cependant, il n'est pas garanti que 100% des messages devant générer un événement MixPanel soient pris en compte.

### Installation

Par défaut, cette fonctionnalité est désactivé. Pour la mettre en place, il suffit d'ajouter la propriété suivante au fichier `$TOMCAT_HOME/conf/catalina.properties` :

```
com.clog.workey.analytics.mixpanel.enable=true
```

### Évènements suivis

* **Create Document** : Déclenché lors de la demande de création d'un nouveau document. En plus des propriétés standard, il contient les propriétés `workey-process`, `workey-document-type`, `workey-state` et `workey-role`.
* Open Document : (non suivi car peu fiable)
* **Submit Document** : Déclenché à la fin de la soumission d'un document (donc pas en cas d'erreur). En plus des propriétés standard, il contient les propriétés :
  * `workey-document`,
  * `workey-process`,
  * `workey-document-type`,
  * `workey-state`,
  * `workey-role`,
  * `workey-agent`, booléen indiquant si la soumission a été faite par un agent
  * `workey-document-alive`, booléen indiquant si le document est arrivé en fin de vie (plus d'état suivant disponible)
* **Save Document** : Déclenché lors de l'enregistrement d'un document (sans changement d'état). En plus des propriétés standard, il contient les propriétés `workey-document`, `workey-process`, `workey-document-type`, `workey-state` et `workey-role`.
* **Open View** : Déclenché lors de l'ouverture ou rafraîchissement d'une vue. En plus des propriétés standard, il contient les propriétés `workey-view`.
* Error during submit : (non suivi actuellement)
* **Execute Search** : Déclenché lorsque une recherche est effectué. Aucune propriété particulière n'est envoyée.
* **Deploy Process** : Déclenché lorsqu'un processus est déployé. Pour des raisons techniques, l'utilisateur effectuant ce déploiement ne peut pas être distingué, un utilisateur avec un id "`-1`" et unique pour la license est utilisé. En plus des propriétés standard, il contient les propriétés :
  * `workey-process-name`
  * `workey-deploy-roles`, le nombre de rôles déployés dans ce processus
  * `workey-deploy-operations`, le nombre d'opérations déployées dans ce processus
  * `workey-deploy-doctypes`, le nombre de types de document déployés dans ce processus
  * `workey-deploy-forms`, le nombre de formulaires déployés dans ce processus
  * `workey-deploy-views`, le nombre de vues déployées dans ce processus

### Propriétés MixPanel

Pour des raisons de sécurités, toutes les propriété ci-dessus (hormis les champ booléen) sont pseudonymisées à partir de la licence.

Cette pseudonymisation prend la forme d'un UUID créé à partir du nom du client, du type de données (document-id, operation-id, etc.) et de l'identifiant de la donnée. Cela permet d'identifier de manière unique chaque partie de données sans avoir les données réelles.

Lors de chaque événement envoyé à MixPanel, les propriétés suivantes sont également envoyées :

* `workey-client` : le nom du client (champ "Licensed To" de workey-license.xml), c'est la seule donnée en clair concernant le client.
* `workey-version` : Version de Workey utilisée pour cet événement ("`6.11.4`", par exemple)
* `workey-env` : Valeur (en clair) de la propriété système "`com.clog.workey.analytics.mixpanel.env`", si elle est présente. Cela permet de filtrer certaines installations particulières, si besoin

### Propriétés Workey

* `com.clog.workey.analytics.mixpanel.enable` : Activation/désactivation de l'envoi d'événements vers MixPanel ("`true`" ou "`false`", "`false`" par défaut)
* `com.clog.workey.analytics.mixpanel.token` : Identifiant de l'environnement MixPanel utilisé ("`1c1358cdd54edfb2341e98682f7956e2`": production (par défaut), "`d714004bdc15c44bffa9313eea27f60f`": test)
* `com.clog.workey.analytics.mixpanel.env` : Propriété système alimentant la propriété MixPanel "`workey-env`" (voi ci-dessus)

***

## Workey Mail Checker

Utilitaire de création de document Workey par vérification de boîte mail (POP ou IMAP)

### Installation

* Dézipper le fichier `workey-checkmail-1.0.0.zip` dans un répertoire
* Configurer le fichier de propriété `mailProcess.properties` (voir section *Configuration*)
* Lancer la commande `bin/workey-checkmail`

### Configuration

```
# Configuration de la classe de traitement automatique de mail
# Mode d'utilisation du scheduler.
# - hours: la vérification des mails s'effectue toutes les n heures
# - cron: la vérification des mails s'effectue selon une expression "cron"
#com.workey.scheduler=minutes
#com.workey.scheduler.mode=cron
# Nombre d'heures entre chaque vérification de la boîte aux lettres
com.workey.scheduler.hours=1
# Expression cron utilisé pour la vérification de la boîte aux lettres
# (ici, lancement toutes les 2 minutes)
com.workey.scheduler.cron=0 0/2 * * * ?
# Type de serveur mail (pop3/imap)
com.workey.mail.server.type=imap
# Nom du serveur de mail d'où sont récupérés les mails
com.workey.mail.server.hostname=localhost
# Nom de l'utilisateur mail
com.workey.mail.server.username=workey
# Mot de passe de l'utilisateur mail
com.workey.mail.server.password=workey
# Nom du dossier à vérifier (optionnel)
com.workey.mail.server.inbox=INBOX
# Classe implémenant l'interface IMailProcessor a utiliser pour le traitement des messages
com.workey.mail.processor.class=com.clog.workey.mailchecker.MailProcess
# Designer name de l'état dans lequel le document se trouvera après le traitement du mail
com.workey.mail.state.new=Cree
# Designer name du role effectuant l'opération de traitement du mail
#com.workey.mail.role=R1
com.workey.mail.role=MailChecker
# Designer name du processus de gestion des courriers
com.workey.mail.process=Validation_MailChecker
# Designer name du type de document a créer par le mail
com.workey.mail.doctype=Ticket
# Designer name du champ du formulaire contenant le sujet du mail
com.workey.doc.subject=Objet
# Designer name du champ du formulaire contenant le 'From' du mail
com.workey.doc.from=Expediteur
# Designer name du champ du formulaire contenant le contenu du mail
com.workey.doc.body=Message
# Designer name du champ du formulaire contenant le 'CC' du mail
##com.workey.doc.cc=mail_cc
# Designer name du champ du formulaire contenant les pièces jointes du mail
com.workey.doc.attachments=Pieces_jointes
# Designer name du champ PJ contenant une copie du mail
com.workey.doc.raw_msg=Mail_original
# Configuration de l'API
com.workey.api.login=<wm_login>
com.workey.api.password=<wm_password>
com.workey.api.url=http://localhost:8080/workey/api
# Propriétés réservées à des fins de diagnostic
# Enregistre le mail sur disque en cas d'erreur
#fail.save.mail=true
# Traitement des mails déjà vus
#com.workey.mail.process.seen.mails=true
# Traitement des mails déjà flaggés (traités mais non supprimés)
#com.workey.mail.process.flagged.mails=true
```

### Usage

```
usage: workey-checkmail --properties=checkmail.properties
 -P,--props <property_file>   Name of the property file to load. Options passed on the command line override the
                              properties
 -h,--help                    Displays this message and exit.
```

***

## Workey Selenium Tester

Cet article présente l'installation, la configuration et l'utilisation de la plateforme Workey d'automatisation des tests "`workey-selenium-tester`".

### Installation

* Récupérer la dernière version de `workey-selenium-tester` auprès de votre interlocuteur Efalia.
* Dézipper l'archive (ex. `workey-selenium-tester-1.5.1.zip`) dans un répertoire de votre système.
* Si besoin, importer le fichier des utilisateurs de tests `resources\ldif\test-users.ldif` dans le LDAP (les tests de validation s'attendent à trouver certains de ces utilisateurs).
* Éditer si besoin les fichiers `admin-rest.properties` et `validation-selenium.properties`

#### Scripts Groovy

Les scripts et WKY de validation Workey se trouvent dans le répertoire `tests/validation`. Le script `tests/validation/000-setup.groovy` est particulier car c'est lui qui déploie les WKY, créé les unités organisationnelles et effectue les assignations des acteurs à leur rôles. Il prend ses informations des fichiers `tests/validation/000-assignments.json` et `tests/validation/000-organizational_units.xml`

Plusieurs scripts Groovy ont été développés pour automatiser la création de formulaires, ordres et demandes dans SIRA. Ils se trouvent dans le répertoire `groovy/`. Les scripts utilisés pour tester le processus de blocage-v2 se trouvent dans le répertoire `test/blocage-v2`.

Les scripts Groovy présents dans le répertoire `test/validation/` sont numérotés en essayant de respecter la convention arbitraire :

* `000`: Administration (spécial)
* `001` à `599` : Fonctionnalités de base de Workey
* `600` à `899` : Fonctions spéciales / modules / etc.
* `900` à `999` : Connecteurs

Dans l'idéal, à chaque script Groovy doit correspondre un projet Workey associé avec le même nom (seule l'extension change).

Dans les cartons…

Il faudrait faire en sorte (avec une sorte de fichier Manifest) que le script Groovy puisse déployer lui-même le processus et faire les affectations avant de se lancer.

### Lancement

Les options de `workey-selenium-tester`:

```
usage: workey-selenium-tester [options] scripts.groovy...
 -l,--loop <LOOP>         Number of time each groovy script has to be executed
 -i,--input-file <FILE>   run tests found in FILE
 -t,--type <TYPE>         runner type WORKEY5, WORKEY6 or WORKEY7 (default WORKEY6)
 -5,--workey5             Set the runner as Workey 5
 -6,--workey6             Set the runner as Workey 6 (default)
 -7,--workey7             Set the runner as Workey 7
 -v,--verbose             Prints more message from Selenium driver
 -h,--help                Prints this help message and exit
```

Pour exécuter un script Groovy:

```
.\bin\workey-selenium-tester.bat .\tests\blocage-v2\test00-treeview.groovy
```

Pour exécuter tous les tests contenus dans un fichier contenant un fichier `.groovy` par ligne :

```
.\bin\workey-selenium-tester.bat -i tests_workey.list
```

Une fois tous les scripts exécutés, les statistiques de réussite et d'échec sont affichées. Si des erreurs sont survenues, la liste des scripts problématiques est enregistrées dans le fichier "`failed-scripts.list`".

Dans PowerShell, pour purger les processus des navigateurs robots :

```
stop-process -name chromedriver
```

Dans les cartons…

Prévoir un GUI pour faciliter le lancement des tests et pouvoir enregistrer le résultat des tests de manière synthétique (CSV, XML ou JSON).

### Compilation

* `.\gradlew.bat installZip`
* `.\build\install\workey-selenium-tester\bin\workey-selenium-tester.bat .\tests\blocage-v2\test00-treeview.groovy`

ou bien,

* `.\gradlew.bat distZip`

### Écriture de tests Workey Selenium

### Configuration

#### Fichier de Propriétés

Le constructeur du robot Selenium prend en paramètre un chemin vers un fichier de propriétés. Les différentes propriétés possibles sont les suivantes :

* `selenium.driver.host` : URL de connexion vers le serveur Workey
* `selenium.driver.type` : Type de navigateur à utiliser: "`chrome`" (par défaut), "`firefox`" ou "`edge`". Le driver Chrome est celui qui est privilégié.
* `selenium.driver.timeout` : Temps d'attente en seconde lors de la recherche d'éléments.

**Propriétés spécifiques Chrome**

* `selenium.driver.chrome.profile` : Réutilise le profil Chrome au lieu d'en créer un nouveau à chaque exécution. Cela permet notamment de réutiliser des extensions (valeur "`true`"/"`false`", défaut à "`false`").
* `selenium.driver.chrome.headless` : Lance Chrome sans interface graphiqe (valeur "`true`"/"`false`", défaut à "`false`").
* `selenium.driver.chrome.allow-notifications` : Autorise les notifications à s'afficher (valeur "`true`"/"`false`", défaut à "`false`").
* `selenium.driver.chrome.maximized` : Lance Chrome avec la fenêtre maximisée (valeur "`true`"/"`false`", défaut à "`false`").
* `selenium.driver.chrome.disable-gpu` : Lance Chrome sans accélération graphique, permet parfois de corriger des bugs visuels (valeur "`true`"/"`false`", défaut à "`false`").
* `selenium.driver.chrome.disable-infobars` : Désactive l'affichage d'une barre indiquant que Chrome est lancé en mode automatique (valeur "`true`"/"`false`", défaut à "`false`").

**Propriétés avancées**

* `selenium.driver.skip-pause` : Ignore les pauses manuelles. Utile lorsque les tests doivent être complètement automatiques (valeur "`true`"/"`false`", défaut à "`false`").
* `screenshot.dir` : Répertoire où seront enregistré les copies d'écran (par défaut "`output`")
* `selenium.proxy` : Créé un proxy permettant d'enregistrer les communications au format HAR avec les méthodes `runner.newHar(harFile)` et `runner.saveHar()` (valeur "`true`"/"`false`", défaut à "`false`").
* `selenium.driver.path` : Chemin d'accès aux drivers des navigateurs (par défaut "`drivers`")
* `test.language` : Code du langage utilisé pour les données créées par JFairy (par défaut "`fr`")
* `runner.type` : Type de robot à utiliser (valeur "`WORKEY_5`", "`WORKEY_6`" ou "`WORKEY_7`")

### Déploiement et initialisation des processus

Le script "`validation/000-setup.groovy`" est un script spécial qui permet de définir les gestionnaires de workflow et de processus, de déployer automatiquement des fichiers WKY, de créer des unités organisationnelles et d'affecter des acteurs à des rôles et à des unités.

Il prend ces informations à partir du fichier "`admin-rest.properties`" dans lequel est défini un chemin vers un fichier JSON (voir par exemple, "`tests/validation/000-assignments.json`")

Dans les cartons…

Cette partie va vraisemblablement être modifiée pour être un peu plus flexible.

#### Script Groovy

### Le "Runner" Workey

L'application dispose de plusieurs robots spécialisés dans différentes versions de Workey. Ils peuvent être forcés avec l'option "`--type`" de `workey-selenium-tester`.

* `com.workey.selenium.SeleniumScriptRunner` : Workey 5 / JBoss
* `com.workey.selenium.SiraScriptRunner` : Workey 5 / JBoss / Fonctions spéciales SIRA (Gencods, création des formulaires, etc.)
* `com.workey.selenium.Workey6ScriptRunner` : Workey 6 / Tomcat
* `com.workey.selenium.WorkeyStoreScriptRunner` : Workey 7 – nouvelle interface/ Tomcat

#### Principales propriétés

* `runner` : le "robot" Workey, couche de haut niveau qui sait se connecter à l'application, ouvrir des vues, créer des document, remplir des formulaires, etc
* `runner.driver` : le moteur Selenium, pour effectuer des actions de bas niveau qui ne seraient pas proposé par le runner.
* `runner.logger` : instance de logger
* `runner.fairy` : Générateur de données factices mais vraisemblables (nom de personne, adresses, société, mail, etc). Pour plus d'informations: [JFairy](https://github.com/Devskiller/jfairy).
* `runner.textProducer` : Générateur de texte aléatoire
* `runner.properties` : Propriétés chargées lors de l'exécution du script

#### Principales méthodes Workey

* `runner.getCredentials("XXX")` : récupère le login/mot de passe à partir des propriétés systèmes "`XXX.login`" et "`XXX.password`". Si ces propriétés n'existent pas, le login "`XXX`" est utilisé, avec le mot de passe "`test`".
* `runner.workeyLogin(Credentials)` : Connexion à l'application.

```
// Connexion à workey avec l'utilisateur test001
runner.workeyLogin(new Credentials('test001', 'pa$$w0rd'));
```

* `runner.workeyLogout()` : Déconnexion
* `runner.openView(viewName)` : Ouverture d'une vue (par son libellé en v6 et v7, par son nom interne en v5).

```
// Ouverture de la vue "A Faire" en v6
runner.openView('A Faire')
```

* `runner.openDocumentFromView(documentIdentifier)` : Ouverture d'un document depuis une vue. Le paramètre doit être de préférence une chaîne de caractère permettant d'identifier sans ambigüité le document à ouvrir.

```
// Ouverture d'un document depuis la vue courante
runner.openDocumentFromView('DocumentTest-1C5-FKI-5CT')
```

* `runner.createNewDocument(documentLabel)` : Création d'un nouveau document, en indiquant le libellé avec lequel il apparaît dans le menu de création.

```
runner.createNewDocument('Demande de congés')
runner.createNewDocument('Note de frais [Valideur]')
```

* `runner.setFieldValue(fieldName, value)`: Change la valeur d'un champ.

{% hint style="warning" %}
Le type de la donnée "`value`" doit être une chaîne de caractère.
{% endhint %}

* `runner.setFieldValue(fieldName, value, index)`: Si le champ est multivalué, ou s'il fait partie d'une table dynamique, change la valeur du champ à l'index indiqué (commence à `0`)
* `runner.getFieldValue(fieldName)`: Récupère la valeur du champ.
* `runner.getFieldValue(fieldName, index)`: Récupère la valeur du champ à l'index indiqué si le champ est multivalué, ou s'il fait partie d'une table dynamique (commence à `0`)

#### Méthodes utilitaires annexes

* `runner.waitForField(fieldName)`: Le script attend que le champ soit visible dans le document.

{% hint style="success" %}
Cette fonction est utile pour s'assurer qu'un document a terminé d'être chargé.
{% endhint %}

* `runner.randomId(prefix)` : Génère une chaîne de caractère aléatoire du type "`prefix-ABC-DEF-GHI`". Cela permet notamment de retrouver facilement des documents testés si cette valeur est utilisée dans le sujet du document.
* `runner.close()` : Ferme la fenêtre active du navigateur.
* `runner.quit()` : Quitte le navigateur
* `runner.newTab()` : Création d'un nouvel onglet
* `runner.switchTab()`: Bascule cyclique d'un onglet à l'autre
* `runner.switchToFrame(frame)`: Sélectionne le `<frame>` HTML courante. La plupart des méthodes de WorkeyScriptRunner se chargent de basculer d'une frame à l'autre si besoin.
* `runner.expectAlert(message)` : Si une alerte JS est émise, cette fonction permet de la valider et continuer le test.
* `runner.pause(message)` : Met le script en pause en affichant un message. L'utilisateur doit appuyer sur Entrée pour continuer le test. Cela permet de donner le temps à l'utilisateur d'effectuer des actions non testable (ouverture et vérification d'un fichier externe, par exemple)
* `runner.pause(temps_ms)` : Marque une pause dans le traitement du script. Utile pour être sûr que certains traitements aient le temps de s'effectuer (JS, etc).
* `runner.screenshot(file)`: Prend une capture d'écran de la fenêtre courante du navigateur et l'enregistre dans un fichier.

### Tests JUnit

Les tests se font avec la classe `org.junit.Assert`

```
// Vérification de la valeur d'un champ
Assert.assertEquals("Valeur de champ correcte",
    "Valeur Correcte", runner.getFieldValue('Champ_a_tester'));
```

* `Assert.assertTrue`
* `Assert.assertFalse`
* `Assert.assertEquals`
* `Assert.assertNotNull`

Pour vérifier qu'un objet est visible dans le navigateur:

```
Assert.assertTrue("Element #workey-button visible.",
    driver.findElement(By.id('workey-button')).isDisplayed());
```

### Expressions XPath

Pour tester une expression XPath dans Chrome, avec la console:

```
document.evaluate("//input[@id='Field_XXX']",
    document, null, XPathResult.ANY_TYPE, null ).iterateNext()
```

### Exemple de script

```
import org.junit.Assert;
import org.openqa.selenium.By;
import com.workey.selenium.WorkeyRunnerFactory;
// Création du robot Workey. Le type (v5, v6 ou v7) est déterminé
// automatiquement.
runner = new WorkeyRunnerFactory('validation-selenium.properties').runner;
driver = runner.driver;
logger = runner.logger;
// Connexion avec le login et mot de passe définis dans les propiétés
// user1.login et user1.password
runner.workeyLogin(runner.getCredentials('user1'));
// Création d'un numéro de test aléatoire pour retrouver le document
// facilement lors de la suite des tests
testId = runner.randomId('TestSelenium');
logger.info("Création du document \"${testId}\"." );
// Création du nouveau document
runner.createNewDocument('Document TestSelenium')
// Attente du chargement complet du document
runner.waitForField('Id_Test');
// Vérification de l'état et du formulaire
runner.assertFormAndState('Formulaire_TestSelenium', '__CREATED');
// Remplissage des champs
runner.setFieldValue('Id_Test', testId);
runner.setFieldValue('String', 'Valeur de mon champ');
// Sélection de l'état suivant et soumission du document
runner.selectNextState('Cree');
runner.clickSubmitButton();
// Ouverture du document dans la vue (peut parfois nécessiter
// de rafraichir la vue)
runner.openDocumentFromView(testId);
// Vérification de la valeur du champ
runner.waitForField('Id_Test');
Assert.assertEquals('Champ String', 'Valeur de mon champ',
    runner.getFieldValue('String'));
// Sélection du dernier état et soumission
runner.selectNextState('Termine');
runner.clickSubmitButton();
// Déconnexion et fermeture du navigateur
runner.workeyLogout();
runner.quit();
```

***


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://documentation.efalia.com/produit/efalia-process/administration/parametrage-connecteurs.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
