Índice

Considerações Gerais 

As informações contidas neste documento têm por objetivo demonstrar como é feita a integração entre o TOTVS | ECM 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 TOTVS | ECM

...

Com o intuito de facilitar o entendimento das informações apresentadas e a simulação dos conceitos apresentados, os exemplos citados neste documento utilizam a funcionalidade de Datasets como exemplo de uso das capacidades de integração do produto. Entretanto, é importante ressaltar que outros pontos do produto possuem disponíveis as mesmas características de integração existentes nos Datasets, em especial as customizações de processos e fichários. 

Visão Geral

Ainda que empíricos, toda empresa possui processos de negócios que permitem à empresa cumprir o seu objetivo, seja ele a prestação de um serviço, a produção de bens materiais ou o comércio de mercadorias. Uma empresa possui uma infinidade de processos, sendo que cada pessoa na organização obrigatoriamente participa em pelo menos um destes processos, e todos eles trocam informações entre si em algum momento. Os processos podem ser formais (como a contratação de um profissional) ou informais (como um incentivo à inovação), críticos (faturamento) ou satélites (controle de envio de cartões de aniversários).

...

A outra forma de integração é via chamadas ao Progress® Open AppServer e é indicada para usuários que precisem integrar o TOTVS | ECM com aplicativos desenvolvidos nesta plataforma. 

WebServices

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

...

Para ter uma lista dos processos disponíveis, abra o navegador no endereço http://<host>:<porta>/webdesk/services.

Cada link apresentado direciona o browser para a URL do WSDL do serviço. O WSDL (Web Service Description Language) possui a descrição do serviço no formato XML e é utilizado pelas ferramentas de desenvolvimento para a criação dos componentes que representarão este serviço.

...

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

A criação dos stubs no Flex™ é feito no menu Data, Opção Import WebService (WSDL), conforme a imagem abaixo.

...

Figura 3 - Flex Builder - Definindo pasta de destino

...

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.

Figura 4 - Flex Builder - Informando o WSDL

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

...

Figura 6 - Objetos gerados pelo Flex Builder

O trecho de código abaixo apresenta um exemplo de invocação do WebService de acesso aos Datasets do TOTVS | ECM.

