Obtenir la structure du modèle de données

Un modèle de données va typiquement être constitué de plusieurs tables de données personnalisées qui gravitent autour d'une table de profils.

Vous pouvez obtenir la liste de toutes les tables personnalisées enregistrées sur une entité grâce à l'opération GET/entity/{e}/customTable

Cette méthode vous donnera les caractéristiques des tables personnalisées liées à une entité et non à une table de profils en particulier.

Elle vous donnera les informations suivantes pour chaque table :

• son identifiant technique auto-généré, qui peut être utilisé pour appeler et soumettre des données

• son nom technique, qui peut être utilisé pour appeler et soumettre des données

• son nom d'affichage, tel qu'il apparaît dans ACTITO

• sa catégorie : lecture uniquement ou lecture et modification

• les capacités de la table (capabilities) : Pour davantage d'information à ce sujet, voir "Comprendre les capacités des tables"

Obtenir la structure d'une table

ACTITO vous donne la possibilité de définir le contenu de vos tables personnalisées durant leur mise en place, afin de s'adapter aux besoins spécifiques de votre activité.

Une fois créée dans ACTITO, la table personnalisée sera caractérisée par :

• Un nom "t", par exemple, "DemoDocTickets"

• Une entité "e", qui correspond aux droits d'accès. Dans cet exemple : "actito"

Vous pouvez utiliser l'opération GET/entity/{e}/customTable pour obtenir la structure de cette table.

Ceci vous permettra de comprendre comment la structure de votre table se traduit dans l'API. Grâce à cette information, vous pourrez plus facilement programmer des méthodes POST ou PUT pour créer un import de données en utilisant correctement tous les éléments qui constituent votre table personnalisée.

Pour ce faire, entrez le nom de l'entité et de la table comme paramètres.

Exemple de réponse à cette requête : (Téléchargez cet exemple)

Cette réponse se caractérise par :

• Des informations sur le type de tables concerné

• La liste de attributs et de leurs caractéristiques :

  • "fieldName" est le nom technique du champ, qui devra être utilisé pour pousser des données

  • "type" : Le type de champ attendu

  • "unique" : Si l'attribut est unique ou pas

  • "required" : Si l'attribut est obligatoire ou pas

  • "description" : La description de l'attribut

• Les informations techniques liées à la table :

  • "primaryKey" : il s'agit de l'identifiant technique de la table, qui correspondra toujours à un attribut technique appelé "id" et auto-généré. Cet attribut technique permet d'identifier chaque enregistrement de la table. Ce champ ne devra jamais être spécifié dans vos appels pour pousser des données.

  • "businessKey" : il s'agit de la clé business de la table. Elle servira d'identifiant clé pour identifier chaque enregistrement lors de vos appels pour pousser des données. Elle devra donc toujours y être mentionnée.

  • "creationMoment" et "updateMoment" : il s'agit du moment de création et de mise à jour de la table. Ce champ technique ne devra jamais être spécifié dans vos appels.

Obtenir les informations d'un enregistrement spécifique

Il peut être utile d'obtenir des informations à propos des enregistrements qui sont déjà présents dans votre table. Cela vous donnera un exemple concret des informations qui sont attendues lors des appels de création de données, surtout en ce qui concerne les caractéristiques des attributs qui la composent.

Vous pouvez récupérer les détails concernant un enregistrement via l'opération GET/entity/{e}/customTable/{t}/record/{r)

Les paramètres à renseigner sont les suivants :

• l'entité à laquelle appartient la table personnalisée

• la table personnalisée qui contient l'enregistrement

• l'enregistrement à récupérer : il faut pour cela utiliser sa clé business, telle que vous avez pu l'identifier en obtenant la structure de la table. L'identifiant technique automatiquement généré ne peut pas être utilisé ici.

Exemple de résultat pour cette requête : (Téléchargez cet exemple)

Veuillez noter que certains attributs techniques sont automatiquement renseignés dans la réponse. Ces attributs ne sont pas modifiables. Il s'agit de :

• "id" : l'identifiant technique auto-généré

• "creationMoment" : la date et l'heure de création

• "updateMoment" : la date et l'heure de la dernière mise à jour

Obtenir les informations d'enregistrements sur base d'une recherche

L'opération GET/entity/{e}/customTable/{t}/record vous permettra d'obtenir les informations d'enregistrements en ajoutant des paramètres de requête spécifiques. Par exemple, obtenir tous les tickets d'un client en particulier.

Il nécessaire de renseigner l'entité et la table personnalisée concernée. Vous pouvez ensuite spécifier les paramètres de requête suivants :

• "searchField" : il s'agit du nom technique du champ sur lequel la recherche doit être basée. Ce champ doit être indexé.

