Árvore de páginas

Versões comparadas

Chave

  • Esta linha foi adicionada.
  • Esta linha foi removida.
  • A formatação mudou.

...

As informações contidas neste documento têm por objetivo demonstrar como realizar a integração entre o fluig TOTVS Fluig Plataforma e aplicativos externos. Para que se tenha uma compreensão completa destas informações, alguns conhecimentos são considerados pré-requisitos, entre eles:

  • Visão geral sobre o produto fluigTOTVS Fluig Plataforma
  • Visão geral sobre integração de sistemas
  • JavaScript
  • WebServices
  • SOAP
  • Datasets (fluigFluig)
  • Java™
  • Apache Flex®

Em várias partes deste documento serão apresentados trechos de códigos em diferentes linguagens de programação, com o intuito de demonstrar o uso das capacidades de integração do fluigFluig Plataforma. Entretanto, este documento não tem por objetivo capacitar o leitor no uso destas tecnologias além do propósito acima descrito, sendo responsabilidade do leitor buscar informações aprofundadas sobre estas linguagens.

...

Com o advento das tecnologias de Sistema da Informação, vários sistemas passaram a dar apoio a estes processos de negócio, especialmente aqueles considerados mais críticos para a operação da empresa. O melhor exemplo disto é a adoção dos sistemas de ERP que dão suporte aos processos de várias áreas da empresa.

O fluig Fluig tem como objetivo ser uma plataforma agnóstica de gestão de processos, documentos e identidades através de uma interface de comunicação colaborativa. Isto pode ser percebido em maior ou menor grau em cada uma das suas funcionalidades, desde as mais simples (como colaboração) até as mais complexas (como BPM).

Entretanto, parte destes processos têm alta dependência dos sistemas de informação já existentes na empresa e, por isso, a arquitetura do fluig da plataforma Fluig é planejada para permitir integrar-se a estes sistemas, possibilitando que os processos modelados tenham maior valor agregado.

O fluig Fluig permite tanto o acesso pelo produto aos sistemas externos (para consultar ou alimentar informações), bem como aceita que outros sistemas venham a conectar-se para a consulta de informações ou para execução de operações transacionais.

...

O principal canal de integração da plataforma é através de WebServices, que vêm se tornando o padrão mais comum de integração com qualquer aplicativo. Através deles, é possível ter acesso às funcionalidades do fluig Fluig Plataforma e dar acesso à aplicativos externos. Este documento dedica uma seção específica sobre integração via WebServices.

...

A integração via WebServices utiliza o protocolo SOAP e, por ser um padrão aberto, permite que sistemas desenvolvidos em plataformas totalmente diferentes como Java™, Microsoft® .Net, C, C++, PHP, Ruby, Pearl, Python, entre outras, possam trocar informações entre si de forma transparente.

...

...

O serviço SOAP será depreciado a partir da atualização 1.6.5. A recomendação é utilizar a API REST.

Acessando os WebServices do

...

TOTVS Fluig Plataforma

O fluig Fluig disponibiliza um conjunto de WebServices que permitem o acesso às informações da plataforma ou a execução de tarefas, como iniciar solicitações de processos por exemplo. Para ter a lista dos WebServices disponíveis, acesse o endereço: 

...

Nota

Atente para cada tipo de atributo que é esperado, por exemplo, o atributo expirationDate do objeto DocumentDto[] é uma data, porém cada linguagem interpreta de maneira diferente, veja alguns exemplos abaixo:

  • C#: dateTime
  • Java™: XMLGregorianCalendar
  • Progress®: DATETIME-TZ


Via Apache Flex®

Como a grande maioria das ferramentas de desenvolvimento, o Apache Flex® permite criar stubs para o acesso a WebServices. Estes stubs encapsulam todas as operações de empacotamento e desempacotamento das informações do padrão XML para os tipos nativos da plataforma.

Utilize o passo-a-passo para visualizar o processo de criação dos stubs para um serviço disponibilizado pelo fluigFuig Plataforma:

Deck of Cards
historyfalse
idstubFlex
Card
defaulttrue
effectDuration0.5
id1
label1º Passo
effectTypefade

A criação dos stubs no Flex® é feito através do menu Data, opção > Import WebService(WSDL), conforme a imagem abaixo.

Card
effectDuration0.5
id2
label2º Passo
effectTypefade

Na primeira janela, é solicitada a pasta dentro do projeto corrente onde devem ser gerados os stubs.

Card
effectDuration0.5
id3
label3º Passo
effectTypefade

Na tela a seguir, deve ser informado o endereço do WSDL onde se encontra o serviço. Também é possível definir se ele será acessado da estação cliente ou do servidor LifeCycle Data Services.

Card
effectDuration0.5
id4
label4º Passo
effectTypefade

Na última tela, deve-se informar o package que será utilizado e qual o nome da classe principal (já sugeridos pelo Flex™ Builder™).

Card
effectDuration0.5
id5
labelResultado
effectTypefade

Uma vez finalizado o processo, o Flex™ Builder™ adicionará ao projeto um conjunto de classes que serão utilizadas pelo programador para invocar os serviços, conforme a figura abaixo:

...

O trecho de código abaixo apresenta um exemplo de invocação do WebService de acesso aos Datasets do fluig da plataforma Fluig:

Bloco de código
languageactionscript3
themeEclipse
firstline1
titleECMDatasetServiceClient.mxml
linenumberstrue
<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute" creationComplete="{this.start()}">
	<mx:Script>
		<![CDATA[
			import generated.webservices.ValuesDto;
			import generated.webservices.DatasetDto;
			import generated.webservices.GetDatasetResultEvent;
			import generated.webservices.SearchConstraintDtoArray;
			import generated.webservices.StringArray;
			import generated.webservices.ECMDatasetServiceService;
			import mx.rpc.events.FaultEvent;
			import mx.collections.ArrayCollection;
		
			//Cria uma instância do Stub de acesso ao serviço
			private var ds:ECMDatasetServiceService = new ECMDatasetServiceService();

			public function start() : void {

				//Cria tipos auxiliares, que serão utilizados na chamado do serviço
				var fields:StringArray = new StringArray();
				var constraints:SearchConstraintDtoArray = new SearchConstraintDtoArray();
				var order:StringArray = new StringArray();

				//Define as funções para tratamento do retorno
				ds.addEventListener(GetDatasetResultEvent.GetDataset_RESULT, resultGetDataset);
				ds.addEventListener(FaultEvent.FAULT,faultGetDataset);
				
				//invoca o método getDataset do serviço
				ds.getDataset("adm", 1, "adm", constraints, order, fields, "colleague");
			}
			
			//Tratamento dos dados retornados do serviço invocado.
			public function resultGetDataset(ev:GetDatasetResultEvent) : void {

				//Recupera o retorno do serviço, na forma de um DatasetDto
				var dataset:DatasetDto = ev.result as DatasetDto;

				//Monta uma string com todos os dados do dataset
				var line:String = "";
				
				//Cabeçalho com o nome dos campos
				var columnsArray:ArrayCollection = new ArrayCollection(dataset.columns);
				for (var j:int = 0; j < columnsArray.length; j++) {
					line += columnsArray.getItemAt(j) + "\t";
				}

				//Linha de dados
				var valuesArray:ArrayCollection = new ArrayCollection(dataset.values);
				for (var j:int = 0; j < valuesArray.length; j++) {
					var row:ValuesDto = valuesArray.getItemAt(j) as ValuesDto;
					line += "\n" + j + ":";
					
					for (var i:int = 0; i < row.length; i++) {
						line += row.getItemAt(i) + "\t";
					}
				}
				
				//Mostra a string criada em um textarea na tela
				this.sysout.text = line;
			}
			
			public function faultGetDataset(ev:FaultEvent) : void {
				this.sysout.text = ev.fault.faultString;
			}
		]]>
	</mx:Script>
	<mx:TextArea id="sysout" name="sysout" width="100%" height="100%" 
		paddingBottom="5" paddingLeft="5" paddingRight="5" paddingTop="5"/>
