Introdução

Combinado com o avanço do Maximo em diversas indústrias e por sua participação cada vez mais presente em soluções Smart, a necessidade de integração com essa plataforma vem aumentando significativamente, principalmente no contexto de processos de monitoramento e manutenção. E por esta razão iremos fornecer um breve artigo de como utilizar componentes opensource para agilizar a criação de um cliente MIF, que posteriormente pode ser utilizado como referência para integrações mais complexas e reutilizáveis.

Ao final deste artigo é esperado que o leitor compreenda o papel dos componentes opensource na integração com o Maximo como também obtenha uma visão introdutória ao MIF e suas interfaces.

Introdução ao MIF

É a camada de integração do Maximo e possibilita que sistemas externos troquem informações através de interfaces já criadas. Essas interfaces são compostas por objetos de negócio do Maximo, e internamente representadas através da aplicação chamada Object Structure.

Atualmente é possível se conectar ao Maximo através de diversas maneiras, entre elas, WebServices, EJB, HTTP, entre outros.

Neste artigo será considerado o uso do Object Structure MXINCIDENT e XML sobre o protocolo HTTP.
Para isso o cliente MIF necessita submter a mensagem XML para uma URL especifica do Maximo e receber sincronamente a mensagem XML de retorno.

O XML utilizado para a troca de mensagens através do MIF é geralmente chamada de Maximo XML, e sua estrutura é similar ao exemplo abaixo:

            
            
            <?xml version='1.0' encoding='UTF-8'?>
            <DeleteMXPROBLEM (1)
                xmlns="http://www.ibm.com/maximo"
                creationDateTime="2010-12-02T22:54:45-0200"
                transLanguage="EN" (2) 
                messageID="3800271411595100160"
                maximoVersion="7 1 20091208-1415 V7116-173">
                <MXPROBLEMSet> (3)
                   <PROBLEM> (4)
                     <CLASS>PROBLEM</CLASS> (5)
                        <TICKETID>89892</TICKETID>
                    </PROBLEM>
                </MXPROBLEMSet>
            </DeleteMXPROBLEM>
            
        

Onde:
(1) Operação (Delete) e nome do Object Structure (MXPROBLEM);
(2) Idioma da mensagem (EN);
(3) Nome do Object Structure e literal Set / Query;
(4) Nome do objeto (MBO) principal do Object Structure;
(5) Lista de atributos

As operações suportadas pela aplicação exemplo são Delete, Update, Query e Create. Outras operações, como Sync, não são consideradas neste artigo, porém podem ser aplicadas em outros cenários de integracão.

Dependendo da operação realizada a lista de atributos pode ter diferentes funções:
- Update: alguns atributos devem compor a chave única do registro, enquanto outros serão os novos valores do registro;
- Delete: os atributos devem compor a chave única do registro a ser apagado;
- Query: cada atributo é utilizado como parâmetro de pesquisa, similar a uma clausula Where;
- Create: os atributos informados serão gravados na criação do registro.

Especificamente sobre a operação de Query, um novo elemento deve ser considerado: o operador de pesquisa. Para este artigo os operadores “=”, “<” e “>” são considerados válidos.

Para mais detalhes sobre as operações suportadas pelo Maximo XML, assim como as particularidades de cada operação, utilize o guideline de integração do Maximo (verificar link na seção Recursos deste artigo)

Configuração Maximo

Para qualquer integração com o Maximo através do MIF é necessário definir, se necessário, alguns parâmetros de configuração do Maximo. As seguintes propriedades devem ser verificadas:
- mxe.int.webappurl: representa a URL padrão onde os serviços HTTP do MIF serão disponibilizados.
- mxe.int.globaldir: indica o diretório no servidor onde os esquemas (XSD) do MIF são armazenados.

Utilize a aplicação System properties para realizar as configurações acima e utilize o guia de integração do Maximo para maiores detalhes.

Funcionamento do cliente MIF

Para um bom entendimento deste artigo, é necessário conhecer os principais elementos utilizados na aplicação exemplo, como também os relacionamentos entre eles. Nesta seção serão apresentados detalhes da aplicação exemplo e os componentes opensource utilizados.

Relacionado a aplicação exemplo, os elementos mais importantes são:

