Arquitetura de Integração e Mensagem Padrão Versão 1.0

Transcrição

1 Arquitetura de Integração e Mensagem Padrão Versão 1.0

2 Copyright 2010 TOTVS. Todos os direitos reservados. Nenhuma parte deste documento pode ser copiada, reproduzida, traduzida ou transmitida por qualquer meio eletrônico ou mecânico, na sua totalidade ou em parte, sem a prévia autorização escrita da TOTVS, que se reserva o direito de efetuar alterações sem aviso prévio. A TOTVS não assume nenhuma responsabilidade pelas conseqüências de quaisquer erros ou inexatidões que possam aparecer neste documento. TOTVS S.A. Av. Santos Dumont, 831 Joinville-SC Brasil CEP

3 i Índice CAPÍTULO 1 Arquitetura de Integração... 3 Definições... 3 XML... 3 XML Schemas... 4 Serviço de transformação (Transformation Service)... 5 Transação... 7 Integração Síncrona... 7 Integração Assíncrona... 7 Point-to-Point (PTP)... 7 Publish/Subscribe (Pub/Sub)... 7 Visão Geral... 7 Integração entre sistemas Progress e o Datasul Service Bus... 9 CAPÍTULO 2 A mensagem padrão Datasul Tipos de mensagens XML Spy Símbolos Modelo da mensagem padrão Datasul Elemento raiz DatasulMessage Elemento Preamble Elemento MessageHeader Elemento TransactionId Elemento CompanyId Elemento ServiceHeader Elemento SystemId Elemento BusinessContent Exemplo de elemento Upsert... 28

4 ii Exemplo de elemento Delete Exemplo de elemento Query Exemplo de elemento Notify Elemento ReturnContent Elemento QueryReturn Exemplos de mensagens XML Mensagem de Ação Mensagem de Retorno Construção de XML Schemas Arquivos utilizados em um XML Schema Nomenclatura de arquivos e diretórios Schemas de entidades comuns Passos para construir um XML Schema Política de evolução de versão das transações... 48

5 3 CAPÍTULO 1 Arquitetura de Integração Descrição Neste capítulo é descrita a forma como acontece o compartilhamento de informações entre diferentes produtos. Além de definir o comportamento que cada sistema deve ter no processo de comunicação, são apresentados também os mecanismos que intermedeiam este trabalho. Definições XML É um padrão aberto que define um conjunto de regras para a construção de documentos. Diferentemente do HTML, que se preocupa também com a maneira como o documento será exibido, o foco do XML é na estruturação das informações. Para a questão da apresentação do documento e outros aspectos do processamento dele existem tecnologias complementares. O XML tem sido muito utilizado na integração de aplicativos por apresentar uma maneira muito flexível e pouco ambígua de representar informações. Exemplo <?xml version="1.0"?> <Customer xsi:nonamespaceschemalocation="customer.xsd" xmlns:xsi=" <Id>1</Id> <Name>João da Silva</Name> <Address>Rua 7 de setembro, 1587</Address> <Gender>Male</Gender> </Customer>

6 4 A mensagem XML anterior contém as informações de código de um cliente, seu nome, endereço e sexo, estruturadas de uma maneira que fica extremamente simples de ser entendida. Exemplo XML Schemas XML Schema é um padrão criado para a modelagem de mensagens XML. Em um schema é possível indicar quais os elementos podem aparecer no interior de outros, em que ordem, de que tipo eles são e os valores que podem conter, dentre outras coisas. Através de um engine de validação é possível verificar se uma mensagem está em conformidade com o schema associado a ela, reduzindo a necessidade de codificar as críticas de entrada a um documento XML que está sendo processado. Como os schemas permitem que sejam inseridas observações sobre os elementos, eles podem ter um papel importante na documentação de um sistema. Os schemas em si também são documentos XML e habitualmente têm a extensão XSD. O software XML Spy oferece uma representação gráfica que facilita enormemente a interpretação dos schemas e deve ser usado na Datasul para a construção dos mesmos. <?xml version="1.0" encoding="utf-8"?> <xs:schema xmlns:xs=" elementformdefault="qualified" attributeformdefault="unqualified"> <xs:element name="customer"> <xs:complextype> <xs:sequence> <xs:element name="id" type="xs:integer"> <xs:annotation> <xs:documentation>código do cliente na base de dados.</xs:documentation> </xs:annotation> </xs:element> <xs:element name="name"> <xs:simpletype> <xs:restriction base="xs:string"> <xs:minlength value="1"/> </xs:restriction> </xs:simpletype> </xs:element> <xs:element name="address" type="xs:string"/> <xs:element name="gender"> <xs:simpletype> <xs:restriction base="xs:string"> <xs:enumeration value="male"/> <xs:enumeration value="female"/> </xs:restriction>

7 5 </xs:simpletype> </xs:element> </xs:sequence> </xs:complextype> </xs:element> </xs:schema> O schema anterior modela a mensagem XML apresentada como exemplo na seção XML. Ele define um documento XML cujo elemento raiz deve chamar-se Customer e deve conter os elementos Id, Name, Address e Gender. O elemento Id deve conter um valor do tipo Integer, enquanto que Name, Address e Gender devem receber Strings. O elemento Id possui uma anotação explicando que seu valor deve corresponder ao código de um cliente na base de dados. São feitas mais duas restrições: uma é que o elemento Name deve conter ao menos um caracter (não pode ser vazio) e a outra é que o elemento Gender apenas pode receber os valores Female e Male. Este Schema no XML Spy fica com a seguinte representação gráfica: Figura 1.1 Serviço de transformação (Transformation Service) A transformação consiste em gerar um novo documento XML a partir do conteúdo de um outro existente. Este processo é alimentado, também, por um outro documento que define o formato daquele que será gerado. Este documento de formatação é elaborado XSL, que é uma das várias tecnologias associadas ao XML. Para que a transformação possa acontecer é necessário um engine que forneça este serviço. Exemplo Mensagem XML original <?xml version="1.0" encoding="utf-8"?> <Cliente xmlns:xsi=" xsi:nonamespaceschemalocation="cliente.xsd"> <Codigo>1</Codigo>