</mx:Application>
Nota

Existe um bug do Flex® que impede o funcionamento correto de serviços que trabalhem com matrizes multidimensionais de dados, como no exemplo acima, onde é retornado um array (de linhas do Dataset) de array (das colunas de cada registro).

Para contornar este problema, é preciso alterar a classe gerada pelo Flex™ Builder™ que irá encapsular o array multidimensional. No exemplo acima, este esta classe é a DatasetDto, que deverá ser alterada (linha 11) conforme o exemplo abaixo:

Bloco de código
languageactionscript3
themeEclipse
firstline1
linenumberstrue
public class DatasetDto
{
	/**
	 * Constructor, initializes the type class
	 */
	public function DatasetDto() {}
            
	[ArrayElementType("String")]
	public var columns:Array;
	[ArrayElementType("ValuesDto")]
	public var values:Array = new Array(); //iniciando o array
}

Outros serviços que não trabalhem com arrays multidimensionais não exigem alterações no código gerado.


Via Java™

Existem muitas implementações de uso de WebServices em Java™ e neste exemplo vamos utilizar as bibliotecas disponíveis no Java™ 7.

...

Nota

Ao utilizar os WebServices via Java™, deve-se atentar para o tipo de cada atributo e para o tipo de retorno do WebService. Por exemplo, para valores do tipo data deve ser utilizado a classe XMLGregorianCalendar:

Bloco de código
languagejava
themeEclipse
firstline1
linenumberstrue
DocumentDto document = new DocumentDto();

XMLGregorianCalendar date = DatatypeFactory.newInstance().newXMLGregorianCalendar();
date.setYear(2013);
date.setMonth(10);
date.setDay(16);
date.setHour(0);
date.setMinute(0);
date.setSecond(0);

document.setExpirationDate(date);


Via Progress® 4GL

Assim como nos exemplos anteriores, o primeiro passo para consumir um WebService em Progress® é usar um utilitário que irá ler o endereço WSDL e gerar as informações necessárias para acessá-lo. Diferente do Java™ e Flex®, o Progress® não gera objetos de stub, mas apenas uma documentação sobre como consumir os serviços descritos no arquivo WSDL. Embora em algumas situações seja possível manipular os tipos nativos do Progress® como parâmetros, dependendo do tipo de dado utilizado é preciso manipular o XML SOAP para extrair ou enviar uma informação.

...

Bloco de código
languagejavafx
themeEclipse
firstline1
titlewsECMDatasetService.p
linenumberstrue
/* Parte I - Invocar o WebService */
DEFINE VARIABLE hWebService     AS HANDLE NO-UNDO.
DEFINE VARIABLE hDatasetService AS HANDLE NO-UNDO.

DEFINE VARIABLE cFields  AS CHARACTER EXTENT 0 NO-UNDO.
DEFINE VARIABLE cOrder   AS CHARACTER EXTENT 0 NO-UNDO.
DEFINE VARIABLE cDataset AS LONGCHAR NO-UNDO.

DEFINE TEMP-TABLE item NO-UNDO
    NAMESPACE-URI ""
    FIELD contraintType AS CHARACTER
	FIELD fieldName     AS CHARACTER
	FIELD finalValue    AS CHARACTER
	FIELD initialValue  AS CHARACTER.
 
DEFINE DATASET dConstraints NAMESPACE-URI "http://ws.dataservice.ecm.technology.totvs.com/"
	FOR item.

CREATE SERVER hWebService.
hWebService:CONNECT("-WSDL 'http://localhost:8080/webdesk/ECMDatasetService?wsdl'").
RUN DatasetService SET hDatasetService ON hWebService.

RUN getDataset IN hDatasetService(INPUT 1,
                                  INPUT "adm",
                                  INPUT "adm",
                                  INPUT "colleague",
                                  INPUT cFields,
                                  INPUT DATASET dConstraints,
                                  INPUT cOrder,
                                  OUTPUT cDataset).