• TemplateLoader: responsável por carregar os templates XML e substituir os valores recebidos como parâmetro nos placeholders adequados.
• Attribute: representa cada parâmetro recebido no formato (campo,operador,valor) nas operações internas do cliente.
• HTTPDispatcher: responsável por enviar a mensagem XML para o Maximo.
• Invoker: classe principal do cliente que gerencia o fluxo de entrada, processamento e saída de uma invocação.

O diagrama de sequência acima apresenta as principais trocas de mensagem entre as classes do exemplo.
Ressaltando que se trata de um processamento síncrono e que o Maximo irá retornar uma mensagem de resposta confirmando que a mensagem original foi recebida e processada com sucesso. Caso contrário, uma exceção é gerada pelo objeto HTTPDispatcher.

Os componentes utilizados são todos da familia Apache e são descritos a seguir:

• Velocity: utilizado na substituição dinâmica de templates XML do MIF
• HttpClient: responsável pelo envio de mensagens ao Maximo sobre o protocolo Http
• Log4J: utilizado para a saída de logs (registro de operações, debug, erros, etc.)
• Commons: compartilhado pelos componentes acima e para o tratamento de String, Properties, Collections entre outros.

O relacionamento entre os componentes e o código fonte da aplicação exemplo é explicado na seção seguinte – Decifrando o código-fonte.

Decifrando o código-fonte

Nesta seção iremos explorar os principais elementos disponibilizados no exemplo deste artigo. Os pontos mais importantes são:

• Templates XML
• Substituição dinâmica
• Cliente HTTP
• Parâmetros de linha de comando

O uso do Velocity nesta solucão é para transformar os templates XML em mensagens que possam ser enviadas para o Maximo. A seguir discutiremos um exemplo da mensagem de Create e como ela foi gerada.

            <?xml version='1.0' encoding='UTF-8'?>
            <Create${mos_name}
            xmlns="http://www.ibm.com/maximo"
            creationDateTime="$creation_date_time"
            transLanguage="${trans_language}"
            messageID="${message_id}"
            maximoVersion="${maximo_version}">
                <${mos_name}Set>
                    <${mbo_name}>
                        ${mbo}
                    </${mbo_name}>
                </${mos_name}Set>
            </Create${mos_name}>
        
        

No template acima, é possível observar o esqueleto da mensagem e também as variáveis de substituição (placeholder) que serão posteriormente trocadas por valores reais.
O padrão ${variável} é reconhecido pelo engine do Velocity e então substituído conforme demonstra o exemplo a seguir.

    ...	
    Velocity.init();
    
    VelocityContext context = new VelocityContext();
    
    //Map XML template with parameters
    ...
    context.put("mos_name", StringUtils.upperCase(this.objectStrucName));
    context.put("mbo_name", StringUtils.upperCase(objectname));
    ...			
    
    Template template = Velocity.getTemplate(LoaderUtils.getTemplateName(operation));
    
    //Invoking Velocity to merge xml with context
    template.merge(context, writer);
    
    //Retrieving template already modified with real values
    this.strResult = writer.toString();
    ...
        

        

O código acima detalha os passos para a utilização do Velocity para a montagem da mensagem final a ser enviada ao Maximo. Seguem:

1. Criação e montagem do contexto do Velocity;
2. Recuperação do template a ser utilizado;
3. Merge do template com o contexto;
4. E posteriormente a recuperação da mensagem final.

Após o processamento do template, o resultado final obtido é similar com o apresentado abaixo.

            
            
            <?xml version='1.0' encoding='UTF-8'?>
            <CreateMXINCIDENT
            xmlns="http://www.ibm.com/maximo"
            creationDateTime="2010-11-30T19:49:54-0200"
                transLanguage="EN"
                    messageID="4138638688644603904"
                        maximoVersion="7 1 20091208-1415 V7116-173">
                <MXINCIDENTSet>
                    <INCIDENT>
                        <CLASS>INCIDENT</CLASS><DESCRIPTION>test2</DESCRIPTION>
                    </INCIDENT>
                </MXINCIDENTSet>
            </CreateMXINCIDENT>
            
        