8 6 <Nome>João da Silva</Nome> <Endereco> <Logradouro>Rua 7 de setembro</logradouro> <Numero>1587</Numero> </Endereco> <Sexo>Masculino</Sexo> </Cliente> /************************************************************/ Arquivo XSL utilizado na transformação <?xml version="1.0"?> <xsl:stylesheet version="1.0" xmlns:xsl=" <xsl:template match="/"> <Customer xsi:nonamespaceschemalocation="customer.xsd" xmlns:xsi=" <Id> <xsl:value-of select="cliente/codigo"/> </Id> <Name> <xsl:value-of select="cliente/nome"/> </Name> <Address> <xsl:value-of select="concat(cliente/endereco/logradouro,', ',Cliente/Endereco/Numero)"/> <xsl:apply-templates select="cliente/endereco/complemento"/> </Address> <Gender> <xsl:choose> <xsl:when test="string( Cliente/Sexo ) = 'Masculino'"> <xsl:text>male</xsl:text> </xsl:when> <xsl:when test="string( Cliente/Sexo ) = 'Feminino'"> <xsl:text>female</xsl:text> </xsl:when> </xsl:choose> </Gender> </Customer> </xsl:template> <xsl:template match="cliente/endereco/complemento"> <xsl:value-of select="concat(' - ',. )"/> </xsl:template> </xsl:stylesheet> Alimentando um engine de transformação com a mensagem XML mais acima e o arquivo XSL anterior, será produzida a mensagem usada no exemplo da seção XML.

9 7 Transação No processo de integração, o termo Transação serve para identificar uma entidade comum a diversos sistemas. Uma Transação pode ser formada simplesmente pelos campos de uma única tabela (Cliente, por exemplo) ou pode estar relacionada com várias (Pedido, que pode ser formada pelo cabeçalho e pelos itens). Os responsáveis pelas entidades é que definem como a Transação é modelada. É importante distinguir este conceito do de transações de banco de dados. Integração Síncrona Em uma integração síncrona, o programa que gera uma mensagem fica bloqueado, aguardando uma resposta a respeito do processamento desta mensagem no sistema destino. Apenas quando esta resposta chega é que o programa continua seu processamento. Um mecanismo chamado Control Broker é quem faz a distribuição da mensagem. Integração Assíncrona Neste tipo de integração o programa envia a mensagem gerada e continua seu trabalho, sem esperar por um retorno de processamento no destino. Neste caso, quem faz a entrega das mensagens é um dispositivo denominado Message Broker. A forma como os problemas de processamento no destino serão tratados depende da implementação do Message Broker. Point-to-Point (PTP) Este é um protocolo de comunicação um para um. A troca de mensagens entre os dois sistemas que participam da integração é feita através de uma fila, onde ambos gravam e de onde recebem informações. Publish/Subscribe (Pub/Sub) Este protocolo de comunicação é do tipo um para muitos. As mensagens publicadas estão associadas a um tópico e enviadas aos programas que o assinam. Visão Geral No centro da infra-estrutura de integração está o Datasul Service Bus (DSB). Através dele são disponibilizados os serviços necessários para a tarefa de

10 8 integração. Por via de regra, a comunicação com este barramento é feita de forma assíncrona. Com a adoção do DSB evita-se a necessidade de implementar em cada sistema estas funções de integração. Ao invés disto, os requisitos para interligar dois sistemas são apenas que eles tenham a capacidade de produzir e consumir mensagens XML e que implementem um dos vários tipos possíveis de canal de comunicação com o DSB. Figura 1.2 Uma vez que a mensagem chega a este barramento de serviços ela pode ser direcionada para diferentes sistemas de acordo com seu conteúdo e ser formatada de maneira específica para cada um deles, por exemplo. Outra vantagem deste modelo de integração é que cada produto tem que se comunicar apenas com um outro sistema (o DSB). Finalmente, o fato de oferecer diversas maneiras de conexão permite que, para cada sistema a ser integrado, seja utilizada a forma mais adequada de comunicação de acordo com a linguagem utilizada em sua construção. Na figura 1.2, sistemas construídos em Progress, Java e.net ou uma outra aplicação legada qualquer, possuem um conector próprio para o Datasul Service Bus. As mensagens XML que chegam nele podem ser submetidas ao

11 9 serviço de transformação, podem fazer parte de um workflow e podem ser processadas de acordo com regras que levam em conta seu conteúdo. Integração entre sistemas Progress e o Datasul Service Bus Figura 1.3 A integração entre sistemas Progress e produtos construídos com outras linguagens, através do DSB, foi projetada para trabalhar de forma independente da implementação deste último. Os diversos sistemas em Progress podem trocar informações entre si de maneira síncrona através de um Control Broker, que faz o roteamento (routing) das mensagens entre eles. Isto exige que cada programa que tenha que gerar ou receber dados de outros produtos possua um adapter para fazer a conversão para o formato XML. Quando executado um programa que manuseia uma entidade (transação) que precisa ser integrada, ele passa as informações a seu adapter síncrono de envio. Este adapter gera a mensagem XML e a entrega ao Control Broker, que verifica a lista de adapters que se subscreveram para receber mensagens daquela transação e executa-os. Os adapters síncronos de recebimento extraem do XML as informações de negócio e as passam ao programa de efetivação correspondente.

12 10 O Software Development Kit (SDK) de integração fornece artefatos que facilitam a construção destes adapters síncronos. O adapter assíncrono é formado por uma fila (implementada como uma tabela Progress), por um programa que assina junto ao Control Broker as transações de interesse dos produtos no DSB e as grava nesta fila e por um outro que lê as mensagens desta fila (postadas pelo DSB) e as envia ao Control Broker. Cabe ao DSB implementar o conector que faz a leitura e gravação das mensagens nesta fila do outro lado da integração.

13 11 CAPÍTULO 2 A mensagem padrão Datasul Descrição Este capítulo detalha o formato padrão das mensagens XML geradas nos produtos da Datasul. Além disso, é apresentado o procedimento para criar os XML Schemas que modelam cada tipo de mensagem. Tipos de mensagens As mensagens que são trocadas no processo de integração podem ser classificadas como sendo de Ação ou Retorno. Mensagens de Ação são aquelas que iniciam um processo de integração, enquanto que as de Retorno são criadas em resposta a uma mensagem de Ação recebida. Quando é executado um programa que manipula informações que estão relacionadas a outros produtos, ele deve criar uma mensagem de Ação contendo estas informações e enviá-la ao mecanismo de integração. Por exemplo, o programa que faz a manutenção da tabela de clientes, sempre que incluir um novo registro deve gerar uma mensagem de Ação com os dados deste cliente adicionado, indicando que esta é uma mensagem de inclusão e enviá-la ao mecanismo de integração. Para toda mensagem de Ação que um produto receba, ele sempre deve gerar uma mensagem de Retorno, indicando se o processamento da primeira aconteceu com sucesso ou não. No último caso, os erros ocorridos também devem ser indicados na mensagem de Retorno. Por exemplo, um programa que receba uma mensagem de inclusão de cliente deve extrair as informações desta mensagem, fazer a inclusão do cliente em sua base de dados e gerar uma mensagem de Retorno, indicando se aconteceram erros neste processo.

