INTEGRAÇÃO TOTVS Gestão Hospitalar - Datasul EAI

Este documento descreve a configuração do Web Service de recebimento do RM no Datasul 12.1.4.

Estrutura Web Service - Recebimento

Configuração

O Datasul EAI disponibiliza um Web Service para receber as informações a serem cadastradas ou consultadas no Datasul.

Para configurar o ambiente, os seguintes serviços devem ser instalados:

• Progress AppServer 10.1A ou superior;
• Progress APPServer, que servirá para conexão Java. É incluído nas licenças do EMS/HR.
• Java SE Development Kit (JDK) 5.0 ou superior (obtido em http://java.sun.com/).
• Apache Tomcat 5.5 (obtido em http://tomcat.apache.org/).
• Apache Axis 1.4 (obtido em http://ws.apache.org/axis/).
• Ambiente do Datasul EMS com o EAI configurado, com suas assinaturas corretamente atribuídas.

Ambiente: Windows 2008 R2 64 bits

Como ambiente de rede, as seguintes mudanças precisam ser promovidas:

• Porta liberada no firewall para receber conexão do emitente da requisição WebServices.

Pré-requisitos instalação/implantação/utilização

Relacione quais são os pré-requisitos (técnicos ou de negócio) para a integração. Este tópico não deve incluir informações da implantação normal do módulo, mas apenas informações específicas da integração. É como se este tópico já partisse do princípio que o módulo que será integrado já está normalmente instalado.

Entre os tópicos deste tópico podemos citar:

• Versões mínimas de produtos.
• Módulos ou programas que geram informações necessárias a integração. Muitas vezes a integração partirá de informações que somente são trabalhadas em um determinado programa ou processo, que deverá estar em uso no cliente.
• Ferramentas que são necessárias a integração, como: EAI, ESB, servidor de WebService etc.
• Aspectos legais nos quais as partes envolvidas na integração devem estar inseridas, caso as informações envolvidas sejam utilizadas para o cumprimento de alguma lei específica.
• Requisitos de hardware ou Software, como servidores, link de internet, capacidade de armazenamento e memória, sistema operacional.

Instalação/Atualização

1 - Instalação do Progress AppServer

1.1 - Acessar a ferramenta Progress Explorer Tool, conectando-se ao servidor que disponibilizará o serviço.

Conectado ao serviço "localhost".

1.2 - Na pasta "Appserver", adicione um novo serviço, escolhendo a opção "Novo" no menu "Ação".

Criado o serviço “wseai”.

1.3 - Acessar as propriedades do serviço criado através do menu "Ação" item "Propriedades".

Nessa janela deve-se selecionar o modo operacional "Stateless", informar um diretório de trabalho e o número da porta do serviço Appserver (TCP). Esse número de porta servirá para que o NameServer redirecione uma nova conexão entrante para o serviço. É sugerido marcar a opção "Início automático", para que o serviço seja iniciado automaticamente com o Admin Service do Progress.

1.4 - Acessar o subitem "Informações sobre o NameServer de controle", do item "Broker".

Nessa janela é necessário:

• Marcar a opção "Registrar com NameServer" para que o cliente possa conectar diretamente ao NameServer e automaticamente ser redirecionado para o serviço Appserver desejado;
• Na opção "NameServer de controle" deve ser selecionado um NameServer previamente criado, local ou remoto. No exemplo usa-se o NameServer "NS1" local e padrão do Progress;
• Para "Modo de Registro" informar o modo preferido de endereço IP que ficará contido no NameServer, esta configuração pode variar dependendo do tipo de estrutura de rede que está sendo utilizada.

1.5 - Acessar o subitem "Geral", do item Servidor.

Configurações:

• Inserir no campo "Arquivo executável do servidor" o caminho da instalação Progress + caminho do executável para AppServer. Ex: "c:\dlc91d\" + "bin_proapsv.exe";
• O campo "Parâmetros de inicialização do servidor" corresponde aos parâmetros comuns utilizados por uma sessão Progress. Nesse campo é necessário informar os parâmetros para conexão de banco e outros parâmetros de uma sessão comum de integração. Também é necessário informar a autenticação do produto que se deseja integrar com WebService (no caso de um dos produtos Datasul) isso deve ser efetuado utilizando o formato -param "produto.usuario.senha", sendo que para "produto" o valor pode ser "EMS2", "EMS5", "HR", “DATASUL10” ou “DATASUL11”.

• No campo "PROPATH" devem ser informados os mesmos diretórios de uma sessão comum de integração. Os valores são separados por ";" (ponto e vírgula) e aconselha-se deixar os valores padrões, e colocar os novos valores no começo do campo.

Exemplo:

• Ao invés de "X:\servidor\diretório" utilizar "\\servidor\compartilhamento\diretório".
• Os campos "Número mínimo de porta" e "Número máximo de porta" devem ser configurados com uma faixa de portas que poderão ser utilizadas pelo serviço AppServer, sendo que o mesmo aceita mais de uma conexão simultânea.

Nota: O PF informado para conexão aos bancos de dados necessita utilizar conexão client/server ou seja, necessita conectar ao banco no seguinte formato: -db nomebanco -S porta -H nomeservidor -N tcp.

1.6 - Acessar o subitem "Arquivo de log" tanto do item "Broker" como do item "Agente":

Neste estágio é importante inserir um caminho correto no campo "Nome de arquivo de log do servidor", sendo que os logs gerados são muito importantes para diagnósticos de problemas de ambiente e configuração. Também deve-se escolher o nível de log conforme desejado. Mais informações sobre como configurar o log no Appserver podem ser obtidas no item Configuração de Log no AppServer.

1.7 – Parametrizar o número de agentes iniciais, mínimo e máximo

Esta parametrização deve respeitar a quantidade máxima de licenças do Progress (verificar no progress.cfg), onde é possível parametrizar com quantos agentes o serviço será iniciado, a quantidade mínima mantida e a máxima permitida.

Lembramos que cada agente em uso ou mantido na memória irá consumir recursos da máquina, porém por se manter ativo pode ter um pequeno ganho de performance na integração do RM com o Datasul.

2 - Instalação do Apache Tomcat

O Tomcat é um servlet container, escrito em Java e, por isso, necessita de uma JVM compatível com o padrão JDK 1.5 ou superior. No entanto, não basta ter a versão runtime de Java instalada, pois o Tomcat necessita compilar (e não apenas executar) programas escritos em Java.

É um software livre, podendo ser utilizado comercialmente.

Durante a instalação deve-se informar o diretório onde o Tomcat será instalado e também a porta que o mesmo irá utilizar. Por padrão, a porta é a 8080.

A configuração se refere à instalação do Apache Tomcat versão 5.5.

2.1 - Instalar o Tomcat em uma estrutura de diretório.

A seguir é apresentado um exemplo da estrutura no qual o Tomcat pode ser instalado:

2.2 – Instalação do JDK de forma padrão 

2.3 - É necessário fazer o download do arquivo http://tomcat.heanet.ie/native/1.1.2/binaries/win32/tcnative-1.dll

Salvar no diretório <instalação do tomcat>\bin (Ex.: C:\Arquivos de programas\Apache Software Foundation\Tomcat 7.0\bin).

2.4 - Nas configurações do Tomcat no folder "JAVA"

Inserir no final do conteúdo do campo "Java Classpath" já existente um ponto e vírgula(";") e informar o caminho completo para o arquivo tools.jar que existe no diretório lib do JDK que está sendo utilizado (Ex.: ";C:\Arquivos de programas\Java\jdk1.5.0_06\lib\tools.jar", conforme instalado no item 2.2).

2.5 - Para essa configuração existem duas opções:

Nas configurações do Tomcat, na aba "JAVA", inserir no final do conteúdo do campo "Java Options" já existente o seguinte conteúdo: -Dfile.encoding=UTF-8. Isso evitará divergências de acentuação durante as integrações;

- no arquivo "server.xml" do diretório "<instalação tomcat>/conf" na linha <Connector port="8080" protocol="HTTP/1.1" connectionTimeout="20000" redirectPort="8443"/> adicionar o trecho URIEncoding="UTF-8" após redirectPort="8443".

Ex.: <Connector port="8080" protocol="HTTP/1.1" connectionTimeout="20000" redirectPort="8443" URIEncoding="UTF-8"/>

Observação: É possível alterar as portas do serviço tomcat no arquivo "server.xml" no diretório "conf" do Tomcat.

3 - Instalação do Axis 1.4

3.1 - Instalar o Axis (copiar a pasta) em uma estrutura de diretório.

A seguir é apresentado um exemplo da estrutura no qual o Axis pode ser instalado:

4 - Habilitar o suporte a Web Services no Tomcat.

4.1 - Copiar o arquivo eai.jar que se encontra na pasta "xmljserv" do EAI (área de programas do Datasul 11) para o diretório \webapps\axis\WEB-INF\lib.

Ex: C:\Arquivos de programas\Apache Software Foundation\Tomcat 7.0\webapps\axis\WEB-INF\lib);

Nota: Caso a versão do Progress que estiver sendo configurada for a versão 10 ou superior, é necessário copiar o arquivo EAI10.JAR ao invés do arquivo EAI.JAR, e renomeá-lo para EAI.JAR.

Neste ambiente utiliza-se o Progress 10, então copiamos o arquivo EAI10.JAR e renomeamos como EAI.JAR.

4.2 - Copiar os seguintes arquivos existentes em \java da instalação do Progress para o diretório \webapps\axis\WEB-INF\lib

(Ex.: C:\Arquivos de programas\Apache Software Foundation\Tomcat 7.-\webapps\axis\WEB-INF\lib):

• PROGRESS.JAR
• MESSAGES.JAR
• O4GLRT.JAR*
• OPENEDGE.JAR*
• BASE.JAR*
• POOL.JAR*
• SPY.JAR*
• UTIL.JAR*

* Copiar caso a versão do Progress for maior que 10. Se o Progress for versão 10.2B não existe os arquivos "MESSAGERS.JAR", "BASE.JAR", "SPY.JAR" e "UTIL.JAR". Sendo assim, é necessário apenas copiar os arquivos "PROGRESS.JAR", "O4GLRT.JAR", "OPENEDGE.JAR" e "POOL.JAR".

4.4 - Inicializar o serviço do Tomcat para que já seja possível testar o funcionamento do suporte à Web Service do Axis.

Para isso, bastar abrir o browser e digitar a seguinte URL: http://localhost:8080/axis/.

5 - Variáveis de Ambiente

Para o correto funcionamento do sistema, é necessário que sejam configuradas as seguintes variáveis de ambiente:

5.1 - JAVA_HOME - Deve apontar para o diretório onde encontra-se a instalação do java.

Por exemplo, c:\jdk1.5.2_06.

                Localização do JDK: C:\Program Files\Java\jdk1.6.0_45

5.2 - CATALINA_HOME - Deve apontar para o local de instalação do Tomcat.

Por exemplo. C:\Tomcat 7.0 

Localização do TomCat: C\Program Files (x86)\Apache Software Foundation\Tomcat 7.0

6 - Publicação do Web Service EAI

Para que se consiga utilizar o web service do EAI, deve-se publicar o arquivo EaiWebService.jws no Tomcat.

6.1 - Copiar o arquivo "xmljserv\EaiWebService.jws" para a pasta "webapps\axis" da instalação do Tomcat.

6.2 - Configurar o arquivo eai.xml, cujo conteúdo deve ser igual ao do arquivo de exemplo a seguir:

Os parâmetros a serem informados neste arquivo são os seguintes:

• SERVER: Endereço IP do servidor onde o AppServer Progress foi instalado. Ex.: localhost
• PORTNUMBER: Número da porta onde o AppServer Progress está sendo executado. O valor desse campo deve ser o mesmo que está cadastrado na propriedade do NameServer. A porta padrão é 5162.
• SERVICE: Nome do serviço para o EAI configurado no AppServer Progress. Ex.: wseai.

Após parametrizado o arquivo eai.xml, é necessário que o mesmo seja publicado na pasta "webapps\axis\WEB-INF\classes", da instalação do Tomcat (Ex.: C:\Arquivos de programas\Apache Software Foundation\Tomcat 5.5\webapps\axis\WEB-INF\classes).

6.3 - Efetuar um teste de acesso ao arquivo de acesso ao Web Service do EAI que foi publicado.

Para isso, deve ser inicializado o Tomcat e após, executar o browser e digitar o seguinte endereço: http://localhost:8080/axis/EaiWebService.jws.

Informações Adicionais

Usuário EMS: foi criado um novo usuário para a integração, EAI com a senha “eai”.

A alteração desta senha influencia diretamente nos parâmetros de inicialização do WSEAI e deverão ser alteradas em: Propriedades do Agente > Agente > Geral > Parâmetros de inicialização do servidor, onde o atual valor apresenta-se abaixo:

-pf C:\totvs\datasul\dts-0\ERP\scripts\appserver\datasul-eai.pf -param "DATASUL11.eai.eai"

Arquivo PF: poderá ser alterado em: Propriedades do Agente > Agente > Geral > Parâmetros de inicialização do servidor, onde o atual valor apresenta-se abaixo:

-pf C:\totvs\datasul\dts-0\ERP\scripts\appserver\datasul-eai.pf -param "DATASUL11.eai.eai"

Arquivo ALIAS: O arquivo de ALIAS deste ambiente encontra-se em Propriedades do Agente > Agente > Recursos Avançados > Inicialização (Startup procedure) e atualmente possui o seguinte conteúdo:

\\Gptesteoracle\erp\scripts\appserver\alias-eai.p

Propath: As pastas consideradas para o WebService encontram-se em Propriedades do Agente > Agente > Geral > Propath e atualmente possui as pastas:

• \\Gptesteoracle\erp\quarentena\EAI\receiver,
• C:\totvs\datasul\dts-0\ERP\quarentena\TSBXMO\ems2,
• C:\totvs\datasul\dts-0\ERP\quarentena\especificos,
• C:\totvs\datasul\dts-0\ERP\quarentena\gp,
• C:\totvs\datasul\dts-0\ERP\quarentena\ems5,
• C:\totvs\datasul\dts-0\ERP\quarentena\hcm,
• C:\totvs\datasul\dts-0\ERP\especificos\gp,
• C:\totvs\datasul\dts-0\ERP\especificos\ems5,
• C:\totvs\datasul\dts-0\ERP\especificos\hcm,
• C:\totvs\datasul\dts-0\ERP,
• C:\totvs\datasul\dts-0\ERP\ems2,
• C:\totvs\datasul\dts-0\ERP\ems5,
• C:\totvs\datasul\dts-0\ERP\hcm,
• C:\totvs\datasul\dts-0\ERP\fnd,
• C:\totvs\datasul\dts-0\ERP\eai,
• C:\totvs\datasul\dts-0\ERP\eai2,
• C:\totvs\datasul\dts-0\ERP\gp,
• C:\totvs\datasul\dts-0\ERP\crm,
• C:\totvs\datasul\dts-0\ERP\crm\database,
• C:\totvs\datasul\dts-0\ERP\crm\integracoes

Reestabelecendo o serviço

Caso a integração RM > Datasul não ocorra, podemos inicialmente verificar:

• Se a URL http://localhost:8080/axis/EaiWebService.jws?wsdl é carregada corretamente (deve mostrar um XML);
• Se o WSEAI está ativo no Progress Explorer Tools (em verde);
• Se o TomCat está ativo nos ícones de notificação.

Em adicional, devem-se avaliar os logs:

• AppServer: C:\TEMP102B (arquivos wseai.broker/wseai.server)
• TomCat: C:\Program Files\Apache Software Foundation\Tomcat 7.0\logs

Ativando o modo DEBUG do EAI

Identificar o diretório de trabalho do AppServer (C:\temp102B) e em seguida criar uma pasta chamada XMLBKP. Com este procedimento, ao ser submetido um XML do RM ao WebService do EAI o mesmo irá criar um arquivo dentro da pasta indicada que conterá o XML recebido e o retorno enviado ao RM.

Transações assinadas para a integração do RM com o Datasul

• Sender:
  • TradingProcessReturn: adapters\xml\fi5\axsfi011.p
  • TradingProcessCancel: adapters\xml\fi5\axsfi012.p
  • Receiver (EMS2):
    • ItemBalance: adapters/xml/ar2/axrar003.p
    • InventoryTransaction: adapters/xml/ar2/axrar011.p
    • Manufacturer: adapters/xml/ma2/axrma015.p
    • ItemManufacturer: adapters/xml/ma2/axrma014.p
    • PriceQuery: adapters/xml/ar2/axqar001.p
    • InventoryTransactionQuery: adapters/xml/ar2/axrar009.p
    • Item: adapters/xml/ma2/axrma005.p
    • MaterialFamily: adapters/xml/ma2/axrma010.p
    • SalesOrer: adapters/xml/vd2/axrvd003.p
    • ItemLote: adapters/xml/ar2/axsar012.p
    • UnitOfMeasure: adapters/xml/ma2/axrma006.p
    • InventoryGroup: adapters/xml/ar2/axrar006.p
    • CustomerVendor: adapters/xml/un5/axrun005.p
    • CustomerVendorInformation: adapters/xml/un5/axqun006.p
    • AccountPayableDocument: adapters/xml/fi5/axrfi001.p
    • AccountReceivableDocument: adapters/xml/fi5/axrfi002.p
    • TaxesCalculate: adapters/xml/fi5/axqfi006.p
    • TradingProcess: adapters\xml\fi5\axrfi010.p
    • PendingPaymentCancel: adapters\xml\fi5\axrfi009.p

Como assinar uma transação

1) Para configurar o ambiente de envio \ sender (Sistema Datasul para RM) na sessão do produto.

Primeiro acessar no Datasul programa Monitor de Integração (queue_monitor). Será aberto o programa EAI9999, clique no botão “Configuração de transações EAI”.

Será aberto o programa EAI0202, clicar com o botão direito do mouse sobre o Produto e selecione “Nova Aplicação”.

Preencher o nome da nova aplicação e clicar em salvar, usar preferencialmente a aplicação Sender ou conforme necessidade do adapter. 

Após a criação da Aplicação, clicar com o botão direito do mouse em cima da aplicação criada e selecionar “Nova transação”.

No campo Transação informar "InventoryTransaction", e escolher qual adapter de transporte será utilizado (Fila - AXSUT001, WebService - AXSUT004 ou HTTP Post - AXSUT003), informando os demais campos conforme necessidade\arquitetura escolhida. O adapter de transporte disponibilizará o XML ao aplicativo de destino. Nesta tela não deverá ser parametrizado o adapter de negócio que cria o XML  (AXSAR001 ou AXSAR011), pois a chamada do mesmo já é realizada dentro das rotinas (fontes) de negócio.

2)Para configurar o ambiente de recebimento \ receiver (Aplicativo Externo para Sistema Datasul)

Acessar o produto utilizando o arquivo .INI que será utilizado no ambiente de receiver (ou seja, o arquivo .INI que será utilizado no Agente EAI, Serviço Appserver ou Serviço WebSpeed) - este arquivo normalmente é um arquivo diferente do utilizado na sessão do produto.

No propath deste arquivo NÃO DEVERÁ EXISTIR nenhuma entrada que aponte para a pasta onde esteja o arquivo eai-config.xml configurado no item 1).

Repetir os passos do item 1), mas no nome da aplicação sugere-se utilizar o nome "Receiver", e depois na criação da transação, informar o adapter de negócio que processará as mensagens XML:  “AXRAR001” ou “AXRAR011” conforme o caso, como explicado no 1o parágrafo.

No caso do EAI-CONFIG.XML de receiver é possível copiá-lo de outros ambientes, pois os adapter apontam para programas do Datasul, não sendo necessário alterar parâmetros conforme ambientes diferentes.