Manual de Configurao do Ambiente de Integrao

Novembro/2005 Verso 1.0

No homologado

Copyright 1998 DATASUL S.A. Todos os direitos reservados. Nenhuma parte deste documento pode ser copiada, reproduzida, traduzida ou transmitida por qualquer meio eletrnico ou mecnico, na sua totalidade ou em parte, sem a prvia autorizao escrita da DATASUL S.A., que se reserva o direito de efetuar alteraes sem aviso prvio. A DATASUL S.A no assume nenhuma responsabilidade pelas conseqncias de quaisquer erros ou inexatides que possam aparecer neste documento.
DATASUL S.A. Av. Santos Dumont, 831, Joinville, SC, CEP 89.222-900

ndice
CAPTULO 1 O ambiente de integrao..........................................................3

A mensagem padro Datasul.........................................................................3 Control Broker..............................................................................................3 Adapter XML................................................................................................4 Servios de Validao e Transformao.......................................................5 Estrutura de diretrios...................................................................................5 Sesso Progress.............................................................................................6
CAPTULO 2 Arquivos de configurao ........................................................7

InstalledApplications.xml.............................................................................7 TransactionSubscription.xml.......................................................................10 ProcessingInfo.xml.....................................................................................12 MessageConstants.xml................................................................................16 config.xml...................................................................................................20 productdir.xml.............................................................................................21 ListOfProcess.xml.......................................................................................22

CAPTULO 3 Adapters Assncronos.............................................................24

Definies...................................................................................................24 Adapter Assncrono de Envio.....................................................................26

InstalledApplications.xml.................................................................26 TransactionSubscription.xml............................................................26
Adapter Assncrono de Recebimento..........................................................27

Processo de Recebimento..................................................................27 ListOfProcess.xml.............................................................................28 Regras de execuo...........................................................................29 Aps iniciar o(s) processo(s).............................................................29

Estrutura tabela FILA-EAI..........................................................................29

Acessando a tabela FILA-EAI....................................................................35

Gravando na tabela FILA-EAI..........................................................35 Lendo da tabela FILA-EAI...............................................................36 Gravando na tabela FILA-EAI em Banco de Dados ORACLE.......39
CAPTULO 4 Monitor da Fila de Integrao..................................................40

Caractersticas.............................................................................................40 Selecionando mensagens para exibio.......................................................40 Alterando uma mensagem...........................................................................43

CAPTULO 5 Validao e Transformao.....................................................45

Configurao...............................................................................................45 Colocando os servios no ar........................................................................46

CAPTULO 6 Configurao passo a passo ..................................................47

Configurando os atalhos..............................................................................47 Configurando os produtos...........................................................................47 Configurando cdigo de pgina da Sesso Java..........................................48

CAPTULO 7 Customizao de Transaes.................................................49

Customizando Transaes...........................................................................49

Declarando include padro................................................................50 Definindo temp-table de comunicao ............................................50 Definindo parmetros do programa de customizao .....................50
Customizando o mtodo isSubscribed.........................................................53

Definindo parmetros do programa de customizao .....................53

CAPTULO 1

integrao
Descrio

O ambiente de

Neste captulo so apresentados os vrios componentes que formam o ambiente de integrao e como feito o relacionamento entre eles. Mais informaes a este respeito podem ser encontradas no documento Arquitetura de Integrao e Mensagem Padro.

A mensagem padro Datasul

Os produtos da Datasul esto preparados para manipular mensagens que estejam dentro do padro por ela definido. A mensagem padro da Datasul possui informaes que no esto armazenadas hoje nas bases de dados. Ela tambm possui elementos opcionais, cujo uso definido no ambiente do cliente. Alm disso, existem certos processamentos que podem ou no ser realizados na mensagem e a definio desta questo tambm s poder ser feita no ambiente do cliente. Todos estes pontos so definidos atravs de arquivos de configurao que esto no formato XML. A apresentao destes arquivos feita no captulo Arquivos de Configurao.

Control Broker
O Control Broker o componente responsvel por fazer a distribuio das mensagens que circulam entre os sistemas escritos em Progress. A integrao entre estes sistemas Progress acontece de maneira sncrona. Isto significa dizer que o programa que gera uma mensagem interrompe sua

execuo e aguarda que a mesma seja entregue e processada nos sistemas destino, continuando seu trabalho apenas depois de receber uma resposta deles. Caso haja algum problema l, ele pode desfazer o trabalho realizado que esteja relacionado mensagem gerada. Caso haja a necessidade de integrar estes sistemas com outros no Progress ou sejam imprescindveis recursos de integrao de um nvel mais elevado, a sada lanar mo de um dispositivo assncrono que d suporte a isto. Quando so utilizados mecanismos assncronos, um programa que gere uma mensagem simplesmente a entrega a este dispositivo e continua seu processamento, no esperando qualquer retorno dos sistemas destino. Cabe ao dispositivo assncrono, comumente denominado Message Broker, oferecer recursos para o gerenciamento de problemas no destino. Para fazer o roteamento das mensagens, o Control Broker se apia em arquivos de configurao. Para cada tipo de transao ele monta uma lista dos programas que devem ser executados e para os quais as mensagens daquela espcie devem ser passadas. Sendo assim, todo aplicativo que pretenda receber as transaes de um determinado tipo deve indicar o programa a ser executado. Para facilitar a configurao da comunicao do Control Broker com um dispositivo assncrono, possvel montar uma lista de transaes e indicar um programa que receba as mensagens destes tipos. O Control Broker ainda aceita que seja feita uma configurao para a execuo de programas de personalizao das mensagens que entram e saem de cada aplicativo.

Adapter XML
Adapter a designao dada a programas que tem a funo de fazer a construo de mensagens XML a partir de informaes num formato qualquer e, no caminho inverso, extrair informaes de mensagens XML. Geralmente so construdos adapters especficos para processar cada tipo de mensagem (transao de negcio). No entanto, nada impede que um adapter manuseie mensagens relativas a vrios tipos de transaes diferentes. A situao comum para este caso aquela em que o adapter simplesmente recebe a mensagem e a encaminha para um dispositivo assncrono sem a processar. Na arquitetura de integrao da Datasul este tipo de adapter classificado como sendo do tipo transport, enquanto que o primeiro do tipo processing. importante esta distino, pois o Control Broker executa primeiro os adapters do tipo processing e depois os do tipo transport. Isto feito para otimizar o

trfego de mensagens, uma vez que se houver um erro na efetivao de uma mensagem no sistema sncrono (processing adapter), o processamento interrompido e ela no chega a ser enviada ao mecanismo assncrono (transport adapter).

Servios de Validao e Transformao

As mensagens Datasul so todas modeladas atravs de XML Schemas. Para garantir que uma mensagem esteja de acordo com seu modelo, pode ser feita a validao dela. Um servio de validao recebe uma mensagem, que em seu interior referencia um XML Schema, e faz a verificao de se esta mensagem est em conformidade com o Schema. Caso no esteja, retorna os erros encontrados. A transformao consiste em gerar uma nova mensagem XML a partir de uma existente e de um arquivo no formato XSL. Estes dois servios so utilizados no ambiente de integrao Datasul e sua configurao apresentada no captulo Validao e Transformao.

Estrutura de diretrios
Cada produto da Datasul possui em seu diretrio raiz alguns subdiretrios que so utilizados no processo de integrao. A seguir so listados cada um deles e sua descrio: adapters/XML: A pasta adapters possui um subdiretrio chamado XML onde esto localizados os programas que fazem a gerao e interpretao das mensagens XML de integrao. Na verdade, o diretrio XML dividido em vrias pastas, sendo cada uma relativa a um aplicativo do produto e nestas pastas aonde realmente residem os adapters. xmlconf: Esta pasta contm a maioria dos arquivos de configurao do produto que controlam o processo de integrao. Ela possui um subdiretrio para cada aplicativo aonde so feitas algumas configuraes especficas deles. xmljserv: Esta pasta contm os programas que compem os servios de validao e transformao e os arquivos que os configuram. xmllog: Nos subdiretrios desta pasta so gerados os arquivos de log de integrao para cada aplicativo do produto. Caso esta pasta no seja encontrada, ser automaticamente criada no diretrio temporrio da sesso em execuo.

xmlschema: Esta pasta possui um subdiretrio por aplicativo, aonde so guardados os XML Schemas das transaes que so de responsabilidade daquele aplicativo. No entanto, ao contrrio das demais pastas, aonde havia subdiretrios apenas para os aplicativos do produto em questo, aqui h pastas para os aplicativos de todos os produtos. O motivo disso que cada tipo de transao de responsabilidade de apenas um aplicativo, dentre aqueles de todos os produtos, e por isso seu Schema tem que estar presente em todos os produtos para que possa ser feita a validao. Por exemplo, no existe um Schema para a transao Cliente no EMS2 e um Schema diferente para Cliente no EMS5. Existe apenas um Schema para Cliente que pertencer a um dos dois produtos, mas que ser distribudo com o outro por poder ser usado por ele. xmltransf: Nesta pasta ficam armazenados todos os arquivos de transformao (XSL). xmlutp: Esta pasta contm o Control Broker e outros utilitrios auxiliares.