<?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.DatasetServiceService;
import mx.rpc.events.FaultEvent;
import mx.collections.ArrayCollection;
/* Cria uma instância do Stub de acesso ao serviço */
private var ds:DatasetServiceService = new DatasetServiceService();
/* Cria tipos auxiliares, que serão utilizados na chamado do serviço */
private var fields:StringArray;
private var constraints:SearchConstraintDtoArray;
private var order:StringArray;
private var search:SearchConstraintDtoArray;
private var columnsArray:ArrayCollection;
private var valuesArray:ArrayCollection;
public function start() : void {
/* Busca dataset especifico */
fields = new StringArray();
constraints = new SearchConstraintDtoArray();
order = new StringArray();
/* Define as funções para tratamento do retorno */
ds.addEventListener(GetDatasetResultEvent.GetDataset_RESULT, resultGetDataset);
ds.addEventListener(FaultEvent.FAULT,faultGetDataset);
ds.getDataset(1, /* Empresa */
"adm", /* Usuario */
"adm", /* Senha */
"estados", /* Nome Dataset */
fields, /* Campos a Retornar */
constraints, /* Condições de busca */
order); /* Campos p/ Ordenação */
}
// 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;
/* Determina o número de colunas e linhas do dataset */
columnsArray = new ArrayCollection(dataset.columns);
valuesArray = new ArrayCollection(dataset.values);
/* Monta uma string com todos os dados do dataset */
var line:String = "";
/* Cabeçalho com o nome dos campos */
for (var j:int=0; j<columnsArray.length; j++) {
line = line + columnsArray.getItemAt(j) + "\t";
}
line = line + "\n";
/* Linha de dados */
for (var j:int=0;j<valuesArray.length;j++) {
var row:ValuesDto = valuesArray.getItemAt(j) as ValuesDto;
line = line + j + ":";
for (var i:int=0;i<row.length;i++) {
line = line + row.getItemAt(i) + "\t";
}
line = line + "\n";
}
/* 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>

...

Aviso: Existe um bug do Adobe® 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).

...

wsimport -d <output_directory >

Através deste comando são gerados os stubs no diretório de destino (output_directory), conforme a descrição do arquivo wsdl (wsdl_url).

...

Figura 8 - Exemplo de Documentação do WebService gerada pelo Progress

...

/* Parte I – Invocar o WebService */
DEFINE VARIABLE hWebService AS HANDLE NO-UNDO.
DEFINE VARIABLE hDatasetService AS HANDLE NO-UNDO.
DEFINE VARIABLE companyId AS INTEGER NO-UNDO.
DEFINE VARIABLE username AS CHARACTER NO-UNDO.
DEFINE VARIABLE password AS CHARACTER NO-UNDO.
DEFINE VARIABLE name AS CHARACTER NO-UNDO.
DEFINE VARIABLE fields1 AS CHARACTER EXTENT 0 NO-UNDO.
DEFINE TEMP-TABLE item NO-UNDO
NAMESPACE-URI ""
FIELD fieldName AS CHARACTER
FIELD finalValue AS CHARACTER
FIELD initialValue AS CHARACTER .
DEFINE DATASET constraints NAMESPACE-URI "http://ws.dataservice.webdesk.technology.datasul.com/"
FOR item.
DEFINE VARIABLE order AS CHARACTER EXTENT 0 NO-UNDO.
DEFINE VARIABLE dataset1 AS LONGCHAR NO-UNDO.
CREATE SERVER hWebService.
hWebService:CONNECT("-WSDL 'http://norberto.datasul.net:8080/webdesk/DatasetService?wsdl'").
RUN DatasetService SET hDatasetService ON hWebService.
/* Procedure invocation of getDataset operation. */
RUN getDataset IN hDatasetService(INPUT 1,
INPUT "joyce",
INPUT "adm",
INPUT "colleague",
INPUT fields1,
INPUT DATASET constraints,
INPUT order,
OUTPUT dataset1).
DELETE OBJECT hDatasetService.
hWebService:DISCONNECT().
DELETE OBJECT hWebService.
/* Parte II - Faz o parser do XML e criar um arquivo 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:\temp\saida.txt.
CREATE X-DOCUMENT hDoc.
hDoc:LOAD("longchar", dataset1, FALSE).
CREATE X-NODEREF hRoot.
hDoc:GET-DOCUMENT-ELEMENT(hRoot).
CREATE X-NODEREF hEntry.
CREATE X-NODEREF hText.
CREATE X-NODEREF hValues.
/* Percorre as colunas primeiro */
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.

...

Via PHP

Para utilizar a integração com o PHP, primeiramente deve ser definido a estrutura DTO utilizado no WebService desejado, como um objeto array. Por exemplo, para utilizar SearchConstraintDto a seguinte estrutura deve ser utilizada no PHP:

$constraint = array("contraintType"=>"MUST", "fieldName"=>"<Valor do Campo>", "initialValue"=>"<Valor inicial>", "finalValue"=>"<Valor final>");
$constraintsDto = array("item"=>$constraint);

...

Um exemplo completo de utilização esta disponível no diretório <Diretório de instalação> \docs-ECM\Documentos de Customizacao\Arquivos Adicionais\Exemplos Webservices\ExemplosDatasetService\PHP\ getColleagueDataset.php

...

O TOTVS | ECM permite fazer chamadas a WebServices de terceiros através do cadastro de Serviços, no Painel de Controle.

Figura 9 - Cadastro de Serviços, no Painel Controle

...

Para adicionar um novo WebService, é preciso entrar na opção Adicionar e informar um nome para o serviço, o seu tipo (neste caso WebService), a sua descrição e a URL para o WSDL. No exemplo abaixo, será utilizado um WebService público para consulta à tabela periódica, cujo endereço do WSDL é http://www.webdtservicex.com/periodictable.asmx?wsdl.

...

É necessário que o servidor esteja no mesmo domínio do servidor proxy. 

Figura 10 - Cadastro do WebService

...

Com base nestas informações, o TOTVS | ECM 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. 

Figura 11 - Visualizando Classes e métodos do Serviço

