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.
