Tipos de ações externas para automatizar scripts no Tactium IP (URA)

---

Objetivo

Este documento visa explicar sobre os tipos de ações externas e suas conexões dentro do Tactium IP – IVR Manager, destacando as particularidades de cada tipo de ação externa.

Tipos de ações externas

Atualmente temos os seguintes tipos de ações externas que podem ser consumidas a partir do Tactium IP dentro do IVRManager, tais como:

• Builtin que são as nativas do Tactium IP e;
  • Validação CPF
  • Validação CNPJ
• Externas que são consumidas nos seguintes formatos:
  • Procedure SQL Server
  • Web Service
    • Formato JSON
    • Formato JSON Restful
    • Formato JSON QueryString+ Array
    • Formato JSON Restful + Array
    • Formato SOAP

Para mais informações do cadastro das ações externas acesse a página Configurando ações externas para automatizar scripts no Tactium IP.

Builtin

No Tactium IP existe nativamente as seguintes ações.

Validação CPF

Para configurar um método de ação nativa através do CPF devemos ir em Cadastro de Ações Externas>>Nova .

Depois devemos selecionar o ‘Tipo de Ação’ como “Builtin”, em ‘Nome do método’ selecionar “Validar CPF” e em ‘Configuração padrão’ não precisarmos selecionar nenhuma.

Em ‘Parâmetros de entrada’ devemos adicionar um Novo com as seguintes configurações:

• Nome: Command;
• Tipo de parâmetro: Variável;
• Variável: (A que tiver sido escolhida para armazenar o CPF).

Em ‘Parâmetros de saída’ devemos adicionar um Novo com as seguintes configurações:

• Nome: Resultado;
• Tipo de parâmetro: Variável;
• Variável: (A que tiver sido escolhida para guardar o resultado da validação).

Quando a ação externa for executada na URA ela vai validar o CPF e informar o resultado como 1 se for válido e se for inválido.

Validação CNPJ

Para configurar um método de ação nativa através do CNPJ devemos ir em Cadastro de Ações Externas>>Nova .

Depois devemos selecionar o ‘Tipo de Ação’ como “Builtin”, em ‘Nome do método’ selecionar “Validar CNPJ” e em ‘Configuração padrão’ não precisarmos selecionar nenhuma.

Em ‘Parâmetros de entrada’ devemos adicionar um Novo com as seguintes configurações:

• Nome: Command;
• Tipo de parâmetro: Variável;
• Variável: (A que tiver sido escolhida para armazenar o CNPJ).

Em ‘Parâmetros de saída’ devemos adicionar um Novo com as seguintes configurações:

• Nome: Resultado;
• Tipo de parâmetro: Variável;
• Variável: (A que tiver sido escolhida para guardar o resultado da validação).

Quando a ação externa for executada na URA ela vai validar o CNPJ e informar o resultado como 1 se for válido e se for inválido.

Externas

Temos nativamente os seguintes formatos que podem ser consumidos no Tactium IP.

Procedure SQL Server

Stored Procedure, que traduzido significa procedimento armazenado, é uma conjunto de comandos em SQL que podem ser executados de uma só vez, como em uma função. Ele armazena tarefas repetitivas e aceita parâmetros de entrada para que a tarefa seja efetuada de acordo com a necessidade individual.

Criando a procedure no banco de dados SQL server

Para configurar um método do tipo procedure é necessário criar a procedure no mesmo banco de dados que foi configurado no cadastro de configurações de conexões.

Abaixo vamos configurar uma procedure que verifica o horário do servidor de banco de dados retorna uma letra de acordo com o horário.

Como podemos ver abaixo a procedure se chama “SP_VERIFICA_ PERIODO” e retorna uma variável chamada de “PERIODO”.

Caso o “Horario” seja menor ou igual à “12:00:00” a procedure irá retornar “PERIODO = M” (Manhã), o horário for menor ou igual “18:00:00” irá retornar “PERIODO = T” (Tarde), se for maior diferente dos demais parâmetros irá retornar  “PERIODO = N” (Noite).