A partir do cadastro do serviço, é possível instanciá-lo nos pontos onde o TOTVS | ECM é customizado utilizando-se JavaScript, como nos eventos de fichários, processos, ou no cadastro de Datasets. No exemplo a seguir, será criado um dataset que fará uso deste serviço para trazer os dados da tabela periódica. Para mais informações sobre o uso de datasets no TOTVS | ECM e como criar Datasets customizados, verifique a documentação técnica do produto.

...

function createDataset(fields, constraints, sortFields) {
// Cria o dataset
var newDataset = DatasetBuilder.newDataset();
newDataset.addColumn("ElementName");
// Conecta o servico e busca os livros
var periodicService = ServiceManager.getService('PeriodicTable');
var serviceHelper = periodicService.getBean();
var serviceLocator = serviceHelper.instantiate('NET.webserviceX.www.PeriodictableLocator');
var service = serviceLocator.getperiodictableSoap();
// Invoca o servico
try {
var retorno = service.getAtoms();
var NewDataSet = new XML(retorno);
for each(elemento in NewDataSet.Table) {
newDataset.addRow(new Array(elemento.ElementName.toString()));
}
} catch(erro) {
newDataset.addRow(new Array(erro.message));
}
return newDataset;
}

...

O primeiro passo para invocar o serviço é solicitar do TOTVS | ECM que faça a carga do serviço, a partir do método ServiceManager.getService('PeriodicTable'). O nome passado como parâmetro, deve ser o mesmo nome utilizado no cadastro do Serviço, no Painel de Controle.

...

Observe na tabela abaixo, os passos exigidos pelo serviço da tabela periódica e como foi criado o código do dataset.

No caso deste serviço, o método getAtoms retorna uma string contendo um XML com a lista de todos os elementos, conforme o exemplo abaixo:

<NewDataSet>
<Table>
<ElementName>Actinium</ElementName>
</Table>
<Table>
<ElementName>Aluminium</ElementName>
</Table>
…..
</NewDataSet>

Para percorrer o XML e extrair o dados disponíveis, são utilizadas as funcionalidades de tratamento de XML do JavaScript que facilita a manipulação de dados deste tipo. Para mais informações sobre esta funcionalidade, acesse:

...

var NewDataSet = new XML(retorno);
for each(elemento in NewDataSet.Table) {
newDataset.addRow(new Array(elemento.ElementName.toString()));
}

Uma vez implementado o código do dataset, é possível visualizá-lo, conforme
a figura abaixo.

Figura 12 - Exemplo de dataset que utiliza um WebService

...

Progress® Open AppServer

Assim como é possível invocar operações em WebServices, o TOTVS | ECM também permite fazer chamadas a programas em Progress® 4GL (ou ABL) expostos via Progress® Open AppServer.

...

Para os três primeiros casos, a lógica de extração das informações desejadas será exposta em um programa com várias procedures, uma para cada necessidade aqui apresentada.

1 Os exemplos utilizam uma base dedados do EMS2 para consulta de centros de custo e usuários. Entretanto, apenas duas tabelas e 6 campos são utilizados no total, o que não deve prejudicar o entendimento da lógica pelo leitor, nem impedir a criação de um esquema equivalente para testes, caso necessário.

2 O código apresentado para extração dos centros de custo tem fins meramente didáticos e não pode ser considerado para uso em produção. Para ter mais informações sobre como extrair centros de custos do EMS2, consulte a documentação técnica do mesmo.

...

No caso da extração de usuários comuns aos dois produtos, será utilizado um programa único, conforme o código abaixo:

Os dois códigos apresentados têm diferenças significativas na forma como são utilizados e na forma como serão expostos pelo Progress®. No primeiro, o programa é carregado de forma persistente e suas procedures podem ser executadas de forma independente. No segundo caso, o programa é executado de forma não-persistente e a lógica principal se encontra no main-block. As procedures internas, caso existam, têm por objetivo melhorar a organização do código e não podem ser utilizadas de forma isolada.

...

Figura 13 - ProxyGen -Nome do Projeto

...

Na primeira tela do ProxyGen o principal ponto que deve ser observado é o nome do Projeto (no exemplo acima, EMSProxies). A informação deste campo será utilizada pelo ProxyGen para nomear a classe de acesso ao serviço, e que será utilizada na configuração do serviço no TOTVS | ECM. Nesta tela também é preciso configurar o PROPATH corretamente, para que seja possível encontrar os arquivos compilados (.r).

