Créer ou mettre à jour un seul profil

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.

De plus, elles permettent de se concentrer sur certains éléments précis de la fiche de profil, comme les abonnements ou les segmentations.

Créer ou mettre à jour un seul profil

Il est possible de créer ou de mettre à jour un profil grâce à l'opération POST/entity{e}/table{t}/profile

Cette méthode implique l’utilisation de code JSON pour saisir les données appartenant au profil concerné. Il est donc conseillé de s'être familiarisé avec la structure de la base de données auparavant, comme expliqué au point "Obtenir la structure d'une table de profils" de la page générale sur les APIs de profils.

Les paramètres à renseigner sont les suivants :

  • L'entité à laquelle la table appartient

  • Le nom de la table de profil à laquelle le profil doit être ajouté, ou celle où se trouve le profil qui doit être mis à jour

  • "allowupdate" : Ce paramètre permet de choisir si vous voulez mettre à jour un profil 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

  • Les caractéristiques du profil concerné, sous forme de code JSON à insérer. Le schéma sur la droite de la documentation technique Swagger vous donne un modèle de la structure de ce code. Celui-ci est composé de 4 sections :

  • "attributes"

La valeur attendue est un tableau de valeur reprenant l'ensemble des informations concernant le profil à créer. Chaque élément se compose du nom de l'attribut et de la valeur à leur donner.

Chaque attribut "obligatoire" (tel que défini dans la structure de la table) devra obligatoirement se voir affecter une valeur. Ce n'est pas le cas pour un attribut "optionnel". Dans ce dernier cas, vous pouvez soit ne pas les mentionner dans votre appel, soit le pousser avec la valeur "null". Les attributs "techniques" ne doivent pas être mentionnés dans l'appel. En effet, ils ne peuvent pas être modifiés et seront générés automatiquement lors de la création.

  • "dataCollectionInformation"

Ces paramètres ne sont pas apparus dans la structure d'un profil que vous avez potentiellement obtenu grâce à une méthode GET. En effet, il s'agit d'informations relatives au RGPD destinées à être stockée au niveau de votre back office afin de pouvoir justifier le consentement marketing donné par un profil. Elles concernent : le moment de la collecte d'information ("date"), son origine ("source") et les informations techniques relatives au moyen de collecte ("way").

  • "subscriptions"

L'ensemble des abonnements est repris dans le tableau de valeur "subscriptions". Il convient ici de donner le nom de l'abonnement puis de renseigner dans le paramètre "subscribe" si le profil y est abonné (true) ou pas (false). Les abonnements absents de l'enregistrement ne seront pas pris en compte.

  • "segmentations"

L'ensemble des segmentations est repris dans le tableau de valeur "segmentations". Il convient ici de donner le nom de la segmentations puis, dans le paramètre "category", de renseigner le nom du segment s'il s'agit d'une segmentation exclusive, ou "Member" s'il s'agit d'une segmentation simple.

images/download/attachments/615292244/image2019-3-14_17-44-2.png


Exemple de requête incluant le code JSON à pousser dans le paramètre "profile" : (Téléchargez cet exemple)

POST/entity/{e}/table/{t}/profile
Curl call:
curl -X POST --header "Content-Type: application/json" --header "Accept: application/json" -d "{
\"attributes\": [{
\"name\": \"lastName\",
\"value\": \"Wayne\"
},
{
\"name\": \"firstName\",
\"value\": \"John\"
},
{
\"name\": \"birthDate\",
\"value\": \"26/05/1907\"
},
{
\"name\": \"sex\",
\"value\": \"M\"
},
{
\"name\": \"motherLanguage\",
\"value\": \"EN\"
},
{
\"name\": \"emailAddress\",
\"value\": \"john.wayne@actito.com\"
},
{
\"name\": \"addressLocality\",
\"value\": \"Los Angeles\"
},
{
\"name\": \"addressCountry\",
\"value\": \"US\"
},
{
\"name\": \"gsmNumber\",
\"value\": \"1223344556\"
},
{
\"name\": \"customerId\",
\"value\": 34567
},
{
\"name\": \"nbChildren\",
\"value\": 2
},
{
\"name\": \"rep\",
\"value\": \"null\"
}
],
\"dataCollectionInformation\": {
\"date\": \"15/03/2019\",
\"source\": \"TEST\",
\"way\": \"api profile 1\"
},
 
