Atividade de Webservice / XML

O objeto de Webservice/XML é um poderoso mecanismo de integração do processo com outros sistemas. É um tipo de atividade essencialmente técnica e que deve ser utilizada somente por programadores.

Com esse objeto, é possível:

  1. Executar procedimentos em outros sistemas via Webservices;
  2. Atualizar campos do formulário a partir de consultas a Webservices externos;
  3. Exportar dados do processos (formulários, mensagens, arquivos, etc.) para arquivos XML;
  4. Importar dados para o formulário do processo a partir da leitura de arquivos XML;

Seu cadastro compreende:

  1. Título: o título da tarefa, para identificação;
  2. Descrição: uma breve descrição da tarefa, para referência;
  3. Fonte de dados: escolha o mecanismo que você vai trabalhar para integração: Webservices ou arquivos XML;

Arquivos XML

Uma vez selecionada a opção "Arquivo XML", novas opções serão abertas, como vemos abaixo:

  1. Usuário: digite o nome de usuário de rede (dependendo das configurações da sua rede, será necessário o domínio também, no formato dominio\usuario) que será utilizado para realizar a operação. Essa informação somente será necessária, em se tratando de arquivos XML, se o diretório repositório dos arquivos for protegido e necessitar autenticação. Caso contrário, deixe esse campo em branco;
  2. Senha: digite a senha do usuário acima;
  3. Nome do arquivo: defina aqui o formato/padrão do nome do arquivo que será importado ou exportado. É possível utilizar variáveis do processo, permitindo assim o gerenciamento de múltiplos arquivos. Exemplo:
    1. {Processo.Codigo}.xml
    2. {Requisitante.Codigo}.xml
    3. DadosDoUsuario{Requisitante.Login}.xml
      Se você não utilizar nenhuma variável, o Orquestra BPM irá sempre ler o mesmo arquivo (no caso de importação) ou exportar por cima do mesmo arquivo (no caso de exportação);
  4. Exportar/Importar selecione a opção desejada.
    1. Exportar: nesse caso, o Orquestra BPM irá exportar todos os dados da instância da execução do processo para um arquivo XML. O formato desse arquivo encontra-se na documentação técnica do sistema. Esse arquivo será exportado para o diretório definido na tela de parâmetros do sistema, especificado no parâmetro "XML_EXPORT_PATH";
    2. Importar: nesse caso, o Orquestra BPM irá ler arquivos XML armazenados no servidor e atualizar informações da instância do processo conforme dados do XML. Esse XML, para ser lido, necessita estar em um formato especial, detalhado na documentação técnica do sistema. Para ler o XML, o Orquestra BPM irá buscar o diretório especificado no parâmetro "XML_IMPORT_PATH", no cadastro geral de parâmetros do sistema;

A função de "Exportar" pode ser utilizada, por exemplo, para backup de informações das instâncias do processo ou para posterior integração das informações de instâncias do processo com sistemas legados (através da leitura posterior desses arquivos).

Já a função de "Importar" pode ser utilizada, por exemplo, para carregar dados do formulário com informações vindas de outros sistemas ou de bases de dados, que tenham previamente gerado os arquivos na rede.

Atenção! A função de importação acima não suporta importação de campos para uma tabela multivalorada.

Webservices

Uma vez selecionada a opção "Webservices", novas opções serão abertas, como vemos abaixo:

  1. Usuário: digite o nome de usuário de rede (dependendo das configurações da sua rede, será necessário o domínio também, no formato dominio\usuario) que será utilizado para realizar a operação. Essa informação somente será necessária se o Webservice estiver sido previamente configurado para solicitar autenticação integrada. Caso contrário, deixe esse campo em branco;
  2. Senha: digite a senha do usuário acima;
  3. Nome do webservice: defina aqui a URL completa com o endereço do Webservice. É necessário que o servidor do Orquestra BPM consiga "enxergar" esse endereço, passando por possíveis firewalls ou bloqueios. Clique em "Ler Métodos" para prosseguir.
  4. Método: se o Orquestra BPM conseguiu ler corretamente o Webservice acima, essa lista será automaticamente preenchida com os nomes dos métodos encontrados no serviço. Selecione o método desejado;
  5. Parâmetros: se o Orquestra BPM conseguiu ler corretamente o método o escolhido, serão listados aqui os parâmetros que esse método espera receber. Ao lado de cada parâmetro, um campo texto para digitação. O valor de cada parâmetro poderá ser um texto fixo (ex.: 3653) ou dinâmico (ex.: {Formulario.campo} ou {Processo.Codigo}). Conheça todas as váriveis que podem ser utilizadas. O Orquestra BPM consegue obter os parâmetros do servico em questão se os mesmos forem dos tipos básicos: boolean, int, string. Tipos complexos como classes, objetos e tipos personalizados não são suportados;
  6. Retorno: o último parâmetro (em negrito, e com nome igual ao nome do método selecionado) armazena o retorno do Webservice. Nesse ponto, é obrigatório o uso de uma variável do formulário, para armazenar esse retorno (ex.: {Formulario.retorno}). Observe que, na versão corrente, o Orquestra BPM somente pode armazenar o retorno em UM campo do formulário, e não há recurso para tratamento, 'parse' ou modificação desse retorno antes de seu armazenamento.
    Para que a informação retornada pelo webservice invocado seja gravada na base do sistema ela deve estar em um dos seguintes formatos:
    1. XML com tag "string". Exemplo: <string xmlns="http://docs.orquestrabpm.com/webservices/">231.8</string>;
    2. XML  formato XML padrão do Orquestra;