Cadastro da configuração (Conexão)

Para criar uma ação externa do tipo procedure é necessário primeiramente realizar o cadastro da configuração de conexão com o banco de dados.

• Nome: Preencha o campo nome com o nome da configuração (Conexão).
• Url: Insira uma string de conexão com o Banco de dados no Campo, conforme o exemplo:
  user id=Usuário;Server=IP_Servidor;persist security info=False;initial catalog=Banco;Password=Senha;
• Tipo: Defina o tipo de conexão como DbConnection.
• Tipo servidor: Defina como SQL Server.

Depois clique em para salvar as configurações.

Cadastrando ação externa

Após criar a procedure no banco de dados e cadastrar as configurações de conexão com o banco de dados será necessário realizar o cadastro da ações externa.

• Nome: Preencha o campo nome com o nome da ação externa.
• Tipo de ação: Builtin
• Nome método: Executar Procedure
• Configuração Padrão: Defina a conexão com o banco de dados cadastrada anteriormente.
• Parâmetros de Entrada e saída: Cadastre os parâmetros de entrada e saída conforme ilustrado na tabela abaixo.

Tipo parâmetro	Nome	Tipo	Valor
Entrada	Command	Valor Fixo	SP_VERIFICA_PERIODO
Saída	Periodo	Variável	Periodo

Neste tipo de ação externa o primeiro parâmetro de entrada deverá ser o “Command”. Note que o parâmetro deve ser digitado respeitando as letras maiúsculas e minúsculas o seu tipo deverá ser fixo e o valor deverá ser o nome da procedure criada.

 

Os parâmetros de saída sempre serão do tipo variável e irão receber o resultado do processamento da ação externa, note que o nome da variável deverá ser exatamente como o criado na procedure respeitando as letras maiúsculas e minúsculas.

Depois clique em para salvar a ação externa.

Exemplo de URA Consumindo uma procedure parecida com a criada neste documento:

Web Service (Formato JSON)

JSON (Java Script Object Notation) é basicamente um formato leve de troca de dados entre sistemas. O JSON além de ser um formato leve para troca de dados, é também, muito simples de ler. Abaixo segue um exemplo de Obtenção de Token via JSON.

Cadastro da configuração (Conexão)

Para criar uma ação externa do tipo Web Service é necessário primeiramente realizar o cadastro da configuração de conexão com a URL do método que será consumido a partir da URA.

• Nome: Preencha o campo nome com o nome da configuração (Conexão).
• Url: Insira a URL referente ao método do Web Service, conforme o exemplo.
• Tipo: Defina o tipo de conexão como “Web Service”.

Depois clique em para salvar as configurações.

Para mais detalhes acesse o tópico “3.2.1 Web Service”.

Cadastrando ação externa

Após realizar o cadastro da Url do Web Service, será necessário cadastrar a ação externa.

• Nome: Preencha o campo nome com o nome da ação externa.
• Tipo de ação: Builtin.
• Nome método: Requisição HTTP/XML.
• Configuração Padrão: Defina a conexão com a Url cadastrada no tópico anterior.
• Parâmetros de Entrada e saída: Para realizar o cadastros dos parâmetros de entrada e saída será necessário que você compreenda o funcionamento do Web Service que está prestes a cadastrar.
  

  ObterToken
  Nome do Método	Verbo	Formato da URL	ContentType	URL
  Requisição HTTP/XML	POST	QueryString	application/json	http://IP_Server/api/Token

  Neste caso, vamos simular um web service que irá receber o nome e senha como parâmetro de entrada e irá retornar um token fictício no parâmetro de saída, desse modo devemos configurar conforme ilustrações abaixo:

Parâmetros
Tipo de parâmetro	Nome	Tipo	Forma envio
Entrada	Nome	Valor Fixo	Body
Entrada	Senha	Valor Fixo	Body
Saída	Success	Variável	Success
Saída	Codigo	Variável	Codigo
Saída	Message	Variável	Message
Saída	Data.token	Variável	token