\"subscriptions\": [{
\"name\": \"Newsletter\",
\"subscribe\": \"true\"
},
{
\"name\": \"Offer\",
\"subscribe\": \"true\"
}
],
\"segmentations\": [{
\"belongs\": \"true\",
\"segmentation\": {
\"name\": \"TypeClient\",
\"category\": \"Gold\"
}
},
{
\"belongs\": \"true\",
\"segmentation\": {
\"name\": \"Active\",
\"category\": \"Member\"
}
}
]
}" https://test.actito.be/ActitoWebServices/ws/v4/entity/actito/table/Demodoc/profile?allowUpdate=true
 
 
Response body:
{
"profileId": 1147690
}

La réponse sera tout simplement l’identifiant technique (profileId) créé automatiquement par ACTITO lors de la création d'un nouveau profil. Si vous avez utilisé cette opération pour une mise à jour d'un profil existant, il s'agira de l'identifiant du profil mis à jour.

Comportement dans le cas de plusieurs clés uniques dans la base de données

Dans le cas où cette opération est utilisée pour la mise à jour d'un profil, et que le paramètre "allowUpdate" a donc été défini comme vrai, le lien avec le profil existant sera fait sur base d'un attribut clé. Dans le cas où l'objet JSON contient plusieurs clés (par exemple, un profileId et une adresse e-mail), les règles suivantes seront appliquées :

  1. Pour chaque valeur d'un attribut unique contenu dans le fichier, le programme va chercher le profil correspondant

  2. Si toutes les valeurs correspondent au même profil, le profil est mis à jour

  3. Si deux ou plus de valeurs correspondent à des profils différents, un conflit est généré et la mise à jour n'est pas appliquée

  4. Si aucun profil correspondant n'est trouvé, le système en créera un nouveau

Mettre à jour un seul profil

Pour mettre à jour un profil existant, il est possible d'utiliser l'opération précédente en définissant bien le paramètre "allowUpdate" comme vrai.

Si vous désirez mettre à jour un profil sans possibilité de créer un nouveau profil s'il n'existe pas (et donc éviter le risque de créer des doublons en cas d'erreur dans l'identifiant), vous pouvez utiliser l'opération PUT/entity/{e}/table{t}/profile{p}

Dans ce cas le corps du JSON pourra uniquement contenir les informations qui doivent être mises à jour. Si certains éléments ne sont pas du tout affectés, ils peuvent ne pas figurer dans la requête. Par exemple, si vous voulez mettre à jour certains attributs, sans toucher aux abonnements et aux segmentations, il convient de laisser les sections "subscriptions" et "segmentations" vides ou de pas les mentionner du tout.

La réponse correspondra à l'identifiant technique (profileId) du profil qui a été mis à jour.

Exemple de requête : (Téléchargez cet exemple)

PUT/entity/{e}/table/{t}/profile/{p}
Curl call:
curl -X PUT --header "Content-Type: application/json" --header "Accept: application/json" -d "{
\"attributes\": [{
\"name\": \"addressLocality\",
\"value\": \"Hollywood\"
},
{
\"name\": \"rep\",
\"value\": \"1\"
}
]
}" "https://test.actito.be/ActitoWebServices/ws/v4/entity/actito/table/demodoc/profile/1147690"
 
Response body:
{
"profileId": 1147690
}

Inscrire ou désinscrire un profil d'un abonnement

Pour modifier les préférences d'abonnements d'un profil, il est possible d'utiliser les deux opérations référencées ci-dessus. Dans ce cas, il convient de modifier le paramètre "subscribe" de chaque abonnement, selon que le profil doit être abonné (true) ou pas (false).

Cependant, des opérations sont mises à votre disposition pour vous concentrer spécifiquement sur les inscriptions et les désinscriptions à un abonnement.

Il est possible d'inscrire un profil à un abonnement via l'opération POST/entity/{e}/table{t}/profile/{p}/subscription/{s}

Il est possible de désinscrire un profil à un abonnement via l'opération DELETE/entity/{e}/table{t}/profile/{p}/subscription/{s}

Dans les deux cas, les paramètres à renseigner sont exactement les mêmes :

  • L'entité à laquelle la table de profils appartient

  • La table de profils dans laquelle figure le profil

  • Le profil dont l'abonnement doit être modifié ("profileId" ou couple "attributClé=Valeur")

  • Le nom de l'abonnement qui doit être ajouté ou retiré au profil. Il s'agit bien du nom que vous avez choisi et pas de l'identifiant technique

  • Les informations de collectes de données ("source", "way" et "date"). Ces informations ne sont pas obligatoires mais constituent une bonne pratique dans le cadre du RGPD.

images/download/attachments/615292244/image2019-3-15_13-40-58.png

Astuce

Ces opérations ne produisent aucun corps de réponse.

Ajouter ou retirer un profil d'une segmentation

