> 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/developpeurs/connecteur-api-rest.md).
# Connecteur API REST
## Préambule
Ce connecteur permet :
* d'effectuer différents types de requêtes vers un service web REST
* d'envoyer et de recevoir de l'information sous différentes formes (des fichiers, du texte, du JSON, des formulaires...)
* de travailler directement avec le composant `Pièce Jointe` de Process
C'est pour ces différentes possibilités qu'une documentation lui est réservé.
L'utilisation du connecteur se compose de deux parties : une partie requête et une partie réponse.
Ce connecteur ne couvre pas tout ce qui est possible d'effectuer avec un service web REST mais permet de réaliser les opérations les plus courantes. Il est disponible à partir de la version **6.36.0** de Process.
{% hint style="warning" %}
* Pour profiter pleinement du connecteur, il est conseillé d'être familiarisé avec les concepts d'API REST.
* Le fait de copier/coller les exemples ne suffit pas à exploiter toutes les possibilités du connecteur, il faut absolument lire la partie [Notes](#notes).
{% endhint %}
## Classe Java du connecteur
```java
com.clog.workey.connectors.ApiRestConnector
```
## Paramètres
### En entrée
* champ **obligatoire** contenant la configuration au format `JSON`. En fonction du type de requête, la configuration peut prendre différentes formes, elles sont détaillées plus bas dans ce document.
Exemple de configuration :
```json
{
"url":"https://my.company.com:8080/api/person/12",
"method": "GET"
}
```
### En sortie
* champ **obligatoire** contenant la réponse textuelle.
Exemple de texte `JSON` stocké dans le champ de sortie :
```json
{
"id": 12,
"firstname": "John",
"lastname": "Doe",
"age": 33
}
```
Un peu plus bas dans ce document, nous verrons comment récupérer directement les valeurs contenues dans le JSON et les mettre dans des champs du formulaire.
## Utilisation
Les requêtes vers les services web `REST` s'appuient sur le protocole `HTTP`. Une requête est une commande envoyée à un serveur via une `URL` et une méthode `HTTP`. Ce connecteur supporte 4 méthodes :
* la méthode `GET` permet de récupérer une resource du serveur sans effectuer de modification.
* la méthode `POST` permet d'envoyer des données en vue d'ajouter une ressource.
* la méthode `PUT` permet d'envoyer des données en vue de modifier une ressource.
* la méthode `DELETE` permet de supprimer une ressource.
### Récupérer d'une ressource via la méthode GET
Lorsqu'une requête est effectuée en vue de récupérer des données, il faut lui spécifier, dans la configuration, le type de donnée attendu à l'aide de la propriété `expectedType`. Elle peut prendre quatre valeurs : `JSON`, `TEXT`, `BINARY` et `MULTIPART_FORM_DATA`.
Exemple de type attendu dans la configuration :
```json
{
"url":"https://my.company.com:8080/api/service/status",
"method": "GET",
"expectedType": "TEXT"
}
```
*Pour information, le statut retourné par la requête ci-dessus est donc du texte (par ex : `service is up`).*
Par défaut, si cette information n'est pas renseignée, l'`expectedType` est positionné à `JSON`. Nous partons donc du principe que le type par défaut attendu est du `JSON` (voir [Récupération de données au format JSON](#récupération-de-données-au-format-json)).
Si l'`expectedType` est positionné à `BINARY`, c'est que le type de donnée attendu est un fichier. Ce dernier sera donc stocké dans un composant `Pièce Jointe` (voir [récupération d'un fichier](#récupération-dun-fichier)).
Si l'`expectedType` est positionné à `MULTIPART_FORM_DATA`, c'est que le type de donnée attendu est une composition de fichiers et de formulaire, comme l'envoie d'un formulaire HTML depuis un navigateur. Les fichiers seront stockés dans un composant `Pièce Jointe` (voir [récupération d'une réponse de plusieurs fichiers](#récupération-dune-réponse-de-plusieurs-fichiers)).
### Envoi de donnée via la méthode la méthode POST ou PUT
Lorsqu'une requête est effectuée en vue de créer ou de modifier une ressource, il est nécessaire de pouvoir envoyer des données.
ApiRestConnector permet d'envoyer :
* une saisie de formulaire ([envoi de données en mode formulaire](#envoi-de-données-en-mode-formulaire))
* du `JSON` ([Envoi de JSON](#envoi-de-json))
* un binaire (fichier) ([Envoi d'un fichier](#envoi-dun-fichier))
* plusieurs fichiers et des données de formulaire ([Envoi de plusieurs fichiers](#envoi-de-plusieurs-fichiers))
### Suppression d'une ressource via la méthode DELETE
Pour supprimer une ressource, il faut donc envoyer une requête avec les informations de la ressource à supprimer. Pour plus d'information voir l'[exemple de suppression](#suppression-dune-ressource).
## Exemples
### Récupération de données au format JSON
Lors d'une réception de donnée au format `JSON`, il est possible, en plus de les recevoir dans le champ de sortie, de les ventiler dans les champs du formulaire.
Pour ce faire, il faut définir cela dans la configuration.
Exemple de configuration :
```json
{
"url":"http://localhost:8080/api/person/12",
"method": "GET",
"expectedType":"JSON",
"jsonMappings": {
"Prenom": "$.firstname",
"Nom": "$.lastname",
"Age": "$.age",
"Hobbies": "$.hobbies[*]",
"Ville": "$.address.city"
}
}
```
Exemple de réponse JSON à la requête ci-dessus :
```json
{
"firstname": "Roger",
"lastname": "Rabbit",
"age": 22,
"hobbies": ["candy", "cinema", "soda"],
"address": {
"street": "500 S Joe Vista St",
"city": "Los Angeles"
}
}
```
Dans le `JSON` de la configuration, on peut apercevoir la propriété `jsonMappings` qui définit la ventilation. C'est un tableau de `clé` / `valeur` où la clé est le nom interne du champ dans le formulaire et où la valeur est le chemin vers la donnée dans le JSON réceptionné à l'exécution de la requête. La syntaxe des chemins se trouve [ici](#syntaxe-du-jsonpath).
Dans notre cas, le champ :
* **Prenom** va contenir la valeur `Roger`.
* **Nom** va contenir la valeur `Rabbit`.
* **Age** va contenir la valeur `22`.
* **Hobbies** va contenir la valeur `candy;cinema;soda` et doit être défini comme multivalué.
* **Ville** va contenir la valeur `Los Angeles`.
⚠️ Bien-sûr, il faut s'assurer que les champs sont bien présents et en écriture dans le formulaire pour le bon déroulement de la ventilation.
En plus de ces champs, il ne faut pas oublier que le champ de sortie contiendra la réponse complète au format texte `JSON`.
### Récupération de données au format texte
Lors d'une réception de donnée au format texte, le contenu de la réponse est tout simplement mis dans le champ de sortie. Bien-sûr la propriété `expectedType` doit être valorisée à `TEXT`.
Exemple de configuration pour récupérer les notes de la personne #45 :
```json
{
"url":"http://localhost:8080/api/person/45/notes",
"method": "GET",
"expectedType":"TEXT"
}
```
Exemple de réponse TEXT à la requête ci-dessus :
```
Il n'y a personne qui aime la douleur en soi, qui la recherche et la veut, simplement parce que c'est de la douleur...
```
### Récupération d'un fichier
Lors de la récupération d'un binaire (fichier), il faut spécifier le type de donnée attendu en positionnant la propriété `expectedType` à `BINARY`, comme dans l'exemple ci-dessous.
```json
{
"url": "https://integration.efalia.cloud:1202/api/documents/14ccebec-e6a9-4e1a-848a-0a491a265e2c/binaire",
"method": "GET",
"expectedType": "BINARY",
"retrievedBinary": {
"designerName": "zeDoc",
"filename": "doc.pdf"
}
}
```
On peut apercevoir une nouvelle propriété `retrievedBinary` qui va indiquer dans quel composant `Pièce Jointe` le fichier va être déposé. Cette propriété se compose d'un objet `JSON` contenant deux autres propriétés :
* `designerName` : le nom interne du composant `Pièce Jointe` à utiliser pour y stocker le fichier.
* `filename` : le nom du fichier à utiliser lors du stockage du fichier.
⚠️️La propriété `filename` peut ne pas être spécifiée si le serveur distant renvoie bien le nom du fichier dans sa réponse. Dans le cas contraire, il faut indiquer le nom de fichier à utiliser pour ne pas avoir d'erreur.
⚠️ Le type de fichier (pdf, word, txt ou autre...) est détecté à la réception du flux de données du service distant. Si le type n'est pas défini par le serveur (`application/octet-stream`), alors l'extension du nom de fichier `filename` est utilisée pour essayer de le déterminer.
⚠️ Le contenu récupéré peut être soumis au [contrôle des types de fichiers autorisés](#types-de-fichiers-autorisés).
### Récupération d'une réponse de plusieurs fichiers
Ce type de réponse se compose souvent d'une partie donnée de formulaire et d'un ou plusieurs fichiers à téléverser. C'est comme si un utilisateur avait saisi ces informations depuis un formulaire dans un navigateur. Pour utiliser ce type de réponse, il faut alors valoriser la propriété `expectedType` à `MULTIPART_FORM_DATA`, comme dans l'exemple ci-dessous.
```json
{
"url": "http://localhost:8000/multipart-response",
"method": "GET",
"expectedType": "MULTIPART_FORM_DATA",
"retrievedMultipart": {
"filePartNames": {
"file1": {
"designerName": "Facture",
"filename": "facture.pdf"
},
"annexe[]": {
"designerName": "Annexes"
}
},
"fieldPartNames": {
"lastname": "Nom",
"firstname":"Prenom"
}
}
}
```
On peut apercevoir une propriété `retrievedMultipart` dédiée à ce type de réponse. Elle se compose d'un object `JSON` contenant 2 propriétés :
* `filePartNames`: cette propriété regroupe les noms des fichiers attendus dans la réponse et en regard les noms internes des composants `Pièce Jointe` qui vont contenir ces fichiers.
* `fieldPartNames`: cette propriété regroupe les noms des champs de formulaires attendus dans la réponse et en regard les noms internes des champs de Process qui vont accueillir les valeurs des champs.
⚠️ Si le serveur distant renvoie une réponse contenant un champ fichier multiple (par ex : `file[]`), le nom de fichier de chaque fichier doit être absolument déduit des informations renvoyées pour ne pas avoir d'erreur.
⚠️ Si la propriété `filename` dans `filePartNames` est spécifiée, le nom fichier déduit des informations envoyées pas le serveur distant est ignoré.
⚠️ Les contenus récupérés peuvent être soumis au [contrôle des types de fichiers autorisés](#types-de-fichiers-autorisés).
### Envoi de données en mode formulaire
Lors d'un envoi de données en mode formulaire, il est nécessaire de positionner la propriété `contentType` à `FORM_DATA`, comme dans l'exemple ci-dessous.
```json
{
"url": "http://localhost:8000/post-form/",
"method": "POST",
"contentType": "FORM_DATA",
"formData": {
"firstname": "val1",
"lastname": "val2"
},
"expectedType": "JSON",
"jsonMappings": {
"Sujet_du_doc": "$.message"
}
}
```
Pour composer le formulaire, il est nécessaire de rajouter la propriété `formData` qui contient la liste des noms de variables à envoyer et en regard la valeur ou le nom interne du champ Process contenant la valeur à envoyer. Pour plus d'information, voir la [résolution des données envoyées en mode formulaire](#résolution-des-données-envoyées-en-mode-formulaire). Concernant le traitement de la réponse `JSON` dans cet exemple, voir [Récupération de données au format JSON](#récupération-de-données-au-format-json).
### Envoi de JSON
Pour envoyer un contenu `JSON`, il est nécessaire de positionner la propriété `contentType` à `JSON` et de valoriser la propriété `jsonBody` avec le nom interne d'un champ contenant le `JSON`, comme dans l'exemple\
ci-dessous :
```json
{
"url": "http://localhost:8000/json-receiver",
"method": "POST",
"contentType": "JSON",
"jsonBody": "champJSON",
"expectedType": "JSON",
"jsonMappings": {
"response": "$.message"
}
}
```
Il s'avère que le champ contenant le `JSON` indiqué par la propriété `jsonBody` et soumis à la composition à partir des données (plus d'infos [ici](#résolution-du-json-envoyé)). Concernant le traitement de la réponse `JSON` dans cet exemple, voir [Récupération de données au format JSON](#récupération-de-données-au-format-json).
Le champ indiqué par la propriété `jsonBody` contient le texte `JSON` à transmettre au service WEB, ce dernier peut contenir des parties variables :
```json
{
"id": "{Person_ID_de_la_partie_variables}",
"lastname": "{nom_interne_du_champ_Nom}",
"firstname": "{nom_interne_du_champ_Prenom}",
"city": "Paris",
"sexe": "M",
"active": true
}
```
### Envoi d'un fichier
Pour envoyer un fichier, il est nécessaire de positionner la propriété `contentType` à `BINARY` et de valoriser la propriété `sentBinary` avec le nom interne d'un champ `Pièce Jointe`, comme dans l'exemple ci-dessous :
```json
{
"url": "http://localhost:8000/upload",
"method": "POST",
"contentType": "BINARY",
"sentBinary": "champPJ",
"expectedType": "JSON",
"jsonMappings": {
"response": "$.message"
}
}
```
Le corps de la requête sera constitué du binaire. Concernant le traitement de la réponse `JSON` dans cet exemple, voir [Récupération de données au format JSON](#récupération-de-données-au-format-json).
### Envoi de plusieurs fichiers
Pour envoyer plusieurs fichiers, il faut positionner la propriété `contentType` à `MULTIPART_FORM_DATA`, comme dans l'exemple ci-dessous :
```json
{
"url": "http://localhost:8000/upload/",
"method": "POST",
"contentType": "MULTIPART_FORM_DATA",
"sentMultipart": {
"filePartNames": {
"file": "Principal",
"annexe[]": "Annexes"
},
"fieldPartNames": {
"firstname": "Prenom",
"lastname": "Nom",
"age": 33
}
},
"expectedType": "JSON",
"jsonMappings": {
"response": "$.message"
}
}
```
On peut apercevoir la propriété `sentMultipart` qui contient les données correspondant à la saisie d'un formulaire de navigateur (une partie *fichiers* et une partie *champs*). Cette propriété contient 2 propriétés :
* `filePartNames`: contient les noms de champs à utiliser dans l'envoi, et en regard, les noms internes des composants `Pièce jointe` d'où sont issus les fichiers
* `fieldPartNames`: contient les noms de champs à utiliser dans l'envoi, et en regard, les valeurs ou les noms internes des champs du formulaire Process d'où sont issues les valeurs
Concernant le traitement de la réponse `JSON` dans cet exemple, voir [Récupération de données au format JSON](#récupération-de-données-au-format-json).
⚠️ Si un composant `Pièce Jointe` contient plus d'un fichier et que le nom du champ spécifié dans la configuration est suffixé par `[]`, tous les fichiers du composant `Pièce Jointe` sont envoyés. Si le nom du champ n'est pas suffixé par `[]`, seul le premier fichier listé est envoyé.
### Suppression d'une ressource
Généralement, c'est dans l'url qu'il y a les informations pour identifier et supprimer la ressource.
Exemple de configuration :
```json
{
"url": "https://mon.serveur.com/api/person/34",
"method": "DELETE",
"expectedType": "JSON",
"jsonMappings": {
"response": "$.message"
}
}
```
Dans cet exemple, on peut apercevoir que dans la propriété `url`, il y a deux portions qui identifient ce que le serveur doit effectuer : supprimer la personne (`/person`) n°34 (`/34`).
Concernant le traitement de la réponse `JSON` dans cet exemple, voir [Récupération de données au format JSON](#récupération-de-données-au-format-json).
## Notes
### Utilisation de variables
Pour chaque configuration d'appel d'une requête, il est possible de définir des variables qui seront utilisées pour composer l'URL et/ou les données envoyées.
Exemple de configuration avec variables :
```json
{
"variables": {
"personId": "88fc3726-05ee-4167-92cd-7a477643f291",
"trucmuche": "foobar",
"nbMax": 99
},
"method": "GET",
"url": "http://localhost:1234/person/{personId}/notes",
"expectedType": "JSON"
}
```
Dans cet exemple, au niveau de la propriété `variables`, la variable `personId` est définie avec une valeur : un uuid. Elle est ensuite utilisée dans la composition de l'`url` (`{personId}`). C'est donc l'uuid qui est utilisé à la place de `{personId}`. Au moment de l'appel, l'url utilisée est `http://localhost:1234/person/88fc3726-05ee-4167-92cd-7a477643f291/notes`. L'exemple n'est pas très élaboré, mais a le mérite de montrer juste le mécanisme de substitution.
Cela peut devenir très intéressant avec les variables systèmes du fichier de configuration `catalina.properties` de Tomcat. En effet, il est possible de passer en valeur d'une variable, le nom d'une variable système.
Dans la configuration ci-dessous :
```json
{
"variables": {
"apiKey": "com.clog.workey.weather.api.key"
}
}
```
Au moment de l'appel, la valeur de `com.clog.workey.weather.api.key` du fichier `cataline.properties` devient la valeur de la variable `apiKey`. La valeur de `apiKey` peut ensuite être utilisée dans la [résolution de la configuration](#résolution-de-la-configuration). Pour les variables de la partie `variables`, il n'y a que ce mécanisme de substitution.
⚠️ Dans les cas d'utilisation d'information de connexion à des services web distants, il est recommandé d'utiliser ce système. Cela permet de ne jamais persister ces informations dans la modélisation au moment de la conception ou dans le formulaire au moment du runtime. Pour des raisons de sécurité, ces informations ne sont pas inscrites dans les fichiers de journalisation.
### Utilisations d'en-têtes HTTP
Pour chaque configuration d'appel d'une requête, il est possible de définir des en-têtes HTTP. Chaque en-tête HTTP est un couple clé/valeur qui est envoyé au serveur de l'api REST.
Exemples de configuration avec des en-têtes :
Avec une clé d'api :
```json
{
"headers": {
"x-api-key": "123456"
}
}
```
Avec une authentification basique :
```json
{
"headers": {
"Authorization": "Basic ZAZEH3456x"
}
}
```
Bien-sûr, pour des raisons de sécurité, il n'est vraiment pas recommandé de metter en clair ces informations de connexion. Il faut mieux utiliser le système de [variables](#utilisation-de-variables).
Lors de l'envoi de donnée, pour chaque nom d'en-tête HTTP, sa valeur est soumise à la [politique de substitution n°2](#politique-de-substitution-n2).
### Utilisation des queryStrings
Il est possible de rajouter des paramètres à l'URL en utilisant la propriété de configuration `queryStrings` comme ci-dessous :
```json
{
"queryStrings": {
"search": "foo*",
"nbMaxItems": 1000
},
"url": "https://ma.recherche.com/api"
}
```
Lors de l'appel, les deux "queryStrings" `search` et `nbMaxItems` seront encodées et rajoutées à l'url pour donner l'adresse suivante : `https://ma.recherche.com/api?search=foo*&nbMaxItem=1000`. Bien-sûr, il est possible d'utiliser la substitution de valeurs pour rendre paramétrable les queryStrings.
Lors de l'envoi de donnée, pour chaque nom de queryString, sa valeur est soumise à la [politique de substitution n°2](#politique-de-substitution-n2).
### Résolution de la configuration
Le seul paramètre en entrée du connecteur est la configuration sous forme de `JSON`, elle définit ce que doit effectuer le connecteur en terme d'appel au service web. Ce `JSON` est constitué de différentes parties listées dans ce document. Lors de l'exécution de la requête, le connecteur dispose de valeurs à sa disposition pouvant être utilisées dans la résolution des différentes parties de la configuration par substitution (*variables* et *champs de formulaires*). Il faut retenir que toutes les résolutions sont dépendantes de la résolution des variables, cette dernière est donc réalisée en premier.
#### Résolution de l'URL
Dans chaque configuration, il faut définir la propriété `url` comme suit :
```json
{
"url": "https://my.company.com/api/foo"
}
```
Il est aussi possible d'y définir des parties variables avec la notation `{partie_variable}` comme cela :
```json
{
"url": "https://my.company.com/api/person/{id}/nodes?limit={nbMaxItems}"
}
```
Au moment de l'appel, le connecteur parcourt l'url pour remplacer toutes les parties variables par de vraies valeurs. Pour ce faire, pour chaque partie `{partie_variable}`, il recherche une valeur ayant pour nom `partie_variable` à l'aide de la [politique de substitution n°1](#politique-de-substitution-n1).
Pour information, il est aussi possible d'ajouter des [queryStrings](#utilisation-des-querystrings), ce sont des paramètres supplémentaires d'url.
#### Résolution des en-têtes HTTP envoyés
Si vous utilisez les [en-têtes HTTP](#utilisations-den-têtes-http), il faut savoir qu'ils sont aussi soumis au système de résolution à l'aide de la [politique de substitution n°2](#politique-de-substitution-n2). C'est-à-dire que pour chaque en-tête de défini, la valeur en regard est utilisée pour rechercher une valeur.
#### Résolution du `JSON` envoyé
Après avoir récupéré le texte `JSON` du champ de formulaire indiqué par la propriété `jsonBody`, au moment de l'appel, le connecteur parcourt le `JSON` pour remplacer toutes les parties variables par de vraies valeurs. Pour ce faire, pour chaque partie `{partie_variable}`, il recherche une valeur ayant pour nom `partie_variable` à l'aide de la [politique de substitution n°1](#politique-de-substitution-n1).
#### Résolution des queryStrings envoyées
Si vous utilisez les [queryStrings](#utilisation-des-querystrings), il faut savoir qu'elles sont aussi soumises au système de résolution à l'aide de la [politique de substitution n°2](#politique-de-substitution-n2). C'est-à-dire que pour chaque queryString de définie, la valeur en regard est utilisée pour rechercher une valeur.
#### Résolution des données envoyées en mode formulaire
Lors de l'envoi de donnée en mode formulaire (propriété `formData`), pour chaque nom de donnée sa valeur est soumise à la [politique de substitution n°2](#politique-de-substitution-n2).
#### Politique de substitution n°1
Avec le nom de la valeur recherche, le connecteur effectue le traitement suivant :
1. il recherche dans les variables (propriété `variables` après résolution) une variable portant le nom de la valeur recherchée.
2. s'il trouve une variable, il utilise la valeur en regard.
3. s'il n'a rien trouvé dans les variables, il recherche dans le formulaire un champ ayant comme nom interne le nom de la valeur recherchée.
4. s'il trouve un champ, il utilise la valeur contenue par le champ.
5. s'il n'a rien trouvé dans le formulaire, il utilise le nom de la valeur tel quelle.
#### Politique de substitution n°2
Avec le nom de la valeur recherche, le connecteur effectue le traitement suivant :
1. si le nom de la valeur recherchée commence par le caractère `#`, c'est le nom lui-même qui est retenu comme valeur sans le premier caractère `#`. Cela permet d'éviter les points suivants qui pourraient répondre positivement et engendrer une valeur non voulue.
2. si le nom n'a pas de caractère d'échappement `#`, il recherche dans les variables (propriété `variables` après résolution) une variable portant le nom de la valeur recherchée.
3. s'il trouve une variable, il utilise la valeur en regard.
4. s'il n'a rien trouvé dans les variables, il recherche dans le formulaire un champ ayant comme nom interne le nom de la valeur recherchée.
5. s'il trouve un champ, il utilise la valeur contenue par le champ.
6. s'il n'a rien trouvé dans le formulaire, il utilise le nom de la valeur tel quelle.
### Syntaxe du JSON
Si vous désirez avoir plus d'informations sur le format `JSON`, c'est [ici](/produit/efalia-process/developpeurs/syntaxes-json-jsonpath.md).
### Syntaxe du JSONPath
Si vous désirez avoir plus d'informations sur la syntaxe du `JSONPath`, c'est [ici](/produit/efalia-process/developpeurs/syntaxes-json-jsonpath.md#syntaxe-du-jsonpath).
### Traitement d'une réponse par Groovy
Si vous rencontrez un cas où les différents types de traitement de réponse ne correspondent pas à vos besoins, il en existe encore un autre : le traitement par script `groovy`.
Ce dernier va conférer une grande liberté de traitement, car il s'effectue avec la création d'un fichier contenant le coding du script [groovy](https://groovy-lang.org) adéquate.
Exemple de configuration utilisant un script `groovy`
```json
{
"url": "https://mon.api.com/api/person/23",
"method": "GET",
"callbackScript": "myScript.groovy"
}
```
On peut apercevoir la propriété `callbackScript` qui identifie le nom d'un fichier `groovy` (⚠️ le nom du fichier est sensible à la casse). Ce dernier doit être placé dans le répertoire du serveur **Tomcat** : `$SERVER/workey-data/scripts`.
Exemple de script `groovy`, dans la configuration ci-dessus cela correspond au contenu du fichier `myScript.groovy`.
```groovy
import groovy.json.JsonSlurper
import java.time.OffsetDateTime
// Interprétation de la réponse JSON
JsonSlurper slurper = new JsonSlurper()
data = slurper.parse(response.toString().getBytes())
// Affichage des variables disponibles
println """Params: ${params}
Document: ${document.id}
API Response: ${data}
Result: ${result}
"""
// Remplissage des valeurs de retour, ici on imagine que
// le webservice a renvoyé une structure JSON de la
// forme suivante :
// { "firstname": "John", "lastname": "Doe", "birthday": "2003-03-16T08:53:44.123+02:00" }
OffsetDateTime ofsDate = OffsetDateTime.parse((String) data.birthday)
String[] returnObj = [ "M " + data.lastname, data.firstname, ofsDate.format("dd/MM/yyyy"), data.age ]
result = returnObj
```
On peut s'apercevoir que les valeurs de retour sont directement renvoyées par le script sous forme de tableau, une valeur par occurrence de tableau `returnObj`. Lors de la modélisation du connecteur, il faut alors bien penser à positionner les champs de retour. Le seul [paramètre de sortie](#en-sortie) par défaut du connecteur n'est plus du tout d'actualité avec l'utilisation des scripts `groovy`.
### Types de fichiers autorisés
Pour les requêtes qui renvoient des fichiers, au moment de l'ajout des contenus dans Process, le contrôle des *Type de fichiers autorisés au téléversement* est sollicité. Ce contrôle peut être configuré dans l'administration de Process :
### Débogage
Pour visualiser la communication du connecteur dans les fichiers de journalisation, il faut positionner la variable systéme `com.clog.workey.connectors.ApiRestConnector.debug` à `true` dans le fichier de configuration `catalina.properties` de **Tomcat**.
---
# 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/produit/efalia-process/developpeurs/connecteur-api-rest.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.