14 12 Cabe ao sistema que originou a mensagem de Ação decidir se desfaz a transação em seu banco de dados quando a mensagem de Retorno contiver erros. Uma outra classificação que pode ser aplicada ao processo de integração separa as mensagens entre Atualização (e mais o mensagem opcional de Notificação) ou Consulta. Como seu nome sugere, uma mensagem de Atualização está relacionada a informações que foram alteradas em uma base de um sistema e, através da integração, busca-se que o mesmo aconteça em outros produtos. As mensagens de Atualização englobam as operações de inclusão, alteração e eliminação de registros. Após o processamento de uma mensagem de Atualização pode ser necessário que o sistema que originou a mensagem tenha acesso às identificações internas utilizada pelo outro sistema. Permitindo assim que seja feito um mapeamento entre as identificações internas de ambos os sistemas. Então para fazer o envio destas identificações, ao final do processamento deve-se enviar uma mensagem de Notificação ao sistema que originou a mensagem de Atualização. Contendo as identificações do sistema de origem e destino, bem como outras informações relevantes para o mapeamento. As mensagens de Consulta, por sua vez, estão relacionadas simplesmente a obtenção de informações por um produto em um outro, não implicando necessariamente na modificação das bases de dados envolvidas. O fato de uma mensagem ser de Atualização ou Consulta tem influência no formato das mensagens de Retorno. XML Spy O XML Spy é um editor de XML e de tecnologias derivadas, como os Schemas. Ele deve ser utilizado para modelar as mensagens de cada transação que faça parte do processo de integração nos produtos da Datasul. Através do XML Spy é possível criar uma representação gráfica do XML Schema que modela uma mensagem. Na seção Modelo da mensagem padrão Datasul é apresentada a estrutura que é comum a toda mensagem manipulada pelos produtos da Datasul. Lá são utilizados os gráficos gerados pelo Spy para ilustrar esta estrutura.

15 13 Símbolos Conector de elementos que indica que cada um deles deve fazer parte da mensagem na seqüência definida. Conector de elementos que indica que apenas um deles pode fazer parte da mensagem. Elemento opcional. Elemento obrigatório. Elemento que pode ocorrer várias vezes. Modelo da mensagem padrão Datasul Tipo complexo que pode ser usado na definição de elementos. Elemento raiz DatasulMessage

16 14 Na mensagem padrão Datasul, o elemento raiz tem o nome DatasulMessage. Ele pode conter três headers (Preamble, MessageHeader e ServiceHeader) e um outro elemento que terá o nome de BusinessContent se for uma mensagem de Ação e ReturnContent se ela for de Retorno. O objetivo dos headers é conter informações de controle. Estas informações são usadas no roteamento da mensagem e na geração de arquivos de log. Elemento Preamble O elemento Preamble está localizado no início da mensagem e tem o objetivo de indicar que a mensagem foi construída para realmente estar de acordo com o padrão Datasul e em que versão deste padrão ela está. Este elemento contém outros dois. Um se chama standardname e seu valor é o nome do padrão que sempre será Datasul. O outro se chama standardversion e indica em que versão do padrão a mensagem está. Elemento MessageHeader O elemento MessageHeader é obrigatório e contém informações sobre a transação cujos dados compõe a parte principal da mensagem e sobre a

17 15 organização relacionada a estes dados. Ele tem como elementos filhos TransactionId e CompanyId. Elemento TransactionId A função do elemento TransactionId é conter informações sobre a transação que motivou a geração mensagem. Este elemento é utilizado pelos mecanismos de integração para identificar para quais sistemas a mensagem deve ser enviada e se algum processamento deve ser realizado. A seguir são descritos os elementos filhos de TransactionId:

18 16

19 17 TrackingId: O objetivo deste elemento é identificar unicamente uma mensagem. Por exemplo, mesmo que sejam geradas simultaneamente duas mensagens da transação Fornecedor, cada uma delas poderá ser localizada facilmente nos arquivos de log através deste elemento. Este elemento, na verdade, é formado pelos elementos DateTime, que contém a data e horário (com indicação de fuso) em que a mensagem foi gerada, e TrackingNumber, cujo valor é um número aleatório que distinguirá duas mensagens construídas no mesmo segundo. O valor do elemento DateTime deve estar na forma yyyy-mm-ddthh:mm:ss±hh:mm. yyyy-mm-dd corresponde a uma data no formato ano-mês-dia, T é um caracter separador desta data e do horário que segue (hora:minuto:segundo). A expressão ±hh:mm corresponde à diferença entre o horário do local em questão e do Meridiano de Greenwich (GMT). Se não houver diferença, o caracter Z é informado. Por exemplo, como o horário de Brasília é três horas menor que o de Greenwich, para um servidor em Brasília esta expressão corresponderia a - 03:00. Product: Formado pelos elementos Name e Version, Product contém o nome e a versão do produto aonde a mensagem foi gerada. Application: O valor deste elemento é o nome do aplicativo aonde a mensagem foi gerada. Name: Nome da transação cujos dados formam a parte principal da mensagem.