DELETE OBJECT hDatasetService.
hWebService:DISCONNECT().
DELETE OBJECT hWebService.

/* Parte II - Faz o parser do XML e criar um arquivo texto separado por tabulacao */
DEFINE VARIABLE iCount  AS INTEGER   NO-UNDO.
DEFINE VARIABLE iCount2 AS INTEGER   NO-UNDO.
DEFINE VARIABLE hDoc    AS HANDLE    NO-UNDO.
DEFINE VARIABLE hRoot   AS HANDLE    NO-UNDO.
DEFINE VARIABLE hValues AS HANDLE    NO-UNDO.
DEFINE VARIABLE hEntry  AS HANDLE    NO-UNDO.
DEFINE VARIABLE hText   AS HANDLE    NO-UNDO.
DEFINE VARIABLE cValue  AS CHARACTER NO-UNDO.

OUTPUT TO c:\dataset.txt.

CREATE X-DOCUMENT hDoc.
CREATE X-NODEREF hRoot.
CREATE X-NODEREF hEntry.
CREATE X-NODEREF hText.
CREATE X-NODEREF hValues.

hDoc:LOAD("longchar", cDataset, FALSE).
hDoc:GET-DOCUMENT-ELEMENT(hRoot).

/* Percorre as colunas <columns> */ 
DO iCount = 1 TO hRoot:NUM-CHILDREN WITH 20 DOWN:
    hRoot:GET-CHILD(hEntry, iCount).
    IF hEntry:NAME <> "columns" THEN
        NEXT.

    hEntry:GET-CHILD(hText, 1).
    PUT UNFORMATTED hText:NODE-VALUE "~t".
    DOWN.
END.
PUT UNFORMATTED SKIP.

/* Percorre os registros <values> */
DO iCount = 1 TO hRoot:NUM-CHILDREN WITH 20 DOWN:
    hRoot:GET-CHILD(hValues, iCount).
    IF hValues:NAME <> "values" THEN
        NEXT.

    /* Percorre os campos <value> */
    DO iCount2 = 1 TO hValues:NUM-CHILDREN:
        hValues:GET-CHILD(hEntry, iCount2).

        IF hEntry:NUM-CHILDREN = 0 THEN
            cValue = "".
        ELSE DO:
            hEntry:GET-CHILD(hText, 1).
            cValue = hText:NODE-VALUE.
        END.
        PUT UNFORMATTED cValue "~t".
    END.

    PUT UNFORMATTED SKIP.
END.

OUTPUT CLOSE.

DELETE OBJECT hValues.
DELETE OBJECT hText.
DELETE OBJECT hEntry.
DELETE OBJECT hRoot.
DELETE OBJECT hDoc.

Acessando WebServices a partir do

...

TOTVS Fluig Plataforma

A plataforma O fluig permite fazer chamadas a WebServices de terceiros através do cadastro de Serviços na Visualização de Serviços do fluig Studio Fluig Studio.

Nota
titleAtenção

Para que um usuário que não é administrador da empresa possa criar, editar e remover serviços é necessário que ele possua a permissão "Configurar Serviços". Esta permissão pode ser concedida pelo administrador através do item "Permissões" disponível na aba "Gerais" do no agrupador Pessoas do Painel de Controle do fluig da plataforma Fluig.

Saiba como realizar esse procedimento clicando aqui.

Para adicionar um novo WebService, é preciso clicar na opção Incluir Serviço, abrindo o assistente Novo Serviço, e informar o servidor do fluig Fluig onde será adicionado o serviço, um código identificador para ele, sua descrição, a URL para o WSDL e o seu tipo (neste caso WebService). No exemplo abaixo, será utilizado um WebService público para consulta à tabela periódica, cujo endereço do WSDL é http://www.webservicex.com/periodictable.asmx?wsdl.

...

Com base nestas informações, o fluig a plataforma Fluig irá extrair as informações sobre o WebService informado e finalizará o cadastro deste serviço. 

