# Application de workflow GETUSERSFROMDIR

## Aperçu  <a href="#apercu" id="apercu"></a>

L’application de workflow **GETUSERSFROMDIR** permet la récupération d’une liste de noms d’utilisateurs, d’une liste d’emails ou d’une liste des IDs utilisateur. Ces listes s’obtiennent via une action automatique WorkflowGen qui exécute des requêtes SQL sur la base de données WorkflowGen. Elle peut être utilisée pour les notifications automatiques ou pour définir (filtrer) les utilisateurs d’une action d’un processus WorkflowGen.

## Définitions  <a href="#definitions" id="definitions"></a>

* **Le caractère** `x` **:** Le caractère `x` dans certains noms de paramètres signifie qu’il peut exister plus d’une instance du paramètre. Par exemple, `QUERYx_CMD` signifie qu’il peut-y avoir `QUERY1_CMD`, `QUERY2_CMD`, `QUERY3_CMD` etc...<br>
* **Action :** Vous devez créer une action WorkflowGen de type GETUSERSFROMDIR pour utiliser cette application.

## Liste des champs et macros disponibles pour les requêtes  <a href="#liste-champs-macros-disponibles-pour-les-requetes" id="liste-champs-macros-disponibles-pour-les-requetes"></a>

Voici les champs et macros disponibles pour les requêtes créées dans les paramètres `QUERYx_CMD`. Ils peuvent être utilisés dans les conditions de ces requêtes afin de filtrer leurs résultats.

#### 📌 Exemples

Cet exemple retourne une liste des noms d’utilisateur des utilisateurs de la province du Québec :

```
QUERY1_CMD: STATE = 'QC'
RESULT_LIST
```

Cet exemple retourne une liste des noms d’utilisateur des utilisateurs dont l’adresse email termine par `advantys.com` :

```
QUERY1_CMD: EMAIL LIKE '%ADVANTYS.COM'
RESULT_LIST
```

Cet exemple retourne une liste des noms d’utilisateur des utilisateurs appartenant au groupe de développement :

```
QUERY1_CMD: {ISMEMBER(DEV)}  
RESULT_LIST
```

| **Champs disponibles**  | **Définition**                 |
| ----------------------- | ------------------------------ |
| `LASTNAME`              | Nom                            |
| `FIRSTNAME`             | Prénom                         |
| `USERNAME`              | Nom d'utilisateur              |
| `EMAIL`                 | Adresse email                  |
| `PHONE`                 | Numéro de téléphone            |
| `MOBILE`                | Numéro de téléphone mobile     |
| `PAGER`                 | Numéro de téléavertisseur      |
| `FAX`                   | Numéro de fax                  |
| `OFFICE`                | Numéro de bureau               |
| `DEPARTMENT`            | Département                    |
| `COMPANY`               | Société                        |
| `JOBTITLE`              | Fonction                       |
| `PERSONALTITLE`         | Titre                          |
| `EMPLOYEENUMBER`        | Matricule                      |
| `EMPLOYEETYPE`          | Type d’employé                 |
| `POSTALADDRESS`         | Adresse                        |
| `ZIPCODE`               | Code postal                    |
| `CITY`                  | Ville                          |
| `STATE`                 | État/Région                    |
| `COUNTRY`               | Pays                           |
| `EXTATT_1`              | Extended attribute 1           |
| `EXTATT_2`              | Extended attribute 2           |
| `EXTATT_3`              | Extended attribute 3           |
| `EXTATT_4`              | Extended attribute 4           |
| `EXTATT_5`              | Extended attribute 5           |
| `{ISMEMBER(groupname)}` | Retourne les membres du groupe |

| **Macro disponible**    | Définition                     |
| ----------------------- | ------------------------------ |
| `{ISMEMBER(groupname)}` | Retourne les membres du groupe |

## Utilisation des paramètres supplémentaires  <a href="#utilisation-parametres-supplementaires" id="utilisation-parametres-supplementaires"></a>

### `QUERY1_CMD` : Exécution d’une requête SQL

#### Description

Pour lancer une requête SQL vous devez ajouter le paramètre (IN) `QUERY1_CMD` à l’action. Si le paramètre est vide ou inexistant l’opération ne sera pas exécutée.

#### 📌 Exemple

Cet exemple retourne la liste des utilisateurs de la ville de Montréal dans le paramètre `RESULT_LIST` :

