Perguntas Frequentes

Nesta seção serão apresentadas respostas para as perguntas mais frequentes relacionadas ao uso da stack de desenvolvimento de softwares institucionais.

Para as dúvidas técnicas sobre a construção de módulos de negócio (como criar um módulo, configurar banco, i18n, rotas, permissões), consulte o guia do desenvolvedor na seção Modularização.

1. Gostei do boilerplate, mas preciso que a solução seja hospedada fora do ambiente de infraestrutura do GTI, é possível?

Sim é possível. Todos os recursos configurados no Boilerplate podem ser ajustados e/ou são acessados por serviços de rede (Ex.: Keycloak, Matomo, Sentry), desta forma podem ser “publicados” em infraestrutura diferente da do GTI.

A exceção é o MongoDB do ETL corporativo, que não é acessível fora da rede da Sede: soluções hospedadas fora dela devem consumir os dados corporativos pelas APIs corporativas, com o ajuste descrito no item 8.

2. Como faço para contribuir com o desenvolvimento do boilerplate?

Após obter acesso ao repositório do projeto do boilerplate no Embrapa I/O, crie uma branch para contemplar suas alterações e depois submeta-a através de um Merge Request. Antes de realizar alguma alteração entre em contato com a equipe da SDSS (Francisco José de Menezes Lima, Rodrigo Pinheiro dos Santos e/ou Joilton Almeida de Jesus) para verificar se já não existe alternativa ou implementação em curso para sua demanda.

Vale reforçar: correção ou melhoria em código genérico (o host, o projeto Core ou o Integracoes) deve ir por Merge Request ao boilerplate, e não como correção local no seu projeto — do contrário ela se perde na próxima sincronização com a base.

3. Existe previsão de construção de boilerplates em outras linguagens de programação além do .NET?

No momento a GTI pretende melhorar e intensificar o uso deste boilerplate não tendo previsão de construção de solução semelhante em outra linguagem de programação. Contudo, vale ressaltar que a plataforma do Embrapa I/O possui diversos outros boilerplates construídos em várias plataformas de programação com o foco no desenvolvimento de ativos digitais.

4. Posso utilizar o layout Spark Bootstrap em uma aplicação sem utilizar o boilerplate?

Sim pode. Basta baixar o layout aqui. ATENÇÃO: Este layout foi adquirido pela Embrapa para uso em soluções corporativas apenas e NÃO pode ser utilizado para quaisquer fins comerciais, o qual exige a compra de uma licença específica para cada solução em uso. Ressaltamos também que a licença adquirida cobre única e exclusivamente seu uso pela Embrapa e não pode ser repassada para uso por terceiros e/ou particular.

5. Como obtenho as credenciais de autenticação para a minha solução?

A autenticação das soluções Web construídas sobre o boilerplate é delegada ao Keycloak institucional, por meio do protocolo OpenID Connect. O Keycloak substituiu a integração direta com o Google OAuth utilizada até 2025 — o boilerplate mantém o mecanismo de revinculação das contas migradas, de modo que o usuário que já acessava a solução pelo login Google continua acessando normalmente.

Cada aplicação deverá possuir o seu próprio client OIDC, por ambiente, com credenciais próprias (Authority, Client Id e Client Secret). Estas credenciais são fornecidas somente através de uma solicitação ao GTI, via chamado na Central de TI, conforme descrito a seguir:

Tipo de Chamado: Solicitação de Serviço
Categoria: Sistemas
Subcategoria: Sistemas Corporativos Embrapa
Serviço: Conceder/revogar permissão de acesso a sistemas corporativos
Grupo de operadores: SEDE - 2 - SDSS - APIs e Webservices

Abrir um chamado para cada sistema/solução (consumidora) identificando:

O nome do sistema;
A unidade requisitante;
As URIs de redirecionamento após a autenticação, incluindo portas, identificadas por ambiente (Desenvolvimento, Homologação e Produção). No boilerplate, a URI de redirecionamento termina sempre em /signin-oidc — ex.: https://minhasolucao-d.nuvem.ti.embrapa.br/signin-oidc;
Se a solução necessitará de autocadastro de usuários externos (nesse caso são fornecidas também as credenciais de administração de realm, KEYCLOAK_ADMIN_CLIENT_ID / KEYCLOAK_ADMIN_CLIENT_SECRET).

Obs.: Não serão aceitas URIs de redirecionamento que sejam para domínios não Embrapa, exceto que seja alguma solução da Embrapa publicada em cloud pública.