20 18 Version: Versão do modelo (Schema) da transação. A versão é formada por dois conjuntos de três algarismos separados pelo caracter. (ponto). O primeiro conjunto de algarismos corresponde ao Workspace do qual o Schema faz parte. O segundo conjunto indica a quantidade de alterações que o Schema sofreu desde sua criação naquele Workspace. Um Schema que tenha sido criado para a versão 205 do EMS e que já tenha sofrido três alterações estará na versão , por exemplo. Na seção Política de evolução de versão das transações são apresentadas mais informações relacionadas ao versionamento dos Schemas. Action: O conteúdo deste elemento indica que espécie de operação foi executada e que implicou na geração da mensagem. Caso tenha acontecido uma inclusão de registro, o valor será add. Se houve uma modificação, será upd. Caso tenha sido uma eliminação, será del e, finalmente, se for uma consulta, será qry. Mas se for uma mensagem de notificação, indicando que uma atualização foi realizada com sucesso, será ntf. É importante ressaltar que apenas estes quatro valores são aceitos para este elemento. Event: Para transações mais complexas pode ser interessante criar eventos que permitam uma subclassificação das operações. Por exemplo, se os registros relativos a uma determinada transação usualmente mudarem de estado de acordo com atualizações que forem acontecendo neles, esta transação é candidata a ter eventos para cada um destes estados. O motivo da criação destes eventos é que, quando a transação é desta natureza, os programas que devem receber as mensagens muitas vezes estão interessados apenas na situação em que o registro passa de um determinado estado para outro e não em toda em qualquer alteração no registro. Nestes casos, o uso de eventos evita a troca desnecessária de mensagens. A decisão de criar ou não eventos cabe ao responsável pela transação, que deve basear sua escolha nas regras de negócio. Pedido é uma transação que pode servir de exemplo para situação, onde sua criação é um evento, a aprovação de crédito é outro e seu faturamento mais um. ListOfKeyFields: O objetivo deste elemento é conter o conjunto de campos que identificam o(s) registro(s) de onde o conteúdo principal da mensagem foi obtido. Funciona como uma chave primária da transação.

21 19 O elemento ListOfKeyFields pode conter várias ocorrências do elemento keyfield. Cada uma delas terá no seu atributo Name o nome do campo e seu conteúdo será o valor dele. Para um sistema aonde a identificação da unidade de negócio seja formada pelo código da empresa e pelo código do estabelecimento, numa mensagem relativa a esta transação o elemento ListOfKeyFields terá duas ocorrências de keyfield, uma para cada um destes campos. Locale: Este elemento contém o código do idioma em que a mensagem está. Caso não esteja presente, significa que a mensagem está em Português. Deve ser usado o padrão ISO 639 na definição do valor deste elemento. O padrão define siglas para identificar os idiomas (en, pt...) e que pode ser adicionado um hífen ao final e a indicação de país, se for o caso. Ex: en-us. Comment: Este elemento é opcional e pode conter qualquer observação que o responsável pela transação julgar importante que seja enviada nas mensagens relativas a ela. Elemento CompanyId

22 20 As informações encontradas nos elementos filhos de CompanyId têm especial importância para o roteamento das mensagens num ambiente Business-to- Business, aonde freqüentemente deseja-se direcionar para certos sistemas apenas as mensagens relativas às empresas as quais eles estão relacionados. O elemento Domain contém a indicação de que tipo de identificador está sendo usado para designar a empresa presente na mensagem. O valor comum para este elemento nas empresas brasileiras é CNPJ, enquanto que para americanas é DUNS. O elemento BusinessIdentifier contém o identificador propriamente dito da empresa, ou seja, para as brasileiras seria o seu CNPJ e para as americanas o seu DUNS. Para complementar a identificação da empresa, os campos CompanyCode e BranchCode podem conter o código da empresa e do estabelecimento/filial da organização a qual a mensagem gerada é relativa.

23 21 Elemento ServiceHeader O elemento ServiceHeader contém informações sobre como deve ser feito o processamento da mensagem e sobre o sistema que a originou. Ele pode ter como filhos os elementos SystemId, ForTestPurpose e IsSecureTransportRequired. Quando o elemento ForTestPurpose apresentar o valor yes significa que a mensagem é para teste e não deve ser efetivada no destino. Quando ele não fizer parte da mensagem ou estiver com o valor no significa que o processamento pode ocorrer normalmente. O uso do elemento IsSecureTransportRequired implica num processamento que ainda não está implementado na infra-estrutura de integração. No entanto, ele já está presente na mensagem pois é certo que no futuro isto acontecerá. Quando esta funcionalidade estiver presente, as mensagens que contiverem este elemento com o valor yes deverão ser transmitidas criptografadas. Elemento SystemId O elemento SystemId contém várias informações a respeito do sistema aonde a mensagem foi gerada. A importância de sua existência está relacionada à tarefa de rastreamento de integrações já realizadas. A seguir são listados seus elementos filho:

24 22

25 23 Site: Contém um identificador do sistema que gerou a mensagem. Como pode haver várias instalações da mesma aplicação no mesmo servidor, a simples combinação de host e produto pode não ser suficiente para indicar a origem da mensagem. Neste caso, é necessário adicionar um terceiro componente para fazer a distinção. Module: Nome do módulo do qual faz parte o programa que gerou a mensagem. Program: Este elemento tem como filhos Name, cujo valor é o nome do programa que gerou a mensagem, e Version que contém a versão deste último. Host: Indicação do servidor onde está localizado o programa que gerou a mensagem. User: Identificação do usuário que executou o programa que gerou a mensagem. Location: Indicação do local onde se encontra o servidor que hospeda a aplicação de onde a mensagem foi gerada. Comment: O valor deste elemento é qualquer observação que for considerada relevante sobre o ambiente aonde a mensagem foi gerada. Elemento BusinessContent O elemento BusinessContent deve estar presente na mensagem quando ela for de Ação. É ele que contém as informações que motivaram a criação da mensagem e é, portanto, sua parte principal.

26 24 De acordo com a operação que originou a mensagem, o BusinessContent terá um de três elementos filhos possíveis: Upsert se a operação for de inclusão (Action = add) ou alteração (Action = upd), Delete se a operação for de eliminação (Action = del), Query se for uma consulta (Action = qry) ou Notify se for uma notificação (Action = ntf). Não é necessário que toda transação aceite todos estes quatro elementos, mas também não é permitido que ela contenha elementos diferentes destes. A estrutura dos três primeiros elementos não é definida pelo padrão, pois varia de transação para transação, obviamente. No entanto, algumas regras devem ser seguidas na sua definição. Já para o quarto elemento (Notify), há uma estrutura mínima a ser seguida, que é apresentada a seguir:

27 25 A seguir são listados seus elementos filho: TransactionName: Nome da transação que originou esta mensagem de notificação. KeyFieldsOfOriginalSystem: Lista com os valores dos campos de identificação enviados pelo sistema de origem. KeyFieldsOfDestinationSystem: Lista com os valores dos campos de identificação do sistema de destino, criados ou alterados durante o processamento de uma mensagem de atualização. OthersFields: Lista de campos opcional, que podem ser utilizados para facilitar o processo de mapeamento de campos entre o sistema de origem e destino. O trabalho de modelagem do BusinessContent de cada transação deve ser feito pelo ADF de cada franquia de desenvolvimento. Nesta tarefa ele deve observar se o elemento que está criando é (ou potencialmente será) utilizado nos modelos de outras transações. Neste caso, a definição do elemento deverá ser

28 26 Exemplo feita em uma include que será compartilhada pelos Schemas delas. O objetivo disto é que uma mesma entidade deve aparecer modelada de maneira igual em diferentes transações. Um exemplo simples de entidade que certamente será compartilhada por várias transações é endereço. Na definição dos nomes dos elementos deve-se ter o cuidado de usar um termo que seja significativo dentro das regras de negócio e evitar utilizar simplesmente o nome do campo correspondente na base de dados. Como o XML Schema tem também a função de documentação, é importante sempre incluir comentários sobre cada elemento em sua definição. Se o elemento possuir uma lista de valores possíveis (enumeration), os mesmos devem ser numéricos e na área de comentários deve ser indicado o significado de cada um destes códigos numéricos. Outro registro importante a ser feito no comentário é o nome do campo que gera o valor do elemento e da include Progress que contém cada um dos valores possíveis para ele, quando for este o caso. O padrão para estas informações é: [Comentário sobre o elemento]. Valores: [lista de código e significado, separados por vírgula]. (Uso interno: Campo=[nome do campo, precedido pelo nome da tabela] Include=[nome da include e seu diretório]) <xs:element name="dimension" type="dimensiontype" default="1" minoccurs="0"> <xs:annotation> <xs:documentation>tipo de grandeza da unidade de medida. Valores: 1 Peso, 2 Linear, 3 Area, 4 Volume, 5 Outros. (Uso interno: Campo=mgind.tab-unidade.dimensao Include= ininc/i01in417.i)</xs:documentation> </xs:annotation> </xs:element> Ainda no que diz respeito à nomenclatura dos elementos, é necessário que sempre se use expressões no idioma inglês para este fim e se o nome é formado por várias palavras, cada uma delas deve ter a letra inicial na forma maiúscula e as demais na minúscula. Elementos cujo valor seja do tipo lógico devem ser definidos como boolean e seu nome deve estar na forma is[adjetivo].

29 27 Exemplo Procurar, sempre que possível, definir os elementos como opcionais. Esta prática permite diminuir o tamanho das mensagens geradas. Porém, é necessário que, para cada elemento opcional, seja criada uma observação no seu Schema indicando o valor default que deve ser usado na sua ausência. Para simplificar o trabalho de rastreamento (tracking), é importante que as mensagens de eliminação contenham campos que facilitem a identificação dos registros que as geraram. Muitas vezes, analisar arquivos de log tendo por base apenas a chave primária pode ser uma atividade complexa. No momento de estruturar o conteúdo do elemento BusinessContent é importante lembrar de incluir informações complementares que servem para contextualizar os dados. Este tipo de situação é comum em entidades que estão relacionadas com mais de uma tabela. Nestes casos a estrutura do Schema da entidade não deve contemplar apenas a tabela principal. Além disso, uma boa prática na construção de documentos XML é não permitir que um elemento tenha entre seus filhos várias ocorrências de um mesmo elemento e ainda outros tipos de elemento. Ou seja, é permitido várias ocorrências de um mesmo elemento, ou elementos diferentes que não se repetem. A maneira de implementar está prática quando há a necessidade de combinar elementos que se repetem com outros tipos de elementos é criar um agrupador para estes repetidos. O nome deste elemento agrupador deve ser formado pelo nome do elemento que contém, precedido pela expressão ListOf. Errado: De acordo com o XML Schema abaixo, o elemento Order pode conter o elemento Order-Number, ShipDate e várias ocorrências do elemento Item. Correto: Para tornar o Schema em conformidade com a boa prática, basta criar o elemento ListOfItem e fazer com que ele contenha as várias ocorrências de Item. Desta maneira o elemento Order contém apenas uma ocorrência dos elementos Order-Number, ShipDate e ListOfItem, enquanto que este último pode conter várias ocorrências de Item, porém nenhum outro tipo de elemento.

30 28 Exemplo de elemento Upsert No diagrama a seguir é modelada uma transação de Cliente, baseada na tabela Customer do banco Sports, para as operações de inclusão e alteração.

31 29 Os elementos Address2, Country, CreditLimit e Discount ilustram a regra que sugere que, quando possível, os elementos devem ser declarados como opcionais.

32 30 Exemplo de elemento Delete No diagrama a seguir é modelada uma transação de Cliente, baseada na tabela Customer do banco Sports, para a operação de eliminação. Ao solicitar que o nome do cliente (Name) também faça parte da mensagem de eliminação, mesmo sendo a chave primária formada apenas pelo código (Number), este fragmento de Schema exemplifica o que a técnica aconselha para este tipo de mensagem. Exemplo de elemento Query Nos diagramas a seguir é modelada uma transação de Cliente, baseada na tabela Customer do banco Sports, para a operação de consulta. Neste modelo é permitido usar como critério de consulta o código do cliente (Number) ou seu nome (Name). Além disso, através do elemento FieldsToReturn é possível especificar que campos que se deseja que sejam retornados. A consulta por código permite que sejam especificados um código inicial (NumberIni) e um final (NumberFin), definindo uma faixa de registros a serem

33 31 retornados. Se apenas o elemento NumberIni for especificado, será retornado apenas o registro relativo ao código informado nele, e não uma faixa de registros. O mesmo se aplica à consulta por nome, aonde NameIni é o critério de busca inicial e NameFin o critério final. Se somente NameIni for especificado, apenas o cliente cujo nome seja igual ao presente nele é que terá suas informações retornadas. A presença do elemento All dentro de FieldsToReturn significa que a consulta deve retornar todos os elementos que compõem a transação. Outra opção é simplesmente listar como um elemento vazio cada campo desejado.

34 32 Exemplo de elemento Notify No diagrama a seguir é modelada uma transação de Cliente, baseada nas tabelas Customer do banco Sports e Clients de um banco fictício, para a operação de notificação.