Sesso Progress
Para que o processo de integrao entre diferentes produtos funcione corretamente necessrio que sejam observados dois pontos na configurao da sesso Progress aonde os programas forem executados. O primeiro deles que os bancos de todos os produtos devem estar conectados simultaneamente. O segundo ponto que o diretrio raiz de todos os produtos a serem integrados esteja presente no ProPath desta sesso.

CAPTULO 2

Arquivos de configurao
Descrio Neste captulo so apresentados os arquivos XML que configuram o ambiente de integrao Datasul.

InstalledApplications.xml
Localizado na raiz do diretrio xmlconf, este o arquivo que guia o processo de configurao do ambiente de integrao. Sua presena indica que o diretrio do ProPath abaixo do qual ele se encontra relativo a um produto que deve ser integrado. Sua ausncia far com que os aplicativos do produto no recebam mensagens e no possam usar os mecanismos de construo de mensagens disponveis. Este arquivo identifica o nome do produto, seus aplicativos que tambm devem fazer parte da integrao e o nvel de log desejado para cada um destes aplicativos. O elemento raiz deste arquivo se chama InstalledApplications e tem como filhos os elementos Product e ListOfApplication.

O elemento Product tem como valor o nome do produto que est sendo integrado.

O elemento ListOfApplication pode conter vrias ocorrncias do elemento Application.

Cada ocorrncia do elemento Application corresponde a um aplicativo que deve fazer parte da integrao, ou seja, a um aplicativo daquele produto que o cliente utiliza.

Application tem como filhos os elementos Id e LogLevel. O valor de Id o cdigo do aplicativo. Nesta pasta xmlconf deve haver um subdiretrio cujo nome seja igual ao valor deste elemento. Nele devem estar localizados os arquivos de configurao especficos do aplicativo. O valor do elemento LogLevel indica o nvel de log que deve ser utilizado para o aplicativo. Na ausncia deste elemento, ser utilizado o nvel de log Error. Existe um arquivo de log para registrar a sada e a entrada de mensagens no aplicativo, cujo nome mov.log, e um outro detalhando os erros ocorridos, chamado error.log. O nvel de log est relacionado com a quantidade de informaes no arquivo mov.log e a gerao ou no de registros no arquivo error.log. As informaes que fazem parte do arquivo error.log so as seguintes: Data; Hora; Elemento TrackingId da mensagem; Nome do produto aonde a mensagem foi gerada; Nome do aplicativo aonde a mensagem foi gerada;

Nome da transao; Verso da transao; Elemento Action da mensagem; Elemento KeyFields; Erro (Tipo, cdigo e descrio);

A seguir so listados os trs nveis de log disponveis e as informaes que so registradas para cada um deles no arquivo mov.log: 1. None: Usando este nvel de log, nenhuma informao sobre as mensagens que entraram e saram do produto registrada em qualquer um dos dois arquivos. 2. Error: Apenas so gravadas as informaes do arquivo de erro. Este o nvel de log default. 3. Terse: Apenas as informaes abaixo que faro parte do arquivo mov.log. Data; Hora; Indicao de se uma mensagem de Ao que est entrando no aplicativo (IN), se uma mensagem de Retorno gerada por ele (IN Ret), se uma mensagem de Ao originada pelo aplicativo e que est saindo dele (OUT) ou se uma mensagem de Retorno que o aplicativo recebeu em resposta a uma de Ao gerada por ele (OUT Ret); Indicao de se a mensagem de erro (ERROR) ou no (OK); Elemento TrackingId da mensagem; Nome do produto aonde a mensagem foi gerada; Nome do aplicativo aonde a mensagem foi gerada; Nome da transao; Verso da transao; Action da mensagem;

KeyFields;

4. Verbose: A mensagem inteira registrada no log, alm das informaes do nvel Terse.

TransactionSubscription.xml
Este arquivo est localizado na pasta xmlconf/[CodigoDoAplicativo], onde CodigoDoAplicativo o valor do elemento InstalledApplications/ListOfApplications/Application/Id do arquivo InstalledApplications.xml, localizado no diretrio um nvel acima deste. Neste arquivo so relacionadas as transaes que o aplicativo deseja receber e para qual adapter cada uma delas deve ser enviada. O Control Broker usa as informaes deste arquivo para fazer o roteamento das mensagens. Quando uma mensagem lhe entregue, ele identifica a transao e monta uma lista com os aplicativos de todos os produtos que assinaram esta transao. Se no existir este arquivo, o aplicativo nunca receber mensagens. Os produtos da Datasul j so distribudos com este arquivo criado para seus aplicativos.

O elemento raiz TransactionSubscription pode conter os elementos DefaultAdapter e ListOfTransaction. A principal utilidade do elemento DefaultAdapter facilitar a configurao de um adapter assncrono. Sempre que este elemento for informado e na configurao especfica de uma transao no for indicado um adapter, o valor dele ser associado a esta transao. Este elemento tem um atributo de nome

Type cujo valor Processing indica que ele sncrono e Transport que assncrono. O elemento ListOfTransaction pode conter vrias ocorrncias do elemento Transaction.

O elemento Transaction representa uma transao da qual o aplicativo deseja receber as mensagens relativas.

O elemento Name tem como valor o nome da transao de integrao. O elemento Adapter contm o nome do programa que deve receber as mensagens que sejam relativas transao escolhida. Caso este elemento no seja declarado, as mensagens da transao sero enviadas ao programa referenciado em DefaultAdapter. Se este tambm no for declarado, ser gerado um erro. Este elemento, assim como o DefaultAdapter, tambm tem um atributo Type com o mesmo significado j explicado. O elemento QueryAdapter apenas deve ser declarado no aplicativo que for o responsvel pela transao. Ele indica o programa que atender as mensagens

de consulta a esta transao. Se este elemento estiver presente na configurao de mais de um aplicativo para a mesma transao, ser gerado um erro. O elemento Instance deve ser usado para execuo exclusiva em um adapter de recebimento (axrut001.p) que tenha o valor no parmetro de execuo.

ProcessingInfo.xml
Assim como o arquivo TransactionSubscription.xml, este arquivo est localizado no diretrio especfico de um aplicativo abaixo da pasta xmlconf. Neste arquivo possvel indicar a necessidade de validar as mensagens que entram e saem do aplicativo e executar programas de personalizao nestas mesmas condies. Alm disso, atravs do arquivo ProcessingInfo.xml que definido que as mensagens que forem geradas no aplicativo devem estar com a indicao de que so para teste e que no devem ser efetivadas nos sistemas destino. A ausncia deste arquivo faz com que o sistema de integrao adote a opo padro para as caractersticas que aqui podem ser definidas. O elemento raiz ProcessingInfo pode ter como filhos os elementos DefaultsForInputMessage, DefaultsForOutputMessage e ListOfTransaction.

O elemento DefaultsForInputMessage tem como filho o elemento ValidationRequerid. O valor no associado a este elemento indica que as mensagens que chegarem a este aplicativo no devem ser validadas, a no ser que o contrrio seja especificado para alguma transao. Este elemento com o valor yes ou a ausncia dele tem o mesmo significado, uma vez que o comportamento padro do sistema de integrao validar as mensagens.

O elemento DefaultsForOutputMessage pode ter como filhos os elementos ValidationRequerid e ForTest. O valor no associado ao elemento ValidationRequerid indica que as mensagens que deixarem este aplicativo no devem ser validadas, a no ser que o contrrio seja especificado para alguma transao. Este elemento com o valor yes ou a ausncia dele tem o mesmo significado, uma vez que o comportamento padro do sistema de integrao validar as mensagens, conforme j observado. O valor yes associado ao elemento ForTest indica que as mensagens que forem criadas neste aplicativo devem estar sinalizadas como sendo para teste e no devem ser efetivadas no destino. Uma definio em contrrio para uma transao especfica muda este comportamento. Este elemento com o valor no ou a ausncia dele tem o mesmo significado, uma vez que o comportamento padro do sistema de integrao no gerar as mensagens como sendo para teste.

O elemento ListOfTransaction permite redefinir no nvel de transao as caractersticas configuradas como padro para o aplicativo atravs dos elementos DefaultsForInputMessage e DefaultsForOutputMessage. ListOfTransaction pode ter vrias ocorrncias do elemento Transaction.

