SEI-Broker - Camada REST de acesso ao SEI

O SEI-Broker é uma camada de integração que foi desenvolvida para integrar os sistemas corporativos da ANS e o SEI, Sistema Eletrônico de Informações do TRF 4. Toda essa camada foi criada utilizando o padrão RESTful de serviços web, sua função é facilitar a integração dos sistemas da ANS com o SEI, utilizando um protocolo mais simples, moderno e performático. A adoção do broker nos permite criar uma camada de abstração para evitar que mudanças no SEI afetem as integrações, isso é possível pelo fato do broker utilizar REST e possuir contrato fraco.

O Broker atualmente está na versão 2.9, essa versão é compatível com o SEI 3.0.13. É importante destacar que é necessário atualizar o SEI-Broker a cada atualização do SEI que altere os serviços web.

Alguns serviços adicionais foram desenvolvidos para extrair dados que não são ofertados pelos serviços nativos do SEI, estes serviços fazem acesso a base de dados do SEI e realizam operações apenas de consulta. A escrita de dados continua a ser exclusividade dos serviços nativos, desta forma a integridade e coerência das inserções é mantida.

Requisitos

• SEI 3.0.13 instalado/atualizado.
• Código-fonte do Broker pode ser baixado a partir do link a seguir, sempre utilize uma versão compatível com o SEI: https://softwarepublico.gov.br/gitlab/ans/sei-broker/tags
• Apache Maven para baixar as dependências e compilar o pacote.
• Servidor JBoss EAP 7.0.4 ou Wildfly 10.
• Banco relacional, o Broker foi desenvolvido usando Oracle 12g, mas com pouco esforço pode utilizar o MySQL.
• Conexão com a internet para que o Maven acesse os repositórios hospedeiros das dependências.
• Ferramenta apiDoc para gerar a documentação da API.
• Templates-broker implantado e configurado. Este requisito é opcional, ele é necessário caso haja interesse em utilizar o Gerenciador de Templates.

Procedimentos para instalação

Configurar as propriedades dos datasources no JBoss.

O broker possui dois datasources e ambos estão declarados no arquivo sei-broker-ds.xml, eles são identificados como jdbc/sei-broker e jdbc/sei-mysql. O jdbc/sei-broker foi definido para acessar as tabelas que foram projetadas para o broker, o jdbc/sei-mysql se conecta ao banco de dados do SEI. O funcionamento dos datasources depende da declaração de algumas System Properties no JBoss.

Abaixo um exemplo de declaração de propriedades feita no arquivo standalone.xml.

<!-- Geralmente no início do arquivo, após as extensions -->
<system-properties>
    <!-- Outras propriedades ... -->
    <property name="br.gov.ans.seiBroker.db.oracle.connectionUrl" value="STRING_CONEXAO_BD_BROKER"/>
    <property name="br.gov.ans.seiBroker.db.oracle.password" value="SENHA_USUARIO_SEI_BROKER"/>
    <property name="br.gov.ans.seiBroker.db.mysql.user" value="USUARIO_MYSQL"/>
    <property name="br.gov.ans.seiBroker.db.mysql.connectionUrl" value="STRING_CONEXAO_BD_SEI"/>
    <property name="br.gov.ans.seiBroker.db.mysql.password" value="SENHA_USUARIO_BD_SEI"/>
</system-properties>

Criar e configurar os arquivos de propriedades no JBoss

O SEI-Broker faz uso de dois arquivos de propriedades que ficam na pasta <JBOSS_HOME>\ans\properties, os arquivos necessários são services.properties e ws-users.properties.

Arquivo Propriedade Descrição services.properties sei.ws.uri URL do SEI sip.ws.uri URL do SIP templates.broker.uri URL do templates-broker ws-users.properties sei.broker.user Usuário de integração do broker sei.broker.password Senha do usuário de integração

Criar security-domain no JBoss