35 33 A utilização de agrupadores diferentes permite facilmente fazer um mapeamento entre as identificações. Independente de este mapeamento ser um-para-um ou muitos-para-muitos, pois em ambos os grupos são utilizados os mesmo elementos. Além de elementos para armazenar as identificações, é possível fazer a inclusão de outros elementos auxiliares. Elemento ReturnContent O elemento ReturnContent deve estar presente na mensagem quando ela for do tipo Retorno. O formato deste elemento também será afetado pelo fato de a mensagem ser de Atualização ou de Consulta. Para mensagens de Atualização, o objetivo deste elemento é fundamentalmente indicar o sucesso ou não da integração. Nas mensagens de Consulta ele tem a função extra de conter as informações pesquisadas.

36 34 Quando o elemento IsMessageProcessed apresenta o valor yes significa que a mensagem de Ação recebida foi efetivada com sucesso pelo sistema que gerou esta mensagem de Retorno. Se o valor for no, ocorreram erros na efetivação da mensagem de Ação. Estes erros são apresentados no elemento ListOfError. O elemento OriginalMessageHeaderReceived, como seu nome sugere, contém o elemento MessageHeader da mensagem de Ação recebida que provocou a criação desta mensagem de Retorno.

37 35 O elemento ListOfError pode conter várias ocorrências do elemento Error, sendo cada uma delas relativa a um erro ocorrido na efetivação da mensagem de Ação. O elemento Error é formado por Id, Type e Desc. Existem oito valores possíveis para o elemento Type: business_error, environment_error, validation_error header_error, business_warning, environment_warning, validation_warning e header_warning. Estes oito valores possíveis, ou seja, ou tipos de erros dividem-se em duas categorias: erros (sufixo _error) e avisos de erro (sufixo _warning). A primeira se refere aos erros que impedem o processamento de uma mensagem, indicando assim que a transação foi desfeita ou não foi realizada. Já a segunda categoria, refere-se aos erros que não impedem o processamento e efetivação da mensagem, devendo ser visto como avisos importantes para evitar outros problemas. O termo business_error indica que houve um problema no momento de efetivar as informações presentes na mensagem de Ação em um sistema destino. Ou seja, a mensagem foi transportada e interpretada com sucesso, porém seu conteúdo violou alguma regra de negócio no sistema. Um exemplo disto é uma mensagem de inclusão de pedido, aonde o valor deste ultrapassa o limite de crédito do cliente no sistema destino. O termo environment_error indica um problema no ambiente de integração. Por exemplo, tomemos por base o adapter do sistema de destino da mensagem XML que a recebe e interpreta. Se ele não puder localizar o programa que efetiva as informações, ele deve gerar uma mensagem de Retorno com um erro do tipo environment_error. O mecanismo de integração (Control Broker ou Message Broker) também pode ter que gerar mensagens deste tipo em diversas

38 36 Exemplo situações, como erro nos seus arquivos de configuração ou problema no serviço de transformação. Os erros do tipo validation_error e header_error apenas são gerados pelo mecanismo de integração. O primeiro ocorrerá quando a mensagem não estiver de acordo com seu Schema e o segundo quando for identificado algum problema em um dos seus headers. O termo business_warning indica que houve um problema no momento de efetivar as informações presentes na mensagem de Ação em um sistema destino, mas este não impediu a efetivação da mensagem de Ação. Ou seja, a mensagem foi transportada e interpretada com sucesso, porém seu conteúdo violou alguma regra de negócio no sistema, mas que não impede a efetivação do processo de negócio no sistema. O termo environment_warning indica um problema no ambiente de integração. Por exemplo, tomemos por base o adapter do sistema de origem da mensagem XML que a monta e envia. Se ele montar uma mensagem XML que exceda o tamanho recomendado, ele deve gerar uma mensagem de Retorno com um erro do tipo environment_warning, porém este erro não impedirá ou bloqueará o restante do processamento. O mecanismo de integração (Control Broker ou Message Broker) também pode ter que gerar mensagens deste tipo em diversas situações, como inexistência de arquivos opcionais ou falta de especificação de diretório de log. Os erros do tipo validation_warning e header_warning são apenas mantidos para fins de compatibilização, mas não estão sendo utilizados pelo mecanismo de integração. O valor do elemento Id é o código da mensagem de erro no sistema que está gerando a mensagem de Retorno e Desc é a sua descrição. Elemento QueryReturn O elemento QueryReturn deve estar presente apenas nas mensagens de Retorno para mensagens de Consulta. Há apenas uma especificação para o formato do conteúdo deste elemento, uma vez que ele é totalmente dependente da estrutura de cada transação. Este elemento sempre deve ter como filho um outro elemento de nome ListOfXXX, onde XXX é o nome da transação. O motivo disto é que como a consulta tanto pode não retornar nenhum registro, como pode retornar vários, é interessante que haja um elemento agrupador para eles. No exemplo a seguir é apresentado como poderia ser o formato do elemento QueryReturn para a transação Customer.

39 37

40 38

41 39 Exemplos de mensagens XML Mensagem de Ação Exemplo <?xml version="1.0" encoding="utf-8"?> <DatasulMessage xmlns:xsi=" xsi:nonamespaceschemalocation="customer_200_000.xsd"> <Preamble> <standardname>datasul</standardname> <standardversion> </standardversion> </Preamble> <MessageHeader> <TransactionId> <TrackingId> <DateTime> T11:46:00-03:00</DateTime> <TrackingNumber> </TrackingNumber> </TrackingId> <Product> <Name>EMS2</Name> <Version>204</Version> </Product> <Application>CRM</Application> <Name>Customer</Name> <Version> </Version> <Action>del</Action> <Event/> <ListOfKeyField> <keyfield Name="Customer.Cust-num">2</keyField> </ListOfKeyField> <Locale>pt-BR</Locale> <Comment/> </TransactionId> <CompanyId> <Domain>CNPJ</Domain> <BusinessIdentifier> </BusinessIdentifier> <CompanyCode>1</CompanyCode> <BranchCode>1</BranchCode> </CompanyId> </MessageHeader> <ServiceHeader> <SystemId> <Site>Datasul</Site> <Program> <Name>send_xml.r</Name> <Version>2.65</Version> </Program> <Host>Sambaqui</Host> <User>super</User> <Location>Av Santos Dumont</Location> </SystemId> </ServiceHeader>