No elemento Transaction so definidas as caractersticas de processamento de uma transao. Ele possui como filhos os elementos Name, InputMessage e OutputMessage. O valor do elemento Name o nome da transao para a qual sero especificadas caractersticas.

No elemento InputMessage so definidas caractersticas para as mensagens daquela transao que chegarem ao aplicativo.

O valor no associado ao elemento ValidationRequerid indica que as mensagens da transao em questo que chegarem ao aplicativo no devem ser validadas contra seus XML Schemas. Se este elemento no for definido, a deciso de validar ou no as mensagens deste tipo ser tomada de acordo com o elemento DefaultsForInputMessage. Se este tambm no existir, a mensagem ser validada, j que este o comportamento padro do sistema. O valor do elemento Customize a indicao de um programa que dever ser executado para fazer ou retirar a personalizao da mensagem antes que ela seja entregue ao adapter e validada. O programa de personalizao deve ter apenas um parmetro que deve ser INPUT-OUTPUT e do tipo HANDLE, aonde ser passada a mensagem XML a ser modificada. O elemento OutputMessage semelhante ao InputMessage, porm as caractersticas definidas afetam as mensagens que saem do aplicativo. Alm disso, ele pode ter como filho tambm o elemento ForTest.

A presena do elemento ForTest com o valor yes faz com que as mensagens que forem criadas neste aplicativo tenham a indicao de que so para teste e que no devem ser efetivadas nos sistemas de destino. Se este elemento no existir ser adotado o que foi definido em DefaultsForOutputMessage. Se l tambm no for especificado nada, as mensagens no devem ser geradas como sendo para teste, j que este o padro do sistema.

MessageConstants.xml
Este arquivo utilizado pelos adapters da Datasul na construo das mensagens de integrao. Ele tanto fornece valor para alguns elementos, como define se elementos opcionais devem ou no fazer parte das mensagens. Existe um deste arquivo por produto e, portanto, fica localizado no diretrio xmlconf. A ausncia deste arquivo indica que os aplicativos do produto apenas recebero mensagens ou no utilizaro os utilitrios do sistema de integrao para gerlas. Para os produtos da Datasul este arquivo obrigatrio e sua ausncia provocar um erro quando um adapter de um dos seus aplicativos for construir uma mensagem.

O elemento raiz deste arquivo se chama MessageConstants e pode ter como filhos os elementos Locale, TimeZone, SystemId, ReturnWithOriginalMessageHeaderInside e ServiceHeader.

O valor do elemento Locale utilizado no elemento DatasulMessage/MessageHeader/TransactionId/Locale e indica em que idioma est o contedo dos elementos da mensagem. Se este elemento no for declarado, na mensagem o elemento correspondente ter a indicao de que o idioma o Portugus. O valor do elemento TimeZone utilizado na construo do elemento DatasulMessage/MessageHeader/TransactionId/TrackingId/DateTime da mensagem. Esta informao est relacionada com o fuso horrio do local em que est o servidor que hospeda o sistema. Este valor deve estar na forma hh:mm e indica a diferena entre o horrio do local em questo e do Meridiano de Greenwich (GMT). Se no houver diferena, o caracter Z deve ser informado. Por exemplo, como o horrio de Braslia trs horas menor que o de Greenwich, para um servidor em Braslia este elemento deveria ter o valor -03:00.

O elemento SystemId contm os elementos Site, Host, Location e Comment. Durante a criao de mensagens pelos adapters, o valor destes elementos neste arquivo de configurao ser usado nos elementos de mesmo nome que so filhos de DatasulMessage/ServiceHeader/SystemId. O elemento ReturnWithOriginalMessageHeaderInside com o valor yes indica que as mensagens do tipo Retorno devem conter o MessageHeader da mensagem de Ao que a originou. Este elemento com o valor no ou sua ausncia faz com que as mensagens de Retorno no contenham o MessageHeader da mensagem de Ao. Como o elemento DatasulMessage/ServiceHeader opcional na mensagem padro Datasul, atravs do elemento ServiceHeader deste arquivo de configurao possvel indicar se ele deve ou no compor as mensagens geradas.

O elemento DefaultSendServiceHeader com o valor no indica que as mensagens devem ser geradas sem o elemento ServiceHeader, a no ser que para uma transao especfica seja dito o contrrio. Se este elemento no existir ou estiver com o valor yes e no houver uma configurao prpria para a transao, o elemento ServiceHeader ser criado na mensagem. O elemento ListOfTransaction pode conter vrias ocorrncias do elemento Transaction.

Atravs do elemento Transaction possvel mudar o comportamento padro do adapter com relao criao ou no do elemento ServiceHeader nas mensagens de uma transao especfica.

O elemento Name contm o nome da transao que est sendo configurada. O elemento SendServiceHeader com o valor no indica que, nas mensagens da transao aqui configurada, o elemento ServiceHeader no deve ser criado. O valor yes, obviamente, indica o contrrio.

config.xml
O arquivo config.xml, localizado no diretrio xmljserv, tem por funo indicar o servidor em que se encontram os servios de validao e transformao e as portas onde esto disponveis.

O elemento raiz JavaServices tem como filhos os elementos Host, Validation e Transformation.

O valor do elemento Host o nome do servidor onde os servios de validao e transformao esto hospedados. O valor do elemento Validation o nmero da porta onde o servio de validao est disponvel. O valor do elemento Transformation o nmero da porta onde o servio de transformao est disponvel. Para saber mais detalhes sobre estes servios consultar o captulo Validao e transformao.

productdir.xml
O arquivo productdir.xml usado exclusivamente pelo programa Java que fornece os servios de validao e transformao. Ele deve estar presente no diretrio xmljserv. O servio de validao alimentado por XML Schemas, enquanto que o de transformao utiliza arquivos no formato XSL. O programa que fornece estes servios, em sua inicializao monta uma lista com os arquivos destes tipos disponveis nos diretrios xmlschema e xmltransf. Ele procura estes diretrios abaixo da mesma pasta em que est seu prprio diretrio. Por exemplo, se este programa estiver sendo executado de C:\DATASUL EMS\2.04\xmljserv, ele varrer os diretrios C:\DATASUL EMS\2.04\xmlschema e C:\DATASUL EMS\2.04\xmltransf em busca dos arquivos citados. O arquivo productdir.xml permite que sejam informados outros diretrios que contenham as pastas xmlschema e xmltransf aonde o programa deve buscar os Schemas e os arquivos XSL. O elemento raiz ProductDir pode conter vrias ocorrncias do elemento Dir.

O valor do elemento Dir deve ser o nome de uma pasta que contenha os diretrios xmlschema e xmltransf. O programa que fornece os servios de validao e transformao procurar tambm nelas os arquivos que utiliza. Por exemplo, se neste elemento for informado o valor C:\ProdutoA, nos diretrios

C:\ProdutoA\xmlschema e C:\ProdutoA\xmltransf tambm sero utilizados na busca dos arquivos de Schemas e XSL.

ListOfProcess.xml
O arquivo ListOfProcess.xml usado exclusivamente pelos adapters de recebimento assncronos. Ele deve estar presente no diretrio dos adapters adapters/xml/utp. Seu objetivo de listar os estabelecimentos que um processo especfico ir utilizar como faixa de processamento. Segue abaixo a estrutura deste arquivo. O elemento raiz ListOfProcess pode conter vrias ocorrncias do elemento Process.

Dentro do elemento Process dever conter mais alguns elementos, entre eles o nome do processo e seus respectivos estabelecimentos.

Como podemos ver, o filho do elemento Process ter o nome do processo e a lista de estabelecimentos.

O ProcessName ter como valor o nome do processo, este ser informado ao iniciar o processo desejado.

O elemento ListOfBranchCode poder conter vrios elementos filhos

No elemento BranchCode deveremos informar o estabelecimento, ou melhor, o cdigo do estabelecimento informado pelo sistema gerador.

CAPTULO 3

Adapters Assncronos
Descrio Neste captulo so apresentados alguns aspectos dos Adapters Assncronos, como interagir com a tabela FILA-EAI, como configur-los e como execut-los corretamente. O objetivo dos adapters assncronos permitir a integrao entre aplicaes de forma assncrona, ou seja, sem que as aplicaes integradas estejam sempre conectadas permitindo com isso que elas continuem trabalhando normalmente se alguma aplicao no estiver disponvel.

Definies
Segue abaixo um fluxograma do processo de integrao.

