Utiliser l'API pour importer les données d'un formulaire web

Accès requis : Analytics et jeton d'API
Difficulté : Développeur uniquement !

Cet article est destiné à guider un développeur qui souhaite importer des informations d'un autre système vers Boréalis. Il donne des exemples sur la façon de :

Obtenir les valeurs possibles pour un menu déroulant
Créer une partie prenante
Créer une communication liée à la partie prenante qui vient d'être créée

Par exemple, si vous avez un site web où les parties prenantes peuvent saisir leurs renseignements personnel pour s'abonner à votre newsletter, ou une section de rétroaction où les parties prenantes peuvent poser des questions ou faire des commentaires. Vous souhaitez envoyer les informations de ce formulaire vers Boréalis.

Avant de commencer

Assurez-vous d'avoir un jeton d'API valide. Cela devrait être fourni par votre superutilisateur.
Vous pouvez trouver la documentation de l'API ici (https://ENTREPRISE.boreal-is.com/api-docs/VOTRE_INSTANCE/).
- Remarque : Si vous n'utilisez pas le Complément vue d'entreprise, ENTREPRISE et VOTRE_INSTANCE devraient être identiques.

Il est également important de comprendre qu'une API est un outil puissant qui permet de transférer des informations entre systèmes. Ainsi, la sécurité est essentielle pour protéger vos données et des mesures supplémentaires doivent être prises pour éviter les potentielles fuites de données. L'une de ces mesures est l'ajout d'un reCAPTCHA sur votre page, ce qui permet aux hébergeurs de sites web de distinguer entre l'accès humain et l'accès automatisé aux sites web, et d'empêcher les bots de spammer les données de votre configuration API.

Obtenir les valeurs possibles pour un menu déroulant

Beaucoup de champs dans Boréalis sont des menus déroulants. Par exemple, un enregistrement doit être lié à un projet (parfois appelé droits d'accès). Pour accéder à la liste des valeurs possibles, vous pouvez faire un appel comme celui-ci :

Appel

curl -X GET "https://ENTREPRISE.boreal-is.com/api/v2/VOTRE_INSTANCE/stakeholders_engagement~register~individuals/values/stkProjectMulti?limit=10&offset=0" -H "accept: application/json" -H "api_key : VOTRE_JETON_API"

Réponse

{
  "total": 3,
  "data": [
    {
      "displayValue": "Mine site",
      "value": 1
    },
    {
      "displayValue": "Transmission line",
      "value": 2
    },
    {
      "displayValue": "General",
      "value": 3
    }
  ]
}

Vous pouvez choisir la valeur que vous souhaitez ajouter. La valeur ne changera pas au fil du temps, vous pouvez donc la configurer initialement et ne pas vous en soucier plus tard.

Créer une partie prenante

Voici un exemple de création d'une partie prenante "Mme Jane Doe".

Vous pouvez trouver la documentation de l'API pour la gestion des individus ici : https://ENTREPRISE.boreal-is.com/api-docs/VOTRE_INSTANCE/stakeholders_engagement~register~individuals/

La création d'un nouvel enregistrement est un appel POST avec le corps suivant :

{ 
  "baseCatIndividualTtlId": 7, 
  "firstName": "Jane", 
  "lastName": "Doe", 
  "stkProjectMulti": [3], 
  "onAddEmail": jane.doe@invalidemail.test, 
  "onAddPhonenumber": "01 22 22 22 22", 
  "onAddAddress": "1 Salmon Street", 
  "onAddCity": "Magog", 
  "onAddStateProvince": "Québec", 
  "onAddCountry": "Canada", 
  "onAddPostcode": "J1X 1G8" 
}

Nous avons utilisé baseCatIndividualTtlId = 7 car dans notre cas c'est pour "Mme".

Vous pouvez trouver de nombreux autres champs qui peuvent être remplis à l'aide de la documentation de l'API.

Réponse

{ 
"sysId": 33842 
}

Vous pouvez l'utiliser pour l'appel de création de communication.

Créer une communication

Voici un exemple de création de communication pour Mme Jane Doe où elle a posé une question.

Vous pouvez trouver la documentation de l'API pour gérer les communications ici : https://ENTREPRISE.boreal-is.com/api-docs/VOTRE_INSTANCE/stakeholders_engagement~consultations~communications/

La création d'un nouvel enregistrement est un appel POST avec le corps suivant :

{ 
"stkMtSummaryNoHl": "Je voulais savoir si la rue sera toujours fermée le week-end prochain. Veuillez m'envoyer un e-mail pour confirmer.", 
"importCommunicationDate": "2021-11-18", 
"baseStakeholderId": [33842 ], 
"stkMtTitle": "Question du site Web", 
"baseProjectId": [3], 
"stkCatMeetingTypeId": 63 
}

Nous avons utilisé stkCatMeetingTypeId = 63 car dans notre cas, il s'agit de questions venant du site Web.

Vous pouvez trouver de nombreux autres champs qui peuvent être remplis à l'aide de la documentation de l'API. La réponse vous donnera l'ID système de la communication créée.

Ajouter votre partie prenante à une liste de distribution

Si vous souhaitez ajouter votre partie prenante à une liste de distribution, vous devez créer la liste de diffusion auparavant et trouver son identifiant.

L'identifiant du système peut être déduit du No. ref. Par exemple un No. ref. DL-00019 signifie que l'identifiant du système est 19.

La création d'un nouvel enregistrement est un appel POST avec l'URL suivante (dans cet exemple, l'identifiant système de la liste de diffusion est 19) :

https://ENTREPRISE.boreal-is.com/api/v2/VOTRE_INSTANCE/stakeholders_engagement~stk_administration_tools~distribution_lists/19/stakeholders

et le corps suivant :

{ 
"baseStakeholderIdAdd": [33842] 
}

Créer une contribution communautaire (investissement social)

Voici un exemple pour créer la demande de commandite qui a été envoyée via un formulaire de site Web.

Vous pouvez trouver la documentation de l'API pour gérer les contributions communautaires ici : https://ENTREPRISE.boreal-is.com/api-docs/VOTRE_INSTANCE/social_investment~investment_portfolio~community_contribution/

La création d'un nouvel enregistrement est un appel POST avec le corps suivant :

{ 
"title": "Demande de commandite", 
"receptionDate": "2023-01-16", 
"contributionContext": "Une partie du programme pour améliorer les options d'activités à l'école.", 
"followUpContact": 33842, 
"contributionType" : 3, 
"requestedItemDescription": "Contribution monétaire", 
"siCatContribItemTypeId": 1, 
"requestedItemValue": 5000, 
"responsiblePerson": 11 
}

Nous avons utilisé

contributionType= 3 car dans notre cas c'est la valeur pour "Commandite"
siCatContribItemTypeId = 1 car il s'agit d'une valeur monétaire
ResponsiblePerson = 11 car il s'agit de "Adam Paige", la personne responsable de l'examen des demandes de commandites.

Vous pouvez trouver de nombreux autres champs qui peuvent être remplis à l'aide de la documentation de l'API. La réponse vous donnera l'ID système de la contribution communautaire créée.

Cela couvre la base sur la façon d'appeler l'API Boréalis pour importer des données à partir d'un site Web. Vous pouvez trouver des informations plus générales sur l'API dans cet article , et nous avons également un exemple sur la façon de récupérer des données de Boréalis pour les transférer vers un autre système .

Articles associés