Desenvolvendo Integrações com o InterSystems IRIS - SQL Inbound Adapter

Projeto 4 – SQL Inbound Adapter

Vamos montar nossa próxima integração utilizando o adaptador SQL Inbound Adapter. Este adaptador permite acessar uma tabela externa ao IRIS e consumir seus registros.

No nosso exemplo iremos ler uma tabela via SQL externa ao IRIS através de uma conexão ODBC e armazenar as informações desejadas em uma global.

O primeiro passo é criar as mensagens da integração. Vamos criar o Request e o Response que iremos utilizar para trafegar as mensagens pelo barramento:

Class ws.global.msg.incluir.Request Extends Ens.Request
{

Parameter XMLTYPE = "incluirReq";

Property codigo As %Integer;

Property nome As %String;

}

Class ws.global.msg.incluir.Response Extends Ens.Response
{

Parameter XMLTYPE = "incluirResp";

Property status As %Boolean;

Property mensagem As %String;

Property sessionId As %Integer;

}

Note que Request tem como superclasse Ens.Request e Response tem como superclasse Ens.Response. Isso é importante para que as funcionalidades do barramento estejam disponíveis nas mensagens.

Após criar nossas mensagens de Request e Response Vamos criar nosso BS, que é quem vai consumir a tabela SQL externa:

Class ws.global.bs.Service Extends Ens.BusinessService
{

Parameter ADAPTER = "EnsLib.SQL.InboundAdapter";

Method OnProcessInput(pInput As EnsLib.SQL.Snapshot, pOutput As %RegisteredObject) As %Status
{

 Set req=##class(ws.global.msg.incluir.Request).%New()
 Set req.codigo=pInput.Get("code")
 Set req.nome=pInput.Get("name")
 Set sc=..SendRequestSync("bpGlobalIncluir",req,.pOutput)
 Quit sc
}

}

Note que nosso BS usa o adaptador EnsLib.SQL.InboundAdapter. Isso habilita nosso BS a consumir a tabela externa. Vamos precisar depois realizar algumas configurações no BS, mas faremos isso quando formos coloca-lo na produção.

Agora vamos criar nosso BO conforme abaixo:

Class ws.global.bo.Operation Extends Ens.BusinessOperation [ ProcedureBlock ]
{

Method incluir(pRequest As ws.global.msg.incluir.Request, Output pResponse As ws.global.msg.incluir.Response) As %Library.Status
{
 Set pResponse=##Class(ws.global.msg.incluir.Response).%New()
 Set ^Cliente(pRequest.codigo)=pRequest.nome
 Set pResponse.status=1
 Set pResponse.mensagem="OK"
 Set pResponse.sessionId=..%SessionId
 Quit $$$OK
}

XData MessageMap
{
<MapItems>
              <MapItem MessageType="ws.global.msg.incluir.Request">
                            <Method>incluir</Method>
              </MapItem>
</MapItems>
}

}

Aqui no BO temos a estrutura XData que recebe qual a classe que vai chegar e direciona para o método que deve tratar aquela entrada.

Note também que neste BO não estamos utilizando nenhum adaptador. Ele trabalha sem fazer chamadas externas, apenas salvando a global que queremos criar.

Agora, por fim, vamos montar nosso BP, que é o orquestrador das chamadas da integração.

 

 

Configure nosso componente CALL da seguinte forma:

 

 

O código do nosso BP ficará assim:

/// 
Class ws.global.bp.incluir.Process Extends Ens.BusinessProcessBPL [ ClassType = persistent, ProcedureBlock ]
{

/// BPL Definition
XData BPL [ XMLNamespace = "http://www.intersystems.com/bpl" ]
{
<process language='objectscript' request='ws.global.msg.incluir.Request' response='ws.global.msg.incluir.Response' height='2000' width='2000' >
<sequence xend='200' yend='350' >
<call name='boEGlobal' target='boGlobal' async='0' xpos='200' ypos='250' >
<request type='ws.global.msg.incluir.Request' >
<assign property="callrequest" value="request" action="set" languageOverride="" />
</request>
<response type='ws.global.msg.incluir.Response' >
<assign property="response" value="callresponse" action="set" languageOverride="" />
</response>
</call>
</sequence>
</process>
}

Storage Default
{
<Type>%Storage.Persistent</Type>
}

}

Vamos agora configurar o acesso ODBC. No nosso exemplo faremos um acesso ao próprio IRIS, mas poderíamos acessar qualquer banco que disponibilizasse um driver ODBC. Primeiro vamos configurar o DSN para o acesso. Vá no Windows (só lembrando que existe driver ODBC para Linux também) e execute o utiliário Fonte de Dados ODBC 64 Bits. Crie um novo DSN de Sistema e preencha as informações conforme a tela abaixo:

 

Salve e faça um teste de conexão:

 

Pronto. Temos o acesso ODBC configurado. Agora precisamos ter nossa tabela criada. Vamos utilizar o modelo a seguir:

Class ws.database.cliente Extends (%Persistent, %Populate, %XML.Adaptor)
{

Property code As %Integer(MAXVAL = 999);

Property name As %String;

}

 

Agora vamos utilizar a production que criamos no exemplo anterior e colocar as classes nela e realizar algumas configurações. A primeira será criar uma credencial para autenticação do acesso ODBC. Vamos em Interoperabilidade->Configurar->Credenciais a partir do painel de Administração do IRIS:

 

Agora crie uma nova credencial. Informe ID = super, Nome do usuário = _SYSTEM e Senha a senha do seu usuário _SYSTEM (padrão é SYS). Você pode criar um usuário para este acesso caso deseje. Estamos usando o _SYSTEM somente para facilitar o teste.

Salve a credencial e você verá uma tela como esta:

Agora vamos colocar nossos componentes na production. Clique no botão (+) ao lado do título Services e inclua o nosso BS conforme a tela abaixo:

 

 

IMPORTANTE: Deixe a caixa Habilitar agora DESMARCADA. Vamos habilitare ste componente mais tarde quando todas as etapas necessárias estiverem cumpridss.

Vamos agora complementar a configuração do BS informando o DSN e a credencial de autenticação para o ODBC. Vá na configuração do BS, opções Parâmetros Básicos e informe conforme abaixo:

 

Mantenha a caixa Habilitado desmarcada. Isso é importante conforme veremos mais à frente.

Agora, ainda na configuração do BS vá em Data e preencha conforme a seguir:

 

A caixa Consulta tem o SQL que será executado para recuperar as informações. A caixa Consulta para Exclusão tem o SQL que limpará a tabela externa dos registros já processados. Em Nome Campo Chave colocamos a coluna que servirá de identificador para a limpeza. Aqui podemos fazer diversos mecanismos diferentes, como por exemplo, alterar a linha processada colocando um flag de processamento e uma data/hora para informar que alquela linha já foi processada. Para maiores detalhes sobre o uso do SQL Inbound Adapter consulte a documentação em https://docs.intersystems.com/irislatest/csp/docbook/Doc.View.cls?KEY=ES...

Pronto. Nosso BS está configurado.

Agora vamos passar para o nosso BO. O processo é o mesmo, ou seja, clique no botão (+) ao lado do título Operations e preencha a tela que será apresentada:

Pronto. Nosso BO está configurado na production.

A seguir clique no botão (+) ao lado do título Process para incluir o nosso BP:

 

 

Preencha a tela conforme acima e clique em OK.

 

 

 

Temos nossos 3 componentes configurados na produção. Clique na bola verde ao lado de bpGlobalIncluir para ver as conexões entre os componentes:

 

 

Agora vamos verificar a global que receberá os dados que virão da tabela externa. Abra um terminal do IRIS e vá para nosso namespace de desenvolvimento. No cado do nosso exemplo é o INTEGRA:

 

Chame o utilitário ^%G e verifique o conteúdo da global ^Cliente:

 

Veja que a global não existe. Será nessa global que nosso BO irá colocar os registros lidos da tabela externa.

Agora abra o Painel de Administração do IRIS, vá em Explorer do Sistema->SQL e mude para o namespace INTEGRA:

 

Faça uma consulta na tabela ws_database.cliente e confirme que ela está vazia:

 

 

Agora vamos criar alguns registros na nossa tabela. Note que usamos a %Populate como uma superclasse da nossa tabela. O IRIS permite herança múltipla, ou seja, uma classe pode ter diversas superclasses:

Class ws.database.cliente Extends (%Persistent, %Populate, %XML.Adaptor)

 

Esta superclasse permite que uma tabela seja populada com dados de teste. Volte ao Terminal e execute o comando abaixo:

Do ##Class(ws.database.cliente).Populate(10)

Veja o comando na janela do terminal:

 

Volte ao SQL Explorer e verifique o conteúdo da nossa tabela:

 

Veja que foram criados 10 registros para nossa tabela. A %Populate é a responsável por isso. Para mais informações veja em https://docs.intersystems.com/irislatest/csp/docbook/DocBook.UI.Page.cls?KEY=GOBJ_populate

 

Agora vamos voltar ao nosso BS e ativá-lo. Assim a integração fará a leitura dos registros que existem na tabela e criará a global ^Cliente:

 

Após marcar a caixa Habilitado clique em Aplicar e nossa integração já estará ativa.

Volte ao terminal e execute o utilitário ^%G e verifique agora a nossa global ^Cliente:

 

Veja que ela está preenchida com as informações da tabela. Volte a tabela e verifique os registros:

 

Os registros lidos foram eliminados da tabela.

 

Veja a lista de mensagens da integração:

 

E abrindo uma das mensagens vemos o trace da execução:

 

Com isso concluímos esta integração. Utilizamos em nosso teste o IRIS 2024.1 que está disponível para download na sua versão Community na internet.