A seguir so descritos os vrios componentes desta arquitetura. Control Broker: Componente responsvel por receber a mensagem XML e transportar (fazer o roteamento) para os destinos (adapters). Este componente apoiado por arquivos de configurao os quais contm as informaes de destino e programas a serem executados. (Desenvolvido em Progress) Assinc Receiver Adapter: Adapter Assncrono de Recebimento, responsvel pela obteno das mensagens na tabela FILA-EAI e envio ao Control Broker. Assinc Sender Adapter: Adapter Assncrono de Envio, responsvel pelo envio das mensagens XML tabela FILA-EAI. FILA-EAI: Tabela destinada a armazenar as mensagens XMLs, que sero lidas por outros sistemas ou que sero colocadas por outros sistemas. O acesso tabela fila-eai feito via ODBC ou JDBC utilizando o mecanismo SQL-92 do Progress. Sistema de Integrao Assncrono: Sistema destinado integrao assncrona. (Desenvolvido em qualquer linguagem) Os componentes Assinc Sender Adapter, Assinc Receiver Adapter e FILAEAI sero nosso foco principal neste capitulo.

Adapter Assncrono de Envio

Neste item saberemos mais sobre como configurar o adapter assncrono de envio para sua correta execuo pelo Control Broker.

InstalledApplications.xml
No arquivo InstalledApplications.xml localizado no diretrio xmlconf do produto, criar uma nova ocorrncia do elemento InstalledApplications /ListOfApplication/Application. Usar como valor de seu elemento filho Id a expresso Assinc. Criar abaixo do diretrio xmlconf a pasta Assinc e nela o arquivo TransactionSubscription.xml.

TransactionSubscription.xml
A forma de configurar este arquivo informando no elemento DefaultAdapter o caminho do adapter assncrono de envio padro conforme o exemplo abaixo. Deve ser informada tambm a lista de transaes que o Control Broker deve enviar para o adapter assincrono. Apenas as transaes que sero utilizadas pelo Hub devem ser informadas, evitando que mensagens desnecessrias sejam garavadas na tabela FILA-EAI. Vejamos abaixo um exemplo de arquivo de configurao destinado a executar o adapter assncrono de envio.
<TransactionSubscription xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="..\TransactionSubscription.xsd"> <DefaultAdapter Type="processing">adapters/xml/utp/axsut001.p</DefaultAdapter> <ListOfTransaction> <Transaction> <Name>Customer</Name> </Transaction> </ListOfTransaction> </TransactionSubscription>

Importante: As mensagens de consulta no devero ser enviadas aos adapters assncronos. Leia mais sobre o arquivo TransactionSubscription.xml no CAPITULO 2.

Adapter Assncrono de Recebimento

Neste item saberemos mais sobre como configurar o adapter assncrono de recebimento para que obtenha corretamente as mensagens da tabela FILA-EAI.

Processo de Recebimento
O adapter assncrono de recebimento, possui trs parmetros de entrada que sero informados ao iniciar a execuo por meio de um arquivo .PF.
Exemplo:

C:\Dlc91d\bin\prowin32.exe -ininame c:\xml.ini -pf c:\fila2.pf

Este arquivo deve possuir as seguintes opes configuradas: -p adapters\xml\utp\axrut001.p => indica que o adapter deve ser executado. -param (ex.: 1.30.process01.ems2.super.super.IN.NONSTOP), dever conter os parmetros de entrada, separados pelo caracter ponto (.): 1. O intervalo inicial de tempo de acesso ao banco de dados, em segundos; 2. O intervalo final de tempo de acesso ao banco de dados, em segundos; 3. O nome do processador. Este valor ser informado conforme o arquivo de configurao ListOfProcess.xml. IMPORTANTE, Informe (branco) para processar os demais estabelecimentos no definidos neste arquivo; 4. A identificao do produto para o qual sero processadas as mensagens assncronas, devendo ser um das seguintes opes: ems2, ems5 ou hr; 5. O nome do usurio que ser utilizado para efetuar login automtico no produto informado; 6. A senha do usurio que ser utilizado para efetuar login automtico no produto informado; 7. O tipo de mensagem a ser processada, informando-se os valores: IN (padro) ou OUT. O valor IN indica ao adapter de recebimento que as mensagens que esto sendo enviadas para o produto Datasul devem ser processadas. J o valor OUT indica que as mensagens que o produto Datasul est enviando, geralmente para um sistema externo, devem ser processadas;

8. O tipo de comportamento para processamento da fila de integrao, que pode ser contnuo ou no contnuo, informando-se os valores: NONSTOP (padro) ou STOP. O valor NONTOP indica ao adapter de recebimento que caso ocorram erros no processamento de uma mensagem, o adapter deve continuar o processamento da fila normalmente. J o valor STOP indica que no caso da ocorrncia de erros, o processamento da fila deve ser interrompido e a mensagem no deve sofrer nenhuma mudana no seu estado. 9. Permitir a gravao de log de determinados pontos do adapter e do Control Broker. O valor YES indica que a gravao de log est ativada. O valor NO (padro) indica que a gravao de log est desativada. 10. Identificao da instncia a ser executada pelo adapter. Ir processar transaes especificadas na tag Instance da assinatura da transao (TransactionSubscription.xml). Caso o valor no seja informado, ir executar todas as transaes que no possurem instncia definida na assinatura da transao. Intervalo INCREMENTAL de acesso banco: O intervalo inicial ser utilizado na primeira vez que a rotina no encontrar nenhum registro na tabela fila-eai a ser lido. Se aps esta verificao a rotina no encontrar novamente ir aguardar o dobro do intervalo de tempo inicialmente aguardado. Se pela terceira vez no encontrar novamente um registro a ser processado, aguardar o dobro do intervalo anterior. E esta lgica repetir at alcanar o intervalo final, e nele permanecer at encontrar algum registro a ser processado, e quando isto acontecer iniciar todo o processo novamente. -b => dever informar este parmetro para que a seo seja executada sem segundo plano.

ListOfProcess.xml
Primeiramente dever configurar o arquivo ListOfProcess.xml, que conter os processos e seus respectivos estabelecimentos. Estes valores sero utilizados futuramente para obter quais os estabelecimentos que um processo deve

processar. Para saber mais sobre este arquivo de configurao v ao capitulo Arquivos de configurao.

Regras de execuo
Lembrando que por via de regra, o administrador que estiver configurando os processos que sero iniciados, dever estar atento aos detalhes de execuo, um deles que deve iniciar um processo para cada registro contido no arquivo de configurao ListOfProcess.xml e mais um processo com o nome do processo em branco, para que este ultimo possa processar todas as mensagens que no estejam no arquivo de lista de processos. Ento, caso o administrador no queira iniciar processos em separado devido baixa demanda de processamento, poder no informar arquivo algum de configurao e passar como parmetro de entrada no nome do processo um valor em branco. Importante efetuar corretamente este procedimento para que no deixemos cair no esquecimento algum estabelecimento resultando num acumulo de mensagens e conseqentemente um atraso excessivo das solicitaes dos usurios. Devemos iniciar o(s) processo(s) aps termos o banco de dados servido, ou melhor, disponvel para acesso.

Aps iniciar o(s) processo(s)

Devemos verificar entre todos os processos iniciados, se algum deles iniciou e finalizou automaticamente, em caso positivo, verifique junto ao arquivo de LOG se nele contm mensagens de erro. Esta situao ocorre normalmente quando o Adapter de Recebimento Assncrono no encontrou o Control Broker, ou ocorreu algum erro ao interpretar o arquivo de configurao. Este arquivo de LOG deve estar contido num subdiretrio do adapters de recebimento assncrono e este diretrio dever ser chamado de LOG. Para pararmos os processos iniciados, devemos finaliz-lo no sistema operacional (ex.: kill no Unix) ou finalizar automaticamente quando efetuado o shuttdown no banco de dados que contm a tabela FILA-EAI.

Estrutura tabela FILA-EAI

A tabela FILA-EAI a interface pela qual outros sistemas estaro se comunicando com o produto Datasul de forma assncrona. Ao ler ou gravar

nesta tabela importante respeitar as regras especificadas para cada um dos campos descritos abaixo:

NUM-PARTE
Identifica se o contedo da mensagem teve que ser dividida em partes devido ao tamanho mximo permitido para um campo texto no banco de dados, seu formato ser do tipo inteiro com quatro dgitos. Os valores de 1 at 9998 identificam as vrias partes em ordem e o valor 9999 identifica a ltima parte existente. Este campo faz parte da chave primria.

CDN-TIPO-FILA
Identifica o tipo da Fila, ou melhor, qual o seu destino. Seu valor do tipo inteiro com uma posio. O valor 1 para mensagens destinadas ao sistema de Integrao assncrona e o valor 2 para mensagens destinadas ao Control Broker. Este atributo faz parte da chave primaria. Observao, o sistema Control Broker verifica todas as mensagens que so de valores 2 e o sistema de integrao assncrona verifica todas que esto com o valor 1.

