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

Image Added

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

Passo 1 - Instalação do Progress AppServer

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

Conectado ao serviço "localhost".

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

Criado o serviço “wseai”“wseai”.

Image Modified

Image Modified

Passo 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.

Image Modified

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

Nessa janela é necessário:

• Assinalar 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.

Image Modified

Passo 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  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.

 Image AddedImage Removed

Passo 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.

Image Modified

Passo 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.

Passo 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.

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

Image Modified

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

Image Modified

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

Passo 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);.

Ponto 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).

Image Modified

Ponto 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.

Image Modified

Controle de Versão

O grupo TOTVS, representado por suas marcas, irá administrar as demandas de evolução dos layouts e demais ajustes, acordando junto aos solicitantes o prazo de liberação de release.

Todas as evoluções programadas deverão ser discutidas e aprovadas pelas marcas antes do início do desenvolvimento e somente serão desenvolvidas em caso de concordância das marcas e alinhamento com as diretivas definidas pelo Comitê de Integração TOTVS.

Suporte

O suporte aos recursos da Integração será de responsabilidade de todas as linhas, sendo assim as equipes de suporte dos produtos RM Conector e Backoffice Protheus estarão aptas a fazer a primeira análise e, quando necessário, repassar para a equipe mais adequada em cada caso.

Observação: Este modelo de suporte está sendo revisado pela TOTVS.

Transações/Entidades/Mensagens únicas

Apresente quais as transações/entidades que são trocadas e quem envia a informação para quem. Pode (e recomenda-se) ter um diagrama, uma tabela ou afins que apresente este fluxo.

Relacione quais são as mensagem únicas (TOTVSMessage) utilizadas e qual o seu relacionamento com as entidades já existentes do ERPs envolvidos.

Exemplos:

 Image Removed

Image Removed

Fluxo das Informações

Para cada fluxo de informação descreva, se necessário, alterações de comportamento que o respectivo produto irá sofrer. Por exemplo: quando o Logix recebe o PEDIDO de OUTRO ERP, este pedido não poderá ser alterado no Logix.

Liste quais as entidades integradas e como é o mapeamento entre as diferentes estruturas. Por exemplo: Classe no sistema A vira categoria no sistema B, o campo X é refletido no campo Y etc.

Liste quais transações/operações a integração fará com as entidades relacionadas. Exemplo: Insert de PEDIDO, Insert, update de ITEM, buscar saldo em estoque do ITEM no dia X ou buscar dados do FUNCIONÁRIO.

Cadastros

Descreva características gerais do fluxo de informações e que serão comuns para este tipo de entidade. Características particulares para cada entidade deverão ser citadas em tópicos específicos de cada entidade.

Sempre que existir (a sugestão é sempre criar) e for agregador ao documento acrescentar aqui os diagramas/imagens ou até mesmo colocar tais diagramas diretamente na especificação dos processos

Em seguida faça uma descrição para cada um dos fluxos para cada entidade

<Transação/Entidade>

Identificador da Mensagem: <mensagem>

Versão: <versão>

Módulo <marca 1>: <BackOffice – Gestão xxxxxxx>

Módulo <marca 2>: <SIGAXXX>

Tipo de Envio: <Assíncrona/Síncrona>

Notas:

Observações sobre comportamento desta mensagem ou dos processos envolvidos nela/para ela

A seguir descrever as variações, particularidades da mensagem e processos (integração) de acordo com cada marca

Limitações/Restrições

Descreva limitações e restrições para a integração que está sendo descrita.

Processos

Descreva características gerais do fluxo de informações e que serão comuns para este tipo de entidade. Características particulares para cada entidade deverão ser citadas em tópicos específicos de cada entidade.

Sempre que existir (a sugestão é sempre criar) e for agregador ao documento acrescentar aqui os diagramas/imagens ou até mesmo colocar tais diagramas diretamente na especificação dos processos

Em seguida faça uma descrição para cada um dos fluxos para cada entidade

<Transação/Processo>

Tipo de Fluxo: Protheus -> RM

Mensagem: Request_1_000

Versão: 1.000

Descrição de todo o comportamento e funcionamento do processo. Breve contexto, origem, regras, integração (geração da mensagem, envio, recebimento no destino), o quê supostamente irá ocorrer no destino, retorno, impacto, consequências, o que foi afetado, como conferir, validar, etc o retorno.

Acrescentar um diagrama do processo.

A seguir descrever as variações, particularidades da mensagem e processos (desta integração) de acordo com cada marca

Notas:

Observações sobre comportamento desta mensagem ou dos processos envolvidos nela/para ela