3 Note que dependendo da versão do Progress®, as telas podem sofrer alguma variação na quantidade e disposição dos campos. Consulte a documentação em caso de dúvida.

...

Figura 15 - ProxyGen -Configurando nome do Serviço

...

Durante o processo de geração dos proxies, observe o campo AppService. Este deve ser o nome do serviço que deve ser publicado no AppServer, caso contrário não será possível conectar o servidor.

Figura 16 - ProxyGen -Definindo o package das classes

...

A última informação relevante para a geração dos proxies é o nome do pacote (package) onde as classes serão criadas. Esta informação é utilizada durante a configuração do serviço Progress® no TOTVS | ECM.

...

 jar -cvf <jar_file_name> <diretório>

...

Observe apenas que no arquivo gerado, é preciso que as classes estejam nos diretórios corretos. No exemplo acima, o diretório com deve ser incluído e estar no raíz do arquivo Jar.

...

Para configurar o ambiente Progress® no TOTVS | ECM, é preciso identificar quais os arquivos .JAR que são exigidos para a execução dos proxies. A tabela abaixo apresenta o conjunto padrão de arquivos para as versões 9 e 10, embora ela possa sofrer variações dependendo do ambiente do usuário. Verifique a documentação do Progress® em cada versão para mais detalhes.

...

ATENÇÃO: O conjunto de arquivos deve também ser copiado para a pasta <ECM>\server\default\lib. É necessário parar o serviço antes de efetuar a cópia e reiniciá-lo em seguida.

...

Para configurar um ambiente Progress®, acesse no painel de controle a opção “Ambientes Progress”, conforme a imagem abaixo: 

Figura 17 - Tela de Configuração dos Ambientes Progress

...

Onde:

• Código do Serviço: Código pelo qual o ambiente será identificado. Ex.: dlc101a, dlc91e, etc.

...

O cadastrado de um serviço é feito no Painel de Controle, na opção Serviços. A tela abaixo apresenta os campos utilizados para o cadastro do Serviço Progress®.

Figura 18 - Tela de cadastro do Serviço Progress  

Onde:

• Nome do Serviço: Nome único que irá identificar o serviço no sistema. Este nome será utilizado nos códigos JavaScript para ter acesso a este serviço
• Descrição: Texto que descreve o serviço de dados.
• URL do Serviço: Identifica a URL de acesso ao serviço AppServer, como por exemplo AppServer://<servidor>/<nome_serviço>.

...

Figura 20 - Visão geral de Classes

...

Onde:

• Script Code: é o código em JavaScript que fará uso das procedures expostas no AppServer. Como mencionado anteriormente, este JavaScript pode ser de qualquer natureza, como a implementação de um Dataset ou a customização de um Workflow.

...

function createDataset(fields, constraints, sortFields) {
// Passo 1 - Recupera o serviço cadastrado no Painel de Controle
var servico = ServiceManager.getService("ems2_v10");
// Passo 2 - Carrega o objeto utilitário para integração com Progress
var serviceHelper = servico.getBean();
// Passo 3 - Carrega a procedure persistente CostCenterUtils.p
var remoteObj = serviceHelper.createManagedObject("CostCenterUtils");
// Passo 4 - Invoca a procedure que retorna uma string com os tipos de CC
var types = serviceHelper.createStringHolder();
remoteObj.readCostTypes(types);
// Passo 5 - Quebra a string em um array com cada um dos tipos
var typeArray = types.getStringValue().split(",");
// Passo 6 - Cria o Dataset e adiciona cada tipo retornado
var newDataset = DatasetBuilder.newDataset();
newDataset.addColumn("id");
newDataset.addColumn("descricao");
for(var pos = 0; pos < typeArray.length; pos++) {
newDataset.addRow(new Array(pos + 1, typeArray[pos]));
}
return newDataset;
}

...

Onde:

• Passo 1 – Nesta etapa é feita a invocação do serviço configurado no Painel de Controle (getService). Note que neste ponto não é preciso informar qualquer parâmetro de conexão ao serviço, uma vez que isto já foi feito no seu cadastro.

...

