Solução de problemas do conector¶

Erros da etapa de autenticação¶

Podem ocorrer problemas ao conectar-se ao ServiceNow no assistente de instalação ou ao executar manualmente o procedimento SET_CONNECTION_CONFIGURATION. Caso encontre erros durante esta etapa, certifique-se de que o usuário que instalou o conector tenha acesso à tabela sys_db_object.

Os códigos de status de erro que podem estar relacionados a problemas de ACL no objeto JSON retornado do procedimento SET_CONNECTION_CONFIGURATION são os seguintes:

• REQUEST_FAILED

É possível executar a consulta abaixo semelhante à do conector para verificar o acesso. Até que a solicitação retorne o resultado esperado, não será possível instalar o conector. Por exemplo, se você estiver usando curl para enviar a solicitação HTTP:

# checking access to the sys_db_object table
curl -u '<username>:<password>' "https://<servicenow_instance>.service-now.com/api/now/table/sys_db_object?sysparm_limit=1"

Onde:

servicenow_instance

Especifica o nome de sua instância do ServiceNow®.

username e password

Especifique as credenciais para sua instância do ServiceNow®.

Respostas de exemplo:

• Pelo menos alguns campos são retornados – o usuário tem as permissões necessárias para acessar a tabela.

• A resposta está vazia – o usuário tem permissão para acessar a tabela, mas não o registro processado. Isso pode causar problemas mais tarde.

• A resposta contém um erro – o usuário não tem as permissões necessárias para acessar a tabela.

Validação de erros de etapa de origem¶

Podem ocorrer problemas ao validar a origem no assistente de instalação ou ao executar manualmente o procedimento FINALIZE_CONNECTOR_CONFIGURATION. Se encontrar erros durante esta etapa, certifique-se de que o usuário usado para instalar o conector tenha as permissões necessárias para acessar as tabelas de metadados.

Os códigos de status de erro que podem estar relacionados a problemas de ACL no objeto JSON retornado do procedimento FINALIZE_CONNECTOR_CONFIGURATION são os seguintes:

• METADATA_TABLE_ACCESS_VALIDATION_ERROR

• JOURNAL_TABLE_ACCESS_VALIDATION_ERROR

É possível executar consultas abaixo semelhantes às do conector para verificar o acesso. Até que as solicitações retornem os resultados esperados, não será possível instalar o conector. Por exemplo, se você estiver usando curl para enviar a solicitação HTTP:

# checking access to the sys_db_object table
# expected fields in the result object: sys_id, super_class, name
curl -u '<username>:<password>' "https://<servicenow_instance>.service-now.com/api/now/table/sys_db_object?sysparm_fields=sys_id,super_class,name&sysparm_limit=1&sysparm_query=name=sys_db_object"

# checking access to the sys_dictionary table
# expected fields in the result object: sys_id, name, element, internal_type
curl -u '<username>:<password>' "https://<servicenow_instance>.service-now.com/api/now/table/sys_dictionary?sysparm_fields=sys_id,name,element,internal_type&sysparm_limit=1&sysparm_query=name=sys_dictionary"

# checking access to the sys_glide_object table
# expected fields in the result object: sys_id, name, scalar_type
curl -u '<username>:<password>' "https://<servicenow_instance>.service-now.com/api/now/table/sys_glide_object?sysparm_fields=sys_id,name,scalar_type&sysparm_limit=1&sysparm_query=name=datetime"

# checking access to the sys_table_rotation table
# expected fields in the result object: sys_id, name
curl -u '<username>:<password>' "https://<servicenow_instance>.service-now.com/api/now/table/sys_table_rotation?sysparm_fields=sys_id,name&sysparm_limit=1&sysparm_query=name=syslog"

# (optional) - check only if deletions auditing is going to be used
# checking access to the journal table
# if known, "&sysparm_query=tablename=<table_name>" or "&sysparm_query=documentkey=<sys_id>" can be appended to the request
# expected fields in the result object: sys_id, sys_created_on, documentkey, tablename
curl -u '<username>:<password>' "https://<servicenow_instance>.service-now.com/api/now/table/<journal_table>?sysparm_fields=sys_id,sys_created_on,documentkey,tablename&sysparm_limit=1"

Onde:

servicenow_instance

Especifica o nome de sua instância do ServiceNow®.

username e password

Especifique as credenciais para sua instância do ServiceNow®.

journal_table

Especifica o nome de sua tabela ServiceNow® usada para auditoria de exclusões. Normalmente isso tem valor de sys_audit_delete.

Respostas de exemplo:

• Todos os campos esperados estão presentes na resposta – o usuário tem as permissões necessárias.

• Alguns dos campos esperados estão ausentes – o usuário não tem as permissões necessárias para todas as colunas.

• A resposta está vazia – o usuário não tem as permissões necessárias para todas as linhas.

• A resposta contém um erro – o usuário não tem as permissões necessárias para a tabela.

Obtenção de dados para solução de problemas¶

Para obter dados de solução de problemas, chame o procedimento armazenado GET_TROUBLESHOOTING_DATA:

CALL GET_TROUBLESHOOTING_DATA(<from_timestamp>, <to_timestamp>);

Onde:

from_timestamp

Especifica o início do intervalo de datas (no fuso horário UTC) para o qual os dados devem ser buscados.

to_timestamp

Especifica o fim do intervalo de datas (no fuso horário UTC) para o qual os dados devem ser buscados.