DTA-GERACAO
Identifica a data/hora que a mensagem foi gerada, normalmente obtida na prpria mensagem XML. Seu formato do tipo caracter de dezenove dgitos. O valor que estar contido ser YYYY/MM/DD hh:mm:ss. Este atributo faz parte da chave primaria. Estes valores serviro para ordenar as mensagens que sero processadas, nunca esquecendo de validar a prioridade. A data/hora dever estar no GMT 00:00. No caso do adapter de envio, o valor ser obtido da prpria mensagem e convertido antes de atribuir a tabela FILA-EAI.

DTA-GERACAO-ORIG
Identifica a data/hora que a mensagem original (de negcio) foi gerada, normalmente obtida na prpria mensagem XML. Este campo somente usado nas mensagems de Retorno OK ou Retorno com Erro. Seu formato do tipo caracter de dezenove dgitos. O valor que estar contido ser YYYY/MM/DD hh:mm:ss. A data/hora dever estar no GMT 00:00. Esse valor serve para permitir a rastrear a(s) mensagem(s) de retorno para uma mensagem de

negcio. No caso do adapter de envio, o valor ser obtido da prpria mensagem e convertido antes de atribuir a tabela FILA-EAI.

TRACKING-ID
Identifica a o ID da mensagem que foi gerada, normalmente obtida na prpria mensagem XML. Seu tipo inteiro com at nove (9) dgitos. Este campo mandatrio. No caso do adapter de envio, o valor ser obtido da prpria mensagem e convertido antes de atribuir a tabela FILA-EAI.

TRACKING-ID-ORIG
Identifica a o ID da mensagem original (de negcio) que foi gerada, normalmente obtida na prpria mensagem XML. Este campo somente usado nas mensagems de Retorno OK ou Retorno com Erro. Seu tipo inteiro com at nove (9) dgitos. Esse valor serve para permitir a restrear a(s) mensagem(s) de retorno para uma mensagem de negcio. No caso do adapter de envio, o valor ser obtido da prpria mensagem e convertido antes de atribuir a tabela FILAEAI.

NUM-SEQUENCIA-FILA
Este atributo serve para diferenciar mensagens geradas no mesmo segundo. Seu formato inteiro de dois dgitos. Este atributo faz parte da chave primaria. Este valor tambm ser utilizado para dar seqncia ao processamento dos registros.

NUM-ESTADO
Este atributo indica o estado da mensagem, onde pode ter sido processada ou no. Seu formato inteiro com duas posies, seu valor padro 00 e significa que a mensagem ainda no foi processada, quando informado 01 significa que a mensagem no foi processada por solicitao do usurio, este caso normalmente informado manualmente pelo usurio. Quando informar 96 associamos que a mensagem foi processada, mas nenhum adapter o assina a transao, 97 a mensagem foi processada, mas ocorreu erro durante ou aps o processamento, 98 a mensagem foi removida pelo usurio, este caso normalmente ocorre quando o usurio decide eliminar a mensagem, mas para no eliminar ele atribui a 97 (backup) e finalmente 99 quando a mensagem

foi processada com sucesso. Somente sero considerados para processamento as mensagens com cdigo zero, as demais sero ignoradas.

NUM-PRIORIDADE
Este atributo informa a prioridade de processamento da mensagem. Seu formato inteiro de trs dgitos podendo variar de 000 999, seu valor padro 500. No pertence a chave primaria. As mensagens com maior prioridade devem ter valor inferior a 500 e mensagens com prioridade inferior devem ter valor superior a 500.

NUM-TOTAL-PARTES
Identifica qual foi o nmero total de partes geradas, no caso da mensagem ter sido dividida. Seu formato do tipo inteiro de quatro dgitos. informado 1 quando existe somente uma parte e informado 2 at 9998 quando a mensagem possui de 2 a 9998 partes. Quando o valor deste campo for 0, a mensagem XML est armazenada somente no registro corrente e no campo DES-XML que do tipo CLOB capaz de armazenar at 1Gb de dados (disponvel somente para banco de dados Progress 10 ou superior). Este atributo no faz parte da chave primaria. utilizado para verificar se todas as partes foram recebidas, sendo assim possvel montar a mensagem XML.

CDN-TIPO-MENSAGEM
Este atributo identifica o tipo da mensagem. Seu formato caracter de uma posio. Informamos 0 para mensagens de negcio, 1 para mensagens de erro e 2 para mensagens de retorno OK. Este atributo no faz parte da chave primaria.

COD-TIPO-TRANSACAO
Identifica o tipo de transao que est contida na mensagem, este valor ser utilizado para verificar se a mensagem assinada por algum adapter. Seu formato caracter com quarenta posies. Seu atributo no pertence a chave primaria.

DES-VERSAO-TRANSACAO

Identifica qual a verso da transao. Seu formato caracter de sete dgitos. Seu atributo no pertence chave primaria. Exemplo de valor 200.000.

DES-CONTEUDO
Neste atributo temos o contedo da mensagem, ou fragmentos, dependendo do tamanho da mensagem. Seu formato caracter de trinta mil posies. Seu atributo no pertence chave primaria.

DES-USUARIO-ALTERACAO
Neste campo dever conter o ltimo usurio que efetuou uma alterao na tabela FILA-EAI atravs de programas de gerenciamento. Seu formato do tipo caracter de doze dgitos. Seu atributo no pertence chave primaria.

DTA-ALTERACAO
Identifica a Data/Hora que o usurio alterou o registro na tabela FILA-EAI. Seu formato do tipo caracter de dezenove dgitos. Seu atributo no pertence a chave primaria.

DES-OBSERVACAO
Neste atributo informamos as observaes, estas observaes sero modificadas tanto pelo usurio, quanto pelo sistema ao encontrar excees que necessitam registrar observaes para o administrador. Este dado importante para manter o histrico da mensagem. Seu formato do tipo caracter de duzentos dgitos. Seu atributo no pertence chave primaria.

COD-ESTABELECIMENTO
Neste atributo informado o cdigo do estabelecimento para fins de processamento, este cdigo ser o mesmo informado no arquivo de configurao ListOfProcess.xml, para saber mais sobre como configurar este arquivo, v ao capitulo Arquivos de configurao. Seu formato do tipo caracter de vinte posies. Seu atributo no pertence chave primaria. Lembrando que informamos o cdigo do estabelecimento a fim de efetuar processamentos direcionados.

COD-PROGRAMA
Neste atributo informamos o nome do programa que gerou a mensagem no sistema de origem. Seu formato caracter de vinte posies. No faz parte da chave primaria.

DES-VERSAO-PROGRAMA
Neste programa obteremos a verso do programa que gerou a mensagem na fila. Seu formato caracter com cinco posies. No pertence a chave primaria.

COD-USUARIO
Neste atributo teremos o usurio que gerou a mensagem no sistema de origem. O Formato do tipo caracter de vinte posies. No pertence a chave primaria.

DES-REFERENCIA-CONTEUDO
Obtemos neste atributo referencias do contedo, ou melhor, palavras-chave sobre o contedo da mensagem. Seu formato caracter de trinta posies, e no esta contida na chave primaria. Este campo deve ser informado na origem, sendo que nas mensagens de negcio devem conter uma breve chave do CONTEUDO e nas de erro deve estar fixo Erro. A origem destes valores ser obtida do ListOfKeyFields da mensagem XML e separados por virgula.

NUM-VARIACAO-HORA
Neste atributo temos a variao horria entre o fuso horrio da origem e GMT 0 (zero). O valor poder ser tanto positivo quanto negativo dependendo do hemisfrio (Oriental/Ocidental). Seu formato do tipo inteiro de duas posies. Seu valor padro 0 (zero). No pertence a chave primaria. O valor dessa variao ser obtido da mensagem XML, durante seu envio tabela FILA-EAI.

DES-XML
Neste atributo temos o contedo completo da mensagem. O uso deste campo indicado atravs do atributo NUM-TOTAL-PARTES = 0 (zero), disponvel

apenas para verses 10 e superiores do Progress. Seu formato CLOB (character long object) com 100Mb de capacidade. Seu atributo no pertence chave primaria.

Acessando a tabela FILA-EAI

As informaes abaixo sero teis ao desenvolvedor que desejar construir adapters que tenham interao com a tabela FILA-EAI.

Gravando na tabela FILA-EAI

As regras de gravao na tabela FILA-EAI, caso for utilizado Progress com verso menor que 10 ou dataserver, so: 1. A mensagem XML deve ser fragmentada em elementos de 30.000 caracteres; 2. Estes fragmentos CONTEUDO; devem ser adicionados no atributo DES-

3. Cada fragmento ser um registro no banco de dados contendo a mesma DTA-GERACAO, TRACKING-ID, DTA-GERACAO-ORIG, TRACKING-ID-ORIG e CDN-TIPO-FILA; 4. As mensagens de retorno devem ter em TRACKING-ID-ORIG e DTAGERACAO-ORIG os valores desses campos na mensagem original (de negcio). 5. As PARTES devero ser numeradas de forma crescente; 6. No caso da mensagem conter uma nica parte devemos informar 0 (zero) no atributo NUM-PARTE; 7. No caso da mensagem conter mais do que uma parte e for a ultima mensagem, devemos informar (9999) no atributo NUM-PARTE; 8. Devemos informar o total de partes no atributo NUM-TOTALPARTES; 9. IMPORTANTE: o numero da seqncia (NUM-SEQUENCIA) dever possuir como valor inicial 0 (zero) e ser acrescido no caso de encontrar outro(s) registro(s) com a mesma DTA-GERACAO e CDNTIPO-FILA;

10. Para a mensagem ser processada o atributo NUM-ESTADO deve ter o valor 0 (zero); 11. preciso lembrar de informar o valor correto no atributo CDN-TIPOFILA; Neste atributo deve informar quem ser o destino desta mensagem, informe 1 para mensagens destinadas ao sistema de integrao assncrona e 2 para mensagens destinadas ao Control Broker; Caso seja utilizado Progress 10 ou superior, as regras so: 1. A mensagem XML deve ser armazenada no campo DES-XML; 2. As mensagens de retorno devem ter em TRACKING-ID-ORIG e DTAGERACAO-ORIG os valores desses campos na mensagem original (de negcio). 3. No caso da mensagem conter uma nica parte devemos informar 0 (zero) no atributo NUM-PARTE; 4. Devemos informar o 0 (zero) no atributo NUM-TOTAL-PARTES; 5. IMPORTANTE: o numero da seqncia (NUM-SEQUENCIA) dever possuir como valor inicial 0 (zero) e ser acrescido no caso de encontrar outro(s) registro(s) com a mesma DTA-GERACAO e CDNTIPO-FILA; 6. Para a mensagem ser processada o atributo NUM-ESTADO deve ter o valor 0 (zero); 7. preciso lembrar de informar o valor correto no atributo CDN-TIPOFILA; Neste atributo deve informar quem ser o destino desta mensagem, informe 1 para mensagens destinadas ao sistema de integrao assncrona e 2 para mensagens destinadas ao Control Broker; Para saber mais sobre o que faz cada atributo da tabela FILA-EAI, leia o item Estrutura tabela FILA-EAI.

Lendo da tabela FILA-EAI

Anteriormente definimos que a mensagem pode ser fragmentada em elementos de 30.000 caracteres ou armazenada em um nico registro. Por este motivo deveremos l-la da mesma forma que a geramos, isto , unir os elementos (registros) para gerarmos uma nica mensagem ou lendo o contedo de outro registro. As regras de leitura da tabela FILA-EAI so: Para Progress < 10 e Dataservers: 1. Inicialmente devemos localizar a ltima parte da mensagem; 2. Este processo de localizao da ultima parte da mensagem simples, porm devemos dobrar nossas atenes neste processo: a. Primeiramente, dever verificar se a mensagem possui mais do que um fragmento. Se o atributo NUM-TOTALPARTES contiver o valor 1 (um) e o atributo NUMPARTE contiver o valor 0 (zero), conseqentemente localizamos o primeiro e nico fragmento da mensagem. b. No caso do atributo NUM-TOTAL-PARTES contiver o valor maior que 0 (zero) o atributo NUM-PARTE dever conter o valor 9999 para ser o ultimo fragmento. c. Exemplo no Progress:
FOR EACH fila-eai WHERE fila-eai.cdn-tipo-fila fila-eai.num-estado ((fila-eai.num-parte fila-eai.num-total-partes (fila-eai.num-parte fila-eai.num-total-partes = = = = = > 1/2 AND 0 AND 0 AND 1 ) OR 9999 AND 1 )):

3. Aps localizarmos o registro desejado; 4. Verifique se este j foi bloqueado por outro usurio; 5. Em caso negativo devemos bloque-lo: a. Exemplo no Progress: exclusive-lock; 6. Verificar se a mensagem possui todas as partes que o atributo NUM-TOTAL-PARTES esta informando. De que forma? Contando os fragmentos e comparando com o atributo NUMTOTAL-PARTES; 7. Em caso negativo:

a. Deve abortar a operao, porm antes deve associar ao atributo NUM-ESTADO de todos os fragmentos encontrados, o valor 97 e ao atributo DES-OBSERVACAO uma observao de que a mensagem encontrada falta fragmentos para ser processada com sucesso. 8. Em caso positivo: a. Deve adicionar os fragmentos numa varivel do tipo MEMPTR para uso futuro; 9. Nesta etapa o desenvolvedor possui em mos uma varivel contendo a mensagem desfragmentada; Para Progress >= 10: 1. Ao ler o registro, se o atributo NUM-TOTAL-PARTES contiver o valor 0 (zero), sabemos que a mensagem XML est armazenada no campo DES-XML. 2. Verifique se este j foi bloqueado por outro usurio; 3. Em caso negativo devemos bloque-lo: a. Exemplo no Progress: exclusive-lock; 4. Adicionar os fragmentos numa varivel do tipo MEMPTR para uso futuro; a. Exemplo no Progress:
COPY-LOB FROM fila-eai.des-xml TO mResultXML CONVERT TARGET CODEPAGE "IBM850".

5. Nesta etapa o desenvolvedor possui em mos uma varivel contendo a mensagem;

Para saber mais sobre o que faz cada atributo da tabela FILA-EAI, leia o item Estrutura tabela FILA-EAI.

Gravando na tabela FILA-EAI em Banco de Dados ORACLE

Quando a tabela FILA-EAI estiver armazenada em um banco de dados Oracle, para um programa no-PROGRESS inserir mensagens destinadas integrao, informaes extras devem ser fornecidas para permitir a correta leitura das mensagens pelos programas PROGRESS. Alm de seguir as instrues contidas no item: Gravando na tabela FILA-EAI, voc deve inserir os seguintes campos na tabela FILA-EAI: 1. 2. 3. 4. 5. 6. O campo U##CDN_TIPO_MENSAGEM UPPPERCASE(CDN_TIPO_MENSAGEM). O campo U##COD_TIPO_TRANSACAO UPPERCASE(COD_TIPO_TRANSACAO). O campo U##COD_ESTABELECIMENTO UPPERCASE(COD_ESTABELECIMENTO). O campo U##DTA_GERACAO UPPERCASE(DTA_GERACAO) O campo U##DTA_GERACAO_ORIG UPPERCASE(DTA_GERACAO_ORIG) deve deve deve deve deve receber receber receber receber receber

O campo PROGRESS_RECID deve receber FILA_EAI_SEQ.NEXTVAL.

Deste modo os dados ficam disponveis logo aps o COMMIT.

CAPTULO 4

Monitor da Fila de Integrao

Descrio Neste captulo so apresentadas informaes a respeito de como utilizar o Monitor da fila de integrao para administr-la.

Caractersticas
Atravs do Monitor possvel gerenciar as mensagens de integrao assncrona. As mensagens a serem visualizadas no Monitor podem ser selecionadas de acordo com seu destino, seu estado de processamento, seu tipo, o estabelecimento e a transao aos quais esto associadas e a data em que foram geradas. Atravs do Monitor, tambm possvel alterar o estado de processamento da mensagem, sua prioridade e o estabelecimento que est associado a ela, alm de seu prprio contedo. Na tela de manuteno de mensagens h um espao disponvel para incluir informaes que justifiquem a alterao feita.

Selecionando mensagens para exibio

Abaixo apresentada a tela principal do Monitor.

Quando o Monitor executado ele exibe as mensagens de entrada (Destino = IN), cujo estado seja No processada e que tenham sido geradas nos ltimos 30 dias. Para visualizar um conjunto diferente de mensagens, o usurio deve definir valores para os critrios desejados, atravs dos campos na tela, e acionar o boto Atualizar. Abaixo so relacionados os principais elementos de tela utilizados: Boto Nome Atualizar Descrio Exibir as mensagens que correspondam aos critrios de seleo definidos.

Campo Status

Descrio Escolher o estado de processamento que deve ter a mensagem para ser exibida. No processada: Indica que a mensagem ainda no foi manipulada no sistema de destino. Suspensa: Indica que a mensagem no deve ser processada, por enquanto. No assinada: Indica que a mensagem foi recebida no sistema de destino, porm no foi processada l porque a transao de negcio a qual est associada no tratada por ele. Erro: Indica que o sistema de destino no encontrou algum problema ao recuperar a mensagem da fila. Eliminada: Indica que a mensagem no deve ser processada definitivamente. Processada: Indica que a mensagem foi efetivada com sucesso no sistema de destino. Escolher o tipo do qual a mensagem deve ser para ser exibida. Todos: Indica que a mensagem deve ser exibida independentemente de seu tipo. Negcio: Indica que a mensagem foi gerada a partir da execuo de um processo de negcio em um sistema. Retorno OK: Indica que a mensagem foi gerada por um sistema em resposta a uma mensagem de Negcio recebida que foi processada com sucesso. Retorno Erro: Indica que a mensagem foi gerada por um sistema em resposta a uma mensagem de Negcio recebida que apresentou problemas em seu processamento.