Uma vez que o serviço esteja cadastrado, é possível visualizar as classes e métodos disponíveis neste serviço e que serão utilizados nos códigos JavaScript que farão uso do mesmo. A tela abaixo apresenta um exemplo de visualização de WebService.

Os serviços adicionados no fluig podem na plataforma podem ser instanciados e utilizados nos pontos onde o produto permite personalização utilizando-se JavaScript, como nos scripts para eventos globais, eventos de processos, eventos de definição de formulário ou Datasets. No exemplo a seguir, será criado um Dataset que fará uso deste serviço para trazer os dados da tabela periódica.

...

O primeiro passo para invocar o serviço é solicitar ao fluig à plataforma Fluig que carregue-o serviço, a partir do método ServiceManager.getService('PeriodicTable'). O valor passado como parâmetro, deve ser o código utilizado quando cadastrado o serviço.

...

  • Passo 1: Instanciar a classe net.webservicex.Periodictable para ter acesso ao localizador do serviço; 

  • Passo 2: Invocar o método getPeriodictableSoap para instanciar o serviço;
  • Passo 3: Invocar o método getAtoms para ter a lista dos elementos.

...

Bloco de código
languagejavascript
themeEclipse
firstline1
titleperiodicTable.js
linenumberstrue
		//Servico "<url_fluig>/webdesk/ECMCardService?wsdl"cadastrado com o código "CardService"
        var cardServiceProvider = ServiceManager.getServiceInstance("CardService");
        var cardServiceLocator = cardServiceProvider.instantiate("com.totvs.technology.ecm.dm.ws.ECMCardServiceServiceLocator");
        var cardService = cardServiceLocator.getCardServicePort();
        var cardFieldDtoArray = cardServiceProvider.instantiate("com.totvs.technology.ecm.dm.ws.CardFieldDtoArray");
        var cardField = cardServiceProvider.instantiate("com.totvs.technology.ecm.dm.ws.CardFieldDto");
     
        //Seta valor no campo com name = 'nome'
        cardField.setField("nome");
        cardField.setValue("Valor alterado via WS dentro de um evento workflow");
 
        var vetCardFields = new Array();
        vetCardFields.push(cardField);
        cardFieldDtoArray.setItem(vetCardFields);
     
        //Altera o(s) campo(s) do registro de formulário.
        //updateCardData(tenantId, login, senha, codRegistroForm, cardFieldDtoArray);
        cardService.updateCardData(1, "adm", "adm", 8, cardFieldDtoArray);


WebServices com Autenticação Básica
Nota
titleAtenção

Esta opção é válida apenas para serviços criados utilizando a API CXF.

WebServices com Autenticação Básica no acesso ao WSDL

Para criar serviços de WebServices que utilizam Autenticação Básica no acesso ao seu WSDL, é necessário marcar a opção Requer Autenticação no cadastro de serviços do fluigFluig Plataforma, conforme exemplo abaixo:

...

Para finalizar o cadastro será apresentada a janela para autenticação abaixo:

Consumindo WebServices com Autenticação Básica

Para consumir WebServices que fazem uso de autenticação básica, é necessário utilizar o método getBasicAuthenticatedClient localizado no provider do serviço (o mesmo que é obtido via ServiceManager). Este método disponibiliza um client autenticado.

...

Bloco de código
languagejavascript
themeEclipse
firstline1
linenumberstrue
var serviceLocator = serviceHelper.instantiate('net.webservicex.Periodictable');
var service = serviceLocator.getPeriodictableSoap();
var authenticatedService = serviceLocator.getPeriodictableSoap();
var authenticatedService serviceHelper.getBasicAuthenticatedClient(service, "net.webservicex.PeriodictableSoap", 'usuario', 'senha');
var result = authenticatedService.getAtoms();



Nota
titleAtenção

Os métodos estáticos não podem ser chamados através de uma instância de objeto. Portanto, é necessário utilizar o método "serviceHelper.instantiate" para criar uma instância do objeto e atribuir um valor, sendo necessário informar como parâmetros o nome da classe, o método da classe, o tipo do valor e o próprio valor. Veja o exemplo a seguir:

Exemplo com Instantiate:
Bloco de código
languagejavascript
themeEclipse
firstline1
linenumberstrue
// Obtém a instância do serviço 'WorkflowEngineService'
var workflowEngineServiceProvider = ServiceManager.getServiceInstance("WorkflowEngineService");

// Instância o serviço
var workflowEngineServiceLocator = workflowEngineServiceProvider.instantiate("com.totvs.technology.ecm.workflow.ws.ECMWorkflowEngineServiceService");
var workflowEngineService = workflowEngineServiceLocator.getWorkflowEngineServicePort();

// Instância objeto de Array de anexos
var processAttachmentDtoArray = workflowEngineServiceProvider.instantiate("com.totvs.technology.ecm.workflow.ws.ProcessAttachmentDtoArray");

//Exemplo executeStaticMethod:

// Obtém a instância do serviço 'wsTerceiro'
var periodicService = ServiceManager.getServiceInstance("wsTerceiro");
// Instancia o serviço
var serviceHelper = periodicService.getBean();
var serviceLocator = periodicService.instantiate("br.com.webformat.webservices.Retorno");
var service = serviceLocator.getRetornoSoap();

// Neste caso, é preciso autenticar no ws
var authService = serviceHelper.getBasicAuthenticatedClient(service, "br.com.webformat.webservices.RetornoSoap", usuario, senha);

// Faz a chamada do método para criar o Enum
var loadStatus = serviceHelper.getBasicAuthenticatedClient(service, "net.webservicex.PeriodictableSoap", 'usuario', 'senha');
var result = authenticatedService.getAtoms(executeStaticMethod("br.com.webformat.webservices.LoadStatus", "fromValue", ["java.lang.String"], [pLoadStatus]);

//Chamada do ws
var response = authService.sendLoadStatusItem(pWsKey, pErpCode, loadStatus, pDescription, pCodSolicitacao);

WebService com client personalizado
Nota
titleAtenção

Esta técnica é válida para o fluig TOTVS Fluig Plataforma 1.3.7 ou superior.

Em integrações que utilizem serviços criados com o CXF com sistemas que não suportam o protocolo HTTP/1.1 (Protheus, por exemplo), é necessário utilizar este método configurando o parâmetro "disable.chunking" com o valor "true".

...

Nota
titleImportante

O tempo de timeout de requisição padrão do fluig da plataforma deveria ser suficiente para a realização de uma integração convencional. Antes de aumentar o tempo de timeout de integrações do fluig da plataforma Fluig verifique o fato que levou a esta decisão.

Por exemplo, revise códigos e dimensionamento do servidor que recebe as integrações. Otimizações de códigos podem reduzir o tempo necessário para realizar uma transação e oferecer as pessoas que utilizam o fluig a plataformacFluig uma navegação mais fluida.

Resolvendo conflitos utilizando arquivos de bind JAXB
Nota
titleAtenção

Esta técnica é válida apenas para serviços criados utilizando a API CXF.

Ao criar serviços no fluig Fluig Plataforma podem ocorrer alguns conflitos impedindo a geração dos stubs. Normalmente isso ocorre quando temos um elemento do schema do WSDL com duas ou mais propriedades com o mesmo identificador ou nome, o que impede a criação da Classe Java desse elemento.

...

Esse arquivo tem o propósito de personalizar a geração dos stubs alterando o nome das propriedades conflitantes.


  • A seguir temos dois exemplos de utilização desses arquivos:


Exemplo 1 :

Durante a criação do serviço ocorreu o seguinte erro :

...

Nota
titleImportante

Além de WebServices o fluig Fluig também pode realizar chamadas Progress. Entretanto essa técnica está descontinuada, e nossa recomendação é usar a API RESTserviços SOAP.

Caso seu projeto já utilize essa técnica acesse a documentação depreciada.


Integrações Assíncronas em Solicitações

...