• "searchValue" : renseignez la valeur pour le champ de recherche pour laquelle vous voulez obtenir tous les enregistrements. Il s'agit d'un critère de stricte égalité.

• "sortedField" : renseignez le champ utilisé pour déterminer l'ordre dans lequel tous les enregistrements vont être présentés. Par défaut, il s'agit de la date de création. Ce champ doit être indexé.

• "ascending" : choisissez si les enregistrements doivent être présentés en ordre croissant (true) ou décroissant (false).

• "number" : choisissez le nombre d'enregistrements à afficher (la valeur maximum et par défaut est de 200).

Exemple de réponse à une requête basée sur une recherche par numéro de client : GET/entity/{e}/customTable/{t}/record.docx

Créer ou mettre à jour un seul enregistrement

Les appels un par un sont à privilégier quand les données sont utilisées pour déclencher un processus de travail ou qu'elles doivent être synchronisées de façon immédiate vers une base de données.

Il est possible de créer ou de mettre à jour un enregistrement d'une table personnalisée grâce à l'opération POST/entity{e}/customTable{t}/record

Cette méthode implique l’utilisation de code JSON pour saisir les données correspondant à l'enregistrement concerné. Il est donc conseillé de s'être familiarisé avec la structure de la base de données auparavant, comme expliqué au début de cette page.

Les paramètres à renseigner sont les suivants :

• l'entité à laquelle la table appartient

• le nom de la table personnalisée à laquelle l'enregistrement doit être ajouté, ou celle où se trouve l'enregistrement qui doit être mis à jour

• "allowUpdate" : Ceci permet de choisir si vous voulez mettre à jour un enregistrement s'il existe déjà. En effet, POST est avant tout une méthode de création, mais elle peut être utilisée pour les mises à jour

• "record" : Les propriétés de l'enregistrement concerné, sous forme de code JSON à insérer. Le schéma sur la droite vous donne un modèle de la structure de ce code. Il s'agit d'un tableau de valeurs reprenant les paires de noms techniques des propriétés ("name") et de la valeur qu'elles doivent prendre ("value")

  

Exemple de requête incluant le code JSON à pousser dans le paramètre "record" : POST/entity/{e}customTable{t}record.docx

La réponse sera tout simplement la clé business ("businessKey") de l'enregistrement que vous venez de créer ou de mettre à jour.

Créer ou mettre à jour des enregistrements en masse

L'alimentation en masse des tables est possible à partir des APIs d'ACTITO. Celles-ci permettent un import de masse basés sur des fichiers ZIP contenant les données de tables. Le fonctionnement des imports de données en masse dans les tables personnalisées est exactement le même pour les imports en masse de profils.

Pour davantage d'information concernant le format attendu pour le fichier, le résultat de l'import ou les erreurs éventuelles que vous pouvez rencontrer, nous vous invitons à vous référer à la page consacrée à l'import en masse de profils.

Les APIs publiques d'ACTITO permettent l'import en masse d'enregistrement de tables personnalisées via l'opération POST/entity/{e}/customTable{t}/import

Cet appel permet de pousser un fichier ZIP contenant un CSV reprenant les données de table à charger.

Les paramètres suivants doivent être renseignés :

• le nom de l'entité sur laquelle se trouve la table de profils

• le nom de la table personnalisée dans laquelle vous voulez importer des données

• le format du fichier CSV. 3 formats de fichier CSV sont supportés :

  • COMMA_SEPARATED_VALUES (séparateur : "," et retour à la ligne)

  • TAB_SEPARATED_VALUES (séparateur : indentation et retour à la ligne)

  • SEMI_COLON_SEPARATED_VALUES (séparateur : "; " et retour à la ligne)

• "charset" : l'encodage du fichier CSV. Il s'agit d'UTF-8 par défaut.

• le mode d'import. Il y a 3 valeurs possibles :

  • CREATE_ONLY : ne charge les données que si elles ne correspondent à aucune ligne dans la table. En d’autres termes, la valeur de la ligne pour la headerKeyColumn indiquée ne doit pas exister en base.

  • UPDATE_ONLY : ne charge les données que si elles correspondent à un profil existant dans la table. Il s'agit uniquement d'une mise à jour de profils existants.

  • CREATE_UPDATE : Crée un profil si aucun ne correspond en base et le met à jour si le profil existe déjà.

• "headerKeyColumn" : nom de la colonne du fichier CSV à utiliser comme clé unique d’identification de la donnée. Cela doit correspondre à un champ unique de la table dans laquelle les données sont chargées.

Après avoir lancé votre import, un code 200 indiquera le succès de l'appel webservice. Le corps de réponse vous donnera alors l'identifiant technique de cet import.

Cet identifiant technique pourra être utilisé pour obtenir le statut de l'import et d'identifier les éventuelles erreurs, comme expliqué sur la page consacrée aux imports en masse de profils.