Tipo

Nome da Transao Informar o nome da transao de negcio relativa a qual deve ser a mensagem para ser exibida. Estabelecimento Destino Informar o estabelecimento relativo ao qual deve ser a mensagem para ser exibida. Selecionar o destino que a mensagem deve ter para ser exibida. IN: Mensagem de entrada. aquela a ser processada pelo produto do qual o Monitor faz parte.

OUT: Mensagem de sada. aquela que gerada pelo produto do qual o Monitor faz parte. Perodo Informar o perodo dentro do qual a mensagem deve ter sido gerada para ser exibida.

Alterando uma mensagem

Abaixo apresentada a tela de manuteno de mensagens do Monitor.

Para a mensagem selecionada na tela principal do Monitor, esta tela traz as informaes a seu respeito presentes na fila, alm de seu prprio contedo. Aps alterar estes dados, o usurio deve acionar o boto OK para que estas modificaes sejam salvas e a janela fechada. Se o usurio acionar o boto Cancelar, as alteraes sero ignoradas e a janela fechada. Abaixo so relacionados os principais elementos de tela utilizados: Campo Status Descrio Novo estado de processamento para a mensagem. A descrio de cada estado idntica quela apresentada para a tela principal do Monitor. Estabelecimento ao qual a mensagem deve ser associada. Prioridade de processamento que a mensagem deve ter. O valor padro 500. As mensagens com maior prioridade devem ter valor inferior a 500 e mensagens com menor prioridade devem ter valor superior a 500. Comentrios sobre a alterao realizada na mensagem ou nas informaes associadas a ela. O prprio contedo da mensagem XML.

Estabelecimento Prioridade

Observao Mensagem XML

CAPTULO 5

Validao e Transformao
Descrio Neste captulo so apresentados alguns aspectos dos servios de validao e transformao, como configur-los e como executar o programa Java que os disponibiliza.

Configurao
Os servios de validao e transformao so utilizados por componentes do sistema de integrao. Estes servios so fornecidos por uma aplicao Java que disponibilizada no diretrio xmljserv dos produtos Datasul. Esta aplicao Java precisa estar rodando apenas em uma mquina, que atuar como o servidor destes servios para todo o ambiente. Se, na mquina escolhida para esta funo, no estiverem acessveis os programas de algum dos produtos Datasul, um deles deve ser instalado nela. Na seo config.xml do captulo Arquivos de configurao descrita a estrutura do arquivo de mesmo nome, localizado na pasta xmljserv. L explicado que os elementos Host, Validation e Transformation fornecem, respectivamente, o nome do servidor que hospeda os servios, a porta para validao e a porta para transformao. Este arquivo utilizado tanto pelos adapters Datasul para saber onde procurar pelo servio, quanto pelo aplicativo que os disponibiliza. Se os programas que compem o produto Datasul estiverem numa unidade de rede e forem acessados tanto pelos usurios em suas estaes, quanto por esta aplicao Java num servidor especfico, o arquivo apenas ter que ser configurado uma vez. Caso os programas estejam em locais diferentes em cada

um destes casos, imprescindvel que os arquivos config.xml tenham os mesmos valores para seus elementos equivalentes. Conforme o caso, pode ser necessrio ter que configurar tambm o arquivo productdir.xml, conforme explicado na seo de mesmo nome.

Colocando os servios no ar
A inicializao dos servios feita atravs de um script localizado no diretrio xmljserv da instalao do produto Datasul utilizado. Em ambiente Windows, deve ser aberta uma janela de comandos (Command Prompt), mudar para o diretrio xmljserv na instalao do produto Datasul e digitar startjserv. Em ambiente Unix/Linux, deve ser aberta uma nova seo, mudar para o diretrio xmljserv na instalao do produto Datasul, dar permisso de execuo ao arquivo startjserv e execut-lo. Em ambos os casos, a verso do JDK 1.3 ou superior deve estar instalada e fazer parte do Path do sistema. Para saber se estes requisitos esto atendidos, basta digitar java version e pressionar a tecla <ENTER>. Para interromper a execuo do programa, basta pressionar simultaneamente as teclas <CTRL> e <C>.

CAPTULO 6

Configurao passo a passo

Descrio Neste captulo so apresentados os passos que devem ser seguidos para a configurao do ambiente de integrao.

Configurando os atalhos
Durante o processo de integrao, um adapter pertencente a um produto executa o Control Broker e lhe passa uma mensagem XML. O Control Broker identifica quais programas se inscreveram para receber as mensagens daquele tipo e os executa um a um. Obviamente, alguns destes programas a serem executados fazem parte de outros produtos. Portanto, necessrio configurar o atalho de execuo do menu de cada produto de forma que, na sesso Progress, os bancos de dados de todos eles estejam conectados e a pasta de cada um deles faa parte do ProPath para que os programas possam ser encontrados.

Configurando os produtos
Para que a integrao entre os produtos acontea de maneira correta, as seguintes tarefas devem ser executadas para cada um deles: 1. Na pasta xmlconf, incluir no arquivo InstalledApplications.xml a lista de aplicativos adquiridos daquele produto. 2. Ainda na pasta xmlconf, criar o arquivo MessageConstants.xml com as informaes a serem usadas nas mensagens geradas pelos aplicativos do produto.

3. Na pasta de cada um dos aplicativos do produto, localizada tambm em xmlconf, criar o arquivo ProcessingInfo.xml se for desejado mudar o comportamento padro do sistema de integrao com relao validao, personalizao e gerao de mensagens de teste. 4. No diretrio xmljserv, configurar o arquivo config.xml. Este passo pode ser desnecessrio se este arquivo j tiver sido configurado para executar a aplicao que disponibiliza os servios de validao e transformao. Observao Mesmo aps terem sido configurados todos os produtos, antes que qualquer programa seja executado, os servios de validao e transformao devem ser colocados no ar. Caso haja integrao assncrona, o adapter de recebimento deve ser inicializado tambm.

Configurando cdigo de pgina da Sesso Java

Na bat de execuo da sesso Java de uma aplicao que se integra ao EMS atravs do EAI, deve-se passar na chamada da aplicao um argumento para o runtime Java, informando o cdigo de pgina utilizado pelo Progress. Esta ao visa evitar problemas com caracteres acentuados que os arquivos XML envolvidos na transao possam conter. Caso contrrio a conexo JDBC no ir reconhecer estes caracteres. O cdigo de pgina utlizado passado atravs do argumento -Dfile.encoding conforme exemplo abaixo: SET DLC=C:\Dlc91e SET JAVA_HOME=C:\j2sdk1.4.2_04 SET PATH=%DLC%;%DLC%\bin;%JAVA_HOME%;%JAVA_HOME %\bin;%PATH% cd C:\datasul\util java -Dfile.encoding=ISO8859-1 JDBCAccess_Grant_Integracao rplcxssr23 50450 ems204 pause No exemplo acima, a aplicao JDBCAccess_Grant_Integracao chamada recebendo os argumentos rplcxssr23, 50450 e ems204, enquanto que passado para o runtime do JAVA que o cdigo de pgina deve ser o ISO8859-1.

CAPTULO 7

Customizao de Transaes
Descrio Neste captulo so apresentados os passos que devem ser seguidos para customizar as transaes do EAI e o mtodo isSubscribed.

Customizando Transaes
Foram criados seis pontos de customizao de mensagens. Esses pontos executam a chamada para um mesmo programa cuja finalidade permitir que o cliente crie programas que repliquem transaes e alterem as informaes necessrias para sua customizao. Os pontos de customizao criados so BeforeCreateXML, AfterCreateXML, AfterGenerateXML, AfterParseMessage, BeforeCreateXMLReceipt e AfterCreateXMLReceipt. Os pontos BeforeCreateXML, AfterCreateXML e AfterGenerateXML so executados antes do Message Handler enviar a mensagem para o Control Broker. J os pontos BeforeCreateXMLReceipt, AfterCreateXMLReceipt e AfterParseMessage so executados quando o Message Handler recebe o XML de resposta do Control Broker. O ponto AfterGenerateXML insere uma tag customizada, chamada CustomInformation, de acordo com a execuo do programa xmlcustom/getreturnmessagecustomprogram.p, na mensagem de envio do produto Datasul ao meio externo. J o ponto AfterParseMessage, obtm o contedo da tag CustomInformation de uma mensagem de recebimento para o produto Datasul, para que o programa xmlcustom/getreturnmessagecustomprogram.p a processe da maneira adequada.