```
QUERY1_CMD: CITY = 'MONTREAL'  
RESULT_LIST
```

### `RESULT_LIST` / `QUERYx_RESULT_LIST` : Capture du résultat des requêtes

#### Description

Pour récupérer le résultat de toutes les requêtes (liste des utilisateurs au format chaîne de caractères) vous devez ajouter le paramètre (OUT) `RESULT_LIST` à l’action. Pour récupérer le résultat individuel par requête vous devez ajouter le paramètre (OUT) `QUERYx_RESULT_LIST` pour chaque requête.

#### 📌 Exemple

Cet exemple retourne la liste des utilisateurs de Montréal, Toronto et New York dans le paramètre `RESULT_LIST`. `QUERY1_RESULT_LIST` contient la liste des utilisateurs de Montréal, `QUERY2_RESULT_LIST` contient la liste des utilisateurs de Toronto et `QUERY3_RESULT_LIST` contient la liste des utilisateurs de New York :

```
QUERY1_CMD: CITY = 'MONTREAL'  
QUERY2_CMD: CITY = 'TORONTO'  
QUERY3_CMD: CITY = 'NEW YORK'  
QUERY1_RESULT_LIST  
QUERY2_RESULT_LIST  
QUERY3_RESULT_LIST  
RESULT_LIST
```

{% hint style="info" %}
À partir de la version 7.15.0 de WorkflowGen, le résultat d'une requête renvoyée dans des données de processus de type TEXT n'a plus de limite de 4 000 caractères pour la base de données MS SQL Server.
{% endhint %}

### `QUERY1_DIR` : Définition de l’annuaire

#### Description

Vous pouvez définir l’annuaire des utilisateurs sur lequel vous voulez que porte la requête. Vous devez ajouter un paramètre (IN) `QUERY1_DIR` dans l’action. Si ce paramètre est NULL ou n’existe pas l’annuaire par défaut est `WORKFLOWGEN` (ou l’annuaire défini comme défaut par l’administrateur).

#### 📌 Exemple

Cet exemple retourne la liste des noms d'utilisateur des utilisateurs de l’annuaire `VotreSociété` dans le paramètre `RESULT_LIST` :

```
QUERY1_CMD: CITY = 'MONTREAL'  
QUERY1_DIR: VotreSociété  
RESULT_LIST
```

### `QUERYx_CMD` : Utilisation de plusieurs requêtes

#### Description

Vous pouvez ajouter plusieurs requêtes dans la même action WorkflowGen et récupérer les résultats dans une liste complète ou dans une liste par requête. Vous devez ajouter le paramètre (IN) `QUERYx_CMD` dont `x` est le numéro de la requête. Vous devez ajouter les paramètres (OUT) `QUERYx_RESULT_LIST` pour récupérer les résultats de chaque requête.

#### 📌 Exemple

Cet exemple retourne la liste des noms d'utilisateur des utilisateurs de Montréal de l’annuaire `WORKFLOWGEN` dans le paramètre (IN) `QUERY1_RESULT_LIST`, la liste des noms d'utilisateur des utilisateurs de Montréal de l’annuaire `INTRANET` dans le paramètre (IN) `QUERY2_RESULT_LIST` et la liste complète des noms d'utilisateur des deux requêtes dans le paramètre (IN) `RESULT_LIST` :

```
QUERY1_CMD: CITY = 'MONTREAL'  
QUERY1_DIR: WORKFLOWGEN  
QUERY2_CMD: CITY = 'MONTREAL'  
QUERY2_DIR: INTRANET  
QUERY1_RESULT_LIST  
QUERY2_RESULT_LIST  
RESULT_LIST
```

### `QUERYx_TOP` : Définition du nombre maximum d’enregistrements du résultat

#### Description

Vous pouvez spécifier le nombre maximum d’enregistrements retournés par les requêtes en ajoutant le paramètre (IN) `QUERYx_TOP` à l’action. Cette requête ne sera pas capable de retourner plus de résultats que le nombre défini dans ce paramètre.

#### 📌 Exemples

Cet exemple retourne seulement les deux premiers noms d'utilisateur de cette requête :

```
QUERY1_CMD: CITY = 'MONTREAL'  
QUERY1_TOP: 2  
RESULT_LIST
```

Cet exemple retourne tous les noms d'utilisateur de cette requête :

```
QUERY1_CMD: CITY = 'MONTREAL'  
RESULT_LIST
```