Este procedimento armazenado retorna os seguintes dados em formato tabular:

• Informações de configuração

• Erros experimentados pelo conector

• Histórico de ingestão

O exemplo a seguir mostra como chamar este procedimento armazenado:

CALL GET_TROUBLESHOOTING_DATA('2024-02-05 10:00:00', '2024-02-10 22:30:00');

Você pode salvar os dados retornados no formato CSV para enviar para o suporte Snowflake.

Restauração do warehouse do conector¶

Se o conector perder o acesso a seu warehouse, configure um novo chamando o procedimento armazenado UPDATE_WAREHOUSE.

Restauração do banco de dados e esquema para os dados do ServiceNow®¶

Se o banco de dados ou esquema para os dados do ServiceNow® for descartado, a única maneira de recuperá-lo é executando o comando UNDROP. Se este comando não estiver disponível, você deverá reinstalar o conector e fazer a ingestão dos dados do ServiceNow® novamente.

Se uma exibição contendo os dados do ServiceNow® for descartada, ela deverá ser recriada automaticamente na próxima vez em que a tarefa em segundo plano responsável pela sua criação for executada.

Se uma das tabelas contendo os dados do ServiceNow® (a tabela de logs de eventos ou dados brutos) for descartada e não for possível usar o comando UNDROP TABLE para recuperá-la, faça o seguinte para iniciar a ingestão da tabela do ServiceNow® novamente:

• Certifique-se de que os logs de eventos e as tabelas de dados brutos desta tabela do ServiceNow® sejam descartados.

• Desative a tabela do ServiceNow®.

• Use o procedimento DELETE_TABLE.

• Ative a tabela do ServiceNow®.

Restauração da integração da notificação do conector¶

Se o conector perder o acesso ao objeto de integração de notificação, faça os procedimentos para configurar novamente os alertas, recriando o objeto de integração de notificação, se necessário.

Se as notificações por e-mail forem configuradas via Snowsight, então você pode simplesmente desativá-las e reativá-las para restaurar os objetos externos necessários.

Como verificar se os metadados da coluna estão presentes no Snowflake¶

Para verificar se os metadados da coluna estão presentes na tabela sys_dictionary no Snowflake, execute a seguinte consulta:

SELECT * FROM <dest_db>.<dest_schema>.sys_dictionary__view WHERE name = '<table_name>' AND element = '<column_name>';

Se a tabela que você estiver investigando tiver tabelas pai (herdadas de outra tabela no ServiceNow®) e a coluna que você estiver procurando tiver sido adicionada à tabela pai, você deve usar o nome da tabela pai.

Para listar todas as tabelas das quais a tabela de seu interesse herda, use a seguinte consulta:

SELECT
    sys_id,
    name,
    PARSE_JSON(super_class):value::string AS super_class_sys_id
FROM <dest_db>.<dest_schema>.sys_db_object__view
START WITH name = '<table_name>'
CONNECT BY sys_id = PRIOR super_class_sys_id;

Se linhas forem retornadas, os metadados da coluna foram corretamente ingeridos no Snowflake, mas a exibição ainda não foi atualizada. Verifique o status e se:

• a visualização foi atualizada recentemente, mas a coluna ainda não está presente. Entre em contato com o suporte.

• a visualização ainda não foi atualizada, aguarde o próximo cronograma de ingestão.

Se um resultado vazio for retornado, significa que o conector ainda não ingeriu os metadados para esta coluna. Você precisa validar no lado do ServiceNow® se o registro está visível para o conector e tem o carimbo de data/hora correto.

Exibição do status de atualização¶

Para validar quando as visualizações de uma determinada tabela foram atualizadas pela última vez e se a operação foi bem-sucedida, execute a seguinte consulta:

SELECT flattened_views_status, flattened_views_last_updated FROM tables_state WHERE table_name = '<table_name>';

Se a última atualização tiver falhado, talvez você queira consultar a tabela de eventos e procurar por erros relatados pelo conector.

Visualização de disponibilidade dos metadados da coluna do ServiceNow®¶

É possível que o motivo das colunas estarem ausentes na exibição nivelada seja que os metadados da coluna não podem ser ingeridos pelo conector. Isso pode estar sendo causado por ACLs impedindo a linha na tabela sys_dictionary de ser retornada pela API da tabela. Outra razão possível é um valor de carimbo de data/hora anterior na coluna sys_updated_on. Também pode ser o caso de a definição da coluna/tabela ter sido importada de uma instância diferente do ServiceNow®. Para determinar se o conector pode acessar metadados de coluna, execute a solicitação GET para o seguinte ponto de extremidade:

https://<servicenow_instance>.service-now.com/api/now/table/sys_dictionary?sysparm_query=name=<table_name>^element=<column_name>

Se um resultado vazio for retornado, o conector não poderá acessar a coluna. A coluna pode estar protegida por uma ACL ou não estar presente.

Se uma definição de coluna tiver sido retornada, examine o valor do campo sys_updated_on. Confirme se a data corresponde ao horário esperado em que a coluna foi adicionada à tabela. Se a importação foi feita de outra instância, será possível mostrar o momento em que a coluna foi criada. O mecanismo de CDC (atualizações incrementais) no conector pode não perceber que o registro datado no passado foi adicionado. Neste caso, acione uma recarga da tabela sys_dictionary.