Criação de uma atividade JDBC

Crie uma atividade JDBC personalizada para automatizar comandos SQL e chamadas de procedimento armazenado para bancos de dados relacionais do fluxo de trabalho.

Antes de Iniciar

Funções necessárias: activity_admin, activity_creator

Por Que e Quando Desempenhar Esta Tarefa

O modelo de atividade JDBC permite executar instruções ANSI SQL ou procedimentos armazenados em um banco de dados de destino. O suporte para procedimentos armazenados com parâmetros IN, OUT e INOUT está disponível em Xanadu. Para saber como configurar esses parâmetros, consulte Parâmetros de procedimento armazenado JDBC.

Nota:

Se você estiver transferindo dados em massa para uma instância ServiceNow a partir de uma fonte de dados externa, use Principais conceitos de Conjuntos para importação. As atividades JDBC permitem transferir dados entre fontes de dados externas e ServiceNow em um fluxo de trabalho. Não se destinam a substituir os recursos de importação em massa de fontes de dados.

Procedimento

1. Criar ou verificar sua credencial JDBC.
   Suas credenciais JDBC devem ter permissão para o banco de dados de destino e configuração apropriada para a conexão JDBC correspondente. As credenciais devem ser configuradas antes de criar uma atividade JDBC.
2. Crie ou verifique sua conexão JDBC.
   Sua conexão JDBC deve ser configurada com credenciais JDBC válidas antes que você possa criar uma atividade JDBC.
3. Crie uma atividade personalizada.
   Esta ação cria uma atividade personalizada usando um modelo.
4. Depois de configurar as propriedades gerais e criar variáveis de entrada, configure o Comando de Execução JDBC.

   Opção	Descrição
   Conexão JDBC	Configure ou faça referência à conexão JDBC apropriada para o banco de dados. A conexão selecionada fornece a atividade com as seguintes informações: Informações do banco de dados de destino (nomes do servidor e do banco de dados) URL de Conexão Porta do banco de dados de destino (se diferente do número da porta padrão) Nome da instância do banco de dados
   Credencial	Credencial JDBC a ser usada na conexão JDBC.
   Instrução SQL	Insira o ANSI SQL a ser executado no banco de dados de destino JDBC. Nota: Este campo é ocultado quando a caixa de seleção Procedimento armazenado é selecionada. Você pode mapear as variáveis de entrada criadas para configurar as instruções SQL. Por padrão, você pode executar as seguintes instruções SQL. selecionar inserir atualizar excluir mostrar criar descrever Para medida de segurança adicional, uma propriedade do MID Server controla as operações que este JDBCOrchestrationProbe executa, o que restringe os comandos SQL usados. Esta propriedade protege contra comandos potencialmente destrutivos, como descartar banco de dados. O mid.property.jdbc_operations contém os controles de propriedade do MID Server. Nota: Você não pode executar várias instruções de tipos diferentes. Por exemplo, você não pode executar uma instrução "selecionar" e uma instrução "atualizar" juntas, mas você pode executar duas instruções "inserir". No entanto, você não pode executar várias instruções "selecionar" nesta atividade.
   Máximo de linhas	Número máximo de registros para recuperar da banco de dados. O padrão é 1000.
   Tamanho de carga máximo (KB)	Você pode definir um limite para o tamanho máximo da carga de dados recuperados do banco de dados. O padrão é 64 KB.
   Tempo limite de conexão	Quanto tempo a atividade espera para fazer a conexão. Este campo é preenchido automaticamente a partir da fonte de dados, mas pode ser alterado para esta atividade.
   Tempo limite da consulta	Tempo decorrido de espera após a execução da consulta até que os dados sejam retornados. Este campo é preenchido automaticamente a partir da fonte de dados, mas pode ser alterado para esta atividade.
   Requer recursos do MID Server	MID Server a ser usado pelos recursos para consultar o JDBC. Por padrão, o sistema seleciona um MID Server que tenha o recurso JDBC.
   Usar procedimento armazenado	Se marcado, você poderá executar um procedimento armazenado nos bancos de dados MySQL, Oracle ou SQL Server inserindo o nome e os parâmetros do procedimento. Consulte Parâmetros de procedimento armazenado JDBC.

   Nota:

   Você pode mapear valores de parâmetro em uma carga de teste para variáveis na guia Saídas automaticamente. Consulte variáveis de saída do mapeamento automático.

O que Fazer Depois

• Testar entradas de atividade JDBC
• Use o mapeamento automático para gerar saídas e regras de análise (recomendado para JDBC)
• Se você não usar o mapeamento automático, poderá criar variáveis de saída e regras de análise manualmente

Tarefas relacionadas

• Criação de atividades personalizadas usando modelos personalizados do designer de atividades

Criação de uma conexão JDBC para uma atividade Orquestração

A tabela Conexão JDBC [jdbc_connection] fornece as informações que as atividades personalizadas de JDBC da Orquestração usam para se conectar a vários bancos de dados de destino.

Antes de Iniciar

Você deve ter um arquivo JAR apropriado, seja ele fornecido com a instância ou um arquivo JAR personalizado.

Nota:

A instância ServiceNow fornece arquivos mysql-connector-java-5.1.21.jar, sql-server-jdbc-4.0.jare ojdbc6.jar como parte da versão atual, que suporta bancos de dados MySQL, SQLServer e Oracle. Outros bancos de dados, como Sybase ou DB2 Universal, devem usar um arquivo JAR personalizado que deve ser carregado para a instância antes de definir a conexão JDBC.

Funções necessárias: activity_admin, activity_creator

Por Que e Quando Desempenhar Esta Tarefa

As credenciais JDBC credenciais JDBC são recuperadas separadamente pelo modelo do designer de atividades e dão suporte ao armazenamento externo de credenciais, como CyberArk.

Procedimento

1. Navegar até Todos > Orquestração > Credenciais e Conexões > Conexões JDBC e clique em Novo.
2. Preencha o formulário usando os campos da tabela.
   A seleção do banco de dados no campo Formato determina quais campos estão disponíveis.

   Tabela 1. Campos de conexão JDBC

   Campo	Formato do banco de dados	Descrição
   Nome	Todos	Nome exclusivo desta conexão JDBC. Por exemplo, você pode inserir JDBC MySQLProd.
   Tempo limite da consulta	Todos	Tempo máximo decorrido em que a consulta JDBC pode ser executada sem uma resposta.
   Tempo limite de conexão	Todos	Tempo máximo decorrido para a atividade JDBC aguardar ao tentar se conectar ao banco de dados de destino.
   Aplicação	Todos	Escopo desta tabela. Por padrão, a tabela Conexão JDBC [jdbc_connection] é executada no escopo Global.
   Domínio	Todos	Domínio desta tabela. Por padrão, a tabela Conexão JDBC [jdbc_connection] é executada no domínio global.
   Formato	Todos	Tipo de banco de dados para esta conexão. As opções padrão são: MySQL Oracle SQLServer Nenhum(a) Você pode adicionar Sybase ou DB2 Universal à lista de seleção carregando o arquivo JAR do driver JDBC apropriado para a instância. A Orquestração reconhece automaticamente esses drivers quando eles são carregados no sistema e os adiciona a esta lista.
   Servidor	Oracle, MySQL, SQLServer	Nome do host ou endereço IP do servidor do banco de dados.
   Oracle sid	Oracle	O identificador do site do banco de dados Oracle. O valor padrão é orcl.
   Porta Oracle	Oracle	Porta que o banco de dados Oracle está usando. O valor padrão é 1521.
   Nome do banco de dados	MySQL, SQLServer	Nome do banco de dados.
   Porta do banco de dados	MySQL, SQLServer	Porta que o banco de dados selecionado está usando.
   Nome da instância	SQLServer	Nome da instância do SQLServer selecionado
   URL de Conexão	Todos	URL que o MID Server usa para se conectar ao banco de dados especificado. O URL é criado automaticamente quando você salva o formulário e é somente leitura para os bancos de dados padrão. Nota: Se o formato selecionado não for um dos bancos de dados padrão, você deve criar o URL de conexão manualmente para que o MID Server saiba como criar a conexão.
   Driver JDBC	Nenhum, DB2 Universal, Sybase	O driver JDBC a ser usado para esta conexão quando não for um banco de dados padrão. Nota: Se você adicionar um banco de dados Sybase ou DB2 Universal, deverá inserir o nome do driver neste campo e carregar o arquivo JAR do driver para a instância.

   Figura 1. Conexão JDBC com exemplo do Oracle

   

3. Clique em Enviar.

Tópicos relacionados

• Credenciais JDBC

Mapeamento automático de variáveis de saída de atividade JDBC

Com o ServiceNow designer de atividades você pode mapear valores de parâmetro em uma carga de teste para variáveis na guia Saída automaticamente.

Antes de Iniciar

Função necessária: administrador

Procedimento

1. No formulário de modelo do provedor JDBC, selecione a guia Entradas.
2. Clique em Testar atividade para testar os parâmetros de entrada.
   Se você adicionou valores reais para os parâmetros e campos, o sistema executará esses valores no destino especificado e retornará a carga resultante. Se você mapeou variáveis de entrada para campos e parâmetros, o sistema exibirá uma caixa de diálogo para atribuir valores de teste a essas variáveis.
3. Forneça valores de teste, se solicitado, e clique em OK para exibir a carga.
   A carga inteira aparece na janela Saída bruta do formulário de Resposta.

   

4. Selecione uma das seguintes opções de mapeamento automático.
   • Mapear automaticamente para local: mapeia valores diretamente para uma variável local para uso na atividade.
   • Mapear automaticamente para saída: mapeia valores diretamente para a variável de saída para passar para outras atividades no fluxo de trabalho. O mapeamento automático para uma variável de saída cria uma matriz de objetos, cada um contendo os nomes das colunas do resultado da consulta.

Parâmetros de procedimento armazenado JDBC

Você pode usar Orquestração para executar um procedimento armazenado nos bancos de dados MySQL, Oracle DB e MS-SQL.

Há suporte para vários tipos de dados, com as seguintes limitações:

• Somente um conjunto de resultados é retornado.
• A ordem dos tipos de dados de entrada e saída nos parâmetros do procedimento armazenado deve corresponder à definição da atividade.
• Binário, Blob, Varbinary e LongBinary devem ser codificados em base64.
• Data, hora e carimbo de data/hora têm um formato específico:

  Formato de data: AAAA-MM-DD

  AAAA-MM-DD é o formato compatível.

  Formato de hora: hh:mm:ss[.sss]

  hh:mm:ss[.sss] é o formato compatível. A precisão é em milissegundos apenas. Microssegundos ou nanossegundos não podem ser processados.

  Nota:

  10:30:59 e 10:30:59.999000 estão corretos, mas 10:30:59. está incorreto.

  Formato de carimbo de data/hora: AAAA-MM-DD hh:mm:ss[.ffffff]

  AAAA-MM-DD hh:mm:ss[.ffffff] é o formato compatível. A precisão é de microssegundos.

• ResultSet é o primeiro conjunto de resultados que retorna do servidor de banco de dados.
• O MS-SQL não oferece suporte a parâmetros INOUT. Se você usar parâmetros INOUT, o modelo de atividade os mapeia de forma transparente para os parâmetros OUT.

Nota:

Se você não quiser fazer uma validação de tipos de dados em parâmetros de procedimento armazenado, como o comportamento legado, defina glide.stored_proc.data_type.validation como falso. Consulte Propriedades do MID Server para obter mais informações.

Tabela 2. Parâmetros de procedimento armazenado

Campo	Descrição
Modo	Tipo de parâmetro de procedimento armazenado. Parâmetros compatíveis: IN OUT INOUT
Tipo de SQL	Um tipo de dados SQL. Tipos de dados compatíveis: ARRAY BIGINT BINARY BIT BLOB CHAR CLOB DATA DECIMAL DISTINCT DOUBLE FLOAT INT INTEGER JAVA_OBJECT LONGVARBINARY LONGVARCHAR NULO NUMERIC OUTRO REAL REF REF_CURSOR SMALLINT STRUCT HORA TIMESTAMP TINYINT VARBINARY VARCHAR
Nome/Valor	Pares de nome-valor a serem passados para o host. Você pode criar esses parâmetros manualmente ou arrastar e soltar variáveis de entrada nos campos de parâmetro e atribuir um valor.

Nota:

Nem todos os provedores de banco de dados oferecem suporte a toda a gama de tipos de dados JDBC. Consulte o manual de referência do banco de dados para entender os tipos de dados compatíveis com sua instalação.

Teste de entradas de modelo de atividade

Você pode testar os parâmetros de entrada de uma atividade personalizada JDBC durante seu desenvolvimento sem precisar executar a atividade em um contexto de fluxo de trabalho.

Antes de Iniciar

Crie variáveis de entrada e mapeie-as para campos no formulário de Comando de Execução ou forneça valores reais para esses campos. Funções necessárias: web_service_admin, activity_admin, activity_creator

Por Que e Quando Desempenhar Esta Tarefa

Este teste de entrada executa somente os parâmetros de entrada em um endpoint e não os scripts de pré-processamento ou pós-processamento. Não é necessário fazer o check-out da atividade para testá-la.

Nota:

Se você fornecer informações suficientes para a Orquestração contatar o endpoint ou o host e retornar dados, poderá testar as variáveis de entrada. Você pode testar a partir de qualquer fase no designer de atividades. Normalmente, a fase de Comando de Execução é o ponto em que suas entradas estão prontas para teste.

Procedimento

1. No Comando de Execução JDBC, clique em Testar entradas.
   A lista de variáveis de origem de entrada é exibida. Se você adicionou valores padrão para essas variáveis, esses valores serão exibidos na coluna Valor substituto. As variáveis obrigatórias são marcadas com uma estrela vermelha.

   Nota:

   O teste falhará se o MID Server não puder ser encontrado ou se ele não puder se conectar ao destino.

   Figura 2. Valores de teste de entrada JDBC

   

2. Filtre a lista de variáveis com estes controles:
   • Todas as entradas: exibe todas as variáveis de entrada. Este controle é a visualização padrão.
   • Entradas obrigatórias: exibe somente variáveis obrigatórias.
   • Entradas sem padrões: mostra as variáveis de entrada que não têm valores padrão atribuídos.
3. Redefina os valores conforme necessário.
   • Redefinir valores padrão: se estiverem presentes, este controle substitui todos os valores de teste definidos neste formulário pelos valores padrão.
   • Limpar valores: limpa todos os valores na lista de variáveis de entrada, mesmo se houver valores padrão.
4. Quando os valores de teste estiverem configurados corretamente, clique em OK.
   O sistema executa os valores de todas as entradas configuradas em relação ao destino especificado e retorna a carga resultante. Os botões no formulário de resposta exibem diferentes exibições da carga. A carga inteira aparece na janela Saída bruta.

   Figura 3. Carga de resposta do teste de entradas

   

5. Para mapear valores de parâmetro apropriados na carga para variáveis na fase de Saídas automaticamente, selecione uma opção de mapeamento automático.
6. Clique no X no canto superior direito da janela para fechá-la.