function createDataset(fields, constraints, sortFields) {
var servico = ServiceManager.getService("ems2_v10");
var serviceHelper = servico.getBean();
var remoteObj = serviceHelper.createManagedObject("CostCenterUtils");
// Lê os tipos de contas
var types = serviceHelper.createStringHolder();
remoteObj.readCostNatureTypes(types);
var typeArray = types.getStringValue().split(",");
var newDataset = DatasetBuilder.newDataset();
newDataset.addColumn("id");
newDataset.addColumn("descricao");
for(var pos = 0; pos < typeArray.length; pos++) {
newDataset.addRow(new Array(pos + 1, typeArray[pos]));
}
return newDataset;
}

...

Após o cadastro do Dataset, é possível visualizar o seu conteúdo.

...

function createDataset(fields, constraints, sortFields) {
var servico = ServiceManager.getService("ems2_v10");
var serviceHelper = servico.getBean();
var remoteObj = serviceHelper.createManagedObject("CostCenterUtils");
// Lê as contas correntes
var holder = serviceHelper.createProDataGraphHolder();
remoteObj.readCostCenters(holder);
var newDataset = DatasetBuilder.newDataset();
newDataset.addColumn("conta");
newDataset.addColumn("titulo");
newDataset.addColumn("natureza");
newDataset.addColumn("tipo");
var ttCC = holder.getProDataGraphValue().getProDataObjects("ttCC");
for(var row_index = 0; row_index < ttCC.size(); row_index++) {
var row = ttCC.get(row_index);
newDataset.addRow(new Array(row.get("conta"),
row.get("titulo"),
row.get("natureza"),
row.get("tipo")));
}
return newDataset;
}

Figura 23-Visualização do Dataset de Centros de Custo 

Usuários em Comuns

A primeira diferença entre o Dataset de usuários comuns e os exemplos anteriores, é que neste caso é preciso passar uma temp-table como parâmetro para a procedure invocada.

...

unction createDataset(fields, constraints, sortFields) {
// Primeiro, recupera os colaboradores correntes
var campos = new Array("colleaguePK.colleagueId", "colleagueName");
var dataset = DatasetFactory.getDataset("colleague",
campos,
null,
null);
// Instancia o servico
var servico = ServiceManager.getService("ems2_v10");
var serviceHelper = servico.getBean();
// Transforma o dataset em um ProDataGraph (v10) e cria holder para saida
var inputTT = serviceHelper.toProDataGraph(dataset);
var holder = serviceHelper.createProDataGraphHolder();
// Invoca a procedure no Progress
serviceHelper.getProxy().verifyUsers(inputTT, holder);
// Cria o novo Dataset
var newDataset = DatasetBuilder.newDataset();
newDataset.addColumn("usuario");
newDataset.addColumn("nome");
var ttCC = holder.getProDataGraphValue().getProDataObjects("ttOutUsers");
for(var row_index = 0; row_index < ttCC.size(); row_index++) {
var row = ttCC.get(row_index);
newDataset.addRow(new Array(row.get("cod_usuar"),
row.get("nom_usuario")));
}
return

Figura 24 - Visualização do Dataset de Usuários Comuns

...

A tabela abaixo apresenta a lista de métodos existentes na classe utilitária para serviços Progress®:

Links Externos

Acesso direto a pasta

...

Exemplo:
http://localhost:8080/webdesk/?state=navigation&folderId=8 

Importante: Esta situação só é válida para sessões que estejam autenticadas. Para sessões não autenticadas consulte o capítulo Acesso sem efetuar login, abaixo.

...

É possível acessar o ECM externamente sem passar pela tela de login, basta utilizar as URL's informando o token de acesso. O token deve ser gerado utilizando o webservice TokenService do ECM. Para mais informações consultar o Guia de Referência Utilização de Webservices.

Os acessos disponíveis são:

...

http://<servidor>:<porta>/josso/signon/ExternalLogin.do?t=<token gerado>&josso_cmd=true&josso_back_to=/webdesk/ 

Navegação posicionada em pasta:

...

http://<servidor>:<porta>/josso/signon/ExternalLogin.do?t=<token gerado>&josso_cmd=true&josso_back_to=/webdesk/workflowstate?pi=<número da solicitação>