É necessário que haja um security-domain registrado com o nome ans-ws-auth, o mesmo pode utilizar um banco de dados¹ ou o LDAP. É importante destacar que o Broker trabalha com autorização baseada em papéis(RBAC²) e que os usuários precisam ter seus papéis atribuídos.

Implantar pacote gerado pelo Maven

Após a realização de todos os passos anteriores, teremos o JBoss pronto para receber o pacote do SEI-Broker. O deploy pode ser feito de diversas maneiras e não é o foco desse manual.

Para essa etapa é necessário ter o Maven instalado e configurado. Ao realizar o primeiro build devemos desabilitar os testes automatizados, os testes dependem de uma instância ativa e impedirão a geração do pacote.

Configurar Sistema no SEI

É preciso cadastrar o SEI-Broker como um sistema que se integrará ao SEI, conforme manual de webservices do SEI. É importante ter atenção para a sigla que será definida, por padrão o broker está configurado para utilizar a sigla SEI-Broker.

Após o cadastro do Sistema precisaremos atribuir os serviços que serão utilizados pelo Broker, nesta etapa é preciso ter atenção para o valor que será definido no campo identificação e aos servidores. A identificação do serviço precisa ser enviada a cada requisição feita aos serviços do SEI, por padrão o Broker utiliza o valor REALIZAR_INTEGRACAO. No campo servidores informaremos os IPs dos servidores onde o SEI-Broker estará implantado.

Os valores utilizados pelo Broker podem ser configurados na classe Constantes, sigla e identificação são respectivamente SIGLA_SEI_BROKER e CHAVE_IDENTIFICACAO.

Gerar documentação da API

Após a implantação é fundamental que a documentação da API seja disponibilizada para os clientes do Broker. A documentação do Broker foi escrita utilizando a ferramenta apiDoc e os fontes estão no diretório /src/main/resources/apidoc/. Será preciso fazer a instalação do apiDoc³ e executar o comando abaixo na raiz do projeto.

apidoc -f ".*\\.apidoc$" -i src/main/resources/apidoc/ -o <CAMINHO_ONDE_DOCUMENTACAO_SERA_GERADA>

A documentação gerada deve ser disponibilizada em um local onde possa ser facilmente acessada pelos clientes.

Serviços complementares

Além dos serviços disponibilizados pelo SEI, o Broker possui alguns serviços adicionais que foram desenvolvidos para atender às necessidades que surgiram com o avanço das integrações.

Autenticação e Autorização

A autenticação no SEI-Broker é feita através do HTTP Basic e a autorização é baseada em roles/papéis que são atribuídas ao usuário. Os sistemas que utilizarão o broker precisarão de um usuário, esse usuário deve ser previamente cadastrados em uma fonte de dados e receber a role correspondente às suas necessidades. Esses dados serão verificados pelo security-domain ans-ws-auth que foi configurado no JBoss.

Roles/Papéis

Existem duas roles de acesso ao Broker, uma com acesso a todas funcionalidades e outra somente para consulta. As roles precisam ter o nome idêntico ao definido no Broker, caso haja divergência o acesso será negado pelo JAAS.

Templates documentos internos

Através do Broker é possível preencher templates em HTML e incluí-los como documentos internos no SEI. O Objetivo é facilitar o desenvolvimento, aumentar a manutenibilidade e tornar os documentos mais ricos e dinâmicos.

Os templates usados no Broker são criados utilizando a ferramenta Mustache e devem ser cadastrados no Gerenciador de Templates, durante a inclusão do documento o templates-broker será consultado. O código em HTML gerado pelo SEI-Broker será inserido dentro do campo conteúdo do modelo de documento feito no SEI. Os detalhes da utilização estão na documentação da API.

É preciso deixar claro que os templates do broker não substituem o modelo de documento do SEI.

Monitoramento do SEI-Broker

O SEI-Broker oferece três serviços de monitoramento, esses serviços verificam as principais conexões do broker.

Os serviços respondem com HTTP status 200 caso as conexões estejam ativas, qualquer outro status é considerado como erro de conexão.

Projetos Relacionados

• Templates-Broker
• Gerenciador de Templates