### `QUERYx_DEFAULT_VALUE` : Définition d’une valeur par défaut

#### Description

Vous pouvez définir une valeur par défaut à retourner pour les valeurs qui ne retournent pas de valeur. Vous devez ajouter un paramètre (IN) `QUERYx_DEFAULT_VALUE` à l’action.

#### 📌 Exemple

Dans cet exemple, la requête ne retourne aucune valeur car la société définie n’existe pas. Ainsi le paramètre `RESULT_LIST` contiendra la valeur `défaut1` :

```
QUERY1_CMD: COMPANY = 'SOCIETE_FICTIVE'  
QUERY1_DEFAULT_VALUE = défaut1  
RESULT_LIST
```

### `RESULT_SEPARATOR` : Définition d’un séparateur

#### Description

Vous pouvez définir un caractère de séparation des résultats dans la liste retournée en ajoutant un paramètre (IN) `RESULT_SEPARATOR` à l’action. Le séparateur par défaut est `,` (virgule).

#### 📌 Exemple

Pour cet exemple, la valeur retournée dans le paramètre `RESULT_LIST` est `nom1***nom2***nom3` :

```
QUERY1_CMD: CITY = 'MONTREAL'  
RESULT_SEPARATOR: ***  
RESULT_LIST
```

Cet exemple retourne la valeur `nom1,nom2,nom3` :

```
QUERY1_CMD: CITY = 'MONTREAL'  
RESULT_LIST
```

### `RESULT_COUNT` / `QUERYx_RESULT_COUNT` : Compteur du nombre d’enregistrements retournés

#### Description

Vous pouvez récupérer le nombre d’enregistrements retournés par chaque requête ou par toutes les requêtes. Pour le nombre total d’enregistrements retournés par toutes les requêtes vous devez ajouter le paramètre (OUT) `RESULT_COUNT` à l’action. Pour le nombre d’enregistrements retournés par requête vous devez ajouter le paramètre (OUT) `QUERYx_RESULT_COUNT` à l’action.

#### 📌 Exemple

L’exemple suivant retourne le nombre total d’enregistrements dans le paramètre `RESULT_COUNT` et le nombre d’enregistrements par requête (`QUERY1` et `QUERY2`) dans les paramètres `QUERY1_RESULT_COUNT` et `QUERY2_RESULT_COUNT` :

```
QUERY1_CMD: CITY = 'NY'  
QUERY1_DIR: WORKFLOWGEN  
QUERY2_CMD: CITY = 'NY'  
QUERY2_DIR: INTRANET  
RESULT_LIST  
RESULT_COUNT  
QUERY1_RESULT_COUNT  
QUERY2_RESULT_COUNT
```

### Utilisation des paramètres dans les conditions des requêtes SQL

#### Description

Vous pouvez utiliser des paramètres dans les conditions SQL contenues dans le paramètre `QUERYx_CMD`. Vous devez ajouter des paramètres IN avec des noms différents des noms réservés suivants :

* `QUERYx_CMD`
* `QUERYx_DIR`
* `QUERYx_TOP`
* `QUERYx_RESULT_COUNT`
* `QUERYx_RESULT_LIST`
* `RESULT_LIST`
* `RESULT_COUNT`
* `RESULT_SEPARATOR`

Vous pouvez alors appeler ces paramètres dans la condition en les préfixant par le caractère `@` (arobase).

#### 📌 Exemple

Cet exemple retourne la liste des noms d'utilisateur des utilisateurs de Montréal de l’annuaire `WORKFLOWGEN` :

```
QUERY1_CMD: CITY = @PARAM1  
PARAM1: MONTREAL  
RESULT_LIST
```

N’oubliez pas que le nom du paramètre utilisé dans la condition doit être le même que celui défini dans l’action WorkflowGen.

### `QUERYx_CMD` : Utilisation des macros dans les conditions des requêtes SQL

#### Description

Vous pouvez utiliser des macros dans les conditions SQL contenues dans les paramètres `QUERYx_CMD`. Vous devez simplement ajouter une macro disponible dans la condition.

#### 📌 Exemple

L’exemple suivant retourne la liste des noms d'utilisateur des utilisateurs membres du groupe `Dev` venant de Montréal et associés à l’annuaire `WORKFLOWGEN` :

```
QUERY1_CMD: CITY = 'MONTREAL' and {ISMEMBER(Dev)}  
RESULT_LIST
```