Pour modifier les segmentations auxquelles fait partie un profil, il est possible d'utiliser les deux opérations générales de création et de mise à jour référencées ci-dessus.

Dans ce cas, il convient de modifier le paramètre "belongs" de chaque segmentation, selon que le profil doit en faire partie (true) ou pas (false).

S'il s'agit d'une segmentation exclusive, qui est donc composée de sous-catégories de segments, il est possible que le profil ne doit pas être retiré complètement de la segmentation mais qu'il doive passer dans un autre segment. Il faut alors modifier le paramètre "category" avec le nom du segment dont fait à présent partie le profil. D'ailleurs, dans le cas d'une segmentation exclusive avec partition complète, c'est à dire que chaque profil doit obligatoirement appartenir à un segment, il ne sera pas possible de retirer un profil de la segmentation mais uniquement de changer le segment auquel il appartient.

Néanmoins, des opérations sont mises à votre disposition spécifiquement pour ajouter, mettre à jour et supprimer l'appartenance d'un profil à un segment.

Ajouter ou mettre à jour la segmentation d'un profil

L'opération PUT/entity{e}/table{t}/profile{p}/segmentation{s} vous permet d'ajouter un profil à une segmentation, ou, dans le cas d'une segmentation exclusive, de modifier le segment auquel il appartient.

Les paramètres à renseigner sont :

  • L'entité à laquelle la table de profils appartient

  • La table de profils dans laquelle figure le profil

  • Le profil dont la segmentation doit être modifiée ("profileId" ou couple "attributClé=Valeur")

  • Le nom de la segmentation. La valeur attendue pour ce paramètre dépend selon qu'il s'agisse d'une segmentation simple ou d'une segmentation exclusive :

  • segmentation simple

La valeur attendue est le nom de la segmentation

  • segmentation exclusive

La valeur attendue devra prendre la forme "segmentName;category=categoryName", où "segmentName" est le nom de la segmentation générale et où "categoryName" réfèrent aux sous-catégories de segments qui la composent.

Par exemple, dans le cadre de la segmentation exclusive "TypeClient" comprenant les segments "Gold", "Silver" et "Bronze", le paramètre devra être "TypeClient;category=Gold" pour faire rentrer le profil dans le segment "Gold".

images/download/attachments/615292244/image2019-3-15_15-11-31.png

Astuce

Cette opération ne produit aucun corps de réponse.

Retirer un profil d'une segmentation

L'opération DELETE/entity{e}/table{t}/profile{p}/segmentation{s} vous permet de retirer le profil d'une segmentation.

Les paramètres à renseigner sont :

  • l'entité à laquelle la table de profils appartient

  • la table de profils dans laquelle figure le profil

  • le profil dont la segmentation doit être modifiée ("profileId" ou couple "attributClé=Valeur")

  • le nom de la segmentation.

Dans ce cas, aucune différence n'est faite entre les segmentations simples et exclusives. Le profil est tout simplement retiré de la segmentation.

Il n'est pas possible de retirer le profil d'un segment pour le mettre dans un autre segment de la même segmentation. Pour un tel objectif, il conviendrait d'utiliser la méthode PUT expliquée précédemment.

Dans le cas d'une segmentation exclusive avec partition complète, c'est à dire que chaque profil doit obligatoirement appartenir à un segment, il ne sera pas possible de retirer un profil de la segmentation mais uniquement de changer le segment auquel il appartient. Une tentative de retirer un profil d'une segmentation exclusive avec partition complète affichera une erreur 401.

images/download/attachments/615292244/image2019-3-15_15-29-43.png

Astuce

Cette opération ne produit aucun corps de réponse.

Supprimer un profil

Les APIs ACTITO disposent d'une opération permettant la suppression d'un profil. Veuillez cependant noter qu'une telle suppression n'est pas sans conséquence. Nous vous invitons donc à préalablement lire la page "Supprimer un profil" pour en mesurer l'impact.

Il s'agit de l'opération DELETE/entity{e}/table{t}/profile{p}

Les paramètres de celle-ci sont

  • l'entité de la table de profils

  • la table de profils

  • l'identifiant du profil à supprimer ("profileId" ou couple "attributClé=Valeur")

images/download/attachments/615292244/image2019-3-15_16-5-22.png

Astuce

Un code de réponse 200 indiquera le succès de l'opération.

Les APIs ACTITO permettent la suppression de profils uniquement un par un. La suppression en masse de profils n'est possible que via l'interface ACTITO. Pour découvrir comment, nous vous invitons à consulter la page "Supprimer des profils sur base d'une liste".