API do webhook do conector do local de trabalho
A API do Webhook do conector do local de trabalho é uma interface genérica que permite que os dados de diferentes tipos de hardware ou sensores do local de trabalho (como sistemas de crachá ou sensores de ocupação) sejam armazenados em tabelas do Workplace Service Delivery.
Esta API é executada no namespace sn_wsd_wc. Para acessar esta API, o plug-in Workplace Connectors (com.sn_wsd_wc) deve ser ativado.
Antes de chamar esta API, você deve configurar registros nas tabelas Configuração do conector [sn_wsd_wc_connector_config] e Configuração do provedor [sn_wsd_wc_provider_config]. Para obter informações sobre como configurar esses registros, consulte Configure Workplace Connectors.
Além disso, você deve configurar um ponto de extensão que defina a conversão/mapeamento de dados da carga de evento baseada em hardware/sensor para a tabela ServiceNow de destino, como a tabela Dados de participação do funcionário [sn_wsd_wc_employee_attendance_data].
Para obter informações adicionais sobre os webhooks do conector para local de trabalho, consulte Workplace Connectors.
Webhook do conector do local de trabalho - POST /workplace_connector_webhook/event
Cria um registro na tabela Eventos do conector [sn_wsd_wc_connector_events] e armazena os dados de evento baseados em hardware/sensor passados na carga do endpoint para o campo Carga desse registro.
Depois que o endpoint armazena a carga, ele define o campo Estado no registro de eventos do conector como novo, indicando que a carga não foi processada.
Um trabalho programado localiza os novos registros de crachá na tabela Eventos do conector e os transforma e os grava na tabela Dados de participação do funcionário [sn_wsd_wc_employee_attendance_data]. O campo Estado é definido como processado.
O mapeamento dos dados entre os dados de carga no registro de eventos do conector e o registro de dados de participação do funcionário é definido em um ponto de extensão. Este ponto de extensão é identificado no campo Definição de ponto de extensão na tabela Configuração do conector associada [sn_wsd_wc_connector_config]. Para este endpoint, este é o ponto de extensão BadgingDataHandler.
processado são limpos após dois dias a partir da data de criação. Registros no estado de erro são limpos após sete dias a partir da data de criação. Os registros no novo estado nunca são limpos.Formato de URL
URL com controle de versões: /api/sn_wsd_wc/v1/workplace_connector_webhook/event
URL padrão: /api/sn_wsd_wc/workplace_connector_webhook/event
Parâmetros de solicitação compatíveis
| Nome | Descrição |
|---|---|
| api_version | Opcional. Versão do endpoint a ser acessada. Por exemplo, v1 ou v2. Especifique este valor somente para usar uma versão de endpoint diferente da mais recente. Tipo de dados: cadeia de caracteres |
| Nome | Descrição |
|---|---|
| ni.nolog.id | Obrigatório. Sys_id do registro de configuração do provedor associado ao hardware que gerou as informações do evento. Localizado na tabela Configuração do provedor [sn_wsd_wc_provider_config]. Tipo de dados: cadeia de caracteres |
| token_name | Nome do token de segurança, como um nome de usuário ou outro valor que identifica o token de segurança. Usado para autenticar a solicitação. Localizado na tabela de configuração do provedor [sn_wsd_wc_provider_config]. Tipo de dados: cadeia de caracteres |
| token_value | Valor associado ao token de segurança, como uma senha. Usado para autenticar a solicitação. Localizado na tabela de configuração do provedor [sn_wsd_wc_provider_config]. Tipo de dados: cadeia de caracteres |
| Nome | Descrição |
|---|---|
| <payload> | Pares de nome-valor dos dados de evento baseados em hardware/sensor. Os nomes devem corresponder aos nomes identificados no ponto de extensão BadgingDataHandler. Por exemplo: Você pode passar vários dados de evento em uma única chamada de endpoint. Passe os dados de cada evento em um objeto separado. Os dados de cada evento são armazenados em um registro de dados de participação do funcionário separado. Nota: Certifique-se de que todos os carimbos de data/hora fornecidos estejam em conformidade com a formatação ISO 8601 para evitar problemas com a análise de data. Tipo de dados: objeto JSON |
Cabeçalhos
Os cabeçalhos de solicitação e resposta a seguir se aplicam somente a esta ação HTTP ou se aplicam a esta ação de maneira distinta. Para obter uma lista de cabeçalhos gerais usados na REST API, consulte Cabeçalhos de REST API compatíveis.
| Cabeçalho | Descrição |
|---|---|
| Aceitar | Formato de dados do corpo da resposta. Oferece suporte somente a application/json. |
| Tipo de conteúdo | Formato de dados do corpo da solicitação. Oferece suporte somente a application/json. |
| Cabeçalho | Descrição |
|---|---|
| Nenhum |
Códigos de status
Os códigos de status a seguir se aplicam a esta ação HTTP. Para obter uma lista de códigos de status possíveis usados na REST API, consulte Códigos de resposta HTTP da REST API.
| Código de status | Descrição |
|---|---|
| 200 | Bem-sucedido. A solicitação foi processada com sucesso. |
| 400 | Solicitação Incorreta. Foi detectado um tipo de solicitação incorreto ou solicitação malformada. |
| 401 | Não autorizado. As credenciais do usuário estão incorretas ou não foram aprovadas. |
| 404 | Não encontrado. O item solicitado não foi encontrado. |
| 500 | Erro interno do servidor. Ocorreu um erro inesperado ao processar a solicitação. A resposta contém informações adicionais sobre o erro. |
Parâmetros do corpo da resposta
| Nome | Descrição |
|---|---|
| Erro | Descrição de qualquer erro ocorrido durante o processamento dos dados. Tipo de dados: objeto |
| erro.detalhe | Informações que fornecem detalhes sobre o erro. Tipo de dados: cadeia de caracteres |
| erro.mensagem | Mensagens de erro Tipo de dados: cadeia de caracteres |
| status | Status do processamento do endpoint. Valores possíveis:
Tipo de dados: cadeia de caracteres |
Solicitação de cURL
O exemplo de código a seguir mostra como chamar este endpoint para adicionar vários eventos de leitor de cartão à tabela Eventos do conector. Antes de processar a solicitação, ela é autenticada.
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\"
}"Resposta:
// 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"
}