Limitações/Restrições

Descreva limitações e restrições para a integração que está sendo descrita. 

Limitações / Restrições Gerais

Descreva limitações e restrições para cada fluxo descrito no tópico anterior. Exemplo:

• ERP1 envia ITEM cadastrado para o ERP2

ERP1 somente enviará o ITEM se este estiver em uma das famílias cadastradas no parâmetro FAMILIA_INTEGRACAO.

Se o tipo de valorização do estoque for FIFO.

• ERP2 envia PEDIDO cadastrado para o ERP1

O pedido recebido no ERP1 vindo do ERP2 estará bloqueado para alteração.

Como fazer (opcional)

Descreva os passos que viabilizem a integração.

Exemplo:

Os passos para viabilizar a integração são:

• No Logix ou no Protheus efetue o cadastro das seguintes informações: Clientes, fornecedores, transportadores, cidades, cotação de moeda e unidades de medida.
• No Logix cadastrar um novo depositante e efetuar toda a parametrização necessária para a operação de WMS.
• No Logix cadastrar um novo produto que seja controlado pelo WMS, para o depositante cadastrado anteriormente.
• No Logix efetuar um processo de recebimento para o produto cadastrado anteriormente, utilizando uma nota fiscal provisória (tipo “A”).
• No Protheus consultar a nota fiscal de recebimento que foi registrada no Logix, validando as informações recebidas.
• No Logix efetuar um processamento de regularização fiscal, efetuando a cobertura dos produtos recebidos anteriormente.
• No Protheus verificar se foi efetuado corretamente o relacionamento entre os dois documentos.
• No Logix efetuar um processo de expedição para o novo produto cadastrado, até o momento do envio da mensagem de integração de pedido de venda.
• No Protheus efetuar o faturamento do pedido de venda recebido.
• No Protheus verificar se a nota fiscal gerada contém todas as informações necessárias para o segmento de operador logístico (armazém geral).
• No Protheus efetuar a escrituração fiscal das notas fiscais, verificando se as regras da legislação deste segmento foram respeitadas.
• No Logix é possível consultar o número do pedido de venda gerado para as notas fiscais de retorno simbólico e conta/ordem no programa WMS6333 (Consulta de Documentos). Para os processos de faturamento de serviço o número do pedido está disponível no programa WMS6411 (Movimentos a Faturar).

Situações comuns (opcional)

Descreva situações problemáticas comuns que podem ocorrer durante o funcionamento da integração e como solucioná-los. Neste ponto também é importante dar instruções de como reconhecer e investigar problemas que podem vir a ocorrer durante a integração. Se houver, apresente tabelas de códigos e descrições de erros que a integração poderá apresentar.

Este tópico possivelmente será alimentado com as experiências durante o desenvolvimento da integração e poderá ser realimentado durante o uso da integração no cliente.

Exemplo 1:

Tratamento de erros de integração (Produto A)

Tratamento de erros de integração (Produto B)

Exemplo 2:

Quando uma mensagem é enviada do Logix para o Protheus, podem ocorrer situações em que o WebService não estará totalmente funcional. Nestes casos uma mensagem de erro genérica irá aparecer na tela:

Exemplo:

Erro ao enviar a mensagem de Cidade via Integração

Se o arquivo de log for analisado, poderemos ver a falha na comunicação com o sistema destino:

-------------------------------------------------------------------------------

WSCERR044 / Não foi possível POST : URL http://172.16.31.57:8011/ws/FWWSEAI.apw

ADVPL WSDL Client 1.080707 / tst on 20120315 08:49:51

-------------------------------------------------------------------------------

Para resolver este problema, verifique as configurações do sistema de destino, analisando o funcionamento do servidor utilizado para esta comunicação e a habilitação do endereço do WebService. 

Checklist de suporte da aplicação

Crie um check-list de verificação de alguns pontos importantes para o funcionamento e atendimento da integração.

Instalação/Configuração

Relacione itens de verificação para garantir que a integração está corretamente instalada e configurada. Isto não pode ser uma cópia do procedimento de instalação/configuração, mas verificações pontuais que podem remeter aos itens da instalação.

Checklist de Verificações:

Relacione itens de verificações para que o atendente possa:

• Identificar o funcionamento da integração;
• Identificar a ocorrências de problemas;
• Coletar evidências do mau funcionamento relatado pelo cliente;
• Realizar possíveis ajustes na integração quanto à configuração ou negócio.

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.

Image Added

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”.

Image Added

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

Image Added

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

Image Added

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”.

Image Added

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.