API Webhook du connecteur du lieu de travail
L’API Webhook Workplace Connector est une interface générique qui permet de stocker les données de différents types de matériel ou de capteurs du lieu de travail (tels que les systèmes de badges ou les capteurs de présence) dans les tables Workplace Service Delivery.
Cette API s’exécute dans l’espace de noms sn_wsd_wc . Pour accéder à cette API, le module d’extension Workplace Connectors (com.sn_wsd_wc) doit être activé.
Avant d’appeler cette API, vous devez configurer les enregistrements dans les tables Configuration du connecteur [sn_wsd_wc_connector_config] et Configuration du fournisseur [sn_wsd_wc_provider_config]. Pour en savoir plus sur la façon de configurer ces enregistrements, reportez-vous à la section Configure Workplace Connectors.
En outre, vous devez configurer un point d’extension qui définit la conversion/le mappage des données à partir de la charge utile d’événement basée sur le matériel/le capteur vers la table cible ServiceNow , telle que la table Données de présence des employés [sn_wsd_wc_employee_attendance_data].
Pour en savoir plus sur les webhooks Workplace Connector, reportez-vous à la section Workplace Connectors.
Webhook du connecteur du lieu de travail - POST /workplace_connector_webhook/event
Crée un enregistrement dans la table Événements de connecteur [sn_wsd_wc_connector_events], puis stocke les données d’événement basées sur le matériel/les capteurs transmises dans la charge utile du point de terminaison dans le champ Charge utile de cet enregistrement.
Une fois que le point de terminaison a stocké la charge utile, il définit le champ État dans l’enregistrement des événements du connecteur sur nouveau, indiquant que la charge utile n’a pas été traitée.
Une tâche planifiée localise les nouveaux enregistrements de badges dans la table des événements du connecteur, les transforme et les écrit dans la table Données de présence des employés [sn_wsd_wc_employee_attendance_data]. Le champ État est ensuite défini sur Traité.
Le mappage des données entre les données de charge utile de l’enregistrement d’événements du connecteur et l’enregistrement des données de présence des employés est défini dans un point d’extension. Ce point d’extension est identifié dans le champ Définition du point d’extension de la table Configuration du connecteur [sn_wsd_wc_connector_config] associée. Pour ce point de terminaison, il s’agit du point d’extension BadgingDataHandler.
l’état Traité de la table Événements du connecteur sont purgés deux jours après la date de création. Les enregistrements dans l’état d’erreur sont purgés après sept jours à compter de la date de création. Les enregistrements dans le nouvel état ne sont jamais purgés.Format d'URL
URL versionnée : /api/sn_wsd_wc/v1/workplace_connector_webhook/event
URL par défaut : /api/sn_wsd_wc/workplace_connector_webhook/event
Paramètres de demande pris en charge
| Nom | Description |
|---|---|
| api_version | Facultatif. Version du point de terminaison auquel accéder. Exemple : v1 ou v2. Spécifiez uniquement cette valeur pour utiliser une version de point de terminaison différente de la dernière. Type de données : chaîne |
| Nom | Description |
|---|---|
| ni.nolog.id | Requis. Sys_id de l’enregistrement de configuration du fournisseur associé au matériel qui a généré les informations sur l’événement. Situé dans la table Configuration du fournisseur [sn_wsd_wc_provider_config]. Type de données : chaîne |
| token_name | Nom du jeton de sécurité, tel qu’un nom d’utilisateur ou une autre valeur qui identifie le jeton de sécurité. Utilisé pour authentifier la demande. Situé dans la table Configuration du fournisseur [sn_wsd_wc_provider_config]. Type de données : chaîne |
| token_value | Valeur associée au jeton de sécurité, comme un mot de passe. Utilisé pour authentifier la demande. Situé dans la table Configuration du fournisseur [sn_wsd_wc_provider_config]. Type de données : chaîne |
| Nom | Description |
|---|---|
| <charge utile> | Paires nom-valeur des données d’événement basées sur le matériel/le capteur. Les noms doivent correspondre aux noms identifiés dans le point d’extension BadgingDataHandler. Par exemple : Vous pouvez transmettre plusieurs données d’événements dans un seul appel de point de terminaison. Transmettez les données de chaque événement dans un objet distinct. Les données relatives à chaque événement sont stockées dans un enregistrement distinct des données de participation des employés. Remarque : Assurez-vous que l’horodatage fourni respecte le formatage ISO 8601 pour éviter tout problème lors de l’analyse de la date. Type de données : objet JSON |
En-têtes
Les en-têtes de demande et de réponse suivants s'appliquent à cette action HTTP uniquement ou s'appliquent à cette action d'une manière distincte. Pour obtenir une liste des en-têtes généraux utilisés dans l’API REST, consultez En-têtes d’API REST pris en charge.
| En-tête | Description |
|---|---|
| Accepter | Format de données du corps de la réponse. Prend uniquement en charge application/json. |
| Content-Type | Format de données du corps de la demande. Prend uniquement en charge application/json. |
| En-tête | Description |
|---|---|
| Aucun |
Codes d'état
Les codes d'état suivants s'appliquent à cette action HTTP. Pour obtenir une liste des codes d’état possibles utilisés dans l’API REST, consultez Codes de réponse HTTP de l’API REST.
| Code d'état | Description |
|---|---|
| 200 | Réussi. La demande a été correctement traitée. |
| 400 | Demande incorrecte. Un type de demande incorrecte ou mal formé a été détecté. |
| 401 | Non autorisé. Les informations d'identification de l'utilisateur sont incorrectes ou n'ont pas été transmises. |
| 404 | Introuvable. L’élément demandé est introuvable. |
| 500 | Erreur interne du serveur. Une erreur inattendue s'est produite lors du traitement de la demande. La réponse contient des informations supplémentaires sur l'erreur. |
Paramètres du corps de réponse
| Nom | Description |
|---|---|
| erreur | Description de toute erreur survenue lors du traitement des données. Type de données : objet |
| erreur.détail | Informations qui fournissent des détails sur l’erreur. Type de données : chaîne |
| message d’erreur | Message d'erreur. Type de données : chaîne |
| statut | État du traitement du point de terminaison. Valeurs possibles :
Type de données : chaîne |
Demande cURL
L’exemple de code suivant montre comment appeler ce point de terminaison pour ajouter plusieurs événements de lecteur de carte à la table Événements du connecteur. Avant de traiter la demande, la demande est authentifiée.
curl http://instance.servicenow.com/api/sn_wsd_wc/v1/workplace_connector_webhook/event?token_name=token&ni.nolog.id=8e666cb0a3053110bc6e146546fcdad1&token_value=babugosha \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data --data "{
\"Time zone\": \"(UTC+02:00) Jerusalem\",
\"Event\": \"Access granted\",
\"Door\": \"L_TLV001_A3.07_KITCHEN AREA INT\",
\"Side\": \"Reader - In\",
\"Cardholder\": \" ninat.alem\",
\"First name\": \" Nina T\",
\"Last name\": \" Salem\",
\"Credential\": \" ninat.salem's credential\",
\"Employee ID (Cardholder)\": 10097,
\"Event timestamp\": \"11/07/2022 10:57:24\"
}
{
\"Time zone\": \"(UTC+02:00) Jerusalem\",
\"Event\": \"Access granted\",
\"Door\": \"L_TLV003_A4.07_FRONT ENT\",
\"Side\": \"Reader - In\",
\"Cardholder\": \" joe.blue\",
\"First name\": \" Joe\",
\"Last name\": \" Blue\",
\"Credential\": \" joe.blue's credential\",
\"Employee ID (Cardholder)\": 24098,
\"Event timestamp\": \"11/07/2022 10:59:33\"
}"Réponse :
// Successful response
{
"staus": "success"
}
// Error response
{
"error": {
"message": "Events request is invalid. Events query parms incomplete, some fields are missing",
"detail": "Missing fields: token_name, token_value"
}
"status": "failure"
}