{% hint style="warning" %}
Il est important de respecter la syntaxe dans la liste des macros disponibles.
{% endhint %}

### `RESULT_LIST_EMAIL` / `QUERYx_RESULT_LIST_EMAIL` : Capture des résultats des requêtes sous forme de liste d’emails

#### Description

Pour récupérer la liste des emails résultant de toutes les requêtes vous devez ajouter un paramètre (OUT) `RESULT_LIST_EMAIL` à l’action. Si vous voulez retrouver les emails par requête vous devez ajouter un paramètre (OUT) `QUERYx_RESULT_LIST_EMAIL` pour chaque requête.

#### 📌 Exemple

Cet exemple retourne la liste des emails des utilisateurs de Montréal et Toronto dans le paramètre `RESULT_LIST_EMAIL`. Les paramètres `QUERY1_RESULT_LIST_EMAIL` et `QUERY2_RESULT_LIST_EMAIL` contiennent respectivement la liste des emails des utilisateurs de Montréal et de Toronto :

```
QUERY1_CMD: CITY = 'MONTREAL'  
QUERY2_CMD: CITY = 'TORONTO'  
QUERY1_RESULT_LIST_EMAIL  
QUERY2_RESULT_LIST_EMAIL  
RESULT_LIST_EMAIL
```

## Gestion des erreurs dans WorkflowGen

Vous devez ajouter une action corrective liée à l’action GETUSERSFROMDIR afin de gérer les erreurs d’exécution. Cette action corrective est de type manuel et est lancée sur erreur d’exécution. Ainsi vous devez ajouter cette exception sur la transition entre les deux actions. Vous trouverez ci-dessous la liste des erreurs les plus fréquentes retournées par l’application.

| **Message d’erreur**                                                                                                                                                                                                                                    | **Solution**                                                                                                |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| Cet annuaire n’existe pas (This directory does not exist)                                                                                                                                                                                               | Vérifiez que l’annuaire défini dans la requête est valide.                                                  |
| Contexte XML vide ou incorrect (XML context is empty or incorrect)                                                                                                                                                                                      | Vérifiez si l’application est réellement exécutée par WorkflowGen                                           |
| Erreur de connexion à la base de donnée (Database connection error)                                                                                                                                                                                     | Vérifiez si la chaîne de connexion à la base de données dans le fichier « config.inc » est valide.          |
| Erreur de requête (Query error)                                                                                                                                                                                                                         | Vérifiez si les champs ou les macros utilisés dans le paramètre `QUERYx_CMD` sont valides.                  |
| La requête retourne trop de valeurs (The queries return too many values)                                                                                                                                                                                | Ajouter des conditions dans le paramètre `QUERYx_CMD` pour filtrer les résultats.                           |
| Le paramètre « (nom du paramètre) » possède le même nom qu’un nom de paramètre réservé par WorkflowGen. Vous devez modifier ce nom. (The parameter "(parameter name)" has the same name as a WorkflowGen reserved parameter. You must change the name.) | Modifiez le nom de ce paramètre pour un nom différent de ceux réservés par WorkflowGen pour les paramètres. |
| Les requêtes retournent trop d’enregistrements (The queries return too many records)                                                                                                                                                                    | Ajouter des conditions dans les paramètres `QUERYx_CMD` pour filtrer les résultats.                         |
| Le paramètre « (nom du paramètre) » doit avoir une valeur (The parameter "parameter name" must have a value)                                                                                                                                            | Vérifiez dans l’action de WorkflowGen si ce paramètre est vide.                                             |
| Le paramètre « (nom du paramètre) » est obligatoire ("Parameter name" parameter is required)                                                                                                                                                            | Ajouter ce paramètre à l’action WorkflowGen.                                                                |

## Nombre maximum d’enregistrements retournés  <a href="#nombre-maximum-enregistrements-retournes" id="nombre-maximum-enregistrements-retournes"></a>

Il existe une constante `GetUsersFromDirMaxResultNb` dans le fichier `web.config` contenant le nombre maximum d’enregistrements pouvant être retourné par une requête. Cette limite réduit le risque d’une erreur d’expiration d’un temps limite qui peut se produire lorsque les résultats des requêtes sont trop nombreux. Si le nombre d’enregistrements retournés est supérieur à la valeur de cette constante un message d’erreur indiquant que les requêtes retournent trop d’enregistrements (« The queries returned too many records ») sera affiché.