Para um exemplo mais detalhado de customizao XML, utilizando os pontos AfterGenerateXML e AfterParseXML, consulte o manual de referncia do EAI, em Cenarios de Integrao Como fazer Customizando Mensagens XML. Para fazer a customizao das transaes deve ser criado um programa chamado xmlcustom/getreturnmessagecustomprogram.p e o ele deve seguir os passos descritos abaixo para funcionar adequadamente.

Declarando include padro

A definio de algumas temp-tables do programa de customizao encontramse na include tterrret.i e deve ser utilizada no programa conforme o exemplo abaixo.
Exemplo:
{xmlinc/tterrret.i}

Definindo temp-table de comunicao

O programa de customizao deve possuir a definio da temp-tables de comunicao ttListOfKeyField de acordo com o exemplo abaixo.
Exemplo:
/* TEMP-TABLE PARA ARMAZENAR A LISTA DE KEY FIELDS */ DEF TEMP-TABLE ttListOfKeyField NO-UNDO FIELD NameField AS CHAR FIELD valueField AS CHAR.

Definindo parmetros do programa de customizao

Para o correto funcionamento do programa de customizao necessrio que sejam definidos alguns parmetros que sero utilizados para receber e enviar informaes para o Message Handler. A definio dos parmetros deve ser feita de acordo com o exemplo abaixo.
Exemplo:
/* Definio dos parmetros de customizao */ DEF INPUT PARAM phDocumentXml AS HANDLE NO-UNDO. DEF INPUT PARAM pProdName AS CHAR NO-UNDO. DEF INPUT PARAM pAppName AS CHAR NO-UNDO.

DEF DEF DEF DEF DEF DEF DEF DEF DEF

INPUT PARAM pTransaction AS CHAR NO-UNDO. INPUT PARAM pEvent AS CHAR NO-UNDO. INPUT PARAM pAction AS CHAR NO-UNDO. INPUT PARAM plIsProcessed AS LOG NO-UNDO. INPUT PARAM pcPoint AS CHAR NO-UNDO. INPUT PARAM TABLE FOR ttListOfKeyField. INPUT-OUTPUT PARAM TABLE FOR ttListOfExtraInformation. INPUT PARAM TABLE FOR ttListOfError. INPUT PARAM phMessageHandler AS HANDLE NO-UNDO.

Abaixo segue a relao dos parmetros e o que cada um deles est recebendo. phDocumentXml: Essa varivel vai receber o handle para a mensagem XML que est sendo gerada; pProdName: recebe o valor do produto que est gerando a mensagem. pAppame: recebe o valor da aplicao que est gerando a mensagem; pTransaction: recebe o nome da transao que est sendo enviada. pEvent: recebe o valor do evento da transao; pAction: recebe o valor da ao da transao; plIsProcessed: possui a informao se a transao foi ou no foi processada; pcPoint: possui o valor do ponto de customizao que est sendo disparado; ttListOfKeyField: recebe a temp-table com a lista de keyfields da mensagem; ttListOfExtraInformation: recebe a temp-table da lista de informaes extras da transao; ttListOfError: recebe a temp-table com a lista de erros que ocorreram at aquele momento na execuo da transao; phMessageHandler: recebe o handle da instncia do programa message_handler que chamou a execuo do programa customizado.

Abaixo segue um exemplo de programa de customizao que ir exibir o nome da transao que est sendo customizada.

Exemplo:
/* Include Padro */ {xmlinc/tterrret.i} /* TEMP-TABLE PARA ARMAZENAR A LISTA DE KEY FIELDS */ DEF TEMP-TABLE ttListOfKeyField NO-UNDO FIELD NameField AS CHAR FIELD valueField AS CHAR. /* Definio dos parmetros de customizao */ DEF INPUT PARAM phDocumentXml AS HANDLE NO-UNDO. DEF INPUT PARAM pProdName AS CHAR NO-UNDO. DEF INPUT PARAM pAppName AS CHAR NO-UNDO. DEF INPUT PARAM pTransaction AS CHAR NO-UNDO. DEF INPUT PARAM pEvent AS CHAR NO-UNDO. DEF INPUT PARAM pAction AS CHAR NO-UNDO. DEF INPUT PARAM plIsProcessed AS LOG NO-UNDO. DEF INPUT PARAM pcPoint AS CHAR NO-UNDO. DEF INPUT PARAM TABLE FOR ttListOfKeyField. DEF INPUT-OUTPUT PARAM TABLE FOR ttListOfExtraInformation. DEF INPUT PARAM TABLE FOR ttListOfError. DEF INPUT PARAM phMessageHandler AS HANDLE NO-UNDO.

IF pcPoint = "AfterCreateXMLReceipt":U THEN DO: MESSAGE pTransaction VIEW-AS ALERT-BOX. END.

IF pcPoint = "BeforeCreateXMLReceipt":U THEN DO: MESSAGE pTransaction VIEW-AS ALERT-BOX. END.

IF pcPoint = "BeforeCreateXML":U THEN DO: MESSAGE pTransaction VIEW-AS ALERT-BOX. END.

IF pcPoint = "AfterCreateXML":U THEN DO: MESSAGE pTransaction VIEW-AS ALERT-BOX. END.

IF pcPoint = "AfterGenerateXML":U THEN DO: MESSAGE pTransaction VIEW-AS ALERT-BOX. END.

IF pcPoint = "AfterParseMessage":U THEN DO: MESSAGE pTransaction VIEW-AS ALERT-BOX. END.

RETURN "OK".

Customizando o mtodo isSubscribed

Foi criado um ponto de customizao no mtodo isSubscribed do Message Handler que permite ao cliente alterar em tempo de execuo as informaes da transao que est sendo enviada. Para fazer a customizao do mtodo deve ser criado um programa chamado xmlcustom/issubscribedcustomprogram.p e o mesmo deve definir os parmetros de acordo com o descrito abaixo.

Definindo parmetros do programa de customizao

Para o correto funcionamento do programa de customizao necessrio que sejam definidos alguns parmetros que sero utilizados para receber e enviar informaes para o Message Handler. A definio dos parmetros deve ser feita de acordo com o exemplo abaixo.
Exemplo:
/* Definio dos DEF INPUT-OUTPUT DEF INPUT-OUTPUT DEF INPUT-OUTPUT DEF INPUT-OUTPUT DEF INPUT-OUTPUT DEF INPUT-OUTPUT DEF INPUT DEF INPUT DEF OUTPUT parmetros de customizao PARAM pProdName AS PARAM pAppName AS PARAM pTransaction AS PARAM pVersion AS PARAM pEvent AS PARAM pAction AS PARAM phMessageHandler AS PARAM phControlBroker AS PARAM cReturnErro AS */ CHAR NO-UNDO. CHAR NO-UNDO. CHAR NO-UNDO. CHAR NO-UNDO. CHAR NO-UNDO. CHAR NO-UNDO. HANDLE NO-UNDO. HANDLE NO-UNDO. CHAR NO-UNDO.

Abaixo segue a relao dos parmetros e o que cada um deles est recebendo. pProdName: recebe o valor do produto que est gerando a mensagem. pAppame: recebe o valor da aplicao que est gerando a mensagem;

pTransaction: recebe o nome da transao que est sendo enviada. pEvent: recebe o valor do evento da transao; pAction: recebe o valor da ao da transao; phMessageHandler: recebe o handle do Message Handler; phControlBroker: recebe o handle do Control Broker; cReturnErro: varivel que vai conter possveis erros que devem ser retornados para o Message Handler.

OBS.: Sempre que for criado um programa para customizao do mtodo isSubscribed necessrio que o mesmo retorne OK ou NOK quando o seu procedimento for concludo, porque se o retorno do mesmo for diferente de OK ser gerada uma mensagem de erro no mtodo. Abaixo segue um exemplo de programa de customizao que ir alterar o nome da transao que est sendo enviada de Teste para createCustomer.
Exemplo:
DEF INPUT-OUTPUT PARAM pProdName DEF INPUT-OUTPUT PARAM pAppName DEF INPUT-OUTPUT PARAM pTransaction DEF INPUT-OUTPUT PARAM pVersion DEF INPUT-OUTPUT PARAM pEvent DEF INPUT-OUTPUT PARAM pAction DEF INPUT DEF INPUT DEF PARAM phMessageHandler PARAM phControlBroker OUTPUT PARAM cReturnErro AS CHAR NO-UNDO. AS CHAR NO-UNDO. AS CHAR NO-UNDO. AS CHAR NO-UNDO. AS CHAR NO-UNDO. AS CHAR NO-UNDO. AS HANDLE NO-UNDO. AS HANDLE NO-UNDO. AS CHAR NO-UNDO.

IF pTransaction = "Teste" THEN DO:

ASSIGN pTransaction = "createCustomer".

END.

RETURN "OK".