42 40 <BusinessContent> <Delete> <Number>2</Number> <Name>Urpon Frisbee</Name> </Delete> </BusinessContent> </DatasulMessage> Mensagem de Retorno Exemplo <?xml version="1.0" encoding="utf-8"?> <DatasulMessage xmlns:xsi=" xsi:nonamespaceschemalocation="customer_200_000.xsd"> <Preamble> <standardname>datasul</standardname> <standardversion> </standardversion> </Preamble> <MessageHeader> <TransactionId> <TrackingId> <DateTime> T11:46:02-03:00</DateTime> <TrackingNumber> </TrackingNumber> </TrackingId> <Product> <Name>EMS5</Name> <Version>5.05</Version> </Product> <Application>Financeiro</Application> <Name>Customer</Name> <Version> </Version> <Action>del</Action> <Event/> <ListOfKeyField> <keyfield Name="Customer.Cust-num">2</keyField> </ListOfKeyField> <Locale>pt-BR</Locale> <Comment/> </TransactionId> <CompanyId> <Domain>CNPJ</Domain> <BusinessIdentifier> </BusinessIdentifier> <CompanyCode>5</CompanyCode> <BranchCode>7</BranchCode> </CompanyId> </MessageHeader> <ServiceHeader> <SystemId> <Site>Datasul</Site> <Program> <Name>receive_xml.r</Name> <Version>3.98</Version> </Program> <Host>Sambaqui</Host>

43 41 <User>adm</User> <Location>Av Santos Dumont</Location> </SystemId> </ServiceHeader> <ReturnContent> <IsMessageProcessed>no</IsMessageProcessed> <OriginalMessageHeaderReceived> <TransactionId> <TrackingId> <DateTime> T11:46:00-03:00</DateTime> <TrackingNumber> </TrackingNumber> </TrackingId> <Product> <Name>EMS2</Name> <Version>204</Version> </Product> <Application>CRM</Application> <Name>Customer</Name> <Version> </Version> <Action>del</Action> <Event/> <ListOfKeyField> <keyfield Name="Customer.Cust-num">2</keyField> </ListOfKeyField> <Locale>pt-BR</Locale> <Comment/> </TransactionId> <CompanyId> <Domain>CNPJ</Domain> <BusinessIdentifier> </BusinessIdentifier> <CompanyCode>1</CompanyCode> <BranchCode>1</BranchCode> </CompanyId> </OriginalMessageHeaderReceived> <ListOfError> <Error> <Id>5</Id> <Type>business_error</Type> <Desc>O cliente 2 não pode ser eliminado pois possui pedidos associados a ele.</desc> </Error> </ListOfError> </ReturnContent> </DatasulMessage> Construção de XML Schemas Para toda transação de negócio que faz parte de mais de um sistema, deve ser avaliada sua inclusão no processo de integração.

44 42 O primeiro passo para implementar a participação de uma transação neste processo é criar um XML Schema que a modele. Conforme já foi citado anteriormente, uma transação de integração não equivale necessariamente a uma tabela de um banco de dados. Cabe ao especialista no negócio analisar a real natureza do que está sendo modelado e definir quais informações farão parte dela. Os XML Schemas são uma evolução das DTDs, que eram o recurso usado inicialmente para modelar as mensagens XML. A primeira característica importante dos Schemas é que eles em si são documentos XML também, ou seja, obedecem as regras para a construção deste tipo de documento. Dentre as muitas características de formatação que podem estar presentes num XML Schemas, aquelas que devem ser utilizadas na modelagem das transações de integração da Datasul, quando aplicável, são: Definição de tipo para os elementos; Indicação de que um elemento é opcional; Indicação de que um elemento pode ocorre várias vezes; Criação de lista de valores possíveis (enumerations) para um elemento; Definição de número mínimo e máximo de caracteres no valor de um elemento, salientando que, se um número mínimo de caracteres não for especificado, um elemento vazio não será rejeitado pelo processo de validação; Criação de várias opções de estrutura para uma parte da mensagem. Na seção Elemento BusinessContent são apresentadas regras que devem ser observadas na modelagem das transações. Arquivos utilizados em um XML Schema No arquivo que contém o XML Schema de uma transação são feitas referências a outros arquivos. Na seção Modelo da mensagem padrão Datasul é apresentada a estrutura que toda mensagem XML manipulada pelos produtos da Datasul deve ter. Como pode ser visto lá, existe uma parte comum a todos os modelos de transação que engloba os elementos Preamble, MessageHeader,

45 43 ServiceHeader e, parcialmente, BusinessContent e ReturnContent. Esta parte comum é modelada num arquivo que deve ser incluído em todo Schema e que se chama DatasulMessage.xsd. Conforme já foi citado na seção Elemento BusinessContent, entidades que fizerem parte de mais de uma transação devem ser modeladas em um arquivo em separado. Este arquivo deve ser utilizado como uma include nos Schemas de cada uma destas transações. Desta forma se cria uma biblioteca de entidades comuns. E caso esteja sendo modelada uma transação de notificação, deve-se fazer a inclusão do arquivo NotifyMessage.xsd, que contém a estrutura básica do elemento Notify. Nomenclatura de arquivos e diretórios Os arquivos relacionados aos Schemas das transações de integração ficam armazenados abaixo do diretório xmlschema. Na raiz deste diretório está localizado o arquivo DatasulMessage.xsd. Lá também se encontra o subdiretório de nome shared, que contém os Schemas das entidades que fazem parte de mais de uma transação. Ainda na raiz do diretório xmlschema existe uma pasta para cada aplicativo dos produtos Datasul, cujo nome é seu código. Cada uma delas armazena os Schemas das transações que são de responsabilidade do aplicativo associado a elas. O nome do Schema que modela uma entidade comum é formado pelo nome da entidade, o caracter _ (underline) e um número inteiro de três dígitos que representa a quantidade de vezes que o Schema foi alterado. Caminho completo para o Schema de uma entidade comum: xmlschema/shared/[entidade]_[3 dígitos].xsd Exemplo: xmlschema/shared/address_000.xsd O nome do Schema que modela uma transação de integração é formado pelo nome da transação, o caracter _ (underline), o código do Workspace do qual ela faz parte, novamente o caracter _ (underline) e um número inteiro de três dígitos que representa a quantidade de vezes que o Schema foi alterado no Workspace. Caminho completo para o Schema de uma transação: xmlschema/[ Aplicativo]/[Transação]_[ Workspace]_[3 dígitos].xsd

