API Webhook du connecteur du lieu de travail
L’API Webhook du connecteur du lieu de travail est une interface générique qui permet de stocker des données provenant de différents types de matériel ou de capteurs du lieu de travail (tels que des systèmes de badges ou des capteurs de présence) dans des tables Prestation de services de lieu de travail.
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 configuration de 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 de l’événement basée sur le matériel/le capteur vers la table cible ServiceNow , telle que la table Données de participation des employés [sn_wsd_wc_employee_attendance_data].
Pour plus d’informations sur les webhooks du connecteur du lieu de travail, reportez-vous à la section Workplace Connectors.
Webhook du connecteur du lieu de travail : PUBLIER /workplace_connector_webhook/événement
Crée un enregistrement dans la table Événements du connecteur [sn_wsd_wc_connector_events], puis stocke les données d’événement basées sur le matériel/le capteur 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 Événements de connecteur, les transforme et les écrit dans la table Données de participation des employés [sn_wsd_wc_employee_attendance_data]. Le champ État est alors défini sur Traité.
Le mappage des données entre les données de charge utile de l’enregistrement des événements du connecteur et l’enregistrement des données de participation 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 associée [sn_wsd_wc_connector_config]. Pour ce point de terminaison, il s’agit du point d’extension BadgingDataHandler.
traité sont purgés au bout de deux jours à compter de la date de création. Les enregistrements à 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/{api_version}/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. Par 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 d’événement. Type de données : chaîne Table : Configuration du fournisseur [sn_wsd_wc_provider_config] |
| 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. Type de données : chaîne Table : configuration du fournisseur [sn_wsd_wc_provider_config] |
| token_value | Valeur associée au jeton de sécurité, telle qu’un mot de passe. Utilisé pour authentifier la demande. Type de données : chaîne Table : configuration du fournisseur [sn_wsd_wc_provider_config] |
| 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 de chaque événement sont stockées dans un enregistrement distinct des données de participation des employés. Remarque : Assurez-vous que tout horodatage fourni respecte le formatage ISO 8601 pour éviter tout problème d’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 la 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 la 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 qui s’est produite pendant le 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.erreur | Message d'erreur. Type de données : chaîne |
| état | É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"
}