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

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

Caso não haja progress na máquina a ser instalada, seguir os passos fornecidos pela Progress.

Servidor: GPTESTEORACLE – Windows 2008 R2 64 bits

Diretório Progress: C:\DLC102B

Versão: 10.2B SP 07

Usuário Progress Explorer Tools: admin/unimed

Versão Datasul: 12.1.4 Oracle

Passo 1.1 - Acessar a ferramenta Progress Explorer Tool, conectando-se no 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”.

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.

Modo operacional: Stateless

                Diretório de trabalho: C:\temp102B

                Número da porta: 4000

                Auto start

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

Nessa janela é necessário:

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

Registrar com o NameServer

                NameServer de Controle: NS1

                Modo de registro: Register-IP

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.

Importante: Para o campo "PROPATH" não são aceitos arquivos de unidades mapeadas, sendo que para se colocar diretórios localizados em outros pontos da rede deve se utilizar o caminho UNC.

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.

Arquivo executável do servidor: "C:\DLC102B\bin\_proapsv.exe"

Parâmetros de inicialização do servidor: -pf C:\totvs\datasul\dts-0\ERP\scripts\appserver\datasul-eai.pf -param "DATASUL11.eai.eai"

Propath:              \\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

                Número mínimo de porta: 2002
              Número máximo de porta: 2202

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.

Server logging level: Extended

                Server log filename: C:\TEMP102B\wseai.server.log

                Server logging entry types: ASPlumbing,DB.Connects,4GLMessages,4GLTrace,FileID

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.

Initial number of servers to start: 1

Minimum servers: 2

Maximum servers: 5

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.

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

Instalado JDK 1.6.0_45 (C:\Program Files\Java\jdk1.6.0_45)

Instalado TomCat 7.0.50 (C:\Program Files\Apache Software Foundation\Tomcat 7.0)

Download: http://tomcat.apache.org/download-70.cgi, versão 32-bit/64-bit Windows Service Installer (pgp, md5)

Porta: 8080

Passo 2.2 – Instalação do JDK de forma padrã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).

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.

                Alterado nas propriedades do TomCat.

Passo 3 - Instalação do Axis 1.4

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

Passo 4 - Habilitar o suporte a Web Services no Tomcat.

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

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

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

Importante: Caso a instalação esteja correta, será exibida a página de boas-vindas do Axis, na qual, é possível efetuar a validação dos componentes instalados, através do link "Validate the local installation´s configuration". 

Passo 5 - Variáveis de Ambiente

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

Passo 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

Passo 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

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

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

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

Importante: O número da porta do NameServer pode ser alterado utilizando o Progress Explorer Tool > Console Root > Progress Explorer > localhost > NameServer. Clicando com o botão direito em cima do NameServer (o mesmo definido no passo 1.4), clicar sob "Properties" ou "Propriedades", uma janela abrirá e poderá ser alterado o valor "Número da porta" do NameServer.

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

<?xml version="1.0" encoding="UTF-8"?>

<DatasulWebService xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:noNamespaceSchemaLocation="\\Gptesteoracle\erp\eai\xmlschema\datasulwebservice.xsd">

                <Config Description="FALHA DE COM">

                               <Server>192.168.50.56</Server>

                               <PortNumber>5162</PortNumber>

                               <Service>wseai</Service>

                </Config>

</DatasulWebService>

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:

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.

Anexos