46 44 Exemplo: xmlschema/dist/customer_205_000.xsd Mas caso a Schema faça a modelagem de uma transação de integração do tipo notificação, deve-se adicionar o sufixo Notify ao final do nome da transação. Caminho completo para o Schema de uma transação do tipo notificação: xmlschema/[ Aplicativo]/[Transação]Notify_[ Workspace]_[3 dígitos].xsd Exemplo: xmlschema/dist/customernotify_205_000.xsd Cada produto da Datasul contém em sua distribuição os Schemas criados nos demais produtos. Isto evita que o aplicativo que tem a responsabilidade sobre o Schema de uma transação tenha que estar instalado para que outros dois aplicativos possam manipular esta transação. Exemplo Schemas de entidades comuns O conteúdo de um XML Schema de uma entidade comum a várias transações é formado, fundamentalmente, pela definição de um tipo complexo (complextype). O nome deste tipo complexo é constituído pelo nome da entidade seguido da string Type (ex: AddressType). No Schema de uma transação, que usa esta entidade, é criado um elemento para representá-la. Seu tipo é indicado como sendo o complextype definido no Schema da entidade. Desta maneira, a estrutura do elemento fica sendo aquela montada para a entidade. Os Schemas das entidades comuns são mantidos pela área de ADF Corporativo. Suponhamos que a entidade Location seja definida no Schema Location_000.xsd da seguinte maneira:

47 45 <?xml version="1.0" encoding="utf-8"?> <xs:schema xmlns:xs=" elementformdefault="qualified" attributeformdefault="unqualified"> <xs:complextype name="locationtype"> <xs:sequence> <xs:element name="address" type="xs:string"/> <xs:element name="city" type="xs:string"/> <xs:element name="state" type="xs:string"/> <xs:element name="postalcode" type="xs:string"/> <xs:element name="country" type="xs:string"/> </xs:sequence> </xs:complextype> </xs:schema> O Schema de uma transação, que utilize esta entidade, simplesmente precisa declarar o arquivo Location_000.xsd como uma include, criar um elemento com qualquer nome e indicar que seu tipo é LocationType. No exemplo abaixo foi criado um elemento de nome Delivery que, por ter a mesma estrutura de Location, foi definido como sendo do tipo LocationType.

48 46 <?xml version="1.0" encoding="utf-8"?> <xs:schema xmlns:xs=" elementformdefault="qualified" attributeformdefault="unqualified"> <xs:include schemalocation="../shared/location_000.xsd"/> <xs:element name="delivery" type="locationtype"/> </xs:schema> Passos para construir um XML Schema 1. No XML Spy, escolher a opção New do menu File. 2. Na janela que se abrir, escolher a opção xsd W3C XML Schema e clicar no botão OK. 3. Alterar o nome do elemento default criado pelo Spy de ENTER_NAME_OF_ROOT_ELEMENT_HERE para DatasulMessage. De: Para: 4. Salvar o arquivo no diretório do aplicativo ao qual a transação pertence, obedecendo as definições apresentadas na seção Nomenclatura de arquivos e diretórios. 5. Por um aparente bug no XML Spy, o diretório corrente do arquivo criado só é atualizado depois que ele é fechado e aberto novamente. Antes disso,

49 47 o diretório corrente é aquele aonde o XML Spy foi instalado. Como nos próximos passos serão declaradas includes utilizando um caminho relativo ao diretório corrente, é necessário fechar o arquivo criado e abrilo em seguida. 6. Clicar no botão Append ( ) e, no menu que se abrir, selecionar a opção Include. 7. Na janela que se abre, digitar../datasulmessage.xsd no campo Choose a File e pressionar o botão OK. Caso ocorra um erro de arquivo não encontrado, significará que há um problema no ambiente. Um erro pode ser a falta do arquivo DatasulMessage.xsd na raiz do diretório xmlschema e outro o Schema que está sendo criado não ter sido salvo num subdiretório deste último. 8. Selecionar o elemento DatasulMessage. Depois, na janela Details, escolher o valor DatasulMessageType no combo-box ao lado do campo type. Este tipo é definido no arquivo DatasulMessage.xsd e sua estrutura corresponde à da mensagem padrão Datasul. 9. O procedimento para criar tipos complexos no Spy é clicar no botão Append, escolher a opção complextype e digitar um nome para ele. Devem ser criados agora os tipos complexos BusinessContentType, que define a estrutura do elemento BusinessContent, e ReturnContentType,

50 48 que define a estrutura do elemento ReturnContent. Este relacionamento entre os elementos e estes tipos é feito no arquivo DatasulMessage.xsd, onde estes dois elementos são definidos como sendo dos tipos correspondentes, sem que seja feita a definição destes tipos. 10. Salvar o Schema que está sendo criado. Se for apontado algum erro neste momento, a provável causa é a falta de algum dos dois tipos complexos que deveriam ter sido criados no passo anterior. 11. Definir um conteúdo para os tipos complexos BusinessContentType e ReturnContentType. Nas seções Elemento BusinessContent e Elemento ReturnContent são apresentados exemplos para a estrutura deles. O tipo BusinessContentType pode conter os elementos Upsert, Delete, Query e Notify e nenhum outro mais. O tipo ReturnContentType deve estender o tipo ReturnContentBaseType, que é definido no arquivo DatasulMessage.xsd. E os tipos KeyFieldsType e OthersFieldsType, devem ser especificados quando o elemento Notify estiver definido. Se na definição destes tipos for utilizada uma entidade que está modelada em seu próprio Schema, ele deve ser referenciado como uma include. O procedimento para isto é semelhante a aquele descrito nos passos 6 e 7, com a diferença de que ao invés de usar a expressão../datasulmessage.xsd para indicar o arquivo da include, deve ser usada uma expressão do tipo../shared/[entidade_versão].xsd. Política de evolução de versão das transações Quando uma transação tiver seu modelo (Schema) alterado, nem sempre é necessário exigir que todos os adapters que a manipulem também sejam modificados. Nestes casos onde alguns adapters continuam esperando receber ou publicando mensagens no formato antigo, é necessário que os responsáveis pela transação construam arquivos de transformação (XSL) que gerem mensagens no novo formato a partir do antigo e o contrário. Os arquivos de transformação devem obedecer a seguinte nomenclatura: