Atenção!| Para usar esse recurso, você deverá ter conhecimento de: conexões SOAP, XML, WSDL e XPATH. |
SOAP significa "Protocolo Simples de Acesso a Objetos", é um protocolo de comunicação baseado em XML que permite a comunicação de mensagens entre aplicações via HTTP, normalmente utilizado em WebServices.
XML é a sigla para Extensible Markup Language, que significa em português "Linguagem Extensível de Marcação Genérica". É uma recomendação para gerar linguagens de marcação para necessidades especiais. XML é capaz de descrever diversos tipos de dados, e seu objetivo principal é a facilidade de compartilhamento de informações através da Internet.
WSDL é uma descrição em formato XML de um Web Service que utilizará SOAP como protocolo. É o acrônimo de Web Services Description Language (Linguagem de Descrição de Serviços Web).
Uma conexão SOAP/WSDL geralmente é representada por uma URL, similarmente as URL´s de navegação na internet. Por isso, ao realizar uma fonte de dados SOAP/WSDL, o fornecedor do sistema que irá fornecer a API deverá informar, no mínimo, a URL do serviço.
Muitas vezes, você conseguirá abrir o arquivo SOAP/WSDL acessando a URL informada diretamente em seu navegador de internet:
Conectividade
O primeiro ponto a verificar ao realizar uma conexão SOAP/WSDL é se o servidor onde está instalado o Orquestra consegue "enxergar" a URL a ser integrada. Se você consegue abrir a URL em seu navegador em seu computador local, é um passo positivo, pois significa que a URL realmente existe. Mas não assegura que o servidor do Orquestra conseguirá acessar.
É muito normal as equipes de TI configurarem servidores para que eles não possam acessar a Internet ou outros recursos da Intranet da empresa. Isso poderá impedir que o Orquestra conecte-se ao serviço.
De modo geral, siga as recomendações abaixo:
- Tente acessar a URL em seu computador local, usando seu navegador. Se funcionar, é um ponto positivo;
- Se você tiver acesso ao servidor onde o Orquestra está instalado, abra o navegador de internet instalado no servidor e procure acessar a URL. Se funcionar, é um ponto positivo;
- Tente configurar a fonte de dados no Orquestra SEM configurar proxy, usuário ou senha. Se funcionar dessa maneira, melhor;
- Se você receber algum erro de conectividade e o acesso a Internet em sua rede é feito via proxy, tente configurar essa conexão na configuração da fonte de dados;
- Use o tipo de autenticação padrão de "Use Global Preferences", caso necessite de autenticação "Pre-emptive" selecione a opção na configuração da fonte de dados;
- Se, ainda assim, não for possível realizar a conexão, será preciso abrir um canal de conversa com a equipe de infraestrutura de TI de sua empresa para compreender porque o servidor do Orquestra não consegue conectar na URL.
Principais configurações
Configurações de autenticação
- Usuário para autenticação: cadastre aqui um usuário de serviço de sua rede, com permissão de navegação dentro da rede da empresa ou da internet, e que fará a conexão com o proxy. É importante que esse usuário seja criado pela TI de sua empresa especialmente para isso; se você cadastrar aqui o seu usuário pessoal e sua senha, é possível que você enfrente problemas no futuro, quando, por exemplo, sua senha expirar. A senha de usuários de serviços não expiram;
- Senha: cadastre aqui a senha do usuário de serviço criado;
- Endereço do proxy: cadastre arquivo o endereço HTTP do seu servidor proxy em sua rede, com a porta de conexão, se necessário;
- Tipo de Autenticação: escolha o tipo de autenticação utilizado pelo serviço;
- Use Global Preferences:Preferencias globais de autenticação do webserserve;
- Authenticate Pre-emptively: Em geral, significa que o servidor espera que as credenciais de autorização sejam enviadas sem fornecer a resposta não autorizada. Reduzindo a carga na rede e no próprio.
Endereço, método e parâmetros
- Endereço de definição do serviço: cadastre aqui a URL que aponta para o WSDL do serviço SOAP que você irá conectar, informada pelo fornecedor do serviço;
- Ler métodos: clique nesse botão para que o Orquestra leia o WSDL informado e procure encontrar os métodos disponíveis. O campo "método" será populado;
- Endereço de endpoint: esse campo, na maioria das vezes, será preenchido automaticamente e será igual ao endereço de definição do serviço. Ele é usado principalmente no caso de serviços onde a documentação do serviço está em uma URL e a execução do serviço está em outra URL;
- Método: após clicar em "Ler métodos", esse campo será preenchido com os métodos de processamento disponíveis. Selecione um;
- SOAP Action: esse campo, na maioria das vezes, será preenchido automaticamente. Ele irá armazenar a assinatura única desse método, caso ele possua uma;
- Envelope: aqui você deverá vincular o "Soap Envelope" de chamada do serviço. O Soap Envelope é um documento XML, no padrão WSDL, específico para o método selecionado. Esse documento geralmente possuirá tokens. Seu formato deverá ser informado na documentação disponibilizada pelo fornecedor do serviço, ou usando um software de mapeamento como SoapUI (gratuito). É possível também Configurar dados de uma tabela multivalorada em uma fonte de dados WSDL/RESTful/JSON
- Ler parâmetros:
- Cabeçalho: no cabeçalho da conexão são, geralmente, enviadas informações adicionais. Aqui também é possível informar um valor novo valor para Content-Type.
Não é necessário utilizar CDATA para a utilização de caracteres especiais em determinadas partes do envelope, o Orquestra BPMS já realiza esse tratamento
- São suportados webservices que utilizem protocolo SOAP desenvolvidos em diversas linguagens, exemplo; C#, Vb.Net, PHP, Java, etc. Para que seja possível ler os métodos e parâmetros dos serviços é necessário que os mesmos exponham um arquivo/url com seu WSDL.
- A partir da versão 3.5 do Orquestra BPM são suportados serviços Windows Communication Foundation (WCF) desde que os mesmos possuam a opção de "singleWsdl" (o serviço a ser chamado dessa forma deverá ter sido desenvolvido em .Net Framework versão 4.5 ou superior).
- Não é possível utilizar webservices que recebam parâmetros na query string, por exemplo: http://servidor/webservice/webservice.aspx?method=Add&WSDL. Exemplo de URL aceita: http://servidor/webservice/webservice.aspx?WSDL.
- Jamais utilize uma atividade de Webservice para concluir ou atualizar automaticamente uma outra atividade da mesma instância de processo usando a API de webservices do Orquestra (http://docs.orquestrabpm.com/bpms/manual/seguro/api/help-webservice-xml.aspx). Isso inclui os métodos FinalizeTask, AttachFile e UpdateForm. Realizar esse tipo de operação, devido a concomitância de acesso aos dados no banco de dados, poderá gerar erros de timeout e deadlock.