Caso você queira retornar diversos valores de uma só vez, atualizando diversos campos do formulário, será possível somente se o seu Webservice retornar texto em formato XML padrão do Orquestra. Esse padrão é o mesmo visto no tópico acima, sobre Arquivos XML. Ou seja, se o seu Webservice retornar um XML, no formato padrão, diversos campos poderão ser atualizados.

  1. Aguardar retorno / Não aguardar retorno selecione a opção desejada.
    1. "Após executar o Webservice, prosseguir com o andamento do fluxo": nesse caso, o Orquestra BPM irá executar o Webservice e prosseguir imediatamente com a execução do processo. É a opção padrão;
    2. "Após executar o Webservice, congelar o fluxo e aguardar retorno externo": nesse caso, APÓS o Orquestra BPM executar o seu Webservice, durante a execução de uma instância do processo, o fluxo entrará em "hibernação", ficará parado, congelado. Nesse caso, é indicativo de que a instância desse processo está esperando um estímulo externo para prosseguir. Essa é uma situação muito específica, quando o seu Webservice trabalha com um sistema de "filas". O seu processamento, uma vez requisitado, não ocorre imediatamente, podendo levar minutos, dias ou mesmo horas. Nesse caso, após o processamento, o Orquestra BPM deverá ser estimulado externamente (por um dos Webservices do próprio Orquestra BPM, por exemplo) para poder continuar a execução da instância;
  2. Padrão de mensagens de erro (expressão regular): diferentes webservices possuem diferentes mecanismos e padrões para informar o sistema requisitante que ocorreu um erro tratado. Alguns webservices retornam um XML com informações de erro, outros simplesmente um texto informando o erro. Através desse recurso, você pode cadastrar uma expressão regular que consolide o padrão de mensagens de erro do sistema requisitado. Caso o retorno da chamada do webservice seja capturado por essa expressão regular, o Orquestra irá mostrar uma mensagem de erro para o usuário e impedir a continuidade do processo. No exemplo visto na imagem será apresentada mensagem de erro que estiver contida em um elemento XML "error".

A utilização do recurso de Webservice expande em muito as capacidades de integração do produto.

Num primeiro momento, esse recurso poderia ser usado simplesmente para acionar procedimentos externos, de outros sistemas (exemplo: iniciar o faturamento de um cliente no sistema financeiro).

Pode, também, ser utilizado para enviar informações da execução do processo para um sistema externo (exemplo: enviar dados do requisitante do processo para o cadastro no CRM).

E pode, também, ser utilizado para carregar campos do formulário com dados de outro sistema (exemplo: carregar campo do formulário indicando se o cliente possui crédito ou não, a partir de consulta ao CRM da empresa).

Em todos os casos, é necessário que o sistema a ser conectado possua, ele também, uma camada de Webservices.

Atenção! As requisições WebService podem envolver acesso à Internet. Certifique-se de verificar se o servidor web tem acesso à requisições desse tipo. Requisições através de Proxies não são suportadas.  

Limitações nas URLs dos Webservices

Não é possível utilizar webservices que recebam parâmetros na query string, por exemplo: http://servidor/webservice/webservice.aspx?method=Add&WSDL

Caso seja utilizada a URL acima a tela de configuração da tarefa apresentará mensagem de erro.

Exemplo de URL aceita: http://servidor/webservice/webservice.aspx?WSDL


Exemplo de um processo com o uso de chamada a Webservice

  1. Crie um processo com três elementos: um evento de início, um elemento de webservice, e uma atividade aprovação, conectados um ao outro, nessa ordem.
  2. Crie um formulário eletrônico com 2 campos do tipo "texto", cujos identificadores são: "celsius" e "fahrenheit"
  3. Habilite o campo "celsius" no evento de início do processo
  4. Configure o elemento de webservice para utilizar os seguintes dados:
    1. URL do Webservice: http://www.w3schools.com/webservices/tempconvert.asmx
    2. Método: CelsiusToFahrenheit
    3. Parâmetros Celsius: {Formulario.celsius}
    4. CelsiusToFahren: {Formulario.fahrenheit}
  5. Torne visível os dois campos na atividade de aprovação

Execute o processo. O campo "fahrenheit" deverá ser corretamente preenchido com o correspondente em Celsius digitado na requisição do processo.

Atenção

Jamais utilize um 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/seguro/api/webservices.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.