6. É possível utilizar a autenticação institucional em uma solução fora do Boilerplate?

Sim. Como o Keycloak fala OpenID Connect, um protocolo padrão de mercado, existem bibliotecas de integração para praticamente todas as plataformas de desenvolvimento. Localize a biblioteca que melhor atenda à sua stack e solicite as credenciais do client conforme detalhado no item 5.

7. Existe previsão de integração da autenticação com outros provedores, por exemplo, Gov.br?

Com a adoção do Keycloak, essa passou a ser uma questão de configuração do realm, e não de código da aplicação. O Keycloak suporta a federação com múltiplos provedores de identidade (Gov.br, Microsoft Entra, LDAP, outros provedores OIDC/SAML), e a aplicação continua enxergando um único ponto de login. Demandas desse tipo devem ser encaminhadas à equipe da SDSS via chamado na Central de TI.

8. Onde foram parar as APIs corporativas de empregado e unidade?

Depende de onde a sua solução vai rodar. A configuração que vem pronta no boilerplate atende ao cenário dos sistemas corporativos desenvolvidos pelo GTI e hospedados na Sede; fora dele, é necessário um ajuste, descrito adiante.

Sistemas corporativos na Sede (configuração padrão do boilerplate)

O consumo de dados corporativos (empregados, unidades, pessoas físicas e jurídicas, localidades) passou a ser feito por conexão direta ao MongoDB do ETL corporativo, e não mais pelas APIs publicadas no API Gateway. Por isso, o registro do HttpClient autenticado no API Gateway foi removido do boilerplate. Solicite a string de conexão à equipe da SDSS.

Soluções fora da Sede

O MongoDB corporativo não é acessível fora da rede da Sede. Nesse caso, o consumo de dados corporativos deve ser feito 100% pelas APIs corporativas, e cabe ao desenvolvedor da solução ajustar a camada de integração para buscar os dados nas APIs em vez do MongoDB.

O ajuste é localizado, e de propósito. Em qualquer um dos dois cenários, o código de negócio nunca fala com a fonte de dados diretamente: ele depende apenas das interfaces de Core/Contracts/Institucional/ — IEmpregadosGateway, IUnidadesGateway, IPessoasGateway, ILocalidadesGateway, IFotoEmpregadoGateway. A implementação vive isolada no projeto Integracoes, que é o único ponto da solução que conhece o MongoDB.

Trocar a origem dos dados, portanto, significa reescrever apenas as implementações dentro de Integracoes para consumirem as APIs corporativas, mantendo as mesmas interfaces. Nenhuma página, service ou módulo precisa ser alterado — eles continuam recebendo os gateways por injeção de dependência, sem saber de onde o dado veio.

Para isso você vai precisar:

Solicitar as credenciais de acesso às APIs corporativas junto à equipe responsável;
Registrar o HttpClient autenticado no API Gateway — o passo a passo está na seção Boilerplates, incluindo os placeholders de configuração a declarar;
Substituir as implementações dos gateways em Integracoes/ pelas versões que consomem as APIs, removendo a dependência do MongoDB.Driver e as variáveis MONGO_*.

Atenção: o caminho base das APIs corporativas muda conforme o ambiente (empregadoapi-d/, empregadoapi-h/, empregadoapi-p/), então esse valor deve ser configurável por estágio de publicação.

Se a sua solução precisar consumir outra API corporativa, além dessas, o procedimento é o mesmo do passo 2.

9. Sou obrigado a organizar minha solução em módulos?

Não. A modularização é um recurso disponível, não uma exigência: o boilerplate funciona normalmente com o domínio escrito diretamente no host, como antes. A lista de módulos registrada (ModuleRegistry.Modulos) nasce vazia.

Os módulos passam a valer a pena quando a solução tem domínios de negócio distintos que precisam evoluir com autonomia — cada um com seu schema, suas permissões, seu menu e suas telas — ou quando você quer garantir que o código de domínio não se misture à plataforma, para facilitar a sincronização com a base. Veja a seção Modularização.

10. Como mantenho a minha solução sincronizada com as atualizações do boilerplate?

A sincronização é feita por merge manual do upstream/main do boilerplate no repositório da sua solução. Para que esse merge seja previsível, a regra é manter as alterações do seu projeto restritas ao domínio da sua solução (os módulos e o seu assembly de contratos) e, sobre os arquivos da base, apenas aos pontos de edição previstos.

A lista taxativa desses pontos de edição está documentada na seção Modularização.