Neste tipo de ação externa os parâmetros de entrada deverão seguir o padrão documentado no Web Service enviando as variáveis necessárias para o seu correto funcionamento.

Ao executar o método do Web Service a URL irá conter os “parâmetros de entrada” seguindo o padrão “Paramento=valor”, caso haja mais de um parâmetro de entrada os demais parâmetros serão separados por “&”, conforme exemplo abaixo:

http://IP_Servidor/obterToken?Nome=Arthur&Senha=1234

Web Service (Formato JSON Restful)

REST significa (Representational State Transfer). Em português, Transferência de Estado Representacional. Trata-se de uma abstração da arquitetura da Web. Resumidamente, o REST consiste em princípios/regras/constraints que, quando seguidas, permitem a criação de um projeto com interfaces bem definidas. Desta forma, permitindo, por exemplo, que aplicações se comuniquem.

Existe uma certa confusão quanto aos termos REST e RESTful. Entretanto, ambos representam os mesmo princípios. A diferença é apenas gramatical. Em outras palavras, sistemas que utilizam os princípios REST são chamados de RESTful.

• REST: conjunto de princípios de arquitetura
• RESTful: capacidade de determinado sistema aplicar os princípios de REST.

Cadastro da configuração (Conexão)

Para criar uma ação externa do tipo Web Service é necessário primeiramente realizar o cadastro da configuração de conexão com a Url do método que será consumido a partir da URA.

• Nome: Preencha o campo nome com o nome da configuração (Conexão).
• Url: Insira a Url referente ao método do Web Service, conforme o exemplo:
  http://IP_Servidor/obter_token/
• Tipo: Defina o tipo de conexão como “Web Service”.

Depois clique em para salvar as configurações.

Para mais detalhes acesse o tópico “3.2.1 Web Service”.

Cadastrando ação externa

Após realizar o cadastro da Url do Web Service, será necessário cadastrar a ação externa.

• Nome: Preencha o campo nome com o nome da ação externa.
• Tipo de ação: Builtin.
• Nome método: Requisiçao HTTP/XML.
• Configuração Padrão: Defina a conexão com a Url cadastrada no tópico anterior.
• Verbo: GET
• Formato da URL: REST
• ContentType: application/json
• Parâmetros de Entrada e saída: Para realizar o cadastros dos parâmetros de entrada e saída será necessário que você compreenda o funcionamento do Web Service ou Web API que está prestes a cadastrar, neste caso, vamos simular um web service que irá receber o “Nome” e a “Senha” como parâmetros de entrada e irá retornar um Success, Message, Codigo e o Token, conforme ilustrado na tabela abaixo:

Parâmetros
Tipo de parâmetro	Nome	Tipo	Valor
Entrada	Authorization	Variável	Authorization
Entrada	1_Nome	Variável	Nome
Entrada	2_Senha	Variável	Senha
Saída	Success	Variável	Success
Saída	Message	Variável	Message
Saída	Codigo	Variável	Codigo
Saída	Data.Token	Variável	Token

Desse modo o retorno será semelhante a imagem abaixo:

Neste tipo de ação externa os parâmetros de entrada deverão seguir o padrão documentado no Web Service enviando as variáveis necessárias para o seu correto funcionamento.

A mesma deverá ser cadastrada exatamente como está no ilustrado na imagem acima respeitando as letras maiúsculas, minúsculas e ponto. Durante a chamada do método esta variável não estará presente na URL da chamada.

Ao executar o método do Web Service cadastrado, o Tactium IP irá chamar uma Url semelhante à do exemplo abaixo:
http://IP_Servidor/obter_token/Arthur/1234

Sendo o primeiro parâmetro o CPF e o segundo o RG conforme o exemplo:

http://IP_Servidor/obter_token/{Nome]/{Senha}

Note que em requisições do tipo Restful não serão passados os nomes dos parâmetros de entrada na Url. Então será necessário que os parâmetros sejam passados na ordem correta durante a chamada da Url.

Quando for cadastrar o parâmetros de entrada o nome de todas as variáveis devem iniciar por um numero em ordem crescente, por exemplo “1_Nome e 2_Senha”, conforme o ilustrado na imagem acima. Durante a chamada do método o valor numeral inserido no nome da variável de entrada não estará presente na URL da chamada.

Web Service (Formato JSON QueryString+ Array)

Os arrays compreendem objetos com vários valores de um mesmo tipo (string, por exemplo). Esses valores são identificados ou referenciados por um índice.

Cadastro da configuração (Conexão)

Para criar uma ação externa do tipo Web Service é necessário primeiramente realizar o cadastro da configuração de conexão com a Url do método que será consumido a partir da URA.

• Nome: Preencha o campo nome com o nome da configuração (Conexão).
• Url: Insira a Url referente ao método do Web Service, conforme o exemplo:
  http://IP_Servidor/obter_token/
• Tipo: Defina o tipo de conexão como “Web Service”.

Depois clique em para salvar as configurações.

Para mais detalhes acesse o tópico “3.2.1 Web Service”.

Cadastrando ação externa

Após realizar o cadastro da Url do Web Service, será necessário cadastrar a ação externa.

• Nome: Preencha o campo nome com o nome da ação externa.
• Tipo de ação: Builtin.
• Nome método: Requisiçao HTTP/XML.
• Configuração Padrão: Defina a conexão com a Url cadastrada no tópico anterior.
• Verbo: GET
• Formato da URL: QueryString
• ContentType: application/json
• Parâmetros de Entrada e saída: Para realizar o cadastros dos parâmetros de entrada e saída será necessário que você compreenda o funcionamento do Web Service ou Web API que está prestes a cadastrar, neste caso, vamos simular um web service que irá receber o “Nome” e o “Senha” como parâmetros de entrada e irá retornar um array com Success,  Message, Codigo e token fictícios, conforme ilustrado na tabela abaixo:

Parâmetros
Tipo de parâmetro	Nome	Tipo	Valor
Entrada	Authorization	Variável	Authorization
Entrada	Nome	Variável	Nome
Entrada	Senha	Variável	Senha
Saída	Success	Variável	Success
Saída	Message	Variável	Message
Saída	Codigo	Variável	Codigo
Saída	Data[0].token	Variável	token

Neste tipo de ação externa os parâmetros de entrada deverão seguir o padrão documentado no Web Service enviando as variáveis necessárias para o seu correto funcionamento.

A mesma deverá ser cadastrada exatamente como está no ilustrado na imagem acima respeitando as letras maiúsculas, minúsculas e ponto. Durante a chamada do método esta variável não estará presente na URL da chamada.

Ao executar o método do Web Service cadastrado, o Tactium IP irá chamar uma Url semelhante à do exemplo abaixo:
http://IP_Servidor/obterToken?Nome=Arthur&Senha=12345

Abaixo segue o exemplo do retorno deste Array.

No JSON de retorno de exemplo acima existe um Array chamado data, para pegar as informações do primeiro item do Array podemos nos referir a ele como Data[0], para acessar um segundo item quando houver use Data[1]. Dentro de Data[0] temos as propriedades id, nome e token, para pegar os valores respectivos delas use Data[0].id, Data[0].nome, Data[0].token.

Este exemplo pode ser transformado em REST, bastando alterar o formato da URL para REST, permitindo assim a passagem apenas parâmetros por ordem, ignorando as chaves.

Web Service (Formato JSON Restful + Array)

Os arrays compreendem objetos com vários valores de um mesmo tipo (string, por exemplo). Esses valores são identificados ou referenciados por um índice. Esse índice é um valor inteiro que é responsável por determinar a posição dos elementos dentro de um Array.

Cadastro da configuração (Conexão)

Para criar uma ação externa do tipo Web Service é necessário primeiramente realizar o cadastro da configuração de conexão com a Url do método que será consumido a partir da URA.

• Nome: Preencha o campo nome com o nome da configuração (Conexão).
• Url: Insira a Url referente ao método do Web Service, conforme o exemplo:
  http://IP_Servidor/obter_endereco/
• Tipo: Defina o tipo de conexão como “Web Service”.

Depois clique em para salvar as configurações.

Para mais detalhes acesse o tópico “3.2.1 Web Service”.

Cadastrando ação externa

Após realizar o cadastro da Url do Web Service, será necessário cadastrar a ação externa.

• Nome: Preencha o campo nome com o nome da ação externa.
• Tipo de ação: Builtin.
• Nome método: Requisição HTTP/XML.
• Configuração Padrão: Defina a conexão com a Url cadastrada no tópico anterior.
• Verbo: GET
• Formato da URL: REST
• ContentType: text/xml
• Parâmetros de Entrada e saída: Para realizar o cadastros dos parâmetros de entrada e saída será necessário que você compreenda o funcionamento do Web Service ou Web API que está prestes a cadastrar, neste caso, vamos simular um web service que irá receber o “CodCliente” e o “Estado” como parâmetros de entrada e irá retornar um array com id,  nome, endereços fictícios, conforme ilustrado na tabela abaixo:

Parâmetros
Tipo de parâmetro	Nome	Tipo	Valor
Entrada	1_CodCliente	Variável	CodCliente
Entrada	2_Estado	Valor Fixo	CE
Entrada	Array.Index	Variável	Array.Index
Saída	Array.Index	Variável	Array.Index
Saída	id	Variável	id
Saída	nome	Variável	nome
Saída	endereco	Variável	endereco
Saída	Array.HasNext	Variável	Array.HasNext

Neste tipo de ação externa os parâmetros de entrada deverão seguir o padrão documentado no Web Service enviando as variáveis necessárias para o seu correto funcionamento.

A mesma deverá ser cadastrada exatamente como está no ilustrado na imagem acima respeitando as letras maiúsculas, minúsculas e ponto. Durante a chamada do método esta variável não estará presente na URL da chamada.

Ao executar o método do Web Service cadastrado, o Tactium IP irá chamar uma Url semelhante à do exemplo abaixo:
http://IP_Servidor/obter_endereco/2345678912/CE

Sendo o primeiro parâmetro o “CodCliente” e o segundo o “Estado” conforme o exemplo:

http://IP_Servidor/obter_endereco/{CodCliente]/{Estado}

Note que em requisições do tipo Restful não serão passados os nomes dos parâmetros de entrada na Url. Então será necessário que os parâmetros sejam passados na ordem correta durante a chamada da Url.

Quando for cadastrar o parâmetros de entrada o nome de todas as variáveis devem iniciar por um numero em ordem crescente, por exempo “1_CodCliente e 2_Estado”, conforme o ilustrado na imagem acima. Durante a chamada do método o valor numeral inserido no nome da variável de entrada não estará presente na URL da chamada.

A variável “Array.Index” deverá ser cadastrada tanto como parâmetro de entrada como de saída e serve como índice da chamada de um método com array, desta forma a aplicação irá se basear no valor contido nela para saber quando o array irá terminar. A mesma deverá ser cadastrada exatamente como ilustrado na tabela acima respeitando as letras maiúsculas, minúsculas e ponto.

A variável “Array.HasNext” serve para indicar (enquanto ela for diferente de zero)  que a ação externa deve ser chamada novamente. A mesma deverá ser cadastrada exatamente como está no print acima respeitando as letras maiúsculas, minúsculas e ponto.

Abaixo um exemplo de fluxo do funcionamento do Array.

Abaixo um exemplo de array utilizado em uma arvore de URA Simples.

Note que sempre que a variável Array.HasNext é diferente de zero há um desvio para executar o método do Web Sevice novamente, quando a variável for igual a zero o array termina.

Abaixo segue o exemplo do retorno deste array.

Outra forma de execução do Web Service com Formato JSON Restful + Array pode ser realizada no formato da Web Service com Formato QueryString + Array alterando apenas o formato da URL para REST, permitindo assim a passagem apenas parâmetros por ordem.

Web Service (Formato SOAP)

SOAP (Simple Object Access Protocol, em português Protocolo Simples de Acesso a Objetos) é um protocolo para troca de informações estruturadas em uma plataforma descentralizada e distribuída. Ele se baseia na Linguagem de Marcação Extensível (XML) para seu formato de mensagem, e normalmente baseia-se em outros protocolos da camada de aplicação, mais notavelmente em chamada de procedimento remoto (RPC) e Protocolo de transferência de hipertexto (HTTP), para negociação e transmissão de mensagens.

Cadastro da configuração (Conexão)

Para criar uma ação externa do tipo Web Service é necessário primeiramente realizar o cadastro da configuração de conexão com a Url do método que será consumido a partir da URA.

• Nome: Preencha o campo nome com o nome da configuração (Conexão).
• Url: Insira a Url referente ao método do Web Service, conforme o exemplo:
  http://IP_Servidor/EnviarEmail.asmx?WSDL
• Tipo: Defina o tipo de conexão como “Web Service”.

Depois clique em para salvar as configurações.

Para mais detalhes acesse o tópico “3.2.1 Web Service”.

Em Web Services Soap é necessário saber qual a URL do WSDL, geralmente clicando em “Service Description” na página aonde se encontra todos os métodos do Web service será exibida a página WSDL.

WSDL, que significa “Web Services Description Language”, é um padrão de mercado para descrever Web Services de forma a eliminar ao máximo a necessidade de comunicação entre as partes envolvidas em uma integração de dados.

Cadastrando ação externa

Após realizar o cadastro da Url do Web Service, será necessário cadastrar a ação externa.

• Nome: Preencha o campo nome com o nome da ação externa.
• Tipo de ação: Builtin.
• Nome método: Web services.
• Configuração Padrão: Defina a conexão com a Url cadastrada no tópico anterior.
• Verbo: GET
• Formato da Url: QueryString
• Content/Type: Text/XML
• Parâmetros de Entrada e saída: Para realizar o cadastros dos parâmetros de entrada e saída será necessário que você compreenda o funcionamento do Web Service ou Web API que está prestes a cadastrar, neste caso, vamos simular um web service que irá receber o “Template” e o “Destinatario” como parâmetros de entrada e irá retornar “MensagemRetorno”, “RetornoRequisicao”, conforme ilustrado na tabela abaixo:

Parâmetros
Tipo de parâmetro	Nome	Tipo	Forma envio
Entrada	Command	Valor Fixo	GerarEmailDestinatario
Entrada	Servico	Valor Fixo	wsTactiumIntegracao
Entrada	Template	Variável	Template
Entrada	Destinatario	Variável	Email
Saída	RetornoRequisicao	Variável	RetornoRequisicao
Saída	MensagemRetorno	Variável	MensagemRetorno

O campo Servico deverá ser definido com valor fixo informando o nome do serviço do web service, ele serve para compor o método deve ser chamado. O nome deve ser cadastrado exatamente da forma está no Web Services respeitando letras maiúsculas e minúsculas,  está parâmetro pode ser encontrado na página WSDL do Web Service, procure pelo parâmetro “wsdl:service name”, conforme exemplo abaixo:

O parâmetro Command serve  para definir qual o método será chamado no web service, o mesmo deve conter nome do comando (nome exatamente da forma criada no webservices) que está no parâmetro “s:element name”, conforme exemplo abaixo:
Os demais parâmetros deverão ser de acordo com a lógica do Web Services criados element name.

Ferramentas de testes

Se você procura por uma ferramenta que ofereça uma interface de usuário prática e que permita realizar solicitações HTTP sem a necessidade de escrever um monte de códigos e testar a funcionalidade de uma API, então acesse a nossa base de conhecimento utilizando o link a seguir, nela vamos dar algumas dicas de ferramentas úteis para realizar testes no dia à dia.

• Realizando testes em Web Services ou APIs em Formato JSON
• Realizando testes em Web Services ou APIs em Formato SOAP