O uso do Velocity para esta aplicação é relativamene pequeno, porém de extrema importância, pois além de otimizar a montagem do XML, facilita futuras manutenções e aumenta significativamente a performance se comparada a criação de XML através de um parse.

O mesmo procedimento é utilizado para as outras operações (update, delete e query) que possuem os respectivos arquivos de template XML.

Quando chega o momento de enviar a mensagem pela classe TemplateLoader.java ao Maximo, entra em cena o componente HttpClient e relacionados (StringEntity, HttpPost, Entity e HttpResponse).

        
        HttpClient client = new DefaultHttpClient();
        HttpPost post = new HttpPost(httpConnInfo[0]);
        HttpResponse response;
        
        ...
        
        try {
        
             //Set message on StringEntity object
             StringEntity strEntity = new StringEntity(message);
             
             //Set header fields values
             strEntity.setContentType("text/html");
             strEntity.setChunked(false);
             strEntity.setContentEncoding("UTF-8");
             
             //Associate entity with HttpPost object
             post.setEntity(strEntity);
             
             //Submit message and retrieves Entity response
             response = client.execute(post);
             HttpEntity entity = response.getEntity();
             
             //Get response from HttpEntity object
             retValue = EntityUtils.toString(entity);	
             
         } catch (ClientProtocolException e) {
         ...
         } catch (IOException e) {
         ...
         } finally {
         //Close Http connection
         client.getConnectionManager().shutdown(); 
         }
        
        

Os passos para o envio da mensagem podem ser resumidos em:

1. Configurar o objeto StringEntity, definindo a mensagem a ser enviada e os parâmetros do header;
2. Associar o objeto StringEntity ao objeto HttpPost;
3. Executar o post e recuperar a mensagem de resposta ;
4. Fechar a conexão Http com o Maximo.

Se processado com sucesso pelo Maximo, a seguinte mensagem é retornada ao cliente, indicando a chave primária do recem-criado registro.

            <?xml version='1.0' encoding='utf-8'?>
            <CreateMXINCIDENTResponse xmlns="http://www.ibm.com/maximo" 
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
            creationDateTime="2010-12-03T10:13:54-02:00" 
            transLanguage="EN" 
            baseLanguage="EN" 
            messageID="1291378434359707296">
                <INCIDENTMboKeySet>
                    <INCIDENT>
                    <CLASS maxvalue="INCIDENT">INCIDENT</CLASS>
                        <TICKETID>1158</TICKETID>
                    </INCIDENT>
                </INCIDENTMboKeySet>
            </CreateMXINCIDENTResponse>
            
            
            
        

Dependendo da operação a mensagem de retorno será diferente.

Para simplificar a forma de invocação deste cliente, optamos pelo métode de linha de comando, cuja responsabilidade de processamento é designada a class Invoker.

Os parâmetros esperados por essa classe estão de acordo com o seguinte padrão:

Exemplos:
Create MXINCIDENT INCIDENT “(description,=,server has failed)” (owner,=,maxadmin)
Update MXINCIDENT INCIDENT (ticketid,=,1137) (priority,=,1)
Query MXWO WO (WONUM,=,4351)

Sobre os demais componentes opensource utilizados (Log4J e Commons), os mesmos podem ser encontrados em quase todas as classes da aplicação.

Especificamente em Invoker.class é possível observar a instanciação do configurador do Log4J através da linha BasicConfigurator.configure();

Lembre-se que para utilizar o Log4J na configuração mais simples, os seguintes passos são necessários:

1. utilizar o arquivo de configurações log4j.properties no classpath da aplicação;
2. em cada classe, iniciar o logger com a seguinte instrução: static Logger logger = Logger.getLogger(<className>.class.getName()); ; onde <className> deve ser o nome da classe corrente;
3. iniciar o configurador através da linha BasicConfigurator.configure(); na classe principal da aplicação (main);
4. invocar o logger através de comandos como logger.info(), logger.debug(), entre outros.

Não se esqueça que o uso excessivo de log pode influenciar na performance da sua aplicação, portanto registre passagens importantes do seu código e use tipos de log apropriados (debug, info, warning, error) para cada necessidade.

Outro ponto importante do código que precisa ser considerado é o arquivo de propriedades de configuração da aplicação exemplo.

#set the maximo integration framework URL
            mxe.int.webappurl=http://localhost:7001/meaweb/os/

Os detalhes para a configuração da URL são descritos abaixo:

onde:

• host: nome da máquina onde o Maximo está instalado;
• port: porta onde o serviço HTTP está respondendo;
• objectstructure_name: Nome do object structure a ser acessado

Executando a aplicação exemplo

Para executar o exemplo fornecido neste artigo, é necessário importar o arquivo Zip anexado como um projeto Java do Eclipse. Seguem os passos para essa importação:

Para resolver os problemas de dependências, usar a seguinte tabela, que apresenta os componentes utilizados e as respectivas bibliotecas necessárias para a execução da aplicação exemplo. Estas bibliotecas estão disponíveis no site do Apache para download e uso, de acordo com as suas respectivas licenças.

Tabela de componentes e bibliotecas opensource

Finalizada a importação e a configuração das dependências (ver tabela de dependências), é possível executar o exemplo. Os passos para a execução estão descritos abaixo.

Selecionar a opção Java Application no menu lateral esquerdo da caixa de dialogo e então selecionar a tab “(x) = Arguments” na seção lateral direita. Incluir os argumentos do programa na caixa de texto “Program arguments” de acordo com as regras de linha de comando já comentadas neste artigo. Clicar no botão “Run”.

Durante a execução a mensagem enviada e recebida serão apresentadas na tab Console. Assim como qualquer exceção ou informação complementar ao processamento.

Ao variar as operações suportadas e os objetos, será possível visualizar as diferenças entre parâmetros de envio como também o conteúdo retornado pelo Maximo. O ambiente do Maximo utilizado na criação da aplicação exemplo foi o MBS 7.1.1.7, porém é esperado compatibilidade com as plataformas superiores ao MBS 7.1.1.4.

Conclusão

Neste ponto do artigo é esperado que o leitor tenha adquirido um conhecimento básico da plataforma de integração Maximo e principalmente da facilidade de usar bibliotecas opensource para a construção de um cliente integrado com o MIF.

São sugeridos leituras e testes específicos para aprofundamento nas bibliotecas aqui apresentadas, como também na arquitetura de integração Maximo. Mais informações podem ser conseguidas nos sites disponibilizados na seção Links.

Alguns tópicos como segurança (autenticação e SSL), multi-tarefa, mensagens assíncronas e outros pontos da integração com o Maximo, não foram discutidos neste artigo para não aumentar a complexidade do mesmo e permitir um início coeso e aplicável.

Novos artigos virão para aumentar o conhecimento do leitor, como também explorar novos aspectos da integração do Maximo com sistema externos.

Recursos

- Maximo home page: http://www-947.ibm.com/support/entry/portal/Overview/Software/Tivoli/Maximo_Asset_Management
- Maximo Integration Guideline (pdf): http://www-947.ibm.com/support/entry/portal/Overview/Software/Tivoli/Maximo_Asset_Management
- Apache home page: http://www.apache.org/

Glossário

• MIF: Maximo Integration Framework – Camada de integração da plataforma Maximo.
• OS : Object Structure – aplicação que consolida objetos de negócios e relacionamentos a fim de expô-los como interfaces para sistemas externos.
• MBO : Maximo Business Object – representa os componentes utilizados internamente pelo Maximo para operações de negócio.
• MBS : Maximo Base Services – nome dado à plataforma genérica do Maximo onde customizações e soluções para indústria são desenvolvidos.

Voltar para parte superior

Download

Informações sobre métodos de download

Sobre o autor

Leucir é Engenheiro de software do Laboratório de desenvolvimento Brasil e vem desempenhando papel de liderança em integrações do Maximo com diversas plataformas no mercado. Possue 13 anos de experiência no mercado de TI, todos eles voltados para a indústria de software. Ver Perfil no My developerWorks

Classificar este artigo

Comentários

Voltar para parte superior

Índice

• Introdução
• Introdução ao MIF
• Configuração Maximo
• Funcionamento do cliente MIF
• Decifrando o código-fonte
• Executando a aplicação exemplo
• Conclusão
• Recursos
• Glossário
• Download
• Sobre o autor
• Comentários

Conheça a IBM da sua cidade

A IBM está mais perto do que você imagina!

---

Saiba mais