Subcontextos

O que são Subcontextos?

Subcontextos são dimensões adicionais de contexto além de entidade, sistema e database. Eles permitem criar estruturas organizacionais específicas do seu sistema, como:

• Estabelecimentos
• Anos letivos
• Unidades administrativas
• Departamentos
• Filiais

Com subcontextos, você pode ter permissões diferentes para o mesmo usuário em diferentes unidades organizacionais.

Quando usar?

Use subcontextos quando seu sistema precisar de:

• Controle de acesso por unidade/estabelecimento
• Permissões diferentes por período (ano letivo, exercício fiscal)
• Segregação de dados por departamento ou filial
• Qualquer dimensão adicional além de database/entity

Configuração

1. Implementar o Endpoint

Seu sistema deve expor um endpoint que retorne a lista de subcontextos disponíveis para o contexto atual.

Formato da resposta:

[
  {
    "id": "estabelecimento",
    "name": "Estabelecimento de ensino",
    "articleGender": "MASCULINO",
    "insulation": true,
    "order": 1,
    "options": [
      { "id": 0,   "name": "Secretaria", "hidden": true },
      { "id": 123, "name": "Escola" }
    ]
  },
  {
    "id": "anoletivo",
    "order": 2,
    "name": "Ano letivo",
    "articleGender": "MASCULINO",
    "insulation": false,
    "options": [
      { "id": 2022, "name": "2022" },
      { "id": 2023, "name": "2023" }
    ]
  }
]

Campo	Tipo	Descrição
id	String	Identificador único do subcontexto
description	String	Nome para exibição no Gerenciador de Acessos

Campos da Estrutura de Subcontexto

Abaixo, detalhamos o propósito de cada campo do objeto retornado pelo endpoint:

Campo	Tipo	Obrigatório	Descrição
id	String	Sim	Identificador único do subcontexto. Exemplo: "estabelecimento", "anoletivo". Usado internamente para referência e integrações.
name	Object	Sim	Nome exibido do subcontexto para o usuário, fornecido em forma de objeto com singular e plural.
articleGender	String	Sim	Gênero gramatical do nome, para uso em mensagens e telas. Aceita "MASCULINO" ou "FEMININO".
insulation	Boolean	Não	Indica se o subcontexto isola acessos e permissões. Se true, cada opção é tratada como um contexto totalmente separado no gerenciador de acessos. Opcional, default é false.
order	Integer	Sim	Ordem de exibição ou processamento do subcontexto. Determina a sequência no fluxo de seleção/interface.
options	Array[Object]	Sim	Lista de opções disponíveis para esse subcontexto (veja estrutura abaixo).

Caso sua aplicação já utilize subcontextos, garanta que o campo id na resposta mantenha exatamente o mesmo valor da chave configurada atualmente. {.is-warning}

Estrutura de cada option

Campo	Tipo	Obrigatório	Descrição
id	String/Int	Sim	Identificador único da opção (pode ser numérico ou texto).
name	String	Sim	Nome exibido da opção.

Como implementar o endpoint de subcontextos?

O endpoint pode ser implementado em qualquer linguagem/framework, desde que atenda as seguintes regras:

1. Rota:
   Defina uma rota REST (ex: GET /api/subcontextos) que retorne a lista dos subcontextos no formato acima, filtrados de acordo com o contexto (entidade + database) se necessário. Deve permitir o escopo suite.services.

2. Retorno:
   Sempre retorne um array de subcontextos, cada um com seus campos obrigatórios e a lista de opções.

3. Campos obrigatórios:
   Todos os campos descritos acima devem ser preenchidos, inclusive as opções.

Limites

O sistema possui os seguintes requisitos para o endpoint de subcontextos:

Requisito	Valor
Tempo de resposta	2000ms
Escopo obrigatório	suite.services

O endpoint deve responder em no máximo 2 segundos. Respostas acima desse tempo podem resultar em erro ou timeout na integração.

2. Configurar no Studio Aplicações

1. Acesse o Studio Aplicações
2. Navegue até Configurações do projeto
3. Localize a seção de Subcontextos
4. Configure a URL do endpoint

Integração com Page Mapping

No Page Mapping, inclua o nome do subcontexto no array contexts:

{
  "contexts": ["database", "subcontexto", "entity"],
  "constraints": [...]
}

Isso permite criar Page Mappings específicos para cada subcontexto, com permissões diferentes por unidade organizacional.

URL do Gerenciador de Acessos

Para sistemas com subcontextos, a URL de redirecionamento ao Gerenciador de Acessos segue o formato:

https://{host}/#/entidades/{contexto}/sistemas/{id_sistema}/subcontextos/{id_subcontexto}

Onde:

• {contexto} = Base64 de database:{id_database},entity:{id_entity}
• {id_subcontexto} = Base64 do JSON do subcontexto (ex: {"unidade":"123"})

Exemplo:

https://gerenciador-autorizacoes.plataforma.betha.cloud/#/entidades/ZGF0YWJhc2U6MTk5LGVudGl0eTo1NzU=/sistemas/158/subcontextos/eyJ1bmlkYWRlIjoiMTIzIn0=

Ambientes disponíveis:

Ambiente	URL
Produção	https://gerenciador-autorizacoes.plataforma.betha.cloud
Teste	https://gerenciador-autorizacoes.test.plataforma.betha.cloud

Exemplo Completo

1. Endpoint de Subcontextos

@GetMapping("/api/subcontextos")
public Response<List<Subcontexto>> listarSubcontextos() {
    // Retorna subcontextos do contexto atual
    return Response.ok(subcontextoService.listarPorContexto());
}

2. Page Mapping com Subcontexto

[
  {
    "contexts": ["database", "unidade", "entity"],
    "constraints": [
      {
        "id": "AtendimentoPage",
        "description": "Atendimento",
        "resources": [
          {
            "accessControll": null,
            "urlPattern": "/api/atendimentos/.*",
            "methods": ["GET"]
          },
          {
            "accessControll": "create",
            "urlPattern": "/api/atendimentos",
            "methods": ["POST"]
          }
        ],
        "accessControll": [
          { "id": "create", "description": "Criar atendimento" }
        ]
      }
    ],
    "groups": [
      {
        "id": "operacoes",
        "description": "Operações",
        "constraints": ["AtendimentoPage"]
      }
    ]
  }
]

3. Redirecionamento ao Gerenciador

function abrirGerenciadorAcessos() {
  const host = window.___bth.envs.suite['autorizacoes-ui'].standalone.host;
  const contexto = btoa(`database:${databaseId},entity:${entityId}`);
  const subcontexto = btoa(JSON.stringify({ unidade: unidadeId }));

  window.open(
    `${host}/#/entidades/${contexto}/sistemas/${sistemaId}/subcontextos/${subcontexto}`
  );
}