Desenvolvendo Intergrações com o InterSystems IRIS

Artigo

Julio Esquerdo · Out. 10 10min de leitura

Projeto 1 - Integração utilizando SOAP Inbound Adapter

A idéia deste novo conjunto de postagens é apresentar uma série de integrações utilizando o InterSystems IRIS. Vamos ver integrações REST, SOAP, utilizando adaptadores ODBC, Arquivos e outros.

Vamos montar nossa primeira integração completa, passando pelas camadas de BS, BP e BO, e devolvendo a resposta esperada. Vamos montar essa nossa primeira integração utilizando o SOAP como o adaptador de entrada, e como cliente vamos utilizar o SoapUI.

Vamos então começar:

1. SoapUI

Baixe o SoapUI do site de download dele (https://www.soapui.org/downloads/soapui/) Nesta tela você poderá optar por baixar o SoapUI Open Source conforme a tela abaixo:

Baixe e instale o produto. Ao executar você verá a seguinte tela:

Pronto. Você já está com o SoapUI instalado e pronto para realizar os testes na sua integração.

2. IRIS

Agora vamos para o IRIS. Após instalar o IRIS e criar um namespace com a opção de Interoperabilidade ativada, vamos então criar as mensagens que vão fazer parte da nossa integração. Vamos criar um Request e um Response conforme abaixo:

Class ws.demo.msg.Request Extends Ens.Request
{

Property string1 As %String;

Property string2 As %String;

}

Class ws.demo.msg.Response Extends Ens.Response
{

Property saida As %String;

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 receber as requisições:

Class ws.demo.bs.Service Extends EnsLib.SOAP.Service
{

Parameter ADAPTER = "EnsLib.SOAP.InboundAdapter";

Parameter SERVICENAME = "entrada";

Method entrada(pInput As ws.demo.msg.Request) As ws.demo.msg.Response [ WebMethod ]
{
              Set tSC=..SendRequestSync("bpEntrada",pInput,.tResponse)
              If $$$ISERR(tSC) Do ..ReturnMethodStatusFault(tSC)
              Quit tResponse
}

}

Note que nosso BS tem como superclasse EnsLib.DSOAP.Service e usa o adaptador EnsLib.SOAP.InbloudAdapter. Isso habilita nosso BS a trabalhar como um BS SOAP, recebendo as requisições neste padrão.

Agora vamos criar nosso BO conforme abaixo:

Class ws.demo.bo.Operation Extends Ens.BusinessOperation [ ProcedureBlock ]
{
Method entrada(pRequest As ws.demo.msg.Request, Output pResponse As ws.demo.msg.Response) As %Library.Status
{
Set pResponse=##Class(ws.demo.msg.Response).%New()
Set pResponse.status=1
Set pResponse.mensagem="OK"
Set pResponse.sessionId=..%SessionId
Set pResponse.saida=pRequest.string1_" "_pRequest.string2
Quit $$$OK
}
XData MessageMap
{
<MapItems>
              <MapItem MessageType="ws.demo.msg.Request">
                            <Method>entrada</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 etrada.

Note também que neste BO não estamos utilizando nenhum adaptador. Ele trabalha sem fazer chamadas externas. Desta fora não vamos precisar para este exemplo de nenhum tipo de comunicação. As próximas integrações já teremos chamadas externas.

Agora, por fim, vamos montar nosso BP, que é o orquestrador das chamadas da integração. No nosso exemplo teremos apenas uma única chamada, mas nosso BP poderia orquestrar chamadas para diversos BOs.

O código do nosso BP ficará assim:

///
Class ws.demo.bp.entrada Extends Ens.BusinessProcessBPL [ ClassType = persistent, ProcedureBlock ]
{ /// BPL Definition
XData BPL [ XMLNamespace = "http://www.intersystems.com/bpl" ]
{
<process language='objectscript' request='ws.demo.msg.Request' response='ws.demo.msg.Response' height='2000' width='2000' >
<sequence xend='200' yend='350' >
<call name='boEntrada' target='boEntrada' async='0' xpos='200' ypos='250' >
<request type='ws.demo.msg.Request' >
<assign property="callrequest" value="request" action="set" languageOverride="" />
</request>
<response type='ws.demo.msg.Response' >
<assign property="response" value="callresponse" action="set" languageOverride="" />
</response>
</call>
</sequence>
</process>
} Storage Default
{
<Type>%Storage.Persistent</Type>
}

}

Agora vamos criar nossa production e colocar as classes nela. Vamos no Painel de Administração->Interoperabilidade e vamos configurar uma nova produção, lembrando que a classe da produção já está no pacote de download:

Clique em Novo e preencha a tela a seguir:

Clique em OK e a produção estará criada. Agora clique no botão (+) ao lado do título Services para incluir o nosso BS na produção:

Preencha a tela conforme acima e clique em OK.

Pronto. O BS já está na production. Agora clique em OK na tela que está apresentada para voltar a tela da produção.

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

Preencha a tela conforme acima e clique em OK.

Pronto. Nosso BP já está na produção. Agora clique em OK para voltar a tela de configuração da produção. E então vamos clicar no botão (+) ao lado do título Operations:

Preencha a tela conforme acima, clique em OK e teremos nosso BO na produção.

Agora clique em OK para voltarmos a tela de configuração da produção:

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

Agora clique sobre o nome do nosso BS expanda a área Parâmestros de Conexão e marque a caixa Habilitar Requisições Padrão, conforme a tela a seguir:

Feita a configuração da produção nossa integração está pronta para uso. Abra o SoapUI e vamos agora importar nosso WSDL. O WSDL é a definição do serviço SOAP. Caso você queira ve-lo antes da importação abra um navegador e vá para o endereço http://localhost/csp/<namespace>/ws.demo.bs.Service.cls?WSDL=1 onde <namespace> é o nome do namespace que você criou para armazenar sua integração. No nosso caso o namespace se chama integra:

Então, voltando ao SoapUI, vamos importar nosso WSDL:

Abra o SoapUI e no menu File clique em New Soap Project:

Preencha a caixa Initial WSDL com o endereço do nosso WSDL. O SoapUI vai preencher sozinho a caixa Project Name. A seguir clique em OK

Abra o treeview do projeto até chegar em Requst 1. Clique neste titulo e você verá a tela com as informações para chamar o serviço:

Preencha string 1 e string 2 com o que você quiser, seu nome e sobrenome por exemplo, e clique na seta verde de play. Você verá então a resposta do serviço na janela ao lado:

Pronto! Realizamos a chamada do nosso serviço e foi devolvida a resposta:

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

<SOAP-ENV:Envelope xmlns:SOAP-ENV='http://schemas.xmlsoap.org/soap/envelope/' xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' xmlns:s='http://www.w3.org/2001/XMLSchema'>

<SOAP-ENV:Body><entradaResponse xmlns="http://tempuri.org">

<entradaResult><saida>Abel Silva</saida>

</entradaResult></entradaResponse>

</SOAP-ENV:Body>

</SOAP-ENV:Envelope>

Agora podemos voltar a nossa produção e ver o trace da nossa integração. Clique sobre o nome do nosso BS e a seguir clique em Mensagens e a seguir em Ir para o Visualizador de mensagens. Localize o SessionID que você recebeu na sua resposta e clique neste número. Então você verá o trace da nossa integração:

Veja que você pode ver o que cada componente recebeu, o tempo de duração de cada chamada, o que foi devolvido e o fluxo geral da integração. Isso é especialmente útil para você administrar ambientes complexos e com grande número de integrações, além de permitir que em caso de necessidade você possa reenviar uma mensagem que por algum motivo não tenha sido processada.

Agora, caso se deseje incluir uma autenticação no serviço, vamos primeiro precisar criar um usuário. Vamos em Portal de Administração/ Segurança/Usuarios e clique em Criar Novo Usuário:

Preencha a tela conforme acima. Informe a senha desejada e lembre de marcar as caixas ‘A senha nunca expira’ e ‘A conta nunca expira’ para que a conta esteja ativa. Você pode aqui colocar as opções de expiração de acordo com o que seu ambiente exija de segurança. Para nosso teste vamos deixar sem expiração.

Após salvar o usuário clique em Roles e selecione a Role %All para este usuário. Clique em Associar. Esta role %All dará total acesso ao seu ambiente para este usuário.

Pronto. O usuário está criado. Podemos criar um usuário com acesso mais restrito, mas no nosso caso não estamos avaliando a questão de segurança e nível de acesso, apenas determinando que o serviço tenha autenticação. Em próximas etapas veremos a parte de segurança do IRIS que é bem completa.

IMPORTANTE: Depois, se for o caso, exclua este usuário do seu ambiente. Ele tem acesso FULL a sua instancia IRIS.

Agora vá em Administração do Sistema/Segurança/Aplicações/Aplicações Web e procure a aplicação web referente ao seu namespace. No nosso caso /csp/integra:

Procure a sessão Métodos permitidos para autenticação, desmarque a caixa Não Autenticado e marque a caixa Senha, e a seguir clique em Salvar.

Volte ao SoapUI e novamente clique no botão de Play. Você verá que agora o SoapUI recebeu um erro da integração:

<?xml version='1.0' encoding='UTF-8' standalone='no' ?>

<SOAP-ENV:Envelope xmlns:SOAP-ENV='http://schemas.xmlsoap.org/soap/envelope/' xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' xmlns:s='http://www.w3.org/2001/XMLSchema' xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secex..." >

<SOAP-ENV:Body>

<SOAP-ENV:Fault>

<faultcode>wsse:FailedAuthentication</faultcode>

<faultstring>The security token could not be authenticated or authorized</faultstring>

<detail></detail>

</SOAP-ENV:Fault>

</SOAP-ENV:Body>

</SOAP-ENV:Envelope>

Veja que o serviço informou que não pode validar o token de segurança pois o mesmo não foi informado. Vamos criar esse token alterando a Request Properties do serviço, logo abaixo na tela do SoapUI:

Informe o nome do usuário, senha e na caixa WSS-Password Type selecione PasswordText. Agora reenvie a sua requisição e você terá a resposta correta:

3. TCPTRACE

Uma ferramenta muito útil quando estamos trabalhando com integrações é o TCPTrace que permite verificar o tráfego TCP de uma conexão. Vamos colocar o TCPTrace para rodar e configurar nosso ambiente para vermos o trace das informações. Execute o TCPTrace do seu local de instalação:

Você verá a tela de configuração. Essa configuração diz ao TCPTrace para monitorar a porta 8080 e repassar o que receber para a porta 80. Preencha como acima e clique em OK. Agora volte ao SoapUI e vamos dizer que o serviço deve se comunicar com a porta 8080 que é a que o TCPTrace está “escutando”:

Logo após o localhost do endereço do serviço informa que a porta é a 8080. O endereço completo ficará assim:

http://localhost:8080/csp/integra/ws.demo.bs.Service.cls

Clique novamente no botão de Play e veja a tela do TCPTrace:

Todo o tráfego foi registrado, tanto do envio do SoapUI quanto do retorno do serviço. Podemos ver, por exemplo o token de segurança do nosso serviço:

<wsse:UsernameToken wsu:Id="UsernameToken-6780B0C4521A4F63E517261668857132"><wsse:Username>service</wsse:Username><wsse:PassworIntegrações utilizando o InterSysted Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-p...">123</wsse:Password>

IMPORTANTE: Aqui estamos usando o que chamamos de Basic Auth, ou seja uma autenticação básica. Os dados de usuário e senha são enviados no header do pacote sem criptografia. Em produção devemos para este caso estar usando um protocolo HTTPS para que o pacote seja criptografado. A ativação do HTTPS envolve um certificado a ser instalado no seu web server (IIS, Apache ou outro suportado pelo IRIS).

Assim fechamos nossa primeira integração. As classes envolvidas estão no pacote de download, basta baixar o pacote e importar para dentro do seu namespace. Após isso você pode abrir todas as classes e verificar todos os pontos.

Utilizamos em nosso teste o IRIS 2024.1, o SoapUI e o TCPTrace. Todos estão disponíveis para download nas suas versões Community na internet.

Até a próxima integração!

Desenvolvendo Intergrações com o InterSystems IRIS - SOAP Inbound Adapter