[space] CITSmart X

[title] Orçamento e controle orçamentário
[path] Aplicações/ERP/Manual do Usuário/

# Introdução

***

O módulo de **Orçamento** existe para responder duas perguntas o ano todo: "quanto foi planejado gastar?" e "quanto já foi comprometido e realizado contra esse plano?". Você começa criando um **orçamento** (por exercício e por natureza — custeio ou investimento), lança as **linhas** que dizem quanto pode ser gasto em cada dimensão (das doze disponíveis — de centro de custo e projeto a cliente, vendedor, região e rota) e em cada período (do diário ao plurianual), e define a **política de controle** de cada linha: apenas alertar, bloquear o estouro, ou exigir uma liberação por alçada quando o gasto ultrapassa o previsto. Depois de **aprovado**, o orçamento passa a ser consultado pelo **controle orçamentário**, que confronta planejado × comprometido × realizado e mostra o saldo disponível de cada linha.

A partir daí o ciclo é de acompanhamento e ajuste: quando um gasto encosta no teto, o sistema **alerta**; quando o ultrapassa numa linha de política "aprovar acima", abre uma **liberação** para quem tem privilégio; e quando o plano precisa mudar de verdade, você registra uma **revisão** — suplementação (mais verba), transferência (de uma linha para outra) ou antecipação (puxar verba de período futuro) — sujeita a aprovação por **alçada**. Todo o previsto × realizado fica visível em painéis, e cada alteração do orçamento fica gravada no **histórico**, dando o versionamento auditável do plano. Você usa este módulo sempre que precisa disciplinar o gasto contra um teto planejado e comprovar, depois, que ele foi respeitado.

:::BlockQuote
**Onde fica no menu.** As telas de orçamento ficam no grupo **Custos** da barra lateral: **Orçamentos**, **Controle orçamentário**, **Liberações acima do orçamento**, **Revisões orçamentárias** e **Orçado × Real**. As **Alçadas de orçamento** ficam no grupo **Administração**, e há ainda um painel **Orçado vs. realizado** no grupo Financeiro, que compara por ano/mês. Várias dessas telas exigem o privilégio **Gerir orçamento** (MANAGE\_BUDGET).
:::

## Passo a passo

***

### Criar um orçamento

1. **Abra "Orçamentos".** Menu **Custos → Orçamentos**. A lista mostra os orçamentos existentes com o **exercício**, a **natureza** (Custeio/Investimento) e a **situação** (Rascunho, Aprovado, Encerrado). Um filtro no topo permite ver só os de uma natureza.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/111-budgets.png" alt caption width="3200" height="2000"}
2. **Novo orçamento.** Clique em **"Novo orçamento"** e preencha o cabeçalho:
   - **Nome** — como o orçamento será identificado (ex.: "Custeio 2026").
   - **Exercício** — o ano de referência.
   - **Natureza** — **Custeio (OPEX)** para despesa corrente ou **Investimento (CAPEX)** para orçamento de investimentos.
   - **Alerta perto do limite (%)** — a folga (em percentual) a partir da qual a linha entra em estado de alerta; é o critério que dispara o aviso de "perto do limite".O aviso sai **no momento do lançamento que cruza esse limiar** — não no dia seguinte. E sai **uma vez**, no cruzamento: os gastos seguintes, já acima do limiar, não repetem a mensagem, porque um alerta repetido a cada lançamento é um alerta que se aprende a ignorar. Há ainda uma varredura diária que pega o caso em que a linha cruza o limiar **sem gasto nenhum** — por exemplo, quando uma revisão baixa o valor planejado.
   - **Observações** — texto livre (opcional).
3. **Salve.** O orçamento nasce com situação Rascunho e abre a ficha de edição, onde você lança as linhas.

### Lançar as linhas do orçamento

1. **Na ficha do orçamento, vá à seção "Linhas".** Enquanto o orçamento está em Rascunho as linhas são editáveis. Clique em **"+ Adicionar linha"** para cada verba planejada.
2. **Preencha cada linha:**
   - **Dimensão** — o tipo do "de onde/para quê" da verba. São doze: **Centro de custo**, **Natureza**, **Projeto**, **Departamento**, **Contrato**, **Estabelecimento**, **Conta contábil**, **Cliente**, **Vendedor**, **Perfil de cliente**, **Região** e **Rota**. Depois escolha o registro específico daquela dimensão no seletor ao lado. É assim que você cria, por exemplo, um **orçamento por projeto** (dimensão Projeto), por contrato, ou uma **meta de venda por vendedor** (dimensão Vendedor).Duas dimensões cobram o **papel** do parceiro, não só a existência dele: em **Cliente** o seletor só oferece parceiros com papel de cliente, e em **Vendedor** só os que têm papel de vendedor — informar um fornecedor numa linha de Cliente é recusado ao salvar. Já **Região**, **Rota** e **Perfil de cliente** são referências livres: o seletor oferece os registros reais, mas o sistema não confere o vínculo.
   - **Período** — a granularidade da verba: **Diário**, **Semanal**, **Mensal**, **Bimestral**, **Trimestral**, **Semestral**, **Anual** ou **Plurianual**.
   - **Início** e **Fim** — as datas que delimitam o período daquela linha.
   - **Planejado** — o valor previsto para essa dimensão nesse período.
   - **Política** — o que o sistema faz quando o gasto encosta ou passa do planejado: **Alertar** (só avisa), **Bloquear** (impede o estouro) ou **Aprovar acima** (abre uma liberação por alçada).
3. **Salve as linhas.** Use **"Salvar"** ao pé da seção. Uma linha sem dimensão ou sem período é ignorada ao salvar.

### Facilitadores de lançamento (opcional)

1. **Use as "Operações em massa".** Ainda com o orçamento em Rascunho, a barra de facilitadores acima das linhas oferece três atalhos para montar o orçamento sem digitar tudo à mão\:Cada operação abre um painel com o campo correspondente e os botões **"Confirmar"** / **"Cancelar"**; ao confirmar, as linhas são atualizadas na hora.
   - **Copiar de outro orçamento** — traz as linhas de um orçamento existente e **desloca o período** por um número de meses que você informa (útil para partir do orçamento do ano anterior).
   - **Reajustar por fator** — multiplica todos os valores planejados por um fator (ex.: 1.05 para +5%, 0.97 para -3%).
   - **Arredondar para múltiplo** — arredonda cada valor planejado para o múltiplo mais próximo que você indicar (ex.: 100).

### Aprovar e versionar o orçamento

1. **Aprove o orçamento.** Na lista de orçamentos, use o botão **"Aprovar"** na linha do orçamento em Rascunho (ou aprove pela ficha). A situação passa a Aprovado — só orçamentos aprovados aparecem no controle orçamentário e podem receber revisões. Um orçamento aprovado pode depois ser **"Encerrado"** (situação Encerrado).
2. **Consulte o histórico de alterações.** No fim da ficha do orçamento, o card **"Histórico de alterações"** lista cada mudança (ação, autor e data). Clique em um evento para abrir o detalhe com o comparativo antes/depois. É esse registro que dá o **versionamento auditável** do orçamento ao longo do tempo.

### Configurar as alçadas de aprovação

1. **Abra "Alçadas de orçamento".** Menu **Administração → Alçadas de orçamento**. Aqui você cadastra as faixas de valor que roteiam as aprovações orçamentárias para o cargo/perfil certo.
2. **Nova alçada.** Clique em **"Nova alçada"** e informe o **nível**, o **valor mínimo** e o **valor máximo** da faixa, o **privilégio exigido** para aprovar dentro dela e, opcionalmente, o **centro de custo** ao qual a faixa se aplica. Faixas diferentes permitem níveis de aprovação distintos conforme o valor envolvido.

### Acompanhar o controle orçamentário

1. **Abra "Controle orçamentário".** Menu **Custos → Controle orçamentário**. Escolha um **orçamento aprovado** no seletor.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/112-budget-control.png" alt caption width="3200" height="2000"}
2. **Leia o quadro por linha.** Para cada linha, o sistema mostra **Planejado**, **Comprometido**, **Realizado**, **Disponível** e a **política**. É o comparativo previsto × comprometido × realizado que sinaliza, a cada movimento, o nível de comprometimento da verba.
3.

**Quem pode lançar.** Desde 2026-08-02, registrar e reclassificar consumo pertencem a quem **administra o orçamento** — o mesmo cargo que mantém os orçamentos e as linhas. Se você acompanha o orçamento mas não o administra, o painel mostra os lançamentos em modo leitura e os botões não aparecem; isso é o comportamento correto, não uma falha de carregamento. Peça ao administrador do orçamento para lançar, ou peça a permissão ao administrador do sistema.

**Histórico do empenho.** Cada lançamento tem um botão **Histórico** que mostra quem lançou, quem reclassificou e quem anulou, com o antes e o depois. Ele fica disponível **também para quem só acompanha** o orçamento — é justamente o auditor que precisa da trilha. A anulação é o caso que mais importa: ela **apaga** a linha do empenho, então o evento passa a ser o único lugar que ainda diz quanto era, contra qual dotação e por quem.

**Registre um consumo.** Clique em **"Consumo"** na linha para abrir o painel e use **"Registrar consumo"** informando o **tipo** (**Comprometido** ou **Realizado**) e o **valor**. O saldo disponível da linha é recalculado. Quando um lançamento ultrapassa o planejado, ele recebe o selo **"Acima do orçado"**.

1. **Reclassifique um lançamento.** No painel de consumo, cada lançamento traz um seletor **"Mover para…"** com as outras linhas do mesmo orçamento e a ação **"Reclassificar"**. Ao mover o consumo para outra linha, os saldos das duas linhas são atualizados — a nova classificação passa a influenciar o resultado do controle orçamentário. Reclassificar é remanejo de dotação, então o seletor e o botão só aparecem para quem administra o orçamento (ver o aviso do passo 14).

### Liberar gastos acima do orçamento

1. **Abra "Liberações acima do orçamento".** Menu **Custos → Liberações acima do orçamento**. Quando uma linha com política **"Aprovar acima"** é consumida além do planejado, o sistema abre aqui uma **solicitação de liberação**. Um filtro permite ver só as **Pendentes** ou **Todas**.
2. **Aprove ou rejeite.** Cada solicitação mostra o **Planejado**, o **Consumido**, o valor do **gasto**, a **situação** e quem decidiu. Nas pendentes, use **"Aprovar"** ou **"Rejeitar"**. A decisão fica registrada com o autor e a data.

### Revisar o orçamento: suplementação, transferência e antecipação

1. **Abra "Revisões orçamentárias".** Menu **Custos → Revisões orçamentárias**. É por aqui que o plano é alterado formalmente, depois de aprovado.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/113-budget-revisions.png" alt caption width="3200" height="2000"}
2. **Crie uma revisão.** No card **"Nova revisão"**, escolha o **orçamento** (apenas aprovados aparecem) e o **tipo**:Informe o **valor** e clique em **"Salvar"**. A revisão entra como Pendente.
   - **Suplementação** — acrescenta verba a uma linha (informe a **linha destino** e o **valor**).
   - **Transferência** — move verba de uma **linha origem** para uma **linha destino** (de uma natureza/centro/projeto para outro), sem alterar o total.
   - **Antecipação** — puxa verba de uma **linha origem de período futuro** para a linha destino.
3. **Aprove ou rejeite a revisão.** Na lista de revisões, as pendentes trazem os botões **"Aprovar"** e **"Rejeitar"** (sujeitos à alçada configurada). Use **"Ver snapshot"** para inspecionar o retrato do orçamento associado àquela revisão. Aprovar aplica a mudança às linhas; rejeitar mantém o orçamento como estava.

### Acompanhar o orçamento de investimento (CAPEX)

Num orçamento de natureza **Investimento**, cada linha pode ter um **cronograma de aportes**: quanto se pretende desembolsar em cada competência e qual bem aquele aporte financia.

1. **Abra o cronograma de aportes.** Na ficha do orçamento, na linha desejada, use a ação que abre o painel **"Cronograma de aportes"**. Ele mostra o **Planejado** da linha, o **Agendado** (soma dos aportes) e a **Diferença**, com um selo indicando se o cronograma está **Conforme o plano** ou **Divergente**.
2. **Registre um aporte.** Informe a **Competência** (o período contábil do desembolso), o **Valor** e, opcionalmente, a **Referência do bem** — o número do tombo que aquele aporte financia. Clique em **Adicionar aporte**.
3. **Confira o que o investimento virou em patrimônio.** Acima da lista, o painel mostra **Incorporado como bens** e **Depreciado até agora** — os valores buscados no cadastro de patrimônio a partir dos tombos citados. E cada aporte que cita um tombo ganha um selo:**Aporte sem referência não é apontado.** Agendar o aporte antes de o bem existir é a ordem normal do processo — a referência se preenche depois da incorporação.
   - **Bem localizado** — o tombo existe e está ativo; ao lado aparecem a descrição do bem, o valor de incorporação e a depreciação acumulada.
   - **Bem baixado** — o tombo existe mas já foi dado baixa. Um investimento que financiou um bem já baixado é um achado, não um detalhe.
   - **Bem não encontrado** — o tombo citado não existe no cadastro. O painel também conta esses casos em **"Aportes que citam um bem inexistente"**.

### Acompanhar previsto × realizado

1. **Abra "Orçado × Real".** Menu **Custos → Orçado × Real**. Escolha um orçamento no seletor para ver o **Painel Orçado × Realizado**: os totais de **Planejado**, **Comprometido**, **Realizado** e **Disponível**, uma barra de **uso do orçamento** (verde/âmbar/vermelho conforme o percentual consumido) e a saúde das linhas — **total de linhas**, **linhas estouradas** e **linhas em alerta**. As linhas em alerta são as que atingiram o percentual de folga definido no cadastro do orçamento.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/116-budget-vs-actual.png" alt caption width="3200" height="2000"}
2. **Compare por ano e mês (visão financeira).** Menu **Financeiro → Orçado vs. realizado**. Escolha o **ano** e, opcionalmente, o **mês** (ou "Ano todo") para ver **Orçado**, **Realizado**, **Variação (R$)** e **Variação (%)**, além do detalhamento por período, centro de custo e natureza. A variação positiva indica gasto abaixo do orçado (favorável).

## Verificação

***

Você sabe que funcionou quando:

- Ao salvar um orçamento novo, ele aparece na lista **Orçamentos** com situação Rascunho e a natureza escolhida (Custeio ou Investimento).
- Depois de lançar linhas e clicar em **"Salvar"**, as linhas permanecem ao reabrir a ficha, com dimensão, período, valor planejado e política preservados.
- Ao **aprovar** o orçamento, a situação vira Aprovado e ele passa a aparecer no seletor de **Controle orçamentário** e de **Revisões orçamentárias**.
- No **Controle orçamentário**, ao registrar um consumo, o **Disponível** da linha diminui; um consumo acima do planejado ganha o selo **"Acima do orçado"**.
- Uma linha com política **"Aprovar acima"** consumida além do teto gera uma solicitação na tela **Liberações acima do orçamento**.
- Uma **revisão** de suplementação/transferência/antecipação entra como Pendente e, ao aprovar, altera os saldos das linhas afetadas.
- O card **"Histórico de alterações"** do orçamento registra cada mudança com autor e data, e o detalhe abre o antes/depois.
- Os painéis **Orçado × Real** e **Orçado vs. realizado** refletem os valores planejados e consumidos, com as linhas estouradas e em alerta destacadas.

## Erros comuns

***

- **Tentar editar linhas de um orçamento já aprovado.** As linhas só são editáveis em Rascunho. Depois de aprovado, mudanças passam por **Revisões orçamentárias**, não pela edição direta das linhas.
- **Orçamento não aparece no controle ou nas revisões.** Essas telas listam apenas orçamentos com situação Aprovado. Um orçamento em Rascunho precisa ser aprovado antes.
- **Salvar linha sem dimensão ou sem datas.** Linhas sem o registro da dimensão ou sem início/fim são descartadas ao salvar — confira que cada linha tem dimensão, período, datas e valor.
- **Esperar bloqueio automático numa linha "Alertar".** Só a política **"Bloquear"** impede o estouro; **"Alertar"** apenas sinaliza e **"Aprovar acima"** encaminha a liberação. Escolha a política conforme o rigor desejado.
- **Não encontrar as telas de orçamento no menu.** Elas ficam no grupo **Custos** (e as alçadas em **Administração**). Sem o privilégio **Gerir orçamento**, itens como Liberações, Revisões e Alçadas não aparecem.
- **Confundir os dois painéis.** **Orçado × Real** (grupo Custos) consolida um orçamento específico; **Orçado vs. realizado** (grupo Financeiro) compara por ano/mês, centro de custo e natureza. São visões complementares.

[title] Glossário
[path] Aplicações/ERP/Manual do Usuário/

# Glossário

***

Termos canônicos do ERP em linguagem de operador. Cada entrada cita o nome usado nas telas do portal (bate com o bundle pt\_BR.ts), um sinônimo coloquial quando existe, definição curta, exemplo concreto e cross-link para as seções do manual onde o termo aparece primeiro.

Ordem alfabética.

## Alçada

***

**Sinônimos:** limite de aprovação, teto de autorização.

Regra que define até que valor um usuário pode aprovar (ou liberar para próxima etapa) uma operação sensível. No ERP, cada combinação de papel × tipo de operação pode ter um teto em reais; acima dele, o documento precisa subir para um nível superior. A **dimensão de centro varia por operação** (ADR 0022): "Aprovar requisição" pode ser escopada por **Centro de Custo**; crédito e venda usam só faixa de valor (sem centro); o orçamento tem alçada por Centro de Custo. Operação sem nenhuma regra é liberada (padrão ADR 0010).

**Exemplo:** o operador analista\_financeiro tem alçada de R$ 10.000,00 para APROVAR\_DOCUMENTO; uma conta a pagar de R$ 12.500,00 fica retida até o gerente\_financeiro aprovar.

**Veja também:** [Administração.](docId\:Z8SS7r6Bvhs09rP1SPxUD)

## Almoxarifado

***

**Sinônimos:** depósito, warehouse.

Local físico onde o estoque é guardado. Cada movimento de estoque (entrada, saída, transferência) acontece em um almoxarifado, e cada almoxarifado pertence a um estabelecimento (matriz ou filial).

**Exemplo:** "Almoxarifado Central — Matriz SP" recebe mercadorias compradas; "Almoxarifado Loja 02 — Filial RJ" guarda estoque para venda local.

**Veja também:** [Estoque](docId\:CVozhYtoHDtuWZyT-bnAT).

## Bin (endereço de estoque)

***

**Sinônimos:** posição, localização, endereço.

Subdivisão dentro do almoxarifado que identifica a posição exata onde um item está guardado (rua/prateleira/nível). Permite localizar a mercadoria rapidamente em armazéns maiores.

**Exemplo:** A-03-02 = rua A, prateleira 03, nível 02.

**Veja também:** [Estoque](docId\:CVozhYtoHDtuWZyT-bnAT).

## Boleto

***

**Sinônimos:** bloqueto, cobrança bancária.

Documento de cobrança bancário com código de barras e linha digitável que o cliente pode pagar em qualquer banco. No ERP, é gerado a partir de uma conta a receber via integração com o banco do estabelecimento.

**Exemplo:** conta a receber da NF-e 1234 vira boleto vencendo em 30 dias, com linha digitável 34191.79001 01043.510047 91020.150008 4 89090000125000.

**Veja também:** [Financeiro — títulos (contas a pagar e a receber)](docId\:D4kuGidayU2GQ-hMhF_T-), [Tesouraria](docId:75tXS8u8o-8q4dR2arnmw).

## Centro de custo

***

**Sinônimos:** CC, departamento de gasto.

Categoria que agrupa gastos com finalidade analítica — saber **onde** o dinheiro está sendo consumido. Diferente de centro de resultado, não vincula receita; serve para apropriar despesas e calcular custo de departamento/projeto.

**Exemplo:** "TI — Infraestrutura" recebe rateio mensal de aluguel proporcional à área ocupada.

**Veja também:** [Financeiro — cadastros de apoio](docId\:yTzjjyyML1B_60VgwDT09), [Custos e orçamento](docId\:C_44BngrBZM27TiNbovzP).

## Centro de resultado

***

**Sinônimos:** CR, unidade de negócio.

Unidade organizacional que **gera receita e absorve despesa** — produz lucro/prejuízo próprio. Usado em alçadas (APROVAR\_DOCUMENTO por CR) e relatórios gerenciais por linha de negócio.

**Exemplo:** "Loja 02 — RJ" é um CR; suas vendas, custos diretos e despesas alocadas formam o resultado da loja.

**Veja também:** [Financeiro — cadastros de apoio](docId\:yTzjjyyML1B_60VgwDT09), [Administração](docId\:Z8SS7r6Bvhs09rP1SPxUD).

## CFOP (Código Fiscal de Operações e Prestações)

***

**Sinônimos:** CFOP.

Código de 4 dígitos que classifica a natureza fiscal de cada item em um documento — se é venda, devolução, transferência, dentro ou fora do estado etc. Determina como o imposto é calculado.

**Exemplo:** 5102 = venda de mercadoria dentro do estado; 6102 = venda fora do estado.

**Veja também:** [Fiscal — saída](docId\:jBJoVopyjL5-zOKm6FGbZ).

## Classificação tributária

***

**Sinônimos:** código de classificação tributária (eSocial).

Código de 2 dígitos que identifica o regime tributário e a categoria fiscal da empresa segundo a tabela 8 do eSocial. Influencia obrigações acessórias (Reinf, DCTFWeb).

**Exemplo:** 99 = Pessoa jurídica em geral; 1 = Empresa enquadrada como Simples Nacional.

**Veja também:** [Cadastro fiscal próprio](docId\:Q-zx6Qk4pMFD09yrhmsve).

## CNAB

***

**Sinônimos:** arquivo CNAB, remessa/retorno bancário.

Formato de arquivo texto padronizado pela FEBRABAN para troca de informações financeiras com bancos (240 ou 400 posições). O ERP gera arquivos de remessa (pagamentos a fazer, boletos a registrar) e processa arquivos de retorno (extrato, baixas).

**Exemplo:** CNAB 240 de remessa Itaú enviado dia 1, retorno processado dia 2 com confirmação de 17 boletos registrados.

**Veja também:** [Tesouraria](docId:75tXS8u8o-8q4dR2arnmw).

## CNAE (Classificação Nacional de Atividades Econômicas)

***

**Sinônimos:** código CNAE, atividade econômica.

Código de 7 dígitos que identifica a atividade econômica principal e secundárias de um estabelecimento. Cadastrado por estabelecimento (não por empresa).

**Exemplo:** 6201501 = Desenvolvimento de programas de computador sob encomenda.

**Veja também:** [Cadastro fiscal próprio](docId\:Q-zx6Qk4pMFD09yrhmsve).

## CNPJ

***

**Sinônimos:** Cadastro Nacional da Pessoa Jurídica.

Identificador de 14 dígitos da pessoa jurídica perante a Receita Federal. Os 8 primeiros formam a raiz (empresa); os 4 seguintes identificam a filial (0001 = matriz); os 2 últimos são dígitos verificadores.

**Exemplo:** 11.222.333/0001-81 — raiz 11222333, filial 0001 (matriz), DV 81.

**Veja também:** [Cadastro fiscal próprio](docId\:Q-zx6Qk4pMFD09yrhmsve).

## CPF

***

**Sinônimos:** Cadastro de Pessoa Física.

Identificador de 11 dígitos da pessoa física perante a Receita Federal. Usado em cadastros de parceiros pessoa física (clientes/fornecedores PF, responsável legal de PJ).

**Exemplo:** 296.936.410-78.

**Veja também:** [Cadastros gerais (parceiros e produtos)](docId:6xpQsdWQ2NTyI40BFqDS-).

## CRT (Código de Regime Tributário)

***

**Sinônimos:** regime tributário.

Código de 1 dígito que indica o regime fiscal da empresa para fins de NF-e. Define como CSTs e tributos serão calculados.

**Exemplo:** 1 = Simples Nacional; 2 = Simples Nacional - excesso de sublimite; 3 = Regime Normal (Lucro Presumido ou Real); 4 = MEI.

**Veja também:** [Cadastro fiscal próprio](docId\:Q-zx6Qk4pMFD09yrhmsve).

## CSC (Código de Segurança do Contribuinte)

***

**Sinônimos:** token NFC-e, idCSC.

Chave secreta que a SEFAZ entrega ao contribuinte para autenticar emissões de NFC-e. É cadastrada por estabelecimento e por UF (em estados onde se opera NFC-e), e fica armazenada cifrada no ERP (write-only — após criação, o token não retorna em consultas).

**Exemplo:** par (SP, 000001, TOKEN-DEMO-123) registrado uma vez; depois disso só aparece como referência, nunca como texto.

**Veja também:** [Cadastro fiscal próprio](docId\:Q-zx6Qk4pMFD09yrhmsve), [Fiscal — saída](docId\:jBJoVopyjL5-zOKm6FGbZ).

## DARF

***

**Sinônimos:** guia federal, DARF Simples, DARF comum.

Documento de Arrecadação de Receitas Federais — guia em PDF usada para pagar tributos federais (IRPJ, CSLL, PIS, Cofins, INSS de PJ etc.). Gerada pelo ERP com código de receita, período de apuração, valor principal, juros, multa e código de barras.

**Exemplo:** DARF código 2089 para PIS/Cofins mensal vencendo dia 25.

**Veja também:** [Financeiro — títulos (contas a pagar e a receber)](docId\:D4kuGidayU2GQ-hMhF_T-).

## DCTFWeb

***

**Sinônimos:** Declaração de Débitos e Créditos Tributários Federais Web.

Obrigação acessória mensal que reúne tributos federais a pagar (apurados via Reinf + folha + outros). O ERP gera o XML/JSON e o PDF da declaração por estabelecimento + período, e cria as DARFs vinculadas.

**Exemplo:** DCTFWeb de maio/2026 da matriz reúne INSS patronal + retenção PIS/Cofins/CSLL + IRRF.

**Veja também:** [Cadastro fiscal próprio](docId\:Q-zx6Qk4pMFD09yrhmsve).

## DPS (Declaração de Prestação de Serviço)

***

**Sinônimos:** XML da NFS-e, evento DPS.

XML padronizado que precede a NFS-e Padrão Nacional. O prestador envia o DPS para o ADN (Ambiente de Dados Nacional); o município processa e responde com a NFS-e emitida (ou rejeição). Modelo nacional substituindo gradualmente os \~5.500 padrões municipais.

**Exemplo:** DPS contendo prestador 11222333000181, tomador, serviço LC 116, valor e ISS calculado.

**Veja também:** [Fiscal — saída](docId\:jBJoVopyjL5-zOKm6FGbZ).

## Encontro de contas

***

**Sinônimos:** compensação, netting.

Operação que compensa uma conta a pagar e uma conta a receber de **mesmo parceiro** (que é simultaneamente cliente e fornecedor), reduzindo o caixa movimentado. O ERP gera um lançamento contábil de baixa cruzada.

**Exemplo:** ACME Servicos Ltda tem R$ 3.000,00 a pagar e R$ 5.000,00 a receber; após encontro, fica só R$ 2.000,00 a receber em aberto.

**Veja também:** [Tesouraria](docId:75tXS8u8o-8q4dR2arnmw).

## Estabelecimento

***

**Sinônimos:** filial, unidade, branch.

Cada CNPJ completo (14 dígitos) cadastrado dentro de uma empresa. A primeira filial (terminada em 0001) é a matriz; as demais são filiais. Quase todo movimento operacional do ERP (NF-e, almoxarifado, conta bancária, lançamento contábil) é vinculado a um estabelecimento.

**Exemplo:** ACME tem 2 estabelecimentos: matriz 11222333000181 (SP) e filial 11222333000262 (RJ).

**Veja também:** [Cadastro fiscal próprio](docId\:Q-zx6Qk4pMFD09yrhmsve).

## Empresa (LegalEntity)

***

**Sinônimos:** pessoa jurídica, matriz fiscal.

Pessoa jurídica raiz identificada pelos 8 primeiros dígitos do CNPJ. Agrupa todos os estabelecimentos com a mesma raiz. É o nível onde se cadastra razão social, CRT, natureza jurídica e responsável legal.

**Exemplo:** ACME Servicos Ltda — raiz 11222333 — agrupa matriz 0001 e filial 0002.

**Veja também:** [Cadastro fiscal próprio](docId\:Q-zx6Qk4pMFD09yrhmsve).

## GARE

***

**Sinônimos:** GARE-ICMS, guia estadual SP.

Guia de Arrecadação Estadual da Receita — documento em PDF para pagamento de tributos estaduais paulistas (ICMS-ST, ICMS-DIFAL, IPVA etc.). Gerada por estabelecimento + período.

**Exemplo:** GARE de ICMS-ST de maio/2026 da matriz SP, vencimento dia 10 do mês seguinte.

**Veja também:** [Financeiro — títulos (contas a pagar e a receber)](docId\:D4kuGidayU2GQ-hMhF_T-).

## GPS

***

**Sinônimos:** Guia da Previdência Social.

Guia em PDF para pagamento de contribuição previdenciária (INSS patronal, segurados). Hoje em transição para DARF-INSS via DCTFWeb, mas ainda usada em casos residuais.

**Exemplo:** GPS de INSS retido na fonte de prestador de serviço PJ.

**Veja também:** [Financeiro — títulos (contas a pagar e a receber)](docId\:D4kuGidayU2GQ-hMhF_T-).

## IEST (Inscrição Estadual de Substituto Tributário)

***

**Sinônimos:** IE-ST.

Inscrição estadual que o estabelecimento mantém em UFs onde recolhe ICMS-ST como substituto. É cadastrada por par (UF, número) no sub-cadastro do estabelecimento.

**Exemplo:** matriz SP com IEST (MG, 12345) para vendas com ST a Minas Gerais.

**Veja também:** [Cadastro fiscal próprio](docId\:Q-zx6Qk4pMFD09yrhmsve).

## Lançamento contábil

***

**Sinônimos:** partida, registro contábil.

Registro de débito e crédito em contas do plano de contas, com data, valor, histórico e referência ao evento que originou (NF-e, baixa de conta, depreciação etc.). Toda operação financeira gera um ou mais lançamentos.

**Exemplo:** baixa de conta a pagar de R$ 1.250,00 gera lançamento Débito Fornecedores 1.250,00 / Crédito Banco 1.250,00.

**Veja também:** [Contabilidade](docId:08cbTyrT0WXBp4ymvrog_).

## NCM (Nomenclatura Comum do Mercosul)

***

**Sinônimos:** código NCM.

Código de 8 dígitos que classifica mercadorias para fins fiscais (IPI, ICMS, II, PIS/Cofins). Cadastrado no produto e replicado em cada item de NF-e.

**Exemplo:** 8471.30.12 = computador portátil; 2202.10.00 = água gaseificada.

**Veja também:** [Cadastros gerais (parceiros e produtos)](docId:6xpQsdWQ2NTyI40BFqDS-), [Fiscal — saída](docId\:jBJoVopyjL5-zOKm6FGbZ).

## Natureza jurídica

***

**Sinônimos:** código IBGE da natureza, CONCLA.

Código de 4 dígitos do IBGE que classifica a forma societária da empresa (LTDA, S.A., EIRELI, MEI etc.). Influencia obrigações fiscais e dados que devem ser preenchidos.

**Exemplo:** 2046 = Sociedade Empresária Limitada; 2305 = Empresário (Individual).

**Veja também:** [Cadastro fiscal próprio](docId\:Q-zx6Qk4pMFD09yrhmsve).

## NF-e (Nota Fiscal Eletrônica)

***

**Sinônimos:** NFe, nota modelo 55, nota fiscal de mercadoria.

Documento fiscal eletrônico para circulação de mercadorias (modelo 55). Emitido por empresa em operação B2B ou B2C de produto físico, autorizado pela SEFAZ estadual. Substitui a antiga nota fiscal de talão.

**Exemplo:** venda de 10 unidades de software-box para outra empresa, NF-e modelo 55 série 1 número 123.

**Veja também:** [Fiscal — saída](docId\:jBJoVopyjL5-zOKm6FGbZ), [Fiscal — entrada](docId:1_QpvYmn6apZ9mqx87Z4K).

## NFC-e (Nota Fiscal do Consumidor Eletrônica)

***

**Sinônimos:** NFCe, nota modelo 65, cupom fiscal eletrônico.

Documento fiscal eletrônico para vendas a consumidor final no PDV (modelo 65). Substituiu o cupom fiscal do ECF. Autenticada via CSC (Código de Segurança do Contribuinte) por estabelecimento × UF. Suporta contingência offline quando a SEFAZ não responde.

**Exemplo:** venda no PDV de um produto a consumidor final, NFC-e modelo 65 número 5678 com QRCode impresso.

**Veja também:** [Fiscal — saída](docId\:jBJoVopyjL5-zOKm6FGbZ), [Extras](docId\:T4kPSRMFPloP-vHVEA9jU).

## NFS-e (Nota Fiscal de Serviço Eletrônica)

***

**Sinônimos:** NFSe, nota de serviço, ISS eletrônica.

Documento fiscal eletrônico para prestação de serviço (sem modelo único histórico — cada município tinha o seu). A partir de 2026 está migrando para o **Padrão Nacional** via ADN (Ambiente de Dados Nacional), iniciado por evento DPS.

**Exemplo:** prestação de serviço de consultoria para outro CNPJ, NFS-e Padrão Nacional emitida a partir de DPS XML enviado ao ADN.

**Veja também:** [Fiscal — saída](docId\:jBJoVopyjL5-zOKm6FGbZ), *DPS*.

## OS (Ordem de Serviço)

***

**Sinônimos:** ordem de trabalho.

Documento interno que controla execução de um serviço (instalação, manutenção, projeto etc.) — vincula cliente, escopo, prazo, custos apropriados e (no fim) faturamento. Usada em empresas de serviço como ponte entre o pedido e a NFS-e.

**Exemplo:** OS 042 — instalação no cliente ACME, 3 dias-homem apropriados, fatura R$ 4.500,00 via NFS-e.

**Veja também:** [Vendas e CRM](docId\:TaINdkXLJcUzyq0xUuGfH), [Custos e orçamento](docId\:C_44BngrBZM27TiNbovzP).

## PIX

***

**Sinônimos:** pagamento instantâneo, transferência PIX.

Sistema de pagamento instantâneo do Banco Central — funciona 24/7. No ERP, chaves PIX são cadastradas por estabelecimento (EMAIL, CPF/CNPJ, TELEFONE, EVP) e usadas em recebimentos (cobrança QR) e pagamentos (transferência direta).

**Exemplo:** estabelecimento matriz com chave PIX EMAIL = fiscal\@acme-exemplo.com cadastrada no Itaú.

**Veja também:** [Cadastro fiscal próprio](docId\:Q-zx6Qk4pMFD09yrhmsve), [Tesouraria](docId:75tXS8u8o-8q4dR2arnmw).

## Plano de contas

***

**Sinônimos:** plano contábil, COA (chart of accounts).

Estrutura hierárquica das contas usadas pela contabilidade (ativo, passivo, receita, despesa). É o "esqueleto" que todo lançamento contábil referencia. O ERP traz um plano seed (\~22 contas) que pode ser customizado.

**Exemplo:** 1.1.1.01 — Caixa, 1.1.2.01 — Banco Itaú c/c, 4.1.1.01 — Receita de Vendas.

**Veja também:** [Financeiro — cadastros de apoio](docId\:yTzjjyyML1B_60VgwDT09), [Contabilidade](docId:08cbTyrT0WXBp4ymvrog_).

## Reinf (EFD-Reinf)

***

**Sinônimos:** Escrituração Fiscal Digital de Retenções e Outras Informações Fiscais.

Obrigação federal mensal/eventual que reporta retenções de tributos federais (PIS/Cofins/CSLL/IRRF) feitas pela empresa em pagamentos a prestadores PJ/PF, comissões etc. O ERP gera o lote por estabelecimento + período e envia ao ambiente da Receita.

**Exemplo:** lote Reinf de maio/2026 da matriz com retenção de R$ 450,00 de PIS/Cofins/CSLL sobre fatura de consultoria PJ.

**Veja também:** [Cadastro fiscal próprio](docId\:Q-zx6Qk4pMFD09yrhmsve).

[title] Por que usar o CITSmart X?
[path] Sobre o CITSmart X/

O Ecossistema <font color="#3b9f0f">**CITSmart X**</font> é ideal para empresas que precisam aumentar a produtividade, reduzir custos, melhorar a qualidade dos serviços e operações, bem como atingir maior satisfação dos clientes.

Para empresas que precisam acelerar a transformação digital, o <font color="#3b9f0f">**CITSmart X** </font>**acelera em até 10x o processo de transformação,** garantindo um ciclo virtuoso de evolução contínua para todo o negócio.&#x20;

O CITSmart X implementa o mecanismo de Optimistic Concurrency Control (OCC) para evitar a sobrescrita de dados quando múltiplas sessões acessam e editam simultaneamente o mesmo registro.

Esse recurso garante que, ao tentar salvar uma alteração, o sistema verifica se o conteúdo foi modificado por outra sessão desde o momento em que foi carregado. Caso o registro tenha sido alterado, o salvamento é bloqueado automaticamente, e o usuário recebe uma mensagem de aviso sobre a atualização concorrente.

Essa abordagem previne a perda não intencional de dados e reforça a integridade das informações, especialmente em ambientes colaborativos com múltiplos usuários atuando em tempo real.

### Benefícios:&#x20;

***Automação de Processos*:** Promove a velocidade, eficiência e precisão do trabalho, reduzindo significativamente a necessidade de intervenção manual.

***Flexível e Escalável*:** A plataforma atende às necessidades de cada organização e pode ser dimensionada de acordo com a demanda.

***Integração*:** Facilita a conexão de diferentes dispositivos e sistemas através de vários componentes de integração e interoperabilidade, possibilitando um gerenciamento unificado e centralizado, bem como evolução e transformação digital sem precedentes.

***Transformação Digital*:&#x20;**&#x50;romove a desburocratização de processos, facilitando a transição para um ambiente digital completo, promovendo inovação, melhorando ROI e elevando os níveis de satisfação dos clientes.

### Acessibilidade Multiplataforma e Compatibilidade Tecnológica&#xA;

O CITSmart foi desenvolvido com foco em acessibilidade e mobilidade, permitindo o acesso completo às suas funcionalidades a partir de desktops, notebooks, tablets e smartphones, com layout responsivo, que se adapta automaticamente ao tipo de dispositivo, tamanho e orientação da tela.&#x20;

A plataforma oferece suporte nativo aos principais navegadores do mercado, incluindo Apple Safari, Mozilla Firefox, Google Chrome e Microsoft Edge, tanto em suas versões desktop quanto mobile. Além disso, sua arquitetura é projetada para manter compatibilidade contínua com as atualizações futuras desses navegadores, garantindo estabilidade, segurança e desempenho consistente.&#x20;

Complementarmente, a solução conta com um aplicativo mobile dedicado, disponível para os sistemas Android e iOS, compatível com as versões mais recentes desses sistemas operacionais. O aplicativo proporciona uma experiência fluida e segura, viabilizando o uso da ferramenta em ambientes de trabalho com alta mobilidade, sem perda de funcionalidade.&#x20;

### Segurança da Informação

A plataforma CITSmart foi projetada com base em princípios de segurança da informação, proteção de dados e conformidade legal, atendendo às melhores práticas internacionais, como os requisitos estabelecidos pela norma ISO/IEC 27001, e às diretrizes da Lei Geral de Proteção de Dados Pessoais (LGPD).

A solução adota políticas e controles que asseguram a confidencialidade, integridade e disponibilidade das informações, além de recursos técnicos e organizacionais que garantem a adesão a padrões e legislações vigentes, promovendo uma operação segura, auditável e em conformidade com as exigências legais aplicáveis.

### Governança de TI

O CITSmart contribui para uma governança eficaz dos serviços de TI, com foco em controle interno, gestão de riscos, integridade das informações e melhoria contínua.

A plataforma incorpora mecanismos que apoiam os objetivos de frameworks como o COSO, incluindo definição de responsabilidades, controle de processos, monitoramento de desempenho e resposta a riscos operacionais. Para isso, disponibiliza recursos nativos, como o módulo de Gestão de Riscos, que permite a identificação, análise, avaliação, tratamento e monitoramento de riscos associados aos serviços e ativos de TI.

Essa estrutura contribui para o alinhamento estratégico, a tomada de decisão baseada em evidências e o fortalecimento dos controles internos, promovendo conformidade e confiança nos resultados entregues.


[title] Jurídico e contencioso
[path] Aplicações/ERP/Manual do Usuário/

## Introdução

***

O módulo **Jurídico** organiza a gestão do contencioso do órgão — os processos judiciais e administrativos em que a entidade é autora ou ré. Cada processo tem uma **ficha** central onde ficam reunidos os dados do caso (número CNJ, matéria, esfera, tribunal, valor da causa), o **histórico de andamentos**, as **partes** envolvidas, os **desdobramentos** (recursos e agravos), os **pedidos e condenações**, os **acordos**, os **prazos** processuais, a **agenda**, e toda a parte financeira: **garantias**, **depósitos judiciais**, **despesas processuais** e a **contingência** (avaliação de risco de perda e a provisão contábil correspondente). A ideia é que quem cuida do jurídico tenha, numa única tela, tudo o que precisa para acompanhar o caso do início ao arquivamento.

Ao redor da ficha, o módulo oferece as visões gerenciais: o **painel do gestor** (prazos, agenda e casos parados da equipe), a lista de **prazos vencidos**, o relatório de **processos parados** (sem movimentação), a **jurimetria** (dashboards com KPIs do contencioso), o **histórico de risco e provisão** (toda alteração de chance de perda e de valor provisionado) e a **conciliação de depósitos** (depósitos × levantamentos × pagamentos). A configuração de **alertas jurídicos** define quando o sistema avisa sobre prazos próximos e casos sem movimento. Tudo isso vive no menu **Jurídico** da barra lateral.

:::BlockQuote
**Quem opera o Jurídico.** As telas de consulta (listas, painel, relatórios) são de leitura aberta. As ações que gravam ou alteram dados do processo — criar caso, mudar situação, arquivar, configurar alertas — exigem a permissão **Gerir processo jurídico**. Se ao salvar aparecer "sem autorização", o seu perfil não tem essa permissão; ela se concede em **Administração** ([Administração](docId\:Z8SS7r6Bvhs09rP1SPxUD)).
:::

## Passo a passo

***

### Abrir um processo

1. **Abra "Processos".** Menu **Jurídico → Processos**. A lista mostra os processos cadastrados com número, matéria, polo do órgão, situação, valor da causa e data de abertura. No topo há duas saídas: **"Exportar planilha"** baixa a relação em planilha, e o seletor **"Exportar dados"** baixa a mesma lista em **Texto (.txt)**, **CSV (.csv)**, **XML (.xml)**, **OpenDocument (.odf)** ou **PDF (.pdf)** .

![](https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/legal-01-cases-list.png)

1. **Novo processo.** Clique em **"Novo processo"** e preencha:
   - **Número do processo** — a numeração CNJ (para processos judiciais) ou o número administrativo. O sistema valida o dígito verificador do CNJ quando o tipo é **Judicial**; um número inválido acusa **"Número CNJ inválido (dígito verificador)"** e trava o botão de criar.
   - **Tipo** — **Judicial** ou **Administrativo**.
   - **Matéria** — Trabalhista, Cível, Tributário ou Administrativo.
   - **Polo do órgão** — se a entidade é **Autor** ou **Réu** no processo.
   - **Esfera** — Municipal, Estadual ou Federal.
   - **Título** — descrição livre do caso (opcional).
   - **Tribunal** — escolha do catálogo (o campo sugere tribunais cadastrados) ou digite.
   - **Valor da causa** — valor monetário (opcional).
2. **Atenção ao alerta de duplicidade.** Ao digitar um número que já existe em outro processo, o sistema mostra, antes de criar, o aviso **"Já existe processo com este número:"** com um link para a ficha existente. O alerta é informativo — não bloqueia —, mas evita cadastrar a mesma ficha duas vezes.
3. **Crie.** Clique em **"Criar processo"**. O sistema abre a ficha do processo recém-criado, já com situação **Ativo**.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/legal-02-case-detail.png" alt caption width="3200" height="2000"}

### Registrar responsáveis e numerações alternativas

1. **Responsáveis.** Na ficha, no card **"Responsáveis"**, associe um ou mais empregados responsáveis pelo processo. O empregado é escolhido de uma lista de valores (funcionários já cadastrados) e entra como responsável pela ficha.
2. **Numerações alternativas.** No card **"Numerações alternativas"**, cadastre outras numerações do mesmo processo além do CNJ (por exemplo, número interno, número do processo administrativo de origem). Informe o **tipo**, o **número** e observações e clique em **"Adicionar numeração"**.

### Definir e alterar a situação do processo

1. **Situação do processo.** Na ficha, além dos selos **Ativo/Arquivado**, há o seletor **"Situação do processo"** (situação de negócio parametrizável, ex.: em andamento, aguardando sentença). Escolha a situação desejada e clique em **"Alterar situação"**. A mudança fica registrada no histórico de alterações do processo.

### Registrar andamentos e comentários (histórico)

1. **Aba "Andamentos".** Na ficha, abra a aba **"Andamentos"**. É aqui que se registra o histórico do processo — o conjunto de andamentos e comentários forma a memória do caso.
2. **Novo andamento.** No formulário do topo da aba, escolha primeiro o **tipo** — *Judicial* ou *Administrativo* — e depois o **subtipo**, que passa a listar apenas os subtipos daquele tipo (em Judicial: petição inicial, sentença, despacho, intimação, audiência…; em Administrativo: reunião, e-mail, solicitação de informações…). O catálogo é parametrizável em **Jurídico → Catálogos**. Informe a **data**, escreva o **comentário** (texto livre) e, se quiser, **anexe documentos já no cadastro** — o arquivo sobe junto com o andamento. Clique em **"Adicionar evento"**. Cada andamento registra automaticamente **quem** o lançou.Trocar o tipo troca a lista de subtipos e reposiciona a seleção num subtipo válido — não é possível gravar um andamento cujo subtipo pertença ao outro tipo.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/legal-03-andamentos.png" alt caption width="3200" height="2000"}
3. **Filtrar o histórico.** Use os seletores **"Filtro"** para restringir os andamentos por **tipo** (Judicial/Administrativo) e por **subtipo** — e aqui vale a mesma hierarquia: escolhido o tipo, o seletor de subtipo passa a oferecer só os subtipos dele, e trocar o tipo limpa o subtipo escolhido. Útil quando a ficha acumula muitos lançamentos.
4. **Documentos do andamento.** Cada andamento permite anexar **documentos** ligados àquele evento (a decisão, a petição, o comprovante), mantendo o arquivo junto do lançamento que ele comprova — tanto no momento do cadastro (passo 9) quanto depois, pelo bloco **"Documentos"** da linha do andamento, de onde também se baixa o arquivo.

### Cadastrar as partes do processo

1. **Aba "Partes".** Abra a aba **"Partes"**. Cadastre as pessoas físicas e jurídicas envolvidas: escolha o **papel** (Autor, Réu, Testemunha, Procurador/Preposto, Juiz, Terceiro), o **tipo de pessoa** (Física/Jurídica), o **nome** e o **documento** (CPF/CNPJ). Clique em **"Adicionar parte"**. As partes cadastradas podem ser **editadas** ou **removidas** depois.

### Acompanhar desdobramentos (recursos e agravos)

1. **Aba "Desdobramentos".** Abra a aba **"Desdobramentos"** para registrar os recursos e agravos do processo. Escolha o **tipo** (Apelação, Agravo, Recurso especial, Extraordinário, Embargos, Outros), a **decisão** (Pendente, Provido, Parcialmente provido, Improvido, Não se aplica), a **data da decisão** e o comentário.
2. **Encadear recursos.** Ao lançar um recurso, é possível apontá-lo como **desdobramento de outro** (campo **"Recurso de origem"**). Assim a tela monta uma **árvore** que mostra os recursos aninhados sob a decisão que os originou — dá para navegar pelos desdobramentos de um processo de forma visual.

### Registrar pedidos e condenações

1. **Aba "Pedidos e condenações".** Abra a aba **"Pedidos e condenações"**. Cada pedido é lançado individualmente com sua **descrição** e o **tipo**: **Pecuniário** (valor) ou **Obrigação de fazer**.
2. **Pedido pecuniário.** Para pedidos com valor, informe os componentes separadamente — **principal**, **correção**, **juros**, **multa**, **honorários sucumbenciais** e **honorários contratuais**. Um **estimador de honorários sucumbenciais (art. 85)** ajuda a calcular a faixa de honorários a partir do valor da condenação.
3. **Obrigação de fazer.** Para pedidos do tipo obrigação de fazer, descreva a obrigação em vez dos valores.
4. **Resultado e decisão por instância.** Registre o **resultado final** de cada pedido (Pendente, Favorável, Parcialmente favorável, Desfavorável). No card **"Decisões por instância"** de cada pedido, cadastre a decisão proferida em cada instância (a instância e o resultado). A lista de pedidos é **segregada por matéria** — trabalhista, cível, tributário, administrativo — em grupos separados.

### Registrar acordos

1. **Aba "Acordos".** Abra a aba **"Acordos"** para registrar acordos, inclusive extrajudiciais. Escolha o **tipo** (Judicial, Extrajudicial, Conciliação, Mediação), informe o **valor**, a **data** e um comentário, e clique em **"Adicionar acordo"**.

### Controlar prazos processuais

1. **Aba "Prazos".** Abra a aba **"Prazos"** e clique para abrir um prazo: descreva **o que é devido**, a **data-gatilho**, o **tipo de prazo** (catálogo), os **dias**. Há a marcação de **prazo em dobro para a Fazenda** quando aplicável, e o campo de **fundamento legal**. Clique em **"Abrir prazo"**. O prazo nasce **Em andamento**.
2. **Suspender e retomar.** Um prazo em andamento pode ter a contagem **suspensa** (botão **"Suspender"**), em função de uma pendência — recesso forense, sobrestamento do processo, terceiro ou outro motivo. Informe o motivo, a data e um comentário. Um prazo suspenso é depois **retomado** (botão **"Retomar"**).
3. **Marcar cumprido.** Enquanto o prazo está em andamento ou suspenso, use **"Marcar cumprido"** quando a tarefa for concluída. Cada prazo tem seu próprio **histórico de alterações** (abertura, suspensão, retomada, cumprimento).

### Manter a agenda do processo

1. **Card "Agenda".** Na ficha, no card **"Agenda"**, crie eventos de calendário do processo (audiências, reuniões, prazos internos): informe **data**, **título** e **notas**, e clique em **"Adicionar evento"**. Cada evento da agenda tem uma **situação** (ex.: concluído, em andamento), que você pode ajustar.

### Avaliar risco e constituir provisão (contingência)

1. **Aba "Contingência".** Abra a aba **"Contingência"**. É aqui que se controla o prognóstico do processo e a provisão contábil associada.
2. **Registrar avaliação de risco.** No formulário, informe a **expectativa de perda** (Provável, Possível, Remota), o **valor-base**, a **data-base** e, opcionalmente, o **índice** (ex.: SELIC) de atualização. A **justificativa é obrigatória** — toda avaliação de risco exige justificar a chance de perda atribuída — e há também um **motivo padronizado** (lista parametrizável). Clique em **"Registrar avaliação"**. É possível informar o **valor sob os outros cenários** (provável/possível/remota) para uma visão comparativa.
   - **A linha "Cenários" mostra dois números por cenário.** O primeiro é o valor **como foi cadastrado na data-base** — ele não muda nunca, porque a avaliação é gravada uma vez e não se reescreve. O segundo, à direita da seta, é o **valor corrigido pelo índice da avaliação até hoje**, calculado na hora em que você abre a ficha (por isso é sempre mais atual do que qualquer rotina noturna). Isso vale para os **três** cenários e **antes** de existir qualquer provisão — a provisão corrige só o cenário Provável, e só depois de constituída.
   - **Se o segundo número não aparecer**, é porque não há o que corrigir: ou a avaliação foi registrada **sem índice**, ou a **série do índice está vazia** no período. No segundo caso o cenário exibe o selo **"Série do índice incompleta"** — o valor mostrado está **subestimado**, e a correção é alimentar os meses que faltam em **Jurídico → Catálogos jurídicos**, na **"Série de taxas de índice"** (passo 4 daquela página). Sem o selo e sem seta, o número é simplesmente o valor da data-base.
3. **Anexar evidências.** Cada avaliação de risco aceita o **anexo de evidências** (decisões, pareceres, cálculos) que sustentam a expectativa registrada, vinculadas àquela avaliação.
4. **Constituir a provisão.** Quando a avaliação **atual** aponta perda **Provável**, aparece o botão **"Constituir provisão"**. Ao acioná-lo, o sistema cria a provisão a partir do valor avaliado. A provisão fica **Ativa** e pode ser **revertida** (botão **"Reverter"**).
5. **Solicitar alteração de valor da provisão.** Numa provisão ativa, use **"Solicitar alteração de valor"**: informe o **novo valor**, o **motivo padronizado**, a **justificativa obrigatória** e anexe o **documento comprobatório** — a peça técnica ou contábil que sustenta o novo valor. O botão **"Enviar para aprovação"** só habilita com os quatro preenchidos; o documento é arquivado junto com a alteração e fica na trilha de auditoria, então a justificativa **descreve** a razão e o anexo **prova**. A alteração fica com situação **"Aguardando aprovação"** e **não altera** o valor efetivo enquanto não for aprovada — o botão **"Aplicar alteração aprovada"** é o passo que efetiva a mudança. Assim, nenhuma alteração de provisão passa sem justificativa nem sem a etapa de aprovação.
6. **Dar o parecer técnico (etapa contábil).** Toda alteração pendente nasce marcada como **"Aguardando parecer técnico"**, e essa marca é visível para **todo mundo** que abre o processo — inclusive para quem não pode assiná-la. Quem tem a alçada técnica (por padrão o cargo **Contador**) vê também o botão **"Dar parecer técnico"**: registre **como o novo valor foi mensurado e classificado** e confirme em **"Registrar parecer"**. A marca passa a **"Parecer técnico: "**, e o texto do parecer aparece ao passar o mouse sobre ela.São **duas etapas distintas e nesta ordem**: a **técnica** atesta que o valor está **certo**; a de **valor** autoriza que ele seja **liberado**. O parecer técnico **não** libera nada — depois dele a solicitação continua "Aguardando aprovação" e ainda precisa passar pela alçada de valor.**Quem pediu a alteração não pode assinar o próprio parecer.** Se for a mesma pessoa, o sistema recusa dizendo que as duas etapas exigem duas alçadas, e vale mesmo que o administrador tenha concedido as duas permissões ao mesmo cargo.**Se "Aplicar alteração aprovada" recusar, leia qual etapa a mensagem nomeia:** *"Falta o parecer técnico"* é a etapa contábil; *"não aprovada"* é a alçada de valor, que se resolve na bandeja de aprovações. São recusas diferentes e resolvidas em lugares diferentes.

### Garantias e depósitos judiciais

1. **Garantias.** Na ficha, no card **"Garantias"**, registre as garantias do processo com o **número do contrato** de referência, a **descrição** e o **valor**. Uma garantia fica **Pendente** até ser **baixada** (botão **"Baixar"**).

**A baixa é a emissão do título.** Ao clicar em **"Baixar"**, o sistema abre um formulário pedindo a **natureza** (a pagar ou a receber), o **favorecido**, a **categoria** e o **vencimento** — e emite o título correspondente no financeiro, já identificando o processo como origem. O **valor não é digitado**: é o que está registrado na garantia. Se o título não puder ser emitido, **a baixa não acontece** e o processo continua bloqueado para arquivamento. Quem informa a natureza é você: o sistema não adivinha, porque em sucumbência recíproca e levantamento parcial o palpite erraria.

1. **Depósitos judiciais.** No card **"Depósitos judiciais"**, registre os depósitos vinculados ao processo: **tipo**, **valor**, **índice** de atualização, **data** e **conta/juízo**. Um depósito pode ser **atualizado** por índice, **baixado** (botão **"Baixar"**, informando natureza, favorecido, categoria e vencimento — o sistema emite o título e usa o **valor atualizado** do depósito quando houver, porque depósito parado em juízo rende correção) e **conciliado** com o pagamento correspondente (botão **"Conciliar"**), relacionando o levantamento a um pagamento/sentença.

### Despesas processuais

1. **Card "Despesas processuais".** No card **"Despesas processuais"**, registre o ciclo financeiro de despesas do processo (adiantamentos, reembolsos, condenações). Cada despesa contém o **tipo**, o **favorecido**, os valores (**principal** e **encargos**), a **data de vencimento** e o **responsável**. Clique em **"Adicionar despesa"**.
2. **Decida a despesa: aprovar, rejeitar ou pagar.** A despesa nasce **Solicitada** e cada linha oferece as decisões que cabem naquele estado — quem não tem a permissão de gestão do processo não vê nenhuma delas.
   - **Aprovar** passa a despesa para Aprovada. Acima do valor de alçada, a aprovação exige que a alçada correspondente já tenha decidido — o sistema recusa enquanto isso não aconteceu.
   - **Rejeitar** exige **motivo**, e ele fica na trilha da despesa. Uma despesa paga ou já rejeitada não pode ser rejeitada de novo.
   - **Pagar** só aparece na despesa Aprovada, e **arquiva o comprovante**: a janela pede qual dos anexos da despesa é o comprovante e a data do pagamento. **Se a despesa ainda não tem anexo, a janela diz isso e não oferece o botão** — o sistema recusa registrar pagamento sem comprovante, então anexe primeiro pelo card de anexos.
   - Cada decisão entra na **trilha da despesa** (o ícone de histórico na linha), com quem decidiu e quando.

### Revisões de provisão

1. **Card "Revisões de provisão".** Quando a **expectativa de perda** de um processo muda e esse processo **carrega provisão**, o sistema abre sozinho uma **tarefa de revisão** — uma por provisão viva —, com prazo tirado do tipo de prazo PROVISION\_REVIEW (parametrizável por tenant). O card mostra a mudança (Provável → Possível), o prazo, a situação e as observações; tarefa passada do prazo ganha o selo **Vencida**.
   - **Concluir a revisão** exige a permissão de gestão de provisão. Registre nas observações o que a revisão concluiu — se a provisão foi mantida, ajustada ou revertida —, porque é isso que explica, depois, por que o valor provisionado ficou como ficou.
   - **A tarefa não nasce em toda mudança de expectativa**: só quando há provisão viva no processo. Mudança de expectativa em caso sem provisão não abre revisão, porque não há o que revisar.
   - **Se aparecer "Você não tem acesso a isto"** no lugar da lista, o seu perfil abre o processo mas não lê as provisões dele. Peça o acesso — não conclua que não há revisão pendente.

### Anexar arquivos ao processo

1. **Card "Anexos".** Na ficha, no card **"Anexos"**, envie os arquivos do processo. Todos os arquivos anexados ficam visíveis de forma contínua no mesmo card, e há anexos também no nível de cada andamento (documentos do evento) e de cada avaliação de risco (evidências).

### Arquivar o processo

1. **Arquivar.** Com o processo **Ativo**, clique em **"Arquivar"** no topo da ficha. O sistema **exige** um **motivo padronizado** (do catálogo parametrizável) e uma **justificativa** — sem os dois, o arquivamento não é confirmado. Ao confirmar, a situação passa a **Arquivado** e a ficha fica imutável.
2. **Bloqueio por garantias/depósitos pendentes.** O sistema **impede o arquivamento** enquanto houver **garantia ou depósito ainda pendente**. Libere/levante as garantias e depósitos em aberto antes de encerrar o processo.

### Imprimir e exportar a ficha

1. **Imprimir PDF.** No topo da ficha, **"Imprimir PDF"** gera a ficha do processo com seus campos e informações, para impressão.
2. **Exportar dados.** O seletor **"Exportar dados"** exporta a ficha nos formatos **Texto (.txt)**, **CSV (.csv)**, **XML (.xml)** e **OpenDocument (.odf)**. Na **lista** de processos o mesmo seletor oferece os cinco formatos, incluindo **PDF (.pdf)**, e **"Exportar planilha"** continua baixando a relação em planilha.

Duas observações sobre o que sai no arquivo. Os cabeçalhos das colunas saem com o **nome técnico do campo** (caseNumber, caseKind, matter…) em todos os formatos — é exportação para tratamento externo, não relatório formatado, e o nome estável é o que permite abrir o arquivo em planilha ou script sem depender do idioma da tela. E a exportação leva a **lista inteira** que você tem permissão de ver: a busca da grade filtra o que está na tela, não o que vai para o arquivo.

### Painel do gestor

1. **Abra "Meu painel jurídico".** Menu **Jurídico → Meu painel jurídico**. O painel reúne centralmente, num só lugar, os **próximos prazos**, a **agenda** e os **processos sem movimentação** — os seus e os dos empregados sob a sua supervisão (das unidades que você chefia e sub-unidades). Cada linha tem o botão **"Abrir processo"** para saltar direto à ficha.

### Prazos vencidos

1. **Abra "Prazos".** Menu **Jurídico → Prazos**. A tela lista os prazos **em andamento que já passaram da data de vencimento** (atrasados), com o que é devido, a data-limite e o botão **"Abrir processo"**.

### Processos parados (sem movimentação)

1. **Abra "Processos parados".** Menu **Jurídico → Processos parados**. Informe o número de **dias sem movimentação** e clique em **"Aplicar"**. O relatório lista os processos ativos sem andamento há pelo menos aquele número de dias, com a **data do último movimento** e os **dias parados** (destacados em vermelho a partir de 90 dias).

### Configurar alertas jurídicos

1. **Abra "Alertas jurídicos".** Menu **Jurídico → Alertas jurídicos**. Defina a **antecedência (dias)** com que o sistema avisa antes de um prazo vencer e a **janela de inatividade (dias)** que caracteriza um processo sem movimento. Escolha os **canais** — **no aplicativo** (ao entrar no sistema) e/ou **e-mail** — e marque **"Alertas ativos"**. Clique em **"Salvar"**. É com essa configuração que o sistema envia as notificações de prazo próximo e de processo sem movimentação.

### Jurimetria (dashboards do contencioso)

1. **Abra "Jurimetria".** Menu **Jurídico → Jurimetria**. A tela aplica métodos quantitativos ao acervo: filtros por **período**, **matéria** e **unidade**, e KPIs no topo — **total de processos**, **total provisionado**, **provisões ativas**, **prazos em andamento** e **prazos vencidos**. Abaixo, gráficos interativos de distribuição **por matéria**, **por instância**, **por expectativa de perda** e **por resultado dos pedidos**, além dos **valores conciliados de depósitos**. Use **"Exportar CSV"** para baixar os números.



![](https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/legal-04-jurimetrics.png)

1. **Anexo de Riscos Fiscais (LDO).** Ainda na Jurimetria, o card **"Anexo de Riscos Fiscais (LDO)"** reúne as contingências classificadas como **perda possível**, agrupadas por **categoria** e **matéria**, com a contagem de processos e o valor de cada grupo e o total geral. É a peça que a **LRF art. 4º §3º** manda divulgar no anexo da Lei de Diretrizes Orçamentárias.
   - **"Exportar CSV"** baixa exatamente esse quadro, para quem monta a LDO. O arquivo abre direto no Excel e traz os rótulos traduzidos, não os códigos internos.
   - **O card exige a permissão de gerir processo jurídico**, e não a de apenas ler — diferente do resto da tela. O motivo é que o anexo é um **agregado do acervo inteiro**: o valor de um processo sigiloso entra no total mesmo que o número dele nunca apareça. Oferecer o total a todo leitor vazaria pela soma o que o sigilo protege processo a processo. Se você não vê o card, é isso.
   - **Vale conferir a data de corte com a contabilidade**: o anexo reflete as avaliações de risco vigentes no momento em que a tela é aberta, não uma foto fechada de competência.

### Histórico de risco e provisão

1. **Abra "Histórico de risco e provisão".** Menu **Jurídico → Histórico de risco e provisão**. O relatório consolida **todas as alterações** de **chance de perda** e de **valor de provisão** de todos os processos, com filtros por período, matéria, tipo e unidade. Cada linha mostra o tipo, o processo, o valor **anterior → novo**, o **autor**, a **data/hora**, a **justificativa** e se a alteração tem **evidência** anexada. Há **"Exportar CSV"** para o histórico completo.

### Conciliação de depósitos

1. **Abra "Conciliação de depósitos".** Menu **Jurídico → Conciliação de depósitos**. A tela relaciona **depósitos × levantamentos × pagamentos**, exibindo o **valor corrigido**, o **valor levantado**, o **alvará**, as **despesas custeadas**, a data e a **divergência** de cada depósito (Conciliado, Pendente, Levantado sem valor, Valor divergente, Não vinculado a pagamento, Despesas não batem com o levantamento). Os totais (corrigido, levantado, contagem de divergências) aparecem no topo, e **"Exportar CSV"** baixa a relação para tratamento das divergências.
2.

**Por que isso importa.** Um alvará pode custear duas coisas diferentes: o pagamento de um acordo/sentença à outra parte, ou as despesas do próprio processo (custas, perícia, dispêndios recursais). Sem informar o depósito, o segundo caso ficava sem contrapartida e o relatório acusava divergência num levantamento que estava correto.

**Diga de qual depósito saiu o dinheiro, ao pagar uma despesa.** Na ficha do processo, no card **Despesas processuais**, o diálogo de **Pagar** tem o campo **"Custeada por depósito judicial"**. Deixe **"Nenhum (caixa)"** quando o pagamento saiu do caixa do órgão — é o caso comum. Preenchendo, o pagamento passa a ser confrontado com o levantamento na conciliação: o depósito deixa de aparecer como **"Não vinculado a pagamento"** e a coluna **"Despesas custeadas"** mostra o total e a quantidade. O seletor só oferece depósitos **daquele processo**.

1.

**Uma execução que não encontrou nada também é registrada**, de propósito. Sem essa linha, "nenhuma divergência hoje" e "a varredura parou de rodar" ficariam com a mesma aparência na tela — e a segunda é a que ninguém abriria chamado para reclamar.

**Confira se a conciliação automática está rodando.** No fim da tela, **"Execuções da conciliação automática"** lista as últimas varreduras: quando rodou, quantos depósitos conferiu, quantas divergências encontrou, quantas eram **novas** e quantos avisos saíram. A varredura roda **de madrugada**, sozinha, e avisa os responsáveis **apenas** das divergências que não existiam na execução anterior — repetir a lista de ontem todo dia é o que faz um aviso deixar de ser lido.

## Catálogos jurídicos

***

O que aparece nos seletores do módulo — subtipo de andamento, situação do processo, motivo de arquivamento, tipo de prazo, motivo de alteração de risco e de provisão, índice econômico — não é fixo: cada órgão parametriza essas listas conforme o seu vocabulário e as suas fases de tramitação. Nesta tela você mantém todos num só lugar — assim, quando o time decide chamar uma fase de outro jeito ou precisa de um novo tipo de andamento, a mudança é feita uma vez e passa a valer para todas as fichas, sem depender da TI.

:::BlockQuote
**Catálogo vazio bloqueia o fluxo que depende dele, e a recusa não explica isso.** Arquivar um processo exige um motivo de arquivamento; abrir um prazo exige um tipo de prazo; alterar uma provisão exige um motivo de alteração. Enquanto a lista correspondente estiver vazia, a ação é recusada sem dizer que a lista é a causa. Por isso o topo da tela avisa quais catálogos ainda estão vazios e oferece **"Carregar os padrões destes"**, que semeia todos de uma vez.
:::

1. **Abra "Catálogos jurídicos".** Menu **Jurídico → Catálogos jurídicos**. A tela traz **oito** seções independentes: **Subtipos de andamento**, **Situações de tramitação do processo**, **Motivos de arquivamento**, **Tipos de prazo**, **Motivos de alteração de provisão**, **Motivos de alteração de risco**, **Índices econômicos** e **Varas e órgãos julgadores** — mais a **Série de taxas de índice** (passo 4) logo abaixo dos índices.
2. **Subtipos de andamento.** É a lista que alimenta o campo **tipo de andamento** dos lançamentos do histórico. Para cadastrar um novo, informe o **nome** (ex.: petição inicial, sentença, audiência) e a **categoria** a que ele pertence — **Judicial** ou **Administrativa** — e confirme. Cada item pode ser **removido** quando deixar de ser usado. Se preferir começar de uma base pronta, clique em **"Semear padrões"** e o sistema cria os subtipos mais comuns de uma vez.
3. **Situações de tramitação do processo.** É a lista que alimenta o seletor **"Situação do processo"** da ficha. Cadastre as situações que descrevem o andamento do caso (ex.: em andamento, aguardando decisão, suspenso), **remova** as que não usa e, se quiser, clique em **"Semear padrões"** para carregar o conjunto inicial.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/e32-21-legal-catalogs.png" alt caption width="3200" height="2000"}
4. **Série de taxas de índice.** Logo abaixo do catálogo de **índices econômicos** fica a série deles: **quanto cada índice vale, mês a mês**. Isso importa mais do que parece — **uma provisão que referencia um índice é corrigida apenas pelos meses presentes aqui**. Se faltar mês, o valor sai **subestimado**, e a série nasce **vazia**: sem alimentar esta tela, toda provisão indexada fica parada no valor histórico como se tivesse sido corrigida.
   - **A taxa é decimal, não percentual.** 0,01 significa **1%**. Digitar 5 pensando em "cinco por cento" multiplica a provisão por seis. Por isso a coluna **"Equivale a"** mostra o percentual correspondente ao lado do valor gravado: uma linha na unidade errada aparece como um absurdo (500,0000%) antes de chegar a qualquer cálculo.
   - **Use o "Simulador de correção" antes de provisionar.** Informe valor base, data base, índice e data alvo: ele devolve o valor corrigido **e avisa, em destaque, quando a série não cobre o período inteiro**. É a forma de descobrir a lacuna enquanto ela ainda é barata de fechar.
   - Manter a série exige a permissão de **gerir provisão jurídica**. Quem não a tem lê a série e usa o simulador, mas não acrescenta nem remove mês.

Você sabe que deu certo quando o subtipo ou a situação recém-cadastrada passa a aparecer, respectivamente, no seletor de tipo de andamento da aba **Andamentos** e no seletor **"Situação do processo"** da ficha.

## Relatório de despesas processuais

***

As despesas de cada processo (custas, adiantamentos, reembolsos, condenações) são lançadas caso a caso na ficha, mas o gestor precisa enxergar o todo: quanto o contencioso consumiu no período, em que tipos de despesa e em que fase do processo. Este relatório reúne essa visão gerencial num só lugar e permite levar os números para uma planilha, respeitando a confidencialidade de cada processo — você só vê as despesas dos casos que tem permissão para acessar.

1. **Abra "Relatório de despesas processuais".** Menu **Jurídico → Relatório de despesas processuais**.
2. **Filtre o período e o recorte.** Informe o **período** (data inicial e final) e, se quiser afunilar, o **tipo de despesa** e a **situação**. Aplique o filtro para atualizar os números.
3. **Leia os totais.** O relatório consolida as despesas do período e apresenta os **totais por tipo** (custas, honorários, perícia…) e os **totais por fase** do processo, ajudando a identificar onde o gasto se concentra.
4. **Exporte para planilha.** Clique em **"Exportar XLSX"** para baixar o relatório em planilha e tratar os números fora do sistema (rateio, conferência, prestação de contas).:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/e32-22-legal-expense-report.png" alt caption width="2880" height="1800"}

Você sabe que deu certo quando os totais refletem apenas o período filtrado e apenas os processos que você pode ver, e o arquivo **XLSX** baixa com as mesmas linhas exibidas na tela.

## Verificação

***

Você sabe que funcionou quando:

- O processo aparece na lista **Processos** com número, matéria, polo, situação **Ativo** e valor da causa.
- Ao digitar um número já existente, surge o aviso **"Já existe processo com este número:"** com link para a ficha original.
- Os andamentos lançados aparecem na aba **Andamentos** com tipo, data e o autor de cada lançamento, e o filtro por tipo/subtipo restringe a lista.
- Os recursos encadeados aparecem como **árvore** de desdobramentos, com os sub-recursos aninhados sob o recurso de origem.
- Os pedidos aparecem **agrupados por matéria**, com os componentes de valor (principal, correção, juros, multa, honorários) e as decisões por instância.
- Um prazo suspenso mostra a situação **Suspenso** e volta a **Em andamento** ao ser retomado; prazos atrasados aparecem em **Jurídico → Prazos**.
- Ao registrar perda **Provável**, o botão **"Constituir provisão"** aparece; a provisão criada fica **Ativa**.
- Uma solicitação de alteração de provisão fica **"Aguardando aprovação"** e só muda o valor efetivo após **"Aplicar alteração aprovada"**.
- O arquivamento é **bloqueado** enquanto houver garantia ou depósito pendente, e exige motivo padronizado + justificativa.
- A **baixa** de garantia/depósito **emite o título** a pagar ou a receber no financeiro; sem título emitido não há baixa.
- Quem aprova uma alteração de provisão só consegue aprovar **até o valor da sua alçada**; acima disso o sistema recusa e a solicitação continua pendente para quem tiver alçada.
- A ficha imprime em **PDF** e exporta em **.txt/.csv/.xml/.odf**; a lista exporta em planilha.
- O **painel do gestor** mostra prazos, agenda e casos parados; a **jurimetria** mostra os KPIs e gráficos; o **histórico de risco e provisão** e a **conciliação de depósitos** trazem as respectivas listas.

## Erros comuns

***

- **"Número CNJ inválido (dígito verificador)"** — no tipo **Judicial**, o número precisa ser um CNJ válido; confira os dígitos. Para número administrativo, use o tipo **Administrativo**.
- **Não consigo constituir a provisão** — o botão **"Constituir provisão"** só aparece na avaliação de risco **atual** e apenas quando a expectativa de perda é **Provável**.
- **Alteração de provisão não mudou o valor** — a solicitação fica **Aguardando aprovação**; o valor só muda depois de **"Aplicar alteração aprovada"**. Sem novo valor, motivo padronizado e justificativa, o envio nem é liberado.
- **Não consigo registrar a avaliação de risco** — a **justificativa é obrigatória**; sem ela o registro é recusado.
- **Não consigo arquivar o processo** — há **garantia ou depósito pendente**; libere/levante os pendentes antes. E o arquivamento exige **motivo padronizado + justificativa**.
- **"Sem autorização" ao salvar** — as ações que gravam dados do processo exigem a permissão **Gerir processo jurídico**; as consultas são abertas. Peça a permissão em [Administração](docId\:Z8SS7r6Bvhs09rP1SPxUD).
- **A ficha ficou imutável** — um processo **Arquivado** não aceita mais alterações; ele permanece no histórico como registro.
- **Não recebo os avisos de prazo** — confira em **Alertas jurídicos** se os alertas estão **ativos**, se o **canal** (e-mail/no aplicativo) está marcado e se as janelas de antecedência/inatividade estão configuradas.

[title] Contabilidade
[path] Aplicações/ERP/Manual do Usuário/

# Contabilidade (razão, eventos, regras, lançamentos, falhas e DRE)

:::BlockQuote
Pré-requisitos: [Financeiro — cadastros de apoio](docId\:yTzjjyyML1B_60VgwDT09) (plano de contas, naturezas e centros já disponíveis).
:::

## Introdução

***

A contabilidade no ERP é movimentada **principalmente por eventos automáticos** vindos das outras áreas: o faturamento gera receita + impostos + custo da mercadoria; o recebimento de compra gera entrada de estoque + conta a pagar; a baixa de tesouraria gera redução de banco + baixa de fornecedor; a *depreciação* do patrimônio gera despesa + depreciação acumulada. Você quase nunca precisa lançar manualmente — o sistema já sabe qual partida (débito × crédito) cada operação exige, porque isso está descrito nos **eventos contábeis** e nas **regras** que você configura uma única vez.

Esta página cobre todo o módulo de Contabilidade do ponto de vista do operador: consultar o **plano de contas** (o razão) e as **naturezas**, entender e ajustar os **eventos contábeis** e os **grupos de regras** que geram as partidas, acompanhar e investigar os **lançamentos**, tratar as **falhas de contabilização** (reprocessar o que não gerou partida), exportar o material para o contador e ler a **DRE gerencial**. É aqui que o contador da ACME confere que "tudo bateu" antes de fechar o mês.

## Passo a passo

***

### Consultar o plano de contas (razão)

O *plano de contas* é o esqueleto que todo lançamento referencia — ativo, passivo, receita, despesa. O ERP já vem com um plano-semente (padrão PCASP) que você pode conferir e complementar.

1. **Abra "Plano de contas".** Menu **Contabilidade → Plano de contas**. A lista mostra o código hierárquico, o nome e a natureza de cada conta.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/118-ledger-accounts.png" alt caption width="3200" height="2000"}
2. **Explore o plano completo.** A tela oferece as visões **Lista** e **Árvore (PCASP)**. Na lista você percorre todas as contas — código hierárquico, nome, tipo (ativo, passivo…), se é analítica e a situação —, das contas de topo (1 — Ativo) até as folhas (1.1.5.6.1.01 — Material de Consumo - Almoxarifado). É por aqui que você localiza a conta certa antes de usá-la em uma regra ou consultar seus lançamentos.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/026-ledger-accounts-detail.png" alt caption width="3200" height="2000"}

:::BlockQuote
**Conta sintética × analítica.** Contas "pai" (sintéticas, ex.: 1.1 — Ativo circulante) só somam as filhas; elas **não** aceitam lançamento direto. Sempre lance em contas analíticas (as folhas da árvore, ex.: 1.1.2.01).
:::

:::BlockQuote
**Validações ao cadastrar/editar uma conta.** O **tipo** é escolhido numa lista fechada do padrão PCASP — Ativo, Passivo, Patrimônio Líquido, VPA (variação patrimonial aumentativa), VPD (variação patrimonial diminutiva) e Controle. Um tipo fora dessa lista é **rejeitado** (o sistema não salva e devolve erro de validação). O **código** da conta é único: repetir um código já existente também é recusado. Quando o cadastro é aceito, a conta pode ser criada, ter o nome alterado e ser removida enquanto não tiver lançamentos que dependam dela.
:::

### Conferir as naturezas contábeis

1. **Abra "Naturezas contábeis".** Menu **Contabilidade → Naturezas contábeis**. A natureza classifica o "tipo" da conta/movimento (receita, despesa, ativo, passivo) e é usada pelas regras para escolher a partida certa.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/119-accounting-natures.png" alt caption width="3200" height="2000"}
2. **Confira a natureza na lista.** Cada linha traz o código, o nome, o tipo e as contas de débito e crédito padrão associadas — é o que as regras usam para escolher a partida.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/024-accounting-natures-detail.png" alt caption width="3200" height="2000"}

:::BlockQuote
**A natureza só aceita contas que existem.** Ao definir a conta de débito ou de crédito padrão de uma natureza, o sistema exige que a conta apontada exista no plano de contas — uma natureza que aponta para uma conta inexistente é **rejeitada**. Cadastre a conta no plano primeiro, depois amarre a natureza a ela.
:::

1. **Naturezas de despesa (STN)** — para órgãos públicos, o menu **Contabilidade → Naturezas de despesa (STN)** traz o catálogo oficial da Secretaria do Tesouro Nacional, usado na classificação orçamentária da despesa pública.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/120-expense-natures.png" alt caption width="3200" height="2000"}

### Configurar os eventos contábeis

O **evento contábil** é o "gatilho" de negócio que gera uma partida — por exemplo "provisão de compra", "baixa de conta a pagar", "devolução de venda", "depreciação do mês". Cada operação das outras áreas dispara um evento, e o evento (via regra) resulta no lançamento.

1. **Abra "Eventos contábeis".** Menu **Contabilidade → Eventos contábeis**. A lista mostra os eventos cadastrados e de qual módulo cada um se origina.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/121-accounting-events.png" alt caption width="3200" height="2000"}
2. **Abra um evento** para ver quando ele dispara e a que grupo de regras está ligado. Cada evento é montado por **linhas** — cada linha é de débito ou de crédito e aponta para uma conta fixa ou para a conta da natureza.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/023-accounting-events-detail.png" alt caption width="3200" height="2000"}

:::BlockQuote
**O modelo de lançamento precisa ser balanceável.** O sistema exige que o evento tenha ao menos uma linha de débito e uma de crédito: um modelo com linhas só de um lado é **rejeitado**. Se uma linha usa conta fixa, essa conta tem que existir no plano; e o **código do evento** é único (repetir um código já cadastrado é recusado).
:::

### Definir e simular grupos de regras

O **grupo de regras** é a tabela de decisão que traduz o evento em partida: "se a operação atende a estes critérios, então debita a conta X e credita a conta Y neste valor". É aqui que mora a inteligência da contabilização automática.

1. **Abra "Grupos de regras".** Menu **Contabilidade → Grupos de regras**. A lista traz cada grupo, o evento que ele atende e a versão publicada.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/122-accounting-rule-groups.png" alt caption width="3200" height="2000"}
2. **Abra um grupo** para ver os **critérios** (as condições que selecionam a regra) e as **linhas de partida** (débito/crédito, conta, valor) que ele produz.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/025-accounting-rule-groups-detail.png" alt caption width="3200" height="2000"}
3. **Parâmetros de regra.** Menu **Contabilidade → Parâmetros de regra** — valores nomeados (alíquotas, contas de referência) que as regras usam sem "chumbar" o número dentro delas. Mudou a alíquota? Muda em um só lugar. Você escolhe o grupo de regras no topo e cadastra a chave, o tipo e o valor no formulário; a lista abaixo mostra os parâmetros já cadastrados para o grupo selecionado — no ambiente de demonstração ela aparece com "Sem parâmetros" até você salvar o primeiro.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/126-rule-parameters.png" alt caption width="3200" height="2000"}
4. **Simule antes de publicar.** Menu **Contabilidade → Simulador de regras**. Informe uma operação de exemplo e o sistema mostra **qual partida seria gerada** — sem tocar em nada de verdade. Use sempre o simulador antes de publicar uma regra nova, para não descobrir o erro só depois que a venda real não contabilizou.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/127-rule-simulator.png" alt caption width="3200" height="2000"}
5. **Histórico e log das regras.** Menu **Contabilidade → Histórico de grupos**: você seleciona um grupo e vê as versões já publicadas dele (quem mudou o quê e quando) — no ambiente de demonstração aparece "Sem versões publicadas" enquanto o grupo não tiver sido publicado. Menu **Contabilidade → Log de aplicação** mostra **onde cada regra atuou** — em quais lançamentos ela foi aplicada. É a trilha de auditoria do motor.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/128-rule-group-history.png" alt caption width="3200" height="2000"}:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/129-rule-application-log.png" alt caption width="3200" height="2000"}O log tem **duas maneiras de perguntar**, e a diferença importa. Escolha em **"Buscar por"**: por **evento contábil**, quando você já sabe qual evento investigar; ou por **período**, informando **De** e **Até**, quando o lançamento **não saiu** e você não sabe qual evento deveria tê-lo produzido — que é justamente o caso em que se procura o log. **Até 2026-08-03 só a primeira pergunta era possível**: sem nomear o evento, a tela não carregava nada.A busca por período cobre o **dia inteiro** das duas pontas — um recorte que parasse às zero hora do dia final esconderia exatamente os lançamentos de fechamento de mês.A tela exige a permissão de **gerir regra contábil**. Quem não a tem recebe o aviso de **sem acesso** — e não uma lista vazia, que se leria como "o motor não fez nada".
6. **Migração v1→v2.** Menu **Contabilidade → Migração v1→v2** — assistente que converte grupos de regras do motor antigo para o novo formato de tabela de decisão. Só é usado uma vez, quando você moderniza regras legadas.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/130-rule-engine-migration.png" alt caption width="3200" height="2000"}

### Acompanhar e investigar os lançamentos

O *lançamento contábil* (a partida) é o resultado final: débito e crédito em contas do plano, com data, valor, histórico e referência ao evento que o originou.

1. **Abra "Lançamentos".** Menu **Contabilidade → Lançamentos**. A lista mostra todos os lançamentos, cada um com sua partida balanceada (total de débitos = total de créditos).:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/123-journal-entries.png" alt caption width="3200" height="2000"}
2. **Filtre para achar um lançamento específico.** Acima da tabela há uma linha de filtros que você combina à vontade — o sistema mostra só os lançamentos que atendem a **todos** ao mesmo tempo\:A consulta é refeita no servidor a cada mudança, então mesmo um volume grande não trava o navegador.
   - **Módulo de origem** (JOURNAL.FILTER\_SOURCE\_MODULE) — de qual área veio (financeiro, vendas, estoque, fiscal, patrimônio).
   - **Evento** (JOURNAL.FILTER\_EVENT) — combo com os eventos contábeis (provisão, baixa, devolução, depreciação, etc.).
   - **Situação** (JOURNAL.FILTER\_STATUS) — Rascunho, Contabilizado, Estornado.
   - **Data inicial** (JOURNAL.FILTER\_DATE\_FROM) e **Data final** (JOURNAL.FILTER\_DATE\_TO) — intervalo da data do lançamento.
   - Botão **Limpar filtros** (COMMON.CLEAR\_FILTERS) — zera todos de uma vez.

:::BlockQuote
**De onde vêm os lançamentos.** Num ambiente recém-configurado, a contabilização pode não aparecer sozinha: os eventos contábeis e o plano de contas precisam estar carregados e as regras publicadas. É esperado, não é erro — depois que as regras estão no lugar, cada venda/compra/baixa vira uma partida balanceada automaticamente. O que não gerou partida fica registrado em **Falhas de contabilização** (abaixo).
:::

### Tratar falhas de contabilização e reprocessar

A contabilização automática é **best-effort**: se algo dá errado (evento sem conta configurada, natureza ausente, regra que não casou), o lançamento **não acontece**, mas a operação de negócio (a venda, o recebimento, a baixa) **não é bloqueada**. A falha fica registrada para correção, e nada se perde.

1. **Abra "Falhas de contabilização".** Menu **Contabilidade → Falhas de contabilização**. A lista traz cada operação que não contabilizou, com o motivo e o valor.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/124-posting-failures.png" alt caption width="3200" height="2000"}
2. **Cartão "Pilha de falhas pendentes por motivo".** Quando há falhas pendentes, aparece no topo um cartão (POSTING\_FAIL.BY\_REASON\_TITLE) que agrupa as causas: cada linha mostra a contagem, o trecho inicial do motivo e o valor total acumulado (POSTING\_FAIL.BY\_REASON\_HINT). Em geral **uma única correção de configuração resolve um lote inteiro** — comece por aí. A janela padrão do agregado é de 90 dias (falhas mais antigas não entram, para evitar consultas caras).
3. **Resolva a causa-raiz.** Vá até o cadastro que origina a falha (o evento contábil, a natureza ou a conta que está faltando) e ajuste.
4. **Reprocessar.** Na linha da falha, clique **Reprocessar**: o sistema tenta gerar o lançamento de novo. A geração é **idempotente** — reprocessar não duplica nada. A falha vira **Resolvida**, o lançamento entra no razão e o cartão agregado recalcula sozinho.

### Exportar para o contador

1. **Abra "Exportação contábil".** Menu **Contabilidade → Exportação contábil**. Aqui você gera um **lote** com os lançamentos do período (ex.: maio/2026) para entregar ao contador ou importar em outro sistema contábil. No ambiente de demonstração a lista aparece vazia ("Nenhum lote de exportação ainda") até você gerar o primeiro lote pelo botão **Gerar lote**.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/125-export-batches.png" alt caption width="3200" height="2000"}
2. **Gere o lote do período** e baixe o arquivo. Cada lote fica registrado com o período e a data de geração, então dá para reconciliar o que já foi enviado.

### Ler a DRE gerencial

A *DRE* gerencial (Demonstração do Resultado do Exercício) resume receitas menos custos e despesas do período, apurando o lucro/prejuízo — a leitura executiva de "quanto sobrou".

1. **Abra "DRE gerencial".** Menu **Financeiro → DRE gerencial**. Escolha o período e o sistema monta a demonstração a partir dos lançamentos contabilizados: receita bruta, lucro bruto, EBIT e lucro líquido, além do detalhamento por categoria. No ambiente de demonstração, sem lançamentos contabilizados no período escolhido, os cartões aparecem em R$ 0,00 e o detalhamento mostra "Sem lançamentos no período".:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/038-finance-dre.png" alt caption width="3200" height="2000"}

:::BlockQuote
A DRE fica **vazia sem lançamentos** — ela lê o que a contabilização automática já materializou. Se um período parece "zerado", confira antes se as operações daquele mês geraram partida (passo 14) ou se há pendências em Falhas de contabilização (passo 16).
:::

### Lançar uma partida manual

Além dos lançamentos automáticos, a tela de **Lançamentos contábeis** permite registrar uma partida manual quando não há evento de origem (por exemplo, um ajuste ou uma reclassificação).

1. Em **Contabilidade → Lançamentos contábeis**, preencha a **data**, o **documento** de origem e o **histórico** do lançamento.
2. Adicione as **linhas de débito e de crédito**, escolhendo em cada uma a conta analítica e o valor. Cada linha aceita ainda, opcionalmente, o **centro de custo** e um **parceiro auxiliar** com o tipo (Cliente, Fornecedor ou Banco) — são esses dois campos que alimentam os relatórios de **razão por centro de custo** e **razão auxiliar** (abaixo).
3. O sistema só habilita **Salvar** quando a partida está **balanceada** — total de débitos igual ao total de créditos, e todas as linhas com conta e valor preenchidos.

### Bloquear e fechar períodos contábeis

Depois de conferir o mês, você impede novos lançamentos no período já encerrado.

1. **Abra "Períodos contábeis".** Menu **Contabilidade → Períodos contábeis**.
2. **Bloqueie um mês.** No cartão **Bloquear um período**, informe o **Ano** e o **Mês** e confirme: nenhum lançamento pode mais ser contabilizado, inserido ou excluído naquele mês. Um mês bloqueado pode ser **reaberto** por quem tiver privilégio, caso ainda precise de um ajuste.
3. **Feche o período.** Informe o intervalo de datas e a conta de resultado para apurar e encerrar o período. A apuração pode ser feita mês a mês ou por trimestre, combinando os meses no intervalo escolhido.

### Emitir demonstrativos contábeis

O razão contabilizado alimenta os demonstrativos oficiais, que você emite e exporta para o contador.

1. **Abra "Demonstrativos contábeis".** Menu **Contabilidade → Demonstrativos contábeis**. No topo, escolha o **Demonstrativo** desejado e o intervalo em **De** e **Até**.
2. **Escolha o demonstrativo.** A lista oferece **Livro diário**, **Razão analítico**, **Razão sintético**, **Balancete**, **Balanço patrimonial** e **Variações patrimoniais** (DMPL). O sistema monta a tabela a partir dos lançamentos contabilizados no período; sem lançamentos, aparece "Nenhum lançamento no período".
3. **Exporte para o contador.** Cada demonstrativo pode ser baixado em **CSV**, **TXT** ou **XLSX** (planilha) pelo botão de exportação — os arquivos CSV/TXT já saem com marca UTF-8 para abrir direto no Excel.

### Razão por centro de custo e razão auxiliar

Além dos demonstrativos oficiais, a tela de **Demonstrativos contábeis** oferece dois relatórios de razão mais analíticos: um que quebra o resultado por área e outro que confere a movimentação de um parceiro específico. São eles que aproveitam o centro de custo e o parceiro auxiliar que você informa nas linhas do lançamento.

1. **Emita o razão por centro de custo.** Menu **Contabilidade → Demonstrativos contábeis**; no seletor **Demonstrativo**, escolha **Razão por centro de custo**. O sistema soma o débito, o crédito e o saldo de cada centro de custo no período, mostrando para onde a despesa (ou a receita) foi apropriada — é a visão de "quanto cada setor movimentou".:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/e32-09-accounting-reports.png" alt caption width="2880" height="1800"}
2. **Emita o razão auxiliar.** No mesmo seletor, escolha **Razão auxiliar** para ver a movimentação por parceiro. Use o filtro de **tipo de parte** para restringir a **Cliente**, **Fornecedor** ou **Banco** (ex.: só fornecedores) e conferir o saldo de cada parceiro no razão. Como nos demais demonstrativos, o resultado sai em CSV, TXT ou XLSX pelo botão de exportação.

:::BlockQuote
**Confirmação.** O razão por centro de custo apresenta uma linha por centro, com débito, crédito e saldo do período; o razão auxiliar traz uma linha por parceiro do tipo escolhido. Sem lançamentos no período, ambos exibem "Nenhum lançamento no período".
:::

### Configurar regras de rateio de custo

Algumas despesas caem numa única conta contábil mas precisam ser divididas entre vários setores — energia elétrica entre os departamentos, aluguel entre as filiais. A **regra de rateio de custo** descreve essa divisão uma única vez, e o sistema passa a apropriar automaticamente cada lançamento daquela conta entre os centros de custo indicados.

1. **Abra "Regras de rateio de custo".** Menu **Contabilidade → Regras de rateio de custo**. A lista mostra as contas que já têm rateio configurado e os destinos de cada uma.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/e32-10-cost-apportionments.png" alt caption width="3200" height="2000"}
2. **Escolha a conta e defina os destinos.** Selecione a **conta contábil** a ratear e adicione uma linha para cada destino, informando o **centro de custo** e o **percentual** que ele recebe. Você pode ter quantos destinos precisar (por exemplo, 40% para a Administração e 60% para a Produção).
3. **Feche em 100%.** O sistema só habilita salvar quando a soma dos percentuais dos destinos é exatamente **100%** — assim nenhum valor fica sem apropriação nem é contado duas vezes.

:::BlockQuote
**Confirmação.** Salvo o rateio, a conta aparece na lista com seus destinos, e todo lançamento futuro nessa conta é distribuído entre os centros na proporção definida — refletindo depois no **razão por centro de custo**.
:::

### Registrar ajuste a valor presente

Recebíveis e pagáveis de longo prazo valem menos hoje do que o valor de face, porque embutem juros até o vencimento. O **ajuste a valor presente** (CPC 12) traz esse saldo para o valor de hoje e reconhece a diferença — o desconto — como receita ou despesa financeira, apropriada parcela a parcela ao longo do prazo.

1. **Abra "Ajuste a valor presente (contábil)".** Menu **Contabilidade → Ajuste a valor presente**. A lista mostra os ajustes já registrados, com o valor nominal e o valor presente apurado de cada um.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/e32-11-present-value-adjustments.png" alt caption width="3200" height="2000"}
2. **Registre o título de longo prazo.** Informe o **tipo** (recebível ou pagável), a **referência** do título, o **valor nominal**, o **número de parcelas** e a **taxa mensal** de desconto. O sistema calcula o valor presente e o desconto total a apropriar.
3. **Acompanhe a apropriação parcela a parcela.** A cada período, o sistema apropria uma fração do desconto, reduzindo a diferença entre o valor nominal e o valor presente até o título vencer — sem que você precise recalcular manualmente.

:::BlockQuote
**Confirmação.** O ajuste aparece na lista com o valor presente menor que o valor nominal, e o desconto é reconhecido nas partidas ao longo das parcelas, coerente com o prazo e a taxa informados.
:::

### Conciliar o razão com o financeiro

Fechar o período prova que os débitos batem com os créditos — mas não prova que a contabilidade conta a mesma história que o financeiro. As duas contas podem estar internamente coerentes e ainda assim discordar: um lançamento que não saiu, ou que saiu na conta errada, deixa o razão dizendo uma coisa e o contas a pagar dizendo outra. A **conciliação razão × auxiliar** compara os dois lado a lado antes de você fechar.

1. **Diga qual conta espelha cada auxiliar.** O sistema não adivinha essa ligação: você informa a **conta contábil de fornecedores** e a **conta de clientes** que correspondem ao contas a pagar e ao contas a receber. Enquanto uma delas não for informada, aquela linha volta como **Não configurado** — e isso é diferente de "não divergiu".
2. **Compare na data de fechamento.** Informe a **data de referência**. O saldo do razão considerado inclui tudo que foi contabilizado **até aquele dia, inclusive** — é o mesmo número contra o qual o fechamento é conferido.
3. **Leia o status de cada linha.** São quatro respostas, e três delas não são divergência\:StatusO que significaO que fazer**Conferido**Razão e auxiliar batem ao centavoNada — pode fechar**Divergente**Os dois discordamInvestigar: lançamento faltando, conta errada ou **lado erradoNão configurado**Você não informou a conta daquele auxiliarInformar a conta e comparar de novo**Conta não encontrada**A conta informada não existe no planoCorrigir o código — não é divergência

:::BlockQuote
**Confirmação.** Num período sem problema as duas linhas voltam **Conferido** com divergência zero. Repare que a conta de fornecedores tem saldo **credor** no razão e o auxiliar informa o valor devido como positivo: o sistema normaliza os dois antes de comparar, então um título lançado no **lado errado** aparece como divergência do **dobro** do valor — e não como "confere", que é o que uma comparação ingênua devolveria.
:::

### Gerar a Escrituração Contábil Digital (ECD)

A ECD é o arquivo que leva a escrituração do exercício à Receita Federal. O sistema monta o texto no leiaute normativo a partir do razão contabilizado; a assinatura digital e a transmissão acontecem no PVA-ECD, fora daqui.

1. **Abra "Geração da ECD".** Menu **Administração → Geração da ECD**. Informe a **data inicial** e a **data final** da escrituração e clique em **Baixar SPED-ECD**.
2. **Confira o aviso de código referencial.** Logo abaixo do botão, o sistema informa **quantas contas analíticas saíram sem código referencial** — e lista os códigos delas.Vale entender por que isso importa: o código referencial é a ligação entre a **sua** conta e a conta equivalente do plano de referência da Receita. Uma conta analítica sem esse código simplesmente **não gera o registro I051**, e o arquivo continua saindo bem formado. Ou seja: sem esse aviso, a escrituração vai para o PVA com a ligação faltando e **nada indica isso** — o problema só aparece na validação da Receita, ou depois.O sistema **não bloqueia** a geração. Você pode legitimamente estar no meio do preenchimento dos códigos, e recusar o arquivo trocaria uma lacuna corrigível por uma obrigação que ninguém entrega. Contas **sintéticas** não entram nessa contagem — elas não recebem lançamento e não mapeiam para o plano referencial.
3. **Preencha os códigos que faltam e gere de novo.** O código referencial fica no cadastro de cada conta contábil (**Contabilidade → Plano de contas**). Preenchidos os que o aviso apontou, gere o arquivo outra vez: o aviso deve passar a dizer que **todas as contas analíticas têm código referencial**.

:::BlockQuote
**Confirmação.** O download acontece e, junto dele, o aviso diz **zero** contas sem código — ou lista exatamente quais faltam. O conteúdo do arquivo é **o mesmo** com ou sem o aviso: a checagem não altera um byte do que a Receita recebe.
:::

## Verificação

***

Você sabe que funcionou quando:

- O razão de uma conta (ex.: 1.1.2.01 — Banco Itaú c/c) mostra cada operação financeira do dia (faturamento, recebimento, baixa, depreciação) com saldo acumulado.
- Em qualquer período, o **total de débitos = total de créditos** — toda partida sai balanceada.
- O simulador de regras devolve exatamente a partida esperada **antes** de você publicar a regra.
- Uma operação real (ex.: uma venda de R$ 1.250,00 para o Cliente Exemplo Ltda) aparece na lista de Lançamentos como uma partida contabilizada e balanceada.
- Após corrigir a configuração e clicar **Reprocessar**, a falha some da lista e o cartão de pendências por motivo recalcula.
- A DRE gerencial do período apresenta receitas, custos e resultado coerentes com os relatórios das outras áreas.

## Erros comuns

***

- **Lançamento não aparece após a operação** — os eventos contábeis/plano de contas não estão carregados ou a regra não foi publicada. Confira em **Falhas de contabilização**: a pendência estará lá com o motivo. Corrija a causa e reprocesse.
- **Conta não permite lançamento direto** — você apontou para uma conta sintética (pai); use uma conta analítica (folha) na regra.
- **Regra não casa com a operação** — os critérios do grupo de regras não bateram com os dados da operação. Use o **Simulador de regras** para descobrir por que a regra foi (ou não foi) selecionada antes de publicar.
- **DRE ou balancete zerados** — não há lançamentos contabilizados no período; verifique pendências em Falhas de contabilização.
- **Não consegui salvar a conta contábil** — o tipo informado está fora da lista PCASP (Ativo, Passivo, PL, VPA, VPD, Controle) ou o código já existe em outra conta. Corrija o tipo ou escolha um código livre.
- **Não consegui salvar o evento contábil** — o modelo ficou desbalanceado (só linhas de débito ou só de crédito), aponta para uma conta fixa que não existe, ou o código do evento repete um já cadastrado. O sistema só aceita eventos com ao menos um débito e um crédito.
- **Natureza recusada** — a conta de débito ou de crédito padrão informada não existe no plano de contas. Cadastre a conta primeiro.


[title] O que é Hyper?
[path] /


[title] Visão geral
[path] Aplicações/Agility/Workspaces e Fundamentos/

# O Workspace e sua Visão geral

:::BlockQuote
Crie o espaço de trabalho da organização e use a Visão geral para acompanhar, em um único ponto, projetos, portfólios, times e ARTs.
:::

***

Um Workspace é o espaço organizacional onde ficam reunidos o trabalho e as pessoas de uma organização. Projetos, portfólios, times, ARTs, metas, pessoas e dados financeiros são consultados dentro desse contexto; selecionar o Workspace correto é o que determina o conjunto de dados que você verá nas páginas seguintes.

A página inicial do Workspace funciona como um diretório operacional. Ela mostra cartões com a quantidade atual de Projetos, Portfólios, Times e ARTs e, logo abaixo, até três projetos recentes. A barra lateral permanece disponível para aprofundar cada assunto, sem obrigar você a voltar ao diretório global.

### Passo a passo

::::WorkflowBlock
:::WorkflowBlockItem
**Abrir o diretório de Workspaces**

Na navegação global, abra "Workspaces". A página lista os espaços disponíveis para você; cada cartão informa o nome, a descrição (quando cadastrada) e os indicadores de Projetos, Tarefas e itens em andamento. Clique no cartão do Workspace que deseja operar para abrir a sua Visão geral.
:::

:::WorkflowBlockItem
**Criar um Workspace**

Se você ainda não tiver o espaço necessário, permaneça em /workspaces e clique em "Novo workspace". O formulário abre em uma janela: informe o nome obrigatório e, se desejar, uma descrição. O botão de criação só fica disponível quando o nome contém texto; espaços em branco não são aceitos.
:::

:::WorkflowBlockItem
**Confirmar a criação**

Envie o formulário. O criador é registrado como responsável inicial e o novo cartão aparece no diretório imediatamente com contagens iniciais zeradas. Para incluir outras pessoas, abra o Workspace e use o gerenciamento de membros disponível na Visão geral; a criação não tenta preencher projetos ou times automaticamente.
:::

:::WorkflowBlockItem
**Ler os cartões da Visão geral**

No Workspace selecionado, os quatro cartões de diretório ficam no alto da página. "Projetos" leva à lista de projetos; "Portfólios" abre a camada estratégica; "Times" mostra os times operacionais; e "ARTs" abre os trens Agile Release Train quando existem no espaço. O número exibido em cada cartão é carregado para aquele Workspace, não para toda a organização.
:::

:::WorkflowBlockItem
**Escolher um projeto recente**

Na seção "Projetos recentes", confira o nome e o código de cada projeto e, quando existirem, os times e ARTs associados. Clique no cartão para abrir a visão do projeto. O link "Ver todos" leva à lista completa quando o projeto que você procura não está entre os três mais recentes.
:::

:::WorkflowBlockItem
**Usar o grupo Workspace**

Na barra lateral, o grupo "Workspace" concentra "Visão geral", "Relatórios", "Projetos", "Times" e "ARTs" (o último aparece quando o Workspace possui ARTs ou enquanto a contagem ainda está sendo carregada). Use "Visão geral" para retornar ao diretório e "Projetos" para iniciar um fluxo de execução.
:::

:::WorkflowBlockItem
**Usar o grupo Estratégia**

O grupo "Estratégia" contém "Portfólios", "Produtos" e "Releases". Portfólios organizam investimento e épicos estratégicos; produtos e releases conectam a estratégia ao que será entregue. Todos os caminhos são escopados pelo id do Workspace selecionado.
:::

:::WorkflowBlockItem
**Usar o grupo Gestão**

Em "Gestão", abra "Metas", "Pessoas" ou "Financeiro". Metas representam objetivos organizacionais, Pessoas é o diretório de identidades e vínculos, e Financeiro reúne a consulta e a operação financeira do Workspace. A presença nesses menus não substitui as permissões de edição: cada tela ainda aplica a capacidade do usuário.
:::

:::WorkflowBlockItem
**Usar o grupo Sistema**

O grupo "Sistema" apresenta "Integrações" e, quando habilitada para a sessão, "Configurações". Integrações mantém o catálogo de adapters e proveniência; Configurações trata das preferências do Workspace. A barra lateral é navegação contextual, não uma fronteira de segurança: a API continua validando o acesso ao dado.
:::

:::WorkflowBlockItem
**Voltar ao diretório sem perder o contexto**

Use o item global "Workspaces" para trocar de espaço. Ao abrir outro cartão, a aplicação recalcula os quatro cartões, os projetos recentes e os caminhos da barra lateral para o novo id; não presuma que um projeto ou portfólio de um Workspace exista em outro.
:::
::::

:::hint{type="success"}
****:FontAwesome[****]{icon="fa-solid fa-check"}**&#x20;Verificação**

- O cartão do Workspace mostra o nome informado e contagens de Projetos, Tarefas e itens em andamento.
- A Visão geral exibe os quatro cartões de Projetos, Portfólios, Times e ARTs e permite abrir cada diretório.
- A seção Projetos recentes mostra cartões preenchidos com nome, código e vínculos quando existem.
- A barra lateral exibe os grupos Workspace, Estratégia, Gestão e Sistema, com caminhos que mantêm o Workspace selecionado.
:::

:::hint{type="warning"}
:FontAwesome[]{icon="fa-solid fa-triangle-exclamation"} Erros comuns

**O botão de criação não permite enviar o formulário**

O nome do Workspace é obrigatório. Remova espaços no início e no fim e informe pelo menos um caractere; a descrição é opcional.

**A lista ou a Visão geral apresenta erro de carregamento**

O diretório e a Visão geral fazem chamadas separadas para os dados agregados. Use o recarregamento da página depois de confirmar a conexão e que o Workspace ainda está disponível para sua sessão.

**O cartão de ARTs não aparece**

ARTs é condicional à existência de pelo menos um trem no Workspace. Crie ou associe um ART pelo fluxo de ARTs; até lá, use Projetos, Times e Portfólios normalmente.
:::

****

[title] Priorização por WSJF
[path] Aplicações/Agility/SAFe — Backlog e execução/

:::BlockQuote
Calcule e compare a prioridade relativa de Épicos e Features usando Weighted Shortest Job First.
:::

:::hint{type="info"}
**Pré-requisito:**

Tenha pelo menos um Épico ou uma Feature cadastrada no ART Backlog. O WSJF é aplicável a esses dois níveis; Histórias usam story points e a ordem da iteração.
:::

***

O WSJF (Weighted Shortest Job First) ajuda o ART a colocar primeiro o trabalho que entrega mais valor relativo em menor tamanho. No Agility, o cálculo é transparente: o painel mostra os quatro componentes usados e o resultado que foi persistido no item.

Os três primeiros componentes formam o Custo do Atraso (Cost of Delay): Valor de negócio, Criticidade no tempo e Redução de risco. O Custo do Atraso é dividido pelo Tamanho do job. O resultado é recalculado no cliente enquanto os chips são alterados e o servidor recalcula novamente ao salvar, mantendo a API como autoridade.

***

### Passo a passo

::::WorkflowBlock
:::WorkflowBlockItem
**Abrir o Backlog do ART**

Entre no ART e abra Backlog. Confira os indicadores de Features candidatas, Enablers, WSJF incompleto e PI candidato. Se um projeto vinculado ao ART estiver disponível para priorização, a tela oferece as visões Board e Tabela; quando a visualização Board está ativa, use o botão de ordenação WSJF quando precisar voltar à lista comparativa.
:::

:::WorkflowBlockItem
**Abrir a edição de uma Feature**

Na Tabela, localize a Feature pelo código e título e clique em Editar; no Board, abra o cartão e acione a edição. O mesmo formulário é usado para criar e refinar uma Feature e mantém os vínculos ao Épico, Times, responsável e PI candidato.
:::

:::WorkflowBlockItem
**Avaliar Valor de negócio**

No bloco de cálculo WSJF, escolha um chip de Valor de negócio na escala 1, 2, 3, 5, 8, 13 ou 21. Esse fator representa o benefício percebido por quem usa a entrega. Use valores maiores somente quando o benefício relativo justificar a posição de outras Features.
:::

:::WorkflowBlockItem
**Avaliar Criticidade no tempo**

Escolha a Criticidade no tempo. Ela representa quanto valor se perde se a Feature for atrasada. Uma urgência real, uma janela de mercado ou uma dependência de release podem justificar um valor maior; registre a decisão na descrição ou na rotina de priorização do ART para que ela possa ser revisitada.
:::

:::WorkflowBlockItem
**Avaliar Redução de risco**

Escolha Redução de risco para expressar o quanto a entrega reduz ameaças técnicas ou de negócio, ou cria conhecimento que diminui incerteza. Features habilitadoras frequentemente recebem atenção nesse fator, mas o valor deve refletir o impacto relativo e não o rótulo Enabler por si só.
:::

:::WorkflowBlockItem
**Avaliar Tamanho do job**

Escolha Tamanho do job no último grupo de chips. Ele é o divisor da fórmula e representa o esforço relativo para entregar o item. Como o painel usa a mesma escala fechada, não digite valores fora dela; ajuste a estimativa no refinamento do backlog quando o tamanho mudar.
:::

:::WorkflowBlockItem
**Ler o resultado em tempo real**

Após cada escolha, o campo Calculado mostra o WSJF formatado em pt-BR. A fórmula é (valor + criticidade + risco) ÷ tamanho do job. Por exemplo, fatores 5, 3, 2 e 3 produzem Custo do Atraso 10 e WSJF 3,33; o exemplo serve para entender a conta, não para substituir a avaliação do ART.
:::

:::WorkflowBlockItem
**Salvar e confirmar no detalhe**

Clique em Salvar. Ao reabrir o detalhe do Épico ou da Feature, o painel lateral WSJF lista Valor de negócio, Criticidade no tempo, Redução de risco e Tamanho do job, exibe a fórmula e destaca o número final. Se a API recalcular um valor diferente de uma edição local, considere o valor devolvido pelo servidor como o resultado válido.
:::

:::WorkflowBlockItem
**Ordenar o backlog**

Na lista do Backlog, alterne o comando de ordenação WSJF para comparar itens do maior para o menor resultado. Sem essa ordenação, a lista usa o rank do trem. O filtro por Time é aplicado antes da ordenação, portanto a comparação deve ser feita dentro do conjunto de Features que realmente pertence ao Time selecionado.
:::

:::WorkflowBlockItem
**Usar WSJF para a conversa, não como status**

Combine o resultado com situação, Épico pai, PI candidato, Times e dependências. O WSJF não move automaticamente a Feature para uma coluna, não cria uma História e não substitui o planejamento do PI. Ele oferece uma ordem relativa para decidir o que entra primeiro no planejamento.
:::
::::

:::hint{type="success"}
:FontAwesome[]{icon="fa-solid fa-check"} **Verificação**

- Os quatro fatores aparecem no painel e cada um tem exatamente os chips da escala 1, 2, 3, 5, 8, 13 e 21.
- O resultado Calculado muda imediatamente quando um chip é trocado.
- O detalhe mostra os fatores persistidos, o Custo do Atraso implícito na fórmula e o WSJF formatado em português.
- A ordenação WSJF coloca os resultados maiores antes dos menores na lista filtrada do Backlog.
:::

:::hint{type="warning"}
****:FontAwesome[****]{icon="fa-solid fa-triangle-exclamation"}**&#x20;Erros comuns**

**Confundir Custo do Atraso com WSJF**

O Custo do Atraso é a soma dos três primeiros fatores; o WSJF ainda divide essa soma pelo Tamanho do job. Compare o valor final do selo WSJF, não somente a soma.

**Alterar somente o tamanho para aumentar a prioridade**

O tamanho é o divisor e uma estimativa artificialmente baixa distorce a fila. Reavalie esforço relativo com o time e mantenha o valor escolhido na escala permitida.

**Esperar WSJF em uma História**

A tela de História informa explicitamente que a priorização acontece em Feature e Épico. Use story points e iteração para o nível executável.

**Resultado local diferente após salvar**

O servidor recalcula os campos derivados e pode devolver o valor persistido. Feche e reabra o detalhe para conferir os quatro fatores gravados e o resultado oficial.
:::


[title] Extras
[path] Aplicações/ERP/Manual do Usuário/

# Telas transversais e plataforma

:::BlockQuote
Pré-requisitos: [Administração](docId\:Z8SS7r6Bvhs09rP1SPxUD) e [Frota e Notificações](docId\:fNEUHaGVicgb22WmbN-Q8). Estas telas cruzam vários módulos — ajuda ter passado pelos cadastros e pela operação antes.
:::

## Introdução

***

Esta página reúne as telas do grupo **Início** do menu lateral — aquelas que não pertencem a um módulo de negócio específico (Compras, Vendas, Financeiro…), mas atendem a operação inteira. São a sua **página inicial** (o painel de resumo), a **caixa única de aprovações pendentes**, os **anexos** de documentos, e o conjunto de telas de **plataforma e segurança**: quem pode fazer o quê (*alçada*), quem está conectado, de quais redes o sistema aceita acesso, os controles de privacidade (LGPD) e o ajuste fino das notificações.

Você usa estas telas no dia a dia sem perceber que "trocou de módulo": abre o sistema e cai no painel; vê que há decisões esperando por você e as despacha pela caixa de aprovações; anexa um comprovante a um cadastro; e, quando é o responsável por segurança ou privacidade, gerencia sessões, faixas de IP, incidentes e pedidos de titulares. Todas ficam agrupadas no topo do menu, sob **Início**.

## Passo a passo

***

### Página inicial (painel de resumo)

1. **Abra o painel.** Clique em **Início → Início** no menu lateral (ou no logotipo). É a primeira tela ao entrar no sistema.
2. **Leia os números do topo.** Os cartões mostram, em tempo real, a contagem de parceiros, produtos, depósitos, requisições em aberto, aprovações pendentes e itens com estoque baixo. Cada cartão é um atalho: clicar abre a tela correspondente.
3. **Confira a posição financeira.** O gráfico de barras compara o saldo em aberto de contas a receber e a pagar; o gráfico de rosca mostra os documentos por situação (em aberto, parcial, baixado, cancelado).
4. **Aja pelo bloco "Precisa de atenção".** Estoque baixo, documentos vencidos, aprovações pendentes e requisições em aberto aparecem como linhas clicáveis que levam direto ao ponto de ação.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/001-home.png" alt caption width="3200" height="2000"}

### Aprovações pendentes (caixa única)

1. **Abra a caixa de aprovações.** Clique em **Início → Aprovações pendentes**. Ela reúne, numa lista só, tudo o que espera a sua decisão vindo de quatro origens: **Vendas**, **Crédito**, **Compras** e **Orçamento**.
2. **Filtre por origem.** Use as pastilhas no topo (Todos, Vendas, Crédito, Compras, Orçamento) — cada uma mostra a contagem de itens daquela categoria.
3. **Abra o item para decidir.** Cada linha traz o tipo, a descrição, o valor (ex.: R$ 1.250,00) e quando foi solicitado. O botão **Abrir** leva você à tela de origem, onde ficam os botões de aprovar/recusar daquele documento.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/002-approvals.png" alt caption width="3200" height="2000"}

:::BlockQuote
A caixa é apenas o **radar** das pendências; a decisão de aprovar ou recusar acontece na tela do próprio documento (o pedido de venda, a requisição de compra, etc.). A lista se atualiza sozinha a cada minuto.
:::

### Anexos (arquivos ligados a um cadastro)

1. **Abra a tela de anexos.** Clique em **Início → Anexos**. Ela é uma vitrine da capacidade de anexar arquivos que existe em várias telas do sistema (por exemplo, um comprovante no cadastro de um parceiro).
2. **Aponte o registro.** Informe o tipo de registro (ex.: partner) e o identificador do registro. Ao preencher os dois, a lista de anexos daquele registro aparece, com opção de enviar novos arquivos e baixar os existentes.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/003-attachments.png" alt caption width="3200" height="2000"}

:::BlockQuote
Na prática você quase sempre chega aos anexos **de dentro** da ficha de um cadastro (parceiro, documento fiscal, etc.), não por esta tela — ela existe para demonstrar e testar o recurso de forma isolada.
:::

### Alçada e permissões (quem pode o quê, até quanto)

1. **Abra as regras de alçada.** Clique em **Início → Alçada**. A tela lista as regras de *alçada*: para cada operação sensível, qual **cargo** pode executá-la e até que **valor teto**.
2. **Entenda a lista.** Cada linha mostra a operação (ex.: aprovar documento), o cargo autorizado, o teto em reais (ou "Ilimitado"), o *centro de custo* quando a operação é escopada por centro, e a situação (ativa/inativa).
3. **Veja o alerta de cobertura.** Um aviso no topo indica quantas operações sensíveis **ainda não têm regra** — sem regra, qualquer usuário autenticado pode executá-las. Clique em "Mostrar todas" para ver quais são.
4. **Crie ou ajuste uma regra.** Use **Nova regra** para adicionar; o lápis edita; o botão de situação ativa/desativa uma regra existente.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/004-authorization-rules.png" alt caption width="3200" height="2000"}

:::BlockQuote
O detalhe completo de como provisionar usuários, cadastrar cargos e delegar alçada está na [Administração](docId\:Z8SS7r6Bvhs09rP1SPxUD).
:::

### Sessões ativas (quem está conectado)

1. **Abra as sessões.** Clique em **Início → Sessões ativas**. A lista reúne quem está logado agora, com usuário, endereço de origem, início da sessão, última atividade e situação (ativa, expirada, encerrada); no ambiente de demonstração ela aparece vazia ("Nenhuma sessão para exibir") até que existam sessões abertas.
2. **Filtre por situação.** Use o seletor **Situação** para ver só as ativas, as expiradas ou as encerradas.
3. **Encerre uma sessão.** Numa sessão ativa, clique no botão de bloquear. O sistema pede confirmação — ao confirmar, aquele usuário é desconectado.
4. **Confira a política de tempo ocioso.** O link **Políticas de sessão** abre o ajuste do tempo máximo de inatividade antes de o sistema deslogar automaticamente.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/005-sessions.png" alt caption width="3200" height="2000"}

### Faixas de IP (de onde o sistema aceita acesso)

1. **Abra as faixas de IP.** Clique em **Início → Faixas de IP**. Aqui você restringe o acesso ao ERP a redes confiáveis.
2. **Cadastre uma faixa.** Informe a faixa de rede (ex.: 192.168.0.0/16), uma descrição (ex.: "Rede da matriz") e o modo: **Monitorar** (só registra quem vem de fora) ou **Bloquear** (recusa quem vem de fora).
3. **Comece por Monitorar.** Uma faixa nova entra como **Monitorar** por padrão, para você não se trancar para fora por engano; depois de conferir os registros, mude para **Bloquear**.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/006-ip-allowlist.png" alt caption width="3200" height="2000"}

:::BlockQuote
Uma lista vazia libera **todos** os IPs. O administrador da plataforma nunca é bloqueado, mesmo com uma regra de bloqueio ativa — é a proteção contra travar o próprio acesso.
:::

### Incidentes de dados (LGPD)

1. **Abra os incidentes de dados.** Clique em **Início → Incidentes de dados**. É o runbook de vazamento/incidente de dados pessoais previsto na LGPD (art. 48).
2. **Registre o incidente.** Informe quando foi detectado, a natureza (ex.: "Acesso não autorizado"), o nível de risco (Baixo, Relevante, Alto), a quantidade de titulares afetados e as medidas técnicas e de mitigação. O sistema calcula sozinho o **prazo de comunicação à ANPD** em dias úteis a partir da data de detecção.
3. **Conduza o incidente.** Ao gerenciar um incidente, você **avança a situação** (Registrado → Em análise → Comunicado → Encerrado) e **registra as comunicações** feitas (à ANPD ou aos titulares), com protocolo.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/007-data-incidents.png" alt caption width="3200" height="2000"}

### Direitos do titular (LGPD)

1. **Abra os direitos do titular.** Clique em **Início → Direitos do titular**. Aqui você atende os pedidos de titulares de dados pessoais previstos na LGPD (art. 18): **acesso**, **portabilidade**, **anonimização** e **eliminação**.
2. **Registre a solicitação.** Informe o identificador do titular (por CPF ou e-mail) e o direito solicitado. O sistema calcula o **prazo de resposta** e mostra quantos módulos já têm localizador de dados pessoais cadastrado.
3. **Processe ou recuse.** Ao gerenciar a solicitação, você a **processa** (o sistema localiza e trata os dados nos módulos cobertos) ou a **recusa** com um motivo. Dados que a lei obriga a reter aparecem listados como "dados bloqueados", com o prazo de retenção.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/008-data-subject-requests.png" alt caption width="3200" height="2000"}

### Modelos de notificação

1. **Abra os modelos.** Clique em **Início → Modelos de notificação**. Cada tipo de notificação do sistema tem um modelo de assunto e corpo, com versão por idioma (português, inglês, espanhol).
2. **Edite ou crie um modelo.** Use **Novo modelo** para adicionar; o botão de situação ativa/desativa um modelo existente. As notificações são disparadas por **eventos** do sistema (não há "enviar agora" avulso) — o modelo apenas define o texto que sai.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/009-notification-templates.png" alt caption width="3200" height="2000"}

### Falhas de envio de e-mail

1. **Abra as falhas de envio.** Clique em **Início → Falhas de envio de e-mail**. A lista reúne os e-mails de notificação que **não** conseguiram sair, com última tentativa, número de tentativas, motivo e situação (pendente, esgotada, resolvida). Quando está tudo em ordem — como no ambiente de demonstração — ela aparece vazia ("Nenhuma falha de envio — todos os e-mails de notificação saíram"), que é o estado saudável esperado.
2. **Reprocesse.** Numa falha ainda não resolvida, clique em **Reenviar** para tentar entregar de novo. O envio é assíncrono e já tenta sozinho algumas vezes; uma falha "esgotada" fica aqui até você reenviar manualmente.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/010-notification-delivery-failures.png" alt caption width="3200" height="2000"}

### Preferências de notificação

1. **Abra as preferências.** Clique em **Início → Preferências de notificação**. A tela é uma matriz: em cada linha, um tipo de notificação; em cada coluna, um canal (**E-mail** e **No sistema**).
2. **Ligue ou desligue por tipo e canal.** Cada célula é um interruptor. Por padrão todos os canais vêm **ligados** — desligue o que você não quer mais receber. A mudança salva na hora.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/011-notification-preferences.png" alt caption width="3200" height="2000"}

### Dicionário de dados (metadados do sistema)

1. **Abra o dicionário de dados.** Clique em **Administração → Dicionário de dados**. É a rotina própria da plataforma (referência técnica) que expõe o dicionário de dados do sistema: a lista de todas as **entidades** (as tabelas de negócio) com a contagem de atributos de cada uma.
2. **Filtre por módulo e busque uma entidade.** Use o seletor **Módulo** para ver só as entidades de um domínio (ex.: *finance*, *sales*, *inventory*) e o campo **"Buscar entidade"** para filtrar pelo nome (ex.: Partner, Product); um contador mostra **quantas de quantas** entidades estão listadas. A lista à esquerda mostra cada entidade com um selo indicando quantos atributos ela possui.
3. **Inspecione os atributos.** Clique numa entidade para abrir, à direita, o **nome técnico da classe** e a tabela de atributos — cada linha traz o **nome do atributo**, o **tipo** e o **mapeamento de persistência**. É a referência para quem precisa entender a estrutura de dados do ERP, sem sair do sistema.

### Chamados de suporte (falar com o suporte dentro do sistema)

1. **Abra os chamados de suporte.** Clique em **Chamados de suporte** no menu. A tela lista os chamados abertos com assunto, categoria, situação (**Aberto**, **Em andamento**, **Resolvido**, **Fechado**), quem abriu e a última atualização.
2. **Abra um chamado.** Clique em **"Abrir chamado"**, informe o **assunto**, escolha a **categoria** (ex.: técnico) e descreva o que você precisa. Envie — o chamado passa a constar na lista.
3. **Converse com o suporte.** Clique num chamado para abrir a conversa. Você e a equipe de suporte trocam mensagens ali mesmo, como um chat — as respostas do suporte aparecem destacadas. A equipe de suporte pode alterar a situação do chamado conforme o atendimento evolui. É o atendimento por chat/abertura de chamados feito diretamente na plataforma.

### Atalhos pessoais e abertura rápida (Ctrl+K)

Cada usuário pode criar apelidos para as telas que mais usa e abri-las digitando o apelido — sem passar pelo menu.

1. **Abra "Atalhos".** Menu **Início → Atalhos**. A lista traz os atalhos que você já criou, com apelido, rótulo e tela de destino.
2. **Novo atalho.** Informe o **apelido** (ex.: req), um **rótulo** amigável e a **tela de destino**. Salve.
3. **Abertura rápida.** Em qualquer lugar do sistema, pressione **Ctrl+K** para abrir a busca; digite o apelido (ou parte do nome da tela) e a tela é aberta na hora.

:::BlockQuote
Os atalhos são **individuais** — cada usuário monta os seus, e eles não interferem nos atalhos de outros usuários.
:::

### Ajuda on-line sensível ao contexto

Todas as telas do sistema têm um botão de ajuda no cabeçalho que abre um painel com orientação relativa à tela em que você está.

1. **Abra a ajuda.** Em qualquer tela, clique no ícone de ajuda no topo. O painel abre à direita.
2. **Leia a orientação da tela atual.** O texto é **específico da tela** em que você está — as 244 opções do menu têm o seu. Ele explica para que serve a tela, o que ela alimenta e onde se erra com mais frequência.
3. **Vá ao passo a passo quando precisar do detalhe.** O rodapé do painel leva à seção do manual que documenta aquela tela, quando ela já está documentada. A ajuda orienta; o manual ensina o procedimento.

:::BlockQuote
A cobertura tela a tela é verificada por teste automatizado: incluir uma opção no menu sem escrever a ajuda dela quebra o build. Se algum dia faltar, o painel ainda resolve para a orientação da **seção** de negócio e, por último, para uma orientação **geral** — nunca fica vazio.
:::

## Verificação

***

Você sabe que funcionou quando:

- Ao entrar no sistema, o **painel inicial** carrega com os cartões preenchidos e o bloco "Precisa de atenção" mostra as pendências reais da sua operação.
- Na **caixa de aprovações**, cada filtro mostra a contagem certa e o botão **Abrir** leva à tela onde a decisão é tomada.
- Em **Anexos**, ao informar tipo e identificador do registro, a lista de arquivos daquele registro aparece.
- Em **Alçada**, quem não tem a regra é bloqueado ("sem autorização") e quem tem passa; o alerta de cobertura some conforme você cria regras.
- Em **Sessões ativas**, encerrar uma sessão desconecta o usuário (a linha muda de "Ativa" para "Encerrada").
- Em **Faixas de IP**, uma faixa em modo **Bloquear** recusa acesso de fora da rede listada; em **Monitorar**, apenas registra.
- Em **Incidentes de dados** e **Direitos do titular**, o registro aparece na lista **com o prazo calculado**, e a situação avança conforme você conduz o caso.
- Em **Modelos**, **Falhas de envio** e **Preferências**, as mudanças salvam: o modelo fica ativo/inativo, a falha some ao ser reenviada com sucesso, e o interruptor de preferência mantém o estado escolhido.

## Erros comuns

***

- **A caixa de aprovações está vazia, mas há documento aguardando.** A caixa só mostra as quatro origens integradas (Vendas, Crédito, Compras, Orçamento). Se o documento é de outro fluxo, aprove pela própria tela dele.
- **"Sem autorização" ao tentar uma operação.** Falta uma regra de *alçada* para o seu cargo naquela operação, ou o valor está acima do seu teto. Peça a quem administra as regras ([Administração](docId\:Z8SS7r6Bvhs09rP1SPxUD)) para ajustar.
- **Fiquei sem acesso após criar uma faixa de IP.** Uma faixa em **Bloquear** recusa quem está fora da rede. Sempre valide em **Monitorar** antes de mudar para **Bloquear** — e lembre que o administrador da plataforma não é bloqueado, então use essa conta para corrigir.
- **O e-mail de notificação não chegou.** Verifique **Falhas de envio de e-mail**: se aparecer lá como "esgotada", corrija a causa (endereço, caixa cheia) e clique em **Reenviar**. Se o tipo estiver desligado em **Preferências de notificação**, religue o canal.

## Veja também

***

- [Glossário](docId\:iE0pyHH-ovGyrIUgMb7Gs): *Alçada*, *Centro de custo*, *CNAB*, *NFC-e*, *NFS-e*.
- [Administração](docId\:Z8SS7r6Bvhs09rP1SPxUD): provisionar usuários, cadastrar cargos, configurar alçadas avançadas, delegações e os fluxos completos de LGPD (consentimento, exportação, anonimização).
- [Frota e Notificações](docId\:fNEUHaGVicgb22WmbN-Q8): acompanhar as notificações in-app no dia a dia.

[title] Enterprise Agility Management
[path] Aplicações/

O <font color="#3b9f0f">**Agility**</font> é uma plataforma de gerenciamento de atividades que se destaca por sua simplicidade e agilidade, proporcionando uma maneira eficaz e intuitiva de administrar projetos. Desenvolvido com o objetivo de facilitar o dia a dia das equipes, o <font color="#3b9f0f">**Agility** </font>oferece uma gama completa de recursos que permitem **organizar, monitorar e delegar tarefas de forma eficiente**, seja em projetos coletivos ou em atividades individuais.&#x20;

Sua interface amigável torna o gerenciamento de projetos acessível a todos os membros da equipe, independentemente de seu nível de experiência. Com o <font color="#3b9f0f">**Agility**</font>, as equipes podem acompanhar o progresso das tarefas em tempo real, identificar gargalos, ajustar prioridades e garantir que os prazos sejam cumpridos.&#x20;

A plataforma é fundamentada em metodologias comprovadas, como **Kanban e SAFe (Scaled Agile Framework)**, que são reconhecidas por sua eficácia na gestão ágil de projetos. O Kanban oferece uma visão clara do fluxo de trabalho, permitindo que as atividades sejam visualizadas em um quadro intuitivo que facilita a identificação de etapas e a movimentação de tarefas conforme elas são concluídas. Já o SAFe, voltado para a escala ágil em grandes organizações, garante que o Agility seja uma solução robusta tanto para pequenas equipes quanto para organizações de grande porte que necessitam de coordenação entre múltiplas equipes e projetos.

Com o <font color="#3b9f0f">**Agility**</font>, as empresas podem alcançar um novo nível de organização e eficiência, tornando o gerenciamento de projetos uma tarefa mais simples, clara e produtiva.

[https://docs.citsmart.com/agility](https://docs.citsmart.com/agility)

[title] Riscos do ART (ROAM)
[path] Aplicações/Agility/SAFe — Backlog e execução/

:::BlockQuote
Registre riscos compartilhados do ART, calcule sua exposição e classifique o tratamento usando o modelo ROAM.
:::

:::hint{type="info"}
**Pré-requisito:&#x20;**

Tenha um ART e, preferencialmente, um PI atual. Para registrar ou classificar riscos é necessária uma sessão com capacidade de edição; em leitura, o board e o detalhe continuam disponíveis.
:::

***

O board de Riscos do ART é a visão de risco compartilhado do trem. Ele reúne riscos levantados para o PI, mostra a exposição calculada por probabilidade × impacto e mantém a decisão de tratamento visível para o ART. O filtro de Time permite concentrar a conversa no grupo afetado.

ROAM organiza o destino de cada risco: Resolvido, Assumido, Mitigado ou Aceito. Um risco recém-levantado entra deliberadamente como Não classificado para que não desapareça da pauta. A classificação é feita no detalhe, onde também se escolhe o responsável quando o tratamento for Assumido e se consulta o histórico de alterações.

***

### Passo a passo

::::WorkflowBlock
:::WorkflowBlockItem
**Abrir Riscos no ART**

Abra ARTs, selecione o trem e entre em Riscos. A página carrega os riscos do PI atual quando existe um PI corrente e também a lista de PIs do ART para o formulário. Os cartões de métrica exibem a contagem por tratamento; mantenha o filtro Todos para uma visão do trem inteiro ou selecione um Time.
:::

:::WorkflowBlockItem
**Entender as quatro colunas ROAM**

Leia as colunas Resolvido, Assumido, Aceito e Mitigado. Resolvido sai da contagem de riscos não resolvidos; Assumido indica que alguém aceitou a responsabilidade; Mitigado registra uma ação para reduzir a exposição; Aceito significa que o ART tomou a decisão consciente de conviver com o risco. O bloco Não classificado aparece separado quando há riscos aguardando decisão.
:::

:::WorkflowBlockItem
**Criar um risco compartilhado**

Clique em Novo risco. Informe Nome e Descrição, escreva a Categoria e escolha Probabilidade e Impacto de 1 a 5. Se o ART tiver mais de um PI, selecione o PI correspondente; em uma página travada no PI atual, esse campo aparece como somente leitura. Marque os Times afetados e confirme em Criar risco.
:::

:::WorkflowBlockItem
**Conferir a exposição**

O cartão usa a exposição calculada para contextualizar a decisão: exposição = probabilidade × impacto. Probabilidade 4 e impacto 5, por exemplo, resultam em exposição 20. Reavalie os números quando a evidência mudar; não trate a categoria textual como substituta da classificação quantitativa.
:::

:::WorkflowBlockItem
**Localizar o risco não classificado**

Após salvar, o novo risco aparece no bloco de pendências Não classificado, com código, nome e indicação de proprietário. Essa etapa é intencional: o diálogo de entrada não escolhe ROAM nem responsável, para manter a decisão explícita no board e evitar um tratamento presumido.
:::

:::WorkflowBlockItem
**Abrir o detalhe do risco**

Clique no cartão. O detalhe mostra nome, descrição, Categoria, probabilidade, impacto, exposição, PI e Times afetados. Em uma sessão somente leitura, os campos de classificação não são editáveis; em uma sessão de edição, o diálogo apresenta os controles de tratamento e proprietário.
:::

:::WorkflowBlockItem
**Classificar como Resolvido, Mitigado ou Aceito**

No campo de classificação, escolha Resolvido quando a ameaça deixou de existir, Mitigado quando ações reduziram o risco ou Aceito quando o ART decidiu conviver com ele. Salve a decisão. O cartão muda para a coluna correspondente e uma mensagem confirma código, tratamento e proprietário.
:::

:::WorkflowBlockItem
**Classificar como Assumido**

Para Assumido, selecione também um membro como proprietário. O Agility bloqueia o salvamento de um risco Assumido sem owner: a responsabilidade precisa ser explícita para que o tratamento seja acompanhado no PI.
:::

:::WorkflowBlockItem
**Usar o histórico**

Reabra o detalhe para consultar o histórico. Eventos de criação e classificação são apresentados com rótulos localizados e registram o ator e o tratamento escolhido. Use o histórico para conduzir a revisão do PI e descobrir quando um risco deixou de estar Não classificado.
:::

:::WorkflowBlockItem
**Revisar por Time e pelo PI**

Alterne o filtro de Time para confirmar que cada grupo afetado consegue encontrar seus riscos. Compare o board do PI atual com a lista de PIs do ART e reavalie riscos abertos na cerimônia de Inspect and Adapt. O objetivo é que os riscos ativos tenham um tratamento e um responsável coerentes com a situação atual.
:::

:::WorkflowBlockItem
**Diferenciar a Central de riscos**

A rota global Central de riscos é uma lente mais ampla de riscos de programas e produtos, com alternância Tabela/ROAM, escopo Todos/Programa/Produto e classificação de exposição. Para riscos compartilhados do trem, use a rota ART → Riscos descrita aqui: ela trabalha com ArtRisk, PI, Times afetados e a decisão ROAM específica do ART.
:::
::::

:::hint{type="success"}
:FontAwesome[]{icon="fa-solid fa-check"} **Verificação**

- O risco recém-criado aparece como Não classificado e não é automaticamente colocado em uma coluna de tratamento.
- A exposição exibida corresponde ao produto de Probabilidade e Impacto escolhidos entre 1 e 5.
- Depois de salvar uma decisão, o cartão aparece exatamente em Resolvido, Assumido, Mitigado ou Aceito.
- Um risco Assumido sempre exibe um proprietário atribuído.
- O histórico do detalhe registra a criação e as classificações realizadas.
:::

:::hint{type="warning"}
****:FontAwesome[****]{icon="fa-solid fa-triangle-exclamation"}**&#x20;Erros comuns**

**Nome ou categoria ausente**

A criação exige Nome e Categoria preenchidos. Se um dos dois estiver vazio, o diálogo mostra a validação e não cria o risco; informe um nome curto e uma categoria que ajude a agrupar a causa.

**Tentar salvar Não classificado**

Não classificado é o estado de entrada, não um tratamento final. Ao editar, escolha Resolvido, Assumido, Mitigado ou Aceito antes de confirmar.

**Assumido sem responsável**

O Agility rejeita Assumido sem owner. Selecione um membro no campo de proprietário e só então salve a classificação.

**Esperar que o risco do ART apareça na Central global**

A Central global e o board ART usam escopos e modelos de dados diferentes. Se a intenção é tratar risco do trem, retorne ao ART correto e abra Riscos; não procure a entrada na tabela global de programa/produto.

**Risco não aparece após filtrar um Time**

O filtro mostra somente riscos associados ao Time selecionado. Volte para Todos para verificar o conjunto completo e, se necessário, edite o risco para incluir o Time afetado.
:::


[title] Recrutamento e seleção
[path] Aplicações/ERP/Manual do Usuário/

## Introdução

***

Antes de existir vaga, alguém precisa autorizá-la. Hoje isso acontece por conversa, e-mail ou memorando: o gestor comenta que precisa de mais uma pessoa, o RH começa a procurar candidato, e a autorização vem depois — quando vem. Quando não vem, o processo é cancelado no meio e quem paga é o candidato, que já fez entrevista.

A **requisição de pessoal** é esse pedido, escrito: quem pede, para qual cargo e unidade, quantas vagas e **por quê**. Ela é o documento que o processo seletivo cita mais adiante — processo seletivo só nasce de requisição aprovada.

:::BlockQuote
**A justificativa não é campo de preenchimento.** Na contratação temporária (CF art. 37, IX) ela é o **próprio fundamento** da exceção legal que permite contratar sem concurso. É o primeiro campo que uma auditoria lê, e o TCU registra o uso indevido dessa hipótese como achado recorrente. Por isso o sistema recusa requisição sem justificativa, e a recusa diz para que ela serve.
:::

:::BlockQuote
**Quem decide não é esta tela.** A requisição vai para a **mesma caixa de aprovação** que a organização já usa em compras e pedidos — não há uma segunda máquina de aprovação para RH. É lá que ela é aprovada ou recusada, e é lá também que **aprovar a própria requisição é recusado**: quem pede não é quem autoriza.
:::

## Passo a passo

***

### Abrir uma requisição

1. **Abra "Requisição de pessoal".** Menu **Recursos humanos → Requisição de pessoal**. A lista mostra código, cargo, unidade, quantas vagas, situação, quem pediu e a data de abertura.
2. **Preencha o pedido.** Escolha o **cargo** e a **unidade**, informe **quantas vagas** e **quem está solicitando**. A justificativa é obrigatória — descreva o motivo real (substituição de quem saiu, ampliação de equipe, projeto com prazo).
3. **Salve.** A requisição nasce como **rascunho**, com um código no formato RP-\<ano>-\<sequência> — é assim que as pessoas vão se referir a ela.

### Enviar para aprovação

1. **Clique na linha da requisição** para selecioná-la. O bloco abaixo mostra o resumo e as ações disponíveis para a situação atual.
2. **"Enviar para aprovação".** A requisição passa a **aguardando aprovação** e aparece na caixa de aprovação de quem tem a alçada de autorizar contratação.
3. **A decisão chega sozinha.** Não é preciso avisar ninguém nem atualizar nada à mão: ao abrir a tela, o sistema busca o que foi decidido e a situação já aparece como **aprovada** ou **recusada**.

### Corrigir uma requisição recusada

1. **Recusa não apaga nada.** Selecione a requisição, use **Editar**, corrija o que motivou a recusa e envie de novo. Todo o histórico permanece — inclusive a versão que foi recusada.

### Marcar a vaga como preenchida

1. **Com a requisição aprovada**, use **"Vaga preenchida"** quando a contratação se concretizar. A partir daí a requisição está encerrada e não aceita mais alterações.

### Retirar uma requisição

1. **"Retirar"** encerra um pedido que não vai mais acontecer. Vale para rascunho, pedido em aprovação, aprovado e recusado — mas não para requisição já preenchida, que é fato consumado.

## Banco de talentos

***

Todo processo seletivo deixa para trás gente boa que não foi contratada porque havia uma vaga só. Sem um banco, esse resíduo se perde e a próxima vaga recomeça a busca do zero.

:::BlockQuote
**A parte desta tela que não é funcionalidade é responsabilidade.** Currículo de quem **não** foi contratado é dado pessoal guardado sem contrato de trabalho para justificá-lo. Por isso a **base legal** e a **data de guarda** são obrigatórias — e, vencida a data, o sistema **apaga** nome, documento e contato. Não é filtro: é a política acontecendo.
:::

### Cadastrar um candidato

1. **Abra "Banco de talentos".** Menu **Recursos humanos → Banco de talentos**.
2. **A data de nascimento não é enfeite de cadastro.** É o que o desempate por idade lê. Concurso com esse critério e candidato sem a data não empata a favor de ninguém — ele simplesmente cai para o fim do critério. Preencha na inscrição, não depois do resultado.
   **Preencha o que serve para achar a pessoa depois:** nome e contato, e os campos de triagem — **formação**, **cidade/UF**, **anos de experiência** e **pretensão salarial**. São escolha de lista e número justamente para a busca funcionar como comparação, e não como procura em texto livre.
3. **Diga como a pessoa chegou.** *Cadastrado pelo RH* (o currículo entregue na portaria, a indicação), *Candidatou-se pelo site* ou *Já é da casa*.
4. **Se já é da casa, aponte o colaborador.** O cadastro passa a referenciar a pessoa que já existe, em vez de criar uma segunda.
5. **Informe a base legal e até quando guardar.** A tela sugere dois anos à frente — é ponto de partida, não política: use o prazo que a sua organização definiu.
6. **Salve.** Cadastro sem base legal, sem data, ou com data já vencida é recusado.

### Achar alguém para uma vaga

1. **Use o bloco "Achar alguém para uma vaga".** Combine cidade, UF, formação, experiência e pretensão. **"Formação a partir de" significa aquele nível ou acima** — pedir superior não esconde quem tem doutorado.
2. **Quem venceu não aparece, e isso não é erro.** A busca e a lista só mostram quem ainda está dentro do prazo de guarda.

**"Mostrar todos"** volta para o banco inteiro.

### Apagar os dados de um candidato

1. **Selecione o candidato** e use **"Apagar os dados pessoais"** — é a resposta a um pedido de eliminação, e não tem volta. Nome, documento e contato somem; o registro dos processos de que a pessoa participou permanece, porque ele responde a outra base legal.
2. **Cadastro já anonimizado não aceita edição.** Preencher os campos de novo recriaria exatamente o dado que a organização declarou não ter direito de guardar.

## Processo seletivo

***

Prover uma vaga não é uma coisa só. Numa empresa, contrata-se pela CLT: anúncio, triagem, entrevistas, proposta. Num órgão público, a regra é o **concurso público** — prova, classificação, homologação e prazo de validade. E existe a **contratação temporária**, que é exceção.

São processos diferentes na regra e iguais no esqueleto: sempre há candidatos passando por etapas até sobrar quem será chamado. A tela monta esse esqueleto uma vez e mostra, de cada regime, só o que aquele regime tem.

:::BlockQuote
**A classificação do concurso não existe antes da homologação.** Não é "ainda não publicada": é não existir como fato jurídico. Enquanto o ato não for registrado, a tela avisa que qualquer ordenação é **provisória** — e ela não deve ser publicada como classificação final.
:::

### Abrir um processo

1. **Abra "Processo seletivo".** Menu **Recursos humanos → Processo seletivo**.
2. **Escolha a requisição.** A lista só traz requisições **aprovadas** — o processo nasce de uma contratação autorizada, e é para isso que a requisição existe.
3. **Escolha a forma de provimento.** *Concurso público*, *Seleção simplificada (temporária)* ou *Contratação CLT*. **Ela não muda depois**: alterá-la deixaria etapas, edital e candidaturas respondendo a regras que ninguém escolheu para elas.
4. **Se for concurso**, informe o **edital** — sem ele não há concurso —, e, se quiser, a data de publicação, a validade em meses e se haverá cadastro de reserva. Nos outros dois regimes esses campos nem aparecem.
5. **Informe o cargo, o nome do processo e o período de inscrição.** Salve.

### Definir as etapas

1. **Selecione o processo** e use o bloco **Etapas**. Não há conjunto fixo: etapas conforme o nível do cargo, então um cargo de motorista e um de procurador levam etapas diferentes.
2. **Se todas as etapas ficarem sem essas marcas, reprovar não elimina.** O candidato chega ao fim como aprovado, porque nada no processo disse o contrário.
   **Diga se a etapa é eliminatória, quanto ela pesa e qual é a nota de corte.** São os três campos que fazem o funil se comportar, e cada um decide uma coisa diferente:
   - **Eliminatória** — ser reprovado nela tira a pessoa do processo. Etapa não eliminatória reprovada deixa o candidato correndo.
   - **Peso** — entra no cálculo da nota final, que é a média ponderada. **Peso vazio significa porteira, não nota**: a etapa aprova ou reprova e não contribui para a classificação. Processo em que nenhuma etapa pesa não tem nota final nenhuma — e isso é honesto, porque não há o que somar.
   - **Nota de corte** — o piso da etapa.
3. **Sem ao menos uma etapa, as inscrições não abrem.** É o sistema recusando convidar candidato para um funil sem passos.

### Registrar o desempate

1. **Por que critérios e não uma frase.** Frase não se aplica — ela explica a um humano o que o sistema não fez. Em recurso, o órgão precisa mostrar que a ordenação é **reproduzível**, e isso exige que a máquina a tenha produzido.
   **Quem não tem o dado fica sempre por último**, nos dois sentidos. Não ter data de nascimento registrada não é qualificação, e nunca ganha posição de ninguém.
   **Idade normalmente é "menor primeiro".** A Lei 10.741/2003 art. 27 favorece o candidato mais velho, e mais velho é data de nascimento **menor**. Já anos de experiência costuma ser "maior primeiro".
   **Use o bloco "Desempate, na ordem".** Escolha o **sentido** — *menor primeiro* ou *maior primeiro* — e acrescente o critério. O sentido vale para o critério que você acrescentar em seguida, e cada um entra no fim da fila, que é a ordem em que serão aplicados.

### Conduzir e homologar

1. **"Abrir inscrições" → "Encerrar inscrições" → "Encerrar o processo"** acompanham o andamento.
2. **Concurso homologado sem ninguém aprovado grava uma lista vazia**, e isso é diferente de não ter gravado. O ato aconteceu, e o registro precisa dizer isso.

**A homologação congela a lista.** No instante do ato o sistema grava a classificação como ela está — colocação, nome e nota de cada um — e passa a mostrar a lista gravada em vez de recalcular. Isso importa porque os cadastros continuam vivos: a pessoa muda de nome, o prazo de guarda do candidato vence e o registro é anonimizado. Nada disso é erro, e todos mudariam uma lista que já foi publicada. Quando um recurso pedir a classificação anos depois, o que aparece é a que saiu.

**"Registrar a homologação"** (só no concurso) pede a **autoridade homologadora** e pratica o ato. A partir dele a classificação vira oficial e a validade começa a contar. **Não tem volta** — por isso é ação separada, e não um campo do formulário.

## Triagem, parecer e classificação

***

Aberto o processo, começa o trabalho de verdade: filtrar quem se encaixa, avaliar cada um em cada etapa e registrar **por quê**. Em processo público isso não é burocracia — é o que sustenta a decisão se alguém recorrer.

### Triar o banco de talentos

1. **A triagem mostra quem atende e não inscreve ninguém.** Você lê a lista e decide. Quem já está no processo, ou passou do prazo de guarda, fica de fora automaticamente.
   **Com o processo selecionado**, use o bloco **"Triar o banco de talentos"**. Combine cidade, UF, formação, experiência e pretensão.
2. **Marque quem deve entrar** e use **"Trazer os selecionados para o processo"**.
3. **Se o filtro não trouxe alguém que você quer**, marque assim mesmo e use **"Trazer como inclusão manual"**. A candidatura passa a registrar que a inclusão foi manual — "por que essa pessoa está no processo" é pergunta de recurso, e a resposta honesta às vezes é "alguém decidiu".

### Registrar parecer e nota

1. **Clique na linha do candidato** e preencha **etapa**, **avaliador**, **nota** e **resultado**.
2. **Reprovação exige parecer.** É o campo que sustenta a decisão se alguém recorrer, e o sistema recusa a reprovação sem ele.
3. **Reprovar em etapa eliminatória elimina o candidato**; em etapa não eliminatória, não. É o que a marcação de eliminatória, feita ao definir as etapas, quer dizer.
4. **A nota final é composta pelos pesos**, nunca digitada. Etapa sem peso não entra na média — ela é porteira, não nota.

### Anexar documentos

1. **Currículo, certificado, laudo, gravação de entrevista** ficam presos à candidatura de quem se referem, e respeitam os limites de tamanho e tipo já configurados no sistema.

### Ver a classificação

1. **Provisória não é rótulo, é o estado.** Em concurso público, enquanto não houver homologação, a ordenação pode ser lida e **não pode ser publicada** — e o botão de registrar a classificação só aparece depois do ato.
   **O bloco "Classificação"** mostra a ordem por nota, com o desempate aplicado na ordem definida.
2. **"Registrar a classificação"** grava a posição de cada candidato. Só existe quando a classificação é oficial.

### Candidato interno e admissão

1. **Por que o bloqueio é no começo e não na admissão.** Barrar só no fim seria tarde: a equipe que vai perder a pessoa descobre quando as entrevistas acabaram e a decisão já está socialmente feita.
   **Candidato que já é da casa** aparece na lista como *Interno*, e enquanto o **gestor atual** não concordar a candidatura **não avança** — nem para receber parecer.
2. **"Registrar a concordância do gestor"** libera o candidato interno para seguir no processo.
3. **Com a candidatura aprovada, use "Admitir como colaborador".** O sistema cria a ficha levando o que a seleção já coletou — nome, documento, contato, data de nascimento, cidade, formação e experiência. **Ninguém redigita.**
4. **Se a pessoa já é da casa, ela continua sendo a mesma pessoa.** O sistema não cria ficha nova: encerra o vínculo anterior no dia anterior ao início do novo e abre o novo no cargo e na unidade que a requisição autorizou. O histórico fica.
5. **Da ficha do colaborador dá para chegar ao processo que o selecionou**, e do processo dá para chegar à ficha. Na ficha, o bloco **"Admitido por processo seletivo"** só aparece para quem entrou por seleção — e leva direto ao processo, já selecionado. No processo, o bloco **"Admitido"** leva à ficha. Os dois lados são de leitura: quem confere um recurso navega sem precisar de permissão para escrever.

## Currículos vindos do site da organização

***

O edital pede que os currículos preenchidos no site do órgão cheguem ao banco de talentos sem ninguém redigitar. Repare no que isso **é** e no que **não é**: é uma importação — o site continua sendo do órgão, a página de vagas continua sendo do órgão, e o texto de consentimento que o cidadão lê é o do órgão. O ERP não hospeda nada disso. O que ele faz é responder ao site quais vagas estão abertas, e receber cada inscrição.

:::BlockQuote
**Quem conversa com o ERP é o site, não o candidato.** O site apresenta uma credencial de integração própria, com autorização apenas para três coisas: listar as vagas divulgadas, entregar um currículo e consultar a situação de uma inscrição. Essa credencial **não** abre o banco de talentos. Se ela vazar, ninguém lê o cadastro de ninguém.
:::

### Divulgar uma vaga no site

1. **Selecione o processo e use "Divulgar no site".** Só a partir daí ele aparece na lista que o site consome. Divulgar é decisão de comunicação, separada do andamento: um processo pode correr aberto por dentro sem estar anunciado, e **"Retirar do site"** tira a vaga do ar sem cancelar o processo.
2. **A vaga só aparece enquanto as inscrições estão abertas e dentro do prazo.** Processo encerrado ou fora da janela some da lista, e uma inscrição endereçada a ele é recusada. A faixa acima dos botões diz em qual dos casos o processo está.

### O que chega, e sob qual base legal

1. **Cada inscrição cria o candidato no banco de talentos com base legal "a pessoa consentiu" e a data do consentimento**, e abre a candidatura no processo. O prazo de guarda começa em dois anos — ponto de partida, não política: o analista pode encurtar no cadastro.
2.

**CPF inválido ou de enfeite não junta ninguém.** Se o site mandar 000.000.000-00, um traço ou um "N/A", o sistema trata como "sem documento" e abre registro novo. Fundir pessoas diferentes num cadastro só porque o formulário mandou o mesmo texto seria pior que duplicar.

**Quem já estava no banco não vira registro duplicado.** O sistema reconhece a pessoa pelo CPF, e o cadastro que o analista já vinha usando **não** é sobrescrito pelo que veio do formulário — só o consentimento e o prazo de guarda são renovados, porque a pessoa acabou de consentir de novo.

1.

**O código é entregue uma vez, no primeiro envio.** Se alguém enviar o formulário de novo com o CPF de outra pessoa, a resposta tem a mesma cara de sempre e o código que volta **não abre nada**. É proposital: saber o CPF de alguém não é prova de ser essa pessoa, e a porta não pode virar consulta de "fulano se candidatou aqui" nem de "como fulano está indo".

**O candidato recebe um código para acompanhar a própria inscrição.** Ele mostra apenas a situação — nunca nota, nunca parecer, nunca dado pessoal.

## Quanto a seleção custou, e quanto tempo levou

***

Duas perguntas que a área de RH costuma não conseguir responder com número: quanto tempo leva para preencher uma vaga, e quanto custa preencher uma vaga. Sem número, discussão de orçamento vira discussão de percepção.

O **tempo** o sistema calcula sozinho — ele conhece o dia em que a seleção abriu e o dia em que a admissão foi praticada. O **custo** ele não tem como adivinhar: é você que informa.

### Lançar o custo

1. **Com o processo selecionado, use o bloco "Quanto esta seleção custou".** Informe em que foi gasto, o valor, e **o dia em que o dinheiro saiu** — não o dia em que você está digitando. É essa data que o indicador usa para saber a que mês o gasto pertence; lançar com a data de hoje faz o número do mês passado mudar toda vez que alguém põe a papelada em dia.
2. **Por que o sistema não obriga.** Obrigar levaria você a escolher qualquer centro só para conseguir salvar — e alocação errada é pior que lacuna declarada, porque parece certa e ninguém adiante consegue perceber. O que o sistema **recusa** é centro que não existe, ou um centro **de resultado**: cobrar seleção num centro de resultado põe gasto onde a contabilidade espera receita.

**O centro de custo pode ficar vazio.** Nesse caso o custo entra como **não alocado**, e aparece destacado tanto na linha quanto no total acima da lista.

### Onde os dois números aparecem

1. **Não há painel próprio de recrutamento, e é de propósito.** Os dois entram no catálogo de indicadores da organização, junto com os demais — com meta, farol e histórico, como qualquer outro. Procure por **"Tempo médio para preencher uma vaga"** e **"Custo por contratação no período"**.
2. **Seleção cancelada sai do tempo e fica no custo.** Ela não produziu admissão nenhuma, então não tem duração para entrar na média; mas o dinheiro que consumiu foi gasto de verdade, e tirá-lo da conta esconderia justamente as tentativas que falharam — que são as que valem ser vistas.
3. **Mês sem nenhuma admissão não é mês de contratação instantânea.** O indicador de tempo mostra zero porque a coluna precisa de um número, mas a origem da apuração diz, em texto, que não houve admissão no período. Se o farol estiver verde, leia a origem antes de comemorar.
4. **Gasto sem contratação no período aparece como o gasto.** Não como zero e não como divisão por zero: um órgão que rodou o concurso em agosto e admite em setembro gastou em agosto, e é esse dinheiro que o gestor precisa ver.

## Verificação

***

- A requisição nasce como **rascunho** e recebe código RP-\<ano>-\<sequência>.
- Requisição sem justificativa é recusada, e a mensagem explica que ela é o fundamento da exceção legal.
- Requisição para **zero vaga** é recusada.
- Enviada, a situação vira **aguardando aprovação** e ela aparece na caixa de aprovação.
- Quem pediu **não consegue aprovar a própria requisição** — a caixa de aprovação recusa.
- Aprovada por outra pessoa, a situação vira **aprovada** ao reabrir a tela.
- **Editar uma requisição aprovada a devolve para rascunho**, e o aviso aparece **antes** de salvar.
- O bloco **Histórico desta requisição** mostra cada alteração com o antes e o depois.
- Candidato sem base legal, sem data de guarda, ou com data já vencida é recusado.
- Candidato marcado como **Já é da casa** sem colaborador escolhido é recusado.
- A busca por **formação a partir de superior** traz também quem tem pós, mestrado e doutorado.
- Candidato com prazo vencido **não** aparece na busca nem na lista.
- Depois de **Apagar os dados pessoais**, o nome vira um código, documento e contato somem, e o cadastro deixa de aceitar edição.
- Processo aberto em qualquer um dos três regimes usa as mesmas etapas e o mesmo desempate.
- Concurso sem edital é recusado; nos outros dois regimes o campo de edital não aparece.
- Concurso não homologado mostra o aviso de classificação **provisória**; homologado, mostra oficial com a data.
- Homologar duas vezes é recusado, e homologar um processo CLT também.
- Processo sem etapas não abre inscrições.
- A triagem devolve quem atende e **não** cria candidatura.
- Candidato já inscrito não aparece de novo na triagem.
- Inclusão manual fica marcada como tal na lista.
- Reprovação sem parecer é recusada.
- Reprovar em etapa **eliminatória** move o candidato para eliminado; em etapa comum, não.
- A nota final respeita os pesos: 80 com peso 3 e 40 com peso 1 dá 70.
- Concurso não homologado mostra a classificação como **provisória**, e registrar é recusado.
- Candidato interno sem concordância do gestor não recebe parecer — a recusa diz o que falta.
- Admitir um aprovado externo cria a ficha com nome, documento, contato, nascimento, cidade, formação e experiência vindos da candidatura.
- Admitir um aprovado que já é da casa **não** cria pessoa nova, e o vínculo anterior fica encerrado com data.
- Admitir alguém que não foi aprovado é recusado.
- Candidato sem documento não vira colaborador.

## Erros comuns

***

**"Preenchi tudo e o botão Salvar continua desabilitado."** Cargo, unidade e solicitante são escolhas de lista — se alguma ficou em "Selecione…", o botão não habilita.

**"Editei a requisição aprovada e ela voltou para rascunho."** É o comportamento correto, e o aviso amarelo diz isso antes de salvar. A autorização foi dada para um efetivo, um cargo e um custo; levá-la para outro conteúdo faria a aprovação dizer o que ninguém aprovou. Envie de novo.

**"Aprovei a requisição e o sistema recusou."** Quem pede não autoriza. Peça a decisão a quem tem a alçada — a mesma regra que já vale para compras e pedidos.

**"A lista está vazia."** Se o que apareceu foi um aviso de falta de acesso, e não a mensagem de lista vazia, o problema é de permissão: a tela é da alçada de quem responde pela estrutura da unidade.

**"Não consigo mais editar."** Requisição **preenchida** ou **retirada** está encerrada. Abra uma nova.

**"O candidato que cadastrei sumiu."** Confira a data de guarda. Vencido o prazo, ele sai da busca e da lista — e a varredura da madrugada apaga os dados pessoais. Não há como restaurar.

**"O sistema recusou o cadastro dizendo que o documento já está em uso."** Duas fichas para a mesma pessoa significariam dois prazos de guarda e dois consentimentos, e responder "o que vocês têm sobre mim" por qualquer uma delas seria responder errado.

**"Sou o encarregado de proteção de dados e não consigo editar o candidato."** É o desenho: o encarregado **lê** o banco inteiro e não altera nem apaga. Quem mantém o cadastro é o RH.

**"A requisição que eu queria não aparece ao abrir o processo."** A lista só traz as **aprovadas**. Se a sua está em rascunho ou aguardando, o processo ainda não pode nascer dela.

**"Escolhi o regime errado e não consigo trocar."** É proposital. Encerre ou cancele o processo e abra outro: trocar o regime deixaria as etapas e o edital pendurados em regras que não são as deles.

**"Homologuei e agora quero desfazer."** Não é possível. A homologação é ato formal, e a validade do concurso é contada a partir da data dela.

**"A triagem não trouxe um candidato que eu sei que existe."** Três motivos possíveis, nessa ordem: ele já está no processo, o prazo de guarda dele venceu, ou ele não atende a um dos filtros. O filtro de formação é "aquele nível **ou acima**".

**"O sistema não deixa reprovar."** Falta o parecer. É o único campo que a reprovação exige, e é o que sustenta a decisão num recurso.

**"A nota final ficou vazia."** Nenhuma etapa do processo tem peso. Etapa sem peso é porteira, não nota — e responder zero jogaria todo mundo para o fim de uma classificação que ninguém disputou.

**"Não consigo registrar a classificação."** Em concurso público ela é provisória até a homologação. Registre a homologação primeiro.

**"O candidato interno não aceita parecer."** Falta a concordância do gestor atual. É proposital, e é o que impede uma equipe de descobrir que perdeu alguém depois da mudança feita.

**"Admiti e não apareceu colaborador novo."** Se a pessoa já era da casa, é isso mesmo: ela continua a mesma, com o vínculo anterior encerrado e o novo aberto. Duas fichas para a mesma pessoa seriam duas histórias funcionais.

**"O sistema não deixa admitir por falta de documento."** O banco de talentos aceita candidato sem CPF — a captação pública registra a pessoa antes de qualificá-la —, mas ficha de colaborador não. Complete o cadastro antes.


[title] Cadastros gerais (parceiros e produtos)
[path] Aplicações/ERP/Manual do Usuário/

# Cadastros gerais (parceiros e produtos)

:::BlockQuote
Pré-requisitos: [Cadastro fiscal próprio](docId\:Q-zx6Qk4pMFD09yrhmsve) concluído (empresa e pelo menos a matriz).
:::

## Introdução

***

Antes de registrar qualquer compra, venda ou nota fiscal, o sistema precisa conhecer com **quem** você opera (clientes e fornecedores) e **o que** você compra/vende (produtos). Esta página cobre, no menu **Cadastros**, todo o núcleo de cadastros gerais: parceiros (pessoa jurídica e física, papéis, endereços, dados fiscais, crédito, contas bancárias e PIX), o mapa geográfico dos parceiros, produtos (com NCM, unidade, método de custeio e códigos de barras), grupos de produto em árvore, tabelas de preço com vigência e faixas de quantidade, e as regras fiscais por produto.

A mesma tela de parceiros aceita pessoa jurídica e pessoa física, e o mesmo registro pode acumular papéis (um parceiro pode ser cliente **e** fornecedor ao mesmo tempo). É um cadastro único: você não mantém "clientes" e "fornecedores" em telas separadas. Tudo o que você cadastrar aqui alimenta os módulos de Compras, Vendas, Estoque e Financeiro nas seções seguintes.

## Passo a passo

***

### Consultar e buscar parceiros

1. **Abra "Parceiros".** No menu lateral, em **Cadastros**, clique em "Parceiros". A tela abre com a lista "Parceiros cadastrados", trazendo as colunas **CNPJ / CPF**, **Nome / Razão social**, **Tipo de pessoa**, **Papéis** (Cliente, Fornecedor, Transportadora, Vendedor) e **Situação** (Ativo/Inativo).:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/012-partners.png" alt caption width="3200" height="2000"}
2. **Busque um parceiro.** Use o campo "Buscar por nome ou CNPJ/CPF..." acima da lista. A busca filtra pelo nome ou pelo documento. Clique nos cabeçalhos de coluna para ordenar (por documento ou por nome).
3. **Ações rápidas de cada linha.** À direita de cada parceiro há três ícones: o **lápis** abre a edição do parceiro; o ícone de **enriquecimento** consulta dados públicos do CNPJ; e o ícone de **bloqueio** inativa o parceiro (sem apagá-lo — o histórico é preservado). A seta **>** abre a ficha completa.

### Cadastrar um cliente (pessoa jurídica)

1. **Clique em "Novo parceiro".** No canto superior direito da lista. O formulário "Novo parceiro" abre em branco, dividido em blocos: **Dados gerais**, **Fiscal**, **Crédito** e **Comercial**.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/07-partner-empty.png" alt caption width="3200" height="2000"}
2. **Tipo de pessoa.** No bloco **Dados gerais**, deixe "Jurídica" (opção padrão).
3. **CNPJ + Razão social.** Digite o CNPJ (no manual usamos o cliente Cliente Exemplo Ltda). Clique em **"Consultar CNPJ"** para trazer automaticamente a razão social, o nome fantasia, a natureza jurídica e **o endereço** a partir de fonte pública — dependendo do CNPJ, alguns campos são preenchidos sozinhos. Se a consulta não retornar, digite manualmente (não bloqueia o salvamento).**Se o CNPJ for de empresário individual (o caso do MEI), a consulta avisa.** Aparece o painel **"Este CNPJ é de empresário individual"**, e o motivo é importante: nesse tipo de empresa a razão social **é o nome civil do titular**, ou seja, dado pessoal de pessoa identificada — não um nome de empresa. O campo continua se chamando "Razão social" e o valor parece qualquer outro, então sem o aviso não há como perceber. Salvar registra esse dado sob a base legal do cadastro de fornecedores; qualquer outro uso (mala direta, divulgação de lista, envio a terceiro) precisa da sua própria base. Órgão público contrata MEI com frequência, então esse caso chega pelo caminho normal e não como exceção. Duas coisas o sistema faz sozinho: se a fonte pública devolver o **CPF colado ao fim do nome** — acontece —, ele é removido antes de o valor chegar ao formulário, porque documento não é parte de nome nenhum; e **a consulta fica registrada na trilha de auditoria**, com quem consultou, quando, e se a resposta continha dado pessoal. Quem precisa dessa trilha a lê na tela **Log de auditoria**, filtrando a ação **Consulta**.Quando a consulta traz endereço, aparece o painel **"Endereço encontrado na Receita Federal"** com o endereço em uma linha e a caixa **"Gravar este endereço como principal ao salvar"**, já marcada. **Duas coisas acontecem ao salvar com ela marcada**, e vale saber a segunda: o endereço é gravado como principal (é ele que alimenta o mapa de parceiros e o cálculo de rota), **e** os campos que continuarem em branco no formulário são completados com os dados da Receita. Se você apagou um campo de propósito — um nome fantasia que a empresa não usa mais, por exemplo — **desmarque a caixa**, senão ele volta. Desmarcada, o cadastro grava exatamente o que você digitou, e o endereço continua podendo ser incluído depois na aba **Endereços** da ficha do parceiro.
4. **Papel.** Marque **"Cliente"**. Você pode marcar mais de um papel na mesma linha de caixas — **Cliente**, **Fornecedor**, **Transportadora** ou **Vendedor** — se o parceiro acumular funções.
5. **Dados complementares.** Preencha o **e-mail** (é obrigatório — o sistema recusa o salvamento sem ele) e, opcionalmente, nome fantasia, telefone e os campos do bloco **Fiscal** (regime tributário / CRT, classificação fiscal, inscrição estadual e municipal) e do bloco **Crédito** (score, rating, observações). **Atenção ao limite de crédito deste bloco:** ele é apenas informativo e **não** participa do bloqueio de crédito das vendas — o limite que a venda respeita é o da tela **Crédito do cliente**, que é a fonte da verdade. Enquanto o cliente não tiver um registro lá, ele **não tem limite avaliado** — o que não é a mesma coisa que estar dentro do limite: a consulta de crédito devolve um **aviso**, e não um "ok", e a venda segue. Se você quiser que esse caso pare para aprovação, ligue **"Exigir ficha de crédito"** na política de crédito (tela **Crédito do cliente**) — com ela ligada, toda venda a cliente sem ficha vai para a fila de aprovações de vendas (documentada no capítulo de Vendas). Ela nasce desligada de propósito: nenhum cliente nasce com ficha de crédito, então ligá-la manda para aprovação todas as vendas a clientes ainda não avaliados. O CNPJ/CPF é **único por empresa**: se você tentar cadastrar um documento que já pertence a outro parceiro, o sistema bloqueia com o aviso de que o documento já existe.
6. **Salve.** Você é redirecionado para a edição do parceiro recém-criado e aparece um check verde **"Salvo às HH\:MM\:SS"** ao lado do botão. O parceiro também passa a aparecer na lista.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/002-partners-detail.png" alt caption width="3200" height="2000"}

### Cadastrar um fornecedor

1. **Repita o processo** em "Novo parceiro" com outro CNPJ (no manual, Fornecedor Exemplo Ltda), marcando o papel **"Fornecedor"**. Ele aparece na lista com o papel "Fornecedor" na coluna **Papéis**.

### Cadastrar um cliente pessoa física

1. **Tipo de pessoa = Física.** No campo "Tipo de pessoa", troque para "Física". O rótulo do documento passa a aceitar CPF. Preencha nome completo e CPF.
2. **Endereço.** No bloco de endereço, informe o CEP (ex.: 01310-100) para autopreencher rua, bairro e cidade; complete número e complemento. O endereço é o que alimenta o mapa de parceiros (passo seguinte).

**Confira a precisão da coordenada.** Depois de salvar, cada endereço da lista mostra ao lado do alfinete **até onde a busca conseguiu chegar**: endereço (achou o logradouro **com** o número — é o melhor nível), rua (achou a rua, sem o número), bairro ou município. Os três últimos aparecem em âmbar de propósito: **município significa que o ponto é o centro da cidade e pode estar a quilômetros do endereço real**. Isso importa quando a coordenada vai ser usada de verdade — roteirização, despacho de serviço em campo, coleta — porque um alfinete de município manda a equipe para o lugar errado sem nenhum aviso.

Se a precisão não for a esperada, use o botão de **geocodificar de novo** (o ícone de alfinete ao lado do endereço). Ele fica disponível sempre, inclusive quando já existe coordenada — que é justamente o caso em que você precisa dele, porque a coordenada existente pode estar errada. Endereços cadastrados antes desta versão aparecem como precisão desconhecida: o sistema tem a coordenada, mas não registrou em que nível a obteve; geocodifique de novo para descobrir.

### Organizar parceiros em grupos

1.

💡 **Filiais da mesma raiz de CNPJ.** Na ficha de um parceiro pessoa jurídica, o cartão **"Filiais da mesma raiz de CNPJ"** lista os demais parceiros cadastrados sob os mesmos **oito primeiros dígitos** do documento — a matriz e suas filiais —, com link para abrir cada uma. O cartão **não aparece** quando o parceiro é o único sob aquela raiz, nem em pessoa física (um CPF não tem raiz). É a leitura complementar do grupo econômico: a raiz agrupa pelo documento, o grupo agrupa por decisão sua, e um cliente pode precisar dos dois.

💡 **E o caminho de volta: consultar por perfil.** Acima da lista de parceiros há quatro filtros que a percorrem no **servidor**, ou seja, respondem sobre a base inteira e não sobre a página que está na tela: **Porte**, **Potencial comercial**, **Grupo** e **Nº de funcionários (mínimo)**. Eles se combinam, e **Limpar filtros** zera todos de uma vez. O de porte é o que mais importa numa contratação pública: microempresa e empresa de pequeno porte têm tratamento favorecido por lei (LC 123/2006), e é por aqui que se responde "quais dos meus fornecedores são ME ou EPP". O de funcionários é **piso**, não igualdade — pedir 50 traz quem tem 50 ou mais; quem não tem o número preenchido fica de fora, porque não informado não é o mesmo que pequeno.

**Grupos de parceiros.** Ainda na tela "Parceiros", role até o painel **"Grupos de parceiros"** no rodapé. Informe o **Nome**, escolha o **Tipo** (ex.: "Grupo econômico") e uma **Descrição**, depois clique em **"Adicionar grupo"**. Depois, no cadastro de cada parceiro, o campo **"Grupo"** (no bloco Dados gerais) permite vincular o parceiro ao grupo criado — útil para consolidar clientes/fornecedores da mesma holding.

### Ver o mapa de parceiros

1. **Abra "Mapa de parceiros".** No menu **Cadastros**. Os parceiros que têm endereço cadastrado aparecem como pinos no mapa, geocodificados a partir do endereço. Use o mapa para visualizar a distribuição geográfica da sua carteira de clientes e fornecedores.



![](https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/013-partners-map.png)

### Contas bancárias e PIX do parceiro

Na ficha do parceiro (edição), a página **"Contas bancárias / PIX"** lista as contas do parceiro, usadas por exemplo no roteamento de pagamentos.

1. **Adicionar conta.** Informe nome da conta, banco (no manual, banco 341), agência 0001, conta 12345-6 e dígito; clique em **"Adicionar"**.
2. **Editar conta.** Clique no ícone de **lápis** na linha da conta — os campos são carregados no formulário e o botão passa a ser **"Salvar"** (use "Cancelar" para desistir). Dados que a tela não mostra (titular, validade) são preservados ao salvar.
3. **PIX com preenchimento automático.** Ao escolher o **Tipo PIX**, a **Chave PIX** é preenchida a partir do cadastro do parceiro: **CPF/CNPJ** → documento; **E-mail** → e-mail; **Telefone** → telefone no formato +55 + DDD + número. Você pode editar a chave depois, se precisar (no manual, a chave fiscal\@acme-exemplo.com).
4. **Remover conta.** Clique no ícone de **lixeira** na linha da conta.

### Contatos, anexos e histórico do parceiro

Ainda na ficha do parceiro (edição), abaixo dos dados principais, ficam três blocos usados no dia a dia do relacionamento: **Contatos**, **Anexos** e **Histórico de alterações**.



![](https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/018-partner-contacts-history.png)

1. **Cadastre múltiplos contatos.** No bloco **"Contatos"** você mantém quantos contatos precisar para o mesmo cliente/fornecedor (comprador, financeiro, responsável técnico…). Informe **Nome**, **Cargo**, **E-mail** e **Telefone** e clique em **"Adicionar"**. Cada contato pode ser editado ou removido na própria linha — é o cadastro de múltiplos contatos por parceiro.
2. **Anexe documentos.** No bloco **"Anexos"**, clique em **"Enviar arquivo"** e selecione o documento — contrato, imagem, PDF, planilha ou documento digitalizado. O anexo passa a constar na lista, com download. Use para guardar contratos e papéis do cadastro junto do parceiro.
3. **Consulte o histórico de alterações.** O card **"Histórico de alterações"** lista os eventos de auditoria do cadastro (criação, alteração, inativação) por **ator** e **data**. Clique num evento para abrir o painel com o **diff campo a campo** — o que mudou, de qual valor para qual. O histórico exige perfil com permissão de auditoria; para os demais perfis o card **não aparece** — o controle de acesso esconde a página, sem tela de erro nem 403.

### Bloquear pagamentos ao fornecedor

Na ficha de um parceiro que seja **fornecedor**, dois cartões travam pagamentos — e a diferença entre eles é o alcance. Ambos exigem a permissão de **aprovar documento**; sem ela os cartões aparecem só para leitura.

1. **Bloquear o pagamento de um fornecedor inteiro.** O cartão **"Bloqueio de pagamento"** trava a baixa de **todos** os títulos abertos daquele fornecedor de uma vez, inclusive os que ainda vão nascer. Informe o **motivo** e confirme; a ficha passa a exibir o selo de bloqueado e desde quando. **"Remover bloqueio"** libera.
2. **Bloquear só um fornecimento.** O cartão **"Bloqueio de um fornecimento específico"** trava apenas os títulos que carregam um determinado **documento de origem** — o contrato, o empenho ou o fornecimento em disputa. É o caso comum: você não quer parar o fornecedor inteiro, quer segurar uma entrega.
   - Informe o **documento de origem** exatamente como ele aparece no título (o sistema guarda em maiúsculas) e o **motivo**. Cada fornecimento bloqueado vira uma linha, com data e motivo, e **"Liberar o bloqueio"** desfaz.
   - Com o bloqueio ativo, tentar baixar um título daquele fornecimento é recusado com a mensagem apontando o documento de origem. Os demais títulos do mesmo fornecedor continuam pagáveis — é isso que separa este bloqueio do de cima.

### Personalizar a tela: esconder ou recolher seções

A ficha do parceiro reúne muitos blocos — dados gerais, endereços, contatos, anexos, histórico, consentimentos, avaliações de fornecedor. O sistema já **esconde os blocos que o seu perfil não tem permissão de ver**; mas, mesmo entre os que você pode ver, nem todos fazem parte do seu dia a dia. O botão **"Personalizar"** (canto superior direito, com o ícone de controles) deixa **cada usuário arrumar a própria tela**, sem depender de TI e sem código.



![](https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/020-partner-personalize-button.png)

Ao clicar em **"Personalizar"**, abre um painel à direita — **"Personalizar tela"** — listando **apenas as seções que você tem permissão de ver**. Para cada uma há dois controles:

- **Ocultar / Mostrar** — remove (ou traz de volta) a seção inteira da tela.
- **Recolher / Expandir** (a seta) — mantém a seção, mas mostra só o título; um clique no título reabre o conteúdo.
- **Restaurar padrão** (no rodapé do painel) — descarta as suas preferências desta tela e volta ao layout completo.



![](https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/021-partner-personalize-drawer.png)

As escolhas são **salvas por usuário** e valem nas próximas vezes que você abrir a tela — inclusive em outro computador. Elas **nunca revelam** uma seção que a sua permissão não libera: o controle de acesso continua acima da personalização, então uma seção que o seu perfil não pode ver não aparece nem na tela, nem nesta lista de personalização.

:::BlockQuote
A personalização por usuário está disponível na ficha de **parceiros** e nas demais telas de detalhe (produtos, contas bancárias, bens patrimoniais, títulos, processos jurídicos, orçamentos, imóveis, requisições de compra, grupos de produto e modelos de notificação). Além disso, um **administrador** pode definir o padrão de seções **por cargo ou para toda a organização** em **Administração → Padrões de seção** — e a escolha de cada usuário **sempre prevalece** sobre esse padrão.
:::

O mesmo botão "Personalizar" aparece nas demais telas de detalhe. Abaixo, na ficha de **produto**, o painel lista as seções daquela tela (o histórico só aparece para quem tem permissão de auditoria):



![](https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/023-product-personalize-drawer.png)

Para o administrador, a tela **Administração → Padrões de seção** define, por tela e por **cargo** ou **toda a organização**, quais seções já vêm escondidas ou recolhidas por padrão:



![](https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/022-admin-section-defaults.png)

### Unidades de Negócio e dados comerciais do parceiro

1. **Vincule Unidades de Negócio.** Quando a empresa opera com várias **Unidades de Negócio** (com regimes tributários, alíquotas e tratamentos contábeis próprios), o mesmo cliente pode ser atendido por mais de uma. No cadastro do parceiro, use o multi-select **"Unidades de Negócio"** para marcar quais unidades atendem esse cliente; nas vendas, o pedido resolve a unidade que atende e aplica o regime/alíquota dela. As unidades são cadastradas em **Administração → Unidades de Negócio**.
2. **Preencha o bloco Comercial.** O bloco **"Comercial"** guarda o **porte**, o **potencial de compra**, o **tipo** e o **nº de funcionários** (perfis de segmentação do parceiro) e a **Forma de pagamento** padrão — que é **sugerida automaticamente** nas movimentações de venda desse parceiro. Preencha e salve.

### Cadastrar grupos de produto

1. **Abra "Grupos de produto".** No menu **Cadastros**. A tela mostra a **árvore de grupos** — a hierarquia usada para classificar produtos e herdar configuração contábil. Se ainda não houver grupos, aparece "Nenhum grupo de produto cadastrado ainda".



![](https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/015-product-groups.png)

1. **Novo grupo.** Clique em **"+ Novo grupo"**, informe o nome e a posição na hierarquia. Os grupos ficam disponíveis para escolha ao cadastrar produtos e servem para organizar os itens em famílias.

### Cadastrar um produto

1. **Abra "Produtos".** No menu **Cadastros**. A lista "Produtos" traz as colunas **Código (SKU)**, **Descrição**, **Grupo**, **Tipo** (Produto, Serviço, etc.), **Rastreio** (Lote/Série/Validade, quando aplicável) e **Situação**. Use o campo "Buscar..." para localizar um item.



![](https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/014-products.png)

1. **Novo produto.** Clique em **"Novo produto"** e preencha:
   - **Código (SKU)** (ex.: PROD-001).
   - **Descrição** (ex.: Notebook ACME 14 polegadas).
   - **Grupo** — escolha um dos grupos cadastrados no passo anterior (opcional).
   - **Tipo** — Produto físico, Serviço, mercadoria revendida, etc.
   - **NCM** — **é obrigatório** e validado por formato: o produto não é salvo sem um NCM válido. Comece a digitar o código ou a descrição (ex.: notebook ou 8471). O campo abre uma busca que vai mostrando as opções conforme você digita; selecione a entrada certa da lista (ex.: 8471.30.12 — Máquinas automáticas para processamento de dados, portáteis). A lista é paginada; role para ver mais resultados. Suas últimas escolhas ficam no topo na próxima vez (atalho da sessão).
   - **CEST** — quando o NCM está sujeito a substituição tributária, escolha o CEST correspondente; caso contrário o campo indica "NCM não sujeito a ST".
   - **Unidade** — busque por sigla (UN, KG, M, L) ou descrição (Quilo, Litro). Selecione da lista.
   - **Rastreio** — marque **Lote**, **Série** e/ou **Validade** se o item precisa ser rastreado no estoque.



![](https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/003-products-detail.png)

1. **Salve.** Ao salvar, a ficha ganha as seções complementares:
   - **Custeio** — mostra o **método de custeio resolvido** do produto (ex.: "Custo médio ponderado móvel"), herdado do padrão da empresa. É o que rege a valorização do estoque.
   - **Classificação STN** (setor público) — se o item for material de consumo com padrão STN, informe natureza da despesa, conta PCASP de estoque e conta PCASP de VPD, e clique em **"Salvar classificação"**. Órgãos privados podem ignorar.
   - **Códigos** — use **"+ Adicionar código"** para registrar códigos de barras / GTIN adicionais do produto.
2. **Duplicar (opcional).** Para cadastrar um item parecido, abra um produto existente e clique em **"Duplicar produto"** — abre um novo com os mesmos dados para você ajustar.
3. **Verifique.** O produto fica disponível para pedidos de compra, pedidos de venda e movimentos de estoque (testaremos isso nas seções 06 e 08).

### Criar e operar uma tabela de preço

1. **Abra "Tabelas de preço".** No menu **Cadastros**. A tela lista as "Tabelas de preço cadastradas" — listas de preço de venda e de fornecedor, com vigência e segmentação. Se ainda não houver nenhuma, aparece "Nenhuma tabela de preço cadastrada ainda".



![](https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/016-price-tables.png)

1. **Nova tabela.** Clique em **"Nova tabela de preço"**, dê um nome, defina a **vigência** (data de início/fim) e o público-alvo (segmentação). Salve e abra a tabela para adicionar itens.
2. **Adicionar item e preço.** Na tabela aberta, adicione o produto e informe o **preço** (e o **piso**/preço mínimo, se aplicável). Cada produto aparece como uma linha da tabela.
3. **Reajustar preços.** No card **"Reajustar preços por percentual"**, informe o percentual e clique em **"Pré-visualizar reajuste"** — a prévia mostra, item a item, o preço atual e o novo, e só depois de conferir você aplica.**Reajuste por índice econômico.** Logo abaixo, em vez de calcular na mão, você pode **trazer o percentual de um índice** já cadastrado na Tesouraria (IPCA, SELIC, CDI, TR): escolha o **índice** e o **período**, clique em **"Buscar do índice"** e o percentual acumulado preenche o campo acima. Três coisas que vale saber:
   - A variação é **composta**, não somada: 1% seguido de 2% dá **3,02%** — é justamente o erro comum de quem faz a conta à mão.
   - Se o índice **não tiver cotação** no período informado, o sistema **avisa e não reajusta** — em vez de aplicar 0% em silêncio.
   - **Deflação** funciona: variação negativa reduz os preços.
4. **Importar planilha CSV (em massa).** Quando você precisa criar ou atualizar muitos preços de uma vez (onboarding com muitos SKUs, reajuste anual, sazonalidade preparada em planilha), use o card **"Importação em massa por CSV"** abaixo da lista de itens:
   - Clique em **"Baixar modelo"** para obter um CSV com cabeçalho internalCode,price,minPrice e uma linha de exemplo.
   - Edite no Excel/LibreOffice e salve como **CSV UTF-8**.
   - Selecione o arquivo e clique **"Pré-visualizar mudanças"**. O sistema mostra cada linha com a ação prevista (criar, atualizar ou erro) num painel com caixa de seleção por linha. Linhas com erro (produto não encontrado/inativo) vêm desabilitadas.
   - Desmarque o que não quer aplicar e clique **"Aplicar a N itens"**. Limite: 5000 linhas por arquivo.
5. **Cadastrar faixa de quantidade.** Para vendas de atacado ("a partir de X unidades, o preço cai"):
   - Na lista de itens, clique no triângulo **▸** ao lado do produto para expandir o subpainel "Faixas de quantidade".
   - Clique **"Adicionar faixa"** e digite Quantidade mínima + Preço (+ Piso opcional).
   - O sistema valida que cada item tem no máximo uma faixa por quantidade mínima e que o piso não pode passar do preço.
   - Quando uma versão da tabela é publicada, as faixas configuradas viram parte do registro histórico (o preço fica congelado para auditoria).

### Cadastrar rotas de venda e cobrar preço por rota

Uma **rota** é o agrupamento comercial dos clientes que o vendedor ou a entrega percorre num mesmo circuito ("Litoral", "Serra", "Capital"). Ela serve para você definir um preço uma única vez **para a rota inteira**, em vez de repetir o mesmo preço cliente a cliente. É só um rótulo de agrupamento — não é roteirização de entrega (sequência de paradas, mapa, otimização).

1. **Abra "Rotas".** No menu **Cadastros**. A tela abre com o subtítulo "Rotas de venda para segmentar tabelas de preço" e lista as rotas nas colunas **Código**, **Nome** e **Situação** (Ativa/Inativa). Enquanto não houver nenhuma, aparece "Nenhuma rota cadastrada".
2. **Cadastre a rota.** Clique em **"Nova rota"**, informe o **Código** (no manual, LIT) e o **Nome** ("Litoral"), deixe **"Ativa"** marcada e salve. O código é convertido para maiúsculas e é **único**: se você repetir um código já usado, o sistema recusa o cadastro. Na lista, o **lápis** reabre a rota para edição e o ícone ao lado a **desativa** (com a confirmação "Desativar esta rota?"); rotas inativas continuam na lista, em cinza, e deixam de ser oferecidas nos próximos passos.
3. **Ligue o cliente à rota.** Abra o parceiro (ver "Cadastrar um cliente (pessoa jurídica)", acima) e, no bloco **Dados gerais**, use o campo **"Rota"** — logo abaixo de "Grupo". O combo lista as rotas ativas no formato CÓDIGO — Nome; o padrão é **"Sem rota"**. Cliente sem rota não é erro: a segmentação por rota simplesmente não se aplica a ele.
4. **Aponte a tabela de preço para a rota.** Abra a tabela de preço e, no card **"Segmentação"**, escolha a **Dimensão** = **"Rota"**. O campo **Referência** vira um seletor ("Selecione uma rota") que lista **apenas as rotas ativas** — você escolhe pelo nome, não digita código. Clique em **"Adicionar segmento"**.
5. **Entenda qual preço vence.** Ao montar um orçamento, o sistema sugere a tabela **mais específica** que se aplica ao cliente, nesta ordem: **cliente → rota → perfil → estado → região**. Ou seja: se o cliente tem uma tabela só dele, ela prevalece sobre a da rota; se não tem, ele herda o preço da rota.

### Definir regras fiscais por produto

1. **Abra "Regras fiscais por produto".** No menu **Cadastros**. A tela lista as "Regras cadastradas" com as colunas **Escopo**, **Operação** (Entrada/Saída), **UF orig.**, **UF dest.**, **CFOP** e as alíquotas de **ICMS**, **IPI**, **PIS** e **COFINS**.



![](https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/017-product-fiscal-rules.png)

1. **Nova regra.** Clique em **"+ Nova regra"** e defina:
   - **Escopo** — a regra pode valer como padrão da operação ou ser filtrada por NCM específico (ex.: "Filtro por NCM: 84713012").
   - **Operação** — Saída (venda) ou Entrada (compra).
   - **UF de origem e destino** — ex.: SP → RJ.
   - ***CFOP*** — ex.: 6102.
   - **Alíquotas** — ICMS, IPI, PIS e COFINS aplicáveis à combinação.
2. **Salve.** A regra passa a ser usada na apuração dos impostos ao emitir a nota fiscal (*NF-e*). Use o **lápis** para editar e a **lixeira** para remover uma regra da lista.

### Definir regras fiscais de serviço (ISS)

Produto e serviço tributam por eixos diferentes: produto por NCM/CFOP (item anterior), serviço pelo **código da Lei Complementar 116/03**. Quem emite NFS-e cadastra a regra aqui.

1. **Abra "Regras fiscais de serviço (ISS)".** No menu **Cadastros**. A tela tem três blocos: o formulário da regra, o bloco **"Qual regra vale?"** e a lista **"Regras cadastradas"**.
2. **Preencha a regra.**
   - **Serviço (opcional)** — deixe em branco para a regra valer para **todo** serviço com aquele código da LC 116. Uma regra com serviço informado **vence** a genérica do mesmo código.
   - **Código do serviço (LC 116)** — ex.: 7.01 (consultoria), 1.05 (análises e testes).
   - **Código nacional da LC 116** — repita o de cima quando não houver diferença.
   - **Código de tributação municipal (CTM)** — o catálogo é de cada prefeitura; opcional.
   - **Alíquota de ISS (%)** — digite em **porcentagem**: 5 para 5%.
   - **ISS devido ao município** — do **prestador** ou do **tomador** (LC 116 art. 3).
   - **Retido pelo tomador** — marque ISS, PIS, COFINS, CSLL e IR conforme o contrato.
3. **Confira antes de emitir.** No bloco **"Qual regra vale?"**, digite o código do serviço e clique em **"Conferir"**. Ele consulta o **mesmo** resolvedor que a NFS-e usa, e responde a alíquota que sairia no documento.
4. **Salve.** Use o **lápis** de uma linha para trazê-la de volta ao formulário e a **lixeira** para encerrá-la.

**Duas armadilhas que valem mais que o passo a passo:**

- **A alíquota é limitada por lei a 2%–5%** (LC 116 art. 8). Fora dessa faixa o sistema recusa com "SERVICE\_FISCAL\_RULE.ALIQ\_ISS\_OUT\_OF\_RANGE" — não é defeito da tela.
- **Sem nenhuma regra ativa, a NFS-e sai assim mesmo** — levando a alíquota **padrão do sistema**, não uma cadastrada por você. Não há aviso na emissão: a nota é transmitida normalmente. É por isso que o bloco "Qual regra vale?" existe, e é por isso que a lista vazia diz o que diz.

## Verificação

***

Você sabe que funcionou quando:

- O parceiro aparece na lista de "Parceiros" com o nome e CNPJ/CPF que você digitou e o(s) papel(is) certo(s) na coluna **Papéis**.
- O check verde **"Salvo às HH\:MM\:SS"** apareceu após cada salvamento.
- Ao buscar pelo nome ou documento, o parceiro recém-cadastrado aparece na lista filtrada; parceiros com endereço aparecem como pinos no **Mapa de parceiros**.
- O produto aparece na lista de "Produtos" com o Código (SKU), a Descrição e o Tipo corretos, e pode ser selecionado em um pedido de compra ou venda.
- A tabela de preço aparece na lista "Tabelas de preço cadastradas" com o item e o preço; a importação CSV mostra "Aplicar a N itens" com o número esperado de linhas.
- A rota aparece na lista de "Rotas" com o código em maiúsculas e a situação **Ativa**; ela pode então ser escolhida no campo "Rota" do cliente e no seletor da dimensão "Rota" da segmentação da tabela de preço.
- A regra fiscal aparece na lista "Regras cadastradas" com o CFOP e as alíquotas informadas.
- A regra fiscal de serviço aparece na lista com o código da LC 116 e a alíquota em porcentagem; o bloco "Qual regra vale?" responde essa mesma alíquota para o código consultado.

## Erros comuns

***

- **"Documento inválido"** (aparece abaixo do campo CNPJ/CPF) — o número digitado tem dígitos verificadores errados. Confira ou cole de uma fonte oficial. Enquanto estiver inválido, o botão "Consultar CNPJ" não traz dados.
- **"Já existe um parceiro com o documento…"** — o CNPJ/CPF é único por empresa e já pertence a outro parceiro. Em vez de recriar, abra o parceiro existente e acrescente o papel que faltava (o mesmo cadastro pode ser cliente **e** fornecedor).
- **E-mail obrigatório** — o salvamento do parceiro é recusado se o e-mail estiver em branco. Preencha um e-mail válido antes de confirmar.
- **"Preencha os campos exigidos pelas declarações obrigatórias: … (exigido por: …)"** — sua empresa configurou, em **Administração → Campos obrigatórios por declaração**, campos que uma declaração (SPED, EFD, NF-e) exige. A mensagem diz **quais** campos e **qual** declaração os pede. Quando os campos listados são de endereço (street, number, district, city, zipCode, state), a exigência vale também para **existir** um endereço: salvar a **edição** de um parceiro que não tem nenhum endereço cadastrado é recusado, e o **último** endereço não pode ser removido — a aba **Endereços** recusa a exclusão com a mesma mensagem. Cadastre o endereço na aba **Endereços** e salve de novo. **A criação inicial não é barrada**, e isso é de propósito: o endereço é um cadastro filho, que só existe depois que o parceiro existe — então "Novo parceiro" salva normalmente e a exigência aparece no salvamento seguinte da ficha. Se a exigência não deveria valer, quem administra pode desligá-la naquela tela (a regra fica registrada, com histórico de quem ligou e quando).
- **Razão social não autopreenche ao "Consultar CNPJ"** — a consulta pública pode estar indisponível ou o CNPJ é muito recente. Digite manualmente — não bloqueia o salvamento.
- **NCM não aparece na busca** — refine o termo. Pode buscar por código completo (8471.30.12), por raiz (8471) ou por descrição (portátil, notebook). Se o catálogo NCM ainda não foi populado, peça ao administrador para rodar o seed de catálogos fiscais.
- **Produto não salva por falta de NCM** — o NCM é obrigatório e validado por formato. Sem um NCM válido selecionado da lista, o cadastro é recusado. Selecione a classificação correta antes de salvar.
- **SKU (código interno) já existe** — o código do produto é único; o sistema bloqueia o cadastro de um SKU repetido. Use outro código ou edite o produto já existente.
- **Código de barras / GTIN recusado** — o sistema confere o dígito verificador (mod-10) do GTIN/EAN no momento do cadastro e rejeita códigos com dígito errado. Confira o número na embalagem ou em fonte oficial.
- **Unidade de medida não aparece** — mesmo procedimento do NCM (busca por sigla ou descrição). Se faltar uma unidade específica, cadastre-a em **Administração → Catálogos fiscais → Unidades de medida**.
- **Importação CSV com linhas em "erro"** — a linha referencia um produto que não existe ou está inativo pelo internalCode. Corrija o código na planilha ou cadastre/reative o produto antes de reimportar.
- **Piso maior que o preço na faixa de quantidade** — o sistema recusa a faixa. Ajuste para que o piso (preço mínimo) seja menor ou igual ao preço.
- **Código de rota já existe** — o código da rota é único e é gravado em maiúsculas (lit e LIT são o mesmo código). Use outro código ou edite a rota existente.
- **A rota não aparece no combo do cliente ou na segmentação da tabela** — ela está **inativa**. Abra "Rotas", reative-a pelo ícone da linha e tente de novo.


[title] Despesas corporativas
[path] Aplicações/ERP/Manual do Usuário/

## Introdução

***

O módulo de **Despesas corporativas** cobre o ciclo de gastos que os colaboradores fazem em nome do órgão — a viagem, o cartão corporativo, o pequeno reembolso — do "gastei" até "foi conferido, aprovado e virou conta a pagar". Ele reúne quatro telas encadeadas: **Cartões corporativos** (cadastra os cartões dos portadores e importa a fatura do emissor), **Políticas de despesa** (as regras de teto e comprovante que o sistema aplica sozinho, mais a configuração de reembolso automático), **Relatórios de despesa** (a prestação de contas propriamente dita — lançar as despesas, submeter, aprovar e liquidar) e **Adiantamento de viagem** (o dinheiro adiantado para a viagem e a prestação de contas depois). Todas essas telas vivem no menu **Financeiro**, exceto o catálogo de naturezas, que fica em **Contábil**.

A ideia central é ter **uma visão única e consolidada** das despesas, sem redigitar o mesmo gasto em vários lugares: a fatura do cartão entra por arquivo, a prestação de contas aprovada vira reembolso e conta a pagar, e cada movimento fica registrado no histórico de auditoria. O sistema ainda aplica as **políticas corporativas automaticamente** na submissão (bloqueando ou avisando quando um gasto estoura o teto ou está sem comprovante) e conta com **apoio de IA** para sugerir a categoria de um gasto, revisar o relatório antes de aprovar e destacar padrões de consumo. Você usa este módulo sempre que precisa controlar gastos de viagem, cartão corporativo e reembolsos a colaboradores.

## Passo a passo

***

### Cadastrar cartões corporativos e importar a fatura

1. **Abra "Cartões corporativos".** Menu **Financeiro → Cartões corporativos**. A tela lista os cartões já cadastrados com portador, emissor, os quatro últimos dígitos, o limite mensal e a situação (Ativo/Inativo).:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/despesas-02-corporate-cards.png" alt caption width="3200" height="2000"}
2. **Novo cartão.** No card **"Novo cartão"**, preencha\:Clique em **"Salvar"**. Para alterar um cartão existente, use o ícone de **lápis** na linha; para tirá-lo de circulação, use o ícone de **proibido** ("Desativar").
   - **Portador** — o colaborador dono do cartão (escolhido entre os parceiros/pessoas cadastrados).
   - **Últimos 4** — os quatro últimos dígitos do cartão (só números).
   - **Emissor** — a bandeira ou o banco emissor.
   - **CC padrão** — o *centro de custo* padrão do cartão (opcional).
   - **Limite mensal** — o teto de gasto do cartão (opcional).
3. **Importe a fatura do cartão.** No card **"Importar fatura do cartão"**, escolha um **cartão ativo**, informe o **formato** (**CSV** ou **OFX**) e anexe o arquivo da fatura ou cole o conteúdo no campo de texto. No CSV, cada linha traz data;valor;descrição (uma transação por linha). Clique em **"Importar fatura"**. É assim que as transações do cartão entram no ERP sem digitação manual, uma a uma.

**Capturar o recibo em vez de digitar.** No editor de linhas da prestação de contas, o bloco de captura lê o comprovante para você:

- **Cole a chave de acesso** de 44 dígitos do cupom/nota (ou o conteúdo do QR Code) e clique em **"Capturar recibo"**; ou
- clique em **"Ler de uma foto"** e escolha a foto do comprovante — o sistema lê o **QR Code** da imagem.

Em ambos os casos o sistema **sugere** os campos (documento fiscal e CNPJ do emitente) e você confere antes de adicionar a linha — nada é lançado sozinho. Se a chave lida **não conferir** (dígito verificador inválido), o sistema avisa e **não preenche nada**, em vez de arriscar um emitente errado. Comprovante sem QR e sem chave continua sendo preenchido à mão.

1. **Confira as transações importadas.** Depois de importar, a lista de faturas do cartão mostra o período, o formato, a quantidade de transações, o total e a data de importação. Clique em **"Transações"** para abrir a gaveta lateral com as linhas (data, descrição e valor) daquela fatura.

### Definir políticas de despesa e o reembolso automático

1. **Abra "Políticas de despesa".** Menu **Financeiro → Políticas de despesa**. A tela traz, no topo, a configuração de **reembolso automático** e, abaixo, o cadastro e a lista de políticas.
2. **Configure o reembolso automático.** No card **"Reembolso automático"**, marque **"Reembolsar automaticamente na aprovação"** se quiser que aprovar um relatório de despesa já emita e liquide o reembolso sozinho. Escolha a **categoria de reembolso** e o **prazo (dias)** até o vencimento. Clique em **"Salvar"**. Com o reembolso automático desligado, a liquidação continua sendo feita manualmente na tela de relatórios (passo 16).
3. **Crie uma política.** No card **"Nova política"**, preencha\:Clique em **"Salvar"**. A política passa a ser avaliada automaticamente quando um relatório é submetido.
   - **Nome** — como a regra será identificada.
   - **Categoria** — a categoria de despesa a que a regra se aplica; deixe **"Todas as categorias"** para valer para qualquer gasto.
   - **Fiscalização** — **"Bloquear submissão"** (impede submeter enquanto a regra for violada) ou **"Apenas avisar"** (permite submeter, mas registra o alerta).
   - **Teto por linha**, **Teto por relatório** e **Comprovante exigido acima de** — os limites em reais. É preciso informar **ao menos um** desses limites para salvar.
4. **Gerencie as políticas.** A lista mostra cada política com seus limites, a fiscalização e a situação. Use os ícones da linha para ver o **histórico** de alterações, **editar** ou **desativar** a política.

### Registrar a prestação de contas (relatório de despesa)

1. **Abra "Relatórios de despesa".** Menu **Financeiro → Relatórios de despesa**. No topo aparecem os painéis consolidados: **"Despesas consolidadas"** (total geral e a quebra por situação) e o **"Painel gerencial"**, que abre a despesa por **categoria**, **centro de custo**, **portador** e **situação**, com filtros por período, portador, categoria e centro de custo. É a visão única e consolidada das despesas corporativas.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/despesas-01-expense-reports.png" alt caption width="3200" height="2000"}
2. **Crie o relatório.** No card **"Novo relatório de despesa"**, escolha o **portador**, o **período** (no formato yyyy-MM, por exemplo 2026-05) e, se quiser, **observações**. Clique em **"Criar"**. O relatório nasce na situação Rascunho.
3. **Lance as despesas (linhas).** Na lista de relatórios, clique em **"Linhas"** para expandir o relatório. Enquanto ele está em Rascunho, informe por linha a **data**, a **descrição**, a **categoria**, o **centro de custo** e o **valor**, e clique em **"Adicionar linha"**. Para tirar uma linha, use **"Remover"**.
   - **Sugestão de categoria por IA.** Ao digitar a descrição, clique em **"Sugerir categoria (IA)"**: o sistema propõe uma categoria a partir do texto e do valor e já preenche o seletor — você confirma ou troca. A resposta indica a origem da sugestão e o grau de confiança.
   - **Comprovantes.** Use a área de **anexos** do relatório para subir os recibos (enviar, listar, baixar, remover).
4. **Revise com apoio de IA (opcional).** Ainda nas linhas, clique em **"Revisão IA"**. O sistema faz uma conferência consultiva do relatório e lista **alertas** (por exemplo, valores atípicos) — é um apoio à conferência, não bloqueia por si só.
5. ⚠️ **Confira quem lançou, e não só de quem é.** Na coluna do portador, quando o relatório foi **aberto por outra pessoa**, aparece embaixo, em destaque, **"lançado por \<nome>"**. Quando o portador lançou o próprio relatório nada é escrito — o destaque existe só para o caso que merece atenção. Vale olhar antes de aprovar: um relatório pode ser aberto legitimamente por um terceiro (a assistente que lança para o diretor), e pode ser aberto por quem não deveria. Sem essa linha, os dois casos ficam idênticos na tela. O sistema registra separadamente **quem abriu** e **quem submeteu**, porque abrir e submeter podem ser pessoas diferentes e é justamente essa passagem que uma auditoria pergunta.
   **Submeta o relatório.** Com as linhas lançadas, clique em **"Submeter"**. A situação muda de Rascunho para Aguardando. Nesse momento o sistema aplica as **políticas de despesa**: se uma política de **bloqueio** for violada (teto ou comprovante), a submissão é barrada com a explicação.
6. **Aprove ou rejeite.** Na lista de relatórios, escolha em **"Aprovando como:"** o aprovador. Para um relatório Aguardando, use **"Aprovar"** (passa a Aprovado) ou **"Rejeitar"**, informando o **motivo da rejeição** (passa a Rejeitado, e o motivo fica visível na linha).
7. **Liquide o reembolso.** Para um relatório Aprovado, clique em **"Liquidar"**, escolha a **categoria de reembolso** e o **vencimento**, e confirme. A liquidação gera o reembolso e integra com o financeiro (a conta a pagar do colaborador). O relatório passa a Liquidado. Se o reembolso automático estiver ligado (passo 6), esse passo acontece sozinho na aprovação.
8. **Acompanhe o histórico.** Ao expandir as linhas, o card **"Histórico de alterações"** lista cada evento (criação, submissão, aprovação, rejeição, liquidação) com o autor e a data. Clique em um evento para abrir o detalhe do que mudou — é a auditoria contínua do relatório.

### Solicitar e prestar contas de adiantamento de viagem

**1 - Abra "Adiantamento de viagem".** Menu **Financeiro → Adiantamento de viagem**. A tela tem três blocos: nova solicitação, pendentes de aprovação e aguardando prestação de contas.


![](https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/despesas-03-travel-advances.png)

2 - ⚠️ **O centro de custo tem de ser um dos autorizados para o viajante.** O adiantamento fica **vinculado ao centro de custo do colaborador**, e o sistema confere isso: se o centro informado não estiver entre os que o colaborador tem autorizados (cadastro do empregado, aba de centros de custo), a solicitação é recusada dizendo qual centro foi negado. Duas ressalvas que evitam chamado à toa: quando o **empregado ainda não tem nenhum centro autorizado cadastrado**, a conferência não opina — lista vazia é silêncio, não negativa —; e quando o **parceiro do viajante não está ligado a um usuário do sistema**, o sistema não tem como saber de quem se trata e também não opina. Nos dois casos, quem garante a correção é a aprovação. Para a trava valer de verdade, o cadastro precisa ligar o parceiro ao usuário e o empregado aos seus centros.
**Faça a solicitação.** No card **"Enviar solicitação"**, preencha o **viajante**, o **centro de custo**, a **categoria financeira**, opcionalmente o **projeto**, o **destino**, as **datas de início e fim**, a **finalidade** e o **valor**. Clique em **"Submeter"**. A solicitação fica pendente de aprovação.
A **categoria financeira** é a conta em que a despesa entra quando o adiantamento for aprovado — a aprovação gera um título a pagar, e todo título carrega uma categoria. Quem pede o dinheiro sabe para que ele é; por isso a categoria é informada aqui, e não na aprovação.

**3 - Quem viaja também não aprova o próprio adiantamento** — desde que o **viajante esteja vinculado ao usuário** na ficha de parceiro. Sem esse vínculo, a regra de quatro olhos consegue barrar apenas **quem digitou** o pedido: bastaria pedir a um colega que preenchesse o formulário. **Hoje o vínculo não está preenchido em nenhum parceiro**, então essa segunda trava ainda não recusa nada — ela passa a valer sozinha assim que o cadastro apontar o usuário de cada pessoa.
**Aprove ou rejeite (regra de quatro olhos).** No card **"Pendente de aprovação"**, cada solicitação pode ser **Aprovada** ou **Rejeitada**, com uma **nota de decisão** opcional. Vale a regra de **quatro olhos**: o próprio solicitante **não pode aprovar** o seu pedido.

**4 - Preste contas.** No card **"Aguardando prestação"**, informe o **gasto real**, marque se **houve comprovantes** e registre **notas**, então clique em **"Prestar contas"**. A prestação de contas é obrigatória — sem comprovantes, o valor tende a virar verba tributável, por isso o registro dos comprovantes importa.

:::BlockQuote
**Gastou mais do que o adiantado? A justificativa passa a ser obrigatória.** Viagem estende, voo remarca, diária sobe — o excesso é legítimo e **não** é recusado. O que é recusado é o excesso **sem nada escrito**: informe o motivo em **notas** e a prestação é aceita. A mensagem mostra o **quanto passou** do adiantado. Gastar menos que o adiantado não pede justificativa nenhuma.A **devolução da sobra** e o **reembolso do excedente** continuam sendo tratados fora desta tela, como um título próprio no contas a pagar/receber.
:::

**5 - Reveja o que já foi concluído.** O card **"Concluídos"** lista os adiantamentos já **prestados** ou **rejeitados**, com o valor adiantado, o gasto real e as observações. Ele existe porque, antes, o adiantamento sumia da tela no instante em que você prestava contas — e a única forma de reencontrá-lo era saber de antemão de quem ele era. O card é somente leitura: adiantamento concluído não se edita aqui.

## Verificação

***

Você sabe que funcionou quando:

- O cartão corporativo aparece na lista como Ativo, com portador, emissor e últimos 4 dígitos; e a fatura importada mostra a quantidade de transações e o total, com as linhas visíveis na gaveta "Transações".
- A política de despesa aparece na lista com o(s) limite(s) definido(s) e, ao submeter um relatório que a viola, o sistema **bloqueia** (política de bloqueio) ou **avisa** (apenas avisar).
- O relatório de despesa percorre as situações Rascunho → Aguardando → Aprovado → Liquidado, e a liquidação gera o reembolso/conta a pagar do colaborador (página Financeiro).
- Os painéis "Despesas consolidadas" e "Painel gerencial" mostram o total e a quebra por categoria, centro de custo, portador e situação — a visão única e consolidada.
- A sugestão de categoria por IA preenche o seletor ao clicar em "Sugerir categoria (IA)", e a "Revisão IA" lista alertas quando há valores atípicos.
- O adiantamento de viagem sai de pendente para aprovado (sem que o solicitante aprove o próprio pedido) e depois é encerrado pela prestação de contas com o gasto real informado.
- O histórico de alterações do relatório registra cada evento (criação, submissão, aprovação, liquidação) com autor e data.

### Quando a prestação de contas não vem: recuperar o valor

Passado o prazo parametrizável sem prestação de contas, o sistema abre um **processo de recuperação** do adiantamento (menu **Financeiro → Recuperação de adiantamentos**). A recuperação tem devido processo — o colaborador é **notificado** e só depois a cobrança pode ser **autorizada** —, e sai por uma de duas vias: **desconto em folha** ou **débito na conta de proventos**.

1. **Autorizações de débito em conta.** Debitar a conta de proventos de alguém exige o **consentimento da pessoa**, e é esse cartão que o registra. Escolha o colaborador (a lista traz quem tem recuperação em curso), e você vê o histórico de autorizações: a **vigente**, se houver, e as já **revogadas**, cada uma com quem concedeu, quando, e a **evidência**.
   - **Registrar a autorização** pede a **conta de proventos** e a **evidência** — o termo assinado, o protocolo, o número do processo. A evidência é obrigatória: sem ela o registro diria que alguém autorizou um débito e não saberia dizer como se sabe disso.
   - **Revogar** vale **de imediato**: a próxima recuperação daquele colaborador volta a ser desconto em folha. Exige motivo, que fica gravado junto da revogação. Revogar é direito do colaborador, e não depende de o órgão concordar.
   - **Sem autorização vigente, o débito em conta simplesmente não acontece** — a recuperação é roteada para o desconto em folha e a linha mostra o motivo. Se você esperava um débito e viu um desconto, é aqui que se olha primeiro.
2. **Zero dias de aviso não quer dizer "não configurado".** Quer dizer descontar no mesmo dia em que o colaborador é avisado, que é o ajuste mais duro que existe. Um campo zerado parece pendente e é, na verdade, o extremo — confira antes de rodar a primeira recuperação.
   **Parâmetros do desconto em folha.** Três campos, no fim da mesma tela, e são eles que decidem como o desconto sai. Até existirem aqui, só dava para configurá-los por chamada de API — ou seja, na prática ninguém configurava.
   - **Rubrica padrão** é a linha em que o desconto aparece no holerite. **Vazia, o repasse é recusado** e a recuperação não chega à folha. O sistema diz o motivo pelo nome, mas até aqui você não tinha onde responder.
   - **Dias de aviso** é o prazo de defesa do art. 462 da CLT: quantos dias antes do desconto o colaborador é avisado.
   - **Teto de parcelas** é em quantos holerites uma recuperação pode ser dividida. Deixe vazio para não haver teto — e isso é uma escolha, não um esquecimento.

## Erros comuns

***

- **Não consigo importar a fatura** — escolha um cartão **ativo**, confira se o **formato** (CSV ou OFX) bate com o arquivo e se há conteúdo no campo (arquivo anexado ou texto colado); um cartão desativado não aparece no seletor de importação.
- **A política não salva** — toda política exige **ao menos um limite** (teto por linha, teto por relatório ou comprovante exigido acima de); só o nome não basta.
- **A submissão do relatório é barrada** — há uma política de **bloqueio** violada (gasto acima do teto ou sem comprovante). Ajuste as linhas ou anexe o comprovante; se a política for de "apenas avisar", a submissão passa com o alerta registrado.
- **Não consigo aprovar o relatório** — escolha antes o aprovador em **"Aprovando como:"**; os botões de aprovar/rejeitar ficam desabilitados enquanto nenhum aprovador está selecionado.
- **A liquidação não gera o reembolso** — a liquidação exige a **categoria de reembolso** e o **vencimento**; sem os dois o botão de confirmar fica bloqueado.
- **O reembolso não sai sozinho na aprovação** — o reembolso automático precisa estar **ligado** e com uma **categoria de reembolso** definida no card "Reembolso automático"; sem isso, a liquidação é manual.
- **Não consigo aprovar o adiantamento de viagem** — pela regra de quatro olhos, o **solicitante não aprova o próprio pedido**; a decisão precisa vir de outra pessoa. Se o **viajante** estiver vinculado ao seu usuário na ficha de parceiro, ele também não aprova o adiantamento de que é beneficiário — nem que outra pessoa tenha digitado.
- **Não consigo submeter o adiantamento de viagem** — a **categoria financeira** é obrigatória, junto com viajante, centro de custo, destino, datas e valor; o botão de submeter só habilita com todos preenchidos.
- **A sugestão de IA não aparece** — a sugestão usa a **descrição** digitada (e o valor); sem descrição o botão fica desabilitado. Quando não há modelo conectado, o apoio de IA opera em modo baseado em regras (o rótulo no card de insights indica se o modelo está ativo ou em modo de regras).

[title] Estoque
[path] Aplicações/ERP/Manual do Usuário/

# Estoque (depósitos, movimentos, reservas, baixas, inventário e relatórios)

:::BlockQuote
Pré-requisitos: [Cadastro fiscal próprio](docId\:Q-zx6Qk4pMFD09yrhmsve) (estabelecimentos, para amarrar cada depósito a uma matriz ou filial) e [Cadastros gerais (parceiros e produtos)](docId:6xpQsdWQ2NTyI40BFqDS-) (produtos, para ter o que movimentar).
:::

## Introdução

***

O módulo **Estoque** guarda **o que** você tem, **onde** está e **quanto** está disponível. Cada saldo pertence a um depósito (também chamado de almoxarifado), e cada movimento — entrada, saída, transferência, reserva, baixa, requisição, devolução — é registrado com data, produto, quantidade e origem. É aqui que o operador confere os saldos do dia a dia, corrige diferenças de contagem e mantém o estoque fiel ao que existe no chão do armazém.

Além do básico (saldo e movimento), o módulo cobre a operação completa de um almoxarifado público de pequeno/médio porte: endereçamento por bin para achar o item na prateleira, reserva de estoque para segurar mercadoria de um pedido, baixa por perda com motivo, política de reposição para avisar quando comprar, requisição e devolução interna de material, contagem de inventário por comissão, envio para conserto e relatórios/KPIs gerenciais. Você usa o menu lateral **Estoque** e escolhe a tela conforme a tarefa.

## Passo a passo

***

### Conferir saldos e registrar um movimento avulso

A tela **Estoque** é o painel central: mostra os saldos por depósito e permite lançar entrada, saída ou ajuste avulso — aquele movimento que **não** veio de um pedido de compra ou de uma venda (doação, perda, correção de contagem, transferência fiscal).

1. **Abra o painel de estoque.** No menu lateral, clique em **Estoque → Estoque**. A tela abre com três áreas: **Registrar movimento**, **Transferência entre depósitos** e **Saldos de estoque** (com o histórico de **Movimentos de estoque** logo abaixo).:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/068-inventory.png" alt caption width="3200" height="2000"}
2. **Registre um movimento.** No bloco **Registrar movimento**, preencha:
   - **Produto** — pesquise pelo nome ou código (ex.: Parafuso Sextavado M8).
   - **Depósito** — o almoxarifado onde o movimento acontece.
   - **Lote** e **Endereço** — opcionais; use quando o produto for controlado por lote ou o depósito exigir bin.
   - **Tipo** — Entrada, Saída, Ajuste, Consumo de produção ou Entrada de produção.
   - **Quantidade** — a quantidade movimentada.
   - **Observações** — o motivo (ex.: Devolução de cliente do pedido 042). **Obrigatório no Ajuste:** um ajuste manual sem motivo é recusado, e o **Documento de origem** serve igualmente (ex.: o número do boletim de ocorrência). A baixa por quebra sempre exigiu motivo tipado; o ajuste avulso passou a exigir o mesmo, para o saldo nunca mudar sem alguém dizer por quê.
3.

**Não há ficha técnica nem ordem de produção.** Quem registra é quem declara o que foi consumido e o que saiu pronto; o sistema não deriva o consumo de uma estrutura de produto nem sequencia ordens. Isso é trabalho de um módulo de produção, que não existe.

**Os dois tipos de produção existem para quem TRANSFORMA material** (gráfica, cozinha, oficina). O Consumo de produção tira do estoque o material que foi transformado; a Entrada de produção devolve ao estoque o produto pronto. No saldo eles se comportam como uma saída e uma entrada comuns — a diferença é que o custeio os reconhece como produção e aplica a **regra de custo do processo de produção** (Custos → Métodos de custeio), em vez da regra geral. Se o órgão só compra e consome, não use nenhum dos dois.

**Quem registrou fica gravado.** Todo movimento passou a guardar o usuário que o lançou, e o campo aparece no histórico de **Movimentos de estoque**. Movimentos anteriores a essa mudança ficam sem autor — o campo vazio significa "não se sabe", e não foi preenchido por estimativa.

**Clique em "Registrar".** Numa entrada o saldo sobe; numa saída, desce. O **Ajuste** aceita quantidade negativa, como avisa a própria tela — use-o para corrigir uma diferença pontual.

### Cadastrar e corrigir lotes

O lote é como o almoxarifado sabe **qual** mercadoria saiu: de quem veio e até quando vale. Para produto com controle de lote, é a validade do lote que orienta o consumo.

No cartão **Lotes** da tela **Estoque → Estoque**, escolha o **produto** — a lista mostra os lotes já cadastrados dele, com código, validade e fornecedor de origem. Para cadastrar, preencha **Código do lote**, **Validade** e **Fornecedor** e clique em **"Adicionar lote"**.

Cada linha tem duas ações:

- **Editar lote** — abre a correção do **código**, da **validade** e do **fornecedor**, já preenchidos com o que está gravado. Use quando a data foi digitada errada no recebimento: sem isso a única saída seria cadastrar um segundo lote com a data certa, o que **parte o saldo do produto em dois** e deixa o lote errado vivo na separação.
- **Rastreabilidade** — mostra o fornecedor de origem e os destinos para onde o lote saiu.

:::BlockQuote
**O produto do lote não se troca.** A caixa de edição não oferece o campo de propósito: um lote pertence ao produto em que nasceu. Se o lote foi cadastrado no produto errado, o caminho é cadastrá-lo no produto certo.
:::

:::BlockQuote
**Dois lotes do mesmo produto não podem ter o mesmo código.** Ao salvar um código já usado, o sistema recusa dizendo qual é o código repetido, e a caixa continua aberta com o que você digitou.
:::

### Transferir entre depósitos

:::BlockQuote
**Transferência entre estabelecimentos diferentes exige o documento.** Depósitos de estabelecimentos distintos são **CNPJs distintos**, e mercadoria que anda entre eles é operação fiscal: informe o **Documento de origem** (a nota de transferência) e ele fica gravado nas duas pernas do movimento. Transferência entre depósitos do **mesmo** estabelecimento continua sem exigir documento.
:::

Use quando o material fisicamente muda de um almoxarifado para outro (da matriz para a filial, do recebimento para o setor de uso).

1. **Localize o bloco "Transferência entre depósitos"** na mesma tela **Estoque** (logo abaixo do registro de movimento).
2. **Preencha a transferência.** Informe o **Produto**, o depósito **De** (origem) e o depósito **Para** (destino) — que devem ser distintos — e a **Quantidade**.
3. **Clique em "Transferir".** O saldo sai da origem e entra no destino, com a mesma data e a mesma quantidade. Se você pedir mais do que existe na origem, o sistema bloqueia e avisa o estoque insuficiente (disponível X, solicitado Y).

### Reservar estoque para um pedido

A reserva **segura** uma quantidade para uma demanda futura sem tirá-la fisicamente do depósito. O disponível passa a ser o físico menos o reservado, evitando que a mesma peça seja prometida a dois clientes.

1. **Abra as reservas.** Menu **Estoque → Reservas de estoque**. A tela traz o formulário **Nova reserva** e, abaixo, a lista de reservas com as colunas **Reservado**, **Pendência** e **Situação**.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/071-stock-reservations.png" alt caption width="3200" height="2000"}
2. **Crie a reserva.** Em **Nova reserva**, escolha o **Produto**, o **Almoxarifado** e a **Quantidade**; clique em **Reservar**. Se houver saldo, a reserva sai como **Liberada** e o disponível cai na quantidade reservada. Se não houver saldo suficiente, parte da reserva fica como **Pendência** (backorder), aguardando reposição.

### Dar baixa por quebra ou perda

A baixa registra a saída definitiva de mercadoria por um motivo de perda — com valor financeiro associado, para a contabilidade reconhecer o prejuízo.

1. **Abra as baixas.** Menu **Estoque → Baixas de estoque**. O formulário **Nova baixa** fica no topo; o histórico de baixas, logo abaixo.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/073-stock-write-offs.png" alt caption width="3200" height="2000"}
2. **Registre a baixa.** Preencha o **Produto**, o **Almoxarifado**, a **Quantidade** e o **Motivo** (Quebra, Roubo, Obsolescência ou Validade). Informe o **Valor da perda** (ex.: R$ 1.250,00) e, se quiser, uma **Observação**. Clique em **Registrar baixa**. O saldo diminui e a perda entra no razão contábil (ver página [Contabilidade](docId:08cbTyrT0WXBp4ymvrog_)).

### Cadastrar e editar depósitos

O depósito é o local de estoque do tenant. Cada movimento acontece dentro de um depósito, e cada depósito pertence a um *estabelecimento* (matriz ou filial).

1. **Abra os depósitos.** Menu **Estoque → Depósitos**. A lista mostra **Código**, **Nome**, **Descrição** e **Situação** (Ativo/Inativo), com busca por código ou nome.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/069-warehouses.png" alt caption width="3200" height="2000"}
2. **Cadastre um depósito.** Clique em **Novo depósito** e preencha\::inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/015-warehouses-detail.png" alt caption width="3200" height="2000"}
   - **Estabelecimento (*CNPJ*)** — escolha entre os cadastrados na página [Cadastro fiscal próprio](docId\:Q-zx6Qk4pMFD09yrhmsve) (ex.: ACME Servicos Ltda — 11222333000181 matriz). É **obrigatório**: sem estabelecimento o sistema bloqueia o cadastro e aponta o campo com erro de validação.
   - **Código** — ex.: CMP-WH-01. Não pode repetir um código já usado em outro depósito (o sistema rejeita duplicatas).
   - **Nome** — ex.: Almoxarifado Central.
   - **Descrição** — opcional.
   - **Exige endereço** — marque "Movimentos exigem bin" se você quer obrigar o operador a informar o endereço interno em cada movimento deste depósito.
3. **Clique em "Salvar".** O depósito passa a aparecer na lista e fica disponível nas movimentações. O mesmo formulário (**Editar depósito**) é usado ao clicar no lápis de um registro existente; o botão de bloqueio ao lado inativa o depósito sem apagar o histórico.

### Endereçar por bin (endereços internos)

O *bin* é a subdivisão dentro do depósito (rua/prateleira/nível) que diz a posição exata da mercadoria. É opcional para o almoxarifado pequeno, recomendado quando o operador começa a perder tempo procurando produto.

1. **Abra os endereços.** Menu **Estoque → Endereços** (/bins). A lista (**Endereços (bins)**) traz filtros por **Depósito**, **Zona** e **Tipo**, e as colunas **Código**, **Zona**, **Tipo** e **Status**.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/070-bins.png" alt caption width="3200" height="2000"}
2. **Cadastre um endereço.** Clique em **Novo endereço** e informe o **Depósito**, um **Código** com naming consistente (ex.: A-03-02 = rua A, prateleira 03, nível 02), a **Zona** (ex.: ZONE-1), o **Tipo** (ex.: Separação) e uma **Descrição**.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/016-bins-detail.png" alt caption width="3200" height="2000"}
3. **Salve.** O endereço fica disponível para ser escolhido no campo **Endereço** dos movimentos. Atenção: o **código do bin não pode ser alterado** depois de criado — se precisar renomear, desative o endereço e crie um novo.

### Configurar a política de reposição

A política de reposição define **quando** avisar que é hora de comprar: com base em dias de cobertura dirigidos pela curva ABC, o sistema aponta os itens que caíram abaixo do estoque mínimo.

1. **Abra a política.** Menu **Estoque → Política de reposição**. A tela tem um painel **Sugestões de reposição** (itens abaixo do mínimo) e a lista de políticas cadastradas; no ambiente de demonstração o painel mostra "Nenhum item abaixo do estoque mínimo" e a lista aparece vazia até você cadastrar a primeira política.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/072-reorder-policies.png" alt caption width="3200" height="2000"}
2. **Cadastre uma política.** Clique em **Nova política** e defina o produto, o depósito e os parâmetros de mínimo/máximo (dias de cobertura), o consumo diário e a classe ABC. A **cobertura máxima** (alvo) não pode ser menor que a **mínima** — o sistema rejeita a política nesse caso. Quando o saldo do item cai abaixo do ponto de pedido, ele passa a aparecer em **Sugestões de reposição** com a quantidade sugerida para repor até o alvo — o gatilho para abrir uma requisição de compra ([Compras](docId:3mdo_BH5DDXIp3VIh4ATK)).

### Configurar as notificações de reposição

A política de reposição (acima) define **quando** um item chega ao ponto de pedido; as notificações de reposição definem **quem** é avisado e **por onde**. Aqui você cadastra os destinatários do alerta de ressuprimento — de um material específico ou de um grupo inteiro de materiais — e escolhe se o aviso chega **no sistema**, por **e-mail** ou nos dois canais. Sem essa configuração, o item até aparece nas sugestões de reposição, mas ninguém é avisado ativamente de que é hora de comprar.

1. **Abra as notificações.** Menu **Estoque → Notificações de reposição**. A tela traz o formulário de nova configuração e, abaixo, a lista das configurações já cadastradas, com a **abrangência** (material ou grupo), os **canais** do aviso e a **situação** (Ativa/Inativa) de cada uma.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/e32-05-reorder-notification-configs.png" alt caption width="3200" height="2000"}
2. **Cadastre quem é avisado.** Escolha a **abrangência**: **Por material** (avisa sobre um produto específico) ou **Por grupo de materiais** (avisa sobre todos os itens de um grupo). Selecione o material ou o grupo correspondente e marque os **canais** do aviso — **No sistema** (notificação dentro do portal) e/ou **E-mail**. Pelo menos um canal precisa estar marcado. Clique em **Salvar**: a configuração passa a valer para os próximos alertas de ponto de pedido e surge na lista com a situação **Ativa**.
3. **Desative ou reative uma configuração.** Na linha da configuração, use a ação de **desativar** para parar de disparar aquele aviso — a **situação** muda para **Inativa** sem apagar o registro. A mesma ação **reativa** quando precisar voltar a avisar. Assim você pausa um alerta em manutenção sem perder o histórico da configuração.

### Requisitar e devolver material interno

A requisição interna é o pedido de um setor ao almoxarifado; a devolução recredita ao estoque o que sobrou. O fluxo da requisição é **Solicitada → Aprovada → Atendida**.

1. **Abra as requisições.** Menu **Estoque → Requisições de material**. Preencha o formulário **Nova requisição**: **Depósito**, **Centro de custo**, **Produto**, **Quantidade**, **Data esperada de atendimento** e **Observações**; clique em **Cadastrar**.Ao **aprovar** a requisição, o sistema grava **quem aprovou** junto do instante da aprovação — é a aprovação que libera a reserva e deixa o material sair do almoxarifado. Aprovações registradas antes dessa mudança aparecem sem autor.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/074-material-requisitions.png" alt caption width="3200" height="2000"}
2. **Devolva o que sobrou.** Menu **Estoque → Devoluções de material**. No bloco **Selecione o item**, escolha o **Almoxarifado**, a **Requisição** e o **Item da requisição**. Depois, em **Nova devolução**, informe a **Quantidade** e o **Motivo** e clique em **Registrar devolução**. O material volta ao saldo do depósito.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/075-material-returns.png" alt caption width="3200" height="2000"}

### Abrir e fechar períodos de armazenagem

O período de armazenagem controla a janela em que o depósito aceita movimentos. Ao fechar o período, o sistema **congela as movimentações** daquele intervalo — garantia de que ninguém lança retroativo depois da contagem ou do fechamento contábil.

1. **Abra os períodos.** Menu **Estoque → Períodos de armazenagem**. Escolha o **Depósito** para ver os períodos daquele almoxarifado, com o ciclo **Aberto → Fechado**. No ambiente de demonstração, com o depósito selecionado, o histórico aparece vazio ("Sem períodos") até você abrir o primeiro período no bloco **Abrir novo período**.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/076-warehouse-periods.png" alt caption width="3200" height="2000"}
2. **Feche o período** quando terminar o mês/contagem. A partir daí, novos movimentos naquele intervalo ficam bloqueados; para reabrir, use a ação correspondente no mesmo painel.

### Fazer a contagem de inventário por comissão

:::BlockQuote
**O tratamento da divergência agora vale.** Linha divergente marcada para **recontagem** impede o fechamento — a contagem avisa quantas estão nessa situação: reconte-as ou mude o tratamento antes de fechar. Divergência **sem** tratamento não impede o fechamento, mas passa a ficar registrada na linha como **ajuste aceito**, para o registro dizer o que o fechamento fez com ela.
:::

A contagem física reconcilia o que o sistema diz com o que está no armazém. No setor público, ela é conduzida por uma **comissão de inventário** — pelo menos 3 membros, com exatamente 1 presidente.

1. **Monte a comissão.** Menu **Estoque → Comissões de inventário**. No **Cabeçalho**, escolha o **Inventário** (a campanha de contagem) e dê um **Nome da comissão**. No bloco **Membros**, selecione cada **usuário** e o **Papel** (Membro ou Presidente) e clique em **Adicionar**. Os contadores no rodapé (3/3 mínimo, 1 presidente) confirmam que a composição é válida.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/077-inventory-commissions.png" alt caption width="3200" height="2000"}
2. **Registre a comissão.** Clique em **Registrar** quando atingir pelo menos 3 membros e exatamente 1 presidente. Por segregação de funções (Lei 4.320/64), o servidor que atua no próprio almoxarifado sendo inventariado **não** pode compor a comissão daquele inventário — o sistema recusa a inclusão. A comissão passa a conduzir a contagem cega (contar sem ver o saldo esperado), a conciliação (esperado × contado × diferença) e os ajustes de cada divergência.
3. **Ajuste pela diferença.** As divergências apuradas na contagem geram movimentos de ajuste (entrada se sobra, saída se falta). Depois de conciliar e ajustar, o saldo do sistema volta a bater com o chão. Na tabela de itens contados, a coluna **Tratamento** marca cada linha divergente como **Sem tratamento** e oferece a ação **Tratar divergência** para resolvê-la item a item.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/150-inventory-count-divergence.png" alt caption width="3200" height="2000"}Ao clicar em **Tratar divergência**, abre a gaveta com **Esperado**, **Contado** e **Diferença**; escolha a **Resolução** (**Aceitar ajuste**, **Recontar** ou **Justificado**) — a opção de recontagem traz a orientação para nova contagem — e registre o **Parecer/observação** que fica ligado à divergência.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/151-inventory-divergence-drawer.png" alt caption width="3200" height="2000"}

### Enviar material para conserto

Quando um bem precisa de reparo externo, você registra a remessa ao fornecedor — o item sai do saldo disponível e fica marcado como "em reparo" até voltar.

1. **Abra as remessas.** Menu **Estoque → Remessas para conserto**. Preencha **Nova remessa**: **Produto**, **Depósito**, **Fornecedor** (ex.: Fornecedor Exemplo Ltda), **Quantidade**, **Data de envio** e **Retorno previsto**. Informe o **Orçamento** (opcional), marque **Em garantia** se for o caso (troca o *CFOP* da operação) e descreva o **Motivo**.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/080-repair-shipments.png" alt caption width="3200" height="2000"}
2. **Clique em "Enviar".** A remessa passa a constar em **Remessas abertas** e o item aparece como em reparo até o retorno ser registrado.

### Consultar relatórios de estoque

Os relatórios gerenciais mostram movimentações, consumo e giro, e permitem exportar dados em CSV para conferência.

1. **Abra os relatórios.** Menu **Estoque → Relatórios de estoque**. No topo, escolha o **Relatório** (ex.: Movimentação por tipo), o **Almoxarifado** e o intervalo **De / Até**; o **Resultado** aparece na área central. No ambiente de demonstração, sem movimentações no intervalo escolhido, o **Resultado** mostra "Sem dados no período" até você registrar movimentos de estoque.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/078-inventory-reports.png" alt caption width="3200" height="2000"}
2.

**Se o download não começar.** Alguns relatórios exigem o intervalo **De / Até** preenchido; sem ele o sistema recusa a exportação e explica qual campo falta. Se o navegador não baixar nada e nenhuma mensagem aparecer, informe o intervalo e tente de novo. *(Até 2026-08-02 todos os relatórios respondiam "sucesso" e interrompiam a transferência no meio, e o clique não produzia nem arquivo nem aviso; corrigido e conferido em execução nos 40 tipos.)*

**Exporte um CSV.** No bloco **Exportações CSV**, clique no relatório desejado — **Saldos atuais**, **Movimentações por período**, **Mais consumidos**, **Produtos inativos**, **Lotes a vencer (30d)**, **Requisições por status**, **Devoluções por produto**, **Recebimentos no período**, **Curva ABC**, **Estoque valorizado**, **Giro de estoque** ou **Status de ressuprimento**. O arquivo é gerado com os filtros do topo aplicados quando relevantes.

### Acompanhar os KPIs de estoque

Os indicadores mostram cobertura, consumo diário médio e giro por produto/depósito — a leitura rápida de saúde do estoque.

1. **Abra os KPIs.** Menu **Estoque → KPIs de estoque**. Informe o **Produto**, o **Depósito** e o intervalo **De / Até**; os indicadores do período aparecem no **Resultado**.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/079-inventory-kpis.png" alt caption width="3200" height="2000"}

### Conferência cega e liberação fiscal do recebimento

A conferência cega manda o conferente contar o que chegou **sem ver a quantidade pedida** — as diferenças só aparecem no fim, quando o recebimento é fechado. Antes de liberar a contagem, a nota do fornecedor passa por um **portão fiscal** (validação da NF-e), e o conferente pode usar o **leitor de código de barras** para reconhecer cada produto. Esse fluxo fica na tela de **Recebimentos** (menu **Compras → Recebimentos**) e complementa o recebimento simples descrito na página [Compras](docId:3mdo_BH5DDXIp3VIh4ATK).

1. **Abra os recebimentos.** No menu lateral, clique em **Compras → Recebimentos**. Abaixo do formulário **Novo recebimento**, encontre o bloco **Conferência cega**.



![](https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/060-goods-receipts.png)

1. **Abra a conferência.** Escolha o **Pedido** — só aparecem pedidos com situação Aberto ou Recebido parcial. Se o material exige controle de qualidade, marque **Inspeção obrigatória**: assim o recebimento só alimenta o estoque depois que o lote de inspeção for aprovado (ver "Cadastrar plano de inspeção e anexar o laudo à nota"). Clique em **Abrir conferência cega**.
2. **Passe pelo portão fiscal.** A contagem fica bloqueada até a NF-e passar no **Portão fiscal**. Informe a **Chave da NF-e**, o **Status SEFAZ** (Autorizado, Cancelado ou Denegado), se a **assinatura** é válida, o **CFOP da NF-e** e o **CFOP esperado**, se o **NCM** está consistente e a **manifestação do destinatário** (Confirmada, Ciente, Desconhece ou Não feita). Clique em **Rodar portão fiscal**. Se algo não confere, o portão falha e a conferência continua bloqueada — revise a nota antes de prosseguir.
3. **Reconheça os produtos pelo coletor.** Com o portão aprovado, use o campo **Ler código de barras (EAN/DUN)** e clique em **Resolver**: o sistema responde **Produto reconhecido** ou **Código desconhecido — busque manualmente**. É o suporte ao coletor de dados na recepção.
4. **Conte cada item.** Na tabela, digite a quantidade **Contada** de cada linha e clique em **Registrar contagem** — sempre sem ver a quantidade que foi pedida.
5. **Feche e revele as divergências.** Clique em **Fechar e revelar divergências**. O sistema mostra, item a item, **Esperado × Contado × Diferença**. Quando tudo bate, aparece "Sem divergência — a contagem bate com o pedido".

### Portaria: agendar entrega, controlar a capacidade da doca e a chegada do veículo

O agendamento de doca organiza **quando** cada fornecedor entrega e **em qual doca**, respeita um limite diário por doca e registra a entrada e a saída do veículo na portaria. A tela fica em **Compras → Portaria & docas** e detalha o agendamento citado em resumo na página [Compras](docId:3mdo_BH5DDXIp3VIh4ATK).

1. **Agende a janela de entrega.** Menu **Compras → Portaria & docas**, bloco **Agendar janela de entrega**. Escolha o **Pedido de compra** (opcional) e o **Fornecedor**, informe a **Doca** (ex.: D1), o **Início** e o **Fim** da janela e, se quiser avisar o fornecedor, o **E-mail do fornecedor** — o sistema usa esse endereço para o comunicado do agendamento (inclusive a orientação de coleta de troca, quando houver). Clique em **Agendar janela**.



![](https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/064-dock-schedule.png)

1. **Defina a capacidade diária da doca.** No bloco **Capacidade diária da doca**, informe a **Doca** e a **Capacidade/dia** (quantos recebimentos aquela doca aceita por dia) e clique em **Salvar**. Docas sem valor usam o padrão global; use **Remover** para voltar ao padrão.
2. **Registre a chegada do veículo.** No bloco **Portaria**, informe a **Placa do veículo** e o **Motorista**, escolha **Para o agendamento** correspondente (ou deixe **Sem agendamento** para uma entrada avulsa) e clique em **Entrada**. O veículo passa a constar em **No pátio**, com a hora de entrada — o que define a ordem de chegada.
3. **Registre a saída.** Quando a descarga termina, clique em **Saída** na linha do veículo em **No pátio**. O intervalo entre a entrada e a saída mede o tempo de permanência do veículo na descarga.
4. **Marque falta (no-show).** Na tabela **Agendamentos de doca**, um agendamento ainda Agendado cujo veículo não apareceu pode ser marcado como **Falta**, preservando o histórico da doca.

### Cadastrar plano de inspeção e anexar o laudo à nota

Quando um produto exige conferência de qualidade, você define um **plano de inspeção** com as características a medir; cada recebimento vira um **lote de inspeção** que é aprovado (libera para o estoque) ou reprovado (bloqueia a entrada). A tela fica em **Compras → Inspeção de recebimento** e detalha o que a página [Compras](docId:3mdo_BH5DDXIp3VIh4ATK) apresenta em resumo.

1. **Cadastre o plano.** Menu **Compras → Inspeção de recebimento**, bloco **Novo plano de inspeção**. Informe o **produto**, o **nível (NBR 5426)** (Geral I, Geral II ou Geral III), o **AQL (%)** e se usa **Skip-lot**. Em **Característica**, digite o nome (ex.: Diâmetro), escolha o **Tipo** (Numérico ou Atributo) e clique em **Adicionar característica** para cada uma. Clique em **Salvar plano** — o plano exige ao menos uma característica.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/061-inspections.png" alt caption width="3200" height="2000"}
2. **Inspecione o lote.** Na lista **Lotes de inspeção**, clique em **Inspecionar** no lote desejado. Para cada característica, escolha-a, informe o **Valor medido** e o **Resultado** (Conforme ou Não conforme) e clique em **Registrar resultado**.
3. **Anexe o laudo.** No bloco de anexo, informe o **id do anexo** (o laudo enviado pelo módulo de anexos) e clique em **Anexar laudo** — o laudo fica ligado ao lote e, por ele, à NF-e do recebimento.
4. **Decida o lote.** Clique em **Aprovar — liberar para o estoque** para liberar a entrada, ou **Reprovar — bloquear entrada** quando o material não passa. A reprovação impede que o produto alimente o estoque.
5. **Rastreie lotes por NF-e.** No bloco **Lotes ligados a uma NF-e**, informe o **id da NF-e** e clique em **Buscar** para ver os lotes de inspeção daquela nota, com a situação e o indicador de laudo anexado.

### Registrar a devolução de um cliente

Quando um cliente devolve mercadoria, você registra a devolução classificada por motivo e credita o material de volta ao almoxarifado. A tela fica no menu **Estoque → Devoluções de clientes**.

1. **Abra as devoluções de clientes.** Menu **Estoque → Devoluções de clientes**. No bloco **Nova devolução de cliente**, escolha o **Cliente** e o **Almoxarifado** que receberá o material.
2. **Classifique a devolução.** Em **Tipo**, escolha o motivo: **Avaria**, **Validade vencida**, **Validade próxima**, **Comercial** (negociação comercial) ou **Outros**. Informe a **Data da devolução** e, se quiser, **Observações**.
3. **Lance os itens devolvidos.** Em **Itens devolvidos**, escolha o **Produto** e a **Quantidade**; use **Adicionar linha** para incluir mais itens na mesma devolução.
4. **Salve.** Clique em **Salvar**. A devolução aparece na lista **Devoluções de clientes** (com cliente, almoxarifado, data, tipo e observações) e o material volta ao saldo do almoxarifado escolhido.
5. **Veja o que voltou.** A lista responde o **cabeçalho** da devolução — cliente, almoxarifado, data, tipo e observações —, e não **a mercadoria**. Clique em **"Ver itens"** na linha para abrir as **linhas** daquela devolução: **produto**, **quantidade** e **lote**. Item de material sem controle de lote aparece como **"Sem lote"** — a célula nunca fica vazia, para ausência de lote não se confundir com falha de carregamento.
   - Abre **uma linha por vez**: as linhas são detalhe da devolução que você está olhando, e carregar as de todas as devoluções de uma vez deixaria a tela lenta sem que ninguém tivesse pedido isso.
   - Se a consulta for **recusada**, o bloco mostra o aviso de **sem acesso** — nunca uma lista vazia. "Esta devolução não tem linhas" e "você não pode ver as linhas" são fatos opostos e não dividem a mesma tela.

### Aprovar e atender requisições de material

A requisição interna não para no cadastro: ela passa por um ciclo de **Solicitada → Aprovada → Atendida** conduzido nesta mesma tela. É aqui que o almoxarife libera, atende (total ou em partes) e acompanha o que cada setor pediu.

1. **Liste as requisições do depósito.** Abra **Estoque → Requisições de material**. No bloco **Requisições de almoxarifado**, escolha o **Almoxarifado** para carregar as requisições daquele depósito. Cada linha mostra a **Situação**: Solicitada, Aprovada, Atendida parcial, Atendida, Rejeitada, Cancelada ou Interrompida.
2. **Aprove, rejeite ou cancele.** Numa requisição ainda Solicitada, use os botões da coluna **Ações**: **Aprovar**, **Rejeitar** ou **Cancelar**. Só depois de **Aprovada** a requisição fica liberada para atendimento — é o ponto de controle de quem autoriza a saída do material.
3. **Atenda a requisição (total ou parcial).** Numa requisição Aprovada (ou Atendida parcial), clique em **Atender**. Abre a gaveta **Atender requisição**, com uma linha por item exibindo **Solicitado** e **Já atendido**. Preencha a coluna **Entregar agora** de cada item e clique em **Confirmar atendimento**. O sistema aceita **atendimento parcial** (entregar menos que o solicitado) e bloqueia qualquer quantidade acima do saldo remanescente. Ao confirmar, ele gera as saídas de estoque; se entregar tudo, a requisição vira Atendida; se entregar parte, Atendida parcial (e pode ser atendida de novo depois). Numa requisição Atendida parcial, a coluna **Ações** ainda oferece **Interromper** (encerra o atendimento pendente) e **Estornar atendimento** (desfaz as saídas já geradas, devolvendo o material ao saldo).:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/149-requisition-interrupt-reverse.png" alt caption width="3200" height="2000"}
4. **Pesquise requisições por situação, unidade e período.** O bloco **Pesquisar requisições** filtra por **Situação**, **Unidade solicitante** e intervalo **De / Até**, independentemente do almoxarifado escolhido acima — útil para achar, por exemplo, todas as requisições Atendida de um setor no mês.
5. **Faça a consulta consolidada por fornecedor.** No bloco **Consulta consolidada**, escolha o **Fornecedor** e marque **Somente requisições pendentes** para ver, num único painel, os **Lotes por fornecedor** e as **Requisições pendentes** ligadas àquele fornecedor.

### Cadastrar unidades requisitantes

A unidade requisitante identifica **qual setor** pede material ao almoxarifado. Cadastrá-la é o que permite depois medir consumo por unidade nos relatórios gerenciais.

1. **Abra as unidades.** Menu **Estoque → Unidades requisitantes**. A lista traz **Código**, **Nome**, **Unidade administrativa** e **Situação** (Ativo/Inativo).
2. **Cadastre uma unidade.** Clique em **Nova unidade** e preencha **Código** e **Nome**; informe opcionalmente a **Unidade administrativa**, que agrupa a unidade nos relatórios de consumo. Deixe **Ativo** marcado e clique em **Salvar**. Para alterar, clique no lápis da linha.
3. **Use a unidade na requisição.** Ao cadastrar uma requisição de material, a unidade cadastrada aparece no campo **Unidade requisitante** — é essa amarração que alimenta os relatórios de consumo por unidade.

### Escolher o tipo de baixa e estornar

A baixa de material de consumo exige classificar **o motivo** da perda com a taxonomia usada no setor público, e permite desfazer um lançamento equivocado sem apagar o histórico.

1. **Classifique o motivo.** Em **Estoque → Baixas de estoque**, ao registrar uma **Nova baixa**, o campo **Motivo** oferece os tipos: **Cadastramento Indevido**, **Doação**, **Extravio**, **Inservível**, **Outros diversos**, **Outros motivos**, **Validade**, **Quebra** e **Roubo**. Escolha o que corresponde à perda — o motivo fica gravado na baixa e nos relatórios de baixa por período.
2. **Confira a baixa na lista.** Cada baixa registrada aparece no histórico abaixo do formulário, com o **Motivo** e o **Valor da perda**.
3. **Estorne uma baixa lançada por engano.** Na coluna **Ações** da lista, clique em **Estornar**: a quantidade volta ao saldo do almoxarifado e a linha passa a exibir o selo **Estornada**. O estorno preserva o registro — a baixa não é apagada, apenas revertida.

### Emitir relatórios de material de consumo e inventário geral

Além dos relatórios básicos de saldo e movimentação, a tela de relatórios traz um conjunto de exportações voltadas ao almoxarifado público — catálogo, atendimento de requisições, baixas, transferências e o resultado do inventário.

1. **Abra os relatórios.** Menu **Estoque → Relatórios de estoque** (**Relatórios de almoxarifado**). No topo, escolha o **Almoxarifado** e o intervalo **De / Até**; alguns relatórios usam filtros extras (uma contagem de inventário, um produto).
2. **Exporte o relatório de material de consumo.** No bloco **Exportações CSV**, além dos relatórios já citados na página anterior, clique no que precisar:
   - **Catálogo de material de consumo** — a relação do catálogo dos materiais de consumo cadastrados.
   - **Requisições atendidas / não atendidas** — o atendimento das requisições no período.
   - **Baixas por período** — as baixas de material realizadas no intervalo, com o motivo.
   - **Transferências por referência** — a movimentação de material entre almoxarifados.
   - **Inventário geral (contagem)** — o resultado consolidado de uma contagem de inventário.
   - **Movimentação mensal de bens (RMB)** — o demonstrativo mensal de movimentação de material.
3. **Baixe o arquivo.** O CSV é gerado com os filtros do topo aplicados quando fazem sentido para o relatório escolhido (por exemplo, o **Inventário geral** usa a contagem selecionada; o **Catálogo** ignora o intervalo de datas).

### Cadastrar e consultar o catálogo de materiais de consumo

O catálogo é a lista **oficial** dos materiais de consumo que a casa padroniza — cada item com código próprio, unidade e código de suprimento. É o que dá ao requisitante um item padronizado para escolher em vez de descrever o material com as próprias palavras; sem o catálogo preenchido, cada setor inventa a sua nomenclatura e a consolidação de consumo por material deixa de fechar.

1. **Abra o catálogo.** Menu **Estoque → Catálogo de consumo**. A **consulta é aberta** a qualquer usuário do portal — o item aparece no menu para todo mundo. A **manutenção** depende da permissão de gestão de estoque: sem ela, o botão **Novo item** e as ações por linha simplesmente não são exibidos, e a tela funciona como consulta. Se a consulta for negada, a tela mostra o **erro** com a opção de tentar de novo — e não uma lista vazia, que se leria como "não há nada cadastrado".
2. **Busque e filtre.** No bloco **Catálogo**, use **Buscar** (por código ou nome) e **Situação** (**Todos**, **Ativo** ou **Inativo**); o botão **Limpar filtros** aparece quando há algum filtro aplicado. A grade é paginada no servidor e vem ordenada por **Código** — clique no cabeçalho de **Código** ou **Nome** para reordenar. As colunas são **Código**, **Nome**, **Unidade**, **Grupo**, **Código de suprimento** e **Situação**; itens inativos aparecem em tom apagado. Quando não há nenhum item, a grade informa "Nenhum item de catálogo cadastrado ainda".
3. **Cadastre um item.** Clique em **Novo item**. Abre a gaveta **Novo item do catálogo**, com o aviso de que o código é único entre os itens ativos\:Clique em **Salvar**: a gaveta fecha e o item passa a constar na consulta. Sair pela tecla Esc, pelo **Cancelar** ou clicando fora com edição pendente pede confirmação antes de descartar.
   - **Código** — obrigatório, até 40 caracteres. Não pode repetir o código de outro item **ativo** (o sistema recusa).
   - **Nome** — obrigatório, até 200 caracteres.
   - **Descrição** — opcional, até 600 caracteres.
   - **Unidade** — opcional, até 16 caracteres (ex.: UN, CX, KG).
   - **Grupo** — opcional; a lista vem dos **grupos de produto** cadastrados na página [Cadastros gerais (parceiros e produtos)](docId:6xpQsdWQ2NTyI40BFqDS-). Se a lista falhar em carregar, a tela **avisa que está incompleta** em vez de parecer que não há grupos.
   - **Produto** — opcional; vincule ao produto do cadastro ([Cadastros gerais (parceiros e produtos)](docId:6xpQsdWQ2NTyI40BFqDS-)) quando o material **já for item de estoque**. Deixe em branco quando ainda não for. Um produto inexistente é recusado.
   - **Código de suprimento** — opcional, até 32 caracteres.
4. **Corrija ou inative.** O lápis da linha reabre a gaveta como **Editar item do catálogo**. A ação de **inativar** pede confirmação e tira o item da consulta de ativos **sem apagar o registro** — a mesma linha passa a oferecer **reativar**, e a reativação só é aceita se o código não tiver sido tomado por outro item ativo nesse meio tempo. Uma recusa aparece como mensagem abaixo da grade: a linha nunca fica silenciosamente igual.

:::BlockQuote
**O catálogo e o cadastro de produtos são registros distintos.** O item de catálogo pode apontar para um produto (campo **Produto**) ou existir sozinho. Consequência prática na exportação: o CSV **Catálogo de material de consumo** (passo 66) é gerado a partir do **cadastro de produtos** ([Cadastros gerais (parceiros e produtos)](docId:6xpQsdWQ2NTyI40BFqDS-)), não desta tela — para conferir o catálogo em si, use a própria consulta desta tela com o filtro de situação.
:::

## Verificação

***

Você sabe que funcionou quando:

- O saldo do produto na área **Saldos de estoque** bate com o último movimento somado às transferências, reservas, baixas e ajustes.
- Após uma transferência, o produto desce na origem e sobe no destino, com a mesma data e a mesma quantidade.
- Uma reserva **Liberada** reduz o disponível na quantidade reservada (disponível = físico − reservado).
- Uma baixa registrada com motivo diminui o saldo e o **Valor da perda** aparece no razão contábil.
- Um inventário conciliado deixa o saldo do sistema igual ao chão (zero divergências em aberto).
- O razão contábil ([Contabilidade](docId:08cbTyrT0WXBp4ymvrog_)) mostra os lançamentos de cada movimento de entrada, saída, baixa e ajuste.
- Em **Estoque → Catálogo de consumo**, o item recém-cadastrado aparece na grade com a situação **Ativo**, e continua encontrável pela busca por código ou nome.

## Erros comuns

***

- **Estoque insuficiente na transferência ou reserva** — você pediu mais do que existe no depósito de origem. O sistema bloqueia e informa o disponível (X) versus o solicitado (Y). Confira o saldo antes ou registre a entrada que falta.
- **Movimento exige endereço (bin)** — o depósito está marcado com "Movimentos exigem bin", mas você deixou o campo **Endereço** vazio. Escolha um bin cadastrado ou desmarque a exigência na ficha do depósito.
- **Comissão de inventário recusada** — a composição não atende à regra: são necessários pelo menos 3 membros e exatamente 1 presidente. Também é recusado o servidor que atua no almoxarifado sendo inventariado (segregação de funções, Lei 4.320/64). Ajuste os papéis/membros até os contadores do rodapé ficarem verdes.
- **Código de depósito ou de lote duplicado** — o sistema rejeita um código de depósito já existente e um código de lote repetido no mesmo produto. Use um código novo.
- **Período fechado** — você tentou lançar um movimento num intervalo já fechado. Reabra o período de armazenagem ou lance na competência corrente.
- **Item em contagem** — enquanto um inventário está em andamento, o item fica bloqueado para movimentação até a contagem ser encerrada.
- **Inventário com muitas divergências** — normalmente significa movimento não lançado em algum lugar (compra sem recebimento, venda sem baixa). Investigue a origem antes de confirmar os ajustes.
- **Código de catálogo já em uso** — dois itens **ativos** não podem dividir o mesmo código. Se o código antigo pertence a um material que saiu de linha, **inative** aquele item antes de reaproveitar o código; e pelo mesmo motivo a **reativação** é recusada quando o código já foi tomado nesse meio tempo.
- **Não vejo o botão "Novo item" no catálogo de consumo** — a consulta é aberta, mas cadastrar, editar e inativar exigem a permissão de gestão de estoque. Sem ela a tela funciona só como consulta; peça a permissão em [Administração](docId\:Z8SS7r6Bvhs09rP1SPxUD).


[title] DevOps e deploys
[path] Aplicações/Agility/Produtos e releases/

:::BlockQuote
Acompanhe execuções de pipeline por ambiente, preserve tentativas e leia métricas de frequência, lead time e falhas.
:::

:::hint{type="info"}
**Pré-requisito:&#x20;**

Abra uma release existente. Para disparar pipeline real, é necessário vincular um projeto GitLab e uma branch ou tag; sem vínculo, é possível registrar uma execução manual.
:::

***

A aba DevOps do detalhe da release conecta a versão ao histórico de deploys. Cada execução é um registro próprio, com pipeline, commit, branch, ambiente, situação, início, duração, tentativa e origem. Reexecutar acrescenta uma nova tentativa e nunca sobrescreve o registro anterior.

Os cartões derivam métricas do histórico: frequência de deploy por semana, lead time até produção, taxa de falha e última execução em produção. Em caso de falha aberta, a tela troca a frequência pelo tempo da falha e sinaliza promoção bloqueada; isso explica por que uma release não pode avançar para Entregue.

***

### Passo a passo

::::WorkflowBlock
:::WorkflowBlockItem
**Abrir a aba DevOps**

No detalhe de uma release, clique em DevOps. O cabeçalho continua exibindo versão, situação e os cartões de data, desvio e features. Na faixa Execuções de pipeline, observe o estado do GitLab, o vínculo de projeto/ref e o botão de ação principal.
:::

:::WorkflowBlockItem
**Entender o vínculo GitLab**

Sem vínculo, a faixa apresenta Vincular GitLab. Clique no botão para abrir o diálogo e busque um projeto visível para a credencial do tenant; a busca é feita no GitLab. Selecione o projeto e informe Ref (branch/tag), normalmente main, depois confirme em Vincular. Com o vínculo salvo, a faixa mostra caminho do projeto e ref e o botão passa a disparar na forja.
:::

:::WorkflowBlockItem
**Disparar ou registrar a primeira execução**

Com GitLab vinculado, use Executar pipeline para disparar uma execução real na forja. Sem vínculo, o botão é Registrar execução e cria um registro manual usando pipeline, commit, branch e ambiente informados no histórico disponível. Essa distinção de origem evita apresentar uma execução local como se fosse um pipeline vivo.
:::

:::WorkflowBlockItem
**Ler a tabela de deploys**

A coluna Execução identifica o pipeline e o código da execução e mostra commit, branch, origem e responsável quando conhecidos. Ambiente separa Dev, Homologação e Produção; Início e Duração registram o tempo; Tent. mostra o número da tentativa; Situação usa Pendente, Executando, Sucesso, Falha ou Cancelado.
:::

:::WorkflowBlockItem
**Filtrar o histórico**

Use a busca da tabela para procurar por pipeline, commit, branch ou responsável. Os filtros Origem, Autor, Ambiente e Situação funcionam como lentes sobre o histórico completo; filtrar não remove execuções da coleção e não provoca nova sincronização com a forja.
:::

:::WorkflowBlockItem
**Reexecutar sem perder a tentativa anterior**

Quando já há histórico, o botão muda para Reexecutar pipeline, Reexecutar manualmente ou Reexecutar o código da falha. Em qualquer caso, uma nova execução é acrescentada e a anterior permanece na tabela. Se a falha estiver aberta, o código e, quando conhecido, o passo que falhou aparecem na mensagem de apoio.
:::

:::WorkflowBlockItem
**Acompanhar sincronização**

Quando a release tem projeto GitLab, o Agility reconcilia o histórico uma vez por vínculo após carregar os dados. Sincronizado com o GitLab na carga confirma a reconciliação; Sem sincronização — o histórico pode estar defasado indica que a forja não respondeu, mas mantém o histórico local legível.
:::

:::WorkflowBlockItem
**Ler os indicadores de entrega**

Frequência de deploy mostra a quantidade por semana e Lead time até produção mostra os dias entre a entrega e a chegada à produção. Taxa de falha resume a porcentagem de execuções com falha. Sem falha aberta, o quarto cartão informa Última em produção; com promoção bloqueada, ele informa Promoção bloqueada e o tempo de Falha aberta há.
:::

:::WorkflowBlockItem
**Usar o histórico para liberar a release**

Uma execução com sucesso em Produção é o fato que permite promover a release para Entregue. Depois de confirmar o sucesso, volte ao botão Mudar situação no cabeçalho, informe data e resultados realizados e confirme a entrega. Se o deploy falhar, corrija a causa e use Reexecutar, preservando a tentativa com falha para auditoria.
:::

:::WorkflowBlockItem
**Desvincular o GitLab quando necessário**

O chip do projeto vinculado contém o caminho e a ref e oferece o ícone de desvincular. Use-o quando a release precisar acompanhar outro projeto ou ref; depois refaça o vínculo pelo botão Vincular GitLab. Sem vínculo, o histórico local continua disponível e novas execuções usam o modo manual.
:::
::::

:::hint{type="success"}
:FontAwesome[]{icon="fa-solid fa-check"} **Verificação**

- A tabela mostra ao menos uma execução com pipeline, commit/branch, ambiente, situação, duração e número de tentativa.
- Uma reexecução cria uma nova linha e mantém a tentativa anterior no histórico.
- Os cartões exibem frequência de deploy, lead time, taxa de falha e última execução em produção, ou sinalizam falha aberta/promoção bloqueada.
- Com GitLab vinculado, o cabeçalho mostra projeto e ref e o botão indica Executar pipeline; sem vínculo, indica Registrar execução.
- Depois de um sucesso em Produção, Entregue fica disponível no diálogo Mudar situação da release.
:::

:::hint{type="warning"}
:FontAwesome[]{icon="fa-solid fa-triangle-exclamation"} **Erros comuns**

**Disparo sem projeto GitLab**

O Agility informa Vincule um projeto GitLab antes de disparar o pipeline. Vincule um projeto e uma ref válidos ou use Registrar execução para documentar um deploy manual.

**GitLab não configurado ou indisponível**

Os chips GitLab não configurado e GitLab indisponível representam estados distintos. No primeiro caso, peça a configuração da integração do tenant; no segundo, aguarde a disponibilidade e tente novamente. O histórico local continua legível.

**Ref ou pipeline recusado pela forja**

Ref vinculada inexistente exige revincular a release a uma branch/tag existente. Se o pipeline for rejeitado, confira .gitlab-ci.yml, rules e permissões da ref antes de reexecutar.

**Promoção bloqueada após falha**

Quando a última execução relevante falha em Produção, o cartão Promoção bloqueada e o código da falha explicam o bloqueio. Reexecute para criar nova tentativa; não apague a execução com falha, pois a tabela é histórico imutável.

**Métricas exibidas como travessão**

Sem amostra suficiente, métricas como frequência, lead time ou última produção aparecem como —, e a tabela pode informar Nenhuma execução registrada. Registre ou execute o primeiro deploy para gerar o histórico.
:::




[title] Portal de conhecimento
[path] Aplicações/ERP/Manual do Usuário/

O treinamento presencial — curso, turma, instrutor, presença — está na página [Treinamento e desenvolvimento](docId\:l_tQrAZuK18Nvhj7OCUT9). Esta página trata do **conteúdo digital**: o material que a pessoa consome sozinha, na tela.

## Biblioteca de aprendizagem

***

**Menu:** Biblioteca de aprendizagem · **Rota:** /learning-contents

### O que a tela guarda — e o que ela não guarda

A biblioteca guarda o **registro** do material, não o material. É a decisão que define esta parte do produto:

- o **vídeo** continua hospedado onde já está, e aqui fica só o endereço dele;
- o **pacote de e-learning** é importado num formato de mercado, sem editor próprio;
- a **ferramenta de autoria** é de terceiro e abre de dentro do portal.

Construir reprodutor, editor e hospedagem de vídeo seria reconstruir uma indústria inteira. O que a organização ganha aqui é parar de distribuir material por link solto em e-mail.

### Cadastrar um conteúdo

1. Abra **Biblioteca de aprendizagem** no menu.
2. Clique em **Novo conteúdo** e dê um **nome**.
3. Escolha o **tipo**. **O formulário muda com ele** — cada tipo pede coisas diferentes\:TipoO que a tela pede**Arquivo nosso**o identificador do anexo enviado**Pacote de e-learning**o anexo do pacote e a **edição** (SCORM 2004 4ª edição ou SCORM 1.2)**Ferramenta externa**endereço, identificador de cliente e identificador de implantação**Questionário**o **banco de questões** que ele apresenta**Vídeo hospedado fora**apenas o endereço
4. Escolha o **curso**, ou deixe em **Biblioteca compartilhada** (veja a armadilha abaixo).
5. Declare o **idioma do conteúdo** e, se souber, a **duração** estimada em minutos.
6. Salve.

### Armadilhas

**O campo de curso vazio não é esquecimento.** Um material pertence a **no máximo um curso**. Material que serve a vários — o vídeo de integração, por exemplo — é guardado **sem curso**, na biblioteca compartilhada, e alcançado pelas trilhas. Se você o amarrar a um curso, os outros cursos precisarão de uma cópia, e as cópias vão divergir.

**A ferramenta externa exige os três campos.** Endereço, identificador de cliente e identificador de implantação. Faltando qualquer um, quem recusa o acesso é a **ferramenta do outro lado**, longe desta tela, com uma mensagem que ninguém aqui consegue interpretar. Por isso o sistema recusa antes, nomeando o campo que falta.

**Trocar o tipo de um conteúdo já cadastrado apaga o que o novo tipo não usa.** Um material trocado de ferramenta externa para vídeo perde o endereço da ferramenta — e passa a parecer correto sem abrir. A tela avisa antes de salvar.

**O questionário não tem banco próprio.** Ele aponta para o **mesmo** banco de questões que o teste de conhecimento de turma usa (página [Treinamento e desenvolvimento](docId\:l_tQrAZuK18Nvhj7OCUT9)). Questionário de trilha e teste de turma são o mesmo artefato em contextos diferentes — um segundo banco seria um segundo lugar para a mesma pergunta divergir da própria resposta.

**O arquivo de abertura do pacote não é digitado.** Ele é lido do manifesto do pacote na importação, e por isso aparece bloqueado.

### Aposentar, não apagar

Não existe excluir. Um material é **aposentado**: sai das opções de montagem de trilha e continua nomeável por tudo que já o usou. Apagar a linha deixaria o treinamento concluído de alguém apontando para um material que ninguém consegue nomear.

### Histórico

Cada conteúdo tem **Histórico deste conteúdo**, com o antes e o depois de cada alteração. É onde se responde *quem trocou o endereço do vídeo de integração, e quando* — pergunta que aparece quando o material é de consumo obrigatório.

### Quem pode o quê

Ler a biblioteca acompanha a leitura do cadastro geral, porque quem planeja o desenvolvimento da equipe precisa consultar o que existe antes de pedir. **Cadastrar e alterar** exige a mesma autoridade do catálogo de treinamentos: dizer de que material a organização ensina é o mesmo ato editorial que dizer o que ela ensina e quem entrega.

## Como se entra no portal de conhecimento

***

**Não existe login do portal de conhecimento.** Isso é a resposta, não uma pendência.

Quem entra no ERP entra pelo **provedor de identidade da organização** — o mesmo diretório que governa os outros sistemas. Chegando aqui, a pessoa já está identificada, e todas as telas de aprendizagem (biblioteca, trilhas, matrículas, certificados, evidência, pontuação, assistente) usam essa mesma identidade.

**O que a organização ganha com isso:**

- **uma senha a menos por pessoa.** Um LMS com senha própria significa uma senha esquecida a mais por colaborador, e um lugar a mais de onde ela vaza;
- **desligou no diretório, desligou aqui.** Não existe "conta de treinamento" sobrevivendo ao desligamento, porque não existe conta separada para sobreviver;
- **auditoria com um nome só.** O ator na trilha de auditoria é a mesma pessoa do diretório.

### O que ainda é decidido dentro do ERP

O diretório diz **quem é** a pessoa. Ele não diz **o que ela pode fazer** — essa parte é do ERP, e fica em **Alçada** (/authorization-rules), regra por operação e por cargo. É por isso que dois colaboradores autenticados do mesmo jeito veem coisas diferentes: quem monta a trilha precisa da autoridade do catálogo de treinamentos; quem só faz o treinamento não precisa de autoridade nenhuma — basta estar matriculado.

### Armadilhas

**"Sair" encerra a sua sessão no ERP, não no provedor.** O botão invalida o seu acesso aqui e **inutiliza o token**, mesmo antes de ele vencer sozinho — largar só o cookie deixaria uma chave ainda válida circulando. Encerrar a sessão **no provedor de identidade** é feito pelo portal por onde você entrou, que é quem é dono do login. Em máquina compartilhada, saia também por lá.

**Sem autoridade não é o mesmo que sem login.** Uma tela que responde *"Você não tem autorização para esta operação"* está reconhecendo você — o que falta é regra de alçada, e quem resolve é o administrador em **Alçada**, não o diretório.

## Validar um pacote de e-learning

***

**Onde:** dentro do conteúdo, no bloco **Pacote SCORM** — só aparece quando o tipo é **Pacote de e-learning**.

O pacote é um .zip que a ferramenta de autoria do fornecedor gerou. Antes de ele valer como material de trilha, o sistema o **lê inteiro** e responde se serve.

### Como validar

1. Anexe o .zip ao conteúdo (campo do anexo, no bloco de cima).
2. No bloco **Pacote SCORM**, clique em **Validar pacote**.
3. Se o pacote servir, a tela mostra o **arquivo de abertura** — que nunca é digitado, é lido do manifesto — e **corrige a edição** para a que o pacote declara.

**A edição que você escolheu no cadastro é um palpite até aqui.** O cadastro pede a edição porque naquele momento ninguém leu o pacote ainda. A validação lê, e se você tiver escolhido errado ela **troca sem perguntar** — o manifesto é a fonte, não o formulário. Verificado: um pacote cadastrado à mão como *SCORM 1.2* passou a *SCORM 2004 4ª edição* depois de validado.

### Cada recusa diz o que está errado

Isto é o que mais economiza tempo aqui. "Pacote inválido" manda o analista de volta ao fornecedor sem nada nas mãos; cada recusa abaixo é um problema diferente, com um conserto diferente:

| A tela diz                                 | O que aconteceu                                                                | O que fazer                                                           |
| ------------------------------------------ | ------------------------------------------------------------------------------ | --------------------------------------------------------------------- |
| **não é um pacote compactado**             | o arquivo enviado não é um .zip — geralmente um PDF ou o vídeo                 | envie o .zip que a ferramenta de autoria gerou                        |
| **não traz o imsmanifest.xml**             | é um .zip, mas não é um pacote SCORM — é comum alguém compactar a pasta errada | compacte a pasta que **contém** o manifesto, não a pasta acima dela   |
| **não declara nenhum arquivo para abrir**  | o manifesto existe mas não aponta nenhuma tela                                 | o pacote saiu incompleto da autoria; peça outro                       |
| **traz um caminho que sai de dentro dele** | o pacote tenta gravar fora da própria pasta                                    | **não use este pacote** e avise a segurança — veja a armadilha abaixo |

### Armadilhas

**Nada é gravado antes de o pacote passar.** Um pacote inválido que ficasse registrado diria ao analista que o curso está publicado, e quem descobriria o problema seria a pessoa que fosse fazer o treinamento. Por isso o registro do arquivo de abertura só acontece depois da leitura completa.

**O pacote recusado por caminho perigoso é recusado INTEIRO, não limpo.** Um arquivo chamado ../ dentro de um pacote é tentativa, não erro de digitação — o resto daquele pacote não merece confiança. A tela não oferece "importar mesmo assim".

**A prévia mostra o curso rodando, não uma amostra dele.** As imagens, folhas de estilo e scripts que o pacote carrega **viajam dentro da própria página** — inclusive os que ele monta enquanto roda, que é como as ferramentas de autoria (Storyline, Rise, Captivate) geram quase todo endereço. O servidor embute tudo antes de mandar, porque a moldura é isolada e, sozinha, não conseguiria buscar arquivo nenhum.

**E o pacote encontra a API do SCORM.** Isso não é detalhe: um pacote que não acha a API não desenha errado — ele **se recusa a abrir**, e o aluno recebe "LMS not found". Quando o pacote reporta conclusão ou nota, a tela mostra o que ele disse, logo abaixo da moldura.

| Quando                              | O que acontece                                         | O que fazer                                                           |
| ----------------------------------- | ------------------------------------------------------ | --------------------------------------------------------------------- |
| o pacote montado passa de **24 MB** | a prévia é **recusada por inteiro**, com essa mensagem | o pacote continua válido e matriculável — é a prévia que não o mostra |

**A conclusão ainda é registrada por quem administra a trilha.** O pacote informa que terminou e a tela mostra esse relato, mas quem grava o progresso do aluno é a tela de acompanhamento da trilha. Isso é escolha, não esquecimento: a prévia é do catálogo, e ali não existe matrícula de ninguém para gravar contra. Quem está na trilha marca o passo como concluído do mesmo jeito que marca um vídeo — e **o progresso vale igual**; só não é automático.

### Por que o conteúdo abre numa moldura isolada

O pacote é HTML e JavaScript que **outra empresa escreveu**, aberto na tela de alguém que está logado no ERP. A moldura onde ele roda é isolada de propósito: o conteúdo **não consegue** ler a sua sessão, os seus dados nem esta página, e qualquer chamada que ele faça ao sistema chega sem identidade nenhuma.

Isso é o que permite aceitar material de fornecedor sem que aceitar material de fornecedor signifique dar a ele as chaves do sistema.

## Abrir uma ferramenta de fora (LTI 1.3)

***

**Menu:** Ferramentas externas · **Rota:** /lti-tools

Quando o curso não é um arquivo nosso mas uma **ferramenta de terceiro** — uma ferramenta de autoria, um curso de fornecedor —, o colaborador abre essa ferramenta de dentro do portal e chega lá **já identificado**, sem uma segunda senha.

### Cadastrar a ferramenta

1. Abra **Ferramentas externas** e clique em **Cadastrar ferramenta**.
2. Dê um **nome** e um **identificador de cliente** — este último é o nome pelo qual a ferramenta vai conhecer este ERP. **Ele não muda depois.**
3. Informe os **dois endereços da ferramenta**: onde o acesso começa (*login*) e para onde a resposta volta (*retorno*). Os dois vêm da documentação da ferramenta.
4. Informe também o endereço das **chaves públicas dela**, se souber. Não é usado para abrir o curso; é o que vai permitir ela devolver nota mais adiante.
5. Salve. O sistema gera **um par de chaves só desta ferramenta**.
6. Ligue o conteúdo à ferramenta: em **Biblioteca de aprendizagem**, tipo **Ferramenta externa**, com o mesmo identificador de cliente.

### A metade que acontece do outro lado

**É aqui que a maioria das tentativas para.** Cadastrar só metade não dá erro nenhum nesta tela — o lançamento é que falha, no fornecedor, com uma mensagem que ninguém aqui consegue interpretar.

No bloco **O que configurar na ferramenta** ficam as duas coisas que você precisa **copiar** para a tela da própria ferramenta:

- o **identificador da chave**;
- a **nossa chave pública**.

Só isso permite a ferramenta conferir que o acesso veio mesmo desta organização.

### Armadilhas

**A chave privada não está nesta tela, e não está em nenhuma.** O que aparece é a metade pública. A metade privada é o que prova que somos nós — quem a tivesse poderia se passar por qualquer pessoa desta organização diante de qualquer ferramenta contratada.

**Trocar a chave interrompe todos os acessos àquela ferramenta** até a chave nova ser colada do outro lado. É ato para quando a antiga puder ter sido exposta, nunca rotina — e por isso é botão separado do **Salvar**.

**O endereço de retorno é conferido, não aceito.** Se a ferramenta pedir um endereço diferente do cadastrado, o acesso é **recusado**. Sem essa conferência, bastaria alguém pedir a entrega em outro endereço para receber uma afirmação assinada por nós sobre uma pessoa real.

**Cada acesso vale uma vez e por poucos minutos.** Recarregar a página no meio do caminho ou voltar pelo histórico do navegador produz *"este lançamento já foi usado"* — abra o curso de novo pela trilha. É de propósito: um acesso que pudesse ser repetido seria um jeito de entrar como outra pessoa.

**O que sai desta organização:** um **identificador** da pessoa e o curso que está sendo aberto. **Não** vão o nome, o e-mail, o cargo nem a avaliação de desempenho. Uma ferramenta que cumprimenta pelo nome vai cumprimentar por um código — o preço, dito, de não mandar dado pessoal para fora.

**O conteúdo criado lá não volta sozinho.** Você abre a ferramenta de autoria daqui e cria o material lá; **cadastrar o resultado na biblioteca ainda é passo manual**. O padrão prevê a volta automática (*Deep Linking*) e ela não está implementada.

### Escolher o material dentro da ferramenta

Em vez de criar o material lá e **copiar o endereço à mão** para cá, abra a ferramenta pelo botão **Escolher material na ferramenta**, escolha ou crie o que quiser, e confirme. O que você selecionou volta **cadastrado na biblioteca**, apontando para a ferramenta certa.

**Pré-requisito:** a ferramenta precisa ter o endereço das **chaves públicas dela** preenchido no cadastro. É por ali que o sistema confere que a resposta veio mesmo dela — sem isso, a tela diz exatamente qual campo falta.

### Armadilhas

**A resposta da ferramenta é conferida antes de qualquer coisa ser gravada.** A resposta diz "cadastre este curso, neste endereço". Aceitar sem conferir a assinatura permitiria que qualquer um colocasse um endereço à escolha dele na biblioteca de um órgão público, para ser aberto por todo mundo que é obrigado a treinar. Assinatura que não confere → **nada é cadastrado**, e a tela diz isso.

**Cada escolha vale uma vez e por poucos minutos.** Recarregar a página de retorno ou voltar pelo histórico não cadastra de novo — cadastrar o mesmo material duas vezes é o jeito mais barato de encher a biblioteca de duplicata que ninguém escolheu.

**Voltar sem escolher nada é dito.** A tela avisa que nada foi selecionado, em vez de responder um sucesso silencioso que deixa você procurando o material que nunca chegou.

**Item sem endereço é recusado.** Material que não abre nada é curso quebrado com cara de publicado.

### A nota volta da ferramenta

Quando a pessoa termina o curso **na ferramenta**, a ferramenta avisa o ERP, e o passo da trilha fecha sozinho — sem ninguém marcar à mão.

**Como habilitar:** emita uma **chave de integração** para a ferramenta (em **Administração → Chaves de aplicação**) com a autoridade **Informar resultado de aprendizagem**, e configure essa chave do lado dela. O endereço para onde ela envia a nota **já vai dentro do próprio acesso** — a ferramenta o encontra sozinha, você não precisa copiar.

### Armadilhas

**Só a autoridade de informar resultado, nunca a do catálogo.** A chave que a ferramenta recebe autoriza **informar nota** e nada mais. Se ela recebesse a autoridade do catálogo, um servidor de terceiro poderia reescrever o que a organização ensina.

**Nota abaixo da média deixa o passo ABERTO.** Ela é registrada como reprovação — com nota e data — e a pessoa pode tentar de novo. Nada é apagado: apagar a tentativa faria a trilha mentir sobre o que aconteceu.

**Nota fora da escala é recusada, não aparada.** Ferramenta que devolve 120 de 100 tem defeito, e aparar para 100 esconderia esse defeito dentro do histórico de treinamento de alguém, onde ele passa a parecer fato.

**A escala da ferramenta não importa.** 8 de 10 e 80 de 100 valem a mesma coisa aqui — a conversão é feita no ERP, então duas ferramentas com escalas diferentes não produzem resultados diferentes para o mesmo desempenho.

**Curso aberto fora de uma trilha não recebe nota de volta**, e isso é de propósito: sem matrícula não há passo para a nota fechar. O acesso simplesmente não leva endereço de retorno — publicar um endereço sem destino faria a ferramenta reportar com sucesso para lugar nenhum.

**Isto não é o padrão AGS completo.** O endereço vai no formato do padrão, mas a autenticação é a chave de integração deste ERP, não o fluxo OAuth2 que o padrão descreve. Na prática: funciona com a ferramenta que a organização **configura**, e uma ferramenta de prateleira não vai encontrar sozinha o caminho de autenticação. A troca para o padrão completo, se um dia for contratada uma ferramenta que exija, é mudança de autenticação — não redesenho.

## Trilhas de aprendizagem

***

**Menu:** Trilhas de aprendizagem · **Rota:** /learning-tracks

Uma trilha é uma sequência de material com um **alcance**: quem tem de fazer, e em que ordem.

### Escolha o alcance antes de tudo

| Alcança por            | Quem entra                                                         |
| ---------------------- | ------------------------------------------------------------------ |
| **Uma competência**    | quem ocupa **qualquer** posto cujo perfil exija aquela competência |
| **Um posto**           | quem ocupa aquele posto                                            |
| **Uma unidade**        | quem está lotado nela                                              |
| **Todos em atividade** | toda a organização — a trilha de integração obrigatória            |

**Prefira competência, e o motivo não é arrumação.** Posto e cargo são a mesma coisa neste sistema. Uma trilha digitada por posto tem de ser digitada uma vez por cadeira, e na primeira atualização algumas cópias são alteradas e outras não — ninguém percebe, porque **trilha desatualizada é idêntica a trilha atual**. Dizendo qual competência a trilha desenvolve, são os perfis de posto que decidem quem precisa dela, inclusive postos criados no ano que vem, **sem ninguém editar a trilha**.

### Montar a trilha

1. Abra **Trilhas de aprendizagem**, clique em **Nova trilha** e informe código e nome.
2. Escolha **alcança por** e, conforme o caso, o alvo.
3. Salve e abra a trilha.
4. Em **Passos, em ordem**, acrescente cada passo: material digital da biblioteca **ou** turma presencial do catálogo de treinamentos. Os dois convivem na mesma sequência — uma trilha de integração costuma ter os dois.
5. Marque se o passo é **obrigatório** e, se for o caso, de qual passo ele **vem depois**.
6. Use as setas para reordenar. A numeração é reescrita pelo sistema e nunca fica com buraco.

### Ler o cartão "Quem isto alcança"

Ele mostra três números juntos, de propósito:

- **Alcança hoje** — quantas pessoas a trilha atinge agora;
- **Passos** — quantos passos ela tem;
- **Medido em** — o dia da medição.

**Alcance zero não é necessariamente erro.** É legítimo quando nenhum posto ocupado exige aquela competência ainda — e é também exatamente o que parece um alvo apontando para a coisa errada. Confira o alvo antes de concluir. **Trilha sem passos alcança gente e não ensina nada**, por isso os dois números ficam lado a lado. E o **dia** importa: o alcance muda a cada transferência e a cada perfil de posto editado, então um número anotado semana passada não se compara com o de hoje sem saber a data.

### Armadilhas

**Pré-requisito circular é recusado na hora de salvar.** Se A espera por B, B por C e C por A, ninguém consegue começar a trilha — e descobrir isso quando um colaborador trava significaria que a trilha já foi publicada para todo mundo que ela alcança. A recusa nomeia o passo que fecha o ciclo.

**Um passo só pode esperar por outro passo da mesma trilha.** Apontar para outra trilha deixaria o bloqueio invisível nesta tela.

**Não se remove um passo do qual outro depende.** Apagar a dependência em silêncio descartaria uma regra que alguém escreveu; mantê-la deixaria um passo esperando algo que não existe mais. Ajuste o dependente primeiro.

### Histórico

**Histórico desta trilha** guarda o antes e o depois de cada alteração — inclusive de alargamentos de alcance, que é o que um auditor pergunta depois que alguém deixou de ser treinado.

## Matrícula automática

***

**Menu:** Matrícula automática · **Rota:** /learning-enrollments

Uma **regra permanente** matricula quem a **trilha dela** alcança, e reaplica **toda noite**. Assim, quem é admitido ou transferido no mês que vem entra sozinho, sem ninguém lembrar de fazer isso.

### A regra não escolhe o público

Quem decide para quem a trilha é já é a própria trilha. A regra só acrescenta duas coisas que o alcance não sabe dizer: **quando vence** e **se está ligada**. Uma segunda resposta sobre público seria mais uma coisa para discordar — e a discordância não apareceria em lugar nenhum.

### Criar e rodar

1. Abra **Matrícula automática** e clique em **Nova regra**.
2. Escolha a **trilha** e, se houver, o **prazo em dias** a partir da matrícula.
3. Salve. A regra passa a rodar toda noite.
4. **Rodar agora** aplica na hora, e devolve o relatório.

**Rodar duas vezes é seguro, e dá para ver.** A segunda execução relata as mesmas pessoas como *já matriculadas* e não cria nada. É essa propriedade que permite a varredura noturna existir.

### Ler o relatório da execução — o quarto número é o que importa

O aviso traz quatro números: **alcançados**, **matriculados**, **já matriculados** e **não avisados**.

**Avisar alguém exige que a pessoa tenha login**, e esse vínculo é opcional neste produto. Então uma execução pode matricular quarenta pessoas e **não conseguir avisar a maioria**. Elas passam a carregar um prazo que ninguém comunicou — e é por isso que o número aparece no mesmo aviso do sucesso, e não num log. **É sobre esse número que se age**: ou se vincula o login das pessoas, ou se avisa por fora.

### Armadilhas

**Prazo vazio é permitido e tem custo.** A regra matricula perfeitamente e **nunca lembra ninguém**. Certo para material opcional; silencioso para material obrigatório.

**Não se cria regra para trilha sem passos.** Prazo sobre material que não existe é obrigação que ninguém consegue cumprir — o sistema recusa nomeando a trilha.

**Uma regra por trilha.** Duas dariam dois prazos e dois lembretes para a mesma obrigação.

### Lembretes

Quem tem prazo se aproximando recebe aviso; quem passou do prazo recebe aviso de atraso e a matrícula passa a **Vencida** — reportada, nunca apagada, porque *quem era obrigado e não fez* é o que uma auditoria pergunta.

### Histórico

Na tela da **trilha** há dois históricos ligados a isto: **da regra de matrícula** (quem criou, quem pausou) e **das execuções** (o que cada rodada fez, incluindo quantos não puderam ser avisados). Ficam ali porque é a trilha que se abre para perguntar isso.

## Progresso de quem está matriculado

***

**Menu:** Trilhas de aprendizagem · **Rota:** /learning-tracks/\{id} — bloco **Progresso de quem está matriculado**

Fica na tela da **trilha**, logo abaixo dos passos, porque é a mesma sequência lida do outro lado: os passos dizem o que a trilha exige, e este bloco diz quem já cumpriu.

### Registrar

1. Abra a trilha e desça até **Progresso de quem está matriculado**.
2. Escolha a **pessoa matriculada**. A lista mostra **todos os passos da trilha**, não só os que ela tocou — um passo nunca iniciado aparece como **Não iniciado**, e é justamente esse que responde *o que falta*.
3. Em cada passo, use **Em andamento**, **Concluir** ou **Abaixo do mínimo**.

### A conclusão é apurada, nunca digitada

Não existe um campo "concluída" na matrícula. **A trilha está concluída quando todo passo obrigatório está concluído** — apurado dos passos a cada registro.

Isso tem uma consequência que surpreende e é correta: **acrescentar um passo obrigatório à trilha devolve para "em andamento" quem já a tinha concluído**. É reportado, não escondido. O certificado que a pessoa já tem **não é cassado** — ele registrou algo que era verdade quando foi emitido.

O contrário disso — um status digitado — continuaria dizendo "concluída" enquanto a trilha mudava embaixo, e a pessoa apareceria certificada num curso que não terminou, com a tela concordando consigo mesma.

### Armadilhas

**Passo opcional não segura a conclusão.** Ele conta para a pessoa e não conta para a obrigação.

**Trilha sem passo obrigatório nunca conclui.** Certificar alguém por uma trilha que não exige nada seria um documento que não atesta nada, então ela fica em andamento — não conclui sozinha.

**O pré-requisito barra de verdade.** Registrar um passo cujo pré-requisito não está concluído é recusado, e a recusa **diz a posição do passo que falta** — que é o número que a pessoa vê na tela dela.

**Matrícula cancelada não recebe progresso.**

## Certificados

***

**Menu:** Certificados · **Rota:** /certificates

O certificado sai de **concluir uma trilha** — todos os passos obrigatórios. **Não existe botão de emitir nesta tela**, de propósito: um botão aqui deixaria certificar alguém que não fez o trabalho, e o histórico mostraria o certificado sem conclusão nenhuma atrás dele.

### Conferir um certificado

1. Abra **Certificados**.
2. Digite o **número de série** impresso no documento e clique em **Conferir**.

**"Cassado" e "não encontrado" são respostas opostas, e a tela as separa.** *Cassado* quer dizer que o certificado foi real e foi retirado — numa data, por um motivo, ambos exibidos. *Não encontrado* quer dizer que aquele número de série **nunca existiu**, que é a cara de uma falsificação. Ler um como o outro é o erro caro desta tela.

O número de série não tem ano nem código de curso, e não usa **I**, **O**, **0** nem **1** — ele é lido em voz alta de um papel e digitado por outra pessoa.

### Validade — hoje sempre vazia, e a tela diz por quê

Nenhum certificado carrega validade hoje. A validade viria da **certificação que a trilha concede**, e a trilha ainda não registra qual é. Em vez de deixar em branco (que se lê como "não vence"), a tela escreve o motivo.

**Inventar uma validade seria pior que não ter nenhuma:** alguém é afastado de uma tarefa com base numa data de expiração.

### Cassar

Na tela do certificado, **Cassar** exige **motivo**. Ele fica no documento: quem conferir o número de série depois é avisado de que foi cassado, e a primeira coisa que pergunta é por quê.

**Cassado, nunca apagado.** A linha continua respondendo "existiu e foi cassado nesta data". Apagar responderia "nunca existiu" — que é falso e, pior, não confere com o papel que a pessoa tem na mão.

### Modelos de certificado

O modelo guarda **logotipo**, **assinatura** e **quem assina**. **Exatamente um é o padrão por vez** — o sistema rebaixa o anterior quando você promove outro. Dois padrões fariam a identidade visual do certificado depender de qual linha a consulta leu primeiro, e ninguém descobriria até duas pessoas imprimirem o mesmo curso com papéis diferentes.

O primeiro modelo salvo **vira padrão sozinho**, para que nenhum certificado saia sem identidade visual nenhuma.

**Diagramar o certificado visualmente ainda não existe.** Todo modelo imprime no mesmo layout — criar um segundo troca a assinatura, não o desenho.

### Histórico

Na tela do certificado há o histórico **do documento** — emitido quando, cassado por quem. Ele é a evidência por trás do número de série: quem apresenta o papel está pedindo para ser acreditado, e é esse histórico que responde a um questionamento. Na tela de certificados, clicar no nome de um **modelo** abre o histórico dele — quem trocou o signatário é uma pergunta sobre documentos que já estão na mão das pessoas.

## Evidência de treinamento

***

**Menu:** Evidência de treinamento · **Rota:** /learning-evidence

Responde a uma pergunta só, e é a que uma auditoria faz: **o que foi estudado neste período?**

### A tela sempre diz quantos registros examinou

Escolha **De** e **Até** e clique em **Examinar**. O aviso no topo do resultado traz o número de registros encontrados — **inclusive quando é zero**.

Isso não é enfeite. *"Nada foi estudado"* e *"a consulta não rodou"* são idênticos numa tabela vazia, e só um dos dois é um achado. Por isso o zero aqui vem escrito por extenso: *examinei o período inteiro e não encontrei nenhum registro*.

### O que a tela mostra

- **Pessoas que estudaram** — quantas pessoas distintas fizeram alguma coisa no período.
- **Horas registradas** — ver a armadilha abaixo.
- **Trilhas concluídas** — quantas conclusões de trilha aconteceram.
- **Por o que aconteceu** e **por de onde veio** — a contagem por tipo de evento e por origem (registrado aqui, pacote SCORM, ferramenta externa, turma presencial).
- **Trilhas concluídas no período**, com quantas pessoas concluíram cada uma.

### Os painéis NÃO ficam aqui

Taxa de conclusão, engajamento e horas são **métricas do catálogo de indicadores da organização**. Crie um indicador sobre elas e ganhe **meta, histórico e farol**, ao lado de todos os outros indicadores do órgão — inclusive compondo **fórmula própria** com métricas de outras áreas, que é como se monta um KPI personalizado.

Um segundo painel nesta tela seria um segundo lugar para o mesmo número discordar de si mesmo.

### Armadilhas

**Horas são o que foi REGISTRADO, não o tempo gasto.** Um passo cujo reprodutor não informou duração contribui com **nada** em vez de uma estimativa — porque uma hora chutada fica indistinguível de uma hora medida assim que entra na coluna, e este número acaba numa defesa de orçamento. O que a tela mostra é um **piso**.

**Conclusão de trilha é diferente de passo concluído.** Alguém pode ter estudado bastante e não ter concluído trilha nenhuma: concluir uma trilha é terminar **todos** os passos obrigatórios dela.

**Um período sem conclusão não é um período sem estudo.** As duas contagens estão na tela lado a lado justamente por isso.

### Quem aparece com nome

O relatório do período **não nomeia ninguém**, de propósito: o que uma pessoa estudou, quando e quanto tempo levou é comportamento individual.

Ver **quem** concluiu uma trilha é um clique a mais no nome da trilha — e exige a alçada do **catálogo de treinamento**, que é mais estreita que a alçada de ler o cadastro. Quem não a tem enxerga as contagens e lê, na própria tela, que os nomes foram omitidos e por quê.

### Quanto tempo o registro dura

Todo evento de aprendizagem é guardado. Uma varredura noturna remove, depois de **dois anos**, apenas os eventos de **início** — que é onde está o volume, um por vídeo aberto. **Conclusão, aprovação, reprovação e comparecimento nunca são removidos**: é neles que está o valor de prova, e uma regra que apagasse por idade acabaria apagando justamente a evidência de que o treinamento obrigatório aconteceu.

## Pontos, selos e ranking

***

**Menu:** Pontos e selos · **Rota:** /gamification — e a área do colaborador em **Meus treinamentos** (/my-trainings)

Trilha obrigatória se cumpre por dever. O que faz alguém fazer a trilha opcional é outra coisa: reconhecimento, progresso visível, um pouco de disputa saudável.

### Nada pontua enquanto não houver regra

Essa é a primeira coisa a saber. Em **O que vale quanto**, diga quantos pontos vale **concluir um passo** e quantos vale **concluir a trilha inteira**. Enquanto a lista estiver vazia, a gamificação inteira está silenciosamente desligada — as pessoas concluem trilhas e não ganham nada.

Pontos precisam ser **maiores que zero**: regra que vale nada não faz nada e parece que faz.

**Iniciar um passo não pontua**, de propósito. Ponto por abrir vídeo premiaria clique, e o ranking classificaria quem clicou mais.

### Selos

Um selo tem **código**, **nome**, uma **condição** (trilhas concluídas ou pontos acumulados) e um **limite**.

**O código é a identidade, e não muda.** Renomear o selo é seguro — quem já o tem continua tendo. Trocar o código o tiraria de todo mundo que o ganhou, porque é o código que fica gravado no que foi concedido.

**Selo criado depois é concedido a quem já passou do limite.** Ninguém precisa ganhar de novo.

### O ranking — três estados, e o do meio é o motivo de não ser um liga-desliga

| Configuração                      | O que a pessoa vê                                                           |
| --------------------------------- | --------------------------------------------------------------------------- |
| **Não mostrar ranking**           | só os próprios pontos e selos; **nenhuma** comparação                       |
| **Só a minha posição** *(padrão)* | a própria colocação e quantas pessoas estão na disputa, **sem nome nenhum** |
| **Ranking completo**              | a classificação com os colegas, em ordem                                    |

Ranking **expõe o desempenho individual de um servidor com nome**. O que motiva alguns constrange outros. *"Só a minha posição"* atende o requisito com o mínimo disso, e é por isso que é o padrão — escolher o ranking completo é um ato deliberado, e a tela avisa o que ele mostra antes.

**Desligar é imediato e completo.** Não existe ranking guardado atrás da configuração: ele é calculado na hora em que alguém pede. Com ele desligado, o sistema **recusa** o ranking em vez de responder lista vazia — lista vazia se leria como *"ninguém pontuou"*, o que é falso.

**Em "só a minha posição", as outras pontuações não chegam ao navegador.** Não estão escondidas na tela: o servidor não as envia. Esconder na tela ainda mandaria a pontuação de todo mundo em ordem, e quem lê uma resposta de rede recolocaria os nomes.

### Conceder pontos é uma decisão separada de comparar

**Conceder pontos e selos** pode ser desligado sem apagar nada do que as pessoas já ganharam — útil enquanto as regras estão sendo reescritas.

### Ponto não é nota de desempenho

Nada disto é lido pela avaliação de desempenho, **de propósito**. Um estímulo que vira critério deixa de ser estímulo e passa a ser uma medida que as pessoas otimizam.

### O que o colaborador vê

Em **Meus treinamentos**, o bloco **Meus pontos e selos** mostra o total, os selos, a posição (quando a organização mostra) e o histórico de como chegou lá — cada linha dizendo por qual conquista os pontos vieram.

## Layout do certificado

***

**Menu:** Certificados · **Rota:** /certificates — bloco **Layout do certificado**, do modelo escolhido na tabela

Escolha um modelo na tabela **Modelos de certificado** e o bloco de layout aparece abaixo.

### Áreas fixas, não arrastar e soltar

Os elementos são colocados em **áreas** — cabeçalho, título, corpo e as três posições de rodapé —, e não posicionados livremente com o mouse.

Isso é uma escolha, não uma limitação de pressa: posicionamento livre exige uma prévia fiel, e a prévia fiel é a parte difícil. **Dois desenhadores divergem**, e a divergência só aparece num documento que já foi entregue a alguém — o analista aprovou uma prévia e o impresso saiu diferente, e ninguém sabe dizer desde quando. Com áreas fixas, a prévia é desenhada **pelo mesmo código do servidor** que imprime o certificado emitido. Ela não pode mentir.

### Dois elementos não podem faltar

**Nome de quem concluiu** e **nome do curso**. Sem o primeiro o documento não identifica ninguém; sem o segundo não atesta nada. O sistema recusa o layout **dizendo qual está faltando** — um certificado que parece pronto e não prova nada é pior que um que não salvou.

Também é recusado o **mesmo elemento duas vezes** (sairia impresso duas vezes) e a **linha livre sem texto**.

### O layout é salvo inteiro

*"O nome está no certificado?"* é uma pergunta sobre o layout, não sobre uma linha. Por isso ele é gravado de uma vez — salvar elemento por elemento deixaria uma janela em que um certificado poderia ser emitido sem nome.

### Prévia com dados fictícios

A prévia usa **Maria da Silva** e um curso de exemplo. Nenhum certificado real de alguém é usado para experimentar um layout.

### Sem layout, ainda sai documento

Um modelo sem layout imprime num formato simples com **nome, curso e número de série**. A alternativa seria página em branco para uma conclusão que de fato aconteceu.

### Certificado cassado imprime a cassação na cara dele

Na tela do certificado, o bloco **O certificado como ele é impresso** mostra o documento. Se ele foi cassado, o motivo aparece **no próprio documento** — um cassado que imprimisse igual a um válido seria uma falsificação produzida pelo próprio sistema.

## O mesmo curso em vários idiomas

***

**Menu:** Biblioteca de aprendizagem · **Rota:** /learning-contents/\{id} — bloco **Versões em outros idiomas**

### O sistema NÃO traduz

Ele mantém conectadas as versões que a **sua organização produziu**. Prometer tradução automática seria prometer qualidade sobre a qual ninguém tem controle, em material usado para **certificar pessoas** — e palavra errada em curso de segurança não é erro de digitação.

### Vincular é decisão de uma pessoa

1. Cadastre o material na outra língua, **com o idioma declarado**.
2. Abra esse material e, em **É versão de**, escolha o material original.
3. **Vincular**.

O vínculo nunca é adivinhado. Um vínculo errado faz um curso contar como **outro** no histórico de alguém — e o histórico é o que uma auditoria lê.

**Desvincular existe** e é importante: sem ele um vínculo errado seria permanente, e o único remédio seria apagar material para o qual o histórico de alguém aponta.

### Recusas que você vai encontrar

**Versão sem idioma declarado é recusada** — sem idioma ela nunca poderia ser escolhida para ninguém, e ficaria no grupo parecendo cobertura que não existe.

**Dois materiais no mesmo idioma dentro do mesmo grupo** são recusados: a escolha passaria a depender de qual linha foi lida primeiro.

### Quem não tem versão no idioma dele é AVISADO

Se alguém usa o sistema em espanhol e o curso só existe em português, recebe a versão padrão **e é informado de que não há versão no idioma dele**. Substituir em silêncio é como alguém assiste a um curso numa língua que não lê enquanto o sistema registra como feito.

### Conclusão conta uma vez só

Concluir **qualquer** versão conta como concluir o curso. Um passo da trilha é **um** passo, qualquer que seja a versão assistida — ninguém precisa fazer o mesmo curso duas vezes para cumprir uma obrigação.

## Plataforma de IA

***

**Menu:** Plataforma de IA · **Rota:** /ai-provider

Aqui a organização instala o token da plataforma de IA que **contrata**, escolhe o modelo e decide se o conteúdo pode sair.

### O produto não faz inferência nenhuma

Ele monta a pergunta e o contexto da trilha e **pergunta à sua plataforma**. Qualidade, custo e tratamento de dados são daquela plataforma, sob o contrato que a sua organização tem com ela.

### O token entra e nunca mais volta

Depois de instalado, o token **nunca é exibido de novo** — nem para quem o instalou. A tela mostra apenas os **quatro últimos caracteres**, que servem para reconhecer qual chave está instalada e não servem para mais nada.

**Deixe o campo vazio para manter o token instalado.** Como a tela nunca recebe a chave, ela não tem como devolvê-la; vazio significa "não mexa". Se significasse "apagar", toda edição do modelo desinstalaria a credencial em silêncio, e o assistente pararia de responder por um motivo que ninguém ligaria à edição.

Para remover de fato, use **Remover o token** — e note que isso também **desliga** o assistente, porque sem chave ele falharia na primeira pergunta.

O token é guardado **cifrado**, nunca aparece em log e **nunca entra no snapshot da trilha de auditoria**: o que a trilha guarda é quem mexeu, qual plataforma, qual modelo e os quatro caracteres visíveis.

### A lista de modelos vem da plataforma, não do nosso código

Assim, um modelo novo aparece aqui **sem versão nova do sistema** — e um modelo aposentado some. Quando a lista não pode ser lida (sem token, sem rede, token recusado), a tela **diz o motivo** e deixa você digitar o identificador à mão. Uma combo vazia se leria como *"esta plataforma não tem modelos"*, o que nunca é verdade.

### O conteúdo saindo da organização é uma decisão, com nome

Quando alguém pergunta ao assistente, **o material da trilha e a pergunta que a pessoa digitou são enviados para fora desta organização**, para a plataforma de IA.

Isso precisa ser **aceito por alguém, com nome**, num controle próprio — separado do formulário que troca o modelo, para não ser algo que se concorda enquanto se faz outra coisa. O nome e a data ficam registrados e vão para a trilha de auditoria.

**Enquanto não for aceito, nada é enviado** e o assistente simplesmente se declara indisponível. A aceitação é o que **abre** a chamada, não um aviso ao lado dela. Ela pode ser **retirada** a qualquer momento.

### Por que o assistente não está respondendo

O aviso no topo diz **qual** das condições falta, e não apenas que está indisponível:

| Motivo                              | O que fazer                                |
| ----------------------------------- | ------------------------------------------ |
| nenhuma plataforma configurada      | preencher e salvar                         |
| nenhum token instalado              | instalar o token                           |
| nenhum modelo escolhido             | escolher ou digitar o modelo               |
| o assistente está desligado         | ligar em **Assistente ligado**             |
| ninguém aceitou que o conteúdo saia | aceitar, com nome, no bloco de privacidade |

### Uma configuração de IA para o produto inteiro

**Esta tela governa toda funcionalidade de IA do sistema, não só o assistente de treinamento.** Até 2026-08-11 havia duas configurações que não se conheciam: a das despesas, num arquivo que o time de infraestrutura editava, e esta, que o cliente preenche. Dava para a organização contratar uma plataforma numa e ter a outra chamando outra — ou nenhuma.

**Escolha a plataforma na combo:** *Anthropic (Claude)*, *OpenAI* ou *Ollama (na rede da organização)*. A lista de **modelos** é lida da plataforma escolhida, com o token da própria organização — cada uma responde essa pergunta de um jeito, e o sistema sabe falar com as três.

**O Ollama não pede token**, e essa é a diferença que importa para quem tem exigência de dado não sair: ele roda na rede da própria organização, então nada trafega para fora. As outras duas são hospedadas, e por isso exigem o aceite nominal descrito acima.

**Se a organização não preencher esta tela**, o sistema ainda respeita o que estiver no arquivo de configuração da instalação — é o que mantém funcionando quem já tinha modelo ligado por lá. Assim que alguém preenche aqui, **o que vale é esta tela**.

## O assistente

***

**Menu:** Meus treinamentos · **Rota:** /my-trainings — bloco **Assistente**

Escolha **sobre qual trilha**, digite a pergunta e clique em **Perguntar**. O assistente responde sobre **aquela trilha** e o que fazer nela em seguida — ele não é um chat de propósito geral dentro do sistema.

### Indisponível diz o motivo, e a trilha continua servindo

Se a organização não contratou plataforma, não instalou o token, não escolheu o modelo, desligou o assistente ou **não aceitou que o conteúdo saia**, o bloco diz **qual** dessas coisas falta e aponta de volta para a trilha: *"siga os passos em ordem, de onde você parou"*.

Isso é de propósito. Uma caixa que abre e não responde é pior que caixa nenhuma — a pessoa espera, tenta de novo e conclui que o sistema está quebrado.

### O que sai da organização é dito em toda resposta

Vão para a plataforma de IA: **o nome da trilha**, **quais passos ela tem e onde você está neles** e **a pergunta que você digitou**. Isso aparece embaixo de cada resposta — não é um aviso mostrado uma vez no começo.

**O que NÃO vai:** o seu nome, o seu cargo e a sua avaliação de desempenho. O assistente responde "o que eu faço nesta trilha", e qualquer coisa além disso seria dado pessoal saindo sem finalidade.

### Nada do que você perguntar fica guardado

Nem a pergunta nem a resposta são armazenadas. Um registro pesquisável do que cada pessoa não entendeu seria um problema de privacidade maior que a própria consulta.

**O custo disso está dito:** a organização não consegue reconstruir depois o que foi enviado. O que fica auditável é a **configuração** — quem instalou o token e quem aceitou que o conteúdo saia.

### Só a sua trilha

Você só pode perguntar sobre matrícula **sua**. Uma matrícula de outra pessoa responde *não encontrada* — e não *sem permissão*, porque dizer "sem permissão" já confirmaria que ela existe.

[title] Cadastro trabalhista (contrato de trabalho)
[path] Aplicações/ERP/Manual do Usuário/

# Cadastro trabalhista (contrato de trabalho)

:::BlockQuote
Pré-requisitos: [Cadastro fiscal próprio01 — Cadastro fiscal próprio](docId\:Q-zx6Qk4pMFD09yrhmsve), porque a **empresa empregadora** e os seus estabelecimentos precisam existir antes; e o bloco **Empregados** de [Administração](docId\:Z8SS7r6Bvhs09rP1SPxUD), porque a **pessoa** precisa estar cadastrada antes de ganhar um contrato.
:::

## Introdução

***

O **cadastro trabalhista** é a área em que a organização registra o **vínculo** entre uma pessoa e a empresa que a contratou. Até aqui o sistema sabia **onde** cada pessoa está — o departamento, o cargo, o centro de custo — e não sabia que ela tinha sido **contratada**: não havia data de admissão, não havia matrícula, não havia empresa empregadora. Essas informações viviam numa planilha ao lado, e era nela que o pessoal de RH consultava desde quando alguém é empregado, por qual empresa e com qual matrícula.

O **contrato de trabalho** é o registro que abre essa área, e é dele que tudo o mais passa a pendurar: remuneração, jornada e escala, afastamentos, férias, movimentações, dependentes e as declarações obrigatórias enviadas ao governo. Guarde uma distinção que atravessa todo o módulo: **a pessoa não é o contrato**. A pessoa é cadastrada uma única vez — o *CPF* é único no cadastro e o sistema recusa duplicá-lo —, enquanto o vínculo é um registro à parte. É por isso que a mesma pessoa pode ter **mais de um contrato** (dois vínculos simultâneos, ou o vínculo novo depois de uma transferência entre empresas do grupo) sem que ninguém precise cadastrá-la duas vezes.

## Passo a passo

***

### Abrir a relação de contratos

1. **A separação é deliberada, e é por causa da auditoria.** Quem só **consulta** — o auditor que confere quem registrou cada contrato e o que mudou desde então — recebe a primeira autoridade e **não** vê o botão **"Novo contrato"**: cadastrar e editar exigem a segunda. Fosse uma autoridade só, o auditor precisaria dela para abrir a relação e passaria a poder **criar e alterar** vínculos, aparecendo no próprio histórico como autor do registro que veio conferir.

**Se o item não aparece no menu, é autoridade e não ausência de dados.** São **duas** autoridades sobre o vínculo, e elas aparecem em **Administração → Perfis e permissões** com estes nomes: **"Consultar contratos de trabalho (sem poder cadastrar nem editar)"** (READ\_EMPLOYMENT\_CONTRACT) e **"Administrar contratos de trabalho (vínculo, matrícula, admissão)"** (MANAGE\_EMPLOYMENT\_CONTRACT). **Qualquer uma das duas** faz o item aparecer no menu e abre a relação. Quem não tem nenhuma delas não enxerga o item; e, se chegar à tela pelo endereço direto, recebe uma **recusa explícita** — nunca uma relação vazia, que passaria por "ainda não há contratos".

A relação vem ordenada pela **matrícula**, em ordem crescente; clicar em qualquer cabeçalho reordena por aquela coluna. São **10 linhas por página**. O campo de busca logo acima da tabela filtra pela matrícula, pelo nome da pessoa e pelo nome do empregador — e também pela categoria eSocial, ainda que ela não seja uma das colunas.

**O estabelecimento de lotação não é coluna da relação.** Ele é obrigatório no cadastro e fica gravado no contrato, mas só aparece quando você **abre** o contrato. Se o que você precisa é saber quem trabalha em qual unidade, abra os contratos um a um — a relação responde "quem, por qual empregador, desde quando e sob qual vínculo", e não "quem, em qual filial".

**Abra "Contratos de trabalho"** (/employment-contracts). No menu lateral, em **Recursos humanos → Contratos de trabalho**. A relação mostra, em cada linha e nesta ordem, a **matrícula**, a **pessoa**, o **empregador**, a **data de admissão**, o **tipo de vínculo** e a **situação**; a última coluna traz o botão de lápis (**Editar**) que abre o contrato.

### Registrar um contrato

1. **O botão "Salvar" nasce desabilitado** e só libera quando os **seis** campos obrigatórios estiverem preenchidos: pessoa, matrícula, empregador, estabelecimento, categoria eSocial e data de admissão. Se ele continua apagado, é um desses seis que falta — não é falha da tela.
   **Clique em "Novo contrato"** — o botão fica no alto da tela, à direita do título (abaixo dele, em tela estreita). Abre **"Novo contrato de trabalho"**: um formulário único, com os campos dispostos em duas colunas — uma só em tela estreita —, na ordem descrita a seguir.
2. **Diga de quem é o vínculo e com qual número.**
   - **Pessoa** — escolha entre os empregados já cadastrados. Se a pessoa ainda não existe, cadastre-a antes em **Recursos humanos → Empregados** e volte aqui.
   - **Matrícula** — o número (ou código) pelo qual essa pessoa é identificada dentro daquele empregador. Aceita até 30 caracteres; o sistema descarta espaços nas pontas e grava em caixa alta, de modo que a-1234 e A-1234 são a **mesma** matrícula. Leia a subseção "A armadilha", adiante, antes de decidir como numerar.
3. **Diga por qual empresa e em qual unidade.**
   - **Empregador** — a empresa do grupo que assina o contrato. É ela que responde pelo vínculo perante o governo, o banco e o sindicato, e é ela que delimita a matrícula.
   - **Estabelecimento** — a unidade em que a pessoa vai trabalhar, identificada pelo nome fantasia (ou pelo CNPJ, quando não há nome fantasia) seguido do número da filial. O campo fica **bloqueado até você escolher o empregador**, exibindo *"Escolha antes o empregador…"*; depois disso lista **só as filiais daquele empregador**. Trocar o empregador **limpa** o estabelecimento já escolhido — escolha-o de novo, não é erro da tela.
4. **Classifique o vínculo.**
   - **Categoria eSocial** — o código numérico da tabela de categorias de trabalhador do eSocial (por exemplo 101 para empregado geral, 901 para estagiário, 721 para diretor). O campo para de aceitar digitação no oitavo caractere. Nesta entrega o sistema confere apenas a **forma** do código (só dígitos, até 8); a conferência contra a tabela oficial e a coerência entre categoria e tipo de vínculo entram numa entrega seguinte.
   - **Tipo de vínculo** — *CLT* (que já vem selecionado), *Estagiário*, *Diretor estatutário* ou *Prestador de serviço*.
5. **Informe as datas.**
   - **Data de admissão** — o dia em que a pessoa começou a trabalhar para este empregador.
   - **Data para efeitos legais** — **deixe em branco no caso normal.** Ela só difere da data de admissão quando há **sucessão de empregador**: a pessoa muda de empresa dentro do grupo, mas o tempo de casa continua contando desde o vínculo anterior, e é essa data mais antiga que vale para décimo terceiro, férias e reajustes. Em branco, o sistema **adota a data de admissão** — o campo existe para você não ter de digitar a mesma data duas vezes em centenas de contratos, o que só produziria divergência por erro de digitação.
6. **Informe como o trabalho acontece.**
   - **Regime de registro de ponto** — *REP eletrônico* (que já vem selecionado), *Manual*, *Mecânico*, *Registro por exceção* ou *Dispensado de registro*. Este campo diz **como a marcação do ponto é feita**, e não qual é a jornada da pessoa: horário, escala e turma são cadastro próprio, com entrega própria.
   - **Modo de trabalho** — *Presencial* (que já vem selecionado), *Híbrido* ou *Remoto*.
7. **A situação e a data de desligamento não estão neste formulário — e a ausência é proposital.** O contrato **nasce Ativo**, e o processo de desligamento é entrega posterior; um campo em branco com cara de editável sugeriria que dá para encerrar o vínculo aqui. Os dois aparecem no **detalhe** do contrato, depois de gravado (passo 11).
   **Contrato que sucede — deixe em *Nenhum*.** O campo aponta para o contrato que este substitui e existe para a transferência entre empresas do grupo; o fluxo que o preenche com significado é entrega posterior. Ele só oferece **outros contratos da mesma pessoa**, identificados pela matrícula e pela data de admissão, e fica bloqueado enquanto você não tiver escolhido a pessoa ou enquanto ela não tiver outro contrato.
8. **Salve.** A tela volta para a relação e o contrato aparece nela como **Ativo**. A partir daí ele é *o* contrato daquela pessoa com aquele empregador — é a ele que a remuneração (passo 27), a jornada e o afastamento vão se pendurar.

### A armadilha: a matrícula é única por EMPREGADOR, não por filial

:::BlockQuote
**Duas filiais da mesma empresa não podem repetir a mesma matrícula.** Ainda que cada filial tenha o seu próprio *CNPJ*, com sufixo diferente, quem envia os dados ao governo usa a **raiz do empregador** — e o mesmo número de matrícula aparecendo em duas pessoas da mesma raiz faz o evento ser **RECUSADO**.**Por que isso engana.** É natural pensar que cada unidade numera os seus empregados a partir do 1, como cada uma tem CNPJ próprio. O sistema recusa essa numeração, e a recusa é o comportamento certo: se ela fosse aceita, nada erraria no dia do cadastro. O erro apareceria **meses depois**, na primeira remessa ao governo em que as duas matrículas se encontrassem — longe de quem cadastrou, e sem que a mensagem de recusa dissesse qual das duas está sobrando.**Na prática:** defina a faixa de matrículas **por empresa empregadora**, e não por unidade. Se as filiais precisam ser distinguíveis pela matrícula, use um prefixo dentro da mesma faixa (MTZ-0001, FIL-0001) em vez de reiniciar a contagem em cada uma.Quando você tenta gravar uma matrícula já ocupada, o sistema recusa **dizendo de quem é o contrato que já a usa** — não um "já existe" genérico —, e a recusa aparece embaixo do próprio campo **Matrícula**. Com o nome em mãos, você acha o outro contrato pela busca da relação e decide qual dos dois números está errado. E a mesma matrícula **em empregadores diferentes** é aceita normalmente: a exclusividade é por empregador, e só.
:::

### Registrar o segundo vínculo da mesma pessoa

1. **Repita os passos 2 a 9 escolhendo a mesma pessoa e outro empregador.** O sistema aceita, e os dois contratos passam a coexistir. O cadastro da pessoa **continua único** — não se cria uma segunda pessoa com o mesmo CPF, e é justamente por isso que o vínculo é um registro separado dela.

### Conferir o contrato e o seu histórico

1. **Clique no botão de lápis (*Editar*), na última coluna da linha**, para abrir o contrato. **A linha em si não é clicável** — quem navega é esse botão. A tela que abre chama-se **"Editar contrato de trabalho"** e traz a matrícula sob o título.São os mesmos campos do cadastro, com quatro diferenças\:Salvar aqui devolve você à relação, como no cadastro.
   - **A pessoa fica bloqueada.** Um contrato gravado não troca de titular; se a pessoa está errada, o caminho é outro contrato.
   - **O empregador também fica bloqueado.** Contrato gravado não troca de empresa empregadora. Levar a pessoa para outra empresa do grupo é **sucessão** — encerra este vínculo e abre outro, preservando o tempo de casa pela *data para efeitos legais* (passo 6) —, e não uma edição deste contrato. Trocar o empregador aqui inscreveria uma **transferência de estabelecimento** na trilha, que é a espécie errada para o fato (ver a tabela de espécies, adiante); o servidor recusa a troca, e o campo bloqueado é o que evita você chegar até a recusa. O caminho certo está nos passos 31 a 33, no cartão **"Vida funcional entre empregadores"**.
   - **Aparece a *Situação*** — *Ativo*, *Suspenso* ou *Encerrado*. Você a muda à mão; nesta entrega nenhum dos três estados é derivado de outro campo.
   - **Aparece a *Data de desligamento***, e ela é **apenas informativa**: preenchê-la não encerra o contrato nem muda a situação, e mudar a situação não preenche a data. O processo de desligamento propriamente dito é entrega posterior.
2. **O cartão só some para quem não tem autoridade sobre a trilha** — e não por falta de histórico. Quem consegue abrir esta tela tem essa autoridade, e portanto vê o cartão; contrato recém-criado mostra nele um evento, o da criação. Se o cartão aparece com uma mensagem de erro no lugar dos eventos, é falha de servidor, e há um botão para tentar de novo.

**Role até o cartão "Histórico", no fim da tela.** Ele lista os eventos do contrato — a ação, quem a fez e quando. **Clique em um evento** para abrir o painel lateral com o detalhe: o retrato do contrato no momento em que foi criado e, em cada alteração posterior, **o que mudou campo a campo**, com o valor antes e o valor depois. É esse painel que responde ao auditor quem mudou a matrícula, a lotação ou a data de admissão, e quando.

:::BlockQuote
**Esta ficha é longa, e você pode arrumá-la para o seu dia a dia.** O botão **"Personalizar"**, no canto superior direito, abre o painel que deixa **ocultar ou recolher** os cartões de *Remuneração*, *Vida funcional entre empregadores*, *Férias*, *Filiação sindical* e *Movimentações de pessoal*. É o mesmo mecanismo da ficha do parceiro, explicado passo a passo em *02 — Cadastros gerais*, e vale para **cada usuário**, sem depender de TI.**Nada vem escondido por padrão** — todos os cartões aparecem até você decidir o contrário, e **"Restaurar padrão"** desfaz tudo. Por isso as instruções abaixo continuam mandando *rolar até o cartão X*: se algum deles não estiver na tela, ou você o ocultou aqui, ou o seu perfil não tem permissão de vê-lo — e o painel de personalização **lista apenas os cartões que você pode ver**, o que é a forma de distinguir os dois casos.
:::

:::BlockQuote
\> \*\*O cartão "Histórico" e o cartão "Movimentação de pessoal" respondem a perguntas diferentes, e a mesma tela mostra os dois.\*\* O \*\*Histórico\*\* guarda \*\*toda\*\* edição do cadastro, campo a campo — inclusive a correção de um dígito da matrícula ou a troca do modo de trabalho. A \*\*movimentação\*\* guarda os fatos da \*\*vida funcional\*\*, e só eles: cada lançamento tem \*\*espécie\*\*, \*\*data de efeito\*\* e \*\*motivo\*\*. Corrigir um erro de digitação é histórico e não é movimentação; transferir a pessoa de unidade é as duas coisas. Os passos 23 e 24 tratam da trilha de movimentação.
:::

### Cadastrar as entidades sindicais

1. **São duas autoridades, pela mesma razão explicada no passo 1.** Em **Administração → Perfis e permissões** elas aparecem como **"Consultar relações trabalhistas (sindicatos e acordos coletivos)"** e **"Administrar relações trabalhistas (sindicatos, representação e acordos coletivos)"**. Qualquer uma das duas abre a relação; só a segunda mostra o botão de cadastro. Quem não tem nenhuma recebe uma **recusa explícita** ao abrir a tela — nunca uma relação vazia, que passaria por "ainda não há entidade cadastrada" e mandaria o analista cadastrar de novo o que já está lá.
   **Abra "Entidades sindicais".** No menu lateral, em **Recursos humanos → Entidades sindicais**. A relação mostra, em cada linha, o **nome** da entidade, o **código de registro sindical**, a **categoria representada**, a **abrangência territorial**, se ela representa **empregados** ou **empregadores**, e se está **ativa**.
2. **Não cadastre a entidade uma segunda vez "só para o RH".** Dois cadastros do mesmo CNPJ são duas verdades sobre a mesma entidade, e a primeira vez que o endereço ou a conta mudar só uma das duas será corrigida — a outra continuará respondendo, sem parecer errada, até o repasse voltar.
   **Clique em "Nova entidade sindical" e informe o CNPJ.** A entidade sindical **não é um cadastro de empresa novo**: ela é um parceiro do cadastro geral, o mesmo registro que o financeiro já usa para pagar o repasse da mensalidade descontada em folha. Se o CNPJ já existe lá — e normalmente existe, justamente porque a entidade recebe dinheiro —, o sistema **reaproveita o cadastro** e apenas lhe acrescenta o papel sindical: o endereço, o contato e o dado bancário continuam sendo **um só**.
3. **Complete o que é próprio do papel sindical.**
   - **Código de registro sindical** — o número pelo qual a entidade é identificada como sindicato.
   - **Categoria representada** — a categoria cuja representação a entidade detém. É ela que decide de quem aquele acordo é a regra.
   - **Abrangência territorial** — a base territorial em que a entidade representa essa categoria (o município, o grupo de municípios ou o estado).
   - **Representa** — *Empregados* ou *Empregadores*. **Este campo não é decorativo:** só as entidades de **empregados** são oferecidas quando se diz quem representa um contrato. Marcar *Empregadores* por engano faz a entidade sumir dessa escolha e parecer que ela nunca foi cadastrada.
4. **Esta tela é o catálogo das entidades.** A ligação entre um contrato e a entidade que o representa — com a data a partir da qual ela vale e a indicação de a pessoa ser ou não associada — é registro do contrato, e a tela dessa ligação é **entrega posterior**. Enquanto ela não chega, é o catálogo que sustenta o resto, porque é dele que os acordos coletivos dependem.

**Representação não é associação — e confundir as duas erra dos dois lados.** *Representação* é obrigatória e vem da categoria: quem é daquela categoria é representado, queira ou não, e é isso que decide **qual acordo vale** para a pessoa. *Associação* é voluntária: a pessoa se filia, paga mensalidade e pode se desfiliar em março, sem deixar de ser representada. Quem trata as duas como uma só desconta mensalidade de quem não é associado, ou aplica a regra errada a quem nunca se filiou.

**Entidade já citada não é apagada — é desativada.** Ao tentar remover uma entidade que algum contrato já citou, o sistema a marca como inativa: ela deixa de aparecer nas escolhas novas e **continua respondendo pelas consultas de datas passadas**. Apagá-la deixaria contratos antigos apontando para o nada, e uma folha refeita do ano passado sairia sem sindicato.

**Salve.** A entidade passa a ser oferecida nas escolhas e, a partir daqui, é dela que os **acordos coletivos** vão pendurar — a subseção seguinte depende deste cadastro.

### Cadastrar o acordo coletivo

Antes dos passos, o que está em jogo: **é deste cadastro que sai quase toda a regra de cálculo do módulo.** O divisor da hora — o número pelo qual se descobre quanto vale uma hora de trabalho daquela pessoa —, a janela em que o adicional noturno incide, quanto tempo vale uma hora dentro dessa janela e o percentual do abono de férias são os quatro **declarados no acordo**, não configurados no sistema. Quem monta a folha não digita nenhum deles: consulta.

1. **Abra "Acordos coletivos".** No menu lateral, em **Recursos humanos → Acordos coletivos**. A relação mostra o **identificador** do acordo, a **entidade** que o assinou, o **período de vigência** e a **base de horas** declarada. As autoridades são as mesmas duas do passo 13.
2. **Clique em "Novo acordo coletivo" e escolha a entidade que o assinou.** Só entidades **ativas** são oferecidas: um acordo pendurado numa entidade desativada ficaria inalcançável para os contratos — existiria no cadastro e não regeria ninguém.
3. É por isso também que **não existe campo "situação"**. Um acordo cadastrado com vigência a começar no ano que vem simplesmente não responde hoje, e passa a responder **sozinho** no dia da virada. Uma situação editável à mão faria o dia da virada depender de alguém lembrar de mudá-la.
   **Nada aqui é "o valor atual" — é "o valor deste acordo, deste dia até aquele".** Há um acordo novo pendente de homologação, e quando ele for assinado alguns destes números mudam. Quando isso acontecer, você **cadastra outra linha**, com a vigência nova: o acordo anterior continua respondendo pelas competências dele, e refazer uma folha do ano passado devolve os números do ano passado. **A mudança é de dado, não de sistema** — ninguém precisa alterar configuração nem esperar entrega nova.
   **Identifique o acordo e informe o período de vigência.** O **identificador** é o nome pelo qual o time chama o documento (por exemplo ACT 2024/2026); a **descrição** é a frase que distingue um acordo do outro na relação; a **vigência** é o dia em que o acordo passa a valer e o dia em que deixa de valer.
4. Ao lado da sua declaração, a tela mostra em campo **não editável** o **divisor mensal** a que ela chega: 40 horas por semana chegam a **200 horas**; 6 horas por dia chegam a **180 horas**, o mesmo que a base mensal de 180 horas declarada pelo outro acordo. **Confira esse número contra o texto do acordo antes de salvar.** É por ele que se descobre quanto vale uma hora daquela pessoa: errá-lo erra toda hora extra, todo adicional e todo desconto de falta de **todo mundo** representado por aquela entidade.
   **O divisor da hora difere por sindicato, e é por isso que ele é dado do acordo e não parâmetro do sistema.** Um dos acordos desta casa trabalha com **40 horas por semana**; o outro declara **180 horas por mês**. As duas bases estão certas — cada uma para o seu quadro —, e um campo único de configuração do sistema teria de escolher uma delas e errar a outra.
   **Declare a base de horas na unidade em que o próprio acordo a escreve** — por semana, por mês ou por dia. Digite o número e escolha a unidade; não converta nada.
5. **Declare os três valores que o acordo fixa.** Leia a subseção "A armadilha", logo adiante, **antes** de digitar — os três diferem do que a lei geral estabelece, e nenhum deles vem preenchido.
   - **Janela do período noturno** — a hora em que o período noturno começa e a hora em que termina. Nos acordos desta casa, **19:00** e **07:00**. A janela **atravessa a meia-noite**, e isso é normal: o sistema conta o tempo dos dois lados da virada.
   - **Duração da hora noturna** — quanto tempo vale uma hora contada dentro dessa janela. Nos dois acordos desta casa, **60 minutos**. O campo também aceita a hora reduzida da lei geral, de **52 minutos e 30 segundos** — e é por isso que ele é declarado com precisão de segundos, e não em minutos inteiros: arredondar para 52 ou para 53 minutos erraria cerca de 1% no adicional de todo o quadro.
   - **Percentual do abono de férias** — o percentual que o acordo declara sobre a remuneração das férias. Nos acordos desta casa, **45%**.
6. **Salve.** O acordo passa a reger, dentro do período informado, quem é representado por aquela entidade. **O sistema recusa a gravação enquanto qualquer um dos três valores acima estiver em branco** — e, ao recusar, não preenche nenhum deles com o valor da lei.

### A armadilha: os valores deste acordo NÃO são os da CLT

::::BlockQuote
**Os três números que a intuição erra estão escritos no acordo, e os três diferem do mínimo legal.**

:::Paragraph{listStyleType="disc" indent="1"}
**A janela do período noturno é das 19h às 7h**, e não das 22h às 5h da lei geral. Digitar a janela legal reduz à metade o tempo sobre o qual o adicional noturno incide — o adicional continua saindo, com cara de certo, e **quase pela metade** do devido.
:::

:::Paragraph{listStyleType="disc" indent="1"}
**A hora noturna vale 60 minutos.** A CLT reduz a hora noturna para 52 minutos e 30 segundos, mas no trabalho portuário essa redução **não existe** (Lei 4.860/1965, art. 4º, §1º) — e é o que os dois acordos declaram. Usar a hora reduzida infla o adicional em torno de **14%**.
:::

:::Paragraph{listStyleType="disc" indent="1"}
**O abono de férias é de 45%**, e não o um terço que a Constituição garante como piso. O acordo dá mais do que a lei; digitar o mínimo constitucional erra as férias do quadro inteiro **para menos**, que é o erro que vira passivo trabalhista.
:::

**Por que isso engana.** Cada um dos três tem um valor "que todo mundo sabe" — 22h às 5h, hora reduzida, um terço —, e é esse valor que a memória oferece quando o campo está em branco. O acordo é que manda, e ele diverge do mínimo legal nos três pontos.**É por isso que os três campos nascem vazios e são obrigatórios.** O sistema **não** os preenche com o valor legal por omissão, de propósito: um campo já preenchido com o mínimo sairia salvo sem ninguém reparar — verde no cadastro, errado no contracheque —, e o erro só apareceria **no holerite**, depois de fechada a competência, sem nada apontar para este cadastro.**Na prática:** preencha esta tela com o acordo assinado aberto na frente, campo a campo, e confira o divisor mensal exibido (passo 20) contra o texto antes de salvar. Um cadastro conferido uma vez evita conferir setecentos contracheques depois.
::::

### Declarar os percentuais de hora extra e do adicional noturno

20-A. **Na tela do acordo, role até "Percentuais de hora extra".** Declare um escalonamento **por tipo de dia** — dia útil, domingo, feriado, dia de repouso —, e dentro de cada tipo, por faixa: as duas primeiras horas a um percentual, as seguintes a outro. A hora extra em dia de repouso não é a mesma coisa que em dia útil, e o sistema trata as duas como declarações separadas porque o **piso legal delas é diferente**.

:::BlockQuote
\> \*\*Os mesmos 50% são legais na terça e ilegais no domingo.\*\* O piso do dia útil é o da Constituição (art. 7º, XVI): \*\*50%\*\*. O do domingo, feriado e dia de repouso vem da Lei 605/1949, art. 9º, com a Súmula 146 do TST: \*\*100%\*\*. Por isso a recusa \*\*nomeia o dispositivo\*\* em vez de dizer "abaixo do mínimo" — genérica, ela deixaria você sem saber sob qual norma está e qual número consertar.

\> \*\*A tela avisa o piso antes de você digitar, e mesmo assim não trava o botão.\*\* O aviso local é conveniência; a recusa que vale é a do servidor, porque é ela que nomeia a norma. Se o botão bloqueasse localmente, você nunca leria a frase que explica.
:::

20-B. **Declare o adicional noturno com a data em que passa a valer.** Publicar um novo percentual **não apaga o anterior**: a linha antiga é fechada na véspera e continua ali, respondendo pelas competências que ela regeu.

:::BlockQuote
\> \*\*A consulta é POR DATA, não "o valor de hoje".\*\* Se o acordo deu 40% até maio de 2025 e 45% a partir de junho, uma apuração de maio tem de receber \*\*40\*\* — e recebe. A tela mostra a linha do tempo inteira, marcando qual está em vigor hoje e quais foram conservadas.
:::

20-C. **Duas casas decimais, e a terceira é recusada.** Não é preciosismo: o banco arredondaria a terceira casa **em silêncio**, e o número digitado deixaria de ser o número pago sem que ninguém soubesse para que lado. Multiplicado por toda hora extra de setecentas pessoas, todo mês, o arredondamento aceito uma vez compõe indefinidamente. 62,5 continua válido — dois é limite, não exigência.

20-D. **Na tela do contrato, o cartão "Hora extra e adicional noturno deste vínculo" mostra o que ele resolve numa data.** Informe o dia e a quantidade de horas extras, e o cartão devolve a repartição por faixa com o percentual de cada uma.

:::BlockQuote
\> \*\*Fique atento à etiqueta da origem.\*\* Verde significa que o percentual veio do \*\*acordo\*\* do vínculo; amarelo significa \*\*piso legal\*\* — ninguém cadastrou aquele número, e provavelmente falta o instrumento coletivo. Ver 20% e achar que alguém declarou 20% é o engano que esta etiqueta existe para evitar.
:::

20-E. **Logo abaixo da filiação sindical, o cartão "Instrumento coletivo que cobre este vínculo" diz qual documento responde por ele hoje.** A filiação diz *quem representa a pessoa*; este cartão diz *qual acordo isso produz* — e é dele que saem os quatro números da subseção anterior. Ele mostra o código do instrumento, a descrição, desde quando está em vigor e **até quando cobre**.

:::BlockQuote
\> \*\*O vencimento é a parte que custa dinheiro, então é a parte que grita.\*\* Faltando 60 dias ou menos, o cartão passa a contar os dias e a \*\*nomear a primeira competência que vai rodar sem o instrumento\*\* — "a partir da competência 2026-09", e não apenas "vence em 31/08/2026". A diferença não é de estilo: um instrumento vencido \*\*não quebra nada\*\*. Ele simplesmente deixa de ser devolvido no mês seguinte, as rubricas de escopo sindical param de ser aplicadas, e a folha fecha, bate e paga menos. Nada fica vermelho no fechamento — por isso o aviso mora aqui, meses antes.

\> \*\*Instrumento já vencido é dito com outras palavras, de propósito.\*\* O cartão nunca escreve "vence em breve" sobre um acordo que já terminou: ele diz que \*\*deixou de cobrir\*\*, porque as duas frases pedem providências diferentes e trocá-las é como um fechamento sai errado.

\> \*\*"Nenhum instrumento coletivo cobre este vínculo" é uma resposta, não uma tela em branco.\*\* Quer dizer que na data de hoje a pessoa não tem representação registrada, ou que a entidade não tem acordo em vigor — e a consequência está escrita ali: \*\*só o mínimo legal se aplica\*\*. Se em vez disso aparecer uma mensagem de erro com botão de tentar de novo, é falha de servidor ou falta de autoridade sobre relações trabalhistas, que é caso diferente e por isso é mostrado diferente.
:::

### Registrar uma transferência de estabelecimento

1. **A data de efeito tem de cair dentro da vida do contrato** — entre a admissão e o desligamento. Fora desse intervalo o sistema recusa e informa o intervalo válido: uma transferência anterior à admissão descreveria alguém trabalhando numa unidade antes de ter sido contratada.
   **Só a troca de estabelecimento inscreve lançamento.** Corrigir a matrícula, ajustar a categoria, mudar o modo de trabalho, preencher a data de desligamento — nada disso entra na trilha de movimentação. Entra no cartão **Histórico**, como qualquer alteração de cadastro. A trilha não é o registro de toda edição: ela guarda as mudanças da vida funcional, e é essa seletividade que a mantém legível dois anos depois.
   **Abra o contrato pelo botão de lápis e troque o campo *Estabelecimento*.** É o mesmo formulário do passo 11. A troca de unidade pede mais dois dados, que existem só para esta mudança:
   - **Data de efeito** — o dia em que a pessoa **passou a trabalhar** na outra unidade. **Não é a data de hoje**, e não é o dia em que você está digitando. Informar a mudança com atraso é o caso normal, e a trilha guarda as duas datas separadas: o dia em que a mudança valeu e o dia em que ela foi registrada.
   - **Motivo** — por que a pessoa mudou de unidade. É **obrigatório**, e a subseção "O motivo é obrigatório", adiante, explica o que escrever nele.
2. **Quem não tem nenhuma das duas autoridades de movimentação vê uma recusa explícita no lugar da lista** — nunca uma trilha vazia. Uma lista vazia passaria por "esta pessoa nunca se movimentou" e mandaria o analista registrar de novo o que já está lá. As duas são as do passo 25.
   **O cartão não tem botão de "Novo lançamento", e a ausência é o desenho da coisa.** Lançamento não se digita: ele nasce da tela do fato — a transferência nasce da troca do estabelecimento (passo 23), a alteração salarial nasce do cartão de remuneração do próprio contrato (passo 28), a licença da tela de afastamento. Um botão que inscrevesse movimento à mão permitiria trilha e cadastro contarem histórias diferentes, e aí nenhuma das duas provaria coisa alguma.
   **Salve e role até o cartão "Movimentação de pessoal", no fim da tela do contrato.** Ele lista os lançamentos do mais recente para o mais antigo, e cada linha traz a **espécie**, a **data de efeito**, o **motivo** e **quem decidiu**. A transferência que você acabou de registrar é a primeira linha. **Clique no lançamento** para abrir o painel lateral com o detalhe daquele ato.

### Consultar a movimentação de toda a organização

1. **Nenhuma das duas dá acesso a criar, editar ou apagar lançamento** — nesta entrega não existe caminho para isso, para ninguém (ver "A armadilha: o lançamento é definitivo", adiante). O lançamento nasce da tela do fato e é autorizado pela autoridade **daquela** tela: a transferência de estabelecimento do passo 23 é autorizada por **"Administrar contratos de trabalho (vínculo, matrícula, admissão)"**, e não por estas duas.
   **As autoridades desta tela são próprias, e não são as de contratos.** São **duas**, e em **Administração → Perfis e permissões** aparecem como **"Consultar movimentação de pessoal (trilha de vida funcional)"** e **"Administrar movimentação de pessoal (registrar e corrigir a trilha)"**. **Qualquer uma das duas** abre a tela: a primeira é a do auditor, que só confere; a segunda é a de quem **provoca** as movimentações — quem transfere gente chega à própria trilha sem receber junto a leitura ampla do auditor. Ter autoridade sobre contratos de trabalho **não** abre esta tela, e é de propósito: a trilha carrega alteração salarial e motivo de afastamento, dado que nem todo mundo que consulta cadastro deve enxergar. Sem nenhuma das duas, a tela recusa o carregamento — explicitamente, e não como relação vazia.
   **Abra "Movimentação de pessoal".** No menu lateral, em **Recursos humanos → Movimentação de pessoal**. É a mesma trilha, vista pela organização inteira em vez de contrato a contrato: cada linha traz o contrato movimentado, a espécie, a data de efeito, o motivo e quem decidiu.
2. **Filtro que não devolve nada é resposta, não falha.** Um período em que ninguém se movimentou devolve nenhuma linha, e a tela diz que não há lançamentos. Se em vez disso aparecer uma mensagem de erro, aí sim é falha — e há como tentar de novo.

**Não há filtro por área nesta tela**, e a diferença importa para quem monta uma resposta de auditoria: a pergunta *"o que aconteceu na área de operações em março"* não se responde aqui. A trilha é por **vínculo**, e a área da pessoa muda ao longo do tempo — filtrar por ela exigiria decidir se vale a lotação do dia do lançamento ou a de hoje, e as duas respostas seriam defensáveis e diferentes. Para essa pergunta, comece pela lotação (bloco **Lotação** da ficha do empregado) e cruze com a trilha de cada vínculo.

**Filtre por período e por espécie.** São três campos — **Vigente de**, **Vigente até** e **Espécie** — e eles se combinam: "todas as promoções do semestre", "as transferências do ano", "tudo o que foi lançado em março". É esta tela que responde à pergunta da auditoria sem abrir setecentos contratos um a um.

### Registrar a remuneração do contrato

1. **As autoridades desta área são próprias, porque salário é dado sensível.** Em **Administração → Perfis e permissões** aparecem como **"Consultar remuneração do contrato (salário de cada empregado)"** e **"Administrar remuneração do contrato (registrar e alterar salário)"**. **Qualquer uma das duas** mostra o cartão; só a segunda mostra os botões — quem tem apenas a primeira **lê** a remuneração e não a altera. Para quem não tem nenhuma das duas, **o cartão de remuneração não aparece na tela** — e essa é a diferença que importa: ele não aparece **vazio**, que passaria por "esta pessoa não tem salário registrado" e mandaria o analista registrar de novo o que já está lá. O contrato abre normalmente; só a área de salário fica fora. E administrar contratos de trabalho **não** abre esta área: quem cadastra matrícula e lotação não recebe junto o salário do quadro inteiro.
   **Abra o contrato pelo botão de lápis e role até o cartão "Remuneração".** Ele mostra a remuneração **vigente** — o valor, a unidade, o tipo e o dia em que passou a valer — e, abaixo dela, as remunerações **anteriores**, cada uma com o período em que valeu. Contrato recém-cadastrado começa sem nenhuma: a remuneração é registrada aqui, não no formulário do contrato.
2. **Clique em "Registrar alteração salarial"** e preencha os cinco campos:
   - **Valor** — quanto a pessoa passa a receber, na unidade escolhida ao lado.
   - **Unidade** — *Mensal*, *Por hora*, *Diário* ou *Por tarefa*. Ela diz **a que período o valor se refere**, e o sistema **não converte** de uma para a outra por conta própria: um valor por hora continua sendo por hora em toda consulta. Quem transforma hora em mês é o **divisor** declarado no acordo coletivo (passo 20), que difere por sindicato — um divisor chutado devolveria um número que parece certo e não é.
   - **Tipo** — *Fixo*, *Variável* ou *Comissão*.
   - **Passa a valer em** — o dia a partir do qual o valor novo vale. **Não é o dia em que você está digitando.** Leia "A armadilha", adiante, antes de preencher: é este campo que decide qual valor a folha usa em cada mês.
   - **Motivo** — por que a remuneração mudou. É **obrigatório**, pela mesma razão do motivo da transferência (ver "O motivo é obrigatório", adiante).
3. **Salve, e confira que agora existem duas linhas.** A remuneração anterior aparece **encerrada na véspera** da data que você informou, e a nova aparece vigente a partir dela. **Nada foi apagado** — alterar salário não substitui o valor antigo, **delimita** o período em que ele valeu. É isso que permite reprocessar uma competência antiga com o valor que valia **naquela** data, e é isso que faz o dissídio retroativo funcionar: quem consultar março recebe o valor de março, mesmo depois de dois aumentos. Cada período guarda ainda quem o registrou e o que mudou nele — salário é a primeira coisa que uma auditoria pergunta.No mesmo instante, um lançamento de **Alteração salarial** aparece no cartão **Movimentação de pessoal** (passo 24), com o dia em que a mudança passa a valer, o motivo que você escreveu e o seu nome como quem decidiu. Não há o que digitar lá: o lançamento nasce daqui.
4. **Os dois botões descrevem fatos diferentes, e trocá-los estraga o registro.** Corrigir uma digitação com **"Registrar alteração salarial"** inscreve na trilha um aumento que nunca houve e parte a vigência em duas por causa de um erro de teclado. Registrar um aumento com **"Corrigir a remuneração vigente"** apaga o valor que valeu até ontem — e a competência passada passa a ser recalculada com o número de hoje. A pergunta que separa os dois é uma só: **o que a pessoa recebia antes estava certo?** Se estava, é alteração; se nunca esteve, é correção.

**Errou o valor digitado? Use "Corrigir a remuneração vigente".** Ele conserta o número da linha que está valendo, **sem** abrir período novo e **sem** inscrever alteração salarial na trilha — a correção aparece no cartão **Histórico**, campo a campo, como qualquer edição de cadastro.

## Registrar o vínculo perante a lei e conferir se ele pode ser declarado

***

**Categoria já gravada que não está mais na lista continua aparecendo**, marcada como *categoria registrada, fora da lista atual*. É deliberado: sumir com ela deixaria o combo vazio numa ficha que está certa, e a saída natural — escolher outra para a tela funcionar — reescreveria uma declaração histórica correta numa errada.

**A lista responde à data de ADMISSÃO, não a hoje.** Um vínculo admitido em 2019 obedece à tabela como ela era em 2019. Se a lista julgasse por hoje, um vínculo antigo e **correto** apareceria portando código descontinuado, e alguém "consertaria" um registro que estava certo. Ao mudar a data de admissão, a lista é consultada de novo.

**Os dois filtros existem por motivos diferentes, e nenhum é cosmético.** A Tabela 01 casa cada código com um tipo de vínculo — oferecer código de estagiário para um vínculo CLT é oferecer uma recusa. E código que o governo aposentou é outra recusa, com outra mensagem. O sistema barra os dois de qualquer jeito; a lista serve para você nunca mirar neles.

**A categoria do eSocial agora é escolhida numa lista, não digitada.** No formulário do contrato (passo 2), o campo **Categoria eSocial** oferece as categorias da **Tabela 01** publicada pelo governo. A lista é filtrada por **dois** critérios ao mesmo tempo: o **tipo de vínculo** escolhido logo abaixo, e a **data de admissão** informada.



**Por que não é só mais um campo do contrato.** Corrigir o número do livro depois de uma fiscalização é exatamente o ato que alguém vai ser chamado a explicar — por isso o registro tem cartão próprio e **histórico próprio**, logo abaixo, mostrando o que mudou campo a campo e quem mudou.

**Role até o cartão "Registro legal do vínculo" e clique em "Registrar".** O art. 41 da CLT obriga todo empregador a registrar seus empregados, e é isto que uma fiscalização do trabalho pede **primeiro**, antes de qualquer contracheque: é o que prova que o vínculo foi formalizado. São quatro campos:

:::Paragraph{listStyleType="disc" indent="2"}
**Forma** — *Sistema eletrônico*, *Livro encadernado* ou *Ficha avulsa*.
:::

:::Paragraph{listStyleType="disc" indent="2"}
**Número do livro** e **Folha** — **obrigatórios** para livro encadernado, e sem sentido nos outros dois: registro eletrônico não tem folha, e ficha avulsa não tem numeração de folha. As dicas dos campos dizem isso enquanto você escolhe.
:::

:::Paragraph{listStyleType="disc" indent="2"}
**Anotação na CTPS** — o dia em que foi anotado na carteira. Fica vazio enquanto não tiver sido.
:::



**Um item bloqueante em falta faz o evento voltar recusado**, e essa recusa não chega na hora: chega semanas depois, num lote inteiro, longe de quem deixou o campo vazio. É esse atraso que o cartão existe para encurtar.

**Não verificável nunca conta como atendido.** Contá-lo como atendido declararia o vínculo apoiado num fato que ninguém conferiu; contá-lo como faltando mandaria você caçar um campo que não existe em tela nenhuma. Por isso o cartão os separa e avisa, acima da lista, quantos são — **o selo verde não os cobre**.

**São três estados, nunca dois, e o terceiro é o que importa.** *Atendido* é o que foi conferido e existe. *Faltando* é o que foi conferido e não está lá — e você consegue resolver. **Não verificável** é outra coisa: significa que **nenhuma fonte respondeu** por aquela exigência, porque a parte do sistema que responderia ainda não existe.

**Confira o cartão "Pronto para declarar".** Ele lista, exigência por exigência, o que o evento de admissão precisa e o que está de fato registrado — e traz no alto um selo **Pronto** ou **Não pronto**.

## Horários de trabalho e a jornada do vínculo

***

**O intervalo é uma faixa de relógio, não uma duração.** "Das 12 às 13", não "60 minutos" — o intervalo tem de ficar em algum ponto do dia, e a duração sai da faixa sozinha.

**"Horário fixo" não é uma caixa que você marca.** Quando a janela de presença obrigatória cobre o expediente inteiro, o horário **é** fixo, e o evento do eSocial declara isso. Janela mais estreita significa horário flexível. Não há campo para escolher: o desenho decide.

**A tolerância não é preferência sua.** O art. 58 §1º da CLT a limita a **5 minutos por marcação e 10 por dia**. Acima disso ela deixa de ser perdão e vira tempo de trabalho não pago — o sistema recusa, nomeando o dispositivo.

**Publicar é VERSIONAR, não editar — e essa é a coisa que você precisa entender aqui.** Salvar com um **código que já existe** abre uma **versão nova** a partir da data informada; os dias anteriores continuam respondendo à versão antiga. É isso que faz uma marcação julgada em março continuar defensável em dezembro. E é isso que significa que uma tolerância "corrigida" **não conserta o passado** — ela governa a partir da data que você digitou, e só.

**Abra "Horários de trabalho"** (/work-schedules). No menu lateral, em **Recursos humanos → Horários de trabalho**. Cada linha é o desenho de **um dia**: quanto ele dura, o intervalo, a janela de presença obrigatória e as tolerâncias de marcação.

34-A. **Para quem trabalha em revezamento, abra "Escalas de revezamento"** (/work-schedule-cycles). No menu lateral, em **Recursos humanos**. Aqui não se desenha um dia: desenha-se um **ritmo** — quantos turnos o ciclo tem, quanto dura cada turno e quanto dura o descanso entre eles. Um 12×36 é um turno de 12 horas seguido de 36 de descanso; um 12×24, de 24.

:::BlockQuote
\> \*\*A escala é DERIVADA, nunca digitada.\*\* Depois de cadastrar o ritmo, informe um período e o sistema mostra os turnos que caem nele — calculados no servidor a partir do ciclo e da partida da turma. Não há tela para "montar a escala do mês": ela é consequência de dois fatos, e recalculá-la à mão é como as duas versões passam a discordar.
:::

34-B. **Cadastre uma turma para cada grupo que roda a mesma escala em fase diferente.** Cada turma tem um **nome**, uma **data de partida** (a âncora) e a **hora em que o turno começa**.

:::BlockQuote
\> \*\*A hora pertence à TURMA, não à escala — e não é detalhe.\*\* É ela que separa a turma do dia da turma da noite na mesma data. Se a hora ficasse no ciclo, as únicas fases possíveis num ciclo de 48 horas seriam 0 h e 24 h, e o par dia/noite do 12×36 seria \*\*impossível de registrar\*\*.

\> \*\*Partidas diferentes NÃO garantem turmas diferentes.\*\* Num ciclo de 36 horas, três dias são duas voltas completas: a escala sai idêntica. O cadastro recusa esse caso, nomeando-o — sem essa recusa o "cada turma tem a sua escala" seria esperança sobre o dado, não fato.
:::

34-C. **Mover a partida de uma turma para trás reescreve dias já trabalhados.** Por isso o ato exige a autorização de correção retroativa, pede **motivo escrito sempre** e é **recusado de vez** quando a folha daquela competência já foi fechada — nesse caso o caminho é retificar a folha, não o cadastro.

34-D. **Com uma escala aberta, o rodapé traz dois históricos, e eles respondem perguntas diferentes.** O **histórico da escala** diz quem declarou aquele ritmo e quando — a pergunta que uma fiscalização traz ao perguntar *desde quando este estabelecimento roda 12×24*. O **histórico da turma** aparece quando você escolhe uma turma, e diz quem moveu a partida dela, de quando para quando e com que motivo escrito.

:::BlockQuote
\> Até 07/08/2026 o primeiro \*\*não existia\*\*: as turmas deixavam rastro e a escala que elas seguem, não. Nada ficava vermelho — e a pergunta da fiscalização era respondida com uma lista de partidas de turma, que é resposta a outra pergunta.
:::

35\. **Abra o contrato e role até "Jornada do vínculo".** Escolha o dia de trabalho **ou a turma da escala de revezamento**, o **regime** (sujeito a horário, atividade externa, cargo de gestão ou teletrabalho), a data em que passa a valer e o motivo.

:::BlockQuote
\> \*\*É um ou outro, nunca os dois nem nenhum.\*\* O vínculo segue um horário fixo \*\*ou\*\* uma turma de revezamento, e o banco recusa a linha ambígua. Vínculo em turma faz o eSocial declarar \`tpJornada\` de \*\*revezamento\*\*, com a descrição montada a partir do ritmo e da turma — o mesmo vínculo em horário fixo declara "jornada com horário fixo", e em janela estreita, "flexível".

\> \*\*A carga semanal e a hora noturna ficam CONGELADAS na linha.\*\* São tomadas do instrumento coletivo vigente no momento da mudança e gravadas ali. Uma convenção nova \*\*não\*\* reescreve o que já foi declarado ao governo: o evento saiu com os números antigos, e um evento que não bate mais com o cadastro é uma rejeição que ninguém consegue explicar depois.
\>
\> \*\*Sem instrumento coletivo vigente, o sistema pede a hora noturna e recusa sem ela\*\* — em vez de supor uma. Ela é em \*\*segundos\*\*: 3150 é a hora reduzida do art. 73 §1º (52min30s), 3600 é a hora cheia que alguns acordos restauram. Arredondar para minutos erraria o adicional de todo o quadro em cerca de 1%.
\>
\> \*\*Vínculo sob garantia de emprego pede o reconhecimento por escrito.\*\* Trocar a jornada de uma gestante, de quem voltou de acidente, de cipeiro ou de dirigente sindical é possível — mas o sistema pede que você declare que sabe da garantia, e esse texto vai junto para a trilha.
:::

36\. **Confira o quadro "O que o evento do eSocial vai dizer".** Ele mostra o regime, o tipo de jornada, as horas semanais e o **descritivo** — a frase que será transmitida, montada a partir do desenho do dia.

:::BlockQuote
\> \*\*O tipo de jornada é DERIVADO, e é bom que seja.\*\* Oferecê-lo como escolha é exatamente onde um vínculo em 12×24 acaba declarado como 12×36, porque é o valor mais próximo da lista oficial — e essa declaração \*\*transmite sem erro\*\*, aparecendo só numa fiscalização.
\>
\> \*\*O revezamento já está disponível\*\* (passos 34-A a 34-C): vínculo ligado a uma turma faz este quadro declarar \`tpJornada\` de \*\*revezamento\*\*, com a descrição montada a partir do ritmo do ciclo, do nome da turma e da hora em que o turno começa. Até 07/08/2026 o sistema recusava a turma com mensagem — recusava, nunca gravava como se fosse outra coisa —, e este bloco dizia isso. Agora ele grava.
:::

## Garantias de emprego e termo de estágio

***

**Mudar a data que o sistema propôs pede motivo escrito.** Não é burocracia: é o que responde à pergunta anos depois, quando ninguém lembra por que aquele prazo ficou diferente do legal.

**Só a acidentária ganha data de fim proposta, e as outras três ficam em branco de propósito.** Elas contam de um fato que este cadastro **não guarda** — o parto, o fim do mandato. Somar os meses à data de início nas quatro produziria uma data que **parece calculada**, expira **antes** da proteção acabar e **cala o alerta enquanto a pessoa ainda está protegida**. Por isso a tela mostra *"indeterminada"* e espera você digitar a data quando o fato acontecer.

**Role até o cartão "Garantias de emprego" e clique em "Registrar garantia".** Garantia de emprego é **proibição de demitir dentro de um intervalo**, e o sistema conhece quatro espécies, cada uma com o seu fundamento legal\:EspécieFundamentoPrazoConta a partir deAcidentáriaLei 8.213/1991, art. 11812 mesesdo próprio início (cessação do benefício)GestanteADCT art. 10, II, "b"5 meses**do parto**CipeiroADCT art. 10, II, "a"1 ano**do fim do mandato**Dirigente sindicalCLT art. 543 §3º1 ano**do fim do mandato**



**Este cartão tem permissão própria, mais estreita que a do contrato.** Que uma pessoa nomeada está grávida, ou voltou de acidente de trabalho, é dado de **saúde e sindical**. A permissão de ler contrato é detida por quase todo cargo de RH; se a garantia respondesse a ela, esse dado apareceria para todo mundo que abre um contrato.

**É a metade que age.** Uma garantia que ninguém informa é linha em tabela. Demitir sem justa causa dentro do intervalo é **nulo**, e a reintegração é decidida na Justiça — o aviso existe para você ver isso **antes** do ato, não como recusa depois de preencher a rescisão inteira.

**Confira o aviso vermelho no alto do cartão.** Quando o vínculo está sob garantia **hoje**, o cartão avisa e **nomeia cada espécie** antes de qualquer outra coisa.

35-A. **Quando o fato acontecer, clique em "Registrar o fim" na linha da garantia.** O botão aparece só nas linhas marcadas como *"aguardando a data do fato"* — as três espécies que não têm data proposta. Informe a **data em que a proteção termina** e, ao lado, **qual fato a decidiu**: o parto, na gestação; o fim do mandato, na CIPA e no cargo sindical.

:::BlockQuote
\> \*\*Sem este ato a garantia nunca fecha.\*\* O cadastro fica em \*"indeterminada"\* para sempre e o aviso vermelho continua disparando sobre proteção \*\*já vencida\*\* — o espelho exato do defeito que o sistema evita ao não inventar data. Um cala o alerta cedo demais; o outro nunca o cala. É essa data, e o motivo ao lado dela, que uma fiscalização lê anos depois.
\>
\> \*\*A data é a do fim da PROTEÇÃO, não a do fato.\*\* Cipeiro cujo mandato terminou em 15/03/2028 fica protegido até \*\*15/03/2029\*\* — um ano \*a contar\* do fim do mandato. Gestante que deu à luz em 10/06 fica protegida até cinco meses depois. Quem digita a data do fato encurta a garantia, e a pessoa perde meses de estabilidade sem que nada acuse.
:::

### A armadilha: a garantia AVISA, ela não impede — e o sistema pede que você diga que sabe

Vínculo sob garantia **não fica congelado**. Reajustar o salário, mudar de setor, conceder férias, trocar a jornada, levar a pessoa numa incorporação — tudo isso continua permitido, e boa parte **é direito da pessoa**, não favor. A garantia veda a **dispensa**, não a vida funcional.

O que o sistema faz é **não deixar o ato passar em silêncio**. Nas cinco telas que produzem movimentação — **salário**, **lotação**, **férias**, **sucessão de contrato** e **jornada** — aparece, quando o vínculo está protegido **naquela data**, um aviso vermelho nomeando as espécies em curso, e logo abaixo o campo **"Reconhecimento da garantia"**. Escreva ali por que o ato segue mesmo assim: o texto viaja com a movimentação na trilha de vida funcional.

:::BlockQuote
**O aviso é julgado pela data do ATO, não por hoje.** Um reajuste digitado em agosto com efeito em junho é medido pelas garantias que vigiam **em junho**. Perguntar por hoje limparia um alerta que estava correndo quando a mudança de fato aconteceu.**Se o campo aparecer sem o aviso vermelho, é porque o seu perfil não pode ler as garantias deste vínculo** — essa permissão é mais estreita que a do contrato, de propósito. Nesse caso o campo é opcional: preencha se o ato for recusado por esse motivo.
:::

## Documentos com validade e o aviso de vencimento

***

35-A. **Abra "Tipos de documento"** (/admin/employee-document-kinds). No menu lateral, em **Administração → Tipos de documento**. Aqui você diz **quais papéis a organização controla** — atestado de saúde ocupacional, treinamento de norma regulamentadora, certificação profissional, habilitação — e, para cada um, **com quantos dias de antecedência quer ser avisada** do vencimento. O sistema já vem com cinco tipos de partida; todos são editáveis.

:::BlockQuote
\> \*\*A antecedência é do TIPO, não uma só para a empresa inteira — e isso é a coisa que decide se o aviso serve.\*\* Marcar exame ocupacional leva semanas; renovar habilitação leva um dia. Um número único obrigaria a escolher entre ruído e aviso que chega tarde. Mudar o número aqui muda \*\*quem a varredura de amanhã avisa\*\*, sem nenhuma versão nova do sistema.
\>
\> \*\*A armadilha: "validade usual" não é prazo legal.\*\* Ela só preenche automaticamente uma data que o analista não digitou. Os tipos semeados a deixam \*\*em branco de propósito\*\*, porque a periodicidade do exame ocupacional vem do PCMSO e depende da função — e o sistema não tem o PCMSO. Número inventado é pior que campo em branco, porque parece informação.
\>
\> \*\*Antecedência zero é recusada, nomeando o motivo.\*\* Avisar no próprio dia do vencimento é o aviso sobre o qual ninguém consegue agir.
\>
\> \*\*Tipo se desativa, nunca se apaga.\*\* Documentos já registrados nele continuam apontando para ele e continuam sendo varridos.
:::

35-B. **Abra a ficha da pessoa** (**Recursos humanos → Empregados**, depois o lápis da linha) **e role até "Documentos e vencimentos".** Clique em **"Novo documento"**, escolha o tipo, informe o número, a data de emissão e responda **"Este documento vence?"**.

:::BlockQuote
\> \*\*A armadilha: deixar a validade em branco NÃO quer dizer "não vence".\*\* São dois fatos opostos — a carteira de trabalho realmente não vence; o atestado ocupacional está sem data porque ninguém tinha o papel na mão. Por isso a pergunta tem \*\*três respostas\*\*: \*"Sim, nesta data"\*, \*"Não, é permanente"\* e \*"Ainda não conferido"\*. Quem não responde cai em \*\*"ainda não conferido"\*\*, e o documento aparece marcado como \*\*sem validade informada\*\* — em amarelo, não em cinza. É de propósito: se o padrão fosse "permanente", a tela ficaria mais verde quanto mais apressado fosse o preenchimento.
\>
\> \*\*Documento sem validade informada NÃO entra na varredura.\*\* Não há data para comparar. Ele é contado e mostrado como lacuna — nunca escondido junto dos que estão em dia.
\>
\> \*\*Declarar "permanente" e informar uma data ao mesmo tempo é recusado.\*\* São duas afirmações contrárias sobre o mesmo papel, e gravar as duas deixaria cada tela lendo uma coluna diferente.
\>
\> \*\*Validade anterior à emissão é recusada\*\*, e o tipo que exige comprovante digitalizado recusa o salvamento sem o anexo.
\>
\> \*\*O campo "Digitalização do documento" é onde o comprovante entra.\*\* Escolha o arquivo antes de salvar: ele é enviado junto e fica sob a \*\*mesma autorização do documento\*\* — quem não pode abrir a ficha não alcança a imagem, nem pela tela genérica de anexos. Ao reabrir o documento, o nome do arquivo aparece com o botão \*\*Baixar\*\*; a lista de documentos mostra um clipe na linha de quem tem digitalização.
\>
\> \*\*Editar um documento não apaga mais a digitalização.\*\* Até 2026-08-12 o anexo era desfeito em toda edição — o arquivo continuava guardado, mas a linha deixava de apontar para ele, e um tipo que exige comprovante passava a recusar a próxima gravação de um documento que sempre teve o papel.
\>
\> \*\*O cartão "Histórico deste documento" abre com o documento em edição.\*\* Ele mostra quem registrou, quem alterou o quê e quem apagou — com o antes e o depois campo a campo. Documento apagado sobrevive ali: a pergunta que a fiscalização faz sobre um certificado que sumiu é exatamente \*\*quem o removeu\*\*.
:::

35-C. **Confira o bloco "Exigido pelo cargo e sem documento na ficha", logo abaixo da lista.** Ele cruza o que o **cargo** exige (cadastrado em *Cargos*) com o que a pessoa **tem**.

:::BlockQuote
\> \*\*A armadilha: lacuna não é vencimento, e o sistema não mistura os dois.\*\* Certificado vencido se \*\*renova\*\*; certificado que nunca existiu se \*\*providencia\*\*, por outra pessoa, em outro prazo. Um distintivo só para os dois casos produziria um número sobre o qual ninguém consegue agir.
\>
\> \*\*O casamento é pelo NOME da exigência.\*\* No campo \*"Atende qual exigência do cargo"\*, escreva exatamente como o cargo a registra. Renomear a exigência no cadastro de cargos \*\*reabre a lacuna\*\* até os documentos serem reapontados — o sistema prefere mostrar a lacuna a continuar afirmando que a exigência está atendida.
:::

35-D. **Abra "Vencimento de documentos"** (/employee-documents). No menu lateral, em **Recursos humanos → Vencimento de documentos**. É a mesma informação vista pela organização inteira, do mais crítico para o menos, com filtro por situação e por categoria. Todo dia, de manhã, o sistema varre esses documentos e avisa quem cuida da papelada — **uma vez por documento**. Renovado, o documento volta a ser avisado quando a validade nova se aproximar.

:::BlockQuote
\> \*\*A armadilha: tela limpa não é organização em dia.\*\* Olhe o painel \*\*"sem validade informada"\*\* no topo. Zero a vencer sobre um cadastro em que ninguém digitou data nenhuma é idêntico, na tela, a zero a vencer sobre um cadastro completo — e é esse painel que separa os dois. Enquanto o cadastro estiver vazio, a tela mostra o aviso de que \*\*não há o que acompanhar\*\*, em vez de fingir que está tudo certo.
\>
\> \*\*O aviso avisa; ele não bloqueia nada.\*\* Documento vencido não trava a folha, não bloqueia o cadastro da pessoa e não recusa alocação. Manter alguém trabalhando com papel vencido é decisão de gente — um sistema que a tomasse calado seria descoberto no dia em que travasse uma folha, e a reação seria desligar o aviso.
\>
\> \*\*Documento já vencido continua sendo avisado\*\*, e não some da varredura por ser "tarde demais": exame que venceu em março é o que a fiscalização acha em setembro, e a multa é por pessoa.
\>
\> \*\*Ao pé da tela fica "Exigido pelo cargo e nunca registrado", da organização inteira.\*\* É o mesmo cruzamento do bloco 35-C, mas de todo mundo \*\*em atividade hoje\*\*, com as exigências \*\*obrigatórias em cima\*\*. Estas linhas \*\*não podem\*\* aparecer na tabela acima por construção: documento que nunca foi registrado não tem data para vencer, então nenhuma ordenação da relação de vencimentos jamais o mostraria. Quem saiu da empresa não entra — certificado que um ex-empregado nunca tirou não é lacuna que alguém feche.
\>
\> \*\*Lista de lacunas vazia não é prova de conformidade.\*\* Cargo que não registra exigência nenhuma também produz lista vazia. O que ela diz é que \*\*nada exigido está descoberto\*\*, não que a organização exigiu o que devia.
:::

## Alocação a contrato, projeto ou atividade

***

36-A. **Role até o cartão "Alocação de trabalho" e clique em "Declarar alocação".** Ele responde a **quanto do tempo** da pessoa está comprometido com cada contrato, projeto ou atividade, e **desde quando**. Escolha o **tipo de alvo**, o alvo, a **proporção** e a **data de início**.

:::BlockQuote
\> \*\*O teto de 100% é somado no SERVIDOR, e a tela não recalcula.\*\* O número que aparece em \*"tempo comprometido"\* é o que o servidor devolveu, com o mesmo critério da regra que recusa o estouro. Uma segunda conta no navegador divergiria da guarda no dia em que a regra mudasse — e a tela pareceria autoritativa nos dois casos.

\> \*\*A recusa por estouro NOMEIA a data em que a soma passa de 100.\*\* Ela aparece num aviso próprio, e não como erro do campo, porque o conserto quase sempre é encerrar ou reduzir \*\*outra\*\* linha, não corrigir a que você acabou de digitar.
:::

36-B. **Para consultar outro dia, use a caixa "Tempo comprometido em".** A data vai para o servidor e volta ecoada — nada no navegador decide o que é "hoje".

36-C. **Corrigir e Encerrar são atos diferentes, e a tela os separa.** *Corrigir* ajusta a proporção **sem mover a janela de vigência** — é para o número que foi digitado errado. *Encerrar* fecha a vigência a partir de uma data, e só aparece em linha ainda em vigor.

:::BlockQuote
\> \*\*Corrigir uma linha exclui a própria linha do teto\*\* ao recalcular: baixar de 40% para 35% com 60% já em vigor é aceito; subir para 45% é recusado. Se as duas contassem, corrigir para baixo seria impossível.
:::

36\. **Para estagiário e bolsista, role até "Termo de compromisso de estágio".** São obrigatórios o **curso**, a **etapa de ensino**, o **supervisor**, o **orientador acadêmico**, a **apólice do seguro** e a **vigência**.

:::BlockQuote
\> \*\*O termo é o que torna o estágio legal, e a sua ausência não é campo em branco — é vínculo de emprego.\*\* Sem termo nomeando instituição, seguro e supervisor, o art. 3º §2º da Lei 11.788/2008 converte o arranjo em relação de emprego \*\*retroativamente\*\*, com todos os encargos. Por isso o sistema \*\*recusa\*\* em vez de avisar.
\>
\> \*\*O supervisor tem de ser empregado DESTA organização\*\* (art. 9º, III). Alguém empregado por outra empresa do grupo é recusado — e essa é justamente a montagem que o artigo proíbe, então a conferência é feita contra os \*\*vínculos\*\*, não contra a lista de pessoas.
\>
\> \*\*No regime alternado não há teto diário, e isso é a lei.\*\* O art. 10 §1º fixa só o \*\*semanal\*\*. Se a tela não conferir o limite diário nesse regime, não está quebrada: está obedecendo ao dispositivo.
:::

### O salário deste contrato não é a faixa do cargo

:::BlockQuote
**São dois cadastros, e eles respondem a perguntas diferentes.** A **faixa salarial** (**Recursos humanos → Faixas salariais**, descrita em [Administração](docId\:Z8SS7r6Bvhs09rP1SPxUD)) é do **cargo** e diz *quanto este posto pode pagar* — mínimo, ponto médio e máximo por nível. A **remuneração do contrato** é desta página, é da **pessoa**, e diz *quanto ela recebe*. A primeira é política de RH; a segunda é fato do contrato, e é a segunda que o cálculo lê.**Quem confunde os dois calcula sobre o número errado**, e o erro é do tipo que não grita: o meio de uma faixa é um valor plausível, sai no contracheque com cara de certo, e a diferença só aparece quando alguém confere à mão, meses depois.**A faixa não trava o contrato.** Um valor fora da faixa do cargo é **aceito** — promoção combinada antes de a faixa ser revista, acordo individual, salário herdado de uma sucessão. A faixa é referência para quem **decide**, não impedimento para quem **registra** o que já foi decidido.**E remuneração não registrada não vale zero.** Quando ninguém registrou a remuneração de uma pessoa numa data, quem depende dela recebe **"não sei"** e declara que não pôde calcular. É deliberado: um cálculo que tratasse a ausência como zero passaria em silêncio, sairia com número plausível e viraria passivo.
:::

### A armadilha: a data de início decide qual valor a folha usa naquele mês

:::BlockQuote
**Errar o dia em que a remuneração passa a valer não é detalhe de digitação — é o que decide o dinheiro do mês.** O sistema guarda cada remuneração com o período em que ela valeu, e toda consulta cai na linha daquele dia. Informar 1º de agosto quando o aumento vale desde 1º de junho deixa junho e julho contados com o valor antigo; informar 1º de junho quando ele só vale a partir de agosto paga dois meses a mais para todo mundo daquele lote.**Por que isso engana.** O campo aceita as duas datas, o cartão mostra o valor novo em seguida e a tela fica com cara de certa nos dois casos. Nada aponta para a data — o erro aparece no **contracheque**, depois de fechada a competência, longe de quem digitou e sem que nada na tela tenha parecido errado.**Data passada é o caso normal, não a exceção.** Acordo coletivo assinado em agosto com efeitos desde junho: informe **junho**. O sistema encerra a remuneração anterior na véspera e abre a nova valendo desde então, e a consulta a qualquer dia de junho e julho passa a devolver o valor novo. É exatamente para isso que a remuneração tem vigência — o dissídio retroativo não exige mexer em mais nada, nem em alocação, nem em lançamento antigo.**E a data errada não se desfaz abrindo outra vigência por baixo.** O sistema **recusa** data anterior ao início da remuneração que está valendo: isso reescreveria um período já encerrado, que já foi pago e já foi declarado. A recusa informa a partir de que dia a data é aceita.**Na prática:** digite a data com o documento que a justifica aberto na frente — o acordo coletivo, a carta de aumento, a ata da decisão — e confira as duas linhas depois de salvar (passo 29). O dia em que **você registra** fica gravado sozinho; o dia em que a mudança **passa a valer** é o único que só você sabe.
:::

### As espécies da trilha — e as três coisas que se chamam "transferência"

Cada lançamento tem uma **espécie**, e é por ela que se filtra. As espécies são estas:

| Como aparece na trilha     | O que é                                                                                                                                                                                                 | Onde o lançamento nasce                                                                                                                                 |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Transferência**          | A pessoa passa a trabalhar em **outra unidade da mesma empresa empregadora**. O contrato é o mesmo, a matrícula é a mesma, o tempo de casa não muda.                                                    | Na troca do estabelecimento, no próprio contrato (passo 23).                                                                                            |
| **Mudança de lotação**     | A pessoa muda de **área, de cargo ou de centro de custo**, sem mudar de empresa nem de unidade.                                                                                                         | No bloco **Lotação** da ficha do empregado, escolhendo *Mudança de lotação* em **"O que é esta mudança"** (*13 — Administração*, passo 8).              |
| **Sucessão de empregador** | A **empresa que assina o contrato** muda. Encerra um vínculo e abre outro, **com continuidade de direitos**: é o caso em que a *data para efeitos legais* (passo 6) fica diferente da data de admissão. | No cartão **Vida funcional entre empregadores** do próprio contrato (passo 32).                                                                         |
| **Promoção**               | A pessoa passa a ocupar um cargo superior.                                                                                                                                                              | No mesmo bloco **Lotação**, escolhendo *Promoção* em **"O que é esta mudança"**. A espécie é **declarada** por você, nunca deduzida do campo que mudou. |
| **Alteração salarial**     | A remuneração da pessoa muda.                                                                                                                                                                           | No cartão **Remuneração** do próprio contrato (passo 28).                                                                                               |
| **Licença**                | A pessoa se afasta do trabalho. O que distingue uma licença de um afastamento é o **motivo legal** informado no registro do afastamento, não a espécie do lançamento.                                   | Na tela **Afastamentos e retornos** (passos 34 a 38). O **retorno** inscreve um segundo lançamento, também de licença.                                  |
| **Férias**                 | O período de gozo de férias.                                                                                                                                                                            | No cartão **Férias** do próprio contrato, pelo botão **Agendar** da linha do período aquisitivo (passos 43 a 46).                                       |

:::BlockQuote
**As três primeiras se chamam "transferência" no corredor, e o sistema as separa de propósito.** No dia a dia, "transferi o João" quer dizer indistintamente que ele mudou de filial, que mudou de departamento ou que passou a ser empregado de outra empresa do grupo. São **três fatos diferentes**, com consequências diferentes, e depois de lançados não há como distingui-los se foram lançados sob o mesmo nome — quem auditar dali a dois anos vai encontrar "transferência" e não vai saber qual das três aconteceu.**A confusão que custa caro é entre transferência e sucessão.** Mudar de unidade **não** mexe no tempo de casa: o contrato continua o mesmo. Mudar de empregador **preserva** o tempo de casa por meio da data para efeitos legais, e é dela que dependem décimo terceiro, férias e reajuste. Registrar uma sucessão como se fosse transferência de estabelecimento deixa a data para efeitos legais como está e é o começo de um erro de rescisão — que só aparece no acerto final, anos depois, quando ninguém mais lembra do lançamento.**Promoção com aumento produz DOIS lançamentos, e isso não é duplicidade.** Um de promoção e um de alteração salarial, porque as duas datas de efeito nem sempre coincidem — o cargo muda num dia, o salário passa a valer noutro — e quem audita pergunta pelas duas separadamente. Ver duas linhas para o mesmo ato é o comportamento certo.**Desde 2026-08-06 o sistema inscreve as SETE espécies, e cada uma tem a sua tela.** Transferência de estabelecimento (passo 23), alteração salarial (passo 28), sucessão de empregador (passo 32), licença e retorno (passos 34 a 38), mudança de lotação e promoção (bloco **Lotação** da ficha do empregado, em *13 — Administração*) e férias (passos 43 a 46). Nenhuma espécie do filtro é mais decorativa. **Não lance uma promoção como transferência "para não perder o histórico"**: a linha ficaria para sempre com a espécie errada, e lançamento não se corrige — é o que a subseção seguinte trata.
:::

### A armadilha: o lançamento é definitivo — não se edita nem se apaga

:::BlockQuote
**Não existe caminho para alterar nem para remover um lançamento da trilha** — não há botão em cartão nenhum, nem na tela de movimentação, e a ausência não é tela por fazer. Se você errou a data de efeito, o motivo ou a própria espécie, não há o que consertar naquela linha.**Quem errou registra de novo, corrigindo o fato.** Volte à tela onde o fato é registrado — no caso da transferência, o contrato —, deixe o cadastro correto e informe a data de efeito certa com um motivo que explique a correção. Isso inscreve um lançamento **novo**. Os dois passam a conviver na trilha, e a leitura correta é a do par: o que se registrou naquele dia, e o que se corrigiu depois.**Por que é assim.** A trilha é **prova** — perante auditoria, controle interno, sindicato, fiscalização e reclamatória. Uma trilha que se reescreve não prova nada: se o lançamento de ontem pode virar outro hoje, ela deixa de responder à única pergunta que interessa a quem fiscaliza, que é *"o que estava registrado naquele dia"*. O cadastro é o estado atual e por isso pode ser corrigido; a trilha é a história e por isso não pode.**Na prática:** confira a **data de efeito** e o **motivo** antes de salvar, com a mesma atenção que se dá a um documento assinado. Um lançamento errado não some — ele fica, com o corretivo ao lado, e quem ler os dois vai ver que houve engano. Isso é bem melhor do que uma trilha editável, e é bem pior do que ter conferido antes.
:::

### O motivo é obrigatório — e é a única parte que o sistema não consegue deduzir

:::BlockQuote
**O sistema sabe três das quatro coisas sozinho.** Sabe **o quê**, comparando o cadastro antes e depois. Sabe **quando**, pela data de efeito que você informou. Sabe **quem**, porque quem registra fica registrado. O **por quê** não está em campo nenhum, não dá para inferir de dado nenhum, e é justamente o que quem audita procura primeiro.**Por isso o motivo em branco é recusado**, e a recusa não é formalidade de tela. Sem o porquê, o histórico vira uma lista de datas — e uma lista de datas é exatamente o que já existia na planilha ao lado, que este cadastro veio substituir.**Escreva pensando em quem vai ler daqui a dois anos, sem você por perto para explicar.** "Transferência" não serve como motivo: a espécie do lançamento já diz isso. Servem "reestruturação do quadro da unidade", "pedido do próprio empregado", "abertura da nova filial", "decisão da diretoria em reunião de 12/03". O motivo é o que a espécie **não** diz.
:::

### Registrar a mudança de empregador (sucessão)

1. **Abra o contrato pelo botão de lápis e role até o cartão "Vida funcional entre empregadores".** Ele mostra **desde quando os direitos desta pessoa vêm contando** — em destaque, com o tempo acumulado em anos, meses e dias ao lado — e, abaixo, **todos os vínculos que ela teve no grupo**, do mais antigo para o mais novo, cada um com o empregador, a matrícula, o período e a situação. O vínculo que você está olhando aparece marcado. Quem nunca mudou de empregador tem um vínculo só, e o cartão diz isso em palavras: um percurso de uma linha **não** é histórico faltando.
2. **Clique em "Registrar mudança de empregador"** e preencha os cinco campos\:Antes de você confirmar, o formulário mostra **a data desde quando os direitos vão continuar contando**. Ela não é um campo — não há o que digitar. Ela é lida do vínculo que está sendo sucedido, e está ali para você **conferir**.
   - **Nova empresa empregadora** — tem de ser **outra** empresa. Escolher a mesma é recusado, e a recusa explica por quê: mudar de estabelecimento dentro da mesma empresa é **transferência**, e se registra editando o próprio contrato (passo 23).
   - **Estabelecimento** — a unidade onde a pessoa passa a ser lotada na nova empresa. A lista só oferece unidades da empresa escolhida ao lado, e trocar a empresa limpa esta escolha de propósito.
   - **Matrícula no novo empregador** — normalmente é uma matrícula nova: a antiga pertencia à outra empresa, e a exclusividade é por empregador.
   - **Passa a valer em** — o primeiro dia no novo empregador. O vínculo atual é encerrado **na véspera**, de modo que os dois ficam adjacentes e nenhum dia da vida funcional fica sem dono. Data passada é aceita; ela precisa ser **posterior** à admissão do vínculo atual.
   - **Motivo** — obrigatório, e vale aqui a mesma regra do passo 24: é o que a espécie do lançamento **não** diz. Ele é inscrito na trilha dos **dois** vínculos.
3. **Salve, e confira o percurso.** O vínculo anterior passa a **Encerrado**, com a data de desligamento na **véspera** da data que você informou; o vínculo novo aparece **Ativo** a partir dela, no novo empregador; e a data em destaque no topo do cartão **não muda** — é essa a diferença entre uma sucessão e uma demissão seguida de nova admissão. No cartão **Movimentação de pessoal** dos **dois** contratos aparece um lançamento de **Sucessão**, com a mesma data de efeito e o mesmo motivo.

### A armadilha: sucessão não é demissão — e o prejuízo aparece meses depois

:::BlockQuote
**Quem tem vinte anos de casa e é transferido em janeiro passa, num cadastro reiniciado, a ter zero ano de casa em janeiro.** Se essa pessoa for desligada em março, o **aviso prévio proporcional** cai de noventa dias para trinta — dois meses de salário que a empresa deixou de provisionar e vai pagar depois, com correção, quando alguém reclamar.**O mesmo relógio manda em mais três coisas:** o adicional por tempo de serviço previsto no acordo coletivo, o **período aquisitivo de férias** que estava a dois meses de vencer, e o saldo do fundo de garantia, que não deve ser sacado numa transferência.**Por que engana.** Nada disso aparece no dia do cadastro. A tela grava, a pessoa continua entrando pela mesma portaria, e o número só fica errado **na primeira rescisão ou na primeira auditoria** — meses depois, longe de quem cadastrou.**Na prática:** nunca registre uma mudança de empregador cadastrando um contrato novo pela relação. Use este cartão. Ele é o único caminho que **encerra o anterior e abre o novo no mesmo ato**, ligando os dois — e é o que faz a data de origem viajar. Se algo falhar no meio, **nada** acontece: o vínculo anterior continua ativo, nenhum vínculo novo passa a existir e nenhum lançamento entra na trilha.
:::

### A armadilha: o vínculo novo nasce SEM remuneração — e isso é decisão, não esquecimento

:::BlockQuote
**A remuneração não é copiada.** O contrato novo aparece com o cartão **Remuneração** vazio, dizendo em palavras que não há valor registrado.**Por que é assim.** Numa reestruturação a remuneração costuma ser **renegociada**; copiar em silêncio congelaria um valor que ninguém confirmou, e ninguém perceberia — o cartão mostraria um número plausível. Além disso, quem mantém a vigência e o histórico da remuneração é o cartão **Remuneração** (passos 27 a 30), e um segundo lugar gravando a mesma coisa é como as duas versões passam a divergir.**Na prática:** registre a remuneração do vínculo novo logo depois da sucessão, pelo passo 28. **Enquanto ela não existir, tudo o que precisar de base salarial para essa pessoa informa que não conseguiu calcular** — e isso é melhor do que assumir zero, que passaria calado por todas as conferências e só apareceria no valor pago.
:::

### A armadilha: um vínculo é sucedido uma única vez

:::BlockQuote
**Depois de registrada a sucessão, o botão do cartão fica desabilitado**, com a explicação ao lado. O percurso acima mostra em qual vínculo a vida funcional continuou.**Por que.** Um percurso que se **bifurca** contaria o mesmo tempo de casa nos dois ramos — e como a data de origem é a mesma nos dois, os dois responderiam "vinte anos" pelos mesmos vinte anos. O servidor recusa, e o banco recusa junto: mesmo que duas pessoas confirmem no mesmo instante, só uma passa.**Na prática:** para continuar o percurso, abra o vínculo **mais recente** e registre a sucessão a partir dele. Numa cadeia de três empresas, o tempo de casa continua contado desde a **primeira** — é o erro mais silencioso que este cadastro pode cometer, porque o número da segunda sucessão sai plausível.
:::

### Antes de qualquer afastamento: declarar os motivos

:::BlockQuote
**Esta é a tela que precisa existir primeiro.** O formulário de afastamento não tem campo livre de motivo: ele oferece **exatamente** o que estiver declarado aqui e vigente na data de início. Num sistema recém-instalado esse cadastro nasce **vazio**, e o efeito é traiçoeiro — a lista de motivos aparece sem nenhuma opção, o que se lê como *"ninguém cadastrou os motivos ainda"* e não como *"falta cadastrar"*. Nenhum afastamento pode ser registrado até aqui ter pelo menos uma linha.
:::

33-A. **Abra "Motivos de afastamento"** (/payroll-leave-reasons). No menu lateral, em **Folha de pagamento → Motivos de afastamento**. A autoridade é a mesma das tabelas legais (INSS, IRRF) — **"Administrar tabelas legais da folha"** —, e é de propósito: quem mantém os parâmetros que a folha obedece é quem mantém estes. Ter autoridade sobre contratos **não** abre esta tela; quem registra o afastamento de uma pessoa não reescreve as regras que precificam o de todo mundo.

33-B. **Clique em "Declarar um motivo"** e preencha:

:::BlockQuote
\- \*\*Código do eSocial\*\* — dois dígitos, da \*\*Tabela 18\*\*. É o que identifica o motivo perante o
&#x20; governo; ele \*\*não\*\* decide nenhum efeito por si.
\- \*\*Descrição\*\* — o nome que o analista vai ver na hora de registrar o afastamento.
\- \*\*Dias pagos pelo empregador\*\* — a janela por conta da empresa. Nos casos de incapacidade a
&#x20; Lei 8.213/1991, art. 60 §3, põe os \*\*15 primeiros dias\*\* na empresa; a maternidade \*\*não tem\*\*
&#x20; essa janela, e o número ali é zero.
\- \*\*Quem paga depois\*\* — Previdência, o próprio empregador, empregador com reembolso, ou ninguém
&#x20; (afastamento sem remuneração). \*\*"Previdência social" quer dizer o regime, não o INSS\*\*: vale
&#x20; igual para o \*\*regime próprio\*\* de um ente público (é o caso dos códigos 05 e 10 da Tabela 18).
&#x20; O que a opção descreve é \*\*de qual bolso sai o dinheiro\*\*, e não qual instituição paga.
\- \*\*Período aquisitivo de férias\*\* — o que a ausência faz com a contagem (CLT art. 133). O campo
&#x20; \*\*Dias até perder o período\*\* só aparece — e só é lido — quando o efeito é \*"reinicia a partir
&#x20; de um limite"\*.
\- \*\*Fundamento legal da perda\*\* — qual \*\*inciso\*\* do art. 133 a perda invoca. Só aparece nos dois
&#x20; efeitos que extinguem o período. \*\*Deixá-lo em "Nenhum" tem consequência:\*\* o sistema apura que
&#x20; o limite foi ultrapassado e \*\*não extingue\*\* o período — de propósito, porque não escolhe
&#x20; fundamento legal sozinho para gravar num registro permanente. Ou seja, um motivo com limite e
&#x20; sem fundamento é uma regra que \*\*nunca dispara\*\*.
\- \*\*Obriga exame de retorno ao trabalho\*\* — marque quando o motivo for \*\*doença ou acidente\*\*.
&#x20; Ao marcar, aparece \*\*Antecedência do aviso do exame de retorno\*\*, em dias. Os dois andam
&#x20; juntos: o sistema \*\*recusa\*\* antecedência informada num motivo que não obriga o exame (seria um
&#x20; número que ninguém consulta) e \*\*recusa\*\* um motivo que obriga o exame sem dizer a antecedência.
\- \*\*Garantia na volta\*\* — se o retorno gera estabilidade (acidentária, Lei 8.213/1991 art. 118;
&#x20; ou gestante).
\- \*\*Janela de continuidade\*\* — em quantos dias uma nova ausência do mesmo motivo ainda conta como
&#x20; \*\*continuação\*\* da anterior.
\- \*\*Vigente a partir de\*\* — o dia em que esta versão passa a valer.
:::

33-C. **Salve.** O motivo passa a ser oferecido no formulário de afastamento a partir da data de vigência.

:::BlockQuote
**Efeito não se edita: declara-se o motivo de novo.** Mudou a regra? Declare o **mesmo código** com a nova vigência. O sistema encerra a versão anterior **no dia anterior**, sozinho. É isso que faz um afastamento aberto no ano passado continuar respondendo pelas regras daquele ano — se a linha fosse sobrescrita, a ausência antiga passaria a ser explicada por uma regra que não valia quando ela aconteceu.**Motivo não é apagado.** Quando deixa de ser usado, use **"Parar de oferecer"** e informe o último dia em que ele ainda pode ser escolhido. Apagar deixaria órfãos os afastamentos já registrados por ele, e a conta que os precificou ficaria sem explicação.
:::

:::BlockQuote
**O exame de retorno é marcado ANTES da volta, e o aviso existe por causa disso.** A NR-7 (item 7.5.9) obriga o exame de retorno quando o afastamento por **doença ou acidente** durou **30 dias ou mais**, e ele tem de ser feito **antes** de a pessoa reassumir. Por isso o aviso sai na véspera do **retorno previsto** — não no dia da volta, quando já seria tarde —, e sai **uma vez por afastamento**, não toda manhã.**A redação de 2022 tirou o parto do gatilho, e é isso que o campo marca.** Licença-maternidade tem 120 dias e passaria em qualquer regra que olhasse só a **duração** — o sistema avisaria sobre um exame que a norma não pede, nomeando uma pessoa e um evento de saúde que não houve. Por isso a exigência é **declarada no motivo** e nunca deduzida do tamanho do afastamento.**Afastamento sem retorno previsto não é avisado — e é contado.** Sem data prevista não há véspera sobre a qual avisar. O sistema informa quantos afastamentos estão nessa situação junto do aviso, porque "ninguém a avisar" e "cadastro pela metade" produzem o mesmo silêncio.
:::

:::BlockQuote
**O limite conta os dias do INSS, não os dias de ausência.** O campo **Dias até perder o período** mede o que o art. 133, IV mede: dias em que a pessoa *"tiver percebido **da Previdência Social** prestações"*. Os primeiros 15 dias de uma incapacidade são pagos **pela empresa** — são dias de ausência, mas não são benefício recebido, e por isso **não entram** nessa conta.Na prática, com 15/180: um afastamento contínuo de **190 dias** tem 175 de benefício e o período aquisitivo **sobrevive**; a partir de **196** dias (181 de benefício) ele se extingue. Cada nova cadeia de afastamento traz a **sua própria** janela de 15 dias, então dois afastamentos separados tiram 30 dias da conta, não 15.Isso vale **só** para este limite. O efeito *"suspende sempre"* (art. 132) conta a ausência **inteira**, com janela do empregador e tudo — são artigos diferentes fazendo perguntas diferentes.
:::

:::BlockQuote
**Duas recusas que valem entender antes de esbarrar nelas.** Informar dias pagos pelo empregador **e** indicar o próprio empregador como quem paga depois é recusado: a janela não separaria nada, e os "15 dias" pareceriam uma regra sem mudar coisa alguma. E informar o limite de dias sob um efeito que não o lê também é recusado — em vez de ignorado —, porque um número que ninguém consulta é pior que um campo vazio: quem digitou acredita que ele está fazendo algo.
:::

### Registrar um afastamento

1. **Abra "Afastamentos e retornos" e escolha o vínculo.** No menu lateral, em **Recursos humanos → Afastamentos e retornos**. A tela não mostra nada antes de o vínculo ser escolhido, e a ausência é de propósito: uma linha do tempo vazia de ninguém em particular se lê como uma organização em que ninguém nunca se afastou. **Quem tem dois vínculos no grupo tem duas linhas do tempo separadas** — ausência num não é ausência no outro, e é por isso que o vínculo vem antes de qualquer outra coisa.
2. **Confira a competência e o painel *"Como este mês se reparte"*.** Ele divide os dias do mês escolhido em quatro: **trabalhados**, **pagos pela empresa**, **cobertos pelo benefício** e **sem pagamento**. Os quatro somam os dias daquele mês — sempre, por construção, e a conta é feita no servidor. É essa repartição que o fechamento da folha lê; a tela não a recalcula.
3. **Clique em "Registrar afastamento"** e preencha\:Escolhido o motivo, o painel **"O que este motivo decide"** mostra, **antes de você salvar**, quantos dias correm por conta da empresa, quem paga depois, o que acontece com a contagem de férias, qual a janela de recaída e se o retorno gera estabilidade. **Nada disso é campo** — não há o que digitar, e não é o navegador que calcula. Tudo vem da linha do catálogo, e está ali para você conferir que escolheu o motivo certo.
   - **De** — o primeiro dia afastado, **inclusive**. Esta data faz duas coisas: abre a ausência e **decide qual versão do motivo se aplica**, porque o catálogo do eSocial muda ao longo do tempo. Trocar a data reconsulta o catálogo, e a lista de motivos pode mudar debaixo da sua mão — isso é o comportamento certo.
   - **Motivo oficial** — o motivo do eSocial, com o código ao lado da descrição. Só as versões **vigentes na data ao lado** são oferecidas. É deste campo que decorre todo o resto.
   - **Previsão de retorno** — **opcional, e deixe em branco quando não souber.** A perícia adia a resposta, e data exigida por formulário é data inventada: um palpite aqui vira previsão oficial em relatório.
   - **Documento** — qual documento justifica a ausência (CAT, atestado, perícia, ou nenhum), **nunca do que a pessoa está doente**. É ele que separa o caso ocupacional do comum, e com isso quem paga e se o retorno gera estabilidade.
   - **Por quê, nas suas palavras** — obrigatório, e vale a mesma regra do passo 24: é inscrito na trilha de vida funcional, e é o que a espécie do lançamento **não** diz.

### A armadilha: o diagnóstico NÃO está nesta tela — e isso não é configuração

:::BlockQuote
**A tela do afastamento não mostra CID nem número de CAT, e não há opção que a faça mostrar.** O dado clínico vive num **registro separado**, sob **autoridade própria** — a de quem cuida de proteção de dados, não a de quem administra vínculo. Quem tem uma não recebe a outra junto.**A tela não diz sequer se existe registro.** Isso é deliberado: "há um registro que você não pode ver" já é informação sobre a saúde da pessoa, e num quadro pequeno costuma bastar para identificá-la. O histórico de alterações do afastamento também não carrega o dado — se carregasse, o painel mascararia perfeitamente e o diagnóstico vazaria pela porta dos fundos.**Por que o cálculo não sofre com isso.** Quem paga, por quantos dias e com qual efeito sobre as férias vem do **motivo oficial**, não do diagnóstico. A folha tem tudo o que precisa sem nunca tocar no dado clínico — e é isso que torna a separação possível sem custo funcional.**Na prática:** se você precisa da parte médica para um processo, procure o encarregado de proteção de dados. Não peça a operação "administrar dado de saúde" para conseguir fechar a folha: ela não é necessária para isso, e concedê-la por conveniência é como a segregação se desfaz.
:::

### A armadilha: recaída não reinicia a janela da empresa — e a diferença é dinheiro

:::BlockQuote
**Uma ausência que recomeça pelo mesmo motivo dentro da janela de recaída CONTINUA a anterior**, em vez de abrir uma janela nova por conta da empresa. O sistema encontra isso sozinho, marca a linha como **recaída** e mostra, no afastamento, quantos dias daquela cadeia já foram debitados.**Por isso o número de dias por conta da empresa pode aparecer menor que o do direito**, e isso não é defeito — é o abatimento do que já se pagou antes na mesma cadeia.**O erro que ela evita é caro e passa despercebido.** Tratar a recaída como afastamento novo faz a empresa pagar os primeiros dias **duas vezes**, em dinheiro real, e o valor sai plausível: ninguém desconfia de uma folha em que o número está dentro da faixa esperada. O erro só aparece numa conferência que cruze as duas ausências — se alguém a fizer.**MAS o sistema não sabe distinguir duas doenças, e você sabe.** O motivo oficial 03 é *"acidente/doença não relacionada ao trabalho"* — **uma linha só** que cobre uma fratura de tornozelo e uma pneumonia. Se a pessoa quebrou o pé em março e em abril se afasta com pneumonia, o sistema encadeia as duas, porque o código é o mesmo, e a empresa acaba pagando **três** dias onde a lei manda pagar **quinze** — a prorrogação que a lei concede é para a **mesma** doença.**É por isso que o formulário tem o campo *"Este afastamento tem causa distinta do anterior"*.** Preencha-o só quando for esse caso, escrevendo qual é a causa nova: aí a janela do empregador **recomeça inteira**. Deixado em branco — que é o normal —, o encadeamento continua valendo exatamente como descrito acima.**Onde isso reaparece depois:** na tela do afastamento, um aviso próprio informa que a causa foi declarada distinta e **repete o motivo que você escreveu**. É o aviso oposto ao da recaída, e os dois nunca aparecem juntos — ou a ausência continua a anterior, ou ela não continua. Quem for conferir a folha meses depois lê ali por que a empresa pagou quinze e não três.**O que você escrever ali é lido por quem confere a folha**, e fica no registro com o seu nome. Não é uma caixa de marcar de propósito: "marcado, sem motivo" é o estado com que ninguém consegue fazer nada depois.**Por que o sistema não decide sozinho:** o que separa as duas doenças é o **diagnóstico**, que mora num registro separado sob autoridade própria — e que, no dia em que você abre o afastamento, normalmente **ainda não chegou**. Quem sabe é você.
:::

### A armadilha: a repartição do mês é do servidor, e 11 a 31 são 21 dias

:::BlockQuote
**Não refaça a conta à mão para "conferir".** Um afastamento que começa no dia 11 e vai até o dia 31 tem **21** dias, não 20 — a subtração das datas esquece que o primeiro dia também conta. É exatamente o erro que este registro veio substituir, e ele é tão comum que quem confere costuma concluir que o sistema está errado.**Se a repartição divergir de uma conta feita fora do sistema, é a conta de fora que precisa ser revista.** Os quatro números fecham com os dias do mês por construção; se somassem outra coisa, o painel não teria como ser exibido.
:::

### Registrar o retorno

1. **Abra o afastamento pela lupa da linha e preencha *"Registrar o retorno"*:** o dia em que a pessoa **de fato** voltou (inclusive) e o que encerrou a ausência — a perícia liberou, o atestado venceu, a pessoa voltou antes. **Data no passado é o caso normal**, porque retorno se digita depois do fato; data anterior ao início do afastamento é recusada.
2. **Salve, e confira a trilha.** No cartão **Movimentação de pessoal** do contrato passam a existir **dois** lançamentos de licença: o da saída, com a data de início, e o do retorno, com a data de volta — cada um com o motivo que você escreveu. Quando o motivo prevê, o retorno **cria a estabilidade** correspondente.

### A armadilha: o retorno se registra uma vez só

:::BlockQuote
**Registrado o retorno, o formulário some** e no lugar dele fica a explicação. Não é tela por fazer: encerrar um afastamento **escreve na trilha** e pode **criar uma estabilidade** — repetir o ato criaria a segunda, com data diferente, e as duas passariam a valer.**Na prática:** data de retorno errada se corrige com quem mantém a trilha, não fechando o afastamento de novo. Confira a data antes de salvar, com a mesma atenção do passo 24.
:::

### Nesta entrega o catálogo de motivos ainda vem vazio

:::BlockQuote
**A tela abre normalmente e a lista de motivos oficiais vem sem nenhuma opção.** O catálogo do eSocial é **dado de referência do governo**, carregado por migração, e ele ainda não foi semeado — a tela diz isso em palavras, em vez de aparecer como lista vazia de motivo nenhum.**Por que não foi preenchido "por enquanto" com alguns motivos.** Cada linha do catálogo carrega quantos dias correm por conta da empresa, quem paga depois, o efeito sobre a contagem de férias e a janela de recaída. Um catálogo preenchido de memória produziria folha **plausível e errada** — e o erro só apareceria no valor pago. Enquanto ele não existir, nenhum afastamento pode ser aberto, o que é a recusa certa.**Na prática:** esta é lacuna do catálogo semeado, e não algo a contornar escolhendo outro motivo. O restante da tela — as datas, o documento, o retorno, a trilha, a repartição do mês — já está pronto e passa a operar no dia em que o catálogo entrar.
:::

### Consultar o saldo de férias de um vínculo

1. **Abra o contrato e desça até o cartão "Férias".** Ele fica **dentro do contrato**, e não num item próprio do menu, porque um período aquisitivo pertence a um **vínculo**: quem tem dois contratos no grupo ganha dois conjuntos independentes de períodos, e uma tela solta teria de perguntar "de qual?" antes de mostrar qualquer coisa. Aberto pelo contrato, a pergunta já está respondida.
2. **Leia a tabela de cima para baixo — o primeiro período é o que importa.** Cada linha é um período aquisitivo, do mais antigo para o mais recente, com cinco colunas:
   - **Período aquisitivo** — os doze meses em que o direito foi ganho. O primeiro começa na data em que os direitos passaram a contar, não necessariamente na admissão.
   - **Dias ganhos** — quantos dias aquele período rendeu, pela escala do art. 130 da CLT. **Pode dizer "não determinado", e isso não é zero** (veja a armadilha logo abaixo).
   - **Faltas não justificadas** — o contador que reduz o direito. Nem toda ausência entra aqui: o art. 131 lista o que **não** conta como falta, e o sistema já separa as duas coisas. Hoje esta coluna diz **"não apurado"** em toda linha, e isso é a verdade: **nada no sistema alimenta esse contador ainda** — falta decidir de onde ele vem (apontamento de ponto, ou marcar no catálogo de motivos quais contam como falta). Enquanto não vier, a coluna **não** exibe 0, porque 0 ali seria a frase "esta pessoa não faltou" dita sobre alguém que pode ter faltado quarenta dias.
   - **Situação** — em aberto, com direito apurado, parcialmente gozado, encerrado ou **perdido**.
   - **Declarado como já usado** — o que aquele período já tinha consumido **antes de o sistema existir**. Zero num quadro recém-migrado quase sempre significa "ninguém declarou ainda", não "a pessoa não gozou nada".

### A armadilha: "não determinado" NÃO é zero — e a diferença é o direito da pessoa

:::BlockQuote
**Um período cujos doze meses ainda estão correndo não tem direito apurado**, e a tela diz isso **em palavras**. Exibir 0 no lugar transformaria "ainda não se sabe" em "esta pessoa não ganhou nada", que é uma afirmação diferente e muito pior — e que, na tela, pareceria perfeitamente comum.**O mesmo vale para um período fechado que não encontrou escala vigente.** O direito não é apurado no ar: ele sai de uma **escala com vigência**. Sem escala em vigor na data de fechamento, o número não existe, e inventá-lo seria pior do que não tê-lo.**Na prática:** "não determinado" numa linha antiga é sinal de que falta escala cadastrada para aquela data — não de que a pessoa perdeu o direito.
:::

### Declarar o que o período já tinha usado antes do sistema

1. **Clique em "Declarar uso anterior" na linha do período** e informe dois números separados: **dias já gozados** e **dias já convertidos em dinheiro** (o terço vendido, do art. 143). Os dois subtraem do saldo exatamente igual hoje — mas só um deles carrega valor já pago quando a folha começar a calcular, e juntá-los num campo só tornaria essa distinção irrecuperável.
2. **Os campos já vêm preenchidos com o que está declarado.** É correção, não evento: quem reabre a tela para acertar **um** dos números não deve ter de redigitar o outro de memória.

### A armadilha: declarar de novo CORRIGE, não soma

:::BlockQuote
**Enviar a declaração uma segunda vez substitui os números; não os acumula.** Você está afirmando um fato sobre o passado, e somar faria a segunda tentativa de acertar produzir um terceiro número errado.**Sem essa declaração, todo empregado já na casa aparece com as férias intactas.** A tela ofereceria trinta dias a quem os gozou em março passado, e — pior — o alerta de acúmulo varreria um cadastro em que ninguém nunca está em risco: **mudo, com selo verde**, que é pior do que não existir.
:::

### Programar as férias

1. **Clique em "Agendar" na linha do período** — o botão só aparece onde o pedido pode dar certo: com o direito apurado e num período que não esteja encerrado nem perdido. Confira, no topo do formulário, **contra qual período aquisitivo** você está agendando: as linhas diferem só pelas datas, e agendar contra a errada é um engano que a trilha guarda.
2. **Informe os trechos.** Cada trecho tem **início** e **quantidade de dias**. Um trecho é o caso normal; para parcelar, use **"Acrescentar período"**. O art. 134 §1º da CLT admite **no máximo três**, e por isso **não existe campo para um quarto** — não é limitação da tela, é o que a lei permite.
3. **Se você parcelou, informe quando o empregado concordou.** O campo aparece **somente** quando há mais de um trecho, porque um trecho único não depende de concordância — mostrá-lo sempre sugeriria que a lei exige algo que ela não exige, e quem preenchesse por precaução registraria um acordo que nunca houve.
4. **Escreva o motivo e salve.** O motivo vai para a trilha de movimentação de pessoal, que **não se edita nem se apaga** — a frase escrita ali é o único relato que restará de por que estas datas e não outras.

### A armadilha: o período mais antigo tem de sair primeiro — e atrasar custa em dobro

:::BlockQuote
**O sistema recusa agendar contra um período mais novo enquanto um mais antigo ainda tem saldo**, e a recusa **nomeia** o período que está na frente. Não é preferência de organização: é o art. 137, e o período vencido passa a ser devido **em dobro**.**O dobro conta por dia, não pelo período inteiro** (Súmula 81 do TST). Cada dia gozado depois do prazo é um dia dobrado — não é "tudo ou nada", e é por isso que atrasar duas semanas já custa dinheiro.**Na prática:** se a recusa aparecer, agende o período que ela nomeou. Ela está mostrando exatamente o que está prestes a ficar caro.
:::

### A armadilha: as regras do art. 134 §1º são do servidor, e a recusa diz qual delas barrou

:::BlockQuote
**A tela não confere nada por conta própria.** Um dos trechos com pelo menos 14 dias, nenhum abaixo de 5, o parcelamento com a concordância do empregado, os dias que ainda restam, a colisão com um afastamento já registrado — tudo isso é conferido no servidor, e a mensagem que volta **diz qual regra recusou**, não apenas que falhou.**Isso é decisão de projeto, não simplificação.** Reimplementar as regras no navegador criaria um segundo livro de regras, e no dia em que os dois discordassem a tela seria a versão em que as pessoas acreditariam. Um livro só, do lado que grava.
:::

### Registrar em que conta o vínculo recebe

1. **Abra o contrato e desça até o cartão "Onde este vínculo é pago".** Ele fica no contrato, e não na ficha da pessoa, porque **a conta é do vínculo**: quem tem dois contratos no grupo pode receber cada um numa conta diferente, e isso é escolha do empregado. Uma conta por pessoa obrigaria o fechamento a adivinhar qual usar.
2. **Clique em "Registrar conta" e escolha a forma de pagamento.** São quatro: *Crédito em conta*, *Conta-salário*, *Cheque* e *Dinheiro*. **Só as duas primeiras entram na remessa bancária** — as outras são pagas fora do arquivo, e o cartão diz isso em palavras para ninguém procurar o vínculo na remessa e concluir que ele sumiu.
3. **Sendo crédito, preencha banco, agência, conta, dígito e titular.** Os campos de banco **só aparecem** para as formas que chegam a um banco: pedir agência de quem recebe em dinheiro recusaria um cadastro legítimo, e o analista inventaria uma conta para passar da tela — conta inventada que depois entra na remessa.
4. **Informe a partir de quando a conta vale, e salve.** Trocar de banco é um fato **com data**.

### A armadilha: a conta nova ENCERRA a anterior, e a anterior continua no registro

:::BlockQuote
**Nada é sobrescrito.** Ao registrar uma conta com início em 01/07, a que estava em vigor é **encerrada em 30/06** e permanece na lista, marcada como *Encerrada*. É isso que mantém respondível a pergunta que aparece quando um crédito cai no lugar errado: **"em que conta caiu a folha de março?"****Por isso não existe "editar conta".** Corrigir é **registrar outra**. E o sistema recusa registrar uma conta com início **anterior** a outra já cadastrada, nomeando a data que está na frente — isso seria correção retroativa, que é outro ato.**Conta pela metade é pior que conta nenhuma.** Faltando qualquer parte da identificação, o sistema recusa e **diz qual campo falta**: uma conta incompleta entra na remessa e volta rejeitada pelo banco **depois** do prazo de crédito. E o titular tem de ser como o banco o registra — remessa com nome divergente é rejeitada **em lote**, não linha a linha.**Quem muda a conta fica registrado.** O cartão de histórico logo abaixo mostra quem registrou, quando, e o que mudou — inclusive o encerramento da conta anterior, que é um evento próprio.
:::

### Ajustar a antecedência do alerta de acúmulo

1. **Abra /admin/vacation-alert-config** — menu **Administração → Alerta de férias**. É uma tela de parâmetro do tenant, com dois campos, e não se abre uma vez por vínculo: o número vale para a organização inteira.
2. **Informe a antecedência em dias e salve.** O padrão é **30**. O sistema recusa qualquer valor abaixo de **1** e diz por quê — com zero o aviso chegaria no próprio dia em que a margem acaba, que é o aviso sobre o qual ninguém consegue agir.
3. **Use a chave "Enviar o alerta" para desligar.** Desligado, a varredura diária **nem lê o cadastro**. Ninguém é avisado, e os períodos continuam acumulando — desligar o aviso não para o relógio.

### A armadilha: a antecedência conta do último dia para COMEÇAR, não do prazo para conceder

:::BlockQuote
**São duas datas diferentes, e a que importa é a primeira.** O prazo para conceder é o fim dos doze meses seguintes ao período aquisitivo; o **último dia para começar** é aquele em que as férias ainda cabem inteiras dentro desse prazo — e ele **anda** conforme o saldo: cada dia já gozado empurra a data para a frente. A varredura avisa sobre a segunda.**Avisar no prazo para conceder seria avisar depois do prejuízo.** Quem não marcou até lá já não tem margem para marcar, e cada dia gozado dali em diante é pago **em dobro**, dia a dia (art. 137 com a Súmula 81 do TST). Trinta dias de antecedência sobre o último dia para começar dão um mês para agendar; trinta dias sobre o prazo para conceder chegariam com a conta já correndo.**O aviso sai uma vez por período, não todo dia.** Um alerta que chegasse toda manhã estaria sem ser lido no terceiro dia, e o quarto seria o que importava. Se ninguém no tenant estiver ativo para receber, o sistema **não** marca o período como avisado — tenta de novo no dia seguinte, em vez de registrar um aviso que nunca saiu.
:::

### Encerrar o vínculo, e o motivo que decide tudo

No cartão **Fim do vínculo**, logo abaixo das garantias de emprego, você informa **três** coisas: o **último dia**, o **motivo** e o que houve com o **aviso prévio**.

:::BlockQuote
**O motivo vem de uma lista fechada — a Tabela 19 do eSocial — e ele decide cada verba.** Não é burocracia: dispensa **sem** justa causa paga aviso, 13º proporcional, as duas férias e a multa de 40% do FGTS; **com** justa causa paga o saldo de salário e **as férias que a pessoa já tinha ganhado** — e mais nada; **acordo** (art. 484-A) paga **metade** do aviso e **metade** da multa.
:::

**Escolhido o motivo, a tabela abaixo mostra o que ele deve — antes de você registrar.** É de propósito: registrar primeiro e descobrir depois é como alguém desliga um empregado por um motivo cuja rescisão o sistema não sabe calcular.

:::BlockQuote
**⚠️ Justa causa NÃO zera as férias já vencidas.** É o erro mais comum, e o mais caro. A CLT diz que as férias adquiridas são devidas *"qualquer que seja a causa"* da saída (art. 146); a Súmula 171 do TST tira só as **proporcionais**. Quem zera as duas fica devendo férias vencidas a todo demitido por justa causa — e o holerite fecha do mesmo jeito.
:::

**Dois avisos que parecem iguais e são opostos:**

| O que aparece                             | O que significa                                                                                                                                                                                |
| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| *"Este motivo NÃO gera verba rescisória"* | Transferência entre empresas do grupo e mudança de CPF **encerram o vínculo e não devem nada** — a pessoa continua trabalhando. Não há folha de rescisão a abrir, e isso é **fato resolvido**. |
| *"Alguns itens não têm norma verificada"* | O sistema **não sabe** o que aquele motivo deve, porque a regra não foi lida em fonte oficial. O desligamento é registrado; a rescisão **não é calculada**. É **lacuna**, não resposta.        |

:::BlockQuote
**O aviso prévio tem quatro respostas, não duas.** *Cumprido* é tempo trabalhado. *Indenizado* é pago **e conta como tempo de serviço** (art. 487 § 1º), então acrescenta avos ao 13º e às férias — é a regra que mais muda o valor final. *Dispensado* é uma decisão que alguém pode ter de provar. *Não devido* é o que o próprio motivo dita.
:::

:::BlockQuote
**Um vínculo encerra uma vez.** Tentar registrar de novo é recusado — dois registros deixariam calcular duas rescisões, e a segunda pareceria tão legítima quanto a primeira.
:::

:::BlockQuote
**O que ainda não é calculado.** Este cartão registra **o que decide**; a soma das verbas é a entrega seguinte. Enquanto isso, abrir uma folha do tipo **Rescisão** cria a folha e recusa pessoa por pessoa, porque o roteiro de cálculo ainda não existe.
:::

### Emitir a ficha de registro do empregado

1. **Abra o contrato e desça até o cartão "Ficha de registro do empregado"** — ele é o último da tela, porque é a consolidação de tudo o que está acima. Reúne numa página só a identificação, os dados declaratórios, o vínculo, o registro legal, a lotação e o cargo, a jornada, a remuneração, os dependentes, as movimentações, os afastamentos, as estabilidades, as férias, a representação sindical e a alocação.
2. **Confira seção por seção o rótulo ao lado do título.** Cada seção diz uma de três coisas, e nunca fica em branco: **Com registros**, **Nenhum registro** ou **Não disponível**. "Nenhum registro" quer dizer que a pergunta foi feita e a resposta é nenhum; "Não disponível" quer dizer que a seção **não foi exibida a você**, e a frase abaixo dela nomeia a autoridade que faltou.
3. **Clique em "Emitir PDF".** O documento sai pronto para impressão, em português, com os mesmos dados da tela, paginado, e com o nome do arquivo trazendo a matrícula — três fichas baixadas durante uma fiscalização não chegam todas como download.pdf.

:::BlockQuote
**A armadilha: campo em branco não é informação neutra.** Uma seção de afastamentos vazia lê-se como "esta pessoa nunca se afastou", e um branco tem exatamente a mesma cara de um zero legítimo. Por isso a ficha nunca deixa uma seção em branco: ou ela traz as linhas, ou diz **nenhum registro**, ou diz **não disponível** e nomeia a permissão que falta. Antes de entregar o documento ao auditor, **passe os olhos nos rótulos**: um "Não disponível" quer dizer que você está entregando uma ficha incompleta, e quem a receber não tem como adivinhar isso.
:::

:::BlockQuote
**A armadilha: a ficha não é a soma das suas permissões — cada seção tem a sua.** A autoridade sobre o contrato de trabalho abre o documento; ela **não** abre o que está dentro dele. Remuneração exige as autoridades próprias de remuneração, estabilidades exigem a de estabilidades, dependentes a de dependentes, e assim por diante. Isso é de propósito: se a ficha exigisse todas, quase ninguém conseguiria emitir; se exigisse uma só, ela viraria a porta dos fundos pela qual quem não pode ver o salário na tela passaria a recebê-lo impresso. Se falta uma seção que você precisa, peça em **Administração → Perfis e permissões** exatamente a autoridade que a frase da seção nomeia.
:::

:::BlockQuote
**A armadilha: o diagnóstico não está na ficha, e isso não é configuração.** A seção de afastamentos traz o **fato** — as datas, o motivo oficial, até quando a empresa paga —, nunca o CID nem o número da CAT. O dado de saúde vive em registro apartado, sob autoridade própria (passo 38), e a ficha não tem seção para ele: nem presente, nem vazia, nem "não disponível". O documento é apresentado a um fiscal do trabalho, e o que a pessoa teve não faz parte do que se apresenta.
:::

:::BlockQuote
**A armadilha: a ficha é do vínculo, não da pessoa.** Quem tem dois contratos tem **duas** fichas, com empregadores e admissões diferentes — e a data de admissão é a primeira coisa que a fiscalização lê. Se você abriu a ficha e a admissão não é a que esperava, confira em qual dos contratos daquela pessoa você está.
:::

:::BlockQuote
**A ficha diz o que cobre.** No fim do documento há uma linha declarando que ele cobre **apenas** as seções listadas. Assunto que o produto ainda não acompanha simplesmente não aparece — em vez de aparecer como um título com nada embaixo, que passaria por "isto nunca aconteceu".
:::

:::BlockQuote
**Emitir fica registrado, e abrir a tela não é a mesma coisa que baixar o documento.** Abrir a ficha grava uma **consulta**; baixar o PDF grava uma **extração**. Quem cuida de proteção de dados consegue perguntar "quem levou a ficha de quem, e quando" sem receber de volta milhares de aberturas de tela. Os dois eventos aparecem no cartão **Histórico** do próprio contrato, ao lado das alterações.
:::

### Publicar as tabelas legais da folha

1. **Abra /payroll-legal-tables** — menu **Recursos humanos → Tabelas legais da folha**. É aqui que ficam os números publicados que todo cálculo lê: as faixas do INSS, as faixas do IRRF, o salário-família, o salário mínimo, a dedução por dependente e a alíquota do FGTS. **Consultar exige uma autoridade de folha — qualquer uma das quatro.** Em **Administração → Perfis e permissões** elas aparecem como *Consultar folha de pagamento*, *Consultar rubricas de folha*, *Manter tabelas legais da folha* e *Executar a folha*. Basta ter **uma**: os números são publicados pelo governo e todo cálculo os lê, então a leitura é larga de propósito — mas não é aberta. Quem não tem nenhuma delas **não vê o item no menu**, e, se chegar pelo endereço direto, recebe uma **recusa explícita** em vez de uma relação vazia. Publicar e corrigir é que exige especificamente a autorização *Manter tabelas legais da folha*.
2. **A relação já vem vazia, e isso é proposital.** O produto **não** semeia nenhum valor da lei. Enquanto não houver versão cadastrada para uma competência, a folha **recusa calcular** aquela competência e diz qual tabela falta.
3. **Clique em "Publicar uma versão" e escolha a tabela oficial.** A escolha muda o formulário: as três tabelas de faixa (INSS, IRRF, salário-família) abrem o editor de faixas; salário mínimo, dedução por dependente e teto remuneratório pedem **um valor**; o FGTS pede **uma alíquota**.
4. **Escolha a competência que seleciona a versão.** *Competência a que o valor se refere* para o INSS; *Mês em que o valor foi pago* para o IRRF. Leia a armadilha logo abaixo antes de mudar isto.
5. **Informe a partir de qual competência a versão vale, no formato AAAA-MM.** Publicar encerra a versão anterior **no mês de trás**, sozinha. Você nunca digita a data de fim.
6. **Informe a norma de origem — é obrigatória.** A portaria, a lei ou o ato normativo de onde os números saíram. Sem ela o sistema recusa.
7. **Sendo tabela de faixa, monte o conjunto inteiro.** O piso **entra** na faixa e o teto **não**: uma faixa termina exatamente onde a próxima começa. A primeira precisa começar em zero. Cada faixa leva alíquota **e** parcela a deduzir, ou — no salário-família — um valor por dependente.
8. **Havendo teto de contribuição, informe o teto e a contribuição devida nele.** Os dois juntos, e a última faixa tem de terminar exatamente no teto.
9. **Salve.** Se as faixas deixarem buraco ou se sobrepuserem, a recusa **nomeia o intervalo** — corrija esse intervalo e salve de novo.

### A armadilha: a época da tabela é do TRIBUTO, e não existe chave para ligá-la

:::BlockQuote
**Quando se paga hoje algo referente ao ano passado, os dois tributos usam tabelas de épocas diferentes.** A contribuição previdenciária usa a tabela **da competência de origem**; o imposto de renda usa a **do mês do pagamento**. Não é preferência: são dois dispositivos diferentes, e um valor de dezembro pago em março legitimamente sai calculado por duas tabelas de anos distintos.**Por isso não existe, em lugar nenhum do processamento, uma chave "usar tabelas antigas".** Ela existiria só para produzir o erro: ligada, aplicaria a tabela antiga **também** ao imposto de renda, e reter imposto por tabela que não é a do mês do pagamento é **retenção ilegal** — não é diferença de arredondamento. Como a época é campo da própria tabela, o estado errado **não é sequer exprimível**.**O que você escolhe no cadastro é a época daquele tributo, não a daquele cálculo.** E ela não muda de uma portaria para a outra: o sistema recusa uma versão nova cujo campo discorde das versões já publicadas da mesma tabela, dizendo desde quando a outra época está declarada.
:::

### A armadilha: o teto não é mais uma faixa — e sem ele o desconto sai várias vezes maior

:::BlockQuote
**Acima do teto, todo mundo contribui o mesmo valor.** Uma tabela de faixas que não conheça o teto continua multiplicando a alíquota mais alta pelo salário inteiro. Para quem ganha bem o erro não é sutil: com a última faixa aplicada sobre a base cheia, um salário três vezes o teto rende uma contribuição **da ordem de três vezes** a devida.**A contribuição no teto é digitada, não calculada.** É o número que a portaria publica, e é exatamente ele que o contador confere na tela contra o Diário Oficial. O sistema **recusa** uma tabela que declare o teto sem declarar a contribuição nele — derivar o número esconderia o que se veio conferir.
:::

### A armadilha: casa decimal a mais é descartada em silêncio

:::BlockQuote
**Alíquota tem quatro casas; valor tem duas.** Uma quinta casa numa alíquota, ou uma terceira num valor, seria arredondada pelo banco **sem avisar** — e o número que você digitou deixaria de ser o número pelo qual toda folha é multiplicada, sem ninguém saber para que lado. O sistema **recusa** o valor que não couber, dizendo qual campo.
:::

### A armadilha: competência sem tabela RECUSA, e não cai na mais recente

:::BlockQuote
**Não existe "usa a última que eu conheço".** Pedido um cálculo para uma competência sem versão cadastrada, o sistema recusa **nomeando a tabela e o mês**. Cair na versão mais nova produziria um número **plausível** — nada fica vermelho, o valor aparece na folha, e o erro só aparece na conferência anual, multiplicado por todo mundo e por todos os meses desde então.**Duas versões da mesma tabela nunca podem começar na mesma competência**, e uma versão nova tem de começar **depois** da que está valendo. A recusa diz desde quando a atual vale.
:::

### A armadilha: pessoa com dois vínculos no mês é RECUSADA, de propósito

:::BlockQuote
**O teto do INSS é cego à categoria e se aplica sobre a soma das origens** — mas a **ordem** em que ele é imputado entre os vínculos ainda não foi definida por ninguém, e ordens diferentes produzem valores diferentes para a mesma pessoa no mesmo mês. Enquanto a decisão não vier, o sistema **recusa** em vez de escolher uma e responder um número que parece certo.
:::

## Verificação

***

Você sabe que funcionou quando:

- O contrato recém-gravado aparece na relação com a matrícula, a pessoa, o empregador, a data de admissão e o tipo de vínculo que você escolheu, e com a situação **Ativo**.
- A mesma pessoa aparece em duas linhas da relação, com empregadores diferentes, e o cadastro dela continua único em **Recursos humanos → Empregados**.
- Tentar gravar, num mesmo empregador, uma matrícula já usada é recusado — **inclusive quando os dois contratos estão em filiais diferentes**.
- A mesma matrícula, em empregadores diferentes, é aceita.
- Ao deixar a **data para efeitos legais** em branco, o contrato gravado mostra nela a mesma data da admissão.
- O botão de lápis da linha abre o contrato, com a matrícula sob o título e o campo **Pessoa** bloqueado.
- No cartão **Histórico**, clicar no evento de criação abre o painel lateral com o retrato do contrato; depois de uma edição, clicar no evento correspondente mostra o que mudou campo a campo.
- A entidade sindical recém-cadastrada aparece na relação com o código de registro, a categoria e a abrangência que você informou, e como **ativa**.
- Cadastrar como entidade sindical um CNPJ que já é parceiro **não** cria um segundo cadastro: o endereço, o contato e o dado bancário continuam sendo os do parceiro que já existia.
- Tentar remover uma entidade já citada por um contrato a deixa **inativa** — ela some das escolhas novas e continua aparecendo nas consultas de datas anteriores.
- Os dois acordos gravados com bases diferentes exibem divisores mensais diferentes: **200 horas** no que declara 40 horas por semana e **180 horas** no que declara 6 horas por dia — e este último bate com o acordo que declara 180 horas por mês.
- Salvar um acordo sem a janela noturna, sem a duração da hora noturna ou sem o percentual do abono é recusado, e nenhum dos três volta preenchido com o valor da lei geral.
- Um acordo cadastrado com vigência a começar no ano seguinte aparece na relação e **não** altera a resposta de hoje.
- No cartão **Histórico** das duas telas novas, clicar no evento de criação abre o painel lateral com o retrato do registro.
- Trocar o estabelecimento do contrato, informando data de efeito e motivo, faz aparecer **um** lançamento de **transferência** no cartão **Movimentação de pessoal**, com a data de efeito que você informou (não a de hoje), o motivo escrito e o seu nome como quem decidiu.
- Editar o contrato **sem** trocar o estabelecimento **não** acrescenta lançamento nenhum à movimentação — a alteração aparece só no cartão **Histórico**.
- Salvar a troca de estabelecimento com o motivo em branco é recusado.
- Uma data de efeito anterior à admissão (ou posterior ao desligamento) é recusada, com o intervalo válido informado.
- Nenhum lançamento oferece editar nem remover: não há botão para isso no cartão do contrato nem na tela de movimentação.
- Na tela **Movimentação de pessoal**, filtrar por uma espécie devolve **somente** os lançamentos daquela espécie; um período em que nada aconteceu devolve nenhuma linha, e a tela diz que não há lançamentos — não uma mensagem de erro.
- Quem não tem **nenhuma** das duas autoridades de movimentação recebe recusa explícita na **tela** de movimentação, e dentro do contrato o **cartão simplesmente não aparece** — nunca uma trilha vazia, que passaria por "esta pessoa nunca se movimentou". Quem tem **qualquer uma** delas abre as duas normalmente.
- Registrar uma alteração salarial com data posterior deixa **duas** linhas no cartão **Remuneração**: a anterior encerrada na véspera da data informada, e a nova vigente a partir dela.
- Registrar uma alteração com data **passada** (o dissídio) produz o mesmo efeito, e a consulta a um dia daquele período retroativo devolve o valor **novo** — enquanto um dia anterior a ele continua devolvendo o valor antigo.
- A alteração salarial aparece no cartão **Movimentação de pessoal** como **Alteração salarial**, com a data que você informou (não a de hoje) e o motivo escrito.
- Salvar uma alteração salarial com o **motivo** em branco é recusado.
- Uma data **anterior ao início da remuneração vigente** é recusada, e a recusa informa a partir de que dia a data é aceita.
- **Corrigir a remuneração vigente** muda o valor da linha que está valendo **sem** criar segunda linha e **sem** acrescentar lançamento à movimentação — a correção aparece só no cartão **Histórico**.
- Um valor **fora da faixa salarial do cargo** é gravado normalmente.
- Quem tem apenas a autoridade de **consulta** sobre remuneração vê o cartão **sem os botões**, com o aviso de painel somente leitura; quem não tem nenhuma das duas **não vê o cartão** — nunca um cartão vazio, que passaria por "esta pessoa não tem salário registrado".
- Registrada a sucessão, o vínculo anterior fica **Encerrado** com a data de desligamento na **véspera** da data informada, e o vínculo novo aparece **Ativo** a partir dela, no novo empregador.
- A data em destaque no topo do cartão **Vida funcional entre empregadores** — *"Direitos contam desde"* — **não muda** com a sucessão, e o percurso passa a mostrar os dois vínculos em sequência.
- Numa cadeia de **três** empregadores, essa data continua sendo a admissão do **primeiro** vínculo, e não a do segundo.
- O cartão **Movimentação de pessoal** dos **dois** contratos mostra um lançamento de **Sucessão**, com a mesma data de efeito e o mesmo motivo.
- O contrato novo abre com o cartão **Remuneração** dizendo, em palavras, que não há remuneração registrada — nunca R$ 0,00.
- Informar como nova empregadora **a mesma empresa** do vínculo atual é recusado, e a recusa explica que isso é transferência.
- Tentar suceder de novo um vínculo já sucedido não é oferecido: o botão fica desabilitado, com a explicação ao lado.
- Uma data de efeito **igual ou anterior** à admissão do vínculo atual é recusada, com o intervalo válido informado.
- Uma matrícula já ocupada no **novo** empregador é recusada, e o vínculo anterior continua **Ativo** — nada foi encerrado.
- Quem tem apenas a autoridade de **consulta** sobre o vínculo vê o percurso **sem o botão**, com o aviso de painel somente leitura.
- A tela **Afastamentos e retornos** aberta **sem** vínculo escolhido não mostra lista nenhuma, e explica por quê — nunca uma relação vazia.
- Os quatro números do painel **"Como este mês se reparte"** somam exatamente os dias do mês da competência escolhida — inclusive em fevereiro e inclusive quando o afastamento atravessa a virada do mês.
- Um afastamento que começa no dia **11** e termina no dia **31** conta **21** dias por conta da empresa, não 20.
- Escolhido o motivo, o painel **"O que este motivo decide"** aparece **antes** de salvar, e os valores dele mudam ao trocar o motivo — sem que nenhum deles seja editável.
- Trocar a **data de início** reconsulta o catálogo, e um motivo que não vigia naquela data deixa de ser oferecido.
- Registrado o afastamento, o cartão **Movimentação de pessoal** do contrato ganha **um** lançamento de **licença**, com a data de início e o motivo que você escreveu.
- Registrado o retorno, aparece um **segundo** lançamento de licença, com a data da volta — e o formulário de retorno some, dando lugar à explicação.
- Uma ausência aberta pelo mesmo motivo dentro da janela de recaída aparece marcada como **recaída**, informa quantos dias daquela cadeia já foram debitados, e **não** reinicia a janela por conta da empresa.
- Nem a tela do afastamento nem o **histórico** dele mostram diagnóstico ou número de CAT — e não há configuração que os faça aparecer.
- Quem detém a autoridade sobre **dado de saúde** vê a parte médica em painel próprio, com histórico próprio; quem detém apenas a de **contrato de trabalho** recebe, no lugar, uma explicação que **não diz se existe registro**.
- Quem tem apenas a autoridade de **consulta** sobre o vínculo abre o afastamento **sem** o formulário de retorno, com o aviso de painel somente leitura.
- Com o catálogo de motivos ainda não semeado, a tela abre e diz **em palavras** que não há motivo vigente — não uma lista vazia nem uma mensagem de erro.
- No cartão **Ficha de registro do empregado**, **toda** seção listada exibe um dos três rótulos — **Com registros**, **Nenhum registro** ou **Não disponível** — e nenhuma aparece só com o título e nada embaixo.
- Um vínculo sem dependentes mostra a seção **Dependentes** com o rótulo **Nenhum registro** e a frase correspondente, e não em branco.
- Com um usuário **sem** a autoridade de estabilidades, a seção **Estabilidades** aparece marcada **Não disponível**, com a frase nomeando a autoridade que falta — e **não** vazia. Com um usuário que a tem, a mesma seção aparece com as linhas.
- O PDF emitido abre, tem mais de uma página quando o vínculo tem muitas movimentações, nenhuma linha aparece cortada à direita, e nomes com acento (ç, ã, é) saem como foram digitados.
- No cartão **Histórico** do contrato, abrir a ficha e baixar o PDF deixam **dois eventos distintos** — consulta e extração —, e filtrar por extração não devolve as aberturas de tela.

## Erros comuns

***

- **"A matrícula \<número> já pertence ao contrato de \<pessoa> nesta empresa empregadora"** — a matrícula é única **por empregador**, e não por filial (ver a armadilha acima). A mensagem aparece embaixo do campo **Matrícula** e diz de quem é o contrato que já a usa: ache-o pela busca da relação e decida qual dos dois números está errado.
- **"O estabelecimento pertence a outra empresa: escolha um da empresa empregadora"** — a unidade de lotação não é do empregador informado. A mensagem aparece embaixo do campo **Estabelecimento**. Escolher primeiro o empregador e depois o estabelecimento evita o caso, porque a lista já vem filtrada — e trocar o empregador limpa o estabelecimento justamente para isso.
- **"A categoria do eSocial deve ter até 8 dígitos"** — o campo aceita a digitação de letras, mas só dígitos são gravados como categoria. Apague o que não for número.
- **"Preencha o campo \<nome> para registrar o contrato de trabalho"** — falta um dado obrigatório. Pela tela isso é raro, porque o botão **Salvar** só libera com os seis campos obrigatórios preenchidos; a mensagem aponta o campo pelo nome técnico (registrationNumber, admissionDate, bondType, …).
- **"A pessoa não está cadastrada como empregado" / "A empresa empregadora não está cadastrada" / "O estabelecimento não está cadastrado ou está inativo"** — o registro escolhido deixou de existir ou foi desativado entre o momento em que a lista foi carregada e o momento de salvar. Recarregue a tela e escolha de novo.
- **A tela recusa o carregamento ao ser aberta** — falta **qualquer uma** das duas autoridades sobre o vínculo: **"Consultar contratos de trabalho (sem poder cadastrar nem editar)"** ou **"Administrar contratos de trabalho (vínculo, matrícula, admissão)"**. Peça a um administrador que conceda a que corresponde ao seu papel, em **Administração → Perfis e permissões** — a de consulta para quem só confere, a de administração para quem cadastra. A recusa é explícita de propósito: uma relação vazia esconderia a falta de permissão.
- **A tela abre, mas o botão "Novo contrato" não aparece** — você tem a autoridade de **consulta** e não a de **administração**. É o comportamento correto, e não uma falha: quem confere o registro não o cadastra. Peça a segunda autoridade se o seu papel também for cadastrar.
- **Recusa ao gravar a entidade sindical porque o CNPJ já é de outra entidade** — a mensagem **nomeia a entidade que já o carrega**, em vez de criar a segunda. Se a intenção era corrigir dado da entidade, edite a que já existe; se eram entidades diferentes, o CNPJ digitado está errado.
- **Recusa ao vincular o acordo a uma entidade inativa** — a entidade escolhida foi desativada. Reative-a na relação de entidades sindicais ou escolha outra: um acordo pendurado em entidade que não é mais oferecida não chega a contrato nenhum.
- **Recusa por vigência sobreposta do acordo** — já existe outro acordo **da mesma entidade** cobrindo parte do período informado, e a mensagem nomeia o acordo conflitante. Dois acordos válidos no mesmo dia deixariam ao acaso qual base rege o cálculo. Ajuste o fim do acordo anterior ou o início do novo.
- **Recusa ao salvar o acordo sem a janela noturna, sem a duração da hora noturna ou sem o percentual do abono** — os três são obrigatórios e **não têm valor assumido**. A recusa é o comportamento certo: um valor legal preenchido por omissão sairia salvo sem ninguém reparar e só apareceria errado no holerite (ver "A armadilha", acima).
- **As telas de entidades sindicais ou de acordos coletivos recusam o carregamento** — falta **qualquer uma** das duas autoridades de relações trabalhistas: **"Consultar relações trabalhistas (sindicatos e acordos coletivos)"** ou **"Administrar relações trabalhistas (sindicatos, representação e acordos coletivos)"**. Peça em **Administração → Perfis e permissões** a que corresponde ao seu papel. Quem só consulta abre a relação e **não** vê o botão de cadastro — isso é a separação funcionando, não falha.
- **Recusa ao salvar a troca de estabelecimento com o motivo em branco** — o motivo é obrigatório em toda movimentação e **não tem valor assumido**. É a única das quatro informações do lançamento que o sistema não consegue deduzir sozinho (ver "O motivo é obrigatório", acima). Escreva por que a pessoa mudou de unidade — não "transferência", que a espécie já diz.
- **Recusa por data de efeito fora da vida do contrato** — a data informada é anterior à admissão ou posterior ao desligamento, e a mensagem informa o intervalo válido. Confira se a data digitada é mesmo o dia em que a mudança **passou a valer**: quem digita a data de hoje por engano quase nunca é recusado, e o erro só aparece depois, na trilha.
-

**Os dois lugares se comportam de forma diferente, e vale saber qual é qual.** Na **tela** a recusa é explícita, de propósito: uma lista vazia passaria por "esta pessoa nunca se movimentou". No **cartão dentro do contrato** o bloco inteiro é omitido — quem não tem a autoridade não vê o cartão, e não vê tampouco uma explicação. Se um colega descreve um cartão que você não encontra na mesma tela, é isso: autoridade, não versão diferente do sistema. *(Uniformizar os dois para recusa em palavras está registrado como follow-up da E125-S13.)*

**A tela "Movimentação de pessoal" recusa o carregamento, ou o cartão de movimentação simplesmente NÃO APARECE dentro do contrato** — faltam as **duas** autoridades de movimentação, que são **próprias** e não vêm junto com a de contratos de trabalho: **"Consultar movimentação de pessoal (trilha de vida funcional)"** e **"Administrar movimentação de pessoal (registrar e corrigir a trilha)"**. **Qualquer uma das duas** basta; peça em **Administração → Perfis e permissões** a que corresponde ao seu papel — a de consulta para quem audita, a de administração para quem provoca as movimentações.

- **"Registrei a transferência e o tempo de casa não mudou"** — não é defeito. Transferência de estabelecimento **não** mexe em tempo de casa: o contrato continua o mesmo. Quem preserva tempo de casa é a **sucessão de empregador**, que é outro caminho e tem o seu próprio cartão no contrato (passo 32).
- **"A promoção/a mudança de lotação/as férias que registrei não aparecem na trilha"** — desde 2026-08-06 as **sete** espécies são inscritas, então isto passou a ser sintoma e não comportamento esperado. Confira, nesta ordem: (1) o **filtro de espécie** da tela está em *Todas*? (2) o lançamento nasce na tela certa — promoção e mudança de lotação vêm do bloco **Lotação** da ficha do empregado, não do contrato; férias vêm do botão **Agendar** do cartão **Férias** (passos 43 a 46); (3) a **data de efeito** que você informou cai dentro do período filtrado — a trilha ordena por ela, não pela data em que você digitou. Se ainda assim não aparecer, é defeito e vale chamado. Não lance a movimentação como transferência para "não perder o histórico": a espécie ficaria errada para sempre, porque lançamento não se edita nem se apaga.
- **A lista de motivos oficiais do afastamento vem vazia** — o catálogo do eSocial é dado de referência do governo carregado por migração, e nesta entrega ele ainda não foi semeado. A tela diz isso em palavras. **Não contorne escolhendo outro motivo**: é do motivo que decorrem os dias por conta da empresa, quem paga depois e o efeito sobre as férias, e um motivo escolhido "que serve" produz folha plausível e errada (ver a subseção acima).
- **"O afastamento que registrei mostra menos dias por conta da empresa do que o direito"** — a ausência foi reconhecida como **recaída** de uma anterior pelo mesmo motivo, dentro da janela, e os dias já debitados naquela cadeia foram abatidos. É o comportamento certo: a janela da empresa não reinicia a cada recaída, e tratá-la como afastamento novo faria a empresa pagar os primeiros dias duas vezes.
- **"A conta de dias não bate com a minha"** — confira a sua antes: um afastamento do dia 11 ao dia 31 tem **21** dias, e a subtração das datas devolve 20 porque esquece o primeiro dia. Os quatro números do painel do mês fecham com os dias daquele mês por construção.
- **"Não consigo ver o CID do afastamento"** — o diagnóstico e o número da CAT ficam em registro apartado, sob autoridade própria (**"Consultar dado de saúde do afastamento (CID e CAT — LGPD art. 11)"** e **"Registrar dado de saúde do afastamento (lançar o CID e a CAT)"**), que **não** acompanha a autoridade sobre contratos de trabalho. A tela não diz sequer se existe registro, e isso é proteção da pessoa, não falta de tela. Nada disso é necessário para fechar a folha: o cálculo vem do **motivo oficial**.
- **"Registrei a data de retorno errada e não acho como corrigir"** — o retorno se registra uma vez só, porque escreve na trilha e pode criar estabilidade. Procure quem mantém a trilha de vida funcional; fechar o afastamento de novo criaria uma segunda estabilidade, com data diferente.
- **A tela "Afastamentos e retornos" abre, mas o botão "Registrar afastamento" não aparece** — você tem a autoridade de **consulta** sobre contratos de trabalho e não a de **administração**. É a separação funcionando: registrar uma ausência decide quantos dias a empresa paga e a partir de quando o benefício assume — dinheiro real.
- **"Errei a data de efeito e não acho como editar o lançamento"** — não há como, e é o comportamento certo. Corrija o **fato** na tela onde ele é registrado, com a data certa e um motivo que explique a correção; isso inscreve um lançamento novo, e a trilha passa a mostrar os dois (ver "A armadilha: o lançamento é definitivo", acima).
- **Recusa ao salvar a alteração salarial com o motivo em branco** — o motivo é obrigatório em toda movimentação, e alteração salarial é uma delas. Escreva por que a remuneração mudou ("dissídio da categoria 2026", "promoção a operador sênior", "correção de enquadramento"), não "aumento", que a espécie do lançamento já diz.
- **Recusa por data anterior ao início da remuneração vigente** — a data informada abriria vigência por baixo de um período já encerrado, que já foi pago e já foi declarado. Confira se o que você quer não é **corrigir** a remuneração vigente (passo 30), que é outro botão e outro fato.
- **O cartão "Remuneração" NÃO APARECE no contrato** (ele é omitido, não mostra recusa) — faltam as **duas** autoridades de remuneração, que são **próprias** e não vêm junto com a de contratos de trabalho: **"Consultar remuneração do contrato (salário de cada empregado)"** e **"Administrar remuneração do contrato (registrar e alterar salário)"**. Qualquer uma das duas basta para ler; peça em **Administração → Perfis e permissões** a que corresponde ao seu papel.
- **O cartão "Remuneração" abre, mas não tem botão nenhum** — você tem a autoridade de consulta e não a de administração. É a separação funcionando, não falha: quem confere salário não o altera.
- **"O valor desta tela não bate com a faixa salarial do cargo"** — não é defeito, e um não deriva do outro: a faixa diz o que o cargo **pode** pagar e a remuneração diz o que a pessoa **recebe** (ver "O salário deste contrato não é a faixa do cargo", acima). Valor fora da faixa é gravado do mesmo jeito.
- **"Registrei a alteração e a competência passada continua com o valor antigo"** — é o comportamento certo, e é o motivo de a remuneração ter vigência: cada data cai na linha que valia nela. Se o valor novo tinha de valer desde antes, o que está errado é o campo **Passa a valer em** (ver "A armadilha: a data de início decide qual valor a folha usa naquele mês", acima).
- **"Emiti a ficha e uma seção veio marcada 'Não disponível'"** — não é defeito, e o documento está dizendo a verdade: aquela seção tem autoridade própria e você não a tem. A frase abaixo do rótulo nomeia exatamente qual. **Não entregue a ficha assim sem avisar quem a recebe**: ela está incompleta, e um "Não disponível" é a única pista disso. Peça a autoridade em **Administração → Perfis e permissões**, ou peça a emissão a quem já a tem.
- **"A ficha não traz o CID do afastamento"** — é o comportamento certo e não há configuração que mude. O dado de saúde vive em registro apartado sob autoridade própria, e a ficha não tem seção para ele — nem presente, nem vazia, nem "não disponível". O documento é apresentado a um fiscal do trabalho, e o diagnóstico não faz parte do que se apresenta.
- **"A ficha não tem uma seção que eu esperava"** — se a seção não aparece **em lista nenhuma** (nem como "Não disponível"), o produto ainda não acompanha aquele assunto, e a linha no fim do documento diz isso em palavras. É diferente de uma seção listada e vazia, que afirmaria que o assunto nunca aconteceu com esta pessoa.
- **"Cliquei em Emitir PDF e nada baixou"** — a mensagem de erro aparece logo abaixo do título do cartão. Se ela apareceu, é falha de rede ou recusa do servidor e vale tentar de novo; se a ficha inteira está com a mensagem de recusa no lugar das seções, falta a autoridade sobre **contratos de trabalho**, que é a que abre o documento.


[title] Índice do Manual
[path] Aplicações/ERP/Manual do Usuário/

# Manual do usuário — índice

:::BlockQuote
Com pressa? Comece pelo [Início rápido](docId\:BARLC3GlkEYd4WUMk6DOE) — caminho mínimo do cadastro à NF-e.
:::

| #  | Seção                                                         | Arquivo                                                                           | Status                             |
| -- | ------------------------------------------------------------- | --------------------------------------------------------------------------------- | ---------------------------------- |
| Q  | Quick start (30 min)                                          | [Início rápido](docId\:BARLC3GlkEYd4WUMk6DOE)                                     | Pronto                             |
| 01 | Cadastro fiscal próprio (empresa + estabelecimentos)          | [Cadastro fiscal próprio](docId\:Q-zx6Qk4pMFD09yrhmsve)                           | Pronto (texto + prints)            |
| 02 | Cadastros gerais (parceiros, produtos)                        | [Cadastros gerais (parceiros e produtos)](docId:6xpQsdWQ2NTyI40BFqDS-)            | Pronto (texto + prints)            |
| 03 | Financeiro — cadastros (bancos, plano de contas)              | [Financeiro — cadastros de apoio](docId\:yTzjjyyML1B_60VgwDT09)                   | Pronto (texto + prints)            |
| 04 | Financeiro — documentos (contas a pagar/receber)              | [Financeiro — títulos (contas a pagar e a receber)](docId\:D4kuGidayU2GQ-hMhF_T-) | Pronto (texto + prints)            |
| 05 | Tesouraria (extrato, conciliação, payment orders)             | [Tesouraria](docId:75tXS8u8o-8q4dR2arnmw)                                         | Pronto (texto + prints)            |
| 06 | Compras (requisição → recebimento)                            | [Compras](docId:3mdo_BH5DDXIp3VIh4ATK)                                            | Pronto (texto + prints)            |
| 07 | Estoque (movimentos, transferência, inventário)               | [Estoque](docId\:CVozhYtoHDtuWZyT-bnAT)                                           | Pronto (texto + prints)            |
| 08 | Vendas (pedido → faturamento)                                 | [Vendas e CRM](docId\:TaINdkXLJcUzyq0xUuGfH)                                      | Pronto (texto + prints)            |
| 09 | Fiscal — saída (NF-e, NFC-e, NFS-e)                           | [Fiscal — saída](docId\:jBJoVopyjL5-zOKm6FGbZ)                                    | Pronto (texto + prints)            |
| 10 | Fiscal — entrada (recebimento de NF-e)                        | [Fiscal — entrada](docId:1_QpvYmn6apZ9mqx87Z4K)                                   | Pronto (texto + prints)            |
| 11 | Contabilidade (lançamentos, fechamento)                       | [Contabilidade](docId:08cbTyrT0WXBp4ymvrog_)                                      | Pronto (texto + prints)            |
| 12 | Custos (rateios, apropriação)                                 | [Custos e orçamento](docId\:C_44BngrBZM27TiNbovzP)                                | Pronto (texto + prints)            |
| 13 | Administração (usuários, alçadas, LGPD)                       | [Administração](docId\:Z8SS7r6Bvhs09rP1SPxUD)                                     | Pronto (texto + prints)            |
| 14 | Frota + Notificações                                          | [Frota e Notificações](docId\:fNEUHaGVicgb22WmbN-Q8)                              | Pronto (texto + prints)            |
| 15 | Extras (Waves 2-8: CRM, NFC-e, NFS-e, motor regras)           | [Extras](docId\:T4kPSRMFPloP-vHVEA9jU)                                            | Pronto (texto + prints)            |
| 16 | Patrimônio (ativo imobilizado: bens móveis e imóveis)         | [Patrimônio](docId\:M8TPkegGwRBU8ojNqKN8w)                                        | Pronto (texto + prints)            |
| 17 | Jurídico e contencioso                                        | [Jurídico e contencioso](docId\:DYpKNts8BU6LAG-ro0VgW)                            | Pronto (texto + prints)            |
| 18 | Orçamento e controle orçamentário                             | [Orçamento e controle orçamentário](docId\:jnavpdcIz66CRN6-S45sm)                 | Pronto (texto + prints)            |
| 19 | Despesas corporativas                                         | [Despesas corporativas](docId:2MnsyCPq-CpZa2-g_AaKW)                              | Pronto (texto + prints)            |
| 20 | Integração com sistemas externos (emitir a chave)             | [Integração com sistemas externos](docId\:eOT99MPnjO9IBLjLoES8X)                  | Pronto (texto)                     |
| 21 | Gestão por indicadores (planejamento estratégico, desempenho) | [Gestão por indicadores](docId:7k-YNc9xigIkRXwPCFOBq)                             | Pronto (texto + prints)            |
| 22 | Gestão de benefícios                                          | [Gestão de benefícios](docId\:p1CcC4r5pbr9XrIl4Zb_c)                              | Pronto (texto)                     |
| 23 | Cadastro trabalhista (contrato de trabalho)                   | [Cadastro trabalhista (contrato de trabalho)](docId\:LxePSOpck0CqjzlijWZj3)       | Pronto (texto; capturas pendentes) |
| G  | Glossário (33 termos canônicos)                               | [Glossário](docId\:iE0pyHH-ovGyrIUgMb7Gs)                                         | Pronto                             |
| M  | Manutenção do manual                                          | MAINTENANCE                                                                       | Pronto                             |

**Como usar este índice:** seguir a ordem do happy path (01 → 16), seguida dos módulos complementares (17 Jurídico, 18 Orçamento, 19 Despesas, 21 Indicadores, 22 Benefícios, 23 Cadastro trabalhista) e da seção 20, que é do administrador que emite credenciais de integração.

**Status:** seções marcadas Pendente (SN) esperam entrega da Story N do epic 01 (planning/manual-usuario/epics/01-manual-v1-happy-path/).

[title] Custos e orçamento
[path] Aplicações/ERP/Manual do Usuário/

# Custos e orçamento

:::BlockQuote
Pré-requisitos: [Financeiro — cadastros de apoio](docId\:yTzjjyyML1B_60VgwDT09) (centros de custo, categorias e conta bancária) e [Contabilidade](docId:08cbTyrT0WXBp4ymvrog_) (plano de contas e lançamentos que alimentam custo e apuração).
:::

## Introdução

***

O módulo de **Custos** responde às perguntas gerenciais que o balanço não responde sozinho: *quanto custa cada produto?*, *quanto sobra de margem depois do custo da mercadoria vendida?*, *onde o gasto indireto (aluguel, energia, administrativo) realmente foi consumido?* e *o quanto já gastamos contra a verba planejada?*. Ele parte dos movimentos de estoque e dos lançamentos contábeis já registrados e monta, por cima deles, o custo médio, o custo-padrão de referência, a margem de contribuição por produto e o rateio dos custos indiretos entre os *centros de custo* que os consomem.

O módulo de **Orçamento** é o outro lado da moeda: você planeja quanto pode gastar por dimensão (centro de custo, categoria, projeto) e por período, e o sistema passa a comparar o **previsto** com o **comprometido** e o **realizado** — bloqueando ou alertando quando o gasto ameaça estourar a verba. No fim, os painéis gerenciais juntam custo, margem e execução orçamentária num só lugar para a gestão decidir. Tudo aqui é **gerencial**: o custo nunca é digitado à mão — ele é sempre derivado do que já foi movimentado.

## Passo a passo

***

### Cadastrar os centros de custo

O centro de custo é a dimensão gerencial que amarra tudo neste módulo: o rateio distribui para ele, o orçamento é planejado por ele e os painéis quebram os números por ele. O cadastro fica no menu **Financeiro**, não em Custos.

1. **Abra a lista de centros.** Menu **Financeiro → Centros de custo**. A tela mostra os centros já cadastrados, com **Código**, **Nome**, **Tipo**, **Classificação** e **Status**. No ambiente de exemplo aparecem ADM — Administration e OPS — Operations, ambos do tipo "Centro de custo" e classificação "Analítico".:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/022-cost-centers.png" alt caption width="3200" height="2000"}
2. **Novo centro.** Clique em **Novo centro** e preencha\::inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/02-cost-center-filled.png" alt caption width="3200" height="2000"}
   - **Código** — o nível próprio do código, ex.: ADM ou 1.
   - **Nome** — ex.: Administração.
   - **Tipo** — Centro de custo (acumula gasto) ou Centro de resultado (*centro de resultado*, usado pelas alçadas de crédito/orçamento/vendas).
   - **Classificação** — Analítico (recebe lançamento e rateio) ou Sintético (só agrupa filhos). **Somente centros analíticos recebem rateio.**
   - **Centro-pai** — deixe Nenhum (raiz) para o topo da hierarquia, ou aponte o pai sintético.
3. **Salve.** O centro aparece na lista com status **Ativo**. Para revisar ou desativar depois, clique no lápis da linha: abre a ficha **Editar centro de custo**, onde você ajusta os mesmos campos e pode **Inativar** o centro.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/005-cost-centers-detail.png" alt caption width="3200" height="2000"}

### Apurar o custo médio e o CMV do período

O custo dos produtos nunca é digitado — ele é **recalculado** a partir dos movimentos de estoque de um período. Essa apuração produz o custo médio e o CMV (custo da mercadoria vendida) que a margem e os painéis vão usar.

1. **Abra "Apuração de custo".** Menu **Custos → Apuração de custo**. A tela explica: "Custo médio e CMV derivados dos movimentos de estoque".
2. **Recalcule um período.** Informe **Início do período** e **Fim do período** (ex.: 01/07/2026 a 31/07/2026) e clique em **Recalcular custo**. O sistema varre as entradas e saídas de estoque do intervalo e consolida o custo médio de cada produto. O aviso na tela reforça: *o custo é sempre derivado dos movimentos de estoque — nunca editado à mão*. O período é obrigatório: recalcular **sem informar as datas** ou com **fim anterior ao início** é recusado pelo sistema.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/104-cost-snapshots.png" alt caption width="3200" height="2000"}

### Conferir custo de aquisição, custo-padrão e margem

1. **Custo de aquisição (landed cost).** Menu **Custos → Custo de aquisição**. Aqui entram os **encargos acessórios** que devem ser rateados no custo do item — frete, seguro, taxas de importação — vinculados a um documento de referência. Preencha **Descrição** e **Documento de referência** e clique em **Salvar**; o encargo passa a compor o custo de entrada do item.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/105-acquisition-costs.png" alt caption width="3200" height="2000"}
2. **Custo-padrão.** Menu **Custos → Custo-padrão**. É o custo unitário de **referência** por produto, comparado depois ao custo médio real — ele **não** substitui o custo médio como método de valoração. Pesquise o produto, informe o **Custo-padrão**, a **Vigência a partir de** e a **Vigência até**, adicione **Observações** se quiser e clique em **Salvar**. O padrão fica válido no intervalo de vigência informado. Três campos são obrigatórios: **produto**, **custo-padrão** e a **vigência a partir de** — salvar sem o produto, ou com custo **zero ou negativo**, é recusado. Observação: o cadastro depende de um **produto já registrado**; o cadastro de produtos exige um cargo com acesso ao módulo de produtos, então se a busca não encontra o item, é porque nenhum produto foi liberado para o seu usuário.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/107-standard-costs.png" alt caption width="3200" height="2000"}
3. **Margem de contribuição.** Menu **Custos → Margem de contribuição**. É a receita menos o CMV, por produto. Informe **Início do período** e **Fim do período** e clique em **Gerar relatório**. Importante: **recalcule o custo do mesmo período antes** (passo 5), senão o CMV ainda não estará disponível e o relatório sai vazio.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/106-margin.png" alt caption width="3200" height="2000"}

### Ratear custos indiretos entre atividades e centros

Custos indiretos (o salário do administrativo, o aluguel do galpão) não pertencem a um produto específico — eles precisam ser **distribuídos** para os centros que os consomem. O módulo faz isso em duas etapas: você descreve as **atividades** e os direcionadores, depois roda um **ciclo de rateio** que transfere os valores.

1. **Cadastrar atividades de custo.** Menu **Custos → Atividades de custo**. A tela ("Absorção / ABC — atividades e os direcionadores que rateiam seu custo") é onde você lista as atividades e os critérios que dirigem o rateio (por área, por número de funcionários, por faturamento). Clique em **Nova atividade**, dê um **código** único, descreva a atividade e o direcionador. O código da atividade é único: repetir um código já usado é recusado.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/108-cost-activities.png" alt caption width="3200" height="2000"}
2. **Rodar um ciclo de rateio.** Menu **Custos → Ciclos de rateio**. O ciclo é o motor que "distribui valores de emissores para receptores conforme os direcionadores". Clique em **Novo ciclo**, dê um código e nome, defina os centros emissores (origem do gasto), os receptores (centros analíticos de destino) e o critério, e execute o ciclo para o período. O sistema lê o saldo da origem, aplica o critério e transfere o custo para os destinos. Para aplicar o custeio por **absorção** ou por **ABC** sobre os ciclos já executados, use o card **Aplicar custeio** nesta mesma tela de **Ciclos de rateio**: ele distribui os custos indiretos aos objetos de custo conforme o método escolhido. **Ciclo recíproco (prestação mútua).** Quando dois centros **servem um ao outro** — a manutenção atende o administrativo e o administrativo atende a manutenção — uma passada só não resolve: o custo volta. Marque **"Recíproco"** ao criar o ciclo e, em **"Executar rodada"**, a tela pede o que o método iterativo precisa\:Ao confirmar, o sistema itera até convergir e devolve a rodada com o número de iterações que precisou. **Até 2026-08-03 marcar "recíproco" criava um ciclo que nenhuma tela conseguia executar**: o botão de executar usava o caminho comum, que recusa esse tipo de ciclo.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/109-allocation-cycles.png" alt caption width="3200" height="2000"}
   - **Centros de serviço** e o **acumulado inicial** de cada um.
   - A **prestação mútua**, uma linha **por sentido** — dois centros que se servem ocupam **duas** linhas, e é exatamente isso que a passada única não dá conta.
   - A **parcela consumida** é **decimal**: 0,30 significa 30%. As parcelas que **saem** de cada centro precisam somar **1**, e a tela mostra a soma ao lado de cada centro, com **"(fecha)"** ou **"(precisa somar 1)"**, para você corrigir antes de enviar.
3. **Apontar custo por etapa (quando houver produção/obra).** Menu **Custos → Custo por etapa**. Para empresas que acompanham material, mão de obra e overhead por **fase de produção**, escolha o **Tipo do objeto** (ex.: Produto) e o **Objeto de custo**, clique em **Carregar** e use **Novo apontamento** para registrar cada fase. O custo do objeto sobe conforme os apontamentos.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/110-phase-cost.png" alt caption width="3200" height="2000"}

### Montar e controlar o orçamento

1. **Criar um orçamento.** Menu **Custos → Orçamentos**. A tela lista os orçamentos gerenciais — "valores previstos por dimensão e período". Clique em **Novo orçamento**, dê um nome ao orçamento, escolha o período de vigência e adicione as **linhas orçamentárias**, cada uma amarrando um valor previsto a uma dimensão (centro de custo, categoria, projeto). Salve e, quando o plano estiver pronto, **aprove** o orçamento — só orçamentos aprovados entram no controle.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/111-budgets.png" alt caption width="3200" height="2000"}
2. **Acompanhar o consumo (controle orçamentário).** Menu **Custos → Controle orçamentário**. A tela compara **previsto × comprometido × realizado** — o gasto lançado contra o orçamento. No campo **Selecione um orçamento aprovado**, escolha o orçamento e o sistema mostra, por linha, quanto foi planejado, quanto já está comprometido (pedidos/contratos em andamento) e quanto de fato foi realizado, sinalizando o saldo disponível.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/112-budget-control.png" alt caption width="3200" height="2000"}
3. **Revisar o orçamento aprovado.** Menu **Custos → Revisões orçamentárias**. Quando a verba precisa de ajuste, aqui você registra uma **suplementação** (aumenta a verba), uma **transferência** (move de uma linha para outra) ou uma **antecipação**. Selecione o **Orçamento**, o **Tipo**, a **Linha de destino**, informe o **Valor** e clique em **Salvar**. A revisão fica no histórico e ajusta o previsto sem apagar o plano original.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/113-budget-revisions.png" alt caption width="3200" height="2000"}

### Simular cenários e ler os painéis gerenciais

1. **Cenários de custo.** Menu **Custos → Cenários de custo**. Compara **Realizado × Projetado × Orçado** por objeto e período. Escolha o **Tipo** e o **Objeto de custo** para consultar, ou informe o **ID do orçamento** em "Derivar do orçamento" e clique em **Derivar orçado** para gerar um cenário a partir de um orçamento existente.**Para projetar com uma premissa sua, use "Derivar projetado".** Informe antes o **Fator de projeção** — por exemplo 1,10 para trabalhar com 10% acima do orçado, ou 0,95 para 5% abaixo. O cenário projetado sai com os valores já ajustados, e a premissa aplicada fica **gravada na observação do cenário**: sem isso, uma projeção a 1,10 e outra a 1,30 ficariam indistinguíveis meses depois, e ninguém saberia qual hipótese produziu a variação que está lendo.**O fator vale só para o projetado.** Tentar aplicá-lo ao **orçado** é recusado, e de propósito: o cenário orçado *é* o plano aprovado, e ajustá-lo significaria registrar como plano um número que a aprovação nunca conteve. Deixe o campo em branco para derivar uma cópia fiel.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/114-cost-scenarios.png" alt caption width="3200" height="2000"}
2. **Painéis de gestão.** Menu **Custos → Painéis de gestão**. Reúne **execução orçamentária** e **indicadores de custo/margem** numa tela só. Selecione um orçamento aprovado para ver a execução, e informe **Início** e **Fim do período** em "Custo e margem" e clique em **Gerar** para os indicadores.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/115-costing-dashboard.png" alt caption width="3200" height="2000"}
3. **Painel Orçado × Realizado.** Menu **Custos → Orçado × Real**. Detalha, por orçamento, o **Planejado × Comprometido × Realizado**. Escolha o orçamento no seletor para carregar o painel.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/116-budget-vs-actual.png" alt caption width="3200" height="2000"}
4. **Painel Margem × Cenário.** Menu **Custos → Margem × Cenário**. Cruza a margem de contribuição com os cenários de custo. Informe o período (**De** / **Até**), o **Tipo de objeto** e o **ID do objeto**, escolha o **Cenário base** (ex.: Real) e o **Cenário comparado** (ex.: Orçado) e clique em **Calcular** para ver a margem por produto em cada cenário.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/117-margin-vs-scenario.png" alt caption width="3200" height="2000"}

### Configurar o método de custeio e as fórmulas de custo

Antes de apurar qualquer custo, defina **como** o sistema valora as saídas de estoque. Essa configuração fica no menu **Administração → Métodos de custeio** e vale para toda a empresa, admitindo exceções por produto, por grupo de produtos e por tipo de processo.

1. **Abra "Métodos de custeio".** Menu **Administração → Métodos de custeio**. A tela mostra o **padrão da empresa** — o método aplicado quando nem o produto, nem o grupo, nem o tipo de processo definem um método próprio.
2. **Escolha o método padrão.** No campo **Método de custeio**, selecione uma das opções: **Custo médio ponderado móvel**, **PEPS/FIFO**, **Custo padrão** ou **Custo específico (por lote/série)**.
3. **Informe uma fórmula auxiliar (opcional).** No campo **Fórmula auxiliar** você pode digitar uma expressão que **soma um valor** ao custo unitário calculado pelo método — útil para embutir frete, seguro ou outro encargo. Deixe em branco para não aplicar fórmula.
4. **Salve.** Clique em **Salvar**; a mensagem de confirmação indica que a configuração de custeio foi atualizada.
5. **Exceções por produto, grupo ou tipo de processo.** O padrão da empresa pode ser sobreposto: um produto pode ter método próprio, um grupo de produtos pode ter o seu, e cada tipo de processo pode ter uma fórmula distinta. O sistema resolve o método na ordem **produto → grupo → tipo de processo → padrão da empresa**, aplicando a definição mais específica encontrada.
6. **Defina a fórmula de cada tipo de processo.** Ainda na mesma tela, abaixo do padrão da empresa, o quadro **"Fórmula por tipo de processo"** lista os cinco tipos — **Produção**, **Revenda**, **Serviço**, **Consumo interno** e **Geral** — cada um com o seu campo de fórmula e o seu botão **Salvar**.
   - Uma fórmula definida aqui **vence** o padrão da empresa e **perde** para uma exceção de produto ou de grupo.
   - **Deixar a linha em branco não é omissão, é escolha:** é o que faz o padrão da empresa valer para aquele tipo de processo. Por isso os cinco tipos aparecem sempre, inclusive os que ainda não têm fórmula.
   - Apagar o conteúdo de uma linha e salvar **remove** a fórmula daquele tipo.
   - **A expressão é conferida ao salvar.** Uma fórmula malformada é recusada na hora, com a mensagem de fórmula inválida — não fica guardada para falhar semanas depois, no meio de um cálculo de custo, longe de quem a digitou. A mesma conferência vale para a fórmula do padrão da empresa, do grupo e do produto.

## Registro manual de custos

***

Nem todo custo chega pelos movimentos de estoque ou pelos lançamentos contábeis. Às vezes o analista de custos precisa **atribuir um custo à mão** — um ajuste, um gasto externo ou uma parcela de custo que pertence a um produto ou a uma atividade específica. Esta tela registra esse lançamento com justificativa, para que a atribuição fique rastreável mesmo sendo manual.

1. **Abra os lançamentos manuais.** No menu **Custos**, abra **Lançamentos manuais de custo**. A lista mostra os lançamentos já registrados, com o alvo, o valor e a data de competência.
2. **Novo lançamento.** Clique em **Novo lançamento**.
3. **Escolha o alvo.** No campo **Tipo de alvo**, selecione **Produto** ou **Atividade de custo** e, em seguida, escolha o produto ou a atividade que vai receber o custo.
4. **Informe os dados.** Preencha o **Valor**, a **Data de competência** e a **Justificativa** — a justificativa é obrigatória e é o que sustenta a trilha de auditoria do lançamento manual.
5. **Declare a natureza.** Escolha entre **Custo de estoque** e **Custo de período** — é este campo que decide se o valor entra na valoração da mercadoria\:Na dúvida, deixe **Custo de período** — é o padrão, e é o lado que não altera a valoração. Um lançamento só vale para a média quando o alvo é um **produto**: custo atribuído a uma atividade não tem estoque a re-ponderar.
   - **Custo de estoque** é o gasto que *adere à mercadoria*: frete sobre a compra, seguro do transporte, manuseio, tributo não recuperável. Ele **entra na média móvel** do produto, então o valor do estoque e o custo médio sobem.
   - **Custo de período** é o gasto que *não adere*: rateio administrativo, despesa de venda, armazenagem fora da produção, perda anormal. Fica registrado e visível, mas **não muda** a média nem o valor do estoque.
6. **Salve.** Clique em **Salvar**.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/e32-13-manual-cost-entries.png" alt caption width="3200" height="2000"}

**Você confirma que funcionou** quando o lançamento aparece na lista com o valor, a data de competência e o alvo (produto ou atividade) escolhidos, e a justificativa fica registrada junto. Se o lançamento foi de **custo de estoque**, apure o custo do período (**Apurar o custo médio e o CMV do período**, acima) e confira que o custo médio daquele produto subiu e que a coluna de custo manual absorvido mostra o valor lançado.

**Errou? Estorne — e é a única correção que existe.** O lançamento não pode ser editado nem excluído, mas pode ser **estornado**. Na coluna **Estorno** da listagem, clique em **Estornar** e informe o motivo (obrigatório). O que acontece:

- a linha **permanece** na lista, com o valor, o alvo, a competência, a justificativa e o autor originais — o estorno é a correção de um dado, não o apagamento de um registro;
- ela passa a exibir o crachá **Estornado** e quem estornou, com o motivo no *tooltip*;
- ela **deixa de contar**: na próxima apuração de custo, um lançamento de **custo de estoque** estornado devolve o custo médio e o valor do estoque ao que eram antes dele. Estornar um lançamento de **custo de período** não muda média nenhuma — ele nunca a alterou.

Estornar **duas vezes** é recusado, e o estorno vale para **qualquer competência**: a média é um número apurado, recalculável, e não alimenta lançamento contábil nenhum — o fechamento do almoxarifado valoriza o consumo pelos próprios movimentos.

## Custo-padrão por atividade

***

O custo-padrão de referência não vale só para produtos. Quando a empresa acompanha o custo das suas **atividades** (uma linha de montagem, um processo administrativo, uma etapa de serviço), é útil ter um valor-padrão por atividade para comparar depois com o custo real rateado. A tela de custo-padrão passou a aceitar os dois tipos de alvo.

1. **Abra o custo-padrão.** No menu **Custos**, abra **Custo-padrão**.
2. **Escolha o tipo de alvo.** No seletor **Tipo de alvo**, troque de **Produto** para **Atividade** — a busca passa a listar as atividades de custo cadastradas.
3. **Selecione a atividade e o valor.** Escolha a **atividade de custo**, informe o **Custo-padrão** de referência, a **Vigência a partir de** e, se quiser, a **Vigência até** e observações.
4. **Salve.** Clique em **Salvar**; o custo-padrão da atividade fica válido no intervalo de vigência informado.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/e32-20-standard-costs.png" alt caption width="3200" height="2000"}

**Você confirma que funcionou** quando o custo-padrão salvo aparece vinculado à atividade escolhida, com o valor e a vigência informados — do mesmo jeito que já acontecia para produtos.

## Padrão × real: por que a diferença

***

Saber que um produto custou mais do que o padrão não diz o que fazer. Saber que a diferença veio do **preço do insumo** manda você conversar com compras; que veio da **quantidade consumida**, com a produção. É isso que esta análise faz: ela **quebra a diferença em causas** em vez de apresentar um número único.

1. **Escolha o alvo.** Na tela **Custos → Custo-padrão**, selecione o produto ou a atividade como de costume. O card **"Padrão × real"** aparece logo abaixo, sempre sobre o **mesmo alvo** que está selecionado em cima — nunca sobre outro.
2. **Informe o período.** Início e fim; a análise é sempre de um período, e sem ele o botão fica travado.
3. **Preencha os pares.** Cada causa é um par **padrão** e **real**: preço do insumo, quantidade do insumo, taxa do recurso, uso do recurso e custo de preparação (lote). Campo em branco vale **zero** — ou seja, "nesta causa não houve diferença".
4. **Clique em "Decompor".** O sistema calcula e **grava** a decomposição; a tabela abaixo passa a mostrar, por causa, quanto era o padrão, quanto foi o real e a **diferença**, com o que ficou **acima** do padrão em destaque.
   - **O "Residual" não é sobra de arredondamento.** É a parte da diferença que as quatro causas nomeadas **não explicam** — e um residual grande é sinal de que o padrão está desatualizado ou de que há uma causa que o modelo não cobre.
   - Decompor exige a permissão de **gerir rateio**. Quem não a tem **lê** as decomposições já gravadas, mas não cria novas.
   - A decomposição fica gravada por alvo e período: ao voltar depois, a tabela mostra o que foi apurado, e não um cálculo perdido.

## Relatório de custos indiretos

***

Depois de rodar os ciclos de rateio de um período, a gestão quer enxergar **para onde** os custos indiretos foram — quanto sobrou em cada atividade e em cada centro de resultado. Este relatório consolida esse apontamento a partir dos ciclos já executados, sem precisar refazer o rateio.

1. **Abra o relatório.** No menu **Custos**, abra **Relatório de custos indiretos**.
2. **Informe o período.** Preencha o **Início** e o **Fim do período** que você quer apurar.
3. **Gere o relatório.** Clique em **Gerar relatório**. O sistema lê os ciclos de rateio executados no período e monta o apontamento do custo indireto rateado **por atividade** e **por centro de resultado**.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/e32-15-indirect-cost-report.png" alt caption width="2880" height="1800"}
4. **Veja o que cada produto absorveu.** Abaixo do relatório, o card **"Overhead absorvido por produto"** responde a outra metade da mesma pergunta. O quadro de cima diz **para onde** o custo indireto foi apontado — atividade e centro de resultado; este diz **quanto entrou no custo de cada produto**, com o **custo médio** e o **valor em estoque** resultantes e o **método de custeio** aplicado.
   - **Usa o mesmo período** que você informou acima — de propósito, para as duas metades nunca serem lidas contra datas diferentes por descuido.
   - É aqui que se confere se uma rodada de **absorção** ou de **ABC** caiu onde se pretendia. Até 2026-08-03 o sistema permitia **aplicar** as duas e não oferecia como **ler o resultado**: o número entrava no custo unitário de cada produto e só era alcançável por integração.
   - Exige a mesma permissão do relatório (**gerir rateio**). Sem ela a tela toda responde "você não tem permissão", e não um relatório vazio.

**Você confirma que funcionou** quando o relatório lista o custo indireto distribuído por atividade e por centro de resultado. Se nenhum ciclo de rateio foi executado no período, o relatório sai vazio — rode um ciclo de rateio antes (passo 10).

## Verificação

***

Você sabe que funcionou quando:

- O centro de custo criado aparece na lista de **Financeiro → Centros de custo** com o código e nome digitados e status **Ativo**; só centros analíticos ficam disponíveis para receber rateio.
- Após **Recalcular custo** de um período, a apuração deixa de mostrar "Nenhuma apuração ainda" e passa a exibir o custo médio consolidado dos produtos movimentados.
- O relatório de **Margem de contribuição** só traz números quando o custo do mesmo período já foi recalculado antes.
- Depois de executar um **ciclo de rateio**, o saldo do centro de origem reduz e sobe nos centros de destino conforme o critério — a soma rateada é igual ao valor de origem (o rateio transfere, não cria nem perde dinheiro).
- Com um orçamento **aprovado**, o **Controle orçamentário** mostra previsto, comprometido e realizado por linha, e o saldo disponível diminui à medida que novos gastos são lançados.
- Uma **revisão orçamentária** salva aparece no histórico do orçamento e altera o valor previsto da linha de destino.
- Os painéis (**Painéis de gestão**, **Orçado × Real**, **Margem × Cenário**) renderizam os números quando o orçamento é selecionado ou o período é informado.

## Erros comuns

***

- **Margem ou painel de custo sai vazio** — o custo do período ainda não foi apurado. Volte em **Custos → Apuração de custo** e recalcule o mesmo intervalo antes de gerar a margem.
- **Recálculo de custo recusado** — o período é obrigatório: informe **Início** e **Fim** e garanta que o fim não seja anterior ao início; datas ausentes ou invertidas são bloqueadas.
- **Custo-padrão não salva** — falta o **produto** ou o valor está **zero/negativo**. O produto e um custo-padrão positivo são obrigatórios; se a busca de produto vem vazia, o cadastro de produtos ainda não foi liberado para o seu cargo.
- **Atividade de custo rejeitada** — o **código** já existe. O código da atividade é único; use um código diferente.
- **Centro não aparece para receber rateio** — o centro está classificado como **Sintético**. Só centros **Analíticos** recebem lançamento e rateio; edite a classificação ou crie um centro analítico filho.
- **Controle orçamentário não lista o orçamento** — o orçamento ainda está em rascunho. Só orçamentos **aprovados** entram no seletor de controle; aprove o orçamento primeiro.
- **Rateio "por critério" não fecha** — se o direcionador escolhido (ex.: por faturamento do mês anterior) não tem base no período, o ciclo não consegue distribuir. Use um percentual fixo como alternativa ou ajuste o período.
- **Revisão rejeitada por saldo** — uma **transferência** entre linhas exige saldo suficiente na linha de origem; use **suplementação** quando o objetivo é aumentar a verba total.


[title] Notificações e Alertas Inteligentes
[path] Aplicações/

A plataforma oferece um sistema robusto de notificações e alertas automatizados, com o objetivo de manter os usuários informados sobre eventos relevantes, riscos, pendências e ações necessárias, em tempo real. Essas notificações são configuradas para atender a diferentes perfis de usuários — executores, gestores, demandantes e interessados — e são disparadas com base em regras e fluxos definidos pelo administrador.

### Funcionalidades de Envio

As notificações podem ser enviadas por diferentes canais:

- Portal da plataforma (avisos, dashboards e pop-ups);
- E-mail corporativo;
- Quadros de avisos internos;
- Outros meios conforme integração com sistemas terceiros.

### Tipos de Conteúdo

As notificações/alertas podem conter:

- Anexos ou links para download de arquivos relevantes à notificação;
- Links diretos para registros dentro da plataforma, facilitando a navegação e o acesso rápido à informação;
- Indicadores sobre tíquetes, como a possibilidade (ou não) de vinculação a outros fluxos ou registros;
- Chamadas à ação, alertando que o destinatário precisa atuar diretamente no fluxo de trabalho.

### Exemplos de Alertas Automatizados

As notificações cobrem uma ampla gama de situações operacionais e estratégicas, incluindo:

- Conflitos que impedem a execução de tíquetes
- Situações em que não é possível parar um item de configuração para manutenção
- Risco iminente ou violação de ANS (Acordo de Nível de Serviço)
- Alterações no CMDB, como inclusão, exclusão ou versionamento de itens de configuração
- Inclusão de Itens de Configuração que impactem outros elementos no mapa de relacionamento
- Notificações sobre diferenças entre a janela de manutenção planejada e a execução real de um tíquete
- Alertas de datas ou horários limiares, indicando que uma atividade precisa ser iniciada ou concluída
- Atualizações sobre o andamento de tíquetes e monitoramentos, especialmente em pontos críticos como a quebra de ANS
- Solicitações de ação imediata, quando o fluxo de trabalho exige a participação do destinatário
- Status do SLA – No prazo, A vencer, Vencido

### Configuração das Regras de Envio

As regras para disparo, formato e frequência das notificações são definidas conforme os critérios estabelecidos pela organização e podem ser ajustadas de acordo com o contexto da operação, processo ou perfil do usuário.

[title] Financeiro do quadro/projeto e rentabilidade
[path] Aplicações/Agility/Financeiro/

:::BlockQuote
Configure o orçamento e os vínculos comerciais do projeto, acompanhe previsto versus realizado, solicite faturamentos e leia a margem por projeto, cliente ou contrato.
:::

:::hint{type="info"}
**Pré-requisito:&#x20;**

Tenha um projeto com a capability Financeiro e, se for associar dimensão comercial, um cliente e contrato cadastrados no Workspace.
:::

***

O financeiro do quadro/projeto é a superfície operacional do trabalho: reúne configuração, custo previsto, custo realizado, lançamentos, produtos e serviços contratados, ordens de serviço, SLAs, solicitações de faturamento e a rentabilidade por tipo. Um Board principal abre essa superfície pela rota do Board; um projeto Tradicional sem Board usa a mesma superfície no escopo do Projeto.

A rentabilidade é calculada sobre os mesmos fatos do projeto. Nos cartões superiores, \*\*Receita\*\* mostra o reconhecido e o faturado, \*\*Custo\*\* soma as saídas apropriadas, \*\*Margem\*\* é receita menos custo e \*\*Margem %\*\* é a margem em relação à receita reconhecida. No Financeiro do Workspace, a aba \*\*Rentabilidade\*\* consolida e compara os resultados por \*\*projeto\*\*, \*\*cliente\*\* ou \*\*contrato\*\*; a linha de projeto é um link para seu financeiro detalhado.

***

### Passo a passo

::::WorkflowBlock
:::WorkflowBlockItem
**Abrir o financeiro do quadro ou projeto**

No projeto, selecione \*\*Financeiro\*\*. Projetos com Board principal são encaminhados ao Financeiro do Board; a rota recebe \`workspaceId\`, \`projectId\` e \`boardId\`. Projetos Tradicionais sem Board renderizam diretamente o Financeiro do Projeto. A superfície mostra no cabeçalho o cliente e o código do contrato quando esses vínculos já estiverem configurados.
:::

:::WorkflowBlockItem
**Configurar o custo previsto e os vínculos**

Clique em \*\*Configurar\*\*. Em \*\*Custo previsto (R$)\*\* informe o orçamento de custo operacional do projeto. Selecione opcionalmente um \*\*Cliente\*\* e um \*\*Contrato\*\*; ambos vêm dos cadastros do Workspace e o contrato pode ser deixado sem vínculo. Os vínculos alimentam a dimensão usada na rentabilidade por cliente e por contrato e também filtram opções de faturamento e ordens de serviço.
:::

:::WorkflowBlockItem
A mesma caixa permite informar uma \*\*Verba corporativa (ref.)\*\* e um \*\*Projeto do ERP (dimensão de orçamento)\*\*. A referência é textual, por exemplo \`VERBA-TI-2026\`; quando o projeto do ERP está vinculado, a disponibilidade da verba passa a ser fato confirmado pelo ERP. Não digite um saldo de verba no Agility. Salve e confira os cartões \*\*Custo previsto\*\*, \*\*Custo realizado\*\* e \*\*Desvio (realizado − previsto)\*\*.
:::

:::WorkflowBlockItem
**Interpretar previsto versus realizado**

O cartão \*\*Custo previsto\*\* vem da configuração. \*\*Custo realizado\*\* é formado pelas despesas, compras e apropriações de horas salvas no projeto; receitas e faturamentos não são custo. O \*\*Desvio\*\* é realizado menos previsto: valor positivo indica estouro. Quando a regra de alerta for atingida, a tela exibe um aviso com limiar, causa e período; quando não houver alerta, exibe \*\*dentro do previsto\*\*.
:::

:::WorkflowBlockItem
**Vincular o que foi contratado**

No card \*\*Produtos e serviços\*\*, clique em \*\*Vincular item\*\*. Escolha um item ativo do catálogo, informe a quantidade, revise o \*\*Preço acordado (R$)\*\* — que pode ser diferente do preço de referência atual — e, se necessário, acrescente uma observação. Salve o vínculo. O card mostra quantidade de itens, total contratado e uma tabela com item, unidade, quantidade e preço acordado. Para alterar, use \*\*Ajustar\*\*; para retirar, use \*\*Desvincular\*\*.
:::

:::WorkflowBlockItem
**Usar contratos e ordens de serviço**

No card \*\*Ordens de serviço\*\*, clique em \*\*Nova OS\*\* para abrir uma ordem vinculada ao projeto e a um contrato ativo. Informe código e título. Em um Board, uma OS aberta no nível do contrato e ainda sem projeto também pode ser adotada com \*\*Vincular OS\*\*; em projeto sem Board não existe essa adoção. O status da OS (Aberta, Em andamento, Concluída ou Cancelada) aparece na tabela.
:::

:::WorkflowBlockItem
**Solicitar um faturamento**

Clique em \*\*Solicitar faturamento\*\* no topo da superfície. Informe o \*\*Valor (R$)\*\*, que vem sugerido pela receita acumulada, e escolha opcionalmente um \*\*Contrato\*\*. Clique em \*\*Solicitar\*\*. A operação usa uma chave idempotente formada pelo escopo e pelo valor para evitar duplicar a mesma solicitação; a nova linha aparece no card \*\*Faturamento\*\*.
:::

:::WorkflowBlockItem
**Acompanhar o ciclo da solicitação**

No card \*\*Faturamento\*\*, acompanhe os estados \*\*Rascunho\*\*, \*\*Solicitado\*\*, \*\*Processando\*\*, \*\*Emitido\*\* ou \*\*Rejeitado\*\*. As ações disponíveis avançam ou rejeitam somente as transições permitidas; use \*\*Processar\*\* ou \*\*Emitir\*\* conforme o estado atual. Se o ERP ou a integração mudar o estado, não force uma transição pela tela: leia a situação retornada e siga o fluxo aceito.
:::

:::WorkflowBlockItem
**Ler a rentabilidade do projeto**

No topo, compare Receita, Custo, Margem e Margem %. Abaixo, o card \*\*Rentabilidade entre projetos\*\* do detalhe exibe a decomposição dos lançamentos por tipo e natureza. Receita reconhecida é a base do percentual; sem receita reconhecida, Margem % aparece como \`—\` e a tela informa que não há receita reconhecida para calcular o percentual.
:::

:::WorkflowBlockItem
**Consolidar por projeto, cliente ou contrato**

Volte ao menu \*\*Financeiro\*\* do Workspace e permaneça na aba \*\*Rentabilidade\*\*. Em \*\*Rentabilidade por projeto\*\*, selecione \*\*Por projeto\*\*, \*\*Por cliente\*\* ou \*\*Por contrato\*\*. Cada tabela traz Receita, Custo, Margem e Margem %. Na visão por projeto, clique no nome para abrir o Financeiro daquele projeto; as visões por cliente e contrato permitem comparar a carteira sem alterar os fatos.
:::

:::WorkflowBlockItem
**Conferir fontes e limitações**

Na tabela de lançamentos, a coluna \*\*Origem\*\* identifica se o fato é do Agility ou externo; os fatos externos são somente leitura. Produtos contratados, OS e SLAs têm cards próprios, mas não substituem o lançamento financeiro. Se o projeto for sintético, apenas a consolidação é exibida e a execução deve ser registrada nos projetos analíticos.
:::
::::

:::hint{type="success"}
:FontAwesome[]{icon="fa-solid fa-check"} **Verificação**

- Os cartões exibem custo previsto, custo realizado e desvio, e o desvio muda quando uma despesa, compra ou hora é lançada.
- O cabeçalho do projeto mostra o cliente e o código do contrato configurados, quando houver.
- Produtos ou serviços vinculados exibem quantidade, preço acordado e total contratado, sem alterar retroativamente o preço de referência do catálogo.
- Uma solicitação de faturamento aparece no card Faturamento e percorre apenas transições de estado válidas.
- A visão Rentabilidade do Workspace mostra as três dimensões — projeto, cliente e contrato — com receita, custo, margem e percentual.
- Na visão por projeto, clicar no nome abre o Financeiro detalhado do projeto correspondente.
:::

:::hint{type="warning"}
****:FontAwesome[****]{icon="fa-solid fa-triangle-exclamation"}**&#x20;Erros comuns**

**Capability Financeiro indisponível**

Se o projeto não tiver a capability efetiva de Financeiro, o acesso direto é bloqueado e a tela informa o motivo. Habilite a capability na configuração do projeto ou escolha um projeto que tenha essa capacidade antes de tentar lançar fatos.

**Item inativo ou já vinculado**

Itens desativados não entram no seletor de vínculo; reative-os em Financeiro → Cadastros. Se o item já estiver vinculado, ajuste quantidade e preço do vínculo existente em vez de criar outra linha.

**Contrato inativo para nova OS**

A abertura de uma OS exige contrato ativo. Se o contrato estiver inativo ou não houver contrato selecionado, volte aos cadastros, revise a situação e configure um contrato válido para o projeto.

**Transição de faturamento inválida**

O servidor só aceita a sequência de estados prevista para faturamento. Se a mensagem indicar transição inválida, não repita o mesmo comando: atualize a lista, leia o estado atual e use a ação compatível ou corrija o processo no sistema de origem.

**Margem percentual sem receita**

Quando não existe receita reconhecida, a coluna Margem % mostra \`—\`. Isso não significa margem zero; registre ou reconheça a receita adequada antes de interpretar o percentual.

**Valores de verba corporativa não confirmados**

Sem vínculo ou resposta do ERP, o card de verba não inventa um saldo: informa que a verba não está orçada ou que o saldo não foi confirmado. Confira o Projeto do ERP e a integração; o Agility controla o consumo operacional, mas o saldo é fato do ERP.

**Projeto sintético sem lançamentos diretos**

A mensagem de projeto sintético é esperada: esse tipo apenas agrupa e consolida. Abra o projeto analítico que contém o Board ou a execução para cadastrar lançamentos, horas e faturamentos.
:::


[title] Cadastro fiscal próprio
[path] Aplicações/ERP/Manual do Usuário/

# Cadastro fiscal próprio (empresa e estabelecimentos)

:::BlockQuote
Pré-requisitos: nenhum. Esta é a primeira coisa que você cadastra ao receber um tenant novo — todo o resto do sistema depende dela.
:::

## Introdução

***

Antes de emitir qualquer nota fiscal ou abrir um almoxarifado, o sistema precisa saber **quem é você** — qual o seu *CNPJ*, qual o seu regime tributário, quais filiais operam. Esta seção cobre o cadastro da sua *empresa* (a raiz do CNPJ, com 8 dígitos) e dos seus *estabelecimentos* (a matriz e as filiais, cada um com o CNPJ completo de 14 dígitos).

Sem este cadastro pronto, o sistema **bloqueia a maior parte das operações**: não há emissão de *NF-e*, não há criação de almoxarifado (o depósito exige um estabelecimento vinculado), não há lançamento contábil nem financeiro amarrado a um CNPJ. Por isso, em um tenant recém-provisionado, **comece por aqui**.

:::BlockQuote
**Dica:** cadastre **2 estabelecimentos ativos** (matriz + 1 filial) logo no início. Alguns recursos do sistema (relatórios multi-filial, transferência de estoque entre filiais, emissão de nota com CNPJ diferente por depósito) só fazem sentido com mais de um estabelecimento.
:::

## Passo a passo

***

### Abrir a tela de empresas

1. **Abra "Empresa".** No menu lateral, em **Cadastros** (ou **Administração**, conforme o seu perfil), clique em **Empresa**. Abre a lista de empresas cadastradas, com as colunas **CNPJ raiz**, **Razão social**, **CRT** e **Status**.A lista tem busca, ordenação por coluna e paginação. Cada linha traz um ícone de **lápis** (abrir/editar) e, nas empresas ativas, a ação **Inativar**.

### Cadastrar a empresa (CNPJ raiz)

1. **Clique em "Nova empresa".** O botão fica no canto superior direito da lista. Abre um formulário de página única — você preenche os dados da empresa, salva, e o sistema leva você para a ficha da empresa, onde você acrescenta os estabelecimentos.
2. **Preencha o CNPJ raiz e tabule.** Digite os **8 primeiros dígitos** do CNPJ (ex.: 11222333) no campo "CNPJ raiz" e pressione Tab. A razão social é preenchida automaticamente via consulta pública ao CNPJ (BrasilAPI). Confira e ajuste se necessário — no exemplo do manual usamos ACME Servicos Ltda.
3. **Complete os dados fiscais.**
   - **CRT (Código de Regime Tributário):** escolha entre 1 — Simples Nacional, 2 — Simples + sublimite, 3 — Regime Normal ou 4 — MEI. No exemplo do manual usamos 3 — Regime Normal.
   - **Natureza jurídica:** busque na lista pelo código ou nome (ex.: 2046 — Sociedade Empresária Limitada, a "LTDA").
   - **Classificação tributária:** geralmente 99 — Pessoa jurídica em geral.
   - **Regime PIS/Cofins:** Cumulativo, Não cumulativo ou Misto, conforme o seu enquadramento.
   - **Responsável legal:** nome completo, CPF (ex.: 296.936.410-78) e a **qualificação** do responsável (ex.: 16 — Presidente, 22 — Sócio, 49 — Sócio-administrador).
   - **E-mail de contato fiscal (opcional):** e-mail para onde vão comunicados fiscais.
4. **(Opcional) Configurações avançadas.** Expanda o accordion **"Configurações avançadas"** se a empresa precisar de algum destes:
   - **NIRE** — número de registro na Junta Comercial.
   - **Plano de contas de referência (ECD)** — indicador do plano usado na Escrituração Contábil Digital.
   - Marcadores especiais: **Cooperativa**, **Construção civil**, **Desoneração da folha**, **Atividade rural** e **Grande empresa**. Deixe desmarcados se não se aplicam.
5. **Clique em "Salvar empresa".** O sistema cria a empresa e leva você para a **ficha da empresa**, onde os estabelecimentos são cadastrados. A empresa passa a aparecer na lista com a razão social vinda da Receita.

### Cadastrar a matriz

Na ficha da empresa, abaixo dos dados da empresa, há o card **Estabelecimentos**.

1. **Clique em "Adicionar estabelecimento".** Abre um formulário inline. O campo **CNPJ completo** já vem pré-preenchido com a raiz da empresa + a sequência 0001 e os dígitos verificadores calculados — a matriz **sempre** termina em 0001 (ex.: 11222333000181). Se você digitar um CNPJ com raiz diferente da empresa, o sistema avisa na hora ("CNPJ root must be...").
2. **Informe o nome fantasia (opcional)** e **preencha o endereço pelo CEP.** Digite o CEP (ex.: 01310-100) e tabule — rua, bairro, cidade e UF são autopreenchidos. Confira o número e o complemento. O código IBGE do município é resolvido automaticamente a partir do endereço.
3. **Informe a Inscrição Estadual (opcional).** Deixe em branco, digite o número da IE ou escreva ISENTO.
4. **Escolha o *CNAE* principal.** Use a busca por palavra-chave (ex.: "desenvolvimento" → 6201501 — Desenvolvimento de programas de computador sob encomenda). CNAEs secundários você acrescenta depois, nos sub-cadastros.
5. **Salve.** A matriz aparece na tabela de estabelecimentos com o marcador **★** (indica a sede) e a filial 0001.



![](https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/001-admin-detail.png)

### Cadastrar uma filial

1. **Clique em "Adicionar estabelecimento" de novo.**
2. **Informe o CNPJ da filial.** Mesma raiz da empresa, mas a sequência **não pode** ser 0001 (ex.: 11222333000262, que é a filial 0002).
3. **Endereço + CNAE.** Mesmo processo da matriz — CEP para autopreencher o endereço, CNAE principal pela busca.
4. **Salve.** A filial aparece na tabela, com o número da filial (ex.: 0002) e **sem** o marcador ★.

### Editar empresa e estabelecimentos

1. **Editar a empresa.** Na lista de empresas, clique no **lápis** da linha (ou, já dentro da ficha, ajuste os campos do card superior). Altere razão social, regime, responsável, etc., e clique em **"Salvar alterações"**. Aparece um "Salvo às HH\:MM\:SS" verde confirmando.
2. **Editar um estabelecimento.** Na tabela de estabelecimentos, clique no **lápis** da linha. O formulário abre em modo "Editar estabelecimento" já preenchido. O **CNPJ fica bloqueado** (não se altera o CNPJ de um estabelecimento em produção — isso passa pelo suporte). Ajuste o nome fantasia, endereço ou CNAE e clique em **"Salvar alterações"**.

### Inativar / reativar

1. **Inativar uma filial.** Na tabela de estabelecimentos, clique no ícone de **proibido** (Inativar) na linha da filial. Ela fica com o status **Inativo** (cinza), mas o histórico é preservado.
2. **Inativar a empresa.** Só é possível depois de inativar **todas** as filiais ativas — se tentar antes, o sistema bloqueia (veja Erros comuns). Na lista de empresas, use a ação **Inativar** na linha.

### Sub-cadastros do estabelecimento

Cada estabelecimento tem 4 abas de sub-cadastros. Para abri-las, clique no botão **"Sub-cadastros"** (ícone de seta ▸) na linha do estabelecimento — um painel inline se expande abaixo, com estas abas:

- **CNAEs secundários** — atividades adicionais além da principal (ex.: 5811500 — Edição de livros, além do desenvolvimento de software). Adicionar o mesmo CNAE duas vezes é bloqueado.
- ***IEST*** — Inscrição Estadual de Substituto Tributário, uma por UF onde você recolhe ICMS-ST como substituto (ex.: (MG, 12345)). Cada linha tem lápis para editar. Só pode haver uma IEST por UF neste estabelecimento.
- ***CSC* NFC-e** — token de segurança da SEFAZ para emitir NFC-e, cadastrado por UF (ex.: (SP, 000001, TOKEN-DEMO-123)). **Após salvar, o token nunca mais aparece em texto puro** — fica armazenado cifrado. Ao **editar**, o campo Token aparece **em branco**: deixe assim para manter o token atual, ou digite um novo para trocá-lo.
- **Contas bancárias** — **vincule** ao estabelecimento uma conta bancária **já cadastrada** em Financeiro → Contas bancárias, escolhendo a **finalidade** (Fiscal, Cobrança ou Pagamento) e, se quiser, marcando-a como **padrão** daquela finalidade. Se ainda não houver conta cadastrada, há um link para cadastrá-la primeiro. (Modelo unificado — não se cadastra mais banco/agência/conta diretamente aqui.) Reutilizar a mesma conta com a mesma finalidade é bloqueado.

### Usar o estabelecimento nas obrigações acessórias

O cadastro fiscal alimenta as telas de obrigações. Para conferir que ficou tudo certo:

1. **Reinf.** Acesse o menu **Reinf** (geração de EFD-Reinf). No campo de estabelecimento, um **dropdown** lista os estabelecimentos cadastrados — escolha a matriz, informe o período (ex.: 2026-05) e gere o lote.
2. **DCTFWeb.** Acesse o menu **DCTFWeb** (relatório). Mesma lógica: escolha o estabelecimento no dropdown, informe o período e baixe o PDF/JSON.

## Verificação

***

Você sabe que funcionou quando:

- A empresa aparece na lista de "Empresa" com a razão social vinda da Receita e o status **Ativo**.
- Na ficha da empresa, o CPF do responsável legal aparece **formatado** (296.936.410-78) — sem isso, é sinal de problema no salvamento.
- A tabela de estabelecimentos mostra a matriz com o marcador **★** e a filial **sem** ★, cada uma com o número de filial (0001, 0002) e a UF.
- Os sub-cadastros (CNAEs secundários, IEST, CSC, contas bancárias) podem ser abertos e listam os itens que você cadastrou.
- Nas telas de **Reinf** e **DCTFWeb**, o dropdown de estabelecimento lista a matriz que você acabou de cadastrar.

## Erros comuns

***

- **ROOT\_INCONSISTENT / "CNPJ root must be..."** — o CNPJ do estabelecimento tem raiz diferente da empresa. Confira os 8 primeiros dígitos: eles têm que ser exatamente os da empresa.
- **BRANCH\_CODE\_DUPLICATE** — você tentou cadastrar duas matrizes (dois CNPJs terminando em 0001) na mesma empresa. Só pode existir uma matriz por raiz; as demais são filiais (0002, 0003, ...).
- **"Dígito verificador inválido"** — o CNPJ digitado não passa na conferência de módulo 11. Confira os dois últimos dígitos.
- **LEGAL\_ENTITY.HAS\_ACTIVE\_ESTABLISHMENTS** — você tentou inativar uma empresa que ainda tem estabelecimentos ativos. Inative as filiais primeiro, depois a empresa.
- **IEST\_DUPLICATE** — já existe IEST cadastrada para esta UF neste estabelecimento. Edite a existente (lápis) em vez de adicionar outra.
- **ISSUER.NOT\_REGISTERED** (ao tentar emitir NF-e) — o estabelecimento não está cadastrado/apto para emitir. Volte ao cadastro e revise o CNPJ, o endereço e o CNAE do estabelecimento.
- **ESTABLISHMENT.REQUIRED** (ao criar um depósito) — o almoxarifado exige um estabelecimento vinculado. Cadastre ao menos a matriz antes de abrir depósitos.


[title] Documentação Citsmart X
[path] /

::::LinkArray{contentSource="CUSTOM" itemsPerRow="2"}
:::LinkArrayItem{headerType="IMAGE" headerImage="https://archbee-image-uploads.s3.amazonaws.com/EkhIfdQkw9x_8PD4a0GRC-hD6NBAzFsDjxwtkj6_hdJ-20240821-202042.png"}
[](https://docs.citsmart.com/conheca-o-citsmart-x)

Uma plataforma integrada 100% web, desenvolvida para acelerar a transformação digital nas organizações.
:::

:::LinkArrayItem{headerType="IMAGE" headerImage="https://archbee-image-uploads.s3.amazonaws.com/EkhIfdQkw9x_8PD4a0GRC-DGBDgWsJ7WLfyRwCi9daB-20240821-200408.png"}
[](https://docs.citsmart.com/workflow)

Uma plataforma totalmente web, desenvolvida para transformar a maneira como as empresas conectam pessoas a recursos digitais.
:::

:::LinkArrayItem{headerType="IMAGE" headerImage="https://archbee-image-uploads.s3.amazonaws.com/EkhIfdQkw9x_8PD4a0GRC-Blevc6-EzoWiuwCmXpsOT-20240821-200434.png"}
[](https://docs.citsmart.com/low-code)

Uma plataforma de desenvolvimento, que integra o portfólio de soluções utilizando o desenvolvimento rápido e seguro de aplicações.
:::

:::LinkArrayItem{headerType="IMAGE" headerImage="https://archbee-image-uploads.s3.amazonaws.com/EkhIfdQkw9x_8PD4a0GRC-Mby0oJCUZsGCBoZr-A-2x-20240821-202057.png"}
[](https://docs.citsmart.com/agility)

Uma plataforma de gerenciamento fácil e ágil de atividades. Criada para gerenciar os projetos da maneira mais simples.
:::

:::LinkArrayItem{headerType="IMAGE" headerImage="https://archbee-image-uploads.s3.amazonaws.com/EkhIfdQkw9x_8PD4a0GRC-0u02Lb4ox5e537dLBII2P-20240821-200455.png"}
<font color="#3b9f0f"></font>

<font color="#3b9f0f">*AIOPS*</font> é uma plataforma de IPM (Infrastructure Performance Monitoring), NPM (Network Performance Monitoring), APM (Application Performance Monitoring) e Orquestração (por Low Code – Drag & Drop de Componentes) – Tudo gerenciado por IA.
:::

:::LinkArrayItem{headerType="IMAGE" headerImage="https://archbee-image-uploads.s3.amazonaws.com/EkhIfdQkw9x_8PD4a0GRC-Xo-WHkYdyNYOlKVo1MZT7-20240821-202013.png"}
<font color="#3da410fe"></font>

Nossa ferramenta de IA para criação de Chatbots e supervisores cognitivos.
:::

:::LinkArrayItem{headerType="IMAGE" headerImage="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/94olFS2ZRo7RS95YKzaUC_studio1.jpg"}
<font color="#3b9f0f"></font>

O Low Code Studio é a plataforma da Run2Biz para criar aplicativos web e mobile de forma visual e intuitiva — sem precisar escrever código do zero.
:::

:::LinkArrayItem

:::
::::


[title] Fiscal — entrada
[path] Aplicações/ERP/Manual do Usuário/

# Fiscal — entrada (nota de compra / NF-e recebida)

:::BlockQuote
Pré-requisitos: [Cadastro fiscal próprio](docId\:Q-zx6Qk4pMFD09yrhmsve) (empresa e estabelecimento ativos, CRT correto) e [Compras](docId:3mdo_BH5DDXIp3VIh4ATK) (um pedido de compra e um recebimento de mercadoria com o fornecedor que vai lhe mandar a nota).
:::

## Introdução

***

Quando um fornecedor entrega mercadoria, ele também envia a **nota fiscal de saída dele** — que, do seu lado, é a **nota de entrada**. Esta página mostra como recepcionar essa nota no ERP, conferi-la contra o pedido e o recebimento (a chamada conferência de três vias), aprovar e deixar o sistema gerar sozinho a **conta a pagar** para o fornecedor. É o passo que fecha o ciclo de compra: sem a nota de entrada lançada e aprovada, o financeiro não tem o pagável e o fiscal não tem o registro de entrada do período.

O operador típico é o **assistente fiscal ou de contas a pagar**, que recebe a NF-e do fornecedor (por e-mail em XML, por chave de acesso ou digitando os dados) e precisa garantir três coisas: que a nota bate com o que foi pedido e recebido, que as retenções de tributos federais foram calculadas quando cabem, e que o pagamento ao fornecedor entra na fila com o valor e vencimento certos. As regras de alíquota e *CFOP* usadas na conferência vêm do cadastro de **regras fiscais por produto** ([Cadastro fiscal próprio](docId\:Q-zx6Qk4pMFD09yrhmsve)), então vale conferi-lo antes de operar em volume.

## Passo a passo

***

### Abrir a lista de notas de entrada

1. **Abra "Compras → Notas de entrada".** A tela lista as notas já lançadas, com **número**, **pedido** de origem, **total** e **situação** (Aprovada, entre outras). No topo há a busca por número e o botão "Nova nota".:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/065-purchase-invoices.png" alt caption width="3200" height="2000"}

### Lançar a nota do fornecedor

1. **Clique em "Nova nota".** Você informa o **pedido de compra** que originou a entrega (ex.: PC-000001) e os dados da nota do fornecedor: **número**, **chave de acesso** (os 44 dígitos da NF-e, quando houver), **data de emissão**, **vencimento** e **valor total** (ex.: R$ 4.000,00). Quando você tem o arquivo XML da NF-e enviado pelo fornecedor, os campos podem ser preenchidos a partir dele; quando não há XML (compra avulsa ou nota de serviço), digite manualmente.
2. **Vincule o fornecedor.** A nota fica amarrada ao **Fornecedor Exemplo Ltda** (ou ao parceiro correspondente do pedido). Salve.

**Trazer a NF-e importada para compras, sem digitar de novo**

Quando o fornecedor manda o XML, o caminho curto é **Fiscal → Importar documentos eletrônicos**: importe o XML e, na linha do documento, clique em **"Trazer para compras"**. Você informa só o **vencimento** — número, chave de acesso, emitente, itens e total vêm do próprio documento.

**O pedido de compra também vem do documento, quando o fornecedor o declarou.** O leiaute da NF-e reserva, em cada item, o campo do **número do pedido de compra do comprador** (a tag xPed), preenchido pelo fornecedor a partir do pedido que você enviou. A tela mostra, antes de você confirmar, os pedidos que a nota declara — e é por eles que cada linha da nota é ligada ao item do pedido correspondente.

Três coisas que valem saber, porque não são óbvias:

- **Uma nota pode cobrir mais de um pedido.** Como o campo é por item, o fornecedor pode juntar numa remessa só o que foi comprado em duas ocasiões. Cada linha guarda o seu pedido; o cabeçalho fica com o predominante.
- **Quando o fornecedor não declara o pedido**, a tela pede que você informe qual é — e aí o casamento dos itens volta a ser feito pela descrição, como na entrada manual.
- **O sistema não escolhe por você quando fica em dúvida.** Se o número declarado corresponde a mais de um pedido do mesmo fornecedor, a linha fica **sem vínculo** e aparece como divergência para você resolver, em vez de o sistema chutar um dos dois.

### Conferir contra pedido e recebimento (conferência de três vias)

1. **Abra a ficha da nota** clicando na linha da lista. A ficha traz o cabeçalho — **número**, **chave de acesso**, **pedido**, **fornecedor**, **emissão**, **vencimento**, **total** e **situação** — e, logo abaixo, o quadro **Divergências**.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/014-purchase-invoices-detail.png" alt caption width="3200" height="2000"}
2. A conferência usa o recebimento registrado em **Compras → Recebimentos** ([Compras](docId:3mdo_BH5DDXIp3VIh4ATK)). Se você ainda não lançou o recebimento do pedido, faça-o antes — sem ele não há a "terceira via" para comparar.

**Leia o quadro "Divergências".** O sistema compara três documentos — o **pedido** (o que foi combinado), o **recebimento** (o que chegou fisicamente ao *almoxarifado*) e a **nota** (o que o fornecedor está cobrando). Quando os três batem em quantidade e valor, aparece **"Sem divergências"** e a nota pode ser aprovada com segurança. Se houver diferença (quantidade recebida menor que a faturada, preço acima do pedido etc.), a divergência é listada aqui para você decidir se aceita ou rejeita.

### Calcular retenções de tributos federais

1. **Use "Calcular retenções"** (botão no topo direito da ficha). Para notas de serviço ou de fornecedores sujeitos a retenção, o sistema apura os tributos federais retidos na fonte (PIS/Cofins/CSLL e IRRF, conforme a regra do fornecedor e do valor). O valor retido é abatido do que você paga ao fornecedor e fica registrado para as obrigações acessórias do mês (ver "Obrigações acessórias" adiante). Em notas comuns de mercadoria sem retenção, o resultado é zero e nada muda no pagável.

### Aprovar e gerar a conta a pagar

1. A nota de entrada exige uma **categoria financeira** para gerar o pagável — é ela que classifica a despesa no financeiro. Se o sistema pedir e você não tiver, cadastre em **Cadastros → Categorias financeiras** ([Financeiro — cadastros de apoio](docId\:yTzjjyyML1B_60VgwDT09)) antes de aprovar.

**Aprove a nota.** Com a conferência limpa (ou com as divergências aceitas dentro da sua *alçada*), a situação passa a **Aprovada**. A autoridade para lançar e aprovar é resolvida pelo **cargo** (via lotação): um usuário sem cargo definido — inclusive um administrador de plataforma — é barrado (fail-closed). A aprovação dispara automaticamente:

:::Paragraph{listStyleType="disc" indent="2"}
A **conta a pagar** ao fornecedor, com o **valor da nota** (líquido de retenções, quando houver) e o **vencimento** informado. Ela passa a aparecer em **Financeiro → Documentos** ([Financeiro — cadastros de apoio](docId\:yTzjjyyML1B_60VgwDT09)).
:::

:::Paragraph{listStyleType="disc" indent="2"}
O **lançamento contábil** de mercadoria/serviço e dos tributos a recuperar ou retidos, conforme o *plano de contas*.
:::

:::Paragraph{listStyleType="disc" indent="2"}
O **registro de entrada** para a apuração fiscal do período.
:::

### Conferir as parametrizações fiscais que a entrada usa

1. **Revise "Cadastros → Regras fiscais por produto"** quando as alíquotas ou o *CFOP* da entrada não baterem com o esperado. Essa tela define **alíquotas e CFOP** por combinação de produto, regime tributário e UFs de origem/destino — a mesma base usada para calcular os tributos da nota. Cada regra mostra o **escopo** (ex.: filtro por *NCM*), a **operação**, as **UFs**, o **CFOP** e os percentuais de ICMS, IPI, PIS e Cofins.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/017-product-fiscal-rules.png" alt caption width="3200" height="2000"}

### Escriturar e apurar (obrigações acessórias)

1. **Não há passo manual de escrituração** — ao aprovar, a nota entra automaticamente no registro de entradas do período. As retenções calculadas no passo 6 alimentam as obrigações acessórias federais (EFD-Reinf e DCTFWeb), geradas em **Fiscal → EFD-Reinf / DCTFWeb** por estabelecimento e período. Ali você fecha o mês e emite os arquivos/guias correspondentes.
2. **Lance as retenções IRRF-PF avulsas antes de gerar o lote.** Em **Fiscal → EFD-Reinf**, abaixo dos lotes, o card **"Retenções IRRF-PF avulsas"** recebe as retenções sobre pagamento a **pessoa física fora da folha** — um serviço pontual, um aluguel, um honorário. Elas **alimentam o lote do período selecionado acima**; um lote gerado sem elas sai incompleto.
   - **Escolha o estabelecimento primeiro.** A retenção precisa nomear o emitente que a pagou; sem ele os botões ficam travados.
   - **Uma a uma:** informe CPF do beneficiário, natureza do rendimento, valor bruto, imposto retido e data do pagamento.
   - **Ou por arquivo:** envie um **CSV** com as colunas cpfBenef, natRend, vlrRendBruto, vlrIr, dtPgto (e observ opcional), com linha de cabeçalho. O sistema informa **quantas linhas gravou** — é assim que você distingue um arquivo lido inteiro de um em que a leitura parou no meio.
   - Não há listagem do que foi lançado: estas retenções são **insumo** do lote, não um cadastro. O que confirma o lançamento é o próprio aviso da tela e, depois, o lote gerado.
3.

**A armadilha:** um evento que você transmitiu e não marcou aqui continua entrando nas conferências como pendente. Na virada do mês isso aparece como obrigação em aberto que, na Receita, já está cumprida — e a divergência é descoberta tarde, quando alguém compara os dois lados.

**Depois de transmitir, volte e diga o que aconteceu.** Gerar e baixar o pacote é metade do trabalho: quem transmite ao fisco é você, no portal da Receita, e o ERP só sabe o desfecho se alguém contar. Na lista de lotes, clique em **Ver eventos** para abrir os eventos daquele lote.

:::Paragraph{listStyleType="disc" indent="2"}
**Evento aceito:** informe o **nº do recibo** que a Receita devolveu e clique em **Marcar transmitido**. Sem isso o evento fica **Pendente** para sempre, e o mês nunca fecha de verdade — o pacote foi entregue, mas o sistema continua achando que não.
:::

:::Paragraph{listStyleType="disc" indent="2"}
**Evento rejeitado ou com valor errado:** clique em **Abrir retificação** no evento já transmitido. O sistema cria o evento retificador amarrado ao recibo original, que é o que a EFD-Reinf exige — retificar não é gerar o lote de novo.
:::

:::Paragraph{listStyleType="disc" indent="2"}
**O recibo é por evento, não por lote.** A Receita responde evento a evento, e um lote pode ter parte aceita e parte rejeitada. Por isso a marcação é feita linha a linha.
:::

## Verificação

***

Você sabe que funcionou quando:

- A nota aparece na lista de **Notas de entrada** com a situação **Aprovada** e o **pedido** de origem vinculado (ex.: PC-000001).
- O quadro **Divergências** da ficha mostra **"Sem divergências"** (ou as divergências aceitas estão registradas).
- Existe uma **conta a pagar** para o fornecedor em **Financeiro → Documentos**, com o **valor da nota** e o **vencimento** informado.
- O **estoque** do produto subiu na quantidade do recebimento vinculado ([Estoque](docId\:CVozhYtoHDtuWZyT-bnAT)).
- Quando havia retenção, o valor **retido** aparece calculado e o pagável saiu líquido.

## Erros comuns

***

- **Nota sem pedido para casar** — o fornecedor mandou a nota sem pedido prévio (compra avulsa). Lance a nota informando os dados manualmente; sem o pedido não há conferência de três vias, mas o pagável ainda é gerado ao aprovar.
- **Divergência de quantidade ou valor** — o recebimento registrou menos do que a nota fatura, ou o preço veio acima do pedido. O quadro Divergências aponta a diferença; ajuste o recebimento ([Compras](docId:3mdo_BH5DDXIp3VIh4ATK)) ou trate a diferença com o fornecedor antes de aprovar.
- **"Sem categoria financeira"** — a nota não consegue gerar o pagável porque falta a categoria que classifica a despesa. Cadastre a categoria ([Financeiro — cadastros de apoio](docId\:yTzjjyyML1B_60VgwDT09)) e tente aprovar de novo.
- **"Sem autorização"** — lançar e aprovar a nota de entrada exige um usuário com **cargo** que dê a autoridade (perfil de compras/fiscal, via lotação). Um usuário sem cargo — mesmo administrador de plataforma — recebe **"Sem autorização"** por padrão (o sistema falha fechado). Troque para a persona com o cargo adequado.
- **Nota duplicada** — a mesma chave de acesso já foi lançada. Procure na busca da lista antes de criar uma nova.


[title] Backlog e requisitos
[path] Aplicações/Agility/Backlog e planejamento/

:::BlockQuote
Use o Backlog para organizar o trabalho pendente de um projeto Scrum e o Planejamento para registrar requisitos, priorizá-los e manter a rastreabilidade até a entrega e a tarefa que os atende.
:::

:::hint{type="info"}
**Pré-requisito:**

Tenha um Workspace com um projeto Scrum e seu Board principal. Para cadastrar requisito, o projeto não pode ser sintético e você precisa ter permissão de edição.
:::

***

O Backlog do projeto Scrum é a fila de trabalho que ainda não foi colocada em uma Sprint. A tela carrega os itens do Team Backlog, exibe código, título e pontos, permite reordenar a fila e oferece o cadastro rápido de um novo item. O item criado passa a ser uma tarefa disponível para o planejamento de Sprint; ele não é um requisito de negócio automaticamente.

Requisitos vivem na aba Planejamento e registram a necessidade que originou a entrega. Cada requisito tem código, título, descrição opcional, origem, prioridade, critério de aceite e situação. A aplicação mostra as entregas vinculadas (épico, feature, história ou tarefa), para que a equipe consiga seguir a relação requisito → entrega e, a partir da tarefa, voltar para o requisito.

***

### Passo a passo

::::WorkflowBlock
:::WorkflowBlockItem
**Abrir o Backlog do projeto**

No Workspace, abra um projeto Scrum e selecione Backlog na navegação do projeto. A rota só renderiza o Team Backlog quando a capacidade de backlog está habilitada e o método de entrega é Scrum; em outros modelos a própria tela informa que a capacidade não está disponível, em vez de apresentar uma lista incorreta.
:::

:::WorkflowBlockItem
**Ler e ordenar a fila**

Confira cada linha pelo código, título e pontos. Quando houver mais de um item, arraste a linha pela alça de ordenação (ícone de pontos) até a posição desejada. A ordem é enviada ao servidor e permanece na lista mesmo depois de uma nova renderização; se a atualização falhar, a tela desfaz a ordem otimista e informa o erro.
:::

:::WorkflowBlockItem
**Criar um item de backlog**

Clique em Novo item. Informe o Título (obrigatório, até 240 caracteres), escreva a Descrição no editor de texto rico e, se já souber quem executará o trabalho, escolha uma Pessoa responsável. Informe Pontos da história como um número inteiro entre 1 e 100. O botão de criação só fica disponível quando título e pontos foram preenchidos.
:::

:::WorkflowBlockItem
**Usar a estimativa sugerida (opcional)**

Com título e descrição preenchidos, o formulário pode habilitar Gerar sugestão. A sugestão usa a raia de trabalho inicial do Board, preenche os pontos e identifica a origem da estimativa, o nível de confiança, os fatores considerados e as limitações. Expanda Mostrar raciocínio para conferir os fatores; se o serviço de sugestão falhar, leia o alerta e tente novamente ou preencha os pontos manualmente. A criação continua possível sem a sugestão.
:::

:::WorkflowBlockItem
**Confirmar o item no backlog**

Clique em Criar. Após o retorno do servidor, o diálogo fecha e a fila é atualizada com o novo código, título e estimativa. Se você aceitou uma sugestão, a decisão de estimativa também é registrada; essa gravação complementar não impede a criação caso falhe. Não confunda esse item com requisito: o backlog contém a execução, enquanto o requisito é cadastrado na aba Planejamento.
:::

:::WorkflowBlockItem
**Abrir o Planejamento e iniciar um requisito**

Selecione Planejamento na navegação do mesmo projeto e clique em Novo requisito. O diálogo apresenta Título (obrigatório), Descrição (opcional), Origem (obrigatória), Prioridade e Critério de aceite (obrigatório). A prioridade começa como Média e pode ser trocada para Alta ou Baixa; escreva o critério de forma verificável, preferencialmente no formato dado/quando/então.
:::

:::WorkflowBlockItem
**Revisar o requisito cadastrado**

Depois de clicar em Criar, a linha recebe um código RQ, exibe título, situação Rascunho, prioridade, origem e critério de aceite. A descrição, quando informada, aparece abaixo do título. Enquanto estiver em Rascunho, use Aprovar para mudar a situação para Aprovado. O botão Concluir existe para qualquer requisito ainda não concluído, mas a API exige uma entrega vinculada para aceitar a conclusão.
:::

:::WorkflowBlockItem
**Vincular uma entrega da hierarquia**

Na linha do requisito, clique em Vincular. O seletor agrupa as opções disponíveis por Épico, Feature e História e remove alvos que já estejam ligados. Escolha o código e o título corretos e confirme em Vincular entrega. O rastro passa a mostrar o nível, o código e o rótulo do alvo; alvos de hierarquia que não têm uma tela própria permanecem como texto, sem criar um link quebrado.
:::

:::WorkflowBlockItem
**Completar a ligação com uma tarefa**

Tarefa não aparece no seletor do diálogo do requisito, porque o quadro pertence ao Workspace e o requisito pertence ao projeto. Abra a tarefa no Board, localize o cartão Requisitos atendidos e clique em Vincular requisito. Escolha no seletor o requisito do catálogo, confirme e aguarde a recarga. O requisito passa a exibir Tarefa e o nome da tarefa; quando há Board e Workspace resolvidos, esse nome abre diretamente a rota da tarefa.
:::

:::WorkflowBlockItem
**Conferir os dois sentidos da rastreabilidade**

Na linha do requisito, use o link do nome da tarefa para voltar ao detalhe da tarefa. No detalhe, confira o mesmo requisito no cartão Requisitos atendidos, com código, título, situação e origem. Para remover a relação, use o ícone de desvincular em qualquer um dos lados e confirme que a outra tela deixa de mostrar a aresta. Uma tarefa pode atender mais de um requisito, e cada requisito mantém suas próprias entregas vinculadas.
:::
::::

:::hint{type="success"}
:FontAwesome[]{icon="fa-solid fa-check"} **Verificação**

- O Backlog mostra itens Scrum com código, título e pontos, e uma reordenação permanece após a atualização da lista.
- O requisito cadastrado aparece com código RQ, prioridade, origem, critério de aceite e situação Rascunho ou Aprovado.
- A linha do requisito mostra a entrega vinculada com o nível e o código; uma tarefa vinculada abre o detalhe correto do Board.
- O cartão Requisitos atendidos da tarefa apresenta o mesmo requisito e permite desvinculá-lo, comprovando o caminho de volta.
:::

:::hint{type="warning"}
****:FontAwesome[****]{icon="fa-solid fa-triangle-exclamation"}**&#x20;Erros comuns**

**O item de backlog não pode ser criado**

Verifique se Título e Pontos foram preenchidos. Pontos precisa ser um inteiro entre 1 e 100; para uma tarefa sem estimativa definida, escolha um valor inicial e registre a decisão no refinamento, em vez de enviar texto ou zero.

**A sugestão de pontos está indisponível**

A sugestão só habilita com título, descrição não vazia e uma raia inicial resolvida. Continue preenchendo Pontos manualmente; um erro do serviço de estimativa não bloqueia o cadastro do item.

**O requisito não pode ser concluído**

Um requisito só pode avançar para Concluído quando existe uma entrega vinculada. Vincule uma feature, história, épico ou tarefa, atualize a tela e tente Concluir novamente.

**A tarefa não aparece ao vincular pelo requisito**

Esse é o comportamento esperado: o diálogo do Planejamento oferece apenas épicos, features e histórias. Faça o vínculo no cartão Requisitos atendidos do detalhe da tarefa; o servidor manterá a mesma relação nos dois sentidos.
:::


[title] ERP
[path] Aplicações/


[title] Financeiro — cadastros de apoio
[path] Aplicações/ERP/Manual do Usuário/

# Financeiro — cadastros de apoio (categorias, centros de custo, contas bancárias, condições e meios de pagamento)

:::BlockQuote
Pré-requisitos: [Cadastro fiscal próprio](docId\:Q-zx6Qk4pMFD09yrhmsve) — a empresa ACME (matriz CNPJ 11222333000181 e filial 11222333000262) já está cadastrada. A conta bancária da matriz pode já existir no sub-cadastro do estabelecimento; aqui você organiza as estruturas financeiras de apoio que **complementam** esse cadastro.
:::

## Introdução

***

Antes de lançar a primeira conta a pagar ou a receber, o financeiro precisa de um punhado de "gavetas" prontas: as **categorias financeiras** (o plano gerencial que classifica cada título), os **centros de custo e de resultado** (para dividir despesas e receitas por área), as **contas bancárias** operacionais da empresa, as **condições de pagamento** (à vista, 30/60/90 dias) e os **meios de pagamento** aceitos (boleto, PIX, transferência, cartão). Sem esses cadastros, a nota de compra e a de venda não conseguem gerar o pagável nem o recebível — o sistema pede uma categoria e uma condição na hora de fechar.

Você faz esses cadastros uma vez, no começo da operação, e depois só ajusta pontualmente. A maior parte já vem pré-carregada por seed; o seu trabalho aqui é **revisar, adaptar ao seu negócio e completar** o que faltar. Os cinco cadastros ficam no menu **Financeiro** (à exceção de **Condições de pagamento**, que está no menu **Cadastros** por ser usada também nas tabelas de preço de vendas).

## Passo a passo

***

### Categorias financeiras (plano gerencial)

A *categoria financeira* é o rótulo que diz "que tipo de dinheiro é este": receita de vendas, despesa com aluguel, despesa com fornecedores, etc. Toda conta a pagar e a receber precisa de uma categoria — é ela que alimenta os relatórios gerenciais e o *DRE* por bucket.

1. **Abra "Categorias financeiras".** No menu lateral, expanda **Financeiro** e clique em **Categorias financeiras**. A lista mostra as categorias já cadastradas, separando receitas de despesas.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/020-financial-categories.png" alt caption width="3200" height="2000"}
2. **Crie uma categoria de receita.** Clique em **Nova categoria** e preencha\:Clique em **Salvar**.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/004-financial-categories-detail.png" alt caption width="3200" height="2000"}
   - **Código**: o código gerencial hierárquico, ex.: 1.01.
   - **Nome**: Receita de Vendas.
   - **Tipo**: escolha **Receita**.
   - **Natureza contábil (opcional)**: deixe em branco no começo — é usada só quando você quiser amarrar a categoria a uma natureza específica do plano contábil.
   - **Bucket DRE**: **Receita** (a linha do DRE gerencial onde a categoria entra).
3. **Crie uma categoria de despesa** do mesmo jeito: nome Despesa com Fornecedores, **Tipo** = **Despesa**, **Bucket DRE** conforme a linha de despesa desejada. Repita para as despesas típicas do seu negócio (aluguel, salários, serviços).
4. **Ative ou inative uma categoria** pelo botão **Ativar/Inativar** no topo da ficha da categoria. Uma categoria inativa some das listas de seleção da nota de compra/venda, mas continua nos títulos antigos que já a usavam.

### Centros de custo e centros de resultado

O *centro de custo* responde "de qual área saiu esse gasto?" e o *centro de resultado* responde "qual unidade gerou essa receita?". Os dois são cadastrados na **mesma tela**, distinguidos pelo campo **Tipo**. Eles permitem ratear despesas e receitas por área nos documentos financeiros.

1. **Abra "Centros de custo".** No menu **Financeiro → Centros de custo**. A lista mostra os centros já cadastrados, com o código, o nome e a classificação.
2. **Crie um centro de custo.** Clique em **Novo centro de custo** e preencha\:Clique em **Salvar**. Repita para os centros de custo típicos: TI — Tecnologia da informação, MKT — Marketing.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/01-cost-center-empty.png" alt caption width="3200" height="2000"}
   - **Código**: o segmento do nível, ex.: ADM (ou um número). O sistema monta a hierarquia a partir do centro-pai.
   - **Nome**: Administrativo.
   - **Tipo**: **Centro de custo** (áreas de gasto sem receita direta).
   - **Classificação**: **Analítico** para os que efetivamente recebem lançamento e rateio; **Sintético** para os que só agrupam filhos. *Somente centros analíticos recebem rateio.*
   - **Centro-pai**: **Nenhum (raiz)** para o topo, ou selecione o centro superior.
3. **Crie um centro de resultado** na mesma tela, mudando o **Tipo** para **Centro de resultado** — são as unidades de negócio que geram receita própria. Exemplos: MTZ — Matriz SP, FIL — Filial RJ, ONL — Loja online.

:::BlockQuote
Se você clicar em **Salvar** com o código ou o nome em branco, a tela acusa o erro no próprio campo e não grava. Preencha os obrigatórios e salve de novo.
:::

### Contas bancárias

A *conta bancária* é o registro **único** de cada conta operacional da empresa. Você cadastra a conta uma vez e ela é reaproveitada em movimentação de caixa, geração de remessa *CNAB* e conciliação bancária — nunca se redigita banco/agência/conta.

1. **Abra "Contas bancárias".** No menu **Financeiro → Contas bancárias**. A lista traz as contas cadastradas com **Nome**, **Banco**, **Agência**, **Conta** e a coluna **Operacional** (mostra **Sim** quando a conta já foi habilitada para tesouraria). O campo **Buscar** filtra por nome, banco ou conta.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/021-bank-accounts.png" alt caption width="3200" height="2000"}
2. **Cadastre uma conta nova.** Clique em **Nova conta** e preencha\:Clique em **Salvar**. A conta passa a aparecer na lista.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/13-bank-account-empty.png" alt caption width="3200" height="2000"}
   - **Nome**: um apelido reconhecível, ex.: Conta ACME Itaú. **Obrigatório** — o sistema rejeita a conta se o nome ficar em branco.
   - **Banco**: selecione na lista FEBRABAN de 3 dígitos, ex.: 341 — Itaú Unibanco.
   - **Agência**: 0001.
   - **Número da conta**: 12345.
   - **Dígito**: 6.
3. **Torne a conta operacional (opcional).** Ao abrir a ficha da conta, o botão **Tornar operacional** habilita saldo inicial, carteira CNAB e sequência de remessa. Só contas operacionais entram em movimentações de caixa, conciliação e geração de remessa — por isso a coluna **Operacional** da lista mostra **Sim**.
4. **Entenda o reaproveitamento da conta.** A mesma conta cadastrada aqui é **referenciada** nos demais cadastros, sem redigitação\:Os documentos emitidos (pagamentos, remessas) **congelam** a identificação da conta no momento da emissão, de modo que uma edição posterior no cadastro não reescreve o histórico financeiro.
   - No sub-cadastro do estabelecimento (**Cadastros → Empresa → aba Bancos**), você **vincula** uma dessas contas ao estabelecimento escolhendo a **finalidade** (Fiscal, Cobrança ou Pagamento) e, se quiser, marcando-a como **Padrão** daquela finalidade. A mesma conta pode servir a mais de uma finalidade.
   - Cada linha da aba Bancos mostra a conta, o selo da finalidade e, quando for o caso, o selo **Padrão**, além dos botões **Definir padrão**, **Histórico de alterações** e **Remover**.
   - Se ainda não houver conta cadastrada, a aba oferece um link direto para cadastrá-la primeiro.

### Condições de pagamento

A condição de pagamento define **em quantas parcelas e em quantos dias** um título é cobrado ou pago — à vista, 30 dias, 30/60/90, entrada + saldo. É usada tanto nas tabelas de preço de vendas quanto ao lançar contas. Por isso ela fica no menu **Cadastros**, não no **Financeiro**.

1. **Abra "Condições de pagamento".** No menu **Cadastros → Condições de pagamento**. A lista mostra cada condição com o código, o nome e o resumo das parcelas (ex.: 30d/50% · 60d/50%).:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/019-payment-conditions.png" alt caption width="3200" height="2000"}
2. **Crie uma condição.** Clique em **Nova condição de pagamento** e preencha\:Clique em **Salvar alterações**. Exemplos típicos\::inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/008-payment-conditions-detail.png" alt caption width="3200" height="2000"}
   - **Código**: AVISTA (ou o código do seu padrão).
   - **Nome**: À vista.
   - **Descrição**: um texto curto de apoio, ex.: Pagamento único no ato.
   - **Parcelas**: para "à vista", uma parcela com **Dias** 0 e **%** 100. Para uma condição parcelada, use **+ Adicionar parcela** e distribua os percentuais — o total precisa fechar **100%** (o indicador ao lado mostra a soma corrente).
   - **À vista** — 1 parcela (0 dias, 100%).
   - **30 dias** — 1 parcela (30 dias, 100%).
   - **30/60** — 2 parcelas (30 dias 50% + 60 dias 50%).
   - **Entrada + 30** — 2 parcelas (0 dias 50% + 30 dias 50%).

### Meios de pagamento

O meio de pagamento é a **forma concreta** com que o dinheiro entra ou sai — boleto, *PIX*, transferência, cartão, dinheiro. Cada meio pode apontar para uma conta bancária de liquidação, o que amarra o recebimento/pagamento à conta certa.

1. **Abra "Meios de pagamento".** No menu **Financeiro → Meios de pagamento**. A lista mostra os meios já cadastrados.
2. **Cadastre um meio de pagamento.** Clique em novo meio e preencha\:Clique em **Salvar alterações**.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/009-payment-instruments-detail.png" alt caption width="3200" height="2000"}
   - **Nome**: um rótulo reconhecível, ex.: Transferência ACME Itaú.
   - **Forma**: escolha na lista a categoria da forma, ex.: **Transferência / PIX** (também há boleto, cartão, dinheiro).
   - **Conta bancária**: selecione a conta de liquidação, ex.: Conta ACME Itaú. Deixe em **Sem conta** quando o meio não estiver amarrado a uma conta específica.

## Verificação

***

Você sabe que funcionou quando:

- A lista de **Categorias financeiras** tem ao menos uma categoria de **Receita** e uma de **Despesa**, e ambas aparecem como opção ao lançar a nota de compra/venda (próxima página).
- Na lista de **Centros de custo**, existe pelo menos um centro de custo e um centro de resultado, e você consegue selecioná-los ao ratear um documento financeiro ou um pedido de venda.
- A lista de **Contas bancárias** mostra a conta ACME com o banco, a agência e a conta corretos; quando você a torna operacional, a coluna **Operacional** exibe **Sim**.
- Na aba **Bancos** do estabelecimento, a conta vinculada aparece com o selo da **finalidade** (Fiscal, Cobrança ou Pagamento) e, quando for o caso, o selo **Padrão** — além dos botões **Definir padrão**, **Histórico de alterações** e **Remover**.
- O botão **Histórico de alterações** de cada vínculo abre o detalhe de auditoria (quem vinculou/alterou/removeu, com data e antes/depois).
- A lista de **Condições de pagamento** mostra cada condição com o resumo de parcelas, e o total das parcelas fecha **100%** ao salvar.
- A lista de **Meios de pagamento** cobre as formas reais que você usa (boleto, PIX, transferência, cartão), com a conta de liquidação correta quando aplicável.

## Erros comuns

***

- **A soma das parcelas não fecha 100%** — o formulário de condição de pagamento não deixa salvar enquanto o total dos percentuais das parcelas não chega a 100%. Ajuste os percentuais até o indicador mostrar 100%.
- **"Código obrigatório" / "Nome obrigatório"** ao salvar categoria ou centro de custo — significa que um campo obrigatório ficou em branco. O erro aparece no próprio campo; preencha e salve de novo.
- **Código de categoria duplicado** — o sistema bloqueia com a mensagem no campo **Código** e mantém o resto do formulário preenchido. Escolha um código ainda não usado.
- **Tipo de categoria inválido** — o **Tipo** só aceita **Receita** ou **Despesa**; qualquer outro valor é rejeitado no ato do salvamento.
- **A categoria/centro não aparece na nota** — verifique se o cadastro está **ativo**. Um registro inativado some das listas de seleção, embora continue nos títulos antigos.
- **Não consigo abrir Categorias/Contas/Centros** — esses três cadastros exigem a permissão de gestão do catálogo financeiro. Se o item nem aparece no menu, peça ao administrador o acesso correspondente.

## Veja também

***

- [Glossário](docId\:iE0pyHH-ovGyrIUgMb7Gs): *Plano de contas*, *Centro de custo*, *Centro de resultado*, *Conta bancária*, *PIX*, *Boleto*, *CNAB*, *DRE*.
- [Financeiro — títulos (contas a pagar e a receber)](docId\:D4kuGidayU2GQ-hMhF_T-): próximo — lançar contas a pagar e a receber usando estas estruturas.
- [Contabilidade](docId:08cbTyrT0WXBp4ymvrog_): o plano de contas contábil e os lançamentos que se apoiam nas categorias e centros cadastrados aqui.

[title] Financeiro
[path] Aplicações/Agility/


[title] Cargos e salários
[path] Aplicações/ERP/Manual do Usuário/

Promoção acontece de dois jeitos, e o sistema trata os dois de forma diferente porque eles **são** diferentes.

A **horizontal** move a pessoa dentro do mesmo cargo, de um nível para outro: mesma cadeira, mais senioridade e salário. A **vertical** muda a cadeira — a pessoa passa a ocupar outro cargo.

Hoje as duas acontecem por conversa entre o gestor e o RH, e o registro que sobra é o salário novo na folha. Quem pergunta "por que esta pessoa foi promovida em março?" seis meses depois não encontra resposta. É essa resposta que a tela existe para guardar.

## Catálogo de certificações

***

**Menu:** Catálogo de certificações · **Rota:** /certifications

Aqui ficam as **credenciais que a organização reconhece** — CNH, registro em conselho, curso obrigatório —, com quem emite e **por quanto tempo valem**.

### Por que este cadastro existe

Antes dele, a mesma credencial era **texto** em dois lugares: no que o posto exige e no que o curso concede. Escrever *"CNH D"* de um lado e *"CNH categoria D"* do outro fazia a ligação sumir **em silêncio** — sem erro, sem aviso, e a pessoa simplesmente deixava de constar como certificada.

E havia um efeito pior: como a trilha não dizia **qual** certificação concede, o certificado saía **sem validade** — e sem validade não existe recertificação. Quem se certificou num treinamento cuja credencial vale dois anos continuava, para o sistema, certificado para sempre.

### Cadastrar

1. Abra **Catálogo de certificações** e clique em **Cadastrar certificação**.
2. Informe o **nome** e, se souber, **quem emite**.
3. Informe **por quantos meses vale**. Deixe **vazio** se a credencial não expira.
4. Salve.

### Armadilhas

**Validade vazia é uma resposta, não cadastro pela metade.** Muita credencial não expira, e é o registro correto para elas. O que o sistema nunca faz é inventar uma data — validade é **agida**: alguém é afastado de uma tarefa por causa dela.

**O posto pode APERTAR o prazo, nunca afrouxar.** Se a organização recertifica o motorista a cada dois anos embora a habilitação dure cinco, informe **24** na exigência do posto — e é esse prazo que vale. O contrário não: cargo não decide que uma credencial dura mais do que quem a emite diz.

**Zero não é "não expira".** Zero seria um certificado vencido no dia em que foi emitido, e o sistema recusa.

**Não existe apagar, só aposentar.** Um certificado emitido ano passado aponta para esta linha; apagá-la deixaria alguém apoiado em nada.

**Nome repetido é recusado, ignorando maiúsculas.** Duas linhas com o mesmo nome trariam de volta, por dentro, a ambiguidade que este catálogo existe para eliminar.

### Histórico

Cada certificação tem **Histórico desta certificação**, com o antes e o depois. É onde se responde *quem mudou a validade desta credencial, e quando* — pergunta que aparece exatamente quando alguém descobre ter trabalhado com credencial vencida.

## Solicitar uma promoção

***

1. **Abra "Promoções".** Menu **Recursos humanos → Promoções**.
2. **Informe quem, o tipo, o destino e a partir de quando.** Em promoção **vertical** o destino é o **cargo**; em **horizontal**, o **nível** dentro do cargo atual. A data é o dia em que a promoção passa a valer — pode ser no futuro, e normalmente é.
3. **A justificativa não é opcional.** É ela que responde à pergunta lá na frente, e é o primeiro campo que uma auditoria lê.
4. **Por que não bloqueia.** Enquadramento fora da faixa acontece — reposicionamento de mercado, decisão judicial. Bloquear levaria alguém a alargar a própria faixa só para conseguir salvar, e aí o fato que valia registrar é justamente o que se perde.
   **Salário fora da faixa do cargo de destino é permitido**, e o sistema pede uma justificativa específica para isso em vez de recusar.
5. **"Enviar para aprovação"** manda a solicitação para quem tem alçada, na mesma caixa de aprovação que a organização já usa para compras e pedidos. **Aprovar a própria solicitação é recusado lá.**

## Efetivar

***

1. **E vale na data de efeito, não no dia da aprovação.** Uma promoção decidida em março para valer em abril deixa as permissões da pessoa como estão até abril.
   **Promoção vertical muda o que a pessoa pode fazer no sistema.** O acesso é governado pelo cargo que ela ocupa, então mudar de cargo move as permissões junto. A tela avisa **antes** de você confirmar. Isso é esperado, não é defeito — mas é o tipo de consequência que ninguém pode descobrir depois.
   **Com a solicitação aprovada, use "Efetivar a promoção".**
2. **O vínculo anterior é encerrado na véspera e um novo começa.** O cargo antigo **não** é sobrescrito: qual cargo a pessoa ocupou e quando fica consultável para sempre. É disso que o ERM do colaborador vive.
3. **Editar uma solicitação já aprovada devolve ela a rascunho.** O que foi autorizado não é o que está sendo pedido agora, e a aprovação anterior não vale para o conteúdo novo — mande de novo.
4. **Solicitação efetivada não volta atrás.** Promoção que aconteceu é fato do histórico da pessoa, e retirá-la deixaria o vínculo que ela abriu sem nada explicando.

## Reajustar salários

***

Em **Pessoas → Reajustes salariais** você registra um reajuste de uma pessoa ou de um grupo. A tela existe para o reajuste **coletivo** deixar de ser uma regra que ninguém confere: cinco por cento para um departamento é uma frase, e a prévia transforma essa frase nas pessoas que ela alcança.

1. Clique em **Novo reajuste** e diga o que ele **alcança** — *uma pessoa* ou *um grupo*. No grupo, escolha se é por **departamento** ou por **posto**.
2. Informe o **motivo** (mérito, acordo coletivo, piso legal, equidade ou outro), a **forma** (percentual, valor somado ou salário-alvo), o **valor** e a data **a partir de** quando ele vale.
3. Clique em **Calcular a prévia**. O sistema resolve quem é alcançado **na data de efeito** — não hoje — e mostra, pessoa por pessoa, quanto ela recebe hoje e quanto passaria a receber.
4. **Enviar para aprovação.** Reajuste coletivo sem prévia não é aceito aqui: quem aprova precisa ver as pessoas, não a regra.
5. Aprovado, clique em **Efetivar**. O que vai para o salário é **exatamente a lista da prévia** — o sistema não recalcula na efetivação.

## O que a prévia está te dizendo

***

**"Fora da faixa"** — o novo valor cai fora da faixa salarial do posto. Isso é **permitido**: um órgão pode decidir pagar acima do plano. O que o sistema não deixa é fazer isso **sem dizer por quê**, então preencha a justificativa antes de efetivar.

**"Não guardado aqui"** — o ERP não guarda o salário daquela pessoa. Acontece com vínculo que ainda está em folha externa. Ela **continua aparecendo na lista**, e é de propósito: sumir com ela faria o reajuste coletivo relatar sucesso tendo pulado gente.

**A coluna "Efetivação"** só é preenchida depois que você efetiva, e é **por pessoa**. "No salário" quer dizer que o novo valor entrou no vínculo. "Sem vínculo aqui", "Dois vínculos correndo" e "Folha recusou" são os três casos em que não havia onde escrever — e ver isso por linha é o que permite tratar as exceções sem desfazer o resto.

## Registrar uma pesquisa salarial

***

Em **Pessoas → Pesquisas salariais** você guarda quanto o mercado paga. A tela existe para revisar faixa deixar de ser discussão entre pessoas que leram pesquisas diferentes.

1. Clique em **Nova pesquisa** e informe o nome, a **fonte** e a **data-base**. As duas últimas são obrigatórias: valor sem fonte não se confere depois, e valor sem data-base não significa nada daqui a um ano — que é justamente quando alguém confere.
2. Abra a pesquisa e acrescente os **cargos de mercado**, um a um, com os percentis que a pesquisa publicou. **Deixe em branco o que ela não publicou** — o sistema recusa zero de propósito, porque zero não é o que "não publicado" quer dizer.
3. O campo **Nosso posto** é **opcional**. Cargo de mercado sem equivalente aqui continua na lista, marcado como *Sem de-para*, e é de propósito: são justamente essas linhas que contam que o mercado tem um cargo em que ninguém pensou.
4. A tabela mostra a **mediana do mercado ao lado da nossa faixa**, e a última coluna diz onde estamos — *Nosso teto está abaixo do mercado*, *Dentro do mercado* ou *Nosso piso está acima do mercado*.

## A faixa comparada é a daquela data

***

A nossa faixa é lida **como estava na data-base da pesquisa**, não como está hoje. Comparar uma pesquisa de 2024 com a faixa de 2026 mostraria como diferença de mercado o que é só passagem do tempo — e alguém revisaria a faixa por causa disso.

Por isso duas pesquisas do mesmo cargo, com datas-base diferentes, são coisas distintas na tela: cada uma traz a sua data e a sua fonte.

## Montar um modelo de dossiê (ERM)

***

O **ERM** é o dossiê consolidado de uma pessoa: numa página só, o que hoje se lê abrindo seis telas — dados cadastrais, por quais postos ela passou, o que se movimentou na carreira dela, o que o cargo exige de competência e de certificação, e o resultado das avaliações de desempenho.

Antes de emitir, alguém define **o que o documento mostra**. É isso que o modelo é: a lista de blocos e a ordem deles. Uma conversa de carreira não pede os mesmos blocos que uma auditoria.

1. **Abra "Modelos de dossiê"** (/erm/templates). No menu lateral, em **Recursos humanos → Modelos de dossiê**.
2. **No quadro "Novo modelo", preencha "Modelo"** com um nome que diga a ocasião — *Conversa de carreira*, *Auditoria de pessoal*, *Movimentação interna*. É por esse nome que quem emite escolhe depois. Deixe **"Situação"** em **Em uso**.
3. **Acrescente os blocos.** À direita, em **"Blocos que você pode acrescentar"**, clique em cada um que o documento deve trazer; ele passa para a lista **"Blocos que este modelo exibe"**, à esquerda, numerada. Um bloco já escolhido fica desabilitado do outro lado — o mesmo bloco duas vezes imprimiria duas vezes, e a segunda leria como um segundo conjunto de fatos.
4. **Ordene com as setas "Subir" e "Descer".** **A ordem faz parte do modelo**: o documento imprime os blocos exatamente como estão listados aqui, na tela e no arquivo. O **X** retira um bloco.
5. **Clique em "Gravar o modelo".** Modelo **sem nome ou sem nenhum bloco não é gravado** — o botão fica desabilitado, e o quadro da esquerda explica por quê.
6. **Para tirar um modelo de circulação, abra-o pela lista, mude "Situação" para "Aposentado"** e clique em **"Salvar o modelo"**. **Não há exclusão**, e é de propósito: dossiês já emitidos continuam em mãos alheias e não trazem escrito de qual modelo vieram — apagado o modelo, ninguém explicaria o documento que o leitor tem na frente. O aposentado continua na lista desta tela e some da escolha de quem emite.
7. **O quadro "Histórico deste modelo" guarda cada alteração.** Quem incluiu ou tirou um bloco, quando, e o que o modelo mostrava antes — é o que responde "por que o dossiê do ano passado não tinha essa parte?".

:::BlockQuote
**Um bloco pode aparecer como não oferecido.** É o caso de **Treinamento**, embaixo de **"Não oferecidos — não há de onde ler"**: o sistema ainda não registra treinamento realizado em lugar nenhum, então nenhum dossiê tem como responder por ele. Ele é **mostrado desabilitado, e não escondido**, de propósito — e o aviso diz que a informação não existe no sistema, que é diferente de afirmar que a pessoa não fez treinamento.
:::

## Emitir o dossiê de um colaborador

***

1. **Abra "Dossiê do colaborador"** (/erm). No menu lateral, em **Recursos humanos → Dossiê do colaborador**.
2. **No quadro "Emitir um dossiê", escolha o "Colaborador" e o "Modelo".** Assim que os dois estiverem escolhidos, o documento se monta no quadro **"O dossiê"**, logo abaixo, bloco a bloco na ordem do modelo. **Só modelos em uso** são oferecidos aqui.
3. **Clique em "Exportar PDF"** para guardar o arquivo. Ele traz **os mesmos blocos, na mesma ordem e nos mesmos estados** da tela — o arquivo não vai buscar nada por conta própria, então tela e arquivo nunca discordam. O PDF sai sempre em português, mesmo que você esteja usando o sistema em outro idioma.
4. **Nada aqui altera nada.** O dossiê só lê. Se um dado está errado, corrija na tela de origem — a promoção em **Promoções**, o reajuste em **Reajustes salariais**, o dado cadastral na ficha da pessoa — e a próxima emissão já sai certa.
5. **A emissão fica registrada no histórico da pessoa**, e a exportação também, como dois fatos separados. Quem emitiu o dossiê de quem, e quando, é pergunta que uma auditoria faz.

## Como ler cada bloco do dossiê

***

Cada bloco traz uma etiqueta com o seu estado, e separar os dois últimos é o ponto todo:

- **"Com registro"** — há informação, e ela está ali.
- **"Sem registro"** — o bloco foi pedido, o sistema procurou e não havia nada. A pessoa nunca foi promovida, por exemplo. Aparece como uma nota discreta.
- **"Retido"** — há informação, e quem emitiu não tem a alçada que a abre. Aparece num painel destacado, com cadeado, e **diz qual alçada falta**. Ele não some e não vira "sem registro": quem recebe o documento precisa sair sabendo que ele está incompleto, e afirmar que não há registro quando há, e está protegido, é informar ao leitor o contrário do que é verdade.

Ao pé do documento há um lembrete que vale ler junto: **o dossiê cobre apenas os blocos listados**. Assunto que não aparece é assunto que aquele modelo não habilitou — nunca uma afirmação de que a pessoa não tem.

E o que cada bloco entrega:

- **Postos ocupados** — por quais postos a pessoa passou e desde quando, com o **vínculo numerado** (1, 2, …) quando há mais de um correndo. O número é do documento, para você ler duas passagens paralelas sem confundi-las; ele não é código de contrato nem matrícula. Lotação anterior ao controle de vínculos aparece com traço, em vez de ser encaixada no vínculo errado.
- **Movimentações** — promoções e reajustes **que aconteceram**, em ordem de data de efeito. Pedido em rascunho, aguardando aprovação ou recusado **não entra**: o dossiê relata fato, não intenção. **Não há valor em reais** — o documento diz que houve reajuste, por qual motivo e a partir de quando; quanto a pessoa recebe é outra tela e outra permissão.
- **Competências exigidas pelo cargo** e **Certificações exigidas pelo cargo** — o nome é literal: é o que o **posto exige**, e não o que a pessoa alcançou nem os certificados que ela detém. Nível atingido em competência é resultado de avaliação e sai no bloco de desempenho.
- **Desempenho** — pode sair **retido mesmo para quem trabalha no RH**, e nesse caso a mensagem **não nomeia alçada nenhuma**: resultado individual de avaliação é liberado à própria pessoa e ao gestor que o ciclo convidou como avaliador. Não há permissão a pedir — procurar um administrador seria perder a viagem.

## Erros comuns

***

**"O sistema não aceita a pesquisa."** Falta a fonte ou a data-base. São as duas colunas que fazem a pesquisa valer alguma coisa numa revisão de faixa, e por isso são as duas que o sistema cobra.

**"O cargo aparece sem comparação."** Ou ele não tem de-para com um posto nosso (*Sem de-para*), ou o posto não tinha faixa vigente na data-base (*Sem faixa naquela data*). São coisas diferentes e a coluna diz qual é: a primeira se resolve no de-para, a segunda na tela de faixas salariais.

**"Editei o reajuste e ele voltou para rascunho."** É o desenho. A aprovação foi dada para uma lista; mudar os termos faz outra lista. A prévia é apagada junto, porque prévia dos termos antigos é pior que prévia nenhuma — ela parece um resultado conferido.

**"A prévia não recalcula."** Depois de enviada para aprovação, a lista não muda mais. Se precisa mudar, cancele ou edite: aí ela volta a rascunho e a prévia pode ser calculada de novo.

**"Não consigo efetivar."** Falta a aprovação de quem tem alçada. O sistema pergunta à caixa de aprovação, e não ao estado que a tela mostra — se a solicitação foi editada depois de aprovada, ela voltou a rascunho e precisa ser enviada de novo.

**"O sistema não deixa promover esta pessoa."** Ela não tem vínculo vigente na data de efeito. Não há de onde promover: primeiro o cadastro trabalhista, depois a promoção.

**"Promovi e as permissões não mudaram."** Confira a data de efeito. A alçada muda **nela**, não no dia em que você clicou.

**"O sistema nega o dossiê desta pessoa."** Ela está fora da sua alçada — quem responde por uma unidade emite o dossiê de quem está sob ela, e o RH central emite o de qualquer um. A recusa é a mesma quer a pessoa exista ou não: se dissesse "essa pessoa não existe" só nos casos em que não existe, quem ficasse tentando descobriria pelo silêncio quem existe. E o que aparece é **a recusa**, não um dossiê vazio.

**"O bloco de desempenho saiu retido e eu sou do RH."** É o desenho. Resultado individual de avaliação é liberado pelo **convite do ciclo**, não pelo cargo de quem consulta. Repare que a mensagem não manda pedir alçada a ninguém: consulte pela tela de avaliação de desempenho, ou fale com quem conduziu o ciclo.

**"O dossiê não mostra quanto a pessoa ganha."** Também é o desenho. O bloco de movimentações traz as **decisões** — que houve promoção, que houve reajuste, o motivo e a data. Valor em reais está no contrato de trabalho e na folha, atrás de permissão própria; trazê-lo para cá transformaria o dossiê num extrato de pagamento e mudaria quem pode emiti-lo.

**"O bloco de treinamento aparece apagado e não deixa marcar."** É o único que não tem de onde ler: o sistema ainda não registra treinamento realizado. Ele fica visível e desabilitado para o autor do modelo enxergar que o assunto existe e ainda não é acompanhado — e é isso que impede um dossiê de afirmar "esta pessoa não fez treinamento" quando o verdadeiro é "o sistema não sabe".

**"O dossiê traz certificação diferente da que a pessoa tem."** Não traz nenhuma das que ela detém: o bloco se chama *Certificações exigidas pelo cargo* e é isso que ele lista. Os documentos da pessoa e as validades deles ficam no cadastro trabalhista.

**"O documento não abriu e apareceu um aviso vermelho."** Leia o aviso: ele diz que a resposta veio num formato que a tela não sabe ler. **Não é dossiê vazio.** Recarregue e, se persistir, avise o suporte — um bloco em branco seria lido como resposta, e por isso a tela prefere não desenhar nada.


[title] APIs REST, Swagger e Integrações no CITSmart
[path] Aplicações/

O CITSmart disponibiliza um conjunto completo de APIs RESTful que permite a integração com sistemas externos, automação de processos e extensão das funcionalidades da plataforma. Baseadas no padrão REST (Representational State Transfer), essas APIs seguem boas práticas de mercado para garantir escalabilidade, interoperabilidade e facilidade de uso.

Todas as requisições passam por um API Gateway centralizado, que permite o gerenciamento, monitoramento e proteção das APIs. Esse gateway atua como um ponto único de controle, oferecendo recursos de segurança, controle de acesso, registro de logs e limitação de tráfego, garantindo maior governança e confiabilidade nas integrações realizadas com o CITSmart.

Para apoiar desenvolvedores e equipes de integração, a plataforma oferece documentação detalhada e interativa por meio do Swagger, incluindo a descrição de cada endpoint, parâmetros de entrada e saída, tipos de dados e exemplos de código para facilitar a implementação de integrações personalizadas. Essa documentação é apresentada em conformidade com os padrões abertos do mercado, promovendo agilidade e segurança no desenvolvimento.

# Acesso à documentação via Swagger:

APIs de Low-Code (objetos de negócio, entidades personalizadas):
https\://\<Base URL>/lowcode/swagger-ui.html#/

APIs de Processos e Módulos da Plataforma (ITSM, ESM etc.):
https\://\<Base URL>/citsmart/webmvc/swagger-ui.html#/

:::hint{type="info"}
**Observação:** Para visualizar o conteúdo das APIs e executar testes diretamente pela interface Swagger, é necessário estar autenticado no sistema com um usuário válido. O conteúdo e as permissões exibidas são controlados com base no perfil de acesso do usuário, respeitando as regras de segurança definidas na plataforma.
:::

Além disso, as APIs do CITSmart contam com controles de autorização granulares, garantindo que apenas usuários devidamente autorizados possam acessar, consultar ou modificar dados sensíveis, conforme os níveis de permissão definidos no sistema de controle de acesso.

***

# API Pesquisa de Tickets

Quando uma pesquisa é realizada **sem informar um período de criação e sem especificar o número do ticket**, o sistema aplica automaticamente um intervalo de datas para a consulta.

Nessa situação, os filtros são preenchidos da seguinte forma:

- **Data inicial de criação:** 90 dias antes da data atual.
- **Data final de criação:** data atual.

Esse comportamento é aplicado automaticamente para tornar a consulta mais eficiente em bases de dados com grande volume de informações.

:::hint{type="info"}
**Exemplo**: Se a pesquisa for executada sem preencher o período de criação e sem informar o número do ticket, o sistema pesquisará automaticamente os tickets criados nos últimos 90 dias.
:::

**Importante:** Para consultar tickets fora do período padrão, basta informar manualmente as datas de criação desejadas ou pesquisar diretamente pelo número do ticket.

[title] Cronograma Gantt, marcos e dependências (Tradicional)
[path] Aplicações/Agility/Sprints e cronograma/

:::BlockQuote
Leia o cronograma derivado da WBS, acompanhe marcos e caminho crítico, consulte dependências e compare o plano atual com uma linha de base aprovada.
:::

:::hint{type="info"}
**Pré-requisito:**

O Projeto precisa usar a forma de trabalho Tradicional e ter itens na WBS com datas, progresso e, quando aplicável, predecessoras. O roteiro usa o Projeto ERP Financeiro do Workspace Portal de Serviços.
:::

***

O Gantt do Projeto transforma a WBS em uma linha do tempo: cada item recebe uma barra entre sua data de início e fim, respeitando a hierarquia, o status, o responsável e as dependências. A tela também calcula o caminho crítico e diferencia atividades concluídas, em andamento, críticas e planejadas. Um marco é desenhado como um ponto e representa uma data de entrega, não uma atividade com duração.

As páginas Marcos e Dependências são leituras especializadas do mesmo cronograma. Marcos filtra itens marcados como marco e mostra data, status, responsável e indicadores; Dependências apresenta a direção predecessora → sucessora, os dois períodos, o status da sucessora e se a aresta é crítica nos dois extremos. A criação e edição dessas relações acontece na WBS, no item sucessor.

Uma baseline é um snapshot imutável do plano publicado. Ela captura escopo, prazo, marcos, orçamento e quantidade de atividades do caminho crítico, além do retrato de cada item. Comparar a baseline com o plano atual torna visíveis alterações de escopo, datas, progresso, orçamento e caminho crítico sem apagar o histórico aprovado.

***

### Passo a passo

::::WorkflowBlock
:::WorkflowBlockItem
**Conferir a WBS de origem**

No ERP Financeiro, abra "WBS" antes de interpretar o Gantt. A tela mostra 7 itens e o período de 03 ago a 18 dez, incluindo Descoberta, Requisitos fiscais, Implementação, Contabilidade, Tesouraria, Implantação e o marco Go-live. Ela também informa 1 marco, orçamento de R$ 2.550.000,00 e 4 atividades no caminho crítico.
:::

:::WorkflowBlockItem
**Abrir o Gantt do Projeto**

Clique em "Gantt do Projeto". Os cartões superiores resumem Período planejado, Atividades e marcos e Caminho crítico. A seção Cronograma da WBS usa a mesma hierarquia da WBS, apresenta a legenda Concluído, Em andamento, Caminho crítico e Planejado e posiciona as barras no calendário mensal.
:::

:::WorkflowBlockItem
**Ler a hierarquia e as barras**

Use os códigos 1, 1.1, 2, 2.1 e assim por diante para distinguir entregas-pai e atividades-filhas. A indentação da linha indica a profundidade na WBS; a barra mostra a duração e exibe o responsável quando há responsável. A cor deriva do estado: concluído, em andamento, crítico ou planejado. Uma linha crítica permanece destacada mesmo que seu progresso ainda esteja parcial.
:::

:::WorkflowBlockItem
**Selecionar uma atividade para seus detalhes**

Clique no nome ou na barra de uma linha. O painel de detalhes mostra código, título, descrição, responsável, período, progresso, status e as predecessoras por código. Em um item de marco, aparece também o indicador Marco; em um item crítico, o indicador Caminho crítico. Isso permite passar do panorama para a causa de uma data sem sair do Gantt.
:::

:::WorkflowBlockItem
**Interpretar dependências no Gantt**

Na tabela Dependências sob o gráfico, leia cada sucessora e a lista "Depende de". No exemplo, Contabilidade (2.1) depende de Requisitos fiscais (1.1), Tesouraria (2.2) depende de Contabilidade e Go-live (3.1) depende de Tesouraria. A caixa Caminho crítico exibe a sequência 1.1 → 2.1 → 2.2 → 3.1; um atraso em qualquer trecho pode alterar a data final prevista.
:::

:::WorkflowBlockItem
**Consultar a página Marcos**

Abra "Marcos" para uma lista sem atividades regulares. Os cartões mostram quantidade total, concluídos e quantos estão no caminho crítico. Use o filtro all, open, completed ou critical e a busca por texto para encontrar um marco; a tabela apresenta código, título, data, status, responsável e indicadores. O botão "Ver na WBS" retorna ao item de origem.
:::

:::WorkflowBlockItem
**Criar ou alterar um marco na WBS**

Na página Marcos, clique em "Gerenciar na WBS" para voltar à estrutura analítica. Edite o item sucessor/entrega na WBS e marque-o como marco, informe sua data e ajuste responsável, status ou progresso conforme o plano. A página de Marcos não mistura cadastro paralelo: ela sempre deriva dos itens que a WBS marcou como marco.
:::

:::WorkflowBlockItem
**Consultar as relações do cronograma**

Abra "Dependências". Os indicadores Relações no cronograma, Sucessoras em andamento e Arestas críticas nos dois extremos quantificam o grafo. Para cada relação, confira datas da predecessora e da sucessora, status/progresso da sucessora e o selo Crítico nos dois extremos quando aplicável.
:::

:::WorkflowBlockItem
**Editar uma dependência na WBS**

Na tela Dependências, clique em "Editar dependências na WBS". No item sucessor, escolha as predecessoras válidas, salve e aguarde a recarga do recurso. A direção é preservada: a predecessora precisa estar disponível antes da sucessora. Volte ao Gantt para conferir as novas datas, o quadro de dependências e o caminho crítico recalculado.
:::

:::WorkflowBlockItem
**Comparar a baseline mais recente**

Abra "Baselines". A tabela de Controle de baselines compara a referência (por exemplo, Baseline v3) com o Plano atual em cinco dimensões: Escopo, Prazo, Marcos, Orçamento e Caminho crítico. Cada linha recebe a situação Alterado ou Inalterado. Abaixo, Mudanças desde a referência lista itens adicionados e alterados com o valor antes → agora.
:::

:::WorkflowBlockItem
**Entender o que uma baseline captura**

Considere a baseline como uma fotografia aprovada no instante da publicação: quantidade de itens do escopo, início e fim do cronograma, número de marcos, orçamento e atividades críticas, além dos dados dos itens. No exemplo, a Baseline v3 tinha 6 itens, prazo até 04 dez, nenhum marco e R$ 2.400.000,00; o plano atual tem 7 itens, prazo até 18 dez, 1 marco e R$ 2.550.000,00. A diferença mostra por que uma referência é útil para governança, auditoria e controle de desvios.
:::

:::WorkflowBlockItem
**Publicar uma nova baseline**

Clique em "Comparar e publicar". Revise a comparação expandível e as mudanças de escopo. Digite uma justificativa com pelo menos 10 caracteres (há contador até 1.000 caracteres) e clique em "Publicar". O Agility cria a próxima versão, confirma a publicação e preserva as versões anteriores como histórico imutável; não edite uma baseline já publicada para corrigir o plano, publique uma nova referência.
:::
::::

![](https://itsm-labdev.cloud4biz.com/agility-v2/docs/screens/04-gantt-wbs.webp "Gantt do Projeto ERP Financeiro com sete itens da WBS, barras coloridas, dependências e caminho crítico 1.1, 2.1, 2.2 e 3.1")

:::hint{type="success"}
:FontAwesome[]{icon="fa-solid fa-check"} **Verificação**

- O Gantt exibe período planejado, quantidade de itens e tamanho do caminho crítico coerentes com a WBS.
- As barras preservam a hierarquia da WBS, exibem o responsável quando informado e diferenciam concluído, em andamento, crítico e planejado.
- O marco Go-live aparece separado das atividades regulares, com data, status, responsável e indicador Marco.
- Dependências mostram predecessora → sucessora, períodos dos dois lados, progresso e criticidade; o caminho crítico lista uma sequência ordenada.
- Baselines compara escopo, prazo, marcos, orçamento e caminho crítico e mantém versões anteriores no histórico imutável.
:::

:::hint{type="warning"}
****:FontAwesome[****]{icon="fa-solid fa-triangle-exclamation"}**&#x20;Erros comuns**

**O Gantt está sem atividades**

O gráfico é derivado da WBS. Se não houver itens com datas, a tela mostra uma área vazia informando que o cronograma não está disponível. Crie ou complete os itens na WBS, com início/fim e, quando necessário, predecessoras, e recarregue o Gantt.

**Não há dependências ou caminho crítico**

Sem relações na WBS, Dependências mostra estado vazio e o Gantt não consegue calcular uma sequência crítica. Edite o item sucessor na WBS, escolha a predecessora adequada e salve; evite criar uma relação circular.

**A justificativa da baseline é curta**

Publicar exige uma justificativa com no mínimo 10 caracteres. O diálogo mantém Publicar desabilitado ou exibe validação enquanto o texto não atingir esse limite; descreva a decisão aprovada antes de tentar novamente.
:::


[title] Sistema
[path] Aplicações/Agility/


[title] ChatBots e Supervisores Cognitivos (AURA)
[path] Aplicações/

**ChatBots e Supervisores Cognitivos (AURA)** - é uma plataforma de assistentes virtuais “omnichannel”, com inteligência cognitiva e online que possibilita agilizar o atendimento e operações aos usuários e clientes. Com ele é possível solicitar serviços comuns do dia a dia, como aberturas de chamado e Chat online integrado com os principais canais de mensagerias existentes no mercado, como: “whatsapp”, “telegram”, “slack”, “facebook messenger”, “webchat”, dentre outros. A plataforma também permite realizar a gestão e orquestração de atividades do dia de operadores e demais áreas de negócios com seu motor cognitivo.

[https://docs.citsmart.com/aura](https://docs.citsmart.com/aura)

[title] Criar um projeto e escolher o modelo
[path] Aplicações/Agility/Workspaces e Fundamentos/

:::BlockQuote
Use o assistente de projetos para registrar a identidade, o responsável, o acesso e a forma de trabalho antes de abrir o projeto no Workspace.
:::

:::hint{type="info"}
**Pré-requisito:&#x20;**

Você precisa estar em um Workspace e ter permissão para criar projetos. O assistente usa os membros, Times e ARTs disponíveis nesse Workspace.
:::

***

Um projeto reúne objetivo, responsável, equipe, prazos e a forma de acompanhar a entrega. A lista de Projetos mostra o código, o tipo (Kanban, Scrum, Tradicional ou SAFe), os Times, os ARTs, o status e o progresso; ao abrir uma linha você entra no resumo e no menu específico daquele projeto.

O modelo escolhido não é apenas uma etiqueta. Ele provisiona a navegação que o time usará: Kanban prioriza o Quadro e o fluxo contínuo, Scrum organiza Backlog e Sprints, Tradicional disponibiliza WBS/Gantt e controles de planejamento, e SAFe vincula o projeto a um ART e a um Planning Interval. As áreas compartilhadas — Planejamento, Pessoas, Documentos, Financeiro, Histórico e Configurações — continuam disponíveis quando a capability correspondente existe.

***

### Passo a passo

::::WorkflowBlock
:::WorkflowBlockItem
**Abrir a lista de Projetos**

Na barra lateral do Workspace, selecione "Projetos". A tabela pode ser pesquisada por nome, código, time ou ART e filtrada por tipo, Times, ARTs e status. No Workspace de demonstração "Portal de Serviços" há projetos populados para abrir e comparar sem começar por uma lista vazia.
:::

:::WorkflowBlockItem
**Iniciar o assistente**

Clique em "Novo projeto" no topo da tabela. O diálogo apresenta um passo a passo com Identidade, Template, Time (quando aplicável) e Revisão. A sequência muda quando você escolhe Tradicional: esse modelo não exibe o passo de configuração de Time.
:::

:::WorkflowBlockItem
**Informar a identidade**

No primeiro passo, preencha "Nome", que é obrigatório e identifica o projeto no Workspace. O campo "Código" é sugerido a partir do nome, mas pode ser ajustado; use de 4 a 8 caracteres, apenas letras minúsculas, números e hífen. Um código com formato inválido aparece como erro no próprio campo e impede avançar.
:::

:::WorkflowBlockItem
Use o editor de texto para registrar a "Descrição", por exemplo o objetivo, o contexto e o resultado esperado. Escolha o "Responsável" entre os membros do Workspace; somente essas pessoas podem ser responsáveis. Se não houver membro disponível, o controle fica indisponível e o projeto não pode avançar até haver um responsável válido.
:::

:::WorkflowBlockItem
Defina o "Acesso inicial": "Workspace" permite que qualquer membro veja e participe, enquanto "Time e membros" restringe o acesso ao Time do projeto e às pessoas adicionadas posteriormente em Membros. Se necessário, informe "Início" e "Término"; quando as duas datas são preenchidas, o término não pode ser anterior ao início.
:::

:::WorkflowBlockItem
**Escolher o template**

No passo "Template do projeto", compare os quatro cartões. A ordem visual é Tradicional, Kanban, Scrum e SAFe. Selecione o modelo que corresponde à governança real do trabalho; a escolha define quais abas e capacidades aparecerão depois da criação.
:::

:::WorkflowBlockItem
"Kanban" representa fluxo contínuo por colunas, com limites de trabalho em progresso. O projeto recebe Quadro, Dashboard, Métricas de fluxo e Automações, além das áreas compartilhadas. É a opção indicada quando o trabalho entra e sai continuamente e o time acompanha o cartão pelas lanes.
:::

:::WorkflowBlockItem
"Scrum" representa trabalho iterativo com backlog priorizado e cadência de Sprints. A navegação apresenta Backlog, Planejar Sprint, Sprint ativo (o quadro da sprint) e Relatórios de Sprint, além das áreas compartilhadas. Use esse modelo quando a seleção de itens e o compromisso de cada sprint forem parte do processo.
:::

:::WorkflowBlockItem
"Tradicional" organiza a entrega por estrutura analítica e linha de base. O projeto apresenta WBS, Gantt do Projeto, Marcos, Baselines, Dependências e Riscos, seguido das áreas compartilhadas; não há o passo de provisionar um Time no assistente. Use-o quando o planejamento por entregáveis, dependências e marcos for mais importante que um quadro de fluxo.
:::

:::WorkflowBlockItem
"SAFe" vincula o projeto a um ART (Agile Release Train), à cadência do trem e a um Planning Interval. No passo de Time e ART, escolha um ART existente e um PI disponível, ou selecione a opção para criar um novo ART e informe seu nome. A escolha de SAFe exige também uma configuração de equipe válida; sem ART/PI quando a opção existente está selecionada, o assistente não permite concluir.
:::

:::WorkflowBlockItem
**Configurar Time e participantes**

Para Kanban, Scrum e SAFe, escolha "Usar time existente" e selecione um Time do Workspace, ou escolha criar um novo. Ao criar, informe o nome do Time; ele é sugerido com base no projeto, mas pode ser alterado. Os participantes iniciais podem ser selecionados entre os membros, e o responsável e o usuário que está criando são preservados como integrantes garantidos quando pertencem ao Workspace.
:::

:::WorkflowBlockItem
No caso de SAFe, confira também o ART e o Planning Interval na mesma etapa. O assistente carrega os PIs do ART escolhido e seleciona o PI corrente quando houver um; se nenhum PI estiver disponível, revise o cadastro do ART antes de tentar criar o projeto.
:::

:::WorkflowBlockItem
**Revisar e criar**

Na etapa "Revisão", confira o nome e código, responsável, acesso, template, Time e membros iniciais. Para SAFe, confira ainda o ART e o PI; para Tradicional, confirme que o Time aparece como não provisionado, pois isso é parte do modelo. Se algo estiver errado, volte pelo indicador de etapas, ajuste e avance novamente.
:::

:::WorkflowBlockItem
Clique em "Criar projeto". O Agility provisiona o projeto e os elementos correspondentes ao template; a confirmação mostra o projeto criado e permite abri-lo. Ao abrir, o resumo exibe status, responsável, progresso, forma de trabalho e, quando houver, Time, Board principal e ART. Use o menu lateral para verificar as abas que foram provisionadas.
:::
::::

:::hint{type="success"}
:FontAwesome[]{icon="fa-solid fa-check"} **Verificação**

- O projeto aparece na tabela do Workspace com nome, código, tipo, status e progresso.
- O resumo mostra a forma de trabalho escolhida e o responsável selecionado; projetos com provisionamento correspondente também exibem Time, Board ou ART.
- A navegação muda de acordo com o modelo: Quadro e métricas no Kanban; Backlog e Sprints no Scrum; WBS, Gantt e Baselines no Tradicional; no SAFe, o resumo e o planejamento registram o vínculo com ART e Planning Interval.
- O projeto pode ser aberto a partir da confirmação do assistente ou da tabela de Projetos.
:::

:::hint{type="warning"}
****:FontAwesome[****]{icon="fa-solid fa-triangle-exclamation"}**&#x20;Erros comuns**

**Código inválido ou duplicado**

O código precisa respeitar o formato de 4–8 caracteres em minúsculas, números e hífen e não pode repetir o código de outro projeto. Corrija o valor no passo de Identidade; em caso de conflito, escolha outro código e envie novamente.

**Término anterior ao início**

Quando ambas as datas são informadas, o assistente rejeita um término anterior ao início. Ajuste as datas ou deixe uma delas em branco até ter o planejamento definido.

**Time novo sem nome**

A opção de criar um Time exige um nome não vazio (e com no máximo 200 caracteres). Preencha o nome sugerido ou selecione um Time existente.

**ART ou Planning Interval não selecionado no SAFe**

No SAFe, selecionar um ART existente exige um PI disponível e selecionado; sem eles o botão de avançar permanece bloqueado. Escolha outro ART, cadastre o PI ou use a opção de criar um novo ART.

**Projeto já existente**

Um conflito de nome, código ou provisionamento é informado após o envio. Revise os dados, altere o nome ou código e tente criar novamente; o assistente não cria uma segunda cópia silenciosamente.
:::


[title] Documentos do quadro e da tarefa
[path] Aplicações/Agility/Workspaces e Fundamentos/

:::BlockQuote
Anexe arquivos ao Board ou a uma task, classifique-os por tipo, consulte os metadados e baixe ou exclua documentos conforme sua permissão.
:::

:::hint{type="info"}
**Pré-requisito:**

Tenha um projeto com a capability de Documentos, Board principal e uma sessão com permissão de visualização. Upload e exclusão exigem a permissão de edição; a gestão do catálogo exige edição e ser administrador do Workspace ou responsável pelo projeto.
:::

***

Documentos existem em dois níveis. A tela "Documentos" do Board lista os arquivos do projeto/Board em uma tabela completa; o painel compacto no detalhe da task mostra apenas os anexos daquela tarefa. O mesmo fluxo oferece visualizar detalhes, baixar o arquivo, excluir e, no nível do projeto, configurar os tipos ativos.

Cada arquivo é enviado como multipart e recebe um tipo do catálogo do projeto. O tipo pode exigir campos de metadados; por isso o upload não é apenas escolher um arquivo: selecione a classificação, preencha os campos obrigatórios e só então envie. O catálogo é específico do projeto e os tipos inativos deixam de ser opções para novos uploads.

***

### Passo a passo

::::WorkflowBlock
:::WorkflowBlockItem
**Abrir Documentos do Board**

No menu do projeto, selecione "Documentos". A rota valida que a capability está ativa, que o Board solicitado é o Board principal do projeto e que sua sessão tem permissão de visualização. Em um acesso válido, o painel completo mostra o título Documentos e a tabela; não é necessário navegar por uma tela intermediária.
:::

:::WorkflowBlockItem
**Conferir o catálogo de tipos**

Se você pode enviar ou administrar tipos, o painel carrega o catálogo ativo do projeto e preenche o seletor de tipo. O tipo determina o nome exibido na coluna Tipo e quais campos de metadados serão pedidos. Selecione outro tipo quando o arquivo representar uma categoria diferente, em vez de colocar tudo em uma classificação genérica.
:::

:::WorkflowBlockItem
**Escolher o arquivo**

Na área de envio, escolha um arquivo pelo seletor. O componente mantém o arquivo selecionado até o envio terminar, permite escolher novamente o mesmo arquivo e não inicia a operação sem um arquivo. Confirme que o tipo ativo desejado continua selecionado antes de prosseguir.
:::

:::WorkflowBlockItem
**Preencher metadados**

Quando o tipo possui campos configurados, preencha cada campo obrigatório mostrado abaixo do seletor. O painel verifica o texto depois de remover espaços em branco; um campo vazio ou composto apenas por espaços impede o envio. Campos opcionais podem permanecer vazios e não são enviados como metadado.
:::

:::WorkflowBlockItem
**Enviar o documento**

Clique em "Enviar". O Agility envia o arquivo, o tipo e os metadados para o escopo atual. Durante a operação, os controles de upload ficam ocupados; em sucesso, o campo de arquivo e os metadados são limpos e a lista é recarregada no mesmo projeto. Em caso de falha, o arquivo e o tipo permanecem disponíveis para tentar novamente.
:::

:::WorkflowBlockItem
**Ler a tabela**

A tabela apresenta nome do documento, tipo, tamanho, autor e ações. O tamanho é formatado para leitura humana; o autor usa o nome projetado pelo backend e não exibe UUID. Use a busca por nome e o filtro de Tipo para reduzir a lista sem alterar os arquivos.
:::

:::WorkflowBlockItem
**Abrir detalhes e baixar**

Na coluna de ações, abra o botão de informações para ver os detalhes do documento. Use o botão de download para obter um Blob autenticado com o nome original do arquivo; a credencial é enviada pelo fetch e não exposta na URL. O download exige permissão de visualização.
:::

:::WorkflowBlockItem
**Excluir um documento do Board**

Se sua sessão tem edição, use o botão de exclusão na linha. O painel abre a confirmação para o documento específico; confirme apenas depois de verificar nome e tipo. Em sucesso, o diálogo fecha e a tabela é recarregada. A exclusão não é exibida para sessões sem a permissão correspondente.
:::

:::WorkflowBlockItem
**Configurar tipos do projeto**

No cabeçalho da variante completa, administradores e o responsável do projeto com permissão de edição veem "Configurar tipos". Abra esse diálogo para consultar ou manter o catálogo do projeto: cada tipo tem nome, descrição, estado ativo e campos ordenados, que podem ser marcados como obrigatórios. Desative um tipo que não deve mais ser usado sem alterar os documentos históricos que já o utilizam.
:::

:::WorkflowBlockItem
**Anexar no detalhe da task**

Abra um cartão no Quadro e role até "Anexos". O painel compacto usa o escopo Board + Projeto + Task, lista apenas os arquivos vinculados àquela tarefa e repete o envio, detalhes, download e exclusão conforme as permissões. Um documento enviado nesse local não aparece como anexo de outra task; o vínculo é específico da tarefa.
:::

:::WorkflowBlockItem
**Trocar de projeto ou tarefa com segurança**

Ao mudar de projeto, Board ou task, o painel cancela carregamentos e operações do escopo anterior, limpa seleção, metadados, filtros e diálogos e carrega a nova lista. Aguarde a lista do novo contexto antes de enviar ou excluir, para evitar trabalhar no arquivo de outro escopo.
:::
::::

:::hint{type="success"}
:FontAwesome[]{icon="fa-solid fa-check"} **Verificação**

- O documento enviado aparece na tabela com nome, tipo, tamanho e autor, e pode ser encontrado pela busca ou filtro de tipo.
- Abrir detalhes mostra o documento correto; baixar cria um arquivo com o nome original.
- Depois de uma exclusão confirmada, a linha desaparece após o recarregamento e o documento não pode mais ser aberto naquele escopo.
- No detalhe de uma task, o anexo aparece somente no painel compacto daquela task.
- Um tipo com campo obrigatório só permite o envio depois que o metadado correspondente é preenchido.
:::

:::hint{type="warning"}
****:FontAwesome[****]{icon="fa-solid fa-triangle-exclamation"}**&#x20;Erros comuns**

**Documentos indisponíveis para a sessão**

Sem capability efetiva de Documentos, sem Board principal correspondente ou sem permissão de visualização, o acesso é bloqueado e o painel informa a indisponibilidade. Entre no projeto correto ou peça a permissão ao administrador; não tente contornar a rota direta.

**Nenhum tipo ativo para upload**

O seletor de tipo fica desabilitado quando o catálogo não tem tipos ativos. Um administrador ou responsável deve criar/ativar um tipo na configuração do projeto antes do primeiro envio.

**Metadado obrigatório ausente**

O botão de upload não avança enquanto algum campo obrigatório estiver vazio ou só contiver espaços. Selecione o tipo correto e preencha todos os campos exigidos; metadados opcionais não precisam ser inventados.

**Upload ou download interrompido**

Uma falha de rede ou troca de contexto cancela a operação. No upload, a seleção permanece para retry; no download, repita a ação no documento ainda listado e confirme que você continua no mesmo projeto/Board.

**Exclusão sem permissão de edição**

A ação de excluir não aparece para uma sessão somente leitura. Solicite acesso de edição ao administrador; visualizar e baixar continuam separados da capacidade de apagar.
:::


[title] ARTs (Agile Release Trains): visão geral
[path] Aplicações/Agility/SAFe — Trens ágeis/

:::BlockQuote
Um ART reúne Times que trabalham juntos em uma missão comum, com cadência e Planning Intervals compartilhados.
:::

:::hint{type="info"}
**Pré-requisito:**

Tenha acesso a um Workspace. No roteiro, usamos o Workspace Portal de Serviços e o ART Cidadão Digital, que já possui Times, projetos e PIs de demonstração.
:::

***

No Agility, um ART (Agile Release Train) é o agrupador SAFe de execução em escala. Ele tem código, nome, missão, cadência de iterações e uma coleção de Times do Workspace. O ART é o ponto que conecta a estratégia (missão e objetivos) ao planejamento de Features, capacidade, riscos e entregas dos Times.

A lista de ARTs é específica do Workspace. Ao abrir um trem, a tela de Visão geral concentra indicadores do trem, o PI atual, capacidade, riscos, missão, Times vinculados, objetivos e o estado da preparação. As abas do próprio ART levam ao Backlog, Planning Intervals, Planning Board, Objetivos, Riscos ROAM e Inspect & Adapt.

***

### Passo a passo

::::WorkflowBlock
:::WorkflowBlockItem
**Abrir o diretório de ARTs**

No Workspace Portal de Serviços, escolha ARTs na barra lateral. A tabela mostra uma linha por trem, com ART (nome e código), Owner, quantidade de Times, quantidade de Projetos e Status. O botão Novo ART aparece para quem tem permissão de edição.
:::

:::WorkflowBlockItem
**Localizar um trem**

Use o campo Buscar por código, nome ou owner para filtrar a tabela. O filtro procura pelo código, nome, identificação do owner e rótulo de owner não definido. O botão Status permite selecionar um ou mais estados exibidos no resultado; os cabeçalhos ART, Owner, Times, Projetos e Status também permitem ordenar a tabela.
:::

:::WorkflowBlockItem
**Abrir o ART de exemplo**

Abra a linha ART Cidadão Digital. O link leva à Visão geral do ART, sem sair do Workspace. O cabeçalho mantém a missão do trem e a navegação horizontal do ART fica disponível para as próximas superfícies.
:::

:::WorkflowBlockItem
**Ler os indicadores da Visão geral**

Confira os cartões de Times, PI atual, previsibilidade e riscos não resolvidos. No exemplo, o PI em destaque aparece junto com o número de iterações, enquanto a previsibilidade e os riscos resumem o estado do ciclo sem substituir o detalhamento das abas.
:::

:::WorkflowBlockItem
**Conferir missão, PI e capacidade**

Na seção de cartões, leia a Missão para confirmar o propósito do trem; o cartão Planning Interval mostra o PI, data de início, iterações concluídas de um total e status, com o botão Abrir PI; e o cartão Capacidade exibe pontos usados, pontos totais e a barra percentual. O cartão Preparação do PI Planning leva à lista de Planning Intervals para iniciar o próximo ciclo.
:::

:::WorkflowBlockItem
**Identificar os Times que compõem o ART**

O cartão Times lista cada Time vinculado e exibe o selo SAFe. No ART Cidadão Digital estão vinculados Time Identidade, Time Jornada e Time Portal de Serviços. Com permissão de edição, o X de cada linha abre a confirmação de desvinculação; a operação altera a composição do trem, não exclui o Time do Workspace.
:::

:::WorkflowBlockItem
**Vincular um Time existente**

No mesmo cartão, use o seletor Vincular Time para escolher um Time do Workspace que ainda não esteja no ART e clique em Vincular Time. O seletor só lista Times não vinculados; depois de salvar, a tela recarrega a visão geral e o Time passa a aparecer na lista. Se todos já estiverem vinculados, o cartão informa essa situação em vez de oferecer uma escolha inválida.
:::

:::WorkflowBlockItem
**Iniciar o cadastro de um novo ART**

Volte ao diretório de ARTs e clique em Novo ART. Informe Nome e Código; o nome gera um código sugerido, mas o código pode ser ajustado antes do envio. A Missão é opcional e descreve o propósito que aparecerá no cabeçalho e no cartão de missão.
:::

:::WorkflowBlockItem
**Montar a composição e a cadência**

No diálogo, marque os Times que devem entrar no trem e, na seção Cadência, escolha o tamanho da iteração em semanas (1 a 4) e a quantidade de iterações (1 a 12). O resumo informa a duração total. O controle de IP habilita ou desabilita a iteração de inovação e planejamento; quando há IP, o resumo separa as iterações de entrega da iteração de IP. Se houver membros, selecione também o RTE ou deixe Sem RTE.
:::

:::WorkflowBlockItem
**Criar e confirmar o ART**

Revise nome, código, missão, Times, cadência, opção de IP e RTE. Clique em Criar ART. O Agility atualiza a contagem de navegação e abre a Visão geral do novo trem, onde você pode confirmar a missão, os Times e preparar o primeiro PI.
:::
::::

![](https://itsm-labdev.cloud4biz.com/agility-v2/docs/screens/05-art-overview.webp "Visão geral preenchida do ART Cidadão Digital, com cartões de PI, capacidade, Times e objetivos")

:::hint{type="success"}
:FontAwesome[]{icon="fa-solid fa-check"} **Verificação**

- A tabela do Workspace mostra o ART Cidadão Digital com código, Times, Projetos e status.
- A Visão geral exibe missão, PI atual, previsibilidade, capacidade e riscos em cartões preenchidos.
- Os Times Identidade, Jornada e Portal de Serviços aparecem no cartão Times com o selo SAFe.
- Depois de criar um ART, a aplicação abre a Visão geral dele e oferece a preparação de um PI.
:::

:::hint{type="warning"}
****:FontAwesome[****]{icon="fa-solid fa-triangle-exclamation"}**&#x20;Erros comuns**

**O botão de criar ou vincular não aparece**

Essas escritas exigem a capacidade de edição. Entre com um usuário que possa editar o Workspace; para leitores, a tela permanece consultável e não oferece um controle que terminaria em 403.

**Código do ART ausente, inválido ou repetido**

Nome e Código são obrigatórios. O código é validado enquanto você digita e o servidor também pode rejeitar conflito; ajuste o código sugerido para um identificador válido e exclusivo antes de reenviar.

**Não há Times para selecionar**

A criação permite continuar sem Times, mas a composição ficará vazia. Crie primeiro um Time no Workspace ou vincule Times existentes pela própria Visão geral do ART.

**O cartão de PI mostra que não existe ciclo atual**

Isso significa que o ART ainda não tem um Planning Interval atual. Abra Planning Intervals e crie o primeiro PI; objetivos, preparação e algumas ações dependem desse PI.
:::


[title] Inspect & Adapt
[path] Aplicações/Agility/SAFe — Trens ágeis/

:::BlockQuote
Analise os fatos persistidos de um PI concluído e registre ações de melhoria para o ART, sem transformar automaticamente o aprendizado em Tasks ou Stories.
:::

:::hint{type="info"}
**Pré-requisito:**

Tenha pelo menos um PI concluído no ART. O ART Cidadão Digital oferece o PI 2026.2 concluído para consulta, com objetivos, capacidade, iterações e riscos persistidos.
:::

***

Inspect & Adapt é o workshop de aprendizagem após o encerramento do PI. A tela não usa o PI atual nem um PI em planejamento como retrospectiva: o usuário escolhe um PI concluído e revisa seus números persistidos, os objetivos atingidos e descartados, as alocações de capacidade e os riscos ROAM.

O resultado do workshop é uma ação de melhoria pertencente ao ART. Cada ação tem título, owner, prazo opcional, objetivo vinculado, risco vinculado e situação (aberta, em andamento, concluída ou cancelada). Registrar a ação preserva a decisão para o próximo ciclo, mas não cria Task ou Story automaticamente.

***

### Passo a passo

::::WorkflowBlock
:::WorkflowBlockItem
**Abrir Inspect & Adapt**

Na navegação do ART, clique em Inspect & Adapt. Use Ver Planning Intervals para voltar à lista de PIs. A tela começa pelo seletor de PI concluído e informa explicitamente que o PI atual ou em planejamento não é usado como retro.
:::

:::WorkflowBlockItem
**Selecionar o PI concluído**

No campo PI concluído, escolha um PI elegível. O rótulo combina nome e data final; no exemplo, o PI 2026.2 aparece com fim em 30/09/2026. Selecione o ciclo para carregar o snapshot factual daquele PI.
:::

:::WorkflowBlockItem
**Ler os fatos persistidos**

O cartão do PI mostra início e fim, Progresso, Iterações concluídas/total, Objetivos concluídos/total, Capacidade usada/total e Previsibilidade. Esses valores são os campos persistidos do PI e servem como base do debate, sem o Agility inferir satisfação a partir deles.
:::

:::WorkflowBlockItem
**Revisar objetivos atingidos e descartados**

Em Resultado do PI, o painel Objetivos atingidos lista objetivos que terminaram como alcançados e mantém seu valor de negócio persistido. O painel Objetivos descartados lista objetivos com situação dropped no snapshot. Use os títulos e valores para conduzir a conversa sobre resultado, não apenas sobre quantidade.
:::

:::WorkflowBlockItem
**Conferir capacidade e alocações**

No Contexto factual, compare Disponível canônico e Alocado canônico com as linhas de capacidade por Time e iteração. A tela indica quando as linhas canônicas coincidem ou divergem dos campos denormalizados do PI e informa quantas alocações de Features foram carregadas; nenhum ponto é inferido dessas linhas.
:::

:::WorkflowBlockItem
**Revisar riscos ROAM**

O painel Riscos ROAM mostra código, nome, classificação (por exemplo, mitigado ou aceito) e exposição persistida. Esses riscos são contexto do PI e não são tratados como causa raiz automaticamente; use-os para formular ações de melhoria concretas.
:::

:::WorkflowBlockItem
**Registrar uma ação de melhoria**

Em Registrar ação, informe o Título, selecione o Owner entre os membros ativos e, se necessário, escolha um Prazo. Você pode vincular a ação a um Objetivo e a um Risco pelos respectivos seletores. Clique em Criar ação; a nova ação aparece na lista do ART.
:::

:::WorkflowBlockItem
**Acompanhar e editar a ação**

Na lista de ações, confira título, owner, prazo, links e situação. Use Editar para alterar os mesmos dados. As transições de situação permitem acompanhar aberta, em andamento, concluída ou cancelada; a atualização permanece no ART e pode ser revisada no próximo ciclo.
:::
::::

![](https://itsm-labdev.cloud4biz.com/agility-v2/docs/screens/05-inspect-adapt-result.webp "Inspect & Adapt do PI 2026.2 concluído com métricas, objetivos atingidos e descartados")

:::hint{type="success"}
:FontAwesome[]{icon="fa-solid fa-check"} **Verificação**

- O seletor oferece apenas PIs concluídos e o cartão exibe o PI escolhido com suas datas.
- Os cartões carregam progresso, iterações, objetivos, capacidade e previsibilidade do snapshot selecionado.
- Objetivos atingidos e descartados aparecem em painéis separados com o valor de negócio persistido.
- Capacidade canônica, alocações e riscos ROAM são exibidos como contexto factual do PI.
- Uma ação criada fica na lista do ART e pode mudar de situação sem criar automaticamente uma Task ou Story.
:::

:::hint{type="warning"}
****:FontAwesome[****]{icon="fa-solid fa-triangle-exclamation"}**&#x20;Erros comuns**

**Nenhum PI concluído disponível**

A tela mostra um estado vazio quando o ART ainda não tem PI concluído. Feche um PI pelo ciclo de vida e volte ao Inspect & Adapt; não use o PI atual como substituto.

**Owner não selecionado na ação**

Título e Owner são obrigatórios. Escolha um membro no campo Owner antes de criar ou salvar uma ação.

**Ação de melhoria não cria trabalho no quadro**

Esse é o comportamento intencional: a ação permanece no ART. Se a decisão precisar de execução operacional, registre separadamente o trabalho no fluxo apropriado e mantenha o vínculo descrito na ação.

**Divergência entre capacidade e campos do PI**

A tela torna a divergência visível em vez de escondê-la. Confira as linhas vivas de capacidade e as alocações do PI antes de concluir uma ação sobre previsibilidade ou capacidade.
:::


[title] 5. Catálogo e frameworks
[path] Aplicações/GRCS/

*Como o catálogo é organizado e o que você pode alterar nele.*

O catálogo é **o que se pergunta**. Ele se prepara depois dos alvos e antes da auditoria, nesta ordem: decidir que normas esta instalação enxerga (**Normas disponíveis**, no fim deste capítulo), escolher um framework de fábrica ou montar o seu (**Framework próprio**, com perguntas de qualquer norma e perguntas novas), ajustar o que cada pergunta vale (**Peso das perguntas**) e, se for disparar por partes, recortar em **Agrupamentos** (capítulo seguinte). Temas e listas de valores são apoio: o tema recorta o acervo por assunto, a lista dá a várias perguntas as mesmas opções.

***

### <font color="#15803D">O catálogo nasce cheio</font>

Os frameworks de fábrica já vêm com requisitos, controles e perguntas carregados. Eles são **somente leitura**: ninguém altera o NIST CSF de dentro da plataforma, porque a norma não é sua.

***

### <font color="#15803D">O que você pode fazer</font>

Em **Framework próprio** você monta o seu selecionando perguntas de qualquer framework existente. Dentro do seu, você pode editar o enunciado e acrescentar perguntas novas — nunca no de origem.

Quando você deriva uma pergunta, a plataforma guarda **de onde ela veio e em que versão**. É isso que permite, depois, saber que a sua pergunta de MFA nasceu da pergunta X do CIS v8.

***

### <font color="#15803D">A tela de Frameworks</font>

Mostra o que existe para auditar. No alto, **Meus frameworks** — os montados em *Framework próprio*, com versão, número de perguntas e se estão *publicado* ou *rascunho*. Abaixo, o **Catálogo de fábrica**, agrupado por categoria e somente leitura.

1.     Para ver as perguntas de uma norma, clique no cartão dela. A janela lista cada pergunta **uma vez**, com o controle que ela avalia, o código dela e as outras normas que ela também alcança (*também alcança*) — é ali que se vê que responder uma coisa resolve cinco.

2.     Para saber em que normas uma pergunta está, use a busca **Buscar uma pergunta e ver em quais frameworks ela está…**, no alto da tela.

3.     Para montar o seu, vá a **Framework próprio**; para recortar uma norma em partes, a **Agrupamentos**.

A lista da janela é agrupada pelo **agrupamento** — o recorte de disparo —, e não pela cláusula. A pergunta não aponta para a cláusula: ela avalia um controle, e o controle responde a várias cláusulas; agrupar por cláusula repetia a mesma pergunta dezenas de vezes. Pergunta em dois agrupamentos aparece nos dois, porque sai em duas rodadas. Norma sem agrupamento vira lista única.

O selo **licenciada** marca a norma de que guardamos só o identificador da cláusula e uma descrição própria, nunca o texto oficial.

***

### <font color="#15803D">A tela de Perguntas</font>

O acervo inteiro num lugar só — as de fábrica, que vêm com os frameworks, e as suas.

Ela existe por causa de uma pergunta que não tinha resposta: *onde estão as perguntas que eu criei e coloquei dentro de frameworks ou temas?* Estavam dentro do questionário onde foram digitadas, o que serve para quem lembra em qual e para mais ninguém.

Três coisas se fazem aqui e não se faziam em lugar nenhum:

**Criar a pergunta sem um questionário que a contenha.** Ela entra no catálogo no ato e passa a ser encontrável por tema, por afinidade e pela busca; entra num questionário depois, se e quando alguém quiser. A ordem inversa — a única possível antes — obrigava a inventar um questionário só para poder escrever a pergunta, e questionário inventado assim nunca é apagado.

A escala de resposta vem junto com o tipo escolhido. Pergunta sem escala não pontua, e pergunta que não pontua entra no ciclo parecendo informativa: silenciosamente fora do score.

**Gerenciar os temas pelo lado da pergunta.** O vínculo já existia, e só pelo lado do tema: quem pensa *esta pergunta é sobre retenção de dados* começava pela pergunta e tinha de ir até a tela de Temas, achar o tema certo e procurá-la numa lista de trezentas. Agora vale nos dois sentidos.

Só temas próprios aparecem para marcar. Os de fábrica vêm com o acervo e não recebem vínculo novo — contaminá-los faria a próxima atualização do catálogo ter de decidir o que fazer com a pergunta do cliente.

***

### <font color="#15803D">Perguntas, passo a passo</font>

No alto, os recortes: **Buscar** (código, enunciado, tema ou norma), **Mostrar** (todas, só as minhas, só as de fábrica), **Norma** e **Tema**; **limpar os filtros** desfaz tudo. A lista mostra as 200 primeiras — refine para chegar ao resto.

1.     **Criar**: **Nova pergunta** → **Código** (é como ela é citada no relatório), **Tipo de resposta** (a escala vem com ele), **Enunciado**, **Evidência esperada** e, se for o caso, **Evidência obrigatória** → **Criar**.

2.     **Abrir o detalhe**: clique na pergunta. Aparecem **Respostas aceitas** (escala, pontuação, se abre achado, peso e criticidade), **Temas**, **Afinidade com normas**, **Dimensões** e, nas suas perguntas, **De onde vêm as opções**.

3.     **Marcar tema**: em **Temas**, clique no tema para ligar ou desligar — grava no clique. Só os temas próprios aparecem; sem nenhum, crie o primeiro em **Temas**.

4.     **Afinidade sugerida**: **sugerir com o modelo** e, em cada proposta, **aceitar** ou **recusar**.

5.     **Afinidade à mão**: em **Marcar à mão**, escolha a norma, escreva **por quê (opcional)** → **marcar afinidade**. Ela já nasce aceita, com o seu nome. Para **remover** uma afinidade aceita, clique no **×** da etiqueta: ela fica registrada como recusada (riscada) e o modelo não a propõe de novo. Uma recusada volta a ser oferecida em *Marcar à mão*, se você mudar de ideia.

6.     **Dimensões**: clique na dimensão para ligar ou desligar — grava no clique. Ver Dimensões.

7.     **Opções de uma lista**: em **De onde vêm as opções**, escolha a lista de valores ou *desta pergunta mesmo*. Trocar não apaga as opções próprias. Valor de lista não pontua nem abre achado.

8.     **Plano obrigatório**: nas suas perguntas com opções próprias, a coluna **plano de ação** da tabela tem uma caixa na resposta que abre achado. Marcada (*obrigatório*), o achado só se trata com plano de ação aprovado — aceitar o risco não basta.

O peso não se muda aqui: vem de **Peso das perguntas**. Pergunta de fábrica é só leitura nesta tela, exceto nas dimensões e na afinidade, que são da sua instalação.

:::hint{type="info"}
**Permissão.** Criar pergunta, mudar temas, opções, plano e afinidade (inclusive *sugerir com o modelo*) exige questionario\:escrever; marcar dimensões exige catalogo\:escrever e ler os alvos e dimensões (escopo\:ler). Sem elas, os botões não aparecem, a tela é consulta e uma linha no alto diz qual permissão falta.
:::

***

### <font color="#15803D">Afinidade não é alcance</font>

A mesma tela mostra duas relações entre pergunta e norma, e a diferença entre elas é a razão de existirem separadas.

**Alcance** é derivado e conferível: a pergunta avalia um controle, o controle atende um requisito, o requisito pertence ao framework. Cada elo é um vínculo que alguém cadastrou, e o resultado se confere cláusula a cláusula. É o que a linha "normas alcançadas" mostra.

**Afinidade** é inferência. A pergunta que a empresa escreveu — *a área mantém inventário das operações de tratamento de dados pessoais?* — tem relação evidente com a LGPD e com a ISO 27701 sem que ninguém tenha mapeado cláusula nenhuma, e ninguém vai mapear cláusula a cláusula para trezentas perguntas internas. Sem essa etiqueta, a pergunta própria só é reencontrada por quem lembra que ela existe.

O botão **sugerir com o modelo** pede ao modelo de linguagem a lista de frameworks com que a pergunta tem afinidade. Três cuidados, e os três vêm da mesma preocupação — que uma inferência não passe por um fato:

•     a sugestão nasce **proposta** e não vale nada até alguém aceitar;

•     o modelo só escolhe entre os frameworks **cadastrados**, e o que ele inventa é descartado — um modelo pequeno produz sigla plausível com facilidade;

•     o que foi **recusado** não volta a ser proposto, e a recusa fica gravada: *nunca foi sugerido* e *foi sugerido e recusado* são coisas diferentes para quem audita o catálogo.

A afinidade também se marca à mão, em **Marcar à mão** — o caminho para quando o modelo não enxerga o óbvio —, e ela nasce aceita e sem confiança declarada: pessoa decide, não estima. Só as normas de fábrica são oferecidas, porque a afinidade é com norma de mercado. Remover uma afinidade é recusá-la: a linha fica gravada, pelo mesmo motivo de a recusa do modelo ficar.

***

### <font color="#15803D">Cada framework é independente</font>

Cada pergunta pertence **só ao próprio framework**. Uma auditoria do Pink Elephant tem as perguntas do Pink; uma da PeopleCert tem as da PeopleCert. Nenhuma das duas entra na avaliação, na nota ou na maturidade de outra norma, mesmo quando o assunto é o mesmo. Por isso a mesma exigência pode aparecer, com a redação de cada uma, em duas normas: cada uma é certificada pela própria régua.

A exceção é o **PPSI**, que é composto de perguntas de outros frameworks por definição.

O que duas normas têm em comum é **informação**, e não pergunta compartilhada: a **correspondência informativa**. Ela liga a pergunta a cláusulas de outras normas que tratam do mesmo tema, com a justificativa (*registro e classificação de incidentes na ferramenta*). Ela aparece em três lugares:

•     **Também serve a…**, nos detalhes da pergunta: as cláusulas de outras normas que a mesma evidência ajuda a atender;

•     **Atendimento cruzado (informativo)**, na auditoria: com as respostas desta auditoria, quanto de cada outra norma fica atendido e quantas cláusulas dela ficam sem correspondência (a lacuna);

•     **Normas × normas**, na Cobertura UCF: a linha do Pink Elephant e a da PeopleCert, e a coluna de cada um nas outras normas, com o percentual de atendimento por similaridade das perguntas (ver *Cobertura UCF: quatro leituras*).

É assim que quem se certificou no Pink Elephant enxerga quanto do ITIL 4, do COBIT ou da ISO 20000 a mesma documentação já atende. O atendimento cruzado é leitura: não muda nota nenhuma e não abre achado em outra norma.

***

### <font color="#15803D">Pink Elephant e PeopleCert</font>

Os dois avaliam a **ferramenta** de gestão de serviços de TI, e vêm com o **texto original**, em inglês; quem usa a plataforma em português ou espanhol vê a tradução (ver *Idiomas*).

Os dois também se correspondem entre si, pelo mesmo critério das outras normas: a pergunta do Pink corresponde ao critério da PeopleCert que aponta para o mesmo controle do UCF, e vice-versa. É o que aparece em **Também serve a…**, no **Atendimento cruzado** de uma auditoria de um deles e na linha e coluna dos dois em **Normas × normas**. Continua informativo: a pergunta do Pink não entra na avaliação da PeopleCert, nem o contrário.

**Pink Elephant** (PinkVERIFY 3.0): um agrupamento por processo, com os critérios do questionário debaixo dele. Toda pergunta pesa 1, a escala é a de implementação, e qualquer resposta abaixo de 100% exige plano de ação com data.

**PeopleCert** (ITIL 4 Assessment Model, ATV 2025.2): um agrupamento por prática (P01 a P20) e um por área de plataforma (T01 a T10). A escala é a da PeopleCert:

| **Resposta**                             | **Obrigatório** | **Opcional e plataforma** |
| ---------------------------------------- | --------------- | ------------------------- |
| Out-of-the-box (nativo)                  | 100%            | 100%                      |
| Local configuration (configuração local) | 70%             | 70%                       |
| Custom development (sob medida)          | 0%              | 50%                       |
| External module (módulo externo)         | 0%              | 50%                       |
| In the next release (próxima versão)     | 0%              | 0%                        |
| Not available (não disponível)           | 0%              | 0%                        |



Módulo externo, configuração local e desenvolvimento sob medida pedem comentário. O peso da planilha (1, 3 ou 5) vai para o peso da pergunta; os critérios de peso 0 (quase todos de IA) ficam no relatório e fora da nota. Abaixo de 100% exige plano, menos nos critérios de peso 0 e de plataforma.

**Aprovação por pontos.** Uma prática é aprovada quando **todo critério obrigatório** tem nota maior que zero **e** os opcionais somam ao menos os **pontos mínimos** da prática (peso × nota). O mínimo é o da PeopleCert: 70% do peso total dos opcionais. Na auditoria, **Aprovação por pontos** mostra, por prática, aprovada ou reprovada, os pontos obtidos contra o mínimo e os obrigatórios pendentes. As áreas de plataforma não têm corte: mostram só o percentual de pontos.

***

### <font color="#15803D">Temas e a Cobertura UCF</font>

**Temas** agrupam perguntas por assunto — acesso, backup, privacidade, continuidade — para você montar questionário por área de interesse.

**Cobertura UCF** mostra o outro eixo: quantas normas cada pergunta alcança. É a tela que responde "se eu responder estas quarenta, quanto do meu ISO 27001 eu cobri?".

***

### <font color="#15803D">Temas, passo a passo</font>

Duas abas. **Taxonomia de fábrica** é somente leitura: **Filtrar tema…** e clique no tema para ver as perguntas dele. **Meus temas** é onde se monta. Os botões de criar, adotar e editar só aparecem para quem tem catalogo\:escrever.

1.     **Criar**: **Novo tema** → **Código** (curto e estável) e **Nome** (é o que aparece no seletor de origem da auditoria) → **Salvar**. O tema nasce vazio.

2.     **Adotar um de fábrica**: em **Adotar um tema de fábrica como meu**, escolha o tema → **Adotar**. Nada é copiado; o recorte passa a ser seu, e o de fábrica fica intacto.

3.     **Trazer perguntas**: abra o tema → **Trazer perguntas** → procure, agrupe (**Por framework**, **Por tema**, **Só a lista**), marque as perguntas (ou **marcar todas** no grupo) → **Vincular**. O **×** ao lado de uma pergunta a tira do tema; ela continua no catálogo.

4.     **Organizar em blocos**: **Organizar em blocos** → **Novo bloco** (**Código**, **Nome**) → **Criar**; em cada bloco, **trazer uma pergunta do tema…** → **Trazer**. Só pergunta que já está no tema entra num bloco, e pergunta fora de bloco aparece no fim do formulário.

5.     **Renomear e proteger**: o lápis abre **Renomear**, com a caixa **Proteger contra exclusão**.

6.     **Excluir**: a lixeira pede confirmação → **Excluir**. Só o tema sai; as perguntas e as auditorias já abertas a partir dele não mudam. Tema protegido mostra um cadeado no lugar da lixeira: desmarque a proteção em **Renomear** antes.

***

### <font color="#15803D">A escala de resposta</font>

A escala padrão tem seis níveis:

| **resposta**     | **pontos** | **significa**                           |
| ---------------- | ---------- | --------------------------------------- |
| Implementado     | 100        | opera e há evidência                    |
| Parcial          | 75         | opera, com lacuna conhecida             |
| Em implantação   | 50         | decidido e em execução, ainda não opera |
| Em estudo        | 25         | reconhecido, sem execução iniciada      |
| Não implementado | 0          | não existe                              |
| Não aplicável    | **peso 0** | fora do escopo avaliado                 |

:::hint{type="info"}
**"Não aplicável" não é nota zero.** Nota zero puniria a organização por um controle que não lhe cabe. Ela sai da média — mas continua contada e exibida nos relatórios, porque um ciclo com metade das perguntas marcadas assim diz muito sobre o escopo declarado.
:::

***

### <font color="#15803D">Cobertura UCF: quatro leituras</font>

| **Matriz**              | **A quem serve**                                                      |
| ----------------------- | --------------------------------------------------------------------- |
| Perguntas × normas      | a quem responde: uma resposta, várias aderências                      |
| Normas × normas         | a quem compara certificações: quanto de uma já está feito pela outra  |
| Temas × normas          | a quem planeja: trabalhando este assunto, que normas eu movo          |
| Requisitos × documentos | a quem mantém o acervo: que documento diz como cumprir cada requisito |



Cada leitura é uma aba no alto da tela:

1.     **Perguntas × normas**: em **Normas na matriz**, clique nas siglas para incluir ou tirar colunas (abrem seis); **voltar ao padrão** desfaz; **Filtrar pergunta…** estreita as linhas.

2.     **Normas × normas**: **todas**, ou clique numa norma para ver a linha dela contra todas, ou em várias para ver só o cruzamento entre elas. Leia da linha para a coluna.

3.     **Temas × normas**: escolha o tema na coluna da esquerda; a barra é a fração das cláusulas folha de cada norma que o tema alcança.

4.     **Requisitos × documentos**: escolha o **Framework**; **só lacunas** mostra os requisitos sem documento. Os contadores dizem **Requisitos**, **Cobertos**, **Lacunas** e **Documentos órfãos**.

A leitura de normas × normas **não é simétrica**, e é isso que ela tem de útil: quem atende a ISO 27001 já fez a maior parte do PCI DSS, e quem atende o PCI está bem longe da ISO. A diferença diz por onde começar.

Os números em **itálico, com sublinhado tracejado**, vêm da correspondência informativa dos frameworks independentes (Pink Elephant, PeopleCert), cujas perguntas não compartilham controle com nenhuma outra norma. Na linha do Pink, o número é a fração das perguntas do Pink que correspondem a alguma cláusula da norma da coluna; na linha da ISO 27001, coluna do Pink, é a fração das perguntas da ISO que alcançam uma cláusula a que alguma pergunta do Pink corresponde. É atendimento por similaridade, e não pergunta compartilhada: nenhuma pergunta passa de uma norma para a outra, e nada disso entra em nota, score ou maturidade.

Em temas × normas a unidade é a **cláusula folha**, e não a pergunta: dez perguntas que batem na mesma cláusula cobrem uma cláusula, e contar perguntas diria dez.

:::hint{type="info"}
**Cobertura não é conformidade.** Ela diz que a pergunta existe, não que a resposta foi boa.
:::

***

### <font color="#15803D">Até onde vão as cláusulas</font>

As normas estão abertas até o nível em que a auditoria de fato cobra: PCI DSS até o sub-requisito, SOC 2 até o critério, ISO 27701 até os controles dos anexos, ISO 42001 até os controles do Anexo A, ISO 37001 e ISO 37301 até a subcláusula, ISO 20022 pelas partes e áreas de negócio das mensagens, IEC 62443 até o requisito de sistema, LGPD e GDPR até o inciso e a alínea.

O nível seguinte de algumas delas — o terceiro nível do PCI, os requisitos de melhoria da 62443, as práticas de APO, BAI, DSS e MEA do COBIT — é conteúdo licenciado que não se deduz da estrutura pública. Ele entra por manifesto derivado do documento que o cliente licenciou. Inventar o identificador seria pior do que não tê-lo: um identificador errado é indistinguível de um certo para quem lê.

***

### <font color="#15803D">Listas de valores</font>

Uma lista cadastrada uma vez e usada por várias perguntas — por exemplo, a lista de sistemas ou de unidades. Vinte cópias da mesma lista envelhecem em ritmos diferentes; uma só muda para todas as perguntas que a usam.

1.     **Nova lista** (no alto da tela) → **Código** e **Nome** → **Criar**.

2.     Clique na lista para abri-la → **Valor** e **Rótulo** → **Acrescentar**.

3.     Valor não se apaga: o ícone do olho **desativa** — sai do formulário e continua valendo no que já foi respondido — e reativa.

4.     Para usar a lista numa pergunta, abra a pergunta em **Perguntas** e escolha a lista em **De onde vêm as opções**. A lista aberta mostra **Perguntas que usam esta lista**.

5.     A lixeira exclui a lista, e é recusada enquanto alguma pergunta a usar: troque antes a origem das opções dessas perguntas.

Criar e editar exige catalogo\:escrever. Lista *de fábrica* é somente leitura. Valor de lista não pontua nem abre achado.

***

### <font color="#15803D">Peso das perguntas</font>

Quanto cada pergunta vale na nota do ciclo, e quão grave é o achado quando ela falha. O peso muda a conta do score; a gravidade muda a severidade da não conformidade que nasce da resposta.

1.     Escolha o recorte: **Framework** ou **Tema** (escolher um limpa o outro) e, se quiser, **Procurar no enunciado ou no código**.

2.     Na linha da pergunta, mude o **Peso** (de 0 ao teto que a tela mostra, em passos de 0,25) e a **Criticidade**.

3.     Clique **gravar**, que aparece quando algo mudou. **de fábrica** volta ao valor que veio na caixa.

Editar exige catalogo\:escrever; sem ela, os campos ficam travados. O peso novo vale **do próximo ciclo em diante** — a marca *em N ciclo(s)* avisa que a pergunta já está em ciclo aberto, e a nota desses ciclos não muda. A marca *capacidade* indica pergunta que não entra na média de implantação.

***

### <font color="#15803D">Framework próprio, passo a passo</font>

1.     **Novo** → **Código**, **Nome** e **Objetivo** → **Criar**. Clique nele na lista à esquerda para abrir.

2.     **Do catálogo**: procure e filtre, marque as perguntas → **Incluir**. Pergunta de fábrica entra por referência.

3.     **Pergunta nova**: **Código**, **Tipo de resposta**, **Enunciado**, **Evidência esperada**, **Só perguntar quando** (em branco, pergunta sempre) e **Exigir evidência** → **Criar pergunta**.

4.     **Editar a pergunta** (lápis): numa pergunta de fábrica, salvar cria **uma cópia sua**, marcada *derivada de …*; a original não muda. Trocar o tipo troca a escala de resposta.

5.     **Remover do framework** (lixeira da linha) tira a pergunta só deste framework, depois de perguntar — com o foco no **Cancelar** e o **Esc** para desistir. A pergunta continua no catálogo.

6.     **Publicar** (exige ao menos uma pergunta). Mexeu depois? A tela avisa *Alterado depois de publicado* e o botão vira **Republicar**. Ciclos já abertos não mudam: a auditoria copia as perguntas na abertura.

7.     **Desativar** tira das listas e da abertura de auditoria sem apagar nada; **Reativar** traz de volta, e **Mostrar N desativados** os põe à vista.

8.     **Excluir** só vale para framework sem proteção e nunca usado em auditoria. A confirmação é **Excluir mesmo assim**, e as perguntas próprias criadas dentro dele saem junto. **Protegido** / **Sem proteção** alterna a trava.

:::hint{type="info"}
**Permissões.** Montar — **Novo**, **Do catálogo**, **Pergunta nova**, editar e remover pergunta, **Desativar** / **Reativar**, **Protegido** / **Sem proteção** e **Excluir** — exige questionario\:escrever (*Framework próprio — montar*); **Publicar** / **Republicar** exige questionario\:publicar (*Framework próprio — publicar*); ver a lista basta questionario\:ler. Sem a permissão, o botão aparece apagado e o título diz qual falta; o lápis e a lixeira de cada pergunta somem. Criar, incluir do catálogo, derivar e remover pergunta passaram a exigir questionario\:escrever também no servidor — antes bastava consultar.
:::

***

### <font color="#15803D">Tema e framework próprios</font>

Podem ser apagados, e podem ser **protegidos** contra exclusão acidental. A proteção não proíbe apagar: obriga a passar pela edição antes, o que troca um clique por engano por um gesto deliberado. O que se perde num tema montado à mão não é o registro — é o trabalho de seleção, e ele some com a mesma facilidade do que foi criado há um minuto.

Um tema de fábrica pode ser **adotado** como tema próprio: nasce com os mesmos vínculos, editável, sem copiar pergunta nenhuma.

***

### <font color="#15803D">Normas disponíveis para este cliente</font>

Em **Administração ▸ Normas disponíveis**, marque quais frameworks do catálogo aparecem para este cliente. O catálogo de fábrica continua inteiro; o que muda é o que as telas oferecem — quem só audita LGPD e ISO 27001 não precisa escolher entre quarenta normas a cada auditoria.

[title] 7. Auditoria, ondas e respostas
[path] Aplicações/GRCS/

*O ciclo de avaliação, da abertura ao fechamento — o que vai a campo, as ondas, a revisão, a apuração e as versões publicadas.*

A auditoria é o primeiro passo que **usa** o que veio antes: o alvo avaliado vem de *Alvos e escopo*, as perguntas vêm do catálogo (*Catálogo e frameworks*, *Agrupamentos*), e quem responde vem de *Áreas, grupos, usuários e perfis*. Com isso pronto, abrir o ciclo leva um minuto; sem isso, ele abre e não chega a ninguém.

***

### <font color="#15803D">A auditoria congela o catálogo</font>

Ao abrir, a auditoria guarda a **versão** de cada pergunta. Editar o enunciado depois não muda o que foi perguntado — a resposta histórica nunca aponta para um texto diferente do que a pessoa leu.

***

### <font color="#15803D">Ondas</font>

A auditoria nasce com todas as perguntas materializadas e **nenhuma visível**. Você monta uma onda com o subconjunto que quer despachar agora, escolhe quem recebe e dispara.

Três regras sustentam isso:

•     Pergunta fora de onda disparada **não é respondível**.

•     Pergunta já despachada **não migra** para outra onda.

•     O disparo **preserva** quem já foi delegado individualmente.

:::hint{type="info"}
Dividir o envio **não** divide o resultado: score e cobertura continuam sendo da auditoria inteira. Se fossem por onda, seria possível fabricar um resultado bom despachando primeiro só o que se sabe implementado.
:::

**Onde se monta.** Há duas portas. Dentro do ciclo, no bloco **Ondas de disparo**, escolhendo as perguntas uma a uma para uma equipe — o caso de uma auditoria de um alvo só. E em **Painel do framework ▸ Montar onda**, que é onde se olha o que voltou da rodada anterior e se despacham agrupamentos para muitos alvos de uma vez — ver *Disparo em escala e painel do framework*. O cartão do agrupamento, em *Catálogo ▸ Agrupamentos*, não dispara: o recorte se escolhe na abertura do ciclo ou na gaveta.

***

### <font color="#15803D">O que entra: agrupamentos</font>

O agrupamento é o **recorte das perguntas de um framework**, e serve a uma coisa só: disparar por partes. Ele é **opcional** — sem agrupamento, o questionário inteiro vai para uma área só, que é o caso comum de uma auditoria interna.

Uma onda carrega **quantos agrupamentos você quiser**, e uma pergunta que esteja em dois deles entra uma vez só. Não há liberação automática: quem olha o resultado da rodada anterior e decide o que perguntar em seguida é você, a cada rodada.

O recorte se cria e se edita antes, em **Catálogo ▸ Agrupamentos**, sempre a partir de um framework — agrupamento pertence a um framework e não atravessa para outro. Ver *Agrupamentos*.

***

### <font color="#15803D">Quem recebe: os alvos, escolhidos por atributo</font>

A escolha dos alvos **não é caixa por caixa**. Com quinze alvos isso funcionaria; com mil e trezentos, não. A gaveta oferece **todos**, **por tipo**, **por situação da resposta** (ainda não respondeu / respondendo / respondeu tudo), **sem área responsável**, e **por busca** — com a contagem do que está escolhido sempre à vista, no topo. A lista continua embaixo para tirar ou pôr um caso particular.

**Cada alvo vai para a própria área responsável.** É o vínculo do alvo em *Alvos e dimensões* que decide o destino de cada pergunta. A equipe escolhida na gaveta é o **destino padrão**, e vale para os alvos que ainda não têm responsável cadastrado — um único alvo sem área não trava o despacho dos outros.

***

### <font color="#15803D">A sobreposição, e o que fazer com ela</font>

Quando uma pergunta da onda **já foi respondida** por aquele alvo, nada acontece sozinho. Você decide entre **reaproveitar** — a resposta vigente passa a contar também nesta onda, e ninguém responde duas vezes a mesma coisa — e **perguntar de novo**, que devolve a pergunta para a fila. Sem decisão, a pergunta fica de fora: sobreposição resolvida em silêncio é a que ninguém percebe até a medição não bater.

Até dois mil itens a decisão é **uma a uma**, com a onda de origem, a data e o valor à vista. Acima disso a tela não oferece a lista, e a decisão é **do lote inteiro** — decidir setenta mil itens um a um não é rigor, é uma tela que ninguém termina, e uma onda que ninguém termina de montar é uma onda que não sai. Para decidir caso a caso numa onda grande, reduza o recorte de alvos ou de agrupamentos.

***

### <font color="#15803D">Delegação por pergunta</font>

Descobrir no meio do ciclo que a pergunta de backup pertence ao time de banco de dados, e não ao de infraestrutura, é o caso normal. Qualquer pergunta pode ser redirecionada sem mexer nas outras.

***

### <font color="#15803D">Onde a equipe responde</font>

Despachar sem caixa de entrada é mandar carta para um endereço sem caixa de correio. Quem recebe a onda **não abre esta tela**: abre **Responder auditoria**, no menu — o site *Responder a auditoria*, cuja lista se chama *Perguntas para Área* —, que reúne o que foi despachado ao grupo dela, o que lhe foi delegado em nome próprio e o que já é da área dela pelo alvo avaliado.

Para a pergunta chegar à área certa, o alvo do ciclo precisa apontar para o cadastro correspondente em **Alvos e dimensões** — é o campo *Representa o cadastro de*. Sem ele a pergunta não sabe de que área é, e só quem tem auditoria\:abrir a encontra. O caminho completo está em Responder uma auditoria.

***

### <font color="#15803D">Auditorias, passo a passo</font>

À esquerda, a busca e as situações — **Rascunhos**, **Em andamento**, **Encerradas**, **Arquivadas**, **Todas**. Clique num ciclo: o detalhe diz no topo qual é o próximo passo.

1.     **Abrir**: **Abrir auditoria** → **Natureza do ciclo** (**Auditoria** ou **Pré-auditoria**), **Alvo avaliado**, e em **Avaliar contra** as normas, temas e frameworks próprios (**Confirmar**). Com norma escolhida, **O que vai a campo** oferece **Todas as perguntas** ou um ou mais agrupamentos. **Código** e **Nome** são obrigatórios; **Prazo** e **Dimensões que este ciclo vai reportar**, opcionais → **Abrir auditoria**. O ciclo nasce **rascunho**.

2.     **Conferir e lançar**: o rascunho diz quantas pessoas o ciclo alcança; **+ alvo** acrescenta outro alvo com as mesmas perguntas. **Lançar** põe o ciclo em execução. Rascunho errado sai em **Apagar** → **Apagar em definitivo**.

3.     **Despachar**: em **Ondas de disparo**, **Nova onda** → código e *O que esta onda cobre* → **Criar**; marque as perguntas → **Incluir na onda**; escolha a **Equipe que responde…** → **Disparar**. **Encerrar onda** fecha a rodada.

4.     **Revisar**: filtre as respostas (**sem resposta**, **esperando revisão**, **aprovadas**, **devolvidas**) e use **Aprovar** ou a seta de devolver, que pede *Por que está devolvendo?* → **Devolver**. Resposta aprovada só volta a mudar por **Devolver para correção**.

5.     **Apurar** calcula o score e levanta os achados; **Fechar ciclo** encerra.

6.     **Cancelar** exige o **Motivo do cancelamento** → **Cancelar o ciclo**. Ciclo encerrado pode ir para **Arquivar** e voltar por **Desarquivar**.

7.     Em qualquer estado: **Respostas (CSV)** e **Relatório do ciclo (PDF)**. Depois de lançado, em **Versões publicadas**: **Elaborar versão** → **Título do documento** (e, opcional, **Observação**) → **Elaborar**; outra pessoa clica **Aprovar**, e o **×** descarta a versão em elaboração. É a mesma seção de **Auditoria em foco** — veja *Versões publicadas*, abaixo.

**Lançar** é recusado sem perguntas materializadas, e depois dele o ciclo não se apaga mais. **Fechar ciclo** é recusado com resposta sem aprovação ou com achado sem plano de ação nem aceite de risco. Quem aprova não pode ser quem respondeu.

**Cada botão pede uma permissão, e a tela mostra isso antes do clique.** Sem a permissão, o botão aparece apagado e o título (e o nome lido pelo leitor de tela) diz qual permissão falta, pelo nome de **Perfis de acesso** — antes a tela oferecia tudo e a pessoa só descobria ao clicar:

| **Botão**                                                                                                           | **Permissão**                                      |
| ------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| **Abrir auditoria**, **Lançar**, **Apagar**, **Lançar como auditoria**, **+ alvo**                                  | auditoria\:abrir (Auditorias — abrir campanha)     |
| **Salvar** a resposta, **Anexar link**                                                                              | auditoria\:responder (Auditorias — responder)      |
| **Aprovar**, devolver, **Apurar**, **Sugerir dimensões**, aceitar ou recusar dimensão                               | auditoria\:revisar (Auditorias — revisar e apurar) |
| **Fechar ciclo**, **Cancelar**, **Arquivar** / **Desarquivar**, **Elaborar versão**, **Aprovar** e descartar versão | auditoria\:fechar (Auditorias — fechar e publicar) |



**Apurar é de quem revisa.** Apurar roda as regras sobre as respostas aprovadas, calcula o score e levanta os achados — é parte de conduzir a revisão, e se refaz quantas vezes for preciso enquanto o ciclo está aberto. Fechar é outro ato: encerra o ciclo, e só passa com todo achado tratado. Por isso são duas permissões. Até 30/09 o catálogo chamava auditoria\:fechar de "apurar e fechar", embora a apuração sempre tenha exigido auditoria\:revisar; os nomes foram corrigidos para dizer o que cada uma permite.

Aceitar e recusar a dimensão sugerida são os únicos que somem em vez de apagar (são ícones dentro da etiqueta); a sugestão continua à vista para quem revisa.

***

### <font color="#15803D">Revisão, devolução e aprovação</font>

O estado de uma resposta anda assim:

:::BlockQuote
pendente → respondida → aprovada        entra no score
&#x20;                    ↘ devolvida → pendente de novo
:::

Quem responde não revisa. A restrição existe também no banco, então não há caminho — nem por API — que a contorne.

**Devolver é o caminho normal**, e não uma punição. A alternativa seria o revisor corrigir a resposta de outra pessoa, e aí a assinatura deixaria de valer. A devolução leva o motivo, e a pergunta volta para a fila de quem respondeu.

Pergunta marcada como exigindo evidência não é aprovada sem anexo.

:::hint{type="info"}
Uma auditoria com tudo respondido e nada revisado tem **score zero**. Não é defeito: só resposta aprovada entra no cálculo.
:::

***

### <font color="#15803D">Auditoria em foco</font>

Uma auditoria de cada vez, inteira: score, cobertura, o que foi respondido e os achados que saíram dela. A lista de auditorias diz quais existem; esta tela diz como foi uma delas.

1.     À esquerda, *Procurar por nome, alvo ou norma*. A lista vem da pior nota para a melhor; clique numa auditoria para vê-la.

2.     Leia **Score**, **Cobertura** (abaixo de 70%, a nota é uma amostra pequena), **Respostas** (e quantas foram aprovadas por outra pessoa) e **Achados**, com **Achados por severidade** e a lista **Achados deste ciclo**, que marca o que está *sem tratamento*.

3.     Em **Versões publicadas**: **Elaborar versão** → **Título do documento** → **Elaborar**. A versão nasce em elaboração e só vale depois de outra pessoa clicar **Aprovar**; o **×** a descarta.

A tela só lê o ciclo: responder, apurar e fechar se fazem em **Auditorias**. As versões publicadas são a exceção, e são a mesma seção das duas telas (veja a seguir).

***

### <font color="#15803D">Versões publicadas</font>

A seção **Versões publicadas** é uma só, e aparece igual em **Auditorias** (no detalhe do ciclo) e em **Auditoria em foco**: os mesmos botões, as mesmas regras e a mesma permissão. Antes eram duas seções com nomes diferentes (*Publicações* numa tela, *Versões publicadas* na outra) e regras diferentes para a mesma coisa.

1.     **Elaborar versão** → **Título do documento** (em branco usa o nome do ciclo) e **Observação** (opcional, o que mudou desde a anterior) → **Elaborar**. A versão nasce **em elaboração**.

2.     Outra pessoa clica **Aprovar**: a versão passa a **aprovada · vigente**, e a anterior aprovada vira **substituída** — continua na lista, porque é ela que responde como o registro estava numa data passada. Quem elaborou vê **Aprovar** apagado: quem elaborou não aprova.

3.     O **×** descarta a versão em elaboração, depois de perguntar (**Descartar** confirma; o foco nasce no **Cancelar**). Aprovada e substituída não se apagam.

Regras: elaborar, aprovar e descartar exigem auditoria\:fechar (sem ela os botões ficam apagados, com o motivo); rascunho não se publica — **Elaborar versão** fica apagado até o ciclo ser lançado; só cabe uma versão em elaboração por vez. O conteúdo não é copiado: o que prova o que foi publicado é o **resumo das respostas**, calculado pelo servidor na hora de elaborar (o prefixo aparece ao lado da versão). Quando as respostas mudam depois da versão vigente, a seção avisa que o documento já não descreve o que está no ar — elabore uma nova. O **Relatório do ciclo (PDF)** continua sendo emitido à parte, pelo botão de exportar.

***

### <font color="#15803D">Apuração e fechamento</font>

*Apurar* roda as regras e levanta os achados. *Fechar ciclo* só passa quando **nenhum achado está sem tratamento**: cada um precisa de plano de ação ou de aceite de risco formal.

Para o que uma resposta faz nascer além do achado de fábrica — não conformidade ou risco por tipo de alvo, tema ou faixa de pontuação —, veja Automação de respostas.

***

### <font color="#15803D">Score e cobertura</font>

O score é a média ponderada das respostas **aprovadas**. A cobertura diz quanto do aplicável já foi avaliado. Abaixo de 70% de cobertura o score aparece marcado como não conclusivo — dez respostas conformes em cem perguntas não são cem por cento.

***

### <font color="#15803D">A pergunta que não se aplica</font>

Uma pergunta pode declarar **quando ela deve ser feita**. "Qual o mecanismo de transferência internacional?" só faz sentido para quem acabou de dizer que há transferência internacional; "qual a hipótese do Art. 11?" só faz sentido onde há dado sensível.

A condição é escrita na mesma linguagem das regras, no cadastro da pergunta, e vale por alvo: a mesma pergunta é feita a um e não a outro. Quando ela é falsa, três coisas acontecem juntas, e é a combinação que importa:

•     a pergunta **sai do formulário**, recolhida num aviso que diz quantas são e por quê — recolhida e não escondida, porque quem audita precisa conferir que ela existia;

•     ela **sai da cobertura**. Esta é a metade que se esquece: mantida no denominador, um ciclo integralmente respondido nunca chegaria a 100%, e o aviso de "score não conclusivo" não sairia nunca;

•     ela **não vira achado por estar em branco**, e não segura o fechamento do ciclo. Campo vazio é o estado normal de uma pergunta que não deveria ter sido feita.

A decisão é recalculada a cada leitura, e não gravada. Responder "sim" à pergunta que a condição observa traz a dependente para a tela no mesmo instante; mudar para "não" a tira de novo.

:::hint{type="info"}
Se a condição estiver mal escrita, a pergunta **é feita**. Esconder por erro produziria um buraco silencioso: ninguém responde, ninguém cobra, e a cobertura sobe.
:::

***

### <font color="#15803D">Pré-auditoria, origens múltiplas e dimensões</font>

Um ciclo pode nascer de várias normas e temas ao mesmo tempo, pode ser um levantamento prévio a ser comparado com o oficial depois, e as respostas podem ser lidas por eixo de negócio. Isso está em Pré-auditoria e em Dimensões.

***

### <font color="#15803D">O ciclo de vida</font>

| **Estado**      | **O que se pode fazer**               |
| --------------- | ------------------------------------- |
| **Rascunho**    | montar, corrigir e **apagar**         |
| **Em execução** | responder e revisar                   |
| **Em revisão**  | apurar, tratar achado, fechar         |
| **Encerrada**   | consultar                             |
| **Cancelada**   | consultar, com o motivo registrado    |
| **Arquivada**   | sai das listas, o histórico permanece |



**Lançar é o ponto sem volta da exclusão.** Antes disso o ciclo é rascunho e pode ser apagado inteiro — é a saída para quem montou errado. Depois, não: um ciclo lançado foi despachado a pessoas, que responderam, e apagá-lo apagaria o trabalho delas. O que resta é cancelar, com motivo, e arquivar.

Rascunho não aceita resposta. Um ciclo que ainda está sendo montado e já recebe resposta produz respostas a perguntas que podem sair da lista antes de alguém lançar.

***

### <font color="#15803D">Cada alvo responde o seu</font>

Quem responde vê **as respostas do seu alvo e mais nada**; quem conduz o ciclo vê tudo, porque consolidar exige. Duas coisas alcançam uma resposta: a **atribuição** — ela foi despachada para mim ou para a minha área — e o **alvo**, quando o alvo tem a minha área como responsável. A segunda existe porque auditoria sem onda não tem atribuição nenhuma, e sem ela quem responde abriria o ciclo e não veria pergunta alguma.

Isso importa pouco num ciclo de quinze filiais da mesma empresa e importa muito num programa de governo: num tenant com mil e trezentos órgãos, leitura aberta significaria um ministério lendo o diagnóstico de segurança de uma agência.

***

### <font color="#15803D">Uma auditoria, vários alvos</font>

O que delimita uma auditoria é **quem responde e o escopo declarado**, e não quantos itens ela avalia. Quinze atividades da mesma área, respondidas pela mesma equipe, com o mesmo questionário, são um trabalho só — e virar quinze ciclos infla a lista de Auditorias, multiplica o acompanhamento e faz a mesma coisa parecer quinze coisas.

O ciclo comporta isso sozinho. Ele tem um alvo principal e recebe os demais em **Alvos**, e cada alvo novo recebe uma cópia do conjunto de perguntas. A resposta guarda o alvo dela, então as quinze linhas convivem sem se sobrescrever, e o resultado da área é a média ponderada dos alvos.

Alvo só se remove antes do lançamento. Depois, o que existe ali é registro: apagar o alvo apagaria respostas aprovadas e os achados que saíram delas.

***

### <font color="#15803D">A resposta consolidada e a visão por pergunta</font>

Com vários alvos, a nota consolida sozinha — é a média ponderada, subindo a hierarquia. A pergunta não: o Jurídico e a TI, com três equipes cada, dão seis respostas a cada pergunta, e "o que a organização respondeu a P-012?" tem mais de uma resposta honesta. Quem decide qual vale é quem abre a auditoria.

**A regra é escolhida na abertura**, em **Resposta consolidada (auditoria com vários alvos)**:

| **Regra**                    | **A resposta da pergunta é**                                                                                                               |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| **A pior resposta** (padrão) | a de menor pontuação — a organização está tão bem quanto a equipe mais fraca                                                               |
| **A média**                  | a média das pontuações, mostrada pela opção de pontuação mais próxima (no empate, a menor) e pelo próprio número: "Maior parte (média 70)" |
| **A maioria**                | a resposta mais frequente; no empate, a de menor pontuação                                                                                 |



Contam só os alvos que **responderam**: sem resposta, "não se aplica" e opção fora do cálculo ficam de fora. Pergunta que não pontua (contexto, texto) consolida pela maioria. A regra se troca na própria visão por pergunta enquanto o ciclo não encerrou (auditoria\:abrir); fechado, cancelado ou arquivado, ela fica como estava — o relatório reemitido precisa dizer o mesmo.

:::hint{type="info"}
A resposta consolidada é **leitura**. Ela não entra em nota, maturidade, cobertura nem aprovação, que continuam consolidando como antes. Trocar a regra não muda número nenhum do ciclo.
:::

**Visão por pergunta.** Na auditoria de mais de um alvo, acima das respostas aparecem duas abas: **Respostas por alvo**, que é como se responde, e **Visão por pergunta**, que é como se consolida (exige auditoria\:abrir, como toda leitura que mostra os alvos lado a lado):

1.     No alto, a regra em vigor, com o seletor para trocá-la.

2.     **Só divergentes**, **Área** (o alvo de cima de cada equipe — o campo **Dentro de**) e **Ordem** (*a do questionário* ou *maior divergência primeiro*).

3.     Até **30 alvos**, cada pergunta é uma linha e cada alvo uma coluna, com a resposta e a pontuação de cada um, a **Resposta consolidada** e a **Divergência**. Acima de 30, uma coluna por alvo vira uma tabela que ninguém lê: a pergunta mostra **quantos alvos deram cada resposta**, quantos responderam e a consolidada.

4.     A lista é paginada (cinquenta perguntas por página) e a conta é feita no banco — uma auditoria de mil e trezentos alvos com trezentas perguntas abre como uma de seis.

**Divergência** é os alvos responderem diferente, ou haver **50 pontos ou mais** entre a menor e a maior pontuação. Ela aparece com ícone e a palavra **Diverge** (e a distância em pontos), e não só com cor.

O **PDF da auditoria** de vários alvos (**Exportar PDF**) traz, logo depois da capa, a seção **Resposta consolidada**: uma linha por pergunta, com a regra dita no alto, quantos alvos responderam e se a pergunta diverge. O PDF de um alvo só, e o de quem não conduz o ciclo, continuam como eram.

**O painel P-CONSOLIDACAO.** Toda instalação tem, já publicado em **Painéis**, o painel de fábrica **Consolidação por área e equipe**. Escolha a auditoria no filtro do painel (**Auditoria**) e ele mostra:

•     **Perguntas com divergência entre equipes** — quantas;

•     **Pontuação por área** — a média das pontuações que contam, por alvo de cima;

•     **Distribuição das respostas consolidadas** — quantas perguntas ficaram em cada resposta;

•     **Pontuação por equipe, pior primeiro**;

•     **Perguntas divergentes, maior distância primeiro**;

•     **Pergunta × equipe (até 30 equipes)** — o mapa de calor das pontuações; acima de 30 equipes ele fica vazio e vale o quadro seguinte, **Respostas por pergunta (mais de 30 equipes)**, com quantas equipes deram cada resposta.

Equipe que ainda não respondeu não aparece nos quadros de pontuação — uma média sem resposta nenhuma viraria zero, e zero é a pior nota. Os quadros são widgets comuns, sobre as fontes **Respostas por área e equipe** e **Perguntas consolidadas** do construtor: o painel pode ser copiado, editado e ganhar quadros como qualquer outro (ver Painéis e construtor).

***

### <font color="#15803D">A prévia de alcance</font>

Antes de lançar, a tela diz quantas pessoas o ciclo alcança. Ela **sobe a hierarquia** até encontrar quem responde: o alvo de um ciclo costuma ser um processo, e processo não espelha equipe — quem espelha é a área acima dele. Olhando apenas o próprio alvo, a prévia dizia "alcança 0 pessoas" para um ciclo que estava sendo despachado corretamente, e quem abre o ciclo desiste de lançá-lo por causa de um número errado.

[title] GRCS
[path] Aplicações/

:::Iframe{iframeHeight="0" code="<div id=&#x22;grcs-lp-root&#x22;></div>&#xA;<script>&#xA;(function () {&#xA;  var root = document.getElementById('grcs-lp-root');&#xA;  if (!root) return;&#xA;&#xA;  var BASE = 'https://docs.citsmart.com/';&#xA;  var groups = [&#xA;    { t: 'Primeiros passos', items: [&#xA;      [1, 'O que é a plataforma', '1-o-que-e-a-plataforma'],&#xA;      [2, 'Como usar (de ponta a ponta)', '2-como-usar-de-ponta-a-ponta']&#xA;    ]},&#xA;    { t: 'Estrutura e catálogo', items: [&#xA;      [3, 'Áreas, grupos, usuários e perfis', '3-areas-grupos-usuarios-e-perfis'],&#xA;      [4, 'Alvos e escopo', '4-alvos-e-escopo'],&#xA;      [5, 'Catálogo e frameworks', '5-catalogo-e-frameworks'],&#xA;      [6, 'Agrupamentos', '6-agrupamentos']&#xA;    ]},&#xA;    { t: 'Auditoria', items: [&#xA;      [7, 'Auditoria, ondas e respostas', '7-auditoria-ondas-e-respostas'],&#xA;      [8, 'Responder uma auditoria', '8-responder-uma-auditoria'],&#xA;      [9, 'Disparo em escala e painel do framework', '9-disparo-em-escala-e-painel-do-framework'],&#xA;      [10, 'Pré-auditoria', '10-pre-auditoria']&#xA;    ]},&#xA;    { t: 'Tratamento e acervo', items: [&#xA;      [11, 'Não conformidade e risco', '11-nao-conformidade-e-risco'],&#xA;      [12, 'Continuidade e monitoramento', '12-continuidade-e-monitoramento'],&#xA;      [13, 'Acervo de documentos', '13-acervo-de-documentos']&#xA;    ]},&#xA;    { t: 'Análise e resultados', items: [&#xA;      [14, 'Painéis e construtor', '14-paineis-e-construtor'],&#xA;      [15, 'Murais e televisão', '15-murais-e-televisao'],&#xA;      [16, 'Resultado por hierarquia', '16-resultado-por-hierarquia'],&#xA;      [17, 'Dimensões', '17-dimensoes'],&#xA;      [18, 'Exportação', '18-exportacao'],&#xA;      [19, 'IMR — Instrumento de Medição de Resultado', '19-imr-instrumento-de-medicao-de-resultado']&#xA;    ]},&#xA;    { t: 'Automação e integrações', items: [&#xA;      [20, 'Área de automação', '20-area-de-automacao'],&#xA;      [21, 'Eventos e conectores', '21-eventos-e-conectores'],&#xA;      [22, 'Automação de respostas', '22-automacao-de-respostas'],&#xA;      [23, 'Avisos e e-mail', '23-avisos-e-e-mail']&#xA;    ]},&#xA;    { t: 'Atendimento', items: [&#xA;      [24, 'Portal, caso e ciclo de vida', '24-portal-caso-e-ciclo-de-vida'],&#xA;      [25, 'Catálogo de serviços e política de atendimento', '25-catalogo-de-servicos-e-politica-de-atendimento']&#xA;    ]},&#xA;    { t: 'Inteligência artificial', items: [&#xA;      [26, 'Modelos de linguagem, parecer prévio e sandbox', '26-modelos-de-linguagem-parecer-previo-e-sandbox'],&#xA;      [27, 'O assistente', '27-o-assistente']&#xA;    ]},&#xA;    { t: 'Administração e plataforma', items: [&#xA;      [28, 'Integração com o diretório', '28-integracao-com-o-diretorio'],&#xA;      [29, 'Sessão, trilha e contas de serviço', '29-sessao-trilha-e-contas-de-servico'],&#xA;      [30, 'Como a instalação chama quem é auditado', '30-como-a-instalacao-chama-quem-e-auditado'],&#xA;      [31, 'Idiomas', '31-idiomas'],&#xA;      [32, 'Layout e aparência', '32-layout-e-aparencia'],&#xA;      [33, 'Acessibilidade', '33-acessibilidade'],&#xA;      [34, 'Instalar como aplicativo', '34-instalar-como-aplicativo'],&#xA;      [35, 'Qualidade e a cadeia de testes', '35-qualidade-e-a-cadeia-de-testes']&#xA;    ]}&#xA;  ];&#xA;&#xA;  var BLUE = '#0C447C';&#xA;  var BLUE_LIGHT = '#E8F0F9';&#xA;  var BORDER = '#D5DEE8';&#xA;  var TEXT = '#1F2A37';&#xA;  var MUTED = '#5B6B7C';&#xA;  var FONT = 'font-family:inherit;';&#xA;&#xA;  function pad(n) { return n < 10 ? '0' + n : '' + n; }&#xA;  function norm(s) { return s.toLowerCase().normalize('NFD').replace(/[̀-ͯ]/g, ''); }&#xA;&#xA;  var total = 0;&#xA;  groups.forEach(function (g) { total += g.items.length; });&#xA;&#xA;  var html = '';&#xA;  // Cabeçalho&#xA;  html += '<div style=&#x22;' + FONT + 'background:' + BLUE + ';border-radius:12px;padding:32px 28px;margin:0 0 20px 0;color:#fff;&#x22;>';&#xA;  html += '<div style=&#x22;font-size:12px;letter-spacing:1.5px;text-transform:uppercase;opacity:.8;margin-bottom:8px;&#x22;>Documentação do sistema</div>';&#xA;  html += '<div style=&#x22;font-size:30px;font-weight:700;line-height:1.2;margin-bottom:8px;&#x22;>GRCS</div>';&#xA;  html += '<div style=&#x22;font-size:16px;line-height:1.5;font-weight:600;margin-bottom:6px;&#x22;>Manual completo da plataforma, por módulo e por tela.</div>';&#xA;  html += '<div style=&#x22;font-size:14px;line-height:1.5;opacity:.88;max-width:720px;margin-bottom:18px;&#x22;><strong>Escopo:</strong> a plataforma usada pelos clientes (tenants). O console da instalação não faz parte deste documento.</div>';&#xA;  html += '<div style=&#x22;display:flex;flex-wrap:wrap;gap:8px;&#x22;>';&#xA;  html += '<span style=&#x22;font-size:13px;line-height:1.4;padding:5px 12px;border-radius:999px;background:rgba(255,255,255,.14);border:1px solid rgba(255,255,255,.25);&#x22;><strong>Versão do produto:</strong> main ae74f60 (09/10/2026)</span>';&#xA;  html += '<span style=&#x22;font-size:13px;line-height:1.4;padding:5px 12px;border-radius:999px;background:rgba(255,255,255,.14);border:1px solid rgba(255,255,255,.25);&#x22;><strong>Data:</strong> 09/10/2026</span>';&#xA;  html += '<span style=&#x22;font-size:13px;line-height:1.4;padding:5px 12px;border-radius:999px;background:rgba(255,255,255,.14);border:1px solid rgba(255,255,255,.25);&#x22;>' + total + ' tópicos</span>';&#xA;  html += '</div>';&#xA;  html += '</div>';&#xA;&#xA;  // Busca&#xA;  html += '<div style=&#x22;margin:0 0 24px 0;&#x22;>';&#xA;  html += '<input id=&#x22;grcs-lp-search&#x22; type=&#x22;text&#x22; placeholder=&#x22;Buscar tópico…&#x22; aria-label=&#x22;Buscar tópico&#x22; style=&#x22;' + FONT + 'width:100%;box-sizing:border-box;padding:12px 14px;font-size:15px;border:1px solid ' + BORDER + ';border-radius:8px;outline:none;color:' + TEXT + ';background:#fff;&#x22;>';&#xA;  html += '<div id=&#x22;grcs-lp-empty&#x22; style=&#x22;display:none;' + FONT + 'color:' + MUTED + ';font-size:14px;padding:12px 2px;&#x22;>Nenhum tópico encontrado.</div>';&#xA;  html += '</div>';&#xA;&#xA;  // Grupos e cartões&#xA;  groups.forEach(function (g, gi) {&#xA;    html += '<div class=&#x22;grcs-lp-group&#x22; data-g=&#x22;' + gi + '&#x22; style=&#x22;margin:0 0 28px 0;&#x22;>';&#xA;    html += '<div style=&#x22;' + FONT + 'font-size:13px;font-weight:700;letter-spacing:1px;text-transform:uppercase;color:' + BLUE + ';margin:0 0 12px 0;padding-bottom:6px;border-bottom:2px solid ' + BLUE_LIGHT + ';&#x22;>' + g.t + '</div>';&#xA;    html += '<div style=&#x22;display:grid;grid-template-columns:repeat(auto-fill,minmax(260px,1fr));gap:12px;&#x22;>';&#xA;    g.items.forEach(function (it) {&#xA;      html += '<a class=&#x22;grcs-lp-card&#x22; data-q=&#x22;' + norm(pad(it[0]) + ' ' + it[0] + ' ' + it[1] + ' ' + g.t) + '&#x22; href=&#x22;' + BASE + it[2] + '&#x22; style=&#x22;' + FONT + 'display:flex;align-items:center;gap:14px;padding:14px 16px;border:1px solid ' + BORDER + ';border-radius:10px;background:#fff;text-decoration:none;color:' + TEXT + ';transition:all .15s ease;&#x22;>';&#xA;      html += '<span class=&#x22;grcs-lp-num&#x22; style=&#x22;flex:0 0 auto;width:40px;height:40px;border-radius:8px;background:' + BLUE_LIGHT + ';color:' + BLUE + ';font-weight:700;font-size:15px;display:flex;align-items:center;justify-content:center;transition:all .15s ease;&#x22;>' + pad(it[0]) + '</span>';&#xA;      html += '<span style=&#x22;flex:1 1 auto;font-size:15px;font-weight:600;line-height:1.35;&#x22;>' + it[1] + '</span>';&#xA;      html += '<span class=&#x22;grcs-lp-arrow&#x22; style=&#x22;flex:0 0 auto;color:' + MUTED + ';font-size:18px;transition:all .15s ease;&#x22;>&rarr;</span>';&#xA;      html += '</a>';&#xA;    });&#xA;    html += '</div></div>';&#xA;  });&#xA;&#xA;  root.innerHTML = html;&#xA;&#xA;  // Hover via JavaScript (sem CSS global, para não afetar o menu do Archbee)&#xA;  var cards = root.querySelectorAll('.grcs-lp-card');&#xA;  Array.prototype.forEach.call(cards, function (c) {&#xA;    var num = c.querySelector('.grcs-lp-num');&#xA;    var arrow = c.querySelector('.grcs-lp-arrow');&#xA;    function on() {&#xA;      c.style.borderColor = BLUE; c.style.boxShadow = '0 4px 12px rgba(12,68,124,.12)'; c.style.transform = 'translateY(-1px)';&#xA;      num.style.background = BLUE; num.style.color = '#fff';&#xA;      arrow.style.color = BLUE; arrow.style.transform = 'translateX(3px)';&#xA;    }&#xA;    function off() {&#xA;      c.style.borderColor = BORDER; c.style.boxShadow = 'none'; c.style.transform = 'none';&#xA;      num.style.background = BLUE_LIGHT; num.style.color = BLUE;&#xA;      arrow.style.color = MUTED; arrow.style.transform = 'none';&#xA;    }&#xA;    c.addEventListener('mouseenter', on);&#xA;    c.addEventListener('mouseleave', off);&#xA;    c.addEventListener('focus', on);&#xA;    c.addEventListener('blur', off);&#xA;  });&#xA;&#xA;  // Busca&#xA;  var input = document.getElementById('grcs-lp-search');&#xA;  var empty = document.getElementById('grcs-lp-empty');&#xA;  input.addEventListener('focus', function () { input.style.borderColor = BLUE; });&#xA;  input.addEventListener('blur', function () { input.style.borderColor = BORDER; });&#xA;  input.addEventListener('input', function () {&#xA;    var q = norm(input.value.trim());&#xA;    var any = false;&#xA;    Array.prototype.forEach.call(root.querySelectorAll('.grcs-lp-group'), function (grp) {&#xA;      var shown = 0;&#xA;      Array.prototype.forEach.call(grp.querySelectorAll('.grcs-lp-card'), function (c) {&#xA;        var ok = !q || c.getAttribute('data-q').indexOf(q) !== -1;&#xA;        c.style.display = ok ? 'flex' : 'none';&#xA;        if (ok) shown++;&#xA;      });&#xA;      grp.style.display = shown ? 'block' : 'none';&#xA;      if (shown) any = true;&#xA;    });&#xA;    empty.style.display = any ? 'none' : 'block';&#xA;  });&#xA;})();&#xA;</script>"}

:::


[title] O quadro Kanban
[path] Aplicações/Agility/Workspaces e Fundamentos/

:::BlockQuote
Acompanhe o trabalho em colunas, crie e mova cartões, configure limites de WIP e aplique regras de automação ao fluxo.
:::

:::hint{type="info"}
**Pré-requisito:**

Tenha um projeto Kanban com Board principal provisionado e acesso de edição. Um quadro populado do Workspace "Portal de Serviços" é o melhor ponto de partida para observar lanes e cartões reais.
:::

***

O Quadro é a superfície operacional do Kanban: cada coluna (lane) representa um status, e cada cartão representa uma task. O cabeçalho da coluna mostra o título, a contagem de cartões ou o contador do limite de WIP; o cartão pode exibir responsável, Feature (em contexto SAFe), bloqueio, SLA e tempo no status.

Além do arraste, o quadro oferece filtro por responsável, agrupamento em swimlanes, criação de colunas, responsáveis por status e automações. O painel da task concentra os dados editáveis e os vínculos que não cabem no cartão, como descrição, datas, estimativa, custos, dependências, requisitos, documentos e trilha de alterações.

***

### Passo a passo

::::WorkflowBlock
:::WorkflowBlockItem
**Abrir o quadro**

No projeto Kanban, selecione "Quadro". O carregamento busca o Board, sincroniza o status das lanes, carrega os cartões de cada coluna e lê as regras configuradas. Se o projeto for Scrum, o quadro é acessado como "Sprint ativo"; para esta seção, use um projeto cujo modelo seja Kanban.
:::

:::WorkflowBlockItem
**Ler as colunas**

Leia as colunas da esquerda para a direita. Cada lane tem um título, uma alça para reordenar e um menu de ações. A linha inferior de cada coluna traz "Adicionar task"; o trilho entre colunas permite adicionar uma nova coluna na posição desejada. Ao criar uma lane, o status é inferido pela posição e sincronizado com o servidor.
:::

:::WorkflowBlockItem
**Filtrar e agrupar os cartões**

Use o filtro de responsável para ver todos, somente não atribuídos ou uma pessoa específica. No segundo filtro, selecione "Sem agrupamento" ou agrupe por responsável; em Boards associados a um ART também é possível agrupar por Feature. O filtro altera apenas a visualização e não movimenta nem altera os cartões.
:::

:::WorkflowBlockItem
**Criar um cartão**

Clique em "Adicionar task" na lane onde o trabalho deve começar, ou use o botão de nova task no topo. Informe o título obrigatório e, se necessário, a descrição em rich text. Escolha a lane e o responsável; em um contexto SAFe, selecione também a Feature. Início, término e story points são opcionais e alimentam o planejamento e o Gantt.
:::

:::WorkflowBlockItem
Se quiser uma sugestão de estimativa, preencha título e descrição e clique em "Gerar sugestão". A sugestão pode preencher story points e data de término, mostra a confiança e deixa o raciocínio recolhido; você continua podendo editar os valores antes de criar. Um custo inicial também pode ser informado, escolhendo o tipo de lançamento e um valor maior que zero.
:::

:::WorkflowBlockItem
**Editar um cartão pelo quadro**

Clique no título do cartão para abrir o detalhe da task. O cartão riscado indica que está concluído; badges adicionais indicam Feature, responsável, bloqueio, SLA vencido ou tempo de permanência na lane. Use a alça do cartão para iniciar o arraste, sem clicar no link do detalhe por engano.
:::

:::WorkflowBlockItem
**Mover e reordenar trabalho**

Arraste o cartão para outra lane para mudar o status ou para outra posição dentro da mesma lane para mudar a ordem. O quadro persiste a mudança de status e depois grava a ordem compacta das tasks afetadas. Também é possível arrastar a alça da coluna para reordenar as lanes; ao soltar, o quadro recarrega para confirmar o estado persistido.
:::

:::WorkflowBlockItem
**Configurar o limite de WIP**

Abra o menu de três pontos da coluna e escolha "Configurar limite de WIP". Informe o limite da regra de fluxo e salve. O cabeçalho passa a mostrar, por exemplo, "2/3"; quando a quantidade atinge o limite, o contador fica destacado. O limite protege a coluna contra excesso de trabalho iniciado, não apaga nem move cartões que já estão nela.
:::

:::WorkflowBlockItem
**Adicionar automações**

No menu da lane, selecione "Adicionar automação". A galeria pode ser filtrada por Populares, Governança, Fluxo e Integração e possui as abas Navegar, Gerenciar e Webhooks. As regras disponíveis incluem aprovação ao entrar, limite de WIP, campos obrigatórios ao sair, SLA e vínculo de webhook; cada cartão informa seu gatilho (criar, atribuir, entrar ou sair) e a configuração necessária.
:::

:::WorkflowBlockItem
**Configurar responsáveis do status**

Escolha "Responsáveis do status" no mesmo menu para indicar quem responde por uma etapa. Esses responsáveis são diferentes do responsável individual da task e aparecem no cabeçalho da lane; o quadro permite mais de uma pessoa e mostra o primeiro nome seguido da quantidade adicional.
:::

:::WorkflowBlockItem
**Renomear ou criar colunas**

Use "Renomear coluna" para corrigir o título sem perder os cartões, ou o trilho "Adicionar coluna" para inserir uma lane. O nome não pode ficar vazio nem duplicar, ignorando diferenças de maiúsculas e minúsculas. A nova coluna recebe status conforme sua posição e pode ser reorganizada depois.
:::

:::WorkflowBlockItem
**Abrir o painel da task**

No detalhe, a área de contexto liga a task ao Projeto, ao Time com acesso, ao Board e, quando aplicável, à Feature. Na descrição você pode clicar no texto ou no placeholder para editar rich text e salvar ou cancelar. Na lateral, altere responsável, início, término e story points; um valor vazio remove a estimativa.
:::

:::WorkflowBlockItem
**Consultar os vínculos da task**

Ainda no detalhe, consulte custos associados e dependências ("B só inicia quando A conclui"), vincule requisitos do projeto, abra os anexos da task e veja a trilha de quem alterou o quê. Dependências cíclicas são rejeitadas pela API e uma task bloqueada aparece sinalizada no cartão do Board
:::
::::

:::hint{type="success"}
:FontAwesome[]{icon="fa-solid fa-check"} **Verificação**

- As lanes aparecem em ordem e o contador de cada coluna corresponde à quantidade de cartões visíveis.
- Uma task criada aparece na lane escolhida com título, responsável e badges aplicáveis; abrir o título leva ao painel de detalhe.
- Arrastar um cartão muda seu status e, após o recarregamento, a task permanece na nova coluna e na ordem escolhida.
- Uma regra de WIP aparece como contador "quantidade/limite" no cabeçalho e uma automação salva pode ser consultada na aba de gerenciamento.
- O detalhe da task permite salvar descrição, responsável, datas e story points e mostra documentos, custos, dependências e histórico no mesmo contexto.
:::

:::hint{type="warning"}
****:FontAwesome[****]{icon="fa-solid fa-triangle-exclamation"}**&#x20;Erros comuns**

**Movimentação recusada pelo limite de WIP**

Ao tentar entrar em uma coluna que já atingiu seu limite, o quadro mostra o aviso "Movimentação recusada pela política do fluxo" e recarrega o estado anterior. Revise o contador da lane, conclua ou mova um cartão, ou peça uma exceção a quem administra as políticas do Board.

**Movimentação recusada por dependência**

Uma task com dependência ainda não concluída pode ficar bloqueada e a API rejeita o arraste. Abra o detalhe, consulte Dependências e conclua o item predecessor ou remova a relação válida antes de mover.

**Nome de coluna vazio ou duplicado**

O diálogo valida o título antes de salvar. Digite um nome não vazio e diferente das outras lanes; a comparação ignora maiúsculas e minúsculas.

**Coluna não pode ser excluída com cartões**

O diálogo de exclusão informa quantas tasks ainda estão na coluna e mantém o botão desabilitado. Mova os cartões para outra lane antes de tentar excluir.

**Data ou estimativa inválida na task**

Story points aceita valores inteiros de 1 a 100; o início e o término são calendários opcionais. Corrija o valor no painel ou deixe a estimativa vazia para removê-la.
:::


[title] Manual do Usuário
[path] Aplicações/ERP/


[title] Backlog e planejamento
[path] Aplicações/Agility/


[title] Sprints e cronograma
[path] Aplicações/Agility/


[title] Inteligência Artificial Integrada ao CITSmart X
[path] Aplicações/

O CITSmart X incorpora recursos avançados de Inteligência Artificial (IA) e aprendizado contínuo, integrados ao ecossistema de gerenciamento de serviços empresariais para promover eficiência operacional, automação inteligente e melhoria contínua dos processos.

A IA da plataforma atua de forma proativa na análise contextual de dados históricos e em tempo real, sendo capaz de sugerir diagnósticos e resoluções com base em informações provenientes de chamados anteriores, base de conhecimento, eventos, mudanças e dados do CMDB. Essas sugestões são apresentadas de forma clara e acessível por meio de notificações automatizadas, respeitando regras e critérios definidos pela organização.

Durante o ciclo de vida dos tickets, a IA também pode propor encaminhamentos adequados dentro dos fluxos de trabalho estabelecidos, além de indicar a necessidade de execução de processos ad hoc, como análise pós-atendimento, registro de lições aprendidas ou ajustes em itens de configuração, sempre que identificada uma oportunidade de aperfeiçoamento.

Além do contexto operacional, os mecanismos de IA contribuem com a antecipação de riscos, identificando tendências de indisponibilidade de serviços ou descumprimento de SLAs, sugerindo ações preventivas baseadas em padrões detectados nos dados históricos.

A IA do CITSmart X também conta com capacidades de reconhecimento em linguagem natural, o que permite interpretar com precisão os registros feitos pelos usuários em diversas fontes de dados, favorecendo uma interação mais fluida e eficaz entre a tecnologia e as pessoas.

Esses recursos evoluem continuamente por meio de aprendizado incremental, preservando a autonomia e a segurança da informação: os dados utilizados no treinamento são exclusivos do ambiente da organização, garantindo a confidencialidade e o controle total por parte do cliente.

A plataforma está preparada para ativação de funcionalidades baseadas em IA Generativa, com capacidade de conexão com modelos de linguagem de mercado (como OpenAI, LLaMA, Gemini entre outros) por meio de APIs abertas, permitindo respostas automatizadas, interações naturais e contextualizadas, e flexibilidade na utilização ou combinação de múltiplos modelos, conforme a necessidade do negócio.

Essa abordagem permite que tanto usuários finais quanto operadores técnicos tenham acesso a uma experiência aprimorada, com respostas inteligentes, contextualizadas e em linguagem natural, fortalecendo a governança digital e a capacidade analítica das organizações.

## Módulo de Análise Preditiva de Disponibilidade de Serviços

A plataforma disponibiliza um módulo de Análise Preditiva de Disponibilidade, que utiliza inteligência artificial para prever riscos de indisponibilidade de serviços, com base em padrões e tendências históricas.

### Como funciona:

O módulo analisa dados provenientes de:

- Tíquetes de incidentes classificados como ""indisponibilidade"";
- Horários e datas de ocorrência, incluindo padrões sazonais e recorrência por dias da semana;
- Categorias de serviço e itens de configuração afetados;
- Base de conhecimento vinculada aos tíquetes resolvidos.
- Com essas informações, a inteligência artificial é capaz de:
- Identificar tendências de falhas por faixa horária, período ou tipo de serviço;
- Calcular a probabilidade de indisponibilidade futura, com base na recorrência e criticidade dos incidentes;
- Fornecer insumos para planejamento preventivo, reestruturação de janelas de manutenção e ajustes de capacidade.

## Módulo de Análise Preditiva de Nível de Serviço (SLA)

O Módulo de Análise Preditiva de Nível de Serviço (SLA) da plataforma utiliza inteligência artificial para identificar padrões históricos e calcular a probabilidade de descumprimento dos acordos de nível de serviço, permitindo uma atuação preventiva por parte das equipes de operação e governança.

### Funcionamento

O módulo analisa o histórico de atendimento de tíquetes, de forma semelhante ao módulo de análise preditiva de disponibilidade, com foco especial em:

- Tempo decorrido entre a abertura e o encerramento de cada tíquete;
- Identificação de SLA violado por tipo de serviço e/ou atividade;
- Classificação dos tíquetes quanto à sua criticidade e categoria.

Com base nesses dados, o sistema é capaz de prever a probabilidade de um novo tíquete violar o SLA, levando em conta padrões comportamentais, horários de atendimento, natureza da solicitação e desempenho anterior.

### Cálculo de Tempo de Indisponibilidade

A métrica de tempo total entre abertura e encerramento de tíquetes classificados como indisponibilidade contribui diretamente para o cálculo real da disponibilidade do serviço, tornando-se um insumo fundamental para:

- Avaliação de acordos de nível de serviço de disponibilidade;
- Ajuste de janelas de manutenção e capacidade de resposta;
- Monitoramento da efetividade das políticas de continuidade.

### Integração com Base de Conhecimento

Além da análise estatística, o módulo utiliza como elemento complementar os artigos da base de conhecimento, que fortalecem a previsibilidade ao fornecer:

- Soluções históricas bem-sucedidas para problemas recorrentes;
- Passos e padrões resolutivos que auxiliam na padronização do atendimento;
- Apoio na construção de probabilidade com base em resoluções já aplicadas.

# Apoio Inteligente ao Diagnóstico com Agentes Cognitivos


Com a integração das soluções Fluxo ESI e Workflow & BPM, a plataforma disponibiliza agentes cognitivos que atuam como assistentes proativos na análise e evolução de tíquetes. Esses agentes são capazes de processar e correlacionar informações automaticamente, oferecendo suporte qualificado à tomada de decisão técnica.

Funcionalidades dos agentes cognitivos:

-
  Ao analisar um tíquete, o agente considera diversos elementos do contexto, como:
  - Descrição do problema reportado;
  - Categorização atribuída;
  - Conhecimentos vinculados ao tíquete;
  - Tíquetes anteriores ou relacionados;
  - Mudanças (RFCs) associadas;
  - Itens de Configuração (ICs) conectados;
  - Ações realizadas previamente, inclusive disparadas por eventos automáticos.

Com base nessa análise, o agente propõe comentários diretamente no tíquete, sugerindo:

- Ações a serem executadas para tratamento ou resolução;
- Hipóteses de causa raiz, com base em padrões históricos e conhecimento registrado;
- Encaminhamentos ou fluxos de trabalho adequados ao cenário detectado.

# Escalonamento de Tíquetes e Sugestão Inteligente de Grupos Executores


A plataforma CITSmart oferece recursos avançados de escalonamento de tíquetes, com base em regras configuráveis de tempo e percentual, além de integrar agentes cognitivos que analisam o conteúdo do tíquete para sugerir, automaticamente, o grupo executor mais adequado.


Escalonamento Automatizado
==========================


O sistema permite configurar regras de escalonamento com base em:

- Tempo absoluto (minutos, horas, dias) desde a abertura do tíquete ou de uma etapa específica do fluxo;
- Percentual de tempo decorrido em relação ao SLA estabelecido para o atendimento.

Com isso, o tíquete pode ser automaticamente:

-
  Redirecionado para outro grupo ou nível de suporte;
- Notificado a gestores ou responsáveis operacionais;
- Tratado com prioridade, conforme criticidade e impacto.


Essas regras disparam ações como redirecionamento, elevação de prioridade ou notificações automáticas, promovendo maior controle sobre o atendimento e mitigando riscos de quebra de SLA.

# Atuação Cognitiva e Sugestão de Grupo Executor

A inteligência artificial da plataforma analisa a descrição do tíquete, categorias e histórico, propondo automaticamente:

- O grupo executor mais adequado, com base nas competências registradas;
- A criação de um subticket do tipo AdHoc, quando a complexidade ou natureza da solicitação assim demandar.
- Esse subticket é gerado para tratar uma ação complementar, específica ou emergente, e é vinculado ao chamado principal para fins de rastreabilidade.

# Categorização Inteligente e Formulários Low-Code


A categorização atribuída ao tíquete, seja manualmente ou pela IA, pode acionar formulários dinâmicos construídos em low-code, permitindo:

- Apresentação de campos específicos conforme a natureza do chamado;
- Geração automática de fluxos personalizados para o tipo de solicitação;
- Execução de ações direcionadas com base nas regras do processo de negócio.

# Apoio Cognitivo à Classificação

Além do escalonamento, a plataforma também conta com agentes cognitivos capazes de interpretar a descrição do tíquete e outros atributos, como:

- Palavras-chave;
- Categorias aplicadas;
- Histórico de atendimentos semelhantes.

Com base nessa análise, o agente sugere grupos executores previamente cadastrados no sistema, que possuem capacidade técnica e perfil adequado para tratar o tíquete, promovendo:

- Redução do tempo de triagem manual;
- Distribuição mais eficiente da carga de trabalho;
- Aumento na assertividade do direcionamento inicial.

# Automação com Inteligência Operacional

A combinação entre regras de escalonamento e inteligência cognitiva melhora significativamente a fluidez do atendimento, reduz gargalos e amplia a governança sobre prazos e responsabilidades.


[title] Portfólios, Programas e Projetos: a hierarquia
[path] Aplicações/Agility/Workspaces e Fundamentos/

:::BlockQuote
Entenda como o Agility organiza investimento, programas e execução em uma árvore flexível, sem exigir que todos os níveis existam.
:::

:::hint{type="info"}
**Pré-requisito:&#x20;**

Tenha acesso a um Workspace e, de preferência, pelo menos um portfólio ou projeto para observar a árvore preenchida.
:::

***

A hierarquia de planejamento do Agility possui três níveis: Portfólio, Programa e Projeto. Um portfólio pode conter programas; um programa pode conter projetos; e um projeto pode ser executável, com tarefas e quadro, ou sintético, usado para agrupar projetos maiores. A regra é flexível: o projeto pode existir sem programa, o programa pode existir sem portfólio e um portfólio pode começar sem nenhum filho.

Essa relação organiza o trabalho sem duplicar o projeto. Metas podem ser conectadas diretamente ao projeto ou herdadas do programa e do portfólio. No diretório global de Portfólios, a árvore também evidencia o backlog SAFe do programa e identifica o método do projeto, facilitando navegar da estratégia para a execução.

***

### Passo a passo

::::WorkflowBlock
:::WorkflowBlockItem
**Abrir a árvore de Portfólios**

Abra "Portfólios" no diretório global para consultar a hierarquia consolidada. A página carrega portfólios, programas e projetos e monta a árvore no cliente: cada Portfólio aparece no primeiro nível, seus Programas são recuados e os Projetos aparecem dentro do Programa correspondente.
:::

:::WorkflowBlockItem
**Interpretar o nível Portfólio**

O Portfólio é o nível de investimento e direção. A linha apresenta o nome e a quantidade de programas. Selecione-a para abrir o painel lateral do nó e consultar seus dados. No contexto de Workspace, o diretório também permite abrir o portfólio operacional com backlog, value streams, orçamento, roadmap e configurações.
:::

:::WorkflowBlockItem
**Criar um Programa e seus objetivos**

No diretório global de Programas, clique em "Novo programa". Informe código e nome obrigatórios, descrição opcional e escolha um Portfólio quando quiser encaixar o programa no primeiro nível; deixar a seleção vazia cria um Programa sem Portfólio. Você também pode acrescentar objetivos de negócio, informando a descrição e os valores planejado e atual. O código é normalizado em maiúsculas e não pode repetir outro Programa.
:::

:::WorkflowBlockItem
**Interpretar o nível Programa**

O Programa agrupa projetos relacionados que perseguem um objetivo comum. A linha mostra a quantidade de projetos; ao selecioná-la, o painel lateral apresenta o programa e suas ações. Um Programa pode ser associado a um Portfólio, mas também pode ficar sem portfólio quando a organização ainda não criou a camada de investimento acima dele.
:::

:::WorkflowBlockItem
**Identificar o backlog do Programa**

Logo abaixo de cada Programa existe uma linha de backlog SAFe. Ela representa o ponto de entrada para o planejamento de épicos, features e histórias daquele programa e não é um quarto nível de hierarquia. Abra a linha quando precisar trabalhar o backlog do trem/programa em vez de abrir um projeto executável.
:::

:::WorkflowBlockItem
**Interpretar o nível Projeto**

O Projeto é onde ficam o quadro e os detalhes de execução: membros, times e ARTs, backlog, sprints ou Gantt conforme o método, riscos, documentos, financeiro e histórico. A etiqueta da linha identifica o método configurado; projetos analíticos são executáveis, enquanto projetos sintéticos funcionam como agrupadores.
:::

:::WorkflowBlockItem
**Usar um Projeto sem Programa**

Na parte inferior da árvore, projetos sem programa aparecem como "Projetos avulsos". Isso não é erro nem impede o uso do quadro: abra a linha para acessar o projeto. Quando a organização precisar agrupá-lo, vincule-o a um Programa pela edição do projeto, sem criar uma cópia.
:::

:::WorkflowBlockItem
**Usar um Programa sem Portfólio**

Programas sem portfólio aparecem em uma seção própria da árvore, ainda com sua linha de backlog e seus projetos filhos. Essa opção é útil para iniciar uma frente de trabalho antes de definir o portfólio de investimento; a ausência do pai não elimina os objetivos, riscos ou projetos já cadastrados.
:::

:::WorkflowBlockItem
**Navegar do Workspace para a hierarquia**

Dentro de um Workspace, entre em "Estratégia > Portfólios" para ver somente os portfólios daquele espaço. Abra uma linha da tabela pelo código ou nome; o portfólio abre diretamente no backlog estratégico. Use "Workspace > Projetos" quando sua intenção for começar pela execução, sem passar pela árvore global.
:::

:::WorkflowBlockItem
**Relacionar metas sem duplicar dados**

Ao conectar uma meta, escolha o nível que realmente a persegue. Uma meta pode ser ligada diretamente ao projeto ou herdada do Programa/Portfólio. Assim, a hierarquia explica a origem estratégica sem copiar a mesma meta para todos os filhos.
:::
::::

:::hint{type="success"}
:FontAwesome[]{icon="fa-solid fa-check"} **Verificação**

- A árvore permite distinguir Portfólio, Programa, backlog do Programa e Projeto por recuo, ícone e etiqueta.
- Projetos sem programa e programas sem portfólio continuam visíveis e navegáveis em suas seções próprias.
- Abrir um projeto leva à execução real (quadro, backlog e demais capacidades), enquanto abrir um portfólio leva à camada estratégica.
- Você consegue explicar qual objetivo pertence ao Portfólio, qual agrupamento pertence ao Programa e quais tarefas pertencem diretamente ao Projeto.
:::

:::hint{type="warning"}
:FontAwesome[]{icon="fa-solid fa-triangle-exclamation"} **Erros comuns**

**Um projeto não aparece dentro do programa esperado**

A árvore agrupa pelo identificador de Programa. Confira a associação do projeto e recarregue o diretório; enquanto estiver sem vínculo, ele ficará na seção de projetos avulsos.

**Esperar que um portfólio seja obrigatório**

Os três níveis são opcionais. Um Programa sem Portfólio e um Projeto sem Programa são estados válidos; crie o nível superior apenas quando houver necessidade real de governança ou investimento.

**Confundir backlog do programa com um projeto**

A linha de backlog usa a etiqueta SAFe e é um acesso ao backlog estratégico do Programa. Para tarefas e execução diária, abra a linha de Projeto correspondente.
:::


[title] Enterprise Low Code
[path] Aplicações/

O <font color="#3b9f0f">**CITSmart X**</font>**&#x20;Low Code** é uma plataforma de desenvolvimento inovadora e estratégica que integra o portfólio de soluções do ecossistema. A plataforma foi projetada para acelerar a criação de aplicações de tecnologia e negócios, oferecendo um ambiente simplificado e seguro que permite tanto a desenvolvedores quanto a usuários menos técnicos a criação de soluções robustas. Com sua interface intuitiva e recursos avançados, o <font color="#3b9f0f">**CITSmart**</font>**&#x20;Low Code** facilita o desenvolvimento rápido de aplicações que atendem de forma eficaz às demandas operacionais e às necessidades estratégicas das empresas. A plataforma é ideal para impulsionar a transformação digital, permitindo que as organizações respondam rapidamente às mudanças do mercado, aumentem a eficiência de seus processos e melhorem sua capacidade de inovação, tudo isso com uma redução significativa no tempo e custo de desenvolvimento.

[https://docs.citsmart.com/low-code](https://docs.citsmart.com/low-code)

[title] Conheça o CITSmart X
[path] Sobre o CITSmart X/

## Sobre

<font color="#3b9f0f">**CITSmart X**</font> é um ecossistema integrado 100% web, mobile e conversacional, desenvolvido para acelerar a transformação digital nas organizações.

O Ecossistema possui componentes de: Workflow, ITSM/ESM, Low Code, Recursos de Integração de Interoperabilidade, Ominichannel, IA (Inteligência Artificial) e Agilidade. Tudo integrado, permitindo liberdade para evoluir.

O <font color="#3b9f0f">**CITSmart X**</font> é composto por uma malha de aplicações, componentes e serviços conectados como “Legos” (Intelligent Composable Business) por meio dos quais novas soluções e componentes de serviços podem ser criados, gerando novas aplicações e novos valores ao negócio de forma acelerada e escalada.

Tudo isso alinhado ao conceito de Agilidade Corporativa, pois além de todas as capacidades digitais oferecidas, que aceleram operações, a plataforma também oferta meios e capacidades de gestão da agilidade, operações de TI e uma malha de opções tecnológicas para sua instituição atingir o sucesso.

:::hint{type="info"}
<font color="#3b9f0f">**O CITSmartX**</font> não é uma plataforma apenas para a TI, mas sim uma plataforma para Hiperautomação e Transformação Digital, ou seja, o <font color="#3b9f0f">**CITSmart X** </font>não é apenas um novo CITSmart ITSM. É algo com alcance maior que promove a Hiperautomação e a Transformação Digital para áreas de negócio e TI.
:::

O <font color="#3b9f0f">**CITSmartX**</font> é um ecossistema de soluções e opções tecnológicas conectadas que já traz algumas aplicações, são elas:

- **Workflow & Service Management** - anteriormente conhecido como ITSM, esta versão possui características que permite gerenciar serviços no nível corporativo, ou seja, permite gerenciar serviços de toda a organização. Tudo isso é possível em virtude de seu poderoso e flexível workflow (design & orquestração) que permite automatizar vários fluxos de trabalho, processos, serviços e cadeias de valor. Com sua capacidade de se integrar a qualquer ambiente legado e aberto por APIs, a solução de Workflow & Service Management se torna essencial para qualquer empresa que deseja atingir altos níveis de excelência. Para você que é da área de TI, a solução possui as mais altas exigências para gestão e operações de TI.



- **Enterprise Low Code** - é uma plataforma de desenvolvimento (web e mobile) inovadora e estratégica que integra o portfólio de soluções do ecossistema. A plataforma foi projetada para acelerar a criação de aplicações de tecnologia e negócios, oferecendo um ambiente simplificado e seguro que permite tanto a desenvolvedores quanto a usuários menos técnicos a criação de soluções robustas. Com sua interface intuitiva e recursos avançados, o CITSmart Low Code facilita o desenvolvimento rápido de aplicações que atendem de forma eficaz às demandas operacionais e às necessidades estratégicas das empresas. Com o Low Code você criar novas aplicações, aprimora aplicações existentes, dá vida e modernização a legados, bem como faz integração de todo o seu parque tecnológico.



- **Enterprise Agility Management** - O **Agility** é uma plataforma de gerenciamento de atividades que se destaca por sua simplicidade e agilidade, proporcionando uma maneira eficaz e intuitiva de administrar projetos. Desenvolvido com o objetivo de facilitar o dia a dia das equipes, o **Agility** oferece uma gama completa de recursos que permitem **organizar, monitorar e delegar tarefas de forma eficiente**, seja em projetos coletivos ou em atividades individuais. A plataforma é fundamentada em metodologias comprovadas, como **Kanban e SAFe (Scaled Agile Framework)**, que são reconhecidas por sua eficácia na gestão ágil de projetos.



- **AIOPS - inteligência artificial para operações** - é uma plataforma de recursos de inteligência artificial (IA), com modelos de aprendizado de máquina, para automatizar e simplificar o gerenciamento de serviços, operações de TI e fluxos de trabalho operacionais. Ela fornece uma visão 360º de toda a unidade de um datacenter (on-premises, nuvem ou híbrida). Gerencia ativamente eventos e incidentes, bem como realiza monitoramento suportado por IA, e executa automações através da base de conhecimento acionável, topologia automática e auto recuperação de ambientes ou equipamentos.&#x20;



- **ChatBots e Supervisores Cognitivos (CITBots)** - é uma plataforma de assistentes virtuais “omnichannel”, com inteligência cognitiva e online que possibilita agilizar o atendimento e operações aos usuários e clientes. Com ele é possível solicitar serviços comuns do dia a dia, como aberturas de chamado e Chat online integrado com os principais canais de mensagerias existentes no mercado, como: “whatsapp”, “telegram”, “slack”, “facebook messenger”, “webchat”, dentre outros. A plataforma também permite realizar a gestão e orquestração de atividades do dia de operadores e demais áreas de negócios com seu motor cognitivo.



- **ERP -&#x20;**&#x20;Plataforma de gestão empresarial que centraliza os processos fiscais, financeiros, contábeis, de compras, estoque e vendas da organização, com módulos complementares para ativos, frota, orçamento, despesas corporativas e folha de pagamento. Integra ainda inteligência artificial (AIOps, chatbots AURA), APIs e business intelligence, cobrindo todo o ciclo operacional da empresa em um único sistema.



- **Agility -&#x20;**&#x20;Plataforma de gestão ágil empresarial que organiza projetos, times e portfólios em um workspace colaborativo, com quadros visuais nos modelos kanban, scrum, tradicional ou SAFe. Reúne também controle financeiro de projetos, análise de rentabilidade e gestão em escala via ARTs, dando visão estratégica de metas, produtos e releases.


[title] PI Planning e iterações
[path] Aplicações/Agility/SAFe — Trens ágeis/

:::BlockQuote
Crie e acompanhe o Planning Interval do ART, sua cadência, etapas de condução e o Planning Board que distribui Features por Time e iteração.
:::

:::hint{type="info"}
**Pré-requisito:**

Abra um ART com permissão de edição para criar PIs. O ART Cidadão Digital já possui os PIs 2027.1, 2026.3, 2026.2 e 2026.1 para consulta.
:::

***

O Planning Interval (PI) é o ciclo de planejamento do ART. Ele concentra a cadência de iterações, os objetivos dos Times, a capacidade planejada, as dependências entre Features e a medição de previsibilidade. No Agility, o fluxo canônico fica dentro de ARTs > Planning Intervals; o antigo atalho separado PI Planning agora redireciona para essa mesma lista.

O PI Planning Board é a cerimônia operacional: as linhas representam os Times, as colunas representam as iterações e os cartões são Features do Backlog do ART. A tela também registra dependências entre Features, risco, data necessária, owner e descrição. A leitura conjunta do detalhe do PI, da preparação e do board mostra o que foi criado e o que ainda precisa ser decidido.

***

::::WorkflowBlock
:::WorkflowBlockItem
**Abrir Planning Intervals**

Na navegação do ART, clique em Planning Intervals. A lista exibe cada PI com nome, data de início, número de iterações, capacidade, progresso, status e ações Preparação e Planning Board. No ART de exemplo, há PIs preenchidos para vários ciclos; abra uma linha pelo nome para consultar seu detalhe.


:::

:::WorkflowBlockItem
**Criar um PI do ART**

Clique em Novo Planning Interval. No diálogo, informe o Nome do PI e a data de início. O campo ART fica somente leitura porque o PI é criado no trem que você está consultando. A cadência de tamanho da iteração e quantidade de iterações vem do ART e fica bloqueada nessa entrada, evitando dois calendários divergentes no mesmo trem.
:::

:::WorkflowBlockItem
**Revisar a cadência antes de salvar**

Confira o resumo de semanas, o total de iterações e a data. No cadastro global legado existiam também seleção de programa e produto e os presets de 3 a 6 iterações; esses campos não são usados na criação canônica de um PI dentro de ART. Clique em Criar PI Planning para salvar.
:::

:::WorkflowBlockItem
**Abrir o detalhe do PI**

Na tabela, clique no nome do PI. O detalhe mostra o status, os cartões de progresso, capacidade, objetivos e previsibilidade e o cartão de ciclo de vida. Os links Preparar, Planejar, Comprometer, Tratar riscos, Resolver bloqueios, Iniciar o PI e Fechar funcionam como mapa da cerimônia e levam cada decisão à tela correspondente.
:::

:::WorkflowBlockItem
**Entender iterações e capacidade**

A quantidade de iterações exibida no PI é a cadência definida no ART; a capacidade é acompanhada por Time × iteração na preparação. No Planning Board, cada coluna de iteração recebe Features e a capacidade é mostrada no resumo do board. Use essas duas visões para conferir que o número de ciclos e os pontos planejados são compatíveis.
:::

:::WorkflowBlockItem
**Avançar o ciclo com segurança**

No cartão de ciclo de vida, o Agility oferece somente o próximo avanço legal. Pendências de prontidão, objetivos, riscos ou dependências aparecem ao lado do botão e são links para correção. Quando a próxima etapa é iniciar, clique em Iniciar o PI; quando é concluir, clique em Concluir PI. Um PI concluído oferece o caminho para Inspect & Adapt.
:::

:::WorkflowBlockItem
**Abrir o Planning Board**

Clique em Planning Board na linha do PI ou no menu do ART. A tela informa o PI no título, total de objetivos, Features, dependências e percentual de capacidade. O seletor Filtrar por Time reduz o quadro a um único Time ou mantém Todos os Times.
:::

:::WorkflowBlockItem
**Ler e mover Features**

No Plano integrado do ART, cada linha identifica um Time e cada coluna uma iteração. Features ainda não planejadas ficam em Não planejado; os cartões mostram código e título e podem ser arrastados para a célula Time × iteração. O quadro separa planejamento do ART da execução operacional do Board do projeto.
:::

:::WorkflowBlockItem
**Registrar uma dependência da cerimônia**

Na seção de dependências, escolha a Feature de Origem e a Feature de Destino, classifique o Risco (por exemplo, risco médio), informe a Data necessária, selecione o Owner da dependência e descreva o acordo. Clique em Registrar dependência. A dependência passa a fazer parte do PI e também aparece nas verificações de prontidão e nas pendências de transição.
:::

:::WorkflowBlockItem
**Entender os caminhos global e canônico**

O caminho \`/workspaces/\{workspaceId}/arts/\{artId}/pi-planning\` é compatibilidade e redireciona para a lista canônica de \`/pis\`, preservando a consulta. As variantes globais \`/pi-planning\`, \`/pi-planning/\{piId}\` e \`/pi-planning/\{piId}/iterations/\{iterationId}\` pertencem ao catálogo legado e, no ambiente atual, redirecionam para \`/workspaces\`; não use esses endereços para iniciar um novo fluxo. A criação e consulta devem começar no Workspace e no ART.
:::
::::

![](https://itsm-labdev.cloud4biz.com/agility-v2/docs/screens/05-art-planning-intervals.webp "Lista preenchida de Planning Intervals do ART, com PIs, datas, preparação e Planning Board")

![](https://itsm-labdev.cloud4biz.com/agility-v2/docs/screens/05-pi-planning-board.webp "Planning Board do PI 2026.3 com Times em linhas, Features não planejadas e filtro de Time")

:::hint{type="success"}
:FontAwesome[]{icon="fa-solid fa-check"} **Verificação**

- O PI aparece na tabela do ART com nome, data, cadência, progresso e status.
- O detalhe do PI mostra métricas de progresso, capacidade, objetivos e previsibilidade e oferece apenas o próximo avanço permitido.
- O Planning Board exibe pelo menos uma Feature real em uma linha de Time ou em Não planejado e calcula os cartões de resumo.
- Uma dependência salva reaparece nas pendências do ciclo e na área de dependências do board.
- O atalho legado do ART leva à lista \`/pis\`, e o atalho global antigo leva ao diretório de Workspaces.
:::

:::hint{type="warning"}
****:FontAwesome[****]{icon="fa-solid fa-triangle-exclamation"}**&#x20;Erros comuns**

**Nome ou data de início não preenchidos**

O diálogo de PI exige nome, ART e data. Preencha os campos obrigatórios antes de clicar em Criar PI Planning; a mensagem de validação fica no próprio diálogo.

**Cadência diferente do ART**

Na criação dentro de um ART, tamanho de sprint e quantidade de iterações são bloqueados de propósito. Ajuste a cadência no cadastro do ART quando o próximo PI precisar de outro calendário.

**Botão de avanço não aparece ou retorna uma pendência**

O serviço oferece somente a transição seguinte e a tela lista o que falta. Abra o link de prontidão, objetivos, riscos ou dependências exibido ao lado do botão; não tente pular estados manualmente.

**Feature não aparece na célula esperada**

O board separa Features não planejadas por PI e Features já alocadas. Verifique o filtro Filtrar por Time, selecione a Feature correta e arraste o cartão para a célula do Time e da iteração desejados.

**A rota global abre Workspaces**

Isso é o comportamento esperado para as rotas legadas. Escolha o Workspace Portal de Serviços, entre em ARTs, abra o ART e use Planning Intervals para chegar ao PI atual.
:::


[title] Readiness e Objectives do PI
[path] Aplicações/Agility/SAFe — Trens ágeis/

:::BlockQuote
Prepare o PI com checklist, escopo, capacidade, dependências e riscos; depois registre objetivos do ART ou dos Times com valor de negócio e situação.
:::

:::hint{type="info"}
**Pré-requisito:**

Tenha um PI no ART. O roteiro usa PI 2026.3 na Preparação e o PI de planejamento atual para a aba Objetivos; ambos têm dados reais no Workspace Portal de Serviços.
:::

***

Readiness é a preparação verificável antes da cerimônia do PI. A tela combina um checklist com responsável e destino de correção, agenda do evento, capacidade por Time e iteração, Features candidatas, dependências e riscos. Ela evita que o ART avance apenas por uma afirmação textual de que está pronto.

Objectives são os resultados esperados do PI. Um objetivo pode ser do ART ou de um Time, tem título, descrição, valor de negócio de 0 a 10 e situação (como Rascunho, Comprometido, Alcançado ou Descartado). A mesma ficha de objetivos aparece na Preparação e na aba Objetivos, que é o endereço durável para revisar e editar os compromissos.

***

### Passo a passo

::::WorkflowBlock
:::WorkflowBlockItem
**Abrir a preparação do PI**

Na lista Planning Intervals, clique em Preparação na linha do PI escolhido; o caminho termina em \`/pis/\{piId}/readiness\`. O cabeçalho identifica o PI e oferece Revisar escopo candidato para abrir o Backlog do ART.
:::

:::WorkflowBlockItem
**Ler os indicadores de Readiness**

Os quatro cartões mostram o percentual do checklist, Times com capacidade, Features candidatas e Itens de agenda. O valor do checklist exibe itens completos de um total; portanto, 0% e 0/0 significam checklist ainda não cadastrado, não aprovação automática.
:::

:::WorkflowBlockItem
**Inspecionar um item do checklist**

Na seção Checklist de readiness, clique em uma linha. O diálogo detalha o que precisa estar pronto, causa ou detalhe, categoria, responsável e destino de correção. Itens medidos pelo sistema recebem o selo Medido e não oferecem uma alteração manual que seria recusada pelo servidor.
:::

:::WorkflowBlockItem
**Cadastrar um item de prontidão**

No formulário Novo item de prontidão, preencha O que precisa estar pronto e Causa / detalhe, escolha uma Categoria (Contexto e objetivos, Pessoas, Escopo ou Capacidade) e, se aplicável, selecione o Responsável. Clique em Adicionar item. O destino de correção é derivado da categoria e aparece no formulário, garantindo um link direto para a tela certa.
:::

:::WorkflowBlockItem
**Acompanhar agenda, escopo e dependências**

A Agenda do evento lista dia, horário, duração e facilitador quando há itens cadastrados. Em Candidate Scope, confira as Features candidatas e o WSJF e use o link para o Backlog. O cartão de Dependências resume abertas e resolvidas e abre o Planning Board na âncora de dependências.
:::

:::WorkflowBlockItem
**Conferir capacidade por Time e iteração**

Em Capacidade por Time, cada linha mostra Time, iteração, pontos alocados e pontos disponíveis. Quem edita pode ajustar Pontos disponíveis e salvar; a aplicação rejeita valores negativos e valores menores que o alocado. Quando uma combinação ainda não tem linha, use o formulário de abertura de capacidade para escolher Time e iteração.
:::

:::WorkflowBlockItem
**Conferir riscos antes do evento**

O cartão Riscos identifica riscos não classificados e não resolvidos e leva à aba Riscos ROAM. Um risco aceito já representa uma decisão; a pendência de cerimônia é o risco que ainda está sem classificação ROAM, não todo risco que permanece aberto.
:::

:::WorkflowBlockItem
**Abrir a aba Objetivos**

Clique em Objetivos no menu do ART ou no link Abrir a aba Objetivos dentro do card embutido. A página resolve o PI de planejamento e, na falta dele, o PI atual; os cartões superiores mostram objetivos concluídos de um total e previsibilidade.
:::

:::WorkflowBlockItem
**Criar um objetivo**

No formulário Novo objetivo, informe Título e, opcionalmente, Descrição. Defina Valor de negócio entre 0 e 10, selecione Objetivo do ART ou um Time no campo Time e escolha a Situação. Clique em Criar objetivo. O objetivo aparece na lista com o selo BV, o Time ou nível do ART e a situação traduzida.
:::

:::WorkflowBlockItem
**Editar ou remover um objetivo**

Use Editar objetivo na ficha existente para alterar título, descrição, valor, Time e situação; salve pelo botão de edição. O botão de remoção exclui o objetivo após a operação. Na Preparação, o mesmo card é embutido para revisão, mas a aba Objetivos continua sendo o destino principal.
:::

:::WorkflowBlockItem
**Usar os objetivos para conduzir o PI**

Volte ao detalhe do PI e abra Comprometer quando os objetivos estiverem pontuados. O mapa do PI usa objetivos em Rascunho como pendência; objetivos não comprometidos não devem ser tratados como entregas confirmadas. O resultado alimenta a previsibilidade e, depois do fechamento, o Inspect & Adapt.
:::
::::

![](https://itsm-labdev.cloud4biz.com/agility-v2/docs/screens/05-pi-readiness-checklist.webp "Preparação do PI 2026.3 com checklist preenchido, item pendente e formulários de escopo e capacidade")

![](https://itsm-labdev.cloud4biz.com/agility-v2/docs/screens/05-pi-objectives.webp "Aba Objetivos do PI 2027.1 com objetivo existente, valor de negócio BV 8 e formulário de criação")

:::hint{type="success"}
:FontAwesome[]{icon="fa-solid fa-check"} **Verificação**

- A Preparação mostra o percentual e a contagem do checklist, além dos cartões de capacidade, Features e agenda.
- Um item salvo aparece no Checklist com status Pendente ou Concluído e abre seu destino de correção.
- A capacidade exibe pontos alocados e disponíveis por Time × iteração, e uma alteração salva permanece após recarregar.
- A aba Objetivos lista título, BV, Time ou ART e situação de cada objetivo.
- Ao criar ou editar um objetivo, os cartões de objetivos e previsibilidade são atualizados pelo PI correspondente.
:::

:::hint{type="warning"}
****:FontAwesome[****]{icon="fa-solid fa-triangle-exclamation"}**&#x20;Erros comuns**

**Título do item de prontidão vazio**

O formulário não cria um item sem O que precisa estar pronto. Preencha o título e a causa ou detalhe para deixar a pendência útil para o próximo responsável.

**Valor de negócio fora de 0 a 10**

A validação impede valores menores que 0 ou maiores que 10. Corrija o campo Valor de negócio e envie novamente.

**Objetivo criado sem PI**

Sem PI de planejamento ou PI atual, a aba Objetivos exibe uma ação bloqueada. Crie um Planning Interval no ART antes de cadastrar objetivos.

**Capacidade disponível menor que a alocada**

O Agility não salva uma disponibilidade inferior aos pontos já alocados. Reduza a alocação no planejamento ou informe uma disponibilidade igual ou maior.

**Item medido não pode ser marcado manualmente**

Itens com selo Medido vêm de escopo ou capacidade calculados pelo sistema. Use a tela de origem indicada no diálogo, em vez de tentar alternar o estado do item medido.

**Usuário leitor não consegue editar**

Leitores continuam vendo checklist e objetivos, mas os controles de adicionar, remover e salvar não são renderizados para evitar ações que terminariam em 403.
:::


[title] Lançamentos: receitas, despesas e apontamento de horas
[path] Aplicações/Agility/Financeiro/

:::BlockQuote
Registre fatos financeiros diretamente no projeto ou quadro e aproprie horas pelo custo vigente da pessoa ou do papel.
:::

:::hint{type="info"}
**Pré-requisito:&#x20;**

Cadastre ao menos um custo-hora em Financeiro → Cadastros para apontar horas. Para associar o projeto a uma dimensão de rentabilidade, configure cliente e contrato na tela financeira do projeto.
:::

***

O lançamento é criado no Financeiro do projeto, pela aba Financeiro do projeto ou pelo caminho do Board. A mesma superfície mostra a tabela de apropriações, os KPIs de receita, custo e margem e os botões \*\*Novo lançamento\*\* e \*\*Apontar horas\*\*. Um lançamento próprio do Agility pode ser editado ou excluído; um fato com origem externa é somente leitura.

A caixa \*\*Novo lançamento\*\* registra quatro tipos: \*\*Despesa\*\*, \*\*Receita\*\*, \*\*Compra\*\* e \*\*Faturamento\*\*. Compra é o fluxo destinado a um fornecedor e pode receber centro de custo do ERP; o apontamento de horas é uma apropriação separada, porque o servidor deriva seu valor de horas × taxa vigente, em vez de aceitar um valor digitado.

***

### Passo a passo

::::WorkflowBlock
:::WorkflowBlockItem
**Abrir o financeiro do projeto**

Abra um projeto com a capability de Financeiro. Se ele tiver Board principal, selecione a aba \*\*Financeiro\*\* do Board; se for um projeto Tradicional sem Board, a mesma tela é exibida no escopo canônico do Projeto. Aguarde a tabela de lançamentos e os cartões de receita, custo, margem e margem %. Um projeto sintético não aceita lançamentos diretos: seus fatos devem ser criados nos projetos analíticos.
:::

:::WorkflowBlockItem
**Registrar uma receita**

Clique em \*\*Novo lançamento\*\* e selecione o tipo \*\*Receita\*\*. Em \*\*Descrição\*\*, informe o fato que entrou no projeto (por exemplo, uma entrega reconhecida). Digite o \*\*Valor (R$)\*\* com até duas casas decimais e informe a \*\*Competência\*\*. O campo de fornecedor não aparece para receita; o centro de custo só aparece se o ERP fornecer centros ativos que aceitem lançamentos.
:::

:::WorkflowBlockItem
Clique em \*\*Lançar\*\*. A nova linha aparece com data, selo \*\*Receita\*\*, descrição, valor positivo, origem e, se selecionado, o centro de custo. A receita alimenta o total de receita reconhecida e a margem; a solicitação de faturamento, descrita na seção de rentabilidade, é um processo separado e não deve ser confundida com o reconhecimento da receita.
:::

:::WorkflowBlockItem
**Registrar uma despesa**
Abra novamente \*\*Novo lançamento\*\*, escolha \*\*Despesa\*\*, informe descrição, valor e competência e, se fizer sentido, escolha um centro de custo ativo no seletor \*\*Centro de custo (ERP)\*\*. O centro de custo é uma dimensão do ERP e o rótulo do momento do lançamento fica congelado no histórico, mesmo que o ERP renomeie o centro mais tarde. Clique em \*\*Lançar\*\*; a tabela mostra a despesa como saída, com o prefixo de valor negativo.
:::

:::WorkflowBlockItem
**Registrar uma compra com fornecedor**
Em \*\*Novo lançamento\*\*, marque \*\*Compra\*\*. Preencha descrição, valor e competência; essa combinação é obrigatória como nos demais tipos. O diálogo revela \*\*Fornecedor (origem ERP demo)\*\*: informe o nome ou referência do fornecedor da compra. Opcionalmente selecione o centro de custo e clique em \*\*Lançar\*\*. A linha passa a mostrar, abaixo da descrição, o fornecedor e o selo \*\*Compra\*\*.
:::

:::WorkflowBlockItem
**Editar ou remover um lançamento próprio**
Na tabela, ações aparecem apenas para fatos com origem \*\*Agility\*\*. Use o lápis para \*\*Editar lançamento\*\* e corrija descrição, valor e competência; em uma compra, o fornecedor também pode ser corrigido. O tipo e a origem não mudam. Se a linha tiver quantidade × preço derivado, o valor fica desabilitado para evitar uma combinação inconsistente. Use a lixeira para excluir e atualize a tabela; fatos externos não podem ser removidos no Agility.
:::

:::WorkflowBlockItem
**Abrir o apontamento de horas**
Clique em \*\*Apontar horas\*\*. O formulário lista em \*\*Pessoa / papel\*\* todas as taxas carregadas do Workspace, exibindo o sujeito, sua dimensão (Pessoa ou Papel) e o valor da hora. Se a lista estiver vazia, o botão fica bloqueado e a tela informa para cadastrar um custo-hora em Financeiro; não há valor manual que substitua essa taxa.
:::

:::WorkflowBlockItem
**Informar horas e competência**

Selecione a pessoa ou o papel, preencha \*\*Horas\*\* em incrementos de 0,5 e informe a \*\*Competência\*\*. A competência é importante: o servidor procura a taxa vigente naquela data, e não necessariamente a taxa criada mais recentemente. Clique em \*\*Apontar horas\*\*. A tabela receberá uma apropriação do tipo hora de serviço e o custo será calculado pela taxa encontrada.
:::

:::WorkflowBlockItem
O cálculo do apontamento é \`horas × custo-hora vigente\`. Por exemplo, 8 horas com uma taxa de R$ 150,00 geram R$ 1.200,00 de custo; o usuário não digita os R$ 1.200,00. A taxa é escolhida por \`subjectKind\` (person ou role), \`subjectRef\` e competência. Ao editar um apontamento, escolha novamente a pessoa/papel e a quantidade de horas; o servidor reprecifica o custo pela taxa vigente na competência informada.
:::

:::WorkflowBlockItem
**Conferir a apropriação**

Na tabela de lançamentos, confira data, selo do tipo, descrição, valor e origem. O total de custo e a margem dos cartões devem refletir a nova saída. Abaixo da lista, \*\*Rentabilidade\*\* decompõe os fatos por tipo e natureza (entrada, saída ou faturado), permitindo conferir separadamente receita, despesa, compra, faturamento e horas.
:::
::::

:::hint{type="success"}
:FontAwesome[]{icon="fa-solid fa-check"} **Verificação**

- Receitas e despesas aparecem na tabela com seus selos, competência, descrição, direção e valor atualizados.
- Uma compra mostra o fornecedor abaixo da descrição e é contabilizada como saída.
- O apontamento aparece como hora de serviço e seu valor corresponde às horas multiplicadas pela taxa vigente na competência.
- Os cartões Receita, Custo, Margem e Margem % são recalculados após salvar o lançamento ou apontamento.
- O lápis e a lixeira aparecem para fatos próprios do Agility, enquanto fatos de origem externa não oferecem essas ações.
:::

:::hint{type="warning"}
****:FontAwesome[****]{icon="fa-solid fa-triangle-exclamation"}**&#x20;Erros comuns**

**Nenhum custo-hora vigente para a data**

O apontamento é recusado quando não existe taxa vigente para a competência escolhida. Cadastre uma taxa em Custos-hora com data de início adequada ou escolha uma competência coberta por uma taxa existente.

**Apontamento sem pessoa ou papel**

O formulário exige selecionar um sujeito listado no campo Pessoa / papel. Se não houver opções, cadastre a taxa; se a opção correta não aparecer, verifique se o cadastro está vigente e se o identificador foi digitado conforme a taxa.

**Fato de origem externa imutável**

Quando a origem exibida é externa, o Agility não mostra editar ou excluir. Corrija a informação no sistema de origem; essa regra preserva o fato que veio do ERP ou de outro adaptador.

**Projeto sintético sem execução**

Projetos sintéticos apenas consolidam projetos analíticos e exibem a mensagem de que não recebem lançamentos diretos. Abra o projeto analítico que executou o trabalho e lance a despesa, receita, compra ou hora lá.

**Campos obrigatórios ou valor inválido**

Descrição, valor, competência e, no apontamento, sujeito e horas, são obrigatórios. Confira se o valor é não negativo, se as horas respeitam o passo de 0,5 e se a data está preenchida antes de tentar salvar novamente.
:::


[title] Catálogo de produtos
[path] Aplicações/Agility/Produtos e releases/

:::BlockQuote
Cadastre os produtos de software que organizam versões, releases, features e objetivos de negócio do Workspace.
:::

:::hint{type="info"}
**Pré-requisito:&#x20;**

Você precisa estar dentro de um Workspace. Um ART pode ser associado ao produto, mas o vínculo com programa é opcional.
:::

***

O catálogo de Produtos é a âncora do ciclo de entrega do Agility. Cada produto representa uma solução de software que pode receber releases versionadas, features e riscos. A página também mostra quantos produtos existem, quantos estão associados a um ART/programa e quantas releases antigas ainda estão sem produto.

O cadastro mantém o contexto do produto separado de seus objetivos de negócio. Depois de salvar o produto, use Gerenciar na seção Objetivos de negócio para registrar resultados esperados e seus valores planejado e atual. Releases são vinculadas ao produto no próprio formulário de release; features podem ser criadas ou vinculadas dentro do detalhe da release.

***

Passo a passo

::::WorkflowBlock
:::WorkflowBlockItem
**Abrir o catálogo**

Na barra lateral do Workspace, abra Produtos. Antes da tabela, confira os indicadores Produtos de software, Vinculados a programa e Releases sem produto. O último é um atalho para a fila de Pendências de vínculo e ajuda a identificar dados legados que ainda precisam de classificação.
:::

:::WorkflowBlockItem
**Conferir a tabela e localizar um produto**

A tabela exibe Produto, Programa, Releases, Riscos e Situação. No nome aparecem também o código e o slug gerados pelo sistema. Use o campo de busca para filtrar por nome, código, slug, descrição ou programa; os filtros Programa e Situação permitem restringir a lista por ART/programa ou por Ativo/Inativo. Clique na linha ou no nome do produto para editar seus dados.
:::

:::WorkflowBlockItem
**Iniciar um cadastro**

Clique em Novo produto. O formulário solicita Nome do produto, ART/Programa, Situação e Descrição. O nome é obrigatório; a API recusa o envio quando ele está vazio. O produto pode ser avulso: em ART/Programa, deixe Sem programa quando não houver um trem ou programa responsável.
:::

:::WorkflowBlockItem
**Preencher identidade e contexto**

Informe um nome que seja reconhecível pelo time, como Portal do Cidadão - Web, e descreva o escopo no campo Descrição. A descrição aceita o contexto funcional e técnico do produto, por exemplo, canal web de serviços digitais com autenticação. Não há seletor de tipo de produto nesta tela: value stream e kind não fazem parte deste cadastro.
:::

:::WorkflowBlockItem
**Escolher programa e situação**

Se o produto pertencer a um ART, selecione-o em ART/Programa; os programas disponíveis são carregados a partir dos ARTs do Workspace. Selecione Ativo para disponibilizá-lo nos cadastros de release ou Inativo para preservar o histórico sem usá-lo em novas entregas. Ao editar, trocar o programa não altera releases já publicadas.
:::

:::WorkflowBlockItem
**Salvar o produto**

Revise nome, programa, situação e descrição e clique em Criar produto. O botão fica desabilitado enquanto o nome estiver vazio. Depois da gravação, o diálogo fecha e a tabela é recarregada; o novo produto passa a ter contagens de releases, riscos e objetivos calculadas pelo servidor.
:::

:::WorkflowBlockItem
**Abrir os objetivos de negócio**

Para um produto já criado, abra-o na tabela e clique em Gerenciar, na seção Objetivos de negócio. Na janela, o campo Produto é somente leitura e confirma o contexto. O seletor Objetivo em edição começa em Novo objetivo e também permite escolher um objetivo existente para atualizá-lo.
:::

:::WorkflowBlockItem
**Registrar um objetivo próprio**

Em Descrição do objetivo, escreva o resultado que o produto deve produzir, por exemplo, aumentar a autonomia do cidadão nos serviços digitais. Escolha Valor planejado na escala 1, 2, 3, 5, 8, 13 ou 21; esse valor representa a importância definida com o objetivo. Em Valor atual, use 0 quando ainda não há progresso ou uma das mesmas opções quando o resultado já evoluiu.
:::

:::WorkflowBlockItem
**Acompanhar e editar objetivos**

Clique em Salvar objetivo. O objetivo aparece em Objetivos deste produto com seus valores planejado e atual, e o painel Valor de negócio somado é recalculado automaticamente a partir da coleção — ele não é um campo digitável. Para atualizar um objetivo, selecione-o em Objetivo em edição, ajuste descrição ou valores e salve novamente; para iniciar outro, escolha Novo objetivo.
:::

:::WorkflowBlockItem
**Relacionar produto, release e feature**

Ao criar uma release, o Produto de software é obrigatório e a versão é única dentro desse produto. No detalhe da release, a aba Features permite usar Nova feature, já com a release selecionada, ou Vincular feature para escolher uma feature existente que ainda não tenha release. Assim, o produto organiza as versões, a release representa uma entrega e a feature descreve uma capacidade incluída nela.
:::
::::

:::hint{type="success"}
:FontAwesome[]{icon="fa-solid fa-check"} **Verificação**

- O produto aparece na tabela com nome, código/slug, situação e contagens derivadas de releases e riscos.
- O objetivo salvo aparece em Objetivos deste produto e o Valor de negócio somado reflete a soma dos valores planejados.
- O produto pode ser selecionado no campo Produto de software ao criar uma release.
- Uma release criada para o produto mostra o nome do produto no catálogo e no cabeçalho do seu detalhe.
:::

:::hint{type="warning"}
:FontAwesome[]{icon="fa-solid fa-triangle-exclamation"} **Erros comuns**

**Nome do produto não informado**

O formulário exibe Informe o nome do produto e não permite salvar enquanto o campo estiver vazio. Preencha o nome e tente novamente.

**Objetivo sem descrição**

A janela de objetivos exige Descrição do objetivo. Se o botão Salvar objetivo estiver desabilitado ou a mensagem de validação aparecer, informe uma descrição antes de escolher os valores.

**Tentar criar objetivo antes do produto**

No formulário Novo produto, Adicionar fica desabilitado porque ainda não existe um id para o objetivo. Salve o produto primeiro e use Gerenciar na edição.

**Alterar o programa esperando mover releases**

O programa é apenas o vínculo organizacional do produto; a ajuda do formulário informa que trocá-lo não altera releases já publicadas. Faça a alteração sabendo que o histórico das releases permanece no produto.
:::


[title] Metas (Goals) e valor de negócio
[path] Aplicações/Agility/Relatórios e metas/

:::BlockQuote
Cadastre uma meta organizacional com valor planejado, conecte-a a um Programa ou produto representado na hierarquia e registre o valor realmente alcançado.
:::

:::hint{type="info"}
**Pré-requisito:&#x20;**

Abra Metas dentro de um Workspace. Para conectar a meta, tenha pelo menos um Portfólio, ART (apresentado como Programa) ou Projeto cadastrado; o escopo conectado informa quem persegue o resultado.
:::

***

Metas organizacionais registram o que a organização quer atingir, quem persegue esse resultado e a medição mais recente. O formulário torna a meta mensurável com indicador, unidade, linha de base, alvo e horizonte. Para acompanhar valor de negócio, use um indicador explícito — por exemplo, "valor de negócio entregue" na unidade definida pela organização — e registre o alvo como valor planejado.

A tela não possui um campo de progresso editável. O valor atual e o percentual são derivados pelo servidor a partir do resultado medido mais recente. A hierarquia disponível para conexão é Portfólio, Programa e Projeto: um ART é apresentado como Programa; quando o produto é governado por um portfólio, conectar o Portfólio é a forma organizacional de fazer a meta descer para os produtos e projetos relacionados.

***

### Passo a passo

::::WorkflowBlock
:::WorkflowBlockItem
**Abrir Metas organizacionais**

No Workspace, abra Metas. A página mostra o título "Metas organizacionais", a explicação de que reúne objetivo, responsável e resultado medido, e o botão Nova meta. A lista também exibe o status (Rascunho, Em vigor ou Concluída), a origem, o indicador, o horizonte e os vínculos de escopo.
:::

:::WorkflowBlockItem
**Definir o resultado de negócio**

Clique em Nova meta e preencha Título com o resultado que a organização quer alcançar. Em Descrição (opcional), registre o impacto esperado para orientar a leitura. No campo Indicador, escreva o que será medido — por exemplo, "Valor de negócio entregue pelas releases prioritárias" — e escolha em Unidade como o valor será contado, como "pontos", "R$" ou "%", conforme a convenção do Workspace.
:::

:::WorkflowBlockItem
**Informar o valor planejado**

Preencha Linha de base com a situação inicial e Alvo com o valor planejado para o fim do horizonte. Ambos são números e aceitam casas decimais. O alvo precisa ser diferente da linha de base: se os dois forem iguais, corrija a expectativa ou o indicador antes de cadastrar. A meta guardará esses valores para comparar o resultado posterior, não para calcular uma porcentagem digitada pelo usuário.
:::

:::WorkflowBlockItem
**Definir o horizonte e cadastrar**

Informe Início do horizonte e Fim do horizonte nos seletores de data. O botão Cadastrar só fica pronto quando as duas datas estão preenchidas; confirme se o fim representa o período em que o valor de negócio será medido. Envie o formulário e aguarde o recarregamento da lista. A nova meta aparece como Rascunho, com a indicação de que ainda não tem escopo conectado e resultado medido.
:::

:::WorkflowBlockItem
**Conectar a um Programa ou produto da hierarquia**

Na linha da meta, clique em Conectar escopo. O seletor combina Portfólios, Programas (ARTs) e Projetos, exibindo nível, código e nome. Para uma meta de um Programa, escolha o item apresentado como Programa e confirme Conectar. Para uma meta cujo valor é acompanhado por um produto, escolha o Portfólio que governa esse produto quando essa for a relação existente no Workspace; a tela trata a conexão como consolidação e permite também uma conexão direta ao projeto.
:::

:::WorkflowBlockItem
**Colocar a meta em vigor**

Depois de conectar pelo menos um escopo, use Pôr em vigor. Uma meta não entra em vigor sem Portfólio, Programa ou Projeto conectado (BR-PROJ-017); se o botão for acionado antes da conexão, a mensagem explica a regra e orienta a conectar o escopo. Em vigor, a meta continua mostrando o alvo planejado e passa a representar um compromisso acompanhado pela hierarquia.
:::

:::WorkflowBlockItem
**Registrar o valor realmente alcançado**

Quando houver uma medição real, clique em Registrar resultado na meta. Preencha Valor com o resultado observado na mesma unidade do alvo, selecione Medido em com a data de calendário e, em Observação (opcional), informe a origem do número — por exemplo, a release, relatório ou reunião de medição. Clique Registrar; a medição aparece na série de resultados e o valor atual/progresso é recalculado a partir da medição mais recente.
:::

:::WorkflowBlockItem
**Interpretar o progresso derivado**

Leia a linha de progresso no formato "valor atual de alvo — linha de base" e o percentual ao lado da barra. O número pode ultrapassar 100% quando o alvo é superado ou ficar negativo quando o valor regride abaixo da linha de base; a barra visual é limitada ao intervalo de 0 a 100 apenas para caber no cartão. Não procure um campo para editar esse percentual: ele vem do resultado medido.
:::

:::WorkflowBlockItem
**Concluir somente com medição**

Quando o valor alcançado representar o encerramento, use Concluir. O servidor exige que exista resultado medido (BR-PROJ-018); assim, uma meta sem medição não pode ser marcada como Concluída. Após a conclusão, preserve a medição que comprova o resultado e use a observação para manter a trilha de auditoria legível.
:::

:::WorkflowBlockItem
**Manter a série de medições**

A meta aceita uma medição por data. Para substituir um número registrado no mesmo dia, apague primeiro o resultado daquela data pelo ícone de exclusão e registre o valor corrigido. Não crie duas medições para a mesma data: a regra de negócio rejeita a duplicidade e informa que o resultado existente deve ser apagado antes da substituição.
:::
::::

:::hint{type="success"}
:FontAwesome[]{icon="fa-solid fa-check"} **Verificação**

- A meta aparece com indicador, unidade, linha de base, alvo planejado e datas de início/fim do horizonte.
- O vínculo mostra o nível conectado (Portfólio, Programa ou Projeto), o código e o nome do escopo que persegue a meta.
- Depois de conectar um escopo, o status pode mudar de Rascunho para Em vigor; sem escopo, a tela explica a regra BR-PROJ-017.
- O resultado registrado aparece com data, valor e observação, e o valor atual/progresso muda sem edição manual de porcentagem.
- Uma tentativa de concluir sem resultado é recusada; depois de registrar a medição, a meta pode ser marcada como Concluída.
- O progresso exibido usa a medição mais recente e distingue claramente o valor planejado (alvo) do valor realmente alcançado (resultado).
:::

:::hint{type="warning"}
:FontAwesome[]{icon="fa-solid fa-triangle-exclamation"} **Erros comuns**

**Indicador, unidade ou alvo inválido**

Confira os campos obrigatórios e use um alvo diferente da linha de base. A validação também exige datas de horizonte coerentes; corrija o formulário antes de tentar cadastrar novamente.

**Tentativa de pôr a meta em vigor sem escopo**

A meta precisa estar conectada a um Portfólio, Programa ou Projeto. Clique Conectar escopo, escolha uma opção disponível e tente Pôr em vigor novamente; a tela explicita a regra BR-PROJ-017 em vez de esconder a causa.

**Resultado duplicado na mesma data**

O servidor aceita uma medição por data. Apague o resultado incorreto usando o ícone da data e registre o valor corrigido com a mesma data, ou escolha outra data quando for uma nova medição real.

**Tentativa de concluir sem valor alcançado**

Registre primeiro o resultado medido pelo botão Registrar resultado. A conclusão sem medição é recusada pela regra BR-PROJ-018, porque o status concluído precisa manter uma evidência do valor alcançado.

**Não há opção adequada para conectar**

A lista de escopos é carregada com Portfólios, ARTs e Projetos do Workspace. Se tudo já estiver conectado ou não houver um nível cadastrado, a caixa informa que não há nada a conectar; cadastre o nível correspondente e reabra o diálogo.
:::


[title] Fiscal — saída
[path] Aplicações/ERP/Manual do Usuário/

# Fiscal — saída (NF-e, NFC-e, NFS-e)

:::BlockQuote
Pré-requisitos: [Cadastro fiscal próprio](docId\:Q-zx6Qk4pMFD09yrhmsve) (estabelecimento ativo, *CRT* correto, IEST e CSC quando aplicável) e [Vendas e CRM](docId\:TaINdkXLJcUzyq0xUuGfH) (pedido de venda pronto para faturar).
:::

:::BlockQuote
**Aviso de ambiente:** no ambiente de demonstração, a **transmissão é simulada** — o sistema gera o documento, autoriza pelo gateway simulado e devolve chave de acesso + protocolo (sintéticos, não válidos na SEFAZ). A partir da nota autorizada, o **XML** e o **DANFE** são **gerados de verdade** e podem ser baixados na ficha da nota (botões "Baixar XML" / "Baixar DANFE"). O que depende de insumo externo é a **autorização real na SEFAZ** (chave + protocolo válidos juridicamente): exige **certificado A1/A3 + provedor de transmissão configurado (fiscal.provider) + homologação SEFAZ** — o núcleo está pronto para plugar esses parâmetros, sem mudança de código. Em produção, é necessário certificado digital A1/A3 válido e conexão configurada com a SEFAZ (NF-e / NFC-e) ou com o ADN (NFS-e Padrão Nacional).
:::

## Introdução

***

O módulo fiscal de saída é onde a venda vira **documento fiscal**. Depois que o pedido de venda está pronto ([Vendas e CRM](docId\:TaINdkXLJcUzyq0xUuGfH)), você emite aqui a nota que acompanha a mercadoria ou o serviço, transmite ao Fisco e acompanha a autorização. No mesmo movimento, o sistema gera automaticamente a **conta a receber** (a duplicata da nota) e **baixa o estoque** dos itens vendidos — não é preciso lançar o recebível à mão.

O operador fiscal usa esta área no dia a dia para: emitir a *NF-e* de saída a partir do pedido, transmitir e acompanhar o protocolo, conferir as duplicatas geradas, cancelar uma nota dentro do prazo, registrar devoluções de cliente, emitir várias notas de uma vez em lote, e manter em dia o certificado digital que assina tudo isso. Todas essas telas ficam no menu lateral, no grupo **Fiscal** — que é próprio, separado de Vendas.

## Passo a passo

***

### Emitir a nota de saída a partir do pedido

1. **Abra "Documentos fiscais".** No menu lateral, em **Fiscal → Documentos fiscais**. A lista mostra cada nota emitida com número, série, tipo, cliente, valor e situação (Emitido, Transmitido, Autorizado, Rejeitado, Cancelado).:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/086-fiscal-documents.png" alt caption width="3200" height="2000"}
2. **Gere a nota do pedido.** A nota nasce a partir de um pedido de venda faturado ([Vendas e CRM](docId\:TaINdkXLJcUzyq0xUuGfH)). Ao faturar, você escolhe a **categoria do recebível** (a conta a receber que será gerada) e o sistema monta a nota com os itens, quantidades e valores vindos do pedido. **O ICMS não vem do pedido nem é digitado**: ao emitir, o sistema resolve a regra fiscal do par de Estados (origem → destino) e o regime especial que o Estado de destino tiver concedido, e grava o imposto calculado. Ver "Como o ICMS é calculado", adiante.
3. **Abra a nota para conferir.** Clique na linha da nota. A ficha mostra o número (ex.: 1-000003), a situação atual (Emitido), o tipo (NF-e (mercadoria)) e o bloco **Itens e tributos** com produto, quantidade, valor unitário, *CFOP* e o link "Tributos" para ver o detalhe do imposto de cada item, **com o valor calculado e a justificativa do cálculo**. Enquanto a nota está apenas Emitido, ela ainda não foi ao Fisco.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/021-fiscal-documents-detail.png" alt caption width="3200" height="2000"}
4. **Transmita ao Fisco.** Na ficha da nota, clique em "Transmitir". No ambiente de demonstração, o sistema simula a resposta e devolve o protocolo de autorização. Em produção, a nota é enviada à SEFAZ (NF-e) ou ao ADN (NFS-e) e a situação muda para Transmitido e depois Autorizado quando o Fisco responde.**Depois de autorizada**, a ficha exibe os botões **"Baixar XML"** e **"Baixar DANFE"** (só aparecem quando a situação é Autorizado): o XML é o documento fiscal em si, que o cliente e a contabilidade guardam; o DANFE é a folha impressa que acompanha a mercadoria, com a chave de acesso, o protocolo, o emitente, o destinatário, os itens e os totais. O cliente também é notificado por e-mail no momento da autorização (não mais na emissão).:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/095-fiscal-document-danfe.png" alt caption width="3200" height="2000"}**A autorização também pode abrir tarefas.** Se a organização cadastrou regras de tarefa para o evento "faturamento autorizado" (menu **Administração → Regras de tarefa**), assim que a nota é autorizada o sistema cria sozinho as tarefas correspondentes na **Caixa de tarefas** do responsável — com o número da nota no título e o prazo contado a partir da autorização. É o jeito de garantir que a conferência, o arquivamento ou a cobrança não dependam de alguém lembrar. Regras com condição que não casa com a nota (por exemplo, uma regra que só vale para nota rejeitada) não criam tarefa.

:::BlockQuote
💡 Se o estabelecimento emissor for definido pelo depósito de saída do pedido (matriz 11222333000181 ou filial 11222333000262), a nota sai com o CNPJ correto de cada emitente. Na tela de emissão há um seletor de estabelecimento opcional — quando você não escolhe nada, o sistema decide pelo depósito do pedido.
:::

### Como o ICMS é calculado

O ICMS muda de Estado para Estado — a alíquota, os produtos sujeitos a **substituição tributária** e os **benefícios** que cada Estado concede (redução de base, diferimento, isenção, suspensão). Em vez de o operador saber tudo isso de cabeça e digitar, o sistema calcula a partir do que está cadastrado.

Dois cadastros alimentam o cálculo, ambos no menu **Fiscal**:

- **Regras fiscais do produto** — por par de Estados (origem → destino): a alíquota do ICMS, o CFOP e, para produto substituído, a **margem (MVA)** e a alíquota da substituição.
- **Regimes especiais de ICMS** — o benefício que um Estado concedeu, com o **dispositivo legal** (o artigo do RICMS ou o número do TARE) e a **vigência**. Pode valer para o Estado inteiro ou ser restrito a uma operação, a um parceiro ou a um produto; o sistema aplica o mais específico que estiver vigente.

Ao emitir a nota, para cada item o sistema identifica o Estado de destino (pelo endereço do destinatário), busca a regra daquele par de Estados e aplica o benefício vigente. O valor calculado **substitui** qualquer imposto que estivesse digitado na linha — a regra cadastrada é que vale.

Abra **Itens e tributos → Tributos** na linha para conferir. Além do valor de cada imposto, um bloco **"Calculado pela regra estadual"** mostra:

- **de quanto a base veio** quando um benefício a reduziu (ex.: *base reduzida de R$ 1.000,00 para R$ 666,70*);
- o **dispositivo legal** do benefício aplicado, exatamente como foi cadastrado;
- a **margem aplicada**, quando há substituição tributária.

Quando o produto é substituído, a linha ganha um segundo imposto, **ICMS-ST**: o sistema calcula a base presumida da operação seguinte e o imposto retido. Numa venda para outro Estado a margem é **ajustada** conforme a legislação, e o valor retido é sempre **descontado** do ICMS próprio — nunca cobrado em dobro. Esse imposto retido **integra o total da nota** e, portanto, o título a receber do cliente.

:::BlockQuote
💡 **Se não houver regra cadastrada** para aquele par de Estados e produto, o sistema não inventa imposto: a nota sai sem aquele tributo. O mesmo vale quando o destinatário está sem Estado no cadastro — vale conferir o endereço do parceiro antes de faturar.
:::

:::BlockQuote
⚠️ Um benefício **sempre reduz** a carga. Se você cadastrar uma redução e o imposto não diminuir, o mais provável é que a regra não esteja casando com a operação (Estado, produto ou vigência) — confira o escopo e as datas do regime especial.
:::

### Escolher a operação fiscal (CFOP / natureza da operação)

1. **Abra "Operações fiscais".** No menu lateral, em **Fiscal → Operações fiscais**. Aqui ficam as **naturezas de operação** — a combinação de CFOP, tipo de nota e finalidade que descreve *o que* está sendo faturado (venda dentro do estado, venda para outro estado, remessa, devolução, prestação de serviço). É a operação fiscal que define qual CFOP entra em cada item da nota.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/087-fiscal-operations.png" alt caption width="3200" height="2000"}
2. **Confira a operação usada.** Antes de emitir, verifique se a operação escolhida bate com a venda: venda interestadual usa CFOP iniciando em 6, venda dentro do estado usa CFOP iniciando em 5. Um CFOP incompatível com a operação é uma das causas mais comuns de rejeição do Fisco.

### Conferir as duplicatas geradas (contas a receber)

1. **Abra "Pré-visualização de duplicatas".** No menu lateral, em **Fiscal → Pré-visualização de duplicatas**. Cada nota de saída gera uma ou mais **duplicatas** — as parcelas da conta a receber, com vencimento conforme a condição de pagamento do pedido. Esta tela mostra as duplicatas que a nota vai gerar antes de você fechar a emissão.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/089-fiscal-duplicatas.png" alt caption width="3200" height="2000"}
2. **Confira valores e vencimentos.** Uma venda de R$ 1.250,00 em três vezes, por exemplo, aparece aqui como três duplicatas com os vencimentos calculados a partir da condição de pagamento. Depois da emissão, essas duplicatas viram contas a receber e aparecem no Financeiro ([Financeiro — títulos (contas a pagar e a receber)](docId\:D4kuGidayU2GQ-hMhF_T-)).

### Emitir várias notas de uma vez (lote fiscal)

1. **Abra "Lotes fiscais".** No menu lateral, em **Fiscal → Lotes fiscais**. Quando há muitos pedidos para faturar de uma vez (fechamento do dia, corte de faturamento mensal), você agrupa os documentos em um **lote** e transmite todos juntos, em vez de emitir nota por nota.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/088-fiscal-batches.png" alt caption width="3200" height="2000"}
2. **Processe o lote.** Selecione os documentos, gere o lote e mande processar. O sistema transmite as notas em segundo plano e vai atualizando os contadores de processadas, autorizadas e rejeitadas. Ao final, o lote fica com a situação Processado.

:::BlockQuote
💡 Há um limite de tamanho por lote. Lotes muito grandes são recusados — divida em lotes menores quando isso acontecer.
:::

### Cancelar uma nota autorizada

1. **Abra a nota na tela de Documentos fiscais** e clique em "Cancelar". Uma nota autorizada pode ser cancelada dentro do prazo legal (regra da SEFAZ; em geral 24 horas para NF-e).
2. **Informe a justificativa.** O cancelamento exige um motivo com no mínimo 15 caracteres — ex.: Pedido cancelado pelo cliente antes do envio. Confirme. A situação muda para Cancelado, o **estoque é devolvido** e a **conta a receber é estornada** automaticamente.

### Registrar uma devolução de cliente

1. **Abra "Devoluções fiscais".** No menu lateral, em **Fiscal → Devoluções fiscais**. Quando o cliente devolve mercadoria, você registra aqui a **nota de devolução** (a NF-e de entrada correspondente à saída original). Ela referencia a nota de venda que está sendo devolvida.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/090-fiscal-returns.png" alt caption width="3200" height="2000"}
2. **Confirme a devolução.** Ao transmitir a devolução, o **estoque volta a subir** (a mercadoria retorna) e o efeito financeiro da venda original é revertido na medida da devolução. A devolução usa uma operação fiscal própria (CFOP de devolução) — confira que a natureza escolhida é de devolução, não de venda.

### Manter o certificado digital

1.

Se a **senha estiver incorreta** ou o **arquivo não for um .pfx legível**, a tela avisa e não preenche nada — você pode digitar os campos à mão, como antes.

**O arquivo não é enviado ao ERP.** A leitura acontece no seu próprio computador, apenas para extrair os dados de identificação; **a senha também não sai da máquina**, e nem o arquivo nem a senha são gravados. Continua valendo a regra de que o certificado em si vive na emissora, não no ERP — o que fica registrado aqui são só os dados de identificação.

É a forma recomendada, porque as datas alimentam o alerta de "certificado vencendo" e um dígito errado na digitação passa despercebido até a emissão falhar.

💡 **Deixe o sistema preencher para você.** Em vez de transcrever os dados à mão, **selecione o arquivo do certificado A1 (.pfx) e informe a senha dele**: o sistema lê o arquivo e preenche sozinho o **titular**, o **emissor** e as **duas datas de validade**. Você confere, completa o **apelido** e a **referência da emissora** (esses dois não vêm do arquivo) e registra. Todos os campos preenchidos continuam editáveis antes de salvar.

**Abra "Certificados fiscais".** No menu lateral, em **Fiscal → Certificados fiscais**. O certificado digital (A1/A3) é o que **assina** eletronicamente cada nota transmitida. Esta tela tem o formulário para registrar um certificado (apelido, referência do provedor, titular, emissor e datas de validade) e, logo abaixo, a relação de certificados ativos com a validade de cada um. O **apelido é obrigatório** — cadastrar sem ele é recusado. O arquivo do certificado fica guardado em cofre, nunca em claro.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/091-fiscal-certificates.png" alt caption width="3200" height="2000"}

1. **Verifique a validade.** Um certificado vencido **impede a emissão** de qualquer nota. Acompanhe a data de expiração e renove com antecedência. A coluna de situação distingue três casos: **Ativo** (verde), **Vence em ≤30 dias** (amarelo, hora de providenciar a renovação) e **Vencido** (vermelho — o certificado continua cadastrado, mas não serve mais para assinar). No ambiente de demonstração a área de certificados ativos aparece vazia ("Nenhum certificado cadastrado") até você registrar o primeiro.

:::BlockQuote
💡 **Certificado não se edita — substitui-se.** O certificado é imutável por design (A1/A3 não é alterado campo a campo). Na renovação anual, você **cadastra um novo** certificado e **remove o antigo** — não há edição do certificado existente.
:::

### Acompanhar os eventos da nota

1. **Abra "Eventos fiscais".** No menu lateral, em **Fiscal → Eventos fiscais**. Cada nota deixa um **rastro cronológico de eventos**: transmissão, autorização, cancelamento, carta de correção. Esta tela traz o formulário para enviar um novo evento — você escolhe o tipo (cancelamento, CC-e, inutilização), informa a nota e o motivo. O evento é sempre uma **ação sobre uma nota já emitida** — não é um lançamento avulso: sem um documento fiscal de origem, o evento não é aceito.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/092-fiscal-events.png" alt caption width="3200" height="2000"}
2. **Investigue uma rejeição.** Quando uma nota é rejeitada, o evento traz o **código e a descrição** da rejeição (ex.: 526 — CFOP incompatível com operação). É por aqui que você descobre o que corrigir antes de reemitir.

### Acompanhar o painel de saída fiscal

1. **Abra "Painel de saída fiscal".** No menu lateral, em **Fiscal → Painel de saída fiscal**. É a visão gerencial do dia: quantas notas foram transmitidas, quantas autorizadas, quantas rejeitadas e quantas ainda estão pendentes de resposta do Fisco.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/093-fiscal-output-panel.png" alt caption width="3200" height="2000"}
2. **Priorize o que travou.** Use os indicadores de rejeitadas e pendentes para agir onde há problema — cada número leva de volta às notas que precisam de correção ou reenvio.

### Gerar os livros fiscais e o SPED-EFD

1. **Abra "Livros fiscais & SPED-EFD".** No menu lateral, em **Fiscal → Livros fiscais & SPED-EFD**. Ao fim do período (mês fiscal), o contador gera aqui as **obrigações acessórias** a partir das notas do sistema: o **Registro de Saídas** e o **Registro de Entradas** (os livros fiscais) e o arquivo **SPED-EFD ICMS/IPI**. Escolha o livro (saídas ou entradas) e o período (data inicial e final).:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/094-fiscal-books.png" alt caption width="3200" height="2000"}
2.

⚠️ **O livro é de um CNPJ, não do sistema inteiro.** O cabeçalho do arquivo (registro 0000) declara **um** estabelecimento — aquele que o sistema resolve como o seu, normalmente a **matriz** —, e o Registro de Saídas traz **só as notas emitidas por esse estabelecimento**. Notas de **outra filial com CNPJ próprio**, ou de **outra empresa** cadastrada no mesmo ambiente, **não** entram: cada CNPJ entrega o seu próprio arquivo. Se você esperava ver uma nota e ela não apareceu, confira em **Fiscal → Notas fiscais** qual estabelecimento a emitiu antes de suspeitar do período.

💡 **Substituição tributária no período.** Quando houve ICMS retido por substituição, o arquivo traz também a **apuração do ICMS-ST por Estado** — um par de registros E200/E210 para cada Estado que efetivamente reteve. Isso é separado da apuração do ICMS próprio (E110), que continua somando só as operações da empresa, como o layout exige.

**Confira o registro e baixe o SPED.** A tabela mostra cada nota do período (data, modelo, número, participante, valor e ICMS), e os cartões no topo somam o total de saídas/entradas e os débitos/créditos de ICMS. Clique em **"Baixar SPED-EFD"** para gerar o arquivo texto no layout de blocos (0/C/E/9) que se entrega ao Fisco. A entrega em si (upload no programa validador — o PVA) segue fora do ERP, como manda a regra.

:::BlockQuote
💡 Os livros reúnem em um único lugar as notas autorizadas do período **do estabelecimento declarado** — controle centralizado por CNPJ. O arquivo gerado cobre o caso padrão (blocos 0/C/E/9), estruturalmente válido para conferência/importação; não é o layout completo do Guia Prático (registros de todos os blocos).
:::

## Verificação

***

Você sabe que funcionou quando:

- A nota aparece na lista de **Documentos fiscais** com a situação avançando de Emitido para Transmitido e, depois da resposta do Fisco, Autorizado.
- A **conta a receber** (duplicata) foi gerada com os vencimentos da condição de pagamento e aparece no Financeiro ([Financeiro — títulos (contas a pagar e a receber)](docId\:D4kuGidayU2GQ-hMhF_T-)).
- O **estoque diminuiu** na quantidade vendida (ex.: caiu de 170 para 165 ao vender 5 unidades).
- Cada nota tem seu histórico completo em **Eventos fiscais** (transmissão e autorização listadas em ordem).
- No **Painel de saída fiscal**, a nota do dia entra na contagem de autorizadas.
- Ao cancelar uma nota dentro do prazo, a situação vira Cancelado, o estoque é devolvido e o recebível é estornado.
- Numa nota **autorizada**, os botões **Baixar XML** e **Baixar DANFE** aparecem e produzem o arquivo (o DANFE é um PDF com a chave de acesso, o protocolo, itens e totais; o XML é o documento fiscal).
- Em **Livros fiscais & SPED-EFD**, ao escolher o período, a nota autorizada aparece no Registro de Saídas e o botão **Baixar SPED-EFD** gera o arquivo texto com os blocos 0/C/E/9.
- No ambiente de demonstração, o protocolo de autorização é preenchido pelo gateway simulado (não é transmissão real).

## Erros comuns

***

- **ISSUER.NOT\_REGISTERED** — o estabelecimento emissor não está com o cadastro fiscal completo. Revise a página [Cadastros gerais (parceiros e produtos)](docId:6xpQsdWQ2NTyI40BFqDS-) (empresa, estabelecimento, CRT, IEST/CSC quando aplicável).
- **526 — CFOP incompatível com operação** — o CFOP do item não bate com a operação (interestadual com CFOP 5xxx, ou intraestadual com CFOP 6xxx). Ajuste a operação fiscal escolhida (passo 5) e reemita.
- **Certificado vencido** — nenhuma nota transmite se o certificado digital estiver expirado. Verifique em **Certificados** (passo 15) e renove.
- **Cancelamento fora do prazo** — passado o prazo legal, o botão "Cancelar" não conclui. Nesse caso o caminho é a devolução ou a carta de correção, conforme o motivo.
- **Justificativa curta no cancelamento** — o motivo precisa ter no mínimo 15 caracteres; texto curto demais é recusado.


[title] Início rápido
[path] Aplicações/ERP/Manual do Usuário/

# Quick start — primeiro contato em 30 minutos

:::BlockQuote
Para quem quer **ver o ERP funcionando** antes de mergulhar nas 15 seções completas. Aqui você cadastra uma empresa mínima, um cliente, um produto, faz uma venda, gera uma NF-e simulada — tudo em meia hora. Depois, volte ao *00-index.md* para o roteiro completo.
:::

:::BlockQuote
**Ambiente esperado:** dev-standalone (demonstração). NF-e e demais documentos fiscais são **simulados** — não vão à SEFAZ real.
:::

## O que você vai conseguir ao final

***

- ✅ Uma empresa cadastrada (matriz).
- ✅ Um cliente cadastrado.
- ✅ Um produto cadastrado.
- ✅ Um pedido de venda faturado.
- ✅ Uma NF-e simulada com chave de acesso.
- ✅ Uma conta a receber gerada automaticamente.

Tempo estimado: **30 minutos** (45 minutos se for sua primeira vez).

## Passo 1 — Cadastrar sua empresa (\~10 min)

***

1. **Menu lateral → Cadastros fiscais → Empresas.**
2. Clique em **"Nova empresa"** — abre o assistente de 3 passos.
3. **Passo 1 (empresa):**
   - CNPJ raiz: 11222333 (8 dígitos) — tabule e a razão social autopreenche.
   - CRT: 3 — Regime Normal.
   - Natureza jurídica: digite "LTDA" → escolha 2046.
   - Classificação tributária: 99.
   - Responsável legal: nome + CPF 296.936.410-78.
   - **Avançar.**
4. **Passo 2 (matriz):**
   - CNPJ completo: 11222333000181.
   - CEP 01310-100 (tabule — endereço autopreenche São Paulo).
   - CNAE principal: busque "desenvolvimento" → 6201501.
   - **Salvar.**
5. **Passo 3:** clique em **"Concluir"** (sem adicionar filial agora).

:::BlockQuote
Quer cadastro fiscal completo (sub-cadastros, IEST, CSC, contas bancárias)? Veja *01 — Cadastro fiscal próprio*.
:::

## Passo 2 — Cadastrar 1 cliente (\~3 min)

***

1. **Menu lateral → Cadastros gerais → Parceiros.**
2. **Novo parceiro:**
   - Tipo: Pessoa jurídica.
   - CNPJ: 44555666000181.
   - Razão social: Cliente Exemplo Ltda.
   - Papel: marque **Cliente**.
   - **Salvar.**
3. Confirmar: você é redirecionado para a edição do parceiro, com check verde **"Salvo às HH\:MM\:SS"** ao lado do botão.

:::BlockQuote
Detalhes completos (PF, fornecedores, papéis múltiplos) em *02 — Cadastros gerais*.
:::

## Passo 3 — Cadastrar 1 produto (\~3 min)

***

1. **Menu lateral → Cadastros gerais → Produtos.**
2. **Novo produto:**
   - Código: PROD-001.
   - Nome: Notebook ACME 14".
   - NCM: 8471.30.12.
   - Unidade de medida: UN.
   - Tipo: Produto físico.
   - **Salvar.**

:::BlockQuote
Quer cadastros mais ricos? Veja *02 — Cadastros gerais*.
:::

## Passo 4 — Fazer um pedido de venda + faturar (\~10 min)

***

1. **Menu lateral → Vendas → Pedidos.**
2. **Novo pedido:**
   - Cliente: Cliente Exemplo Ltda.
   - Vendedor: você (auto-preenchido).
   - Item: PROD-001, quantidade 1, preço R$ 4.500,00.
   - Condição de pagamento: À vista (ou outra cadastrada).
   - Forma de pagamento: PIX.
   - Almoxarifado de origem: o primeiro da lista (precisa existir um — se não, volte e crie em **Estoque → Almoxarifados**).
   - **Salvar e confirmar.**
3. O pedido fica Aguardando aprovação ou Aprovado direto (depende de alçada cadastrada).
4. Se ficar aguardando, abra-o e clique em **"Aprovar"**.
5. Com o pedido Aprovado, clique em **"Faturar"**:
   - Confirme os dados fiscais (CFOP, NCM, CST sugeridos).
   - **Confirmar emissão.**

:::BlockQuote
Detalhes de aprovação por alçada, faturamento parcial, devolução em *08 — Vendas*.
:::

## Passo 5 — Conferir o que aconteceu (\~4 min)

***

Em **paralelo**, o sistema gerou:

- ✅ **NF-e modelo 55** — vá em **Fiscal → Saída → NF-e**. Você vê a nota com status Autorizada (simulação) + chave de acesso de 44 dígitos + DANFE para impressão.
- ✅ **Conta a receber** — vá em **Financeiro → Contas a receber**. A conta do Cliente Exemplo Ltda aparece com R$ 4.500,00 e vencimento de acordo com a condição.
- ✅ **Baixa de estoque** — vá em **Estoque → Movimentos**. O produto PROD-001 tem 1 unidade a menos no almoxarifado.
- ✅ **Lançamento contábil** — vá em **Contabilidade → Razão**, filtre pela conta Receita de Vendas. Aparece o crédito do faturamento + débito em Clientes a receber.

## O que aprendemos

***

Em 30 minutos, você:

- Conheceu o **fluxo principal** do ERP: cadastros → operação → financeiro → fiscal → contabilidade em cadeia.
- Viu que **o sistema faz ligações automáticas** — uma única ação (faturar) gera ≥4 efeitos coordenados.
- Identificou onde estão os menus principais (Cadastros, Vendas, Estoque, Fiscal, Financeiro, Contabilidade).

## Próximo passo

***

Cada um dos 5 passos acima é o **resumo** de uma página completa. Quando quiser mergulhar:

| **Passo**           | **Página completa**                                                               |
| ------------------- | --------------------------------------------------------------------------------- |
| 1                   | [Cadastro fiscal próprio](docId\:Q-zx6Qk4pMFD09yrhmsve)                           |
| 2 + 3               | [Cadastros gerais (parceiros e produtos)](docId:6xpQsdWQ2NTyI40BFqDS-)            |
| 4                   | [Vendas e CRM](docId\:TaINdkXLJcUzyq0xUuGfH)                                      |
| 5 (NF-e)            | [Fiscal — saída](docId\:jBJoVopyjL5-zOKm6FGbZ)                                    |
| 5 (conta a receber) | [Financeiro — títulos (contas a pagar e a receber)](docId\:D4kuGidayU2GQ-hMhF_T-) |
| 5 (estoque)         | [Estoque](docId\:CVozhYtoHDtuWZyT-bnAT)                                           |
| 5 (razão)           | [Contabilidade](docId:08cbTyrT0WXBp4ymvrog_)                                      |

Para entender por que cada peça existe, veja o *00-index.md* com as 15 seções na ordem do happy path.

Para vocabulário (CFOP, NCM, alçada, encontro de contas, etc.), veja o *glossario.md*.

## Erros comuns no quick start

***

- **Wizard de empresa preso no passo 2** — verifique se a razão social foi preenchida no passo 1 (com o tab no CNPJ raiz). Se não autopreencheu, digite manualmente.
- **Faturar diz "Almoxarifado obrigatório"** — você precisa ter pelo menos 1 almoxarifado cadastrado em **Estoque → Almoxarifados**, vinculado à matriz. Crie um simples (ALM-MTZ-01) e tente de novo.
- **NF-e fica em "Em processamento" e não muda** — em dev-standalone a autorização é simulada e quase instantânea. Se ficou parado, recarregue a tela; provavelmente já está Autorizada.
- **"Cliente bloqueado"** — em primeiro uso não deve aparecer. Se aparecer, verifique se o parceiro foi salvo com papel "Cliente" marcado (passo 2).


[title] Estrutura Analítica do Projeto (WBS)
[path] Aplicações/Agility/Backlog e planejamento/

:::BlockQuote
Organize um projeto Tradicional em uma hierarquia de pacotes de trabalho, com responsáveis, datas, progresso, marcos, dependências e situação.
:::

:::hint{type="info"}
**Pré-requisito:**

Use um projeto Tradicional com a capacidade WBS habilitada e dados de membros do Workspace para atribuir responsáveis. A tela não é carregada para projetos sem a capacidade correspondente.
:::

***

A WBS (Work Breakdown Structure) decompõe o projeto Tradicional em uma árvore de entregas e pacotes de trabalho. A tabela preserva pai e filhos, permite expandir ou recolher níveis e mostra um resumo do projeto antes da lista. Cada item pode ser acompanhado por código, responsável, período, progresso, marco, criticidade, dependências e situação.

A estrutura é editável diretamente na tela: crie uma raiz, acrescente filhos pelo item-pai, edite os campos ou arraste linhas para alterar a ordem e o nível. A aplicação envia cada alteração ao serviço de WBS e recarrega os dados; permissões de edição controlam a presença dos botões e da alça de arrastar.

***

### Passo a passo

::::WorkflowBlock
:::WorkflowBlockItem
**Abrir a WBS de um projeto Tradicional**

Abra um projeto Tradicional e clique em WBS. A página carrega o recurso tradicional do projeto e apresenta o título e a descrição da tela. Se o recurso estiver indisponível, use Tentar novamente após verificar a conectividade; se o projeto não tiver a capacidade WBS, a aplicação bloqueia a rota com a explicação correspondente.
:::

:::WorkflowBlockItem
**Ler o resumo e a tabela**

No topo, leia os cartões de resumo da WBS para ter a visão agregada do trabalho. Na tabela, Delivery mostra a árvore e o recuo, Código identifica o pacote, Responsável mostra o avatar ou Não atribuído, Prazo mostra início e fim, Progresso mostra barra e percentual e Indicadores sinaliza marco, caminho crítico e quantidade de dependências. Use o filtro textual da barra da tabela para localizar um título ou código.
:::

:::WorkflowBlockItem
**Criar o primeiro pacote**

Se a WBS estiver vazia, clique em Adicionar primeiro; se já houver itens, use Adicionar na barra da tabela para criar uma nova raiz. Informe um Título não vazio e, no editor rico, uma Descrição que delimite o trabalho. O novo item recebe a próxima ordem entre os itens do mesmo pai e aparece na árvore depois da confirmação.
:::

:::WorkflowBlockItem
**Preencher responsável e situação**

No formulário, selecione uma pessoa ativa em Responsável ou mantenha Nenhum responsável. Escolha Situação entre Não iniciado, Em andamento, Concluído e Bloqueado. Membros inativos não podem ser escolhidos para um novo vínculo; um responsável histórico continua visível no item que já o possuía, mas não pode ser selecionado novamente.
:::

:::WorkflowBlockItem
**Definir período e progresso**

Informe Data inicial e Data final pelos seletores de data. O formulário limita a data inicial para não ultrapassar a final e vice-versa. Ajuste Progresso pelo controle deslizante ou pelo campo numérico de 0 a 100. Marque Marco apenas quando o item representar um ponto de controle do cronograma.
:::

:::WorkflowBlockItem
**Configurar marco e dependências**

Quando Marco estiver marcado, informe as duas datas e use o mesmo dia: um marco precisa ter início e fim preenchidos e iguais. Em Dependências, selecione um ou mais itens existentes no combobox; o item atual não pode depender de si mesmo. A aplicação também verifica o grafo e recusa uma combinação que criaria ciclo.
:::

:::WorkflowBlockItem
**Criar filhos na hierarquia**

Na linha de um item, clique no botão Adicionar filho (ícone +). O mesmo formulário é aberto com aquele item como pai; repita os passos de título, descrição, responsável, situação, datas, progresso, marco e dependências. Salve para que o filho apareça indentado. Use o botão de expandir ou recolher ao lado do título para controlar a quantidade de níveis visíveis.
:::

:::WorkflowBlockItem
**Editar e excluir**

Use o lápis da linha para reabrir o item e ajustar qualquer campo. Salve alterações para persistir os dados e recarregar a árvore. O botão de lixeira abre uma confirmação; só confirme quando tiver certeza, pois a exclusão remove o item do recurso. Cancelar fecha o diálogo sem alterar a WBS.
:::

:::WorkflowBlockItem
**Reordenar ou reparentear por arraste**

Com permissão de edição, arraste uma linha pela alça vertical. Solte sobre outro item ou em sua posição para alterar a ordem; o recuo horizontal projeta se o item ficará como irmão ou filho e a tela abre o novo pai quando necessário. A operação envia as posições e os parentId dos itens ao servidor em conjunto. Enquanto grava, as alças ficam desabilitadas; se falhar, a árvore volta à posição anterior e mostra o alerta de reordenação.
:::

:::WorkflowBlockItem
**Usar o foco de um item**

Quando a WBS é aberta com um item focado a partir de outra tela, os ancestrais desse item são expandidos automaticamente e a linha recebe destaque e foco. Assim você consegue localizar um pacote profundo sem abrir manualmente cada nível; continue usando o controle de expansão para navegar pelos irmãos.
:::
::::

:::hint{type="success"}
:FontAwesome[]{icon="fa-solid fa-check"} **Verificação**

- A tabela exibe a hierarquia com recuos, controles de expandir/recolher e os dados de responsável, prazo, progresso e indicadores.
- Um pacote criado como raiz e um filho criado pelo botão + aparecem na ordem e no nível esperados após o recarregamento.
- Editar um item preserva os demais campos e alterar o responsável, datas ou progresso atualiza a linha correspondente.
- Um arraste aceito muda a ordem ou o pai; um erro de persistência restaura a ordem anterior e mostra um alerta.
:::

:::hint{type="warning"}
****:FontAwesome[****]{icon="fa-solid fa-triangle-exclamation"}**&#x20;Erros comuns**

**Progresso ou datas inválidos**

Use um progresso inteiro de 0 a 100 e uma data inicial que não seja posterior à final. Para um marco, as duas datas são obrigatórias e precisam ser o mesmo dia.

**Dependência recusada por ciclo**

Remova a dependência que aponta para o próprio item ou para um descendente. A WBS valida o grafo antes de salvar para evitar que um pacote dependa de algo que, direta ou indiretamente, depende dele.

**Não é possível atribuir um membro**

Escolha uma pessoa ativa do Workspace. Um membro inativo só pode permanecer como histórico de um item já atribuído; não pode receber novas tarefas na WBS.
:::


[title] Histórico de alterações e planejamento
[path] Aplicações/Agility/Backlog e planejamento/

:::BlockQuote
Acompanhe a trilha de auditoria do projeto e use a tela de Planejamento para governar requisitos, aprovações, entregas e conclusão.
:::

:::hint{type="info"}
**Pré-requisito:**

O projeto precisa ter as capacidades efetivas Histórico e Requisitos. O histórico é somente leitura; alterações são registradas automaticamente no momento em que o servidor grava uma entidade.
:::

***

Histórico é a trilha de versões do projeto, dos requisitos e das tarefas provisionadas no Board principal. Cada registro identifica a ação, o tipo de entidade, o código e o rótulo no momento da alteração, a versão, o autor, a data e a comparação dos campos de antes para depois. A tela não oferece editar, restaurar ou apagar uma versão: ela documenta o que realmente foi gravado.

Planejamento é a superfície de governança dos requisitos do projeto. Além de criar requisitos e exibir prioridade, origem e critério de aceite, ela permite aprovar, vincular entregas, desvincular relações e concluir quando a cadeia de entrega estiver completa. A filtragem e a trilha ajudam a explicar quando e por que uma decisão de planejamento foi tomada.

***

### Passo a passo

::::WorkflowBlock
:::WorkflowBlockItem
**Abrir o Histórico**

No projeto, selecione Histórico. Aguarde o carregamento da trilha; se o projeto não tiver a capacidade efetiva, a rota mostra Histórico indisponível e a explicação da permissão, sem fingir que não existem alterações. Em uma trilha populada, a versão mais recente aparece primeiro.
:::

:::WorkflowBlockItem
**Interpretar uma linha de versão**

Leia os marcadores de ação, como Cadastrou, Alterou ou Vinculou entrega, seguidos do tipo (Projeto, Requisito ou Tarefa). O código e o rótulo identificam a entidade, v4 por exemplo identifica a quarta versão, e a linha seguinte informa o ator projetado e o instante formatado. Se o diretório não resolver o nome, a tela usa Usuário indisponível em vez de expor um UUID.
:::

:::WorkflowBlockItem
**Ler a comparação de→para**

Em cada alteração, o nome do campo aparece com o valor anterior, uma seta e o novo valor. Cadastros mostram apenas o valor que passou a valer; remoções exibem o destino como um traço. Rótulos e enums são traduzidos para a linguagem da interface, como Situação, Rascunho e Aprovado, tornando a leitura útil para auditoria sem consultar o banco.
:::

:::WorkflowBlockItem
**Filtrar o escopo da trilha**

Use o seletor no canto do cartão para escolher Todas, Projeto, Requisito ou Tarefa. A seleção é enviada ao servidor como entityKind, e não apenas filtrada no navegador; desse modo, versões antigas daquela espécie não desaparecem por terem ficado fora do limite geral. Troque novamente para Todas para reconstruir a visão completa.
:::

:::WorkflowBlockItem
**Entender o limite de leitura**

Se a quantidade devolvida alcançar o limite, a mensagem Mostrando as alterações mais recentes informa que a lista é parcial. Isso é uma proteção de leitura, não uma indicação de que o histórico terminou. Use o filtro por espécie para concentrar a investigação, ou consulte a política de retenção da sua instalação quando precisar de uma auditoria mais antiga.
:::

:::WorkflowBlockItem
**Abrir o Planejamento**

Volte à navegação do projeto e selecione Planejamento. A tela carrega requisitos e, quando o projeto tem escopo SAFe, os épicos, features e histórias disponíveis para vínculo. Um projeto sem esse escopo continua podendo registrar requisito; nesse caso, os alvos da hierarquia ficam vazios e o vínculo com tarefa continua sendo feito no detalhe da tarefa.
:::

:::WorkflowBlockItem
**Registrar e priorizar uma necessidade**

Clique em Novo requisito e preencha Título, Descrição opcional, Origem, Prioridade (Alta, Média ou Baixa) e Critério de aceite. Após salvar, confira a linha RQ com situação Rascunho. Use a prioridade para ordenar a conversa de planejamento, sem substituir a justificativa da origem nem o critério verificável.
:::

:::WorkflowBlockItem
**Aprovar e acompanhar o estado**

Enquanto o requisito estiver em Rascunho, clique em Aprovar para marcá-lo como Aprovado. A linha oferece Concluir até chegar a Concluído, mas o servidor verifica a regra de negócio: sem entrega vinculada, a ação retorna uma mensagem explicando o que falta. Use o erro como orientação, vincule a entrega e tente novamente.
:::

:::WorkflowBlockItem
**Manter entregas e vínculos atualizados**

Clique em Vincular na linha e selecione um épico, feature ou história que ainda não esteja ligado. Para tarefas, vá ao cartão Requisitos atendidos na própria tarefa. Remova uma relação pelo ícone de desvincular e confirme que o histórico registra a ação de vínculo ou desvínculo, com a comparação do campo Entregas vinculadas.
:::

:::WorkflowBlockItem
**Usar as duas telas em uma auditoria**

Comece no Histórico filtrando Requisito para descobrir quando uma prioridade, situação ou entrega mudou. Abra Planejamento para conferir o estado atual, o critério de aceite e os destinos clicáveis. Se a mudança envolveu execução, filtre Tarefa e abra o detalhe da tarefa pelo caminho do requisito; assim a investigação conecta decisão, entrega e trabalho realizado.
:::
::::

:::hint{type="success"}
:FontAwesome[]{icon="fa-solid fa-check"} **Verificação**

- O Histórico mostra autor, instante, versão, ação e mudanças em ordem da mais recente para a mais antiga.
- O filtro de escopo muda a consulta e exibe somente Projeto, Requisito ou Tarefa quando selecionado.
- A comparação apresenta valores traduzidos de antes e depois, inclusive alterações de situação e entregas vinculadas.
- No Planejamento, um requisito aprovado mantém prioridade, origem e critério de aceite e só é concluído depois que uma entrega foi vinculada.
- Um vínculo ou desvínculo realizado no Planejamento ou no detalhe da tarefa aparece como evento rastreável no Histórico.
:::

:::hint{type="warning"}
****:FontAwesome[****]{icon="fa-solid fa-triangle-exclamation"}**&#x20;Erros comuns**

**O Histórico aparece indisponível**

Confirme que a capacidade Histórico está habilitada para o projeto e que sua permissão efetiva permite leitura. A tela bloqueia o acesso quando essa capacidade não está disponível; não há botão local para editar essa configuração.

**A trilha não mostra uma alteração esperada**

Confira o escopo selecionado e o limite indicado no rodapé. O servidor pode ter devolvido apenas as alterações mais recentes. Troque para Todas ou para a espécie correta e verifique se a operação realmente foi confirmada pela tela de origem.

**O planejamento fica sem alvos para vínculo**

É normal em projetos sem escopo SAFe: épicos, features e histórias são carregados como listas vazias. Crie ou associe a hierarquia SAFe quando fizer sentido; para uma tarefa existente, faça a ligação no detalhe da tarefa.

**A conclusão do requisito é recusada**

Leia o alerta devolvido pelo servidor e verifique a lista de entregas na linha. Vincule pelo menos uma entrega válida e confirme que ela permanece ligada antes de clicar em Concluir novamente.
:::


[title] Épicos, Features e Histórias
[path] Aplicações/Agility/SAFe — Backlog e execução/

:::BlockQuote
Organize o trabalho SAFe em três níveis rastreáveis: Épico, Feature e História, mantendo cada entrega ligada ao seu requisito pai.
:::

:::hint{type="info"}
**Pré-requisito:**

Tenha um ART ativo no Workspace e, para criar itens, uma sessão com capacidade de edição. O fluxo pressupõe que o ART e seus Times já foram configurados.
:::

***

A hierarquia SAFe do Agility começa no Épico, que expressa um objetivo amplo, passa pela Feature, que descreve um incremento de valor que pode ser priorizado e planejado, e termina na História, que representa o trabalho executável pelo time. O vínculo é descendente: uma Feature aponta para um Épico pai e uma História aponta para uma Feature pai.

A aba Épicos do ART apresenta o trabalho em um quadro com as situações Funil, Em análise, Pronto e Em implementação. O Backlog do ART reúne Features comuns e habilitadores (enablers), enquanto a História é criada a partir do contexto de um projeto e permanece rastreável ao seu pai. Os detalhes de cada nível exibem situação, descrição, vínculos e, quando aplicável, os fatores do WSJF.

***

### Passo a passo

::::WorkflowBlock
:::WorkflowBlockItem
**Abrir a aba de Épicos do ART**

Na navegação do Workspace, abra ARTs e selecione o trem desejado. Entre na aba Épicos. A página carrega os indicadores de quantidade de Épicos, Épicos em implementação, Features vinculadas e Épicos sem Feature. Use Board para acompanhar as colunas ou Tabela para consultar os mesmos itens em linhas.
:::

:::WorkflowBlockItem
**Criar o Épico**

Clique em Novo Épico. Informe o nome, selecione a situação inicial (o formulário começa na coluna de entrada, Funil), e registre uma descrição que explique o objetivo. O formulário também permite marcar Habilitador e escolher um responsável quando houver membros disponíveis. Para Épicos, preencha os quatro fatores WSJF antes de confirmar.
:::

:::WorkflowBlockItem
**Avaliar o Épico**

Depois de salvar, abra o cartão do Épico. O cartão exibe código, título, selo de Habilitador, quantidade de Features e o WSJF. No detalhe, a coluna principal mostra o objetivo e as Features do Épico; a lateral mostra o painel de cálculo e os vínculos do Programa, produto, release e Kanban. Clique em Editar para corrigir a descrição, a situação, os fatores ou o responsável.
:::

:::WorkflowBlockItem
**Criar uma Feature pelo Backlog do ART**

Abra Backlog na área do ART e clique em Nova Feature. Digite o título e escolha o tipo Feature ou Habilitador. Uma Feature habilitadora é o trabalho técnico, arquitetural ou de infraestrutura que sustenta uma entrega, mas ainda participa da priorização e do planejamento como qualquer outra Feature.
:::

:::WorkflowBlockItem
**Vincular a Feature ao Épico**

No campo Épico pai, selecione um Épico existente. O seletor oferece somente Épicos do próprio ART. Se nenhum pai adequado existir, escolha Criar Épico, informe o título do novo Épico e conclua o mesmo envio: o Agility cria o pai e usa seu identificador para criar a Feature, evitando deixar um Épico órfão quando o preenchimento é cancelado.
:::

:::WorkflowBlockItem
**Completar os dados da Feature**

Preencha a descrição, o ART textual quando o fluxo exigir essa referência, a release de destino e as horas estimadas. Atribua um responsável, selecione um ou mais Times e, se já existir, o PI candidato. Em seguida, escolha os quatro fatores WSJF nos chips da escala Fibonacci 1, 2, 3, 5, 8, 13 ou 21 e confirme em Criar Feature.
:::

:::WorkflowBlockItem
**Conferir o vínculo e o habilitador**

Na tabela ou no quadro do Backlog, a linha mostra o código e o título da Feature, o Épico, o responsável, os Times, o projeto, o WSJF, o PI candidato e o estado. O tipo Habilitador aparece como selo próprio. Abra a Feature para conferir, no painel Vínculos, o Épico pai, o ART, a release, as horas estimadas e o valor Sim/Não de Enabler.
:::

:::WorkflowBlockItem
**Criar a História ligada à Feature**

A História nasce no contexto de um projeto: abra o projeto SAFe, entre no Backlog e acione Novo item/História, ou use o ponto de criação disponível no quadro de Histórias. Informe o título e a descrição, selecione a Feature pai no campo obrigatório e escolha os story points na mesma escala Fibonacci. O formulário também permite marcar a História como Habilitador, indicar a iteração e atribuir um membro.
:::

:::WorkflowBlockItem
**Acompanhar a execução da História**

Abra o detalhe da História para verificar os vínculos com Feature, Épico, ART e iteração. O stepper de Progresso da história mostra as situações do quadro; clique em uma etapa para mover a História quando o trabalho avançar. O detalhe não calcula WSJF: a priorização ocorre no Épico e na Feature, enquanto a História usa a ordem da iteração e o tamanho em story points.
:::

:::WorkflowBlockItem
**Conferir rastreabilidade**

Use a seção de rastreabilidade no detalhe de cada nível para confirmar a origem do requisito e o que aconteceu com a entrega. A cadeia esperada é Épico → Feature → História. Se a Feature estiver sem pai ou a História sem Feature, volte ao formulário de edição e selecione o vínculo correto antes de iniciar o planejamento.
:::

:::WorkflowBlockItem
**Reordenar o trabalho no quadro**

Na aba Épicos, arraste um cartão entre Funil, Em análise, Pronto e Em implementação. O movimento é salvo como uma transição de situação após o drop e a tela recarrega a verdade do servidor. No Backlog, alterne entre Board e Tabela conforme a tarefa: o Board é útil para fluxo e a Tabela para comparar vínculos e priorização.
:::
::::

:::hint{type="success"}
****:FontAwesome[****]{icon="fa-solid fa-check"}**&#x20;Verificação**

- O Épico criado aparece em uma coluna do quadro e seu detalhe lista as Features filhas.
- A Feature mostra o Épico pai no painel Vínculos e, quando habilitadora, exibe o selo Habilitador.
- A História exibe Feature pai e Épico no detalhe, além de story points, situação e iteração.
- A cadeia Épico → Feature → História pode ser percorrida sem perder o contexto do ART ou do projeto.
:::

:::hint{type="warning"}
****:FontAwesome[****]{icon="fa-solid fa-triangle-exclamation"}**&#x20;Erros comuns**

**Feature ou História sem pai**

O formulário não envia uma Feature sem Épico pai nem uma História sem Feature pai. Se a mensagem solicitar a seleção do pai, volte ao respectivo seletor; a lista é carregada do programa/ART atual.

**Título vazio**

O botão de envio permanece indisponível ou o envio é ignorado quando o título contém somente espaços. Informe um nome significativo antes de salvar.

**Épico criado sem Feature**

Criar o pai acontece dentro do envio da Feature. Se o título do Épico novo estiver vazio, o botão fica bloqueado; preencha-o ou selecione um Épico existente para não interromper o vínculo.

**História confundida com item WSJF**

Histórias não têm painel WSJF. Ajuste a prioridade no Épico ou na Feature e use os story points para dimensionar a História; não tente interpretar a ausência de WSJF como erro de carregamento.
:::


[title] AIOPS - inteligência artificial para operações
[path] Aplicações/

**AIOPS - inteligência artificial para operações** - é uma plataforma de recursos de inteligência artificial (IA), com modelos de aprendizado de máquina, para automatizar e simplificar o gerenciamento de serviços, operações de TI e fluxos de trabalho operacionais. Ela fornece uma visão 360º de toda a unidade de um datacenter (on-premises, nuvem ou híbrida). Gerencia ativamente eventos e incidentes, bem como realiza monitoramento suportado por IA, e executa automações através da base de conhecimento acionável, topologia automática e auto recuperação de ambientes ou equipamentos.&#x20;

[https://docs.citsmart.com/aiops](https://docs.citsmart.com/aiops)

[title] Gestão por indicadores
[path] Aplicações/ERP/Manual do Usuário/

# Gestão por indicadores (planejamento estratégico e desempenho)

:::BlockQuote
Pré-requisitos: nenhum obrigatório para começar. Para vincular um objetivo a uma **área** e a um **responsável**, tenha antes os departamentos e servidores cadastrados (ver [Administração](docId\:Z8SS7r6Bvhs09rP1SPxUD)) — mas um objetivo **sem** responsável também é válido.
:::

## Introdução

***

A **Gestão por indicadores** é o módulo em que o órgão registra o seu planejamento estratégico e acompanha, mês a mês, se está entregando o que prometeu à sociedade. Tudo é **nativo** e mora na mesma base do ERP: o número que aparece no semáforo vem do próprio dado transacional, sem planilha paralela e sem ferramenta de BI externa — por isso ele é auditável e contestável.

O caminho é sempre o mesmo, de cima para baixo: você abre um **ciclo** (a versão do plano daquele período), organiza as **perspectivas** (as grandes lentes do plano — no setor público a *Sociedade* fica no topo), pendura os **objetivos** sob cada perspectiva, cria os **indicadores** (as fichas de KPI que medem cada objetivo), define as **metas** de cada indicador por período e, ao longo do exercício, registra as **apurações** (o valor realizado). O **Painel de desempenho** cruza meta × realizado e pinta o semáforo. Quando um indicador desvia, você abre um **plano de ação** (5W2H) e registra a **análise de causa-raiz**. As quatro telas de entrada ficam no menu lateral, no grupo **Gestão por indicadores**: *Planejamento estratégico*, *Indicadores*, *Painel de desempenho* e *Painel gerencial* — o **Painel de desempenho** é a grade linha a linha (um indicador em um período, com o seu farol), e o **Painel gerencial** é a mesma verdade vista de cima (o ciclo consolidado, por nível e por área, com o mapa estratégico e os gráficos). Toda tela tem o botão **Ajuda** (o "?" no topo), com uma orientação curta e as armadilhas de cada passo.

As telas do módulo foram verificadas no celular (375 px), no tablet retrato (768 px) e no laptop (1024 px, com a barra lateral aberta): a página não rola de lado, o acesso ao menu e o botão de sair continuam dentro da tela, e a grade larga do painel rola dentro do seu próprio quadro. Abrir no telefone não é o mesmo que **servir** no telefone — o que foi conferido é o alcance de cada controle, não a aparência da tela.

## Passo a passo

***

### 1. Abrir o planejamento e criar o ciclo

1. **Abra o planejamento estratégico.** No menu lateral, em **Gestão por indicadores → Planejamento estratégico**. A tela lista os ciclos já existentes com nome, período, lente e situação.
2. **Crie um ciclo.** Clique em **Novo ciclo** e informe o **nome** (ex.: Plano Estratégico 2026), o **período** (ex.: 01/01/2026 a 31/12/2026) e a **lente** de gestão — *Balanced Scorecard (BSC)*, *OKR* ou *Gestão por Diretrizes (GPD)*. A lente é só a forma de olhar: ela troca o vocabulário e a forma de pontuar o atingimento, mas não muda os dados, e pode ser trocada a qualquer momento enquanto o ciclo não estiver fechado.
3. **Ative o ciclo.** Um ciclo nasce como **Rascunho**. Clique em **Ativar** (a seta na linha do ciclo, ou o botão dentro do ciclo) para passá-lo a **Ativo** — só um ciclo ativo aceita objetivos, indicadores e apurações. Ao final do exercício, **Fechar** congela o ciclo para comparação com os próximos (um ciclo fechado é somente leitura).

### 2. Ajustar as perspectivas e criar os objetivos

1. **Abra o ciclo.** Clique no nome do ciclo para entrar no detalhe. O ciclo já nasce com as **quatro perspectivas clássicas do Balanced Scorecard**, em inglês (Financial, Customers, Internal Processes, Learning and Growth) — elas são um ponto de partida para você **renomear** para o seu contexto.
2. **Renomeie e reordene as perspectivas.** Use o lápis para renomear (ex.: Sociedade, Processos Internos, Aprendizado & Crescimento, Orçamentária) e as setas para reordenar. No setor público, a **Sociedade** vai para o topo, invertendo a ordem clássica do setor privado. Você também pode **Adicionar perspectiva** ou remover as que não usar.
3. **Crie os objetivos.** Na seção **Objetivos**, clique em **Novo objetivo**. Informe o **Título** (ex.: Ampliar a satisfação do cidadão), a **Descrição**, o **Nível** — *Missão*, *Visão*, *Estratégico*, *Tático* ou *Operacional* —, a **Perspectiva** a que ele pertence e, opcionalmente, a **Área** e o **Responsável**. Em **Aferição**, escolha *Quantitativo* ou *Qualitativo*. **Missão** e **Visão** são diretrizes, não metas: a razão de existir do órgão e o estado futuro que ele persegue — cadastre cada uma como um objetivo do seu nível, para que o plano não comece já no estratégico, sem a diretriz que o justifica. O **Nível** é descritivo: quem liga um objetivo ao outro é o **Desdobrar**, não o nível — pôr Operacional num objetivo não o pendura em ninguém.
4. **Desdobre em cascata (opcional).** Use **Desdobrar** para ligar um objetivo de topo aos seus objetivos táticos e operacionais. Um objetivo-filho pode sustentar **mais de um** pai — o desdobramento é uma teia, não uma árvore.
5. **Dê o peso ao desdobrar — é o peso que faz o número subir.** No formulário **Desdobrar objetivo** você escolhe o **Objetivo-pai (acima)**, o **Objetivo-filho (abaixo)**, o **Tipo de vínculo** (*Desdobramento*, *Causa e efeito* ou *Apoio*) e o **Peso**. O peso não é enfeite: o resultado de cada objetivo de baixo sobe **ponderado** por ele até o objetivo de cima. Um objetivo estratégico sem indicador próprio, com dois filhos de peso 3 e 1 medidos em 100% e 20%, fecha em **80%** — não em 60%. Se o pai tiver indicador próprio, o resultado dele entra na conta com peso 1. **Peso** em branco vale 1; peso 0 (ou negativo) tira o filho da conta **em silêncio** — se um filho parece não influenciar o pai, confira o peso antes de duvidar da medição.
6. **Leia o resultado que subiu.** O alinhamento medido aparece no **Painel gerencial** (menu **Gestão por indicadores → Painel gerencial**), no bloco **Mapa estratégico**: cada objetivo mostra o farol e o percentual consolidado, e o que se desdobra dele aparece indentado logo abaixo, com o tipo de vínculo e o peso. Para ver separado o que é do próprio objetivo e o que veio de baixo, use **Fixar no meu painel** no card do objetivo — em **Meu painel** ele passa a exibir **Próprio** e **Consolidado** lado a lado. Duas leituras que enganam: o farol de um objetivo é o **pior caso entre os indicadores dele mesmo**, e não é herdado dos filhos — um objetivo estratégico sem indicador próprio aparece com o farol **Sem meta** mesmo carregando um consolidado alto; e objetivo sem nenhuma medição mostra **—**, nunca 0%, porque zero é um resultado ruim e "não medido" é ausência de informação.

### 3. Detalhar o objetivo e criar o indicador

1. **Abra o objetivo.** Na lista de objetivos do ciclo, clique no objetivo. O detalhe mostra a descrição, a perspectiva, a área, o responsável e a data de criação, além da seção **Indicadores**.
2. **Crie o indicador.** Clique em **Novo indicador** e preencha a ficha de KPI: **nome** (ex.: Execução Orçamentária), **unidade** (%, dias, h…), a **polaridade** (qual direção é boa — *Maior é melhor*, *Menor é melhor*, *No alvo é melhor* ou *Estabilizar*), o **tipo de medida** (Instantâneo, Acumulado, Média) e a **periodicidade de apuração** (Mensal, Trimestral, Anual…). A polaridade é essencial: sem ela, um número como "80" não pode ser lido como bom ou ruim. Marque **Sigiloso** quando o número não puder circular — e saiba o que a marca faz, porque a consequência é silenciosa. Um indicador sigiloso **não dispara o alerta automático de desvio**: ele pode estourar a meta e ninguém é avisado, já que o alerta sairia para todos os usuários ativos levando o nome do indicador junto. E a conversa e o compartilhamento dele ficam restritos a quem administra o planejamento — para os demais, os comentários são recusados, e compartilhar com uma área não notifica ninguém. Sigiloso quer dizer que o desvio dele **você** tem que ir olhar.
3. **Complete o resto da ficha.** Informe a **linha de base** (o valor de onde você partiu) e a **data da linha de base**, e o **prazo máximo de apuração (dias)** — o prazo para fechar um período. Sem linha de base o indicador mostra se você chegou à meta, mas não mostra o quanto andou desde o início do plano.
4. **Diga como o indicador é alimentado.** No campo **Como é alimentado** escolha **Manual** (alguém digita o valor de cada período) ou **Calculado** (o sistema lê o próprio dado do ERP e calcula). Ao marcar **Calculado**, a ficha cresce: aparecem a origem do cálculo, a métrica e a apuração automática. A escolha também muda a seção **Apurações** do indicador: no calculado você deixa de digitar valor.
5. **Escolha a métrica do catálogo.** Em **Origem do cálculo**, deixe **Uma métrica do catálogo** e abra **Métrica do catálogo**. A lista vem agrupada por módulo. Hoje o catálogo tem **11 métricas em 10 módulos**: **Financeiro** (*Saldo de contas a receber em aberto* e *Saldo de contas a pagar em aberto*), **Vendas**, **Compras**, **Estoque**, **Custos e orçamento**, **Folha de pagamento**, **Patrimônio**, **Frota e manutenção**, **Contabilidade** e **Jurídico**. O catálogo é **fechado**: você escolhe de uma lista pronta, não escreve consulta ao banco — cada métrica é um item que o sistema já sabe calcular e rastrear, e é isso que impede um indicador de ler o que não deveria. A armadilha está no formato do número: as duas do **Financeiro** são **saldo** (uma foto do momento da apuração, que não é recortada pelo período); as outras nove são **movimento do período**. Ligar um indicador mensal a um saldo é legítimo, mas o número responde "quanto há hoje", não "quanto aconteceu no mês".
6. **Ou componha uma fórmula.** Troque **Origem do cálculo** para **Fórmula sobre métricas** e escreva a conta no campo **Fórmula** — por exemplo \{SALES.REVENUE} / \{PURCHASING.ORDERED\_VALUE} \* 100. Não digite o nome da métrica de cabeça: use o combo **Inserir uma métrica**, que acrescenta a referência no formato certo **no fim** do que já está escrito (monte a conta na ordem, ou ajuste o texto depois). Só métricas do catálogo podem ser citadas: um nome fora da lista é **recusado** ao testar e ao salvar — não vira zero silencioso. Uma fórmula sem nenhuma métrica também é recusada, porque um número fixo devolveria sempre o mesmo resultado parecendo um indicador vivo.
7. **Teste a fórmula antes de salvar.** Clique em **Testar fórmula**. O sistema roda a conta sobre o **mês corrente** (do dia 1º até hoje) e mostra o **Resultado:** e a **Memória de cálculo** — cada parcela com o seu valor. Sem o teste, o erro de conta só aparece depois que o cartão foi aprovado e já pintou o painel; com o teste, ele custa um clique.
8. **Ligue a apuração automática.** Marque **Apurar automaticamente na periodicidade** — a caixa só existe no indicador calculado. Toda madrugada o sistema atualiza o valor do período em aberto e, quando o período vira, congela o último valor do período que fechou, na periodicidade da própria ficha. A armadilha: a varredura só pega indicador **Aprovado**. Enquanto o selo no topo disser **Rascunho** ou **Aguardando aprovação**, ele é pulado — envie para aprovação e efetive antes de esperar número.
9. **Saiba que o indicador nasce em rascunho.** A ficha recém-criada recebe o selo **Rascunho** e ainda não é oficial: ela não entra no **Painel de desempenho**, não é apurada automaticamente e não dispara alerta de desvio. Quem libera é outra pessoa, e o passo 5 mostra como enviar e efetivar. A lista de **Indicadores** não exibe esse selo — para saber a situação de um indicador, abra a ficha dele.

### 4. A lista de indicadores

Toda a carteira de indicadores do órgão também pode ser consultada de uma vez pela tela **Indicadores** (menu **Gestão por indicadores → Indicadores**). Cada linha mostra a unidade, a polaridade, a periodicidade e se o indicador está **vinculado** a um objetivo. Clique em qualquer um para abrir a ficha completa.



![](https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/21-indicadores-04-indicadores.png)

### 5. Meta, aprovação, apuração e retificação

1. **Abra o indicador.** Na ficha do indicador você define as metas e registra os valores realizados.
2. **Defina a meta.** Na seção **Metas**, clique em **Nova meta** e informe o **período**, o **valor da meta** (ex.: 85) e a **faixa de tolerância** — a zona amarela do semáforo. A faixa precisa ficar do **lado certo** da meta: **abaixo** dela para *Maior é melhor*, **acima** para *Menor é melhor*, **cercando** para *No alvo é melhor*. Uma faixa no lado errado é recusada, porque pintaria de verde um resultado ruim. Ainda dá para informar **peso**, **tipo de compromisso** (Comprometida, Esticada, Aspiracional) e o **critério de aceitação**.
3. **Envie o indicador e a meta para aprovação.** Os dois nascem em **Rascunho**, e nada em rascunho conta. Quem tem **Gerenciar indicadores e metas** clica em **Enviar para aprovação** — o botão do indicador fica no topo da ficha, ao lado do selo de situação; o da meta, na própria linha da meta. Cada selo passa a **Aguardando aprovação**. Enquanto estiverem assim, o **Painel de desempenho** não mostra linha nenhuma para esse indicador: o painel só enxerga o que está **Aprovado**.
4. **Peça a decisão e efetive.** Quem decide é outra pessoa, com a permissão **Aprovar solicitações (alçada)**, em **Início → Solicitações de aprovação**. O pedido aparece lá com o módulo **Indicadores**, a operação **Aprovação de indicador** ou **Aprovação de meta** e o **Solicitado por**. Quem enviou não pode aprovar o próprio pedido — o sistema recusa. Depois do **Aprovar**, volte à ficha e clique em **Efetivar aprovação**: só nesse clique o selo vira **Aprovado** e a linha entra no painel. Aprovar não efetiva sozinho — se você parar no clique do aprovador, o selo continua **Aguardando aprovação** e o painel continua vazio.
5. **Se for recusado, volte para rascunho.** O aprovador pode **Recusar**, com uma **Observação**. A ficha não avisa: o selo continua **Aguardando aprovação** e **Efetivar aprovação** passa a ser negado, dizendo que a meta (ou o indicador) ainda não foi aprovada. Clique em **Voltar para rascunho**, corrija e envie de novo. A observação da recusa fica registrada na solicitação, com o aprovador — a ficha não a mostra, então combine a correção com ele.
6. **Editar o que já está aprovado derruba a aprovação.** Alterar a meta — ou a ficha do indicador — devolve o selo a **Rascunho** e limpa a aprovação: a linha sai do painel na hora e precisa de nova decisão. É proposital: vale o número que foi aprovado, não o que veio depois. Por isso uma ficha aprovada não oferece **Enviar para aprovação** — o caminho é editar, o que a devolve a rascunho, e enviar de novo.
7. **Registre a apuração.** Na seção **Apurações**, você pode salvar um valor **em andamento** (estimativa parcial do período em aberto) e depois **congelar** o valor oficial do período. Um período congelado não é sobrescrito.
8. **Retifique sem apagar.** Se o valor congelado precisar de correção, use **Retificar**: o sistema **exige uma justificativa**, preserva o valor anterior e cria uma nova versão vigente. A ficha marca a apuração como **Retificado v2**, e o ícone de histórico mostra todas as versões — essa é a análise histórica que o controle exige.
9. **No indicador calculado, você não digita a apuração.** A seção **Apurações** troca os botões: em vez de **Nova apuração**, aparecem **Recalcular agora** e **Apurar agora**. **Recalcular agora** atualiza só o valor do período em aberto — não fecha o período anterior e não toca em período já congelado. **Apurar agora** abre **Apurar a partir da métrica**: informe **Início do período** e **Fim do período**, e o sistema calcula e **congela** o valor daquele período. O valor não é digitado porque ele precisa continuar batendo com a memória de cálculo — um número escrito à mão no período aberto seria substituído no recálculo seguinte.
10. **Leia a memória de cálculo.** Clique no ícone **Histórico de retificação** na linha do período. Cada versão mostra o valor, a data e, embaixo, a nota gravada no momento do cálculo: a fórmula, a janela apurada e cada parcela com o seu valor. É texto técnico, guardado exatamente como o sistema calculou — de propósito, para o auditor refazer a conta à mão e chegar ao mesmo número. É essa nota que sustenta a promessa de que o indicador vem do dado transacional, e não de uma planilha.
11. **Desconfie do período sem dado.** Uma métrica sem movimento no período **não** dá erro: ela devolve **zero**, e a memória de cálculo diz de onde veio esse zero. Zero é um número — ele congela e o painel o compara com a meta, pintando **vermelho** num indicador *Maior é melhor*. Antes de congelar, leia a nota: "zero porque não houve movimento" e "zero porque o módulo de origem não está disponível" pintam o mesmo vermelho e significam coisas muito diferentes.

### 6. Aviso automático de desvio

Você não precisa abrir o painel todo dia para descobrir que um indicador furou a meta: quando um período fecha fora da meta, o sistema avisa sozinho.

1. **Congele o período.** Na seção **Apurações**, salve a apuração no modo **Congelar (oficial)** — ou use **Apurar agora**, no indicador calculado. No mesmo instante o sistema compara o valor oficial com a meta do período e, se o farol ficar **vermelho**, dispara o aviso. Um valor salvo como **Em andamento** nunca dispara nada: estimativa parcial de um mês em aberto não é desvio, e avisar sobre ela só geraria ruído e descrédito.
2. **Receba o aviso pelos dois canais.** O aviso sai ao mesmo tempo pelo **sino** no topo do portal (ver *14 — Frota e Notificações*) e por **e-mail**. O assunto é **Indicador fora da meta**, e o corpo traz o indicador, o período, o realizado e a meta (ex.: "realizado 80 vs. meta 100"), pedindo o registro da análise de desvio. Hoje o aviso vai para **todos os usuários ativos**, e não só para o responsável pelo objetivo — por isso você pode receber o desvio de um indicador de outra secretaria.
3. **Conte com um aviso por desvio, não um por dia.** Um período já avisado não é avisado de novo, mesmo continuando vermelho: além do disparo imediato, o sistema varre de madrugada (por padrão às 2h30) os períodos congelados que ainda não geraram aviso, e pula os já avisados. Quem **reabre** o aviso é a **retificação** — corrigir o valor cria uma nova versão, que volta a ser avaliada do zero e gera um aviso novo se também ficar fora da meta. É isso que impede o sino de virar enxurrada.
4. **Saiba por que às vezes o aviso não vem.** Quatro situações silenciam o aviso de propósito: a ficha do indicador ou a meta do período ainda está em **Rascunho** ou **Aguardando aprovação** (sem número aprovado não existe "desvio" — o aviso sai quando a aprovação sair); o farol ficou **amarelo**, dentro da faixa de tolerância (só vermelho alerta); o indicador está marcado como **Sigiloso**, e o nome dele não é enviado em massa a todos os usuários; ou você mesmo desligou esse tipo ou canal em **Início → Preferências de notificação**. E, no indicador que apura automaticamente, o aviso chega na varredura da madrugada seguinte, não no instante — porque quem fechou o período foi o trabalho noturno.

### 7. Plano de ação (5W2H, PDCA e causa-raiz)

Quando um indicador desvia da meta — e você foi avisado pelo passo anterior —, abra um **plano de ação** a partir da própria ficha do indicador (seção **Planos de ação → Novo plano**).



![](https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/21-indicadores-06-plano-acao.png)

1. **Detalhe as ações no 5W2H.** Cada ação responde às sete perguntas: **o quê** (título), **por quê** (motivo), **onde** (área), **quem** (responsável), **quando** (prazo), **como** (método) e **quanto** (custo). Cada ação tem um **status** (A fazer, Fazendo, Feito, Bloqueado, Cancelado) e uma **fase do PDCA** (Planejar, Executar, Checar, Agir) — o ciclo de melhoria contínua.
2. **Analise a causa-raiz.** Na seção **Análise de causa-raiz**, desdobre o desvio em causas encadeadas (técnica de *Ishikawa* / *5 Porquês*): uma causa pode ter causas-filhas, e as folhas do fundo são marcadas como **raiz**. É a raiz que orienta as ações que resolvem o problema, não só o sintoma.
3. **Acompanhe a evolução.** O plano também passa por aprovação: nasce em **Rascunho**, vai a **Aguardando aprovação** pelo botão **Enviar para aprovação** e só chega a **Em andamento** quando alguém aprova na bandeja e você clica em **Ativar** — ativar sem aprovação é recusado. Depois vira **Concluído**, e toda a trilha de auditoria fica registrada.

### 8. Painel de desempenho

1. **Abra o painel.** No menu **Gestão por indicadores → Painel de desempenho**, selecione o **ciclo**. A grade cruza, para cada indicador e período, a **meta** com o **realizado**, calcula a **variação** e o **desempenho** (o atingimento, pontuado conforme a lente do ciclo) e pinta o **farol**.
2. **Leia o semáforo.** **Verde** = na meta ou acima; **Amarelo** = dentro da faixa de tolerância; **Vermelho** = além da faixa, no sentido ruim. A cor respeita a polaridade — o mesmo número é verde para um indicador *Maior é melhor* e vermelho para um *Menor é melhor*. Um indicador **sem meta** (ou ainda não apurado) no período mostra **Sem meta**, e **não** vermelho — meta ausente não é estouro.
3. **Desça à origem.** Clique numa linha para abrir o **detalhamento**: as versões da medição daquele período (incluindo o histórico de retificação), provando de onde veio o número.
4. **Exporte.** O botão **Exportar CSV** manda a grade inteira para planilha.

### 9. Painel gerencial

O **Painel de desempenho** responde "como está o indicador X no período Y?". O **Painel gerencial** responde as outras três perguntas: como está o plano no conjunto, qual nível está travando e qual área puxa o resultado para baixo. As duas telas leem os **mesmos** números — a conta é a mesma da grade e do CSV, então o painel nunca discorda da planilha que você exportou para conferir.

1. **Abra o painel gerencial.** No menu **Gestão por indicadores → Painel gerencial**, escolha o ciclo em **Selecione um ciclo…**. Enquanto nenhum ciclo estiver escolhido, a tela mostra só "Escolha um ciclo para ver o desempenho consolidado" — mas os dois blocos do fim (**Compartilhado com a minha área** e **Meu painel**) aparecem assim mesmo, porque não dependem do ciclo.
2. **Leia os quatro cartões.** **Objetivos**, **Indicadores**, **Atingimento médio** e **Fora da meta**. Embaixo do atingimento vem a contagem "3 de 4 períodos medidos" — leia essa contagem antes de concluir qualquer coisa: 96% apurados sobre 1 de 12 períodos não é um plano em dia. Quando nada foi medido, o atingimento e o **Fora da meta** mostram um travessão (—), nunca zero: falta de informação não é bom resultado, e um "0" verde diria exatamente o contrário. O atingimento é a **média simples** das apurações; o **peso** do objetivo só vale no mapa, no consolidado de cada objetivo.
3. **Veja a distribuição do farol.** O gráfico em anel **Distribuição do farol** separa as medições em **Verde**, **Amarelo**, **Vermelho** e **Sem meta**. Ele conta **apurações** (indicador × período), não indicadores — o mesmo indicador entra em vermelho num mês e em verde no outro. Ciclo sem nenhuma medição mostra "Nada medido neste ciclo ainda.".
4. **Corte por nível e por área.** Duas tabelas lado a lado, **Por nível de desdobramento** (Estratégico, Tático, Operacional…) e **Por área**, com as colunas **Agrupamento**, **Indicadores**, **Medidos** (medidos/total) e **Atingimento**. Um nível sem nenhum objetivo é **omitido**, não aparece zerado: a prefeitura pequena que legitimamente não tem camada tática leria uma linha de zeros como fracasso. Objetivo sem área cai em **Sem área atribuída**; se a área foi informada mas não foi encontrada no cadastro, a linha diz **Área não resolvida** — são coisas diferentes e a tela não as mistura.
5. **Leia o mapa estratégico.** O bloco **Mapa estratégico** desenha o plano: uma faixa por perspectiva, um cartão por objetivo com o farol e o percentual consolidado, e o que se desdobra dele indentado abaixo, com o tipo de ligação (**Desdobramento**, **Causa e efeito**, **Apoio**), o **peso** e a marca **não consolida** quando aquele filho não entra na conta do pai. Objetivo sem perspectiva não some do mapa: ele vai para a faixa **Sem perspectiva**, no fim. Se essa faixa está cheia, o que falta arrumar é a perspectiva dos objetivos, não o mapa. Objetivo sigiloso aparece como **Objetivo reservado** para quem não administra o planejamento — o farol e o peso continuam à vista, porque escondê-lo mudaria o consolidado que o leitor tem direito de ver.
6. **Veja a curva de um indicador.** No bloco **Indicador no tempo**, escolha em **Escolha um indicador…**. O gráfico traça o realizado e, tracejada, a meta de cada período. Onde não houve apuração a linha **interrompe** em vez de descer — unir os pontos desenharia uma queda que nunca aconteceu. Duas armadilhas: o combo lista **toda** a carteira de indicadores do órgão, não só os do ciclo selecionado; e indicador sem nenhum período apurado mostra "Este indicador ainda não tem período medido.".
7. **Monte o seu painel.** Use **Fixar no meu painel** — o mapa inteiro pelo cabeçalho do mapa, um objetivo pelo alfinete no cartão dele, o indicador escolhido ao lado do combo — e **Fixar o resumo do ciclo**, no cabeçalho do bloco **Indicador no tempo**. O que você fixa aparece em **Meu painel**, no fim da tela, já desenhado (a curva, o resumo, o mapa), com **Mover para cima**, **Mover para baixo** e **Remover do meu painel**. O painel é **seu**: ninguém mais vê o que você fixou e ninguém reordena o que é seu. Fixar também não amplia o que você enxerga — o widget mostra só o que você já poderia abrir. Dois limites que aparecem como recusa: o mesmo item não entra duas vezes ("Este widget já está no seu painel.") e o painel guarda no máximo 24 widgets ("Seu painel já tem o máximo de 24 widgets."). E widget fixado em outro ciclo não mostra número de plano errado: ele avisa "Fixado em outro ciclo — selecione-o acima para ver este widget.".
8. **Veja o que outra área apontou para você.** O bloco **Compartilhado com a minha área**, no fim da tela, é o lado receptor do compartilhamento — cada linha é um link que abre o item que outra área mandou você olhar. Como se compartilha, e o que o colega passa (ou não) a poder ver, está na página [Fiscal — entrada](docId:1_QpvYmn6apZ9mqx87Z4K).

### 10. Discussão e compartilhamento entre áreas

O indicador, o plano de ação e a apuração de um período carregam um painel de colaboração com duas caixas — **Discussão** e **Compartilhado com**. É ali que a explicação do desvio fica registrada junto do número, em vez de morrer no e-mail de uma pessoa só, e é dali que uma área chama a outra para agir.

1. **Abra o painel.** Ele fica no fim da **ficha do indicador**, no fim do **plano de ação** e dentro do **detalhamento** de uma célula do Painel de desempenho (a janela **Medições de origem**). É o mesmo painel nos três lugares, mas cada um conversa sobre o seu próprio item — o indicador, o plano ou o número daquele período. No detalhamento, a conversa se prende à versão **Vigente** da apuração: se você **retificar** o valor, a vigente passa a ser outra e o painel abre uma conversa nova, em branco — a anterior fica presa à versão corrigida e não volta a aparecer ali. Conversa que precisa sobreviver à correção deve ser escrita na ficha do indicador ou no plano de ação, que não versionam.
2. **Comente e responda.** Escreva no campo de texto (limite de 4.000 caracteres) e clique em **Comentar**. Use **Responder** para encadear a resposta, que fica aninhada sob o comentário original. Quem já escreveu na conversa recebe o aviso no sino, no canto superior direito do portal. Mas **o primeiro comentário não avisa ninguém** — ainda não há ninguém na conversa. Para chamar outra área, o caminho é o compartilhamento do passo 4, não o comentário.
3. **Remova sabendo que o texto fica.** A lixeira (**Remover comentário**) risca o comentário e carimba **removido por** com o nome de quem removeu — o texto continua visível na conversa. É proposital: o comentário é o registro da interação, e registro que some deixa a discussão ser reescrita meses depois, quando o controle interno perguntar o que foi combinado. Você remove só os seus; quem gerencia a estratégia remove o de qualquer um.
4. **Compartilhe com a área que precisa agir.** Na caixa **Compartilhado com**, escolha a **Área**, escreva em **Observação** o que aquela área deve olhar e clique em **Compartilhar**. Quem está lotado nessa área **hoje** (lotação futura não conta) recebe o aviso no sino e passa a ver o item na lista **Compartilhado com a minha área**, no **Painel gerencial** — a apuração leva à grade do Painel de desempenho, que é onde ela se lê. Duas armadilhas: **compartilhar aponta, não concede** — o colega é chamado, mas continua passando pela permissão dele, e sem acesso à tela o link não abre; e item **sigiloso** não gera aviso nenhum, porque o título entregaria à área justamente o nome que o painel esconde (para quem não gerencia a estratégia, o painel de discussão nem aparece na tela). A mesma área duas vezes é recusada — não são dois fatos —, e a lixeira (**Retirar o compartilhamento**) desfaz o apontamento **sem deixar rastro**, ao contrário do comentário removido.

### 11. Perfis de acesso do módulo

A autoridade neste ERP é do **cargo**, não do usuário: quem entra na Gestão por indicadores é quem ocupa um dos cargos do módulo. São três, e eles **não se sobrepõem** — cada um faz uma parte do trabalho.

1. **Conheça os três perfis.** Em **Recursos humanos → Cargos** eles aparecem com o nome de cadastro, em inglês (você pode renomeá-los ali mesmo — o que vale é o cargo, não o nome)\:Além dos três, o cargo **Auditor** também entra no módulo: lê tudo e não altera nada. A divisão é proposital — quem define a meta não é quem registra o número que vai ser comparado com ela.
   - **Strategy Director** (a diretoria) — monta o plano: cria, ativa e fecha o ciclo, renomeia e reordena as perspectivas, cria e desdobra os objetivos. Lê o painel. **Não** cria nem edita ficha de indicador ou meta, **não** registra apuração e **não** abre plano de ação.
   - **Performance Manager** (o gestor) — cuida dos números: ficha de indicador, metas, apurações, retificação e planos de ação. Lê o painel. **Não** cria ciclo e **não** mexe em perspectiva nem em objetivo.
   - **Operational Analyst** (o operacional) — registra e retifica a apuração do período. Lê o painel. **Não** cria indicador, meta nem plano de ação.
2. **Atribua o cargo pela lotação.** O vínculo entre a pessoa e o cargo é a **lotação** do empregado, no bloco **Lotação** da ficha (ver *13 — Administração*). Quem não ocupa nenhum desses cargos **não entra** no módulo — nem para olhar o painel. Não é bloqueio parcial: a tela recusa. Se o seu órgão já usava o módulo antes de os perfis existirem, todo mundo perde o acesso até receber um cargo.
3. **Confira as permissões em Alçada.** Em **Início → Alçada** as cinco operações do módulo aparecem pelo nome: *Gerenciar planejamento estratégico*, *Gerenciar indicadores e metas*, *Registrar e retificar medições*, *Ver painel de desempenho* e *Gerenciar planos de ação*. É ali que você amarra uma operação a outro cargo, se a sua estrutura for diferente. Cuidado com o caminho inverso: uma operação que fica **sem nenhuma regra ativa** volta a ser liberada a qualquer usuário autenticado — apagar a última regra não fecha a porta, abre.
4. **Entenda por que um indicador "some".** Quem tem apenas *Ver painel de desempenho* — diretoria, operacional e auditoria — enxerga somente os indicadores e as metas já **Aprovado**. O que está em **Rascunho** ou **Aguardando aprovação** aparece só para o gestor, que é quem está construindo. Um indicador que sumiu para a diretoria quase sempre é um indicador ainda não aprovado, não um indicador apagado.

### 12. Trilha de alterações (quem mudou o quê)

Toda alteração de indicador, meta e apuração fica registrada com autor, data e o estado anterior. A pergunta do controle interno nunca é "qual é o número?", é "quem mexeu neste número, quando, e qual era antes" — e é isso que a trilha responde.

1. **Abra a trilha do indicador.** Na ficha do indicador, clique em **Histórico**, no topo. O painel **Histórico do indicador** lista os eventos do mais recente para o mais antigo: a ação (**Criado**, **Atualizado**), o autor e a data/hora. Clique numa linha para abrir o detalhe — numa criação, os **Valores iniciais**; numa alteração, os **Campos alterados**, com **Antes** e **Depois** lado a lado. A trilha responde *quem mudou*, não *quanto ficou*: o valor que vale hoje está na ficha, não aqui.
2. **Abra a trilha de uma meta.** Na seção **Metas**, o ícone de histórico na linha abre **Histórico da meta**. É a trilha que o auditor de fato pede, porque a meta é o compromisso pelo qual a secretaria será cobrada. Ela é separada da trilha da apuração: mudar a meta e mudar o realizado são dois fatos distintos, e ficam em dois registros distintos.
3. **Abra a trilha de uma apuração.** Na seção **Apurações**, o ícone de histórico da linha abre **Histórico de retificação**, com as versões do período (**Versão** 1, 2… e o selo **Vigente** na que vale). Dentro dele, cada versão tem o ícone **Log de alterações**, que abre a trilha daquela versão. São duas coisas empilhadas, e confundi-las custa tempo: a lista de versões conta **o que o número virou**; o **Log de alterações** conta **quem o mudou e quando**.

:::BlockQuote
**Sem a permissão de auditoria, o botão não existe.** O **Histórico** do indicador, o **Histórico da meta** e o **Log de alterações** da medição só são desenhados para quem tem a operação **Consultar log de auditoria** — no cadastro padrão, o cargo **Auditor**. Nenhum dos três perfis do módulo tem essa permissão: o próprio gestor que criou a meta **não** vê o botão da meta dele. Não aparece mensagem de erro nem cadeado — a tela simplesmente não mostra o botão, e é fácil concluir que a trilha não existe. Ela existe: peça a operação ao administrador em **Início → Alçada**, ou consulte pela trilha geral em **Administração → Trilha de auditoria**, filtrando pela entidade.
:::

## Verificação

***

Você sabe que funcionou quando:

- o ciclo aparece como **Ativo** na lista de planejamento;
- o detalhe do ciclo mostra as suas perspectivas (com a **Sociedade** no topo) e os objetivos pendurados nelas;
- a ficha do indicador mostra a **meta** com a faixa de tolerância e a **apuração congelada** do período (e, se você retificou, o selo **Retificado v2**);
- a ficha do indicador mostra o selo **Aprovado** no topo **e** na linha da meta, e a solicitação correspondente já saiu de **Solicitações de aprovação**;
- a ficha do indicador calculado, ao abrir **Editar**, mostra a **Métrica do catálogo** (ou a **Fórmula**) que você escolheu, e **Testar fórmula** devolve **Resultado:** com a **Memória de cálculo** listando cada parcela;
- ao congelar um período com o valor fora da meta, o aviso **Indicador fora da meta** aparece no **sino** do portal (e sai também por e-mail) trazendo o indicador, o período, o realizado e a meta — e congelar de novo o mesmo período **não** repete o aviso;
- o **Painel de desempenho**, com o ciclo selecionado, mostra uma linha por indicador com **meta**, **realizado**, **variação**, **desempenho** e o **farol** na cor correta (verde/amarelo/vermelho/sem meta);
- ao clicar numa linha do painel, o detalhamento lista as versões da medição daquele período;
- o **Painel gerencial**, com o ciclo selecionado, mostra os cartões **Objetivos**, **Indicadores**, **Atingimento médio** (com a contagem "N de M períodos medidos") e **Fora da meta**;
- as tabelas **Por nível de desdobramento** e **Por área** trazem uma linha por agrupamento que tem objetivo, com **Medidos** no formato medidos/total;
- o **Mapa estratégico** mostra uma faixa por perspectiva, com um cartão por objetivo, cada um com o farol e o percentual;
- escolhido um indicador em **Indicador no tempo**, o gráfico traça o realizado e a meta e **interrompe** nos períodos sem apuração;
- o que você fixa aparece em **Meu painel** já desenhado e continua lá quando você volta à tela;
- o **Atingimento médio** do painel gerencial bate com a média refeita a partir do CSV exportado no **Painel de desempenho**.

## Erros comuns

***

- **"Objetivos só podem ser alterados enquanto o ciclo está ativo."** — o ciclo ainda está em **Rascunho** (ou já foi **Fechado**). Ative o ciclo antes de criar objetivos; se ele estiver fechado, abra o **próximo** ciclo em vez de tentar reabrir este.
- **A faixa de tolerância foi recusada.** — a faixa está do lado errado da meta para a polaridade escolhida. Coloque-a **abaixo** da meta para *Maior é melhor*, **acima** para *Menor é melhor*, ou **cercando** a meta para *No alvo é melhor*.
- **A retificação não salva.** — a **justificativa** é obrigatória. Escreva o motivo da correção; o valor anterior é preservado como versão anterior.
- **O Painel de desempenho não mostra linha nenhuma ("Nenhum indicador com meta neste ciclo ainda.").** — o indicador ou a meta ainda estão em **Rascunho** ou **Aguardando aprovação**. O painel só enxerga o que está **Aprovado**, e o que não está **não gera célula alguma** — nem com o rótulo "Sem meta". Registrar e congelar a apuração não resolve: o valor fica gravado e continua invisível. Abra a ficha do indicador, confira os **dois** selos (o do topo e o da linha da meta), envie o que estiver em rascunho, peça a decisão em **Início → Solicitações de aprovação** e clique em **Efetivar aprovação**. O **Painel gerencial** lê a mesma grade e fica vazio pelo mesmo motivo.
- **Uma linha do painel aparece como "Sem meta".** — a linha só existe porque há meta **aprovada** naquele período; o que falta é o **realizado**. Registre e **congele** a apuração para o semáforo acender. Se o painel não mostra linha **alguma**, o caso é outro, o da aprovação — veja a entrada acima.
- **"Apurar agora" ou "Recalcular agora" não faz nada / dá erro.** — o indicador ainda não está **Aprovado**. Confira o selo no topo da ficha: em **Rascunho** ou **Aguardando aprovação** ele não apura, nem à mão nem pela varredura noturna.
- **A fórmula foi recusada ao salvar.** — ou ela cita um nome que não está no catálogo, ou não cita métrica nenhuma (só números), ou você preencheu métrica única **e** fórmula ao mesmo tempo. Use o combo **Inserir uma métrica** e teste antes de salvar.
- **O indicador calculado apurou zero.** — a métrica não achou movimento no período, ou o módulo de origem não está disponível. Abra o **Histórico de retificação** do período e leia a **Memória de cálculo**: ela diz qual dos dois foi.
- **O número do indicador não é do mês.** — a métrica escolhida é de **saldo** (as duas do Financeiro), que responde "quanto há hoje". Para medir o que aconteceu no período, escolha uma métrica de movimento.
- **O atingimento do painel gerencial aparece como "—".** — nenhum período do ciclo foi apurado ainda. Travessão é ausência de medição, não zero.
- **Um objetivo aparece na faixa "Sem perspectiva".** — ele foi criado sem perspectiva, e o mapa é desenhado por perspectiva. Edite o objetivo e informe a perspectiva.
- **O mapa mostra "Objetivo reservado".** — o objetivo é sigiloso e você não administra o planejamento estratégico. O farol, o peso e o percentual continuam visíveis; só o título é omitido.
- **"Seu painel já tem o máximo de 24 widgets."** — o **Meu painel** está cheio. Remova o que você não acompanha mais antes de fixar outro.
- **Um widget diz "Fixado em outro ciclo".** — ele foi fixado com outro ciclo selecionado. Escolha aquele ciclo no topo da tela e o widget volta a desenhar.
- **O botão Histórico não aparece na ficha.** — você não tem a operação **Consultar log de auditoria**. A trilha existe e está gravada; peça a permissão em **Início → Alçada** ou consulte por **Administração → Trilha de auditoria**.
- **Perspectivas em inglês.** — não é erro: o ciclo nasce com as quatro perspectivas padrão do Balanced Scorecard em inglês, para você **renomear** para o seu contexto (a Sociedade no topo, no setor público).


[title] Produtos e releases
[path] Aplicações/Agility/


[title] Relatórios e metas
[path] Aplicações/Agility/


[title] Compras
[path] Aplicações/ERP/Manual do Usuário/

# Compras (requisição → cotação → pedido → recebimento → nota)

:::BlockQuote
Pré-requisitos: [Cadastros gerais (parceiros e produtos)](docId:6xpQsdWQ2NTyI40BFqDS-) (fornecedores + produtos) e [Financeiro — cadastros de apoio](docId\:yTzjjyyML1B_60VgwDT09) (centros de custo e condições de pagamento).
:::

## Introdução

***

O módulo de **Compras** conduz todo o ciclo de suprimentos — do "preciso disto" até "chegou, conferi e virou conta a pagar". O caminho completo tem cinco etapas encadeadas: **requisição** (o solicitante pede o que precisa), **cotação** (o comprador pede preço a 2-3 fornecedores e compara), **pedido de compra** (escolhe o fornecedor vencedor e gera o documento oficial), **recebimento** (confere a mercadoria que chegou contra o pedido) e **nota de entrada** (registra a nota fiscal do fornecedor, que vira conta a pagar). Ao redor desse fluxo há apoios operacionais: **agendamento de doca** para organizar a chegada, **inspeção** de qualidade do lote, **não conformidade** quando o material chega errado, e o acompanhamento contínuo da **qualidade do fornecedor** (IQF, avaliações e infrações).

A separação em etapas parece burocrática para uma compra pontual, mas é o que dá rastreabilidade a compras recorrentes ou de valor alto: registra **quem pediu, quem cotou, quem aprovou, quem recebeu** e **quem conferiu a nota**. Cada etapa pode ter *alçada* de aprovação própria, de modo que compras acima de um teto sobem automaticamente para quem tem poder de liberar. Você usa este módulo sempre que a empresa precisa adquirir produtos ou materiais de um fornecedor externo.

:::BlockQuote
**Quem opera Compras.** A autoridade neste módulo vem do **cargo** do usuário (via lotação), não de um papel genérico de administrador. Um usuário sem cargo — inclusive o administrador de plataforma — recebe **"sem autorização"** ao criar ou aprovar em Compras, por design (a alçada resolve autoridade pelo cargo). Para operar a esteira, entre como um perfil com cargo de compras (Comprador, Aprovador com teto definido, ou Gerente). As lotações e os tetos de cada cargo se cadastram em **Administração** ([Administração](docId\:Z8SS7r6Bvhs09rP1SPxUD)).
:::

## Passo a passo

***

### Criar a requisição

1. **Abra "Requisições".** Menu **Compras → Requisições**. A lista mostra as requisições existentes com a situação de cada uma (Rascunho, Aguardando aprovação, Aprovada, Rejeitada, Cancelada).:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/057-purchase-requisitions.png" alt caption width="3200" height="2000"}
2. **Nova requisição.** Clique em **"Nova requisição"** e preencha o cabeçalho:
   - **Preparador** — quem digita (o usuário logado).
   - **Solicitante (empregado)** — o empregado **para quem** é a compra ("em nome de"). É dele que derivam o *centro de custo* e a alçada (padrão de mercado do SAP Ariba). Opcional no fluxo legado, mas recomendado.
   - **Centro de custo** — onde o gasto pousa. Ao escolher um solicitante, o seletor fica **restrito aos centros autorizados dele** ([Administração](docId\:Z8SS7r6Bvhs09rP1SPxUD)); com um único autorizado, pode deixar em branco que o sistema assume; com vários, é preciso escolher.
   - **Necessário até** — data limite desejada (opcional).
   - **Observações** — texto livre (opcional).
3. **Salve o cabeçalho.** A requisição nasce com situação Rascunho.
4.

💡 **Ache o produto pelo código de barras.** Na busca do produto, além do nome e do SKU, você pode **digitar, colar ou ler com um leitor** o código de barras (GTIN/EAN) já cadastrado no produto — ele aparece para escolha com o **código ao lado do nome**, o que ajuda a conferir que é o item certo. Um leitor USB comum funciona: ele se comporta como teclado. Se o código não estiver cadastrado em nenhum produto, nada trava — a busca por nome continua funcionando normalmente. A opção **"Texto livre"** também segue disponível.

**Adicione os itens.** Já na ficha da requisição, na seção **"Itens"**, use **"Adicionar item"**. Cada item pode ser de **catálogo** (escolha um **produto** cadastrado na página [Cadastros gerais (parceiros e produtos)](docId:6xpQsdWQ2NTyI40BFqDS-)) ou de **texto livre**; informe quantidade, unidade, descrição e preço estimado. Marque **"Estoque"** quando o item alimenta o inventário no recebimento — essa marcação **exige um produto** (texto livre não movimenta estoque). Os itens são lançados aqui, depois de salvar o cabeçalho.

### Submeter e aprovar a requisição

1. **Submeter.** Com os itens lançados, clique em **"Submeter"**. A situação muda de Rascunho para Aguardando aprovação.
2.

Enquanto a requisição **ainda não é terminal**, ela pode ser **cancelada** (ação **"Cancelar"** na ficha) — a situação vira Cancelada e ela deixa de seguir na cadeia de compras. Requisição não é "excluída": ela é cancelada e permanece no histórico.

A aprovação é **por cargo e por valor**: uma requisição de R$ 6.000 é **negada** para quem tem teto de R$ 5.000 e **liberada** para quem tem teto de R$ 50.000. Aprovar uma requisição já aprovada é bloqueado (transição inválida).

**Aprovar.** O aprovador (com alçada Aprovar requisição suficiente para o valor e o centro de custo) abre a requisição e clica em **"Aprovar"**. A situação muda para Aprovada. Também é possível **"Rejeitar"**, levando a Rejeitada. Na ficha há um card de **Escalonamento de alçada** que mostra, a partir do cargo do solicitante, **para qual cargo** aquele valor escala — ou avisa que **nenhum cargo cobre** (bloqueado) ou que a operação está **liberada** sem regra. Esse card é informativo/roteamento; o bloqueio efetivo de quem pode aprovar continua sendo o teto do aprovador atual.

:::BlockQuote
Dica: quem é o aprovador padrão de cada centro de custo e qual é o teto de cada cargo se cadastram em [Administração (seção 13)](docId\:Z8SS7r6Bvhs09rP1SPxUD). As aprovações pendentes que caem na sua caixa também aparecem em **Início → Aprovações pendentes**.
:::

### Cotar com fornecedores

1. **Abra "Cotações".** Menu **Compras → Cotações**. A lista reúne as cotações em andamento e concluídas; no ambiente de demonstração ela aparece vazia até você criar a primeira cotação.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/058-quotations.png" alt caption width="3200" height="2000"}
2. **Nova cotação a partir de requisições.** Em **"Nova cotação"**, escolha o modo **"Originar de requisições aprovadas"**, marque uma ou mais requisições aprovadas e confirme. O sistema cria a cotação **copiando os itens** dessas requisições.
3. **Adicione fornecedores.** Escolha 2-3 fornecedores cadastrados ([Cadastros gerais (parceiros e produtos)](docId:6xpQsdWQ2NTyI40BFqDS-)). Para cada combinação de fornecedor + item, registre o preço cotado e o prazo de entrega. Com a cotação ainda **Aberta**, o botão **"Enviar aos fornecedores"** no cabeçalho dispara o e-mail de convite aos fornecedores participantes e informa o resultado do envio.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/152-quotation-send-suppliers.png" alt caption width="3200" height="2000"}
4. **Escolha o vencedor.** Para cada item, marque qual fornecedor venceu (o vencedor pode variar item a item). O **mapa comparativo** mostra o preço de referência por item (média, mediana e menor preço) e sinaliza quando há dispersão alta de preços — sinal de proposta fora da curva.
5. **Feche a cotação.** Salve; a situação passa a Concluída.

**Alternativa: assistente de cotação por etapas**

Para uma cotação conduzida passo a passo (em vez da tela única), abra o **assistente** pelo botão **"Abrir assistente"** na lista de cotações ou na ficha. Ele guia por etapas — abertura/itens, fornecedores, propostas, critérios e pesos, julgamento, aprovação e publicação — com um indicador de progresso no topo. Avançar só é liberado quando a etapa está completa; para **voltar** a uma etapa anterior o sistema exige uma **justificativa**, que fica gravada no **histórico de etapas** (botão **"Histórico"**).

- Na etapa **critérios e pesos**, o regime público segue os presets da Lei 14.133 (travados — o preset só se aplica a cotações públicas) e o regime privado permite critérios livres (a soma dos pesos deve fechar 100%).
-

**A nota só pode ser informada até a etapa de critérios.** A partir de **julgado**, o sistema recusa a alteração de critérios e notas (*"Critérios e notas não podem mudar na etapa JUDGED"*) — para corrigir, é preciso **retroceder** a cotação, o que exige justificativa e fica gravado no histórico de etapas.

**Proposta sem nota é desclassificada — e o sistema não avisa no momento do julgamento.** Se você julgar antes de pontuar, o quadro devolve **todas** as propostas como *Desclassificado*, o que é indistinguível de um certame em que ninguém atendeu. O quadro de julgamento passa a dizer quantas foram desclassificadas e lembrar da nota, mas o momento de evitar isso é aqui.

**Nota técnica das propostas — obrigatória em "técnica e preço" e em "melhor técnica".** Esses dois critérios pesam uma **nota qualitativa** que só a comissão pode atribuir; os outros três decidem só por preço e não pedem nota nenhuma. Quando o critério escolhido pesa nota, aparece na própria etapa de critérios o bloco **"Notas técnicas das propostas"**, com uma linha por proposta (item × fornecedor) e o botão **"Informar nota técnica"**. Informe a nota de **cada** critério qualitativo e salve.

- Na etapa **julgamento**, o sistema calcula um score por fornecedor, sugere o vencedor de cada item e sinaliza empates e desclassificações.
- Na **aprovação**, quem tem alçada pode **substituir** o vencedor sugerido mediante justificativa obrigatória (registrada na auditoria). **Um empate não resolvido impede a publicação** até que se defina o vencedor daquele item.
- Na **publicação**, o botão **"Gerar pedido de compra"** emite o pedido a partir do que foi adjudicado — é daqui que sai o pedido, e não do preenchimento manual. Se um item foi **dividido entre fornecedores** (porque o mais bem colocado não cobria toda a quantidade), sai **um pedido para cada vencedor**, cada um com a sua fatia e o seu preço. Concluída a emissão, a cotação passa à etapa **"Pedido gerado"**, que lista os pedidos criados com link para cada um — e uma segunda tentativa é **recusada**, para não duplicar compra já empenhada.

### Fechar o pedido de compra

1. **Abra "Pedidos de compra".** Menu **Compras → Pedidos de compra**.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/059-purchase-orders.png" alt caption width="3200" height="2000"}
2. **Novo pedido a partir da cotação.** O pedido nasce na etapa **"Publicação"** do assistente, no botão **"Gerar pedido de compra"** — não se digita de novo o que já foi adjudicado. O sistema cria **um pedido por fornecedor vencedor**, com produto, quantidade e preço adjudicados já preenchidos, e guarda em cada linha de qual proposta ela veio (é isso que permite conferir o recebimento contra a adjudicação, e não contra uma cópia digitada).
3. **Confira e complete.** Verifique os valores totais, a **condição de pagamento** (cadastro na página [Financeiro — cadastros de apoio](docId\:yTzjjyyML1B_60VgwDT09)) e o prazo de entrega. Ajuste o que for preciso antes de aprovar.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/013-purchase-orders-detail.png" alt caption width="3200" height="2000"}Cada linha de item tem uma coluna **Produto**, ao lado do tipo. Quando o tipo é **Produto**, escolher o item do catálogo é **obrigatório** — o botão **Salvar** fica travado enquanto faltar, com o aviso na tela. É esse vínculo que faz o **recebimento** movimentar o estoque: uma linha de produto sem produto seria recebida normalmente e **não daria entrada em nada**. Linhas de **Serviço**, **Bem** e **Entrega futura** não pedem produto, porque não têm saldo em estoque. A busca do campo consulta o catálogo inteiro — digite o código interno, a descrição ou passe o leitor de código de barras.
4. **Situação e liberação.** O pedido nasce com situação Aberto e já alimenta o recebimento. Se houver alçada Aprovar pedido, o pedido sobe para quem tem teto suficiente antes de ficar liberado. Um pedido que não vai adiante é **cancelado** (ação **"Cancelar"** → situação Cancelado), não excluído; e um pedido já cancelado ou já recebido **não pode mais ser alterado**.

### Agendar a doca (opcional)

1. **Abra "Portaria & docas".** Menu **Compras → Portaria & docas**. Aqui você organiza a **janela de doca** para a chegada da mercadoria de um pedido — útil quando há muitos recebimentos concorrendo pela mesma plataforma. Agende o pedido para uma data e horário; a portaria usa esse agendamento para receber o veículo.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/064-dock-schedule.png" alt caption width="3200" height="2000"}**Escolha COMO agendar.** O campo **"Como agendar"** oferece dois caminhos, e a diferença não é de conveniência:**O comunicado ao fornecedor.** O campo **"E-mail do fornecedor"** já vem preenchido com o endereço do cadastro assim que você escolhe o pedido, e pode ser alterado — troque quando estiver tratando aquela entrega com uma pessoa específica; o que você digitar vence o do cadastro. O e-mail é **obrigatório no cadastro do fornecedor**, então sempre há um endereço para onde mandar — o que faltava era o produto ir buscá-lo. Marcando **coleta de troca**, o comunicado é outro, dizendo ao fornecedor para trazer a troca.
   - **À mão (qualquer data)** — você digita início e fim. Serve para o que não nasce de um pedido, e **aceita qualquer data**: nada impede marcar a janela para um mês depois da entrega que ela deveria receber.
   - **A partir do pedido de compra** — você escolhe o pedido e informa só a **hora** e a **duração**. A **data vem do pedido** (a entrega prevista que o comprador registrou), o **fornecedor também**, e é o único caminho que marca **coleta de troca**. Um pedido **sem data de entrega prevista é recusado** — o sistema diz isso em vez de inventar uma data.
2. **Consulte o histórico do pátio.** Na mesma tela, abaixo da fila, o card **"Histórico do pátio"** lista **todo veículo que passou pela portaria**, do mais recente para o mais antigo, com placa, motorista, entrada e saída. A fila de cima responde **quem está dentro agora**, que é a pergunta do porteiro; o histórico responde **quem veio e quando**, que é a de todo o resto — do comprador que cobra uma entrega ao auditor que concilia um recebimento com a chegada. Saída em branco não fica em branco: aparece **"ainda no pátio"**, para não se confundir registro faltando com veículo dentro.

### Receber a mercadoria

1. **Abra "Recebimentos".** Menu **Compras → Recebimentos**. A lista mostra os recebimentos registrados e sua situação.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/060-goods-receipts.png" alt caption width="3200" height="2000"}
2. **Novo recebimento.** Aponte para o pedido aprovado. O sistema sugere as quantidades a receber (iguais às pedidas).
3.

**Se o mesmo produto aparece em duas linhas do pedido** (compra dividida entre fornecedores, dois lotes, duas datas de entrega), o sistema **não escolhe por você**: ele avisa e não conta. É deliberado — a conferência cega **esconde a quantidade esperada**, então nada na tela consegue desempatar, e escolher sozinho mandaria tudo para a primeira linha, fechando com uma sobrando e a outra zerada. Nesse caso use o ajuste manual da contagem, que continua disponível em qualquer linha, com a nota fiscal ou o romaneio à mão.

**"Este produto está em mais de uma linha do pedido — conte manualmente"** — ver abaixo.

**"Código desconhecido — busque manualmente"** — o código não está cadastrado em produto nenhum.

**"Produto não pertence a este pedido"** — o código é de um produto conhecido, mas fora deste pedido; **não conta nada**. Não é lentidão do leitor.

**"+1 contado"** — a linha subiu e está gravada.

**Quatro desfechos possíveis de uma leitura**, e vale reconhecer cada um:

**A contagem só sobe depois de gravada.** O número na tela é o número registrado — se a gravação falhar, o campo volta ao que estava e o aviso diz **"Não contado — a contagem não foi gravada. Leia o código de novo."** Isso importa numa conferência, que é contada **uma vez**, com a mercadoria na bancada: sem esse aviso o conferente bipa a caixa seguinte sem saber que a anterior não entrou, e a divergência só apareceria no fechamento.

💡 **Conferência cega: bipe e a contagem sobe sozinha.** Na conferência cega, o conferente conta **sem ver a quantidade pedida** — as divergências só aparecem quando o recebimento é fechado. No campo de leitura, cada código de barras lido (ou digitado) **soma uma unidade** à linha do produto correspondente: você bipa item a item e não digita quantidade nenhuma. Bipar o mesmo produto de novo acumula.

**Informe o lote quando o material for controlado por lote.** A linha do item tem o campo **Lote**, ao lado da validade. Ele é **opcional para a maioria dos materiais** — mas, para um material marcado como *controlado por lote* no cadastro de produto ([Vendas e CRM](docId\:TaINdkXLJcUzyq0xUuGfH)), o recebimento **é recusado sem ele**, com a mensagem "informe o lote na entrada". Digite o código como ele vem na embalagem: não é preciso cadastrar o lote antes, o sistema **cria o lote na hora** a partir do que você digitar, já vinculado ao fornecedor do pedido. É esse código que faz o saldo do almoxarifado ficar **separado por lote** — sem ele, o estoque sabe que há 100 unidades e não sabe de qual remessa.

**Informe o endereço quando o depósito exigir.** Alguns almoxarifados são cadastrados com **endereçamento obrigatório** (o campo "Exige endereço" no cadastro do depósito, [Estoque](docId\:CVozhYtoHDtuWZyT-bnAT)). Para esses, a coluna **Endereço** da linha do item é **obrigatória** — o recebimento é recusado sem ela, com a mensagem "O endereço é obrigatório". A tela avisa isso assim que você escolhe o depósito, e a coluna aparece marcada com asterisco. O endereço é escolhido numa lista, não digitado: só valem endereços **já cadastrados e ativos** daquele depósito. Se a lista abrir vazia, ninguém cadastrou endereços ainda — faça isso em **Estoque → Endereços** antes de receber, porque nenhum endereço vem pronto de fábrica.

**Confira a mercadoria.** Ajuste as quantidades se vier diferente do pedido — o sistema aceita **recebimento parcial** e mantém o pedido em Recebido parcial até completar. Escolha o **almoxarifado de destino** (cadastro na página [Estoque](docId\:CVozhYtoHDtuWZyT-bnAT)) onde a entrada vai pousar.

1. **Confirme.** Ao confirmar, o **estoque sobe** na quantidade recebida no almoxarifado escolhido, e o pedido é marcado como Recebido (parcial ou total, conforme as quantidades). O botão **"Etiquetas do recebimento"** abre um painel com a **identificação por item** (botão **"Etiqueta"** de cada item) e o **endereçamento (onde é guardado)** — o depósito resolvido, o campo do local e a etiqueta do endereço.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/148-receipt-labels-drawer.png" alt caption width="3200" height="2000"}Na mesma linha há a ação **"Nota de recebimento (CSV)"**, que baixa a **nota do recebimento**: o cabeçalho do recebimento com **uma linha por item** — produto, descrição, quantidades, lote, validade e resultado da inspeção. É o documento que acompanha a conferência, para arquivo ou para anexar ao processo de pagamento. O arquivo sai em CSV com acentuação preservada, e abre direto no Excel.

:::BlockQuote
Observação de perfil: o recebimento é tarefa de quem tem **cargo de compras** (o comprador). Como toda a esteira, ele depende do cargo do usuário — se aparecer "sem autorização", troque para um perfil com esse cargo (as lotações e permissões se cadastram em Administração, [Administração](docId\:Z8SS7r6Bvhs09rP1SPxUD)).
:::

:::BlockQuote
**Validade do lote recebido.** O recebimento só recusa um item perto de vencer se existir uma **política de validade em vigor** — enquanto nenhuma estiver cadastrada, qualquer lote entra e nada avisa. O piso se cadastra em **Compras → Política de validade** ("Parametrizar a política de validade (shelf life) do recebimento", mais adiante nesta página).
:::

### Inspecionar o lote recebido (opcional)

1. **Abra "Inspeção de recebimento".** Menu **Compras → Inspeção de recebimento**. A tela reúne a busca de lotes por NF-e, o cadastro de planos de inspeção e a lista de lotes de inspeção — no ambiente de demonstração ainda não há nenhum plano nem lote. Quando o material exige conferência de qualidade, **você gera a inspeção** no bloco **"Gerar lote de inspeção"**: escolha o **recebimento** e o **plano** e clique em **Gerar lote**. A combo lista só os recebimentos que ainda podem gerar lote — os que exigem inspeção e ainda não têm um lote vivo —, então o botão não oferece opção que o sistema vá recusar. O **tamanho do lote não é digitado**: vem do que efetivamente chegou. Depois, abra o lote, registre o resultado da conferência e marque a inspeção como **aprovada** ou **reprovada**.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/061-inspections.png" alt caption width="3200" height="2000"}**O tamanho do lote sai do recebimento, não da digitação.** A NBR 5426 dimensiona a amostra a partir do lote apresentado à inspeção, e o lote é o que o recebimento diz que chegou. Se você informar um tamanho diferente da quantidade recebida, o sistema recusa e mostra os dois números — informar 500 sobre um recebimento de 5 produzia uma amostra que ninguém consegue tirar, e informar menos produzia uma amostra pequena demais para significar alguma coisa.**Aprovar exige ter conferido.** Quando o plano de inspeção lista características, o lote não pode ser aprovado sem **nenhum** resultado registrado — antes disso, aprovar sem conferir nada dava nota **100** ao fornecedor no índice de qualidade, o que ainda fazia a próxima remessa dele ser dispensada de inspeção pelo *skip-lot*. Sem resultado registrado, nenhum índice é gravado: fornecedor não medido não é premiado como medido.**Quem decidiu fica registrado.** Aprovar ou reprovar grava o usuário no próprio lote e no histórico. Use o botão **Histórico** na linha do lote para ver a decisão, o autor e o que mudou; clique no evento para abrir o detalhe campo a campo.

### Registrar não conformidade

1. **Abra "Não conformidades".** Menu **Compras → Não conformidades**. Quando um lote é reprovado (na inspeção ou na conferência), registre uma **não conformidade (NC)** ligada ao recebimento reprovado — é o documento que sustenta a reclamação ou a devolução ao fornecedor.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/063-nonconformities.png" alt caption width="3200" height="2000"}
2. **Abra a NC e trate.** Informe o motivo, a quantidade afetada e a providência (devolução, retrabalho, aceite com ressalva). A NC fica com a **origem ligada ao recebimento**, o que alimenta o histórico de qualidade daquele fornecedor.**A liberação sob concessão faz a mercadoria entrar.** Resolver a NC como *aceite com ressalva* é a autorização para o material entrar no estoque apesar do defeito — antes ela gravava só o rótulo e a mercadoria ficava bloqueada, sem nenhuma outra porta (aprovar o lote já decidido é recusado). O **portão fiscal continua valendo**: concessão sobre problema de **qualidade** não libera mercadoria que a SEFAZ reprovou. **Reposição** não libera nada — significa mercadoria nova a caminho, não a defeituosa aceita. E fica registrado **quem** concedeu: use o **Histórico** na ficha da NC para ver a decisão, o autor e o que mudou.

### Lançar a nota de entrada

1. **Abra "Notas de entrada".** Menu **Compras → Notas de entrada**. Quando a nota fiscal do fornecedor chega, registre-a aqui. A *NF-e* de entrada é confrontada com o pedido e o recebimento (conferência de três pontas: pedido × recebido × nota).:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/065-purchase-invoices.png" alt caption width="3200" height="2000"}
2. **Confira e confirme a nota.** Verifique valores, itens e a **categoria financeira** (exigida para gerar a conta a pagar — cadastro na página [Financeiro — cadastros de apoio](docId\:yTzjjyyML1B_60VgwDT09)). Ao confirmar, a nota gera automaticamente a **conta a pagar** para o fornecedor, com vencimento conforme a condição de pagamento do pedido.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/014-purchase-invoices-detail.png" alt caption width="3200" height="2000"}

:::BlockQuote
Se o fornecedor enviou o **XML** da NF-e, ele é processado na entrada fiscal ([Fiscal — entrada](docId:1_QpvYmn6apZ9mqx87Z4K)) e alimenta esta nota — evita redigitar item a item.
:::

### Acompanhar a qualidade do fornecedor

1. **IQF do fornecedor.** Menu **Compras → IQF do fornecedor**. O IQF (Índice de Qualidade de Fornecimento) consolida o desempenho de cada fornecedor a partir de recebimentos, inspeções, não conformidades e avaliações — um placar contínuo para decidir com quem comprar de novo.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/062-supplier-quality.png" alt caption width="3200" height="2000"}
2. **Avaliações.** Menu **Compras → Avaliações**. Registre avaliações periódicas de fornecedor (prazo, qualidade, atendimento). Elas entram na composição do IQF. Cada avaliação exige **vínculo a um recebimento** e as notas devem ficar **entre 0 e 100** — uma nota fora dessa faixa, ou uma avaliação sem o recebimento de origem, é recusada.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/066-supplier-evaluations.png" alt caption width="3200" height="2000"}
3. **Infrações de fornecedor.** Menu **Compras → Infrações de fornecedor**. Registre penalidades e ocorrências formais (atraso, entrega fora de especificação, quebra de contrato). Ficam no histórico do fornecedor e pesam no IQF.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/067-supplier-infractions.png" alt caption width="3200" height="2000"}

### Aprovar o pedido e alterar pedido já aprovado

Além da liberação por alçada, o pedido tem um passo de **aprovação** e uma regra específica para quando alguém precisa mexer num pedido que já foi aprovado:

1. Um pedido em situação Aberto pode ser **aprovado** por quem tem alçada Aprovar pedido suficiente para o valor: use **"Aprovar"** e a situação passa a Aprovado.
2. Alterar um pedido **já aprovado** depende de dois controles combinados: a **política do órgão** precisa permitir alteração após a aprovação **e** o usuário precisa ter **alçada suficiente para o valor** do pedido. Sem a política ativa, ou sem alçada, a alteração é bloqueada.
3. Um pedido Cancelado ou Recebido **não pode mais ser alterado**, independentemente da política.

:::BlockQuote
A política "permite alterar pedido aprovado" é um parâmetro do órgão ([Administração](docId\:Z8SS7r6Bvhs09rP1SPxUD)). Mesmo com ela ativa, a alteração de um pedido aprovado continua respeitando o teto de alçada do usuário para o valor do pedido.
:::

### Entregas em locais diferentes no mesmo pedido

Um mesmo pedido de compra pode ter itens entregues em locais distintos — útil quando a aquisição abastece mais de uma unidade ou almoxarifado:

1. Em cada linha do pedido, preencha o campo **"Local de entrega"** com o endereço ou a unidade de destino daquela linha.
2. Linhas diferentes podem apontar **locais de entrega diferentes** dentro do mesmo pedido; deixe em branco para usar o destino padrão.
3. Salve o pedido; cada item guarda o seu próprio local de entrega, que orienta a logística do recebimento.



![](https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/013-purchase-orders-detail.png)

### Tipos de item no pedido (produto, serviço, bem imobilizado, entrega futura)

Cada linha do pedido de compra tem um **tipo** e uma **natureza**, que definem o que está sendo adquirido e como o item se comporta no recebimento e na contabilização:

1. No item do pedido, escolha o **tipo**: **Produto**, **Serviço**, **Ativo imobilizado** ou **Entrega futura**. Use "Serviço" para contratações sem movimentação de estoque, "Ativo imobilizado" para bens patrimoniais e "Entrega futura" para compras cuja entrega ocorre em data posterior.
2. Defina a **natureza** da linha — **Estoque** (alimenta o inventário no recebimento), **Ativo imobilizado** (bem patrimonial) ou **Despesa** (consumo direto).
3. Salve o pedido. O tipo e a natureza acompanham a linha até o recebimento e a nota de entrada, orientando onde a entrada pousa e como o gasto é classificado.

### Conferência de três pontas e divergências da nota

Ao lançar a nota de entrada, o sistema confronta a nota com o pedido e o recebimento e identifica as divergências item a item:

1. Registre a nota apontando o **pedido de compra** de origem — a nota fica ligada ao pedido e ao recebimento correspondentes.
2. Rode a **conferência** (ação **"Conferir"**). O sistema compara quantidades e valores da nota com os do pedido e do recebimento e marca a nota como **Conferida** (sem divergência) ou **Divergente** (há diferença).
3. Quando há divergência, abra a nota para ver a **lista de divergências** — o que difere entre nota, pedido e recebimento. Uma nota divergente ainda pode seguir para aprovação com a divergência registrada, conforme a política do órgão.

:::BlockQuote
Se o fornecedor enviou o **XML** da NF-e ([Fiscal — entrada](docId:1_QpvYmn6apZ9mqx87Z4K)), os itens já chegam preenchidos, e a conferência recai sobre a comparação com o pedido e o recebimento — evita redigitar item a item.
:::



![](https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/014-purchase-invoices-detail.png)

### Rateio da nota por categoria financeira

Uma mesma nota de entrada pode ratear o seu valor entre **categorias financeiras diferentes**, tanto para produtos quanto para serviços:

1. Na nota de entrada, atribua a **categoria financeira** por **linha** — cada item pode apontar para uma categoria distinta.
2. Ao confirmar, o sistema **agrupa os subtotais por categoria** e gera a conta a pagar rateada, distribuindo o valor (e as retenções, quando houver) proporcionalmente entre as categorias.
3. Confira, na conta a pagar gerada ([Financeiro — títulos (contas a pagar e a receber)](docId\:D4kuGidayU2GQ-hMhF_T-)), que a soma das parcelas rateadas fecha exatamente o total da nota, sem centavos perdidos.

### Decidir se o sistema retém sozinho ao aprovar a nota

Aprovar uma nota de entrada pode calcular e aplicar as retenções **sem ninguém clicar**. Isso é uma decisão da organização, e é ela que decide — não a instalação.

44a. **Abra o mapa de retenção por CFOP.** Menu **Compras → Retenção por CFOP**. Antes do mapa, o card **"Retenção automática na aprovação"** mostra a chave e o estado dela. A ordem é proposital: o mapa abaixo só importa quando a chave está ligada.

44b. **Leia a frase abaixo da chave antes de mexer.** Ela distingue duas situações que a caixa marcada não distingue: - **"Ninguém nesta organização decidiu ainda"** — vale o padrão da instalação. Desmarcado aqui não quer dizer que alguém escolheu desligar. - **"Esta organização já decidiu"**, com a data da última alteração — aí sim é escolha registrada.

44c. **Marque ou desmarque, e pronto** — o efeito é imediato e fica na trilha de auditoria, com autor e data. **Só quem tem alçada fiscal altera**; quem tem acesso à tela mas não à alçada **vê** o estado (é contexto para as notas que aprova) e recebe o aviso de que decidir é ato fiscal.

:::BlockQuote
**Ligar não substitui o mapa, e o mapa não substitui a chave.** Com a chave ligada e o mapa vazio, toda nota é retida como *serviços profissionais*, seja qual for o CFOP — inclusive compra de mercadoria. As duas coisas são configuradas nesta mesma tela por esse motivo.
:::

### Quem mudou um imposto calculado, e por quê

Ao calcular as retenções da nota do fornecedor, o sistema chega sozinho ao valor de cada tributo. O operador pode **substituir** esse valor — e, para fazê-lo, o sistema **exige uma justificativa de no mínimo 20 caracteres**. Essa troca fica registrada, e é nesta área da ficha da nota que ela é respondida.

1. Na ficha da nota de entrada, use **"Calcular retenções"**. No painel, ajuste o valor de um tributo e escreva a justificativa; confirme.
2. De volta à ficha, o card **"Sobreposições manuais"** passa a mostrar, para cada tributo tocado: o valor **calculado**, o valor **aplicado**, a **diferença** (destacada quando o imposto retido diminuiu), a **justificativa**, o **autor** e a **data**.
3. **O card só aparece quando existe alguma sobreposição.** A nota que seguiu o cálculo do sistema não exibe nada — ausência de card significa "ninguém mexeu", e não "não consegui verificar": se a consulta for recusada, o card aparece com o aviso de recusa, nunca vazio.

:::BlockQuote
**O autor vem de quem está logado, não do que a chamada declara.** Uma integração que informasse outro usuário no corpo da requisição seria ignorada. Sobreposições gravadas por chave de aplicação (máquina, sem usuário) aparecem como **"Não registrado"**.
:::

### Histórico de situações da requisição

Cada requisição mantém um **histórico** das mudanças de situação e datas, para acompanhar as etapas de atendimento:

1. Na ficha da requisição, abra o card **"Histórico de alterações"**. Ele lista, em ordem, cada evento (criação, submissão, aprovação, rejeição, cancelamento) com o autor e a data.
2. Clique em um evento para abrir o **detalhe** — o painel mostra o que mudou (situação anterior → nova, campos alterados).
3. Use o histórico para saber **quem pediu, quando submeteu e quem aprovou**, sem depender da memória do time.



![](https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/012-purchase-requisitions-detail.png)

### Parametrizar a política de validade (shelf life) do recebimento

O órgão pode exigir que um material entre no estoque com um mínimo de validade ainda pela frente — um lote que vence em quinze dias não serve para um almoxarifado que gira em sessenta. **Enquanto nenhuma política estiver em vigor, o recebimento aceita qualquer lote**, inclusive um que vence amanhã, e nada é sinalizado. É nesta tela que o piso é definido: um padrão para todos os materiais e, quando necessário, um mínimo mais rígido por material.

1. **Abra a política de validade.** Menu **Compras → Política de validade**. A entrada só aparece para quem tem a permissão de **gestão de inspeção de recebimento** (a mesma de quem opera a página "Inspeção de recebimento"). Quem não a tem não vê o item no menu e, ao abrir o endereço direto, recebe a mensagem de **sem acesso** — e não uma lista vazia, que se leria como "não há nada configurado".
2. **Leia o aviso do topo antes de olhar a lista.** A tela abre pelo **estado da regra**, não pela tabela\:Esse aviso é o que distingue "ninguém configurou ainda" de "está tudo certo": uma tabela vazia sozinha tem a mesma aparência das duas situações.
   - Faixa de atenção — **"Nenhuma regra de validade em vigor"**: não há política cadastrada **ou** todas estão suspensas. O recebimento não está barrando nada.
   - Faixa de confirmação — o recebimento **recusa** o item cuja validade remanescente esteja abaixo do mínimo configurado.
3. **Defina o piso.** No bloco **Definir uma política**, preencha\:Clique em **Salvar** (**Limpar** descarta o que foi digitado). Gravar de novo o mesmo alcance **substitui** a política daquele alcance — não cria uma segunda linha para o mesmo material.
   - **Vale para** — **"Todos os materiais (padrão)"** (o piso da casa) ou **"Um material"** (a exceção). Escolhendo "Um material", aparece o seletor **Material**; um material que não existe no cadastro é recusado antes de gravar.
   - **Mínimo de dias remanescentes** — obrigatório e **maior que zero**, contado da data do recebimento até a data de validade do item. Zero dia não é exigência, e o sistema recusa.
   - **Em vigor** — deixe marcado para a regra bloquear de fato. Desmarque para manter a política **registrada sem bloquear** (útil para suspender a exigência sem perder o número parametrizado).
4. **Confira a lista.** Em **Políticas configuradas**, cada linha traz **Vale para**, **Mínimo de dias remanescentes**, **Situação** (Em vigor ou Suspensa) e **Última alteração**. O padrão da casa aparece **em primeiro lugar** e as exceções por material vêm depois, identificadas por código e descrição. O lápis devolve a linha ao formulário para edição; a lixeira **remove a política imediatamente, sem pedir confirmação** — e, se era a última em vigor, o aviso de "nenhuma regra de validade em vigor" volta a aparecer no topo.

:::BlockQuote
**Qual piso vale para cada material.** A regra do **material** vence a regra padrão da casa. Atenção à consequência: se a regra do material estiver **suspensa**, aquele material fica **sem nenhuma exigência** — ele **não** volta a cair no padrão. Para que um material siga o padrão da casa, **remova** a regra específica dele em vez de suspendê-la.
:::

:::BlockQuote
**A verificação atua sobre a validade informada no item recebido.** A data se informa na coluna **Validade** de cada linha, em **Compras → Recebimentos → Novo recebimento** — o campo é opcional, porque a maioria dos materiais não tem validade. Item recebido **sem** data de validade não é barrado: não há o que comparar. A regra também depende de o item do pedido apontar um **produto** cadastrado (item de texto livre não entra na verificação). Quando o lote é recusado, a mensagem nomeia **qual item** violou o piso, para o conferente saber qual linha devolver ao fornecedor.
:::

:::BlockQuote
**A recusa acontece ao salvar o recebimento, não ao fechar a conferência.** A regra roda no registro do recebimento: se a validade estiver abaixo do piso, o recebimento **não é criado**. Quem espera o bloqueio no fechamento da conferência cega conclui, erradamente, que a política não está funcionando.
:::

### Acompanhar o que o fornecedor ainda deve entregar

O painel de **pedidos pendentes** responde a uma pergunta só: **o que já foi pedido e ainda não chegou**. Ele lista, por item, quanto foi pedido, quanto já foi recebido e quanto falta — e o valor que esse saldo representa. Pedido totalmente recebido sai do painel sozinho; pedido cancelado também.

1. **Abra o painel.** Menu **Compras → Pedidos pendentes**, ou o botão **"Pedidos pendentes"** na tela de pedidos.
2. **Leia os três números do topo antes da lista.** **Pedidos pendentes**, **Em atraso** e **Valor a receber**. Eles cobrem **todos** os pedidos que atendem aos filtros — não apenas os que couberam na página que está na tela. É por isso que avançar de página não muda os totais: o número embaixo deles diz isso em uma linha.
3. **Estreite pelo que você precisa cobrar.**&#x54;rocar qualquer filtro volta para a **primeira página**. Quando nada atende, o painel diz **"Nenhum pedido pendente atende a estes filtros"** — e não a lista completa, que faria parecer que o filtro foi ignorado.
   - **Fornecedor** — busca no cadastro inteiro conforme você digita (não é uma lista curta pré-carregada).
   - **Entrega** — Somente atrasados (a previsão já passou) ou Somente no prazo.
   - **Situação** — Aberto, Aprovado ou Recebido parcial. São as únicas situações que um pedido pendente pode ter; escolher qualquer outra devolve painel vazio, porque de fato não há o que mostrar.
   - **Texto** — casa **número do pedido**, **nome do fornecedor** e **descrição do item**. Tecle Enter ou clique em **Buscar**.
4. **Ordene pelo que interessa naquele momento.** Data prevista (padrão), **valor pendente** (maior primeiro — o que está segurando mais dinheiro), número do pedido ou fornecedor.
5. **Clique no número do pedido para abrir a ficha.** É de lá que se **aprova**, **cancela** ou se altera a entrega prevista — o painel mostra e localiza; quem age é a ficha do pedido.

:::BlockQuote
**"Em atraso" compara a data prevista de entrega com hoje.** Pedido **sem** data prevista nunca aparece como atrasado — não há com o que comparar. Se o painel mostra zero atrasados num dia em que você esperava vários, confira se os pedidos têm a **entrega prevista** preenchida antes de concluir que o alerta falhou.
:::

### Encerrar o saldo de um pedido que o fornecedor abandonou

Um pedido do qual chegou só uma parte fica **Recebido parcial** e, normalmente, só sai desse estado quando o fornecedor entrega o resto. Quando ele não vai entregar — faliu, o item saiu de linha, a entrega parcial foi aceita como final — o saldo ficaria no painel de pendências para sempre, somando nos três totais. É para esse caso que existe o **encerramento do saldo pendente**.

1. **Abra a ficha do pedido.** O botão **"Encerrar saldo pendente"** só aparece quando a situação é Recebido parcial — nos demais estados ele não existe, porque não há saldo abandonado a encerrar.
2. **Informe o motivo.** O sistema pergunta por que o restante nunca vai chegar e **não segue sem resposta**. O texto vai para a trilha de auditoria junto com quem encerrou e quando: é o que o controle interno pergunta depois. Limite de 500 caracteres — um motivo maior é **recusado**, não cortado.
3. **Confira o resultado.** A situação passa a **Saldo encerrado**, o pedido sai do painel de pendências e para de entrar no alerta de atraso e na previsão de suprimento.

:::BlockQuote
**A quantidade pedida NÃO é alterada.** Ela é o que foi contratado, e a diferença entre ela e o que chegou é a medida do que o fornecedor deixou de entregar — informação que alimenta a avaliação de qualidade dele. Encerrar o saldo não é "acertar o pedido para o que veio": é declarar que o resto não vem.
:::

:::BlockQuote
**O empenho volta para o orçamento.** Aprovar um pedido reserva o valor na linha orçamentária. Ao encerrar o saldo, a parte que ainda estava reservada e não virou nota é devolvida à linha — dinheiro que ninguém vai gastar deixa de reduzir o disponível do órgão. A parte que já virou nota fiscal não volta: ela deixou de ser reserva quando a nota foi lançada.
:::

:::BlockQuote
**Não há como desfazer nesta versão, e o aviso diz isso antes de confirmar.** Se o fornecedor voltar a entregar depois de um encerramento, o caminho é um pedido novo. Também não é possível registrar recebimento contra um pedido com saldo encerrado — a tentativa é recusada.
:::

## Verificação

***

Você sabe que funcionou quando:

- A requisição aparece com situação Aprovada.
- A cotação mostra os preços de 2-3 fornecedores e o vencedor marcado item a item, com o mapa comparativo preenchido.
- O pedido de compra aparece com fornecedor, valor, condição de pagamento e prazo de entrega, com situação Aberto (ou Aprovado, se passou por alçada de pedido) — liberado para recebimento.
- O recebimento gerou **movimento de entrada** no almoxarifado escolhido ([Estoque](docId\:CVozhYtoHDtuWZyT-bnAT)) e o pedido ficou Recebido (total ou parcial).
- A nota de entrada gerou a **conta a pagar** para o fornecedor com o vencimento correto ([Financeiro — títulos (contas a pagar e a receber)](docId\:D4kuGidayU2GQ-hMhF_T-)) e o **lançamento contábil** correspondente ([Contabilidade](docId:08cbTyrT0WXBp4ymvrog_)).
- Quando houve reprovação, a não conformidade aparece com a origem ligada ao recebimento, e o IQF do fornecedor reflete o histórico.
- Em **Compras → Política de validade**, o topo mostra a faixa de confirmação (recebimento recusa item abaixo do mínimo) — e **não** o aviso de "nenhuma regra de validade em vigor" —, com o padrão da casa listado em primeiro lugar e situação Em vigor.

## Erros comuns

***

- **Cotação não encontra fornecedores** — confira se eles estão marcados com o papel **Fornecedor** na página [Cadastros gerais (parceiros e produtos)](docId:6xpQsdWQ2NTyI40BFqDS-).
- **Pedido bloqueado por alçada** — o aprovador padrão pode estar com teto insuficiente para o valor; revise as alçadas em [Administração](docId\:Z8SS7r6Bvhs09rP1SPxUD).
- **Requisição não salva o centro de custo** — com um **solicitante** escolhido, o centro de custo precisa estar entre os **autorizados** dele (cadastro na página [Administração](docId\:Z8SS7r6Bvhs09rP1SPxUD)); com mais de um autorizado, é obrigatório escolher.
- **Não consigo marcar "Estoque" no item** — marque um **produto** antes; item de estoque exige produto (texto livre não alimenta o inventário).
- **Recebimento divergente do pedido** — ajuste as quantidades; o sistema aceita recebimento parcial e mantém o pedido em Recebido parcial até completar.
- **Requisição não deixa submeter** — uma requisição **sem nenhum item** não pode ser enviada para aprovação; adicione ao menos um item e ela permanece em Rascunho até isso.
- **Nota de entrada não gera a conta a pagar** — a nota precisa de uma **categoria financeira** ([Financeiro — cadastros de apoio](docId\:yTzjjyyML1B_60VgwDT09)); sem ela, a conta a pagar não é criada.
- **Avaliação de fornecedor recusada** — a nota precisa ficar **entre 0 e 100** e a avaliação precisa estar **vinculada a um recebimento**; sem isso o sistema recusa o registro. O recebimento tem de **existir de verdade e ser daquele fornecedor** — um número inventado, ou o recebimento de outra empresa, é recusado com a explicação. A regra existe porque a avaliação alimenta o **IQF**, o índice que classifica o fornecedor: sem lastro numa entrega real, o índice diria algo que nunca aconteceu.
- **"Você não tem autorização" ao avaliar ou desqualificar um fornecedor** — avaliar e qualificar fornecedor é ato de **suprimentos**: quem não ocupa um cargo de compras é recusado, e isso vale também para as consultas de avaliações e qualificações. Desqualificar um fornecedor com **"bloqueia pedidos"** o retira das cotações do órgão, então a autoridade é a do gestor de compras e do comprador. Se o cargo certo estiver recebendo a recusa, confira a operação **Avaliar fornecedor** em **Administração → Autorizações**.
- **Recebimento recusado por validade** — o item chegou com validade remanescente **abaixo do mínimo** parametrizado; a mensagem nomeia o item. Devolva o lote ao fornecedor ou, se o piso estiver errado para aquele material, ajuste-o em **Compras → Política de validade**.
- **Cadastrei a política e o lote entrou assim mesmo** — confira três coisas na ordem: a política do material (ou o padrão) está com situação Em vigor e não Suspensa; o item do recebimento teve a coluna **Validade** preenchida no momento de registrar (em branco, a regra não tem o que comparar e deixa passar); e o item do pedido aponta um **produto** cadastrado (texto livre não entra na verificação). Lembre que uma regra **específica suspensa** deixa aquele material sem exigência nenhuma — não o devolve ao padrão da casa.
- **"Sem autorização" em Compras** — a autoridade vem do **cargo** (lotação), não de um papel de administrador. Criar/aprovar requisição ou pedido, e receber mercadoria, exigem um usuário com cargo de compras; o administrador de plataforma sem cargo recebe "sem autorização" por design. Troque para um perfil com cargo ([Administração](docId\:Z8SS7r6Bvhs09rP1SPxUD)).


[title] Workflow & Service Management
[path] Aplicações/

O <font color="#3b9f0f">**CITSmart**</font> é uma plataforma totalmente web, desenvolvida para transformar a maneira como as empresas conectam pessoas a recursos digitais. Uma de suas plataformas principais é a de **Workflow & Service Management**, que é inteiramente baseada nos conceitos de Information Technology Infrastructure Library (ITIL), uma biblioteca que padroniza nomenclaturas, processos e práticas presentes em ambientes de Tecnologia da Informação.&#x20;



No ambiente de Service Management do CITSmart (ITSM), você encontrará facilidade para configurar o gerenciamento dos **Processos ITIL**. Nossa plataforma **CITSmart X v10** possui a certificação PINKVerify em 21 processos na versão 4 ITIL, o que garante a integração e execução correta dos processos de acordo com as melhores práticas disponíveis.&#x20;

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/1ytI_oTawqockVz0LfX_F_thumbnail-pink-verify-2023-02.jpg" size="28" width="1920" height="709" position="center" darkWidth="1920" darkHeight="709" showCaption="false"}

Os processos de TI não são algo estático, todos estão em constante movimento e passam por mudanças aceleradas. Para garantir total funcionalidade e integração entre os processos, é necessário a utilização de **Fluxos.&#x20;**

No CITSmart, a funcionalidade de **Workflow** tem a finalidade de modelar seus objetivos de negócio, descrevendo os passos que precisam ser executados para atingir esses objetivos através de um fluxo digital inteligente.&#x20;

Na sessão de **Workflow & Service Management&#x20;**&#x64;a nossa documentação, você encontrará mais informações sobre os processos ITIL, fluxos de trabalho e como configurá-los:

[https://docs.citsmart.com/workflow](https://docs.citsmart.com/workflow)




[title] Administração
[path] Aplicações/ERP/Manual do Usuário/

# Administração, segurança e plataforma (usuários, alçadas, LGPD, notificações)

:::BlockQuote
Pré-requisitos: [Cadastro fiscal próprio](docId\:Q-zx6Qk4pMFD09yrhmsve). Esta página é executada pelo **perfil administrador** do tenant. A maior parte dos operadores nunca precisa abrir estas telas.
:::

## Introdução

***

A administração é o **posto de controle** do tenant: define quem pode entrar (usuários e papéis de login), qual a **estrutura organizacional** (empregados, cargos, lotação) que sustenta a autoridade, até que valor cada cargo pode aprovar/cancelar/transmitir (a *alçada*), a **delegação** dessa autoridade quando o titular se ausenta, e as travas de segurança da plataforma — sessões ativas, faixas de IP, trilha de auditoria e chaves de integração. Cobre ainda a **conformidade com a LGPD** (incidentes de dados, direitos do titular, consentimentos de campanha) e a plataforma de **notificações** (modelos, preferências e reprocessamento de e-mails que falharam).

:::BlockQuote
**As duas camadas (não confundir).** O **login** só autentica — diz *quem é a pessoa*. A **autoridade** (alçada) vem do **cargo** que o empregado ocupa pela **lotação** — diz *o que ele pode aprovar e até quanto*. Um mesmo login pode mudar de cargo (e de alçada) sem trocar de usuário. Por isso, para dar poder de aprovação a alguém, você mexe no **cargo** e na **lotação**, não no usuário.
:::

:::BlockQuote
**Onde ficam as telas de pessoal.** **Empregados**, **Cargos** e **Competências** saíram do menu Administração e passaram a viver no grupo **Recursos humanos**, porque a gestão de pessoas deixou de ser três telas de configuração. Continuam documentadas aqui — é onde a alçada por cargo é explicada, e separar o passo a passo da regra de autoridade deixaria as duas metades incompletas. A **delegação** de alçada segue em Administração: ela delega *autoridade*, não vínculo de trabalho.
:::

## Passo a passo

***

### Provisionar usuários de acesso

O usuário é apenas a credencial de login — quem autentica a pessoa e carrega os papéis de acesso. A autoridade de aprovação vem depois, pelo cargo.

1. **Abra "Usuários".** Menu **Administração → Usuários**. A lista mostra os logins do tenant, com nome, e-mail, papéis e situação.
2. **Novo usuário.** Informe nome, e-mail e os **papéis** de acesso (ex.: usuário comum, aprovador financeiro, administrador). O sistema cria a credencial no provedor de identidade e dispara um e-mail para a pessoa definir a própria senha.
3. **Salve.** A pessoa recebe o link de cadastro de senha por e-mail e, em seguida, consegue entrar. O que ela vê e pode fazer depende dos papéis atribuídos aqui e da alçada do cargo que ela ocupa (adiante).

### Cadastrar cargos (organograma e escalonamento)

:::BlockQuote
**Permissão exigida (por design).** Todo o cluster de estrutura organizacional — **departamentos, cargos, empregados, lotação, centros de custo autorizados e delegações** — fica atrás de uma permissão própria (MANAGE\_DEPARTMENTS, tipicamente do administrador de RH/organização). Um usuário que **não** carrega essa permissão recebe **"Você não tem autorização para esta operação"** (bloqueio *fail-closed*) ao tentar cadastrar, listar ou editar qualquer desses itens — inclusive só **abrir a lista** de empregados. Isso não é defeito: é a mesma segmentação por papel que governa Compras. Se você bater nesse bloqueio, autentique com o papel correto.
:::

A alçada é do **cargo**, não do usuário. Antes de criar regras de alçada, cadastre os cargos da organização e a cadeia de chefia por onde os valores sobem.

1. **Abra "Cargos".** Menu **Recursos humanos → Cargos**. A tela mostra o **organograma** (cargos por chefia) à esquerda e, ao selecionar um cargo, à direita: a **alçada** ligada a ele (operação, teto, *centro de custo*) e a **cadeia de escalonamento** — para qual cargo o valor sobe quando passa do teto.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/132-positions.png" alt caption width="3200" height="2000"}
2. **Novo cargo.** Informe nome, **chefia** (cargo-pai — opcional; em branco = topo do organograma) e descrição. O sistema recusa uma chefia que criaria um ciclo (A chefia de B que chefia A). Um empregado passa a exercer a alçada do cargo pela **lotação** — o vínculo que registra quem ocupa o cargo.

### Descrever o que o cargo exige (competências)

A alçada diz o que quem ocupa o cargo **pode fazer**; o perfil diz o que se **espera** dele. É esse perfil que o processo seletivo usa para triar candidato, a avaliação de desempenho para pontuar, e o plano de desenvolvimento para apontar lacuna.

5a. **Cadastre as competências da organização.** Menu **Recursos humanos → Competências**. Informe código (único), nome, **natureza** (técnica ou comportamental), descrição e o **teto da escala** — o nível máximo em que aquela competência pode ser avaliada.

O teto vive na competência, não numa configuração global, porque cada uma é medida na sua própria escala. Um cargo **não pode exigir nível acima dele**: a tentativa é recusada informando qual é o teto válido.

Competência não é apagada, apenas **inativada** — apagar levaria o histórico de avaliação junto. A tela guarda histórico de alterações: quem mudou, quando e de quê para quê.

5b. **Descreva o perfil do cargo.** Na tela de **Cargos**, selecione um cargo no organograma. Abaixo da alçada aparece o bloco **"O que este cargo exige"**. Use **Adicionar competência**, escolha a competência, o **nível exigido** e se ela é obrigatória. O nível é editável direto na lista.

:::BlockQuote
**Armadilha que vale conhecer.** Neste produto o cargo **é** a cadeira do organograma: cinco cadeiras de "Analista de Compras Pleno" em três departamentos são **cinco cargos**, cada um com o seu próprio perfil. Ao revisar uma exigência, **confira os cargos irmãos de mesmo nome** — senão três ficam atualizados e dois não, e a diferença só aparece meses depois.
:::

5c. **Copie o perfil de um cargo irmão.** No mesmo bloco, escolha um cargo em **"Copiar perfil de"** e clique em **Pré-visualizar cópia**. O sistema mostra um **rascunho** com as competências e os níveis do cargo de origem, deixando de fora as que este cargo já exige — **nada é gravado até você confirmar**. Revise, ajuste o que for diferente e confirme.

5d. **Registre as certificações que o cargo exige.** Ainda na tela de **Cargos**, abaixo das competências fica o bloco **"Certificações que este cargo exige"**. Clique em **Adicionar certificação** e informe o nome (ex.: "CNH categoria D"), o **órgão emissor** quando houver, e a **validade em meses**.

:::BlockQuote
**O campo de validade decide se alguém vai ser cobrado.** Deixar a validade **em branco** significa que a habilitação **não expira** — e essa certificação nunca entra na cobrança de recertificação. Deixe em branco **de propósito**, não por esquecimento: é a diferença entre um registro que o sistema acompanha e um que ele ignora para sempre. **Zero não serve** para dizer "não expira": o sistema recusa, porque prazo zero deixaria a exigência permanentemente vencida.
:::

5e. **Descreva as funções que compõem o cargo.** No bloco **"Funções que compõem este cargo"**, use **Acrescentar função** e escreva uma atribuição por linha. Reordene com as setas ↑ e ↓ e remova com a lixeira.

Função **não** é competência: competência é o que a pessoa precisa **saber**, função é o que ela precisa **fazer**. É a lista de atribuições que se publica num edital de concurso e que orienta a conversa de avaliação.

:::BlockQuote
**A ordem só vale depois de salvar.** Reordenar e editar mexem apenas na tela; clique em **Salvar lista e ordem** para gravar. O sistema grava a lista **inteira** de uma vez — não linha por linha — e por isso a numeração nunca fica com buracos. Linhas em branco são descartadas na gravação, em vez de barrarem o resto da sua edição.
:::

### Registrar a faixa salarial do cargo

A faixa é o intervalo que a organização considera adequado para o cargo, por nível. É contra ela que um reajuste ou uma promoção é medido — sem faixa, cada decisão salarial vira uma negociação isolada.

:::BlockQuote
**Esta tela pede autorização própria.** Menu **Recursos humanos → Faixas salariais** só aparece para quem carrega a permissão de **ler faixas salariais**. Ter a leitura genérica de cadastros **não basta**: remuneração é dado sensível e foi deliberadamente separada. Se o item não está no seu menu, é por isso — e não por defeito.
:::

6a. **Abra "Faixas salariais"** e escolha o cargo. A lista mostra as faixas já cadastradas, com nível, mínimo, ponto médio, máximo e a vigência de cada uma.

6b. **Cadastre uma faixa.** Clique em **Nova faixa** e informe o **nível** (ex.: "Sênior"), o **mínimo**, o **máximo**, opcionalmente o **ponto médio**, e a data em que passa a valer. O sistema recusa mínimo maior que o máximo, e ponto médio fora do intervalo, dizendo quais números estão em conflito.

:::BlockQuote
**Cadastrar uma faixa nova não apaga a anterior.** Se a nova começa depois, o sistema **encerra a atual na véspera** daquela data, na mesma operação. A faixa antiga continua legível — é ela que justifica uma decisão salarial tomada quando valia. Por isso não existe "excluir faixa".
:::

:::BlockQuote
**Vigências não podem se sobrepor.** Duas faixas do mesmo cargo e nível nunca valem ao mesmo tempo. Ao tentar, o sistema recusa e informa a partir de quando a faixa conflitante já vale.
:::

6c. **Consulte qual faixa valia numa data.** No bloco **"Qual faixa valia numa data"**, informe o nível e a data — em branco significa hoje. É o que responde "contra qual intervalo esta promoção de dois anos atrás foi avaliada".

6d. **Veja o histórico.** Selecione uma faixa na lista: abaixo aparece o histórico de alterações, com autor, data e os valores antes e depois. Faixa salarial é a primeira coisa que uma auditoria pergunta.

:::BlockQuote
**A faixa é deste cargo, não do nome do cargo.** Cinco cadeiras de "Analista de Compras Pleno" carregam **cinco faixas separadas**. Ao reajustar, confira os cargos irmãos de mesmo nome.
:::

### Conferir divergências entre cargos de mesmo nome

Neste produto o cargo **é** a cadeira do organograma. Cinco cadeiras de "Analista de Compras Pleno" são cinco cargos, cada um com o seu perfil e a sua faixa — e no dia do reajuste três são atualizadas e duas ficam para trás, porque ninguém sabia que existiam. O problema não aparece no dia seguinte: aparece meses depois, quando duas pessoas no mesmo cargo descobrem que estão em faixas diferentes.

Esta tela é a rede que torna isso administrável.

6e. **Abra "Divergências entre cargos"** no menu **Recursos humanos**. O sistema agrupa os cargos **ativos** pelo nome — ignorando maiúsculas e espaços a mais, porque "Analista de Compras Pleno" e "analista de compras pleno" são o mesmo cargo na intenção de quem cadastrou — e compara, em cada grupo, as competências exigidas com os seus níveis e a faixa vigente.

:::BlockQuote
**A tela sempre diz quanto foi comparado**, mesmo quando não há nada a corrigir. "Nenhuma divergência" e "a comparação não rodou" produziriam a mesma tela vazia, e a segunda é um defeito silencioso.
:::

6f. **Leia o apontamento.** Cada grupo divergente mostra em quê os cargos se afastaram — competências diferentes, faixa diferente, ou as duas — e lista cada cadeira com o que ela exige e o que paga hoje.

6g. **Corrija, ou registre que a diferença é intencional.** Dois cargos de mesmo nome podem legitimamente diferir. Clique em **"Esta diferença é intencional"** e escreva o motivo — o motivo é obrigatório, porque aceite sem justificativa não se distingue de alguém apagando um aviso para ele sumir.

:::BlockQuote
**O aceite não é permanente, e é de propósito.** Ele fica selado contra o estado que você olhou. Se qualquer coisa naquele grupo mudar depois — uma competência acrescentada, um nível alterado, uma faixa reajustada — o selo deixa de bater e **o grupo volta a aparecer**. É o que impede que um "marcar como resolvido" silencie para sempre justamente a revisão que a tela existe para pegar.
:::

### Cadastrar empregados, lotação e centros de custo

O **empregado** é a base da estrutura: dele dependem a lotação (onde trabalha e em que cargo), os centros de custo autorizados e a alçada (que vem do cargo).

1. **Abra "Empregados".** Menu **Recursos humanos → Empregados**. A lista reúne os empregados com nome, *CPF*, e-mail e situação. Ela exige a permissão de RH/organização (MANAGE\_DEPARTMENTS, ver nota acima): sem ela, o carregamento é **recusado** (bloqueio *fail-closed*); no ambiente de demonstração, o perfil padrão não carrega essa permissão, e a tela fica em "Carregando…" sem trazer dados.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/131-employees.png" alt caption width="3200" height="2000"}
2. **Novo empregado.** Informe nome, CPF (único por tenant), e-mail, situação (Ativo/Inativo) e, opcionalmente, o **usuário de acesso** (o login provisionado no passo 2). Lembre: o login só autentica; a alçada vem do cargo da lotação.

7-A. **Dados declaratórios.** Na ficha do empregado, no cartão **"Dados declaratórios"**, registre o que o governo pede no evento de admissão e que não cabe no cadastro básico: **nome social**, **data de nascimento**, **PIS/NIS**, **CTPS** (número, série e UF), **raça/cor**, **estado civil** e o bloco de **deficiência**.

:::BlockQuote
**Nada aqui é obrigatório para salvar, e isso é deliberado.** O bloco é completado **conforme os documentos chegam** — registrar a admissão hoje com a CTPS chegando semana que vem é o caso normal, não erro. Quem confere a completude é a **declaração**, na hora de transmitir. Se o cadastro exigisse tudo de uma vez, alguém digitaria um número qualquer para passar da tela, e dado inventado é pior que dado faltando: ele **parece** informação.**O PIS/NIS é conferido ao salvar.** Digite como o documento imprime, com pontuação — o sistema normaliza. O que ele recusa é **dígito verificador inválido**: número errado volta como **rejeição do lote inteiro**, meses depois, e a rejeição não diz de quem é.**A deficiência são cinco afirmações independentes**, não uma escolha: física, visual, auditiva, mental e intelectual. A mesma pessoa pode ter mais de uma, e o governo as declara assim. **"Conta na cota legal" é decisão à parte** — o sistema recusa marcá-la para quem não tem nenhuma deficiência declarada **nem** é reabilitado pela previdência (Lei 8.213/1991, art. 93), porque contar quem não é infla o relatório de cota, que é o primeiro número que a fiscalização confere.**O nome social não substitui o nome civil.** O CPF e a CTPS carregam o civil, e a declaração precisa dos dois — por isso são campos separados.**Este cartão tem permissão própria**, mais estreita que a do cadastro: raça/cor, deficiência e nome social são dado sensível (LGPD), e quem não a tem **não vê o cartão** — não vê um formulário vazio, que se leria como "nada foi declarado". O histórico logo abaixo mostra quem alterou e o quê.
:::

7-B. **Dependentes.** No cartão **"Dependentes"**, cadastre filhos, cônjuge e demais dependentes com **nome**, **tipo** (Tabela 07 do eSocial), **data de nascimento** e **documento**. Depois, pelo botão **"Registrar direito"** de cada linha, informe **qual direito** aquele dependente carrega e **desde quando**.

:::BlockQuote
**Os dependentes são da PESSOA, não de um vínculo.** Quem tem dois contratos no grupo tem os mesmos filhos nos dois — por isso o cartão está aqui, na ficha do empregado, e não no contrato de trabalho. Cadastrá-los por contrato faria a mesma criança existir duas vezes, e as duas cópias divergiriam no primeiro aniversário.**São DOIS direitos separados, e essa é a parte que mais custa se for tratada como uma só.** A **dedução de IRRF** vale até **21 anos** (24 cursando ensino superior ou técnico) e vale **também para o cônjuge**; o **salário-família** vai até **14 anos** e tem **teto de renda**. Os dois conjuntos se cruzam mas não coincidem: um filho de 16 anos **deduz e não gera** salário-família; um cônjuge **deduz e nunca gera**. Uma marcação só erraria esses casos **em silêncio** — o contracheque sairia plausível.**O limite AVISA; ele não desliga nada.** O cartão mostra, para cada dependente, até quando cada direito valeria, e marca em vermelho o que já passou. Quem muda o estado é você. Registrar um período que passa do limite é legítimo — universitário, dependente inválido — mas o sistema **exige o motivo por escrito**: é ele que responde à fiscalização anos depois.**O documento pode ficar vazio.** Recém-nascido não tem CPF nas primeiras semanas, e inventar um manda o número errado para o governo. O que o sistema recusa é **o mesmo CPF duas vezes** para a mesma pessoa — o evento sairia com o dependente repetido e voltaria recusado.**Este cartão também tem permissão própria.** Nome, CPF e data de nascimento de filhos são dado pessoal de **terceiro**, com a proteção reforçada da LGPD quando é criança. Quem não tem a permissão não vê o cartão.
:::

7-C. **Foto.** No cartão **"Foto"**, use **"Enviar foto"** para escolher a imagem. Trocar por outra é o mesmo botão, agora escrito **"Trocar"**; **"Remover"** deixa a pessoa sem foto.

:::BlockQuote
**Uma vigente, sempre.** Trocar a foto **aposenta a anterior na mesma operação** — nunca ficam duas. É o que faz "a foto do fulano" ter uma resposta só quando o crachá, a ficha de empregado e a folha forem buscá-la.**A foto responde à permissão do CADASTRO DE PESSOAS, não à de anexos** — e essa distinção é a razão de o cartão existir separado. Ela não é visível olhando a tela: a permissão genérica de anexos é detida por praticamente todo cargo, e se a foto respondesse a ela, o rosto de qualquer empregado ficaria listável e baixável pela tela genérica de **Anexos** por quem não pode nem abrir a ficha. Aqui não fica — quem não tem a permissão do cadastro leva recusa **em todas as portas**: no cartão, na tela de anexos e no download direto por link.**O campo aceita imagem, e diz isso quando não é.** Arrastar para cá o PDF do contrato devolve uma recusa que **nomeia** o problema: este campo quer foto, e o PDF vai na pasta de documentos da pessoa.
:::

1.

**Registrar uma lotação para o mês que vem não tira a pessoa da lotação de hoje.** A anterior é **encerrada na véspera** do início da nova, e continua sendo a lotação vigente até lá — é dela que saem o cargo, o departamento, o teto de alçada e os centros de custo que a pessoa pode apropriar. Agendar uma promoção com antecedência é operação normal e não deixa ninguém sem lotação no intervalo.

**A coluna "Primária" tem três leituras, e a do meio costuma assustar.** **Primária** é a que vale hoje. **Primária a partir de \<data>** é uma lotação que você marcou como primária e que **ainda não começou** — o caso normal de quem registra uma promoção com antecedência; a marcação pegou, ela só entra em vigor na data. E **—** é uma lotação não primária, ou uma já encerrada.

**A mesma área e o mesmo cargo, duas vezes no mesmo período, é recusado.** A recusa nomeia a lotação que já cobre aquelas datas. Duas lotações sobrepostas contam a **mesma pessoa duas vezes** em tudo que é apurado por unidade — população de benefício, rateio de custo —, e o número sai plausível.

**O motivo é obrigatório e vai para a trilha de vida funcional.** Vale a mesma regra do cadastro trabalhista: o sistema sabe **o quê** (comparando antes e depois), **quando** e **quem**; o **por quê** não está em campo nenhum e é a primeira coisa que um auditor procura. Escreva "reestruturação da diretoria", "pedido do próprio empregado", "assumiu a coordenação da equipe" — não "mudança de lotação", que a espécie já diz.

**"O que é esta mudança" é declaração, não dedução — e é por isso que é um campo.** As opções são **Mudança de lotação** e **Promoção**. O sistema **não** adivinha: mover alguém de área e promover alguém mexem exatamente nos mesmos dois campos (departamento e cargo), e a diferença não está no dado — está no que a organização decidiu. Como o lançamento na trilha **não se edita nem se apaga**, uma dedução errada ficaria gravada para sempre. Uma promoção que também mexe no salário produz **dois** lançamentos, um aqui e outro no cartão de remuneração do contrato, e isso é o comportamento certo: as duas datas de efeito nem sempre coincidem.

**Atribuir o vínculo por essa porta deixa rastro**, como qualquer correção de passado: entra uma **Mudança de lotação** na trilha de movimentação, com o motivo que você escreveu. Até esta data não deixava — a correção não gravava o vínculo, e a inscrição na trilha dependia justamente dele.

**Lotações antigas aparecem como "Registrada antes de existir vínculo"** — são as linhas gravadas antes de o contrato de trabalho existir no sistema, e elas continuam valendo. **Desde 2026-08-06 dá para atribuir o vínculo a elas**, pelo botão **Corrigir lotação passada** da própria linha (passo 10): escolha o vínculo, escreva o motivo e salve. O sistema **preenche** um vínculo que estava vazio e **recusa trocar** um que já esteja preenchido — trocar moveria um trecho da vida funcional de um vínculo para outro, e a trilha já escrita contra o anterior continuaria apontando para ele. Para esse caso, encerre a lotação e registre outra no vínculo certo.

**O vínculo vem primeiro, e é campo novo.** A lotação diz *onde a pessoa trabalha*; o **contrato de trabalho** diz *por qual empresa*. Quem tem dois vínculos no grupo — dois contratos simultâneos, ou o vínculo novo depois de uma sucessão — tem **duas** vidas funcionais, e uma lotação que nomeasse só a pessoa não diria qual das duas está descrevendo. Se a lista de vínculos vier vazia é porque a pessoa ainda não tem contrato: cadastre-o em **Recursos humanos → Contratos de trabalho** (ver *23 — Cadastro trabalhista*) e volte.

**Lotação.** Na ficha do empregado, no bloco **Lotação**, registre o **vínculo** + departamento + **cargo** + centro de custo padrão + vigência (início e, quando o vínculo terminar, fim), mais **o que é a mudança** e **por quê**. Marque **primária** a lotação que vale por padrão — ao registrar uma nova primária, a anterior é encerrada automaticamente como primária. O histórico de lotação fica guardado. É a lotação **vigente** (primária, início ≤ hoje, sem fim) que define o cargo (e a alçada) e o centro de custo padrão do empregado.

1. **Trilha de uma lotação.** Cada linha do histórico traz o botão **Trilha**, que abre o que mudou naquela linha, campo a campo, com quem mudou e quando. É a trilha **daquela** lotação, e não do bloco inteiro: qual linha mudou é metade da pergunta que uma auditoria faz.
2.

**E há um terceiro caso, que não trava mas também não passa calado:** quando **não existe folha nenhuma** para a competência tocada, o sistema não tem como afirmar que ela está aberta. A recusa aí é **diferente** da anterior e diz o que falta — porque mandar o operador "retificar a folha" quando não há folha a retificar é um beco sem saída. Nesta entrega, enquanto a apuração nativa não existir e a organização não importar lote, **toda** correção retroativa cai nesse caso.

**Por que é uma porta estreita.** Lotar gente daqui pra frente é trabalho do dia a dia e não deve virar cerimônia. Reescrever um mês que já foi encerrado, pago e declarado é outro ato: a lotação é o que o rateio de custo e o encargo da folha leem para decidir **qual departamento pagou** por aquela pessoa. Mudá-la muda números que já foram reportados.

**Corrigir uma lotação já encerrada.** Linhas encerradas trazem o botão **Corrigir lotação passada**, e ele é diferente de todos os outros desta página:

:::Paragraph{listStyleType="disc" indent="2"}
**Exige autoridade própria** — **"Corrigir lotação de período passado"**, concedida em **Administração → Perfis e permissões**. Ela **não** vem junto com a permissão de RH/organização, e quem não a tem vê o botão **desabilitado com a explicação ao lado** — nunca um botão ausente, que se lê como funcionalidade inexistente.
:::

:::Paragraph{listStyleType="disc" indent="2"}
**Exige motivo**, como qualquer movimentação.
:::

:::Paragraph{listStyleType="disc" indent="2"}
**É recusada de plano quando a folha daquele mês já foi encerrada**, e a recusa **nomeia a competência**. Nenhuma alçada passa por cima: a lotação daquele mês é a base do que já foi pago, e o caminho é a retificação da folha.
:::

1. **Centros de custo autorizados.** No bloco **Centros de custo autorizados**, autorize 1 ou mais centros e marque **um como padrão**. Quando o empregado tem mais de um centro autorizado, a requisição dele **exige escolher** qual usar (e valida que o escolhido está nesta lista).

### Configurar alçadas e permissões

A alçada de Aprovar documento já apareceu na página [Financeiro — títulos (contas a pagar e a receber)](docId\:D4kuGidayU2GQ-hMhF_T-). A tela de alçadas cobre **todas as operações sensíveis** do sistema.

1. **Abra "Alçada".** Menu **Início → Alçada**. No topo, o painel **"Operações sem regra ativa"** lista o que **ainda não tem regra**: por padrão, uma operação sem regra é **liberada** a qualquer usuário autenticado. Use esse painel como checklist do que falta governar.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/004-authorization-rules.png" alt caption width="3200" height="2000"}
2. **Operações disponíveis.** O seletor de "Nova regra" lista **todas** as operações governadas (financeiro, compras, estoque, fiscal, contabilidade, tesouraria, frota, vendas, viagens etc.), ordenadas pelo nome traduzido — por exemplo: Aprovar documento, Cancelar documento, Liquidar documento, Transmitir nota fiscal, Aprovar requisição, Gerenciar orçamento, Gerenciar crédito, Aprovar venda, Gerenciar estoque.
3.

⚠️ Restringir uma regra **não** cria restrição onde não havia. Operação **sem nenhuma regra ativa** continua liberada a qualquer usuário autenticado (é o que o painel do passo 12 lista). E quem tem o cargo mas está lotado **fora** da unidade da regra simplesmente não é alcançado por ela — se não houver outra regra que o alcance, a operação lhe é negada.

**Nova regra.** Escolha **operação** + **cargo** + teto opcional. O campo de cargo é um seletor dos cargos cadastrados (tela "Cargos"): o usuário é autorizado quando o **cargo** dele (resolvido pela lotação primária vigente) casa com a regra, respeitando o teto. O campo de **centro de custo** aparece **apenas** para "Aprovar requisição" — a dimensão da despesa. Quando o valor excede o teto do cargo, o sistema **escala** automaticamente para o cargo-chefe até encontrar um que cubra (visível na tela "Cargos").**Unidade organizacional (opcional).** O mesmo cargo costuma existir em várias unidades — há "Comprador" na superintendência e "Comprador" na gerência. Deixar o campo em **"Todas as unidades (geral)"** concede a autoridade ao cargo **em todo o órgão**, que é como toda regra já cadastrada funciona. Escolher uma unidade **restringe** a regra a quem está lotado nela — e, por herança, a quem está lotado nas **unidades abaixo** dela: uma regra na superintendência alcança as gerências subordinadas, não o contrário.

1.

**Nem toda alçada é exercida na tela do documento.** Algumas operações não têm dono: quem decide é a própria autoridade aprovadora, não o documento. Elas caem numa fila separada — veja **"Decidir solicitações de aprovação"**, ao fim desta página.

**Salve.** A regra vale imediatamente e passa a aparecer na lista, com busca por cargo funcionando.

### Configurar as faixas de aprovação de vendas (inadimplência e desconto)

Além da alçada geral por cargo, o módulo de vendas tem uma tela própria para **encaminhar ao papel certo** uma venda que ficou retida — seja porque o cliente está **inadimplente**, seja porque o **desconto** passou do limite do vendedor. Em vez de decidir caso a caso quem pode liberar, você monta **faixas por valor** (ou por percentual de desconto) e liga cada faixa a um **papel aprovador**: uma venda que caia dentro de uma faixa vai para a fila de aprovação daquele papel.

Abra **Administração → Alçadas de aprovação de vendas**. A lista traz as faixas já cadastradas, com o escopo, o nível, o intervalo e o papel que aprova. Em **Nova faixa**, escolha primeiro o escopo em **Aplica-se a**: *Venda a cliente inadimplente (valor)* roteia pelo valor da operação com um cliente em atraso; *Alçada de desconto (%)* roteia pelo percentual de desconto concedido. Informe o **Nível** (inteiro ≥ 1 — use níveis crescentes quando houver mais de uma faixa no mesmo escopo) e o intervalo que aciona a faixa: **Valor mínimo** e **Valor máximo (opcional)** no escopo de inadimplência, ou **Desconto mínimo (%)** e **Desconto máximo % (opcional)** (0 a 100) no de desconto — deixe o máximo em branco para "sem teto". Por fim, escolha o **Papel aprovador**, a operação que autoriza a liberação (ex.: *Aprovar venda*): é o papel de quem vai decidir. **Salve** — a faixa vale de imediato; edite ou remova pelos ícones na linha.

A partir daí, uma venda cujo valor (ou desconto) caia dentro do intervalo é **retida** e encaminhada ao papel aprovador da faixa; a decisão acontece em **Vendas → Aprovações** ([Vendas e CRM08 — Vendas e CRM](docId\:TaINdkXLJcUzyq0xUuGfH)), com o motivo *Inadimplência* ou *Desconto*, e a venda só avança depois que a autoridade libera.

:::BlockQuote
💡 **As faixas de limite de crédito funcionam igual — e agora valem de verdade.** Na mesma tela existe o bloco de faixas para **mudança de limite de crédito**: até um valor decide o analista de crédito, acima dele decide a tesouraria, por exemplo. **A faixa vale para aprovar e para recusar**, porque recusar também encerra o pedido contra o cliente. Quem tem a autoridade de **qualquer** faixa enxerga a fila de pendentes — senão o tesoureiro, único autorizado a liberar os pedidos grandes, não conseguiria encontrá-los. Uma ressalva que evita configuração inútil: se a operação escolhida na faixa **não tiver nenhuma regra ativa** na tela de autorizações, ela não restringe ninguém (uma operação sem regra é permitida a todos), e o sistema então mantém a exigência anterior — a do analista de crédito — em vez de abrir a decisão para qualquer usuário. Configure a faixa **e** a regra da operação que ela nomeia.
:::

### Autorizar (ou não) a alteração de pedido aprovado

Um pedido de compra já aprovado pode ficar **congelado** — nenhuma mudança depois do aval — ou permanecer **editável**, hipótese em que cada alteração o **reavalia contra a alçada** de aprovação. O administrador decide isso num único interruptor em **Administração → Política de alteração de pedido aprovado**: desligado, o pedido aprovado fica travado; ligado, ele volta a aceitar mudanças e é reconferido pela alçada do cargo.



![](https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/144-purchase-order-policy.png)

### Delegar alçada (substituição)

Quando o titular de um cargo se ausenta (férias, licença) ou a função passa temporariamente a outra pessoa, registre uma **delegação**: um substituto passa a exercer a alçada do cargo no período.

1. **Abra "Delegações".** Menu **Administração → Delegações**. A lista reúne as delegações com tipo, escopo, substituto, vigência, motivo e situação; no ambiente de demonstração aparece vazia até você registrar a primeira pela ação **Nova delegação**.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/133-delegations.png" alt caption width="3200" height="2000"}
2. **Nova delegação.** Escolha o **tipo** (Temporária — com início e fim; ou Permanente — sem prazo), o **escopo** (Cargo inteiro ou uma Operação específica), o **cargo** de origem, o **substituto** (empregado) e a **justificativa** (obrigatória). Em delegação temporária, informe início e fim.
3. **Encerrar.** Em uma delegação vigente, use a ação de encerrar (com motivo opcional). O **histórico** de cada delegação (criação e encerramento) fica na trilha de auditoria — acessível pelo ícone de histórico na linha.

:::BlockQuote
Uma delegação por **operação** vence a do **cargo inteiro** para aquela operação. O sistema impede a sobreposição de duas delegações vigentes do mesmo escopo. Toda delegação é um deslocamento de poder de aprovação — por isso a justificativa e a auditoria são obrigatórias.
:::

**O que o substituto passa a poder — e até quanto.** Enquanto a delegação estiver vigente, o substituto executa as operações que o **cargo de origem** autoriza, **até o limite de valor desse cargo** — não é alçada ilimitada, e não é a alçada dele. Fora da vigência (ainda não começou, já terminou) ou depois de encerrada, ele volta a ser recusado como antes. Três situações valem conhecer:

- **Quem já podia por conta própria continua agindo por conta própria.** Se o substituto já tinha autorização para aquela operação, o sistema usa a **dele** — inclusive o limite dele — e o ato **não** é registrado como substituição. Só quem seria recusado é que passa a agir em nome de outro.
- **Duas substituições ao mesmo tempo bloqueiam.** Se a pessoa responde por **dois cargos diferentes** no mesmo dia, ou por um mesmo cargo em dois recortes que não se contêm, o sistema **recusa** em vez de escolher um: não há como dizer qual autoridade está sendo exercida. Encerre a que não vale mais e a ação volta a passar.
- **Delegação com departamento vale só ali.** Quando a substituição é confinada a uma unidade, o substituto alcança apenas o que aquela unidade (e as acima dela) alcança — nem o alcance do titular, nem o dele próprio.

### Controlar sessões ativas

1. **Abra "Sessões ativas".** Menu **Início → Sessões ativas**. A tela reúne os logins atualmente conectados, com usuário, início da sessão, último acesso e origem; no ambiente de demonstração ela aparece vazia ("Nenhuma sessão para exibir.") até que alguém esteja de fato conectado.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/005-sessions.png" alt caption width="3200" height="2000"}
2. **Encerrar uma sessão.** Em uma linha, use a ação de encerrar. A sessão revogada não consegue mais chamar o sistema — o usuário é obrigado a entrar de novo. Sessões inativas por muito tempo são encerradas automaticamente pela política de timeout do tenant.

### Restringir por faixa de IP

1. **Abra "Faixas de IP".** Menu **Início → Faixas de IP**. A tela lista os intervalos de rede autorizados a acessar o tenant.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/006-ip-allowlist.png" alt caption width="3200" height="2000"}
2. **Registrar uma faixa.** Informe o intervalo de rede (formato CIDR, ex.: 203.0.113.0/24) e uma descrição (ex.: "Rede da matriz ACME"). A partir daí, acessos de endereços **fora** das faixas cadastradas são recusados. Deixe a lista **vazia** para não aplicar restrição de IP (todos passam).

### Configurar e consultar a auditoria

Toda criação, edição e exclusão de cadastro sensível é gravada automaticamente. Você controla o que é monitorado e consulta o resultado.

1. **Configurar o que é monitorado.** Menu **Administração → Auditoria**. Marque quais entidades são acompanhadas pela trilha. Ao desmarcar uma entidade, novas operações naquela entidade deixam de gerar evento (útil para reduzir ruído em cadastros de baixo risco).
2. **Consultar a trilha.** Menu **Administração → Trilha de auditoria**. Filtre por entidade e/ou ator para investigar quem fez o quê; enquanto você não refina os filtros e busca, a área de resultados fica vazia ("Refine os filtros para começar a busca."). Cada evento traz o autor, a data/hora e o **antes/depois** da alteração (estado inicial na criação, campos alterados na edição, estado final na exclusão).:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/134-audit-events.png" alt caption width="3200" height="2000"}

:::BlockQuote
Dentro da ficha de cada cadastro há também um botão **Histórico**, que abre a mesma trilha filtrada só para aquele registro — o caminho mais rápido para investigar uma linha específica.
:::

**Quando o ato foi feito por substituição.** Um evento autorizado por *delegação* abre com a tarja **"Ato por substituição: autoridade do cargo X"**, dizendo de quem era a alçada exercida. Sem ela, a trilha mostraria alguém aprovando o que o próprio cargo não autoriza — que é como se lê um furo, não uma substituição. A informação também sai na **exportação CSV**, na coluna delegatedFromPositionId. A ausência da tarja significa que a pessoa agiu por autoridade própria.

### Emitir chaves de integração

1. **Abra "Chaves de integração".** Menu **Administração → Chaves de integração**. Aqui você emite as credenciais que sistemas externos usam para conversar com o ERP.
2.

Na mesma tela, o cartão **"Contrato da API"** é onde se abre a documentação — e ele **não é um link**: o navegador não envia cabeçalho ao navegar, então você escolhe a área de negócio, cola a chave e o sistema troca a chave por um acesso de curta duração para este navegador. O passo a passo está em *20 — Integração com sistemas externos*.

**Duas regras do escopo que surpreendem.** Operação fora do escopo é recusada **mesmo que o órgão ainda não tenha definido regra de alçada para ela** — para pessoas, "não configurei" significa liberado; para um sistema externo, significa não. E **chave nunca aprova valor**: aprovar dentro de alçada é ato de agente público, preso a um cargo, e um programa não tem cargo. Uma chave sem nenhuma operação no escopo não faz nada, propositalmente.

**Emitir uma chave.** Informe a descrição da integração (ex.: "Loja de compras do parceiro"), **escolha o escopo** — a lista de operações que aquela chave poderá executar — e emita. Copie o valor exibido: ele não é mostrado de novo. O sistema aplica limite de chamadas por minuto (rate-limit) automaticamente. Revogue a chave quando a integração for desativada; a revogação vale na chamada seguinte.

### LGPD — incidentes de dados

O ERP registra e acompanha incidentes de privacidade conforme a LGPD (art. 48), para que o prazo de notificação à autoridade e aos titulares seja cumprido.

1. **Abra "Incidentes de dados".** Menu **Início → Incidentes de dados**. A tela traz o formulário de registro no topo e, abaixo, a lista de incidentes com descrição, data, situação e prazo (vazia até o primeiro registro).:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/007-data-incidents.png" alt caption width="3200" height="2000"}
2. **Registrar um incidente.** Descreva o ocorrido, os dados afetados e as mitigações adotadas. O sistema calcula o **prazo regulatório** e o mostra na lista. A partir do registro fica disponível a exportação para comunicação à autoridade de proteção de dados.

### LGPD — direitos do titular

Um titular de dados pode pedir acesso aos próprios dados, correção ou exclusão. O ERP registra o pedido, controla o prazo e executa a exportação ou a anonimização.

1. **Abra "Direitos do titular".** Menu **Início → Direitos do titular**. Lista com titular, tipo do pedido (acesso, correção, eliminação), data e prazo legal.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/008-data-subject-requests.png" alt caption width="3200" height="2000"}
2. **Registrar um pedido.** Escolha o parceiro pessoa física, o **tipo** (acesso / correção / eliminação) e a data. O pedido aparece com o prazo regulatório a cumprir (referência: 15 dias para o direito de acesso).
3. **Exportar os dados do titular (direito de acesso).** No pedido de acesso, gere o **arquivo de dados** com tudo o que está armazenado sobre a pessoa (cadastro, históricos de pedido, notas fiscais em que é tomador, consentimentos etc.) e entregue ao titular dentro do prazo.
4. **Anonimizar (direito de esquecimento).** Para pedidos de eliminação em que **não** há obrigação fiscal de retenção, use a ação de **anonimizar**. Os dados pessoais são substituídos por marcadores (Anonimizado em DD/MM/AAAA), mas as referências fiscais/financeiras são mantidas para a escrituração — o histórico contábil continua íntegro.
5.

⚠️ **Bloqueio vale para as exportações seguintes — inclusive a de acesso e a de portabilidade.** Bloquear é *suspender qualquer tratamento* do dado, não anotar que ele é sensível. Por isso, depois de um bloqueio, um pedido de **acesso**, **portabilidade** ou **acesso por hipótese legal** do mesmo titular **não** devolve mais o dado bloqueado: o arquivo traz a linha Withheld under LGPD art. 16 (blocked) com a **entidade**, o **motivo legal** e o **prazo**. A existência do dado continua declarada — o que não se repete é a entrega. Se o titular exportar e vir só essa linha, é isso que aconteceu; não é o sistema dizendo que não há dado.

🔎 **Histórico da solicitação — o registro de quem fez o quê.** No pedido aberto, o cartão **"Histórico da solicitação"** lista cada ato: quem **registrou** o pedido, quem o **processou** (e a entrega aparece como **Exportação** quando o direito é de acesso/portabilidade, e como exclusão ou alteração quando o direito é de eliminação ou anonimização) e quem o **recusou**, com a justificativa. Clique numa linha para ver o detalhe. Esse cartão existe porque a pergunta que uma auditoria faz não é "o pedido foi atendido?" e sim "quem entregou o dado dessa pessoa, e quando" — antes ela não tinha resposta em lugar nenhum. **Quem consultou** dado pessoal (a consulta de CNPJ do cadastro de parceiros) aparece na tela **Log de auditoria**, filtrando a ação **Consulta**.

**Quando o dado é bloqueado em vez de apagado.** Se o dado está sob obrigação legal de guarda (o caso da maioria dos parceiros, pela retenção fiscal de 5 anos), o pedido de eliminação **não apaga**: registra um **bloqueio** (LGPD art. 16), e o resultado do processamento diz quantos registros foram apagados e quantos foram bloqueados. Veja os bloqueios do pedido na ação **"Bloqueios"**.

### LGPD — consentimentos de campanha

O consentimento para campanhas de marketing vive **dentro da ficha do parceiro**, não em uma tela separada — assim fica ao lado dos demais dados do cliente.

1. **Abra a ficha do parceiro.** Menu **Cadastros → Parceiros**, abra um parceiro pessoa física e vá à seção **"Consentimentos LGPD"**. A lista traz canal (e-mail / SMS / WhatsApp), finalidade (marketing / newsletter / cobrança), quando foi concedido e quando foi revogado.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/002-partners-detail.png" alt caption width="3200" height="2000"}
2. **Registrar consentimento.** Informe finalidade + canal + **versão do termo** (obrigatória, ex.: v1.0) e, opcionalmente, contato e evidência (texto ou link do registro). Registre. A linha aparece como **Ativo**.
3. **Revogar consentimento.** Em uma linha ativa, use a ação de revogar e escreva o **motivo** (ex.: "Titular pediu opt-out por e-mail em 28/05/2026"). A linha passa a **Revogado**, com a data e o motivo. A partir daí, o sistema bloqueia novas campanhas para aquele canal/finalidade.

### Notificações — modelos, preferências e falhas

As notificações são disparadas por **eventos do sistema** (pedido confirmado, nota emitida, carta de cobrança). Não existe "enviar agora" avulso — o administrador configura os modelos e as preferências, e reprocessa o que falhou.

1. **Modelos de notificação.** Menu **Início → Modelos de notificação**. Confira e edite os modelos por idioma (o mesmo evento tem versão em cada idioma do portal). Ao salvar, o novo texto passa a valer nos próximos disparos.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/009-notification-templates.png" alt caption width="3200" height="2000"}
2. **Preferências de notificação.** Menu **Início → Preferências de notificação**. Ative ou desative tipos e canais (in-app, e-mail). Desativar um tipo/canal e salvar faz com que novos eventos daquele tipo **não** notifiquem mais por aquele canal.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/011-notification-preferences.png" alt caption width="3200" height="2000"}
3. **Falhas de envio de e-mail.** Menu **Início → Falhas de envio de e-mail**. Aqui aparecem os e-mails que não saíram (destinatário inválido, erro do provedor) para você conferir o motivo e **reprocessar** os que puderem ser reenviados. Quando tudo saiu — o estado saudável, como no ambiente de demonstração — a tela mostra "Nenhuma falha de envio — todos os e-mails de notificação saíram.".:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/010-notification-delivery-failures.png" alt caption width="3200" height="2000"}

### Regras automáticas de e-mail (mapear evento → notificação)

As notificações do dia a dia (modelos, preferências, falhas) valem para o tenant. Um degrau acima ficam as **regras automáticas de e-mail**: cada regra liga um **tipo de evento de negócio** (ex.: orçamento acima do limite, pedido confirmado) a uma **notificação** — definindo os canais, os destinatários e uma condição opcional de disparo. É por aqui que se responde “quando *isto* acontecer, avise *estas* pessoas por *estes* canais”, sem pedir desenvolvimento. Atenção: esta tela é restrita ao **administrador de plataforma** — não a um cargo comum do tenant; um usuário sem esse perfil não a acessa.

1. **Abra “Regras automáticas de e-mail”.** Menu **Administração → Regras automáticas de e-mail**. A lista mostra as regras já cadastradas, com o **tipo de evento**, a **notificação** disparada, os **canais** (E-mail, No aplicativo), os **destinatários**, a **condição** e o **status** (Ativa/Inativa).:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/e32-16-notification-rules.png" alt caption width="3200" height="2000"}
2. **Nova regra.** Use **Nova regra**. O **tipo de evento** é escolhido numa **lista** — não se digita: a lista traz exatamente os eventos que o sistema publica (nota fiscal autorizada, título registrado/liquidado/cancelado/aprovado, lead registrado/qualificado/desqualificado/convertido, nota criada), com o código técnico abaixo de cada nome. Escolha também a **notificação** a enviar, os **canais** (e-mail e/ou no aplicativo), os **destinatários** e, se quiser restringir, uma **condição**. Uma regra **sem condição** dispara para **todo evento** daquele tipo.**Por que a lista, e não um campo livre.** Antes era possível digitar qualquer texto no tipo de evento. O sistema aceitava, a regra ficava **Ativa** — e nunca disparava, porque nenhum evento com aquele nome é publicado. Não havia erro em lugar nenhum: a regra parecia certa na tela e o silêncio parecia defeito do envio. Hoje o cadastro recusa um evento que ninguém publica e diz quais existem.**Se você já tem regra antiga apontando para um evento inexistente**, ela continua no banco e a lista a marca com **"Evento não publicado — esta regra nunca dispara"**. Corrija o tipo de evento (ou remova a regra): ela não foi apagada automaticamente para você não perder a configuração de canais e destinatários.**Sobre os destinatários:** a opção **"Usuários citados no evento"** não alcança ninguém hoje — nenhum evento do produto carrega usuário no seu conteúdo, e a tela avisa isso. Para e-mail, use **endereços da regra** (você digita os destinos) ou **e-mail do parceiro** (lido do parceiro que o evento cita — confira o aviso da tela, porque nem todo evento traz parceiro).
3. **Ative e salve.** Com a regra **Ativa**, todo evento do tipo escolhido passa a enviar a notificação aos destinatários resolvidos. Edite ou remova a regra pelos ícones na linha; **desative-a** para interromper os disparos sem apagá-la.

### Renomear rótulos de campos (sem codificação)

O administrador pode trocar o texto de qualquer rótulo do sistema pelo termo usado na própria organização, sem programar e sem novo deploy.

1. **Abra "Rótulos personalizados".** Menu **Administração → Rótulos personalizados**. A lista mostra as substituições já cadastradas, com a chave do rótulo, o idioma e o texto próprio.
2. **Nova substituição.** Em vez de adivinhar a chave, escolha a **Tela** e depois o **Campo** numa lista — a **chave** do rótulo é preenchida automaticamente (o modo **"Digitar a chave manualmente"** continua disponível para chaves fora do catálogo). Selecione o **idioma** (Português, Inglês ou Espanhol) e digite o **texto** da sua organização.
3. **Salve.** A troca é sobreposta ao dicionário do sistema e passa a valer no **próximo carregamento de tela** — não exige reinício nem publicação. Cada alteração exige a permissão de rótulos e vale só para o seu tenant.
4. **Histórico.** Cada substituição guarda a trilha de auditoria (quem alterou, antes/depois), acessível pelo ícone de histórico na linha.

### Base legal ao compartilhar registros de acesso (sigilo)

O compartilhamento de registros de acesso de um titular só ocorre sob uma **hipótese legal** registrada — por exemplo, ordem judicial —, preservando o sigilo e a confidencialidade.

1. **Ao registrar um pedido de acesso** do titular (menu **Início → Direitos do titular**), informe a **base legal** que autoriza o compartilhamento (ex.: *Ordem judicial*).
2. **A base legal fica gravada** no pedido e aparece tanto na lista quanto na ficha da solicitação, compondo a trilha de quem autorizou o quê e sob qual fundamento.

### Destinação dos dados ao término do contrato

Ao encerrar a relação contratual, o administrador executa uma rotina que **devolve** e depois **elimina** os dados pessoais do tenant, com comprovação (LGPD art. 15 e 16).

1. **Abra a tela de encerramento.** Menu **Início → Encerramento de contrato (destinação de dados)**. A lista mostra as execuções da rotina e a situação de cada uma.
2. **Devolver os dados.** Use **Executar a rotina** para iniciar a devolução — a situação passa a **Devolvido**, disponibilizando os dados para entrega à Controladora.
3. **Eliminar com comprovação.** Após a devolução, confirme a **eliminação**: a situação passa a **Concluído**, registrando a comprovação. Cópias são preservadas apenas nas hipóteses legais.

### Personalizar a ordem dos campos de uma tela (sem codificação)

Cada equipe usa a mesma tela de um jeito. O administrador pode **reordenar** e **ocultar** os campos de uma tela — para um usuário, um cargo ou um processo de negócio — pela própria ferramenta, sem programar e sem novo deploy. É o recurso que o mercado chama de "otimizador de tela".

1. **Abra "Ordem de campos".** Menu **Administração → Ordem de campos**. No topo, escolha a **Tela** que vai personalizar (ex.: *Parceiro*) e o **Escopo** do arranjo.
2. **Escolha o escopo.** *Toda a organização* vale para todo o tenant; *Usuário* vale só para uma pessoa; *Cargo (grupo)* vale para quem ocupa aquele cargo; *Processo de negócio* vale no contexto daquele processo. Quando o escopo pede um alvo (usuário, cargo ou processo), informe-o no campo **Alvo**.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/tech-field-layouts.png" alt caption width="3200" height="2000"}
3. **Reordene e oculte.** Use as setas **para cima/para baixo** para mudar a posição de cada campo e o ícone de **olho** para mostrar/ocultar. A numeração à esquerda reflete a ordem que o usuário verá.
4. **Salve.** O arranjo passa a valer para o escopo escolhido no **próximo carregamento da tela**. Quando um usuário se enquadra em mais de um arranjo, vale o **mais específico**: o pessoal do usuário prevalece sobre o do cargo, que prevalece sobre o do processo, que prevalece sobre o da organização. Use **Limpar escopo** para remover as personalizações daquele escopo e voltar ao padrão. Cada alteração fica na trilha de auditoria (ícone de histórico na linha) e vale só para o seu tenant.

### Criar layouts de importação e exportação de arquivos (sem codificação)

O órgão troca arquivos com outros sistemas o tempo todo, cada um com seu layout. O administrador pode **montar os próprios layouts** de importação e exportação — nos formatos **TXT** (posição fixa ou delimitado), **CSV**, **XLS** e **XML** — e usá-los para **exportar** dados do sistema ou **importar** dados de um arquivo recebido, tudo por configuração.

1. **Abra "Layouts de import/export".** Menu **Administração → Layouts de import/export**. A lista mostra os layouts já cadastrados, com nome, direção (Exportação/Importação), formato e o conjunto de dados de origem.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/tech-data-layouts.png" alt caption width="3200" height="2000"}
2. **Novo layout.** Clique em **Novo layout**. No painel à direita, dê um **nome**, escolha a **direção** (Exportação ou Importação), o **formato** (TXT/CSV/XLS/XML), o **tipo** (Delimitado ou Posição fixa) e o **conjunto de dados** de destino. Para layout delimitado, informe o **delimitador** (ex.: ;); marque **"Primeira linha é cabeçalho"** quando o arquivo tem cabeçalho.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/tech-data-layouts-builder.png" alt caption width="3200" height="2000"}
3. **Monte as colunas.** Em **Colunas**, adicione um campo por vez a partir do conjunto de dados escolhido; para cada coluna defina o **cabeçalho**, a **máscara** e se é **obrigatória** (na importação), e — em layout de posição fixa — a **posição inicial** e a **largura**. Reordene as colunas com as setas. Salve.
4. **Executar.** Num layout de **exportação**, o ícone de **download** na linha gera o arquivo no formato definido e baixa na hora. Num layout de **importação**, o ícone de **upload** abre o envio do arquivo: o sistema lê conforme o layout, valida os campos obrigatórios e as máscaras, grava as linhas válidas e devolve um **relatório** com quantas foram aceitas e quais foram recusadas (com a linha e o motivo). Cada layout guarda a trilha de auditoria e vale só para o seu tenant.

### Criar campos customizados (sem codificação)

Às vezes o órgão precisa guardar uma informação que o cadastro padrão não previu — o número do processo SEI, a modalidade da licitação, a data de vigência do contrato. Em vez de pedir desenvolvimento, o administrador **cria campos adicionais** na própria ferramenta: escolhe a tela, dá um rótulo, define o tipo e quem pode ver — sem programar e sem novo deploy. Os campos valem só para o seu tenant.

1. **Abra "Campos customizados".** Menu **Administração → Campos customizados**. No topo, escolha a **Funcionalidade (tela)** onde o campo vai aparecer (ex.: *Parceiro*). A lista mostra os campos adicionais já criados naquela tela, com o rótulo, o tipo e se é obrigatório.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/tech-custom-fields.png" alt caption width="3200" height="2000"}
2. **Novo campo.** Clique em **Novo campo**. No painel à direita, informe o **rótulo** (ex.: *Nº do processo SEI*), a **chave** (identificador estável, sugerido a partir do rótulo), o **tipo** e o **acesso**. Os **tipos** disponíveis cobrem o essencial de um formulário: Texto de linha, Texto de área, Inteiro, **Decimal**, **Moeda**, Data, Seleção, **Seleção múltipla**, Sim/Não, Opção única, **E-mail**, **URL**, **Telefone**, **Relação (lookup)** e **Fórmula (calculado)**. Para os tipos de lista (Seleção/Opção única/Seleção múltipla), monte as **opções** com **código** e **texto** — o código é o valor guardado (estável), o texto é o que aparece na tela; use **Adicionar opção** para cada uma. Marque **Obrigatório** quando o preenchimento for exigido — toda validação acontece **no servidor**.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/tech-custom-fields-drawer.png" alt caption width="3200" height="2000"}
   - **Valor padrão, ajuda e restrições.** Informe um **valor padrão** (o campo já vem preenchido num registro novo) e um **texto de ajuda** (aparece como dica sob o campo). Conforme o tipo, defina **restrições**: **mínimo/máximo** (Inteiro/Decimal/Moeda), **tamanho máximo** (textos, e-mail, URL, telefone) e um **formato** (expressão regular, para Texto de linha). O servidor recusa um valor fora do formato ou da faixa.
   - **Aparecer só quando… (visibilidade condicional).** Em **"Visibilidade condicional"**, escolha um **campo controlador** da mesma tela e o(s) **valor(es)** que revelam este campo — assim ele só aparece quando fizer sentido (ex.: mostrar *CNPJ* só quando *Tipo de pessoa = Empresa*). Um campo obrigatório que esteja escondido pela condição **não** trava o salvamento. Para regras mais ricas, clique em **"Usar uma expressão"**: escreva uma condição com comparações (==, !=, >, >=, \<, \<=, contains) e os conectivos && (E), || (OU) e ! (NÃO) sobre outros campos — ex.: \{status} == "APROVADO" && \{valor} > 1000. Referencie um campo pela sua chave entre chaves (\{chave}). O sistema **valida** a expressão ao salvar (uma condição malformada é recusada) e a aplica **igual** no servidor e na tela; **não é programação** — nenhuma linha de código do usuário é executada.
   - **Relação a outro cadastro (lookup).** Para o tipo **Relação**, escolha o **cadastro-alvo** (ex.: Parceiro, Produto); na ficha, o usuário busca e escolhe um registro existente e o sistema guarda o vínculo pelo identificador (renomear o registro não quebra a referência).
   - **Campo calculado (fórmula).** Para o tipo **Fórmula**, escreva uma expressão aritmética referenciando outros campos por \{chave} (ex.: \{preco} \* \{quantidade}), com + - \* / e parênteses. O valor é **calculado no servidor** e o campo é somente-leitura na ficha — o usuário não digita.
   - **Valor único.** Marque **Valor único** para exigir que o valor não se repita em outro registro da mesma tela (ex.: um número de protocolo). Um valor em branco é sempre aceito. (Não se aplica a Seleção múltipla.)
   - **Acesso a vários cargos e/ou usuários.** Sem nenhuma regra, o campo é visível a **todos**. Para restringir, use **Adicionar cargo** e **Adicionar usuário** quantas vezes precisar: o campo fica visível a quem estiver em **qualquer** uma das regras (vários cargos e vários usuários ao mesmo tempo). O controle de acesso do sistema sempre prevalece.
   - **Rótulo por idioma (opcional).** No bloco **"Rótulo por idioma"**, preencha o texto do rótulo em **Português, Inglês e Espanhol**. Cada usuário verá o rótulo no seu idioma; deixando um idioma em branco, aparece o rótulo padrão informado acima. Nos tipos de lista, cada **opção** também pode ter tradução por idioma. As traduções reaproveitam o mesmo mecanismo de "Rótulos personalizados" (4.3).
3. **Salve, edite ou remova.** O campo fica registrado naquela funcionalidade, para o seu tenant, e passa a compor a configuração da tela. Para **editar** um campo já criado, clique em **Editar** na linha (o rótulo, o tipo, as opções, a obrigatoriedade e o acesso mudam; a **chave** permanece a mesma); para **remover**, use **Remover**. O **controle de acesso do sistema sempre prevalece**: um campo restrito a um cargo não aparece para quem não o ocupa, e um campo numa tela que o usuário não pode ver nunca é exibido.
4. **Os campos aparecem na ficha do registro — em qualquer tela.** Feita a definição, os campos adicionais surgem numa seção **"Campos adicionais"** na ficha do próprio registro, em **qualquer tela de detalhe de registro do sistema** — dos cadastros (Parceiro, Produto, Centro de custo, Conta contábil, Tabela de preços, Funcionário, Depósito, …) às telas transacionais (Pedido de venda/compra, Cotação, Documento fiscal, Ordem de pagamento, Título, Processo jurídico, Orçamento, Bem patrimonial/imóvel, Oportunidade, Lead, …) — já preenchidos com o que foi salvo, e com o rótulo no idioma do usuário quando houver tradução. O operador informa os valores e clica em **Salvar** — a validação (tipo, obrigatoriedade, opção da lista) acontece no servidor, e o erro é mostrado no campo. Cada usuário vê só os campos que o acesso lhe concede. Nessas mesmas telas, o botão **Personalizar** deixa cada usuário **esconder ou recolher** seções (inclusive a de "Campos adicionais"), sempre respeitando o controle de acesso.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/tech-custom-fields-render.png" alt caption width="3200" height="2000"}
5. **Consulte e exporte por campo customizado.** Em **Administração → Relatório de campos customizados**, escolha a funcionalidade, informe filtros (campo + valor) e clique em **Consultar**: o sistema lista os registros que batem, com os valores dos campos que você pode ver. **Exportar CSV** baixa o resultado para planilha. Só entram na consulta os campos a que você tem acesso.
6. **Leve a configuração para outro ambiente ou órgão (exportar/importar definições de uma ou mais telas).** Na tela **Campos customizados**, o botão **Exportar** baixa um arquivo com as **definições** dos campos da tela selecionada (rótulos, tipos, opções, acesso e traduções) — **sem** os valores dos registros; o botão **Exportar tudo** gera um único arquivo com as definições de **todas as telas** de uma vez. Em outro ambiente (ex.: de homologação para produção) ou em outro órgão, o botão **Importar** envia esse arquivo e primeiro mostra uma **prévia** (nada é gravado ainda): o plano do que vai acontecer — quais telas seriam **criadas** ou **reaproveitadas** e quais campos seriam **criados** ou **atualizados**, além de quantas **regras de acesso** seriam ignoradas. Confira e clique em **Confirmar importação** para aplicar. A importação **recria** os campos de **todas as telas contidas no arquivo**, reaproveitando o que já existe (mesma tela / mesma chave são atualizados). As regras de acesso a um usuário ou cargo específico não são trazidas, porque os cadastros de destino são de outro ambiente; ajuste o acesso no destino, se necessário.

### Dicionário de dados (metamodelo do sistema)

Antes de criar um campo customizado, um layout de import/export ou um relatório, ajuda saber **quais entidades e campos** o sistema já tem. O **dicionário de dados** é a rotina própria da plataforma para essa consulta: lista as entidades do sistema (o metamodelo) e, ao abrir uma delas, os campos de cada uma, com **filtro por módulo** para achar rápido o domínio certo. É uma tela de **referência** — só consulta, não altera nada.

1. **Abra “Dicionário de dados”.** Menu **Administração → Dicionário de dados**. À esquerda, escolha o **Módulo** (ou *Todos os módulos*) e, se quiser, digite em **Buscar entidade**; a lista traz as entidades do módulo e, em cada linha, quantos campos ela tem. O contador no topo (ex.: *415 / 415 entidades*) mostra quantas entidades o filtro alcançou.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/e32-01-data-dictionary.png" alt caption width="3200" height="2000"}
2. **Inspecione uma entidade.** Clique numa entidade da lista para ver, no painel à direita, os **campos** dela (o nome e o tipo de cada atributo). Enquanto nenhuma entidade está selecionada, o painel mostra “Selecione uma entidade para inspecionar.”.

### Exigir no cadastro os campos que as declarações obrigatórias precisam

O SPED Fiscal descreve cada participante que apareceu numa nota do mês — nome, CNPJ ou CPF, inscrição estadual, município, rua, número, bairro. Faltando um desses, o **arquivo inteiro** é rejeitado, e a correção acontece no pior momento: no dia da entrega. Esta tela antecipa a cobrança para a **hora do cadastro**, e permite dizer **por causa de qual declaração** cada campo é exigido — porque isso muda de órgão para órgão e muda com a lei.

1. **Abra “Campos obrigatórios por declaração”.** Menu **Administração → Campos obrigatórios por declaração**. A tela é do perfil que responde pelas obrigações acessórias (o analista fiscal); exige a autorização *Gerenciar campos obrigatórios por declaração*.
2. **Parta do catálogo pronto.** O bloco **Exigências conhecidas das declarações** já traz os campos que os leiautes notoriamente exigem — os do registro 0150 do SPED (nome, CNPJ/CPF, inscrição estadual, logradouro, número, bairro, cidade) e os da NF-e/NFS-e (CEP, UF, e-mail). Clique em **Adicionar** na linha desejada: a exigência é criada **desligada**.
3.

**A tela *Produto* cobre os campos que o SPED pede do item** (registro 0200): **código (SKU)**, **descrição**, **unidade**, **NCM**, **CEST**, **código CATMAT/CATSER** e **natureza de estoque**. Use a condição **Somente quando → Tipo = Produto** nas exigências fiscais: um **serviço** não tem NCM, e uma regra sem essa condição tornaria impossível cadastrar qualquer serviço. Atenção a uma diferença em relação ao parceiro: o produto **já tem** exigências de fábrica que não se desligam aqui — NCM e unidade são obrigatórios para produto e matéria-prima, e o NCM é conferido contra o catálogo oficial. O que se configura nesta tela é o que vai **além** disso. A exigência vale também ao **duplicar** um produto.

**Ou monte a exigência à mão.** No bloco **Nova exigência**, escolha a **Declaração**, a **Tela** (*Parceiro*, *Endereço do parceiro* ou *Produto*), o **Campo exigido** e, se for o caso, a condição em **Somente quando** — por exemplo, exigir o CNPJ apenas quando o parceiro for **pessoa jurídica**. A observação é livre e serve para registrar o fundamento legal.

1. **Ative quando os cadastros estiverem prontos.** Toda exigência nasce **desligada**, de propósito: ligar uma regra retroativamente travaria a atualização de parceiros antigos que hoje passam. Use **Ativar** quando decidir cobrar. A partir daí, gravar um parceiro (ou um endereço) com aquele campo em branco é **recusado**, e a mensagem lista **todos** os campos faltantes de uma vez, dizendo quais declarações os exigem. A cobrança vale na tela, pela API e na importação — não só para quem digita no formulário.
2. **Desligue sem perder o histórico.** **Desativar** suspende a cobrança mantendo a regra cadastrada; **Excluir** remove de vez. Quem tem acesso à trilha de auditoria vê, no ícone de histórico da linha, quem ligou ou desligou cada exigência e quando.

### Decidir solicitações de aprovação (fila da autoridade aprovadora)

Certas mudanças exigem o aval de quem tem alçada: uma **despesa processual acima do teto de valor**, a **reversão de uma provisão** e a **alteração do valor de uma provisão** ([Jurídico e contencioso17 — Jurídico](docId\:DYpKNts8BU6LAG-ro0VgW)). Nesses casos o módulo **não aplica** a mudança: ele guarda uma solicitação, deixa o documento em "aguardando aprovação" e espera a decisão da autoridade. Esta é a tela onde essa decisão é tomada.

:::BlockQuote
**Não confunda com "Aprovações pendentes".** A caixa única de **Início → Aprovações pendentes** ([Extras15 — Extras](docId\:T4kPSRMFPloP-vHVEA9jU)) é um **índice**: cada linha leva você até a tela dona daquela decisão — venda, crédito, compras, orçamento —, e o botão de aprovar fica lá. As solicitações desta fila **não têm tela dona**: a decisão é da autoridade, não do documento, e por isso é tomada aqui mesmo. As duas telas existem e são coisas diferentes.
:::

1. **Abra a fila.** Menu **Início → Solicitações de aprovação** (logo abaixo de **Aprovações pendentes**). No topo, um aviso permanente repete a regra que mais engana: **aprovar aqui autoriza a mudança, não a aplica**.
2. **Leia o que está aguardando decisão.** A lista traz, por solicitação: o **Módulo** de origem (selo — ex.: *Jurídico*), a **Operação** em jogo (*Aprovação de despesa processual*, *Reversão de provisão*, *Alteração de valor de provisão*), a **Descrição**, o **Valor** envolvido, quem pediu (**Solicitado por**) e quando (**Solicitado em**). Módulo e operação aparecem por extenso, não em código interno.
3. **Decida.** Na linha, use a ação **Decidir**: abre o cartão **Decisão**, com o campo **Observação** (até 500 caracteres) e os botões **Aprovar**, **Recusar** e **Cancelar**. A observação fica gravada junto com a decisão — na prática ela é obrigatória ao recusar, para que quem pediu saiba o motivo.
4. **Confira o resultado.** Um aviso confirma a decisão (*Solicitação aprovada.* ou *Solicitação recusada.*), a lista é recarregada e a solicitação sai da fila. Quando não sobra nada esperando, a tela mostra **"Nada aguardando decisão."**.
5. **Volte ao documento de origem e refaça a ação.** Este passo é obrigatório e é onde a maioria erra: a aprovação apenas **autoriza**. Quem pediu precisa reabrir o documento (a despesa processual, a provisão) e executar a ação de novo — é nessa segunda execução que a mudança acontece. Se ninguém voltar, a solicitação consta **aprovada** e **nada aconteceu**.

:::BlockQuote
**Permissão exigida.** A fila é privativa de quem tem a autorização **Aprovar solicitações (alçada)** — cadastrada em **Início → Alçada** (passo 14). Quem não a tem **nem vê o item no menu**; entrando pela URL, a tela informa que somente uma autoridade aprovadora vê e decide estas solicitações, e **nem chega a consultar** a fila. O servidor ainda barra dois casos, mesmo com a permissão: **quem pediu não aprova** o próprio pedido (segregação de funções) e **valor acima do teto** da alçada do cargo é recusado. **Recusar**, esse sim, é permitido em qualquer valor — negar nunca cria risco.
:::

:::BlockQuote
**Fila negada não é fila vazia.** Se o servidor recusar a leitura, a tela mostra o **erro** com a opção de tentar de novo — nunca "Nada aguardando decisão.", que faria a autoridade ir embora tranquila com a fila cheia.
:::

:::BlockQuote
**O que a tela ainda não faz.** Ela mostra **só o pendente**: o que já foi aprovado ou recusado não é consultável aqui (a trilha da decisão fica na auditoria). E **nada avisa** que existe solicitação esperando há dias — enquanto não houver alerta, vale abrir a fila com regularidade, porque um documento parado em "aguardando aprovação" não reclama sozinho.
:::

### Exigir a linha orçamentária no pedido de compra

Por padrão, informar a linha orçamentária no pedido de compra é **opcional** — e essa é a razão de uma compra não prevista no orçamento conseguir passar: o controle de teto só age sobre o pedido que **menciona** uma linha. Quem não menciona nenhuma não é comparado com nada.

1. **Abra Início → Política de vínculo orçamentário do pedido.** A tela tem um único interruptor, **Exigir linha orçamentária em todo pedido de compra**, e ele nasce **desligado**. Enquanto estiver assim, o comportamento é o de sempre: pedido sem linha é gravado normalmente.
2. **Ligue o interruptor e clique em Salvar.** A partir daí, gravar os itens de um pedido que não informa a linha é **recusado**, e o comprador vê a mensagem pedindo a linha orçamentária. A mudança fica registrada na auditoria — quem ligou e quando.

:::BlockQuote
**Antes de ligar, saiba o que muda para o comprador.** A exigência vale para **todo** pedido, seja como for criado: direto, a partir de uma requisição ou de uma cotação julgada. Os dois fluxos guiados **ainda não trazem** a linha orçamentária, então, com a política ligada, o comprador passa a ter de escolher uma antes de conseguir gravar os itens — inclusive nos pedidos que ele antes gerava com um clique.
:::

:::BlockQuote
**Não confunda com o teto.** Esta política exige **informar** a linha. Se o valor **cabe** naquela linha é outra decisão, tomada pela política de controle da própria linha (bloquear, avisar ou exigir aprovação), configurada no orçamento. Ligar esta e esquecer aquela deixa o pedido preso a uma linha que ele pode estourar à vontade.
:::

:::BlockQuote
**Existe uma política irmã, e são independentes.** Em **Início → Política de vínculo orçamentário do pagável** vale a mesma ideia para o contas a pagar. São interruptores separados de propósito: é razoável exigir o empenho no momento do compromisso — o pedido — e deixá-lo opcional nos pagáveis que o sistema gera sozinho (multas, ordens de serviço da frota, frete), que ainda não carregam linha.
:::

### Definir o fluxo da cotação de compras

A sequência de etapas pela qual uma cotação passa — abertura, convite a fornecedores, coleta de propostas, critérios, julgamento, aprovação, publicação, geração do pedido — vem pronta e **vale para o órgão inteiro**. Quando o regimento interno da organização exige outra ordem, é aqui que ela é declarada.

1. **Abra Início → Fluxo da cotação de compras.** A tela mostra a **sequência em vigor** e diz de onde ela vem: **"Fluxo padrão"** enquanto a organização não declarou nenhuma, ou **"Declarada por esta organização"** depois que você salvar.
2. **Reordene com Subir e Descer**, e use **Remover** para tirar uma etapa que o seu rito não usa. A coluna **"Retornar exige justificativa"** decide, etapa por etapa, se voltar a um passo anterior a partir dela obriga a escrever o motivo.
3. **Clique em Salvar sequência.** A partir daí é essa a ordem que o sistema cobra. **Voltar ao fluxo padrão** desfaz a declaração e devolve a sequência de fábrica.

:::BlockQuote
**Reordenar NÃO afrouxa o fluxo — e isso é o ponto.** O avanço continua sendo de uma etapa por vez, e pular etapa continua sendo recusado. O que muda é **qual** é a sequência: a rigidez passa a valer sobre a ordem que você declarou. Se o objetivo for permitir saltos, esta tela não faz isso, de propósito.
:::

:::BlockQuote
**Etapa com cotação parada nela não sai.** O sistema recusa a remoção e diz **quantas** cotações estão ali. É deliberado: um documento parado numa etapa que a sequência nova não conhece responderia "transição inválida" a qualquer movimento, sem nada que explicasse o motivo — ele travaria. E, num certame, mudar o rito de um processo já em andamento tem peso jurídico. Termine ou cancele aquelas cotações antes de reorganizar.
:::

:::BlockQuote
**O cancelamento nunca entra na fila.** Ele é alcançável de qualquer etapa ativa e não é um passo do caminho — por isso a tela não o oferece como etapa da sequência.
:::

:::BlockQuote
**A sequência é do órgão, não da cotação.** Não há como dar a um processo específico um rito diferente dos demais, e isso é escolha de produto: fluxos por documento transformam um processo auditável em dezenas que ninguém consegue comparar.
:::

## Verificação

***

Você sabe que funcionou quando:

- Um novo usuário consegue entrar e vê apenas o que os papéis dele permitem.
- Um empregado com lotação vigente aparece com o cargo certo, e a requisição dele deriva o centro de custo dos autorizados.
- Uma delegação temporária vigente faz o substituto exercer a alçada do cargo no período; encerrada, a autoridade volta ao titular.
- Uma tentativa de operação acima do teto da alçada é **bloqueada** com mensagem clara ("sem autorização").
- Uma **faixa de aprovação de vendas** cadastrada faz uma venda dentro do intervalo (inadimplência ou desconto) ser **retida** e encaminhada ao **papel aprovador** definido, aparecendo em **Vendas → Aprovações**.
- Uma sessão encerrada não consegue mais chamar o sistema; acesso de IP fora das faixas cadastradas é recusado.
- A trilha de auditoria mostra as operações da sessão (criações e edições) com o antes/depois.
- O incidente de dados e o pedido de titular aparecem na lista **com o prazo** calculado.
- Um parceiro com consentimento revogado deixa de ser elegível para campanha naquele canal/finalidade.
- A exportação LGPD gera um arquivo legível com os dados completos do titular.
- Modelos e preferências de notificação salvam; e-mails com falha podem ser reprocessados.
- Um campo customizado criado numa funcionalidade aparece na lista daquela tela com o tipo e a obrigatoriedade certos; um campo de seleção sem opções é recusado, e a validação de tipo e obrigatoriedade acontece no servidor.
- Uma **regra automática de e-mail** ativa, ligada a um tipo de evento, faz a notificação sair pelos canais escolhidos aos destinatários resolvidos quando aquele evento ocorre (tela restrita ao administrador de plataforma).
- No **dicionário de dados**, filtrar por um módulo reduz a lista de entidades, e clicar numa entidade mostra os campos dela no painel — a tela carrega o metamodelo, sem ficar vazia.
- Uma solicitação submetida por um módulo aparece em **Início → Solicitações de aprovação** com módulo, operação, valor e solicitante; ao **Aprovar**, o aviso de confirmação surge, a linha sai da fila — e a mudança só se concretiza quando a ação é refeita no documento de origem.

## Erros comuns

***

- **Usuário criado, mas não aparece no ERP** — a sincronização com o provedor de identidade atrasou; aguarde alguns minutos e recarregue a lista.
- **A alçada parece não bloquear** — confira se a regra tem o teto correto e se o **cargo** da regra é o cargo do usuário (resolvido pela lotação primária vigente — telas "Cargos" e a lotação do empregado).
- **Empregado sem a alçada esperada** — verifique se ele tem **lotação primária vigente** (início ≤ hoje, sem fim) apontando o cargo certo; lotação com início futuro ainda não vale.
- **A requisição não deixa salvar o centro de custo** — o empregado solicitante precisa ter o centro na lista de **autorizados**; com mais de um, é preciso escolher qual usar.
- **A delegação não deixa salvar** — sem justificativa, período inválido, substituto inativo ou sobreposição com outra vigente do mesmo escopo são recusados.
- **Acesso recusado sem motivo aparente** — confira se o IP de origem está dentro de alguma **faixa de IP** cadastrada; com a lista preenchida, endereços fora dela são bloqueados.
- **A revogação de consentimento não bloqueou a campanha** — confira se a campanha foi montada **antes** da revogação; campanhas já disparadas têm a lista de destinatários fixada no momento do envio.
- **O e-mail não chegou ao destinatário** — confira "Falhas de envio de e-mail": destinatário inválido ou erro do provedor aparecem ali, com opção de reprocessar.
- **Aprovei a solicitação e nada mudou no documento** — é o comportamento esperado: aprovar **autoriza**, não executa. Volte ao documento de origem e refaça a ação; sem esse segundo passo a solicitação consta aprovada e a mudança não acontece.
- **"Solicitações de aprovação" não aparece no meu menu** — o item é exibido apenas para quem tem a autorização **Aprovar solicitações (alçada)**. Peça ao administrador uma regra dessa operação para o seu cargo (**Início → Alçada**).
- **Não consigo aprovar uma solicitação que eu mesmo pedi** — é a segregação de funções: quem submete não decide. A solicitação precisa de outra autoridade. Acima do teto da alçada do cargo a aprovação também é recusada — nesses casos, ou o valor sobe para o cargo-chefe pelo escalonamento, ou a solicitação é recusada (recusar é permitido em qualquer valor).


[title] Vendas e CRM
[path] Aplicações/ERP/Manual do Usuário/

# Vendas e CRM (lead → orçamento → pedido)

:::BlockQuote
Pré-requisitos: [Cadastros gerais (parceiros e produtos)](docId:6xpQsdWQ2NTyI40BFqDS-) (clientes + produtos), [Financeiro — cadastros de apoio](docId\:yTzjjyyML1B_60VgwDT09) (condições de pagamento + categorias de receita) e [Estoque](docId\:CVozhYtoHDtuWZyT-bnAT) (saldo disponível para reservar e faturar).
:::

## Introdução

***

Este módulo cobre toda a jornada comercial, do primeiro contato até o pedido fechado: você capta um **lead**, acompanha o negócio no **funil** (pipeline), monta o **orçamento** com desconto, passa pela ***alçada*** quando o desconto é alto, transforma o orçamento aprovado em **pedido de venda** e, por fim, fatura (a emissão da nota fiscal em si é feita no módulo Fiscal — [Fiscal — saída](docId\:jBJoVopyjL5-zOKm6FGbZ)). Em paralelo, o time comercial registra **atividades de CRM** (ligações, e-mails, visitas), segue **cadências** de follow-up e mede resultados por **metas de venda**.

O operador típico é o **vendedor** ou o **gestor comercial**. O vendedor usa o dia a dia (leads, orçamentos, atividades, agenda); o gestor configura as **etapas do funil**, define **metas** e é quem, com alçada, aprova descontos acima do limite. Todas as telas ficam no menu lateral **Vendas**, na ordem em que a venda acontece: Leads → Contatos → Orçamentos → Solicitações de cotação → Pedidos de venda, e mais abaixo Oportunidades → Pipeline kanban → Estágios do funil.

## Passo a passo

***

### Captar e qualificar um lead

1. **Abra "Leads".** Menu **Vendas → Leads**. A lista mostra cada lead com nome, documento (*CNPJ*/CPF), origem (WEBSITE, indicação, feira...) e a etapa de qualificação atual.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/081-leads.png" alt caption width="3200" height="2000"}
2. **Novo lead.** Clique em "Novo lead" (canto superior direito) e preencha\::inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/017-leads-detail.png" alt caption width="3200" height="2000"}
   - **Nome** — a razão social do interessado (ex.: Cliente Exemplo Ltda).
   - **Nome fantasia** — o nome comercial, se houver.
   - **Documento (CNPJ/CPF)** — ex.: 44555666000181.
   - **E-mail** e **Origem** — de onde veio o contato.
   - **Vendedor** — quem vai tocar a oportunidade.
3. **Qualifique.** Conforme o lead avança (você fala com ele, entende a necessidade), use a ação de qualificar/converter para movê-lo pelas etapas. Quando o lead vira negócio real, ele é **convertido** — nesse momento pode virar um cliente no cadastro e uma **oportunidade** no funil. O selo Convertido aparece na ficha e na lista.

### Contatos e solicitações de cotação

1. **Consulte os contatos.** Menu **Vendas → Contatos**. É a lista global das pessoas com quem o time comercial fala (compradores, decisores) — cada contato pode estar ligado a um cliente. Serve para o vendedor achar rapidamente o interlocutor certo.
2. **Veja as solicitações de cotação.** Menu **Vendas → Solicitações de cotação**. Quando um cliente pede um preço, a solicitação entra aqui — e já **nasce como um orçamento em rascunho** (ganha número ORC-… e aparece na lista com a situação Rascunho). O que a solicitação carrega é o **cliente**, a **validade** e uma **observação em texto livre**: o que ele quer chega escrito, não em itens. Por isso a coluna **O que foi pedido** aparece já na lista — é o único campo que diz *o quê*, e uma solicitação sem ele é uma linha que avisa que alguém quer algo e nunca diz o quê. O texto vem cortado no tamanho da coluna; passe o mouse para ler inteiro. Quem monta os itens é você, em **Orçamentos**, sem começar do zero — o documento e o cliente já estão lá.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/084-quote-requests.png" alt caption width="3200" height="2000"}
3. **Repare na coluna Origem.** Ela diz **de onde veio** cada solicitação, e a diferença muda o que você pode assumir. **Registro interno** é o caminho de sempre: alguém do time atendeu o cliente e transcreveu o pedido. **Portal do cliente** é uma solicitação que o próprio interessado enviou, sem ninguém do setor no meio — o que também significa que **ninguém conferiu o pedido antes de ele entrar**. Vale ler o texto com o mesmo cuidado que você teria ao telefone.O tratamento é o mesmo nos dois casos: **clique na linha** para abrir o orçamento — é o mesmo documento, com o número ORC-… que a lista mostra — e responda pelo caminho normal. É também na ficha do orçamento que fica o **Histórico de alterações**; a lista de solicitações não guarda histórico próprio, porque não é um segundo documento.Por trás do selo **Portal do cliente** existem **dois** caminhos, e vale saber qual é qual porque o que o interessado consegue fazer depois é diferente:
   - **Portal do município (canal do cidadão).** Qualquer pessoa identificada no portal do município (pelo gov.br) manda o pedido, e recebe de volta um **código de acompanhamento**. Com esse código ela vê **só a situação e as datas** — nunca solicitante, itens ou valores, porque o código não prova quem ela é. A proposta continua indo pelo e-mail de sempre. Quem **habilita** esse canal — a chave de aplicação e o grupo de acesso que carrega a operação — é o administrador, em *20 — Integração com sistemas externos*.
   - **Área do cliente (acesso nominal).** O cliente **entra** com um acesso que você concedeu, e aí ele tem uma área própria: vê as solicitações **dele**, acompanha a situação e **responde à proposta** — é o assunto dos próximos passos.

### Dar acesso ao cliente e receber a resposta dele

1.

⚠️ Convite é **acesso a dado de cliente**. Emitir para o e-mail ou telefone errado entrega a alguém a lista de solicitações de outra empresa. Confira o destinatário antes — é o mesmo cuidado de mandar uma proposta.

**Convide o representante.** Abra a ficha do cliente em **Cadastros → Parceiros** e use o bloco de **acesso ao portal**. Você gera um convite, e o código aparece **uma única vez** na tela — copie e entregue ao representante pelo canal que você já usa com ele. O sistema **não** mostra o código de novo depois: se ele se perder, revogue e emita outro. Cada convite serve **uma vez só**; depois de resgatado, ele fica registrado como usado, com quem resgatou e quando.

1.

:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/08-vendas-09-area-cliente-resgate.png" alt caption width="3200" height="2000"}Se o botão **não aparecer** e no lugar dele estiver escrito que o órgão ainda não configurou a entrada, é porque o provedor não foi definido na instalação — nesse caso o acesso continua possível pelo link do convite. Se a volta do provedor falhar, a pessoa retorna ao mesmo cartão com o aviso de que a entrada não se completou; o motivo técnico fica no log do servidor, nunca na tela, porque a mensagem do provedor costuma nomear a conta e a aplicação.Quem define o provedor (endereço de autorização, identificador da aplicação, endereço de retorno e — quando o próprio ERP conclui a entrada — o endereço de token) é quem administra a instalação; o passo a passo está em *20 — Integração com sistemas externos*.

⚠️ **Entrar não é o mesmo que ter acesso.** Identificar-se prova **quem a pessoa é**; não prova que ela representa aquele cliente. Quem entra sem ter resgatado convite vê **"Acesso ainda não vinculado"** e nenhuma solicitação — mesmo tendo entrado com sucesso. O convite do passo 7 continua sendo o que concede o acesso, e é isso que o cartão explica, com o atalho para digitar o código.

**Como o representante entra.** A área do cliente **não tem senha própria** — o ERP não guarda senha de ninguém. Quem identifica a pessoa é o provedor de identidade que o órgão já usa. Ao abrir a área sem estar identificado, ela vê o cartão **"Entre para ver as suas solicitações"** com um botão nomeado pelo provedor configurado — **"Entrar com gov.br"** onde o órgão usa o Login Único, **"Entrar com Keycloak"** onde usa o próprio servidor de identidade, e assim por diante. Clicando, é levada ao provedor; depois de se identificar, volta à área já reconhecida, e o topo passa a mostrar **"Conectado como \<nome>"**.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/08-vendas-08-area-cliente-entrada.png" alt caption width="3200" height="2000"}

1. **O que o cliente passa a ver.** Na área dele, o representante vê **apenas** as solicitações do cliente que ele representa — e nada mais do sistema. Ele consegue: abrir uma solicitação nova escrevendo o que precisa; acompanhar a situação de cada uma; e, quando você envia a proposta, **aceitar ou recusar** ali mesmo. Não há tela de cadastro, de estoque, de financeiro — a área é só isso.
2. **Envie a proposta e espere a resposta.** Monte os itens em **Orçamentos** (próximos passos) e use **Enviar**. A partir daí a proposta aparece na área do cliente como Enviado, com o prazo de validade, e os botões **Aceitar** e **Recusar** ficam disponíveis para ele. Quando ele responde, a situação do orçamento muda sozinha para Aprovado ou Recusado — você não transcreve nada.
3.

⚠️ **Proposta vencida não se aceita.** Passada a data em **Válido até**, a resposta do cliente é recusada e o orçamento passa a constar como **Vencido** — inclusive na tela dele, para que ninguém fique esperando resposta de um documento morto. Se o cliente demorou e você ainda quer vender, gere um orçamento novo com prazo novo; não existe "reabrir". Vale igual para você: a tela interna também recusa aprovar orçamento fora do prazo.

**Confira quem respondeu.** No **Histórico de alterações** da ficha do orçamento fica registrado quem aceitou (ou recusou), quando, e que a resposta veio **da área do cliente** — e não de alguém do setor aprovando em nome dele. São fatos diferentes, e é essa linha que responde à pergunta do controle interno meses depois.

### Montar o orçamento

1. **Abra "Orçamentos".** Menu **Vendas → Orçamentos**. Clique em "Novo orçamento" (ou abra um existente para editar).
2. **Preencha o cabeçalho.** Escolha o **Cliente**, a **Tabela de preço** (opcional — o preço sugerido dos itens vem dela), a data em **Válido até** e uma **Observação** livre, se precisar. No topo o sistema mostra a **Posição do cliente** (pedidos anteriores, total já comprado e situação de ***crédito***: OK significa liberado).



![](https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/019-sales-quotes-detail.png)

1.

💡 **Ache o produto pelo código de barras.** Na busca do seletor de produto você pode **digitar, colar ou ler com um leitor** o código de barras (GTIN/EAN) cadastrado no produto — ele vem no **topo da lista**, com o código ao lado do nome para você conferir. Um leitor USB funciona direto (ele se comporta como teclado, e o Enter dele confirma a escolha assim que o resultado do código aparece). Código não cadastrado não trava nada: a busca por nome ou SKU continua como antes. O mesmo seletor — e portanto o mesmo recurso — aparece no pedido de compra e na requisição de material.

**Adicione os itens.** Para cada linha escolha o **produto** (selecione na lista, não apenas digite), a **quantidade** e o **preço unitário**. O preço sugerido pode ser ajustado. Se quiser dar um abatimento, informe o **desconto** — ele é em **porcentagem** (digite 30 para 30%).

1. **Salve.** O orçamento fica com o status Enviado (ou Em edição, conforme a etapa). O total é recalculado com os itens e o desconto. Não é possível **enviar um orçamento sem itens** (é rejeitado), e depois de **aprovado** o orçamento fica **travado para edição** — para mudar algo, gere uma nova versão.

:::BlockQuote
💡 O bloco **Apoio à venda** (abas Sugestões / Saldo) ajuda o vendedor: mostra o histórico de compra do cliente e o saldo em estoque dos produtos do orçamento, para não prometer o que não há. Nesta etapa o saldo é **apenas consultivo** — a reserva de estoque só acontece no pedido de venda.
:::

:::BlockQuote
⚠️ **Orçamento não se apaga, cancela-se.** O orçamento é um documento com ciclo de vida: a tela oferece **Cancelar**, não excluir. Cancelar encerra o documento por transição de status, preservando o histórico — nada é apagado.
:::

### Aprovação por alçada (desconto alto)

1. **Quando o desconto passa do limite, o orçamento é retido.** Se você concedeu um desconto acima da sua ***alçada*** de vendedor (ou o cliente está no limite de crédito), ao tentar aprovar/fechar o sistema **segura** o orçamento e ele não avança sozinho. É a mesma lógica de alçada de compras e financeiro: quem tem teto maior precisa liberar.
2. **O gestor aprova em "Aprovações".** Menu **Vendas → Aprovações**. A lista mostra cada documento retido, o **motivo** (Desconto, Crédito, Inadimplência), o **valor** e três ações: **Aprovar**, **Aprovar parcial** (libera até um valor/desconto menor, informado no campo) ou **Rejeitar** (com o motivo da rejeição). Ao aprovar, o orçamento volta a fluir.



![](https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/103-sales-approvals.png)

1. **Confirme a liberação no orçamento.** Voltando à ficha do orçamento, o botão **"Aprovar e gerar pedido"** cria o pedido de venda diretamente a partir do orçamento aprovado.

### Fechar o pedido de venda

1. **Abra "Pedidos de venda".** Menu **Vendas → Pedidos de venda**. A lista traz número (ex.: PV-000001), cliente, data de entrega e **situação** (Aberto, Faturado...). Use "Novo pedido" para criar do zero, ou chegue aqui pelo botão "Aprovar e gerar pedido" do orçamento.



![](https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/085-sales-orders.png)

1. **Confira o pedido.** Na ficha, revise os **itens** (produto escolhido, quantidade e preço) e indique o **almoxarifado de origem** — de onde o estoque vai sair. Ao confirmar, o pedido fica Aberto e o **estoque é reservado** para aquele cliente, impedindo venda dupla do mesmo saldo: a reserva aparece em **Estoque → Reservas de estoque** e é abatida do saldo disponível para os demais pedidos. Ela é liberada quando o pedido é **cancelado** ou quando é **totalmente faturado** (aí a própria saída já baixou o saldo). Só um **orçamento aprovado** pode virar pedido pela conversão — o sistema recusa converter orçamento ainda não aprovado.

:::BlockQuote
⚠️ **A reserva depende do almoxarifado.** Uma reserva pertence a um lugar: pedido salvo **sem** almoxarifado de origem fica aberto normalmente, mas **não segura estoque nenhum** — o saldo continua disponível para outro cliente. Preencha o almoxarifado antes de prometer prazo.
:::



![](https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/020-sales-orders-detail.png)

:::BlockQuote
💡 O produto tem que estar **escolhido** no item (não só digitado por texto) — é o vínculo com o produto que faz o estoque baixar no faturamento.
:::

:::BlockQuote
⚠️ **Pedido também não se apaga: cancela-se.** Se o negócio caiu, use **Cancelar** — o pedido passa de Aberto para Cancelado e a **reserva de estoque é liberada** de volta ao saldo livre. O documento permanece no histórico; não há exclusão.
:::

:::BlockQuote
⚠️ **Isso vale para o documento, não para as linhas.** Salvar os itens **substitui** a lista inteira: se você salvar sem nenhuma linha, todas somem, e o sistema aceita — porque esvaziar um pedido é uma operação legítima, não um acidente que se deva barrar. Não há confirmação e não há desfazer. O que existe é registro: o bloco **Histórico de alterações**, no fim da ficha, guarda quantas linhas havia antes, quanto somavam, e quem fez a troca. É lá que se responde "o pedido tinha doze itens, o que aconteceu?" — a lista de pedidos não conta essa história.
:::

:::BlockQuote
💡 **Salvar cinza não é falta de permissão.** Enquanto os itens do pedido estão carregando, o botão fica desabilitado de propósito: um clique nesse instante enviaria uma lista vazia e apagaria tudo. Se a carga falhar, a tela mostra o erro e um botão de tentar de novo, em vez de fingir que o pedido não tem itens.
:::

:::BlockQuote
💡 **Bloquear o cliente a prazo sem perder a venda à vista.** A ficha do cliente na tela **Crédito do cliente** tem, ao lado de **Bloqueio manual** e **Venda bloqueada**, o campo **"Bloqueio alcança"**, com duas opções: **Toda venda** e **Somente vendas a prazo**. Com **Toda venda** — o padrão, e o comportamento de sempre — o cliente travado não fecha pedido nenhum. Com **Somente vendas a prazo**, o mesmo cliente **continua comprando à vista**: o dinheiro entra antes de a mercadoria sair, então essa venda não carrega o risco que a trava existe para conter.**O que o sistema considera "à vista" é o prazo da tabela de preço do documento** — a mesma origem que já decide a alçada por condição de pagamento. Prazo **zero** é à vista; qualquer prazo maior é a prazo. E um pedido **sem tabela de preço** tem prazo **desconhecido**, o que conta como a prazo e continua sendo barrado — de propósito: quem não sabe a condição não deve poder afrouxar um bloqueio por omissão.Na prática, para liberar a venda à vista de um cliente travado: cadastre (ou aponte) uma **tabela de preço com prazo 0**, use-a no pedido, e deixe a ficha do cliente em **Somente vendas a prazo**. Sem os dois lados o pedido continua retido. ⚠️ **Pedido avulso barrado por crédito? Aprove e reenvie a ação.** Um pedido criado direto (**Novo pedido**, sem partir de um orçamento) passa pela mesma checagem de crédito na tela de itens: se o cliente estiver **no limite de crédito** ou **inadimplente**, ao confirmar o pedido o sistema o **retém** em vez de abri-lo — igual ao orçamento bloqueado. A liberação segue a mesma lógica: quem tem alçada aprova em **Vendas → Aprovações** (motivo Crédito ou Inadimplência), o bloqueio é removido e o pedido **volta a fluir**. De volta à ficha, **reenvie a confirmação** — o pedido então passa a Aberto e reserva o estoque.
:::

### Faturar (handoff para o Fiscal)

1. **Fature o pedido.** A partir do pedido Aberto, a ação de faturar leva ao módulo **Fiscal**, na tela de documentos fiscais. Lá você escolhe a **categoria do recebível**, confere os dados fiscais (CFOP, NCM, tributos) e emite a ***NF-e***. O passo a passo completo da emissão está na página [Fiscal — saída](docId\:jBJoVopyjL5-zOKm6FGbZ). Ao faturar, o pedido passa a Faturado, o **estoque baixa**, é criada a **conta a receber** e o lançamento contábil é gerado.

### Funil, oportunidades e etapas

1. **Configure as etapas do funil.** Menu **Vendas → Estágios do funil**. Cada etapa tem **código**, **nome**, **ordem**, **probabilidade %** (peso para o forecast), **desfecho** (Em aberto, Ganho, Perdido) e um alerta de **estagnação** (dias sem mexer). Marque **Ativo** para a etapa aparecer em novas oportunidades.



![](https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/022-pipeline-stages-detail.png)

1. **Acompanhe as oportunidades.** Menu **Vendas → Oportunidades**. Cada oportunidade tem **cliente**, **título**, **valor estimado**, **probabilidade**, **vendedor**, **fechamento previsto** e a **etapa** atual. **Título** e **cliente** são obrigatórios, e a **probabilidade** só aceita valores entre **0 e 100** — fora disso o sistema recusa. Você também pode anexar documentos à oportunidade. Uma oportunidade cujo prazo de fechamento vence é **reaberta automaticamente**.



![](https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/018-opportunities-detail.png)

1. **Use o pipeline kanban.** Menu **Vendas → Pipeline kanban**. As oportunidades aparecem em colunas por etapa (Lead, Qualificado, Proposta, Ganho, Perdido), cada coluna somando quantidade e valor. **Arraste** um cartão para mover o negócio de etapa; oportunidades paradas há muito tempo ficam sinalizadas como estagnadas.



![](https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/095-sales-pipeline.png)

1. **Leia o funil, o forecast e defina metas.** Menu **Vendas → Funil e metas**. A tela mostra as **métricas por etapa** (quantidade, total, ticket médio e valor **ponderado** pela probabilidade), o **forecast por mês** de fechamento previsto e um formulário de **Nova meta** (período, vendedor, etapa, região e valor da meta). As metas cadastradas também aparecem em **Metas de venda**.



![](https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/097-sales-funnel.png)

### Atividades, agenda e cadências

1. **Registre atividades de CRM.** Menu **Vendas → Atividades de CRM**. Use o painel **Nova atividade** para anotar cada interação com o cliente (ligação, e-mail, reunião, visita) e agendar follow-ups. Fica tudo no histórico do lead/oportunidade. No ambiente de demonstração as listas **Atividades** e **Contatos a contactar** aparecem vazias até você registrar a primeira atividade.



![](https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/099-crm-activities.png)

1. **Veja sua agenda.** Menu **Vendas → Minha agenda**. Aqui você gera um URL de assinatura para acompanhar suas atividades de CRM no Google Calendar ou no Outlook, sem perder um retorno prometido. No ambiente de demonstração o URL ainda não existe: clique em **Gerar URL** para criá-lo.



![](https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/100-calendar-feed.png)

1. **Siga uma cadência.** Menu **Vendas → Cadências**. Uma cadência é uma sequência pré-definida de contatos (dia 1 ligar, dia 3 e-mail, dia 7 WhatsApp...). Ela guia o vendedor no ritmo certo de follow-up.



![](https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/101-sales-cadences.png)

1. **Use modelos de WhatsApp.** Menu **Vendas → WhatsApp**. Modelos de mensagem prontos para envio ao cliente, mantendo o padrão de comunicação do time.



![](https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/102-whatsapp-templates.png)

### Enviar o orçamento por e-mail ao cliente

1. **Envie o orçamento.** Na ficha ou na lista de **Orçamentos**, use a ação **Enviar**. Além de mudar o status para Enviado, o sistema dispara automaticamente um e-mail ao contato do cliente com a proposta — você não precisa redigir a mensagem à mão.
2. **Confira o destinatário.** O e-mail segue para o endereço do contato cadastrado no parceiro. Se o cliente não tiver contato com e-mail, o envio é ignorado e apenas registrado no log; cadastre o contato em *02 — Cadastros gerais* e reenvie.

### Brindes e bonificações no orçamento

Brindes e bonificações seguem **regras parametrizáveis** do tipo "compre X, ganhe Y", mantidas pela administração (menu **Administração → Regras de bonificação**).

1. **Cadastre a regra.** Informe o produto que dá direito ao brinde, a quantidade mínima, o produto bonificado e a quantidade concedida.
2. **Monte o orçamento normalmente.** Ao adicionar os itens que se enquadram na regra, o sistema registra o **brinde/bonificação** correspondente no orçamento, conforme a regra vigente.
3. **Confira o total.** O item bonificado entra com a condição definida na regra (por exemplo, sem valor), preservando o registro do que foi concedido.

### Positivação do orçamento

A **positivação** acompanha o desfecho comercial de cada orçamento — quantos viraram negócio e quantos se perderam.

1. **Abra a ficha do orçamento.** No bloco **Positivação**, escolha o desfecho atual: Ganho, Perdido, Pendente ou Em negociação.
2. **Registre a evolução.** Atualize o desfecho conforme a negociação avança; o valor fica visível como "Atual" na própria ficha.
3. **Acompanhe os resultados.** Os desfechos alimentam a leitura de conversão da carteira, complementando o funil e as metas de venda.

### E-mail de confirmação do pedido

1. **Confirme o pedido de venda.** Ao confirmar o pedido (situação Aberto), o sistema envia automaticamente um e-mail de confirmação ao contato do cliente, com os dados do pedido.
2. **Sem e-mail cadastrado, sem envio.** Se o parceiro não tiver um contato com e-mail, a confirmação é apenas registrada e o envio é ignorado — cadastre o e-mail do contato em *02 — Cadastros gerais*.

### Brindes e bonificações no pedido

1. **Converta ou crie o pedido.** As mesmas **regras parametrizáveis** de brindes e bonificações ("compre X, ganhe Y") descritas no orçamento valem para o pedido de venda.
2. **O pedido registra a bonificação.** Ao incluir os itens que atendem à regra, o pedido passa a registrar o brinde/bonificação concedido, mantendo o histórico do que foi entregue como cortesia.

### Programação de entregas e liberações parciais

Quando o pedido é atendido em etapas (o cliente recebe em lotes), use a **programação de entregas** no próprio pedido.

1. **Abra a ficha do pedido.** No card **Programação de entregas**, cadastre cada liberação parcial com a **data prevista** e os itens/quantidades do lote.
2. **Controle o status de cada lote.** Cada liberação evolui de Planejada para Liberada (ou Cancelada), permitindo acompanhar o atendimento parcial.
3. **Fature por etapa.** À medida que os lotes são liberados e faturados, o pedido reflete a situação Parcialmente faturado até a conclusão.

### Perfis de relacionamento

Além do cadastro individual, o time pode agrupar clientes, leads e contatos em **perfis de relacionamento** (por exemplo: cliente-chave, prospect, em risco), usados para segmentar cadências e comunicação.

1. **Abra os perfis.** Menu **Vendas → Contatos e perfis**, na área de perfis.
2. **Crie um perfil.** Informe o **nome** e a **aplicabilidade** — se ele vale para **clientes**, **leads**, **contatos** ou **todos**.
3. **Use o perfil.** Ao cadastrar um contato, associe-o ao perfil; as cadências podem ser configuradas para se aplicar a um perfil específico.

### Classificação dos contatos

Cada interação registrada em **Atividades de CRM** pode ser marcada com uma **classificação** definida pela sua organização — um catálogo mantido pelo time (por exemplo Cliente-chave, Prospect, Em risco).

1. **Mantenha o catálogo.** As classificações disponíveis são parametrizáveis: a organização cadastra os códigos e rótulos que fazem sentido para o seu processo.
2. **Classifique a atividade.** No formulário **Nova atividade** (menu **Vendas → Atividades de CRM**), escolha a **Classificação** no campo próprio ao registrar o contato.
3. **Segmente depois.** Como a classificação segue uma estrutura pré-definida, ela permite filtrar e agrupar os contatos de forma consistente.

### Suspensão e cancelamento automático de pedidos parados

O sistema acompanha os pedidos **em aberto** (ainda não faturados) e, depois de um tempo **sem atendimento**, os **suspende** automaticamente; se continuarem parados por mais tempo, os **cancela** — liberando as reservas de estoque. É uma escalada em dois estágios.

1. **Parametrize os prazos.** Na **política de pedidos de venda** (parâmetros de suspensão e cancelamento), informe em quantos dias um pedido parado deve ser **suspenso** e, num prazo maior, **cancelado**. Os dois prazos são configuráveis por organização.
2. **O prazo conta a partir da data do pedido.** O relógio é a **data do pedido** — sempre preenchida —, e **não** a data prevista de entrega (que é opcional). Assim, um pedido criado **sem** data prevista de entrega também é alcançado pela suspensão/cancelamento; nenhum pedido fica de fora por causa de um campo em branco.
3. **A suspensão fica visível.** Um pedido suspenso continua com a situação Aberto, mas ganha o selo **Suspenso** na **lista de pedidos** e na **ficha do pedido**, para o time perceber que ele parou e agir (retomar ou deixar cancelar no prazo maior).

## Verificação

***

Você sabe que funcionou quando:

- O **lead** cadastrado aparece na lista de Leads e, depois de qualificado, muda de etapa (e ganha o selo Convertido quando vira negócio).
- O **orçamento** fica salvo com os itens, o desconto aplicado e o total recalculado.
- Um orçamento com **desconto acima da alçada não fecha sozinho**: ele aparece em **Vendas → Aprovações** com o motivo Desconto e só avança depois que alguém com alçada clica em "Aprovar".
- O **pedido** aprovado fica Aberto e a reserva de estoque aparece no relatório de estoque (saldo livre = saldo total − reservado).
- No **pipeline kanban**, o cartão da oportunidade está na coluna certa e o **funil** mostra o forecast ponderado somando aquele valor.
- Após faturar ([Fiscal — saída](docId\:jBJoVopyjL5-zOKm6FGbZ)): o pedido vira Faturado, a *NF-e* aparece em *09 — Fiscal – saída*, o estoque do produto cai e a conta a receber é criada na página [Financeiro — títulos (contas a pagar e a receber)](docId\:D4kuGidayU2GQ-hMhF_T-).
- Um pedido parado além do prazo de suspensão ganha o selo **Suspenso** na lista e na ficha (continuando Aberto); passado o prazo maior, ele é **cancelado** automaticamente e a reserva de estoque é liberada.

## Erros comuns

***

- **Orçamento "preso" sem avançar** — quase sempre é **alçada**: o desconto passou do seu limite (ou o cliente está no limite de crédito). Peça a quem tem alçada para liberar em **Vendas → Aprovações**, ou reduza o desconto.
- **Estoque não baixa no faturamento** — o item foi digitado por texto em vez de **selecionar o produto** na lista. Volte ao pedido e escolha o produto de fato no item.
- **STOCK\_INSUFFICIENT ao faturar** — você tentou faturar mais do que há em estoque. Confira se há recebimento de compra pendente ([Compras](docId:3mdo_BH5DDXIp3VIh4ATK)) ou faça um ajuste no estoque ([Estoque](docId\:CVozhYtoHDtuWZyT-bnAT)).
- **Cliente bloqueado / crédito vencido** — o bloco "Posição do cliente" mostra o crédito diferente de OK. Resolva no cadastro do parceiro ([Cadastros gerais (parceiros e produtos)](docId:6xpQsdWQ2NTyI40BFqDS-)) ou no financeiro antes de fechar a venda. A checagem de crédito e a **inadimplência** (cliente com título vencido há muitos dias) também geram **aprovação pendente** em **Vendas → Aprovações**.
- **"Não acho o botão de excluir" no orçamento/pedido** — não existe. Orçamentos e pedidos são documentos com ciclo de vida: você **cancela** (transição de status), não apaga. Cancelar preserva o histórico e, no caso do pedido, libera a reserva de estoque. **As linhas são outra história:** salvar os itens substitui a lista toda, e salvar sem nenhuma linha esvazia o pedido — é aceito de propósito, e fica registrado no bloco **Histórico de alterações** da ficha.
- **"O pedido perdeu os itens e ninguém sabe explicar"** — abra o **Histórico de alterações** no fim da ficha do pedido e clique no evento. Ele mostra quantas linhas havia antes e depois, o total de cada lado e quem fez. Cobre a troca de itens, o cancelamento e também a **alteração do cabeçalho** — trocar o cliente, a data de entrega, o almoxarifado ou a observação gera um evento próprio, com o valor antigo e o novo lado a lado.
- **Não consigo converter o orçamento em pedido** — só orçamento **aprovado** converte. Se ainda está Enviado/Em edição (ou preso na alçada), aprove primeiro em **Vendas → Aprovações**.
- **"O cliente diz que aceitou, mas o sistema recusou"** — confira a data em **Válido até**. Passado o prazo, a resposta é recusada e o orçamento fica Vencido; não há como reabrir. Gere um orçamento novo, com prazo novo. Vale para os dois lados: você também não consegue aprovar pela tela interna um orçamento fora do prazo.
- **"O cliente não consegue entrar na área dele"** — o convite pode já ter sido usado (serve **uma vez só**), revogado, ou nunca ter sido resgatado. Emita outro na ficha do parceiro. Se ele entra mas vê a mensagem de acesso não vinculado, é porque autenticou sem ter resgatado convite algum — mande o código.
- **"Enviei a proposta e o cliente não foi avisado"** — hoje ele descobre **entrando** na área dele; não há aviso automático ao representante externo. Avise pelo canal de sempre até que esse envio exista.


[title] Patrimônio
[path] Aplicações/ERP/Manual do Usuário/

# Patrimônio (ativo imobilizado)

:::BlockQuote
Pré-requisitos: [Cadastro fiscal próprio](docId\:Q-zx6Qk4pMFD09yrhmsve) (empresa e estabelecimentos) e [Contabilidade](docId:08cbTyrT0WXBp4ymvrog_) (plano de contas, para as contas PCASP das classes de bens).
:::

## Introdução

***

O módulo de Patrimônio acompanha o ciclo de vida de cada bem do ativo imobilizado — do berço ao túmulo. Você **incorpora** o bem (tombamento individual, com número de patrimônio próprio), ele **deprecia** mês a mês pelo fechamento contábil, pode ser **transferido**, **reavaliado** ou **baixado** ao longo da vida, e é conferido periodicamente pelo **inventário físico** (o que existe fisicamente × o que está registrado). O módulo cobre bens móveis (veículos, móveis, equipamentos) e bens imóveis (terrenos e edificações), sempre com a contabilização automática no plano de contas público (PCASP) e a trilha de auditoria que o órgão de controle exige.

Você usa esta área sempre que um bem novo chega (compra, doação), quando vira o mês e é hora de lançar a depreciação, quando um bem muda de responsável ou local, quando o valor de um bem precisa ser corrigido, e quando a comissão de inventário sai a campo para o levantamento anual. O registro individualizado de cada bem atende à *Lei 4.320/64 art. 94* (registro analítico individualizado dos bens móveis e imóveis).

## Passo a passo

***

### Cadastrar classes de bens

Antes de tombar qualquer bem, defina as **classes** — os grupos que carregam a vida útil e as contas contábeis. É a classe que decide como o bem deprecia e onde ele bate na contabilidade.

1. **Abra a lista de classes.** Menu **Patrimônio → Classes de bens**. Você vê os grupos já cadastrados (ex.: Veículos, Móveis, Equipamentos de informática) com a vida útil e as contas de cada um.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/04-asset-classes-list.png" alt caption width="3200" height="2000"}
2.

**A classe é dado de referência — não se exclui.** Como os bens ficam vinculados a ela, uma classe não pode ser apagada; ela é **desativada** (fica inativa) e some das opções para novos bens, mas os bens já tombados naquela classe continuam válidos. A **vida útil** tem que ser maior que zero (informar zero é barrado como campo inválido), e as contas contábeis são obrigatórias.

**Abra ou crie uma classe.** Na classe você define\::inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/05-asset-class-detail.png" alt caption width="3200" height="2000"}

:::Paragraph{listStyleType="disc" indent="2"}
**Vida útil** (em meses ou anos) e **valor residual** (percentual que sobra ao fim da vida útil).
:::

:::Paragraph{listStyleType="disc" indent="2"}
**Método de depreciação** (ex.: linear/quotas constantes).
:::

:::Paragraph{listStyleType="disc" indent="2"}
As **contas PCASP**: a conta do imobilizado, a de depreciação acumulada e a de despesa/contrapartida. É por elas que o fechamento mensal gera o *lançamento contábil*.
:::

### Incorporar um bem (tombamento)

Com as classes prontas, você tomba o bem — dá a ele um número de patrimônio e registra de quem é a carga.

1. **Abra a lista de bens.** Menu **Patrimônio → Bens patrimoniais**. A lista mostra cada bem com o número de tombamento, a descrição, a classe, o valor e a situação.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/01-assets-list.png" alt caption width="3200" height="2000"}
2.

É assim que a norma manda tratar (MCASP / NBC TSP): reconhece-se o bem na posição em que ele está, sem reescrever as competências já encerradas. Antes disso todo bem entrava zerado, e o balanço subavaliava a depreciação acumulada enquanto bens de vida útil vencida ainda apareciam com valor líquido.

**Bem que já estava em uso entra com a depreciação que carrega.** Ao tombar um bem cuja data de entrada em uso é anterior — regularização patrimonial, inventário, bem recebido de exercício passado —, o sistema abre a posição dele na **data do reconhecimento**: calcula quantos meses já correram entre o início da depreciação e a data de contabilização, limitado à vida útil, e grava a depreciação acumulada correspondente. Você pode informar a posição de abertura à mão (**depreciação acumulada** e **meses decorridos**) quando o inventário físico souber o número melhor que o calendário; nesse caso o que você informou prevalece. Bem que entrou em uso neste mês continua abrindo em zero.

**Clique em "Novo".** Preencha o formulário de incorporação:

:::Paragraph{listStyleType="disc" indent="2"}
**Descrição** do bem e **classe** (que traz a vida útil e as contas).
:::

:::Paragraph{listStyleType="disc" indent="2"}
**Valor de aquisição** (ex.: R$ 1.250,00) e **data de entrada**.
:::

:::Paragraph{listStyleType="disc" indent="2"}
**Estabelecimento** e **responsável pela carga** — quem responde pelo bem.
:::

:::Paragraph{listStyleType="disc" indent="2"}
Documento de origem (nota de compra, termo de doação), quando houver.
:::

1.

**Por que mês seguinte?** A regra contábil pública manda começar a depreciar no mês posterior à colocação em uso. Um bem que entra em 20 de maio começa a depreciar em 1º de junho.

**Salve.** O sistema gera o número de tombamento e o bem passa a constar na lista. A depreciação já fica programada para começar no **primeiro dia do mês seguinte** à entrada — não no dia da incorporação.

### Consultar a ficha e o histórico de depreciação

1. **Abra o bem.** Na lista, clique no bem desejado. A ficha reúne os dados de aquisição, a classe, o responsável e a situação atual.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/02-asset-detail-QAPAT-000001.png" alt caption width="3200" height="2000"}
2.

As cotas mensais só aparecem **depois** que o fechamento do mês correspondente rodou (próximo passo).

**Leia o histórico de depreciação.** Na própria ficha há o quadro mês a mês: a cota do mês, a depreciação acumulada e o valor líquido (valor de aquisição menos depreciação acumulada). Junto aparece a trilha de auditoria — quem criou, quem alterou, com o antes e o depois de cada campo.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/03-asset-detail-history.png" alt caption width="3200" height="2000"}

### Fechamento mensal / rodar a depreciação

1. **Abra o fechamento.** Menu **Patrimônio → Fechamento mensal**. Escolha o mês (ex.: maio/2026).:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/06-asset-closing.png" alt caption width="3200" height="2000"}
2.

**Este é o fechamento dos bens móveis.** Os bens imóveis (edificações) têm fechamento próprio, em **Patrimônio → Fechamento de imóveis** — veja a seção **"Fechamento e depreciação mensal de bens imóveis"**, mais adiante. Fechar um **não** fecha o outro: são duas rodadas independentes e as duas precisam ser executadas todo mês.

Quando o aviso aparecer, confira nos bens: **situação de depreciação** (precisam estar prontos para depreciar), **método** e **vida útil**. É quase sempre cadastro pela metade, não mês sem movimento. Vale o mesmo espírito do aviso equivalente no fechamento de imóveis, mais adiante.

⚠️ **Mês sem nada a depreciar é recusado, e isso é proteção.** Se nenhum bem entra no cálculo, o sistema **não fecha** a competência: avisa que não há o que depreciar, em vez de gravar uma rodada zerada. O motivo é o bloqueio acima — uma rodada vazia ocuparia a competência, e ela não poderia ser nem contabilizada (não há lançamento) nem refeita (o mês já constaria como rodado). O mês ficaria queimado sem que nada tivesse sido depreciado.

O mês fechado bloqueia recontagem: a depreciação daquele período não é recalculada, só o mês seguinte segue o ciclo.

**Se o fechamento não passar, a mensagem diz o que corrigir.** Quando algum lançamento falha, o sistema desfaz o fechamento inteiro (mês pela metade seria pior) e informa **quantos de quantos** falharam e a **causa agrupada por classe e conta** — por exemplo, class QAPAT-CLS1 (accumulated=1.2.1.9). Corrija as contas PCASP daquela classe do bem e feche o mês de novo. A mensagem agrupa pela **correção**, não pelo volume: dezenas de bens barrados costumam virar duas ou três classes mal configuradas.

**Confirme o fechamento.** O sistema calcula a cota de depreciação de cada bem ativo, fecha o mês e gera o lançamento contábil de cada bem no PCASP (com débito igual a crédito). Terrenos, que não depreciam, ficam de fora do cálculo.

### Transferir um bem

1. **Abra as transferências.** Menu **Patrimônio → Transferências de bens**. Aqui você move um bem de responsável, estabelecimento ou local, e acompanha a fila de aceite e o histórico de movimentações.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/07-asset-movements.png" alt caption width="3200" height="2000"}
2. **Registre a transferência.** Informe o bem, o destino (novo responsável/local) e o motivo. A transferência entra numa **fila de aceite**: o novo responsável confirma o recebimento (aceite eletrônico), fechando o termo de carga. Enquanto não aceita, a movimentação fica pendente.

### Reavaliação, impairment e baixa

Estas ações partem da própria ficha do bem (menu **Patrimônio → Bens patrimoniais → abrir o bem**).

1.

A reversão de um impairment tem **teto**: não pode devolver mais do que a perda originalmente reconhecida.

**Reavaliação ou impairment.** Quando o valor de um bem mudou, você o corrige na ficha:

:::Paragraph{listStyleType="disc" indent="2"}
**Reavaliação** — ajusta o bem ao valor justo, a maior ou a menor. O sistema lança o ajuste na contabilidade (reserva de reavaliação quando o valor sobe).
:::

:::Paragraph{listStyleType="disc" indent="2"}
**Impairment** (redução ao valor recuperável) — reconhece uma perda quando o bem vale menos do que o registrado. Lança a perda na contabilidade.
:::

1. **Baixa / desfazimento.** Ao dar baixa, informe a classificação e a modalidade de desfazimento (venda, doação, inservível, etc.). O sistema muda o bem para **baixado**, faz o desreconhecimento contábil (zera depreciação acumulada e impairment contra o valor bruto) e o bem some das operações ativas — não dá mais para transferir nem depreciar. O lançamento de baixa fica balanceado (débito igual a crédito) e visível no histórico da ficha.

### Inventário físico de bens móveis

O inventário confronta o que existe fisicamente com o que está registrado, conforme a Lei 4.320/64 art. 96.

1. **Abra os inventários.** Menu **Patrimônio → Inventários**. A lista mostra as campanhas, cada uma com a data-base, o escopo e a situação (aberta, em conciliação, encerrada).:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/09-asset-inventories-list.png" alt caption width="3200" height="2000"}
2. **Abra uma campanha e conduza o levantamento.** Na ficha da campanha você\::inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/10-asset-inventory-detail.png" alt caption width="3200" height="2000"}
   - Define o **escopo** (por estabelecimento, departamento ou classe) e a **data-base**.
   - Designa a **comissão** — mínimo de 3 membros, e ninguém que detenha bem dentro do escopo pode participar (evita conflito).
   - Registra a **contagem cega**: quem conta não vê a quantidade nem o local esperados. Isso impede "acertar" o número para bater com o registro.
   - Faz a **conciliação**: o sistema aponta cada divergência (bem faltante, local divergente, custódia divergente).
   - **Encerra** a campanha, gerando o relatório de conciliação.

### Cadastrar bens imóveis

Imóveis do órgão (terrenos e edificações) têm cadastro próprio, com a regra de que **terreno nunca deprecia**.

1. **Abra a lista de imóveis.** Menu **Patrimônio → Bens imóveis**. Cada imóvel traz o selo do tipo (terreno ou edificação) e a marca de depreciável / não depreciável.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/11-real-properties-list.png" alt caption width="3200" height="2000"}
2.

**Edificação que já estava em uso entra com a depreciação que carrega** — mesma regra dos bens móveis (passo 4). Ao cadastrar uma edificação cuja entrada em uso é anterior à data de contabilização, o sistema abre a posição dela no reconhecimento em vez de zerada, e você pode informar a posição à mão quando o laudo souber o número melhor que o calendário. **Terreno não entra nessa conta**: não deprecia, então abre sempre em zero, sem posição de abertura nenhuma.

**Clique em "Novo".** Escolha o **tipo** (terreno ou edificação), a **classe**, a **matrícula**, o **valor** e a **data**. Para uma edificação, você pode vincular o terreno correspondente. O próprio tipo decide a depreciação: **terreno vem marcado como não depreciável** (não existe botão para ligar/desligar), edificação deprecia normalmente.

1. **Consulte a ficha do imóvel.** Ao abrir um imóvel, você vê os dados de matrícula, valor, tipo e a trilha de auditoria (quem cadastrou e alterou, com antes e depois).:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/13-real-property-detail-history.png" alt caption width="3200" height="2000"}

### Inventário de bens imóveis

1. **Abra o inventário de imóveis.** Menu **Patrimônio → Inventário de imóveis**. É o mesmo rito do inventário de móveis, adaptado a imóveis: a localização é estabelecimento + departamento (imóvel não fica em prateleira, então não há endereço de bin), e a situação de conservação vai até "ruins".:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/15-rp-inventories-list.png" alt caption width="3200" height="2000"}
2. **Conduza a campanha.** Abra a campanha com a comissão, faça a **contagem cega** de cada imóvel (registrando a conservação, sem ver o esperado), **concilie** as divergências e **encerre** a campanha com o resumo.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/16-rp-inventory-detail.png" alt caption width="3200" height="2000"}

### Definir o detentor (carga) do bem

Além do responsável informado no tombamento, cada bem tem um **detentor** — a pessoa que fisicamente responde pela carga. O detentor é gerido dentro da própria ficha do bem, no quadro **Detentor (carga)**.

1. **Abra o bem.** Menu **Patrimônio → Bens patrimoniais → abrir o bem**. Role até o quadro **Detentor (carga)**, onde aparece o detentor atual (marcado como **Atual**), a data de atribuição e as anotações.
2. **Atribua um detentor.** Clique em **Atribuir detentor**, escolha o servidor na lista de detentores, informe a **data da atribuição** e uma anotação (opcional). Ao salvar, esse servidor passa a constar como detentor atual e a atribuição anterior fica no histórico.
3. **Edite ou emita o termo.** Use **Editar** para corrigir os dados de uma atribuição e **Termo do detentor** para gerar o documento formal da carga, que o servidor assina reconhecendo a responsabilidade pelo bem.

### Emitir termo de responsabilidade com aceite eletrônico

O **termo de responsabilidade** formaliza a guarda do bem por um servidor e pode ser aceito eletronicamente, sem papel.

1. **Abra os termos de responsabilidade.** Menu **Patrimônio → Termos de responsabilidade**. A lista mostra cada termo com o bem, o detentor, a finalidade, a situação (**Pendente**, **Aceito** ou **Rejeitado**) e a data de aceite.
2. **Registre um novo termo.** No quadro **Registrar termo**, escolha o **bem** e o **detentor** (ambos com busca por digitação), informe a **finalidade** (campo opcional) e clique em **Registrar**. O termo nasce com situação **Pendente**.
3. **Acompanhe o aceite eletrônico.** O detentor confirma pela ação **Aceitar** ou recusa pela ação **Rejeitar**. Ao aceitar, a situação vira **Aceito** e a data de aceite é gravada; ao rejeitar, vira **Rejeitado**. Use **Imprimir termo** para gerar o documento do termo a qualquer momento.

### Registrar e acompanhar transferências (interna, externa e termo)

O quadro de transferências do módulo (menu **Patrimônio → Transferências de bens**) mostra a fila de aceite; para o histórico completo e a busca use o **registro de transferências**.

1. **Abra o registro de transferências.** Menu **Patrimônio → Registro de transferências**. Filtre por **Tipo** (**Interna** ou **Externa**), por **Situação** (**Aguardando aceite**, **Aceita**, **Rejeitada**) e por período (**De** / **Até**).
2. **Leia a lista.** Cada linha traz o bem, o tipo, a situação, a origem (**De**), o destino (**Para**), a data e quem iniciou. Use **Exportar CSV** para baixar o resultado da busca em planilha.
3. **Emita o termo e anexe documentos.** Na linha da transferência, use **Termo de transferência** para gerar o documento de movimentação e **Documentos** para anexar comprovantes ligados à transferência (interna ou externa).
4. **Confirme ou recuse pela fila de aceite.** Quando você é o novo detentor, a transferência aparece em **Aguardando meu aceite** (dentro de **Transferências de bens**). Ali você vê a origem, para quem e quando, e decide por **Aceitar** (assume a custódia) ou **Rejeitar** — neste caso o sistema exige o **Motivo da rejeição** e o bem permanece com o detentor de origem. A transferência externa, ao ser aceita, lança o movimento na contabilidade (débito igual a crédito).

### Ceder bens patrimoniais (cessão)

A **cessão** registra a entrada de bens cedidos por outro órgão, com período de vigência e a relação de materiais.

1. **Abra as cessões.** Menu **Patrimônio → Cessões**. Filtre por **Tipo de entrada**, **Situação** e pela busca livre (código, origem ou almoxarifado). A lista mostra código, tipo, situação, almoxarifado, origem, período e a contagem de materiais.
2. **Cadastre uma cessão.** Clique em **Nova cessão** e preencha o cabeçalho: **Código**, **Tipo de entrada**, **Situação**, **Almoxarifado**, **Origem**, **Data de início** e **Data de fim** e **Observações**.
3. **Adicione os materiais.** No bloco **Materiais**, use **Adicionar material** para incluir cada item com **Material**, **Número patrimonial**, **Quantidade**, **Valor unitário**, **Situação física** e **Características**. Salve para gravar a cessão.
4. **Consulte e anexe documentos.** Abra a cessão para ver o cabeçalho, a relação de materiais (com o **Valor total** calculado) e o quadro **Documentos**, onde ficam anexados os comprovantes da entrada de cessão. Use **Editar** na lista para ajustar uma cessão já cadastrada.

### Vincular adição a um bem principal

A **adição a bem principal** amarra um bem patrimonial a outro (o principal), útil quando um acessório ou componente passa a integrar um bem já tombado.

1. **Abra as adições.** Menu **Patrimônio → Adições de bens**. Filtre por **Bem principal** (busca por digitação) e veja a lista com o bem principal, o bem adicionado, a data da adição, a localização atual e as observações.
2. **Registre a adição.** Clique em **Nova adição**, escolha o **Bem principal** e o **Bem adicionado** (o sistema barra escolher o mesmo bem nos dois campos), informe a **Data da adição**, a **Localização atual** e as **Observações**, e confirme em **Registrar adição**.

### Agrupar bens em seleções

A **seleção de bens** é uma lista nomeada de bens patrimoniais, usada para agrupar e trabalhar um conjunto específico.

1. **Abra as seleções.** Menu **Patrimônio → Seleções de bens**. A lista mostra nome, descrição, quantidade de bens, quem criou e quando. Use **Exportar CSV** para baixar a relação em planilha.
2. **Crie ou edite uma seleção.** Clique em **Nova seleção**, informe **Nome** e **Descrição** e, no bloco **Bens da seleção**, filtre os bens e marque os que fazem parte (o rodapé mostra a contagem de **Bens selecionados**). Salve. Para ajustar depois, use **Editar**; para remover, use **Excluir** (o sistema pede confirmação).

### Registrar saída temporária e retorno

A **saída temporária** controla bens que deixam a organização por um período e devem voltar (empréstimo, conserto externo, evento).

1. **Abra as saídas temporárias.** Menu **Patrimônio → Saídas temporárias**. Filtre por **Situação** (**Fora** ou **Devolvido**) e por período (**De** / **Até**). A lista traz o bem, o objetivo, o responsável, o destino, a data de saída, o retorno previsto, o retorno efetivo e a situação. Use **Exportar CSV** para a planilha.
2. **Cadastre a saída.** Clique em **Nova saída** e preencha **Bem**, **Objetivo** (por que o bem está saindo), **Responsável**, **Destino**, **Data de saída** e **Data prevista de retorno**. A saída nasce com situação **Fora**.
3. **Anexe documentos e registre o retorno.** Use **Documentos** para anexar os comprovantes da saída. Quando o bem voltar, use **Retornar**, informe a **Data de retorno** (em branco assume hoje) e as **Observações de retorno** (condição do bem, por exemplo) e confirme. A situação passa a **Devolvido**.

### Requisitar material permanente

A **requisição de material permanente** é o pedido interno de bens patrimoniais, com itens, aprovação e atendimento.

1. **Abra as requisições.** Menu **Patrimônio → Requisições de material permanente**. Filtre por **Situação**, **Centro de custo** e período (**De** / **Até**). A lista mostra número, data de criação, centro de custo, situação e a previsão de atendimento.
2. **Crie a requisição.** Clique em **Nova requisição**, informe o **Centro de custo**, a **Data prevista de atendimento** e as **Observações**. No bloco **Itens**, use **Adicionar item** para incluir cada linha com **Descrição**, **Classe do bem** (opcional), **Unidade** (ex.: UN, CX) e **Quantidade**. Confirme em **Criar requisição**.
3. **Tramite a requisição.** Nas ações da lista, você **Aprova**, **Rejeita** ou **Cancela** a requisição, e usa **Detalhes** para ver o conteúdo. Quando aprovada, use **Atender**: na tela de atendimento cada item mostra o **Solicitado**, o **Já atendido** e o campo **Entregar agora**, permitindo atendimento total ou parcial. Confirme em **Confirmar atendimento**.
4. **Emita os relatórios.** Use **Relatório de atendimento (CSV)** para o comprovante de atendimento das requisições e **Exportar (CSV)** para a relação das requisições pesquisadas.

### Baixar bens: modalidade, comissão e estorno

A baixa parte da ficha do bem (menu **Patrimônio → Bens patrimoniais → abrir o bem → Baixa / desfazimento**) e tem registro próprio para consulta.

1. **Preencha a baixa na ficha do bem.** No formulário de baixa você informa a **Classificação** (ex.: **Ocioso**, **Recuperável**, **Antieconômico**, **Irrecuperável**), a **Modalidade** de desfazimento (**Venda**, **Doação**, **Permuta**, **Leilão**, **Sucateamento**, **Extravio**, **Furto**, **Cadastramento indevido**, **Mudança para consumo**, entre outras), a **Data da baixa**, a **Comissão** (mínimo de 3 membros) e a **Justificativa** (gravada como evidência de auditoria). Confirme em **Baixar**. O sistema mostra o **Valor líquido** e o **Valor bruto** antes de confirmar.
2. **Consulte o registro de baixas.** Menu **Patrimônio → Registro de baixas**. Filtre por **Modalidade** e período (**De** / **Até**). A lista traz o bem, a data, a modalidade, a classificação, o valor líquido, a situação (**Baixado** ou **Estornado**) e o acesso aos **Documentos**.
3. **Emita os documentos e anexe comprovantes.** Da própria ficha, na área de desfazimento, você emite o **Termo de baixa**, a **Autorização de saída** e o **Recibo de bens**, e anexa os documentos ligados à baixa.
4. **Estorne, se necessário.** Se a baixa foi indevida, use o **estorno** (reversão da baixa): o bem volta às operações ativas e o lançamento de desreconhecimento é revertido. No registro, a linha passa a exibir a situação **Estornado**.

### Registrar reavaliação e reunir a comissão

Além de lançar a reavaliação/impairment na ficha do bem, o módulo mantém um registro das reavaliações e um cadastro de comissões reaproveitáveis.

1. **Lance na ficha do bem.** No quadro **Reavaliações e impairment** da ficha, escolha a **Operação** (**Reavaliação (valor justo)**, **Perda por impairment** ou **Reversão de impairment**) e o **Motivo** (**Reavaliação** ou **Ajuste de dados**), informe o **Valor justo** (ou o **Valor recuperável**, no impairment) e a **Justificativa**. O sistema orienta: acima do valor líquido a reavaliação lança superávit no patrimônio líquido; abaixo, lança perda; a reversão só pode ir até o impairment já reconhecido.
2. **Consulte o registro de reavaliações.** Menu **Patrimônio → Registro de reavaliações**. Filtre por **Tipo** e por período (**De** / **Até**) e veja, por linha, o bem, a data, o tipo, o ajuste, o líquido anterior e o novo líquido.
3. **Mantenha as comissões.** Menu **Patrimônio → Comissões**. Em **Registrar comissão**, dê um **Nome** (ex.: Comissão anual 2026) e use **Adicionar membro** para compor a comissão — mínimo de 3 membros, conforme a Lei 4.320 art. 96. A comissão cadastrada fica disponível para reaproveitar na baixa, na reavaliação e no inventário; use **Desativar** quando ela não for mais usada.

### Emitir os relatórios do patrimônio

O módulo concentra os relatórios de bens móveis numa tela única de emissão em CSV.

1. **Abra os relatórios.** Menu **Patrimônio → Relatórios de patrimônio**. No quadro **Emitir relatório**, escolha o **Relatório** na lista e, quando o relatório for por período, informe **De** e **Até**. Clique em **Baixar CSV**.
2. **Escolha o relatório certo.** A lista cobre, entre outros: **catálogo de bens**, **bens por detentor**, **por tipo do bem**, **entradas por período / por tipo / por conta / sintético**, **transferências internas** (analítico e quantitativo), **transferências externas (entre UG)**, **baixas por período**, **reavaliação detalhada**, **pendências / nada consta** e os **analíticos de bens agrupados por conta** e **por conta e material**. Cada opção gera a planilha correspondente para conferência e prestação de contas.

### Emitir relatórios patrimoniais

Além dos relatórios que saem da ficha de cada bem, o módulo tem uma tela única que reúne os relatórios gerenciais e contábeis do patrimônio, todos exportados em CSV (abrem no Excel).

1. **Abra os relatórios.** Menu **Patrimônio → Relatórios patrimoniais**. A tela tem um campo **Relatório** (a lista de modelos disponíveis) e, para os relatórios que trabalham por intervalo de datas, os campos **De** e **Até**.
2. **Escolha o modelo.** No campo **Relatório** você seleciona um dos modelos. Os principais para prestação de contas e conferência:

- **UL por UA (unidade localizadora por administrativa)** — a distribuição dos bens por unidade.
- **Analítico por conta contábil** e **Entradas por conta contábil** — os bens e as entradas agrupados pela conta do PCASP.
- **Materiais por conta contábil** — os materiais permanentes por conta.
- **Valor residual** — o valor que resta em cada bem depois da depreciação.
- **Histórico de depreciação mensal** e **Depreciação acumulada (mensal)** — a evolução da depreciação mês a mês.
- **Depreciação por almoxarifado** — a depreciação agrupada por almoxarifado/estabelecimento.
- **Documentos por entrada** — os documentos de origem vinculados a cada entrada.
- **Transferências internas** — as movimentações internas do período.
- **Entradas (sintético)** — o resumo das entradas patrimoniais por período.
- **Movimentação de bens por almoxarifado (RMB)** — o Relatório de Movimentação de Bens por almoxarifado.
- **Carga patrimonial por período** — a carga de bens por responsável no intervalo escolhido.

3. **Informe o período, se o modelo pedir.** Quando o relatório escolhido trabalha por intervalo (entradas, transferências, depreciação, movimentação, carga por período), os campos **De** e **Até** ficam disponíveis. Modelos que são uma fotografia do momento (catálogo, valor residual, UL por UA) não pedem período.
4. **Clique em "Emitir relatório"** e depois em **"Baixar CSV"**. O arquivo é gerado e baixado; abra no Excel para conferir, filtrar ou anexar ao processo.

:::BlockQuote
Os mesmos números que alimentam esses relatórios são os que o fechamento mensal contabiliza — por isso o relatório de depreciação acumulada de um mês só traz valores dos meses já fechados.
:::

### Detalhar o cadastro do imóvel e do terreno

O cadastro de bens imóveis (menu **Patrimônio → Bens imóveis**) vai muito além do tipo e do valor: ele guarda a localização completa, a forma como o bem entrou no patrimônio, o desmembramento e os documentos do imóvel. Estes campos ficam no formulário de cadastro (botão **Novo**) e na ficha do imóvel (ao abrir um registro).

1. **Escolha o tipo e a classe.** No **tipo** você define se é **Terreno** ou **Edificação** (a marca de depreciável vem do tipo — terreno nunca deprecia). A **classe** traz a vida útil e as contas contábeis.
2. **Informe o tipo de incorporação.** O campo **Tipo de incorporação** registra como o bem entrou no patrimônio: **compra, doação, permuta, cessão de uso, reversão, dação em pagamento, desapropriação, usucapião, construção, benfeitoria** ou **desmembramento**. É o que o controle exige para saber a origem de cada imóvel.
3. **Registre o desmembramento, quando for o caso.** Se o imóvel ou terreno nasceu do desmembramento de outro, escolha a incorporação **Desmembramento** e vincule o **imóvel principal** no campo **Imóvel principal (desmembramento)**. Assim o novo registro fica amarrado ao bem de origem.
4. **Preencha a localização completa.** Informe **CEP, logradouro, número, complemento, bairro, município, UF, região e país**. Para terrenos você também informa **largura, comprimento** e a **zona** (rural ou urbana). Os campos **latitude** e **longitude** guardam a geolocalização; depois de salvar, a ficha mostra o link **Abrir no Google Maps** / **Abrir no OpenStreetMap** e o mapa da localização.
5. **Complete os dados gerais.** Na ficha do imóvel você informa a **unidade gestora**, a **situação de ocupação**, a **situação física / condição de uso**, o **número do RIP**, o **responsável**, a **data de incorporação**, o **valor de aquisição** e a **matrícula** (número de registro).
6. **Vincule os documentos do imóvel.** Na área **Documentos** da ficha, anexe escritura, alvará, registro de cartório, habite-se, fotos do imóvel e demais comprovantes. Ficam guardados junto ao registro e disponíveis para consulta.
7. **Consulte e edite.** A lista de imóveis permite consultar por nome, valor de aquisição, tipo de incorporação e tipo de imóvel. Ao abrir um registro você vê todos os dados e pode **editar** o cadastro pelo botão de edição da ficha.



![](https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/13-real-property-detail-history.png)

### Registrar o memorial descritivo

O memorial descritivo é a "certidão de nascimento" da obra: descreve o projeto, o detalhamento construtivo e as características físicas do imóvel. Ele fica dentro da ficha do imóvel, na área **Memorial descritivo**.

1. **Abra o imóvel e vá em "Memorial descritivo".** Menu **Patrimônio → Bens imóveis → abrir o imóvel**. O memorial já nasce vinculado àquele imóvel — não é um cadastro solto.
2. **Preencha os dados gerais.** Informe o **RIP**, o **responsável**, o **valor de aquisição**, o **valor atual**, o **tipo de obra**, a **empresa responsável pelo memorial**, a **matrícula do imóvel**, o **padrão construtivo**, a **área construída** e a **área do terreno**.
3. **Descreva o projeto e o detalhamento.** No campo **conceituação do projeto** você descreve a concepção da obra; no **detalhamento** você descreve serviços gerais, estruturas, obras complementares, paredes, painéis, cobertura, revestimentos, pinturas, pavimentações, instalações e demais itens; no campo de **complementação e despesas eventuais** você registra o que faltou.
4. **Informe as características físicas.** Registre a quantidade de **pavimentos, banheiros, salas, paredes, cozinhas, copas e refeitórios**, além da **idade aparente** do imóvel.
5. **Mantenha o checklist de atualizações.** Na área **Atualizações da obra**, clique em **Adicionar atualização** e informe a **data** e a **descrição** de cada atualização (formato de checklist datado). Cada linha fica registrada com sua data.
6. **Anexe os documentos do memorial.** Na área **Documentos** do memorial, vincule registro de cartório, fotos do imóvel e demais comprovantes.
7. **Emita o relatório e mantenha o registro.** O botão **Relatório (PDF)** gera o relatório analítico do memorial. O memorial pode ser **editado** e **excluído** (o sistema pede confirmação antes de apagar).

### Registrar vistorias do imóvel e do terreno

A vistoria documenta o estado de conservação de um imóvel ou terreno numa data, podendo até revisar a vida útil. Fica na área **Vistorias** da ficha do imóvel.

1. **Abra o imóvel e vá em "Vistorias".** Menu **Patrimônio → Bens imóveis → abrir o imóvel → Vistorias**. A área lista as vistorias já cadastradas para consulta.
2. **Escolha o alvo da vistoria.** No campo **Alvo** você define se a vistoria é da **Edificação** ou do **Terreno** — os dois são vistoriados separadamente.
3. **Preencha os dados da vistoria.** Informe o **nome da vistoria**, a **data**, o **endereço**, a **nova vida útil (em meses)** quando a vistoria reavaliar a durabilidade, e a **justificativa / avaliação final** do imóvel ou terreno.
4. **Marque os itens inspecionados.** No **checklist de constatações** você seleciona os itens inspecionados e registra a **situação de conservação** encontrada. Nas **considerações finais** você descreve as observações do responsável.
5. **Consulte, gere o relatório, edite ou exclua.** A vistoria aparece na lista da ficha; o botão **Relatório (PDF)** gera o relatório analítico da vistoria; o registro pode ser **editado** e **excluído** (com confirmação).

### Importar levantamento, tratar inconsistências e emitir relatórios do inventário

A campanha de inventário (menu **Patrimônio → Inventários**) não é só contagem cega e conciliação: ela permite classificar a campanha, importar o levantamento de campo, tratar divergências em lote e gerar os relatórios exigidos. Estas ações ficam na ficha da campanha.

1. **Classifique a campanha.** Ao abrir a campanha, informe o **tipo** (anual, eventual, extinção ou transferência) e o **objetivo** (conferência, criação de órgão, entre outros). Isso identifica a finalidade do inventário para o controle.
2. **Anexe os documentos da campanha.** Na área de **documentos** da campanha, vincule portarias, atas e demais arquivos associados ao inventário.
3. **Importe os dados de levantamento.** Se a contagem foi feita por planilha ou pelo aplicativo de campo, use **Importar CSV** (área **Importar dados de levantamento**). O sistema mostra quantos itens foram **importados**, quantos foram **marcados como não localizados** e quantos foram **ignorados por serem desconhecidos**.
4. **Trate as inconsistências, individualmente ou em lote.** Depois da contagem, cada bem aparece com o resultado (**Localizado** / **Não localizado**). Você pode tratar um item por vez ou **selecionar vários itens** (seleção em lote) e aplicar o tratamento de uma vez — o painel mostra o total **selecionado** e permite **limpar a seleção**.
5. **Concilie e feche.** Com todos os bens contados, clique em **Conciliar**. O sistema monta o **resumo de conciliação (físico × contábil)** e libera o encerramento (só é possível conciliar depois de contar todos os bens).
6. **Emita os relatórios do inventário.** A campanha gera três relatórios: **Relatório geral (PDF)** dos materiais levantados, **Relatório de itens (CSV)** — a listagem filtrável, item a item, para relatórios diversos e personalizados — e **Estrutura organizacional (CSV)** — a estrutura da unidade a ser inventariada. O **relatório de conciliação (PDF)** sai no encerramento.



![](https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/078-inventory-reports.png)

### Coletar bens em campo pelo aplicativo mobile

Para o levantamento físico, o sistema tem uma tela otimizada para celular (o aplicativo de coleta), pensada para o servidor percorrer as salas com o telefone na mão. Ele funciona no navegador do celular, em uma única coluna.

1. **Acesse a coleta.** Abra o endereço **/coleta** no celular. A coleta reaproveita o **login do portal** (o mesmo usuário e senha do sistema) — não há cadastro nem senha separados. Se você não estiver logado, a tela pede para entrar.
2. **Configure o aparelho (uma vez).** Em **Configurações**, informe o **nome da conexão** (o ambiente, ex.: Produção), o **prefixo da plaqueta** (removido do código lido, se houver) e a **quantidade de dígitos da plaqueta** (as plaquetas numéricas são completadas com zeros à esquerda até essa largura). Essas preferências ficam salvas no próprio aparelho.
3. **Escolha a unidade gestora / campanha.** A tela inicial lista as **campanhas de inventário abertas**. Toque na campanha da unidade que você vai inventariar; o aplicativo carrega os bens patrimoniais daquela campanha e guarda para uso mesmo sem internet.
4. **Colete cada bem por plaqueta.** Digite a plaqueta no campo ou toque em **Ler código de barras** para usar a câmera. O aplicativo mostra o resultado (**Encontrado** / **Não encontrado**); registre a **conservação** e as **observações** e toque em **Confirmar coleta**. (A coleta por RFID ainda não está disponível — depende de leitor próprio.)
5. **Inclua bens sem registro patrimonial.** Se aparecer um bem que não tem plaqueta cadastrada, use **Adicionar bem sem registro**, descreva o bem, informe o **local** e a **conservação**, e adicione à coleta. Ele entra na aba **Sem registro** para tratamento posterior.
6. **Acompanhe o coletado e sincronize.** As abas **Coletar / Coletado / Sem registro** mostram o que já foi levantado, inclusive o que está **pendente de envio**. O indicador **Online / Offline** avisa a conexão. Quando houver rede, toque em **Sincronizar** para enviar a fila ao sistema — o resumo mostra quantas leituras, quantos bens sem registro e quantas plaquetas desconhecidas subiram. Se a sincronização falhar, a fila é preservada para nova tentativa.
7. **Faça o backup do aparelho.** O botão **Backup** exporta um arquivo JSON com a coleta daquele aparelho, como cópia de segurança antes de sincronizar.

### Baixa (desfazimento) de bem imóvel

Quando um imóvel deixa de servir ao órgão — foi vendido, doado, sucateado, ou saiu em cessão temporária —, você registra a **baixa** diretamente na ficha do imóvel. Todos os cartões desta e das próximas seções ficam na mesma tela: menu **Patrimônio → Bens imóveis**, abra o imóvel e role até o cartão correspondente.

1. **Abra o imóvel e vá ao cartão "Baixas".** Menu **Patrimônio → Bens imóveis**, clique no imóvel; a baixa já fica vinculada a ele (não há re-seleção de imóvel).
2. **Classifique a baixa.** Escolha a **classificação** do bem (ocioso, recuperável, antieconômico ou irrecuperável) e a **modalidade** de desfazimento — venda, doação, permuta, leilão, sucateamento, perda, dação em pagamento, investidura, alienação por investidura, desmembramento, entre outras.
3. **Informe o tipo de baixa.** No campo **Disposição**, marque **Permanente** ou **Temporária**. Uma baixa temporária (ex.: cessão com devolução prevista) admite a **Previsão de devolução**.
4. **Preencha os dados gerais e do processo.** Informe **Data da baixa**, **Número do decreto**, **Número do processo**, **Destinatário**, **Unidade gestora**, **Valor do terreno**, **Localização** e a **Justificativa** (motivo da baixa).
5. **Clique em "Registrar baixa".** O registro passa a aparecer na lista de baixas do imóvel, com a modalidade, a classificação e a data.
6. **Edite quando necessário.** Use **Editar** no registro para ajustar campos administrativos (decreto, processo, destinatário, unidade gestora, localização, previsão de devolução e justificativa). Valores e data de baixa são imutáveis após o registro.
7. **Gere o relatório e anexe documentos.** Cada baixa tem o link **Relatório de baixa (PDF)** (relatório analítico) e uma área de anexos para memorandos, processo da baixa, fotos do imóvel e outros documentos.

### Impostos e tarifas do imóvel

O cartão **"Impostos e tarifas"** registra IPTU, tarifas e taxas que incidem sobre o imóvel, com controle de parcelas e vencimentos.

1. **Vá ao cartão "Impostos e tarifas"** na ficha do imóvel.
2. **Cadastre o imposto/tarifa.** Escolha o **Tipo** (IPTU, Tarifa, Taxa ou Outros), a **Descrição**, o **Ano de referência**, o **Valor**, os **Juros** e a **Multa**.
3. **Defina periodicidade e status.** Marque a **Periodicidade** (Anual ou Mensal) e o **Status de pagamento** (A pagar, Quitada ou Contestada).
4. **Informe as datas e o parcelamento.** Preencha a **Data de apresentação**, a **Quantidade de parcelas** e a **Data do primeiro vencimento** — o sistema gera as parcelas a partir daí. Use **Informações complementares** para notas livres.
5. **Clique em "Registrar imposto".** O registro entra na lista, mostrando tipo, descrição, valor e status.
6. **Acompanhe e baixe as parcelas.** Cada imposto exibe suas **parcelas** com o vencimento; use **Marcar como paga** para quitar uma parcela. Assim você acompanha os prazos e vencimentos.
7. **Anexe documentos, edite ou exclua.** Vincule documentos ao cartão; use **Atualizar imposto** para editar e o ícone de lixeira para **excluir** o registro.

:::BlockQuote
**Campos não disponíveis nesta versão da tela:** centro de custo e fornecedor não aparecem no formulário de imposto/tarifa — registre esses dados nas informações complementares se precisar rastreá-los.
:::

### Contrato de aluguel do imóvel

Quando o órgão aluga um imóvel (é locatário), registre o contrato no cartão **"Aluguéis"** da ficha do imóvel.

:::BlockQuote
**Não confunda com o cartão vizinho.** Se o imóvel é do órgão e quem paga é um terceiro, o contrato vai no cartão **Locações (como locador)**, que gera o aluguel a receber todo mês — ver *Locação de imóvel próprio*. Este cartão aqui não gera título nenhum.
:::

1. **Vá ao cartão "Aluguéis".**
2. **Cadastre o contrato.** Informe o **Número do contrato**, o **Locador**, o **Valor do aluguel**, a **Data de pagamento**, a **Vigência inicial** e a **Vigência final**.
3. **Complete as condições financeiras.** Preencha a **Caução** (depósito de garantia), a **Multa**, os **Juros**, a **Periodicidade** (Anual ou Mensal) e o **Índice de reajuste**. Use **Informações complementares** para o restante do contrato.
4. **Clique em "Registrar aluguel".** O contrato entra na lista de aluguéis do imóvel (já vinculado a ele).
5. **Consulte, edite, exclua e anexe.** A lista mostra os contratos cadastrados; use **Atualizar aluguel** para editar, o ícone de lixeira para **excluir**, e a área de anexos para documentos do contrato.

### Benfeitorias no imóvel

O cartão **"Benfeitorias"** registra obras e melhorias no imóvel, com classificação jurídica e tipo de manutenção.

1. **Vá ao cartão "Benfeitorias"** na ficha do imóvel.
2. **Preencha os dados gerais.** Informe a **Data**, a **Descrição**, o **Valor** (capitalizado ao imóvel), o **Número do contrato**, a **Empresa contratada** (Executado por), a **Ordem de serviço**, o **Número do processo**, a **Origem da verba** (Fonte de recurso), a **Data inicial**, a **Data final** e o **Responsável técnico**.
3. **Classifique a natureza jurídica.** No campo **Natureza jurídica**, escolha **Necessária**, **Útil** ou **Voluptuária**.
4. **Marque o tipo de execução.** No campo **Tipo de benfeitoria**, selecione **Construção**, **Ampliação**, **Reforma**, **Modernização**, **Adaptação**, **Recuperação** ou **Outros**.
5. **Indique a manutenção executada.** Use o **Tipo de manutenção** (Preventiva, Corretiva, Preditiva) e a **Disciplina de manutenção** (Hidráulica, Elétrica, Construção, Pintura, Alvenaria, Carpintaria, Outros). Descreva o que foi feito no campo **Serviços**.
6. **Clique em "Registrar benfeitoria".** O registro entra na lista.
7. **Consulte, edite e anexe.** A lista mostra as benfeitorias cadastradas; use **Editar** para ajustar (o valor capitalizado fica bloqueado na edição), o ícone de lixeira para **excluir**, e a área de anexos para contrato, fotos das benfeitorias e outros documentos.

### Seguros do imóvel

O cartão **"Seguros"** guarda as apólices que cobrem o imóvel.

1. **Vá ao cartão "Seguros"** na ficha do imóvel.
2. **Cadastre a apólice.** Informe a **Seguradora**, o **Número da apólice**, o **Valor segurado**, o **Responsável pelo seguro**, o **Início** e o **Fim da vigência**, o **Prêmio**, a **Franquia** (Deductible) e a **Descrição da cobertura**.
3. **Clique em "Registrar seguro".** A apólice entra na lista, já vinculada ao imóvel.
4. **Consulte, edite, exclua e anexe.** A lista mostra os seguros cadastrados; edite ou **exclua** (o sistema pede confirmação antes de apagar) e anexe o contrato do seguro, fotos do imóvel e outros documentos.

### Pedidos de manutenção e reforma do imóvel

O cartão **"Pedidos de manutenção / reforma"** conduz o fluxo em duas etapas — o **pedido** (feito pelo requisitante) e a **autorização** (feita pelo setor técnico).

1. **Vá ao cartão "Pedidos de manutenção / reforma"** na ficha do imóvel.
2. **Registre o pedido.** Informe a **Data do pedido**, o **Requisitante**, o **Ramal** (Extensão), a **Localização**, o **Setor**, os **Materiais / serviços**, os **Quantitativos** e o **Detalhamento**.
3. **Clique em "Registrar pedido".** Ele entra na lista com status **Pendente**.
4. **Complemente ou exclua enquanto está pendente.** Um pedido **Pendente** pode ser editado (o setor responsável ajusta ou complementa materiais/serviços, quantitativos e observações) ou excluído pelo ícone de lixeira. Depois de decidido, o pedido não é mais editável.
5. **Autorize ou negue.** No bloco **Autorização** do pedido pendente, informe a **Data da autorização**, o **Técnico**, o **Valor** da manutenção/reforma e as **Observações**; então clique em **Autorizar** (status **Autorizado**) ou em **Negar** (status **Não autorizado**).
6. **Anexe documentos das duas etapas.** Cada pedido tem áreas separadas de **Documentos do pedido** e **Documentos da autorização**.
7. **Emita o relatório.** O cabeçalho do cartão traz o botão **Relatório (CSV)** com os pedidos e autorizações do imóvel.

### Itens verificados e classificação no inventário de imóveis

Além da comissão, contagem cega e conciliação (já descritas acima), a campanha de inventário de imóveis tem um **checklist de itens verificados** e uma classificação por tipo e objetivo.

1. **Abra a campanha.** Menu **Patrimônio → Inventário de imóveis**, clique na campanha.
2. **Confira o tipo e o objetivo.** A campanha traz o **Tipo** (Anual, Eventual, Inicial ou Transferência de gestão), o **Objetivo** (Levantamento ou Atualizar valor), as **datas de início e fim**, o **nome** e o **status** (Aberta, Conciliada, Encerrada ou Cancelada).
3. **Marque os itens verificados.** No cartão **Checklist de itens verificados**, marque cada item conferido — Documentação dominial, Planta de situação, Projeto arquitetônico, Projeto estrutural, Projeto de incêndio (PPCI), Projeto de climatização, Projeto de fundações, Instalações hidrossanitárias, Instalações elétricas, Instalações telefônicas / rede e Outros. Cada item marcado admite uma nota.
4. **Clique em "Salvar checklist".** O checklist fica gravado enquanto a campanha estiver editável.
5. **Anexe documentos e encerre.** Vincule documentos à campanha e conclua o rito de conciliação para gerar o resumo.

### Termo de responsabilidade e ficha individual do imóvel

1. **Abra o imóvel.** Menu **Patrimônio → Bens imóveis**, clique no imóvel.
2. **Emita o termo de responsabilidade.** No topo da ficha, o botão **Termo de responsabilidade (PDF)** gera o documento de responsabilidade pelo imóvel.
3. **Emita a ficha individual.** Ainda no topo, o botão **Ficha (PDF)** gera a ficha individual do imóvel. Quando há memorial descritivo cadastrado, o cartão **Memorial descritivo** também oferece um **Relatório (PDF)** com área, cômodos, padrão construtivo e valores.

### Termos de responsabilidade de bens móveis

Para bens móveis, os termos de responsabilidade dos servidores que respondem pela guarda dos itens têm tela própria, com aceite eletrônico.

1. **Abra a tela.** Menu **Patrimônio → Termos de responsabilidade**.
2. **Registre um termo.** No cartão **Registrar termo**, escolha o **Bem** (busca por número/descrição), o **Detentor** (servidor responsável) e, opcionalmente, a **Finalidade**; clique em **Registrar**. O termo nasce com status **Pendente**.
3. **Confirme ou recuse o aceite.** Na lista, um termo **Pendente** oferece **Aceitar** (vira **Aceito**, com data de aceite registrada) ou **Recusar** (vira **Recusado**).
4. **Reimprima o termo.** Termos que têm movimentação associada oferecem **Imprimir termo** (PDF), inclusive os já aceitos — útil para reemitir o comprovante de carga.

### Agregar e desagregar valores ao bem (adições)

Quando um componente ou benfeitoria é incorporado a um bem já tombado, você registra a **adição** ligando o bem adicionado ao bem principal — mantendo a rastreabilidade de cada parte.

1. **Abra a tela.** Menu **Patrimônio → Adições de bens**.
2. **Consulte as adições existentes.** A lista mostra o **Bem principal**, o **Bem adicionado**, a **Data da adição**, a **Localização atual** e as **Observações**. Use os filtros por bem principal para localizar.
3. **Registre uma adição.** Clique em **Nova adição**, escolha o **Bem principal** e o **Bem adicionado** (que deve ser diferente do principal), informe a **Data da adição** e, opcionalmente, a **Localização atual** e **Observações**; confirme em **Registrar adição**.

:::BlockQuote
Cada bem mantém seu próprio registro e histórico — a adição relaciona os dois sem apagar a origem, o que preserva a rastreabilidade do valor de aquisição e dos documentos.
:::

### Relatórios de patrimônio (bens móveis)

A central de relatórios de bens móveis reúne, num só lugar, as consultas por detentor, por tipo, por unidade, o valor residual e os relatórios de movimentação e depreciação.

1. **Abra a tela.** Menu **Patrimônio → Relatórios de patrimônio**.
2. **Escolha o relatório.** No campo **Relatório**, selecione o tipo desejado, por exemplo:

- **Catálogo de bens**, **Bens por detentor**, **Bens por tipo** e **UL por UA** (unidade localizadora por unidade administrativa) — para agrupar e classificar os bens por unidade, detentor e tipo.
- **Valor residual** — para o valor residual apurado dos bens (apoio à baixa).
- **Resumo de movimentação (por classe)** — saldo inicial, adições, baixas, transferências e saldo final, por custo e por depreciação.
- **Depreciação econômica (mês + exercício)** e **Histórico de depreciação mensal** — depreciação do mês e acumulada no exercício.
- **Ficha de movimentação** — a ficha por bem com origem e destino das movimentações.

3. **Informe o período, se pedido.** Para os relatórios por período (entradas, transferências, baixas, depreciação, ficha de movimentação), preencha as datas **De** e **Até**. Relatórios de inventário/catálogo não pedem período.
4. **Clique em "Baixar CSV".** O relatório é gerado e baixado em CSV.

## Catálogo de material permanente

***

O catálogo de material permanente é a lista oficial dos tipos de bem que o órgão pode adquirir e tombar. Cada item carrega o **código Federal Supply** (o código federal de suprimentos que identifica o tipo de material), a **conta contábil** onde o bem é registrado no PCASP e as regras de **transferência entre contas** quando o material for reclassificado. É a referência que padroniza a nomenclatura dos bens e garante que cada material caia na conta certa da contabilidade — você mantém este catálogo antes de requisitar ou incorporar bens, para que todos usem a mesma descrição e a mesma classificação contábil.

1. **Abra o catálogo.** Menu **Patrimônio → Materiais permanentes**. A lista mostra cada material com a descrição, o código Federal Supply e a conta contábil vinculada.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/e32-08-permanent-materials.png" alt caption width="3200" height="2000"}
2. **Cadastre um material.** Clique em **Novo material** e informe a **descrição**, o **código Federal Supply** e a **conta contábil** em que o bem é registrado no PCASP.
3. **Configure as transferências entre contas.** Quando o material puder migrar de uma conta contábil para outra (reclassificação), registre as contas de destino permitidas — assim a mudança de conta fica controlada e rastreável.
4. **Salve e consulte.** Ao salvar, o material passa a constar no catálogo e fica disponível para as requisições e para o tombamento de bens. Use a busca para localizar um item por descrição ou código e **Editar** para ajustar um material já cadastrado.

:::BlockQuote
**Como saber que deu certo:** o material recém-cadastrado aparece na lista com a descrição, o código Federal Supply e a conta contábil preenchidos, e passa a ser oferecido na hora de requisitar ou incorporar bens daquele tipo.
:::

## Roteiro de baixa de ativo

***

O roteiro de baixa é um lote de desfazimento: em vez de baixar bem a bem, você monta um único processo (roteiro) reunindo vários bens que serão desfeitos pela mesma modalidade — leilão, doação, inservível, e assim por diante. O roteiro passa por uma avaliação (**Em avaliação → Autorizado** ou **Não autorizado**) e permite registrar o estado físico de cada bem, individualmente ou de uma vez para o lote inteiro, atendendo ao Decreto 9.373/2018, que trata do desfazimento de bens da Administração Pública.

1. **Abra os roteiros de baixa.** Menu **Patrimônio → Roteiros de baixa**. A lista mostra cada roteiro com a modalidade de desfazimento, a quantidade de bens incluídos e a situação (**Em avaliação**, **Autorizado** ou **Não autorizado**).:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/e32-06-asset-disposal-routes.png" alt caption width="3200" height="2000"}
2. **Crie um roteiro.** Clique em **Novo roteiro**, dê uma identificação ao lote e escolha a **modalidade** de desfazimento — **leilão, doação, inservível (sucateamento)**, entre outras. A modalidade define como aquele conjunto de bens será desfeito.
3. **Inclua os bens.** Adicione ao roteiro os bens que serão baixados naquele lote. Você pode incluir vários bens no mesmo roteiro, agrupando o desfazimento num único processo.
4. **Registre o estado físico.** Informe o estado físico (condição de conservação) de cada bem — **individualmente** ou **em lote**, aplicando a mesma condição a todos os bens marcados de uma vez.
5. **Acompanhe a avaliação.** O roteiro nasce **Em avaliação**. Quando a autoridade competente decide, a situação passa a **Autorizado** (o desfazimento pode seguir) ou **Não autorizado** (o lote é barrado). A situação de cada roteiro fica visível na lista.

:::BlockQuote
**Como saber que deu certo:** o roteiro criado aparece na lista com a modalidade e a contagem de bens; depois da decisão, a situação muda de **Em avaliação** para **Autorizado** ou **Não autorizado**, e o estado físico informado fica gravado em cada bem do lote.
:::

## Processo de reavaliação de ativo

***

O processo de reavaliação organiza, num único registro, a revisão de valor de um bem: você abre o processo indicando o tipo de alteração e o motivo, define a comissão responsável (os funcionários que respondem pela reavaliação) e acompanha a situação até a conclusão. É o envelope administrativo que dá formalidade e rastreabilidade à reavaliação, separando a decisão (o processo e sua comissão) do lançamento contábil que ela gera na ficha do bem.

1. **Abra os processos de reavaliação.** Menu **Patrimônio → Processos de reavaliação**. A lista mostra cada processo com o tipo de alteração, o motivo, a comissão responsável e a situação.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/e32-07-asset-revaluation-processes.png" alt caption width="3200" height="2000"}
2. **Abra um processo.** Clique em **Novo processo** e informe o **tipo de alteração** (a natureza da reavaliação) e o **motivo** que justifica a revisão de valor.
3. **Defina a comissão responsável.** Adicione os **funcionários** que compõem a comissão da reavaliação — são eles que respondem tecnicamente pelo processo.
4. **Evolua a situação.** Conforme o trabalho avança, atualize a **situação** do processo até a conclusão. O andamento fica visível na lista, mostrando em que etapa cada reavaliação está.

:::BlockQuote
**Como saber que deu certo:** o processo aberto aparece na lista com o tipo de alteração, o motivo e a comissão informados; ao evoluir, a situação registrada reflete o andamento e mantém o histórico de quem participou da reavaliação.
:::

## Fechamento e depreciação mensal de bens imóveis

***

Edificação perde valor com o tempo e isso tem que aparecer na contabilidade todo mês — **terreno nunca deprecia, só a edificação**. Este é o fechamento que dispara essa conta: você escolhe a competência, o sistema deprecia as edificações elegíveis, atualiza o valor líquido de cada imóvel e gera o lançamento contábil (despesa de depreciação contra depreciação acumulada). **Não existe rotina automática** — enquanto ninguém fechar a competência aqui, a depreciação dos imóveis simplesmente não acontece, e o imobiliário fica superavaliado no balanço.

É uma tela **diferente** do **Patrimônio → Fechamento mensal**, que roda a depreciação dos bens móveis. As duas rodadas são independentes.

1. **Abra o fechamento de imóveis.** Menu **Patrimônio → Fechamento de imóveis**. A tela tem dois cartões: **Competência a fechar**, em cima, e **Histórico de fechamentos**, embaixo.
2. **Confira a competência.** O campo **Mês de referência** já vem preenchido com o período aberto do patrimônio (o mesmo período compartilhado com o fechamento de bens móveis); se essa consulta falhar, o campo cai para o mês corrente do calendário — a sugestão é conveniência, não trava. Você pode trocar o mês. A dica do campo lembra a regra que mais surpreende: **um mês só pode ser fechado uma vez**.
3. **Decida quando contabilizar.** A opção **Calcular agora e contabilizar depois** deixa a rodada como **rascunho**: os valores são calculados e guardados, mas **nada chega à contabilidade**. Deixe desmarcado para calcular e contabilizar de uma vez (o comportamento normal). Marque apenas se você quer conferir os números antes de mandar para o razão.
4. **Clique em "Fechar competência".** Abaixo do botão aparece o **Resultado** da rodada: a situação (**Rascunho** ou **Contabilizado**), a quantidade de **Imóveis** e a **Depreciação total**. Se nenhuma edificação foi depreciada, um aviso explica o que conferir — **vida útil, data de contabilização e situação de depreciação** dos imóveis —, em vez de exibir um resultado zerado que parece sucesso.
5. **Leia o histórico.** O cartão **Histórico de fechamentos** lista as rodadas da mais recente para a mais antiga, com **Competência**, **Imóveis**, **Depreciação total**, **Status** (**Rascunho** ou **Contabilizado**) e **Contabilizado em**. É por ele que você confere o que já rodou e o que ficou pela metade.
6. **Contabilize a rodada que ficou em rascunho.** Numa linha com status **Rascunho**, use a ação **Contabilizar este fechamento** e confirme a pergunta. A linha passa a **Contabilizado**, com a data e a hora. **Este é o único caminho:** como a mesma competência não pode ser fechada de novo, uma rodada adiada que ninguém contabiliza fica parada para sempre — os números existem, mas a despesa nunca entra na contabilidade.

:::BlockQuote
**Quem pode executar.** A **consulta** do histórico é aberta: qualquer usuário autenticado vê a tela no menu e lê as rodadas. **Executar** exige a autorização **Depreciar bens imóveis** (cadastrada em **Início → Alçada**, [Administração13](docId\:Z8SS7r6Bvhs09rP1SPxUD)). Sem ela, a tela avisa que você pode consultar os fechamentos mas não executá-los, o mês, a opção de adiar e o botão **Fechar competência** ficam desabilitados, e a ação **Contabilizar este fechamento** não aparece nas linhas.
:::

:::BlockQuote
**Consulta negada não é histórico vazio.** Se o servidor recusar a leitura das rodadas, o histórico mostra o **erro**, com a opção de tentar de novo — nunca "nenhum fechamento executado ainda", que se leria como se o mês nunca tivesse sido fechado.
:::

:::BlockQuote
**O que este fechamento não faz.** Ele **não** avança o período aberto do patrimônio (isso continua a cargo do fechamento de bens móveis) e **não** detalha imóvel a imóvel: o histórico mostra o agregado da rodada (quantidade e total). A trava contra depreciar o mesmo mês duas vezes é o próprio registro da competência no histórico.
:::

:::BlockQuote
**Como saber que deu certo:** a competência aparece no histórico com a quantidade de imóveis e o valor depreciado, com status **Contabilizado** e a data de contabilização preenchida; a ficha de cada edificação passa a mostrar a nova depreciação acumulada e o valor líquido menor; e o lançamento de depreciação daquele mês aparece no razão e no balancete da *contabilidade*, com débito igual a crédito.
:::

:::BlockQuote
**Rascunho não significa "nada aconteceu".** O cálculo é feito na hora, mesmo com a opção de adiar marcada: **a ficha dos imóveis já está depreciada** — depreciação acumulada, valor líquido e meses de vida útil consumidos são gravados no fechamento, não na contabilização. O que falta numa rodada em **Rascunho** é só o **lançamento contábil**. Por isso não adianta conferir o cadastro para saber se o mês foi contabilizado: o cadastro vai parecer certo nos dois casos. Quem responde é o status da rodada no histórico e o razão da contabilidade.
:::

## Locação de imóvel próprio (o órgão como locador) e o aluguel a receber

***

Esta é a direção **oposta** à do cartão **Aluguéis**, e vale ler a distinção antes de cadastrar, porque os dois cartões ficam lado a lado na mesma ficha e se parecem:

- **Aluguéis** — o órgão **paga**. É o contrato de um imóvel de terceiro que o órgão ocupa; o campo *Locador* é quem recebe o dinheiro. Não gera título nenhum.
- **Locações (como locador)** — o órgão **recebe**. É o imóvel próprio cedido a terceiro; o campo *Locatário* é quem paga. **Cada contrato ativo gera um título a receber por mês.**

1. Abra **Menu Patrimônio → Bens imóveis**, escolha o imóvel e localize o cartão **Locações (como locador)**.
2. Preencha o **Número do contrato**, escolha o **Locatário** (é um parceiro cadastrado, não um nome digitado — ele será o devedor do título) e o **Instrumento**: locação, concessão de uso, concessão de direito real de uso ou arrendamento. Só instrumentos onerosos aparecem na lista, porque um instrumento gratuito não teria o que cobrar.
3. Informe o **Valor mensal**, a vigência (**Início** e **Fim**) e o **Dia de vencimento**, entre 1 e 28. O limite não é capricho: um contrato que vence dia 30 não teria vencimento em fevereiro, e empurrar para o último dia do mês faria a data variar — o locatário lê isso como mudança de regra.
4. Escolha a **Natureza da receita**. A lista traz só as categorias que aceitam lançamento; uma categoria de agrupamento seria recusada na hora de gerar o título.
5. Escolha o **Índice de reajuste** pactuado e a **Situação**. Só contratos **Ativos** são cobrados.
6. Salve. O contrato passa a valer para as próximas cobranças.

### Como a cobrança acontece

A cobrança roda **sozinha, uma vez por mês**, e gera **um título por contrato por competência**. Não é preciso fazer nada para que aconteça.

Para conferir sem esperar a virada do mês, use **Gerar cobrança do mês** no próprio cartão. O resultado mostra três números: quantos títulos foram **emitidos**, quantos contratos **já estavam cobrados** naquele mês e quantos tiveram **falha**.

:::BlockQuote
**Clicar duas vezes não cobra duas vezes.** A segunda execução no mesmo mês emite zero e reporta os contratos como já cobrados. Isso é proposital e é a parte que mais importa: cobrar o locatário em duplicidade custa mais caro que deixar de cobrar, porque desgasta quem paga em dia.
:::

:::BlockQuote
**Um contrato com problema não derruba os outros.** Se a natureza de receita de um contrato tiver sido desativada, por exemplo, aquele contrato aparece em **falha** e os demais são cobrados normalmente.
:::

O título gerado nasce **amarrado ao contrato**: quem abrir o título no financeiro consegue navegar de volta para o imóvel que o originou, sem precisar perguntar de onde aquilo veio.

:::BlockQuote
**Outras origens de título a receber.** A locação é uma das operações que geram título automaticamente; venda e adiantamento também geram, e o passo a passo desses caminhos está em *Financeiro — documentos*.
:::

:::BlockQuote
**O que esta entrega ainda não faz.** O reajuste pelo índice **não** é aplicado sozinho no aniversário do contrato: o campo registra o índice pactuado, e o valor cobrado é o que estiver em *Valor mensal*. Atualizá-lo é edição manual do contrato.
:::

## Verificação

***

Você sabe que funcionou quando:

- Uma classe cadastrada aparece na lista de classes com sua vida útil e as três contas PCASP preenchidas.
- Ao salvar um bem novo, ele aparece na lista com o número de tombamento gerado, e a ficha mostra a depreciação programada para começar no mês seguinte.
- Depois de rodar o fechamento de um mês, o histórico da ficha do bem mostra a cota daquele mês e a depreciação acumulada cresce; o valor líquido bate com valor de aquisição menos depreciação acumulada.
- Uma transferência aceita pelo novo responsável muda o responsável/local do bem e some da fila de pendentes.
- Após uma baixa, o bem fica com situação "baixado", não aparece mais nas operações ativas e o lançamento de baixa está balanceado.
- Numa campanha de inventário, a contagem cega não expõe os números esperados e, ao conciliar, cada divergência aparece classificada (faltante, local, custódia).
- Um imóvel do tipo terreno aparece na lista como **não depreciável** e não recebe cota de depreciação no fechamento.
- Depois de fechar a competência em **Patrimônio → Fechamento de imóveis**, a rodada aparece no histórico com status **Contabilizado** e a data de contabilização preenchida; o valor líquido das edificações cai e o lançamento de depreciação do mês aparece no razão.

## Erros comuns

***

- **Não consigo tombar o bem — falta escolher a classe** — a classe é obrigatória porque é ela que traz a vida útil e as contas contábeis. Cadastre a classe primeiro (menu **Classes de bens**).
- **A ficha não mostra depreciação** — as cotas só aparecem depois do fechamento do mês correspondente. Rode o fechamento mensal e volte à ficha.
- **A comissão de inventário foi recusada** — a comissão precisa de no mínimo 3 membros, e ninguém que detenha bem dentro do escopo pode compor a comissão. Ajuste os membros.
- **Terreno sem depreciação** — não é erro: terreno nunca deprecia. Se o bem deveria depreciar, ele provavelmente foi cadastrado como terreno em vez de edificação.
- **Não consigo transferir/depreciar um bem** — verifique se ele já foi baixado. Bem baixado sai das operações ativas.
- **Não consigo excluir uma classe de bens** — não é possível: a classe é dado de referência (há bens vinculados a ela). Em vez de excluir, **desative** a classe — ela deixa de aparecer para novos bens, sem afetar os bens já tombados.
- **A classe não salva com vida útil zero** — a vida útil precisa ser maior que zero e as contas contábeis são obrigatórias. Preencha esses campos antes de salvar.
- **A edificação não deprecia, mesmo com o mês fechado** — confira se você fechou o mês na tela certa: **Patrimônio → Fechamento mensal** roda os bens **móveis**; a depreciação das edificações sai de **Patrimônio → Fechamento de imóveis**. As duas rodadas são independentes.
- **A competência aparece no histórico, mas nada chegou à contabilidade** — a rodada está em **Rascunho** (foi fechada com a opção *Calcular agora e contabilizar depois*). Use **Contabilizar este fechamento** na linha; refechar o mesmo mês é recusado, então essa é a única saída.
- **"Nenhuma edificação foi depreciada nesta competência"** — não é falha do fechamento: nenhum imóvel estava elegível. Confira a vida útil da classe, a data de contabilização e a situação de depreciação dos imóveis — e lembre que **terreno nunca deprecia**.
- **Não consigo fechar a competência de imóveis** — ou o mês já foi fechado (o histórico mostra a competência), ou falta a autorização **Depreciar bens imóveis**; sem ela a tela permite consultar, mas o botão de fechar fica desabilitado.


[title] Treinamento e desenvolvimento
[path] Aplicações/ERP/Manual do Usuário/

Treinamento numa organização se repete: a mesma integração de novos servidores, o mesmo curso de licitações, a mesma reciclagem de segurança. Sem catálogo, cada realização é redigitada — conteúdo, carga horária, pré-requisito — e a informação se perde entre planilhas.

**Curso e turma são coisas diferentes, e o sistema as separa desde o começo.**

O **curso** é a definição: o que ensina, quantas horas tem, o que exige antes e quais competências desenvolve. A **turma** é a realização: data, local, instrutor, custo, quem compareceu. Se custo e presença morassem no curso, seria preciso duplicar o curso a cada realização — e a partir daí o catálogo deixa de ser catálogo.

Esta página cobre o catálogo e os instrutores. A turma vem depois.

## Passo a passo

***

### Cadastrar um curso

1. **Abra "Catálogo de treinamentos"** (/training-courses). Menu **Recursos Humanos → Catálogo de treinamentos**.
2. Se você usar um código que já existe, o sistema recusa **dizendo o nome do curso que já o tem**. Isso normalmente resolve a dúvida na hora: quase sempre o curso já está cadastrado e você ia cadastrá-lo de novo.
   **Preencha código e nome.** O código é como as pessoas se referem ao curso em voz alta, e é único.
3. Não é detalhe de preenchimento: a validade da certificação e a frequência mínima que o sistema vai conferir na conclusão são calculadas a partir desse número.
   **Informe a carga horária em horas.**
4. É esse campo que decide quem conduz o curso: o presencial é conduzido aqui, com turma, lista de presença e custo; o conteúdo on-line é entregue pela plataforma de aprendizagem.
   **Escolha a forma de entrega** — presencial, on-line ou misto.
5. É o "eventuais requisitos". Quando a matrícula existir, é esse campo que ela vai conferir antes de aceitar alguém numa turma.
   **Indique o curso pré-requisito, se houver.** Deixe "Nenhum" quando não houver.
6. **Escreva exatamente como a certificação está cadastrada.** O sistema casa os dois **por texto** — uma letra diferente e a baixa automática na conclusão não encontra nada. E ela falha em silêncio: um nome que não casa com nada simplesmente não casa, sem erro e sem aviso.
   **Preencha a certificação concedida, se o curso conceder alguma.**
7. **Salve.**

### Dizer o que o curso desenvolve

1. **Clique no código do curso** na lista para abrir a ficha dele.
2. **Na seção "O que este curso desenvolve", escolha uma competência.** O combo mostra o teto da escala de cada uma ao lado do nome.
3. O nível **nunca passa do teto daquela competência** — e cada competência tem o seu. Se você pedir nível 7 numa competência medida até 5, o sistema recusa **nomeando a competência e o teto dela**, para você não ter de adivinhar qual dos dois números está errado.
   Deixar em branco é legítimo e significa "desenvolve, sem nível declarado". Exigir um número aí só faria alguém inventar um.
   **Informe o nível a que o curso leva, ou deixe em branco.**
4. Ele simplesmente não será sugerido automaticamente num plano de desenvolvimento, porque não há lacuna a que possa ser associado. É o vínculo com a competência que tira o plano de ser uma lista digitada à mão.

**Um curso sem nenhuma competência é aceito** — e a tela avisa o que isso custa.

### Cadastrar instrutores

1. **Abra "Instrutores"** (/instructors). Menu **Recursos Humanos → Instrutores**.
2. **Escolha a espécie: colega ou de fora.**
3. Se você tentar cadastrar o mesmo colega duas vezes, o sistema recusa e nomeia o registro que já existe.
   Ministrar é algo que a pessoa fez, e as horas pertencem à ficha dela. Um nome digitado criaria uma segunda versão de alguém que o cadastro já guarda, e as duas divergiriam na primeira vez que um nome fosse corrigido.
   **Para um colega, escolha a pessoa no cadastro** — não digite o nome.
4. Um convidado que ministra uma vez não precisa de cadastro de parceiro. Quando houver contrato e nota a rastrear, aí sim o parceiro é o caminho.
   **Para alguém de fora, basta o nome.**
5. **Salve.**

### Aposentar em vez de excluir

Curso e instrutor **não são excluídos** — são aposentados pelo botão na linha.

:::BlockQuote
Turmas passadas apontam para os dois. Apagar a linha deixaria um registro de presença descrevendo um curso que ninguém consegue nomear, ministrado por ninguém.
:::

## O que fica registrado

***

A ficha do curso traz o **histórico** de quem alterou o quê e quando. É onde um auditor confere uma mudança de carga horária — que é o número de que depende a validade de uma certificação.

## Quem pode o quê

***

Qualquer pessoa com acesso de leitura ao cadastro **consulta** o catálogo: ele é referência para o gestor de área que planeja o desenvolvimento da equipe.

**Manter** o catálogo — criar curso, ligar competência, cadastrar instrutor — exige a autorização própria de treinamento. A separação é intencional: o que o curso promete desenvolver, e até que nível, alimenta o plano de desenvolvimento e o orçamento que ele consome.

## Agendar uma turma

***

Curso é definição; **turma é quando ele acontece**. Data, local, vagas, custo e material são da turma — o mesmo curso custa diferente a cada realização, e por isso o valor não cabe no catálogo.

1. **Abra "Turmas de treinamento"** (/training-classes). Menu **Recursos Humanos → Turmas de treinamento**.
2. Data de início no passado é **recusada**, a menos que você marque que a realização já aconteceu. A causa comum de data passada é ano digitado errado, e turma agendada para trás nunca pode ser frequentada — mas registrar um treinamento que a organização já fez é legítimo. As duas coisas precisam continuar distinguíveis, então a segunda tem de ser **dita**, não deduzida da data.
   **Escolha o curso, a data de início e a de término.**
3. Em branco e zero são fatos diferentes: zero quer dizer que a realização foi gratuita. O relatório de custo **pula** as turmas sem custo lançado em vez de contá-las como zero — somar como zero deixaria o orçamento silenciosamente otimista.
   **Lance o custo, se já souber.** Deixe em branco enquanto não souber.
4. **Salve.** A turma nasce como rascunho.

### Declarar o material

1. **Abra a turma** clicando na data.
2. Só dá para mexer no material enquanto a turma é **rascunho**. Depois de enviada para aprovação, mudar o material deixaria o aprovador tendo autorizado uma turma diferente.

**Acrescente os itens** que o almoxarifado terá de fornecer, com a quantidade.

### Aprovar e confirmar

1. **Envie para aprovação** — é o analista terminando o trabalho dele.
2. Aprovar é alçada **separada** de manter o catálogo. Quem cura cursos não passa, por isso, a comprometer orçamento: confirmar uma turma compromete o custo num centro de custo e dispara requisição contra o almoxarifado.
   **Quem tem alçada de treinamento aprova e confirma.**
3. **Ao confirmar, a requisição de material é gerada sozinha** e fica ligada à turma.

### A armadilha: a turma que parece pronta

Se a requisição **falhar**, a turma continua confirmada — de propósito, porque indisponibilidade do estoque não pode impedir treinamento de ser agendado. Mas ela passa a exibir um **aviso vermelho** dizendo que a requisição não passou, com o motivo e um botão para tentar de novo. O aviso aparece também **na lista**, não só na tela da turma.

:::BlockQuote
Ignorar esse aviso significa que ninguém foi acionado para as apostilas. Isso é descoberto no dia, pelo instrutor, na frente da sala — e é exatamente o problema que esta tela existe para evitar.
:::

### Quanto um curso custou

No fim da tela de turmas, escolha o curso e o período. O total é **somado das realizações**, porque o catálogo não guarda dinheiro nenhum.

## Matricular, registrar presença e encerrar

***

Turma confirmada, começa a operação. Tudo acontece no bloco **Quem está matriculado e quantas horas assistiu**, na tela da turma.

### Matricular

Escolha a pessoa e clique em **Matricular**. O convite sai **na hora** — pela caixa de mensagens do portal, se ela tiver usuário, ou pelo e-mail que está na ficha. Depois disso o sistema ainda manda, sozinho, a **confirmação** quando a data se aproxima e o **lembrete na véspera**. São três avisos diferentes de propósito: quem não quer o lembrete pode desligar só ele nas preferências de notificação, sem perder o convite.

Se a turma tiver vagas e elas acabarem, a matrícula é recusada dizendo **quantas vagas existem e quantas estão ocupadas** — não um "sem vagas" seco que deixa você sem saber se dá para espremer mais uma.

Cancelar a matrícula **libera a vaga**. Matricular a mesma pessoa de novo reaproveita a linha em vez de criar uma segunda, e recomeça os avisos — quem cancelou depois da confirmação recebe a próxima.

**Cancelar a turma retira todo mundo que ainda não foi apurado.** Sem isso, um treinamento que não aconteceu continuaria aparecendo como "Matriculado" na ficha de cada pessoa, com as vagas ocupadas.

### Registrar a presença

A presença é registrada **em horas, não em sim ou não**. Isso não é preciosismo: certificado depende de carga horária, e quem assistiu metade não pode receber o mesmo que quem assistiu tudo. Digite as horas na linha da pessoa e clique em **Salvar**.

Zero é uma resposta válida e significa **ausente** — diferente de deixar em branco, que significa que a presença ainda não foi apurada.

Mais horas do que o curso dura é recusado. A causa comum disso é um zero a mais digitado, e aceitar seria emitir certificado em cima de um erro de digitação.

### Encerrar a turma

**Encerrar a turma e apurar a presença** é o momento em que o treinamento vira fato. Cada matrícula viva é comparada com a **frequência mínima do curso** — que, quando está em branco no cadastro do curso, é a carga horária inteira:

- **igual ou acima** → concluído, com a data da conclusão, e o treinamento passa a aparecer na **ficha do colaborador**;
- **abaixo, mas com horas** → abaixo do mínimo, sem conclusão e sem certificação;
- **sem horas** → ausente.

Corrigir as horas de alguém **depois** do encerramento reapura aquela matrícula na hora. O resultado antigo não fica de pé.

### A armadilha: a certificação que não foi baixada

Quando o curso concede certificação, o sistema procura, entre as certificações exigidas pelo **cargo vigente da pessoa**, uma com **exatamente aquele nome** — e a comparação é por texto. Achando, grava a nova validade a partir do prazo daquela exigência; não achando, **não baixa nada**.

A coluna **Certificação** diz qual dos casos aconteceu, e é para isso que ela existe:

| O que aparece                                                | O que significa                                                      |
| ------------------------------------------------------------ | -------------------------------------------------------------------- |
| Válida até *(data)*                                          | Baixada; a validade veio do prazo da exigência do cargo              |
| Baixada — não vence                                          | Baixada; aquela exigência não tem prazo                              |
| Nenhuma certificação do cargo tem o nome que o curso concede | **Nada foi baixado.** Confira a grafia dos dois lados                |
| A pessoa não tem cargo vigente                               | **Nada foi baixado.** Não havia conjunto de exigências para comparar |
| Este curso não concede certificação                          | Nada era esperado                                                    |

:::BlockQuote
As duas linhas em destaque ficariam **idênticas** a "não vence" se a tela mostrasse só a data vazia. É assim que um nome digitado com uma letra de diferença vira alguém que acredita estar habilitado.
:::

## Os treinamentos na ficha do colaborador

***

Na ficha de cada pessoa há o bloco **Treinamentos**, com o que ela cursou, quantas horas assistiu, quando concluiu e o que a conclusão rendeu de certificação.

Ele mostra **também** o que não foi concluído. O gestor que pergunta "essa pessoa fez o curso?" é mal servido por uma lista que só responde quando a resposta é sim: "matriculado e ausente" é justamente o fato que ele veio buscar.

O bloco pode ser escondido pelo botão **Personalizar**, como os demais da ficha.

## Teste de conhecimento e pesquisa de satisfação

***

Dois instrumentos acompanham qualquer treinamento sério: o **teste** mede se a pessoa aprendeu, e é o que sustenta a certificação de quem depende dela; a **pesquisa** mede se o treinamento prestou, e é o que permite trocar um instrutor ruim antes da terceira turma.

Na prática os dois raramente acontecem, porque montar cada um dá trabalho e a turma seguinte já está no calendário. É por isso que eles nascem de **modelos**.

:::BlockQuote
**"Gerar automaticamente" aqui é gerar a partir de um modelo, não inteligência artificial escrevendo perguntas.**
:::

### Montar um modelo

**Abra "Modelos de teste e pesquisa"** (/training-assessments). Menu **Recursos Humanos → Modelos de teste e pesquisa**. Escolha se é teste ou pesquisa — a escolha decide tudo o que vem depois:

|                  | Teste de conhecimento          | Pesquisa de satisfação        |
| ---------------- | ------------------------------ | ----------------------------- |
| Tipos de questão | múltipla escolha, dissertativa | escala, dissertativa          |
| Nota mínima      | opcional                       | não se aplica                 |
| Como é lido      | **com nome**, por matrícula    | **só consolidado**, por turma |

Abra o modelo e acrescente as questões.

### A armadilha: questão objetiva sem gabarito

Numa questão de múltipla escolha o sistema exige que você diga **qual alternativa é a correta**. Isso é recusado, não aceito em branco — e a razão é que aceitar seria pior do que parece: a correção rodaria, não acharia com o que comparar, e **todo participante perderia aquele ponto sem um único erro aparecer em lugar nenhum**. Este formulário é o último momento em que alguém está olhando.

Na escala, o topo fica **na questão**, não numa constante do sistema. A base é sempre 1. Alargar a escala depois não muda o que cada resposta já dada significava.

### Gerar para um curso

Na tela do curso, bloco **Teste de conhecimento e pesquisa de satisfação**: escolha o modelo e clique em **Gerar do modelo**.

O que acontece é uma **cópia**: as questões do modelo passam a existir também no curso. Ajustar a cópia depois **não** toca no modelo nem em nenhum outro curso gerado dele — é isso que torna seguro adaptar um curso, e sem isso ninguém confiaria num modelo depois da primeira vez.

:::BlockQuote
**As questões congelam assim que alguém responde.** Editar uma mudaria o que as respostas já gravadas respondiam; acrescentar uma mudaria o denominador de toda nota já dada. Os dois recalculariam em silêncio a nota de gente que já foi embora.
:::

### Responder

**Abra "Meus treinamentos"** (/my-trainings). Menu **Recursos Humanos → Meus treinamentos**. O participante vê apenas as próprias matrículas — a tela não aceita identificador de outra pessoa, e o servidor resolve quem está pedindo pela sessão.

As respostas são gravadas conforme ele preenche. **Enviar** encerra a tentativa: no teste, é o que dispara a correção das objetivas — e depois disso o teste não aceita mais resposta, para que uma questão preenchida atrasada não devolva a nota já gravada para "aguardando". Na pesquisa não há nota a apurar; enviar apenas confirma, e o que foi escrito já entra no consolidado da turma.

### A armadilha: a nota que não sai

No envio, as objetivas são corrigidas na hora. As dissertativas vão para uma pessoa — e, **enquanto alguma estiver esperando correção, o resultado fica retido**, não é calculado com o resto.

Isso é deliberado. Uma prova de dez questões com uma dissertativa por corrigir **não é um 90**: é um resultado que ainda não existe. Publicar o parcial poria na ficha da pessoa um número que ninguém sustenta e — porque nota parcial é idêntica a nota final na tela — ninguém jamais seria lembrado de ir ler o texto.

A tela do participante diz que está esperando. Do lado do RH, na tela da turma, o bloco **Resultados do teste e da pesquisa** lista as dissertativas pendentes com o texto de cada uma e um campo de nota de **0 a 1** — a fração do único ponto daquela questão. Corrigida a última, o resultado sai e vai para a matrícula.

### A nota na matrícula

Fechada a correção, a nota entra na matrícula do participante e aparece na coluna **Nota do teste**, tanto na lista da turma quanto no bloco de treinamentos da ficha. Ela **não** muda o status da matrícula: quem concluiu o treinamento foi decidido pela **presença**, no encerramento da turma, e deixar uma nota digitada depois reverter aquilo retiraria uma certificação retroativamente sem nada na tela dizer por quê. A nota fica ao lado da conclusão, e as telas leem as duas juntas.

:::BlockQuote
**Quem só lê o cadastro não vê gabarito nem nota.** A lista de modelos mostra título, tipo e nota mínima; o **gabarito**, a nota de cada participante e a fila de correção exigem manter o catálogo ou aprovar treinamento. Sem essa separação, o próprio participante — que tem acesso de leitura como todo mundo — abriria o modelo pelo menu e leria a resposta certa.
:::

### A armadilha: a pesquisa com poucos respondentes

A pesquisa de satisfação **nunca** é lida com nome. O que existe é a consolidação por turma — e ela só aparece a partir de **três respondentes**.

Abaixo disso o sistema diz **quantos responderam de quantos são necessários**, em vez de mostrar uma tabela vazia — tabela vazia leria como "ninguém respondeu", que é outra coisa. Não é excesso de zelo: com um respondente, "a média" **é** a resposta daquela pessoa sem o nome; com dois, duas pessoas que sentaram na mesma sala conseguem cada uma subtrair a própria e ler a da outra.

O mesmo piso vale **por questão** no texto livre: se todo mundo deu nota na escala e uma pessoa só escreveu o comentário, o comentário não aparece — sozinho, ele identifica quem escreveu tanto quanto uma média de um.

A consolidação fica no bloco **Resultados do teste e da pesquisa**, na tela da turma.

## O plano anual de desenvolvimento

***

**Abra "Planos de desenvolvimento"** (/development-plans). Menu **Recursos Humanos → Planos de desenvolvimento**.

O sistema permite "registrar um plano de treinamento". Lido sem contexto, isso sugere um campo de texto. Num órgão público o plano tem nome, forma e prazo: é o **Plano de Desenvolvimento de Pessoas**, entregue todo ano a um órgão central, com data-limite.

### A armadilha: o ano do plano não é o ano da entrega

O ano que você informa é o ano em que as **ações acontecem**. A entrega é no ano **anterior**:

:::BlockQuote
**IN SGP-ENAP/SEDGG/ME nº 21/2021, art. 3º** — o PDP é elaborado anualmente com as ações "a serem executadas **no ano seguinte ao do planejamento**".**Art. 6º** — enviado ao órgão central do SIPEC "**até o dia 30 de setembro de cada ano civil**, ou no dia útil subsequente".
:::

Ou seja: o plano de **2027** vence em **30/09/2026**. A tela mostra a data calculada para o ano que você escolher, justamente para ninguém precisar fazer essa conta de cabeça.

### O prazo é do seu órgão

30 de setembro é o padrão **federal** e vale para os órgãos do SIPEC. Estado e município têm normativo próprio — por isso o dia e o mês são configuráveis na própria tela, por quem tem a alçada de escrever o plano.

:::BlockQuote
**Mudar o prazo vale daqui para a frente.** Plano já aberto mantém o prazo sob o qual foi aberto — senão um plano entregue no prazo viraria "atrasado" porque alguém editou uma configuração meses depois.
:::

### As lacunas medidas

No plano, o bloco **Lacunas de competência medidas** cruza o que o cargo exige com o que a avaliação de desempenho encontrou, no período que você informar. Cada lacuna traz quantas pessoas estão abaixo, a distância média e os cursos do catálogo que a desenvolvem.

Aceitar uma lacuna cria uma linha do plano que **carrega a competência que a originou**. É isso que separa um plano de uma lista digitada — e é o que permite, depois, responder "por que este curso está aqui".

### A armadilha: lista vazia não é a mesma coisa que sem base

Quando não há o que sugerir, a tela **diz por quê**, e são três respostas diferentes:

| O que aparece                                   | O que significa                                                                      |
| ----------------------------------------------- | ------------------------------------------------------------------------------------ |
| Nenhum ciclo de avaliação terminou nesta janela | Não há medição. **No primeiro ano de uso, é a resposta certa** — monte o plano à mão |
| Ciclos terminaram, mas nada foi pontuado        | Os ciclos existiram e não produziram medição                                         |
| Todo mundo atingiu o que o cargo exige          | **Isso é um achado**, não uma ausência                                               |

Uma tabela vazia diria as três de uma vez, e leria como se a função estivesse quebrada.

### Entregar

**Entregar o plano** registra a data e — se passou do prazo — marca o atraso. O sistema **aceita**: plano atrasado vale mais que plano nenhum, e bloquear levaria alguém a antedatar, trocando um atraso visível por uma data falsa.

O que ele **recusa** é plano **sem nenhuma linha**: isso não diz nada ao órgão parecendo cumprimento.

## Solicitação de treinamento

***

**Abra "Solicitações de treinamento"** (/training-requests). Menu **Recursos Humanos → Solicitações de treinamento**.

É o caminho de quem quer algo que o plano não previu. O colaborador pede para si mesmo em **Meus treinamentos**; o gestor pede para alguém da equipe aqui. A solicitação pode nomear um curso do catálogo **ou só descrever o que precisa** — o pedido útil costuma ser exatamente de treinamento que o catálogo ainda não tem.

A justificativa é obrigatória. Sem ela, quem decide não tem em cima de que decidir, e o pedido volta a ser resolvido por quem fala mais alto.

### A armadilha: aprovar sem plano aberto

Aprovar **escreve uma linha no plano** que você escolher — e só um plano ainda em elaboração aceita. Se não houver nenhum, o botão não faz nada e a tela avisa.

Isso é de propósito: um "sim" que não pousa em lugar nenhum é um sim que ninguém executa, e quem pediu só descobre no fim do ano — o que, do lugar dele, é igual a ter sido ignorado.

Solicitação recusada **continua na lista**, com a decisão. Quem pediu tem direito de ver que foi respondido, e o plano do ano seguinte se escreve melhor contra o que foi recusado do que contra o silêncio. O botão **Histórico** mostra quem decidiu e quando.

[title] Relatórios e dashboards
[path] Aplicações/Agility/Relatórios e metas/

:::BlockQuote
Leia o consolidado do Workspace e o dashboard de um quadro para acompanhar desempenho, custos, releases, capacidade de PI e desvios.
:::

:::hint{type="info"}
**Pré-requisito:&#x20;**&#x54;enha acesso ao Workspace e, para o dashboard, a um projeto com quadro acessível. O consolidado usa as fontes disponíveis de desempenho, financeiro, releases e capacidade de PI; uma fonte indisponível não transforma os outros indicadores em zero.
:::

***

A tela Relatórios do Workspace é a visão de consolidação para quem precisa comparar a operação sem abrir projeto por projeto. Ela reúne a seção Desempenho e financeiro, a lista de Releases e DevOps e a capacidade dos PIs dos ARTs. Os números são acompanhados do estado da fonte; assim, fica explícito quando um dado está disponível ou quando depende de uma integração que não respondeu.

O Dashboard do quadro é a visão operacional de um único projeto/board. Ele mostra o progresso das tarefas, receita, custo e margem, compara custo previsto e realizado e detalha a execução por Time e por responsável. Quando o custo realizado ultrapassa o previsto, o cartão marca Desvio e explica a causa, o período e o limiar que disparou o alerta.

***

### Passo a passo

::::WorkflowBlock
:::WorkflowBlockItem
**Abrir os relatórios do Workspace**

Dentro do Workspace, abra Relatórios. Aguarde o carregamento das fontes de Workspace e de relatório. A página começa pela seção Desempenho e financeiro; acima dos cartões aparecem os banners de estado de Desempenho por Time e Financeiro. Se uma fonte não estiver disponível, o banner informa isso e o botão de nova tentativa permite recarregar sem esconder os demais fatos.
:::

:::WorkflowBlockItem
**Ler progresso e os totais financeiros**

Na primeira grade, use o cartão Progresso para entender quantas tarefas foram concluídas em relação ao total. Os cartões financeiros mostram Receita, o valor Faturado como complemento, Custo, Margem e Margem %. A margem percentual só é apresentada quando há receita reconhecida; caso contrário, a tela exibe um traço e a observação "sem receita reconhecida", em vez de fabricar um percentual.
:::

:::WorkflowBlockItem
**Comparar custo previsto por projeto**

No cartão "Custos × previsto por projeto", leia cada projeto com as colunas de custo previsto, realizado e variação. Use essa tabela para localizar rapidamente onde o consumo está acima ou abaixo do orçamento. Logo ao lado, "Identificação de desvios" lista apenas os projetos que cruzaram o alerta; se nenhum projeto tiver alerta, a mensagem verde confirma que todos estão dentro do previsto.
:::

:::WorkflowBlockItem
**Analisar rentabilidade e desempenho do Workspace**

Role até "Rentabilidade por projeto" para mudar a lente do total financeiro para a dimensão de cada projeto. Em seguida, confira "Desempenho por Time": a tabela organiza tarefas por Time, separando concluídas, em andamento, a fazer e percentual de conclusão. A tabela "Desempenho por responsável" usa a mesma divisão por estágio, mas identifica cada pessoa do Workspace; tarefas sem responsável aparecem como "Sem responsável".
:::

:::WorkflowBlockItem
**Consultar Releases e DevOps**

Na seção "Releases e DevOps", comece pelos cartões Releases, Em andamento, Entregues no trimestre e Entregues em atraso. O cartão de Releases também informa quantas releases têm produto associado. Abaixo, "Métricas por release" apresenta código/título, situação, frequência de deploy por semana, lead time em dias, CFR (taxa de falha de mudança) e o estado da amostra.
:::

:::WorkflowBlockItem
**Filtrar e abrir uma release**

Use a barra de ferramentas da tabela para pesquisar por código, título, versão, produto ou programa. O filtro de Situação aceita mais de um status, e o filtro Amostra separa métricas Disponíveis de Indisponíveis. Clique no código ou título da release para abrir seus detalhes; quando uma métrica não existe para aquela amostra, o relatório mostra "—" e não interpreta a ausência como zero.
:::

:::WorkflowBlockItem
**Selecionar um ART e seu PI**

Na seção "Capacidade de PI", o cartão "ART e PI selecionados" traz dois seletores pesquisáveis. Escolha o ART e, depois, o PI; por padrão, a tela seleciona o PI atual e, na ausência dele, o primeiro PI disponível. Se o Workspace não tiver ART com PI ou se o ART selecionado ainda não tiver PI, a tela explica qual desses dois dados falta.
:::

:::WorkflowBlockItem
**Interpretar os indicadores de capacidade**

Para o PI selecionado, leia Progresso (percentual e iterações concluídas de um total), Capacidade usada (usada/total), Objetivos (concluídos/total) e Previsibilidade. Quando a fonte detalhada estiver disponível, a tabela seguinte abre por Time e Iteração, com pontos Disponíveis e Alocados. O link Abrir detalhes do PI leva ao planejamento desse intervalo para investigar a origem dos números.
:::

:::WorkflowBlockItem
**Abrir um dashboard de quadro**

Para a visão operacional, abra um projeto, escolha o quadro e entre na aba Dashboard. O cabeçalho identifica o projeto e oferece o atalho Financeiro do quadro. Diferentemente do relatório do Workspace, esta tela consolida somente o board escolhido e funciona tanto para um quadro Kanban quanto para um board usado por Scrum quando a capacidade do projeto permite o dashboard.
:::

:::WorkflowBlockItem
**Conferir progresso, receita, custo e margem**

Na primeira linha, o cartão Progresso apresenta o percentual e a quantidade de tarefas concluídas do board. Os cartões seguintes mostram Receita, o faturado como complemento, Custo e Margem; quando a margem não pode ser calculada porque não há receita reconhecida, o cartão informa essa condição. Use os valores em conjunto: receita é o valor do trabalho, custo é o consumo e margem é a diferença que sobra.
:::

:::WorkflowBlockItem
**Investigar o cartão Custos × previsto**

No cartão "Custos × previsto", compare os campos Previsto, Realizado e Variação. A barra horizontal representa o realizado e marca verticalmente o previsto. Quando a variação é positiva, o cartão exibe a etiqueta Desvio, colore o valor em destaque e apresenta a explicação com causa, período e limiar; o número da variação vem com sinal de mais para tornar o excesso evidente.
:::

:::WorkflowBlockItem
**Ler as tabelas de equipe**

Use "Desempenho por Time" para ver o total de tarefas do Time dono do board, quantas estão concluídas, em andamento ou a fazer e o percentual de conclusão. Depois, em "Desempenho por responsável", repita a leitura por pessoa: a tabela mostra tarefas, concluídas, em andamento, a fazer e uma barra de conclusão. Se uma tarefa não tiver responsável ou Time, ela fica explicitamente agrupada como sem responsável ou sem Time.
:::
::::

:::hint{type="success"}
:FontAwesome[]{icon="fa-solid fa-check"} **Verificação**

- A tela do Workspace exibe separadamente Desempenho e financeiro, Releases e DevOps e Capacidade de PI, com o estado das respectivas fontes.
- Você consegue identificar, por projeto, custo previsto, custo realizado e os desvios sinalizados, sem confundir ausência de dado com valor zero.
- Você filtrou a tabela de releases por situação ou amostra e abriu uma release pelo código/título.
- Você selecionou um ART e PI e encontrou progresso, capacidade, objetivos e previsibilidade, além das linhas de Time e Iteração quando a fonte detalhada estava disponível.
- No dashboard do board, Progresso, custo, margem, desempenho por Time e desempenho por responsável correspondem ao quadro aberto.
- Quando o realizado supera o previsto, a etiqueta Desvio e a mensagem com causa, período e limiar ficam visíveis no cartão de orçamento.
:::

:::hint{type="warning"}
:FontAwesome[]{icon="fa-solid fa-triangle-exclamation"}**&#x20;Erros comuns**

**A tela informa que uma fonte está indisponível**

Não preencha o valor manualmente nem trate o traço como zero. Leia o banner que identifica a fonte, confira se a API ou integração está disponível e use a nova tentativa. Os outros blocos do relatório continuam sendo úteis enquanto aquela fonte não retorna.

**Não há ART ou PI para selecionar**

A capacidade de PI depende de um ART com um PI cadastrado. Cadastre o ART e o intervalo de planejamento nas telas de SAFe antes de voltar ao relatório; com ART sem PI, o relatório mostra "O ART selecionado ainda não possui PI".

**A tabela de releases está vazia**

A mensagem "Nenhuma release neste workspace" significa que não há release para consolidar. Crie uma release na área de Produtos e releases e volte ao relatório; uma release sem amostra DevOps ainda pode aparecer, mas suas métricas serão marcadas como indisponíveis.

**O dashboard não carrega para o projeto**

Verifique se o projeto possui a capacidade de quadro/relatórios habilitada e se o board informado ainda pertence ao projeto. Abra o board pelo projeto, em vez de reutilizar um endereço de outro Workspace; o dashboard carrega o financeiro e o desempenho do board selecionado.

**Não há tarefas atribuídas ou tarefas de Time**

As tabelas informam "Nenhuma tarefa atribuída" ou "Nenhuma tarefa nos Times do escopo" quando não há linhas para aquele agrupamento. Atribua responsáveis e Times nas tarefas e atualize a tela; não use o total do Workspace para inferir o desempenho de um board específico.
:::


[title] 1. O que é a plataforma
[path] Aplicações/GRCS/

*As peças da plataforma inteira, como elas se encaixam e as regras de que ela não abre mão.*

Um GRC responde a três perguntas, nesta ordem:

1.     **Estamos fazendo o que deveríamos?** — a auditoria pergunta e alguém responde.

2.     **O que não está de pé?** — a resposta insuficiente vira uma não conformidade.

3.     **Quanto isso nos custa?** — a não conformidade alimenta um risco.

Tudo o mais existe para sustentar essas três: a estrutura que diz quem responde, o catálogo que diz o que se pergunta, os painéis que mostram o resultado, e os módulos que trabalham com ele — o acervo de documentos, o IMR, a automação, o atendimento e a IA.

***

### <font color="#15803D">A ideia que economiza mais trabalho</font>

Uma pergunta não pertence a uma norma. Ela pertence a um **controle interno**, e o controle é que responde a várias normas ao mesmo tempo.

:::hint{type="info"}
"Existe MFA no acesso administrativo?" é uma pergunta só. Ela alimenta o NIST CSF, a ISO 27001, o CIS, a IEC 62443 e a LGPD de uma vez. Quem responde, responde uma vez; quem audita, colhe cinco aderências.
:::

É por isso que o catálogo tem **controles no meio**, entre a norma e a pergunta. Sem eles, a mesma pergunta existiria copiada em cada framework e envelheceria diferente em cada cópia.

***

### <font color="#15803D">As peças, na ordem em que se usam</font>

A plataforma se aprende na ordem em que se monta: primeiro o que **prepara** a auditoria, depois a **auditoria** e o **tratamento** do que ela achou, e só então os **módulos** que vivem desse resultado. O manual segue essa ordem, e o capítulo *Como usar (de ponta a ponta)* a percorre passo a passo.

| **Peça**           | **O que ela responde**                                                                                              | **Onde fica no menu**                                            |
| ------------------ | ------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| **Estrutura**      | quem responde, quem aprova, quem pode o quê                                                                         | Administração ▸ Áreas e grupos, Usuários, Perfis de acesso       |
| **Alvos**          | o que é auditado — contrato, serviço, área, fornecedor, a própria empresa — e como o resultado sobe pela hierarquia | Configuração ▸ Alvos e dimensões                                 |
| **Catálogo**       | o que se pergunta: frameworks de fábrica, framework próprio, perguntas, pesos, temas, listas e agrupamentos         | Catálogo                                                         |
| **Auditoria**      | o ciclo: abrir, despachar em ondas, responder, revisar, apurar e fechar                                             | Auditoria ▸ Auditorias, Responder auditoria, Painel do framework |
| **Tratamento**     | o que fazer com o que foi achado: não conformidade, plano de ação, risco, oportunidade, continuidade                | Tratamento                                                       |
| **Acervo**         | as políticas e os procedimentos, com versão, aprovação e leitura obrigatória                                        | Acervo                                                           |
| **Análise**        | o resultado em número: painéis, murais de TV, resultado por hierarquia, dimensões e exportação                      | Análise                                                          |
| **IMR**            | o valor a faturar de um contrato do Governo Federal, com nexo auditável — só onde o módulo está ligado              | IMR                                                              |
| **Automação**      | o que roda sem ninguém clicar: conectores, inspeções, regras, avisos e destinos                                     | Automação                                                        |
| **Casos e portal** | o atendimento: o que se pode pedir, o prazo prometido e a fila de quem atende                                       | Tratamento ▸ Casos e vizinhos; /portal                           |
| **IA**             | o modelo de linguagem que opina — e nunca decide —, o assistente e o sandbox                                        | Administração ▸ Modelo de linguagem; a faísca do cabeçalho       |
| **Administração**  | diretório, contas de serviço, e-mail, trilha, vocabulário e aparência                                               | Administração, Configuração                                      |



Três leituras atravessam todos os ciclos e respondem o que nenhum ciclo sozinho responde:

| **Onde**                 | **A pergunta que só ela responde**                                     |
| ------------------------ | ---------------------------------------------------------------------- |
| Resultado por hierarquia | onde estão os maiores riscos, descendo da organização até o contrato   |
| Cobertura UCF            | quanto de cada norma o trabalho num assunto já move                    |
| Continuidade             | o que não pode parar, o que avisa antes, e o que aconteceu mesmo assim |

***

### <font color="#15803D">Três endereços, um login</font>

| **Endereço** | **Quem entra**                 | **O que faz**                                                         |
| ------------ | ------------------------------ | --------------------------------------------------------------------- |
| /            | auditor, gestor, administrador | prepara, conduz e trata — tudo o que está no menu                     |
| /responder   | a área ou equipe avaliada      | responde as perguntas que lhe foram despachadas                       |
| /portal      | quem precisa de alguma coisa   | procura na base de conhecimento, abre chamado, lê o que é obrigatório |



Os três usam o mesmo cadastro de pessoas e o mesmo login. Fora deles fica o **console da instalação**, em /console, com credencial própria: é onde se criam e se param os tenants, e ele não é uma tela do produto.

***

### <font color="#15803D">Três regras que a plataforma não abre mão</font>

**Quem responde não revisa.** Autoavaliação sem segunda linha é o ponto fraco clássico de todo GRC, e por isso a segregação está no banco, não só na tela.

**Nenhum achado fica sem saída.** O ciclo não fecha enquanto houver achado sem plano de ação ou sem aceite de risco formal, temporário e aprovado por quem tem autoridade para aceitá-lo.

**Tudo é editável, e tudo fica registrado.** Nenhum registro é travado — nem resposta aprovada, nem achado encerrado. A integridade vem do rastro: quem alterou, quando, de que valor para qual.

***

### <font color="#15803D">Imprimir</font>

Toda tela imprime, pelo botão nas Preferências ou por Ctrl+P. O que sai no papel não é a tela: o menu e os botões saem de cena, a rolagem interna é desfeita — senão sairia só o pedaço visível, e uma tabela de duzentos achados viraria uma folha com doze —, a paleta vai para o claro mesmo no tema escuro, e o rodapé registra quem imprimiu e quando. Folha sem isso não serve de evidência.

Para entregar o registro a quem vai arquivar ou assinar, a impressão não basta: veja *Exportação*.

***

### <font color="#15803D">Acessibilidade</font>

A plataforma segue as diretrizes da WCAG no que depende dela: atalho para saltar o menu e ir ao conteúdo (primeiro Tab de cada tela), anel de foco visível na navegação por teclado, nome acessível em todo botão que é só um ícone, diálogos que prendem o Tab e devolvem o foco ao fechar, e anúncio de carregamento e erro para leitor de tela.

Ela também respeita o que o sistema operacional pede: menos movimento, mais contraste e modo de cores forçadas. Nada disso troca a paleta — reforça a que já existe. O detalhe está em *Acessibilidade*.

As cores dos gráficos são validadas por script para daltonismo, e identidade nunca fica só na cor: toda série com legenda carrega o rótulo junto.

***

### <font color="#15803D">O passo a passo dentro da plataforma</font>

O **Como funciona, de ponta a ponta**, nas Preferências, tem duas formas, e as duas seguem os mesmos passos do capítulo *Como usar*. A lista mostra cada passo com o seu estado real — o que já está feito aparece marcado, e o passo que o seu perfil não alcança não aparece. E o **passo a passo** abre cada tela e fica numa faixa embaixo, com o que fazer ali: a tela continua viva, você mexe nela, e a faixa acompanha.

Ele não bloqueia nem conduz o clique de propósito. Um tour que segura a mão ensina a seguir o tour; o que se quer é ensinar a plataforma, e para isso a tela precisa estar de verdade sob a mão.

[title] 3. Áreas, grupos, usuários e perfis
[path] Aplicações/GRCS/

*A estrutura que responde, as pessoas que entram e o que cada uma pode fazer — o primeiro passo de qualquer instalação.*

É o primeiro passo, porque tudo o que vem depois procura alguém aqui: a pergunta despachada procura o **grupo** que responde, a aprovação procura **quem** aprova, e cada botão procura a **permissão** de quem clica. Sem estrutura, a auditoria abre e não chega a ninguém.

A ordem que funciona:

1.     **Áreas e grupos** — a forma da organização: área › grupos.

2.     **Usuários** — cada pessoa, com um perfil e os grupos dela.

3.     **Perfis de acesso** — só se os de fábrica não servirem.

Quem entra pelo login da empresa (OpenID Connect ou LDAP) chega já autenticado; o que se configura aqui continua valendo — ver *Integração com o diretório*.

***

### <font color="#15803D">Permissão, não cargo</font>

A autorização compara **permissões**, não rótulos. O perfil é um atalho para um conjunto delas, e você pode criar os seus.

| **Perfil**    | **O que faz**                                                   |
| ------------- | --------------------------------------------------------------- |
| Administrador | tudo, inclusive usuários, perfis e estrutura                    |
| Gestor        | abre e fecha ciclo, aceita risco, publica questionário e painel |
| Analista      | responde, revisa, trata achado e monta painel                   |
| Monitoramento | **só lê painel** — existe para uma televisão na parede          |



Vêm de fábrica também perfis de uso específico: **Solicitante**, **Colaborador**, **Qualidade** (gestor do acervo) e os de integração — **Coletor de inspeção**, **Integração de casos** e **Integração do IMR** —, que servem às contas de serviço.

***

### <font color="#15803D">Como cada pessoa chega, e com que perfil</font>

| **Porta**                                           | **Perfil**                                   | **O que faz**                                                                                                                    | **Licença** |
| --------------------------------------------------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| login da empresa (OAuth2/OIDC ou LDAP), sem convite | **Solicitante**                              | portal: abre e acompanha chamados, lê documentos e pergunta à base                                                               | não consome |
| convite por e-mail                                  | **Colaborador** (pré-selecionado no convite) | o do Solicitante, mais a análise de aderência e o **/responder**: responde as perguntas despachadas para a área ou a equipe dele | Analista    |
| promoção pelo Gestor ou pelo Administrador          | **Analista**                                 | responde, revisa, trata não conformidade, escreve documento, monta painel                                                        | Analista    |



O Solicitante é o único dos três que não consome licença, e não responde auditoria. O perfil padrão de quem entra pelo login da empresa se troca em **Diretório e identidade**.

***

### <font color="#15803D">Promover um Colaborador a Analista</font>

Em **Auditoria ▸ Colaboradores e analistas** (permissão usuario\:promover, do **Gestor** e do Administrador) aparecem as pessoas com perfil Colaborador ou Analista. **Promover a Analista** e **Voltar a Colaborador** alternam entre os dois, e nada além: a tela não cria usuário, não mexe em grupos e não troca nenhum outro perfil — isso continua em **Administração ▸ Usuários**. Os dois perfis consomem licença de Analista, então a troca não muda a conta de licenças.

**Montar painel é de todos**, menos do perfil de monitoramento. Cada usuário tem exatamente um perfil.

***

### <font color="#15803D">Montar áreas e grupos, e convidar por e-mail</font>

Em **Administração ▸ Áreas e grupos** a tela tem a forma do dado: **área › grupos › pessoas**. A pessoa se vincula ao **grupo**, nunca à área — área sem grupo não recebe onda nenhuma.

1.     Em **Áreas**, clique em **Nova**, preencha **CÓDIGO** e **Nome da área** e clique em **Criar**.

2.     Com a área selecionada, clique em **Novo grupo**, preencha **CÓDIGO** e **Nome do grupo** e **Criar**.

3.     No grupo, clique em **Pessoas**. Em cima aparece quem já está no grupo; o **×** ao lado do nome tira a pessoa. Para pôr alguém, digite ao menos duas letras do nome ou do login no campo **Incluir pessoa**: a busca vai ao servidor e mostra até 20 pessoas que ainda não estão no grupo (as inativas vêm marcadas). Clique no nome para incluir. Cada clique já grava. Se a pessoa não aparecer entre as 20, escreva mais do nome.

4.     Para quem não tem conta, ainda dentro de **Pessoas**, clique em **convidar**, preencha **Nome**, **E-mail**, **Perfil** e, se for o caso, outros **Grupos**, e clique em **Enviar convite**. A tela mostra o link com **copiar link**; na lista, **reenviar** gera um link novo (o anterior deixa de valer) e **cancelar** desfaz o convite pendente.

O lápis do grupo (**Renomear ou mover de área**) renomeia e troca a área — mover leva as pessoas junto. O lápis da área a renomeia. A lixeira apaga; a da área só acende quando ela não tem mais grupos (**Mova ou apague os grupos desta área antes**). O convite não oferece perfis de integração nem o de Monitoramento, e mostra a classe de licença de cada perfil.

Os grupos daqui são os que respondem. O que é **auditado** — o contrato, o serviço, a própria área — se declara em *Alvos e escopo*, e o campo **Representa o cadastro de** liga um ao outro.

***

### <font color="#15803D">Cadastrar um usuário</font>

Em **Administração ▸ Usuários** estão todos que entram na plataforma, com tipo, perfil, contato, grupos e se estão ativos.

1.     Clique em **Novo usuário**.

2.     Preencha **Login** (ex.: maria.souza), **Nome**, **E-mail**, **Telefone** e **Senha (mínimo 10 caracteres)**. O e-mail importa: sem ele o aviso existe na plataforma e nunca vira e-mail.

3.     Em **Tipo**, escolha **Interno** ou **Externo** — o externo enxerga só o que lhe foi despachado.

4.     Em **Perfil — apenas um por usuário**, clique no perfil.

5.     Em **Áreas e grupos — quantos forem necessários**, marque os grupos (é pelo grupo que a onda chega à pessoa).

6.     Clique em **Criar**. O botão só acende com nome, perfil, login e senha.

Para corrigir, use o lápis (**Editar cadastro, perfil e grupos**) e **Salvar**. Login, senha e tipo **não se editam**: o login é o que a trilha registra em cada linha, a senha quem troca é a própria pessoa, e mudar o tipo muda o que ela alcança. Não há exclusão: o interruptor da coluna **Ativo** desativa e reativa (**Desativar** / **Ativar**), e a trilha continua apontando para alguém com nome.

Para quem ainda não tem conta, o caminho mais curto costuma ser o **convite por e-mail**, em Áreas e grupos (acima): a pessoa define a própria senha e entra já no grupo.

***

### <font color="#15803D">Vincular uma pessoa a uma equipe</font>

O vínculo existe nos dois sentidos, porque quem administra pensa dos dois jeitos: às vezes "quem responde por banco de dados?", às vezes "põe o João na Arquitetura".

**Pelo usuário.** Em Administração ▸ Usuários, a coluna de equipes é um botão. Ele abre a lista de equipes agrupada por área, com busca, e cada clique grava. Se a equipe procurada não existir, a busca vazia oferece criá-la dentro de uma área e já vincula a pessoa — em vez de devolver nada, que é indistinguível de não saber usar a tela.

**Pela equipe.** Em Áreas e grupos, abrir um grupo lista quem está nele. Ele não lista todas as pessoas da plataforma, que podem ser milhares: para incluir alguém, o campo **Incluir pessoa** pede ao menos duas letras do nome ou do login e mostra até 20 resultados, só de quem ainda não está no grupo.

**Pelo alvo.** No editor de um alvo que representa uma equipe, como descrito em *Alvos e escopo*.

Uma distinção importa: **trocar equipes não toca o perfil de acesso**. São dois assuntos e dois caminhos. Antes havia um só, que obrigava a reenviar o perfil junto — quem só queria vincular alguém acabava regravando a permissão dele de passagem, e um engano ali não aparece na hora: aparece no dia em que a pessoa alcança o que não devia.

***

### <font color="#15803D">Montar um perfil por tela e por ação</font>

Em **Administração ▸ Perfis de acesso** fica a lista de perfis; clicar num deles mostra as permissões que ele tem. Para criar um:

1.     Clique em **Novo perfil**.

2.     Preencha **Código** (por exemplo AUDITOR-EXTERNO), **Nome** e **Descrição**. Em **Classe de licença**, deixe **Pelas permissões** ou escolha **Auditor**, **Analista** ou **Livre**.

3.     Opcional: em **Começar das permissões de**, escolha um perfil existente para copiar as permissões dele e ajustar a partir daí — o perfil de origem não muda.

4.     Marque as permissões (veja abaixo) e clique em **Criar perfil**. O botão só acende com código, nome e pelo menos uma permissão.

As permissões aparecem **pelo nome, agrupadas por módulo** (Auditorias, Atendimento, Riscos, Acervo de documentos…), cada uma com a descrição e as **telas que ela abre**. Ao lado fica **O que este perfil vê no menu**, com o menu inteiro:

•     quem pensa na **ação** — "ela aprova documento" — marca a ação no módulo;

•     quem pensa na **tela** — "ela precisa ver Riscos" — clica na tela apagada do menu, e a permissão que a abre é marcada;

•     os atalhos **Nenhuma / Só consultar / Todas** valem por módulo;

•     a caixa **Procurar por tela ou ação** filtra a lista (ex.: riscos, aprovar, painel).

Em Auditorias, **Revisar e apurar** (auditoria\:revisar) é de quem aprova ou devolve respostas e apura o ciclo; **Fechar e publicar** (auditoria\:fechar) é de quem fecha, cancela e arquiva o ciclo e elabora ou aprova as versões publicadas. Apurar ficou com quem revisa porque é parte da revisão; fechar é o ato que encerra (veja Auditoria, ondas e respostas).

Para corrigir, selecione o perfil e use o lápis (**Editar nome, descrição e permissões**) e depois **Salvar perfil**; a lixeira remove. O **código não muda** depois de criado — é por ele que o perfil está atribuído aos usuários. Perfis marcados **fábrica** não se editam nem se removem: copie-os num perfil novo. O perfil vale no mesmo instante para quem o tem.

A tela que aparece no menu é a mesma que abre: o menu pede a mesma permissão que o servidor pede para carregar a tela. Perfis de acesso pedem admin\:perfis, Áreas e grupos admin\:estrutura, Modelo de linguagem llm\:administrar, llm\:configurar ou admin\:usuarios, Sandbox llm\:administrar, e o Manual é de todo usuário conectado.

***

### <font color="#15803D">Classe de licença do perfil</font>

Cada perfil mostra a **classe de licença** que consome: **auditor** (abre ou fecha auditoria), **analista** (qualquer trabalho fora do portal) ou **livre** (portal, painéis, leitura do acervo, Pergunte à base e análise de aderência). Sem escolha no perfil, a classe sai das permissões; escolhida, ela vale. O convite mostra a classe ao lado de cada perfil, porque convidar é também ocupar uma licença — quem só abre chamados no portal entra como Solicitante, sem gastar licença; o Colaborador, que responde auditoria, ocupa uma vaga de Analista.

***

### <font color="#15803D">Sessão, trilha e contas de serviço</font>

Por que a sessão expira, a exceção do perfil de monitoramento, a trilha de auditoria e as contas de serviço das integrações estão em *Sessão, trilha e contas de serviço*, no bloco de administração.

[title] 6. Agrupamentos
[path] Aplicações/GRCS/

*Recortar as perguntas de um framework para despachá-las por partes — o último passo do catálogo antes de abrir a auditoria.*

O agrupamento é **catálogo**, e não execução: ele se monta antes de existir auditoria, e é usado depois em dois lugares — na abertura do ciclo (**O que vai a campo**) e na montagem de cada onda. Por isso ele vem aqui, logo depois dos frameworks, e não junto das ondas.

***

### <font color="#15803D">A cadeia, em quatro elos</font>

**Framework → Agrupamento (ou não) → Perguntas → Alvos.**

Tudo começa no framework, e ele **isola**: um agrupamento pertence a um framework e não faz sentido fora dele. Cruzar o recorte de um com as perguntas de outro produz um número que não significa nada, e por isso a plataforma não oferece o cruzamento.

### <font color="#15803D">O que é um agrupamento</font>

O recorte das perguntas de um framework, **para disparar por partes em vez de tudo de uma vez**. Nada além disso — não é eixo de comparação, não é etapa de um fluxo, não é dimensão de análise.

Ele é **opcional**. Sem agrupamento, o questionário inteiro vai para uma área só, que é o caso comum de uma auditoria interna. Com ele, conjuntos diferentes vão para áreas diferentes, ou o mesmo conjunto vai para muitos alvos ao mesmo tempo.

:::hint{type="info"}
**Por que ele existe.** O PPSI tem cerca de 310 medidas. Mandar as 310 de uma vez para 1.304 órgãos é pedir que ninguém responda. O agrupamento é o que permite escolher o recorte pertinente e disparar aquele conjunto, rodada a rodada.
:::

***

### <font color="#15803D">Criar e editar — Catálogo ▸ Agrupamentos</font>

A tela parte do **framework**, e não de uma lista geral, porque é assim que o trabalho começa: ninguém agrupa "perguntas", agrupa "as perguntas do PPSI".

1.     Escolha o **Framework** no alto. O contador diz quantas perguntas ele tem, quantas já estão em algum agrupamento e quantas estão *fora de qualquer recorte*.

2.     **Novo agrupamento** → **Código** e **Nome** → **Criar**. Nasce vazio, marcado *meu*.

3.     Recorte *de fábrica* é somente leitura: **Adotar para editar** cria uma **cópia sua**, editável, e a de fábrica fica intacta.

4.     Clique no cartão para abri-lo. Embaixo aparece a lista das perguntas do framework que ainda não estão em recorte nenhum; a busca *procurar pergunta do framework para trazer…* só estreita. Marque as que quer → **Trazer N perguntas**. A caixa *mostrar também as N que já estão em outro recorte* libera a mesma pergunta em dois agrupamentos.

5.     O **×** na pergunta a tira do agrupamento; a lixeira do cartão exclui o recorte — as perguntas continuam no framework, e a exclusão é recusada se alguma onda já usou o agrupamento.

Criar, adotar e editar exigem catalogo\:escrever. O agrupamento **não se dispara daqui**: quem decide o que vai a campo é quem abre a auditoria, em **Auditorias ▸ Abrir auditoria ▸ O que vai a campo**, ou quem monta a rodada em **Painel do framework ▸ Montar onda**. Pergunta fora de qualquer agrupamento só sai quando vai o questionário inteiro.

***

### <font color="#15803D">Depois do recorte</font>

Com o framework escolhido e, se for o caso, recortado, o catálogo está pronto. O passo seguinte é abrir a auditoria — ver *Auditoria, ondas e respostas*. Despachar os agrupamentos para muitos alvos de uma vez, e acompanhar o que voltou, está em *Disparo em escala e painel do framework*.

[title] B.I
[path] Aplicações/


[title] SAFe — Backlog e execução
[path] Aplicações/Agility/


[title] Frota e Notificações
[path] Aplicações/ERP/Manual do Usuário/

# Frota e Notificações

:::BlockQuote
Pré-requisitos: [Cadastros gerais (parceiros e produtos)](docId:6xpQsdWQ2NTyI40BFqDS-) (parceiros fornecedores de combustível e manutenção; parceiros proprietários dos veículos) e [Financeiro — títulos (contas a pagar e a receber)](docId\:D4kuGidayU2GQ-hMhF_T-) (centros de custo que recebem o custo da frota).
:::

## Introdução

***

Esta página cobre dois assuntos independentes, mas ambos operacionalmente úteis no dia a dia. O primeiro é o **módulo de Frota**: onde o gestor cadastra os veículos da empresa (ou dos parceiros transportadores) e seus motoristas, planeja a manutenção preventiva, abre ordens de serviço, registra abastecimentos e o consumo, controla os pneus, lança multas e tributos (como o *IPVA*) e, ao final, consulta o **custo total consolidado de cada veículo**. É o painel de quem responde pela frota e precisa saber quanto cada placa está custando e quando o próximo serviço vence.

O segundo é o **sistema de notificações**: o sino no topo do portal que avisa o operador de eventos importantes (uma NF-e rejeitada, uma conta vencendo, um recebimento conferido), mais as telas de administração da plataforma — preferências de quem recebe o quê, modelos de mensagem por idioma e a fila de falhas de envio de e-mail. As notificações são **disparadas automaticamente por eventos do sistema** (não existe um botão "enviar agora" avulso); o operador as consome e o administrador as configura.

## Passo a passo

***

### Cadastrar motorista

O motorista é a pessoa habilitada que dirige um veículo da frota. Cadastrá-lo antes do veículo permite vincular responsáveis a abastecimentos, ordens de serviço e multas.

1. **Abra "Frota → Motoristas"** no menu lateral. A lista mostra cada motorista com a CNH, a validade e o parceiro vinculado, sinalizando as habilitações a vencer.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/136-drivers.png" alt caption width="3200" height="2000"}
2. **Clique em "Novo"** e preencha:
   - **Nome** do motorista.
   - **Número da CNH** e sua **validade** (o sistema alerta quando a habilitação está perto de vencer).
   - **Parceiro vinculado** — o motorista pode ser funcionário próprio ou de um parceiro transportador cadastrado (ex.: Fornecedor Exemplo Ltda).
3. **Salve.** O motorista passa a aparecer na lista e fica disponível para ser atribuído a veículos, multas e ordens de serviço.

### Cadastrar veículo

O veículo é a placa que a empresa controla — próprio ou de parceiro. É a entidade central da frota: abastecimentos, manutenções, pneus e multas se penduram nele.

1. **Abra "Frota → Veículos".** A lista mostra cada veículo com placa e odômetro atual.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/135-vehicles.png" alt caption width="3200" height="2000"}
2. **Clique em "Novo"** e preencha:
   - **Placa**, **RENAVAM** e **chassi**.
   - **Marca, modelo e ano**.
   - **Tipo** — carro, caminhão, cavalo mecânico, carreta, máquina ou outro. É uma lista fechada: informar um tipo fora dessa lista é recusado pelo sistema (mensagem de dado inválido).
   - **Tipo de combustível** — gasolina, etanol, diesel, flex ou GNV.
   - **Odômetro inicial** (KM atual do painel no momento do cadastro).
   - **Parceiro proprietário** — a própria empresa ACME Servicos Ltda ou um parceiro transportador.
   - **Centro de custo** vinculado, para onde os custos do veículo serão apropriados.
3. **Salve.** O veículo fica disponível para registro de abastecimento, manutenção, pneus e multas.

### Planejar a manutenção preventiva

O plano de manutenção define quando cada tipo de serviço deve ocorrer — por quilometragem rodada ou por tempo decorrido — para que o sistema projete os próximos serviços e antecipe a abertura da ordem.

1. **Abra "Frota → Planos de manutenção".** A lista mostra os planos preventivos por veículo, com a periodicidade (km/tempo) e os próximos serviços projetados.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/137-maintenance-plans.png" alt caption width="3200" height="2000"}
2. **Clique em "Novo"** e preencha:
   - **Veículo** ao qual o plano se aplica.
   - **Tipo de serviço** (troca de óleo, revisão, alinhamento, etc.).
   - **Periodicidade** — a cada N quilômetros **ou** a cada N meses (o que vencer primeiro).
3. **Salve.** O sistema passa a **projetar o próximo serviço** com base no odômetro atual do veículo e na periodicidade definida, exibindo-o na lista de planos.

**Franquia, excedente e recorrência do contrato**

A periodicidade acima diz **quando** um serviço vence. O bloco **"Franquia e excedente (contrato)"**, no mesmo formulário do passo 8, diz **quantos** já estão pagos e **quanto custa** cada um além disso — é o que transforma um plano preventivo em um contrato de manutenção recorrente:

- **Serviços incluídos por janela** — quantos serviços o contrato já cobre. Em branco = o plano não vende franquia e se comporta como sempre.
- **Janela (meses)** — de quanto em quanto tempo os serviços incluídos voltam a zerar. Em branco = nunca zeram.
- **Preço do excedente por serviço** — quanto o cliente paga por cada serviço além da franquia.
- **Categoria financeira do excedente** — onde entra a receita do excedente.
- **Cliente do contrato** — o parceiro que será cobrado.

**Preencha a categoria financeira do excedente.** Sem ela a ordem gerada além da franquia nasce faturável, com cliente e com preço, mas o **fechamento é recusado**: o título a receber não tem onde entrar, e a ordem de serviço não tem tela de edição para informar a categoria depois. A mensagem de recusa aponta os dois lugares onde a categoria pode ser informada — no **plano** (quando a OS veio de um plano) ou na **própria OS** (quando ela foi aberta avulsa).

**Para um plano já criado**, abra "Frota → Planos de manutenção", clique no plano e use o cartão **"Editar termos do contrato"** no fim da ficha. É por ali que um plano antigo — cadastrado antes de o contrato existir — ganha franquia, preço de excedente e categoria financeira. O cartão só aparece para quem tem permissão de gerir a frota.

### Abrir e fechar ordem de serviço

A ordem de serviço (OS) é o registro concreto de uma manutenção executada — preventiva (a partir de um plano) ou corretiva. Ao fechar a OS, o custo dos serviços e das peças é apropriado ao ativo mantido.

1. **Abra "Frota → Ordens de serviço".** A lista mostra as OS com o **alvo da manutenção**, tipo, situação (aberta/fechada) e custo. O alvo é a **placa** quando a OS é de veículo e o **nome do ativo** quando é de máquina, equipamento, balança ou instalação.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/138-work-orders.png" alt caption width="3200" height="2000"}
2.

Só aparecem na lista os **planos de serviço ativos** — um plano desativado não recebe OS nova.

**Clique em "Novo"** para abrir a OS. Preencha:

:::Paragraph{listStyleType="disc" indent="2"}
**Alvo da manutenção** — escolha **Veículo** ou **Ativo (plano de serviço)**. Conforme a escolha, o campo seguinte pede a **placa** ou o **plano de serviço do ativo**. Uma OS atende a um **ou** ao outro, nunca aos dois: o mesmo custo apropriado nos dois lugares apareceria duas vezes nos relatórios, então o sistema recusa a combinação.
:::

:::Paragraph{listStyleType="disc" indent="2"}
Quando for preventiva de veículo, o **plano de manutenção** de origem.
:::

:::Paragraph{listStyleType="disc" indent="2"}
**Tipo** — preventiva ou corretiva. É pelo tipo **corretiva** que o ativo entra no cálculo de MTBF/MTTR (passo 57): uma OS preventiva é serviço programado, não falha.
:::

:::Paragraph{listStyleType="disc" indent="2"}
**Fornecedor** responsável pelo serviço (ex.: Fornecedor Exemplo Ltda).
:::

:::Paragraph{listStyleType="disc" indent="2"}
**Peças trocadas** e **serviços executados**, cada item com seu valor.
:::

1. **Feche a OS.** Ao concluir, a OS passa à situação **fechada** e o **custo total é apropriado ao alvo**: ao veículo, alimentando o painel de custo (passo 25), ou ao ativo, alimentando o **custo total de manutenção** exibido na ficha do plano de serviço.

### Registrar abastecimento e acompanhar o consumo

O abastecimento registra litros, valor e odômetro de cada parada no posto. Com dois abastecimentos de tanque cheio, o sistema calcula o consumo médio (km/L) do veículo.

1. **Abra "Frota → Abastecimentos".** A lista mostra cada abastecimento com veículo, data, litros, odômetro e o consumo calculado.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/140-refuelings.png" alt caption width="3200" height="2000"}
2. **Clique em "Novo"** e preencha:
   - **Veículo** + **data** + **odômetro (KM atual)**.
   - **Posto fornecedor** — parceiro fornecedor cadastrado.
   - **Litros**, **valor unitário** e **valor total**.
   - **Tanque cheio?** — marque quando encheu o tanque; o cálculo de km/L só é feito **entre dois abastecimentos de tanque cheio**.
3. **Salve.** A partir do segundo abastecimento de tanque cheio, o sistema calcula o **consumo médio (km/L)** com base na distância percorrida entre os dois odômetros e nos litros consumidos.

### Controlar os pneus

O controle de pneus acompanha o ciclo de vida de cada pneu: montagem em uma posição/eixo do veículo, rodízio, recapagem e sucateamento — com histórico por eixo.

1. **Abra "Frota → Pneus".** A lista mostra cada pneu com o veículo, a posição (eixo) e a etapa do ciclo de vida.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/139-tires.png" alt caption width="3200" height="2000"}
2. **Clique em "Novo"** para cadastrar um pneu e registrar suas movimentações:
   - **Montagem** — vincula o pneu a um veículo e a uma **posição/eixo**.
   - **Rodízio (troca de posição)** — move o pneu para outra posição do mesmo veículo.
   - **Recapagem** — registra o reprocessamento do pneu.
   - **Sucateamento** — encerra o ciclo de vida do pneu.
3. **Salve cada movimentação.** O pneu mantém o **histórico por eixo**, permitindo saber onde cada pneu esteve e em que etapa está.

### Registrar multas de trânsito

A multa registra uma infração associada a um veículo e ao motorista responsável, gerando o ônus financeiro para o responsável.

1. **Abra "Frota → Multas".** A lista mostra as infrações com veículo, motorista responsável, data e valor.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/141-traffic-fines.png" alt caption width="3200" height="2000"}
2. **Clique em "Novo"** e preencha:
   - **Veículo** e **data da infração**.
   - **Motorista responsável** (para atribuir o ônus).
   - **Descrição / código da infração**, **pontuação** e **valor** (ex.: R$ 1.250,00).
3. **Salve.** A multa entra na lista e o valor passa a compor o custo do veículo e o ônus do motorista responsável. Quando há **prazo de indicação de condutor**, o sistema avisa o gestor antes de o prazo terminar, para que a multa e os pontos não fiquem com a empresa.

### Registrar tributos do veículo (IPVA e taxas)

Esta tela concentra os tributos e taxas anuais do veículo — IPVA, licenciamento, seguro obrigatório — para que entrem no custo consolidado da placa.

1. **Abra "Frota → IPVA / Taxas".** A tela traz o formulário de cadastro de tributo e, abaixo, a lista dos tributos lançados por veículo e exercício; no ambiente de demonstração a lista aparece vazia até você cadastrar o primeiro tributo.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/143-vehicle-taxes.png" alt caption width="3200" height="2000"}
2. **Clique em "Novo"** e preencha:
   - **Veículo** e **exercício** (ano).
   - **Tipo de tributo** — IPVA, licenciamento, seguro obrigatório.
   - **Valor** e **vencimento**.
3. **Salve.** O tributo fica lançado, o sistema gera a **conta a pagar** correspondente (ver *04 — Financeiro – documentos*) e o valor passa a compor o custo total do veículo (passo 25).

### Consultar o custo total do veículo

O painel de custo consolida, por veículo, tudo o que foi lançado nos passos anteriores: manutenção (ordens de serviço), combustível (abastecimentos), multas e tributos.

1. **Abra "Frota → Custo de veículo".** O painel exibe o **custo total consolidado por veículo**, somando manutenção, combustível, multas e tributos.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/142-vehicle-cost.png" alt caption width="3200" height="2000"}
2. **Analise por veículo.** Use o painel para comparar placas, identificar a que mais custa e decidir sobre renovação ou baixa da frota.

### Acompanhar as notificações in-app (sino)

O sino no topo do portal é o canal in-app: ele avisa o operador dos eventos que o sistema gera automaticamente (recebimento conferido, NF-e rejeitada, conta vencendo, carta de cobrança emitida).

1. **Localize o sino** no canto superior direito do portal, ao lado do avatar. Um contador mostra quantas notificações **não lidas** existem.
2. **Clique no sino.** Abre a lista das notificações in-app mais recentes, cada uma referente a um evento de negócio (ex.: aviso de recebimento ao conferente, *NF-e* rejeitada, conta a vencer).
3. **Abra uma notificação** clicando nela: o portal leva ao documento relacionado e a notificação **sai do contador de não lidas**, permanecendo no histórico.
4. **Marque todas como lidas** pelo botão no topo da lista quando quiser zerar o contador de uma vez.

### Configurar preferências de notificação

As preferências definem, por tipo de evento e por canal (in-app ou e-mail), o que cada usuário deseja receber. Desativar um tipo/canal (opt-out) faz o sistema deixar de notificar aquele evento por aquele canal.

1. **Abra "Notificações → Preferências"** no menu lateral. A tela lista os tipos de evento e os canais disponíveis, com o estado ativo/inativo de cada combinação.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/011-notification-preferences.png" alt caption width="3200" height="2000"}
2. **Desative um tipo/canal** (opt-out) e **salve**. Ao reabrir a tela, a preferência persiste; a partir daí, um novo evento daquele tipo/canal **não gera notificação** para você.

**Procurar um aviso que o sino já não mostra**

**O sino é uma janela, não a caixa de entrada.** Ele carrega as mais recentes e só. As rotinas periódicas — os avisos de manutenção e de OS em atraso rodam a cada 30 minutos — produzem várias notificações por hora para cada usuário, então um alerta **diário** afunda para fora do sino **no mesmo dia em que é emitido**. O caso clássico é o alerta de reposição de estoque, que sai às 7h: quem procurar por ele no sino à tarde não o encontra, e é fácil concluir que o aviso nunca foi enviado.

**Abra "Notificações"** no menu (ou o link "Ver todas as notificações" no rodapé do sino). A tela lista **tudo** o que você recebeu, com:

- **paginação**, para chegar às notificações antigas;
- **filtro por tipo** — é por aqui que você acha o alerta de reposição sem rolar meses de avisos de frota;
- **filtro por situação** (enviada / lida);
- **busca por texto**, que procura no título **e** no corpo da mensagem — útil porque o operador costuma lembrar o que a mensagem dizia, não o título dela.

Antes de concluir que um aviso importante não chegou, **filtre por tipo nesta tela**. Se ele não estiver aqui, aí sim ele não foi emitido — e o caminho passa a ser conferir a configuração do evento em "Notificações → Preferências" e o modelo em "Administração → Modelos de notificação".

### Administrar os modelos de notificação

Os modelos definem o texto que cada notificação exibe, em cada idioma. Ajustar um modelo muda a mensagem para todos os disparos futuros daquele evento. Esta tela é de administração da plataforma.

1. **Abra "Administração → Modelos de notificação".** A lista mostra os modelos por evento e por idioma (pt\_BR, en, es).:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/009-notification-templates.png" alt caption width="3200" height="2000"}
2. **Abra um modelo e edite** o assunto/corpo do idioma desejado; **salve**. A mudança passa a valer para os próximos disparos. Esta tela é acessível apenas a quem tem o papel de administrador da plataforma.

### Conferir as falhas de entrega de e-mail

Quando o canal de e-mail é usado, um envio pode falhar (endereço inexistente, indisponibilidade do provedor). Esta tela de administração lista essas falhas para acompanhamento.

1. **Abra "Administração → Falhas de envio".** A tela lista as tentativas de e-mail que não foram entregues, com o motivo. No caminho feliz, a fila fica **sem falhas pendentes**.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/010-notification-delivery-failures.png" alt caption width="3200" height="2000"}

### Planos de lubrificação, calibração e afiação (por ativo)

Além dos planos de manutenção do veículo, o sistema mantém planos de serviço por ativo — máquina, equipamento, balança, instalação ou veículo — para lubrificação, calibração, afiação e manutenção preditiva.

1. **Abra "Frota → Lubrificação e calibração".** A lista mostra os planos por tipo (lubrificação, calibração, afiação, preditivo), com o ativo e a periodicidade. O card **"Mapa de manutenção"** consolida os planos por ativo com o próximo vencimento, a última execução e a situação (**Vencido**, **A vencer** ou **Em dia**), ordenados pelo mais urgente.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/146-fleet-maintenance-map.png" alt caption width="3200" height="2000"}
2. **Preencha o formulário:** escolha o **tipo de plano** (lubrificação, calibração, afiação ou preditivo) e o **tipo de ativo** (máquina, equipamento, balança, veículo ou instalação); informe o **nome do ativo** e a **especificação** (por exemplo, o tipo de lubrificante ou o padrão de calibração).
3. **Defina o intervalo** — por horas, dias, quilômetros ou quantidade produzida — e as respectivas **tolerâncias**; **salve**.
4. **Abra o plano na lista** para conferir os ciclos e tolerâncias e para **anexar fotos, vídeos ou documentação técnica** ao plano. O card **"Custo total de manutenção"** exibe, em R$, quanto o ativo já consumiu; e o formulário **"Registrar serviço executado"** dá baixa em uma execução informando **Executado em**, **Hodômetro**, **Horímetro** e **Qtd. produzida**.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/147-fleet-plan-cost-execution.png" alt caption width="3200" height="2000"}
5. **Monte o check-list do plano.** Ainda na ficha, o card **"Check-list"** guarda **os serviços de que o plano é feito**, em ordem de execução. Informe a **Ordem** e o **Serviço** e clique em **"Adicionar serviço"**; deixe a Ordem em branco para o item entrar no **fim** da lista. É este check-list que vira **as linhas da ordem de serviço** gerada a partir do plano — o intervalo diz **quando**, o check-list diz **o quê**.
   - **Plano sem check-list gera OS sem linhas.** A ordem é aberta e chega ao mecânico sem nada para seguir. O card avisa isso quando a lista está vazia, em vez de simplesmente não mostrar nada.
   - **A ordem importa.** As linhas saem ordenadas pelo número, não pela data em que você as cadastrou — um check-list lido fora de sequência é outro procedimento. Deixar espaço entre os números (10, 20, 30) facilita encaixar um passo depois.
   - Montar e remover itens exige a permissão de **gerir frota**. Quem não a tem lê o check-list, mas não o altera.
6. **Use o botão de gerar ordem de serviço** para criar a OS diretamente a partir do plano.

### Aprovação, apontamento e serviços de terceiros na OS

A ordem de serviço vai além do abrir/fechar: ela pode exigir aprovação, guardar o agendamento e o apontamento da execução e registrar serviços feitos por terceiros.

1. **Ao abrir a OS ("Frota → Ordens de serviço → Nova OS")**, escolha o **tipo** (preventiva/corretiva), o **tipo de serviço** (classificação), a **data prevista** e o **agendamento** (início e fim previstos).
2. **Marque "Requer aprovação"** quando a OS precisar de liberação. Ela fica na situação **"Pendente de aprovação"** até que um usuário com privilégio de liberação a libere.
3. **Para serviços de terceiros**, selecione a execução **"Terceirizada"**, informe o **fornecedor** e as **referências das notas fiscais** de produtos e de serviços.
4. **Registre as garantias** (do produto, do serviço e geral) com suas datas de validade.
5. **Faça o apontamento** pela lista de OS: **iniciar** o serviço, registrar as **sessões de execução** (data e hora de início e de fim, inclusive quando a tarefa leva vários dias) e **fechar** a OS. As telas são responsivas, acessíveis também em dispositivos móveis.
6. **Aponte os itens consumidos durante a execução** pelo botão **"Itens"** da linha da OS. Escolha o **tipo** — **Material**, **Mão de obra** ou **Deslocamento** —, a descrição, a quantidade e o custo unitário. Para material de estoque, selecione também o **item de estoque**; deixando esse campo em branco, o material é tratado como **não estocado** e segue para compras em vez do almoxarifado. O painel **"Custo por categoria"** da mesma gaveta soma as três categorias separadamente.
7. **Registre os contatos** pelo botão **"Contatos"** da linha da OS: ligações, e-mails, mensagens e visitas trocadas sobre o serviço, com **canal**, **sentido** (recebido/enviado), **quando aconteceu**, com quem foi e um **resumo**. É o registro das interações, complementar ao **histórico** (ícone de relógio), que registra as **mudanças de campo** da OS.
8. **Ao fechar**, os custos são apropriados ao ativo.

:::BlockQuote
**Atenção — o que muda depois de fechar.** Uma OS encerrada ou cancelada não aceita mais **sessões** nem **itens**: a gaveta passa a só consultar. **Contatos continuam sendo aceitos**, de propósito — boa parte da conversa sobre um reparo acontece justamente depois do fechamento (acionamento de garantia, reclamação, retorno). E numa OS **reaberta**, um material **de estoque** é recusado: as peças já saíram do almoxarifado no primeiro fechamento e não sairiam de novo, então a linha ficaria custeada sem nunca ser entregue. Mão de obra e deslocamento continuam permitidos.
:::

### Mapa de manutenção e alertas de vencimento

O mapa consolida, em uma única lista ordenada por urgência, os planos ativos e o próximo serviço projetado de cada ativo — é o mapa de manutenção automático da frota.

1. **Abra "Frota → Mapa de manutenção".** A lista mostra os planos ativos e o próximo serviço projetado, ordenados pela urgência (o que vence primeiro fica no topo).
2. **Acompanhe os vencimentos:** na lista de planos, os ativos que atingiram o intervalo (km, horas ou tempo) aparecem **sinalizados**, antecipando a abertura da ordem de serviço.
3. **Espere o alerta chegar sozinho.** Além do mapa, o sistema varre os planos de hora em hora e **notifica** quem tem a preferência ligada: **"Manutenção vencida"** para o plano de veículo e **"Manutenção de ativo vencida"** para máquina, equipamento, balança ou instalação. A varredura automática julga o **intervalo de tempo (dias)** e a **condição preditiva**, que estão gravados no plano; km, horas e quantidade produzida dependem de uma leitura do medidor no momento e continuam sendo avaliados quando você abre o mapa ou consulta o vencimento do plano.

### Agenda de técnicos e OS em atraso

1. **Abra "Frota → Agenda de técnicos".** A tela mostra as ordens de serviço abertas e agendadas **agrupadas por técnico executor**, servindo de agenda de prestação de serviços por funcionário.
2. **Abra "Frota → OS em atraso".** A tela lista as OS agendadas cuja **data planejada já passou** e que ainda estão abertas — o sistema alerta o atraso na execução dos serviços.

### Garantias a vencer

1. **Abra "Frota → Garantias a vencer".** A tela acompanha as garantias de **produto**, de **serviço** e **geral** que estão próximas do vencimento, separadas por tipo.
2. **Reveja os itens sinalizados:** o sistema destaca as garantias cujo prazo está próximo do fim, para que o produto ou serviço seja reexecutado ainda dentro da garantia.

### Indicadores de manutenção (MTBF/MTTR) e desempenho de técnicos

1. **Abra "Frota → Indicadores de manutenção".** A tela apresenta os indicadores **MTBF** (tempo médio entre falhas) e **MTTR** (tempo médio de reparo), calculados automaticamente a partir das ordens de serviço corretivas. São **duas** tabelas: **"Por veículo"** e **"Por ativo"** — esta última cobre máquina, equipamento, balança e instalação, e só se preenche com OS **corretivas** abertas contra o plano de serviço do ativo (passo 11).
2. **Abra "Frota → Desempenho de técnicos".** A tela apresenta os indicadores de desempenho por técnico de manutenção.
3. **Deixe qualquer uma das duas telas aberta.** No canto superior direito aparece "Atualização automática a cada 30s" e o horário da última leitura, com segundos. As duas telas **se atualizam sozinhas**: não é preciso recarregar a página para ver o efeito de uma OS que acabou de ser fechada — o horário avança e os números acompanham.

### Comparar previsto x realizado

1. **Abra "Frota → Previsto x realizado".** A tela lista as ordens de serviço **já fechadas** e põe lado a lado o que foi prometido e o que aconteceu: **data prevista** contra **data de conclusão**, e **tempo previsto** (janela agendada) contra **tempo realizado** (execução medida).
2. **Leia as duas colunas de desvio.** O desvio de data e o de tempo vêm com sinal: **+4 d** em vermelho é uma OS entregue quatro dias depois do prometido; **-2 d** em azul é adiantamento; **"No prazo"** em verde é desvio zero. A lista já vem ordenada pelo **pior atraso primeiro**.
3. **Trate o traço (—) como "não havia o que comparar".** Uma OS fechada **sem data prevista**, ou sem marcação de início/fim de execução, não tem base de comparação naquele eixo — e por isso mostra traço em vez de zero. Essas linhas ficam **no fim da lista**: contá-las como "no prazo" inflaria artificialmente a pontualidade.

## Verificação

***

Você sabe que funcionou quando:

- **Motorista** e **veículo** aparecem nas respectivas listas; a CNH próxima do vencimento é sinalizada.
- O **plano de manutenção** projeta o próximo serviço com base no odômetro; a **ordem de serviço** fecha e seu custo é apropriado ao veículo.
- O **abastecimento** aparece no histórico com litros, odômetro e custo; o **consumo médio (km/L)** aparece calculado após o segundo abastecimento de tanque cheio.
- O **pneu** fica vinculado ao veículo com histórico por eixo; a **multa** e o **tributo** entram nas listas com seus valores.
- O **painel de custo do veículo** soma manutenção, combustível, multas e tributos numa linha por placa.
- O **sino** mostra o contador correto de não lidas; abrir uma notificação leva ao documento e reduz o contador.
- A **preferência** desativada persiste ao reabrir a tela e o evento correspondente deixa de notificar.
- O **modelo de notificação** editado é salvo; a **fila de falhas de envio** fica vazia no caminho feliz.

## Erros comuns

***

- **Tipo de veículo recusado** — o **Tipo** é uma lista fechada (carro, caminhão, cavalo mecânico, carreta, máquina, outro). Selecionar/enviar um valor fora dessa lista faz o sistema recusar o cadastro com aviso de dado inválido. Escolha um dos tipos previstos.
- **Consumo médio não aparece** — o cálculo de km/L só ocorre **entre dois abastecimentos de tanque cheio**. Se você não marcou "tanque cheio" em ambos, ou só há um abastecimento, o consumo fica em branco. Registre um segundo abastecimento de tanque cheio.
- **"Enviar notificação agora" não existe** — as notificações são disparadas **por eventos do sistema** (recebimento, NF-e, cobrança). Não há envio avulso; se você não vê a notificação esperada, verifique se o evento de negócio de fato ocorreu e se a preferência daquele tipo/canal não está desativada.
- **A OS atrasada não aparece em "Previsto x realizado"** — a tela compara o que foi **executado**, então lê apenas as ordens **fechadas**. Uma OS que estourou o prazo e continua aberta não tem "realizado" para comparar: ela está em **"Ordens de serviço atrasadas"**. As duas telas são complementares, não redundantes.
- **Desvio em branco (—) não é "no prazo"** — o traço quer dizer que faltou o lado **previsto** (a OS foi fechada sem data prevista, ou sem início/fim de execução registrados). Se muitas linhas aparecem com traço, o problema está no **preenchimento da OS**, não no relatório: preencha a data prevista ao abrir e use "Iniciar"/"Concluir" para marcar a execução.
- **Não consigo abrir "Modelos de notificação" nem "Falhas de envio"** — são telas de administração da plataforma, acessíveis apenas a quem tem o papel de administrador. Solicite o acesso ao responsável.


[title] Financeiro — títulos (contas a pagar e a receber)
[path] Aplicações/ERP/Manual do Usuário/

# Financeiro — títulos (contas a pagar e a receber)

:::BlockQuote
Pré-requisitos: [Cadastro fiscal próprio](docId\:Q-zx6Qk4pMFD09yrhmsve), [Cadastros gerais (parceiros e produtos)](docId:6xpQsdWQ2NTyI40BFqDS-) (fornecedores e clientes) e [Financeiro — cadastros de apoio](docId\:yTzjjyyML1B_60VgwDT09) (contas bancárias, categorias financeiras e centros de custo/resultado).
:::

## Introdução

***

A vida financeira da empresa gira em torno de dois fluxos: **o que você precisa pagar** (fornecedores, impostos, salários, aluguel) e **o que você precisa receber** (clientes, comissões, restituições). Esta página cobre o módulo de **Títulos** — em **Financeiro → Títulos** — onde o operador do financeiro lança cada conta, faz a **baixa** (liquidação total ou parcial), registra **juros, multa e descontos**, distribui o valor por **centro de custo** (rateio), compensa **adiantamentos** e passa os títulos de valor alto pela ***alçada* de aprovação**.

Boa parte desses títulos nasce **automaticamente** a partir de notas de entrada ([Compras](docId:3mdo_BH5DDXIp3VIh4ATK)) e pedidos de venda ([Vendas e CRM](docId\:TaINdkXLJcUzyq0xUuGfH)) — o sistema mostra a origem na ficha do título. Aqui você aprende o ciclo completo, incluindo o **lançamento manual**, útil para despesas avulsas, impostos e adiantamentos que não vêm de um pedido.

## Passo a passo

***

### Abrir a lista de títulos

1. **Abra "Títulos".** No menu lateral, clique em **Financeiro → Títulos**. A lista mostra tipo (**A pagar** / **A receber**), parceiro, vencimento, valor, saldo e situação. Quando o valor tem imposto retido na fonte, a coluna de valor mostra três linhas — **Bruto**, **Retido** e **Líquido**.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/023-financial-documents.png" alt caption width="3200" height="2000"}
2. **Localize um título.** Use a busca no topo da lista (por nome do parceiro ou descrição). A situação aparece como uma etiqueta colorida: Aberto, Parcial, Quitado ou Cancelado. Títulos retidos pela alçada exibem ainda um aviso **Aprovação pendente** ao lado da situação.

### Lançar uma conta a pagar manual

1. **Novo título.** Clique em **Novo título** (canto superior direito). Abre o formulário de cadastro.
2.

**Silêncio quer dizer que não há orçamento cobrindo aquela categoria naquela data.** Não é falha: é a ausência de um teto a respeitar.

**Ele funciona mesmo sem preencher "Linha de orçamento".** A busca é pela **categoria**, não pelo empenho — por isso vale para o título comum, que é a maioria.

**O aviso não impede o lançamento.** Ele informa; quem decide é você. O bloqueio, quando o órgão quiser um, é a política de vínculo obrigatório descrita abaixo.

Três coisas que valem entender:

**O aviso de comprometimento do orçamento.** Assim que você escolhe a **Categoria**, informa o **Vencimento** e digita o **Valor**, o sistema procura uma linha de orçamento aprovada que cubra aquela categoria naquela data e, se achar, mostra ali mesmo o **nível de comprometimento** — planejado, comprometido, realizado e disponível. Se o valor que você está lançando passa do disponível, o aviso muda para **alerta**, mostrando quanto sobra e quanto você está lançando.

**Preencha o cabeçalho.** No formulário:

:::Paragraph{listStyleType="disc" indent="2"}
**Tipo** — escolha **A pagar**.
:::

:::Paragraph{listStyleType="disc" indent="2"}
**Parceiro** — busque o fornecedor na lista (ex.: Fornecedor Exemplo Ltda, cadastrado na página [Cadastros gerais (parceiros e produtos)](docId:6xpQsdWQ2NTyI40BFqDS-)).
:::

:::Paragraph{listStyleType="disc" indent="2"}
**Conta de destino** — apenas para contas **a pagar**: escolha a conta bancária do fornecedor para onde o pagamento será roteado (banco 341 — Itaú, ag. 0001, conta 12345-6). Se o fornecedor não tem conta cadastrada, o sistema avisa que o título ficará **sem roteamento** — você pode salvar assim mesmo e roteá-lo depois na tesouraria.
:::

:::Paragraph{listStyleType="disc" indent="2"}
**Categoria** — escolha a categoria financeira / conta de despesa (ex.: 5.1.1.05 — Despesa de aluguel). Ela liga o título ao *plano de contas*.
:::

:::Paragraph{listStyleType="disc" indent="2"}
**Valor** — ex.: R$ 1.250,00.
:::

:::Paragraph{listStyleType="disc" indent="2"}
**Vencimento** — a data em que a conta vence.
:::

:::Paragraph{listStyleType="disc" indent="2"}
**Descrição** — ex.: Aluguel matriz SP — maio/2026.
:::

:::Paragraph{listStyleType="disc" indent="2"}
**Adiantamento** — deixe **desmarcado** para uma conta comum. Marque apenas se este lançamento for um adiantamento a compensar depois (ver adiante).
:::

1. **Salve.** Clique em **Salvar**. O título é criado com situação Aberto e o sistema abre a **ficha** dele.

### Lançar uma conta a receber manual

1.

Observação: o campo **Conta de destino** só aparece para contas **a pagar**; para recebíveis o roteamento de cobrança é tratado na tesouraria ([Tesouraria](docId:75tXS8u8o-8q4dR2arnmw)).

**Novo título — a receber.** Volte a **Financeiro → Títulos**, clique em **Novo título** e, em **Tipo**, escolha **A receber**. A estrutura é a mesma:

:::Paragraph{listStyleType="disc" indent="2"}
**Parceiro** — o cliente (ex.: Cliente Exemplo Ltda).
:::

:::Paragraph{listStyleType="disc" indent="2"}
**Categoria** — ex.: 4.1.1.05 — Outras receitas.
:::

:::Paragraph{listStyleType="disc" indent="2"}
**Valor, vencimento, descrição** — ex.: R$ 1.250,00, vencimento e Comissão sobre indicação — abril/2026.
:::

1. **Salve.** O recebível entra na lista com situação Aberto, amarrado ao cliente e à categoria escolhida.

### Abrir a ficha de um título

1. **Abra a ficha.** Na lista, clique na linha do título (ou no ícone de editar à direita). A ficha reúne o **Resumo** (tipo, parceiro, vencimento, valor, saldo, descrição e origem) e todos os blocos de ação: aprovações, baixa, juros/multa/descontos, rateio, compensação de adiantamento e histórico.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/007-financial-documents-detail.png" alt caption width="3200" height="2000"}

### Aprovar um título retido pela alçada

A *alçada* limita até quanto cada papel pode aprovar. Quando existe uma regra de alçada e o título passa do teto, ele **não fica pagável direto**: entra na fila de aprovação. O cadastro dessas faixas fica em **Financeiro → Alçada de títulos**.

:::BlockQuote
**Não confunda com Administração → Autoridade.** São duas coisas com o mesmo apelido. **Autoridade** ([Administração](docId\:Z8SS7r6Bvhs09rP1SPxUD)) diz *quem pode executar cada operação* do sistema — é permissão. **Alçada de títulos** diz *a partir de qual valor um título precisa de aprovação* — é limite financeiro. Um usuário pode ter a permissão e ainda assim ver o título parar na fila, porque o valor estourou a faixa.
:::

### Cadastrar as faixas de alçada

Em **Financeiro → Alçada de títulos**, cada regra é uma faixa de valor com um cargo aprovador:

- **De / Até** — a faixa em que a regra vale. **Deixe o "Até" em branco** para a regra sem teto, aquela que pega todo valor acima do piso.
- **Cargo aprovador** — quem decide nessa faixa.
- **Ordem de avaliação** — quando duas faixas se sobrepõem, a de **menor** ordem responde. Sem isso, duas regras concorrentes dão resultado imprevisível.
- **Tipo de título** — a pagar ou a receber; a mesma faixa raramente serve aos dois.

**A armadilha, e ela é silenciosa:** um título cujo valor **não cai em faixa nenhuma** é pago **sem aprovação**. Aqui a ausência de regra é permissão, não negativa — o oposto do que a intuição sugere. Se a intenção é que tudo passe por alguém, é preciso existir uma faixa que comece em zero.

Regra errada não se apaga: ela é **desativada** e pode ser **reativada** depois, para o histórico de quem aprovou o quê continuar fazendo sentido.

1. **Verifique a pendência.** Na ficha, o bloco **Aprovações** lista as aprovações do título. Uma aprovação pendente aparece com a etiqueta **Aprovação pendente**. Enquanto ela não for resolvida, o título fica retido.
2. **Aprove ou rejeite.** Um usuário com alçada suficiente clica em **Aprovar** (libera o título) ou **Rejeitar**. Ao aprovar, o título volta a ficar disponível para baixa; se o valor exceder o seu próprio teto, o sistema recusa e mantém a pendência.

### Dar baixa (liquidar) um título

A **baixa** é a liquidação do título — total ou parcial. É o registro de que a conta foi paga (ou recebida). Cada baixa reduz o **saldo** e gera o *lançamento contábil* correspondente.

1. **Abra o bloco "Baixar".** Na ficha, localize o cartão **Baixar**. Ele só aceita baixa enquanto o título está Aberto ou Parcial.
2. **Baixa parcial.** Informe um valor **menor** que o saldo (ex.: R$ 500,00 de um saldo de R$ 1.250,00) e clique em **OK**. O título passa para situação Parcial e o saldo cai para R$ 750,00.
3. **Baixa total.** Informe o **saldo restante** e confirme. O título passa para Quitado e o saldo vai a zero. A partir daí o cartão de baixa fica fechado (mensagem de que o título não está mais aberto para baixa).

### Registrar juros, multa e descontos

Um título pago em atraso pode receber **juros** e **multa**; um título pago adiantado pode receber **desconto**. Esses acréscimos e abatimentos são registrados sem alterar o valor nominal do título.

1. **Abra o bloco "Juros, multa e descontos".** Na ficha, escolha o **Tipo** (Juros, Multa, Outra taxa, Desconto ou Outra dedução), informe o **Valor** e, se quiser, uma **Descrição** (ex.: Atraso 10 dias, multa convencional). Clique em **Registrar**.
2. **Confira o saldo com acréscimos.** O cartão mostra a **soma líquida dos acréscimos** e o **saldo em aberto (com acréscimos)** — é esse saldo ajustado que o operador considera na hora de quitar. Cada acréscimo lançado aparece na lista com etiqueta (verde para descontos/deduções, amarela para juros/multas) e data.

### Ratear o título por centro de custo

O **rateio** distribui o valor do título entre vários *centros de custo*, quando uma despesa é compartilhada (ex.: aluguel dividido entre administração e vendas). A soma dos percentuais tem de fechar em **100%**.

1. **Abra o bloco "Rateio".** Na ficha, cada linha do rateio tem um **centro de custo** e um **percentual**. Escolha o centro (ex.: CC-ADM — Administrativo) e informe o percentual (ex.: 60).
2. **Adicione as demais linhas.** Clique em **+ Adicionar centro** para incluir outra linha (ex.: CC-COM — Comercial com 40). O total aparece em verde quando fecha **100,00%** e em vermelho enquanto não fecha.
3. **Salve o rateio.** O botão **Salvar** só habilita quando o total está correto. O rateio fica gravado no título.

### Compensar e aplicar adiantamentos

Um **adiantamento** é um título marcado com a caixa **Adiantamento** no cadastro. Ele pode ser **compensado** contra outro título do mesmo parceiro e do mesmo tipo (adiantamento a fornecedor abate uma conta a pagar; adiantamento de cliente abate um recebível).

1. **Compensar manualmente.** Na ficha de um título comum (não adiantamento) que esteja Aberto ou Parcial, use o bloco **Compensar adiantamento**: escolha o adiantamento em aberto do mesmo parceiro, informe o **valor** a compensar e clique em **Salvar**. O saldo do título cai pelo valor compensado.
2. **Aplicar adiantamentos automaticamente.** No bloco **Aplicar adiantamentos automaticamente**, clique em **Aplicar agora**. O sistema consome todos os adiantamentos em aberto daquele parceiro, do mais antigo ao mais novo, até zerar o saldo do título — e lista quais adiantamentos foram aplicados e por quanto.

### Ações sobre o título (cancelar, bloquear, prorrogar, endossar)

:::BlockQuote
**O título é um documento com ciclo de vida, não um cadastro editável.** Depois de lançado, o **valor de face nunca muda** e o título **não se edita nem se apaga direto**: ele muda apenas por **ações de ciclo de vida** — baixa, cancelamento, prorrogação, endosso, renegociação. Isso preserva a trilha de auditoria e a integridade contábil. (Quem tentar "corrigir" ou "apagar" o título por fora dessas ações é barrado pelo sistema.)
:::

Enquanto o título está Aberto ou Parcial, o topo da ficha oferece ações de gestão, cada uma em uma janela própria de confirmação:

1. **Cancelar o título.** Um título lançado **por engano** é **cancelado**, não excluído: o topo da ficha oferece **Cancelar título**, que passa a situação para Cancelado. Um título cancelado **não aceita mais baixa**, e o **empenho volta para a dotação** — a obrigação deixou de existir, então o dinheiro reservado para ela é devolvido à linha orçamentária.
   - **O motivo é obrigatório**, ao contrário do bloqueio (onde é opcional). A diferença não é de rigor burocrático: bloquear é uma trava que qualquer um levanta depois; cancelar extingue a obrigação. O motivo fica **na própria ficha**, no resumo do título, e vai para a trilha de auditoria — quem abre um título morto perguntando "por que isto está cancelado?" em geral não tem acesso à trilha.
   - **A ação só aparece para quem tem a permissão "Cancelar título".** Sem ela o botão não é exibido.
   - **Só é possível cancelar um título que ainda não teve baixa** — se já houve baixa (situação Parcial ou Quitado), o cancelamento é recusado; nesse caso o caminho é estornar/renegociar, não cancelar.
   - **Título cancelado junto com uma folha carrega o motivo da folha.** Quando o cancelamento de um lote de folha anula as contas que ele gerou, o motivo informado lá é gravado em **cada** título — assim quem abre o título encontra a explicação sem precisar descobrir de qual lote ele veio.
2. **Bloquear / Desbloquear.** **Bloquear** trava o título contra pagamento (ex.: divergência fiscal — aguardando CFOP); o motivo é opcional. Um título bloqueado exibe a etiqueta **Bloqueado** no resumo. **Desbloquear** o libera novamente para baixa.
3. **Prorrogar vencimento.** **Prorrogar** abre um campo de **nova data de vencimento** — use quando o fornecedor concede mais prazo.
4. **Endossar para outro parceiro.** **Endossar** transfere o título para outro parceiro de destino (ex.: cessão de recebível). Escolha o parceiro na lista e confirme.
5. **Baixar recibo de adiantamento.** Se o título é um adiantamento, o topo da ficha oferece **Baixar recibo** — gera o comprovante impresso do adiantamento (arquivo de texto), com o modelo certo para adiantamento a fornecedor ou de cliente.

### Consultar a conta de destino congelada e o histórico

1. **Conta de destino congelada.** Quando o pagamento é liquidado, o sistema guarda uma **foto** da conta bancária usada (**Conta de destino congelada na baixa**), para que uma alteração posterior do cadastro do parceiro não mude o que já foi pago.
2. **Histórico de alterações.** No fim da ficha, o bloco **Histórico** lista cada mudança do título (criação, edição, baixa) com autor e data. Clique em uma linha para abrir o **detalhe da alteração**, com o comparativo campo a campo (antes e depois).

### Operações em lote e ordens de pagamento (relacionados)

O módulo de Títulos concentra o ciclo por título. Dois módulos vizinhos, no mesmo grupo **Financeiro**, atuam sobre conjuntos de títulos:

1. **Operações de título.** Menu **Financeiro → Operações de título** — reúne operações aplicadas a vários títulos de uma vez.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/054-document-operations.png" alt caption width="3200" height="2000"}
2. **Ordens de pagamento.** Menu **Financeiro → Ordens de pagamento** — agrupa contas a pagar em uma ordem para pagamento em lote (detalhado na página [Tesouraria](docId:75tXS8u8o-8q4dR2arnmw)).:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/055-payment-orders.png" alt caption width="3200" height="2000"}

### Capturar uma conta a pagar pelo código de barras do boleto

Em vez de digitar valor e vencimento à mão, você pode ler o boleto e deixar o sistema preencher os campos.

1. **Abra o campo do boleto.** No formulário de **Novo título** (tipo **A pagar**), localize o campo **Código de barras do boleto**.
2. **Leia o código.** Escaneie com o leitor óptico ou digite a linha digitável e clique em **Ler código de barras**.
3. **Confira o preenchimento.** O sistema decodifica a linha e preenche automaticamente o **valor** e a **data de vencimento**; complete parceiro, categoria e descrição.
4. **Salve.** Clique em **Salvar** para criar a conta a pagar normalmente.

### Classificar o acréscimo em uma natureza contábil própria

Juros, multas e taxas de um título podem ser contabilizados em uma conta contábil separada da despesa principal.

1. **Use o campo Natureza contábil.** No bloco **Juros, multa e descontos** da ficha, além do **Tipo** e do **Valor**, escolha a **Natureza contábil** do acréscimo.
2. **Herde ou especifique.** Deixe em **Igual ao documento** para o acréscimo herdar a categoria do próprio título, ou escolha uma **categoria financeira específica** (ex.: Juros passivos) para que o lançamento contábil do acréscimo aponte para aquela natureza.
3. **Registre.** Clique em **Registrar**; a contabilização passa a usar a natureza escolhida.

### Renegociar, parcelar e consolidar títulos

Títulos em aberto podem ser renegociados (substituídos por novas parcelas, com juros) ou consolidados (agrupados em um só), preservando sempre os originais para a trilha de auditoria.

1. **Abra as renegociações.** No menu **Financeiro → Renegociações**.
2. **Escolha o parceiro.** Selecione o **Parceiro**; o sistema lista os títulos em aberto ou parciais dele.
3. **Escolha o tipo.** **Renegociação** substitui os originais por novas parcelas com juros; **Consolidação** agrupa vários títulos em um único.
4. **Selecione e parametrize.** Marque os títulos que entram na operação e informe **número de parcelas**, **taxa de juros (%)** e **primeira data de vencimento**.
5. **Confirme.** Clique em **Renegociar**. Os títulos originais são preservados (marcados como substituídos) e o sistema gera as novas parcelas, aplicando a taxa de juros automaticamente.
6. **Audite a cadeia.** Na lista de renegociações, clique em **Ver cadeia** para ver quais títulos originais deram origem às novas parcelas.

:::BlockQuote
O mesmo fluxo vale para contas a receber (renegociação e consolidação de recebíveis).
:::

### Adiantamento de viagem

1. No menu **Financeiro → Adiantamentos de viagem** (rota /travel-advances), clique em **Novo adiantamento**.
2. Informe o **colaborador**, o **valor**, o **centro de custo** ao qual a viagem se vincula e a **finalidade/descrição**.
3. Envie para aprovação. Quando o valor ultrapassa a **alçada** do solicitante, a solicitação fica pendente de liberação por um aprovador com teto suficiente.
4. Depois de aprovado, o adiantamento gera o título financeiro correspondente, e o **recibo** pode ser emitido na ficha do título.

### Receber com cartão de crédito/débito descontando a taxa de administração

Quando um recebível é liquidado por **cartão**, a operadora fica com uma **taxa de administração**. O sistema desconta essa taxa no momento da baixa e a registra como **despesa financeira** separada — o valor que efetivamente entra no caixa já é o líquido.

1. **Abra a ficha do recebível.** Em **Financeiro → Títulos**, clique no título **A receber** que será baixado (situação Aberto ou Parcial).
2. **No bloco "Baixar", informe o valor.** No campo **Valor** digite o montante recebido (ex.: R$ 1.000,00).
3. **Escolha a forma de pagamento "Cartão".** No campo **Forma de pagamento**, selecione **Cartão** (as demais opções são Transferência, Dinheiro, Boleto, Cheque e Encontro de contas). Ao escolher **Cartão**, aparece um campo extra **Taxa do cartão**.
4. **Informe a taxa da operadora.** No campo **Taxa do cartão**, digite o valor cobrado pela adquirente (ex.: R$ 25,00). Esse campo só existe para a forma **Cartão** — nas outras formas ele nem aparece.
5. **Confirme a baixa.** Clique em **OK**. O sistema calcula o **líquido creditado** subtraindo a taxa do valor recebido (mais eventuais juros/multa e menos descontos já lançados) e baixa o título por esse líquido.
6. **A taxa vira despesa financeira.** Além do lançamento da baixa, o sistema gera **automaticamente** um lançamento contábil próprio da **taxa de administração como despesa financeira**, sem misturar com a receita do título. Não é preciso lançar a despesa à mão.

:::BlockQuote
Se a taxa informada for maior que tudo o que se recebeu (o líquido ficaria negativo), o sistema recusa a baixa e avisa que a **taxa do cartão excede o valor líquido** — revise o valor da taxa.
:::

### Adiantamento de viagem — solicitar, aprovar e prestar contas

Além do lançamento avulso pela ficha do título, o financeiro tem uma **tela dedicada** de adiantamentos de viagem, com o ciclo completo: pedir, aprovar em quatro olhos e **prestar contas** ao final da viagem.

1. **Abra a tela.** No menu **Financeiro → Adiantamentos de viagem** (rota /travel-advances). A tela reúne três blocos: **enviar solicitação**, **pendentes de aprovação** e **aguardando prestação de contas**.
2. **Preencha a solicitação.** No bloco **Enviar solicitação**, informe:

- **Viajante** — o colaborador que fará a viagem.
- **Centro de custo** — o centro ao qual a viagem se vincula (obrigatório).
- **Projeto** — opcional; escolhido de uma lista de projetos cadastrados.
- **Destino**, **Data inicial**, **Data final** e **Valor** do adiantamento.
- **Finalidade** — o motivo da viagem.

3. **Envie.** Clique em **Enviar**. O sistema confirma "Solicitação enviada — pendente de aprovação" e o pedido passa para o bloco de pendentes.
4. **Aprove ou rejeite (quatro olhos).** No bloco **Pendentes de aprovação**, cada solicitação mostra viajante, destino, período e valor. Um aprovador escreve uma **nota de decisão** (opcional) e clica em **Aprovar** ou **Rejeitar**. A regra dos **quatro olhos** impede que o próprio solicitante aprove o seu pedido — a tela exibe o aviso de que solicitantes não aprovam as próprias solicitações. Quando o valor supera a ***alçada*** de quem tenta liberar, a aprovação é recusada e o pedido continua pendente.
5. **Preste contas ao voltar.** Depois de aprovado, o adiantamento entra no bloco **Aguardando prestação de contas**. Informe o **Gasto real R$** (o que foi de fato gasto), marque **Comprovantes?** se há recibos e, se quiser, escreva uma **nota**. Clique em **Prestar contas**.
6. **Atenção aos comprovantes.** A prestação de contas é obrigatória: a própria tela avisa que, **sem comprovantes**, o valor pode ser tratado como **remuneração tributável** (RIR/2018). Preste contas com os recibos para evitar essa reclassificação.

### Guias de recolhimento de impostos como contas a pagar

Uma guia de recolhimento chega ao sistema por **dois caminhos**, e a diferença muda o que você faz na tela.

**A maioria nasce da nota.** Quando uma nota fiscal de entrada tem **impostos retidos na fonte** (IRRF, CSLL, COFINS, PIS, INSS, ISS), o sistema **gera automaticamente as guias de recolhimento** (DARF, GPS, GARE-ISS ou DAM) e, para cada guia, cria também **uma conta a pagar** dirigida ao órgão beneficiário (Receita Federal, INSS ou prefeitura), já com o **vencimento legal** do tributo. Essas ninguém digita — elas nascem da nota.

**Algumas não têm como nascer daí.** A **GNRE** (Guia Nacional de Recolhimento de Tributos Estaduais) e as taxas impressas por portal de estado ou de prefeitura não vêm de retenção nenhuma: nenhum tributo estadual é retido na fonte numa nota de serviço, então não existe retenção a partir da qual o sistema pudesse gerá-las. Para essas há o **lançamento manual** (passo 61): alguém digita o **código de barras impresso na guia** e ela passa a valer como qualquer outra — entra na lista, gera a conta a pagar e pode ser selecionada numa **remessa de pagamento** ([Tesouraria](docId:75tXS8u8o-8q4dR2arnmw)), que é o que de fato chega ao banco.

:::BlockQuote
**Lançar a guia não paga a guia.** Em qualquer um dos dois caminhos, a guia registrada aqui só vira pagamento quando entra numa remessa. Uma guia parada nesta lista no dia do vencimento é um tributo em atraso.
:::

1. **Confirme a nota com retenções.** As guias surgem quando uma nota fiscal de entrada com retenções é confirmada (fluxo de compras/entrada, [Compras](docId:3mdo_BH5DDXIp3VIh4ATK) e [Fiscal — entrada](docId:1_QpvYmn6apZ9mqx87Z4K)).
2. **Abra a tela das guias.** No menu **Financeiro → Guias de recolhimento** (rota /tax-payment-slips), logo abaixo do item de remessas de pagamento. A lista mostra **tipo** da guia, **código de receita**, **competência**, **vencimento**, **valor** e **situação** (Aberta, Paga, Vencida ou Cancelada). O item de menu exige a permissão **Gerenciar guias de tributos**; quem não a tem não o enxerga.
3. **Lance à mão uma guia emitida fora do sistema (GNRE, taxa).** No topo da tela, o cartão **Lançar guia emitida fora do sistema** tem o botão **Lançar guia**, que abre o formulário. A tela pede a permissão **Gerenciar guias de tributos**: quem só tem a permissão de remessa bancária **enxerga a lista** (para escolher guias de uma remessa) mas **não vê este formulário** — declarar que existe uma dívida tributária nova não é trabalho de tesouraria. Preencha\:Clique em **Registrar guia**. O botão só habilita quando todos os campos estão preenchidos e o código de barras tem um dos dois comprimentos válidos. Três coisas a saber depois de salvar: o **mesmo código de barras não entra duas vezes** — se já houver uma guia não cancelada com ele, o lançamento é recusado, porque pagar de novo pagaria a mesma dívida duas vezes (guia **cancelada** não conta: redigitar o código dela é justamente como se corrige um erro de digitação); a guia lançada à mão **não é reemitida** por aqui, porque a multa, os juros e o código de barras pertencem ao órgão emissor — guia estadual vencida se resolve reemitindo no portal do estado e lançando a nova; e o código de barras é aceito **como digitado** — o sistema confere os dígitos verificadores, mas não tem como perguntar ao estado se aquela guia existe, então um dígito trocado que ainda feche a conta gera um pagamento que o banco aceita e o estado não recebe.
   - **Tipo** — GNRE (estadual) aparece primeiro porque é o caso que existe na prática; os demais tipos também podem ser lançados.
   - **Código de barras ou linha digitável** — o número impresso na guia. São **44 dígitos** (o código de barras) **ou 48** (a linha digitável impressa abaixo das barras). Pontos e espaços podem ser digitados, o sistema os ignora. Qualquer outra quantidade é recusada na hora, dizendo quantos dígitos você digitou — inclusive os **47** de um boleto de **cobrança bancária**, que é outro instrumento, viaja em outro trecho do arquivo do banco e não pode ser registrado aqui.
   - **Valor** — o valor impresso na guia. Ele é **conferido contra o código de barras**, e o lançamento é recusado se os dois discordarem: **quem paga é o código de barras**, então aceitar os dois liquidaria a dívida por um valor enquanto a tela, a conta a pagar e a contabilidade mostram outro.
   - **Vencimento**, **Competência (AAAA-MM)** e **Código de receita** — como impressos na guia (a "receita" da GNRE, por exemplo 100102 para ICMS-ST).
   - **Beneficiário** — o órgão que recebe o pagamento: a secretaria da fazenda do estado, no caso da GNRE.
4. **Filtre pelo período ou situação.** Use os campos **Competência (AAAA-MM)** e **Situação** no topo. Com a lista vazia, a tela lembra do caminho automático — *"Confirme uma nota fiscal de compra com retenções para gerar guias automaticamente"* — e não do manual; o lançamento à mão do passo 61 continua disponível no cartão acima da lista.
5. **Encontre a conta a pagar correspondente.** Toda guia — gerada ou lançada à mão — cria um título **A pagar** que aparece em **Financeiro → Títulos** com o beneficiário do tributo (Receita Federal / INSS / prefeitura / secretaria da fazenda), o **vencimento** da guia e uma descrição que diz de onde ela veio: Guia \<tipo> \<código> (NF \<nota>) quando nasceu de uma nota, e Guia \<tipo> \<código> (lançamento manual) quando foi digitada. Ou seja, a guia já entra no fluxo normal de pagamento.
6. **Baixe o PDF e cancele o que entrou errado.** Na coluna de ações, o ícone de documento abre o **PDF da guia** (com código de barras); para várias de uma vez, use **Baixar PDF do lote** no topo. Enquanto a guia não está paga nem cancelada, a ação **Cancelar** exige uma **justificativa de no mínimo 20 caracteres**. Guias já pagas não podem ser canceladas por aqui.

### Manter a série SELIC que a reemissão de guia vencida usa

Guia paga em atraso rende **multa** — que o sistema calcula sozinho (0,33% por dia de atraso, limitada a 20%) — e **juros pela SELIC**, que ele não tem como calcular: é uma taxa **por mês**, divulgada pela Receita, que alguém do órgão precisa lançar. O recálculo soma a taxa de **cada mês entre o mês seguinte ao vencimento e a competência atual**; se faltar **um** desses meses, a reemissão é **recusada por inteiro** — nunca cobra a menos. Por isso a tela abre pela lacuna: o que interessa não é quantas taxas já existem, é **qual mês falta**.

1. **Abra "Série SELIC".** No menu lateral, **Financeiro → Série SELIC** (rota /selic-rates), logo abaixo do item das guias de recolhimento. A tela exige a permissão **Gerenciar guias de tributos** — a mesma que governa as guias do passo 60. Quem não a tem **não enxerga o item no menu**; e, se abrir a rota direto, recebe **"Você não tem acesso a isto"** — não uma lista vazia, que passaria a impressão errada de série sem taxa nenhuma.
2. **Leia o aviso antes de olhar a tabela.** No topo aparece um de três estados:
   - **vermelho, "Nenhuma taxa lançada"** — a série está vazia e **toda** reemissão de guia vencida é recusada;
   - **amarelo, "Competências sem taxa"** — lista os meses sem taxa entre a competência mais antiga lançada e o mês corrente; **cada mês é um botão** que já preenche o formulário abaixo com aquela competência;
   - **verde, "A série cobre todos os meses até a competência atual"** — não há buraco, e a tela fica só de consulta e manutenção.
3. **Lance a taxa de uma competência.** No cartão **Lançar a taxa de uma competência**:Clique em **Lançar taxa**. A competência sai do aviso amarelo na hora.
   - **Competência** — o mês, no seletor de mês. O campo **não aceita mês futuro**: o cálculo dos juros nunca lê um mês que ainda não terminou, então competência à frente é sempre ano digitado errado.
   - **Taxa mensal (%)** — **em percentual, como a Receita divulga**: digite 0,93 para 0,93% no mês, e não 0,0093. O sistema recusa taxa negativa e taxa acima de **10% ao mês** — margem larga de propósito, para barrar o dedo errado sem recusar um mês atípico (recusar deixaria a série com buraco, que é o erro mais caro dos dois).
4. **Corrija uma taxa já lançada.** Na linha da tabela, o ícone de editar reabre o cartão como **Corrigir uma taxa lançada**. Só a taxa muda: a **competência fica travada** (com o aviso *"Não pode ser alterada"*), porque mover uma taxa de um mês para outro mudaria em silêncio o que toda reemissão passada teria cobrado. Também **não há exclusão** por esta tela — taxa lançada na competência errada se resolve corrigindo o valor das duas competências envolvidas.
5. **Confira a tabela "Taxas lançadas".** As colunas são **Competência** (aaaa-MM), **Taxa mensal (%)** com quatro casas, **Origem** — preenchida com RFB, já que a tela não importa a série de lugar nenhum — e **Registrada em**, o carimbo de quando alguém lançou. A ordem é da competência mais recente para a mais antiga.
6. **Repita todo mês.** A série que veio na instalação termina na competência **2026-05**; de junho de 2026 em diante, cada mês só existe aqui porque alguém lançou. Lance a taxa assim que a Receita divulgar a do mês: enquanto o mês anterior estiver em branco, **toda** reemissão que atravesse esse mês é recusada — inclusive a de guias vencidas há muito tempo, cujo intervalo de juros passa por ele.

:::BlockQuote
**O que quebra sem esta tela.** A reemissão de uma guia vencida recalcula multa + juros e **regera o código de barras** pelo novo valor. Faltando competência, ela para com *"A série da SELIC não cobre as competências: 2026-06, 2026-07. Carregue as taxas faltantes antes de reemitir a guia."* e **nada é gravado** — a guia continua com o valor antigo. O recálculo é acionado pelo serviço de reemissão da guia; a lista do passo 60 oferece apenas o PDF e o cancelamento.
:::

:::BlockQuote
**Não confunda com Financeiro → Indexadores.** A SELIC também existe como **índice de correção** da tesouraria ([Tesouraria](docId:75tXS8u8o-8q4dR2arnmw)), usada para reajustar contratos e saldos. São **duas tabelas independentes**: o recálculo da guia lê **somente** a série desta tela. Lançar a SELIC nos índices não destrava a reemissão — e vice-versa.
:::

### Receber o fechamento da folha e virar contas a pagar

A folha de pagamento é calculada em outro sistema. O que chega aqui é o **fechamento** — quanto cada pessoa recebe líquido, quanto foi descontado dela e para quem, e quanto a empresa paga de encargo — e o sistema transforma isso em contas a pagar já conferidas, em vez de alguém redigitar centenas de linhas no dia mais crítico do mês.

1. **Abra "Lotes de folha".** Vá em **Financeiro → Lotes de folha** (rota /payroll-batches). Escolha o **estabelecimento pagador** e a **natureza financeira** em que as contas vão nascer.
2. **Suba o arquivo e confira ANTES de gravar.** Selecione o arquivo do fechamento e clique em **"Conferir sem gravar"**. O sistema mostra quantos colaboradores, o total líquido, o total de consignações e o bruto declarado — e diz se **os totais fecham**. **Nada é gravado nesta etapa.**
3. **Olhe o que não pôde ser aproveitado.** A prévia destaca, separadamente, as **linhas recusadas** (com o número da linha e o motivo) e as **pessoas ou credores não cadastrados** aqui. Se houver qualquer um dos dois, o botão de efetivar fica bloqueado.
4. **Corrija na origem, não aqui.** Devolva ao pessoal de RH, peça o arquivo corrigido e suba de novo. Como a conferência não gravou nada, o reenvio é uma importação limpa — não existe lote pela metade para cancelar.
5. **Efetive o lote.** Com os totais fechando e nenhuma pendência, clique em **"Efetivar o lote"**. Nascem as contas a pagar: **uma por colaborador** pelo valor líquido, **uma por credor de desconto** (Receita Federal, INSS, juízo, sindicato) com o **vencimento próprio de cada uma**, e **uma por encargo da empresa**. Elas entram no fluxo normal de pagamento — e as dos colaboradores vão para a ordem de pagamento e a remessa bancária ([Tesouraria](docId:75tXS8u8o-8q4dR2arnmw)).

75a. **Efetivar não paga ninguém — clique em "Pagar no banco".** O lote efetivado ganha, na lista, o botão **"Pagar no banco"** (só em lote **Efetivado**: antes disso não existem contas a pagar para levar ao banco). Ele abre os dois passos que faltam, com o link de cada um: **montar e autorizar a ordem de pagamento** e depois **gerar a remessa**. Cada passo diz **quem** pode executá-lo — quem liquida títulos monta a ordem, quem autoriza a aprova, a tesouraria fala com o banco — e, se você não tiver a permissão de um deles, a tela **diz isso** em vez de simplesmente não mostrar o passo.

:::BlockQuote
\> \*\*Não use a remessa CNAB de "Caixa e bancos" para folha.\*\* A lista de documentos daquela tela filtra só por situação, então as contas da folha \*\*aparecem\*\* ali — mas o arquivo que ela gera instrui \*\*cobrança\*\*, não pagamento: não tem cabeçalho de lote, nem tipo de serviço, nem os dados bancários do favorecido. Enviá-lo ao banco não paga salário nenhum. O caminho da folha é o do passo 75a.
:::

76\. **Reenvio do mesmo arquivo é recusado.** O arquivo é identificado pelo seu conteúdo: subir exatamente os mesmos dados de novo é **recusado**, não duplicado. Para corrigir um fechamento já efetivado, gere um arquivo novo no sistema de folha.

:::BlockQuote
A prévia também informa \*\*quantas linhas serão gravadas sem servidor rastreável\*\*. O vínculo com a pessoa existe para uma guia agregada poder ser rastreada até quem a originou — é o que o auditor pede. O \*\*encargo patronal\*\* é coletivo por natureza e o arquivo não nomeia servidor nele, então esse número raramente é zero: ele não impede a efetivação, serve para você saber o que está gravando.
:::

77\. **Importou o lote errado? Cancele-o.** Toda linha que ainda não esteja cancelada traz o botão **Cancelar folha** — inclusive um lote apenas importado, que é justamente o caso de "veio o arquivo errado". Cancelar anula **as contas a pagar que o lote gerou** e marca o lote como **Cancelado**; não é preciso caçar título por título em outra tela. Quem importa a folha é quem cancela.

:::BlockQuote
\- \*\*O sistema pede o motivo, e ele fica gravado.\*\* O motivo aparece \*\*na própria linha\*\*, abaixo da situação, e vai para a trilha de auditoria. Isso existe porque a competência cancelada deixa para trás um conjunto de títulos anulados: sem o motivo, quem audita encontra o ato registrado e nenhuma explicação. Cancelar sem motivo é recusado.
\- \*\*Título já liquidado impede o cancelamento\*\*, e isso é proposital: dinheiro que saiu não volta por mudança de situação. O sistema \*\*confere todas as linhas antes de anular qualquer uma\*\* e recusa dizendo \*\*quantas\*\* linhas estão liquidadas, de quantas, e \*\*quais\*\* — para você localizar o servidor sem abrir o financeiro título a título. O lote \*\*continua efetivado\*\*, que é a verdade, e nenhuma conta foi anulada no caminho. A partir daí a folha não pode mais ser cancelada: o caminho é estornar as baixas primeiro.
\- \*\*Depois de cancelar, o arquivo corrigido entra.\*\* O bloqueio de competência duplicada ignora lotes cancelados, então a reemissão da mesma folha é aceita sem precisar declará-la como \*complementar\* — que é outra coisa.
\- \*\*O custo do lote cancelado sai dos indicadores.\*\* A métrica de custo de folha conta só lotes efetivados; anular um lote tira o valor dele do indicador em vez de deixá-lo somando para sempre.
:::

:::BlockQuote
**O layout do arquivo** está publicado em docs/ops/payroll-integration-layout.md — é o que o fornecedor da folha precisa produzir. **O ERP não calcula folha**: não há tabela de INSS/IRRF, nem regra de incidência, nem fórmula de rubrica. Os valores chegam calculados; a única conta feita aqui é conferir se o bruto declarado bate com o líquido mais os descontos.
:::

:::BlockQuote
**Cada colaborador precisa estar cadastrado como parceiro** e ter uma **conta principal** eleita na ficha dele — veja o passo 8 da página [Tesouraria](docId:75tXS8u8o-8q4dR2arnmw). Quem não estiver cadastrado é listado na prévia; o sistema **não** adivinha a pessoa por semelhança de nome.
:::

### Contrato administrativo: a medição atestada é que gera o título

Em **Financeiro → Contratos administrativos** ficam os contratos de fornecimento, serviço, obra e locação. É a tela que fecha a cláusula "contratos" dos itens **25.2** (contas a pagar) e **26.1** (contas a receber) — os dois pedem que as operações gerem o título automaticamente, e contrato era a única das operações listadas sem produtor.

1. **Cadastre o contrato.** Informe o número, a outra parte, a **categoria** — fornecimento de bens, locação, prestação de serviços ou obras, que são as quatro do art. 141 da Lei 14.133 —, o objeto, o valor total, a vigência, o dia de vencimento, o índice de reajuste pactuado e a natureza de receita ou despesa.
2. **Diga o sentido.** *Despesa* quando o órgão contrata e paga; *Receita* quando o órgão é o credor. É o que decide de que lado do razão o título nasce, e por isso mora no contrato e não na hora de faturar.
3. **Registre a medição do período.** Referência (a competência ou o número da medição), valor medido e data. A soma das medições **não pode ultrapassar o valor total** do contrato — se ultrapassar, a tela recusa e informa quanto ainda resta.
4.

**Um contrato de doze meses não vira doze títulos no dia da assinatura.** Isso não é limitação do sistema: é como a lei manda. O art. 140 da Lei 14.133 faz do termo de recebimento o insumo da **liquidação** do art. 63 da Lei 4.320/1964, e para obras diz expressamente que se paga **a cada medição**. O órgão não deve nada por um serviço que ainda não foi prestado.

**Ateste — e é só aqui que o título nasce.** Registrar a medição guarda o que foi entregue; **atestar** é o ato formal que gera a conta a pagar (ou a receber) no valor medido, com o vencimento do contrato e em nome da outra parte.

1. **Atestar de novo não gera outro título.** A segunda tentativa informa que aquela medição já está faturada — que é diferente de dizer que faturou agora. A linha passa a mostrar **Abrir título**, que leva direto ao documento financeiro gerado.
2. **Do título de volta ao contrato.** Na ficha do título, tanto o campo **Origem** quanto o cartão **Documentos vinculados** (com o selo *Contrato*) abrem o contrato que o originou — é o drill-down que os itens **25.4** e **26.2** pedem.

:::BlockQuote
**Não confunda com "Contratos de captação"**, logo abaixo no menu: aquele é empréstimo, financiamento e leasing — dinheiro que o órgão toma. Este é contratação.
:::

## Verificação

***

Você sabe que funcionou quando:

- O contrato aparece em **Financeiro → Contratos administrativos** com a categoria, o sentido e a situação; o **saldo do contrato** desconta o que já foi medido.
- Registrar uma medição **não** cria título nenhum: o documento só aparece depois de **Atestar**.
- Atestar a mesma medição duas vezes gera **um** título, e a segunda tentativa avisa que ela já estava faturada.
- O título gerado abre o contrato de origem pelos **dois** caminhos da ficha (campo Origem e cartão de documentos vinculados).
- A conta a pagar aparece na lista de **Títulos** com tipo **A pagar**, o fornecedor, a categoria e a situação Aberto.
- A conta a receber aparece com tipo **A receber**, amarrada ao cliente correto.
- Uma **baixa parcial** deixa o título em Parcial com saldo menor; a **baixa total** o deixa em Quitado com saldo zero.
- O **rateio** só salva quando os percentuais somam exatamente **100%** (o total aparece em verde).
- Um título acima do teto de alçada fica com **Aprovação pendente** e não pode ser baixado até alguém com alçada superior aprovar.
- Ao registrar juros/multa/desconto, o **saldo em aberto (com acréscimos)** muda de acordo.
- O *lançamento contábil* da baixa aparece em **Contabilidade → Razão**  com débito e crédito balanceados.
- Em **Financeiro → Série SELIC**, o aviso do topo está **verde** (A série cobre todos os meses até a competência atual). Enquanto ele estiver amarelo, a reemissão de guia vencida cujo intervalo passe por um dos meses listados continua recusada.

## Erros comuns

***

- **Aprovação pendente que não some** — o título está acima do teto de alçada de quem tenta pagar. Peça a um aprovador de nível superior para abrir a ficha e clicar em **Aprovar**.
- **Rateio não salva (botão desabilitado)** — os percentuais não fecham 100%. Ajuste as linhas até o total ficar verde.
- **Fornecedor/cliente não aparece na busca** — o parceiro não está cadastrado. Volte à página [Cadastros gerais (parceiros e produtos)](docId:6xpQsdWQ2NTyI40BFqDS-) e cadastre antes de lançar o título.
- **Falta a categoria** — o sistema não aceita o título sem categoria financeira, porque a contabilidade precisa dela para o lançamento. Escolha a categoria antes de salvar.
- **Título "sem roteamento"** — o fornecedor não tem conta bancária cadastrada, então a conta a pagar fica sem conta de destino. Cadastre a conta do parceiro ou informe o roteamento na tesouraria.
- **Não consigo baixar mais do que o saldo** — o sistema **recusa a sobre-baixa**: não se paga (nem recebe) mais do que o saldo em aberto. Informe um valor até o saldo restante.
- **Não consigo editar nem excluir o título** — de propósito. O título é um **documento com ciclo de vida**, não um cadastro editável: ele só muda por **baixa, cancelamento, prorrogação, endosso ou renegociação**. Para desfazer um título lançado por engano, use **Cancelar** (não "excluir").
- **A série da SELIC não cobre as competências: ...** — a reemissão da guia vencida foi recusada porque falta a taxa de pelo menos um mês do intervalo de juros. Abra **Financeiro → Série SELIC**, lance as competências apontadas no aviso amarelo e repita a reemissão. A recusa é do recálculo **inteiro**, de propósito: não existe "cobrar só os meses que dá".
- **A taxa mensal deve ficar entre 0 e 0,10** — a taxa digitada passou de **10% no mês**. Confira se você não digitou a taxa acumulada do ano no lugar da mensal. Atenção: a mensagem fala em **fração** (0,0093), mas o campo da tela é em **percentual** (0,93) — digite como a Receita divulga.
- **A competência ... já tem taxa lançada** — a mesma competência não entra duas vezes. Use o ícone de editar na linha existente para corrigir o valor.
- **A competência ... está no futuro** — quase sempre é o ano digitado errado; a série só aceita meses já encerrados ou o mês corrente.
- **Não consigo cancelar o título** — só é possível cancelar um título **sem baixa**. Se ele já está Parcial ou Quitado, o cancelamento é recusado — o caminho passa a ser estornar/renegociar. Da mesma forma, um título **cancelado não aceita mais baixa**.


[title] Integração com sistemas externos
[path] Aplicações/ERP/Manual do Usuário/

# Integração com sistemas externos (emitir e controlar a chave)

:::BlockQuote
Pré-requisitos: [Administração](docId\:Z8SS7r6Bvhs09rP1SPxUD). Esta página é do **perfil administrador** do tenant.**Se você é quem vai escrever a integração**, esta não é a sua página: o contrato, os exemplos de código e o catálogo de operações estão na **Documentação para desenvolvedores**, uma coleção própria no portal.
:::

## Introdução

***

Quando um sistema externo precisa conversar com o ERP — um portal de transparência que puxa empenhos, um aplicativo de campo que devolve medições, o sistema de protocolo que consulta fornecedor — alguém do órgão precisa dizer **quem ele é e o que pode fazer**. É o que esta tela faz.

A ideia central: **quem entra de fora entra com uma chave, e a chave já diz o que pode**. Não existe "usuário de integração" com cargo fictício no organograma — o programa não tem cargo, e inventar um servidor fantasma só para pendurar permissão é algo que ninguém consegue auditar depois.

## Passo a passo

***

**1 - Abra "Chaves de integração".** Menu **Administração → Chaves de integração**. A tela inicial é a **grade** das chaves já emitidas (nome, prefixo, permissões, situação, último uso), com as ações **Editar** e **Revogar** por linha, o botão **"Nova chave"** e um link para abrir o contrato da API. O item só aparece para quem tem a permissão de **gerenciar chaves de integração**; sem ela, a lista não carrega — mostra um aviso de acesso negado, com botão de tentar de novo, e não uma tela vazia.

**2 - Emita a chave.** Clique em **"Nova chave"** para abrir a tela de emissão. Informe uma descrição que diga **qual integração é** — "Portal da transparência", "App de medição de obra" — e não apenas "integração". Você vai revogar pelo nome daqui a um ano.

**3 - Diga o que a chave pode fazer.** Há dois caminhos, e o campo **"Grupos de acesso"** aparece primeiro porque é o recomendado\:As **duas regras do escopo** logo abaixo valem para os dois caminhos.

:::Paragraph{listStyleType="disc" indent="2"}
**Associe um ou mais grupos de acesso** (recomendado). Um grupo é um conjunto de permissões com nome de negócio — "Emissão fiscal", "Consulta de cadastros" — em vez de uma lista de códigos técnicos. Marque um ou mais grupos e a chave passa a poder tudo o que a **união** deles concede. Ao marcar um grupo, o campo de operações some: as permissões vêm do grupo. É a seção *Grupos de acesso*, logo abaixo, que explica como criá-los e por que compensam. Você **não precisa** decorar nomes de operação.
:::

:::Paragraph{listStyleType="disc" indent="2"}
**Ou liste as operações uma a uma** (avulso). Deixe os grupos sem marcar e o campo **"Escopo"** reaparece, autocompletando com o catálogo de operações: comece a digitar e escolha da lista, separando várias por vírgula (ex.: READ\_REGISTRY, READ\_INVENTORY). Serve para uma chave pontual que não vale a pena virar grupo.
:::



![](https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/145-app-key-scope.png)

**4 - Copie o segredo.** Ele aparece **uma única vez**. Não há recuperação: se perder, emita outra e revogue esta.

**5 - Entregue a chave ao parceiro.** O contrato — a lista de operações que o desenvolvedor dele vai programar — é alcançado **com a própria chave**, e não por um endereço público que você repassa. Para conferir você mesmo o que ele vai encontrar, abra o **"Contrato da API"** pelo link na tela de chaves: é uma **troca** (você cola a chave uma vez), não um endereço para repassar. É o assunto da seção *Abrir o contrato da API*, adiante.

**6 - Revogue quando a integração terminar.** Vale na chamada seguinte, inclusive para o acesso à documentação. Não há período de graça.

## As duas regras do escopo que surpreendem

***

:::BlockQuote
**O escopo é uma lista fechada.** Uma operação fora dele é recusada — **mesmo que o órgão ainda não tenha definido nenhuma regra de alçada para ela**. Para pessoas, o ERP assume que "ainda não configurei" significa liberado, porque o órgão organiza suas alçadas aos poucos. Para um programa que fala de fora, silêncio significa **não**. Uma chave emitida **sem nenhuma operação no escopo não faz absolutamente nada** — e isso é proposital: se valesse a regra das pessoas, ela herdaria tudo que ainda não foi governado.Em particular, **ROLE\_INTEGRATION (ou qualquer token que comece com ROLE\_) não é uma operação** — é papel, não permissão. Uma chave com só isso no escopo é exatamente o caso "não nomeia operação nenhuma": ela valida, aparece ativa na lista e devolve 403 em tudo. Por isso o sistema agora **recusa a emissão** de um escopo que não nomeie ao menos uma operação, em vez de deixar você descobrir pelo chamado do parceiro.
:::

:::BlockQuote
**Chave nunca aprova valor.** Operações sujeitas a limite de alçada são recusadas para integração, sempre. Aprovar valor dentro de alçada é ato de agente público, preso a um cargo, e um programa não tem cargo. Se o parceiro disser que "precisa aprovar", o desenho está errado: a integração **registra**, e uma pessoa aprova.
:::

## Grupos de acesso — permissão em linguagem de negócio

***

Escolher operação por operação funciona, mas cansa e erra: são dezenas de códigos (READ\_REGISTRY, TRANSMIT\_FISCAL, SETTLE\_DOCUMENT…), e cada chave nova obriga a montar a lista de novo. Um **grupo de acesso** resolve isso — é um conjunto de operações com **nome de negócio**, criado uma vez e associado a quantas chaves precisar. Em vez de "esta chave tem MANAGE\_FINANCIAL\_DOCUMENT e SETTLE\_DOCUMENT", você diz "esta chave tem **Faturamento**". É o mesmo padrão que a nuvem usa (papel no Google, política gerenciada na AWS, conjunto de permissões no Salesforce): a permissão vira reutilizável e ganha um nome que o gestor entende.

Quem administra os grupos usa **Menu Administração → Grupos de acesso** (/admin/access-groups). O item só aparece para quem tem a permissão de **gerenciar grupos de acesso**.

### O que já vem pronto

O sistema já traz cinco **presets** (grupos prontos), que cobrem os casos mais comuns:

| Preset                                  | O que concede                                                |
| --------------------------------------- | ------------------------------------------------------------ |
| **Integration read-only (all modules)** | leitura de todos os módulos (o "só consulta")                |
| **Registry read**                       | leitura de cadastros (parceiros, produtos, tabelas de preço) |
| **Inventory read**                      | leitura de estoque                                           |
| **Fiscal issuance**                     | emitir e gerir documentos fiscais                            |
| **Billing**                             | gerir e baixar documentos financeiros                        |

Preset é ponto de partida — pode ser **renomeado** e ter as permissões ajustadas, mas **não pode ser excluído** (só desativado). Os nomes chegam em inglês por serem semente do sistema; renomeie para o vocabulário do seu órgão à vontade.

### Criar um grupo próprio

1. **"Novo grupo".** Dê um **nome** que o gestor entenda ("Portal da transparência", "Emissão fiscal") e uma descrição do que ele serve.
2. **Escolha as permissões** ("Permissões"), agrupadas por módulo — são as mesmas operações do escopo avulso, só que reunidas sob o nome. Um grupo **sem nenhuma permissão não concede nada** (a tela nem deixa salvar).
3. **Salve.** O grupo passa a aparecer no seletor de grupos da emissão de chave.

O nome é **único** e não diferencia maiúscula de minúscula: não há dois grupos "Faturamento".

### A regra que surpreende: editar um grupo mexe em todas as chaves que o usam

Um grupo é **um único ponto de mudança**. Quando você acrescenta uma permissão a um grupo, **toda chave associada a ele passa a ter essa permissão na chamada seguinte** — sem reemitir nada. É a vantagem (ajusta um lugar, propaga para todas) e é a armadilha (ampliar um grupo compartilhado amplia todas as chaves de uma vez). Daí a disciplina de grupos enxutos: se só uma integração precisa de uma permissão a mais, dê a ela um grupo próprio, em vez de inchar um grupo que muitas chaves usam. **Desativar** um grupo remove as permissões dele das chaves que o referenciam — mesmo cuidado.

### Histórico do grupo

Mudança em grupo é mudança de permissão, então fica registrada. Na linha do grupo, **"Histórico"** abre a trilha de auditoria: quem criou, quem alterou o quê e quando, com o **diff campo a campo** em cada alteração — o mesmo padrão de histórico das demais telas de cadastro do ERP.

### Chaves antigas (migradas)

Chaves que já existiam antes dos grupos continuam valendo com o escopo avulso que tinham. Para não perder rastreabilidade, cada uma dessas listas de escopo virou automaticamente um grupo próprio (com nome começando por "Migrated"), que você pode renomear, reaproveitar em outras chaves, ou ignorar. Nada quebrou: a chave continua exatamente com as permissões de antes.

## Editar as permissões de uma chave

***

Antes, mudar o que uma chave podia fazer exigia **revogá-la e emitir outra** — e reconfigurar a integração do outro lado por uma mudança pequena. Agora não: na grade, a ação **Editar** de cada chave abre a tela de edição, onde você troca o **nome** e as **permissões** (marcando outros grupos de acesso, ou operações avulsas) e salva. **O segredo não muda** — a chave que o parceiro já usa continua valendo; muda só o que ela pode fazer, valendo na chamada seguinte. É o mesmo princípio dos provedores de nuvem: a credencial autentica, as permissões são um ajuste à parte.

Três detalhes que evitam susto:

- **Chave revogada é só leitura.** Você a abre para consultar o que ela concedia e o histórico, mas não há botão de salvar — revogar é definitivo.
- **Editar um grupo muda todas as chaves que o usam.** Se a chave é autorizada por um grupo compartilhado, alterar aquele grupo (na tela *Grupos de acesso*) repercute em **todas** as chaves associadas. Para mexer só nesta chave, dê a ela um grupo próprio ou use operações avulsas.
- **Toda alteração fica no histórico.** A própria tela de edição mostra o **Histórico de alterações** da chave: quem mudou o quê e quando, com o diff campo a campo. O segredo **nunca** aparece ali — a trilha guarda nome, prefixo e permissões, jamais a chave.

## Abrir o contrato da API (destravar no navegador)

***

O contrato não fica aberto na internet: ele responde a **chave cadastrada**, e só. Aí aparece um detalhe que confunde todo mundo na primeira vez — **um navegador não envia cabeçalho quando você navega**. Um programa carimba a chave em cada chamada; uma aba do navegador só pede a página, sem nada junto. Por isso um link direto para o console devolve "não autorizado" mesmo com a chave certa em mãos: não existe onde colocá-la.

O cartão **"Contrato da API"** resolve isso com uma troca. Você cola a chave **uma vez** e o ERP devolve, para aquele navegador, uma autorização curta que apenas **nomeia** a chave — nunca carrega a chave. É essa autorização que abre o console nas navegações seguintes.

### Como fazer

1. O cartão **"Contrato da API"** é o primeiro da tela **Administração → Chaves de integração**. Se ele avisar **"Nenhuma chave ativa ainda"**, não há o que destravar: emita a primeira chave no painel de baixo e volte aqui.
2. **Escolha a "Área de negócio".** O contrato é publicado em uma seção por área — Cadastros, Compras, Estoque, Vendas e faturamento, Financeiro, Contabilidade, Patrimônio e imóveis, Custos e orçamento, Frota, Jurídico, Folha de pagamento, Gestão por indicadores, Plataforma e gateway. A escolha diz **em que seção o console vai abrir**; ela não muda o que a chave pode fazer, que continua sendo só o escopo dela.
3. **Cole a chave em "Chave de integração".** O campo é do tipo senha — o que você colar não fica legível na tela. É o segredo que apareceu **uma única vez** na emissão. O **prefixo listado na tabela de baixo não serve** — ele é apenas o identificador visível da chave, e é o engano mais comum de quem tenta pela primeira vez. Se você acabou de emitir, o botão **"Usar esta chave para abrir o contrato"**, no painel do segredo, preenche o campo sem passar pela área de transferência.
4. **Clique em "Destravar o contrato".**
5. **Dando certo**, aparece uma faixa verde com o **nome da chave** que abriu e **em quanto tempo o console fecha de novo** (uma hora, na configuração padrão), mais dois caminhos\:O seletor de área continua ativo depois de destravar: troque a área e os dois caminhos passam a apontar para ela, sem colar a chave outra vez.
   - **"Abrir o console"** — a página interativa, já posicionada na área escolhida;
   - **"Abrir o documento (JSON)"** — o mesmo contrato em arquivo, que é o que o desenvolvedor do parceiro joga no gerador de código dele.

### O que fica valendo depois

- **A abertura vale só naquele navegador** e expira sozinha. Não é endereço para repassar por e-mail: quem receber o link sem ter destravado bate no mesmo "não autorizado".
- **Revogar a chave fecha o console na requisição seguinte.** Cada navegação reconfere se a chave ainda está ativa — não há período de tolerância até o prazo vencer.
- **"Usar outra chave"** apenas devolve o formulário para destravar com outra chave; ele **não** fecha o que já está aberto. O que fecha é o prazo ou a revogação.
- **Se o desenvolvedor do parceiro não tem acesso ao portal, ele não usa esta tela** — e não precisa. O programa dele lê o mesmo contrato enviando a chave no cabeçalho X-Erp-AppKey, como faz em qualquer outra chamada. Esta tela existe para o navegador, que é justamente quem não consegue mandar o cabeçalho.

### Quando o destravamento é recusado

A tela distingue os motivos porque a saída de cada um é diferente:

| O que a faixa vermelha diz                                      | O que aconteceu                                                                                       | O que fazer                                                                                                                      |
| --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| "Esta chave não foi reconhecida"                                | chave errada, incompleta ou já revogada. Espaço colado antes ou depois **não** é causa: a tela remove | confira que você colou o segredo da emissão, e não o prefixo da tabela; se o segredo se perdeu, emita outra chave e revogue esta |
| "Tentativas demais a partir deste endereço"                     | proteção contra chute de chave: cerca de dez tentativas por minuto vindas do mesmo endereço           | espere um minuto e tente de novo — não adianta reemitir a chave                                                                  |
| "Abrir o contrato pelo navegador está desligado neste ambiente" | esta instalação não tem configurado o segredo que assina a autorização                                | é ajuste de quem administra a instalação, não da tela; enquanto isso só o caminho pelo cabeçalho funciona                        |
| "Não foi possível falar com o servidor"                         | a requisição não chegou a sair                                                                        | rede, VPN ou servidor fora do ar                                                                                                 |

Se o destravamento der certo mas **"Abrir o console" cair em página não encontrada**, o problema é outro: o console não está publicado no mesmo endereço do portal nesta instalação. Também é assunto de quem administra o ambiente — reemitir chave não resolve.

### Se ninguém destravar

Não quebra nada dentro do ERP. Quebra do outro lado, mais tarde: sem o contrato aberto, o desenvolvedor do parceiro programa por descrição verbal ou por um documento antigo que alguém mandou por e-mail, e a integração chega em produção errando nome de campo e operação que nem existe mais. São os chamados de "está dando 400 e não sei por quê" que ninguém consegue responder sem o documento à mão — e o documento está aqui, a uma colagem de chave.

## O portal do cidadão pedindo orçamento&#x20;

***

Esta é a primeira integração que o próprio **cidadão** dispara, ainda que ele nunca fale com o ERP. Vale ler o desenho antes de habilitar, porque ele responde de antemão a maior parte das perguntas que aparecem depois.

**Quem é quem.** O interessado entra no **portal do município**, já identificado por lá (o gov.br, tipicamente), e pede um orçamento. Quem conversa com o ERP é o **portal**, não ele — com uma chave de aplicação, como qualquer outro sistema desta página. O ERP **não** autentica o cidadão e **não** guarda senha dele. Do lado de cá, a solicitação chega como se um sistema parceiro a tivesse enviado, porque foi exatamente isso que aconteceu.

**Não existe, e não vai existir, uma tela do ERP para o cidadão.** A operação SUBMIT\_QUOTE\_REQUEST é **de máquina**: nenhum cargo humano pode recebê-la, nem por regra de autorização — o sistema recusa a tentativa. Se alguém pedir "o print da tela do portal do cliente", a resposta honesta é que a tela é do município; o que o ERP mostra é o resultado dela, em **Vendas → Solicitações de cotação**, com o selo **Portal do cliente** na coluna Origem (veja *08 — Vendas*, passos 5 e 6).

### Como habilitar

1. **Crie um grupo de acesso** com a operação *Receber pedido de orçamento pelo portal do cliente* — é o nome dela na lista. Um grupo dedicado, e não um grupo existente com mais uma operação: quando alguém perguntar "quem pode abrir solicitação em nome de cidadão?", a resposta tem que ser um nome, não uma varredura.
2. **Emita a chave** para o portal do município ligada a esse grupo. O segredo aparece **uma única vez**, na criação — o mesmo cuidado de sempre.
3. **Entregue a chave a quem mantém o portal do município.** Ele precisa também do identificador do órgão (o *tenant*), que acompanha a chave. O contrato das duas operações está publicado na área **Vendas e faturamento** da documentação da API, e vem pronto no SDK tipado — é o que evita o desenvolvedor do outro lado programar por descrição verbal e descobrir nome de campo errado em produção.

**Cada solicitação diz por qual chave entrou.** Toda entrada por este canal fica registrada no **Histórico de alterações** da própria solicitação, com a chave identificada pelo prefixo (appkey:…) e a data. É o que torna a chave dedicada mais que burocracia: a pergunta "quem abriu esta solicitação em nome do cidadão?" passa a ter resposta **por solicitação**, não só por permissão.

:::BlockQuote
Uma ressalva para não mandar ninguém a um beco: **abrir esse histórico exige perfil de auditoria.** Quem cuida da carteira comercial vê a solicitação, mas não o registro de origem — se ele clicar e receber uma negativa de permissão, o manual não está errado e a tela não está quebrada; falta o perfil. Peça a leitura a quem audita.
:::

:::BlockQuote
⚠️ **O cidadão precisa já ser cliente cadastrado.** Este canal **não cadastra ninguém**: se o requerente não existir no cadastro com o papel de cliente, a solicitação é recusada. Foi decisão do patrocinador, e é o que impede que um canal aberto vire porta de entrada de cadastro sem conferência.
:::

### O que o cidadão vê depois

Ele recebe um **código de acompanhamento** — uma sequência longa, sem significado, que não revela nada sobre o órgão nem sobre o pedido. Com ele, e apenas por meio do portal do município, consulta **em que situação** a solicitação está e **as datas**. Nunca valores: nem o total, nem o preço de item nenhum. A proposta continua indo pelo caminho de sempre, quando o vendedor enviar o orçamento.

Isso é deliberado. O código sozinho não pode virar uma janela para o preço que o órgão praticou — e como ele viaja por fora, é preciso assumir que pode vazar.

### O que muda no dia a dia de quem vende

Nada no procedimento, e uma coisa no julgamento: a solicitação que chega por este canal **não passou por ninguém do setor**. Ninguém conferiu se o pedido faz sentido, se o cliente é quem diz ser para aquele item, se o texto está completo. Vale ler com o mesmo cuidado que se teria ao telefone com um desconhecido. O selo na coluna Origem existe para isso.

### Quando alguém disser que não funciona

| O que relatam                                    | O que provavelmente é                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| "o portal manda e dá 403"                        | a chave não tem a operação no escopo. **Não reemita** — abra a chave em **Editar** e marque o grupo que carrega *Receber pedido de orçamento pelo portal do cliente*. O segredo não muda e vale já na chamada seguinte; reemitir derrubaria o canal do cidadão até o município reconfigurar o segredo do outro lado                                                                                                                         |
| "dá 403 e a operação está no grupo"              | o grupo pode estar **inativo**; a chave só herda de grupo ativo                                                                                                                                                                                                                                                                                                                                                                             |
| "dá 400 dizendo que o cliente não existe"        | o requerente não está no cadastro, ou está sem o papel de cliente                                                                                                                                                                                                                                                                                                                                                                           |
| "dá 400 e não fala de cliente"                   | o pedido só carrega **cliente**, **validade** (opcional) e uma **observação de até 400 caracteres** — texto maior é recusado. Quem limita o campo é o portal do município                                                                                                                                                                                                                                                                   |
| "o acompanhamento devolve 404"                   | o identificador não corresponde a nada **naquele órgão**. Desconhecido, digitado errado e pertencente a outro órgão devolvem os três a **mesma** resposta vazia, de propósito — para ninguém descobrir por tentativa que um código existe. **Não significa que a solicitação foi apagada:** confira o código guardado pelo portal antes de mandar o cidadão pedir de novo, senão entra uma segunda solicitação igual no funil de quem vende |
| "consultamos o acompanhamento e não vem o valor" | é o comportamento correto — o canal nunca devolve valor                                                                                                                                                                                                                                                                                                                                                                                     |
| "funciona no servidor e falha no navegador"      | o navegador manda o **cookie de sessão** junto com a chave, e aí o ERP trata a chamada como se fosse uma pessoa e recusa; a integração tem que chamar sem cookie                                                                                                                                                                                                                                                                            |

## Quando o parceiro relatar erro

***

| O que ele relata                                         | O que provavelmente é                                                                                                                                                                      |
| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| "dá 401"                                                 | chave errada, digitada com espaço, ou já revogada                                                                                                                                          |
| "dá 403 numa operação que existe"                        | falta aquela operação no escopo da chave — reemita                                                                                                                                         |
| "dá 403 e você diz que está no escopo"                   | o recurso pode ser fechado para integração; abra chamado                                                                                                                                   |
| "dá 429"                                                 | ele está estourando o limite de chamadas; é ele que ajusta o ritmo                                                                                                                         |
| "abri o endereço da documentação no navegador e deu 401" | ele navegou direto, sem a troca descrita em *Abrir o contrato da API* — o navegador não leva a chave junto; ou ele destrava, ou o programa dele baixa o documento com a chave no cabeçalho |

O catálogo de operações, na documentação para desenvolvedores, mostra **o escopo exigido por operação** — é a lista da qual você monta o escopo da chave, sem adivinhar.


[title] Backlog do ART e Planning Board
[path] Aplicações/Agility/SAFe — Backlog e execução/

:::BlockQuote
Administre o backlog de Features do trem e aloque cada entrega em uma combinação de Time e iteração no Planning Board.
:::

:::hint{type="info"}
**Pré-requisito:&#x20;**

O ART precisa ter Features, Times e um Planning Interval com iterações. Para arrastar e gravar alocações, a sessão deve possuir capacidade de edição.
:::

***

O Backlog do ART é a fila de Features que o trem pode levar para um PI. Ele reúne Features e Enablers, apresenta seus vínculos e permite comparar WSJF, rank, Times, projeto e PI candidato. Quando o ART está ligado a um projeto com board, a visão Board também apresenta o trabalho priorizado no contexto de execução.

O Planning Board transforma a decisão do PI Planning em uma matriz: o poço Não planejado concentra Features sem alocação, as linhas representam Times e as colunas representam iterações. Uma Feature pode ser arrastada do poço para uma célula Time × Iteração ou devolvida ao poço para remover sua alocação.

***

### Passo a passo

::::WorkflowBlock
:::WorkflowBlockItem
**Conferir a fila do ART**

Abra ARTs, selecione o trem e entre em Backlog. Leia os quatro cartões de resumo: Features candidatas, Enablers, WSJF incompleto e PI candidato. O quadro de Features é o recorte do ART, portanto os nomes de Épicos, Times e projetos exibidos devem ser escolhidos dessa própria coleção.
:::

:::WorkflowBlockItem
**Alternar Board e Tabela**

Use Board para visualizar o fluxo e Tabela para conferir cada coluna de dados. Na tabela, você encontra Feature, Épico, responsável, Times, projeto, WSJF, PI candidato e estado; com permissão de edição, a última coluna também apresenta as ações. Se ainda não houver um board de projeto resolvido, o sistema mantém a lista em Tabela em vez de mostrar uma matriz vazia.
:::

:::WorkflowBlockItem
**Filtrar e ordenar antes de planejar**

Se o trabalho de um Time específico estiver em foco, use o filtro por Time e confirme o chip que identifica o recorte. Use a ordenação WSJF para comparar prioridades; sem ela, a ordem da lista é o rank do trem. Limpe o filtro quando precisar voltar ao conjunto completo.
:::

:::WorkflowBlockItem
**Criar ou refinar uma Feature**

Clique em Nova Feature para incluir uma entrega na fila ou abra uma existente para refinar. Selecione Épico pai, tipo Feature/Habilitador, Times, responsável, PI candidato e fatores WSJF. Salve e confira se a Feature aparece no Backlog antes de tentar alocá-la no Planning Board.
:::

:::WorkflowBlockItem
**Abrir o Planning Board do PI**

Na navegação do ART, abra Planning Board. O cabeçalho identifica o Planning Interval e apresenta os indicadores de objetivos, Features alocadas, dependências e capacidade. Use o filtro de Time para enxergar apenas uma linha da matriz ou mantenha Todos para a conversa do ART inteiro.
:::

:::WorkflowBlockItem
**Ler a matriz integrada**

Na grade, a primeira coluna identifica o Time, a segunda é o poço Não planejado e as demais mostram cada iteração com nome e data de início. Os cartões no poço ainda não têm Time; cartões nas células representam alocações já registradas. A capacidade mostra pontos alocados e pontos disponíveis, e o percentual resume o uso total.
:::

:::WorkflowBlockItem
**Alocar pelo formulário**

Se preferir não arrastar, use o cartão de alocação. Escolha uma Feature, um Time e uma Iteração nos campos de busca e clique em Alocar. O formulário oferece somente Features, Times e iterações do board atual. Depois do sucesso, o cartão sai do poço e aparece na célula correspondente.
:::

:::WorkflowBlockItem
**Alocar por arrastar**

Com edição habilitada, arraste o cartão pelo controle de arraste do poço até uma célula de Time e iteração. O movimento visual é otimista durante o gesto; ao soltar, o Agility grava primeiro a nova alocação e atualiza a origem. Aguarde a recarga antes de repetir o movimento para que a matriz reflita o servidor.
:::

:::WorkflowBlockItem
**Desalocar ou trocar a célula**

Para retirar uma Feature do plano, arraste-a de volta ao poço Não planejado; isso remove a alocação. Para trocar de iteração ou Time, arraste para a nova célula. Se uma gravação falhar, o board recarrega e restaura a posição conhecida pelo servidor, em vez de manter uma posição apenas visual.
:::

:::WorkflowBlockItem
**Registrar dependências entre Features**

No cartão Nova dependência, selecione a Feature de origem e a Feature de destino. Defina risco baixo, médio ou alto, data Needed by, responsável e uma nota. A origem e o destino precisam ser diferentes. As dependências salvas aparecem em Visual dependencies e podem ser abertas para alterar status ou remover o registro.
:::

:::WorkflowBlockItem
**Revisar capacidade e objetivos**

Antes de encerrar o planejamento, compare o número de Features com os objetivos do PI, observe o percentual de capacidade e filtre cada Time. Use as dependências para discutir bloqueios entre Times. Um cartão no poço não está comprometido com uma iteração; só considere a Feature planejada depois que a célula tiver sido gravada.
:::
::::

:::hint{type="success"}
:FontAwesome[]{icon="fa-solid fa-check"} **Verificação**

- O Backlog mostra Features reais do ART, com Épico, Times, WSJF, estado e PI candidato.
- O Planning Board apresenta uma coluna Não planejado, uma linha por Time e uma coluna por iteração.
- Depois de alocar, o cartão aparece na célula Time × Iteração e deixa de ser contado no poço.
- Ao devolver o cartão ao poço, a alocação desaparece após a confirmação do servidor.
- A dependência criada aparece em Visual dependencies com risco, origem, destino e proprietário.
:::

:::hint{type="info"}
****:FontAwesome[****]{icon="fa-solid fa-triangle-exclamation"}**&#x20;Erros comuns**

**Alocação incompleta**

O formulário exige Feature, Time e Iteração. Se algum campo estiver vazio, o Agility mostra a mensagem de alocação incompleta e não faz chamada à API.

**Não há candidatos para alocar**

Sem Features, Times ou iterações, o cartão de alocação informa que não existem candidatos. Cadastre ou configure esses elementos no ART e no PI antes de planejar.

**Dependência com uma única Feature**

O formulário exige pelo menos duas Features e rejeita a mesma Feature como origem e destino. Escolha duas entregas distintas do board.

**Cartões não arrastam**

O arraste é desabilitado em uma sessão sem capacidade de edição. Use a sessão autorizada ou consulte o board em modo de leitura; não confunda essa proteção com ausência de dados.

**Falha ao soltar o cartão**

Se a gravação da célula falhar, aparece um alerta e o board recarrega para desfazer a posição otimista. Confirme a mensagem, aguarde a recarga e tente novamente somente após verificar a capacidade e a origem do cartão.
:::


[title] Manual do Usuário
[path] Aplicações/B.I/

## 1. Antes de começar

***

### Entrar

O acesso é pelo **Keycloak** — não há login próprio da plataforma. Ao abrir o endereço, você é levado à tela de autenticação da empresa e volta autenticado.

O **espaço de trabalho** (tenant) vem do seu usuário. Cada espaço tem os próprios dados, conexões e painéis: o que você vê é o do seu espaço, sempre.

***

### A barra superior

| Elemento | Para que serve                                                                                              |
| -------- | ----------------------------------------------------------------------------------------------------------- |
| Idioma   | Português, English, Español, Français. Muda a interface na hora.                                            |
| 🌙 / ☀️  | Alterna entre tema claro e escuro.                                                                          |
| 🔔 Sino  | Alertas e insights do Pulse (ver [Automação](https://docs.citsmart.com/TDbT-manual-do-usuario#12-automao)). |
| Seu nome | Identifica a sessão.                                                                                        |
| Sair     | Encerra a sessão.                                                                                           |

***

### O menu lateral

Quatro grupos:

- **Análise & Preparação** — Explorar, Datasets, Fluxos de dados, Modelagem, SQL Lab, Galeria
- **Visualização** — Páginas/Dashs/Apps, Relatórios, Portal Análise Dados, Portal de Relatórios
- **Automação & IA** — Automação, Conhecimento, Conectores LLM
- **Administração** — Conexões, Histórico, Perfis de Acesso, Configurações

O menu pode ser recolhido para ganhar espaço horizontal. **O que aparece nele depende dos seus perfis** — ver [Perfis de Acesso](https://docs.citsmart.com/TDbT-manual-do-usuario#perfis-de-acesso).

***

### O caminho mais curto para o primeiro gráfico

1. **Explorar → Enviar arquivo** e escolha um CSV, Excel, JSON ou Parquet.
2. Arraste um campo para **Dimensões** e outro para **Medidas**.
3. Escolha o **Tipo de apresentação**.
4. **Salvar no dashboard**.

***

## 2. Conceitos da plataforma

Vale ler esta seção uma vez: quase toda dúvida de uso nasce de confundir dois destes conceitos.

| Conceito                      | O que é                                                                                                                   |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| **Conexão**                   | O acesso a uma origem: banco, API REST, arquivo. Guarda endereço e credencial.                                            |
| **Dataset**                   | Uma tabela consultável na plataforma, com campos classificados em dimensões e medidas. É a matéria-prima de toda análise. |
| **Consulta salva**            | Uma análise montada no Explorar e guardada com nome. Pode ser reaproveitada em painéis e páginas.                         |
| **Dashboard**                 | Uma grade de widgets com filtros globais.                                                                                 |
| **Página**                    | Uma composição livre de blocos — inclui texto, botões, vídeo e conteúdo incorporado, além de gráficos.                    |
| **Aplicação**                 | Um conjunto de páginas e dashboards navegáveis como um produto só, com ícone, cor e tela inicial.                         |
| **Relatório**                 | Um documento em seções, feito para ser exportado em PDF, Excel, Word ou PowerPoint.                                       |
| **Fluxo de dados**            | Uma sequência de passos que transforma uma ou mais origens e gera um dataset novo.                                        |
| **Modelo**                    | Tabelas de uma conexão ligadas por relacionamentos, que geram um dataset sem escrever SQL.                                |
| **Documento de conhecimento** | Regra de negócio, glossário ou definição em Markdown, consultado pela IA e exibível nos widgets.                          |

***

### Dashboard, Página ou Relatório?

- **Dashboard** quando o objetivo é *acompanhar*: números lado a lado, filtros no topo, atualização periódica.
- **Página** quando o objetivo é *conduzir*: texto explicativo entre os gráficos, parâmetros, botões de ação.
- **Relatório** quando o objetivo é *entregar*: o material vai virar arquivo e circular por e-mail.

***

## 3. Explorar — o construtor de análises

É a tela onde as análises nascem.

***

### Painel de fontes (esquerda)

- **Enviar arquivo** — CSV, Excel, JSON ou Parquet viram dataset na hora.
- **Conectar fonte de dados** — banco ou API REST (ver [Conexões](https://docs.citsmart.com/TDbT-manual-do-usuario#14-conexes)).
- **Nova planilha (digitar dados)** — cria um dataset digitando os dados à mão, útil para metas, orçamentos e tabelas de apoio.
- **Datasets** e **Consultas salvas** — o que já existe, com busca.

***

### Painel de campos

Os campos do dataset, separados em **Dimensões** (o que agrupa), **Medidas** (o que se soma) e **Métricas** (cálculos nomeados, reutilizáveis).

O botão f+ cria um **campo calculado**; o Σ ao lado de uma métrica indica um cálculo salvo no dataset.

***

### Montando a análise

1. **Tipo de apresentação** — 36 formatos (ver [referência](https://docs.citsmart.com/TDbT-manual-do-usuario#16-referncia-rpida)).
2. **Dimensões** — arraste os campos que agrupam.
3. **Medidas** — arraste os campos numéricos; escolha a agregação (SUM, AVG, MIN, MAX, COUNT, COUNT DISTINCT, mediana, P90, P95, desvio padrão, variância).
4. **Filtros** — arraste campos para restringir.
5. **Segmentos** — salve o conjunto de filtros atual com um nome e reaplique depois em um clique.

***

### Os três popovers de ajuste

- **Formatação** — paleta, título, títulos dos eixos, formato dos números, rótulos, empilhamento, orientação, legenda, opções da tabela dinâmica.
- **Interação** — o que acontece ao clicar: detalhar, filtrar o painel, abrir uma URL, abrir outro dashboard, ou nada.
- **Análise** — linha de tendência, linha de média, linha de referência (meta), previsão, agrupamento (k-means).

***

### A barra de ações

| Botão                   | O que faz                                                                                                |
| ----------------------- | -------------------------------------------------------------------------------------------------------- |
| **Salvar**              | Grava a consulta. Se já estava aberta uma, atualiza; a mensagem confirma qual das duas coisas aconteceu. |
| **Salvar como…**        | Cria uma consulta nova a partir da atual.                                                                |
| **CSV**                 | Baixa o resultado.                                                                                       |
| **Prever**              | Projeta os próximos períodos de uma série.                                                               |
| **Insights**            | Resumo executivo e anomalias detectadas. Permite **assinar a métrica no Pulse**.                         |
| **Consulta**            | Mostra o SQL gerado — útil para conferir ou levar a outra ferramenta.                                    |
| **Form. condicional**   | Regras que colorem as células (ver abaixo).                                                              |
| **Indicadores**         | Colunas de sinalizadores (ver abaixo).                                                                   |
| **Salvar no dashboard** | Envia a análise para um painel.                                                                          |
| **Modo foco**           | Esconde a configuração e amplia o gráfico.                                                               |

***

### Formatação condicional

Disponível em **Tabela** e **Dinâmica**. Três tipos de regra:

- **Escala de cor** — o valor pinta a célula em um degradê.
- **Barra de dados** — uma barra proporcional dentro da célula.
- **Limiar** — pinta quando o valor passa de um limite (>, ≥, \<, ≤, =).

O campo **Regra por texto** aceita linguagem natural (“destaque em vermelho vendas abaixo de 1000”) e a IA monta a regra.

O painel pode ser **redimensionado pelo canto**, e o tamanho fica guardado.

***

### Colunas de indicador

Também em **Tabela** e **Dinâmica**. É a ideia dos conjuntos de ícones do Excel: o valor cai numa faixa e a faixa define um símbolo.

Seis conjuntos prontos — **Semáforo, Setas, Sinais, Bandeiras, Bolinhas, Estrelas** — e o campo do símbolo aceita **qualquer emoji ou texto curto** colado.

Ao criar, os limites já vêm sugeridos a partir dos terços do intervalo real da coluna, arredondados. Ajuste-os à sua régua.

**As faixas valem de cima para baixo: a primeira que casar define o símbolo.**

Cada indicador escolhe **onde aparece**:

- **Em coluna própria** — uma coluna nova à direita. Na dinâmica, ela avalia o **total da linha**: o sinal fala da linha inteira.
- **Dentro da célula do valor** — o símbolo entra na célula, como no Excel. Na dinâmica é a única forma de sinalizar **célula a célula**.

Para ter os dois, crie dois indicadores sobre a mesma medida.

***

### Tabela dinâmica

A barra própria da dinâmica oferece:

- **Expandir tudo / Recolher tudo** e o seletor de **Níveis**
- **Escalonado** (hierarquia recuada numa coluna) ou **Colunas** (uma coluna por dimensão)
- **Trocar eixos** — leva as dimensões de linha para as colunas e vice-versa
- **Subtotais** e **Col. total**
- **Heatmap** — colore as células por escala
- **CSV**

Arraste a divisa entre as colunas para redimensioná-las.

***

### Detalhar um ponto

**Duplo clique** em uma barra, fatia ou célula abre a janela de **Detalhe** com as linhas por trás daquele número.

- Datas e valores saem formatados conforme a configuração do sistema.
- Os cabeçalhos usam o **Rótulo** do cadastro do dataset (o nome técnico fica na dica da coluna).
- **Copiar** leva a tabela para a área de transferência **separada por TAB** — colando no Excel, cai direto nas células.

***

### Análise de IA

Um dos tipos de apresentação. Em vez de um gráfico, a plataforma escreve a leitura dos dados em texto. O campo **Pergunta** direciona a análise (“compare com o mês anterior e aponte o que explica a queda”). Exige um conector LLM configurado.

***

## 4. Datasets

A tela lista os datasets do espaço. Ao editar um, há seis abas.

***

### Identidade

Nome, descrição e a marca **Fonte certificada (confiável)**, que sinaliza aos demais usuários que aquele dataset é oficial.

Mostra também a **origem** — e avisa quando a conexão de origem não existe mais: o dataset continua consultável com o que já foi materializado, mas **não consegue se atualizar**.

***

### Campos

Cada campo tem:

- **Rótulo** — o nome que aparece nas telas. É o que resolve sum\_valor\_da\_venda virar “Valor da Venda” em filtros, parâmetros e no detalhe.
- **Papel** — Dimensão ou Medida.
- **Tipo** — o tipo do dado.

Edite quantos quiser e use **Salvar campos** para gravar todos de uma vez; o contador mostra quantos estão com alteração pendente.

**+ Campo calculado** cria uma coluna por expressão SQL, por exemplo (receita - custo) / nullif(receita, 0).

***

### Acesso

Os perfis (roles) que podem ver e usar o dataset no Explorar. **Vazio = visível a todos.** Administradores sempre veem.

***

### Sincronização

Define com que frequência os dados são trazidos da origem — vale para todas as consultas e painéis que usam o dataset.

- **Intervalo** (minutos, horas, dias) ou **expressão CRON** de cinco campos, com conferência dos próximos disparos.
- **Como atualizar**:
- **Completa** — recarrega a origem inteira. Sempre fiel, mais cara.
- **Incremental** — traz só o que mudou desde a última vez. Exige uma **coluna de avanço** (crescente: data de atualização ou id sequencial) e as **colunas que identificam a linha**.

**Atenção com a carga incremental:** ela não enxerga linhas **excluídas** na origem. Configure a **recarga periódica de reconciliação** — é o que impede a diferença de se acumular, e o melhor uso da expressão CRON, para cair fora do horário de pico.

***

### Dados

Edita as células diretamente (até 500 linhas de amostra). É como se mantém uma planilha de metas ou uma tabela de apoio criada na plataforma.

***

### SQL

Para datasets vindos de consulta: permite trocar o SQL que os alimenta.

***

## 5. Fluxos de dados

Um fluxo transforma dados e **gera um dataset**. É a alternativa ao SQL para quem prefere montar a transformação passo a passo — e ao mesmo tempo comporta SQL e JavaScript onde eles forem necessários.

***

### Estrutura

- **Origens** — os datasets de entrada, cada um com um **apelido** usado nos passos.
- **Variáveis** — valores reaproveitáveis, escritos como $ dentro dos passos. Há 15 embutidas (data e hora atuais, última execução, usuário, espaço).
- **Passos** — a sequência de transformações.
- **Resultado final** — o passo que vira dataset.

***

### Prévia

Cada passo mostra o resultado **daquele ponto**, com contagem de colunas e linhas de amostra. É assim que se confere a transformação sem executar o fluxo inteiro.

A prévia **não chama** serviços externos: passos de IA e de API aparecem com as colunas vazias. Use o **Testar** do próprio passo e depois **Executar**.

***

### Passos disponíveis

**Preparar** — Filtrar linhas · Colunas · Coluna calculada · Converter tipo · Ordenar · Limitar linhas · Remover duplicatas · Substituir texto · Dividir coluna

**Combinar** — Juntar (LEFT, INNER, FULL, ANTI, SEMI) · Empilhar · Juntar por semelhança (Jaro-Winkler ou Levenshtein)

**Remodelar** — Agrupar e resumir · Colunas viram linhas · Linhas viram colunas

**Análise avançada** — Detectar anomalias (z-score ou IQR, comparando dentro de cada grupo) · Faixas de valor (quantis ou intervalos iguais) · Normalizar escala · Correlação · Agrupar semelhantes (k-means) · Prever série · Preencher faltantes

**Código e IA** — SQL · Código (JavaScript) · Definir variável · Perguntar à IA · Buscar de API

***

### Passo SQL

O passo anterior chega como entrada e as origens pelo apelido. É **uma consulta só**, sem ponto e vírgula. Use $\{variável} onde entra uma data de corte ou um parâmetro.

***

### Passo Código (JavaScript)

Recebe a linha (ou todas as linhas, no modo tabela) e a lista de variáveis. O painel lateral mostra **como a linha chega**, com a amostra real e os cuidados — principalmente com valores nulos, que derrubam o passo se usados sem verificação.

***

### Passo Perguntar à IA

Classifica, extrai ou resume o conteúdo de cada linha com um modelo de linguagem. Traz exemplos prontos (Classificar, Extrair, Resumir, Sentimento).

**Custo:** cada pergunta **distinta** é uma chamada paga. Linhas que geram a mesma pergunta são perguntadas **uma vez só** — classificar mil linhas em dez categorias custa dez chamadas. Há uma trava de **máximo de linhas**.

***

### Passo Buscar de API

Três modos: **Enriquecer cada linha** (uma chamada por valor distinto), **Empilhar o resultado** ou **Juntar por chave**. Também tem trava de linhas e um **Testar em 5 linhas**.

***

### Agendamento

Depois da primeira execução bem-sucedida, o fluxo pode rodar sozinho na frequência escolhida.

***

## 6. Modelagem

Conecta tabelas de uma fonte, sugere os relacionamentos e gera datasets **sem escrever SQL**.

1. Escolha a **conexão** à esquerda e clique nas tabelas para adicioná-las.
2. As **relações prováveis aparecem sozinhas** — confirme, ajuste o tipo de junção ou remova.
3. Defina a **tabela base**.
4. **Ver SQL** para conferir o que foi montado; **Gerar dataset** para materializar.

Cada relacionamento tem a opção **Prevenir fan-out**, que evita que uma junção de um-para-muitos infle as medidas.

O modelo pode ser **ao vivo** (consulta a fonte a cada uso, com pushdown) ou **materializado** (copia para o motor analítico).

***

## 7. SQL Lab

Para quem escreve SQL.

- **Schema** — as tabelas disponíveis; clique para ver as colunas. JOIN é permitido.
- **Salvas** — suas consultas SQL guardadas.
- **Gerar SQL** por linguagem natural — descreva a consulta e revise o que a IA escreveu antes de executar.
- **Data Manager** — selecione dois ou mais datasets e a plataforma **sugere associações prováveis**, analisando nomes de colunas, tipos e sobreposição real de chaves, com percentual de confiança. Gera o SQL do modelo.
- **Unir (append)** — empilha datasets alinhando colunas por nome.
- **Materializar como dataset** ou **Criar gráfico** a partir do resultado.
- **Histórico** de execuções, para reaproveitar um SQL já rodado.

***

## 8. Galeria de modelos

Modelos prontos de dashboards, relatórios e apps, filtráveis por setor.

Escolha o modelo, aponte o **dataset** e a plataforma monta a estrutura — os campos do modelo são mapeados automaticamente para as colunas escolhidas.

Você também pode transformar seus próprios dashboards e relatórios em modelos, pelo botão **Modelo** dentro deles.

***

## 9. Páginas, Dashboards e Aplicações

Uma tela só reúne os três, porque eles se compõem.

***

### Dashboards

Uma grade de widgets. Cada widget tem cabeçalho com as ações:

- **↑ ↓** ordenam
- **Inteira / ½ / ⅓** definem a largura
- **✎** abre o construtor
- **📖** vincula conhecimento (ver abaixo)
- **✕** remove

Arraste a alça do canto inferior direito para mudar a altura.

### Barra superior:

| Recurso                             | O que faz                                       |
| ----------------------------------- | ----------------------------------------------- |
| Auto-refresh                        | Reconsulta em intervalo fixo.                   |
| Ao vivo                             | Reconsulta quando um dataset usado muda.        |
| Tema e tela cheia                   | Só para exibição.                               |
| 🔒                                  | Trava o layout contra arrasto acidental.        |
| + Seção / + Card / + Consulta salva | Acrescenta conteúdo.                            |
| PDF                                 | Exporta o painel.                               |
| ⭐ 🔗 \</> 🗑                        | Favoritar, link público, incorporação, excluir. |
| Comentários                         | Discussão anexada ao painel.                    |

**Filtros** aceitam três tipos de campo — valor (multisseleção), numérico (intervalo) e data (intervalo) — e oferecem:

- **Escopo por widget** — a quais widgets cada filtro se aplica.
- **Cascata** — as opções de um filtro refletem os demais filtros ativos.

Clicar num ponto do gráfico aplica **cross-filter** ao painel, conforme a configuração de Interação da análise.

**Retratos (versões)** guardam o estado do painel — capturados diariamente e a cada clique — e permitem **comparar dois retratos** indicador a indicador.

***

### Páginas

Composição livre, em **fluxo vertical** ou **grade**. Tipos de bloco:

| Bloco                          | Para que serve                                                                                |
| ------------------------------ | --------------------------------------------------------------------------------------------- |
| **Texto**                      | Markdown: títulos, listas, ênfase.                                                            |
| **Gráfico / Tabela / Métrica** | Dados, montados ali ou vindos de uma consulta salva.                                          |
| **Parâmetro**                  | Um seletor que filtra os demais blocos da mesma fonte de dados. Aceita multisseleção.         |
| **Ação**                       | Botão: navegar, definir parâmetro, disparar evento, abrir relatório, gravar dado, abrir link. |
| **HTML / Vídeo / Incorporar**  | Conteúdo próprio, YouTube ou iframe externo.                                                  |

***

### Aplicações

Reúnem páginas e dashboards existentes como **telas** de um produto só, com nome, descrição, ícone, cor e **tela inicial**. Dois modos:

- **Estrutura** — editar telas, identidade e acesso.
- **Executar** — navegar como o usuário final.

***

### Conhecimento no widget

O ícone 📖 no cabeçalho aparece **quando há orientação vinculada** — e só quando há. Duas formas, que servem a coisas diferentes:

- **Nota do widget** — o que vale só ali: *“este total exclui devoluções”*.
- **Documentos da base** — o que vale em muitos lugares: a definição de “cliente ativo”, a regra de rateio. Escritos uma vez, corrigidos uma vez, e a correção chega a todo widget que aponta para eles.

Nas telas públicas aparece **apenas a nota**. Os documentos da base exigem sessão, e publicá-los junto com o link exporia material interno.

***

### Consultas salvas vinculadas

Ao arrastar uma **consulta salva** para um painel ou página, fica registrado de qual consulta ela veio — o ícone de elo no cabeçalho indica isso. A configuração é lida da origem a cada abertura, inclusive no PDF e nas telas públicas.

- **Editar o widget no construtor desfaz o vínculo** (com aviso): a partir dali as mudanças valem só naquele painel.
- Se a consulta for **apagada**, o widget continua funcionando com a última configuração conhecida.

***

### Compartilhamento

- **Acesso por perfil** — quais roles podem abrir.
- **Link público** — endereço que dispensa login. Pode ser revogado.
- **Incorporação** — código para embutir em outro sistema, com filtros travados no servidor.



## 10. Relatórios

Documentos em seções, feitos para virar arquivo.

***

### Seções

| Tipo          | Conteúdo                                                                                 |
| ------------- | ---------------------------------------------------------------------------------------- |
| **Texto**     | Markdown, com marcadores de data e nome do relatório.                                    |
| **Tabela**    | Listagem simples (com escolha e rótulo das colunas, e subtotais por campo) ou agregação. |
| **Gráfico**   | Barras, linhas, área ou pizza.                                                           |
| **Parâmetro** | Um seletor que filtra as demais seções da mesma fonte de dados.                          |

Cada seção tem título, formato dos números, limite de linhas e largura (inteira ou metade — duas meias formam uma linha).

***

### Gráfico: legenda

**Mostrar legenda** liga e desliga; **Texto da legenda** troca o nome da série. O campo mostra como placeholder o nome atual (sum\_vendas), e apagá-lo volta ao original.

Na pizza a legenda lista as fatias, e o texto vem dos próprios dados — por isso o campo não aparece ali.

***

### Parâmetros

Mesmo desenho do bloco de parâmetro das Páginas: fonte de dados, campo, rótulo e multisseleção. O recorte é **por fonte de dados** — um parâmetro de uf não filtra seção que lê outra tabela.

**Os parâmetros valem também nos arquivos exportados**, e cada formato registra o recorte aplicado: parágrafo no PDF, resumo no Excel, cabeçalho no Word, capa no PowerPoint. Um arquivo filtrado que não diz por qual valor engana quem o receber adiante.

***

### Exportação

**PDF**, **Excel**, **Word** e **PowerPoint**. O PDF desenha os gráficos com a mesma paleta da tela.

**Modelo** transforma o relatório num modelo reaproveitável na Galeria.

***

## 11. Portais

Duas telas de consumo, para quem usa e não constrói:

- **Portal Análise Dados** — tudo que você tem permissão de executar: dashboards, páginas e aplicações, em cards ou listagem, com busca.
- **Portal de Relatórios** — os relatórios que você pode ver, já com os botões de exportação.

***

## 12. Automação

Cinco recursos, na mesma tela.

***

### Envio agendado de relatórios

Escolha o relatório, os destinatários, o formato do anexo e a frequência — **intervalo** ou **expressão cron** de seis campos (ex.: 0 0 8 \* \* MON-FRI = dias úteis às 8h), com fuso horário. **Enviar agora** testa na hora.

***

### Alertas por condição de dado

Vigiam uma consulta salva e disparam quando o valor passa de um limiar (maior que, menor que, igual a) ou quando foge do padrão (**anomalia por desvio σ**).

Canais: **e-mail**, **in-app (sino)** e **webhook**.

**Testar** mostra o valor atual e se dispararia agora.

***

### Entrega de dados agendada

Exporta o resultado de uma consulta salva — com seus filtros — em CSV ou XLSX e envia por e-mail no intervalo ou cron definido.

***

### Gatilhos por evento de negócio

Disparam e-mail ou relatório **quando o sistema de origem chama o webhook** — por exemplo, um pedido confirmado. Copie a URL gerada e configure no sistema transacional. Nos textos de assunto e corpo, use  e os campos do payload como .

***

### Pulse — insights proativos

Assine uma métrica pelo botão **Assinar no Pulse**, dentro do modal **Insights** do Explorar. O Pulse verifica periodicamente e avisa no **sino** (e por e-mail) quando surge uma anomalia ou tendência — sem você precisar procurar.

Sem SMTP configurado, os envios ficam em **dry-run**: são registrados no log do servidor, mas não saem. Ver [Configurações](https://docs.citsmart.com/TDbT-manual-do-usuario#configuraes).

***

## 13. Conhecimento e IA

***

### Conhecimento

A base que a IA consulta ao responder — e de onde saem as orientações exibidas nos widgets.

Organize **pastas** e **documentos Markdown**. Crie na tela ou faça **upload** de .md, .txt, .csv, .json, .docx.

Cada documento pode ser **vinculado a datasets**: sem marcar nenhum, vale como conhecimento geral; marcando, o assistente usa aquele documento apenas nas conversas sobre os datasets escolhidos.

***

### Conectores LLM

Os modelos de linguagem que a plataforma usa. Provedores suportados:

| Provedor                    | Observação                                       |
| --------------------------- | ------------------------------------------------ |
| **Anthropic**               | Chave em console.anthropic.com                   |
| **OpenAI**                  | Chave em platform.openai.com                     |
| **Google Gemini**           | Chave no Google AI Studio                        |
| **Ollama (local)**          | Roda na sua infraestrutura; não precisa de chave |
| **vLLM (servidor próprio)** | Servidor compatível com a API da OpenAI          |

Um conector precisa estar **ativo** e marcado como **padrão** — sem isso, os recursos de IA não têm a quem perguntar. **Testar** confirma que o modelo responde.

Ollama e vLLM rodam na sua infraestrutura e **não mandam dado nenhum para fora**.

***

### O assistente (botão IA)

Presente no canto inferior direito. Permite:

- **Conversar com os dados** em linguagem natural, com perguntas de acompanhamento; a IA responde em texto **e monta o gráfico**.
- **Gerar insights automáticos** sobre um dataset.
- **Gerar um painel ou página inteiros** a partir de uma descrição (“vendas por região e evolução mensal”), com a opção de salvar ou descartar.
- **Falar** em vez de digitar, nos navegadores com reconhecimento de voz.

***

## 14. Conexões

***

### Tipos suportados

**Banco de dados**, agrupados por família:

- **Relacional (SQL)** — PostgreSQL, MySQL, SQL Server, SQLite (arquivo) e afins
- **Data warehouse (nuvem)**
- **Query engine / OLAP** — inclui OpenSearch, cujos **índices** aparecem como tabelas
- **Big Data (Hadoop)**
- **Object storage** — Parquet/CSV por URI, com região e endpoint MinIO opcional
- **NoSQL**

**API REST**, com autenticação **Nenhuma**, **Basic**, **Token/JWT (Bearer)** ou **cabeçalho personalizado (API key)**, cabeçalhos extras e **Caminho JSON** para quando os registros vêm dentro de um envelope (resultado.itens).

**Testar API** confere antes de salvar.

***

### Importar

Ao conectar, a plataforma lista as tabelas (ou índices). Selecione as que interessam: **cada uma vira um dataset** com o nome da tabela.

***

### A tela Conexões (Administração)

Manutenção do que já existe: renomear, trocar parâmetros, **testar**, excluir e definir **quais perfis podem mexer** em cada conexão.

Aqui, **nenhum perfil marcado = só administrador** — o oposto dos datasets, onde lista vazia libera. A diferença é proposital: nos datasets se lê dado; aqui se altera a credencial de um banco.

Excluir uma conexão em uso avisa quantos datasets deixarão de se atualizar.

***

## 15. Administração

***

### Histórico

Registro de acessos aos componentes de BI: quando, quem, tipo e componente.

***

### Perfis de Acesso

Define **quais funcionalidades cada perfil (role) pode acessar** — é o que decide o menu de cada usuário.

Regras que valem a pena conhecer:

- Administradores sempre acessam tudo.
- Um usuário **sem nenhuma funcionalidade concedida** enxerga o sistema sem restrição de menu. É proposital: evita travar o acesso de todos por um cadastro incompleto.

**Segurança em nível de linha (RLS)** fica na mesma área:

1. Dê **atributos** ao usuário (regiao=Sul).
2. Crie a **regra por dataset**: linhas onde o campo regiao = o atributo regiao do usuário.

A partir daí, cada pessoa vê apenas as linhas que lhe cabem, em qualquer tela.

***

### Configurações

**Formato de data e moeda** — data, hora, moeda, separadores e casas decimais, com prévia. Vale para Explorar, Relatórios, dashboards e páginas.

“Segue o idioma” usa a convenção do idioma escolhido na barra superior. Prefira um **formato fixo** quando o material precisa sair igual para todo mundo.

**E-mail (SMTP)** — remetente, host, porta, usuário e senha. Sem **habilitar envio real**, tudo fica em dry-run.

**Backup e portabilidade** — exporta todos os elementos criados (dashboards, consultas, relatórios, automação, configurações) num único .json, e importa um pacote para restaurar ou migrar. Os **dados brutos das fontes não são incluídos** — apenas as definições. A inclusão de segredos (senhas e chaves) é opcional e explícita.

***

## 16. Referência rápida

***

### Tipos de apresentação

**Comparação** — Barras · Linhas · Área · Combinado · Cascata · Tornado · Bullet · Marimekko

**Composição** — Pizza · Rosca · Treemap · Sunburst · Funil · Stream graph

**Relação** — Dispersão · Bolhas · Correlação em matriz (heatmap) · Radar · Coordenadas paralelas · Sankey · Grafo · Árvore

**Distribuição** — Histograma · Boxplot

**Evolução no tempo** — Calendário · Gantt · Candlestick · Pulse

**Número único** — KPI · Tendência · Medidor (gauge)

**Tabelas** — Tabela · Tabela dinâmica

**Geográfico** — Mapa (país, UF, cidade, bairro)

**Texto** — Nuvem de palavras

**Narrativa** — Análise de IA

***

### Agregações

SUM · AVG · MIN · MAX · COUNT · COUNT DISTINCT · MEDIAN · P90 · P95 · STDDEV · VARIANCE

***

### Formatos de número

| Formato    | Exemplo     |
| ---------- | ----------- |
| Número     | 1.234,56    |
| Milhares   | 1.235       |
| Moeda      | R$ 1.234,56 |
| Percentual | 1.234,6%    |

O símbolo da moeda e os separadores vêm das **Configurações** do espaço.

***

## 17. Perguntas frequentes

**Alterei uma consulta salva e o painel não mudou.** Painéis criados antes da versão que introduziu o vínculo guardam uma cópia solta. Adicione a consulta ao painel novamente: a partir daí ele acompanha a origem.

**Um campo aparece com nome técnico (sum\_vendas) nos filtros.** Preencha o **Rótulo** do campo em *Datasets → Campos*. Ele vale para filtros, parâmetros, cabeçalhos e para a janela de detalhe.

**O e-mail não chega.** Confira em *Configurações → E-mail* se **Habilitar envio real** está ligado. Sem isso, os envios ficam em dry-run e só aparecem no log do servidor.

**Os recursos de IA estão indisponíveis.** É preciso um conector em *Conectores LLM* que esteja **ativo** e marcado como **padrão**.

**A carga incremental está deixando linhas para trás.** A carga incremental não enxerga exclusões na origem. Configure a **recarga periódica de reconciliação** na aba Sincronização do dataset.

**O dataset parou de se atualizar.** Veja a aba *Identidade*: se a conexão de origem foi excluída, o dataset continua consultável com o que já foi materializado, mas não se atualiza mais.

**Não consigo ver um menu que meu colega vê.** O menu depende dos perfis. Peça a um administrador para conferir em *Perfis de Acesso*.

**Preciso que os números saiam iguais para todo mundo, em qualquer idioma.** Em *Configurações → Formato*, escolha um formato **fixo** em vez de “Segue o idioma”.

*Este manual descreve a plataforma como ela está. Recursos e telas evoluem — em caso de divergência, a tela é a referência.*

[title] Gestão de benefícios
[path] Aplicações/ERP/Manual do Usuário/

## Introdução

***

Hoje cada benefício vive onde o fornecedor colocou: o vale-refeição no portal da operadora, o plano de saúde em outro, a premiação por fora. Ninguém consegue responder de cabeça quantos benefícios a organização concede, quanto cada um custa por mês e para qual fornecedor vai o dinheiro.

O módulo de **Benefícios** começa por resolver isso: um cadastro central onde cada benefício tem o seu nome, o **regime** que o rege, os **fornecedores** que o atendem e a **configuração financeira** de onde sai o pagamento.

:::BlockQuote
**O regime não é burocracia.** Vale-refeição e vale-alimentação seguem as regras do PAT; vale-transporte segue a lei do vale-transporte; premiação não segue nenhum dos dois. Marcar isso no cadastro é o que vai permitir ao sistema avisar quando uma regra específica de um desses regimes estiver prestes a ser quebrada — em vez de a organização descobrir numa fiscalização.
:::

## Passo a passo

***

### Cadastrar um benefício

1. **Abra "Benefícios".** Menu **Benefícios → Benefícios**. A lista mostra cada benefício com código, nome, regime e situação.
2. **Novo benefício.** Informe o **código** (único), o **nome**, o **regime** que o rege e, se quiser, uma descrição. Se o código já estiver em uso, o sistema recusa **dizendo qual benefício o ocupa** — não um "código já existe" genérico.
3. **Sem essa rubrica, o desconto não aparece sozinho no holerite.** É a armadilha desta tela: tudo o mais funciona — o cálculo, o título financeiro, o relatório — e só na hora de rodar a folha alguém descobre que o desconto teria de ser digitado à mão.
   **Deixe em branco se a folha desta organização roda em outro sistema.** O benefício continua funcionando exatamente como antes e o desconto continua saindo pelo arquivo de exportação. Em branco significa "este benefício não chega ao holerite daqui" — e o processamento diz isso, benefício por benefício, em vez de inventar uma rubrica.
   **Diga qual rubrica leva o desconto ao holerite.** No campo **Rubrica de desconto na folha**, escolha a rubrica que carrega o desconto do colaborador no holerite. A lista traz **apenas rubricas de desconto** — apontar o vale-transporte para um provento *pagaria* ao colaborador o valor que a organização está descontando, e o sistema recusa se você tentar.
4. **Benefício não é apagado, é inativado.** Concessões e pagamentos apontam para ele; apagar levaria o rastro junto.

### Associar os fornecedores

1. **Se você associar o fornecedor depois, o sistema recupera as concessões já feitas.** Ao enviar o cadastro ao emissor, as concessões daquele benefício que estavam sem fornecedor recebem este — **desde que ele seja o único fornecedor ativo do benefício**. Havendo dois ou mais, o sistema não escolhe por você: a operadora de cada colaborador é decisão dele, e essas concessões continuam aparecendo no aviso da apuração até alguém dizer. Antes disso, uma concessão feita sem fornecedor ficava inalcançável para sempre, e a tela do emissor respondia *"aceitos: 0 · recusados: 0"* sem explicar por quê.

**Sem fornecedor ativo, a concessão individual é recusada — e a apuração em lote concede assim mesmo, avisando.** Os dois caminhos são diferentes de propósito: o repasse à folha não precisa de fornecedor, então o plano de saúde continua chegando ao holerite e o colaborador continua recebendo o que lhe é devido. O que essas concessões **não** conseguem é chegar a um emissor de cartão — e é isso que a apuração diz, nomeando o benefício, em vez de terminar com cara de sucesso.

**Mais de um fornecedor é o esperado, não a exceção.** Desde que a portabilidade entre operadoras passou a ser obrigatória e gratuita, dois colaboradores da mesma organização podem estar em operadoras diferentes, por escolha deles. Por isso a escolha do fornecedor acontece **por colaborador, na concessão** — este cadastro apenas diz quais estão disponíveis.

**Com o benefício selecionado**, use o bloco **Fornecedores**. Escolha o parceiro e, se o emissor do cartão tiver um identificador próprio para o acordo, informe a **referência no emissor**.

### Informar de onde sai o dinheiro

1. **Cadastrar uma configuração nova não apaga a anterior.** Se a nova começa depois, o sistema **encerra a atual na véspera** daquela data. A anterior continua legível — é ela que responde para onde foi um pagamento do ano passado, quando alguém for conciliar o razão.
   **No bloco "De onde sai o dinheiro"**, informe a **conta bancária**, a **natureza financeira** e a data em que a configuração passa a valer.
2. **Veja o histórico.** Abaixo dos blocos aparece o histórico de alterações do benefício, com autor, data e os valores antes e depois — incluindo mudanças de fornecedor e de configuração financeira, porque para o auditor tudo isso é alteração *do benefício*.

### Definir quem recebe e quanto cada lado paga

Um benefício cadastrado ainda não alcança ninguém. Quem faz isso é a **regra**, no bloco **Elegibilidade e cálculo**, que responde a duas perguntas: **quem** recebe e **quanto** cada lado paga.

1. **Escolha o alcance.** *Todos*, um **grupo de beneficiários**, um **centro de custo**, um **departamento** ou um **cargo**. Qualquer alcance que não seja "Todos" exige apontar qual — o sistema recusa dizendo o que falta, porque um alcance sem referência acabaria valendo para a organização inteira sem ninguém ter pedido.
2. **O salário é digitado, e isso é deliberado.** Este sistema **não guarda o salário de ninguém** — a folha de pagamento é externa. Resolver o \{SALARY\_BASE} pelo meio da faixa salarial do cargo produziria um número plausível e errado para quase todo mundo, e errado na direção que o colaborador paga. Então ele entra como informação, e passará a vir sozinho quando o retorno da folha for importado. A faixa salarial continua disponível, com o nome que ela tem: \{SALARY\_BAND\_MIN}, \{SALARY\_BAND\_MID} e \{SALARY\_BAND\_MAX}, que são a **faixa do cargo**, não o que a pessoa ganha — e exigem informar o **nível**, porque a faixa pertence a um par cargo + nível.
   **Termo que o sistema não conhece é recusado pelo nome.** Se você escrever \{BONUS} e esse termo não existir, a mensagem diz exatamente qual termo não foi reconhecido, em vez de um "fórmula inválida" que obriga a reler a expressão caractere a caractere.
   **Escreva as duas fórmulas.** A da **empresa** é obrigatória; a do **colaborador** fica em branco quando o benefício não lhe custa nada. A fórmula é aritmética sobre uma lista fechada de termos, que a própria tela mostra ao lado do campo — por exemplo 22.50 \* \{WORKING\_DAYS} ou \{SALARY\_BASE} \* 0.06.
3. **Teste antes de salvar.** No bloco **Testar antes de salvar**, escolha um colaborador, informe o salário e os dias devidos, e clique em **Avaliar**. A tela mostra o valor e **cada parcela que o compôs**, para você conferir a conta antes de a regra chegar ao pagamento de alguém. Nada é salvo — mas a conferência **fica na trilha de auditoria**, porque ela lê os números de uma pessoa nomeada.
4. **Aviso de isonomia no PAT.** Se o benefício é regido pelo PAT e as regras vigentes produzem valores diferentes entre colaboradores, o sistema **avisa** e pede uma justificativa — e **salva mesmo assim**. Bloquear inviabilizaria a diferenciação por perfil; silenciar deixaria o enquadramento se perder sem ninguém ter decidido. A justificativa fica gravada **na regra**, não só em log: o aviso só significa alguma coisa se alguém responder pela decisão. O aviso aparece também quando existe **uma única regra** cuja fórmula varia por pessoa — o caso que passa despercebido, porque a lista de regras parece uniforme.

**Informe a prioridade.** Quando duas regras alcançam a mesma pessoa, vence a de **maior prioridade**, e o sistema informa qual foi aplicada. É um número que você controla — a alternativa, "a mais específica vence", ninguém consegue prever de cabeça.

### Montar um grupo de beneficiários

1. **Abra "Grupos de beneficiários".** Menu **Benefícios → Grupos de beneficiários**. Use-o quando o critério for um que o organograma não sabe expressar: o grupo piloto, quem aderiu, quem está sob um acordo coletivo específico.
2. **Grupo em uso não é desativado.** Enquanto uma regra ativa apontar para o grupo, desativá-lo é recusado. Se fosse permitido, o benefício pararia para todos que estão nele e a descoberta viria pelo pagamento, não pela tela.

**Crie o grupo e inclua as pessoas.** Um grupo vazio **não alcança ninguém** — uma regra apontando para ele concede nada, em silêncio.

### Apurar o mês

1. **Abra "Apuração de benefícios".** Menu **Benefícios → Apuração de benefícios**. Informe o **período** (AAAA-MM), os **dias devidos** no mês e escolha o tipo.
2. **Simule primeiro.** A simulação e o definitivo são **o mesmo cálculo** — o tipo decide apenas o destino do resultado. Então o que você confere linha por linha é exatamente o que vai valer, não uma aproximação que pode divergir.
3. **O sistema também avisa quando apurou sem saber quem esteve afastado.** "Ninguém se afastou" e "eu não tinha como saber" produzem os mesmos números, e só um dos dois é um fato. **O aviso segue as pessoas:** ele sai por quem ninguém soube responder, e cala quando os afastamentos estão registrados aqui dentro, no vínculo do colaborador. Se ele aparece para a sua organização inteira, a leitura é literal — ninguém está informando afastamento a este sistema.
   **Benefício sem regra vigente fica INTEIRAMENTE de fora**, e um total verde é justamente o que esconde isso. O sistema avisa em vez de omitir.
   **Leia os avisos antes dos totais.** A tela mostra, nesta ordem: os avisos, o que ficou de fora, e só então os valores. Isso é de propósito.
4. **"Desconto proporcional sem contagem de dias" é configuração, não defeito.** Você declarou que aquele afastamento reduz o benefício proporcionalmente, e a fonte que respondeu traz o tipo do afastamento mas não as datas — então não há como dividir. O sistema recusa em vez de pagar o vale inteiro a quem esteve afastado, que é o erro que chega ao bolso do colaborador. Registre o afastamento no vínculo, com início e fim, e a apuração passa a calcular a proporção sozinha.
   **Confira quem ficou de fora, e por quê.** Cada exclusão vem com o motivo: nenhuma regra o alcança, suspenso por afastamento, falta o valor de um termo, sem natureza de rubrica vigente, pediu para sair do benefício, ou desconto proporcional sem contagem de dias. É isso que impede "o colaborador não apareceu na folha" de virar investigação.
5. **Confira os lançamentos.** São **dois por concessão** — o custo da empresa e o desconto do colaborador. Nascem juntos e são conferidos juntos; faltar um dos dois é erro, não omissão.
6. **Faça valer.** Só uma apuração do tipo *Definitivo* pode ser efetivada, e o período efetivado **recusa uma segunda**. Simulação pode ser descartada e refeita quantas vezes quiser; apuração definitiva **nunca é apagada**, porque um pagamento passado precisa continuar explicável pela apuração que o produziu.

### Os títulos a pagar, e o rateio

1. **Só o custo da empresa vira título.** O que é descontado do colaborador não é dívida com o fornecedor — é instrução para a folha, e sai pela exportação (S5). Somar os dois aqui cobraria da operadora um dinheiro que o colaborador paga.
   **Ao fazer valer**, o sistema gera **um título a pagar por fornecedor** com o total do período. Você não redigita no financeiro o que o RH acabou de calcular — o título já nasce com a apuração e o período gravados, e é por isso que o financeiro consegue rastreá-lo sem conhecer o módulo de benefícios.
2. **A categoria financeira é um campo novo da configuração do benefício, e não é a mesma coisa que a natureza da despesa.** A natureza responde à contabilidade pública; a categoria é a classificação gerencial que o título a pagar exige. Uma não deriva da outra — as duas convivem, e as duas precisam estar preenchidas.
   Os quatro motivos: **sem configuração financeira vigente** no período, **sem categoria financeira**, **sem empenho vinculado** (quando o ente exige), e **fornecedor não encontrado**.
   **Por que não gerar um título incompleto:** seria transformar um problema do RH num problema do financeiro, para outra pessoa consertar. E por que não pular o fornecedor em silêncio: o dinheiro sumiria da apuração.
   **Leia as pendências antes da lista de títulos.** Quando um título **não** pode ser gerado, o sistema **não** o gera e **não** deixa o valor desaparecer: a linha fica na tela com o valor e o motivo.
3. **Empenho.** Por padrão o sistema **exige** empenho vinculado, porque em órgão público despesa sem empenho prévio é irregular. Ente privado pode operar isento. A mudança para isento é deliberada e deve ser auditada: um ente que exige empenho configurado como isento gera despesa irregular sem nada acusar.
4. **Quem não tinha área na data de referência aparece numa linha própria**, "sem área". Jogar esse valor na maior área faria o relatório fechar estando errado; descartá-lo faria o relatório não fechar.

**Confira o custo por área.** O bloco **Custo por área** distribui o mês por centro de custo, e os totais aparecem ao lado das linhas para você conferir que fecham.

### As naturezas do eSocial

1. **Não há edição nem exclusão.** Natureza que deixou de valer é **encerrada pela data de término**, para um lançamento carimbado no ano passado continuar explicável.
   **Benefício de outro regime precisa da natureza cadastrada aqui.** Sem ela a apuração deixa o benefício **inteiro** de fora e diz isso — não é exclusão de colaborador, é o benefício que não pôde ser apurado. Cadastre o código copiando da tabela do eSocial que a sua contabilidade usa; a tela não inventa códigos.
   **No fim da tela de Benefícios**, o bloco **Naturezas do eSocial** lista os códigos que cada lançamento da apuração carrega. Vêm cadastrados **quatro**: vale-transporte (1810 / 9216) e alimentação do PAT (1806 / 9241).
2. **O regime do benefício é escolha, não default.** Ao cadastrar um benefício você precisa dizer o regime — o sistema não assume "sem regime específico" por omissão. "Sem regime" continua sendo uma resposta legítima; o que deixou de ser é o que se obtém não respondendo.

### Mandar para a folha

1. **Só apuração definitiva e já efetivada.** Simulação é recusada — carregada na folha, seria indistinguível da real. Apuração calculada mas ainda não efetivada também: os valores podem mudar até lá, e a folha não sabe descarregar um arquivo.
   **No bloco "Exportar para a folha"**, com a apuração **efetivada**, clique em Exportar. O arquivo baixa e o sistema registra a exportação com data, autor, contagem de linhas e **checksum**.
2. **Este arquivo não é o de entrada ao contrário.** O layout que o ERP **lê** se chama "Folha → Financeiro" e toda linha dele vira obrigação a pagar. O desconto do colaborador não é obrigação — ele *reduz* o líquido de quem recebe —, e o custo da empresa já virou título na etapa anterior. Mandá-lo de novo criaria pagamento em duplicidade. São dois layouts, um por sentido: docs/ops/benefit-payroll-export-layout.md.
   **O arquivo usa as naturezas de rubrica do eSocial** — 1810/9216 para vale-transporte concedido e descontado, 1806/9241 para alimentação do PAT. São códigos oficiais que qualquer folha do mercado já conhece, e é isso que dispensa um de-para em cada implantação.
3. **Confira o checksum.** Igual ao da exportação anterior significa o mesmo arquivo reenviado. Diferente significa que os valores mudaram entre as duas — e quem vai carregar precisa saber disso **antes** de carregar. O controle final é seu.
   **Reexportar é permitido, e fica registrado.** Arquivo se perde, lote é rejeitado, valor é corrigido — o sistema não impede. O que ele faz é **avisar antes do botão** e guardar o registro anterior.
4. **Leia as linhas que não puderam ser produzidas.** Colaborador sem documento no cadastro não gera linha: a folha externa casa pessoa por CPF, não pelos nossos ids. Benefício cujo regime não tem natureza vigente também não. O sistema **diz quais e por quê** em vez de entregar um arquivo que parece completo enquanto alguém ficou de fora.
5. **Cada lançamento diz se já foi.** Na lista de lançamentos, o que já saiu mostra "enviado à folha em ". Serve para o caso que o histórico não cobre: o lançamento que **ficou de fora** do arquivo.
6. **O caminho de volta não mudou.** O retorno da folha continua entrando pela importação que o ERP já tinha.

### Conciliar com o fornecedor

1. **Nunca de uma simulação.** Comparar a fatura real do fornecedor com números que nunca valeram acharia diferença onde não há. Período sem apuração efetivada é recusado dizendo isso.
   **Abra "Conciliação de benefícios"** (/benefit-reconciliations), escolha o período e o fornecedor. O sistema já sabe quanto foi concedido: ele toma o total da **apuração efetivada** do mês.
2. **A origem fica gravada porque as duas não têm o mesmo valor de prova.** Um total digitado e um lido na fonte ficam idênticos na tela, e é o auditor quem precisa distinguir.
   **Informe quanto o fornecedor cobrou** e diga de onde veio esse número — lido do extrato dele ou digitado da fatura.
3. **Deixe o valor em branco enquanto ele não chegou.** Em branco significa "ainda não chegou" e o período fica como *Não comparado*. Não é zero: tratar como zero criaria uma diferença do tamanho do mês inteiro e a chamaria de divergência.
4. **O primeiro bloco da tela é o que está em aberto em TODOS os períodos**, não só no que você escolheu. Diferença achada em março costuma fechar em maio, e nenhum período isolado responde "o que ainda está comigo".
5. **Leia a contagem de pares comparados antes da lista.** Lista vazia pode significar duas coisas opostas — "não há o que conciliar" e "ninguém conciliou" — e só a contagem distingue.
6. **Diferença dentro da tolerância do fornecedor não vira item.** A defasagem é estrutural, não erro: o estabelecimento tem até 15 dias úteis para receber, então a conta dele e a nossa raramente fecham no mesmo dia. A tolerância é cadastrada por fornecedor e começa em zero.
7. **Dê um responsável e um prazo a cada diferença.** Enquanto não tem dono, ela fica **destacada no topo** — diferença sem dono não é resolvida, fica.
8. **A classificação que o sistema dá é só a que dois totais sustentam:** não cobrou, cobrou a mais, cobrou a menos. **"Devolução de saldo" é uma causa, não uma direção** — quem nomeia é você, ao tratar. O sistema não escreve no registro do auditor um diagnóstico que ninguém fez.
9. **Encerre dizendo como foi tratada.** A observação é obrigatória nas duas saídas: *Resolvida* (foi corrigida) e *Aceitar como está* (foi aceita sem correção). São decisões diferentes, e um mês cheio de aceitações é sinal de que a tolerância ou o fornecedor merecem uma olhada.
10. **Conciliar de novo não apaga o seu trabalho.** Se a fatura vem corrigida, o valor da diferença muda — mas o responsável, o prazo e o andamento continuam. E se a diferença fechou, o item vira *Resolvida* dizendo que fechou na conciliação seguinte, em vez de simplesmente sumir.
11. **A adesão é contagem, nunca pessoa.** O bloco de adesão mostra quantos estão ativos contra quantos têm direito. **O emissor não fornece extrato individual de colaborador à empresa** — invoca a LGPD e o sigilo bancário, e sustenta que nem a autorização do próprio colaborador tornaria isso válido, porque a relação de hierarquia fragiliza esse consentimento. O denominador ("com direito") é nosso, tirado das concessões, então a taxa é calculável mesmo quando o fornecedor só manda contagens.

### A área do colaborador

1. **Você só vê o que é seu.** Nenhuma tela ou endereço desta área aceita o nome de outra pessoa: quem está pedindo é resolvido pela sessão. Tentar abrir o pedido de um colega responde "não encontrado", e não "sem permissão" — dizer "sem permissão" já confirmaria que o pedido existe.
   **Cada colaborador tem "Meus benefícios"** (/my-benefits), e o menu aparece para **todo mundo** — não é preciso permissão nenhuma, porque o assunto é o registro da própria pessoa.
2. **Peça aderir, sair ou mudar o valor**, com o motivo. O pedido entra na **bandeja de aprovação que a organização já usa** — não é um fluxo novo — e some da sua lista de pendências quando alguém decide.
3. **Leia a faixa embaixo de um pedido APROVADO.** Aprovado e "surtiu efeito" são coisas diferentes, e a faixa diz qual dos dois aconteceu:
   - **Aderir** coloca você na lista de adesão do benefício, quando ela existe — e a próxima apuração já te alcança.
   - **Quando o benefício não tem lista de adesão**, a decisão fica registrada e **quem é alcançado não muda**. A tela diz isso na cara, em vez de deixar você esperando uma linha no contracheque que não vinha. Quem cuida das regras precisa agir.
   - **Sair** vale a partir da **próxima** apuração, e aparece nela como exclusão com o motivo — nunca em mês já fechado.
   - **Mudar o valor** é pedido, não mudança: o valor continua vindo da regra. Um número digitado por cima de uma fórmula escaparia da verificação de tratamento igual do PAT, que é justamente o controle que existe para pegar duas pessoas na mesma situação recebendo diferente.
4. **Cancele enquanto ninguém decidiu.** Depois de decidido, não dá — e o sistema diz isso.
5. **O que fica guardado aqui é a sua instrução, não o seu saldo.** O saldo vive no emissor do cartão, que é quem liquida. Espelhar o saldo aqui criaria uma segunda verdade que divergiria da dele no primeiro estorno.

**O teto vem da concessão, não do que você digita.** Passar do disponível é recusado dizendo **os dois números** — quanto você somou e quanto havia. E o desconto do colaborador não entra no que há para distribuir: ele é cobrado de você, não concedido.

**Distribua o saldo entre categorias** no bloco de baixo. Escolha o mês (cada linha traz o benefício, porque quem tem dois benefícios tem dois valores no mesmo mês), e reparta entre refeição, alimentação, cultura, premiação e mobilidade.

### Enquadramento legal

1. **O bloco "Enquadramento legal" na apuração diz primeiro que a checagem rodou.** Zero apontamentos e checagem que não rodou seriam a mesma tela em branco — a linha existe para separar as duas.
2. **O teto é sobre o salário básico, não sobre o bruto.** O Decreto 95.247/1987, art. 9º, exclui expressamente "quaisquer adicionais ou vantagens". Calcular sobre o bruto daria um teto alto demais — e alto demais, aqui, é na direção em que quem paga é o colaborador.
   **Duas regras são conferidas.** A do programa de alimentação: o benefício precisa ter **o mesmo valor para todos os trabalhadores** (Decreto 10.854/2021, art. 172, parágrafo único), e a irregularidade cancela a inscrição — junto com o tratamento fiscal. E a do transporte: o desconto do colaborador é de no máximo **6% do salário básico**, e o que passar disso é a empresa que paga (Lei 7.418/1985, art. 4º, parágrafo único).
3. **O apontamento avisa, nunca bloqueia.** Diferenciação por perfil (54.8) e conformidade (54.34) na mesma seção: bloquear inviabilizaria a primeira, e silenciar criaria passivo. Então quem responde pela conformidade **decide**, registra o porquê e segue.
4. **Justificar não é silenciar para sempre.** A justificativa vale para a **configuração atual**: mude a regra e o apontamento **reabre**, com a justificativa anterior preservada — ela é a prova do que foi decidido, e sobre o quê.
5. **"Não deu para conferir" é um apontamento, não silêncio.** Sem o salário básico do período, o teto do transporte não pode ser verificado — e isso aparece dito, em vez de a lista ficar vazia parecendo que está tudo certo.
6. **Efetivar com apontamento em aberto é permitido, e pede confirmação.** A primeira tentativa volta dizendo quantos estão em aberto; a segunda, com "Li os apontamentos", efetiva — e a apuração passa a registrar que foi selada sobre eles.

### O emissor do cartão

1. **O cartão não é nosso e não vai ser.** Bandeira, rede credenciada e liquidação são de uma empresa autorizada a operar meios de pagamento. E desde o Decreto 12.712/2025 o emissor é peça **substituível por norma**: portabilidade do trabalhador e interoperabilidade entre bandeiras são obrigatórias. Por isso o sistema fala com "um emissor", e cada fornecedor é uma implementação dessa conversa.
   **Abra "Emissor do cartão"** (/benefit-issuer). É por aqui que sai o cadastro, os créditos e os pedidos de cartão — em vez de alguém subir planilha no portal do fornecedor todo mês.
2. **Se a tela disser que nenhum emissor está configurado, isso é passo de configuração — não mês vazio.** As duas coisas produziriam a mesma lista em branco, e só uma delas é tarefa de alguém.
3. **Enquanto não confirma, ninguém nesse estado recebe crédito.** Mandar dinheiro para alguém que o emissor não conhece dá erro lá e valor perdido no meio do caminho. O envio **pula** essa pessoa e **diz quem foi** — a contagem aparece na apuração, não só na resposta da tela.
   **Envie o cadastro.** Cada pessoa vira um vínculo **aguardando o emissor**: o cadastro não é instantâneo, o emissor aceita o pedido e confirma depois.
4. **Cadastro recusado mostra a frase do próprio emissor.** Se o conserto é documento faltando ou cadastro duplicado, está nela. Reenviar o cadastro é a forma normal de tentar de novo: o vínculo é atualizado, nunca duplicado.
5. **Peça o cartão só de quem já foi confirmado.** O sistema recusa antes disso — cartão de plástico impresso e postado para um cadastro que ainda pode ser recusado é prejuízo com endereço.
6. **Acompanhe pela encomenda, não pela remessa.** A remessa é coletiva; quem recebe é a pessoa. "Onde está" mostra o estado da encomenda daquele colaborador — pedido, em preparação, a caminho, entregue, devolvido, problema na entrega.

## Verificação

***

- Cadastrar um benefício com regime de alimentação e consultá-lo mostra o regime registrado
- Associar dois fornecedores diferentes ao mesmo benefício é aceito
- Reusar um código existente é recusado, nomeando o benefício que o ocupa
- Registrar configuração financeira nova encerra a anterior na véspera
- O histórico mostra autor, data e valores antes e depois
- Fórmula com termo desconhecido é recusada nomeando o termo
- A prévia mostra o valor e cada parcela, sem salvar a regra
- Entre duas regras que alcançam a mesma pessoa vale a de maior prioridade, e o sistema diz qual
- Benefício do PAT com valores divergentes avisa, pede justificativa e salva
- Alcance que exige referência sem informá-la é recusado dizendo o que falta
- Simular e efetivar o mesmo período **sem mudar nada** produz valores idênticos, linha por linha
- Cada concessão tem dois lançamentos — ou só o custo, quando a regra não prevê desconto
- Benefício sem regra vigente no período gera aviso visível, não omissão
- Efetivar um período já efetivado é recusado apontando a apuração existente
- A apuração informa quantos ficaram de fora e por quê
- Efetivar com dois fornecedores gera um título por fornecedor, com o total de cada um
- A ligação entre título e apuração é visível nos dois sentidos
- Fornecedor sem configuração financeira não gera título, e a pendência aparece na tela
- O custo por área soma exatamente o total da apuração
- Dias devidos negativo ou zero é recusado, dizendo o valor recebido
- Duas regras ativas empatadas em prioridade e data de início são recusadas
- Benefício cujo regime não tem natureza fica de fora **uma vez**, no nível do benefício
- Registrar a justificativa de isonomia grava na regra e o aviso desaparece
- Editar regra pela URL de outro benefício é recusado
- Exportar apuração efetivada gera uma linha por lançamento, com natureza correta por lado
- Exportar simulação é recusado explicando o motivo
- Reexportar avisa e registra a nova exportação, sem apagar a anterior
- A data de exportação fica visível nos lançamentos
- Alimentação e transporte no mesmo período saem cada um com a sua natureza
- Conciliar com valores iguais marca o período como conciliado e não cria diferença
- Conciliar com valores diferentes cria a diferença com o valor e a classificação
- Diferença sem responsável aparece destacada
- Encerrar sem dizer como foi tratada é recusado
- Conciliar de novo mantém responsável, prazo e andamento
- Período sem apuração efetivada é recusado
- O colaborador vê apenas os próprios pedidos
- Tentar mexer no pedido de outra pessoa responde "não encontrado"
- Pedido aprovado mostra o que mudou de fato
- Sair aparece como exclusão na próxima apuração
- Distribuição acima do disponível é recusada com os dois números
- Valor desigual num benefício de alimentação gera apontamento sem impedir a gravação
- Justificar exige motivo
- Mudar a regra reabre o apontamento justificado
- Desconto de transporte acima de 6% aparece com o valor e o teto
- Sem salário básico, a checagem diz que não pôde rodar
- Efetivar com apontamentos em aberto pede confirmação e fica registrado
- Enviar o cadastro cria o vínculo como "aguardando o emissor"
- Cadastro recusado mostra a frase do emissor
- Crédito não é enviado para quem não foi confirmado, e os pulados são contados
- Pedir cartão antes da confirmação é recusado
- O acompanhamento é por encomenda individual

## Erros comuns

***

- **"Este código já é usado pelo benefício X"** — o código é único no catálogo. A mensagem nomeia o benefício que o ocupa; escolha outro código ou edite aquele.
- **"O benefício X não tem fornecedor ativo"** — o cadastro está incompleto. Associe um fornecedor antes de conceder.
- **"Conta bancária não encontrada"** — a conta informada não existe no cadastro financeiro. Cadastre-a em **Financeiro → Contas bancárias** primeiro.
- **"O termo X não é reconhecido"** — a fórmula usa um nome que não está na lista de termos disponíveis, mostrada ao lado do campo. Confira a grafia e as chaves.
- **"Falta o valor do termo X"** — a fórmula usa um termo que o sistema não deriva sozinho (o salário básico, os dias devidos) e ele não foi informado. **O sistema recusa em vez de tratar como zero**, de propósito: um desconto que vira zero em silêncio não é recusado por ninguém.
- **"Informe o nível"** — a fórmula lê a faixa salarial, e a faixa pertence a um par cargo + nível. Sem o nível a consulta não encontraria faixa nenhuma e a conta sairia contra um intervalo de zero.
- **"O grupo ainda é usado por N regra(s)"** — desative ou reaponte as regras antes de desativar o grupo.
- **"Já existe uma apuração efetivada para este período"** — o período está selado. Para corrigi-lo, simule quantas vezes quiser; a correção do definitivo é assunto da conciliação (S6).
- **"Sem natureza de rubrica vigente"** — a natureza do eSocial daquele lado e regime não cobre o período apurado. É proposital: carimbar um evento com código fora de vigência faz a folha rejeitá-lo depois, longe de quem apurou.
- **"Apenas simulação pode ser descartada"** — apuração definitiva não é apagada.
- **"Esta apuração já gerou os títulos a pagar"** — gerar de novo dobraria a obrigação e o financeiro não teria como saber. Se algum título precisa mudar, trate pelo cancelamento.
- **"Sem categoria financeira"** — preencha a categoria na configuração financeira do benefício. Não é a natureza da despesa: são duas classificações diferentes e as duas são necessárias.
- **"Sem empenho vinculado"** — informe o empenho na apuração, ou confirme com a contabilidade se este ente opera isento.
- **"Dias devidos precisa ser maior que zero"** — valor negativo produziria benefício negativo e zero produziria concessões de R$ 0,00 contadas como concessão.
- **"Já existe regra ativa com prioridade N vigente a partir de D"** — duas regras empatadas em prioridade **e** data deixariam o valor pago por conta da ordem do banco. Use outra prioridade, ou outra data de início.
- **"A regra X não pertence ao benefício Y"** — a regra é editada pela URL do próprio benefício.
- **"Já existe a natureza X vigente para este lado e regime"** — encerre a anterior pela data de término antes de cadastrar a nova.
- **"Só apuração definitiva vai para a folha"** — a apuração é simulação. Rode em definitivo e efetive.
- **"A apuração foi calculada mas ainda não foi efetivada"** — efetive antes de exportar.
- **"Não há apuração definitiva efetivada para este período"** — rode e efetive a apuração antes de conciliar.
- **"Diga como a diferença foi tratada"** — a observação é obrigatória para encerrar, inclusive para aceitar como está.
- **"Você já tem uma solicitação deste tipo aguardando decisão"** — cancele a anterior ou espere a decisão; dois pedidos iguais na bandeja não têm como ser distinguidos por quem decide.
- **"Este login não está vinculado a um colaborador"** — peça ao RH para ligar o seu acesso ao seu cadastro.
- **"O emissor ainda não confirmou este colaborador"** — espere a confirmação, ou reenvie o cadastro se ele foi recusado.
- **"Colaborador sem documento — o emissor identifica pessoa por CPF"** — preencha o CPF no cadastro e reenvie.
- **"Há N apontamento(s) de conformidade em aberto"** — leia o bloco Enquadramento legal; para seguir assim, use "Li os apontamentos".
- **"Diga por que a organização segue assim"** — a justificativa é obrigatória, e vale só para a configuração atual.
- **"A distribuição soma X e o disponível é Y"** — reduza até caber; o teto é o valor concedido no mês.
- **"Colaborador responsável não encontrado"** — o responsável precisa ser um colaborador ativo do cadastro.
- **"colaborador sem documento no cadastro"** — preencha o CPF no cadastro de colaboradores. A folha externa casa pessoa por documento.


[title] Releases
[path] Aplicações/Agility/Produtos e releases/

:::BlockQuote
Crie versões planejadas, associe features e acompanhe resultado, escopo e entrega no detalhe da release.
:::

:::hint{type="info"}
**Pré-requisito:**

Cadastre ao menos um Produto de software. O produto é o primeiro campo obrigatório do formulário e a versão deve ser única dentro dele.
:::

***

Releases são unidades versionadas de entrega do produto. A lista resume situação, versão, data planejada ou realizada e desvio; os indicadores mostram entregas do trimestre, itens em andamento, atrasos e releases sem produto. Uma release sem produto pode existir apenas como legado e fica na fila de backfill até ser classificada.

Ao abrir uma release, o cabeçalho mostra versão, situação, produto/programa, data planejada, entrega realizada, desvio e quantidade de features. As abas Visão geral, Features, Fases e tarefas e DevOps separam o planejamento, o conteúdo da entrega, o escopo operacional e as execuções de pipeline.

***

### Passo a passo

::::WorkflowBlock
:::WorkflowBlockItem
**Abrir a lista de releases**

Na barra lateral do Workspace, clique em Releases. Confira os indicadores e a mensagem de apoio: o desvio compara a data real de entrega com a data planejada, e uma release sem produto não entra nos indicadores por produto. Use a busca por nome, código, versão ou produto e os filtros de situação e produto para encontrar a entrega desejada.
:::

:::WorkflowBlockItem
**Iniciar uma release**

Clique em Nova release. O formulário começa pelo campo Produto de software, que é obrigatório. Se nenhum produto estiver selecionado, o botão Criar release permanece desabilitado. Selecione o produto que receberá a versão; trocar o produto durante uma edição move a release inteira, não apenas suas features.
:::

:::WorkflowBlockItem
**Informar título e versão**

Preencha Título da release com o nome da entrega e informe a Versão, por exemplo 2026.4.1. A versão é única dentro do produto: o Agility verifica o par produto/versão enquanto você digita e novamente na submissão. Se houver conflito, o campo recebe a mensagem com o produto e a versão ocupados e o salvamento fica bloqueado.
:::

:::WorkflowBlockItem
**Planejar a entrega**

Em Data planejada, selecione a data prevista. Em Tipo, escolha Funcionalidade para uma entrega de capacidade ou Correção para uma versão voltada à correção. Na criação, Situação é exibida como Planejada; a data real não é solicitada aqui, pois só existe quando a situação passa para Entregue.
:::

:::WorkflowBlockItem
**Registrar o resultado esperado**

Use Resultado esperado para descrever o efeito que a entrega deve produzir, como o cidadão receber avisos de andamento sem abrir o portal. Esse texto aparece na Visão geral junto do estado esperado. Revise Produto, Título, Versão, data, tipo e resultado e clique em Criar release.
:::

:::WorkflowBlockItem
**Abrir o detalhe**

Após salvar, clique no nome da release na tabela. O cabeçalho oferece Mudar situação e Editar, além dos cartões de data planejada, entrega realizada, desvio e Features na release. As abas são rotas próprias: podem ser compartilhadas e preservam a release que está sendo analisada.
:::

:::WorkflowBlockItem
**Conferir a Visão geral**

Na aba Visão geral, leia o painel Resultado e benefício. O resultado esperado é o texto informado na criação. O resultado realizado e o benefício realizado permanecem pendentes até a transição para Entregue; o selo informa se cada item está informado ou pendente.
:::

:::WorkflowBlockItem
**Vincular uma feature existente**

Abra a aba Features e clique em Vincular feature. O diálogo identifica a release pelo código, título e versão e carrega as features do Workspace que ainda não possuem release. Escolha uma opção no campo Feature; o resumo mostra código, situação, se é habilitador e que ela ainda está sem release. Clique em Vincular feature e aguarde a tabela ser recarregada.
:::

:::WorkflowBlockItem
**Criar feature diretamente na release**

Se nenhuma feature sem release estiver disponível, clique em Nova feature. O formulário de item SAFe abre com a release atual já selecionada; informe os campos da feature, selecione épico quando aplicável e salve. A nova feature passa a aparecer na tabela da aba Features sem precisar de um segundo vínculo.
:::

:::WorkflowBlockItem
**Ler as features vinculadas**

A tabela de Features mostra título e código, situação, épico, WSJF, histórias e o marcador Enabler. O rodapé resume total de features, quantidade de habilitadores e WSJF somado. Uma feature de produto diferente da release é identificada na linha, o que permite revisar o vínculo antes de entregar.
:::

:::WorkflowBlockItem
**Alterar a situação e concluir a entrega**

Clique em Mudar situação no cabeçalho. Escolha a nova situação entre as transições permitidas. Para Entregue, informe Data de entrega, Resultado realizado e Benefício realizado; o diálogo calcula o desvio a partir das datas e registra os valores na Visão geral. A entrega só fica disponível quando existe execução de pipeline com sucesso em Produção.
:::

:::WorkflowBlockItem
**Entender o backfill**

Se o indicador Sem produto vinculado for maior que zero, abra Pendências de vínculo no indicador ou no atalho da lista. A tela existe para classificar releases legadas cujo product\_id era nulo: a sugestão automática aparece quando todas as features apontam para o mesmo produto, enquanto casos com produtos concorrentes exigem Decisão manual. Use Confirmar para uma sugestão, Escolher para selecionar o produto, ou inspecione o detalhe pelo chevron antes de decidir.
:::

:::WorkflowBlockItem
**Aplicar sugestões em lote**

Quando houver sugestões automáticas, o botão Aplicar sugestões abre uma confirmação em lote. Revise a quantidade antes de confirmar; nada é gravado apenas por aparecer como sugestão. A fila registra Resolvidas hoje e, quando pendências chega a zero, informa que todas as releases têm produto e que o vínculo pode se tornar obrigatório no cadastro.
:::
::::

:::hint{type="success"}
:FontAwesome[]{icon="fa-solid fa-check"} **Verificação**

- A release aparece na lista com o produto correto, versão, situação Planejada e data planejada.
- O cabeçalho do detalhe mostra os cartões de planejamento, entrega, desvio e total de features.
- Uma feature vinculada aparece na aba Features com situação, épico, WSJF, histórias e Enabler.
- Após concluir a entrega, resultado e benefício realizados deixam de ser pendentes e a data real alimenta o desvio.
- A fila de backfill mostra a release como resolvida após confirmar uma sugestão ou escolher um produto.
:::

:::hint{type="warning"}
:FontAwesome[]{icon="fa-solid fa-triangle-exclamation"} **Erros comuns**

**Versão já existente no produto**

O campo Versão informa que o par já existe e desabilita o botão principal. Escolha outra versão ou selecione outro produto; a checagem é refeita nas duas mudanças.

**Feature não aparece no diálogo de vínculo**

Vincular feature lista somente features já cadastradas sem release. Se a lista estiver vazia, use Nova feature para criar uma com a release atual ou verifique se a feature já está vinculada a outra entrega.

**Entregue indisponível**

A transição para Entregue é bloqueada quando não há execução de pipeline com sucesso em Produção. Registre ou execute o deploy na aba DevOps, aguarde o sucesso e volte a Mudar situação.

**Release sem produto na fila**

Releases legadas podem aparecer com Sem produto vinculado. Abra o detalhe para revisar features e escopo; depois use Confirmar ou Escolher na fila de backfill. O chevron apenas inspeciona, não grava o vínculo.
:::


[title] Cadastros financeiros
[path] Aplicações/Agility/Financeiro/

:::BlockQuote
Cadastre clientes, contratos, produtos e serviços do catálogo e os custos-hora que alimentam os projetos e a rentabilidade.
:::

:::hint{type="info"}
**Pré-requisito:&#x20;**

Tenha acesso a um Workspace. O cadastro é do Workspace e pode ser reutilizado por todos os seus projetos.
:::

***

A aba \*\*Financeiro → Cadastros\*\* reúne os registros que dão contexto ao financeiro operacional: clientes, contratos, produtos e serviços do catálogo e custos-hora por pessoa ou papel. A ordem dos segmentos acompanha a dependência dos dados: primeiro o cliente, depois o contrato; catálogo e custos-hora são independentes.

Esses cadastros são compartilhados pelos projetos do Workspace. Um contrato pertence a um cliente; o projeto pode associar cliente e contrato na sua configuração financeira, vincular itens do catálogo pelo preço acordado e apropriar horas usando a taxa vigente. O Agility não possui cadastro de banco nem plano de contas contábil: essas entidades não aparecem na rota nem nos componentes de Financeiro. Contas bancárias, conciliação e classificação contábil devem ser tratadas no ERP integrado, quando houver.

***

### Passo a passo

::::WorkflowBlock
:::WorkflowBlockItem
**Abrir os cadastros**

Entre no Workspace e abra \*\*Financeiro\*\*. Se a página abrir em outra aba, selecione \*\*Cadastros\*\*; a aba é endereçável por \`?section=cadastros\`. Os quatro segmentos aparecem como abas: \*\*Clientes\*\*, \*\*Contratos\*\*, \*\*Catálogo\*\* e \*\*Custos-hora\*\*, cada um com a quantidade de registros carregados.
:::

:::WorkflowBlockItem
**Abrir a aba Operacional do Workspace**

Além de \*\*Cadastros\*\*, o Financeiro do Workspace tem a aba \*\*Operacional\*\* (\`?section=operacional\`). Ela reúne as visões que atravessam projetos: \*\*Ordens de serviço\*\*, \*\*SLA\*\*, \*\*Tesouraria / aging\*\* e \*\*Documentos financeiros do ERP\*\*. Use as ordens e o SLA para acompanhar a execução comercial dos contratos; os dois cartões de ERP são leituras de consulta e só aparecem preenchidos quando a integração fornece esses dados. Não confunda essa visão consolidada com o Financeiro de um projeto, que contém os lançamentos e a margem daquele contexto.
:::

:::WorkflowBlockItem
**Ler Ordens de serviço e SLA**

No bloco \*\*Ordens de serviço\*\*, filtre e abra uma OS para conferir contrato, cliente, projeto, datas, situação e valores. O bloco \*\*SLA\*\* mostra meta, resultado e eventual alerta de prazo descumprido; uma OS só pode ser criada para contrato ativo. Quando o ERP estiver sem resposta, a tela mantém o estado de integração e explica que a origem externa não está disponível, em vez de apresentar valores locais como se fossem oficiais.
:::

:::WorkflowBlockItem
**Consultar tesouraria e documentos do ERP**

Use \*\*Tesouraria / aging\*\* para consultar títulos e vencimentos retornados pelo ERP e \*\*Documentos financeiros do ERP\*\* para consultar os documentos financeiros associados. Esses cartões não são um cadastro ou uma tela de edição do Agility: seus estados, totais e mensagens refletem a proveniência e o resultado da última leitura da integração. Para corrigir um título ou documento, siga o processo no ERP de origem e atualize a leitura no Agility.
:::

:::WorkflowBlockItem
**Cadastrar um cliente pessoa jurídica**

Na aba \*\*Clientes\*\*, clique em \*\*Novo cliente\*\*. O diálogo começa na opção \*\*Pessoa jurídica\*\*. Se o ERP disponibilizar parceiros ativos com o papel de cliente, o campo \*\*Parceiro no ERP\*\* permite selecionar um deles ou deixar \*\*Sem vínculo ERP\*\*. Ao vincular, nome e CNPJ vêm do ERP e deixam de ser editáveis no cadastro do Agility; isso mantém a mesma entidade nas duas bases e permite comparar a margem por cliente.
:::

:::WorkflowBlockItem
Sem vínculo ERP, preencha \*\*Nome\*\* e, se desejar, \*\*CNPJ\*\*. O documento é digitado com máscara, mas o servidor armazena apenas os dígitos. Pessoa jurídica exige CNPJ com 14 dígitos; para um cadastro pessoa física, troque para a aba \*\*Pessoa física\*\*, informe o nome e um CPF com 11 dígitos. Trocar a aba limpa o documento digitado, pois CPF e CNPJ têm formatos diferentes.
:::

:::WorkflowBlockItem
Complete os dados de endereço que serão úteis para identificação: \*\*Endereço\*\*, \*\*País\*\*, \*\*Cidade\*\* e \*\*Estado\*\*. Os campos são opcionais, mas preencher ao menos a cidade e o estado ajuda a reconhecer o cliente na operação. Clique em \*\*Salvar\*\*; o cliente passa a aparecer na tabela, com documento, tipo (PJ ou PF), eventual parceiro ERP e quantidade de contratos.
:::

:::WorkflowBlockItem
**Localizar e editar um cliente**

Use \*\*Buscar por nome, CNPJ ou parceiro\*\*. A busca aceita o documento pontuado como aparece na tela ou somente os dígitos. Na coluna de ações, escolha \*\*Editar cliente\*\*. Em um cliente vinculado ao ERP, o nome e o documento ficam bloqueados e a tela informa que a edição deve ser feita no ERP; endereço, país, cidade e estado continuam editáveis.
:::

:::WorkflowBlockItem
**Cadastrar o contrato do cliente**

Abra a aba \*\*Contratos\*\* e clique em \*\*Novo contrato\*\*. Selecione o \*\*Cliente\*\* no campo obrigatório; por isso um cliente precisa existir antes do contrato. Informe o \*\*Código\*\* (a aplicação o transforma em maiúsculas), o \*\*Título\*\* e o \*\*Tipo\*\*. Os tipos disponíveis são \*\*Recorrente\*\*, \*\*Preço fixo\*\*, \*\*Hora faturável\*\* e \*\*Marcos\*\*.
:::

:::WorkflowBlockItem
Informe o valor de referência em reais. O rótulo muda conforme o tipo: mensalidade para contrato recorrente, valor da hora para hora faturável e valor do contrato para preço fixo ou marcos; o valor é opcional e pode ser zero. Salve para ver a linha com código, título, cliente, tipo, valor e quantidade de ordens de serviço. Na edição, o cliente aparece bloqueado: repontá-lo reatribuiria a margem histórica.
:::

:::WorkflowBlockItem
Use \*\*Buscar por código, título ou cliente\*\* para filtrar contratos. Contratos cadastrados aqui podem ser selecionados na configuração financeira de um projeto, em uma solicitação de faturamento e na criação de uma ordem de serviço. Um contrato inativo não pode receber uma nova OS; reative ou escolha outro contrato antes de continuar.
:::

:::WorkflowBlockItem
**Criar item no catálogo**

Na aba \*\*Catálogo\*\*, clique em \*\*Novo item\*\*. Escolha a espécie \*\*Produto\*\* ou \*\*Serviço\*\*, preencha o \*\*Código\*\*, a \*\*Unidade\*\* (por exemplo, hora, mês ou licença), o \*\*Nome\*\*, o \*\*Preço de referência (R$)\*\* e, opcionalmente, uma \*\*Observação\*\* sobre o que está incluído. O preço é apenas uma referência do Workspace; o preço efetivamente contratado é gravado depois no vínculo com cada projeto.
:::

:::WorkflowBlockItem
Salve e confirme a linha com código, nome, espécie, unidade, preço e situação \*\*Ativo\*\*. O botão \*\*Editar item\*\* permite alterar código, nome, unidade, preço e observação, mas a espécie fica fixa. Use \*\*Desativar\*\* para retirar o item dos seletores de projetos sem apagar seu histórico; itens desativados continuam listados e podem ser \*\*Reativados\*\*.
:::

:::WorkflowBlockItem
**Definir custo-hora**

Na aba \*\*Custos-hora\*\*, clique em \*\*Novo custo-hora\*\*. Em \*\*Dimensão\*\*, selecione \*\*Pessoa\*\* ou \*\*Papel\*\*. Informe o identificador no campo correspondente (por exemplo, \`ana.souza\` para pessoa ou \`Desenvolvedor\` para papel), o \*\*Custo-hora (R$)\*\* e a data \*\*Vigente desde\*\*. A taxa passa a ser uma referência histórica; uma nova taxa do mesmo sujeito encerra a anterior.
:::

:::WorkflowBlockItem
Após salvar, a tabela mostra dimensão, sujeito, custo-hora e a data de vigência. A busca aceita o nome da pessoa ou do papel. Taxas encerradas ficam esmaecidas, recebem a marca \*\*encerrada\*\* e não oferecem edição: alterar o sujeito reescreveria custos já apropriados. Cadastre uma taxa vigente antes de apontar horas em um projeto.
:::

:::WorkflowBlockItem
**Sobre bancos e plano de contas**

Não procure as opções \*\*Bancos\*\* ou \*\*Plano de contas\*\* dentro desta página: elas não fazem parte do Financeiro do Agility. Os lançamentos do Agility trabalham com tipo (receita, despesa, compra ou faturamento), direção, valor, competência, fornecedor opcional e, quando disponível, centro de custo do ERP. A escrituração bancária e a conta contábil são responsabilidade do ERP integrado e não devem ser inventadas como cadastro no Agility.
:::
::::

:::hint{type="success"}
:FontAwesome[]{icon="fa-solid fa-check"} **Verificação**

- A aba Clientes mostra pelo menos um cliente com tipo PF/PJ e, quando aplicável, documento e parceiro ERP.
- A aba Contratos apresenta o cliente relacionado, o tipo comercial e o valor de referência; o cliente do contrato não pode ser trocado na edição.
- Um produto ou serviço ativo aparece no catálogo e pode ser escolhido para vínculo dentro do financeiro de um projeto.
- A aba Custos-hora mostra uma taxa vigente por pessoa ou papel, com custo e data a partir da qual ela vale.
- Ao criar outra taxa para o mesmo sujeito, a anterior deixa de ser editável e fica marcada como encerrada.
- A aba Operacional permite consultar Ordens de serviço, SLA, aging/tesouraria e documentos financeiros do ERP; cartões externos indicam a origem e não oferecem edição local.
:::

:::hint{type="warning"}
****:FontAwesome[****]{icon="fa-solid fa-triangle-exclamation"}**&#x20;Erros comuns**

**Nome de cliente duplicado**

O servidor recusa nomes repetidos e exibe que já existe um cliente com este nome. Pesquise a tabela e edite o cadastro existente ou escolha um nome que diferencie a entidade.

**CPF ou CNPJ inválido**

A mensagem de documento inválido indica que o CPF precisa ter 11 dígitos e o CNPJ, 14. Remova caracteres extras, confira o documento e salve novamente; a pontuação mostrada na tela é apenas formatação de leitura.

**Contrato sem cliente ou código repetido**

Contrato exige cliente e código único. Volte à aba Clientes para cadastrar o cliente, selecione-o no diálogo e altere o código se ele já estiver em uso.

**Código de catálogo já utilizado**

Cada produto ou serviço do Workspace deve ter código único. Pesquise o código, edite o item existente ou escolha outro; desativar um item não libera automaticamente seu código para uma nova linha.

**Vigência de custo-hora sobreposta**

Uma taxa nova não pode se sobrepor à vigência de outra taxa do mesmo sujeito. Escolha uma data posterior ao fim da vigência anterior ou use a taxa vigente existente; uma taxa encerrada também não pode ser editada.
:::


[title] 4. Alvos e escopo
[path] Aplicações/GRCS/

*O que pode ser auditado e como o score consolida por nível.*

Toda auditoria incide sobre um alvo. Não existe auditoria sem escopo.

Cadastre os alvos **depois** das áreas e grupos (*Áreas, grupos, usuários e perfis*): o campo **Representa o cadastro de** aponta para eles, e é ele que faz a pergunta despachada chegar a alguém. E cadastre-os **antes** do catálogo e da auditoria: o tipo do alvo é o eixo pelo qual o resultado se lê depois (*Dimensões*), e os drivers decidem que perguntas se aplicam a cada um.

***

### <font color="#15803D">Alvos e dimensões, passo a passo</font>

A tela (menu Configuração) tem duas abas: **Tipos e dimensões** e **Alvos cadastrados**. Criar, editar e apagar exige escopo\:escrever; sem ela, a tela é consulta.

1.     **Cadastrar um alvo**: aba **Alvos cadastrados** → **Novo alvo** → **Código**, **Nome** e **Tipo** (obrigatórios), **Dentro de** (o pai na hierarquia; *Nenhum* deixa na raiz), **Representa o cadastro de** (a área ou o grupo que responde por ele) e **Descrição** → **Salvar**.

2.     **Quem responde**: abra o alvo pelo lápis. Com grupo vinculado, aparece **Quem responde por …**: clicar no nome liga ou desliga a pessoa, e cada clique já grava. Sem equipe correspondente, escolha a área em *dentro da área* → **Criar equipe e vincular a este alvo**.

3.     **Achar**: **Filtrar alvo…** e as fichas por tipo (**Todos**, e uma por tipo, com a contagem).

4.     **Documentos do alvo**: o ícone de documento abre os documentos ligados a ele — para quem tem documento\:ler.

5.     **Desativar / Reativar** (olho) tira das listas sem apagar; **Mostrar N desativados** os põe à vista de novo e **Ocultar desativados** os tira.

6.     **Apagar** (lixeira): só alvo **sem história** se apaga — a caixa diz *Nada depende dele* e oferece **Apagar**, **Desativar em vez disso** e **Cancelar**. Alvo com auditoria, não conformidade, risco ou alvo dentro dele **não se apaga**: a caixa diz *Não dá para apagar*, conta o que ele tem e oferece só **Desativar** (ele sai das listas e das auditorias novas, e o que já aconteceu nele continua consultável) e **Fechar**. Se ele já está desativado, não há mais nada a fazer — é o máximo para alvo com história.

7.     **Perfil do alvo (drivers)**: abra o alvo pelo lápis. Em **Perfil do alvo (drivers)**, cada driver tem **Sim**, **Não** e **não respondido** — cada clique já grava, sem precisar salvar o alvo. Quem só lê os alvos vê o mesmo perfil, sem poder mudar, pelo ícone **Perfil do alvo (drivers)** na linha do alvo. Ver Drivers.

8.     **Criar um tipo**: aba **Tipos e dimensões** → **Novo tipo** → **Código**, **Nome** e **Descrição** → **Salvar**. Os doze de fábrica não se editam; os seus se editam pelo lápis e se desativam pelo olho. **Mostrar desativados** põe os tipos desativados na lista, e **Ocultar desativados** os tira de novo.

9.     **Registro ROPA (CSV)**, no alto da tela, baixa o registro das atividades de tratamento — ver Exportação. Aparece para quem tem auditoria\:ler.

***

### <font color="#15803D">O que pode ser um alvo</font>

Organização · Unidade de negócio · Área · Equipe · Contrato · Serviço · Cliente · Fornecedor · Ativo de TI · Processo · Sistema · Planta industrial

Esses doze vêm de fábrica e são somente leitura. Em **Alvos e dimensões** você cadastra os seus quando auditar algo que não está na lista.

O tipo do alvo é também a **dimensão** pela qual as respostas são agrupadas depois — ver Dimensões. E o alvo é compartilhado: auditoria, não conformidade e risco apontam todos para o mesmo cadastro, e é por isso que dá para perguntar "quantos riscos abertos neste contrato?" sem cruzar planilha nenhuma.

Área e equipe são especiais: elas já existem no cadastro como **quem responde**, e podem ser também **o que é auditado**. O escopo aponta para o cadastro existente em vez de recriá-lo — senão a mesma equipe existiria duas vezes e o score de uma não encontraria a outra.

***

### <font color="#15803D">Hierarquia e consolidação</font>

Os alvos formam uma árvore. O score de um nível é a média ponderada dos filhos.

O peso pode vir de duas fontes. Sem declaração, cada filho pesa pelo volume de perguntas avaliadas — quem tem mais substância avaliada pesa mais. Com peso declarado, o gestor afirma que uma unidade importa mais que outra independentemente do volume.

***

### <font color="#15803D">Drivers</font>

Antes do questionário, o alvo responde alguns **drivers**: trata dados pessoais? tem ambiente industrial? é fornecedor crítico? As respostas filtram o que se aplica, para o respondente não percorrer perguntas irrelevantes, e alimentam as regras compostas — são o PERF('CÓDIGO') das condições de aplicabilidade e das regras.

Eles se respondem em *Alvos e dimensões*, no próprio alvo (lápis → **Perfil do alvo (drivers)**), e ao lado do título aparece quantos já foram respondidos. Três estados, e não dois:

| **Na tela**        | **Gravado** | **O que a regra lê**                   |
| ------------------ | ----------- | -------------------------------------- |
| **Sim**            | Sim         | PERF('CLOUD') = 'Sim' é verdadeiro     |
| **Não**            | Nao         | PERF('CLOUD') = 'Nao' é verdadeiro     |
| **não respondido** | nada        | nenhuma das duas — o driver está vazio |



*Não respondido* não é *Não*: a regra que olha o "Nao" não deve disparar para quem nunca respondeu. O driver de sim ou não só aceita essas duas respostas, sempre gravadas nessa grafia — é a que as regras comparam, sem diferença de maiúscula. Driver de outro tipo recebe texto livre e **gravar**.

Responder exige escopo\:escrever, a mesma permissão de editar o alvo.

***

### <font color="#15803D">O alvo é uma dimensão</font>

Porque é hierárquico e porque o resultado sobe por ele, o alvo é também um eixo de análise. A tela *Resultado por hierarquia* mostra a árvore inteira com o score próprio e o acumulado de cada nó, e abre o resumo de qualquer um deles — achados, riscos e auditorias, sem sair da árvore.

Um alvo com história não se apaga: a plataforma recusa e diz o que ele tem — auditorias, achados, riscos ou filhos. Desativar tira das listas sem perder o rastro, e é quase sempre o que se quer.

***

### <font color="#15803D">Quem responde por este alvo</font>

A plataforma tem dois cadastros para a mesma coisa, e o campo **Representa o cadastro de** é o que os liga. A equipe **auditada** vive aqui, no escopo; a equipe que **responde** vive em Áreas e grupos. Sem o vínculo, a mesma equipe existe duas vezes e a pergunta despachada não encontra a fila da área certa.

No editor do alvo, abaixo desse campo, aparece **quem responde por ele**, com busca. Marcar e desmarcar grava na hora. E quando o alvo ainda não tem equipe correspondente — o caso comum de um alvo criado pelo escopo antes de a estrutura existir — um botão cria a equipe com o nome do alvo, dentro da área escolhida, e já liga os dois. Procurar em silêncio numa lista onde o nome não está é indistinguível de não saber usar a tela.

Área é exceção e de propósito: ela não recebe pessoas direto, alcança-as pelos grupos dentro dela. A tela mostra quem a área alcança, como leitura. Deixar marcar ali inventaria um vínculo que o modelo não tem, e alguém ligado à área sem estar em grupo nenhum não receberia onda alguma.

[title] 2. Como usar (de ponta a ponta)
[path] Aplicações/GRCS/

*O caminho inteiro, na ordem em que se faz — preparar, auditar, tratar e, depois, os módulos —, cada passo com a tela e o capítulo.*

A plataforma se usa em quatro tempos, e a ordem não é estética: cada tempo usa o que o anterior deixou pronto.

1.     **Preparar** — quem responde, o que é auditado e o que se pergunta. Feito uma vez, vale para todas as auditorias.

2.     **Auditar** — abrir o ciclo, despachar, responder, revisar e apurar.

3.     **Tratar** — dar saída a cada achado e acompanhar o risco, e só então fechar o ciclo.

4.     **Os módulos** — acervo, painéis, IMR, automação, atendimento e IA, que vivem do que a auditoria produziu.

Os passos abaixo são os mesmos do **Como funciona, de ponta a ponta**, nas Preferências, com os mesmos títulos — lá, cada um mostra se a sua organização já o fez, e o **passo a passo** abre a tela de cada um. Lá, o passo que o seu perfil não alcança — e o do IMR, onde o módulo não está ligado — não aparece, e a numeração se ajusta. Cada passo diz **onde** se faz (grupo do menu ▸ tela) e qual **capítulo** tem o detalhe. O índice do manual segue a mesma ordem.

***

### <font color="#15803D">Antes de começar: onde pedir ajuda</font>

•     **A faísca**, no alto de toda tela, abre o **assistente**. Em *Como fazer*, pergunte em palavras suas — "como registro uma não conformidade?", "onde aprovo um documento?" — e ele explica o passo a passo pelo manual e oferece o botão que leva à tela (*O assistente*).

•     **O ?** abre este manual já na parte que fala da tela em que você está.

•     **Como funciona, de ponta a ponta**, nas Preferências, mostra estes passos e marca o que já foi feito na sua organização.

•     **As Preferências** (a engrenagem no layout de portal; o seu nome no menu lateral) trocam idioma, tamanho do texto, tema e layout (*Layout e aparência*).

O menu só mostra o que o seu perfil abre. Passo que leva a uma tela que você não vê é de outra pessoa — normalmente do administrador.

***

### <font color="#15803D">Antes de tudo: o tenant existe</font>

Quem instala a plataforma cria o tenant no **console da instalação** (/console). Ele nasce com o administrador, três áreas iniciais, o alvo raiz com o nome do tenant, o catálogo de normas de fábrica, o catálogo de serviços de GRC e a configuração padrão da IA. O passo 1 começa daí, entrando com o administrador. Detalhe em *Console da instalação*.

***

## <font color="#15803D">Preparar</font>

### <font color="#15803D">1. Monte a estrutura: áreas e grupos</font>

**Onde:** Administração ▸ Áreas e grupos · **Capítulo:***Áreas, grupos, usuários e perfis*

Tudo o que vem depois procura alguém aqui. A pergunta despachada cai num **grupo** — nunca numa área sem grupo, nunca numa pessoa solta —, e a aprovação procura quem aprova.

1.     Em **Áreas**, **Nova** → **CÓDIGO** e **Nome da área** → **Criar**.

2.     Com a área selecionada, **Novo grupo** → **CÓDIGO** e **Nome do grupo** → **Criar**.

3.     No grupo, **Pessoas**: clique nos nomes para pôr ou tirar. Para quem ainda não tem conta, **convidar** manda o convite por e-mail, já com o perfil e o grupo.

***

### <font color="#15803D">2. Cadastre as pessoas, cada uma com um perfil</font>

**Onde:** Administração ▸ Usuários e Perfis de acesso · **Capítulo:***Áreas, grupos, usuários e perfis*

Cada pessoa tem **exatamente um perfil**, e o perfil é um conjunto de permissões, não um cargo. Os de fábrica — Administrador, Gestor, Analista, Monitoramento, Solicitante e os demais — cobrem o caso comum.

1.     Em **Usuários**, **Novo usuário** → **Login**, **Nome**, **E-mail** (sem ele, o aviso nunca vira e-mail), **Senha**, **Tipo**, o **Perfil** e os **grupos** → **Criar**.

2.     Se nenhum perfil de fábrica servir, monte o seu em **Perfis de acesso** → **Novo perfil**, marcando por ação ou clicando na tela do menu que a pessoa precisa ver.

O **login é único dentro do tenant**, não na instalação: outro cliente pode ter um admin ou um maria.silva sem conflito com o seu. A pessoa entra pelo **endereço da organização** (a URL do tenant, ou empresa.localhost\:porta no ambiente local) — é o endereço que diz em qual tenant o login é procurado, e a tela de entrada não pede organização.

Quem entra pelo login da empresa (OpenID Connect ou LDAP) é configurado em **Administração ▸ Diretório e identidade** — ver *Integração com o diretório*.

***

### <font color="#15803D">3. Declare o que vai ser auditado</font>

**Onde:** Configuração ▸ Alvos e dimensões · **Capítulo:***Alvos e escopo*

Não existe auditoria sem alvo. Pode ser um contrato, um serviço, uma área, uma equipe, um fornecedor, um cliente ou a própria empresa — e o **tipo** do alvo é a dimensão pela qual o resultado se lê depois (*Dimensões*).

1.     Aba **Alvos cadastrados** → **Novo alvo** → **Código**, **Nome** e **Tipo**.

2.     **Dentro de** pendura o alvo noutro: o score do pai passa a ser a média dos filhos, e o resultado sobe pela hierarquia (*Resultado por hierarquia*).

3.     **Representa o cadastro de** aponta o grupo ou a área que responde por ele — é o que faz a pergunta chegar a alguém.

4.     Se for o caso, responda o **Perfil do alvo (drivers)**: eles decidem que perguntas se aplicam.

Tipo que não está entre os doze de fábrica se cria na aba **Tipos e dimensões**.

***

### <font color="#15803D">4. Escolha o framework, ou monte o seu com perguntas e pesos</font>

**Onde:** Catálogo ▸ Frameworks, Framework próprio, Perguntas, Peso das perguntas · **Capítulo:** *Catálogo e frameworks*

O catálogo já nasce cheio, e o de fábrica é só leitura.

1.     **Administração ▸ Normas disponíveis**: marque as normas que esta instalação enxerga e, no primeiro bloco, como ela chama quem é auditado — empresa ou órgão (*Como a instalação chama quem é auditado*).

2.     **Frameworks**: clique no cartão para ver as perguntas de uma norma. Para aplicar uma inteira, não há mais nada a fazer aqui.

3.     **Framework próprio**: **Novo** → **Do catálogo** (perguntas de qualquer framework, que entram por referência) e **Pergunta nova** (as suas) → **Publicar**. Editar uma pergunta de fábrica cria uma cópia sua; a original não muda.

4.     **Peso das perguntas**: quanto cada pergunta vale na nota, e quão grave é o achado quando ela falha. O peso novo vale do próximo ciclo em diante.

Apoio, quando precisar: **Perguntas** reúne o acervo inteiro e cria pergunta sem questionário; **Temas** recorta por assunto; **Listas de valores** dá as mesmas opções a várias perguntas; **Cobertura UCF** mostra quanto de cada norma um conjunto de perguntas cobre.

***

### <font color="#15803D">5. Recorte as perguntas em agrupamentos — se quiser</font>

**Onde:** Catálogo ▸ Agrupamentos · **Capítulo:** *Agrupamentos*

O agrupamento serve a uma coisa só: **disparar por partes** em vez de tudo de uma vez. É opcional; sem ele, o questionário inteiro vai para uma área só, que é o caso comum de uma auditoria interna.

1.     Escolha o **Framework** no alto — cada agrupamento pertence a um framework e não atravessa para outro.

2.     **Novo agrupamento** → **Código** e **Nome** → **Criar**; ou, num recorte de fábrica, **Adotar para editar**, que cria a sua cópia.

3.     Abra o cartão, marque as perguntas → **Trazer N perguntas**.

É o último passo do catálogo, e por isso vem antes da auditoria: o agrupamento **não se dispara** da tela dele. O recorte se escolhe ao abrir a auditoria (**O que vai a campo**) e ao montar cada onda.

***

## <font color="#15803D">Auditar</font>

### <font color="#15803D">6. Abra a auditoria e lance o ciclo</font>

**Onde:** Auditoria ▸ Auditorias · **Capítulo:** *Auditoria, ondas e respostas*

1.     **Abrir auditoria** → **Natureza do ciclo** (**Auditoria** ou **Pré-auditoria** — ver *Pré-auditoria*), **Alvo avaliado** e, em **Avaliar contra**, as normas, temas e frameworks próprios → **Confirmar**.

2.     Em **O que vai a campo**, **Todas as perguntas** ou um ou mais agrupamentos.

3.     **Código** e **Nome**; se quiser, **Prazo** e **Dimensões que este ciclo vai reportar** → **Abrir auditoria**.

4.     O ciclo nasce **rascunho**. Confira quantas pessoas ele alcança, acrescente outros alvos em **+ alvo** e clique **Lançar**.

Lançar **congela a versão de cada pergunta** — editar o enunciado no ano que vem não muda o que foi perguntado agora — e dá a cada uma um número de registro próprio, que nunca se repete. Depois de lançado, o ciclo não se apaga: cancela-se, com motivo.

***

### <font color="#15803D">7. Dispare a onda, para um alvo ou para mil</font>

**Onde:** Auditorias ▸ Ondas de disparo, ou Auditoria ▸ Painel do framework ▸ Montar onda · **Capítulos:** *Auditoria, ondas e respostas* e *Disparo em escala e painel do framework*

Cento e vinte perguntas de uma vez produzem resposta rápida e ruim. Pergunta fora de onda disparada **não é respondível** — é o que impede o faseamento de virar decoração.

•     **Um alvo só:** no ciclo lançado, **Ondas de disparo** → **Nova onda** → o código e *O que esta onda cobre* → **Criar**; marque o que a equipe consegue responder agora → **Incluir na onda** → **Equipe que responde…** → **Disparar**.

•     **Muitos alvos:** **Painel do framework ▸ Montar onda** → os **agrupamentos** desta rodada, os **alvos** por atributo (todos, por tipo, por situação, sem área responsável), o que fazer com as já respondidas, **Equipe** e **Prazo** → **Montar e disparar para N alvo(s)**.

Cada alvo é despachado para a própria área responsável e responde o seu sem enxergar o dos outros; a equipe escolhida é o destino padrão de quem ainda não tem responsável.

***

### <font color="#15803D">8. A área responde na fila dela</font>

**Onde:** Auditoria ▸ Responder auditoria (o site /responder) · **Capítulo:** *Responder uma auditoria*

Quem recebe a onda não abre a tela de Auditorias: abre **Responder auditoria**, que reúne o que foi despachado ao grupo dela, o que lhe foi delegado e o que já é da área pelo alvo avaliado.

1.     Clique na pergunta, escolha a **Situação declarada** e escreva a **Descrição — o que sustenta essa situação**.

2.     Em **Evidências**, suba o arquivo ou aponte um documento da base.

3.     **Responder**. Recebeu no lugar errado? **Encaminhar para outra equipe**.

Fila vazia quase sempre quer dizer uma de três coisas: nada foi disparado, o alvo do ciclo não aponta para uma área (passo 3), ou a pessoa não está em grupo nenhum (passos 1 e 2).

***

### <font color="#15803D">9. Outra pessoa revisa; depois, apure</font>

**Onde:** Responder auditoria ▸ Para revisar, ou o ciclo em Auditoria ▸ Auditorias · **Capítulo:** *Auditoria, ondas e respostas*

Quem responde não revisa — a segregação está no banco, não só na tela.

1.     Leia o valor e as evidências e clique **Aprovar** ou **Devolver**, com o motivo. Devolver é o caminho normal: a pergunta volta para a fila de quem respondeu.

2.     No ciclo, **Apurar** roda as regras sobre as respostas aprovadas, calcula o score e levanta os achados. Refaça quantas vezes for preciso enquanto o ciclo está aberto.

Só resposta aprovada entra no score: um ciclo todo respondido e nada revisado tem score zero, e está certo.

***

### <font color="#15803D">10. Veja como está o conjunto, e depois cada um</font>

**Onde:** Auditoria ▸ Painel do framework; Análise ▸ Auditoria em foco · **Capítulos:** *Disparo em escala e painel do framework* e *Auditoria, ondas e respostas*

O **Painel do framework** responde na ordem em que a pergunta se faz: **quantos responderam** — antes da nota —, como está cada agrupamento, a distribuição por faixa e, só então, o alvo individual, com quem não respondeu à frente. É dali que se monta a onda seguinte.

**Auditoria em foco** mostra uma auditoria de cada vez, inteira: score, cobertura, respostas e achados. Abaixo de 70% de cobertura, a nota é uma amostra pequena.

***

## <font color="#15803D">Tratar</font>

### <font color="#15803D">11. Trate os achados</font>

**Onde:** Tratamento ▸ Não conformidades · **Capítulo:***Não conformidade e risco*

A apuração levanta as não conformidades; o que alguém encontra fora de auditoria entra por **Novo achado**. Cada achado sai por um de dois caminhos:

•     **Plano de ação:** **Novo plano** → objetivo, link, anexo ou detalhamento → ações → **Aprovar plano** → **concluir** cada ação, com a evidência.

•     **Aceite de risco:** **Registrar aceite de risco** → justificativa e **Válido até**. Só quem tem a autoridade de aceitar vê o botão, e o aceite vencido devolve o achado à triagem.

***

### <font color="#15803D">12. Acompanhe o risco residual</font>

**Onde:** Tratamento ▸ Riscos e Continuidade; Configuração ▸ Categorias de risco · **Capítulos:** *Não conformidade e risco* e *Continuidade e monitoramento*

O inerente você informa; o **residual é sempre calculado**. Achado aberto sobre um controle anula a eficácia dele, e o risco sobe sozinho; achado tratado o devolve à conta.

1.     **Novo risco** → título, categoria, probabilidade e impacto. Registre a **Decisão de tratamento** — aceitar, mitigar, transferir ou evitar —, sem a qual o risco não se encerra.

2.     Em **Continuidade** ficam o que não pode parar (**Análise de impacto**), o que avisa antes (**Indicadores (KRI)**) e o que já aconteceu (**Eventos de perda**).

***

### <font color="#15803D">13. Registre a melhoria onde ela foi percebida</font>

**Onde:** Tratamento ▸ Oportunidades · **Capítulo:** *Não conformidade e risco*

A oportunidade é o mesmo evento incerto visto do outro lado, com a mesma escala do risco. Ela nasce na linha da resposta — quem respondeu acabou de olhar o controle — ou em **Registrar**, e anda por avaliação, tratamento e aprovação até o valor realizado.

***

### <font color="#15803D">14. Feche o ciclo e entregue o resultado</font>

**Onde:** Auditoria ▸ Auditorias · **Capítulos:** *Auditoria, ondas e respostas* e *Exportação*

1.     **Fechar ciclo** só passa com toda resposta aprovada e todo achado com plano de ação ou aceite.

2.     Em **Versões publicadas**, **Elaborar versão**; outra pessoa clica **Aprovar**.

3.     **Relatório do ciclo (PDF)** traz sempre as mesmas seções, com quem emitiu, quando e o resumo criptográfico do arquivo. **Respostas (CSV)**, e as exportações de achados e de riscos, servem a quem vai cruzar em planilha.

***

## <font color="#15803D">Depois de auditar: os módulos</font>

Os módulos não dependem uns dos outros, e cada organização liga os que usa. A ordem abaixo é a do manual.

***

### <font color="#15803D">15. Guarde os documentos no acervo, com aprovação e ciência</font>

**Onde:** Acervo ▸ Documentos, Aprovações, Leitura obrigatória · **Capítulo:** *Acervo de documentos*

Política, norma interna e procedimento vivem no acervo, com versão, fluxo de aprovação e leitura obrigatória. Quem aprova recebe a etapa em **Aprovações**; quem precisa ler confirma a ciência em **Leitura obrigatória**. O **Pergunte à base** responde com a fonte citada, a **Análise de aderência** confere um documento contra as normas, e o **Grafo do acervo** mostra o que cada documento controla. Tipos, fluxos e espaços ficam em **Configuração do acervo**.

***

### <font color="#15803D">16. Monte o que você quer olhar</font>

**Onde:** Análise ▸ Construtor e Banco de widgets · **Capítulo:***Painéis e construtor*

No **Construtor**: a consulta, sem código, em cinco passos — sobre o quê, quais registros, o que quero ver, confira o resultado, dê um nome —; depois o widget, que veste a consulta, em seis passos; e só então o painel. O **Banco de widgets** traz a pergunta já feita, e o **Atalho: perguntar** faz os três de uma vez.

***

### <font color="#15803D">17. Publique o painel</font>

**Onde:** Análise ▸ Painéis e Gestão à Vista · **Capítulos:***Painéis e construtor* e *Murais e televisão*

1.     **Novo painel** → **colocar widget** ou **do banco de widgets** → arraste para posicionar.

2.     **Publicar**. Publicado, ele pode entrar no menu (grupo Gestão), numa pasta, e é o que o perfil de monitoramento enxerga.

3.     Em **Gestão à Vista**, **Novo mural** junta painéis publicados numa sequência que gira numa TV.

Leituras prontas, sem montar nada: **Resultado por hierarquia** (*Resultado por hierarquia*) e o bloco **Respostas por dimensão**, dentro de cada ciclo (*Dimensões*).

***

### <font color="#15803D">18. Apure o período do IMR</font>

**Onde:** IMR ▸ Contratos, Períodos, Apuração · **Capítulo:***IMR — Instrumento de Medição de Resultado*

Só existe onde o módulo foi ligado (Administração ▸ Normas disponíveis, bloco IMR), porque atende exclusivamente a contratos do Governo Federal. Cadastre o **contrato**, confira as **unidades**, abra o **período**, congele a base, receba os sinais e apure; ouça o **contraditório**, registre a **decisão**, e só então o **Faturamento** mostra o valor a pagar.

***

### <font color="#15803D">19. Deixe a plataforma trabalhar sozinha</font>

**Onde:** Automação · **Capítulos:** *Área de automação*, *Eventos e conectores*, *Automação de respostas* e *Avisos e e-mail*

O grupo reúne o que roda sem ninguém clicar:

•     **o que entra** — **Eventos e conectores** (SIEM, XDR, diretório, nuvem, ITSM) e **Fontes de conteúdo** (pastas, SharePoint, repositórios, e-mail);

•     **o que decide** — **Inspeções** com **Lentes**, **Automação de respostas** (a resposta que vira não conformidade ou risco) e **Avisos por regra**;

•     **o que sai** — **Destinos**: webhook, Teams, CITSmart ou e-mail.

O achado que a automação levanta cai em **Achados**, a caixa única, onde alguém confirma, descarta ou o transforma em não conformidade, risco ou caso. O coletor das inspeções entra por uma **conta de serviço** (*Sessão, trilha e contas de serviço*).

***

### <font color="#15803D">20. Saiba o que a plataforma diz em seu nome</font>

**Onde:** Administração ▸ E-mail e avisos · **Capítulo:***Avisos e e-mail*

Na aba **A conta**, o servidor de e-mail e o **Enviar teste**. Na aba **O fluxo do aviso**, cada aviso declara de que objeto partiu, quem recebe, que texto sai e para onde a resposta volta — e o texto é seu, com as variáveis à vista. Sem conta de e-mail, o aviso continua no **sino**, dentro da plataforma.

***

### <font color="#15803D">21. O portal, que é outro endereço</font>

**Onde:** Tratamento ▸ Catálogo de serviços, Políticas de atendimento, Ciclo de vida do caso, Regras de atendimento e Casos; o portal em /portal · **Capítulos:** *Portal, caso e ciclo de vida* e *Catálogo de serviços e política de atendimento*

Quem pede ajuda não entra no produto: entra em /portal, que procura na base de conhecimento antes de abrir o chamado. Para o atendimento funcionar, monte nesta ordem:

1.     **Catálogo de serviços** — o que se pode pedir (já vem com os serviços de GRC de fábrica).

2.     **Políticas de atendimento** — o prazo de cada relógio, por prioridade, o escalonamento e a matriz.

3.     **Ciclo de vida do caso** — a matriz de "de → para": o que não estiver marcado a plataforma recusa.

4.     **Regras de atendimento** — notificar, atribuir, escalar; ensaie antes de ligar.

A fila de quem atende é **Casos**.

***

### <font color="#15803D">22. Na dúvida, pergunte ao assistente</font>

**Onde:** a faísca no cabeçalho; Administração ▸ Modelo de linguagem; Automação ▸ Sandbox · **Capítulos:** *O assistente* e *Modelos de linguagem, parecer prévio e sandbox*

O assistente responde pelo manual e pelas telas que você pode abrir, e oferece o botão que leva até lá. Ele orienta; quem executa é você. Com um **modelo de linguagem** cadastrado ele conversa, e o modelo também dá o parecer prévio nas respostas e alimenta o Pergunte à base — sempre opinando, nunca decidindo. O **Sandbox** é onde se experimenta a correlação com eventos sem alterar a auditoria de ninguém.

***

## <font color="#15803D">A administração, quando precisar</font>

Nada disto é passo do caminho; é o que se ajusta uma vez e se revisita de vez em quando.

| **O quê**                                       | **Onde**                                                              | **Capítulo**                              |
| ----------------------------------------------- | --------------------------------------------------------------------- | ----------------------------------------- |
| login pela empresa (OpenID Connect, LDAP)       | Administração ▸ Diretório e identidade                                | *Integração com o diretório*              |
| sessão, trilha de auditoria e contas de serviço | Configuração ▸ Trilha de auditoria; Administração ▸ Contas de serviço | *Sessão, trilha e contas de serviço*      |
| empresa ou órgão nos textos                     | Administração ▸ Normas disponíveis                                    | *Como a instalação chama quem é auditado* |
| idioma                                          | Preferências                                                          | *Idiomas*                                 |
| layout, página inicial e cores                  | Preferências; console                                                 | *Layout e aparência*                      |
| acessibilidade                                  | —                                                                     | *Acessibilidade*                          |
| instalar no computador ou no celular            | o navegador                                                           | *Instalar como aplicativo*                |
| criar, parar e exportar tenants                 | /console                                                              | *Console da instalação*                   |

***

### <font color="#15803D">O caminho mais curto até o primeiro score</font>

Para ver a plataforma funcionando em dez minutos, numa instalação que já tem áreas e grupos: crie um alvo apontando para um grupo seu (passo 3), abra uma auditoria contra um framework de fábrica e lance (passo 6), dispare uma onda pequena para esse grupo (passo 7), responda (passo 8), peça a **outra pessoa** que aprove e clique **Apurar** (passo 9). A partir daí há score, cobertura, não conformidades e riscos.

[title] Avaliação de desempenho
[path] Aplicações/ERP/Manual do Usuário/

# Avaliação de desempenho

Avaliação de desempenho tem formatos: o gestor avalia o liderado (*Up Down*), o liderado avalia o gestor (*Down Up*), a pessoa se avalia e o gestor confirma (*180 graus*), e todo mundo em volta responde (*360 graus*).

**Você não vai encontrar essa escolha em lugar nenhum desta tela — e isso é de propósito.**

O formato não é uma configuração aqui. Ele é simplesmente **quem foi convidado**. Um ciclo cujos avaliadores são só gestores *é* Up Down. Um que convida também a própria pessoa, os pares e o time *é* 360 graus. Não há caixa a marcar porque não há nada a decidir além de quem responde — e um formato que ninguém pensou ainda não vai precisar de opção nova.

## Passo a passo

### Montar o formulário, antes do ciclo

1. **Abra "Formulários de avaliação"** (/evaluation-forms). Menu **Recursos Humanos → Formulários de avaliação**. Sem um formulário, o ciclo não abre — e essa recusa existe para não convidar centenas de pessoas a responder um questionário que não existe.
2. **Crie o formulário** com um nome que diga do que ele trata, e acrescente as questões.
3. Deixar sem competência é legítimo: "você trabalharia com esta pessoa de novo" vale ser perguntada e não pertence a nenhuma.
   Uma questão ligada a uma competência alimenta o perfil da pessoa **naquela competência** — e é daí que sai o radar e a comparação entre o esperado do cargo e o demonstrado. Questão solta deixa uma nota que ninguém sabe o que fazer com ela.
   **A competência é o campo que decide se isto serve para alguma coisa.**
4. O que essa recusa evita não quebra nada: a nota seria gravada, o radar a desenharia, e a pessoa apareceria ultrapassando um teto que existe justamente para nível significar a mesma coisa em todo lugar.
   **A escala nunca passa do teto da competência.** Se você ligar a questão a uma competência medida até 5 e pedir escala até 6, o sistema recusa — **e a mensagem traz o teto dela**, para você não ter de adivinhar qual dos dois números está errado.
5. **Questão de escala sem teto é recusada**, em vez de virar 5 por padrão. O padrão decidiria o instrumento por quem esqueceu o campo.
6. **Quem responde: deixar tudo desmarcado é o caso comum e significa TODOS.** Marcar papéis é como uma pergunta sobre liderar equipe deixa de ser feita a um par — que estaria respondendo sobre o que não consegue observar, e essa resposta pesaria igual a uma informada.

### Definir o critério de nota, antes de haver nota

1. **Abra "Critérios de nota"** (/score-rules). Menu **Recursos Humanos → Critérios de nota**. É aqui que se decide como várias opiniões viram um resultado — e o ciclo só compõe nota se apontar para um deles.
2. **Os pesos existem porque média chã é uma decisão que ninguém tomou.** Somar todo mundo em partes iguais afirma que a opinião de um par vale exatamente o mesmo que a do gestor e o mesmo que a visão da própria pessoa sobre si. Pode ser o que a organização quer; o que não pode é ser o que ela ganha por acidente da aritmética.
3. **Esconder o papel não é descartar a resposta.** Abaixo do mínimo o papel não aparece separado no resultado, mas as respostas dele **continuam compondo a nota geral**. São dois atos diferentes: o primeiro protege quem respondeu; o segundo puniria a pessoa avaliada pela quantidade de colegas que se deu ao trabalho de responder, que não é coisa que ela controle.
   **Com um respondente, "a média dos pares" É a resposta daquele par com o nome retirado.** Quem conhece a equipe descobre quem foi. E a partir do momento em que as pessoas percebem isso, ninguém responde com sinceridade de novo — o que custa mais caro que qualquer avaliação isolada. Por isso o sistema **recusa** qualquer valor abaixo de 2, e o padrão é 3.
   **O mínimo de respondentes por papel é o campo mais importante desta tela — e ele não é estatística.**
4. **Quem não tem meta no período não é quem errou todas as metas.** São fatos opostos. Um critério com 40% em metas tiraria 40% de alguém para quem ninguém definiu objetivo nenhum. O sistema deixa o peso **de fora do divisor** e avisa no resultado.
   **Peso de metas: zero exclui metas de vez**, que é o ajuste honesto para quem não trabalha com elas. As metas são **lidas** do módulo de indicadores — objetivo, indicador, meta e medição já existem lá, e um segundo lugar onde a meta de alguém mora seria um segundo lugar para discordar sobre se ela foi cumprida.
5. **Descartar extremos** só se aplica quando o papel tem **mais de duas** respostas — com duas, descartar a maior e a menor descarta tudo.

### Abrir um ciclo

1. **Abra "Ciclos de avaliação"** (/evaluation-cycles). Menu **Recursos Humanos → Ciclos de avaliação**. A lista traz cada ciclo com a janela de resposta, a data em que a estrutura foi lida e a situação.
2. **Os dois últimos podem ficar em branco enquanto o ciclo é rascunho**, e cada um é cobrado onde a ausência custa alguma coisa: sem questionário o ciclo **não abre**; sem critério ele abre e recebe respostas, mas **não compõe nota**. Deixar para depois é legítimo; descobrir na hora de abrir, na frente de todo mundo que ia ser convidado, não é.
   **Novo ciclo.** Informe o **nome** — algo que diga do que ele trata, como "1º semestre de 2026" —, as três datas, o **questionário** e o **critério de nota**.
3. **Esta é a armadilha da tela.** Coloque a data de hoje e quem mudou de área em março será avaliado pelos colegas da área nova — e nada vai parecer errado: os convites saem, as pessoas respondem, o relatório volta cheio. O erro só aparece quando alguém estranha o resultado, meses depois.
   **É o dia em que a estrutura da organização é lida.** Gestor, pares e liderados são derivados das lotações vigentes **nessa data**. Um ciclo aberto em julho, sobre o primeiro semestre, deve apontar para **janeiro**.
   **Cuidado com a data de referência: ela não é o começo das respostas.**
4. **A data de referência não pode ser posterior ao início das respostas.** O sistema recusa: derivar avaliadores de uma estrutura que só vai existir no mês que vem convidaria gente que ainda não está lá.
5. **Salve.** O ciclo nasce como **Rascunho**, e enquanto estiver assim pode ser editado à vontade.

### Abrir e convidar

1. **Ciclo que não alcança ninguém não abre.** Se a data de referência é anterior à primeira lotação da organização, o sistema recusa em vez de marcar como aberto um ciclo em que ninguém foi perguntado. Um ciclo vazio marcado como "Aberto" é indistinguível de um saudável.
   **Abrir é uma vez só e não tem volta.** Depois disso o ciclo **não pode mais ser editado** — mexer na data de referência deixaria convites já emitidos sem a regra que os produziu. Se a data estava errada, o caminho é cancelar e abrir outro.
   **Clique em "Abrir e convidar".** É aqui que o ciclo sai do papel: o sistema lê a estrutura na data de referência, cria uma avaliação por pessoa em serviço e emite os convites, cada um com o papel de quem responde.
2. *sem lotação na data de referência* — a pessoa não tinha lotação naquele dia.
   *chefia o próprio departamento* — não é problema: a autoavaliação já cobre, e um convite de gestor seria a mesma pessoa respondendo duas vezes;
   *o gestor nomeado já não estava na data de referência* — o cadastro aponta para alguém que saiu; convidar essa pessoa mandaria a avaliação para quem já foi embora;
   *o departamento não nomeia nenhum gestor* — falta preencher o gestor no cadastro do departamento;
   **Essa falta é invisível em todo o resto do sistema.** O ciclo abre, todos os outros convites saem, as telas ficam normais. É por isso que ela é dita em voz alta aqui, com o motivo, que é o que diz o que consertar:
   **Leia o aviso que aparece depois de abrir.** Ele diz quantas pessoas foram avaliadas e quantos convites saíram — e, principalmente, **quem ficou sem ninguém convidado como gestor**.
3. **Ninguém aparece duas vezes para a mesma pessoa.** O gestor senta no mesmo departamento que a equipe, então ele seria alcançado como gestor **e** como par. O sistema dá precedência ao fato estrutural: quem é gestor é gestor, quem é liderado é liderado, e "par" fica para quem não é nenhum dos dois. Sem isso, uma pessoa responderia duas vezes e a média penderia para ela.

**É aqui que você lê o formato.** Só *Gestor* na lista significa Up Down. *Ela mesma* mais *Gestor* é 180 graus. Os quatro papéis é 360 graus. Nada disso foi configurado.

**Veja quem foi convidado.** O botão abre a lista de avaliados; clicar num nome mostra os avaliadores com o papel de cada um — *Ela mesma*, *Gestor*, *Par*, *Liderado*.

### Encerrar

1. **Encerre quando a janela fechar.** As respostas param de ser aceitas e o que foi apurado é o que vale.
2. **Cancelar não apaga nada.** Um ciclo que alcançou pessoas é um fato — alguém foi convidado, e possivelmente respondeu. "Por que eu preenchi aquilo à toa?" merece um registro, não uma tela em que o ciclo simplesmente não está mais lá. Ciclo já encerrado não pode ser cancelado.

### Compor o resultado

1. **Abra "Ver quem foi convidado", clique no nome da pessoa e em "Compor o resultado".** O sistema aplica o critério de nota do ciclo às respostas **enviadas** — formulário começado e não enviado não é opinião que alguém deu, e não entra.
2. **Compor um ciclo ainda aberto é recusado.** Uma nota apurada no meio da janela é um número que alguém vai citar, e ele muda conforme as respostas que faltam chegam. Encerre primeiro.
3. E essas respostas escondidas **estão** na nota final. Ver — no papel e um número no resultado não é inconsistência: é a diferença entre proteger quem respondeu e punir quem foi avaliado.
   Papel **abaixo do mínimo** aparece sem média, com o motivo escrito e **com a contagem de respondentes**. Isso é de propósito: "dois pares responderam, mas a média deles não vai ser mostrada" e "nenhum par respondeu" são fatos diferentes, e sumir com a linha faria os dois parecerem a mesma coisa.
   **Leia o que o painel diz sobre cada papel, não só a nota final.**
4. **"Nenhuma meta mensurável no período" não é nota zero em metas.** É o aviso de que o peso das metas saiu do cálculo. Se ele aparece para alguém que deveria ter meta, o que falta está no módulo de indicadores — objetivo, indicador, meta ou medição —, não aqui.

### A área do colaborador

1. E é ela que faltava para a avaliação funcionar. Até aqui, responder exigia a permissão de **abrir ciclos** — que nenhum colaborador comum tem. Os convites saíam e ninguém conseguia empurrar a porta.
   **Abra "Minhas avaliações"** (/my-evaluations). Menu **Recursos Humanos → Minhas avaliações**. Esta tela é de todo mundo: **não exige permissão nenhuma**, porque o assunto dela é o que é seu.
2. **"Não tenho como responder esta"** é uma resposta legítima: quem não convive com a pessoa avaliando às cegas é pior que uma resposta a menos.
   **Salvar não é enviar.** Enquanto a rodada está aberta você pode voltar e mudar. Depois de **enviar**, não — o que foi respondido é o que compôs a nota, e alterar depois faria o resultado publicado deixar de decorrer do que está registrado.
   **Responda o que lhe couber.** Cada convite traz a rodada, o seu papel e o prazo. As questões já vêm filtradas pelo papel: um par não recebe pergunta sobre liderar equipe.
3. **Nível esperado em branco não é zero.** Quando o cargo não define expectativa para aquela competência, a linha tracejada simplesmente não passa por ali. Desenhar zero mostraria uma lacuna perfeita num eixo onde ninguém pôs a barra.
   **O radar não recalcula nada** — ele lê o que foi gravado na apuração. É por isso que o número dele e o da apuração não podem divergir.
   **Veja o seu radar.** Encerrada a rodada e apurado o resultado, o radar mostra, competência a competência, **o nível que o cargo espera** e **o que a avaliação apontou**.
4. **Três recusas de leitura, cada uma dizendo o que é.** "A rodada ainda está aberta", "encerrou mas ninguém apurou" e "menos gente respondeu que o mínimo do critério" são fatos diferentes. O terceiro é o mesmo motivo de sempre: **com poucos respondentes, o formato do radar identifica quem respondeu** tão bem quanto uma média de uma pessoa só.
5. **Não é quem se reporta a você hoje.** A rodada foi montada sobre a estrutura da data de referência. Ler a estrutura de hoje entregaria o resultado de quem mudou de área ao gestor que nunca o avaliou, e o esconderia de quem avaliou — sem nada na tela dizendo que mudou.
   **Se você é gestor, o card "Resultados da minha equipe" aparece** — e só com quem **aquela rodada** convidou você a avaliar como gestor.
6. **Ninguém navega pelo desempenho alheio.** Tentar abrir o resultado de quem não é você nem da sua equipe responde **não encontrado** — e não "sem permissão", que já confirmaria que aquela pessoa foi avaliada naquela rodada.

## Erros comuns

***

- **"O ciclo termina antes de começar."** A data de fim é anterior à de início.
- **"A data de referência não pode ser posterior ao início do ciclo."** Ver o passo 4.
- **"O ciclo já está aberto."** Abrir é uma vez só. Para refazer, cancele e crie outro.
- **"O ciclo não tem questionário."** Monte o formulário antes — ver o passo 1.
- **"A competência X é medida até N."** A escala da questão passa do teto da competência ligada.
- **"Esta questão não é feita a quem responde na sua condição."** A questão foi marcada para outros papéis; quem está respondendo não é um deles.
- **"O ciclo não alcança ninguém na data de referência."** Nenhuma pessoa tinha lotação naquele dia — quase sempre uma data de referência escolhida cedo demais.
- **"Só um ciclo aberto pode ser encerrado."** Rascunho não se encerra: ou se abre, ou se cancela.
- **"O ciclo ainda está aberto."** Encerre antes de compor — ver o passo 12.
- **"O ciclo não tem critério de nota."** Aponte o ciclo para um critério — ver o passo 2.
- **"O mínimo de respondentes não pode ser menor que 2."** É recusa de projeto, não de validação de campo: abaixo de 2 a média de um papel identifica quem respondeu.
- **"Os pesos somam zero."** Um critério que não pesa nada não compõe nada.
- **"Peso negativo não é aceito."** Faria a resposta boa de alguém **baixar** a nota — o que quer que isso modele, não é o que foi dito a quem preencheu o formulário.
- **"Convite de avaliação não encontrado."** Na área do colaborador, isto aparece quando o convite não é seu. É a mesma resposta que se dá a um convite que não existe, **de propósito**: dizer "sem permissão" já confirmaria que aquele convite existe e de quem é.
- **"Este login não está vinculado a um colaborador."** A tela é sua, mas o sistema não sabe quem você é como pessoa da folha. Quem faz o vínculo é o RH, no cadastro do colaborador.


[title] Agility
[path] Aplicações/

### Primeiro contato em 30 minutos

Para quem quer ver o Agility funcionando antes de mergulhar nas seções completas do manual.

Este manual documenta, seção por seção, tudo que o Agility faz — da criação de um Workspace até o financeiro, o SAFe e os relatórios. Se você tem meia hora e quer entender o fluxo principal antes de ler as seções completas, comece por aqui.

O roteiro abaixo usa dados reais de demonstração já carregados no ambiente (Workspace "Portal de Serviços"), então cada tela citada existe e pode ser aberta enquanto você lê.

Passo a passo

::::WorkflowBlock
:::WorkflowBlockItem
**Escolher o Workspace**

Abra "Workspaces" no topo da navegação. Um Workspace é o espaço de colaboração de uma organização — membros, permissões e todo o trabalho vivem dentro dele. Escolha (ou crie) um Workspace; o restante da aplicação vive dentro dele.
:::

:::WorkflowBlockItem
**Visão geral do Workspace**

Ao entrar no Workspace, a "Visão geral" resume o que existe ali: quantos Projetos, Portfólios, Times e ARTs (trens SAFe), além dos projetos recentes. É o ponto de partida para navegar — a barra lateral, à esquerda, agrupa tudo em quatro blocos: Workspace (Projetos, Times, ARTs), Estratégia (Portfólios, Produtos, Releases), Gestão (Metas, Pessoas, Financeiro) e Sistema (Integrações, Configurações).
:::

:::WorkflowBlockItem
**Abrir um projeto e seu quadro**

Clique em "Projetos" na barra lateral e abra um projeto existente. Cada projeto nasce com um modelo de trabalho — Kanban, Scrum, Tradicional ou SAFe — e o quadro (Board) é onde o time move o trabalho dia a dia: colunas (lanes), cartões (tarefas), e as abas de Backlog, Sprints/Gantt (conforme o modelo), Riscos, Financeiro, Documentos e Histórico.
:::

:::WorkflowBlockItem
**Ver o financeiro e os relatórios**

No menu "Financeiro" do Workspace você encontra cadastros (bancos, plano de contas, clientes, contratos) e, dentro de cada projeto/quadro, os lançamentos e a rentabilidade. Em "Relatórios", o Workspace mostra desempenho por time e custo previsto vs. realizado.
:::

:::WorkflowBlockItem
**Explorar o SAFe (se o Workspace tiver um ART)**

Se o Workspace tiver pelo menos um ART (Agile Release Train) cadastrado, o item "ARTs" aparece na barra lateral. Ali vivem o PI Planning, os Épicos/Features/Histórias priorizados por WSJF, o Backlog do trem e os riscos ROAM — a camada de ágil em escala do Agility.
:::
::::

![](https://itsm-labdev.cloud4biz.com/agility-v2/docs/screens/manual-workspaces-lista.webp "Lista de Workspaces do usuário, com contagem de projetos, tarefas e fluxo ativo de cada um")

![](https://itsm-labdev.cloud4biz.com/agility-v2/docs/screens/manual-workspace-visao-geral.webp "Visão geral de um Workspace com os cartões de Projetos, Portfólios, Times e ARTs, a lista de projetos recentes e a barra lateral com os quatro grupos de navegação")

:::hint{type="success"}
:FontAwesome[]{icon="fa-solid fa-check"}**&#x20;Verificação**

- Você consegue nomear os quatro grupos da barra lateral do Workspace (Workspace, Estratégia, Gestão, Sistema) e o que cada um contém.
- Você abriu pelo menos um projeto e viu seu quadro (Board) com colunas e cartões.
:::


[title] Folha de pagamento (motor de cálculo CLT)
[path] Aplicações/ERP/Manual do Usuário/

# Folha de pagamento (rubricas e o S-1010)

:::BlockQuote
Pré-requisitos: [Cadastro trabalhista (contrato de trabalho)](docId\:LxePSOpck0CqjzlijWZj3), porque a folha é calculada sobre **vínculos**; e o bloco de **estabelecimentos** de [Cadastro fiscal próprio](docId\:Q-zx6Qk4pMFD09yrhmsve), porque a tabela de rubricas é declarada sob um **declarante** e o sistema confere se ele existe.
:::

## Introdução

***

**Rubrica** é cada linha do contracheque. Salário-base, hora extra a 50%, adicional noturno, adiantamento, desconto do plano de saúde, desconto do sindicato, vale-transporte. Cada uma tem um nome que o empregado lê, um código pelo qual o governo a conhece, e um punhado de marcações que decidem em que contas ela entra.

Essas marcações não são detalhe de preenchimento: **são elas que decidem o dinheiro**. Se a rubrica entra na conta do INSS, a empresa e o empregado recolhem sobre ela. Se entra na do imposto de renda, o empregado paga imposto sobre ela. Se entra na do FGTS, a empresa deposita sobre ela. Uma rubrica cadastrada sem essas marcações não é uma rubrica incompleta — é uma rubrica que **cala** sobre a coisa mais cara que ela tem a dizer, e o silêncio vira recolhimento a menos, que aparece com multa e juros anos depois. Por isso o sistema **não assume nada por omissão**: deixar uma incidência em branco é recusado, e deixar o teto remuneratório sem resposta também.

O segundo ponto é o que quase todo mundo erra na primeira vez: **as regras de uma rubrica mudam com o tempo, e a rubrica continua sendo a mesma**. Quando o acordo coletivo eleva o adicional noturno a partir de 1º de junho, isso não cria uma rubrica nova — cria uma **vigência** nova da mesma rubrica. A vigência anterior é encerrada na véspera e **preservada**, para que refazer a folha de maio continue lendo a regra de maio. E folha se refaz o tempo todo: pagamento retroativo, revisão de rescisão, perícia trabalhista.

Há um detalhe de calendário que parece pedante e não é: a regra de uma rubrica vale **a partir de um mês de competência**, não de um dia. É assim que o governo pede e é assim que a folha funciona — não existe "esta rubrica passou a incidir no dia 17". Por isso a data se informa como AAAA-MM.

Por fim, as rubricas ficam guardadas em **tabelas de rubricas**. A empresa pode manter mais de uma, e o governo suporta isso de propósito: o código de uma rubrica nunca se repete **dentro** de uma tabela, mas pode repetir **entre** tabelas — a rubrica 1001 de uma tabela não é a mesma 1001 da outra.

## Quem pode ver e quem pode alterar

***

São duas autoridades diferentes, e a separação é intencional:

- **Consultar rubricas** — quem tem READ\_PAYROLL\_RUBRIC. Hoje: **Gerente de RH**, **Contador** e **Auditor**. É a autoridade de quem confere a classificação antes do primeiro fechamento e de quem, meses depois, pergunta com que regra determinada rubrica foi declarada.
- **Cadastrar e alterar** — quem tem MANAGE\_PAYROLL\_RUBRIC. Hoje: **somente o Gerente de RH**. Alterar uma incidência muda quanto imposto é retido de todo mundo que a rubrica alcança.

Quem não tem a autoridade de leitura recebe uma **recusa explícita** ao abrir a tela — e não uma lista vazia. Os dois são respostas opostas e nunca aparecem iguais.

## A ordem em que o sistema cobra as coisas

***

Esta é a parte que ninguém descobre lendo tela por tela: **a folha recusa em cascata**, e cada recusa aponta para um cadastro que deveria ter vindo antes. A tabela abaixo é essa ordem, na sequência em que o operador esbarra nela. Vale ler antes de começar — economiza o dia em que alguém tenta fechar a competência e descobre que faltava algo lá atrás.

| #  | O que precisa existir                                                   | O que acontece se faltar                                                                                                                                      |
| -- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1  | **Estabelecimento da empresa**                                          | O catálogo de rubricas e o roteiro mensal **não são instalados**. Veja o aviso logo abaixo — é a falha mais silenciosa desta página.                          |
| 2  | **Tabelas legais publicadas** (INSS e imposto de renda)                 | O cálculo é recusado **nomeando a tabela** que falta. Os encargos da empresa são a exceção: sem eles a folha roda, porque não chegam ao colaborador.          |
| 3  | **Roteiro de cálculo em vigor**                                         | A folha inteira não abre — não é uma pessoa, é a competência.                                                                                                 |
| 4  | **Colaborador com vínculo**                                             | Sem vínculo não há a quem pagar.                                                                                                                              |
| 5  | **Salário no contrato**                                                 | O painel de conferência do vínculo aponta a remuneração como faltando.                                                                                        |
| 6  | **Jornada do vínculo**                                                  | Necessária para o ponto. Vínculo com estabilidade exige **motivo escrito** para trocar.                                                                       |
| 7  | **Atribuição das rubricas** — a quem cada verba se aplica               | A verba fica **ausente** do holerite. Não zerada: ausente, que é diferente e mais difícil de notar.                                                           |
| 8  | **Resultado do período** — trabalhado, noturno, extra                   | **Ausente não é zero.** Sem lançamento, a linha é recusada e **trava o fechamento**; com zero declarado, paga zero. Esta distinção é a que mais gera chamado. |
| 9  | **Credor e categoria financeira por rubrica**, e a categoria do líquido | O lote de pagamento fecha com os totais certos e **zero títulos**. A categoria do líquido é perguntada na **abertura** da folha, não no fechamento.           |
| 10 | **A pessoa também cadastrada como parceiro**                            | O título sai sem destinatário.                                                                                                                                |

:::BlockQuote
**O caso do item 1, dito por extenso porque ele não avisa.** O catálogo inicial de rubricas CLT e o roteiro mensal são instalados por uma migração que **exige um estabelecimento cadastrado**. Só que o estabelecimento nasce quando alguém cadastra a empresa — depois da migração ter passado. Quando isso acontece, a instalação é **descartada em definitivo** e o ambiente fica sem roteiro de cálculo: ninguém consegue abrir uma folha, e **nada na tela explica por quê**. Se você recebeu um ambiente novo e a lista de roteiros está vazia, é isto. Fale com quem instalou antes de cadastrar qualquer coisa por cima.
:::

### As armadilhas que valem saber antes

- **Rubrica com fórmula pede QUANTIDADE, não valor.** Informar o valor devolve erro de campo. A fórmula é que transforma quantidade em dinheiro — é o motivo de ela existir.
-

**O desconto de adiantamento salarial saiu dessa lista em 2026-08-13.** Ele nascia desligado pela mesma razão aparente, mas o dado dele não falta: o valor chega pronto do **Financeiro**, pela recuperação de adiantamento, e é justamente por isso que essa rubrica nunca teve fórmula. Na prática, cada ambiente novo exigia **dois** atos manuais — ligar a rubrica e declarar a vigência — antes que um único adiantamento pudesse ser descontado; e quem ligasse só a rubrica esbarrava numa segunda recusa, que rejeita **a pessoa inteira** na folha em vez da linha. Agora ela já vem ligada e com vigência.

**Rubrica desligada recusa o lançamento.** Várias nascem assim de propósito — hora extra, adicional noturno, DSR, desconto de faltas e salário-família. O motivo é sempre o mesmo: falta o dado de entrada que a fórmula delas exige, e ligar a rubrica sem esse dado troca a recusa por um valor errado. Ative depois de ter o que ela precisa.

- **Termo de estágio exige um parceiro com o papel de instituição de ensino** — não serve qualquer parceiro. E carga horária acima do teto da etapa é recusada citando os dois números.
- **Quem administra pessoal normalmente não cadastra parceiro.** Se o cadastro do estágio depende de uma instituição que ainda não existe, o operador vai precisar de alguém do cadastro — vale combinar antes, não no meio.
- **Jornada com vigência aberta cobre tudo depois dela.** Declarar outra em data posterior é recusado por sobreposição: feche a anterior primeiro.
- **A ordem judicial se declara inteira** — processo, vara e beneficiário — ou nenhum dos três.
- **O nome do termo na fórmula importa, e a grafia é literal.** Um termo escrito com acento onde o catálogo não tem acento é hoje **recusado nomeando o termo**. Antes disso, a fórmula pagava **zero em silêncio**, com o holerite fechando — é a razão de a recusa existir.

## Passo a passo

***

### Criar a tabela de rubricas

Antes de cadastrar a primeira rubrica é preciso ter onde guardá-la.

1. **Abra "Tabelas de rubricas"** (/payroll-rubric-tables). No menu lateral, em **Recursos humanos → Tabelas de rubricas**.
2. No cartão **Nova tabela de rubricas**, preencha:
   - **Identificador da tabela** — é o ideTabRubr que vai no evento. Aceita texto, no máximo 8 caracteres.
   - **Nome** — como a tabela aparece nesta tela. Não é transmitido.
   - **Declarante** — **Empresa (CNPJ raiz)** ou **Estabelecimento (CNPJ completo)**.
   - **Identificador do declarante** — o identificador do estabelecimento ou da empresa sob a qual a tabela é declarada.
3. **O declarante é conferido.** O sistema procura o identificador no cadastro que o tipo escolhido nomeia: estabelecimento entre os estabelecimentos, empresa entre as empresas. Uma tabela pendurada num CNPJ que a organização não tem produz a mesma rejeição do governo, sem nada na tela que dê pista.
   **O identificador 1 é recusado — e o 01 também.** Ele é reservado à **Tabela de Rubricas Padrão do eSocial**, cujas rubricas o empregador **não declara**. Uma tabela criada sob ele parece perfeitamente normal nesta tela e é **rejeitada pelo governo na primeira transmissão**, semanas depois de alguém tê-la preenchido de rubricas.
   Clique em **Salvar**.
4. Uma tabela que sai de uso é **desativada** pelo botão **Desativar** na linha dela. Não há remoção: rubricas já declaradas sob aquele identificador precisam continuar explicáveis.

### Cadastrar uma rubrica

1. **Abra "Rubricas de folha"** (/payroll-rubrics). No menu lateral, em **Recursos humanos → Rubricas de folha**.
2. No cartão **Nova rubrica de folha**, preencha primeiro a identidade da rubrica:
   - **Tabela de rubricas** — em qual lista ela entra.
   - **Código da rubrica** — o codRubr, até 30 caracteres. Único **dentro daquela tabela**.
   - **Descrição no contracheque** — o que o empregado lê.
   - **Tipo** — **Provento**, **Desconto**, **Informativa** ou **Encargo do empregador**. Este é o eixo **interno**: decide onde a linha aparece no contracheque e como entra nos totais.
3. Em seguida, a **primeira vigência** — ela é cadastrada **junto** com a rubrica, e não depois:
   - **Vigente a partir de (competência)** — no formato AAAA-MM.
   - **Natureza do eSocial (natRubr)** — escolhida do dicionário oficial (Tabela 03), que o sistema já traz carregado.
   - **Tipo no eSocial (tpRubr)** — **Vencimento**, **Desconto**, **Informativa** ou **Informativa dedutora**.
   - **Incidência de contribuição previdenciária (codIncCP)** e **de FGTS (codIncFGTS)** — escolhidas de uma **lista fechada**, cada código com o agrupamento oficial ao lado. **Repare no 31**: de 31 a 35 a linha **não é base** — é a contribuição *descontada do segurado*. A regra intuitiva "qualquer coisa diferente de 00 compõe a base" transformaria o INSS retido em base de INSS, para todo mundo da folha. O rótulo nomeia o **grupo** que a tabela oficial publica, não cada código individualmente.
   - **Incidência de IRRF (codIncIRRF)** — continua **texto livre**, e não é esquecimento: a Tabela 21 tem 87 códigos misturando base, retenção, dedução e isenção no mesmo campo, é publicada por faixas (nem todo número da faixa existe) e é a única das três com vigência — **15 códigos estão extintos desde 30/06/2021**, inclusive 0 e 1. Uma lista fechada montada das faixas recusaria códigos válidos; uma que ignorasse a vigência ofereceria códigos mortos.
   - **Incidência de PIS/PASEP (codIncPisPasep)** — só se aplica a declarante cujo S-1000 afirma isso; deixe em branco caso contrário.
   - **Compõe o teto remuneratório (art. 37, XI)** — **Sim** ou **Não**. Nasce em **Sem resposta**, e salvar assim é recusado.
   - **Casas decimais** e **Modo de arredondamento** — por rubrica, porque instrumentos diferentes mandam arredondar de formas diferentes.
4.

**Se a incidência começa com 9, o processo passa a ser obrigatório.** A família 9X de qualquer tabela de incidência significa **suspensa por decisão judicial**. Ao digitar um código assim, aparece o campo do processo correspondente, e salvar sem preenchê-lo é recusado: suspender a cobrança sem dizer por decisão de quem deixa o empregador sem defesa.

**tpRubr é declarado, nunca deduzido da natureza.** O eSocial publica **uma única** amarração entre os dois campos, e nenhum mapeamento geral. Se o sistema escolhesse o tipo a partir da natureza, ele transmitiria um valor que ninguém decidiu.

**Por que a vigência vem junto.** Uma rubrica sem vigência é uma rubrica **sem natureza e sem incidências**. Se fosse possível salvá-la assim e classificá-la depois, toda competência calculada nesse intervalo teria de ser refeita — o que não é uma correção de cadastro, é passivo.

Clique em **Salvar**.

### Alterar a regra de uma rubrica

Rubrica **não se edita** quando a regra muda. Declara-se de novo.

1. Na relação, clique no lápis da rubrica. Abre a tela de detalhe (/payroll-rubrics), com o cartão **Vigências por competência** listando, da mais recente para a mais antiga, o intervalo de competências, a natureza, o tpRubr, as três incidências, o teto e o arredondamento de cada uma.
2. No cartão **Declarar a partir de nova competência**, informe a competência em que a regra nova passa a valer e preencha os mesmos campos da primeira vigência. Clique em **Declarar**.
3.

**Competência com folha já fechada é recusada.** Se já existe folha lançada para aquele mês, alterar o que a rubrica declarou nela faria o que foi transmitido e o que está no sistema divergirem em silêncio. O caminho é a **retificação** (S-1298), não a edição.

**A competência nova tem de ser posterior à da vigência em curso.** Igual ou anterior é recusado, e a mensagem diz desde quando a vigência atual vale — se a nova começasse no mesmo mês, não sobraria mês nenhum para encerrar a anterior, e as duas responderiam pela mesma competência.

O sistema encerra a vigência em curso **na véspera** da competência informada e abre a nova. Nada é sobrescrito: a linha antiga continua na tabela e continua respondendo pelos meses que cobria.

1. Para ver **quem** mudou o quê e quando, abra o cartão de **histórico** no rodapé da tela de detalhe. Ele mostra a alteração campo a campo — o valor anterior e o novo — com a data e o autor.

### Descobrir o que a rubrica declarava em um mês

Quando a rubrica já tem quatro ou cinco vigências, responder *"qual delas valia em março de 2026?"* lendo a tabela é um exercício que se erra na direção que mais custa: pega-se a regra **atual** para uma competência velha, e o recálculo passa a discordar do holerite que foi emitido.

No rodapé do cartão **Vigências por competência** há o bloco **"O que esta rubrica declarava em uma competência?"**. Informe o mês no formato AAAA-MM e clique em **Consultar**. A resposta traz a vigência que **cobre** aquele mês — o intervalo, o tpRubr e as três incidências.

:::BlockQuote
**Competência anterior à primeira declaração é recusada, não respondida com a linha mais antiga.** Se a rubrica só passou a valer em 2026-01, perguntar por 2025-11 devolve uma recusa. Devolver a vigência mais próxima seria afirmar uma regra que não existia naquele mês — que é justamente o erro que este bloco existe para evitar.
:::

### Tirar uma rubrica de uso

Use o botão **Desativar** no topo da tela de detalhe. A rubrica deixa de ser oferecida em lançamentos e cálculos novos, e continua legível nas competências em que foi usada. **Não há remoção**, e a ausência do botão é a proteção: uma rubrica usada num cálculo não pode sumir.

## Bases de cálculo — os acumuladores

***

**Abra "Bases de cálculo"** (/payroll-calculation-bases). No menu lateral, em **Recursos humanos → Bases de cálculo**.

A base do INSS não é um campo em lugar nenhum. Ela é a **soma das verbas que incidem sobre INSS, menos as que a reduzem** — ou seja, um *acumulador*. Por isso a pergunta "esta verba entra nesta base?" é respondida no cadastro de cada verba, e não no meio de uma conta.

Esta tela é onde se vê **quais acumuladores existem**. O sistema já traz oito: INSS, IRRF, FGTS, THIRTEENTH\_INSS, THIRTEENTH\_IRRF, UNION\_DUES, SEVERANCE e NET\_PAY. Uma fórmula depois **lê** uma delas escrevendo \{BASE.INSS}, já apurada.

### Cadastrar uma base própria

Preencha **Código**, **Nome** e **Em vigor a partir de** (competência AAAA-MM) e clique em **Salvar**. A base passa a poder ser usada nas fórmulas e a receber a declaração de participação das verbas.

:::BlockQuote
**As oito bases do sistema aparecem na lista e não podem ser alteradas nem desativadas.** Elas ficam visíveis de propósito: escondê-las faria o cadastro parecer vazio e levaria alguém a criar um segundo INSS — e duas bases com o mesmo significado dobram uma linha do holerite **em silêncio**. A coluna **Origem** distingue as duas.
:::

:::BlockQuote
**Base é versionada por competência, não por data.** Norma que muda em julho é uma versão nova a partir de 2026-07, e a anterior é encerrada em junho automaticamente. Recalcular um mês anterior continua lendo o que valia lá.
:::

### Corrigir uma base

Clique no **lápis** na linha. O formulário do topo se preenche com a base e o título muda para **Editar**. Corrija o **Nome** e clique em **Salvar alterações**.

:::BlockQuote
**Código e competência ficam bloqueados na correção, de propósito.** Mudar a competência de uma versão que já tem sucessora deixaria a cadeia de vigências inconsistente — e o sistema aceitaria sem reclamar. Enquanto isso não for tratado no servidor, o caminho para trocar a competência é declarar uma **versão nova**, que é o que a nota acima descreve.
:::

Em base do **sistema** o lápis aparece, mas ao salvar o servidor recusa e a tela mostra a frase dele, nomeando qual base. É melhor assim do que uma linha sem ação nenhuma, que não explica nada.

### Tirar uma base de uso

Use **Desativar** na linha. **Não há remoção**: a composição de toda competência já fechada aponta para a base, e apagá-la moveria valor num mês que ninguém tocou.

## Fórmulas — a conta de cada verba

***

**Abra "Fórmulas da folha"** (/payroll-formulas). No menu lateral, em **Recursos humanos → Fórmulas da folha**.

Aqui o analista escreve a conta de uma verba usando os **termos que o sistema oferece** — e nada além deles. É de propósito menos livre que uma linguagem de programação: uma conta que pode tudo pode também travar o fechamento de setecentos holerites, ou ler dado que quem a escreveu não deveria ver.

Escreva o termo entre chaves: \{SALARY\_BASE} / \{DAYS\_IN\_COMPETENCE} \* \{WORKED\_DAYS}.

O campo **cresce** conforme a conta cresce — uma fórmula de uma dúzia de termos fica inteira na tela, em vez de correr para o lado e esconder o próprio começo.

### Achar o termo sem decorar o nome

Há dois caminhos, e o primeiro é o mais rápido:

- **Digite \{ no campo da expressão.** A lista aparece ali mesmo, filtrando enquanto você digita — e filtra tanto pelo código quanto pelo nome em português, então \{noturn já acha \{NIGHT\_MINUTES}. Use as **setas** para escolher e **Enter** para inserir; **Esc** desiste. O termo entra completo, no lugar do que você tinha começado a digitar.
- **Ou clique no painel de termos**, que **flutua** sobre a tela e você **arrasta pelo cabeçalho** para onde não atrapalhe. Ele vem agrupado por espécie — dinheiro, tempo, contagens, percentuais — com um filtro no topo, e o termo entra **onde o cursor está**, não no fim: quem estava no meio de um parêntese continua dentro dele. O painel **guarda onde você o deixou**. Fechou? O botão **Termos que você pode usar**, ao lado do título do cartão, traz de volta. Sem mouse: dê **Tab** até o cabeçalho do painel — as **setas** movem, **Shift+seta** move mais rápido e **Esc** fecha.

:::BlockQuote
**O vocabulário vem do próprio sistema**, então nunca diverge do que o cálculo de fato conhece. O que vai na fórmula é o **código entre chaves**; o nome ao lado é só como a tela lê para você, e é por isso que ele não é traduzido dentro da expressão — uma fórmula escrita em um idioma precisa continuar legível em outro.
:::

:::BlockQuote
**Enquanto você escreve, a tela confere três coisas — e só essas três.** Em **vermelho**: palavra que não existe no vocabulário (dizendo qual), chave aberta e não fechada, e **dois termos colados** sem operador entre eles (\{A} \{B}), que o servidor recusa. Em **âmbar**: termo que **ainda não tem quem o produza** — veja o aviso abaixo. Em cinza, e só quando não há nada em vermelho, quantos termos foram reconhecidos. Ela **não** julga a conta: quem decide se a expressão faz sentido é o servidor, ao salvar. Uma tela que desse o próprio veredito acabaria escondendo o dele.
:::

### Publicar uma fórmula

Preencha **Código**, **Nome**, a **Expressão**, o que ela **Produz** e a competência inicial. Ao salvar, o sistema confere que cada palavra usada existe no vocabulário e que a conta faz sentido como expressão.

:::BlockQuote
**Se você escrever um termo errado, a recusa diz QUAL palavra não existe.** Não é "fórmula inválida" — essa mensagem mandaria você reler a própria conta caractere a caractere, no meio de um fechamento.
:::

:::BlockQuote
**A armadilha mais cara, e é a razão desta tela existir: termo sem valor NÃO é zero.** Um desconto cuja base não chegou descontaria nada, a empresa absorve a diferença, e **ninguém abre chamado por desconto que não veio**. O sistema recusa a linha e **nomeia o termo** que faltou.
:::

:::BlockQuote
**Termo marcado "sem produtor" é aceito na publicação e recusa a linha TODO mês.** São **quatro** dos dezessete termos: existem na lista, a fórmula que os usa é publicada sem uma reclamação, e aí a linha do holerite é recusada em toda competência, porque nada nesta versão do sistema preenche o valor deles. Três vêm do **ponto** — \{WORKED\_MINUTES}, \{NIGHT\_MINUTES}, \{OVERTIME\_MINUTES} — que ainda está por construir; o quarto é \{SALARY\_UNIT\_AMOUNT}. Eles continuam na lista de propósito, para quem escreve a fórmula hoje deixar a conta pronta, mas a tela **avisa em âmbar**, tanto no painel de termos quanto abaixo da expressão.
:::

:::BlockQuote
**Termo marcado "depende de acordo" ou "depende de tabela" é outra coisa — e essa você resolve.** Ele responde assim que o cadastro existir: ligue o vínculo a um **sindicato com acordo vigente** (\{HOURLY\_RATE}, \{MONTHLY\_BASE\_MINUTES}, \{VACATION\_BONUS\_PERCENT}) ou publique a **tabela legal** da competência (\{MINIMUM\_WAGE}). Sem o cadastro, a linha é recusada nomeando o termo — o sistema **não** chuta um divisor de 220 horas nem um terço constitucional, porque o divisor difere por sindicato e chutar seria pagar errado com cara de acerto. A marca é cinza, e não âmbar, porque aqui há o que fazer.
:::

:::BlockQuote
Os que respondem **sempre**: \{SALARY\_BASE}, \{DAYS\_IN\_COMPETENCE}, \{DAILY\_RATE} (o salário dividido por trinta, que é o mês do mensalista na CLT — não pela quantidade de dias do mês), \{WORKED\_DAYS}, \{ABSENCE\_DAYS}, \{DEPENDENT\_COUNT\_IRRF}, \{DEPENDENT\_COUNT\_FAMILY\_ALLOWANCE}, \{NIGHT\_PREMIUM\_PERCENT} (o acordo, ou os 20% do art. 73 quando não há acordo) e \{THIRTEENTH\_TWELFTHS}.
:::

:::BlockQuote
**Marque "elegibilidade" só em fórmula que produz uma condição.** Uma que devolve valor leria qualquer número diferente de zero como "sim", e a regra nunca excluiria ninguém. O sistema recusa a combinação.
:::

### Mudar a conta quando o acordo muda

Não edite a fórmula publicada. Declare uma **versão nova** com a competência em que a regra nova passa a valer — a anterior é encerrada no mês de véspera e continua respondendo pelos meses em que valeu. Correção de erro de digitação, aí sim, é edição da versão publicada.

**Para corrigir a digitação:** clique no **lápis** na linha da fórmula. O formulário do topo se preenche e o título passa a **Editar**, mostrando ao lado o código e a competência **como o registro ainda os guarda**. Corrija a expressão e clique em **Salvar alterações**; **Cancelar** desiste sem gravar. Se a expressão citar um termo que o sistema não conhece, a recusa vem do servidor e nomeia o termo.

:::BlockQuote
**Código e competência ficam bloqueados na correção.** Trocar a competência de uma versão que já tem sucessora deixaria a cadeia de vigências inconsistente, e hoje o servidor aceitaria isso sem reclamar. Para mudar quando a fórmula passa a valer, o caminho é a **versão nova** descrita acima.
:::

## Roteiros de cálculo — a ordem

***

**Abra "Roteiros de cálculo"** (/payroll-routines). No menu lateral, em **Recursos humanos → Roteiros de cálculo**.

Um roteiro é a lista de passos que a folha executa, em sequência: calcule estas verbas, acumule aquela base, aplique a tabela do IRRF, feche o holerite. **A ordem não é apresentação — ela decide os números.**

### Montar os passos de um roteiro

Clique no ícone **Passos** na linha do roteiro. O painel abre com os passos na ordem em que rodam, em leitura. Para mexer, clique em **"Editar os passos"** — o botão só aparece para quem tem a autorização *Manter roteiros de cálculo*.

Em modo de edição cada passo mostra:

| Campo                 | Quando aparece                                                                                                |
| --------------------- | ------------------------------------------------------------------------------------------------------------- |
| **O que o passo faz** | sempre — calcular uma verba, acumular uma base, aplicar tabela oficial ou fechar o holerite                   |
| **Verba**             | ao calcular uma verba; e também ao aplicar tabela oficial, para dizer **em qual verba** o resultado é lançado |
| **Base de cálculo**   | ao acumular uma base                                                                                          |
| **Tabela oficial**    | ao aplicar tabela oficial (INSS, IRRF, salário-família…)                                                      |
| **Condição**          | sempre, e é opcional — a fórmula que decide se o passo roda                                                   |

Os botões da linha **sobem**, **descem** e **removem** o passo; o de baixo acrescenta um passo novo ao fim. Nada é gravado enquanto você não clicar em **"Salvar a ordem"** — e **"Descartar alterações"** devolve tudo ao que estava.

:::BlockQuote
**Salvar envia o conjunto inteiro, não uma linha.** É a ordem que o sistema confere, e conferir uma linha de cada vez deixaria o roteiro, por um instante, numa ordem que ninguém checou.
:::

:::BlockQuote
**Um roteiro sem passo nenhum não calcula nada.** Ele fica registrado e a folha daquele tipo não fecha. A tela avisa antes de salvar.
:::

### Por que o sistema recusa uma ordem

Um passo que lê uma base **antes** do passo que a acumula **não falha**. Ele produz **zero** — e zero numa base se lê como *"essa pessoa não teve esse provento"*. A folha fecha, os holerites saem, e o recolhimento a menos aparece na conciliação anual, quando já ninguém sabe em que competência começou.

Por isso o sistema monta o grafo de dependência entre os passos e **recusa ao salvar**, não ao fechar. A recusa diz **qual passo lê o quê** e **qual passo só acumula depois** — ou que ninguém acumula aquela base, que é outro erro com outro conserto.

:::BlockQuote
**Só passo de acumulação pode nomear uma base de cálculo.** Qualquer outro que carregue uma é recusado, e essa exclusividade não é burocracia: é o que permite ao sistema enxergar as **duas pontas** de toda dependência. Base alcançada por outro caminho seria dependência que nada vê.
:::

:::BlockQuote
**O passo de tabela oficial também lê uma base — a que a própria tabela taxa.** O INSS incide sobre a base do INSS, o IRRF sobre a base do IRRF: isso é característica do tributo, não escolha de quem monta o roteiro, e por isso não há campo para informá-la. A conferência de ordem leva esse passo em conta desde 2026-08-09; até então ela só enxergava o que uma fórmula de condição lesse, e aceitava a tabela do INSS aplicada **antes** da acumulação da base dele. Quem já tivesse salvado um roteiro assim não pagava errado — o cálculo recusava pessoa a pessoa, dizendo que a base não foi acumulada —, mas descobria tarde.
:::

:::BlockQuote
**Passo com condição precisa de fórmula que produza CONDIÇÃO.** Uma que devolve valor leria qualquer número diferente de zero como "sim", e o passo nunca seria pulado.
:::

### Numeração dos passos

Use números espaçados — 10, 20, 30. Inserir um passo entre dois outros não deve renumerar o resto, porque renumerar reescreve linhas que um auditor pode ter citado.

## Declarar o que uma verba compõe

***

Na tela de detalhe da rubrica, o cartão **O que esta verba compõe** lista **todas** as bases em vigor naquela competência. Para cada uma, escolha **Soma**, **Subtrai** ou **Não entra**, e clique em **Salvar**.

:::BlockQuote
**"Não entra" é uma resposta e fica gravado.** "Esta verba não entra na base do FGTS" e "ninguém disse ainda se entra" são fatos diferentes, e só o primeiro é resposta. É por isso que a lista mostra todas as bases, e não apenas as já declaradas: o contador que assina a composição antes do primeiro fechamento precisa enxergar a diferença.
:::

:::BlockQuote
**Isto NÃO substitui os códigos de incidência do eSocial**, e as duas coisas convivem de propósito. Os códigos de incidência são o que se **declara ao Fisco**; este cartão é o que o sistema **calcula**. É legítimo — e comum — uma verba ter código de incidência de INSS e papel "não entra" numa base interna.
:::

:::BlockQuote
**O papel pende da VIGÊNCIA da rubrica, não da rubrica.** Uma verba pode entrar na base do FGTS até certa data e sair depois: é mudança de norma, não rubrica nova. Pendurar na rubrica faria a mudança **reescrever o passado**.
:::

## Dizer a quem o desconto é repassado

***

Na tela de detalhe da rubrica, o cartão **Quem recebe esse dinheiro, e quando** responde a outra metade da pergunta: o holerite desconta, e alguém tem de receber. O INSS retido vai à Previdência, o imposto de renda à Receita, a contribuição sindical ao sindicato, e o FGTS e o patronal são recolhidos pela empresa. Preencha três campos e clique em **Salvar**:

| Campo                    | O que informar                                                                                 |
| ------------------------ | ---------------------------------------------------------------------------------------------- |
| **Pago a**               | O parceiro que recebe. Comece a digitar o nome ou o documento.                                 |
| **Vence no dia**         | O dia do mês **seguinte** à competência. Em branco, vale a data de pagamento da própria folha. |
| **Categoria de despesa** | A linha do plano de contas em que a obrigação entra no financeiro.                             |

:::BlockQuote
**O fechamento da folha RECUSA enquanto isto estiver em branco**, nomeando a rubrica e o valor. Não é rigor de cadastro: o dinheiro já saiu do bolso do colaborador, e emitir o lote sem a obrigação de repassá-lo deixaria dinheiro de terceiro dentro da entidade com **todos os totais batendo** — ninguém perceberia até a guia vencer.
:::

:::BlockQuote
**Cada ausência tem a sua frase, e vale ler qual apareceu.** Falta o credor, falta a categoria da rubrica, falta a categoria do líquido (que se informa na **abertura** da folha, não aqui) e falta a pessoa estar cadastrada como parceiro são quatro consertos em três telas diferentes. As frases saem uma de cada vez, na ordem do conserto mais próximo: resolva a que apareceu e feche de novo.
:::

:::BlockQuote
**O dia 31 é aparado, não recusado.** Quem declara 31 está dizendo "o último dia"; em abril o vencimento sai no dia 30. Recusar faria onze meses funcionarem e um falhar.
:::

:::BlockQuote
**A pensão alimentícia é a exceção, e ela se declara na pessoa.** O beneficiário é nomeado na ordem judicial e é diferente para cada empregado, então a declaração feita no cartão **A quem esta verba se aplica** (logo abaixo) **vence** o que estiver aqui. Duas ordens sobre a mesma rubrica geram **dois** repasses, cada um no nome do seu beneficiário — nunca um só somado.
:::

## Declarar a quem uma verba se aplica

***

Na tela de detalhe da rubrica, o cartão **A quem esta verba se aplica** responde a pergunta que o holerite faz: *esta pessoa recebe isto?*. Escolha o degrau em **Aplica-se a**, informe **Qual**, opcionalmente um **Valor fixo**, a competência em **Em vigor a partir de**, e clique em **Declarar**.

A folha sobe os degraus **do mais estreito para o mais largo** e para no primeiro que responde:

| Degrau         | Alcança              | Uso típico                          |
| -------------- | -------------------- | ----------------------------------- |
| Uma pessoa     | só aquele empregado  | acordo individual, decisão judicial |
| Um cargo       | quem ocupa o cargo   | adicional de função                 |
| Um setor       | quem está lotado ali | insalubridade de uma área           |
| Um sindicato   | a categoria          | piso ou reajuste de convenção       |
| Toda a empresa | todos                | vale-refeição, salário-base         |

:::BlockQuote
**Só o degrau mais largo dispensa o alvo.** Uma declaração de cargo **sem** dizer qual cargo ficaria cadastrada, apareceria na lista e **não alcançaria ninguém** — a tela mostraria a verba configurada e quarenta pessoas não a receberiam. Por isso o sistema recusa. E o inverso também: a declaração para toda a empresa **não** leva alvo, porque levando um ela nunca seria encontrada.
:::

:::BlockQuote
**A verba que ninguém declarou fica AUSENTE do holerite, e não zerada.** Uma linha "R$ 0,00" é uma pergunta que o empregado leva ao RH, não uma resposta. Se uma verba não sai para ninguém, comece conferindo se ela tem alguma declaração aqui.
:::

**Quando o desconto vem de uma decisão judicial**

Abaixo dos campos comuns há um bloco separado com **número do processo**, **vara** e **beneficiário**. Ele é só para desconto que um juiz mandou fazer — pensão alimentícia, retenção judicial. A maioria das verbas não passa por ali, e deixar os três em branco é o normal.

**Preencha os três ou nenhum.** O sistema recusa meia ordem, e cada metade que falta quebra o processo num lugar diferente:

| Falta              | O que acontece se fosse aceito                                                                                                                                                                                                                |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| O **beneficiário** | O desconto sai todo mês e o repasse não tem a quem ir. O lote que paga a folha recusa a linha por falta de destinatário — semanas depois, longe de quem cadastrou. O servidor recebe a menos e quem deveria receber a pensão não recebe nada. |
| O **processo**     | O desconto acontece e ninguém consegue provar por quê. Numa fiscalização, desconto sem a ordem que o autoriza é valor a devolver ao empregado (CLT art. 462).                                                                                 |
| A **vara**         | O processo não pode ser localizado: os números se repetem entre jurisdições, e é o par processo + vara que identifica a ordem.                                                                                                                |

O beneficiário precisa estar **cadastrado como parceiro**, porque é para ele que o título de repasse será emitido. Um beneficiário que não é parceiro geraria um pagamento endereçado a ninguém — e o sistema avisa na hora do cadastro, não na hora de pagar.

:::BlockQuote
**A ordem se declara na PESSOA.** O beneficiário é nomeado no ofício e muda a cada empregado, então a declaração de pensão é sempre no degrau "uma pessoa" — nunca no cargo ou na empresa.
:::

:::BlockQuote
**O degrau que respondeu fica gravado na linha calculada.** Refazer a competência do ano passado depois que a pessoa mudou de setor responderia **outro** degrau: sem o carimbo ninguém saberia qual dos dois foi pago. É o que sustenta uma resposta a reclamação trabalhista.
:::

:::BlockQuote
**Mais de uma lotação principal vigente faz a folha RECUSAR.** Não é rigidez: o valor passaria a depender de qual linha o banco devolvesse primeiro, e nada registraria a escolha. Encerre a lotação sobreposta no cadastro trabalhista e rode de novo.
:::

## Calcular a folha de um mês

***

Em **Folha de pagamento → Cálculo da folha**, clique em **Abrir uma folha**, informe o estabelecimento, a **competência**, a **data de pagamento**, em **Líquido entra em** a categoria de despesa dos salários, e o tipo de folha; clique em **Abrir**. Depois, na linha da folha, clique em **Calcular**.

:::BlockQuote
**Por que o líquido tem uma categoria própria, informada aqui.** Cada desconto leva a sua, declarada na rubrica; o líquido não tem rubrica a quem perguntar — é o que sobra dos proventos depois dos descontos. Ele é perguntado na **abertura** e não no fechamento de propósito: no fechamento você está conferindo, não configurando, e descobrir ali que falta uma linha do plano de contas é o pior momento do processo, com a folha já calculada e todo mundo esperando. Refazer o cálculo (**Recalcular**) leva a categoria adiante — você não a informa duas vezes.
:::

:::BlockQuote
**A data de pagamento não é detalhe administrativo.** É ela que decide qual tabela de imposto de renda se aplica. Uma folha de janeiro paga em fevereiro é retida pela tabela de **fevereiro**, enquanto a contribuição previdenciária dela usa a de **janeiro** — e nas férias o pagamento é **antes** do gozo começar. Competência e data de pagamento são dois campos porque são dois fatos.
:::

:::BlockQuote
**O comando volta na hora; o cálculo continua.** A coluna **Andamento** mostra quantas pessoas já foram processadas. Você pode sair da tela e voltar.
:::

### O que a tela deixa fazer, e por quê

Ao abrir uma folha, o painel começa por uma faixa que diz **em que estado ela está**, oferece a **única ação que faz sentido agora** e mostra a ação recusada **desabilitada, com o motivo escrito ao lado**. Uma folha calculada oferece **Fechar e enviar ao financeiro**; uma folha de teste oferece **Recalcular** e mostra o fechar recusado, porque folha de teste nunca fecha; uma versão que já foi superada por outra mais nova não oferece nem uma coisa nem outra.

:::BlockQuote
**A faixa não adivinha tudo — e é de propósito.** Quatro recusas do fechamento dependem de fatos que a tela não enxerga: a competência já encerrada, a remessa bancária já emitida, os totais que não fecham e uma folha irmã do mesmo bolo calculada e não fechada. Nesses casos o botão é oferecido, o servidor recusa **pelo nome** e a tela mostra a frase dele. Uma faixa que chutasse essas quatro às vezes proibiria o que o servidor permite — e com uma tela não se discute.
:::

:::BlockQuote
**Quem calcula não é necessariamente quem fecha.** Se o fechamento não estiver na sua alçada, a faixa diz isso em vez de oferecer um botão que responderia "acesso negado" no clique.
:::

### A folha de férias

Férias não se pagam junto com o salário do mês, e não é preferência: a lei manda pagar tudo de uma vez **até dois dias antes** de o descanso começar, e o imposto de renda das férias é apurado à parte do salário. São duas folhas no mesmo mês.

Conceda as férias no cadastro da pessoa, abra uma folha do tipo **Férias** para **o mês em que as férias começam** e calcule. O recibo traz as parcelas separadas:

| Linha                              | O que é                                    | Quando aparece           |
| ---------------------------------- | ------------------------------------------ | ------------------------ |
| **Férias**                         | o valor dos dias tirados                   | sempre                   |
| **Terço constitucional de férias** | um terço **das férias**                    | sempre                   |
| **Férias em dobro (CLT art. 137)** | a segunda cópia dos dias fora do prazo     | só quando o prazo passou |
| **Abono pecuniário de férias**     | os dias **vendidos** em vez de descansados | só quando houve venda    |
| **Terço sobre o abono pecuniário** | um terço do abono                          | só quando houve venda    |
| **Adiantamento de férias**         | o valor adiantado, digitado por você       | só quando lançado à mão  |

:::BlockQuote
**O mês que paga é o mês que COMEÇA.** Trinta dias iniciando em 25 de janeiro são pagos **inteiros** na folha de janeiro — não vinte e três dias em janeiro e sete em fevereiro. Se você abrir a folha de férias do mês seguinte, ninguém terá férias começando ali e o sistema recusa pelo nome. É a mesma regra que faz o fracionamento funcionar: cada pedaço entra na folha do mês em que ele começa.
:::

:::BlockQuote
**O terço é um terço DAS FÉRIAS, não do salário.** Quem tira quinze dias recebe metade do terço de quem tira trinta. Um sistema que calculasse sobre o salário pagaria o mesmo terço aos dois — e o recibo fecharia igual, que é o que torna esse erro difícil de enxergar.
:::

:::BlockQuote
**A dobra inclui o terço.** O que a lei manda dobrar é a *remuneração* das férias, e a remuneração tem o terço dentro (Súmula 81 do TST). Por isso a linha da dobra é maior que a das férias daqueles dias, e não igual a ela.
:::

:::BlockQuote
**Quem não tem férias no mês é RECUSADO pelo nome, não pago com zero.** Uma linha de "R$ 0,00" de férias é uma pergunta que o colaborador leva ao RH. E se ninguém do estabelecimento tem férias começando naquele mês, a folha inteira falha — o desfecho certo para uma folha de férias sem ninguém de férias.
:::

:::BlockQuote
**Vender dias é uma escolha da CONCESSÃO, não uma linha à parte.** Ao conceder as férias você informa quantos dias a pessoa vendeu; o sistema paga esses dias pela **mesma base** dos dias descansados — médias incluídas — e acrescenta o terço sobre eles. Quem não vendeu nada **não vê linha nenhuma de abono** no recibo.
:::

:::BlockQuote
**O teto da venda é um terço do que a pessoa TEM DIREITO, e nem sempre são dez dias.** Quem faltou demais tem direito a 24, 18 ou 12 dias (é a escala do art. 130), e aí o teto é 8, 6 ou 4. O sistema recusa acima disso pelo nome. E os dias vendidos **descontam do mesmo saldo** dos descansados: quem tem 30 dias e vende 10 pode descansar 20, não 30.
:::

:::BlockQuote
**O adiantamento de férias é digitado, não calculado.** Ele é um valor negociado, e nenhuma fórmula sabe qual é. Lance-o à mão na folha de férias e ele entra no recibo. Enquanto ninguém lançar, a linha simplesmente não existe.
:::

:::BlockQuote
**Ele NÃO segue a regra do adiantamento do 13º.** O adiantamento do décimo terceiro não sofre desconto na hora — a lei manda cobrar tudo na segunda parcela. Não existe regra igual para férias: adiantar férias antecipa o **dinheiro**, não a cobrança. Por isso o adiantamento de férias entra normalmente nas bases de INSS, IRRF e FGTS.
:::

### O que o fechamento deixa no financeiro

Fechar não é só mudar o estado da folha: é **criar as contas a pagar**. O sistema separa o que foi apurado em três destinos e gera um título para cada um:

| Destino                                                   | Quantos títulos                   | Vencimento                      |
| --------------------------------------------------------- | --------------------------------- | ------------------------------- |
| **Líquido de cada pessoa**                                | um por colaborador, nunca somados | a data de pagamento da folha    |
| **O que foi retido** (INSS, IRRF, sindical, pensão)       | um por rubrica e por credor       | o dia declarado do mês seguinte |
| **O que a empresa deve** (patronal, RAT, FGTS, terceiros) | um por rubrica                    | o dia declarado do mês seguinte |

:::BlockQuote
**O líquido nunca é consolidado em um título só**, e isso não é preferência: um título somado não carrega a conta bancária de cada pessoa, e é dela que a remessa bancária é feita. Um pagamento único ao "pessoal" não vira arquivo de crédito em conta.
:::

:::BlockQuote
**INSS e imposto de renda vão ao mesmo órgão em títulos separados.** São guias diferentes, e um título cobrindo as duas não concilia com nenhuma quando o extrato voltar.
:::

:::BlockQuote
**Se algo estiver sem destino, o fechamento recusa e NADA é criado** — nem os títulos que estavam completos. O lote e as obrigações nascem juntos, na mesma operação: ou os dois existem, ou nenhum. Não há meio-fechamento para desfazer à mão.
:::

### Quem não pôde ser calculado

Se alguém não pôde ser calculado, a folha abre uma lista **Não calculados** com o motivo de cada um — falta o salário, falta a tabela do mês, falta um ingrediente da conta.

:::BlockQuote
**Resolva essa lista antes de fechar.** Uma folha que termina com 699 de 700 e não diz nada é pior que uma folha que não fecha: a pessoa que faltou descobre no dia do pagamento. É por isso que a lista é uma tela e não uma nota de rodapé.
:::

:::BlockQuote
**Ninguém calculado ⇒ a folha fica em FALHOU**, e não em "calculada". Concluída sobre resultado vazio se lê como sucesso em toda tela que a mostra.
:::

### De onde saiu cada número

Clique em qualquer linha do holerite e a folha abre a **memória**: cada ingrediente com o valor que contribuiu e de onde veio — o salário do vínculo, a base acumulada nesta folha, a faixa da tabela oficial e qual **versão** dela pagou.

:::BlockQuote
**Isso é obrigação, não conforto.** A jurisprudência trabalhista anula pagamento feito "englobado", sem discriminação do que o compõe. A memória é o que torna o número contestável por alguém que não estava lá quando ele foi calculado — o perito, o contador, o próprio empregado.
:::

:::BlockQuote
**A linha aponta para a VIGÊNCIA da rubrica, não para a rubrica.** Se a regra mudar por norma no ano que vem, a linha do ano passado continua explicada pelas regras sob as quais foi calculada.
:::

Cada ingrediente sai **como o que ele é**: dinheiro com cifrão e centavos, alíquota em porcentagem, contagem como número inteiro. Quem lê a memória não precisa saber de que espécie é cada termo para entender a linha — descobrir isso é justamente o que a memória existe para poupar.

### O imposto de renda: a tabela e a redução

A linha do imposto de renda tem **duas** etapas, e a memória mostra as duas separadas de propósito:

1. **LEGAL\_TABLE** é o que a tabela progressiva produziu sobre a base tributável. Quem confere pode caminhar as faixas da tabela publicada e tem de chegar exatamente neste número.
2. **TAX\_REDUCTION** é a **redução do imposto** que a Lei nº 15.270/2025 (art. 3º-A da Lei nº 9.250/1995) criou a partir de janeiro de 2026. Ela é subtraída do imposto apurado e **não pode passar dele** — o desconto pode chegar a zero, nunca a valor negativo.

O que é retido é a diferença. Para quem ganha até cinco mil reais no mês a redução costuma zerar o imposto, e é por isso que **LEGAL\_TABLE maior que zero com o desconto em R$ 0,00 está certo** — não é erro de cálculo, é a lei.

:::BlockQuote
**A redução lê o rendimento BRUTO do mês, não a base de cálculo.** O ingrediente TAXABLE\_INCOME mostra qual rendimento foi lido. Duas pessoas com o mesmo bruto e deduções diferentes recebem a **mesma** redução — se os dois números divergirem, é a base que está sendo lida no lugar do rendimento, e aí o imposto sai errado para os dois.
:::

:::BlockQuote
**A redução precisa estar cadastrada em Tabelas oficiais, como espécie IRRF — redução do imposto.** Sem ela a folha calcula assim mesmo, e retém o imposto **cheio** — que é o que a norma mandava antes de 2026. Não há recusa, porque uma competência anterior a 2026 legitimamente não tem essa tabela; se os holerites de 2026 estiverem saindo com imposto maior do que o esperado, é o primeiro lugar a olhar.
:::

### Qual folha você está lendo, e por que ela falhou

Ao abrir uma folha, a faixa logo abaixo do código diz **qual folha está aberta**: a situação, o tipo, a competência, a data de pagamento e a versão — mais o selo **Teste** quando for simulação. Sem ela esses dados ficavam só na linha da grade, que sai de vista assim que o painel abre, e tudo abaixo era lido sem se saber de que mês era.

Se a situação for **Falhou**, aparece a **razão** em vermelho. É a diferença entre "deu erro" e *"nenhuma pessoa pôde ser calculada"* — e a segunda vem com a lista de quem faltou logo abaixo.

### Recalcular e folha de teste

**Recalcular** cria uma **versão nova** e conserva a anterior, consultável e comparável linha a linha. Folha **fechada** recusa recálculo — o caminho é reabrir ou lançar uma complementar.

:::BlockQuote
**Cancelar conserva todos os números.** Nada é apagado: os números de uma folha cancelada são o que o auditor lê para entender por que um pagamento foi desfeito.
:::

:::BlockQuote
**Folha marcada como teste produz os mesmos números e não pode ser fechada.** Ela aparece na mesma lista das reais, com a etiqueta **Teste** e com o código começando em SIM- — porque citar um valor simulado a um empregado é o tipo de erro que acontece uma vez e não se esquece.
:::

### Pagar uma diferença: a folha complementar

Quando o mês já foi pago e faltou pagar alguma coisa — o aumento que entrou tarde, a hora extra que chegou depois do fechamento —, o caminho **não** é reabrir a folha: é abrir uma **folha complementar** da mesma competência, que paga só a diferença.

1. **Folha de Pagamento → Cálculo da folha → Nova folha.** Escolha a **mesma competência** do mês que já foi pago e o tipo **Complementar**. A data de pagamento é a da nova quitação, que normalmente cai no mês seguinte.
2. **Lance a diferença de cada pessoa** em **Lançamentos manuais**, com a rubrica **Diferença salarial** e o valor que falta pagar. Escreva o motivo — ele fica no registro e é o que responde à pergunta "por que essa pessoa recebeu duas vezes em março".
3. **Calcule.** O sistema desconta INSS e imposto de renda sobre a diferença e apura o líquido.
4. **Confira a memória de cálculo** de quem recebeu e **feche**.

:::BlockQuote
**Um mês fechado não impede o lançamento destinado à complementar.** É a única exceção da trava de competência fechada, e ela existe exatamente para isto: a complementar não reescreve o pagamento que já saiu, ela alimenta um pagamento novo. Lançamento para qualquer outro tipo de folha continua sendo recusado.
:::

:::BlockQuote
**Os descontos consideram o que o mês já pagou, e é por isso que eles parecem "altos".** Tanto o INSS quanto o imposto de renda são apurados sobre o **total** recebido na competência, não sobre a diferença isolada — a segunda folha continua a progressão de onde a primeira parou e abate o que já foi retido. Uma diferença de R$ 1.000 paga a quem já recebeu R$ 5.000 no mês **não** é descontada como se aquela pessoa ganhasse mil reais. A memória de cálculo mostra as duas metades da conta: quanto o mês já havia tributado e quanto já havia sido retido.
:::

:::BlockQuote
**Feche a folha normal antes de calcular a complementar.** A complementar precisa enxergar o que a folha do mês pagou, e esse fato passa a existir no **fechamento**. Se você calcular a complementar com a mensal ainda em aberto, o sistema **recusa o fechamento** dela e diz qual folha fechar primeiro — em vez de deixar passar um imposto apurado a menos, que ninguém perceberia depois.
:::

## Consultar o contracheque de uma pessoa

***

**Folha de Pagamento → Contracheques.** É o primeiro item do grupo de propósito: as telas seguintes são a ordem em que uma folha se **monta**, e esta é a que quem atende abre todo dia.

A pergunta que chega ao RH é sempre sobre **a pessoa e o mês** — "o de março veio menor", "eu recebi o décimo terceiro?". Por isso a consulta começa assim: escolha o colaborador, escolha o ano, abra o mês. São dois cliques até o documento.

Três coisas que valem saber antes de responder:

:::BlockQuote
**O seletor de ano só oferece os anos em que aquele vínculo realmente tem contracheque.** Não é uma lista de anos quaisquer. Um ano vazio se leria como "esta pessoa nunca foi paga" — alarmante, e quase sempre apenas o ano errado.
:::

:::BlockQuote
**O mesmo mês pode ter mais de um contracheque.** Uma folha mensal, uma complementar e uma tentativa cancelada aparecem as três sob o mesmo mês, cada uma com a sua **situação** — porque só a situação diz qual foi o dinheiro. Uma folha cancelada guarda os números para consulta, e uma marcada como **Teste** nunca chegou na conta de ninguém; as duas avisam isso em destaque ao abrir.
:::

:::BlockQuote
**Proventos menos descontos nem sempre é o líquido.** Os **encargos da empresa** são custo do empregador e ficam de fora; os **informativos** não entram em total nenhum. Cada um tem o seu bloco dizendo isso, justamente para que ninguém some e abra chamado contra um número correto.
:::

O contracheque abre com o salário bruto e o líquido em destaque, depois **Proventos** e **Descontos** separados, cada bloco com o seu subtotal e as verbas uma a uma, com código e nome.

:::BlockQuote
**Clique numa verba e o sistema mostra de onde saiu o número.** Cada ingrediente do valor, na ordem em que a conta os usou, e a origem de cada um. É o que a Súmula 91 do TST espera que um contracheque consiga reproduzir — e é o que nenhum aplicativo de banco mostra.
:::

### Quanto ainda pode ser comprometido

Abaixo do contracheque aberto, o cartão **Quanto ainda pode ser comprometido** responde a pergunta que chega ao RH antes de toda autorização de empréstimo: *quanto dessa pessoa ainda cabe?*

Nem tudo que sai do holerite conta igual. O INSS, o imposto de renda e uma pensão alimentícia saem porque a lei ou um juiz mandaram — a pessoa não teve o que consentir. Um empréstimo consignado, uma previdência privada ou a contribuição sindical saem porque ela **concordou**. Só o segundo grupo é limitado, e o cartão mostra os dois separados.

| Linha                                       | O que é                                                                   |
| ------------------------------------------- | ------------------------------------------------------------------------- |
| **Remuneração**                             | a soma dos proventos do mês — a base sobre a qual os tetos são calculados |
| **Imposto por lei ou por decisão judicial** | o que não disputa a margem                                                |
| **Acordado pelo colaborador**               | o que disputa                                                             |
| **Teto do que é acordado**                  | 35% da remuneração                                                        |
| **Teto de tudo somado**                     | 70% da remuneração                                                        |
| **Ainda disponível**                        | quanto cabe de novo consignado                                            |

:::BlockQuote
**O obrigatório NÃO come a margem — ele decide quanta margem existe.** Contar o imposto de renda dentro dos 35% encolheria justamente a margem de quem ganha mais, e todo número da tela continuaria batendo.
:::

:::BlockQuote
**O teto de tudo somado pode morder antes do outro, e aí é ele que vale.** Quem já tem 60% do salário tomado por pensão e impostos tem **10%** de espaço, não 35%. É por isso que o cartão mostra os dois tetos: olhar só o primeiro autoriza um empréstimo que a lei proíbe.
:::

:::BlockQuote
**Passou de um teto? O cartão diz por quanto, e diz qual.** Acima dos 35% a frase é sobre o que foi acordado; acima dos 70% ela diz que **nada** mais cabe neste mês, seja qual for o teto da classe. São duas conversas diferentes com a pessoa.
:::

:::BlockQuote
**Desconto que ninguém classificou aparece nomeado, e a margem acima fica incompleta.** O sistema não chuta de que lado ele está: supor obrigatório infla a margem de todo mundo, supor acordado a encolhe, e os dois erros são silenciosos. Classifique a rubrica no cartão **Quem recebe esse dinheiro, e quando**, no campo **Imposto ou acordado**.
:::

:::BlockQuote
**Competência não calculada não é margem zero.** Se o mês ainda não rodou, o cartão diz isso em palavras — porque ler margem cheia de um mês inexistente é autorizar contra uma folha que não existe.
:::

:::BlockQuote
**A suspensão automática ainda não existe.** Quando a margem estoura o sistema **avisa** e não suspende nada sozinho: a lei manda suspender do menos prioritário para cima, e suspender o contrato errado é pior que não suspender. Por enquanto a decisão é de quem lê.
:::

## Lançar o que a pessoa trabalhou no mês

***

**Abra "Ponto e banco de horas"** (/payroll-time-sheet). No menu lateral, em **Recursos humanos → Ponto e banco de horas**.

Até esta tela existir, a folha **não sabia pagar uma hora extra** — não por falta da conta, mas por falta do número: ninguém dizia quantos minutos a pessoa trabalhou. É por isso que as rubricas de hora extra e adicional noturno nascem **desligadas** no catálogo.

1. Escolha a **competência** (AAAA-MM).
2. Escolha o **vínculo** e informe três números: quanto foi **trabalhado**, quanto disso foi **noturno** e quanto disso foi **hora extra**. Você pode escrever 7h20, 7:20 ou 440 — a tela repete embaixo o que entendeu, em horas e minutos, porque 720 e 7h20 são onze horas de diferença.
3. **O motivo** não é observação: é a primeira coisa que um fiscal pergunta.

:::BlockQuote
**Noturno e hora extra são PARTE do trabalhado, não uma soma.** Uma hora extra feita às 23h conta nos dois campos, e por isso a soma dos dois **pode** passar do total — o que o sistema recusa é cada um deles isoladamente maior que o trabalhado, porque aí a folha pagaria adicional sobre hora que ninguém fez, e o holerite fecharia do mesmo jeito.
:::

:::BlockQuote
**A armadilha: vínculo SEM lançamento não é pago como zero.** As linhas que dependem da hora são recusadas **nomeando o termo**, e a recusa aparece na lista de falhas da folha e trava o fechamento — que é o comportamento certo, barulhento. **Lançar zero é outro ato**, e é legítimo: quem ficou afastado o mês inteiro trabalhou zero minuto, e dizer isso não é a mesma coisa que não dizer nada.
:::

:::BlockQuote
**Lançar de novo para o mesmo vínculo e competência CORRIGE o lançamento anterior**, não cria um segundo. O histórico guarda o que mudou, campo a campo.
:::

### O banco de horas

Hora extra pode ser paga ou guardada. Quando a convenção prevê banco, ela vira **crédito**, e o servidor tem um prazo para tirar a folga correspondente. Passado o prazo sem folga, a lei é direta: **paga-se** (CLT art. 59 § 3º).

No cartão **Banco de horas** você faz três coisas:

1. **Levar a hora extra da competência ao banco.** O sistema lê o mesmo lançamento de resultado do período que a folha usaria para pagar a hora — então banco e holerite nunca discordam sobre quantos minutos houve. Uma competência entra **uma vez**; tentar de novo é recusado, porque creditar duas vezes dobraria o saldo e o fechamento pagaria a mesma hora duas vezes.
2. **Ver o saldo.** Escolhido o vínculo, aparecem **três números**: o **saldo**, o que está **fora da janela** (que é o que o fechamento transforma em dinheiro) e o que ainda está **dentro da janela**. Saldo negativo — mais folga tirada do que hora bancada — aparece em vermelho, **é reportado e nunca descontado**: o que a lei manda fazer nesse caso não foi pesquisado, e descontar por suposição tiraria dinheiro do contracheque de alguém.
3. **Fechar o banco**, informando a janela que a sua convenção pratica e a rubrica que paga a hora bancada.

:::BlockQuote
**O banco guarda MINUTOS, nunca dinheiro, e isso é o que protege o servidor.** Quem fez a hora em janeiro ganhando R$ 3.000 e recebe em dezembro ganhando R$ 3.600 recebe **a R$ 3.600** — é o que o art. 59 § 3º manda. Por isso o lançamento que o fechamento gera carrega **horas**, e o valor é calculado pela folha da competência que paga.
:::

:::BlockQuote
**Folga tirada compensa a hora MAIS ANTIGA.** Se consumisse a mais recente, um crédito velho venceria enquanto um novo era gasto no lugar dele — e o fechamento pagaria de novo horas que já tinham sido compensadas.
:::

**A janela é sua, não do sistema.** A lei dá o teto: acordo individual **escrito** compensa em até **seis meses** (art. 59 § 5º) e acordo tácito, **no mesmo mês** (§ 6º). O regime coletivo tem teto próprio, e o sistema **registra** a janela que a sua convenção declara em vez de julgá-la.

O fechamento responde uma coisa por vínculo:

| Resultado                  | O que significa                                                                                                                                                                            |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Pago na folha**          | O que venceu virou lançamento na competência e **saiu** do banco. Fechar de novo não paga outra vez.                                                                                       |
| **Ainda dentro da janela** | Nada venceu; o saldo continua correndo.                                                                                                                                                    |
| **Saldo negativo**         | A pessoa compensou mais do que fez. O sistema **reporta e não desconta** — o que fazer nesse caso depende da sua convenção, e descontar por conta própria tiraria dinheiro de um holerite. |

:::BlockQuote
**Vínculo sem movimento fica de fora, e isso não é saldo zero.** Quem nunca teve hora levada ao banco simplesmente não tem banco — o fechamento não abre um para ele.
:::

### Carregar o arquivo do relógio de ponto

Todo relógio eletrônico é obrigado a produzir um arquivo — o **AFD** — e o empregador é obrigado a guardá-lo: é ele que a fiscalização do trabalho pede. O sistema lê esse arquivo no leiaute oficial (**Portaria MTP nº 671/2021**), então **qualquer relógio homologado serve**, de qualquer fabricante — não há formato próprio nem conversor para manter.

1. Exporte o AFD no relógio ou no software dele.
2. No primeiro cartão da tela, escolha o arquivo e clique em **Importar arquivo**.
3. Leia os **cinco números** que aparecem. Eles não são decoração — cada um tem um dono:

| Número          | O que significa                             | De quem é o assunto                     |
| --------------- | ------------------------------------------- | --------------------------------------- |
| **Lidas**       | marcações que o sistema entendeu no arquivo | —                                       |
| **Importadas**  | marcações novas, gravadas agora             | —                                       |
| **Já tinha**    | marcações que já estavam aqui               | ninguém: é o normal de reexportar o mês |
| **Sem vínculo** | o CPF não é de ninguém cadastrado           | cadastro de pessoal                     |
| **Rejeitadas**  | linhas que o sistema não conseguiu ler      | o relógio                               |

:::BlockQuote
**Carregar o mesmo arquivo duas vezes não faz mal nenhum.** Cada marcação é reconhecida pelo relógio que a gravou e pelo número de sequência dela, então a segunda carga **não grava nada** e conta tudo como *já tinha*. Reexportar o mês inteiro é rotina, e o sistema foi feito esperando isso — sem esse cuidado, a segunda carga dobraria todas as marcações e a folha pagaria o dobro de hora extra sem nada parecer errado.
:::

:::BlockQuote
**Se aparecer “Arquivo incompleto”, baixe de novo antes de fechar o período.** O próprio arquivo declara, no fim, quantas marcações contém — quando essa conta não bate com o que foi lido, o download veio truncado. É o defeito mais comum de puxar arquivo de relógio, e sem esse aviso o mês fecharia com menos horas do que a pessoa trabalhou.
:::

:::BlockQuote
**Marcação sem vínculo não é descartada.** Ela fica guardada; cadastre a pessoa e ela se liga sozinha. Descartar deixaria a importação silenciosamente menor que o arquivo — que é justamente o tipo de coisa que ninguém percebe.
:::

**Depois de importar, confira no espelho.** A importação guarda a marcação como o relógio a gravou; quem transforma isso em horas é o cartão seguinte.

### O espelho do ponto

É o documento que o empregado assina, e é onde a conta aparece. Escolha o **vínculo** e o sistema monta o mês dia a dia: as marcações como o relógio as gravou, quanto foi trabalhado, quanto passou da jornada e quanto caiu na janela noturna.

Três coisas para ler com atenção:

- **A tolerância aparece com o número.** Um dia cujas variações couberam na tolerância legal (cinco minutos por marcação, dez no dia) é marcado como **Tolerância**, com os minutos que ela absorveu ao lado. O número está ali porque um fiscal confere **por quê**, não apenas que sim.
- **Quando a tolerância estoura, conta tudo.** Um dia doze minutos acima da jornada paga **doze** minutos de hora extra, não dois. É a lei, e é o ponto em que quase todo sistema erra: tratar a tolerância como desconto paga a menos e ninguém percebe.
- **Dia marcado como Incompleto é dia em que alguém não bateu a saída.** O sistema **não inventa** o horário que falta — inventar seria criar hora que ninguém fez, ou apagar hora que fez. Ajuste as marcações antes de confirmar o período.

**A apuração PROPÕE; quem confirma é você.** O botão **Usar esta apuração** leva os três totais para o formulário de lançamento logo abaixo, e o lançamento continua sendo o seu ato — que é exatamente o que a fiscalização espera encontrar.

:::BlockQuote
**O turno que vira a noite é UM dia.** Quem entra às 21h e sai às 6h aparece uma vez só, no dia em que começou, com nove horas trabalhadas e sete noturnas. Um sistema que fechasse o dia à meia-noite partiria o turno em dois e metade do adicional noturno sumiria — com o total de horas continuando certo.
:::

:::BlockQuote
**O que ainda não entra na conta:** qual dia é de folga na escala (então um dia trabalhado numa folga é medido contra a jornada comum, e a hora extra dele sai **menor**, nunca maior), o desconto por intervalo suprimido e o banco de horas.
:::

Quem lança é quem administra pessoal; quem roda a folha **não** pode mexer nestas horas, e essa separação é de propósito: são três números que a folha multiplica pelo valor da hora e por um percentual.

### Corrigir o registro de ponto

Logo abaixo do espelho, depois de escolher o vínculo, aparece **Corrigir o registro de ponto** — o lugar onde o dia incompleto que o espelho aponta tem conserto. São duas ações, e nenhuma delas reescreve o que o relógio gravou.

**Desconsiderar a marcação errada.** Informe **por que** ela não deve contar e confirme. A marcação **continua na lista**, riscada, com o motivo ao lado — ela sai da conta, não do registro.

**Lançar a marcação que faltou.** Informe a data e a hora da batida que nunca foi feita e o motivo. Ela entra identificada como **Lançada à mão**, sem NSR.

:::BlockQuote
**Por que a marcação desconsiderada continua aparecendo.** O espelho é o documento que o empregado assina. Um espelho que sumisse com a marcação que alguém decidiu desconsiderar esconderia justamente o ato que ele existe para mostrar — e é esse ato, com o motivo e o autor, que a fiscalização pede. Sair da conta e sair do papel são coisas diferentes.
:::

:::BlockQuote
**Por que a marcação lançada à mão não ganha NSR.** O NSR é o número sequencial que o próprio relógio atribui, e o arquivo que ele produz (o AFD) declara essa sequência contínua. Inventar um número para uma batida digitada corromperia a sequência que torna o arquivo uma prova. Onde apareceria o NSR, aparece **Lançada à mão** — e quem lê nunca confunde as duas.
:::

:::BlockQuote
**Sem motivo o sistema recusa.** Desconsiderar sem dizer por quê é apagar com outro nome, e o motivo é a primeira coisa perguntada numa fiscalização. Vale para as duas ações.
:::

:::BlockQuote
**Depois de declarar o total do período, o sistema recusa a correção.** A ordem é: corrija as marcações, depois declare. Se o total já foi declarado, desfaça a declaração antes — corrigir por baixo dela deixaria dois números divergentes sem nada avisando.
:::

:::BlockQuote
**Duas marcações no mesmo minuto são recusadas.** É a forma de um clique duplicado, não de dois eventos. A janela é o **minuto** e não o segundo, porque o relógio grava ao segundo e quem digita uma correção não sabe qual.
:::

**Toda correção fica na trilha** — quem fez, quando e por quê.

### Fechar o ponto da competência

O espelho acima resolve **uma pessoa por vez**. Num órgão com relógio de ponto instalado, confirmar três números por servidor não é um processo — é a explicação de por que o relógio foi comprado e nunca foi usado. O cartão **Fechar o ponto da competência** faz o mês inteiro de uma vez: pega todo mundo que o relógio registrou, apura a jornada de cada um e grava as horas para a folha.

O que volta **não é "pronto"** — é uma lista dizendo o que aconteceu com cada vínculo, e duas das três respostas são o sistema se recusando a gravar:

| Resultado                    | O que significa                                                                 | O que fazer                                                                              |
| ---------------------------- | ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| **Gravado**                  | A jornada foi apurada e as horas estão registradas para a folha.                | Nada.                                                                                    |
| **Recusado — dia em aberto** | Alguém não bateu a saída em um ou mais dias, e o número deles aparece na linha. | Importe o arquivo com as marcações que faltam, ou acerte pelo espelho, e feche de novo.  |
| **Declaração à mão mantida** | O mês daquela pessoa já tinha sido lançado por alguém.                          | Nada, se estava certo. Para trocar pela apuração do relógio, corrija o lançamento à mão. |

**Pode fechar de novo à vontade.** Fechar duas vezes não duplica nada: reescreve o que o próprio fechamento gravou antes e deixa intacto o que uma pessoa declarou. É por isso que "importar o que faltava e fechar de novo" é o conserto normal, e não um risco.

:::BlockQuote
**Por que um dia sem saída é recusado, e não gravado pela metade.** A tentação é gravar o que já se tem e deixar a pessoa completar depois. Só que saída faltando significa que o total está **a menos** — e uma folha que paga a menos fecha certinho, bate, e ninguém percebe. Recusar aquele vínculo e seguir fechando os outros é o que transforma um erro invisível numa linha na tela.
:::

:::BlockQuote
**Quem não tem marcação nenhuma fica de fora, e isso é diferente de zero.** Servidor cujo relógio ainda não foi instalado não recebe linha nenhuma — e a folha **recusa pelo nome** a linha dele quando uma rubrica pedir as horas, em vez de pagar zero em silêncio. Inventar um zero para todo mundo pagaria nada a quem trabalhou o mês inteiro.
:::

Fechar exige a **mesma permissão de lançar à mão**, de propósito: os dois gravam a hora que alguém recebe, e uma permissão mais fraca no caminho automático deixaria quem não pode mexer nas horas de uma pessoa mexer nas de todas.

## O vale que o financeiro já autorizou

***

Quando alguém recebe um adiantamento e não presta contas no prazo, quem abre a recuperação é o **financeiro**: ele avisa a pessoa, espera o prazo de defesa que a lei exige e só então autoriza o desconto. Todo esse cuidado acontece fora da folha, e é assim que deve ser.

O que a folha faz é **receber**. Em **Financeiro → Descontos em folha**, a ação de entregar manda para a folha todas as recuperações já autorizadas do estabelecimento. Cada uma vira um lançamento no holerite da competência que ela nomeia, com a base legal junto no motivo.

:::BlockQuote
**Você não redigita nada, e é esse o ponto.** O valor sai do financeiro e entra na folha pelo mesmo caminho, sem passar por planilha. Antes disso ele saía como arquivo para alguém digitar de volta — o que fazia sentido quando a folha era de outro fornecedor.
:::

:::BlockQuote
**Entregar duas vezes não desconta duas vezes.** Cada recuperação carrega a marca do lançamento que virou, e a entrega seguinte pula quem já tem. Pode rodar sem medo.
:::

:::BlockQuote
**O que a folha não consegue receber é dito PELO NOME, e continua autorizado.** Uma pessoa que é parceiro mas não colaborador (um fornecedor, por exemplo), uma competência já fechada, uma rubrica que o catálogo não tem — cada caso aparece na resposta com o seu motivo, a recuperação **não** é marcada como entregue, e a próxima entrega a pega quando a causa for resolvida.
:::

:::BlockQuote
**A pessoa precisa estar cadastrada como parceiro E como colaborador, com o mesmo documento.** É por ele que os dois cadastros se encontram. Sem isso a recuperação é recusada dizendo exatamente isso.
:::

:::BlockQuote
**Quem ainda roda a folha em outro sistema continua com o arquivo.** A remessa não saiu do lugar, e a mesma recuperação nunca sai pelos dois caminhos: o que já foi enviado é pulado.
:::

## Lançar à mão o que a regra não explica

***

Em **Folha de Pagamento → Lançamentos manuais** entra o caso que nenhuma regra cobre: um acordo, uma correção retroativa, um desconto combinado. É a porta que impede o padrão que sempre nasce sem ela — a planilha paralela que ninguém audita.

1. Escolha a **competência** (AAAA-MM). A tela trabalha um mês por vez, que é como se trabalha folha.
2. Escolha o **vínculo**, a **rubrica** e a qual **folha** da competência o lançamento se destina — um mês pode ter mensal, adiantamento, décimo terceiro, rescisão e férias, e um lançamento feito para uma delas não pode ser varrido para outra.
3. Informe a **quantidade** *ou* o **valor**, **nunca os dois**. Quem decide qual dos dois é a rubrica: a que calcula por fórmula recebe a quantidade de onde calcular; a que não calcula recebe o valor. O sistema recusa o errado em vez de adivinhar.
4. **O motivo é obrigatório**, e não é observação. É o que o lançamento **é**: valor sem explicação no holerite de alguém é exatamente o que esta tela existe para impedir.
5. Para lançar o mesmo evento para várias pessoas, clique em **Várias pessoas**. Sai **uma linha e uma entrada de trilha por pessoa** — nunca um lançamento em massa sem rastro individual.

### Quanto os meses fechados passaram a dever, depois de um dissídio

O dissídio se assina em maio com efeito de janeiro. O salário muda, e de janeiro a abril todo mundo foi pago a menos. O cartão **Retroativo de reajuste** desta mesma tela responde **quanto** — e por isso fica aqui: é daqui que a diferença apurada vira lançamento.

Informe o **vínculo**, o mês em que o reajuste passa a valer e a **competência corrente**. A tabela traz, mês a mês, três números:

| Coluna          | O que é                                                                                                                                                                                 |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Pago**        | O que aquele mês efetivamente pagou de proventos, lido da folha real. Folha cancelada não conta — ela é uma folha que alguém retirou, e contá-la faria a diferença sair menor do que é. |
| **Recalculado** | O que o mesmo mês pagaria com o salário novo. Enquanto ninguém tiver refeito aquele mês, a coluna diz **"ainda não recalculado"**.                                                      |
| **Devido**      | A diferença. Só entra no total quando é positiva.                                                                                                                                       |

:::BlockQuote
**A competência corrente fica de fora de propósito.** A folha dela já é calculada com o salário novo, então incluí-la pagaria a diferença **duas vezes** — uma como retroativo e outra dentro do próprio mês. É o tipo de erro cujo holerite fecha, bate e nunca é questionado.
:::

:::BlockQuote
**"Ainda não recalculado" não quer dizer "não deve nada".** São coisas diferentes, e o cartão mostra as duas colunas justamente para você não confundir uma com a outra. Um mês que ninguém refez não entra no total.
:::

**Quem refaz os meses é o botão "Recalcular estes meses"**, logo abaixo da tabela. Ele abre **uma simulação por mês** da janela e devolve, numa linha, quantas abriu, quantas já existiam e quantos meses não tinham folha para comparar. Cada simulação **copia a folha que foi paga naquele mês** — mesmo estabelecimento, mesmo tipo, mesma data de pagamento e mesma categoria de despesa. Não é comodidade: o **tipo** garante que um mês de férias seja refeito como férias e não como folha mensal (comparar dois holerites diferentes chamaria de dívida a diferença entre eles), e a **data de pagamento** é o que decide qual tabela de IRRF se aplica — usar a data de hoje tributaria uma diferença de janeiro pela tabela de dezembro.

:::BlockQuote
**Apertar de novo é seguro, e isso foi construído de propósito.** O extrato soma as linhas de **todas** as simulações do mês; se o botão abrisse uma segunda, o mês passaria a dever o dobro. Um mês que já tem simulação é reaproveitado, e a linha de resposta diz quantos foram.
:::

:::BlockQuote
**Mês sem folha fechada não é recalculado — é relatado.** Não há folha para copiar, e adivinhar os parâmetros produziria um recalculado sem contrapartida, que nesta mesma tela se lê como dívida. Esses meses aparecem na contagem de "meses sem folha para comparar".
:::

:::BlockQuote
**As simulações são despachadas e não esperadas.** A resposta chega na hora; os números aparecem na tabela conforme o motor termina cada mês. Se a coluna **Recalculado** ainda estiver vazia, atualize a tela em alguns segundos antes de concluir que algo falhou.
:::

:::BlockQuote
**Só quem executa folha vê o botão.** Ler o extrato e abrir folhas são atos diferentes: o extrato está aberto a quem lê folha, e recalcular exige a permissão de **executar** folha, porque cria folhas de verdade no sistema.
:::

:::BlockQuote
**A diferença não é necessariamente do reajuste — leia-a antes de pagar.** O recálculo é uma folha nova, feita **agora**, com as regras e os cadastros de agora. Se o roteiro mudou, se uma rubrica ganhou vigência nova, se um período aquisitivo foi corrigido ou se o próprio sistema passou a calcular alguma verba de outro jeito desde que aquele mês foi fechado, isso **também** aparece na coluna Devido. Medido em 2026-08-13 num mês de férias sem reajuste nenhum: o pago trazia dobra de R$ 2.500,00 e o recálculo trouxe R$ 3.333,33 — uma diferença de R$ 833,33 que não vinha de dissídio algum. Isso é o método funcionando como projetado (a diferença **é** o recálculo, e não um percentual aplicado sobre o que foi pago), e é por isso que a tabela mostra as três colunas: antes de lançar, confira **quais rubricas** mudaram entre a folha paga e a simulada, abrindo as duas em **Folhas de pagamento**.
:::

:::BlockQuote
**Diferença negativa aparece e não é paga.** Se o recálculo der menos que o pago — uma correção para baixo, um reajuste aplicado ao grupo errado, um mês que teve um pagamento avulso —, o número aparece em cinza e fica fora da soma. Esconder seria apagar o sinal de que alguma declaração está errada; descontar seria tirar dinheiro de alguém por um mês já encerrado.
:::

**O cartão é um extrato, não um pagamento.** Ele diz o valor; quem paga é o formulário de lançamento acima, na competência corrente — que é onde os impostos sobre essa diferença são calculados. Essa separação é a mesma que o eSocial usa: o retroativo é declarado no mês do acordo, e os meses passados **não** são retificados.

### A comissão que o faturamento já calculou

O cartão **Comissão de venda**, no fim desta mesma tela, apura o que cada vendedor ganhou no mês a partir das **notas fiscais autorizadas** — e fica aqui pela mesma razão do retroativo: é daqui que o valor apurado vira lançamento.

**Primeiro, quem ganha o quê.** Uma regra por vendedor:

| Campo                     | O que decide                                                                                                                                  |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| **Vendedor**              | De quem é a regra. É o parceiro que aparece no pedido de venda.                                                                               |
| **Vínculo em que é paga** | Onde a comissão entra na folha. **Deixe vazio** quando o vendedor não recebe pela folha — um representante comercial pago por contas a pagar. |
| **Percentual**            | Digite em **por cento**: 3 é três por cento.                                                                                                  |
| **Ganha**                 | **Na emissão da nota** ou **na baixa do título**.                                                                                             |
| **Base**                  | **Bruto, com impostos** ou **líquido de impostos**.                                                                                           |
| **Vale a partir de**      | A competência em que a regra passa a valer.                                                                                                   |

:::BlockQuote
**"Ganha" e "Base" mudam o dinheiro no bolso da pessoa, e por isso o sistema não escolhe por você.** Comissionar **na emissão** paga o vendedor por uma venda que o cliente pode nunca pagar; **na baixa** atrasa o vendedor, mas só paga o que entrou. E numa nota de 10.000 com 1.800 de imposto, a três por cento, a comissão é **300,00** com os impostos na base e **246,00** sem eles. São cinquenta e quatro reais de diferença numa nota só, e as duas respostas são legítimas.
:::

:::BlockQuote
**Vínculo vazio não é cadastro pela metade — é a resposta.** Nem todo vendedor é empregado. Se o sistema adivinhasse o vínculo pelo CPF, criaria lançamento de folha para quem não tem contrato de trabalho. Com o campo vazio, as vendas dele aparecem na apuração marcadas como *"não recebe pela folha"* — em vez de sumirem.
:::

**Depois, o mês.** Clique em **Apurar** e o cartão traz duas listas. A de cima é o que cada vendedor ganhou: quantas vendas, a base e a comissão. A de baixo é **o que não rendeu nada, com o motivo**:

| Motivo                                                 | O que aconteceu                                                    |
| ------------------------------------------------------ | ------------------------------------------------------------------ |
| **O vendedor não tem regra de comissão**               | Alguém vendeu e ninguém declarou quanto ele ganha.                 |
| **A regra paga na baixa e o título não foi recebido**  | A venda volta a concorrer no mês em que o dinheiro entrar.         |
| **A regra não nomeia vínculo — não recebe pela folha** | É o caso do representante: a comissão dele sai por contas a pagar. |

:::BlockQuote
**Essa segunda lista existe justamente para não haver silêncio.** Um mês inteiro de vendas rendendo zero, sem nada aparecer na tela, é o defeito que ninguém abre chamado — o vendedor descobre no contracheque.
:::

**Por fim, o lançamento.** Escolha a **rubrica que paga a comissão** e clique em **Lançar na folha**. Sai **um** lançamento por vendedor, com o valor arredondado **uma vez** sobre a base do mês inteiro.

:::BlockQuote
**A rubrica não é escolhida pelo sistema, e isso é deliberado.** Qual rubrica paga uma comissão decide as incidências de INSS e IRRF sobre aquele valor. Escolher por você seria decidir o imposto de alguém a partir de uma suposição.
:::

:::BlockQuote
**A rubrica tem de aceitar VALOR, não quantidade.** A comissão é um valor apurado em reais, então uma rubrica calculada por fórmula — adicional de periculosidade, insalubridade, e boa parte do catálogo CLT — é recusada com a mensagem *"Esta rubrica calcula por fórmula — informe a quantidade, não o valor"*. Não é defeito: é a mesma trava que impede um lançamento manual de contradizer a fórmula da rubrica. Escolha (ou cadastre) uma rubrica de comissão que receba valor.
:::

:::BlockQuote
**Nota cancelada não é venda.** Ela não aparece nem como ganho nem como perdido — porque não é uma venda que deixou de pagar comissão, é uma venda que não existe. Recebimento **parcial** também não conta como recebido: metade do dinheiro entrando não faz a venda cobrada.
:::

:::BlockQuote
**Percentual mudou?** Vale a declaração **mais recente** que já estava em vigor na competência. A anterior fica no histórico — mês já pago não é recalculado a uma taxa que ninguém acordava então.
:::

## Entra uma vez

***

Enquanto o lançamento **aguarda uma folha**, só pode existir um para o mesmo vínculo, rubrica, competência e tipo de folha. Depois que uma folha o **leva**, a linha registra **qual** foi — e a partir daí ele não pode mais ser editado nem cancelado, porque já é linha paga.

**Errou o valor? Corrija, não cancele.** Clique no **lápis** na linha — ele fica ao lado da lixeira. O formulário do topo se preenche, o título passa a **Editar** e logo abaixo aparece **qual** linha está sendo corrigida: matrícula, pessoa, verba e competência. Ajuste o que estiver errado e clique em **Salvar alterações**. O resultado é **uma** linha na competência com o valor certo — e o conferente da folha vê um lançamento onde houve um erro de digitação, não dois.

**Cancelar não apaga**, e continua existindo para quem realmente quer retirar o lançamento. A linha fica como cancelada e sai da regra de unicidade, para que o lançamento que a substitui possa ser gravado e o original continue legível. Lançamento retirado é fato que alguém pergunta depois.

**Competência fechada é recusada** — com **uma** exceção, e ela é a razão de a folha complementar existir: lançamento destinado à **folha complementar** não é barrado por um mês já fechado, porque ele não reescreve nada do que foi pago; alimenta uma folha nova. Mensal, décimo terceiro, férias e rescisão continuam recusados. Competência sobre a qual ninguém informou o sistema é permitida — e a trilha registra que a situação de fechamento era desconhecida, para que ninguém conclua depois que alguém conferiu.

## Equipamentos de proteção e a ficha de entrega

***

Em **Folha de pagamento → Equipamentos de proteção**. A NR-6 obriga o empregador a fornecer equipamento **aprovado**, gratuitamente, e a **registrar** cada entrega — e a própria norma (item 6.5.1, alínea *d*) aceita "livros, fichas **ou sistema eletrônico**". Esta tela **é** esse registro: não é apoio a um papel que alguém arquiva.

### Cadastrar o equipamento

Informe **código**, **nome** e, quando houver, o **Certificado de Aprovação (CA)** com a data até a qual ele vale. Opcionalmente, fabricante, o prazo de troca em dias e se o item exige treinamento.

:::BlockQuote
**O certificado é do MODELO, não da peça.** Ele vence no calendário dele, e é por isso que mora no cadastro do equipamento e não em cada entrega. Item sem certificação legítima fica com o campo vazio; o que o sistema **recusa** é número de CA sem data de validade — sem ela, ninguém sabe a partir de que dia a entrega passa a ser irregular.
:::

### Registrar a entrega

Escolha o colaborador, o equipamento, a data, a quantidade e **por que** o equipamento mudou de mãos: primeira entrega, troca por prazo, danificado, extraviado ou devolução.

:::BlockQuote
**O motivo é declarado, nunca deduzido.** A NR-6 (item 6.5.1, alínea *g*) separa "substituir imediatamente quando danificado ou extraviado" da troca por prazo — o primeiro diz algo sobre o local de trabalho, o segundo diz apenas que o tempo passou, e numa fiscalização os dois se leem diferente.
:::

:::BlockQuote
**A ficha é do VÍNCULO.** Quem tem dois contratos no grupo tem duas fichas: o equipamento é fornecido por um empregador, e a ficha que o fiscal lê é a dele.
:::

### O certificado vencido barra a entrega

Uma faixa no topo lista os certificados **vencidos ou a vencer em 30 dias**. E se alguém tentar registrar uma entrega com data posterior ao vencimento, **o sistema recusa** — nomeando o equipamento, o certificado, o dia em que venceu e o caminho: renovar o certificado, ou cadastrar o modelo recertificado.

:::BlockQuote
**Por que recusar em vez de apenas avisar.** Uma luva inteira, entregue no dia seguinte ao vencimento do CA dela, é uma entrega irregular. Um controle que aceitasse esse lançamento seria um lugar de escrever bonito a própria não-conformidade — e o registro é justamente o que o empregador apresenta quando alguém se acidenta.
:::

**A devolução continua permitida** mesmo com o certificado vencido ou o item fora de uso: é assim que o equipamento deixa o prédio.

### Nada se apaga

Lançamento errado se **cancela com motivo** — e o motivo é obrigatório, porque cancelamento sem motivo é apagar com outro nome. Equipamento que já foi entregue a alguém não pode ser excluído: as entregas que o citam são prova, e o caminho é **tirá-lo de uso**. Esses registros são guardados por décadas porque é deles que se depende numa ação sobre acidente.

## Plano de saúde: quem está coberto, o consentimento e a coparticipação

***

Em **Folha de pagamento → Planos de saúde**. O desconto que aparece no holerite é a **soma** de duas metades que quase ninguém vê juntas: as **mensalidades de cada vida coberta** — a parte previsível — e as **cobranças de coparticipação do mês** — a parte que surpreende. É por isso que as duas moram nesta tela, uma embaixo da outra.

### Cadastrar o plano

Informe **código**, **nome** e o **tipo de contratação**.

:::BlockQuote
**O tipo não é enfeite, e o erro dele é invisível.** Coletivo empresarial e plano contratado pelo próprio trabalhador descontam **exatamente o mesmo valor** — eles só escolhem o código declarado ao eSocial (9219 e 9912). Plano cadastrado no tipo errado sai **certo** no holerite para o empregado, para o analista e para a conferência, e sai errado só no arquivo que o governo lê meses depois, onde consertar custa caro. Por isso **não existe valor pré-selecionado**: um padrão aqui seria o sistema chutando sobre um contrato que ninguém mostrou a ele.
:::

### A autorização assinada

Escolha o plano, a **data da assinatura** e **onde o papel está**.

:::BlockQuote
**Sem consentimento assinado não há desconto.** O art. 462 da CLT proíbe descontar do salário; a Súmula 342 do TST é o que torna o plano de saúde uma exceção — e só quando o trabalhador autorizou **por escrito**. O que a fiscalização pede é o **documento**, então o que o sistema guarda é a data e a referência do papel, não o visto de alguém numa tela.
:::

:::BlockQuote
**Ver que falta é o ponto desta lista.** Sem ela, a recusa só aparece **quando a folha roda** — no dia em que ninguém tem folga para correr atrás de assinatura. Aqui ela aparece semanas antes, como "nenhum consentimento registrado para este vínculo".
:::

:::BlockQuote
**Revogação é data, não exclusão.** Consentimento revogado em setembro **não** torna ilegal o desconto de agosto, e a linha revogada continua na lista justamente por isso: a pergunta é sempre sobre uma competência, não sobre hoje.
:::

### As vidas cobertas

Cada vida — o titular e cada dependente — entra com a **mensalidade** e o dia em que a cobertura começou.

:::BlockQuote
**O desconto é a SOMA das vidas.** Titular com dois dependentes paga **três** mensalidades numa linha só do holerite. Quem procura a diferença numa mensalidade isolada não acha.
:::

:::BlockQuote
**Encerrar cobertura é data, nunca apagar.** A vida que deixou de ser coberta em março **foi** cobrada em fevereiro, e competência fechada precisa continuar explicável. Entrada e saída no meio do mês são cobradas **proporcionalmente aos dias**.
:::

### As cobranças de coparticipação

Cada uso do plano cobrado do trabalhador: a data, o valor e o que foi usado. Marque **internação**, **saúde mental** e **cobrado como percentual** quando for o caso — esses três campos são o que a norma lê.

:::BlockQuote
**Duas recusas, e as duas acontecem na hora de lançar.** A primeira: percentual sobre **internação** é proibido (Resolução CONSU 8/1998), com a saúde mental como exceção expressa — por isso a recusa exige as três condições juntas, e uma regra que olhasse só "internação" barraria uma cobrança psiquiátrica legítima. A segunda: as cobranças do mês **não podem passar a mensalidade daquela vida** (STJ, 2024) — e o teto é **por vida**, não por vínculo, senão uma família grande teria cobrança legítima recusada e uma pequena teria cobrança ilegal aceita.
:::

:::BlockQuote
**Por que recusar no lançamento e não no cálculo da folha.** Quando a folha roda, alguém já cobrou o trabalhador e o dinheiro está em disputa: recusar ali produz um holerite que não fecha e uma discussão que ninguém resolve. Recusar na porta produz uma cobrança que **nunca foi aceita** — que é o estado sobre o qual a organização consegue agir.
:::

:::BlockQuote
**E por que o sistema não "apara" o excesso em silêncio.** Aparar esconderia o fato que a recusa existe para dizer: alguém cobrou mais do que a norma permite. O empregado veria uma linha menor e nunca saberia; e a organização, que responde por ter descontado, não teria registro de que aconteceu.
:::

### Quem vê a lista de cobranças

As cobranças ficam atrás de uma **permissão própria**, separada da que administra o plano. Saber que alguém **está coberto** é um fato; saber **o que a pessoa usou** — consulta, internação, saúde mental, inclusive de dependentes — é outro. Quem administra o cadastro não recebe o segundo junto com o primeiro, e a recusa vem do servidor: a lista não aparece nem em exportação, nem no histórico de alterações.

## Pagar quem não é empregado: o recibo de autônomo (RPA)

***

A prefeitura contrata um eletricista autônomo para um serviço pontual. Não há vínculo, não há férias, não há décimo terceiro — mas **há retenção**, e ela não é a mesma da folha.

**Abra "Recibo de autônomo (RPA)"** (/service-receipts). No menu lateral, em **Folha de pagamento → Recibo de autônomo (RPA)**. A tela emite o recibo já com as contas feitas.

Informe o **estabelecimento** e a **competência**, escolha o **prestador**, a **data do serviço**, o que foi feito e o **valor bruto**. Depois, um campo que o sistema **não preenche por você**.

### O campo que decide o dinheiro é sobre a SUA organização, não sobre o prestador

**"O que esta organização é"** decide a alíquota da previdência do prestador:

| Escolha                                 | Retenção do prestador | Quando                                                                                                   |
| --------------------------------------- | --------------------- | -------------------------------------------------------------------------------------------------------- |
| **Deve a contribuição patronal de 20%** | **11%**               | O caso comum de um órgão público ou de uma empresa.                                                      |
| **Não deve a patronal**                 | **20%**               | Quem paga é pessoa física, cooperativa de trabalho ou entidade isenta — não há patronal de onde deduzir. |

:::BlockQuote
**Não há padrão, e isso é de propósito.** Chutar 11% recolhe **a menos** em todos os casos da segunda linha; chutar 20% recolhe **a mais** na primeira. Nenhum dos dois erros aparece no recibo: ele imprime, os totais somam, e a diferença chega como autuação anos depois.
:::

:::BlockQuote
**Não some 45% em cima dos 11%.** Quem lê o art. 30, § 4º isolado é convidado a isso, mas os 11% **já são** os 20% menos o teto de 9% — a mesma regra dita duas vezes. Aplicar as duas dá 2%, e 2% num recibo parece só um valor baixo. O sistema não faz isso, e este parágrafo existe para que ninguém "corrija" o cálculo achando que faltava.
:::

:::BlockQuote
**O teto vale para um lado só.** A retenção do prestador para no teto do salário de contribuição; a contribuição de 20% da organização **não para**. São duas bases sobre o mesmo pagamento.
:::

### O imposto de renda é do MÊS, não do recibo

Dois pagamentos de R$ 2.000,00 ao mesmo prestador em agosto **não são dois pagamentos isentos**: são R$ 4.000,00 com imposto devido, e ele aparece **no segundo recibo**.

:::BlockQuote
**Por isso a coluna do imposto às vezes mostra uma base MAIOR que o bruto daquele recibo.** Não é erro de conta: é o mês inteiro. A tela escreve *"sobre X acumulados no mês"* justamente para o leitor não corrigir o que está certo.
:::

:::BlockQuote
**O terceiro recibo retém só a diferença.** O que já foi retido no mês é abatido; ninguém paga o imposto duas vezes.
:::

### O ISS é digitado, e o sistema não o calcula

Não existe regra nacional de retenção de ISS: quem manda é a **lei do município**, e a lei complementar nomeia responsáveis por **tipo de serviço**, nunca pela inscrição do prestador. Um sistema que calculasse o ISS estaria inventando a lei de uma cidade que ninguém lhe mostrou. Por isso a tela pede o **valor** e o **município** (código IBGE), guarda os dois como você informou, e registra quem informou.

### O que o sistema recusa

:::BlockQuote
**Prestador com vínculo de emprego vigente na data do serviço: bloqueio, não aviso.** Serviço prestado sob vínculo é **não-incidência**, e o RPA usado para mascarar vínculo é o risco jurídico mais caro deste módulo. Um aviso seria dispensado por quem está com pressa, e o recibo que ele deixasse passar é o documento que uma reclamação trabalhista lê de volta para a organização.
:::

:::BlockQuote
**Mas quem SAIU pode voltar como prestador.** O bloqueio mede o vínculo **na data do serviço**: alguém desligado no ano passado pode legitimamente ser pago como autônomo hoje.
:::

:::BlockQuote
**Falta de tabela legal recusa nomeando qual.** Sem o teto do salário de contribuição ou sem a tabela do imposto de renda da competência, o sistema diz **qual** publicar — e não um genérico "não foi possível calcular", que manda você abrir chamado.
:::

### O que a tela mostra e o que ela não desconta

A coluna **Custo da organização** traz a contribuição de 20% que a organização paga por cima. Ela **não** é descontada do líquido do prestador, porque não sai do bolso dele — mas está na tela porque sem ela o pagamento parece custar um quinto menos do que custa.

Cada recibo tem **Histórico**: quem emitiu, para quem, de quanto e sob qual natureza de tomador — o campo que decidiu 11% ou 20%.

:::BlockQuote
**Ler e emitir são permissões diferentes.** O contador e o auditor leem recibos que não podem emitir; quem executa a folha não emite recibo de autônomo.
:::


[title] Sprints e relatórios de sprint (Scrum)
[path] Aplicações/Agility/Sprints e cronograma/

:::BlockQuote
Planeje uma Sprint Scrum, registre sua meta e capacidade, comprometa itens do Team Backlog, acompanhe o Sprint ativo e consulte Burndown, Velocity e o Sprint Report.
:::

:::hint{type="info"}
**Pré-requisito:**

O Projeto precisa usar a forma de trabalho Scrum, ter um Board principal e ter um Time associado. No roteiro, usamos o Projeto Portal do Cidadão, do Workspace Portal de Serviços.
:::

***

Uma Sprint é o ciclo de execução do Scrum: ela reúne um compromisso de trabalho, uma meta e um período. No Agility, a entrada Planejar Sprint mostra a Sprint corrente em planejamento e também a capacidade registrada para cada membro do Time. O planejamento não é uma estimativa automática pelo tamanho do Time: a capacidade é informada explicitamente por pessoa.

O fluxo conecta o Team Backlog ao Board. Os itens selecionados no planejamento entram no compromisso; quando a Sprint começa, o Board passa a mostrar somente os itens comprometidos e o cabeçalho mantém visíveis a meta, o período, os pontos comprometidos, os pontos concluídos e o progresso. Ao encerrar, os itens concluídos ficam registrados na Sprint e os demais retornam ao Team Backlog; uma nova Sprint é aberta em planejamento.

Os Relatórios de Sprint permitem selecionar qualquer Sprint listada e analisar três perspectivas: Burndown (pontos restantes por dia, ideal versus real), Velocity (pontos concluídos nas Sprints encerradas) e Sprint Report (comprometido, concluído e transbordado). O relatório detalhado só fica disponível depois que a Sprint é encerrada.

***

### Passo a passo

::::WorkflowBlock
:::WorkflowBlockItem
**Abrir o planejamento Scrum**

Abra o Projeto Portal do Cidadão e clique em "Planejar Sprint". A tela carrega a Sprint em planejamento — no ambiente de demonstração, "Sprint 26" — com seu período (10 de ago. a 21 de ago.), a meta já registrada e os cartões de Capacidade, Planejado, Disponível e Período. O menu "Sprint ativo" é a tela de execução que será usada depois do início.
:::

:::WorkflowBlockItem
**Conferir a meta e o período**

Leia o campo "Meta da Sprint" antes de selecionar trabalho. A meta é um texto livre que orienta o compromisso; no exemplo, ela descreve concluir a recuperação de acesso e a auditoria de consentimento. O período é exibido no cartão de métricas e é definido pela Sprint, não por cada item individual.
:::

:::WorkflowBlockItem
**Registrar capacidade por membro**

No quadro "Meta e capacidade da Sprint", confira o Time e os campos numéricos de cada membro. Cada campo aceita a capacidade em pontos e limita o valor entre 0 e 100. Ajuste os valores para representar a disponibilidade real (férias, outras demandas ou dedicação parcial) e clique em "Salvar"; o Agility informa que a meta e a capacidade foram salvas para a revisão do plano.
:::

:::WorkflowBlockItem
**Escolher itens do Team Backlog**

No cartão "Team Backlog", marque as caixas dos itens que o Time pretende assumir. Cada linha mostra a chave, o título e os pontos; no exemplo, estavam disponíveis CID-142 (SSO do cidadão, 13 pts), CID-151 (Recuperar acesso, 8 pts) e CID-158 (Auditar consentimento, 5 pts). A seleção atual aparece com a quantidade de itens e a soma de pontos.
:::

:::WorkflowBlockItem
**Adicionar e revisar o compromisso**

Clique em "Adicionar à Sprint". Os itens escolhidos saem do Team Backlog e aparecem no cartão "Compromisso"; o cartão também atualiza Planejado e Disponível. No roteiro, CID-151 e CID-158 passaram para o compromisso, totalizando 13 pontos, enquanto CID-142 permaneceu no Team Backlog. Para desfazer uma escolha antes do início, marque-a no compromisso e use "Remover da Sprint".
:::

:::WorkflowBlockItem
**Revisar sobrecarga antes de iniciar**

Clique em "Revisar plano". A revisão mostra a meta, o número de itens, o compromisso em pontos e a capacidade total, além de um indicador "Dentro da capacidade" ou "Sobrecarga". Se houver sobrecarga, remova itens ou ajuste as disponibilidades; o botão de início fica bloqueado enquanto o compromisso exceder a capacidade. A revisão também lembra que PI/ART não participa deste cálculo Scrum.
:::

:::WorkflowBlockItem
**Iniciar a Sprint**

Com uma meta preenchida, ao menos um item comprometido e capacidade suficiente, clique em "Iniciar Sprint" e aguarde a confirmação. O status muda de Planejamento para Ativa e a execução passa a estar disponível no menu "Sprint ativo". Se o servidor informar que o Sprint ou item mudou, recarregue o planejamento para buscar a versão atual antes de tentar novamente; essa proteção evita iniciar com dados desatualizados.
:::

:::WorkflowBlockItem
**Trabalhar no Sprint ativo**

Abra "Sprint ativo". O cabeçalho exibe a meta, o período, o progresso percentual, a métrica de concluído e os pontos no formato concluído/comprometido. Abaixo fica o mesmo Board com lanes e drag-and-drop; somente os itens comprometidos estão visíveis. Mova os cartões pelas lanes e abra seus detalhes normalmente. Depois de cada movimento, o cabeçalho é atualizado para refletir os pontos concluídos no servidor.
:::

:::WorkflowBlockItem
**Encerrar a Sprint**

Quando o período ou o trabalho terminar, clique em "Encerrar Sprint". O diálogo lista quantos itens não concluídos voltarão ao Team Backlog e explica que os itens concluídos permanecem registrados na Sprint. Confirme em "Confirmar encerramento"; depois da operação, a tela informa que a Sprint foi encerrada, mostra a nova Sprint já em planejamento e oferece o retorno ao planejamento.
:::

:::WorkflowBlockItem
**Abrir os Relatórios de Sprint**

Clique em "Relatórios de Sprint" e use o seletor "Sprint" para escolher uma Sprint. O seletor identifica cada item por nome e status (Ativa, Encerrada, Planejamento ou Cancelada) e o cabeçalho também mostra período e meta. O relatório sempre carrega o Burndown da Sprint selecionada e o painel de Velocity agregado do Projeto.
:::

:::WorkflowBlockItem
**Interpretar Burndown e Velocity**

No cartão "Burndown", compare a linha Ideal com a linha Real de pontos restantes por dia; a linha real para no último dia que tem dado. No cartão "Velocity", leia os pontos concluídos nas últimas Sprints encerradas — o texto informa quantas Sprints formam o histórico. Se ainda não houver Sprint encerrada, o painel informa que não há histórico de Velocity, sem fabricar uma média.
:::

:::WorkflowBlockItem
**Ler o Sprint Report**

Para uma Sprint encerrada, o cartão "Sprint Report" apresenta três números: Comprometido, Concluído e Transbordado. Quando houver transbordo, a tabela detalha item, pontos e destino (Team Backlog ou outra Sprint); quando não houver, informa que tudo que foi comprometido foi concluído. Para uma Sprint ainda ativa ou em planejamento, o cartão avisa que o relatório detalhado ficará disponível depois do encerramento.
:::
::::

![](https://itsm-labdev.cloud4biz.com/agility-v2/docs/screens/04-sprint-planning.webp "Planejamento da Sprint 26 com meta, capacidade de 52 pontos, compromisso de 13 pontos e os itens Recuperar acesso e Auditar consentimento")

:::hint{type="success"}
:FontAwesome[]{icon="fa-solid fa-check"} **Verificação**

- A tela de planejamento mostra uma Sprint, seu período, uma meta e a capacidade de cada membro do Time.
- Depois de adicionar itens, Planejado corresponde à soma dos pontos comprometidos e Disponível é recalculado.
- A revisão do plano sinaliza Dentro da capacidade e habilita Iniciar Sprint somente com meta e compromisso válidos.
- No Sprint ativo, o Board mostra os itens comprometidos e o progresso do cabeçalho acompanha os movimentos de lane.
- Ao encerrar, itens concluídos permanecem na Sprint, itens não concluídos retornam ao Team Backlog e uma nova Sprint aparece em planejamento.
- Relatórios exibem Burndown para a Sprint selecionada; Velocity usa somente Sprints encerradas e Sprint Report detalha comprometido, concluído e transbordado.
:::

:::hint{type="warning"}
****:FontAwesome[****]{icon="fa-solid fa-triangle-exclamation"}**&#x20;Erros comuns**

**O compromisso está em sobrecarga**

A revisão mostra "Sobrecarga" e o botão Iniciar Sprint fica desabilitado quando os pontos comprometidos excedem a capacidade registrada. Remova itens do compromisso ou corrija a capacidade dos membros e salve o plano antes de revisar novamente.

**O Sprint ou item mudou e não aceita esta operação**

Essa mensagem aparece quando outra atualização alterou o Sprint entre a leitura e o clique. Recarregue a tela Planejar Sprint, confirme a meta e o compromisso que vieram do servidor e repita a operação sobre a versão mais recente.

**O Sprint Report ainda não está disponível**

O relatório detalhado é calculado somente para status Encerrada. Use Burndown durante a execução e encerre a Sprint antes de consultar Comprometido × Concluído × Transbordado.
:::


[title] Portal do colaborador (autoatendimento)
[path] Aplicações/ERP/Manual do Usuário/

:::BlockQuote
Pré-requisitos: [Cadastro trabalhista (contrato de trabalho)](docId\:LxePSOpck0CqjzlijWZj3), porque quem **dá** o acesso é o RH, pelo convite emitido na ficha do colaborador; e o bloco **Empregados** de [Administração](docId\:Z8SS7r6Bvhs09rP1SPxUD), porque quem entra precisa estar ligado a um cadastro de empregado.
:::

## Introdução

Esta página é a única do manual escrita **para o colaborador**, e não para quem opera o RH. São as portas pelas quais a pessoa resolve sozinha o que diz respeito a ela mesma: **pegar o próprio contracheque**, **ler os comunicados** que o órgão publicou, **mandar uma sugestão**, **pedir as próprias férias** e **ver o próprio ponto do mês, pedindo correção do que estiver errado**. Todas ficam no menu **Recursos humanos**, e todas mostram apenas os dados de quem está logado — a pessoa vem da sessão, nenhuma delas pede que você diga quem é.

O que isso evita vale ser dito, porque é o motivo de o autoatendimento existir. Sem ele, o empregado pede o holerite ao RH, e o RH **exporta o documento de uma pessoa** — que é exatamente o ato que o encarregado de proteção de dados filtra na trilha. Toda segunda-feira de pagamento vira uma fila de pedidos e uma fileira de exportações individuais, cada uma indistinguível, na trilha, de alguém tirando cópia do contracheque alheio. Com o portal, o documento é retirado por quem ele pertence, e a exportação continua registrada — só que agora com o nome certo em cima.

As mesmas telas são **reproduzidas pelo portal externo** que a equipe de fora constrói sobre o SDK de integração: as duas pontas leem o mesmo dado. Elas existem **dentro** do ERP por um motivo prático — sem elas, ninguém consegue conferir que o comunicado chegou, que o holerite abre e que o pedido de férias entrou na fila antes de o portal externo ficar pronto.

***

## Passo a passo

### Meus contracheques: o colaborador pega o próprio holerite

O menu **RH → Meus contracheques** (/my-payslips) é a área do **próprio colaborador** — não do RH. Quem entra vê os contracheques dele, escolhe o ano e baixa o PDF, sem pedir nada a ninguém.

1. **Abra o menu e escolha o ano.** A tela já abre no ano mais recente que tenha contracheque fechado.
2. **Clique em "Baixar o PDF"** na competência que você quer.

:::BlockQuote
**Vínculo encerrado continua na lista, e de propósito.** Quem foi desligado em março ainda precisa dos holerites de janeiro e fevereiro. Uma lista que mostrasse só vínculos ativos responderia "você não tem nenhum" justamente a quem mais precisa.
:::

:::BlockQuote
**Cada download entra na trilha de auditoria como EXPORTAÇÃO — inclusive o seu.** Não é desconfiança: tirar cópia do contracheque de um indivíduo do sistema é exatamente o ato que o encarregado de proteção de dados filtra. Tratar o autoatendimento como ato menor faria da única exportação sempre legítima a única invisível.
:::

**A armadilha: ano vazio quer dizer nada FECHADO, não nada perdido**

Só aparecem competências com cálculo **fechado**. Um ano que aparece vazio é um ano em que nada foi fechado para você — não um holerite que sumiu. Se você tem certeza de que trabalhou naquele período, é o RH que precisa fechar o cálculo.

### Meus comunicados: o que o colaborador recebe

A tela **Recursos humanos → Meus comunicados** (/my-announcements) é o outro lado do mural: a mesma coisa vista por quem recebe, e é a que o portal da equipe externa reproduz — as duas leem o mesmo dado. Quem **escreve e publica** é o RH, e isso está descrito em [Cadastro trabalhista (contrato de trabalho)](docId\:LxePSOpck0CqjzlijWZj3).

Nela o colaborador vê só o que está no ar para ele, do mais novo para o mais antigo, e clica em **Li este aviso**. A confirmação vale **uma vez**: clicar de novo não muda a data da primeira, que é a data que responde, depois, se a pessoa foi comunicada dentro do prazo.



![](https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/29-portal-colaborador-02-meus-comunicados.png)

Nada nessa tela pede identificação de quem é o colaborador — a pessoa vem da sessão. Se ela abrir e disser que não há vínculo, é porque o usuário logado não está ligado a um cadastro de empregado, e é isso que o cadastro de **Empregados** resolve.

### Minhas sugestões: para quem envia

O portal também deixa o colaborador **fazer sugestões**, na tela **Recursos humanos → Minhas sugestões** (/my-suggestions) — onde você envia e acompanha. Quem lê e responde é o RH, na tela dele, descrita em [Cadastro trabalhista (contrato de trabalho)](docId\:LxePSOpck0CqjzlijWZj3).

Assunto, texto, e uma caixa: **Enviar anonimamente**.



![](https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/29-portal-colaborador-03-caixa-de-sugestoes.png)

**A escolha do anônimo é definitiva, e não é só sobre quem lê.** Marcando a caixa, o nome **não chega a ser gravado** — não é gravado e escondido, não é apagado depois. As três consequências vêm juntas e a tela avisa antes do envio:

- ninguém pode ser informado de quem escreveu;
- **você não recebe resposta**, porque não há a quem responder;
- **a sugestão não aparece na sua própria lista**, porque o sistema honestamente não sabe que ela é sua.

Essa última costuma surpreender e não é defeito: se a lista mostrasse as anônimas de alguém, o sistema estaria guardando exatamente a ligação que prometeu não guardar.

Identificando-se, a sugestão entra na sua lista e a resposta do RH aparece nela. **Anônimo protege; identificar-se é o que permite ser respondido** — a decisão é sua, caso a caso.

### Minhas férias: para quem pede

Outra porta do portal é **solicitar férias**, na tela **Recursos humanos → Minhas férias** (/my-vacation) — onde você pede e acompanha. A fila em que o RH decide é outra tela, descrita em [Cadastro trabalhista (contrato de trabalho)](docId\:LxePSOpck0CqjzlijWZj3).

O seletor lista os seus **períodos aquisitivos**, cada um com o saldo (disponível/direito) e o estado. Você escolhe um período, monta até **três períodos de gozo** com data de início e quantidade de dias, informa quantos dias quer **vender** (abono) e envia.



![](https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/29-portal-colaborador-01-minhas-ferias.png)

**A conferência acontece no envio, não depois — e é essa a diferença que importa.** As regras que decidem se um conjunto de datas é legal são justamente as que ninguém de fora da folha conhece: o período aquisitivo mais antigo tem de ser gozado primeiro; dividir em três exige um período de no mínimo **quatorze** dias e nenhum com menos de **cinco**; não pode colidir com afastamento nem com férias já agendadas; no máximo **um terço** pode ser vendido. Um formulário que aceitasse qualquer coisa e respondesse "aguarde" jogaria no colaborador a culpa por uma regra que ele não tinha como saber — e ele só descobriria dias depois, por um analista.

**Período marcado Perdido é o que você precisa levar ao RH.** Ele aparece no seletor de propósito: esconder seria pior, porque a pessoa pediria e receberia uma recusa sem entender o que sumiu. Perdido significa que o prazo de gozo venceu, e a lei manda pagá-lo **em dobro**.

Enquanto ninguém decidiu, você pode **Desistir**. Depois de decidido, o pedido é histórico e continua na lista com a resposta do RH.

**O motivo do registro não é pedido a você**, e isso é decisão de projeto: aquele texto vai inscrito na trilha da vida funcional, é campo do analista, e exigi-lo aqui tornaria todo pedido ilegal por algo que não tem relação com as datas. Já a sua **observação** é opcional e serve para explicar o pedido a quem vai decidir.

### Meu ponto: o mês inteiro, e o pedido de correção

A tela **Recursos humanos → Meu ponto** (/my-time-punches) sempre deu o **comprovante** de cada marcação e as últimas **48 horas**. O que ela passou a dar é o **mês**: o cartão **Meu espelho de ponto** mostra dia a dia o que o relógio registrou **e** o que foi tratado depois.

**Isso não é conveniência, é obrigação.** A Portaria MTP 671/2021 manda no art. 84 que o Espelho de Ponto Eletrônico contenha as marcações feitas no REP **e** as tratadas — e o parágrafo único exige que o empregador dê ao trabalhador acesso **mensal** a esse documento.

**Uma marcação desconsiderada continua na tela, riscada, com o motivo ao lado.** É esse o ponto: se ela sumisse, você não teria como saber que uma batida sua foi tirada da conta, nem por quê. A marcação que alguém acrescentou aparece com (acrescentada) e **sem número de sequência** — o NSR é do relógio e não se inventa, e é assim que se distingue o que a máquina viu do que uma pessoa escreveu.



![](https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/29-portal-colaborador-04-meu-espelho-de-ponto.png)

Para pedir correção, use **Pedir uma correção**:

1. Diga **o que está errado**: falta uma marcação, ou uma marcação não deveria contar.
2. Aponte **qual** marcação, ou **quando** a que falta deveria ter sido.
3. Escreva **por quê** — é o que o gestor lê para decidir.

O pedido aparece em **Meus pedidos deste mês** com o estado. Quando for respondido, você lê a resposta **e o motivo** — inclusive na recusa, que aparece com o mesmo destaque de um aceite.

:::BlockQuote
**Você pede, você não edita.** A lei reserva a correção a quem responde pela equipe (art. 82), e é por isso que o botão diz pedir. O que você ganha é o registro que a conversa por mensagem nunca teve: quem pediu, o quê, por quê, quem respondeu e com que motivo.
:::

:::BlockQuote
**A armadilha: mês já homologado não aceita pedido.** A tela avisa antes de você digitar a justificativa. Mês ainda **em tratamento** aceita — é justamente o mês que alguém está arrumando.
:::

***

## Verificação

Você sabe que funcionou quando:

- **Meus contracheques** abre já no ano mais recente em que você tem competência **fechada**, e lista somente as suas — nenhuma de outra pessoa, nenhuma ainda em cálculo.
- O PDF baixado abre com o seu nome, a competência escolhida e os mesmos proventos e descontos que a tela mostrava.
- Quem foi desligado no meio do ano continua vendo, na lista, os holerites dos meses em que trabalhou.
- O download aparece na trilha de auditoria como **extração** — e não como simples consulta —, com o seu nome e o momento.
- **Meus comunicados** mostra só o que está no ar para você, do mais novo para o mais antigo; clicar em **Li este aviso** carimba a data, e clicar de novo não a muda.
- Essa confirmação aparece do lado do RH, na coluna **Confirmaram leitura** do comunicado.
- Uma sugestão enviada **identificada** aparece na sua lista e recebe a resposta do RH nela; uma enviada **anônima** não aparece na sua lista — e nenhuma das duas mostra o autor na relação do RH.
- **Minhas férias** recusa, **no envio**, um conjunto de datas que quebre uma das regras legais, e a recusa **nomeia a regra** (o período mais antigo primeiro, os quatorze dias, os cinco dias, o terço vendido, a colisão com afastamento).
- Um pedido válido entra na fila do RH, aparece na sua lista como aguardando, e o botão **Desistir** some assim que alguém decide.
- Depois de decidido, o pedido continua na lista com a resposta escrita pelo RH — aprovada ou recusada, sempre com texto.
- Critérios de aceitação do produto atingidos: o colaborador consultou o contracheque, pediu férias, recebeu comunicado e enviou sugestão **sem passar pelo RH**.

***

## Erros comuns

- **A tela abre e diz que não há vínculo** — o usuário logado não está ligado a um cadastro de **empregado**. Não é falta de dado da tela: é a ligação entre a identidade que entrou e a pessoa cadastrada. Quem resolve é o RH, no cadastro de **Empregados** ([Administração](docId\:Z8SS7r6Bvhs09rP1SPxUD)).
- **"Escolhi o ano e não aparece contracheque nenhum"** — naquele ano nada foi **fechado** para você. Competência em cálculo não aparece de propósito: um valor que ainda vai mudar, baixado como documento, vira a versão que a pessoa guarda. Procure o RH para fechar a competência.
- **"Enviei uma sugestão anônima e ela não está na minha lista"** — é o comportamento certo, e é o preço do anonimato: o sistema não guardou que ela é sua, então não tem como listá-la para você (ver *Minhas sugestões*, acima). Se você quer acompanhar e ser respondido, envie identificado.
- **"Confirmei a leitura do aviso duas vezes e a data não mudou"** — a confirmação vale uma vez, e a data que fica é a da **primeira**. É ela que responde se você foi comunicado dentro do prazo.
- **"Pedi férias e o sistema recusou as datas"** — a recusa nomeia a regra quebrada, e todas elas são legais, não do produto. Se o período que você quer aparece marcado **Perdido**, o caminho não é pedir de novo: é levá-lo ao RH, porque prazo de gozo vencido a lei manda pagar em dobro.
- **"Perdi o código de acesso ao portal" / "o código não funciona mais"** — o convite vence em sete dias e o código aparece uma única vez. Não há reenvio: peça ao RH que **cancele** o convite e emita outro ([Cadastro trabalhista (contrato de trabalho)](docId\:LxePSOpck0CqjzlijWZj3)).

[title] SAFe — Trens ágeis
[path] Aplicações/Agility/


[title] Untitled
[path] /


[title] Times e Pessoas
[path] Aplicações/Agility/Workspaces e Fundamentos/

:::BlockQuote
Consulte o diretório de pessoas, crie times com identidade visual e membros e acompanhe os vínculos com projetos e ARTs.
:::

:::hint{type="info"}
**Pré-requisito:**

Selecione o Workspace correto. Para criar time ou alterar membros/cor, a sessão precisa ter capacidade de edição; a consulta do diretório exige apenas acesso ao Workspace.
:::

***

Times são unidades operacionais que podem ser associados a projetos e ARTs. A lista de Times mostra os registros do Workspace; ao abrir um time, você acompanha capacidade atual, projetos ativos e membros. A página de Pessoas responde quem está no Workspace e como cada pessoa se relaciona com Times, Projetos e ARTs, sem repetir todos os vínculos em cada linha.

O diretório de Pessoas tem duas visões: Diretório, para buscar e filtrar por identidade, papel, status, times, projetos e alertas de sobreposição; e Alocação, que lista uma linha para cada vínculo Time–Projeto, mantendo inclusive pessoas sem vínculo. Ao abrir uma pessoa, as abas separam Times, ARTs via time, Projetos diretos e Projetos via time.

***

### Passo a passo

::::WorkflowBlock
:::WorkflowBlockItem
**Abrir o diretório de Times**

Na barra lateral, escolha "Workspace > Times". A tabela permite buscar pelo nome e mostra os times do Workspace. Clique em "Novo time" para abrir o formulário ou selecione uma linha para abrir o detalhe daquele time.
:::

:::WorkflowBlockItem
**Criar um time**

No formulário "Novo time", informe o nome obrigatório. Escolha opcionalmente uma cor entre as sete amostras oferecidas (laranja, azul, roxo, verde, vermelho, amarelo e azul profundo). Se houver membros no Workspace, marque as caixas de seleção desejadas; a contagem de selecionados aparece no cabeçalho da lista.
:::

:::WorkflowBlockItem
**Salvar e confirmar o time**

Clique em "Criar". O ator da sessão entra na lista de membros pelo serviço, e os membros marcados são acrescentados aos vínculos do time. O novo time aparece na tabela; abra-o para conferir o contador de membros e a cor escolhida.
:::

:::WorkflowBlockItem
**Consultar a identidade do time**

Na página do time, o cartão de identidade mostra a cor atual e os controles de paleta. Clique em outra amostra para salvar a nova cor imediatamente; use "Limpar cor" para remover a cor. Os indicadores do alto mostram quantidade de membros e projetos ativos.
:::

:::WorkflowBlockItem
**Gerenciar membros do time**

Na aba "Membros", consulte a capacidade atual e use o painel de membros para adicionar ou remover pessoas do Workspace. O painel trabalha com a lista atualizada de membros do Workspace; depois de uma alteração, aguarde a atualização do contador e da lista para confirmar o vínculo.
:::

:::WorkflowBlockItem
**Consultar os projetos do time**

Abra a aba "Projetos" no detalhe do time. Ela lista os projetos associados ao time e permite seguir para o projeto correspondente. Use essa visão para distinguir a capacidade do time dos projetos efetivamente ativos.
:::

:::WorkflowBlockItem
**Excluir um time quando necessário**

Com o detalhe aberto, clique em "Excluir". Leia a consequência exibida no diálogo de confirmação e confirme somente depois de verificar os vínculos. Após a exclusão, o Agility retorna à lista de Times do Workspace.
:::

:::WorkflowBlockItem
**Abrir Pessoas**

Na barra lateral, escolha "Gestão > Pessoas". A aba "Diretório" mostra uma tabela escaneável: nome/e-mail, papel no Workspace, times, status, projetos e eventual alerta de sobreposição. Use a busca por nome ou e-mail e os filtros de papel/status para reduzir a lista.
:::

:::WorkflowBlockItem
**Abrir o detalhe de uma pessoa**

Clique no nome ou na linha da pessoa. A janela de detalhe organiza os vínculos nas abas Times, ARTs via time, Projetos diretos e Projetos via time, cada uma com sua contagem. Um vínculo direto dá acesso ao projeto; uma participação via Time representa o vínculo operacional e mantém visíveis papel e período quando registrados.
:::

:::WorkflowBlockItem
**Ler a visão Alocação**

Troque para a aba "Alocação". Cada linha representa uma relação Time–Projeto; pessoas sem vínculo também aparecem com travessão. A tabela exibe pessoa, status, projeto e período do vínculo e mantém o alerta de sobreposição apenas na primeira linha da pessoa para não repetir o sinal.
:::

:::WorkflowBlockItem
**Usar as relações para planejar**

Quando uma pessoa aparecer em vários times ou projetos, use o alerta de sobreposição e a visão Alocação para revisar capacidade. Para alterar a relação, volte ao detalhe do Time e gerencie os membros; o diretório de Pessoas é uma leitura consolidada dos vínculos registrados.
:::
::::

:::hint{type="success"}
:FontAwesome[]{icon="fa-solid fa-check"} **Verificação**

- O novo time aparece na lista com nome e, quando escolhida, a cor selecionada.
- O detalhe do time mostra contadores de membros/projetos e as abas Membros e Projetos.
- Adicionar ou remover um membro atualiza a capacidade atual do time e a pessoa passa a refletir o vínculo no diretório.
- A tabela de Pessoas permite filtrar por papel/status e abrir o detalhe com as quatro visões de vínculo.
- A visão Alocação mostra relações Time–Projeto e mantém pessoas sem relação, em vez de ocultá-las.
:::

:::hint{type="warning"}
:FontAwesome[]{icon="fa-solid fa-triangle-exclamation"} **Erros comuns**

**O time não é criado por nome inválido**

O nome é obrigatório e é enviado sem espaços nas extremidades. Informe um nome não vazio; se a API indicar entrada inválida, revise também a cor e os membros selecionados.

**Conflito ao criar um time**

O serviço sinaliza conflito quando o cadastro colide com um time existente. Retorne à lista, escolha outro nome e tente novamente em vez de repetir o mesmo envio.

**Uma pessoa aparece sem nome ou com papel desconhecido**

O diretório preserva a identidade devolvida pela API. Usuários não resolvidos ou papéis que não fazem parte das opções conhecidas aparecem com o valor disponível e não devem ser interpretados como ausência de vínculo.

**Uma pessoa não aparece na visão Alocação**

A visão monta linhas a partir dos vínculos via Time e inclui uma linha com travessão para quem não tem nenhum. Se um vínculo acabou de ser alterado, recarregue a página para atualizar a projeção do diretório.

**Não há controles para editar cor ou membros**

A sessão pode estar em modo somente leitura. Solicite a capacidade de edição ao administrador; a consulta do time e das pessoas continua disponível.
:::


[title] Operar um Portfólio
[path] Aplicações/Agility/Workspaces e Fundamentos/

:::BlockQuote
Crie ou abra um portfólio e percorra o backlog estratégico, os value streams, o orçamento, o roadmap e as configurações de identidade.
:::

:::hint{type="info"}
**Pré-requisito:**

Tenha um Workspace selecionado e permissão de edição para criar ou alterar portfólio, value streams e orçamento. A leitura das telas continua disponível sem essa permissão.
:::

***

Um Portfólio organiza investimento estratégico em Épicos e Value Streams. No Workspace, a tabela de portfólios permite buscar por código ou nome e exibe indicadores de value streams, épicos ativos e épicos em análise. Abrir um registro leva a um shell próprio com cinco abas: Backlog, Value Streams, Orçamento, Roadmap e Configurações.

O fluxo recomendado começa pela identidade do portfólio e por pelo menos um Value Stream. Depois você pode registrar um Épico no backlog, definir o teto do Lean Budget, acompanhar o funil no Roadmap e ajustar nome ou descrição em Configurações. É o mesmo dado visto em painéis diferentes, não cópias independentes.

***

### Passo a passo

::::WorkflowBlock
:::WorkflowBlockItem
**Abrir os portfólios do Workspace**

Na barra lateral, escolha "Estratégia > Portfólios". A tabela apresenta cada portfólio com código e nome, quantidade de Value Streams, quantidade de Épicos ativos e quantidade em análise. Use o campo de busca para filtrar por código ou nome antes de abrir um registro.
:::

:::WorkflowBlockItem
**Criar um portfólio**

Clique em "Novo portfólio". Informe o código e o nome, ambos obrigatórios; acrescente uma descrição para explicar o domínio de investimento. O formulário também permite cadastrar imediatamente o primeiro Value Stream com código e nome opcionais. Se deixar esses campos vazios, crie o stream depois na aba Value Streams.
:::

:::WorkflowBlockItem
**Abrir o portfólio**

Clique no código ou nome na tabela, ou selecione a linha. O portfólio abre no Backlog. O cabeçalho mostra o nome e a descrição e a navegação segmentada mantém disponíveis Backlog, Value Streams, Orçamento, Roadmap e Configurações.
:::

:::WorkflowBlockItem
**Cadastrar um Value Stream**

Abra "Value Streams" e use o formulário "Novo Value Stream". Informe código e nome obrigatórios e, se necessário, uma descrição. Clique em "Criar". O cartão criado mostra nome, código e descrição; a partir dele você pode editar o nome/descrição ou remover o stream.
:::

:::WorkflowBlockItem
**Corrigir ou editar um Value Stream**

Clique em "Editar" no cartão. O código aparece bloqueado para preservar a identificação e você pode alterar nome e descrição. Salve as alterações ou cancele para retornar ao formulário vazio. Remover usa a ação destrutiva do cartão; confirme somente se nenhum Épico precisar mais desse stream.
:::

:::WorkflowBlockItem
**Registrar um Épico no backlog estratégico**

Volte a "Backlog" e clique em "Novo Épico". Selecione um Value Stream e um responsável entre os membros do Workspace, escolha o tipo Negócio ou Habilitador, informe o investimento em reais e preencha a hipótese e o MVP. Quando houver ARTs, marque os trens afetados. Envie o formulário para criar o cartão.
:::

:::WorkflowBlockItem
**Acompanhar o funil do backlog**

O backlog é um Kanban estratégico. Os cartões são organizados nas colunas Funil, Em revisão, Em análise, Backlog, Em implementação e Concluído. Você pode filtrar pelo Value Stream, abrir o Épico para ver detalhes e arrastar o cartão entre estados; a mudança de coluna é persistida como transição.
:::

:::WorkflowBlockItem
**Definir o Orçamento**

Abra "Orçamento" e informe o limite do Lean Budget no campo numérico, em reais, com até duas casas decimais. Clique em "Salvar". A tela mostra o valor formatado em BRL e, para cada Value Stream, o limite do portfólio, o investimento dos Épicos ativos e a quantidade de Épicos ativos. Épicos concluídos não entram mais na reserva ativa.
:::

:::WorkflowBlockItem
**Ler o Roadmap**

Abra "Roadmap" para visualizar os Épicos em uma pilha vertical, separados pelos seis estados do funil. Cada seção traz a quantidade de itens e cada cartão recebe uma posição própria naquela seção. Clique no cartão para abrir o detalhe lateral; use o link para voltar ao Backlog quando precisar alterar o estado.
:::

:::WorkflowBlockItem
**Atualizar as configurações**

Em "Configurações", o código é apenas leitura e não pode ser trocado. Edite o nome e a descrição e clique em "Salvar". O cabeçalho, a tabela e todos os cartões passam a usar o nome atualizado depois que o portfólio é recarregado.
:::

:::WorkflowBlockItem
**Operar somente em leitura**

Quando a sessão não tem capacidade de edição, os formulários ficam desabilitados ou a tela informa "somente leitura". Você ainda pode abrir o backlog, consultar o roadmap, visualizar cards e filtrar a tabela, mas deve solicitar a permissão adequada para criar, editar, remover ou salvar orçamento.
:::
::::

:::hint{type="success"}
:FontAwesome[]{icon="fa-solid fa-check"}  **Verificação**

- O portfólio aparece na tabela do Workspace com código, nome e os indicadores de Value Streams e Épicos.
- Há pelo menos um Value Stream no cartão correspondente e o botão "Novo Épico" fica habilitado no Backlog.
- Um Épico criado aparece em uma coluna do funil e também no Roadmap, com o mesmo estado e dados.
- O orçamento salvo é mostrado em reais e o detalhamento por Value Stream reflete os Épicos ativos.
- Uma alteração de nome ou descrição em Configurações aparece no cabeçalho depois de salvar.
:::

:::hint{type="warning"}
:FontAwesome[]{icon="fa-solid fa-triangle-exclamation"} **Erros comuns**

**Não é possível criar um portfólio**

Código e nome são obrigatórios. Preencha ambos com texto; se a API informar conflito, escolha um código ainda não usado no Workspace.

**O botão Novo Épico está desabilitado**

O backlog exige pelo menos um Value Stream. Cadastre-o primeiro em Value Streams e retorne ao Backlog; o botão é deliberadamente bloqueado enquanto a lista estiver vazia.

**O orçamento não é salvo**

O limite deve ser um número finito maior ou igual a zero. Remova texto ou separadores inválidos, use duas casas decimais no máximo e tente novamente.

**Um Épico não passa pelo formulário**

Selecione Value Stream e responsável e preencha título, hipótese e MVP. O investimento deve ser numérico; os ARTs são opcionais quando existem no Workspace.

**O código do Value Stream não pode ser alterado**

O código é a identificação estável do stream e fica desabilitado no modo de edição. Crie um novo stream se a identificação estiver incorreta, em vez de tentar editar o campo bloqueado.
:::


[title] Riscos do projeto
[path] Aplicações/Agility/Sprints e cronograma/

:::BlockQuote
Registre riscos operacionais do Projeto, calcule a exposição por probabilidade e impacto, acompanhe o status, a resposta e a responsabilidade.
:::

:::hint{type="info"}
**Pré-requisito:**

O Projeto deve usar uma forma de trabalho que disponibilize a capacidade de Riscos (como o Projeto ERP Financeiro Tradicional usado neste roteiro) e o usuário precisa ter permissão de edição para criar ou atualizar o registro.
:::

***

O Registro de riscos do Projeto é o lugar para acompanhar incertezas que podem afetar escopo, prazo, custo ou qualidade. Ele é separado dos riscos ROAM de um ART: um risco aqui pertence ao Projeto e pode ser acompanhado pela equipe responsável pela entrega.

Cada registro combina título, descrição, probabilidade de 1 a 5, impacto de 1 a 5, status, responsável e estratégia de resposta. A exposição é calculada pelo servidor a partir de probabilidade e impacto e aparece como "P x I" na tabela; ela não é editada diretamente pelo formulário.

***

### Passo a passo

::::WorkflowBlock
:::WorkflowBlockItem
**Abrir o registro do Projeto**

No ERP Financeiro, clique em "Riscos". A página explica que o registro é separado dos riscos ROAM do ART e apresenta a contagem Total e Encerrados quando já existem itens. No ambiente usado no roteiro, o registro começou sem riscos; por isso foi criado um risco operacional antes da captura de tela.
:::

:::WorkflowBlockItem
**Iniciar um novo risco**

Clique em "Novo risco". O diálogo informa que o responsável precisa ser uma pessoa ativa do Workspace e que a exposição será calculada pelo servidor. O formulário apresenta Título, Descrição, Probabilidade, Impacto, Status, Responsável e Estratégia de resposta.
:::

:::WorkflowBlockItem
**Descrever o evento**

No Título, escreva uma frase curta e identificável, como "Indisponibilidade do provedor de pagamentos". Em Descrição, explique o evento e a consequência concreta para o Projeto; no exemplo, a indisponibilidade poderia atrasar a homologação e o go-live. Evite colocar a mitigação somente na descrição, porque há um campo próprio para a resposta.
:::

:::WorkflowBlockItem
**Avaliar probabilidade e impacto**

Escolha Probabilidade e Impacto nos seletores de 1 a 5. Probabilidade representa a chance de o evento ocorrer; Impacto representa a severidade para o Projeto. No exemplo, foi escolhida probabilidade 5 e impacto 1, resultando em exposição 5 (P5 × I1). O formulário aceita apenas valores entre 1 e 5.
:::

:::WorkflowBlockItem
**Definir status e responsável**

O status inicial é "Aberto"; ao acompanhar o plano, você pode alterar para Mitigando, Aceito ou Encerrado. Selecione uma pessoa ativa em Responsável ou deixe "Sem responsável" até haver um dono definido. A tela mostra o nome do responsável na tabela e mantém o risco separado de responsáveis de tarefas ou WBS.
:::

:::WorkflowBlockItem
**Registrar a estratégia de resposta**

Em Estratégia de resposta, documente a ação concreta: reduzir probabilidade, reduzir impacto, transferir, aceitar ou acompanhar. No roteiro, a resposta foi validar o plano de contingência, testar retentativas e manter contato de escalonamento. Essa coluna aparece na tabela junto da data de atualização, para que a equipe saiba qual ação está sendo monitorada.
:::

:::WorkflowBlockItem
**Criar e conferir a exposição**

Clique em "Criar risco" e aguarde o retorno. O novo registro aparece na tabela com título e descrição, exposição numérica, notação P × I, status, responsável e resposta. No exemplo, a tabela passou a mostrar Total: 1 · Encerrados: 0, o selo Aberto, Sem responsável e a data de atualização.
:::

:::WorkflowBlockItem
**Atualizar o acompanhamento**

Quando a resposta avançar, use o ícone de edição na linha do risco. Você pode ajustar descrição, probabilidade, impacto, status, responsável e estratégia; salve a alteração e confirme que a exposição e a data de atualização foram recalculadas. Marque Encerrado somente quando a ameaça estiver resolvida ou formalmente fechada.
:::

:::WorkflowBlockItem
**Usar o registro em conjunto com o cronograma**

Relacione mentalmente um risco a seus efeitos nas atividades, marcos e caminho crítico do Projeto. A página de Riscos não altera automaticamente uma barra do Gantt; se a resposta mudar datas, progresso ou dependências, atualize o item correspondente na WBS e depois revise Gantt, Marcos e Baselines.
:::
::::

![](https://itsm-labdev.cloud4biz.com/agility-v2/docs/screens/04-riscos-projeto.webp "Registro de riscos do Projeto com o risco de indisponibilidade do provedor, exposição 5 P5 × I1, status Aberto e estratégia de resposta")

:::hint{type="success"}
:FontAwesome[]{icon="fa-solid fa-check"} **Verificação**

- O registro mostra Total e Encerrados e contém o risco criado com título e descrição reconhecíveis.
- A exposição exibida corresponde à multiplicação de probabilidade e impacto e aparece como Pn × In.
- O status inicial é Aberto e a estratégia de resposta fica visível na mesma linha, com data de atualização.
- A edição permite trocar status, dono, avaliação e resposta sem alterar diretamente o valor calculado de exposição.
- Um risco encerrado aumenta a contagem Encerrados e permanece no histórico do Projeto para consulta.
:::

:::hint{type="warning"}
****:FontAwesome[****]{icon="fa-solid fa-triangle-exclamation"}**&#x20;Erros comuns**

**Título, probabilidade ou impacto inválidos**

O formulário rejeita título vazio e valores fora de 1 a 5. Preencha o título e escolha uma opção válida em ambos os seletores antes de criar ou salvar.

**Responsável não está ativo no Workspace**

O backend valida que o responsável seja uma pessoa ativa do Workspace. Se a pessoa foi removida ou está inativa, selecione outro membro ativo ou use Sem responsável até regularizar o acesso.

**A exposição não pode ser editada**

Exposição é calculada pelo servidor e a UI não envia um campo editável para ela. Altere Probabilidade ou Impacto; ao salvar, a tabela mostrará o novo produto P × I.

**Conflito ao salvar uma atualização**

Se outra pessoa alterou o mesmo risco, o servidor pode responder com conflito. Recarregue o registro, compare status, avaliação e estratégia atuais e reaplique somente a alteração necessária sobre a versão mais recente.
:::


[title] Integrações
[path] Aplicações/Agility/Sistema/

:::BlockQuote
Consulte o catálogo de contratos que conectam o Agility ao ERP, acompanhe cada tentativa de leitura e reprocesse uma operação quando ela falhar.
:::

:::hint{type="info"}
**Pré-requisito:&#x20;**

Você precisa estar dentro de um Workspace e ter acesso à opção Integrações na seção Sistema da barra lateral.
:::

***

A tela Integrações é o catálogo de adapters do ERP para o Workspace ativo. Ela mostra quais leituras estão publicadas, o domínio e a versão de cada contrato, o endpoint que pode ser auditado e a procedência do dado. A tela não altera fatos no ERP: são operações de consulta, e qualquer correção deve ser feita no sistema de origem.

No ambiente de demonstração, o cabeçalho identifica explicitamente o Adapter de demonstração. Os contratos usam o mesmo contrato HTTP do produto, mas são atendidos por um adapter determinístico; portanto, nenhum dado desta tela deve ser interpretado como uma sincronização viva com o ERP. Quando o modo ERP real estiver ligado, a própria tela passa a informar que as consultas são feitas ao ERP corporativo e cada leitura registra uma execução.

***

### Passo a passo

::::WorkflowBlock
:::WorkflowBlockItem
**Abrir o catálogo do Workspace**

Na barra lateral, expanda o grupo Sistema e clique em Integrações. A página mostra o título Integrações e o subtítulo Integrações configuradas para este workspace. O catálogo é contextualizado pelo Workspace selecionado no topo; se o identificador do Workspace não puder ser resolvido, a página informa que o Workspace não foi encontrado em vez de exibir contratos de outro contexto.
:::

:::WorkflowBlockItem
**Conferir a procedência da conexão**

Leia o cartão superior antes de interpretar qualquer contrato. No ambiente usado neste manual, o cartão diz Adapter de demonstração e explica que os contratos são atendidos por um adapter determinístico, com o mesmo contrato HTTP do produto, mas sem dados vindos do ERP. Em uma instalação ligada ao ERP, o cartão muda para Integração ao vivo com o ERP e informa que as leituras consultam o ERP corporativo e registram uma execução.
:::

:::WorkflowBlockItem
**Identificar os contratos disponíveis**

Cada cartão de contrato apresenta o nome funcional, o selo de disponibilidade e o estado de sincronização. No Workspace Portal de Serviços, o catálogo povoado exibe Projetos (dimensão do ERP), Parceiros (clientes e fornecedores), Centros de custo, Títulos a pagar e a receber, Saldo de orçamento por projeto e Posição de aging e ciclo de caixa. O estado Sem sincronização e a frase Nunca sincronizado significam que ainda não houve uma execução bem-sucedida para aquele contrato; não significam que o contrato está indisponível.
:::

:::WorkflowBlockItem
**Auditar domínio, versão e endpoint**

Abaixo do nome de cada contrato, confira o endpoint publicado, o domínio e a versão. Os contratos de registro usam GET /api/registry/projects e GET /api/registry/partners, no domínio registry, contrato v1. Os contratos financeiros usam GET /api/finance/cost-centers e GET /api/finance/financial-documents, no domínio finance, contrato v1. O saldo por projeto usa GET /api/costing/budget-consumptions/balance-by-dimension, no domínio costing, contrato v1; aging informa GET /api/finance/aging/kpis + /aging/top-debtors, no domínio finance, contrato v1.
:::

:::WorkflowBlockItem
**Interpretar os selos de estado**

O selo Disponível indica que o contrato está publicado para consulta. Ao lado dele, o selo de frescor diferencia o dado atual, simulado, defasado ou desconhecido. No adapter de demonstração, um resultado determinístico correto continua sendo identificado como simulado — não como atual. Quando a última tentativa falha, o cartão mostra a mensagem da falha e, se o dado estiver defasado, avisa que as telas continuam exibindo o último dado conhecido marcado como defasado.
:::

:::WorkflowBlockItem
**Ver o histórico de tentativas**

No contrato desejado, clique em Ver tentativas. A tela abre uma tabela abaixo dos botões com as colunas Quando, Resultado, Itens, Duração e Correlação. Cada linha informa a data e hora de conclusão, OK ou Erro, a quantidade de itens retornados, a duração em milissegundos e o correlation ID. O histórico é somente de acompanhamento e é cumulativo: uma nova execução não apaga a tentativa anterior.
:::

:::WorkflowBlockItem
**Localizar uma falha para reprocessamento**

Se a última execução falhar, leia o texto ao lado do ícone de alerta no cartão e abra Ver tentativas para conferir o erro, a quantidade e o correlation ID. Use essas informações para diferenciar uma falha transitória de uma resposta sem itens. A tentativa que falhou permanece visível depois de qualquer nova tentativa, o que permite comparar o resultado anterior com o reprocessamento.
:::

:::WorkflowBlockItem
**Passo 8 — Reprocessar uma operação sem parâmetros**

Para contratos que não dependem de uma dimensão específica, clique em Reprocessar. O botão fica desabilitado durante o processamento e troca seu texto para Reprocessando…. Ao terminar, o Agility recarrega o contrato e as tentativas; o cartão atualiza o último resultado e a lista ganha uma nova linha. O reprocessamento repete a leitura do contrato, não edita o fato correspondente no ERP.
:::

:::WorkflowBlockItem
**Tratar o saldo de orçamento por projeto**

No cartão Saldo de orçamento por projeto, o botão Reprocessar aparece desabilitado e vem acompanhado da explicação de que a consulta exige informar projeto e data. Não tente contornar essa restrição clicando repetidamente: esta tela não tem os campos necessários para montar esses parâmetros. Abra a superfície que solicita projeto e data para uma consulta parametrizada, ou corrija o dado no ERP de origem conforme a regra do processo.
:::

:::WorkflowBlockItem
**Verificar o resultado**

Depois de uma execução concluída, confirme a nova data em última sincronização bem-sucedida em… e abra Ver tentativas para localizar a linha mais recente. Um resultado OK, sua quantidade de itens, duração e correlation ID são a evidência operacional da leitura. Se a execução continuar em erro, o cartão mantém a mensagem de falha e o estado defasado quando aplicável; isso é uma informação para investigação, não uma confirmação de atualização.
:::
::::

![](https://itsm-labdev.cloud4biz.com/agility-v2/docs/screens/10-integracoes-catalogo.webp "Catálogo de Integrações do Workspace com o adapter de demonstração, contratos ERP disponíveis, endpoints e botões Ver tentativas e Reprocessar")

:::hint{type="success"}
:FontAwesome[]{icon="fa-solid fa-check"} **Verificação**

- O cabeçalho identifica explicitamente se a conexão é um Adapter de demonstração ou uma Integração ao vivo com o ERP.
- Cada contrato mostra nome, disponibilidade, frescor, domínio, versão, endpoint e última sincronização (ou Nunca sincronizado).
- Ver tentativas revela data/hora, resultado, quantidade de itens, duração e correlation ID sem apagar linhas anteriores.
- Após um reprocessamento permitido, uma nova execução aparece no histórico e o cartão atualiza o último resultado; o contrato parametrizado permanece corretamente bloqueado sem projeto e data.
:::

:::hint{type="warning"}
:FontAwesome[]{icon="fa-solid fa-triangle-exclamation"} **Erros comuns**

**O catálogo mostra erro de carregamento**

Confira se você está dentro de um Workspace válido e recarregue a página. A rota interrompe o carregamento quando não recebe workspaceId ou quando a consulta de contratos falha; ela mostra uma mensagem de erro em vez de apresentar uma lista parcial.

**Um contrato aparece como defasado**

Leia a mensagem da última tentativa e abra o histórico. Defasado significa que a última leitura não confirmou um dado novo, embora o último dado conhecido possa continuar sendo exibido. Reprocesse apenas contratos sem parâmetros e confirme o novo resultado; para o saldo por projeto, informe projeto e data na consulta apropriada.

**O botão Reprocessar está desabilitado**

No contrato Saldo de orçamento por projeto isso é intencional: a operação requer projeto e data e a tela de catálogo não os coleta. Em outros contratos, aguarde o processamento terminar; o botão também fica desabilitado enquanto a chamada está em andamento.

**A execução foi bem-sucedida, mas o dado continua marcado como simulado**

Esse é o comportamento honesto do adapter de demonstração. Simulado descreve a procedência do resultado, não a qualidade da resposta. Somente a configuração de uma integração ERP real muda o modo indicado no cabeçalho.

**O histórico não abre**

A tabela de tentativas é carregada separadamente do catálogo. Se a consulta falhar, a lista não é exibida e a mensagem Falha ao carregar as tentativas aparece no cartão; registre o erro e tente novamente, sem interpretar a ausência da tabela como ausência de execuções.
:::


[title] Workspaces e Fundamentos
[path] Aplicações/Agility/


[title] Tesouraria
[path] Aplicações/ERP/Manual do Usuário/

# Tesouraria (caixa e bancos, ordens de pagamento, índices, CNAB, extrato e conciliação)

:::BlockQuote
Pré-requisitos: [Cadastro fiscal próprio](docId\:Q-zx6Qk4pMFD09yrhmsve) (conta bancária da matriz cadastrada), [Financeiro — cadastros de apoio](docId\:yTzjjyyML1B_60VgwDT09) (formas/meios de pagamento e categorias) e [Financeiro — títulos (contas a pagar e a receber)](docId\:D4kuGidayU2GQ-hMhF_T-) (algumas contas a pagar/receber já lançadas e em aberto).
:::

## Introdução

***

A tesouraria é o coração operacional do dia-a-dia financeiro. É aqui que você acompanha o saldo de cada conta bancária e do caixa, agrupa várias contas a pagar em uma única ordem para liquidar de uma vez, mantém os índices de correção (SELIC, CDI, IPCA) que reajustam valores no tempo, troca arquivos com o banco pelo padrão *CNAB* (remessa e retorno), importa o extrato bancário e faz a conciliação — casar cada linha do extrato com o lançamento correspondente no sistema.

Você usa esta parte do ERP todos os dias: de manhã para conferir o saldo consolidado e programar os pagamentos do dia, e ao longo do mês para importar o extrato, conciliar, gerar remessas de cobrança e compensar valores com parceiros que são cliente e fornecedor ao mesmo tempo (*encontro de contas*). Cada conciliação e cada baixa de ordem gera automaticamente o *lançamento contábil* correspondente, mantendo a contabilidade em dia sem digitação manual.

## Passo a passo

***

### Consultar caixa e bancos

O ponto de partida do dia é conferir para onde o dinheiro está indo e de onde está entrando, conta por conta.

1. **Abra "Caixa e banco".** No menu lateral, vá em **Financeiro → Caixa e banco**. A tela lista os movimentos de cada conta (entradas e saídas) com data, descrição, valor e o saldo resultante. Filtre por conta bancária (banco 341 — Itaú, agência 0001, conta 12345-6) e por período para focar no que interessa.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/024-cash-bank.png" alt caption width="3200" height="2000"}
2. **Abra a tesouraria.** Em **Financeiro → Tesouraria** você faz a **apropriação mensal por competência** (informa o mês de competência e clica em "Apropriar" para apropriar juros e rendimento das contas internas) e consulta os **saldos de captações e aplicações** por contrato.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/034-treasury.png" alt caption width="3200" height="2000"}

### Manter os índices e indexadores

Índices como SELIC, CDI, IPCA e TR são usados para corrigir valores ao longo do tempo (juros de mora, atualização monetária de contratos, correção de saldos). O sistema mantém uma tabela desses índices com as taxas por período.

1. **Abra "Índices".** Vá em **Financeiro → Indexadores**. A tela lista os indexadores cadastrados e as taxas registradas por data.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/035-treasury-indexes.png" alt caption width="3200" height="2000"}
2. **Abra um índice para ver o histórico.** Clique no índice desejado para ver a ficha com a série de taxas por período. É a partir daqui que você confere se a taxa do mês vigente já foi lançada — sem ela, correções ficam desatualizadas.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/011-treasury-indexes-detail.png" alt caption width="3200" height="2000"}

### Criar uma ordem de pagamento (pagar várias contas juntas)

Em vez de liquidar conta a conta, você agrupa várias contas a pagar em uma **ordem de pagamento** e libera tudo de uma vez, respeitando a *alçada* de aprovação.

1. **Abra "Ordens de pagamento".** Vá em **Financeiro → Ordens de pagamento**. A tela lista as ordens existentes com sua situação (rascunho, autorizada, liquidada, cancelada).:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/055-payment-orders.png" alt caption width="3200" height="2000"}
2. **Nova ordem (rascunho).** Clique em "Nova" e preencha:
   - **Conta bancária** — de qual banco vai sair o pagamento (banco 341, conta 12345-6).
   - **Data programada** — quando o pagamento será executado.
   - **Descrição** — ex.: Lote fornecedores SP.
3. **Adicionar contas a pagar.** Dentro da ordem, clique em "Adicionar conta" e escolha cada conta a pagar **em aberto** que entra no lote (ex.: uma conta de R$ 1.250,00 do Fornecedor Exemplo Ltda). O valor total da ordem é atualizado automaticamente a cada conta incluída. Cada item da ordem **fotografa a conta de destino do fornecedor** (banco, agência, conta e chave PIX) e a exibe na coluna **Conta do favorecido** — o que você vê ali é exatamente o que vai para o banco, congelado no momento em que o item foi criado. Trocar depois a conta do fornecedor **não** altera uma ordem já montada. É esse snapshot que alimenta a remessa CNAB.Se a conta aparecer como **"Sem conta"**, o favorecido não tem conta principal eleita — veja o passo seguinte.
4. **Eleger a conta principal do favorecido (quando ele tem mais de uma).** Na ficha do parceiro, no bloco **Contas bancárias / PIX**, a conta marcada com o selo **Principal** é a creditada por padrão quando o lançamento não escolhe uma explicitamente. Para trocar, clique em **"Tornar principal"** na conta desejada — o selo migra na hora, e cada favorecido tem no máximo uma. Um favorecido **sem** conta principal gera título sem roteirização, e esse título não entra numa ordem de pagamento.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/010-payment-orders-detail.png" alt caption width="3200" height="2000"}
5. **Autorizar.** Com o lote pronto, clique em "Autorizar". A situação muda de **rascunho** para **autorizada** — a partir daqui as contas estão comprometidas e a ordem entra na fila de execução. Se o valor total ultrapassar o limite da sua alçada, a ordem fica pendente de aprovação de um superior antes de poder ser autorizada.
6. **Baixar (liquidar).** No dia do pagamento — ou depois de confirmar a saída pelo extrato — clique em "Baixar". A situação muda para **liquidada**, cada conta vinculada passa a **paga** e os lançamentos contábeis são gerados automaticamente.
7. **Cancelar (se necessário).** Enquanto a ordem ainda não foi baixada, é possível cancelá-la. Todas as contas vinculadas voltam ao estado **em aberto** e podem entrar em outra ordem.

### Gerar remessa CNAB (falar com o banco por arquivo)

O padrão *CNAB* (240 ou 400 posições) é a forma de trocar instruções com o banco por arquivo: você envia a **remessa** (instruções de cobrança, pagamento ou *boleto*) e recebe o **retorno** (confirmações e ocorrências).

1. **Abra "Remessas CNAB".** Vá em **Financeiro → Remessas CNAB**. A tela reúne os arquivos de remessa enviados ao banco; no ambiente de demonstração ela aparece vazia ("Nenhuma remessa") até você gerar a primeira remessa.A tela exige a permissão **Gerenciar importação bancária**. Quem não a tem **não enxerga o item no menu**; e, se abrir a rota direto, recebe **"Você não tem acesso a isto"** — não uma lista vazia, que passaria a impressão errada de que o órgão nunca enviou remessa nenhuma.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/025-cnab-remittances.png" alt caption width="3200" height="2000"}
2. **Gerar uma remessa.** Clique em "Gerar remessa", escolha a conta bancária e o conjunto de documentos que entram no arquivo. O sistema monta o arquivo no layout do seu banco (banco 341). Baixe o arquivo gerado e envie pelo internet banking do banco.
3.

O ato exige a permissão **Gerenciar importação bancária**, a mesma da remessa. A tela de caixa e banco continua abrindo para quem não a tem (ela serve também a quem só lança movimento de caixa); o que aparece, ao tentar processar, é a **recusa explícita** — nunca uma tela que parece ter funcionado.

**Dois avisos que valem ler.** Se o arquivo não for o retorno daquele banco, é comum que o sistema **não reconheça nenhuma linha**: em vez de fingir sucesso, a tela diz *"Nenhuma linha de detalhe foi reconhecida neste arquivo — nada foi liquidado"*. E se o arquivo tiver uma linha de detalhe corrompida ou de outro layout, o sistema **recusa o arquivo inteiro dizendo em qual linha parou** — nada é liquidado pela metade.

**Registrar o retorno.** O retorno **não** se envia pela tela de remessas: ele entra em **Financeiro → Caixa e banco**, no cartão **Retorno bancário**, logo abaixo da remessa. Selecione a mesma conta bancária, escolha o arquivo que o banco devolveu e clique em **"Processar retorno"**.O sistema lê cada ocorrência (pago, rejeitado, baixado) e casa cada uma com o título pelo **nosso número**, atualizando a situação — o título baixa automaticamente e o movimento de crédito aparece no caixa da conta. Logo abaixo do botão, a tela informa **quantas ocorrências reconheceu** e lista todas elas, inclusive as que baixaram — é a única visão que mostra o retorno inteiro, porque a *fila de conciliação* só guarda o que **não** baixou.Ocorrências que não baixam sozinhas vão para essa fila de tratamento manual, com um de **três** rótulos\:O sistema só baixa sozinho quando a ocorrência é de **liquidação** **e** o valor confere exatamente com o saldo devido. Qualquer outra combinação vira uma linha nessa fila, de propósito: baixar por aproximação seria dar por pago o que o banco não disse que foi pago.

:::Paragraph{listStyleType="disc" indent="2"}
**"Título não localizado"** — o nosso-número da ocorrência não casa com nenhum título enviado em remessa.
:::

:::Paragraph{listStyleType="disc" indent="2"}
**"Valor divergente"** — casou o título, mas o valor que o banco informa não bate com o saldo devido. O sistema **não** baixa por diferença; a decisão é sua.
:::

:::Paragraph{listStyleType="disc" indent="2"}
**"Pendente"** — casou o título, mas a ocorrência **não é de liquidação**. Tende a ser o rótulo mais comum num retorno real, porque o banco devolve uma linha para cada evento do título, não só para o pagamento: confirmação de registro, alteração, instrução acatada. Ver várias dessas linhas depois de importar um retorno é **esperado**, não é erro — elas registram o que o banco fez com o título, não um recebimento.Para saber **o que** cada uma é, leia a coluna **Ocorrência**: ela mostra o código e a descrição **como vieram no arquivo do banco**. O sistema não traduz esses códigos — cada banco usa a sua tabela, e inventar um significado aqui seria arriscar dizer "pago" sobre o que não foi.
:::

### Pagar a folha e os tributos por arquivo (remessa de pagamento)

A remessa de **cobrança** acima manda o banco cobrar dos seus clientes. A remessa de **pagamento** faz o contrário: manda o banco pagar — o salário de cada colaborador, uma guia de tributo, uma transferência a fornecedor.

13a. **Abra "Remessas de pagamento".** Vá em **Financeiro → Remessas de pagamento (tributos, folha)**. A tela tem duas entradas: as **guias de tributo em aberto**, que você marca uma a uma, e a **ordem de pagamento**, que traz de uma vez todas as transferências de um lote — é por aqui que a folha do mês entra. Vindo de um lote de folha, o botão **"Pagar no banco"** do passo 75a da página[Financeiro — títulos (contas a pagar e a receber)](docId\:D4kuGidayU2GQ-hMhF_T-) traz você até aqui.

13b. **Escolha a conta pagadora e o que vai no arquivo.** Selecione a conta bancária e, no campo **Ordem de pagamento**, a ordem autorizada que você quer pagar. Pode combinar: guias marcadas **e** uma ordem, no mesmo arquivo.

:::BlockQuote
\> \*\*O arquivo é recusado antes de sair, e não pelo banco, em dois casos.\*\* Se a
\> conta pagadora não tiver o \*\*código de convênio\*\* cadastrado, o sistema não
\> gera — nenhum banco processa arquivo sem ele, e um arquivo sem convênio é
\> recusado por inteiro, não linha a linha. E se algum colaborador do lote de
\> folha estiver \*\*sem CPF cadastrado\*\*, o sistema recusa \*\*dizendo o nome de
\> quem falta\*\*: é o CPF que permite ao banco conferir que a conta creditada é
\> mesmo daquela pessoa.
:::

13c. **Baixe e envie.** O arquivo sai no padrão CNAB-240, organizado em **lotes**: um lote por tipo de pagamento e forma de crédito. Os salários viajam num lote declarado como **pagamento de salários**; as guias de tributo, noutro. Quem recebe por PIX sai em lote separado — um lote nunca mistura formas de pagamento, porque essa informação fica no cabeçalho do lote e só cabe uma.

13d. **Importe o retorno do pagamento.** Dias depois o banco devolve um arquivo dizendo, pagamento a pagamento, o que aconteceu. Importe-o no cartão **Retorno bancário**, na mesma tela.

:::BlockQuote
\> \*\*Aceite não é pagamento — e o sistema não confunde os dois.\*\* O banco
\> costuma responder duas vezes: primeiro para dizer que \*\*aceitou\*\* a
\> instrução, depois, na data do crédito, para dizer que \*\*pagou\*\*. Só a
\> segunda resposta baixa o título. Entre uma e outra ainda cabe saldo
\> insuficiente, conta bloqueada ou cancelamento — dar baixa no aceite seria
\> registrar como pago um salário que ninguém recebeu.
:::

13e. **Trate a fila de exceção.** Todo pagamento que o banco **não** efetivou aparece na **Fila de exceção**, com o motivo em português ("Conta do favorecido inválida", "Saldo insuficiente") em vez do código do banco. O título correspondente **continua em aberto** — é isso que garante que um pagamento recusado não desapareça.

:::BlockQuote
\> \*\*Um arquivo ilegível dá erro, não "zero ocorrências".\*\* Se você importar o
\> arquivo errado, o sistema recusa a importação dizendo isso. Ele nunca
\> registra uma importação bem-sucedida sem nenhum resultado — que é como um
\> lote inteiro de pagamentos recusados passaria despercebido.
:::

### Importar o extrato bancário

Para conferir o que de fato entrou e saiu, você traz o extrato do banco para dentro do sistema.

1. **Abra "Importar extrato".** Vá em **Financeiro → Importar extrato**. Escolha a conta bancária (banco 341, conta 12345-6) e selecione o arquivo de extrato baixado do internet banking. O formato aceito é **OFX** (o mesmo que os bancos disponibilizam para download) — planilha CSV **não** é um formato de extrato aqui.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/043-bank-import.png" alt caption width="3200" height="2000"}
2.

💡 **O mesmo arquivo não entra duas vezes.** Cada importação guarda uma assinatura do conteúdo do arquivo. Se você (ou um colega) reenviar **exatamente o mesmo** extrato para a **mesma conta**, o sistema recusa e diz **quando** ele já foi importado — porque importar de novo abriria uma **segunda conciliação** sobre o mesmo período, e as duas poderiam ser fechadas contra os mesmos lançamentos. Um arquivo **diferente** (outro período, ou o mesmo período reexportado com outras linhas) importa normalmente: a trava é sobre o arquivo idêntico, não sobre a conta.

**Confira o resultado.** O sistema transforma o arquivo em linhas de extrato (data, descrição, valor, entrada/saída). As linhas que ainda não foram casadas com um lançamento ficam com situação **pendente** — prontas para a conciliação.

### Conciliar o extrato

Conciliar é casar cada linha do extrato do banco com o lançamento correspondente no sistema, provando que o saldo do sistema bate com o saldo do banco.

1. **Abra "Conciliação bancária".** Vá em **Financeiro → Conciliação bancária**. Abra a conciliação de uma **conta**: o sistema fotografa o saldo do livro (movimentos do sistema) e você informa o **saldo do extrato** que veio do banco. A tela mostra, lado a lado, as linhas do extrato e os movimentos de caixa candidatos a casar.:inlineImage[]{src="https://itsm-labdev.cloud4biz.com/portal/docs-img/manual/029-bank-reconciliations.png" alt caption width="3200" height="2000"}
2. **Casar uma linha.** Selecione a linha do extrato e confirme o movimento sugerido pelo sistema (mesmo valor, mesmo parceiro) — ou, quando a sugestão não bate, escolha manualmente outro movimento. Ao confirmar, a linha fica **classificada** e a conta no sistema passa a **paga** (ou **recebida**).
3. **Classifique todas e feche.** Continue casando linha a linha até que nenhuma fique **a classificar**. Só é possível **fechar** a conciliação quando **todas as linhas estão classificadas** e o **saldo do sistema bate exatamente com o saldo do extrato** — uma linha sem par ou saldos divergentes **bloqueiam o fechamento**. Ao fechar, a conciliação fica **conciliada** e os lançamentos contábeis são gerados automaticamente.

### Encontro de contas

Se um parceiro é ao mesmo tempo cliente (deve dinheiro a você) e fornecedor (você deve dinheiro a ele), você pode compensar os valores sem movimentar caixa — é o *encontro de contas*.

1. **Abra a conta a pagar do parceiro.** Em **Financeiro → Documentos**, abra a conta a pagar do parceiro que também é cliente e clique em "Encontro de contas".
2. **Selecione as contas a receber a compensar.** O sistema sugere as contas a receber em aberto do mesmo parceiro. Marque as que entram na compensação.
3. **Confirme.** Os valores são compensados: a menor conta zera e a maior fica com a diferença (ex.: pagar R$ 3.000,00 e receber R$ 5.000,00 deixa R$ 2.000,00 a receber). Um lançamento contábil cruzado registra a baixa dos dois lados.

### Importar contas a pagar eletrônicas (DDA)

O DDA (Débito Direto Autorizado) traz para o sistema os boletos que o banco já disponibilizou eletronicamente em nome da empresa, para que sejam conciliados com as contas a pagar.

1. **Abra o bloco DDA.** Em **Financeiro → Importar extrato**, localize o bloco **DDA**.
2. **Lance a entrada.** Informe o **código de barras**, o **valor** e o **vencimento** do débito autorizado e clique em **Importar DDA**.
3. **Entenda a conciliação.** O lançamento DDA entra na lista e **concilia** com uma conta a pagar já existente — ele nunca baixa o título sozinho, apenas o casa com o pagável correspondente.
4. **Concilie à mão o que a importação não reconheceu.** Ao importar, o sistema **tenta casar sozinho**: se o lançamento traz o fornecedor e existe uma conta a pagar aberta dele que sirva, o DDA já entra **Conciliado**. O que ele não reconhece fica **Pendente** — e aí é com você. Use **"Conciliar"** na linha, escolha o **título a pagar** correspondente e confirme; o lançamento passa a **Conciliado** e só então o botão **Pagar** aparece.
   - **Pendente não é para ficar pendente.** Até 2026-08-03 a única ação disponível numa linha pendente era **Ignorar**: uma cobrança que o banco mandou e o sistema não reconheceu só podia ser descartada.
   - Conciliar exige a permissão de **gerir importação bancária**. Sem ela a linha aparece sem ação nenhuma — nem conciliar, nem ignorar, nem pagar.
5. **Descarte o que não se aplica.** Para um DDA que não corresponde a nenhum título, use **Ignorar**.

### Antecipar pagamentos e recebimentos com desconto

Um título pode ser liquidado antes do vencimento aplicando um desconto financeiro calculado por taxa.

1. **Abra a tela.** Em **Financeiro → Encontro de contas e antecipação**, use o bloco **Antecipação**.
2. **Escolha o título.** Selecione a conta a pagar (ou a receber) que será liquidada antes do vencimento.
3. **Informe a taxa.** Digite a **taxa de desconto**; o sistema calcula o desconto proporcional e o contabiliza na conta contábil de desconto financeiro adequada.
4. **Confirme.** O título é baixado pelo valor com desconto e o desconto financeiro fica registrado.

### Bloquear datas de pagamento

Datas específicas (feriados, dias de fechamento) podem ser impedidas de receber pagamentos.

1. **Abra a tela.** Em **Financeiro → Datas bloqueadas para pagamento**.
2. **Registre a data.** Informe a **data** que não pode receber pagamentos e um **motivo** opcional; clique em **Adicionar**.
3. **Efeito.** A data passa a constar na lista de bloqueios; ordens de pagamento e baixas programadas para ela são impedidas.
4. **Liberar.** Para desbloquear, remova a data da lista.

### Controlar cheques (talão, emissão e caução)

O sistema controla a numeração dos cheques por talão, emite o cheque e acompanha sua situação, incluindo cheques caucionados.

1. **Abra os cheques.** No menu **Financeiro → Cheques**.
2. **Cadastre o talão.** Informe a **conta bancária** e a **faixa de numeração** — o sistema passa a controlar a numeração sequencial dos cheques.
3. **Emita um cheque.** Escolha a conta, o **valor** e o favorecido; o sistema gera o cheque com o próximo número disponível e permite imprimir o comprovante (PDF).
4. **Acompanhe a situação.** Cada cheque exibe seu estado — **emitido**, **em carteira**, **custódia**, **caucionado**, **compensado** ou **devolvido**. Para um **cheque caucionado**, registre a situação **Caucionado**; para dar entrada de um cheque recebido, use **Receber cheque**.

### Fechamento de caixa

1. No menu **Financeiro → Fechamento de caixa** (rota /cash-closings), selecione o **caixa/conta** e o **período** a fechar.
2. Confira os movimentos do período (entradas e saídas) e o **saldo apurado**.
3. Clique em **Fechar**. O sistema consolida o caixa; quando há vários caixas, apresenta também o **fechamento consolidado**, somando todos os caixas do período.

### Fluxo de caixa projetado

1. No menu **Financeiro → Fluxo de caixa** (rota /cash-forecast), o sistema projeta o **saldo por período** — saldo atual mais recebimentos previstos, menos pagamentos previstos — organizado por **cenário**.
2. Ajuste a **granularidade do período** para acompanhar a projeção em visão **diária, semanal ou mensal**, ou por um intervalo específico.
3. Use o **gráfico** e a **tabela de detalhamento por período** para antecipar faltas ou sobras de caixa e programar a movimentação financeira.

### Fluxo de caixa projetado (visões por período)

Na tela de **Fluxo de caixa** (/cash-forecast), alterne a granularidade do período para consultar a projeção em visão **diária, semanal, mensal** ou por **intervalo específico** de datas, conforme a necessidade de acompanhamento.

### Fundos fixos (caixa pequeno)

1. No menu **Financeiro → Fundo fixo** (rota /petty-cash), clique em **Novo fundo** e informe o **valor do fundo** e o **responsável**.
2. Registre os **desembolsos** (pagamentos miúdos do dia a dia) à medida que ocorrem — o saldo do fundo cai a cada desembolso.
3. Quando o saldo baixa, use **Recompor** para devolver o fundo ao valor original, gerando o título de reposição correspondente.

### Contratos de captação (mútuo e empréstimo)

1. No menu **Financeiro → Contratos de captação** (rota /funding-contracts), clique em **Novo contrato** e escolha o **tipo** (mútuo ou empréstimo).
2. Informe a **contraparte**, o **valor principal**, a **taxa de juros**, o **IOF** (quando aplicável) e o **plano de amortização/parcelas**, vinculando o contrato ao **plano de contas**.
3. Registre as **entradas de recursos**, os **pagamentos/amortizações** e deixe o sistema apropriar periodicamente **juros e IOF**.
4. Acompanhe o **saldo devedor** e as **apropriações mensais** na ficha do contrato e na **Tesouraria** (apropriação por competência).

### Aplicações financeiras

1. No menu **Financeiro → Aplicações** (rota /investments), cadastre a aplicação escolhendo a **modalidade** (CDI, CDB, fundo de investimento, poupança, títulos públicos, hedge, etc.).
2. Informe a **conta de aplicação**, o **valor aplicado** e as **garantias** vinculadas à operação, quando houver.
3. Controle os **compromissos e resgates** inerentes à aplicação e acompanhe os **rendimentos** apropriados por competência na Tesouraria.

### Registrar um contrato de captação (mútuo ou empréstimo)

Contratos de captação são as operações em que a empresa toma recursos: contratos de **mútuo** entre partes e **empréstimos** bancários, entre outras modalidades. Cada contrato é cadastrado com o valor tomado, a taxa e o plano de amortização.

1. **Abra "Contratos de captação".** No menu lateral, vá em **Financeiro → Contratos de captação** (rota /funding-contracts). A tela lista os contratos existentes com **Número**, **Modalidade**, **Contraparte**, **Principal**, **Taxa** e **Situação** (rascunho, ativo, liquidado ou cancelado). Use os filtros **Modalidade** e **Situação** no topo da lista para focar num grupo de contratos, e "Limpar filtros" para voltar à lista completa.
2. **Crie um contrato.** Clique em **Novo contrato de captação**. No formulário, preencha:

- **Número** — identificação do contrato (obrigatório).
- **Modalidade** — escolha entre **Empréstimo** (LOAN), **Mútuo** (MUTUAL), **Capital de giro** (WORKING\_CAPITAL), **CCB**, **Conta garantida** (SECURED\_ACCOUNT) e **Leasing**. Para um contrato de mútuo, escolha **Mútuo**; para um empréstimo bancário, escolha **Empréstimo**.
- **Contraparte** — o credor da operação (banco ou parte do mútuo).
- **Principal** — o valor tomado (obrigatório).
- **Data do contrato** e **Primeiro vencimento** — datas que servem de base para o cronograma.

3. **Defina a taxa de juros.** No campo **Tipo de taxa**, escolha:

- **Fixa** — informe a **Taxa de juros (% a.m.)** diretamente.
- **Flutuante** — escolha um **Índice** da tabela de índices da tesouraria (SELIC, CDI, IPCA, etc.) e informe o **Spread (% a.m.)** que se soma ao índice.

:::BlockQuote
**Confira a taxa EFETIVA na ficha do contrato.** A lista mostra a taxa **contratada** — num pós-fixado, algo como "CDI + 2%", que não diz quanto se está pagando a menos que você saiba a cotação do dia. O card **"Taxa efetiva"**, na ficha, mostra os dois lado a lado: a contratada e **a que ela resolve na data** (a cotação do índice em vigor mais o spread, ou a taxa fixa). Deixe a data em branco para hoje.
:::

:::BlockQuote
Se o índice **não tiver cotação** para a data pedida, o card **avisa** em vez de mostrar um traço: a tabela de amortização é calculada por essa taxa, então um contrato cujo índice não resolve produz um cronograma que o sistema não conseguiu precificar. As cotações se mantêm na tabela de índices da tesouraria.
:::

1. **Complete os parâmetros da operação.** Ainda no formulário, informe:

- **Amortização** — o método de cálculo das parcelas: **PRICE** (parcelas iguais), **SAC** (amortização constante) ou **SACRE**.
- **Carência (meses)** — quantos meses de carência antes de começar a amortizar.
- **IOF** — o valor do imposto sobre operações financeiras da captação, quando aplicável (típico dos contratos de mútuo).
- **Taxa** — outras taxas/tarifas da operação. Clique em **Salvar**. O contrato nasce na situação **rascunho** e ainda pode ser editado à vontade.

### Gerar o cronograma de amortização (parcelas com juros e IOF)

O cronograma transforma o valor principal em parcelas com **principal**, **juros** e **IOF** calculados pelo método escolhido, e é ele que amarra o contrato ao plano de contas e gera as contas a pagar.

1. **Abra o contrato.** Na lista de **Contratos de captação**, clique no ícone de edição da linha do contrato para abrir a ficha. No topo, um selo mostra a situação atual (rascunho/ativo). Abaixo do formulário aparece o bloco **Cronograma de amortização**, com o aviso de que gerar o cronograma transforma cada parcela em conta a pagar e ativa o contrato.
2. **Gere o cronograma (contrato em rascunho).** Com o contrato ainda em **rascunho**, preencha no bloco:

- **Credor (parceiro)** — o parceiro cadastrado que é a contraparte da operação.
- **Categoria** — a categoria financeira que vincula as parcelas ao **plano de contas**, para que os juros e a amortização caiam na conta contábil certa.
- **Parcelas** — o número de parcelas (padrão 12). Clique em **Gerar cronograma**.

3. **Confira as parcelas geradas.** O sistema monta a tabela do cronograma, uma linha por parcela, com **#**, **Vencimento**, **Principal**, **Juros**, **IOF**, **Prazo** (curto ou longo, conforme o vencimento caia dentro ou fora dos próximos 12 meses) e **Situação** de pagamento. Cada parcela vira automaticamente uma **conta a pagar** ligada ao credor e à categoria escolhida — é assim que as entradas de recursos do empréstimo geram as parcelas correspondentes com seus juros e taxas. Ao gerar, o contrato passa de **rascunho** para **ativo** e não pode mais ter o cronograma regerado (a ficha exibe "Cronograma já gerado — o contrato está ativo").
4. **Controle pagamentos e amortizações.** Cada parcela do cronograma é uma conta a pagar comum: liquide-a na tela de **Documentos** ([Financeiro — títulos (contas a pagar e a receber)](docId\:D4kuGidayU2GQ-hMhF_T-)) na data do vencimento. A coluna **Situação** de cada linha do cronograma acompanha esse pagamento (em aberto, parcial, liquidada ou cancelada), dando a visão consolidada da amortização do contrato.
5. **Aproprie juros e IOF periodicamente.** O lançamento automático e periódico dos juros acontece na tela de **Tesouraria** (**Financeiro → Tesouraria**), pela **apropriação mensal por competência**: informe o mês e clique em "Apropriar" para que o sistema calcule os juros do período sobre o saldo devedor do contrato e os registre, sem digitação manual. O saldo devedor e as apropriações acumuladas ficam visíveis na própria Tesouraria, por contrato.

### Cadastrar uma aplicação financeira e suas garantias

As aplicações financeiras cobrem as diversas modalidades em que a empresa aplica sobras de caixa — de renda fixa a fundos e títulos públicos — registrando também as garantias vinculadas à operação.

1. **Abra "Aplicações".** No menu lateral, vá em **Financeiro → Aplicações** (rota /investments). A tela tem, de cima para baixo, o formulário **Nova aplicação**, a lista **Aplicações financeiras** e o bloco **Movimentos**.
2. **Cadastre a aplicação.** No formulário **Nova aplicação**, preencha:
   - **Número** — identificação da aplicação.
   - **Modalidade** — escolha entre **CDB**, **RDB**, **CDI**, **Título público** (PUBLIC\_BOND), **Fundo** (FUND), **Poupança** (SAVINGS) e **Hedge**. Essa lista cobre CDI, títulos do Banco Central, CDBs, fundos de investimento, poupança e operações de hedge.
   - **Instituição** — o banco ou gestora onde o recurso está aplicado.
   - **Data de aplicação** — quando o recurso foi aplicado.
   - **Valor aplicado** — o montante aplicado (obrigatório).
   - **Cotas (fundo)** — a quantidade de cotas, quando a modalidade é um fundo.
   - **Garantia** — a referência da garantia vinculada à operação, quando houver. Clique em **Salvar**. A aplicação entra na lista com a situação **ativa** e o sistema abre internamente a conta de tesouraria correspondente, já com o valor aplicado.
3. **Consulte as aplicações.** A lista **Aplicações financeiras** mostra **Número**, **Modalidade**, **Instituição**, **Valor aplicado** e **Situação** (ativa ou resgatada) de cada aplicação cadastrada. É o painel para acompanhar quais operações estão em aberto.

### Registrar aportes, resgates e rendimentos da aplicação

Depois de cadastrada, cada aplicação tem seus compromissos (aportes) e resgates controlados pelo bloco **Movimentos**, que também registra os rendimentos creditados.

1. **Selecione a aplicação.** No bloco **Movimentos** (parte inferior da tela de Aplicações), escolha a aplicação no campo **Aplicação**. O formulário de lançamento e o histórico de movimentos daquela aplicação passam a aparecer.
2. **Lance um movimento.** No campo **Tipo**, escolha:
   - **Aporte** — reforça o valor aplicado; informe o **Valor** e, para fundos, as **Cotas**.
   - **Resgate** — retira recursos da aplicação; informe o **Valor**, as **Cotas** (para fundos) e, quando houver, os valores de **IR** e **IOF** retidos no resgate. O resgate não pode exceder o saldo da aplicação, e quando o saldo zera a aplicação passa a **resgatada**.
   - **Rendimento** — credita o rendimento apropriado; informe apenas o **Valor**. Informe a **Data** e clique em **Registrar**.
3. **Acompanhe o histórico.** A tabela de movimentos lista cada lançamento com **Data**, **Tipo**, **Valor**, **Cotas** e **IR**, dando o controle dos compromissos e resgates inerentes à aplicação. Os rendimentos também podem ser apropriados por competência na tela de **Tesouraria**, junto com os juros das captações.

### Fluxo de caixa por dimensão (centro de resultado, unidade e empresa)

Além da projeção por período, a mesma tela de fluxo de caixa monta automaticamente o **caixa realizado** segmentado por dimensão, a partir de cada movimentação financeira lançada pelos usuários — sem nenhuma digitação extra.

1. Abra **Financeiro → Fluxo de caixa** (rota /cash-forecast) e role até o quadro **Fluxo de caixa por dimensão**, no rodapé da tela, abaixo do gráfico de projeção e da tabela por período.
2. No campo **Eixo**, escolha como quer olhar a movimentação: **Centro de resultado**, **Unidade de negócio** ou **Empresa**. O quadro é remontado na hora — ele lê cada movimento financeiro já registrado e soma por conta própria.
3. Leia a tabela: a coluna **Dimensão** mostra o centro de resultado, a unidade de negócio ou a empresa, e a coluna **Caixa líquido** mostra o resultado do período naquela dimensão (entradas menos saídas). Movimentos que não têm a dimensão preenchida aparecem agrupados na linha **Não classificado**.
4. Confira a linha **Consolidado**, no rodapé da tabela: ela soma o caixa líquido de todas as dimensões e é o total que deve bater com o caixa da empresa no período.
5. Troque o **Eixo** para comparar exatamente a mesma movimentação sob os três recortes — por centro de resultado, por unidade de negócio e por empresa — sem sair da tela. Quando ainda não há movimento financeiro no período, o quadro exibe o aviso de que não há movimentos de caixa.

### Definir quem cobra quem (carteiras de cobrança)

A tela **Financeiro → Carteiras de cobrança** (rota /collection-wallet) sempre mostrou a fila de cada cobrador. O que faltava era dizer **de antemão** quem cobra cada cliente: até 2026-08-04 a varredura da régua criava as ações **sem dono**, todas num monte comum, e alguém distribuía à mão, ação por ação. O cartão **Definição das carteiras**, no rodapé dessa tela, fecha isso.

1. **Crie a carteira.** No cartão **Definição das carteiras**, informe um **nome** (por exemplo, Grandes contas — Sul), escolha o **cobrador** responsável e mantenha **Ativa** marcada. Clique em **Adicionar**.
2. **Diga quais clientes são dela.** Na linha da carteira, clique em **Clientes**. Use o seletor **Incluir cliente** e adicione um por um.
   - **Um cliente pertence a no máximo uma carteira.** Se você tentar incluir alguém que já está em outra, o sistema recusa e **diz em qual** — "Este cliente já está na carteira X. Retire-o de lá primeiro". A exclusividade é o que faz a lista ser de fato *dividida* por usuário: com carteiras sobrepostas, dois cobradores teriam o mesmo devedor.
3. **Deixe a régua rodar.** Daí em diante, toda ação de cobrança gerada para um título vencido daquele cliente **nasce com o cobrador da carteira** e já aparece na fila dele. Cliente que não está em carteira nenhuma continua exatamente como antes: a ação nasce sem dono, no **Pool não atribuído**.
4. **Reatribuir uma ação continua valendo.** A carteira define o **padrão**, não uma regra: na tabela de ações, o seletor da coluna do responsável continua movendo uma ação específica para outra pessoa — férias, uma negociação que o gerente assume.

:::BlockQuote
💡 **Desligar a carteira não apaga a lista de clientes.** Desmarcar **Ativa** faz a carteira **parar de alimentar** a varredura — as ações novas daqueles clientes voltam ao monte comum —, mas os clientes continuam vinculados. É o que se usa quando o cobrador sai de férias ou deixa a equipe: religar depois não exige redigitar ninguém.
:::

:::BlockQuote
⚠️ **As ações já criadas não mudam de dono.** Tirar um cliente da carteira, ou trocá-lo de carteira, vale para as ações **futuras**. As que já existem ficam com quem as recebeu — são trabalho em curso, e tirá-las das mãos de alguém no meio de uma negociação seria pior que a inconsistência.
:::

## Verificação

***

Você sabe que funcionou quando:

- O painel de **Caixa e banco** e o de **Tesouraria** mostram o saldo consolidado esperado após os movimentos do dia.
- A ordem de pagamento **liquidada** exibe todas as contas vinculadas com situação **paga**, e o total da ordem confere com a soma das contas.
- A remessa CNAB gerada aparece na lista com a conta e o layout corretos, e o retorno importado atualizou a situação dos documentos.
- Depois de importar o extrato e classificar todas as linhas, a conciliação **fecha** (fica "conciliada"): o saldo do sistema **bate** com o saldo do extrato e não sobra nenhuma linha **a classificar**.
- O encontro de contas reduziu o valor em aberto do parceiro corretamente (ex.: R$ 5.000,00 a receber menos R$ 3.000,00 a pagar = R$ 2.000,00 a receber).
- O razão contábil ([Contabilidade](docId:08cbTyrT0WXBp4ymvrog_)) mostra os lançamentos gerados pela conciliação, pela ordem de pagamento liquidada e pelo encontro de contas.

## Erros comuns

***

- **Arquivo de extrato não é lido** — o formato precisa ser **OFX** (o que o banco disponibiliza para download). Uma planilha CSV não é um extrato válido aqui.
- **Arquivo CNAB rejeitado** — layout ou banco incompatível. Confira: 240 ou 400 posições, banco cadastrado na página [Financeiro — cadastros de apoio](docId\:yTzjjyyML1B_60VgwDT09) e o layout exato que o seu banco exige.
- **Sugestão de conciliação errada** — a sugestão é apenas um atalho. Quando o valor ou o parceiro não batem, escolha o lançamento correto manualmente antes de confirmar.
- **Não consigo baixar a ordem de pagamento** — a ordem precisa estar **autorizada** (não em rascunho) para ser baixada. Se o valor passou da sua alçada, ela fica pendente de aprovação antes de poder ser autorizada.
- **Conta de destino de outro fornecedor** — a ordem de pagamento só aceita uma **conta bancária do próprio fornecedor** do título. Tentar apontar a conta de outro fornecedor é **rejeitado**. Ao lançar o pagável, a conta primária do fornecedor já vem preenchida; troque apenas por outra conta do **mesmo** fornecedor.
- **Retorno CNAB sem par** — quando o arquivo de retorno traz uma ocorrência que não casa com nenhum título (por nosso número), ela vai para uma **fila manual** (não baixa nada sozinha). Valor divergente entre retorno e título também é sinalizado em vez de baixar. **Fila cheia depois de importar um retorno não é sinal de erro:** o banco devolve uma linha por evento do título, e só as de liquidação com valor exato baixam sozinhas — ver o passo 13.
- **Conta bancária com título em aberto** — não é possível **inativar** uma conta bancária que ainda tenha título em aberto vinculado; liquide ou cancele os títulos antes.
- **Correção com taxa desatualizada** — se a atualização de um valor veio menor/maior do que o esperado, confira em **Índices** se a taxa do mês vigente já foi lançada.


[title] Configurações e administração
[path] Aplicações/Agility/Sistema/

:::BlockQuote
Administre o estado da integração de IA no Workspace e ajuste a identidade, o acesso, o ciclo de vida e as datas de um Projeto.
:::

:::hint{type="info"}
**Pré-requisito:&#x20;**

Para a configuração do Workspace, a sessão precisa ter a capacidade de administrador. Para editar a identidade de um Projeto, a sessão precisa ter a capacidade de edição e ser responsável pelo Projeto ou dona do Workspace.
:::

***

Configurações aparece em dois níveis diferentes. A opção Configurações da barra lateral do Workspace abre uma página administrativa do próprio Workspace, cujo conteúdo atual é o cartão de IA. Já a aba Configurações dentro de um Projeto abre Configurações do projeto e edita a identidade persistida desse Projeto. Não confunda os dois caminhos: o primeiro consulta o estado da integração de IA do tenant; o segundo não configura a IA e não altera o código imutável do Projeto.

Também existe uma rota chamada operating-directories.tsx no código. Ela resolve para a tela de diretório de Times (WorkspaceTeamsPage), com busca e criação de times conforme a permissão de edição; não é uma tela adicional de administração ou de configurações. O diretório deve ser usado no item Times e continua relacionado ao cadastro de equipes, não a esta seção de configurações.

***

### Passo a passo

::::WorkflowBlock
:::WorkflowBlockItem
**Abrir Configurações do Workspace**

Com o Workspace selecionado, clique em Configurações no grupo Sistema da barra lateral. A página apresenta o título Configurações e o subtítulo Permissões e integrações administrativas deste workspace. No código, esse caminho é /workspaces/\:workspaceId/settings e é registrado como WorkspaceSettingsPage; portanto, ele não é um placeholder sem rota.
:::

:::WorkflowBlockItem
**Verificar a permissão administrativa**

O conteúdo depende da capacidade admin da sessão. Um administrador vê o cartão IA e pode consultar o estado. Uma sessão sem essa capacidade vê o cartão Acesso restrito com a mensagem de que somente administradores acessam as configurações do workspace; não há edição parcial nem exposição da chave para usuários comuns.
:::

:::WorkflowBlockItem
**Ler o cartão de IA**

No cartão IA, confira a descrição Provedor de linguagem por tenant via resource Tenancit agility.ai, com fallback no ambiente da instalação. A interface informa explicitamente que a chave nunca é exibida. O campo Estado começa como Carregando estado da integração… e depois apresenta Não configurado, Configurado via resource Tenancit ou Configurado via ambiente da instalação, podendo incluir o modelo retornado.
:::

:::WorkflowBlockItem
**Interpretar os dados técnicos exibidos**

Quando a IA estiver configurada, o cartão pode mostrar Dialeto (o padrão de API retornado) e Endpoint. O endpoint é exibido para o administrador diagnosticar a conexão, enquanto a chave permanece oculta. Se não estiver configurada, esses campos não são apresentados e o Estado permanece Não configurado.
:::

:::WorkflowBlockItem
**Testar a conexão**

Clique em Testar conexão para executar a verificação do provedor. Durante a chamada, o botão muda para Testando…. Em uma resposta positiva, aparece Conexão ok, eventualmente com latência em milissegundos e modelo. No ambiente usado neste manual, a IA está Não configurado e o teste retorna Falha - invalid\_config; essa mensagem confirma o diagnóstico de configuração inválida, não uma falha do catálogo de integrações.
:::

:::WorkflowBlockItem
**Reagir a indisponibilidade ou falta de permissão**

Se o control plane do tenant estiver fora do ar, o cartão informa Indisponível (control plane de tenant fora do ar). Se a sessão não tiver permissão para consultar ou testar, informa Sem permissão para consultar o estado da IA ou Sem permissão para testar a conexão. Em ambos os casos, corrija a disponibilidade ou a permissão no ambiente administrativo; não há campo local para digitar uma chave nesta tela.
:::

:::WorkflowBlockItem
**Abrir as Configurações do Projeto**

Entre em um Projeto populado, como ERP Financeiro (código ERP-FIN), e clique em Configurações na navegação do Projeto. O cabeçalho identifica a tela como Configurações e informa Forma de trabalho, capacidades e permissões do Projeto. No conteúdo, o título é Configurações do projeto e o texto explica que os dados persistidos são gerenciados ali, enquanto as capacidades da barra lateral vêm do servidor.
:::

:::WorkflowBlockItem
**Conferir o cartão Identidade**

O cartão Identidade reúne os dados que podem ser atualizados. Código é exibido em um campo somente leitura e é imutável para preservar as referências já criadas. Nome é obrigatório. Responsável é um seletor de membros do Workspace e também é obrigatório. Descrição usa um editor de texto rico com negrito, itálico, tachado, lista com marcadores e lista numerada.
:::

:::WorkflowBlockItem
**Ajustar acesso e status**

Em Acesso inicial, escolha Workspace para permitir que qualquer membro veja e participe, ou a opção restrita indicada pelo formulário para limitar o acesso. Em Status, escolha somente uma transição aceita pelo ciclo de vida atual. A própria ajuda avisa que as transições não podem voltar para uma etapa anterior; se o status atual não oferecer duas opções, o seletor permanece desabilitado.
:::

:::WorkflowBlockItem
**Definir a janela de datas**

Preencha Início e Término usando os seletores de data. O campo Término recebe a data de Início como limite mínimo, e o salvamento também valida a regra no cliente e no servidor: a data de término não pode ser anterior à data de início. Deixe o campo vazio quando o Projeto não tiver uma data correspondente, em vez de usar uma data fictícia
:::

:::WorkflowBlockItem
**Salvar a identidade**

Depois de modificar um ou mais valores, clique em Salvar identidade. O botão só fica ativo quando há alterações e muda para Salvando… durante a chamada. Ao concluir, o shell do Projeto é recarregado e aparece Identidade salva. Se a sessão for somente leitura, os valores continuam visíveis, mas o editor e o botão não permitem alteração.
:::

:::WorkflowBlockItem
**Entender o diretório operacional**

O arquivo de rota workspaces.$workspaceId.operating-directories.tsx não cria um terceiro painel de configurações: ele exporta WorkspaceTeamsPage. A tela de Times carrega os times do Workspace, permite pesquisar por nome e oferece Novo time apenas para quem tem capacidade de edição; use-a para administrar equipes operacionais e volte a Configurações para as duas superfícies descritas acima.
:::
::::

![](https://itsm-labdev.cloud4biz.com/agility-v2/docs/screens/10-configuracoes-ia.webp "Configurações do Workspace Portal de Serviços com o cartão de IA, estado Não configurado e resultado Falha - invalid_config após testar a conexão")

![](https://itsm-labdev.cloud4biz.com/agility-v2/docs/screens/10-configuracoes-projeto.webp "Configurações do projeto ERP Financeiro com o cartão Identidade preenchido, código imutável, responsável, descrição, acesso, status e datas")

:::hint{type="success"}
:FontAwesome[]{icon="fa-solid fa-check"} **Verificação**

- Em Configurações do Workspace, um administrador vê o cartão IA e o Estado retornado pelo tenant; uma sessão sem admin recebe Acesso restrito.
- O teste de conexão apresenta um resultado observável (Conexão ok com latência/modelo ou Falha com o tipo do erro); no ambiente de demonstração, a configuração não existente resulta em Falha - invalid\_config.
- Em Configurações do projeto, Código permanece desabilitado e os demais dados de identidade ficam preenchidos com os valores persistidos do Projeto.
- Após uma alteração válida, Salvar identidade fica ativo, o formulário mostra Identidade salva e a navegação do Projeto passa a refletir os dados recarregados.
- O diretório operacional de Times é reconhecido como a tela de equipes, com busca e Novo time condicionado à permissão de edição, e não como outra tela de configurações.
:::

:::hint{type="warning"}
:FontAwesome[]{icon="fa-solid fa-triangle-exclamation"} **Erros comuns**

**Configurações do Workspace mostra Acesso restrito**

A página exige a capacidade admin para consultar o estado da IA. Use uma sessão administrativa para diagnosticar a integração; a implementação não oferece um atalho para elevar a permissão dentro da própria tela.

**O estado da IA fica como Não configurado**

Esse estado indica que não foi encontrado resource Tenancit nem configuração de ambiente de instalação. A tela não coleta a chave: configure o provedor no ambiente administrativo e volte para consultar o estado novamente.

**O teste retorna Falha - invalid\_config**

Verifique o resource agility.ai, o dialeto e o endpoint no control plane/ambiente da instalação. No ambiente de demonstração usado neste manual, esse resultado é esperado porque a IA não está configurada; ele não deve ser descrito como Conexão ok.

**A data de término é rejeitada**

Informe uma data de término igual ou posterior à data de início. O formulário bloqueia a combinação inválida antes da chamada e o servidor também responde com invalid\_date\_range, exibindo A data de término não pode ser anterior à data de início.

**A transição de status não é permitida**

Escolha uma opção oferecida para o status atual. O ciclo de vida é progressivo e não aceita voltar para uma etapa anterior; o servidor pode responder invalid\_status\_transition quando a transição não fizer parte dos destinos aceitos.

**Salvar identidade retorna acesso negado ou conflito**

Somente o responsável pelo Projeto ou o dono do Workspace pode alterar a identidade. Se outra alteração tiver sido salva primeiro, recarregue a página e tente novamente; a tela traduz esses casos como erro de permissão ou conflito.

**O diretório operating-directories não mostra uma configuração administrativa**

Isso é intencional: apesar do nome do arquivo de rota, ele renderiza WorkspaceTeamsPage, o diretório operacional de Times. Procure por Times na barra lateral para cadastrar e pesquisar equipes; não espere encontrar ali o cartão de IA ou o formulário de identidade do Projeto.
:::


[title] Glossário de termos
[path] Aplicações/Agility/

:::BlockQuote
Vocabulário usado ao longo do manual — gestão de projetos, ágil, escalado e financeiro.
:::

:::hint{type="info"}
Termos citados nas seções anteriores, reunidos aqui para consulta rápida. Cada entrada é a definição usada dentro do Agility — em alguns casos (WSJF, ROAM, PI) o termo vem direto do framework SAFe; em outros (Workspace, Portfólio) é vocabulário próprio do produto.
:::

***

### Estrutura organizacional

Workspace — o espaço de colaboração de uma organização: membros, permissões e todo o trabalho vivem dentro dele. Portfólio — conjunto de Programas com objetivos estratégicos em comum, com orçamento e roadmap próprios. Programa — agrupamento de Projetos relacionados, coordenados juntos porque entregam mais valor combinados do que separados. Projeto — o esforço que produz um resultado específico; nasce com um modelo de trabalho (Kanban, Scrum, Tradicional ou SAFe) e é onde tarefas, requisitos, riscos e financeiro realmente vivem. Todos os três níveis (Portfólio/Programa/Projeto) são opcionais entre si — um Projeto pode existir sozinho.

***

### Kanban e execução do dia a dia

Quadro (Board) — a tela onde o time move o trabalho: colunas (lanes) representam etapas do processo, e cartões representam tarefas. WIP (Work in Progress) — limite de quantos cartões podem estar simultaneamente numa coluna, para evitar sobrecarga. Automação (regra) — ação que dispara sozinha quando um cartão entra numa lane (ex.: aprovação obrigatória, limite de WIP). Backlog — lista priorizada de itens de trabalho ainda não iniciados.

***

### Scrum

Sprint — período de tempo fixo (normalmente 1-4 semanas) em que o time se compromete a entregar um conjunto de itens do backlog. Relatório de sprint — o resumo do que foi planejado vs. entregue ao final da sprint.

***

### Projeto tradicional

WBS (Work Breakdown Structure / Estrutura Analítica do Projeto) — decomposição hierárquica do trabalho em pacotes menores. Marco (milestone) — um ponto de controle no cronograma, sem duração própria. Dependência — uma tarefa que só pode começar (ou terminar) depois de outra. Linha de base (baseline) — uma fotografia congelada do cronograma planejado, usada depois para comparar com o realizado.

***

### SAFe (ágil em escala)

ART (Agile Release Train) — o trem: um agrupamento estável de Times que planejam e entregam juntos, em torno de um objetivo comum. PI (Program Increment) — o ciclo de planejamento do ART, tipicamente de 8-12 semanas, dividido em Iterações. Iteração — cada "sprint" dentro de um PI. PI Planning — o evento em que o ART planeja o PI inteiro, com todos os Times. Readiness — checklist de pré-condições para o PI Planning começar bem preparado. Objective (objetivo do PI/time) — o que o Time ou o ART se compromete a entregar no PI, com o valor de negócio esperado. Inspect & Adapt — o workshop de encerramento do PI, onde o trem revisa métricas e ajusta o processo. Épico — a maior unidade de valor no SAFe, grande demais para um PI só. Feature — um fatiamento do épico entregável dentro de um PI; pode ser "habilitadora" (trabalho técnico sem valor direto ao usuário final) ou de negócio. História (story) — o menor incremento de valor, entregável por um Time numa Iteração. WSJF (Weighted Shortest Job First) — fórmula de priorização do SAFe: soma de valor de negócio, criticidade de tempo e redução de risco/oportunidade, dividida pelo tamanho do trabalho — quanto maior o resultado, antes o item deve ser feito. ROAM — categorização de risco do SAFe: Resolvido, Owned (com dono), Aceito ou Mitigado.

***

### Financeiro

Lançamento — um registro de receita, despesa, compra ou apontamento de horas. Contrato — o vínculo comercial com um cliente que baliza faturamento e SLA. Rentabilidade — o resultado financeiro (receita menos custo) de um projeto, cliente ou contrato. Custo previsto vs. realizado — comparação entre o orçamento planejado do projeto/quadro e o que foi efetivamente lançado.

***

### Produtos, releases e times

Produto — um catálogo com objetivos próprios, ao qual releases e features podem se vincular. Release — um pacote de entrega com features associadas, do qual nascem os registros de deploy. DevOps (do release) — os registros de deploy (ambiente, status, link de pipeline/commit) e as métricas de frequência de entrega e lead time. Time — o grupo de pessoas com papéis definidos, vinculado a um Workspace e, opcionalmente, a um ART. Requisito — um item de escopo com origem, prioridade e critério de aceite, rastreável até a(s) tarefa(s) que o implementam.


[title] Untitled
[path] /


[title] Cadastrar Menu
[path] Início Rápido/Como Navegar na Interface do Usuário/

Esta funcionalidade tem por <font color="#3b9f0f">**objetivo permitir ao usuário a configuração dos itens de menu**</font>, de acordo com as suas preferências, disponibilizando ações diversas, como: incluir, alterar e excluir um menu.

Provê melhor usabilidade no acesso aos menus, onde os itens poderão ser organizados conforme a sua necessidade.

## Procedimento

1. Acesse a funcionalidade por meio da navegação no menu principal `Workflow > Cadastros Gerais > Menu`;
2. Preencha os campos disponibilizados;
3. O botão **"Gerar XML"** serve para gerar um arquivo dos menus no formato ".xml";
4. O botã&#x6F;**&#x20;"Atualizar Menus"&#x20;**&#x73;erve para atualizá-los;
5. Ter muito cuidado em relação à execução do botão **"Atualizar Menus"**, pois todas as alterações cadastrais dos menus serão perdidas desde a última vez que houve a geração de XML. Recomenda-se, portanto, a seguinte sequência de execução:
   - ****<font color="#3b9f0f">**1.**</font> botão "**Gerar XML**";
   - <font color="#3b9f0f">**2.** </font>botão "**Atualizar Menus**".
6. Por fim, clique em **"Gravar"**.

## O que Fazer a Seguir

Acesse o menu principal para verificar se o(s) menu(s) foram criado(s).




[title] Grupos
[path] Início Rápido/🌐Gestão de Pessoas/

A página de Grupos exibe uma lista com os grupos do sistema, e permite a criação de novos grupos.&#x20;

Um grupo é uma coleção de usuários do sistema. Para que as funcionalidades de atendimento e solicitação de tickets funcionem corretamente, é necessário que cada usuário tenha um grupo associado a ele. Os grupos combinam o usuário clientes, atendentes ou administradores, e cada grupo possui permissões de acesso diferentes. Um grupo de usuários atendentes é responsável por determinadas tarefas dentro do portfolio oferecido pela empresa. Em outras palavras, se um usuário cliente abrir um chamado de determinada atividade, a solicitação será executada por algum usuário do grupo definido no fluxo.&#x20;

Para acessar a funcionalidade, selecione a aplicação de Gestão de Pessoas no menu de aplicações, depois clique em Grupos no menu de navegação principal.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/kcvZLf22bK53YT1V9QHk-_image.png" size="38" width="246" height="292" position="center" showCaption="false"}

# Grupos

A tela de Grupos exibe uma lista dos grupos cadastrados, com informações divididas em colunas e alguns botões:

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/qSCzcZMPEgaKHOdjRueqs_image.png)

Acima da lista, são exibidos os botões para **Copiar&#x20;**&#x61; lista para a área de transferência, ou exportar a lista em formato **CSV, XLSX&#x20;**&#x6F;u **PDF,** e o botão de **Criar.**

No topo da lista, do lado direito são exibidos os campos para **Pesquisar&#x20;**&#x6E;a lista de grupos.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/EJIIFUn93CO4RfNjXIUzI_image.png)

As colunas da lista de grupos exibem algumas informações sobre cada grupo:

- **Grupo:&#x20;**&#x4E;ome do grupo.
- **Descrição:&#x20;**&#x44;escrição do grupo.
- **Última Modificação:&#x20;**&#x44;ata da última modificação.
- **Ações:&#x20;**&#x42;otões para **Editar&#x20;**&#x61;s informações o&#x75;**&#x20;Excluir&#x20;**&#x67;rupo.

Se houverem muitos grupos cadastrados, a visualização será dividida em páginas. Utilize as setas no fim da página para navegar entre as páginas.

## Criar grupo

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/xys9WLUEyeE2RPx1nJgZD_image.png" size="26" width="91" height="53" position="center" showCaption="false"}

Para criar um novo grupo, clique no botão **+Criar&#x20;**&#x6E;o topo da tela.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/IE1lIZuhLbVzq8vOZ7HO8_image.png" size="50" width="381" height="170" position="center" showCaption="false"}

Inclua um **Nome&#x20;**&#x70;ara o seu grupo, e clique em **Criar&#x20;**&#x70;ara salvar ou **Fechar&#x20;**&#x70;ara cancelar

[title]  18. Onde configurar as integrações com terceiros e a instalação
[path] Aplicações/BSC/

Este capítulo é um guia de consulta rápida: para cada integração com terceiros, mostra **onde** fica cada configuração, na ordem em que deve ser feita, no formato **Menu › Tela › campo**. O detalhe de cada tela, as mensagens de erro e as regras de uso estão nos capítulos do hub de integrações e de mensageria; aqui o foco é o caminho.

O roteiro se repete em todas as integrações: cadastrar a integração no hub com o endereço e a credencial, pedir ao administrador do sistema a aprovação do servidor na **lista de saída**, **Testar**, e só então ligar a integração ao que a usa (canais de área, alertas, mensagens ou conectores).

A última seção reúne os arquivos e as variáveis da instalação do Bússola/BSC no modo interno (Docker Compose) e em nuvem (Kubernetes). Valores secretos nunca aparecem neste manual: onde houver um segredo, ele está indicado como \<valor>.

***

## <font color="#15803D">18.1 Onde configurar o WhatsApp</font>

ID BSC-CFG-01

### <font color="#15803D">Para que serve</font>

O WhatsApp leva os alertas pessoais do Bússola/BSC ao celular de cada pessoa que confirmou o número. O envio é feito pelo provedor contratado, em nome da Empresa Exemplo S.A., e a configuração passa por seis telas: o cadastro da conta no hub, a lista de saída, o endereço dos avisos entregue ao provedor, a mensagem com o modelo aprovado, a regra de alertas e, por fim, o consentimento de cada pessoa.

Só pode haver uma integração de WhatsApp ativa por ambiente.

**Quem usa:** Analista de Integração de Dados; Administrador do sistema; Gestor de Desempenho (escritório de estratégia); Responsável por ação/área.

### <font color="#15803D">Passo a passo</font>

1. Obtenha com o provedor contratado: a URL base do serviço, o identificador do número, o identificador da conta, o token de acesso, o App Secret, o número de WhatsApp da empresa e o nome e o idioma do modelo aprovado dos alertas.
2. Integrações › Integrações › **Nova integração** › **WhatsApp** › **Identificação**: informe Nome (por exemplo, "WhatsApp — alertas (produção)"), Código, Objetivo, Ambiente e responsáveis.
3. Mesma tela › **Endereço**: preencha **URL base** (o endereço do provedor), **Identificador do número (phone number id)**, **Identificador da conta (WABA id)**, **Número de WhatsApp da empresa** e **Nome da empresa no consentimento** (o nome do remetente que aparece no texto de autorização, por exemplo Empresa Exemplo S.A.).
4. Mesma tela › **Autenticação**: preencha **Token de acesso**, **App Secret (assinatura dos avisos)** e **Token de verificação do webhook** (uma palavra que você escolhe). Só altere **Cabeçalho de autenticação** e **Esquema da autenticação** se o provedor pedir.
5. Mesma tela › **Avançado**: confira **Template aprovado dos alertas**, **Idioma do template** e **Teto diário de envios (0 = sem teto)**; clique em **Salvar**.
6. Início › Lista de saída das integrações › **Aprovar destino** (administrador do sistema): informe o **Servidor** do provedor, Protocolo **HTTPS**, porta 443, e a **Justificativa**.
7. Integrações › Integrações › abra a integração de WhatsApp › **Testar**. O teste lê o cadastro do número no provedor e não envia mensagem.
8. Integrações › Canais de área › quadro **WhatsApp da empresa** › copie o **Endereço dos avisos** e entregue-o ao provedor contratado junto com o token de verificação.
9. Início › Mensagens institucionais › abra a variação do tipo de aviso com **Canal** = **WhatsApp** e confira o nome e o idioma do modelo aprovado e o preenchimento de cada espaço numerado.
10. Gestão por indicadores › Alertas e mensagens › em cada tipo de registro, na coluna **Pessoas**, marque **WhatsApp** nas famílias de aviso desejadas (Registro novo, Atraso, Comentário, Mudança).
11. Início › Preferências de notificação › **Meu WhatsApp** (cada pessoa): **Confirmar pelo WhatsApp**, enviar o código pelo próprio celular, **Já enviei — verificar de novo** e **Ligar para os alertas do Bússola/BSC** (consentimento).

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/-ZC1RyG-92OeOTqiwjPhK_image.png" size="62" isUploading="false" width="620" height="646" darkWidth="620" darkHeight="646" showCaption="false"}

Figura 196 — Integrações › Nova integração › WhatsApp: endereço do provedor, identificadores do número e da conta, token, App Secret e token de verificação.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/JQ-JRsa-zgiK65opVgQhI_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 197 — Início › Lista de saída das integrações › Aprovar destino: servidor, protocolo, porta e justificativa.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/EdECacO52wgC9ni9MLC4j_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 198 — Integrações › Canais de área › WhatsApp da empresa: o endereço dos avisos a entregar ao provedor contratado.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/Mcvuj7M6ixurRqOquku8i_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 199 — Início › Mensagens institucionais: o modelo da mensagem, com as variantes por canal.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/zqgc1O-GVCdRdmkb8A13q_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 200 — Gestão por indicadores › Alertas e mensagens: marcar WhatsApp em cada família de aviso.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/52AVhW9F6iVcTZv0FD-a-_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 201 — Início › Preferências de notificação › Meu WhatsApp: cada pessoa confirma o número e o consentimento.

### <font color="#15803D">Observações</font>

- Token de acesso, App Secret e token de verificação ficam cifrados e nunca voltam à tela; a ficha mostra só "Definido em … por …".
- Enquanto o token de acesso não for salvo, o **Testar** responde que a integração aguarda credenciais e nada é enviado.
- Sem o App Secret, nenhum aviso do provedor é aceito e ninguém consegue confirmar o número; sem o **Número de WhatsApp da empresa**, também não.
- Se o quadro **WhatsApp da empresa** disser que o endereço público da instalação não foi configurado, peça à equipe de operação; sem ele não há endereço dos avisos para entregar ao provedor.
- Só chega por WhatsApp o aviso que tem as três condições: WhatsApp marcado em **Alertas e mensagens**, variação de WhatsApp com modelo aprovado em **Mensagens institucionais** e pessoa com número confirmado e alertas ligados.
- Registro sigiloso nunca é enviado por WhatsApp. Os envios que não saíram aparecem em **Início › Falhas de envio**, com o motivo.

***

## <font color="#15803D">18.2 Onde configurar o Microsoft Teams e o Discord</font>

ID BSC-CFG-02

### <font color="#15803D">Para que serve</font>

O Microsoft Teams e o Discord recebem os avisos do Bússola/BSC num canal compartilhado de cada área. Cada canal é uma integração do hub com a **URL do webhook** gerada no próprio Teams (fluxo do Workflows) ou no Discord (webhook do canal); depois de testada, a integração é ligada a uma unidade em **Canais de área** e escolhida nas regras de **Alertas e mensagens**.

**Quem usa:** Analista de Integração de Dados; Administrador do sistema; Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia).

### <font color="#15803D">Passo a passo</font>

1. No Teams, gere a URL no canal por **⋯ › Workflows**, com o modelo de postar no canal quando uma solicitação de webhook for recebida; no Discord, por **Configurações do canal › Integrações › Webhooks › Novo webhook › Copiar URL do webhook**.
2. Integrações › Integrações › **Nova integração** › **Microsoft Teams** (ou **Discord**) › **Identificação**: informe Nome (por exemplo, "Teams — avisos da DIROB"), Código, Objetivo, Ambiente e responsáveis.
3. Mesma tela › **Endereço**: cole a URL inteira em **URL do webhook**.
4. Mesma tela › **Avançado**: informe o **Nome do canal** (como as pessoas o chamam) e clique em **Salvar**.
5. Início › Lista de saída das integrações › **Aprovar destino** (administrador do sistema): o servidor do Workflows da Microsoft ou discord.com, Protocolo **HTTPS**, porta 443, com a **Justificativa**. Uma aprovação do Discord serve para todos os canais.
6. Integrações › Integrações › abra a integração › **Testar** e confira a mensagem de teste no canal.
7. Integrações › Canais de área › **Ligar canal**: escolha a **Integração de Teams ou Discord**, a **Unidade** (por exemplo, GEOBR — Gerência de Obras; vazio = **Organização inteira**) e o **Nome do canal**; clique em **Salvar**.
8. Gestão por indicadores › Alertas e mensagens › na família de aviso, em **Canais da área**, clique em **Publicar num canal**, escolha **Microsoft Teams** ou **Discord** e, em **Onde**, o canal da **unidade do registro** ou um canal fixo.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/4pnt1P8biraS1WN2fcjQm_image.png" size="62" isUploading="false" width="620" height="560" darkWidth="620" darkHeight="560" showCaption="false"}

Figura 202 — Integrações › Nova integração › Microsoft Teams: a URL do webhook do fluxo do canal.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/FKP1TatDlLNIyDqzDSAbW_image.png" size="62" isUploading="false" width="620" height="560" darkWidth="620" darkHeight="560" showCaption="false"}

Figura 203 — Integrações › Nova integração › Discord: a URL do webhook do canal.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/JQ-JRsa-zgiK65opVgQhI_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 204 — Início › Lista de saída das integrações › Aprovar destino para o servidor do webhook.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/8APsNm0fzmA4BbrDT7m8Y_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 205 — Integrações › Canais de área › Ligar canal: a integração de Teams ou Discord e a unidade que recebe os avisos.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/zqgc1O-GVCdRdmkb8A13q_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 206 — Gestão por indicadores › Alertas e mensagens: publicar o aviso no canal da área.

### <font color="#15803D">Observações</font>

- A URL do webhook é um segredo: quem a tem consegue publicar no canal. Ela fica cifrada e nunca volta à tela nem ao histórico do canal.
- Só é aceita URL HTTPS na porta 443. No Teams, só fluxos do Workflows; os antigos conectores do Office 365 não são aceitos. No Discord, o link do canal não serve: tem de ser a URL do webhook.
- A mesma URL não pode estar em duas integrações. A integração de um canal ligado não muda: desative o canal e ligue outro.
- Em **Ligar canal** só aparecem integrações ativas; a que falhou no último teste aparece marcada.
- Unidade sem canal ativo do tipo escolhido não recebe a publicação, que fica como "sem destino" em **Início › Falhas de envio**.
- Registro sigiloso nunca é publicado em canal compartilhado, e ninguém é mencionado nas publicações.

***

## <font color="#15803D">18.3 Onde configurar SEI, SIAFI, Portal da Transparência e Tesouro Gerencial</font>

ID BSC-CFG-03

### <font color="#15803D">Para que serve</font>

SEI, SIAFI, Portal da Transparência e Tesouro Gerencial são cadastrados como integrações do hub e usados pelos conectores do BSC. O SEI acompanha e abre processos; o tipo SIAFI traz a execução do orçamento por um de seus canais (API Dados SIAFI (STA), dados abertos do Portal da Transparência, relatório extraído do Tesouro Gerencial ou web services do SIAFI). O De-Para traduz o dado capturado nos objetos do BSC, e cada execução fica registrada no Monitor de integrações.

Para treinar usuários e homologar o lado do Bússola/BSC antes de os acessos reais serem entregues, há um **ambiente de simulação para treinamento e homologação** que responde como o SEI, o STA e o Portal da Transparência; as integrações de simulação levam o selo **Simulador** e não existem em produção.

**Quem usa:** Analista de Integração de Dados; Administrador do sistema; Gestor de Desempenho (escritório de estratégia).

### <font color="#15803D">Passo a passo</font>

1. SEI: Integrações › Integrações › **Nova integração** › **SEI** › **Endereço**: **URL base** (https\://, por exemplo sei.exemplo.com.br), **Interface do SEI**, **Versão da API** e, só se a TI informar outro, **Caminho da API do módulo**.
2. SEI › **Autenticação**: **Usuário de serviço** e **Senha do usuário de serviço**; depois de um Testar com sucesso, em **Avançado**, escolha **Órgão (id no SEI)**, **Unidade padrão (id no SEI)** e marque as **Operações habilitadas no Bússola/BSC**.
3. SIAFI: Integrações › Integrações › **Nova integração** › **SIAFI** › **Canal**: escolha **API Dados SIAFI (STA)**, **Dados abertos — Portal da Transparência**, **Relatório extraído do Tesouro Gerencial** ou **Web services do SIAFI (exige o Tesouro)**.
4. Canal STA: **Unidade gestora (UG)** (6 dígitos) e **Gestão** (5 dígitos) em Endereço; **Usuário** e **Senha** em Autenticação; **Órgão**, **Exercício** e **Tamanho máximo de uma resposta (MB)** em Avançado.
5. Canal Portal da Transparência: **Endereço da API do Portal**, **Chave da API de dados**, **Unidade gestora (UG)**, **Gestão**, **Órgão** e **Exercício**. Canal Tesouro Gerencial: **Formato do relatório**, **Codificação do relatório**, **Separador de colunas**, **Linha do cabeçalho** e **Aba**. Canal web services: **Endereço do serviço (informado pelo Tesouro)**, **Certificado de aplicação (PKCS#12)**, **Senha do certificado**, UG, gestão, órgão e exercício.
6. Início › Lista de saída das integrações › **Aprovar destino** (administrador do sistema): o servidor do SEI, do STA ou do Portal, Protocolo **HTTPS**, porta 443 e **Justificativa**. O canal Tesouro Gerencial não precisa: o arquivo é enviado pela própria tela.
7. Integrações › Integrações › abra a integração › **Testar** e, nos tipos que leem dados, **Pré-visualizar**.
8. Gestão por indicadores › Configuração de conectores › escolha o componente de captura na paleta, a integração do hub em **Envia ou recebe**, **Por agenda** em **Quando age** (a cada N horas, diária, semanal ou mensal) e **Capturar dado** em **O que faz**; **Simular (sem enviar)** e **Salvar conector**.
9. Na ficha do conector › **Abrir o De-Para**: **Executar leitura de teste** (SIAFI), **Novo De-Para para** (ou um modelo pronto SIAFI), linhas **Vem de** e **Conversão**, **Validar (prévia)** e **Publicar**.
10. Integrações › Tabelas de equivalência › **Nova tabela**: traduza códigos do outro sistema (por exemplo, plano interno → entrega) e use-a no De-Para com a conversão **Tabela de equivalência**.
11. Integrações › Monitor de integrações › filtre pela integração ou pelo conector para ver cada captura, cada disparo e cada aplicação do De-Para.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/Z24grnysFnhJvAZiPgjFT_image.png" size="62" isUploading="false" width="620" height="646" darkWidth="620" darkHeight="646" showCaption="false"}

Figura 207 — Integrações › Nova integração › SEI: interface, endereço, caminho da API, versão, usuário de serviço e operações habilitadas.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/xBabt1fzA6Qc1RLSZ92dJ_image.png" size="62" isUploading="false" width="620" height="646" darkWidth="620" darkHeight="646" showCaption="false"}

Figura 208 — Integrações › Nova integração › SIAFI e dados abertos de orçamento: o canal (API de dados do SIAFI, Portal da Transparência, Tesouro Gerencial, web services) e os campos de cada um.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/FsXNEjWdgo7gFjBlYuTSG_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 209 — Início › Lista de saída das integrações: os servidores aprovados para as integrações.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/uYo0aUL9quw1nU_6TTaSJ_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 210 — A integração aberta: Testar, Pré-visualizar e o resultado do último teste.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/Ee-20ntCgkuum3eqFv0xm_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 211 — Gestão por indicadores › Configuração de conectores: a paleta, com os componentes SEI e SIAFI.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/oQx59UL6RZoW96R2Fq0jl_image.png" size="74" isUploading="false" width="742" height="900" darkWidth="742" darkHeight="900" showCaption="false"}

Figura 212 — O De-Para do conector de captura: de que campo do dado capturado vem cada valor do Bússola/BSC.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/-3f_jHTuLLY4_ad7cAgsj_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 213 — Integrações › Tabelas de equivalência: o código da origem e o objeto do Bússola/BSC que ele representa.

### <font color="#15803D">Observações</font>

- Sem usuário e senha (SEI e STA) ou sem chave (Portal), nada é chamado: o **Testar** diz o que falta e a integração não é oferecida aos conectores até um teste com sucesso.
- No SEI, a trava do que o Bússola/BSC faz é o campo **Operações habilitadas no Bússola/BSC**; tudo aparece no SEI como feito pelo usuário de serviço.
- Web services do SIAFI exigem adesão formal ao Tesouro; não são oferecidos aos conectores até a adesão estar completa.
- Até um De-Para ser publicado, o conector de captura fica "De-Para a configurar" e não lê o outro sistema. Os modelos SIAFI trazem uma hipótese de contas contábeis que a contabilidade precisa confirmar.
- Ambiente de simulação: use as integrações com selo **Simulador** para treinamento e homologação e mantenha ao lado a integração real do mesmo tipo; quando os acessos chegarem, preencha a credencial na real e teste de novo.
- Homologação e produção do mesmo sistema são duas integrações, cada uma com seu selo de ambiente.

***

## <font color="#15803D">18.4 Onde configurar a instalação (Compose e Kubernetes)</font>

ID BSC-CFG-04

### <font color="#15803D">Para que serve</font>

Reúne os arquivos e as variáveis que configuram a instalação do Bússola/BSC: no modo interno, com Docker Compose num servidor da empresa; no modo nuvem, com Kubernetes. A configuração da aplicação é a mesma nos dois modos. O procedimento completo de instalação e de backup está nas seções BSC-INS-01 e BSC-INS-02.

Os segredos (senhas, chave de cifragem, chaves do destino do backup) são gerados pela empresa e preenchidos só nos arquivos de segredo, nunca em manual, chamado ou mensagem; aqui eles aparecem como \<valor>.

**Quem usa:** Administrador do sistema.

### <font color="#15803D">Passo a passo</font>

1. Compose: em \`deploy/compose/bussola/\`, copie \`.env.example\` para \`.env\` e proteja-o com \`chmod 600 .env\`; preencha todo valor marcado \`REPLACE\_\`.
2. Compose › \`.env\` › imagens e endereço: \`BUSSOLA\_BACKEND\_IMAGE\`, \`BUSSOLA\_FRONTEND\_IMAGE\`, \`BUSSOLA\_HOST=bussola.exemplo.com.br\`, \`HTTPS\_PORT\`, \`HTTP\_PORT\`; certificado em \`tls/fullchain.pem\` e \`tls/privkey.pem\`.
3. Compose › \`.env\` › identidade e ambiente: \`KEYCLOAK\_ISSUER\_URI\`, \`KEYCLOAK\_JWK\_URI\` (o backend não sobe sem os dois), \`BUSSOLA\_TENANT\_ID\` e \`BUSSOLA\_TENANT\_NAME\`.
4. Compose › \`.env\` › banco e segredos: \`DB\_ADMIN\_USER\`, \`DB\_ADMIN\_PASS=\<valor>\`, \`MASTER\_DB\_NAME\`, \`TENANT\_DB\_NAME\`, \`TENANT\_DB\_SCHEMA\`, \`TENANT\_READER\_PASS=\<valor>\`, \`RESOURCE\_TENANT\_SECURITY\_KEY=\<valor>\`, \`FINANCE\_PIX\_WEBHOOK\_SECRET=\<valor>\`.
5. Compose › \`.env\` › backup: \`BACKUP\_CRON=0 1 \* \* \*\`, \`BACKUP\_TZ=America/Sao\_Paulo\`, \`BACKUP\_KEEP\_LOCAL\`, \`BACKUP\_DEST\_KIND=S3\` (ou \`PATH\` com \`BACKUP\_DEST\_HOST\_DIR\` e \`BACKUP\_DEST\_KEEP\`), \`BACKUP\_S3\_ENDPOINT\`, \`BACKUP\_S3\_BUCKET\`, \`BACKUP\_S3\_PREFIX\`, \`BACKUP\_S3\_REGION\`, \`BACKUP\_S3\_ACCESS\_KEY=\<valor>\`, \`BACKUP\_S3\_SECRET\_KEY=\<valor>\`, \`BACKUP\_S3\_SSE=AES256\`.
6. Compose: suba com \`docker compose up -d\` e acompanhe \`docker compose logs -f backend\`.
7. Kubernetes: o overlay fica em \`k8s/bussola/\` (sobre \`k8s/base\`); confira com \`kubectl kustomize k8s/bussola\`.
8. Kubernetes › \`backend.env\` (segredo \`erp-backend-secret\`): \`MASTER\_DB\_URL\`, \`MASTER\_DB\_USER\`, \`MASTER\_DB\_PASS=\<valor>\`, \`BUSSOLA\_TENANT\_ID\`, \`TENANT\_DB\_URL\`, \`TENANT\_DB\_USER\`, \`TENANT\_DB\_PASS=\<valor>\`, \`TENANT\_DB\_SCHEMA\`, \`TENANT\_READER\_PASS=\<valor>\`, \`RESOURCE\_TENANT\_SECURITY\_KEY=\<valor>\`, \`FINANCE\_PIX\_WEBHOOK\_SECRET=\<valor>\`; crie com \`kubectl -n bussola create secret generic erp-backend-secret --from-env-file=backend.env\`.
9. Kubernetes › \`configmap.backend.yaml\`: \`KEYCLOAK\_ISSUER\_URI\`, \`KEYCLOAK\_JWK\_URI\`, \`KAFKA\_BOOTSTRAP\_SERVERS\`, \`ERP\_ATTACHMENTS\_DIR=/data/attachments\`; perfis \`SPRING\_PROFILES\_ACTIVE=homolog,bussola\`. No overlay, ajuste também as imagens (\`images:\`), o host e a classe do Ingress (\`ingress.yaml\`) e a classe de armazenamento do volume de anexos (\`pvc.attachments.yaml\`).
10. Kubernetes › backup: \`configmap.backup.yaml\` (\`BACKUP\_DEST\_KIND\`, \`BACKUP\_ATTACHMENTS\_DIR\`, \`BACKUP\_TENANT\_SCHEMAS\`), segredo a partir de \`secret.backup.yaml.example\` e agendamento em \`cronjob.backup.yaml\` (\`schedule: "0 1 \* \* \*"\`, \`timeZone: America/Sao\_Paulo\`).
11. Kubernetes: crie o segredo TLS \`bussola-tls\` e aplique com \`kubectl -n bussola apply -k k8s/bussola\`.
12. Configuração da aplicação (os dois modos): \`k8s/bussola/application-bussola.yml\`, montada em \`/config/\`.

### <font color="#15803D">Observações</font>

- Guarde uma cópia de \`RESOURCE\_TENANT\_SECURITY\_KEY\` num cofre de segredos, fora do destino do backup: sem a mesma chave, toda credencial gravada (integrações, conexões) deixa de abrir após uma restauração.
- Nunca guarde o \`.env\` preenchido em repositório; ele e os segredos do Kubernetes ficam fora do backup, de propósito.
- Sem \`BACKUP\_TZ\`/\`timeZone\`, o agendamento usa UTC e "0 1" viraria 22:00 de Brasília.
- Os anexos ficam no volume \`bussola-attachments\` (Compose) ou no volume persistente do overlay, nunca no diretório temporário do contêiner.
- Liberações de rede: entrada HTTPS no nome público; saída para o provedor de identidade, para os sistemas integrados (SEI, SIAFI, Portal da Transparência, provedor contratado do WhatsApp, Teams e Discord) e para o destino do backup. Os destinos das integrações também precisam estar na lista de saída do Bússola/BSC.
- O ambiente de simulação para treinamento e homologação das integrações não é instalado em produção.
- Procedimento completo, conferência da primeira subida e restauração: seções BSC-INS-01 e BSC-INS-02.

[title]  16. Estrutura organizacional e acesso às empresas
[path] Aplicações/BSC/

A estrutura organizacional do Bússola/BSC é formada pelas **unidades** (Conselho, Presidência, Diretorias, Superintendências, Gerências e Supervisões), pelos **cargos** e pela **lotação** de cada empregado. O **organograma institucional** é desenhado sozinho a partir desses cadastros: não há desenho à mão nem passo de "gerar organograma".

O acesso tem duas camadas que não se confundem. O **usuário** só autentica: diz quem é a pessoa e em quais empresas do grupo ela trabalha. A **autoridade** vem do **cargo** que a pessoa ocupa pela lotação vigente: é ele que dá as permissões. Para mudar o que alguém pode fazer, mexa no cargo e na lotação, não no usuário.

As unidades cadastradas aqui são as mesmas que o planejamento estratégico usa como áreas responsáveis por objetivos, indicadores e ações.

***

## <font color="#15803D">16.1 Cadastrar unidades com hierarquia, sigla e situação</font>

ID BSC-ORG-01

### <font color="#15803D">Para que serve</font>

As **unidades organizacionais** são a estrutura da organização. Cada unidade tem **código** (chave técnica estável), **sigla** (como a organização chama a unidade, por exemplo DIRPLAN ou SUPLAN), **nome**, **nível** e **unidade superior**. É a unidade superior que monta a hierarquia do organograma.

A unidade pode estar **ativa** ou **inativa**. A unidade inativa sai das escolhas novas, mas continua nomeando os registros antigos.

**Quem usa:** Administrador do sistema; Gestor de Desempenho (escritório de estratégia).

### <font color="#15803D">Passo a passo</font>

1. Abra **Administração › Departamentos**.
2. Clique em **Novo departamento** para criar uma unidade, ou abra uma unidade da lista para editá-la.
3. Informe o **código**, a **sigla** e o **nome** (por exemplo, sigla SUPLAN, nome "Superintendência de Planejamento Estratégico").
4. Escolha o **nível**: Conselho de Administração, Presidência, Diretoria, Superintendência, Gerência ou Supervisão.
5. Escolha a **unidade superior** (por exemplo, DIRPLAN para a SUPLAN). Deixe em branco apenas para a unidade do topo.
6. Clique em **Salvar**. A unidade passa a aparecer no organograma, sob a unidade superior.
7. Para retirar uma unidade de uso, abra-a e clique em **Inativar**.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/TS0q7LhT0GlevA4oKMahY_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 189 — Lista de unidades com sigla, nível, unidade superior e situação

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/h82GUf7H0Jy-MpV3xRYFE_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 190 — Unidade aberta: unidade superior, sigla, nível e situação

### <font color="#15803D">Observações</font>

- A sigla é obrigatória ao criar e ao editar: até 20 letras, dígitos ou hífen, gravada em maiúsculas.
- A sigla não se repete entre unidades ativas, sem diferença de maiúsculas. A recusa aparece no próprio campo e nomeia a unidade que já usa a sigla. Uma unidade inativa libera a sigla para ser reaproveitada numa reestruturação.
- Unidades antigas, criadas antes da sigla existir, aparecem com o aviso **"sem sigla"**; a sigla é pedida na próxima edição.
- **Inativar** é recusado, com o motivo logo abaixo do botão, quando a unidade tem subordinada ativa (a mensagem lista as siglas) ou pessoa lotada nela hoje (a mensagem diz quantas). Mova subordinadas e pessoas antes.
- Criar e editar unidades exige a permissão de gerenciar departamentos. Quem não a tem vê a estrutura, mas não os botões de edição; uma tentativa de salvar recebe "Você não tem autorização para esta operação".
- As áreas do planejamento estratégico são as unidades do organograma: ative ou inative uma unidade aqui para incluí-la ou retirá-la das escolhas de área.

***

## <font color="#15803D">16.2 Cargos e lotação: unidade × cargo e a montagem automática do organograma</font>

ID BSC-ORG-02

### <font color="#15803D">Para que serve</font>

O **cargo** dá as permissões; a **lotação** diz onde a pessoa trabalha e em qual cargo. O cartão **Lotação** da unidade lista os cargos que a unidade comporta, com o número de vagas. Quem ocupa cada cargo não se digita na unidade: vem da lotação funcional de cada empregado.

É a **lotação primária vigente** (marcada como primária, com início até hoje e sem fim) que posiciona a pessoa no organograma e define o cargo, e portanto as permissões, que ela exerce.

**Quem usa:** Administrador do sistema; Gestor de Desempenho (escritório de estratégia).

### <font color="#15803D">Passo a passo</font>

1. Abra **Recursos humanos › Cargos** e clique em **Novo cargo**. Informe o **nome**, a **chefia** (cargo superior; em branco, o cargo fica no topo) e a **descrição**, e salve.
2. Abra **Administração › Departamentos**, abra a unidade e vá ao cartão **Lotação**.
3. Em **Acrescentar cargo à lotação**, escolha o cargo e, se quiser, as **vagas** (1 ou mais; em branco, o número fica não informado). Clique em **Acrescentar**.
4. Para mudar o número de vagas, use **Vagas** na linha do cargo. Para tirar o cargo da lotação sem mexer em ninguém, use **Inativar**.
5. Abra **Recursos humanos › Empregados** e abra a ficha da pessoa (por exemplo, Karina Albuquerque).
6. No bloco **Lotação**, registre o vínculo, a unidade (por exemplo, GEOBR), o **cargo**, o centro de custo padrão, a data de início, o tipo da mudança (**Mudança de lotação** ou **Promoção**) e o **motivo**.
7. Marque **primária** a lotação que vale por padrão e salve. Ao registrar uma nova primária, a anterior é encerrada automaticamente na véspera do início da nova.
8. Abra **Administração › Organograma** e confira a pessoa na caixa da unidade, com a ocupação do cargo.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/q04el_fuQW42wsGsGjgwr_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 191 — Cargos organizados por chefia

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/aPOug-nOhBNYqokmZN4MD_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 192 — Ficha da empregada com a lotação unidade × cargo

### <font color="#15803D">Observações</font>

- O cadastro recusa uma chefia de cargo que criaria um ciclo (A chefia B, que chefia A).
- Divergência é aviso, não bloqueio: pessoa lotada num cargo que a lotação da unidade não prevê aparece em **"Fora da lotação"** e continua contando na unidade; mais ocupantes que vagas aparecem como **"acima do quadro"**. Corrija a lotação da unidade ou o vínculo da pessoa, nunca o organograma.
- A lotação adicional também aparece como ocupante, identificada como "(lotação adicional)".
- A mesma unidade e o mesmo cargo duas vezes no mesmo período são recusados; a recusa nomeia a lotação que já cobre aquelas datas.
- Uma lotação primária com início futuro aparece como **"Primária a partir de \<data>"**: a pessoa continua na lotação atual até lá.
- O motivo é obrigatório e vai para a trilha de vida funcional. Cada linha de lotação tem o botão **Trilha**, com o que mudou, quem mudou e quando.
- Se a pessoa ainda não tem contrato de trabalho, a ficha não abre o formulário de lotação e oferece o link **"Cadastrar o contrato de trabalho"**.
- Cargos, empregados e lotação exigem a permissão de gerenciar departamentos; sem ela, a tela recusa até a listagem.
- O ícone de relógio de cada linha do cartão **Lotação** da unidade abre o histórico daquela linha, com o antes e o depois.

***

## <font color="#15803D">16.3 Unidades assistentes</font>

ID BSC-ORG-03

### <font color="#15803D">Para que serve</font>

Uma **unidade assistente** assessora a unidade superior em vez de estar na linha de comando dela. Exemplos: a Auditoria Interna (AUDIN) junto ao Conselho de Administração (CONSAD), ou uma assessoria ao lado da Presidência (PRESI). No organograma ela aparece ao lado da unidade assessorada, ligada lateralmente.

A unidade assessorada é sempre a unidade superior. As subordinadas de uma assistente são unidades comuns dela.

**Quem usa:** Administrador do sistema.

### <font color="#15803D">Passo a passo</font>

1. Abra **Administração › Departamentos** e abra a unidade (por exemplo, AUDIN).
2. Escolha primeiro a **unidade superior** (por exemplo, CONSAD).
3. Marque **Unidade assistente da unidade superior** e salve.
4. Para definir em quais níveis uma assistente pode ser pendurada, vá ao fim da tela, no cartão **Níveis que recebem unidades assistentes**.
5. Marque os níveis permitidos (por exemplo, Conselho de Administração, Presidência e Diretoria) e salve.
6. Use o botão **Histórico** do cartão para ver quem mudou a regra e quando.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/h82GUf7H0Jy-MpV3xRYFE_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 193 — Unidade marcada como assistente da unidade superior

### <font color="#15803D">Observações</font>

- Quando a marcação não é possível, a caixa fica desabilitada com o motivo escrito embaixo: sem unidade superior, unidade superior inativa ou nível da superior que não recebe assistentes pela regra da organização.
- Sem nenhum nível marcado no cartão, todos os níveis podem receber unidades assistentes.
- A regra vale quando uma unidade é marcada como assistente ou muda de unidade superior. Assistentes já existentes não são desfeitas quando a regra aperta e continuam podendo ser renomeadas.
- No detalhe da assistente, o organograma mostra **"Assessora"** no lugar da unidade superior.

***

## <font color="#15803D">16.4 Organograma interativo</font>

ID BSC-ORG-04

### <font color="#15803D">Para que serve</font>

O **organograma** mostra a estrutura da organização desenhada a partir das unidades, da lotação e de quem ocupa cada cargo hoje. Cada caixa traz a sigla, o nome, o chefe, a ocupação (por exemplo, "2 de 3 vagas") e, em destaque, **"fora da lotação"** ou **"acima do quadro"** quando houver.

O organograma pode ser visto como **Gráfico** ou como **Lista** recuada, com a mesma expansão e o mesmo destaque.

**Quem usa:** Administrador do sistema; Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia); Responsável por ação/área; Leitor/Auditor.

### <font color="#15803D">Passo a passo</font>

1. Abra **Administração › Organograma**. O desenho abre mostrando três níveis.
2. Para expandir ou recolher um ramo, use o botão sob a caixa. A caixa recolhida mostra **"+N"**, o número de unidades escondidas no ramo.
3. Use **Expandir tudo**, **Recolher tudo** ou **Três níveis** para mudar a profundidade de uma vez.
4. Em **Buscar unidade ou pessoa**, digite a sigla, o nome ou o código da unidade, ou o nome da pessoa (a partir de duas letras). Escolha um resultado: o caminho até ele é aberto e destacado desde o topo.
5. Clique numa caixa (ou chegue a ela com Tab e pressione Enter) para abrir o **detalhe**: chefe, unidade superior, ocupação, lotação com os ocupantes de cada cargo, quem está fora da lotação e o histórico.
6. No detalhe, clique em **Ver a partir desta unidade** para mostrar só aquele ramo; use a trilha acima do desenho para voltar a qualquer nível ou à **Organização inteira**.
7. Use **Aproximar (+)**, **Afastar (−)** e **Ajustar à tela** para o zoom; arraste o fundo para mover o desenho.
8. Marque **Mostrar unidades inativas** para incluí-las no desenho; troque a **Visão** para **Lista** quando preferir a estrutura recuada.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/SCYV_Onnbx13ELTvAfNpc_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 194 — Organograma interativo com unidades assistentes ao lado da unidade assessorada

### <font color="#15803D">Observações</font>

- Unidades assistentes aparecem ao lado da unidade que assessoram, com borda e ligação tracejadas e o rótulo **ASSISTENTE**. Caixas tracejadas também indicam unidades inativas.
- Escolher uma pessoa na busca abre também o detalhe da unidade dela.
- A roda do mouse aproxima no ponto do cursor. Com o desenho selecionado, as teclas **+**, **−** e as setas fazem o mesmo.
- No celular (largura abaixo de 768 px), a **Lista** é a visão padrão, sem rolagem horizontal.
- Ler o organograma exige só a permissão de leitura de cadastros, que todo cargo costuma ter. O botão **Editar unidade e lotação** aparece apenas para quem administra a estrutura.
- A tela não tem exportação nem impressão própria; para registro em papel, use a impressão do navegador.
- Sem nenhuma unidade cadastrada, a tela informa que o organograma aparece quando existir a primeira unidade.

***

## <font color="#15803D">16.5 Acesso do usuário às empresas</font>

ID BSC-ORG-05

### <font color="#15803D">Para que serve</font>

O **usuário** é a credencial de login: nome, e-mail e papéis de acesso. Quando a instalação administra mais de uma empresa do grupo (a própria e empresas controladas ou vinculadas), cada usuário pode ficar limitado às empresas em que trabalha.

A limitação vale para o **seletor de empresa** do cabeçalho e é conferida pelo servidor em toda operação da pessoa, não só no que a tela oferece.

**Quem usa:** Administrador do sistema.

### <font color="#15803D">Passo a passo</font>

1. Abra **Administração › Usuários**. A lista mostra os logins com nome, e-mail, papéis, situação e a coluna **Empresas com acesso**.
2. Para criar um usuário, clique em **Novo usuário**, informe nome, e-mail e papéis de acesso e salve. A pessoa recebe por e-mail o link para definir a própria senha.
3. Para limitar as empresas, ache o usuário pela busca e clique em **Empresas** na linha dele. O painel lista as empresas ativas, com a raiz do CNPJ.
4. Marque as empresas em que a pessoa pode trabalhar e clique em **Salvar**. O painel confirma "Acesso salvo", e a linha passa a mostrar as empresas.
5. Para devolver o acesso a todas as empresas, desmarque tudo e salve.
6. Use o botão **Histórico** do painel para ver cada alteração, com as empresas antes e depois e quem mudou.
7. Peça à pessoa que escolha a empresa (ou o estabelecimento) no **seletor de empresa** do cabeçalho antes de gravar.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/k_wPaFZKpGPpUy_fs5HKG_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 195 — Usuários › Empresas: empresas em que o usuário pode trabalhar

### <font color="#15803D">Observações</font>

- Sem nenhuma empresa marcada, o usuário trabalha em todas. Marcar todas as empresas de hoje não é o mesmo: uma empresa cadastrada depois só entra para quem está sem nenhuma marcada.
- O acesso salvo vale a partir da próxima tela que o usuário abrir.
- Com uma única empresa permitida, o sistema já trabalha nela. Se ela não tem matriz ativa, escolha um estabelecimento no seletor; a mensagem "A empresa … não tem matriz ativa" avisa o caso.
- Com duas ou mais empresas permitidas e nenhuma escolhida, as consultas abrem, mas gravar é recusado com "Você trabalha em mais de uma empresa e nenhuma está escolhida". Preferências pessoais (colunas, notificações) gravam sem escolher empresa.
- Empresa fora da lista, escolhida no seletor ou enviada como filtro, é recusada com "A empresa pedida … não está entre as suas", e a escolha é limpa automaticamente.
- Se o servidor não consegue conferir a lista, a operação é recusada com "Não foi possível conferir as empresas em que você pode trabalhar"; nunca é liberada.
- Empresa inativa não é oferecida para marcar; se já estava marcada, continua listada e pode ser desmarcada.
- Limites conhecidos: com duas ou mais empresas e nenhuma escolhida, consultas consolidadas sem filtro de empresa mostram todas; um estabelecimento informado dentro do próprio formulário não é reconferido; e os cadastros de empresa e estabelecimento seguem legíveis (nome e CNPJ). Para isolamento total, deixe a pessoa com uma única empresa.
- A coluna e o botão **Empresas** aparecem só para quem tem a permissão "Escolher as empresas em que cada usuário trabalha". Quem a tem pode ampliar o próprio acesso: dê a permissão apenas a administradores de confiança e confira o **Histórico**.
- O usuário só autentica. O que a pessoa pode fazer vem do cargo da lotação vigente (BSC-ORG-02).

[title]  13. Hub de integrações, conectores e De-Para
[path] Aplicações/BSC/

O **hub de integrações** é o ponto único onde a Empresa Exemplo S.A. cadastra cada ligação do Bússola/BSC com outro sistema: APIs, web services, bancos de dados, arquivos, SEI, SIAFI, dados abertos e canais de mensagem. Cada integração guarda a credencial cifrada, passa por uma lista de saída aprovada pelo administrador do sistema e é testada antes de ser usada.

Sobre as integrações, os **conectores do BSC** definem quando agir e o que fazer (avisar pessoas e canais quando um indicador sai da faixa, ou capturar dados por agenda), e o **De-Para** traduz o dado capturado nos objetos do BSC: realizado e meta de indicador, execução de entregas e atividades e itens de portais.

Este capítulo cobre o cadastro e o teste das integrações, cada tipo disponível, os sistemas corporativos sob demanda, o ambiente de simulação, os conectores e o De-Para com suas tabelas de equivalência. O acompanhamento das execuções está no Monitor de integrações, descrito no capítulo de dados.

***

## <font color="#15803D">13.1 Conceitos: integração, conector e De-Para</font>

ID BSC-ITG-01

### <font color="#15803D">Para que serve</font>

O **hub de integrações** é o lugar único onde a organização cadastra cada ligação do Bússola/BSC com um sistema de fora: SEI, SIAFI, APIs de parceiros, bancos de dados, arquivos, brokers e canais de mensagem (Microsoft Teams, Discord e WhatsApp também são tipos do hub). Ele fica num menu próprio, **Integrações**; o BSC apenas escolhe entre as integrações cadastradas, e ninguém digita a senha de outro sistema em outra tela.

Três peças trabalham juntas: a **integração** diz com quem e com que credencial o Bússola/BSC fala; o **conector** diz quando e para quê usar a integração (por exemplo, "atingimento abaixo de 80%" → enviar mensagem, ou capturar dado por agenda); o **De-Para** diz o que vira o quê, isto é, qual coluna da origem vai para qual campo de um objeto do BSC.

**Quem usa:** Analista de Integração de Dados; Gestor de Desempenho; Diretoria de Estratégia; Administrador do sistema.

### <font color="#15803D">Passo a passo</font>

1. Integrações › Integrações › veja a lista das integrações cadastradas.
2. Gestão por indicadores › Configuração de conectores › veja os conectores que usam essas integrações.
3. Na ficha de um conector de captura, use **Abrir o De-Para** para ver a tradução dos campos.
4. Na ficha de uma integração, consulte **Quem usa** para saber quais conectores e canais dependem dela.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/-GBQac1XnXOBwPg7vJ2QJ_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 141 — Lista de integrações do hub

### <font color="#15803D">Observações</font>

- A senha, a chave ou o token fica cifrado e nunca volta para a tela, o histórico ou uma mensagem de erro; a ficha mostra só "Definido em … por …".
- O endereço de destino precisa estar na lista de saída aprovada pelo administrador do sistema.
- Endereços internos da própria máquina, da nuvem ou dos servidores da plataforma são sempre recusados, mesmo aprovados.
- Homologação e produção do mesmo sistema são duas integrações, cada uma com seu selo de ambiente.
- Uma integração usada por um conector ativo não pode ser desativada: pause ou troque antes o conector.

***

## <font color="#15803D">13.2 Cadastrar uma integração</font>

ID BSC-ITG-02

### <font color="#15803D">Para que serve</font>

O cadastro registra o sistema de destino, o objetivo, o ambiente e os responsáveis, além do endereço e da autenticação próprios de cada tipo.

**Quem usa:** Analista de Integração de Dados.

### <font color="#15803D">Passo a passo</font>

1. Integrações › Integrações › use os filtros (tipo, direção, ambiente e situação) para conferir se a integração já existe.
2. Clique em **Nova integração** e escolha o tipo num dos cartões, agrupados em Dados, Governo, Mensageria e API aberta.
3. Em **Identificação**, preencha Nome (único; diga sistema, objetivo e ambiente, por exemplo "SEI — abrir processo (homologação)"), Código, Objetivo, Ambiente (homologação ou produção), unidade e pessoa responsáveis.
4. Preencha **Endereço**, **Autenticação** e **Avançado** conforme o tipo; consulte o painel **Como integrar** ao lado do formulário.
5. Clique em **Salvar**; o Bússola/BSC confere o endereço na lista de saída e recusa na hora se não estiver aprovado ou for proibido.
6. Na ficha, clique em **Testar** e, nos tipos que leem dados, em **Pré-visualizar**.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/WokAPJ8jAKgk5a-D4vuTy_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 142 — Nova integração: escolha do tipo por grupo

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/uYo0aUL9quw1nU_6TTaSJ_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 143 — Ficha da integração com Testar, Pré-visualizar e periodicidade

### <font color="#15803D">Observações</font>

- A lista mostra nome, tipo, direção (captura, envio ou ambos), ambiente, último teste, quantos conectores a usam e responsável.
- O código aceita maiúsculas, números, hífen e sublinhado e não muda depois; o tipo também não muda: cadastre outra integração.
- É normal ter duas integrações do mesmo sistema (por exemplo, "SEI — abrir processo" e "SEI — consultar andamento"). Nunca troque de ambiente editando o endereço: cadastre a outra.
- "Já existe uma integração com o nome …": acrescente objetivo ou ambiente ao nome.
- "Este tipo de integração ainda não está disponível nesta versão": o tipo é de uma próxima entrega.
- O cadastro e cada alteração entram no histórico da integração.

***

## <font color="#15803D">13.3 Testar uma integração</font>

ID BSC-ITG-03

### <font color="#15803D">Para que serve</font>

O botão **Testar** chama o outro sistema pelo caminho de teste do tipo, passando pela lista de saída e pela guarda de endereços, e grava o resultado com data. A resposta é sempre traduzida para a linguagem do operador.

**Quem usa:** Analista de Integração de Dados.

### <font color="#15803D">Passo a passo</font>

1. Integrações › Integrações › abra a integração.
2. Clique em **Testar**.
3. Leia o resultado na ficha e na lista, por exemplo "Conectou: o outro sistema respondeu." ou "O outro sistema recusou a credencial…".
4. Corrija o que for indicado e teste de novo.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/uYo0aUL9quw1nU_6TTaSJ_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 144 — Resultado do teste na ficha da integração

### <font color="#15803D">Observações</font>

- Resultados: funcionando (destino respondeu com sucesso); credencial recusada (confira a autenticação e substitua o segredo); caminho não existe (corrija o caminho de teste); redirecionou (o Bússola/BSC não segue redirecionamento, cadastre o endereço final); endereço não aprovado ou proibido; não respondeu a tempo, recusou a conexão ou certificado não confere (confira o serviço e os tempos em Avançado).
- Editar o endereço ou a credencial apaga o último teste: ele provou outra configuração.
- Se alguém alterar a integração enquanto um teste roda, o resultado aparece para quem testou mas não fica na ficha.
- O tipo Arquivo não tem Testar. O tipo Banco de dados testa também a conta.
- Só quem mantém integrações vê o botão Testar.
- O texto técnico do outro sistema nunca chega à tela.

***

## <font color="#15803D">13.4 Pré-visualizar os dados de uma integração</font>

ID BSC-ITG-04

### <font color="#15803D">Para que serve</font>

Os tipos que leem dados (API REST, web service SOAP e arquivo) têm o cartão **Pré-visualização**: ele lê os primeiros 50 registros como a integração está configurada e mostra os nomes dos campos encontrados, para conferir o caminho dos registros, o elemento que se repete ou o leiaute antes de uma carga ou de um De-Para.

**Quem usa:** Analista de Integração de Dados.

### <font color="#15803D">Passo a passo</font>

1. Integrações › Integrações › abra a integração.
2. No cartão **Pré-visualização**, para arquivo enviado pela tela, anexe um arquivo de exemplo.
3. Clique em **Pré-visualizar**.
4. Confira a tabela com os nomes dos campos e os fatos medidos (resposta, páginas lidas, versão do SOAP).
5. Passe o mouse sobre um valor cortado para vê-lo inteiro.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/uYo0aUL9quw1nU_6TTaSJ_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 145 — Cartão de pré-visualização com os primeiros registros

### <font color="#15803D">Observações</font>

- Na API e no SOAP a pré-visualização chama o outro sistema e o resultado fica como último teste da integração.
- No arquivo, o exemplo (até 10 MB) é lido e descartado e não conta como teste.
- Campo aninhado aparece como JSON compacto.

***

## <font color="#15803D">13.5 Periodicidade da atualização</font>

ID BSC-ITG-05

### <font color="#15803D">Para que serve</font>

API REST, web service SOAP e banco de dados têm a seção **Atualização**, que define com que frequência os dados devem ser renovados. Quem executa a atualização são as cargas de dados e os conectores que usam a integração.

**Quem usa:** Analista de Integração de Dados.

### <font color="#15803D">Passo a passo</font>

1. Integrações › Integrações › abra a integração e clique em **Editar**.
2. Na seção **Atualização**, escolha Manual, De hora em hora (no minuto escolhido), Diária, Semanal (dia da semana) ou Mensal (dia 1 a 28).
3. Informe o horário no formato HH\:mm.
4. Salve e confira a **próxima atualização prevista** na lista e na ficha.

### <font color="#15803D">Observações</font>

- Todos os horários são de Brasília, seja qual for o fuso do seu computador.
- O dia do mês vai de 1 a 28 para existir em todos os meses.
- Integração inativa não tem próxima atualização.
- O tipo Arquivo não tem periodicidade própria: o agendamento de arquivo por endereço fica na carga de dados.

***

## <font color="#15803D">13.6 Segredos e troca de credencial</font>

ID BSC-ITG-06

### <font color="#15803D">Para que serve</font>

Senhas, chaves, tokens e certificados são guardados cifrados e só podem ser escritos, nunca lidos de volta. A troca de credencial é registrada sem o valor antigo nem o novo.

**Quem usa:** Analista de Integração de Dados; Administrador do sistema.

### <font color="#15803D">Passo a passo</font>

1. Integrações › Integrações › abra a integração.
2. No cartão **Credenciais**, clique em **Substituir** (ou edite a integração e preencha o campo do segredo).
3. Informe o novo valor e salve.
4. Clique em **Testar** de novo, pois o último teste foi apagado.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/uYo0aUL9quw1nU_6TTaSJ_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 146 — Cartão Credenciais com a opção Substituir

### <font color="#15803D">Observações</font>

- Ao editar, o campo de segredo mostra "Definido em … por …"; deixá-lo intocado mantém o valor guardado.
- O histórico registra "segredo trocado em …" sem os valores.
- Cabeçalho ou parâmetro comum com nome de credencial (Authorization, Cookie, X-Api-Key, ou contendo token, secret, password ou key), chave na URL e usuário e senha embutidos no endereço são recusados: credencial vai na seção Autenticação.
- Os segredos usam a cifragem com versão de chave da plataforma; quando o administrador troca a chave em **Início › Chaves de cifragem**, os segredos das integrações são recifrados junto.
- "A credencial guardada não pode ser lida": a chave sumiu antes da recifragem; substitua o segredo.

***

## <font color="#15803D">13.7 Lista de saída (destinos aprovados)</font>

ID BSC-ITG-07

### <font color="#15803D">Para que serve</font>

A lista de saída diz para onde as integrações do ambiente podem se conectar. É mantida só pelo administrador do sistema e protege a rede interna e a plataforma contra conexões indevidas.

**Quem usa:** Administrador do sistema.

### <font color="#15803D">Passo a passo</font>

1. Início › Lista de saída das integrações › clique em **Aprovar destino**.
2. Informe o **Servidor** exato (por exemplo, api.exemplo.com.br) ou um IP, sem curinga e sem caminho.
3. Escolha o **Protocolo** (HTTPS, HTTP só para rede local, banco de dados, broker AMQP ou Kafka) e a **Porta** (vazia só para HTTPS público, que vira 443).
4. Marque **Servidor da rede local** quando o destino for um servidor interno da organização.
5. Escreva a **Justificativa** e salve.
6. Para consultar mudanças, abra o histórico do destino (ícone de relógio); para retirar a aprovação, use o ícone de energia.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/FsXNEjWdgo7gFjBlYuTSG_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 147 — Lista de saída com os destinos aprovados

### <font color="#15803D">Observações</font>

- Retirar a aprovação faz toda integração que usa o destino ser recusada na próxima execução.
- Nunca são liberados, mesmo aprovados: a própria máquina, a rede de enlace local, os metadados de nuvem, IP escrito de forma não padrão, nomes de uma palavra só e os servidores da própria plataforma (banco, mensageria, autenticação, arquivos, portal).
- O endereço é conferido já resolvido no momento da conexão: um nome aprovado que passe a apontar para a rede interna é recusado.
- Servidor interno exige "Servidor da rede local" marcado e o nome completo.
- O histórico de um destino abre para quem tem a leitura da auditoria.

***

## <font color="#15803D">13.8 Perfis de acesso ao hub</font>

ID BSC-ITG-08

### <font color="#15803D">Para que serve</font>

O acesso ao hub é controlado por operações atribuídas aos cargos nas regras de autorização. O Analista de Integração de Dados mantém as integrações; Diretoria de Estratégia e Gestor de Desempenho consultam; o administrador do sistema cuida da lista de saída.

**Quem usa:** Administrador do sistema; Analista de Integração de Dados; Diretoria de Estratégia; Gestor de Desempenho.

### <font color="#15803D">Passo a passo</font>

1. Início › Alçada (regras de autorização) › localize as operações **Ver o hub de integrações**, **Cadastrar e testar integrações** e **Configurar conectores do BSC**.
2. Atribua ou retire cada operação dos cargos conforme a política da organização.
3. Confira com um usuário do cargo se o menu Integrações aparece como esperado.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/X9ysGv29hbyr4whrYzjRU_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 148 — Regras de autorização por cargo

### <font color="#15803D">Observações</font>

- Analista de Integração de Dados: vê o hub; cadastra, testa, troca segredo e desativa.
- Diretoria de Estratégia: vê o hub sem botões de edição e liga canais de Teams e Discord às unidades.
- Gestor de Desempenho: vê o hub sem botões de edição.
- Administrador do sistema: mantém a lista de saída.
- Demais cargos: o menu não aparece e o acesso é recusado.

***

## <font color="#15803D">13.9 Tipo API REST</font>

ID BSC-ITG-09

### <font color="#15803D">Para que serve</font>

Lê dados da API de outro sistema por HTTP(S), com consulta GET (ou POST com corpo fixo), página após página. Tem Testar, Pré-visualizar e periodicidade.

**Quem usa:** Analista de Integração de Dados; Administrador do sistema.

### <font color="#15803D">Passo a passo</font>

1. Obtenha do outro sistema o endereço base (por exemplo, https\://api.exemplo.com.br/v1), o caminho dos dados, um caminho leve para teste, a credencial (de preferência uma conta só de leitura dedicada ao Bússola/BSC), a forma de paginação e onde fica a lista na resposta JSON.
2. Peça ao administrador do sistema a aprovação do servidor da API e, se for outro, do servidor do token OAuth2.
3. Integrações › Integrações › **Nova integração** › API REST.
4. Em **Endereço**, preencha URL base, Método, Caminho dos dados, Corpo da requisição (só POST, JSON fixo, nunca credencial) e Caminho de teste.
5. Em **Autenticação**, escolha Nenhuma, chave num cabeçalho, usuário e senha (Basic), token (Bearer) ou OAuth2 com credenciais do cliente.
6. Em **Avançado**, informe cabeçalhos e parâmetros fixos, Caminho dos registros, Paginação (página e tamanho, deslocamento e limite, cursor ou cabeçalho de próxima página), tempos e requisições por minuto.
7. Salve, clique em **Testar** e depois em **Pré-visualizar** para conferir os registros.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/uYo0aUL9quw1nU_6TTaSJ_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 149 — Integração de API REST com pré-visualização dos registros

### <font color="#15803D">Observações</font>

- No OAuth2 o Bússola/BSC pede o token ao servidor de autorização (HTTPS obrigatório), guarda-o só em memória até vencer e o envia como Bearer.
- A pré-visualização lê até 5 páginas e mostra os 50 primeiros registros.
- Erros comuns: caminho dos registros não encontrado; API que não respondeu em JSON; servidor de autorização recusou o cliente; próxima página apontando para outro servidor (nunca seguida); redirecionamento; resposta acima de 10 MB depois de descompactada (use paginação).

***

## <font color="#15803D">13.10 Tipo web service SOAP</font>

ID BSC-ITG-10

### <font color="#15803D">Para que serve</font>

Lê uma operação de consulta de um web service SOAP descrito por um WSDL 1.1, o caso de serviços que ainda não têm API REST. Tem Testar (lê o WSDL e confere a operação, sem chamá-la), Pré-visualizar e periodicidade. O tipo só lê; o SOAP do SEI tem tipo próprio.

**Quem usa:** Analista de Integração de Dados; Administrador do sistema.

### <font color="#15803D">Passo a passo</font>

1. Obtenha o endereço do WSDL 1.1 (por exemplo, https\://ws.exemplo.com.br/servico?wsdl), a operação de consulta, os valores dos parâmetros de entrada, o elemento que se repete na resposta e a credencial, se houver.
2. Peça a aprovação na lista de saída do servidor do WSDL e do servidor do serviço, se forem diferentes.
3. Integrações › Integrações › **Nova integração** › Web service SOAP.
4. Informe o **Endereço do WSDL** e clique em **Ler o WSDL** para listar serviços, portas e operações.
5. Escolha a operação; serviço, porta e versão do SOAP são preenchidos automaticamente.
6. Informe o **Elemento que se repete** e, em Avançado, os **Parâmetros** (o valor  vira o dia da execução).
7. Escolha a autenticação (Nenhuma, Basic, chave num cabeçalho ou usuário e senha na mensagem), salve, teste e pré-visualize.

### <font color="#15803D">Observações</font>

- Só operações com entrada simples (textos, números, datas) são atendidas; para as demais, use um barramento REST ou peça um tipo próprio.
- Importações do WSDL precisam estar no mesmo servidor; WSDL 2.0 é recusado.
- Basic e usuário e senha na mensagem só funcionam sobre https\://.
- Uma falha SOAP aparece com o código e a mensagem curta do outro sistema; o detalhe técnico nunca é mostrado.
- XML com declaração DOCTYPE/DTD é recusado por segurança.
- Use **Endereço do serviço** só quando o endereço dentro do WSDL estiver errado; ele também é conferido na lista de saída.

***

## <font color="#15803D">13.11 Tipo banco de dados</font>

ID BSC-ITG-11

### <font color="#15803D">Para que serve</font>

Lê tabelas e visões do banco de outro sistema (PostgreSQL ou SQL Server) para as consultas e cargas do Bússola/BSC. Tem Testar, com diagnóstico da conta, e periodicidade; as consultas são escritas no editor SQL e nas cargas.

**Quem usa:** Analista de Integração de Dados; Administrador do sistema.

### <font color="#15803D">Passo a passo</font>

1. Obtenha o servidor, a porta, o nome do banco e uma conta somente leitura dedicada ao Bússola/BSC, sem poder gravar e sem papel de administração.
2. Peça ao administrador do sistema a aprovação do servidor na lista de saída com protocolo Banco de dados e a porta exata (servidor interno com "Servidor da rede local").
3. Integrações › Integrações › **Nova integração** › Banco de dados.
4. Em **Endereço**, informe Tipo de banco, Servidor (só nome ou IP, por exemplo db.exemplo.com.br), Porta, Banco e Criptografia.
5. Em **Autenticação**, informe usuário e senha da conta somente leitura.
6. Em **Avançado**, use apenas as propriedades extras do driver aceitas para o tipo de banco.
7. Salve e clique em **Testar**; leia o diagnóstico da conta.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/uYo0aUL9quw1nU_6TTaSJ_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 150 — Teste de banco de dados com o diagnóstico da conta

### <font color="#15803D">Observações</font>

- Diagnóstico: conta somente leitura funciona; conta que pode gravar funciona com aviso (consultas e cargas só rodam depois de um teste limpo); conta administradora é recusada com o motivo.
- Não existe campo de linha de conexão: vírgula, barra, arroba, espaço, instância nomeada e parâmetros no servidor são recusados.
- Trocar servidor, porta, banco, criptografia, usuário ou senha apaga o último teste.
- Prefira "Criptografada, com certificado e nome conferidos" sempre que o servidor tiver certificado confiável.
- Conexão em paralelo a vários endereços e banco em nuvem no modo de redirecionamento não são atendidos; cadastre o endereço que responde por um IP.
- A conexão é feita por driver nativo; não há ODBC a instalar. Outros bancos podem ser instalados sob pedido da organização.

***

## <font color="#15803D">13.12 Tipo arquivo</font>

ID BSC-ITG-12

### <font color="#15803D">Para que serve</font>

Lê arquivos CSV, TXT, Excel, JSON ou XML, enviados pela tela ou baixados de um endereço, para as cargas do Bússola/BSC. Não tem Testar nem periodicidade própria; tem Pré-visualizar com arquivo de exemplo.

**Quem usa:** Analista de Integração de Dados.

### <font color="#15803D">Passo a passo</font>

1. Integrações › Integrações › **Nova integração** › Arquivo.
2. Em **Origem do arquivo**, escolha enviado pela tela ou baixado de um endereço (informe a URL https\:// e peça a aprovação do servidor na lista de saída).
3. Em **Avançado**, defina Formato, Codificação, Separador, Linha do cabeçalho, Aba (Excel), Caminho dos registros (JSON) ou Elemento que se repete (XML).
4. Salve e, na ficha, anexe um arquivo de exemplo e clique em **Pré-visualizar**.
5. Use a integração numa carga de dados, onde fica o agendamento.

### <font color="#15803D">Observações</font>

- O leiaute fica fixado na integração: um arquivo exportado com outra codificação ou outro separador lê colunas erradas até a integração ser editada. Pré-visualize um arquivo novo antes de usá-lo numa carga.
- Codificação automática: UTF-8 quando o arquivo é UTF-8; senão Windows-1252.
- XML com DOCTYPE ou entidades é recusado por segurança; nada é lido de fora.
- "Este tipo de integração não tem periodicidade própria": agende pela carga.

***

## <font color="#15803D">13.13 Tipos das próximas entregas: HTTP de saída, webhook de entrada, broker e barramento</font>

ID BSC-ITG-13

### <font color="#15803D">Para que serve</font>

Alguns tipos já aparecem citados na tela de nova integração para planejamento, mas ainda não executam nesta versão. Conhecê-los ajuda a preparar o que pedir aos outros sistemas.

**Quem usa:** Analista de Integração de Dados; Administrador do sistema.

### <font color="#15803D">Passo a passo</font>

1. Integrações › Integrações › **Nova integração** › veja os tipos citados abaixo dos cartões.
2. Para **HTTP de saída** (envio de dados com fila de reenvio e chave de idempotência), prepare o endereço que recebe (POST, PUT ou PATCH), a credencial e, se houver, o segredo de assinatura.
3. Para **Webhook de entrada** (eventos assinados enviados ao Bússola/BSC), saiba que o endereço e o segredo serão gerados pelo próprio Bússola/BSC e mostrados uma vez.
4. Para **Broker de mensageria** (Kafka ou AMQP), prepare servidores e portas, usuário e senha ou certificado de cliente, tópicos ou filas e a aprovação na lista de saída com o protocolo do broker.
5. Para **Barramento de integração**, prepare o endereço base, a credencial e o catálogo das operações liberadas.

### <font color="#15803D">Observações</font>

- Esses tipos aparecem na paleta de conectores com o selo **Próxima entrega** e não abrem.
- O broker da própria plataforma nunca pode ser usado como destino.

***

## <font color="#15803D">13.14 Tipo SEI</font>

ID BSC-ITG-14

### <font color="#15803D">Para que serve</font>

Abre e acompanha processos no SEI pelo módulo REST oficial do SEI, entrando com um **usuário de serviço** da organização. O Bússola/BSC só faz o que o perfil desse usuário permite, e tudo aparece no SEI como feito por ele.

Uso no BSC: a execução de uma entrega ou atividade pode ser acompanhada por um processo SEI (quando concluído em todas as unidades, a entrega vai a 100% na data do último andamento); abrir processo, incluir relatório em PDF e lançar andamento são disparados pelos conectores.

**Quem usa:** Analista de Integração de Dados; Administrador do sistema.

### <font color="#15803D">Passo a passo</font>

1. Peça à área de TI que administra o SEI: a instalação do módulo REST oficial no SEI de homologação, um usuário de serviço não pessoal com perfil básico lotado na unidade de acompanhamento da estratégia, a senha, o endereço https\:// e a liberação de rede.
2. Peça ao administrador do sistema a aprovação do servidor do SEI (por exemplo, sei.exemplo.com.br) na lista de saída.
3. Integrações › Integrações › **Nova integração** › SEI; informe nome, código, objetivo e ambiente.
4. Em **Endereço**, informe a URL base e, só se a TI instalou o módulo em outra pasta, o caminho da API.
5. Em **Autenticação**, informe a sigla do usuário de serviço e a senha (podem ficar em branco até serem entregues).
6. Clique em **Testar**: a primeira etapa confirma o módulo; a segunda entra com o usuário e lista as unidades.
7. Em **Avançado**, escolha o órgão e a **Unidade padrão** na lista e marque as **Operações habilitadas no Bússola/BSC**.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/uYo0aUL9quw1nU_6TTaSJ_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 151 — Integração do SEI com o teste em duas etapas

### <font color="#15803D">Observações</font>

- Operações possíveis: listar catálogos, abrir processo, incluir relatório, lançar andamento, consultar processo, ler o histórico e listar documentos. A trava do que o Bússola/BSC faz é o campo de operações habilitadas.
- Sem usuário ou senha, o teste diz "Módulo encontrado; aguardando o usuário de serviço e a senha do SEI" e a integração aparece desabilitada na escolha, com o motivo.
- A sessão devolvida pelo SEI fica só em memória e é descartada ao fim; ao vencer, o Bússola/BSC entra de novo uma vez.
- Processo sigiloso, de unidade sem lotação ou inexistente aparece igual: "Processo não encontrado ou sem acesso no SEI". Nenhuma mensagem do SEI é gravada.
- "Resultado incerto: o SEI não respondeu à criação": o Bússola/BSC não repete a abertura sozinho; confira no SEI.
- O endereço precisa ser https\://. Se a política da organização não aceitar usuário de serviço, a alternativa é o cadastro do Bússola/BSC como sistema no SEI, em entrega própria.

***

## <font color="#15803D">13.15 Tipo SIAFI: API Dados SIAFI (STA)</font>

ID BSC-ITG-15

### <font color="#15803D">Para que serve</font>

O tipo SIAFI traz a execução do orçamento (empenhado, liquidado, pago) para o Bússola/BSC, com cinco canais num tipo só. O canal padrão é a **API Dados SIAFI (STA)**, fonte primária de empenhos com itens, restos a pagar e saldos contábeis. Em nenhum canal o Bússola/BSC envia dado ao SIAFI.

**Quem usa:** Analista de Integração de Dados; Administrador do sistema; Gestor de Desempenho.

### <font color="#15803D">Passo a passo</font>

1. Obtenha com a área de orçamento: usuário e senha de serviço do STA (só consulta), unidade gestora (6 dígitos), gestão (5 dígitos) e órgão (5 dígitos), com zeros à esquerda.
2. Peça à contabilidade a confirmação das contas contábeis que formam disponível, empenhado, liquidado e pago, e à área de orçamento a fórmula do indicador de execução do orçamento.
3. Peça ao administrador do sistema a aprovação do servidor do STA na lista de saída (HTTPS, porta 443).
4. Integrações › Integrações › **Nova integração** › SIAFI › Canal **API Dados SIAFI (STA)**.
5. Preencha UG e gestão em Endereço; usuário e senha em Autenticação; órgão, exercício, tamanho máximo de resposta e tempos em Avançado.
6. Clique em **Testar**: o Bússola/BSC entra no STA, procura a UG e confere a gestão.

### <font color="#15803D">Observações</font>

- Sem credencial nada é chamado e o resultado é "Aguardando usuário e senha do STA"; a integração fica fora dos conectores até um teste com sucesso.
- A captura lê itens de empenho do exercício ou alterados nos últimos dias, restos a pagar, saldos contábeis da UG e do órgão, e as visões derivadas de posição orçamentária e execução por nota de empenho.
- Os dados chegam com defasagem, não em tempo real.
- Credor pessoa física chega sem CPF e nome, a menos que a opção de mantê-los seja ligada.
- O STA não pagina: acima do tamanho máximo de resposta a captura fica parcial. Cada captura tem até 10 minutos.
- Erros comuns: credencial recusada; UG não encontrada; resposta acima do tamanho máximo; contas contábeis de cada grupo não informadas no conector.

***

## <font color="#15803D">13.16 Tipo SIAFI: Portal da Transparência, Tesouro Gerencial e web services</font>

ID BSC-ITG-16

### <font color="#15803D">Para que serve</font>

Além do STA, o tipo SIAFI oferece canais alternativos: dados abertos do **Portal da Transparência** (sem credencial do SIAFI), **relatório extraído do Tesouro Gerencial** (arquivo enviado por um servidor habilitado) e **web services do SIAFI** (integração oficial que exige adesão formal).

**Quem usa:** Analista de Integração de Dados; Administrador do sistema.

### <font color="#15803D">Passo a passo</font>

1. Integrações › Integrações › **Nova integração** › SIAFI › escolha o **Canal**.
2. Portal da Transparência: obtenha a chave gratuita da API de dados por um e-mail institucional da área responsável, informe UG, gestão, órgão e exercício, peça a aprovação do servidor do Portal na lista de saída e clique em **Testar**.
3. Tesouro Gerencial: peça um relatório CSV (separador ;) ou XLSX, de até 20 MB, sem colunas de favorecido pessoa física; informe formato, codificação, separador, linha do cabeçalho e aba.
4. Web services do SIAFI: cadastre endereço, certificado e senha, UG, gestão, órgão e exercício; o teste informa o que falta (adesão, certificado de aplicação e homologação).

### <font color="#15803D">Observações</font>

- Portal: sem chave nada é chamado ("Aguardando a chave"); com chave, o teste lê uma página da despesa anual do órgão. A captura lê documentos de despesa por dia (até 31 dias) e por fase, itens dos empenhos e despesa anual do órgão.
- Portal: se o ritmo for excedido, o Bússola/BSC espera dentro do tempo da execução; se o tempo acabar, a captura fica parcial e o histórico diz a última página lida.
- Tesouro Gerencial: o Bússola/BSC não acessa o sistema; o arquivo é enviado numa captura manual do conector. O teste responde "Pronto". Uma coluna chamada só "ND" nunca é ligada pelo nome: quem configura o De-Para escolhe.
- O histórico de cada captura guarda o nome do arquivo e a impressão digital do conteúdo: o reenvio do mesmo arquivo é reconhecível.
- Web services do SIAFI não são oferecidos aos conectores até a adesão estar completa.

***

## <font color="#15803D">13.17 Canais de mensagem como tipos do hub</font>

ID BSC-ITG-17

### <font color="#15803D">Para que serve</font>

Microsoft Teams, Discord e WhatsApp também são cadastrados no hub como tipos de integração da família Mensageria. Eles publicam os avisos do Bússola/BSC num canal ou enviam alertas pessoais, e são usados pelos conectores que enviam mensagem.

**Quem usa:** Analista de Integração de Dados; Diretoria de Estratégia.

### <font color="#15803D">Passo a passo</font>

1. Integrações › Integrações › **Nova integração** › grupo Mensageria › escolha Microsoft Teams, Discord ou WhatsApp.
2. Cadastre e teste a integração seguindo o capítulo de mensageria.
3. Ligue os canais de Teams e Discord às unidades em **Integrações › Canais de área** (tarefa da Diretoria de Estratégia).
4. Use a integração num conector que envia mensagem.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/EdECacO52wgC9ni9MLC4j_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 152 — Canais de área ligados às unidades

### <font color="#15803D">Observações</font>

- O endereço de um webhook de Teams ou Discord é um segredo: fica cifrado e nunca volta à tela.
- Enquanto houver um canal ativo usando a integração, ela não pode ser desativada no hub.
- Os detalhes de cada canal, do consentimento do WhatsApp e das mensagens estão no capítulo de mensageria.

***

## <font color="#15803D">13.18 Sistemas corporativos sob demanda</font>

ID BSC-ITG-18

### <font color="#15803D">Para que serve</font>

Na tela **Nova integração**, o grupo **Sistemas corporativos — sob demanda** apresenta, com o selo **Disponível sob demanda**, integrações que o produto pode oferecer com outros sistemas corporativos: **GRCS** (GRC corporativo), **Agility** (gestão de cards) e **ServiceNow SPM** (portfólio estratégico). Elas não estão habilitadas na instalação: não há formulário, nada é gravado e o Bússola/BSC nunca chama o outro sistema.

**Quem usa:** Analista de Integração de Dados; Diretoria de Estratégia; Administrador do sistema.

### <font color="#15803D">Passo a passo</font>

1. Integrações › Integrações › **Nova integração** › grupo Sistemas corporativos — sob demanda.
2. Abra o cartão do sistema para ver o que a integração faria em cada direção (Enviar e Capturar) e os campos e segredos que pediria.
3. Use **Testar** para confirmar a situação: "Integração disponível sob demanda — não habilitada nesta instalação".
4. Para habilitar, solicite ao provedor contratado.
5. Na configuração de conectores, monte e salve o conector com o componente sob demanda para deixar a regra pronta.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/WokAPJ8jAKgk5a-D4vuTy_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 153 — Vitrine dos sistemas corporativos sob demanda na tela Nova integração

### <font color="#15803D">Observações</font>

- GRCS: enviaria um risco, uma não conformidade ou um achado de auditoria quando uma regra do BSC disparasse, e acompanharia o estado do registro aberto. Pediria URL base, chave de acesso de conta de serviço, segredo de assinatura do webhook, ações habilitadas e os de-para de criticidade → severidade e de natureza do risco → categoria.
- Agility: criaria um card vinculado a cada tarefa do BSC e moveria o card conforme o percentual; ao contrário, atualizaria o percentual da tarefa quando o card mudasse de raia, por um de-para raia → percentual (por exemplo, Backlog 0%, Em andamento 50%, Homologação 90%, Produção 100%). Pediria URL, endereço do token, id e segredo do cliente, workspace, board e raia de entrada.
- ServiceNow SPM: vincularia demandas e projetos do portfólio a ações estratégicas e sincronizaria o progresso nos dois sentidos. Pediria endereço da instância, cliente OAuth, usuário de serviço, tabelas de projetos e demandas e um filtro de portfólio.
- Conectores com componente sob demanda podem ser configurados e salvos; cada execução fica registrada como "Sob demanda — não habilitado aqui".

***

## <font color="#15803D">13.19 Ambiente de simulação para treinamento e homologação</font>

ID BSC-ITG-19

### <font color="#15803D">Para que serve</font>

Para treinar usuários e homologar o lado do Bússola/BSC antes de os sistemas reais estarem disponíveis, existe um **ambiente de simulação** que responde como o SEI, a API Dados SIAFI (STA) e o Portal da Transparência nas operações que o Bússola/BSC usa, com dados fictícios.

**Quem usa:** Analista de Integração de Dados; Gestor de Desempenho.

### <font color="#15803D">Passo a passo</font>

1. Integrações › Integrações › localize as integrações marcadas com o selo **Simulador**.
2. Use-as para testar e exercitar os fluxos de ponta a ponta (entrar com usuário de serviço, abrir processo, incluir relatório, lançar andamento; capturar empenhos e saldos; ler documentos de despesa).
3. Mantenha ao lado a integração real do mesmo tipo, cadastrada com os campos definitivos; o Testar dela mostra exatamente o que falta.
4. Quando os acessos reais forem entregues, preencha a credencial na integração real e teste de novo, sem mudar mais nada.

### <font color="#15803D">Observações</font>

- A integração de simulação é do mesmo tipo da integração real e leva o selo Simulador em toda tela onde aparece.
- A simulação prova o lado do Bússola/BSC, não o sistema real: não prova acentuação gravada no sistema real, limites reais de uso, mensagens reais de erro nem o significado das contas contábeis.
- O ambiente de simulação só é alcançável em ambientes de treinamento e homologação; num ambiente de produção a marca de simulação é recusada.

***

## <font color="#15803D">13.20 Conectores do BSC: a paleta de componentes</font>

ID BSC-ITG-20

### <font color="#15803D">Para que serve</font>

A **Configuração de conectores** põe as integrações do hub para trabalhar no BSC. A tela abre com a **paleta**: um ícone por componente, lido do catálogo do hub, mais os canais próprios do Bússola/BSC. Cada componente mostra se envia, recebe ou os dois, e o que faz em cada direção.

**Quem usa:** Gestor de Desempenho; Analista de Integração de Dados; Diretoria de Estratégia.

### <font color="#15803D">Passo a passo</font>

1. Gestão por indicadores › Configuração de conectores › veja a paleta de componentes.
2. Identifique o grupo: Canais do Bússola/BSC (Sino, E-mail, Push), Mensageria (WhatsApp, Teams, Discord), Dados e governo disponíveis, Sistemas corporativos sob demanda ou Próximas entregas.
3. Passe pelo componente para ler o que ele faz ao enviar e ao receber.
4. Clique no componente desejado para montar um conector.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/Ee-20ntCgkuum3eqFv0xm_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 154 — Configuração de conectores com a paleta de componentes

### <font color="#15803D">Observações</font>

- Configuram: Gestor de Desempenho e Analista de Integração de Dados. A Diretoria de Estratégia lê conectores e histórico, sem editar. Quem não lê as integrações não vê o menu.
- Canais do Bússola/BSC e Mensageria criam conectores que enviam mensagem; na mensageria a integração é opcional e liga os disparos ao monitor.
- Componentes de dados e governo exigem uma integração ativa e testada do mesmo tipo.
- Componentes de próximas entregas aparecem com o selo Próxima entrega e não abrem.

***

## <font color="#15803D">13.21 Montar um conector</font>

ID BSC-ITG-21

### <font color="#15803D">Para que serve</font>

O conector define quando agir (por condição ou por agenda), o que fazer (enviar mensagem, capturar dado ou enviar dado) e para quem. Antes de salvar, a simulação mostra o efeito sem enviar nada.

**Quem usa:** Gestor de Desempenho; Analista de Integração de Dados.

### <font color="#15803D">Passo a passo</font>

1. Gestão por indicadores › Configuração de conectores › clique no componente da paleta.
2. Em **Envia ou recebe**, para tipo de dado escolha a direção e a **integração do hub** (só aparecem as ativas e testadas; se a lista estiver vazia, a tela explica cada exclusão).
3. Em **Quando age**, escolha **Quando uma condição for alcançada** (atingimento abaixo de X% ou alcançou X%, faixa vermelho/amarelo/verde, apuração vencida, avanço da ação abaixo de/alcançou X%, entrega em atraso) com o escopo (ciclo, perspectiva, objetivo, unidade ou lista de registros), ou **Por agenda** (a cada N horas, diária, semanal ou mensal, hora de Brasília).
4. Ajuste **reavisar a cada N dias**, o **Teto diário de disparos** (padrão 50) e, se quiser, **Adicionar outros limiares** para criar conectores irmãos.
5. Em **O que faz**, escolha **Enviar mensagem** (canais, **Também enviar push**, destinatários, observação e **Avisar também quando normalizar**), **Capturar dado** (abre o De-Para) ou **Enviar dado**.
6. Clique em **Simular (sem enviar)** e confira registros do escopo, quem dispararia, reavisaria ou normalizaria, canais, destinos, a mensagem como ficaria, o aviso de teto e outros conectores sobre os mesmos registros.
7. Clique em **Salvar conector**.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/6iGMkXlI9p5esVcDeSSY3_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 155 — Conector aberto com componente, gatilho e ações

### <font color="#15803D">Observações</font>

- Teams e Discord exigem o destinatário "Canal da área"; o push vai a pessoas.
- O texto da mensagem segue o modelo **Alerta de conector do BSC** das mensagens institucionais; a observação vai ao final.
- Até um De-Para ser publicado, o conector de captura fica "De-Para a configurar" e cada execução é registrada sem ler o outro sistema.
- Enviar dado fica registrado como não disponível nesta versão ou sob demanda.
- Outros limiares só podem ser adicionados na criação e cada limiar tem estado próprio.
- "A integração ainda não passou no teste do hub": rode Testar na integração. Nomes de conector são únicos.

***

## <font color="#15803D">13.22 Como o conector dispara e sigilo</font>

ID BSC-ITG-22

### <font color="#15803D">Para que serve</font>

O conector dispara na **passagem** de normal para em alerta, não a cada medição, e só leva a cada pessoa o que ela pode ler. Isso evita excesso de avisos e vazamento de registros sigilosos.

**Quem usa:** Gestor de Desempenho; Analista de Integração de Dados; Diretoria de Estratégia.

### <font color="#15803D">Passo a passo</font>

1. Lance ou importe um valor no indicador: a avaliação roda logo depois.
2. Aguarde a varredura automática (a cada 15 minutos) ou, na ficha, clique em **Avaliar agora** (conector por agenda: **Executar agora**).
3. Acompanhe os registros em **Registros em alerta** e no **Histórico de disparos**.

### <font color="#15803D">Observações</font>

- Exemplo com "atingimento abaixo de 80%": 85% não dispara; 70% gera uma mensagem e o registro fica em alerta; 75% não gera nada (sem reaviso); 85% gera "Normalizado" (se marcado) e volta a normal.
- Duas avaliações ao mesmo tempo nunca mandam a mesma mensagem duas vezes.
- O conector vê só os registros que o dono (quem criou ou reativou) pode ler, e cada pessoa só recebe se puder ler o registro.
- Registro sigiloso nunca sai por WhatsApp, e-mail, Teams ou Discord: vai só ao sino de quem pode lê-lo (e push sem o nome). Sem sino nem push, o disparo fica "Retido: registro sigiloso".
- Quem não pode ler um registro vê "Registro reservado" na simulação e no histórico.

***

## <font color="#15803D">13.23 Ficha do conector e acompanhamento no monitor</font>

ID BSC-ITG-23

### <font color="#15803D">Para que serve</font>

A ficha reúne a regra, os canais, os destinatários, os registros em alerta e o histórico completo de disparos e alterações. Todo disparo também aparece no Monitor de integrações.

**Quem usa:** Gestor de Desempenho; Analista de Integração de Dados; Diretoria de Estratégia.

### <font color="#15803D">Passo a passo</font>

1. Gestão por indicadores › Configuração de conectores › abra o conector.
2. Confira componente, integração herdada, regra em uma frase, canais, destinatários, dono e situação.
3. Consulte **Registros em alerta** e o **Histórico de disparos** (quando, registro, passagem, valor e resultado).
4. Use **Simular**, **Avaliar agora** / **Executar agora**, **Pausar** / **Reativar** e **Editar** conforme a necessidade.
5. Integrações › Monitor de integrações › filtre pelo conector para ver cada disparo e cada aplicação do De-Para.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/6iGMkXlI9p5esVcDeSSY3_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 156 — Ficha do conector com histórico de disparos

### <font color="#15803D">Observações</font>

- Resultados possíveis de um disparo: Enviado, Pulado pelo teto, Retido por sigilo, Ninguém a avisar, De-Para a configurar, Sob demanda.
- Mudar a condição, o limiar ou o escopo zera os estados: a regra nova começa do normal.
- O conector se pausa sozinho, com o motivo visível, quando a integração é desativada no hub ou o dono perde a permissão; quem reativa passa a ser o dono.
- No monitor há uma linha por disparo, nunca duas; cada aplicação do De-Para gera uma linha do tipo De-Para aplicado, com as contagens.

***

## <font color="#15803D">13.24 De-Para: destinos</font>

ID BSC-ITG-24

### <font color="#15803D">Para que serve</font>

O **De-Para** traduz o que outro sistema manda no que o BSC guarda: qual coluna do dado capturado vai para qual campo de um objeto do BSC. Ele entrega cada linha ao dono do objeto e nunca grava direto em lugar nenhum.

**Quem usa:** Gestor de Desempenho; Analista de Integração de Dados.

### <font color="#15803D">Passo a passo</font>

1. Gestão por indicadores › Configuração de conectores › abra um conector que captura dado e clique em **Abrir o De-Para**.
2. Em **Novo De-Para para**, escolha o destino: Realizado de indicador, Meta de indicador, Execução de entrega, Execução de atividade, Item de portal do governo ou Só guardar as linhas.
3. Confira as condições do destino antes de montar as linhas.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/oQx59UL6RZoW96R2Fq0jl_image.png" size="74" isUploading="false" width="742" height="900" darkWidth="742" darkHeight="900" showCaption="false"}

Figura 157 — De-Para do conector com amostra e destinos

### <font color="#15803D">Observações</font>

- Realizado de indicador: grava como valor enviado por integração (mesmo valor = sem mudança; valor revisto = retificação com a versão anterior preservada). Exige o indicador marcado como alimentado por integração e o período terminado.
- Meta de indicador: a meta nasce rascunho e, com **Enviar para aprovação ao importar**, segue o fluxo de aprovação. Meta valendo ou em aprovação nunca é alterada.
- Execução de entrega ou atividade: grava pela sincronização da ação, por referência e só o que mudou. Exige a entrega vinculada a este conector na configuração de execução automática.
- Item de portal do governo: grava pela sincronização dos portais; a fonte do portal precisa ler a mesma integração do conector.
- Só guardar as linhas: as linhas ficam na área de preparação.
- Um objeto que o dono do conector não pode ler é recusado como "Destino não encontrado", sem revelar que existe.

***

## <font color="#15803D">13.25 De-Para: montar, validar e publicar</font>

ID BSC-ITG-25

### <font color="#15803D">Para que serve</font>

O De-Para é montado sobre uma amostra real do dado capturado, validado numa prévia que não grava nada e publicado como versão imutável.

**Quem usa:** Gestor de Desempenho; Analista de Integração de Dados.

### <font color="#15803D">Passo a passo</font>

1. No quadro **Amostra (o que chegou)**, confira as colunas; num conector SIAFI, clique em **Executar leitura de teste**; nos demais, execute antes a carga de dados da mesma integração.
2. Em **Novo De-Para para**, escolha o destino ou um modelo pronto (SIAFI — Execução do orçamento (%) ou SIAFI — % financeiro da entrega) e clique em **Criar rascunho**.
3. Num conector SIAFI, confira em **O que é lido do SIAFI (STA)** a operação e as contas contábeis propostas, confirme com a contabilidade e clique em **Salvar o que é lido**.
4. Em cada linha, escolha **Vem de**, a **Conversão** (como vem, sem espaços, maiúsculas, número, data, período, multiplicar, dividir, razão em percentual, valor fixo, valor quando vazio, juntar, parte do texto, tabela de equivalência), o parâmetro e o **padrão quando vazio**.
5. Defina o **Formato de número** e o **padrão de data**; se quiser, limite com **Só as linhas em que** (até 5 condições).
6. Clique em **Validar (prévia)** e confira, para até 50 linhas, o que criaria, ficaria sem mudança, retificaria, seria recusado (com motivo) ou ficaria fora.
7. Clique em **Publicar**.
8. Para mudar, use **Editar (nova versão)**; para tirar de uso, **Aposentar**.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/oQx59UL6RZoW96R2Fq0jl_image.png" size="74" isUploading="false" width="742" height="900" darkWidth="742" darkHeight="900" showCaption="false"}

Figura 158 — Linhas do De-Para com conversões e prévia da validação

### <font color="#15803D">Observações</font>

- Não há fórmula nem script: só a lista fechada de conversões.
- O produto nunca liga uma coluna pelo nome e nunca adivinha formato de número ou de data.
- Publicar exige validação sem pendências sobre a amostra atual e ao menos uma linha aceita. A versão publicada não muda mais; a anterior é aposentada na hora.
- Cada valor gravado cita o conector, a versão do De-Para e a linha de origem; medições antigas continuam citando a versão que as produziu.
- Os modelos SIAFI trazem uma hipótese de contas contábeis que precisa ser confirmada pela contabilidade antes de confiar nos números.
- Aposentar devolve o conector ao estado "De-Para a configurar".

***

## <font color="#15803D">13.26 De-Para: aplicar</font>

ID BSC-ITG-26

### <font color="#15803D">Para que serve</font>

A versão publicada do De-Para é aplicada a cada execução do conector de captura ou sob comando, sem duplicar dados e preservando o histórico de retificações.

**Quem usa:** Gestor de Desempenho; Analista de Integração de Dados.

### <font color="#15803D">Passo a passo</font>

1. Deixe o conector de captura executar pela agenda ou pela condição: ele lê o outro sistema e aplica a versão publicada.
2. Para aplicar às linhas atuais sem ler o outro sistema de novo, clique em **Aplicar agora** no topo do De-Para.
3. Confira as contagens (criadas, sem mudança, retificadas, recusadas, fora) e as linhas recusadas com o motivo.
4. Acompanhe a linha do tipo De-Para aplicado em **Integrações › Monitor de integrações**.

### <font color="#15803D">Observações</font>

- Uma linha recusada não impede as outras.
- Recapturar o mesmo dado não cria nada em dobro; um valor revisto pela origem retifica com a versão anterior preservada.
- Na execução de entrega, a entrega vinculada é sincronizada na hora; fato com data de hoje só entra na execução de amanhã.

***

## <font color="#15803D">13.27 Tabelas de equivalência</font>

ID BSC-ITG-27

### <font color="#15803D">Para que serve</font>

Uma tabela de equivalência traduz um código de outro sistema (por exemplo, o plano interno do SIAFI ou um PTRES) num objeto do BSC (entrega, atividade, ação, indicador) ou num texto. É usada pela conversão Tabela de equivalência do De-Para.

**Quem usa:** Gestor de Desempenho; Analista de Integração de Dados.

### <font color="#15803D">Passo a passo</font>

1. Integrações › Tabelas de equivalência › clique em **Nova tabela**.
2. Informe código e nome e escolha **Os códigos apontam para**.
3. Acrescente os códigos e escolha o objeto de cada um.
4. Clique em **Salvar tabela**.
5. No De-Para, use a conversão **Tabela de equivalência** e escolha a tabela.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/RuSCTf9PrnxLHE8QOpEpC_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 159 — Tabelas de equivalência

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/-3f_jHTuLLY4_ad7cAgsj_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 160 — Tabela de equivalência aberta com os códigos e objetos

### <font color="#15803D">Observações</font>

- Só aparecem os objetos que você pode ler.
- Maiúsculas e espaços nas pontas não contam na comparação.
- Um código que falta na tabela deixa a linha fora da captura; nunca é adivinhado.
- O histórico mostra quem mudou o quê; um objeto sigiloso aparece no histórico só pelo tipo.
- O modelo "% financeiro da entrega" cria a tabela PI → entrega se ela ainda não existir.

[title]  12. Dados: console SQL, consultas, cargas e portais
[path] Aplicações/BSC/

A área **Dados do Bússola/BSC** é onde a organização trabalha o dado que sustenta a estratégia: o Analista de Integração de Dados experimenta consultas no console SQL, publica consultas salvas com versão, traz dados de outros sistemas por cargas e mantém o catálogo dos portais do governo. Indicadores, controles diários, execução de ações e painéis passam a ser alimentados por essas consultas, sem extrações manuais.

Tudo roda sobre uma **base de leitura** preparada para isso: somente leitura, sem dado pessoal e sem o que é sigiloso. Cada execução fica registrada e pode ser acompanhada no **Monitor de integrações**, junto com os serviços agendados da plataforma.

As conexões com os outros sistemas (bancos, arquivos, APIs, SEI, SIAFI) são cadastradas no hub de integrações, descrito no capítulo seguinte.

***

## <font color="#15803D">12.1 Área de dados e base de leitura</font>

ID BSC-DAD-01

### <font color="#15803D">Para que serve</font>

A área **Dados do Bússola/BSC** reúne o que se faz com dados dentro do BSC: experimentar consultas, publicar consultas com versão, trazer dados de outros sistemas por cargas, apurar indicadores automaticamente e manter o catálogo dos portais do governo. As conexões com os outros sistemas ficam no menu **Integrações**; aqui fica o uso do dado.

Todas as consultas leem a **base de leitura**: um conjunto de visões preparadas sobre os dados de gestão do Bússola/BSC (ciclos, perspectivas, objetivos, indicadores, metas, medições, planos de ação, ações, programas, vínculos estratégicos, linhas importadas pelas cargas e itens dos portais). As tabelas internas do sistema, outros ambientes e o catálogo do servidor de banco não aparecem. A base é preparada uma única vez por ambiente pelo administrador de banco da organização, com um usuário de banco que só lê.

**Quem usa:** Analista de Integração de Dados; Gestor de Desempenho; Diretoria de Estratégia; Administrador do sistema.

### <font color="#15803D">Passo a passo</font>

1. Peça ao administrador do sistema que confirme que a base de leitura foi preparada no ambiente (tarefa única do administrador de banco).
2. Abra o menu **Dados do Bússola/BSC** e confira os itens disponíveis para o seu cargo: Console SQL, Consultas salvas, Cargas de dados, Portais do governo, Itens de portais e Categorias de itens.
3. Use o **Console SQL** para experimentar e as **Consultas salvas** para o que vai ser usado por indicadores, controles, painéis e cargas.
4. Acompanhe o resultado das execuções em **Integrações › Monitor de integrações**.

### <font color="#15803D">Observações</font>

- A base de leitura deixa de fora indicadores e objetivos sigilosos e tudo o que depende deles (metas, medições, planos e ações).
- Nenhum dado de pessoa aparece nas visões: nem responsável, nem quem registrou, nem quem aprovou.
- O usuário de banco da base de leitura é somente leitura: mesmo que algo escape da conferência do texto, o próprio banco recusa a escrita.
- Se a tela disser que a base de leitura não está disponível ou não está configurada, o roteiro de preparação ainda não rodou no ambiente; se disser que as visões serão criadas no próximo início, a aplicação precisa ser reiniciada. Nos dois casos, acione o administrador do sistema.

***

## <font color="#15803D">12.2 Console SQL</font>

ID BSC-DAD-02

### <font color="#15803D">Para que serve</font>

O console SQL permite que o Analista de Integração de Dados escreva uma consulta de leitura sobre a base de leitura e veja o resultado na hora, para desenhar a apuração de um indicador sem pedir extração à TI.

A consulta roda num ambiente cercado: só leitura, no máximo 1.000 linhas na pré-visualização, interrupção após 30 segundos e registro de toda execução, aceita ou recusada.

**Quem usa:** Analista de Integração de Dados.

### <font color="#15803D">Passo a passo</font>

1. Dados do Bússola/BSC › Console SQL › abra o console (o item aparece só para quem pode escrever e executar SQL na área de dados).
2. No cartão **Tabelas e colunas**, abra uma visão para ver as colunas e o tipo de cada uma, ou use a busca.
3. Clique numa coluna ou em **Inserir o nome** para colocá-la na consulta no ponto do cursor.
4. Escreva uma única consulta de leitura (select ou with … select). Use **Ctrl+Espaço** para abrir as sugestões de visões e colunas; setas escolhem, **Enter** ou **Tab** aceitam, **Esc** fecha.
5. Para cada parâmetro escrito como \:nome, informe em **Parâmetros** o tipo (data, número, texto, lista de textos ou unidade organizacional) e o valor.
6. Clique em **Pré-visualizar** e confira as colunas, as linhas, o tempo gasto e o eventual aviso de corte em 1.000 linhas.
7. Se o resultado foi cortado, filtre ou agrupe a consulta para ver o total.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/nDuzljZk7u6wljX3ejnHm_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 126 — Console SQL com o cartão Tabelas e colunas, o editor e o resultado da pré-visualização

### <font color="#15803D">Observações</font>

- A lista de tabelas e colunas é lida com o próprio usuário de leitura: o que aparece é exatamente o que a consulta consegue ler.
- O valor de um parâmetro vai ao banco como dado, nunca como parte do texto: um valor malicioso não altera a consulta.
- São recusadas: instruções de inclusão, alteração, exclusão ou criação; duas instruções no mesmo texto; funções que leem arquivos do servidor, esperam de propósito, mudam a sessão ou alcançam outro servidor; objetos fora das visões publicadas; ponto de interrogação solto (use \:nome ou as funções de JSON equivalentes).
- Subconsultas só são aceitas no FROM, no WHERE ou na lista de colunas.
- O limite é de duas execuções simultâneas por ambiente; se aparecer o aviso, aguarde e tente de novo.
- Quem atua em mais de uma empresa deve escolher a empresa no seletor do topo antes de pré-visualizar.

***

## <font color="#15803D">12.3 Consultas salvas: criar uma consulta</font>

ID BSC-DAD-03

### <font color="#15803D">Para que serve</font>

O console serve para experimentar; o que vai ser usado (pela apuração de um indicador, por um controle diário, por um painel ou por uma carga) vira uma **consulta salva**, com nome, finalidade, fonte e versões numeradas. O texto de uma versão publicada nunca muda, e quem usa a consulta continua na versão que escolheu até alguém trocá-la. Assim um número já apresentado à diretoria não muda em silêncio.

**Quem usa:** Analista de Integração de Dados; Gestor de Desempenho; Diretoria de Estratégia.

### <font color="#15803D">Passo a passo</font>

1. Dados do Bússola/BSC › Consultas salvas › clique em **Nova consulta**.
2. Informe um **nome** único (sem diferença entre maiúsculas e minúsculas) e uma descrição.
3. Escolha a **finalidade**: Apuração de indicador (exige a coluna de valor), Controle diário (exige referência, data e valor ou percentual), Conjunto de dados para painéis ou Carga de dados.
4. Escolha a **fonte**: **Base própria (somente leitura)** ou uma integração de banco de dados cadastrada no hub.
5. Clique em **Criar e abrir o editor** para ir à ficha da consulta.
6. Para mudar nome ou descrição depois, use **Renomear**.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/QaKEeCnacMHCldG5ZqGF__image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 127 — Lista de consultas salvas com finalidade, fonte e versão atual

### <font color="#15803D">Observações</font>

- Finalidade e fonte não mudam depois de criada a consulta.
- A finalidade Carga de dados exige uma integração de banco de dados como fonte.
- Uma integração de banco só executa SQL daqui depois de um teste com resultado OK: uma conta que pode escrever no banco nunca executa SQL escrito por uma pessoa.
- O Analista de Integração de Dados escreve, publica e desativa; a Diretoria de Estratégia e o Gestor de Desempenho veem lista, ficha, texto e versões e podem pré-visualizar a versão publicada informando só valores.

***

## <font color="#15803D">12.4 Consultas salvas: escrever e publicar uma versão</font>

ID BSC-DAD-04

### <font color="#15803D">Para que serve</font>

Na ficha da consulta o analista escreve o texto, declara os parâmetros, pré-visualiza, diz o papel de cada coluna e publica uma versão numerada com nota explicando o porquê da mudança.

**Quem usa:** Analista de Integração de Dados.

### <font color="#15803D">Passo a passo</font>

1. Dados do Bússola/BSC › Consultas salvas › abra a consulta.
2. Comece do zero, de uma consulta pronta em **Consultas pré-formatadas** (por exemplo, Medições do período, Meta versus realizado por período, Indicadores aprovados sem medição no período, Percentual de ações concluídas no período, Execução das ações com prazo no período) com **Usar no editor**, ou de uma tabela.
3. Para montar o SELECT sem escrever SQL, clique em **Usar esta tabela** no cartão Tabelas e colunas, desmarque as colunas que não interessam, dê a cada uma o nome de exibição e clique em **Colocar o SELECT no editor**.
4. Em **Parâmetros**, clique em **Declarar \:nome** para cada parâmetro do texto e escolha tipo, obrigatoriedade e valor padrão.
5. Clique em **Pré-visualizar**; se quiser, troque os valores em **Valores para a pré-visualização** (em branco vale o padrão).
6. Em **Colunas do resultado**, indique qual coluna é o valor (e os demais papéis exigidos pela finalidade) e os nomes de exibição.
7. Escreva a **nota da versão** e clique em **Publicar v1** (ou v2, v3…).

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/RHMDYjTJ_brVqCrA8PZ3o_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 128 — Ficha da consulta salva com editor, parâmetros, colunas do resultado e versões

### <font color="#15803D">Observações</font>

- Os parâmetros do período de apuração (início e fim do período, indicador e unidade) são preenchidos pelo Bússola/BSC e não se declaram; declará-los gera recusa.
- Na pré-visualização o período é o mês corrente e não há indicador nem unidade: um resultado vazio pode significar apenas que nada foi medido neste mês.
- O botão de publicar só se habilita depois de uma pré-visualização bem-sucedida do mesmo texto e dos mesmos parâmetros; ao publicar, o servidor executa e confere tudo de novo.
- Mensagens comuns: parâmetro usado e não declarado (ou declarado e não usado); coluna do papel que não aparece no resultado; valor que precisa ser numérico pelo tipo da coluna (converta no texto); "Nada mudou desde a versão N".

***

## <font color="#15803D">12.5 Consultas salvas: versões, comparação e desativação</font>

ID BSC-DAD-05

### <font color="#15803D">Para que serve</font>

Cada consulta guarda todas as versões publicadas. Quem só lê a área de dados pode executar a versão publicada informando valores, sem mexer no texto, e comparar versões antigas com a atual.

**Quem usa:** Analista de Integração de Dados; Gestor de Desempenho; Diretoria de Estratégia.

### <font color="#15803D">Passo a passo</font>

1. Dados do Bússola/BSC › Consultas salvas › abra a consulta.
2. No cartão **Versão atual**, confira texto, parâmetros, papéis, nomes das colunas, quem publicou e quando.
3. Clique em **Pré-visualizar esta versão** e informe os valores dos parâmetros para executar o texto publicado.
4. Em **Versões**, clique em **Comparar com a atual** para ver o texto de uma versão antiga ao lado da atual.
5. Abra o **Histórico** para ver criação, publicações (número e impressão digital do texto) e desativações, com autor e data.
6. Para retirar a consulta das escolhas, clique em **Desativar**.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/RHMDYjTJ_brVqCrA8PZ3o_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 129 — Versões da consulta com a comparação de textos

### <font color="#15803D">Observações</font>

- Desativar impede novas publicações e tira a consulta das escolhas; as versões continuam legíveis.
- Uma consulta em uso por indicador, carga ou painel não pode ser desativada.
- Na pré-visualização de uma versão publicada viajam só valores, nunca texto; por isso leitores da área de dados podem usá-la.

***

## <font color="#15803D">12.6 Consulta sobre banco externo</font>

ID BSC-DAD-06

### <font color="#15803D">Para que serve</font>

Uma consulta salva pode ter como fonte uma integração de **banco de dados** cadastrada no hub. Nesse caso a consulta lê o banco de outro sistema, pela conta somente leitura daquela integração, com os mesmos limites do console e sem armazenar nada.

**Quem usa:** Analista de Integração de Dados.

### <font color="#15803D">Passo a passo</font>

1. Cadastre e teste a integração de banco de dados em **Integrações › Integrações** até o teste dar OK.
2. Dados do Bússola/BSC › Consultas salvas › **Nova consulta** › escolha a integração de banco como fonte.
3. No cartão **Tabelas e colunas**, confira o que a conta da integração consegue ler, com nomes no formato esquema.tabela.
4. Escreva a consulta usando as sugestões do editor e clique em **Pré-visualizar**.
5. Declare parâmetros, papéis das colunas e publique como em qualquer consulta salva.

### <font color="#15803D">Observações</font>

- Enquanto a integração não tiver teste OK, o cartão explica o motivo e o editor continua aberto para escrever.
- Falhas de conexão aparecem como "O banco recusou o usuário ou a senha", "O banco informado não existe nesse servidor" ou "Não foi possível conectar ao banco": confira e teste a integração no hub.
- Um servidor fora da lista de saída aparece como "Endereço não aprovado", sem o nome do servidor; o analista vê o detalhe no teste da integração.
- O catálogo do servidor de banco não é exibido.

***

## <font color="#15803D">12.7 Cargas de dados: cadastrar uma carga</font>

ID BSC-DAD-07

### <font color="#15803D">Para que serve</font>

Uma **carga** traz linhas de outro sistema para dentro do Bússola/BSC, de um arquivo (CSV, TXT ou Excel), de um banco de dados (por uma consulta salva de finalidade Carga) ou de uma API REST, e guarda cada linha com a sua origem. O dado bruto importado alimenta depois consultas SQL, indicadores e painéis.

Não confunda com **Indicadores importados**, que recebe valores já calculados por chave de indicador.

**Quem usa:** Analista de Integração de Dados; Gestor de Desempenho; Diretoria de Estratégia.

### <font color="#15803D">Passo a passo</font>

1. Cadastre antes, em **Integrações › Integrações**, a integração de onde o dado vem: Arquivo, Banco de dados ou API REST.
2. Para banco, publique em **Consultas salvas** uma consulta de finalidade Carga sobre essa integração.
3. Dados do Bússola/BSC › Cargas de dados › clique em **Nova carga**, dê um nome e escolha a integração (e a consulta, se for banco).
4. Em **Origem dos dados**, para arquivo, diga **Como o arquivo chega** (enviado pelo analista ou baixado do endereço da integração), o **Formato**, a **Aba** (Excel) e a **Linha dos nomes das colunas** (0 = sem cabeçalho).
5. Em **Roda sozinha**, deixe vazio para seguir a periodicidade da integração, escolha outra periodicidade (por exemplo, diária às 06:00 de Brasília) ou **Só à mão**.
6. Em **Execuções com linhas guardadas** (1 a 50, padrão 10), defina quantas execuções mantêm as linhas.
7. Para arquivo enviado, em **Arquivo da carga**, escolha o arquivo e clique em **Enviar**.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/-kbTbo27005kFzcZKPmKF_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 130 — Lista de cargas de dados

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/MTTXeCmf4qFGWTd2j_QqH_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 131 — Carga aberta com origem dos dados, colunas e execuções

### <font color="#15803D">Observações</font>

- O tipo da integração define o tipo da carga e não muda depois.
- O Analista de Integração de Dados cadastra e configura; o analista e o Gestor de Desempenho executam; a Diretoria de Estratégia e o Gestor de Desempenho leem cargas, execuções e dados importados.
- As execuções mais antigas perdem as linhas guardadas, mas o histórico de execuções permanece.
- Limites: arquivo de até 20 MB e 200 mil linhas, até 200 colunas; Excel com compactação suspeita é recusado.
- Um endereço de arquivo fora da lista de saída é recusado; peça a aprovação ao administrador do sistema.

***

## <font color="#15803D">12.8 Cargas de dados: pré-visualizar e nomear as colunas</font>

ID BSC-DAD-08

### <font color="#15803D">Para que serve</font>

Antes da primeira execução, o analista pré-visualiza a fonte e confirma o nome e o tipo de cada coluna. Cada execução aplica sempre o que foi confirmado, de modo que o mesmo arquivo é lido do mesmo jeito todo dia.

**Quem usa:** Analista de Integração de Dados.

### <font color="#15803D">Passo a passo</font>

1. Dados do Bússola/BSC › Cargas de dados › abra a carga e clique em **Pré-visualizar** (até 50 linhas, sem gravar nada).
2. Confira o tipo sugerido para cada coluna e as células destacadas que não converteram.
3. Para cada coluna, ajuste **Importar**, **Chave no SQL** (minúsculas sem acento, números e \_), **Nome de exibição** e **Tipo** (Automático, Texto, Número, Data ou Sim/não).
4. Em **Como os números estão escritos**, escolha 1.234,56 (padrão brasileiro) ou 1,234.56.
5. Clique em **Confirmar N colunas**.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/MTTXeCmf4qFGWTd2j_QqH_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 132 — Pré-visualização da carga com tipos sugeridos e células não convertidas

### <font color="#15803D">Observações</font>

- Sem confirmar as colunas a carga não executa.
- Uma célula não convertida não impede a carga: a linha entra inteira, com o texto original guardado e a célula marcada.
- Fixe o tipo Número numa coluna de valores para que textos como "-" ou "a apurar" fiquem marcados como não convertidos.
- Datas são lidas como dd/mm/aaaa ou aaaa-mm-dd, nunca com o mês primeiro.
- Arquivo que não é UTF-8 é lido como Windows-1252 e a pré-visualização avisa: confira os acentos.
- Se o cabeçalho do arquivo mudar, a execução fica Parcial com "Colunas nomeadas que não vieram na fonte": pré-visualize e confirme de novo.

***

## <font color="#15803D">12.9 Cargas de dados: executar e acompanhar</font>

ID BSC-DAD-09

### <font color="#15803D">Para que serve</font>

A execução lê a fonte inteira e grava as linhas. O cartão **Execuções** mostra cada execução com resultado, contagens e o que exatamente foi lido, e garante que uma execução incompleta nunca substitua a última completa.

**Quem usa:** Analista de Integração de Dados; Gestor de Desempenho; Diretoria de Estratégia.

### <font color="#15803D">Passo a passo</font>

1. Dados do Bússola/BSC › Cargas de dados › abra a carga e clique em **Executar agora**.
2. Confira o resultado no topo e no cartão **Execuções**: quando, como (à mão ou agendada, e por quem), resultado, linhas importadas, células não convertidas e o que foi lido (arquivo com impressão digital, endereço e páginas da API, ou consulta e versão).
3. Interprete o resultado: **Concluída** (vira a execução corrente), Concluída com teto atingido, **Parcial (não corrente)** ou **Falhou** (com o motivo).
4. Para a execução automática, aguarde o horário configurado; a execução aparece como **Agendada**.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/MTTXeCmf4qFGWTd2j_QqH_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 133 — Cartão Execuções com resultado e origem de cada leitura

### <font color="#15803D">Observações</font>

- Uma execução parcial ou com falha nunca substitui a última completa: as consultas continuam vendo o dado anterior.
- Tetos: banco, 100 mil linhas ou 2 minutos; API, 100 páginas e 100 mil registros. Ao atingir o teto a execução entra até o limite e vira corrente, marcada como teto atingido.
- Duas execuções da mesma carga ao mesmo tempo não acontecem: a segunda é recusada com "já está em execução".
- Recusas do outro sistema aparecem com o código do hub (credencial recusada, pedido para diminuir o ritmo, erro interno), nunca com o texto devolvido por ele.
- O agendador verifica as cargas a cada 15 minutos.

***

## <font color="#15803D">12.10 Dados importados e consulta em SQL</font>

ID BSC-DAD-10

### <font color="#15803D">Para que serve</font>

O cartão **Dados importados** mostra as linhas trazidas pela carga com a cadeia completa de origem. As mesmas linhas ficam disponíveis na base de leitura para o console SQL e as consultas salvas.

**Quem usa:** Analista de Integração de Dados; Gestor de Desempenho; Diretoria de Estratégia.

### <font color="#15803D">Passo a passo</font>

1. Dados do Bússola/BSC › Cargas de dados › abra a carga e vá ao cartão **Dados importados**.
2. Veja as linhas da execução corrente ou escolha outra execução em **Ver linhas**.
3. Marque **Só linhas com célula não convertida** para revisar o que não converteu (o texto original aparece destacado).
4. Para usar o dado em SQL, consulte no console a visão de linhas importadas, filtrando pelo nome da carga e pela execução corrente, e leia os valores pelas Chaves no SQL confirmadas.
5. Publique a consulta como consulta salva se ela for alimentar indicador, controle ou painel.

### <font color="#15803D">Observações</font>

- A visão de linhas importadas traz o nome da carga, o início da execução, o número da linha, os valores convertidos, o texto original e a marca de execução corrente.
- Filtre pela execução corrente para ler só a última execução completa de cada carga.
- As linhas importadas não têm sigilo por linha: quem lê a área de dados e quem consulta a base de leitura vê todas. Carregar dado pessoal é decisão da organização, que deve limitar quem recebe esses cargos.

***

## <font color="#15803D">12.11 Apuração de indicador por consulta SQL</font>

ID BSC-DAD-11

### <font color="#15803D">Para que serve</font>

Uma consulta salva de finalidade **Indicador** alimenta um indicador calculado. O gestor escolhe a consulta no cartão do indicador e o serviço diário apura o valor na periodicidade do indicador, guardando o valor e uma nota de origem completa.

**Quem usa:** Analista de Integração de Dados; Gestor de Desempenho.

### <font color="#15803D">Passo a passo</font>

1. Escreva a consulta para devolver uma linha por período, usando os parâmetros de período, indicador e unidade preenchidos pelo Bússola/BSC.
2. Indique a coluna do valor no papel **VALUE**; se a consulta devolve várias linhas (uma por mês, por exemplo), indique a coluna de data no papel **PERIOD**.
3. Declare os parâmetros que o gestor vai preencher (por exemplo, o código da unidade) e publique a versão.
4. Gestão por indicadores › Indicadores › abra o indicador e, em **Origem do cálculo**, escolha **Consulta SQL** e a consulta.
5. Preencha os parâmetros exigidos e use **Testar** para conferir o valor.
6. Mantenha o indicador aprovado e com apuração automática marcada; use **Recalcular agora** para refazer o período corrente.
7. Quando o cartão avisar que uma nova versão da consulta está disponível, decida se religa o indicador à nova versão.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/2-8CPcQEZJAX2yX7Bi_Lv_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 134 — Ficha do indicador com a origem do cálculo por consulta SQL

### <font color="#15803D">Observações</font>

- O serviço diário roda às 02:00: atualiza o período em aberto e, na virada, consolida o anterior com o último valor apurado.
- O cartão fixa a versão da consulta: publicar uma versão nova não muda o número de quem usa a anterior. Religar à nova versão devolve o cartão a rascunho.
- Sem o papel PERIOD, mais de uma linha é recusada.
- Zero linhas não é zero: o período fica sem valor e o registro diz "sem dado".
- Falha (banco fora do ar, mais de dois minutos, mais de uma linha para o período, valor não numérico) não grava nada naquele indicador; os demais seguem sendo apurados.
- Numa consulta sobre banco externo nenhuma linha do outro sistema é copiada; ficam só o valor e a nota de origem, que seguem o sigilo do indicador.

***

## <font color="#15803D">12.12 Consultas de controle e retratos diários</font>

ID BSC-DAD-12

### <font color="#15803D">Para que serve</font>

Uma consulta de finalidade **Controle** (execução financeira ou cronograma) roda todo dia e guarda o resultado como o **retrato daquele dia**. A mesma consulta pode alimentar a execução física e financeira de entregas e atividades de uma ação estratégica.

**Quem usa:** Analista de Integração de Dados; Gestor de Desempenho; Responsável por ação/área.

### <font color="#15803D">Passo a passo</font>

1. Dados do Bússola/BSC › Consultas salvas › crie a consulta com finalidade Controle diário, indicando as colunas de referência, data e valor ou percentual, e publique.
2. Na ficha da consulta, acompanhe o cartão **Retratos diários** (dias, linhas, versão, hora e quem executou).
3. Clique em **Ver as linhas** para abrir um retrato.
4. Use **Executar agora** para guardar ou substituir o retrato de hoje.
5. Para alimentar uma ação estratégica, no cartão de execução automática da entrega ou atividade escolha a fonte **Consulta salva** e a consulta de controle; salve a configuração.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/TwPd0l_RoJZt1qZcpQeAp_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 135 — Execução automática de uma entrega alimentada por consulta salva

### <font color="#15803D">Observações</font>

- O serviço roda às 03:30, do primeiro dia do mês até o dia; acima de 1.000 linhas o retrato é marcado **Cortado em 1.000 linhas**.
- Declare só parâmetros com valor padrão: o serviço diário não tem quem preencha um parâmetro obrigatório e a execução é recusada.
- Na ação estratégica: PERIOD vira a data de cada linha, REF a chave, VALUE o valor executado, PERCENT o percentual físico e ACTUAL\_END a conclusão real. Atividade exige PERCENT; entrega exige VALUE ou PERCENT.
- A versão publicada no momento fica fixada na configuração da ação; para usar uma nova versão, salve a configuração de novo.
- Mais de 1.000 linhas, linha sem data ou percentual fora de 0 a 100 faz a sincronização falhar sem copiar nada; o motivo aparece com o número da linha.
- Executar agora exige a permissão de executar cargas.

***

## <font color="#15803D">12.13 Portais do governo: ver e configurar</font>

ID BSC-DAD-13

### <font color="#15803D">Para que serve</font>

Os portais da administração pública que a organização usa (como SEI, Gov.br e SIAFI) publicam produtos e serviços. O Bússola/BSC guarda esses itens, permite classificá-los em categorias próprias e vinculá-los à estratégia.

O Bússola/BSC não lê os portais por conta própria nesta tela: o catálogo de cada portal chega por uma **carga de dados** ou pelo **hub de integrações**. A maioria dos portais exige credencial ou adesão formal da organização; até lá, o portal aparece como **Não configurado**.

**Quem usa:** Analista de Integração de Dados; Gestor de Desempenho; Diretoria de Estratégia.

### <font color="#15803D">Passo a passo</font>

1. Dados do Bússola/BSC › Portais do governo › veja cada portal com situação (Não configurado, Pronto, Suspenso), origem dos itens, itens publicados e última sincronização.
2. Para um portal que não está na lista, clique em **Novo portal**.
3. Capture o catálogo do portal numa carga de dados e execute-a até ter uma execução completa.
4. Clique no nome do portal e, em **De onde vêm os itens**, escolha **Carga de dados** e a carga (ou a integração do hub, quando o portal for alimentado por conector).
5. Indique qual coluna é cada campo: **Código do item** e **Nome** (obrigatórios), Descrição, Categoria no portal, Tipo (produto ou serviço, com os textos que significam cada um) e Endereço (https).
6. Clique em **Salvar** e em **Pré-visualizar os primeiros itens** para ver os 20 primeiros e quantas linhas ficaram de fora.
7. Clique em **Ativar**: o portal fica Pronto e entra na sincronização diária.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/1ClcqxLAgXCtsmLYx2fLP_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 136 — Lista de portais do governo com situação e última sincronização

### <font color="#15803D">Observações</font>

- Não configurado significa dependência de credencial ou adesão, não "portal sem itens".
- Sem itens na pré-visualização, a ativação é recusada.
- Um portal alimentado pelo hub (API REST, SEI ou SIAFI) recebe os itens pelo De-Para do conector; aqui só se escolhe a integração.
- Mensagens comuns: "A carga ainda não tem uma execução completa" (execute a carga antes) e "As primeiras linhas da carga não viraram nenhum item" (confira as colunas de código e nome).

***

## <font color="#15803D">12.14 Portais do governo: sincronização</font>

ID BSC-DAD-14

### <font color="#15803D">Para que serve</font>

A sincronização atualiza os itens de cada portal pronto com a última execução completa da carga correspondente, preservando categorias e vínculos.

**Quem usa:** Analista de Integração de Dados; Gestor de Desempenho.

### <font color="#15803D">Passo a passo</font>

1. Dados do Bússola/BSC › Portais do governo › abra o portal.
2. Clique em **Sincronizar agora** para sincronizar na hora (ou aguarde a sincronização diária).
3. Confira o resultado: novos, alterados, inativados, publicados de novo e linhas deixadas de fora.
4. Acompanhe cada sincronização em **Integrações › Monitor de integrações**.

### <font color="#15803D">Observações</font>

- A sincronização automática roda todo dia às 04:00 para os portais prontos alimentados por carga.
- Item novo é incluído; item com qualquer campo diferente é alterado, com a data da alteração.
- Item que deixou de aparecer numa sincronização completa fica **Inativo na origem**: nunca é apagado e mantém categoria e vínculos; se voltar a ser publicado, fica ativo sozinho.
- Se a carga não trouxe o catálogo inteiro, a sincronização fica **Incompleta**: grava o que leu e não inativa nada.
- Uma falha no meio não grava nada; os itens continuam como estavam.

***

## <font color="#15803D">12.15 Categorias de itens e regras de classificação</font>

ID BSC-DAD-15

### <font color="#15803D">Para que serve</font>

As categorias próprias organizam os itens dos portais do jeito da organização. Regras atribuem uma categoria automaticamente aos itens que chegam sem categoria, a partir da categoria informada pelo portal.

**Quem usa:** Diretoria de Estratégia; Gestor de Desempenho; Analista de Integração de Dados.

### <font color="#15803D">Passo a passo</font>

1. Dados do Bússola/BSC › Categorias de itens › clique em **Nova categoria** e informe código, nome e descrição.
2. Em **Regras**, acrescente linhas: categoria no portal (texto), portal específico ou qualquer portal, e a categoria a atribuir.
3. Salve; a regra age na próxima sincronização.
4. Consulte o **Histórico** para ver cada mudança, inclusive nas regras.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/kmHGrN4C1E7WbVdGluIBi_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 137 — Categorias de itens com as regras de classificação

### <font color="#15803D">Observações</font>

- A comparação da categoria no portal ignora diferenças entre maiúsculas e minúsculas.
- A regra nunca troca uma categoria escolhida por uma pessoa.
- A mesma categoria no portal não pode ter regra em duas categorias: retire a regra da outra antes.
- Uma categoria inativa continua nos itens que já a têm, mas deixa de ser oferecida.
- Quem lê a área de dados apenas consulta as categorias.

***

## <font color="#15803D">12.16 Itens de portais: classificar e vincular à estratégia</font>

ID BSC-DAD-16

### <font color="#15803D">Para que serve</font>

A lista de itens permite filtrar, classificar em lote e abrir cada item para definir a categoria e os vínculos com programas, objetivos, indicadores e ações.

**Quem usa:** Diretoria de Estratégia; Gestor de Desempenho; Analista de Integração de Dados.

### <font color="#15803D">Passo a passo</font>

1. Dados do Bússola/BSC › Itens de portais › filtre por portal, categoria (inclusive Sem categoria), tipo, situação no portal e nome ou código.
2. Para classificar em lote, marque os itens, escolha a categoria e clique em **Classificar**.
3. Abra um item e, em **Nossa categoria**, escolha em **Classificar como** e clique em **Salvar categoria**.
4. Em **Vínculos com a estratégia**, escolha **Vincular a** (programa ou subprograma, objetivo estratégico, indicador, ação ou projeto), procure o **Destino** pelo nome, escreva uma observação e clique em **Vincular**.
5. Para desfazer, use **Desfazer vínculo**; marque **Mostrar vínculos desfeitos** para consultar os anteriores.
6. Consulte **Histórico da categoria** e **Histórico dos vínculos**.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/5nzKwZpJ3ocRCDN7n8LIT_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 138 — Itens de portais com filtros e classificação em lote

### <font color="#15803D">Observações</font>

- A classificação em lote aceita até 500 itens por vez; cada item registra a mudança no próprio histórico.
- Escolher **Sem categoria (volta para as regras)** devolve o item às regras automáticas.
- Desfazer vínculo mantém o registro de quem desfez e quando.
- Um vínculo com objetivo, indicador ou ação sigilosa que você não lê aparece como **Reservado**; o título nunca aparece, nem no histórico.
- "Destino não encontrado" ao vincular indica que o destino não existe ou é sigiloso para você.

***

## <font color="#15803D">12.17 Conteúdo da base de leitura</font>

ID BSC-DAD-17

### <font color="#15803D">Para que serve</font>

A base de leitura publica visões sobre os dados de gestão, sempre sem dado pessoal e sem o que é sigiloso. Conhecer o que entra e o que fica de fora evita surpresas ao montar consultas e painéis.

**Quem usa:** Analista de Integração de Dados; Gestor de Desempenho; Leitor/Auditor.

### <font color="#15803D">Passo a passo</font>

1. Dados do Bússola/BSC › Console SQL › abra o cartão **Tabelas e colunas** para ver as visões disponíveis.
2. Abra cada visão para conferir as colunas e os tipos.
3. Use a lista abaixo para saber o que cada grupo de visões traz e o que fica de fora.

### <font color="#15803D">Observações</font>

- Ciclos, perspectivas e programas/subprogramas: completos.
- Objetivos: sem os sigilosos e sem responsável. Indicadores: sem os sigilosos (ou de objetivo sigiloso), sem responsável, sem quem aprovou e sem fórmula interna.
- Metas: sem as de indicador oculto, sem quem aprovou e sem critério de aceite. Medições: só a medição corrente de cada período, sem versões antigas, sem quem registrou e sem nota.
- Planos de ação e ações: sem os sigilosos ou de indicador oculto, sem responsável e sem quem executa. Vínculos estratégicos: sem vínculos com objetivo ou indicador oculto.
- Linhas importadas pelas cargas: texto original e valor convertido, com carga, execução e marca de corrente; sem execuções que falharam sem importar e sem quem executou.
- Itens dos portais: com portal, categoria própria, situação e contagem de vínculos por tipo de destino; sem o nome dos destinos vinculados.
- Métricas de outros módulos entram sempre agregadas e sem pessoa, à medida que cada módulo publicar a sua visão.

***

## 12.18 Acesso de leitura para ferramentas de BI

ID BSC-DAD-18

### <font color="#15803D">Para que serve</font>

A mesma base de leitura pode ser lida diretamente no banco pela ferramenta de análise da organização (como Power BI, Metabase ou DBeaver), com uma conta de banco própria para BI. Essa conta é separada da usada pelo console SQL: tem senha própria e pode ser revogada sem afetar o Bússola/BSC.

**Quem usa:** Administrador do sistema; Analista de Integração de Dados.

### <font color="#15803D">Passo a passo</font>

1. Solicite ao administrador de banco da organização a criação da conta de leitura para BI, com o mesmo roteiro de preparação da base de leitura.
2. Solicite a liberação de rede necessária (só cabe em instalação dedicada).
3. Configure a ferramenta de BI com a conta recebida e aponte para as visões da base de leitura.
4. Para trocar a senha ou revogar o acesso, acione o administrador de banco.

### <font color="#15803D">Observações</font>

- A conta de BI lê as mesmas visões da base de leitura e executa SQL sobre elas; não escreve nem enxerga as tabelas do sistema, e o próprio banco recusa.
- Valem as mesmas exclusões de sigilo e de dado pessoal da base de leitura.
- Criar, trocar a senha e revogar são tarefas do administrador de banco, fora das telas do Bússola/BSC.

***

## <font color="#15803D">12.19 Registro das execuções</font>

ID BSC-DAD-19

### <font color="#15803D">Para que serve</font>

Toda execução de dados gera uma linha num registro único do ambiente, que responde "quem executou o quê, quando e com que resultado". É desse registro que o monitor de integrações e os sinais de falha de apuração nos painéis leem.

**Quem usa:** Analista de Integração de Dados; Gestor de Desempenho; Diretoria de Estratégia; Leitor/Auditor.

### <font color="#15803D">Passo a passo</font>

1. Execute qualquer operação de dados (pré-visualização, publicação, carga, apuração, retrato, sincronização).
2. Integrações › Monitor de integrações › localize a linha da execução pelos filtros.
3. Abra o detalhe para ver tipo, origem, quem executou, início, fim, duração, linhas lidas, corte, resultado e motivo.

### <font color="#15803D">Observações</font>

- Entram no registro: pré-visualizações do console e das consultas, a execução de conferência ao publicar, cada execução de carga (e a consulta da carga por banco), cada apuração de indicador, cada retrato diário, cada sincronização de portal, os testes e execuções das integrações do hub, a sincronização da execução das ações e cada lote de valores recebido por chave de integração (indicadores importados).
- Na recusa ou falha fica o código do motivo, nunca a mensagem técnica do banco.
- O texto das consultas ad hoc e dos rascunhos fica registrado; a execução de uma versão publicada aponta a versão.
- Os painéis marcam falha de apuração no indicador cuja última apuração falhou.

***

## <font color="#15803D">12.20 Monitor de integrações</font>

ID BSC-DAD-20

### <font color="#15803D">Para que serve</font>

O monitor reúne numa lista só todas as execuções do registro (cargas, apurações, controles diários, sincronizações das ações e dos portais, lotes recebidos, testes de conexão, execuções do hub e disparos de conectores), com sucesso ou falha por execução, e permite executar de novo o que falhou.

**Quem usa:** Analista de Integração de Dados; Gestor de Desempenho; Diretoria de Estratégia.

### <font color="#15803D">Passo a passo</font>

1. Integrações › Monitor de integrações › confira o resumo **Últimas 24 horas** (sucesso, parciais, falhas, interrompidas e em andamento).
2. No cartão **Falhas seguidas**, veja cada carga, consulta, indicador, ação ou serviço cuja última execução falhou, com a contagem desde o último sucesso; clique em **Ver as execuções** para filtrar.
3. Use os **Filtros** (tipo, resultado, integração e período); copie o endereço da página para compartilhar o filtro.
4. Abra o **Detalhe** (ícone de olho) para ver início, fim, duração, registros lidos e gravados, origem do dado, quem disparou, integração, parâmetros, contadores e o motivo traduzido.
5. Clique em **Executar novamente** no detalhe de uma carga, consulta de controle, sincronização de portal ou serviço agendado.
6. Para apuração de indicador, sincronização de ação ou teste de conexão, siga a indicação do detalhe (Recalcular agora no indicador, Sincronizar agora na ação, Testar na integração).

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/GLws9oVTanUCRmt_Y5kuH_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 139 — Monitor de integrações com resumo, falhas seguidas e lista de execuções

### <font color="#15803D">Observações</font>

- Se o resumo não puder ser lido, a tela diz que não conseguiu; nunca mostra "0 falhas".
- Falhas seguidas ficam em vermelho a partir de três.
- O filtro "qualquer falha" junta falha, tempo esgotado, recusa e interrompida.
- O motivo é sempre traduzido: nunca a mensagem técnica do banco ou do outro sistema, nem senha, token ou cabeçalho de autenticação.
- Executar novamente exige a permissão de executar cargas; quem não a tem vê quem pode.
- Execuções de indicador ou objetivo sigiloso e de ações fora do seu alcance aparecem como **Registro sigiloso**, sem nome nem parâmetros, e o detalhe não abre.
- As pré-visualizações do console SQL ficam fora da lista; só quem escreve consultas pode pedi-las pelo filtro de tipo.
- No cartão do indicador apurado automaticamente, **Últimas apurações** mostra resultado, origem, duração e motivo, com link para o monitor filtrado; se a execução já saiu do registro, o detalhe avisa que expirou.

***

## <font color="#15803D">12.21 Serviços agendados e manutenção do registro</font>

ID BSC-DAD-21

### <font color="#15803D">Para que serve</font>

O cartão **Serviços agendados** do monitor lista o que a plataforma executa sozinha, com a próxima execução e a última nesta organização, e permite rodar um serviço na hora. A manutenção diária do registro encerra execuções presas e apaga registros antigos.

**Quem usa:** Analista de Integração de Dados; Gestor de Desempenho; Administrador do sistema.

### <font color="#15803D">Passo a passo</font>

1. Integrações › Monitor de integrações › vá ao cartão **Serviços agendados**.
2. Confira, para cada serviço, a próxima execução e a última (resultado, quando, se foi agendada ou quem executou).
3. Clique em **Executar agora** para rodar o serviço só nesta organização, em segundo plano.
4. Acompanhe a linha **Em andamento** até ela mudar sozinha ao terminar.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/GLws9oVTanUCRmt_Y5kuH_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 140 — Cartão Serviços agendados no monitor de integrações

### <font color="#15803D">Observações</font>

- Horários (Brasília): apuração automática dos indicadores 02:00; alertas de desvio 02:30; sincronização da execução das ações 02:30; cargas agendadas a cada 15 minutos; consultas de controle 03:30; sincronização dos portais 04:00; manutenção do registro 05:00; prazos de apuração dos indicadores 07:00; resumo programado de hora em hora, aos 5 minutos.
- O botão Executar agora só aparece para quem tem a permissão do ato do serviço (gerir indicadores, registrar execução das ações, executar cargas ou configurar a mensageria). A execução fica registrada com o nome de quem clicou.
- Se o serviço já estiver rodando nesta organização, a tela pede para tentar de novo em um minuto; a execução da madrugada pula a organização cujo Executar agora ainda está rodando.
- Cargas agendadas e resumo programado só deixam linha quando trabalharam.
- Manutenção: execução que ficou em andamento por parada do servidor passa a **Interrompida** após 2 horas (6 horas para sincronização de portais); registros com mais de dois anos são apagados em lotes, exceto os de cargas e retratos que ainda existem.
- Parâmetros de texto livre podem conter dado pessoal digitado e seguem o mesmo prazo de retenção.

[title]  Índice de seções
[path] Aplicações/BSC/

Identificador estável de cada seção, o título e a página onde ela começa.

| <font color="#15803D">**ID**</font> | <font color="#15803D">**Nº**</font> | <font color="#15803D">**Título/ Link**</font>                                                                                                                                                                          |
| ----------------------------------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| BSC-INT-01                          | 1.1                                 | [O que é o Bússola/BSC](https://docs.citsmart.com/1-introducao-ao-bsc#11-o-que-o-bssolabsc)                                                                                                                            |
| BSC-INT-02                          | 1.2                                 | [Perfis funcionais](https://docs.citsmart.com/1-introducao-ao-bsc#12-perfis-funcionais)                                                                                                                                |
| BSC-INT-03                          | 1.3                                 | [Navegação pelo menu lateral](https://docs.citsmart.com/1-introducao-ao-bsc#13-navegao-pelo-menu-lateral)                                                                                                              |
| BSC-INT-04                          | 1.4                                 | [Seletor de empresa no cabeçalho](https://docs.citsmart.com/1-introducao-ao-bsc#14-seletor-de-empresa-no-cabealho)                                                                                                     |
| BSC-INT-05                          | 1.5                                 | [Ajuda contextual da tela](https://docs.citsmart.com/1-introducao-ao-bsc#15-ajuda-contextual-da-tela)                                                                                                                  |
| BSC-INT-06                          | 1.6                                 | [Trilha de alterações (quem mudou o quê)](https://docs.citsmart.com/1-introducao-ao-bsc#16-trilha-de-alteraes-quem-mudou-o-qu)                                                                                         |
| BSC-INT-07                          | 1.7                                 | [Discussão e compartilhamento entre áreas](https://docs.citsmart.com/1-introducao-ao-bsc#17-discusso-e-compartilhamento-entre-reas)                                                                                    |
| BSC-INT-08                          | 1.8                                 | [Seguir um registro](https://docs.citsmart.com/1-introducao-ao-bsc#18-seguir-um-registro)                                                                                                                              |
| BSC-INT-09                          | 1.9                                 | [Uso no celular e no tablet](https://docs.citsmart.com/1-introducao-ao-bsc#18-seguir-um-registro)                                                                                                                      |
| BSC-EST-01                          | 2.1                                 | [Criar um ciclo estratégico](https://docs.citsmart.com/2-estrategia-ciclos-objetivos-e-mapa-estrategico#21-criar-um-ciclo-estratgico)                                                                                  |
| BSC-EST-02                          | 2.2                                 | [Ativar e fechar o ciclo](https://docs.citsmart.com/2-estrategia-ciclos-objetivos-e-mapa-estrategico#22-ativar-e-fechar-o-ciclo)                                                                                       |
| BSC-EST-03                          | 2.3                                 | [Identidade institucional](https://docs.citsmart.com/2-estrategia-ciclos-objetivos-e-mapa-estrategico#23-identidade-institucional)                                                                                     |
| BSC-EST-04                          | 2.4                                 | [Perspectivas (eixos estratégicos)](https://docs.citsmart.com/2-estrategia-ciclos-objetivos-e-mapa-estrategico#24-perspectivas-eixos-estratgicos)                                                                      |
| BSC-EST-05                          | 2.5                                 | [Régua de desempenho](https://docs.citsmart.com/2-estrategia-ciclos-objetivos-e-mapa-estrategico#25-rgua-de-desempenho)                                                                                                |
| BSC-EST-06                          | 2.6                                 | [Criar objetivos do plano](https://docs.citsmart.com/2-estrategia-ciclos-objetivos-e-mapa-estrategico#26-criar-objetivos-do-plano)                                                                                     |
| BSC-EST-07                          | 2.7                                 | [Desdobramento em cascata e pesos](https://docs.citsmart.com/2-estrategia-ciclos-objetivos-e-mapa-estrategico#27-desdobramento-em-cascata-e-pesos)                                                                     |
| BSC-EST-08                          | 2.8                                 | [Cadastros estratégicos: programas e subprogramas](https://docs.citsmart.com/2-estrategia-ciclos-objetivos-e-mapa-estrategico#28-cadastros-estratgicos-programas-e-subprogramas)                                       |
| BSC-EST-09                          | 2.9                                 | [ODS, classificações de entrega, regiões e sistemas externos](https://docs.citsmart.com/2-estrategia-ciclos-objetivos-e-mapa-estrategico#29-ods-classificaes-de-entrega-regies-e-sistemas-e)                           |
| BSC-EST-10                          | 2.10                                | [Áreas do plano](https://docs.citsmart.com/2-estrategia-ciclos-objetivos-e-mapa-estrategico#210-reas-do-plano)                                                                                                         |
| BSC-EST-11                          | 2.11                                | [Programas e áreas do objetivo e do indicador](https://docs.citsmart.com/2-estrategia-ciclos-objetivos-e-mapa-estrategico#211-programas-e-reas-do-objetivo-e-do-indicador)                                             |
| BSC-EST-12                          | 2.12                                | [Mapa estratégico: infográfico e sinalizadores](https://docs.citsmart.com/2-estrategia-ciclos-objetivos-e-mapa-estrategico#212-mapa-estratgico-infogrfico-e-sinalizadores)                                             |
| BSC-EST-13                          | 2.13                                | [Mapa estratégico: detalhamento e visão consolidada](https://docs.citsmart.com/2-estrategia-ciclos-objetivos-e-mapa-estrategico#213-mapa-estratgico-detalhamento-e-viso-consolidad)                                    |
| BSC-IND-01                          | 3.1                                 | [Lista de indicadores](https://docs.citsmart.com/3-indicadores-e-desempenho#31-lista-de-indicadores)                                                                                                                   |
| BSC-IND-02                          | 3.2                                 | [Criar a ficha do indicador](https://docs.citsmart.com/3-indicadores-e-desempenho#32-criar-a-ficha-do-indicador)                                                                                                       |
| BSC-IND-03                          | 3.3                                 | [Configurar a linha do tempo do indicador](https://docs.citsmart.com/3-indicadores-e-desempenho#33-configurar-a-linha-do-tempo-do-indicador)                                                                           |
| BSC-IND-04                          | 3.4                                 | [Indicador calculado: métrica do catálogo ou fórmula](https://docs.citsmart.com/3-indicadores-e-desempenho#34-indicador-calculado-mtrica-do-catlogo-ou-frmula)                                                         |
| BSC-IND-05                          | 3.5                                 | [Apuração automática do indicador calculado](https://docs.citsmart.com/3-indicadores-e-desempenho#35-apurao-automtica-do-indicador-calculado)                                                                          |
| BSC-IND-06                          | 3.6                                 | [Lançar metas e faixa de tolerância](https://docs.citsmart.com/3-indicadores-e-desempenho#36-lanar-metas-e-faixa-de-tolerncia)                                                                                         |
| BSC-IND-07                          | 3.7                                 | [Aprovação do indicador e da meta](https://docs.citsmart.com/3-indicadores-e-desempenho#37-aprovao-do-indicador-e-da-meta)                                                                                             |
| BSC-IND-08                          | 3.8                                 | [Registrar, congelar e retificar a apuração](https://docs.citsmart.com/3-indicadores-e-desempenho#38-registrar-congelar-e-retificar-a-apurao)                                                                          |
| BSC-IND-09                          | 3.9                                 | [Apurar o indicador calculado e ler a memória de cálculo](https://docs.citsmart.com/3-indicadores-e-desempenho#39-apurar-o-indicador-calculado-e-ler-a-memria-de)                                                      |
| BSC-IND-10                          | 3.10                                | [Linha do tempo das medições](https://docs.citsmart.com/3-indicadores-e-desempenho#310-linha-do-tempo-das-medies)                                                                                                      |
| BSC-IND-11                          | 3.11                                | [Mudar a periodicidade, o início ou o número de medições](https://docs.citsmart.com/3-indicadores-e-desempenho#311-mudar-a-periodicidade-o-incio-ou-o-nmero-de-me)                                                     |
| BSC-IND-12                          | 3.12                                | [Evidências de apuração](https://docs.citsmart.com/3-indicadores-e-desempenho#312-evidncias-de-apurao)                                                                                                                 |
| BSC-IND-13                          | 3.13                                | [Indicadores importados (alimentados por integração)](https://docs.citsmart.com/3-indicadores-e-desempenho#313-indicadores-importados-alimentados-por-integra)                                                         |
| BSC-IND-14                          | 3.14                                | [Aviso automático de desvio](https://docs.citsmart.com/3-indicadores-e-desempenho#314-aviso-automtico-de-desvio)                                                                                                       |
| BSC-IND-15                          | 3.15                                | [Alertas de prazo de apuração](https://docs.citsmart.com/3-indicadores-e-desempenho#315-alertas-de-prazo-de-apurao)                                                                                                    |
| BSC-IND-16                          | 3.16                                | [Resumo programado dos indicadores automatizados](https://docs.citsmart.com/3-indicadores-e-desempenho#316-resumo-programado-dos-indicadores-automatizado)                                                             |
| BSC-IND-17                          | 3.17                                | [Painel de desempenho](https://docs.citsmart.com/3-indicadores-e-desempenho#317-painel-de-desempenho)                                                                                                                  |
| BSC-IND-18                          | 3.18                                | [Painel gerencial: visão consolidada do ciclo](https://docs.citsmart.com/3-indicadores-e-desempenho#318-painel-gerencial-viso-consolidada-do-ciclo)                                                                    |
| BSC-IND-19                          | 3.19                                | [Meu painel (fixar widgets)](https://docs.citsmart.com/3-indicadores-e-desempenho#319-meu-painel-fixar-widgets)                                                                                                        |
| BSC-IND-20                          | 3.20                                | [Indicadores sigilosos](https://docs.citsmart.com/3-indicadores-e-desempenho#320-indicadores-sigilosos)                                                                                                                |
| BSC-PAC-01                          | 4.1                                 | [Abrir um plano de ação a partir do indicador](https://docs.citsmart.com/4-planos-de-acao-5w2h#41-abrir-um-plano-de-ao-a-partir-do-indicador)                                                                          |
| BSC-PAC-02                          | 4.2                                 | [Detalhar as ações no formato 5W2H](https://docs.citsmart.com/4-planos-de-acao-5w2h#42-detalhar-as-aes-no-formato-5w2h)                                                                                                |
| BSC-PAC-03                          | 4.3                                 | [Situação da ação e fase do PDCA](https://docs.citsmart.com/4-planos-de-acao-5w2h#43-situao-da-ao-e-fase-do-pdca)                                                                                                      |
| BSC-PAC-04                          | 4.4                                 | [Análise de causa-raiz](https://docs.citsmart.com/4-planos-de-acao-5w2h#44-anlise-de-causa-raiz)                                                                                                                       |
| BSC-PAC-05                          | 4.5                                 | [Registrar a execução, as evidências e o histórico da ação](https://docs.citsmart.com/4-planos-de-acao-5w2h#45-registrar-a-execuo-as-evidncias-e-o-histrico-da)                                                        |
| BSC-PAC-06                          | 4.6                                 | [Aprovação e ciclo de vida do plano](https://docs.citsmart.com/4-planos-de-acao-5w2h#46-aprovao-e-ciclo-de-vida-do-plano)                                                                                              |
| BSC-PAC-07                          | 4.7                                 | [Atualizar a ação pela Mesa de trabalho](https://docs.citsmart.com/4-planos-de-acao-5w2h#47-atualizar-a-ao-pela-mesa-de-trabalho)                                                                                      |
| BSC-PAC-08                          | 4.8                                 | [Planos de ação no Mapa estratégico](https://docs.citsmart.com/4-planos-de-acao-5w2h#48-planos-de-ao-no-mapa-estratgico)                                                                                               |
| BSC-PAC-09                          | 4.9                                 | [Discussão, sigilo e acesso ao plano](https://docs.citsmart.com/4-planos-de-acao-5w2h#49-discusso-sigilo-e-acesso-ao-plano)                                                                                            |
| BSC-ACE-01                          | 5.1                                 | [Categorias de ação](https://docs.citsmart.com/5-acoes-estrategicas#51-categorias-de-ao)                                                                                                                               |
| BSC-ACE-02                          | 5.2                                 | [Cadastrar uma ação estratégica](https://docs.citsmart.com/5-acoes-estrategicas#52-cadastrar-uma-ao-estratgica)                                                                                                        |
| BSC-ACE-03                          | 5.3                                 | [Priorizar com a matriz GUT](https://docs.citsmart.com/5-acoes-estrategicas#53-priorizar-com-a-matriz-gut)                                                                                                             |
| BSC-ACE-04                          | 5.4                                 | [Classificações do escopo (dimensões livres)](https://docs.citsmart.com/5-acoes-estrategicas#54-classificaes-do-escopo-dimenses-livres)                                                                                |
| BSC-ACE-05                          | 5.5                                 | [Montar o escopo: agrupadores e entregas](https://docs.citsmart.com/5-acoes-estrategicas#55-montar-o-escopo-agrupadores-e-entregas)                                                                                    |
| BSC-ACE-06                          | 5.6                                 | [Ver o escopo como organograma](https://docs.citsmart.com/5-acoes-estrategicas#56-ver-o-escopo-como-organograma)                                                                                                       |
| BSC-ACE-07                          | 5.7                                 | [Detalhar entregas em atividades, subtarefas e dependências](https://docs.citsmart.com/5-acoes-estrategicas#57-detalhar-entregas-em-atividades-subtarefas-e-de)                                                        |
| BSC-ACE-08                          | 5.8                                 | [Ler o cronograma no gráfico de Gantt](https://docs.citsmart.com/5-acoes-estrategicas#58-ler-o-cronograma-no-grfico-de-gantt)                                                                                          |
| BSC-ACE-09                          | 5.9                                 | [Registrar o andamento das atividades](https://docs.citsmart.com/5-acoes-estrategicas#59-registrar-o-andamento-das-atividades)                                                                                         |
| BSC-ACE-10                          | 5.10                                | [Planejamento financeiro mensal](https://docs.citsmart.com/5-acoes-estrategicas#510-planejamento-financeiro-mensal)                                                                                                    |
| BSC-ACE-11                          | 5.11                                | [Ver as entregas na ficha do indicador](https://docs.citsmart.com/5-acoes-estrategicas#511-ver-as-entregas-na-ficha-do-indicador)                                                                                      |
| BSC-ACE-12                          | 5.12                                | [Iniciar a ação e gerar a linha de base nº 1](https://docs.citsmart.com/5-acoes-estrategicas#512-iniciar-a-ao-e-gerar-a-linha-de-base-n-1)                                                                             |
| BSC-ACE-13                          | 5.13                                | [Comparar o plano com a linha de base](https://docs.citsmart.com/5-acoes-estrategicas#513-comparar-o-plano-com-a-linha-de-base)                                                                                        |
| BSC-ACE-14                          | 5.14                                | [Solicitar e decidir uma mudança (nova linha de base)](https://docs.citsmart.com/5-acoes-estrategicas#513-comparar-o-plano-com-a-linha-de-base)                                                                        |
| BSC-ACE-15                          | 5.15                                | [Suspender, retomar, concluir ou cancelar a ação](https://docs.citsmart.com/5-acoes-estrategicas#515-suspender-retomar-concluir-ou-cancelar-a-ao)                                                                      |
| BSC-ACE-16                          | 5.16                                | [Execução física e financeira das entregas](https://docs.citsmart.com/5-acoes-estrategicas#516-execuo-fsica-e-financeira-das-entregas)                                                                                 |
| BSC-ACE-17                          | 5.17                                | [Evidências da execução](https://docs.citsmart.com/5-acoes-estrategicas#517-evidncias-da-execuo)                                                                                                                       |
| BSC-ACE-18                          | 5.18                                | [Comentários na entrega e na ação](https://docs.citsmart.com/5-acoes-estrategicas#518-comentrios-na-entrega-e-na-ao)                                                                                                   |
| BSC-ACE-19                          | 5.19                                | [Execução automatizada: lançamentos contábeis e indicador](https://docs.citsmart.com/5-acoes-estrategicas#519-execuo-automatizada-lanamentos-contbeis-e-indi)                                                          |
| BSC-ACE-20                          | 5.20                                | [Execução automatizada: conclusão de processo do SEI](https://docs.citsmart.com/5-acoes-estrategicas#520-execuo-automatizada-concluso-de-processo-do-se)                                                               |
| BSC-ACE-21                          | 5.21                                | [Sincronização, falhas e correção de linhas integradas](https://docs.citsmart.com/5-acoes-estrategicas#521-sincronizao-falhas-e-correo-de-linhas-integrad)                                                             |
| BSC-ACE-22                          | 5.22                                | [Carteira consolidada: o que a tela mostra](https://docs.citsmart.com/5-acoes-estrategicas#522-carteira-consolidada-o-que-a-tela-mostra)                                                                               |
| BSC-ACE-23                          | 5.23                                | [Carteira: ordenar, filtrar e exportar](https://docs.citsmart.com/5-acoes-estrategicas#523-carteira-ordenar-filtrar-e-exportar)                                                                                        |
| BSC-ACE-24                          | 5.24                                | [Histórico da ação](https://docs.citsmart.com/5-acoes-estrategicas#524-histrico-da-ao)                                                                                                                                 |
| BSC-ACE-25                          | 5.25                                | [Riscos da ação estratégica](https://docs.citsmart.com/5-acoes-estrategicas#525-riscos-da-ao-estratgica)                                                                                                               |
| BSC-ACE-26                          | 5.26                                | [Perfis de acesso e sigilo da carteira](https://docs.citsmart.com/5-acoes-estrategicas#526-perfis-de-acesso-e-sigilo-da-carteira)                                                                                      |
| BSC-MES-01                          | 6.1                                 | [O que aparece na mesa de trabalho](https://docs.citsmart.com/6-mesa-de-trabalho#61-o-que-aparece-na-mesa-de-trabalho)                                                                                                 |
| BSC-MES-02                          | 6.2                                 | [Janelas de prazo e filtro por tipo](https://docs.citsmart.com/6-mesa-de-trabalho#62-janelas-de-prazo-e-filtro-por-tipo)                                                                                               |
| BSC-MES-03                          | 6.3                                 | [Atualizar indicadores, atividades e entregas pela mesa](https://docs.citsmart.com/6-mesa-de-trabalho#63-atualizar-indicadores-atividades-e-entregas-pel)                                                              |
| BSC-MES-04                          | 6.4                                 | [Atualizar ações 5W2H, encaminhamentos, reuniões e tratamentos de risco](https://docs.citsmart.com/6-mesa-de-trabalho#64-atualizar-aes-5w2h-encaminhamentos-reunies-e-tr)                                              |
| BSC-MES-05                          | 6.5                                 | [Quem pode usar a mesa e quando ela recusa](https://docs.citsmart.com/6-mesa-de-trabalho#65-quem-pode-usar-a-mesa-e-quando-ela-recusa)                                                                                 |
| BSC-MES-06                          | 6.6                                 | [Mesa de trabalho no celular](https://docs.citsmart.com/6-mesa-de-trabalho#66-mesa-de-trabalho-no-celular)                                                                                                             |
| BSC-AGE-01                          | 7.1                                 | [Categorias da agenda](https://docs.citsmart.com/7-agenda-estrategica#71-categorias-da-agenda)                                                                                                                         |
| BSC-AGE-02                          | 7.2                                 | [Navegar no calendário](https://docs.citsmart.com/7-agenda-estrategica#72-navegar-no-calendrio)                                                                                                                        |
| BSC-AGE-03                          | 7.3                                 | [Agenda no celular](https://docs.citsmart.com/7-agenda-estrategica#73-agenda-no-celular)                                                                                                                               |
| BSC-AGE-04                          | 7.4                                 | [Cadastrar um evento ou reunião](https://docs.citsmart.com/7-agenda-estrategica#74-cadastrar-um-evento-ou-reunio)                                                                                                      |
| BSC-AGE-05                          | 7.5                                 | [Participantes internos e externos](https://docs.citsmart.com/7-agenda-estrategica#75-participantes-internos-e-externos)                                                                                               |
| BSC-AGE-06                          | 7.6                                 | [Responder à presença](https://docs.citsmart.com/7-agenda-estrategica#76-responder-presena)                                                                                                                            |
| BSC-AGE-07                          | 7.7                                 | [Remarcar, mudar a situação e consultar o histórico](https://docs.citsmart.com/7-agenda-estrategica#77-remarcar-mudar-a-situao-e-consultar-o-histrico)                                                                 |
| BSC-AGE-08                          | 7.8                                 | [Eventos confidenciais](https://docs.citsmart.com/7-agenda-estrategica#78-eventos-confidenciais)                                                                                                                       |
| BSC-AGE-09                          | 7.9                                 | [Documentos e presença da reunião](https://docs.citsmart.com/7-agenda-estrategica#79-documentos-e-presena-da-reunio)                                                                                                   |
| BSC-AGE-10                          | 7.10                                | [Ata: salvar, finalizar e enviar, adendo](https://docs.citsmart.com/7-agenda-estrategica#710-ata-salvar-finalizar-e-enviar-adendo)                                                                                     |
| BSC-AGE-11                          | 7.11                                | [Encaminhamentos](https://docs.citsmart.com/7-agenda-estrategica#711-encaminhamentos)                                                                                                                                  |
| BSC-AGE-12                          | 7.12                                | [Enviar o evento aos participantes por e-mail](https://docs.citsmart.com/7-agenda-estrategica#712-enviar-o-evento-aos-participantes-por-e-mail)                                                                        |
| BSC-AGE-13                          | 7.13                                | [Enviar pelos canais integrados (WhatsApp, Teams, Discord)](https://docs.citsmart.com/7-agenda-estrategica#713-enviar-pelos-canais-integrados-whatsapp-teams)                                                          |
| BSC-AGE-14                          | 7.14                                | [Envio automático por categoria](https://docs.citsmart.com/7-agenda-estrategica#714-envio-automtico-por-categoria)                                                                                                     |
| BSC-AGE-15                          | 7.15                                | [Registro de envios e o que "enviado" quer dizer](https://docs.citsmart.com/7-agenda-estrategica#715-registro-de-envios-e-o-que-enviado-quer-dizer)                                                                    |
| BSC-AGE-16                          | 7.16                                | [Exportar o evento em CSV](https://docs.citsmart.com/7-agenda-estrategica#716-exportar-o-evento-em-csv)                                                                                                                |
| BSC-AGE-17                          | 7.17                                | [Perfis de acesso na agenda](https://docs.citsmart.com/7-agenda-estrategica#717-perfis-de-acesso-na-agenda)                                                                                                            |
| BSC-RIS-01                          | 8.1                                 | [Naturezas de risco](https://docs.citsmart.com/8-gestao-de-riscos#81-naturezas-de-risco)                                                                                                                               |
| BSC-RIS-02                          | 8.2                                 | [Leitura das matrizes de risco](https://docs.citsmart.com/8-gestao-de-riscos#82-leitura-das-matrizes-de-risco)                                                                                                         |
| BSC-RIS-03                          | 8.3                                 | [Completar e ativar uma matriz](https://docs.citsmart.com/8-gestao-de-riscos#83-completar-e-ativar-uma-matriz)                                                                                                         |
| BSC-RIS-04                          | 8.4                                 | [Escolher a matriz padrão](https://docs.citsmart.com/8-gestao-de-riscos#84-escolher-a-matriz-padro)                                                                                                                    |
| BSC-RIS-05                          | 8.5                                 | [Nova versão de uma matriz já usada](https://docs.citsmart.com/8-gestao-de-riscos#85-nova-verso-de-uma-matriz-j-usada)                                                                                                 |
| BSC-RIS-06                          | 8.6                                 | [Aposentar uma matriz e consultar o histórico do método](https://docs.citsmart.com/8-gestao-de-riscos#86-aposentar-uma-matriz-e-consultar-o-histrico-do)                                                               |
| BSC-RIS-07                          | 8.7                                 | [Registrar um risco](https://docs.citsmart.com/8-gestao-de-riscos#87-registrar-um-risco)                                                                                                                               |
| BSC-RIS-08                          | 8.8                                 | [Vincular o risco ao que ele ameaça](https://docs.citsmart.com/8-gestao-de-riscos#88-vincular-o-risco-ao-que-ele-ameaa)                                                                                                |
| BSC-RIS-09                          | 8.9                                 | [Avaliar o risco inerente e o residual planejado](https://docs.citsmart.com/8-gestao-de-riscos#89-avaliar-o-risco-inerente-e-o-residual-planejado)                                                                     |
| BSC-RIS-10                          | 8.10                                | [Reavaliar um risco](https://docs.citsmart.com/8-gestao-de-riscos#810-reavaliar-um-risco)                                                                                                                              |
| BSC-RIS-11                          | 8.11                                | [Estratégia de resposta e ativação do risco](https://docs.citsmart.com/8-gestao-de-riscos#811-estratgia-de-resposta-e-ativao-do-risco)                                                                                 |
| BSC-RIS-12                          | 8.12                                | [Encerrar e reabrir um risco](https://docs.citsmart.com/8-gestao-de-riscos#812-encerrar-e-reabrir-um-risco)                                                                                                            |
| BSC-RIS-13                          | 8.13                                | [Riscos sigilosos](https://docs.citsmart.com/8-gestao-de-riscos#813-riscos-sigilosos)                                                                                                                                  |
| BSC-RIS-14                          | 8.14                                | [Histórico do risco](https://docs.citsmart.com/8-gestao-de-riscos#814-histrico-do-risco)                                                                                                                               |
| BSC-RIS-15                          | 8.15                                | [Cadastrar tratamentos do risco](https://docs.citsmart.com/8-gestao-de-riscos#815-cadastrar-tratamentos-do-risco)                                                                                                      |
| BSC-RIS-16                          | 8.16                                | [Lançar a execução do tratamento com evidência](https://docs.citsmart.com/8-gestao-de-riscos#816-lanar-a-execuo-do-tratamento-com-evidncia)                                                                            |
| BSC-RIS-17                          | 8.17                                | [Corrigir um lançamento de execução](https://docs.citsmart.com/8-gestao-de-riscos#817-corrigir-um-lanamento-de-execuo)                                                                                                 |
| BSC-RIS-18                          | 8.18                                | [Cancelar um tratamento](https://docs.citsmart.com/8-gestao-de-riscos#818-cancelar-um-tratamento)                                                                                                                      |
| BSC-RIS-19                          | 8.19                                | [Tratamentos vencidos e o sinal de riscos no mapa estratégico](https://docs.citsmart.com/8-gestao-de-riscos#819-tratamentos-vencidos-e-o-sinal-de-riscos-no-ma)                                                        |
| BSC-RIS-20                          | 8.20                                | [Filtros de criticidade no registro de riscos](https://docs.citsmart.com/8-gestao-de-riscos#820-filtros-de-criticidade-no-registro-de-riscos)                                                                          |
| BSC-RIS-21                          | 8.21                                | [Mapa de riscos](https://docs.citsmart.com/8-gestao-de-riscos#821-mapa-de-riscos)                                                                                                                                      |
| BSC-RIS-22                          | 8.22                                | [Registrar uma ocorrência](https://docs.citsmart.com/8-gestao-de-riscos#822-registrar-uma-ocorrncia)                                                                                                                   |
| BSC-RIS-23                          | 8.23                                | [Ligar a ocorrência a um tratamento](https://docs.citsmart.com/8-gestao-de-riscos#823-ligar-a-ocorrncia-a-um-tratamento)                                                                                               |
| BSC-RIS-24                          | 8.24                                | [Retirar uma ocorrência registrada por engano](https://docs.citsmart.com/8-gestao-de-riscos#824-retirar-uma-ocorrncia-registrada-por-engano)                                                                           |
| BSC-RIS-25                          | 8.25                                | [Modelos de plano de riscos](https://docs.citsmart.com/8-gestao-de-riscos#825-modelos-de-plano-de-riscos)                                                                                                              |
| BSC-RIS-26                          | 8.26                                | [Aplicar um modelo de plano de riscos](https://docs.citsmart.com/8-gestao-de-riscos#826-aplicar-um-modelo-de-plano-de-riscos)                                                                                          |
| BSC-RIS-27                          | 8.27                                | [Seguir um risco, discutir e receber avisos](https://docs.citsmart.com/8-gestao-de-riscos#827-seguir-um-risco-discutir-e-receber-avisos)                                                                               |
| BSC-RIS-28                          | 8.28                                | [Perfis de acesso à gestão de riscos](https://docs.citsmart.com/8-gestao-de-riscos#828-perfis-de-acesso-gesto-de-riscos)                                                                                               |
| BSC-SWT-01                          | 9.1                                 | [Criar uma análise SWOT](https://docs.citsmart.com/9-analise-swot#91-criar-uma-anlise-swot)                                                                                                                            |
| BSC-SWT-02                          | 9.2                                 | [Cadastrar fatores](https://docs.citsmart.com/9-analise-swot#92-cadastrar-fatores)                                                                                                                                     |
| BSC-SWT-03                          | 9.3                                 | [Ordenar os fatores por prioridade](https://docs.citsmart.com/9-analise-swot#93-ordenar-os-fatores-por-prioridade)                                                                                                     |
| BSC-SWT-04                          | 9.4                                 | [Publicar a análise](https://docs.citsmart.com/9-analise-swot#94-publicar-a-anlise)                                                                                                                                    |
| BSC-SWT-05                          | 9.5                                 | [Criar um risco a partir de uma fraqueza ou ameaça](https://docs.citsmart.com/9-analise-swot#95-criar-um-risco-a-partir-de-uma-fraqueza-ou-amea)                                                                       |
| BSC-SWT-06                          | 9.6                                 | [Acompanhar os riscos e tratamentos de um fator](https://docs.citsmart.com/9-analise-swot#96-acompanhar-os-riscos-e-tratamentos-de-um-fator)                                                                           |
| BSC-SWT-07                          | 9.7                                 | [Ligar um risco existente a fraquezas e ameaças](https://docs.citsmart.com/9-analise-swot#97-ligar-um-risco-existente-a-fraquezas-e-ameaas)                                                                            |
| BSC-SWT-08                          | 9.8                                 | [Apagar um fator](https://docs.citsmart.com/9-analise-swot#98-apagar-um-fator)                                                                                                                                         |
| BSC-SWT-09                          | 9.9                                 | [Arquivar a análise](https://docs.citsmart.com/9-analise-swot#99-arquivar-a-anlise)                                                                                                                                    |
| BSC-SWT-10                          | 9.10                                | [Histórico da análise](https://docs.citsmart.com/9-analise-swot#910-histrico-da-anlise)                                                                                                                                |
| BSC-SWT-11                          | 9.11                                | [Perfis de acesso às análises SWOT](https://docs.citsmart.com/9-analise-swot#911-perfis-de-acesso-s-anlises-swot)                                                                                                      |
| BSC-PRO-01                          | 10.1                                | [Tipos de processo](https://docs.citsmart.com/10-processos-e-cadeia-de-valor#101-tipos-de-processo)                                                                                                                    |
| BSC-PRO-02                          | 10.2                                | [Macroprocessos](https://docs.citsmart.com/10-processos-e-cadeia-de-valor#102-macroprocessos)                                                                                                                          |
| BSC-PRO-03                          | 10.3                                | [Cadastrar um processo](https://docs.citsmart.com/10-processos-e-cadeia-de-valor#103-cadastrar-um-processo)                                                                                                            |
| BSC-PRO-04                          | 10.4                                | [Editar, inativar e consultar o histórico do processo](https://docs.citsmart.com/10-processos-e-cadeia-de-valor#104-editar-inativar-e-consultar-o-histrico-do-proc)                                                    |
| BSC-PRO-05                          | 10.5                                | [Anexar o arquivo de modelagem e descrever a mudança](https://docs.citsmart.com/10-processos-e-cadeia-de-valor#105-anexar-o-arquivo-de-modelagem-e-descrever-a-mu)                                                     |
| BSC-PRO-06                          | 10.6                                | [Enviar a versão para revisão](https://docs.citsmart.com/10-processos-e-cadeia-de-valor#106-enviar-a-verso-para-reviso)                                                                                                |
| BSC-PRO-07                          | 10.7                                | [Validar ou devolver uma versão](https://docs.citsmart.com/10-processos-e-cadeia-de-valor#107-validar-ou-devolver-uma-verso)                                                                                           |
| BSC-PRO-08                          | 10.8                                | [Abrir uma nova versão e consultar o histórico da versão](https://docs.citsmart.com/10-processos-e-cadeia-de-valor#108-abrir-uma-nova-verso-e-consultar-o-histrico-da)                                                 |
| BSC-PRO-09                          | 10.9                                | [Ler a cadeia de valor](https://docs.citsmart.com/10-processos-e-cadeia-de-valor#109-ler-a-cadeia-de-valor)                                                                                                            |
| BSC-PRO-10                          | 10.10                               | [Navegar da cadeia de valor aos processos](https://docs.citsmart.com/10-processos-e-cadeia-de-valor#1010-navegar-da-cadeia-de-valor-aos-processos)                                                                     |
| BSC-PRO-11                          | 10.11                               | [Exportar a cadeia de valor](https://docs.citsmart.com/10-processos-e-cadeia-de-valor#1011-exportar-a-cadeia-de-valor)                                                                                                 |
| BSC-PRO-12                          | 10.12                               | [Perfis de acesso a processos](https://docs.citsmart.com/10-processos-e-cadeia-de-valor#1012-perfis-de-acesso-a-processos)                                                                                             |
| BSC-PAI-01                          | 11.1                                | [Abrir os painéis e saber qual abre ao entrar](https://docs.citsmart.com/11-paineis-e-relatorios#111-abrir-os-painis-e-saber-qual-abre-ao-entrar)                                                                      |
| BSC-PAI-02                          | 11.2                                | [Criar um painel](https://docs.citsmart.com/11-paineis-e-relatorios#112-criar-um-painel)                                                                                                                               |
| BSC-PAI-03                          | 11.3                                | [Criar um painel a partir de um modelo](https://docs.citsmart.com/11-paineis-e-relatorios#113-criar-um-painel-a-partir-de-um-modelo)                                                                                   |
| BSC-PAI-04                          | 11.4                                | [Acrescentar widgets](https://docs.citsmart.com/11-paineis-e-relatorios#114-acrescentar-widgets)                                                                                                                       |
| BSC-PAI-05                          | 11.5                                | [Mover, redimensionar e remover widgets](https://docs.citsmart.com/11-paineis-e-relatorios#115-mover-redimensionar-e-remover-widgets)                                                                                  |
| BSC-PAI-06                          | 11.6                                | [Alterar um widget](https://docs.citsmart.com/11-paineis-e-relatorios#116-alterar-um-widget)                                                                                                                           |
| BSC-PAI-07                          | 11.7                                | [Widgets de indicadores, objetivos e ciclo](https://docs.citsmart.com/11-paineis-e-relatorios#117-widgets-de-indicadores-objetivos-e-ciclo)                                                                            |
| BSC-PAI-08                          | 11.8                                | [Comparação de períodos](https://docs.citsmart.com/11-paineis-e-relatorios#118-comparao-de-perodos)                                                                                                                    |
| BSC-PAI-09                          | 11.9                                | [Widgets de ações, riscos e processos](https://docs.citsmart.com/11-paineis-e-relatorios#119-widgets-de-aes-riscos-e-processos)                                                                                        |
| BSC-PAI-10                          | 11.10                               | [Widgets de planos de ação, cargas de dados e consultas salvas](https://docs.citsmart.com/11-paineis-e-relatorios#1110-widgets-de-planos-de-ao-cargas-de-dados-e-con)                                                  |
| BSC-PAI-11                          | 11.11                               | [Sigilo nos painéis](https://docs.citsmart.com/11-paineis-e-relatorios#1111-sigilo-nos-painis)                                                                                                                         |
| BSC-PAI-12                          | 11.12                               | [Compartilhar um painel pessoal](https://docs.citsmart.com/11-paineis-e-relatorios#1112-compartilhar-um-painel-pessoal)                                                                                                |
| BSC-PAI-13                          | 11.13                               | [Publicar um painel de cargo e torná-lo padrão](https://docs.citsmart.com/11-paineis-e-relatorios#1113-publicar-um-painel-de-cargo-e-torn-lo-padro)                                                                    |
| BSC-PAI-14                          | 11.14                               | [Painel da organização](https://docs.citsmart.com/11-paineis-e-relatorios#1114-painel-da-organizao)                                                                                                                    |
| BSC-PAI-15                          | 11.15                               | [Escolher o painel que abre ao entrar](https://docs.citsmart.com/11-paineis-e-relatorios#1115-escolher-o-painel-que-abre-ao-entrar)                                                                                    |
| BSC-PAI-16                          | 11.16                               | [Duplicar um painel](https://docs.citsmart.com/11-paineis-e-relatorios#1116-duplicar-um-painel)                                                                                                                        |
| BSC-PAI-17                          | 11.17                               | [Histórico, arquivamento e restauração de painéis](https://docs.citsmart.com/11-paineis-e-relatorios#1117-histrico-arquivamento-e-restaurao-de-painis)                                                                 |
| BSC-PAI-18                          | 11.18                               | [Sinalização dos painéis (estilo dos sinalizadores)](https://docs.citsmart.com/11-paineis-e-relatorios#1118-sinalizao-dos-painis-estilo-dos-sinalizadores)                                                             |
| BSC-PAI-19                          | 11.19                               | [Atualização dos dados: o carimbo e a recarga automática](https://docs.citsmart.com/11-paineis-e-relatorios#1119-atualizao-dos-dados-o-carimbo-e-a-recarga-aut)                                                        |
| BSC-PAI-20                          | 11.20                               | [Detalhar: do widget para a tela de origem](https://docs.citsmart.com/11-paineis-e-relatorios#1120-detalhar-do-widget-para-a-tela-de-origem)                                                                           |
| BSC-PAI-21                          | 11.21                               | [Filtrar o painel: a barra de filtros](https://docs.citsmart.com/11-paineis-e-relatorios#1121-filtrar-o-painel-a-barra-de-filtros)                                                                                     |
| BSC-PAI-22                          | 11.22                               | [Compartilhar o recorte e gravar o recorte padrão](https://docs.citsmart.com/11-paineis-e-relatorios#1122-compartilhar-o-recorte-e-gravar-o-recorte-pad)                                                               |
| BSC-PAI-23                          | 11.23                               | [Relatórios por período: abrir, escolher a visão e filtrar](https://docs.citsmart.com/11-paineis-e-relatorios#1123-relatrios-por-perodo-abrir-escolher-a-viso-e)                                                       |
| BSC-PAI-24                          | 11.24                               | [Ler os relatórios de indicadores e objetivos](https://docs.citsmart.com/11-paineis-e-relatorios#1124-ler-os-relatrios-de-indicadores-e-objetivos)                                                                     |
| BSC-PAI-25                          | 11.25                               | [Relatórios de ações estratégicas e de processos](https://docs.citsmart.com/11-paineis-e-relatorios#1125-relatrios-de-aes-estratgicas-e-de-processos)                                                                  |
| BSC-PAI-26                          | 11.26                               | [Exportar relatório para planilha Excel](https://docs.citsmart.com/11-paineis-e-relatorios#1126-exportar-relatrio-para-planilha-excel)                                                                                 |
| BSC-PAI-27                          | 11.27                               | [Exportar o painel para planilha Excel](https://docs.citsmart.com/11-paineis-e-relatorios#1127-exportar-o-painel-para-planilha-excel)                                                                                  |
| BSC-PAI-28                          | 11.28                               | [Baixar imagem do gráfico e imprimir o painel em PDF](https://docs.citsmart.com/11-paineis-e-relatorios#1128-baixar-imagem-do-grfico-e-imprimir-o-painel-e)                                                            |
| BSC-PAI-29                          | 11.29                               | [Painéis no celular](https://docs.citsmart.com/11-paineis-e-relatorios#1129-painis-no-celular)                                                                                                                         |
| BSC-DAD-01                          | 12.1                                | [Área de dados e base de leitura](https://docs.citsmart.com/12-dados-console-sql-consultas-cargas-e-portais#121-rea-de-dados-e-base-de-leitura)                                                                        |
| BSC-DAD-02                          | 12.2                                | [Console SQL](https://docs.citsmart.com/12-dados-console-sql-consultas-cargas-e-portais#122-console-sql)                                                                                                               |
| BSC-DAD-03                          | 12.3                                | [Consultas salvas: criar uma consulta](https://docs.citsmart.com/12-dados-console-sql-consultas-cargas-e-portais#123-consultas-salvas-criar-uma-consulta)                                                              |
| BSC-DAD-04                          | 12.4                                | [Consultas salvas: escrever e publicar uma versão](https://docs.citsmart.com/12-dados-console-sql-consultas-cargas-e-portais#124-consultas-salvas-escrever-e-publicar-uma-verso)                                       |
| BSC-DAD-05                          | 12.5                                | [Consultas salvas: versões, comparação e desativação](https://docs.citsmart.com/12-dados-console-sql-consultas-cargas-e-portais#125-consultas-salvas-verses-comparao-e-desativao)                                      |
| BSC-DAD-06                          | 12.6                                | [Consulta sobre banco externo](https://docs.citsmart.com/12-dados-console-sql-consultas-cargas-e-portais#126-consulta-sobre-banco-externo)                                                                             |
| BSC-DAD-07                          | 12.7                                | [Cargas de dados: cadastrar uma carga](https://docs.citsmart.com/12-dados-console-sql-consultas-cargas-e-portais#127-cargas-de-dados-cadastrar-uma-carga)                                                              |
| BSC-DAD-08                          | 12.8                                | [Cargas de dados: pré-visualizar e nomear as colunas](https://docs.citsmart.com/12-dados-console-sql-consultas-cargas-e-portais#128-cargas-de-dados-pr-visualizar-e-nomear-as-colu)                                    |
| BSC-DAD-09                          | 12.9                                | [Cargas de dados: executar e acompanhar](https://docs.citsmart.com/12-dados-console-sql-consultas-cargas-e-portais#129-cargas-de-dados-executar-e-acompanhar)                                                          |
| BSC-DAD-10                          | 12.10                               | [Dados importados e consulta em SQL](https://docs.citsmart.com/12-dados-console-sql-consultas-cargas-e-portais#1210-dados-importados-e-consulta-em-sql)                                                                |
| BSC-DAD-11                          | 12.11                               | [Apuração de indicador por consulta SQL](https://docs.citsmart.com/12-dados-console-sql-consultas-cargas-e-portais#1211-apurao-de-indicador-por-consulta-sql)                                                          |
| BSC-DAD-12                          | 12.12                               | [Consultas de controle e retratos diários](https://docs.citsmart.com/12-dados-console-sql-consultas-cargas-e-portais#1212-consultas-de-controle-e-retratos-dirios)                                                     |
| BSC-DAD-13                          | 12.13                               | [Portais do governo: ver e configurar](https://docs.citsmart.com/12-dados-console-sql-consultas-cargas-e-portais#1213-portais-do-governo-ver-e-configurar)                                                             |
| BSC-DAD-14                          | 12.14                               | [Portais do governo: sincronização](https://docs.citsmart.com/12-dados-console-sql-consultas-cargas-e-portais#1214-portais-do-governo-sincronizao)                                                                     |
| BSC-DAD-15                          | 12.15                               | [Categorias de itens e regras de classificação](https://docs.citsmart.com/12-dados-console-sql-consultas-cargas-e-portais#1215-categorias-de-itens-e-regras-de-classificao)                                            |
| BSC-DAD-16                          | 12.16                               | [Itens de portais: classificar e vincular à estratégia](https://docs.citsmart.com/12-dados-console-sql-consultas-cargas-e-portais#1216-itens-de-portais-classificar-e-vincular-estra)                                  |
| BSC-DAD-17                          | 12.17                               | [Conteúdo da base de leitura](https://docs.citsmart.com/12-dados-console-sql-consultas-cargas-e-portais#1217-contedo-da-base-de-leitura)                                                                               |
| BSC-DAD-18                          | 12.18                               | [Acesso de leitura para ferramentas de BI](https://docs.citsmart.com/12-dados-console-sql-consultas-cargas-e-portais#1218-acesso-de-leitura-para-ferramentas-de-bi)                                                    |
| BSC-DAD-19                          | 12.19                               | [Registro das execuções](https://docs.citsmart.com/12-dados-console-sql-consultas-cargas-e-portais#1219-registro-das-execues)                                                                                          |
| BSC-DAD-20                          | 12.20                               | [Monitor de integrações](https://docs.citsmart.com/12-dados-console-sql-consultas-cargas-e-portais#1220-monitor-de-integraes)                                                                                          |
| BSC-DAD-21                          | 12.21                               | [Serviços agendados e manutenção do registro](https://docs.citsmart.com/12-dados-console-sql-consultas-cargas-e-portais#1221-servios-agendados-e-manuteno-do-registro)                                                 |
| BSC-ITG-01                          | 13.1                                | [Conceitos: integração, conector e De-Para](https://docs.citsmart.com/13-hub-de-integracoes-conectores-e-de-para#131-conceitos-integrao-conector-e-de-para)                                                            |
| BSC-ITG-02                          | 13.2                                | [Cadastrar uma integração](https://docs.citsmart.com/13-hub-de-integracoes-conectores-e-de-para#132-cadastrar-uma-integrao)                                                                                            |
| BSC-ITG-03                          | 13.3                                | [Testar uma integração](https://docs.citsmart.com/13-hub-de-integracoes-conectores-e-de-para#133-testar-uma-integrao)                                                                                                  |
| BSC-ITG-04                          | 13.4                                | [Pré-visualizar os dados de uma integração](https://docs.citsmart.com/13-hub-de-integracoes-conectores-e-de-para#134-pr-visualizar-os-dados-de-uma-integrao)                                                           |
| BSC-ITG-05                          | 13.5                                | [Periodicidade da atualização](https://docs.citsmart.com/13-hub-de-integracoes-conectores-e-de-para#135-periodicidade-da-atualizao)                                                                                    |
| BSC-ITG-06                          | 13.6                                | [Segredos e troca de credencial](https://docs.citsmart.com/13-hub-de-integracoes-conectores-e-de-para#135-periodicidade-da-atualizao)                                                                                  |
| BSC-ITG-07                          | 13.7                                | [Lista de saída (destinos aprovados)](https://docs.citsmart.com/13-hub-de-integracoes-conectores-e-de-para#137-lista-de-sada-destinos-aprovados)                                                                       |
| BSC-ITG-08                          | 13.8                                | [Perfis de acesso ao hub](https://docs.citsmart.com/13-hub-de-integracoes-conectores-e-de-para#138-perfis-de-acesso-ao-hub)                                                                                            |
| BSC-ITG-09                          | 13.9                                | [Tipo API REST](https://docs.citsmart.com/13-hub-de-integracoes-conectores-e-de-para#139-tipo-api-rest)                                                                                                                |
| BSC-ITG-10                          | 13.10                               | [Tipo web service SOAP](https://docs.citsmart.com/13-hub-de-integracoes-conectores-e-de-para#1310-tipo-web-service-soap)                                                                                               |
| BSC-ITG-11                          | 13.11                               | [Tipo banco de dados](https://docs.citsmart.com/13-hub-de-integracoes-conectores-e-de-para#1311-tipo-banco-de-dados)                                                                                                   |
| BSC-ITG-12                          | 13.12                               | [Tipo arquivo](https://docs.citsmart.com/13-hub-de-integracoes-conectores-e-de-para#1312-tipo-arquivo)                                                                                                                 |
| BSC-ITG-13                          | 13.13                               | [Tipos das próximas entregas: HTTP de saída, webhook de entrada, broker e barramento](https://docs.citsmart.com/13-hub-de-integracoes-conectores-e-de-para#1313-tipos-das-prximas-entregas-http-de-sada-webho)         |
| BSC-ITG-14                          | 13.14                               | [Tipo SEI](https://docs.citsmart.com/13-hub-de-integracoes-conectores-e-de-para#1314-tipo-sei)                                                                                                                         |
| BSC-ITG-15                          | 13.15                               | [Tipo SIAFI: API Dados SIAFI (STA)](https://docs.citsmart.com/13-hub-de-integracoes-conectores-e-de-para#1315-tipo-siafi-api-dados-siafi-sta)                                                                          |
| BSC-ITG-16                          | 13.16                               | [Tipo SIAFI: Portal da Transparência, Tesouro Gerencial e web services](https://docs.citsmart.com/13-hub-de-integracoes-conectores-e-de-para#1316-tipo-siafi-portal-da-transparncia-tesouro-ger)                       |
| BSC-ITG-17                          | 13.17                               | [Canais de mensagem como tipos do hub](https://docs.citsmart.com/13-hub-de-integracoes-conectores-e-de-para#1317-canais-de-mensagem-como-tipos-do-hub)                                                                 |
| BSC-ITG-18                          | 13.18                               | [Sistemas corporativos sob demanda](https://docs.citsmart.com/13-hub-de-integracoes-conectores-e-de-para#1318-sistemas-corporativos-sob-demanda)                                                                       |
| BSC-ITG-19                          | 13.19                               | [Ambiente de simulação para treinamento e homologação](https://docs.citsmart.com/13-hub-de-integracoes-conectores-e-de-para#1319-ambiente-de-simulao-para-treinamento-e-homolo)                                        |
| BSC-ITG-20                          | 13.20                               | [Conectores do BSC: a paleta de componentes](https://docs.citsmart.com/13-hub-de-integracoes-conectores-e-de-para#1320-conectores-do-bsc-a-paleta-de-componentes)                                                      |
| BSC-ITG-21                          | 13.21                               | [Montar um conector](https://docs.citsmart.com/13-hub-de-integracoes-conectores-e-de-para#1321-montar-um-conector)                                                                                                     |
| BSC-ITG-22                          | 13.22                               | [Como o conector dispara e sigilo](https://docs.citsmart.com/13-hub-de-integracoes-conectores-e-de-para#1322-como-o-conector-dispara-e-sigilo)                                                                         |
| BSC-ITG-23                          | 13.23                               | [Ficha do conector e acompanhamento no monitor](https://docs.citsmart.com/13-hub-de-integracoes-conectores-e-de-para#1323-ficha-do-conector-e-acompanhamento-no-monitor)                                               |
| BSC-ITG-24                          | 13.24                               | [De-Para: destinos](https://docs.citsmart.com/13-hub-de-integracoes-conectores-e-de-para#1324-de-para-destinos)                                                                                                        |
| BSC-ITG-25                          | 13.25                               | [De-Para: montar, validar e publicar](https://docs.citsmart.com/13-hub-de-integracoes-conectores-e-de-para#1325-de-para-montar-validar-e-publicar)                                                                     |
| BSC-ITG-26                          | 13.26                               | [De-Para: aplicar](https://docs.citsmart.com/13-hub-de-integracoes-conectores-e-de-para#1326-de-para-aplicar)                                                                                                          |
| BSC-ITG-27                          | 13.27                               | [Tabelas de equivalência](https://docs.citsmart.com/13-hub-de-integracoes-conectores-e-de-para#1327-tabelas-de-equivalncia)                                                                                            |
| BSC-MSG-01                          | 14.1                                | [Acompanhar as notificações no sino](https://docs.citsmart.com/14-mensageria-e-notificacoes#141-acompanhar-as-notificaes-no-sino)                                                                                      |
| BSC-MSG-02                          | 14.2                                | [Procurar um aviso antigo na tela Notificações](https://docs.citsmart.com/14-mensageria-e-notificacoes#142-procurar-um-aviso-antigo-na-tela-notificaes)                                                                |
| BSC-MSG-03                          | 14.3                                | [Configurar as preferências de notificação](https://docs.citsmart.com/14-mensageria-e-notificacoes#143-configurar-as-preferncias-de-notificao)                                                                         |
| BSC-MSG-04                          | 14.4                                | [Receber avisos push no celular e no computador](https://docs.citsmart.com/14-mensageria-e-notificacoes#144-receber-avisos-push-no-celular-e-no-computador)                                                            |
| BSC-MSG-05                          | 14.5                                | [Confirmar o número e autorizar o WhatsApp pessoal](https://docs.citsmart.com/14-mensageria-e-notificacoes#145-confirmar-o-nmero-e-autorizar-o-whatsapp-pesso)                                                         |
| BSC-MSG-06                          | 14.6                                | [Seguir registros e gerenciar os itens que sigo](https://docs.citsmart.com/14-mensageria-e-notificacoes#146-seguir-registros-e-gerenciar-os-itens-que-sigo)                                                            |
| BSC-MSG-07                          | 14.7                                | [Editar as mensagens institucionais e usar campos automáticos](https://docs.citsmart.com/14-mensageria-e-notificacoes#147-editar-as-mensagens-institucionais-e-usar-camp)                                              |
| BSC-MSG-08                          | 14.8                                | [Criar uma variação da mensagem para um canal](https://docs.citsmart.com/14-mensageria-e-notificacoes#148-criar-uma-variao-da-mensagem-para-um-canal)                                                                  |
| BSC-MSG-09                          | 14.9                                | [Configurar a variação de WhatsApp com o modelo aprovado](https://docs.citsmart.com/14-mensageria-e-notificacoes#149-configurar-a-variao-de-whatsapp-com-o-modelo-a)                                                   |
| BSC-MSG-10                          | 14.10                               | [Configurar os alertas do Bússola/BSC por família](https://docs.citsmart.com/14-mensageria-e-notificacoes#1410-configurar-os-alertas-do-bssolabsc-por-famlia)                                                          |
| BSC-MSG-11                          | 14.11                               | [Publicar os alertas nos canais da área (Teams e Discord)](https://docs.citsmart.com/14-mensageria-e-notificacoes#1411-publicar-os-alertas-nos-canais-da-rea-teams-e)                                                  |
| BSC-MSG-12                          | 14.12                               | [Cadastrar a integração com o Microsoft Teams](https://docs.citsmart.com/14-mensageria-e-notificacoes#1412-cadastrar-a-integrao-com-o-microsoft-teams)                                                                 |
| BSC-MSG-13                          | 14.13                               | [Cadastrar a integração com o Discord](https://docs.citsmart.com/14-mensageria-e-notificacoes#1413-cadastrar-a-integrao-com-o-discord)                                                                                 |
| BSC-MSG-14                          | 14.14                               | [Configurar a conta de WhatsApp da empresa](https://docs.citsmart.com/14-mensageria-e-notificacoes#1414-configurar-a-conta-de-whatsapp-da-empresa)                                                                     |
| BSC-MSG-15                          | 14.15                               | [Ligar canais de Teams e Discord às unidades (Canais de área)](https://docs.citsmart.com/14-mensageria-e-notificacoes#1415-ligar-canais-de-teams-e-discord-s-unidades-ca)                                              |
| BSC-MSG-16                          | 14.16                               | [Conferir e reprocessar as falhas de envio](https://docs.citsmart.com/14-mensageria-e-notificacoes#1416-conferir-e-reprocessar-as-falhas-de-envio)                                                                     |
| BSC-ACS-01                          | 15.1                                | [Criar um perfil de acesso do BSC](https://docs.citsmart.com/15-acesso-seguranca-e-administracao#151-criar-um-perfil-de-acesso-do-bsc)                                                                                 |
| BSC-ACS-02                          | 15.2                                | [Associar e retirar pessoas de um perfil](https://docs.citsmart.com/15-acesso-seguranca-e-administracao#152-associar-e-retirar-pessoas-de-um-perfil)                                                                   |
| BSC-ACS-03                          | 15.3                                | [Consultar quem tem acesso a uma tela do BSC](https://docs.citsmart.com/15-acesso-seguranca-e-administracao#153-consultar-quem-tem-acesso-a-uma-tela-do-bsc)                                                           |
| BSC-ACS-04                          | 15.4                                | [Cadastrar um usuário local do BSC](https://docs.citsmart.com/15-acesso-seguranca-e-administracao#154-cadastrar-um-usurio-local-do-bsc)                                                                                |
| BSC-ACS-05                          | 15.5                                | [Exemplo: perfil "Leitura de riscos" para a auditoria](https://docs.citsmart.com/15-acesso-seguranca-e-administracao#155-exemplo-perfil-leitura-de-riscos-para-a-audito)                                               |
| BSC-ACS-06                          | 15.6                                | [Configurar as regras de autorização (alçada) das operações do Bússola/BSC](https://docs.citsmart.com/15-acesso-seguranca-e-administracao#156-configurar-as-regras-de-autorizao-alada-das-op)                          |
| BSC-ACS-07                          | 15.7                                | [Restringir a regra a uma unidade e conceder um módulo inteiro](https://docs.citsmart.com/15-acesso-seguranca-e-administracao#157-restringir-a-regra-a-uma-unidade-e-conceder-um)                                      |
| BSC-ACS-08                          | 15.8                                | [Delegar a alçada de um cargo (substituição)](https://docs.citsmart.com/15-acesso-seguranca-e-administracao#158-delegar-a-alada-de-um-cargo-substituio)                                                                |
| BSC-ACS-09                          | 15.9                                | [Consultar as chaves de cifragem e recifrar os segredos](https://docs.citsmart.com/15-acesso-seguranca-e-administracao#159-consultar-as-chaves-de-cifragem-e-recifrar-os)                                              |
| BSC-ACS-10                          | 15.10                               | [Trocar a chave de cifragem em duas fases](https://docs.citsmart.com/15-acesso-seguranca-e-administracao#1510-trocar-a-chave-de-cifragem-em-duas-fases)                                                                |
| BSC-ACS-11                          | 15.11                               | [Consultar o histórico de um registro do Bússola/BSC](https://docs.citsmart.com/15-acesso-seguranca-e-administracao#1511-consultar-o-histrico-de-um-registro-do-bssola)                                                |
| BSC-ACS-12                          | 15.12                               | [Configurar e consultar a trilha de auditoria](https://docs.citsmart.com/15-acesso-seguranca-e-administracao#1512-configurar-e-consultar-a-trilha-de-auditoria)                                                        |
| BSC-ACS-13                          | 15.13                               | [Controlar sessões ativas e faixas de IP](https://docs.citsmart.com/15-acesso-seguranca-e-administracao#1513-controlar-sesses-ativas-e-faixas-de-ip)                                                                   |
| BSC-ORG-01                          | 16.1                                | [Cadastrar unidades com hierarquia, sigla e situação](https://docs.citsmart.com/16-estrutura-organizacional-e-acesso-as-empresas#161-cadastrar-unidades-com-hierarquia-sigla-e-situ)                                   |
| BSC-ORG-02                          | 16.2                                | [Cargos e lotação: unidade × cargo e a montagem automática do organograma](https://docs.citsmart.com/16-estrutura-organizacional-e-acesso-as-empresas#162-cargos-e-lotao-unidade-cargo-e-a-montagem-auto)              |
| BSC-ORG-03                          | 16.3                                | [Unidades assistentes](https://docs.citsmart.com/16-estrutura-organizacional-e-acesso-as-empresas#163-unidades-assistentes)                                                                                            |
| BSC-ORG-04                          | 16.4                                | [Organograma interativo](https://docs.citsmart.com/16-estrutura-organizacional-e-acesso-as-empresas#164-organograma-interativo)                                                                                        |
| BSC-ORG-05                          | 16.5                                | [Acesso do usuário às empresas](https://docs.citsmart.com/16-estrutura-organizacional-e-acesso-as-empresas#165-acesso-do-usurio-s-empresas)                                                                            |
| BSC-INS-01                          | 17.1                                | [Instalação interna (no ambiente da empresa) e em nuvem](https://docs.citsmart.com/17-instalacao-backup-e-restauracao#171-instalao-interna-no-ambiente-da-empresa-e-em-n)                                              |
| BSC-INS-02                          | 17.2                                | [Backup diário e restauração](https://docs.citsmart.com/17-instalacao-backup-e-restauracao#172-backup-dirio-e-restaurao)                                                                                               |
| BSC-INS-03                          | 17.3                                | [Registrar o teste de restauração](https://docs.citsmart.com/17-instalacao-backup-e-restauracao#173-registrar-o-teste-de-restaurao)                                                                                    |
| BSC-CFG-01                          | 18.1                                | [Onde configurar o WhatsApp](https://docs.citsmart.com/18-onde-configurar-as-integracoes-com-terceiros-e-a-instalacao#181-onde-configurar-o-whatsapp)                                                                  |
| BSC-CFG-02                          | 18.2                                | [Onde configurar o Microsoft Teams e o Discord](https://docs.citsmart.com/18-onde-configurar-as-integracoes-com-terceiros-e-a-instalacao#182-onde-configurar-o-microsoft-teams-e-o-discord)                            |
| BSC-CFG-03                          | 18.3                                | [Onde configurar SEI, SIAFI, Portal da Transparência e Tesouro Gerencial](https://docs.citsmart.com/18-onde-configurar-as-integracoes-com-terceiros-e-a-instalacao#183-onde-configurar-sei-siafi-portal-da-transparnc) |
| BSC-CFG-04                          | 18.4                                | [Onde configurar a instalação (Compose e Kubernetes)](https://docs.citsmart.com/18-onde-configurar-as-integracoes-com-terceiros-e-a-instalacao#184-onde-configurar-a-instalao-compose-e-kubernete)                     |


[title] Usuários
[path] Início Rápido/🌐Gestão de Pessoas/

A página de Usuários exibe uma lista com os usuários do sistema, e permite a criação de novos usuários.

Os usuários são as pessoas que utilizam o sistema, tanto para abrir quanto para atender chamados. Para que as funcionalidades de atendimento e solicitação de tickets funcionem corretamente, é necessário a criação de usuários, e a atribuição de grupos e papéis para cada usuário. Os grupos e papéis definem se o usuário é um cliente, atendente ou administrador, e cada grupo e papel possui permissões de acesso diferentes.

Para acessar a funcionalidade, selecione a aplicação de Gestão de Pessoas no menu de aplicações, depois clique em Usuários no menu de navegação principal.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/cfeTMnwsR6Ojmv0J4dJhT_image.png" size="32" width="238" height="293" position="center" showCaption="false"}

# Usuários

A tela de Usuários exibe algumas métricas sobre os usuários cadastrados na plataforma, bem como uma lista:

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/kktDn9-UpLSB353P6yver_image.png)

Os cards no topo da tela exibem o número total de Grupos, Roles e Usuários cadastrados no sistema.

Acima dos cards, no lado direito da tela, são exibidos os botões para [Criar novo Usuário](docId\:nkmrcFbICuv9la0hrM5QB) e Cadastrar novos usuários em massa.

Abaixo dos cards, ao centro da tela, é exibida uma lista com todos os usuários e algumas informações divididas em colunas.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/A22aFNE5k05lhDH5qcoe2_image.png" size="56" width="232" height="77" position="center" showCaption="false"}

No topo da lista, são exibidos botões que permitem **Copiar&#x20;**&#x61; lista para a área de transferência, ou exportar a lista em formato **CSV, XLSX&#x20;**&#x6F;u **PDF.**

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/BH0EbtkD-43rSiiFdASL4_image.png" size="50" width="252" height="78" position="center" showCaption="false"}

No topo da lista, do lado direito são exibidos os campos para **Pesquisar&#x20;**&#x6E;a lista de usuários, **Limpar&#x20;**&#x61; busca realizada, e **Exportar Usuários** em formato CSV.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/0rMBzWxx-szWoFjEaxQnH_image.png)

As colunas da lista de usuários exibem algumas informações sobre cada usuário:

- **nome:&#x20;**&#x4E;ome e sobrenome do usuário.
- **usuário:&#x20;**&#x4C;ogin do usuário.
- **email:&#x20;**&#x45;ndereço de email do usuário.
- **status:&#x20;**&#x41;tivo ou Inativo
- **sessão:**
- **última modificação:&#x20;**&#x44;ata da última modificação das informações do usuário.
- **ações:&#x20;**&#x42;otões para **Editar&#x20;**&#x61;s informações o&#x75;**&#x20;Excluir&#x20;**&#x75;suário.

Se houverem muitos usuários cadastrados, a visualização será dividida em páginas. Utilize as setas no fim da página para navegar entre as páginas.

[title] Roles
[path] Início Rápido/🌐Gestão de Pessoas/

A página de Roles exibe uma lista com os roles do sistema, e permite a criação de novos roles.

Um Role é o papel de determinado grupo de usuários no sistema. Os roles definem se o grupo é de clientes, atendentes ou administradores, e cada role possui permissões de acesso e atribuições diferentes. Os roles são atribuídos aos grupos de usuários, e são utilizados na configuração do Portfolio para definir seu papel dentro do fluxo de determinada atividade.

Para acessar a funcionalidade, selecione a aplicação de Gestão de Pessoas no menu de aplicações, depois clique em Roles no menu de navegação principal.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/SyXnsK__CKOidllb1UAY9_image.png" size="34" width="241" height="279" position="center" showCaption="false"}

# Roles

A tela de Roles exibe uma lista dos papéis cadastrados, com informações divididas em colunas e alguns botões:

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/wvmHBw_g4mlWyfRMHLe06_image.png)

Acima da lista, são exibidos os botões para **Copiar&#x20;**&#x61; lista para a área de transferência, ou exportar a lista em formato **CSV, XLSX&#x20;**&#x6F;u **PDF,** e o botão de **Criar.**

No topo da lista, do lado direito são exibidos os campos para **Pesquisar&#x20;**&#x6E;a lista de roles.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/S2-WrKpA0diPqkNexjWuB_image.png)

As colunas da lista de grupos exibem algumas informações sobre cada grupo:

- **Nome:&#x20;**&#x4E;ome do role.
- **Descrição:&#x20;**&#x44;escrição do role.
- **Ações:&#x20;**&#x42;otão par&#x61;**&#x20;Excluir&#x20;**&#x72;ole.

Se houverem muitos papéis cadastrados, a visualização será dividida em páginas. Utilize as setas no fim da página para navegar entre as páginas.

## Criar role

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/xys9WLUEyeE2RPx1nJgZD_image.png" size="26" width="91" height="53" position="center" showCaption="false"}

Para criar um novo papel, clique no botão **+Criar&#x20;**&#x6E;o topo da tela.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/sSwlU4tdkjUxnSVIJ1znr_image.png" size="70" width="384" height="236" position="center" showCaption="false"}

Inclua um **Nome&#x20;**&#x65; uma **Descrição&#x20;**&#x70;ara o seu role, e clique em **Criar&#x20;**&#x70;ara salvar ou **Fechar&#x20;**&#x70;ara cancelar.

[title] BSC
[path] Aplicações/

# Gestão estratégica (BSC)

***

### Manual do usuário

Versão 1.0 — 09/10/2026

Os exemplos e as telas usam a organização fictícia **Empresa Exemplo S.A.** e pessoas fictícias.

***

# Como usar este manual

Cada capítulo cobre um módulo do Bússola/BSC e se divide em seções numeradas. Toda seção tem um **identificador estável** no formato **BSC-\<MÓDULO>-NN** (por exemplo, BSC-RIS-04), impresso logo abaixo do título e gravado como marcador do documento. O identificador não muda entre versões do manual: use-o para citar uma funcionalidade.

Cada seção traz: **para que serve**, **quem usa** (o perfil funcional), o **passo a passo** numerado — no formato Menu › Tela › ação —, as **telas** com legenda e as **observações** com regras importantes.

O final traz o glossário e o **Índice de seções** (identificador → título → página).

Os nomes de pessoas, unidades, projetos e números que aparecem nos exemplos e nas telas são fictícios.

[title] 9. Disparo em escala e painel do framework
[path] Aplicações/GRCS/

*Despachar agrupamentos para um alvo ou para mil e trezentos, decidir a sobreposição e acompanhar quem respondeu e como está o conjunto.*

Numa auditoria de um alvo só, a onda se monta dentro do ciclo, em **Ondas de disparo** — ver *Auditoria, ondas e respostas*. Num programa com centenas de alvos, ela se monta no **Painel do framework** (menu Auditoria), que é também onde se lê o que voltou da rodada anterior: quem olha o resultado e decide o que perguntar em seguida está na mesma tela.

O que entra numa onda são os **agrupamentos** recortados no catálogo — ver *Agrupamentos*.

***

### <font color="#15803D">Disparar para muitos alvos</font>

A gaveta **Montar a onda** abre em **Painel do framework ▸ Montar onda**, já na auditoria escolhida no painel. Ela pede, nesta ordem:

1.     **Agrupamentos desta onda** — marque quantos quiser; pergunta que esteja em dois entra uma vez só. Sem ao menos um, não se monta.

2.     **Alvos** — **por atributo**, e não caixa por caixa: **todos os N**, **nenhum**, *procurar pelo nome*, *qualquer tipo*, *qualquer situação* (ainda não respondeu nada, respondendo, respondeu tudo), **sem área responsável** e **só os escolhidos**; **marcar os N do recorte** marca o que o filtro mostra. A contagem do que está escolhido fica no topo.

3.     **O que fazer com as já respondidas**, quando houver sobreposição: **decidir uma a uma**, ou o lote inteiro — *deixar de fora da onda*, *reaproveitar todas*, *perguntar todas de novo*.

4.     **Para quem, e até quando** — **Equipe** e **Prazo**. Equipe sem ninguém ativo aparece desabilitada.

O botão final diz o que vai acontecer: **Montar e disparar para N alvo(s)**, com equipe escolhida, ou **Montar (fica em rascunho)**, sem ela — a onda em rascunho não sai para ninguém.

**Cada alvo vai para a própria área responsável**, pelo vínculo declarado em *Alvos e dimensões*. A equipe escolhida aqui é o **destino padrão**, para os alvos que ainda não têm responsável — um único alvo sem área não pode travar o despacho dos outros mil e trezentos.

**Cada alvo responde o seu.** Quem responde vê as respostas do seu alvo e mais nada; quem conduz o ciclo vê tudo, porque consolidar exige.

***

### <font color="#15803D">Sobreposição: reaproveitar ou perguntar de novo</font>

Quando a pergunta já foi respondida por aquele alvo, nada acontece sozinho. **Reaproveitar** faz a resposta vigente contar também nesta onda; **perguntar de novo** devolve a pergunta para a fila. Sem decisão, ela fica de fora.

Até dois mil itens você decide **um a um**, vendo a onda de origem, a data e o valor. Acima disso a decisão é **do lote inteiro**, declarada na tela: decidir setenta mil itens um a um não é rigor, é uma tela que ninguém termina. Para decidir caso a caso numa onda grande, reduza o recorte.

***

### <font color="#15803D">Acompanhar — Painel do framework</font>

O painel responde na ordem em que a pergunta se faz:

1.     **Quantos responderam**, antes da nota. Uma média sobre 847 de 1.304 apresentada como "a nota do conjunto" é enganosa, e a diferença não aparece se ninguém a disser.

2.     **Como está cada agrupamento** no conjunto.

3.     **A distribuição por faixa** — média de mil e trezentos esconde os extremos, e o extremo ruim é o que justifica o programa existir.

4.     **O alvo individual**, clicando no agrupamento: lista paginada, com busca, **ordenada da pior nota para a melhor e com quem não respondeu à frente**. Ausência de nota não é nota boa.

Como usar:

1.     Escolha a **Auditoria** (abre na primeira em execução) e o **Framework** — o painel é sempre de um framework só.

2.     Leia os indicadores de situação, **Por agrupamento** e **Distribuição por faixa**.

3.     Clique num agrupamento para descer ao alvo: **por alvo** (com *procurar alvo pelo nome ou código* e páginas de cinquenta, **anterior** / **próxima**) ou **por área**, que ordena as áreas da pior nota para a melhor e mostra à parte os alvos sem área nem equipe. **voltar ao consolidado** sobe.

4.     **Montar onda** abre a gaveta de despacho descrita acima.

A palavra que a tela usa para o alvo vem do **cadastro**: quando todos os alvos do ciclo são do mesmo tipo, ela usa o nome dele — "Órgãos", "Contratos".

***

### <font color="#15803D">O que isso custa, em escala</font>

Um ciclo do PPSI para 1.304 órgãos são **445.968 respostas**. Nessa massa, o painel consolidado responde em cerca de 1,9 s, o drill-down de cinquenta alvos em 58 ms, e montar e disparar uma onda de 70 mil perguntas leva cerca de 16 s.

:::hint{type="info"}
**Ao lançar um programa desse tamanho, peça um \`ANALYZE\` ao banco logo depois da abertura.** As respostas nascem todas de uma vez, e até o banco recolher estatística nova o planejador escolhe planos ruins — a mesma consulta que leva 285 ms pode levar mais de dois minutos nesse intervalo.
:::


[title] 29. Sessão, trilha e contas de serviço
[path] Aplicações/GRCS/

*Por que a sessão expira, o rastro de cada alteração e a identidade própria das integrações.*

Três garantias que sustentam a regra *tudo é editável, e tudo fica registrado*: a sessão não fica aberta para sempre, toda alteração deixa rastro, e integração não usa o login de uma pessoa.

***

### <font color="#15803D">A sessão expira por inatividade</font>

O tempo de vida do token **é** a janela de inatividade. Cada ação sua renova a janela; parar de usar derruba a sessão sozinho. A janela é de cada tenant: o console da instalação a define (de 5 a 720 minutos), e sem escolha vale o padrão da instalação. Um segundo limite impede que a sessão viva para sempre só porque alguém continua mexendo.

***

### <font color="#15803D">A exceção, e o preço dela</font>

O perfil de **Monitoramento** não tem **desconexão por inatividade** nem o limite de duração da sessão — uma tela parada na parede não deve deslogar sozinha. O token dele ainda tem prazo: vale 24 horas e a própria tela o renova antes de vencer. Renovar é o que prova que a tela ainda existe: um token copiado de uma televisão que ninguém mais usa para de valer sozinho no dia seguinte. Se o perfil da tela deixar de ser *sem inatividade*, a sessão que já estava aberta passa a valer como as outras na renovação seguinte: volta a cair por inatividade e ganha, dali em diante, o limite de duração.

:::hint{type="info"}
Justamente por isso ele **não recebe nenhuma permissão de escrita**, e o banco recusa qualquer tentativa de dar-lhe uma. Sessão sem inatividade somada a direito de alterar significaria que quem passa perto da televisão altera o painel que a diretoria lê, sem nada que encerre esse acesso.
:::

***

### <font color="#15803D">A trilha de auditoria</font>

Tudo é editável, e toda alteração é registrada campo a campo: quem mudou, quando, de que valor para qual. A trilha é **append-only** — a aplicação não consegue reescrevê-la nem apagá-la.

Em **Configuração ▸ Trilha de auditoria** (permissão admin\:usuarios), para achar uma alteração:

1.     Escolha a tabela em **Todas as tabelas** — cada opção mostra quantas alterações ela tem.

2.     Para um registro específico, cole o identificador em **Id do registro…**; clicar no registro de uma linha faz o mesmo filtro (**Ver tudo o que aconteceu com este registro**).

3.     Em **Quem alterou…**, digite o login; no seletor de período, escolha de **Últimas 24 horas** a **Desde sempre** (o padrão é **Últimos 30 dias**).

4.     Marque **incluir sessão e token** só quando procurar login e sessão — por padrão eles ficam fora, porque cada entrada gera uma alteração e afoga o dado de negócio.

5.     **Exportar esta página** baixa o que está na tela; **limpar filtros** volta ao padrão.

Cada linha diz o que foi **criado**, **alterado** ou **excluído**, por quem e quando, com os campos e os dois valores lado a lado. O selo de origem diz se veio de uma pessoa pela interface, de uma integração pela API ou da própria plataforma (carga de catálogo, migração, rotina).

***

### <font color="#15803D">Entrar pela organização</font>

A plataforma autentica de dois modos: **local**, guardando usuário e senha, ou por **gestor de identidade externo**, via OpenID Connect. A escolha é de configuração, e nada abaixo da camada de segurança sabe qual está em uso — nos dois casos o que circula depois é o mesmo token com login, tenant e permissões.

A tela **Administração ▸ Diretório e identidade** mostra o que está valendo e prova que o provedor responde. O capítulo *Integração com o diretório* trata dela.

***

### <font color="#15803D">Contas de serviço</font>

Identidade de sistema, com chave própria e perfil próprio, para integrações. Integrar com o login de uma pessoa faz o sistema parar quando o token dela expira, herda as permissões de quem emprestou o acesso e registra na trilha um responsável que não fez nada daquilo.

Em **Administração ▸ Contas de serviço**:

1.     Clique em **Nova conta**.

2.     Preencha **Nome** (ex.: Integração com o SIEM) e **O que ela faz** — é o que explica a conta a quem ler a trilha daqui a um ano.

3.     Em **Perfil**, escolha o menor perfil que cobre a integração: ela poderá tudo o que o perfil permite, e nada além. Escolher o de administrador "porque funciona" é o problema que a tela existe para evitar.

4.     Opcional: **Vence em** — prazo obriga alguém a reconfirmar que a integração ainda existe.

5.     Clique em **Criar e mostrar a chave** e use **copiar**. A chave aparece **uma vez só**: o que fica guardado é o hash, e nem o administrador a vê de novo. Guarde-a no cofre da integração.

A integração envia a chave no cabeçalho X-API-Key. Cada conta mostra o perfil, quando foi criada, quando vence e o último uso (**nunca usada** aparece destacado). Os três ícones da linha (o nome aparece ao passar o mouse):

•     a seta circular — **Gerar chave nova; a atual para de valer**. É o que fazer quando a chave vaza: troca o segredo e mantém nome, perfil e histórico;

•     o círculo cortado — **Revogar**: a conta para de autenticar e continua explicando a trilha;

•     a lixeira — **Apagar**. Quase sempre pior que revogar: a trilha passa a apontar para um identificador sem nome.

Os três perguntam antes, porque os três derrubam a integração na hora: a pergunta mostra o último uso da conta, e o botão diz o que vai acontecer — **Gerar chave nova**, **Revogar** ou **Excluir**. O foco nasce no **Cancelar**, e o **Esc** desiste.

**Abrir a documentação da API** abre, numa aba nova, a descrição de todas as rotas (Swagger), já com o tenant de quem abriu. A aba entra por um acesso de 30 minutos que o botão concede: o token da sua sessão não vai para o endereço, e o link copiado para outra pessoa não abre nada.

**De qual tenant é a chave.** A tela mostra o **tenant destas chaves**, com código e id. Toda chave criada aqui pertence a ele, e é a própria chave que diz o tenant ao servidor: não há como uma chave gravar noutro tenant. Atrás de um API gateway com endereço único para todas as empresas, mande também o cabeçalho X-Tenant com o código (ou o id) do tenant. Ele **confere**, não escolhe: se não for o tenant da chave, a chamada é recusada (403), e uma chave trocada é pega na porta em vez de gravar no lugar errado. No login de pessoa pela API (POST /api/v1/auth/login) por um gateway desses, é o X-Tenant que diz o tenant.

As contas de serviço são o que liga à plataforma o coletor da *Área de automação* (perfil **Coletor de inspeção**), as integrações de casos e as plataformas que enviam dado ao *IMR*.

[title] 31. Idiomas
[path] Aplicações/GRCS/

*Como a plataforma, o portal, o responder, o console, o conteúdo e o manual falam português, inglês e espanhol.*

A plataforma opera em **português, inglês e espanhol**. O seletor, pelas bandeiras, fica nas **Preferências** (a engrenagem no layout de portal; o seu nome no menu lateral), na tela de entrada e no alto do **portal de atendimento**, do **portal de resposta** e do **console da instalação** — quem chega de fora encontra o idioma antes de precisar ler o menu que não entende. A escolha fica guardada no navegador. Ver *Layout e aparência*.

***

### <font color="#15803D">Duas metades, e elas são diferentes</font>

**A interface** é traduzida no navegador. Menu, títulos, botões e mensagens vêm de um dicionário por idioma.

**O conteúdo** — frameworks, temas, perguntas, controles — é traduzido no servidor. A escolha do seletor viaja em cada chamada no cabeçalho Accept-Language, e o servidor devolve o texto no idioma pedido.

As duas andam juntas de propósito. Uma interface em espanhol com as perguntas em português é pior do que não traduzir nada: parece defeito, e quem responde fica em dúvida se entendeu a pergunta.

***

### <font color="#15803D">Tradução é parcial por natureza, e isso é tratado</font>

Um framework recém-importado existe só no idioma em que foi escrito. Um texto sem tradução **aparece no idioma de origem**, e não em branco nem como um código.

É uma decisão, e não uma limitação: um campo vazio esconde informação, e um identificador na tela (tela.auditorias.titulo) é pior ainda, porque não diz nada a ninguém. Ver a frase em português é informação de verdade — e mostra, de relance, exatamente o que falta traduzir.

***

### <font color="#15803D">O que está traduzido hoje</font>

| **Parte**                                                                                                                                                       | **Situação**                 |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- |
| Telas da plataforma, do portal, do responder e do console                                                                                                       | nos três idiomas             |
| Mensagens que o servidor manda para a tela                                                                                                                      | nos três idiomas             |
| Catálogo de fábrica: frameworks, temas, perguntas (enunciado, orientação e evidência esperada), controles, requisitos, agrupamentos, tipos e opções de resposta | nos três idiomas             |
| Nomes dos painéis, widgets e consultas que vêm de fábrica                                                                                                       | nos três idiomas             |
| Manual                                                                                                                                                          | nos três idiomas             |
| Respostas das análises de IA e do assistente                                                                                                                    | no idioma de quem pediu      |
| Conteúdo que cada cliente cria (perguntas próprias, documentos, respostas)                                                                                      | no idioma em que foi escrito |

Os marcadores de vocabulário (**empresa** ou **órgão**, ver *Vocabulário da instalação*) seguem o idioma: "\{da\_entidade}" sai "da empresa" em português, "of the company" em inglês e "de la empresa" em espanhol.

O conteúdo escrito em outro idioma também aparece traduzido para o português, quando a tradução existe: um framework importado em inglês mostra o texto original para quem usa em inglês e a tradução para quem usa em português.

A troca de idioma vale na hora: a tela é redesenhada no idioma novo, sem sair da sessão. O dicionário de cada idioma é baixado só quando ele é escolhido; quem usa em português não baixa os outros dois.

***

### <font color="#15803D">Traduzir uma resposta</font>

Resposta escrita em outro idioma (por exemplo, a evidência de um fornecedor em inglês) pode ser traduzida, uma por vez: o botão **Traduzir** abaixo da justificativa pede a tradução ao modelo de IA do tenant, no idioma da tela, e **Ver original** volta ao texto escrito. Nada é traduzido sozinho nem em lote, e a tradução não é gravada: ela não substitui o que foi respondido.

***

### <font color="#15803D">Para traduzir conteúdo próprio</font>

Um framework próprio importado por manifesto pode trazer as traduções junto:

```javascript
{ "codigo": "Q-MINHA-01",
  "enunciado": "Existe MFA no acesso administrativo?",
  "traducoes": {
    "en-US": { "enunciado": "Is MFA enforced on administrative access?" },
    "es-ES": { "enunciado": "¿Se exige MFA en el acceso administrativo?" }
  } }

```

O mesmo vale para tema e para framework. O que não vier traduzido continua aparecendo no idioma em que foi cadastrado.

[title] 32. Layout e aparência
[path] Aplicações/GRCS/

*O layout de portal e o menu lateral, a página inicial, as Preferências e as cores de cada site.*

A plataforma tem dois layouts para a área de auditoria. As telas, as permissões e a ajuda são as mesmas nos dois — só a casca muda.

•     **Portal** (padrão): a barra da marca no topo, a barra de seções logo abaixo e uma página inicial com destaque, atalhos e quadros. É o mesmo desenho do portal de atendimento, do portal de resposta e do console.

•     **Menu lateral**: o menu de sempre, à esquerda, com os grupos recolhíveis e a busca no menu.

***

### <font color="#15803D">A página inicial</font>

No layout de portal a plataforma abre no **Início**:

•     o **destaque** com a busca de telas ("riscos", "aprovações", "painéis"…);

•     os **atalhos** com as contagens do que pede ação: auditorias em andamento, NCs sem tratamento, riscos acima do apetite, documentos para aprovar, perguntas para responder e leitura obrigatória;

•     os **quadros**: auditorias em andamento com o quanto já foi respondido, documentos para aprovar, o resumo das NCs e dos riscos, a leitura obrigatória e as perguntas que esperam a sua resposta.

Cada atalho e cada quadro só aparece para quem tem a permissão da tela que ele resume, e os números são os da própria tela — clicar leva a ela.

***

### <font color="#15803D">As seções e o menu de cada grupo</font>

A barra de seções tem um botão por grupo (Gestão, Auditoria, Tratamento, Automação, Acervo, Análise, IMR, Catálogo, Configuração, Administração). Clicar abre o menu do grupo, com cada tela e uma linha dizendo o que ela é; **Página de…** abre a página do grupo, com todas as telas dele. A seção da tela aberta fica sublinhada. Esc fecha o menu.

A busca da barra da marca acha qualquer tela pelo nome, em qualquer grupo.

***

### <font color="#15803D">O cabeçalho</font>

Nos dois layouts o cabeçalho mostra à vista só o que se usa todo dia, em ícone com dica:

•     a **faísca** abre o assistente (*O assistente*);

•     o **?** abre a ajuda da tela em que você está;

•     o **sino** abre os avisos, com o número dos que você ainda não leu.

O resto fica nas **Preferências**: no layout de portal, pelo botão de engrenagem; no menu lateral, pelo seu **nome**, à direita — e no menu lateral o nome da tela aberta aparece ao lado da marca.

***

### <font color="#15803D">Preferências</font>

As Preferências reúnem:

•     **Idioma**, pela bandeira: Brasil (português), Espanha (espanhol) e Estados Unidos (inglês). O leitor de tela anuncia o nome do idioma, não a bandeira.

•     **Tamanho do texto**: normal, maior e o maior.

•     **Tema**: claro, escuro ou cinza.

•     **Layout**: portal ou menu lateral, quando a organização deixa cada pessoa escolher.

•     **Segundo fator da minha conta**, **Imprimir esta tela** e **Como funciona, de ponta a ponta**.

•     No menu lateral, também o **Sair**.

Esc ou um clique fora fecha o painel.

***

### <font color="#15803D">Quem decide o layout</font>

•     O **console** define, por tenant, o layout padrão e se cada pessoa pode escolher o seu (Console → tenant → **Layout da plataforma**).

•     Com a escolha liberada, cada pessoa troca nas Preferências; a escolha fica gravada na conta e vale em qualquer navegador. **Voltar ao padrão da organização** apaga a escolha própria.

•     Com a escolha desligada, todos veem o padrão. A escolha de ninguém é apagada: se a escolha voltar a ser permitida, cada um reencontra a sua.

***

### <font color="#15803D">As cores de cada site</font>

São três sites com cores próprias, definidas no console (tenant → **Cores dos sites**): a **Plataforma** (a área de auditoria, no layout de portal e no menu lateral), o **portal de atendimento** e o **portal de resposta**. Cada um tem barra superior, barra das seções, destaque da página inicial e cor de ação (botões, links e ícones dos atalhos).

•     A cor do texto sobre cada faixa é escolhida sozinha, branca ou escura, pelo contraste.

•     O selo de cada cor diz se o texto chega ao mínimo de leitura (WCAG AA, 4,5:1).

•     No tema escuro e no cinza a cor de ação é clareada até ler sobre o fundo do tema.

•     A Plataforma **herda as cores do portal de atendimento** até o tenant gravar cores próprias para ela. Era assim antes de a plataforma ter cores suas, e um tenant que já tinha personalizado o portal não muda de cor sozinho. Plataforma igual ao portal não se grava: continua acompanhando o portal.

•     Sem cores definidas, o portal e o portal de resposta ficam com as do produto (e a Plataforma, com as do portal).

***

### <font color="#15803D">O aplicativo instalado</font>

Quem instala a plataforma como aplicativo (*Instalar como aplicativo*) recebe o aplicativo **do tenant**, e não um genérico: o manifesto sai do endereço por onde a pessoa chegou.

•     **Nome** — o nome de exibição do tenant.

•     **Ícone** — gerado do logotipo do tenant, centrado num quadrado branco, sem a margem vazia do arquivo, nos tamanhos que os sistemas pedem (inclusive a versão que o lançador recorta em círculo). Só funciona com logotipo em **PNG** ou **JPEG**; com **WebP**, ou sem logotipo, fica o ícone do produto.

•     **Cor da barra** — a da barra superior da Plataforma; sem ela, a do portal de atendimento; sem ela, a do portal de resposta; e, por fim, a do produto.

Trocar o logotipo ou as cores vale para quem instala dali em diante. Quem já tinha instalado pode ver o ícone antigo por um tempo: cada navegador decide quando relê o manifesto, e às vezes é preciso desinstalar e instalar de novo para o ícone trocar.

[title]  8. Gestão de riscos
[path] Aplicações/BSC/

A gestão de riscos do Bússola/BSC começa pelo método: com que tipos de risco a empresa trabalha e com que régua cada risco é medido. O nível de um risco é a pontuação da probabilidade multiplicada pela pontuação do impacto, nas escalas definidas pela própria empresa, e acima de certo nível o risco fica fora do apetite e passa a ser prioridade. Quem define escalas e cortes é a governança, por isso o método fica numa tela própria, mantida pela Diretoria de Estratégia, e toda avaliação usa o que estiver configurado ali.

Com o método pronto, cada área registra os seus riscos no Registro de riscos: o evento, as causas e as consequências, a natureza, a área, o responsável, os vínculos com o que o risco ameaça e duas avaliações na mesma matriz — o risco inerente (sem nenhuma ação gerencial) e o risco residual planejado (onde a área se compromete a levar o risco depois do tratamento). Cada risco recebe tratamentos com responsável, área e prazo; os executores lançam o andamento com evidências; os fatos que materializam o risco são registrados como ocorrências.

As telas ficam no menu lateral, grupo Governança e riscos: Registro de riscos, Mapa de riscos, Matrizes e naturezas de risco e Modelos de plano de riscos. Os exemplos deste capítulo usam a Empresa Exemplo S.A., com riscos como "Atraso na emissão de licenças ambientais da Ponte do Vale" e "Contingenciamento do orçamento das obras".

## 8.1 Naturezas de risco

ID BSC-RIS-01

### Para que serve

As naturezas formam a tipologia que classifica cada risco: operacional, imagem/reputação, legal, financeiro/orçamentário, integridade e segurança, além das que a empresa criar. Cada natureza informa se a empresa a analisa de forma qualitativa ou quantitativa; nas duas abordagens a pontuação continua sendo peso da probabilidade × peso do impacto.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia); Responsável por ação/área.

### Passo a passo

1\.  Abra Governança e riscos › Matrizes e naturezas de risco e selecione a aba **Naturezas**.

2\.  Confira o catálogo: cada linha mostra o código, o nome com a descrição, a abordagem e a situação.

3\.  Para mudar a abordagem, clique no lápis da natureza, troque **Abordagem de análise** (por exemplo, para **Quantitativa** em Financeiro/Orçamentário) e salve.

4\.  Para criar uma natureza, clique em **Nova natureza** e informe **Código** curto em maiúsculas, **Nome**, **Descrição** e abordagem.

5\.  Use o botão de liga/desliga para inativar ou reativar uma natureza.

6\.  Clique no relógio da linha para ver o histórico da natureza, com o antes e o depois de cada campo.



![](https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/QVB_KRu4vsvL_eIodfwsg_upload.png)

Figura 66 — Matrizes e naturezas de risco: catálogo de naturezas com a abordagem de análise.

### Observações

·        O produto já vem com seis naturezas, todas qualitativas.

·        Código e nome não se repetem; o nome é comparado sem diferença de maiúsculas e minúsculas.

·        Natureza inativa some da escolha dos riscos novos, mas os riscos que já a usam continuam com ela.

·        Quem trabalha no registro de riscos abre a tela só para consulta, sem botões de alteração; quem não tem permissão de riscos lê que não tem acesso.

## 8.2 Leitura das matrizes de risco

ID BSC-RIS-02

### Para que serve

A matriz de risco é a régua: uma escala de probabilidade e uma de impacto, cada nível com rótulo, critério e peso, e as faixas de risco que transformam a pontuação em criticidade (Risco Baixo, Médio, Alto, Extremo), com cor, rótulo curto e marca de dentro ou fora do apetite. A empresa pode manter várias matrizes ao mesmo tempo, e uma delas é a padrão dos riscos novos.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia); Responsável por ação/área; Leitor/Auditor.

### Passo a passo

1\.  Abra Governança e riscos › Matrizes e naturezas de risco e selecione a aba **Matrizes**.

2\.  Em cada cartão, confira nome, versão (v1, v2…), situação (**Ativa**, **Rascunho** ou **Aposentada**) e os selos **Padrão** e **Em uso**.

3\.  Leia a grade: linhas são a probabilidade (a mais provável em cima), colunas são o impacto; cada célula traz a pontuação e o rótulo curto da faixa, na cor da faixa.

4\.  Passe o mouse (ou o leitor de tela) sobre uma célula para ler por extenso os níveis, a pontuação e a faixa.

5\.  Ao lado da grade, leia as faixas: rótulo curto, nome, intervalo de pontuação, **Dentro do apetite** ou **Fora do apetite** e a ação requerida.

6\.  Num rascunho incompleto, leia a lista **Para ativar esta matriz, ainda faltam:**.



![](https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/FPgXGQLPTuN7NaCURPKth_upload.png)

Figura 67 — Cartão de matriz com a grade probabilidade × impacto e as faixas de risco.

### Observações

·        O produto já vem com a Matriz corporativa 5×5, ativa e padrão (pesos 1, 2, 5, 8 e 10; faixas Baixo 0–10, Médio 10–40, Alto 40–80 e Extremo 80–100, as duas últimas fora do apetite), e com uma matriz processual 3×3 em rascunho, sem faixas.

·        As cores das faixas da matriz corporativa são sugestão do produto; troque-as se a empresa usar outras.

·        O texto da célula fica preto ou branco conforme o contraste: a cor nunca é o único sinal.

## 8.3 Completar e ativar uma matriz

ID BSC-RIS-03

### Para que serve

O editor de matriz permite definir as escalas de probabilidade e impacto e as faixas de risco, com uma prévia da grade atualizada a cada alteração. Uma matriz só é ativada quando está completa, com faixas cobrindo todas as pontuações possíveis.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador).

### Passo a passo

1\.  Em Governança e riscos › Matrizes e naturezas de risco, aba **Matrizes**, clique em **Editar** no cartão da matriz em rascunho.

2\.  À esquerda, informe o nome e as características (quando a matriz é usada e de onde vêm as escalas).

3\.  Em **Níveis de probabilidade** e **Níveis de impacto**, informe **Rótulo**, **Peso** e **Critério** de cada nível; use **Adicionar nível** para incluir e a lixeira para remover.

4\.  Em **Faixas de risco**, clique em **Adicionar faixa** e informe rótulo, rótulo curto (até 8 caracteres), pontuação **De** e **Até**, cor, **Dentro do apetite a risco** e ação requerida.

5\.  Acompanhe a **Prévia da grade** à direita: uma célula sem faixa aparece tracejada com **?**.

6\.  Corrija os problemas listados em vermelho ao lado da grade; enquanto houver problema, **Salvar** fica desabilitado.

7\.  Salve. A matriz pode ficar em rascunho mesmo sem faixas; o aviso amarelo diz o que falta para ativar.

8\.  No cartão, clique em **Ativar**.



![](https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/nL4n4TqoZ1hYzPoFxYoNa_upload.png)

Figura 68 — Editor de matriz com escalas, faixas e prévia da grade.

### Observações

·        Os níveis vão do menor para o maior, e cada peso tem de ser maior que o do nível anterior; até 10 níveis por eixo.

·        Cada faixa vale da pontuação De (inclusive) até a Até (exclusive); só a última inclui o próprio limite. Exemplo para pesos 5, 10 e 15: faixas 0–50, 50–100 e 100–225.

·        Problemas apontados: pontuação sem faixa, faixas sobrepostas, faixas que não chegam à menor ou à maior pontuação, peso fora de ordem e cor inválida.

·        Para ativar: pelo menos dois níveis em cada eixo e faixas cobrindo todas as pontuações. Ativada, a matriz passa a ser oferecida aos riscos novos.

## 8.4 Escolher a matriz padrão

ID BSC-RIS-04

### Para que serve

A matriz padrão é a sugerida para todo risco novo. Existe sempre uma única matriz padrão, e ela precisa estar ativa.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador).

### Passo a passo

1\.  Em Governança e riscos › Matrizes e naturezas de risco, aba **Matrizes**, localize o cartão de uma matriz **Ativa** que não seja a padrão.

2\.  Clique em **Tornar padrão**.

3\.  Confira que o selo **Padrão** passou para esta matriz e saiu da anterior.



![](https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/6UPf_N31SRj-GFzQjLpH2_upload.png)

Figura 69 — Selo Padrão no cartão da matriz.

### Observações

·        Só uma matriz ativa pode ser a padrão.

·        A mudança fica registrada no histórico da matriz.

## 8.5 Nova versão de uma matriz já usada

ID BSC-RIS-05

### Para que serve

Uma régua que já avaliou riscos não muda por baixo deles: se um peso fosse trocado, riscos antigos mudariam de cor sem reavaliação. Por isso, assim que uma avaliação usa a matriz, ela ganha o selo Em uso e só pode ser alterada por meio de uma nova versão.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador).

### Passo a passo

1\.  Em Governança e riscos › Matrizes e naturezas de risco, aba **Matrizes**, no cartão com o selo **Em uso**, clique em **Nova versão**.

2\.  O sistema copia a matriz num rascunho com o número de versão seguinte, com as mesmas escalas e faixas.

3\.  Ajuste a cópia no editor, como numa matriz em rascunho.

4\.  Clique em **Ativar** na nova versão; a versão anterior é aposentada e, se era a padrão, a nova passa a ser padrão na mesma hora.

5\.  Se desistir, use **Excluir rascunho** numa versão que nunca foi ativada.



![](https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/Ncex--nXhjG0VvYqRX59i_upload.png)

Figura 70 — Matriz Em uso com o botão Nova versão.

### Observações

·        Enquanto houver uma nova versão em rascunho, não é possível abrir outra (o cartão mostra **Nova versão em rascunho**).

·        Os riscos já avaliados continuam na versão em que foram avaliados, com a pontuação, a faixa e a cor daquele dia.

·        Uma matriz ativa que ainda não foi usada continua editável por **Editar**, mas precisa continuar completa.

## 8.6 Aposentar uma matriz e consultar o histórico do método

ID BSC-RIS-06

### Para que serve

Aposentar retira a matriz da escolha dos riscos novos sem afetar os riscos que já a usam. O histórico de cada matriz registra todas as mudanças do método.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Leitor/Auditor.

### Passo a passo

1\.  Em Governança e riscos › Matrizes e naturezas de risco, aba **Matrizes**, no cartão de uma matriz ativa, clique em **Aposentar**.

2\.  Se a matriz for a padrão, torne outra matriz padrão antes.

3\.  Clique em **Histórico** no cartão para ver quem criou, editou, ativou, tornou padrão, abriu nova versão ou aposentou a matriz, com o antes e o depois de cada campo, inclusive escalas e faixas.

### Observações

·        A matriz padrão não pode ser aposentada.

·        Uma matriz aposentada não volta a ser editada.

## 8.7 Registrar um risco

ID BSC-RIS-07

### Para que serve

O Registro de riscos é a lista corporativa dos riscos de todas as áreas. Cada risco recebe um código sequencial (R-0001, R-0002…) e nasce em rascunho até ser avaliado e ativado.

**Quem usa:** Gestor de Desempenho (escritório de estratégia).

### Passo a passo

1\.  Abra Governança e riscos › Registro de riscos e clique em **Novo risco**.

2\.  Em **O evento de risco**, informe o **Título** (por exemplo, Atraso na emissão de licenças ambientais da Ponte do Vale) e, se quiser, **Descrição do evento**, **Causas** e **Consequências**.

3\.  Em **Classificação e responsabilidade**, escolha a **Natureza** (o campo mostra se ela é qualitativa ou quantitativa).

4\.  Escolha a **Matriz de risco**: vem sugerida a matriz padrão; as outras matrizes ativas também aparecem.

5\.  Escolha a **Área** (por exemplo, GEPVA — Gerência da Ponte do Vale) e o **Responsável pelo risco**, buscando pelo nome.

6\.  Se for um risco de integridade (fraude, corrupção), marque **Sigiloso**.

7\.  Salve: o risco nasce em **Rascunho** com o próximo código e a ficha abre.



![](https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/rk4YsoVJzX0xve7H3_pzm_upload.png)

Figura 71 — Registro de riscos com código, natureza, área, inerente → residual e situação.



![](https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/qyUmPnN90qNnSnZ-RwTi0_upload.png)

Figura 72 — Ficha do risco recém-registrado.

### Observações

·        Área e responsável são obrigatórios: os relatórios são cortados por eles e o responsável acompanha o risco.

·        A lista mostra código, título, natureza com a abordagem, área, responsável, os chips do inerente e do residual planejado com a seta entre eles e a situação.

·        Os filtros cortam por código ou título, área, natureza, matriz e situação; clicar no título de uma coluna ordena o registro inteiro, não só a página.

## 8.8 Vincular o risco ao que ele ameaça

ID BSC-RIS-08

### Para que serve

O vínculo liga o risco ao objetivo estratégico, eixo temático, programa, subprograma ou ação estratégica que ele ameaça. É por esse vínculo que os riscos aparecem no mapa estratégico e na ficha da ação.

**Quem usa:** Gestor de Desempenho (escritório de estratégia).

### Passo a passo

1\.  Em Governança e riscos › Registro de riscos, abra a ficha do risco e vá ao cartão **O que o risco ameaça**.

2\.  Em **Vincular a**, escolha o **Tipo**: **Objetivo estratégico**, **Eixo temático**, **Programa** ou **Ação estratégica**.

3\.  Busque o **Item** pelo nome (a ação estratégica também pelo código, por exemplo PV-01).

4\.  Clique em **Vincular**; o vínculo aparece no cartão e o histórico registra a inclusão.

5\.  Para remover, clique na lixeira do vínculo.



![](https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/cxjFL2VqFHfjS1eykNaGA_upload.png)

Figura 73 — Cartão O que o risco ameaça com os vínculos do risco.

### Observações

·        O mesmo item não pode ser vinculado duas vezes ao mesmo risco.

·        Programas com programa-pai aparecem como **Subprograma** (por exemplo, Ponte do Vale, do PROROD).

·        A busca oferece objetivos e eixos de ciclos não encerrados, programas ativos e ações não concluídas nem canceladas.

·        Objetivo sigiloso só aparece para quem pode ver objetivos sigilosos; os demais veem **Item restrito**. Ação sigilosa só aparece para o gestor dela e para quem gerencia a carteira.

·        Numa ação concluída ou cancelada os riscos não mudam mais: o sistema recusa vincular e desvincular. O mesmo vínculo pode ser feito pela aba **Riscos** da ação.

## 8.9 Avaliar o risco inerente e o residual planejado

ID BSC-RIS-09

### Para que serve

A avaliação posiciona o risco numa célula da matriz. O risco inerente é a exposição sem nenhuma ação; o residual planejado é a meta de redução que a área assume com o tratamento, não o residual calculado por auditoria.

**Quem usa:** Gestor de Desempenho (escritório de estratégia).

### Passo a passo

1\.  Na ficha do risco (Governança e riscos › Registro de riscos), vá ao cartão **Avaliação**: à esquerda a mini-matriz do **Risco inerente**, à direita a do **Risco residual planejado**.

2\.  Clique na célula de probabilidade × impacto do inerente (por exemplo, Média × Alto na matriz 5×5).

3\.  Confira a prévia calculada pelo sistema: pontuação (40), faixa (**Risco Alto**), cor e **Fora do apetite**.

4\.  Clique em **Confirmar avaliação**; o chip do inerente aparece e a célula fica contornada.

5\.  Clique na célula do residual planejado (por exemplo, Baixa × Médio), confira a prévia (10, **Risco Médio**, **Dentro do apetite**) e confirme.

6\.  Confira os dois chips lado a lado com a seta — **RA 40 → RM 10** —, também na lista do registro.



![](https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/LF2m_zVCHk0gH5l_3Kge-_upload.png)

Figura 74 — Cartão Avaliação com as mini-matrizes do inerente e do residual planejado.

### Observações

·        A primeira avaliação congela a matriz do risco: inerente e residual precisam ser lidos na mesma régua, e a matriz passa a ser **Em uso**.

·        O residual planejado só é avaliado depois do inerente.

·        Se o residual escolhido for mais crítico que o inerente, o sistema grava, mas avisa para conferir as células.

## 8.10 Reavaliar um risco

ID BSC-RIS-10

### Para que serve

Quando o risco muda, uma nova avaliação passa a valer, e a anterior permanece na série de avaliações. Nenhuma avaliação é alterada ou apagada.

**Quem usa:** Gestor de Desempenho (escritório de estratégia).

### Passo a passo

1\.  Na ficha do risco, cartão **Avaliação**, clique em outra célula da mini-matriz do mesmo tipo de avaliação.

2\.  Preencha **Por que reavaliar**.

3\.  Confirme a avaliação.

4\.  Consulte a **Série de avaliações**, abaixo do cartão, com data, autor, células, resultado e justificativa; use o relógio da linha para ver o histórico de cada avaliação.



![](https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/86lhcGU7fLd34zN2RDv6K_upload.png)

Figura 75 — Série de avaliações do risco.

### Observações

·        Sem justificativa, a reavaliação não é gravada.

·        Cada avaliação guarda a pontuação, a faixa e a cor do momento em que foi feita, mesmo que a matriz ganhe uma nova versão depois.

## 8.11 Estratégia de resposta e ativação do risco

ID BSC-RIS-11

### Para que serve

A estratégia de resposta registra como a empresa decide lidar com o risco: evitar, transferir, aceitar ou mitigar. Depois de avaliado o inerente, o risco pode ser ativado e passa a contar no mapa e nos indicadores de risco.

**Quem usa:** Gestor de Desempenho (escritório de estratégia).

### Passo a passo

1\.  Na ficha do risco, cartão **Estratégia de resposta**, escolha **Evitar**, **Transferir**, **Aceitar** ou **Mitigar**.

2\.  Se quiser, preencha a **Justificativa** e salve.

3\.  No alto da ficha, clique em **Ativar**.



![](https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/HN1wSvbtpOVfMgss4Eusn_upload.png)

Figura 76 — Cartão Estratégia de resposta e botão Ativar.

### Observações

·        A resposta só é escolhida com o inerente avaliado.

·        Aceitar um risco cujo inerente está fora do apetite exige justificativa; sem ela, o sistema recusa e explica.

·        Um risco só é ativado depois de ter avaliação inerente.

## 8.12 Encerrar e reabrir um risco

ID BSC-RIS-12

### Para que serve

Encerrar retira o risco das contagens de ativos e deixa a ficha só para leitura; reabrir devolve o risco ao trabalho.

**Quem usa:** Gestor de Desempenho (escritório de estratégia).

### Passo a passo

1\.  No alto da ficha, clique em **Encerrar risco** e informe o **Motivo**.

2\.  Para retomar, clique em **Reabrir** e informe o motivo.

3\.  Confira a situação: o risco volta a **Ativo**, ou a **Rascunho** se ainda não tinha avaliação inerente.

### Observações

·        O histórico e as avaliações de um risco encerrado continuam consultáveis.

·        Risco encerrado não recebe alteração, tratamento novo, lançamento nem ocorrência: reabra-o antes.

## 8.13 Riscos sigilosos

ID BSC-RIS-13

### Para que serve

Riscos de integridade, como fraude e corrupção, podem ser marcados como sigilosos. Eles só são vistos por quem tem a autorização de riscos sigilosos.

**Quem usa:** Gestor de Desempenho (escritório de estratégia); Diretoria de Estratégia (patrocinador/aprovador); Leitor/Auditor.

### Passo a passo

1\.  Ao registrar ou editar o risco, marque **Sigiloso**.

2\.  Salve; a partir daí o risco some da lista, das contagens e do mapa para quem não tem a autorização.

3\.  Para conferir, peça a um usuário sem a autorização que abra o endereço da ficha: a resposta é **Risco não encontrado**.

### Observações

·        Só quem pode ver riscos sigilosos pode marcar um risco como sigiloso.

·        Para quem não tem a autorização, o risco sigiloso não aparece na lista, em nenhuma contagem, no mapa nem no sinal do mapa estratégico, e o histórico dele aparece vazio.

·        Exceção: o perfil com acesso à trilha de auditoria lê o histórico de qualquer risco.

·        Avisos de risco sigiloso chegam só ao sino de quem pode vê-lo, nunca por e-mail, WhatsApp, push ou canal de área.

## 8.14 Histórico do risco

ID BSC-RIS-14

### Para que serve

O histórico registra cada mudança do risco, com o antes e o depois, para rastreabilidade e auditoria.

**Quem usa:** Gestor de Desempenho (escritório de estratégia); Leitor/Auditor.

### Passo a passo

1\.  Abra a ficha do risco.

2\.  Selecione a aba **Histórico**.

3\.  Leia quem registrou, editou, vinculou ou desvinculou, escolheu a resposta, ativou, encerrou ou reabriu, com o antes e o depois de cada campo, inclusive a lista de vínculos.

4\.  Para o histórico de uma avaliação, use o relógio da linha na **Série de avaliações**.

### Observações

·        A ligação do risco a um fator SWOT também aparece no histórico do risco.

## 8.15 Cadastrar tratamentos do risco

ID BSC-RIS-15

### Para que serve

O tratamento é a ação que responde ao risco, com pessoa, área e prazo. Um risco fora do apetite precisa de tratamento.

**Quem usa:** Gestor de Desempenho (escritório de estratégia).

### Passo a passo

1\.  Na ficha do risco, cartão **Tratamentos**, clique em **Novo tratamento**.

2\.  Descreva a **Ação a ser executada**.

3\.  Escolha o **Tipo de tratamento**: **Preventivo (mitigação)**, que age antes do evento, ou **Contingência (se o risco se materializar)**.

4\.  Escolha a **Pessoa responsável** (busca por nome) e a **Área responsável**.

5\.  Informe o **Início** (opcional) e o **Prazo**.

6\.  Salve: o tratamento aparece **Aberto**, com 0% e a contagem de dias até o prazo.



![](https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/1O_n0lrvDIHZHd-esk5dD_upload.png)

Figura 77 — Cartão Tratamentos da ficha do risco.

### Observações

·        Pessoa e área responsáveis são campos separados: quem executa nem sempre é da área do risco nem é o responsável pelo risco.

·        Pessoa, área e prazo são obrigatórios; o prazo não pode ser anterior ao início.

·        O lápis edita um tratamento aberto; tratamento concluído ou cancelado não muda mais.

·        Risco encerrado não recebe tratamento novo.

## 8.16 Lançar a execução do tratamento com evidência

ID BSC-RIS-16

### Para que serve

Quem executa o tratamento registra o andamento, com a data, o que foi feito, o percentual acumulado e os arquivos que comprovam a execução.

**Quem usa:** Gestor de Desempenho (escritório de estratégia); Responsável por ação/área.

### Passo a passo

1\.  Na ficha do risco, cartão **Tratamentos**, clique em **Lançar execução** na linha do tratamento.

2\.  Confira a linha do tempo dos lançamentos, do mais recente ao mais antigo.

3\.  Em **Lançar uma execução**, informe a **Data da execução**, **O que foi feito** e o **% executado acumulado** (o total até aqui, não o acréscimo).

4\.  Em **Arquivos de evidência**, anexe a prova: ofício, ata, relatório.

5\.  Clique em **Lançar execução**; o percentual do tratamento passa a ser o lançado.

6\.  Para anexar mais arquivos depois, use **Evidências** no lançamento.



![](https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/gvLx3sIL3PK3vrArv57XA_upload.png)

Figura 78 — Linha do tempo de lançamentos do tratamento, com evidências.

### Observações

·        A data da execução não pode ser futura.

·        Um lançamento de 100% conclui o tratamento, que não recebe mais lançamentos; não há reabertura — cadastre um tratamento novo, se preciso.

·        Nenhum lançamento é editado ou apagado e nenhuma evidência é removida. Cada lançamento e cada tratamento têm o próprio histórico.

·        O responsável nomeado pelo tratamento também lança a execução e anexa evidências pela **Mesa de trabalho**, sem precisar de permissão de riscos; correções continuam sendo feitas na ficha.

·        Arquivo de tipo ou tamanho não aceito é recusado pelo nome.

## 8.17 Corrigir um lançamento de execução

ID BSC-RIS-17

### Para que serve

Um lançamento errado não é apagado: ele é corrigido por um novo lançamento que o referencia, e os dois ficam na linha do tempo.

**Quem usa:** Gestor de Desempenho (escritório de estratégia); Responsável por ação/área.

### Passo a passo

1\.  No cartão **Tratamentos**, clique em **Lançar execução** no tratamento.

2\.  Informe o percentual correto (por exemplo, 50% quando foi lançado 70%).

3\.  Em **Corrige o lançamento**, escolha o lançamento errado.

4\.  Clique em **Lançar execução** e confira as marcas **Corrigido por um lançamento posterior** e **Corrige o lançamento de …**.

### Observações

·        Percentual menor que o do último lançamento sem marcar a correção é recusado; a tela avisa antes de enviar e informa o último percentual.

·        Para trocar uma evidência errada, faça um lançamento de correção com o arquivo certo.

## 8.18 Cancelar um tratamento

ID BSC-RIS-18

### Para que serve

Um tratamento que perdeu o sentido é cancelado com motivo, sem apagar o que já foi lançado.

**Quem usa:** Gestor de Desempenho (escritório de estratégia).

### Passo a passo

1\.  Na ficha do risco, cartão **Tratamentos**, clique em **Cancelar tratamento** na linha.

2\.  Informe o **Motivo do cancelamento**.

3\.  Confirme; o tratamento sai das contagens de abertos e vencidos.

### Observações

·        Tratamento cancelado não aceita mais lançamentos; lançamentos e histórico continuam.

·        Num risco encerrado, o gestor ainda pode cancelar os tratamentos que ficaram abertos.

## 8.19 Tratamentos vencidos e o sinal de riscos no mapa estratégico

ID BSC-RIS-19

### Para que serve

O produto destaca tratamentos com prazo vencido na ficha, no registro e no mapa estratégico, para que a gestão saiba onde agir primeiro.

**Quem usa:** Gestor de Desempenho (escritório de estratégia); Diretoria de Estratégia (patrocinador/aprovador); Responsável por ação/área.

### Passo a passo

1\.  Na ficha do risco, identifique os tratamentos **Vencido**, com os dias de atraso.

2\.  Em Governança e riscos › Registro de riscos, leia a coluna **Tratamentos abertos / vencidos** de cada risco.

3\.  Abra **Gestão por indicadores › Mapa estratégico** e observe o sinal **Riscos** de cada objetivo.

### Observações

·        Vencido é um tratamento aberto, abaixo de 100%, com prazo já passado; um prazo de hoje só vence no fim do dia (calendário de Brasília).

·        O sinal Riscos conta os riscos ativos vinculados ao objetivo que estão sem tratamento (inerente fora do apetite, sem tratamento aberto ou concluído e sem resposta Aceitar justificada) ou com tratamento vencido; cada risco conta uma vez.

·        O sinal aparece para quem lê riscos; riscos sigilosos não entram na contagem de quem não tem a autorização.

·        Tratamentos de riscos em rascunho não entram no sinal até o risco ser ativado.

## 8.20 Filtros de criticidade no registro de riscos

ID BSC-RIS-20

### Para que serve

Além dos filtros básicos, o registro oferece filtros que leem a criticidade e o andamento dos tratamentos, para priorizar os riscos que pedem decisão.

**Quem usa:** Gestor de Desempenho (escritório de estratégia); Diretoria de Estratégia (patrocinador/aprovador); Leitor/Auditor.

### Passo a passo

1\.  Abra Governança e riscos › Registro de riscos.

2\.  Em **Ler na avaliação**, escolha inerente ou residual planejado.

3\.  Em **Apetite**, escolha dentro ou fora.

4\.  Escolha a **Matriz de risco** e, em seguida, a **Faixa**.

5\.  Em **Tratamentos**, escolha com ou sem tratamento vencido.

6\.  Combine "Fora do apetite" e "Com tratamento vencido" para ver os riscos que pedem decisão primeiro.



![](https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/G3q0-2SvML12VvbYJo6_M_upload.png)

Figura 79 — Registro de riscos com filtros de criticidade.

### Observações

·        O filtro **Faixa** só funciona com a matriz escolhida: o rótulo de uma faixa só é inequívoco dentro de uma matriz.

·        Filtrar por um item sigiloso que você não pode ver responde **O item usado como filtro não foi encontrado**.

## 8.21 Mapa de riscos

ID BSC-RIS-21

### Para que serve

O mapa de riscos é a matriz de calor da exposição: probabilidade cresce para cima e impacto para a direita, cada célula na cor da faixa, com o rótulo curto e a quantidade de riscos ativos. Mostra a leitura inerente, a residual planejada e a evolução entre elas, e leva da célula à lista dos riscos.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia); Leitor/Auditor.

### Passo a passo

1\.  Abra Governança e riscos › Mapa de riscos.

2\.  Em **Matriz de risco**, escolha a matriz (a padrão vem escolhida; versões aposentadas com riscos ativos aparecem marcadas como aposentadas).

3\.  Em **Leitura do mapa**, escolha **Inerente**, **Residual planejado** ou **Evolução**.

4\.  Use os filtros **Área**, **Natureza** e **Vinculado a** / **Item vinculado** para recortar o mapa.

5\.  Leia a **Legenda**: cada faixa com rótulo curto, nome, intervalo, cor, apetite e quantidade de riscos.

6\.  Clique numa célula (ou use Tab e Enter) para abrir o **Registro de riscos** filtrado pela matriz, pela leitura e pela célula; o botão "Célula: …" na lista remove esse filtro.

7\.  Consulte a tabela equivalente abaixo do desenho, que repete o mapa em texto para leitores de tela.

8\.  Para imprimir, use a impressão do navegador.



![](https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/by_YfCFsvN0mxSgt_y-Ga_upload.png)

Figura 80 — Mapa de riscos: matriz de calor com quantidades por célula e legenda das faixas.

### Observações

·        Um mapa mostra uma matriz só; riscos de matrizes diferentes nunca são somados.

·        Só riscos ativos contam: rascunhos e encerrados ficam fora. Matriz sem riscos avaliados mostra **Ainda não há riscos avaliados nesta matriz**.

·        Na Evolução, uma seta por par de células indica a quantidade de riscos; um anel marca residual na mesma célula; um ponto marca riscos sem residual planejado, contados na legenda.

·        Para quem não tem a autorização de riscos sigilosos, eles não entram em nenhum número do mapa, e o mapa avisa **Riscos sigilosos não entram na sua contagem**.

·        Exportar o mapa como imagem ou planilha é feito pelos painéis e relatórios (widget de matriz de calor).

## 8.22 Registrar uma ocorrência

ID BSC-RIS-22

### Para que serve

A ocorrência é o fato que materializa o risco, como "em 12/05 o órgão ambiental devolveu o pedido de licença da Ponte do Vale por falta de estudo". Ela compõe o histórico de monitoramento e orienta ações corretivas.

**Quem usa:** Gestor de Desempenho (escritório de estratégia); Responsável por ação/área.

### Passo a passo

1\.  Na ficha de um risco **ativo**, cartão **Ocorrências**, clique em **Registrar ocorrência**.

2\.  Informe a **Data do evento** — o dia em que o fato aconteceu.

3\.  Em **O que aconteceu (descrição circunstanciada)**, descreva o que aconteceu, quando, onde e com quem.

4\.  Se um tratamento do risco já responde ao fato, escolha-o em **Tratamento deste risco que responde ao fato**.

5\.  Em **Documentos do fato**, anexe ofício, notificação ou relatório.

6\.  Salve: a ocorrência entra na linha do tempo do cartão, e a coluna **Última ocorrência** do registro mostra a data.



![](https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/8iQab1BmrSsQLoxxSIZEd_upload.png)

Figura 81 — Cartão Ocorrências com a linha do tempo dos fatos.

### Observações

·        A data do evento não pode ser futura; a descrição exige pelo menos 20 caracteres.

·        Ocorrência só em risco ativo: ative o rascunho ou reabra o risco encerrado antes.

·        O lápis edita data, descrição e tratamento ligado; **Documentos** anexa mais arquivos; **Histórico da ocorrência** mostra todas as mudanças.

## 8.23 Ligar a ocorrência a um tratamento

ID BSC-RIS-23

### Para que serve

Uma ocorrência costuma pedir uma ação corretiva. Ela pode originar um tratamento novo ou ser ligada a um tratamento existente do mesmo risco.

**Quem usa:** Gestor de Desempenho (escritório de estratégia); Responsável por ação/área.

### Passo a passo

1\.  Para um tratamento novo, clique em **Criar tratamento a partir dela** na ocorrência.

2\.  Complete o formulário de tratamento (pessoa e área do risco já vêm preenchidas) e salve; o tratamento é criado e ligado na mesma operação.

3\.  Para um tratamento existente, edite a ocorrência e escolha-o em **Tratamento deste risco que responde ao fato**.

4\.  Confira na ocorrência o texto **Originou o tratamento: …** com a situação dele.



![](https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/RmqgMV13thpIEeXlkmMHe_upload.png)

Figura 82 — Ocorrência ligada ao tratamento que originou.

### Observações

·        Só aparecem tratamentos do próprio risco.

·        Depois que a ocorrência originou um tratamento, o botão de criar não aparece de novo; para trocar, edite a ocorrência.

·        Criar tratamento a partir da ocorrência é de quem gerencia o risco; quem só registra ocorrências pode ligá-la a um tratamento existente.

## 8.24 Retirar uma ocorrência registrada por engano

ID BSC-RIS-24

### Para que serve

Ocorrências não são apagadas. Uma ocorrência registrada no risco errado ou em duplicidade é retirada com motivo e continua consultável.

**Quem usa:** Gestor de Desempenho (escritório de estratégia); Responsável por ação/área; Leitor/Auditor.

### Passo a passo

1\.  Na ocorrência, clique na lixeira (**Retirar ocorrência**).

2\.  Informe o **Motivo da retirada** e confirme.

3\.  Para consultar retiradas, marque **Mostrar retiradas**: aparecem quem retirou, quando e por quê.

### Observações

·        Sem motivo, a retirada é recusada.

·        A ocorrência retirada sai da linha do tempo e da coluna **Última ocorrência**, não muda mais nem recebe documentos.

## 8.25 Modelos de plano de riscos

ID BSC-RIS-25

### Para que serve

Os modelos guardam riscos que se repetem — como contingenciamento do orçamento das obras ou fiscalização contratual insuficiente — com os tratamentos sugeridos, para que um plano novo não comece do zero.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia).

### Passo a passo

1\.  Abra Governança e riscos › Modelos de plano de riscos e clique em **Novo modelo**.

2\.  Informe **Código** (letras sem acento, números, hífen e sublinhado), **Nome** e, se quiser, **Quando usar**.

3\.  Em cada **Risco-modelo**, informe **Risco (o evento)**, **Causas**, **Consequências** e, se quiser, **Natureza** e **Resposta sugerida**.

4\.  Informe, se quiser, **Probabilidade sugerida (posição)** e **Impacto sugerido (posição)**, contadas a partir do nível mais baixo (1).

5\.  Em **Tratamentos sugeridos**, clique em **Adicionar tratamento sugerido** e informe ação, tipo e **Prazo (dias)** a partir da data-base.

6\.  Use **Adicionar risco-modelo** para outros riscos e as setas para ordenar; salve.

7\.  Para tirar um modelo de uso, clique em **Inativar**; para remover um modelo nunca aplicado, clique em **Excluir**.

8\.  Use o relógio da linha para ver o histórico do modelo.



![](https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/UaQxKA0diol-fDk7RCgaD_upload.png)

Figura 83 — Modelos de plano de riscos com riscos-modelo e tratamentos sugeridos.

### Observações

·        O modelo precisa de pelo menos um risco-modelo; o prazo em dias não pode ser negativo; o código não se repete.

·        A posição sugerida só vale numa matriz que tenha essa posição, porque o modelo não sabe em que matriz será aplicado.

·        Editar um modelo já aplicado muda só as próximas aplicações. Item já aplicado pode ser alterado, mas não removido.

·        Modelo já aplicado não pode ser excluído: a janela oferece **Inativar o modelo**.

·        Quem gerencia riscos abre a tela só para consulta (botão **Ver**).

## 8.26 Aplicar um modelo de plano de riscos

ID BSC-RIS-26

### Para que serve

Aplicar um modelo cria de uma vez, por cópia, os riscos e tratamentos sugeridos, vinculados a um objetivo, eixo, programa ou ação estratégica.

**Quem usa:** Gestor de Desempenho (escritório de estratégia).

### Passo a passo

1\.  Em Governança e riscos › Registro de riscos, clique em **Aplicar modelo**.

2\.  Escolha o **Modelo** (só os ativos) e desmarque os riscos-modelo que não se aplicam.

3\.  Em **O que os riscos ameaçam**, escolha o **Tipo** e busque o **Item** (por exemplo, a ação RN-03 Duplicação da Rodovia Norte — trecho 3).

4\.  Escolha **Área**, **Responsável pelos riscos e pelos tratamentos**, **Matriz de risco** (vazia = padrão) e **Data-base**.

5\.  Se algum risco-modelo não tiver natureza ativa, escolha a **Natureza dos riscos-modelo sem natureza**.

6\.  Clique em **Aplicar modelo** e use os links da lista para abrir cada risco criado.

7\.  Na ficha de cada risco, confira **Criado a partir do modelo** e confirme a avaliação inerente na célula pré-selecionada ou escolha outra.



![](https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/wCvbajyjT6zctC8oF9aNU_upload.png)

Figura 84 — Aplicação de um modelo de plano de riscos.

### Observações

·        Os riscos nascem em **Rascunho**, já vinculados; cada tratamento vence na data-base mais os seus dias (data-base 01/03 e 30 dias: prazo 31/03).

·        A aplicação é tudo ou nada: se o item não existir mais ou faltar natureza, nada é criado e a janela diz por quê.

·        Ação estratégica concluída ou cancelada não recebe riscos novos.

·        A célula sugerida só pré-seleciona (contorno tracejado): a avaliação é de quem confirma.

## 8.27 Seguir um risco, discutir e receber avisos

ID BSC-RIS-27

### Para que serve

Seguir um risco faz chegar avisos das mudanças dele e dos seus tratamentos. A discussão reúne comentários de quem lê o risco.

**Quem usa:** Gestor de Desempenho (escritório de estratégia); Diretoria de Estratégia (patrocinador/aprovador); Responsável por ação/área.

### Passo a passo

1\.  Na ficha do risco, clique em **Seguir** (no alto, ao lado da situação); o número ao lado mostra quantas pessoas seguem.

2\.  No fim da aba **Visão geral**, escreva um comentário na **Discussão** do risco.

3\.  Ajuste os avisos em **Mensageria › Alertas e mensagens**, nos quadros **Risco corporativo** e **Tratamento de risco**.



![](https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/2iXH8dedTA8liHH0h8J0I_upload.png)

Figura 85 — Avisos de risco e tratamento no sino de notificações.

### Observações

·        Quem segue é avisado de mudanças no cadastro, vínculos, resposta, situação, avaliação nova, ocorrência registrada e de tratamentos cadastrados, alterados, cancelados ou concluídos. Não há botão de seguir no tratamento.

·        Quem comenta passa a seguir o risco; o responsável e os seguidores são avisados, nunca quem comentou. A discussão não é compartilhada com áreas.

·        Padrão (sino e e-mail): risco novo → responsável; comentário e mudança → responsável e seguidores; tratamento novo → quem responde por ele; tratamento atrasado → quem responde por ele e seguidores, uma vez por dia (verificação diária das 6h30); mudança no tratamento → seguidores.

·        Risco sigiloso: aviso só pelo sino, e só para quem pode vê-lo.

## 8.28 Perfis de acesso à gestão de riscos

ID BSC-RIS-28

### Para que serve

Cada perfil tem um papel definido no método, no registro, nos tratamentos, nas ocorrências e nos modelos de plano.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia); Responsável por ação/área; Leitor/Auditor; Administrador do sistema.

### Passo a passo

1\.  Identifique o perfil da pessoa na tabela de responsabilidades abaixo.

2\.  Se faltar acesso a alguma tela, peça ao **Administrador do sistema** a permissão de riscos correspondente.

3\.  Para ver riscos sigilosos, solicite a autorização específica de riscos sigilosos.



![](https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/cw8t6S2unYgjqi6HInvph_upload.png)

Figura 86 — Perfis de acesso do Bússola/BSC.

### Observações

·        Diretoria de Estratégia: mantém naturezas, matrizes e modelos; consulta registro, mapa (inclusive sigilosos), tratamentos e ocorrências; não lança execução nem aplica modelos.

·        Gestor de Desempenho: consulta o método; registra, vincula, avalia, responde, ativa e encerra riscos; vê e marca sigilosos; cadastra, edita e cancela tratamentos, lança execução; registra, edita e retira ocorrências e cria tratamento a partir delas; aplica modelos.

·        Responsável por ação/área (perfil operacional): consulta o registro sem riscos sigilosos; lança execução nos tratamentos que vê; registra e retira ocorrências e as liga a tratamentos existentes; não vê a tela de modelos.·        &#x20;

·        Qualquer pessoa nomeada responsável por um tratamento lança a execução dele pela Mesa de trabalho, mesmo sem permissão de riscos; em risco sigiloso, vê só o código.

[title] 14. Painéis e construtor
[path] Aplicações/GRCS/

*Como montar consultas sem escrever código e colocá-las num painel.*

O construtor tem quatro camadas, e a ordem importa.

***

### <font color="#15803D">O construtor, passo a passo</font>

A tela (menu Análise ▸ **Construtor**) tem quatro abas: **1. Consultas**, **2. Widgets**, **Itens lógicos** e **Atalho: perguntar**. Montar exige painel\:montar.

1.     **Consulta**: aba **1. Consultas** → **Nova consulta** → **Sobre o quê?** (a fonte) → **Quais registros?** (condições com E/OU, ou um item lógico salvo) → **O que quero ver?** (contar registros, somar, média, mínimo, máximo ou listar; agrupar é opcional) → **Confira o resultado** → **Dê um nome e guarde** (**Código**, **Nome**) → **Salvar consulta**.

2.     **Widget**: aba **2. Widgets** → **Novo widget** → os seis passos descritos em *4. Widget*, abaixo → **Criar widget**.

3.     **Levar ao painel**: em **Painéis**, **colocar widget** ou **do banco de widgets**.

4.     **Item lógico**: aba **Itens lógicos** → **Novo item lógico** → código, nome, fonte, descrição e as condições → **Salvar item**.

5.     **Atalho: perguntar** faz consulta, widget e bloco de uma vez, e guarda só se você quiser.

Nas listas, o lápis (ou **Editar**) abre para mudar, o ícone de cópia abre um duplicado para ajustar sem tocar no original — e o botão de gravar da cópia diz **Criar cópia**, porque grava um novo e deixa o original como está. A lixeira pergunta antes de apagar: a pergunta diz o que se perde, o que fica e o que a tela sabe que depende do item (a consulta desenhada por widgets, o item lógico citado por consultas), com o foco no **Cancelar** e o **Esc** para desistir; só **Excluir** apaga. Widget que está em algum painel não se apaga direto: a recusa aparece na própria pergunta, que passa a oferecer **Retirar dos painéis e apagar**. A fonte de um item lógico não se troca depois de criado, nem na cópia.

***

### <font color="#15803D">1. Condição</font>

Compara um campo com um valor. O operador vem do tipo do campo: quem escolhe uma data recebe *antes de*, *entre*, *nos últimos N dias*; quem escolhe uma severidade recebe *é*, *está entre*. Comparação impossível não chega a ser oferecida.

***

### <font color="#15803D">2. Item lógico</font>

Um conjunto de condições ligadas por E/OU, **salvo com nome próprio**. É a peça que justifica o resto.

:::hint{type="info"}
Defina *"achado crítico em aberto"* uma vez e cite-o em quantos widgets precisar. No dia em que a organização mudar o que entende por crítico, você muda num lugar e todos os painéis acompanham. Copiado dentro de cada widget, o mesmo conceito envelheceria diferente em cada um, e dois widgets do mesmo painel passariam a dar respostas diferentes para a mesma pergunta.
:::

Um item lógico pode citar outro, o que permite compor conceitos.

***

### <font color="#15803D">3. Consulta</font>

Fonte, filtro e agregação — contar, somar, média, mínimo, máximo ou listar, com agrupamento opcional. **A cadeia de E/OU faz parte da consulta**: dentro dela você monta o grupo — *todas as condições precisam ser verdadeiras*, *ao menos uma precisa ser verdadeira*, *inverter o grupo* —, acrescenta subgrupos e cita itens lógicos salvos. A prévia mostra o resultado enquanto você monta.

A consulta **se salva com nome** e entra na lista, para ser escolhida depois em quantos widgets precisar. O item lógico e o filtro próprio da consulta valem **juntos**: assim você reaproveita o conceito e ainda restringe a um escopo sem duplicar a definição.

***

### <font color="#15803D">4. Widget</font>

A consulta com uma forma de aparecer, e regras de cor. Em **Construtor ▸ 2. Widgets ▸ Novo widget**, em seis passos e na mesma ordem da consulta:

1.     **Qual consulta?** — o dado já montado e salvo. O widget só o veste.

2.     **Como mostrar?** — só os visuais que servem ao formato daquela consulta. Oferecer pizza para um valor único seria oferecer o que não desenha.

3.     **Como se lê, e o que obedece** — prefixo, sufixo, casas decimais, faixa do medidor, e se o widget dispensa o filtro do painel.

4.     **Cores por faixa de valor** — avaliadas de cima para baixo; a primeira que casar decide.

5.     **Confira como ficou** — desenhado com o dado de verdade, e não com exemplo.

6.     **Dê um nome e guarde** — código e nome por último, quando já se sabe o que o widget mostra.

:::hint{type="info"}
A mesma consulta pode virar um número num painel e uma rosca em outro. O botão de duplicar no cartão do widget é o "salvar como" de quem quer o mesmo dado noutro visual.
:::

**Por que o nome vem no fim.** Pedir código e nome antes de existir o que nomear obriga a pessoa a descrever algo que ela ainda não viu — e o que sai daí é W-1, W-2, W-3. Depois da prévia, o nome se escreve sozinho.

| **A consulta devolve** | **Visuais**                                                    |
| ---------------------- | -------------------------------------------------------------- |
| valor único            | número, semáforo, medidor, medidor em arco, barra de progresso |
| série agrupada         | barras, horizontais, empilhadas, linha, área, pizza, rosca     |
| listagem               | tabela, grade                                                  |



As **regras de cor** são avaliadas de cima para baixo e a primeira que casa decide. A ordem é sua: *"acima de 10 é crítico, acima de 5 é alerta, o resto está bem"* só funciona nessa sequência.

A cor é semântica — bem, atenção, alerta, crítico — e não uma cor escolhida à mão, para que o painel continue legível nos três temas.

***

### <font color="#15803D">Painéis, passo a passo</font>

Os painéis aparecem como fichas no alto da tela; *rascunho* marca o que não foi publicado. Quem só lê vê apenas os publicados. Criar, montar e publicar exige painel\:publicar.

1.     **Novo painel** → código, **Nome do painel**, **Descrição** e ao menos um dos **Blocos** fixos (Indicadores, Por severidade, Por estado, Por escopo, Por norma, Auditorias) → **Criar**.

2.     Em **Widgets do painel**: **colocar widget** → *escolha um widget…* → **Colocar no fim**; ou **do banco de widgets**, que abre o banco com este painel como destino. Arraste para posicionar; **arrumar** reflui tudo num modelo; o seletor ao lado define de quanto em quanto tempo o painel se refaz (*só ao abrir* até *15 min*).

3.     **Publicar** (ou **Despublicar**). Publicado, a caixa **no menu** e a pasta decidem onde ele aparece no grupo Gestão; *+ nova pasta…* cria a pasta na hora.

4.     **Filtro do painel**: **30 dias**, **90 dias**, **12 meses**, ou **De** e **Até**, o **Alvo** e, quando algum quadro separa por auditoria, a **Auditoria** → **aplicar**; **salvar como padrão** fixa o filtro com que o painel abre; **limpar** desfaz. O quadro cuja fonte não separa por auditoria aparece em *não respondem — ver por quê*: ele soma todas.

5.     A lixeira da barra remove o painel, depois de perguntar: a pergunta avisa se ele está publicado, quantos widgets mostra e de quantos murais é parada. Os widgets continuam no banco. A lixeira de um quadro dentro do painel também pergunta antes de tirá-lo — o widget fica no banco, mas a posição e o tamanho não voltam.

Clicar num número ou numa barra abre a gaveta com os registros por trás dele.

***

### <font color="#15803D">O painel</font>

Grade de doze colunas. Cada painel declara de quanto em quanto tempo se refaz: painel pendurado na parede precisa se atualizar sozinho, painel de análise não.

**A disposição é livre.** Ao arrastar um widget, a grade mostra os destinos que existem:

| **Solte sobre**                | **Acontece**                                         |
| ------------------------------ | ---------------------------------------------------- |
| outro widget                   | os dois **trocam de lugar**                          |
| um espaço vazio da linha       | o widget **ocupa aquele espaço**                     |
| a faixa tracejada entre linhas | abre uma **linha nova** e empurra o resto para baixo |



Só aparecem como destino os espaços que **cabem** o widget arrastado: oferecer um vão de três colunas a um widget de seis seria prometer uma posição que a grade recusa.

Largura e altura saem do menu do próprio widget, em frações que se entendem sem contar colunas. O botão **arrumar** reflui todos num modelo pronto, mantendo a ordem em que já estão.

Não existe campo de SQL em lugar nenhum, de propósito: quem monta painel não é quem administra o banco.

***

### <font color="#15803D">Painéis de fábrica</font>

Toda instalação nasce com dois painéis publicados, entregues uma vez a cada tenant — o que o tenant editar ou apagar depois não volta:

| **Painel**                                          | ~~**O**~~**&#x20;que mostra**                                                                                                                                                                                                                    |
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Painel de gestão** (GESTAO)                       | os blocos fixos de partida: indicadores, achados por severidade e por estado, por escopo e por norma. Só nasce no tenant que ainda não tem painel nenhum                                                                                         |
| **Consolidação por área e equipe** (P-CONSOLIDACAO) | uma auditoria de vários alvos lida por área (o alvo de cima) e por equipe: pontuação por área e por equipe, perguntas divergentes, a distribuição das respostas consolidadas e o mapa pergunta × equipe. Escolha a auditoria no filtro do painel |



Os quadros do P-CONSOLIDACAO são widgets comuns, sobre duas fontes do construtor — **Respostas por área e equipe** (uma linha por resposta, com a equipe, a área, a resposta e a pontuação que conta) e **Perguntas consolidadas** (uma linha por pergunta de cada auditoria, com a resposta consolidada pela regra da auditoria e a divergência). A regra e a divergência estão em Auditoria e ondas, em *A resposta consolidada e a visão por pergunta*.

***

### <font color="#15803D">Da gaveta para o registro</font>

O número de um painel abre a lista que o produziu — mesma fonte, mesmo filtro, mesmo item lógico. Recalcular por outro caminho abriria a chance de divergirem, e um detalhe que não fecha com o total é pior do que nenhum detalhe.

A lista não é só leitura. **Cada linha abre o registro onde ele é tratado**: achado vai para Não conformidades, risco para Riscos, resposta para a auditoria dela. Antes disso, quem reconhecia o achado no painel tinha de sair, trocar de tela e procurar o mesmo código a mão — e a chance de tratar a coisa errada nasce aí.

A gaveta tem busca em todas as colunas e filtro por valor onde a coluna tem poucos valores distintos. Acima de doze valores o filtro deixa de ajudar e vira outra lista para procurar dentro, então só o campo de busca aparece. **Exportar respeita o recorte da tela**: quem filtrou e clicou em exportar quer aquilo, e receber a lista inteira faria o arquivo discordar do que acabou de ver.

***

### <font color="#15803D">Duas fontes que respondem perguntas que as outras não respondem</font>

**Alvos avaliados** existe porque ausência de linha é informação. Contando achados, quem não tem achado nenhum não aparece — o painel mostrava onze não conformidades e não tinha como dizer que havia quinze processos, nem quais quatro estavam limpos. Nenhuma consulta sobre achados consegue expressar isso. Essa fonte traz também o campo **Conformidade**, que responde em uma palavra o que o score não responde.

**Código do alvo** existe em toda fonte que tem escopo, porque o nome serve para ler e o código serve para recortar. Montar um painel de uma área inteira listando o nome de cada alvo dela produz um painel que passa a mentir no dia em que alguém cria mais um processo e esquece de editá-lo. Com o código, "começa com PROC-N3-" continua verdadeiro sozinho.

***

### <font color="#15803D">Score vazio não é falta de avaliação</font>

Instrumento de registro — o ROPA, por exemplo — não pontua. O ciclo aparecia com score vazio e parecia não avaliado, quando o que acontecera era o oposto: ele **foi** avaliado, por regra e não por nota. É para isso que serve o campo Conformidade: ele mostra a conclusão, e não a nota.

***

## <font color="#15803D">Perguntar: o caminho curto</font>

Ver um número custava quatro objetos — item lógico, consulta, widget e bloco no painel — e quatro nomes antes de qualquer resposta aparecer. Nesta instalação isso virou vinte e oito consultas e quarenta widgets para seis painéis: quase quatro objetos por número exibido.

A aba **Atalho: perguntar**, no Construtor, inverte a ordem:

1.     **Sobre o quê?** Escolhe-se o objeto — não conformidades, riscos, respostas, auditorias, ações, alvos.

2.     **Quais?** Monta-se a condição com os campos daquele objeto. Sem condição nenhuma, são todos.

3.     **O que mostrar?** Quantidade ou lista, separada por um campo ou não.

4.     **A resposta agora.** O resultado aparece enquanto se monta, pelo mesmo caminho de execução que o bloco usará depois — prévia que calcula por outro caminho é prévia que pode mentir.

5.     **Guardar esta pergunta?** Opcional — dá para só olhar e sair. Para guardar: **Nome**, **Como mostrar** e **Em qual painel** (ou *nenhum, por enquanto*) → **Guardar**.

Os quatro objetos continuam existindo e continuam valendo para quem reaproveita: um item lógico com nome próprio impede que "achado crítico em aberto" exista copiado em cada widget, e mudar o que a organização entende por crítico num lugar só. O que mudou é deixarem de ser **obrigatórios** para quem só quer uma resposta.

Quando se guarda, os três nascem numa transação. Três chamadas seguidas falhando no meio deixariam consulta sem widget e widget sem bloco: lixo que ninguém sabe que criou e que aparece meses depois numa lista.

***

## <font color="#15803D">Os valores vêm do próprio dado</font>

Dos cinquenta e um campos do catálogo, onze declaram lista fechada. Nos outros quarenta havia uma caixa em branco, e quem montava o painel precisava adivinhar se escrevia ALTA, Alta ou alta. Errar não dava erro: dava um widget zerado, que parece defeito de cálculo e não filtro que não casou com nada.

Agora o campo oferece o que existe. Lista fechada responde a norma — inclusive valores que ainda não ocorreram. Campo livre lê do próprio dado, com busca, e pela mesma política de tenant que todas as outras leituras: o que aparece é do tenant e nunca do vizinho. Continua sendo campo de texto, porque valor que ainda não ocorreu precisa poder ser escrito — senão o filtro só enxerga o passado.

Data e número ficam de fora: a lista teria o tamanho da tabela, e o campo já é do tipo certo.

***

## <font color="#15803D">Comparar com outro campo</font>

A condição compara com um valor **ou com outro campo do mesmo objeto**. Havia uma família inteira de perguntas que não cabia sem isso — "prazo anterior a hoje", "risco residual maior que o inerente", "encerrada antes de identificada" — e a única saída era digitar um número fixo que envelhece no dia seguinte.

Três travas, cada uma contra um jeito de a pergunta sair errada em silêncio. O campo comparado sai da mesma lista do catálogo. O operador precisa ser de ordem ou igualdade, porque "contém" entre dois campos produziria SQL válido respondendo a uma pergunta que ninguém fez. E os tipos precisam casar: data com número o banco recusa, mas texto com número ele converte sozinho e devolve uma ordem alfabética com cara de resultado.

***

## <font color="#15803D">Perguntar sobre o objeto vizinho</font>

O seletor de campo mostra os campos deste objeto e, abaixo, os do objeto relacionado: *Auditorias — da auditoria*, *Alvos avaliados — do alvo*. Escolher "Situação" ali dentro pergunta sobre a auditoria do achado, e não sobre o achado.

Até aqui o vínculo entre entidades era simulado por subconsulta fixa que devolvia só o **nome** do relacionado: dava para exibir e não dava para filtrar. "Achados cujas auditorias estão em execução" era impossível de perguntar, e é das perguntas mais naturais que existem.

**As relações são declaradas em código, não montadas na tela.** O catálogo é a lista branca que o compilador consulta para saber que tabela e coluna podem entrar no SQL; um construtor de junções livres devolveria essa decisão a quem monta o painel, e nome de tabela não é dado — é código. Quem decide que caminhos existem continua sendo o código; a tela só oferece os que já estão escritos.

A condição vira EXISTS, e não junção no FROM. A diferença aparece no primeiro relacionamento de um para muitos: junção multiplica a linha de origem por quantas casarem do outro lado, e "achados de auditoria em execução" passaria a contar o mesmo achado várias vezes — um número errado que parece plausível, que é o pior tipo.

Uma limitação conhecida: **comparar campo com campo ainda não atravessa relação**. Dentro do EXISTS as duas fontes estão em escopo, e "outro campo" ficaria ambíguo — da origem ou do destino? Recusar com uma frase clara é melhor do que escolher por conta própria.

***

## <font color="#15803D">Banco de widgets: a pergunta já feita</font>

O construtor pergunta tudo — fonte, campo, agregação, agrupamento, visual — e é a ferramenta certa para quem faz BI. Para quem só quer o painel da própria área, o **Banco de widgets** (menu Análise, ou o botão *do banco de widgets* dentro de um painel) traz a pergunta pronta: escolhe-se o widget, aplicam-se os filtros e coloca-se no painel.

São cerca de mil e novecentos modelos sobre todo o GRC — não conformidades, riscos, KRIs, eventos de perda, planos e ações, aceites de risco, auditorias, respostas, atribuições, evidências, controles, frameworks, requisitos, perguntas, integrações, eventos, achados de log da IA, pareceres da IA, continuidade (BIA), oportunidades, usuários e grupos. Navega-se por **tema**, por **tipo** (indicador, distribuição, ranking, tendência, cruzamento, comparação, relatório), por **fonte** ou pela busca. *Essenciais de GRC* mostra os sessenta e poucos modelos curados — "NCs vencidas", "Riscos acima do apetite", "Matriz de calor do risco residual", "Perda efetiva por mês", "Controles sem pergunta" — que trazem recorte próprio e regra de cor.

**O banco é derivado do catálogo, e não uma segunda lista para manter.** Toda lista fechada vira uma distribuição; todo par de listas, um mapa de calor; toda data, uma série mensal e trimestral; todo número, média, soma e máximo, por categoria e por mês; toda fonte, um relatório em grade. Campo novo no catálogo aparece no banco na subida seguinte.

Passo a passo:

1.     **Achar o modelo**: a busca *Procurar entre N widgets…*, **Todas as fontes**, **Essenciais de GRC**, as fichas de tema (**Todos** e um por tema) e as de tipo. **Mostrar mais** traz os próximos. Clique no cartão para abrir.

2.     **Nome no painel**: o título com que o widget vai aparecer.

3.     **Visual**: só os que servem para a forma da pergunta.

4.     **Filtros**: *+ adicionar filtro…* oferece os campos da fonte — lista fechada e texto viram caixas de marcar com os valores que o dado tem; data vira "últimos N dias"; número, **mín.** e **máx.** Os filtros **se somam** ao recorte do modelo — "em aberto" continua valendo — e o filtro de período e alvo do painel continua valendo por cima.

5.     **Prévia**: dados reais, com os filtros escolhidos, pelo mesmo caminho que o quadro usará.

6.     **Destino**, no rodapé: *No painel: …* → **Colocar no painel** (entra numa faixa nova no fim do painel; **Concluir** fecha), ou *Só criar o widget* → **Criar widget**, que vai para o Construtor.

No menu, o banco aparece para quem tem painel\:montar; dentro do painel, o botão **do banco de widgets** aparece para quem monta o painel.

O que nasce é uma consulta comum: aparece no construtor e se edita como qualquer outra. Ela **não fica presa ao modelo** — um widget que mudasse sozinho quando o banco mudasse trocaria a pergunta do painel de uma diretoria numa atualização da plataforma sem ninguém ter pedido.

Quem não tem a permissão do módulo de uma fonte (por exemplo, admin\:usuarios para Usuários) não vê os modelos dela: o banco, a prévia, a lista de valores e a gaveta de registros exigem a mesma permissão que a tela daquele módulo. O quadro já publicado num painel continua visível a quem lê o painel — quem publicou decidiu mostrar aquele agregado.

***

## <font color="#15803D">Agrupar por período</font>

O agrupamento aceita data **por período**: dia, semana, mês, trimestre ou ano. A série sai ordenada pelo tempo (e não pelo valor), e clicar num ponto abre a gaveta com os registros daquele período exato — do primeiro dia até antes do primeiro dia do período seguinte.

***

## <font color="#15803D">Grade de relatório</font>

Os visuais **Grade** e **Tabela** viram uma grade de relatório dentro do painel e na gaveta: cada coluna se ordena e se filtra de forma independente (texto contém; lista com contagem; número por faixa; data por intervalo), a grade se agrupa por uma ou mais colunas com subtotais (soma, média, mínimo, máximo, contagem) e total geral, escolhem-se as colunas visíveis, e o que se vê — com os filtros, a ordem e os grupos — **exporta para Excel (XLSX) e CSV** e **imprime como relatório**, com título, filtros aplicados e data de emissão no cabeçalho.

***

## <font color="#15803D">A gaveta obedece ao filtro do painel</font>

Clicar num quadro de um painel filtrado abre os registros **com o mesmo filtro**. Antes a gaveta pedia pelo widget solto: a barra dizia 4 e a lista trazia os 31 do ano, e um detalhe que não fecha com o número que se clicou é pior do que nenhum detalhe.

[title] 15. Murais e televisão
[path] Aplicações/GRCS/

*Painéis no menu, pastas, e a sequência que gira numa TV da área.*

Painel publicado é produto de trabalho consultado todo dia. Por isso ele aparece no grupo **Gestão**, no topo do menu, e não apenas dentro da tela de Painéis.

Ao publicar, na barra de ações do painel, duas escolhas:

•     **no menu** — desmarque para manter o painel publicado e acessível, mas fora da navegação. Serve ao painel que só faz sentido dentro de um mural;

•     **pasta** — onde ele mora no menu. A opção *+ nova pasta…* cria e move numa ação só.

As pastas são suas. A plataforma não impõe taxonomia porque cada organização separa por área, por diretoria ou por assunto, e nenhuma dessas escolhas cabe no produto. Um nível de subpasta é o limite: dois já é árvore, e árvore de menu esconde atrás de dois cliques o que deveria estar a um.

Apagar uma pasta não apaga painel — eles voltam para a raiz.

***

## <font color="#15803D">Murais de TV</font>

Uma televisão mostra uma **sequência**, e não um painel só. O mural é essa sequência.

***

### <font color="#15803D">Montando — Análise ▸ Gestão à Vista</font>

A tela se chama **Gestão à Vista**. Montar exige painel\:publicar; quem só lê vê os murais e pode exibi-los.

1.     **Novo mural** → **Código**, **Nome** e **Tempo padrão** (segundos por parada, de 5 a 3600) → **Criar mural**.

2.     Selecione o mural na lista à esquerda. Em **Acrescentar painel…**, escolha um painel publicado → **Acrescentar**.

3.     Em cada parada, o campo de segundos muda o tempo dela — grava ao sair do campo, e *(padrão)* indica que ela herda o do mural. As setas mudam a ordem; o **×** tira a parada.

4.     **Exibir** põe o mural em tela cheia (veja abaixo).

5.     **Excluir** pergunta antes de apagar o mural — a pergunta diz quantas paradas ele tem, com o foco no **Cancelar** e o **Esc** para desistir; só **Excluir** apaga. Os painéis continuam existindo. Tirar uma parada (o **×**) não pergunta: o painel volta com **Acrescentar**.

Cada parada pode ter o próprio tempo porque um painel de quatro números se lê em dez segundos, e uma matriz de risco não.

Só **painel publicado** entra. Um mural que exibisse rascunho colocaria número inacabado na parede da área — e a parede é justamente o lugar onde menos se confere a procedência do que se lê.

***

### <font color="#15803D">Exibindo</font>

O botão **Exibir** ocupa a tela inteira e gira sozinho. O contador regressivo aparece de propósito: sem ele, uma televisão parada e uma televisão entre trocas são indistinguíveis, e a primeira reação a uma tela parada é achar que o dado está velho. **Sair (Esc)**, ou a tecla Esc, volta; o botão de pausa (**Pausar** / **Retomar**) serve para quem quer olhar uma parada com calma. Mural sem parada não exibe — o botão fica desabilitado.

***

### <font color="#15803D">O perfil de monitoramento</font>

É o perfil que se usa na televisão: **o token não expira** e o acesso é **só a painel**. Ele **não** monta murais — montar exige permissão de publicar.

A razão é direta: token que nunca expira somado a permissão de escrita é o pior par possível. Qualquer pessoa que chegue perto da televisão passaria a decidir o que a área inteira vê, e a sessão nunca morre para encerrar esse acesso.

[title] 16. Resultado por hierarquia
[path] Aplicações/GRCS/

*Onde estão os maiores riscos, descendo da organização até o contrato.*

A lista de auditorias responde "como foi cada auditoria". Numa organização com dezesseis áreas, trinta equipes e cento e dez contratos, ninguém faz essa pergunta — faz-se **onde estão os maiores riscos**, e a resposta é uma árvore, porque o risco de uma área é o dela mais o de tudo o que está pendurado nela.

***

### <font color="#15803D">Resultado por hierarquia, passo a passo</font>

A tela (menu Análise) só lê: não cria nem altera alvo — isso é em **Alvos e dimensões**.

1.     No alto, os totais — **Alvos na hierarquia**, **Com auditoria própria**, **Achados abertos**, **Riscos abertos** — e **Onde o resultado é pior**, com os três piores.

2.     *Procurar alvo por nome ou código* abre a árvore até o que foi achado.

3.     **Só quem tem resultado** / **Mostrando tudo** alterna o filtro; **Expandir tudo** / **Recolher tudo** abre ou fecha todos os níveis. A seta à esquerda da linha abre só os filhos dela.

4.     Clique na linha para abrir o resumo do alvo, com **Score próprio**, **Score acumulado**, **Achados abertos** e **Riscos abertos**, e as abas **Auditorias**, **Achados** e **Riscos**.

5.     Clique num achado ou num risco do resumo para abrir o registro na tela dele, pronto para tratar.

A árvore segue o campo **Dentro de** de cada alvo. Alvo sem pai aparece na raiz.

***

### <font color="#15803D">As duas medidas, e por que são duas</font>

| **Medida**          | **O que conta**                    |
| ------------------- | ---------------------------------- |
| **Score próprio**   | só o que foi auditado naquele nó   |
| **Score acumulado** | a subárvore inteira, inclusive ele |



A diferença é o ponto. Uma área sem auditoria própria e com quarenta achados abaixo dela **não está bem — está sem olhar**, e só a distância entre os dois números mostra isso.

Um nó pode ter score próprio vazio e acumulado alto: é o caso de quem só consolida. E pode ter score próprio vazio por outro motivo — o ciclo dele não pontua, como o ROPA, cujo valor está nos achados e não numa nota.

***

### <font color="#15803D">Drilldown</font>

Clicar numa linha abre o resumo do alvo: as auditorias do próprio nó, com score e cobertura, e os achados e riscos da **subárvore inteira**, cada um dizendo de que alvo veio.

Ir até a tela de não conformidades filtrada por alvo daria o mesmo resultado em três cliques, duas telas e a perda do lugar na árvore — que numa hierarquia de cento e sessenta e sete nós é o que mais custa.

A seta à esquerda expande os filhos; o resto da linha abre o resumo.

***

### <font color="#15803D">O filtro que vale a pena entender</font>

Por padrão a tela mostra só quem tem resultado. Numa hierarquia real, a maioria dos nós são contratos e fornecedores ainda não auditados, e eles empurram para baixo justamente o que interessa. O botão mostra tudo quando a pergunta for outra: **o que ainda não foi olhado**.

***

### <font color="#15803D">Cobertura não é conformidade</font>

Score alto com cobertura baixa é a combinação que engana. A tela marca a cobertura abaixo de 70% no resumo do ciclo, porque uma nota calculada sobre um terço das perguntas não é uma nota — é uma amostra pequena com cara de nota.

[title] 20. Área de automação
[path] Aplicações/GRCS/

*O que a plataforma faz sozinha, num lugar só — conectores, regras e destinos de webhook.*

A **Automação** é o grupo do menu com tudo o que roda sem ninguém clicar: o que **entra** (conectores que trazem eventos e logs), o que **decide** (regras que transformam resposta e log em achado, e avisos por regra) e o que **sai** (destinos que recebem um aviso por HTTP quando algo acontece). Antes isso estava espalhado entre Auditoria e Administração, e quem queria saber "o que a plataforma faz sozinha" precisava conhecer três menus.

| **Tela**                   | **O que faz**                                                                                                                | **Para ver**      |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ----------------- |
| **Painel da automação**    | coletores no ar, inspeções, execuções e custo da semana, achados abertos, o que está falhando e a cadeia de selos            | `automacao:ler`   |
| **Achados**                | a caixa única: achados de inspeção e de log, para confirmar, descartar ou promover                                           | `automacao:ler`   |
| **Eventos e conectores**   | SIEM, XDR, EDR, nuvem, identidade e ITSM; regras de log e achados de log ficam na integração aberta (*Eventos e conectores*) | `integracao:ler`  |
| **Automação de respostas** | a resposta de auditoria que vira NC ou risco (*Automação de respostas*)                                                      | `auditoria:ler`   |
| **Avisos por regra**       | quem recebe o quê, e quando (*Avisos e e-mail*)                                                                              | `admin:usuarios`  |
| **Fontes de conteúdo**     | de onde o coletor lê documentos, código e mensagens                                                                          | `integracao:ler`  |
| **Inspeções**              | uma fonte lida pelas lentes e julgada contra as normas                                                                       | `automacao:ler`   |
| **Lentes**                 | o que procurar, escrito pelo cliente                                                                                         | `automacao:ler`   |
| **Destinos**               | para onde sai o aviso: webhook, Teams, CITSmart ou e-mail                                                                    | `automacao:ler`   |
| **Sandbox**                | ensaiar regra e modelo sem gravar de verdade (*Modelos de linguagem, parecer prévio e sandbox*)                              | `llm:administrar` |



As telas mudaram de grupo, e não de endereço: avisos antigos, links e a ajuda continuam abrindo a mesma tela. Embaixo do grupo há atalhos para **Modelo de linguagem**, **Contas de serviço** e **Regras de atendimento**, que ficam onde estão porque servem à plataforma inteira (ou aos casos).

As permissões da área são `automacao:ler` (ver destinos e entregas), `automacao:escrever` (cadastrar, testar e reenviar) e `automacao:triar` (decidir o que um achado da automação vira). De fábrica, o administrador e o gestor têm as três, e o analista tem ler e triar. Perfis próprios que já viam ou mantinham as integrações receberam o equivalente na atualização.

***

### <font color="#15803D">O coletor: quem faz o trabalho pesado</font>

Ler milhares de documentos, abrir compactados, fazer OCR e chamar o modelo de linguagem é peso, e esse peso não roda dentro da plataforma: roda no **grc-coletor**, um processo à parte, em quantas instâncias forem precisas — numa máquina ao lado ou dentro da rede do cliente. O coletor fala com a plataforma só pela API, com uma **conta de serviço** do perfil **Coletor de inspeção** (Administração ▸ Contas de serviço): pede trabalho, recebe a inspeção com a credencial da fonte, entrega os achados e encerra.

Há dois jeitos de ligar o coletor:

•     **Coletor da instalação** (GRC\_COLETOR\_CHAVE\_INSTALACAO, a mesma no app e no coletor, ao menos 32 caracteres). Ele atende **todos os tenants ativos** — inclusive os criados depois que subiu, conferidos a cada cinco minutos —, sem uma chave por cliente e sem reinício. Em cada tenant ele trabalha com uma conta de serviço própria, **Coletor da instalação**, que a plataforma cria na primeira vez e que o administrador do tenant vê em Contas de serviço: o RLS, a trilha e o teto de ingestão seguem por tenant. **Revogar** essa conta tira o coletor da instalação daquele tenant. A chave da instalação só abre a API do coletor: no resto da plataforma ela não vale nada.

•     **Coletor do cliente** (GRC\_COLETOR\_CHAVES): a chave de uma conta de serviço do próprio tenant, para quem roda o coletor dentro da rede do cliente, perto das fontes que só ele alcança.

•     Cada inspeção vai a um coletor por vez, por 15 minutos renováveis. Coletor que cai deixa a vez vencer e outro continua de onde os documentos ficaram.

•     Antes de cada lote ao modelo, o coletor pergunta se pode: com gente usando a IA pela tela, fora da janela de lote ou com o modelo recusando chamadas, ele espera. A tela continua rápida.

•     A entrega tem teto por tenant (600 documentos por minuto). Vinte coletores juntos não deixam a plataforma lenta. O teto é contado no banco e vale para a instalação inteira: com várias instâncias da aplicação atrás do balanceador, o tenant continua com 600 no total, e não 600 em cada uma. Quem passa do teto recebe 429 com o tempo de espera, e o coletor tenta de novo depois.

•     O topo de **Inspeções** diz quantos coletores estão no ar e se têm OCR.

•     A API do coletor é só para conta de serviço. Nem o administrador, que tem todas as permissões, a chama com o login dele: a resposta leva a credencial decifrada da fonte.

•     Fora da própria máquina e da rede do compose, o coletor só fala com a plataforma por **https** (`GRC_COLETOR_API`). Quem instala numa rede já cifrada por outro meio libera o http com `GRC_COLETOR_PERMITIR_HTTP=true`.

•     Sem memória, o coletor sai e o contêiner sobe de novo: ficar de pé com o trabalhador parado deixaria os tenants sem inspeção.

***

### <font color="#15803D">Fontes de conteúdo</font>

Em **Automação ▸ Fontes de conteúdo** (mudar pede `integracao:escrever`), **Nova fonte** e escolha o tipo: **Pasta**, **MinIO ou S3**, **Envio manual**, **Links**, **SharePoint**, **OneDrive**, **SharePoint local**, **Google Drive**, **CITSmart Athena (GED)**, **GitHub**, **GitLab**, **E-mail (IMAP)**, **E-mail (Microsoft 365)** ou **Teams (canais)**. O formulário pede os campos do tipo; senha, token e chave vão cifrados e não voltam à tela (em branco na edição mantém o que está guardado).

•     **Testar** é um pedido: a plataforma não alcança a fonte, quem alcança é o coletor. Ele atende no pulso seguinte e devolve uma amostra do que enxergou (até cinco documentos), ou o erro.

•     **Pasta**: cada tenant tem a própria pasta no coletor, `/dados/<código do tenant>` (`GRC_COLETOR_PASTAS` muda a raiz), e o **caminho** da fonte é relativo a ela: politicas, ou . para a pasta inteira. Caminho absoluto, .. e link simbólico para fora são recusados — o mesmo coletor atende vários tenants, e nenhum lê a pasta do outro.

•     **Links** lê só a web pública: endereço da rede interna é recusado, no cadastro e a cada link seguido.

•     Todo endereço de fonte (S3, Athena, SharePoint local, GitHub, GitLab, IMAP) é conferido: rede do cliente sim; a própria máquina, os metadados da nuvem e a rede da plataforma, não. Redirecionamento para outro servidor é seguido sem a credencial da fonte.

•     **Envio manual**: em **Arquivos**, envie o contrato ou a política avulsa (até 50 MB); entra na próxima execução das inspeções da fonte.

•     **E-mail e Teams** leem mensagens de pessoas. A fonte só roda depois que quem administra a plataforma (`admin:usuarios`) registrar, em **Base legal**, a hipótese da LGPD, a política que sustenta o monitoramento e quem a aprovou no jurídico e no encarregado de dados. Revogar a base legal pausa as inspeções da fonte.

***

### <font color="#15803D">Lentes</font>

Uma lente é o que procurar, escrito como se diria a um auditor. Em **Automação ▸ Lentes**, **Nova lente**: um gatilho por título ##, com o que conta e o que não conta como achado (o formulário traz um modelo). Mudar as instruções cria a **versão** seguinte — o achado diz por qual versão foi reconhecido, e os documentos já vistos voltam ao modelo na execução seguinte.

**Lentes de fábrica.** Todo tenant nasce com cinco lentes do produto, marcadas **de fábrica**: segredos e credenciais expostos, dados pessoais fora do lugar (LGPD), procedimento que contraria a política, incidente sem tratamento e obrigação de fornecedor descumprida. Elas são só leitura: **Ligar** e **Desligar** valem para o seu tenant, e **Duplicar** cria uma cópia sua, que você ajusta à vontade — a de fábrica continua recebendo as melhorias do produto. Os exemplos que você põe numa lente de fábrica são do seu tenant. O modelo de tenant, no console, diz quais nascem ligadas.

Em **Versões e exemplos**, os **exemplos** são os casos já revisados por gente: "não é achado" (falso positivo) e "é achado". Os ativos entram no prompt da lente, para o mesmo erro não voltar. O falso positivo marcado na triagem vira exemplo sozinho.

O documento chega ao modelo como **dado**, depois das instruções, e um detector procura nele texto escrito para dar ordens ao modelo ("ignore as instruções anteriores…"): documento assim vira achado **Injeção de prompt suspeita**, mesmo que o modelo não dispare nada.

***

### <font color="#15803D">Inspeções</font>

Em **Automação ▸ Inspeções**, **Nova inspeção** junta uma **fonte**, as **lentes** e, se quiser, as **normas contra as quais julgar** (frameworks e temas do catálogo). Escolha a **frequência**, um **teto de tokens por execução** (estourado, a execução para e retoma depois de onde parou), **só estas extensões** e se o coletor deve fazer OCR. Salvar deixa em rascunho; **Ativar** põe na fila.

•     **Executar agora** antecipa a vez; **Reanalisar tudo** esquece o que já foi visto.

•     Documento com o mesmo conteúdo e a mesma chave de análise (versão das lentes, exemplos, normas e modelo) não vai ao modelo de novo.

•     Compactados (zip, 7z, tar, gz, bz2, xz) são abertos até três níveis, com teto de 5 000 arquivos e 512 MB descompactados — a bomba de compressão para no teto e o documento fica como falha.

Clique no nome da inspeção para ver:

•     **Achados**: o que as lentes reconheceram, com o trecho, a confiança e a versão da lente;

•     **Normas**: cada requisito e quantos documentos o **atendem**, atendem **em parte**, **não atendem** ou não tratam do assunto (**sem evidência**), com o trecho que sustenta cada veredito. Requisito sem trecho próximo no documento é "sem evidência" sem gastar chamada ao modelo; "não atende" com confiança vira também achado, ligado ao requisito;

•     **Documentos**: o que foi visto, ignorado, sem texto ou com falha, e o motivo;

•     **Execuções**: cada passada do coletor, com documentos, achados e tokens.

***

### <font color="#15803D">Painel da automação</font>

**Automação ▸ Painel da automação** mostra, numa olhada, o que roda sozinho: quantos coletores responderam nos últimos três minutos, inspeções ativas (e as atrasadas há mais de uma hora), execuções, documentos, achados e tokens dos últimos sete dias, o custo por inspeção, os achados abertos por severidade e destinos com entrega desistida. Em **Pede atenção** aparecem a fonte que falhou no teste e a inspeção ativa que não executa há uma semana. A tela se atualiza a cada minuto.

***

### <font color="#15803D">Achados: a caixa única</font>

Em **Automação ▸ Achados** estão, num lugar só, os achados das **inspeções** e os das **regras de log** — filtre por origem, situação, severidade ou texto. Clique no achado para ver a explicação, o trecho, o documento, o requisito, a lente e o selo. Decidir pede `automacao:triar`:

•     **Confirmar** — é achado, e alguém vai cuidar dele;

•     **Falso positivo** — pede o motivo, e o motivo vira **exemplo na lente** que reconheceu o achado: o mesmo caso não volta na próxima execução;

•     **Descartar** — não interessa, sem ensinar nada à lente;

•     **Reabrir** — volta atrás numa decisão;

•     **Virar NC** (pede também `nc:tratar`), **Virar risco** (`risco:escrever`) ou **Abrir caso** (`caso:abrir`). A NC nasce com origem **Inspeção**, o requisito violado, o trecho como evidência, o documento como link e a referência ao achado — promover de novo é recusado. O risco entra com o impacto da severidade; o caso, como incidente pelo canal API, com impacto e urgência da severidade.

**Comentários** ficam no achado, com resposta. **PDF** gera o relatório do achado, com a evidência, o selo, os comentários e quem gerou. Achado de log segue as decisões da tela de eventos (virar NC, risco ou descartar).

***

### <font color="#15803D">O selo: prova de que o achado não foi mexido</font>

Cada achado de inspeção, ao ser gravado, entra na **cadeia do dia** do tenant: o selo dele é o hash do conteúdo (título, explicação, evidências, documento, lente, requisito) **mais o selo do anterior**. O banco recusa mudar o conteúdo de um achado selado — a triagem (estado, motivo, quem decidiu, o que virou) continua livre. Se alguém mudasse o conteúdo por baixo, a cadeia quebraria daquele ponto em diante. Pelo mesmo motivo, achado selado não se apaga: a inspeção que já tem achados é **pausada**, e não removida, e a lente que reconheceu algum é **desativada** — a tela diz isso ao tentar.

No **Painel**, **Cadeia de selos** lista os dias; **Conferir** refaz os hashes, elo a elo, até o fim da cadeia, e separa os dois problemas: **lacuna** (falta um elo — achado apagado) e **adulteração** (o conteúdo do achado mudou depois de selado). Mesmo depois de uma lacuna, o conteúdo de cada elo seguinte continua conferido. De hora em hora a plataforma **ancora** a ponta de cada cadeia (**Ancorar agora** antecipa). A âncora leva o carimbo de tempo da **FreeTSA** (RFC 3161), a autoridade gratuita que o produto usa por padrão — só o hash sai da instalação — e o arquivo .tst pode ser baixado e conferido com qualquer ferramenta de carimbo de tempo (openssl ts -verify, com o certificado da FreeTSA). GRC\_SELO\_TSA\_URL troca a autoridade; vazio desliga, para a instalação sem internet, e aí a cadeia vale pelo encadeamento.

***

### <font color="#15803D">Destinos: avisar outro sistema quando algo acontece</font>

Um destino recebe um aviso a cada evento que ele assina. O **tipo** diz como:

| **Tipo**            | **O que chega**                                                                                                                                                                                            |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Webhook**         | um POST com o JSON do evento, assinado — para o SIEM, o sistema de chamados ou um script seu                                                                                                               |
| **Microsoft Teams** | um cartão no canal: **Adaptive Card**, para o fluxo "Quando uma solicitação de webhook é recebida" do Power Automate, ou **MessageCard**, para o conector de entrada antigo                                |
| **CITSmart**        | um chamado aberto no CITSmart (/webmvc/servicerequestincident/create), com o título e o texto do evento; informe os ids de solicitante, atividade e contrato e o cabeçalho Authorization, guardado cifrado |
| **E-mail**          | a notificação às pessoas escolhidas — no sino e por e-mail, conforme a preferência de cada uma; não sai pedido para fora da plataforma                                                                     |



Em **Automação ▸ Destinos** (cadastrar pede `automacao:escrever`):

1.     Clique em **Novo destino** e escolha o **tipo** (não muda depois).

2.     Preencha **Nome** e **Endereço** (http ou https, com o nome completo do servidor ou o IP; o e-mail não tem endereço, e sim as pessoas que recebem) e marque em **Eventos** o que ele recebe:

◦      **nc.criada** — uma não conformidade nasceu, de qualquer origem (regra, auditoria, automação, log, inspeção ou à mão);

◦      **nc.estado\_alterado** — a NC mudou de estado (triagem, plano, conclusão, encerramento);

◦      **risco.criado** — um risco foi registrado;

◦      **achado\_de\_log.criado** — as regras de log reconheceram um desvio;

◦      **achado\_de\_inspecao.criado** — uma inspeção reconheceu um achado (lente, segredo, injeção ou requisito não atendido).

3.     Clique em **Criar destino**. A tela mostra o **segredo de assinatura** uma vez só: copie e entregue a quem cuida do sistema que recebe. Perdeu? **Trocar segredo** gera outro (o antigo deixa de valer na hora).

4.     Clique em **Testar**: a plataforma manda um evento teste agora e mostra o que o destino respondeu e em quanto tempo.

Na lista, cada destino mostra a última entrega com sucesso, a última falha e quantas entregas estão na fila. **Pausar** segura o envio (o que acontecer nesse meio-tempo não é enfileirado); **Entregas** abre o histórico, e **Reenviar** põe de volta na fila uma entrega que falhou — depois de consertar o outro lado.

O endereço não pode ser a própria máquina da plataforma, o enlace local onde mora o serviço de metadados da nuvem (169.254.x.x) nem um nome sem domínio (postgres, objetos), que é como os serviços da instalação se chamam entre si. Rede privada é aceita: o sistema de chamados do cliente costuma morar nela. A rede da própria plataforma, não: com a aplicação em contêiner, a sub-rede dela é recusada sozinha; fora de contêiner, informe as redes a recusar em GRC\_AUTOMACAO\_REDES\_BLOQUEADAS (CIDR, separados por vírgula). O endereço é conferido no cadastro e de novo a cada envio.

O **Testar** de um destino CITSmart abre um chamado de verdade no CITSmart do cliente, e a tela pede confirmação antes.

***

### <font color="#15803D">O que chega do outro lado</font>

```none
POST /seu/endereco
Content-Type: application/json
X-GRC-Evento: nc.criada
X-GRC-Entrega: 4f0c…           (o id desta entrega; igual nas tentativas)
X-GRC-Tentativa: 1
X-GRC-Timestamp: 1759314656    (segundos desde 1970)
X-GRC-Assinatura: sha256=9331ca93…
 
{"evento": "nc.criada", "entregaId": "4f0c…", "ocorridoEm": "2026-10-01T10:30:56Z",
 "registro": {"tipo": "NAO_CONFORMIDADE", "id": "…", "numero": "NC-2026-0237", "titulo": "…",
              "severidade": "ALTA", "estado": "IDENTIFICADO", "origem": "INSPECAO",
              "requisitoId": "…", "evidenciaUrl": "https://…", "referenciaExterna": "…"}}

```

A assinatura é o HMAC-SHA256 do segredo sobre `<X-GRC-Timestamp>.<corpo>`. Confira as duas coisas antes de confiar no aviso: a assinatura e o instante (recuse o que tiver mais de cinco minutos). Em Python:

```python
import hmac, hashlib, time
esperada = "sha256=" + hmac.new(segredo.encode(), f"{ts}.{corpo}".encode(), hashlib.sha256).hexdigest()
ok = hmac.compare_digest(esperada, cabecalho_assinatura) and abs(time.time() - int(ts)) < 300

```

Responda **2xx em até 10 segundos** e processe depois. Sem resposta, com 5xx, 408 ou 429, a entrega volta para a fila e tenta de novo em 30 s, 1 min, 2 min… dobrando até 6 h entre tentativas, e desiste depois de 10 (cerca de oito horas e meia). Outro 4xx (endereço errado, autenticação recusada) desiste na hora, porque repetir não muda nada. Use X-GRC-Entrega para descartar repetidos: numa queda de rede, a mesma entrega pode chegar duas vezes.

A entrega nasce na mesma gravação do que aconteceu: se a NC for gravada, o aviso não se perde mesmo que o destino esteja fora do ar; se a gravação for desfeita, o aviso não sai. Entregas enviadas ficam 30 dias no histórico, e as que desistiram, 90.

***

### <font color="#15803D">Não conformidade por API, com o que ela viola</font>

Quem cria NC pela API (uma conta de serviço com nc\:tratar) pode dizer, além de título, descrição e severidade, o que o achado viola e de onde ele veio:

| **Campo**                   | **O que é**                                                                    |
| --------------------------- | ------------------------------------------------------------------------------ |
| `origem`                    | MANUAL (padrão) ou INSPECAO. As demais origens nascem só dentro da plataforma. |
| `requisitoId`, `controleId` | o requisito e o controle do catálogo (de fábrica ou do tenant)                 |
| `evidenciaUrl`              | onde a evidência mora — o documento, o commit, a página; só http e https       |
| `evidenciaTrecho`           | o trecho que sustenta o achado, já sem dados pessoais                          |
| `referenciaExterna`         | o id do achado no sistema que o mandou                                         |



Com referenciaExterna, o pedido é **idempotente**: mandar o mesmo achado de novo devolve a NC que já existe (200), em vez de criar outra (201). É o que deixa um coletor reenviar um lote que caiu no meio sem duplicar nada. A NC mostra requisito, controle e evidência no detalhe, e o webhook nc.criada leva os mesmos campos.

***

### <font color="#15803D">Dados pessoais antes do modelo de linguagem</font>

Cada modelo em **Administração ▸ Modelo de linguagem** tem **Mascarar dados pessoais**. Ligado, o texto vai ao modelo com CPF, CNPJ, e-mail, telefone e cartão trocados por marcadores (\[CPF], \[E-MAIL]…) — o modelo não vê o número, mas vê que havia um, e é o que uma regra como "dado pessoal em log" precisa julgar. Número sem pontuação só vira marcador quando o dígito verificador confere (o cartão, quando passa no Luhn): onze dígitos quaisquer podem ser um pedido ou um protocolo.

Vem ligado para modelo fora da rede da instalação e desligado para o que mora nela (localhost, rede privada ou o ollama do compose), que é o caminho recomendado para quem não pode mandar texto para fora.

***

### <font color="#15803D">Análise de aderência gravada</font>

A análise de aderência do acervo (*Acervo de documentos*) continua sem guardar nada por padrão. Marque **Gravar esta análise** antes de **Analisar** para guardar **só o resultado** — requisito a requisito, com os trechos citados —, nunca o documento. As gravadas aparecem em **Análises gravadas**, abaixo da tela: clique para reabrir (e baixar o relatório de novo) ou apague. Cada pessoa vê as suas; quem configura o acervo vê todas.

O conector de logs **GRCS Inspect** saiu do catálogo de **Eventos e conectores**: não aceita integração nova, e a integração que já existe continua coletando até ser removida.

O destino **CITSmart** não reenvia sozinho uma entrega que pode ter aberto o chamado (resposta que não veio, erro do servidor): o CITSmart não recusa chamado repetido, e reenviar abriria o segundo. A entrega fica como desistida, com o aviso de conferir no CITSmart; **Reenviar** continua à mão. Conexão recusada, 429 e 503 voltam à fila normalmente.

[title] 21. Eventos e conectores
[path] Aplicações/GRCS/

*Receber e buscar eventos das plataformas de segurança, e o que isso muda na auditoria.*

Todo o resto da plataforma pergunta e alguém responde. Aqui a plataforma **vai buscar** — ou **recebe** — o que a ferramenta de segurança está medindo de fato.

:::hint{type="info"}
Alguém responde "sim, temos MFA" e o sistema registra que alguém escreveu isso. O diretório mostra 71% de cobertura. A diferença entre o declarado e o medido vira achado sozinha, e é essa diferença que separa autoavaliação de auditoria.
:::

***

### <font color="#15803D">O caminho</font>

| **Passo**   | **O que acontece**                                                                |
| ----------- | --------------------------------------------------------------------------------- |
| A origem    | SIEM, XDR, EDR, diretório, varredura de vulnerabilidade, nuvem, ITSM ou API livre |
| A entrada   | a plataforma busca de tempos em tempos, ou a origem empurra num endereço próprio  |
| O evento    | normalizado na chegada, com o original guardado ao lado                           |
| O indicador | muitos eventos viram um número                                                    |
| A regra     | compara o declarado com o medido e levanta o achado                               |



O indicador é o passo que costuma ser esquecido. **Sem ele os eventos ficam guardados e não participam de apuração nenhuma** — a integração funciona, a tela mostra os eventos chegando, e nenhuma regra dispara.

***

### <font color="#15803D">Buscar ou receber</font>

A escolha é de quem configura, e não do produto.

**Buscar** é a plataforma indo atrás, com a credencial que você informa. Serve para quem não pode expor a origem, e é o caminho em que a falha aparece do lado de cá: a execução fica registrada com o erro que a origem devolveu.

**Receber** é a origem empurrando para um endereço próprio, autenticado por uma chave. Serve para quem já tem a origem sabendo empurrar, e evita guardar credencial de terceiro aqui dentro — o que é especialmente relevante em nuvem.

A chave aparece **uma única vez**, no momento da ativação. Chave que a tela mostra de novo é chave que vaza pelo print, pelo backup do banco e pela captura do suporte.

***

### <font color="#15803D">O conector é catálogo, não código</font>

Trinta conectores vêm prontos, agrupados por categoria, e um fornecedor novo entra por cadastro e não por atualização do produto. O que muda de um SIEM para outro não é o protocolo — os dois falam REST com JSON —, e sim a URL, a forma de autenticar e onde os campos moram dentro da resposta.

Quando o produto que você usa não está na lista, **API livre** e **Webhook livre** são o mesmo motor com os campos em branco: você informa o endereço, o cabeçalho de autorização e o caminho de cada campo.

:::hint{type="info"}
**Sobre os logotipos.** Cada conector traz um selo com a sigla sobre a cor da marca. A plataforma não embarca o logotipo oficial de terceiros: marca registrada não se redistribui dentro de um produto vendido, e uma aproximação desenhada por nós seria pior que nenhuma. O cadastro do conector aceita o endereço do arquivo oficial, e ele entra no lugar do selo.
:::

***

### <font color="#15803D">Conectar uma origem, passo a passo</font>

Em **Automação ▸ Eventos e conectores** (ver pede integracao\:ler):

1.     Clique em **Nova integração**. Em **Escolha a origem**, procure pelo nome do produto (Splunk, Falcon, Sentinel, Entra…) ou percorra as categorias, e clique no conector. Não achou? Use **API livre** ou **Webhook livre**.

2.     Em **Conectar …**, se o conector aceitar os dois modos, escolha em **Como os eventos chegam**: **A plataforma busca** ou **A origem empurra**.

3.     Preencha **Nome desta integração**, **A que alvo os eventos se referem** (em branco vale para a **Organização inteira**) e, na busca, **De quanto em quanto tempo buscar (minutos)** — mínimo 5.

4.     Preencha os campos do conector (endereço, credencial…). O que for secreto não volta a ser exibido. Clique em **Criar como rascunho**; enquanto faltar campo obrigatório, a tela diz qual.

5.     Na integração aberta, clique em **Testar contra a origem** (só no modo busca) e confira como os três primeiros eventos ficariam.

6.     Clique em **Ativar**. No modo recebimento, a tela mostra o **Endereço** e o **Cabeçalho** (X-Integracao-Chave) para configurar do lado da origem — a chave aparece só agora.

7.     Em **Indicadores**, clique em **+ indicador**, preencha **Código** (exatamente como a regra escreve dentro de MED(), ex.: mfa.cobertura), **Como se lê**, **Como muitos eventos viram um número**, o filtro de categoria (opcional) e **Janela (dias)**, e clique em **Criar indicador**.

Na lista, cada cartão tem **Abrir**, **Coletar agora** (no modo busca, depois de sair do rascunho: busca fora do intervalo) e **Pausar** (quando ativa). O quadro **O que está sendo medido agora** mostra os números que o motor de regras recebe na apuração. Dentro da integração ficam também **Últimos eventos** e **Execuções**, e **Excluir**.

***

### <font color="#15803D">Regras de log: de texto a achado</font>

Para log, que é texto, o indicador não basta. Na integração aberta, em **Regras de log**:

1.     Clique em **+ regra** e preencha **Nome da regra** e **O que procurar** — escrito como se diria a um analista; é o critério que o modelo de linguagem recebe junto com o log.

2.     Opcional: **Modelo de linguagem** (em branco usa o padrão), **Só estas severidades**, **Só estas categorias**, **Só logs que contenham** (filtro barato: o que não passa nem vai ao modelo) e **Confiança mínima**.

3.     Em **O que o achado faz**, escolha **Só achado**, **Não conformidade**, **Risco** ou **Não conformidade e risco**, e em **Plano de ação obrigatório?** mantenha **pela severidade** ou force sim ou não.

4.     Clique em **Experimentar nos últimos logs** para ver o que viraria achado, e só então em **Criar regra**.

A regra avalia o que chega depois dela; a triagem roda a cada 30 segundos, e **Triar agora** adianta. Em **Achados das regras**, o achado aberto espera decisão: **Virar não conformidade**, **Virar risco**, **Não conformidade e risco** ou **Descartar**. Cada regra pode ser pausada, editada ou excluída na própria linha.

***

### <font color="#15803D">Testar antes de ativar</font>

O teste **chama a origem de verdade** e mostra como os três primeiros eventos ficariam depois de normalizados. Ele não valida o formulário: a diferença entre "os campos estão preenchidos" e "a credencial funciona" é a diferença entre ativar uma integração e descobrir de madrugada que ela nunca funcionou.

Por isso a integração nasce em **rascunho**. Preencher, testar, ativar — nessa ordem.

***

### <font color="#15803D">Quando alguma coisa dá errado</font>

O estado **pausada** é decisão de quem opera; **erro** é acidente. Colapsar os dois em "inativa" faria a falha de madrugada ficar indistinguível de uma pausa deliberada.

Cada execução fica registrada com o que a origem respondeu, traduzido: "a credencial foi aceita mas não tem permissão para esta consulta" diz o que fazer; "403" não diz. Integração que falha em silêncio é pior do que integração que não existe — a ausência de evento parece ausência de problema, e o painel fica verde justamente porque parou de receber.

***

### <font color="#15803D">A janela do indicador</font>

Medição sem prazo mente dos dois lados. Um evento de dois anos atrás não descreve o controle de hoje; uma janela curta demais devolve nada sempre que a origem fica um dia em silêncio — e nada, numa regra de confronto, é indistinguível de conformidade.

Indicador sem evento na janela **não aparece** no mapa de medições, e isso é diferente de aparecer com zero. Zero é uma medição: diria que a cobertura de MFA é zero por cento.

***

### <font color="#15803D">Segurança</font>

As credenciais são cifradas com AES-GCM. A chave vem da variável de ambiente GRC\_INTEGRACAO\_CHAVE; sem ela, uma chave é gerada e guardada na configuração, o que funciona e é um degrau abaixo — quem tem o banco tem a chave. A tela avisa quando esse é o caso.

O endereço de recebimento é público por necessidade: quem chama é um SIEM às três da manhã, e exigir token de pessoa seria exigir que alguém estivesse acordado para renová-lo. Ele se autentica pela própria chave, que vai no cabeçalho e nunca na URL — URL aparece em log de proxy, em histórico e em relatório de erro.

Reentrega não duplica. Todo webhook reentrega, por retentativa e por tempo esgotado, e a plataforma reconhece o evento pelo identificador da origem. Sem isso a mesma ocorrência contaria duas vezes numa medição que continuaria plausível.

[title] 26. Modelos de linguagem, parecer prévio e sandbox
[path] Aplicações/GRCS/

*Como ligar um modelo, o que ele opina, o que ele nunca decide, e onde experimentar sem alterar a auditoria de ninguém.*

A plataforma sabe conversar com modelos de linguagem em dois lugares, e os dois seguem a mesma regra: **o modelo opina, a pessoa decide**. Não existe caminho em que uma resposta de modelo entre no registro sem alguém aceitar.

***

### <font color="#15803D">Cadastrar um modelo de linguagem</font>

Em **Administração ▸ Modelo de linguagem** cadastram-se quantos modelos forem necessários. O que a plataforma exige é que ele fale *chat completions* — o mesmo formato que a OpenAI publicou e que virou o denominador comum do mercado. Isso inclui os serviços pagos, e inclui um modelo local.

Para cadastrar um modelo:

1.     Clique em **Novo modelo**.

2.     Em **Finalidade**, escolha **Conversa (parecer, triagem, perguntas)**, **Embeddings (busca semântica)** ou **Reranqueamento (ordem da busca)**. Para embeddings, informe a **Dimensão do vetor** — ela não muda depois de indexar.

3.     Preencha **Nome**, **Fornecedor**, **Nome do modelo** (ex.: gpt-4o-mini) e **Endereço** — o caminho completo, que costuma terminar em /v1/chat/completions no caso de conversa.

4.     **Chave**: opcional; modelo local não pede credencial. **Tempo limite (segundos)** e **Chamadas simultâneas** (teto para não saturar uma GPU compartilhada).

5.     Marque **Usar como padrão para …** se ele deve responder quando ninguém escolher outro, e deixe **Ativo** marcado. Clique em **Salvar**.

6.     Na linha do modelo, clique em **Testar**: uma ida e volta curta que diz o que voltou.

**A chave nunca volta pela tela**: a linha diz **chave configurada** ou **sem chave**, e na edição o campo em branco mantém a atual. O selo **respondendo** / **sem resposta** é a saúde conferida pela plataforma. Para trocar o modelo de embeddings, cadastre o novo e use **Adotar para embeddings**: o acervo é reindexado em segundo plano e a busca troca ao terminar.

Criar, editar, remover e testar exige llm\:configurar (perfil Administrador); com só llm\:administrar, a tela abre em **Somente leitura**, e continuam disponíveis a **Fila de IA** (o que espera o servidor de IA), as **Análises de IA do acervo** (ligar, desligar e escolher o modelo de cada análise; em branco vale o padrão) e as **Fontes de referência por framework** (escolha o **Framework** e o **Documento** e clique em **Designar como fonte**).

Mais abaixo, na mesma tela, fica o formulário antigo de um modelo só (**Endereço do serviço**, **Modelo**, **Chave de acesso**, **Salvar** e **Testar**, com **Caminhos conhecidos** para preencher), usado pelo assistente para transformar frase em consulta de painel. Ele avisa quando o endereço é público e o texto das auditorias sai da organização.

*Um modelo local, para quem não quer mandar dado para fora*

Modelo de linguagem lendo resposta de auditoria é dado sensível saindo da organização. Para avaliação, demonstração ou ambiente fechado, um modelo pequeno rodando localmente resolve:

:::BlockQuote
docker run -d --name ollama -p 11434:11434 -v ollama-modelos\:/root/.ollama ollama/ollama
docker exec ollama ollama pull qwen2.5:3b-instruct-q6\_K
docker network connect grc\_default ollama     # para o contêiner do GRC alcançá-lo
:::

No cadastro, o endereço é http\://ollama:11434/v1/chat/completions e o modelo é o nome puxado. Um modelo de três bilhões de parâmetros quantizado cabe em qualquer máquina de trabalho e responde em segundos — e julga pior que um modelo grande. Isso não é defeito de configuração: é o teto do tamanho, e a plataforma foi construída para conviver com ele, porque o modelo nunca decide sozinho.

***

### <font color="#15803D">***A IA nativa da plataforma***</font>

Todo tenant já vem com a **IA nativa da plataforma**: um modelo de conversa e um de embeddings servidos pela própria instalação. Na lista, eles aparecem com o selo **nativa** e a frase **Endereço administrado pela plataforma**, sem endereço e sem chave. No topo da tela, um quadro diz se a IA nativa está **ligada**, quantas chamadas simultâneas este ambiente pode fazer nela e quantas estão em uso agora.

A IA nativa não se edita nem se apaga por aqui: quem a configura é a administração da plataforma, no console da instalação. Para usar a IA da sua organização:

1.     Clique em **Novo modelo** e cadastre o seu, na finalidade que quiser substituir (conversa ou embeddings).

2.     Salve com **Ativo** marcado. Ele passa a ser o padrão daquela finalidade, no lugar da nativa, sem mais nada a fazer.

3.     Para voltar à nativa, desative ou apague o seu modelo: a nativa volta a ser o padrão.

Trocar o modelo de **embeddings** reindexa o acervo: use **Adotar para embeddings**, e a busca troca ao terminar.

O limite de chamadas simultâneas e o desligamento valem só para a IA nativa: com a sua IA, o custo e o limite são seus. Se a administração da plataforma desligar a IA nativa deste ambiente, as análises que dependem dela respondem **A IA nativa deste tenant foi desativada pela administração da plataforma**, e o seu modelo, se houver, continua funcionando.

*Como a IA isola os dados de cada tenant*

A IA nativa é um servidor compartilhado pela instalação, e o isolamento é feito pela plataforma, a cada chamada:

•     **O modelo não guarda nada.** Cada chamada leva só o texto daquele tenant e acaba na resposta. O modelo não tem memória entre chamadas nem aprende com o que lê.

•     **O que fica guardado é separado por tenant.** Os trechos e vetores dos documentos ficam no banco com segurança por linha: uma consulta de um tenant não alcança os de outro, nem por defeito da aplicação. Os arquivos ficam no armazenamento de objetos sob o prefixo do tenant.

•     **A fila e o coletor sabem de quem é cada tarefa.** Cada tarefa de IA guarda o tenant de origem. O coletor de fontes externas trabalha com um token por tenant, e a entrega só grava no tenant daquele token.

•     **O consumo é medido por tenant**, sem conteúdo: chamadas, erros, tempo e tokens.

Para quem exige isolamento físico (um cliente regulado, por exemplo), a administração da plataforma pode dar ao tenant um **servidor nativo exclusivo**: o quadro do topo passa a dizer **servidor exclusivo deste ambiente**.

***

### <font color="#15803D">Parecer prévio</font>

Dentro de uma resposta de auditoria, o auditor pode pedir um parecer. O modelo lê o enunciado, o que foi declarado e a evidência anexada, e devolve três coisas: uma opinião, uma sugestão de julgamento e uma confiança.

**O parecer não é a resposta.** Ele fica ao lado dela, com o nome do modelo que o emitiu, e o auditor aceita ou recusa — e essa decisão fica registrada. Uma plataforma de auditoria em que a máquina julga sozinha não produz auditoria; produz uma opinião automatizada que ninguém assinou.

***

### <font color="#15803D">Correlacionar evento com o que já foi respondido</font>

Este é o recurso que mais muda o trabalho. A integração traz eventos — o SIEM, o EDR, o scanner, o DLP. O modelo lê um evento e procura, entre as respostas já aprovadas da auditoria em curso ou da última, aquela que o evento **contradiz**.

A regra do que fazer com o achado é do negócio, e não do modelo:

•     **Sem risco no controle** — cria o risco, porque o evento comprova que o cenário deixou de ser hipótese;

•     **Com risco já existente** — abre não conformidade e eleva o grau, porque reincidência não é novidade, é agravamento.

O risco criado assim nasce ligado ao alvo e aos controles da pergunta. Não é detalhe: é pelo controle que a próxima ocorrência encontra este risco em vez de criar um irmão dele, e é pelo alvo que ele aparece no painel da área em vez de existir só no registro de riscos.

Três coisas limitam o que a correlação alcança, e é melhor saber delas de antemão:

1.     **Só perguntas com resposta definida entram.** Texto corrido se relaciona com qualquer coisa — um evento de elevação de privilégio já foi parar no campo "observações e recomendações", que não afirma nada sobre controle nenhum e por isso não pode ser desmentido por evento algum.

2.     **As candidatas passam por pré-seleção.** Uma auditoria de quinze alvos tem quinze cópias de cada pergunta; entregar todas ao modelo produz prompt que ele lê em minutos e entende pior.

3.     **Sem modelo ativo, a correlação continua funcionando** por correspondência de termos, com confiança baixa e dizendo na cara que foi ela quem achou. É pior que um modelo e não é nada.

***

### <font color="#15803D">O sandbox: experimentar a correlação sem alterar nada</font>

:::hint{type="info"}
O Sandbox só existe em **tenant de demonstração** (marcado no console da instalação). Em produção o menu não aparece e as simulações são recusadas, para teste não se misturar com dado real.
:::

**Automação ▸ Sandbox** (permissão llm\:administrar) é onde isso tudo se experimenta. Há um catálogo de mensagens por assunto — senha, dado pessoal, cartão de crédito, acesso indevido, continuidade, vulnerabilidade, terceiros, monitoramento — e cada uma chega com o selo da origem que a produziria de verdade: Entra ID, CrowdStrike, Tenable, Datadog, Wazuh, CSV em pasta de rede.

Para experimentar:

1.     Deixe **Simular** marcado (é o que impede qualquer gravação além do registro da simulação).

2.     Em **Disparar mensagem de teste**, clique no assunto e depois na mensagem.

3.     Ajuste, se quiser, o **Texto da mensagem** — é o que o modelo lê.

4.     Leia o quadro **O que vai acontecer nesta simulação** e clique em **Disparar simulação**.

5.     O resultado aparece ali mesmo; o registro fica em **Simulações anteriores**, no fim da tela.

Em **Eventos recebidos**, cada evento que já chegou por uma integração tem o botão **Simular** (ou **Correlacionar**, fora da simulação), e o resultado aparece na própria linha. Sem nenhum modelo ativo os botões ficam apagados — cadastre um em **Modelo de linguagem** primeiro.

O interruptor **Simular** decide o desfecho:

•     **Marcado** — nada é gravado além do registro da simulação. Nenhum risco criado, nenhum achado aberto.

•     **Desmarcado** — vale de verdade: o botão vira **Disparar para valer**, o risco e a não conformidade entram no ciclo, e o grau do risco sobe. O resultado traz **Abrir o risco …** ou **Abrir o achado …** para ir até o registro criado.

O que foi criado de verdade pode ser desfeito: **Desfazer este disparo**, no resultado, ou **Desfazer todos os disparos**, em **Correlações aplicadas** — os dois pedem confirmação. O servidor recusa, com o motivo por extenso, quando o registro já seguiu vida própria (achado com plano, aceite de risco registrado, risco ligado a outro achado); aí o desfazer volta a ser trabalho manual. Tudo fica na trilha, com autor e instante.

As mensagens disparadas viram eventos de verdade e aparecem na lista de eventos recebidos. O que as distingue é a integração de origem, chamada **Simulação**, criada na primeira vez e apontando para o conector real. Sem essa separação, a demonstração de hoje vira o achado inexplicável de amanhã.

***

### <font color="#15803D">Quanto a IA demora, e o que fazer quando demora demais</font>

O tempo de uma resposta é quase todo do servidor do modelo, e não da plataforma. Medido nesta instalação de referência (modelo de 3B parâmetros **só em CPU**), o Pergunte à base leva de 2 a 8 minutos: ler o prompt custa segundos quando ele já foi lido antes, mas **gerar** a resposta sai a menos de um token por segundo quando a CPU está disputada. Com GPU, o mesmo pedido responde em poucos segundos.

O que a plataforma já faz para não piorar:

•     **Pouco texto no prompt.** Seis trechos de até 1.200 caracteres por padrão (grc.acervo.prompt.trechos e grc.acervo.prompt.caracteres-por-trecho); quem tem GPU sobe.

•     **Teto de saída e resposta em JSON.** Cada análise pede só o tamanho de resposta que usa, e em JSON — sem preâmbulo que ninguém lê.

•     **Quem está na tela passa na frente.** Enquanto alguém usa a IA pela tela, a fila (parecer, análise de registro, indexação) não começa tarefa nova; volta sozinha minutos depois.

•     **A mesma pergunta não roda duas vezes.** A resposta fica guardada por 30 minutos para a mesma pergunta sobre os mesmos trechos — e, como os trechos já passaram pela visibilidade de quem pergunta, ninguém recebe resposta apoiada em documento que não pode ler.

•     **Tempo esgotado não é erro da tarefa.** Uma tarefa da fila que estoura o tempo volta para a fila sem gastar tentativa.

O que resolve de verdade, em ordem de efeito:

1.     **Servidor com GPU** para o modelo de conversa.

2.     **Modelo menor para as funções interativas.** Em **Modelo de linguagem ▸ Análises de IA do acervo**, cada análise pode ter modelo próprio: um modelo pequeno no Pergunte à base e na pré-validação, e o maior no parecer e na análise de registro, que rodam na fila sem ninguém esperando.

3.     **Janela de lote** (grc.ia.janela-lote, por exemplo 20:00-07:00) para a indexação e as reindexações pesadas rodarem fora do expediente.

4.     Com Ollama local: OLLAMA\_NUM\_PARALLEL=1 (uma conversa por vez termina antes do que duas dividindo a CPU) e OLLAMA\_CONTEXT\_LENGTH de pelo menos 8.192 — o padrão de 4.096 corta o começo do prompt, onde está a instrução, em silêncio.

[title] 22. Automação de respostas
[path] Aplicações/GRCS/

*Declarar o que uma resposta faz nascer — não conformidade, risco ou os dois —, sem passar por desenvolvedor.*

Antes, o que uma resposta produzia estava decidido em dois lugares fora do alcance de quem audita: a opção de resposta traz o julgamento gravado no catálogo de fábrica, e o vínculo com risco era regra fixa em código — toda não conformidade procura risco para elevar e, se não acha, cria um.

Isso serve ao caso comum e não tem saída para os outros. Quem trata "Parcial" como aceitável num contrato de baixa criticidade não tinha como dizer isso. Quem quer risco aberto direto — sem achado, porque não há o que corrigir e há o que monitorar — também não.

***

### <font color="#15803D">Criar uma automação</font>

Em **Automação ▸ Automação de respostas** (criar, editar e apagar pedem a permissão de escrever no catálogo):

1.     Clique em **Nova automação**.

2.     Preencha **Código** e **Nome** (obrigatórios) e, em **Por que esta automação existe**, a razão — é o que explica o achado a quem o ler daqui a um ano.

3.     Em **Quando disparar**, recorte: **Tipo de resposta**, **Valor exato da resposta** ou **Ou pontuação até**, **Só em alvo do tipo**, **Só no tema** e **Só na pergunta** (esta só lista depois de escolher o tema).

4.     Em **O que abrir**, marque **Não conformidade** (e a severidade), **Risco** (e a categoria, a probabilidade e o impacto), ou os dois.

5.     Clique em **Criar automação**.

Na lista, o botão de ligar ativa ou desativa, o lápis edita e a lixeira apaga — depois de perguntar, com o foco no **Cancelar** e o **Esc** para desistir; só **Excluir** apaga. A pergunta diz quantos disparos a automação registrou, que saem junto com ela. O que a automação já abriu fica: achado e risco são registro de auditoria. A faixa de pontuação não se aplica a tipo de resposta sem peso, e o campo fica desligado.

***

### <font color="#15803D">O gatilho</font>

É **conjuntivo**, e tudo o que ficar em branco significa "qualquer":

| **Campo**        | **O que ele recorta**                                |
| ---------------- | ---------------------------------------------------- |
| Tipo de resposta | só perguntas daquele tipo                            |
| Valor exato      | a resposta escolhida, palavra por palavra            |
| Pontuação até    | qualquer opção que pontue até aquele valor           |
| Tipo de alvo     | só em contrato, só em ativo de TI, só em fornecedor… |
| Tema             | só nas perguntas daquele assunto                     |
| Pergunta         | só naquela pergunta                                  |

**Valor ou faixa de pontuação é obrigatório.** Sem nenhuma condição a automação dispararia em toda resposta do ciclo, e a primeira apuração encheria o registro de achados idênticos.

A faixa de pontuação existe porque o valor exato não alcança o caso mais comum. Numa escala de implantação o que interessa é "pontuou 50 ou menos", e enumerar as opções que satisfazem isso obriga a reescrever a regra toda vez que a escala ganhar um degrau. Por isso o seletor marca quais tipos têm peso: só neles a faixa faz sentido.

:::hint{type="info"}
**O recorte por pergunta evita a armadilha mais comum.** Uma automação de "tipo sim/não, valor Sim, tema X" alcança *todas* as perguntas de sim/não daquele tema. Quem configura pensando numa pergunta recebe um registro por pergunta, e só descobre depois de apurar.
:::

***

### <font color="#15803D">A ação</font>

Abrir não conformidade, risco, ou os dois.

•     **Com achado**, o risco nasce ligado a ele, e encerrar o achado depois baixa o residual.

•     **Sem achado**, o risco nasce solto — de propósito. É a resposta que não tem o que corrigir e tem o que monitorar.

A categoria vem do cadastro de categorias, e a automação oferece primeiro as que combinam com o tema da pergunta. Sem escala declarada, a severidade manda: a mesma tabela que a ligação entre achado e risco já usa.

***

### <font color="#15803D">O que ela não faz</font>

Não substitui o comportamento de fábrica. A opção marcada como gap continua gerando achado como sempre; a automação **acrescenta**. Desligar o que serve à maioria para atender à minoria que quer outro seria a troca errada.

***

### <font color="#15803D">Disparos</font>

Cada disparo fica registrado com a resposta, o achado e o risco que produziu. É o que faz reapurar não duplicar, e é o que responde a pergunta que o risco sozinho não responde: por que ele existe.

***

### <font color="#15803D">E as regras de atendimento?</font>

A automação de respostas age sobre **resposta de auditoria**. As regras que agem sobre **casos** — notificar, atribuir, escalar quando o prazo aperta — ficam em **Tratamento ▸ Regras de atendimento**, ao lado da fila que elas mexem, e estão descritas em *Portal, caso e ciclo de vida*. A Automação tem um atalho para elas.

[title] 23. Avisos e e-mail
[path] Aplicações/GRCS/

*Quem envia, quem escreve, quem é avisado e para onde a resposta volta.*

As perguntas que este capítulo responde foram feitas juntas, e por isso são respondidas juntas: *como é enviado um e-mail? quem envia? quem escreve? qual o tema? quando respondem, onde entra a resposta? quem é sinalizado? onde ficam esses dados?*

Separadas em telas diferentes, cada uma teria resposta e o fluxo continuaria invisível — que era exatamente a queixa. Tudo está em **Administração ▸ E-mail e avisos**, em duas abas: **A conta** e **O fluxo do aviso**. Os avisos que nascem de uma condição sobre qualquer objeto ficam ao lado, em **Automação ▸ Avisos por regra**.

***

### <font color="#15803D">O aviso é um registro; o e-mail é só uma forma de entrega</font>

Essa distinção tem três consequências práticas:

•     a pessoa vê o aviso dentro da plataforma mesmo quando o e-mail não chega;

•     a falha de entrega fica **registrada**, em vez de sumir num log;

•     uma instalação sem servidor de e-mail continua avisando — só que dentro da tela.

O contrário disso é o que quase todo produto faz: envia e esquece. Quando alguém pergunta "o aviso saiu?", a resposta honesta passa a ser "não sei".

***

### <font color="#15803D">O sino</font>

O **sino** do cabeçalho abre a caixa de avisos, com o número dos que você ainda não leu. Cada aviso diz o assunto, o começo do texto e quando chegou; clicar marca como lido e leva até o que o aviso fala. **Marcar todas como lidas** zera a contagem.

Quando o aviso é sobre **um registro**, o clique abre o próprio registro, e não só a tela da lista:

| **O aviso fala de…**                                                                                  | **O clique abre**                                                                       |
| ----------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| Um documento (aprovação pendente, versão publicada, revisão vencida, leitura obrigatória, comentário) | O **detalhe do documento**, onde se aprova, se registra a ciência ou se lê o comentário |
| Uma não conformidade (regra de aviso sobre achado)                                                    | O **modal da NC**                                                                       |
| Um risco ou uma oportunidade (regra de aviso)                                                         | O **modal** do risco ou da oportunidade                                                 |
| Um caso (novo, atribuído, aprovação pendente no chamado)                                              | O **modal do caso**                                                                     |
| Um prazo de auditoria                                                                                 | A **auditoria**, já selecionada                                                         |



O resto — despacho e devolução (que levam à **Minha fila**), o convite de avaliação do atendimento (que leva ao portal) e o aviso de configuração — continua abrindo a tela. Avisos antigos, gravados antes desta versão, também abrem o documento ou o caso: a plataforma os reconhece pela tela a que levavam. A permissão continua a mesma de abrir o registro pela tela dele: o sino não abre o que a pessoa não poderia ver.

Os avisos vêm de toda a plataforma, cada um com o seu ícone: onda despachada, devolução, prazo vencendo, achado, publicação, caso do portal, documento (aprovação, publicação, leitura obrigatória), convite e configuração. Um tipo novo que a caixa ainda não conheça aparece com o sino — ele nunca impede a caixa de abrir.

O aviso de **configuração** é o guiado: quando o tenant está sem modelo de linguagem padrão (de conversa ou de embeddings), quem pode cadastrar modelo (llm\:configurar) recebe, no primeiro acesso, **Cadastre o modelo de linguagem do tenant** — o clique abre Administração › Modelo de linguagem (*Modelos de linguagem, parecer prévio e sandbox*). Ele sai uma vez por pessoa.

***

### <font color="#15803D">A conta — quem envia</font>

Aba **A conta**. Servidor, porta, usuário, credencial e remetente, gravados pela tela e não por variável de ambiente: quem opera a plataforma não tem acesso ao arquivo do servidor, e recurso que depende de desenvolvedor para ser ligado é recurso desligado.

Para ligar a entrega por e-mail:

1.     Em **O servidor**, preencha **Servidor SMTP** (ex.: smtp.exemplo.com.br), **Porta** (587 por padrão), **Remetente** (ex.: grc\@exemplo.com.br), **Usuário** e **Senha**. Sem usuário e senha, a plataforma envia sem autenticar.

2.     Clique em **Gravar**. O indicador **Entrega por e-mail** passa a **Ligada**.

3.     Em **A prova**, informe um endereço em **Enviar um teste para** e clique em **Enviar teste**. A resposta diz se o servidor aceitou ou por que recusou.

A conexão usa STARTTLS. Campo com cadeado (**travado pelo ambiente**) foi fixado por variável de ambiente e não se muda pela tela.

A senha **nunca volta para a tela**. O campo chega vazio e, em branco, mantém a que já existe — salvar o formulário para trocar a porta não pode apagar a credencial.

O **envio de teste** existe porque, sem ele, ligar o e-mail é um ato de fé: grava‑se a configuração, espera‑se o ciclo de dois minutos, e se nada chegar não há como saber se o servidor recusou, se a credencial está errada ou se simplesmente ainda não havia aviso na fila.

Os indicadores do topo da aba mostram **Aguardando envio**, **Desistiu** e **Entregues em 24h**, e o **Último erro de entrega** quando houver. Avisos que desistiram depois de cinco tentativas não saem sozinhos de novo: corrija a causa e clique em **Devolver à fila**.

***

### <font color="#15803D">O fluxo — quem escreve, quem recebe, para onde a resposta volta</font>

Aba **O fluxo do aviso**. Cada linha é um **ponto do produto de onde sai um aviso**, e cada uma declara quatro coisas:

| **O que a linha declara**      | **Por que isso importa**                                                                                                                |
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| **de que objeto parte**        | sem isso, o identificador gravado no aviso não diz de que tabela é, e "todos os e-mails desta auditoria" vira uma pergunta sem consulta |
| **quem recebe**                | estava espalhado entre uma consulta de grupo e um campo de atribuição, e quem opera a plataforma não lê nem uma coisa nem outra         |
| **que texto sai**              | o seu, ou o de fábrica enquanto você não escreve o seu — e a linha diz qual dos dois está valendo                                       |
| **para onde a resposta volta** | o endereço de retorno; vazio, usa o remetente da conta                                                                                  |

***

### <font color="#15803D">Escrever o texto</font>

O texto **não está no código**. Mudar uma palavra do aviso não exige publicar versão nova — o que, na prática, significava que ninguém mudava, e o aviso continuava dizendo o que o desenvolvedor achou e não o que a organização quer dizer.

1.     Na aba **O fluxo do aviso**, ache o cartão do aviso — o selo diz **texto de fábrica** ou **texto escrito aqui**.

2.     Clique em **Escrever o texto deste aviso**.

3.     Edite **Assunto** e **Corpo**; clique numa variável de **Disponíveis** para acrescentá-la ao corpo.

4.     Opcional: **A resposta volta para** — vazio usa o remetente da conta.

5.     Clique em **Ver como fica** para conferir com valores de exemplo, e depois em **Gravar o texto**.

As **variáveis ficam à vista enquanto você escreve**, e não numa ajuda a um clique de distância: quem escreve precisa saber o que tem à mão *antes* de escrever, e não depois de o aviso sair errado para trezentas pessoas. Clicar numa variável a acrescenta ao corpo.

Uma variável que aquele evento **não oferece** é recusada na gravação, com a lista das que existem. Não é rigor gratuito: ela sairia entre chaves no e-mail, e quem recebe leria \{prazo} onde deveria haver uma data.

**Ver como fica** monta o texto com valores de exemplo antes de ele sair para alguém.

**Voltar ao texto de fábrica** apaga o seu — e não o substitui por uma cópia dele. É por isso que sempre funciona.

***

### <font color="#15803D">A etiqueta de protocolo, e o limite honesto</font>

Cada aviso cita uma etiqueta no formato GRC-AUDITORIA-A1B2C3D4. É ela que liga uma resposta de e-mail de volta ao objeto que a originou.

**A plataforma não lê caixa postal.** Isto está dito na própria tela, e não escondido aqui: a resposta volta para a caixa de quem responde pela auditoria, e a etiqueta é o que permite ligá‑la ao objeto — por leitura automática no dia em que houver uma caixa real para apontar, e por quem recebe até lá. Um leitor de IMAP que nunca foi apontado para uma caixa de verdade é código que ninguém sabe se funciona.

***

### <font color="#15803D">Por que o aviso não chegou</font>

Os quatro números do topo da aba **O fluxo do aviso** respondem, nesta ordem:

•     **Saíram** — entregues, e como quem.

•     **Na fila** — saem no próximo ciclo, a cada dois minutos.

•     **Desistiu** — cinco tentativas sem sucesso. Não saem sozinhos de novo; depois de corrigir a causa, **Devolver à fila**, na aba **A conta**, os põe de volta.

•     **Sem endereço** — o aviso existe na plataforma e **nunca vira e-mail**, porque a pessoa não tem endereço no cadastro. É a causa mais comum de "o aviso não chegou", e a única que não aparece como erro em lugar nenhum.

***

### <font color="#15803D">Avisos por regra — um aviso novo sem publicar versão</font>

O fluxo do aviso reescreve o texto dos avisos que o produto já tem. **Automação ▸ Avisos por regra** é o outro lado: aqui o aviso nasce inteiro na tela. A condição usa o mesmo construtor dos painéis — objeto, campo, comparação, E/OU — e vale para qualquer objeto: achado, risco, chamado, resposta, auditoria.

1.     Clique em **Nova regra**.

2.     Preencha **Nome da regra** (ex.: Achado crítico avisa o responsável), escolha **Sobre o quê** e **Quando avaliar**: **ao criar e ao alterar**, **só ao criar** ou **só ao alterar**.

3.     Monte a condição. Vazia significa **sempre** — e sempre é o que produz aviso demais.

4.     Em **Para quem vai**, escolha o destinatário.

5.     Escreva **Assunto** e **Corpo**; as variáveis de **Disponíveis** (\{numero}, \{titulo}, \{protocolo}…) entram com um clique. A que o objeto não tiver sai entre chaves, à mostra.

6.     Deixe **Em ensaio** marcado na primeira vez: a regra avalia e registra, e não envia. Clique em **Gravar**.

7.     Acompanhe os disparos na lista. Quando o ensaio mostrar que a condição casa com o que devia, clique em **Editar**, desmarque **Em ensaio** e grave — a partir daí o aviso sai de verdade.

Cada regra mostra quantas vezes disparou e quando. **Nunca disparou** é o sintoma mais comum de condição escrita errada. **Ativa**, desmarcada, desliga a regra sem apagá-la; a lixeira a apaga, depois de perguntar — os disparos já feitos continuam registrados. O ensaio nasce ligado de propósito: ninguém desfaz um e-mail enviado a trezentas pessoas.

[title] 27. O assistente
[path] Aplicações/GRCS/

*Pergunte como fazer qualquer coisa na plataforma — ele responde pelo manual e leva você à tela.*

A **faísca**, no alto de toda tela, abre o assistente. Ele tem três modos, escolhidos no topo da janela:

•     **Como fazer** — o padrão, para qualquer pessoa conectada: tire qualquer dúvida sobre a plataforma e seja levado à tela certa.

•     **Planejar auditoria** — descreva o que quer auditar e ele recomenda as normas e pergunta o que falta de escopo (para quem lê o catálogo).

•     **Montar widget** — descreva o quadro e ele monta a consulta para você conferir e criar (para quem monta painéis).

***

### <font color="#15803D">Como fazer</font>

Pergunte em palavras suas o que você quer fazer — criar, aprovar, encontrar, configurar:

•     "Como registro uma não conformidade e o plano de ação?"

•     "Onde aprovo um documento que está comigo?"

•     "Como disparo uma onda de auditoria para as áreas?"

•     "Como monto um painel com os riscos acima do apetite?"

A resposta traz:

1.     **O passo a passo**, com os nomes das telas e dos botões.

2.     **Os botões do caminho**: *Abrir* seguido do nome da tela leva direto a ela; *Ler no manual* abre o capítulo em que a resposta se apoiou.

3.     **Com base em** — as seções do manual usadas, para você conferir.

A conversa continua: pergunte de novo, peça detalhe, diga o que não deu certo. Ele considera a tela em que você está quando abriu a janela.

***

### <font color="#15803D">O que ele sabe, e o que ele não faz</font>

•     Ele responde **pelo manual** desta plataforma e pelas **telas que o seu menu mostra**. Não indica tela que o seu perfil não abre: se o que você quer depende de outra permissão, ele diz isso, e quem concede é o administrador (*Áreas, grupos, usuários e perfis*).

•     Quando o manual não cobre a pergunta, ele diz que não sabe e sugere a tela mais próxima, em vez de inventar menu ou campo.

•     Ele **orienta; quem executa é você**. Criar, aprovar, encerrar e publicar continuam sendo feitos na tela, com a sua permissão e o seu registro na trilha de auditoria.

***

### <font color="#15803D">Com e sem modelo de linguagem</font>

Com um modelo de linguagem cadastrado (*Modelos de linguagem, parecer prévio e sandbox*), a resposta é conversada: ele lê os trechos do manual e explica o caminho. Sem modelo — ou com o modelo fora do ar — ele ainda ajuda: busca as seções do manual e as telas pelo vocabulário da pergunta e oferece os mesmos botões, com o trecho do manual no lugar da explicação.

***

### <font color="#15803D">Outras ajudas</font>

•     **O ?** do cabeçalho abre o manual na seção da tela em que você está.

•     **Como funciona, de ponta a ponta** (nas Preferências) mostra o processo inteiro, passo a passo, e marca o que a sua organização já fez.

•     **Pergunte à base** (Acervo) responde sobre os **documentos da organização** — políticas, normas, procedimentos —, com a fonte citada. O assistente responde sobre **a plataforma**.

[title] 28. Integração com o diretório
[path] Aplicações/GRCS/

*Como a organização entra na plataforma, e um teste que prova.*

Duas formas de a organização entrar, e elas não são equivalentes.

**Cada tenant tem o seu.** O provedor (ou o LDAP) é configurado dentro do tenant, em Diretório e identidade, e vale só para ele: cada empresa entra pelo próprio diretório, e o de uma não serve a outra. Vale para os três sites do tenant — a plataforma, o **portal de atendimento** e o **responder** —, e a pessoa volta ao site de onde saiu. O provedor da instalação (o do console da instalação) é outro e não é de cliente nenhum.

***

### <font color="#15803D">OpenID Connect / OAuth 2.0 — a preferida</font>

A senha de rede do usuário **nunca chega à plataforma**: o navegador vai ao provedor, o provedor fala com o Active Directory, e o GRC recebe apenas o código de autorização. Um comprometimento do GRC não expõe credencial de rede de ninguém.

***

### <font color="#15803D">LDAP direto — a alternativa</font>

Serve quando não há gestor de identidade no meio, e é a inferior das duas: no bind a senha de rede do usuário passa pela plataforma. Por isso a conexão sem ldaps\:// é sinalizada — o canal carrega a credencial como ela é.

***

### <font color="#15803D">Configurar o login da empresa (OpenID Connect ou LDAP)</font>

A tela fica em **Administração ▸ Diretório e identidade** (o título da página é o mesmo do menu), com permissão admin\:usuarios. Dois blocos lado a lado: **OpenID Connect / OAuth 2.0** e **Diretório Ativo por LDAP**, cada um com o selo **em uso** ou **inativo**.

Para ligar o OpenID Connect:

1.     Em **Como as pessoas entram**, escolha **Os dois: login da empresa e senha local** (recomendado), **Só o login da empresa (OIDC)** ou **Só senha local**. "Só OIDC" deixa todo mundo de fora — inclusive o administrador — se o provedor cair.

2.     Preencha **Emissor (realm)** (ex.: https\://auth.exemplo.com/realms/producao), **Client ID**, **Segredo do cliente** (em branco para cliente público, só PKCE), **Redirect URI**, **Escopos**, **Claim do usuário**, **Claim de grupos** e, se o provedor declarar o tenant no token, **Claim do tenant**. Escolha o **Perfil padrão** na lista (o recomendado é **Solicitante**) e, se quiser, monte o mapa **Grupo do diretório → perfil** (veja Perfis).

3.     Clique em **Testar conexão** e confira os selos **emissor confere**, **PKCE suportado** e **tenant no token**.

4.     Clique em **Salvar OpenID Connect**. Vale na próxima entrada, sem reiniciar: o login lê a configuração do tenant a cada vez. Teste antes de salvar, e mantenha "os dois" até confirmar que o login da empresa funciona — com "só OIDC" e um emissor errado, ninguém deste tenant entra.

Para o LDAP, preencha **Servidor** (prefira ldaps\://), **Base DN**, **Filtro de usuário**, **Bind DN**, **Senha de serviço**, **Base de grupos** e **Filtro de grupos**, escolha o **Perfil padrão** na lista, marque **Usar o LDAP direto** e clique em **Salvar LDAP**.

O LDAP também é do tenant. **Servidor**, **Base DN**, **Bind DN**, **Senha de serviço** e **Base de grupos** são só dele: nenhuma variável de ambiente os preenche ou trava, e um tenant que não os salvou não tem LDAP. As variáveis GRC\_LDAP\_URL, GRC\_LDAP\_BASE\_DN, GRC\_LDAP\_BIND\_DN, GRC\_LDAP\_BIND\_PASSWORD, GRC\_LDAP\_GROUP\_BASE\_DN e GRC\_LDAP\_ENABLED não valem para tenant nenhum — uma variável da instalação valeria para todos de uma vez. **Filtro de usuário**, **Filtro de grupos** e **Perfil padrão** têm o padrão da instalação (grc.ldap.\*, ou seja, GRC\_LDAP\_USER\_FILTER, GRC\_LDAP\_GROUP\_FILTER e GRC\_LDAP\_DEFAULT\_ROLE; de fábrica, (sAMAccountName=\{0}), (member=\{0}) e Solicitante), que vale onde o tenant deixou o campo em branco.

GRC\_LDAP\_ALLOW\_PLAINTEXT=true continua sendo uma permissão da instalação, e não configuração de diretório: é o que deixa um servidor ldap\://, sem TLS, ser usado num ambiente de teste. Sem ela, o login por ldap\:// é recusado e o motivo vai para o log do servidor, porque a senha iria em claro pela rede.

Abaixo dos blocos, **Como ligar o Keycloak como ponte para o Active Directory** traz o passo a passo do lado do provedor, com a URL de retorno desta instalação pronta para copiar:

1.     No realm, crie um cliente OpenID Connect com *Standard flow* (Authorization Code) e *PKCE method* S256.

2.     Em *Valid redirect URIs*, informe a URL de retorno que a tela mostra.

3.     Adicione um *mapper* de grupos com nome de claim groups (nomes com caminho, como /GRC/Analistas, são aceitos).

4.     Preencha os campos da tela, use **Testar conexão** e só então tente entrar. A **Redirect URI** é a do endereço deste tenant (ex.: https\://empresa.exemplo.com/oidc/callback), e é ela que vai em *Valid redirect URIs* — cada tenant registra a sua no provedor dele.

5.     Em **Grupo do diretório → perfil**, ligue cada grupo do AD ao perfil da plataforma e salve. Em **Perfis de acesso** se define o que cada perfil pode fazer — o grupo só escolhe o perfil.

***

### <font color="#15803D">O provedor é do tenant, e só dele</font>

Emissor, client ID, segredo e redirect URI são de cada tenant, e nenhuma variável de ambiente os preenche ou trava: um tenant sem provedor salvo entra só com senha local. GRC\_OIDC\_SCOPES, GRC\_OIDC\_USERNAME\_CLAIM, GRC\_OIDC\_ROLE\_CLAIM e GRC\_OIDC\_DEFAULT\_ROLE, quando definidas, são só o padrão dos campos que o tenant deixou em branco. GRC\_OIDC\_ISSUER não liga o login de ninguém: serve para validar tokens de serviço quando a instalação usa GRC\_AUTH\_MODO=oidc ou ambos. Se o provedor declara o tenant numa claim (**Claim do tenant**), ela tem de bater com o tenant do endereço — um token de outra empresa não abre sessão aqui.

Quem entra pelo provedor pela primeira vez, sem convite, e não casa com nenhum grupo mapeado recebe o **perfil padrão** — **Solicitante**, se o tenant não escolher outro: abre chamado no portal e lê e pergunta sobre documentos, e nada mais. Quem veio por **convite** entra com o perfil do convite (Colaborador, por padrão), que também responde no /responder. Para dar mais, mapeie o grupo ou troque o perfil da pessoa em Usuários; a troca manual fica, a menos que um grupo mapeado diga outra coisa na próxima entrada.

***

### <font color="#15803D">Conta local com o mesmo login</font>

A entrada pelo provedor acha a pessoa pelo login que o token traz, e só entra em conta de **origem externa** — a que o próprio provedor criou na primeira entrada, ou a que nasceu de um convite aceito pelo diretório. **Nunca entra em conta local**, a que tem senha guardada na plataforma, nem quando a pessoa chega com um convite. Há provedor que deixa cada um escolher o próprio nome de usuário, e vincular pelo login entregaria o admin do tenant a quem criasse lá um usuário admin. (Origem não é o **Tipo** da tela de Usuários: uma conta local pode ser do tipo Interno ou Externo.)

Quando o login do provedor coincide com uma conta local, a entrada é recusada. A pessoa lê que já existe uma conta local com aquele login e que o administrador da organização precisa resolver; o log do servidor registra o tenant, o login e a conta. A conta local não é alterada.

A plataforma não tem ação que transforme conta local em externa, nem que troque o login de uma conta. Para resolver:

•     **A pessoa continua na conta local:** entra com login e senha, como antes. Desativar a conta local não libera o login para o provedor — ela continua existindo.

•     **A pessoa passa a entrar pelo provedor:** faça o provedor mandar um login que não colida — outro nome de usuário para ela no provedor, ou a **Claim do usuário** apontando para uma claim única, como o e-mail (essa troca vale para todo o tenant). Na primeira entrada nasce a conta externa; dê a ela o perfil e os grupos em Usuários e desative a conta local antiga.

•     **O login precisa continuar o mesmo:** quem administra a instalação, com acesso ao banco, renomeia o login da conta local (iam.usuario.login, por exemplo admin para admin.local); a próxima entrada pelo provedor cria a conta externa com o login que ficou livre.

O segredo do cliente e a senha de serviço nunca saem do servidor. A tela mostra **se eles existem**, nunca o valor, e o campo em branco mantém o que já está gravado: segredo que a tela desenha é segredo que vaza pelo print, pelo log do navegador e pela captura do suporte.

No banco, os dois ficam **cifrados** (AES-GCM, com o prefixo v1:), e não em claro: quem lê o banco ou um backup não vê as credenciais dos diretórios. A chave é a da instalação — GRC\_CONSOLE\_CHAVE, senão GRC\_INTEGRACAO\_CHAVE, senão uma chave sorteada e guardada no banco na primeira vez. Trocar a chave (ou restaurar a base noutra instalação) faz o segredo guardado deixar de abrir: ele passa a valer como não configurado, o log do servidor diz por quê, e é preciso informar o segredo do cliente e a senha de serviço de novo nesta tela. Trate a chave como parte do backup da instalação.

***

### <font color="#15803D">O que a entrada pelo provedor confere</font>

O id\_token que volta do provedor é conferido como ele pede: a **assinatura**, pelas chaves que o provedor publica no jwks\_uri do documento de descoberta; o **emissor**; a **audiência**, que tem de ser o client ID deste tenant; e a **validade**, com um minuto de folga de relógio. Token de outro emissor, emitido para outro cliente ou vencido não abre sessão, e a razão fica escrita. O provedor precisa publicar jwks\_uri: sem as chaves, a assinatura não tem como ser conferida, e a entrada é recusada. O **Testar conexão** não olha esse campo; se a entrada falhar dizendo isso, confira o documento de descoberta do provedor.

A ida ao provedor fica no banco (core.entrada\_oidc\_pendente, por dez minutos), e não na memória de uma instância: com várias instâncias atrás do balanceador, a volta pode cair em qualquer uma. A tabela tem RLS por tenant, então a volta só acha o pedido pelo endereço do mesmo tenant de onde a pessoa saiu. A chave da linha é o hash do state, e não o state.

***

### <font color="#15803D">O teste de conexão</font>

Busca o documento de descoberta do emissor, e é o que separa três coisas que a tela de login mostra como o mesmo erro:

| **Sintoma**               | **O que é**                             |
| ------------------------- | --------------------------------------- |
| HTTP 404                  | realm errado no emissor                 |
| responde, emissor diverge | o realm existe e não é o que se pensava |
| não responde              | rede bloqueada, ou provedor fora        |

Ele também confere duas coisas que só aparecem depois:

•     **PKCE**, que é o que protege o código de autorização em cliente público.

•     **O claim do tenant**, se houver. O tenant vem do endereço por onde a pessoa entrou, e o provedor é o daquele tenant. A claim é uma conferência a mais, opcional: preenchida, um token que declara outro tenant não abre sessão aqui; em branco, vale só o endereço.

***

### <font color="#15803D">Perfis</font>

O mapa **Grupo do diretório → perfil**, no bloco OIDC, é do tenant: cada empresa tem os próprios grupos. Cada linha liga um grupo (com caminho, como /GRC/Analistas, ou só o nome) a um perfil escolhido na lista — os de fábrica e os que o tenant criou em **Perfis de acesso**. **+ Grupo** acrescenta uma linha, **Tirar** remove, e o mapa vale a partir da próxima entrada de cada pessoa, quando é salvo com **Salvar OpenID Connect**. Enquanto o tenant não grava o próprio mapa, a tela mostra o padrão da instalação e diz que é esse o caso. Um perfil que não existe no tenant é recusado na gravação, e o mapa aceita até 200 grupos.

Um grupo mapeado para um perfil com escrita dá escrita a todo mundo do grupo: revise antes de salvar. Quem autentica e não casa com grupo nenhum fica com o **perfil padrão** — de fábrica, o **Solicitante**, que só usa o portal e não consome licença: autenticar no diretório não deve, por si, conceder escrita sobre auditoria.

O **Mapeamento por grupo** do LDAP continua declarado na configuração da implantação (grc.ldap.role-mappings) e aparece só à vista.

No LDAP, **sem nenhum mapeamento o mapeamento por grupo fica desligado** e todos entram com o perfil padrão — mesmo com a base de grupos preenchida. A tela avisa quando é esse o caso.

[title] 24. Portal, caso e ciclo de vida
[path] Aplicações/GRCS/

*O site de quem pede, a fila de quem atende, a matriz que diz o que a plataforma aceita e as regras que agem sobre o caso.*

***

### <font color="#15803D">O portal é outro endereço</font>

**\`/portal\`**, e não uma aba do produto.

A separação não é estética. Quem abre um chamado trabalha na empresa, não é auditor: entrar no produto para pedir ajuda significa atravessar um menu de auditorias, riscos e não conformidades que não lhe diz respeito e no qual ele não tem o que fazer. Uma barra lateral de portas trancadas faz a pessoa concluir que errou de lugar — e o que ela faz então é telefonar. **O chamado que nasce de um telefonema nasce sem registro.**

O portal tem endereço próprio, pacote próprio e tela própria: cabeçalho, seletor de tema, seletor de tamanho de texto, e nada mais. **A autenticação continua sendo a mesma** — o mesmo servidor, o mesmo cadastro de pessoas. Identidade separada seria um segundo cadastro de usuários para manter, e um segundo lugar onde alguém esquece de remover quem saiu da organização.

A aba Pedir ajuda continua existindo dentro do produto, como atalho para quem já está lá. É o mesmo componente, e não uma segunda implementação.

***

### <font color="#15803D">O que o colaborador faz no portal</font>

O portal é a casa de quem trabalha na organização, e não só de quem pede ajuda. As abas:

| **aba**                   | **o que é**                                                                        | **pede**                               |
| ------------------------- | ---------------------------------------------------------------------------------- | -------------------------------------- |
| **Preciso de ajuda**      | procurar no catálogo e na base; se não resolver, abrir o chamado                   | `caso:abrir`                           |
| **Leitura obrigatória**   | os documentos que a organização pede que você leia; a ciência fica ligada à versão | `documento:ler`                        |
| **Pesquisar e perguntar** | procurar documentos do acervo, ou perguntar à base em linguagem natural            | `documento:ler`, `documento:perguntar` |
| **Análise de aderência**  | trazer um documento e ver se ele atende às normas marcadas; nada é guardado        | `documento:analisar`                   |
| **Meus chamados**         | acompanhar os próprios chamados                                                    | `caso:abrir`                           |

Cada aba aparece só para quem tem a permissão. O **Solicitante** (quem entra pelo login da empresa) tem a ajuda, os chamados, a leitura e a pergunta à base; a **análise de aderência** é do **Colaborador** (quem entra por convite), que também responde auditoria no **/responder**. Ler, perguntar e analisar a aderência não consomem licença por si (D11); o que consome é o perfil — o Colaborador ocupa vaga de Analista, porque responde auditoria. O custo da IA fica contido pela cota diária por pessoa. As mesmas telas continuam no menu do produto (Acervo), para o auditor e o gestor.

***

### <font color="#15803D">São três páginas, e elas se citam</font>

| **Endereço** | **Quem entra**               | **O que faz**                                   |
| ------------ | ---------------------------- | ----------------------------------------------- |
| /            | auditor, gestor              | conduz auditorias, trata achados, monta painéis |
| /responder   | a área ou equipe avaliada    | responde as perguntas que lhe foram despachadas |
| /portal      | quem precisa de alguma coisa | procura na base de conhecimento e abre chamado  |

As três compartilham **o mesmo login** — o mesmo servidor, o mesmo cadastro de pessoas. Identidade separada seria um segundo cadastro de usuários para manter, e um segundo lugar onde alguém esquece de remover quem saiu da organização.

Quando o tenant configurou o próprio provedor de identidade (*Integração com o diretório*), a entrada do portal e do /responder mostra **Entrar pelo provedor da organização**, acima do login e senha. É o provedor do tenant daquele endereço, o mesmo da plataforma, e a volta dele cai de novo no site de onde a pessoa saiu, e não na plataforma. Com o tenant em "só o login da empresa", o formulário de senha some e fica só o botão.

E se citam: o rodapé de cada uma leva às outras duas, e o rodapé do menu lateral do produto leva às duas de fora. Separadas sem se citarem viram ilhas, e a pessoa que precisa da outra volta a perguntar a alguém por onde se entra — que é exatamente o que a separação veio evitar.

***

### <font color="#15803D">O artigo vem antes do formulário</font>

Metade do que chega como chamado já está respondida na base de conhecimento. Um portal que abre o formulário primeiro transforma toda dúvida em chamado — e o artigo que resolveria em trinta segundos vira uma fila de dois dias.

***

### <font color="#15803D">Quando a palavra não acha, a descrição acha</font>

A busca do portal é por termo. Quem escreve *"não consigo entrar"* não encontra um item chamado *"Redefinição de senha"*, porque as palavras não coincidem — e era esse o ponto em que a pessoa desistia do portal.

Quando a busca **não acha nada** e há o que descrever, aparece **Classificar o que eu escrevi**: a plataforma lê a descrição e diz onde aquilo se encaixa.

•     **Com catálogo cadastrado**, o modelo **escolhe** dentro do que existe. Não inventa galho novo: um catálogo que cresce sozinho a cada chamado deixa de ser catálogo em um mês, e a fila de atendimento passa a ter trezentas categorias com um caso cada.

•     **Sem catálogo** — que é o estado de fábrica —, ele **propõe** um trio novo: serviço, categoria e subcategoria. É o único modo em que ele escreve no catálogo, e mesmo assim só depois de alguém com permissão de administrar aceitar.

•     **"Nenhuma serve"** é uma resposta legítima, e a tela a mostra como tal. Um chamado mal classificado vai para a fila errada e espera lá; um palpite classificado parece uma decisão.

A sugestão **não abre o chamado** e não se aplica sozinha. Ela vem com o nome do modelo e o grau de confiança, e quem confirma é quem pediu — sugestão aplicada sem confirmação é decisão sem autor, e quando erra não há a quem perguntar por quê.

A classificação exige um modelo de linguagem ativo em **Administração ▸ Modelo de linguagem**. Sem ele, a tela diz isso em vez de falhar em silêncio.

***

### <font color="#15803D">Casos — abrir, atender e encerrar</font>

A tela **Casos** é a fila de quem atende. Filtre por **Estado**, **Prioridade**, **Buscar** (número ou título) e **só os meus**; a barra de cada linha diz qual relógio corre e quanto dele já passou.

1.     Para registrar, clique em **Abrir caso**. Preencha **O que aconteceu** (obrigatório), **Detalhe**, **Item do catálogo** (ou *sem item — o atendente classifica*), **Impacto** e **Urgência**. Marque **Envolve dado pessoal** quando for o caso: eleva a prioridade e aciona o prazo legal. Clique em **abrir**.

2.     Clique no caso. No topo ficam os **Relógios do acordo**; abaixo, as abas **Trabalho**, **Vínculos** e **Linha do tempo**.

3.     Em **Responder**, escreva e clique em **Responder ao solicitante** — é o que cumpre o relógio de primeira resposta — ou em **Nota interna**, que o solicitante não vê.

4.     Em **Tarefas**, clique em **concluir** em cada uma. As **obrigatórias** aparecem marcadas.

5.     Em **Mover o caso**, os botões são as situações para onde o ciclo de vida deixa ir; algumas pedem motivo.

6.     Para fechar, clique em **Encerrar com causa**: escolha a **Categoria de causa**, escreva a **Solução aplicada** (obrigatória) e, se houve, a **Solução de contorno**. Clique em **encerrar**.

A prioridade sai da matriz da política (impacto × urgência); quando algo a eleva, o caso diz de quanto e por quê.

Para ligar o caso a um objeto de governança, na aba **Vínculos**:

1.     Clique em **Vincular a um registro**.

2.     Escolha o **Tipo de registro** — risco, não conformidade, controle, ativo (alvo), processo, auditoria, política, oportunidade, plano de ação ou outro caso — e a **Relação**. Para risco, a relação padrão é **materializa**: o caso conta como ocorrência do risco e entra no histórico de frequência da reavaliação. **Materializa** só existe para risco, e **duplica** só para outro caso.

3.     Busque pelo número ou pelo título e clique no registro. O vínculo aparece na lista, com o nome do registro, e a prioridade é recalculada — vínculo com risco de criticidade alta ou com contrato sobe um degrau.

4.     Para desfazer, clique no **x** do vínculo e confirme em **Desfazer vínculo**. A linha do tempo registra a remoção, e a prioridade é recalculada sem ele.

Vincular e desfazer pedem a permissão de atender caso. Os vínculos criados por regra ("Vincular a um registro", em Regras de atendimento) aparecem na mesma lista.

***

### <font color="#15803D">O ciclo de vida do caso é seu</font>

**Tratamento ▸ Ciclo de vida do caso** (pede a permissão de administrar casos).

1.     Escolha o tipo: **Incidente**, **Requisição**, **Problema**, **Incidente maior** ou **Ocorrência**.

2.     Na matriz, cada linha é a situação de origem e cada coluna a de destino. Clique na célula para ligar ou desligar a transição.

3.     Clique em **Gravar o ciclo**. O botão fica desligado enquanto nada mudou ou enquanto algum status ficaria sem saída.

A plataforma nasce com nove situações por tipo de caso — incidente, requisição, problema, incidente maior e ocorrência — e com o desenho de fábrica de **o que liga cada uma às outras**.

A tela é uma **matriz**, e não uma lista de transições. A diferença não é estética: numa lista, *"de Resolvido não se volta para Novo"* é uma linha que não existe, e o que não existe não se vê. Na matriz é uma célula vazia — que se vê, e que se clica para mudar de ideia.

O que **não** estiver marcado a plataforma recusa. É isso que impede um chamado de encerrar sem que ninguém o tenha olhado.

*As regras do desenho de fábrica*

| **Regra**                                                            | **Por quê**                                                                                                                                                      |
| -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| de **Novo** só se vai para triagem, atendimento ou cancelado         | encerrar um caso que ninguém olhou é a forma mais comum de fila limpa mentindo sobre trabalho feito                                                              |
| os três **"aguardando"** voltam para atendimento, e não para triagem | o caso já foi triado; refazê‑lo joga fora a decisão de quem triou                                                                                                |
| **Resolvido** reabre para atendimento                                | resolver é uma afirmação sobre o problema, e quem abriu pode discordar                                                                                           |
| **Encerrado** e **Cancelado** não saem                               | um estado terminal do qual se sai não é terminal: é um estado intermediário com nome de fim, e todo indicador que conta "encerrados" passa a contar o que voltou |

*O que a gravação recusa*

Três incoerências, e a recusa é deliberada. Uma máquina de estados incoerente não quebra nada no momento em que é gravada: ela quebra semanas depois, quando um caso entra num status de onde não sai, e o que se vê então é um chamado parado que ninguém entende.

•     transição de um status para ele mesmo;

•     saída a partir de um estado terminal;

•     status sem nenhuma saída — a tela avisa **enquanto você edita**, e não só ao gravar, porque descobrir isso no fim faria você refazer a matriz inteira para achar a linha vazia.

**Voltar ao de fábrica** apaga o seu desenho. A linha de fábrica fica intacta o tempo todo, e é por isso que voltar sempre funciona.

***

### <font color="#15803D">Regras de atendimento: condição e ação em listas</font>

Em **Tratamento ▸ Regras de atendimento** (pede a permissão de administrar casos), a regra se monta escolhendo, e não escrevendo JSON:

1.     Clique em **Nova regra**. Preencha **Nome**, **Descrição**, **Gatilho** e **Ordem**.

2.     Em **Condição**, clique em **Adicionar condição** para cada linha e escolha em **Vale quando** se valem todas as linhas ou qualquer uma.

3.     Em **Ação**, escolha **O que fazer** e preencha os parâmetros que aparecem.

4.     Deixe **Ativa** e **Só simular (não age sobre o caso)** marcadas enquanto testa. Clique em **Gravar**.

5.     Na lista, clique em **Ensaiar**, escolha o **Caso** e clique em **Rodar sem executar**. O botão **Conferir em …** leva ao lugar onde o efeito apareceria.

6.     Satisfeito, abra a regra (**Editar**), desmarque **Só simular** e grave.

**Varrer agora** roda na hora a varredura do tempo que a plataforma faz sozinha a cada cinco minutos. **Remover**, dentro do editor, pergunta antes de apagar a regra: o log de disparos dela sai junto, e o que ela já fez nos casos fica no histórico de cada um. Para só pausar, desmarque **Ativa**. O que cada regra fez aparece na coluna **Disparos**, ao lado da lista.

O que cada parte faz:

•     **Gatilho** — quando a regra é avaliada: o caso nasce, muda, encosta no prazo ou para de andar.

•     **Condição** — linhas de *campo*, *operador* e *valor*. Os campos com valores conhecidos (prioridade, impacto, urgência, nível, tipo, estado) oferecem a lista; os demais aceitam texto. Escolha se valem **todas** as linhas ou **qualquer** uma. Sem linha, a regra vale para todo caso do gatilho.

•     **Ação** — o que fazer: notificar, atribuir, alterar um campo, mudar o status, criar tarefa, escalonar ou vincular. Cada ação mostra só os parâmetros dela (para quem notificar, por qual modo atribuir, qual campo e valor, e assim por diante).

A regra continua gravada no mesmo formato de antes, e o JSON segue disponível em **Editar como JSON (avançado)**. Uma regra antiga com grupos aninhados (um "e" dentro de um "ou") abre direto no modo avançado, com um aviso: o formulário não a mostraria inteira, e abrir num formulário que a achatasse mudaria o que ela faz.

***

### <font color="#15803D">O ensaio diz onde conferir e o que esperar</font>

Antes ele terminava em *"notificaria ATENDENTE sobre INC-2026-000015"* e parava ali, deixando duas perguntas sem resposta — **onde eu confiro?** e **o que eu devo ver?** — cuja única saída era disparar de verdade e procurar. Ensaio que obriga a executar para ser entendido não é ensaio.

Agora cada ensaio devolve três coisas: a **página** onde o registro muda, o **link** para ela já apontado ao caso, e uma frase no futuro dizendo o que aparece lá.

| **Ação**       | **Onde conferir** | **O que esperar**                                                                                                |
| -------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------- |
| Notificar      | Avisos            | um aviso novo para o destinatário, com aquele assunto; sai também por e-mail se a conta estiver configurada      |
| Atribuir       | o caso            | o campo Atendente deixa de estar vazio e o relógio de atribuição para                                            |
| Alterar campo  | o caso            | o campo passa a valer aquilo, e a troca entra no histórico com o nome da regra                                   |
| Alterar status | o caso            | o caso vai para aquele status — se a transição não existir no ciclo de vida, a regra falha e a falha fica no log |
| Criar tarefa   | o caso            | uma tarefa nova, pendente e sem dono                                                                             |
| Escalar        | o caso            | um escalonamento registrado e um aviso a quem a matriz da política aponta                                        |
| Vincular       | o caso            | um vínculo novo, visível nos dois lados                                                                          |

***

### <font color="#15803D">"Ao disparar, nada mudaria"</font>

O ensaio avisa **antes** quando a ação dispararia sem fazer nada. O caso de sempre: a regra avisa o atendente, e o caso ainda não tem atendente — ela dispara, registra o disparo e não avisa ninguém. Era exatamente isto que se via como *"ficou disparando e nada aconteceu"*.

Quando acontece de verdade, **o disparo não fica gravado como sucesso**. A linha antiga dizia que a regra agiu, e quem investigava acreditava no log.

***

### <font color="#15803D">Uma regra de tempo não se repete com o caso parado</font>

Três gatilhos não dependem de ninguém agir — **percentual de SLA**, **prazo** e **inatividade** — e a condição deles continua verdadeira enquanto o caso fica parado. Sem memória, a varredura de cinco em cinco minutos redisparava a mesma regra sobre o mesmo caso indefinidamente: dois casos chegaram a **388 disparos cada** em dois dias. Em simulação isso enche o log; ligada, seriam 388 e-mails para a mesma pessoa sobre o mesmo chamado — e o que a organização faz com isso é desligar a automação inteira.

A memória é o **movimento do caso**, e não um intervalo fixo: assim que alguém interage, o aviso volta a poder sair. Um intervalo fixo silenciaria o aviso de um caso que acabou de mudar de mão, que é justamente quando ele importa.

O ensaio mostra quantas vezes aquela regra já disparou sobre aquele caso. Número alto é quase sempre condição que nunca deixa de ser verdadeira.

[title] 30. Como a instalação chama quem é auditado
[path] Aplicações/GRCS/

*Empresa ou órgão público — um valor que troca a palavra em 269 textos sem editar nenhum.*

A pergunta que originou este campo foi literal: *"tem como deixar órgão somente no PPSI e o restante como empresa?"*

**Por norma não dá**, e o motivo é o desenho do acervo. A mesma pergunta serve a várias normas ao mesmo tempo — quatro delas atendem a quinze normas cada —, existe **um enunciado por pergunta**, e é exatamente isso que faz a pergunta cobrada por duas normas ser respondida uma vez só. Duplicá-la resolveria a frase e destruiria o alcance cruzado: quem responde veria a mesma pergunta duas vezes. E uma auditoria aberta contra PPSI **e** ISO 27001 juntos não teria qual dos dois textos mostrar.

**Por instalação dá**, e é melhor que as duas alternativas. O texto guarda um marcador, e a instalação declara o que ela é:

:::BlockQuote
\{\{A\_entidade}} nomeou um Gestor de Segurança da Informação?
:::

A chave **dupla** acima não é erro de digitação: é como se escreve o marcador sem que ele seja trocado. Sem ela, este capítulo seria o único texto da plataforma que a tradução estragaria — ele mostraria "A empresa nomeou…" onde precisa mostrar o marcador.

Uma empresa lê *"A empresa nomeou…"*; um órgão público troca um valor e lê *"O órgão nomeou…"*, sem editar duzentos e sessenta e nove textos. **O padrão é empresa**, porque é o que descreve quase todo cliente.

***

### <font color="#15803D">Trocar a palavra</font>

1.     Abra **Administração ▸ Normas disponíveis**. O primeiro bloco é **Como chamamos quem é auditado**.

2.     Escolha uma das opções — cada uma traz ao lado o exemplo do texto como ele vai ficar.

3.     Pronto: não há botão de salvar. A escolha grava na hora e as listagens abertas se recarregam.

Trocar exige a permissão admin\:estrutura; quem tem só admin\:usuarios vê a tela e não grava. Voltar atrás é escolher a outra opção de novo — nenhum texto é reescrito.

***

### <font color="#15803D">Os marcadores carregam a contração</font>

E não só o substantivo. "O órgão" é masculino e "a empresa" é feminino: um marcador único deixaria "do empresa" pelo caminho, e ninguém revisa duzentos e sessenta e nove enunciados procurando concordância. Por isso existem formas separadas para \{\{da\_entidade}}, \{\{na\_entidade}}, \{\{pela\_entidade}}, \{\{as\_entidades}} e as demais, cada uma com a sua versão capitalizada.

Marcador desconhecido **fica à mostra**, entre chaves, em vez de virar vazio. Apagar em silêncio produziria "A nomeou uma autoridade" — uma frase que parece correta e está errada, e que ninguém revisa porque não chama atenção.

***

### <font color="#15803D">Onde a troca </font>

Na leitura, num lugar só: a serialização da resposta. O enunciado aparece na listagem de perguntas, na fila, no questionário, na exportação, na busca, no assistente e em cada painel que cita a pergunta — traduzir em cada um deles seria dezenas de lugares, e o que fosse esquecido só apareceria na tela de alguém.

O banco continua guardando o marcador. Por isso a troca é **reversível sem perda**, e por isso ela vale para as telas já existentes e para a que ainda não foi escrita.

***

### <font color="#15803D">O que a troca não alcança</font>

Um texto que alguém **editou pela tela** deixa de acompanhar o vocabulário: ao gravar, o que vai para o banco é a palavra literal que estava no campo. É o comportamento certo — aquele texto passou a ser da instalação, escrito como ela quis —, mas vale saber que ele não muda mais junto.

O módulo **IMR** continua dizendo "órgão contratante" de propósito: ele atende exclusivamente a contratos do Governo Federal brasileiro, e ali a palavra é a correta.

[title] 35. Qualidade e a cadeia de testes
[path] Aplicações/GRCS/

*As doze categorias de teste que sustentam a plataforma, o que cada uma responde e como rodá-las.*

A plataforma tem uma cadeia de testes em doze categorias, com um executor único. Ela vive em testes/ e roda contra um ambiente de pé:

:::BlockQuote
cd testes && ./executar.sh            # a cadeia inteira
cd testes && ./executar.sh seguranca  # uma categoria
:::

A ordem não é estética. Unitário primeiro porque é o mais barato e o que localiza melhor: se a regra está errada na função, não adianta descobrir isso numa jornada de navegador quinze minutos depois. Aceitação vem perto do fim porque é o mais caro e o que menos informa sobre onde está o defeito. EHT vem depois dela porque é leitura — não derruba nada —, e failover fica por último porque é o único que deixa o ambiente diferente de como o encontrou por alguns segundos.

***

### <font color="#15803D">O que cada elo responde</font>

**Unitário** — cada peça isolada faz o que promete. Backend em JUnit dentro de contêiner, para que a máquina não precise ter Java; frontend em Vitest.

**Funcional** — o sistema cumpre a regra de negócio, e não apenas responde. A diferença aparece na segregação: o endpoint responde com alegria, e a regra diz que quem respondeu não aprova. Um teste que só olha o status nunca descobre isso.

**Regressão** — o que já quebrou não voltou a quebrar. Cada caso corresponde a um defeito real e traz o sintoma que foi relatado, e não só a asserção. Um teste de regressão escrito por adivinhação cobre o que nunca falhou.

**Integração** — os módulos conversam nas costuras. É onde o sistema realmente falha: cada módulo passa no próprio teste e a resposta que vira achado, que vira risco, que aparece no painel, que abre o registro, é uma corrente de quatro elos que ninguém testa inteira por acidente.

**Performance** — velocidade e estabilidade sob concorrência. Mede percentil e não média: a média esconde a consulta que responde em 80ms quase sempre e em 4s uma vez a cada vinte, e é da quarta que o usuário lembra.

**Segurança** — o que a plataforma promete ser impossível é impossível. Não é varredura genérica: são as promessas deste produto, que é o que um atacante interno testaria primeiro — ver dado de outro tenant, alcançar endpoint sem permissão, forjar token, ler segredo pela API.

**Usabilidade** — o piso do que torna uma tela utilizável: teclado, rótulo associado, idioma declarado, ausência de rolagem horizontal no celular.

**PWA** — o aplicativo instala e sobrevive à perda de rede, e o cache recusa a API.

**Aceitação** — a jornada real fecha. "Carreguei o meu ROPA; onde vejo se estou conforme, o que falta e quem responde por isso?" Se essa jornada não fecha numa sessão, o resto não importa.

**EHT — Engenharia de Homologação Técnica** — o produto foi *construído* direito, e não só funciona. Um sistema inteiramente vulnerável passa em todos os testes funcionais. São quatro frentes:

•     **SAST**, sobre o próprio código: segredo escrito no fonte, SQL montado com texto que pode vir de fora, verificação de certificado desligada, execução de processo do sistema, HTML cru na interface, pendência de segurança.

•     **Dependências com CVE**: usa o relatório do OWASP Dependency-Check quando ele existe — daí saem CVSS, KEV e EPSS — e, quando não existe, confere offline as versões resolvidas no jar e o npm audit. E **diz qual dos dois caminhos usou**: um teste que passa sem base de dados e sem avisar é pior que não existir, porque produz confiança falsa.

Um achado tem três destinos possíveis, e a diferença entre eles é o que separa gestão de vulnerabilidade de teatro:

\| Destino | Quando | Onde fica | |---|---|---| | corrigir | há versão corrigida na linha em uso | sobe a versão | | suprimir | é falso positivo demonstrável | supressoes-cve.xml, uma entrada por CVE, com o motivo | | registrar | é real e não tem correção na linha | riscos-conhecidos.json, com a análise de alcance e **data de revisão** |

Suprimir é a decisão de não olhar mais, então só entra o que se demonstra: o componente vulnerável não está no classpath, ou a versão presente já é posterior à corrigida e o casamento foi por CPE errada. O que é verdadeiro e apenas improvável vai para o registro, não para a supressão.

A suíte reprova quando aparece CVE alta **fora** do registro — é risco novo que ninguém olhou —, quando a data de revisão vence, e quando uma entrada do registro já não aparece na varredura, porque registro que só cresce deixa de ser lido. O relógio é o ponto: sem ele, "migramos depois" vira a decisão permanente que ninguém tomou.

•     **DAST**, sobre a aplicação de pé: cabeçalhos, exposição de tecnologia, endpoint de gestão aberto, e resposta a entrada hostil sem vazar detalhe interno.

•     **Práticas**: RLS ligada *e forçada* em toda tabela com tenant, gatilho de trilha, papel de conexão sem superusuário nem BYPASSRLS, esquema versionado.

**Failover (HA)** — o que acontece quando uma peça cai. Derruba o banco de verdade e verifica as três promessas que só aparecem sob falha: a saúde deixa de dizer UP em vez de fingir; a consulta responde erro em vez de **lista vazia com 200** — zero num painel não parece defeito, parece boa notícia; e a aplicação volta sozinha, com a escrita confirmada antes da queda ainda lá. Não testa cluster: testa o comportamento do processo diante da perda da dependência crítica, que é a metade do problema que o código controla.

***

### <font color="#15803D">O que a cadeia não faz</font>

Usabilidade não se prova por automação — quem prova é gente usando. O que está automatizado é o piso, não o teto. A aceitação cobre as jornadas conhecidas; jornada nova continua exigindo alguém do negócio olhando.

E nenhuma destas suítes substitui teste de penetração. Elas verificam as promessas específicas deste produto, não a superfície inteira.

***

### <font color="#15803D">Achados que a própria cadeia produziu</font>

A suíte de segurança encontrou duas tabelas com tenant\_id e **sem** Row-Level Security: iam.chave\_de\_acesso, que guarda credenciais de contas de serviço, e integration.indice\_de\_execucao, que revela quais fontes cada cliente monitora e desde quando. Corrigidas na migração V63.

A suíte de regressão fixou o trabalhador de serviço como público: ele nasceu devolvendo 401, e o registro falha em silêncio — o aplicativo simplesmente nunca se instalaria, sem erro na tela.

A suíte de segurança, ao ganhar o bloco da chave de integração, mostrou que **nenhuma chave de serviço autenticava**: a troca da chave por token lê iam.chave\_de\_acesso antes de haver tenant na sessão — o tenant é justamente o que a chave vai dizer —, e a política de leitura não casava com nada. Toda chamada com X-API-Key respondia 401 sem explicação. O login por senha já tinha a solução desde sempre: uma política válida só enquanto a janela grc.autenticando está aberta. A chave de serviço nunca ganhou a equivalente. Corrigido na migração V204.

A suíte de EHT, na primeira execução, reprovou seis vezes — e **as seis eram defeitos dela**, não do produto: contava visão como tabela sem RLS; cobrava gatilho de trilha da própria tabela de trilha, o que seria recursão; comparava f/f com o false/false que o psql imprime; media a versão do driver do PostgreSQL pelo número de flyway-database-postgresql; acusava concatenação de SQL num filtro montado só com literais; e, o mais instrutivo, acusava TODO pendente em dois comentários perfeitamente escritos, porque a busca sem distinção de caixa casava com a palavra portuguesa *todo*. Um verificador que acusa o certo é treinamento para ignorar verificador.

[title] 18. Exportação
[path] Aplicações/GRCS/

*Levar o registro para fora — planilha para cruzar, documento fechado para assinar.*

A impressão de tela resolve *levar isto para a reunião*. O que ela não resolve é o outro uso, que é o que a auditoria externa pede: **entregar o registro em formato que se arquiva**. São duas coisas diferentes, e por isso dois formatos.

| **Formato** | **Para quem**               | **O que ele é**                                                 |
| ----------- | --------------------------- | --------------------------------------------------------------- |
| CSV         | quem vai cruzar em planilha | achados contra contratos, riscos contra áreas                   |
| PDF         | quem vai assinar            | o ciclo inteiro, sempre nas mesmas seções, com espaço de aceite |

***

### <font color="#15803D">O que se exporta</font>

| **Onde**                           | **Botão**                | **O que sai**                                                      |
| ---------------------------------- | ------------------------ | ------------------------------------------------------------------ |
| Auditorias, com o ciclo aberto     | Respostas (CSV)          | as respostas com quem respondeu, quem revisou e quantas evidências |
| Auditorias, com o ciclo aberto     | Relatório do ciclo (PDF) | resumo, achados, respostas e aceite                                |
| Não conformidades                  | Exportar achados (CSV)   | a carteira inteira, com a saída de cada achado                     |
| Riscos                             | Exportar riscos (CSV)    | o registro de risco, com inerente e residual lado a lado           |
| Alvos e dimensões, no alto da tela | Registro ROPA (CSV)      | o registro ROPA: uma linha por atividade, uma coluna por pergunta  |

Clique no botão e o arquivo baixa. Os dois botões do ciclo valem em qualquer estado, inclusive rascunho — é o jeito de conferir numa planilha a lista de perguntas de um ciclo grande antes de lançar. Depois do PDF, o botão mostra o começo do resumo SHA‑256 do arquivo emitido. O ROPA sai de todos os ciclos que tocaram o tema ROPA, e por isso o botão fica em **Alvos e dimensões**, e não dentro de um ciclo: cada atividade de tratamento é um alvo.

***

### <font color="#15803D">O CSV abre certo no Excel</font>

Duas escolhas que parecem detalhe e são a diferença entre um arquivo útil e um chamado.

O separador é **ponto e vírgula**, porque o Excel configurado em português usa a vírgula como separador decimal — um CSV separado por vírgula abre com tudo empilhado numa coluna só, e quem recebe não conclui "o separador está errado", conclui que a exportação está quebrada.

E o arquivo começa com a marca de ordem de bytes, senão o Excel lê UTF‑8 como Latin‑1 e *não conformidade* vira *não conformidade* na planilha inteira. Os números saem com vírgula decimal pelo mesmo motivo: com ponto, a planilha trata como texto e nenhuma soma funciona.

***

### <font color="#15803D">O relatório é um documento fechado</font>

Ele não é a tela impressa. Traz sempre as mesmas seções, na mesma ordem, e se identifica: o rodapé de **cada folha** diz quem emitiu e quando, porque folha solta circula sozinha.

O aviso de cobertura abaixo de 70% sai dentro do quadro de resumo, junto do número — num documento que vai para fora, quem lê não tem a tela ao lado para descobrir que só um terço foi avaliado.

Logo depois do resumo vem o **grau de maturidade**, em duas metades e antes dos achados: **por agrupamento**, que diz *o que* está fraco, e **por área responsável**, que diz *de quem é*. As duas juntas, e não em seções distantes, porque quem lê só uma fecha o documento sabendo que a governança está em 0,41 e sem saber a quem perguntar por quê.

A área sem responsável aparece com nome próprio, e não somada às demais: escondê‑la esconderia exatamente o que precisa ser cadastrado, e omiti‑la faria as partes não fecharem com o todo. Nota sem resposta nenhuma sai como travessão e **não como zero** — zero é uma afirmação sobre desempenho, e "ninguém respondeu" não é uma afirmação sobre desempenho; as duas situações pedem ações opostas.

Na tabela de achados há uma coluna **Saída**: plano de ação, aceite vigente, ou SEM SAÍDA. É a regra de ouro impressa, achado a achado.

E há espaço de aceite, com duas assinaturas — a área avaliada e o auditor. Sem a linha, quem recebe imprime, assina na margem, e o que volta é uma rubrica solta que não diz o que foi atestado.

***

### <font color="#15803D">O resumo que prova que o documento é o original</font>

Cada relatório emitido tem o seu **SHA‑256** calculado sobre o arquivo entregue. Ele aparece na tela depois do download, viaja no cabeçalho X-Documento-SHA256 e fica guardado no registro da exportação.

É o que permite comparar o PDF que alguém apresenta numa auditoria com o que a plataforma registrou ter emitido. Sem essa amarra, um documento com o timbre certo e uma tabela alterada é indistinguível do original.

***

### <font color="#15803D">Exportar fica registrado</font>

Exportar é a operação que tira o dado de dentro. Numa plataforma cuja premissa é *tudo é editável, e por isso tudo fica registrado*, deixar justamente a saída sem rastro seria o buraco que a própria auditoria aponta.

Toda exportação grava quem levou, o quê, quando, quantas linhas saíram e — no caso do documento fechado — o resumo do arquivo. Esse registro entra na trilha como qualquer outro: não pode ser alterado nem apagado por quem opera o negócio.

:::hint{type="info"}
**Permissão.** Exportar exige a mesma permissão de ler o que está sendo exportado, e não uma permissão própria. Quem vê o achado na tela consegue copiá-lo de qualquer forma; uma permissão separada seria teatro. O controle de verdade é o registro.
:::

***

### <font color="#15803D">O registro ROPA</font>

O formato que a LGPD pede é uma linha por atividade de tratamento, com as perguntas como colunas — e é o único que um encarregado consegue ler. A plataforma guarda o oposto, uma linha por resposta, então a exportação pivota.

As colunas saem do próprio catálogo, na ordem do formulário: acrescentar uma pergunta ao tema ROPA acrescenta a coluna sozinha. Atividade sem nenhuma resposta preenchida fica de fora — ela existe porque o ciclo tocou o tema, mas uma linha inteiramente vazia num registro legal não informa nada e sugere um tratamento registrado sem conteúdo.

Para baixar: **Alvos e dimensões** → **Registro ROPA (CSV)**, no alto da tela. O botão aparece para quem tem auditoria\:ler — a mesma permissão de ler os ciclos de onde as linhas saem — e, como toda exportação, fica registrado.

[title]  7. Agenda estratégica
[path] Aplicações/BSC/

A estratégia é acompanhada em reuniões: a Reunião de Acompanhamento Estratégico (RAE), o Acompanhamento da Rodovia Norte, o Comitê de riscos, as visitas técnicas às obras e os eventos com outras instituições. A agenda estratégica reúne esses eventos num calendário só — mês, semana, dia ou lista —, cada um na cor da sua categoria, com a pauta, os participantes internos e externos e quem confirmou presença.

Cada reunião tem a sua ficha, com documentos, presença, ata, adendos, encaminhamentos com responsável e prazo, exportação em CSV e envio aos participantes por aviso no sistema, e-mail, WhatsApp e canais de área no Microsoft Teams ou no Discord. Eventos confidenciais ficam visíveis só para quem precisa deles. As telas ficam em Gestão por indicadores › Agenda estratégica e Categorias da agenda.

## 7.1 Categorias da agenda

ID BSC-AGE-01

### Para que serve

As categorias são os tipos de evento da agenda e definem a cor de cada evento no calendário. Toda instalação começa com três: **Reunião**, **Visita técnica** e **Evento externo**.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador).

### Passo a passo

1. Abra Gestão por indicadores › Categorias da agenda.
2. Clique em **Nova categoria**.
3. Informe o **Nome**, a **Descrição** e a **Cor** (obrigatória) e confira a prévia.
4. Salve.
5. Use **Editar** para mudar nome, descrição ou cor, e **Inativar** para tirar a categoria das novas escolhas.
6. Use **Histórico** para ver cada mudança com antes e depois.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/0B4BKUSf9AlSMWkPUHk09_image.png" size="62" isUploading="false" width="620" height="387" showCaption="false"}

Figura 47 — Categorias da agenda com as suas cores

### Observações

- O nome não se repete, sem diferença de maiúsculas e minúsculas.
- O calendário escolhe sozinho o texto preto ou branco com mais contraste sobre a cor.
- Mudar a cor repinta todos os eventos da categoria, inclusive os antigos.
- A categoria inativa continua nos eventos que já a usam.
- Quem só lê a agenda vê a lista de categorias sem botões.

## 7.2 Navegar no calendário

ID BSC-AGE-02

### Para que serve

A agenda estratégica reúne num calendário só as reuniões, visitas técnicas e eventos da estratégia, cada um na cor da sua categoria.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia); Responsável por ação/área; Leitor/Auditor.

### Passo a passo

1. Abra Gestão por indicadores › Agenda estratégica.
2. Use **Mês**, **Semana**, **Dia** ou **Lista** para trocar a visão.
3. Use as setas e **Hoje** para andar no tempo.
4. Clique numa categoria da legenda para ocultar ou mostrar os eventos dela.
5. Marque **Só os meus** para ver só os eventos que você organiza ou dos quais participa.
6. Clique num evento para abrir a ficha.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/8faIgd45BoCG2YwCC3XWz_image.png" size="62" isUploading="false" width="620" height="387" showCaption="false"}

Figura 48 — Agenda estratégica na visão de mês, com a legenda das categorias

### Observações

- Tudo aparece no horário de Brasília, mesmo num computador em outro fuso.
- O dia de hoje fica destacado; na semana e no dia, uma linha vermelha marca a hora atual.
- Pelo teclado: **Tab** chega ao dia selecionado, as setas levam ao dia vizinho e **Enter** abre o dia. O leitor de tela anuncia a data, se é hoje, quantos eventos há e diz **Confidencial** antes do assunto de evento confidencial.
- Categoria desligada na legenda fica riscada até ser religada.
- Se o seu login não estiver vinculado a um empregado, **Só os meus** avisa: não é que você não tenha eventos.
- Eventos que se sobrepõem dividem a largura só entre si.

## 7.3 Agenda no celular

ID BSC-AGE-03

### Para que serve

No celular, a agenda abre na lista da semana, mais fácil de ler numa tela estreita.

**Quem usa:** Responsável por ação/área; Leitor/Auditor.

### Passo a passo

1. No navegador do celular, abra Gestão por indicadores › Agenda estratégica.
2. Percorra a lista da semana ou troque para a visão de mês.
3. No mês, toque num dia (ou tecle Enter) para ver a lista do dia abaixo do calendário.
4. Toque no evento para abrir a ficha.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/CZ-fZD59SU4Or0Y7QZmap_image.png" size="21" isUploading="false" width="208" height="451" showCaption="false"}

Figura 49 — Agenda estratégica no celular

### Observações

- As regras de sigilo e de horário são as mesmas da tela grande.

## 7.4 Cadastrar um evento ou reunião

ID BSC-AGE-04

### Para que serve

Cada evento registra o assunto, a categoria, a data e o horário, o local, a pauta e, se quiser, a que ele se refere no plano: uma ação estratégica, um objetivo ou um ciclo.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia).

### Passo a passo

1. Abra Gestão por indicadores › Agenda estratégica e clique em **Novo evento**.
2. Informe o **Assunto** (por exemplo, Reunião de Acompanhamento Estratégico (RAE)) e a **Categoria**.
3. Informe **Data**, **Início** e **Término** (horário de Brasília).
4. Escolha a **Situação**: Agendado, Realizado, Adiado ou Cancelado.
5. Informe **Local ou link** e a **Pauta**.
6. Em **A que se refere**, ligue o evento, se quiser, a uma ação estratégica (por exemplo, RN-03), a um objetivo ou a um ciclo.
7. Inclua os participantes (veja a seção seguinte) e marque **Confidencial**, se for o caso.
8. Salve: quem cadastra fica registrado como **Organizador**.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/JVSR6TnCYi7ZuqRFh-yNt_image.png" size="62" isUploading="false" width="620" height="387" showCaption="false"}

Figura 50 — Ficha do evento com pauta, participantes e vínculo com o plano

### Observações

- Término **00:00** quer dizer fim do dia: a reunião das 22h às 00h aparece como **22:00–24:00** no dia digitado.
- Um evento acaba no mesmo dia em que começa; para algo de vários dias, cadastre um evento por dia.
- **Realizado** só vale para evento que já começou, inclusive no cadastro.
- A lista de **A que se refere** só oferece o que você pode ler.
- Categoria inativa não pode ser escolhida para evento novo.
- Se o seu login não estiver vinculado a um empregado, o evento não é salvo; peça ao RH o vínculo.

## 7.5 Participantes internos e externos

ID BSC-AGE-05

### Para que serve

Os participantes podem ser empregados da empresa ou pessoas de fora, com os campos do modelo de ata de reunião. O participante externo não vira usuário do sistema: os dados dele servem só para convocar e registrar a reunião.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia).

### Passo a passo

1. No formulário do evento, vá a **Participantes**.
2. Inclua empregados pela busca por nome.
3. Para pessoa de fora, informe **Nome**, **Órgão / empresa**, **E-mail** e **Telefone**.
4. Marque quem é **Obrigatório**.
5. Salve e confira na ficha a lista com a resposta de cada um.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/JVSR6TnCYi7ZuqRFh-yNt_image.png" size="62" isUploading="false" width="620" height="387" showCaption="false"}

Figura 51 — Participantes internos e externos com a resposta de presença

### Observações

- O e-mail e o telefone de externo aparecem só para o organizador, os participantes internos e quem gerencia a agenda; os demais veem nome e órgão com a marca **Contato restrito**.
- Quem edita sem poder ver o contato encontra os campos travados; o contato gravado é mantido.
- O mesmo empregado ou o mesmo e-mail externo não pode entrar duas vezes.
- Externo precisa de nome; o e-mail, se informado, precisa ser válido.
- O histórico nunca guarda e-mail nem telefone de externo: mostra **Contato alterado (externos)** com o nome da pessoa.

## 7.6 Responder à presença

ID BSC-AGE-06

### Para que serve

Cada participante interno confirma ou recusa a presença pela própria ficha do evento ou pela Mesa de trabalho. Não é preciso ter permissão da agenda: basta ser participante.

**Quem usa:** Responsável por ação/área.

### Passo a passo

1. Abra o evento na agenda (ou o convite na Mesa de trabalho).
2. Em **Sua resposta**, clique em **Confirmar presença** ou **Recusar**.
3. Confira a resposta registrada na ficha.

### Observações

- Só participante interno do evento pode responder sobre a própria presença.
- A resposta entra no histórico do evento com antes e depois.
- Quem respondeu e continua na lista mantém a resposta quando o evento é remarcado.

## 7.7 Remarcar, mudar a situação e consultar o histórico

ID BSC-AGE-07

### Para que serve

O evento pode ser remarcado enquanto está agendado ou adiado. Realizado ou cancelado, ele vira registro: data, participantes e pauta não mudam mais, só a situação.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia); Leitor/Auditor.

### Passo a passo

1. Abra o evento e clique em **Editar** para mudar data, horário, participantes ou outros dados.
2. Para mudar a situação, clique em **Mudar situação** e escolha Realizado, Adiado, Cancelado ou Agendado.
3. Clique em **Histórico** para ver cada criação, remarcação, troca de participantes e resposta, com antes e depois.

### Observações

- A situação de um evento já cadastrado só muda por **Mudar situação**.
- Para remarcar um evento realizado ou cancelado, volte antes a situação para **Agendado**, se for o caso.
- Se outra pessoa salvou o evento depois que você o abriu, feche, reabra e refaça a alteração.
- No histórico, o item a que o evento se refere aparece pelo nome só quando é um ciclo; ação e objetivo ficam pelo código interno, porque podem virar sigilosos depois.

## 7.8 Eventos confidenciais

ID BSC-AGE-08

### Para que serve

Um evento confidencial existe só para quem precisa dele: o organizador, os participantes internos, os responsáveis por encaminhamentos do evento e quem gerencia a agenda. Para os demais, ele simplesmente não aparece.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia); Administrador do sistema.

### Passo a passo

1. No formulário do evento, marque **Confidencial**.
2. Salve e confira que a ficha mostra a marca de confidencial.
3. Para revisar quem gerencia a agenda, confira a permissão correspondente em Início › Alçada.

### Observações

- Para quem não pode ver, o evento não aparece no calendário, o endereço direto responde que ele não existe ou não está aberto e o histórico vem vazio.
- "Gerenciar a agenda" só abre os confidenciais quando a permissão tem regra ativa na Alçada; sem regra, ela não abre o confidencial de ninguém.
- Ata, encaminhamentos, envios, documentos e CSV de evento confidencial seguem o mesmo sigilo.
- Se o evento se refere a uma ação ou objetivo sigiloso que você não pode ler, a ficha mostra só **Reservado — não está aberto para você**.
- Evento confidencial nunca vai a WhatsApp, Teams ou Discord, e o e-mail vai sem o arquivo anexado.

## 7.9 Documentos e presença da reunião

ID BSC-AGE-09

### Para que serve

Na ficha do evento, quem gerencia a agenda anexa os documentos discutidos e, depois que a reunião começa, registra quem compareceu.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia).

### Passo a passo

1. Abra o evento na agenda.
2. Em **Documentos**, anexe a apresentação, o relatório ou o que foi discutido.
3. Depois do início da reunião, marque para cada participante **Compareceu** ou **Faltou**.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/JVSR6TnCYi7ZuqRFh-yNt_image.png" size="62" isUploading="false" width="620" height="387" showCaption="false"}

Figura 52 — Ficha do evento com documentos e presença

### Observações

- Os documentos seguem o sigilo do evento: de evento confidencial, só baixa quem vê o evento.
- A presença marcada pelo organizador é diferente da resposta do participante (confirmar ou recusar antes).
- Depois que a ata é finalizada, nenhum documento entra nem sai, e a presença trava.
- Evento cancelado não recebe ata, presença, encaminhamento nem envio.

## 7.10 Ata: salvar, finalizar e enviar, adendo

ID BSC-AGE-10

### Para que serve

A ata registra o que foi discutido e decidido. Depois de finalizada, ela não muda mais e é enviada aos participantes; correções entram como adendo, o que dá à ata valor de prova.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia).

### Passo a passo

1. Abra o evento e vá a **Resumo da reunião**.
2. Escreva o que foi discutido e decidido e clique em **Salvar ata** (quantas vezes quiser).
3. Quando a ata estiver pronta, clique em **Finalizar e enviar** e confirme.
4. Confira a marca **Finalizada por … em …** e a linha **Enviado ao finalizar a ata** em **Envios**.
5. Para corrigir depois, clique em **Registrar adendo** e escreva a correção.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/JVSR6TnCYi7ZuqRFh-yNt_image.png" size="62" isUploading="false" width="620" height="387" showCaption="false"}

Figura 53 — Ata finalizada com adendo e encaminhamentos

### Observações

- Finalizar trava o texto, a presença e os documentos e envia o evento sozinho aos participantes e aos responsáveis por encaminhamento.
- Só dá para finalizar uma reunião que já começou e um texto salvo: se mexeu no texto, salve antes.
- O adendo aparece abaixo do texto original, com data e autor; o original fica intacto.
- Áudio e transcrição automática não fazem parte desta versão: a ata é o texto escrito.
- Cada ata e cada adendo têm o próprio histórico.

## 7.11 Encaminhamentos

ID BSC-AGE-11

### Para que serve

Os encaminhamentos são as tarefas decididas na reunião, cada uma com responsável e prazo. Eles continuam abertos depois da ata finalizada: são o acompanhamento do que foi decidido.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia); Responsável por ação/área.

### Passo a passo

1. Abra o evento e clique em **Novo encaminhamento**.
2. Informe **O que fazer**, o **Responsável** (qualquer empregado, mesmo quem não participou) e o **Prazo**.
3. Se quiser, escolha a **Ação estratégica** a que o encaminhamento serve.
4. Salve: o responsável recebe um aviso e o item entra na Mesa de trabalho dele.
5. O responsável usa **Concluir**, com uma observação, quando terminar.
6. O organizador pode editar, concluir ou **Cancelar** o encaminhamento.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/JVSR6TnCYi7ZuqRFh-yNt_image.png" size="62" isUploading="false" width="620" height="387" showCaption="false"}

Figura 54 — Encaminhamentos com responsável, prazo e situação

### Observações

- O prazo é no dia da reunião ou depois, pelo calendário de Brasília.
- Encaminhamento pendente com prazo vencido aparece como **Atrasado**.
- O responsável por um encaminhamento passa a ler o evento, mesmo confidencial. Ler não é editar.
- Só o responsável ou quem gerencia a agenda conclui ou repassa o encaminhamento.
- O aviso ao responsável segue a preferência dele (sino e, se ligado, e-mail).

## 7.12 Enviar o evento aos participantes por e-mail

ID BSC-AGE-12

### Para que serve

O envio leva aos participantes e aos responsáveis por encaminhamento o registro da reunião: data, local, pauta, resumo com adendos, encaminhamentos e o endereço do evento. O e-mail leva também o arquivo do evento em CSV.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia).

### Passo a passo

1. Com a ata finalizada, abra o evento e clique em **Enviar aos participantes**.
2. Confira a lista de destinatários e o canal de cada um.
3. Observe em vermelho quem ficou sem canal e o motivo.
4. Clique em **Enviar agora**.
5. Confira o resultado na seção **Envios**.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/JVSR6TnCYi7ZuqRFh-yNt_image.png" size="62" isUploading="false" width="620" height="387" showCaption="false"}

Figura 55 — Janela de envio com destinatários e canais

### Observações

- Cada pessoa aparece uma vez, mesmo sendo participante e responsável por encaminhamento.
- Interno com login recebe aviso no sistema e e-mail (conforme a preferência); interno sem login com e-mail cadastrado recebe e-mail; externo recebe e-mail.
- Quem não tem canal (**Sem e-mail cadastrado**, **Sem login e sem e-mail cadastrado**) não impede o envio aos outros.
- Cada pessoa recebe uma mensagem só sua; ninguém vê o endereço dos outros.
- O anexo vai sem e-mail e telefone de externos. Evento confidencial ou arquivo acima de 2 MB vão só com o endereço do evento.
- O envio só é liberado com a ata finalizada; depois, **Enviar agora** reenvia quantas vezes for preciso.

## 7.13 Enviar pelos canais integrados (WhatsApp, Teams, Discord)

ID BSC-AGE-13

### Para que serve

Além do aviso no sistema e do e-mail, o evento pode sair pelo WhatsApp de cada participante interno e pelo canal da área no Microsoft Teams ou no Discord. Esses canais levam só o essencial e o link; quem decide quem vê a ata é a regra de leitura do evento.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia).

### Passo a passo

1. Na janela **Enviar aos participantes**, localize o bloco **Enviar também por**.
2. Marque ou desmarque o WhatsApp e os canais de área ativos (já vêm marcados conforme a categoria do evento).
3. Clique em **Enviar agora**.
4. Confira em **Envios**, canal por canal, quantos foram endereçados e quantos ficaram de fora e por quê.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/EdECacO52wgC9ni9MLC4j_image.png" size="62" isUploading="false" width="620" height="387" showCaption="false"}

Figura 56 — Canais de área (Teams e Discord por unidade) e conta de WhatsApp

### Observações

- O WhatsApp vai a quem confirmou o número e ligou o WhatsApp para o aviso "Envio do evento da agenda" em Preferências de notificação. A mensagem usa o modelo aprovado de envio do evento: assunto, data e link.
- Externo não recebe WhatsApp; fica com o e-mail.
- O canal da área recebe um cartão com assunto, data, horário, quantidade de encaminhamentos e o botão que abre o evento. Nunca recebe o texto da ata, a lista de participantes nem contatos, porque é coletivo.
- Nenhum desses canais leva o arquivo.
- Evento confidencial não vai a nenhum deles.
- Os motivos de ficar de fora (sem número confirmado, WhatsApp desligado para o aviso, evento sigiloso, canal desativado ou removido) aparecem só como contagem, nunca com nomes.
- Enquanto o modelo de mensagem não estiver aprovado na conta de WhatsApp da empresa, a mensagem é recusada e aparece em Notificações › Falhas de entrega.

## 7.14 Envio automático por categoria

ID BSC-AGE-14

### Para que serve

Quem coordena os canais de mensageria define, para cada categoria da agenda, se finalizar a ata também envia o evento sozinho pelo WhatsApp e pelos canais de área escolhidos.

**Quem usa:** Gestor de Desempenho (escritório de estratégia); Administrador do sistema.

### Passo a passo

1. Abra **Alertas e mensagens › Agenda: envio do evento pelos canais integrados**.
2. Para cada categoria (ou na linha **Padrão**, que vale para as categorias sem configuração própria), ligue o envio automático.
3. Escolha o WhatsApp e os canais de área que devem receber.
4. Salve e consulte o **Histórico** de cada alteração.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/EdECacO52wgC9ni9MLC4j_image.png" size="62" isUploading="false" width="620" height="387" showCaption="false"}

Figura 57 — Canais de área disponíveis para o envio automático

### Observações

- Sem o envio automático, finalizar a ata envia só o aviso no sistema e o e-mail; o organizador envia pelos outros canais a partir do evento, com eles pré-marcados.
- Só se escolhe canal de área ativo; um canal desativado depois é pulado e aparece no registro do envio.
- Para corrigir "Escolha só canais de área ativos", reative o canal em Canais de área ou tire-o da lista.

## 7.15 Registro de envios e o que "enviado" quer dizer

ID BSC-AGE-15

### Para que serve

A seção **Envios** da ficha guarda cada envio do evento, para que o organizador saiba quem foi endereçado, por quais canais e o que aconteceu com o arquivo.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia); Leitor/Auditor.

### Passo a passo

1. Abra o evento e vá à seção **Envios**.
2. Confira data, quem enviou (ou **Enviado ao finalizar a ata**), quantos destinatários internos e externos, os canais e o que aconteceu com o arquivo.
3. Abra o histórico do envio, se precisar.
4. Se um e-mail não chegou, consulte **Notificações › Falhas de entrega**.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/vI-4w5ueuWjjTvK-Xr60V_image.png" size="62" isUploading="false" width="620" height="387" showCaption="false"}

Figura 58 — Notificações, onde ficam as falhas de entrega

### Observações

- "Enviado" quer dizer endereçado, não entregue: se o servidor de e-mail recusar depois, a mensagem aparece em Falhas de entrega.
- Se a instalação não tiver servidor de e-mail configurado, a tela avisa que os e-mails só vão para o registro do servidor; os avisos no sistema chegam normalmente.
- Quem ficou sem canal aparece só pelo nome, nunca com e-mail ou telefone.
- O registro diz se o arquivo foi anexado ou se foi só o endereço (evento confidencial, arquivo acima de 2 MB ou arquivo que não pôde ser preparado).

## 7.16 Exportar o evento em CSV

ID BSC-AGE-16

### Para que serve

A exportação gera uma planilha com tudo o que foi registrado na reunião, para arquivo ou para distribuição.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia); Leitor/Auditor.

### Passo a passo

1. Abra o evento.
2. Clique em **Exportar CSV**.
3. Abra o arquivo (nome evento-\<data>-\<assunto>.csv) no Excel ou no LibreOffice.

### Observações

- Disponível para quem lê o evento.
- O arquivo traz em blocos: o evento, os participantes com a presença, a pauta, a ata (com a situação e quem finalizou), os adendos e os encaminhamentos.
- Em português, usa ponto e vírgula e datas dd/mm/aaaa e abre com os acentos já em colunas.
- Célula que começaria como fórmula (=, +, - ou @) sai como texto: o arquivo nunca executa nada.
- E-mail e telefone de externo só saem para quem os vê na ficha; para os demais, **Contato restrito**.

## 7.17 Perfis de acesso na agenda

ID BSC-AGE-17

### Para que serve

A agenda separa quem mantém as categorias, quem cadastra e registra as reuniões e quem só lê ou responde.

**Quem usa:** Administrador do sistema; Diretoria de Estratégia (patrocinador/aprovador).

### Passo a passo

1. Abra Início › Alçada.
2. Localize as permissões da agenda (ler a agenda, gerenciar a agenda, manter as categorias da agenda).
3. Confira os cargos ligados a cada uma e ajuste conforme a estrutura da organização.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/X9ysGv29hbyr4whrYzjRU_image.png" size="62" isUploading="false" width="620" height="387" showCaption="false"}

Figura 59 — Alçada com as permissões da agenda

### Observações

- Diretoria de Estratégia: mantém as categorias, cadastra e edita eventos e vê todos, inclusive os confidenciais.
- Gestor de Desempenho: cadastra e edita eventos e vê todos.
- Analista Operacional: lê a agenda e os eventos abertos, os confidenciais em que é participante, responde à presença, lê ata, encaminhamentos e envios e exporta o CSV.
- Ata, presença, documentos, encaminhamentos e envio são de quem gerencia a agenda.
- Qualquer participante interno responde à própria presença; o responsável por um encaminhamento conclui o próprio encaminhamento e lê o evento dele.

[title]  17. Instalação, backup e restauração
[path] Aplicações/BSC/

O Bússola/BSC pode ser instalado de duas formas: **interna**, num servidor do ambiente da empresa com Docker Compose, ou **em nuvem**, num cluster Kubernetes. As peças instaladas são as mesmas nos dois modos: banco PostgreSQL 16, mensageria, backend, portal web, entrada TLS e o serviço de backup.

Não há aplicativo de loja. Computador, tablet e celular usam o mesmo portal web responsivo, que o navegador permite instalar como aplicativo ("Instalar aplicativo" ou "Adicionar à tela inicial").

Este capítulo é para o Administrador do sistema e a equipe de infraestrutura da empresa.

***

## <font color="#15803D">17.1 Instalação interna (no ambiente da empresa) e em nuvem</font>

ID BSC-INS-01

### <font color="#15803D">Para que serve</font>

Descreve o que é instalado, os pré-requisitos e os comandos de instalação nos dois modos. As peças: **banco** PostgreSQL 16 com dois bancos (mestre, de controle de migração, e o banco de dados da organização); **mensageria** (o produto sobe sem ela, mas avisos e notificações dependem dela); **backend** (aplica as migrações do banco na subida); **portal** web responsivo servido em /portal/; **entrada TLS** (nginx no modo interno ou o Ingress do cluster), único ponto exposto; e o serviço de **backup**.

Recursos mínimos no modo interno, tudo num servidor: 4 vCPU, 8 GB de RAM e 50 GB de disco para banco e anexos, mais o espaço das cópias locais de backup.

**Quem usa:** Administrador do sistema.

### <font color="#15803D">Passo a passo</font>

1. Providencie os pré-requisitos: provedor de identidade compatível com OIDC (por exemplo, Keycloak), nome público com certificado TLS (por exemplo, bussola.exemplo.com.br), destino de backup e liberações de rede.
2. Gere os segredos: senha do banco, RESOURCE\_TENANT\_SECURITY\_KEY (cifra as credenciais guardadas; guarde uma cópia fora do backup) e FINANCE\_PIX\_WEBHOOK\_SECRET.
3. Modo interno: em deploy/compose/bussola, copie .env.example para .env, proteja-o com chmod 600 e preencha todos os valores marcados com REPLACE\_.
4. Modo interno: copie o certificado e a chave para tls/fullchain.pem e tls/privkey.pem, rode docker compose up -d e acompanhe docker compose logs -f backend até aparecer "Started Application".
5. Modo nuvem: confira o que será aplicado com kubectl kustomize k8s/bussola.
6. Modo nuvem: crie no namespace bussola o segredo erp-backend-secret a partir de backend.env, o segredo do backup (a partir de secret.backup.yaml.example) e o segredo TLS bussola-tls; depois aplique o overlay com kubectl -n bussola apply -k k8s/bussola.
7. Modo nuvem: ajuste no overlay as imagens, o host e a classe do Ingress, as variáveis KEYCLOAK\_\* e KAFKA\_BOOTSTRAP\_SERVERS no configmap.backend.yaml e a classe de armazenamento do volume.
8. Confira a primeira subida: abra https\://\<host>/portal/ e verifique o redirecionamento ao provedor de identidade.
9. Depois do login, verifique que **Mapa estratégico**, **Indicadores** e **Dados** abrem para um usuário com os cargos adequados.
10. Provisione a base de leitura com scripts/ops/bsc-leitura/provision-pg.sql, informe TENANT\_READER\_PASS, reinicie o backend e confira que o console SQL lê a visão indicator\_v.
11. Confira o primeiro backup: uma linha com "status":"ok" no log do serviço de backup e o conjunto gravado no destino.

### <font color="#15803D">Observações</font>

- O perfil de segurança da instalação não tem login próprio e recusa subir sem KEYCLOAK\_ISSUER\_URI e KEYCLOAK\_JWK\_URI. O provedor de identidade deve emitir tokens assinados com a reivindicação que identifica o ambiente da organização.
- No modo interno, o banco da organização é criado na primeira subida e o backend cria os esquemas e aplica as migrações. A primeira subida pode levar minutos.
- Os anexos ficam no volume nomeado bussola-attachments, nunca no diretório temporário do contêiner (sumiriam na primeira troca de imagem). O backup copia esse volume.
- A configuração é a mesma nos dois modos: k8s/bussola/application-bussola.yml, montada em /config/.
- O banco não é publicado na rede. Ferramentas de BI usam a base de leitura própria.
- No modo nuvem, o backend.env leva MASTER\_DB\_URL/USER/PASS, BUSSOLA\_TENANT\_ID, TENANT\_DB\_URL/USER/PASS/SCHEMA, TENANT\_READER\_PASS, RESOURCE\_TENANT\_SECURITY\_KEY e FINANCE\_PIX\_WEBHOOK\_SECRET.
- No modo nuvem, o backend roda com uma réplica e estratégia Recreate (volume ReadWriteOnce); o agendamento de backup roda no mesmo nó para montar o volume de anexos só para leitura. O PostgreSQL é o gerenciado da empresa, fora do overlay.
- Liberações de rede: entrada HTTPS no nome público; saída para o provedor de identidade, para os sistemas integrados (SEI, SIAFI, Portal da Transparência, mensageria da empresa) e para o destino do backup. Webhooks de entrada chegam em https\://\<host>/portal/api/integrations/inbound//.
- O ambiente de simulação para treinamento e homologação das integrações não é instalado em produção.

***

## <font color="#15803D">17.2 Backup diário e restauração</font>

ID BSC-INS-02

### <font color="#15803D">Para que serve</font>

O backup gera, toda noite, um **conjunto** com data e hora UTC no nome (por exemplo, bussola-20261009T040000Z/) e o envia ao destino definido pela empresa. O conjunto contém: tenant.dump (banco de dados da organização), master.dump (banco mestre, na instalação dedicada), attachments.tar.gz (anexos: evidências de indicador, de entrega, atas) e SHA256SUMS (somas de conferência, gravado por último).

A restauração é feita num ambiente limpo, com o roteiro bsc-restore.sh, que confere cada arquivo antes de restaurar.

**Quem usa:** Administrador do sistema.

### <font color="#15803D">Passo a passo</font>

1. Defina o destino em BACKUP\_DEST\_KIND: **S3** (armazenamento de objetos compatível; informe endereço, balde, prefixo e chave com PutObject e GetObject) ou **PATH** (diretório montado, como NFS).
2. Confirme o agendamento: no modo interno, o serviço backup usa BACKUP\_CRON (padrão 0 1 \* \* \*) com TZ=America/Sao\_Paulo; no modo nuvem, o CronJob bussola-backup usa timeZone America/Sao\_Paulo. Ambos rodam às 01:00 de Brasília.
3. Configure o alerta: nenhuma linha "status":"ok" nas últimas 26 horas, ou código de saída diferente de 0.
4. Para restaurar, prepare um servidor novo com PostgreSQL 16, os bancos vazios (bussola e bussola\_master) e o usuário da aplicação.
5. Execute o bsc-restore.sh no contêiner da imagem bussola-backup:16, com PGHOST, PGUSER, PGPASSWORD, RESTORE\_TENANT\_DB, RESTORE\_MASTER\_DB e RESTORE\_ATTACHMENTS\_DIR. Com RESTORE\_SOURCE\_KIND=S3 ele baixa o conjunto pelo nome; com PATH, recebe o diretório.
6. Recrie os papéis de leitura com senhas novas, usando scripts/ops/bsc-leitura/provision-pg.sql, e informe a nova senha na configuração.
7. Suba o produto com a **mesma** RESOURCE\_TENANT\_SECURITY\_KEY da origem.
8. Confira: contagens das tabelas-chave iguais às da origem (indicadores, medições, objetivos), uma evidência de indicador abre (prova os anexos), **Dados › Conexões** testa uma conexão com sucesso (prova a chave) e o console SQL lê indicator\_v (prova a base de leitura).

### <font color="#15803D">Observações</font>

- Ficam fora do backup, de propósito, e devem ser guardados à parte com dono nomeado: a chave RESOURCE\_TENANT\_SECURITY\_KEY (num cofre de segredos, fora do destino do backup), os papéis de banco de leitura e de BI (recriados na restauração) e o arquivo .env ou os Secrets do Kubernetes.
- Sem a mesma chave de cifragem, o produto sobe, mas toda credencial gravada (conexões de banco, integrações) deixa de abrir, sem aviso.
- Em servidor compartilhado, o backup leva só os esquemas listados em BACKUP\_TENANT\_SCHEMAS e as respectivas bases de leitura; dados de outros ambientes não vão para o destino.
- Cifragem no destino S3: BACKUP\_S3\_SSE=AES256. Retenção remota: regra de ciclo de vida do balde (S3) ou BACKUP\_DEST\_KEEP=\<n> (PATH).
- Sem TZ, o horário escorrega: o agendador do contêiner usa UTC e "0 1" viraria 22:00 de Brasília. O horário de 01:00 evita disputa com as rotinas noturnas do produto, que começam às 02:00.
- Cada execução grava uma linha JSON no log, com status, código de saída, conjunto, tamanho, soma e destino; o destino nunca leva credencial e o campo de erro diz o passo que falhou.
- Código 3: arquivo corrompido ou que não confere com SHA256SUMS; nada é enviado (no backup) ou tudo é abortado (na restauração). Código 4: destino fora do ar; a cópia fica no disco local, que cresce até o próximo envio bem-sucedido. Código 5: banco de destino com tabelas; a restauração é recusada.
- RESTORE\_FORCE=1 só deve ser usado quando o alvo foi conferido por duas pessoas.
- A restauração usa --no-owner --no-privileges: os objetos passam a pertencer ao usuário que conectou.
- Conjunto sem SHA256SUMS no destino é envio incompleto. Se os anexos estão num armazenamento de objetos, o backup deles é a versão ou a replicação do próprio balde.

***

## <font color="#15803D">17.3 Registrar o teste de restauração</font>

ID BSC-INS-03

### <font color="#15803D">Para que serve</font>

Uma cópia de segurança só vale se a restauração funciona. A empresa deve fazer restaurações reais periódicas num ambiente separado e registrar cada uma, para comprovar que o backup diário é utilizável.

**Quem usa:** Administrador do sistema; Leitor/Auditor.

### <font color="#15803D">Passo a passo</font>

1. Escolha um conjunto recente no destino do backup.
2. Restaure-o num ambiente limpo, seguindo a seção BSC-INS-02.
3. Anote a data, quem executou, o ambiente, o nome do conjunto, o tamanho e a duração.
4. Registre as contagens das tabelas-chave na origem e no destino e confirme que são iguais.
5. Registre a evidência de indicador aberta e a conexão testada em **Dados › Conexões**.
6. Guarde o registro junto à documentação de operação da instalação.

### <font color="#15803D">Observações</font>

- Uma restauração que sobe o produto mas não abre as conexões indica chave de cifragem diferente da origem.
- Banco de dados SQL Server não é a base padrão do produto; quando usado, o equivalente é o backup nativo com CHECKSUM e COMPRESSION, a verificação com RESTORE VERIFYONLY e o envio do arquivo .bak pelo mesmo destino.

[title]  11. Painéis e relatórios
[path] Aplicações/BSC/

Cada perfil acompanha a estratégia por um ângulo diferente: a diretoria quer a visão mensal da empresa, o gestor de desempenho acompanha os indicadores que apura, o escritório de projetos olha a carteira de ações. Os Painéis dão a cada perfil o seu painel. No Bússola/BSC, perfil é o cargo — o mesmo que decide as permissões —, e um painel tem um de três alcances: Pessoal (só seu, a menos que você o compartilhe), Cargo (visto por quem ocupa os cargos do público, depois de publicado) e Organização (visto por todos que acompanham desempenho, depois de publicado).

Cada painel é uma grade de doze colunas onde os widgets são posicionados e dimensionados, com o mouse ou pelo teclado. Os widgets são pintados pelas faixas de desempenho do ciclo, mostram quando o dado foi atualizado e levam, num clique, à tela onde se age. Montar um painel nunca dá acesso a dado: cada widget mostra só o que a pessoa que olha já poderia ver na tela de origem.

Os Relatórios trazem indicadores, objetivos, ações estratégicas e processos mês a mês ou ano a ano, com as mesmas cores e a mesma barra de filtros, e exportam para planilha Excel. As telas ficam no menu lateral, grupo Gestão por indicadores: Painéis e Relatórios. Os exemplos usam o Ciclo Estratégico 2026 — Empresa Exemplo e painéis como o Painel da Diretoria e o Painel do Escritório de Projetos.

***

## <font color="#15803D">11.1 Abrir os painéis e saber qual abre ao entrar</font>

ID BSC-PAI-01

### <font color="#15803D">Para que serve</font>

A tela de Painéis reúne todos os painéis que você pode ver e informa qual deles abre quando você entra no Bússola/BSC, e por quê.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia); Responsável por ação/área; Leitor/Auditor.

### <font color="#15803D">Passo a passo</font>

1. Abra Gestão por indicadores › Painéis.
2. No cartão **Abre quando você entra**, veja qual painel abre e o motivo: **escolhido por você**, **o padrão do seu cargo**, **o padrão da organização** ou **o seu próprio painel**.
3. Percorra os grupos **Meus painéis**, **Compartilhados comigo** (com o nome de quem compartilhou), **Do meu cargo** e **Da organização**.
4. Marque **Mostrar arquivados** para ver os painéis arquivados que você pode restaurar.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/7j9g3bs3mO-U5YbmSavos_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 101 — Lista de painéis com o cartão Abre quando você entra e os quatro grupos.

### <font color="#15803D">Observações</font>

- Quem gerencia painéis vê também os rascunhos nos grupos de cargo e de organização.
- O antigo **Meu painel** do Painel gerencial virou o seu primeiro painel pessoal, com os mesmos itens na mesma ordem.

***

## <font color="#15803D">11.2 Criar um painel</font>

ID BSC-PAI-02

### <font color="#15803D">Para que serve</font>

Cria um painel vazio com o alcance escolhido. Painéis de cargo e de organização nascem em rascunho, invisíveis ao público até a publicação.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia); Responsável por ação/área.

### <font color="#15803D">Passo a passo</font>

1. Em Gestão por indicadores › Painéis, clique em **Novo painel**.
2. Informe o **Nome** (por exemplo, Painel da Diretoria) e, se quiser, a **Descrição**.
3. Em **Para quem**, escolha **Pessoal**, **Cargo** ou **Organização**.
4. Clique em **Criar**: o painel abre vazio.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/7j9g3bs3mO-U5YbmSavos_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 102 — Formulário Novo painel com o alcance.

### <font color="#15803D">Observações</font>

- Quem não gerencia painéis só vê a opção **Pessoal**; **Cargo** e **Organização** são da Diretoria de Estratégia e do Gestor de Desempenho.
- Só quem gerencia painéis cria painel de cargo ou da organização; os demais podem criar um painel pessoal e compartilhá-lo.

***

## <font color="#15803D">11.3 Criar um painel a partir de um modelo</font>

ID BSC-PAI-03

### <font color="#15803D">Para que serve</font>

Os modelos preenchem o painel com widgets já posicionados, que depois podem ser movidos, alterados ou removidos livremente.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia); Responsável por ação/área.

### <font color="#15803D">Passo a passo</font>

1. Em Gestão por indicadores › Painéis, clique em **Novo painel**.
2. Na seção **Começar de um modelo**, escolha o **Modelo**.
3. Se o modelo for **Visão do indicador**, escolha o indicador (por exemplo, Avanço físico da Ponte do Vale).
4. Clique em **Criar** e ajuste os widgets como quiser.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/cm4lStGoRK1O8FA8iL9Y3_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 103 — Painel criado a partir de um modelo.

### <font color="#15803D">Observações</font>

- **Desempenho por unidade**: ciclo consolidado, barras por unidade, lista de situação e rosca por situação.
- **Visão do indicador**: cartão, velocímetro, comparação trimestral, linha com meta e tendência e tabela dos períodos.
- **Planejamento estratégico por nível**: ciclo por nível de desdobramento, períodos por situação e objetivos com atingimento consolidado.
- **Visão executiva**: velocímetro do ciclo, indicadores por situação (piores primeiro) e unidades lado a lado.
- **Escritório de projetos**: progresso das ações, matriz de calor de riscos, ações com mais atividades atrasadas e processos por macroprocesso; só aparece para quem lê a carteira, e os widgets de riscos e processos entram só para quem lê esses módulos.

***

## <font color="#15803D">11.4 Acrescentar widgets</font>

ID BSC-PAI-04

### <font color="#15803D">Para que serve</font>

O widget é o bloco de informação do painel. Ele lê uma fonte de dados do servidor, sempre com o acesso de quem olha, e é desenhado num dos tipos que a fonte suporta.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia); Responsável por ação/área.

### <font color="#15803D">Passo a passo</font>

1. No painel aberto, clique em **Editar**.
2. No cartão **Acrescentar widget**, escolha o **Assunto**: **Indicadores**, **Objetivos**, **O ciclo como um todo**, **Itens clássicos (painel fixado)** ou, conforme seu acesso, Ações e projetos, Riscos, Processos, Planos de ação (5W2H) e Cargas de dados e consultas salvas.
3. Escolha a **Fonte de dados** e como ela é **Desenhada** (só aparecem os tipos que a fonte sabe desenhar).
4. Conforme a fonte, escolha **Indicador**, **Objetivo** e **Ciclo** (vazio usa o ciclo do painel; o do painel vazio usa o ciclo ativo).
5. Se quiser, informe o **Título**.
6. Clique em **Pré-visualizar** para ver o widget com os dados reais.
7. Clique em **Acrescentar**: o widget entra no primeiro lugar livre, com quatro colunas de largura.
8. Clique em **Concluir** para voltar ao modo de leitura.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/cm4lStGoRK1O8FA8iL9Y3_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 104 — Painel em edição com o cartão Acrescentar widget.

### <font color="#15803D">Observações</font>

- Só aparecem os indicadores que você vê na tela de indicadores.
- Os **Itens clássicos** são os quatro itens do antigo painel fixado: Série do indicador, Objetivo, Resumo do ciclo e Alinhamento medido.
- Um painel guarda no máximo 24 widgets.

***

## <font color="#15803D">11.5 Mover, redimensionar e remover widgets</font>

ID BSC-PAI-05

### <font color="#15803D">Para que serve</font>

A grade de doze colunas permite posicionar e dimensionar cada widget com o mouse ou só pelo teclado, sem sobreposição.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia); Responsável por ação/área.

### <font color="#15803D">Passo a passo</font>

1. No painel, clique em **Editar**.
2. Com o mouse, arraste o widget pela alça do canto superior direito; arraste o canto inferior direito para mudar o tamanho.
3. Pelo teclado, use os botões do rodapé: **Mover para a esquerda**, **Mover para a direita**, **Mover para cima**, **Mover para baixo**, **Mais largo**, **Mais estreito**, **Mais alto** e **Mais baixo**.
4. Com o widget em foco (Tab), use as setas para mover e **Shift + setas** para redimensionar.
5. Para tirar um widget, clique em **Remover widget**.
6. Clique em **Concluir**.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/cm4lStGoRK1O8FA8iL9Y3_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 105 — Widgets na grade com os controles de posição e tamanho.

### <font color="#15803D">Observações</font>

- Um widget tem de 1 a 12 colunas de largura e de 1 a 12 linhas de altura.
- Um passo que sairia da grade ou cobriria outro widget não acontece, e a tela avisa "Não cabe aí".
- Se outra pessoa alterar o painel ao mesmo tempo, recarregue e refaça a alteração.

***

## <font color="#15803D">11.6 Alterar um widget</font>

ID BSC-PAI-06

### <font color="#15803D">Para que serve</font>

Um widget do catálogo pode ser reconfigurado a qualquer momento, sem programação.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia); Responsável por ação/área.

### <font color="#15803D">Passo a passo</font>

1. No painel, clique em **Editar**.
2. No widget, clique no lápis (**Alterar o widget**).
3. Troque o tipo de gráfico (entre os que a fonte desenha), o indicador, o agrupamento, o período da comparação, as linhas de meta e de tendência ou a cor da linha.
4. Clique em **Pré-visualizar** e depois em **Salvar**.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/cm4lStGoRK1O8FA8iL9Y3_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 106 — Formulário Alterar o widget.

### <font color="#15803D">Observações</font>

- As alterações de um painel publicado chegam ao público na hora.

***

## <font color="#15803D">11.7 Widgets de indicadores, objetivos e ciclo</font>

ID BSC-PAI-07

### <font color="#15803D">Para que serve</font>

As fontes de dados do desempenho estratégico alimentam cartões, velocímetros, linhas, tabelas, listas de situação, barras e roscas, sempre com as cores das faixas do ciclo.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia); Responsável por ação/área; Leitor/Auditor.

### <font color="#15803D">Passo a passo</font>

1. Para acompanhar um indicador, escolha a fonte **Um indicador ao longo dos períodos** e desenhe como Cartão de indicador, Velocímetro, Linha, Tabela ou Comparação de períodos.
2. Para ver o conjunto, escolha **Os indicadores do ciclo** e desenhe como Tabela, Lista de situação, Barras ou Rosca, agrupando por unidade, objetivo, eixo ou situação.
3. Para objetivos, escolha **Objetivos com o atingimento consolidado** (cartão e velocímetro mostram um objetivo escolhido).
4. Para a visão geral, escolha **O ciclo consolidado (painel gerencial)**.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/cm4lStGoRK1O8FA8iL9Y3_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 107 — Widgets de indicador, barras por unidade e rosca por situação.

### <font color="#15803D">Observações</font>

- Cartão e velocímetro mostram o último período medido: valor, meta e atingimento.
- A linha traz a meta tracejada e a tendência pontilhada — a reta de mínimos quadrados dos últimos seis períodos medidos, sem projetar além do último.
- Agrupado, cada barra é a média do atingimento dos períodos medidos, os mesmos números do Painel gerencial.
- A cor do objetivo é a do mapa estratégico — a pior faixa dos seus períodos —, por isso um objetivo pode ter 95% consolidado em vermelho.
- Na rosca do ciclo, contam-se períodos por situação.

***

## <font color="#15803D">11.8 Comparação de períodos</font>

ID BSC-PAI-08

### <font color="#15803D">Para que serve</font>

O widget de comparação mostra o período atual contra o anterior e contra o mesmo período do ano anterior, com variação e seta de evolução ou regressão conforme o sentido do indicador.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia); Responsável por ação/área.

### <font color="#15803D">Passo a passo</font>

1. Ao acrescentar ou alterar o widget, escolha a fonte **Um indicador ao longo dos períodos** e o desenho **Comparação de períodos**.
2. Escolha **Mês contra mês**, **Trimestre contra trimestre** ou **Ano contra ano**.
3. Leia a variação absoluta e percentual e a seta de **Evolução** ou **Regressão**.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/cm4lStGoRK1O8FA8iL9Y3_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 108 — Widget de comparação de períodos.

### <font color="#15803D">Observações</font>

- O sentido do indicador decide a seta: maior é melhor, menor é melhor (por exemplo, Prazo médio de emissão de licenças ambientais) ou distância até a meta.
- Os valores seguem o tipo de medição: último valor (posição), soma (acumulado) ou média.
- Um lado sem medição aparece como **sem dado**, sem seta — nunca como regressão.
- Período acumulado incompleto aparece como **(parcial)** e não é comparado. Indicador trimestral não tem comparação mensal; indicador semanal deve ser comparado por trimestre ou ano.

***

## <font color="#15803D">11.9 Widgets de ações, riscos e processos</font>

ID BSC-PAI-09

### <font color="#15803D">Para que serve</font>

Os painéis também leem a carteira de ações, o registro de riscos e o catálogo de processos, com os mesmos números das telas de origem.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia); Responsável por ação/área.

### <font color="#15803D">Passo a passo</font>

1. Para a carteira, escolha **Ações e projetos: previsto x realizado (carteira)** e o tipo **Progresso de ações**; em **Ordem**, escolha prioridade (GUT), atividades atrasadas, execução financeira ou código.
2. Para riscos, escolha **Matriz de calor de riscos** e, em **Leitura**, **Risco inerente** ou **Risco residual planejado**.
3. Para processos, escolha **Processos da cadeia de valor por macroprocesso**, em Barras ou Tabela.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/cm4lStGoRK1O8FA8iL9Y3_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 109 — Painel do Escritório de Projetos com progresso de ações e matriz de calor de riscos.

### <font color="#15803D">Observações</font>

- Progresso de ações: código, nome (link para a ficha), situação, barras Física e Financeira, previsto e realizado em reais e atividades atrasadas; até 50 ações; posição de hoje, sem filtro de período.
- Matriz de calor: desenha a matriz padrão ativa com a contagem de riscos ativos por célula e o total, a mesma do mapa de riscos; sem matriz ativa, o widget avisa.
- Processos: cada macroprocesso ativo com os processos ativos e quantos estão em elaboração, em revisão ou validados.
- Estes assuntos só aparecem para quem lê o módulo correspondente.

***

## <font color="#15803D">11.10 Widgets de planos de ação, cargas de dados e consultas salvas</font>

ID BSC-PAI-10

### <font color="#15803D">Para que serve</font>

Estes widgets trazem ao painel os planos de ação 5W2H, a saúde das cargas de dados e o resultado de consultas salvas publicadas para painéis.

**Quem usa:** Gestor de Desempenho (escritório de estratégia); Analista de Integração de Dados.

### <font color="#15803D">Passo a passo</font>

1. Para planos, escolha o assunto **Planos de ação (5W2H)** e a fonte **Planos de ação por situação, com os atrasados**, em Barras, Tabela ou Cartão KPI.
2. Para cargas, escolha **Cargas de dados e consultas salvas** e a fonte **Cargas de dados: última execução, situação e linhas**.
3. Para uma consulta, escolha **Resultado de uma consulta salva (conjunto de dados para painéis)** e a **Consulta salva**.
4. Desenhe a consulta como Tabela, Barras ou Cartão KPI.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/cm4lStGoRK1O8FA8iL9Y3_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 110 — Widgets de planos de ação e de cargas de dados.

### <font color="#15803D">Observações</font>

- Plano atrasado é o plano em execução com ação aberta depois do prazo. O widget segue Unidade, Eixo, Objetivo e Indicador.
- Na tabela de cargas, as que falharam vêm primeiro; o nome leva à página da carga. Nenhum filtro da barra se aplica.
- A consulta salva roda sempre a versão publicada, com as proteções da área de dados (só leitura, 30 segundos, até 1.000 linhas) e registra a execução no monitor. Só entram consultas ativas, de finalidade Conjunto de dados para painéis, com versão publicada.
- Os filtros Período e Unidade chegam à consulta como parâmetros; a consulta aceita uma unidade por vez.
- Dados de outros sistemas chegam aos painéis como indicadores ou por consulta salva sobre a integração.

***

## <font color="#15803D">11.11 Sigilo nos painéis</font>

ID BSC-PAI-11

### <font color="#15803D">Para que serve</font>

Montar ou compartilhar um painel nunca amplia o acesso: cada widget é lido com as permissões de quem olha, e itens sigilosos são protegidos.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia); Responsável por ação/área; Leitor/Auditor.

### <font color="#15803D">Passo a passo</font>

1. Abra o painel e observe os widgets marcados **Widget restrito** — "Sem acesso a este dado".
2. Nos agregados, observe os itens com o nome **Reservado (sigiloso)**.
3. Se precisar do dado, solicite a permissão do assunto ao **Administrador do sistema**.

### <font color="#15803D">Observações</font>

- Um widget sobre um indicador ou objetivo sigiloso aparece como Widget restrito para quem não pode lê-lo, sem nem o título que o autor digitou.
- Nos agregados sem filtro, o indicador sigiloso continua nas contas com o nome reservado; com qualquer filtro aplicado, sai das contas de quem não pode lê-lo.
- Riscos sigilosos, planos sigilosos e ações sigilosas ficam fora de todo número para quem não tem a permissão, e o widget avisa.
- "Sem acesso a este dado" é diferente de "Nada a mostrar ainda" (sem meta aprovada ou medição) e de "Nenhum dado para este recorte."
- A resposta de cada pessoa fica guardada por até um minuto.

***

## <font color="#15803D">11.12 Compartilhar um painel pessoal</font>

ID BSC-PAI-12

### <font color="#15803D">Para que serve</font>

Um painel pessoal pode ser compartilhado com pessoas ou com uma unidade, com permissão de ver ou de editar.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia); Responsável por ação/área.

### <font color="#15803D">Passo a passo</font>

1. Abra o seu painel e clique em **Editar**.
2. No cartão **Compartilhar**, em **Com**, escolha uma pessoa ou uma unidade (por exemplo, EST — Estratégia).
3. Em **Permissão**, escolha **pode ver** ou **pode editar** e clique em **Acrescentar**.
4. Clique em **Salvar compartilhamento**.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/cm4lStGoRK1O8FA8iL9Y3_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 111 — Cartão Compartilhar do painel pessoal.

### <font color="#15803D">Observações</font>

- Unidade = as pessoas lotadas naquela unidade, sem as subordinadas.
- Com **pode editar**, a pessoa acrescenta, move e remove widgets; compartilhar, arquivar e restaurar continuam só com o dono.
- Cada widget continua sendo lido com o acesso de quem recebe.
- Um painel pessoal compartilhado passa a ter histórico.

***

## <font color="#15803D">11.13 Publicar um painel de cargo e torná-lo padrão</font>

ID BSC-PAI-13

### <font color="#15803D">Para que serve</font>

O painel de cargo é publicado para os cargos do seu público e pode ser o padrão deles, abrindo quando essas pessoas entram.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia).

### <font color="#15803D">Passo a passo</font>

1. Abra o painel de cargo e clique em **Editar**.
2. No cartão **Público (cargos)**, marque os cargos que verão o painel e clique em **Salvar público**.
3. No cartão **Publicação**, marque **Padrão dos cargos do público (abre ao entrar)**, se for o caso.
4. Clique em **Publicar**.
5. Se algum cargo já tiver outro painel padrão, leia o aviso e clique em **Confirmar e tirar dele o padrão**.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/cm4lStGoRK1O8FA8iL9Y3_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 112 — Cartões Público (cargos) e Publicação.

### <font color="#15803D">Observações</font>

- Cargo que não acompanha desempenho aparece com o aviso de que não verá o painel; ele precisa antes da permissão de ver o painel de desempenho.
- Há um padrão por cargo; a troca fica no histórico dos dois painéis.
- Para preparar uma mudança grande, use **Duplicar como pessoal** e publique como painel novo, ou **Voltar a rascunho** para tirar o painel do público até a nova publicação.

***

## <font color="#15803D">11.14 Painel da organização</font>

ID BSC-PAI-14

### <font color="#15803D">Para que serve</font>

O painel da organização é visto por todos que acompanham desempenho e pode ser o padrão para quem não tem outro definido.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia).

### <font color="#15803D">Passo a passo</font>

1. Crie o painel com o alcance **Organização** e monte os widgets.
2. No cartão **Publicação**, marque **Padrão da organização**, se for o caso.
3. Clique em **Publicar**.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/cm4lStGoRK1O8FA8iL9Y3_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 113 — Publicação de um painel da organização.

### <font color="#15803D">Observações</font>

- Publicado, aparece em **Da organização** para todos que acompanham desempenho.
- Só um painel da organização é padrão por vez; ele abre para quem não tem painel escolhido nem padrão do cargo.
- Num painel da organização, quem não lê um módulo vê o widget desse módulo como Sem acesso a este dado.

***

## <font color="#15803D">11.15 Escolher o painel que abre ao entrar</font>

ID BSC-PAI-15

### <font color="#15803D">Para que serve</font>

Cada pessoa pode escolher qual painel abre quando entra, sobrepondo os padrões do cargo e da organização.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia); Responsável por ação/área; Leitor/Auditor.

### <font color="#15803D">Passo a passo</font>

1. Abra qualquer painel que você vê.
2. Clique em **Abrir ao entrar**.
3. Para desfazer, clique em **Voltar ao padrão**.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/7j9g3bs3mO-U5YbmSavos_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 114 — Cartão Abre quando você entra.

### <font color="#15803D">Observações</font>

- Ordem de decisão: o painel que você escolheu → o padrão do seu cargo → o padrão da organização → o seu Meu painel.
- Se você perder acesso ao painel escolhido (arquivado, fora do público), a escolha é ignorada e vale o próximo da ordem.
- Quem age por delegação vê os painéis do próprio cargo, não os do cargo de quem delegou.

***

## <font color="#15803D">11.16 Duplicar um painel</font>

ID BSC-PAI-16

### <font color="#15803D">Para que serve</font>

Duplicar cria uma cópia pessoal de um painel, com os mesmos widgets nos mesmos lugares, sem alterar o original.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia); Responsável por ação/área.

### <font color="#15803D">Passo a passo</font>

1. Abra o painel que deseja copiar.
2. Clique em **Duplicar como pessoal**.
3. Ajuste a cópia em **Meus painéis**.

### <font color="#15803D">Observações</font>

- É o caminho para adaptar para você um painel do cargo, ou preparar a nova versão de um painel publicado.

***

## <font color="#15803D">11.17 Histórico, arquivamento e restauração de painéis</font>

ID BSC-PAI-17

### <font color="#15803D">Para que serve</font>

Painéis de cargo, da organização ou pessoais compartilhados guardam o histórico de cada mudança. Painéis podem ser arquivados e restaurados.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia); Responsável por ação/área; Leitor/Auditor.

### <font color="#15803D">Passo a passo</font>

1. Para ver mudanças, clique em **Histórico** no painel: widgets, público, compartilhamentos, publicação e padrão, com antes, depois, autor e data.
2. Para arquivar, clique em **Arquivar** (no cartão **Publicação** ou no painel pessoal).
3. Para restaurar, marque **Mostrar arquivados**, abra o painel e clique em **Restaurar**.

### <font color="#15803D">Observações</font>

- O botão Histórico aparece para quem pode editar o painel; o título de widget sobre item sigiloso aparece como retido.
- Arquivar tira o painel de todas as listas e de padrão; painel pessoal só o dono arquiva.
- O painel pessoal restaurado volta a uso; o de cargo ou da organização volta como rascunho.

***

## <font color="#15803D">11.18 Sinalização dos painéis (estilo dos sinalizadores)</font>

ID BSC-PAI-18

### <font color="#15803D">Para que serve</font>

Define, para toda a organização, o ícone e o alerta exibidos pelos widgets em cada situação de desempenho. As cores não ficam aqui: vêm das faixas de desempenho de cada ciclo.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia); Responsável por ação/área; Leitor/Auditor.

### <font color="#15803D">Passo a passo</font>

1. Em Gestão por indicadores › Painéis, clique no link **Sinalização** para abrir a tela **Sinalização dos painéis**.
2. Para cada situação — **Meta atingida**, **Em risco**, **Meta não atingida**, **Não medido**, **Sem meta**, **Atualização atrasada** e **Falha de apuração** —, escolha o **Ícone**.
3. Marque **Mostrar o alerta** para que os widgets exibam um selo quando a situação ocorrer.
4. Clique em **Salvar**.
5. Use **Histórico** para ver o antes e o depois de cada alteração.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/fX4wFOkVRqGZ8_Ooc-Uf4_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 115 — Sinalização dos painéis: ícone e alerta por situação.

### <font color="#15803D">Observações</font>

- Todos que acompanham desempenho veem a tela; só quem gerencia painéis altera.
- Os widgets desenham a nova sinalização na próxima recarga.
- Um widget nunca escolhe cor própria: ele e a grade de desempenho pintam o mesmo valor da mesma cor.
- Atualização atrasada = período encerrado sem valor além do prazo de apuração. Falha de apuração depende do registro de execuções das apurações automáticas.

***

## <font color="#15803D">11.19 Atualização dos dados: o carimbo e a recarga automática</font>

ID BSC-PAI-19

### <font color="#15803D">Para que serve</font>

Cada widget informa quando o dado por trás dele foi registrado, e o painel se recarrega sozinho enquanto está visível.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia); Responsável por ação/área; Leitor/Auditor.

### <font color="#15803D">Passo a passo</font>

1. Leia, no rodapé de cada widget, **Atualizado em**: data e hora do valor mais novo (apuração automática, carga ou lançamento).
2. Para mudar o intervalo de recarga, clique em **Editar** e ajuste o campo de atualização no cartão **Painel**.
3. Mantenha a aba visível para que o painel se recarregue no intervalo definido.

### <font color="#15803D">Observações</font>

- Padrão de 5 minutos, mínimo de 60 segundos. Com a aba em segundo plano, a recarga pausa.
- O dado novo chega pelas apurações e cargas programadas; não há transmissão contínua.
- O servidor guarda cada resposta por até um minuto para cada pessoa.

***

## <font color="#15803D">11.20 Detalhar: do widget para a tela de origem</font>

ID BSC-PAI-20

### <font color="#15803D">Para que serve</font>

Os widgets levam, num clique, à tela onde se age sobre o dado (drill-down).

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia); Responsável por ação/área; Leitor/Auditor.

### <font color="#15803D">Passo a passo</font>

1. Clique num **ponto da linha** ou **período da tabela** para abrir o indicador naquele período.
2. Clique na **barra de uma unidade** para abrir a grade de desempenho filtrada pela unidade; use **Mostrar todas as unidades** para tirar o filtro.
3. Clique num **objetivo** para abrir a ficha do objetivo, ou numa **ação** para abrir a ficha da ação.
4. Clique numa **célula da matriz de calor** para abrir o Registro de riscos filtrado por matriz, leitura, probabilidade e impacto.
5. Clique num **macroprocesso** para abrir a cadeia de valor.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/cm4lStGoRK1O8FA8iL9Y3_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 116 — Widgets com links para as telas de origem.

### <font color="#15803D">Observações</font>

- O clique só é oferecido a quem pode abrir a tela de destino; para os demais, o nome aparece como texto.
- Com várias unidades no recorte, a célula da matriz de calor não é link, porque o registro filtra uma unidade só.

***

## <font color="#15803D">11.21 Filtrar o painel: a barra de filtros</font>

ID BSC-PAI-21

### <font color="#15803D">Para que serve</font>

A barra de filtros recorta o painel por período, unidade, programa, subprograma, eixo, objetivo e indicador, além de tipo de ação, ação/projeto e processo para quem lê esses módulos.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia); Responsável por ação/área; Leitor/Auditor.

### <font color="#15803D">Passo a passo</font>

1. No painel, use a barra abaixo do título (no celular, toque em **Filtros**).
2. Em **Período**, escolha **Ciclo inteiro**, **Mês**, **Trimestre**, **Ano** ou **Intervalo de datas**.
3. Abra **Unidade**, **Programa**, **Subprograma**, **Eixo**, **Objetivo** ou **Indicador** e marque um ou mais valores.
4. Escolhida uma unidade, marque **Com subunidades** para incluir as unidades abaixo dela.
5. Se tiver acesso, use **Tipo de ação**, **Ação/projeto** e **Processo**.
6. Leia, no rodapé de cada widget, os filtros que não se aplicam a ele.
7. Clique em **Limpar filtros** para voltar ao recorte padrão.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/cm4lStGoRK1O8FA8iL9Y3_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 117 — Barra de filtros do painel.

### <font color="#15803D">Observações</font>

- Valores dentro de um filtro somam (ou); filtros diferentes se cruzam (e). As listas se encadeiam (por exemplo, PROROD limita Subprograma a Rodovia Norte e Ponte do Vale).
- Mês, trimestre e ano correntes são calculados pelo servidor. Um período entra no recorte pelo dia em que termina.
- A unidade de um indicador é a unidade do objetivo a que ele pertence.
- O widget diz "Não se aplica a este widget: …" em vez de fingir que filtrou. Os itens clássicos não seguem a barra.
- Recorte que não deixa nada mostra "Nenhum dado para este recorte."

***

## <font color="#15803D">11.22 Compartilhar o recorte e gravar o recorte padrão</font>

ID BSC-PAI-22

### <font color="#15803D">Para que serve</font>

O recorte fica no endereço da página e pode ser enviado a outras pessoas. Quem edita o painel pode gravar um recorte padrão.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia); Responsável por ação/área.

### <font color="#15803D">Passo a passo</font>

1. Aplique os filtros desejados.
2. Copie o endereço da página e envie-o; quem abrir com acesso ao painel vê o mesmo recorte.
3. Para gravar o recorte como padrão do painel, clique em **Gravar como padrão**.
4. Para apagar o recorte gravado, clique em **Tirar o padrão**.

### <font color="#15803D">Observações</font>

- Valor de filtro que a pessoa não pode ver é ignorado com o aviso "Um filtro foi ignorado…" e aparece como **Valor indisponível**.
- Quem abrir sem filtros no endereço começa no recorte padrão ("Este é o recorte padrão do painel.").
- Em painéis com histórico, a gravação do padrão fica registrada.

***

## <font color="#15803D">11.23 Relatórios por período: abrir, escolher a visão e filtrar</font>

ID BSC-PAI-23

### <font color="#15803D">Para que serve</font>

Os relatórios trazem indicadores, objetivos, ações estratégicas e processos mês a mês ou ano a ano. O catálogo lista só o que você pode abrir.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia); Responsável por ação/área; Leitor/Auditor.

### <font color="#15803D">Passo a passo</font>

1. Abra Gestão por indicadores › Relatórios e escolha o relatório no catálogo: **Indicadores por período**, **Objetivos por período**, **Ações estratégicas**, **Execução das ações por período** ou **Processos por período**.
2. Em **Visão**, escolha **Mensal** (os doze meses de um **Ano**) ou **Anual** (de um ano a outro, até dez anos).
3. Use a barra de filtros com os filtros que o relatório segue.
4. Copie o endereço para outra pessoa abrir o mesmo relatório.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/UOtjBWdir4ilthKa18fxo_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 118 — Catálogo de relatórios do Bússola/BSC.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/3qkbOkwH_oNvKEHEylbJc_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 119 — Relatório aberto com visão, filtros e tabela.

### <font color="#15803D">Observações</font>

- Cada relatório exige, além da permissão de relatórios, o acesso ao assunto dele.
- O relatório lê o ciclo ativo, cujo nome aparece abaixo da tabela. O período da barra não se aplica: o período do relatório são as colunas.
- Os relatórios não são recortados pela empresa escolhida no topo: a estratégia é da organização.

***

## <font color="#15803D">11.24 Ler os relatórios de indicadores e objetivos</font>

ID BSC-PAI-24

### <font color="#15803D">Para que serve</font>

Cada célula mostra meta, realizado e percentual atingido na cor da faixa de desempenho do ciclo, com regras claras para períodos sem dado.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia); Responsável por ação/área; Leitor/Auditor.

### <font color="#15803D">Passo a passo</font>

1. Leia uma linha por indicador (com unidade de medida e objetivo) e, em cada coluna, **Meta**, **Realizado** e **% atingido**.
2. Consulte a **Legenda** para as faixas de cor.
3. No relatório de objetivos, leia o **% atingido** consolidado de cada coluna.
4. Em **Indicadores por período**, clique no nome do indicador para abrir o gráfico do histórico com meta e linha de tendência.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/3qkbOkwH_oNvKEHEylbJc_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 120 — Relatório de indicadores por período com as cores das faixas.

### <font color="#15803D">Observações</font>

- Um período entra na coluna do mês em que termina; um indicador trimestral só tem célula no mês que fecha o trimestre (os outros mostram —).
- Célula sem número nunca é zero: **sem dado** é período encerrado sem valor; **a apurar** é período não encerrado.
- Na visão anual, o ano soma, faz a média ou pega o último valor conforme a agregação do indicador, sobre os períodos que já têm valor.
- O objetivo numa coluna é a média do atingimento dos indicadores com valor nela.
- Indicador ou objetivo sigiloso que você não pode ler não aparece no relatório nem entra nas médias.

***

## <font color="#15803D">11.25 Relatórios de ações estratégicas e de processos</font>

ID BSC-PAI-25

### <font color="#15803D">Para que serve</font>

Os relatórios de ações mostram a posição e a execução da carteira por período; o de processos mostra a versão vigente e as validações de cada processo.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia); Responsável por ação/área; Leitor/Auditor.

### <font color="#15803D">Passo a passo</font>

1. Em **Ações estratégicas**, leia a posição de hoje de cada ação: **Previsto**, **Realizado**, **% financeiro** e **% físico**.
2. Em **Execução das ações por período**, leia cada ação seguida das entregas (com o código da EAP), mês a mês ou ano a ano.
3. Em **Processos por período**, leia, por processo ativo, a **Versão vigente** e quantas versões foram **Validadas** em cada coluna.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/3qkbOkwH_oNvKEHEylbJc_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 121 — Relatório de execução das ações por período.

### <font color="#15803D">Observações</font>

- Previsto é o orçamento do período (da linha de base vigente ou, sem ela, do plano atual); Realizado soma as linhas de execução datadas no período; % físico é o acumulado ao fim da coluna.
- Coluna com orçamento e sem execução mostra realizado 0; coluna não iniciada fica **a apurar**; sem nada previsto ou executado mostra —.
- O relatório conta pela data da execução, não pelo dia do registro. O % físico que vem só das atividades existe apenas para hoje.
- Ação sigilosa só aparece para o gerente dela e para quem gerencia ações.
- O catálogo de processos não liga processo a indicador, por isso o relatório de processos não traz atingimento.

***

## <font color="#15803D">11.26 Exportar relatório para planilha Excel</font>

ID BSC-PAI-26

### <font color="#15803D">Para que serve</font>

O relatório é exportado pelo servidor com a mesma tabela da tela, números somáveis, as mesmas cores e uma aba que documenta o recorte.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia); Responsável por ação/área; Leitor/Auditor.

### <font color="#15803D">Passo a passo</font>

1. Abra o relatório e aplique a visão e os filtros.
2. Clique em exportar para Excel.
3. Abra o arquivo e confira a aba **Filtros**: relatório, visão, período, ciclo, filtros com os nomes, filtros ignorados, legenda das faixas, quem gerou e data e hora.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/3qkbOkwH_oNvKEHEylbJc_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 122 — Relatório com a opção de exportação para Excel.

### <font color="#15803D">Observações</font>

- Os números saem como números e as células com as cores das faixas.
- Texto que começa com =, +, -, @, tabulação ou quebra de linha sai como texto, nunca como fórmula.
- Acima de 10.000 linhas, o arquivo traz só as primeiras e a tela avisa.
- Valor de filtro que você não pode ver é ignorado e não aparece na aba Filtros.

***

## <font color="#15803D">11.27 Exportar o painel para planilha Excel</font>

ID BSC-PAI-27

### <font color="#15803D">Para que serve</font>

O painel é exportado com os dados de cada widget no recorte da tela, uma aba por widget e abas de controle.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia); Responsável por ação/área; Leitor/Auditor.

### <font color="#15803D">Passo a passo</font>

1. Abra o painel e aplique os filtros.
2. Clique em **Exportar** (ao lado de **Editar**) e escolha o Excel.
3. No arquivo, confira uma aba por widget, a aba **Painel** (widgets na ordem, tipo, situação da exportação e carimbo **Atualizado em**) e a aba **Filtros**.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/cm4lStGoRK1O8FA8iL9Y3_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 123 — Botão Exportar do painel.

### <font color="#15803D">Observações</font>

- O botão some enquanto você edita a grade.
- Os nomes das abas usam o título do widget (até 31 caracteres; repetidos ganham "(2)").
- Widget sem acesso sai como "Widget restrito — Sem acesso a este dado" e numa aba "Sem acesso N", sem título nem números; widget com falha sai numa aba "Erro N"; item clássico aparece como "Não exportado".
- Exportar nunca mostra mais que a tela.

***

## <font color="#15803D">11.28 Baixar imagem do gráfico e imprimir o painel em PDF</font>

ID BSC-PAI-28

### <font color="#15803D">Para que serve</font>

Cada gráfico pode ser baixado como imagem para slides, e o painel inteiro pode ser impresso ou salvo em PDF pelo navegador.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia); Responsável por ação/área; Leitor/Auditor.

### <font color="#15803D">Passo a passo</font>

1. No widget de gráfico, clique em **Baixar imagem** (abaixo do carimbo) para gerar um PNG com título, recorte e carimbo.
2. Para o PDF, clique em **Exportar** e escolha o PDF.
3. Se aparecer **Nem todo widget está pronto**, clique em **Tentar de novo** ou **Imprimir assim mesmo**.
4. Na impressão do navegador, escolha **Salvar como PDF** e, se as cores não aparecerem, marque **Gráficos de fundo**.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/cm4lStGoRK1O8FA8iL9Y3_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 124 — Painel com Baixar imagem e Exportar.

### <font color="#15803D">Observações</font>

- A imagem existe para cartões, velocímetros, linhas, barras, roscas e comparações com dado; tabelas e listas vão no Excel. A resolução é dobrada para slides.
- Antes de imprimir, o sistema espera os widgets carregarem (até 10 segundos) e pausa a recarga; widget não pronto sai com a mensagem, nunca em branco.
- A folha sai em A4 deitado, sem menu, filtros nem botões, com cabeçalho (nome, recorte, data e hora, quem imprimiu), widgets em duas colunas e sem cortes entre páginas.
- Se o navegador não converter o gráfico em imagem, use outro navegador ou o PDF.

***

## <font color="#15803D">11.29 Painéis no celular</font>

ID BSC-PAI-29

### <font color="#15803D">Para que serve</font>

Os painéis funcionam em qualquer largura de tela, com os widgets reorganizados numa única coluna.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia); Responsável por ação/área; Leitor/Auditor.

### <font color="#15803D">Passo a passo</font>

1. Abra Gestão por indicadores › Painéis no celular e escolha o painel.
2. Role a coluna de widgets, na ordem de leitura da grade (de cima para baixo e da esquerda para a direita).
3. Toque em **Filtros** para abrir a barra de filtros recolhida (o botão mostra quantos filtros estão em uso).
4. Para editar, use os botões de posição e tamanho do rodapé de cada widget.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/hMo62IlGw0sabCPzFzF9J_image.png" size="21" isUploading="false" width="208" height="451" darkWidth="208" darkHeight="451" showCaption="false"}

Figura 125 — Painel aberto no celular, com os widgets em uma coluna.

### <font color="#15803D">Observações</font>

- O arraste com o mouse aparece a partir do tablet; a edição por botões e teclado funciona em qualquer largura.

[title] Glossário
[path] Aplicações/BSC/

| <font color="#15803D">**Termo**</font> | <font color="#15803D">**Definição**</font>                                                                                                                                                                                                                   |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Agenda estratégica**                 | Calendário que reúne as reuniões e eventos de acompanhamento da estratégia, cada um na cor da sua categoria, com pauta, participantes, ata e encaminhamentos.                                                                                                |
| **Agrupador**                          | Item do escopo de uma ação estratégica que organiza entregas (um lote, uma fase). Não tem valor próprio: soma as entregas abaixo dele.                                                                                                                       |
| **Alertas e mensagens**                | Tela que define, por tipo de registro do Bússola/BSC e por família de aviso, os canais (sino, e-mail, WhatsApp, push, canal da área) e os destinatários dos alertas.                                                                                         |
| **Alçada**                             | Regra de autorização que define qual cargo pode executar uma operação, opcionalmente com teto de valor e restrita a uma unidade. Operação sem nenhuma regra ativa fica liberada a qualquer pessoa autenticada.                                               |
| **Análise SWOT**                       | Diagnóstico de ambiente de um setor em quatro quadrantes: forças, fraquezas, oportunidades e ameaças. Só fraquezas e ameaças originam riscos.                                                                                                                |
| **Apetite a risco**                    | Limite de exposição que a empresa aceita. Na matriz de risco, cada faixa é marcada como dentro ou fora do apetite; risco fora do apetite é prioridade de tratamento.                                                                                         |
| **Apuração**                           | Registro do valor realizado de um indicador num período. Pode ficar em andamento (estimativa) ou ser congelada como oficial; só a apuração oficial dispara o aviso de desvio.                                                                                |
| **Atingimento**                        | Percentual que expressa quanto do resultado esperado foi alcançado, calculado a partir da meta e do realizado e respeitando a polaridade do indicador.                                                                                                       |
| **Ação estratégica**                   | Projeto da carteira da empresa (obra, estudo, projeto de tecnologia) com código, escopo, cronograma, orçamento e os objetivos do plano que atende. Exemplo: RN-03 Duplicação da Rodovia Norte — trecho 3. Não confundir com a ação de um plano de ação 5W2H. |
| **Cadeia de valor**                    | Infográfico que organiza os processos da empresa por tipo (gestão, finalísticos e suporte) e macroprocesso, calculado a partir do catálogo de processos.                                                                                                     |
| **Canal de área**                      | Canal compartilhado do Microsoft Teams ou do Discord ligado a uma unidade (ou à organização inteira) para receber os avisos do Bússola/BSC daquela área.                                                                                                     |
| **Carga de dados**                     | Rotina que traz dados de outro sistema para a base de leitura do Bússola/BSC, com colunas definidas e histórico de execuções.                                                                                                                                |
| **Ciclo estratégico**                  | Versão do plano estratégico para um período, com identidade (missão, visão, valores), perspectivas, objetivos e régua de desempenho. Exemplo: Ciclo Estratégico 2026 — Empresa Exemplo.                                                                      |
| **Conector**                           | Configuração que diz quando e para quê o Bússola/BSC usa uma integração: por exemplo, enviar uma mensagem quando o atingimento cair abaixo de um limite, ou capturar dados para um indicador.                                                                |
| **Console SQL**                        | Tela em que o analista escreve consultas de leitura sobre a base de leitura do Bússola/BSC e vê o resultado na hora, sem dados de pessoas nem registros sigilosos.                                                                                           |
| **Consulta salva**                     | Consulta SQL guardada com versões e parâmetros, reutilizável na apuração de indicadores e em cargas de dados.                                                                                                                                                |
| **Cronograma**                         | Distribuição no tempo das entregas, atividades e subtarefas de uma ação estratégica, gerada a partir do escopo e exibida também em gráfico de Gantt.                                                                                                         |
| **De-Para**                            | Tabela de tradução que diz qual coluna do dado capturado de outro sistema vai para qual campo de um objeto do Bússola/BSC.                                                                                                                                   |
| **Delegação**                          | Registro que permite a um substituto exercer, num período, a alçada de um cargo de origem, até o limite desse cargo, com justificativa obrigatória.                                                                                                          |
| **Encaminhamento**                     | Providência decidida numa reunião da agenda estratégica, com responsável e prazo, acompanhada na Mesa de trabalho.                                                                                                                                           |
| **Entrega**                            | Item do escopo de uma ação estratégica que representa o que de fato se produz, com valor previsto, período, unidade e responsável.                                                                                                                           |
| **Evidência**                          | Arquivo ou registro que comprova a execução de uma entrega ou de um tratamento de risco.                                                                                                                                                                     |
| **Falhas de envio**                    | Tela que lista as notificações não entregues (e-mail, WhatsApp, Teams, Discord, push), com o motivo, para conferência e reprocessamento.                                                                                                                     |
| **Família de aviso**                   | Grupo de alertas do Bússola/BSC com o mesmo gatilho: registro novo, atraso, comentário ou mudança (ouvintes).                                                                                                                                                |
| **Farol**                              | Cor que sinaliza o desempenho de um indicador ou objetivo (verde, amarelo, vermelho ou sem meta), definida pela régua de desempenho do ciclo. Também chamado de semáforo.                                                                                    |
| **Hub de integrações**                 | Lugar único em que a organização cadastra as ligações do Bússola/BSC com outros sistemas, com credenciais cifradas e destinos aprovados na lista de saída.                                                                                                   |
| **Indicador**                          | Medida que acompanha um objetivo estratégico, com fórmula, unidade, polaridade, periodicidade, linha de base, metas e apurações.                                                                                                                             |
| **Indicador importado**                | Indicador cujos valores chegam de um sistema externo por integração, identificado pelo código da série naquele sistema.                                                                                                                                      |
| **Integração**                         | Cadastro que diz com quem e com que credencial o Bússola/BSC fala: SEI, SIAFI, Portal da Transparência, banco de dados, arquivo, Microsoft Teams, Discord, WhatsApp e outros.                                                                                |
| **Linha de base (ação estratégica)**   | Foto aprovada do escopo, do cronograma e do financeiro de uma ação estratégica, congelada ao iniciá-la. Nova linha de base só nasce de uma solicitação de mudança aprovada.                                                                                  |
| **Linha de base (indicador)**          | Valor de partida de um indicador e a data correspondente, usados para medir quanto se avançou desde o início do plano.                                                                                                                                       |
| **Lista de saída**                     | Relação de servidores, protocolos e portas que as integrações podem acessar, mantida pelo administrador do sistema.                                                                                                                                          |
| **Mapa de riscos**                     | Matriz de calor que mostra a exposição dos riscos por probabilidade e impacto, nas visões inerente e residual planejado.                                                                                                                                     |
| **Mapa estratégico**                   | Representação gráfica do plano: uma faixa por perspectiva, com os objetivos, seus faróis e as ligações de desdobramento entre eles.                                                                                                                          |
| **Matriz de risco**                    | Régua de avaliação de riscos, com escalas de probabilidade e impacto, pesos e faixas de criticidade (por exemplo, Baixo, Médio, Alto, Extremo).                                                                                                              |
| **Matriz GUT**                         | Método de priorização que dá notas de 1 a 5 para Gravidade, Urgência e Tendência; o produto das três é a prioridade GUT, de 1 a 125.                                                                                                                         |
| **Mensagem institucional**             | Modelo de texto enviado em cada tipo de aviso, por idioma, com campos automáticos e variações por canal.                                                                                                                                                     |
| **Mesa de trabalho**                   | Tela pessoal que reúne tudo o que está com a pessoa — indicador a apurar, atividade, ação de plano, encaminhamento, reunião, tratamento de risco — agrupado por prazo.                                                                                       |
| **Meta**                               | Valor esperado de um indicador numa janela da linha do tempo, com faixa de tolerância e aprovação.                                                                                                                                                           |
| **Modelo aprovado de WhatsApp**        | Modelo de mensagem (template) aprovado na plataforma do WhatsApp, obrigatório para a empresa iniciar uma conversa; o texto do Bússola/BSC preenche os espaços numerados dele.                                                                                |
| **Modelo de plano de riscos**          | Conjunto de riscos recorrentes guardado para ser aplicado por cópia a um objetivo, eixo ou programa.                                                                                                                                                         |
| **Objetivo estratégico**               | Resultado que a empresa quer alcançar no ciclo, ligado a uma perspectiva, medido por indicadores e desdobrado em outros objetivos com peso.                                                                                                                  |
| **Ocorrência de risco**                | Registro de que um risco efetivamente aconteceu, com data e descrição, que pode originar um tratamento corretivo.                                                                                                                                            |
| **Painel**                             | Grade configurável de widgets sobre indicadores, objetivos e ações, com alcance pessoal, por cargo ou da organização, e barra de filtros.                                                                                                                    |
| **Painel de desempenho**               | Grade que cruza, para cada indicador e período, a meta e o realizado, com variação, atingimento e farol.                                                                                                                                                     |
| **Perfil de acesso do BSC**            | Conjunto de itens de menu do Bússola/BSC concedido a pessoas específicas, além do que o cargo já dá. Só soma acesso, nunca retira.                                                                                                                           |
| **Perspectiva**                        | Grande dimensão do plano estratégico que agrupa objetivos, como Clientes e sociedade, Resultados financeiros, Processos internos e Aprendizado e crescimento.                                                                                                |
| **Plano de ação (5W2H)**               | Conjunto de ações que responde a um indicador fora da meta, cada uma descrita por o quê, por quê, onde, quando, quem, como e quanto.                                                                                                                         |
| **Polaridade**                         | Sentido em que o resultado de um indicador é bom: maior é melhor, menor é melhor, no alvo é melhor ou estabilizar.                                                                                                                                           |
| **Preferências de notificação**        | Tela em que cada pessoa escolhe, por tipo de aviso, os canais pessoais que recebe: sistema (sino), e-mail, WhatsApp e push.                                                                                                                                  |
| **Processo**                           | Item do catálogo de processos da empresa, com versões que passam por elaboração, revisão e validação; há sempre uma única versão vigente.                                                                                                                    |
| **Programa**                           | Agrupamento de ações estratégicas e objetivos por tema, com subprogramas. Exemplos: PROROD, PROTER, PROGOV.                                                                                                                                                  |
| **Push**                               | Aviso exibido na tela do celular ou do computador, mesmo com o Bússola/BSC fechado, para quem o ativou no aparelho.                                                                                                                                          |
| **Recifragem**                         | Operação que reabre cada segredo guardado com a chave que o cifrou e o cifra de novo com a chave ativa.                                                                                                                                                      |
| **Registro de riscos**                 | Lista dos riscos corporativos da empresa, com evento, causas, consequências, natureza, responsável, vínculos e avaliações.                                                                                                                                   |
| **Registro sigiloso**                  | Indicador, objetivo, plano, ação ou risco marcado como reservado: o nome aparece só para quem tem permissão, e os avisos dele saem apenas no sino de quem pode vê-lo.                                                                                        |
| **Risco inerente**                     | Nível do risco sem nenhuma ação gerencial, calculado pela probabilidade e pelo impacto na matriz de risco.                                                                                                                                                   |
| **Risco residual planejado**           | Nível em que a área espera que o risco fique depois do tratamento planejado; é a meta de redução assumida pela área.                                                                                                                                         |
| **Régua de desempenho**                | Critério do ciclo que decide a cor do farol: pela tolerância de cada meta ou pelo percentual de atingimento.                                                                                                                                                 |
| **Seguir (registro)**                  | Ação de acompanhar um indicador, objetivo, plano, ação estratégica ou entrega para receber os avisos de mudança, comentário e atraso dele.                                                                                                                   |
| **Sino**                               | Canal de notificações dentro do portal, no canto superior direito, com contador de não lidas.                                                                                                                                                                |
| **Solicitação de mudança**             | Pedido formal de alteração do plano de uma ação estratégica que, aprovado, gera uma nova linha de base.                                                                                                                                                      |
| **Tratamento de risco**                | Ação definida para reduzir um risco, com responsável, área e prazo, acompanhada pelo lançamento de andamento e evidências.                                                                                                                                   |
| **Trilha de auditoria**                | Registro automático de criações, edições e exclusões de cadastros sensíveis, com autor, data e o antes e o depois.                                                                                                                                           |
| **Usuário local do BSC**               | Pessoa cadastrada diretamente no Bússola/BSC, com nome, e-mail, login e unidade, para receber perfis de acesso quando ainda não existe no cadastro corporativo.                                                                                              |
| **Widget**                             | Componente de um painel, como cartão de indicador, velocímetro, gráfico de linha, barras, rosca, tabela ou lista de situação.                                                                                                                                |


[title]  14. Mensageria e notificações
[path] Aplicações/BSC/

O Bússola/BSC avisa as pessoas sobre o que acontece na estratégia — registro novo, atraso, comentário, mudança em item seguido, desvio de meta — por vários canais: o sino do portal, o e-mail, o WhatsApp pessoal, o push no celular e no computador, e os canais compartilhados de cada área no Microsoft Teams e no Discord.

A configuração tem três camadas. A coordenação decide, em **Alertas e mensagens**, por quais canais e para quem cada família de aviso sai, e escreve o texto em **Mensagens institucionais**. Quem mantém as integrações cadastra os webhooks do Teams e do Discord e a conta de WhatsApp da empresa no hub de integrações, e a coordenação liga cada canal à sua unidade em **Canais de área**. Cada pessoa, por fim, escolhe o que quer receber em **Preferências de notificação**.

Em todo canal valem as mesmas garantias: registro sigiloso nunca sai por e-mail, WhatsApp ou canal compartilhado; ninguém é mencionado nos canais; quem agiu não recebe o aviso da própria ação; e o que não pôde ser entregue aparece em **Falhas de envio**.

***

## <font color="#15803D">14.1 Acompanhar as notificações no sino</font>

ID BSC-MSG-01

### <font color="#15803D">Para que serve</font>

O sino, no canto superior direito do portal, é o canal de avisos dentro do sistema. Ele mostra as notificações mais recentes geradas pelo Bússola/BSC — registro novo, atraso, comentário, mudança em item que você segue, desvio de meta de indicador — e um contador com as que você ainda não leu.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia); Responsável por ação/área; Analista de Integração de Dados; Leitor/Auditor; Administrador do sistema.

### <font color="#15803D">Passo a passo</font>

1. Localize o **sino** ao lado do seu avatar, no canto superior direito. O número sobre ele é a quantidade de notificações não lidas.
2. Clique no sino para abrir a lista das notificações mais recentes.
3. Clique numa notificação para lê-la. Ela sai do contador de não lidas e continua no histórico.
4. Quando aparecer o link **Abrir o registro relacionado**, clique nele para ir direto à ficha do registro (por exemplo, a ficha do indicador ou da ação estratégica).
5. Use **Marcar todas como lidas** no topo da lista para zerar o contador de uma vez.
6. Clique em **Ver todas as notificações**, no rodapé do sino, para abrir a tela completa de notificações.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/vI-4w5ueuWjjTvK-Xr60V_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 161 — Notificações recebidas pelo usuário, com contador de não lidas

### <font color="#15803D">Observações</font>

- Nem todo aviso traz o link para o registro. Quando ele não aparece, leia o texto do aviso, que nomeia o registro, e abra a tela correspondente pelo menu.
- As cópias enviadas por WhatsApp e por push não aparecem no sino: cada aviso aparece uma vez só e não conta em dobro nas não lidas.

***

## <font color="#15803D">14.2 Procurar um aviso antigo na tela Notificações</font>

ID BSC-MSG-02

### <font color="#15803D">Para que serve</font>

O sino é uma janela com os avisos mais recentes, não a caixa de entrada completa. Avisos diários ou de rotinas periódicas podem sair do sino no mesmo dia em que foram emitidos. A tela **Notificações** lista tudo o que você recebeu, com paginação, filtros e busca.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia); Responsável por ação/área; Analista de Integração de Dados; Leitor/Auditor; Administrador do sistema.

### <font color="#15803D">Passo a passo</font>

1. Abra **Início › Notificações** (ou clique em **Ver todas as notificações** no rodapé do sino).
2. Use o **filtro por tipo** para mostrar só um tipo de aviso, por exemplo os avisos de atraso de ações estratégicas.
3. Use o **filtro por situação** para separar as notificações enviadas das já lidas.
4. Digite na **busca** uma palavra que você lembra da mensagem. A busca procura no título e no corpo do aviso.
5. Navegue pelas páginas para chegar às notificações mais antigas.
6. Se o aviso não estiver na lista, confira as suas escolhas em **Início › Preferências de notificação** e o texto do aviso em **Início › Mensagens institucionais**.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/vI-4w5ueuWjjTvK-Xr60V_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 162 — Tela de notificações com filtros por tipo e situação e busca por texto

### Observações

- Antes de concluir que um aviso não chegou, filtre por tipo nesta tela. Se ele não estiver aqui, ele não foi emitido para você.

***

## <font color="#15803D">14.3 Configurar as preferências de notificação</font>

ID BSC-MSG-03

### <font color="#15803D">Para que serve</font>

As preferências definem, por tipo de aviso e por canal pessoal — **No sistema** (sino), **E-mail**, **WhatsApp** e **Push** —, o que cada pessoa recebe. As escolhas são individuais: desligar um canal silencia o aviso só para você, não para a sua equipe.

Sistema, e-mail e push começam ligados. O WhatsApp começa desligado e só pode ser ligado depois de você confirmar o número. Um tipo de aviso novo segue a mesma regra.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia); Responsável por ação/área; Analista de Integração de Dados; Leitor/Auditor; Administrador do sistema.

### <font color="#15803D">Passo a passo</font>

1. Abra **Início › Preferências de notificação**. No topo fica o quadro **Meu WhatsApp**; abaixo, o quadro **Tipos e canais**.
2. Em **Tipos e canais**, os avisos aparecem agrupados por área (por exemplo, "Bússola/BSC — indicadores" e "Bússola/BSC — planos de ação"), com uma coluna por canal. As áreas do Bússola/BSC já vêm abertas; o número entre parênteses é a quantidade de tipos da área.
3. Clique no interruptor de uma combinação tipo × canal para ligá-la ou desligá-la. A mudança é salva na hora e vale a partir do próximo aviso.
4. Para achar um tipo de aviso, digite parte do nome na **busca** (por exemplo, "atraso"). A lista mostra os tipos de todas as áreas que combinam.
5. Para mudar uma área inteira, use o seletor **Mudar a área inteira** ao lado do nome da área (por exemplo, **Ligar WhatsApp para esta área** ou **Silenciar E-mail nesta área**). A tela informa quantos tipos mudaram.
6. Se a coluna WhatsApp estiver com cadeado, clique em **Confirmar meu número** e siga a seção sobre o WhatsApp pessoal.
7. Se a tela avisar que o push ainda não chega a lugar nenhum, clique em **Ativar neste dispositivo**.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/52AVhW9F6iVcTZv0FD-a-_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 163 — Preferências de notificação por tipo de aviso e canal: sistema, e-mail, WhatsApp e push

### <font color="#15803D">Observações</font>

- Desligar o e-mail de um tipo de aviso não desliga o mesmo aviso no sino; cada combinação é independente.
- A mudança de área inteira é tudo ou nada: se o WhatsApp não estiver confirmado, nada é gravado.
- Microsoft Teams e Discord não aparecem como escolha pessoal. Esses avisos chegam ao canal da sua área, configurado em **Integrações › Canais de área**.
- Enquanto o WhatsApp estiver bloqueado, as escolhas já feitas na coluna ficam guardadas, mas nenhum aviso sai por WhatsApp.
- Toda mudança de preferência fica registrada.

***

## <font color="#15803D">14.4 Receber avisos push no celular e no computador</font>

ID BSC-MSG-04

### <font color="#15803D">Para que serve</font>

O quadro **Avisos push neste dispositivo** liga o aviso que aparece na tela do celular ou do computador, como o de qualquer aplicativo, mesmo com o Bússola/BSC fechado. O portal do Bússola/BSC pode ser instalado como aplicativo pelo navegador, sem loja de aplicativos. Quais alertas saem por push é regra da coordenação; se eles chegam a você é escolha sua, aparelho por aparelho.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia); Responsável por ação/área; Analista de Integração de Dados; Leitor/Auditor; Administrador do sistema.

### <font color="#15803D">Passo a passo</font>

1. Abra **Início › Preferências de notificação** no aparelho que vai receber os avisos (celular ou computador).
2. No quadro **Avisos push neste dispositivo**, clique em **Receber avisos neste dispositivo**.
3. Aceite a permissão de notificações que o navegador pede. O aparelho entra na lista (por exemplo, "Chrome · Android") com a situação **Recebendo** e a data de ativação.
4. Clique em **Enviar aviso de teste** para conferir que o aparelho recebe os avisos.
5. Toque no aviso recebido: o Bússola/BSC abre; num alerta, abre direto na ficha do registro.
6. Repita nos outros aparelhos que você usa. Cada aparelho ativo recebe o mesmo aviso uma vez.
7. Para parar em um aparelho, clique em **Desativar** na linha dele.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/52AVhW9F6iVcTZv0FD-a-_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 164 — Quadro de avisos push com a lista de aparelhos ativos

### <font color="#15803D">Observações</font>

- No iPhone e no iPad (iOS/iPadOS 16.4 ou mais novo), o push só funciona com o Bússola/BSC na tela de início: no Safari, toque em **Compartilhar › Adicionar à Tela de Início**, abra pelo ícone e ative ali.
- Se você negou a permissão, libere-a nas configurações do site no navegador (cadeado ao lado do endereço › Notificações › Permitir). Nada é gravado até a permissão ser dada.
- Se o navegador foi reinstalado ou os dados do site foram apagados, o aparelho aparece como **Expirado**. Ative de novo nele.
- O aviso de um registro sigiloso aparece na tela apenas como "Você tem um novo alerta no Bússola/BSC", sem nome nem valor.
- Se uma regra pede push e você não ativou nenhum aparelho, você recebe pelos outros canais e a tela de falhas registra "sem dispositivo".

***

## <font color="#15803D">14.5 Confirmar o número e autorizar o WhatsApp pessoal</font>

ID BSC-MSG-05

### <font color="#15803D">Para que serve</font>

O quadro **Meu WhatsApp** permite que você receba os alertas do Bússola/BSC no seu WhatsApp. Ao contrário do sino e do e-mail, o WhatsApp fica desligado até você ligar: a empresa paga por mensagem iniciada pelo sistema e precisa da sua autorização expressa. A autorização fica registrada com data, hora, texto e versão.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia); Responsável por ação/área; Analista de Integração de Dados; Leitor/Auditor; Administrador do sistema.

### <font color="#15803D">Passo a passo</font>

1. Abra **Início › Preferências de notificação** e localize o quadro **Meu WhatsApp**.
2. Informe o seu celular com DDD (por exemplo, (11) 98888-7777; de outro país, comece com +) e clique em **Salvar número**.
3. Clique em **Confirmar pelo WhatsApp**. A tela mostra o texto da autorização, um código no formato BUSSOLA-XXXXXX, o botão **Abrir o WhatsApp** e um QR.
4. Aponte a câmera do celular para o QR ou toque em **Abrir o WhatsApp**. O WhatsApp abre com a mensagem pronta para o número da empresa.
5. Envie a mensagem sem alterá-la, a partir do número que você informou, em até 30 minutos.
6. Volte ao Bússola/BSC e clique em **Já enviei — verificar de novo**. O quadro passa a mostrar **WhatsApp confirmado**.
7. Clique em **Ligar para os alertas do Bússola/BSC** para autorizar o WhatsApp para os avisos dos registros da estratégia (registro criado, alterado, atrasado e comentado).
8. Para parar, clique em **Parar de receber pelo WhatsApp** ou envie SAIR (ou PARAR, STOP, CANCELAR) para o número da empresa.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/52AVhW9F6iVcTZv0FD-a-_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 165 — Quadro Meu WhatsApp com número confirmado e alertas do Bússola/BSC ligados

### <font color="#15803D">Observações</font>

- Número fixo ou incompleto é recusado com a indicação do formato esperado.
- O código vale 30 minutos e só é aceito se vier do número informado. Se vencer, gere um novo código.
- Trocar o número desfaz a confirmação anterior; é preciso confirmar de novo.
- Só chega por WhatsApp o aviso cuja regra em **Alertas e mensagens** tem o WhatsApp marcado e cujo tipo tem a variação de WhatsApp com modelo aprovado.
- Registro sigiloso nunca é enviado por WhatsApp.
- Se o quadro disser que o WhatsApp não está disponível, a conta de WhatsApp da empresa ainda não foi configurada no hub de integrações.

***

## <font color="#15803D">14.6 Seguir registros e gerenciar os itens que sigo</font>

ID BSC-MSG-06

### <font color="#15803D">Para que serve</font>

Seguir um registro faz você receber os avisos de mudança, comentário e atraso daquele registro. O quadro **Itens que sigo** reúne os indicadores, objetivos, planos de ação, ações estratégicas e entregas que você segue.

**Quem usa:** Gestor de Desempenho (escritório de estratégia); Responsável por ação/área; Diretoria de Estratégia (patrocinador/aprovador); Leitor/Auditor.

### <font color="#15803D">Passo a passo</font>

1. Na ficha de um indicador, objetivo, plano de ação, ação estratégica ou entrega, clique em **Seguir**. Ao comentar num registro, você passa a segui-lo automaticamente.
2. Abra **Início › Preferências de notificação** e role até o quadro **Itens que sigo**.
3. Confira o tipo, o nome (com link para a ficha) e desde quando você segue cada registro.
4. Clique em **Deixar de seguir** na linha do registro que não interessa mais. Os avisos de mudança daquele registro deixam de chegar para você.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/52AVhW9F6iVcTZv0FD-a-_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 166 — Quadro Itens que sigo com os registros acompanhados

### <font color="#15803D">Observações</font>

- A entrega abre pela ficha da ação estratégica a que pertence.
- Um registro que você deixou de poder ver (ficou sigiloso ou mudou de área) some da lista sem mostrar o nome.
- O tratamento de risco não tem botão de seguir: quem segue o risco recebe os avisos dos tratamentos dele.

***

## <font color="#15803D">14.7 Editar as mensagens institucionais e usar campos automáticos</font>

ID BSC-MSG-07

### <font color="#15803D">Para que serve</font>

As mensagens institucionais são o texto que o sistema envia em cada tipo de aviso do Bússola/BSC — desvio de meta do indicador, novo comentário, indicador compartilhado com a área, plano de ação atrasado, risco cadastrado, entrega do cronograma chegando. Há uma mensagem padrão por tipo e idioma (português, inglês e espanhol), usada por todos os canais. Ajustar uma mensagem muda o texto de todos os próximos avisos daquele tipo.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia); Administrador do sistema.

### <font color="#15803D">Passo a passo</font>

1. Abra **Início › Mensagens institucionais**. Abaixo do título, a tela informa o total de modelos no catálogo.
2. Filtre por **área** (indicadores, planos de ação, ações estratégicas, cronograma, riscos, agenda), **canal** e **idioma**, ou busque pelo tipo, idioma, assunto ou canal.
3. Abra a mensagem que deseja ajustar.
4. Clique no **assunto**, no **corpo** ou no **corpo HTML**, no ponto onde quer inserir um dado.
5. Clique num dos botões de **campos automáticos** ao lado do texto (por exemplo, **Nome do registro**, **Autor**, **Trecho do comentário**, **Nome do destinatário**, **Data de hoje**, **Nome da organização**, **Link para o registro**). O campo entra onde está o cursor, na forma .
6. Confira a **pré-visualização** à direita, que mostra a mensagem como chega no e-mail, no sino, no Microsoft Teams e no Discord, com valores de exemplo.
7. Marque **Exemplo com caracteres especiais** para conferir que nomes com asteriscos, menções ou quebras de linha chegam como texto simples.
8. Clique em **Salvar**. O novo texto vale para os próximos avisos daquele tipo.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/uHrobeFBnQG-XrYr7OE2u_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 167 — Lista de mensagens institucionais com filtros por área, canal e idioma

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/Mcvuj7M6ixurRqOquku8i_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 168 — Modelo de mensagem aberto com campos automáticos e pré-visualização por canal

### <font color="#15803D">Observações</font>

- O sistema recusa um campo que aquele tipo de aviso não tem; a mensagem de erro nomeia o campo e lista os disponíveis.
- O sistema recusa chave simples () ou chave que não fecha (\{); a mensagem mostra a forma correta.
- Não é possível criar uma segunda mensagem para o mesmo tipo, idioma e canal: edite a que já existe.
- A pré-visualização nunca usa dados reais.
- Toda alteração fica no **Histórico de alterações** da mensagem, com o antes e o depois.
- A Diretoria de Estratégia (ou o cargo com a permissão "Editar as mensagens institucionais do Bússola/BSC") edita as mensagens do Bússola/BSC; o administrador do sistema edita as de todos os módulos. Quem não tem nenhuma das duas não vê o item no menu.
- Se a busca não achar um modelo, compare com o total exibido antes de concluir que ele não existe.

***

## <font color="#15803D">14.8 Criar uma variação da mensagem para um canal</font>

ID BSC-MSG-08

### <font color="#15803D">Para que serve</font>

Quando um canal precisa de um texto diferente — por exemplo, uma versão mais curta para o Microsoft Teams —, crie uma variação daquele tipo de aviso para o canal. Os demais canais continuam usando a mensagem padrão.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia); Administrador do sistema.

### <font color="#15803D">Passo a passo</font>

1. Abra **Início › Mensagens institucionais** e clique em **Novo modelo**.
2. Escolha o mesmo **tipo** de aviso e o mesmo **idioma** da mensagem padrão.
3. Em **Canal**, escolha o canal da variação (por exemplo, Microsoft Teams).
4. Escreva o texto adaptado, usando os campos automáticos como na mensagem padrão.
5. Inclua o campo **Link para o registro** quando quiser que o aviso leve à ficha do registro no portal.
6. Confira a pré-visualização e clique em **Salvar**.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/Mcvuj7M6ixurRqOquku8i_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 169 — Variação da mensagem para um canal específico

### <font color="#15803D">Observações</font>

- Sem variação no idioma do aviso, vale a variação em português; sem variação nenhuma, vale a mensagem padrão.
- O **Link para o registro** traz só o endereço da ficha, nunca o nome do registro. Ele depende do endereço público do portal, configurado pela equipe de operação; sem ele, a pré-visualização avisa "O endereço público do portal não está configurado" e o campo sai vazio.

***

## <font color="#15803D">14.9 Configurar a variação de WhatsApp com o modelo aprovado</font>

ID BSC-MSG-09

### <font color="#15803D">Para que serve</font>

No WhatsApp, a empresa só pode iniciar uma conversa com um modelo de mensagem (template) aprovado na plataforma do WhatsApp. O texto escrito no Bússola/BSC não vai como está: ele preenche os espaços numerados (, , …) do modelo aprovado. Sem a variação de WhatsApp com modelo aprovado, o aviso não sai por esse canal.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia); Administrador do sistema.

### <font color="#15803D">Passo a passo</font>

1. Cadastre o modelo na conta de WhatsApp da empresa (no gerenciador de modelos do WhatsApp Business): categoria **Utilidade**, idioma **Português (BR)**, nome sugerido bussola\_alerta.
2. No corpo do modelo, escreva um texto genérico com os espaços — por exemplo: "Bússola/BSC:  — . Veja no portal: " — e preencha os exemplos pedidos.
3. Envie para aprovação e aguarde a situação **Aprovado**.
4. No Bússola/BSC, abra **Início › Mensagens institucionais** e abra (ou crie com **Novo modelo**) a variação do tipo de aviso com **Canal** = **WhatsApp**.
5. Na seção **Template aprovado do canal**, informe o **nome do modelo aprovado** e o **idioma**, exatamente como cadastrados.
6. Indique qual campo automático preenche cada espaço (por exemplo, 1 = Nome do registro, 2 = Trecho do comentário, 3 = Link para o registro).
7. Confira na pré-visualização o modelo e o valor de cada espaço e clique em **Salvar**.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/Mcvuj7M6ixurRqOquku8i_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 170 — Variação de WhatsApp com o modelo aprovado e o preenchimento de cada espaço

### <font color="#15803D">Observações</font>

- Os avisos do Bússola/BSC (registro novo, atraso, comentário e mudança, comentários de indicador, entrega e ação estratégica, e avisos de apuração) já vêm com a variação de WhatsApp criada, em português, apontando para o modelo bussola\_alerta com dois campos: 1 = o registro e 2 = o detalhe (quem cadastrou, o que mudou, dias de atraso ou trecho do comentário).
- Se o modelo aprovado na conta tiver outro nome ou outra ordem de campos, edite a variação de WhatsApp de cada tipo nesta tela. Uma variação já criada por você é mantida como está.
- Sem nome e idioma do modelo, o sistema não salva a variação de WhatsApp.
- A pré-visualização já mostra os valores sem quebra de linha, porque a plataforma do WhatsApp recusa parâmetros com quebra de linha, tabulação ou mais de quatro espaços seguidos.
- Um aviso sem variação de WhatsApp aparece em **Falhas de envio** como "o aviso não tem mensagem de WhatsApp com template aprovado".

***

## <font color="#15803D">14.10 Configurar os alertas do Bússola/BSC por família</font>

ID BSC-MSG-10

### <font color="#15803D">Para que serve</font>

A tela **Alertas e mensagens** decide, para cada tipo de registro do Bússola/BSC — indicador, objetivo, plano de ação, ação estratégica, entrega (cronograma), risco corporativo e tratamento de risco — e para cada família de aviso, por quais canais e para quem o sistema avisa.

As famílias são: **Registro novo** (avisa o responsável quando o registro é cadastrado); **Atraso** (ação do plano 5W2H, atividade do cronograma ou tratamento de risco que passou do prazo, verificado todo dia às 6h30; avisa o responsável e quem segue); **Comentário** (avisa o responsável e quem segue); e **Mudança (ouvintes)** (avisa quem segue o registro quando ele é alterado).

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia).

### <font color="#15803D">Passo a passo</font>

1. Abra **Gestão por indicadores › Alertas e mensagens**. Cada tipo de registro aparece num quadro, com uma linha por família de aviso.
2. Na coluna **Pessoas**, marque os canais pessoais da família: **Sistema (sino)**, **E-mail**, **WhatsApp** e **Também enviar push**.
3. Em **Quem recebe**, escolha o responsável, quem segue o registro ou os dois.
4. Use a chave **Ligado/Desligado** para ativar ou desativar a família inteira daquele tipo de registro.
5. Clique em **Verificar atrasos agora** para rodar na hora a verificação diária de atrasos (útil depois de corrigir um prazo).
6. Clique em **Editar a mensagem** para abrir as **Mensagens institucionais** e ajustar o texto do aviso.
7. Clique no ícone de relógio de uma regra para ver o **Histórico**, com o antes e o depois de cada mudança.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/zqgc1O-GVCdRdmkb8A13q_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 171 — Alertas e mensagens: canais e destinatários por tipo de registro e família de aviso

### <font color="#15803D">Observações</font>

- A mudança vale a partir do próximo aviso. Uma família desligada não envia nada daquele tipo de registro; as demais continuam.
- Cada pessoa ainda pode desligar um tipo de aviso para si em **Preferências de notificação**.
- O WhatsApp só chega a quem confirmou o número e ligou os alertas, e só para tipo de aviso com variação de WhatsApp. O push vem desligado por padrão.
- Cada item atrasado é avisado no máximo uma vez por dia, mesmo que a verificação rode de novo.
- Os campos automáticos dos avisos de família são Nome do registro, Quem fez, O que mudou, Item atrasado, Prazo e Dias de atraso.
- Quem agiu não é avisado: o autor de uma mudança ou comentário nunca recebe o aviso da própria ação, e quem não pode mais ver o registro sai da lista.
- Registro sigiloso é avisado só no sino de quem pode vê-lo; o push, se pedido, sai apenas com o texto genérico "Você tem um novo alerta no Bússola/BSC". A conferência é refeita na hora do envio.
- Quem não tem a permissão "Ligar canais de Teams e Discord às áreas" não vê o item no menu.

***

## <font color="#15803D">14.11 Publicar os alertas nos canais da área (Teams e Discord)</font>

ID BSC-MSG-11

### <font color="#15803D">Para que serve</font>

Além dos canais pessoais, cada família de aviso pode ser publicada num canal compartilhado do Microsoft Teams ou do Discord: o canal da unidade dona do registro ou sempre um canal fixo (por exemplo, o da diretoria).

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia).

### <font color="#15803D">Passo a passo</font>

1. Abra **Gestão por indicadores › Alertas e mensagens** e localize o quadro do tipo de registro.
2. Na família desejada, em **Canais da área**, clique em **Publicar num canal**.
3. Escolha o tipo de canal: **Microsoft Teams** ou **Discord**.
4. Em **Onde**, escolha o canal da **unidade do registro** (cada registro vai para o canal da sua área) ou **um canal** fixo.
5. Se a regra mostrar "Unidades sem canal deste tipo — os avisos delas não são publicados", ligue um canal a essas unidades em **Integrações › Canais de área**.
6. Para que o aviso publicado no canal também chegue por push, marque **Também enviar push** na regra de pessoas da mesma família.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/zqgc1O-GVCdRdmkb8A13q_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 172 — Regra de publicação de alertas no canal da área

### <font color="#15803D">Observações</font>

- O aviso de uma unidade sem canal ativo do tipo escolhido não sai pelo canal e fica registrado como "sem destino" em **Falhas de envio**.
- Registro sigiloso nunca é publicado em canal compartilhado.

***

## <font color="#15803D">14.12 Cadastrar a integração com o Microsoft Teams</font>

ID BSC-MSG-12

### <font color="#15803D">Para que serve</font>

A integração com o Microsoft Teams publica os avisos do Bússola/BSC num canal do Teams, como um cartão com título, texto e o botão "Abrir no Bússola/BSC". O endereço usado é o de um fluxo do aplicativo **Workflows** do próprio Teams.

**Quem usa:** Analista de Integração de Dados; Administrador do sistema.

### <font color="#15803D">Passo a passo</font>

1. No Teams, no canal que vai receber os avisos, abra **⋯ › Workflows** e escolha o modelo "Postar em um canal quando uma solicitação de webhook for recebida".
2. Dê um nome ao fluxo (por exemplo, "Bússola/BSC — avisos da DIRPLAN"), confirme a equipe e o canal e conclua. Copie a **URL do fluxo** inteira.
3. Acrescente um **coproprietário** ao fluxo no Workflows, para que ele não pare quando o criador sair da organização.
4. Peça ao administrador do sistema que aprove o servidor da URL na **lista de saída das integrações** (HTTPS, porta 443).
5. No Bússola/BSC, abra **Integrações › Integrações**, clique em **Nova integração** e escolha **Microsoft Teams**.
6. Cole a URL no campo **URL do webhook** e, em **Avançado**, informe o **Nome do canal**. Salve.
7. Clique em **Testar**. O Bússola/BSC publica a mensagem "Bússola/BSC — mensagem de teste" no canal; confira no Teams.
8. Ligue o canal a uma unidade em **Integrações › Canais de área**.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/WokAPJ8jAKgk5a-D4vuTy_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 173 — Escolha do tipo de integração, incluindo Microsoft Teams

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/uYo0aUL9quw1nU_6TTaSJ_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 174 — Integração aberta com o botão Testar

### <font color="#15803D">Observações</font>

- A URL do webhook é um segredo: quem a tem consegue publicar no canal. Ela fica cifrada e nunca volta à tela; a ficha mostra só "Definido em … por …".
- Só é aceita URL HTTPS, porta 443, num servidor do Workflows da Microsoft. Os antigos conectores do Office 365 não são aceitos.
- "O canal recusou o endereço": o fluxo foi apagado ou desligado; gere outra URL e use **Substituir** no segredo.
- "Endereço não aprovado": o servidor não está na lista de saída.
- "O outro sistema pediu para diminuir o ritmo": o Teams aceita cerca de quatro mensagens por segundo por fluxo; tente de novo em instantes.
- A mesma URL não pode estar em duas integrações, para evitar avisos em dobro.
- Se o teste diz "publicada" mas o cartão não aparece, confira o histórico de execuções do fluxo no Workflows.

***

## <font color="#15803D">14.13 Cadastrar a integração com o Discord</font>

ID BSC-MSG-13

### <font color="#15803D">Para que serve</font>

A integração com o Discord publica os avisos do Bússola/BSC num canal do Discord: o texto na mensagem e o título, com o link do registro, num quadro. Ninguém é mencionado: @everyone, @here ou nomes de pessoas no texto de um registro aparecem como texto, sem notificar o servidor.

**Quem usa:** Analista de Integração de Dados; Administrador do sistema.

### <font color="#15803D">Passo a passo</font>

1. No Discord, abra **Configurações do canal › Integrações › Webhooks › Novo webhook** (é preciso a permissão Gerenciar webhooks).
2. Dê um nome ao webhook (por exemplo, "Bússola/BSC"), que aparece como autor das mensagens, e clique em **Copiar URL do webhook**.
3. Peça ao administrador do sistema que aprove discord.com na **lista de saída das integrações** (HTTPS, porta 443). Uma aprovação serve para todos os canais.
4. No Bússola/BSC, abra **Integrações › Integrações**, clique em **Nova integração** e escolha **Discord**.
5. Cole a URL em **URL do webhook**, informe o **Nome do canal** em **Avançado** e salve.
6. Clique em **Testar** e confira a mensagem de teste no canal.
7. Ligue o canal a uma unidade em **Integrações › Canais de área**.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/uYo0aUL9quw1nU_6TTaSJ_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 175 — Integração com o Discord aberta, com o resultado do teste

### <font color="#15803D">Observações</font>

- A URL do webhook é um segredo (o token está no próprio endereço): fica cifrada e nunca volta à tela.
- Só é aceita URL HTTPS, porta 443, em discord.com (ou discordapp.com) com o caminho de webhook. O link do canal não é aceito.
- "O canal recusou o endereço": o webhook foi apagado ou o token trocado; crie outro e use **Substituir**.
- O Bússola/BSC neutraliza a formatação do Discord para que o nome de um registro nunca vire negrito, link ou menção. O link para o registro é a exceção e continua clicável.

***

## <font color="#15803D">14.14 Configurar a conta de WhatsApp da empresa</font>

ID BSC-MSG-14

### <font color="#15803D">Para que serve</font>

A integração de WhatsApp envia os alertas pessoais do Bússola/BSC para o WhatsApp de cada pessoa que confirmou o número. O envio é feito pelo provedor contratado, que fala com a plataforma oficial do WhatsApp em nome da Empresa Exemplo S.A. Só pode haver uma integração de WhatsApp ativa por ambiente.

**Quem usa:** Analista de Integração de Dados; Administrador do sistema.

### <font color="#15803D">Passo a passo</font>

1. Obtenha com o provedor contratado: a URL base do serviço, o token de acesso (e o cabeçalho e o esquema de autenticação, se forem diferentes do padrão), o identificador do número, o identificador da conta, o número de WhatsApp da empresa, o nome e o idioma do modelo aprovado dos alertas e o segredo do aplicativo (App Secret).
2. Peça ao administrador do sistema que aprove o servidor do provedor na **lista de saída das integrações** (HTTPS, porta 443).
3. Abra **Integrações › Integrações**, clique em **Nova integração** e escolha **WhatsApp**.
4. Em **Endereço**, informe a **URL base**, o **Identificador do número**, o **Identificador da conta** (opcional), o **Número de WhatsApp da empresa** e o **Nome da empresa no consentimento**.
5. Em **Autenticação**, informe o **Token de acesso**, o **App Secret** e o **Token de verificação do webhook** (que você escolhe e entrega também ao provedor).
6. Em **Avançado**, confira o **modelo aprovado dos alertas** e o **idioma do modelo**, o **teto diário de envios** e os tempos de conexão e leitura. Salve.
7. Abra **Integrações › Canais de área** e copie, no quadro **WhatsApp da empresa**, o endereço dos avisos; entregue-o ao provedor junto com o token de verificação.
8. Clique em **Testar**. O teste lê o cadastro do número no provedor e não envia mensagem.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/EdECacO52wgC9ni9MLC4j_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 176 — Quadro WhatsApp da empresa com o endereço dos avisos

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/uYo0aUL9quw1nU_6TTaSJ_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 177 — Integração de WhatsApp com as seções Endereço, Autenticação e Avançado

### <font color="#15803D">Observações</font>

- Enquanto o token não for salvo, o teste responde "Aguardando credenciais" e nada é enviado.
- Sem o App Secret, nenhum aviso do provedor é aceito e ninguém consegue confirmar o número. Aviso sem assinatura válida é recusado e nada muda.
- Sem o número de WhatsApp da empresa, ninguém consegue confirmar o número.
- Teto diário de envios = 0 significa sem teto. Um valor maior faz o Bússola/BSC parar de enviar por WhatsApp no dia (horário de Brasília) quando o número de alertas chega a ele; os demais canais seguem.
- "O outro sistema recusou a credencial": token errado, vencido ou no cabeçalho errado. "O caminho de teste não existe lá": identificador do número ou URL base errados.
- Falha de entrega por mensagem fora da janela de 24 horas indica modelo aprovado com nome, idioma ou variáveis diferentes do cadastrado.
- O custo por mensagem de modelo entregue é condição comercial do contrato com o provedor.
- Cada envio fica registrado como execução da integração no monitor de integrações; a situação do provedor (aceito, enviado, entregue, lido, falhou) fica na notificação.

***

## <font color="#15803D">14.15 Ligar canais de Teams e Discord às unidades (Canais de área)</font>

ID BSC-MSG-15

### <font color="#15803D">Para que serve</font>

Cadastrar e testar o webhook é tarefa de quem mantém as integrações. Decidir qual unidade recebe os avisos em qual canal é feito na tela **Canais de área**, por quem tem a permissão "Ligar canais de Teams e Discord às áreas".

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia).

### <font color="#15803D">Passo a passo</font>

1. Abra **Integrações › Canais de área** e clique em **Ligar canal**.
2. Escolha a **integração** de Teams ou Discord. Só aparecem as integrações ativas, com aviso quando o último teste falhou.
3. Escolha a **unidade** cujos avisos vão para o canal (por exemplo, GEOBR — Gerência de Obras) ou deixe **Organização inteira** para o canal geral.
4. Dê um **nome ao canal** e salve.
5. Confira na lista a unidade, a integração (com o selo do ambiente) e o último teste feito no hub.
6. Para parar de publicar num canal, use **Desativar** na linha dele.
7. Clique no ícone de relógio para ver o histórico de cada ligação.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/EdECacO52wgC9ni9MLC4j_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 178 — Canais de área: canais de Teams e Discord ligados às unidades e conta de WhatsApp da empresa

### <font color="#15803D">Observações</font>

- O histórico da ligação nunca mostra nenhuma parte do endereço do webhook.
- Desativar um canal não apaga a integração. Enquanto houver um canal ativo usando a integração, ela não pode ser desativada no hub; a ficha da integração mostra o canal em "Quem usa".
- Se o Teams ou o Discord pedir para diminuir o ritmo ou estiver fora do ar, o envio é repetido mais tarde; recusas definitivas (webhook apagado, canal desativado) param na hora. As duas aparecem em **Falhas de envio**.
- Registro sigiloso nunca é publicado num canal compartilhado, e ninguém é mencionado nas publicações.

***

## <font color="#15803D">14.16 Conferir e reprocessar as falhas de envio</font>

ID BSC-MSG-16

### <font color="#15803D">Para que serve</font>

A tela **Falhas de envio** lista as notificações que não saíram — por e-mail, WhatsApp, Teams, Discord ou push —, com o motivo em linguagem do operador, para conferência e reprocessamento do que puder ser reenviado.

**Quem usa:** Administrador do sistema; Gestor de Desempenho (escritório de estratégia).

### <font color="#15803D">Passo a passo</font>

1. Abra **Início › Falhas de envio**.
2. Confira cada falha: canal, destinatário e motivo (por exemplo, destinatário inválido, erro do provedor, canal que recusou o endereço).
3. Para falhas de WhatsApp, leia o motivo: a pessoa não tem número confirmado ou parou de receber, registro sigiloso, teto diário atingido, integração inexistente ou aguardando credenciais, ou aviso sem modelo aprovado.
4. Para falhas de push, confira se o motivo é "sem dispositivo" (a pessoa não ativou o push) ou recusa do serviço de push.
5. Para avisos de canal da área "sem destino", ligue um canal à unidade em **Integrações › Canais de área**.
6. Corrija a causa e use **Reprocessar** nas falhas que podem ser reenviadas.

### <font color="#15803D">Observações</font>

- No estado saudável, a tela mostra "Nenhuma falha de envio — todos os e-mails de notificação saíram."
- Notificação para quem não tem e-mail cadastrado não vira falha: o canal de e-mail é pulado e o aviso continua no sino. Corrija o cadastro da pessoa.
- As regras automáticas de e-mail (**Administração › Regras de e-mail**) ligam eventos de outros módulos a notificações e são restritas ao administrador do sistema; os avisos do Bússola/BSC são configurados em **Alertas e mensagens**.

[title] Política de Liberação
[path] Diretório de Releases/

## Visão Geral

O objetivo desta política é descrever os ciclos de liberação e atualização dos **Produtos&#x20;**<font color="#3b9f0f">**CITSmart**</font>, notificações ao cliente e outras informações relevantes.

As diretrizes da política são aplicáveis a todos os nossos produtos, estejam eles usando o modelo SaaS ou On-Premise.

## Ciclos de Liberação e Atualização

Nossa proposta de liberação e atualização de produtos foi definida para fornecer estabilidade, resposta rápida a problemas, além de fornecimento contínuo de novos recursos e experiências.

Os produtos <font color="#3b9f0f">**CITSmart**</font>, geralmente, seguem 3 tipos de liberação, conforme listado na tabela a seguir:

| **Tipo Liberação**     | **Escopo**                                                                                                                 | **Frequência**                      | **Notificação**                                                                                  |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------ |
| *Major Release*        | Novas funcionalidades e killer features para o produto.                                                                    | Tipicamente, duas vezes por ano     | Tipicamente, um mês antes do lançamento, com uma segunda notificação 20 dias após o envio da 1ª. |
| *Minor Release*        | Inclui, mas não se limita a pequenas melhorias, atualizações de segurança e geralmente não envolve mudanças arquiteturais. | Tipicamente, uma vez a cada 2 meses |                                                                                                  |
| *Hotfix* **Planejada** | Atualizações incluindo correção de erros e aplicações e ajustes pontuais.                                                  | Tipicamente, uma vez por mês        |                                                                                                  |
| *Hotfix* **Crítica**   | Correções emergenciais para garantir a estabilidade e segurança do Sistema                                                 | Sempre que necessário               | Poucas horas antes, preferencialmente 48h antes                                                  |

A <font color="#3b9f0f">**Central IT** </font>refere-se a cada Feature Release, e seus Hotfixes associados, como uma “Série”. Por exemplo, a Versão 7.6.5.4 faz parte da Série 7. As séries são atualizações de versão, na maioria das vezes, com mudanças significativas na aplicação ou na arquitetura.

Por conta disso, os produtos <font color="#3b9f0f">**CITSmart** </font>utilizam o seguinte padrão de versão:

`Series > Major Release > Minor Release > Hotfix`

Por exemplo: Na versão 7.6.5.4, 7 é a Série, 6 é a Major Release, 5 é a Minor Release e 4 é o HotFix associado.

Cronograma de Lançamento do <font color="#3b9f0f">**CITSmart**</font>:

| **Mês de Lançamento** | **Tipo de Lançamento**          | **Número da Versão**             |
| --------------------- | ------------------------------- | -------------------------------- |
| **Janeiro**           | **Hot-fix Planejada**           | **\<series>.x.1.1**              |
| **Fevereiro**         | **Minor Release**               | **\<series>.x.2.0**              |
| **Março**             | **Hot-fix Planejada**           | **\<series>.x.2.1**              |
| **Abril**             | **New Series ou Major Release** | **SERIE.0.0.0/ \<series>.X.0.0** |
| **Maio**              | **Hot-fix Planejada**           | **\<series>.x.0.Y**              |
| **Junho**             | **Minor Release**               | **\<series>.x.1.0**              |
| **Julho**             | **Hot-fix Planejada**           | **\<series>.x.1.Y**              |
| **Agosto**            | **Minor Release**               | **\<series>.x.2.0**              |
| **Setembro**          | **Hot-fix Planejada**           | **\<series>.x.2.Y**              |
| **Outubro**           | **New Series ou Major Release** | **SERIE.0.0.0/ \<series>.X.0.0** |
| **Novembro**          | **Hot-fix Planejada**           | **\<series>.x.0.Y**              |
| **Dezembro**          | **Minor Release**               | **\<series>.x.1.0**              |

(\*) O tempo e a frequência dos lançamentos estão sujeitos a alterações, a critério exclusivo da <font color="#3b9f0f">**Central IT**</font>. No caso de alterações deste cronograma, os clientes deverão ser previamente notificados.

## Versões Suportadas

Nossa política atual é oferecer suporte a Série mais recente. A série anterior será suportada até 6 meses após o lançamento da nova série.

A <font color="#3b9f0f">**Central IT**</font> geralmente realiza dois grandes lançamentos por ano, sendo assim, o cliente precisará atualizar, aproximadamente, uma vez por ano para se permanecer em uma versão suportada. A <font color="#3b9f0f">**Central IT**</font> fornece atualizações (por exemplo: correções e hotfixes) somente para a versão suportada.

## Informações Adicionais Sobre Atualização

Os Procedimentos de Atualização dependem do modelo da solução adquirida (SaaS ou On-Premise), para cada uma delas, siga as recomendações abaixo:

**Clientes SaaS**

Os clientes podem agendar atualizações de software quando necessário, enviando uma nova solicitação de serviço por meio de nosso site de suporte. Nessa solicitação, o cliente informa a data desejada para atualização, versão desejada e tipo de ambiente não produção ou produção). Os tempos de interrupção são definidos para minimizar a interrupção dos negócios do cliente. Todo o processo de atualização é feito pelo time de suporte da <font color="#3b9f0f">**Central IT**</font>.

**Clientes On-Premise**

Nesse caso, os clientes são responsáveis pela atualização de software. Recomendamos que os clientes testem funcionalidades e customizações no ambiente de não produção antes de realizar a atualização no ambiente de produção. Orientações sobre como atualizar ou usar novos recursos estarão disponíveis nas Notas da Versão.

Se você tiver alguma dúvida sobre os procedimentos de atualização, envie-nos uma solicitação de serviço, por meio do nosso site de suporte.


[title]  5. Ações estratégicas
[path] Aplicações/BSC/

A carteira de ações estratégicas reúne num lugar só os projetos que a empresa executa para cumprir o plano estratégico: obras, estudos, contratos de gestão, projetos de tecnologia. Na Empresa Exemplo S.A., por exemplo, estão ali a Duplicação da Rodovia Norte — trecho 3 (RN-03), a Construção da Ponte do Vale (PV-01) e a Ampliação do Terminal Sul (TS-01). Cada ação tem categoria, área, gestor, programa, objetivos atendidos e a prioridade calculada pela matriz GUT.

Cada ação é decomposta no seu escopo (agrupadores e entregas), e cada entrega em atividades com dependências. Do escopo nascem sozinhos o cronograma em Gantt e o planejamento financeiro mensal. A ação nasce em planejamento; quando a diretoria a inicia, o plano é congelado como linha de base, e qualquer nova linha de base só nasce de uma solicitação de mudança aprovada.

Com a ação em andamento, cada entrega é acompanhada pela execução física e financeira, pelas evidências e pelos comentários, e parte dos dados pode chegar automaticamente de outros sistemas. As telas ficam em Gestão por indicadores › Ações estratégicas, Categorias de ação e Classificações do escopo.

## 5.1 Categorias de ação

ID BSC-ACE-01

### Para que serve

As categorias classificam a carteira do jeito que a empresa decidir: obra, estudo, tecnologia, contrato de gestão. Toda ação estratégica precisa de uma categoria, e a cor da categoria ajuda a identificá-la nas listas.

O produto não traz nenhuma categoria pronta: não existe lista oficial, e cada organização monta a sua.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador).

### Passo a passo

1. Abra Gestão por indicadores › Categorias de ação.
2. Clique em **Nova categoria**.
3. Informe o **Nome** (por exemplo, Obra, Estudo ou Tecnologia) e uma **Descrição**.
4. Se quiser, marque **Usar uma cor** e escolha a cor que identifica a categoria.
5. Clique em **Salvar**.
6. Para alterar, use o lápis da linha; para tirar a categoria de uso, use o botão de liga/desliga.
7. Use o ícone de relógio da linha para abrir o histórico da categoria.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/9mIhtBxg0cV5uZgLN81yV_image.png" size="62" isUploading="false" width="620" height="387" showCaption="false"}

Figura 25 — Categorias de ação com nome, descrição, cor e situação

### Observações

- Renomear uma categoria muda o rótulo de todas as ações que a usam de uma vez.
- Uma categoria desativada some das novas escolhas; as ações que já estão nela continuam com ela e mostram o selo **Inativo**.
- O nome não se repete, sem diferença de maiúsculas e minúsculas: "obra" e "Obra" são a mesma categoria.
- Só quem mantém o catálogo da carteira (em geral, a diretoria de estratégia) vê esta tela.

## 5.2 Cadastrar uma ação estratégica

ID BSC-ACE-02

### Para que serve

Uma ação estratégica é um projeto da carteira da empresa: uma obra, um estudo, um contrato de gestão, um projeto de tecnologia. Reunir as ações num lugar só permite compará-las, porque elas disputam os mesmos recursos.

Não confunda com o plano de ação 5W2H dos indicadores: aquele responde a um indicador fora da meta; a ação estratégica é um projeto planejado. Por isso o produto sempre escreve "ação estratégica", nunca "ação" sozinho.

**Quem usa:** Gestor de Desempenho (escritório de estratégia).

### Passo a passo

1. Abra Gestão por indicadores › Ações estratégicas.
2. Clique em **Nova ação estratégica**.
3. Informe o **Código** (por exemplo, PV-01). Ele é gravado em maiúsculas e não se repete na carteira.
4. Informe o **Título** (por exemplo, Construção da Ponte do Vale) e a **Descrição**.
5. Escolha a **Categoria** (obrigatória; só aparecem as ativas).
6. Se já souber, escolha a **Área responsável** e o **Gestor da ação** pela busca por nome.
7. Escolha o **Programa ou subprograma** (por exemplo, PROROD › Ponte do Vale); o subprograma aparece recuado sob o programa.
8. Se a ação tiver projeto próprio no cadastro de orçamento, escolha-o em **Projeto do cadastro (orçamento)**.
9. No campo de objetivos atendidos, marque um ou mais objetivos do plano; eles aparecem agrupados pelo plano a que pertencem.
10. Marque **Sigilosa**, se for o caso (veja a seção sobre sigilo).
11. Clique em **Salvar**: a ação nasce **Em planejamento** e a ficha dela abre.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/sQUCp5IWSj71PTcrL3iVM_image.png" size="62" isUploading="false" width="620" height="387" showCaption="false"}

Figura 26 — Carteira de ações estratégicas com o botão Nova ação estratégica

### Observações

- Área, gestor e programa são opcionais no cadastro, mas área e gestor serão exigidos para iniciar a ação.
- O código é comparado sem diferença de maiúsculas e minúsculas; o título pode repetir.
- Uma categoria inativa não pode ser escolhida para ação nova; a ação que já estava nela continua podendo ser editada sem trocá-la.
- O projeto do cadastro permite, mais adiante, ler o realizado financeiro sem digitação (execução automatizada).
- Ação cadastrada por engano não é excluída: é cancelada, e o histórico fica.

## 5.3 Priorizar com a matriz GUT

ID BSC-ACE-03

### Para que serve

A matriz GUT ajuda a decidir o que atacar primeiro. Cada ação recebe uma nota de 1 a 5 em **Gravidade** (o estrago se nada for feito), **Urgência** (o tempo disponível para agir) e **Tendência** (o quanto piora com o tempo).

A **Prioridade GUT** é o produto das três notas, de 1 a 125. A carteira abre ordenada por ela, da maior para a menor.

**Quem usa:** Gestor de Desempenho (escritório de estratégia); Diretoria de Estratégia (patrocinador/aprovador).

### Passo a passo

1. Abra Gestão por indicadores › Ações estratégicas e clique na ação.
2. Na aba **Visão geral**, cartão **Priorização GUT**, clique em **Avaliar GUT**.
3. Escolha a nota de **Gravidade** (de 1 — Sem gravidade a 5 — Extremamente grave).
4. Escolha a nota de **Urgência** (de 1 — Pode esperar a 5 — Ação imediata).
5. Escolha a nota de **Tendência** (de 1 — Não irá mudar a 5 — Irá piorar rapidamente).
6. Confira a **Prioridade GUT** calculada (por exemplo, 5 × 4 × 3 = 60) e clique em **Salvar**.

### Observações

- A avaliação vale com as três notas ou com nenhuma: com uma faltando, a tela avisa e não salva.
- Deixar as três em branco e salvar limpa a avaliação.
- Ação sem GUT aparece como **não avaliada** e vai para o fim da lista nos dois sentidos da ordenação. Não é a menos urgente: é a que ninguém avaliou.
- Com a ação suspensa, concluída ou cancelada, a GUT fica somente leitura.

## 5.4 Classificações do escopo (dimensões livres)

ID BSC-ACE-04

### Para que serve

Os relatórios gerenciais cortam a carteira por vários eixos ao mesmo tempo. Programa, tipo de entrega e região já são cadastros estratégicos próprios e não se criam aqui. Aqui ficam as **dimensões livres**: os eixos que a própria empresa quer criar sem pedir alteração no sistema.

O produto traz duas dimensões como ponto de partida: **Instrumento de planejamento** (com os valores Contrato de gestão, PDTI e Plano plurianual) e **Área temática** (sem valores). Renomeie, complete ou desative à vontade.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador).

### Passo a passo

1. Abra Gestão por indicadores › Classificações do escopo.
2. Para criar um eixo, clique em **Nova dimensão**, informe o **Nome** (por exemplo, Eixo do plano plurianual) e a **Descrição**, e salve.
3. No cartão da dimensão, escreva um valor no campo de baixo e clique em **Incluir valor** (ou tecle Enter).
4. Use o lápis para renomear uma dimensão ou um valor.
5. Use o liga/desliga para desativar uma dimensão ou um valor.
6. Use o relógio de cada dimensão ou valor para abrir o histórico.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/aESc1-thNXbuUQqNxVYrM_image.png" size="62" isUploading="false" width="620" height="387" showCaption="false"}

Figura 27 — Dimensões livres de classificação do escopo com os seus valores

### Observações

- A dimensão nova aparece na hora como campo de classificação de todo item do escopo.
- O valor não se repete dentro da mesma dimensão, sem diferença de maiúsculas e minúsculas.
- Renomear muda o rótulo de todos os itens já classificados; desativar só esconde das novas escolhas.
- Programa, tipo de entrega e região são mantidos em Cadastros estratégicos.

## 5.5 Montar o escopo: agrupadores e entregas

ID BSC-ACE-05

### Para que serve

O escopo decompõe a ação numa árvore de **agrupadores** (um lote, uma fase) e **entregas** (o que de fato se produz), em quantos níveis forem precisos: é a estrutura analítica do projeto.

Cada entrega tem valor previsto, período de execução, unidade organizacional e responsável. O agrupador não tem valor próprio: ele soma as entregas abaixo dele. Do escopo, o sistema gera sozinho o cronograma e o planejamento financeiro mensal.

**Quem usa:** Gestor de Desempenho (escritório de estratégia).

### Passo a passo

1. Na ficha da ação, abra a aba **Escopo**.
2. Clique em **Agrupador**, dê um nome (por exemplo, Lote 1 — Fundações) e salve.
3. Use o **+** da linha do agrupador para incluir um item dentro dele (o botão **Entrega** do topo cria no primeiro nível).
4. Em **Tipo do item**, escolha **Entrega** ou **Agrupador** (para um subnível). O tipo não muda depois.
5. Na entrega, informe **Valor previsto**, **Início** e **Fim** do período de execução.
6. Escolha a **Unidade organizacional** (por exemplo, GEPVA) e o **Responsável pela entrega**.
7. Em **Classificação**, marque **Programa**, **Tipo de entrega**, **Região** e os valores das dimensões livres.
8. Em **Indicadores que este item move**, marque os indicadores do plano (por exemplo, Avanço físico da Ponte do Vale).
9. Salve e confira a árvore: código hierárquico (1, 1.1, 1.2.1…), valor, período, responsável, farol dos indicadores e classificações.
10. Use as setas **↑** e **↓** para trocar a ordem entre irmãos, ou troque **Dentro do agrupador** para mover o item.
11. Use **Buscar código ou nome**, o filtro de classificação e **Só incompletas** para encontrar itens.
12. Para remover, abra o item, clique em **Remover** e em **Confirmar remoção**.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/J7nd0Bo6K47IayTga651t_image.png" size="62" isUploading="false" width="620" height="387" showCaption="false"}

Figura 28 — Árvore do escopo com agrupadores, entregas, valores e faróis dos indicadores

### Observações

- Enquanto a ação está em planejamento, só o **Nome** é obrigatório. A entrega sem valor, período, unidade ou responsável fica **Incompleta** e a linha diz o que **Falta**.
- Não digite valor no agrupador: contaria o mesmo dinheiro duas vezes. O período do agrupador vai do primeiro início ao último fim das entregas.
- O sistema recusa pôr um item debaixo de uma entrega e mover um agrupador para dentro do próprio ramo.
- Agrupador com itens e entrega com atividades não podem ser removidos; esvazie-os antes. Entrega com execuções, evidências ou execução automatizada também fica.
- O farol de cada indicador ligado segue o do mapa estratégico: verde na meta, amarelo em atenção, vermelho fora da meta, cinza sem meta ou medição.
- Com a ação suspensa, concluída ou cancelada, o escopo é somente leitura.
- Se a tela disser que o item foi criado, mas nem tudo foi salvo, corrija o motivo em vermelho e salve de novo: o sistema completa o mesmo item.
- **Histórico deste item**, no rodapé, lista cada mudança com antes e depois.

## 5.6 Ver o escopo como organograma

ID BSC-ACE-06

### Para que serve

O organograma desenha o mesmo escopo em caixas, de cima para baixo, para apresentar a estrutura da ação de um jeito visual.

**Quem usa:** Gestor de Desempenho (escritório de estratégia); Diretoria de Estratégia (patrocinador/aprovador); Leitor/Auditor.

### Passo a passo

1. Na ficha da ação, abra a aba **Escopo**.
2. Clique em **Organograma**.
3. Use os botões **−** e **+** para mudar o zoom.
4. Use o botão sob cada caixa para recolher ou expandir o ramo.
5. Clique numa caixa (ou tecle Enter) para abrir o item.

### Observações

- A ação aparece no topo e cada item mostra código, nome, valor, período e responsável.
- As entregas incompletas aparecem com borda tracejada.
- No celular, o desenho rola dentro do próprio quadro, sem arrastar a página.

## 5.7 Detalhar entregas em atividades, subtarefas e dependências

ID BSC-ACE-07

### Para que serve

A entrega é o "o quê"; a **atividade** é o "como". Cada entrega é detalhada em atividades e subtarefas, com responsável, datas planejadas, peso e dependências entre elas.

As atividades são numeradas a partir do código da entrega: a entrega 1.1.1 tem as atividades 1.1.1.1, 1.1.1.2 e a subtarefa 1.1.1.2.1.

**Quem usa:** Gestor de Desempenho (escritório de estratégia).

### Passo a passo

1. Na ficha da ação, abra a aba **Cronograma**.
2. Em **Atividades por entrega**, clique em **Nova atividade** na entrega desejada.
3. Informe o **Nome**, o **Início planejado**, o **Fim planejado**, o **Peso** (vazio vale 1) e o **Responsável**.
4. Para criar uma subtarefa, escolha em **Subtarefa de** outra atividade da mesma entrega.
5. Para ligar atividades, abra a atividade sucessora e, em **Dependências**, escolha a predecessora em **Começa depois de**.
6. Informe a **Folga (dias)**, se houver, e clique em **Incluir dependência**.
7. Para remover, abra a atividade, clique em **Remover** e em **Confirmar remoção**.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/auOojEGc9A5JSLiNFrDPl_image.png" size="62" isUploading="false" width="620" height="387" showCaption="false"}

Figura 29 — Atividades por entrega com responsáveis, datas e dependências

### Observações

- Atividade só existe dentro de entrega; agrupador não recebe atividade.
- Em planejamento, só o nome é obrigatório; a atividade sem datas ou responsável mostra o que **Falta**, e isso será conferido ao iniciar a ação.
- A atividade com subtarefas vira uma linha-resumo: mostra o período das subtarefas e o andamento delas ponderado pelo peso.
- A dependência é sempre de término para início, e pode ligar atividades de entregas diferentes da mesma ação.
- O sistema recusa a dependência que fecharia um ciclo e a dependência numa atividade que tem subtarefas (ligue as subtarefas). Também recusa criar subtarefas numa atividade que já tem dependência.
- Se a sucessora estiver planejada para começar antes do fim da predecessora, o sistema aceita e avisa **Começa antes do fim da predecessora**. Ele nunca remarca datas sozinho.
- Atividade com subtarefas não pode ser removida antes delas; as dependências da atividade removida saem junto.
- **Histórico desta atividade** mostra cada mudança, inclusive dependências incluídas ou removidas.

## 5.8 Ler o cronograma no gráfico de Gantt

ID BSC-ACE-08

### Para que serve

O cronograma não se digita: cada entrega aparece como barra-resumo no seu período, cada agrupador do primeiro início ao último fim, e as atividades e subtarefas logo abaixo da entrega. Mudou o período da entrega no escopo, a barra muda junto.

Depois que a ação é iniciada, cada barra ganha por baixo uma barra fina cinza com o período acordado na linha de base.

**Quem usa:** Gestor de Desempenho (escritório de estratégia); Diretoria de Estratégia (patrocinador/aprovador); Responsável por ação/área; Leitor/Auditor.

### Passo a passo

1. Na ficha da ação, abra a aba **Cronograma**.
2. Localize a linha vermelha que marca **Hoje**.
3. Use a seta **˅** ao lado de cada linha para recolher ou expandir entregas, agrupadores e atividades-mãe.
4. Clique numa barra de entrega ou agrupador para abrir o item do escopo; numa barra de atividade, para abrir a atividade.
5. Com a ação iniciada, escolha em **Linha de base desenhada sob as barras** qual linha de base comparar.
6. Observe as setas entre barras: são as dependências; em cor de alerta, a sucessora começa antes do fim da predecessora.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/auOojEGc9A5JSLiNFrDPl_image.png" size="62" isUploading="false" width="620" height="387" showCaption="false"}

Figura 30 — Gráfico de Gantt com barras-resumo, dependências, linha de Hoje e linha de base

### Observações

- Atividade com fim planejado já passado, não concluída nem cancelada, aparece **Atrasada**: barra vermelha e ponto vermelho. A que vence hoje só fica atrasada amanhã (calendário de Brasília).
- A atividade-mãe fica atrasada quando alguma subtarefa está.
- Barra que passou da cinza está planejada para depois do acordado; linha sem barra cinza foi criada depois daquela linha de base.
- A linha que ainda não tem período diz **Sem período ainda**.
- No celular, o gráfico rola dentro do próprio quadro, e a lista de atividades mostra nome, responsável e datas.

## 5.9 Registrar o andamento das atividades

ID BSC-ACE-09

### Para que serve

Com a ação em andamento, cada atividade sem subtarefas recebe a situação, o percentual concluído e as datas reais. É isso que alimenta o andamento das entregas e os índices de prazo da carteira.

**Quem usa:** Gestor de Desempenho (escritório de estratégia); Responsável por ação/área.

### Passo a passo

1. Na ficha da ação em andamento, abra a aba **Cronograma**.
2. Abra a atividade pela barra, pelo nome ou pela linha da lista.
3. Clique em **Registrar andamento**.
4. Escolha a **Situação**: Não iniciada, Em andamento, Concluída ou Cancelada.
5. Informe o percentual (para Em andamento) e as datas reais de início e término.
6. Salve.

### Observações

- Enquanto a ação está em planejamento, toda atividade fica **Não iniciada**.
- Concluída é sempre 100% e Não iniciada é sempre 0%: o campo se preenche e trava.
- Data real deixada em branco mantém a já registrada; para apagá-la, limpe o campo que tinha data.
- A atividade-mãe mostra a média ponderada das subtarefas e não recebe andamento próprio; subtarefa cancelada sai da média.
- O responsável pela atividade pode registrar o andamento pela Mesa de trabalho, mesmo sem permissão do módulo.

## 5.10 Planejamento financeiro mensal

ID BSC-ACE-10

### Para que serve

Ao salvar uma entrega, o sistema distribui o valor previsto igualmente pelos meses do período. Uma entrega de R$ 120.000,00 de janeiro a dezembro fica com R$ 10.000,00 em cada mês. A aba Financeiro mostra cada entrega numa linha, cada mês numa coluna e o **Total do mês** no rodapé.

**Quem usa:** Gestor de Desempenho (escritório de estratégia).

### Passo a passo

1. Na ficha da ação, abra a aba **Financeiro**.
2. Clique no lápis da entrega para abrir os meses dela.
3. Altere os valores; o rodapé mostra se os meses ainda somam o valor previsto ou a diferença.
4. Salve. Os meses ajustados ficam marcados com **\\**\* na tabela.
5. Para desfazer os ajustes, use **Distribuir igualmente de novo**.

### Observações

- Os centavos que não dividem vão para o último mês.
- O sistema exige que a soma dos meses seja igual ao valor da entrega; se não bater, recusa e mostra quanto falta ou sobra.
- Se a entrega tem meses ajustados e você muda o valor ou o período, o sistema pergunta antes e oferece **Redistribuir e salvar**.
- Período acima de 600 meses é recusado; quase sempre é ano digitado errado.

## 5.11 Ver as entregas na ficha do indicador

ID BSC-ACE-11

### Para que serve

A ligação entre entrega e indicador funciona nos dois sentidos. Na ficha do indicador, o cartão **Entregas ligadas** mostra os itens de escopo que movem aquele indicador. É por aí que a diretoria responde "esta obra atrasada afeta qual meta?".

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia); Leitor/Auditor.

### Passo a passo

1. Abra Gestão por indicadores › Indicadores e clique no indicador.
2. Localize o cartão **Entregas ligadas**.
3. Confira a ação, o código, o valor, o período e o responsável de cada entrega.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/2-8CPcQEZJAX2yX7Bi_Lv_image.png" size="62" isUploading="false" width="620" height="387" showCaption="false"}

Figura 31 — Ficha do indicador, onde aparece o cartão Entregas ligadas

### Observações

- O cartão só aparece para quem lê a carteira de ações.
- Itens de uma ação sigilosa ficam de fora para quem não pode vê-la.
- Um indicador sigiloso só pode ser ligado por quem gerencia indicadores ou a estratégia; para os demais, a ligação aparece como **Indicador sigiloso**, sem nome nem farol, e não pode ser desfeita.
- Quem lê a carteira sem acesso ao painel de desempenho vê o nome dos indicadores ligados, sem farol, meta nem realizado.

## 5.12 Iniciar a ação e gerar a linha de base nº 1

ID BSC-ACE-12

### Para que serve

A ação nasce em planejamento e é preenchida aos poucos. Quando o plano está completo, a diretoria a inicia: o sistema congela o plano como **linha de base nº 1** (escopo, cronograma com atividades e dependências, financeiro mensal) e a ação passa a **Em andamento**.

A linha de base é o acordo. Ela nasce na aprovação do plano e só muda pelo controle integrado de mudanças.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador).

### Passo a passo

1. Abra a ficha da ação **Em planejamento**.
2. Clique em **Iniciar ação**.
3. Leia a lista de verificação; cada pendência mostra o código e o nome do item onde está.
4. Se houver pendências, peça ao gestor de desempenho para corrigi-las nas abas Escopo e Cronograma e abra o painel de novo.
5. Com tudo completo, clique em **Iniciar e gerar a linha de base nº 1**.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/vtT0ixyyeg82SdAzg10B8_image.png" size="62" isUploading="false" width="620" height="387" showCaption="false"}

Figura 32 — Linha de base vigente e solicitações de mudança da ação

### Observações

- A lista de verificação exige: área responsável e gestor; pelo menos uma entrega; toda entrega com valor, período, unidade, responsável e financeiro mensal que soma o valor; todo agrupador com item abaixo, unidade e responsável; toda atividade com responsável e, se não tiver subtarefas, datas planejadas; nenhuma dependência em atividade com subtarefas.
- A operação é única: ou tudo é gravado (linha de base, situação, quem iniciou e quando), ou nada muda.
- A partir daí as atividades recebem andamento e as entregas recebem execução.

## 5.13 Comparar o plano com a linha de base

ID BSC-ACE-13

### Para que serve

Depois de iniciada, a ação continua podendo ser replanejada. O cartão **Plano × linha de base** mostra a diferença entre o plano atual e o que foi acordado, sem mudar a linha de base.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia); Leitor/Auditor.

### Passo a passo

1. Na ficha da ação iniciada, abra a aba **Visão geral**.
2. Localize o cartão **Plano × linha de base** e compare o valor total e o término acordados com os atuais.
3. Confira a lista de itens que mudaram (**Só o que mudou** vem marcado; desmarque para ver todos).
4. Use o seletor para comparar com uma linha de base anterior.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/vtT0ixyyeg82SdAzg10B8_image.png" size="62" isUploading="false" width="620" height="387" showCaption="false"}

Figura 33 — Comparação do plano atual com a linha de base

### Observações

- A diferença aparece em vermelho quando o plano ficou mais caro ou mais tarde.
- Item criado depois da linha de base aparece como **Fora da linha de base**; item retirado, como **Removido do plano**.
- A linha de base nunca é editada nem apagada.

## 5.14 Solicitar e decidir uma mudança (nova linha de base)

ID BSC-ACE-14

### Para que serve

Uma nova linha de base (nº 2, nº 3…) só nasce de uma solicitação de mudança aprovada pela diretoria. As linhas de base anteriores continuam disponíveis para comparação.

**Quem usa:** Gestor de Desempenho (escritório de estratégia); Diretoria de Estratégia (patrocinador/aprovador).

### Passo a passo

1. Com a ação em andamento, replaneje primeiro o que for preciso (escopo, cronograma, financeiro).
2. Na ficha, abra a aba **Mudanças** e clique em **Nova solicitação de mudança**.
3. Informe a **Necessidade**, a **Motivação** e o impacto em custo (R$, negativo se economiza), prazo (dias) e escopo.
4. Clique em **Enviar à diretoria**.
5. A diretoria abre a solicitação e escolhe **Aprovar** ou **Recusar** (a recusa exige a observação do motivo).
6. Enquanto a solicitação aguarda, o gestor pode **Retirar** a própria solicitação.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/vtT0ixyyeg82SdAzg10B8_image.png" size="62" isUploading="false" width="620" height="387" showCaption="false"}

Figura 34 — Aba Mudanças com as solicitações e a linha de base vigente

### Observações

- Aprovar gera, na mesma operação, a próxima linha de base com o plano como está naquele momento. Por isso, replaneje antes de pedir a aprovação.
- Recusar ou retirar não muda a linha de base vigente.
- Só uma solicitação aguarda decisão por vez.
- Solicitações só são abertas e aprovadas com a ação em andamento.
- Quem abre a solicitação não a aprova: são papéis separados.

## 5.15 Suspender, retomar, concluir ou cancelar a ação

ID BSC-ACE-15

### Para que serve

As mudanças de situação são atos da diretoria e sempre pedem o motivo, que fica na ficha (**Motivo da última mudança de situação**) e no histórico.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador).

### Passo a passo

1. Abra a ficha da ação.
2. Use o botão ao lado da situação: **Suspender**, **Retomar**, **Concluir** ou **Cancelar ação**.
3. Informe o motivo.
4. Confirme.

### Observações

- Suspensa, nada do plano nem da execução pode ser alterado: dados, GUT, escopo, financeiro, atividades, andamento e solicitações ficam somente leitura.
- Retomar volta a Em andamento com a mesma linha de base.
- Concluir vale para ação em andamento; cancelar vale para ação em planejamento, em andamento ou suspensa. Depois disso, a ação fica somente leitura para sempre, com linhas de base e histórico disponíveis.
- Solicitação de mudança pendente precisa ser decidida ou retirada antes de concluir ou cancelar.
- Se outra pessoa mudou a situação enquanto a tela estava aberta, recarregue a página.

## 5.16 Execução física e financeira das entregas

ID BSC-ACE-16

### Para que serve

Com a ação em andamento, cada entrega é acompanhada na aba **Entregas**: o valor planejado na linha de base, o planejado no plano atual, o executado e o percentual concluído. No topo aparecem os mesmos números da ação inteira; o percentual da ação é a média das entregas ponderada pelo valor de cada uma.

**Quem usa:** Gestor de Desempenho (escritório de estratégia); Responsável por ação/área.

### Passo a passo

1. Na ficha da ação em andamento, abra a aba **Entregas**.
2. Clique na entrega para abrir o detalhe.
3. Clique em **Registrar execução**.
4. Informe a **data**, o **valor executado**, o **percentual físico acumulado** (0 a 100) ou os dois, e uma observação.
5. Salve e confira o executado e o percentual da entrega.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/TwPd0l_RoJZt1qZcpQeAp_image.png" size="62" isUploading="false" width="620" height="387" showCaption="false"}

Figura 35 — Aba Entregas com planejado, executado e percentual físico

### Observações

- O executado da entrega é a soma dos valores; o percentual é o da linha mais recente que informou um, porque é acumulado.
- Sem nenhum percentual informado, vale a média das atividades da entrega ponderada pelo peso.
- Linha manual pode ser editada e removida enquanto a ação está em andamento.
- Execuções só entram com a ação em andamento.
- O responsável pela entrega lê a entrega e as evidências; para registrar sem a permissão do cargo, use a Mesa de trabalho.
- A soma da aba Entregas pode diferir do orçado da carteira: a carteira mede contra a linha de base aprovada, a aba lista o plano atual.

## 5.17 Evidências da execução

ID BSC-ACE-17

### Para que serve

A evidência é o documento que comprova a execução de uma atividade ou a efetivação de uma entrega: a foto da obra, o termo de recebimento, o processo administrativo no SEI.

**Quem usa:** Gestor de Desempenho (escritório de estratégia); Responsável por ação/área.

### Passo a passo

1. Na aba **Entregas**, abra a entrega.
2. Clique em **Registrar evidência**.
3. Informe uma **descrição** e/ou um **link** (endereço completo, começando com http\:// ou https\://, como o endereço do processo no SEI).
4. Informe a **data** e, se quiser, a **atividade** da entrega a que a evidência se refere.
5. Anexe os **arquivos** no mesmo formulário ou depois, na própria evidência.
6. Salve.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/TwPd0l_RoJZt1qZcpQeAp_image.png" size="62" isUploading="false" width="620" height="387" showCaption="false"}

Figura 36 — Detalhe da entrega com execuções e evidências

### Observações

- A evidência precisa de descrição ou link; os arquivos podem entrar depois.
- Evidências só entram com a ação em andamento.
- Cada evidência tem o próprio histórico, e todas entram no histórico da ação, com o mesmo sigilo.
- Para vincular a execução à conclusão de um processo do SEI de forma automática, use a execução automatizada com a fonte Processo SEI.

## 5.18 Comentários na entrega e na ação

ID BSC-ACE-18

### Para que serve

A **Discussão** troca recados sobre uma entrega ou sobre a ação inteira e avisa as pessoas certas no sino e, se a preferência mandar, por e-mail.

**Quem usa:** Gestor de Desempenho (escritório de estratégia); Responsável por ação/área; Diretoria de Estratégia (patrocinador/aprovador).

### Passo a passo

1. Para falar de uma entrega, abra-a na aba **Entregas** e escreva na **Discussão**.
2. Para falar da ação inteira, use a **Discussão** no fim da aba **Visão geral**.
3. Publique o comentário.

### Observações

- O comentário na entrega avisa o responsável pela entrega (mesmo que nunca tenha comentado) e quem já participa da conversa e ainda pode lê-la; nunca quem escreveu.
- O comentário na ação avisa o gestor da ação e os participantes da conversa.
- Os avisos **Comentário em entrega** e **Comentário em ação estratégica** são distintos e podem ser ligados ou desligados separadamente nas preferências de notificação.
- Quem perdeu o acesso à ação (por exemplo, ela virou sigilosa) deixa de receber o aviso.
- Comentar é possível em qualquer situação da ação.

## 5.19 Execução automatizada: lançamentos contábeis e indicador

ID BSC-ACE-19

### Para que serve

Parte da execução já existe em outro sistema e não deve ser digitada de novo. O cartão **Execução automatizada** liga a entrega, ou cada atividade dela, a uma fonte, e o sistema busca os dados novos todos os dias.

Esta seção cobre duas fontes: os lançamentos contábeis do projeto do cadastro (dinheiro) e os resultados de um indicador (percentual).

**Quem usa:** Gestor de Desempenho (escritório de estratégia).

### Passo a passo

1. Na aba **Entregas**, abra a entrega (ou a atividade dela).
2. No cartão **Execução automatizada**, clique em **Automatizar**.
3. Para entregas, escolha **Lançamentos contábeis do projeto do cadastro** e, se quiser, o projeto; sem escolher, vale o projeto da ação no momento em que você salva.
4. Para entregas ou atividades, escolha **Resultados de um indicador (percentual)** e o indicador que mede o andamento (por exemplo, Avanço físico da Ponte do Vale).
5. Salve e use **Sincronizar agora** para trazer os dados na hora.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/TwPd0l_RoJZt1qZcpQeAp_image.png" size="62" isUploading="false" width="620" height="387" showCaption="false"}

Figura 37 — Cartão de execução automatizada no detalhe da entrega

### Observações

- Lançamentos contábeis: cada mês vira uma linha integrada com o valor lançado (débito menos crédito). Lançamento atrasado num mês já sincronizado também é trazido. Contam os lançamentos de todas as empresas do grupo que usam o projeto.
- Trocar depois o projeto da ação não muda a fonte gravada; para seguir outro projeto, altere a configuração.
- O razão contábil mede dinheiro e só alimenta entregas; para atividade, use um indicador.
- Indicador: só aprovado, não sigiloso e com resultados de 0 a 100. Isso é conferido a cada sincronização; se deixar de valer, a sincronização falha e nada é copiado.
- Numa atividade, o resultado 100 a conclui, com o fim do período como término real. A retificação de um período antigo não faz a atividade voltar.
- O resultado entra pela data em que foi gravado e a sincronização vai até ontem: o gravado hoje chega amanhã.
- Atividade alimentada por fonte ligada não recebe subtarefas; desligue a execução automatizada antes de detalhá-la.

## 5.20 Execução automatizada: conclusão de processo do SEI

ID BSC-ACE-20

### Para que serve

Quando uma entrega ou atividade é executada por um processo administrativo no SEI, a fonte **Processo SEI (conclusão)** acompanha o processo: concluído o processo, a entrega ou a atividade vai a 100%.

O SEI aqui é um tipo de integração cadastrado no Hub de integrações.

**Quem usa:** Gestor de Desempenho (escritório de estratégia); Analista de Integração de Dados.

### Passo a passo

1. Na aba **Entregas**, abra a entrega (ou a atividade).
2. No cartão **Execução automatizada**, clique em **Automatizar** e escolha **Processo SEI (conclusão)**.
3. Escolha a **integração SEI** cadastrada no Hub de integrações.
4. Informe o **número do processo** como o SEI mostra (por exemplo, 00000.000123/2026-01).
5. Salve e acompanhe o resultado no cartão.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/-GBQac1XnXOBwPg7vJ2QJ_image.png" size="62" isUploading="false" width="620" height="387" showCaption="false"}

Figura 38 — Hub de integrações, onde a integração SEI é cadastrada e testada

### Observações

- O processo é considerado concluído quando nenhuma unidade o mantém aberto. A entrega ou atividade vai a 100% na data do último andamento, que vira o término real.
- Processo concluído hoje chega na sincronização de amanhã; enquanto estiver aberto, nada muda.
- A lista mostra todas as integrações SEI ativas: a que ainda não passou no **Testar** aparece desabilitada, com o motivo; a do ambiente de simulação para treinamento e homologação leva o selo **Simulador**.
- Processo sigiloso, de unidade a que o usuário de serviço não tem acesso ou inexistente dá a mesma falha: **Processo não encontrado ou sem acesso no SEI**. Nada é copiado nem mostrado.
- Cada leitura do SEI também fica registrada como execução da integração.

## 5.21 Sincronização, falhas e correção de linhas integradas

ID BSC-ACE-21

### Para que serve

Todo dia, de madrugada, o sistema busca nas fontes o que há de novo até ontem, grava cada linha marcada como **Integração** e atualiza os totais. Esta seção explica como acompanhar a sincronização e como corrigir um valor integrado sem apagar o que veio da fonte.

**Quem usa:** Gestor de Desempenho (escritório de estratégia); Responsável por ação/área; Analista de Integração de Dados.

### Passo a passo

1. No detalhe da entrega, confira no cartão até que dia os dados estão sincronizados, a última execução e o resultado.
2. Clique em **Sincronizar agora** para buscar na hora.
3. Abra **Log de sincronização** para ver cada execução: início, fim, se foi diária ou manual, linhas gravadas e dias pedidos.
4. Para discordar de um valor integrado, clique em **Corrigir** na linha e informe o valor correto.
5. Para trocar a fonte ou os parâmetros, use **Alterar** no cartão.
6. Para pausar, desmarque **Ligada** em **Alterar**; para retomar, marque de novo.

### Observações

- Rodar de novo não duplica nada.
- Na falha, o cartão fica vermelho com o motivo e a data sincronizada não avança; na execução seguinte, todos os dias pendentes são pedidos de novo.
- Se a ação for suspensa ou a configuração alterada durante a leitura, nada é gravado e isso não conta como falha.
- Linha integrada nunca é editada nem removida. A corrigida fica riscada com o selo **Corrigida — não soma**, e a correção soma no lugar dela; remover a correção traz o valor integrado de volta.
- Trocar a fonte ou os parâmetros recomeça do zero: todas as linhas integradas antigas saem, inclusive as corrigidas com as suas correções. As execuções manuais ficam.
- Desligar e ligar mantém a data; ao religar, o sistema recupera os dias em que ficou desligada.

## 5.22 Carteira consolidada: o que a tela mostra

ID BSC-ACE-22

### Para que serve

A tela **Ações estratégicas** é a carteira consolidada: num lugar só, a prioridade GUT, as atividades iniciadas, atrasadas e concluídas, o orçado e o realizado de cada ação, e os índices de desempenho de escopo, prazo e custo.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia); Leitor/Auditor.

### Passo a passo

1. Abra Gestão por indicadores › Ações estratégicas.
2. Leia as colunas: **Código**, **Título** (com categoria e gestor), **Situação**, **GUT**, **Iniciadas**, **Atrasadas**, **Concluídas**, **Orçado**, **Realizado**, **Orçado − realizado**, **% financeiro**, **% físico** e **IDE · IDP · IDC**.
3. Passe o mouse sobre as siglas dos índices para ver a fórmula.
4. Confira na última linha os totais de todas as ações filtradas, de todas as páginas.
5. Clique na linha (ou no código) para abrir a ficha da ação.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/sQUCp5IWSj71PTcrL3iVM_image.png" size="62" isUploading="false" width="620" height="387" showCaption="false"}

Figura 39 — Carteira consolidada com GUT, atividades, orçado, realizado e índices

### Observações

- Atividades contam só as que não têm subtarefas. Atrasadas são as com fim planejado antes de hoje, não concluídas nem canceladas; uma atividade em andamento e atrasada conta nas duas colunas.
- Orçado é o total da linha de base vigente (abaixo: linha de base nº N). Sem linha de base, é a soma do plano, marcada **planejado (sem linha de base)**.
- Realizado é a soma das execuções das entregas; % físico é a média das entregas ponderada pelo valor.
- IDE = entregas concluídas ÷ entregas previstas na linha de base com fim até hoje. IDP = andamento ponderado das atividades da linha de base com fim até hoje. IDC = realizado ÷ orçamento mensal da linha de base até o mês atual.
- Em planejamento os índices mostram **não se aplica**; se nada vencia ainda, **n.a.**.
- Ação sigilosa só entra na tela, nos totais e no arquivo para o gestor dela e para quem gerencia a carteira.
- No celular, a tabela rola de lado dentro do próprio quadro.

## 5.23 Carteira: ordenar, filtrar e exportar

ID BSC-ACE-23

### Para que serve

A carteira pode ser ordenada por qualquer coluna, filtrada por vários critérios e exportada para planilha, sempre valendo para a carteira inteira e não só para a página aberta.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia); Leitor/Auditor.

### Passo a passo

1. Abra Gestão por indicadores › Ações estratégicas.
2. Clique no título de uma coluna para ordenar; clique de novo para inverter.
3. Use **Shift+clique** para acrescentar uma segunda ordem.
4. No cartão **Filtrar a carteira**, use **Buscar por código ou título**, **Situação**, **Categoria**, **Programa**, **Área responsável**, **Gestor da ação** e **Só com atividades atrasadas**.
5. Em **Mais filtros**, informe a faixa da GUT (1 a 125), os mínimos de atividades e as faixas de **Orçado** e **Realizado**.
6. Se nada atender, use **Limpar filtros**.
7. Clique em **Exportar CSV** para baixar a vista filtrada.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/sQUCp5IWSj71PTcrL3iVM_image.png" size="62" isUploading="false" width="620" height="387" showCaption="false"}

Figura 40 — Filtros, ordenação e exportação da carteira

### Observações

- Retirando a última ordem, a tabela volta à ordem padrão por GUT, maior primeiro.
- % físico e índices são calculados só para a página aberta e por isso não ordenam.
- O filtro de programa inclui os subprogramas; ação não avaliada fica fora de qualquer faixa de GUT.
- Faixa ao contrário ou número não inteiro na GUT e nos mínimos de atividades é recusado com **Filtro inválido**.
- O arquivo leva a data no nome, traz na primeira linha até que dia os atrasos foram contados e acrescenta as três notas GUT, o gestor, a área e a origem do orçado.
- Em português, o arquivo usa ponto e vírgula e vírgula decimal e abre direto em colunas no Excel ou no LibreOffice.
- Cabem até 10.000 ações por arquivo; acima disso, estreite os filtros e exporte em partes.

## 5.24 Histórico da ação

ID BSC-ACE-24

### Para que serve

A aba **Histórico** guarda toda alteração da ação e dos registros dela, com o antes, o depois, quem fez e quando. Enquanto a linha de base é o acordo, o histórico é a trilha de cada edição.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia); Leitor/Auditor.

### Passo a passo

1. Na ficha da ação, abra a aba **Histórico**.
2. Percorra a lista, da alteração mais recente para a mais antiga, com o tipo do registro, o nome, o autor e a data.
3. Clique numa linha para ver os **Valores iniciais** (criação) ou os **Campos alterados** com **Antes** e **Depois**.
4. Use **Mostrar alterações mais antigas** para trazer a página seguinte.

### Observações

- Entram itens de escopo, atividades, dependências, linhas de base, solicitações de mudança, execuções, evidências e execuções automatizadas, inclusive os já excluídos.
- Categoria, área, gestor e programa aparecem pelo nome, não por código.
- O histórico de ação sigilosa segue o sigilo: quem não pode ver a ação não vê a trilha dela nem de nenhum item dela. O auditor continua vendo tudo.
- Cada categoria, dimensão, item, atividade, dependência, execução e evidência também tem o seu próprio relógio de histórico.

## 5.25 Riscos da ação estratégica

ID BSC-ACE-25

### Para que serve

A ação estratégica não tem classificação de risco própria: um risco da ação é um risco do registro de riscos da empresa, vinculado à ação. Assim o mesmo risco aparece na matriz da empresa e na ação, com a mesma avaliação e os mesmos tratamentos.

**Quem usa:** Gestor de Desempenho (escritório de estratégia); Diretoria de Estratégia (patrocinador/aprovador); Leitor/Auditor.

### Passo a passo

1. Na ficha da ação, abra a aba **Riscos**.
2. Leia o **Mapa de riscos desta ação**: cada risco na posição inerente, com a seta até a residual planejada.
3. Confira em **Riscos vinculados** a situação, as avaliações e os tratamentos de cada risco.
4. Para vincular, clique em **Vincular risco**, busque por código ou título (por exemplo, Atraso na emissão de licenças ambientais da Ponte do Vale) e clique em **Vincular**.
5. Para desvincular, clique em **Desvincular** e confirme.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/GekwtZ7nDDUwgKdY-x8CO_image.png" size="62" isUploading="false" width="620" height="387" showCaption="false"}

Figura 41 — Matriz de calor no padrão do registro de riscos

### Observações

- Riscos encerrados e já vinculados não aparecem na busca. O risco que ainda não existe é cadastrado no Registro de riscos.
- Um risco pode estar ligado a um objetivo e à ação ao mesmo tempo; no mapa da empresa ele aparece uma vez.
- Desvincular não apaga o risco; o histórico do risco registra a inclusão e a remoção.
- Ação concluída ou cancelada não aceita vincular nem desvincular.
- Risco sigiloso fica fora da lista, da matriz e das contagens para quem não pode vê-lo; quem não lê riscos vê um aviso, não uma matriz vazia.
- Vincular e desvincular são de quem gerencia riscos; a evolução dos tratamentos é lançada pelo responsável na Mesa de trabalho.

## 5.26 Perfis de acesso e sigilo da carteira

ID BSC-ACE-26

### Para que serve

A carteira divide o trabalho entre três perfis: a diretoria decide (inicia, aprova mudança, encerra), o gestor de desempenho monta e mantém o plano, e o analista lê e registra a execução. Ações sigilosas restringem ainda mais quem vê.

**Quem usa:** Administrador do sistema; Diretoria de Estratégia (patrocinador/aprovador).

### Passo a passo

1. Abra Início › Alçada.
2. Localize as permissões pelo nome, como \*Ver a carteira de ações estratégicas\*, \*Cadastrar e editar ações estratégicas\* e \*Manter categorias e classificações das ações estratégicas\*.
3. Confira a quais cargos cada permissão está ligada e ajuste conforme a estrutura da organização.
4. Para marcar uma ação como sigilosa, edite a ação e marque **Sigilosa**.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/X9ysGv29hbyr4whrYzjRU_image.png" size="62" isUploading="false" width="620" height="387" showCaption="false"}

Figura 42 — Alçada com as regras de autorização por cargo

### Observações

- Diretoria de Estratégia: mantém categorias e classificações, lê a carteira, inicia, suspende, retoma, conclui e cancela ações e decide as solicitações de mudança. Não edita o plano.
- Gestor de Desempenho: cadastra e edita ações, avalia a GUT, monta escopo, financeiro e atividades, registra execuções e evidências, configura a execução automatizada e abre solicitações de mudança. Não inicia a ação nem aprova a própria solicitação. Vê todas as ações, inclusive as sigilosas.
- Analista Operacional: lê tudo sem botões de edição do plano; registra andamento, execuções e evidências de ação em andamento, corrige linha integrada e pede **Sincronizar agora**.
- As permissões já chegam ligadas a esses cargos. Num órgão em que ninguém ocupa esses cargos, a carteira fica fechada até o administrador atribuir os cargos ou religar as operações; quem não tem a permissão vê **Você não tem acesso a isto**.
- Uma operação sem nenhuma regra ativa volta a ser liberada a qualquer usuário autenticado.
- Ação sigilosa só aparece para o gestor da ação e para quem gerencia a carteira; pelo endereço direto, os demais leem **Ação estratégica não encontrada**.

[title]  2. Estratégia: ciclos, objetivos e mapa estratégico
[path] Aplicações/BSC/

A estratégia da empresa vive num **ciclo estratégico**: a versão do plano para um período, com a identidade institucional (missão, visão e valores), as perspectivas, os objetivos e a régua que decide a cor dos faróis. Este capítulo mostra como criar e ativar o ciclo, organizar as perspectivas, cadastrar e desdobrar objetivos, manter os cadastros estratégicos (programas, ODS, classificações, regiões, sistemas externos e áreas) e ler o **Mapa estratégico**.

O exemplo usado é o **Ciclo Estratégico 2026 — Empresa Exemplo** (1/1/2026 a 31/12/2026), com as perspectivas Clientes e sociedade, Resultados financeiros, Processos internos e Aprendizado e crescimento.

## 2.1 Criar um ciclo estratégico

ID BSC-EST-01

### Para que serve

Cada ciclo é um mapa estratégico da empresa para um período. Ao criá-lo, você escolhe a **lente** de gestão — Balanced Scorecard (BSC), OKR ou Gestão por Diretrizes (GPD). A lente muda o vocabulário e a forma de pontuar o atingimento, mas não muda os dados.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador).

### Passo a passo

1. Abra **Gestão por indicadores › Planejamento estratégico**. A lista **Mapas estratégicos (ciclos de planejamento)** mostra nome, período, lente e situação de cada ciclo.
2. Clique em **Novo mapa estratégico**.
3. Informe o **nome** (por exemplo, **Ciclo Estratégico 2026 — Empresa Exemplo**).
4. Informe o **período**: 01/01/2026 a 31/12/2026.
5. Escolha a **lente**: Balanced Scorecard (BSC), OKR ou Gestão por Diretrizes (GPD).
6. Salve. O ciclo aparece na lista com a situação **Rascunho**.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/Gwhx-V4LhpvRLNP6qt2ld_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 6 — Lista de ciclos estratégicos, com nome, período, lente e situação.

### Observações

- A lente pode ser trocada a qualquer momento enquanto o ciclo não estiver fechado.
- Na lente Gestão por Diretrizes as perspectivas são chamadas de **Eixos estratégicos**; na lente OKR, de **Temas**.

## 2.2 Ativar e fechar o ciclo

ID BSC-EST-02

### Para que serve

O ciclo passa por três situações: **Rascunho**, **Ativo** e **Fechado**. Só um ciclo ativo aceita objetivos, indicadores e apurações. Ao fim do exercício, fechar o ciclo congela o plano para comparação com os próximos.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador).

### Passo a passo

1. Em **Gestão por indicadores › Planejamento estratégico**, localize o ciclo em **Rascunho**.
2. Clique em **Ativar** (a seta na linha do ciclo ou o botão dentro do ciclo). A situação passa a **Ativo**.
3. Trabalhe o plano durante o exercício: objetivos, indicadores, metas e apurações.
4. Ao fim do exercício, abra o ciclo e clique em **Fechar**. O ciclo passa a ser somente leitura.

### Observações

- Mensagem “Objetivos só podem ser alterados enquanto o ciclo está ativo.”: o ciclo está em Rascunho ou já foi Fechado. Ative-o ou, se estiver fechado, trabalhe no próximo ciclo.
- Um ciclo fechado não é reaberto: ele é a fotografia do que foi pactuado.

## 2.3 Identidade institucional

ID BSC-EST-03

### Para que serve

O cartão **Identidade institucional**, no topo do ciclo, guarda a **Missão**, a **Visão**, os **Valores** e a **Descrição institucional** do plano. Esses textos aparecem também na faixa superior do Mapa estratégico.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador).

### Passo a passo

1. Em **Gestão por indicadores › Planejamento estratégico**, clique no nome do ciclo.
2. No cartão **Identidade institucional**, clique em **Editar identidade**.
3. Preencha **Missão**, **Visão**, **Valores** e **Descrição institucional**. Cada campo mostra quantos caracteres ainda cabem.
4. Salve.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/hb52-XCX_GXqHaOYKl__9_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 7 — Ciclo aberto com a identidade institucional, as perspectivas e os objetivos.

### Observações

- Todos os campos são opcionais; apagar o texto e salvar limpa o campo.
- Quem só lê o painel vê o cartão sem o botão de edição.
- Num ciclo fechado a identidade não muda mais.

## 2.4 Perspectivas (eixos estratégicos)

ID BSC-EST-04

### Para que serve

O ciclo nasce com as quatro perspectivas clássicas do Balanced Scorecard, como ponto de partida. Você as renomeia, reordena, colore, acrescenta ou remove para refletir o seu plano. A cor de cada perspectiva pinta a faixa dela no mapa estratégico.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador).

### Passo a passo

1. Abra o ciclo em **Gestão por indicadores › Planejamento estratégico**.
2. Na seção de perspectivas, clique no lápis (**Editar nome e cor**) de uma perspectiva.
3. Renomeie (por exemplo, **Clientes e sociedade**) e escolha a **Cor no mapa estratégico**.
4. Para voltar à cor original da posição, marque **Usar a cor padrão da posição**.
5. Use as setas para reordenar, deixando no topo a perspectiva de maior valor para o plano.
6. Adicione as perspectivas que faltarem e remova as que não usar.

### Observações

- As perspectivas padrão vêm com nomes em inglês de propósito: elas existem para serem renomeadas.
- Objetivo sem perspectiva vai para a faixa **Sem perspectiva** no fim do mapa.

## 2.5 Régua de desempenho

ID BSC-EST-05

### Para que serve

A **Régua de desempenho** define como o farol de todo o plano é decidido. Ela vale para o Painel de desempenho, o Painel gerencial, o Mapa estratégico e o aviso automático de desvio.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador).

### Passo a passo

1. Abra o ciclo e localize o cartão **Régua de desempenho**.
2. Clique em **Editar régua**.
3. Escolha **Pela tolerância de cada meta** (verde na meta, amarelo dentro da tolerância da meta, vermelho além dela) ou **Pelo percentual de atingimento da meta**.
4. No modo por percentual, informe o mínimo do verde e o mínimo do amarelo (o padrão é 100% e 85%).
5. Escolha a cor de cada faixa, inclusive a de **Não informado** (sem meta ou sem medição). **Cor padrão** volta à cor original.
6. Salve.

### Observações

- O percentual respeita o sentido do indicador: num indicador “menor é melhor” com meta 4,2 e realizado 4,6, o atingimento é 91,3%. Num indicador “no alvo”, passar da meta penaliza tanto quanto ficar abaixo.
- O aviso automático de desvio dispara no que a régua chama de vermelho.
- A cor nunca aparece sozinha: o rótulo da faixa vai junto.

## 2.6 Criar objetivos do plano

ID BSC-EST-06

### Para que serve

Os objetivos são pendurados nas perspectivas e medidos pelos indicadores. Cada objetivo tem nível (Missão, Visão, Estratégico, Tático ou Operacional), tipo de aferição e situação no ciclo de vida.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador).

### Passo a passo

1. Abra o ciclo ativo e, na seção **Objetivos**, clique em **Novo objetivo**.
2. Informe o **Título** (por exemplo, **Ampliar a capacidade da Rodovia Norte**) e a **Descrição**.
3. Escolha o **Nível**: Missão, Visão, Estratégico, Tático ou Operacional.
4. Escolha a **Perspectiva** (por exemplo, Processos internos).
5. Opcionalmente, informe a **Área** (por exemplo, DIROB — Diretoria de Obras) e o **Responsável**.
6. Em **Aferição**, escolha Quantitativo ou Qualitativo.
7. Em **Situação**, deixe **Ativo** ou escolha Suspenso, Alcançado ou Cancelado.
8. Salve. O objetivo aparece na lista do ciclo, com a situação.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/lI4q8NeJgE0Onyox6tRgN_image.png" size="62" isUploading="false" width="620" height="387" showCaption="false"}

Figura 8 — Ficha do objetivo, com indicadores, ações e vínculos.

### Observações

- Cadastre a Missão e a Visão como objetivos dos seus níveis, para que o plano não comece direto no estratégico.
- O nível é descritivo: quem liga um objetivo a outro é o **Desdobrar**, não o nível.
- A situação é uma declaração de quem gere o plano e é separada do farol: um objetivo Suspenso continua apurado e com farol calculado.
- Um objetivo sem responsável também é válido.

## 2.7 Desdobramento em cascata e pesos

ID BSC-EST-07

### Para que serve

O desdobramento liga um objetivo de cima aos objetivos táticos e operacionais que o sustentam. O resultado de cada objetivo de baixo sobe **ponderado pelo peso** até o objetivo de cima. Um objetivo-filho pode sustentar mais de um pai: o desdobramento é uma teia, não uma árvore.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador).

### Passo a passo

1. No ciclo ativo, clique em **Desdobrar**.
2. No formulário **Desdobrar objetivo**, escolha o **Objetivo-pai (acima)** e o **Objetivo-filho (abaixo)**.
3. Escolha o **Tipo de vínculo**: Desdobramento, Causa e efeito ou Apoio.
4. Informe o **Peso** do filho na conta do pai.
5. Salve e confira o resultado em **Gestão por indicadores › Painel gerencial**, no bloco **Mapa estratégico**.
6. Para ver separado o resultado próprio e o consolidado, use **Fixar no meu painel** no cartão do objetivo e consulte **Meu painel** (colunas **Próprio** e **Consolidado**).

### Observações

- Exemplo: um objetivo sem indicador próprio, com dois filhos de peso 3 e 1 medidos em 100% e 20%, fecha em 80% — não em 60%.
- Se o pai tem indicador próprio, o resultado dele entra na conta com peso 1.
- Peso em branco vale 1. Peso 0 ou negativo tira o filho da conta em silêncio; no mapa ele aparece com a marca **não consolida**.
- O farol de um objetivo é o pior caso entre os indicadores dele mesmo e não é herdado dos filhos. Objetivo sem indicador próprio mostra **Sem meta**, mesmo com consolidado alto.
- Objetivo sem nenhuma medição mostra “—”, nunca 0%.

## 2.8 Cadastros estratégicos: programas e subprogramas

ID BSC-EST-08

### Para que serve

A tela **Cadastros estratégicos** guarda o vocabulário em que o plano é escrito. Em **Programas** ficam os programas e subprogramas da empresa (por exemplo, PROROD — Programa Rodoviário, com os subprogramas Rodovia Norte e Ponte do Vale), com os planos a que pertencem, os ODS para os quais contribuem, as áreas envolvidas e os códigos em sistemas externos.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Leitor/Auditor.

### Passo a passo

1. Abra **Gestão por indicadores › Cadastros estratégicos** e a aba **Programas**.
2. Clique em **Novo programa** e informe **Código** (por exemplo, PROROD), **Nome** e **Descrição**.
3. Para um subprograma, escolha o programa em **Subprograma de**.
4. Marque os **Planos estratégicos** a que o programa pertence.
5. Marque os **Objetivos de Desenvolvimento Sustentável** para os quais ele contribui.
6. Em **Áreas do programa**, inclua as áreas como **Direta** (responde pelo resultado) ou **Transversal** (contribui).
7. Em **Códigos em sistemas externos**, informe, por exemplo, o número do processo no SEI.
8. Salve.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/hPjvhqsP4ICPpEJym_ot8_image.png" size="62" isUploading="false" width="620" height="387" showCaption="false"}

Figura 9 — Cadastros estratégicos: programas, ODS, classificações, regiões, sistemas externos e áreas.

### Observações

- O código é gravado em maiúsculas.
- A hierarquia tem dois níveis: subprograma não tem subprogramas.
- O mesmo programa atravessa planos: ligue-o ao próximo ciclo em vez de recriá-lo.
- Um código externo identifica um único programa; repetir o mesmo número do SEI em dois programas é recusado.
- Nada é apagado nos cadastros estratégicos: **Inativar** tira o item das novas escolhas e mantém os vínculos existentes.

## 2.9 ODS, classificações de entrega, regiões e sistemas externos

ID BSC-EST-09

### Para que serve

As demais abas de **Cadastros estratégicos** mantêm listas de apoio. A aba **ODS** traz os 17 Objetivos de Desenvolvimento Sustentável da Agenda 2030 e o objetivo 18 (igualdade étnico-racial), marcado como **Nacional**. As abas de **classificações de entrega**, **regiões** e **sistemas externos** são mantidas pela empresa.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Leitor/Auditor.

### Passo a passo

1. Abra **Gestão por indicadores › Cadastros estratégicos**.
2. Consulte a aba **ODS** para ver os objetivos disponíveis.
3. Na aba desejada (classificações de entrega, regiões ou sistemas externos), clique em **Novo item**.
4. Informe código, nome e descrição. Na classificação de entrega, informe também o **Nível** (estratégico, tático ou operacional).
5. Salve. Para retirar um item de uso, use **Inativar**.

### Observações

- Os ODS são fixos: ninguém cria, renomeia ou apaga um ODS.
- O código não se repete dentro do mesmo cadastro.
- O produto já vem com os sistemas externos **SEI** e **gov.br**. O cadastro de sistemas externos é usado também pelos indicadores importados.

## 2.10 Áreas do plano

ID BSC-EST-10

### Para que serve

As áreas do plano são as unidades do organograma (por exemplo, DIRPLAN, DIROB, SUPLAN, GEOBR). A aba **Áreas** define quais níveis da estrutura contam como área no plano.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Administrador do sistema.

### Passo a passo

1. Abra **Gestão por indicadores › Cadastros estratégicos** e a aba **Áreas**.
2. Marque os níveis da estrutura que contam como área (por exemplo, superintendência, gerência, supervisão).
3. Salve.
4. Para inativar uma unidade extinta, abra **Administração › Departamentos**, entre no departamento e use **Desativar**.

### Observações

- Sem nenhum nível marcado, toda unidade ativa conta como área.
- A unidade desativada sai das escolhas novas e continua nomeando os objetivos antigos.

## 2.11 Programas e áreas do objetivo e do indicador

ID BSC-EST-11

### Para que serve

O objetivo e o indicador podem ser ligados aos programas que atendem. É assim que um indicador tático ou operacional aparece por programa nos relatórios, e que cada área sabe se responde diretamente pelo objetivo ou se apenas contribui.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia).

### Passo a passo

1. Abra a ficha do objetivo a partir do ciclo ativo.
2. No cartão **Programas e áreas**, inclua os programas (por exemplo, PROROD) e as áreas, cada um com o seu **Responsável**.
3. Marque cada área como direta ou transversal e salve.
4. Na ficha do indicador, use o cartão **Programas medidos** para indicar quais programas e subprogramas o indicador mede.

### Observações

- Programas e áreas do objetivo só mudam com o ciclo **ativo**.
- O cartão **Programas medidos** do indicador é editado pelo Gestor de Desempenho.

## 2.12 Mapa estratégico: infográfico e sinalizadores

ID BSC-EST-12

### Para que serve

O **Mapa estratégico** desenha o plano inteiro numa tela: uma linha por eixo (na cor da perspectiva), com os objetivos dentro. Cada cartão de objetivo mostra o atingimento, a faixa da régua, os programas ligados e sinais de atraso. O mapa se atualiza sozinho a cada minuto; a linha **Atualizado às …** mostra a hora da última leitura.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia); Leitor/Auditor.

### Passo a passo

1. Abra **Gestão por indicadores › Mapa estratégico**.
2. No topo, escolha o plano (na primeira vez vem o plano ativo; a escolha fica lembrada).
3. Na aba **Infográfico**, leia cada eixo e os objetivos dentro dele.
4. Passe o mouse sobre um objetivo para ver o **Planejado** e o **Realizado** das ações.
5. Leia os sinais acesos no cartão: **Indicadores**, **Ações**, **Planos de ação** e **Riscos**.
6. Em **Sinalizadores**, ligue ou desligue cada tipo de sinal, inclusive **Planejado × realizado**.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/F8NvQRvRDT798jb98s0Fz_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 10 — Mapa estratégico com eixos, objetivos, atingimento e sinalizadores.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/_-YDUv6x2jEHOJFd3q5aX_image.png" size="21" isUploading="false" width="208" height="451" darkWidth="208" darkHeight="451" showCaption="false"}

Figura 11 — Mapa estratégico no celular.

### Observações

- Sinal de **Indicadores**: abaixo da meta no último período ou período vencido sem apuração além da folga do indicador.
- Sinal de **Ações**: ação 5W2H vencida sem conclusão ou com início vencido sem andamento; ação estratégica com ao menos uma atividade vencida.
- Sinal de **Planos de ação**: período encerrado, ação atrasada ou nenhum andamento depois do início.
- Sinal de **Riscos**: riscos ativos vinculados ao objetivo fora do apetite sem tratamento ou com tratamento vencido. Só aparece para quem lê riscos.
- O planejado soma o custo previsto das ações 5W2H e o planejado das ações estratégicas (linha de base vigente ou, sem ela, o plano atual); o realizado soma o realizado das ações 5W2H e as execuções das entregas.
- A escolha de sinalizadores vale só para você e só no navegador em uso.

## 2.13 Mapa estratégico: detalhamento e visão consolidada

ID BSC-EST-13

### Para que serve

A partir de um objetivo do mapa você desce aos indicadores e às ações que o sustentam, até a série histórica de cada indicador. A aba **Visão consolidada** reúne, numa só tela, a lista completa de indicadores e de ações do plano, com os totais planejado e realizado.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia); Leitor/Auditor.

### Passo a passo

1. No **Mapa estratégico**, clique num objetivo para abrir o painel lateral.
2. Consulte **Indicadores do objetivo** (farol, meta, realizado do último período e **Atualização vencida**).
3. Consulte **Ações estratégicas do objetivo**, com **Execução física**, **Realizado / planejado**, **Término previsto**, situação e atraso. O código e o título levam à ficha da ação.
4. Clique num indicador para ver a série **Meta × realizado no tempo** e as **Ações vinculadas**.
5. Use **Abrir a ficha do indicador** para ir à ficha completa.
6. Abra a aba **Visão consolidada** para ver a lista completa de indicadores (com eixo, objetivo, meta, realizado, atingimento e situação) e de ações (primeiro as estratégicas, depois as dos planos 5W2H), com os totais planejado e realizado no topo.

### Observações

- Uma ação estratégica alinhada a dois objetivos conta nos dois cartões, mas na Visão consolidada é somada uma vez só.
- Objetivo sigiloso aparece como **Objetivo reservado** para quem não é da Diretoria de Estratégia; indicador sigiloso aparece como **Indicador reservado** para quem não gerencia a estratégia nem os indicadores. Farol, valores e sinais continuam à vista.
- Ação ou plano ligado a item reservado aparece como **Ação reservada**, **Plano de ação reservado** ou **Ação estratégica reservada**. Ação estratégica sigilosa fica fora do mapa para quem não pode abrir a ficha dela.
- Quem só lê o painel vê no mapa apenas indicadores aprovados; por isso o número de indicadores de um objetivo pode diferir entre o gestor e o leitor.

[title]  4. Planos de ação 5W2H
[path] Aplicações/BSC/

Quando um indicador desvia da meta, a resposta é um **plano de ação**. O plano é aberto a partir da própria ficha do indicador e organiza as ações corretivas no formato **5W2H** (o quê, por quê, onde, quem, quando, como e quanto), cada uma com situação e fase do ciclo **PDCA**, além de uma **análise de causa-raiz**.

O plano de ação 5W2H não se confunde com a **ação estratégica**: o plano responde a um indicador fora da meta; a ação estratégica é um projeto planejado da carteira. Este capítulo mostra como abrir o plano, detalhar as ações, analisar a causa-raiz, registrar a execução, aprovar o plano e acompanhar as ações pela Mesa de trabalho e pelo Mapa estratégico.

No exemplo, o indicador **Prazo médio de emissão de licenças ambientais** fechou o trimestre acima da meta, e a GEPRO — Gerência de Projetos Estratégicos abre um plano de ação para corrigir o desvio.

## 4.1 Abrir um plano de ação a partir do indicador

ID BSC-PAC-01

### Para que serve

O plano de ação nasce na ficha do indicador que desviou. Ele pode apontar para uma meta específica do próprio indicador ou ficar sem meta específica.

**Quem usa:** Gestor de Desempenho (escritório de estratégia).

### Passo a passo

1. Abra **Gestão por indicadores › Indicadores** e clique no indicador (por exemplo, **Prazo médio de emissão de licenças ambientais**).
2. Na seção **Planos de ação**, clique em **Novo plano**.
3. Informe o título e a descrição do plano.
4. Escolha a meta do próprio indicador a que o plano responde, ou **Sem meta específica**.
5. Marque o plano como sigiloso, se necessário.
6. Salve. O plano nasce em **Rascunho**.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/GPQiOBSDretJNLUwlvqKe_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 21 — Plano de ação 5W2H aberto, com ações, fase PDCA e análise de causa-raiz.

### Observações

- O plano só aponta para metas do próprio indicador (“Esta meta pertence a outro indicador…”).
- Meta aposentada não pode passar a ser apontada por nenhum plano; o plano que já a apontava continua com ela enquanto a meta não for trocada.
- O aviso de desvio (**Indicador fora da meta**) é o gatilho típico para abrir um plano.

## 4.2 Detalhar as ações no formato 5W2H

ID BSC-PAC-02

### Para que serve

Cada ação do plano responde às sete perguntas do 5W2H: **o quê** (título), **por quê** (motivo), **onde** (área), **quem** (responsável), **quando** (prazo), **como** (método) e **quanto** (custo previsto).

**Quem usa:** Gestor de Desempenho (escritório de estratégia).

### Passo a passo

1. No plano de ação, adicione uma nova ação.
2. Preencha **o quê** (por exemplo, “Revisar o fluxo de protocolo dos estudos ambientais da Ponte do Vale”) e **por quê**.
3. Em **onde**, informe a área (por exemplo, GEPVA — Gerência da Ponte do Vale).
4. Em **Quem (pessoa)**, escolha o empregado responsável; o nome é preenchido automaticamente.
5. Use o texto **Quem** apenas quando o responsável não é uma pessoa do cadastro (uma unidade ou uma contratada).
6. Informe **quando** (prazo), **como** (método) e **quanto** (custo previsto).
7. Salve a ação.

### Observações

- Só o empregado escolhido em **Quem (pessoa)** recebe a ação na **Mesa de trabalho**. Um responsável escrito à mão não aparece na mesa de ninguém.
- O **quando** da ação é o prazo usado pela Mesa de trabalho e pelos sinais de atraso do mapa.

## 4.3 Situação da ação e fase do PDCA

ID BSC-PAC-03

### Para que serve

Cada ação tem uma **situação** — A fazer, Fazendo, Feito, Bloqueado ou Cancelado — e uma **fase do PDCA** — Planejar, Executar, Checar ou Agir —, que mostra em que ponto do ciclo de melhoria contínua ela está.

**Quem usa:** Gestor de Desempenho (escritório de estratégia); Responsável por ação/área.

### Passo a passo

1. Abra o plano de ação e localize a ação na tabela.
2. Atualize a **situação** conforme o andamento.
3. Atualize a **fase do PDCA**.
4. Salve a ação.

### Observações

- Cancelar uma ação é decisão de quem gerencia o plano; o responsável pela ação não cancela pela Mesa de trabalho.
- Ação cujo início já passou, ainda **A fazer** e com 0%, conta como atrasada no Mapa estratégico, mesmo antes do prazo final.

## 4.4 Análise de causa-raiz

ID BSC-PAC-04

### Para que serve

A seção **Análise de causa-raiz** desdobra o desvio em causas encadeadas, na linha das técnicas de Ishikawa e dos 5 Porquês. É a causa raiz que orienta as ações que resolvem o problema, não só o sintoma.

**Quem usa:** Gestor de Desempenho (escritório de estratégia).

### Passo a passo

1. No plano de ação, abra a seção **Análise de causa-raiz**.
2. Registre a primeira causa do desvio (por exemplo, “Estudos entregues incompletos ao órgão licenciador”).
3. Para cada causa, acrescente as causas-filhas que a explicam.
4. Marque como **raiz** as causas do fundo da cadeia.
5. Defina as ações 5W2H para atacar as causas raiz identificadas.

### Observações

- Uma causa pode ter várias causas-filhas; a análise forma uma árvore.
- Ações que atacam só o sintoma tendem a fazer o desvio voltar no período seguinte.

## 4.5 Registrar a execução, as evidências e o histórico da ação

ID BSC-PAC-05

### Para que serve

A coluna **Execução** de cada ação mostra o percentual executado e o valor realizado ao lado do custo previsto. Esses números alimentam o planejado × realizado do objetivo no Mapa estratégico. Cada ação guarda também as **Evidências** da execução e o **Histórico da ação**.

**Quem usa:** Gestor de Desempenho (escritório de estratégia); Responsável por ação/área; Leitor/Auditor.

### Passo a passo

1. No plano de ação, clique na barra de execução da ação.
2. Informe **Executado (%)** (de 0 a 100) e o valor **Realizado**, e salve.
3. Em **Evidências**, abaixo da barra, anexe os arquivos que comprovam a execução.
4. Clique em **Histórico da ação** para ver cada alteração, com antes, depois e autor.

### Observações

- Evidências podem ser anexadas e removidas enquanto o plano não está concluído nem cancelado.
- Em plano sigiloso, os arquivos de evidência só abrem para quem gerencia a estratégia.
- O histórico da ação abre para quem lê o plano (quem gerencia a estratégia, os indicadores ou os planos de ação).
- O que o responsável registra pela Mesa de trabalho aparece aqui com ele como autor.

## 4.6 Aprovação e ciclo de vida do plano

ID BSC-PAC-06

### Para que serve

O plano de ação passa por aprovação antes de entrar em execução. As situações são **Rascunho**, **Aguardando aprovação**, **Em andamento** e **Concluído** (ou cancelado). Toda a trilha fica registrada.

**Quem usa:** Gestor de Desempenho (escritório de estratégia); Diretoria de Estratégia (patrocinador/aprovador).

### Passo a passo

1. Com o plano montado, clique em **Enviar para aprovação**. A situação passa a **Aguardando aprovação**.
2. O aprovador abre **Início › Solicitações de aprovação** e aprova ou recusa o pedido.
3. Depois da aprovação, volte ao plano e clique em **Ativar**. A situação passa a **Em andamento**.
4. Acompanhe a execução das ações até o fim.
5. Ao concluir todas as ações, encerre o plano como **Concluído**.

### Observações

- Ativar sem aprovação é recusado.
- Quem enviou não aprova o próprio pedido.
- Plano concluído ou cancelado não aceita mais anexar nem remover evidências.

## 4.7 Atualizar a ação pela Mesa de trabalho

ID BSC-PAC-07

### Para que serve

O responsável por uma ação 5W2H a encontra na **Mesa de trabalho**, junto com as demais pendências, agrupada pelo prazo. Pela mesa ele atualiza a situação, o percentual e as evidências da própria ação, mesmo sem permissão para gerenciar planos.

**Quem usa:** Responsável por ação/área.

### Passo a passo

1. Abra **Gestão por indicadores › Mesa de trabalho**.
2. Localize a ação nos grupos **Atrasadas**, **Hoje**, **Próximos 7 dias**, **Depois** ou **Sem prazo**; use **Tipo de pendência** para filtrar.
3. Clique em **Atualizar** na linha da ação.
4. Informe a **Situação** (A fazer, Fazendo, Feito, Bloqueado) e o **Percentual concluído**.
5. Anexe os arquivos em **Evidências**.
6. Salve. A ação muda de grupo ou sai da lista, e a alteração aparece no plano com você como autor.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/5mlHqSAkU9zgfk2dfzZgr_image.png" size="62" isUploading="false" width="620" height="387" showCaption="false"}

Figura 22 — Mesa de trabalho com as pendências agrupadas por prazo.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/1qMmPR7FeMR1kJ4NhNqTh_image.png" size="21" isUploading="false" width="208" height="451" darkWidth="208" darkHeight="451" showCaption="false"}

Figura 23 — Mesa de trabalho no celular.

### Observações

- Aparecem na mesa as ações A fazer, Fazendo ou Bloqueadas, de planos não concluídos nem cancelados, cujo responsável foi escolhido como empregado.
- O prazo usado é o **quando** da ação; os grupos são calculados no horário de Brasília.
- Se outra pessoa alterou a ação depois que a mesa foi carregada, o painel informa o motivo e recarrega a situação atual.

## 4.8 Planos de ação no Mapa estratégico

ID BSC-PAC-08

### Para que serve

As ações 5W2H aparecem no Mapa estratégico junto com as ações estratégicas: entram no planejado × realizado do objetivo, acendem os sinais de atraso e são listadas nas ações vinculadas a cada indicador.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia); Leitor/Auditor.

### Passo a passo

1. Abra **Gestão por indicadores › Mapa estratégico** e escolha o plano estratégico.
2. Verifique no cartão do objetivo os sinais **Ações** e **Planos de ação**.
3. Passe o mouse no cartão para ver o **Planejado** e o **Realizado**, que somam o custo previsto e o realizado das ações 5W2H.
4. Clique no objetivo e depois num indicador para ver as **Ações vinculadas**, com situação, prazo, execução, realizado / planejado e atraso.
5. Na aba **Visão consolidada**, consulte **Ações dos planos de ação (5W2H)** com os totais.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/F8NvQRvRDT798jb98s0Fz_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 24 — Mapa estratégico com os sinais de ações e de planos de ação.

### Observações

- Sinal de **Planos de ação**: período encerrado, ação atrasada ou nenhum andamento depois do início.
- Ação de plano sigiloso, ou de indicador reservado, aparece como **Ação reservada** e **Plano de ação reservado**, com situação, prazo, execução e valores à vista.
- Para quem só lê o painel, as ações de planos de indicadores ainda não aprovados ficam fora do mapa.

## 4.9 Discussão, sigilo e acesso ao plano

ID BSC-PAC-09

### Para que serve

O plano de ação tem o painel de colaboração com **Discussão** e **Compartilhado com**, para registrar a análise junto do plano e chamar outras áreas. O acesso ao plano segue o perfil de quem gerencia planos de ação e as regras de sigilo do indicador.

**Quem usa:** Gestor de Desempenho (escritório de estratégia); Diretoria de Estratégia (patrocinador/aprovador); Leitor/Auditor.

### Passo a passo

1. Abra o plano de ação e role até o fim da tela.
2. Na caixa **Discussão**, registre comentários e respostas.
3. Na caixa **Compartilhado com**, escolha a área que deve agir (por exemplo, SUOBR — Superintendência de Obras), escreva a **Observação** e clique em **Compartilhar**.
4. Clique em **Seguir** no topo do plano para receber avisos de mudanças e comentários.

### Observações

- Plano sigiloso, ou de indicador sigiloso por si ou pelo objetivo, mostra o selo **Sigiloso** ou **Indicador sigiloso**, e só quem gerencia a estratégia vê a discussão dele.
- Gerenciar planos de ação é atribuição do Gestor de Desempenho; a Diretoria de Estratégia lê os planos e decide as aprovações.
- O responsável por uma ação registra a execução pela Mesa de trabalho, sem precisar da permissão de gerenciar planos.

[title]  6. Mesa de trabalho
[path] Aplicações/BSC/

A mesa de trabalho é a tela de cada servidor: tudo o que está com ele na estratégia — indicador a apurar, atividade e entrega de ação estratégica, ação de plano 5W2H, encaminhamento de reunião, reunião e tratamento de risco — agrupado pelo que já atrasou, vence hoje, vence nos próximos dias, vence depois ou não tem prazo.

Cada item pode ser atualizado ali mesmo. A alteração vai para a tela dona do item (a ficha da ação, o plano 5W2H, a ficha do indicador, o evento da agenda, a ficha do risco) e fica no histórico dela, com o servidor como autor. A tela fica em Gestão por indicadores › Mesa de trabalho.

## 6.1 O que aparece na mesa de trabalho

ID BSC-MES-01

### Para que serve

A **Mesa de trabalho** é a caixa de entrada de cada servidor na estratégia: num lugar só, tudo o que tem o seu nome como responsável, sem precisar lembrar em qual tela mora cada pendência. Ela não guarda nada próprio: olha para cada lugar onde a pendência já existe.

**Quem usa:** Responsável por ação/área; Gestor de Desempenho (escritório de estratégia); Diretoria de Estratégia (patrocinador/aprovador).

### Passo a passo

1. Abra Gestão por indicadores › Mesa de trabalho.
2. Confira os tipos de item da lista: indicador, atividade, entrega, ação 5W2H, encaminhamento, reunião e tratamento de risco.
3. Em cada item, leia o tipo, o título, **de onde vem** (a ação estratégica, o objetivo, o plano ou a reunião) e o prazo.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/5mlHqSAkU9zgfk2dfzZgr_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 43 — Mesa de trabalho com as pendências agrupadas por prazo

### Observações

- **Indicador**: você é o responsável direto (ou, sem responsável, o dono do objetivo) e há período fechado sem valor. Aparece uma linha por indicador, com o período mais antigo sem valor, o prazo de apuração e quantos períodos faltam. Indicador alimentado por integração não aparece.
- **Atividade**: de ação estratégica em andamento, não concluída nem cancelada; o prazo é o término planejado. A atividade-mãe não aparece.
- **Entrega**: de ação estratégica em andamento, abaixo de 100%; o prazo é o fim do período.
- **Ação 5W2H**: A fazer, Fazendo ou Bloqueada, num plano ativo, com você escolhido como empregado responsável. Responsável escrito à mão não leva a ação à mesa.
- **Encaminhamento** de reunião pendente, com o prazo do encaminhamento.
- **Reunião**: convite dos próximos 30 dias que você não recusou, e reunião que você organizou, já começou nos últimos 60 dias e continua Agendada.
- **Tratamento de risco** aberto, de risco que saiu do rascunho; a linha mostra o risco, se é preventivo ou de contingência, o percentual executado e o último lançamento. De risco sigiloso, só o código para quem não pode vê-lo.

## 6.2 Janelas de prazo e filtro por tipo

ID BSC-MES-02

### Para que serve

A mesa organiza as pendências pela urgência, para que o servidor comece pelo que já atrasou.

**Quem usa:** Responsável por ação/área.

### Passo a passo

1. Abra Gestão por indicadores › Mesa de trabalho.
2. Leia os contadores do topo: **Atrasadas** (em vermelho), **Hoje**, **Próximos 7 dias**, **Depois** e **Sem prazo**.
3. Percorra a lista, agrupada do mesmo jeito.
4. Use o campo **Tipo de pendência** para ver só um tipo (por exemplo, só indicadores); os contadores acompanham o filtro.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/5mlHqSAkU9zgfk2dfzZgr_image.png" size="62" isUploading="false" width="620" height="387" showCaption="false"}

Figura 44 — Grupos Atrasadas, Hoje, Próximos 7 dias, Depois e Sem prazo

### Observações

- Os grupos seguem o horário de Brasília, qualquer que seja o fuso do computador: o item que vence hoje continua em **Hoje** às 22h.
- **Próximos 7 dias** são os sete dias seguintes a hoje, não a semana do calendário.
- Atividade sem término planejado vai para **Sem prazo**.

## 6.3 Atualizar indicadores, atividades e entregas pela mesa

ID BSC-MES-03

### Para que serve

O botão **Atualizar** abre o painel do item com só o que cabe a ele. A atualização feita na mesa é a mesma da tela dona do item e fica no histórico dela, com você como autor.

**Quem usa:** Responsável por ação/área.

### Passo a passo

1. Na mesa, clique em **Atualizar** no item.
2. **Indicador**: informe o **Valor** do período mostrado e clique em **Registrar prévia**.
3. **Atividade**: informe **Situação**, **Percentual concluído**, **Início real** e **Término real** e salve.
4. **Entrega**: registre uma execução com **Data da execução** (até hoje), **Percentual físico atingido (acumulado)**, **Valor executado** e **Observação** e salve.
5. Confira para qual grupo o item foi (ou se saiu da lista).

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/5mlHqSAkU9zgfk2dfzZgr_image.png" size="62" isUploading="false" width="620" height="387" showCaption="false"}

Figura 45 — Painel de atualização aberto a partir da mesa

### Observações

- Período congelado de indicador não recebe prévia. **Congelar valor oficial** só aparece para quem tem a permissão de registrar medições; para os demais, a prévia fica registrada para a controladoria congelar.
- Atividade concluída é 100% e não iniciada é 0%.
- Evidências e correções de linha integrada da entrega continuam na aba Entregas da ação, com a permissão do cargo.
- Depois de salvar, o item muda de grupo ou sai da lista na hora, sem recarregar a página.

## 6.4 Atualizar ações 5W2H, encaminhamentos, reuniões e tratamentos de risco

ID BSC-MES-04

### Para que serve

Além de indicadores e ações estratégicas, a mesa atualiza as pendências dos planos de ação, das reuniões e do registro de riscos, sem que o servidor precise abrir cada módulo.

**Quem usa:** Responsável por ação/área.

### Passo a passo

1. Na mesa, clique em **Atualizar** no item.
2. **Ação 5W2H**: informe **Situação** (A fazer, Fazendo, Feito, Bloqueado) e **Percentual concluído** e anexe os arquivos de **Evidências**.
3. **Encaminhamento**: use **Marcar como concluído**, com uma observação, ou **Repassar** para outro servidor.
4. **Reunião**: use **Confirmar presença** ou **Recusar**; se você organizou, use **Marcar como realizada**.
5. **Tratamento de risco**: informe **Data da execução** (até hoje), **O que foi feito** e **Percentual executado acumulado** e salve.
6. Para anexar a prova do tratamento, abra o item de novo e use **Evidências do último lançamento**.

### Observações

- Cancelar uma ação 5W2H é decisão de quem gerencia o plano.
- O encaminhamento repassado sai da sua mesa e entra na do novo responsável, que é avisado.
- No tratamento de risco, o percentual não pode ficar abaixo do último lançamento; a correção de um lançamento errado é feita na ficha do risco.
- Lançar 100% conclui o tratamento, que sai da mesa; a evidência desse lançamento é anexada na ficha do risco, por quem tem a permissão de lançar execução de tratamento.

## 6.5 Quem pode usar a mesa e quando ela recusa

ID BSC-MES-05

### Para que serve

A mesa não depende de cargo: qualquer servidor com login ligado ao cadastro de servidor a abre e vê o que é dele. Ser o responsável pelo item é o que autoriza registrar a execução daquele item, mesmo sem permissão do módulo.

**Quem usa:** Responsável por ação/área; Administrador do sistema.

### Passo a passo

1. Abra Gestão por indicadores › Mesa de trabalho.
2. Se aparecer um aviso amarelo, leia qual tipo de pendência não pôde ser carregado e tente de novo em instantes.
3. Se o painel recusar a atualização, leia o motivo e refaça a partir da mesa recarregada.

### Observações

- Só os campos de execução passam pela mesa; o plano (datas planejadas, peso, responsável, escopo) continua com quem o gerencia.
- Item de ação estratégica sigilosa aparece com o nome da ação, mas o link para a ficha só aparece para quem pode abri-la. O mesmo vale para a ficha do risco.
- Se outra pessoa alterou o item depois que a mesa foi carregada, ou a ação foi suspensa, o painel diz o motivo e a mesa se recarrega.
- "Este item não está na sua mesa de trabalho": o item foi repassado ou o plano trocou o responsável.
- Login sem cadastro de servidor lê **Seu login não está ligado a um servidor**, não uma lista vazia.
- Indicador que não aparece precisa estar aprovado, com linha do tempo configurada e período fechado sem valor.

## 6.6 Mesa de trabalho no celular

ID BSC-MES-06

### Para que serve

A mesa foi pensada para o servidor de campo, que atualiza a atividade ou a entrega no próprio local da obra.

**Quem usa:** Responsável por ação/área.

### Passo a passo

1. No navegador do celular, abra Gestão por indicadores › Mesa de trabalho.
2. Toque no grupo (por exemplo, **Atrasadas**) para abrir ou fechar a seção.
3. Toque em **Atualizar** no item e preencha o painel.
4. Salve e confira o novo grupo do item.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/1qMmPR7FeMR1kJ4NhNqTh_image.png" size="21" isUploading="false" width="208" height="451" darkWidth="208" darkHeight="451" showCaption="false"}

Figura 46 — Mesa de trabalho no celular, com os grupos em seções

### Observações

- No celular, os grupos viram seções que abrem e fecham.
- As regras de prazo, permissão e recusa são as mesmas da tela grande.

[title]  3. Indicadores e desempenho
[path] Aplicações/BSC/

Os indicadores medem os objetivos do plano. Cada indicador tem uma ficha (o que mede, como se calcula, sentido, unidade, responsável), uma **linha do tempo** de medições, **metas** aprovadas por período e **apurações** (o valor realizado), com evidências e trilha de alterações. Indicadores podem ser alimentados à mão, calculados pelo sistema ou importados de outro sistema por integração.

Este capítulo cobre a ficha do indicador, metas e aprovação, apuração e retificação, evidências, indicadores importados, avisos de desvio e de prazo, o **Painel de desempenho**, o **Painel gerencial** e o **Meu painel**.

Os exemplos usam indicadores da Empresa Exemplo S.A., como **Avanço físico da Rodovia Norte — trecho 3**, **Execução do orçamento de investimentos** e **Prazo médio de emissão de licenças ambientais** (dias, menor é melhor).

## 3.1 Lista de indicadores

ID BSC-IND-01

### Para que serve

A tela **Indicadores** mostra toda a carteira de indicadores da empresa. Cada linha traz a unidade, a polaridade, a periodicidade e se o indicador está vinculado a um objetivo.

**Quem usa:** Gestor de Desempenho (escritório de estratégia); Diretoria de Estratégia (patrocinador/aprovador); Leitor/Auditor.

### Passo a passo

1. Abra **Gestão por indicadores › Indicadores**.
2. Localize o indicador desejado (por exemplo, **Taxa de frequência de acidentes nas obras**).
3. Clique na linha para abrir a ficha completa.
4. Na ficha, confira o selo de situação no topo (**Rascunho**, **Aguardando aprovação** ou **Aprovado**).

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/rEJ6ut4rthmwwlnEvpfrd_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 12 — Lista de indicadores com unidade, polaridade, periodicidade e vínculo.

### Observações

- A lista não exibe o selo de aprovação; para saber a situação, abra a ficha.
- Quem só lê o painel vê na lista apenas indicadores **aprovados** e **não sigilosos**.

## 3.2 Criar a ficha do indicador

ID BSC-IND-02

### Para que serve

A ficha do indicador descreve o que é medido, como, por quem e com que frequência. O formulário é dividido em **Identificação**, **Ficha do indicador**, **Responsabilidade**, **Linha do tempo** e **Apuração e sigilo**.

**Quem usa:** Gestor de Desempenho (escritório de estratégia).

### Passo a passo

1. Abra o objetivo no ciclo ativo e, na seção **Indicadores**, clique em **Novo indicador**.
2. Em **Identificação**, informe o nome (por exemplo, **Execução do orçamento de investimentos**) e a **Descrição** do que o indicador mede.
3. Em **Ficha do indicador**, informe a **Fórmula de cálculo** (texto explicativo), a **unidade** (%, dias, km…), o **sentido (polaridade)** — Maior é melhor, Menor é melhor, No alvo é melhor ou Estabilizar —, o **tipo de medida** (Instantâneo, Acumulado, Média) e a **linha de base** com a sua data.
4. Em **Responsabilidade**, informe a **Unidade responsável** (por exemplo, SUAFI) e o **Responsável direto**.
5. Em **Linha do tempo**, informe periodicidade, data de início e número de medições (veja a seção seguinte) e o **prazo máximo de apuração (dias)**.
6. Em **Apuração e sigilo**, escolha **Como é alimentado** (Manual, Calculado ou Por integração) e marque **Sigiloso** se o número não puder circular.
7. Salve. A ficha nasce com o selo **Rascunho**.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/2-8CPcQEZJAX2yX7Bi_Lv_image.png" size="62" isUploading="false" width="620" height="387" showCaption="false"}

Figura 13 — Ficha do indicador: identificação, ficha técnica e responsabilidade.

### Observações

- A **Descrição** é opcional para salvar, mas obrigatória para enviar a ficha para aprovação.
- A **Fórmula de cálculo** é só explicação para o leitor; o sistema não a calcula.
- A unidade responsável e o responsável direto respondem pela apuração e podem ser diferentes da área e do responsável do objetivo.
- Sem linha de base, o indicador mostra se chegou à meta, mas não quanto andou desde o início do plano.
- Indicador em Rascunho não entra no Painel de desempenho, não é apurado automaticamente e não dispara aviso de desvio.

## 3.3 Configurar a linha do tempo do indicador

ID BSC-IND-03

### Para que serve

A linha do tempo define as janelas de medição do indicador a partir de três dados: **Periodicidade de apuração**, **Data de início** e **Número de medições**. Metas e apurações são lançadas sempre numa dessas janelas.

**Quem usa:** Gestor de Desempenho (escritório de estratégia).

### Passo a passo

1. No formulário do indicador, abra a seção **Linha do tempo**.
2. Escolha a **Periodicidade de apuração** (Mensal, Trimestral, Anual…).
3. Informe a **Data de início** (qualquer dia do primeiro período).
4. Informe o **Número de medições** (de 1 a 300).
5. Confira o resumo exibido logo abaixo (por exemplo, “12 medições (Mensal), de 01/01/2026 a 31/12/2026”) e salve.

### Observações

- Data de início e número de medições são obrigatórios em todo indicador novo.
- Se a data de início cair no meio de um período, a primeira medição cobre o período inteiro, e o formulário avisa.
- Indicador criado dentro de um objetivo já vem com o período do plano; indicadores de longo prazo podem ir além do fim do plano (a ficha avisa).

## 3.4 Indicador calculado: métrica do catálogo ou fórmula

ID BSC-IND-04

### Para que serve

Um indicador **Calculado** é apurado pelo sistema a partir do próprio dado registrado. A origem pode ser **Uma métrica do catálogo** (lista fechada de métricas já rastreáveis, agrupadas por módulo) ou **Fórmula sobre métricas**, que combina métricas do catálogo numa conta.

**Quem usa:** Gestor de Desempenho (escritório de estratégia).

### Passo a passo

1. No formulário do indicador, em **Como é alimentado**, escolha **Calculado**.
2. Em **Origem do cálculo**, deixe **Uma métrica do catálogo** e escolha a métrica em **Métrica do catálogo**.
3. Ou troque para **Fórmula sobre métricas** e monte a conta no campo **Fórmula**, inserindo cada métrica pelo combo **Inserir uma métrica**.
4. Clique em **Testar fórmula** para ver o **Resultado:** e a **Memória de cálculo** do mês corrente.
5. Salve quando o teste devolver o valor esperado.

### Observações

- O combo **Inserir uma métrica** acrescenta a referência no fim do texto: monte a conta na ordem ou ajuste depois.
- Nome fora do catálogo é recusado ao testar e ao salvar. Fórmula sem nenhuma métrica também é recusada.
- Não preencha métrica única e fórmula ao mesmo tempo.
- Métricas de **saldo** respondem “quanto há hoje” e não são recortadas pelo período; as demais medem o movimento do período. Escolha conforme a pergunta do indicador.
- A apuração por consulta SQL é outra origem possível; ela é descrita no capítulo de Dados do Bússola/BSC.

## 3.5 Apuração automática do indicador calculado

ID BSC-IND-05

### Para que serve

Com a apuração automática ligada, o sistema atualiza toda madrugada o valor do período em aberto e, quando o período vira, congela o último valor do período que fechou, na periodicidade da ficha.

**Quem usa:** Gestor de Desempenho (escritório de estratégia).

### Passo a passo

1. Na ficha de um indicador **Calculado**, clique em **Editar**.
2. Marque **Apurar automaticamente na periodicidade**.
3. Salve e envie o indicador para aprovação.
4. Depois de aprovado, acompanhe os valores na seção **Apurações** e na **Linha do tempo das medições**.

### Observações

- A caixa só existe no indicador calculado.
- A varredura noturna só apura indicador **Aprovado**. Em Rascunho ou Aguardando aprovação, o indicador é pulado.
- Se a apuração automática falhar ou não gerar valor, o responsável recebe o aviso **Indicador automatizado sem atualizar**.

## 3.6 Lançar metas e faixa de tolerância

ID BSC-IND-06

### Para que serve

Cada janela da linha do tempo recebe uma meta, com uma **faixa de tolerância** que forma a zona amarela do farol. A meta é o compromisso pelo qual a área será cobrada.

**Quem usa:** Gestor de Desempenho (escritório de estratégia).

### Passo a passo

1. Na ficha do indicador, no cartão **Linha do tempo das medições**, clique em **Lançar meta** na janela desejada (ou **Editar meta**, se já houver uma).
2. Confira a janela em **Janela da linha do tempo**. Outra opção é usar **Nova meta** na seção **Metas** e escolher a janela.
3. Informe o **valor da meta** (por exemplo, 85).
4. Informe a **faixa de tolerância** do lado certo da meta: abaixo para Maior é melhor, acima para Menor é melhor, cercando a meta para No alvo é melhor.
5. Opcionalmente, informe **peso**, **tipo de compromisso** (Comprometida, Esticada, Aspiracional) e **critério de aceitação**.
6. Salve. A meta nasce em **Rascunho**.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/dv1N67GJ0EC8v2GwI0U-n_image.png" size="62" isUploading="false" width="620" height="387" showCaption="false"}

Figura 14 — Metas do indicador, com tolerância e situação de aprovação.

### Observações

- Cada janela tem uma meta só (“Esta janela da linha do tempo já tem uma meta.”). Para trocar o número, edite a meta.
- Data base que não seja uma janela é recusada (“A meta deve ser lançada numa janela da linha do tempo do indicador.”).
- Faixa de tolerância do lado errado é recusada, pois pintaria de verde um resultado ruim.

## 3.7 Aprovação do indicador e da meta

ID BSC-IND-07

### Para que serve

Indicador e meta nascem em **Rascunho** e só contam depois de aprovados por outra pessoa. A aprovação passa pela bandeja **Solicitações de aprovação** e termina com a efetivação na ficha.

**Quem usa:** Gestor de Desempenho (escritório de estratégia); Diretoria de Estratégia (patrocinador/aprovador).

### Passo a passo

1. Na ficha do indicador, clique em **Enviar para aprovação** (ao lado do selo no topo). Para a meta, use o botão na linha da meta.
2. Os selos passam a **Aguardando aprovação**.
3. O aprovador abre **Início › Solicitações de aprovação**, localiza o pedido (módulo **Indicadores**, operação **Aprovação de indicador** ou **Aprovação de meta**) e clica em **Aprovar** ou **Recusar**, com uma **Observação**.
4. Depois da aprovação, volte à ficha e clique em **Efetivar aprovação**. O selo passa a **Aprovado** e a linha entra no painel.
5. Em caso de recusa, clique em **Voltar para rascunho**, corrija e envie de novo.

### Observações

- Quem enviou não pode aprovar o próprio pedido.
- Aprovar não efetiva sozinho: sem o clique em **Efetivar aprovação**, o selo continua Aguardando aprovação.
- A ficha não mostra a observação da recusa; ela fica na solicitação, com o aprovador.
- Editar a ficha ou a meta aprovada devolve o selo a **Rascunho** e tira a linha do painel até nova aprovação.
- Enquanto aguardam aprovação, indicador e meta não aparecem no Painel de desempenho nem disparam avisos.

## 3.8 Registrar, congelar e retificar a apuração

ID BSC-IND-08

### Para que serve

A apuração é o valor realizado de um período. Você pode salvar um valor **em andamento** (estimativa parcial) e depois **congelar** o valor oficial. Uma correção posterior é feita por **retificação**, que preserva o valor anterior.

**Quem usa:** Gestor de Desempenho (escritório de estratégia); Responsável por ação/área.

### Passo a passo

1. Na ficha do indicador, abra a seção **Apurações** e clique em **Nova apuração**.
2. Escolha a janela, informe o valor e salve como **Em andamento** (estimativa) ou **Congelar (oficial)**.
3. Para corrigir um valor congelado, clique em **Retificar** na linha do período.
4. Escreva a **justificativa** e o novo valor e salve. A linha passa a mostrar **Retificado v2**.
5. Para ver todas as versões, clique no ícone **Histórico de retificação** da linha.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/wbTCJV1Ja9Ql2PRbMUHSA_image.png" size="62" isUploading="false" width="620" height="387" showCaption="false"}

Figura 15 — Linha do tempo e medições do indicador, com apuração congelada e retificada.

### Observações

- Período congelado não é sobrescrito: a mudança é sempre uma nova versão.
- A justificativa da retificação é obrigatória.
- Valor em andamento não dispara aviso de desvio; o aviso só ocorre ao congelar.
- O responsável pode registrar uma prévia pela **Mesa de trabalho**; congelar o valor oficial exige a permissão de registrar medições.
- Indicador importado não aceita lançamento nem retificação manual.

## 3.9 Apurar o indicador calculado e ler a memória de cálculo

ID BSC-IND-09

### Para que serve

No indicador calculado, o valor não é digitado: a seção **Apurações** oferece **Recalcular agora** e **Apurar agora**. Cada valor calculado guarda uma **memória de cálculo** com a fórmula, a janela e as parcelas, para que o auditor possa refazer a conta.

**Quem usa:** Gestor de Desempenho (escritório de estratégia); Leitor/Auditor.

### Passo a passo

1. Na ficha de um indicador calculado e aprovado, abra a seção **Apurações**.
2. Clique em **Recalcular agora** para atualizar só o valor do período em aberto.
3. Ou clique em **Apurar agora**, informe **Início do período** e **Fim do período** em **Apurar a partir da métrica** e confirme: o valor do período é calculado e congelado.
4. Clique no ícone **Histórico de retificação** da linha para ler a memória de cálculo de cada versão.

### Observações

- Recalcular não fecha o período anterior nem toca em período congelado.
- Uma métrica sem movimento devolve **zero**, que congela e pode pintar vermelho. Leia a memória de cálculo antes de congelar: ela diz se o zero veio da falta de movimento ou da indisponibilidade do módulo de origem.
- Se **Apurar agora** ou **Recalcular agora** não funciona, confira se o indicador está **Aprovado**.

## 3.10 Linha do tempo das medições

ID BSC-IND-10

### Para que serve

O cartão **Linha do tempo das medições** mostra uma janela por medição prevista, com a meta (e o selo de aprovação), o resultado e a situação de cada janela. No topo ficam o resumo e as contagens de **Medidas**, **Em atraso**, **Aguardando apuração** e **Futuras**.

**Quem usa:** Gestor de Desempenho (escritório de estratégia); Responsável por ação/área; Leitor/Auditor.

### Passo a passo

1. Abra a ficha do indicador e localize o cartão **Linha do tempo das medições**.
2. Leia a situação de cada janela: **Futura**, **Aberta**, **Aguardando apuração**, **Atrasada**, **Parcial, não congelada** ou **Medida**.
3. Clique em **Mostrar as N janelas** para ver todas as janelas de um plano longo.
4. Abra a seção recolhida **Fora da linha do tempo (N)** para ver metas aposentadas e resultados fora das janelas atuais.
5. Abra **Mudanças de parâmetros (N)** para ver cada mudança da linha do tempo, com autor, data e justificativa.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/wbTCJV1Ja9Ql2PRbMUHSA_image.png" size="62" isUploading="false" width="620" height="387" showCaption="false"}

Figura 16 — Cartão Linha do tempo das medições com as situações das janelas.

### Observações

- **Aguardando apuração**: a janela fechou sem valor oficial e ainda está no prazo. **Atrasada**: o prazo passou (sem prazo informado, fica atrasada assim que fecha).
- Depois da última janela a ficha mostra **Linha do tempo encerrada**; apuração de período que não é janela é recusada.
- Mudança de fórmula, métrica, unidade, sentido ou tipo de medição é marcada como **Quebra de série**.
- Indicador sem linha do tempo configurada mostra metas e resultados em **Fora da linha do tempo** até receber data de início e número de medições.

## 3.11 Mudar a periodicidade, o início ou o número de medições

ID BSC-IND-11

### Para que serve

Mudar os parâmetros da linha do tempo redesenha as janelas. Antes de gravar, o sistema mostra o que vai sair da linha do tempo e pede justificativa.

**Quem usa:** Gestor de Desempenho (escritório de estratégia).

### Passo a passo

1. Na ficha do indicador, clique em **Editar**, altere periodicidade, data de início ou número de medições e salve.
2. Se nada sair da linha do tempo, a ficha é salva sem perguntas.
3. Se algo sair, leia o aviso (por exemplo, **Alterar a periodicidade de Mensal para Trimestral**) com as contagens de metas excluídas, metas aposentadas e resultados que saem.
4. Clique em **Ver os itens** para conferir cada item afetado.
5. Escreva a **Justificativa** (mínimo de 20 caracteres).
6. Clique em **Alterar e aposentar metas (N)** para aplicar, ou em **Manter os parâmetros atuais** para desistir.
7. Envie o indicador para aprovação de novo.

### Observações

- Meta em rascunho que sai é excluída. Meta aguardando aprovação ou aprovada que sai é **aposentada**: fica somente leitura em **Fora da linha do tempo** e não volta se a mudança for desfeita.
- Resultados medidos nunca são apagados: saem da linha do tempo e voltam sozinhos se uma configuração futura tiver o período deles.
- Se alguém mudar metas ou valores com o aviso aberto, os números são recarregados (“Os números acima foram atualizados”); confira e confirme de novo.
- Se outra pessoa salvar a ficha enquanto você edita, a sua alteração não é gravada; a ficha recarrega e você refaz a mudança sobre o que foi salvo.
- Como toda edição, a mudança devolve o indicador a **Rascunho**.

## 3.12 Evidências de apuração

ID BSC-IND-12

### Para que serve

Cada resultado precisa mostrar de onde veio: o relatório mensal da obra, a planilha de medição, o documento que trouxe o número. A evidência fica presa ao **período** (à janela), não a uma versão do valor.

**Quem usa:** Gestor de Desempenho (escritório de estratégia); Responsável por ação/área; Leitor/Auditor.

### Passo a passo

1. No cartão **Linha do tempo das medições**, clique em **Evidências (N)** na janela desejada.
2. No painel **Evidências do período**, preencha **Descrição** e **Data da evidência** em **Registrar evidência**.
3. Em **Arquivos**, escolha um ou mais arquivos (PDF, imagem, planilha, documento).
4. Clique em **Registrar evidência**.
5. Confira a evidência na lista, com **Registrada por**, data e arquivos; use o ícone de download para baixar.
6. Use **Histórico** na evidência para ver quem registrou, anexou ou removeu arquivos.

### Observações

- Descrição e data são obrigatórias; a data não pode ser futura. Arquivos são opcionais e podem ser anexados depois.
- Se um arquivo não subir, a evidência fica registrada e o painel indica o arquivo que faltou.
- Depois que o período é congelado, a evidência recebe o selo **Preservada (período congelado)** e não pode mais ser removida; só se acrescenta.
- Indicador com evidências registradas não pode ser excluído.
- Evidência de indicador sigiloso só é vista por quem gerencia a estratégia ou o indicador.

## 3.13 Indicadores importados (alimentados por integração)

ID BSC-IND-13

### Para que serve

Parte dos indicadores vem de séries publicadas por outros sistemas ou instituições, que divulgam valores (em geral anuais) e às vezes revisam números antigos. Esses indicadores ficam no mesmo cadastro, com meta, sigilo, evidências e trilha, mas os valores chegam pela integração, sem redigitação.

**Quem usa:** Gestor de Desempenho (escritório de estratégia); Analista de Integração de Dados; Leitor/Auditor.

### Passo a passo

1. Confira em **Gestão por indicadores › Cadastros estratégicos**, aba de sistemas externos, se o sistema de origem existe.
2. No formulário do indicador, em **Apuração e sigilo › Como é alimentado**, escolha **Por integração**.
3. Na seção **Código em sistema externo**, escolha o **Sistema externo** e informe o **Código no sistema externo** (por exemplo, MOV-CARGA-TOTAL para **Movimentação de carga no Terminal Sul**).
4. Preencha **Linha de base** e **Data da linha de base** (o ano dessa data é o ano base) e salve.
5. Envie o indicador para aprovação.
6. Peça ao Analista de Integração de Dados que a integração envie os valores.
7. Acompanhe em **Gestão por indicadores › Indicadores importados**: fonte, ano base, um valor por ano, **Resultado atual** e **Sinal**.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/oIrDjiqlXD7cvZAd15M29_image.png" size="62" isUploading="false" width="620" height="387" showCaption="false"}

Figura 17 — Indicadores importados, com fonte, ano base, série anual e sinal.

### Observações

- Cada valor recebido é gravado como apuração congelada, com origem **Integração**.
- Reenviar o mesmo valor não muda nada (**sem alteração**). Quando a fonte revisa um número, ele vira nova versão (**Revisto pela fonte v2**) e o ano aparece com **(rev.)**.
- São aceitos anos anteriores à linha do tempo e as janelas dela; período ainda não terminado é recusado.
- Com meta aprovada, o sinal é o farol **vs. meta**. Sem meta, compara com o ano base: **Melhorou**, **Estável**, **Piorou** ou **Mudou**. Sem valor, **Sem valor**.
- Um envio pode ter até 1000 valores, e cada um recebe a sua resposta: criado, sem alteração, retificado ou recusado com o motivo.
- Ninguém lança, congela nem retifica à mão o valor de um indicador importado: o número é da fonte.

## 3.14 Aviso automático de desvio

ID BSC-IND-14

### Para que serve

Quando um período é congelado fora da meta (farol vermelho), o sistema avisa sozinho, pelo sino do portal e por e-mail, com o assunto **Indicador fora da meta**, trazendo o indicador, o período, o realizado e a meta.

**Quem usa:** Gestor de Desempenho (escritório de estratégia); Diretoria de Estratégia (patrocinador/aprovador); Responsável por ação/área.

### Passo a passo

1. Na seção **Apurações**, congele o valor do período (ou use **Apurar agora** no indicador calculado).
2. Se o farol ficar vermelho, o aviso sai no mesmo instante.
3. Abra o aviso no sino e vá à ficha do indicador.
4. Registre a análise do desvio e, se necessário, abra um plano de ação.

### Observações

- Um período avisado não é avisado de novo; a retificação gera nova avaliação e, se continuar fora da meta, novo aviso.
- Uma varredura de madrugada avisa os períodos congelados ainda não avisados; no indicador com apuração automática, o aviso chega nessa varredura.
- Não há aviso quando: o indicador ou a meta não estão aprovados; o farol ficou amarelo; o indicador é sigiloso; ou o canal foi desligado em **Início › Preferências de notificação**.

## 3.15 Alertas de prazo de apuração

ID BSC-IND-15

### Para que serve

O sistema avisa quando a apuração manual de um indicador está para vencer ou venceu, e quando um indicador automatizado deixou de atualizar.

**Quem usa:** Responsável por ação/área; Gestor de Desempenho (escritório de estratégia).

### Passo a passo

1. Na ficha do indicador, preencha o **prazo de apuração** (dias após o fim do período) e o **Responsável direto**.
2. Faltando 3 dias para o prazo, o responsável e quem segue o indicador recebem **Prazo de apuração chegando**.
3. No dia seguinte ao prazo, recebem **Apuração vencida**, e um lembrete a cada 7 dias enquanto faltar o valor.
4. Para o indicador calculado com apuração automática, recebem **Indicador automatizado sem atualizar** quando a apuração não gera valor ou falha.
5. Em **Gestão por indicadores › Alertas e mensagens**, o coordenador escolhe canais e destinatários de cada família de aviso.
6. Use **Verificar prazos de apuração agora** para rodar a verificação na hora.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/zqgc1O-GVCdRdmkb8A13q_image.png" size="62" isUploading="false" width="620" height="387" showCaption="false"}

Figura 18 — Alertas e mensagens: famílias de aviso de apuração e resumo programado.

### Observações

- A verificação roda todo dia às 7 h (horário de Brasília). Cada aviso sai uma única vez por período.
- Indicador sem prazo de apuração não gera aviso de prazo.
- Indicador sem responsável direto avisa só quem o segue.
- O aviso de indicador automatizado se repete no máximo uma vez por semana enquanto a pendência continuar.

## 3.16 Resumo programado dos indicadores automatizados

ID BSC-IND-16

### Para que serve

Quem responde por indicadores automatizados recebe, na frequência escolhida, uma única mensagem com quantos estão no verde, amarelo, vermelho, sem avaliação e sem atualizar, e uma linha por indicador.

**Quem usa:** Responsável por ação/área; Gestor de Desempenho (escritório de estratégia).

### Passo a passo

1. Abra **Minhas notificações** e localize o cartão **Resumo dos meus indicadores automatizados**.
2. Escolha a **frequência** (diário, semanal, mensal ou desligado).
3. Escolha o **dia** e a **hora** (horário de Brasília) e salve.
4. Para voltar ao padrão da instalação, clique em **Usar o padrão da instalação**.
5. O coordenador define o **Resumo padrão da instalação** no fim da tela **Gestão por indicadores › Alertas e mensagens**.

### Observações

- O padrão da instalação é semanal, segunda-feira, 8 h.
- O resumo lista até 30 indicadores; o restante aparece como “e mais N”.
- O nome de indicador sigiloso só aparece na versão do resumo dentro do sistema; no e-mail e no WhatsApp ele entra apenas nas contagens.
- O resumo por WhatsApp usa um modelo aprovado e só sai depois que esse modelo for aprovado na conta de WhatsApp da empresa.

## 3.17 Painel de desempenho

ID BSC-IND-17

### Para que serve

O **Painel de desempenho** é a grade linha a linha: para cada indicador e período, cruza meta e realizado, calcula a variação e o desempenho (pontuado conforme a lente do ciclo) e pinta o farol.

**Quem usa:** Gestor de Desempenho (escritório de estratégia); Diretoria de Estratégia (patrocinador/aprovador); Leitor/Auditor.

### Passo a passo

1. Abra **Gestão por indicadores › Painel de desempenho** e selecione o **ciclo**.
2. Leia o farol: **Verde** na meta ou acima; **Amarelo** dentro da tolerância; **Vermelho** além da tolerância; **Sem meta** quando falta o realizado.
3. Clique numa linha para abrir o detalhamento (**Medições de origem**) com as versões da medição do período.
4. Use a discussão do detalhamento para comentar o número daquele período.
5. Clique em **Exportar CSV** para levar a grade a uma planilha.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/MZUVuD_4-g2JpcF-qxSZl_image.png" size="62" isUploading="false" width="620" height="387" showCaption="false"}

Figura 19 — Painel de desempenho com meta, realizado, variação, desempenho e farol.

### Observações

- A cor respeita a polaridade: o mesmo número pode ser verde num indicador Maior é melhor e vermelho num Menor é melhor.
- O painel só mostra indicador e meta **aprovados**. Se não aparece linha nenhuma (“Nenhum indicador com meta neste ciclo ainda.”), confira os dois selos na ficha.
- Linha **Sem meta** significa que há meta aprovada mas falta o realizado congelado.
- Indicador sigiloso continua na grade e no CSV com todos os números, mas com o nome **Indicador reservado** para quem não gerencia a estratégia nem os indicadores; essas linhas vêm no fim da lista.

## 3.18 Painel gerencial: visão consolidada do ciclo

ID BSC-IND-18

### Para que serve

O **Painel gerencial** responde como está o plano no conjunto, qual nível está travando e qual área puxa o resultado para baixo. Ele lê os mesmos números da grade e do CSV do Painel de desempenho.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia); Leitor/Auditor.

### Passo a passo

1. Abra **Gestão por indicadores › Painel gerencial** e escolha o ciclo em **Selecione um ciclo…**.
2. Leia os cartões **Objetivos**, **Indicadores**, **Atingimento médio** (com a contagem “N de M períodos medidos”) e **Fora da meta**.
3. Veja o gráfico **Distribuição do farol** (Verde, Amarelo, Vermelho, Sem meta).
4. Compare as tabelas **Por nível de desdobramento** e **Por área** (colunas Agrupamento, Indicadores, Medidos e Atingimento).
5. Leia o bloco **Mapa estratégico**: uma faixa por perspectiva, com os objetivos, o farol, o consolidado e os desdobramentos indentados.
6. No bloco **Indicador no tempo**, escolha um indicador para ver a curva do realizado e a meta tracejada.
7. Consulte, no fim da tela, **Compartilhado com a minha área**.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/CwdokSZ-w61B0OjQarEqU_image.png" size="62" isUploading="false" width="620" height="387" showCaption="false"}

Figura 20 — Painel gerencial com cartões consolidados, distribuição do farol, cortes por nível e por área e mapa estratégico.

### Observações

- Leia a contagem de períodos medidos antes de concluir: 96% sobre 1 de 12 períodos não é um plano em dia.
- Sem medição, o atingimento e o Fora da meta mostram “—”, nunca zero.
- O atingimento médio é a média simples das apurações; o peso do objetivo vale só no consolidado do mapa.
- A distribuição do farol conta apurações (indicador × período), não indicadores.
- Nível sem objetivos é omitido. **Sem área atribuída** e **Área não resolvida** são situações diferentes.
- Na curva, períodos sem apuração interrompem a linha em vez de desenhar uma queda.
- Itens sigilosos entram nas contagens para todos os leitores; só o nome fica reservado.

## 3.19 Meu painel (fixar widgets)

ID BSC-IND-19

### Para que serve

O **Meu painel** reúne, no fim do Painel gerencial, os itens que você fixou: o mapa inteiro, um objetivo, a curva de um indicador ou o resumo do ciclo. O painel é pessoal e também é o seu primeiro painel em **Gestão por indicadores › Painéis**.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia); Leitor/Auditor.

### Passo a passo

1. No **Painel gerencial**, use **Fixar no meu painel** no cabeçalho do mapa, no alfinete de um objetivo ou ao lado do combo **Indicador no tempo**.
2. Use **Fixar o resumo do ciclo** no cabeçalho do bloco **Indicador no tempo**.
3. Em **Meu painel**, reorganize com **Mover para cima** e **Mover para baixo**.
4. Use **Remover do meu painel** para tirar um item.
5. Para organizar em grade, criar outros painéis ou compartilhá-los, clique em **Organizar em Painéis**.

### Observações

- Ninguém mais vê o que você fixou, e fixar não amplia o que você pode ver.
- O mesmo item não entra duas vezes, e o painel guarda no máximo 24 widgets.
- Cada widget lê o ciclo em que foi fixado; “Fixado em outro ciclo” indica que é preciso escolher aquele ciclo no topo para vê-lo.

## 3.20 Indicadores sigilosos

ID BSC-IND-20

### Para que serve

Marcar um indicador como **Sigiloso** restringe quem lê o nome, a ficha, a discussão e as evidências dele, sem tirar os números das contas dos painéis. Um indicador também é tratado como sigiloso quando está ligado a um objetivo sigiloso.

**Quem usa:** Gestor de Desempenho (escritório de estratégia); Diretoria de Estratégia (patrocinador/aprovador); Leitor/Auditor.

### Passo a passo

1. No formulário do indicador, em **Apuração e sigilo**, marque **Sigiloso** e salve.
2. Confira na ficha o selo **Sigiloso** (ou **Objetivo sigiloso**, quando herdado do objetivo).
3. Acompanhe o desvio desse indicador diretamente no Painel de desempenho, pois ele não gera aviso automático.
4. Registre as apurações dele pelo Gestor de Desempenho, que é quem enxerga a ficha.

### Observações

- Indicador sigiloso não dispara o aviso automático de desvio.
- Para quem não gerencia a estratégia nem os indicadores, a ficha responde que o indicador não existe ou não está aberto — a mesma resposta de um endereço inexistente, de propósito.
- Na grade, no CSV, no mapa e no painel gerencial ele continua com os números e o nome **Indicador reservado**.
- A discussão e o compartilhamento ficam restritos a quem gerencia a estratégia; compartilhar com uma área não notifica ninguém.

[title]  15. Acesso, segurança e administração
[path] Aplicações/BSC/

O acesso ao Bússola/BSC é decidido em duas camadas. A primeira é o **cargo**: as regras de autorização (alçada) dizem quais cargos executam cada operação do Bússola/BSC, e uma operação sem nenhuma regra ativa fica liberada a qualquer pessoa autenticada. A segunda são os **perfis de acesso do BSC**, que somam itens de menu a pessoas específicas — um auditor, um consultor, uma área convidada — sem criar cargo; quando a pessoa ainda não existe no cadastro, ela é registrada como **usuário local do BSC**.

As credenciais que o Bússola/BSC usa para falar com outros sistemas ficam cifradas, e a chave de cifragem pode ser trocada sem parar o sistema. Toda mudança de configuração e de cadastro sensível fica no **histórico** do registro e na **trilha de auditoria**, com o antes e o depois.

***

## <font color="#15803D">15.1 Criar um perfil de acesso do BSC</font>

ID BSC-ACS-01

### <font color="#15803D">Para que serve</font>

Um **perfil de acesso do BSC** é um conjunto de itens de menu do Bússola/BSC. Quem é associado ao perfil passa a ver esses itens, além do que o cargo já lhe dá, e os perde quando é retirado. Serve para dar a um auditor, a um consultor ou a uma área convidada apenas as telas de que precisam, sem criar cargo no organograma.

O perfil só soma: nunca tira o que o cargo dá.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Administrador do sistema.

### <font color="#15803D">Passo a passo</font>

1. Abra **Governança e riscos › Perfis de acesso do BSC** e clique em **Novo perfil de acesso**.
2. Informe o **nome** do perfil (por exemplo, "Leitura de riscos") e, se quiser, a **descrição**.
3. Em **Menus e itens do BSC**, marque os itens do perfil (por exemplo, **Registro de riscos** e **Mapa de riscos**). A caixa do grupo marca o grupo inteiro.
4. Para cada item que tem permissão de edição própria, decida se marca **Permitir editar**. Sem essa marca, o perfil só consulta.
5. Clique em **Salvar**.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/gKyuDmBdgkcNsiilGDRi5_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 179 — Perfis de acesso do BSC com os itens de menu de cada perfil

### <font color="#15803D">Observações</font>

- O perfil precisa de ao menos um item: sem isso, aparece "Escolha ao menos um item de menu para o perfil."
- Alguns itens só abrem com a permissão de edição (por exemplo, **Planejamento estratégico** e **Console SQL**). A tela avisa que escolhê-los já deixa a pessoa editar.
- Tela que nenhuma regra de autorização governa continua aberta a toda pessoa autenticada; para essas telas o perfil não muda nada.
- Mantém perfis e usuários locais quem tem a permissão "Manter os perfis de acesso do BSC", concedida por padrão à Diretoria de Estratégia.
- O **Histórico** do perfil registra cada mudança de itens e de pessoas, com o antes e o depois.

***

## <font color="#15803D">15.2 Associar e retirar pessoas de um perfil</font>

ID BSC-ACS-02

### <font color="#15803D">Para que serve</font>

Depois de criado, o perfil recebe as pessoas que devem ver os seus itens, com vigência opcional. A retirada vale na próxima tela que a pessoa abrir.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Administrador do sistema.

### <font color="#15803D">Passo a passo</font>

1. Abra **Governança e riscos › Perfis de acesso do BSC**.
2. Na linha do perfil, clique no botão **Pessoas** (ícone de pessoas).
3. Em **Associar uma pessoa**, procure a pessoa pelo nome ou pelo login.
4. Se quiser, informe **Válido a partir de** e **Válido até**. Datas em branco significam acesso sem prazo.
5. Clique em **Associar**.
6. Para retirar uma pessoa, clique em **Retirar do perfil** (lixeira) na linha dela e confirme no painel que aparece.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/gKyuDmBdgkcNsiilGDRi5_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 180 — Pessoas associadas ao perfil, com vigência

### <font color="#15803D">Observações</font>

- No painel de confirmação, **Cancelar** não muda nada; **Retirar do perfil** confirma.
- Ao ser retirada, a pessoa perde os itens do perfil na próxima tela que abrir; o que ela tem pelo cargo continua.

***

## <font color="#15803D">15.3 Consultar quem tem acesso a uma tela do BSC</font>

ID BSC-ACS-03

### <font color="#15803D">Para que serve</font>

A aba **Quem tem acesso** responde, para cada item de menu do Bússola/BSC, quem abre a tela e por quê: pelo cargo (regra de autorização) ou por um perfil de acesso.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Administrador do sistema; Leitor/Auditor.

### <font color="#15803D">Passo a passo</font>

1. Abra **Governança e riscos › Perfis de acesso do BSC**.
2. Clique na aba **Quem tem acesso**.
3. Escolha o item de menu (por exemplo, **Registro de riscos**).
4. Leia a lista: cada pessoa aparece com a origem do acesso — **Cargo** ou **Perfil de acesso** (com o nome do perfil) — e se ela pode editar.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/gKyuDmBdgkcNsiilGDRi5_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 181 — Aba Quem tem acesso com a origem de cada acesso

### <font color="#15803D">Observações</font>

- Se a pessoa vê uma tela que não está no perfil dela, confira aqui: ela tem a tela pelo cargo, ou a tela não é governada por nenhuma regra (aberta a todos). A aba avisa quando a tela não é governada.
- Duas telas podem usar a mesma permissão (por exemplo, **Registro de riscos** e **Análises SWOT**). O menu mostra só a escolhida, mas a outra continua alcançável: a permissão é a unidade de segurança; o item de menu é a unidade de apresentação.

***

## <font color="#15803D">15.4 Cadastrar um usuário local do BSC</font>

ID BSC-ACS-04

### <font color="#15803D">Para que serve</font>

Quando a pessoa ainda não existe no cadastro do sistema — por exemplo, uma auditora externa —, a tela **Usuários locais do BSC** a cadastra com nome, e-mail, login e unidade, e já a associa aos perfis de acesso.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Administrador do sistema.

### <font color="#15803D">Passo a passo</font>

1. No cabeçalho do portal, escolha a **empresa** em que a pessoa vai trabalhar (por exemplo, Empresa Exemplo S.A.). O formulário mostra essa empresa.
2. Abra **Governança e riscos › Usuários locais do BSC** e clique em **Novo usuário local**.
3. Informe **Nome** (por exemplo, Maria Auditora), **E-mail** (maria.auditora\@exemplo.com.br), **Login** (por exemplo, maria.auditora) e **Unidade** (por exemplo, AUDIN — Auditoria Interna).
4. Marque os perfis de acesso que a pessoa recebe (por exemplo, "Leitura de riscos").
5. Clique em **Salvar**.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/d7ncKZyfUrx7TrAlO4BMl_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 182 — Usuários locais do BSC com unidade e perfis de acesso

### <font color="#15803D">Observações</font>

- O login tem de 3 a 40 caracteres: letras minúsculas, dígitos, ponto, hífen ou sublinhado.
- Login e e-mail não se repetem (o e-mail sem distinção de maiúsculas). O repetido é recusado com a mensagem "já é usado por outra pessoa".
- O usuário local não tem senha no Bússola/BSC. Numa instalação com login corporativo, o mesmo login precisa existir no provedor de identidade da empresa.
- A pessoa trabalha só na empresa escolhida no cabeçalho no momento do cadastro. Sem empresa escolhida, ela fica com todas as empresas.

***

## <font color="#15803D">15.5 Exemplo: perfil "Leitura de riscos" para a auditoria</font>

ID BSC-ACS-05

### <font color="#15803D">Para que serve</font>

Este exemplo junta as seções anteriores: a Auditoria Interna precisa consultar o registro e o mapa de riscos, sem editar nada e sem ganhar um cargo novo.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Administrador do sistema; Leitor/Auditor.

### <font color="#15803D">Passo a passo</font>

1. Crie o perfil **Leitura de riscos** em **Governança e riscos › Perfis de acesso do BSC**, com os itens **Registro de riscos** e **Mapa de riscos**, sem marcar **Permitir editar**.
2. Cadastre a usuária local **Maria Auditora** (maria.auditora\@exemplo.com.br), unidade AUDIN, em **Governança e riscos › Usuários locais do BSC**, marcando o perfil **Leitura de riscos**.
3. Peça à usuária que entre no portal: no grupo do Bússola/BSC ela vê só os itens do perfil, além dos que o cargo já lhe dava.
4. Peça que ela abra a ficha de um risco (por exemplo, "Atraso na emissão de licenças ambientais da Ponte do Vale"): a ficha abre para consulta, sem oferecer edição.
5. Confira na aba **Quem tem acesso** que ela aparece com origem **Perfil de acesso — Leitura de riscos**.
6. Ao fim do trabalho, retire-a do perfil (ou deixe a vigência expirar) e confira que os itens somem do menu dela.
7. Abra o **Histórico** do perfil e confira o registro de cada mudança.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/gKyuDmBdgkcNsiilGDRi5_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 183 — Perfil Leitura de riscos com a usuária associada

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/d7ncKZyfUrx7TrAlO4BMl_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 184 — Usuária local Maria Auditora cadastrada na AUDIN

### <font color="#15803D">Observações</font>

- Se a pessoa continuar vendo uma tela depois de retirada, ela a tem pelo cargo ou a tela não é governada por regra.

***

## <font color="#15803D">15.6 Configurar as regras de autorização (alçada) das operações do Bússola/BSC</font>

ID BSC-ACS-06

### <font color="#15803D">Para que serve</font>

A tela **Alçada** define quais cargos executam cada operação sensível do sistema. No Bússola/BSC, as operações ficam no módulo **Gestão por indicadores** — por exemplo, "Gerenciar planejamento estratégico", "Gerenciar indicadores e metas", "Gerenciar planos de ação", "Cadastrar e avaliar riscos corporativos", "Ver e marcar riscos sigilosos", "Validar versões de processos", "Publicar painéis para cargos e para a organização", "Configurar conectores do BSC", "Ligar canais de Teams e Discord às áreas", "Editar as mensagens institucionais do Bússola/BSC" e "Manter os perfis de acesso do BSC".

Regra importante: uma operação **sem nenhuma regra ativa fica liberada** a qualquer usuário autenticado.

**Quem usa:** Administrador do sistema; Diretoria de Estratégia (patrocinador/aprovador).

### <font color="#15803D">Passo a passo</font>

1. Abra **Início › Alçada**.
2. Confira no topo o painel **Operações sem regra ativa**: ele lista o que ainda está liberado a todos. Use-o como checklist do que falta governar.
3. Use o filtro **Módulo** = **Gestão por indicadores** (e, se quiser, o filtro **Cargo** e a busca) para ver as regras do Bússola/BSC.
4. Clique em **Nova regra**.
5. Escolha o **Módulo** e a **Operação** (por exemplo, "Cadastrar e avaliar riscos corporativos").
6. Escolha o **Cargo** entre os cargos cadastrados e, se quiser, a **Unidade organizacional**.
7. Clique em **Salvar**. A regra vale imediatamente.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/X9ysGv29hbyr4whrYzjRU_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 185 — Alçada: regras de autorização por cargo e painel de operações sem regra ativa

### <font color="#15803D">Observações</font>

- A pessoa é autorizada quando o cargo da sua lotação primária vigente casa com a regra. Lotação com início futuro ainda não vale.
- Ao criar a primeira regra de uma operação, quem não tem cargo coberto por ela passa a ser recusado. Confira antes quem precisa da operação.
- Quem não tem a permissão de uma tela não vê o item no menu; se abrir o endereço, vê a mensagem de recusa.
- Toda regra criada ou alterada fica na trilha de auditoria.

***

## <font color="#15803D">15.7 Restringir a regra a uma unidade e conceder um módulo inteiro</font>

ID BSC-ACS-07

### <font color="#15803D">Para que serve</font>

O mesmo cargo costuma existir em várias unidades. A regra pode valer para o cargo em toda a organização ou só para quem está lotado numa unidade e nas unidades abaixo dela. Também é possível conceder, de uma vez, todas as operações do Bússola/BSC a um cargo.

**Quem usa:** Administrador do sistema.

### <font color="#15803D">Passo a passo</font>

1. Em **Início › Alçada**, clique em **Nova regra**.
2. Escolha o **Módulo** = **Gestão por indicadores**.
3. Para conceder tudo, marque **Conceder todas as operações de Gestão por indicadores (N)**: o sistema grava uma regra por operação que o cargo ainda não tem.
4. Escolha o **Cargo**.
5. Em **Unidade organizacional**, deixe **Todas as unidades (geral)** para valer em toda a organização, ou escolha uma unidade (por exemplo, SUPLAN) para restringir a ela e às unidades subordinadas.
6. Clique em **Salvar**.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/X9ysGv29hbyr4whrYzjRU_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 186 — Nova regra com módulo, operação, cargo e unidade

### <font color="#15803D">Observações</font>

- Uma regra na superintendência alcança as gerências subordinadas, não o contrário.
- Restringir uma regra não cria restrição onde não havia: operação sem nenhuma regra ativa continua liberada.
- Quem tem o cargo mas está lotado fora da unidade da regra não é alcançado por ela; se nenhuma outra regra o alcançar, a operação lhe é negada.
- Se uma das regras do lote for recusada, a mensagem informa quantas já foram gravadas.

***

## <font color="#15803D">15.8 Delegar a alçada de um cargo (substituição)</font>

ID BSC-ACS-08

### <font color="#15803D">Para que serve</font>

Quando o titular de um cargo se ausenta (férias, licença) ou a função passa temporariamente a outra pessoa, uma **delegação** faz um substituto exercer a alçada do cargo no período, até o limite desse cargo.

**Quem usa:** Administrador do sistema; Diretoria de Estratégia (patrocinador/aprovador).

### <font color="#15803D">Passo a passo</font>

1. Abra **Administração › Delegações** e clique em **Nova delegação**.
2. Escolha o **tipo**: Temporária (com início e fim) ou Permanente.
3. Escolha o **escopo**: o cargo inteiro ou uma operação específica.
4. Escolha o **cargo** de origem e o **substituto**.
5. Escreva a **justificativa** (obrigatória) e, na temporária, informe início e fim. Salve.
6. Para encerrar antes do prazo, use a ação de encerrar na linha da delegação.

### <font color="#15803D">Observações</font>

- Delegação por operação vence a do cargo inteiro para aquela operação. Duas delegações vigentes do mesmo escopo não podem se sobrepor.
- Quem já podia agir por conta própria continua usando a própria autorização, sem registro de substituição.
- Se a pessoa responde por dois cargos diferentes ao mesmo tempo, o sistema recusa em vez de escolher um.
- O ato feito por substituição aparece na trilha de auditoria com a tarja "Ato por substituição: autoridade do cargo X".

***

## <font color="#15803D">15.9 Consultar as chaves de cifragem e recifrar os segredos</font>

ID BSC-ACS-09

### <font color="#15803D">Para que serve</font>

As senhas, chaves e tokens que o Bússola/BSC guarda para falar com outros sistemas (as integrações, os webhooks do Teams e do Discord, a conta de WhatsApp) ficam cifrados no banco de dados. Cada segredo registra qual chave o cifrou, o que permite trocar a chave sem parar o sistema. A tela **Chaves de cifragem** mostra os nomes das chaves e quantos segredos usam cada uma — nunca mostra uma chave.

**Quem usa:** Administrador do sistema.

### <font color="#15803D">Passo a passo</font>

1. Abra **Início › Chaves de cifragem**.
2. No cartão **Chaves configuradas**, confira os nomes das chaves. A ativa traz o selo **Ativa — cifra os segredos novos**; a chave inicial do sistema traz o selo **Chave original**.
3. Na tabela **Segredos guardados por chave**, confira quantos segredos usam cada chave, por ambiente e por local onde o segredo fica.
4. Em **Recifrar com a chave ativa**, clique em **Recifrar agora** e em **Confirmar**.
5. Leia o resultado: quantos segredos foram recifrados, quantos já estavam na chave ativa, quantos não abrem e quantos foram alterados durante a recifragem.
6. Confira na tabela que nenhum segredo ficou na chave antiga. Se algum ambiente não terminou, recifre de novo.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/Tw84WZG8Pfdn7wPtVQrVo_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 187 — Chaves de cifragem: chaves configuradas e segredos guardados por chave

### <font color="#15803D">Observações</font>

- A tela é restrita ao administrador do sistema.
- Recifrar pode ser repetido quantas vezes quiser: o que já está na chave ativa não muda.
- Segredos que "não abrem" foram copiados de outro cadastro ou alterados direto no banco. Eles ficam como estão e precisam ser cadastrados de novo na integração; o aviso do resultado fica amarelo.
- Cada segredo fica amarrado ao seu cadastro: copiado para outro cadastro ou outro ambiente, ele não abre e nada é revelado.

***

## <font color="#15803D">15.10 Trocar a chave de cifragem em duas fases</font>

ID BSC-ACS-10

### <font color="#15803D">Para que serve</font>

A troca periódica da chave é feita em conjunto com a equipe de infraestrutura, que mantém as chaves na configuração do servidor. Ela acontece em duas fases porque o servidor costuma rodar em mais de uma cópia, e todas precisam conhecer a chave nova antes que ela passe a cifrar.

**Quem usa:** Administrador do sistema.

### <font color="#15803D">Passo a passo</font>

1. Fase 1: peça à equipe de infraestrutura que acrescente a chave nova à configuração de todas as cópias do servidor, sem ativá-la, e reinicie. Em **Início › Chaves de cifragem**, a chave nova aparece em **Chaves configuradas** sem o selo de ativa.
2. Fase 2: peça que a chave nova seja marcada como ativa e o servidor reiniciado. A partir daí todo segredo novo é cifrado com ela.
3. Em **Início › Chaves de cifragem**, clique em **Recifrar agora** e confirme.
4. Confira em **Segredos guardados por chave** que a chave antiga ficou com zero segredos.
5. Só então peça à infraestrutura que retire a chave antiga da configuração.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/Tw84WZG8Pfdn7wPtVQrVo_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 188 — Chave nova ativa e contagem de segredos por chave depois da recifragem

### <font color="#15803D">Observações</font>

- Nunca se retira uma chave que ainda tem segredos. Se algum segredo indicar a chave retirada, o servidor recusa subir e informa quantos segredos dependem dela: devolva a chave, recifre e retire de novo.
- Para voltar atrás, a infraestrutura volta a ativa para a chave anterior mantendo a nova na configuração; uma nova recifragem traz tudo para a anterior.
- Restaurar a cópia do banco em outro banco ou esquema (por exemplo, um clone para homologação) invalida os segredos de propósito: cadastre de novo as credenciais no ambiente de destino. Recifrar não resolve.
- Cada ambiente de homologação e produção precisa da sua própria chave, guardada como segredo.

***

## <font color="#15803D">15.11 Consultar o histórico de um registro do Bússola/BSC</font>

ID BSC-ACS-11

### <font color="#15803D">Para que serve</font>

Cada cadastro do Bússola/BSC guarda o histórico das suas mudanças: quem fez, quando, e o antes e o depois de cada campo. É o caminho mais rápido para investigar uma alteração específica — numa regra de alerta, num perfil de acesso, num canal de área, numa mensagem institucional ou na ficha de um indicador, ação ou risco.

**Quem usa:** Gestor de Desempenho (escritório de estratégia); Diretoria de Estratégia (patrocinador/aprovador); Leitor/Auditor; Administrador do sistema.

### <font color="#15803D">Passo a passo</font>

1. Abra a ficha ou a linha do registro que deseja investigar (por exemplo, o perfil "Leitura de riscos" ou a regra de atraso de ações estratégicas).
2. Clique no botão **Histórico** ou no ícone de relógio.
3. Leia cada evento: autor, data e hora, e os valores antes e depois da mudança.
4. Para uma visão de vários registros, use a **Trilha de auditoria** (seção seguinte).

### <font color="#15803D">Observações</font>

- O histórico nunca mostra segredos: credenciais e endereços de webhook aparecem só como "Definido em … por …".
- O histórico abre a mesma trilha de auditoria, já filtrada para aquele registro.

***

## <font color="#15803D">15.12 Configurar e consultar a trilha de auditoria</font>

ID BSC-ACS-12

### <font color="#15803D">Para que serve</font>

Toda criação, edição e exclusão de cadastro sensível é gravada automaticamente. O administrador escolhe o que é monitorado e qualquer pessoa autorizada consulta quem fez o quê.

**Quem usa:** Administrador do sistema; Leitor/Auditor.

### <font color="#15803D">Passo a passo</font>

1. Abra **Administração › Auditoria** e marque as entidades acompanhadas pela trilha.
2. Abra **Administração › Trilha de auditoria**.
3. Filtre por autor, entidade, ação e período. Enquanto os filtros não forem refinados, a área de resultados fica vazia.
4. Leia cada evento: autor, data e hora, e o antes e o depois (estado inicial na criação, campos alterados na edição, estado final na exclusão).
5. Exporte o resultado em CSV quando precisar anexá-lo a um relatório de auditoria.

### <font color="#15803D">Observações</font>

- Ao desmarcar uma entidade em **Auditoria**, novas operações nela deixam de gerar evento. Use apenas para cadastros de baixo risco.
- Um evento autorizado por delegação traz a tarja "Ato por substituição: autoridade do cargo X"; a informação também sai na exportação.

***

## <font color="#15803D">15.13 Controlar sessões ativas e faixas de IP</font>

ID BSC-ACS-13

### <font color="#15803D">Para que serve</font>

Duas proteções complementam as regras de acesso: a lista de **sessões ativas**, que permite encerrar um acesso em andamento, e as **faixas de IP**, que limitam de quais redes o sistema pode ser acessado.

**Quem usa:** Administrador do sistema.

### <font color="#15803D">Passo a passo</font>

1. Abra **Início › Sessões ativas** para ver os logins conectados, com usuário, início da sessão, último acesso e origem.
2. Para encerrar uma sessão, use a ação de encerrar na linha dela. O usuário precisa entrar de novo.
3. Abra **Início › Faixas de IP** para ver as redes autorizadas.
4. Para registrar uma faixa, informe o intervalo de rede no formato CIDR (por exemplo, 203.0.113.0/24) e uma descrição, e salve.

### <font color="#15803D">Observações</font>

- Com a lista de faixas preenchida, acessos de fora delas são recusados. Lista vazia significa sem restrição de IP.
- Sessões inativas por muito tempo são encerradas automaticamente pela política de tempo limite.
- Acesso recusado sem motivo aparente: confira se o IP de origem está numa faixa cadastrada.

[title] 34. Instalar como aplicativo
[path] Aplicações/GRCS/

*A plataforma se instala como aplicativo no computador e no celular, e o que ela guarda — e recusa guardar — quando a rede cai.*

A plataforma é um aplicativo web instalável. No computador, o navegador oferece a instalação na barra de endereço; no celular, pelo menu do navegador em "Adicionar à tela de início". Instalada, ela abre em janela própria, sem barra de endereço, e aparece na lista de aplicativos do sistema.

Não há loja, não há pacote para distribuir e não há versão para manter em paralelo: o aplicativo é a mesma aplicação, e atualizar o servidor atualiza todo mundo.

***

### <font color="#15803D">O que acontece quando a rede cai</font>

Um trabalhador de serviço guarda o **casco** da aplicação — a página, o estilo, o código. Se a rede cair, a aplicação ainda abre e diz que está sem rede, em vez de mostrar a tela de erro do navegador.

**Nada que venha da API é guardado.** A decisão é de segurança e não de desempenho: numa plataforma de GRC, uma resposta de auditoria em cache é dado sensível sobrevivendo no disco de quem saiu da empresa. Por isso o aplicativo instalado **não funciona sem rede** para nada que dependa de dado — ele abre, e informa.

A estratégia é rede primeiro, casco depois: o navegador tenta a rede sempre, e o cache só responde quando ela falha. Numa plataforma onde o dado muda a cada aprovação, servir tela velha por padrão seria pior do que dizer que está sem conexão.

***

### <font color="#15803D">Para quem administra</font>

O manifesto fica em /manifest.webmanifest e o trabalhador de serviço em /sw\.js. Ambos precisam ser públicos — o navegador os busca antes de qualquer autenticação. Se /sw\.js responder 401, o registro falha **em silêncio**: não há erro na tela, o aplicativo simplesmente nunca se instala.

Em produção, servir por HTTPS é requisito do navegador, e não recomendação: fora de localhost, sem HTTPS não há trabalhador de serviço e não há instalação.

[title] 33. Acessibilidade
[path] Aplicações/GRCS/

*O que a plataforma cumpre das regras da W3C, como isso é medido a cada execução, e o que nenhuma ferramenta mede.*

A plataforma é verificada contra a **WCAG 2.1, níveis A e AA** — o critério que a legislação brasileira e a maioria dos contratos públicos exigem. A verificação não é uma declaração: roda na cadeia de testes, em mais de cinquenta telas — as do IMR entre elas — e nos três temas, a cada execução; cinco telas representativas repetem a varredura em Firefox, WebKit e no iPhone. O IMR entrou na lista porque módulo que nasce depois da varredura é exatamente onde a regressão passa despercebida: ninguém mede o que ainda não existia quando a lista foi escrita.

:::BlockQuote
cd testes && ./executar.sh acessibilidade
:::

***

### <font color="#15803D">O que está garantido</font>

**Estrutura.** Marcos de região nomeados, link para pular direto ao conteúdo como primeiro parador de tabulação, idioma declarado na página, cada campo com rótulo associado, cada botão com nome acessível — inclusive os que são só ícone.

**Contraste.** Todo par de cores usado em texto alcança 4,5:1. Chegar lá custou três mudanças de paleta, e cada uma nasceu de uma medição:

•     O verde da marca escureceu de #2f8f3e para #277732. Branco sobre o anterior dava 4,10:1.

•     Surgiu um token para a cor do texto **sobre** o acento. O acento é escuro no tema claro e claro nos temas escuro e cinza; branco fixo em cima dele dava 2,17:1 em dois dos três temas.

•     O vermelho do tema cinza clareou de #dd8878 para #e59a8c.

**Opacidade deixou de ser hierarquia de texto.** opacity-70 sobre um token que passa com 6,28:1 o derruba para 3,19:1. Texto secundário usa o token próprio.

**O mapa de calor escolhe a cor do texto medindo.** A célula é a cor da série misturada com a superfície em proporção que depende do valor — a cor de fundo só existe depois de renderizada. Nenhuma regra fixa de "branco acima de tanto" funciona nos três temas. A plataforma mistura as cores, calcula a luminância pela fórmula da WCAG e escolhe o extremo de maior contraste.

**Teclado.** Todo controle focado mostra onde o foco está, o foco não entra em região escondida, diálogos prendem o foco e o devolvem ao fechar, e Esc fecha. Dentro do diálogo o Tab só para no que está à vista: aba escondida, painel recolhido e conteúdo de um "mais detalhes" fechado ficam de fora da volta.

**Botão apagado diz por quê, à vista.** Quando falta permissão para uma ação, o botão aparece desbotado — e não some —, e logo abaixo da barra vem uma linha curta com o motivo: qual ação e qual permissão do perfil falta ("Lançar e Apagar: Seu perfil não tem a permissão …"). Antes o motivo só aparecia ao passar o rato (que não existe no celular nem no teclado) ou para o leitor de tela. A nota sai uma vez por trecho da tela, e não em cada botão; quando há motivos diferentes no mesmo trecho, ela vira a pergunta "Por que não dá para …?", que abre com clique, toque ou Enter.

**Alvos de toque.** Os botões só de ícone que tiram um item — desfazer vínculo de caso, desvincular risco de um achado, tirar um anexo — têm área de toque de pelo menos 24 × 24 px (WCAG 2.5.8), sem o ícone crescer.

**Movimento.** prefers-reduced-motion é respeitado: quem pediu menos animação ao sistema recebe menos animação aqui.

**Texto que cresce.** Aumentar a fonte é critério de acessibilidade, e dos que ferramenta nenhuma mede: o axe verifica a página como ela está, e redimensionar exige aumentar de verdade e olhar o que quebrou. São dois critérios AA — **1.4.4**, texto a 200% sem perder conteúdo nem função, e **1.4.10**, refluxo a 320px sem rolagem em dois eixos, que é a condição de quem usa zoom de 400%.

A plataforma cumpre os dois, e agora isso é medido a cada execução, nas duas larguras. O que sustenta é o texto ser declarado em unidade relativa: travado em pixel, ele ignora o ajuste do navegador e o controle de acessibilidade do sistema operacional deixa de ter efeito.

**E há um controle no próprio produto**: **Tamanho do texto**, nas Preferências, com três tamanhos — padrão, grande (112%) e maior (125%). Ele aparece também na tela de entrada e no cabeçalho dos portais de atendimento e de resposta, porque quem precisa de letra maior precisa dela para ler o formulário de login, e não só depois dele.

Ele não é o que faz a plataforma cumprir o critério 1.4.4 — isso é do texto em unidade relativa, e já valia antes. Ele existe porque o zoom do navegador aumenta **tudo**: margens, ícones, grade. Quem precisa de letra maior nem sempre quer a tela inteira maior. Aqui só a raiz tipográfica muda.

São três degraus e não um controle contínuo. Um deslizador de porcentagem convidaria a testar dezenas de valores intermediários que ninguém verificou; três tamanhos são três estados, e os três estão medidos na suíte.

Um detalhe que o teste prende: a escolha é aplicada **antes da montagem**, junto com o tema. Se fosse aplicada depois, a página apareceria no tamanho padrão e cresceria um instante depois — e quem escolheu letra maior veria a tela saltar a cada carregamento.

***

### <font color="#15803D">O que nenhuma ferramenta mede</font>

O axe-core verifica atributos e contraste. Ele não percorre a tela: não descobre que a ordem de tabulação pula a navegação, que um rótulo está tecnicamente presente e semanticamente errado, ou que uma mensagem de erro aparece longe do campo que a causou. Por isso há também um teste de navegação por teclado — e por isso nada disso substitui alguém usando a plataforma com leitor de tela.

***

### <font color="#15803D">O assistente, que era o pior caso</font>

Ele abria sozinho na primeira entrada e cobria a tela com um fundo que engolia qualquer clique, e o Esc não o fechava. A primeira ação possível de quem entrava pela primeira vez era fechar uma coisa que ninguém pediu — orientação que obstrui deixa de ser orientação.

Foi corrigido em três frentes. **Não abre sozinho**: na primeira entrada o botão "Como funciona" ganha um ponto, e o nome acessível dele diz "ainda não visto", porque cor sozinha não comunica a quem não a enxerga. **Não bloqueia**: virou painel encostado à direita, sem fundo interceptando — dá para ler um passo e clicar no menu ao mesmo tempo, e aria-modal="false" diz ao leitor de tela a verdade, que o resto da página continua disponível. **Fecha pelo Esc**, e devolve o foco ao botão que o abriu.

Em tela estreita ele ocupa a largura toda, porque ali não existe "ao lado".

[title] 1. Introdução ao BSC
[path] Aplicações/BSC/

# 1. Introdução ao Bússola/BSC

O **Bússola**/BSC é o módulo de gestão da estratégia (Balanced Scorecard — BSC) do sistema. Nele a empresa registra o seu plano estratégico e acompanha, período a período, se está entregando o que se comprometeu a entregar. Tudo fica na mesma base de dados: o número que acende o farol vem do próprio dado registrado, com origem rastreável, sem planilha paralela.

Este capítulo apresenta os conceitos do Bússola/BSC, os perfis funcionais que trabalham nele e os recursos de navegação comuns a todas as telas: o menu lateral, o seletor de empresa, a ajuda da tela, a trilha de alterações, a discussão entre áreas, o recurso de seguir um registro e o uso no celular.

Os exemplos deste manual usam uma organização fictícia, a **Empresa Exemplo S.A.**, empresa de infraestrutura com obras rodoviárias, pontes e terminais, e o seu **Ciclo Estratégico 2026 — Empresa Exemplo**.

## 1.1 O que é o Bússola/BSC

ID BSC-INT-01

### Para que serve

O Bússola/BSC organiza a estratégia de cima para baixo. A empresa abre um **ciclo estratégico** (a versão do plano para um período), organiza as **perspectivas** (as grandes lentes do plano, como Clientes e sociedade, Resultados financeiros, Processos internos e Aprendizado e crescimento), cadastra os **objetivos** de cada perspectiva e cria os **indicadores** que medem cada objetivo. Cada indicador recebe **metas** por período e, ao longo do ano, as **apurações** (o valor realizado). Os painéis cruzam meta e realizado e pintam o farol.

Em volta desse núcleo, o Bússola/BSC reúne: **planos de ação 5W2H** para corrigir desvios; **ações estratégicas** (os projetos da carteira, com escopo, cronograma e execução); a **agenda estratégica** com reuniões e encaminhamentos; o **registro de riscos** e as **análises SWOT**; os **processos** e a **cadeia de valor**; **painéis e relatórios**; os **dados do Bússola**/BSC (consultas, cargas e portais) e as **integrações** com outros sistemas, como SEI, SIAFI, Portal da Transparência e canais de mensagem.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia); Responsável por ação/área; Analista de Integração de Dados; Leitor/Auditor; Administrador do sistema.

### Passo a passo

1. Entre no sistema com o seu login corporativo.
2. No menu lateral, abra o grupo **Gestão por indicadores**.
3. Clique em **Planejamento estratégico** para ver os ciclos da empresa (por exemplo, **Ciclo Estratégico 2026 — Empresa Exemplo**).
4. Abra **Mapa estratégico** para ter a visão do plano inteiro numa tela, com os faróis de cada objetivo.
5. Abra **Mesa de trabalho** para ver o que está sob a sua responsabilidade.
6. Use os demais grupos do menu conforme o seu perfil: **Integrações**, **Dados do Bússola**/BSC e **Governança e riscos**.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/F8NvQRvRDT798jb98s0Fz_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 1 — Mapa estratégico do Ciclo Estratégico 2026 — Empresa Exemplo, com objetivos por perspectiva e faróis.

### Observações

- O número exibido no painel é auditável: cada apuração guarda quem registrou, quando e, quando calculada, a memória de cálculo.
- Um ciclo em **Rascunho** ainda não aceita objetivos, indicadores nem apurações; ative-o antes de começar.
- Ação estratégica (projeto da carteira) e ação de plano 5W2H (resposta a um indicador fora da meta) são coisas diferentes. O manual sempre diz qual das duas.

## 1.2 Perfis funcionais

ID BSC-INT-02

### Para que serve

O Bússola/BSC separa o trabalho entre perfis funcionais, para que quem define a meta não seja quem registra o número comparado com ela. O acesso vem do **cargo** de cada pessoa (definido pela lotação dela) e, quando preciso, de um **perfil de acesso do BSC**, que soma itens de menu a uma pessoa sem criar cargo novo.

Os perfis usados neste manual são: **Diretoria de Estratégia** (patrocinador e aprovador) — monta o plano: cria, ativa e fecha ciclos, ajusta perspectivas, cria e desdobra objetivos, mantém os cadastros estratégicos e decide sobre ações estratégicas e mudanças; **Gestor de Desempenho** (escritório de estratégia) — cuida dos números: fichas de indicador, metas, apurações, retificações, planos de ação e a carteira de ações estratégicas; **Responsável por ação/área** — registra a apuração e a execução dos itens que estão com ele, em geral pela Mesa de trabalho; **Analista de Integração de Dados** — escreve consultas, cargas e integrações que alimentam o Bússola/BSC; **Leitor/Auditor** — consulta painéis, fichas e trilhas sem alterar nada; **Administrador do sistema** — mantém usuários, perfis de acesso, alçadas, canais e chaves.

**Quem usa:** Administrador do sistema; Diretoria de Estratégia (patrocinador/aprovador).

### Passo a passo

1. Confirme com o Administrador do sistema o seu cargo e a sua lotação: é a lotação que dá o acesso ao Bússola/BSC.
2. Se precisar de telas que o cargo não dá, peça a inclusão num perfil de acesso em **Governança e riscos › Perfis de acesso do BSC**.
3. Para conferir quem abre uma tela e por quê, use a aba **Quem tem acesso** em **Governança e riscos › Perfis de acesso do BSC**.
4. Para pessoas que ainda não estão no cadastro (por exemplo, um consultor convidado), o administrador usa **Governança e riscos › Usuários locais do BSC**.
5. Para mudar qual cargo executa uma operação, o administrador usa **Início › Alçada**.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/gKyuDmBdgkcNsiilGDRi5_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 2 — Perfis de acesso do BSC: itens de menu e pessoas associadas.

### Observações

- O perfil de acesso só **soma** telas ao que o cargo já dá; ele nunca retira acesso.
- Quem tem apenas leitura do painel vê somente indicadores e metas **aprovados**. Um indicador que “sumiu” para a diretoria quase sempre ainda não foi aprovado.
- Indicadores e objetivos **sigilosos** aparecem nos painéis com números, mas com o nome reservado para quem não gerencia a estratégia ou os indicadores.
- Atenção ao configurar a alçada: uma operação que fica sem nenhuma regra ativa passa a ser liberada a qualquer usuário autenticado.

## 1.3 Navegação pelo menu lateral

ID BSC-INT-03

### Para que serve

O menu lateral reúne as telas do Bússola/BSC em quatro grupos. **Gestão por indicadores**: Mesa de trabalho, Planejamento estratégico, Indicadores, Indicadores importados, Mapa estratégico, Cadastros estratégicos, Ações estratégicas, Categorias de ação, Classificações do escopo, Agenda estratégica, Categorias da agenda, Painel de desempenho, Painéis, Relatórios, Painel gerencial, Alertas e mensagens e Configuração de conectores. **Integrações**: Integrações, Monitor de integrações, Tabelas de equivalência e Canais de área. **Dados do Bússola**/BSC: Console SQL, Consultas salvas, Cargas de dados, Portais do governo, Itens de portais e Categorias de itens. **Governança e riscos**: Registro de riscos, Mapa de riscos, Matrizes e naturezas de risco, Processos, Tipos de processo e macroprocessos, Modelos de plano de riscos, Análises SWOT, Cadeia de valor, Perfis de acesso do BSC e Usuários locais do BSC.

Cada pessoa vê apenas os itens que o cargo ou o perfil de acesso dela permitem. No grupo **Início** ficam recursos gerais usados pelo Bússola/BSC, como **Solicitações de aprovação**, **Alçada** e **Preferências de notificação**.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia); Responsável por ação/área; Analista de Integração de Dados; Leitor/Auditor; Administrador do sistema.

### Passo a passo

1. No menu lateral, clique no nome do grupo (por exemplo, **Gestão por indicadores**) para expandi-lo.
2. Clique no item desejado, por exemplo **Gestão por indicadores › Painel de desempenho**.
3. Para voltar a uma lista a partir de uma ficha, use o item do menu ou o botão de voltar do navegador.
4. Se um item esperado não aparece, confira com o administrador o seu cargo ou o seu perfil de acesso.

### Observações

- Duas telas podem usar a mesma permissão de leitura: o menu mostra só a escolhida no perfil, mas a outra continua acessível a quem tem a permissão.
- Ausência de um item no menu não significa que o dado não exista — significa que o seu acesso não inclui aquela tela.

## 1.4 Seletor de empresa no cabeçalho

ID BSC-INT-04

### Para que serve

Quando a instalação atende mais de uma empresa do grupo, o cabeçalho traz um seletor de empresa. A empresa escolhida define o contexto das telas: os cadastros e listas passam a mostrar os dados dessa empresa, e os novos registros são criados nela.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia); Responsável por ação/área; Administrador do sistema.

### Passo a passo

1. No cabeçalho, abra o seletor de empresa.
2. Escolha a empresa em que vai trabalhar (por exemplo, **Empresa Exemplo S.A.**).
3. Abra a tela desejada pelo menu lateral; ela passa a refletir a empresa escolhida.
4. Antes de cadastrar um usuário local, confira a empresa no cabeçalho: o usuário passa a trabalhar nela.

### Observações

- Se a empresa escolhida não estiver entre as que você tem acesso, a escolha é limpa e o sistema pede outra.
- Usuário sem nenhuma empresa marcada no cadastro trabalha em todas — lista vazia de empresas não significa “sem acesso”.

## 1.5 Ajuda contextual da tela

ID BSC-INT-05

### Para que serve

Toda tela do Bússola/BSC tem o botão **Ajuda** (o “?” no topo). Ele abre o painel **Ajuda desta tela**, com uma orientação curta: para que a tela serve, o que ela alimenta e a armadilha mais comum. No rodapé do painel, o link **Abrir a documentação completa** leva à seção correspondente deste manual.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia); Responsável por ação/área; Analista de Integração de Dados; Leitor/Auditor; Administrador do sistema.

### Passo a passo

1. Abra a tela sobre a qual tem dúvida.
2. Clique em **Ajuda** (o “?” no topo da tela).
3. Leia a orientação no painel **Ajuda desta tela**.
4. Para o passo a passo completo, clique em **Abrir a documentação completa**.
5. Feche o painel para voltar ao trabalho.

### Observações

- A ajuda da tela é orientação; o procedimento detalhado está neste manual.

## 1.6 Trilha de alterações (quem mudou o quê)

ID BSC-INT-06

### Para que serve

Toda alteração de indicador, meta, apuração e dos demais cadastros do Bússola/BSC fica registrada com autor, data e hora e o estado anterior. A trilha responde à pergunta do controle interno: quem mexeu neste registro, quando e qual era o valor antes.

**Quem usa:** Leitor/Auditor; Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia).

### Passo a passo

1. Abra a ficha do registro (por exemplo, a ficha do indicador **Avanço físico da Ponte do Vale**).
2. Clique em **Histórico**, no topo da ficha.
3. No painel de histórico, veja os eventos do mais recente para o mais antigo, com a ação (**Criado**, **Atualizado**), o autor e a data.
4. Clique numa linha: numa criação aparecem os **Valores iniciais**; numa alteração, os **Campos alterados**, com **Antes** e **Depois**.
5. Para a trilha de uma meta, use o ícone de histórico na linha da meta (**Histórico da meta**).
6. Para uma apuração, use o ícone **Histórico de retificação** e, em cada versão, **Log de alterações**.
7. Para consultar fora da ficha, use **Administração › Trilha de auditoria**, filtrando pela entidade.

### Observações

- Os botões de histórico só aparecem para quem tem a operação **Consultar log de auditoria**. Sem ela não há erro nem cadeado: o botão simplesmente não aparece.
- A trilha diz quem mudou; o valor que vale hoje está na ficha.
- As versões de uma apuração mostram o que o número virou; o **Log de alterações** mostra quem o mudou e quando.

## 1.7 Discussão e compartilhamento entre áreas

ID BSC-INT-07

### Para que serve

O indicador, o plano de ação e a apuração de um período têm um painel de colaboração com duas caixas: **Discussão** e **Compartilhado com**. A explicação de um desvio fica registrada junto do número, e uma área pode chamar outra para agir. O painel fica no fim da ficha do indicador, no fim do plano de ação e no detalhamento de uma célula do Painel de desempenho.

**Quem usa:** Gestor de Desempenho (escritório de estratégia); Diretoria de Estratégia (patrocinador/aprovador); Responsável por ação/área.

### Passo a passo

1. Abra a ficha do indicador, o plano de ação ou o detalhamento de uma célula do **Painel de desempenho**.
2. Na caixa **Discussão**, escreva o comentário (até 4.000 caracteres) e clique em **Comentar**.
3. Para responder a um comentário, use **Responder**; a resposta fica aninhada sob o original.
4. Para remover um comentário seu, use **Remover comentário**.
5. Na caixa **Compartilhado com**, escolha a **Área** (por exemplo, GEOBR — Gerência de Obras), escreva a **Observação** e clique em **Compartilhar**.
6. Quem recebe consulta o item na lista **Compartilhado com a minha área**, no **Painel gerencial**.
7. Para desfazer um compartilhamento, use **Retirar o compartilhamento**.

### Observações

- O primeiro comentário não avisa ninguém, pois ainda não há participantes. Para chamar outra área, compartilhe.
- Comentário removido continua visível, riscado e com o nome de quem removeu; o compartilhamento retirado não deixa rastro.
- Compartilhar aponta, não concede: o colega continua sujeito às próprias permissões.
- No detalhamento de um período, a conversa se prende à versão vigente da apuração; uma retificação abre conversa nova. Para conversas duradouras, use a ficha do indicador ou o plano de ação.
- Item sigiloso não gera aviso de compartilhamento, e a discussão dele só aparece para quem gerencia a estratégia.
- A mesma área não pode ser escolhida duas vezes para o mesmo item.

## 1.8 Seguir um registro

ID BSC-INT-08

### Para que serve

Quem acompanha um indicador, objetivo, plano de ação, ação estratégica ou risco sem ser o responsável pode **seguir** o registro e passar a receber avisos das mudanças e dos comentários feitos por outras pessoas.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia); Responsável por ação/área; Leitor/Auditor.

### Passo a passo

1. Abra a ficha do registro (por exemplo, a ação estratégica **RN-03 Duplicação da Rodovia Norte — trecho 3**).
2. No topo da ficha, clique em **Seguir**. O botão passa a **Seguindo** e mostra quantas pessoas seguem o registro.
3. Para deixar de seguir, clique em **Seguindo**.
4. Para ver tudo o que você segue, abra **Início › Preferências de notificação** e consulte **Itens que sigo**.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/52AVhW9F6iVcTZv0FD-a-_image.png" size="62" isUploading="false" width="620" height="387" darkWidth="620" darkHeight="387" showCaption="false"}

Figura 3 — Preferências de notificação, com a lista de itens seguidos.

### Observações

- Comentar num registro faz você segui-lo automaticamente.
- O aviso diz quem mudou e quais campos mudaram, nunca os valores. Você não é avisado da sua própria ação.
- Os avisos chegam pelos canais definidos em **Gestão por indicadores › Alertas e mensagens**, respeitando as suas preferências.
- O botão **Seguir** só aparece para quem pode abrir o registro. Se perder o acesso, deixa de receber os avisos.
- Registro sigiloso é avisado apenas no sino de quem pode vê-lo, nunca por e-mail, WhatsApp ou canal de área.

## 1.9 Uso no celular e no tablet

ID BSC-INT-09

### Para que serve

As telas do Bússola/BSC funcionam no celular (a partir de 375 px de largura), no tablet e no notebook. A página não rola para os lados; o menu e o botão de sair continuam ao alcance, e grades largas rolam dentro do próprio quadro. Algumas telas mudam de forma no celular: a Mesa de trabalho mostra os grupos como seções que abrem e fecham e a tela de indicadores importados mostra todos os anos em cartões.

**Quem usa:** Responsável por ação/área; Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia).

### Passo a passo

1. Abra o sistema no navegador do celular e entre com o seu login.
2. Toque no ícone do menu para abrir o menu lateral.
3. Escolha a tela, por exemplo **Gestão por indicadores › Mesa de trabalho**.
4. Nas grades largas, deslize o quadro da grade para os lados para ver as demais colunas.
5. Toque no nome de um grupo da Mesa de trabalho para abri-lo ou fechá-lo.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/1qMmPR7FeMR1kJ4NhNqTh_image.png" size="21" isUploading="false" width="208" height="451" darkWidth="208" darkHeight="451" showCaption="false"}

Figura 4 — Mesa de trabalho no celular, com os grupos de prazo recolhíveis.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/_-YDUv6x2jEHOJFd3q5aX_image.png" size="21" isUploading="false" width="208" height="451" darkWidth="208" darkHeight="451" showCaption="false"}

Figura 5 — Mapa estratégico no celular.

### Observações

- Abrir no celular garante o alcance de cada controle; telas muito extensas continuam mais confortáveis no notebook.

[title] 11. Não conformidade e risco
[path] Aplicações/GRCS/

*Como o achado nasce, como ele mexe no risco, e o registro de risco inteiro.*

São **entidades distintas**, e é isso que faz a coisa funcionar.

***

### <font color="#15803D">O achado pode nascer aqui</font>

Até aqui o achado só nascia de regra, de auditoria ou de confronto. O que alguém encontra andando pela operação — *o backup de homologação nunca foi restaurado* — não tinha onde entrar, e o caminho que sobrava era criar uma auditoria só para poder registrar um achado. Ninguém faz isso: anota num caderno.

O botão **Novo achado** cria direto, com título, descrição, severidade e prazo. Duas coisas são opcionais de propósito:

**O alvo.** Ele nasceu obrigatório porque toda NC vinha de auditoria, e auditoria sempre tem alvo. O achado solto nem sempre tem — exigi-lo no ato faz a pessoa escolher um qualquer para o formulário deixar salvar, e alvo errado é pior que alvo nenhum porque entra nos painéis.

**O risco.** Dá para vincular na criação ou deixar solto. Deixar solto é legítimo: nem tudo que se encontra é a materialização de um cenário que alguém já mapeou. O vínculo se faz e se desfaz depois, e vincular duas vezes não cria dois vínculos.

***

### <font color="#15803D">O achado não fica bloqueado</font>

Duas rigidezes saíram, e as duas produziam o mesmo contorno.

A primeira: o fluxo só andava para a frente. Quem colocasse o achado em execução por engano não tinha como voltar à triagem. Agora volta, e recuar não é retrocesso — é o que impede que a correção vire um achado novo.

A segunda: **encerrado e falso positivo eram absorventes**. Fechou, acabou. Quem fechasse por engano criava outro achado igual, o que apaga a história e faz a recorrência contar errado: um achado que reincide três vezes é uma informação sobre o controle; três achados parecidos são três linhas numa lista.

Agora sai por **reabertura**, que exige motivo escrito e fica registrada com quem e quando. Exigir o motivo é o que a distingue de desfazer. Reabrir um encerrado conta como recorrência; reabrir um falso positivo não, porque nunca houve tratamento que tivesse falhado.

A tela oferece só as transições que o motor aceita — a lista vem dele, e não de uma cópia da regra na interface, que envelheceria na direção errada.

***

### <font color="#15803D">O plano de ação, em três formas</font>

As três aparecem na vida real e nenhuma substitui as outras:

**Link externo** para o chamado, o quadro ou o documento onde o trabalho está sendo de fato tocado. Só http e https — um campo de link que aceita qualquer esquema vira um lugar de onde se executa código.

**Anexo** para o que já mora em outro sistema, por referência.

**Detalhamento** em texto rico, para o que não mora em lugar nenhum: o passo a passo, o que ficou combinado, e o print. Ele é **Markdown**, com barra de ferramentas e prévia — e não um editor visual. A plataforma renderiza Markdown montando elementos, sem injetar HTML, então não existe superfície de XSS a defender; um editor visual guardaria HTML, e HTML guardado exige um sanitizador escrito à mão, que é a classe de código em que o erro é silencioso e caro.

**A imagem é enviada de verdade**, e entra como referência — não embutida no texto. Colar um print direto no campo funciona, que é como o print chega. Um print de 800 KB colado em três planos viraria 3 MB de texto dentro de linhas do banco, e o dano aparece no backup e na replicação muito depois de alguém lembrar por quê.

A plataforma guarda imagem (PNG, JPEG, GIF, WebP) e PDF, até 8 MB. SVG fica de fora embora seja imagem: ele é um documento XML que executa script quando servido como imagem. O mesmo arquivo enviado duas vezes reaproveita a linha, reconhecido pelo hash — que também serve para provar que o que se baixa é o que se enviou.

***

### <font color="#15803D">Os quatro agrupadores</font>

A mesma lista responde a quatro perguntas diferentes, e atende mal quando atende só uma:

| **Agrupador**        | **A pergunta que ele responde**                       |
| -------------------- | ----------------------------------------------------- |
| **Prioridade**       | por onde começo? Severidade e prazo                   |
| **Risco**            | o que este risco está me custando? Um grupo por risco |
| **Não conformidade** | a lista corrida, uma linha por achado                 |
| **Sem vínculo**      | o ponto cego: sem risco e sem auditoria               |



No agrupamento por risco, o grupo **sem risco vinculado** aparece mesmo vazio. A ausência dele é informação — quer dizer que tudo está mapeado, e isso merece ser visto em vez de inferido.

***

### <font color="#15803D">Não conformidades — registrar e tratar um achado</font>

A tela **Não conformidades** lista os achados agrupados por **Prioridade**, **Risco**, **Não conformidade** ou **Sem vínculo**, com o filtro **Estado**. Os cartões do topo — **Sem tratamento**, **Prazo vencido**, **Recorrentes**, **Sem vínculo** — recortam a lista ao clicar; clicar de novo tira o recorte.

Para registrar:

1.     Clique em **Novo achado**.

2.     Preencha **Título** (obrigatório), **Descrição**, **Severidade** e **Prazo**.

3.     Em **Plano de ação obrigatório?**, deixe *pela severidade* (alta e crítica exigem) ou escolha sim ou não.

4.     Se quiser, escolha a **Auditoria** (só as abertas) e o **Alvo** dela, e o **Risco relacionado** — ou deixe *deixar solto*. Clique em **Criar**.

Para tratar, clique no achado (**ampliar** abre em tela ampla):

1.     Em **Planos de ação**, clique em **Novo plano**, preencha o **Objetivo** e, se houver, o **Link externo**, o arquivo (**Anexar arquivo**) e o **Detalhamento**. Clique em **Criar plano**.

2.     No cartão do plano, escreva em **Nova ação** e clique em **+**. Plano sem ação não é aprovado.

3.     Aprove pelo botão de visto (**Aprovar plano**). Plano marcado como **Proposta da IA** precisa de **Aceitar** antes.

4.     Conclua cada ação em **concluir**, com a evidência (link, número do chamado).

5.     Em **Estado**, avance o achado pelos botões — em triagem, plano definido, em execução, concluído, eficácia verificada, encerrado. A tela só mostra as transições que o motor aceita. Na lista, o achado tratado aparece como **tratado** (plano) ou **aceito até** a data (aceite de risco).

Para tratar por **aceite de risco** (a outra saída, quando o plano não é obrigatório):

1.     Na seção **Aceite de risco**, clique em **Registrar aceite de risco** — ou em **aceitar o risco…**, em **Estado**, que abre o mesmo formulário.

2.     Escreva a **Justificativa** (obrigatória), o **Controle compensatório**, se houver, e a data em **Válido até** — a partir de amanhã; é a data de revisão do aceite.

3.     Clique em **Registrar aceite**. O achado vai para **risco aceito**, e a seção passa a mostrar o aceite vigente com a autoridade, a data do registro e a validade.

4.     Para tirar o achado da lista de abertos, clique em **encerrar por aceite**, em **Estado**.

A autoridade que responde pelo aceite é **quem está logado**, e só aparece o botão para quem tem a permissão **Não conformidades — aceitar risco**; os demais veem o aviso de que precisam dessa autoridade. Não há campo para escolher outro nome: aceitar em nome de alguém que nunca viu o achado não é aceite. O estado **risco aceito** sozinho não trata nada — sem aceite registrado, o servidor recusa movê-lo para lá. **Renovar o aceite** registra um novo antes do vencimento. Vencida a validade, o achado volta sozinho para **em triagem** e conta como recorrência — inclusive o que foi encerrado por aceite, e nesse caso a volta aparece em **Reaberturas** com o motivo.

Regras: **encerrado** exige plano aprovado ou aceite de risco vigente. Com **Plano de ação obrigatório** marcado, só o plano serve e o botão **risco aceito** não aparece. Encerrado e falso positivo só saem por **Reabrir**, com o campo **Por que reabrir**. **Vincular a um risco** liga o achado a um risco existente, e o ícone ao lado do risco desfaz o vínculo. Os documentos do achado entram por **subir** ou **apontar da base**.

***

### <font color="#15803D">O achado</font>

Nasce da apuração, quando uma regra encontra uma resposta insuficiente. Tem severidade, dono, prazo e um ciclo de vida com bloqueios: não se encerra o que não foi tratado.

**A regra de ouro:** o ciclo não fecha com achado sem plano de ação ou sem aceite de risco formal, temporário e aprovado pela autoridade competente.

***

### <font color="#15803D">O risco</font>

O **inerente** você informa: probabilidade × impacto, numa matriz de 5×5.

O **residual é sempre calculado**, nunca digitado. Ele vem da eficácia dos controles que mitigam o risco, e obedece a quatro regras:

1.     As reduções **compõem**, não somam. Três controles de 50% não zeram o risco; deixam 12,5% dele.

2.     A redução incide sobre a **probabilidade**, não sobre o impacto. Controle preventivo torna o evento menos provável; não torna o vazamento menos grave depois de acontecido.

3.     **Achado aberto sobre um controle anula a eficácia dele** — não desconta, anula. Um controle com não conformidade aberta não está reduzindo risco nenhum.

4.     O piso é 1. Probabilidade zero não existe enquanto o risco estiver aberto.

:::hint{type="info"}
É por isso que o residual não pode ser digitado. Digitado, ele sobrevive ao controle que o justificava, e o risco fica bonito no relatório e falso na realidade.
:::

***

### <font color="#15803D">Como os dois se encontram</font>

•     Achado sobre um controle **já mapeado** a um risco: nenhum risco novo. O controle sai da conta e o residual sobe sozinho.

•     Achado sobre um controle **sem risco mapeado**: nasce um risco de origem *não conformidade*.

•     Achado tratado e encerrado: o controle volta à conta e o residual desce.

•     No encerramento, **a origem decide o destino**. Risco de registro volta ao baseline e permanece — ele existia antes do achado. Risco que nasceu do achado é extinto com ele.

***

### <font color="#15803D">Riscos — registrar, decidir o tratamento e encerrar</font>

Criar, editar e mover pedem a permissão de escrever risco; sem ela, a tela só mostra.

1.     Clique em **Novo risco**. Preencha o **Título**, a **Descrição**, a **Categoria** e a **Probabilidade e impacto** (1 a 5 cada; a nota inerente aparece ao lado). O **Código interno (opcional)** é gerado se ficar em branco. Em **Plano de ação obrigatório?**, *pelo inerente* exige plano a partir de 15. Clique em **Salvar**.

2.     Abra o risco — pelo **Mapa de calor**, pela **Lista**, pelo **Tratamento** ou pelos **Vencidos**. A ficha tem as abas **Resumo**, **Plano de ação**, **Bowtie**, **Revisões** e **Documentos**.

3.     Clique em **Editar** para completar causa, consequência, **Alvo**, **Dono**, **Revisar a cada (dias)**, **Velocidade**, **Fonte** e a **Decisão de tratamento** — **Aceitar**, **Mitigar**, **Transferir** ou **Evitar** —, com a justificativa. Clique em **Salvar**.

4.     Na aba **Plano de ação**, o plano funciona como o da não conformidade: **Novo plano**, ações, aprovação.

5.     Em **Mover para**, escolha **Aberto**, **Em tratamento**, **Monitorado** ou **Encerrado**. **Revisar** marca o risco como revisado hoje e agenda a próxima revisão.

Regras: encerrar exige a decisão de tratamento registrada e, com **Plano de ação obrigatório** marcado, um plano aprovado. Um risco **Aberto** passa por **Em tratamento** antes de **Monitorado**. **Encerrado** não volta: o que reaparecer é risco novo. **Apagar** só vale para risco ainda aberto e sem evento de perda. O residual não se digita — **Recalcular residual** refaz a conta de todos. **Biblioteca** traz riscos típicos: marque os que quer, ajuste o prefixo do código e clique em **Importar**.

***

### <font color="#15803D">O registro de risco</font>

A tela de Riscos tem quatro leituras da mesma carteira, porque cada pergunta pede uma forma diferente:

| **Leitura**   | **A pergunta que ela responde**  |
| ------------- | -------------------------------- |
| Mapa de calor | **onde** os riscos se acumulam   |
| Lista         | quais são, do maior para o menor |
| Tratamento    | em que pé está cada um           |
| Vencidos      | quais deixaram de ser geridos    |



O mapa desenha as células vazias de propósito. Um mapa que só pinta onde há risco vira lista colorida, e some justamente a informação de que o canto mais grave está livre. Clicar numa célula abre os riscos que estão nela, e clicar num deles abre o registro inteiro.

***

### <font color="#15803D">Bowtie</font>

Causas à esquerda, o evento no nó, consequências à direita, e as barreiras em cada caminho. O que ele entrega não é o desenho: é o **caminho sem barreira**. Uma causa sem barreira chega ao evento sem encontrar nada; uma consequência sem barreira acontece inteira.

***

### <font color="#15803D">Decisão de tratamento</font>

Aceitar, mitigar, transferir ou evitar. O número diz o tamanho do risco; a decisão diz o que se resolveu fazer com ele, e sem ela o registro está incompleto — um risco avaliado e não decidido não pode ser encerrado.

***

### <font color="#15803D">Oportunidades</font>

O efeito favorável da incerteza sobre um objetivo. É o mesmo evento que o risco descreve, visto do outro lado, e por isso usa a mesma escala e a mesma matriz. Rejeitar não apaga: o histórico das rejeições é o que ensina a organização a escolher melhor da próxima vez. Toda oportunidade nova recebe a análise da IA do acervo, com os documentos que precisariam mudar para implementá-la.

Para registrar e levar adiante:

1.     Clique em **Registrar**. Preencha **Título**, **Descrição — causa, evento e efeito favorável**, **Classe** (melhoria ou estratégica) e **Fonte**.

2.     Melhoria pede **Unidade** ou **Processo** (os processos vêm da análise de impacto, em Continuidade); estratégica pede o **Objetivo estratégico**. A aba **Análise SWOT** é opcional. Clique em **registrar** — o botão só libera com os obrigatórios preenchidos.

3.     Selecione a oportunidade e clique em **Avaliar**: probabilidade e impactos (1 a 5, a mesma escala do risco), **Benefício mínimo**, **Benefício provável**, **Benefício máximo**, **Confiança da estimativa**, **Custo de captura** e **Prazo (dias)**. Clique em **salvar**. Se o benefício provável passar do teto da faixa de melhoria, a ficha mostra o aviso de que a oportunidade foi **reclassificada como estratégica** e subiu de alçada.

4.     Na seção **Tratamento**, clique em **Definir tratamento** (ou **Editar tratamento**). Escolha a **Estratégia**, escreva a **Justificativa** (obrigatória em *aceitar* e *rejeitar*) e preencha **Métrica de realização**, **Linha de base**, **Valor projetado** e **Data de verificação**. *Explorar*, *melhorar* e *compartilhar* exigem um plano de ação vinculado: busque o plano pelo objetivo ou pelo número do achado/risco e clique nele para vinculá-lo (o **x** desfaz). O plano de ação nasce num achado ou num risco — crie-o lá, se ainda não existir. Clique em **salvar tratamento**.

5.     **Mover para …** avança a oportunidade para a situação seguinte do fluxo.

6.     Em **avaliada** ou **em aprovação**, clique em **Aprovar**. O botão fica desligado, com a lista do que falta, até estratégia, métrica, linha de base e data de verificação estarem definidas. **Rejeitar** (também na triagem) abre o campo **Por que rejeitar**, obrigatório; a rejeitada volta por **Reabrir**, com nova justificativa.

7.     Depois de aprovada, **Mover para em execução** e, se quiser, **em verificação**. Nas duas, **Encerrar** pede o **Valor realizado**, a **Evidência da verificação** (PDF ou imagem) e as **Lições aprendidas**. Clique em **encerrar**; a ficha passa a mostrar o realizado e a taxa de realização.

Aprovar e rejeitar pedem a permissão de aprovar oportunidade; tratar, mover e encerrar, a de escrever. O dono não aprova a própria. Oportunidade encerrada, rejeitada ou cancelada não tem mais o tratamento editado — é história. A matriz **Benefício × esforço** mostra por onde começar: o quadrante de cima à esquerda.

***

### <font color="#15803D">Categorias</font>

A categoria de risco é **cadastro**, não texto livre. Enquanto o risco nascia de alguém digitando, o campo livre passava: quem erra vê o erro. Com a automação abrindo risco sozinha, "Privacidade", "privacidade" e "Priv." viram três categorias para a mesma coisa, e quem monta o painel não tem como saber que são a mesma.

Cada categoria declara os temas que cobre, e é isso que faz a automação oferecer primeiro as que combinam com a pergunta. É sugestão e não trava: um risco de continuidade pode nascer de uma pergunta de acesso.

Para cadastrar, em **Categorias de risco** (pede a permissão de escrever risco):

1.     Clique em **Nova categoria**.

2.     Preencha **Código** e **Nome** (obrigatórios; o código não muda depois), **O que ela abrange** e a **Cor**. Deixe **Ativa** marcada.

3.     Em **Temas que ela cobre**, clique nos temas para marcar ou desmarcar.

4.     Clique em **Criar categoria**. O lápis edita e a lixeira apaga — depois de perguntar, com o foco no **Cancelar** e o **Esc** para desistir. A pergunta avisa quantas automações abrem risco com o nome da categoria; os riscos já classificados guardam o nome como estava.

As categorias **de fábrica** têm o cadeado e são somente leitura: significam o mesmo em todo cliente. Desmarcar **Ativa** tira a categoria das listas sem apagar o que já a usa. No formulário do risco, o campo **Categoria** ainda é texto livre — escreva o nome exatamente como no cadastro.

***

### <font color="#15803D">Biblioteca</font>

Riscos típicos prontos, por categoria, cada um já apontando os controles que o mitigam. Importar cria uma cópia sua, editável — o modelo não entra no mapa de calor, porque modelo não é risco que alguém assumiu.

[title] 🌐Gestão de Pessoas
[path] Início Rápido/

A aplicação de Gestão de Pessoas permite a alteração do perfil do usuário, cadastro de novos usuários, grupos e roles.

Para acessar a aplicação, selecione **Gestão de Pessoas&#x20;**&#x6E;o menu de aplicações.

## Controle Granular de Permissões de Acesso

A plataforma permite uma gestão precisa e detalhada de permissões de acesso, garantindo que cada usuário visualize e interaja apenas com os recursos que são pertinentes ao seu perfil ou função.

Com o controle de permissões granular, é possível:

- Definir quais módulos, funcionalidades ou dados cada usuário pode acessar;
- Restringir ações específicas, como visualizar, editar, excluir ou aprovar conteúdos e processos;
- Criar perfis de acesso personalizados de acordo com a estrutura organizacional ou a necessidade de equipes e projetos específicos.

Essa flexibilidade assegura maior segurança da informação, evita acessos indevidos e contribui para a conformidade com políticas internas e regulamentações vigentes.

## Delegação de Atividades Administrativas por Perfil

A plataforma permite definir, de forma controlada e flexível, quais atividades administrativas cada usuário poderá executar, respeitando os papéis atribuídos e o nível de autonomia desejado. Essa configuração garante que apenas usuários autorizados tenham acesso a recursos críticos de configuração e gestão, mantendo a segurança e a governança do ambiente.

Entre as atividades administrativas que podem ser delegadas estão:

- Configuração e uso de recursos Low-Code/No-Code: definição de fluxos, regras, interfaces e integrações;
- Gestão de domínio e estrutura organizacional: controle de unidades, grupos, permissões e vínculos hierárquicos;
- Manutenção de cadastros gerais: usuários, serviços, categorias, campos customizados, entre outros;
- Outras permissões específicas, conforme diretrizes definidas pela organização ou pelo administrador da solução.

### Gestão de Perfis Administrativos

As permissões administrativas são atribuídas por meio da definição de papéis com privilégio elevado, que podem ser ajustados a partir de necessidades operacionais, modelos de governança ou critérios de segurança. A granularidade no controle dessas permissões assegura que cada administrador tenha acesso apenas às funcionalidades necessárias à sua atuação.

### Segurança e Rastreamento

Todas as ações administrativas realizadas na plataforma são registradas e auditáveis, garantindo transparência, rastreabilidade e conformidade com políticas internas de controle de acesso.


[title] Como Navegar na Interface do Usuário
[path] Início Rápido/

A interface do usuário é a maneira mais fácil deste interagir com aplicativos e informações em uma **instância** <font color="#3b9f0f">**CITSmart**</font>.

Após realizar seu login, clique no ícone de **Aplicações&#x20;**&#x6C;ocalizado no canto superior esquerdo da tela para visualizar as aplicações em sua instância.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/hIC6r-665wY3ook69tycT_image.png" size="12" width="52" height="48" position="center" showCaption="false"}

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/Z9m1TWPZ-YFKSl_ZEyMAF_image.png" size="46" width="345" height="206" position="center" showCaption="false"}

Clique em um aplicação para acessá-la.&#x20;

As aplicações disponíveis em sua instância podem variar de acordo com a instalação do seu ambiente CITSmart. Veja também [Workflow & Service Management](docId\:rsF0XSzzo8x3ArZ3jSTUb) , [Enterprise Low Code](docId\:S5Zm-HGAbuhF820Ze0wXA) , [Enterprise Agility Management](docId\:RZ2PdHG7lVo1yxnLMcBrk) , [AIOPS - inteligência artificial para operações](docId\:YwMV07HcwY7eHITdWdpS7) e [ChatBots e Supervisores Cognitivos (AURA)](docId\:bCn4lErlwnyMMWi0Fhh9v) para mais informações sobre as aplicações CITSmart.

## Navegando em uma aplicação

Após selecionar a aplicação desejada, um novo menu será exibido ao lado dos ícones e aplicações, contendo as respectivas páginas e funcionalidades da aplicação selecionada.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/vpPQ8BN9YpHglyxgjLpyS_image.png" size="32" width="238" height="469" position="center" showCaption="false"}

A imagem acima mostra algumas das páginas disponíveis para a aplicação de **Workflow.&#x20;**&#x43;ada aplicação terá diferentes menus, a depender de sua instalação do CITSmart e seu perfil de acesso. Para navegar entre as páginas, selecione o nome da página desejada, e ela será exibida ao centro da tela do navegador.

Os menus contendo **>** em seu título podem ser expandidos para exibir seus respectivos sub-menus.

Com uma tela já aberta, selecionar outro menu da lista abrirá uma nova guia dentro do CITSmart para eixbir a nova tela:

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/g8qSKtL0iNUWV7T6uBMzY_image.png" size="70" width="455" height="48" position="center" showCaption="false"}

Para alternar entre telas abertas, selecione a aba correspondente. Para fechar uma aba, selecione o ícone de **X&#x20;**&#x61;o lado de seu título.

Por fim, no canto superior direito da tela mais alguns ícones podem ser encontrados:

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/c7wXIyXipoxfCzIXrAqzE_image.png" size="38" width="178" height="51" position="center" showCaption="false"}

- O primeiro ícone pode ser usado para chamados.
- O segundo ícone permite acesso ao assistente virtual.
- O terceiro ícone permite a mudança de idioma.
- O último ícone exibe as informações do usuário logado.

Para mais informações sobre as diferentes telas de cada aplicação, consulte os respectivos documentos da aplicação para encontrar mais detalhes.


[title] Release Notes
[path] /


[title]  9. Análise SWOT
[path] Aplicações/BSC/

A análise SWOT (forças, fraquezas, oportunidades e ameaças) é o diagnóstico de ambiente de cada setor, e é dela que muitos riscos nascem. Forças e fraquezas descrevem o ambiente interno; oportunidades e ameaças, o externo.

O Bússola/BSC segue uma regra de verificação de risco: só fraquezas e ameaças geram riscos. Uma fraqueza pode gerar vários riscos, e um risco pode decorrer de várias fraquezas e ameaças, inclusive de análises diferentes. Forças e oportunidades não originam risco.

A tela fica no menu lateral, grupo Governança e riscos › Análises SWOT. Os exemplos usam a análise "SWOT 2026 — Superintendência de Obras" da Empresa Exemplo S.A., no Ciclo Estratégico 2026 — Empresa Exemplo.

## 9.1 Criar uma análise SWOT

ID BSC-SWT-01

### Para que serve

A análise SWOT registra o diagnóstico de um setor numa data de referência, com responsável técnico e, opcionalmente, ligada a um ciclo estratégico.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador).

### Passo a passo

1\.  Abra Governança e riscos › Análises SWOT e clique em **Nova análise SWOT**.

2\.  Informe o **Título** (por exemplo, SWOT 2026 — Superintendência de Obras) e, se quiser, o **Descritivo**.

3\.  Escolha o **Setor responsável** (por exemplo, SUOBR — Superintendência de Obras) e o **Responsável técnico**, buscando pelo nome.

4\.  Informe a **Data de referência** (vazia vale hoje) e, se quiser, o **Ciclo estratégico**.

5\.  Salve: a análise nasce em **Rascunho** e o quadro abre.



![](https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/q27Y49oNRSVnGEHRixMWv_upload.png)

Figura 87 — Lista de análises SWOT com setor, responsável, ciclo e situação.

### Observações

·        Setor responsável e responsável técnico são obrigatórios.

·        A lista mostra título, setor, responsável técnico, ciclo, data de referência, quantidade de fatores e situação (**Rascunho**, **Publicada** ou **Arquivada**); os filtros cortam por setor, situação e ciclo.

## 9.2 Cadastrar fatores

ID BSC-SWT-02

### Para que serve

Os fatores são os itens de cada quadrante. Cada um recebe um código por quadrante e, opcionalmente, uma relevância para priorização.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador).

### Passo a passo

1\.  Em Governança e riscos › Análises SWOT, abra a análise; o quadro mostra **Forças** e **Fraquezas** em cima, **Oportunidades** e **Ameaças** embaixo.

2\.  No quadrante desejado, clique em **Adicionar**.

3\.  Descreva o fator (por exemplo, "Equipe de fiscalização reduzida" em Fraquezas).

4\.  Se quiser, informe a **Relevância** de 1 (baixa) a 5 (alta) e salve.

5\.  Para corrigir descrição ou relevância, use o lápis do cartão.



![](https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/sMoTXae2ax_TjTtUGJXXG_upload.png)

Figura 88 — Quadro da análise SWOT com os quatro quadrantes e os fatores codificados.

### Observações

·        Códigos por quadrante: FO1, FO2… (forças), FR1… (fraquezas), OP1… (oportunidades) e AM1… (ameaças). O número nunca é reaproveitado: apagado o FR2, o próximo é FR3.

·        O quadrante de um fator não muda: um fator classificado errado é criado de novo no quadrante certo e o antigo é apagado.

·        No celular, os quadrantes aparecem um embaixo do outro.

## 9.3 Ordenar os fatores por prioridade

ID BSC-SWT-03

### Para que serve

A ordem dos fatores dentro de cada quadrante expressa a prioridade e fica gravada para todos.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador).

### Passo a passo

1\.  No quadro da análise, arraste o cartão pela alça para cima ou para baixo dentro do quadrante.

2\.  Alternativamente, use os botões **Subir** e **Descer** do cartão.

3\.  Recarregue o quadro para confirmar que a ordem foi mantida.



![](https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/UYhb2NQBiRjwD5-Q9VkPw_upload.png)

Figura 89 — Cartões de fatores com alça de arrasto e botões Subir/Descer.

### Observações

·        Os botões **Subir** e **Descer** sempre aparecem: no celular o arrasto não funciona, e quem usa teclado ou leitor de tela chega ao mesmo resultado.

·        Se outra pessoa mudar o quadro ao mesmo tempo, a tela recusa a ordem; recarregue a página e ordene de novo.

## 9.4 Publicar a análise

ID BSC-SWT-04

### Para que serve

Publicar indica que o diagnóstico está pronto para uso pela organização.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador).

### Passo a passo

1\.  Revise os fatores e a ordem de cada quadrante.

2\.  No alto do quadro, clique em **Publicar**.

3\.  Confira a situação **Publicada** na lista de análises.



![](https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/xFvL5NxamL6otDQDyuBfp_upload.png)

Figura 90 — Análise com a situação Publicada.

### Observações

·        A publicação fica registrada no histórico da análise.

## 9.5 Criar um risco a partir de uma fraqueza ou ameaça

ID BSC-SWT-05

### Para que serve

Um risco pode nascer diretamente de um fator negativo da análise, já ligado a ele, num passo só.

**Quem usa:** Gestor de Desempenho (escritório de estratégia).

### Passo a passo

1\.  No quadro da análise, localize o cartão de uma fraqueza ou ameaça (por exemplo, FR2 — Equipe de fiscalização reduzida).

2\.  Clique em **Criar risco a partir deste fator**.

3\.  No cadastro do risco, que abre com o título **Novo risco a partir de FR2**, complete título, natureza, matriz, área e responsável.

4\.  Salve: o risco nasce em rascunho, já ligado ao fator.

5\.  Confira que o cartão do fator passa a mostrar **1 risco(s)**.



![](https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/TxElqwgb_cuXK49oua3wA_upload.png)

Figura 91 — Cartão de fraqueza com a ação Criar risco a partir deste fator.

### Observações

·        Só cartões de **Fraquezas** e **Ameaças** têm ações de risco; o sistema recusa ligar risco a força ou oportunidade mesmo por fora da tela.

·        O restante do trabalho com o risco (avaliação, tratamentos, ativação) segue o capítulo de Gestão de riscos.

## 9.6 Acompanhar os riscos e tratamentos de um fator

ID BSC-SWT-06

### Para que serve

O cartão do fator mostra os riscos que ele originou, com a criticidade e o andamento dos tratamentos — o plano de ação daquele fator.

**Quem usa:** Gestor de Desempenho (escritório de estratégia); Diretoria de Estratégia (patrocinador/aprovador); Responsável por ação/área; Leitor/Auditor.

### Passo a passo

1\.  No cartão do fator, clique em **Ver riscos e tratamentos** para expandi-lo.

2\.  Leia, de cada risco: o código (que abre a ficha), o título, a situação, os chips do inerente e do residual planejado, e os tratamentos abertos, vencidos e concluídos.

3\.  Clique no chip **n risco(s)** para abrir o **Registro de riscos** filtrado por aquele fator.

4\.  Na lista filtrada, use **Ver todos os riscos** para remover o filtro.



![](https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/Uso7GH8v6D9mjeGK_pdLz_upload.png)

Figura 92 — Cartão do fator expandido com riscos e tratamentos.

### Observações

·        Risco sigiloso ligado ao fator aparece, para quem não pode vê-lo, só como **+ 1 risco(s) sigiloso(s) que você não pode ver**, sem código nem título.

·        A lista filtrada exibe o aviso **Mostrando só os riscos originados pelo fator SWOT que você abriu**.

## 9.7 Ligar um risco existente a fraquezas e ameaças

ID BSC-SWT-07

### Para que serve

Um risco já registrado pode ser ligado a um ou mais fatores negativos, inclusive de análises diferentes.

**Quem usa:** Gestor de Desempenho (escritório de estratégia).

### Passo a passo

![](https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/IQWI2ahypINGa3QGXeDgl_upload.png)

1\.  Em Governança e riscos › Registro de riscos, abra a ficha do risco e vá ao cartão **Origem na análise SWOT**.

2\.  Em **Ligar a uma fraqueza ou ameaça**, busque o fator pela descrição ou pelo título da análise.

3\.  Clique em **Ligar**: o fator aparece com código, quadrante, descrição e título da análise (que abre o quadro).

4\.  Repita para ligar a fatores de outras análises, se for o caso.

5\.  Para desligar, clique na lixeira do fator.



Figura 93 — Cartão Origem na análise SWOT na ficha do risco.

### Observações

·        A busca oferece só fraquezas e ameaças de análises não arquivadas.

·        Ligar o mesmo risco ao mesmo fator duas vezes é recusado.

·        Inclusões e remoções ficam no histórico do risco, não no da análise.

## 9.8 Apagar um fator

ID BSC-SWT-08

### Para que serve

Fatores podem ser apagados enquanto não tiverem originado riscos.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador).

### Passo a passo

1\.  No quadro da análise, clique na lixeira do cartão do fator.

2\.  Se o sistema recusar informando quantos riscos estão ligados, desligue os riscos na ficha de cada um (cartão **Origem na análise SWOT**).

3\.  Repita a exclusão do fator.

![](https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/4UqBYORnW5HYHJMbVjpfJ_upload.png)

### Observações

·        A contagem de riscos ligados inclui os sigilosos.

·        O código do fator apagado não é reaproveitado.

## 9.9 Arquivar a análise

ID BSC-SWT-09

### Para que serve

Arquivar encerra a análise e a deixa somente leitura, preservando a origem dos riscos já ligados.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador).

### Passo a passo

1\.  Abra a análise.

2\.  No alto do quadro, clique em **Arquivar** e confirme.

3\.  Confira a situação **Arquivada** na lista (marque o filtro de situação, se necessário).



Figura 94 — Lista com análises arquivadas.

### Observações

·        Numa análise arquivada nenhum fator é criado, alterado, reordenado ou apagado, e nenhum risco novo é ligado aos fatores dela.

·        Os riscos já ligados continuam mostrando o fator de origem na ficha.

## 9.10 Histórico da análise

ID BSC-SWT-10

### Para que serve

O histórico registra todas as mudanças da análise e dos fatores, com o antes e o depois.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Leitor/Auditor.

### Passo a passo

1\.  Abra a análise.

2\.  Selecione a aba **Histórico**.

3\.  Leia quem criou, editou o cabeçalho, cadastrou, alterou, reordenou ou apagou fatores, publicou e arquivou.

### Observações

·        A ligação de um risco a um fator aparece no histórico do risco, não no da análise.

## 9.11 Perfis de acesso às análises SWOT

ID BSC-SWT-11

### Para que serve

Os perfis separam quem mantém o diagnóstico de quem gera riscos a partir dele.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador); Gestor de Desempenho (escritório de estratégia); Responsável por ação/área; Leitor/Auditor; Administrador do sistema.

### Passo a passo

1\.  Identifique o perfil da pessoa nas observações abaixo.

[title]  10. Processos e cadeia de valor
[path] Aplicações/BSC/

A gestão do portfólio de processos se organiza pela cadeia de valor, que deve ficar atualizada sempre que um processo é criado, excluído ou renomeado. Os processos são organizados em níveis: no topo, a cadeia de valor, dividida em tipos (gestão, finalísticos e suporte); abaixo, os macroprocessos; abaixo, os processos. O detalhe de cada processo — atividades, tarefas, raias — vive no desenho feito numa ferramenta de modelagem (arquivos .bpm ou no padrão aberto .bpmn).

O Bússola/BSC não desenha processos: guarda o catálogo e as versões de cada processo, com o arquivo de modelagem anexado. Cada versão nasce em elaboração, vai para revisão e é validada por outra pessoa, que tem essa atribuição. Ao validar uma versão nova, a anterior passa a substituída: há sempre uma única versão vigente. Os processos não dependem de ciclo estratégico: o catálogo é da empresa e continua o mesmo quando um novo ciclo começa.

As telas ficam no menu lateral, grupo Governança e riscos: Processos, Tipos de processo e macroprocessos e Cadeia de valor — o infográfico calculado do próprio catálogo, sem passo de publicação.

## 10.1 Tipos de processo

ID BSC-PRO-01

### Para que serve

Os tipos são as faixas da cadeia de valor, na ordem em que são desenhadas. O produto já vem com Gestão, Finalístico (desenhado em sequência) e Suporte, que a empresa pode renomear, colorir e reordenar.

**Quem usa:** Gestor de Desempenho (escritório de estratégia).

### Passo a passo

1. Abra Governança e riscos › Tipos de processo e macroprocessos e selecione a aba **Tipos**.
2. Use as setas da coluna **Ordem** para subir ou descer um tipo; a nova ordem vale na hora.
3. Para dar cor, clique no lápis do tipo, marque **Usar cor própria** e escolha a cor.
4. Marque **Desenhar em sequência** no tipo cujos macroprocessos formam uma corrente lida da esquerda para a direita (em geral, o finalístico).
5. Para criar, clique em **Novo tipo de processo** e informe código curto e único (em maiúsculas) e nome.
6. Use o botão de liga/desliga para inativar um tipo.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/mNmvSnQt8c8G9tozM2Q68_image.png" size="62" isUploading="false" width="620" height="387" showCaption="false"}

Figura 89 — Tipos de processo e macroprocessos: aba Tipos com ordem, cor e desenho em sequência.

### Observações

- Sem cor própria, a faixa usa a cor padrão da posição (a lista mostra "(cor padrão)"). A cor é sempre hexadecimal de seis dígitos.
- Tipo com macroprocessos ativos não é inativado: a tela informa quantos são.
- A tela é do escritório de processos; os demais perfis não a veem no menu.

## 10.2 Macroprocessos

ID BSC-PRO-02

### Para que serve

Os macroprocessos agrupam os processos dentro de cada tipo e aparecem como cartões na cadeia de valor.

**Quem usa:** Gestor de Desempenho (escritório de estratégia).

### Passo a passo

1. Em Governança e riscos › Tipos de processo e macroprocessos, selecione a aba **Macroprocessos** e filtre pelo tipo.
2. Clique em **Novo macroprocesso**, escolha o **Tipo de processo** e informe código e nome (por exemplo, Gerir obras rodoviárias, no tipo Finalístico).
3. Se quiser, informe descrição, **Setor** e **Responsável**.
4. Use as setas para ordenar o macroprocesso entre os do mesmo tipo.
5. Use o botão de liga/desliga para inativar.
6. Clique no relógio da linha para ver o histórico do tipo ou do macroprocesso.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/mNmvSnQt8c8G9tozM2Q68_image.png" size="62" isUploading="false" width="620" height="387" showCaption="false"}

Figura 90 — Aba Macroprocessos com a coluna Processos ativos.

### Observações

- Só tipos ativos são oferecidos.
- Macroprocesso com processos ativos não é inativado; a coluna **Processos ativos** mostra quantos são.
- Setor e responsável são opcionais no macroprocesso.

## 10.3 Cadastrar um processo

ID BSC-PRO-03

### Para que serve

O processo é a unidade do catálogo que recebe versões e arquivos de modelagem. Todo processo nasce com a versão 1 em elaboração.

**Quem usa:** Gestor de Desempenho (escritório de estratégia).

### Passo a passo

1. Abra Governança e riscos › Processos e clique em **Novo processo**.
2. Escolha o **Macroprocesso** (só os ativos).
3. Informe código (único), nome e objetivo (por exemplo, Fiscalizar contrato de obra, no macroprocesso Gerir obras rodoviárias).
4. Escolha o **Setor** (por exemplo, GEOBR — Gerência de Obras) e o **Responsável**.
5. Salve: a ficha abre com o caminho tipo › macroprocesso, os dados do processo e a versão 1 em elaboração.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/MKmF2nvfhKoNm5PvOao53_image.png" size="62" isUploading="false" width="620" height="387" showCaption="false"}

Figura 91 — Lista de processos com tipo, macroprocesso, setor, situação e versão vigente.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/l_hUTMDnq_iB-03Qw37Ox_image.png" size="62" isUploading="false" width="620" height="387" showCaption="false"}

Figura 92 — Ficha do processo com as versões.

### Observações

- No processo, setor e responsável são obrigatórios.
- A lista mostra tipo (com a cor), macroprocesso, setor, responsável, situação da versão mais recente (com o número) e versão vigente — "nenhuma validada ainda" enquanto não houver validação.
- Filtros: tipo, macroprocesso, setor, situação, ativos/inativos e texto (código ou nome); por padrão, só os ativos.

## 10.4 Editar, inativar e consultar o histórico do processo

ID BSC-PRO-04

### Para que serve

O cadastro do processo pode ser ajustado a qualquer momento. Inativar é a forma de excluir um processo sem perder sua história.

**Quem usa:** Gestor de Desempenho (escritório de estratégia); Leitor/Auditor.

### Passo a passo

1. Em Governança e riscos › Processos, abra a ficha do processo.
2. Clique em **Editar** para mudar os dados e salve.
3. Para excluir, clique em **Inativar**.
4. Clique em **Histórico** no cabeçalho para ver as mudanças do cadastro.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/l_hUTMDnq_iB-03Qw37Ox_image.png" size="62" isUploading="false" width="620" height="387" showCaption="false"}

Figura 93 — Cabeçalho da ficha do processo com Editar, Inativar e Histórico.

### Observações

- Processo inativo sai da cadeia de valor e dos seletores, mas continua consultável com versões e histórico.
- Inativar é permitido mesmo com uma versão em revisão, que fica como está.
- Cada versão tem histórico próprio.

## 10.5 Anexar o arquivo de modelagem e descrever a mudança

ID BSC-PRO-05

### Para que serve

Cada versão guarda o arquivo de modelagem do processo e, opcionalmente, o PDF publicado pela ferramenta. O arquivo mais recente é o que o validador vai revisar.

**Quem usa:** Gestor de Desempenho (escritório de estratégia).

### Passo a passo

1. Na ficha do processo, seção **Versões**, localize a versão em elaboração.
2. Em **Arquivos da versão**, clique em **Enviar arquivo** e escolha o .bpm ou .bpmn exportado da ferramenta de modelagem.
3. Se quiser, anexe também o PDF de documentação.
4. No campo **O que mudou nesta versão**, descreva a mudança e clique em **Salvar a descrição**.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/l_hUTMDnq_iB-03Qw37Ox_image.png" size="62" isUploading="false" width="620" height="387" showCaption="false"}

Figura 94 — Versão em elaboração com os arquivos anexados e a marca Arquivo de modelagem.

### Observações

- Só são aceitos .bpmn, .bpm e .pdf; outro tipo é recusado com a lista dos aceitos. O limite de tamanho é o geral dos anexos (50 MB).
- O arquivo de modelagem mais recente recebe a marca **Arquivo de modelagem**.
- Os arquivos são sempre baixados e abertos na ferramenta de modelagem: o Bússola/BSC não abre nem interpreta o desenho.

## 10.6 Enviar a versão para revisão

ID BSC-PRO-06

### Para que serve

Enviar para revisão congela os arquivos da versão e a coloca na fila do validador.

**Quem usa:** Gestor de Desempenho (escritório de estratégia).

### Passo a passo

1. Confirme que a versão tem um arquivo .bpmn ou .bpm anexado.
2. Clique em **Enviar para revisão**.
3. Confira a situação **Em revisão** e o registro do envio na linha do tempo da versão.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/l_hUTMDnq_iB-03Qw37Ox_image.png" size="62" isUploading="false" width="620" height="387" showCaption="false"}

Figura 95 — Versão Em revisão com a linha do tempo.

### Observações

- Sem arquivo de modelagem, o botão não fica disponível e a tela avisa; o PDF sozinho não basta.
- Em revisão, os arquivos da versão não mudam até ela ser devolvida.

## 10.7 Validar ou devolver uma versão

ID BSC-PRO-07

### Para que serve

Quem tem a atribuição de validar revisa o arquivo de modelagem e decide: validar torna a versão vigente; devolver a envia de volta para elaboração com o motivo.

**Quem usa:** Diretoria de Estratégia (patrocinador/aprovador).

### Passo a passo

1. Na ficha do processo, abra a versão **Em revisão**.
2. Baixe o arquivo de modelagem e revise-o na ferramenta de modelagem.
3. Para aprovar, clique em **Validar**: a versão passa a **Validada** e **Vigente**, e a validada anterior passa a **Substituída** na mesma operação.
4. Para recusar, clique em **Devolver**, informe o motivo e confirme em **Devolver para elaboração**.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/l_hUTMDnq_iB-03Qw37Ox_image.png" size="62" isUploading="false" width="620" height="387" showCaption="false"}

Figura 96 — Versão em revisão com os botões Validar e Devolver.

### Observações

- Quem enviou a versão para revisão não pode validá-la, mesmo tendo as duas permissões.
- O motivo da devolução é obrigatório e aparece na linha do tempo; o gestor corrige o arquivo e envia de novo.
- Versão validada ou substituída não muda mais, nem os arquivos.

## 10.8 Abrir uma nova versão e consultar o histórico da versão

ID BSC-PRO-08

### Para que serve

Para mudar um processo já validado, abre-se uma nova versão; a vigente continua valendo até a nova ser validada.

**Quem usa:** Gestor de Desempenho (escritório de estratégia); Leitor/Auditor.

### Passo a passo

1. Na ficha do processo, clique em **Nova versão**: nasce a versão seguinte (v2, v3…) em elaboração.
2. Anexe o novo arquivo, descreva a mudança e envie para revisão, como na versão 1.
3. Clique no relógio do cartão da versão para ver o histórico: criação, envio, devolução, validação, substituição e cada arquivo anexado ou removido.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/l_hUTMDnq_iB-03Qw37Ox_image.png" size="62" isUploading="false" width="620" height="387" showCaption="false"}

Figura 97 — Seção Versões com a versão vigente e a nova em elaboração.

### Observações

- Só existe uma versão em elaboração ou revisão por vez; enquanto houver uma, o botão não aparece e a tela explica por quê.
- As versões aparecem da mais recente para a mais antiga, com a situação e a linha do tempo.

## 10.9 Ler a cadeia de valor

ID BSC-PRO-09

### Para que serve

A cadeia de valor é calculada do catálogo toda vez que a tela abre: não é desenhada à mão nem publicada. Qualquer mudança em tipos, macroprocessos ou processos aparece na próxima abertura.

**Quem usa:** Gestor de Desempenho (escritório de estratégia); Diretoria de Estratégia (patrocinador/aprovador); Responsável por ação/área; Leitor/Auditor.

### Passo a passo

1. Abra Governança e riscos › Cadeia de valor.
2. Leia uma faixa por tipo de processo, na ordem e na cor do tipo, com o nome e o total de processos.
3. Dentro de cada faixa, leia os cartões dos macroprocessos com "n processos": setas encadeadas no tipo desenhado em sequência, blocos nos demais.
4. Passe o cursor sobre um cartão (ou chegue a ele com Tab) para ver quantos processos estão em elaboração, em revisão e validados.
5. Confira a data de referência da leitura no cabeçalho.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/53uOqfisbnorJnqrvlj_l_image.png" size="62" isUploading="false" width="620" height="387" showCaption="false"}

Figura 98 — Cadeia de valor com faixas por tipo e cartões de macroprocessos.

### Observações

- Só entram itens ativos: processo, macroprocesso ou tipo inativo não aparece nem conta.
- A situação é sempre a da versão mais recente de cada processo.
- Catálogo sem macroprocessos mostra as faixas vazias e um aviso; quem mantém o catálogo vê o atalho **Cadastrar tipos e macroprocessos**.

## 10.10 Navegar da cadeia de valor aos processos

ID BSC-PRO-10

### Para que serve

Da cadeia é possível descer ao macroprocesso, ver seus processos e baixar o arquivo de modelagem vigente.

**Quem usa:** Gestor de Desempenho (escritório de estratégia); Diretoria de Estratégia (patrocinador/aprovador); Responsável por ação/área; Leitor/Auditor.

### Passo a passo

1. Em Governança e riscos › Cadeia de valor, clique no cartão de um macroprocesso (ou tecle Enter sobre ele).
2. Leia a lista dos processos: código, nome, setor, responsável, situação e versão vigente.
3. Clique em **Baixar o arquivo de modelagem vigente** para obter o desenho atual.
4. Clique no nome de um processo para abrir a ficha dele.
5. Use **Lista** para ver a cadeia como texto e **Desenho** para voltar ao infográfico.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/53uOqfisbnorJnqrvlj_l_image.png" size="62" isUploading="false" width="620" height="387" showCaption="false"}

Figura 99 — Lista de processos de um macroprocesso aberta a partir da cadeia.

### Observações

- No celular a cadeia aparece sempre em lista, sem rolagem lateral.
- A cadeia pode mostrar número menor que a lista de processos, porque conta só itens ativos.

## 10.11 Exportar a cadeia de valor

ID BSC-PRO-11

### Para que serve

A cadeia pode ser exportada como imagem, para publicação institucional, ou impressa e salva em PDF.

**Quem usa:** Gestor de Desempenho (escritório de estratégia); Diretoria de Estratégia (patrocinador/aprovador); Responsável por ação/área; Leitor/Auditor.

### Passo a passo

1. Em Governança e riscos › Cadeia de valor, clique em **Baixar imagem (PNG)**; o arquivo traz título, data de referência e legenda dos tipos.
2. Para PDF, clique em **Imprimir ou salvar em PDF**; a impressão do navegador abre só com a cadeia, em paisagem.
3. No destino da impressão, escolha **Salvar como PDF**.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/53uOqfisbnorJnqrvlj_l_image.png" size="62" isUploading="false" width="620" height="387" showCaption="false"}

Figura 100 — Botões de exportação da cadeia de valor.

### Observações

- O nome do PNG inclui a data de referência (cadeia-de-valor-AAAA-MM-DD.png).
- Em alguns navegadores, escolha a orientação paisagem no próprio diálogo de impressão.
- Se o navegador não conseguir gerar a imagem (cadeias muito grandes em aparelhos antigos), use a impressão em PDF.

## 10.12 Perfis de acesso a processos

ID BSC-PRO-12

### Para que serve

Os perfis separam quem elabora o catálogo e as versões de quem as valida.

**Quem usa:** Gestor de Desempenho (escritório de estratégia); Diretoria de Estratégia (patrocinador/aprovador); Responsável por ação/área; Leitor/Auditor; Administrador do sistema.

### Passo a passo

1. Identifique o perfil da pessoa nas observações abaixo.
2. Se faltar acesso, peça ao **Administrador do sistema** a permissão correspondente (manter o catálogo de processos ou validar versões).
3. Garanta que quem elabora e quem valida sejam pessoas diferentes.

### Observações

- Gestor de Desempenho (escritório de processos): cria, edita, reordena e inativa tipos, macroprocessos e processos; abre versões, anexa e remove arquivos, descreve a mudança e envia para revisão.
- Diretoria de Estratégia (validador): consulta o catálogo; valida e devolve versões em revisão; baixa os arquivos.
- Responsável por ação/área e Leitor/Auditor: consultam e baixam os arquivos.
- Todos os perfis com acesso consultam, navegam e exportam a cadeia de valor.

[title] 8. Responder uma auditoria
[path] Aplicações/GRCS/

*O lado de quem recebe a pergunta — onde ela aparece, quem responde e o que acontece depois.*

Este capítulo é o outro lado de Auditoria, ondas e respostas. Lá o ponto de partida é o ciclo e a visão é de quem conduz; aqui é a pessoa que recebeu a pergunta.

***

### <font color="#15803D">Quem responde</font>

Quem entra por convite nasce **Colaborador** e já responde no **/responder** as perguntas despachadas para a área ou a equipe dele. O Gestor o promove a **Analista** (em **Auditoria ▸ Colaboradores e analistas**) quando ele precisa também revisar, tratar não conformidade ou escrever documento. O **Solicitante** — quem entra pelo login da empresa sem convite — não responde auditoria. No /responder também está a **Análise de aderência**, a mesma do portal: compare o documento da área com os requisitos de uma norma sem sair dali.

Para entrar no /responder, use o login e a senha da plataforma ou, quando a organização configurou o próprio provedor de identidade, o botão **Entrar pelo provedor da organização**. É o provedor do tenant daquele endereço, o mesmo da plataforma e do portal, e a volta dele traz você de novo ao /responder (*Integração com o diretório*).

***

### <font color="#15803D">Onde a pergunta aparece</font>

Em **Responder auditoria**, no menu. Ele abre o site *Responder a auditoria*, e a lista se chama *Perguntas para Área*. Você não precisa saber qual auditoria foi aberta, nem procurar por ela: quem responde não escolhe o ciclo em que trabalha, trabalha no que lhe foi despachado.

A pergunta é sua por três caminhos, e você não precisa distinguir entre eles:

•     a pergunta **despachada ao seu grupo** numa onda;

•     a pergunta **delegada a você** em nome próprio, quando o contexto é seu e não da equipe;

•     a pergunta de um ciclo lançado que **já é da sua área pelo alvo avaliado**.

Os três dizem **de quem** é a pergunta. **Quando** ela pode ser respondida é outra regra: a lista só mostra para responder a pergunta que está numa onda **disparada**. Ciclo lançado sem onda disparada ainda não aparece aqui.

:::hint{type="info"}
**O recorte é do servidor, não da tela.** As perguntas de uma área não saem daqui para quem não pertence a ela. Não há lista completa escondida por trás de um filtro.
:::

***

### <font color="#15803D">Quem vê a fila inteira</font>

Quem tem auditoria\:abrir — normalmente quem conduz o ciclo. A pergunta que essa pessoa precisa responder é "onde isto parou", e ela não tem resposta olhando uma área de cada vez.

Não existe perfil de auditor entre os de fábrica, e não precisa existir: crie um em **Administração › Perfis de acesso** com auditoria\:abrir e ele enxerga a fila inteira no mesmo instante, sem deploy. A autorização verifica permissão, nunca o nome do perfil.

***

### <font color="#15803D">Quem responde cada pergunta</font>

A onda cai num **grupo**, não numa pessoa — o despacho é por torre, e quem responde por backup é a equipe de infraestrutura, não um nome. Dentro da área, alguém reparte.

Quem tem auditoria\:distribuir define o responsável de cada pergunta, e o limite é a própria área: não se distribui trabalho para fora de casa. A verificação é feita contra o banco e não contra a lista que a tela ofereceu — uma tela que oferece as pessoas certas continua sendo uma tela, e o pedido chega por HTTP.

Enquanto ninguém assume, a pergunta aparece com o grupo e a marca **sem responsável**. É deliberado: uma pilha sem dono é visível, e a área precisa saber de quem cobrar.

***

### <font color="#15803D">Responder, passo a passo</font>

1.     Em **Responder auditoria**, os atalhos do alto recortam a lista: **Esperando resposta**, **Fora do prazo**, **Comigo** e **Devolvidas** (para quem revisa, **Para revisar** no lugar do último). **Procurar nas perguntas** acha pela pergunta, código, auditoria ou alvo.

2.     Na seção **Perguntas para responder**, as perguntas vêm agrupadas por auditoria. Clique numa para abri-la.

3.     Escolha a **Situação declarada** — ou preencha a **Resposta**, conforme o tipo — e escreva a **Descrição — o que sustenta essa situação**.

4.     Em **Evidências**: **subir** um arquivo (até 25 MB) ou um link para onde ele já vive, ou **apontar da base** um documento que já existe.

5.     Se quiser, **Pré-validar** mostra o que o auditor provavelmente vai recomendar. É opcional e não fica registrado.

6.     **Responder** — o botão só se habilita com a situação escolhida.

Recebeu no lugar errado? **Encaminhar para outra equipe** manda a pergunta, com o mesmo prazo, para uma equipe da área dela ou de uma área de que você faz parte. Quem tem auditoria\:distribuir vê também **Definir responsável** / **Trocar responsável**, limitado às pessoas da área. A caixa **só as que estão comigo** mostra o que é seu.

Pergunta marcada como exigindo evidência **não é aprovada sem anexo**, então anexar depois é retrabalho garantido. Responder não fecha nada: a resposta fica **respondida**, esperando revisão.

**Revisar.** Quem tem auditoria\:revisar tem a seção **Para revisar**: leia o valor, as evidências e a recomendação da IA, escreva o motivo e clique **Aprovar** ou **Devolver**. Devolver exige motivo — sem ele, o primeiro clique traz o *o que fazer* da recomendação para o campo, para você ler e editar. A sua própria resposta nunca aparece para você revisar.

***

### <font color="#15803D">O que acontece depois</font>

:::BlockQuote
pendente → respondida → aprovada        entra no score
&#x20;                    ↘ devolvida → pendente de novo
:::

**Quem responde não revisa.** A segregação está no banco, não só na tela: não há caminho — nem por API — que a contorne. É o que separa uma auditoria de um formulário.

Quando o revisor **devolve**, a pergunta volta para a sua fila com o motivo registrado. Devolver é o caminho normal, e não uma punição: a alternativa seria o revisor corrigir a resposta de outra pessoa, e aí a assinatura deixaria de valer.

**Só resposta aprovada entra no score.** Uma auditoria com tudo respondido e nada revisado tem score zero — e está certo.

***

### <font color="#15803D">Prazo</font>

Cada pergunta mostra o prazo que veio da atribuição, da onda ou do ciclo, nessa ordem. O que passou do prazo aparece em vermelho, e o contador no alto diz quantas são — a fila ordena pelo prazo, então o atrasado sobe sozinho.

***

### <font color="#15803D">Quando a fila aparece vazia</font>

Três causas, em ordem de frequência:

1.     **Nada foi despachado ainda.** O ciclo pode estar em rascunho — rascunho não aceita resposta —, ou lançado sem nenhuma onda disparada. Quem conduz o ciclo dispara em **Ondas de disparo**, na tela da auditoria, ou em **Painel do framework ▸ Montar onda**.

2.     **O alvo avaliado não tem área.** É a causa menos óbvia. O alvo do ciclo precisa apontar para a área ou o grupo correspondente em **Alvos e dimensões**, no campo *Representa o cadastro de*. Sem isso a pergunta não sabe de que área é, e só quem enxerga a fila inteira a encontra.

3.     **Você não está em nenhum grupo.** O vínculo é feito em **Administração › Usuários**, e um usuário pode pertencer a quantos grupos forem necessários.

[title] 10. Pré-auditoria
[path] Aplicações/GRCS/

*O levantamento prévio, e a comparação com o que o ciclo oficial apurou.*

O ciclo oficial não é o primeiro contato com o assunto. Antes dele existe o levantamento: as mesmas perguntas, feitas sem peso formal, para saber **onde se está** antes de registrar onde se está.

***

### <font color="#15803D">É o mesmo registro, de propósito</font>

Pré-auditoria e auditoria têm a mesma estrutura, as mesmas perguntas, as mesmas ondas de despacho e a mesma revisão. A diferença é a natureza declarada na abertura, e o que ela significa:

|                | **Pré-auditoria** | **Auditoria**        |
| -------------- | ----------------- | -------------------- |
| Para quê       | levantar          | apurar               |
| Peso formal    | nenhum            | é o registro oficial |
| Gera indicador | não               | sim                  |



Ter as duas como telas separadas tornaria impossível a única pergunta que justifica existirem as duas: **o que a pré dizia, e o que a oficial apurou**.

***

### <font color="#15803D">Abrir uma pré e lançá-la como auditoria</font>

1.     Em **Auditorias** → **Abrir auditoria**, escolha a natureza **Pré-auditoria** e siga como numa auditoria comum → **Abrir pré-auditoria**. Na lista, o ciclo leva o selo *pré*.

2.     Lance, despache e responda a pré como qualquer ciclo.

3.     Com a pré em andamento, o detalhe dela mostra **Lançar como auditoria**. Preencha **Código**, **Nome** e **Prazo** e decida a caixa **Copiar as respostas da pré-auditoria** → **Lançar auditoria**.

O ciclo oficial nasce com **as mesmas perguntas** da pré, copiadas dela e não buscadas de novo no catálogo, para que a comparação fale da mesma pergunta mesmo que o catálogo mude. Copiadas, as respostas entram como **respondidas, e não como aprovadas**: a revisão por outra pessoa continua sendo a porta de entrada do score. Sem copiar, a auditoria nasce em branco e a pré fica só como termo de comparação.

***

### <font color="#15803D">Como se ligam</font>

Ao abrir uma auditoria, o campo *"Veio de uma pré-auditoria?"* oferece as pré-auditorias que ainda não geraram ciclo oficial — ele só aparece com a natureza **Auditoria** e quando existe alguma pré. Uma pré alimenta **uma** auditoria: duas tornariam ambígua a frase "o que a pré dizia".

***

### <font color="#15803D">A comparação</font>

Vinculadas, a tela da auditoria ganha o bloco **Pré-auditoria × auditoria** — clique para abrir; a caixa **Mostrar só o que mudou** vem marcada —, com:

•     quantas perguntas **melhoraram**, **pioraram** e ficaram **iguais**;

•     as que existem **só na auditoria** — normal quando o ciclo oficial é mais amplo que o levantamento;

•     as que ficaram **só na pré** — normalmente um sinal de que algo saiu de escopo sem que se percebesse.

O cruzamento é **pela pergunta**, e não pela posição: os dois ciclos podem ter origens diferentes. Pergunta que só existe de um lado aparece assim mesmo, contada à parte — escondê-la faria a comparação parecer completa quando não é.

***

### <font color="#15803D">Uma auditoria pode nascer de várias origens</font>

O campo **Avaliar contra** abre uma janela com todo o catálogo. Marque quantas quiser — normas, **Meus temas** e **Meus frameworks**, juntos; *Filtrar por nome ou código…* ajuda a achar — e clique **Confirmar**.

A pergunta pedida por duas normas é materializada **uma vez**. Duplicá-la faria quem responde responder duas vezes o mesmo, e o score contaria o mesmo controle em dobro. A janela mostra a soma das perguntas como um **teto**, não como o total — o número final costuma ser menor, porque o acervo é compartilhado entre as normas.

[title] 12. Continuidade e monitoramento
[path] Aplicações/GRCS/

*O que não pode parar, o que avisa antes, e o que aconteceu mesmo assim.*

Três leituras que confrontam o risco com a realidade. A matriz diz o que se teme; estas dizem o que a organização não pode perder, o que está se deteriorando agora, e o que já aconteceu.

***

### <font color="#15803D">Continuidade — registrar processo, indicador e evento de perda</font>

A tela tem três abas: **Análise de impacto**, **Indicadores (KRI)** e **Eventos de perda**. Registrar pede a permissão de escrever risco.

**Processo e análise de impacto**

1.     Clique em **Novo processo**, preencha **Código**, **Processo** e, se houver, o **Alvo**, e clique em **Criar processo**. A janela passa a ser a do processo criado — o aviso **Processo … criado** aparece no topo e o botão vira **Salvar processo**.

2.     Na mesma janela (ou, depois, abrindo o cartão do processo na lista), em **Tempos e impacto**, preencha **MTPD (h)**, **RTO (h)**, **RPO (h)**, **Impacto por hora (R$)** e **Mínimo operacional**, e clique em **Salvar análise**.

3.     Em **Dependências**, escolha o tipo, escreva **De que depende** e a **Alternativa, se houver**, e clique em **+**. As dependências só se listam depois de salvar a análise.

**Indicador:** **Novo indicador** → **Código**, **Nome**, **Unidade**, **Limite de atenção**, **Limite crítico**, **Direção** (**Piora subindo** ou **Piora caindo**), **Medir a cada (dias)** e **Risco associado** → **Criar indicador**. Para lançar um valor, **Registrar medição** → **Valor** e **Referência** → **Registrar**.

**Evento de perda:** **Registrar evento** → **Código**, **O que aconteceu**, **Ocorrido em**, **Detectado em**, **Severidade**, **Perda estimada**, **Perda efetiva**, **Risco relacionado**, **Causa raiz** e **Lição** → **Registrar**.

A análise só conta como completa com MTPD, RTO, RPO e ao menos uma dependência. A lixeira do processo (no topo da janela dele), da medição e do evento, e o **×** da dependência, perguntam antes de apagar — **Excluir processo “…”?**, **Excluir dependência “…”?**, e assim por diante —, dizendo o que sai junto. O foco nasce em **Cancelar**; **Excluir** confirma. Excluir o processo leva a análise e as dependências dele; as oportunidades que o citavam continuam, sem ele. Para corrigir uma medição, registre de novo a mesma data de referência em vez de apagar.

***

### <font color="#15803D">Análise de impacto</font>

Cada processo declara três tempos, e a ordem entre eles não é opinião:

| **Sigla** | **O que é**                                              | **A regra**                         |
| --------- | -------------------------------------------------------- | ----------------------------------- |
| **MTPD**  | o teto: além dele a interrupção deixa de ser recuperável | o maior dos três                    |
| **RTO**   | a meta de retomada                                       | tem de caber dentro do MTPD         |
| **RPO**   | quanto dado se aceita perder                             | problema de backup, não de retomada |



A plataforma recusa RTO maior que MTPD. Não é validação de formulário: um plano que promete retomar depois do ponto sem volta não é plano.

O impacto por hora é o que justifica investir em redundância — sem ele, a discussão de custo de contingência não tem lado.

**As dependências são a conclusão.** Cada processo declara de que depende, e a dependência crítica sem alternativa é um **ponto único de falha**. A tela também cruza tudo e mostra a **concentração**: quantos processos críticos dependem da mesma coisa. É o que nenhuma avaliação de risco isolada mostra, porque cada uma olha um processo por vez.

***

### <font color="#15803D">Indicadores (KRI)</font>

O que avisa antes de a perda acontecer. Cada indicador declara limite de atenção, limite crítico e **direção** — e a direção não é detalhe: tempo de correção piora subindo, cobertura de backup piora caindo. Sem declarar, metade dos alertas sairia invertida.

Uma medição por data de referência: dois valores para o mesmo mês seriam duas verdades sobre o mesmo fato. Reenviar a mesma data corrige em vez de duplicar, e uma medição lançada na data errada pode ser apagada — pela tela, com rastro, e não por acesso direto ao banco.

### <font color="#15803D">Eventos de perda</font>

O risco que aconteceu. É o único lugar em que a matriz é confrontada com o fato: uma probabilidade avaliada como baixa que se materializou três vezes no ano **não era baixa**.

A perda estimada e a efetiva ficam em campos separados de propósito. A diferença entre as duas é o aprendizado, e sobrescrever uma com a outra apagaria justamente isso.

O tempo até detectar mede a capacidade de detecção, que é outra coisa da capacidade de prevenção — e costuma ser a que está pior.

[title] 13. Acervo de documentos
[path] Aplicações/GRCS/

*Políticas, procedimentos, contratos e evidências com versão, aprovação, portal, vínculos, grafo e IA.*

***

### <font color="#15803D">O que é</font>

O acervo guarda os documentos da empresa — políticas, procedimentos, processos, contratos, planos, modelos, registros, artigos e normas externas — com **versão**, **aprovação por fluxo**, **leitura obrigatória** e **vínculos** com o catálogo, os alvos e os registros de GRC. Ele funciona inteiro sem IA; as funções de IA somam-se quando há modelo configurado.

***

### <font color="#15803D">Tipos, subtipos e fluxos</font>

Em **Configuração do acervo**, cada tipo raiz (Normativo, Processo, Contrato, Plano, Modelo, Registro, Conhecimento, Norma externa) tem subtipos. O subtipo herda o que deixar em branco: prefixo do código, visibilidade padrão, periodicidade de revisão, fluxo de aprovação e a associação exigida (alvo, plano, framework, item de serviço). O fluxo tem etapas com ordem — **mesma ordem, etapas em paralelo** — e o aprovador pode ser uma pessoa, um grupo, um papel, o dono da área do documento, o dono do alvo associado, a gestão do acervo, o aprovador do plano de ação ou o revisor indicado no documento. Quem escreveu a versão não aprova sozinho a própria versão.

A tela tem três abas, e mexer nela pede a permissão de configurar o acervo:

1.     **Tipos e subtipos** — **Novo tipo** cria um tipo raiz; **+ subtipo**, na linha do tipo, cria um subtipo dele. No formulário, preencha a identificação e o que for diferente do tipo pai: **Fluxo de aprovação**, **Revisão periódica (meses)**, **Visibilidade padrão**, **Associação** e os **Metadados do tipo**. Clique em **Gravar**. Tipo com documentos, ou de fábrica, não se exclui: a confirmação oferece **Desativar em vez disso**.

2.     **Fluxos de aprovação** — **Novo fluxo**; em **Etapas**, dê a cada uma **Ordem**, **Nome da etapa**, **Quem aprova** e **Prazo (dias)**. **+ etapa seguinte** acrescenta uma etapa depois; **+ etapa em paralelo com a última** usa a mesma ordem. Com grupo ou papel, **basta um aprovar** decide se um só resolve a etapa. Clique em **Gravar**: as etapas são substituídas inteiras, e as versões já em aprovação seguem o fluxo com que foram submetidas.

3.     **Espaços** — **Novo espaço**, com **Dentro de** para aninhar, e **Gravar**.

***

### <font color="#15803D">Visibilidade</font>

| **nível**    | **quem lê**                                                     |
| ------------ | --------------------------------------------------------------- |
| Público      | qualquer pessoa, inclusive no portal                            |
| Interno      | quem é da empresa                                               |
| Restrito     | a lista de acesso (áreas, grupos, pessoas)                      |
| Confidencial | a lista de acesso, e não aparece na busca de quem não está nela |



A visibilidade vale **em toda consulta**, inclusive na busca semântica, no Pergunte à base e no grafo: o que você não pode ler não chega à resposta da IA. No grafo e no impacto, um documento que você não pode ler aparece como **restrito** — você sabe que existe uma dependência, não o que ela diz.

***

### <font color="#15803D">Aprovações — decidir uma versão que está com você</font>

A tela **Acervo ▸ Aprovações** lista as versões que esperam a sua decisão, com documento, versão, etapa, data de envio e prazo. No layout de portal, o quadro **Documentos para aprovar** da página inicial leva à mesma lista, e o sino avisa quando uma etapa chega para você.

1.     Em **Aprovações**, clique em **ler e decidir** na linha da versão.

2.     Leia a versão à esquerda. **Comparar com a vN vigente** mostra o que mudou em relação à versão que vale hoje; **abrir o documento** leva ao detalhe completo.

3.     À direita estão as etapas da aprovação, a recomendação da IA (que não decide nada) e as inconsistências encontradas na versão.

4.     Em **Sua decisão na etapa**, escreva o comentário e clique em **Aprovar** ou **Reprovar**. O comentário é opcional para aprovar e obrigatório para reprovar — é o que o autor vai corrigir.

Reprovar devolve a versão ao autor com o seu comentário. Aprovar passa para a próxima etapa; na última, a versão é publicada na data de vigência. Quem é o único autor da versão não pode aprová-la: o servidor recusa.

***

### <font color="#15803D">Documentos — cadastrar, versionar e publicar</font>

Em **Documentos**, a lista mostra só o que você pode ler; **Procurar**, **Tipo**, **Espaço** e **Situação** filtram. Clique no título para abrir.

1.     Clique em **Novo documento** (pede permissão de escrever no acervo). Escolha **Tipo e subtipo** e preencha o **Título** — os dois obrigatórios; o tipo não muda depois. **Código** em branco é numerado pelo prefixo do tipo. Complete **Quem responde** (área dona, dono, revisor, co-autores) e **Quem lê** (a visibilidade; restrito e confidencial pedem a lista de acesso). Se o tipo admitir, dá para marcar já a **Leitura obrigatória** e o **Público-alvo** — ou deixar para a aba **Leitura obrigatória** do documento, que tem também alvo, prazo e a contagem de pessoas (veja abaixo). Clique em **Criar documento**: ele abre em seguida.

2.     Clique em **Primeira versão** (depois, **Nova versão**). Escolha como ela entra — **Arquivo**, **Redigir aqui** ou, se o tipo aceitar, **Referência externa** —, a **Numeração** (alteração maior ou menor) e **O que mudou**. Clique em **Criar rascunho**.

3.     No quadro da versão em andamento: **Editar conteúdo** corrige o rascunho; **Submeter à aprovação** → **Submeter** inicia o fluxo do tipo. Tipo sem fluxo mostra **Publicar** direto.

4.     Aprovada, clique em **Publicar**: **Início da vigência** (obrigatório), **Fim da vigência** (opcional) e até quando a versão substituída continua pesquisável. Clique em **Publicar**. Vigência futura fica aguardando e troca sozinha no dia.

A partir da segunda versão, o **resumo** e a **natureza** da mudança são obrigatórios: **Editorial** não avisa ninguém; **Substantiva** avisa os donos dos documentos que dependem deste. Publicada, a versão não muda mais, e a substituída continua consultável pela auditoria. Versão reprovada volta ao autor com o comentário do aprovador: corrija e submeta de novo. **Confirmar revisão** registra que a vigente continua valendo sem mudança; **Revogar** pede justificativa e, se outros documentos dependem deste, que você marque ter visto a lista. Na aba **Versões**, marque duas e clique em **comparar as duas marcadas**.

*Exigir a leitura de um documento — por equipe, área, alvo ou perfil*

A leitura obrigatória se configura no próprio documento, na aba **Leitura obrigatória**. Ela está sempre à vista de quem responde pelo documento: o dono, os co-autores, quem o cadastrou (com permissão de escrever ou de publicar no acervo) e a gestão do acervo. Configurar é de quem escreve o documento; quem só publica acompanha as confirmações e lembra quem falta.

1.     Em **Documentos**, abra o documento e clique na aba **Leitura obrigatória**.

2.     Marque **Exigir leitura**.

3.     Em **Acrescentar por**, escolha **Área**, **Equipe**, **Alvo** ou **Perfil**; escolha o item na lista ao lado e clique em **acrescentar**. Repita para cada item. Cada item mostra quantas pessoas alcança hoje; o **X** tira o item.

4.     Se quiser, preencha **Prazo para ler** (em dias, de 1 a 365). Ele conta do início da vigência da versão que pede a ciência; passado o prazo, quem não leu aparece como **atrasada**. Em branco, sem prazo.

5.     Confira a frase **"N pessoas vão receber"** e clique em **Gravar leitura obrigatória**. **Desfazer** volta ao que está gravado.

Quem entra no público:

•     **Área** — todas as pessoas das equipes da área.

•     **Equipe** — as pessoas da equipe.

•     **Alvo** — vale pela área ou pela equipe que o alvo representa (em **Alvos**, edite o alvo e veja **Representa o cadastro de**). O alvo que não representa nada aparece desligado na lista, com o aviso "não representa nenhuma área nem equipe", e não pode ser gravado: ligue o alvo a um cadastro ou escolha a área ou a equipe diretamente.

•     **Perfil** — todas as pessoas com o perfil de acesso.

•     Quem está em mais de um item (a área e a equipe dela, e o perfil) conta uma vez.

O público só alcança **quem pode ler o documento**. A leitura obrigatória escolhe, entre as pessoas que a visibilidade do documento já deixa ler, quem precisa ler; ela não abre o documento para ninguém. Quem está na área, na equipe ou no perfil mas fica de fora da visibilidade não recebe o aviso, não conta no andamento e não é lembrado. Isso vale, por exemplo, para quem está fora da lista de um documento **Restrito** ou **Confidencial**, ou para um externo diante de um documento **Interno**. A frase da prévia avisa quantos ficaram de fora, por exemplo "3 pessoas do público não podem ler este documento (visibilidade CONFIDENCIAL) e não vão receber". O item em que ninguém pode ler mostra o mesmo aviso. Para incluir essas pessoas, ajuste a visibilidade ou a lista de acesso na aba **Cadastro**. O público acompanha a mudança na hora.

O público é recalculado a cada consulta, e não congelado no dia em que se gravou: quem entra na equipe depois passa a precisar ler, e quem sai deixa de aparecer como pendente. Se o alvo passar a representar outro cadastro, o público acompanha. A ciência que alguém já registrou nunca se perde: quem saiu do público continua na lista, como **fora do público**, mas não conta no progresso.

Se o documento já tem versão vigente, quem entra no público ao gravar recebe o aviso na hora, no sino e por e-mail; senão, o aviso sai quando a primeira versão entrar em vigor.

Se a aba disser que o tipo não admite leitura obrigatória, quem configura o acervo liga **Admite leitura obrigatória** no tipo, em **Configuração do acervo › Tipos e subtipos** — só depois disso a aba oferece a configuração. No formulário **Cadastro** de um documento que já existe, a leitura só é lembrada: a configuração é a da aba.

*Confirmações — quem leu e quem falta*

Na mesma aba, depois que há versão vigente, a parte **Confirmações** mostra:

•     o andamento: "v1.1: 12 de 32 registraram ciência (37%)", com a barra de progresso e o prazo;

•     os filtros **Todas**, **Pendentes** (com as atrasadas), **Atrasadas** e **Lidas**, cada um com a contagem, e o campo **procurar pessoa ou equipe**;

•     a lista: **Pessoa** (e por que ela está no público), **Equipe · Área**, **Situação**, **Lida em** e **Versão** lida.

**Lembrar quem falta** manda o aviso, no sino e por e-mail, só para quem ainda não leu. O lembrete sai uma vez a cada 24 horas por documento: enquanto não passam, o botão fica desligado e diz a partir de quando o próximo pode sair. **Exportar CSV** baixa a lista como está filtrada, pronta para o Excel.

A lista de quem leu e de quem não leu, com nome e hora, é dado pessoal: só quem responde pelo documento a vê. Quem só lê o documento vê, na aba, apenas onde registrar a própria ciência.

No construtor de painéis, o campo **Leituras obrigatórias pendentes** da fonte **Documentos do acervo** conta igual a esta aba: só quem está no público **e pode ler o documento** pela visibilidade dele — num documento confidencial com a área inteira no público, conta só quem está na lista nominal. O painel mostra o número, nunca os nomes.

A ciência é da versão. Uma versão nova **substantiva** pede a leitura de novo; a **editorial** não — quem leu a v1.0 não é cobrado pela v1.1 editorial, e a aba diz "a ciência pedida é a da v1.0".

***

### <font color="#15803D">Leitura obrigatória</font>

Um documento pode exigir a sua ciência — por estar numa área, numa equipe, num alvo ou num perfil que o documento pede. Quando a versão entra em vigor (ou quando a leitura é exigida de um documento já publicado), você recebe o aviso **Leitura obrigatória — código do documento** no sino e por e-mail; o clique no aviso abre esta tela.

Para registrar a sua ciência:

1.     Abra **Leitura obrigatória**: a lista traz as versões que esperam a sua leitura, com a data de publicação e o **Prazo** ("Ler até 12/10/2026", ou "Atrasada" quando já passou).

2.     Clique em **abrir e ler** na linha do documento e leia a versão.

3.     Clique em **Li e estou ciente desta versão** — ou em **Ler depois**, que só fecha.

A ciência fica ligada àquela versão: uma versão nova substantiva pede a leitura de novo; a editorial, não. Aberto pela tela **Documentos**, o documento de leitura obrigatória mostra na aba **Versão vigente** o botão **Li e estou ciente desta versão**, que faz o mesmo. Não pediram a sua leitura e você leu assim mesmo? A ciência fica registrada, mas não conta no andamento do documento.

Para exigir a leitura de um documento e acompanhar as confirmações, veja **Exigir a leitura de um documento**, na seção Documentos.

***

### <font color="#15803D">Importar acervo</font>

Suba um ZIP com os arquivos e um metadados.csv (separador ;, colunas arquivo, codigo, titulo, tipo, espaco, area, dono\_login, visibilidade, data\_publicacao, palavras). A primeira versão de cada documento entra publicada, com a data original. Uma linha com erro não desfaz as outras; o relatório diz linha a linha o que entrou e o que falhou.

1.     Em **Importar acervo** (pede a permissão de configurar o acervo), clique em **Baixar modelo do metadados.csv** e preencha uma linha por documento. arquivo é o caminho dentro do ZIP; tipo é o código do tipo ou subtipo; visibilidade é PUBLICO, INTERNO, RESTRITO ou CONFIDENCIAL; data\_publicacao vai em AAAA-MM-DD.

2.     Monte o ZIP com os arquivos, em qualquer pasta, e o metadados.csv na raiz.

3.     Em **Arquivo ZIP**, escolha o arquivo e clique em **Importar**.

4.     Confira **Linhas lidas**, **Importados** e **Falharam** e o **Relatório da importação**. Corrija a planilha e suba de novo só as linhas que falharam.

***

### <font color="#15803D">Pergunte à base</font>

Pergunte em linguagem natural. A resposta usa **só trechos que você pode ler** e cita documento, versão e seção. Quando nenhum documento responde, a tela diz **"A base não cobre esta pergunta"** e oferece abrir um chamado — ela não inventa uma resposta em tom de norma. Marque útil ou não útil: perguntas sem resposta e respostas não úteis formam as **lacunas do acervo**, que o gestor vê.

1.     Em **Pergunte à base**, escreva a pergunta (ao menos três letras) e clique em **Perguntar** — Enter também envia; Shift+Enter quebra a linha.

2.     Leia a resposta e as fontes citadas; clique numa fonte para abrir o documento. Se a resposta se apoiar numa versão que não está vigente, a tela avisa.

3.     Em **Esta resposta foi útil?**, clique em **útil** ou **não útil** (um voto por resposta).

4.     Se não resolveu, clique em **Abrir um chamado**: o portal abre com a pergunta, e ela vira lacuna para o dono da base.

Quem gere a base (permissão de configurar ou de publicar no acervo) tem também a aba **Lacunas do acervo**, com as perguntas sem resposta ou com voto não útil no **Período** escolhido.

***

### <font color="#15803D">Análise de aderência</font>

Envie um documento (ou cole o texto), marque as normas e acompanhe a avaliação requisito a requisito: atende, atende parcialmente, não atende, não aplicável ou inconclusivo, com o trecho que fundamenta e o ajuste sugerido. **O documento não é armazenado**: só fica registrado que você usou a análise, para a cota diária. Para guardar o resultado, baixe o relatório em PDF ou DOCX. Quando a norma não tem texto licenciado importado, a comparação é feita com a descrição do catálogo, e a tela avisa que a precisão é menor.

1.     Em **1. O documento**, escolha **Arquivo** (PDF, Word, Excel, PowerPoint, texto ou HTML, até 25 MB) ou **Colar o texto**.

2.     Em **2. O que ele precisa atender**, marque as **Normas do catálogo** e, se quiser, **Documentos prescritivos da organização** — a política ou o contrato que o documento deve seguir.

3.     Clique em **Analisar** e acompanhe o progresso; **Cancelar a análise** interrompe sem guardar nada.

4.     No **Resumo por norma** e na tabela (**Requisito**, **Situação**, **Fundamento no documento**, **O que ajustar**), leia o resultado. Antes de sair, clique em **Relatório PDF** ou **Relatório DOCX** — fechada a tela, a análise se perde.

Há uma cota diária de análises por pessoa.

***

### <font color="#15803D">Pré-validação e parecer</font>

Antes de enviar uma resposta de auditoria, o botão **Pré-validar** mostra o que a IA recomendaria ao auditor: aprovar ou devolver, por quê e o que ajustar. É opcional, nunca bloqueia o envio e **não deixa registro**. Se o auditor terá acesso a mais documentos que você, a tela avisa que a prévia foi feita com menos fontes.

Ao enviar, o **parecer** entra na fila e o auditor o encontra pronto: a recomendação, o porquê, o que fazer e as fontes. Se a resposta mudar, o parecer anterior fica marcado como desatualizado. **A recomendação nunca muda o status**: quem aprova ou devolve é uma pessoa — e, ao devolver, o "o que fazer" já vem preenchido como comentário, editável. Plano de ação e versão de documento têm o botão **Pedir recomendação da IA**; na versão, a recomendação inclui o impacto e as possíveis inconsistências com os documentos que dependem dela.

***

### <font color="#15803D">NC, risco e oportunidade</font>

Todo registro novo recebe uma **análise da IA**: os documentos que deveriam ter sido seguidos, onde o fato desvia do que está escrito (ou se a lacuna é do próprio documento), achados semelhantes e um **plano proposto**. O plano proposto aparece marcado como **proposta da IA** e só pode ser aprovado depois que alguém o aceita. A ação "revisar o documento X" só conclui quando existe versão nova de X publicada depois da abertura do achado, ou com justificativa.

***

### <font color="#15803D">Vínculos, cobertura e grafo</font>

Citações no texto ("conforme PRO-QUA-004", "ISO 27001 A.5.15") e sugestões da IA viram **vínculos pendentes** em **Vínculos a revisar**; só depois de confirmados eles contam na **cobertura** (requisito × documento prescritivo, na tela do UCF) e entram no **grafo**. Citações com o ano da edição ("ISO/IEC 27001:2022 A.8.13"), artigos da LGPD ("LGPD art. 46") e cláusulas da ISO 22301 ("ISO 22301 cláusula 8.4") também são reconhecidas.

Para revisar os pendentes, em **Vínculos a revisar** (pede a permissão de vincular documentos):

1.     Filtre por **Origem** — *extraído do texto* ou *inferido pela IA* — e, havendo mais de uma, por **Relação**.

2.     Leia a coluna **Por quê**: a justificativa e o trecho de onde o vínculo saiu.

3.     Marque as linhas, ou **Selecionar todos**, e clique em **Confirmar** ou **Rejeitar**.

Para ligar um documento à mão, abra-o em **Documentos**, vá à aba **Vínculos** e clique em **Declarar vínculo**: escolha o **Tipo do destino** e a **Relação**, procure o destino, escreva a **Justificativa (opcional)** e clique em **Declarar**. O vínculo declarado não passa pela fila; quando ele pode ser removido, a lixeira da linha aparece — e pergunta antes de remover, avisando quando o vínculo é a evidência de que o documento atende a um requisito.

***

### <font color="#15803D">Grafo do acervo — explorar impacto e dependências</font>

O grafo mostra impacto a jusante e dependências a montante, o caminho entre dois nós, os nós mais críticos, órfãos e lacunas, e uma simulação "e se" que não grava nada.

1.     Escolha a visão no topo: **Hierarquia da auditoria** ou **Rede de vínculos**.

2.     Na rede, recorte por **Tipos de nó**, **Framework**, **Profundidade** e **Sentido**; **incluir vínculos pendentes** mostra também os que ainda não foram confirmados.

3.     Clique num nó, ou procure em **Procurar nó pelo nome**. No painel do nó: **impacto** conta o que depende dele e aquilo em que ele se apoia; **caminho até…** pede um segundo nó; **centrar aqui** refaz o recorte em volta dele; **e se sumir?** e **e se ligar a…** simulam sem gravar.

4.     No painel ao lado, as abas **Nós críticos**, **Órfãos e lacunas** e **E se**; nesta, **desfazer tudo** limpa a simulação.

5.     Para levar o recorte, use **PNG**, **JSON** ou **tabela (Excel)**.

*Duas visões do grafo*

•     **Hierarquia da auditoria** (padrão para quem lê auditoria): escolha a auditoria e ela aparece em árvore — **auditoria → alvos (com os alvos-pai) → não conformidades e riscos → planos de ação e documentos**. Cada ramo fechado diz o que guarda ("12 NC · 3 riscos · 2 planos"); sob o alvo, as NCs se agrupam por severidade (Crítica, Alta, Média, Baixa). Abra um ramo para descer um nível, ou use **até os alvos / até os grupos / tudo / recolher**. A busca mostra só os ramos com o termo, já abertos até ele, e os filtros escondem um tipo (planos, documentos…). Ao lado, o **desenho em camadas** mostra, da esquerda para a direita, só o que estiver aberto — por isso continua legível com dez alvos. Um risco materializado por duas NCs aparece sob as duas. Para levar, **desenho PNG**, **desenho SVG**, **tabela (Excel)** ou **imprimir**.

**Controles e requisitos.** Sob cada NC vem o **controle** que ela aponta como falho — o da pergunta que gerou a NC, pela resposta ou pela regra (ligação **falha no controle**) — e, sob o risco, o controle que o mitiga (**mitigado por**). Sob o controle, os **requisitos** que ele atende (**atende**), só dos frameworks que a auditoria avalia: um controle do catálogo unificado atende dezenas de requisitos de outras normas, e eles enterrariam o achado. Auditoria de tema ou de questionário mostra o controle sem requisito. Assim a cadeia **requisito → controle → achado** se lê a partir do achado: a NC, o controle que falhou, o requisito que ficou descoberto. O mesmo controle aparece sob cada NC que falha nele, e o ramo fechado conta os controles ("8 NC · 5 controles · 2 riscos"); a tabela (Excel) ganha a coluna **Controles abaixo**, no fim. Controle e requisito pedem catalogo\:ler, como na rede; para ver só os achados, desmarque **Controle** nos filtros de tipo.

•     **Rede de vínculos**: o grafo de forças do acervo inteiro, para explorar o que se liga a quê, impacto, caminho e simulação. Com muitos nós ele fica denso: filtre por tipo e centre num nó.

*Por área e equipe — filtros e "Quem tem…"*

As duas visões respondem também **que área ou que equipe tem** um documento, uma NC, um risco, uma oportunidade ou um plano. A área e a equipe de cada registro vêm do cadastro de **Áreas e grupos**, com a mesma regra nas duas visões:

| **Registro**             | **É da área / equipe…**                                                                                              |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------- |
| Alvo                     | que ele representa (**Representa o cadastro de**); se não representa nada, a do alvo-pai mais próximo que represente |
| Documento                | do próprio documento, a do espaço em que está e as equipes do dono                                                   |
| Não conformidade e risco | do alvo em que ocorrem e as equipes do dono                                                                          |
| Oportunidade             | da unidade e as equipes do dono                                                                                      |
| Plano de ação            | da NC ou do risco que trata, e as equipes de quem tem ação no plano                                                  |



A equipe sempre traz a área dela: filtrar pela área inclui o que é das equipes dela. Requisito, controle e framework são do catálogo, de todos, e não entram. Documento restrito não mostra área nem equipe.

1.     **Área** e **Equipe**, ao lado dos outros filtros: abra a caixa e marque uma ou várias (o número ao lado é quantos registros do recorte são de cada uma). Dentro da caixa vale qualquer uma das marcadas; entre Área e Equipe, as duas. **tirar área e equipe** limpa.

◦      Na **hierarquia**, ficam os registros da seleção e os ramos acima deles, em **itálico e esmaecidos** — só para mostrar em que alvo cada um está. A contagem de cada ramo passa a contar só a seleção. O controle e o requisito abaixo de um registro da seleção também ficam, esmaecidos: são do catálogo, sem área nem equipe, e sem eles a NC da equipe perderia a cadeia até o requisito.

◦      Na **rede**, ficam os nós da seleção e, com **com os vizinhos diretos, esmaecidos**, os vizinhos de cada um, em itálico.

2.     **Quem tem…**: escolha um tipo (**Não conformidade**, **Documento**, **Risco**…) ou **qualquer registro** — ou, no detalhe de um registro, **quem tem este?**. O que tem ganha **contorno duplo** no desenho (e a marca **tem** na árvore); o resto esmaece. Ao lado, a lista mostra cada área e cada equipe com a quantidade por tipo, e avisa quantos não são de área nenhuma.

3.     Clique numa linha da lista para filtrar o grafo por ela; clique de novo para tirar. **lista (Excel)** leva a lista.

4.     A **tabela (Excel)** das duas visões traz as colunas de áreas e equipes; na hierarquia, **imprimir** inclui o filtro e a lista do "Quem tem…".

***

### <font color="#15803D">Configuração da IA</font>

Em **Modelos de linguagem**, cada análise pode ser desligada ou ter modelo próprio, e documentos internos podem ser designados como **fonte de referência** de um framework (por exemplo, um guia de interpretação da LGPD). Numa instalação sem GPU, a indexação em lote cede a vez a quem está usando a IA na tela.

[title] 17. Dimensões
[path] Aplicações/GRCS/

*Como saber o resultado por contrato, serviço, área, fornecedor, cliente e a própria empresa.*

Depois que as respostas chegam, a pergunta muda. Não é mais "qual o score do ciclo", e sim **"como está por contrato? e por fornecedor?"**. A dimensão é o eixo que responde a isso.

***

### <font color="#15803D">A dimensão é o tipo do alvo</font>

São a mesma coisa vista de dois lados:

|                  | **O que é** | **Exemplo**                        |
| ---------------- | ----------- | ---------------------------------- |
| **Tipo de alvo** | a classe    | Contrato                           |
| **Alvo**         | a instância | Contrato 4471 — Manutenção predial |



A auditoria escolhe a **instância** como alvo. A não conformidade e o risco apontam para a mesma instância. O relatório agrupa pelo **tipo**. Por isso não existe um cadastro separado de dimensões: elas são os tipos de alvo, em **Alvos e dimensões**.

Vêm doze de fábrica — organização, unidade de negócio, área, equipe, contrato, serviço, cliente, fornecedor, ativo de TI, processo, sistema e planta. São somente leitura. Você cria os seus quando auditar algo que não está nessa lista; a lista do que uma organização audita não é universal.

***

### <font color="#15803D">Como uma resposta chega a uma dimensão</font>

Uma resposta pode falar de mais de um eixo ao mesmo tempo — "existe MFA no acesso remoto" diz algo sobre serviços, sobre fornecedores e sobre a própria empresa. O vínculo entre resposta e dimensão tem três origens possíveis, e elas **não têm o mesmo valor probatório**:

1.     **A marcação da pergunta.** Feita no catálogo, uma vez, vale para toda auditoria que use aquela pergunta. É a mais barata e a mais estável — quem escreve a pergunta sabe que ela fala de fornecedor.

2.     **A marcação à mão, na resposta.** Alguém olhou aquela resposta e disse que ela toca aquele eixo.

3.     **A leitura automática.** A plataforma lê o enunciado e a justificativa e **propõe** vínculos, com um grau de confiança e o motivo em que se baseou.

As duas primeiras são declaração humana e valem imediatamente. A terceira é hipótese: **nasce sem aceite e não entra em número nenhum** até alguém aceitar. A regra não é disciplina do código — é uma restrição da própria tabela no banco.

***

### <font color="#15803D">Marcar a dimensão na pergunta</font>

Em **Catálogo ▸ Perguntas**, abra a pergunta e, em **Dimensões**, clique na dimensão para ligar ou desligar — grava no clique. Vale para toda auditoria **aberta depois**: a resposta já nasce ligada ao eixo. A marcação é da sua instalação, inclusive nas perguntas de fábrica — o que uma pergunta avalia depende do negócio de quem a usa. Exige catalogo\:escrever (e escopo\:ler, para ver a lista de dimensões); sem isso, as dimensões marcadas aparecem só para leitura.

### <font color="#15803D">Marcar e desmarcar a dimensão na resposta</font>

Na tela da auditoria, no alto de cada resposta, ficam as etiquetas dos vínculos:

1.     **Marcar à mão**: **+ dimensão** → escolha a dimensão. Só aparecem as ativas que a resposta ainda não tem. Se havia uma sugestão pendente daquela dimensão, marcar à mão é aceitá-la.

2.     **Desmarcar**: o **×** da etiqueta de um vínculo aceito — da pergunta, à mão ou sugestão aceita. A resposta deixa de contar naquele eixo.

3.     As sugestões da leitura automática têm **✓** e **×** — ver abaixo.

Tudo isso exige auditoria\:revisar, e some com o ciclo em rascunho ou encerrado; sem a permissão, as etiquetas aparecem só para leitura.

### <font color="#15803D">Marcar dimensões no ciclo não liga resposta nenhuma</font>

Ao abrir a auditoria, no campo **Dimensões que este ciclo vai reportar**, você escolhe **sobre quais eixos quer reportar**. Isso faz duas coisas: os eixos aparecem no painel de dimensões mesmo com zero, e a leitura automática fica restrita a eles.

O que essa marcação **não** faz é afirmar que cada resposta fala de todos aqueles eixos. A primeira versão desta funcionalidade fazia exatamente isso, e o resultado foi um painel em que as 130 perguntas apareciam nos quatro eixos — tudo em tudo, que é o mesmo que não ter painel.

Nada marcado significa **todos os eixos ativos**, e não nenhum.

***

### <font color="#15803D">O painel de dimensões</font>

Em **Auditorias**, abra o ciclo e clique no bloco **Respostas por dimensão** para abri-lo. O botão **Sugerir dimensões** roda a leitura automática sobre as respostas do ciclo e diz quantas sugestões fez. Cada eixo mostra:

•     **score** — média ponderada, pela mesma regra do ciclo: só resposta **aprovada** e pontuável entra. Uma dimensão sem revisão concluída aparece sem score, e isso é correto: contar a resposta não revisada faria a dimensão parecer melhor que a auditoria inteira.

•     **respondidas** — quantas das respostas ligadas àquele eixo já foram respondidas.

•     **gaps** — quantas apontaram ausência de controle.

•     **a conferir** — sugestões automáticas pendentes de aceite.

A soma das colunas é maior que o total de perguntas do ciclo, e isso é correto: a mesma resposta de fato diz algo sobre contrato e sobre fornecedor ao mesmo tempo.

***

### <font color="#15803D">Aceitar ou recusar uma sugestão</font>

As sugestões aparecem como etiquetas tracejadas no alto da própria resposta, com a confiança em porcentagem e o motivo no rótulo de ajuda (passe o mouse). Duas ações, na etiqueta:

•     **✓ aceitar** — passa a contar no score daquele eixo, e fica registrado quem aceitou e quando;

•     **× recusar** — apaga a sugestão.

Os botões somem com o ciclo em rascunho ou encerrado, e sem auditoria\:revisar. Recusar só alcança sugestão pendente. Vínculo já aceito tem dono; desfazê-lo é desmarcar a dimensão (o **×** da etiqueta aceita), o que gera o registro correspondente na trilha.

***

### <font color="#15803D">Sobre a leitura automática</font>

Hoje ela é **léxica**: procura no enunciado e na justificativa as palavras que caracterizam cada dimensão, e diz na própria justificativa em que palavras se baseou. Não interpreta contexto e não resolve negação — por isso a confiança satura em 90% e nunca chega a certeza.

Quando a integração por modelo entrar, ela troca de lugar com esta sem que nada mais mude: nem a tabela, nem esta tela, nem a regra de aceite. Chamar a leitura de hoje de "IA" seria descrever errado o que roda.


[title] 19. IMR — Instrumento de Medição de Resultado
[path] Aplicações/GRCS/

*O motor que transforma sinal técnico e registro de processo em valor a faturar, com nexo auditável. Exclusivo de contratos do Governo Federal brasileiro.*

O IMR não é mais um indicador. É um **motor de apuração financeira**: transforma telemetria e registros em valor a faturar por contrato, por mês, com nexo auditável.

Ele não coleta dado e não opera nada. Recebe fatos de duas fontes, aplica regra contratual e produz três saídas: a memória de cálculo, a proposta de ateste ou glosa, e o registro imutável que sustenta a decisão da Administração.

O princípio que governa tudo:

:::hint{type="info"}
Disponibilidade isolada não confere conformidade. Uma unidade só é conforme quando os três sinais coincidem no mesmo período, sobre o mesmo ativo, com evidência no canal pactuado.
:::

E a consequência disso, que explica metade das decisões do módulo: **ausência de sinal nunca vira conformidade**. Um sinal que não chegou vale DESCONHECIDO, jamais OK.

***

### <font color="#15803D">Ligar e desligar</font>

O módulo nasce **desligado**. Em **Administração ▸ Normas disponíveis**, no bloco **IMR — Instrumento de Medição de Resultado**, o botão mostra **Desligado** ou **Ligado nesta instalação**; clique nele para trocar (exige admin\:estrutura). Ligado, acrescenta o grupo **IMR**, com dez telas, ao menu de quem tem imr\:ler; desligado, nenhuma tela aparece.

As permissões do módulo separam quem faz o quê: `imr:ler `consulta; `imr:operar` conduz o ciclo (abrir período e ligá-lo ao contrato, congelar, apurar, propor consequências, abrir contraditório, registrar alegação, declarar janela e registrar à mão ocorrência aberta); `imr:decidir` registra o ato da Administração, revisa apuração, responde alegação, define parâmetro e vê o Faturamento; `imr:contratar` cadastra contrato, atividade, regra, modelo de cálculo e unidade; `imr:ingerir` é das plataformas que enviam dado.

Desligar **não apaga nada**. Períodos, apuração e decisões continuam gravados, e religar devolve tudo — um interruptor que destrói dado não é interruptor, é armadilha.

A razão de nascer desligado: o instrumento atende exclusivamente a contratos do Governo Federal brasileiro. Numa instalação privada seriam dez itens de menu que ninguém abre, e menu que não serve ensina a pessoa a ignorar o menu.

***

### <font color="#15803D">Como o módulo fica desacoplado</font>

O IMR é um módulo Maven próprio, com esquema próprio (`imr`) e permissões próprias. A dependência aponta só para dentro: ele conhece o núcleo e o escopo, e **nenhum outro módulo o conhece**. Tirar a linha do pom.xml deve deixar a plataforma compilando — se um dia não deixar, o acoplamento voltou e alguém precisa desfazer.

***

### <font color="#15803D">As dez telas</font>

**Contratos** — o que foi contratado, por quanto, e sob que regras. É a primeira tela do menu porque é onde o instrumento começa: sem contrato não há valor a ratear, e a glosa fica só em percentual.

**Unidades de remuneração** — U1 a U7, com o que cada dimensão significa em cada uma e quais itens estão nelas. A unidade é o que liga o item de configuração ao dinheiro: o item pertence a uma, a atividade contratada atende uma, e é por essa coincidência que o motor sabe quanto vale cada item no rateio.

**Períodos** — o ciclo mensal, um período por contrato, e suas ações: abrir já com o contrato, congelar, apurar, propor consequências, abrir contraditório. Cada botão só acende no estado em que faz sentido.

**Apuração** — item a item, com estado, percentual de pagamento, valor rateado e montante da glosa. Cada linha abre: os sinais que a sustentam, o histórico de revisões, e a ação de revisar.

**Contraditório** — os itens abertos para contestação com o valor em jogo, e as alegações apresentadas. Antes da decisão e não depois: um instrumento que glosa e depois ouve inverte a ordem que o contrato estabelece.

**Decisões e travas** — o ato da Administração, e o indicador de tempestividade.

**Memória de cálculo** — de qualquer valor, o caminho até o sinal que o sustenta, com o contrato, o método de rateio e o hash da base na mesma folha. Exportável em CSV, formato aberto, independente do produto.

**Parâmetros do ANS** — os limiares, com rótulo, unidade, faixa e explicação, versionados por data de vigência.

**Faturamento** — o que vai para pagamento no mês, uma linha por contrato.

**Itens de configuração** — o que o Autonomous descobriu, e os sinais que foram rejeitados.

O caminho de um mês, na ordem das telas: cadastre o **contrato** (com atividades e regras), confira as **unidades**, abra e conduza o **período**, confira a **apuração**, ouça o **contraditório**, registre a **decisão**, e só então o **faturamento** mostra o valor a pagar.

***

### <font color="#15803D">Itens de configuração e sinais rejeitados</font>

A tela **IMR ▸ Itens de configuração** é de consulta: os itens chegam pela ingestão do Autonomous (`POST /api/v1/imr/ingestao/ativos`), e não por cadastro na tela.

1.     Em **Procurar por nome, identificador ou endereço IP**, digite parte do nome, o identificador ou o IP.

2.     A tabela mostra **Item**, **Endereço**, **Tipo**, **Unidade**, **Criticidade**, **Localidade** e **Visto em**. Clique no nome do item para ver o inventário que cada fonte reportou.

3.     Em **Sinais rejeitados**, no fim da tela, fica o que a ingestão recusou, com o motivo e quando chegou — é o primeiro lugar a olhar quando um item aparece sem sinal na apuração.

Trocar o item de unidade é na tela **Unidades** (coluna **Mover para**).

***

### <font color="#15803D">As unidades, e o que cada dimensão significa em cada uma</font>

U1 a U7 existiam como restrição no banco e lista fixa no formulário: sem nome, sem explicação, e sem nenhum lugar onde ver quais itens estão em cada uma.

Na tela **IMR ▸ Unidades** (alterar exige `imr:contratar`):

1.     Clique numa unidade para abrir a lista dos itens dela; na coluna **Mover para**, escolha outra unidade para mudar o item de lugar.

2.     Para criar uma unidade que o ANS definiu, clique em **Nova unidade**, preencha **Código**, **Nome**, **Ordem**, **Descrição** e os três critérios — **Critério de disponibilidade**, **Critério de registro** e **Critério de controle** — e clique em **Salvar**.

3.     Para corrigir uma unidade própria, use **editar** no cartão dela. As marcadas **do requisito** não têm esse link.

O que a tela traz de novo não é o cadastro — é o **critério de cada dimensão**. O requisito define, para cada unidade, o que conta como disponibilidade, como registro e como controle, e são coisas diferentes: num endpoint a disponibilidade é o agente reportando; num ativo de rede é a coleta de estado e enlace; num ativo recuperável, a conformidade nem se mede por estar de pé, e sim por uma restauração testada dentro do tempo acordado.

|                              | **Disponibilidade**                | **Registro**                          | **Controle**                                                   |
| ---------------------------- | ---------------------------------- | ------------------------------------- | -------------------------------------------------------------- |
| **U1** Endpoint              | agente ativo e reportando          | item ativo na CMDB                    | EDR ativo, disco cifrado, postura de MDM, atualização no prazo |
| **U2** Servidor ou instância | telemetria de SO e de desempenho   | item e serviço no catálogo            | linha de base, backup com restauração válida, agente presente  |
| **U3** Ativo de rede         | coleta de estado e enlace          | item com janela de mudança registrada | regra revalidada após a mudança, registro íntegro no SIEM      |
| **U4** Serviço digital       | monitor sintético e desempenho     | serviço publicado no catálogo         | mudança aprovada, WAF ativo, backup válido                     |
| **U5** Ativo protegido       | telemetria do controle de proteção | item vinculado ao controle            | controle reportando saúde no período                           |
| **U6** Ativo recuperável     | rotina de backup íntegra           | item com política vinculada           | restauração testada dentro de RTO e RPO                        |
| **U7** Outros, sob demanda   | caso a caso, no ANS                | registro obrigatório                  | definido no ANS                                                |

Sem esse texto à vista, quem recebe um item em "não governável" não tem como saber o que deveria ter chegado, e a conversa com o fornecedor vira troca de opinião.

A tela mostra, por unidade, quantos itens existem, quantas atividades a cobrem e quanto vale cada item no rateio — e **avisa quando há unidade com item e sem atividade contratada**: esses itens são apurados e rateados a zero, e apareceriam na apuração sem valor e sem explicação.

Mover um item de unidade é possível, e é recusado quando ele está numa base congelada de período ainda não encerrado: trocar a unidade ali mudaria o denominador de um rateio já feito. Não se move o poste depois do tiro.

As sete de fábrica não se editam — o texto delas é o do requisito, e reescrevê-lo faria a plataforma divergir do documento que o contrato cita. O órgão cria as próprias quando o ANS definir outras.

***

### <font color="#15803D">O contrato, que é a base de tudo</font>

O IMR nasceu apurando conformidade e propondo glosa em percentual. Faltava o denominador: um item em 50% propunha "glosa de 50%" de coisa nenhuma. **Percentual sem base não é glosa, é opinião** — e nenhuma Administração assina uma opinião.

Na tela **IMR ▸ Contratos** (cadastrar exige `imr:contratar`), nesta ordem:

1.     **Modelo de cálculo** — no bloco **Modelos de cálculo**, no fim da tela, clique em **Novo modelo** e preencha **Código**, **Nome**, **Versão**, **Descrição**, **Rateio**, **Arredondamento**, **Casas decimais** e **Teto mensal (%)**. **Salvar**. Para mudar o método, prefira uma versão nova a editar: preserva o histórico.

2.     **Contrato** — clique em **Novo contrato** e preencha **Código**, **Nome**, **Objeto**, **Número**, **Processo**, **Papel no nexo** (Governança C1-GOV, Operação C2-OPR ou Segurança C3-SEC), **Fornecedor**, **Órgão**, **Vigência — início** e **fim**, **Valor mensal** (o denominador do rateio), **Valor global** e **Modelo de cálculo**. **Salvar**.

3.     **Atividades** — clique no contrato para abri-lo; na aba **Atividades e serviços**, clique em **Nova atividade** e preencha **Código**, **Nome**, **Tipo** (Serviço, Atividade ou Insumo), **Unidade do IMR**, **Quantidade**, **Valor unitário** e **Valor mensal**. A tela diz se a soma das atividades fecha com o valor mensal do contrato.

4.     **Regras de glosa** — na aba **Regras de glosa**, clique em **Nova regra** e preencha **Código**, **Nome**, **Gatilho**, **Condição** (ex.: CONTROLE=FALHA), **% de glosa**, **Base** (Item, Atividade ou Contrato), **Teto (%)**, **Vigente de** e **Aplica-se a** (Todo o contrato ou uma atividade). **Salvar**.

Para corrigir um contrato, use **editar** no cartão dele.

O cadastro tem quatro objetos, nesta ordem de dependência:

**Modelo de cálculo** — o *como*. Existe antes do contrato e serve a vários: o rateio, o arredondamento, o teto mensal. Um órgão tem um jeito de calcular e vários contratos; redigitar o método a cada assinatura é onde a divergência nasce. O contrato o **herda**, não o copia.

**Contrato** — o *o quê*: objeto, número, processo, fornecedor, órgão, vigência, valor mensal e valor global. O contrato também é um **Alvo** da plataforma, porque contrato é dimensão de avaliação em auditoria, risco e painel — e o cadastro cria ou liga o Alvo sozinho, pelo código. Dois cadastros do mesmo contrato garantiriam que um dia eles divergissem, e esse dia seria o de uma glosa calculada sobre o valor errado.

**Atividades e serviços** — o que o contrato presta, cada um com quantidade, valor unitário, valor mensal e a **unidade do IMR** que atende. A unidade é o que liga dinheiro a apuração: o item de configuração pertence a uma unidade, a atividade também, e é por essa coincidência que o motor sabe quanto vale um item. A tela soma as atividades e diz se elas fecham com o valor mensal do contrato — quando não fecham, a diferença não é rateada sobre item nenhum, e é melhor saber disso antes do fechamento.

**Regras de glosa** — quando se glosa e quanto, por contrato ou por atividade. O percentual é de **glosa**, não de pagamento: 20% em NC leve glosa um quinto. Antes disto o percentual vinha do código; funciona para um contrato e para nenhum outro, e um número negociado que só existe dentro do jar é um número que ninguém audita. Sem regra cadastrada o motor usa o padrão do produto — o complemento do percentual de pagamento — e a memória de cálculo **diz qual dos dois caminhos foi usado**, porque um padrão não pode passar por uma negociação que não houve.

Cinco gatilhos, e a ordem de procura vai do mais específico para o mais geral — que é a ordem em que a Administração escreve o contrato:

| **Gatilho**     | **Dispara quando**                      | **Condição**   |
| --------------- | --------------------------------------- | -------------- |
| DIMENSAO        | uma dimensão chega em certo valor       | CONTROLE=FALHA |
| NAO\_GOVERNAVEL | o item não é governável                 | —              |
| VISIBILIDADE    | a evidência está fora do canal pactuado | —              |
| INCLUSAO        | item novo remunerado                    | —              |
| ESTADO          | a faixa do estado apurado               | NC\_MEDIA      |

Primeiro o caso nomeado — *controle em falha glosa tanto* —, depois a faixa do estado, e só então o padrão. Começar pelo estado faria a regra de dimensão nunca pegar, porque todo item não conforme tem estado.

Entre regras do mesmo gatilho, a da **atividade** vence a do contrato inteiro, a de **vigência mais recente** vence a anterior — aditivo sucede o texto, não o apaga —, e a de menor **ordem** desempata.

A **base** escolhe sobre o que o percentual incide: o item que falhou, a atividade inteira quando a falha a compromete, ou o contrato quando o descumprimento é estrutural. As três contas produzem valores muito diferentes. O **teto** limita o percentual efetivo da própria regra, e a memória registra quando ele pegou.

***

### <font color="#15803D">Como o valor de um item é calculado</font>

Na tela **IMR ▸ Memória de cálculo**, escolha o **Período**. Os cartões trazem o contrato, o fornecedor, o valor mensal, o estado do período, a base rateada, a glosa proposta, os itens na base congelada e o **Hash da base**; o quadro **Como este valor foi calculado** diz o método, o teto e o residual do rateio; e **Consequências** lista cada proposta, inclusive as suprimidas por não cumulatividade. **Exportar memória (CSV)** baixa tudo num arquivo só, com o hash da base, e a exportação fica registrada.

O período pertence a um contrato, e o contrato só responde pelas unidades que presta. Por isso o congelamento e a apuração consideram apenas os itens das unidades cobertas — apurar o parque inteiro produziria linhas "não governável, R$ 0,00" que não dizem respeito a ninguém. Período sem contrato continua pegando tudo, que é o modo sombra.

Com o rateio padrão, **por parque da unidade**:

:::BlockQuote
valor do item = valor mensal da atividade ÷ itens daquela unidade na base congelada
glosa do item = valor do item × (100 − percentual de pagamento) ÷ 100
:::

ou, quando há regra cadastrada, o percentual e a base dela no lugar do complemento. O valor fica **gravado na apuração**, e não recalculado na leitura: a apuração é append-only e sustenta glosa, e se o valor viesse de junção, mudar o contrato amanhã mudaria a memória de cálculo de ontem — que existe exatamente para não mudar.

A soma das bases quase nunca fecha exatamente com o valor mensal: dividir o valor de uma atividade por catorze itens deixa centavos de fora. A memória **declara o residual** em vez de deixá-lo sumir — quem confere soma a coluna e compara com o contrato, e alguns centavos sem explicação custam uma reunião. Acima de um real a diferença deixa de ser arredondamento e a tela diz isso: provavelmente há atividade sem item apurado na unidade dela.

***

### <font color="#15803D">Faturamento: o que vai para pagamento no mês</font>

A tela **IMR ▸ Faturamento** (exige `imr:decidir`) é a saída para o financeiro: uma linha por contrato, e não a memória de cálculo.

1.     Em **Referência**, escolha o mês.

2.     Confira cada contrato: **Valor mensal**, **Inclusões**, **Glosa**, **Líquido** e **Situação** — **faturável**, **travado** ou **sem ato**. O total do alto é **Faturável no mês**.

3.     **Exportar bloco (CSV)** baixa o bloco para o financeiro.

Só entra na soma o contrato com ato da Administração registrado (em **Decisões e travas**) e sem trava. Contrato travado aparece com zero e com o motivo, e não some da lista: omiti-lo faria a soma fechar como se ele não existisse. Mês sem período aberto não mostra linha nenhuma.

***

### <font color="#15803D">O teto mensal de glosa</font>

Depois de todas as regras, e **depois da supressão por não cumulatividade**, a glosa acumulada é comparada ao teto: um percentual do valor mensal do contrato, vindo do parâmetro do ANS quando ele existe e do modelo de cálculo quando não — e a memória diz de qual dos dois, porque o modelo é o método padrão do órgão e o parâmetro é o que aquele instrumento negociou.

Passando do teto, o corte é **proporcional**, e não por ordem de chegada: cada item cede a mesma fração. Cortar as últimas glosas até caber faria o valor de um item depender de quando ele foi processado, que é o oposto de reprodutível.

Nada é apagado. O evento guarda o valor bruto e o valor limitado, e a diferença entre as duas colunas é o corte — visível na memória de cálculo em vez de sumir numa subtração que ninguém vê. Um evento próprio registra o excedente, o fator aplicado e o critério.

A ordem importa: o teto vem depois da supressão porque consequência suprimida não pode consumir teto. Fosse antes, a supressão — que existe para não cobrar duas vezes pelo mesmo fato — acabaria reduzindo a glosa dos outros itens.

***

### <font color="#15803D">Revisar a apuração</font>

Na tela **IMR ▸ Apuração**:

1.     Escolha o **Período**. Os cartões mostram contrato, valor mensal, base rateada e glosa proposta no filtro.

2.     Filtre por **Estado**, **Unidade** ou **Buscar item** (identificador ou nome); **limpar** volta a tudo.

3.     Clique no item para abrir **Sinais recebidos no período** e **Revisões**.

4.     Para corrigir, clique em **Revisar esta apuração**, escolha o **Estado**, informe o **% de pagamento** e o **Motivo**, e clique em **Gravar revisão**.

Se o período não estiver ligado a um contrato, a tela avisa: a conformidade é apurada do mesmo jeito, mas a glosa fica só em percentual. O contrato se liga em **IMR ▸ Períodos**, e só antes de congelar a base (veja *O ciclo, passo a passo*); com a base já congelada, a saída é apagar o período e abri-lo de novo escolhendo o contrato.

A apuração pode ser corrigida, e a correção não apaga nada: grava uma revisão nova com estado, percentual, motivo e autor, e a anterior continua inteira e consultável. Exige `imr:decidir`, e não `imr:operar` — mudar o estado apurado à mão muda o que se vai faturar, e isso é ato de quem decide.

A alternativa, deixar corrigir o número no lugar, é o que transforma um instrumento de medição em planilha: quem confere a glosa precisa poder perguntar *o que dizia antes, e quem mudou*, e se a resposta some no UPDATE, a memória de cálculo vira declaração de fé.

***

### <font color="#15803D">O contraditório tem prazo</font>

Na tela **IMR ▸ Contraditório**:

1.     Escolha o **Período**. O quadro **Como funciona neste período** diz o prazo para alegar e o prazo para a Administração decidir. Alegação só entra depois de o contraditório ser aberto, pelo botão **Contraditório** da tela **Períodos**.

2.     Em **Itens abertos para contestação**, ordenados pelo valor em jogo, clique em **registrar alegação** no item, preencha **Fornecedor**, **Alegação** e **Evidência** e clique em **Registrar**.

3.     Em **Alegações apresentadas**, clique em **Acolher** ou **Rejeitar**, escreva o **Fundamento** e clique em **Registrar resposta**.

Acolher não corrige o valor sozinho: a correção é uma revisão na tela **Apuração**.

Abrir o contraditório calcula dois prazos em **dias úteis** sobre o calendário de feriados, a partir dos parâmetros do ANS: até quando o fornecedor pode alegar, e até quando a Administração tem para decidir.

O calendário fica em **Parâmetros do ANS ▸ Calendário de prazos**. Os feriados nacionais vêm de fábrica e não saem — valem por lei, e apagá-los faria o prazo do instrumento divergir do prazo do processo. O municipal é do cliente e se acrescenta ali. Ponto facultativo — Carnaval e Corpus Christi — não é feriado por lei, e a distinção existe no direito administrativo: por padrão ele também não conta, e o parâmetro prazo.considera.ponto.facultativo inverte a escolha.

Quando o calendário não cobre o ano, o cálculo degrada para fim de semana e **registra** o aviso. Prazo silenciosamente errado é pior do que prazo declaradamente aproximado — e num instrumento que recusa alegação fora do prazo, contar feriado como dia útil produz recusa que o fornecedor contesta com razão. Alegação fora do prazo é **recusada**, e a recusa diz até quando era — aceitar em silêncio faria o prazo existir só no papel, e o fornecedor seguinte, que respeitou, teria sido prejudicado por respeitar.

A tela mostra primeiro **o que pode ser contestado**, ordenado pelo valor em jogo, e depois as alegações apresentadas. Antes ela listava só alegações, e no começo do prazo não há nenhuma — a tela nascia vazia justamente no momento em que mais precisa ser usada. A decisão de contestar é econômica antes de ser jurídica, e por isso o montante vem junto.

Acolher ou rejeitar **exige fundamento escrito**. Sem ele a resposta é recusada: o fornecedor tem direito a saber o motivo, e quem revisa depois precisa dele. Acolher não muda a apuração sozinho — a correção é uma revisão, com motivo próprio. São dois atos porque são duas decisões.

***

### <font color="#15803D">O ciclo, passo a passo</font>

Na tela **IMR ▸ Períodos** (conduzir exige `imr:operar`):

1.     Em **Nova referência (AAAA-MM)**, digite o mês (ex.: 2026-10), escolha o **Contrato** e clique em **Abrir período**. Com um contrato ativo só, ele já vem escolhido. A opção **sem contrato (modo sombra)** existe de propósito, e a tela avisa o que custa: a conformidade sai, mas não há valor a ratear e a glosa fica só em percentual.

2.     A coluna **Contrato** mostra de qual contrato é cada período. Enquanto o período está **aberto** e sem base congelada, **ligar a contrato** (ou **trocar**) abre a lista: escolha e clique em **Ligar**. Depois do congelamento a troca não é oferecida — a base congelada é a do contrato, e trocá-lo faria a base de um sustentar a glosa de outro. Se o período aberto **já recebeu sinais**, eles entraram pela cobertura do contrato de antes: quando o contrato novo presta só parte do que o antigo cobria (o caso comum é ligar o período **sem contrato**, que cobre o parque todo), a troca passa e os sinais de itens fora do contrato novo saem do período — a tela diz quantos. Quando o contrato novo presta unidade que o antigo não prestava, a troca é recusada: os sinais dessa unidade foram para outro período ou recusados. Apague o período e abra de novo com o contrato; as plataformas reenviam, e reenviar não duplica.

3.     Na coluna **Avançar**, clique em **Congelar**, depois em **Apurar**, depois em **Consequências** e, se houver o que contestar, em **Contraditório**. Cada botão só acende no estado em que faz sentido; apagado, ele diz **O estado do período não permite esta ação agora** — ou, se o que falta é permissão, qual permissão falta.

4.     **Apagar** remove o período e o que foi calculado nele (base congelada, sinais, apuração, propostas), depois de uma confirmação. É o caminho para o período que foi congelado sem contrato: apague e abra de novo, já com o contrato. Período com decisão registrada não se apaga — decisão é ato da Administração, e o servidor recusa.

5.     A tabela mostra, por período, **Sinais**, **Apurados**, **Propostas** e a **Base congelada** (revisão e hash). A decisão é em **Decisões e travas**.

Abrir, ligar a contrato, apagar e conduzir o ciclo exigem `imr:operar`; sem ela os botões aparecem apagados, com o motivo.

Em **Exceções do ciclo**, abaixo, declare o que o cálculo precisa saber para não cobrar o que foi combinado. Escolha a aba — **Janelas de manutenção**, **Restrições da contratante** ou **Ocorrências abertas** —, clique em **declarar** (na aba de ocorrências, **registrar ocorrência**), preencha os campos (item, unidade ou localidade, início, fim, motivo; na janela, também **RFC** e **Aprovada por**; na ocorrência, **Item**, **Referência**, **Protocolo** e **Resumo**) e clique em **registrar**. Janela exige `imr:operar`; restrição exige `imr:decidir`, porque vira ARRC e afasta glosa.

**Quem registra ocorrência aberta.** A ocorrência aberta chega normalmente pela integração — é o Citsmart X que sabe o que está aberto, e a conta de integração (perfil **Integração do IMR**, com `imr:ingerir`) a envia sozinha. Registrar à mão existe para quando o conector ainda não está ligado, e é preparo do fechamento do mês, como declarar uma janela: por isso pede `imr:operar`, a permissão de quem conduz o ciclo. A rota aceita as duas (`imr:operar` ou `imr:ingerir`) e grava de onde veio: o que foi marcado à mão aparece com a fonte **manual**, e não como se tivesse vindo do conector. `imr:ingerir` continua fora dos perfis de pessoa — a separação entre ingerir e operar é o que impede a conta de integração de conduzir ciclo. Sem `imr:operar`, a aba mostra o botão apagado e explica por quê.

O registro à mão **nunca altera o que veio do conector**. Item, mês e protocolo identificam a ocorrência; se já existe uma com a mesma chave vinda do Citsmart X, registrar à mão é recusado e a mensagem diz de onde veio a existente — registre com outro protocolo, ou deixe que a integração a feche. O caminho inverso vale: o conector pode confirmar ou fechar o que foi marcado à mão, e a ocorrência passa a ser dele. O administrador, que tem as duas permissões, grava **manual** quando não diz a fonte. E a pessoa só registra ocorrência de item cadastrado em **Itens de configuração** e, se tiver acesso restrito por contrato, de item de um contrato que ela alcança.

**1. Abrir o período.** Referência AAAA-MM e o contrato — o período é por contrato, e a mesma referência se abre uma vez para cada um.

**2. Congelar a base.** O motor tira um retrato dos itens ativos e grava o **hash** do conteúdo ordenado. Depois disso, inclusão ou exclusão não altera o período: *não se move o poste depois do tiro*. Recongelar é possível e fica registrado como ato extraordinário — recongelamento silencioso apagaria a razão de existir do congelamento.

**3. Receber sinais.** Três dimensões por item: disponibilidade, registro e controle.

**4. Apurar.** As três dimensões decidem o estado:

| **Estado**     | **Pagamento** | **Quando**                                     |
| -------------- | ------------- | ---------------------------------------------- |
| conforme       | 100%          | as três dimensões OK, com evidência no canal   |
| NC leve        | 80%           | uma dimensão degradada                         |
| NC média       | 50%           | uma dimensão em falha, ou duas degradadas      |
| NC grave       | 20%           | duas falhas, ou uma falha em ativo crítico     |
| não governável | 0%            | sem sinal, ou evidência fora do canal pactuado |



**5. Propor consequências.** Chamada **separada** da apuração, e de propósito: apurar conformidade é seguro desde o primeiro dia, aplicar glosa e travar faturamento não. Poder operar meses sem chamar esta ação é o que permite calibrar limiar com dado real antes de ligar a consequência.

**6. Contraditório.** Fornecedores contestam com evidência.

**7. Decidir.** Ateste, glosa, ARRC, trava ou reabertura — sempre com autor e fundamento. Sem os dois, a transição é rejeitada.

***

### <font color="#15803D">O que o motor propõe, e nunca decide</font>

Na tela **IMR ▸ Decisões e travas** (decidir exige `imr:decidir`):

1.     Escolha o **Período**. Os cartões mostram **Contrato**, **Valor mensal**, **Glosa proposta** e **A atestar**.

2.     Revise **O que o motor propõe**. Para tirar uma proposta da conta, clique em **afastar**, escreva o **Fundamento — obrigatório** e **confirmar**. As afastadas ficam listadas logo abaixo, com **devolver à conta**.

3.     Em **Registrar o ato**, escolha o **Ato** — **ateste**, **glosa**, **ARRC**, **trava trilateral** ou **reabertura** —, escreva o fundamento e clique em **Registrar**.

4.     Em **Decisões registradas**, a decisão não se edita nem se apaga: **retificar** cria um ato novo que substitui o anterior e o deixa visível, marcado como retificado.

**Tempestividade**, no fim da tela, mede quantos dias cada decisão levou.

Cada regra do requisito vira uma proposta registrada, não um ato:

•     **Glosa por nexo** recai sobre o contrato responsável pela falha, e não sobre quem a reportou. Falha de controle imputa C3-SEC; de disponibilidade, C2-OPR; de medição, C1-GOV.

•     **Glosa por visibilidade** quando a evidência não é consultável no canal pactuado — e ela é **suprimida** quando há glosa por nexo sobre o mesmo fato. A supressão aparece na memória de cálculo: supressão silenciosa quebraria a auditabilidade.

•     **Trava trilateral** para item não governável sem ARRC deferida: suspende o faturamento nos **três contratos simultaneamente**. Travar um e faturar os outros é defeito de implementação.

•     **Inclusão remunerada** paga uma vez, com adicional; segunda instalação do mesmo item é bloqueada, não cobrada a menos.

•     **Teto de U7** corta o excedente e registra o corte.

Nenhuma delas vigora até alguém assinar.

***

### <font color="#15803D">Como as plataformas enviam dado</font>

Duas rotas, e o esquema é este — as plataformas se adaptam a ele. Um motor que aceita o formato de cada fornecedor acaba com um tradutor por fornecedor, e cada tradutor é um lugar onde a regra contratual pode ser distorcida sem ninguém ver.

*Os dois conectores*

O catálogo de integrações traz **CitSmart X** (ITSM) e **CitSmart Autonomous** (monitoração e descoberta), com logo próprio. A divisão de papéis é a do requisito e não é arbitrária:

| **Origem**          | **Dimensões**             | **O que ela sabe que a outra não sabe**      |
| ------------------- | ------------------------- | -------------------------------------------- |
| CitSmart Autonomous | disponibilidade, controle | o estado do ativo, e o inventário dele       |
| CitSmart X          | registro                  | se houve atendimento, e se ele saiu do prazo |



Um chamado fechado com SLA rompido é exatamente o fato que a dimensão de registro pede: houve atendimento — logo há registro — e ele saiu do prazo — logo o registro não é conforme. São os dois lados, e só o ITSM os conhece.

*O tenant vem do token, e de nenhum outro lugar*

A chave de serviço pertence a um tenant no momento em que é criada, e o token curto que ela gera carrega esse tenant como reivindicação assinada. Tudo o que a chamada grava entra nesse tenant e tudo o que ela lê sai dele. Mandar X-Tenant-Id, tenant na query ou qualquer variante não muda nada: os cabeçalhos são ignorados, e a política do banco não enxerga a aplicação. Para escrever noutro tenant é preciso outra chave, criada lá.

O perfil certo para essas plataformas é **\`INTEGRACAO\_IMR\`**, que tem `imr:ingerir` e `imr:ler` e nada mais: não conduz ciclo, não decide e não cadastra contrato. Ele foi criado porque o banco recusou — corretamente — dar permissão de escrita ao perfil de Monitoramento: aquele perfil tem token que não expira por inatividade, e credencial perpétua com poder de escrita, uma vez vazada, escreve para sempre.

O teste de segurança da cadeia verifica isso a cada execução: a chave escreve no tenant dela, nenhum cabeçalho troca o destino, item de outro tenant não aparece nem procurando pelo identificador exato, e as rotas de operar, contratar e administrar respondem 403.

**Inventário** — POST `/api/v1/imr/ingestao/ativos, permissão imr:ingerir:`

```javascript
[{
  "icId": "EP-IBAMA-DF-004821",
  "nome": "NB-IBAMA-4821",
  "enderecoIp": "10.12.4.21",
  "tipo": "ENDPOINT",
  "unidadeImr": "U1",
  "localidade": "Brasília DF",
  "criticidade": "ALTA",
  "fonte": "autonomous.edge-agent",
  "inventario": { "so": "Windows 11 23H2", "cpu": "i7-1265U", "memoria_gb": 16 }
}]
```

Nome e endereço bastam para o item existir. O resto do inventário entra livre em inventario e **acumula** entre as fontes: a descoberta de rede sabe o endereço, o agente sabe o hardware, o gerenciador sabe o software. Cada um conhece uma parte, e sobrescrever faria a última mensagem apagar as outras. É por isso que não há esquema fixo ali — o que uma plataforma de descoberta envia hoje não é o que ela envia no ano que vem.

**Sinal** — POST `/api/v1/imr/ingestao/sinais:`

```javascript
[{
  "icId": "EP-IBAMA-DF-004821",
  "referencia": "2026-09",
  "dimensao": "CONTROLE",
  "valor": "OK",
  "detalhe": { "edr": "ativo", "patch_sla": "dentro", "disco_cifrado": true },
  "fonte": "autonomous.edge-agent",
  "coletadoEm": "2026-09-30T23:58:04-03:00",
  "evidenciaUri": "evid://autonomous/2026-09/EP-004821.json",
  "evidenciaHash": "sha256:…",
  "canalPactuado": true
}]
```

Dimensões: DISPONIBILIDADE, REGISTRO, CONTROLE. Valores: OK, DEGRADADO, FALHA, DESCONHECIDO.

Três garantias da interface:

**Idempotência** por item, período, dimensão e instante de coleta. Reenviar o mesmo sinal não duplica.

**Lacuna declarada.** Quem não mediu envia DESCONHECIDO. Ausência silenciosa também nunca vira conformidade, mas declarar ajuda a distinguir "não medi" de "não chegou".

**Rejeição visível.** O que não passa fica na tela de Itens de configuração, com o motivo. Descartar em silêncio é a forma mais cara de perder dado, porque quem enviou acredita que chegou.

Sinal para período já apurado é recusado, e a mensagem diz o que fazer: ele entra no período seguinte com marcação de atraso. Aceitar ali reescreveria período já fechado.

**De qual contrato é o sinal.** O mês tem um período por contrato, e o sinal não diz o contrato: a plataforma descobre pelo item. O sinal entra em **todo período do mês cujo contrato presta a unidade do item** (uma atividade ativa naquela unidade) — no modelo trilateral, os três contratos que atendem a unidade recebem o mesmo sinal, porque cada um apura o próprio período. Período sem contrato, ou de contrato sem atividade cadastrada, cobre o parque todo, a mesma regra do congelamento da base. Quando nenhum período cobre o item — item ainda não inventariado, ou unidade que nenhum contrato presta —, o sinal só entra se o mês tiver **um período só**; com dois ou mais, ele é recusado e aparece em **Itens de configuração ▸ sinais rejeitados**, com o item, a unidade e os contratos do mês no motivo. Antes o sinal ia sempre para o período mais antigo do mês, e os outros contratos apuravam sem sinal — e sem sinal o item é não governável. A resposta traz aceitos (sinais que entraram), gravacoes (linhas novas, uma por período) e repetidos (reenvio do mesmo sinal, aceito e não gravado de novo); a recusa por estado do período é por período, e um contrato já apurado não impede o outro de receber.

**Depois do congelamento, vale a base.** Para período já congelado, quem decide se o item é dele é a **base congelada** (a última revisão), e não o cadastro de hoje. O item que muda de unidade depois do congelamento continua recebendo sinal no período em que ele está sendo apurado — sem isso, ele ficaria sem sinal ali e viraria não governável, glosa de 100% sobre um item que estava bem. E o item incluído depois do congelamento não entra no período congelado: não se move o poste depois do tiro. Item inativo no cadastro conta como não inventariado.

**Uma coisa de cada vez no mesmo período.** Congelar, apurar, ligar ou trocar o contrato e receber sinais travam o período enquanto agem: a segunda operação espera a primeira terminar e lê o estado já mudado. Assim o contrato não troca no meio de um congelamento (a base de um sustentaria a glosa de outro), e o sinal não entra no meio de uma apuração.

**Ocorrência aberta** — POST `/api/v1/imr/ocorrencias`, permissão `imr:ingerir` (a integração) ou `imr:operar` (quem registra à mão na tela Períodos): icId, referencia, protocolo, resumo, fechada e, opcional, fonte. A conta de integração pode dizer a própria fonte (sem dizer, fica citsmart); quem não tem `imr:ingerir` grava sempre manual, diga o pedido o que disser, e quem tem as duas sem dizer a fonte também grava manual. Registro manual que encontra, na mesma chave (item, mês, protocolo), uma ocorrência de outra fonte é recusado com 409 — a marcação à mão não fecha nem reescreve o que veio do conector.

***

### <font color="#15803D">Correlação por modelo de linguagem não entra aqui</font>

A plataforma tem um motor de correlação por LLM, e ele **não toca** em estado de conformidade. O requisito é taxativo e a decisão é acertada: um valor faturado não pode depender de inferência probabilística. Correlação é insumo de priorização e de investigação; estado de conformidade é regra determinística, e por isso a apuração é reexecutável e produz o mesmo resultado.

***

### <font color="#15803D">Painéis do IMR</font>

Dois painéis publicados, porque são duas perguntas feitas em momentos diferentes:

**IMR — faturamento e glosa** responde a pergunta do fechamento: quanto foi apurado, quanto se propõe glosar, e onde a glosa se concentra — por contrato, por unidade e por atividade.

**IMR — conformidade e nexo** responde a pergunta de quem vai tratar: onde a falha está, de quem é o nexo, e o que o motor propôs como consequência.

As três fontes do construtor — apuração, consequências e itens de configuração — são registradas pelo próprio módulo do IMR, e não escritas no catálogo comum. Numa instalação privada que nunca rodou a migração do IMR, o catálogo comum citando imr.apuracao faria a plataforma **falhar ao iniciar**, porque ele é conferido contra o banco na subida.

Uma regra atravessa todas as consultas: **só a revisão vigente**. A apuração é append-only, e um painel que somasse todas contaria o mesmo item duas vezes e mostraria glosa maior que a proposta. Ninguém desconfia de um número num painel.

***

### <font color="#15803D">Simular as origens no Sandbox</font>

Em **Automação ▸ Sandbox** há um bloco **Origens do IMR** — visível só onde o módulo está ligado — que dispara as duas plataformas pelo mesmo caminho de ingestão que elas usariam de verdade, com validação, idempotência e rejeição visível. Um simulador que grava direto na tabela prova que a tabela aceita o dado, que é a parte que nunca falhou.

Escolha o **Período de destino** (é preciso ter um período aberto), **Quantos ativos** e, se quiser ver a glosa, marque **Incluir uma falha**. Depois clique em **Disparar CitSmart Autonomous**, **Disparar CitSmart X — SLA rompido** e **Reapurar o período**; o resultado mostra a base rateada e a glosa proposta. Disparar exige `imr:operar`.

A separação entre as duas é o ponto: dispare só o **Autonomous** e todos os itens ficam sem a dimensão de registro, logo nenhum é conforme. É a conformidade tripla funcionando, e vê-la falhar ensina mais do que qualquer texto sobre ela.

***

### <font color="#15803D">Parâmetro geral e parâmetro de contrato</font>

Na tela **IMR ▸ Parâmetros do ANS** (definir exige `imr:decidir`):

1.     Escolha a aba: **Regra padrão** (vale para todo contrato sem valor próprio) ou **Pactuado por contrato**. Nesta, escolha o **Contrato**; com **Todos — mostre onde se combinou diferente**, a tela lista só o que cada contrato pactuou fora do padrão.

2.     No parâmetro, clique em **alterar**, informe o **Valor** (dentro da faixa mostrada), **Vigente de** e **Por quê** (o ato que fixou o valor), e clique em **Definir**.

3.     Para desfazer, use **voltar ao padrão do requisito** (na regra padrão) ou **voltar ao geral** (no contrato).

4.     Em **Calendário de prazos**, escolha o ano e use **Acrescentar feriado local** — **Data**, **Nome**, **Tipo**, **Abrangência**, **UF**, **Município** — e **Acrescentar**. Os de fábrica não se removem. **remover**, no feriado local, pergunta antes: a data volta a contar como dia útil, e os prazos que passam por ela terminam um dia antes.

O **Histórico de vigências** mostra cada valor definido, desde quando e por quem.

Cada parâmetro pode valer para a instalação inteira ou só para um contrato, e o do contrato vence o geral. A tela de parâmetros tem um seletor de escopo e **diz de onde o valor em vigor veio** — sem isso alguém altera o geral esperando mudar um contrato que tem valor próprio, e o número não se move sem explicação.

Vigência não retroage nem antecipa: um valor com data futura não aparece como vigente, e período já apurado continua com o que valia quando foi apurado.

***

### <font color="#15803D">O que ainda depende da Administração</font>

Os limiares que separam leve, média e grave; a proporcionalidade para item com vigência parcial no período; os percentuais de glosa por visibilidade; o critério objetivo de ARRC; e os prazos de contraditório e de decisão.

Nada disso bloqueia o uso. Todos são **parâmetros versionados por período** — o motor apura com os padrões do requisito e registra tudo, o que permite operar em modo sombra e calibrar com dado real antes de ligar a consequência financeira.

[title] 25. Catálogo de serviços e política de atendimento
[path] Aplicações/GRCS/

*O que se pode pedir — com os serviços e artigos de GRC que todo tenant recebe —, e o que a organização promete sobre cada pedido: prazos por prioridade, escalonamento, matriz e avisos.*

Duas telas, uma pergunta. O **catálogo** responde *o que dá para pedir*; a **política** responde *o que a organização promete sobre o que foi pedido*. Separadas, cada uma cabe na cabeça de quem a mantém: o catálogo é do dono do serviço, a política é de quem responde pelo atendimento.

***

### <font color="#15803D">O catálogo tem quatro níveis</font>

Serviço → Categoria → Subcategoria → Item. O item é o que a pessoa escolhe no portal, e é ele que carrega o que a abertura precisa saber: **tipo de caso** (incidente, requisição, problema, incidente maior, ocorrência), **fila** que recebe e **política** que vale. Os três níveis de cima só organizam.

Para montar, em **Catálogo de serviços** (mexer pede a permissão de administrar casos):

1.     Clique em **Novo serviço**, preencha **Código**, **Nome** e **Descrição** e clique em **Gravar**.

2.     Na linha do serviço, clique em **+ categoria**; na da categoria, em **+ subcategoria**; na da subcategoria, em **+ item**. A seta à esquerda abre e fecha cada galho.

3.     No item, escolha o **Tipo de caso**, o **Acordo de nível de serviço** (a política) e a **Fila que atende**. **Aparece no portal** decide se o colaborador o vê. Clique em **Gravar**.

4.     O lápis edita; a lixeira pergunta antes de apagar, com o foco no **Cancelar** e o **Esc** para desistir — só **Excluir** apaga.

Apagar é recusado enquanto o nó tiver filhos, ou, no item, chamados abertos a partir dele — nesse caso, desmarque **Ativo**. A pergunta já avisa quando a recusa vai acontecer, com o número. O topo da tela conta os itens **sem acordo de nível de serviço**: chamado aberto por eles nasce sem prazo.

A árvore de quem monta mostra **o galho vazio**. Um serviço recém-criado ainda não tem categoria, e uma consulta com JOIN o faria sumir da própria tela em que acabou de nascer — o que se parece exatamente com "a gravação não funcionou". Quem escolhe um item, no portal, vê só o que está publicado e completo; são consultas diferentes porque são perguntas diferentes.

***

### <font color="#15803D">O que todo tenant recebe de fábrica</font>

Todo tenant nasce com um catálogo de serviços de GRC no portal de atendimento e uma base de conhecimento para as dúvidas de quem é auditado. Os dois foram montados a partir dos frameworks e das perguntas do catálogo de normas.

*Os serviços*

| **Serviço**                     | **Exemplos de itens**                                                                                                                                                  |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Auditorias e avaliações         | tirar dúvida sobre uma pergunta, pedir prorrogação de prazo, pedir reabertura de resposta, enviar evidência complementar, incluir ou retirar alvo, solicitar auditoria |
| Achados e planos de ação        | contestar um achado, prorrogar ação do plano, informar conclusão de ação, apoio para montar o plano, pedir aceite formal de risco                                      |
| Riscos e continuidade           | registrar risco, revisar avaliação, reportar interrupção, apoio para BIA e teste do plano                                                                              |
| Políticas e documentos          | dúvida sobre política, pedir exceção, comunicar descumprimento, sugerir revisão, pedir publicação                                                                      |
| Privacidade e proteção de dados | pedido de titular (LGPD), incidente com dado pessoal, relatório de impacto, dúvida sobre tratamento                                                                    |
| Segurança da informação         | incidente de segurança, e-mail ou mensagem suspeita                                                                                                                    |
| Acesso à plataforma GRC         | pedir acesso ou perfil, pedir treinamento, relatar problema                                                                                                            |

São 29 itens, cada um com o formulário do que o atendimento precisa saber e a fila certa (Auditoria, Riscos, Conformidade, Privacidade, Segurança ou Plataforma). Campos que só fazem sentido numa situação aparecem só nela.

*A base de conhecimento*

São 25 artigos (KB-2026-001 a KB-2026-025), publicados no espaço Conhecimento: o que conta como evidência, quando responder "não se aplica", prazos e prorrogação, o que acontece depois da resposta, como contestar um achado, como montar e comprovar um plano de ação, aceite de risco, leitura obrigatória, análise de aderência, exceção a política e artigos por tema (controle de acesso, backup, incidentes e fornecedores na ISO/IEC 27001; bases legais, direitos do titular, incidentes e relatório de impacto na LGPD; BIA e testes na ISO 22301; as cláusulas comuns dos sistemas de gestão). Os artigos citam os identificadores reais do catálogo (A.8.13, Art.18, Cl.8.4…).

Cada artigo está ligado aos itens do catálogo a que responde: o portal mostra o artigo **antes** do formulário, e o **Pergunte à base** usa os artigos para responder, citando a fonte.

*Editar sem perder*

O catálogo e os artigos de fábrica são do tenant: pode editar, trocar a fila, tirar campos ou apagar. A semente não volta a criar o que foi apagado nem sobrescreve o que foi editado; um item ou artigo do próprio tenant com o mesmo código ou título fica como está.

***

### <font color="#15803D">Políticas de atendimento — criar e configurar o SLA</font>

Em **Políticas de atendimento** (mexer pede a permissão de administrar casos):

1.     Clique em **Nova política**. Preencha **Código** (não muda depois), **Nome** e **Vale para** — *qualquer tipo de chamado* ou um dos tipos de caso da plataforma: **Incidente**, **Requisição**, **Problema**, **Incidente maior** ou **Ocorrência** (os mesmos do catálogo de serviços).

2.     Marque os relógios que a política tem — **Primeira resposta**, **Atribuição**, **Atualização**, **Contorno**, **Resolução** — e dê a cada um os **Minutos** e o **Calendário**.

3.     Para um prazo diferente por prioridade, clique em **Desdobrar por prioridade** no relógio; **Um prazo para todas** junta de novo. Clique em **Gravar**.

4.     Na política gravada, cada parte tem o seu botão (**Configurar** quando vazia, **Editar** quando não):

◦      **Escalonamento**: **+ Degrau**, e em cada degrau **Prioridade**, **Degrau**, **% do prazo**, **Chama** (e a **Equipe**, se for um grupo) e **Por**. Clique em **Gravar escalonamento**.

◦      **Matriz de prioridade**: escolha a prioridade de cada cruzamento de impacto e urgência e clique em **Gravar matriz**. Cruzamento em branco cai na regra geral da instalação.

◦      **Avisos**: marque as regras que obedecem à política e clique em **Gravar avisos**.

5.     **Editar prazos** reabre os relógios. A lixeira pergunta antes de apagar — **Excluir política de atendimento “…”?**, com o que sai e quantos itens do catálogo apontam para ela; confirme em **Excluir** ou volte em **Cancelar**.

Política **de fábrica** não se edita: **Adotar e editar** cria a sua cópia, com tudo dentro. O item do **Catálogo de serviços** é que diz qual política vale para o chamado aberto por ele.

Até a versão anterior, **Vale para** oferecia *mudança*, que não é tipo de caso na plataforma — a política gravava e nunca valia para chamado nenhum. Na atualização, as políticas que valiam para mudança ficaram **inativas**, sem tipo, com o nome terminado em *(valia para mudanca, tipo de caso que não existe)* e a marca **inativa**: elas não valiam para nada e continuam não valendo. Para reaproveitar uma, clique em **Editar prazos**, escolha um tipo em **Vale para**, marque **Ativa** e clique em **Gravar**; senão, exclua.

***

### <font color="#15803D">A política agrupa, e a prioridade é dimensão do prazo</font>

Esta foi uma correção de desenho, e a conta que a motivou veio de quem usa: *"se eu tiver 5 serviços terei que criar 25 itens da forma que está na tela, e não 5 SLAs com as regras de cada um"*.

Antes, a prioridade era a própria política: existia uma linha para "Global P1", outra para "Global P2", e assim por diante. Cinco serviços com quatro prioridades pediam vinte cadastros quase idênticos, e mudar o calendário de todos significava abrir os vinte.

Agora a prioridade é **dimensão do prazo, dentro da política**. Uma política chamada Incidente diz, num lugar só, quanto tempo tem a primeira resposta de um P1 e a resolução de um P4. Onde a diferença não existe, um prazo só vale para todas — e "Desdobrar por prioridade" transforma esse prazo em quatro já preenchidos com o valor que estava lá, para que diferenciar não seja recomeçar.

*Os cinco relógios*

***

| **Relógio**       | **O que mede**                                      |
| ----------------- | --------------------------------------------------- |
| Primeira resposta | quanto tempo até alguém falar com quem abriu        |
| Atribuição        | quanto tempo até o chamado ter dono                 |
| Atualização       | de quanto em quanto tempo quem abriu recebe notícia |
| Contorno          | quanto tempo até existir uma saída provisória       |
| Resolução         | quanto tempo até o problema acabar                  |

Cada um corre sozinho. Um SLA único de resolução esconde o que o solicitante sente primeiro: **o silêncio**.

A gravação recusa o que só apareceria semanas depois — resolução antes da primeira resposta, ou contorno depois da resolução. A conferência é **por prioridade**: resolução de P1 em duas horas e primeira resposta de P4 em oito não são incoerentes entre si, e compará-las recusaria uma política correta.

***

### <font color="#15803D">O que mais mora dentro da política</font>

A política não é só prazo. Dentro dela também ficam:

•     **Escalonamento** — quem é chamado quando o relógio aperta, por prioridade e por degrau. O percentual passa de 100 de propósito: o degrau aos 150% é o que aciona quem precisa saber que o prazo **já** estourou.

•     **Matriz de prioridade** — traduz o que o solicitante sabe dizer, impacto e urgência, na prioridade que o relógio usa. É por política porque um incidente e uma requisição não classificam igual, e uma matriz única obrigaria a escolher qual dos dois fica errado.

•     **Avisos** — as regras que obedecem a esta política. O vínculo é feito aqui; **a condição continua sendo escrita em Regras de atendimento**, com o construtor inteiro. Dois editores para a mesma coisa criariam duas gramáticas, e a que ficasse para trás passaria a recusar o que a outra aceita.

Cada seção se edita no lugar em que aparece. Um formulário único, com tudo dentro, obrigaria a percorrer prazos e matriz para mexer num degrau — e faria um engano em qualquer campo derrubar a gravação inteira.

***

### <font color="#15803D">Seção vazia continua aparecendo</font>

E diz **quantos valem no lugar dela**. Uma política sem degrau próprio não deixa ninguém sem socorro: o escalonamento global continua valendo, e a tela escreve isso. Sem esse número, quem administra leria "nada configurado", concluiria que ninguém é chamado, e cadastraria um degrau duplicado para consertar o que não estava quebrado.

***

### <font color="#15803D">As políticas de fábrica não se alteram</font>

Elas são o piso de toda instalação. **Adotar e editar** cria uma cópia sua com tudo dentro — prazos, degraus, matriz e avisos — e a de fábrica fica intacta. Sem esse caminho, a única saída seria montar a sua do zero, repetindo o que já estava ali.

Pela mesma razão, uma **regra de fábrica** não entra numa política: ela já vale para todo chamado e não pertence a nenhuma. Vincular uma delas é recusado com o motivo, em vez de aceito em silêncio — aceitar e não fazer nada faria a tela dizer "gravado" e voltar sem o aviso.

***

### <font color="#15803D">Isto não é o IMR</font>

As duas coisas medem tempo, e param aí. O **acordo de atendimento** é o prazo de um chamado. O **IMR** é o instrumento de medição de um contrato, e o que ele apura vira glosa. Um é operação, o outro é dinheiro; amarrar os dois faria toda demora de atendimento virar desconto de fatura sem ninguém ter decidido isso.

[title] Criar novo Usuário
[path] Início Rápido/🌐Gestão de Pessoas/Usuários/

Para criar um novo usuário, acesse a página de [Usuários](docId:0ic0SPuQMpGve2LnURycp) e clique no botão **+Usuário&#x20;**&#x70;ara criar um usuário único, ou **+Usuários em Lote&#x20;**&#x70;ara cadastrar vários usuários ao mesmo tempo.



::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/TCTKSmZKiSdmtYZ0jYJV2_image.png" size="40" width="258" height="54" position="center" showCaption="false"}

## +Usuário

O botão de +Usuário exibe uma tela com as informações do usuário a ser criado:

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/sPxoX51e4Vsr9SU66VEvS_image.png)

Inclua as informações de identificação de **Nome&#x20;**&#x65; **Sobrenome,&#x20;**&#x6F; **Email&#x20;**&#x65; o nome de **Usuário.&#x20;**&#x4F; nome de usuário será usado para acessar a plataforma, e o email será o principal ponto de contato externo com o usuário.

Ao centro, selecione na caixa o tipo de sessão do usuário: **Permanente**, **Concorrente**, **Administrador&#x20;**&#x65; **Ilimitado**. O tipo de sessão influencia no tipo de acesso que o usuário terá ao sistema.

Na parte de baixo, marque a caixa de **Ativo&#x20;**&#x70;ara ativar o usuário.&#x20;

A caixa de **Senha Padrão?**, quando marcada, cria o acesso usando a senha padrão do sistema, exibida ao lado. Ao realizar o acesso pela primeira vez, será requisitado ao usuário que escolha uma nova senha. Marcar esta caixa automaticamente desabilita a opção de senha temporária.

:::hint{type="info"}
🚨 A senha padrão será sempre Mudar-123
:::



A caixa de **Senha temporaria?&#x20;**&#x70;ermite que uma senha padrão personalizada seja definida no campo ao lado. Ao realizar o acesso pela primeira vez, será requisitado ao usuário que escolha uma nova senha. Este campo só pode ser alterado caso a opção de Senha padrão esteja desabilitada.

Após incluir as informações desejadas, selecione **Cadastrar&#x20;**&#x70;ara criar o novo usuário ou **Fechar&#x20;**&#x70;ara cancelar e voltar para a tela anterior.

## +Usuários em lote

Na lista de usuários, o botão de **+Usuários em lote&#x20;**&#x70;ermite que uma lista de usuários seja importada para o cadastro de múltiplos usuários.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/SQ4KjTUGUpk7I4qo6Cpb8_image.png)

A tela exibida define o modelo usado para importar usuários. É necessário fazer o upload de uma lista no formato **CSV&#x20;**&#x73;eguindo o padrão exibido. É possível baixar um arquivo de exemplo ao clicar no botão **Baixar Modelo&#x20;**&#x61;baixo da caixa.

As observações definem alguns parâmetros que devem ser seguidos ao fazer o upload da lista.

Abaixo das observações, clique no botão para navegar em sua máquina e selecionar um arquivo compatível para o upload.&#x20;

Após selecionar um arquivo, a lista abaixo será atualizada com os novos usuários.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/3LLfLOckUS-PNlL3UN4B4_image.png)

Para concluir a criação, clique em **Importar Usuários&#x20;**&#x61;o lado direito, ou clique em **Fechar&#x20;**&#x6E;a parte de baixo da tela para cancelar e voltar para a tela anterior.

[space] Infraestrutura (/admin)

[title] Manual de utilização do aplicativo mobile CITSmart Experience
[path] Administração da Plataforma/Mobile/

Este documento tem o propósito de fornecer orientações necessárias para instalar, configurar e utilizar o aplicativo mobile CITSmart Experience, disponível nas plataformas Android e iOS.

O aplicativo Experience oferece a facilidade no atendimento, direcionamento de onde a solicitação está localizada, filtragem das solicitações pessoais e por grupo de trabalho, visualização dos detalhes de uma solicitação de serviço, acesso a base de conhecimento, entre diversas outras funcionalidades possíveis devido a renderização das páginas e layout responsivo. Em resumo, é possível realizar no aplicativo mobile todas as atividades feitas na versão web.&#x20;

## Antes de começar

- [x] Para utilizar o aplicativo Experience é preciso criar o menu com as opções que poderão ser acessadas.

## Procedimento

1. Instalar o aplicativo Experience nativamente a partir da sua loja online (App Store ou Play Store);
2. Clicar em "**Connections**":
3. O sistema abrirá a tela de Configuração da Conexão:
4. Caso exista alguma configuração cadastrada o usuário poderá editá-la;
5. Para criar uma conexão, clicar no botão “+”;
6. Será apresentada tela “**Nova Conexão**” para registrar conexão:
7. Após informar os dados da conexão desejada, clicar no botão "**Salvar**";
8. Depois de adicionada a conexão, aparecerá a listagem das conexões criadas. Para alterar uma conexão, basta selecionar e manter pressionada a conexão e fazer a alteração;
9. Logar com o usuário e senha utilizados no CITSmart web;
10. Após realizar a conexão, será apresentada a tela com menus de funcionalidades disponíveis.

:::hint{type="danger"}
**Atenção:** Caso o aparelho seja trocado, esta conexão deve ser deletado.
:::


[title] Parametrização - LDAP
[path] Administração da Plataforma/Untitled/

Ao contrário dos demais parâmetros do produto, esta configuração de parâmetros ligados à integração com o LDAP ocorre de uma forma implícita usando a funcionalidade Configuração LDAP ou de forma explícita usando a funcionalidade Parâmetros do CITSmart.

## Procedimento

1. Acessar a funcionalidade através da navegação no menu principal `Parametrização > Parâmetros CITSmart;`
2. Definir o valor do parâmetro a ser configurado;
3. Efetuar a mudança;
4. Clicar no botão "**Gravar**";
5. A lista abaixo apresenta os parâmetros da funcionalidade e a finalidade de cada um deles:

| #   | Nome                                                                                            | Valores possíveis | Finalidade                                                                                                     | Orientações complementares                                                                                                                                                                                                                                                                                        |
| --- | ----------------------------------------------------------------------------------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 39  | LDAP - ID do perfil de acesso que será setado automaticamente caso o usuário não possua nenhum. | Ex: 2             | Informar o número de identificação (ID) do Perfil de Acesso padrão para o usuário.                             | Ao cadastrar um usuário e caso não seja informado o perfil de acesso, quando o mesmo realizar login na aplicação, será estabelecido o perfil de acesso (definido no valor do parâmetro). Essa regra vale para os usuários importados do AD. Esse ID do Perfil de Acesso é definido na tela de “Perfil de Acesso”. |
| 45  | LDAP - ID Grupo Padrão                                                                          | Ex:123            | Informar o número de identificação (ID) do grupo padrão, ao qual os usuários do AD serão associados            | Esse ID do grupo é definido na tela de "Cadastro de Grupo".                                                                                                                                                                                                                                                       |
| 409 | LDAP - Atributo que representa o superior imediato do usuário                                   | Ex: Maria         | Nome do superior imediato do usuário no LDAP para que se consiga recuperar essa informação pelo AD do cliente. | Para poder usar em casos de aprovação de um ticket por exemplo                                                                                                                                                                                                                                                    |

Tabela 1 - Tabela de parâmetros


[title] Configurar Conta de E-mail
[path] Administração da Plataforma/

Este documento tem como objetivo apresentar um passo-a-passo da configuração de e-mail no CITSmart Platform, através da leitura (IMAP) e envio (SMTP) de mensagens.

## Antes de começar

Obtenha as informações de e-mail e configure as permissões de acesso ao servidor de e-mail.

## Procedimento

1\. Acessar o menu principal `Parametrização > E-mail `&#x20;

### Configurar o SMTP

| ID  | Descrição                            | Exemplo              |
| --- | ------------------------------------ | -------------------- |
| 10  | Endereço de email da organização     | empresa\@exemplo.com |
| 11  | Requer autenticação                  | Sim                  |
| 12  | Endereço do e-mail                   | seu.email\@gmail.com |
| 13  | Senha                                | Sua senha do Gmail   |
| 14  | Servidor para envio de e-mail (SMTP) | smtp.gmail.com       |
| 199 | Requer TLS/SSL                       | Sim                  |
| 269 | Porta                                | 587                  |

### Configurar IMAP

| ID<br />Descrição<br />Exemplo | Descrição                                              | Exemplo              |
| ------------------------------ | ------------------------------------------------------ | -------------------- |
| 23                             | Servidor para receber e-mails (IMAP)                   | imap.gmail.com       |
| 24                             | Endereço do e-mail                                     | seu.email\@gmail.com |
| 25                             | Senha                                                  | Sua senha do Gmail   |
| 26                             | Protocolo (imaps, pop, etc.)                           | imaps                |
| 27                             | Porta                                                  | 993                  |
| 28                             | Caixa de e-mail                                        | inbox                |
| 72                             | Número de mensagens carregadas                         | 10                   |
| 199                            | Requer TLS/SSL<br />Requer TLS/SSL<br />Requer TLS/SSL | Sim                  |


[title] Configurar Caixa de E-mail
[path] Administração da Plataforma/Untitled/

Como uma plataforma ominichannel, o CITSmart conecta com múltiplos canais de comunicação. A variedade se apresenta tanto nos tipos e formatos dos canais, como em sua quantidade. Desta maneira, o CITSmart habilita o uso simultâneo e conectado de diversos canais de comunicação facilitando o contato entre provedor e consumidor de serviços.

Dentre as opções de comunicação, o e-mail é uma das formas mais ativas e populares. O CITSmart é capaz de realizar o envio e o recebimento de e-mail a partir de diversas contas diferentes, mesmo que estejam em servidores de correio eletrônico separados. Assim, o fluxo de informação pode ser construído para atender as necessidades de negócio.

Por exemplo: Configurar uma conta de e-mail diferente para cada contrato gerenciado pelo CITSmart, onde cada caixa-postal está hospedada no servidor de correio eletrônico do cliente correspondente.

Nesta configuração, temos as seguintes vantagens:

- Facilita-se a comunicação com os clientes através do uso de um endereço de e-mail familiar à sua organização.
- Reduz-se o impacto de indisponibilidade na comunicação já que a perda de acesso a um servidor afeta apenas o contrato relacionado.
- As mensagens ficam adequadamente armazenadas e agrupadas por contrato.

## Procedimento para registro de caixa de e-mail

- Acessar a funcionalidade através `Menu de Navegação > Parametrização > Caixa de e-mail;`
- Clicar no botão "**Novo**";
- Preencher o campo de “Descrição” para identificar a conexão de e-mail;
- Escolher o tipo de caixa de e-mail. Cada um tem um propósito diferente, a saber:

1. O tipo "Entrada" significa que os e-mails que chegarem na caixa de e-mail especificada serão lidos e processados. Utilize essa opção para indicar por onde as mensagens dos usuários chegarão.&#x20;
   Neste caso, serão abertos novos campos cadastrais, tais como:
   &#x20;       \- Servidor (endereço do host ou IP do servidor);
   &#x20;       \- Porta do servidor (Porta de conexão);
   &#x20;       \- Usuário (Endereço do e-mail);
   &#x20;       \- Senha de conexão;
   &#x20;       \- Provider (Protocolo de conexão, podendo ser imaps, pops, imap ou pop);
   &#x20;       \- Pasta da caixa de entrada onde os e-mails estarão armazenados (Geralmente é inbox).

2. O tipo "Saída" indica a conexão que será utilizada pelo CITSmart para o envio de e-mails originados por ações do sistema. Por exemplo: confirmação da abertura de uma requisição, pedido de aprovação ou a conclusão de um atendimento.&#x20;
   &#x20;   Neste caso, serão abertos novos campos cadastrais, tais como:    &#x20;
   &#x20;       \- Servidor (endereço do host ou IP do servidor);
   &#x20;       \- Porta do servidor (Porta de conexão - geralmente o valor é 25);
   &#x20;       \- Remetente (Identificação que será apresentada ao destinatário);
   &#x20;       \- Indicar se é requerida a autenticação segura do tipo TSL/SSL;
   &#x20;       \- Indicar se é requerida a autenticação do usuário de conexão. Caso seja, será exigido o preenchimento dos campos correspondentes de usuário e senha.

- Clicar no botão "**Gravar**" para efetuar a operação.

## Procedimento para vincular uma caixa de e-mail a um contrato

Caso deseje vincular uma das caixas de e-mail registradas anteriormente a um contrato, siga o procedimento:

1. Acessar o `Menu de Navegação > Processos > Gerência de Portfólio e Catálogo > Contrato;`
2. Então vincular no campo Caixa de E-mail de Saída a caixa de e-mail desejada. A caixa postal precisa estar previamente cadastrada;
3. Clicar no botão "**Gravar**" para efetuar a operação.

## Procedimento para vincular uma caixa de e-mail a um fluxo de trabalho

Caso deseje vincular uma caixa de e-mail a um fluxo de trabalho, siga o procedimento abaixo:

- Acessar o `Menu de Navegação > Tracker > Desenho de Fluxo;`
- Ao criar ou editar um fluxo, localize na aba "**Diagrama**". Inclua ou edite um conector do tipo "**Envio de mensagem - email**";
- Na aba “**Mensagem**”, no campo "Configuração da caixa de saída de e-mail" existem 2 opções:

1. Escolha a opção “**Contrato**” para que o componente utilize a caixa de e-mail indicada no contrato relacionado ao fluxo.
2. Escolha a opção “**Específica**” para fazer a indicação da caixa de e-mail desejada.

- Concluir a parametrização do envio de e-mail indicando na aba "**Destinatários**", os usuários ou grupos que serão os receptores das mensagens;
- Clicar no botão "**Gravar**" para efetuar a operação.

:::hint{type="warning"}
**Atenção:** Por padrão, todo fluxo utiliza primariamente a caixa de e-mail de saída do sistema. Portanto, só é necessário indicar uma caixa de e-mail específica se for preciso satisfazer um requisito particular de um fluxo de trabalho.
:::


[title] Verificar o posicionamento dos atendentes
[path] Administração da Plataforma/Mobile/

Esta funcionalidade tem por objetivo verificar o posicionamento dos técnicos, ou seja, a localização atual dos técnicos de campo, responsáveis pelo atendimento das solicitações de serviço.

Nesta tela, poderá visualizar a localização do(s) técnicos(s) no mapa de acordo com os filtros informados.

## Antes de começar

- [x] É necessário configurar a conexão do sistema com as API's do Google.

## Procedimento

1. Acessar a funcionalidade através da navegação no menu principal `Gestão Integrada > Gerência de Força de Atendimento > Posicionamento dos Atendentes;`
2. Definir os filtros conforme a necessidade e clicar no botão "**Pesquisar**";
3. Serão exibidos no mapa os pontos de localização dos técnicos. Clicar, então, no ponto de localização do técnico para verificar as informações referentes ao atendimento da solicitação de serviço.


[title] Incidentes/requisições/procedimentos
[path] Administração da Plataforma/Automatização /Cadastrar ação automática/

Alguns eventos irão apresentar uma situação onde a ação apropriada precisará ser tratada pelo processo de gerenciamento de incidentes, ou seja, esta funcionalidade tem como objetivo realizar o cadastro de ações automáticas do tipo incidente/requisição/procedimento. Este cadastro será associado às ações automáticas, onde será usado nos cadastros de gerentes de eventos do CITSmart Nagios, Zabbix, Inventory e Eventos Correlacionados.

O gerenciamento de eventos apoia o processo de gerenciamento de incidentes, pois a partir dele é possível detectar com antecedência falhas nos serviços e atuar rapidamente para evitar uma indisponibilidade do serviço para o usuário final.

Esta funcionalidade disponibiliza ações diversas, tais como, incluir, alterar e excluir ações automáticas do tipo incidente/requisição/procedimento.

## Antes de começar

- [x] Para realizar o cadastro de uma ação automática de requisição/incidente/procedimento é necessário registrar previamente a unidade, o grupo, o contrato, vincular grupo aos contratos, associando os solicitantes (colaboradores) já relacionado a este grupo, para que sejam listados os contratos e os solicitantes relacionados na tela de solicitação, definir o portfólio de serviços, o tempo de atendimento e o grupo de atividade periódica.

## Procedimento

1. Acessar a funcionalidade através da navegação no menu principal `Sistema > Ações Automáticas > Ações de Incidentes/Requisições/Procedimentos;`
2. Preencher os campos disponibilizados;
3. Clicar em "**Gravar**".


[title] Parametrização - Sistema
[path] Administração da Plataforma/Untitled/

A parametrização do "Sistema" é utilizada para alterar características no que tange trocar a forma de autenticação no sistema, informar a URL do sistema, informar os diretórios diversos (GED, Log, Temporários), definir a página inicial, validar as permissões de botões (gravar, excluir e pesquisar), ativar o log do sistema (auditoria), definir preferências de idioma, dentre outras ações.

## Procedimento

1. Acessar a funcionalidade através da navegação no menu principal **Parametrização > Sistema;**
2. Definir os valores dos parâmetros (atributos);
3. Clicar no botão "**Gravar**" para efetuar a operação;
4. A lista abaixo representa os parâmetros do "**Sistema**" e a finalidade de cada um deles:

<table columnWidths="99,513,169,169" selectedRows="" selectedTable="false" isTableHeaderOn="true" selectedColumns="">
  <tr>
    <td align="left">
      <p><strong>#</strong></p>
    </td>
    <td align="left">
      <p><strong>Nome</strong></p>
    </td>
    <td align="left">
      <p><strong>Finalidade</strong></p>
    </td>
    <td align="left">
      <p><strong>Observação</strong></p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><strong>0</strong></p>
    </td>
    <td align="left">
      <p>ORIGEM - Configuração de Origem de Informações (para federação de dados) - (Ex: 0)</p>
    </td>
    <td align="left">
      <p>Configuração de Origem de Informações (para federação de dados).</p>
    </td>
    <td align="left">
      <p>Caso não informe o valor do parâmetro, não será possível realizar a exportação do CMDB (Banco de Dados do Gerenciamento de Configuração) na tela de “Gerenciamento de Itens de Configuração”.</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><strong>15</strong></p>
    </td>
    <td align="left">
      <p>GED Interno (Ex: S ou N)</p>
    </td>
    <td align="left">
      <p>Informar se o GED (Gerenciamento Eletrônico de Documento) utilizado é interno. Obs.: Atualmente a única forma de utilizar o GED é de forma interna. Ao definir 'S' para o GED Interno, o sistema irá criar a pasta definida pelo parâmetro 18 e irá criar uma subpasta com a identificação da empresa e uma outra subpasta chamada “A”. Os arquivos GED serão gravados nessas pastas.</p>
    </td>
    <td align="left">
      <p>Caso seja informado o valor 'N' para o GED Interno, os arquivos não serão salvos corretamente, não serão salvos no local correto e não será feita a criptografia dos mesmos.</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><strong>16</strong></p>
    </td>
    <td align="left">
      <p>GED Interno em Banco de Dados(Ex: S ou N)</p>
    </td>
    <td align="left">
      <p>Informar se o GED (Gerenciamento Eletrônico de Documento) utilizado é interno em Banco de Dados.</p>
    </td>
    <td align="left">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><strong>17</strong></p>
    </td>
    <td align="left">
      <p>GED Externo - Classe de tratamento</p>
    </td>
    <td align="left">
      <p>Informar a classe do GED externo (Gerenciamento Eletrônico de Documento).</p>
    </td>
    <td align="left">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><strong>18</strong></p>
    </td>
    <td align="left">
      <p>GED Diretório (Ex: Windows –C:/gedCitsmart)</p>
    </td>
    <td align="left">
      <p>Definir o diretório para manipulação dos arquivos do GED (Gerenciamento Eletrônico de Documento).</p>
    </td>
    <td align="left">
      <p>Caso não informe o diretório GED, não irá funcionar a gestão eletrônica de documentos, pois a mesma utiliza o diretório para criptografia dos arquivos.</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><strong>19</strong></p>
    </td>
    <td align="left">
      <p>Nome da Empresa</p>
    </td>
    <td align="left">
      <p>Informar o nome da empresa.</p>
    </td>
    <td align="left">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><strong>22</strong></p>
    </td>
    <td align="left">
      <p>MÉTODO DE AUTENTICAÇÃO(1 - Próprio, 2 - LDAP) (Ex: 1)</p>
    </td>
    <td align="left">
      <p>Definir qual método de autenticação será utilizado no sistema: 1 (Próprio) ou 2 (LDAP).</p>
    </td>
    <td align="left">
      <p>Se o método de autenticação de LDAP for alterado de 1 (Próprio) para LDAP, então, deverá existir um sincronismo entre LDAP e Citsmart, nesse momento é comum haver duplicação de empregados e usuários na base dados podendo causar problemas de autenticação e perfil de acesso.</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><strong>32</strong></p>
    </td>
    <td align="left">
      <p>DB - nome do SCHEMA do Banco de dados –(Ex: Postgres - public)</p>
    </td>
    <td align="left">
      <p>Informar o nome do Schema do Banco de Dados que será utilizado pela aplicação.</p>
    </td>
    <td align="left">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><strong>33</strong></p>
    </td>
    <td align="left">
      <p>URL de acesso ao sistema</p>
    </td>
    <td align="left">
      <p>Informar a URL de acesso ao sistema.</p>
    </td>
    <td align="left">
      <p>Caso não informe a URL do sistema corretamente, algumas funcionalidades irão se comportar de forma inesperada, como por exemplo, os relatórios não serão gerados.</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><strong>44</strong></p>
    </td>
    <td align="left">
      <p>Diretório Upload repositório path (Ex: Windows - C:/temp)</p>
    </td>
    <td align="left">
      <p>Informar o diretório para armazenar os arquivos que serão feitos upload.</p>
    </td>
    <td align="left">
      <p>Caso não seja informado o diretório corretamente, não será possível anexar os arquivos no sistema.</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><strong>46</strong></p>
    </td>
    <td align="left">
      <p>Tela inicial do CITSmart? (Opções: SD = Smart Decisions, SP = Smart Portal, EC = Centro de Experiência)</p>
    </td>
    <td align="left">
      <p>Definir qual será a tela inicial do CITSmart</p>
    </td>
    <td align="left">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><strong>48</strong></p>
    </td>
    <td align="left">
      <p>Validar permissões de botões (gravar, excluir e pesquisar) (Ex: S ou N).</p>
    </td>
    <td align="left">
      <p>Definir se será feita a validação de permissão de acesso dos botões: Gravar, Excluir e Pesquisar. Caso seja, a permissão de acesso aos botões (Gravar, excluir e pesquisar) definida no perfil de acesso será validada.</p>
    </td>
    <td align="left">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><strong>52</strong></p>
    </td>
    <td align="left">
      <p>Ativar log no sistema (Ex: 'true' ou 'false')</p>
    </td>
    <td align="left">
      <p>Ativar o Log de Auditoria no Sistema.</p>
    </td>
    <td align="left">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><strong>53</strong></p>
    </td>
    <td align="left">
      <p>Tipos: 'CIT_LOG' (arquivo de log), 'DB_LOG'(grava no banco)</p>
    </td>
    <td align="left">
      <p>Definir o tipo de log do sistema “CIT_LOG” (arquivo de log) ou “DB_LOG” (grava no banco). Se o tipo de Log for “CIT_LOG”, será salvo o arquivo de Log em um diretório (definido no parâmetro 54). Se o tipo de Log for “DB_LOG”, será gravado o mesmo em Banco de Dados.</p>
    </td>
    <td align="left">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><strong>54</strong></p>
    </td>
    <td align="left">
      <p>Caminho da pasta que ficará o arquivo deLOG (Ex: Linux - /var/tmp/)</p>
    </td>
    <td align="left">
      <p>Informar o diretório (pasta) para armazenar os arquivos de Log (CIT_LOG). Ao definir no parâmetro 53 o valor ‘CIT_LOG’, deve definir neste parâmetro o diretório onde ficará armazenado o arquivo de log.</p>
    </td>
    <td align="left">
      <p>Caso não informe o diretório, não serão armazenados os arquivos de Log (CIT_LOG).</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><strong>55</strong></p>
    </td>
    <td align="left">
      <p>Nome do arquivo de log (Ex: log_citsmart)</p>
    </td>
    <td align="left">
      <p>Definir o nome para o arquivo de Log. Os arquivos de Log serão gravados com nome conforme definido no parâmetro.</p>
    </td>
    <td align="left">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><strong>56</strong></p>
    </td>
    <td align="left">
      <p>Extensão do arquivo de log (Ex: txt)</p>
    </td>
    <td align="left">
      <p>Definir a extensão do arquivo de Log. Os arquivos de Log serão gravados com a extensão TXT, conforme definida no parâmetro.</p>
    </td>
    <td align="left">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><strong>66</strong></p>
    </td>
    <td align="left">
      <p>Idioma padrão do sistema (Ex: EN = Inglês)?</p>
    </td>
    <td align="left">
      <p>Definir o idioma padrão a ser utilizado na aplicação.</p>
    </td>
    <td align="left">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><strong>70</strong></p>
    </td>
    <td align="left">
      <p>Mostrar botões de importação e exportaçãodo xml no cadastro de menus. (Ex: S ou N - Default: 'S')</p>
    </td>
    <td align="left">
      <p>Definir se os botões de importação e exportação do XML serão exibidos na tela de Cadastro de Menus. Caso seja informado “S”, serão exibidos na tela de “Cadastro de Menu” os botões “Gerar XML” e “Atualizar menus” para importação e exportação do XML.</p>
    </td>
    <td align="left">
      <p>Caso não informe o valor do parâmetro, será estabelecido o valor padrão do sistema: “S” (Sim).</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><strong>71</strong></p>
    </td>
    <td align="left">
      <p>Parâmetro para ler o arquivo XML padrão de menus (Ex: S ou N - Default: 'S')</p>
    </td>
    <td align="left">
      <p>Habilitar a leitura do arquivo XML de menus. Caso seja habilitado, será feita a leitura do arquivo XML de menus no momento em que iniciar a aplicação.</p>
    </td>
    <td align="left">
      <p>Caso não informe o valor do parâmetro, será estabelecido o valor padrão do sistema: “N” (Não).</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><strong>117</strong></p>
    </td>
    <td align="left">
      <p>Informar o caminho para salvar a tabela LOGDADOS</p>
    </td>
    <td align="left">
      <p>Definir o diretório para armazenar as tabelas de LOGDADOS.</p>
    </td>
    <td align="left">
      <p>Caso não informe o diretório corretamente, não será possível armazenar as tabelas de LOGDADOS.</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><strong>118</strong></p>
    </td>
    <td align="left">
      <p>ID do Contrato padrão para abertura de chamados.</p>
    </td>
    <td align="left">
      <p>Informar o número de identificação (ID) do contrato para realização da abertura de incidentes/requisições através do portal.</p>
    </td>
    <td align="left">
      <p>Caso não informe o valor do parâmetro, não será possível realizar a abertura de incidentes/requisições via portal.</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><strong>131</strong></p>
    </td>
    <td align="left">
      <p>Definir a quantidade de Itens que serão listados nas buscas (Default: 10)</p>
    </td>
    <td align="left">
      <p>Definir a quantidade de dados que serão listados por página nas telas de Pesquisa do Sistema.</p>
    </td>
    <td align="left">
      <p>Não há impacto negativo. Caso não informe o valor do parâmetro, será utilizado o valor padrão do sistema: 10.</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><strong>135</strong></p>
    </td>
    <td align="left">
      <p>ID do Perfil de Acesso que será usado como Administrador</p>
    </td>
    <td align="left">
      <p>Informar o número de identificação (ID) do perfil de acesso que será utilizado como administrador para a validação de atualizações do Citsmart ITSM. Somente os usuários relacionados ao Perfil de Acesso definido neste parâmetro podem acessar e validar a atualização de versão do Citsmart ITSM.</p>
    </td>
    <td align="left">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><strong>136</strong></p>
    </td>
    <td align="left">
      <p>URL Logomarca padrão de relatórios (Ex.: <a href="http://www.citsmart.com.br/imagens/logoPadraoRelatorio.png">http://www.citsmart.com.br/imagens/logoPadraoRelatorio.png</a> )</p>
    </td>
    <td align="left">
      <p>Informar a URL da imagem que será utilizada como logomarca nos relatórios.</p>
    </td>
    <td align="left">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><strong>198</strong></p>
    </td>
    <td align="left">
      <p>Caminho da pasta que ficará o arquivo de LOG do Banco de dados (Ex: Linux - /var/tmp/)</p>
    </td>
    <td align="left">
      <p>Informar o diretório (pasta) para armazenar os arquivos de LOG do Banco de Dados.</p>
    </td>
    <td align="left">
      <p>Caso não informe o diretório, não será possível armazenar os arquivos de LOG do Banco de Dados.</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><strong>219</strong></p>
    </td>
    <td align="left">
      <p>Habilitar migração de dados automática</p>
    </td>
    <td align="left">
      <p>Ativar/Inativar a rotina de importação de dados para ser executada automaticamente.</p>
    </td>
    <td align="left">
      <p>Com o parâmetro ativado, habilitará uma thread que será executada, que além de diminuir a performance, poderá escrever mensagens de erro nos logs (console) do sistema, caso a importação de dados não esteja corretamente cadastrada. Caso informe “N”, não ocorrerá a importação de dados automaticamente.</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><strong>223</strong></p>
    </td>
    <td align="left">
      <p>Configuração do E-mail do Suporte da ferramenta CITSmart</p>
    </td>
    <td align="left">
      <p>Definir o e-mail do suporte do CITSmart que será exibido na barra de informação. Obs.: O sistema permite adicionar um ou mais e-mail de suporte.</p>
    </td>
    <td align="left">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><strong>224</strong></p>
    </td>
    <td align="left">
      <p>Configuração do Telefone do Suporte da ferramenta CITSmart</p>
    </td>
    <td align="left">
      <p>Definir o número de telefone do suporte do CITSmart para ser exibido na barra de informação. Obs.: O sistema permite adicionar um ou mais telefone de suporte.</p>
    </td>
    <td align="left">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><strong>225</strong></p>
    </td>
    <td align="left">
      <p>Configuração do E-mail do Suporte da ferramenta CITSmart Tela de Login</p>
    </td>
    <td align="left">
      <p>Definir o e-mail do suporte do CITSmart para ser exibido na tela de login. Obs.: O sistema permite adicionar um ou mais e-mail de suporte.</p>
    </td>
    <td align="left">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><strong>226</strong></p>
    </td>
    <td align="left">
      <p>Configuração do Telefone do Suporte da ferramenta CITSmart Tela de Login</p>
    </td>
    <td align="left">
      <p>Definir o número de telefone do suporte do CITSmart para ser exibido na tela de login. Obs.: O sistema permite adicionar um ou mais telefone de suporte.</p>
    </td>
    <td align="left">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><strong>235</strong></p>
    </td>
    <td align="left">
      <p>Usar AutoComplete no campo unidade nas telas de Colaborador e Unidade. (S ou N - Default: 'N')</p>
    </td>
    <td align="left">
      <p>Definir se o objeto de tela para o campo Unidade será um Auto Complete (valor=S) ou uma caixa de seleção (combobox) (valor=N).</p>
    </td>
    <td align="left">
      <p>Modifica a maneira como o usuário seleciona a unidade nas telas de Solicitação de Serviço, Registro de Problema e Requisição de Mudança. Esse parâmetro não refletirá o campo de Unidade da tela de Solicitação de serviço.</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><strong>244</strong></p>
    </td>
    <td align="left">
      <p>Mensagem da tela inicial</p>
    </td>
    <td align="left">
      <p>Informar uma mensagem que aparecerá na tela de Login do Sistema.</p>
    </td>
    <td align="left">
      <p>Quando o parâmetro não estiver configurado será exibida a mensagem padrão na tela de Login.</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><strong>254</strong></p>
    </td>
    <td align="left">
      <p>API Key para uso de serviços Google</p>
    </td>
    <td align="left">
      <p>Informar a key (chave) que registra o consumo dos serviços Google.</p>
    </td>
    <td align="left">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><strong>266</strong></p>
    </td>
    <td align="left">
      <p>ID do calendário padrão (Default = 1)</p>
    </td>
    <td align="left">
      <p>Definir o calendário padrão para utilização nos filtros de recuperação de tarefas.</p>
    </td>
    <td align="left">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><strong>271</strong></p>
    </td>
    <td align="left">
      <p>Informe a cidade de instalação do sistema:</p>
    </td>
    <td align="left">
      <p>Informar o nome da cidade que será apresentada nos relatórios do sistema.</p>
    </td>
    <td align="left">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><strong>275</strong></p>
    </td>
    <td align="left">
      <p>Manter o sistema sempre em inglês?</p>
    </td>
    <td align="left">
      <p>Definir se o idioma do sistema ficará somente em inglês.</p>
    </td>
    <td align="left">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><strong>276</strong></p>
    </td>
    <td align="left">
      <p>URL Relatório Power Bi</p>
    </td>
    <td align="left">
      <p>Informar a URL da ferramenta Power Bipara construção de relatórios dinâmicos referente aos processos ITIL. Ao informar a URL da ferramenta, quando acessar a funcionalidade “Relatórios Gerente Power Bi” será exibida a ferramenta para construção de relatórios.</p>
    </td>
    <td align="left">
      <p>Caso não informe o valor do parâmetro, não terá acesso à ferramenta Power Bi.</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><strong>277</strong></p>
    </td>
    <td align="left">
      <p>Permite o cadastro de colaborador com mesmo nome? Valores: "S" para "Sim" e "N" para "Não". Default: "N"</p>
    </td>
    <td align="left">
      <p>Definir se será permitido o registro de colaborador com o nome semelhante a outro colaborador. Quando seu valor é "S", o sistema permite que o usuário cadastre um colaborador com o mesmo nome que outro colaborador já cadastrado, porém com um CPF diferente. Também faz com que o campo "CPF/CNPJ" se torne obrigatório. Quando informado o valor "N", o sistema não permite que seja cadastrado um usuário com o nome semelhante a outro usuário cadastrado.</p>
    </td>
    <td align="left">
      <p>Caso não seja definido o valor para o parâmetro, será definido pelo sistema automaticamente o valor: “N” (Não).</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><strong>278</strong></p>
    </td>
    <td align="left">
      <p>Tamanho máximo de arquivo, em bytes, para upload. Default [1073741824] = 1GB</p>
    </td>
    <td align="left">
      <p>Limitar a quantidade de Bytes que pode ser carregada por arquivo nas telas de anexos do sistema.</p>
    </td>
    <td align="left">
      <p>O tamanho do arquivo que será carregado nas telas de anexos em solicitação de serviço, problema, mudança, liberação, continuidade e painel de controle BI será limitado.</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><strong>297</strong></p>
    </td>
    <td align="left">
      <p>Desativa envio de e-mails do sistema (Valores: "S" ou "N" Default: "N")</p>
    </td>
    <td align="left">
      <p>Desativa todos os envios de e-mail do sistema.</p>
    </td>
    <td align="left">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><strong>318</strong></p>
    </td>
    <td align="left">
      <p>Lista de extensões de arquivos que não poderão ser anexados (Para mais de uma extensão separar por ponto e vírgula)</p>
    </td>
    <td align="left">
      <p>Lista de extensões de arquivos que não poderão ser anexados</p>
    </td>
    <td align="left">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><strong>319</strong></p>
    </td>
    <td align="left">
      <p>Ativar Acesso Remoto</p>
    </td>
    <td align="left">
      <p>URL para abrir tela de acesso remoto</p>
    </td>
    <td align="left">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><strong>320</strong></p>
    </td>
    <td align="left">
      <p>ID da Categoria Galeria para envio das imagens adicionadas no editor (Ex.: 1)</p>
    </td>
    <td align="left">
      <p>Configurar o ID da galeria que será usada para fazer o upload de imagens adicionadas no editor</p>
    </td>
    <td align="left">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><strong>331</strong></p>
    </td>
    <td align="left">
      <p>Ativar Google Maps API</p>
    </td>
    <td align="left">
      <p>Ativar Google Maps API</p>
    </td>
    <td align="left">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><strong>334</strong></p>
    </td>
    <td align="left">
      <p>Caminho para a Logo do início (Ex.: /citsmart/path/logo.png)</p>
    </td>
    <td align="left">
      <p>Permitir que a logo da tela de login possa será alterada.</p>
    </td>
    <td align="left">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><strong>335</strong></p>
    </td>
    <td align="left">
      <p>Caminho para a Logo do Portal (Ex.: /citsmart/path/logo-portal.png)</p>
    </td>
    <td align="left">
      <p>Permitir que a logo do Portal possa será alterada.</p>
    </td>
    <td align="left">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><strong>336</strong></p>
    </td>
    <td align="left">
      <p>Caminho para a Logo do Sistema (Ex.: /citsmart/path/logo-sistema.png)</p>
    </td>
    <td align="left">
      <p>Permitir que a logo do Sistema possa será alterada.</p>
    </td>
    <td align="left">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><strong>337</strong></p>
    </td>
    <td align="left">
      <p>Tornar obrigatório o campo 'Localidade Física' no cadastro de Serviço S ou N (default N)</p>
    </td>
    <td align="left">
      <p>Tornar obrigatório o campo 'Localidade Física' no cadastro de Serviço</p>
    </td>
    <td align="left">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><strong>341</strong></p>
    </td>
    <td align="left">
      <p>Configuração do contato para Ouvidoria na tela de login</p>
    </td>
    <td align="left">
      <p>Permite informar o telefone/e-mail de Ouvidoria, informação que vai aparecer na tela de login do sistema.</p>
    </td>
    <td align="left">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><strong>344</strong></p>
    </td>
    <td align="left">
      <p>Ouvidoria – URL padrão para logo da tela</p>
    </td>
    <td align="left">
      <p>Permite informar o link de uma logomarca para a tela de Ouvidoria.</p>
    </td>
    <td align="left">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><strong>345</strong></p>
    </td>
    <td align="left">
      <p>Ouvidoria – ID do serviço de denúncia</p>
    </td>
    <td align="left">
      <p>Permite informar o código da atividade de denúncia de um portfólio usado na abertura de um ticket de Ouvidoria.</p>
    </td>
    <td align="left">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><strong>346</strong></p>
    </td>
    <td align="left">
      <p>Ouvidoria – ID do serviço de reclamação</p>
    </td>
    <td align="left">
      <p>Permite informar o código da atividade de reclamação de um portfólio usado na abertura de um ticket de Ouvidoria.</p>
    </td>
    <td align="left">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><strong>347</strong></p>
    </td>
    <td align="left">
      <p>Ouvidoria – ID do serviço de sugestão</p>
    </td>
    <td align="left">
      <p>Permite informar o código da atividade de sugestão de um portfólio usado na abertura de um ticket de Ouvidoria.</p>
    </td>
    <td align="left">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><strong>348</strong></p>
    </td>
    <td align="left">
      <p>Ouvidoria – Login do usuário para autenticação</p>
    </td>
    <td align="left">
      <p>Permite informar o usuário solicitante usado na abertura de um ticket de Ouvidoria.</p>
    </td>
    <td align="left">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><strong>349</strong></p>
    </td>
    <td align="left">
      <p>Ouvidoria – ID da origem do contato</p>
    </td>
    <td align="left">
      <p>Permite informar o código da origem do chamado usado na abertura de um ticket de Ouvidoria.</p>
    </td>
    <td align="left">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><strong>370</strong></p>
    </td>
    <td align="left">
      <p>Ativar autenticação automática por e-mail via token</p>
    </td>
    <td align="left">
      <p>Permite ligar ou desligar a capacidade do sistema receber autenticação via token.</p>
    </td>
    <td align="left">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><strong>378</strong></p>
    </td>
    <td align="left">
      <p>Quantidade mínima de registros que determina a geração do relatório em segundo plano.</p>
    </td>
    <td align="left">
      <p>Estabelecer um limite a partir do qual os relatórios serão gerados em segundo plano.</p>
    </td>
    <td align="left">
      <p>Faz com que os relatórios da tela Pesquisa avançada, sejam gerados em segundo plano e quando ficarem prontos, é enviada uma notificação para o usuário, com um link para download do arquivo.</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><strong>383</strong></p>
    </td>
    <td align="left">
      <p>Habilitar listagem de domínios no login</p>
    </td>
    <td align="left">
      <p>Permite mostrar ou ocultar a lista de domínios na tela de login por uma questão de segurança. Caso habilitado o parâmetro e o usuário digite um domínio, o domínio será alterado para o digitado. Caso o usuário tenha digitado um domínio e faça a alteração na listagem, o domínio digitado também será alterado.</p>
    </td>
    <td align="left">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><strong>384</strong></p>
    </td>
    <td align="left">
      <p>Timeout das consultas ao WebService DATA_QUERY</p>
    </td>
    <td align="left">
      <p>Tempo máximo de espera para a resposta da consulta usando o Web Service DATA_QUERY</p>
    </td>
    <td align="left">
      <p>O tempo definido no sistema está em segundos: de 0 a 2.147.483.647 segundos.</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><strong>385</strong></p>
    </td>
    <td align="left">
      <p>Habilitar criação de solicitação relacionada como cópia</p>
    </td>
    <td align="left">
      <p>Permite a visualização do botão "criar solicitação relacionada por cópia", na tela interna de solicitação de serviço. Este botão irá abrir a tela para criar uma solicitação relacionada, copiando a descrição, solicitante, anexos, conhecimentos relacionados e itens de configuração da solicitação de serviço principal.</p>
    </td>
    <td align="left">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><strong>390</strong></p>
    </td>
    <td align="left">
      <p>ID da unidade padrão</p>
    </td>
    <td align="left">
      <p>ID da Unidade que será atribuído ao usuário cadastrado no perfil</p>
    </td>
    <td align="left">
      <p>Não se aplica.</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><strong>400</strong></p>
    </td>
    <td align="left">
      <p>Smart Analytics – URL Schema Gen</p>
    </td>
    <td align="left">
      <p>Parâmetro depreciado  a partir da versão 8.0</p>
    </td>
    <td align="left">
      <p>Não se aplica.</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><strong>401</strong></p>
    </td>
    <td align="left">
      <p>Smart Analytics – URL externa</p>
    </td>
    <td align="left">
      <p>Caminho para acesso ao BI</p>
    </td>
    <td align="left">
      <p>Não se aplica.</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><strong>402</strong></p>
    </td>
    <td align="left">
      <p>Anuva Assistant – URL externa</p>
    </td>
    <td align="left">
      <p>Caminho para acesso externo à ANUVA</p>
    </td>
    <td align="left">
      <p>Não se aplica.</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><strong>403</strong></p>
    </td>
    <td align="left">
      <p>Utilizar autenticação SSO para login</p>
    </td>
    <td align="left">
      <p>Permite utilizar Single Sign On para login no sistema</p>
    </td>
    <td align="left">
      <p>Não se aplica.</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><strong>405</strong></p>
    </td>
    <td align="left">
      <p>Configuração Machine Learning</p>
    </td>
    <td align="left">
      <p>Permite utilizar Machine Learning para abertura de chamados. <em>OBS:Este parâmetro se encontra na funcionalidade "Parâmetros CITSmart"</em></p>
    </td>
    <td align="left">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><strong>409</strong></p>
    </td>
    <td align="left">
      <p>LDAP - Atributo que representa o superior imediato do usuário</p>
    </td>
    <td align="left">
    </td>
    <td align="left">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><strong>449</strong></p>
    </td>
    <td align="left">
      <p>Tempo de Sessão do Usuário (Em Minutos)</p>
    </td>
    <td align="left">
      <p>Configurar  o tempo de expiração das sessões da aplicação</p>
    </td>
    <td align="left">
      <p>Incluir, em minutos, o valor desejado para duração da sessão . Logo após, é necessário desconectar e conectar novamente ao sistema, dessa forma, o sistema buscará o novo padrão para o tempo de expiração de sessões.</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><strong>450</strong></p>
    </td>
    <td align="left">
      <p>Habilitar Anuva Assistant</p>
    </td>
    <td align="left">
      <p>Habilitar ou não a Anuva no CITSmart Workflow</p>
    </td>
    <td align="left">
      <p>O parâmetro reflete diretamente no Smart Chat externo (Centro de Experiência e Smart Portal) e no botão interno no header do sistema onde é mostrado o botão para falar com a Anuva.</p>
    </td>
  </tr>
</table>

Tabela 1 - Lista de parâmetros


[title] Configurar as rotas diárias
[path] Administração da Plataforma/Mobile/

Esta funcionalidade tem por objetivo configurar a agenda diárias dos técnicos de campo. Após a configuração, o técnico terá uma lista de solicitações que serão atendidas via Mobile.

Esta tela permite realizar a pesquisa de solicitações de acordo com os filtros informados, ou seja, de acordo com sua necessidade, a fim de direcionar as solicitações abertas para serem atendidas pelo técnico de campo.

## Antes de começar

- [x] Antes de configurar a agenda diária dos técnicos de campo é necessário configurar a conexão do sistema com as API's do Google.

## Procedimento

1. Acessar a funcionalidade através da navegação no menu principal `Gestão Integrada > Gerência de Força de Atendimento > Gerência de Rotas Diárias;`
2. Definir os filtros conforme a necessidade e clicar no botão "**Pesquisar**". Serão apresentadas as solicitações as quais o técnico tem permissão de execução com as seguintes situações (não atendida, em atendimento, atendida com pendência);
3. Direcionar as solicitações de serviços disponíveis para o técnico realizar o atendimento através destes passos:
   - Selecionar as solicitações que serão atendidas pelo técnico e informar a prioridade do atendimento das solicitações;
   - No campo "**Data de execução**", informar a data prevista para execução das solicitações;
   - Após selecionar as solicitações, serão apresentados no mapa os marcadores da rota que o técnico deverá seguir. Lembrar que ao clicar no marcador da rota, serão apresentadas as informações da solicitação de serviço.
4. Clicar no botão "Gravar" para efetuar a operação. Após a gravação, será enviada uma notificação para o técnico, onde o mesmo poderá verificar pelo aplicativo CITSmart Enterprise ITSM Mobile as solicitações que serão atendidas por ele.


[title] Cadastrar uma unidade
[path] Administração da Plataforma/Untitled/

Esta funcionalidade tem por objetivo registrar as unidades onde os colaboradores estão alocados. Esta funcionalidade disponibiliza ações diversas, tais como, incluir, alterar e excluir uma unidade.

## Antes de começar

- [x] O cadastro de uma unidade precede da realização da carga de países e da configuração dos parâmetros 254 e 331.

## Procedimento

1. Acessar a funcionalidade através da navegação no menu principal `Cadastros Gerais > Gerência de Pessoal > Unidade;`
2. Preencher os campos necessários;
3. Clicar em "**Gravar**".

:::hint{type="success"}
**Novidade**

Nesta versão é possível editar as informações nos campos Latitude e Longitude.
:::


[title] Parametrização - Liberação
[path] Administração da Plataforma/Untitled/

Gerenciamento de liberação é o processo responsável por planejar, programar e controlar a construção, o teste e a implantação de liberações, e por entregar novas funcionalidades exigidas pelo negócio enquanto protege a integridade dos serviços existentes. A parametrização de "Liberação" deve ser realizada para permitir a execução/uso deste processo, podendo ser possível, definir se será enviado notificações ao solicitante da execução dos fluxos de solicitação de serviços/incidentes, por exemplo.

## Procedimento

1. Acessar a funcionalidade através da navegação no menu principal `Parametrização > Gerência de Liberação;`
2. Definir os valores dos parâmetros (atributos);
3. Clicar no botão "**Gravar**" para efetuar a operação;
4. A lista abaixo representa os parâmetros da "**Liberação**" e a finalidade de cada um deles:

| #   | Nome                        | Valores possíveis | Finalidade                                                                                                                                                                                            | Orientações complementares |
| --- | --------------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
| 146 | Id template do questionário | Ex: 13            | Informar o número de identificação (ID) do template para o questionário (checklist) referente à mudanças e liberação. Esse ID do template é definido na tela de “Template de Solicitação de Serviço”. | Não se aplica              |

Tabela 1 - Lista de parâmetros


[title] Cadastrar template de ticket/mudança
[path] Administração da Plataforma/Untitled/

Esta funcionalidade tem o objetivo de habilitar algumas funcionalidades na tela de solicitação de serviço (ticket).

Esta funcionalidade disponibiliza ações diversas, tais como, incluir, alterar e excluir template de ticket/mudança.

## Antes de começar

- [x] O template de ticket do tipo Questionário requer o registro de um questionário previamente.
- [x] O template de ticket do tipo Neuro requer o registro prévio de um formulário do tipo **Neuro** previamente.

## Procedimento

1. Acessar a funcionalidade de Template de Solicitação de Serviço através da navegação no menu principal `Sistema > Template de Ticket/Mudança;`
2. Clicar no botão " **Novo**";
3. Identifique o template através do campo "**Identificação do template**";
4. Dê um nome para o template através do campo "**Nome do template**";
5. Selecione as checkbox disponíveis para os templates:
   - Aplicável a Ticket;
   - Habilita direcionamento;
   - Habilita situação;
   - Habilita item de configuração;
   - Habilita mudança;
   - Habilita problema;
   - Habilita solução;
   - Habilita solicitação relacionada;
   - Habilita botão gravar e continuar.

:::hint{type="info"}
**Nota: **Ao selecionar o checkbox "Aplicável a Ticket", esse campo o usuário entende que o seu tipo de template é aplicável apenas à ticket.
:::

:::hint{type="info"}
**Nota: **Ao selecionar o Tipo de Template "Neuro", será apresentado o novo campo do tipo checkbox com o texto: "Aplicável a Mudança". Ao selecionar esse campo o usuário entende que o seu tipo de template é aplicável apenas à Mudança.
:::

:::hint{type="warning"}
**Atenção: **No caso de templates do Tipo "Neuro", o usuário poderá informar que o template será utilizado tanto para ticket quanto para mudança.
:::


[title] Parametrização - E-mail
[path] Administração da Plataforma/Untitled/

Podemos definir o e-mail (correio eletrônico) como um método que permite compor, enviar e receber mensagens através de sistemas eletrônicos de comunicação. A parametrização de "e-mail" permite configurar o envio de leitura de e-mail,
informar o domínio de e-mail padrão da empresa, dentre outras ações, afim de permitir a utilização do serviço de correio eletrônico para agregar melhor experiência na utilização dos diversos recursos disponíveis nas soluções CITSmart, permitindo o envio de informações para os usuários.

## Procedimento

1. Acessar a funcionalidade através da navegação no menu principal `Parametrização > E-mail;`
2. Definir os valores dos parâmetros (atributos);
3. Clicar no botão "**Gravar**" para efetuar a operação;
4. A lista abaixo apresenta os parâmetros do "**E-mail**" e a finalidade de cada um deles:

| #   | Nome                                                                                         | Valores possíveis                                                  | Finalidade                                                                                                                                                                                                                                                                                         | Orientações complementares                                                                                                                                          |
| --- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 10  | SMTP ENVIO - E-mail origem das notificações de solicitações de serviço                       | Ex: [citsmart@centralit.com.br](mailto\:citsmart@centralit.com.br) | Informar o e-mail que será utilizado como origem do envio das notificações referentes as Solicitações de Incidente/Requisições abertas ou alteradas.                                                                                                                                               | Não se aplica                                                                                                                                                       |
| 11  | SMTP ENVIO - Exige autenticação para envio de e-mail (Ex: S ou N - Default: 'N')             | S ou N (Default: N)                                                | Definir se o envio de e-mail utilizado para notificações exige autenticação. Se o e-mail configurado no parâmetro 10 não exigir autenticação, deve ser definido o valor “N”. Se o e-mail exigir autenticação, deve ser definido o valor “S” e configurar as autenticações nos próximos parâmetros. | Caso não seja definido o valor para o parâmetro, será definido pelo sistema automaticamente o valor: “N” (Não).                                                     |
| 12  | SMTP ENVIO - Usuário para autenticação de e-mail                                             | Ex: citsmart                                                       | Informar o usuário de e-mail para autenticação. Caso o e-mail exija autenticação, devemos informar o usuário a ser autenticado.                                                                                                                                                                    | Caso não informe o usuário corretamente, não será realizada a autenticação.                                                                                         |
| 13  | SMTP ENVIO - Senha para autenticação de e-mail                                               |                                                                    | Informar a senha de e-mail para autenticação. Caso e e-mail exija autenticação, devemos informar a senha do usuário do e-mail.                                                                                                                                                                     | Caso não informe a senha corretamente, não será realizada a autenticação.                                                                                           |
| 14  | SMTP ENVIO - Servidor para envio de e-mail                                                   | Ex: 172.20.0.200                                                   | Informar o servidor SMTP, utilizado para o envio de e-mail. O servidor SMTP é encarregado de enviar aos destinatários os e-mails de notificações do sistema.                                                                                                                                       | Caso não informe o servidor SMTP, não será possível realizar o envio de e-mails de notificações do sistema.                                                         |
| 23  | SMTP LEITURA - Servidor de entrada de e-mails do Service Desk                                | Ex: 172.20.0.200                                                   | Informar o servidor de e-mails do Service Desk que será acessado para a leitura de e-mails.                                                                                                                                                                                                        | Não se aplica                                                                                                                                                       |
| 24  | SMTP LEITURA - Usuário da Caixa de entrada de e-mails do Service Desk                        | Ex: citsmart                                                       | Informar a conta de e-mail do Service Desk que será utilizado para receber os e-mails enviados pelo usuário.                                                                                                                                                                                       | Não se aplica                                                                                                                                                       |
| 25  | SMTP LEITURA - Senha da Caixa de entrada de e-mails do Service Desk                          |                                                                    | Informar a senha da conta de e-mail informado no parâmetro 24 para acesso à caixa de entrada de e-mails do Service Desk.                                                                                                                                                                           | Não se aplica                                                                                                                                                       |
| 26  | SMTP LEITURA - Provider do servidor de e-mails do Service Desk (imaps, pops, imap, pop, etc) | Ex: imap                                                           | Informar o protocolo do servidor de e-mails do Service Desk que será utilizado para a leitura de e-mails.                                                                                                                                                                                          | Não se aplica                                                                                                                                                       |
| 27  | SMTP LEITURA - Porta do servidor de e-mails do Service Desk                                  | Ex: 143                                                            | Informar a porta do servidor que será utilizada para a leitura de e-mails.                                                                                                                                                                                                                         | Não se aplica                                                                                                                                                       |
| 28  | SMTP LEITURA - Pasta da caixa de entrada de e-mails do Service Desk                          | Ex: Inbox                                                          | Informar a pasta da caixa de entrada de e-mails da conta de e-mail do Service Desk.                                                                                                                                                                                                                | Não se aplica                                                                                                                                                       |
| 72  | SMTP LEITURA - Limite de e-mails carregados em Solicitação Serviço                           | Ex: 20                                                             | Definir o limite de e-mails que serão carregados na tela de Solicitação de Serviço/Incidente. Ao clicar no botão “carregar e-mail” na tela de Solicitação de Serviços/Incidentes, será carregada a quantidade de e-mails conforme estabelecido no parâmetro.                                       | Não se aplica                                                                                                                                                       |
| 199 | SMTP ENVIO - O E-mail Usa Autenticação TLS / ssl? (Ex: S ou N - Default ´N´)                 | S ou N (Default: N)                                                | Definir se o sistema de e-mail utilizará a autenticação starttls.                                                                                                                                                                                                                                  | Se não for informado o valor ‘S’ para o parâmetro, impactará somente nos servidores que utilizam TLS/SSL na autenticação e o sistema não conseguirá enviar e-mails. |
| 269 | SMTP ENVIO - Porta para envio de e-mail                                                      | Ex: 465 (porta segura SSL/TLS), 25 e 26 (portas comuns)            | Informar a porta do servidor que será utilizada para o envio de e-mails ao servidor.                                                                                                                                                                                                               | Não se aplica                                                                                                                                                       |
| 297 | Desativa envio de e-mails do sistema (Valores: "S" ou "N" Default: "N")                      | S ou N (Default: N)                                                | Desativa todos os envios de e-mail do sistema.                                                                                                                                                                                                                                                     | Não se aplica                                                                                                                                                       |

Tabela 1 - Lista de parâmetros


[title] Configurar instância CITSmart para acesso via mobile
[path] Administração da Plataforma/Mobile/

Este documento tem como objetivo orientar para a configuração do servidor para uso do aplicativo CITSmart Experience.

## Antes de começar

- [x] É necessário Implantar a versão 7.2.2.0 (ou superior) do CITSmart, configurar os parâmetros 257 e 272, sendo:

* Valores: "S" ou "N". Default: "N"
* Caso o valor do parâmetro seja “S”, poderão ser mostradas somente as
  notificações de solicitações sem responsável atual.
* Caso o valor do parâmetro seja “N”, poderão ser mostradas as notificações de
  todas as solicitações.

- [x] Os parâmetros 254 (Parametrização > Sistema), 255, 256, 258, 267, 284, 285, 286, 350 também devem ser configurados.

## Configurando os web services

A configuração dos Web services são fundamentais para o acesso a todas as funcionalidades do aplicativo. Seguir os passos para melhor configurá-lo:

1. No CITSmart Experience (Web), acessar a funcionalidade de Web Services referente ao mobile (`Sistema > Configurações > Web Services Citsmart Mobile`);
2. Clicar na aba “Vincular Grupos” e vincular o grupo executor de atividades aos Web Services do CITSmart Experience Mobile.

:::hint{type="success"}
**Regra**

No momento que o grupo for selecionado ele será vinculado a todos os Web Services do CITSmart Experience de forma automatizada.
:::

## Instalação do certificado intermediário globalsign

Para reconhecer o certificado intermediário da GlobalSign (Emissora do Certificado Digital) é necessário a instalação do mesmo:

1. Acessar o endereço: [https://support.globalsign.com/customer/portal/articles/1464460-domainssl-intermediate-certificates](https://support.globalsign.com/customer/portal/articles/1464460-domainssl-intermediate-certificates);
2. Depois de instalado, alterar o endereço do aplicativo para suas necessidades (exemplo: “[https://citsmart.empresa.com.br/citsmart](https://citsmart.centralit.com.br/citsmart)”).

### Instalação do app Android/iOS

1. Acessar a loja (Play Store ou App Store) para baixar o aplicativo CITSmart Experience mobile;
2. Pesquisar por CITSmart Experience e após a pesquisa, selecionar o aplicativo;
3. Pressionar o botão "Instalar" para baixar o aplicativo.

### Criar chave para uso e consumo das APIs Google

Para que seja possível o uso e consumo das APIs Google é necessário que uma API Key seja criada. Para isso, os seguintes passos devem ser seguidos:

:::hint{type="info"}
Para realizar esses procedimentos é necessário estar logado com uma conta Google.
:::

1. Acessar o console do desenvolvedor Google [https://console.developers.google.com](https://console.developers.google.com/);
2. Clicar em "Criar um projeto", conforme indicado na figura abaixo:
3. Será apresentada uma janela, conforme ilustrada na figura abaixo, para informar os dados do novo projeto;
4. Informar o nome do projeto e clicar no botão "Criar" para criação do projeto.
5. Após criar o projeto, clicar em APIs e serviços. Para criar a API Key, clicar em APIs e serviços > Credenciais > Criar credenciais > Chave de API, conforme indicado na figura abaixo:
6. Feito isso, a chave de API será apresentada:
7. Escolha a opção que melhor atenda a necessidade. Para mais informações sobre qual chave irá lhe atender, acessar [https://developers.google.com/console/help/new/#generatingdevkeys](https://developers.google.com/console/help/new/#generatingdevkeys).
8. Após as chaves criadas, as APIs já poderão ser consumidas.

### APIs a serem utilizadas nas soluções

Segue abaixo as APIs do Google a serem consideradas nas soluções:

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/wVZf75YjMX0KR14jbiFxe_image.png" size="52" width="304" height="169" caption="Figura 7 - APIs" position="center" signedSrc="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/wVZf75YjMX0KR14jbiFxe_image.png"}

- **Directions API**: a API de direções do Google é consumida através de requisições HTTP. Tal API calcula direções entre dois pontos informados, a origem e o destino, possuindo outras diversas opções. Para maiores informações sobre o uso dessa API, acesse: [https://developers.google.com/maps/documentation/directions](https://developers.google.com/maps/documentation/directions).
- **Distance Matrix API**: a API Google Distance Matrix permite a recuperação de matrizes de distâncias entre dois pontos, ou seja, retorna também resultado aproximados. A diferença para a Google Directions API é que a Distance Matrix não retorna informações tão detalhadas, como os passos a serem realizados. Para maiores informações sobre o uso dessa API, acesse: [https://developers.google.com/maps/documentation/distancematrix](https://developers.google.com/maps/documentation/distancematrix).
- **Geocoding API**: a Google geocoding API é uma API que ajuda a recuperar posições geográficas enviando como argumento um endereço por extenso. O consume da API é feito por HTTP e os resultados podem ser obtidos em XML ou JSON. Para maiores informações sobre o uso dessa API, acesse: [https://developers.google.com/maps/documentation/geocoding](https://developers.google.com/maps/documentation/geocoding).
- **Statics Maps API**: a API para mapas estáticos do Google será utilizada em casos que não será necessário a interação como mapa, apenas visualização. É interessante seu uso uma vez que é mais leve, visto que não é necessário o download de recurso JS e imagens que não serão utilizadas. Para maiores informações sobre o uso dessa API, acesse: [https://developers.google.com/maps/documentation/staticmaps](https://developers.google.com/maps/documentation/staticmaps).
- **Google Maps JavaScript API**: o uso da API é feito por meio de uma API JS. Para seu uso, basta linkar o JS na página que irá usar o maps. Para maiores informações sobre o uso dessa API, acesse: [https://developers.google.com/maps/documentation/javascript](https://developers.google.com/maps/documentation/javascript).

## Ativando uma API

Para ativar uma API para uso, proceder conforme os passos descritos abaixo:

1. Após executar os passos descritos na seção "Criar chave para uso e consumo das APIs Google";
2. Clicar em APIs e serviços > Ativar APIs e serviços , conforme indicado na figura abaixo:

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/F9UOEtWnaCVZP-G3lDyf3_image.png" size="74" width="577" height="285" caption position="center" signedSrc="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/F9UOEtWnaCVZP-G3lDyf3_image.png"}

1. Será apresentada a biblioteca de APIs. Selecionar a API que deseja ativar (a figura abaixo representa um exemplo de API) e clicar no botão "Ativar" conforme indicado na figura abaixo:

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/4xDz4xE5gPYEsXGfcVRla_image.png" size="68" width="555" height="219" caption position="center" signedSrc="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/4xDz4xE5gPYEsXGfcVRla_image.png"}

1. Feito isso, a API estará habilitada para uso.


[title] Campos Chave de E-mails de Problema
[path] Administração da Plataforma/Untitled/

Este documento tem o objetivo de fornecer a relação dos campos chave, disponíveis para o cadastro de modelo de e-mail relacionada a problemas.

## Relação dos Campos Chave

| **CAMPO-CHAVE**               | **DESCRIÇÃO**                                                                                                                  |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| $\{ACOESCORRETAS}             | Ações Realizadas Corretamente.Informa a descrição das ações realizadas corretamente referente à revisão de problema grave.     |
| $\{ACOESINCORRETAS}           | Ações Realizadas Incorretamente.Informa a descrição das ações realizadas incorretamente referente à revisão de problema grave. |
| $\{CONTRATO}                  | Contrato.Informa o nome do contrato referente ao registro de problema.                                                         |
| $\{DATAHORACAPTURA}           | Data e Hora de Início do Registro de Problema.Informa a data e hora em que foi registrado o problema.                          |
| $\{DATAHORAFIM}               | Data e Hora da Finalização do Problema.Informa a data e hora em que foi finalizado o problema.                                 |
| $\{DATAHORALIMITE}            | Prazo Limite para Atendimento do Problema.Informa o prazo limite (data e hora) para atendimento do problema.                   |
| $\{DATAHORALIMITESOLUCIONAR}  | Prazo Limite para Solucionar/Contornar o problema.Informa o prazo limite para solucionar/contornar o problema.                 |
| $\{DESCRICAO}                 | Descrição do Problema.Informa a descrição do problema.                                                                         |
| $\{DIAGNOSTICO}               | Diagnóstico do Problema.Informa a descrição do diagnóstico do problema.                                                        |
| $\{EMAILCONTATO}              | E-mail do Contato.Informa o e-mail do solicitante para contato.                                                                |
| $\{IDFASEATUAL}               | Situação atual da identificação do Problema.Informa a situação atual da identificação (fase) em que problema se encontra.      |
| $\{FECHAMENTO}                | Fechamento do Problema.Informa a descrição do fechamento do problema.                                                          |
| $\{IDPROBLEMA}                | Número de Identificação do Problema.Informa o número de identificação do registro de problema.                                 |
| $\{IMPACTO}                   | Impacto do Problema.Informa a identificação do impacto do problema.                                                            |
| $\{LINKPESQUISASATISFACAO}    | Link para pesquisa de satisfação.Informa o link para fazer a avaliação do atendimento do problema.                             |
| $\{MELHORIASFUTURAS}          | Possíveis Melhorias Futuras.Informa a descrição das possíveis melhorias futuras referente à revisão de problema grave.         |
| $\{MSGERROASSOCIADA}          | Mensagem de Erro Associada.Informa a mensagem de erro associada que foi descrito na avaliação e diagnóstico do problema.       |
| $\{NOMECONTATO}               | Nome do Contato.Informa o nome do solicitante para contato.                                                                    |
| $\{NOMEGRUPOATUAL}            | Grupo Executor.Informa o nome do grupo executor do problema.                                                                   |
| $\{PRAZOHH}                   | Prazo (horas) para Atendimento do Problema.Informa o prazo para atendimento do problema.                                       |
| $\{PRIORIDADE}                | Prioridade.Informa a prioridade do problema.                                                                                   |
| $\{PROATIVOREATIVO}           | Gerenciamento do Problema.Informa o gerenciamento do problema (proativo ou reativo).                                           |
| $\{RECORRENCIAPROBLEMA}       | Recorrência do Problema.Informa a descrição de como prevenir a recorrência do problema referente à revisão de problema grave.  |
| $\{RESPONSABILIDADETERCEIROS} | Responsabilidade de Terceiros.Informa a descrição da responsabilidade de terceiros referente à revisão de problema grave.      |
| $\{RESPONSAVEL}               | Responsável pelo Atendimento do Problema.Informa o responsável atual pelo atendimento do problema.                             |
| $\{SEVERIDADE}                | Severidade do problema.Informa a descrição da severidade do problema.                                                          |
| $\{SOLICITANTE}               | Nome do Solicitante.Informa o nome do solicitante do registro de problema.                                                     |
| $\{SOLUCAODEFINITIVA}         | Descrição da Solução Definitiva.Informa a descrição da solução definitiva do problema.                                         |
| $\{DESCRSTATUS}               | Status do Problema.Informa o status em que o problema se encontra.                                                             |
| $\{TITULO}                    | Título do Problema.Informa o título do problema que foi registrado.                                                            |
| $\{URGENCIA}                  | Urgência do Problema.Informa a identificação da Urgência do Problema.                                                          |

Tabela 1 - Lista de campos chave


[title] Gerenciar dados
[path] Administração da Plataforma/

O objetivo desta funcionalidade é gerar exportação e importação de dados das tabelas do sistema.

## Procedimento

1. Acessar a funcionalidade através da navegação no menu principal `Sistema > Banco de Dados > Gerenciamento de Dados;`
2. Clicar em "**Carregar Metadados**" para atualizar a listagem de tabelas;
3. Para gerar exportação das tabelas do sistema em formato ".XML", clicar no botão "**Exportar Tudo**", para a exportação de todas as tabelas do sistema no formato referente;
4. Para gerar exportação das tabelas do sistema em formato ".SQL", clicar no botão "**Exportar Tudo SQL**", para a exportação de todas as tabelas do sistema com os comandos SQLs;
5. Para exportar uma tabela, clicar duas vezes na tabela desejada;
6. Definir os dados que serão exportados;
7. Clicar em "**Processar**".


[title] UF/Estado
[path] Administração da Plataforma/

Aqui estão os **estados **que estão cadastrados no sistema. Além disso, é possível** registrar **um novo estado ou **excluir** um já cadastrado.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/feaKjhbRmUzGD5MjT2JB9_image.png "Tela Hyper - UF/Estados")

***

Na aba "**UF/Estado**" é tanto possível registrar um novo estado como exportar um arquivo **.csv** contendo as informações dos estados já cadastrados no sistema.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/YkwU5ifPqCeVa0mcDjzsU_image.png" size="64" width="492" height="47" caption position="center" signedSrc="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/YkwU5ifPqCeVa0mcDjzsU_image.png"}

Além disso, também é possível editar e excluir um estado, escreva o **nome do estado** desejado ou a **ID do estado **no campo de busca e prosseguir com a ação clicando em "**Editar**"**.**

***

- Ao clicar em "**Editar**", as seguintes alterações estão disponíveis;

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/DpBFnABsI9xXx-qJ8B7xq_image.png)

<table columnWidths="217,527,248" selectedRows="" selectedTable="false" isTableHeaderOn="true" selectedColumns="">
  <tr>
    <td>
      <p><strong>Campos</strong></p>
    </td>
    <td>
      <p><strong>Descrição</strong></p>
    </td>
  </tr>
  <tr>
    <td>
      <p><strong>Nome</strong>*</p>
    </td>
    <td>
      <p>Adicione um novo estado: <strong>Alabama</strong></p>
    </td>
  </tr>
  <tr>
    <td>
      <p><strong>País</strong></p>
    </td>
    <td>
      <p>Registre ou edite um país</p>
    </td>
  </tr>
</table>

As informações com asterisco (\*) são obrigatórias.

***

- Após concluir todas as alterações, clique em "**Registro**".


[title] Cadastrar questionário
[path] Administração da Plataforma/Untitled/

Esta funcionalidade disponibiliza ações diversas, tais como, incluir, alterar e excluir questionários (formulários) de uma forma muito genérica, multi-propósitos e fáceis para serem utilizados em outras rotinas do sistema. É possível a importação de um questionário já elaborado. Para garantir maior produtividade, o botão "Copiar de outro questionário" permite ao Administrador que importe Questionários construídos tanto na forma anterior, quanto na forma atual. É possível também a criação de questionários através do Low Code, para ser disponibilizado em incidentes/requisições/mudanças/problemas.

## Antes de começar

- [x] É necessário ter cadastrado previamente a categoria do questionário.

## Procedimento

1. Acessar a funcionalidade através da navegação no menu principal `Sistema > Visões e Metadados > Questionário > Cadastrar;`
2. Clicar no botão "**Novo**";
3. Preencher os campos disponibilizados;
4. Elaborar as questões;
5. Clicar em "**Gravar**";
6. O botão "**Exportar**" permite gravar em um disco um arquivo eletrônico contendo todas as características do questionário selecionado.


[title] Parametrização do Sistema
[path] Administração da Plataforma/

A parametrização do sistema é utilizada para **alterar **as características da autenticação do sistema, para **informar **a URL do sistema, os **diversos diretórios** (GED, Log, Temporários), **definir **a tela inicial, **validar **a permissão dos botões (salvar, excluir e pesquisa), **ativar **o log do sistema (auditoria), **definir **a preferência de idioma e outros.&#x20;

## Procedimento

1. Acesse a funcionalidade através do menu principal `Parametrização > Sistema`;
2. Defina o valor dos parâmetros (atributos);
3. Clique em "**Salvar**";

A lista abaixo apresenta os parâmetros do sistema e a finalidade de cada um deles:

<table columnWidths="64,134,166,150,125" selectedRows="" selectedTable="false" isTableHeaderOn="true" selectedColumns="">
  <tr>
    <td align="center">
      <p><strong>#</strong></p>
    </td>
    <td align="center">
      <p><strong>Nome</strong></p>
    </td>
    <td align="center">
      <p><strong>Valores Possíveis</strong></p>
    </td>
    <td align="center">
      <p><strong>Propósito</strong></p>
    </td>
    <td align="center">
      <p><strong>Orientação Adicional</strong></p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p><strong>0</strong></p>
    </td>
    <td align="center">
      <p>SOURCE - Information Source Configuration (for data federation) - (Eg: 0)</p>
    </td>
    <td align="center">
      <p>Information Source Configuration (for data federation).</p>
    </td>
    <td align="center">
      <p>Se o valor do parâmetro não for inserido, não será possível exportar a Configuração de Gestão do Banco de Ddos (CMDB. Em inglês, Configuration Management Database).</p>
    </td>
    <td align="center">
    </td>
  </tr>
  <tr>
    <td align="center">
      <p><strong>15</strong></p>
    </td>
    <td align="center">
      <p>Internal GED (Eg: Y or N)</p>
    </td>
    <td align="center">
      <p>Y ou N</p>
    </td>
    <td align="center">
      <p>Informe se o Gerenciamento Eletrônico de Documentos utilizado é interno.
      Nota: Atualmente a única forma de utilização da gestão eletrônica de documentos é interna. Ao definir "<strong>Y</strong>" para Interno, o sistema criará a pasta definida pelo parâmetro 18 e criará uma subpasta com o ID da empresa e outra subpasta denominada "<strong>A</strong>". Os arquivos de gerenciamento eletrônico de documentos serão gravados nessas pastas.</p>
    </td>
    <td align="center">
      <p>Se for informado o valor "<strong>N</strong>" para o GED Interno, os arquivos não serão salvos corretamente, não serão salvos no local correto e não serão criptografados.</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p><strong>16</strong></p>
    </td>
    <td align="center">
      <p>Internal GED in Database (Eg: Y or N)</p>
    </td>
    <td align="center">
      <p>Y ou N</p>
    </td>
    <td align="center">
      <p>Informe se o Gerenciamento Eletrônico de Documentos (GED) utilizado é interno ao Banco de Dados</p>
    </td>
    <td align="center">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p><strong>17</strong></p>
    </td>
    <td align="center">
      <p>External GED - Treatment Class</p>
    </td>
    <td align="center">
    </td>
    <td align="center">
      <p>Informe a classe GED externa (Gestão Eletrônica de Documentos).</p>
    </td>
    <td align="center">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p><strong>18</strong></p>
    </td>
    <td align="center">
      <p>GED Directory (Eg: Windows - C:/gedCitsmart)</p>
    </td>
    <td align="center">
      <p>E.g.: Windows - C:/gedCitsmart</p>
    </td>
    <td align="center">
      <p>Defina o diretório para manipulação dos arquivos do Gerenciamento Eletrônico de Documentos (GED).</p>
    </td>
    <td align="center">
      <p>Se você não entrar no diretório GED, o gerenciamento eletrônico de documentos não funcionará, já que usa o diretório para criptografia de arquivos.</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p><strong>19</strong></p>
    </td>
    <td align="center">
      <p>Company Name</p>
    </td>
    <td align="center">
    </td>
    <td align="center">
      <p>Insira o nome da empresa</p>
    </td>
    <td align="center">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p><strong>22</strong></p>
    </td>
    <td align="center">
      <p>AUTHENTICATION METHOD (1 - Personal, 2 - LDAP) (Eg: 1)</p>
    </td>
    <td align="center">
      <p>E.g.: 1</p>
    </td>
    <td align="center">
      <p>Define which authentication method will be used in the system: 1 (Own) or 2 (LDAP).</p>
    </td>
    <td align="center">
      <p>If the LDAP authentication method is changed from 1 (Own) to LDAP, then there must be a synchronization between LDAP and CITSmart, at that time it is common to have duplication of employees and users in the database, which can cause problems in authentication and access profile.</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p><strong>32</strong></p>
    </td>
    <td align="center">
      <p>DB - Database SCHEMA name - (Eg: Postgres - public)</p>
    </td>
    <td align="center">
      <p>E.g.: Postgres - public</p>
    </td>
    <td align="center">
      <p>Enter the name of the Database Schema that will be used by the application.</p>
    </td>
    <td align="center">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p><strong>33</strong></p>
    </td>
    <td align="center">
      <p>System access URL</p>
    </td>
    <td align="center">
    </td>
    <td align="center">
      <p>Enter the URL system access.</p>
    </td>
    <td align="center">
      <p>If you do not enter the system URL correctly, some features will behave unexpectedly, for example, reports will not be generated.</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p><strong>44</strong></p>
    </td>
    <td align="center">
      <p>Upload Directory of the repositor path(Eg: Windows – C: /temp )</p>
    </td>
    <td align="center">
      <p>E.g.: Windows - C:/temp</p>
    </td>
    <td align="center">
      <p>Inform the directory to store the files that will be uploaded.</p>
    </td>
    <td align="center">
      <p>If you do not enter the directory correctly, you will not be able to attach the files to the system.</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p><strong>46</strong></p>
    </td>
    <td align="center">
      <p>CITSmart home screen? (Options: SD = Smart Decisions, SP = Smart Portal, EC = Centro de Experiência)</p>
    </td>
    <td align="center">
    </td>
    <td align="center">
      <p>Set the CITSmart** **home screen</p>
    </td>
    <td align="center">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p><strong>48</strong></p>
    </td>
    <td align="center">
      <p>Validate button permissions (save, delete and search) (Eg: Y or N).</p>
    </td>
    <td align="center">
      <p>Y or N</p>
    </td>
    <td align="center">
      <p>Set if it will validate the access permission of the buttons: Save, Delete, and Search. If it is, the access permission to the buttons (Save, delete, and search) defined in the access profile will be validated.</p>
    </td>
    <td align="center">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p><strong>52</strong></p>
    </td>
    <td align="center">
      <p>Enable logging on the system (Eg: 'true' or 'false')</p>
    </td>
    <td align="center">
      <p>E.g.: true or false</p>
    </td>
    <td align="center">
      <p>Enable Audit Log on the System.</p>
    </td>
    <td align="center">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p><strong>53</strong></p>
    </td>
    <td align="center">
      <p>Types: 'CIT_LOG' (log file), 'DB_LOG' (save in the database)</p>
    </td>
    <td align="center">
    </td>
    <td align="center">
      <p>Set the system log type "CIT_LOG" (logfile) or "DB_LOG" (save in the database). If the Log type is "CIT_LOG", the Log file is saved to a directory (defined in parameter 54). If the Log type is "DB_LOG", it will be saved to the Database.</p>
    </td>
    <td align="center">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p><strong>54</strong></p>
    </td>
    <td align="center">
      <p>Path of the folder that will be the LOG file (Eg: Linux -/var/tmp/)</p>
    </td>
    <td align="center">
      <p>E.g.: Linux - /var/tmp/</p>
    </td>
    <td align="center">
      <p>Inform the directory (folder) to store the Log files (CIT_LOG). When you set the value 'CIT_LOG' to parameter 53, you must define in this parameter the directory where the log file will be stored.</p>
    </td>
    <td align="center">
      <p>If you do not enter the directory, the Log files (CIT_LOG) will not be stored.</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p><strong>55</strong></p>
    </td>
    <td align="center">
      <p>Name of the log file (Eg: log_citsmart)</p>
    </td>
    <td align="center">
      <p>E.g.: log_citsmart</p>
    </td>
    <td align="center">
      <p>Define the name for the log file. The log files will be saved with the name as defined in the parameter.</p>
    </td>
    <td align="center">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p><strong>56</strong></p>
    </td>
    <td align="center">
      <p>Extension of the log file (Eg: txt)</p>
    </td>
    <td align="center">
      <p>E.g.: txt</p>
    </td>
    <td align="center">
      <p>Define the extension of the Log file. The Log files will be written with the TXT extension, as defined in the parameter.</p>
    </td>
    <td align="center">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p><strong>66</strong></p>
    </td>
    <td align="center">
      <p>Default system language (Eg: EN)</p>
    </td>
    <td align="center">
      <p>E.g.: EN = English</p>
    </td>
    <td align="center">
      <p>Set the default language to be used in the application.</p>
    </td>
    <td align="center">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p><strong>70</strong></p>
    </td>
    <td align="center">
      <p>Show xml import and export buttons in the menu bar. (Eg: Y or N - Default: 'Y')</p>
    </td>
    <td align="center">
      <p>Y or N (Default: S)</p>
    </td>
    <td align="center">
      <p>Define whether the XML import and export buttons are displayed on the Menu Registration screen. If "Y" is entered, the "Generate XML" and "Update Menus" buttons for XML import and export will be displayed in the "Menu Registration" screen.</p>
    </td>
    <td align="center">
      <p>If you do not enter the parameter value, the system default value will be set: "Y" (Yes).</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p><strong>71</strong></p>
    </td>
    <td align="center">
      <p>Parameter to read the default XML file from menus. (Eg: Y or N - Default: 'Y')</p>
    </td>
    <td align="center">
      <p>Y or N (Default: Y)</p>
    </td>
    <td align="center">
      <p>Enable reading of the XML file from menus. If enabled, the menu XML file will be read when the application starts.</p>
    </td>
    <td align="center">
      <p>If you do not enter the parameter value, the system default value will be set: "N" (No).</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p><strong>117</strong></p>
    </td>
    <td align="center">
      <p>Enter the path to save the table LOGDATA</p>
    </td>
    <td align="center">
    </td>
    <td align="center">
      <p>Define the directory to store the LOGDATE tables.</p>
    </td>
    <td align="center">
      <p>If you do not enter the directory correctly, you will not be able to store the LOGDATE tables.</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p><strong>118</strong></p>
    </td>
    <td align="center">
      <p>Default Contract ID for call opening.</p>
    </td>
    <td align="center">
    </td>
    <td align="center">
      <p>Inform the identification number (ID) of the contract to perform the opening of incidents/requests through the portal.</p>
    </td>
    <td align="center">
      <p>If you do not enter the value of the parameter, it is not possible to open the incident/request via the portal.</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p><strong>131</strong></p>
    </td>
    <td align="center">
      <p>Set the number of items that will be listed in the searches   (Default: 10)</p>
    </td>
    <td align="center">
    </td>
    <td align="center">
      <p>Define the amount of data that will be listed per page in the System Search screens.</p>
    </td>
    <td align="center">
      <p>There is no negative impact. If you do not enter the parameter value, the system default value is used: 10.</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p><strong>135</strong></p>
    </td>
    <td align="center">
      <p>Access Profile ID to be used as Administrator</p>
    </td>
    <td align="center">
    </td>
    <td align="center">
      <p>Enter the identification number (ID) of the access profile that will be used as the administrator for the validation of **ITSM <strong>CITSmart</strong> **updates. Only users related to the Access Profile defined in this parameter can access and validate the CTSmart ITSM version update.</p>
    </td>
    <td align="center">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p><strong>136</strong></p>
    </td>
    <td align="center">
      <p>Default URL logo of reports (Eg.: <a href="http://www.citsmart.com.br/imagens/logoPadraoReel.png">http://www.citsmart.com.br/imagens/logoPadraoReel.png</a>)</p>
    </td>
    <td align="center">
    </td>
    <td align="center">
      <p>Enter the URL of the image that will be used as a logo in the reports.</p>
    </td>
    <td align="center">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p><strong>198</strong></p>
    </td>
    <td align="center">
      <p>Path of the folder that will be the database LOG file (Eg.: Linux - /var /tmp/)</p>
    </td>
    <td align="center">
    </td>
    <td align="center">
      <p>Inform the directory (folder) to store the database LOG files.</p>
    </td>
    <td align="center">
      <p>If you do not enter the directory, you will not be able to store the database LOG files.</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p><strong>219</strong></p>
    </td>
    <td align="center">
      <p>Enable Automatic Data Migration</p>
    </td>
    <td align="center">
    </td>
    <td align="center">
      <p>Enable/disable the data import routine to run automatically.</p>
    </td>
    <td align="center">
      <p>With the parameter enabled, it will enable a thread that will be executed, which in addition to decreasing performance, can write error messages in the system logs if the data import is not correctly registered. If you enter "N", it will not automatically import data.</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p><strong>223</strong></p>
    </td>
    <td align="center">
      <p>E-mail Configuration of the CITSmart** **Support</p>
    </td>
    <td align="center">
      <p>E.g.: <a href="mailto:suporte.citsmart@citsmart.com">suporte.citsmart@citsmart.com</a></p>
    </td>
    <td align="center">
      <p>Set the CITSmart** **support email that will be displayed in the information bar. Note: The system allows you to add one or more support e-mails.</p>
    </td>
    <td align="center">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p><strong>224</strong></p>
    </td>
    <td align="center">
      <p>Phone Configuration of the CITSmart** **Support</p>
    </td>
    <td align="center">
      <p>E.g.: +55 (61) 3966-4349</p>
    </td>
    <td align="center">
      <p>Set the CITSmart** **support phone number to be displayed in the information bar. Note: The system allows you to add one or more support phone numbers.</p>
    </td>
    <td align="center">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p><strong>225</strong></p>
    </td>
    <td align="center">
      <p>Email Configuration of the CITSmart** **Support Login Screen</p>
    </td>
    <td align="center">
      <p>E.g.: <a href="mailto:suporte.citsmart@citsmart.com">suporte.citsmart@citsmart.com</a></p>
    </td>
    <td align="center">
      <p>Set the CITSmart** **support email to be displayed on the login screen. Note: The system allows you to add one or more support e-mails.</p>
    </td>
    <td align="center">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p><strong>226</strong></p>
    </td>
    <td align="center">
      <p>Phone Configuration of the CITSmart** **Support Login Screen</p>
    </td>
    <td align="center">
      <p>E.g.: +55 (61) 3966-4349</p>
    </td>
    <td align="center">
      <p>Set the CITSmart** **support phone number to be displayed on the login screen. Note: The system allows you to add one or more support phone numbers.</p>
    </td>
    <td align="center">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p><strong>235</strong></p>
    </td>
    <td align="center">
      <p>Use Autocomplete in the unit field on the Employee and Unit screens. (Y or N - Default: 'N')</p>
    </td>
    <td align="center">
      <p>Y or N (Default: N)</p>
    </td>
    <td align="center">
      <p>Set if the screen object for the Drive field will be an Auto Complete (value = Y) or a checkbox (combobox) (value = N).</p>
    </td>
    <td align="center">
      <p>Change how the user selects the unit in the Service Request, Problem Registration, and Request for Change screens. This parameter will not reflect the Unit field of the Service Request screen.</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p><strong>244</strong></p>
    </td>
    <td align="center">
      <p>Home screen message</p>
    </td>
    <td align="center">
    </td>
    <td align="center">
      <p>Enter a message that will appear on the System Login screen.</p>
    </td>
    <td align="center">
      <p>When the parameter is not configured, the default message will be displayed on the Login screen.</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p><strong>254</strong></p>
    </td>
    <td align="center">
      <p>API Key for use of Google services</p>
    </td>
    <td align="center">
    </td>
    <td align="center">
      <p>Enter the key that registers the consumption of Google services.</p>
    </td>
    <td align="center">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p><strong>266</strong></p>
    </td>
    <td align="center">
      <p>Default calendar ID</p>
    </td>
    <td align="center">
    </td>
    <td align="center">
      <p>Set the default calendar for use in task recovery filters.</p>
    </td>
    <td align="center">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p><strong>271</strong></p>
    </td>
    <td align="center">
      <p>Enter the city of installation of the system:</p>
    </td>
    <td align="center">
    </td>
    <td align="center">
      <p>Enter the name of the city that will appear in the system reports.</p>
    </td>
    <td align="center">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p><strong>275</strong></p>
    </td>
    <td align="center">
      <p>Always keep the system in English?</p>
    </td>
    <td align="center">
      <p>Y or N (Default: N)</p>
    </td>
    <td align="center">
      <p>Set if the system language will be in English only.</p>
    </td>
    <td align="center">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p><strong>276</strong></p>
    </td>
    <td align="center">
      <p>URL Powr BI Report</p>
    </td>
    <td align="center">
    </td>
    <td align="center">
      <p>Inform the URL of the Power BI tool for building dynamic reports for ITIL processes. When you enter the URL of the tool, when you access the "Power BI Manager Reports" functionality, the reporting tool will be displayed.</p>
    </td>
    <td align="center">
      <p>If you do not enter the parameter value, you will not have access to the Power Bi tool.</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p><strong>277</strong></p>
    </td>
    <td align="center">
      <p>Allow the registration of an employee with the same name? Values: "Y" for "Yes" and "N" for "No". Default: "N"</p>
    </td>
    <td align="center">
      <p>Y or N (Default: N)</p>
    </td>
    <td align="center">
      <p>Define if the registration of an employee will be allowed with a name similar to another employee. When its value is "Y", the system allows the user to register an employee with the same name as another employee already registered, but with a different ID. It also makes the ID field mandatory. When the value "N" is entered, the system does not allow a user with a name similar to another registered user to be registered.</p>
    </td>
    <td align="center">
      <p>If the value for the parameter is not set, the value "N" will be automatically set by the system.</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p><strong>278</strong></p>
    </td>
    <td align="center">
      <p>Tamanho máximo de arquivos, em bytes, para upload. Default [1073741824]</p>
    </td>
    <td align="center">
    </td>
    <td align="center">
      <p>Limite do número de bytes que podem ser carregados por arquivo nas telas de anexo do sistema.</p>
    </td>
    <td align="center">
      <p>O tamanho do arquivo que será carregado em anexos nas telas de requisição, problema, mudança, release, continuidade e painel de controle BI será limitado.</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p><strong>297</strong></p>
    </td>
    <td align="center">
      <p>Disables sending system emails (Values: "Y" or "N" Default: "N"</p>
    </td>
    <td align="center">
      <p>Y or N (Default: N)</p>
    </td>
    <td align="center">
      <p>Disables all system email submissions.</p>
    </td>
    <td align="center">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p><strong>318</strong></p>
    </td>
    <td align="center">
      <p>Lista de extensões de arquivo que não podem ser anexadas (para mais de uma extensão, use ;)</p>
    </td>
    <td align="center">
    </td>
    <td align="center">
      <p>Lista de extensões de arquivo que não podem ser anexadas.</p>
    </td>
    <td align="center">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p><strong>319</strong></p>
    </td>
    <td align="center">
      <p>Enable Remote Access</p>
    </td>
    <td align="center">
    </td>
    <td align="center">
      <p>URL to open remote access screen</p>
    </td>
    <td align="center">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p><strong>320</strong></p>
    </td>
    <td align="center">
      <p>Category ID Gallery for uploading the images added in the editor (Eg: 1)</p>
    </td>
    <td align="center">
      <p>E.g.: 1</p>
    </td>
    <td align="center">
      <p>Set the gallery ID that will be used to upload images added in the editor</p>
    </td>
    <td align="center">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p><strong>331</strong></p>
    </td>
    <td align="center">
      <p>Enable Google Maps API</p>
    </td>
    <td align="center">
      <p>Y or N</p>
    </td>
    <td align="center">
      <p>Activate Google Maps API</p>
    </td>
    <td align="center">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p><strong>334</strong></p>
    </td>
    <td align="center">
      <p>Path to Start Logo (Eg: /citsmart/path/logo.png)</p>
    </td>
    <td align="center">
      <p>E.g.: /citsmart/path/logo.png</p>
    </td>
    <td align="center">
      <p>It allows the login screen logo to be changed.</p>
    </td>
    <td align="center">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p><strong>335</strong></p>
    </td>
    <td align="center">
      <p>Path to Portal Logo (Eg: /citsmart/path/logo-portal.png)</p>
    </td>
    <td align="center">
      <p>E.g.: /citsmart/path/logo-portal.png</p>
    </td>
    <td align="center">
      <p>It allows the Portal logo to be changed.</p>
    </td>
    <td align="center">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p><strong>336</strong></p>
    </td>
    <td align="center">
      <p>Path to the System Logo (Eg: /citsmart/path/logo-system.png)</p>
    </td>
    <td align="center">
      <p>E.g.: /citsmart/path/logo-sistema.png</p>
    </td>
    <td align="center">
      <p>It allows the System logo to be changed.</p>
    </td>
    <td align="center">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p><strong>337</strong></p>
    </td>
    <td align="center">
      <p>Make the 'Physical Location' field mandatory in the Y or N Service register (default N)</p>
    </td>
    <td align="center">
    </td>
    <td align="center">
      <p>Make the 'Physical Location' field mandatory in the Service register</p>
    </td>
    <td align="center">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p><strong>341</strong></p>
    </td>
    <td align="center">
      <p>Contact setup for Ombudsman on the login screen</p>
    </td>
    <td align="center">
    </td>
    <td align="center">
      <p>It allows informing the telephone/e-mail of the Ombudsman, information that will appear in the login screen of the system.</p>
    </td>
    <td align="center">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p><strong>344</strong></p>
    </td>
    <td align="center">
      <p>Ombudsman - Default URL for screen logo</p>
    </td>
    <td align="center">
    </td>
    <td align="center">
      <p>It allows informing the link of a logo to the Ombudsman screen.</p>
    </td>
    <td align="center">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p><strong>345</strong></p>
    </td>
    <td align="center">
      <p>Ombudsman - Reporting service ID</p>
    </td>
    <td align="center">
    </td>
    <td align="center">
      <p>It allows informing the code of the denunciation activity of a portfolio used in the opening of an Ombudsman ticket.</p>
    </td>
    <td align="center">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p><strong>346</strong></p>
    </td>
    <td align="center">
      <p>Ombudsman - Complaint Service ID</p>
    </td>
    <td align="center">
    </td>
    <td align="center">
      <p>It allows informing the code of the complaint activity of a portfolio used in the opening of an Ombudsman ticket.</p>
    </td>
    <td align="center">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p><strong>347</strong></p>
    </td>
    <td align="center">
      <p>Ombudsman - suggestion service ID</p>
    </td>
    <td align="center">
    </td>
    <td align="center">
      <p>It allows informing the code of the suggestion activity of a portfolio used in the opening of an Ombudsman ticket.</p>
    </td>
    <td align="center">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p><strong>348</strong></p>
    </td>
    <td align="center">
      <p>Ombudsman - User login for authentication</p>
    </td>
    <td align="center">
    </td>
    <td align="center">
      <p>It allows informing the user requester used in the opening of an Ombudsman ticket.</p>
    </td>
    <td align="center">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p><strong>349</strong></p>
    </td>
    <td align="center">
      <p>Ombudsman - Contact Origin ID</p>
    </td>
    <td align="center">
    </td>
    <td align="center">
      <p>It allows informing the origin code of the call used in the opening of an Ombudsman ticket.</p>
    </td>
    <td align="center">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p><strong>370</strong></p>
    </td>
    <td align="center">
      <p>Enable automatic email authentication via token</p>
    </td>
    <td align="center">
    </td>
    <td align="center">
      <p>It allows you to turn on or off the system's ability to receive token authentication.</p>
    </td>
    <td align="center">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p><strong>378</strong></p>
    </td>
    <td align="center">
      <p>The minimum amount of registries that determines the generation of the report in the background.</p>
    </td>
    <td align="center">
      <p>E.g.: from 50.000 registries</p>
    </td>
    <td align="center">
      <p>Set a limit from which reports will be generated in the background.</p>
    </td>
    <td align="center">
      <p>It causes reports on the Advanced Search screen to be generated in the background and when they are ready, a notification is sent to the user with a download link to the file.</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p><strong>383</strong></p>
    </td>
    <td align="center">
      <p>Enable login domain listing</p>
    </td>
    <td align="center">
      <p>E.g.: citsmart.com\ariadner.borges</p>
    </td>
    <td align="center">
      <p>It allows to show or hide the list of domains on the login screen for security reasons. If the parameter is enabled, and the user enters a domain, the domain will be changed to type. If the user has typed a domain and changed the listing, the typed domain will also be changed. </p>
    </td>
    <td align="center">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p><strong>384</strong></p>
    </td>
    <td align="center">
      <p>Query Timeout to Webservice DATA_QUERY</p>
    </td>
    <td align="center">
      <p>"Default:0"</p>
    </td>
    <td align="center">
      <p>Maximum waiting time for the query response using Webservice DATA_QUERY</p>
    </td>
    <td align="center">
      <p>The time set in the system is in seconds: 0 to 2.147.483.647 seconds.</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p><strong>385</strong></p>
    </td>
    <td align="center">
      <p>Enable Related Request Creation as Copy</p>
    </td>
    <td align="center">
      <p>Y or N</p>
    </td>
    <td align="center">
      <p>It allows seeing the "create related request by copy" button on the internal service request screen. This button will open the screen to create a related request by copying the description, requester, attachments, related knowledge, and configuration items from the main service request.</p>
    </td>
    <td align="center">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p><strong>390</strong></p>
    </td>
    <td align="center">
      <p>Default unit ID</p>
    </td>
    <td align="center">
    </td>
    <td align="center">
      <p>Unit ID that will be assigned to the user registered in the profile</p>
    </td>
    <td align="center">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p><strong>400</strong></p>
    </td>
    <td align="center">
      <p>Smart Analytics – URL Schema Gen</p>
    </td>
    <td align="center">
    </td>
    <td align="center">
      <p>Parameter deprecated from version 9.0</p>
    </td>
    <td align="center">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p><strong>401</strong></p>
    </td>
    <td align="center">
      <p>Smart Analytics – external URL</p>
    </td>
    <td align="center">
    </td>
    <td align="center">
      <p>Path to BI Access</p>
    </td>
    <td align="center">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p><strong>402</strong></p>
    </td>
    <td align="center">
      <p>Anuva Assistant – external URL</p>
    </td>
    <td align="center">
    </td>
    <td align="center">
      <p>Path for external access to Anuva</p>
    </td>
    <td align="center">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p><strong>403</strong></p>
    </td>
    <td align="center">
      <p>Use SSO login authentication</p>
    </td>
    <td align="center">
      <p>Y or N</p>
    </td>
    <td align="center">
      <p>It allows using Single Sign-On to login to the system</p>
    </td>
    <td align="center">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p><strong>405</strong></p>
    </td>
    <td align="center">
      <p>Machine Learning Configuration</p>
    </td>
    <td align="center">
    </td>
    <td align="center">
      <p>It allows using Machine Learning to open calls. <em>NOTE: This parameter is found in the "<em>CITSmart</em></em>* ***<em>Parameters" feature</em></p>
    </td>
    <td align="center">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p><strong>409</strong></p>
    </td>
    <td align="center">
      <p>LDAP - Attribute representing the immediate superior of the user</p>
    </td>
    <td align="center">
    </td>
    <td align="center">
    </td>
    <td align="center">
      <p>Não se aplica</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p><strong>449</strong></p>
    </td>
    <td align="center">
      <p>User Session Time (In Minutes)</p>
    </td>
    <td align="center">
      <p>E.g.: 120 minutes</p>
    </td>
    <td align="center">
      <p>Set expiration time for application sessions</p>
    </td>
    <td align="center">
      <p>Include in minutes the value you want for the session duration. After that, you need to disconnect and reconnect to the system, so the system will look for the new default for the session expiration time.</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p><strong>450</strong></p>
    </td>
    <td align="center">
      <p>Enable Anuva Assistant</p>
    </td>
    <td align="center">
      <p>Y or N</p>
    </td>
    <td align="center">
      <p>Whether or not to enable Anuva in CITSmartWorkflow</p>
    </td>
    <td align="center">
      <p>The parameter reflects directly on the external Smart Chat (Experience Center and Smart Portal) and the internal button in the system header where the button is shown to talk to Anuva.</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p><strong>485</strong></p>
    </td>
    <td>
      <p>Number of times a Ticket has been assigned </p>
    </td>
    <td>
    </td>
    <td align="center">
      <p>Receives the number of times the adminstrator wants to monitor the ticket assignment;</p>
    </td>
    <td>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p><strong>486</strong></p>
    </td>
    <td>
      <p>Email template for notice of attribution Amount</p>
    </td>
    <td>
    </td>
    <td align="center">
      <p>Receives the id number of the email template created to notify about the number of assignments a ticket has had on a given task</p>
    </td>
    <td>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p><strong>487</strong></p>
    </td>
    <td>
      <p>Group for warning about the amount of assignments</p>
    </td>
    <td>
    </td>
    <td align="center">
      <p>Receives the id of the group that should receive notification about the amount of attribution a given ticket</p>
    </td>
    <td>
    </td>
  </tr>
</table>


[title] Problema
[path] Administração da Plataforma/Automatização /Cadastrar ação automática/

Alguns eventos irão apresentar uma situação onde a ação apropriada precisará ser tratada pelo processo de gerenciamento de problema, ou seja, esta funcionalidade tem como objetivo realizar o cadastro de ações automáticas do tipo problema. Este cadastro será associado às ações automáticas, onde será usado nos cadastros de gerentes de eventos do CITSmart Nagios, Zabbix, Inventory e Eventos Correlacionados.

Esta funcionalidade disponibiliza ações diversas, tais como, incluir, alterar e excluir ações automáticas do tipo problema.

## Antes de começar

- [x] Para cadastrar uma ação automática de mudança é preciso registrar previamente o grupo, a unidade, o solicitante(colaborador), o contrato e o mesmo estar vinculado ao colaborador e a unidade, a categoria de problema e a mesma estar vinculada ao fluxo referente ao problema.

## Procedimento

1. Acessar a funcionalidade através da navegação no menu principal `Sistema > Ações Automáticas > Ações de Problema;`
2. Preencher os campos disponibilizados;
3. Clicar em "**Gravar**".

### **Inclusão de Informações e Notificação por E-mail**

**Inserção de Informações Detalhadas:**

Todas as informações adicionais que o usuário deseja compartilhar com o solicitante devem ser inseridas na seção "Outras Informações" do formulário de registro de problema.&#x20;

**Notificação por E-mail para o Solicitante:**

Após preencher todos os campos necessários e adicionar informações ao campo "Outras Informações", a solicitação será gravada. Automaticamente, o sistema enviará um e-mail para o solicitante contendo todas as informações registradas, incluindo os detalhes inseridos na seção "Outras Informações".&#x20;

[title] Gerenciar a indexação de conteúdo
[path] Administração da Plataforma/Untitled/

O CITSmart usa o Apache SOLR para indexar o conteúdo criado na Gerência de Conhecimento e o disponibiliza no sistema de busca do Portal de Conhecimento.

## O que fazer antes

Para que a Indexação de conhecimento funcione corretamente é necessário:

- [x] Instalar o componente Apache SOLR como apresentado no manual de instalação.

## Parametrizar o serviço de indexação

1. Acessar o menu principal `Parametrização > Parâmetros CITSmart;`
2. Configurar o parâmetro 304 informando a URL do componente SOLR;
3. Configurar o parâmetro 308 informando a quantidade de itens a serem indexados por vez;
4. Configurar o parâmetro 332 informando se a sincronização com o servidor de Indexação está ativa;
5. Configurar o Parâmetro 333 informando o intervalo em minutos para sincronizar os conhecimentos com o servidor de indexação – Valores aceitos entre 1 e 59;
6. Acessar o menu principal `Sistema > Configurações > Gerência do Conhecimento (Indexação)` e clicar em "**Atualizar o servidor de indexação**".

## Gerenciar conteúdo

1. Acessar o menu principal `Sistema > Configurações > Gerência do Conhecimento (Indexação);`
2. Para indexar os conhecimentos disponíveis, clicar em "**Indexar base de conhecimento**", ou para remover os conhecimentos já indexados, clicar em "**Remover indexação base conhecimento**".


[title] Configurar logotipo do banner
[path] Administração da Plataforma/Untitled/

É possível alterar o banner no seu ambiente para que o CITSmart tenha a identidade da sua empresa.

## Procedimento

1. Acessar o menu principal `Sistema > Configurações > Configurações de Ambiente;`
2. Para alterar uma das imagens (logotipo inicial, logotipo do portal, logotipo do sistema e logotipo do relatório), clicar em "**Selecione uma imagem**";
3. Clicar na caixa pontilhada para arrastar um arquivo ou fazer o upload;
4. Clicar em "**Gravar**".

:::hint{type="info"}
**Dica: **Para alterar o ícone de carregamento, altere o valor do parâmetro 387 para "SIM". `Parametrização > Parâmetros CITSmart > 387.`
:::


[title] Cadastrar modelo de planilha para importação de colaborador
[path] Administração da Plataforma/Untitled/

Esta funcionalidade foi implementada com o intuito de permitir uma carga direta na tabela de colaboradores. O sistema avisa caso algum campo obrigatório não seja preenchido e não lê o arquivo até que seja dada manutenção.

## Procedimento

1. Acessar a funcionalidade através do menu `Sistema > Importação e Carga de Dados > Carga Colaborador;`
2. Clicar na aba **Modelo de planilha para importação**;
3. Preencher os campos disponibilizados e considerar que nos campos obrigatórios, o sistema não permite deletar do XLS que será gerado para que sejam imputadas as informações;
4. O campo "**Active**" permite que seja colocado no XLS todos os colaboradores como ativos;
5. Para gerar modelo de planilha em formato ".xls", clicar no botão "Gerar Modelo .xls";
6. Para gerar modelo de planilha em formato ".xlsx", clicar no botão "Gerar Modelo .xlsx".


[title] Template de Recursos
[path] Administração da Plataforma/

Este é um cadastro de templates de recursos. Os **recursos **são elementos importantes para a configuração dos tenants (inquilinos ou clientes que usam espaços na plataforma).

Desse modo, os recursos podem representar: **Banco de dados,** **Sistema de Arquivos, entre outros. **

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/kS8QIEgR52PJ-vWdgm6qH_image.png "Tela de Cadastro de template")

> ***Exemplo***
>
> **:**
>
>  Podemos criar um template de recursos chamando de "
>
> **Banco de dados**
>
> ". 
> Este pode conter todos os campos necessários para configurar o recurso de banco de dados (URL do servidor, nome do BD, senha, etc...)


[title] Cadastrar item de domínio
[path] Administração da Plataforma/Untitled/

A funcionalidade de Itens de Domínio tem por objetivo permitir a customização das opções do campo de uma determinada tela do sistema. Para utilizar a mesma, deverá ter conhecimento sobre a codificação do sistema.

Esta funcionalidade disponibiliza ações diversas, tais como, incluir, alterar e excluir item de domínio.

## Antes de começar

- [x] O registro de item de domínio requer o cadastro do domínio previamente.

## Procedimento

1. Acessar a funcionalidade através da navegação no menu principal `Sistema > Domínios > Itens de Domínio;`
2. Clicar no botão "**Novo**";
3. Preencher os campos disponibilizados;
4. Clicar em "**Gravar**".


[title] Automatização 
[path] Administração da Plataforma/

## Processamento Batch

Esta funcionalidade tem o objetivo de registrar a utilização de processamento batch, que poderá ser utilizado em outras rotinas do sistema.

Rotinas como:

- Verificação de e-mail
- Verificação da hora do servidor
- Distribuição automática de Tickets com balanceamento carga de trabalho

## Antes de Começar

- [x] O processamento Batch do CITSmart utiliza o Quartz para o agendamento e processamento de rotinas de sistema. Sendo assim, antes de utilizar qualquer rotina batch é necessário configurar o Quartz.

## Procedimento

1. Acessar a funcionalidade através da navegação no menu principal `Sistema > Processamento Batch;`
2. Clicar no botão "**Novo**";
3. Preencher os campos disponibilizados (descrição, tipo \[classe Java, RhinoScript, SQL]; situação; expressão cron que define o horário de execução da rotina e o conteúdo da rotina, onde será descrito o contexto da rotina a ser executada na ferramenta);
4. Clicar em "Gravar".

## Rotinas Batch

- Retornar horário do Servidor
  - Tipo: RhinoScript
  - Conteúdo:
- Realizar leitura de e-mail
  - Tipo: Classe Java
  - Conteúdo:

```java
br.com.centralit.citcorpore.quartz.job.JobConfiguracaoAberturaAutomaticaViaEmail
```


[title] Mudança
[path] Administração da Plataforma/Automatização /Cadastrar ação automática/

Alguns eventos irão apresentar uma situação onde a ação apropriada precisará ser tratada pelo processo de gerenciamento de mudança, ou seja, esta funcionalidade tem como objetivo realizar o cadastro de ações automáticas do tipo mudança. Este cadastro será associado às ações automáticas, onde será usado nos cadastros de gerentes de eventos do CITSmart Nagios, Zabbix, Inventory e Eventos Correlacionados.

Esta funcionalidade disponibiliza ações diversas, tais como, incluir, alterar e excluir ações automáticas do tipo mudança.

## Antes de começar

- [x] Para cadastrar uma ação automática de mudança é preciso registrar previamente a unidade, o solicitante (colaborador), o contrato e o mesmo estar vinculado ao colaborador e a unidade;&#x20;
- [x] O Comitê Consultivo de Mudanças (grupo) e a mesma estar vinculada ao fluxo referente a mudança;&#x20;
- [x] Configurar os parâmetros 47, 279 e 280 referentes a mudança.

## Procedimento

1. Acessar a funcionalidade através da navegação no menu principal `Sistema > Ações Automáticas > Ações de Mudança;`
2. Preencher os campos disponibilizados;
3. Clicar em "**Gravar**".

## **Ação Automática para Mudanças**

No menu "Automatização", para mudanças normais, temos um formulário padrão que inclui as seguintes funcionalidades:

Perguntas obrigatórias, além de perguntas com formato check-Box e formato option button, pesos para respostas da análise de risco e análise de risco por categoria de mudança com parametrização das faixas de risco, além de campos para comentários dos usuários e ainda informações adicionais.

Cada categoria de mudança pode ter sua própria análise de risco configurada. Isso significa que o usuário pode personalizar a análise de risco de acordo com as características específicas de cada tipo de mudança.

:::hint{type="info"}
**Nota:** Ao preencher o formulário de mudança, o usuário pode selecionar as opções relevantes na pesquisa de risco, atribuir pesos às respostas, adicionar comentários e categorizar a mudança com base na análise de risco.
:::


[title] Menus (Associar papéis)
[path] Administração da Plataforma/

Além de associar a versão de Apps, é também necessário também "**vincular papéis**". Para isso, vincule primeiro o cliente:&#x20;

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/gG9mi4HKEovQQSbWjf3w6_image.png)



***

Escolha a **CITSmart **pois é onde está vinculado o **Tenant frontManager.**

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/XTdP22ubmDarWvw6gyEqb_image.png)

***

Em seguida, faça o gerenciamento do **Tenant frontManager **e escolha a aplicação que deseja gerenciar. Como por exemplo, Workflow e ESM

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/Fh5Hb3g-nVno_jlBFroQo_image.png)



:::hint{type="info"}
🖊 ***Nota*****: **Associe os **Roles **de acordo com suas necessidades. Lembrando que esses provêm do software gerenciador de acesso. Após associar as Roles, o item de menu irá agora ser exibido no menu conforme as configurações que foram realizadas no sistema.
:::


[title] Região
[path] Administração da Plataforma/

Aqui é possível encontrar as **regiões **já cadastradas no sistema. Além disso, é também possível **registrar **uma nova região ou **excluir **a que já estiver cadastrada.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/7JvgoInjQ5-rQLsQCzBBf_image.png "Hyper - Regiões")

***

Na aba "**Região**", é tanto possível registrar um novo país, como exportar um arquivo **.csv** contendo as informações das regiões já cadastradas no sistema.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/YkwU5ifPqCeVa0mcDjzsU_image.png" size="64" width="492" height="47" caption="Botões Registar e Exportar CSV" position="center" signedSrc="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/YkwU5ifPqCeVa0mcDjzsU_image.png"}

Além disso, é possível editar e excluir uma região, escreva o nome da região desejada ou simplesmente a **ID da Região **no campo de busca e prossiga com a ação clicando em "**Editar**"**.**

***

- Ao clicar em "**Editar**", é possível realizar as alterações desejadas;

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/dXwGR_51nUdNGlCxbLY2Q_image.png)

<table columnWidths="217,527,248" selectedRows="" selectedTable="false" isTableHeaderOn="true" selectedColumns="">
  <tr>
    <td>
      <p><strong>Campos</strong></p>
    </td>
    <td>
      <p><strong>Descrição</strong></p>
    </td>
  </tr>
  <tr>
    <td>
      <p><strong>Nome</strong>*</p>
    </td>
    <td>
      <p>Adicione uma nova região: <strong>São Paulo/BR</strong></p>
    </td>
  </tr>
  <tr>
    <td>
      <p><strong>Estado</strong></p>
    </td>
    <td>
      <p>É possível registrar ou editar um estado</p>
    </td>
  </tr>
  <tr>
    <td>
      <p><strong>Situação</strong>*</p>
    </td>
    <td>
      <p><strong>Ativo</strong> ou <strong>Inativo</strong></p>
    </td>
  </tr>
</table>

As informações com asterisco (\*) são obrigatórias.

***

- Após concluir todas as alterações, clique em "**Registro**".


[title] Menus (Manutenção de Itens)
[path] Administração da Plataforma/

O **Menu **é uma representação de uma funcionalidade de uma determinada aplicação (que será disponibilizada aos usuários).

As **aplicações**, conforme explicado em "**Aplicações**" (veja cadastro de [Aplicações](docId\:H8be6L0e7mnv5M48G8kAn)), são disponibilizadas através de **versões**. Nesse sentido, cada versão tem um conjunto de opções de funcionalidades, portanto essas opções são itens de menus.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/VNjOZC_gRAYlTNhrpvy-W_image.png)

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/a3s9jNSkE3C0WRjbPPV16_image.png" size="72" width="492" height="47" caption position="center" signedSrc="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/a3s9jNSkE3C0WRjbPPV16_image.png"}

- Para inserir itens no menu, clique em "**Registrar**" e escolha a aplicação que deseja conforme a imagem abaixo:

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/8uucCF1q8gjnQzLnKgO5q_image.png "Agile Work Management (1) ou (2) ou Workflow & ESM ")

- Em seguida, complete os campos necessários e clique em "**Salvar**" quando concluir:

<table columnWidths="134,609,248" selectedRows="" selectedTable="false" isTableHeaderOn="true" selectedColumns="">
  <tr>
    <td>
      <p><strong>Campos</strong></p>
    </td>
    <td>
      <p><strong>Descrição</strong></p>
    </td>
  </tr>
  <tr>
    <td>
      <p><strong>ID Aplicação</strong></p>
    </td>
    <td>
      <p>13</p>
    </td>
  </tr>
  <tr>
    <td>
      <p><strong>Aplicação</strong></p>
    </td>
    <td>
      <p>Workflow &#x26; ESM</p>
    </td>
  </tr>
  <tr>
    <td>
      <p><strong>Menu Pai</strong></p>
    </td>
    <td>
      <p>Gerência de Ticket</p>
    </td>
  </tr>
  <tr>
    <td>
      <p><strong>Título</strong>*</p>
    </td>
    <td>
      <p>Práticas Unificadas</p>
    </td>
  </tr>
  <tr>
    <td>
      <p><strong>Descrição</strong></p>
    </td>
    <td>
      <p>Práticas Unificadas</p>
    </td>
  </tr>
  <tr>
    <td>
      <p><strong>Caminho</strong></p>
    </td>
    <td>
      <p>**Exemplo: **/pages/practiceUnified/practiceUnified.load</p>
    </td>
  </tr>
  <tr>
    <td>
      <p><strong>Observação</strong></p>
    </td>
    <td>
      <p>Adicione uma observação</p>
    </td>
  </tr>
  <tr>
    <td>
      <p><strong>Render</strong>*</p>
    </td>
    <td>
      <p>Informação de como será a renderização. Selecione: <strong>Legado iframe</strong>; <strong>Microfront-End</strong>; <strong>Microfront-End por Iframe</strong>; <strong>SPA</strong></p>
    </td>
  </tr>
  <tr>
    <td>
      <p><strong>Estado</strong></p>
    </td>
    <td>
      <p><strong>Ativo</strong> ou <strong>Inativo</strong>. Se colocar como inativa, a aplicação não será exibida no menu das aplicações</p>
    </td>
  </tr>
  <tr>
    <td>
      <p><strong>Ordem</strong>*****</p>
    </td>
    <td>
      <p>5 (Essa ordem será utilizada na apresentação dos itens de menus)</p>
    </td>
  </tr>
  <tr>
    <td>
      <p><strong>Ícone</strong></p>
    </td>
    <td>
      <p>Adicione uma imagem</p>
    </td>
  </tr>
</table>

As informações com asterisco (\*) são obrigatórias.

:::hint{type="info"}
🖊 ***Nota*****: **O item de menu é formado pelo link da versão da aplicação (Exemplo: [https://frontmanager.apps.centralit.co[m.br/citsmart](https://frontmanager.apps.centralit.com.br/citsmart)](https://frontmanager.apps.centralit.com.br/) ) acrescentado do caminho do menu (exemplo: **/pages/practiceUnified/practiceUnified.load**). Neste caso o caminho será: **https\://frontmanager.apps.centralit.com.br/citsmart/pages/practiceUnified/practiceUnified.load**


:::

Foi criado então um item chamado **Prática Unificadas**. Porém para ser mostrado no menu é necessário <a href="https://docs.citsmart.com/hyper/menus-associar-versao-de-apps" target="_blank">associar o item a uma versão</a>.


[title] Configurar as opções de menu no mobile
[path] Administração da Plataforma/Mobile/

Esta funcionalidade tem por objetivo configurar as opções de Menu para o uso via mobile. Ao configurar estas opções, as mesmas estarão disponíveis no aplicativo CITSmart Experience e no site ITSM na versão mobile.

:::hint{type="warning"}
**Atenção**

O aplicativo Experience permite utilizar as funcionalidades da versão web escolhidas na versão mobile, tendo as mesmas funções que a versão desktop. &#x20;
:::

## Antes de começar

- [x] É necessário instalar, previamente, o aplicativo CITSmart Experience no dispositivo mobile.

## Procedimento

1. Acessar a funcionalidade através da navegação no menu principal `Acesso e permissão > Configuração das opções de mobile;`
2. Clicar no botão "**Novo**";
3. Preencher os campos necessários (título, a situação, a descrição nas três línguas do CITSmart \[português, inglês e espanhol] e selecionar o menu que melhor se ajusta à funcionalidade desejada);
4. Clicar em "**Gravar**" para efetuar a operação.


[title] Idioma e Região
[path] Administração da Plataforma/

Esta funcionalidade destina-se a configurar o idioma padrão do sistema.

## Procedimento

1. Acesse a funcionalidade através do menu principal `Parametrização > Parâmetros CITSmart;`
2. Pesquisar o parâmetro 66, setar o valor EN para o idioma Inglês, ES para Espanhol e PT para Português;
3. Clicar em "**Gravar**".

### Manter o sistema sempre em Inglês

1. Acessar a funcionalidade através do menu principal `Parametrização > Parâmetros CITSmart;`
2. Pesquisar o parâmetro 275;
3. Selecionar "**Sim**";
4. Clicar em "**Gravar**".


[title] Manutenção de Questionários
[path] Administração da Plataforma/Untitled/

Questionários são instrumentos que podem ser usados para coletar informações. No CITSmart Platform, eles podem ser usados para capturar informações no início de um atendimento (Gerenciamento de Ticket) e servir como recurso para a aplicação de listas de verificação nos processos de Mudança, Liberação e Problema.


[title] Papéis
[path] Administração da Plataforma/

"**Papel**" representa o papel que o usuário pode executar dentro da plataforma ou aplicações.

Esta área permite a criação dos papéis (perfis de acesso) que os usúários ou grupos de usuários terão para um determinado ambiente, aplicação (lowcode, ITSM, CHATBOT, etc), bem como menus, submenus e acessos.


Os papeís também são considerados perfils de usuários que também definem quais os acessos podem ser concedicos para pessoas ou grupos específicos.&#x20;

:::hint{type="info"}
🖊 ***Nota:*** Dentro da plataforma ou aplicações, algumas **ações** só podem ser executadas por usuários que possuem determinado papel vinculado (role vinculado).&#x20;
:::

Abaixo é possível encontrar os papeis (**roles) **que estão cadastrados no sistema. É possível registrar um novo papel (**roles) **ou excluir algum já cadastrado. É um item muito importante uma vez que será vinculado após a associação com a versão de Apps.&#x20;

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/yLwkvItA_VSa44X_lVxzf_image.png)

:::hint{type="info"}
🖊 ***Nota*****: **Após associar os Roles, o item de menu será exibido no **menu **conforme as configurações que foram realizadas no sistema.
:::

***

Na aba Papel (**Roles)**, é possível tanto registrar um **novo role,** como exportar um arquivo **.csv** contendo as informações dos roles já cadastradas no sistema.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/YkwU5ifPqCeVa0mcDjzsU_image.png" size="64" width="492" height="47" caption position="center" signedSrc="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/YkwU5ifPqCeVa0mcDjzsU_image.png"}

Além disso, é possível **editar **e **excluir **um role: escreva um **nome** desejado ou a **ID do Papel **no campo de busca. Após, prossiga com a ação clicando em "**Editar**"**.**

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/EQttT4z-Zn9qrshfDgZhj_image.png)

***

- Ao clicar em "**Editar**", é possível realizar as alterações que deseja;

<table columnWidths="217,527,248" selectedRows="" selectedTable="false" isTableHeaderOn="true" selectedColumns="">
  <tr>
    <td>
      <p><strong>Campos</strong></p>
    </td>
    <td>
      <p><strong>Descrição</strong></p>
    </td>
  </tr>
  <tr>
    <td>
      <p><strong>ID do Papel</strong>*</p>
    </td>
    <td>
      <p>Adicione uma nova role: <strong>demo</strong></p>
    </td>
  </tr>
  <tr>
    <td>
      <p><strong>Tenant (main_url_dns)</strong></p>
    </td>
    <td>
      <p>Adicione un Tenant: <strong>frontmanager.apps.centralit.com.br</strong></p>
    </td>
  </tr>
  <tr>
    <td>
      <p><strong>Descrição</strong>*</p>
    </td>
    <td>
      <p>Adicione um comentário</p>
    </td>
  </tr>
</table>

As informações com asterisco (\*) são obrigatórias.

***


[title] Versão (das Aplicações)
[path] Administração da Plataforma/

Uma **versão **é uma forma de disponibilização de uma aplicação, ou seja, uma aplicação é disponibilizada na plataforma através de uma ou mais versões. A versão é configurada conforme sua **numeração **e conforme o caminho (URL) que a plataforma usará para apresentar ao usuário.

No menu lateral esquerdo da administração da plataforma é exibida uma lista de aplicações de acesso rápido. Ao selecionar uma aplicação, o sistema executará uma versão específica (aquela vinculada na licença do tenant do cliente).

***

### **Exemplo**

**Versão do Workflow**

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/hEvxsN5OlZnyZSFh-myqi_image.png)

- Clique em "**Editar**"

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/CIoUVAB2UvENMUSP6aEKc_image.png)

Na tela do Workflow se mostrará:

- **a Versão: 1.0.0.0**
- **a URL: **%MAIN\_URL\_DNS%/citsmart****
- **o Nome Base: /workflow**
- **e as Ações **

Na hora de usar o sistema, a palavra-chave da URL: %MAIN\_URL\_DNS%será substituida pelo `Tenant`** **que está sendo utilizada, representada como no exemplo caminho inicial: [https://frontmanager.apps.centralit.com.br/](https://frontmanager.apps.centralit.com.br/)

É possível ter uma aplicação somando à palavra-chave a parte final, formando então a aplicação chamada CITSmart ****[https://frontmanager.apps.centralit.com.br/citsmart](https://frontmanager.apps.centralit.com.br/)

:::hint{type="info"}
🖊 ***Nota*****: **É possível ter várias versões do mesmo produto no ar. São lançadas para fornercer ao cliente as correções que foram feitas no produto.
:::


[title] Caixas de E-mail (por Tenant)
[path] Administração da Plataforma/

Aqui é possível encontrar as **caixas de e-mail **(**por Tenant**)** **já cadastradas no sistema. **Registre **também uma nova caixa de e-mail ou **exclua **alguma já cadastrada.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/FqjWr6xbwTGXC59stvsm7_image.png)

***

Na aba "**Caixas de E-mail**", tanto é possível registrar uma nova caixa de saída de e-mail como exportar um arquivo **.csv** contendo as informações das já cadastradas no sistema.&#x20;

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/YkwU5ifPqCeVa0mcDjzsU_image.png" size="64" width="492" height="47" caption position="center" signedSrc="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/YkwU5ifPqCeVa0mcDjzsU_image.png"}

Além disso, é possível **editar **e **excluir **uma caixa de e-mail, basta fazer a busca da caixa de saída de e-mail desejada** **no campo de busca e prosseguir com a ação clicando em "**Editar**"**.**

***

- Ao clicar em "**Editar**", realize as alterações que deseja;

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/3A4xPdBEP8uhOFjFzdKR-_image.png)

<table columnWidths="425,319,223" selectedRows="" selectedTable="false" isTableHeaderOn="true" selectedColumns="">
  <tr>
    <td>
      <p><strong>Item</strong></p>
    </td>
    <td>
      <p><strong>Descrição</strong></p>
    </td>
  </tr>
  <tr>
    <td>
      <p>Servidor</p>
    </td>
    <td>
    </td>
  </tr>
  <tr>
    <td>
      <p>Porta (*)</p>
    </td>
    <td>
    </td>
  </tr>
  <tr>
    <td>
      <p>Usuário</p>
    </td>
    <td>
    </td>
  </tr>
  <tr>
    <td>
      <p>Remetente</p>
    </td>
    <td>
    </td>
  </tr>
  <tr>
    <td>
      <p>Tenant</p>
    </td>
    <td>
    </td>
  </tr>
  <tr>
    <td>
      <p>SSL/TLS (*)</p>
    </td>
    <td>
      <p>Selecione "<strong>Sim</strong>" ou "<strong>Não</strong>"</p>
    </td>
  </tr>
</table>

As informações com asterisco (\*) são obrigatórias.

***

- Após concluir todas as alterações, clique em "**Registro**".


[title] Executar script
[path] Administração da Plataforma/Untitled/

O objetivo é manter registro de scripts para a execução dos mesmos no sistema.

## Procedimento

1. Acessar a funcionalidade através da navegação no menu principal `Sistema > Banco de Dados > Scripts > Execução de Scripts;`
2. Clicar na guia **Cadastro de Scripts**;
3. Preencher os campos para um novo script;
4. Clicar em "**Gravar**";
5. Para executar o script que está sendo criado, clicar na guia Pesquisa de Scripts;
6. Preencher algum dos campos disponibilizados;
7. Clicar em "**Pesquisar**";
8. Selecionar o script desejado;
9. O mesmo será disponibilizado na guia **Cadastro de Script**;
10. Clicar no botão "**Executar**".


[title] Importar Portfólio de Serviço
[path] Administração da Plataforma/Untitled/

O objetivo desta funcionalidade é realizar a importação de portfólio de serviços. Os dados importados poderão ser visualizados no Portfólio de Serviços.

## Antes de começar

- [x] Para realizar a importação é necessário gerar o modelo de planilha de importação.

## Procedimento

1. Acessar a funcionalidade através da navegação no menu principal `Sistema > Importação e Carga de Dados > Carga do Portfólio de Serviços;`
2. Para cadastrar um modelo de planilha para importação, clicar na guia **Importação**;
3. Clicar em "Escolher arquivo" e selecionar o arquivo o qual deve estar em formato ".xls" ou ".xlsx";
4. Clicar em "Importar".

:::hint{type="info"}
**Nota: **Ao realizar a importação, caso haja alguma inconsistência entre os valores adotados no sistema e os valores informados na planilha, o sistema exibirá um alerta.
:::


[title] Configurar visões
[path] Administração da Plataforma/Untitled/

Esta funcionalidade tem por objetivo permitir a criação de visões (telas) diversas do sistema, com possibilidades de associação com visões vinculadas (subtelas).

Esta funcionalidade disponibiliza ações diversas, tais como, incluir, alterar e excluir visões (telas) diversas do sistema.

## Procedimento

1. Acessar a funcionalidade através da navegação no menu principal `Sistema > Visões e Meta dados > Manutenção de Visões;`
2. Preencher os campos disponibilizados;
3. Para adicionar campos na visão (tela) que está sendo criada clicar no botão "**Adicionar Campo**";
4. Para adicionar uma subtela na visão clicar no botão "**Adicionar Visão Vinculada**";
5. Para adicionar botões na visão que está sendo criada clicar no botão "**Botões de Ação**".
6. Para incluir instruções/códigos JavaScript clicar no botão "**Script**";
7. Para incluir instruções/códigos HTML clicar no botão "HTML Code (adicional)";
8. Clicar no botão "**Gravar**".


[title] Cadastrar importação de dados
[path] Administração da Plataforma/Untitled/

A finalidade desta funcionalidade é realizar a importação de dados de uma outra base de dados para base de dados do CITSmart.

Esta funcionalidade disponibiliza ações diversas, tais como, incluir, alterar e excluir a importação de dados.

## Antes de começar

- [x] Para realizar a importação de dados é necessário ter conhecimento sobre programação e banco de dados, além de ter uma conexão externa cadastrada.

## Procedimento

1. Acessar a funcionalidade através da navegação no menu principal `Sistema > Importação e Carga de Dados > Importação de Dados;`
2. Dependendo da forma de importação escolhida no campo Importar por, serão disponibilizados campos diferentes;
3. Clicar no botão "**Executar Rotina**" para execução da importação de dados;
4. Clicar no botão "**Gravar**".


[title] Aplicações
[path] Administração da Plataforma/

Uma **aplicação **é um item muito importante dentro da Plataforma. Aqui você pode ver as aplicações diversas que estão cadastradas no sistema. Essas aplicações podem ser disponibilizadas para os tenatns através do licenciamento (**veja cadastro de licenças**).

:::hint{type="warning"}
📌 ***IMPORTANTE*****! **

As aplicações são disponibilizadas na plataforma através de versões (veja cadastro de versões).
:::

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/5GErnYrFq-WpIsGsyrly1_image.png "Administrar Aplicações - Hyper")

***

## Aba Aplicações

Na aba "**Aplicações**", é possível tanto registrar uma nova aplicação, como exportar um arquivo **.csv** contendo as informações das aplicações já cadastradas no sistema.&#x20;

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/YkwU5ifPqCeVa0mcDjzsU_image.png" size="64" width="492" height="47" caption position="center" signedSrc="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/YkwU5ifPqCeVa0mcDjzsU_image.png"}

Além disso, também é possível editar e excluir uma aplicação: escreva o nome da aplicação desejada ou a **ID de Aplicação** no campo de busca e prossiga com a ação clicando em "**Editar**"**. **

### **Workflow**

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/v546PRbPG3QKUiW0YZUlg_image.png)

***

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/UdhSMhN9OjJJEM6CSPIMs_image.png)

Ao clicar em "**Editar**", é possível alterar as informações da aplicação:

<table columnWidths="109,634,248" selectedRows="" selectedTable="false" isTableHeaderOn="true" selectedColumns="">
  <tr>
    <td>
      <p><strong>Campo</strong></p>
    </td>
    <td>
      <p><strong>Descrição</strong></p>
    </td>
  </tr>
  <tr>
    <td>
      <p><strong>Nome</strong>*****</p>
    </td>
    <td>
      <p>Nome da aplicação.</p>
    </td>
  </tr>
  <tr>
    <td>
      <p><strong>Descrição</strong>*****</p>
    </td>
    <td>
      <p>O título da aplicação no menu das aplicações muda conforme a alteração.</p>
    </td>
  </tr>
  <tr>
    <td>
      <p><strong>Cliente</strong></p>
    </td>
    <td>
      <p>Essa informação deve ser usada somente se a aplicação foi desenvolvida por um cliente especifico (de propriedade intelectual do cliente). O padrão é deixar este campo vazio.</p>
    </td>
  </tr>
  <tr>
    <td>
      <p><strong>Situação</strong>*****</p>
    </td>
    <td>
      <p><strong>Ativo</strong> ou <strong>Inativo</strong>. Se colocar como inativa, a aplicação não aparece no menu das aplicações.</p>
    </td>
  </tr>
  <tr>
    <td>
      <p><strong>Render</strong>*****</p>
    </td>
    <td>
      <p>Informação de como renderizar. Selecione: <strong>Legado iframe</strong>; <strong>Microfront-End</strong>; <strong>Microfront-End por Iframe</strong>; <strong>SPA</strong></p>
    </td>
  </tr>
  <tr>
    <td>
      <p><strong>Tipo</strong>*****</p>
    </td>
    <td>
      <p>Se é: <strong>Gerenciada pela plataforma</strong> ou <strong>Gerenciada pelo cliente (O padrão é Gerenciada pela plataforma)</strong></p>
    </td>
  </tr>
  <tr>
    <td>
      <p><strong>Observação</strong></p>
    </td>
    <td>
      <p>Adicione uma observação.</p>
    </td>
  </tr>
</table>

As informações com asterisco (\*) são obrigatórias.

***

- Além das informações possíveis de ser alteradas, é possível também adicionar um **ícone** que aparecerá no menu das aplicações de acesso rápido no campo esquerdo da tela. E caso queira modificar o ícone, clique em "**image**", para alterar e salve a alteração.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/GOpn0XhgMwRJ_8t4g9acS_image.png)

- Após concluir todas as alterações, clique em "**Registro**".

***

:::hint{type="warning"}
📌 ***IMPORTANTE*****! **

Não há nenhum caminho ao fazer as alterações desejadas, mesmo mudando o nome da aplicação ou fazendo outras alterações. Isso porque a ***Hyper Platform ***é um recurso muito dinâmico.
:::


[title] Notificação
[path] Administração da Plataforma/Automatização /Cadastrar ação automática/

Esta funcionalidade tem como objetivo cadastrar ações automáticas ou manuais de notificação. A notificação formaliza e comunica informações sobre o evento e é importante que as informações sobre um evento sejam descritas e completas para
facilitar posteriormente a tomada de decisão. Este cadastro será associado às ações automáticas, e será usado nos cadastros de gerentes de eventos do CITSmart Nagios, Zabbix, Inventory e Eventos Correlacionados.

Convém que as notificações de eventos sejam enviadas somente para os responsáveis pelo tratamento das ações ou decisões relacionadas. Isto evita notificações desnecessárias para aqueles que não estão diretamente envolvidos no processo dos eventos.

Esta funcionalidade disponibiliza ações diversas, tais como, incluir, alterar e excluir ações automáticas de notificação.

## Antes de começar

- [x] Para cadastrar uma ação automática de notificação é preciso registrar previamente o usuário e o grupo.

## Procedimento

1. Acessar a funcionalidade através da navegação no menu principal `Sistema > Ações Automáticas > Ações Notificação;`
2. Preencher os campos disponibilizados;
3. Para vincular um usuário, clicar na guia "**Adicionar Usuários**" e em seguida em "**Adicionar**";
4. Para vincular um grupo, clicar na guia "**Adicionar Grupos**" e em seguida em "**Adicionar**";
5. Para vincular um e-mail, clicar na guia "**Adicionar e-mails**", digitar o e-mail no campo e em seguida em "**Adicionar**";
6. Clicar em "Gravar".

### Notificação Automática de Novo Anexo no Tíquete

A plataforma conta com um Componente de Notificação de Novo Anexo, que informa automaticamente os usuários interessados sempre que um novo arquivo é adicionado a um tíquete.

Quem é notificado:

- Responsável atual pelo tíquete
- Criador do tíquete
- Solicitante do tíquete

Esses usuários recebem uma notificação imediata por meio dos recursos de comunicação definidos no item NOTIFICAÇÃO/ALERTA da plataforma (como alertas visuais, e-mails ou mensagens internas no sistema, conforme as configurações da organização).

### Notificação de Ticket Vinculado

A plataforma conta com a funcionalidade de Automação de Notificação de Tíquetes Vinculados, que garante que todos os interessados nos tíquetes relacionados sejam informados sobre a vinculação e o andamento do tíquete principal (original).

Essa funcionalidade assegura a sincronização de informações entre tíquetes relacionados, promovendo visibilidade e alinhamento entre as equipes envolvidas.


[title] Cadastrar Categoria de Questionário
[path] Administração da Plataforma/

Esta funcionalidade disponibiliza ações diversas, tais como, incluir, alterar e excluir categorias de questionários que serão utilizadas para filtragem e organização dos mesmos registrados na base.

## Procedimento

1. Acessar a funcionalidade através da navegação no menu principal `Sistema > Visões e Metadados > Questionário > Categoria Questionário;`
2. Clicar no botão "**Novo**";
3. Preencher o campo disponibilizado;
4. Clicar em "**Gravar**".


[title] Menus (Associar Versão de Apps)
[path] Administração da Plataforma/

Após <a href="https://docs.citsmart.com/hyper/menus-manutencao-de-itens" target="_blank">criar um **Item**</a>** **é necessário associá-lo a uma **versão **para ser exibido no menu.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/4kLblq14z4azYqUbaO7wk_image.png)

Para isso, procure a aplicação que deseja no campo de busca e prossiga com a ação clicando em "**Editar**"**.**

## **Workflow**

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/hVgiaEgPXg1M1fLNlQeic_image.png "Botão Editar")

Em seguida, selecione a **versão 1.0.0.0**

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/qsZPWra9oW2753Y1Opm2l_image.png "Versão 1.0.0.0")

Ao selecioná-la uma lista de itens de menu que surgirão em versões futuras será exibida. Além disso, é necessário fazer o gerenciamento destes:

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/eUhD3xn8Bn_1lxASC3V7c_image.png "Tela de Itens de Menu")

:::hint{type="info"}
🖊 ***Nota*****: **Ao fazer a gestão de itens de menu, é preciso atribuir o item que deseja pois irá aparecer para você como "**Não atribuído**".&#x20;

> **Exemplo: **
>
> `Atribuir > Práticas Unificadas`
>
> ** (Não atribuido)**
>
>
>
>
> `Itens de menu > Gerência de Ticket (1.0.0.0) > Práticas Unificadas`
>
> ** (1.0.0.0)**
:::

***

Depois, clique em "**Associar**" para atribuir o item. As **Práticas Unificadas** agora estarão consequentemente vinculados à **versão (1.0.0.0)**

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/m9xnlG_VKpgfOrYIXEDEw_image.png)

:::hint{type="warning"}
📌 ***IMPORTANTE*****! **

Agora é necessário realizar uma outra vinculação, assim como** **<a href="https://docs.citsmart.com/hyper/menus-associar-roles" target="_blank">**vincular Roles**</a>. Associar somente a versão de Apps não basta.
:::


[title] Personalização do Sistema
[path] Administração da Plataforma/Untitled/

É possível personalizar diversas informações no seu ambiante, tais quais:

- Logotipo do Sistema
- Portal de Conhecimento (CSS e logotipo)

Na Personalização do sistema é possível realizar correções nos campos do sistema, podendo corregir acentuação, alterar palavras e configurar o que aparecerá conforme o idioma desejado.


[title] Configurar campos de obrigatoriedade
[path] Administração da Plataforma/Untitled/

Através da configuração dos campos de obrigatoriedade é facultado ao administrador a escolha de quais campos o usuário será compelido a preencher ao contactar os atendentes. A finalidadade desta habilidade é impor ao solicitante a satisfazer as informações imprescindíveis a resolução de sua solicitação.

## Procedimento

1. Acessar a funcionalidade através da navegação no menu principal `Sistema > Configurações > Páginas - Configuração de campos;`
2. Serão apresentadas as páginas que comportam a escolha de campos obrigatórios. São duas: Gerenciamento de Problema e Gerenciamento de Incidentes/Requisições.

### Configurar os campos da funcionalidade “Problema”

*Utilizando a opção de utlizar a obrigatoriedade do campo é possível exigir que determinadas informações sejam registradas ao criar o problema.*

1. Após acessar a página inicial da funcionalidade, escolher a opção “**Problema**” e clicar no botão “**Editar**”;
2. Marcar os campos que deseja tornar obrigatório. São eles:
3. Clicar no botão “**Gravar**”.

### Configurar os campos da funcionalidade “Gerenciamento de Ticket"

Utilizando a opção de utlizar a obrigatoriedade do campo é possível exigir que determinadas informações sejam registradas ao criar o incidente/requisição.

- Após acessar a página inicial da funcionalidade, escolher a opção “Gerenciamento de Incidentes” e clicar no botão “**Editar**”;
- Marcar os campos que deseja tornar obrigatório. São eles:
  - Telefone
  - E-mail
  - Unidade
  - Localidade Física
  - Origem do contato
  - Categoria solução
  - causa
  - Justificativa SLA vencido
- Clicar no botão “**Gravar**”.


[title] Customizar Campos 
[path] Administração da Plataforma/

## Personalizar Labels

Esta funcionalidade tem por objetivo mudar os nomes de labels dentro da Plataforma CITSmart permitindo assim uma maior customização do mesmo. É preciso que o usuário tenha conhecimento sobre programação.

## Procedimento

1. Acessar a funcionalidade através do menu `Sistema > Configurações > Personalização do Sistema;`
2. Preencher os campos disponibilizados;
3. Clicar no botão "**Gravar**".

## O que fazer a seguir

Depois de gravar a mudança, acessar a funcionalidade que foi realizada a mudança de label para verificação.


[title] Campos Chave de E-mails de Mudança
[path] Administração da Plataforma/Untitled/

Este documento tem o objetivo de fornecer a relação dos campos chave, disponíveis para o cadastro de modelo de e-mail relacionado a mudanças.

## Relação de Campos Chaves

São relacionados abaixo os campos chave disponíveis para inserção no cadastro de modelo de e-mail relacionados a mudanças:

| **Campo-Chave**            | **Descrição**                                                                                |
| -------------------------- | -------------------------------------------------------------------------------------------- |
| $\{ATRASOSTR}              | Tempo de Atraso.Informa o tempo de atraso do atendimento da mudança.                         |
| $\{DATAACEITACAO}          | Data de Aceitação.Informa a data de aceitação da mudança.                                    |
| $\{DATACONCLUSAOSTR}       | Data de Conclusão.Informa a data da conclusão do atendimento da mudança.                     |
| $\{DATAHORACAPTURA}        | Data e Hora de Captura da Requisição.Informa a data e hora da captura da mudança.            |
| $\{DATAHORAINICIOSTR}      | Data e Hora do Registro da Requisição.Informa a data e hora em que a mudança foi registrada. |
| $\{DATAHORASOLICITACAOSTR} | Data e Hora do Registro da Requisição.Informa a data e hora em que a mudança foi registrada. |
| $\{DATAHORATERMINOSTR}     | Prazo Limite.Informa a prazo limite para atendimento da mudança.                             |
| $\{DATAINICIO}             | Data de Início da Reunião.Informa a data de início da reunião agendada.                      |
| $\{DATAVOTACAO}            | Data da Votação.Informa a data da votação para aprovação da mudança.                         |
| $\{DESCRICAO}              | Descrição da Requisição de Mudança.Informa a descrição da mudança.                           |
| $\{DURACAOESTIMADA}        | Duração Estimada.Informa a duração estimada da reunião agendada.                             |
| $\{EMAILSOLICITANTE}       | E-mail do Solicitante.Informa o e-mail do solicitante da mudança.                            |
| $\{FECHAMENTO}             | Fechamento.Informa a descrição do fechamento da mudança.                                     |
| $\{HORAINICIO}             | Hora de Início da Reunião.Informa a hora de início da reunião agendada.                      |
| $\{IDREQUISICAOMUDANCA}    | Número da Requisição de Mudança.Informa o número de identificação da mudança.                |
| $\{NIVELIMPACTO}           | Impacto.Informa o impacto da mudança.                                                        |
| $\{LOCALREUNIAO}           | Local da Reunião.Informa o local da reunião agendada.                                        |
| $\{NIVELURGENCIA}          | Urgência.Informa a urgência da mudança.                                                      |
| $\{NOMECATEGORIAMUDANCA}   | Categoria da Mudança.Informa da categoria da mudança.                                        |
| $\{NOMECONTATO}            | Nome do Contato.Informar o nome do solicitante para contato.                                 |
| $\{NOMEGRUPOATUAL}         | Grupo Atual.Informa o grupo atual responsável pelo atendimento da mudança.                   |
| $\{NOMEGRUPONIVEL1}        | Grupo de Nível 1.Informa o grupo de nível 1 configurado para atendimento da mudança.         |
| $\{NOMESOLICITANTE}        | Nome do Solicitante.Informa o nome do solicitante da mudança.                                |
| $\{NOMETAREFA}             | Tarefa.Informa a tarefa atual da mudança.                                                    |
| $\{PRIORIDADE}             | Prioridade.Informa a prioridade da mudança.                                                  |
| $\{DESCRSTATUS}            | Status da Mudança.Informa o status da mudança.                                               |
| $\{TIPO}                   | Tipo de Mudança.Informa o tipo de mudança que foi registrada.                                |
| $\{TITULO}                 | Título da Mudança.Informa o título da mudança que foi registrada.                            |

Tabela 1 - Lista de campos chave


[title] Event Processing - Container
[path] Administração da Plataforma/

Este cadastro representa o cadastro de *containers* (pequenas máquinas virtuais) para processamento de eventos. Os eventos são estímulos captados externamente.

> ***Exemplo***
>
> **: **
>
> E-mail, Mensageria, WhatsApp, Telegram, Temporizadores, Weebhook, entre outros. 

Portanto, o ***container***** **é responsável por **capturar **(receber o estímulo externo) e **processar **(encaminhar para processamento).

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/DGCh5DJOFJFIpAFJLDJI2_image.png "Cadastro de containers de eventos")

:::hint{type="warning"}
📌 ***IMPORTANTE*****! **

O *container *pode processar eventos de vários tenants (***cluster spaces***), portanto é necessário configurar as informações para seus acessos (**sistema de autenticação OAuth2**).
:::


[title] Parametrização - Configuração
[path] Administração da Plataforma/Untitled/

O Gerenciamento de configuração é o registro e atualização detalhada de informações que descrevem o hardware e software de uma empresa. É um processo para estabelecer e manter a consistência do desempenho de um produto, seus atributos funcionais, dentre outras informações operacionais ao longo de sua vida.

A parametrização da configuração deve ser realizada para permitir a execução/uso deste processo, podendo ser possível, definir o nome do grupo para os Itens de configuração que não possuem grupo, definir o destinatório do envio de emails notificando a expiração próxima do IC do tipo Software, definir o nome do domínio da rede, dentre outras.

## Procedimento

1. Acessar a funcionalidade através da navegação no menu principal `Parametrização > Gerência de Configuração;`
2. Definir os valores dos parâmetros (atributos);
3. Clicar no botão "**Gravar**" para efetuar a operação;
4. A lista abaixo apresenta os parâmetros da funcionalidade "**Configuração**" e a finalidade de cada um deles:

| #   | Nome                                                                                                 | Valores possíveis                                | Finalidade                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Orientações complementares                                                                                                                                     |
| --- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 3   | Nó Pesquisa - (Ex: HARDWARE)                                                                         | Ex: HARDWARE                                     | Realizar a busca no documento XML do Nó definido. Após gerar o inventário, será gerado o arquivo XML, onde neste será feita a leitura do(s) NÓ(S) conforme definido(s) neste parâmetro.                                                                                                                                                                                                                                                                                                                                       | Não se aplica                                                                                                                                                  |
| 4   | Atributo Pesquisa - (Ex: IPADDR,NAME,UDERID)                                                         | Ex: IPADDR,NAME,UDERID                           | Realizar busca no documento XML dos atributos definidos. Após identificar o NÓ, será verificado dentro do mesmo o(s) atributo(s) conforme definido(s) neste parâmetro.                                                                                                                                                                                                                                                                                                                                                        | Não se aplica                                                                                                                                                  |
| 5   | CAMINHO\_INSTALADORES                                                                                |                                                  | Informar o caminho do diretório definido para armazenar os arquivos executáveis dos softwares a serem instalados.                                                                                                                                                                                                                                                                                                                                                                                                             | Não se aplica                                                                                                                                                  |
| 60  | Grupo de novos itens de configuração.                                                                |                                                  | Definir o nome do Grupo para Itens de Configuração que não possuem Grupo. Esse ID é definido na tela de “Grupo de Item Configuração”.                                                                                                                                                                                                                                                                                                                                                                                         | Não se aplica                                                                                                                                                  |
| 73  | Número de dias para Notificar Expiração de Licença. (Default: 90 dias)                               | Default: 90 dias                                 | Definir os dias de antecedência da data de expiração da licença do IC para notificar o grupo ou proprietário do IC sobre a expiração. Na criação do item de configuração do tipo “SOFTWARE” deve ser informada a data de expiração, ou seja, a data em que a licença do software irá expirar. Será utilizado o modelo de e-mail definido no parâmetro 75 para notificar ao grupo ou proprietário do IC definido no parâmetro 74, com antecedência de N dias (definido neste parâmetro) da data de expiração da licença do IC. | Caso não informe a quantidade de dias, será estabelecido o valor padrão do sistema: 90 (noventa) dias.                                                         |
| 74  | Enviar e-mail para Grupo ou Proprietário do IC? (1: Grupo 2\:proprietário).                          | 1: Grupo 2: Proprietário                         | Definir para quem será feito o envio de e-mails notificando que o IC do tipo Software está com a licença próxima da expiração: 1 = Grupo ou 2 = Proprietário.                                                                                                                                                                                                                                                                                                                                                                 | Caso não informe o valor do parâmetro, não será realizado o envio de e-mail.                                                                                   |
| 75  | ID do modelo de e-mail para envio de notificação de licença próximo da expiração                     |                                                  | Informar o número de identificação (ID) do modelo de e-mail de notificação de licença próximo da expiração. Será utilizado para o envio da notificação do IC do tipo Software que está com a licença próxima da expiração o modelo de e-mail definido neste parâmetro. Esse ID do modelo de e-mail é definido na tela de “Modelo de E-mail”.                                                                                                                                                                                  | Caso não informe o número de identificação (ID) do modelo de e-mail, há possiblidade de não enviar o e-mail correto.                                           |
| 76  | Nome do Domínio da Rede (Ex: EMPRESA, CORPORACAO)                                                    | Ex: EMPRESA, CORPORACAO                          | Definir o nome do domínio da rede.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Não se aplica                                                                                                                                                  |
| 85  | Verificar vínculo de Mudança relacionada ao IC?                                                      | S ou N                                           | Definir se o vínculo de Item de Configuração (IC) à Mudança será obrigatório. Caso seja definido o valor “S”, ao cadastro um Item de Configuração na tela de “Item de Configuração” deve relacionar o IC à Mudança.                                                                                                                                                                                                                                                                                                           | Caso não informe o valor do parâmetro, será utilizado o valor padrão do sistema: “S” (Sim).                                                                    |
| 87  | ID do modelo de e-mail para Notificação de Criação de IC                                             | Ex: 16                                           | Informar o número de identificação (ID) do modelo de e-mail de notificação de criação de Item de Configuração (IC). Ao criar um IC na tela de “Gerenciamento de Itens de Configuração”, será utilizado para o envio da notificação de criação do IC o modelo de e-mail definido neste parâmetro. Essa notificação será enviada para o proprietário e/ou grupo associado ao IC. Esse ID do modelo de e-mail é definido na tela de “Modelo de E-mail”.                                                                          | Caso não informe o número de identificação (ID) do modelo de e-mail, há possiblidade de não enviar o e-mail correto.                                           |
| 88  | ID do modelo de e-mail para Notificação de Alteração de IC                                           | Ex: 14                                           | Informar o número de identificação (ID) do modelo de e-mail de notificação de alteração de Item de Configuração (IC). Ao alterar um IC na tela de “Gerenciamento de Itens de Configuração”, será utilizado para o envio da notificação de alteração do IC o modelo de e-mail definido neste parâmetro. Essa notificação será enviada para o proprietário e/ou grupo associado ao IC. Esse ID do modelo de e-mail é definido na tela de “Modelo de E-mail”.                                                                    | Caso não informe o número de identificação (ID) do modelo de e-mail, há possiblidade de não enviar o e-mail correto.                                           |
| 89  | Modelo de alteração de IC de grupo (Ex: 15)                                                          | Ex: 15                                           | Informar o número de identificação (ID) do modelo de e-mail de notificação de alteração do Grupo de Item de Configuração (IC). Ao alterar um Grupo de IC na tela de “Gerenciamento de Itens de Configuração”, será utilizado para o envio da notificação de alteração do Grupo de IC o modelo de e-mail definido neste parâmetro. Essa notificação será enviada para o proprietário e/ou grupo associado ao IC. Esse ID do modelo de e-mail é definido na tela de “Modelo de E-mail”.                                         | Caso não informe o número de identificação (ID) do modelo de e-mail, há possiblidade de não enviar o e-mail correto.                                           |
| 90  | Envio de e-mails de Notificação de ICs (1-Grupo, 2-Proprietario, 3-Todos) (Default: 1)               | 1- Grupo, 2- Proprietário, 3- Todos (Default: 1) | Definir para quem será feito o envio de e-mails de notificações dos Itens de Configuração (IC’s): 1 = Grupo, 2 = Proprietário ou 3 = Todos                                                                                                                                                                                                                                                                                                                                                                                    | Caso não informe o valor do parâmetro, será utilizado o valor padrão do sistema: “1” = Grupo                                                                   |
| 92  | Nome do Grupo de ICs que estão na Fase de Desenvolvimento. (Ex: ICs em Desenvolvimento)              | Ex: Desenvolvimento                              | Definir o nome do grupo de ICs que estão na fase de Desenvolvimento. Na tela de “Gerenciamento de Itens de Configuração”, será exibido o nome do grupo de ICs da fase de desenvolvimento conforme definido neste parâmetro.                                                                                                                                                                                                                                                                                                   | Caso não informe o valor do parâmetro, não será exibido o nome do grupo de ICs da fase de desenvolvimento na tela de “Gerenciamento de Itens de Configuração”. |
| 93  | Nome do Grupo de ICs que estão na Fase de Produção. (Ex: ICs em Produção)                            | Ex: Produção                                     | Definir o nome do grupo de ICs que estão na fase de Produção. Na tela de “Gerenciamento de Itens de Configuração”, será exibido o nome do grupo de ICs da fase de produção conforme definido neste parâmetro.                                                                                                                                                                                                                                                                                                                 | Caso não informe o valor do parâmetro, não será exibido o nome do grupo de ICs da fase de produção na tela de “Gerenciamento de Itens de Configuração”.        |
| 94  | Nome do Grupo de ICs que estão na Fase de Homologação. (Ex: ICs em Homologação)                      | Ex: Homologação                                  | Definir o nome do grupo de ICs que estão na fase de Homologação. Na tela de “Gerenciamento de Itens de Configuração”, será exibido o nome do grupo de ICs da fase de homologação conforme definido neste parâmetro.                                                                                                                                                                                                                                                                                                           | Caso não informe o valor do parâmetro, não será exibido o nome do grupo de ICs da fase de homologação na tela de “Gerenciamento de Itens de Configuração”.     |
| 95  | Nome do Grupo de ICs Inventariados. (Default: Inventário)                                            | Ex: Inventário                                   | Definir o nome do grupo de ICs gerados do inventário automático. Na tela de “Gerenciamento de Itens de Configuração”, no grupo de ICs da fase de desenvolvimento, será exibido o nome do grupo de Itens de Configuração gerados do inventário automático conforme definido neste parâmetro.                                                                                                                                                                                                                                   | Não há impacto negativo. Caso não informe o valor do parâmetro, será utilizado o valor padrão do sistema: Inventário.                                          |
| 96  | ID do Grupo de ICs em Desenvolvimento. (Ex: 1)                                                       | Ex: 1                                            | Definir o número de identificação (ID) do grupo de ICs da fase de Desenvolvimento. Na tela de “Gerenciamento de Itens de Configuração” será criado um grupo que representará a fase do clico de vida do IC em desenvolvimento, conforme o ID definido neste parâmetro e a descrição definida no parâmetro 92.                                                                                                                                                                                                                 | Não há impacto negativo. Caso não informe o valor do parâmetro, será utilizado o valor padrão do sistema: 997.                                                 |
| 97  | ID do Grupo de ICs em Produção. (Ex: 2)                                                              | Ex: 2                                            | Definir o número de identificação (ID) do grupo de ICs da fase de Produção. Na tela de “Gerenciamento de Itens de Configuração” será criado um grupo que representará a fase do clico de vida do IC em produção, conforme o ID definido neste parâmetro e a descrição definida no parâmetro 93.                                                                                                                                                                                                                               | Não há impacto negativo. Caso não informe o valor do parâmetro, será utilizado o valor padrão do sistema: 998.                                                 |
| 98  | ID do Grupo de ICs em Homologação. (Ex: 3)                                                           | Ex: 3                                            | Definir o número de identificação (ID) do grupo de ICs da fase de Homologação. Na tela de “Gerenciamento de Itens de Configuração” será criado um grupo que representará a fase do clico de vida do IC em homologação, conforme o ID definido neste parâmetro e a descrição definida no parâmetro 94.                                                                                                                                                                                                                         | Não há impacto negativo. Caso não informe o valor do parâmetro, será utilizado o valor padrão do sistema: 999.                                                 |
| 99  | ID do Grupo de ICs Inventariados. (Ex: 4)                                                            | Ex: 4                                            | Definir o número de identificação (ID) do grupo de Inventário de Itens de Configuração. Na tela de “Gerenciamento de Itens de Configuração”, no grupo de ICs da fase de desenvolvimento, será criado um grupo para os IC’s gerados do inventário automático, conforme o ID definido neste parâmetro e a descrição definida no parâmetro 95.                                                                                                                                                                                   | Não há impacto negativo. Caso não informe o valor do parâmetro, será utilizado o valor padrão do sistema: 1000.                                                |
| 140 | ID do Grupo padrão de ICs em Desenvolvimento                                                         |                                                  | Definir o número de identificação (ID) do grupo padrão de ICs em desenvolvimento. Na tela de “Gerenciamento de Itens de Configuração”, no grupo de ICs da fase de desenvolvimento, será criado um grupo padrão para os ICs em desenvolvimento, conforme o ID definido neste parâmetro e a descrição definida no parâmetro 143.                                                                                                                                                                                                | Não há impacto negativo. Caso não informe o valor do parâmetro, será utilizado o valor padrão do sistema: 1001.                                                |
| 141 | ID do Grupo padrão de ICs em Homologação                                                             |                                                  | Definir o número de identificação (ID) do grupo padrão de ICs em homologação. Na tela de “Gerenciamento de Itens de Configuração”, no grupo de ICs da fase de homologação, será criado um grupo padrão para os ICs em homologação, conforme o ID definido neste parâmetro e a descrição definida no parâmetro 144.                                                                                                                                                                                                            | Não há impacto negativo. Caso não informe o valor do parâmetro, será utilizado o valor padrão do sistema: 1002.                                                |
| 142 | ID do Grupo padrão de ICs em Produção                                                                |                                                  | Definir o número de identificação (ID) do grupo padrão de ICs em produção. Na tela de “Gerenciamento de Itens de Configuração”, no grupo de ICs da fase de produção, será criado um grupo padrão para os ICs em produção, conforme o ID definido neste parâmetro e a descrição definida no parâmetro 145.                                                                                                                                                                                                                     | Não há impacto negativo. Caso não informe o valor do parâmetro, será utilizado o valor padrão do sistema: 1003.                                                |
| 143 | Nome do Grupo padrão dos ICs em Desenvolvimento. (Ex: Desenvolvimento - Default)                     | Ex: Desenvolvimento - Padrão                     | Definir o nome do grupo padrão de ICs em desenvolvimento. Na tela de “Gerenciamento de Itens de Configuração”, no grupo de ICs da fase de desenvolvimento, será exibido o nome do grupo padrão de ICs em desenvolvimento, conforme definido neste parâmetro.                                                                                                                                                                                                                                                                  | Caso não informe o valor do parâmetro, não será exibido o nome do grupo padrão de ICs em desenvolvimento.                                                      |
| 144 | Nome do Grupo padrão dos ICs em Homologação. (Ex: Homologação - Default)                             | Ex: Homologação - Padrão                         | Definir o nome do grupo padrão de ICs em homologação. Na tela de “Gerenciamento de Itens de Configuração”, no grupo de ICs da fase de homologação, será exibido o nome do grupo padrão de ICs em homologação, conforme definido no neste parâmetro.                                                                                                                                                                                                                                                                           | Caso não informe o valor do parâmetro, não será exibido o nome do grupo padrão de ICs em homologação.                                                          |
| 145 | Nome do Grupo padrão dos ICs em Produção. (Ex: Produção - Default)                                   | Ex: Produção - Padrão                            | Definir o nome do grupo padrão de ICs em produção. Na tela de “Gerenciamento de Itens de Configuração”, no grupo de ICs da fase de produção, será exibido o nome do grupo padrão de ICs em produção, conforme definido neste parâmetro.                                                                                                                                                                                                                                                                                       | Caso não informe o valor do parâmetro, não será exibido o nome do grupo padrão de ICs em produção.                                                             |
| 248 | ID do modelo de e-mail que será utilizado durante o monitoramento de ativos                          |                                                  | Informar o número de identificação (ID) do modelo de e-mail que será utilizado durante o monitoramento de ativos. Esse ID do Modelo de E-mail é definido na tela de “Modelo de E-mail”.                                                                                                                                                                                                                                                                                                                                       | Se o número de identificação (ID) não for informado corretamente o sistema não enviará e-mails de notificação.                                                 |
| 249 | Monitoramento de Ativos - Número de Threads? (Default '10')                                          | Default: 10                                      | Definir o número de threads que vão realizar o monitoramento de ativos.                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Não se aplica                                                                                                                                                  |
| 250 | Exibir nome na árvore de itens de configuração (Ex: S ou N - Default 'S')                            | S ou N (Default: S)                              | Definir se o campo “Nome” será utilizado na exibição dos itens de configuração na tela de Gerência de Itens de Configuração. Caso não informado ou tenha o valor ‘S’, será exibido na listagem de itens de configuração na tela de Gerência de Itens de configuração o valor do campo “Nome” do Item de Configuração. Caso o valor informado seja ‘N’, será exibido na listagem o valor do campo “Identificação” do Item de Configuração.                                                                                     | Não se aplica                                                                                                                                                  |
| 440 | Quantidade mínima de registro que determina se a exportação de dados será executada em segundo plano |                                                  | Utilizar sempre que o usuário desejar informar a quantidade mínima de registros que o sistema deverá executar a exportação em segundo plano.                                                                                                                                                                                                                                                                                                                                                                                  | Não se aplica                                                                                                                                                  |
| 502 | Restringir CMDB por contrato                                                                         | S ou N (Default: N)                              | Define o formato de visualização dos itens de configuração pelos usuários logados. Caso esteja como sim, o usuário só poderá acessar os dados dos intens de configuração que estiverem vinculados a um contrato que o mesmo tem permissão.                                                                                                                                                                                                                                                                                    | Não se aplica                                                                                                                                                  |

.Tabela 1 - Lista de parâmetros


[title] Event Processing - Event
[path] Administração da Plataforma/

Esse cadastro faz a configuração de eventos que serão capturados e processados (em algum container configurado). Os eventos são estímulos captados externamente e internamente.


Os eventos podem ser agendados ou em tempo de execução, ou seja, pode capturar no momento que ocorre algo dentro de um sistema ou pode-se criar agendamentos de execução de eventos como por exemplo, ler e-mails trocados dentro do servidor de email, identificando o ticket que está sendo falado e gerar adicionar no histórico do chamado em tempo real, ou avaliar todos os tickets abertos de minuto em minuto e fechar todos os tickets que estão em uma fase do fluxo a um determinado tempo.

> ***Por exemplo***
>
> **:**
>
>  E-mail, Mensageria, WhatsApp, Telegram, Temporizadores, Weebhook, entre outros. 

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/AhxU6FO7PAgHwGCYGPWgi_image.png "Cadastro de eventos")

:::hint{type="warning"}
📌 ***IMPORTANTE*****! **

Após informar o container o sistema permitirá informar o tenant (cluster space) vinculado a este evento.
:::



:::hint{type="warning"}
📌 ***IMPORTANTE*****!**

- ***Integration Type*****:** É o tipo de evento a ser capturado (**E-mail**, **Webhook**, **Kafka**, **etc**.). Quando é selecionado um determinado tipo, o sistema apresenta uma tela especifica com dados para aquele evento especifico.
  - O webhook é uma tecnologia que permite vários sistemas/tecnologias enviarem eventos para o nosso sistema. Exemplo: O WhatsApp e Microsoft Teams se integram através desta tecnologia.
- ***Action Type*****:** É a ação a ser tomada com a chegada do evento. Pode ser encaminhado ao ESI (*Enterprise Service Integration do Low Code*), FaaS (*Function as a Service do Low Code*), Kafka (Gravar no sistema de mensageria do Kafka), Websocket (Enviar mensagem por Websocket).      **Obs.:** O sistema vai encaminhar todos os dados recebidos ao destino (ação) selecionado.
:::

***

Outro campo importante é o **Status**, pois indica se o evento pode ser captado (**em caso de Ativo**) ou não (**em caso de Inativo**).

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/Ey-fdXcY32Cssu0EHb0Up_image.png "Detalhamento do funcionamento do captador de eventos")

No **Events **também é possível realizar diversas notificações por vários meios para atender a regras específicas. Como por exemplo, avaliar se um SLA pré-estabelecido está chegando ao seu limite em qualquer processo mapeado da solução ou tarefa de fluxo e enviar um alerta conforme definido.

[title] Requisitos para entrega do ambiente Citsmart
[path] Infraestrutura/

:::hint{type="info"}
**Objetivo**

Este documento tem como objetivo descrever a arquitetura de referência para a implantação da plataforma Citsmart On-Premise, contemplando organização em camadas, estrutura física e lógica, mecanismos de automação, segurança e infraestrutura necessária para operação em ambiente do cliente.
:::

**Visão Geral das Camadas**

*Camada Web*

- Kong – API Gateway: segurança, roteamento e rate limiting
- NGINX – Ingress controller do cluster
- Keycloak – Autenticação centralizada: OAuth2, OIDC, SAML
- Rancher/OKD – Orquestrador do cluster&#x20;
- Edge Runtime – executor de código JavaScript/TypeScript

*Camada de Aplicação*

- Aplicações: Aplicações do Citsmart implantadas como microserviços.
- Kafka + Kafka Connect: fila de eventos e conectores externos.
- Redis: caching e controle de sessão.
- Elasticsearch: logs, buscas e indexação distribuída.

*Camada de Dados*

- PostgreSQL 13+: banco de dados principal. (cluster principal e réplicas)
- MinIO: armazenamento de objetos compatível com S3.
- NFS: volumes persistentes para PVCs no Kubernetes.
- PgBouncer: gerenciamento do pool de conexões

*Camada de Integração*

- Apache NiFi: fluxo de dados, transformação e integração visual.
- Kafka Connect: conectividade com sistemas externos.
- Webhooks/REST APIs: consumo e entrega de eventos.

*Camada de IA*

- Tika: extração de conteúdo: PDFs, Docx, Imagens, planilha e apresentações
- Langchain: Framework modular para construir aplicações com LLMs
- Psycopg: Armazenamento de embeddings, cache de conversa e metadados estruturados
- gTTS: TTS, prototipagem funcional
- LangSmith: Debugging de chains, avaliação de qualidade e monitoramento
- PGVector: Extensão para vetores

# ✅ 1. Entrega de servidores para o Cluster

:::hint{type="warning"}
Necessário acesso Root aos servidores
:::

**Topologia do Ambiente**

*Sistema Operacional:*

- AWS Linux RedHat&#x20;
- On-premises - Rock Linux, Ubuntu, Linux Red Hat
- OKE – OCI Oracle Linux (baseado no RedHat)



*Cluster Kubernetes*

| Hostname | CPU | RAM (GB) | HD     | Tipo               |
| -------- | --- | -------- | ------ | ------------------ |
| master1  | 8   | 8        | 100 GB | controlplane, etcd |
| master2  | 8   | 8        | 100 GB | controlplane, etcd |
| master3  | 8   | 8        | 100 GB | controlplane, etcd |
| worker1  | 16  | 32       | 200 GB | worker             |
| worker2  | 16  | 32       | 200 GB | worker             |
| worker3  | 16  | 32       | 200 GB | worker             |
| worker4  | 16  | 32       | 200 GB | worker             |
| worker5  | 16  | 32       | 200 GB | worker             |

*Servidores Adjacentes*

| Hostname    | CPU | RAM | HD                  | Função                             |
| ----------- | --- | --- | ------------------- | ---------------------------------- |
| database1   | 32  | 64  | 100 GB LVM          | PostgreSQL primário                |
| database2\* | 32  | 64  | 100 GB LVM          | PostgreSQL secundário (HA)         |
| haproxy1    | 2   | 4   | 40 GB               | Load balancer (exposição 443)      |
| haproxy2\*  | 1   | 4   | 40 GB               | Load balancer secundário (HA)      |
| nfs         | 2   | 4   | 500 GiB – 1 TiB LVM | Volumes persistentes               |
| bastion     | 2   | 4   | 40 GB               | Runner + Ansible + provisionamento |

*LLM free*

| Hostname | GPU                       | CPU | RAM (GB) | HD |
| -------- | ------------------------- | --- | -------- | -- |
| LLM node | NVidia A100.1 80GB de Ram | 14  | 236      | 50 |

## Justificativa

Cluster Kubernetes

Ao implantar o Kubernetes, você obtém um cluster. Para mais informações detalhadas, pode ser consultado o documento oficial do Kubernetes no link** https\://kubernetes.io/ptbr/docs/concepts/overview/components/**

Um cluster Kubernetes consiste em um conjunto de servidores de processamento, chamados nodes, que executam aplicações containerizadas. Todo cluster possui ao menos um servidor de processamento (worker node), porém se este falhar, todo o ambiente fica sem monitoramento das funcionalidades dos serviços e sem gerênciamento.

A descrição simples de cada tipo de nó pode ser da seguinte forma:

- **Servidores Master**, são responsáveis por manter o estado do cluster Kubernetes, agendam e criam Pods nos nodes Workers.
  Kubernetes usa o algoritmo de consenso RAFT para quorum. Para manter o quorum, você precisará de nodes mestres íntegros floor(n/2) 1.
  Praticamente isso significa:
  - 1 nó mestre: você precisará de 1 nó mestre íntegro para o quorum, a perda do nó mestre deixará o cluster sem gerenciamento.
  - 2 nodes mestres: você precisará de 2 nodes mestres íntegros para o quorum; a perda de qualquer um dos nodes mestres deixará o cluster sem gerenciamento.
  - 3 nodes mestres: você precisará de 2 nodes mestres íntegros para o quórum, a perda de um dos nodes mestres pode ser compensada.
  - 4 nodes mestres: você precisará de 3 nodes mestres íntegros para o quorum, a perda de um nos nodes mestres pode ser compensada. Uma configuração com 4 nodes mestres não tem vantagem sobre uma configuração de 3 nodes mestres.
  - 5 nodes mestres: você precisará de 3 nodes mestres íntegros para o quorum, a perda de até dois nodes mestres pode ser compensada.
  - 6 nodes mestres: você precisará de 4 nodes mestres íntegros para o quorum, a perda de até dois nodes mestres pode ser compensada. Nenhuma vantagem em comparação com 5 nodes mestres.
  - 7 nodes mestres: você precisará de 4 nodes mestres íntegros para o quorum, a perda de até três nodes mestres pode ser compensada.

Esta é a razão pela qual é necessário utilizar um número ímpar de nodes master para o gerênciamento.&#x20;

- **Servidores workers** são responsáveis por receberem as cargas de trabalho e executar os pods(contêineres). Um node apenas é possível executar cargas de trabalho, mas a perda deste, deixará o cluster sem lugar para os Pods. Foi selecionado a quantidade de 5 servidores worker para dividir a carga de trabalho, deixando os servidores com menos estresse nos recursos como CPU e RAM, a perda de um dos nodes worker será compensada pelos nodes restantes.

**Servidores Adjacentes**

- **	database**- Será o servidor responsável pelo Banco de dados para todas as ferramentas do Citsmart X.
- **	haproxy** - Um serviço de Proxy que pode ser utilizado em HA Alta Disponibilidade), a escolha de dois servidores será opcional, mas a perda dele, não pode ser compensada.
- **	bastion** - Responsável por criar o cluster Kubernetes com o RKE, também será responsável pelo gerênciamento via linha de comando no cluster.

**Diagrama do Ambiente**



![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/zbnRydhB03CvCH5Xs5ziF_.blob)

Diagrama acima contempla a utilização de 3 workers, que devem ser escalados de acordo com a necessidade da carga.

**Como é feita a implantação**

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/wJNGhCO4MfuNWGLWxfD0H_.blob)



Diagrama acima contempla a utilização de 3 workers, que devem ser escalados de acordo com a necessidade da carga.

**Observações:**

- Bastion precisa chegar ao Banco de dados na porta 22 e 5432
- Bastion precisa chegar aos servidores do cluster na porta 22
- Bastion precisa resolver nomes(DNS) do ambiente.
- Todos os servidores precisam ter acesso root.
- HAProxy porta 443
- Banco de dados porta 5432 para o cluster.



# ✅ 2. Regras de Firewall

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/-J1JDkop7gZ02z5qtk-VG_.blob)

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/tQviriC1mKgQ1NNNK7B5C_.blob)

## Justificativas

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/37k1OTGnAh8XwK7uFERpO_.blob)

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/JJjhcfY67Ec427564rFOH_.blob)

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/milIr4zU0zKabEFwq6B_n_image.png)

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/LhMfrUeqxJcgRiQ6fssh__.blob)



![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/U39XzJjXWJeIa44_7wgrR_.blob)

# ✅ 3. DNS

Após criar o servidor HAProxy na **etapa 1**, deve ser criadas as URL's abaixo e aponta-las para o servidor HAProxy caso for On-Premises ou IgressController caso for na Cloud.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/yUlfExN0aOg7rafYtbm7e_image.png)

# ✅ 4. Certificado

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/NdYedywXg_-R1LFrIAMx0_image.png)

# ✅ 5. Acesso à internet

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/4i4H87jB_raVs8yN50mEG_image.png)

Acesso ao Git da empresa para automação de implantação.

- URL: https\://gitlab.centralit.io
- Porta: 443

O processo de implantação faz uso de vários Helm Charts disponíveis em fontes como Artifact Hub e GitHub, Gitlab da Central IT.

Além disso, o processo depende de repositórios de imagens de contêiner, como Docker Hub, Quay.io e Nexus.

Em ambientes restritos, é essencial garantir acesso à internet durante a implantação para agilizar o processo.

# Considerações Finais

Esta arquitetura oferece:

- Alta Disponibilidade: redundância de control plane, workers, bancos e proxy.
- Automação CI/CD: GitLab + Runner + Ansible + Helm.
- Escalabilidade Horizontal: adição de workers conforme necessidade.
- Flexibilidade On-Prem ou Cloud: adaptação de DNS e Load Balancer.
- Segurança: acesso restrito, certificados TLS e autenticação e autorização centralizada.

# A seguir

Demais instalações:

<a href="https://docs.citsmart.com/aiops/portas-e-servicos-por-instancia#QMiHc" target="_blank">Xventory</a>

<a href="https://docs.citsmart.com/aiops/portas-e-servicos-por-instancia" target="_blank">AIOPS</a>

<a href="https://docs.citsmart.com/aura/manual-de-instalacao-de-um-novo-ambiente" target="_blank">AURA</a>


[title] Configurar instância para uso do aplicativo CITSmart GO
[path] Administração da Plataforma/Mobile/

O aplicativo CITSmart GO possibilita a realização de atendimentos em modo offline - em que o atendente não possui internet. Após o aplicativo se conectar a internet, a aplicação enviará, automaticamente, as informações para o ambiente em produção. Vale lembrar que a delegação da solicitação para um atendente deve ser realizada manualmente por um responsável.
O atendente visualizará apenas solicitações que foram delegadas a ele.

## Antes de começar

- [x] Instalar o aplicativo CITSmart GO;
- [x] No ambiente - instância do CITSmart -, configurar as seguintes
  funcionalidades:

* Webservice: indicar no item "permissões" os grupos de atendimento que poderão visualizar os tickets;
* Unidade: obter as coordenadas da unidade cadastrada.

## Procedimento

### Webservice

1. Acessar a funcionalidade através do menu principal `Sistema > Webservice > Operação Webservice;`
2. Na aba **Pesquisa de Operações**, buscar por cada um dos webservices abaixo, em seguida em cada um clicar no botão "Adicionar grupo" e incluir o(s) grupo(s) que o(s) atendente(s) estão vinculados:
   - request\_add\_attachments
   - request\_updateRequestList
   - request\_userLocation
   - request\_saveRequest
   - request\_uploadAttachment
   - request\_getByUser
   - request\_saveRequestNote
   - request\_updateRequestNoteList
   - request\_updateRequestListGroups
   - request\_uploadSignature
   - parameter\_query
3. Clicar no botão "**Gravar**" após configurar os grupos em cada webservice.

### Unidade

1. Acessar a funcionalidade através do menu principal `Cadastros Gerais > Gerência de Pessoal > Unidade;`
2. Buscar pela unidade na aba Pesquisa de Unidade e selecionar a escolhida;
3. Na aba Cadastro de Unidade com a unidade já escolhida, clicar no botão "**Obter Coordenadas**";
4. Clicar em "**Gravar**".

## O que fazer a seguir

Logar no aplicativo CITSmart GO já instalado, inserindo a URL, usuário e a senha do ambiente. Verificar os tickets e realizar atendimento.


[title] Campos Chave dos E-mails de Base de Conhecimento
[path] Administração da Plataforma/Untitled/

Este documento tem o objetivo de fornecer a relação dos campos chave disponíveis para o cadastro de modelo de e-mail relacionado à base de conhecimento.

## Relação dos Campos Chave

São relacionados abaixo os campos chave disponíveis para inserção no cadastro de modelo de e-mail relacionado à base de conhecimento:

<table columnWidths="229,437" selectedRows="" isTableHeaderOn="true" selectedColumns="">
  <tr>
    <td align="center">
      <p><strong>CAMPO-CHAVE</strong></p>
    </td>
    <td align="center">
      <p><strong>DESCRIÇÃO</strong></p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p>${APROVADOR}</p>
    </td>
    <td align="center">
      <p>Aprovador do Conhecimento. Informa o nome do aprovador do conhecimento.</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p>${AUTOR}</p>
    </td>
    <td align="center">
      <p>Autor do Conhecimento. Informa o nome do autor do conhecimento.</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p>${CONTEUDO}</p>
    </td>
    <td align="center">
      <p>Conteúdo do Conhecimento. Informa a descrição do conteúdo do conhecimento.</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p>${DATAEXPIRACAO}</p>
    </td>
    <td align="center">
      <p>Data de Expiração. Informa a data de expiração do conhecimento.</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p>${DATAINICIO}</p>
    </td>
    <td align="center">
      <p>Data de Criação do Conhecimento. Informa a data de criação do conhecimento.</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p>${DATAPUBLICACAO}</p>
    </td>
    <td align="center">
      <p>Data de Publicação. Informa a data de publicação do conhecimento.</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p>${DESTINATARIO}</p>
    </td>
    <td align="center">
      <p>Grupo ou usuário a que se destina o e-mail.</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p>${FONTEREFERENCIA}</p>
    </td>
    <td align="center">
      <p>Fonte/Referência do Conhecimento. Informa a descrição da fonte do conhecimento.</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p>${IDBASECONHECIMENTO}</p>
    </td>
    <td align="center">
      <p>Identificação do conhecimento. Informa a identificação do conhecimento na base.</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p>${JUSTIFICATIVAOBSERVACAO}</p>
    </td>
    <td align="center">
      <p>Justificativa/Observação. Informa a descrição da justificativa/observação do conhecimento.</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p>${NOMEORIGEM}</p>
    </td>
    <td align="center">
      <p>Nome origem do conhecimento. Informa a origem do nome do conhecimento.</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p>${ORIGEM}</p>
    </td>
    <td align="center">
      <p>Origem do Conhecimento. Informa a identificação da origem do conhecimento.</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p>${PRIVACIDADE}</p>
    </td>
    <td align="center">
      <p>Privacidade do Conhecimento. Informa a identificação da privacidade do conhecimento.</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p>${SITUACAO}</p>
    </td>
    <td align="center">
      <p>Situação do Conhecimento. Informa a identificação da situação do conhecimento.</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p>${TITULO}</p>
    </td>
    <td align="center">
      <p>Título do Conhecimento. Informa a descrição do título do conhecimento.</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p>${URL}</p>
    </td>
    <td align="center">
      <p>Caminho da base de conhecimento;</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p>${VERSAO}</p>
    </td>
    <td align="center">
      <p>Versão do Conhecimento. Informa a versão do conhecimento.</p>
    </td>
  </tr>
</table>

## Exemplos de utilização

- **Modelo de e-mail para criação/ alteração de base de conhecimento**

```Text
Senhor(a) ${DESTINATARIO},

Informamos que o conhecimento ${TITULO} foi registrado em ${DATACRIACAO} e se encontra,

Situação: ${SITUACAO}
Autor: ${AUTOR}

Caminho: ${URL}

Atenciosamente,
```

- **Modelo de e-mail para Data de Expiração de base de conhecimento**

```Text
Senhor(a) ${DESTINATARIO},

Informamos que o conhecimento ${TITULO} está próximo à expirar em ${DATAEXPIRACAO} e se encontra,

Situação: ${SITUACAO}
Autor: ${AUTOR}

Caminho: ${URL}:
Atenciosamente,
```


[title] Parametrização - Telefonia
[path] Administração da Plataforma/Untitled/

A parametrização da "Telefonia permite definir se ativa a integração dos webservices com a telefonia, informar o número de identificação do serviço de requisição, dentre outras ações possíveis afim de configurar o uso da telefonia no CITSmart.

## Procedimento

1. Acessar a funcionalidade através da navegação no menu principal `Parametrização > Telefonia;`
2. Definir os valores dos parâmetros (atributos);
3. Clicar no botão "**Gravar**" para efetuar a operação;
4. A lista abaixo representa os parâmetros da "**Telefonia**" e a finalidade de cada um deles:

| #   | Nome                                                                                                                                                       | Valores possíveis   | Finalidade                                                                                                                                                                                       | Orientações complementares                                                                                      |
| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
| 281 | Ativar WebService de integração com a Telefonia - Valores: "S" ou "N" Default: "N"                                                                         | S ou N (Default: N) | Definir se ativa a integração dos webservices com a telefonia.                                                                                                                                   | Caso não seja definido o valor para o parâmetro, será definido pelo sistema automaticamente o valor: “N” (Não). |
| 282 | A telefonia deve lançar uma solicitação filha, referente à visualização de informações de uma solicitação já existente? - Valores: "S" ou "N" Default: "N" | S ou N (Default: N) | Definir se ativa o lançamento automático de uma solicitação de serviço filha, da que está sendo visualizada ou executada, pelo webservice “visualizarSolicitacao”.                               | Caso não seja definido o valor para o parâmetro, será definido pelo sistema automaticamente o valor: “N” (Não). |
| 283 | ID do serviço de requisição de informações sobre uma solicitação já existente.                                                                             | S ou N              | Informar o número de identificação (ID) do serviço de requisição, o qual será utilizado para lançar a solicitação filha referente à visualização de informações de uma solicitação já existente. | Não se aplica                                                                                                   |

Tabela 1 - Lista de parâmetros


[title] Parametrização - Mudança
[path] Administração da Plataforma/Untitled/

O Gerenciamento de Mudanças é o processo responsável por avaliar, coordenar e decidir sobre a realização de mudanças propostas a Serviços e/ou Itens de Configuração (ICs). Os parâmetros a ser configurados permitem ajustar o envio de notificação, informar os modelos de e-mail para escalar a requisição de mudança, informar o nome dos fluxos referentes a aplicação e definir o tipo de votação usado no comitê consultivo de mudança, dentre outras ações.

## Procedimento

1. Acessar a funcionalidade através da navegação no menu principal `Parametrização > Gerência de Mudança;`
2. Definir os valores dos parâmetros (atributos);
3. Clicar no botão "**Gravar**" para efetuar a operação;
4. A lista abaixo apresenta os parâmetros da funcionalidade "**Mudança**" e a finalidade de cada um deles:

| #   | Nome                                                                                                  | Valores possíveis     | Finalidade                                                                                                                                                                                                                                                                                                                                                                                                                          | Orientações complementares                                                                                                               |
| --- | ----------------------------------------------------------------------------------------------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| 47  | Nome do fluxo padrão para mudanças                                                                    | Ex: RequisicaoMudanca | Informar o nome do fluxo de requisição de mudança “padrão”. Esse fluxo é definido na tela de “Desenho de Fluxo”.                                                                                                                                                                                                                                                                                                                    | Não se aplica                                                                                                                            |
| 120 | ID do modelo de e-mail para envio de notificação para o comitê de consultivo de mudanças              | Ex: 29                | Informar o número de identificação (ID) do modelo de e-mail de notificação para o Comitê de Consultivo de Mudanças. Será utilizado para envio das notificações de requisição de mudanças o modelo de e-mail definido neste parâmetro. Essa notificação será enviada para o Comitê de Consultivo de Mudanças. Esse ID do modelo de e-mail é definido na tela de “Modelo de E-mail”.                                                  | Caso não informe o número de identificação (ID) do modelo de e-mail, há possibilidade de não enviar o e-mail correto.                    |
| 122 | ID do modelo de e-mail que será enviado para o grupo de destino ao escalar uma requisição mudança     | Ex: 30                | Informar o número de identificação (ID) do modelo de e-mail de escalação de requisição de mudança. Ao escalar uma requisição de mudanças, será enviada para o grupo de destino uma notificação, conforme o modelo definido neste parâmetro. Esse ID do modelo de e-mail é definido na tela de “Modelo de E-mail”.                                                                                                                   | Caso não informe o número de identificação (ID) do modelo de e-mail, há possiblidade de não enviar o e-mail correto.                     |
| 133 | ID do modelo de e-mail para envio de notificação de reunião agendada                                  | Ex: 39                | Informar o número de identificação (ID) do modelo de e-mail de notificação de reunião agendada. Ao agendar uma reunião para uma requisição de mudança na tela de Gerenciamento de Mudanças, será enviado um e-mail para o grupo responsável, notificando sobre o agendamento da reunião. Esse ID do modelo de e-mail é definido na tela de “Modelo de E-mail”.                                                                      | Caso não informe o número de identificação (ID) do modelo de e-mail, há possiblidade de não enviar o e-mail correto.                     |
| 146 | Id template do questionário                                                                           | Ex: 13                | Informar o número de identificação (ID) do template para o questionário (checklist) referente à mudanças e liberação. Esse ID do template é definido na tela de “Template de Solicitação de Serviço”.                                                                                                                                                                                                                               | Não se aplica                                                                                                                            |
| 193 | Habilita o escalonamento de mudanças definido nas regras de escalonamento? (Ex: S ou N - Default 'N') | S ou N (Default: N)   | Definir se o escalonamento de mudanças determinado nas regras de escalonamento será habilitado. Essa regra de escalonamento de mudanças é definida na tela de “Regras de Escalonamento e Notificações Automáticas”.                                                                                                                                                                                                                 | Caso não informe o valor do parâmetro, será estabelecido o valor padrão do sistema: “N” (Não).                                           |
| 268 | ID do modelo de e-mail para notificar encerramento da mudança                                         |                       | Informar o número de identificação (ID) do modelo de e-mail usado para notificar encerramento de uma requisição de mudança. Ao encerrar uma requisição de mudança, na tela de “Gerenciamento de Mudanças”, será utilizado para o envio da notificação de encerramento da mesma o modelo de e-mail definido. Essa notificação será enviada para o solicitante. Esse ID do modelo de e-mail é definido na tela de “Modelo de E-mail”. | Caso não informe o número de identificação (ID) do modelo de e-mail, há possibilidade de não enviar o e-mail correto para o solicitante. |
| 279 | Nome do fluxo normal para mudanças                                                                    |                       | Informar o nome do fluxo de requisição de mudança normal. Esse fluxo é definido na tela de “Desenho de Fluxo”.                                                                                                                                                                                                                                                                                                                      | Caso não informe o valor do parâmetro, será exibida uma mensagem de erro na exibição da tela de Requisição de Mudança.                   |
| 280 | Nome do fluxo emergencial para mudanças                                                               |                       | Informar o nome do fluxo de requisição de mudança emergencial. Esse fluxo é definido na tela de “Desenho de Fluxo”.                                                                                                                                                                                                                                                                                                                 | Caso não informe o valor do parâmetro, será exibida uma mensagem de erro na exibição da tela de Requisição de Mudança.                   |

Tabela 1 - Lista de parâmetros


[title] País
[path] Administração da Plataforma/

Aqui é possível encontrar os **países** cadastrados no sistema. Além disso, há a opção de **registrar** um novo país ou **excluir **o que já estiver cadastrado.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/H8YH4gWBc9n4af_Nfiaqs_image.png "Hyper - Países")

***

Na aba "**País**", tanto é possível registrar um novo país, como exportar um arquivo **.csv** contendo as informações dos países já cadastrados no sistema.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/YkwU5ifPqCeVa0mcDjzsU_image.png" size="64" width="492" height="47" caption position="center" signedSrc="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/YkwU5ifPqCeVa0mcDjzsU_image.png"}

Além disso, é possível editar e excluir um país, basta escrever o nome do país desejado ou simplesmente a **ID do País **no campo de busca e prosseguir com a ação clicando em "**Editar**"**.**

***

- Ao clicar em "**Editar**", é possível realizar as alterações que deseja;

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/Ltl0PQAd9C3HuPlXdZ6cC_image.png)

<table columnWidths="217,527,248" selectedRows="" selectedTable="false" isTableHeaderOn="true" selectedColumns="">
  <tr>
    <td>
      <p><strong>Campos</strong></p>
    </td>
    <td>
      <p><strong>Descrição</strong></p>
    </td>
  </tr>
  <tr>
    <td>
      <p><strong>Nome</strong>*</p>
    </td>
    <td>
      <p>Adicione um novo país: <strong>Brasil</strong></p>
    </td>
  </tr>
</table>

As informações com asterisco (\*) são obrigatórias.

- Após concluir todas as alterações, clique em "**Registro**".


[title] Administração da Plataforma
[path] /


[title] Ferramenta de base de dados
[path] Administração da Plataforma/Untitled/

O objetivo é manter registro de scripts para a execução dos mesmos no sistema.

## Procedimento

1. Acessar a funcionalidade através da navegação no menu principal `Sistema > Banco de Dados > Ferramenta Base Dados;`
2. Para criar um tabela, clicar em "**Criar Tabela**";
3. Inserir os dados necessários;
4. Clicar em "**Executar**";
5. Para adicionar campos na tabela clicar na tabela escolhida;
6. Clicar no botão "**Adicionar Campos na Tabela**";
7. Será inserida uma linha de comando SQL na área de Console de Scripts SQL para inserção do campo na tabela;
8. Informar os dados necessários e clicar no botão "**Executar**".


[title] Campos Chave dos E-mails de Ticket
[path] Administração da Plataforma/Untitled/

Este documento tem o objetivo de fornecer a relação dos campos chave disponíveis para o cadastro de modelo de e-mail de Solicitação de serviço.

## Antes de começar

- [x] O disparo de e-mail ocorre somente após configuração da caixa de e-mail.

## Relação dos Campos Chave

São relacionadas abaixo os campos chave disponíveis para inserção no cadastro de modelo de e-mail relacionado à Solicitação de serviço:

<table columnWidths="247,419" selectedRows="" isTableHeaderOn="true" selectedColumns="">
  <tr>
    <td align="center">
      <p><strong>Campo-Chave</strong></p>
    </td>
    <td align="center">
      <p><strong>Descrição</strong></p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p>${ATRASOSLASTR}</p>
    </td>
    <td align="center">
      <p>Tempo de Atraso do SLA.Informa o tempo de atraso do SLA (Acordo de Nível de Serviço).</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p>${CONTRATO}</p>
    </td>
    <td align="center">
      <p>Contrato da Solicitação.Informa o nome do contrato referente à solicitação de serviço/incidente.</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p>${DATAHORAINICIO}</p>
    </td>
    <td align="center">
      <p>Data e hora de início do registro da solicitação.Informa a data e hora que foi registrado a solicitação de serviço/incidente.</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p>${DATAHORAFIM}</p>
    </td>
    <td align="center">
      <p>Data da finalização da Solicitação.Informa a data em que foi finalizada a solicitação de serviço/incidente.</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p>${DATAHORAINICIOSLASTR}</p>
    </td>
    <td align="center">
      <p>Data e hora de início do SLA.Informa a data e hora de início do SLA (Acordo de Nível de Serviço).</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p>${DATAHORALIMITESTR}</p>
    </td>
    <td align="center">
      <p>Prazo limite para atendimento da solicitação.Informa o prazo limite (data e hora) para atendimento da solicitação.</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p>${DATAHORASOLICITACAOSTR}</p>
    </td>
    <td align="center">
      <p>Data e hora do atendimento da solicitação.Informa a data e hora do atendimento da solicitação de serviço/incidente.</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p>${DEMANDA}</p>
    </td>
    <td align="center">
      <p>Tipo de Solicitação.Informa o tipo de solicitação (Incidente ou Requisição).</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p>${DESCRICAO}</p>
    </td>
    <td align="center">
      <p>Descrição da Solicitação.Informa a descrição da solicitação de serviço.</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p>${DESCRSITUACAO}</p>
    </td>
    <td align="center">
      <p>Descrição da Situação da Solicitação.Informa a descrição da Situação em que a Solicitação se encontra.</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p>${DETALHAMENTOCAUSA}</p>
    </td>
    <td align="center">
      <p>Detalhamento da Causa do Incidente.Informa o detalhamento da causa do incidente.</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p>${EMAILCONTATO}</p>
    </td>
    <td align="center">
      <p>E-mail do Solicitante para Contato.Informa o e-mail do solicitante.</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p>${FASEATUAL}</p>
    </td>
    <td align="center">
      <p>Fase Atual da Solicitação.Informa a fase atual da solicitação de serviço.</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p>${GRUPOATUAL}</p>
    </td>
    <td align="center">
      <p>Grupo Atual de Atendimento da Solicitação.Informa o grupo atual, responsável pelo atendimento da solicitação de serviço.</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p>${GRUPONIVEL1}</p>
    </td>
    <td align="center">
      <p>Grupo de Nível 1.Informa o grupo de nível 1 configurado para atendimento da solicitação.</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p>${IDSOLICITACAOSERVICO}</p>
    </td>
    <td align="center">
      <p>Número da Solicitação.Informa o número da solicitação de serviço.</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p>${IMPACTO}</p>
    </td>
    <td align="center">
      <p>Impacto da Solicitação de Serviço / Incidente.Informa a identificação do impacto da solicitação de serviço.</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p>${LINKPESQUISASATISFACAO}</p>
    </td>
    <td align="center">
      <p>Link para pesquisa de satisfação.Informa o link para fazer a avaliação do atendimento da solicitação de serviço.</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p>${LINKSOLICITACAOSERVICO}</p>
    </td>
    <td align="center">
      <p>Link para a solicitação de serviço.Informa o link para exibição do registro da solicitação de serviço.</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p>${NOMECONTATO}</p>
    </td>
    <td align="center">
      <p>Nome do Solicitante para Contato.Informa o nome do solicitante para contato.</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p>${NOMEGRUPOATUAL}</p>
    </td>
    <td align="center">
      <p>Retorna a descrição do Nome do grupoem que se encontra atualmente a solicitação de serviço.</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p>${NOMESERVICO}</p>
    </td>
    <td align="center">
      <p>Nome do Serviço.Informa o nome do serviço solicitado.</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p>${NOMEUNIDADERESPONSAVEL}</p>
    </td>
    <td align="center">
      <p>Unidade do Responsável.Informa a unidade do responsável pelo registro da solicitação de serviço.</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p>${NOMEUNIDADESOLICITANTE}</p>
    </td>
    <td align="center">
      <p>Unidade do Solicitante.Informa a unidade do solicitante.</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p>${OBSERVACAO}</p>
    </td>
    <td align="center">
      <p>Observação do Contato do Solicitante.Informa a observação descrita na solicitação de serviço.</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p>${ORIGEM}</p>
    </td>
    <td align="center">
      <p>Origem da Solicitação.Informa a origem da solicitação de serviço.</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p>${PRIORIDADE}</p>
    </td>
    <td align="center">
      <p>Prioridade do Atendimento da Solicitação.Informa a prioridade do atendimento da solicitação de serviço.</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p>${RESPONSAVEL}</p>
    </td>
    <td align="center">
      <p>Responsável pelo Registro da Solicitação.Informa o responsável pelo registro da solicitação de serviço.</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p>${RESPOSTA}</p>
    </td>
    <td align="center">
      <p>Descrição do Fechamento da Solicitação.Informa a descrição do fechamento da solicitação de serviço.</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p>${SERVICO}</p>
    </td>
    <td align="center">
      <p>Serviço Solicitado.Informa o nome do serviço que foi solicitado.</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p>${SITUACAO}</p>
    </td>
    <td align="center">
      <p>Situação da Solicitação;Informa a situação em que a solicitação de serviço se encontra.</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p>${SLAACOMBINAR}</p>
    </td>
    <td align="center">
      <p>SLA “A Combinar”.Informa se o SLA é a combinar.</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p>${SOLICITANTE}</p>
    </td>
    <td align="center">
      <p>Nome do Solicitante.Informa o nome do solicitante.</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p>${SOLICITANTEUNIDADE}</p>
    </td>
    <td align="center">
      <p>Nome do Solicitante e Unidade.Informa o nome do solicitante e a unidade em que o mesmo é alocado.</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p>${TELEFONECONTATO}</p>
    </td>
    <td align="center">
      <p>Telefone do Solicitante para Contato.Informa o número de telefone do solicitante para contato.</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p>${URGENCIA}</p>
    </td>
    <td align="center">
      <p>Urgência da Solicitação.Informa a identificação da urgência da solicitação de serviço.</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p>$ (RESPONSAVELATUAL)</p>
    </td>
    <td align="center">
      <p>Utilizar para e-mails de Delegação - Chave que retorna o nome do usuário que foi delegado em um ticket.</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p>${NOTA}</p>
    </td>
    <td align="center">
      <p>Utilizar em e-mails disparados na inclusão, resposta ou edição de uma ocorrência – Chave que retorna a descrição de uma ocorrência</p>
    </td>
  </tr>
</table>

Tabela 1 - Lista de campos chave


[title] Manual de utilização do aplicativo mobile CITSmart Experience - Android
[path] Administração da Plataforma/Mobile/Manual de utilização do aplicativo mobile CITSmart Experience/

Este documento tem o propósito de fornecer orientações necessárias para instalar, configurar e utilizar o aplicativo mobile CITSmart Experience, disponível nas plataformas Android e iOS.

O aplicativo Experience oferece a facilidade no atendimento, direcionamento de onde a solicitação está localizada, filtragem das solicitações pessoais e por grupo de trabalho, visualização dos detalhes de uma solicitação de serviço, entre diversas outras funcionalidades possíveis devido a renderização das páginas e leiaute responsivo

## Antes de começar

- [x] Para utilizar o aplicativo Experience é preciso criar o menu com as opções que poderão ser acessadas.

## Procedimento

1. Instalar o aplicativo Experience a partir da loja online (App Store ou Play Store);
2. Para criar uma conexão, clicar no botão “**Add**” ou “**Adicionar conexão**”;
3. Será apresentada tela “**Nova Conexão**” para registrar conexão:
4. Após informar os dados da conexão desejada, clicar no botão "**Salvar**";
5. Depois de adicionada a conexão, aparecerá a listagem das conexões criadas. Para alterar uma conexão, basta selecionar e manter pressionada a conexão e fazer a alteração;
6. Logar com o usuário e senha utilizados no CITSmart web;
7. Após realizar a conexão, será apresentada a tela com menus de funcionalidades disponíveis.

:::hint{type="warning"}
**Atenção: **Caso o aparelho seja trocado, esta conexão deve ser deletado.
:::


[title] Parametrização - Ticket
[path] Administração da Plataforma/Untitled/

Para a entrega de serviços são necessárias algumas configurações de parâmetros que permitem ações do gerenciamento de ticket, como por exemplo o fluxo padrão, a fase em que a solicitação de serviço ao ser registrada será encaminhada, entre outras.

## Procedimento

1. Acessar a funcionalidade através da navegação no menu principal `Parametrização > Gerência de requisição e Incidente;`
2. Definir o valor do parâmetro a ser configurado;
3. Efetuar a mudança;
4. Clicar no botão "**Gravar**";
5. A lista abaixo apresenta os parâmetros da funcionalidade ticket e a finalidade de cada um deles:

| #   | Nome                                                                                                                                                                                       | Valores possíveis                                                                                                                                                          | Finalidade                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Orientações adicionais                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 9   | ID Grupo Nível 1 (Ex: 1)                                                                                                                                                                   | Ex: 1                                                                                                                                                                      | Informar o número de identificação (ID) do grupo de atendimento do 1º nível. Este grupo é o grupo padrão a ser utilizado, caso não seja informado o grupo de atendimento de um serviço. Se o CITSmart for utilizado em múltiplos contratos, esse grupo deve ser definido no template de importação dos serviços ao contrato. Esse ID do grupo é definido na tela de “Cadastro de Grupo”.                                                                                                                                                                                       | Não se aplica                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| 30  | ID da fase padrão para execução de serviços (Ex: 2)                                                                                                                                        | Ex: 2                                                                                                                                                                      | Definir a fase em que uma solicitação de serviço ao ser registrada será encaminhada. (1 = fase de captura ou 2 = fase de execução).                                                                                                                                                                                                                                                                                                                                                                                                                                            | Não se aplica                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| 31  | Envia e-mail na execução dos fluxos de solicitações/incidentes (Ex: S ou N)                                                                                                                | S ou N                                                                                                                                                                     | Definir se será feito o envio de notificações por e-mail para o solicitante ao realizar a execução dos fluxos de solicitação de serviços/incidentes.                                                                                                                                                                                                                                                                                                                                                                                                                           | Não se aplica                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| 40  | Faz o controle de acessos do catalogo de serviço por unidade (Ex: S ou N)?                                                                                                                 | S ou N                                                                                                                                                                     | Definir se o controle de acesso do catálogo de serviço será feito por unidade. Caso seja, será disponibilizado na tela de "Cadastro de Unidade” um botão "Serviço" para vincular o(s) serviço(s) à unidade, onde os mesmos serão exibidos na solicitação de serviços conforme a unidade do solicitante informada.                                                                                                                                                                                                                                                              | Não se aplica                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| 41  | Faz o controle de vínculo de colaboradores aos contratos (Ex: S ou N)?                                                                                                                     | S ou N                                                                                                                                                                     | Definir se o controle de colaborares será feito por contrato. Caso seja, serão exibidos os contratos na tela de “Cadastro de Grupo” para vínculo dos mesmos ao grupo, onde os colaboradores pertencentes do grupo serão vinculados aos contratos.                                                                                                                                                                                                                                                                                                                              | Não se aplica                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| 42  | Página para cadastro de solicitações de serviço (será usado o padrão caso não seja informado)                                                                                              |                                                                                                                                                                            | Informar a página que será utilizada para o registro de Solicitações de Serviço/Incidentes. Default: /pages/solicitacaoServicoMultiContratos/solicitacaoServicoMultiContratos.load                                                                                                                                                                                                                                                                                                                                                                                             | Não há impacto negativo. Caso não informe a página, será utilizada a página padrão do sistema: /pages/solicitacaoServicoMultiContratos/solicitacaoServicoMultiContratos.load.                                                                                                                                                                                                                                                                                            |
| 50  | Aceitar Valor 0 (Zero) para quantidade e custo da atividade? (Ex: S ou N)                                                                                                                  | S ou N                                                                                                                                                                     | Definir se será aceito o valor 0 (zero) para quantidade e custo da Atividade do Serviço. Caso seja, será permitido executar uma Ordem de Serviço informando o valor 0,00. Caso não seja, o sistema não permitirá executar uma Ordem de Serviço sem informar o valor devido.                                                                                                                                                                                                                                                                                                    | Não se aplica                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| 57  | ID do modelo de e-mail que será enviado para o grupo de destino ao escalar uma solicitação. (Ex: 4)                                                                                        |                                                                                                                                                                            | Informar o número de identificação (ID) do modelo de e-mail. Esse modelo de e-mail será enviado para o grupo de destino ao escalar uma solicitação de serviço/incidente. Esse ID do modelo de e-mail é definido na tela de “Modelo de E-mail”.                                                                                                                                                                                                                                                                                                                                 | Caso não informe o número de identificação (ID) do modelo de e-mail, há possiblidade de não enviar o e-mail correto para o grupo de destino.                                                                                                                                                                                                                                                                                                                             |
| 58  | Notificar o grupo ao receber uma escalação de solicitação de serviço (Ex: S ou N).                                                                                                         | S ou N                                                                                                                                                                     | Definir se será notificado o grupo ao receber uma escalação de solicitação de serviço/incidente. Caso seja, ao escalar uma solicitação de serviço/incidente para o grupo, o mesmo será notificado via e-mail.                                                                                                                                                                                                                                                                                                                                                                  | Caso não informe o valor “S” para o parâmetro, o grupo não será notificado ao receber uma escalação de solicitação de serviço/incidente.                                                                                                                                                                                                                                                                                                                                 |
| 61  | Vincula contratos a unidade (Ex: S ou N)                                                                                                                                                   | S ou N                                                                                                                                                                     | Definir se será feito o vínculo de contratos à unidade. Caso seja, serão exibidos os contratos na tela de “Cadastro de Unidade” para que seja vinculado à unidade.                                                                                                                                                                                                                                                                                                                                                                                                             | Não se aplica                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| 62  | Identifica o id do serviço para solicitações de serviços e incidentes                                                                                                                      |                                                                                                                                                                            | Esse parâmetro deve ser configurado caso o portal do usuário esteja ativado. Deve informar o identificador (ID) do serviço para solicitações de serviços/incidentes a partir do portal. Esse ID está disponível no Catálogo de Serviços.                                                                                                                                                                                                                                                                                                                                       | Não se aplica                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| 65  | Identifica o id de origem do chamado padrão da solicitação de serviço                                                                                                                      |                                                                                                                                                                            | Informar o número de identificação (ID) da Origem padrão para abertura de solicitação de serviço/Incidente. Esse ID é definido na tela de cadastro de “Origem de Solicitações”.                                                                                                                                                                                                                                                                                                                                                                                                | Não se aplica                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| 69  | Validar campos Causa e Categoria da Solução da página solicitação serviço obrigatórios (Ex: S ou N - Default: 'N')                                                                         | S ou N (Default: N)                                                                                                                                                        | Definir se os campos “Causa” e “Categoria da Solução” da tela de Requisição de Serviço/Incidente serão de preenchimento obrigatórios.                                                                                                                                                                                                                                                                                                                                                                                                                                          | Caso não informe o valor do parâmetro, será estabelecido o valor padrão do sistema: “N” (Não).                                                                                                                                                                                                                                                                                                                                                                           |
| 72  | SMTP LEITURA - Limite de e-mails carregados em Solicitação Serviço                                                                                                                         | Ex: 20                                                                                                                                                                     | Definir o limite de e-mails que serão carregados na tela de Solicitação de Serviço/Incidente. Ao clicar no botão “carregar e-mail” na tela de Solicitação de Serviços/Incidentes, será carregada a quantidade de e-mails conforme estabelecido no parâmetro.                                                                                                                                                                                                                                                                                                                   | Não se aplica                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| 86  | Mostrar Categoria de serviço em Incidente (Ex: S ou N - Default 'S')                                                                                                                       | S ou N (Default: S)                                                                                                                                                        | Definir se a Categoria de Serviço será exibida na tela de Solicitação de Serviço/Incidente. Caso seja definido o valor “S”, será exibido o campo “Categoria de Serviço” na tela de Solicitação de Serviço/Incidente.                                                                                                                                                                                                                                                                                                                                                           | Caso não informe o valor do parâmetro, será utilizado o valor padrão do sistema: “S” (Sim).                                                                                                                                                                                                                                                                                                                                                                              |
| 103 | ID do modelo de e-mail para envio de notificação de alteração de serviço (Ex: 19)                                                                                                          |                                                                                                                                                                            | Informar o número de identificação (ID) do Modelo de E-mail de notificação de alteração de serviço. Ao alterar um Serviço do contrato, será utilizado para envio da notificação de alteração do serviço o modelo de e-mail definido neste parâmetro. Essa notificação será enviada para o usuário e/ou grupo associado ao serviço. Esse ID do modelo de e-mail é definido na tela de “Modelo de E-mail”.                                                                                                                                                                       | Caso não informe o identificador (ID) do Modelo de E-mail, há possiblidade de não enviar o e-mail correto.                                                                                                                                                                                                                                                                                                                                                               |
| 104 | Calcular a prioridade da solicitação dinamicamente usando a fórmula cadastrada. (Ex: S ou N - Default: 'N')                                                                                | S ou N (Default: N)                                                                                                                                                        | Definir se o cálculo da prioridade da solicitação será feito utilizando a fórmula cadastrada. Caso seja informado “S”, será calculada a prioridade da solicitação dinamicamente usando a fórmula cadastrada.                                                                                                                                                                                                                                                                                                                                                                   | Caso não informe o valor do parâmetro, será utilizado o valor padrão do sistema: “N” (Não).                                                                                                                                                                                                                                                                                                                                                                              |
| 105 | ID da origem que será setado como padrão ao criar um novo incidente                                                                                                                        |                                                                                                                                                                            | Informar o número de identificação (ID) da Origem padrão para abertura de solicitação de serviço/Incidente. Esse ID da origem é definido na tela de cadastro de “Origem de Solicitações”.                                                                                                                                                                                                                                                                                                                                                                                      | Não se aplica                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| 113 | ID do modelo de e-mail para escalação automática                                                                                                                                           |                                                                                                                                                                            | Informar o número de identificação (ID) do modelo de e-mail de escalação automática. A escalação automática acontece quando se configura no acordo de nível de serviço que após NN minutos (conforme configuração) o sistema deve escalar para o grupo ou prioridade (conforme configurado na tela de acordo de nível de serviço). Esse ID do modelo de e-mail é definido na tela de “Modelo de E-mail”.                                                                                                                                                                       | Caso não informe o número de identificação (ID) do modelo de e-mail, há possiblidade de não enviar o e-mail correto.                                                                                                                                                                                                                                                                                                                                                     |
| 115 | Tirar vinculo de localidade física com unidade? (Ex: S ou N - Default: 'N')                                                                                                                | S ou N (Default: N)                                                                                                                                                        | Definir se vínculo de localidade física com unidade será retirado. Caso seja informado “S”, será retirado o vínculo de localidade física com a unidade, ou seja, a localidade não será estabelecida quando informar a unidade, ao registrar uma solicitação de serviço/incidente.                                                                                                                                                                                                                                                                                              | Caso não informe o valor do parâmetro, será estabelecido o valor padrão do sistema: “N” (Não).                                                                                                                                                                                                                                                                                                                                                                           |
| 119 | Tipo de captura de solicitações/Incidentes (1-Na execução, 2-No direcionamento) (Default: 1)                                                                                               | 1- Na execução ou 2- No direcionamento (Default: 1)                                                                                                                        | Definir o tipo de captura de Solicitações/Incidentes: 1 = Na execução ou 2 = No direcionamento;                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Caso não informe o valor do parâmetro, será utilizado o valor padrão do sistema: “1” = Na execução.                                                                                                                                                                                                                                                                                                                                                                      |
| 134 | ID do grupo padrão para atendimento de requisições de RH                                                                                                                                   |                                                                                                                                                                            | Informar o número de identificação (ID) do grupo padrão para o atendimento das requisições de Recursos Humanos. Esse ID é definido na tela de “Cadastro de Grupo”.                                                                                                                                                                                                                                                                                                                                                                                                             | Não se aplica                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| 137 | ID do modelo de e-mail para envio de notificação de uma avaliação "ruim" ou "regular", em uma pesquisa de satisfação                                                                       |                                                                                                                                                                            | Informar o número de identificação (ID) do modelo de e-mail de notificação de uma avaliação “ruim” ou “regular” em uma pesquisa de satisfação. Quando uma pesquisa de satisfação de alguma solicitação recebe um valor negativo (regular ou ruim) o e-mail de notificação (informado no parâmetro) é enviado ao determinado grupo (configurado no parâmetro 138) informando os dados da avaliação feita.                                                                                                                                                                       | Caso não informe o número de identificação (ID) do modelo de e-mail, há possiblidade de não enviar o e-mail correto.                                                                                                                                                                                                                                                                                                                                                     |
| 138 | ID do grupo que receberá e-mail de notificação de uma avaliação "ruim" ou "regular", em uma pesquisa de satisfação                                                                         |                                                                                                                                                                            | Informar o número de identificação (ID) do grupo que receberá o e-mail de notificação de uma avaliação “ruim” ou “regular” realizada em uma pesquisa de satisfação, a fim de que providências sejam tomadas sobre essa avaliação negativa. Esse ID do grupo é definido na tela de “Cadastro de Grupo”.                                                                                                                                                                                                                                                                         | Caso não informe o número de identificação (ID) do grupo, não será realizado o envio do e-mail.                                                                                                                                                                                                                                                                                                                                                                          |
| 139 | Prazo em dias para responder pesquisa de satisfação referente às solicitações de serviço (Ex. 7)                                                                                           |                                                                                                                                                                            | Definir o prazo (em dias) para responder a pesquisa de satisfação referente às solicitações de serviço. Caso não responda a pesquisa de satisfação referente às solicitações de serviço, será estabelecido o prazo em dias (conforme definido no parâmetro) para ser realizada a automatização da resposta.                                                                                                                                                                                                                                                                    | Não se aplica                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| 151 | Usar aprovação automática de pesquisa de satisfação não respondida (Ex: S ou N - Default: 'N')                                                                                             | S ou N (Default: N)                                                                                                                                                        | Ativar a aprovação automática de pesquisa de satisfação, caso não seja respondida.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Não se aplica                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| 152 | Nota padrão para pesquisa de satisfação automática. (Usar um ID válido de um grau de satisfação)                                                                                           |                                                                                                                                                                            | Definir a nota padrão para pesquisa de satisfação. Caso seja ativada a aprovação de pesquisa de satisfação automática, será estabelecida a resposta automática da pesquisa de satisfação, conforme definido neste parâmetro.                                                                                                                                                                                                                                                                                                                                                   | Não se aplica                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| 171 | Limite de dias para a reabertura de Incidentes/Requisição de serviços.                                                                                                                     |                                                                                                                                                                            | Definir o limite de dias para reabertura de Incidentes/Requisição de Serviços.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Não se aplica                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| 182 | Pasta para ser salvo a Descrição e a solução da solicitação de serviço na Base de Conhecimento. (Ex: Windows - Descrição\_Resposta\_ Para\_BaseConhecimento)                               | Ex: Windows - Descrição\_Resposta \_Para\_BaseConhecimento                                                                                                                 | Definir o diretório para armazenar a descrição da resposta da solicitação de serviço/incidente para ser gravada na base de conhecimento. Na tela de Solicitação de Serviço/Incidente é apresentada o campo “Gravar Solução/Resposta na Base de Conhecimento”. Ao atender uma solicitação de serviço/incidente e caso queira gravar a descrição da Solução Resposta na base conhecimento, basta selecionar o campo e informar o título, feito isso, ao gravar e avançar o fluxo, a descrição da solução resposta da solicitação será armazenada na pasta definida no parâmetro. | Não se aplica                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| 190 | Liga o funcionamento das regras de escalonamento? (Ex: S ou N - Default:'N')                                                                                                               | S ou N (Default: N)                                                                                                                                                        | Definir se o funcionamento das regras de escalonamento será habilitado.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Caso não informe o valor do parâmetro, será estabelecido o valor padrão do sistema: “S” (Sim).                                                                                                                                                                                                                                                                                                                                                                           |
| 192 | Mostrar Gravar Solução/Reposta na Base de Conhecimento? OBS: Apenas mostrará na criação de uma Nova Solicitação se a Situação estiver marcada como 'Resolvida'. (Ex: S ou N - Default 'S') | S ou N (Default: S)                                                                                                                                                        | Definir se a Solução/Resposta da Requisição de Serviço/Incidente será gravada na Base de Conhecimento. Na tela de Requisição de Serviço/Incidente será exibido o campo “Gravar Solução/Resposta na Base de Conhecimento”, no qual deve informar o título referente à solução/resposta. Neste caso, ao gravar as informações da requisição de serviço/incidente será gravada na Base de Conhecimento a solução/resposta da determinada solicitação.                                                                                                                             | Caso não informe o valor do parâmetro, será estabelecido o valor padrão do sistema: “S” (Sim).                                                                                                                                                                                                                                                                                                                                                                           |
| 195 | Id do modelo de e-mail para envio de notificação de solicitação com prazo a vencer (Ex.: 1)                                                                                                |                                                                                                                                                                            | Informar o número de identificação (ID) do modelo de e-mail de notificação de solicitação com prazo a vencer. Ao criar uma regra de escalonamento, é definido o prazo para vencimento da solicitação, onde será enviado um e-mail para o usuário (definido no parâmetro 197) notificando o prazo para vencimento da solicitação.                                                                                                                                                                                                                                               | Caso não informe o número de identificação (ID) do modelo de e-mail, há possiblidade de não enviar o e-mail correto.                                                                                                                                                                                                                                                                                                                                                     |
| 197 | Login do usuário que receberá e-mail referente a regras de escalonamento de solicitação de serviço que estão vencendo (Ex.: Consultor)                                                     |                                                                                                                                                                            | Definir o login do usuário que receberá o e-mail referente às regras de escalonamento de solicitação de serviço que estão vencendo. Quando criamos uma regra de escalonamento, definimos o prazo para vencimento da solicitação, e o login de usuário definido nesse parâmetro irá receber um e-mail notificando que a solicitação entrou no status “vencendo”.                                                                                                                                                                                                                | Caso não informe o login do usuário, o e-mail não será enviado.                                                                                                                                                                                                                                                                                                                                                                                                          |
| 200 | Habilitar rotina para leitura de e-mails novos automaticamente? (Ex: S ou N - Default 'N')                                                                                                 | S ou N (Default: N)                                                                                                                                                        | Habilitar a rotina de leitura de e-mails automática. Essa rotina ao ser habilitada funciona da seguinte forma: Ao enviar um e-mail para o suporte do CITSmart será feita a leitura do e-mail automática, caso o e-mail seja referente a uma solicitação, será verificado o título do e-mail se contém a palavra ‘Solicitação’ e o número da solicitação, caso contenha, será armazenado o e-mail como ocorrência na solicitação referente.                                                                                                                                     | Caso não informe o valor para o parâmetro, será estabelecido o valor padrão do sistema: “N” (Não).                                                                                                                                                                                                                                                                                                                                                                       |
| 215 | Receber notificação ao encerrar/escalonar solicitações vinculadas (Ex: S ou N - Default: 'S')                                                                                              | S ou N (Default: S)                                                                                                                                                        | Ativar/inativar o envio de notificações das solicitações filhas para o grupo executor das solicitações pai. Ao informar o valor ‘S’ para o parâmetro, o sistema enviará para o grupo executor das solicitações de serviço pai, e-mails de notificação a respeito de criação, escalonamento, captura, demais alterações e encerramento de solicitações de serviço filhas. Será utilizado o modelo de e-mail vinculado ao serviço da solicitação filha.                                                                                                                          | Não se aplica                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| 216 | Id modelo de e-mail criação que será enviado ao grupo executor da solicitação relacionada                                                                                                  |                                                                                                                                                                            | Informar o número de identificação (ID) do modelo de e-mail de criação que será enviado ao grupo executor de uma solicitação relacionada a outra. Esse ID do modelo de e-mail é definido na tela de “Modelo de E-mail”.                                                                                                                                                                                                                                                                                                                                                        | Se o número de identificação (ID) não for informado corretamente o sistema não enviará e-mails de notificação.                                                                                                                                                                                                                                                                                                                                                           |
| 217 | Id modelo de e-mail ações que será enviado ao grupo executor da solicitação relacionada                                                                                                    |                                                                                                                                                                            | Informar o número de identificação (ID) do modelo de e-mail de demais ações que será enviado ao grupo executor de uma solicitação relacionada a outra. Esse ID do modelo de e-mail é definido na tela de “Modelo de E-mail”.                                                                                                                                                                                                                                                                                                                                                   | Se o número de identificação (ID) não for informado corretamente o sistema não enviará e-mails de notificação.                                                                                                                                                                                                                                                                                                                                                           |
| 218 | Id modelo de e-mail encerramento que será enviado ao grupo executor da solicitação relacionada                                                                                             |                                                                                                                                                                            | Informar o número de identificação (ID) do modelo de e-mail de encerramento que será enviado ao grupo executor de uma solicitação relacionada a outra. Esse ID do modelo de e-mail é definido na tela de “Modelo de E-mail”.                                                                                                                                                                                                                                                                                                                                                   | Se o número de identificação (ID) não for informado corretamente o sistema não enviará e-mails de notificação.                                                                                                                                                                                                                                                                                                                                                           |
| 227 | Identificador do elemento do fluxo que é o responsável pela execução da solicitação de serviço                                                                                             |                                                                                                                                                                            | Definir o elemento do fluxo responsável pela execução da solicitação de serviço.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Não se aplica                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| 231 | Ativar envio de e-mail quando for editado um incidente (S ou N - Default: 'S')                                                                                                             | S ou N (Default: S)                                                                                                                                                        | Habilitar/Desabilitar o envio de notificação de alteração da solicitação (incidente) por e-mail para o solicitando. Ao habilitar o parâmetro, quando houver alteração nas informações da solicitação (incidente) será enviado um e-mail ao solicitante notificando sobre a alteração feita.                                                                                                                                                                                                                                                                                    | Não se aplica                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| 251 | ID do modelo de e-mail para notificar o solicitante sobre o lançamento de ocorrências da solicitação                                                                                       |                                                                                                                                                                            | Informar o número de identificação (ID) do modelo de e-mail que será utilizado para notificar o solicitante sobre o lançamento de ocorrências da solicitação. Esse ID do Modelo de E-mail é definido na tela de “Modelo de E-mail”.                                                                                                                                                                                                                                                                                                                                            | Com o número de identificação do modelo de e-mail que será utilizado para notificar o solicitante sempre que for aberta uma ocorrência permitida a visualização do solicitante. Se o número de identificação (ID) não for informado corretamente o sistema não enviará e-mails de notificação.                                                                                                                                                                           |
| 260 | Tipo hierarquia do filtro unidade (Default 1-Lista sem Restrição, 2-Unidades do colaborador logado)                                                                                        | Ex: 1- Unidade sem restrição; 2- Unidade de colaborador e suas unidades filhas (restritivo); 3- Unidade do colaborador juntamente com seus níveis superiores (restritivo). | Definir qual o tipo de hierarquia será utilizado para gerar a árvore de unidades que um colaborador tem permissão de acessar.                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Alterar como o sistema irá gerar a árvore de unidades permitidas para um usuário/colaborador, pode ser que muitas unidades não sejam visualizadas se o tipo de hierarquia utilizar restrição de acesso.                                                                                                                                                                                                                                                                  |
| 261 | Quantidade de Registros retornados na Pesquisa Avançada (Ex: 50)                                                                                                                           |                                                                                                                                                                            | Definir quantos registros serão retornados pelo sistema na Pesquisa Avançada de Solicitação de Serviços.                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Caso não informe o valor do parâmetro, o sistema irá retornar na Pesquisa Avançada de Solicitação de Serviços todos os registros relacionados à busca do usuário. Qualquer valor que o usuário inserir irá limitar a quantidades de registros da pesquisa para o valor do parâmetro. Se a pesquisa do usuário tiver mais registros que o definido pelo parâmetro, o sistema irá representar uma mensagem de erro relacionada e não retornará nenhum registro ao usuário. |
| 264 | Filtrar por Solicitação em Andamento                                                                                                                                                       | S ou N                                                                                                                                                                     | Se for definido o valor “S” para o parâmetro, a opção “Em andamento” do campo “Situação” do Portal ficará selecionada por padrão e irá retornar uma lista de solicitações somente com requisição cuja tarefa atual esteja igual a 'Em Andamento'.                                                                                                                                                                                                                                                                                                                              | Não se aplica                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| 274 | Filtrar a "Categoria de Serviço" pelo CONTRATO e/ou SERVIÇO na Solicitação de Serviços? Valores: "S" ou "N". Default: "S"                                                                  | S ou N (Default: S)                                                                                                                                                        | Definir se o filtro da categoria de serviço, na tela de solicitação de serviços, será pelo serviço do contrato. Se ativado, na tela de registro de solicitação, serão disponibilizadas somente as categorias de serviço que estão vinculadas ao serviço do contrato.                                                                                                                                                                                                                                                                                                           | Não se aplica                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| 288 | URL Logomarca pesquisa de satisfação. (Ex.: [http://www.citsmart.com](http://www.citsmart.com) /imagens/logo.png)                                                                          | Ex: citsmart.com/ imagens/logo.png                                                                                                                                         | Informar a URL da imagem que será utilizada como logomarca na tela de pesquisa satisfação.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Não se aplica                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| 289 | Envia Notificação nas Solicitações Relacionadas conforme configurado para o Grupo? (S ou N)                                                                                                | S ou N                                                                                                                                                                     | Definir se será enviado notificações de e-mail para o grupo executor quando criar uma solicitação relacionada a outra.                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Não se aplica                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| 290 | ID do modelo de e-mail enviado ao suspender uma solicitação de serviço                                                                                                                     |                                                                                                                                                                            | Informar o número de identificação (ID) do modelo de e-mail de suspensão de solicitação de serviço. Ao suspender uma solicitação de serviço será utilizado para envio da notificação de suspensão o modelo de e-mail informado neste parâmetro. Essa notificação será enviada para o solicitante. O ID do modelo de e-mail é definido na tela de “Modelo de E-mail”.                                                                                                                                                                                                           | Não se aplica                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| 291 | ID do modelo de e-mail enviado ao reativar uma solicitação de serviço                                                                                                                      |                                                                                                                                                                            | Informar o número de identificação (ID) do modelo de e-mail de reativação de solicitação de serviço. Ao reativar uma solicitação de serviço será utilizado para envio da notificação de reativação o modelo de e-mail informado neste parâmetro. Essa notificação será enviada para o solicitante. O ID do modelo de e-mail é definido na tela de “Modelo de E-mail”.                                                                                                                                                                                                          | Não se aplica                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| 294 | Solicitante selecionado ao criar uma Solicitação Relacionada: - Valores: 0-Nenhum, 1-Solicitante e 2-Usuário logado. Default:0                                                             | S ou N (Default: S)                                                                                                                                                        | Definir se, quando criar uma solicitação relacionada, os campos para preenchimento dos dados do solicitante serão preenchidos pelo sistema com os dados do solicitante da solicitação principal.                                                                                                                                                                                                                                                                                                                                                                               | Caso não seja definido o valor para o parâmetro, será definido pelo sistema automaticamente o valor: “S” (Sim).                                                                                                                                                                                                                                                                                                                                                          |
| 295 | Reabrir Solicitação Pela Pesquisa de Satisfação (Valores possíveis: S ou N, Default: N)                                                                                                    | S ou N (Default: N)                                                                                                                                                        | Habilitar a reabertura da solicitação pela pesquisa de satisfação. Quando o valor do parâmetro for “S”, na tela de pesquisa satisfação, irá exibir a opção “Não Atendida” no campo “Avaliação” que ao ser selecionada exibirá o botão para reabrir a solicitação de serviço. Quando o valor do parâmetro for “N”, a opção “Não Atendida” não irá ser exibida no campo “Avaliação”, portanto o botão para reabrira solicitação continuará desabilitado e invisível ao usuário.                                                                                                  | Caso não seja definido o valor para o parâmetro, será definido pelo sistema automaticamente o valor: “N” (Não).                                                                                                                                                                                                                                                                                                                                                          |
| 296 | Nome(s) do(s) fluxo(s) de aprovação pelo usuário superior (separar por vírgula)                                                                                                            |                                                                                                                                                                            | Configurar o total de itens que devem ser importados de uma só vez do banco para o Solr                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Não se aplica                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| 299 | Requisição/Incidente - Ativar troca de mensagens (Valores: "S" ou "N" Default: "N")                                                                                                        | S ou N (Default: N)                                                                                                                                                        | Ativar a troca de mensagens entre o solicitante e o responsável pela solicitação                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Não se aplica                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| 301 | Exibir o título da solicitação/incidente (Valores: "S" ou "N" Default: "N")                                                                                                                | S ou N (Default: N)                                                                                                                                                        | Definir se o campo título da solicitação/incidente será exibido                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Não se aplica                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| 306 | Nível de Suporte da Ferramentas de Gerenciamento de Incidentes                                                                                                                             |                                                                                                                                                                            | A qualidade da ferramenta de gerenciamento de incidentes para apoiar as atividades. Coletada através de comparação com as funcionalidades existentes na ferramenta e as práticas de ITSM                                                                                                                                                                                                                                                                                                                                                                                       | Não se aplica                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| 307 | Maturidade do Processo de Gerenciamento de Incidentes                                                                                                                                      |                                                                                                                                                                            | A maturidade com que executamos as atividades de gerenciamento de incidentes, esta informação é coletada através de processo de assessment.                                                                                                                                                                                                                                                                                                                                                                                                                                    | Não se aplica                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| 343 | Restringe por atribuição na pesquisa avançada? (Valores: "S" ou "N" Default: "S")                                                                                                          | S ou N (Default: S)                                                                                                                                                        | Permite o controle de acesso (segurança) à funcionalidade de Pesquisa Avançada.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Não se aplica                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| 351 | Habilita a criação de ocorrências de localização através da unidade durante a criação de solicitações                                                                                      | S ou N (Default: N)                                                                                                                                                        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Não se aplica                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| 372 | Habilitar complemento obrigatório ao suspender a solicitação                                                                                                                               | S ou N (Default: N)                                                                                                                                                        | Caso este parâmetro seja Sim, o sistema vai mostrar e exigir o preenchimento de um texto para o atendente justificar o motivo de uma suspensão do ticket.                                                                                                                                                                                                                                                                                                                                                                                                                      | Não se aplica                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| 379 | Nível de Suporte da Ferramenta de Gerenciamento de Requisições                                                                                                                             |                                                                                                                                                                            |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Não se aplica                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| 380 | Maturidade do Processo de Gerenciamento de Requisições                                                                                                                                     |                                                                                                                                                                            |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |

Tabela 1- Tabela de parâmetros


[title] Cadastrar o motivo de negação do check in
[path] Administração da Plataforma/Mobile/

Esta funcionalidade permite registrar o motivo de negação do check in, o qual será utilizado ao realizar o check in através do aplicativo CITSmart Enterprise ITSM Mobile.

## Procedimento

1. Acessar a funcionalidade através da navegação no menu principal `Gestão Integrada > Gerência de Força de Atendimento > Cadastro de Motivo de Negação;`
2. Na aba "**Cadastrar Motivo de Negação de Checkin**" e descrever o motivo desejado;
3. Clicar no botão "**Gravar**" para efetuar a operação.


[title] Manual de utilização do aplicativo mobile CITSmart Experience - IOS
[path] Administração da Plataforma/Mobile/Manual de utilização do aplicativo mobile CITSmart Experience/

Este documento tem o propósito de fornecer orientações necessárias para instalar, configurar e utilizar o aplicativo mobile CITSmart Experience, disponível nas plataformas Android e iOS.

O aplicativo Experience oferece a facilidade no atendimento, direcionamento de onde a solicitação está localizada, filtragem das solicitações pessoais e por grupo de trabalho, visualização dos detalhes de uma solicitação de serviço, entre diversas outras funcionalidades possíveis devido a renderização das páginas e leiaute responsivo

## Antes de começar

- [x] Para utilizar o aplicativo Experience é preciso criar o menu com as opções que poderão ser acessadas.

## Procedimento

1. Instalar o aplicativo Experience a partir da loja online (App Store ou Play Store);
2. Para criar uma conexão, clicar no botão “**Add**” ou “**Adicionar conexão**”;
3. Será apresentada tela “**Nova Conexão**” para registrar conexão:
4. Após informar os dados da conexão desejada, clicar no botão "**Salvar**";
5. Depois de adicionada a conexão, aparecerá a listagem das conexões criadas. Para alterar uma conexão, basta selecionar e manter pressionada a conexão e fazer a alteração;
6. Logar com o usuário e senha utilizados no CITSmart web;
7. Após realizar a conexão, será apresentada a tela com menus de funcionalidades disponíveis.

:::hint{type="warning"}
**Atenção: **Caso o aparelho seja trocado, esta conexão deve ser deletado.
:::


[title] Obter assinatura em atendimento de campo
[path] Administração da Plataforma/Mobile/

Este documento tem por objetivo explanar sobre a configuração do aplicativo CITSmart (GO e Experience) para que o técnico receba a assinatura digital de um validador em atendimento de campo.

## Antes de começar

- [x] Ter o aplicativo CITSmart mobile previamente instalado. Para que o técnico em campo, possa visualizar tickets apenas atribuídos a ele em sua listagem de solicitações, o atendente/administrador deverá setar o parâmetro 435 para a opção “Sim”.

## Procedimento

### No CITSmart:

1. Acessar o menu principal `Processos > Gerência de Portfólio e Catálogo > Portfólio;`
2. Buscar pelo portfolio pretendido e clicar em “**Avançar**”;
3. Selecionar o serviço e clicar em “**Avançar**”;
4. Clicar na guia **Contratos**;
5. Selecionar o contrato e clicar em “**Avançar**”;
6. Clicar na guia **Requisições**;
7. Selecionar a atividade e clicar em “**Editar**”;
8. Configurar para a opção “**Sim**” o campo *Exige assinatura para Mobile*;
9. Clicar em “**Gravar**”.

### No mobile:

1. Ao capturar um ticket (usando o mobile), o técnico deve preencher os campos disponibilizados e ao colocar o ticket com status de “Resolvido”, o campo de **Assinaturas** ficará ativo para que se possa colocar o *Número do registro/Matrícula*, o *Nome* e a *Assinatura* do validador em campo. Esta assinatura será feita com o dedo na tela do mobile;
2. Clicar no botão “Opções” e em seguida em “Gravar e avançar o fluxo”;
3. O ticket não aparecerá mais na listagem do técnico;
4. O atendente/administrador somente verá a solicitação atendida pelo técnico, quando buscar a mesma na *pesquisa avançada* (menu lateral da tela de listagem de tickets) e ao abrir poderá visualizar assinatura colhida também.


[title] Untitled
[path] /


[title] Importar colaborador
[path] Administração da Plataforma/Untitled/

Esta funcionalidade permite realizar a importação da planilha de colaborador.

## Antes de começar

- [x] A importação requer o cadastro da planilha para importação do colaborador.

## Procedimento

1. Acessar a funcionalidade através do menu `Sistema > Importação e Carga de Dados > Carga Colaborador;`
2. Clicar na aba **Importação**;
3. Clicar em "**Escolher arquivo**" e selecionar o arquivo o qual deve estar em formato ".xls" ou ".xlsx";
4. Clicar em "**Importar**".


[title] Parametrização - VoIP
[path] Administração da Plataforma/Untitled/

VoIP (Voice over Internet Protocol) é o roteamento de conversação humana usando a Internet ou qualquer outra rede de computadores baseada no Protocolo de Internet, tornando a transmissão de voz mais um dos serviços suportados pela rede de dados. Os parâmetros do "VoIP" permitem definir a senha para comunicação com o servidor, informar o ramal de comunicação padrão para ligação VoIP, dentre outras ações afim de configurar o uso do VoIP no CITSmart.

## Procedimento

1. Acessar a funcionalidade através da navegação no menu principal `Parametrização > Voip;`
2. Definir os valores dos parâmetros (atributos);
3. Clicar no botão "**Gravar**" para efetuar a operação;
4. A lista abaixo representa os parâmetros do "**VoIP**" e a finalidade de cada um deles:

| #   | Nome                                                                                                                                            | Valores possíveis                                                                                                                                                                                                                                                            | Finalidade                                                                                                  | Qual é o impacto no sistema?                                                                                                                                                                     |
| --- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 323 | VoIP - Ativar VoIP (Valores: "S" ou "N" Default: "N")                                                                                           | S ou N (Default: N)                                                                                                                                                                                                                                                          | Ativar o recurso VoIP.                                                                                      | Assim que ativo um ícone de fone de ouvido, ficará disponível no rodapé da tela Portal de Serviços (Smart Portal) para que o usuário possa entrar em contato com o HelpDesk via telefone (VoIP). |
| 324 | VoIP - Servidor (ex.: [https://127.0.0.1:8089/janus](https://127.0.0.1:8089/janus))                                                             | Ex: [https://127.0.0.1:8089/janus](https://127.0.0.1:8089/janus)                                                                                                                                                                                                             | Endereço SIP do servidor (SIP = Protocolo de Iniciação e Sessão) para uso do VoIP                           | Não se aplica                                                                                                                                                                                    |
| 325 | VoIP - Domínio (ex.: 127.0.0.1)                                                                                                                 | Ex: 127.0.0.1                                                                                                                                                                                                                                                                | VoIP - Domínio (ex.: 127.0.0.1)                                                                             | Não se aplica                                                                                                                                                                                    |
| 326 | VoIP - Porta (ex.: 5061)                                                                                                                        | Ex: 5061                                                                                                                                                                                                                                                                     | Informar a porta por onde trafega a informação de voz                                                       | Não se aplica                                                                                                                                                                                    |
| 327 | VoIP - Usuário (ex.: goofy, substitui o Identificador SIP quando informado)                                                                     | Ex: goofy, substitui o Identificador SIP quando informado                                                                                                                                                                                                                    | Identificação para comunicação com o servidor                                                               | Não se aplica                                                                                                                                                                                    |
| 328 | VoIP - Senha                                                                                                                                    | Valores Possíveis – Não se aplica                                                                                                                                                                                                                                            | Senha para comunicação com o servidor                                                                       | Não se aplica                                                                                                                                                                                    |
| 329 | VoIP - Ramal (ex.: 0800)                                                                                                                        | Ex:: 0800                                                                                                                                                                                                                                                                    | Informar o ramal de comunicação padrão para ligação VoIP                                                    | Não se aplica                                                                                                                                                                                    |
| 330 | VoIP - Abordagem de Registro (Ex: 1. Registrar usando senha simples; 2. Registrar usando a senha HA1; 3. Registre como um convidado (sem senha) | Se o usuário configurar:1 - Significa que o sistema irá usar a senha definida no parâmetro 328;2 - Significa que o sistema irá usar uma senha criptografada;3 - Significa que não terá senha, e mesmo que definido o parâmetro 328, o sistema irá desconsiderar o parâmetro. | Abordagem de registro para que ocorra a comunicação, seja uma abordagem de registro utilizando senha ou não | Não se aplica                                                                                                                                                                                    |

Tabela 1 - Lista de parâmetros


[title] Manual de utilização do aplicativo CITSmart GO
[path] Administração da Plataforma/Mobile/

O objetivo do aplicativo CITSmart GO é permitir a realização de atendimentos do técnico em campo no modo offline (onde o atendente não possui internet).

## Antes de começar 

- [x] Ter configurado o aplicativo na instância ITSM;
- [x] Instalar o aplicativo CITSmart GO (Android e iOS);
- [x] É necessário delegar tarefas ao técnico no site CITSmart para que o mesmo as possa atender em campo no modo offline.

## Procedimento

:::hint{type="info"}
Ao logar no aplicativo CITSmart GO, a primeira sincronização pode demorar alguns instantes, pois para funcionar offline tem que baixar todas as solicitações e enviar as que tiveram mudanças para que o aplicativo funcione corretamente.
:::

1. Informar os dados para login do aplicativo;
2. Selecionar o ticket desejado e clicar sobre o mesmo. Será apresentado uma tela com os dados da solicitação, inclusive um mapa do local onde será realizado o atendimento;
3. Clicar no botão "**Executar solicitação**" e em seguida "**Outras informações**" (está opção só estará disponível se existir um questionário vinculado a atividade do ticket). Preencher os dados referentes a execução da solicitação e clicar em "**Salvar**".
4. Se desejar adicionar algum arquivo clicar na aba "**Anexos**";
5. Se desejar adicionar alguma nota, clicar na aba "**Notas**". Relatar a ocorrência referente ao ticket e a data que a mesma ocorreu. É possível também registrar o tempo gasto para a solução da ocorrência. É disponibilizado a visualização deste relato pelo solicitante e o envio do mesmo para o e-mail dele ao selecionar as opções "**Visível ao solicitante**" e "**Enviar ao e-mail**". Clicar em "**Salvar**".
6. Clicar em "**Finalizar**" e completar os dados sobre a conclusão do atendimento. Selecionar a situação do atendimento (em andamento, resolvida ou cancelada) e o detalhar da mesma;
7. Clicar em "**Coletar Assinatura e Avançar o Fluxo**" (ver documento relacionado) ou "**Gravar e manter tarefa atual**" para
   completar a operação. Serão então automaticamente sincronizadas as alterações. Se o aplicativo não encontrar a rede para completar a sincronização, será apresentado o ícone “**Atualização automática**” para aguardar o encontro de rede para e então completar a sincronização;
8. Está disponível a sincronização manual das solicitações assim que o aplicativo encontrar uma rede acessível. Para tanto, basta deslizar a tela para baixo com o dedo ou clicar no ícone “**Atualizar lista**”;
9. Existem filtros que facilitam a localização do ticket necessário, acesse o mesmo pela caixa de pesquisa ou clique no ícone “**Filtros**”.


[title] Parametrização - Conhecimento
[path] Administração da Plataforma/Untitled/

O sistema de gerenciamento de conhecimento de serviço inclui ferramentas para coletar, armazenar, gerenciar, atualizar, analisar e apresentar todos os conhecimentos, informações e dados que um provedor de serviço de TI precisa para gerenciar o ciclo de vida completo dos serviços de TI.

A parametrização de "Conhecimento" deve ser realizada para permitir a execução/uso deste processo, podendo ser possível, definir a pasta para armazenamento do conhecimento criado a partir de eventos, definir o diretório para armazenar a descrição da resposta da solicitação de serviço/incidente para ser gravada na base de conhecimento, dentre outras ações.

## Procedimento

1. Acessar a funcionalidade através da navegação no menu principal `Parametrização > Gerência de conhecimento;`
2. Definir os valores dos parâmetros (atributos);
3. Clicar no botão "**Gravar**" para efetuar a operação;
4. A lista abaixo apresenta os parâmetros do "**Conhecimento**" e a finalidade de cada um deles:

| #   | Nome                                                                                                                                                        | Valores possíveis                                                                             | Finalidade                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Orientações complementares                                                                                                                                                                                                                                             |
| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 78  | Avisar, com antecedência, a quantidade de dias que restam para a expiração do conhecimento. (Default: 90 dias)                                              | Default: 90 dias                                                                              | Definir com quantos dias de antecedência da data de expiração do conhecimento, o autor e aprovador serão notificados. Na criação de um conhecimento na tela “Base de Conhecimento”, deve ser informada a data de expiração, ou seja, a data em que o conhecimento irá expirar. Será notificado ao autor e aprovador do conhecimento, com antecedência de N dias (definido neste parâmetro) da data de expiração do conhecimento.                                                                                                                                               | Não se aplica                                                                                                                                                                                                                                                          |
| 79  | ID do modelo de e-mail para envio de notificação de criação de pasta                                                                                        |                                                                                               | Informar o número de identificação (ID) do modelo de e-mail de notificação de criação de pasta. Ao criar uma pasta na tela de “Cadastro de Pasta”, será utilizado para o envio da notificação de criação da pasta o modelo de e-mail definido neste parâmetro. Essa notificação será enviada para o grupo e/ou usuário associado à pasta. Esse ID do modelo de e-mail é definido na tela de “Modelo de E-mail”.                                                                                                                                                                | Caso não informe o número de identificação (ID) do modelo de e-mail, há possiblidade de não enviar o e-mail correto.                                                                                                                                                   |
| 80  | ID do modelo de e-mail para envio de notificação de atualização de pasta                                                                                    |                                                                                               | Informar o número de identificação (ID) do modelo de e-mail de notificação de atualização de pasta. Ao alterar uma pasta na tela de “Cadastro de Pasta”, será utilizado para o envio da notificação de atualização da pasta o modelo de e-mail definido neste parâmetro. Essa notificação será enviada para o grupo e/ou usuário associado à pasta. Esse ID do modelo de e-mail é definido na tela de “Modelo de E-mail”.                                                                                                                                                      | Caso não informe o número de identificação (ID) do modelo de e-mail, há possiblidade de não enviar o e-mail correto.                                                                                                                                                   |
| 81  | ID do modelo de e-mail para envio de notificação de exclusão de pasta                                                                                       |                                                                                               | Informar o número de identificação (ID) do modelo de e-mail de notificação de exclusão de pasta. Ao excluir uma pasta na tela de “Cadastro de Pasta”, será utilizado para o envio da notificação de exclusão da pasta o modelo de e-mail definido neste parâmetro. Essa notificação será enviada para o grupo e/ou usuário associado à pasta. Esse ID do modelo de e-mail é definido na tela de “Modelo de E-mail”.                                                                                                                                                            | Caso não informe o número de identificação (ID) do Modelo de E-mail, há possiblidade de não enviar o e-mail correto.                                                                                                                                                   |
| 82  | ID do modelo de e-mail para envio de notificação de criação de conhecimento                                                                                 | Ex: 11                                                                                        | Informar o número de identificação (ID) do Modelo de E-mail de notificação de criação de conhecimento. Ao cadastrar um conhecimento na tela de “Base de Conhecimento”, será utilizado para o envio da notificação de criação do conhecimento o modelo de e-mail definido neste parâmetro. Essa notificação será enviada para o grupo e/ou usuário associado à base de conhecimento. Esse ID do modelo de e-mail é cadastrado na tela de “Modelo de E-mail”.                                                                                                                    | Caso não informe o número de identificação (ID) do modelo de e-mail, há possiblidade de não enviar o e-mail correto.                                                                                                                                                   |
| 83  | ID do modelo de e-mail para envio de notificação de atualização de conhecimento                                                                             | Ex: 12                                                                                        | Informar o número de identificação (ID) do modelo de e-mail de notificação de atualização de conhecimento. Ao atualizar um conhecimento na tela de “Base de Conhecimento”, será utilizado para o envio da notificação de atualização do conhecimento o modelo de e-mail definido neste parâmetro. Essa notificação será enviada para o grupo e/ou usuário associado à base de conhecimento. Esse ID do modelo de e-mail é definido na tela de “Modelo de E-mail”.                                                                                                              | Caso não informe o número de identificação r (ID) do modelo de e-mail, há possiblidade de não enviar o e-mail correto.                                                                                                                                                 |
| 84  | ID do modelo de e-mail para envio de notificação de exclusão de conhecimento                                                                                | Ex: 13                                                                                        | Informar o número de identificação (ID) do modelo de e-mail de notificação de exclusão de conhecimento. Ao excluir um conhecimento na tela de “Base de Conhecimento”, será utilizado para o envio da notificação de exclusão do conhecimento o modelo de e-mail definido neste parâmetro. Essa notificação será enviada para o grupo e/ou usuário associado à base de conhecimento. Esse ID do modelo de e-mail é definido na tela de “Modelo de E-mail”.                                                                                                                      | Caso não informe o número de identificação (ID) do modelo de e-mail, há possiblidade de não enviar o e-mail correto.                                                                                                                                                   |
| 182 | Pasta para ser salvo a Descrição e a solução da solicitação de serviço na Base de Conhecimento. (Ex: Windows - Descrição\_Resposta\_Para\_BaseConhecimento) | Ex: Windows: C:\Citsmart\BaseConhecimento                                                     | Definir o diretório para armazenar a descrição da resposta da solicitação de serviço/incidente para ser gravada na base de conhecimento. Na tela de Solicitação de Serviço/Incidente é apresentada o campo “Gravar Solução/Resposta na Base de Conhecimento”. Ao atender uma solicitação de serviço/incidente e caso queira gravar a descrição da Solução Resposta na base conhecimento, basta selecionar o campo e informar o título, feito isso, ao gravar e avançar o fluxo, a descrição da solução resposta da solicitação será armazenada na pasta definida no parâmetro. | Não se aplica                                                                                                                                                                                                                                                          |
| 273 | Pasta padrão para os conhecimentos criados a partir de ocorrências de eventos                                                                               |                                                                                               | Definir a pasta para armazenamento do conhecimento criado a partir das ocorrências de eventos                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Não se aplica                                                                                                                                                                                                                                                          |
| 304 | URL do servidor do SOLR (Ex: [http://localhost:8983/solr/collection\_name](http://localhost:8983/solr/collection_name))                                     | Ex: [http://localhost:8983/solr/collection\_name](http://localhost:8983/solr/collection_name) | Configurar a URL da coleção do Apache Solr que será usada pelo CITSmart para indexar os conhecimentos                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Não se aplica                                                                                                                                                                                                                                                          |
| 305 | URL do servidor do Apache Tika (Ex: [http://localhost:9998/tika](http://localhost:9998/tika))                                                               | Ex: [http://localhost:9998/tika](http://localhost:9998/tika)                                  | Configurar a URL do Apache Tika para fazer OCR dos anexos do conhecimento no momento da indexação                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Não se aplica                                                                                                                                                                                                                                                          |
| 308 | Total de itens a serem importados por vez ao indexar documentos no Solr (Ex: 1000)                                                                          | Ex: 1.000                                                                                     | Configurar a quantidade de itens que serão indexados por vez no Apache Solr                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Não se aplica                                                                                                                                                                                                                                                          |
| 313 | Id da Pasta para cadastrar Conhecimentos criados pelo usuário final                                                                                         |                                                                                               | Pasta default para cadastrar Conhecimentos criados pelo usuário final                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Não se aplica                                                                                                                                                                                                                                                          |
| 314 | Id da origem dos Conhecimentos criados pelo usuário final                                                                                                   |                                                                                               | Origem default que será usado nos conhecimentos criados pelo usuário final                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Não se aplica                                                                                                                                                                                                                                                          |
| 332 | Ativar sincronização com o servidor de indexação                                                                                                            | S ou N                                                                                        | Quando é realizado uma indexação de conhecimento no Solr, seja por exclusão, atualização ou criação de um novo conhecimento. Se o Solr estiver parado e este parâmetro estiver ativo, é iniciado uma sincronização automática com o Solr até que este seja ativo novamente. Assim que ele voltar a funcionar todos os conhecimentos que estão pendentes de indexação são indexados e a sincronização automática é finalizada.                                                                                                                                                  | Não se aplica                                                                                                                                                                                                                                                          |
| 333 | Informe o intervalo em minutos para sincronizar os conhecimentos com o servidor de indexação                                                                | Entre 0 e 59 minutos. Default é vazio.                                                        | Define o tempo em minutos que um conhecimento ficará em revisão.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Para saber a quantidade máxima que deve ser colocada no parâmetro, conforme o seu tipo, deve-se verificar [neste endereço](http://www.quartz-scheduler.org/documentation/quartz-2.3.0/tutorials/crontrigger.html), na parte de "Format", a coluna de "Allowed Values". |
| 354 | URL da logo (Portal do conhecimento) (Ex:./citsmart/imagens/logo/logo-header-icon.png)                                                                      | Ex: /citsmart/imagens/logo/logo-header-icon.png                                               | Parâmetro de uso restrito à CITSmart Corporation, indica a URL da logo do Portal do conhecimento.                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Não se aplica                                                                                                                                                                                                                                                          |
| 355 | URL do fundo do cabeçalho (Portal do conhecimento)(Ex.:/citsmart/imagens/background-header.png)                                                             | Ex.:/Citsmart/imagens/background-header.png                                                   | Parâmetro que personaliza a aparência do Portal do Conhecimento.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Não se aplica                                                                                                                                                                                                                                                          |
| 356 | Cor de fundo do cabeçalho (Portal do Conhecimento)(Default::#e6e6e6)                                                                                        | Ex: #e6e6e6                                                                                   | Parâmetro que personaliza a aparência do Portal do Conhecimento.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Não se aplica                                                                                                                                                                                                                                                          |
| 357 | Cor de fonte do cabeçalho (Portal do conhecimento) (Default : #333333)                                                                                      | Ex: #333333                                                                                   | Parâmetro que personaliza a aparência do Portal do Conhecimento.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Não se aplica                                                                                                                                                                                                                                                          |
| 358 | Habilitar ranking de pesquisas da base de conhecimento (Ex: S ou N - Default 'N')                                                                           | S ou N                                                                                        | A não configuração desta informação, ou a atribuição de "N" impede a criação de relatórios gerenciais que tratam do assunto.                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Não se aplica                                                                                                                                                                                                                                                          |
| 359 | Armazenar registros de pesquisas por quantos dias? (Ex: 30)                                                                                                 | Ex: 30                                                                                        | A não configuração deste limitador pode acumular quantidade excessiva de dados desnecessariamente ao longo do tempo causando lentidões no processamento da aplicação, principalmente em relatórios que tratarem do assunto.                                                                                                                                                                                                                                                                                                                                                    | Não se aplica                                                                                                                                                                                                                                                          |
| 360 | Cor da fonte dos favoritos (Portal do Conhecimento) (Default : #f1a21f)                                                                                     | Ex.: #f1a21f                                                                                  | Personalizar a aparência do quadro "Favoritos" que fica na tela inicial tanto do Portal do Conhecimento quanto do Guia do Usuário.                                                                                                                                                                                                                                                                                                                                                                                                                                             | Não se aplica                                                                                                                                                                                                                                                          |
| 361 | Cor da fonte dos curtidos (Portal do Conhecimento) (Default : #6c8ebe)                                                                                      | Ex.: #6c8ebe                                                                                  | Personalizar a aparência do quadro "Curtidos" que fica na tela inicial tanto do Portal do Conhecimento quanto do Guia do Usuário.                                                                                                                                                                                                                                                                                                                                                                                                                                              | Não se aplica                                                                                                                                                                                                                                                          |
| 362 | Cor da fonte dos indicados (Portal do Conhecimento) (Default : #67c15e)                                                                                     | Ex.: #67c15e                                                                                  | Personalizar a aparência do quadro "Indicados" que fica na tela inicial do Portal do Conhecimento.                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Não se aplica                                                                                                                                                                                                                                                          |
| 363 | URL do Help (Ex: [https://help..citsmartcloud.com/citsmart](https://help..citsmartcloud.com/citsmart))                                                      | Ex: [https://help..citsmartcloud.com/citsmart](https://help..citsmartcloud.com/citsmart)      | O parâmetro é usado para informar a URL do Guia do Usuário                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Não se aplica                                                                                                                                                                                                                                                          |
| 364 | URL da logo (Guia do usuário) (Ex.: /citsmart/imagens/logo/logo-header-icon.png)                                                                            | Ex.: /citsmart/imagens/background-header.png                                                  | Parâmetro de uso restrito à CITSmart Corporation, indica a URL da logo do Guia do Usuário.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Não se aplica                                                                                                                                                                                                                                                          |
| 365 | URL do fundo do cabeçalho (Guia do usuário) (Ex.: /citsmart/imagens/background-header.png)                                                                  | Ex.: /citsmart/imagens/background-header.png                                                  | Parâmetro de uso restrito à CITSmart Corporation, indica a URL da imagem de fundo do Guia do Usuário.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Não se aplica                                                                                                                                                                                                                                                          |
| 366 | Cor do fundo do cabeçalho (Guia do usuário) (Default : #e6e6e6)                                                                                             | Ex.: #e6e6e6                                                                                  | Parâmetro de uso restrito à CITSmart Corporation, personaliza a aparência do Guia do Usuário.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Não se aplica                                                                                                                                                                                                                                                          |
| 367 | Cor da fonte do cabeçalho (Guia do usuário) (Default : #333333)                                                                                             | Ex.: #333333                                                                                  | Parâmetro de uso restrito à CITSmart Corporation, personaliza a aparência do Guia do Usuário.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Não se aplica                                                                                                                                                                                                                                                          |
| 368 | URL para login do parceiro (Ex.: [https://example.com/citsmart](https://example.com/citsmart))                                                              | Ex.: [https://example.com/citsmart](https://example.com/citsmart)                             | Parâmetro de uso restrito à CITSmart Corporation, personaliza o link para onde é direcionada a solução quando clicar em "Sou Agente" no Guia do Usuário.                                                                                                                                                                                                                                                                                                                                                                                                                       | Não se aplica                                                                                                                                                                                                                                                          |
| 410 | Exibir título da tela de Portal do Conhecimento (Default: S)                                                                                                |                                                                                               | Informa se é para apresentar o título do conhecimento na tela de Pesquisa de Base de Conhecimento                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Não se aplica                                                                                                                                                                                                                                                          |

Tabela 1 - Lista de parâmetros


[title] Tenant (Espaço de Cliente)
[path] Administração da Plataforma/

"**Tenant**" é um espaço do cliente dentro do cluster que indicou. É aonde o cliente tem acesso e visualiza as aplicações que adquiriu.

É possível criar diversas aplicações e portais customizados que podem ter urls diferentes para acesso de pessoas distintas, centrais de atendimento separadas, tudo em um único local de configuração.

Na tela de configuração do Tenant, existem vários campos que representam informações importantes:

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/7mECFpS4YiRq5I7_1yCPV_image.png "Tela de Cadastro de Tenant")

:::hint{type="info"}
✏️ ***Nota:***** **Cada tenant poderá ter um URL e visões diferentes customizados, independentes um do outro.
:::

### Cadastros Tenant

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/ZicVS4GRKqBoK7PxCMIBs_image.png "Relacionamento dos dados Tenant")

Para o entendimento correto da organização das informações da plataforma, **confira o sinônimo de termos abaixo:**

- cluster\_space\_client = Tenant
- platform\_application = Aplicação
- platform\_application\_version = Versão (da aplicação)
- client\_category = Categoria do cliente

Analisando a imagem acima:

1. Identificamos que o tenant é vinculado a um cliente. E um tenant tem licenciamento de versões de aplicações;
2. Um cluster processa vários tenants;
3. Um cliente pode ter vários tenants;
4. Licença é um elemento importante, pois somente através dele os usuários daquele tenant terão acesso a determinada aplicação (na verdade uma versão especifica da aplicação).


[title] Cadastrar ação automática
[path] Administração da Plataforma/Automatização /

As ações automáticas são associadas no cadastro de gerentes de eventos. Estas ações serão relacionadas de acordo com o tipo do evento desejado e disparadas sempre que for reconhecido um evento significativo.

Esta funcionalidade disponibiliza ações diversas, tais como, incluir, alterar e excluir ações automáticas.

## Procedimento

1. Acessar a funcionalidade através da navegação no menu principal `Sistema > Ações Automáticas > Ações Automáticas;`
2. Preencher o campo disponibilizado;
3. Clicar em "**Gravar**".


[title] Cadastrar domínio
[path] Administração da Plataforma/Untitled/

A funcionalidade de Domínio tem por objetivo permitir o cadastro de domínios, ou seja, novas opções no campo de uma determinada tela do sistema. Para utilizar a mesma, é preciso ter conhecimento sobre a codificação do sistema.

Esta funcionalidade disponibiliza ações diversas, tais como, incluir, alterar e excluir o domínio.

## Procedimento

1. Acessar o menu principal `Sistema > Domínios > Domínios;`
2. Clicar no botão "**Novo**";
3. Preencher os campos disponibilizados;
4. Clicar em "**Gravar**".


[title] Verificar o histórico de atendimento
[path] Administração da Plataforma/Mobile/

Esta funcionalidade tem por objetivo verificar o histórico de atendimento das solicitações de serviços feito pelos técnicos de campo.

Nesta tela, poderá visualizar o histórico de atendimento de solicitação de serviço feito pelos técnicos de campo, de acordo com os filtros informados.

## Antes de começar

- [x] Para verificar o histórico de atendimento é necessário, anteriormente, configurar a conexão do sistema com as API's do Google.

## Procedimento

1. Acessar a funcionalidade através da navegação no menu principal `Gestão Integrada > Gerência de Força de Atendimento > Histórico de Atendimento;`
2. Definir os filtros de acordo com a necessidade. Lembrar que ao selecionar o técnico, serão apresentadas as solicitações de serviços que o mesmo atendeu e que faz referência aos contratos que ele pertence;
3. Após os filtros definidos, clicar no botão "**Pesquisar**". Será exibido no mapa o histórico de atendimento das solicitações de serviço pelo técnico de campo.


[title] Licenças de Aplicações/Versões
[path] Administração da Plataforma/

A **Licença **é uma permissão de uso de uma versão de aplicação para um determinado tenant.

:::hint{type="warning"}
📌 ***IMPORTANTE*****! **

Os usuários só terão acesso a uma aplicação se houver licença vinculada para o tenant e aplicação. Portanto, a **licença **determina em qual versão um ou outro tenant está.
:::

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/1h9suaopqQ3QTPlrdU_cE_image.png)

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/7WtcNkc22VFptuLFCCVoD_image.png)


[title] Cliente
[path] Administração da Plataforma/

O **Cliente** representa uma empresa ou qualquer instituição que seja cliente da plataforma. Nesse sentido, um cliente pode comprar **1** ou **vários tenants**.

Esse cliente também pode comprar tenants que ficam no mesmo cluster ou em cluster diferentes (espalhados pelo mundo - caso a empresa seja global).

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/uEBLXSVxjO0De4UUMqpEq_image.png)


[title] Gestão de Pessoas - CITSMART
[path] Administração da Plataforma/

## **Objetivo**

O objetivo deste documento é detalhar a utilização da aplicação "Gestão de Pessoas", disponível na ferramenta ITSM Citsmart, destacando suas funcionalidades e procedimentos, incluindo a gestão de usuários, alteração, cadastro e administração de grupos, além da definição e atribuição de roles. Seu propósito é fornecer uma visão clara do uso da aplicação, garantindo a correta configuração e manutenção dos acessos.

**PROCEDIMENTO PARA EXECUÇÃO**

## **Acessar o Citsmart**

Após acessar a ferramenta CITSmart, utilize o menu de navegação vertical à esquerda. Selecione a opção “Gestão de Pessoas”

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/PoNh9khOO1qpazJfeEI_P_imagem.png" signedSrc size="30" width="273" height="392" position="center" caption}

## **Meu perfil**

Ao selecionar a opção "Meu perfil", os dados básicos são preenchidos automaticamente. Caso deseje, você pode informar CPF, data de nascimento, telefone e endereço para completar seu cadastro na ferramenta Citsmart.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/WTFzTf1-KhKyHoHYjEp2y_imagem.png" signedSrc size="36" width="255" height="148" position="center" caption}



![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/-LWDi220CmFltCfuGNOGl_imagem.png)

## **Roles**

Na ferramenta Citsmart, **roles** (ou papéis) representam conjuntos de permissões que definem o que um usuário pode visualizar e executar no sistema. Cada role está associada a um nível de acesso específico, permitindo a configuração de responsabilidades e restrições conforme a necessidade da organização.

Para acessar a funcionalidade, selecione a aplicação de Gestão de Pessoas no menu de aplicações, depois clique em “Roles”.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/VXbvKy4j69nUpD_rM5MwK_imagem.png" signedSrc size="44" width="409" height="276" position="center" caption}

Nesta tela, são apresentados os roles existentes na ferramenta Citsmart. Para criar um novo role, utilize o botão “Criar” localizado no lado direito da tela. Para excluir um role, utilize o botão disponível para cada role existente.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/M9EiUJOVjgKavtHREMBXJ_imagem.png)

## **Grupos**

Cada grupo possui permissões de acesso específicas, determinando as funcionalidades disponíveis para cada usuário.

Para acessar a funcionalidade, selecione a aplicação de Gestão de Pessoas no menu de aplicações, depois clique em “Grupos”.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/FsSAVRu1lZgneaD9Y-l4Z_imagem.png" signedSrc size="40" width="355" height="325" position="center" caption}

Nesta tela, são apresentados os grupos existentes na ferramenta Citsmart. Para criar um novo grupo, utilize o botão “Criar” localizado no lado direito da tela. Para editar ou excluir um grupo, utilize os botões disponíveis para cada grupo.

No topo da lista, são exibidos botões que permitem copiar a lista para a área de transferência, ou exportar a lista em formato CSV, XLSX ou PDF.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/OgenYXj2b7b9tRX5QSC7s_imagem.png)

## **Usuários**

A página de Usuários exibe uma lista com os usuários do sistema, e permite a criação de novos usuários.

Os usuários são as pessoas que utilizam o sistema, tanto para abrir quanto para atender chamados. Para que as funcionalidades de atendimento e solicitação de tickets funcionem corretamente, é necessário a criação de usuários, e a atribuição de grupos e papéis para cada usuário. Os grupos e papéis definem se o usuário é um cliente, atendente ou administrador, e cada grupo e papel possui permissões de acesso diferentes.

Para acessar a funcionalidade, selecione a aplicação de Gestão de Pessoas no menu de aplicações, depois clique em “Usuários”.



::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/b4bWeVquDxlFwJXWcV996_imagem.png" signedSrc size="46" width="338" height="399" position="center" caption}

A tela de Usuários exibe algumas métricas sobre os usuários cadastrados na plataforma, bem como uma lista. Os cards no topo da tela exibem o número total de Grupos, Roles e Usuários cadastrados no sistema.

Acima dos cards, no lado direito da tela, são exibidos os botões para **Criar novo Usuário** e Cadastrar novos usuários em massa.

Abaixo dos cards, ao centro da tela, é exibida uma lista com todos os usuários e algumas informações divididas em colunas.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/sP3-hjPd31Vw914ZmcoIv_imagem.png)

No topo da lista, do lado direito são exibidos os campos para **Pesquisar **na lista de usuários, **Limpar **a busca realizada, e **Exportar Usuários**.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/uBcr6KqgqtRWYxXqsg074_imagem.png" signedSrc size="50" width="318" height="102" position="center" caption}

As colunas da lista de usuários exibem algumas informações sobre cada usuário:

- **Nome: **Nome e sobrenome do usuário.
- **Usuário: **Login do usuário.
- **Email: **Endereço de email do usuário.
- **Status: **Ativo ou Inativo
- **Sessão:**
- **Última modificação: **Data da última modificação das informações do usuário.
- **Ações: **Botões para **Editar **as informações ou** Excluir **usuário.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/qnX5eNe_uoLw5GO3MO_d5_imagem.png)

Se houverem muitos usuários cadastrados, a visualização será dividida em páginas. Utilize as setas no fim da página para navegar entre as páginas.

## **Criar novo Usuário**

Para criar um novo usuário, acesse a página de “Usuários” e clique no botão “+Usuário” para criar um usuário único, ou “+Usuários em Lote” para cadastrar vários usuários ao mesmo tempo.



::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/JanqGD1wfg1PBoJtqueme_imagem.png" signedSrc size="52" width="362" height="99" position="center" caption}

- **+Usuário: **O botão de “**+Usuário**” exibe uma tela com as informações do usuário a ser criado:

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/ERoqf9eO1pwwE_agLjt33_imagem.png)

Inclua as informações de identificação de Nome e Sobrenome, o Email e o nome de Usuário. O nome de usuário será usado para acessar a plataforma, e o email será o principal ponto de contato externo com o usuário.

Ao centro, selecione na caixa o tipo de sessão do usuário: Permanente, Concorrente, Administrador e Ilimitado. O tipo de sessão influencia no tipo de acesso que o usuário terá ao sistema.

Na parte de baixo, marque a caixa de Ativo para ativar o usuário.

**A caixa de Senha “Padrão?”,** quando marcada, cria o acesso usando a senha padrão do sistema, exibida ao lado. Ao realizar o acesso pela primeira vez, será requisitado ao usuário que escolha uma nova senha. Marcar esta caixa automaticamente desabilita a opção de senha temporária.

:::hint{type="warning"}
**A senha padrão será sempre Mudar-123**
:::



**A caixa de Senha temporária?** permite que uma senha padrão personalizada seja definida no campo ao lado. Ao realizar o acesso pela primeira vez, será requisitado ao usuário que escolha uma nova senha. Este campo só pode ser alterado caso a opção de Senha padrão esteja desabilitada.

Após incluir as informações desejadas, selecione Cadastrar para criar o novo usuário ou Fechar para cancelar e voltar para a tela anterior.

- **+Usuários em lote: **Na lista de usuários, o botão de “**+Usuários em lote” **permite que uma lista de usuários seja importada para o cadastro de múltiplos usuários.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/MkIUEyMJKHpOEuXJ__VBV_imagem.png)

A tela exibida define o modelo usado para importar usuários. É necessário fazer o upload de uma lista no formato **CSV **seguindo o padrão exibido. É possível baixar um arquivo de exemplo ao clicar no botão “**Baixar Modelo” **abaixo da caixa.

As observações definem alguns parâmetros que devem ser seguidos ao fazer o upload da lista.

Abaixo das observações, clique no botão para navegar em sua máquina e selecionar um arquivo compatível para o upload.

Após selecionar um arquivo, a lista abaixo será atualizada com os novos usuários.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/inJ4QDGZmnmC_MI4oFZLz_imagem.png)

Para concluir a criação, clique em “**Importar Usuários” **ao lado direito.


[title] Cluster
[path] Administração da Plataforma/

Um **Cluster **representa um nó da plataforma que se encontra hospedado em um determinado local.

> ***Exemplo***
>
> **: **
>
> Podemos ter tanto um cluster em São Paulo (rodando dentro da 
>
> *Oracle Cloud*
>
> ) como um outro cluster em Nova York (rodando dentro da AWS - 
>
> *Amazon Web Services*
>
> ). 

Esses clusters são configurados conforme a necessidade do cliente (negociado com o fabricante) ou fabricante.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/LIwHOB0_K6MVzu02dzukg_image.png)


[title] Cadastrar modelo de planilha para importação de portfólio de serviços
[path] Administração da Plataforma/Untitled/

O objetivo desta funcionalidade é otimizar a criação de vários serviços e consequentemente de suas atividades dentro de um ou mais portfólios de serviços.

:::hint{type="info"}
**Nota:** Ao gerar as planilhas independente do formato, o usuário encontrará campos com hiperlink. Esses campos recuperam a referência do enumerado com a descrição do campo. Nesses casos o usuário utilizará o enumerado para preenchimento correto da lista.
:::

## Antes de começar

- [x] Para realizar o carregamento de portfólio de serviços é preciso registrar previamente o tipo de serviço e a categoria de serviço.

## Procedimento

1. Acessar a funcionalidade através da navegação no menu principal `Sistema > Importação e Carga de Dados > Carga do Portfólio de Serviços;`
2. Para cadastrar um modelo de planilha para importação, clicar na guia **Modelo de planilha para importação**;
3. O cadastro de planilha para importação está estruturado conforme o passo a passo para se criar um portfólio de serviços com as etapas Portfólio, Serviço e Atividade (Incidente/Requisição);
4. Para gerar modelo de planilha em formato ".xls", clicar no botão "Gerar Modelo .xls";
5. Para gerar modelo de planilha em formato ".xlsx", clicar no botão "Gerar Modelo .xlsx".


[title] Dados e Importação
[path] Administração da Plataforma/

É possível importar um intervalo de dados para o CITSmart Platform.

Isso pode ajudar no processo de configuração de ferramentas ou no projeto de processos.


[title] Cadastrar localidade
[path] Administração da Plataforma/Untitled/

Esta funcionalidade disponibiliza ações diversas, tais como, incluir, alterar e excluir os locais em que os solicitantes de serviços estão alocados, podendo ser o nome da unidade, cidade, nome do órgão etc.

## Procedimento

1. Acessar a funcionalidade através da navegação no menu principal `Cadastros Gerais > Gerência de Pessoal > Localidade;`
2. Preencher o campo disponibilizado;
3. Clicar em "**Gravar**".


[title] Carregar metadados
[path] Administração da Plataforma/Untitled/

Esta funcionalidade tem o objetivo de carregar as informações de tabelas do banco de dados.

## Procedimento

1. Acessar a funcionalidade através da navegação no menu principal `Sistema > Visões e Meta dados > Carrega Metadados;`
2. Informar o nome da tabela ou para exibir a lista completa de todas, clicar no botão "**Carregar**".


[title] Customizar o Portal do Conhecimento
[path] Administração da Plataforma/Untitled/

Esta funcionalidade tem por objetivo alterar imagens que estão no Portal do Conhecimento.

## Procedimento

1. Acessar a funcionalidade através do menu principal `Sistema > Configurações > Portal do Conhecimento > Customizar;`
2. Escolher um o(s) item(ns) que será(ão) modificado/customizado(s);
3. Clicar em "**Gravar**".


[title] Gerenciar importação dados
[path] Administração da Plataforma/Untitled/

Esta funcionalidade tem por objetivo realizar a importação de dados.

## Procedimento

1. Acessar a funcionalidade através da navegação no menu principal `Sistema > Gerência de Importação;`
2. Preencher os campos disponibilizados;
3. Para execução da importação de dados clicar no botão "**Executar**";
4. Clicar no botão "**Gravar**".


[title] Categoria de Cliente
[path] Administração da Plataforma/

A **Categoria de cliente** é uma forma de categorização do cliente.

> ***Exemplo***
>
> **:**
>
>  Cliente do segmento de TI, Bancário, Indústria, ou qualquer outro segmento.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/_ih-b1baaeROxJHKGBbdv_image.png)


[title] Configurar Modelo de E-mail
[path] Administração da Plataforma/Untitled/

Esta funcionalidade tem por objetivo criar modelos de e-mail para notificações do sistema.

Um conhecimento permite a anexação de imagens, links, entre outros recursos visuais, tornando assim o compartilhamento de e-mails mais interativo.

## Procedimento

1. Acessar a funcionalidade através da navegação no menu principal` Sistema > Configurações > Modelo de E-mail;`
2. Preencher os campos cadastrais disponibilizados;
3. Clicar em "**Gravar**".


[title] Mobile
[path] Administração da Plataforma/

A funcionalidade Mobile foi desenvolvida para permitir maior autonomia no gerenciamento de serviços, pois permite a provisão de serviços em diferentes perspectivas, seja como portal de atendimento ao usuário final, seja como instância flexível para o analista realizar o serviço de campo.

Os produtos gerados são compatíveis com dispositivos móveis, com layout responsivo que se adapta automaticamente ao tamanho da tela, garantindo usabilidade e consistência em diferentes formatos de dispositivo.


[title] Escalonamento
[path] Administração da Plataforma/Automatização /Cadastrar ação automática/

Esta funcionalidade tem por objetivo a ação de agendamento. Ela será o complemento para se criar uma regra de escalonamento.

Esta funcionalidade disponibiliza ações diversas, tais como, incluir, alterar e excluir ação automática de escalonamento.

## Procedimento

1. Para ter acesso clicar no menu principal `Sistema > Ações automáticas > Ações de escalonamento;`
2. Clicar no botão "**Novo**";
3. Preencher os campos disponibilizados;
4. Clicar em "**Gravar**".


[title] E-mail
[path] Administração da Plataforma/Automatização /Cadastrar ação automática/

A finalidade desta funcionalidade é programar a abertura automática de solicitações de serviço via e-mail.

Esta funcionalidade disponibiliza ações diversas, tais como, incluir, alterar e excluir ação automática via e-mail.

## Antes de começar

- [x] A criação automática via e-mail requer o registro prévio da ação automática de incidentes/requisições/procedimentos.

## Procedimento

1. Acessar a funcionalidade através da navegação no menu principal `Sistema > Configurações > Configuração de ação automática via e-mail;`
2. Preencher os campos disponibilizados;
3. Clicar no botão "**Gravar**".


[title] Configurar filtros do Portal do Conhecimento
[path] Administração da Plataforma/Untitled/

Esta funcionalidade tem por objetivo configurar os filtros que irão aparecer habilitados para pesquisa de um conhecimento no Portal do Conhecimento.

## Procedimento

1. Acessar a funcionalidade através da navegação no menu principal `Sistema > Configurações > Portal do Conhecimento > Configuração de Filtros do Portal do Conhecimento;`
2. Selecionar os filtros e a ordem que se deseja apresentar no Portal do Conhecimento;
3. Clicar no botão "**Gravar**".


[title] Cadastrar tipo de unidade
[path] Administração da Plataforma/Untitled/

Esta funcionalidade disponibiliza ações diversas, tais como, incluir, alterar e excluir os tipos de unidade.

## Procedimento

1. Acessar a funcionalidade através da navegação no menu principal `Cadastros Gerais > Gerência de Pessoal > Tipo de Unidade;`
2. Preencher o campo disponibilizado;
3. Clicar em "**Gravar**". 


[title] Carregar países
[path] Administração da Plataforma/Untitled/

O objetivo é realizar a carga de países nas telas de Fornecedor e Unidade.

## Procedimento

1. Acessar a funcionalidade através da navegação no menu principal `Sistema > Banco de Dados > Carga Países;`
2. Selecionar um país;
3. Clicar em "**Carregar**".


[title] Recursos do Tenant
[path] Administração da Plataforma/

Os **Tenants** representam espaços do cliente dentro da plataforma. É possível que uma mesma organização tenha diversos Tenants distintos, com seu próprio conjunto de grupos (multitenant). Entretanto, os **Recursos** representam informações e elementos que os Tenants fazem uso. Ou seja, pode-se ter diversos ambientes de usuários separados até por urls diferentes, com acessos, permissões, visões e regras de negócios distintos, ou diversos tenants com urls distintas acessando as mesmas regras de negócios, usuários e base de dados.Tudo sendo orquestrado em um único local.

Desse modo, os recursos podem representar: `Banco de dados, Sistema de Arquivos, entre outros`.&#x20;

:::hint{type="info"}
✏️ ***Nota:***** **Os grupos e itens de configuração também serão segregados.
:::

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/ZiV0_7x23xkYioFp8hjxS_image.png "Tela de Cadastro de Recursos")

:::hint{type="info"}
🖊 ***Nota*****: **É necessário informar somente os dados do recurso, bem como a qual tenant o recurso será vinculado. Caso o recurso tenha campos, é necessário infomá-los.
:::

***

> ***Exemplo***
>
> **:**
>
>
> Caso esteja configurando um recurso de Banco de dados, os campos com as informações da URL do servidor, bem como senha devem ser informados.
>
> A aplicação fará a leitura de todos os recursos configurados para aquele tenant e adaptará seu funcionamento conforme estes recursos.

## Ambientes de Trabalho: Desenvolvimento, Homologação e Produção

A plataforma é capaz de provisionar e licenciar múltiplos ambientes de trabalho, permitindo a separação adequada das etapas de desenvolvimento, validação e operação em produção. Essa separação garante controle de qualidade, segurança operacional e rastreabilidade, além de atender às boas práticas de ciclo de vida de sistemas.

Estão previstos, no mínimo, os seguintes ambientes:

Ambiente de Desenvolvimento: voltado à construção, parametrização, testes técnicos e validação inicial de funcionalidades por equipes técnicas ou squads de desenvolvimento;

Ambiente de Homologação: utilizado para validação funcional por usuários-chave ou áreas de negócio, onde são realizados testes de aceitação e verificação antes da liberação para produção;

Ambiente de Produção: ambiente definitivo de operação da plataforma, utilizado por usuários finais e com controle completo de disponibilidade, performance, segurança e integridade dos dados.

## Portabilidade de Dados entre Ambientes

A plataforma oferece mecanismos que permitem mover dados do ambiente de produção para outras bases ou ambientes da aplicação, de forma segura, controlada e auditável. Essa funcionalidade é essencial para atividades como testes, análises, validações, treinamentos e simulações baseadas em dados reais.

Os principais objetivos dessa capacidade incluem:

Replicação de dados produtivos para o ambiente de homologação ou desenvolvimento, com o intuito de validar melhorias ou identificar problemas com base em cenários reais;

Transferência estruturada de dados entre instâncias da aplicação, mantendo integridade e consistência;

Suporte a práticas seguras de portabilidade, com opções de anonimização ou desidentificação de dados, quando necessário, conforme as diretrizes da LGPD e boas práticas de segurança.

[title] Configurar o Ambiente CITSmart
[path] Administração da Plataforma/

A funcionalidade de Configuração de Ambiente tem por objetivo facilitar uma eventual intervenção (correção) direto no ambiente (servidor) e alterar os logos do sistema.

Poderá alterar o logo do sistema, verificar as informações do ambiente e realizar o download do Log do Jboss.

## Procedimento

- Acessar o menu principal `Sistema > Configurações > Configurações de
   Ambiente;`
- Para alterar umas das imagens (logo início, logo portal, logo sistema e logo relatório), clicar no botão "**Selecionar uma imagem**";

:::hint{type="info"}
**Nota: **O campo Logo sistema obedecerá ao parâmetro 387.
:::

- Clicar na caixa pontilhada para arrastar um arquivo ou fazer o upload;
- Clicar em "**Gravar**";
- Para realizar o download do Log do Jboss ou, clicar no botão "**Download**".


[title] Parametrização - Problema
[path] Administração da Plataforma/Untitled/

O gerenciamento de problemas controla o ciclo de vida de todos problemas desde a primeira identificação, passando pela investigação, documentação e eventual remoção. A parametrização de "Problema" deve ser realizada para permitir a execução/uso deste processo, podendo ser possível definir o nome do fluxo padrão para problema, definir se serão notificados o responsável e grupo executor quando o prazo para contornar/solucionar o problema houver expirado, dentre outras ações.

## Procedimento

1. Acessar a funcionalidade através da navegação no menu principal `Parametrização > Gerência de Problema;`
2. Definir os valores dos parâmetros (atributos);
3. Clicar no botão "**Gravar**" para efetuar a operação;
4. A lista abaixo representa os parâmetros do "**Problema**" e a finalidade de cada um deles:

| #   | Nome                                                                                                                                             | Valores possíveis   | Finalidade                                                                                                                                                                                                                                                                                                                                                                                                                         | Orientações complementares                                                                                           |
| --- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| 123 | Nome do fluxo padrão para problema                                                                                                               | Ex: ProblemaPadrao  | Informar o nome do fluxo padrão para Problema. Caso não seja informado um fluxo para o problema, será estabelecido pelo sistema o fluxo (conforme informado no valor do parâmetro). Esse fluxo é definido na tela de “Desenho de Fluxo”.                                                                                                                                                                                           | Não se aplica                                                                                                        |
| 124 | ID do modelo de e-mail que será enviado para o solicitante quando um problema for criado                                                         |                     | Informar o número de identificação (ID) do modelo de e-mail de notificação de criação do problema. Ao registrar um problema na tela de “Registro de Problemas” será utilizado para o envio da notificação de criação do problema o modelo de e-mail definido. Onde essa notificação será enviada para o solicitante. Esse ID do modelo de e-mail é cadastrado na tela de “Modelo de E-mail”.                                       | Caso não informe o número de identificação (ID) do modelo de e-mail, há possiblidade de não enviar o e-mail correto. |
| 125 | ID do modelo de e-mail que será enviado para o solicitante quando um problema estiver em andamento                                               |                     | Informar o número de identificação (ID) do modelo de e-mail de notificação do andamento do problema. Ao realizar a execução do problema na tela de “Problema” será utilizado para o envio da notificação do andamento do problema o modelo de e-mail definido. Onde essa notificação será enviada para o solicitante. Esse ID do modelo de e-mail é cadastrado na tela de “Modelo de E-mail”.                                      | Caso não informe o número de identificação (ID) do modelo de e-mail, há possiblidade de não enviar o e-mail correto. |
| 126 | ID do modelo de e-mail que será enviado para o solicitante quando um problema for finalizado                                                     |                     | Informar o número de identificação (ID) do modelo de e-mail de notificação de finalização do problema. Ao finalizar o problema na tela de “Problema” será utilizado para o envio da notificação de finalização do problema o modelo de e-mail definido. Onde essa notificação será enviada para o solicitante. Esse ID do modelo de e-mail é cadastrado na tela de “Modelo de E-mail”.                                             | Caso não informe o número de identificação (ID) do modelo de e-mail, há possiblidade de não enviar o e-mail correto. |
| 127 | ID do modelo de e-mail que será enviado para o grupo de destino ao escalar um problema                                                           |                     | Informar o número de identificação (ID) do modelo de e-mail de notificação da escalação do problema. Ao escalar um problema para o grupo na tela de “Gerenciamento de Problema”, será utilizado para o envio da notificação da escalação do problema o modelo de e-mail definido. Onde essa notificação será enviada para o grupo de destino. Esse ID do modelo de e-mail é cadastrado na tela de “Modelo de E-mail”.              | Caso não informe o número de identificação (ID) do modelo de e-mail, há possiblidade de não enviar o e-mail correto. |
| 128 | ID do modelo de e-mail que será enviado para o responsável e grupo executor quando o prazo para contornar/solucionar um problema houver expirado |                     | Informar o número de identificação (ID) do modelo de e-mail de notificação de expiração do prazo para contornar/solucionar o problema. Quando o prazo para contornar/solucionar um problema houver expirado, será enviada para o responsável e grupo executor a notificação de expiração do prazo para contornar/solucionar o problema, conforme definido. Esse ID do modelo de e-mail é cadastrado na tela de “Modelo de E-mail”. | Caso não informe o número de identificação (ID) do modelo de e-mail, há possiblidade de não enviar o e-mail correto. |
| 129 | Notificar o responsável e o grupo executor ao expirar o prazo de aplicação da solução/contorno do problema (Ex: S ou N - Default: 'S')           | S ou N (Default: S) | Definir se serão notificados o responsável e o grupo executor quando o prazo para contornar/solucionar o problema houver expirado.                                                                                                                                                                                                                                                                                                 | Caso não informe o valor do parâmetro, será utilizado o valor padrão do sistema: “S” (Sim).                          |
| 194 | Habilita o escalonamento de problema definido nas regras de escalonamento? (Ex: S ou N - Default 'N')                                            | S ou N (Default: N) | Definir se o escalonamento de problema determinado nas regras de escalonamento será habilitado. Essa regra de escalonamento de problema é definida na tela de “Regras de Escalonamento e Notificações Automáticas”.                                                                                                                                                                                                                | Caso não informe o valor do parâmetro, será estabelecido o valor padrão do sistema: “N” (Não).                       |

Tabela 1 - Lista de parâmetros


[title] Relatório de distância percorrida por analista
[path] Administração da Plataforma/Mobile/

Este documento visa mostrar as configurações para visualizar o relatório que demonstra a quilometragem (Quilômetros) percorrida pelo analista de atendimento que esteja utilizando o app CITSmart Experience.

## Antes de começar

- [x] Para o relatório ser visualizado é necessário importar o relatório disponibilizado na seção de Anexo.
- [x] No aplicativo mobile CITSmart Experience o usuário deverá setar a flag “Disponível” (`APP CITSMART > Página Inicial > [Conexão] > Editar > Disponível` ) para iniciar a contagem de Km.
- [x] Ao final dos atendimentos o usuário deverá desabilitar a flag “Disponível”, pois o sistema contabiliza todo o período de disponibilidade.

## Procedimento

*Passo 1*:

1. Acessar o menu principal `Relatórios > Relatório Smart > Gerador de Relatórios Smart;`
2. Clicar no botão “Importar” e selecionar o arquivo do Anexo.

*Passo 2*:

1. Acessar o menu principal `Relatórios > Relatório Smart > Relatórios Smart;`
2. Clicar na aba Incidentes/Requisições e selecionar o relatório importado no passo anterior;
3. Selecionar os filtros para visualizar o relatório;
4. Visualizar o relatório.

:::hint{type="success"}
**Regra:**

Somente tickets capturados/delegados ao atendente e que estejam fechados serão
&#x20;contabilizados no campo “Solicitações” do relatório.
:::


[title] Realizar conexões externas
[path] Administração da Plataforma/Untitled/

Esta funcionalidade tem por objetivo permitir a criação de conexões com outros
&#x20;bancos de dados seja ele interno ou externo.

Esta funcionalidade disponibiliza ações diversas, tais como, incluir, alterar e
&#x20;excluir conexões externas.

## Procedimento

1. Acessar a funcionalidade através da navegação no menu principal `Sistema > Conexões Externas;`
2. Preencher os campos disponibilizados;
3. Clicar no botão "**Teste Conexão**" para verificar se a conexão foi estabelecida com sucesso;
4. Clicar no botão "**Gravar**".

:::hint{type="info"}
**Nota: **É apresentada a seguinte mensagem caso os dados do campo Url, Usuário e Senha não forem válidos:&#x20;

*Dados incorretos e/ou Banco inacessível! Deseja salvar assim mesmo?*
:::


[title] Parametrização - Mobile
[path] Administração da Plataforma/Untitled/

A parametrização de "Mobile" possui a finalidade de configuração, customização para adequação de cenário no que tange a utilização dos aplicativos mobile (como por exemplo, o CITSmart GO).

## Procedimento

1. Acessar a funcionalidade através da navegação no menu principal `Parametrização > Mobile;`
2. Definir os valores dos parâmetros (atributos);
3. Clicar no botão "**Gravar**" para efetuar a operação;
4. A lista abaixo representa os parâmetros do "**Mobile**" e a finalidade de cada um deles:

| #   | Nome                                                                                                                     | Valores possíveis   | Finalidade                                                                                                                                                                                                                                                                                             | Orientações complementares |
| --- | ------------------------------------------------------------------------------------------------------------------------ | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------- |
| 255 | Raio de Ação/Visualização do atendente no Mobile - (Default: 30)                                                         |                     | Definir o raio de ação de um atendente, utilizado no APP mobile. Definir o raio máximo de atendimento de solicitações que estejam com situação “Não Direcionada”.                                                                                                                                      | Não se aplica              |
| 256 | Intervalo (em minutos) de tempo para reporte de posição do Atendente - (Default: 10)                                     |                     | Definir o intervalo que o aplicativo Mobile deve reportar ao servidor o posicionamento geográfico do atendente.                                                                                                                                                                                        | Não se aplica              |
| 257 | Tamanho de página para retorno nos serviços REST paginados (Default: 10)                                                 |                     | Definir a quantidade de registros retornado em serviços de listagem consumidos pelo Mobile.                                                                                                                                                                                                            | Não se aplica              |
| 258 | Intervalo máximo de dias para consulta (Default: 30)                                                                     |                     | Definir restrição de intervalo máximo de consulta nas telas, inicialmente utilizadas na gestão da força de atendimento.                                                                                                                                                                                | Não se aplica              |
| 267 | Tamanho de página para retorno nos serviços REST V1 mobile (Default: 200)                                                |                     | Definir o tamanho da página para retorno nos serviços REST.                                                                                                                                                                                                                                            | Não se aplica              |
| 272 | Determina se serão notificados somente solicitações sem responsável no CITSmart Mobile. Valores: "S" ou "N" Default: "N" | S ou N (Default: N) | Definir quais solicitações poderão ser notificadas ao usuário. Caso o valor do parâmetro seja “S”, serão apresentadas somente as notificações de solicitações sem responsável atual pelo atendimento. Caso o valor do parâmetro seja “N”, serão apresentadas as notificações de todas as solicitações. | Não se aplica              |
| 284 | ID do contrato padrão para a criação de novos incidentes/requisições no CITSmart Mobile.                                 |                     | Informar o número de identificação (ID) do contrato para realizar a abertura de solicitações de serviço via mobile.                                                                                                                                                                                    | Não se aplica              |
| 285 | ID do serviço padrão para solicitações de serviços e incidentes criados no CITSmart Mobile.                              |                     | Informar o número de identificação (ID) do serviço que será padrão para registro de solicitações de serviços via mobile.                                                                                                                                                                               | Não se aplica              |
| 286 | ID de origem padrão para as solicitações de serviço e incidentes criados no CITSmart Mobile.                             |                     | Informar o número de identificação (ID) da origem padrão para abertura de solicitação de serviço via mobile.                                                                                                                                                                                           | Não se aplica              |
| 350 | Habilita o envio de notificações para celulares                                                                          | S ou N (Default: N) | Permite controlar se as notificações do sistema serão enviadas para dispositivos móveis (gerais).                                                                                                                                                                                                      | Não se aplica              |
| 352 | Habilita o envio de notificações para celulares durante a criação de solicitações                                        | S ou N (Default: N) | Permite controlar se as notificações do sistema serão enviadas para dispositivos móveis (gerais).                                                                                                                                                                                                      | Não se aplica              |
| 353 | Habilita o envio de notificações para celulares durante a atualização de solicitações informando atendimentos próximos   | S ou N (Default: N) | Permite controlar se as notificações do sistema serão enviadas para dispositivos móveis (gerais).                                                                                                                                                                                                      | Não se aplica              |

Tabela 1 - Lista de parâmetros


[title] Parametrização - Chat
[path] Administração da Plataforma/Untitled/

A noção de "Chat" é usada para fazer alusão à troca de mensagens escritas de forma instantânea. Neste caso, permite o usuário ter contato direto ao atendente do sistema afim de dirimir dúvidas, realizar solicitações, dentre outros. Os parâmetros desta aplicação permitem ativar o chat, definir o contrato padrão para abertura de chamado e ajustar o grupo padrão, dentro de outras ações.

## Procedimento

1. Acessar a funcionalidade através da navegação no menu principal `Parametrização > Chat;`
2. Definir os valores dos parâmetros (atributos);
3. Clicar no botão "**Gravar**" para efetuar a operação;
4. A lista abaixo apresenta os parâmetros da funcionalidade "**Chat**" e a finalidade de cada um deles.

| #   | Nome                                                               | Valores posssíveis | Finalidade                                                                    | Orientações complementares |
| --- | ------------------------------------------------------------------ | ------------------ | ----------------------------------------------------------------------------- | -------------------------- |
| 118 | ID do contrato padrão para abertura de chamados                    |                    | ID do contrato padrão para abertura de chamados                               | Não se aplica              |
| 315 | ID da origem das solicitações criadas pelo chat                    |                    | ID da origem das solicitações criadas pelo chat                               | Não se aplica              |
| 316 | Ativar Chat                                                        | S ou N             | Ativar Chat                                                                   | Não se aplica              |
| 317 | ID da atividade das solicitações criadas pelo chat                 |                    | ID da atividade das solicitações criadas pelo chat                            | Não se aplica              |
| 388 | ID usuário padrão (Requisição externa)                             |                    | ID usuário padrão (Requisição externa)                                        | Não se aplica              |
| 389 | ID grupo padrão (Requisição externa)                               |                    | ID grupo padrão (Requisição externa)                                          | Não se aplica              |
| 390 | ID da unidade padrão                                               |                    | ID da Unidade que será atribuido ao usuário cadastrado no profile             | Não se aplica              |
| 447 | ID do modelo de e-mail para notificação de novas mensagens no chat |                    | ID do modelo de e-mail para notificação de novas mensagens no chat            | Não se aplica              |
| 299 | Ticket - Ativar troca de mensagens                                 | S ou N             | Ativa um ícone de conversa ao lado do número do ticket na fila de atendimento | Não se aplica              |
| 448 | Editor de texto utilizado pela aplicação                           |                    | Editor de texto utilizado pela aplicação                                      | Não se aplica              |

Tabela 1 - Lista de parâmetros


[title] Parametrização - Ordem de Serviço
[path] Administração da Plataforma/Untitled/

Ordem de serviço é um documento que irá fornecer a permissão de execução relativa a algum serviço. A parametrização de "Ordem de serviço" permite definir a fórmula de cálculo da glosa de ordem de serviço, habilitar assinaturas personalizadas no relatório de Ordens de Serviço, dentre outras ações.

## Procedimento

1. Acessar a funcionalidade através da navegação no menu principal `Parametrização > Ordem de Serviço (OS);`
2. Definir os valores dos parâmetros (atributos);
3. Clicar no botão "**Gravar**" para efetuar a operação;
4. A lista abaixo representa os parâmetros da "**Ordem de serviço**" e a finalidade de cada um deles:

| #   | Nome                                                                                     | Valores possíveis   | Finalidade                                                                                                                                                                                                                                                                                                                                                                                 | Orientações complementares                                                                                                                       |
| --- | ---------------------------------------------------------------------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| 51  | FORMULA GLOSA OS - Código Padrão                                                         |                     | Definir a fórmula de Cálculo da Glosa de Ordem de Serviço. Por padrão a fórmula já está definida na ferramenta.                                                                                                                                                                                                                                                                            | Não se aplica                                                                                                                                    |
| 130 | Permitir a listagem de Ordem de Serviços com data retroativa (Ex: S ou N - Default: 'N') | S ou N (Default: N) | Definir se será permitida a listagem de Ordem de Serviços com data retroativa.                                                                                                                                                                                                                                                                                                             | Caso não informe o valor do parâmetro, será utilizado o valor padrão do sistema: “N” (Não).                                                      |
| 229 | Re-configurar Fórmulas das Atividades (S ou N - Default: 'S')                            | S ou N (Default: S) | Modificar a estrutura da fórmula das atividades já cadastradas para a nova estrutura que é configurável de na tela de Fórmula OS. Ao informar o valor padrão “S”, o sistema irá executar a rotina de reconfiguração da fórmula das atividades no momento que o JBoss for reiniciado numa atualização do sistema CITSmart e atribuir “N” para este parâmetro no momento de sua finalização. | Uma vez informado o valor “S”, a fórmula das atividades do contrato, ainda não configurada, ficará de acordo com a nova estrutura de Fórmula OS. |
| 243 | Ativar assinaturas personalizadas no relatório de Ordens de Serviço                      |                     | Habilitar assinaturas para serem utilizadas na impressão dos relatórios de Ordem de Serviço. Quando o parâmetro estiver ativado (valor = S) o sistema exibirá um campo na tela de cadastro de Ordem de Serviço e o usuário poderá escolher qual configuração dos quadros de assinaturas será usada na impressão de seus relatórios.                                                        | Quando habilitado o parâmetro, obriga o usuário definir e configurar mais um campo antes de gravar uma Ordem de Serviço.                         |

Tabela 1 - Lista de parâmetros


[title] Parametrização - Smart Portal
[path] Administração da Plataforma/Untitled/

O Smart Portal é um recurso da solução que disponibiliza o Catálogo de Serviços (Negócio e Apoio) aos usuários do sistema e entres outras informações, como: solicitações de serviços, notícias referentes ao sistema e chat. A parametrização do "Smart Portal" permite ativar a troca de mensagens entre o solicitante e o responsável pela solicitação, habilitar a opção de cancelar um ticket pelo Portal, dentre outras ações viáveis.

## Procedimento

1. Acessar a funcionalidade através da navegação no menu principal `Parametrização > Smart Portal;`
2. Definir os valores dos parâmetros (atributos);
3. Clicar no botão "**Gravar**" para efetuar a operação;
4. A lista abaixo representa os parâmetros do "**Smart Portal**" e a finalidade de cada um deles:

| #   | Nome                                                                                                             | Valores possíveis   | Finalidade                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Orientações complementares                                                                                                                                                                                                                                                  |
| --- | ---------------------------------------------------------------------------------------------------------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 245 | Apresentar tela lista de serviço completa no Portal (Ex: S ou N - Default 'N')                                   | S ou N (Default: N) | Habilitar a exibição das colunas de preço no carrinho de compras do Portal do CITSmart.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Não se aplica                                                                                                                                                                                                                                                               |
| 246 | Ocultar Botão 'Nova Solicitação' no Portal (Ex: S ou N)                                                          | S ou N              | Ocultar a exibição do botão “Nova Solicitação” na tela do Portal.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Não se aplica                                                                                                                                                                                                                                                               |
| 247 | Serviços do Carrinho de Compras venham desmarcados por default no Portal (Ex: S ou N - Default 'S')              | S ou N (Default: S) | Desabilitar/Habilitar a marcação dos serviços do carrinho de compras do Portal.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Não se aplica                                                                                                                                                                                                                                                               |
| 252 | Registrar Ocorrência pelo Portal                                                                                 |                     | Habilitar a opção de registrar ocorrência para uma solicitação que estiver com situação “Em Andamento”.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Se o parâmetro estiver com valor ‘S’ a opção de registrar ocorrência pelo portal será exibida para o usuário.                                                                                                                                                               |
| 253 | ID e-mail Registro Ocorrência pelo Portal                                                                        |                     | Informar o número de identificação (ID) do modelo de e-mail padrão para envio de notificação para o “responsável” da solicitação, após o registro de uma ocorrência pelo Portal. Esse ID do modelo de e-mail é definido na tela de “Modelo de E-mail”.                                                                                                                                                                                                                                                                                                                                  | Com o número de identificação o modelo de e-mail que será utilizado para notificar o técnico quando houver um registro de ocorrência pelo Portal de Serviço. Se o número de identificação (ID) não for informado corretamente o sistema não enviará e-mails de notificação. |
| 262 | ID Categoria Registra Ocorrência Portal                                                                          |                     | Definir a categoria padrão para o registro de ocorrência pelo Portal. Se o valor for definido corretamente, o campo “Categoria” ficará desabilitado para alteração recebendo o valor desse parâmetro. Caso o valor do parâmetro seja inválido, o parâmetro ficará desabilitado.                                                                                                                                                                                                                                                                                                         | Não se aplica                                                                                                                                                                                                                                                               |
| 263 | ID Origem Registra Ocorrência Portal                                                                             |                     | Definir a origem padrão para o registro de ocorrência pelo Portal. Se o valor for definido corretamente, o campo “Origem” ficará desabilitado para alteração recebendo o valor desse parâmetro. Caso o valor do parâmetro seja inválido, o parâmetro ficará desabilitado.                                                                                                                                                                                                                                                                                                               | Não se aplica                                                                                                                                                                                                                                                               |
| 292 | Habilita botão "Adicionar e continuar" na popup de nova solicitação no portal - Valores: "S" ou "N" Default: "N" | S ou N (Default: N) | Definir se o botão “Adicionar e continuar” será apresentado na tela de Solicitação de Serviço do Portal.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Caso não seja definido o valor para o parâmetro, será definido pelo sistema automaticamente o valor: “N” (Não).                                                                                                                                                             |
| 293 | Habilita permissão de acesso para grupos de usuário no portal - Valores: "S" ou "N" Default: "N"                 | S ou N (Default: N) | Habilitar a configuração da permissão de acesso dos grupos feita no portfólio de serviço, serviço de negócio/TI e serviço de incidente e requisição para visualização dos mesmos no Portal. Quando o valor do parâmetro for "S", a visibilidade no Portal passa a ser limitada aos grupos de usuários configurados no cadastro do portfólio, cadastro do serviço deste portfolio e no cadastro dos serviços de incidentes e requisições do serviço. E quando o valor do parâmetro for "N", é desabilitado a permissão de acesso, logo a visibilidade no Portal é liberada por completo. | Caso não seja definido o valor para o parâmetro, será definido pelo sistema automaticamente o valor: “N” (Não).                                                                                                                                                             |
| 298 | Exibir as ocorrências da Solicitação/Incidente (Valores: "S" ou "N" Default: "N")                                | S ou N (Default: N) | Exibir ou esconder as ocorrências do ticket                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Não se aplica                                                                                                                                                                                                                                                               |
| 299 | Requisição/Incidente - Ativar troca de mensagens (Valores: "S" ou "N" Default: "N")                              | S ou N (Default: N) | Ativar a troca de mensagens entre o solicitante e o responsável pela solicitação                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Não se aplica                                                                                                                                                                                                                                                               |
| 302 | Habilitar cancelamento de solicitação/incidente pelo portal (Valores: "S" ou "N" Default: "N")                   | S ou N (Default: N) | Habilitar a opção de cancelar um ticket pelo portal                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Não se aplica                                                                                                                                                                                                                                                               |
| 371 | Habilitar resposta da solicitação no portal                                                                      | S ou N (Default: N) | Permite mostrar/ocultar a Solução Resposta ao mostrar o ticket no Smart Portal.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Não se aplica                                                                                                                                                                                                                                                               |
| 373 | ID Grupo padrão cadastro profile                                                                                 |                     | Guarda o ID do grupo que será configurado para um usuário gravado via perfil                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Não se aplica                                                                                                                                                                                                                                                               |
| 374 | ID Portfólio redirecionamento profile                                                                            |                     | Guarda o ID de portfólio que o usuário gravado via perfil terá acesso                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Não se aplica                                                                                                                                                                                                                                                               |
| 376 | ID Modelo de E-mail cadastro profile                                                                             |                     | Guarda o ID do modelo de e-mail que será enviado ao usuário cadastrado pelo perfil                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Não se aplica                                                                                                                                                                                                                                                               |
| 377 | URL Redirecionamento logout                                                                                      |                     | Guarda o endereço que o usuário será redirecionado após o cadastro no perfil                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Não se aplica                                                                                                                                                                                                                                                               |
| 386 | ID Sub portfólio redirecionamento profile                                                                        | Números inteiros    | Guarda o ID de serviço/negócio que o usuário gravado via perfil terá acesso                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Não se aplica                                                                                                                                                                                                                                                               |
| 387 | Usar logo header em loading                                                                                      |                     | Informa se o usuário irá utilizar outra imagem quando houver carregamento no sistema                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Não se aplica                                                                                                                                                                                                                                                               |

Tabela 1 - Lista de parâmetros


[title] Verificar log do sistema
[path] Administração da Plataforma/Log's e auditoria/

A solução trás logs de auditoria de todas as movimentações que ocorrem dentro de todas as apliações sejam elas do ESM ou da área de Infraestrutura. Esses logs auxiliam na rastreabilidade do que os usuários fizeram dentro da solução.

Além de gerar o relatório na solução, é possível extrair o seu resultado como arquivos do tipo .csv e .xlsx.

## Procedimento

O relatório pode ser acessado pelo seguinte caminho: `Relatórios POC > Acompanhamento
 de Logs ITSM`

Neste local poderá escolher qual o tipo de log que deseja visualizar, sendo de Infraestrutura ou Geral.

Para gerar o relatório é necessário preencher os campos e selecionar a opção atualizar.

:::hint{type="info"}
NotaDevido a arquitetura da plataforma e sistema de segurança, os logs só podem ser visualizados sem nenhuma possibilidade de edição ou exclusão.
:::

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/THjyF7RmrrJE1a-X_-8dp_.blob)

### Auditoria de Atividades e Acessos

A plataforma oferece um recurso completo de auditoria, permitindo que você acompanhe todas as ações realizadas nos fluxos de trabalho e nos dados registrados, garantindo conformidade, integridade, confiabilidade e transparência no uso do sistema.

O que é possível acompanhar na auditoria:

- Quem acessou o sistema ou realizou determinada ação
- Quando a ação foi executada (data e hora)
- O que foi feito: alterações em dados, execuções de processos ou acessos a informações sensíveis
- Quais dados foram visualizados ou modificados
- Garantia de não repúdio (registro imutável da autoria da ação)


[title] CITSmart auto-login - SSO
[path] Administração da Plataforma/Untitled/

> **Branchs**
>
> :
>    Sso (itsm)
>    Spnego 1.0 (artifactory)

## Criar usuário AD

- Acessar criar usuário em Usuários e Computadores do Active Directory:

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/PV1u4m_0mNnQmmgxaQp-W_sso-1.jpg" size="62" width="574" height="684" caption position="center" signedSrc="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/PV1u4m_0mNnQmmgxaQp-W_sso-1.jpg"}

- Criar uma senha:

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/u9pWP51ChakMzvWsLXrSZ_sso-2.jpg" size="70" width="397" height="306" caption position="center" signedSrc="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/u9pWP51ChakMzvWsLXrSZ_sso-2.jpg"}

- Clicar no lado direito do mouse, no botão usuário/propriedades:

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/zulmdP9PjIGrGBy7joOd-_sso-3.jpg" size="62" width="472" height="488" caption position="center" signedSrc="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/zulmdP9PjIGrGBy7joOd-_sso-3.jpg"}

- Selecionar a opção "Esta conta oferece suporte para criptografia de 256 bits", aplicar e marcar "OK":

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/tpq3QruFtLIekZyrvN6gE_sso-4.jpg" size="70" width="408" height="459" caption position="center" signedSrc="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/tpq3QruFtLIekZyrvN6gE_sso-4.jpg"}

- Abrir o ADSI Editar. Logo após, conectar no AD, clicar em usuários e localizar o usuário recém criado:

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/S38udF5L12KSFyKEQXpZz_sso-5.jpg)

- Clicar no botão direito do mouse e selecionar a opção Propriedades. Logo após, procurar o **servicePrincipalName** (sigla de SPN);
- Adicionar HTTP/hom-itsm.centralit.com.br, clicar em "OK" para efetuar a operação:

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/o6QQC6hFzVbb8vuKqc_FX_sso-6.jpg)

- Abrir o **CMD** como Administrador e colocar os seguintes comandos. Lembrar que o primeiro seta o **SPN** e o segundo gera o Keytab (o que será utilizado no Wildfly):

> setspn -s HTTP/hom-itsm.centralit.com.br citsmart2
>
> ktpass / princ HTTP/hom-itsm.centralit.com.br /mapuser citsmart2  /pass central@123 /ptype KRB5_NT_Principal/outcitsmart2.keytab /crypto ALL

- Realizado os passos acima, o **AD** estará configurado. 

## Configurar o servidor Wildfly

1. Copiar o **war** gerado da branch **sso**;
2. Copiar o arquivo krb5.conf (validar as informações de acordo com o AD) para
   a pasta standalone/configuration (wildfly):

```shell
[libdefaults]
default_tkt_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 rc4-hmac
default_tgs_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 rc4-hmac
permitted_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 rc4-hmac
[realms]
```

```shell
[domain_realm]
.citsmartsrv.citsmartsrv.bigdata-team.com = citsmartsrv.citsmartsrv.bigdata-team.com
```

```shell
[domain_realm]
.citsmartsrv.citsmartsrv.bigdata-team.com = citsmartsrv.citsmartsrv.bigdata-team.com
```

1. Copiar o arquivo login.conf (validar as informações de acordo com o AD) para a pasta standalone/configuration (wildfly):

```shell
custom-client {
com.sun.security.auth.module.Krb5LoginModule required
storeKey=true
useKeyTab=true
keyTab="file:///opt/wildfly-12.0.0.Final/standalone/configuration/lightkeytab.keytab"
principal=HTTP/light-desenvolvimento.citsmartcloud.com\@CITSMARTSRV.BIGDATA-TEAM.COM;
};
```

1. Copiar o arquivo lightkeytab.keytab (gerado pelo comando no AD) para a pasta standalone/configuration (wildfly)
2. Arrumar o standalone.xlm ao adicionar as seguintes informações:

- Em **\\\<system-properties>**

```java
\<property name="sun.security.krb5.debug" value="true"/\>
\<property name="java.security.krb5.kdc" value="CITSMARTSRV.BIGDATA-TEAM.COM"/\>
\<property name="java.security.krb5.realm"value="CITSMARTSRV.BIGDATA-TEAM.COM"/\>
\<property name="java.security.krb5.conf"value="/opt/wildfly-12.0.0.Final/standalone/configuration/krb5.conf"/\>
\<property name="java.security.auth.login.config"value="/opt/wildfly-12.0.0.Final/standalone/configuration/login.conf"/\>
\<property name="krb.keyTab"value="/opt/wildfly-12.0.0.Final/standalone/configuration/lightkeytab.keytab"/\>
\<property name="krb.principal"value="HTTP/light-desenvolvimento.citsmartcloud.com\@CITSMARTSRV.BIGDATA-TEAM.COM"/\>
```

- Em **\\\<security-domains**>

```java
\<security-domain name="spnego-server"\>
\<authentication\>
\<login-module code="com.sun.security.auth.module.Krb5LoginModule"flag="required"\>
\<module-option name="storeKey" value="true"/\>
\<module-option name="useKeyTab" value="true"/\>
\<module-option name="keyTab" value="\${krb.keyTab}"/\>
\<module-option name="principal" value="\${krb.principal}"/\>
\<module-option name="isInitiator" value="false"/\>
\</login-module\>
\</authentication\>
\</security-domain\>
\<security-domain name="SPNEGO" cache-type="default"\>
\<authentication\>
\<login-module code="Kerberos" flag="required"\>
\<module-option name="storeKey" value="true"/\>
\<module-option name="refreshKrb5Config" value="true"/\>
\<module-option name="useKeyTab" value="true"/\>
\<module-option name="doNotPrompt" value="true"/\>
\</login-module\>
\</authentication\>
\</security-domain\>
```

1. Caso não tenha alterado o jar do policy do JAVA (JCE - Java Cryptography Extension), baixar os arquivos e colocar em
   jdk/jre/lib/security/policy/limited e jdk/jre/lib/security/policy/unlimited;
2. Importar (sincronizar) usuários do LDAP no ITSM.

:::hint{type="warning"}
**Atenção**

O DN Alias deve ser igual ao domínio da rede (exemplo: CIT\\\usuario), logo o DN Alias = CIT, conforme a figura abaixo:
:::

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/HlKeM_pSfQfu_PKh-bzyi_image.png" size="96" width="758" height="577" caption="Figura 7 - Definir o DN" position="center"}

:::hint{type="success"}
**Dica: **É recomendável a leitura dos seguintes materiais de apoio: <a href="https://ss64.com/nt/setspn.html" target="_blank">https\://ss64.com/nt/setspn.html</a> e <a href="http://spnego.sourceforge.net/" target="_blank">http\://spnego.sourceforge.net/</a>
:::


[title] Papéis do usuário
[path] Administração de Usuários, Grupos, Papéis e Parâmetros/

Esta área permite a criação dos papéis (perfis de acesso) que os usúários ou grupos de usuários terão para um determinado ambiente, aplicação (lowcode, ITSM, CHATBOT, etc), bem como menus, submenus e acessos.

Os papeís também são considerados perfils de usuários que também definem quais os acessos podem ser concedicos para pessoas ou grupos específicos.&#x20;

A ferramenta tem uma tela de busca e apresenta documentos provenientes do gestor de identidade.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/vRiMlCe_i9cIxf96od_7Y_image.png)

É possível selecionar diversos documentos simultaneamente e excluí-los. Esta ferramenta permite também editar e remover um documento específico.

Além disso, é possível criar um novo papel que também será incluído no Keycloak.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/UKtGgjQPaMiPyUugxGyTv_cadastro-de-roles-001.png" size="90" width="847" height="381" caption position="center" signedSrc="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/UKtGgjQPaMiPyUugxGyTv_cadastro-de-roles-001.png"}

As informações com asterisco (\*) são obrigatórias.

***

Para salvar o novo documento, clique em "**Salvar**", ou para salvar e continuar a edição, clique em "**Salvar e continuar**".

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/dZltbTEAjX7qYWy76VIFH_cadastro-de-roles-002.png" size="86" width="712" height="376" caption position="center" signedSrc="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/dZltbTEAjX7qYWy76VIFH_cadastro-de-roles-002.png"}


[title] Autenticação
[path] Administração da Plataforma/

Nativamente, são possíveis os seguintes tipos de autenticação na plataforma: local, LDAP/AD,SSO e Okta.

- **Local**: este é o método padrão de acesso à plataforma, em que os usuários são cadastrados na base de dados da ferramenta.
- **LDAP/AD**: a autenticação é a forma mais comum de acesso à plataforma e está voltada ao cenário do cliente final. Com ele é possível autenticar-se no sistema sem a necessidade de criar usuários manualmente.
- **Sing Single On - SSO**: esta é uma alternativa para fazer logon automático na plataforma. Contudo é necessário ter uma infraestrutura orientada a este serviço.
- **Okta**: com este método é possível utilizar uma base usuários disponível no Okta e utilizá-la para autenticação em uma instância CITSmart.

## Autenticação Integrada com Provedores de Identidade (IdP)

A plataforma oferece suporte à autenticação de usuários por meio da integração com provedores de identidade externos (IdPs), utilizando o protocolo SAML (Security Assertion Markup Language). Esse modelo de autenticação federada permite que os usuários acessem a plataforma com segurança, usando credenciais corporativas já existentes, sem a necessidade de criar novos logins ou senhas.

Atualmente, a solução está configurada para utilizar o Keycloak como principal IdP, possibilitando:

- Autenticação centralizada e padronizada;
- Gerenciamento de identidade conforme as políticas de segurança da organização;
- Integração com diretórios corporativos (como LDAP ou Active Directory);
- Suporte ao protocolo SAML 2.0, viabilizando a comunicação com outros provedores compatíveis, caso necessário.

Essa abordagem garante uma experiência de login segura, consistente e alinhada com os padrões de segurança utilizados por grandes organizações e ambientes governamentais.


[title] Criar Calendário
[path] Administração da Plataforma/

A página de gerenciamento de calendário tem funcionalidades que permitem realizar diversas ações como: incluir, alterar e excluir calendários/escalas de jornada de trabalho

## Antes de começar

- [x] Para cadastrar um calendário é necessário o registro prévio de um perfil de acesso e um registro da jornada de trabalho.

## Procedimento

1. Para acessar essa funcionalidade utilize o menu principal Cadastros Gerais > Gerência de Pessoal > Calendário;
2. Ao abrir a funcionalidade como padrão abrirá na aba de cadastro de calendário;
3. Inicie a criação do calendário preenchendo os campos disponibilizados da melhor maneira;

:::hint{type="info"}
**Nota:** Ao indicar a opção sim, no campo Considera Feriados, isto significa que os feriados serão considerados como dia de folga no calendário. Portanto, se o time relacionado ao calendário trabalha durante feriados, escolha a opção **não**.
:::

1. Na parte das exceções clique no ícone exceções “+”, será aberta uma janela onde poderão ser inseridas as exceções para dias de folga ou trabalho;
2. Clique em gravar para que o calendário seja criado;
3. Na aba Pesquisa de Calendário tem uma barra de pesquisa que é utilizada para pesquisar um calendário específico;
4. Clicando em pesquisar será listado todos os calendários existentes;
5. Para editar um calendário apenas selecione o calendário e será direcionado para a aba de cadastro de calendário com todas as informações já preenchidas;
6. Caso necessite excluir o calendário clique no botão excluir;
7. Caso necessite criar outro calendário clique no botão limpar para que todas as informações sejam apagadas;


[title] Administração de Usuários, Grupos, Papéis e Parâmetros
[path] /


[title] Configurar o Okta no CITSmart
[path] Administração da Plataforma/Untitled/

Este método de autenticação permite que se utilize os recursos do Okta para autenticar usuários da organização em uma instância CITSmart. Este documento explica os passos da configuração deste método. Para saber mais sobre o Okta acesse okta.com

## Antes de começar

- [x] A configuração desta solução é um processo de diversas fases. A primeira fase é a criação de uma conta Okta.

## Procedimento

*1º Passo: Criar uma conta Okta:*

1. Acessar o site:  [https://www.okta.com](https://www.okta.com);
2. Clicar em "Try Okta" e em seguida "Sign up today";
3. Informar os dados essenciais (e-mail, nome e sobrenome);
4. Apertar o botão "Get Started" para concluir a operação. Em seguida, verificar o e-mail cadastrado (que enviará um link de acesso), acessar a conta com a senha temporária enviada e alterar a mesma para maior segurança dos dados;

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/PSny54mLBxj5h7FrAx_kf_image.png" size="66" width="420" height="448" caption position="center" signedSrc="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/PSny54mLBxj5h7FrAx_kf_image.png"}

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/2woQLMfAyhrq7nMmoIlGj_image.png)



*2º Passo: Criar a aplicação CITSmart dentro do Okta:*

1. Após concluído a etapa anterior, conectar-se ao Okta com a conta recém criada;
2. Clicar na aba "Applications e em seguida no botão "Add Application";

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/GSuKTYqIx6iYdDnZ1Mtf0_image.png)

1. Apertar em "Create New App";

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/KwLOlGTkthY0le35YTwxO_image.png)

1. Marcar a opção "SAML 2.0" e depois clicar no botão "Create";
2. No campo "App name", adcionar o nome da aplicação e logo após, é necessário clicar no botão "Next";
3. Configurar o caminho da aplicação e depois clicar no botão Next;
4. Marcar as opções "I'm an Okta customer adding an internal app" e "This is an internal app that we have created". Logo em seguida, clicar no botão "Finish".

*3º Passo: Atribuir usuários a aplicação CITSmart do Okta:*

1. Concluído o passo anterior, é necessário clicar na aba "Applications > Applications" e em seguida em "Assign Applications" e optar pelo filtro chamado "People";
2. Em seguida, é possível escolher o usuário que terá a permissão de acessar a aplicação que está sendo criada. Clicar então no botão "Assign" e posteriormente para finalizar, clicar em  "Done";

*4º Passo: Incluir informações necessárias no CITSmart configurado no Okta:*

1. Será necessário configurar alguns dados no diretório do WildFly. Acessar o diretório, abrir a pasta "/standalone/configuration" e alterar o arquivo "citsmart.cfg".

*5º Passo: Sincronizar usuário do Okta no CITSmart:*

1. Dentro do CITSmart, acessar o menu "Okta Config" e cadastrar uma nova configuração ao clicar no botão "Novo";
2. Preencher os campos com as informações necessárias:
   - **Descrição:** introduzir uma definição desta nova configuração Okta;
   - **Alias:** incluir o domínio do usuário que será gravado na base. Exemplo: okta\\[administrador@citsmart.com](mailto\:administrador@citsmart.com);
   - **URL de domínio:** deverá incluir o mesmo valor (URL) que foi inserida na linha *OKTA\_URL* no arquivo "citsmart.cfg";
   - **Token API:** incluir o mesmo valor do token inserido na linha *OKTA\_TOKEN* no arquivo "citsmart.cfg";
   - **Grupo:** inserir o ID do grupo no qual o usuário sincronizado e gravado pertencerá no CITSmart;
   - **Perfil de Acesso:** inserir o ID do perfil no qual o usuário sincronizado e gravado pertencerá no CITSmart;
   - **ID da aplicação:** incluir o ID da aplicação. Esta informação pode ser recuperada na URL do Okta, conforme a figura abaixo:
3. Clicar no botão "Salvar" e em seguida "Sicronizar usuários" para efetuar a operação.

*6º Passo: Configurar o Logout:*

1. Como o Okta não possui tela de logout, no parâmetro 377 do CITSmart podemos inserir algum endereço de página para redirecionar o usuário ao final da sessão;
2. Configurar o link para logout também no endereço (**Admin > Settings > Customization > Sign-Out-Page)** , em seguida marcar a opção "Usar a custom sign-out page". Então, deve-se inserir a URL ([https://localhost:8443/citsmart/saml/logout](https://localhost:8443/citsmart/saml/logout)) com as devidas adaptações (host e porta), conforme a imagem abaixo:

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/HJPzyTAlHhGbomAr7GZiC_image.png)

:::hint{type="warning"}
**Importante: **Ao fazer o *logout* do CITSmart não deve ser realizado o *logout* do Okta, pois o usuário pode ter outras aplicações na sessão do Okta. Em contrapartida, se fizer o *logout* do Okta, a sessão do usuário no CITSmart será removida.
:::

## O que fazer a seguir

Concluída a integração do Okta com o CITSmart, alguns parâmetros do CITSmart podem ser configurados para melhor personalizar esta integração:

- O parâmetro 445 (Nome do grupo Administrador no Okta) permite escolher o grupo administrador na solução Okta. Se o usuário pertencer a este grupo escolhido, terá o perfil de acesso definido como administrador. Caso o mesmo não tenha um perfil definido, o sistema atribuirá o parâmetro 39 e caso este usuário já tenha um perfil definido no CITSmart, este se manterá.


[title] Logs e auditoria
[path] Administração da Plataforma/


[title] Desbloquear Usuário
[path] Administração da Plataforma/Untitled/

Neste documento veremos os requisitos necessários para desbloqueio de um usuário.

## Antes de começar

- [x] O administrador deverá ter habilitado a regra de Bloqueio de Usuário, contida no cadastro de Política de Segurança;
- [x] O usuário deverá estar impedido de acessar a aplicação devido o uso da regra de bloqueio de usuário.

## Procedimento

A partir da versão 9.1.2.24 foram inseridos novas regras de segurança que originou a inclusão dessa funcionalidade.

1. Acessar o menu principal` Sistema > Segurança > Usuários Bloqueados;`
2. Ao acessar a funcionalidade, aparecerá uma tela com o campo: Nome do usuário - Campo tipo texto para busca pelo nome do usuário bloqueado;
3. Além desse campo, aparecerá uma lista com as seguintes informações:

| Lista               | Descrição                                                            |
| ------------------- | -------------------------------------------------------------------- |
| Usuários bloqueados | Apresenta a informação contexto/login do usuário que foi bloqueado   |
| Data do bloqueio    | Apresenta a informação de data/hora que o sistema efetuou o bloqueio |

1. Aqui também existirá a ação de Excluir, que permite a retirada do bloqueio imediato do usuário.


[title] Usuários
[path] Administração de Usuários, Grupos, Papéis e Parâmetros/

## Cadastro de usuários

Esta ferramenta permite registrar os usuários.

### Procedimento

1. Para criar um usuário, clique no botão "**Criar**" **㊉ **no lado direito;
2. Complete todas as categorias necessárias:

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/qpjFVKImIik-E2Gg8iOHV_cadastro-de-usuario-001.png" size="80" width="1302" height="559" caption position="center" signedSrc="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/qpjFVKImIik-E2Gg8iOHV_cadastro-de-usuario-001.png"}

3\. Selecione se o usuário está ativo ou não, no botão "**Ativo?**";

4\. Este cadastro mostra automaticamente os grupos destinados ao usuário. Estes dados provêm da Conexão Keycloak com o site:

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/Y6mDyNCjuA9Nza9JA2IG3_cadastro-de-usuario-001.png)

5\. Para cadastrar um novo usuário, clique no botão "**Salvar e Continuar**".

## Habilitando e desabilitando usuários

Esta ferramenta permite habilitar e desabilitar usuários.

### Procedimento

1. Para desabilitar um usuário ativado, clique na caixa de seleção ☐ desejada localizada na primeira coluna da esquerda para a direita (além do nome do usuário), e na barra de navegação superior, no lado direito, selecione "🗑** Desabilitar**".
2. Para ativar um usuário desabilitado, clique na caixa de seleção ☐ desejada localizada na primeira coluna da esquerda para a direita (além do nome do usuário), e na barra de navegação superior, no lado direito, selecione "🗑 **Habilitar**".

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/phDtDLvkxfcLs0dPthale_image.png)

:::hint{type="warning"}
**🖊 *****Nota 1*****: **Apenas desabilite os usuários que estiverem marcados com "**Sim**" na coluna "**Ativo**". Isto significa que o usuário está ativo.

**🖊 *****Nota 2*****: **Apenas habilite os usuários que estiverem marcados com "**Não**" na coluna "**Ativo**". Isto significa que o usuário não está ativo.
:::

3\. É possível editar um usuário clicando no ícone 🖊, localizado na última coluna à direita.
4\. Para excluir um usuário, clique no ícone 🗑, localizado na última coluna à direita.&#x20;

:::hint{type="warning"}
⚠️ ***Atenção*****! **

Ao excluir o usuário, **eles não são removidos do banco de dados.**
:::

## Perfil

- Este sistema permite alterar os dados do perfil do usuário;
- Na tela Perfil, é possível alterar dados pessoais a seguir:

<table columnWidths="125,535,220" selectedRows="" selectedTable="false" isTableHeaderOn="true" selectedColumns="">
  <tr>
    <td>
      <p><strong>Campo</strong></p>
    </td>
    <td>
      <p><strong>Descrição</strong></p>
    </td>
  </tr>
  <tr>
    <td>
      <p><strong>E-mail</strong>*****</p>
    </td>
    <td>
    </td>
  </tr>
  <tr>
    <td>
      <p><strong>Telefone</strong></p>
    </td>
    <td>
    </td>
  </tr>
  <tr>
    <td>
      <p><strong>Ramal</strong></p>
    </td>
    <td>
    </td>
  </tr>
  <tr>
    <td>
      <p><strong>Nome</strong>*****</p>
    </td>
    <td>
    </td>
  </tr>
  <tr>
    <td>
      <p><strong>Sobrenome</strong>*****</p>
    </td>
    <td>
    </td>
  </tr>
  <tr>
    <td>
      <p><strong>Nome da mãe</strong></p>
    </td>
    <td>
    </td>
  </tr>
  <tr>
    <td>
      <p><strong>Idioma</strong>*****</p>
    </td>
    <td>
    </td>
  </tr>
  <tr>
    <td>
      <p><strong>Time Zone</strong>*</p>
    </td>
    <td>
    </td>
  </tr>
</table>

As informações com asterisco (\*) são obrigatórias.

***

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/MFwnbSAxo2pl_v7LqC7OU_image.png)


[title] Configurar serviço de alteração de senha
[path] Administração da Plataforma/Untitled/

A alternativa de alteração de senha do usuário é uma das possiblidades liberadas pelo sistema. Para configurar esta opção é necessário seguir os procedimentos aqui descritos.

:::hint{type="warning"}
**Atenção:**

Esta opção está disponível apenas para autenticação de contas manuais.
:::

## Antes de começar

- [x] É necessário previamente ter um serviço de correio eletrônico (SMTP) funcional, uma vez que o envio da senha é feito via e-mail.

## Procedimento

*1º Passo: Criar um modelo de e-mail com a finalidade de alteração de senha*

1. Acessar o menu principal `Sistema > Configurações > Modelo de e-mail;`
2. Criar o modelo de e-mail com o intuito de alterar a senha;

*2° Passo: Setar a parametrização referente ao serviço de alteração de senha*

1. Acessar o menu principal `Parametrização > Parâmetros CITSmart;`
2. Editar e salvar o parâmetro 116 atribuindo-lhe o valor numeral do ID gerado
   para o modelo de e-mail recém criado;

## O que fazer depois

Para testar o serviço de alteração de senha, acessar a página de login, clicar na opção “Esqueceu sua senha?”, informar um login de usuário local e apertar “Gravar”.


[title] Criar Ciclo no Calendário
[path] Administração da Plataforma/Criar Calendário/

Esta funcionalidade disponibiliza ações diversas, tais como, incluir, alterar e excluir os ciclos de período com data inicial e final a ser usado no controle financeiro.

Cada item cadastrado na opção "Atributos Financeiros" dentro de "Serviço de Negócio" de um Portfólio qualquer tem como um dos seus campos o Ciclo, um ciclo deverá ser selecionado em uma lista naquele formulário.

O 'Relatório de Lucratividade dos Atendimentos por Contrato' depende do cadastramento de ciclos.

## Procedimento

1. Acessar a funcionalidade através da navegação no menu principal `Cadastros Gerais > Gerência de Pessoal > Ciclo;`
2. Clicar em "**Novo**";
3. Preencher os campos disponibilizados;
4. Vale lembrar que:
   - Cada intervalo de datas deve ser único, mesmo com títulos diferentes e o
     &#x20;sistema cuida de impedir este tipo de redundância e inconsistência;
   - Não é permitido a exclusão do ciclo, caso este esteja vinculado a alguma
     &#x20;receita ou despesa do controle financeiro.
5. Clicar em "**Gravar**".


[title] Recomendações de Segurança
[path] Administração da Plataforma/

Para maior segurança do seu ambiente operacional, recomendamos:

- [ ] A utilização de autenticadores externos, por exemplo, LDAP ou servidores OAuth2. Caso sua empresa não possua, existem vários servidores de segurança padrão OAuth2 em provedores de nuvem que podem ser integrados facilmente a plataforma.&#x20;
- [ ] Evite a utilização de usuários locais da plataforma. A equipe de segurança detectou em diferentes versões da plataforma, a não-conformidade da funcionalidade perante padrões internacionais de segurança. Portanto, recomendamos a sua não utilização. Ela será descontinuada nas próximas versões, e como descrito no item 1, existem alternativas rápidas, acessíveis e mais seguras em substituição desta funcionalidade.
- [ ] Alinhado ao item 2, recomendamos que após as configurações iniciais, que todos os usuários locais sejam removidos da plataforma. Se houver dúvidas neste processo, favor acionar os canais de suporte.
- [ ] Recomendamos o uso de Captcha para instalações onde há acesso ou visibilidade por grande público externo, por exemplo, cidadãos. Esta funcionalidade pode ser ativada através de configurações da plataforma.
- [ ] Configurar um e-mail de alerta para quando exceder o número máximo de tentativas de autenticação com insucesso na plataforma. Esta funcionalidade pode ser ativada através de configurações da plataforma.
- [ ] Para ambientes operacionais on-premises, ou seja, hospedados em instalações de responsabilidade do cliente, recomendamos o uso de soluções de detecção de intrusão. Estas soluções contribuem para a segurança do ambiente operacional como um todo. Elas são externas a plataforma, precisam ser adquiridas, implementadas e mantidas pelo cliente.
- [ ] Ainda para ambientes operacionais on-premises, recomendamos que todos os componentes da infraestrutura que suportam a plataforma, dentre eles, o servidor de banco de dados e o servidor de aplicações, possuam rotinas regulares de alteração de senha.
- [ ] Também para ambientes operacionais on-premises, recomendamos que o servidor de aplicação onde a plataforma está implantada não tenha visibilidade direta na internet, ou seja, recomendamos a utilização de softwares intermediários (balanceadores, proxy reverso, ou outros) como porta de entrada para a plataforma, além de ocultar detalhes internos. Também é importante o uso adequado de estruturas de firewall.
- [ ] É importante a manutenção e controle total de todos os níveis de acesso dos usuários. Verifique as funções de todos os funcionários da organização para definir o acesso adequado a um componente ou funcionalidade específica. Assegure o acesso do usuário autorizado aos itens estritamente necessários ao desenvolvimento de suas tarefas. Tais recomendações valem para instalações on-premises, onde existem vários perfis com acesso à informações da infraestrutura, bem como acessos e funções dentro da plataforma. O fabricante não se responsabiliza por uso inadequado da gestão de acessos na plataforma, bem como na estrutura de componente.
- [ ] Solicitamos que qualquer situação de fragilidade de segurança identificada seja imediatamente encaminhada para nossa equipe de suporte ou um de nossos parceiros autorizados. Em nenhuma hipótese, faça qualquer tipo de manifestação antes da devida análise da equipe de segurança do fabricante, pois tais situações podem fazer parte do pacote de recomendações já existentes ou ser uma situação relacionada com proteções duplas ou adicionais. O CITSmart é uma marca global, com patentes registradas e aprovadas nos EUA, Europa, América, África e Asia, e, portanto, citações não autorizadas podem ser interpretadas como violação de direitos.

## Comunicação e Segurança de Interface

A comunicação entre os componentes da plataforma é criptografada por meio de certificados digitais, garantindo proteção contra ataques como Man-in-the-Middle. Todas as transações são autenticadas por meio de tokens JWT, assegurando integridade e rastreabilidade.

As interfaces da plataforma e os formulários Low-Code privados contam com mecanismos de proteção contra vulnerabilidades comuns, como injeção de SQL, cross-site scripting (XSS) e outras ameaças conhecidas, alinhando-se às boas práticas de segurança em aplicações web.

Além disso, a plataforma permite configurar métodos robustos de autenticação, como MFA (autenticação multifator), integração com Gov.br e federação de identidade, oferecendo camadas adicionais de controle de acesso e prevenção de uso indevido."

[title] Parâmetros
[path] Administração de Usuários, Grupos, Papéis e Parâmetros/

Na tela de "**Parâmetros"**, selecione as opções que permitem a visualização e realização dos ajustes necessários dos parâmetros no sistema:

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/jcxw1b-SRephH5wN_4awP_image8.png" size="42" width="318" height="286" caption="Hyper - Parâmetros" position="flex-start" signedSrc="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/jcxw1b-SRephH5wN_4awP_image8.png"}

Ao selecionar as opções aparece uma tabela com os seguintes itens: **Atributo, Descrição, Tipo e Valor.**

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/N-KOKVQGNWF-DaW5urpgc_image14.png)

Nessa mesma tela de Parâmetros, é possível tanto **exibir **como **esconder **um formulário, além de adicionar um novo parâmetro:

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/wRdngbUgvPRGmAKIRX3Wh_image11.png" size="44" width="371" height="100" caption="Botão Exibir formulário" position="center" signedSrc="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/wRdngbUgvPRGmAKIRX3Wh_image11.png"}

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/IFV8KbJ6cTaoQClBiOChq_image12.png" size="42" width="378" height="104" caption="Botão Esconder formulário" position="center" signedSrc="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/IFV8KbJ6cTaoQClBiOChq_image12.png"}

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/Tzfkz9uX5lW-e-s8RQFuO_image13.png" size="42" width="338" height="98" caption="Botão Adicionar parâmetro" position="center" signedSrc="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/Tzfkz9uX5lW-e-s8RQFuO_image13.png"}

***

1. Ao exibir o formulário, é possível editá-lo;
2. Preencha todos os campos requeridos e faça as alterações que deseja;
3. Clique em "**Salvar**" para prosseguir.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/YlW3CnZ4m1ZUtcbRC14BF_image.png)

As informações com asterisco (\*) são obrigatórias.


[title] Cadastrar conexões LDAP
[path] Administração da Plataforma/Untitled/

O LDAP (*Lightweight Directory Access Protocol* - "Protocolo de acesso aos diretórios leves") é um protocolo padrão que permite gerenciar diretórios, ou seja, acessar bancos de informações sobre os usuários de uma rede por meio de protocolos TCP/IP.

Você pode configurar o CITSmart para consultar bases de usuários disponíveis num serviço de diretório (Microsoft Active Directory ou open-LDAP) e, com isso, permitir que esses usuários se autentiquem no CITSmart usando suas credenciais, sem a necessidade de cadastrá-los manualmente (no CITSmart).

Atualmente, a leitura de dados em um servidor AD/LDAP se resume ao objeto "usuário". Dessa forma, você pode usar filtros para trazê-los para o CITSmart. Além disso, você pode utilizar a opção "Mapeamento de campos" para carregar informações de atributos (ex.: e-mail, telefone, localidade etc.).

Abaixo, é demonstrado um modelo de autenticação para clientes CITSmart Cloud que querem usar suas bases de diretórios locais (on-premises).

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/0wzpu3iT40-t-2HKYuSPJ_image.png)

## Antes de começar

- [x] Caso você queira configurar a sincronização automática de usuários é preciso criar um CRON para esta finalidade (Ex. sincronizar usuários todo dia às 00:00). Para criar um agendamento vá no menu Processos > Gerência de Evento > Horário.

## Procedimento

### Configurar conexão

1. Acessar o menu `Parametrização > Configuração LDAP;`
2. Clicar no botão "**Novo**";
3. Preencher os campos disponibilizados;
4. Verificar conectividade com a base, para isso, clicar em "**Testar Conexão**", se todos os dados estiverem corretos você receberá a mensagem "**Conexão realizada com sucesso**";
5. Clicar no botão "**Gravar**".

### Configurar Grupo DN e Apontamentos

Após ter configurado uma conexão com sucesso, você deverá adicionar preferências para a sincronização de usuários, neste caso, você deve indicar Grupos LDAP e Mapeamento de campos. No caso dos "Grupos LDAP", você tem a possibilidade de criar personalizações onde determinados usuários herdarão automaticamente permissões no CITSmart via link com Perfil de Acesso ou Grupo. Para o item "Mapeamento de campos", você pode configurar a aplicação para ler as informações de atributos do AD/LDAP e trazê-las para o cadastro do colaborador (ex.: ler o atributo "mail" e alimentar o campo "e-mail" do colaborador).

1. Para vincular novos grupos, clicar no botão "Adicionar" na área **Grupos LDAP** e informar os dados:
2. Para vincular atributos à campos, clicar no botão "Adicionar", na área **Mapeamento de campos**, digitar o nome do campo LDAP e selecionar o campo correspondente no CITSmart;
3. Clicar no botão "Gravar".

### Para usar o protocolo LDAPS

A utilização do protocolo LDAPS no CITSmart requer o certificado público do servidor AD/LDAP no repositório de certificados CA do JAVA (em seu servidor Wildfly). Assim, você deverá exportá-lo do servidor AD/LDAP e importá-lo em sua instância. Em caso de dúvidas acerca da importação de certificados no servidor de aplicação, consulte o documento de instalação.

## O que fazer depois

Para usar efetivamente a autenticação AD/LDAP é necessário, após o cadastro da conexão, alterar o parâmetro 22 e informar valor igual à "2", ou seja, indicar que o método padrão de autenticação no CITSmart é o AD/LDAP. De toda forma, a autenticação manual continuará funcionando normalmente.


[title] Visões Dinâmicas Baseadas em Papéis de Usuário
[path] Administração de Usuários, Grupos, Papéis e Parâmetros/Papéis do usuário/

A plataforma permite personalizar, de forma dinâmica, a exibição de painéis, relatórios e telas de acordo com o perfil do usuário, o nível de importância da sua função, os processos e subprocessos dos quais ele participa e os serviços associados ao seu papel.

Essa personalização é gerenciada por meio do módulo de Gestão de Papéis (Roles), onde é possível configurar:

- Papéis personalizados (roles) atribuíveis a usuários ou grupos;
- Atribuição de acessos granulares por tipo de sistema (como Low-Code, ITSM, Chatbot, etc);
- Exibição condicional de menus, submenus e funcionalidades conforme o papel designado;
- Diferenciação automática de experiências com base na jornada do usuário dentro da plataforma.

## O que são papéis?

Papéis são perfis funcionais que determinam o conjunto de permissões, interfaces e recursos visíveis para um usuário ou grupo. Um mesmo usuário pode possuir diferentes papéis em diferentes contextos, e os recursos da plataforma se adaptam dinamicamente a essas configurações.

:::hint{type="info"}
**Exemplo prático:**

Um gestor poderá visualizar dashboards estratégicos com métricas de desempenho e status de serviços; já um operador técnico verá telas com foco em tarefas operacionais e fluxos de execução.
:::

O módulo de Gestão de Pessoas da plataforma está preparado para associar papéis e permissões diretamente ao cadastro de usuários, permitindo que a definição de acessos e visões seja feita de forma centralizada e auditável.

No entanto, é recomendada a inclusão de documentação interna mais detalhada neste módulo, contemplando:

- Estrutura de papéis padrão da organização;
- Exemplos de uso por tipo de usuário;
- Diretrizes para criação e manutenção de novos papéis;
- Boas práticas para separação de funções e responsabilidades.


[title] Registrar o Formulário de Análise de Risco
[path] Administração da Plataforma/

Um formulário de análise de risco pode ser registrado para uso nas práticas de **Gerenciamento de **Problemas**, **Mudanças **e **Liberações.

## Procedimento

### Criar novo formulário

1. Para cadastrar um novo formulário de Análise de Risco, acesse a função através de `Cadastro Geral > Formulário de Análise > Formulário de Cadastro`;
2. Clique na opção **Cadastrar Formulário** e no botão **Novo;**
3. O sistema mostrará a tela do formulário Cadastro, com os seguintes campos:

<table columnWidths="318,318,212" selectedRows="12" selectedTable="false" isTableHeaderOn="true" selectedColumns="">
  <tr>
    <td align="center">
      <p><strong>Campo</strong></p>
    </td>
    <td align="center">
      <p><strong>Descrição</strong></p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p>Título</p>
    </td>
    <td align="center">
      <p>Identificação do formulário</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p>Processo</p>
    </td>
    <td align="center">
      <p>Vincula o formulário à uma prática específica</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p>Descrição</p>
    </td>
    <td align="center">
      <p>Descrição detalhada do formulário</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p>Perguntas</p>
    </td>
    <td align="center">
      <p>Campo para adicionar, editar ou remover as perguntas no formulário</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p>Adicionar</p>
    </td>
    <td align="center">
      <p>Adiciona uma nova pergunta</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p>Pergunta</p>
    </td>
    <td align="center">
      <p>Conteúdo da pergunta</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p>Valor (*)</p>
    </td>
    <td align="center">
      <p>Valores de entrada de 1 a 10</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p>Excluir</p>
    </td>
    <td align="center">
      <p>Exclui a pergunta selecionada</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p>Salvar</p>
    </td>
    <td align="center">
      <p>Salva o formulário</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p>Apagar</p>
    </td>
    <td align="center">
      <p>Apaga todos os campos</p>
    </td>
  </tr>
  <tr>
    <td align="center">
      <p>Voltar</p>
    </td>
    <td align="center">
      <p>Volta à tela de cadastro do formulário</p>
    </td>
  </tr>
</table>

(\*) Campos obrigatórios

### Editar Formulário de Análise de Risco

1. Para editar um formulário existente, acesse a função através de `Cadastro Geral > Formulário de Análise > Formulário de Cadastro`;
2. Nesta tela, é possível ver todos os formulários existentes. Escolha o formulário que deseja editar e clique no botão **Editar **no lado direito do título;
3. O sistema mostrará a mesma tela descrita acima, exceto que os campos já estarão preenchidos. É possível editar as informações nesses campos;
4. Na parte inferior da página, estarão disponíveis alguns novos botões: **Salvar**, **Copiar**, **Excluir**, **Visualizar**, **Limpar**, **Voltar**.


[title] STT, TTS e Inverter Cor
[path] Administração da Plataforma/

A plataforma oferece a função Fala para Texto e Texto para Fala nas pesquisas, além de um modo de cores invertidas:

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/_ELdTjQliD_sLCkpT3FRv_ba-ugwf8yjjv21k6yvzeiimage.png)

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/4ASupnd5baPJUZyD4BR0A_kzhwr-dpt76p6yjqg4ff-image.png)


[title] Autenticação Oauth2 usando Keycloak
[path] Administração da Plataforma/Untitled/

## Antes de começar

- [x] Possuir um servidor de autenticação com protocolo OAUTH2, exemplo Keycloak
- [x] Conectar o servidor de autenticação ao sistema
- [x] Após leitura de um novo usuário, o sistema atribuirá as seguintes permissões contidas nos seguintes parâmetros:

## Procedimento

1. Acessar o menu principal Parametrização > Método de Autenticação > Oauth2;
2. Será apresentado a tela de Método de Autenticação Oauth2 com duas opções "Filtros" e "Método de Autenticação";
3. A partir da versão 9.1.2.24 houve alterações na interface descritas abaixo;
4. A opção "**Filtros**" é uma tela de pesquisa com 4 opções:

| **Opção**       | **Descrição**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Tipo            | Onde será escolhido o tipo de autenticação. Existem dois tipos: Interno ou Externo.  Se a opção for externa o sistema poderá ter 3 tipos de autenticação: Interno, Oauth2 ou Ambos.  Se a opção estiver como ambos o sistema irá apresentar a tela de login com a área para: "autenticação", a opção de "esqueceu sua senha" e "acesse a sua conta" que poderá ser através do Google, Facebook ou Run2biz Keycloak.  Se a opção for ambos mas não tiver nenhum provedor externo cadastrado, o sistema não irá mostrar as opções de autenticação por Google, Facebook ou Run2biz Keycloak.  Se a opção for Oauth2 e não tiver um provedor cadastrado ele não irá mostrar a tela com vários provedores, mostrando direto a "tela de login da Run2biz". |
| Provider        | Onde será escolhido se será do tipo Google, Facebook ou outros                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| Domínio         | Informar o domínio da autenticação                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| Nome do cliente | Informar o nome do cliente da autenticação                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |

1. Após preencher as informações em "Filtros", caso exista algum cadastro com o campo informado, ele será apresentado na tabela exibida logo abaixo em "Método de Autenticação";
2. Caso não haja nenhum método autenticação cadastrado ou você deseja criar um novo, clicar em "Novo";
3. Ao clicar em "Novo" será apresentado a tela para cadastro de um novo método de autenticação com 2 abas para serem preenchidas: "Identificação" e "Mapeamento de Campos";
4. Para a aba de "Identificação", preencher:

| **Campo**            | **Descrição**                                                                                                                                                                                                                                                                                                                         |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Tipo de Autenticação | Existem duas opções para selecionar "Oauth2 - Interna" e "Oauth2"                                                                                                                                                                                                                                                                     |
| Provider             | Onde será escolhido se será do tipo "Google", "Facebook" ou "outros"  Se for do tipo Google ou Facebook só será preciso informar: o Id do Cliente e a Chave Secreta do Cliente;  Se for do tipo Outros será preciso informar: o Nome do cliente, o Domínio que deverá ser o mesmo cadastrado nas URLs de redirecionamento do provedor |
| Id do Cliente        | Onde deve ser informado o client id que foi cadastrado no servidor Oauth2                                                                                                                                                                                                                                                             |
| Tipo de concessão    | Identifica o grant de acesso concedido pelo provedor de autenticação. Geralmente contém o valor “password”                                                                                                                                                                                                                            |
| Url de Autenticação  | Onde deverá ser informado o caminho do servidor de autenticação Oauth2                                                                                                                                                                                                                                                                |
| Senha                | Onde deverá ser informado o client secret cadastrado no servidor Oauth2                                                                                                                                                                                                                                                               |
| Situação             | Onde poderá ser escolhido se a autenticação está ativa ou inativa.  Essa situação determina se o sistema vai iniciar o processo de sincronização de usuário                                                                                                                                                                           |
| Botão Gravar         | Salva o meio de autenticação                                                                                                                                                                                                                                                                                                          |
| Botão Excluir        | Apaga o meio de autenticação do banco de dados                                                                                                                                                                                                                                                                                        |
| Botão Limpar         | Limpa todos os campos                                                                                                                                                                                                                                                                                                                 |
| Botão Pesquisa       | Apresentado no topo da tela, que volta para a tela de pesquisa                                                                                                                                                                                                                                                                        |

1. Para a aba de "Mapeamento de Campos", preencher:

| **Campo**      | **Descrição**                                                  |
| -------------- | -------------------------------------------------------------- |
| Botão Gravar   | Salva os campos                                                |
| Botão Limpar   | Limpa todos os campos                                          |
| Botão Pesquisa | Apresentado no topo da tela, que volta para a tela de pesquisa |

- Essa aba permite o mapeamento de informações presentes no token de autenticação Oauth2.  Na tela são apresentadas duas colunas: a primeira coluna com o nome dos campos existentes no cadastro de usuário do Sistema e a segunda coluna com o nome do respectivo atributo do token Oauth2;
- As informações que podem ser mapeadas são: CPF, Telefone e Data de Nascimento;

1. Deverá ser configurada a URL de Retorno ao CITSmart através da Plataforma escolhida para autenticação externa.


[title] Cadastrar jornadas de trabalho
[path] Administração da Plataforma/Criar Calendário/

Esta funcionalidade disponibiliza ações diversas, tais como, incluir, alterar e excluir a jornada de trabalho da organização.

Módulo de Gestão de Jornada de Trabalho e Ausências, acessível via o menu de gestão de pessoas, permite definir a jornada de trabalho padrão de cada usuário e registrar seus períodos de ausência.

Este módulo integra-se com a ferramenta de gestão de pessoas para buscar e vincular automaticamente eventos e informações sobre jornadas já cadastradas, além de possibilitar a adição manual de novos períodos de ausência, como férias, licenças ou afastamentos.



## Procedimento

1. Acessar a funcionalidade através da navegação no menu principal `Cadastros Gerais > Gerência de Pessoal > Jornada de Trabalho;`
2. Preencher os campos disponibilizados;
3. Clicar em "**Gravar**".

## Gestão de Jornada de Trabalho e Períodos de Ausência

A plataforma permite definir e gerenciar a jornada de trabalho dos usuários, bem como identificar seus períodos de ausência, com base em eventos registrados na ferramenta corporativa de Gestão de Pessoas.

**Funcionalidades:**

- Definição da jornada padrão de trabalho para cada usuário (dias úteis, horários, turnos, etc.);
- Registro de ausências temporárias como férias, licenças, afastamentos ou folgas;
- Utilização dessas informações para:
- Cálculo preciso de SLA;
- Planejamento de escalas e alocação de chamados;
- Substituições automáticas ou manuais durante períodos de ausência.

A gestão da jornada contribui para maior precisão no acompanhamento de desempenho e no respeito aos limites operacionais dos colaboradores.

[title] Implementar regras de segurança de senha
[path] Administração da Plataforma/Untitled/

Esta funcionalidade retrata a configuração de senhas de uso do sistema,
disponibilizando maior nível de segurança com uso de diferentes caracteres.

:::hint{type="warning"}
**Atenção: **Esta política de segurança não está disponível para usuários LDAP.
:::

1. A partir da versão 9.2.1.0 ao atualizar a aplicação o sistema irá automaticamente configurar os seguintes parâmetros da tela de política de privacidade:
2. O sistema exigirá a alteração de senha no primeiro login, após uma atualização ou instalação;
3. Para atualizações, caso a política de senha já estiver habilitada, o sistema respeitará as configurações do cliente;
4. Caso a aplicação tenha sua versão alterada novamente no período inferior ao de 2 meses, setado na configuração inicial, o sistema não solicitará alteração de senha para os usuários locais que já tiverem realizado a alteração;
5. Essas configurações só serão válidas para usuários locais;
6. Ao habilitar a Política de Bloqueio de usuários, o administrador autoriza o bloqueio de usuários externos ou internos;
7. O uso de captcha altera a forma de realizar login, possuindo um método a mais de autenticação;
8. O administrador, caso habilite o bloqueio de usuários, poderá enviar e-mail aos responsáveis pela segurança do sistema.

## Procedimento

1. Acessar o menu principal `Sistema > Configurações > Política de Segurança;`
2. Habilitar a chave “**Habilitar política de senha**”;
3. No campo **Força da senha** o administrador deverá definir o número mínimo
   de caracteres da senha (valor mínimo de 8) e se a mesma conterá exigências
   de\:letras maiúsculas, minúsculas, números e símbolos;
4. Definir a quantidade de senhas anteriores na qual a nova não poderá ser
   igual, no limitador **A nova senha não pode ser igual às anteriores**;
5. Para novos usuários a troca de senha poderá ser definida ao clicar na chave
   “Exigir a troca de senha no primeiro login”
6. No campo **Duração da senha** definir o tempo de expiração da senha;
7. Para usuários que já estejam em operação é possível forçar a troca de senha
   da nova configuração, a partir do próximo login, clicar na chave “Forçar
   troca de senha no próximo login para todos os usuários”;

A partir da versão 9.1.2.23 ou 9.2.1.0 foram inseridos novos parâmetros:

1. Habilitar a chave “**Habilitar política de bloqueio de usuário**”:
   - Um símbolo com um i informando que: Será considerado tanto para logins internos quanto externos;
2. Habilitar a chave “Habilitar Captcha no Login”: Essa funcionalidade habilita uma verificação obrigatória para conexões de todos os usuários no sistema; durante o login;
3. No campo Bloqueio de usuário o administrador deverá definir o número mínimo de erros sucessivos de credenciais para bloqueio do usuário, esse bloqueio ocorre tanto para usuários internos quanto externos e o desbloqueio é realizado dentro do produto;
4. Definir o tempo de erros sucessivos de credenciais dos últimos minutos para bloqueio do usuário: Esse campo está ligado ao campo **“Bloquear usuário após erros sucessivos de credenciais”**, pois, o sistema precisa de um parâmetro de tempo para comparar a quantidade de erro em um determinado espaço de tempo e não considerar bloqueado o usuário caso não esteja dentro do prazo definido por ter alcançado o número de tentativas para bloqueio;
5. No campo Notificações deverá ser definido:
   1. Enviar alerta de segurança para o grupo: Informar o grupo para quem será enviado o e-mail de alerta em caso de usuário bloqueado por exceder as tentativas configuradas;
   2. Enviar alerta de segurança para os e-mails: Informa o e-mail de possíveis colaboradores que deverão ser alertados em caso de bloqueio de usuário. Os e-mails deverão ser separados por vírgula e sem nenhum espaço entre eles e sem espaço no final;

:::hint{type="warning"}
**Atenção: **Caso o sistema identifique o e-mail do usuário que teve o acesso bloqueado esse usuário também receberá e-mail de bloqueio. O modelo de e-mail de bloqueio não está disponível para alteração nessa versão.&#x20;
:::

1. Clicar em “**Salvar**”.


[title] Perfil
[path] Administração de Usuários, Grupos, Papéis e Parâmetros/

### Perfil do usuário logado

- Este sistema permite alterar os dados do perfil do usuário;
- Na tela Perfil, é possível alterar os dados pessoais a seguir: &#x20;

<table columnWidths="125,535,220" selectedRows="" selectedTable="false" isTableHeaderOn="true" selectedColumns="">
  <tr>
    <td>
      <p><strong>Campo</strong></p>
    </td>
    <td>
      <p><strong>Descrição</strong></p>
    </td>
  </tr>
  <tr>
    <td>
      <p><strong>E-mail</strong>*****</p>
    </td>
    <td>
    </td>
  </tr>
  <tr>
    <td>
      <p><strong>Telefone</strong></p>
    </td>
    <td>
    </td>
  </tr>
  <tr>
    <td>
      <p><strong>Ramal</strong></p>
    </td>
    <td>
    </td>
  </tr>
  <tr>
    <td>
      <p><strong>Nome</strong>*****</p>
    </td>
    <td>
    </td>
  </tr>
  <tr>
    <td>
      <p><strong>Sobrenome</strong>*****</p>
    </td>
    <td>
    </td>
  </tr>
  <tr>
    <td>
      <p><strong>Nome da mãe</strong></p>
    </td>
    <td>
    </td>
  </tr>
  <tr>
    <td>
      <p><strong>Idioma</strong>*****</p>
    </td>
    <td>
    </td>
  </tr>
  <tr>
    <td>
      <p><strong>Time Zone</strong>*</p>
    </td>
    <td>
    </td>
  </tr>
</table>

As informações com asterisco (\*) são obrigatórias.

***

1. Realize a edição do seu perfil;
2. Após concluir o processo, clique em "**Salvar alterações**".

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/lEvuBx-JYzrBMn9-J83fv_image.png)

Apresentação de Datas e Horários com Suporte a Fusos Horários
A plataforma exibe todas as datas e horários com base no fuso horário oficial de Brasília – DF – Brasil (UTC-3), assegurando consistência em registros, cálculos de prazos e acompanhamento de atividades.

Para usuários localizados em outras Unidades Federativas ou países com fusos horários diferentes, a plataforma oferece um recurso de conversão automática de fuso horário. Isso significa que os horários poderão ser apresentados de acordo com o horário local do usuário, promovendo maior clareza e precisão nas interações com o sistema.

:::hint{type="info"}
Nota sobre Timezone:

Embora a apresentação possa ser ajustada ao fuso horário do usuário, todos os registros e operações internas da plataforma seguem, por padrão, o horário de Brasília. Essa abordagem garante uniformidade nos cálculos de prazos e auditoria de eventos, conforme diretrizes definidas pela organização e/ou pelo cliente.
:::


[space] Administrator (/admin-en)

[title] Parametrization - Knowledge
[path] Platform Administration/Untitled/

The **Knowledge Management** Service system includes <font color="#3b9f0f">**tools to collect, store,
 manage, update, analyze and present all knowledge, information, and data**</font> that an
&#x20;IT service provider needs to manage the complete lifecycle of IT services.

The "**Knowledge**" parametrization must be performed to allow the execution/use of
&#x20;this process.    It may be possible to define the folder for tstorage of knowledge
&#x20;created from events, define the directory to store the description of the
&#x20;service request/incident response to be saved in the knowledge base, and other
&#x20;actions.

## Procedure

1. Access the functionality through the main menu `Parametrization > Knowledge
    Management`;
2. Set the values of the parameters (attributes);
3. Click on "**Save**";
4. The list below presents the "**Knowledge**" parameters and the purpose of each
   &#x20;one of them:

| **#**   | **Name**                                                                                                                                              | **Possible Values**                                                                             | **Purpose**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | **Additional Guidance**                                                                                                                                                                      |
| ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **78**  | Warn, in advance, the number of days remaining for the expiration of the knowledge. (Default: 90 days)                                                | Default: 90 days                                                                                | Define how many days in advance of the knowledge expiration date, the author and approver will be notified. When creating knowledge on the "Knowledge Base" screen, the date of expiration, that is, the date on which the knowledge will expire must be informed. It will be notified to the author and approver of the knowledge, in advance of N days (defined in this parameter) of the expiration date of the knowledge.                                                                                                                                                           | Not applicable                                                                                                                                                                               |
| **79**  | E-mail template ID to send folder creation notification                                                                                               |                                                                                                 | Enter the ID number of the folder creation notification email template. When creating a folder in the "Folder Registration" screen, the email template defined in this parameter will be used to send the folder creation notification. This notification will be sent to the group and/or user associated with the folder. This email template ID is set on the "E-mail Template" screen.                                                                                                                                                                                              | If you do not enter the identification number (ID) of the email template, the correct email may not be sent.                                                                                 |
| **80**  | E-mail template ID for sending folder update notification                                                                                             |                                                                                                 | Enter the identification number (ID) of the folder update notification e-mail template. When you change a folder in the "Folder Registration" screen, the e-mail template defined in this parameter will be used to send the folder update notification. This notification will be sent to the group and/or user associated with the folder. This email template ID is set on the "Email Template" screen.                                                                                                                                                                              | If you do not enter the identification number (ID) of the e-mail template, you may not send the correct e-mail.                                                                              |
| **81**  | E-mail template ID for sending folder delete notification                                                                                             |                                                                                                 | Enter the identification number (ID) of the folder deletion notification email template. When deleting a folder in the "Folder Registration" screen, the email template defined in this parameter will be used to send the folder delete notification. This notification will be sent to the group and/or user associated with the folder. This email template ID is set on the "E-mail Template" screen.                                                                                                                                                                               | If you do not enter the ID number of the E-mail Template, you may not send the correct e-mail.                                                                                               |
| **82**  | Email template ID for submitting knowledge creation notification                                                                                      | E.g.: 11                                                                                        | Enter the Knowledge Creation Notification E-mail Template (ID) number. By registering a knowledge on the "Knowledge Base" screen, the knowledge creation notification will be used to send the email template defined in this parameter. This notification will be sent to the group and/or user associated with the knowledge base. This email template ID is entered in the "E-mail Template" screen.                                                                                                                                                                                 | If you do not enter the identification number (ID) of the e-mail template, the correct e-mail may not be sent.                                                                               |
| **83**  | E-mail template ID for submitting knowledge update notification                                                                                       | E.g.: 12                                                                                        | Enter the Knowledge Update Notification email template number (ID). When updating knowledge on the "Knowledge Base" screen, the email template defined in this parameter will be used to send the knowledge update notification. This notification will be sent to the group and/or user associated with the knowledge base. This email template ID is set on the "Email Template" screen.                                                                                                                                                                                              | If you do not enter the r (ID) ID number of the e-mail template, you may not be able to send the correct email.                                                                              |
| **84**  | E-mail template ID for sending knowledge deletion notification                                                                                        | E.g.: 13                                                                                        | Enter the identification number (ID) of the knowledge deletion notification email template. By deleting a knowledge on the "Knowledge Base" screen, the email template defined in this parameter will be used to send the knowledge exclusion notification. This notification will be sent to the group and/or user associated with the knowledge base. This email template ID is set on the "Email Template" screen.                                                                                                                                                                   | If you do not enter the identification number (ID) of the e-mail template, the correct email may not be sent.                                                                                |
| **182** | Folder to save the Description and the solution to the service request in the Knowledge Base (Eg: Windows - Description\_Response\_To\_KnowledgeBase) | E.g.: Windows: C:\Citsmart\BaseConhecimento                                                     | Define the directory to store the response description of the service/incident request to be saved in the knowledge base. In the Service Request/Incident screen, the field "Save Solution/Response in the Knowledge Base" is displayed. When answering a service/incident request, and if you want to register the description of the Response Solution in the knowledge base, simply select the field and inform the title, done this, when save and forward the flow, the description of the solution response of the request will be stored in the folder defined in the parameter. | Not applicable                                                                                                                                                                               |
| **273** | Default folder for knowledge created from event occurrences                                                                                           |                                                                                                 | Define the folder for knowledge storage created from the event occurrences                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Not applicable                                                                                                                                                                               |
| **304** | URL of SOLR server (E.g.: http: // localhost: 8983 / solr / collection\_name)                                                                         | E.g.: [http://localhost:8983/solr/collection\_name](http://localhost:8983/solr/collection_name) | Configure the URL of the Apache Solr collection that will be used by <font color="#3b9f0f">**CITSmart** </font>to index the knowledge                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Not applicable                                                                                                                                                                               |
| **305** | Apache Tika server URL (Eg: [http://localhost](http://localhost): 9998/tika)                                                                          | E.g.: [http://localhost:9998/tika](http://localhost:9998/tika)                                  | Configure the Apache Tika URL to make OCRs of knowledge attachments at the time of indexing                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Not applicable                                                                                                                                                                               |
| **308** | Total items to be imported at a time when indexing documents in Solr (Eg: 1000)                                                                       | E.g.: 1.000                                                                                     | Configure how many items will be indexed at a time in Apache Solr                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Not applicable                                                                                                                                                                               |
| **313** | The ID of the folder to register Knowledge created by the end-user                                                                                    |                                                                                                 | Default folder to register Knowledge created by the end-user                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Not applicable                                                                                                                                                                               |
| **314** | Source ID of Knowledge created by the end-user                                                                                                        |                                                                                                 | Default origin that will be used in the knowledge created by the end-user                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Not applicable                                                                                                                                                                               |
| **332** | Enable synchronization with the index server                                                                                                          | Y or N                                                                                          | When knowledge indexing is performed in Solr, either by deleting, updating, or creating new knowledge. If Solr is stopped and this parameter is active, automatic synchronization with Solr is started until Solr is reactivated. As soon as it back to work, all the knowledge that is pending indexing is indexed, and the automatic synchronization is finished.                                                                                                                                                                                                                     | Not applicable                                                                                                                                                                               |
| **333** | Enter the interval in minutes to sync the knowledge with the index server                                                                             | Between 0 and 59 minutes. Default is empty.                                                     | This parameter will define the time in minutes that the knowledge will be under revision.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | To know the maximum amount of time to input, check [this link](http://www.quartz-scheduler.org/documentation/quartz-2.3.0/tutorials/crontrigger.html), go to "Format" then "Allowed Values". |
| **354** | URL of the logo (Knowledge Portal) (Eg: /citsmart/imagens/logo/logo-header-icon.png)                                                                  | E.g.: /citsmart/imagens/logo/logo-header-icon.png                                               | Parameter of use restricted to <font color="#3b9f0f">**CITSmart** </font>**Corporation&#x20;**&#x69;ndicates the URL of the Knowledge Portal logo.                                                                                                                                                                                                                                                                                                                                                                                                                                      | Not applicable                                                                                                                                                                               |
| **355** | Header Background URL (Knowledge Portal) (Eg: /citsmart/images/background-header.png)                                                                 | E.g.:/Citsmart/imagens/background-header.png                                                    | The parameter that customizes the appearance of the Knowledge Portal.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Not applicable                                                                                                                                                                               |
| **356** | Background color of the header (Portal of Knowledge) (Default: #e6e6e6)                                                                               | E.g.: #e6e6e6                                                                                   | The parameter that customizes the appearance of the Knowledge Portal.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Not applicable                                                                                                                                                                               |
| **357** | Header Font Color (Knowledge Portal) (Default: #333333)                                                                                               | E.g.: #333333                                                                                   | The parameter that customizes the appearance of the Knowledge Portal.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Not applicable                                                                                                                                                                               |
| **358** | Enable knowledge base search ranking (Eg: Y or N - Default 'N')                                                                                       | Y or N                                                                                          | Failure to configure this information, or the assignment of "N", prevents the creation of management reports that deal with the subject.                                                                                                                                                                                                                                                                                                                                                                                                                                                | Not applicable                                                                                                                                                                               |
| **359** | Store search registries for how many days? (Eg: 30)                                                                                                   | E.g.: 30                                                                                        | Failure to configure this limiter can accumulate excessive amounts of data unnecessarily over time, causing slowness in application processing, especially in reports that handle the subject.                                                                                                                                                                                                                                                                                                                                                                                          | Not applicable                                                                                                                                                                               |
| **360** | Font color of favorites (Knowledge Portal) (Default: #f1a21f)                                                                                         | E.g..: #f1a21f                                                                                  | Customize the appearance of the "Favorites" frame that is on the Home screen of both the Knowledge Portal and the User's Guide.                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Not applicable                                                                                                                                                                               |
| **361** | Font color of likes (Knowledge Portal) (Default: # 6c8ebe)                                                                                            | E.g..: #6c8ebe                                                                                  | Customize the appearance of the "Liked" frame that is on the Home screen of both the Knowledge Portal and the User's Guide.                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Not applicable                                                                                                                                                                               |
| **362** | Color of the indicated source (Portal of Knowledge) (Default: #67c15e)                                                                                | E.g..: #67c15e                                                                                  | Customize the appearance of the "Indicated" frame that is on the Knowledge Portal home screen.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Not applicable                                                                                                                                                                               |
| **363** | Help URL (Eg: [https://help.citsmartcloud.com/citsmart](https://help.citsmartcloud.com/citsmart))                                                     | E.g.: [https://help..citsmartcloud.com/citsmart](https://help..citsmartcloud.com/citsmart)      | The parameter is used to enter the URL of the User's Guide                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Not applicable                                                                                                                                                                               |
| **364** | Logo URL (User Guide) (Eg: /citsmart/images/logo/logo-header-icon.png)                                                                                | E.g..: /citsmart/imagens/background-header.png                                                  | Parameter of restricted use to <font color="#3b9f0f">**CITSmart** </font>**Corporation&#x20;**&#x69;ndicates the URL of the User Guide logo.                                                                                                                                                                                                                                                                                                                                                                                                                                            | Not applicable                                                                                                                                                                               |
| **365** | Header Background URL (User Guide) (Eg: /citsmart/images/background-header.png)                                                                       | E.g..: /citsmart/imagens/background-header.png                                                  | Parameter of restricted use to <font color="#3b9f0f">**CITSmart** </font>**Corporation** indicates the URL of the background image of the User's Guide.                                                                                                                                                                                                                                                                                                                                                                                                                                 | Not applicable                                                                                                                                                                               |
| **366** | Background color of the header (User Guide) (Default: #e6e6e6)                                                                                        | E.g..: #e6e6e6                                                                                  | Parameter of restricted use to <font color="#3b9f0f">**CITSmart** </font>**Corporation**, customize the appearance of the User's Guide.                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Not applicable                                                                                                                                                                               |
| **367** | Header Font Color (User's Guide) (Default: #333333)                                                                                                   | E.g..: #333333                                                                                  | Parameter of restricted use to <font color="#3b9f0f">**CITSmart** </font>**Corporation**, customize the appearance of the User's Guide.                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Not applicable                                                                                                                                                                               |
| **368** | URL for partner login (Eg: [https://example.com/citsmart](https://example.com/citsmart))                                                              | E.g..: [https://example.com/citsmart](https://example.com/citsmart)                             | Parameter of restricted use to <font color="#3b9f0f">**CITSmart** </font>**Corporation**, customize the link to which the solution is directed when clicking on "I am an Agent" in the User's Guide.                                                                                                                                                                                                                                                                                                                                                                                    | Not applicable                                                                                                                                                                               |
| **410** | Display title of Knowledge Portal (Default: Y)                                                                                                        |                                                                                                 | Informs if it is to display the title of knowledge on the Knowledge Base Search screen                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Not applicable                                                                                                                                                                               |

**Table 1 - Parameters List**


[title] Registering Questionnaire
[path] Platform Administration/Untitled/

This feature provides a variety of actions, such as <font color="#3b9f0f">**including, changing, and deleting questionnaires** </font>(forms) in a very generic, multi-purpose, and easy to be used in other system routines. It is possible to import a completed questionnaire.&#x20;

To ensure greater productivity, the "**Copy from another questionnaire**" button allows the Manager to import Questionnaires built in both the previous form and the current form.

## Before getting started

- [x] It is necessary to register previously the questionnaire category.

## Procedure

1. Access the functionality through the main menu `System > Visions and
    Metadata > Questionnaire > Register`;
2. Click on "**New**";
3. Complete the fields available;
4. Create the questions;
5. Click on "**Save**";
6. The "**Export**" allows saving in a disk an electronic file with all
   &#x20;characteristics of the questionnaire selected.


[title] Registering Ticket Template
[path] Platform Administration/Untitled/

This feature allows the <font color="#3b9f0f">**manager to add, change and delete ticket templates**</font>.

## Before getting started

- [x] The Questionnaire type ticket/change template requires the previous registration of a questionnaire;
- [x] The Neuro type ticket/change template requires the previous registration of the Neuro form.

## Procedure

1. Access the functionality through the main menu `System > Ticket/Change Template`;
2. Click on "**New**";
3. The type of template selected will define the fields to fill:
4. Identify the template using the "**Identification of the service request template**" field;
5. Name the template using the "**Template name**" field;
6. Select the checkboxes available for the templates:
   - Applicable to Ticket;
   - Enable targeting;
   - Enable status;
   - Enable configuration item;
   - Enable change;
   - Enable problem;
   - Enable solution;
   - Enable related requests;
   - Enable the save and continue button.

:::hint{type="info"}
🖊 ***Note*****:&#x20;**&#x57;hen selecting the "**Applicable to Ticket**" checkbox, the user understands that the type of template is applicable only to the ticket.
:::

:::hint{type="info"}
🖊 ***Note*****:&#x20;**&#x57;hen selecting the "**Neuro**" Template Type, the new checkbox type field will be displayed with the text: "**Applicable to Change**". When selecting this field the user understands that the type of template is applicable only to the Change.
:::

:::hint{type="warning"}
⚠️ ***Attention*****!**

In the case of "**Neuro**" type templates, the user can inform that the template will be used for both tickets and changes.
:::


[title] CITSmart auto-login -SSO
[path] Platform Administration/Authentication/

**Branchs**:

- Sso (itsm)
- Spnego 1.0 (artifactory)

## Create user AD

1. Access "**create user**" in **Users and Computers of the Active Directory**, as in the image below:

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/KGsXn-6wBwmSdUi5cCyNm_image.png "Figure 1 - Creating User")

2\. Create a password: 

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/YUtZMoWF-ojYhhwAMLaY2_image.png" size="62" width="371" height="275" caption="Figure 2 - Password" position="flex-start" showCaption="true"}

3\. Click on the right side of the mouse, in the button user/properties:

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/jLtoL4WP6dDzuUv0ja-Y9_image.png" size="84" width="468" height="479" caption="Figure 3 - Button User/Properties" position="center" showCaption="true"}

4\. Select the "**This account supports 256-bit encryption**" option, apply it, and check "**OK**", as below:

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/JOu5gDwFrmN1neoUDz17f_image.png" size="78" width="410" height="478" caption="Figure 4 - Configuring Account" position="center" showCaption="true"}

5\. Open the **ADSI Edit**. Then, connect in the **AD**, click on users and locate the user newly created, as below:

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/rrI29X1MIYQW62Q3O5B9i_image.png "Figure 5 - Verifying User")

6\. Right-click and select the Properties option. Then, search for the **ServicePrincipalName** (SPN);

7\. Add **HTTP/hom-itsm.centralit.com.br**, click on "**OK**", as in the image below:

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/RoZvWo2z7AfJd1Rw5QE27_image.png "Figure 6 - Adding Value")

8\. Open the CMD as Administrator and put the following commands. Remember that the first sets the SPN and the second creates the Keytab (which will be used in the Wildfly):

- setspn -s HTTP/hom-itsm.centralit.com.br citsmart2
- ktpass / princ HTTP/hom-itsm.centralit.com.br /mapuser citsmart2  /pass
  central\@123 /ptype KRB5\_NT\_Principal/outcitsmart2.keytab /crypto ALL

9\. Making the steps above, the AD will be configured. 

## Configure the Wildfly server

1. Copy the **war** generated from the branch **sso**;
2. Copy the file krb5.conf (validate the information according to the AD) to the folder standalone/configuration (wildfly):

````sh
    ```sh
    [libdefaults]
    default_tkt_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 rc4-hmac
    default_tgs_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 rc4-hmac
    permitted_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 rc4-hmac
    [realms]
    ```
    
    ```sh
    citgosrv004.cit.local  = {
    kdc = citsmartsrv.citsmartsrv.bigdata-team.com
    default_domain = citsmartsrv.citsmartsrv.bigdata-team.com }     
    ```
    
    ```sh
    [domain_realm]
    .citsmartsrv.citsmartsrv.bigdata-team.com = citsmartsrv.citsmartsrv.bigdata-team.com
    ```
````

Copy the file login.conf (validate the information according to the AD) to the folder standalone / configuration (wildfly):

````sh
    ```sh
    custom-client {
    com.sun.security.auth.module.Krb5LoginModule required
    storeKey=true
    useKeyTab=true
    keyTab="file:///opt/wildfly-12.0.0.Final/standalone/configuration/lightkeytab.keytab"
    principal=HTTP/light-desenvolvimento.citsmartcloud.com\@CITSMARTSRV.BIGDATA-TEAM.COM;
    };
    ```
````

1. Copy the lightkeytab.keytab file (generated by the command in AD) to the standalone / configuration (wildfly) folder;
2. Fix standalone.xlm by adding the following information:

In **\\\<system-properties>**

````java
    ```java
    \<property name="sun.security.krb5.debug" value="true"/\>
    \<property name="java.security.krb5.kdc" value="CITSMARTSRV.BIGDATA-TEAM.COM"/\>
    \<property name="java.security.krb5.realm"value="CITSMARTSRV.BIGDATA-TEAM.COM"/\>
    \<property name="java.security.krb5.conf"value="/opt/wildfly-12.0.0.Final/standalone/configuration/krb5.conf"/\>
    \<property name="java.security.auth.login.config"value="/opt/wildfly-12.0.0.Final/standalone/configuration/login.conf"/\>
    \<property name="krb.keyTab"value="/opt/wildfly-12.0.0.Final/standalone/configuration/lightkeytab.keytab"/\>
    \<property name="krb.principal"value="HTTP/light-desenvolvimento.citsmartcloud.com\@CITSMARTSRV.BIGDATA-TEAM.COM"/\>
    ```
````

In **\\\<security-domains>**

````java
    ```java
    \<security-domain name="spnego-server"\>
    \<authentication\>
    \<login-module code="com.sun.security.auth.module.Krb5LoginModule"flag="required"\>
    \<module-option name="storeKey" value="true"/\>
    \<module-option name="useKeyTab" value="true"/\>
    \<module-option name="keyTab" value="\${krb.keyTab}"/\>
    \<module-option name="principal" value="\${krb.principal}"/\>
    \<module-option name="isInitiator" value="false"/\>
    \</login-module\>
    \</authentication\>
    \</security-domain\>
    \<security-domain name="SPNEGO" cache-type="default"\>
    \<authentication\>
    \<login-module code="Kerberos" flag="required"\>
    \<module-option name="storeKey" value="true"/\>
    \<module-option name="refreshKrb5Config" value="true"/\>
    \<module-option name="useKeyTab" value="true"/\>
    \<module-option name="doNotPrompt" value="true"/\>
    \</login-module\>
    \</authentication\>
    \</security-domain\>
    ```
````

1. If you do not have changed the jar of the policy of JAVA (JCE - Java Cryptography Extension), download the files and put in jdk/jre/lib/security/policy/limited and jdk/jre/lib/security/policy/unlimited;
2. Import (synchronize) users of LDAP in ITSM.

:::hint{type="warning"}
⚠️ ***Attention*****!&#x20;**

The DN Alias should be the same as the network domain (example: CIT\user), than the DN Alias = CIT, as below:
:::

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/MxstjGn2domoCyJEGjEY__image.png "Figure 7 - Defining DN")

:::hint{type="warning"}
⚠️ ***Attention*****!&#x20;**

It is recommended to read the following support materials: [https://ss64.com/nt/setspn.html](https://ss64.com/nt/setspn.html) and [http://spnego.sourceforge.net/](http://spnego.sourceforge.net/) 
:::


[title] Managing Content Indexing
[path] Platform Administration/Untitled/

****<font color="#3b9f0f">**CITSmart** </font>uses **Apache SOLR** to index content created in the Knowledge Management and makes it available in the Knowledge Portal search system.

## What to do before

In order for Knowledge Indexing to work correctly, it is necessary:

- [x] Install the **Apache SOLR&#x20;**&#x63;omponent as shown in the installation manual.

## Parametrizing the Indexing Service

1. Access the main menu `Parametrization > CITSmart Parameters`;
2. Configure **parameter 304** by entering the URL of the SOLR component;

:::hint{type="info"}
**http\://localhost:8983/solr/collection\_name**
:::

3\. Configure **parameter 308** stating the number of items to be indexed each time;

4\. Configure **parameter 332** stating whether synchronization with the Indexing server is active;

5\. Configure **parameter 333** informing the interval in minutes to synchronize knowledge with the index server - Accepted values between **1&#x20;**&#x61;nd **59**;

6\. Access the main menu `System > Settings > Knowledge Management` (Indexing) and click on "**Update the index server**".

## Managing Content

1. Access the main menu `System > Settings > Knowledge Management` (Indexing);
2. To index the available knowledge, click on "**Index Knowledge Base**", or to remove the knowledge already indexed, click on "**Remove Knowledge Base Indexing**".


[title] Configuring CITSmart Environment
[path] Platform Administration/

The **Environment Configuration** functionality is intended to <font color="#3b9f0f">**facilitate an
 intervention**</font> (correction) in the <font color="#3b9f0f">**environment** </font>(server) and to <font color="#3b9f0f">**change the logos of
 the system**</font>.

You can change the system logo by checking the **Environment Information**, and also by downloading
&#x20;the **JBoss Log**.

## Procedure

1. Access the main menu `System > Settings > Environment Configuration`;
2. To change one of the images (start logo, portal logo, system logo, and report logo), click on "**Select an Image**";

:::hint{type="warning"}
 📌 ***IMPORTANT!&#x20;***

The **Logo&#x20;**&#x66;ield system will obey **parameter 387**.
:::

3\. Click on the pointed box to drag a file or make the upload;

4\. Click on "**Save**";

5\. To download the Jboss Log, click on "**Download**".


[title] Unlocking Users 
[path] Platform Administration/Untitled/

In this document, we will see the necessary requirements to unlock a user.

## Before getting started

- [x] The administrator must have enabled the User Blocking rule, contained in the Security Policy record;
- [x] The user must be prevented from accessing the application due to the use of the user blocking rule.

## Procedure

From <font color="#3b9f0f">**version 9.1.2.24**</font>, new security rules have been added which led to the inclusion of this functionality.

1. Access the main menu `System > Security > Blocked Users`;
2. When accessing the functionality, a screen with the field will appear: **User name - Text type field to search for the blocked users by name**;
3. In addition to this field, a list will appear with the following information:

| **List**          | **Description**                                                         |
| ----------------- | ----------------------------------------------------------------------- |
| **Blocked users** | Displays the context/login information of the user who has been blocked |
| **Blocking date** | Displays the date/time information that the system performed the block  |

4\. Here, there is also the "**Delete**" action, which allows the removal of the user's immediate block.


[title] Customizing Fields 
[path] Platform Administration/

## Customizing Labels

This functionality is intended to **change the names of labels** within the <font color="#3b9f0f">**CITSmart** </font>**Platform**,
&#x20;allowing greater customization of it. It is necessary for the user to have some knowledge about programming.

## Procedure

1. Access the functionality through the main menu `System > Settings > System
    Customization`;
2. Complete the fields available;
3. Click on "**Save**".

## What to do next

After saving the change, access the functionality that was made and the label change
&#x20;to verification.


[title] Configuring Okta in CITSmart
[path] Platform Administration/Authentication/

This **Authentication Method** allows you to <font color="#3b9f0f">**use the Okta features to authenticate users of your organization**</font> in a <font color="#3b9f0f">**CITSmart** </font>instance. This document explains the steps in configuring this method. To learn more about Okta, visit **okta.com**

## Before getting started

- [x] The configuration of this solution is a multi-phase process;
- [x] The first step is the creation of an Okta account.

## Procedure

### 1st Step: Create an Okta account:

1. Access the site:  [https://www.okta.com](https://www.okta.com);
2. Click on "**Try Okta**" and then on "**Sign up today**";
3. Enter the essential data (e-mail, name, and last name);

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/O9NuxXolfVblTkBCuXX1X_image.png" size="56" width="420" height="448" position="flex-start" showCaption="false"}

4\. Click on "**Get Started**" to complete the operation. Then check the registered e-mail (which will send an access link), access the account with the temporary password sent, and change it for greater data security;

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/dX-7TtrDLtY4DFetvepsE_image.png)



### 2nd Step: Created <font color="#3b9f0f">**CITSmart** </font>application within Okta:

1. After completing the previous step, connect to Okta with your newly created account;
2. Click on the "**Applications**" tab and then on "**Add Application**";

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/tmlB2UZlSYNUz89zHBRDa_image.png)

3\. Click on "**Create New App**";

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/X98F1ZKkRljB2-sI2-XAi_image.png)

4\. Select the option "**SAML 2.0**" and then click on "**Create**";

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/YTWQPerNEnTGRJNVlV8dR_image.png)

5\. In the "**App name**" field, add the name of the application, and soon after, it is necessary to click on "**Next**";

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/y4uK-NUDnsdbnROtitYUa_image.png)

6\. Configure the application path and then click on Next:

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/BgGPXAOyzLq7p5kGmlE5K_image.png)

:::hint{type="warning"}
⚠️ ***Attention*****!&#x20;**

In the "**Single sign-on URL**" and "**Audience URI** (SP Entity ID)" fields, the URL addresses on which the <font color="#3b9f0f">**CITSmart** </font>Application will be executed should be included.
:::

7\. Select the options "**I'm an Okta customer adding an internal app**" and "**This is an internal app that we have created**". Then, click on "**Finish**".

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/sQSidAuXb0tyRjudBPm1L_image.png)



### 3rd Step: Assign users to Okta's <font color="#3b9f0f">**CITSmart** </font>application:

1. After completing the previous step, you need to click on the "`Applications > Applications`" tab and then on "**Assign Applications**" and choose the filter called "**People**";

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/43IjKVMoYzWmRRzkBroXM_image.png)

2\. Then you can choose the user who will be allowed to access the application that is being created. Click on "**Assign**" and then, to finish, click on "**Done**";

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/MlYMjeMwBlJJDBySJqqnr_image.png)



### 4th Step: Include required information in the <font color="#3b9f0f">**CITSmart** </font>configured on Okta:

1. You will need to configure some data in the WildFly directory. Access the directory, open the "**/standalone/configuration**" folder and change the file "**citsmart.cfg**".

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/yW6F8BUGbwxMJ-6196XfT_image.png)

2\. When accessing the file, you need to include this information in the file "**citsmart.cfg**":

a) In the line, ***SAML2\_HOST*****&#xA0;and&#xA0;*****SAML2\_PORT*** includes the address and port of the <font color="#3b9f0f">**CITSmart** </font>application;

b) In the line, ***SAML2\_METADATA*** includes the SAML metadata of the Okta. This data can be obtained by following the instructions below:

- Access the <font color="#3b9f0f">**CITSmart** </font>application in Okta, click the "`Applications > Applications`" tab, and then on "**Sign On**". When you click on the "**Identity Provider metadata**" option, a new tab will be available to the metadata, copy the URL of the browser and insert in the property **SAML2\_METADATA**;

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/qUdRiZxVOVMtF3FF7NLyD_oktaimg12.png)



c) In the line, ***OKTA\_URL*** includes the main URL in the Okta account.

d) In the line, ***OKTA\_TOKEN*** includes the token to access through API. To get this token, follow these steps:

- Access the <font color="#3b9f0f">**CITSmart** </font>application in Okta, select the "`Security > API`" menu, and then click on "**Create Token**". Name the token and click on "**Create Token**". It will be presented the token value to be copied on the line quoted above.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/w1jjUuUrrzeoUMwVIZzht_image.png)

e) In the line, ***OKTA\_DOMAIN\_ALIAS*** includes the domain of users coming from Okta.


### 5th Step: Synchronize Okta user on <font color="#3b9f0f">**CITSmart**</font>:

1. Within <font color="#3b9f0f">**CITSmart**</font>, access the "**Okta Config**" menu and register a new configuration by clicking on "**New**";

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/C_bujQhXea5hlMptUVTtw_image.png)

2\. Complete the fields with the necessary information:

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/ZLSVN201YkrH1J-e1pUbZ_image.png)

- **Description:&#x20;**&#x69;ntroduce a definition of this new setting Okta;
- **Alias:&#x20;**&#x69;nclude the user domain that will be saved to the database. Example: okta\\[administrador@citsmart.com](mailto\:administrador@citsmart.com);
- **URL domain:&#x20;**&#x73;hould include the same value (URL) that was entered in the line ***OKTA\_URL*** in the "**citsmart.cfg**" file;
- **Token API:&#x20;**&#x69;nclude the same value of the token inserted in the line ***OKTA\_TOKEN*** in the file "**citsmart.cfg**";
- **Group:&#x20;**&#x69;nsert the ID of the group in which the synchronized and registered user will belong in <font color="#3b9f0f">**CITSmart**</font>;
- **Access Profile:&#x20;**&#x69;nsert the profile ID in which the synchronized and registered user will belong in <font color="#3b9f0f">**CITSmart**</font>;
- **Application ID:&#x20;**&#x69;nclude the application ID. This information can be retrieved from the Okta URL, as shown below:

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/alW2e5yejrMEff5yikkD6_image.png)

3\. Click on "**Save**" and then on "**Synchronize users**" to perform the operation.



### 6th Step: Configure the Logout:

1. Since Okta does not have a logout screen, in **parameter 377** of <font color="#3b9f0f">**CITSmart**</font>, we can insert some page address to redirect the user to the end of the session;
2. Set up the logout link also at the address **(**`Admin > Settings > Customization > Sign-Out-Page`**)**, then check the "**Use the custom sign-out page**" option. Therefore, enter the URL ([https://localhost:8443/citsmart/saml/logout](https://localhost:8443/citsmart/saml/logout)) with the appropriate adaptations (host and port), according to the image below:

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/Nyq6VemtIcLInYZdsweSg_image.png)

:::hint{type="info"}
🖊 ***Note*****:&#x20;**&#x57;hen ***logout*** in <font color="#3b9f0f">**CITSmart**</font>, do not ***log out*****&#xA0;**&#x66;rom the Okta, since users may have other applications in the Okta session. In contrast, if you do Okta *logout*, the user session in <font color="#3b9f0f">**CITSmart**</font> will be removed.
:::

## What to do next

Once the Okta integration with <font color="#3b9f0f">**CITSmart** </font>is complete, some <font color="#3b9f0f">**CITSmart** </font>parameters can be configured to better customize this integration. They are:

- The **parameter 445** (Name of the Administrator group in Okta) allows you to choose the administrator group in the Okta solution. If the user belongs to this chosen group, he/she will have the access profile defined as administrator. If this is not the case, your access profile will be the default profile defined by **parameter 39**.


[title] Parametrization - Chat
[path] Platform Administration/Untitled/

The notion of "**Chat**" is used to <font color="#3b9f0f">**allude to the exchange of written messages of
 instantaneous form**</font>. In this case, it allows the **user to have direct contact
&#x20;with the system attendant in order to solve doubts, make requests, and others**.&#x20;

The
&#x20;parameters of this application allow activating the chat, setting the default
&#x20;agreement for call opening, and adjusting the default group and other actions.

## Procedure

1. Access the functionality through the main menu `Parametrization > Chat`;
2. Set the value of the parameters (attributes);
3. Click on "**Save**";
4. The list below presents the parameter of the functionality "**Chat**" and the
   &#x20;purpose of each one of them.

| **#**   | **Name**                                                       | **Possible Values** | **Purpose**                                                            | **Additional Guidance** |
| ------- | -------------------------------------------------------------- | ------------------- | ---------------------------------------------------------------------- | ----------------------- |
| **118** | Default Contract ID for call opening.                          |                     | Default contract ID to open calls                                      | Not applicable          |
| **315** | The ID of the requests created by the chat                     |                     | Source ID of requests created by chat                                  | Not applicable          |
| **316** | Activate Chat                                                  | Y or N              | Activate Chat                                                          | Not applicable          |
| **317** | Activity ID of requests created by chat                        |                     | Activity ID of requests created by chat                                | Not applicable          |
| **388** | Default user ID (External request)                             |                     | Default user ID (External request)                                     | Not applicable          |
| **389** | Default group ID (External request)                            |                     | Default group ID (External request)                                    | Not applicable          |
| **390** | Default unit ID                                                |                     | Unit ID that will be assigned to the user registered in the profile    | Not applicable          |
| **447** | Email template ID for notification of new messages in the chat |                     | E-mail template ID for notification of new messages in the chat        | Not applicable          |
| **299** | Ticket - Activate message exchange                             | Y or N              | Activate a chat icon next to the ticket number in the attendance queue | Not applicable          |
| **448** | Text editor used by the application                            |                     | Text editor used by the application                                    | Not applicable          |

**Table 1 - Parameters List**


[title] Users
[path] Initial Settings/Users, Groups, Roles/

## User Registration

This tool allows you to register users.

### Procedure

1. To create a user, click the "**Create**" button **㊉** on the right side;
2. Fill in all required fields:

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/isq7SFXw2Ca3rBG0Uw7j6_image.png)

1. Select whether the user is active or not using the "**Active?**" button;
2. This registration automatically displays the groups assigned to the user. This data comes from the Keycloak connection with the site:

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/Mi9sXq0BGlc2lAY-b83qB_image.png)

1. To register a new user, click the "**Save and Continue**" button.

## Enabling and Disabling Users

This tool allows you to enable and disable users.

### Procedure

1. To disable an enabled user, click the desired checkbox ☐ located in the first column from left to right (next to the user's name), and in the top navigation bar on the right side, select "🗑 **Disable**".
2. To enable a disabled user, click the desired checkbox ☐ located in the first column from left to right (next to the user's name), and in the top navigation bar on the right side, select "🗑 **Enable**".

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/DWyT_dLOo6h3VkUBUWHOR_image.png)

1. You can edit a user by clicking the 🖊 icon located in the last column on the right.
2. To delete a user, click the 🗑 icon located in the last column on the right.

## Profile

This system allows you to modify user profile data.

On the Profile screen, you can update the following personal details:

- **Email**\*
- **Phone**
- **Extension**
- **First Name**\*
- **Last Name**\*
- **Mother's Name**
- **Language**\*
- **Time Zone**\*

Fields marked with an asterisk (\*) are mandatory.

***

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/k4QxxgUgQJVTefn3fAhHv_image.png)

***

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/k4QxxgUgQJVTefn3fAhHv_image.png)


[title] Log's and Auditing
[path] Platform Administration/


[title] Log's and Auditing 
[path] Platform Administration/Untitled/

## Checking System Log

This functionality is intended to <font color="#3b9f0f">**check the system log for the audit trail**</font>.

:::hint{type="info"}
🖊 ***Note*****:&#x20;**&#x49;f the table names are not updated, access the <font color="#3b9f0f">**CITSmart** </font>**Parameters&#x20;**&#x66;unctionality and define the name of the database used in the **parameter&#x20;**'**DB - name of the database SCHEMA**'. After that, access the **Load Metadata** functionality and update all tables.
:::

## Procedure

1. Access the functionality through the main menu `System >
    Audit Trail > System Log`;
2. Complete the filters available;
3. Click on the "**Search**" button to display the system log according to the data entered;
4. To generate the system log report, click on the "**Generate Report**" button.


[title] System Parameters
[path] Platform Administration/


[title] Creating Cycle in Calendar
[path] Platform Administration/Untitled/

This feature provides a variety of actions, such as <font color="#3b9f0f">**including, changing, and
 deleting the period cycle with start and end date**</font>, to be used in the financial
&#x20;control.

Each item registered in the "**Financial Attributes**" option within the "**Business
&#x20;Service**" of any Portfolio, has as a field the Cycle. A Cycle should be selected
&#x20;in a list in that form.

The "**Profitability Reporting of Contracts**" depends on the registration of
&#x20;cycles.

## Procedure

1. Access the main menu `General Registration > Personnel Management > Cycle`;
2. Click on "**New**";
3. Complete all mandatory fields;
4. It is worth remembering that:
   - Each date range should be unique, even with different titles. The system takes care to prevent this type of redundancy and inconsistency;
   - The exclusion of the cycle is not allowed if it is linked to some revenue or expense of the financial control.
5. Click on "**Save**".


[title] Parametrization - Problem
[path] Platform Administration/Untitled/

**Problem Management** manages the <font color="#3b9f0f">**lifecycle of all problems from the first
 identification**</font>, through to investigation, documentation, and eventual removal.

The "**Problem**" parametrization must be made to allow the execution/use of this
&#x20;process. It may be possible to define the default flow name for the problem, to
&#x20;define whether the responsible party and the executing group will be notified
&#x20;when the time to work around the problem has expired, among other viable
&#x20;actions.

## Procedure

1. Access the functionality through the main menu `Parametrization > Problem
    Management`;
2. Define the value of the parameters (attributes);
3. Click on "**Save**";
4. The list below presents the "**Problem**" parameters and the purpose of each one
   &#x20;of them:

| **#**   | **Name**                                                                                                                                              | **Possible Values**  | **Purpose**                                                                                                                                                                                                                                                                                                                                                                                              | **Additional Guidance**                                                                                         |
| ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| **123** | Default flow name for problem                                                                                                                         | E.g.: DefaultProblem | Enter default flow name for Problem. If no flow is informed of the problem, the flow will be established by the system (as reported in the parameter value). This flow is defined in the "Flow Design" screen.                                                                                                                                                                                           | Not applicable                                                                                                  |
| **124** | The ID of the E-mail template that will be sent to the requester when a problem is created                                                            |                      | Enter the identification number (ID) of the problem-creating notification email template. When registering a problem in the "Problem Registration" screen, the defined email template will be used to send the problem creation notification. Where this notification will be sent to the requester. This email template ID is entered in the "Email Template" screen.                                   | If you do not enter the identification number (ID) of the email template, you may not send the correct email.   |
| **125** | The ID of the E-mail template that will be sent to the requester when a problem is in progress                                                        |                      | Enter the identification number (ID) of the notification e-mail template for the progress of the problem. When performing the problem on the "Problem" screen, the defined email template will be used to send the notification of the progress of the problem. Where this notification will be sent to the requester. This email template ID is entered in the "Email Template" screen.                 | If you do not enter the identification number (ID) of the e-mail template, you may not send the correct email.  |
| **126** | The ID of the E-mail template that will be sent to the requester when a problem is finalized                                                          |                      | Enter the identification number (ID) of the problem-finishing notification email template. At the end of the problem on the "Problem" screen, the defined email template will be used to send the problem-finishing notification. Where this notification will be sent to the requester. This email template ID is entered in the "Email Template" screen.                                               | If you do not enter the identification number (ID) of the e-mail template, you may not send the correct email.  |
| **127** | The ID of the e-mail template that will be sent to the target group when escalating a problem                                                         |                      | Enter the identification number (ID) of the notification e-mail template for the escalation of the problem. When escalating a problem for the group in the "Problem Management" screen, the defined email template will be used to send the problem escalation notification. Where this notification will be sent to the target group. This email template ID is entered in the "Email Template" screen. | If you do not enter the identification number (ID) of the e-mail template, you may not send the correct e-mail. |
| **128** | The ID of the e-mail template that will be sent to the responsible party and executor group when the time to workaround/resolve a problem has expired |                      | Enter the expiration notification email template ID number of the deadline to workaround/solve the problem. When the time to workaround/solve a problem has expired, the notice of expiration of the time to workaround/solve the problem, as defined, will be sent to the responsible and executing group. This email template ID is entered in the "Email Template" screen.                            | If you do not enter the identification number (ID) of the email template, you may not send the correct email.   |
| **129** | Notify the responsible party and the executing group when the solution/workaround of the problem expires (Eg: Y or N - Default: 'Y'                   | Y or N (Default: Y)  | Define whether the responsible and the executing group will be notified when the time to workaround/solve the problem has expired.                                                                                                                                                                                                                                                                       | If you do not enter the parameter value, the system default value will be used: "Y" (Yes).                      |
| **194** | Enable problem escalation defined in the escalation rules? (Eg: Y or N - Default 'N')                                                                 | Y or N (Default: N)  | Define whether the problem escalation determined in the escalation rules is enabled. This problem escalation rule is defined in the "Escalation Rules and Automatic Notifications" screen.                                                                                                                                                                                                               | If you do not enter the parameter value, the system default value will be set: "N" (No).                        |

**Table 1 - Parameters List**


[title] Parametrization - Change
[path] Platform Administration/Untitled/

**Change Management** is the process responsible for <font color="#3b9f0f">**evaluating, coordinating and
 deciding on making proposed changes**</font> to the Services and/or Configuration Items
&#x20;(CIs).&#x20;

The parameters to be configured allow adjusting the notification
&#x20;submission, inform the e-mail templates to escalate the request for change,
&#x20;inform the name of the application flows and define the type of voting used in
&#x20;the change advisory board, among other actions.

## Procedure

1. Access the functionality through the main menu `Parametrization > Change
    Management`;
2. Define the values for the parameters (attributes);
3. Click on "**Save**";
4. The list below presents the parameters of "**Change**" and their purpose:

| **#**   | **Name**                                                                                            | **Possible Values** | **Purpose**                                                                                                                                                                                                                                                                                                                                                                             | **Additional Guidance**                                                                                                        |
| ------- | --------------------------------------------------------------------------------------------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| **47**  | Default flow name for changes                                                                       | E.g.: RequestChange | Enter the name of the "default" request for change flow. <br />This flow is defined in the "Flow Design" screen.                                                                                                                                                                                                                                                                        | Not applicable                                                                                                                 |
| **120** | E-mail template ID for sending notification to the Change Advisory Board                            | E.g.: 29            | Inform the notification email template (ID) for the Change Advisory Board. The e-mail template defined in this parameter will be used to send the request for change notifications. This notice will be sent to the Change Advisory Board. <br />This email template ID is set on the "E-mail Template" screen.                                                                         | If you do not enter the ID number of the email template, you may not be able to send the correct e-mail.                       |
| **122** | The ID of the email template that will be sent to the target group when escalating a change request | E.g.: 30            | Enter the request for change escalation email template identification number (ID). When escalating a request for change, a notification is sent to the target group, according to the template defined in this parameter. <br />This email template ID is set on the "E-mail Template" screen.                                                                                          | If you do not enter the identification number (ID) of the email template, you may not send the correct email.                  |
| **133** | Email template ID for sending scheduled meeting notification                                        | E.g.: 39            | Enter the identification number (ID) of the scheduled meeting notification email template. When scheduling a meeting for a request for change on the Change Management screen, an e-mail will be sent to the responsible party, notifying them about the meeting schedule. <br />This e-mail template ID is set on the "E-mail Template" screen.                                        | If you do not enter the identification number (ID) of the e-mail template, you may not send the correct e-mail.                |
| **146** | Questionnaire template ID                                                                           | E.g.: 13            | Enter the identification number (ID) of the template for the checklist for the changes and release. <br />This template ID is set on the "Service Request Template" screen.                                                                                                                                                                                                             | Not applicable                                                                                                                 |
| **193** | Enable the escalation of changes defined in the escalation rules? (Eg: Y or N - Default 'N')        | Y or N (Default: N) | Define if the escalation of changes determined in the escalation rules will be enabled. This change escalation rule is defined in the "Escalation Rules and Automatic Notifications" screen.                                                                                                                                                                                            | If you do not enter the parameter value, the system default value will be set: "N" (No).                                       |
| **268** | Email template ID to notify when finishing the change                                               |                     | Enter the identification number (ID) of the e-mail template used to notify the closure of a request for change. When closing a request for change, the "Change Management" screen will be used to send the notification of closure defined in the email template. This notification will be sent to the requester. <br />This email template ID is set on the "E-mail Template" screen. | If you do not enter the identification number (ID) of the email template, you may not send the correct email to the requester. |
| **279** | Normal flow name for changes                                                                        |                     | Enter the name of the normal request for change flow. <br />This flow is defined in the "Flow Design" screen.                                                                                                                                                                                                                                                                           | If you do not enter the parameter value, an error message appears on the Request for Change screen.                            |
| **280** | Name of emergency flow for changes                                                                  |                     | Enter the name of the emergency request for change flow. <br />This flow is defined in the "Flow Design" screen.                                                                                                                                                                                                                                                                        | If you do not enter the parameter value, an error message appears on the Request for Change screen.                            |
| 303     | RFC voting using the rule of absolute majority (50% + 1) (Values: "Y" or "N" Default: "Y")          | Y or N (Default: Y) | Define which type of voting will be used in the request for change: absolute majority rule or all vote.<br />                                                                                                                                                                                                                                                                           | Not applicable                                                                                                                 |

**Table 1 - Parameters List**


[title] Registering Unit
[path] Platform Administration/Untitled/

This functionality is intended to **register the unities where the employees are placed**.

This feature provides a variety of actions, such as <font color="#3b9f0f">**including, changing, and deleting a unit**</font>.

## Before getting started

To register the unit, it is necessary:

- [x] To load the countries and configuration of
  &#x20;**parameters 254** and **331**.

## Procedure

1. Access the functionality through the main menu `General Registration >
    Personnel Management > Unit`;
2. Complete the fields necessary;
3. Click on "**Save**".

:::hint{type="info"}
🖊 ***Note*****:** In this version, you can edit the information in the "**Latitude**" and "**Longitude**"
&#x20;fields.
:::


[title] Parametrization - Release
[path] Platform Administration/Untitled/

**Release Management** is the process <font color="#3b9f0f">**responsible for planning, scheduling and
 controlling the construction, testing, and deployment of releases**</font>, and for
&#x20;<font color="#3b9f0f">**delivering new functionality required by the business**</font> while protecting the
&#x20;integrity of existing services.&#x20;

The "**Release**" parametrization must be
&#x20;performed to allow the execution/use of this process, and it may be possible to
&#x20;define whether notifications will be sent to the requester for the execution of
&#x20;the services/incidents request flows, for example.

## Procedure

1. Access the functionality through the main menu `Parametrization > Release
   Management`;
2. Set the values of parameters (attributes);
3. Click on "**Save**";
4. The list below represents the parameters of "**Release**" and the purpose of
   &#x20;each one of them:

| **#**   | **Name**                  | **Possible Values** | **Purpose**                                                                                                                                                           | **Additional Guidance** |
| ------- | ------------------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| **146** | Questionnaire template ID | E.g.: 13            | Enter the identification number (ID) of the template for the checklist for the changes and release. This template ID is set on the "Service Request Template" screen. | Not applicable          |

**Table 1 - Parameters List**


[title] Authentication
[path] Platform Administration/

Natively, the following types of platform authentication are possible: **local, LDAP / AD, SSO, and Okta**.

| **Fields**               | **Description**                                                                                                                                                                                          |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Local**                | This is the standard method of accessing the platform, where users are registered in the tool database.                                                                                                  |
| **LDAP/AD**              | Authentication is the most common form of access to the platform and is geared towards the end customer scenario. It allows you to authenticate to the system without the need to create users manually. |
| **Sing Single On - SSO** | This is an alternative to automatic login on the platform. However, it is necessary to have an infrastructure oriented to this service.                                                                  |
| **Okta**                 | With this method, it is possible to use an available user base in Okta and use it for authentication in a <font color="#3b9f0f">**CITSmart** </font>instance.                                            |


[title] Importing Employee
[path] Platform Administration/Untitled/

This functionality allows you to <font color="#3b9f0f">**import the employees' spreadsheet**</font>.

## Before getting started

- [x] The import requires to have registered the spreadsheet to import the employee.

## Procedure

1. Access the functionality through the main menu `System > Data Importing and
    Loading > Employee Load`;
2. Click on the "**Import**" tab;
3. Click on "**Choose File**" and select the file that has to be in the "**.xls**" or "**.xlsx**" format
   ;
4. Click on "**Import**".


[title] Initial Settings
[path] /


[title] Configuring Service to change Password
[path] Platform Administration/Untitled/

The user's password change alternative is one of the possibilities released by the system.                 To configure this option, you need to follow the procedures described here.

:::hint{type="warning"}
⚠️ ***Attention*****! &#x20;**

This option is only available for manual account authentication.
:::

## Before getting started

- [x] It is necessary to first have a functional e-mail service (SMTP) since the sending of the password is done via e-mail.

## Procedure

### <font color="#3b9f0f">*1st Step*</font>: Create an e-mail template for changing the password

1. Access the main menu `System > Settings > E-mail Template`;
2. Create an e-mail template to change the password;

:::hint{type="warning"}
⚠️ ***Attention*****!&#x20;**

In order for the user to receive the new access information, it's necessary to use, in the e-mail message, the key ‘\{NOVASENHA}’ (for example, the key for the "New password"). In addition, you can also send the user login using the key ‘\{LOGIN}’ (for example, the key about the“Login”).
:::

### **<font color="#3b9f0f">*2nd Step*</font>: Set the parameter about the service to change the password

1. Access the main menu `Parametrization > CITSmart Parameters`;
2. Edit and save **parameter 116** by assigning the numeric value of the ID generated for the newly created e-mail template;

## What to do next

To test the service to change the password, access the login page, click on "**Forgot your password?**", enter a local user login, and click on "**Save**".


[title] Configuring Mandatory Fields
[path] Platform Administration/Untitled/

By configuring the mandatory fields, the manager will choose which fields will be mandatory for users to complete when contacting the attendants. Its purpose is to <font color="#3b9f0f">**get the necessary information from the requesters to solve their requests**</font>.

## Procedure

1. Access the main menu `System >
    Settings > Pages - Field configuration`;
2. The pages with the possibility of choice of the required fields will be presented.
   &#x20;Here are they: **Problem Management** and **Request/Incident Management**.

### <font color="#3b9f0f">Configure fields of the "Problem" functionality</font>

*Deciding to use mandatory fields, it's possible to demand certain information to be
&#x20;registered when creating a problem.*

1. After accessing the home page of the functionality, choose the "**Problem**"
   &#x20;option and click on "**Edit**";
2. Select the fields you want to make mandatory:

| **Field**                                             | **Mandatory                          &#x20;** |
| ----------------------------------------------------- | --------------------------------------------- |
| **Catalog                                    &#x20;** | :ballot\_box\_with\_check:                    |
| **Service Category**                                  | :ballot\_box\_with\_check:                    |
| **Service**                                           | :ballot\_box\_with\_check:                    |
| **Phone**                                             | :ballot\_box\_with\_check:                    |
| **Extension**                                         | :ballot\_box\_with\_check:                    |
| **Physical Location**                                 | :ballot\_box\_with\_check:                    |
| **Observation**                                       | :ballot\_box\_with\_check:                    |
| **Executor Group**                                    | :ballot\_box\_with\_check:                    |
| **Solve/Workaround till**                             | :ballot\_box\_with\_check:                    |

3\. Click on "**Save**".

### <font color="#3b9f0f">Configure fields of "Ticket Management" functionality</font>

*Deciding to use mandatory fields, it is possible to demand certain information to be
&#x20;registered when creating a request/incident.*

1. After accessing the home page of the functionality, choose the "**Incident/Request Management**" option
   &#x20;and click on "**Edit**";
2. Select the fields you want to make mandatory:

| **Field**                                     | **Mandatory                          &#x20;** |
| --------------------------------------------- | --------------------------------------------- |
| **Phone                              &#x20;** | :ballot\_box\_with\_check:                    |
| **E-mail**                                    | :ballot\_box\_with\_check:                    |
| **Unit**                                      | :ballot\_box\_with\_check:                    |
| **Physical Location**                         | :ballot\_box\_with\_check:                    |
| **Contact's Origin**                          | :ballot\_box\_with\_check:                    |

:::hint{type="info"}
🖊 ***Note*****:&#x20;**&#x54;he **parameters 65** (that identifies the default call origin ID of the service request) and **105&#x20;**(identifies the source ID that will default when creating a new incident) set up automatically a contact source when the user registers a ticket.&#x20;



Therefore, if the "**Contact Origin**" field, on the ticket screen, is ***not*****&#xA0;mandatory**, but, there is an indication in the previous parameters, the field will be completed automatically.
:::

3\. Click on "**Save**"


[title] Registering Spreadsheet Template for Employee Import
[path] Platform Administration/Untitled/

This functionality was implemented to allow <font color="#3b9f0f">**direct loading in the employees' tables**</font>. The system warns in case some mandatory field is not completed and doesn't read the file till its maintenance.

## Procedure

1. Access the functionality through the main menu `System > Data Importing and
    Loading > Employee Load`;
2. Click on the "**Spreadsheet Template to Import**" tab;
3. Complete the fields available and consider that in the mandatory fields, the system does not allow deleting the "**XLS**" that will be generated to be imputed
   &#x20;the information;
4. The "**Active**" field allows to be put in XLS all the employees as actives;
5. To generate the spreadsheet template in "**.xls**", click on "**Generate Template
   &#x20;.xls**";
6. To generate the spreadsheet template in "**.xlsx**", click on "**Generate Template
   &#x20;.xlsx**".


[title] Profile
[path] Initial Settings/Users, Groups, Roles/

### Logged-in User Profile

- This system allows you to modify user profile data;
- On the Profile screen, you can update the following personal details:

| **Field**                | **Description** |
| ------------------------ | --------------- |
| **Email**\*\*\*\*\*      |                 |
| **Phone**                |                 |
| **Extension**            |                 |
| **First Name**\*\*\*\*\* |                 |
| **Last Name**\*\*\*\*\*  |                 |
| **Mother's Name**        |                 |
| **Language**\*\*\*\*\*   |                 |
| **Time Zone**\*          |                 |

Fields marked with an asterisk (\*) are mandatory.

***

1. Edit your profile information;
2. After completing the changes, click "**Save Changes**".

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/IK8ASIl6oCpsM0ilx-k4l_image.png)

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/IK8ASIl6oCpsM0ilx-k4l_image.png)


[title] Navigation and User Interface
[path] Initial Settings/

The user interface is the easiest way for the user to interact with
&#x20;applications and information in a <font color="#3b9f0f">**CITSmart**</font>**&#x20;instance**.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/qRG23iw4qNv_Bpfm4ZPFr_image.png "Figure 1 – CITSmart Homepage Screen")

**1. Banner frame:** in the internal area of the system, the taskbar contains navigation items and tools, such as,

- The main menu, with all the <font color="#3b9f0f">**CITSmart**</font> functionalities;
- Buttons with VoIP integration;
- The virtual assistant <font color="#3b9f0f">**Anuva**</font>;&#x20;
- Information about the user login;
- Environment version; and also&#x20;
- About language change.

**2. Navigation in applications**:&#x20;

- Access to <font color="#3b9f0f">**CITSmart**</font>**'s 16 certified processes**,
  &#x20;
- Basic registration functionalities,&#x20;
- Creation, and emission of reports,&#x20;
- Parameters,
  &#x20;
- Access to <font color="#3b9f0f">**CITSmart**</font> **Neuro&#x20;**(application engine);
- And other platform management functionalities
  .

**3.  User panel**:&#x20;

- Determines the layout of the user panel presentation (Smart
  &#x20;Decision) available on the <font color="#3b9f0f">**CITSmart**</font> **Platform&#x20;**&#x68;ome page.&#x20;
- It allows putting
  &#x20;quick accesses such as links, reports, and widgets.

## User Interface Tour

### Banner Frame

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/9_T_w0vBCsq81UJrb2uoQ_image.png" size="74" width="917" height="58" caption="Figure 2 - Banner Frame" position="center" showCaption="true"}

The taskbar, located at the top, contains navigation items and tools:

- ****<font color="#3b9f0f">**1**</font>: Main navigation menu, contains all the processes and functionalities of <font color="#3b9f0f">**CITSmart**</font>;
- ****<font color="#3b9f0f">**2**</font>: When browsing the system and wanting to return to the home screen, click on "**Home**";
- ****<font color="#3b9f0f">**3**</font>: System notifications to the user, which is evidenced by the quantity existing;
- ****<font color="#3b9f0f">**4**</font>: **VOIP&#x20;**&#x63;all service;
- ****<font color="#3b9f0f">**5**</font>: Attendance chat (visible to attendance group users);
- ****<font color="#3b9f0f">**6**</font>: Shortcut to the main system applications;
- ****<font color="#3b9f0f">**7**</font>: User information, as well as providing system language change, manage
  &#x20;chat status, <font color="#3b9f0f">**CITSmart**</font> support media, and installed version environment
  &#x20;data.

### Navigation in Applications

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/rOuGiAXRJM2wJjoZWR6mx_image.png" size="40" width="301" height="494" caption="Figure 3 – Main Menu Screen" position="center" showCaption="true"}

By clicking on the main navigation menu, you will see all the features that <font color="#3b9f0f">**CITSmart**</font> provides.

- ****<font color="#3b9f0f">**1**</font>: Search bar of the functionality, accessible via a menu;
- ****<font color="#3b9f0f">**2**</font>: Access to settings for maintaining flows;
- ****<font color="#3b9f0f">**3**</font>: It has all **16 certified Processes** of the <font color="#3b9f0f">**CITSmart**</font> Platform;
- ****<font color="#3b9f0f">**4**</font>: Integrated management has functionalities that help in the management
  &#x20;of the processes;
- ****<font color="#3b9f0f">**5**</font>: It presents basic registers to start <font color="#3b9f0f">**CITSmart**</font>, such as users, location, besides
  &#x20;being able to register and edit menus within the system;
- ****<font color="#3b9f0f">**6**</font>: It has data to manage the **Experience Center**, which is a portal customizable
  &#x20;for the user;
- ****<font color="#3b9f0f">**7**</font>: Provides several types of reports that the system can generate with the
  &#x20;data of the main functionalities, therefore, making possible the information
  &#x20;to be better analyzed, besides allowing the creation of customized reports;
- ****<font color="#3b9f0f">**8**</font>: Configuration of access and permission in the system;
- ****<font color="#3b9f0f">**9**</font>: Configuration of the application and system parameters;
- ****<font color="#3b9f0f">**10**</font>: Functionalities to manage the <font color="#3b9f0f">**CITSmart**</font>**&#x20;Platform**;
- ****<font color="#3b9f0f">**11**</font>: Access to <font color="#3b9f0f">**CITSmart**</font> **Neuro&#x20;**(the engine of applications).

### User Panel (Smart Decision)

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/0XefbZzzGIEXQ7HFFR_eZ_image.png "Figure 4 – Smart Decision Screen")

Customization of the **User Panel** (**Smart Decision**) displayed on the system
&#x20;homepage, where you can place quick accesses such as links, reports, and widgets.

- ****<font color="#3b9f0f">**1**</font>: Vertical bar containing the registered panels. Bar items can be shifted to fit the user's need;
- ****<font color="#3b9f0f">**2**</font>: Items to edit a dashboard;
- ****<font color="#3b9f0f">**3**</font>: Items to edit widgets in a dashboard;
- ****<font color="#3b9f0f">**4**</font>: Example of widget of type "link", that can be internal or external.


[title] User Roles
[path] Initial Settings/Users, Groups, Roles/



This area allows the creation of roles (access profiles) that users or user groups will have for a specific environment or application (lowcode, ITSM, CHATBOT, etc.), as well as menus, submenus, and access permissions.

Roles are also considered user profiles that define which access rights can be granted to specific individuals or groups.

The tool features a search screen and displays documents from the identity manager.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/4b1I5g9uiiwQ95Pmx4U-D_image.png)

You can select multiple documents simultaneously and delete them. This tool also allows editing and removing specific documents.

Additionally, you can create new roles that will also be included in Keycloak.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/d_qCmdUSC3LhpuXx1l2UL_image.png)

Fields marked with an asterisk (\*) are mandatory.

***

To save the new document, click "**Save**", or to save and continue editing, click "**Save and continue**".

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/yk6sD6zfDReEB9yG_fTRw_image.png)

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/yk6sD6zfDReEB9yG_fTRw_image.png)


[title] Running Script
[path] Platform Administration/Untitled/

The purpose is to <font color="#3b9f0f">**maintain the script's registration to its execution in the system**</font>.

## Procedure

1. Access the functionality through the main menu `System > Database > Scripts  > Run Scripts`;
2. Click on "**Scripts Registration**";
3. Complete the fields to a new script;
4. Click on "**Save**";
5. To run the script that is being created, click on the "**Search Scripts**" tab;
6. Complete one of the fields available;
7. Click on "**Search**";
8. Select the script you want;
9. It will be presented on the "**Script Registration**" tab;
10. Click on "**Run**".


[title] Platform Administration
[path] /


[title] Configuring E-mail Template
[path] Platform Administration/Untitled/

This functionality is intended to <font color="#3b9f0f">**create e-mail templates for the system
 notifications**</font>.

The **Knowledge&#x20;**&#x61;llows the **attachment of images, and links, among other visual
&#x20;resources**, making the sharing of e-mails more interactive.

## Procedure

1. Access the functionality through the main menu `System > Settings > E-mail
    Template`;
2. Complete the fields available;
3. Click on "**Save**".


[title] Automatic Action via E-mail
[path] Platform Administration/Automation/

This functionality is intended to **program the automatic opening of a service
&#x20;request&#x20;**&#x74;hrough e-mail.

This feature provides a variety of actions, such as <font color="#3b9f0f">**including, changing, and deleting an automatic action via e-mail**</font>.

## Before getting started

The automatic creation via e-mail requires:

- [x] The previous registration of the
  &#x20;automatic action of incident/request/procedure.

## Procedure

1. Access the functionality through the main menu `System > Settings >
    Automatic Action Setting Via E-mail`;
2. Complete the fields available;
3. Click on "**Save**".


[title] Language and Region
[path] Platform Administration/

This functionality is intended to <font color="#3b9f0f">**set up the default language of the system**</font>.

## Procedure

1. Access the functionality through the main menu `Parameterization > CITSmart Parameter`;
2. Search **parameter 66**, set **value EN** for **English**, **ES&#x20;**&#x66;or **Spanish,&#x20;**&#x6F;r **PT&#x20;**&#x66;or **Portuguese**;
3. Click on "**Save**".

:::hint{type="info"}
🖊 ***Note*****:** ***Always keep the system in English*****:&#x20;**

1\. Access the functionality through the main menu `Parameterization > CITSmart parameter`;  &#x20;
2\. Search **parameter 275**;&#x20;
3\. Select "**Yes**"; &#x20;
4\. Click on "**Save**".
:::


[title] Parametrization - VoIP
[path] Platform Administration/Untitled/

**VoIP&#x20;**(**Voice over Internet Protocol**) is human conversation routing using the
&#x20;<font color="#3b9f0f">**Internet or any other Internet protocol-based computer network, making voice
 transmission, one of the services supported by the data network**</font>.&#x20;

The "**VoIP**"
&#x20;parameters allow **setting the password for communication with the server**,
&#x20;informing the standard communication extension for VoIP connection, among other
&#x20;feasible actions in order to configure the use of VoIP in <font color="#3b9f0f">**CITSmart**</font>.

## Procedure

1. Access the functionality through the main menu `Parametrization > Voip`;
2. Set the value of the parameters (attributes);
3. Click on "**Save**";
4. The list below presents the "**VoIP**" parameters and the purpose of each one of
   &#x20;them:

| **#**   | **Name**                                                                                                                                     | **Possible Values**                                                                                                                                                                                                                                                                  | **Purpose**                                                                                                          | What's the impact on the system?                                                                                                                             |
| ------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **323** | VOIP - Enable Voip (Values: "Y" or "N" Default: "N")                                                                                         | Y or N (Default: N)                                                                                                                                                                                                                                                                  | Activate VoIP resources.                                                                                             | Once you have activated a headphone icon, it will be available in the footer of the Smart Portal so that the user can contact the HelpDesk via phone (VoIP). |
| **324** | VOIP - Server (Eg.: [https://127.0.0.1:8089/janus](https://127.0.0.1:8089/janus))                                                            | E.g.: [https://127.0.0.1:8089/janus](https://127.0.0.1:8089/janus)                                                                                                                                                                                                                   | Server SIP Address (SIP = Session Initiation Protocol) for VoIP usage                                                | Not applicable                                                                                                                                               |
| **325** | VOIP - Domain (Eg: 127.0.0.1)                                                                                                                | E.g.: 127.0.0.1                                                                                                                                                                                                                                                                      | VoIP - Domain (e.g..: 127.0.0.1)                                                                                     | Not applicable                                                                                                                                               |
| **326** | VOIP - Port (Eg.: 5061)                                                                                                                      | E.g.: 5061                                                                                                                                                                                                                                                                           | Inform the port where the voice information goes through                                                             | Not applicable                                                                                                                                               |
| **327** | VOIP - User (Eg: goofy, replaces SIP Identifier when informed)                                                                               | E.g.: goofy, replaces the SIP Identifier when informed                                                                                                                                                                                                                               | Identification to the communication with the server                                                                  | Not applicable                                                                                                                                               |
| **328** | VOIP - Password                                                                                                                              | Not applied                                                                                                                                                                                                                                                                          | Password to the communication with the server                                                                        | Not applicable                                                                                                                                               |
| **329** | VOIP - Extension (Eg.: 0800)                                                                                                                 | E.g.\:: 0800                                                                                                                                                                                                                                                                         | Inform the default communication extension for VoIP connection                                                       | Not applicable                                                                                                                                               |
| **330** | VOIP - Registration Approach (eg, 1. Register using a simple password, 2. Register using HA1 password, 3. Register as a guest (no password)) | If the user configures:1 - It means that the system will use the password defined in parameter 328;2 - It means the system will use an encrypted password;3 - It means that it will not have a password, and even if you set parameter 328, the system will disregard the parameter. | Registration approach for the communication to happen, whether it is a registration approach using a password or not | Not applicable                                                                                                                                               |

**Table 1 - Parameters List**


[title] Ticket E-mail Key Fields
[path] Platform Administration/Untitled/

This document is intended to <font color="#3b9f0f">**provide the available fields**</font> to reference information in **Service Request Management** and insert it into the e-mail templates.

## Before getting started

- [x] E-mail triggering occurs only after setting the email box

## List of Key Fields

The key fields available for insertion in the e-mail template file related to the Service Request are listed below:

| **Key Fields**                     | **Description**                                                                                                              |
| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| **$\{CAUSEDETAIL}**                | Detail of Cause of the Incident. Inform the details of the cause of the incident.                                            |
| **$\{CONTACTEMAIL}**               | Applicant's E-mail for Contact. Inform the e-mail of the applicant.                                                          |
| **$\{CONTACTNAME}**                | Name of Applicant for Contact. Provide the name of the requestor for contact.                                                |
| **$\{CONTACTPHONE}**               | Applicant's Telephone for Contact. Inform the contact's telephone number.                                                    |
| **$\{CONTRACTNAME}**               | Contract of the Request. Inform the name of the contract regarding the service/incident request.                             |
| **$\{CURRENTGROUP}**               | Current Attendance Group. Inform the current group, responsible for the service request.                                     |
| **$\{CURRENTGROUPNAME}**           | Returns the description of the Group Name in which the service request is currently located.                                 |
| **$\{CURRENTPHASE}**               | Current Phase of the Request. Report the current phase of the service request.                                               |
| **$\{DATETIMEREACTIVATIONSLASTR}** | SLA start date and time. Inform the start date and time of the SLA (Service Level Agreement).                                |
| **$\{DEADLINESTR}**                | Deadline for request. Inform the deadline (date and time) to attend the request.                                             |
| **$\{DEMANDTYPENAME}**             | Type of Request. Inform the type of request (Incident or Request).                                                           |
| **$\{DESCRIPTION}**                | Description of the Request. Inform the description of the service request.                                                   |
| **$\{DESCRSITUATION}**             | Description of the Request Status. Inform the description of the current situation of the Request.                           |
| **$\{ENDDATETIME}**                | End date of the Request. Inform the date and time from when the service/incident request was completed.                      |
| **$\{GROUPLEVEL1}**                | Level 1 Group. Inform the Level 1 group configured to fulfill the request.                                                   |
| **$\{IDSERVICEREQUEST}**           | Request Number. Inform the service request number.                                                                           |
| **$\{IMPACT}**                     | Impact of Service Request/Incident. Inform the identification of the impact of the service request.                          |
| **$\{LINKSATISFACTIONSURVEY}**     | Link to the satisfaction survey. Inform the link to evaluate the service request.                                            |
| **$\{LINKSERVICEREQUEST}**         | Link to the service request. Report the link to view the service request record.                                             |
| **$\{OBSERVATION}**                | Applicant Contact Notes. Inform the notes described in the service request.                                                  |
| **$\{ORIGINNAME}**                 | Origin of the Request. Inform the source of the service request.                                                             |
| **$\{OVERDUESLASTR}**              | SLA Delay Time. Report the SLA (Service Level Agreement) delay time.                                                         |
| **$\{OWNERDEPARTMENTNAME}**        | Responsible Unit. Inform the unit of the person responsible for attending the service request                                |
| **$\{OWNERNAME}**                  | Responsible for the Registration of the Request. Inform the person responsible for registering the service request.          |
| **$\{PRIORITY}**                   | Priority of the Request of the Request. Inform the priority of service request fulfillment.                                  |
| **$\{REQUESTDATETIMESTR}**         | Date and time of the request. Inform the date and time of service of the service/incident request.                           |
| **$\{REQUESTERDEPARTMENTNAME}**    | Applicant's Unit. Inform the requester's unit.                                                                               |
| **$\{REQUESTERNAME}**              | Name of Applicant. Inform the name of the applicant.                                                                         |
| **$\{REQUESTERUNITY}**             | Name of Applicant and Unit. Inform the name of the applicant and the unit in which it is allocated.                          |
| **$\{RESPONSE}**                   | Description of the Closing of the Request. Inform the description of the closing of the service request.                     |
| **$\{SERVICENAME}**                | Service Name. Inform the name of the requested service.                                                                      |
| **$\{SERVICENAME}**                | Service Requested. Inform the name of the requested service.                                                                 |
| **$\{SITUACTION}**                 | Status of the Request. Inform the current situation of the service request.                                                  |
| **$\{SLATOAGREE}**                 | SLA "To Combine". Inform if the SLA is to match.                                                                             |
| **$\{STARTDATETIME}**              | Start date and time of request record. Inform the date and time when the service/incident request was recorded.              |
| **$\{URGENCY}**                    | The urgency of the Request. Inform the identification of the urgency of the service request.                                 |
| **$(CURRENTRESPONSIBLE)**          | Use for Delegation e-mails - Key that returns the name of the user who was delegated on a ticket                             |
| **$\{NOTE}**                       | Use in e-mails triggered when adding, replying, or editing an occurrence - Key that returns the description of an occurrence |

**Table 1 - List of Key Fields**

****

[title] Customizing Knowledge Portal
[path] Platform Administration/Untitled/

This functionality is intended to <font color="#3b9f0f">**change images in the Knowledge Portal**</font>.

## Procedure

1. Access the functionality through the main menu `System > Settings >
    Knowledge Portal > Customize`;
2. Choose the item that will be changed/customized;
3. Click on "**Save**".

:::hint{type="warning"}
⚠️ ***Attention*****!&#x20;**

To display the title on the **Knowledge Portal** screen, set **parameter 410** to
&#x20;value "**Y**" and also select the "**Show Title**" button on the **Knowledge Portal
&#x20;Management** screen.&#x20;
:::


[title] Cluster vs Competition
[path] Platform Administration/Automation/Graph Mail/

### E-mail Readout

It is plausible that one or more Graph Mail accede to the same Microsoft E-mail and folder, whereas the work logic is protected against competition. For the reason a Graph Mail project reads and processes the same queue or folder of another, the user must be aware that they can compete as long as the purpose of the processing is the same or the destination of the processing is another SM, for example.

However, if the work scope is isolated by a queue or a folder, it is possible to work simultaneously without conflict.

### Work Logic

- [x] One queue for each account
- [x] One folder for each processing objective

### E-mail dispatch

For dispatching, there are no competition problems since ActiveMQ is used, it covers competition in queue consumption issues. Therefore, it is possible to upload more than one Graph Mail container, so that a dispatch cluster can be made. The Graph Mail can already handle to avoid the attachments files competition, sharing them via volume.

### Clearing

The directory mapped in the container volumes is emptied by Graph Mail and SM from the attachments files, to process operations. It only leaves the image gallery files that are frequently used, to reduce disk writing operations.




[title] Implementing Password Security Rules
[path] Platform Administration/Untitled/

This functionality portrays the <font color="#3b9f0f">**configuration of system usage passwords**</font>,
&#x20;providing a higher level of security with the usage of different characters.

:::hint{type="warning"}
⚠️ ***Attention*****!&#x20;**

This security policy **is not available for LDAP users**.
:::

1. From **version Helium 2.1.0**, when updating the application, the system will automatically configure the following parameters of the privacy policy screen:
   - The "**Enable Password Policy**" field will be configured as enabled;
   - The "**Minimum Size**" field will be set to 8;
   - The "**Require**" field will come with **Lowercase, Uppercase, Numbers, and Symbols&#x20;**&#x6F;ptions configured as enabled;
   - The "**New password**" field cannot be equal to the previous ones, it will be set in 2;
   - The "**Require password**" change on the first login field will be configured as enabled;
   - The "**Password duration**" field will be set as 2 months.
2. The system will require changing the password at the first login, after an update or installation;
3. For updates, if the password policy is already enabled, the system will respect the client's settings;
4. If the application has its version changed again in less than 2 months, set in the initial configuration, the system will not request a password change for local users who have already made the change;
5. These settings will only be valid for local users;
6. By enabling the "**User Blocking Policy**", the administrator authorizes the blocking of external or internal users;
7. The use of captcha changes the way of logging in, having an extra method of authentication;
8. The administrator, if enabling user blocking, can send e-mail to those responsible for system security.

## Procedure

1. Access the main menu `System > Settings > Policy Settings`;
2. Enable the "**Enable password security policy**" key;
3. In the "**Password force**" field, the manager must define the minimum number
   &#x20;of password characters (minimum value of 8) and it will contain requirements of:
   &#x20;**uppercase letter, lower case, numbers,&#x20;**&#x61;nd **symbols**;
4. Define the number of previous passwords in which the new one cannot be equal,
   &#x20;in the limiter "**The new password cannot be the same as the previous ones**";
5. For new users, the password change can be defined by clicking on the "**Require password change on the first login**" key
   ;
6. In the "**Password expiration**" field, define the time to expire the password;&#x20;
7. For users who are already in operation, it's possible to force the password
   &#x20;change of the new configuration, from the next login, click on the key "**Force
   &#x20;password change at next login for all users**";

From **version 9.1.2.23** or **9.2.1.0**, new parameters were added:

8\. Enable the "**Enable user blocking policy**" key:

- A symbol with an "***i***" stating that: Will be considered for both internal and external logins;

9\. Enable the "**Enable Captcha at Login**" key: This functionality enables a mandatory check for connections of all users in the system; during the login;

10\. In the User blocking field, the administrator must define the minimum number of successive errors of credentials for user blocking, this blocking occurs for both internal and external users and the unlocking is performed inside the product;

11\. Define the time of successive credential errors from the last minutes to block the user: This field is linked to the "**Block user after successive credential errors**" field since the system needs a time parameter to compare the amount of error in a certain period of time and do not consider the user to be blocked if they are not within the defined time limit for reaching the number of attempts to block;

12\. In the "**Notifications**" field, the following must be defined:&#x20;

- Send security alert to the group: Inform the group to whom the alert email will be sent in case of the blocked user for exceeding the configured attempts;&#x20;
- Send security alerts to e-mails: Inform the e-mail of possible employees who should be alerted in case of user blocking. E-mails must be separated by a comma and with no space between them and no space at the end;

:::hint{type="warning"}
⚠️ ***Attention*****!&#x20;**

If the system identifies the e-mail of the user to whom the access was blocked, this user will also receive a blocking e-mail. The blocking e-mail template is not available for change in this version.
:::

13\. Click on "**Save**".


[title] Configuring Banner Logo
[path] Platform Administration/Untitled/

It is possible to **change the banner in your environment** so that <font color="#3b9f0f">**CITSmart** </font>will have the **identity of your company**.

## Procedure

1. Access the main menu `System > Settings > Environment Configurations`;
2. To change one of the images (start logo, portal logo, system logo, and report logo), click on "**Select an Image**";
3. Click on the pointed box to drag a file or make the upload;
4. Click on "**Save**".

:::hint{type="info"}
🖊 ***Note*****: Change the Loading Icon:**

To change the loading icon, change the value of the **parameter 387** to "**YES**".

**Path:** `Parametrization > CITSmart Parameters > 387`. &#x20;
:::


[title] Development Guidelines
[path] Platform Administration/Automation/Graph Mail/

This implementation does not substitute the previous **POP3**, **SMT**, an&#x64;**&#x20;IMAP** integration for other e-mail services. It can also be parametrized for being utilized simultaneously with those integrations.

# Configuration

The following steps must be accomplished in their presented order:

# Infrastructure

## Azure parametrization

Inside Microsoft Azure:

- Create or choose an e-mail to be utilized by the system in these integrations; It is not necessary to be a specific e-mail account. However, the user must be aware that the e-mail readout and dispatch can modify and pollute the mail inbox; so the user must create rules and folders for messages clearing and organization, so the work of one does not interfere with another.
- Create or choose an application from this e-mail account, in Azure Active Directory. It will be used for e-mail readout and dispatch.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/zlAleJNn-I30eAZk2Xluz_image.png)

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/YmT8xxuCWpSI_GsR4JWii_image.png)

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/--JIptUseyMcenlZCLtLC_image.png)

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/647PGRgpRSZMilc0K1VbD_image.png)

- Set the following permissions:

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/g097cmw8cei8czftZYpdf_image.png)

- Set the application access to the email account that will be used:

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/4Mn7fGZihEAjUg-LJJsxl_image.png)

- Allow the public-client flow for the application:

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/WiXrjlzM4IcL4IeYrM1TG_image.png)

- **APP ID**: Save this ID for future configuration.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/N0pe1OjctSOGFYBQhqwJ5_image.png)

- **Folders for e-mail readout**: If the user wishes to define filtering folders and rules for the mail inbox readout, they must be created at this point. In the first Graph Mail Project version, the sweep for identifying the folders is only realized as it launches.

## Service Management

### WildFly 1.1.2

**ActiveMQ user**

Set a user to have access to the ActiveMQ queues by executing the following command and parametrizing a secure password for the option "-p", according to your environment:

`sh add-user.sh -a -u jmsuser -p 1 -g guest`

**ActiveMQ queues**

The e-mail readout and dispatch queues must be set in the WildFly configuration file, the standalone.xml file, for example. Add the tags with the names of the queues inside the main tag: `<subsystem xmlns="urn:jboss:domain:messaging-activemq:3.0">`

**Example:**

:::BlockQuote

\<jms-queue name="graphMailQueue" entries="queue/graphMailQueue
java\:jboss/exported/jms/queue/queue/graphMailQueue"/>
:::

:::BlockQuote

\<jms-queue name="readGraphMailQueue"
entries="queue/readGraphMailQueue
java\:jboss/exported/jms/queue/queue/readGraphMailQueue"/>
:::

**System Properties**

For the Service Management project to upload the listeners, who will listen to the e-mail readout queues, it is necessary to set the following property:



:::BlockQuote
\<property name="jms.readGraphMailQueue.list" value="readGraphMailQueue"/>
:::

In the tag `<system-properties>` of standalone.xml it is possible to name a queue multiple times to be heard, only by separating with a coma.

### File Sharing

**Folder for sharing images and file attachments**

**A folder must be created** and the **writing** and **readout** **permissions must be set** on the application server, for the volume mapping of the docker containers, which will upload the applications. Thus it will allow the sharing of files between them. This folder will be used for the compose files and in **parameter 479**.

## Graph Mail Parametrization

### Docker

The correct file localization in the docker-compose.yml file from the Graph Mail Project must be set. Also, set the defined folders for image and attachment sharing.

:::BlockQuote
version: '2.2'

**services:**
  citSOLR:
    container\_name: citSOLR
    image: registry.cloud4biz.com/templates/solr\:latest
    command: solr-create -c base\_conhecimento -d base\_conhecimento\_configs

  citTIKA:
    container\_name: citTIKA
    image: registry.cloud4biz.com/templates/tika\:latest
    command: tika.sh
    ports:
    - 9998:9998

  graphmail:
    image: registry.cloud4biz.com/templates/graphmail:1.1.2 
    container\_name: graphmail
    restart: on-failure
    depends\_on:
        - "CITSMART"

    volumes:
    - /storage/my4biz/attachments\:/opt/attachments/
    - /storage/my4biz/config.properties\:/opt/graphmail/config.properties

 CITSMART:
    container\_name: CITSMART
    image: registry.cloud4biz.com/templates/itsmops:2.2.9 
    links:
    - citSOLR
    - citTIKA

    environment:
    - XMS=9600
    - XMX=9600
    - MIN\_POOL\_SIZE=10
    - MAX\_POOL\_SIZE=600
    - STATISTICS\_ENABLE=true
    - BLOCKING\_TIMEOUT\_MILLIS=60000
    - IDLE\_TIMEOUT\_MINUTES=2
    - GC\_CLIENT\_INTERVAL=1800000
    - GC\_SERVER\_INTERVAL=1800000
    - PARALLELGCTHREADS=4
    - ADMIN\_USER=seuuser
    - ADMIN\_PASS=QSPLwso497665kderfij
    - DB\_CITSMART=db\_seubanco
    - JB\_CONFI\_XML=standalone-full-ha.xml
    - TIME\_ZONEAmerica/Fortaleza
    - DB\_HOST=10.10.10.20
    - DB\_USER=seuuser
    - DB\_PASSWORD=QSPLwso497665kderfij
    - DB\_PORT=5432
    - CITSMART\_URL=10.10.10.30
    - GRAPHMAIL\_READ=readGraphMailQueue
    - SOLR\_URL=citSOLR
    - ENABLE\_SSL=yes
    - VALID\_SSL=yes
    - CERT\_KEY\_FILE=seucertificado.jks
    - CERT\_FILE=seucertificado.com.crt
    - CERT\_PASSWORD=789321456
    - CERT\_ALIAS=seualias
    - TIMEOUT\_DEPLOY=60000
    - EVM\_ENABLE=false
    - INV\_ENABLE=false
    - MONGODB\_HOST= #citmongo
    - MONGODB\_PORT= #27017
    - MONGODB\_USER= #admin
    - MONGODB\_PASSWORD= #admin
    - ESPER\_THREADS=4
    - CITSMART\_PROTOCOL=http
    - CITSMART\_LOGIN=consultor
    - CITSMART\_PASSWORD=P\@ssW0rd
    - CITSMARTINV\_ID=citsmartinventory
    - CITSMARTEVM\_ID=citsmartevm
    - CITSMART\_HTTP\_PORT=8080
    - ENABLE\_NEURO=Yes

\#### IVM and EVM Parameters
    - START\_MONITORA\_INCIDENTES=FALSE
    - JDBC\_ALIAS\_REPORTS=
    - JDBC\_ALIAS\_BPM=
    - JDBC\_ALIAS\_BPM\_EVENTOS=
    - START\_VERIFICA\_EVENTOS=FALSE
    - QUANTIDADE\_BACKUPLOGDADOS=1000
    - START\_MODE\_RULES=FALSE
    - START\_MODE\_ITSM=FALSE
    - INICIAR\_PROCESSAMENTOS\_BATCH=TRUE
    - DBQUARTZ=STANDALONE

\##### Deploys
    - CITSMART\_APP=Helium-2.3.3.war
    - CITNEURO\_APP=citsmart-neuro-builder-1.3.7.7.war
    - CITPROFILE\_APP=
    - CITSMARTEVM\_APP=
    - CITSMARTINV\_APP=
    - CITAUDIT\_APP=
    - EVM\_INV\_ONLY=No

    # If EVM\_INV\_ONLY=Yes you need to set FULL\_STACK=Yes
    - FULL\_STACK=Yes
    - LOG\_LEVEL=INFO
    - DB\_SYSTEM=postgres
    - ITSM\_FLAVOR=citsmart

    ports:
    - 8080:8080
    - 443:8443
    - 9990:9990

    volumes:
    - /storage/my4biz/deploys\:/opt/deploys
    - /storage/my4biz/citsmart:/opt/citsmart
    - /storage/my4biz/certs\:/opt/wildfly/certs
    - /storage/my4biz/log:/opt/wildfly/standalone/log
    - /storage/my4biz/mp4:/opt/wildfly/mp4
    - /storage/my4biz/assets\:/opt/wildfly/assets
    - /storage/my4biz/attachments\:/opt/attachments/
:::

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/zjcNOXXIHDUbahrK5c_Ks_image.png)

### Config File

The following properties must be set in the config.properties file of the Graph Mail Project, according to the client scenario:

:::BlockQuote
*JMS\_CONNECTION\_FACTORY\_JNDI = jms/RemoteConnectionFactory
JMS\_WILDFLY\_REMOTING\_URL = http-remoting://172.18.0.4:8080
JMS\_QUEUE\_JNDI = jms/queue/queue/graphMailQueue
JMS\_READ\_MAIL\_QUEUE\_JNDI = jms/queue/queue/readGraphMailQueue
JMS\_USERNAME = jmsuser
&#xA;*&#x4A;MS\_PASSWORD = 352TEDDWtHpfRObR166VOuOBI1F4
GRAPH\_APP\_ID = 51255c25-165446-25d5sd5d5-dssdsd
GRAPH\_USERNAME = [seue-mail@seudominio.gov.br](#)
GRAPH\_PASSWORD = QsPlWSOK
GRAPH\_MAIL\_FOLDERS\_LIST = Inbox
:::

### Dependency

The Graph Mail Project depends on the Service Management project, so it should only be executed when the Service Management one is running.

**Functioning**

- A Thread or Job:
  - Obtains the e-mail messages occasionally and extracts the: **sender**, **subject**, **body**, and **attachments&#x20;**&#x66;rom the parameterized list of folders;
  - Registers messages received in a specific queue for registration of tickets in WildFly, containing the name of the folder, the queue, and the content of the email, including the list of attachments;
  - Etches the attachments to a mapped folder on a volume that SM is able to access;
  - Performs the "Email control procedure":
    - Processing control: the system reads a predefined folder, allowing the user to create filtering rules, specific to the ticket registration. It can be an incident, problem, change or release ticket: what determines it is the automatic action registration;
    - <font color="#ff0004">Destination of the processed message: the system marks the already processed message as read.</font>
    - Mailbox sharing:&#x20;
      - It can be used by the user and the system - if the folder for reading is implemented;
      - It will also be used for sending e-mails.


[title] Configuring E-mail Account
[path] Platform Administration/

This document aims to <font color="#3b9f0f">**present a step-by-step of the e-mail configuration**</font> in the <font color="#3b9f0f">**CITSmart** </font>**Platform&#x20;**&#x62;y reading (**IMAP**) and sending (**SMTP**) messages.

## Before getting started

It is necessary:

- [x] To get the e-mail information; and&#x20;
- [x] To configure the access permissions to the e-mail server.

## Procedure

1. Access the main menu `Parametrization > E-mail`
   - Configure the SMTP

| **ID**  | **Description**                     | **Example**                                          |
| ------- | ----------------------------------- | ---------------------------------------------------- |
| **10**  | Organization Email Address          | [company@exemple.com](mailto\:company@exemple.com)   |
| **11**  | Requires authentication             | Yes                                                  |
| **12**  | E-mail address                      | [your.email@gmail.com](mailto\:your.email@gmail.com) |
| **13**  | Password                            | Your Gmail password                                  |
| **14**  | Server for sending an e-mail (SMTP) | smtp.gmail.com                                       |
| **199** | Requires TLS/SSL                    | Yes                                                  |
| **269** | Port                                | 587                                                  |

2\. Access the main menu `Parametrization > E-mail`

- Configure the IMAP

| **ID**  | **Description**                    | **Example**                                          |
| ------- | ---------------------------------- | ---------------------------------------------------- |
| **23**  | Server for receiving emails (IMAP) | imap.gmail.com                                       |
| **24**  | E-mail address                     | [your.email@gmail.com](mailto\:your.email@gmail.com) |
| **25**  | Password                           | Your Gmail password                                  |
| **26**  | Protocol (imaps, pop, etc.)        | imaps                                                |
| **27**  | Port                               | 993                                                  |
| **28**  | E-mail box                         | inbox                                                |
| **72**  | Number of messages loaded          | 10                                                   |
| **199** | Requires TLS/SSL                   | Yes                                                  |


[title] Data Management
[path] Platform Administration/

The purpose of this functionality is to <font color="#3b9f0f">**generate exportation and importation of
 data in the system table**</font>.

## Procedure

1. Access the functionality through the main menu `System > Database > Data
    Management`;
2. Click on "**Load Metadata**" to update the table list;
3. To generate a system exportation table in "**.XML**", click on "**Export All**", for exporting all system tables in the format chosen;
4. To generate the system table exportation in "**.SQL**", click on "**Export All
   &#x20;SQL**", to export all system tables with SQL command;
5. To export a table, double click on the table you want;
6. Set the data that will be exported;
7. Click on "**Process**".


[title] Change Automatic Actions
[path] Platform Administration/Automation/

Some events will present **a situation where the appropriate action will need to
&#x20;be addressed by the Change Management process**, that is, this functionality is
&#x20;intended to register automatic actions of the type change. This registration
&#x20;will be associated with the automatic actions, where it will be used
&#x20;in the <font color="#3b9f0f">**CITSmart** </font>**Event Managers** registration of **Nagios, Zabbix, Inventory&#x20;**&#x61;nd
&#x20;**Events Correlated**.

This feature provides a variety of actions, such as <font color="#3b9f0f">**including, changing, and
 deleting automatic actions of the type change**</font>.

## Before getting started

To register change automatic actions, it is necessary:

- [x] To register
  &#x20;previously the unit, requester (employee), contract linked to the employee and unit;
- [x] As well as the
  &#x20;Change Advisory Board (group); and&#x20;
- [x] To configure the **parameters 47, 279**, and **280&#x20;**&#x61;bout the change.

## Procedure

1. Access the functionality through the main menu `System > Automatic Actions  > Automatic Actions`;
2. Complete the fields available;
3. Click on "**Save**".


[title] Parametrization - Work Order
[path] Platform Administration/Untitled/

The **Work Order** is a document that will <font color="#3b9f0f">**give permission to the relative execution
 of a service**</font>. The "**Work Order**" parametrization allows defining the calculation
&#x20;formula of the work order gloss, and enables custom signatures in the Work Orders
&#x20;report, within other viable actions.

## Procedure

1. Access the functionality through the main menu `Parametrization > Work Order
    (WO)`;
2. Define the value of the parameters (attributes);
3. Click on "**Save**";
4. The list below presents the "**Work Order**" parameters and the purpose of each
   &#x20;one of them:

| **#**   | **Name**                                                                           | **Possible Values** | **Purpose**                                                                                                                                                                                                                                                                                                                                                                                      | **Additional Guidance**                                                                                                                          |
| ------- | ---------------------------------------------------------------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| **51**  | WO GLOSS FORMULA - Default Code                                                    |                     | Define the Work Order Calculation formula. By default, the formula is already defined in the tool.                                                                                                                                                                                                                                                                                               | Not applicable                                                                                                                                   |
| **130** | It allows Work Order listing with the retroactive date (Eg: Y or N - Default: 'N') | Y or N (Default: N) | Define whether to allow the listing of a Work Order with a retroactive date.                                                                                                                                                                                                                                                                                                                     | If you do not enter the parameter value, the system default value will be used: "N".                                                             |
| **229** | Reset Activity Formulas (Eg: Y or N - Default: 'Y')                                | Y or N (Default: Y) | Change the formula structure of the activities already registered to the new structure that is configurable from the WO Formula screen. When reporting the default value of "Y", the system will execute the activity formula reset routine at the time JBoss restarts on a <font color="#3b9f0f">**CITSmart**</font> system update and assigns "N" to this parameter at the time it's finished. | Once the "Y" value has been entered, the contract activity formula, not yet configured, will be in accordance with the new WO Formula structure. |
| **243** | Allow custom subscriptions in the Work Orders report                               |                     | Enable signatures to be used for printing the Work Order reports. When the parameter is enabled (value = Y), the system displays a field in the Work Order form, and you can choose which signature frame configuration to use when printing your reports.                                                                                                                                       | When enabled, it forces the user to define and configure one more field before saving a Work Order.                                              |

**Table 1 - Parameters List**


[title] System Customization
[path] Platform Administration/Untitled/

It is possible to customize numerous information in your environment, as well as:

- **Banner Logo of System**
- **Knowledge Portal** (CSS and banner logo)


[title] Parameters
[path] Initial Settings/Users, Groups, Roles/

On the "**Parameters**" screen, select the options that allow viewing and making necessary parameter adjustments in the system:



When selecting the options, a table appears with the following items: **Attribute, Description, Type, and Value.**

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/8aDVHLdxCV-wvCcd2e4-E_image.png)

On this same Parameters screen, you can **remove** a form, as well as add a new parameter:

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/MVRi-jUGz5pvkRvZonDF3_image.png)

***

1. When displaying the form, you can edit it;
2. Fill in all required fields and make the desired changes;
3. Click "**Save**" to proceed.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/YlW3CnZ4m1ZUtcbRC14BF_image.png)

Fields marked with an asterisk (\*) are mandatory.


[title] Data and Import
[path] Platform Administration/

It is possible to import a range of data to the <font color="#3b9f0f">**CITSmart** </font>**Platform**.

This can help in the process of tool configuration or process design.


[title] Groups
[path] Initial Settings/Users, Groups, Roles/

This solution area allows the creation of security groups, service teams, and management groups, which can be associated with distinct roles, workflow permissions, and contracts (multi-client).

The tool features a search screen and displays groups from the identity manager.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/DgUU2GkRoSOcvsbda8j6g_image.png)

1. By selecting all groups on the left, you can deactivate them.
2. Additionally, you can edit or remove these groups in `Actions`, performed directly in the **identity manager**.
3. You can create a new group by clicking the `Create` button.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/WStXupWjsynbZ3yV9_iog_image.png)

- When creating a new group, you can link these groups to roles.
- Furthermore, you can grant permissions by selecting which roles have menu access rights.
- Click "**Save**" or "**Save and continue**". Doing so will keep you on the registration screen.


[title] Parametrization - Mobile
[path] Platform Administration/Untitled/

The "**Mobile**" parametrization has the purpose of **configuring and customizing to adequate the scenario about the mobile application usage** (for example, <font color="#3b9f0f">**CITSmart** </font>**GO**).

## Procedure

1. Access the functionality through the main menu `Parametrization > Mobile`;
2. Define the value of the parameters (attributes);
3. Click on "**Save**";
4. The list below presents the "**Mobile**" parameters and the purpose of each one
   &#x20;of them:

| **#**   | **Name**                                                                                                                                                             | **Possible Values** | **Purpose**                                                                                                                                                                                                                                                     | **Additional Guidance** |
| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| **255** | Range of Action/View of attendant in the Mobile - (Default: 30)                                                                                                      |                     | Define the radius of action of an attendant, used in APP mobile. Define the maximum radius of service for requests that are in a "Non-Directed" status.                                                                                                         | Not applicable          |
| **256** | Interval (in minutes) of time for reporting the Attendant position - (Default: 10)                                                                                   |                     | Define the interval that the Mobile application should report to the server the geographic positioning of the attendant.                                                                                                                                        | Not applicable          |
| **257** | Page size for return in paged REST services (Default: 10)                                                                                                            |                     | Define the number of registries returned in the list of services consumed by the Mobile.                                                                                                                                                                        | Not applicable          |
| **258** | Maximum interval of days for consultation (Default: 30)                                                                                                              |                     | Define maximum query range restriction on the screens, initially used in service force management.                                                                                                                                                              | Not applicable          |
| **267** | Page size for return on REST V1 mobile services (Default: 200)                                                                                                       |                     | Set the page size to return in REST services.                                                                                                                                                                                                                   | Not applicable          |
| **272** | Determine whether you will only be notified of requests without responsible in <font color="#3b9f0f">**CITSmart** </font>**Mobile**. Values: "Y" or "N" Default: "N" | Y or N (Default: N) | Define which requests can be notified to the user. If the value of the parameter is "Y", only the notifications of requests without current attendant will be displayed. If the value of the parameter is "N", notifications of all requests will be displayed. | Not applicable          |
| **284** | Default contract ID for creating new incidents/requests in <font color="#3b9f0f">**CITSmart** </font>**Mobile**.                                                     |                     | Enter the identification number (ID) of the contract to perform the opening of service requests via mobile.                                                                                                                                                     | Not applicable          |
| **285** | Default service ID for service requests and incidents created in <font color="#3b9f0f">**CITSmart** </font>**Mobile**.                                               |                     | Enter the service identification number (ID) that will be the default for the registration of service requests via mobile.                                                                                                                                      | Not applicable          |
| **286** | Default source ID for service requests and incidents created in <font color="#3b9f0f">**CITSmart** </font>**Mobile**.                                                |                     | Enter the identification number (ID) of the default origin to open the service request via mobile.                                                                                                                                                              | Not applicable          |
| **350** | Enable sending notifications to mobile devices                                                                                                                       | Y or N (Default: N) | It allows controlling whether system notifications will be sent to mobile devices (general).                                                                                                                                                                    | Not applicable          |
| **352** | Enables sending notifications to mobile devices when creating requests                                                                                               | Y or N (Default: N) | It allows controlling whether system notifications will be sent to mobile devices (general).                                                                                                                                                                    | Not applicable          |
| **353** | Enables sending mobile notifications while updating requests reporting close calls                                                                                   | Y or N (Default: N) | It allows controlling whether system notifications will be sent to mobile devices (general).                                                                                                                                                                    | Not applicable          |

**Table 1 - Parameters List**


[title] Registering LDAP Connection
[path] Platform Administration/Authentication/

**LDAP&#x20;**(**Lightweight Directory Access Protocol**) is a standard protocol that allows <font color="#3b9f0f">**managing directories**</font>, that is, accessing information banks about the users of a network through **TCP/IP** **protocols**.

You can configure <font color="#3b9f0f">**CITSmart**</font> to query available user bases in a directory service (Microsoft Active Directory or open-LDAP), which allows these users to authenticate at <font color="#3b9f0f">**CITSmart**</font> by using their credentials without having to manually enroll them (at <font color="#3b9f0f">**CITSmart**</font>).

Today, the reading of data from an AD/LDAP server boils down to the "**user**" object. That way you can use filters to bring them to <font color="#3b9f0f">**CITSmart**</font>. Moreover, you can use the "**Field Mapping**" option to upload attribute information (e.g.: email, phone, location, and others).

Below is an authentication model for <font color="#3b9f0f">**CITSmart**</font> **Cloud&#x20;**&#x63;ustomers who want to use their on-premises directory base.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/DrcQKlv6NImP47sTjDMWa_image.png)

## Before getting started

If you want to automatically set up and synchronize the users, it is necessary:

- [x] To create a **CRON** for this purpose (e.g.: synchronize users every day at 12:00 AM);
- [x] To create a schedule go to `Processes > Event Management > Time`.

## Procedure

### Configuring Connection

1. Access the menu `Parametrization > LDAP Configuration`;
2. Click on "**New**";
3. Complete all the fields available;

| **Field**            | **Description**                                                                                                                  | **Example**                                  |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
| **Implementation**   | Type of directory server                                                                                                         | AD/OpenLDAP                                  |
| **URL Connection**   | Access address to the directory base. Note that you can use an unencrypted (port 389) or encrypted (port 636) connection         | ldaps\://auth.domain.com:636                 |
| **DN Base**          | DN Base used to search user entries                                                                                              | dc=domain,dc=com                             |
| **DN Alias**         | Domain/Connection Name, this name will be visible on the login screen                                                            | domain.com                                   |
| **Filter**           | Filter to query objects in directories                                                                                           | (&(objectCategory=person)(objectClass=user)) |
| **DN Manager**       | User with permission to search the directory. In this case, enter the value according to the "distinguishedName" attribute of AD | CN=Service User,OU=COMPANY,DC=domain,DC=com  |
| **Manager Password** | The password of the DN Manager                                                                                                   | \*\*\*\*\*                                   |
| **Default Setting**  | If the connection is available on the login screen                                                                               | Yes/No                                       |

:::hint{type="warning"}
 📌 ***IMPORTANT*****!**

If there are no DN Groups, complete the "**DN Group**" field with an asterisk only. This will make the system verify the entire domain.
:::

4\. Check connectivity with the base by clicking on "**Test Connection**", if all data is correct you will receive the message "**Connection successful**";

5\. Click on "**Save**".

:::hint{type="warning"}
⚠️ ***Attention*****!&#x20;**

Before asking to test **you must** click on "**Save**" to save the configuration, otherwise, the test will use the data prior to the changes made on the screen.
:::

### Configuring DN Group and Appointments

After you have successfully configured a connection, you must add preferences for user synchronization, in which case you must enter LDAP Groups and Field Mapping. For "**LDAP Groups**" you have the possibility to create customizations where certain users will automatically inherit permissions in <font color="#3b9f0f">**CITSmart** </font>via linkage with the Access Profile or Group. For the "**Field Mapping**" item, you can configure the application to read AD/LDAP attribute information and bring it into the employee record (e.g.: read the "mail" attribute and feed the "e-mail" field of the employee).

1. To link new groups, click on "**Add**" in the **LDAP Groups** area and enter the data:

| **Field**             | **Description**                                                                                                                  | **Example**                                  |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
| **DN Grupo**          | Path to the DN Group                                                                                                             | OU=Users, OU=Company                         |
| **Filter**            | Filter to search for the object. Leave blank to use what is defined in the connection                                            | (&(objectCategory=person)(objectClass=user)) |
| **Attribute to name** | Enter the attribute to read the name (e.g.: CN, SamAccountName, etc.)                                                            | CN                                           |
| **Update Links**      | How often the "Access Profile" and "Group" fields will be updated when performing sync (Options: Always, Never, or Creation Only | Always                                       |
| **Access Profile**    | System profile that the users will inherit                                                                                       | Manager                                      |
| **Group**             | System group that the users will be entered                                                                                      | Managers                                     |
| **Scheduling**        | The period when auto-sync will run                                                                                               | \[Everyday]\*                                |

2\. To link attributes to fields, click on "**Add**" in the **Field Mapping** area, enter the name of the LDAP field and select the corresponding field in <font color="#3b9f0f">**CITSmart**</font>;

| **Field in LDAP**   | **Field in System** |
| ------------------- | ------------------- |
| **mail**            | E-mail              |
| **telephoneNumber** | Phone               |
| **localeID**        | Location            |

3\. Click on "**Save**".

:::hint{type="info"}
🖊 ***Note*****:&#x20;**&#x57;hen there is an authentication request in the system identification screen (login and password), a correct connection search cycle is executed based on this configuration, that is, there is an authentication attempt for each domain registered here (if there is more than one).
:::

### To use LDAP protocol

Using the LDAPS protocol in <font color="#3b9f0f">**CITSmart** </font>requires the AD/LDAP server public certificate in the JAVA CA certificate store (on your Wildfly server). Therefore, you must export it from the AD/LDAP server and import it into your instance. If you have questions about importing certificates on the application server installation document.

## What to do next

To use AD/LDAP authentication effectively, after registering the connection, change **parameter 22** and enter a **value&#x20;**&#x65;qual to "**2**", that is, indicate that the default authentication method in <font color="#3b9f0f">**CITSmart** </font>is AD/LDAP. However, manual authentication will continue to function normally.


[title] Problem E-mail Key Fields
[path] Platform Administration/Untitled/

This document is intended to<font color="#3b9f0f"> **provide a list of the key fields**</font> available for the
&#x20;problem-related email template registration.

## List of Key Fields

- [x] The following key fields are listed below for insertion into the problem-related
  &#x20;e-mail template record:

| **Key Fields**                 | **Description**                                                                                                                    |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| **$\{CORRECTACTIONS}**         | Actions Taken Correctly. Inform the description of the actions performed correctly regarding the review of a serious problem.      |
| **$\{INCORRECTACTIONS}**       | Actions Taken Incorrectly. Inform the description of actions performed incorrectly regarding serious problem review.               |
| **$\{CONTRACT}**               | Contract agreement. Inform the name of the contract regarding the problem record.                                                  |
| **$\{CAPTUREDATETIME}**        | Date and Time of Starting the Problem Log. Inform the date and time the problem was logged.                                        |
| **$\{ENDDATETIME}**            | Date and Time of Problem Completion. Inform the date and time when the problem was terminated.                                     |
| **$\{DEADLINE}**               | Limit Time to Answer the Problem. Inform the deadline (date and time) to attend to the problem.                                    |
| **$\{DEADLINETOSOLVE}**        | Deadline to Solve/Work around the problem. Report the deadline to solve/work around the problem.                                   |
| **$\{DESCRIPTION}**            | Problem description. Inform the description of the problem.                                                                        |
| **$\{DIAGNOSTIC}**             | Diagnosis of the Problem. Report the description of the problem diagnosis.                                                         |
| **$\{CONTACTEMAIL}**           | Contact E-mail. Inform the contact's e-mail address.                                                                               |
| **$\{CURRENTPHASEID}**         | Current problem identification situation. Inform the current situation of the identification (phase) in which the problem is.      |
| **$\{CLOSURE}**                | Closing the Problem. Report the description of the problem closure.                                                                |
| **$\{PROBLEMID}**              | The issue Identification Number. Inform the identification number of the problem record.                                           |
| **$\{IMPACT}**                 | Impact of the Problem. Inform the identification of the impact of the problem.                                                     |
| **$\{SATISFACTIONSURVEYLINK}** | Link to the satisfaction survey. Inform the link to evaluate the problem.                                                          |
| **$\{FUTUREIMPROVEMENTS}**     | Possible Future Improvements. Inform the description of possible future improvements regarding serious problem review.             |
| **$\{ASSOCIATEDERRORMESSAGE}** | Associated Error Message. Report the associated error message that was described in the evaluation and diagnosis of the problem.   |
| **$\{CONTACTNAME}**            | Contact name. Please provide the name of the requestor for contact.                                                                |
| **$\{CURRENTGROUP}**           | Executor Group. Inform the name of the executing group of the problem.                                                             |
| **$\{DEADLINEHH}**             | Deadline (hours) for Answering the Problem. Inform the deadline for attending to the problem.                                      |
| **$\{PRIORITY}**               | Priority. Inform the priority of the problem.                                                                                      |
| **$\{PROACTIVEREACTIVE}**      | Problem Management. Inform problem management (proactive or reactive).                                                             |
| **$\{PROBLEMRECURRENCE}**      | Recurrence of the problem. Inform the description of how to prevent recurrence of the problem concerning the major problem review. |
| **$\{THIRDRESPONSIBILITY}**    | Liability of Third Parties. Inform the description of third-party liability regarding serious problem review.                      |
| **$\{OWNERNAME}**              | Responsible for the Problem Answer. Inform the person in charge of the problem.                                                    |
| **$\{SEVERITY}**               | The severity of the problem. Inform the description of the severity of the problem.                                                |
| **$\{REQUESTERNAME}**          | Name of Applicant. Inform the name of the requestor of the problem record.                                                         |
| **$\{DEFINITIVESOLUTION}**     | Description of the Definitive Solution. Tell the description of the definitive solution of the problem.                            |
| **$\{STATUSDESCRIPTION}**      | Status of the Problem. Tell you the status of the problem.                                                                         |
| **$\{TITLE}**                  | Problem Title. Inform the title of the problem that was registered.                                                                |
| **$\{URGENCY}**                | The Urgency of the Problem. Inform the identification of the Problem Urgency.                                                      |

**Table 1 - List of Key Fields**


[title] Problem Automatic Action  
[path] Platform Administration/Automation/

Some events will present **a situation where the appropriate action will need to be addressed by the problem management process**, that is, this functionality is intended to register the problem type automatic actions. This registration will be associated with the automatic actions, where it will be used in the <font color="#3b9f0f">**CITSmart** </font>**Event Manager** registration of **Nagios, Zabbix, Inventory,&#x20;**&#x61;nd **Correlated Events.**

This feature provides a variety of actions, such as <font color="#3b9f0f">**including, changing, and deleting problem-type automatic actions**</font>.

## Before getting started

To register a problem automatic action, it is necessary:

- [x] To register
  &#x20;previously the group, unit, the requester (employee), the contract that is being linked to the employee and
  &#x20;unit, problem category being linked to the flow about the problem.

## Procedure

1. Access the functionality through the main menu `System > Automatic Actions  > Problem Actions`;
2. Complete the fields available;
3. Click on "**Save**".


[title] Parametrization - Smart Portal
[path] Platform Administration/Untitled/

**Smart Portal** is a feature of the solution that provides the Service Catalog
&#x20;(Business and Support) to users of the system and other information, such as
&#x20;service requests, system news, and chat.&#x20;

The "**Smart portal**" parametrization allows the <font color="#3b9f0f">**activation of the exchange of messages between the requester and the
 responsible for the request**</font>, enabling the option of canceling a ticket through
&#x20;the portal, among other actions.

## Procedure

1. Access the functionality through the main menu `Parametrization > Smart
    Portal`;
2. Define the value of the parameters  (attributes);
3. Click on "**Save**";
4. The list below presents the "**Smart Portal**" parameters and the purpose of
   &#x20;each one of them:

| **#**   | **Name**                                                                                                      | **Possible Values** | **Purpose**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | **Additional Guidance**                                                                                                                                                                                                                                        |
| ------- | ------------------------------------------------------------------------------------------------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **245** | Display full-service list screen in Portal (Eg: Y or N - Default 'N')                                         | Y or N (Default: N) | It enables the presentation of price columns in the shopping cart of the <font color="#3b9f0f">**CITSmart** </font>**Portal**.                                                                                                                                                                                                                                                                                                                                                                                                                             | Not applicable                                                                                                                                                                                                                                                 |
| **246** | Hide 'New Request' button in Portal (Eg: Y or N)                                                              | Y or N              | Hide the "New Request" button on the Portal screen.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Not applicable                                                                                                                                                                                                                                                 |
| **247** | Shopping Cart services are unchecked by default in the Portal (Eg: Y or N - Default 'Y')                      | Y or N (Default: Y) | Disable/Enable Portal Shopping Cart services.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Not applicable                                                                                                                                                                                                                                                 |
| **252** | Register Occurrence through Portal                                                                            |                     | Enable the option to register an occurrence for a request that is in the "In Progress" status.                                                                                                                                                                                                                                                                                                                                                                                                                                                             | If the parameter is 'Y', the option to register occurrence through the portal will be displayed to the user.                                                                                                                                                   |
| **253** | Occurrence Registration Email ID by Portal                                                                    |                     | Inform the identification number (ID) of the standard email template to send a notification to the "responsible" of the request, after an event has been registered by the Portal. This email template ID is set on the "Email Template" screen.                                                                                                                                                                                                                                                                                                           | With the identification number, the e-mail template will be used to notify the technician when there is an occurrence record by the Service Portal. If the identification number (ID) is not correctly entered, the system will not send notification e-mails. |
| **262** | The ID Category Occurrence Registration via Portal                                                            |                     | Define the default category for occurrence logging by the Portal. If the value is set correctly, the "Category" field will be disabled for change by receiving the value of this parameter. If the value of the parameter is invalid, the parameter will be disabled.                                                                                                                                                                                                                                                                                      | Not applicable                                                                                                                                                                                                                                                 |
| **263** | Portal Occurrence Origin ID                                                                                   |                     | Define the default source for occurrence logging by the Portal. If the value is set correctly, the "Source" field will be disabled for change by receiving the value of this parameter. If the value of the parameter is invalid, the parameter will be disabled.                                                                                                                                                                                                                                                                                          | Not applicable                                                                                                                                                                                                                                                 |
| **292** | Enable the "Add and Continue" button in the new request popup in the portal - Values: "Y" or "N" Default: "N" | Y or N (Default: N) | Set whether the "Add and Continue" button will appear on the Portal Service Request screen.                                                                                                                                                                                                                                                                                                                                                                                                                                                                | If the value for the parameter is not set, the value "N" will be automatically set by the system.                                                                                                                                                              |
| **293** | Enable access permission for user groups in the portal - Values: "Y" or "N" Default: "N"                      | Y or N (Default: N) | Enable the configuration of the group access permission made in the Service Portfolio, Business/Technical, and Service Incident and Request to view them in the Portal. When the value of the parameter is "Y", the visibility in the Portal is limited to the user groups configured in the portfolio, the portfolio of the service in this portfolio, and the register of the incident services and service requests. When the value of the parameter is "N", the access permission is disabled, so the visibility in the Portal is completely released. | If the value for the parameter is not set, the value "N" will be automatically set by the system.                                                                                                                                                              |
| **298** | Display the occurrences of the Request/Incident (Values: "Y" or "N" Default: "N")                             | Y or N (Default: N) |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Not applicable                                                                                                                                                                                                                                                 |
| **299** | Request/Incident - Activate message exchange (Values: "Y" or "N" Default: "N")                                | Y or N (Default: N) | Enable message exchange between the requester and the person responsible to the request                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Not applicable                                                                                                                                                                                                                                                 |
| **302** | Enable cancellation of request/incident by the portal (Values: "Y" or "N" Default: "N")                       | Y or N (Default: N) | Enable the option to cancel a ticket through the portal                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Not applicable                                                                                                                                                                                                                                                 |
| **371** | Enable request response on portal                                                                             | Y or N (Default: N) | It allows showing/hiding the Solution Answer when showing the ticket in the Smart Portal.                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Not applicable                                                                                                                                                                                                                                                 |
| **373** | ID Default register profile                                                                                   |                     | It saves the group ID that will be configured for a user registered via profile                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Not applicable                                                                                                                                                                                                                                                 |
| **374** | ID Portfolio redirection profile                                                                              |                     | It saves the portfolio ID that the user saved via profile will have access                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Not applicable                                                                                                                                                                                                                                                 |
| **376** | Default user ID (External request)                                                                            |                     | It saves the ID of the email template that will be sent to the user registered by the profile                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Not applicable                                                                                                                                                                                                                                                 |
| **377** | Default group ID (External request)                                                                           |                     | It saves the address that the user will be redirected to after registering in the profile                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Not applicable                                                                                                                                                                                                                                                 |
| **386** | ID Sub portfolio redirection profile                                                                          | Whole numbers       | It saves the service/business ID that the user registered via profile will have access                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Not applicable                                                                                                                                                                                                                                                 |
| **387** | Use logo header in loading                                                                                    |                     | Informs if the user will use another image when the system is loaded                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Not applicable                                                                                                                                                                                                                                                 |

**Table 1 - Parameters List**


[title] Registering Domain
[path] Platform Administration/Untitled/

The **Domain&#x20;**&#x66;unctionality is intended to **register the domain to insert new domain
&#x20;items**, that is, new options in the field of a certain system screen. To use it,
&#x20;it should have knowledge about the system codification.

This feature provides a variety of actions, such as <font color="#3b9f0f">**including, changing, and
 deleting a domain**</font>.

## Procedure

1. Access the main menu `System > Domain Settings > Domains`;
2. Click on "**New**";
3. Complete the fields available;
4. Click on "**Save**".


[title] Parametrization - E-mail
[path] Platform Administration/Untitled/

We can define **e-mail** as a <font color="#3b9f0f">**method that allows us to compose, send and receive
 messages**</font> through electronic communication systems.&#x20;

The "**E-mail**" parametrization allows to configure the sending e-mail reading, inform the company's
&#x20;default e-mail domain, among other actions, in order to allow the use of the
&#x20;e-mail service to add better experience in the use of the various resources
&#x20;available in <font color="#3b9f0f">**CITSmart** </font>solutions, allowing to sending information to users.

## Procedure

1. Access the functionality through the main menu `Parametrization > E-mail`;
2. Set the values of parameters (attributes);
3. Click on "**Save**";
4. The list below presents the "**E-mail**" parameters and their goal:

| **#**   | **Name**                                                                              | **Possible values**                                                  | **Objective**                                                                                                                                                                                                                                                                                                     | **Additional Guidance**                                                                                                                                              |
| ------- | ------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **10**  | SMTP SEND - E-mail source of service request notifications                            | E.g.: [citsmart@centralit.com.br](mailto\:citsmart@centralit.com.br) | Inform the e-mail that will be used as the origin of the notifications regarding the Incident/Requests opened or changed.                                                                                                                                                                                         | Not applicable                                                                                                                                                       |
| **11**  | SMTP SEND - Requires authentication for sending an e-mail (Eg: Y or N - Default: 'N') | Y or N (Default: N)                                                  | Define if the email sending used for notifications requires authentication. If the email configured in parameter 10 does not require authentication, the value "N" must be set. If the email requires authentication, the value "Y" must be set and the authentication must be configured in the next parameters. | If the value for the parameter is not set, the value "N" (No) will be automatically set by the system.                                                               |
| **12**  | SMTP SEND - User for Email Authentication                                             | E.g.: citsmart                                                       | Inform the user of the email for authentication. If the email requires authentication, we must inform the user to be authenticated.                                                                                                                                                                               | If you do not inform the user correctly, authentication will not be performed.                                                                                       |
| **13**  | SMTP SEND - Password for Email Authentication                                         |                                                                      | Enter the email password for authentication. If the e-mail requires authentication, we must inform the user password for the email.                                                                                                                                                                               | If you do not enter the password correctly, authentication will not be performed.                                                                                    |
| **14**  | SMTP SEND - Server for sending e-mail                                                 | E.g.: 172.20.0.200                                                   | Inform the SMTP server, used for sending an e-mail. The SMTP server is in charge of sending the system notification emails to the recipients.                                                                                                                                                                     | If you do not inform the SMTP server, you will not be able to send system notification emails.                                                                       |
| **23**  | SMTP READING - Service Desk Email Input Server                                        | E.g.: 172.20.0.200                                                   | Inform the Service Desk email server that will be accessed for reading emails.                                                                                                                                                                                                                                    | Not applicable                                                                                                                                                       |
| **24**  | SMTP READING - Service Desk Email Inbox User                                          | E.g.: citsmart                                                       | Enter the Service Desk email account that will be used to receive the emails sent by the user.                                                                                                                                                                                                                    | Not applicable                                                                                                                                                       |
| **25**  | SMTP READING - Service Desk Email Inbox Password                                      |                                                                      | Enter the email account password entered in parameter 24 for access to the Service Desk email inbox.                                                                                                                                                                                                              | Not applicable                                                                                                                                                       |
| **26**  | SMTP READING - Service Desk email server provider (imaps, pops, imap, pop, etc)       | E.g.: imap                                                           | Inform the protocol of the Service Desk email server that will be used for reading emails.                                                                                                                                                                                                                        | Not applicable                                                                                                                                                       |
| **27**  | SMTP READING - Service Desk email server port                                         | E.g.: 143                                                            | Inform the server port that will be used for reading emails.                                                                                                                                                                                                                                                      | Not applicable                                                                                                                                                       |
| **28**  | SMTP READING - Service Desk Email Inbox Folder                                        | E.g.: Inbox                                                          | Inform the email inbox folder of the Service Desk email account.                                                                                                                                                                                                                                                  | Not applicable                                                                                                                                                       |
| **72**  | SMTP READING - Email Limit Loaded on Service Request                                  | E.g.: 20                                                             | Set the limit of emails that will be loaded on the Service/Incident Request screen. By clicking on the "upload email" button on the Service/Incident Request screen, the number of e-mails as configured in the parameter will be loaded.                                                                         | Not applicable                                                                                                                                                       |
| **199** | SMTP SEND - Does the Email Use TLS / ssl Authentication? (Eg: Y or N - Default 'N'    | Y or N (Default: N)                                                  | Set whether the email system will use starttls authentication.                                                                                                                                                                                                                                                    | If you do not enter the 'Y' value for the parameter, it will impact only the servers that use TLS/SSL authentication and the system will not be able to send emails. |
| **269** | SMTP SEND - Port for sending e-mail                                                   | E.g.: 465 (security port SSL/TLS), 25 and 26 (common ports)          | Inform the server port that will be used to send emails to the server.                                                                                                                                                                                                                                            | Not applicable                                                                                                                                                       |
| **297** | Disables sending system emails (Values: "Y" or "N" Default: "N")                      | Y or N (Default: N)                                                  | Disables all system e-mail submissions.                                                                                                                                                                                                                                                                           | Not applicable                                                                                                                                                       |

**Table 1 - Parameters List**


[title] Registering External Connections
[path] Platform Administration/Untitled/

This functionality is intended to allow th&#x65;**&#x20;connection creation with other
&#x20;database**, being internal or external.

This feature provides various actions, such as <font color="#3b9f0f">**including, changing, and deleting
 external connections**</font>.

## Procedure

1. Access the functionality through the main menu `System > External
    Connections`;
2. Complete the fields available;
3. Click on "**Test Connection**" to verify if the connection was successfully
   &#x20;established;
4. Click on "**Save**".

:::hint{type="info"}
🖊 ***Note*****:&#x20;**&#x54;he following message is displayed if the data in the Url, User, and Password
&#x20;field is not valid: "**Incorrect data and/or Bank inaccessible! Do you want to save
&#x20;it anyway?**".
:::


[title] Registering User
[path] Initial Settings/Users, Groups, Roles/Employee Registration/

In order for the employee to access the system, it is necessary to create a user. By registering it, it is possible that the user's data (login and password) are sent to the e-mail of the employee.&#x20;

To do this, set **parameter 455** indicating the e-mail template (ID) created for this purpose. The e-mail template should contain the keys **$\{LOGIN}** and **$\{NEWPASSWORD}**.

This feature provides a variety of actions, such as including, changing, and deleting a user.

:::hint{type="warning"}
📌 ***IMPORTANT*****!**

The sending of login and password, when registering the new user, does not include users imported via AD or LDAP.
:::

## Before getting started

To register a user, it is necessary to:

- [x] Register the Employee;
- [x] Have at least an Access Profile;



To send the Login and Password to the Employee's e-mail:

- [x] Configuring **parameter 33** and correctly indicating the instance's URL;
- [x] Configuring **parameter 455** with the e-mail template ID created to send the access data;

:::hint{type="success"}
✅ ***Rule*****:&#x20;**&#x49;n the e-mail template, the $\{LOGIN} and $\{NEWPASSWORD} keys must be included.
:::

:::BlockQuote
***Example Basic template***: "Dear user, here's the access data. Username: $\{LOGIN} and Password: $\{NEWPASSWORD}"
:::

## Procedure

1. Access the main menu `General Registration > Personnel Management > User`;
2. Complete the fields available;
3. Click on "**Save**".

:::hint{type="success"}
✅ ***Rule*****:&#x20;**&#x54;he system checks if there is an e-mail template for the new employee that has the password key to send via e-mail. The system manager registers or changes an employee login and password on the user screen. The system checks whether: the system uses the password policy and whether the user is LDAP or not. The system allows you to enter a new password. After saving, the system sends by e-mail the new data to the employee.
:::


[title] Importing the Service Portfolio
[path] Platform Administration/Untitled/

The purpose of this functionality is to <font color="#3b9f0f">**import the service portfolio**</font>. The import
&#x20;data can be viewed in the Service Portfolio.

## Before getting started

- [x] To import, it is necessary to generate the import spreadsheet template.

## Procedure

1. Access the functionality through the main menu `System > Data Importing and
    Loading > Service Portfolio Load`;
2. To register an import spreadsheet template, click on the "**Import**" tab;
3. Click on "**Choose File**" and select the file that has to be in the "**.xls**" or "**.xlsx**" format
   ;
4. Click on "**Import**".

:::hint{type="info"}
🖊 ***Note*****:&#x20;**&#x57;hen importing, if there is any inconsistency between the values adopted
&#x20;in the system and the values entered in the spreadsheet, the system will
&#x20;display an alert. &#x20;
:::


[title] Registering Domain Item
[path] Platform Administration/Untitled/

The **Domain Items** functionality is intended to **customize the field options of a
&#x20;certain system screen.** To use it, you should have knowledge about system
&#x20;codification.

This feature provides a variety of actions, such as <font color="#3b9f0f">**including, changing, and
 deleting a domain item**</font>.

## Before getting started

- [x] The domain item registration requires the previous registration of the domain.

## Procedure

1. Access the functionality through the main menu `System > Domain Settings >
    Domain Items`;
2. Click on "**New**";
3. Complete the fields available;
4. Click on "**Save**".


[title] Escalation Automatic Action
[path] Platform Administration/Automation/

This functionality has the objective of **scheduling action**. It will be the complement to create an escalation rule.&#x20;

This feature provides a variety of actions, such as <font color="#3b9f0f">**including, changing, and
 deleting escalation automatic action**</font>.

## Procedure

1. To access click on the main menu `System > Automatic Actions > Escalation
    Actions`;
2. Click on "**New**";
3. Complete the fields available;
4. Click on "**Save**".


[title] Automation
[path] Platform Administration/

## Batch Processing

This functionality allows the <font color="#3b9f0f">**registration of batch processing routines**</font>, that can be later used in other system routines.

These Routines include:

- E-mail verification
- Server time verification
- Automatic ticket distribution with workload balancing

## Before getting started

- [x] ****<font color="#3b9f0f">**CITSmart** </font>**Batch&#x20;**&#x70;rocessing uses Quartz for scheduling and processing system routines;
- [x] Therefore, before using any batch routine it is necessary to configure Quartz.

## Procedure

1. Access the functionality through the main menu `System > Batch Processing`;
2. Click on "**New**";
3. Complete the fields available (description, type \[Java class, RhinoScript,
   &#x20;SQL]; status; a cron expression that defines the routine execution time and
   &#x20;the context of the routine to be executed in the system);

Example of "**Class Java**" content:

```javascript
br.com.centralit.citcorpore.quartz.job.JobConfiguracaoAberturaAutomaticaViaEmail
```

4\. Click on "**Save**".

## Batch Routines

- Return server time
  - Type: RhinoScript
  - Content:
- Perform e-mail reading
  - Type: Java class
  - Content:

```javascript
br.com.centralit.citcorpore.quartz.job.JobConfiguracaoAberturaAutomaticaViaEmail
```


[title] Loading Metadata
[path] Platform Administration/Untitled/

This functionality is intended to <font color="#3b9f0f">**register the table information of the database**</font>.

## Procedure

1. Access the functionality through the main menu `System > Visions and
    Metadata > Load Metadata`;
2. Enter the table name or to display the complete list of all, click on
   &#x20;"**Load**".


[title] Automatic Actions of Incident/Request/Procedure
[path] Platform Administration/Automation/

Some events will present **a status where the action appropriate will need to be
&#x20;treated by the Incident Management process**, that is, this functionality is
&#x20;intended to register the automatic actions of incident/request/procedure. This
&#x20;registration will be associated with the automatic actions, where it will be used
&#x20;in the <font color="#3b9f0f">**CITSmart** </font>**Event Managers** registration of **Nagios, Zabbix, Inventory&#x20;**&#x61;nd
&#x20;**Events Correlated**.

The **Event Management** supports the incident management process because it is
&#x20;possible to detect early failures in the service and quickly work to avoid a
&#x20;service unavailability to the end-user.

This feature provides a variety of actions, such as <font color="#3b9f0f">**including, changing, and
 deleting automatic actions of incident/request/procedure**</font>.

## Before getting started

To register an automatic action of request/incident/procedure, it is necessary:

- [x] To register previously the unit, group, contract, link group to contract,
  &#x20;associating the requester (employees) already related to this group, to be
  &#x20;listed the contracts and requests related in the request screen;
- [x] To define the
  &#x20;service portfolio, the time of attendance, and periodic activity group.

## Procedure

1. Access the functionality through the main menu `System > Automatic Actions  > Incident/Request/Procedure Actions`;
2. Complete the fields available;
3. Click on "**Save**".


[title] Parametrization - System
[path] Platform Administration/Untitled/

The "**System**" parametrization is used to <font color="#3b9f0f">**change the characteristics**</font> about the
&#x20;<font color="#3b9f0f">**system authentication, inform the system URL, the several directories**</font> (GED, Log,
&#x20;Temporaries), <font color="#3b9f0f">**define the home screen, validate buttons permission**</font> (save, delete
&#x20;and search), <font color="#3b9f0f">**activate system log**</font> (audit), <font color="#3b9f0f">**define the language preference and
 others**</font>.

## Procedure

1. Access the functionality through the main menu `Parametrization > System`;
2. Define the value of the parameters (attributes);
3. Click on "**Save**";
4. The list below presents the "**System**" parameters and the purpose of each one
   &#x20;of them:

| **#**   | **Name**                                                                                                                                          | **Possible Values**                                                          | **Purpose**                                                                                                                                                                                                                                                                                                                                                                                                                             | **Additional Guidance**                                                                                                                                                                                                                                                                                                  |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **0**   | SOURCE - Information Source Configuration (for data federation) - (Eg: 0)                                                                         | Information Source Configuration (for data federation).                      | If you do not enter the parameter value, you cannot export the Configuration Management Database (CMDB) from the "Configuration Item Management" screen.                                                                                                                                                                                                                                                                                |                                                                                                                                                                                                                                                                                                                          |
| **15**  | Internal GED (Eg: Y or N)                                                                                                                         | Y or N                                                                       | Inform if the Electronic Document Management used is internal. Note: Currently the only way to use electronic document management is internal. By setting 'Y' to the Internal one, the system will create the folder defined by parameter 18 and will create a subfolder with the company ID and another subfolder named 'A'. The electronic document management files will be written to these folders.                                | If the 'N' value for the Internal GED is informed, the files will not be saved correctly, will not be saved in the correct location, and will not be encrypted.                                                                                                                                                          |
| **16**  | Internal GED in Database (Eg: Y or N)                                                                                                             | Y or N                                                                       | Inform if the Electronic Document Management (GED) used is internal to the Database.                                                                                                                                                                                                                                                                                                                                                    | Not applicable                                                                                                                                                                                                                                                                                                           |
| **17**  | External GED - Treatment Class                                                                                                                    |                                                                              | Inform the external GED class (Electronic Document Management).                                                                                                                                                                                                                                                                                                                                                                         | Not applicable                                                                                                                                                                                                                                                                                                           |
| **18**  | GED Directory (Eg: Windows - C:/gedCitsmart)                                                                                                      | E.g.: Windows - C:/gedCitsmart                                               | Define the directory for manipulation of the Electronic Document Management (GED) files.                                                                                                                                                                                                                                                                                                                                                | If you do not enter the GED directory, electronic document management will not work because it uses the directory for file encryption.                                                                                                                                                                                   |
| **19**  | Company Name                                                                                                                                      |                                                                              | Enter the company name.                                                                                                                                                                                                                                                                                                                                                                                                                 | Not applicable                                                                                                                                                                                                                                                                                                           |
| **22**  | AUTHENTICATION METHOD (1 - Personal, 2 - LDAP) (Eg: 1)                                                                                            | E.g.: 1                                                                      | Define which authentication method will be used in the system: 1 (Own) or 2 (LDAP).                                                                                                                                                                                                                                                                                                                                                     | If the LDAP authentication method is changed from 1 (Own) to LDAP, then there must be a synchronization between LDAP and <font color="#3b9f0f">**CITSmart**</font>, at that time it is common to have duplication of employees and users in the database, which can cause problems in authentication and access profile. |
| **32**  | DB - Database SCHEMA name - (Eg: Postgres - public)                                                                                               | E.g.: Postgres - public                                                      | Enter the name of the Database Schema that will be used by the application.                                                                                                                                                                                                                                                                                                                                                             | Not applicable                                                                                                                                                                                                                                                                                                           |
| **33**  | System access URL                                                                                                                                 |                                                                              | Enter the URL system access.                                                                                                                                                                                                                                                                                                                                                                                                            | If you do not enter the system URL correctly, some features will behave unexpectedly, for example, reports will not be generated.                                                                                                                                                                                        |
| **44**  | Upload Directory of the repositor path(Eg: Windows – C: /temp )                                                                                   | E.g.: Windows - C:/temp                                                      | Inform the directory to store the files that will be uploaded.                                                                                                                                                                                                                                                                                                                                                                          | If you do not enter the directory correctly, you will not be able to attach the files to the system.                                                                                                                                                                                                                     |
| **46**  | <font color="#3b9f0f">**CITSmart**</font>home screen? (Options: SD = Smart Decisions, SP = Smart Portal, EC = Centro de Experiência)              |                                                                              | Set the <font color="#3b9f0f">**CITSmart**</font> home screen                                                                                                                                                                                                                                                                                                                                                                           | Not applicable                                                                                                                                                                                                                                                                                                           |
| **48**  | Validate button permissions (save, delete and search) (Eg: Y or N).                                                                               | Y or N                                                                       | Set if it will validate the access permission of the buttons: Save, Delete, and Search. If it is, the access permission to the buttons (Save, delete, and search) defined in the access profile will be validated.                                                                                                                                                                                                                      | Not applicable                                                                                                                                                                                                                                                                                                           |
| **52**  | Enable logging on the system (Eg: 'true' or 'false')                                                                                              | E.g.: true or false                                                          | Enable Audit Log on the System.                                                                                                                                                                                                                                                                                                                                                                                                         | Not applicable                                                                                                                                                                                                                                                                                                           |
| **53**  | Types: 'CIT\_LOG' (log file), 'DB\_LOG' (save in the database)                                                                                    |                                                                              | Set the system log type "CIT\_LOG" (logfile) or "DB\_LOG" (save in the database). If the Log type is "CIT\_LOG", the Log file is saved to a directory (defined in parameter 54). If the Log type is "DB\_LOG", it will be saved to the Database.                                                                                                                                                                                        | Not applicable                                                                                                                                                                                                                                                                                                           |
| **54**  | Path of the folder that will be the LOG file (Eg: Linux -/var/tmp/)                                                                               | E.g.: Linux - /var/tmp/                                                      | Inform the directory (folder) to store the Log files (CIT\_LOG). When you set the value 'CIT\_LOG' to parameter 53, you must define in this parameter the directory where the log file will be stored.                                                                                                                                                                                                                                  | If you do not enter the directory, the Log files (CIT\_LOG) will not be stored.                                                                                                                                                                                                                                          |
| **55**  | Name of the log file (Eg: log\_citsmart)                                                                                                          | E.g.: log\_citsmart                                                          | Define the name for the log file. The log files will be saved with the name as defined in the parameter.                                                                                                                                                                                                                                                                                                                                | Not applicable                                                                                                                                                                                                                                                                                                           |
| **56**  | Extension of the log file (Eg: txt)                                                                                                               | E.g.: txt                                                                    | Define the extension of the Log file. The Log files will be written with the TXT extension, as defined in the parameter.                                                                                                                                                                                                                                                                                                                | Not applicable                                                                                                                                                                                                                                                                                                           |
| **66**  | Default system language (Eg: EN)                                                                                                                  | E.g.: EN = English                                                           | Set the default language to be used in the application.                                                                                                                                                                                                                                                                                                                                                                                 | Not applicable                                                                                                                                                                                                                                                                                                           |
| **70**  | Show xml import and export buttons in the menu bar. (Eg: Y or N - Default: 'Y')                                                                   | Y or N (Default: S)                                                          | Define whether the XML import and export buttons are displayed on the Menu Registration screen. If "Y" is entered, the "Generate XML" and "Update Menus" buttons for XML import and export will be displayed in the "Menu Registration" screen.                                                                                                                                                                                         | If you do not enter the parameter value, the system default value will be set: "Y" (Yes).                                                                                                                                                                                                                                |
| **71**  | Parameter to read the default XML file from menus. (Eg: Y or N - Default: 'Y')                                                                    | Y or N (Default: Y)                                                          | Enable reading of the XML file from menus. If enabled, the menu XML file will be read when the application starts.                                                                                                                                                                                                                                                                                                                      | If you do not enter the parameter value, the system default value will be set: "N" (No).                                                                                                                                                                                                                                 |
| **117** | Enter the path to save the table LOGDATA                                                                                                          |                                                                              | Define the directory to store the LOGDATE tables.                                                                                                                                                                                                                                                                                                                                                                                       | If you do not enter the directory correctly, you will not be able to store the LOGDATE tables.                                                                                                                                                                                                                           |
| **118** | Default Contract ID for call opening.                                                                                                             |                                                                              | Inform the identification number (ID) of the contract to perform the opening of incidents/requests through the portal.                                                                                                                                                                                                                                                                                                                  | If you do not enter the value of the parameter, it is not possible to open the incident/request via the portal.                                                                                                                                                                                                          |
| **131** | Set the number of items that will be listed in the searches   (Default: 10)                                                                       |                                                                              | Define the amount of data that will be listed per page in the System Search screens.                                                                                                                                                                                                                                                                                                                                                    | There is no negative impact. If you do not enter the parameter value, the system default value is used: 10.                                                                                                                                                                                                              |
| **135** | Access Profile ID to be used as Administrator                                                                                                     |                                                                              | Enter the identification number (ID) of the access profile that will be used as the administrator for the validation of **ITSM&#x20;**<font color="#3b9f0f">**CITSmart**</font> updates. Only users related to the Access Profile defined in this parameter can access and validate the CTSmart ITSM version update.                                                                                                                    | Not applicable                                                                                                                                                                                                                                                                                                           |
| **136** | Default URL logo of reports (Eg.: [http://www.citsmart.com.br/imagens/logoPadraoReel.png](http://www.citsmart.com.br/imagens/logoPadraoReel.png)) |                                                                              | Enter the URL of the image that will be used as a logo in the reports.                                                                                                                                                                                                                                                                                                                                                                  | Not applicable                                                                                                                                                                                                                                                                                                           |
| **198** | Path of the folder that will be the database LOG file (Eg.: Linux - /var /tmp/)                                                                   |                                                                              | Inform the directory (folder) to store the database LOG files.                                                                                                                                                                                                                                                                                                                                                                          | If you do not enter the directory, you will not be able to store the database LOG files.                                                                                                                                                                                                                                 |
| **219** | Enable Automatic Data Migration                                                                                                                   |                                                                              | Enable/disable the data import routine to run automatically.                                                                                                                                                                                                                                                                                                                                                                            | With the parameter enabled, it will enable a thread that will be executed, which in addition to decreasing performance, can write error messages in the system logs if the data import is not correctly registered. If you enter "N", it will not automatically import data.                                             |
| **223** | E-mail Configuration of the <font color="#3b9f0f">**CITSmart**</font> Support                                                                     | E.g.: [suporte.citsmart@citsmart.com](mailto\:suporte.citsmart@citsmart.com) | Set the <font color="#3b9f0f">**CITSmart**</font> support email that will be displayed in the information bar. Note: The system allows you to add one or more support e-mails.                                                                                                                                                                                                                                                          | Not applicable                                                                                                                                                                                                                                                                                                           |
| **224** | Phone Configuration of the <font color="#3b9f0f">**CITSmart**</font> Support                                                                      | E.g.: +55 (61) 3966-4349                                                     | Set the <font color="#3b9f0f">**CITSmart**</font> support phone number to be displayed in the information bar. Note: The system allows you to add one or more support phone numbers.                                                                                                                                                                                                                                                    | Not applicable                                                                                                                                                                                                                                                                                                           |
| **225** | Email Configuration of the <font color="#3b9f0f">**CITSmart**</font> Support Login Screen                                                         | E.g.: [suporte.citsmart@citsmart.com](mailto\:suporte.citsmart@citsmart.com) | Set the <font color="#3b9f0f">**CITSmart**</font> support email to be displayed on the login screen. Note: The system allows you to add one or more support e-mails.                                                                                                                                                                                                                                                                    | Not applicable                                                                                                                                                                                                                                                                                                           |
| **226** | Phone Configuration of the <font color="#3b9f0f">**CITSmart**</font> Support Login Screen                                                         | E.g.: +55 (61) 3966-4349                                                     | Set the <font color="#3b9f0f">**CITSmart**</font> support phone number to be displayed on the login screen. Note: The system allows you to add one or more support phone numbers.                                                                                                                                                                                                                                                       | Not applicable                                                                                                                                                                                                                                                                                                           |
| **235** | Use Autocomplete in the unit field on the Employee and Unit screens. (Y or N - Default: 'N')                                                      | Y or N (Default: N)                                                          | Set if the screen object for the Drive field will be an Auto Complete (value = Y) or a checkbox (combobox) (value = N).                                                                                                                                                                                                                                                                                                                 | Change how the user selects the unit in the Service Request, Problem Registration, and Request for Change screens. This parameter will not reflect the Unit field of the Service Request screen.                                                                                                                         |
| **244** | Home screen message                                                                                                                               |                                                                              | Enter a message that will appear on the System Login screen.                                                                                                                                                                                                                                                                                                                                                                            | When the parameter is not configured, the default message will be displayed on the Login screen.                                                                                                                                                                                                                         |
| **254** | API Key for use of Google services                                                                                                                |                                                                              | Enter the key that registers the consumption of Google services.                                                                                                                                                                                                                                                                                                                                                                        | Not applicable                                                                                                                                                                                                                                                                                                           |
| **266** | Default calendar ID                                                                                                                               |                                                                              | Set the default calendar for use in task recovery filters.                                                                                                                                                                                                                                                                                                                                                                              | Not applicable                                                                                                                                                                                                                                                                                                           |
| **271** | Enter the city of installation of the system:                                                                                                     |                                                                              | Enter the name of the city that will appear in the system reports.                                                                                                                                                                                                                                                                                                                                                                      | Not applicable                                                                                                                                                                                                                                                                                                           |
| **275** | Always keep the system in English?                                                                                                                | Y or N (Default: N)                                                          | Set if the system language will be in English only.                                                                                                                                                                                                                                                                                                                                                                                     | Not applicable                                                                                                                                                                                                                                                                                                           |
| **276** | URL Power BI Report                                                                                                                               |                                                                              | Inform the URL of the Power BI tool for building dynamic reports for ITIL processes. When you enter the URL of the tool, when you access the "Power BI Manager Reports" functionality, the reporting tool will be displayed.                                                                                                                                                                                                            | If you do not enter the parameter value, you will not have access to the Power BI tool.                                                                                                                                                                                                                                  |
| **277** | Allow the registration of an employee with the same name? Values: "Y" for "Yes" and "N" for "No". Default: "N"                                    | Y or N (Default: N)                                                          | Define if the registration of an employee will be allowed with a name similar to another employee. When its value is "Y", the system allows the user to register an employee with the same name as another employee already registered, but with a different ID. It also makes the ID field mandatory. When the value "N" is entered, the system does not allow a user with a name similar to another registered user to be registered. | If the value for the parameter is not set, the value "N" will be automatically set by the system.                                                                                                                                                                                                                        |
| **278** | Maximum file size, in bytes, for upload. Default \[1073741824]                                                                                    |                                                                              | Limit the number of Bytes that can be uploaded per file in the system attachment screens.                                                                                                                                                                                                                                                                                                                                               | The size of the file that will be loaded in the attachments screens on service request, problem, change, release, continuity, and BI control panel will be limited.                                                                                                                                                      |
| **297** | Disables sending system emails (Values: "Y" or "N" Default: "N"                                                                                   | Y or N (Default: N)                                                          | Disables all system email submissions.                                                                                                                                                                                                                                                                                                                                                                                                  | Not applicable                                                                                                                                                                                                                                                                                                           |
| **318** | List of file extensions that can not be attached (For more than one extension, separated by semicolons)                                           |                                                                              | List of file extensions that cannot be attached                                                                                                                                                                                                                                                                                                                                                                                         | Not applicable                                                                                                                                                                                                                                                                                                           |
| **319** | Enable Remote Access                                                                                                                              |                                                                              | URL to open remote access screen                                                                                                                                                                                                                                                                                                                                                                                                        | Not applicable                                                                                                                                                                                                                                                                                                           |
| **320** | Category ID Gallery for uploading the images added in the editor (Eg: 1)                                                                          | E.g.: 1                                                                      | Set the gallery ID that will be used to upload images added in the editor                                                                                                                                                                                                                                                                                                                                                               | Not applicable                                                                                                                                                                                                                                                                                                           |
| **331** | Enable Google Maps API                                                                                                                            | Y or N                                                                       | Activate Google Maps API                                                                                                                                                                                                                                                                                                                                                                                                                | Not applicable                                                                                                                                                                                                                                                                                                           |
| **334** | Path to Start Logo (Eg: /citsmart/path/logo.png)                                                                                                  | E.g.: /citsmart/path/logo.png                                                | It allows the login screen logo to be changed.                                                                                                                                                                                                                                                                                                                                                                                          | Not applicable                                                                                                                                                                                                                                                                                                           |
| **335** | Path to Portal Logo (Eg: /citsmart/path/logo-portal.png)                                                                                          | E.g.: /citsmart/path/logo-portal.png                                         | It allows the Portal logo to be changed.                                                                                                                                                                                                                                                                                                                                                                                                | Not applicable                                                                                                                                                                                                                                                                                                           |
| **336** | Path to the System Logo (Eg: /citsmart/path/logo-system.png)                                                                                      | E.g.: /citsmart/path/logo-sistema.png                                        | It allows the System logo to be changed.                                                                                                                                                                                                                                                                                                                                                                                                | Not applicable                                                                                                                                                                                                                                                                                                           |
| **337** | Make the 'Physical Location' field mandatory in the Y or N Service register (default N)                                                           |                                                                              | Make the 'Physical Location' field mandatory in the Service register                                                                                                                                                                                                                                                                                                                                                                    | Not applicable                                                                                                                                                                                                                                                                                                           |
| **341** | Contact setup for Ombudsman on the login screen                                                                                                   |                                                                              | It allows informing the telephone/e-mail of the Ombudsman, information that will appear in the login screen of the system.                                                                                                                                                                                                                                                                                                              | Not applicable                                                                                                                                                                                                                                                                                                           |
| **344** | Ombudsman - Default URL for screen logo                                                                                                           |                                                                              | It allows informing the link of a logo to the Ombudsman screen.                                                                                                                                                                                                                                                                                                                                                                         | Not applicable                                                                                                                                                                                                                                                                                                           |
| **345** | Ombudsman - Reporting service ID                                                                                                                  |                                                                              | It allows informing the code of the denunciation activity of a portfolio used in the opening of an Ombudsman ticket.                                                                                                                                                                                                                                                                                                                    | Not applicable                                                                                                                                                                                                                                                                                                           |
| **346** | Ombudsman - Complaint Service ID                                                                                                                  |                                                                              | It allows informing the code of the complaint activity of a portfolio used in the opening of an Ombudsman ticket.                                                                                                                                                                                                                                                                                                                       | Not applicable                                                                                                                                                                                                                                                                                                           |
| **347** | Ombudsman - suggestion service ID                                                                                                                 |                                                                              | It allows informing the code of the suggestion activity of a portfolio used in the opening of an Ombudsman ticket.                                                                                                                                                                                                                                                                                                                      | Not applicable                                                                                                                                                                                                                                                                                                           |
| **348** | Ombudsman - User login for authentication                                                                                                         |                                                                              | It allows informing the user requester used in the opening of an Ombudsman ticket.                                                                                                                                                                                                                                                                                                                                                      | Not applicable                                                                                                                                                                                                                                                                                                           |
| **349** | Ombudsman - Contact Origin ID                                                                                                                     |                                                                              | It allows informing the origin code of the call used in the opening of an Ombudsman ticket.                                                                                                                                                                                                                                                                                                                                             | Not applicable                                                                                                                                                                                                                                                                                                           |
| **370** | Enable automatic email authentication via token                                                                                                   |                                                                              | It allows you to turn on or off the system's ability to receive token authentication.                                                                                                                                                                                                                                                                                                                                                   | Not applicable                                                                                                                                                                                                                                                                                                           |
| **378** | The minimum amount of registries that determines the generation of the report in the background.                                                  | E.g.: from 50.000 registries                                                 | Set a limit from which reports will be generated in the background.                                                                                                                                                                                                                                                                                                                                                                     | It causes reports on the Advanced Search screen to be generated in the background and when they are ready, a notification is sent to the user with a download link to the file.                                                                                                                                          |
| **383** | Enable login domain listing                                                                                                                       | E.g.: citsmart.com\ariadner.borges                                           | It allows to show or hide the list of domains on the login screen for security reasons. If the parameter is enabled, and the user enters a domain, the domain will be changed to type. If the user has typed a domain and changed the listing, the typed domain will also be changed.                                                                                                                                                   | Not applicable                                                                                                                                                                                                                                                                                                           |
| **384** | Query Timeout to Webservice DATA\_QUERY                                                                                                           | "Default:0"                                                                  | Maximum waiting time for the query response using Webservice DATA\_QUERY                                                                                                                                                                                                                                                                                                                                                                | The time set in the system is in seconds: 0 to 2.147.483.647 seconds.                                                                                                                                                                                                                                                    |
| **385** | Enable Related Request Creation as Copy                                                                                                           | Y or N                                                                       | It allows seeing the "create related request by copy" button on the internal service request screen. This button will open the screen to create a related request by copying the description, requester, attachments, related knowledge, and configuration items from the main service request.                                                                                                                                         | Not applicable                                                                                                                                                                                                                                                                                                           |
| **390** | Default unit ID                                                                                                                                   |                                                                              | Unit ID that will be assigned to the user registered in the profile                                                                                                                                                                                                                                                                                                                                                                     | Not applicable.                                                                                                                                                                                                                                                                                                          |
| **400** | Smart Analytics – URL Schema Gen                                                                                                                  |                                                                              | Parameter deprecated from version 9.0                                                                                                                                                                                                                                                                                                                                                                                                   | Not applicable.                                                                                                                                                                                                                                                                                                          |
| **401** | Smart Analytics – external URL                                                                                                                    |                                                                              | Path to BI Access                                                                                                                                                                                                                                                                                                                                                                                                                       | Not applicable.                                                                                                                                                                                                                                                                                                          |
| **402** | Anuva Assistant – external URL                                                                                                                    |                                                                              | Path for external access to Anuva                                                                                                                                                                                                                                                                                                                                                                                                       | Not applicable.                                                                                                                                                                                                                                                                                                          |
| **403** | Use SSO login authentication                                                                                                                      | Y or N                                                                       | It allows using Single Sign-On to login to the system                                                                                                                                                                                                                                                                                                                                                                                   | Not applicable.                                                                                                                                                                                                                                                                                                          |
| **405** | Machine Learning Configuration                                                                                                                    |                                                                              | It allows using Machine Learning to open calls. *NOTE: This parameter is found in the "*<font color="#3b9f0f">***CITSmart***</font> *Parameters" feature*                                                                                                                                                                                                                                                                               | Not applicable                                                                                                                                                                                                                                                                                                           |
| **409** | LDAP - Attribute representing the immediate superior of the user                                                                                  |                                                                              |                                                                                                                                                                                                                                                                                                                                                                                                                                         | Not applicable                                                                                                                                                                                                                                                                                                           |
| **449** | User Session Time (In Minutes)                                                                                                                    | E.g.: 120 minutes                                                            | Set expiration time for application sessions                                                                                                                                                                                                                                                                                                                                                                                            | Include in minutes the value you want for the session duration. After that, you need to disconnect and reconnect to the system, so the system will look for the new default for the session expiration time.                                                                                                             |
| **450** | Enable Anuva Assistant                                                                                                                            | Y or N                                                                       | Whether or not to enable Anuva in <font color="#3b9f0f">**CITSmart**</font>Workflow                                                                                                                                                                                                                                                                                                                                                     | The parameter reflects directly on the external Smart Chat (Experience Center and Smart Portal) and the internal button in the system header where the button is shown to talk to Anuva.                                                                                                                                 |

**Table 1 - Parameters List**


[title] Parametrization - Ticket
[path] Platform Administration/Untitled/

To deliver the service, it is necessary that some parameter settings allow
&#x20;**ticket management actions**, such as the <font color="#3b9f0f">**standard flow, the phase in which the
 service requests to be registered will be forwarded, and others**</font>.

## Procedure

1. Access the functionality through the main menu `Parametrization > Request
    and Incident Management`;
2. Set the parameter value to be configured;
3. Make the change;
4. Click on "**Save**";
5. The list below presents the ticket's functionality and the objective of each
   &#x20;one of them:

| **#**   | **Name**                                                                                                                                                               | **Possible Values**                                                                                                                                           | **Purpose**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | **Additional Guidance**                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **9**   | Group Level 1 ID (Eg: 1)                                                                                                                                               | E.g.: 1                                                                                                                                                       | Enter the identification number (ID) of the 1st level of attendance group. This group is the default to be used if the service is not informed. If <font color="#3b9f0f">**CITSmart**</font> is used in multiple contracts, this group must be defined in the contract services import template. This group ID is set on the "Group Registration" screen.                                                                                                                                                                                                                      | Not applicable                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| **30**  | Default phase ID for service execution (Ex: 2)                                                                                                                         | E.g: 2                                                                                                                                                        | Define the phase in which a service request to be registered will be forwarded. (1 = capture phase or 2 = execution phase).                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Not applicable                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| **31**  | Send email in the execution of request/incident flows (Eg: Y or N)                                                                                                     | Y or N                                                                                                                                                        | Define whether email notifications will be sent to the requester when performing the service/incident request flows.                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Not applicable                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| **40**  | Does the access control of the service catalog per unit (Eg: Y or N)?                                                                                                  | Y or N                                                                                                                                                        | Define if the access control of the service catalog will be per unit. If it is, a "Service" button will be available on the "Unit Registration" screen, to link the service (s) to the unit, where they will be displayed in the service request according to the unit of the requester informed.                                                                                                                                                                                                                                                                              | Not applicable                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| **41**  | Does the control of employees linked to contracts (Eg: Y or N)?                                                                                                        | Y or N                                                                                                                                                        | Define if the control of employees will be done by contract. If it is, the contracts will be displayed on the "Group Registration" screen to link them to the group, where employees belonging to the group will be linked to the contracts.                                                                                                                                                                                                                                                                                                                                   | Not applicable                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| **42**  | Service requests registration page (default will be used if not informed)                                                                                              |                                                                                                                                                               | Inform the page that will be used for the registration of Service Requests/Incidents. Default: /pages/solicitacaoServicoMultiContratos/solicitacaoServicoMultiContratos.load                                                                                                                                                                                                                                                                                                                                                                                                   | There is no negative impact. If you do not enter the page, the default system page will be used:/pages/solicitacaoServicoMultiContratos/solicitacaoServicoMultiContratos.load.                                                                                                                                                                                                                                                                    |
| **50**  | Accept Value 0 (Zero) for quantity and cost of the activity? (Eg: Y or N)                                                                                              | Y or N                                                                                                                                                        | Define if will be accepted the value 0 (zero) for quantity and cost of the Service Activity. If it is, it will be allowed to execute a Work Order informing the value 0.00. If it is not, the system will not allow the execution of a Work Order without informing the amount due.                                                                                                                                                                                                                                                                                            | Not applicable                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| **57**  | The ID of the e-mail template will be sent to the destination group when escalating a request. (Eg: 4)                                                                 |                                                                                                                                                               | Enter the identification number (ID) of the email template. This email template will be sent to the target group when escalating a service/incident request. This email template ID is set on the "Email Template" screen.                                                                                                                                                                                                                                                                                                                                                     | If you do not enter the ID number of the email template, there's the possibility of not sending the correct email to the target group.                                                                                                                                                                                                                                                                                                            |
| **58**  | Notify the group when receiving a service request escalation (Eg: Y or N).                                                                                             | Y or N                                                                                                                                                        | Set whether to notify the group when receiving a service request/incident escalation. If it is, when escalating a service request/incident to the group, it will be notified via email.                                                                                                                                                                                                                                                                                                                                                                                        | If you do not enter the "S" value for the parameter, the group will not be notified upon receiving a service request/incident escalation.                                                                                                                                                                                                                                                                                                         |
| **61**  | Link contracts to the unit (Eg: Y or N)                                                                                                                                | Y or N                                                                                                                                                        | Define whether the contracts will be linked to the unit. If so, the contracts will be displayed on the "Unit Registration" screen to be linked to the unit.                                                                                                                                                                                                                                                                                                                                                                                                                    | Not applicable                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| **62**  | Identifies the service ID for service and incident requests                                                                                                            |                                                                                                                                                               | This parameter must be configured if the user portal is enabled. You must enter the service identifier (ID) for service/incident requests from the portal. This ID is available in the Service Catalog.                                                                                                                                                                                                                                                                                                                                                                        | Not applicable                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| **65**  | Identify the source ID of the service request default call                                                                                                             |                                                                                                                                                               | Enter the identification number (ID) of the Default Source to open the service Request/Incident. This ID is set on the "Source of Requests" registration screen.                                                                                                                                                                                                                                                                                                                                                                                                               | Not applicable                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| **69**  | Validate fields Cause and Solution Category of the service request page required (Eg: Y or N - Default: 'N')                                                           | Y or N (Default: N)                                                                                                                                           | Define whether the "Cause" and "Solution Category" fields of the Service Request/Incident screen are mandatory.                                                                                                                                                                                                                                                                                                                                                                                                                                                                | If you do not enter the parameter value, the system default value will be set: "N" (No).                                                                                                                                                                                                                                                                                                                                                          |
| **72**  | SMTP READING - Email Limit Loaded on Service Request                                                                                                                   | E.g.: 20                                                                                                                                                      | Set the limit of emails that will be loaded on the Service/Incident Request screen. By clicking on the "upload email" button on the Service/Incident Request screen, the number of e-mails as configured in the parameter will be loaded.                                                                                                                                                                                                                                                                                                                                      | Not applicable                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| **86**  | Show Incident service category (Eg: Y or N - Default 'S')                                                                                                              | Y or N (Default: Y)                                                                                                                                           | Define whether the Service Category appears on the Service Request/Incident screen. If the value "Y" is set, the "Service Category" field is displayed on the Service Request/Incident screen.                                                                                                                                                                                                                                                                                                                                                                                 | If you do not enter the parameter value, the system default value will be used: "Y" (Yes).                                                                                                                                                                                                                                                                                                                                                        |
| **103** | E-mail template ID for sending service change notification (Eg: 19)                                                                                                    |                                                                                                                                                               | Enter the ID number of the notification for the E-mail Template of service change. When you change the Service of the contract, the email template defined in this parameter will be used to send the service change notification. This notification will be sent to the user and/or group associated with the service. This email template ID is set on the "Email Template" screen.                                                                                                                                                                                          | If you do not enter the Identifier (ID) of the Email Template, you may not send the correct email.                                                                                                                                                                                                                                                                                                                                                |
| **104** | Calculate the priority of the request dynamically using the registered formula. (Eg: Y or N - Default: 'N')                                                            | Y or N (Default: N)                                                                                                                                           | Define whether to calculate the priority of the request using the registered formula. If "Y" is informed, the priority of the request will be calculated dynamically using the registered formula.                                                                                                                                                                                                                                                                                                                                                                             | If you do not enter the parameter value, the system default value will be used: "N" (No).                                                                                                                                                                                                                                                                                                                                                         |
| **105** | Source ID that will be set by default when creating a new incident                                                                                                     |                                                                                                                                                               | Enter the identification number (ID) of the Default Source to open the service Request/Incident. This source ID is set on the "Source of Requests" registration screen.                                                                                                                                                                                                                                                                                                                                                                                                        | Not applicable                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| **113** | Email template ID for auto-escalation                                                                                                                                  |                                                                                                                                                               | Enter the identification number (ID) of the auto-escalation email template. Automatic escalation occurs when setting up the service level agreement, that after NN minutes (according to configuration) the system must escalate to the group or priority (as configured on the service level agreement screen). This email template ID is set on the "Email Template" screen.                                                                                                                                                                                                 | If you do not enter the identification number (ID) of the email template, you may not send the correct email.                                                                                                                                                                                                                                                                                                                                     |
| **115** | Unlink physical location with the unit? (Eg: Y or N - Default: 'N')                                                                                                    | Y or N (Default: N)                                                                                                                                           | Define if the linkage between the physical location with the unit will be removed. If "Y" is informed, the physical location link with the unit will be removed, that is, the location will not be established when informing the unit when registering a service/incident request.                                                                                                                                                                                                                                                                                            | If you do not enter the parameter value, the system default value will be set: "N" (No).                                                                                                                                                                                                                                                                                                                                                          |
| **119** | Type of Requests/Incidents capture (1-In execution, 2-In targeting) (Default: 1)                                                                                       | 1- At execution or 2- Directing (Default: 1)                                                                                                                  | Define the type of Requests/Incidents capture: 1 = At execution or 2 = Directing;                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | If you do not enter the value of the parameter, the system default value will be used: "1" = At execution.                                                                                                                                                                                                                                                                                                                                        |
| **134** | Default group ID for meeting HR requisitions                                                                                                                           |                                                                                                                                                               | Enter the identification number (ID) of the standard group for the fulfillment of Human Resources requests. This ID is set on the "Group Registration" screen.                                                                                                                                                                                                                                                                                                                                                                                                                 | Not applicable                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| **137** | E-mail template ID to send notification of a "bad" or "regular" evaluation in a satisfaction survey                                                                    |                                                                                                                                                               | Inform the notification email template identification number of a "bad" or "regular" evaluation email in a satisfaction survey. When a request satisfaction survey receives a negative value (regular or bad), the notification email (entered in the parameter) is sent to the determined group (configured in parameter 138), informing the evaluation data made.                                                                                                                                                                                                            | If you do not enter the identification number (ID) of the email template, you may not send the correct email.                                                                                                                                                                                                                                                                                                                                     |
| **138** | The ID of the group receiving e-mail notification of a "bad" or "regular" evaluation in a satisfaction survey                                                          |                                                                                                                                                               | Enter the identification number (ID) of the group that will receive the notification email of a "bad" or "regular" evaluation performed on a satisfaction survey, so that action is taken on that negative evaluation. This group ID is set on the "Group Registration" screen.                                                                                                                                                                                                                                                                                                | If you do not enter the group ID number, the email will not be sent.                                                                                                                                                                                                                                                                                                                                                                              |
| **139** | Deadline in days to respond to a satisfaction survey regarding service requests (Eg. 7)                                                                                |                                                                                                                                                               | Define the term (in days) to respond to the satisfaction survey regarding service requests. If the satisfaction survey is not answered, the deadline in days (as defined in the parameter) will be established to be automated answered.                                                                                                                                                                                                                                                                                                                                       | Not applicable                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| **151** | Use automatic approval for unanswered satisfaction surveys (Eg: Y or N - Default: 'N')                                                                                 | Y or N (Default: N)                                                                                                                                           | Enable automatic satisfaction survey approval, if not answered.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Not applicable                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| **152** | Standard note for automatic satisfaction search. (Use a valid ID of a degree of satisfaction)                                                                          |                                                                                                                                                               | Set the default note for the satisfaction survey. If automatic satisfaction survey approval is enabled, the satisfaction survey automatic answer will be established, as defined in this parameter.                                                                                                                                                                                                                                                                                                                                                                            | Not applicable                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| **171** | Days limit for reopening of services Incidents/Requests.                                                                                                               |                                                                                                                                                               | Set the days limit for reopening the Incident/Service Request.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Not applicable                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| **182** | Folder to save the Description and the solution to the service request in the Knowledge Base (Eg: Windows - Description\_Response\_To\_KnowledgeBase)                  | E.g.: Windows - Description\_Answer \_To\_KnowledgeBase                                                                                                       | Define the directory to store the answer description of the service/incident request to be saved in the knowledge base. In the Service Request/Incident screen, the field "Save Solution/Response in the Knowledge Base" is displayed. When answering a service/incident request, and if you want to save the description of the Response Solution in the knowledge base, simply select the field and inform the title, then, when saving and forward the flow, the description of the solution response of the request will be stored in the folder defined in the parameter. | Not applicable                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| **190** | Activate the escalation rules work? (Eg: Y or N - Default: 'N')                                                                                                        | Y or N (Default: N)                                                                                                                                           | Define whether the operation of scheduling rules is enabled.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | If you do not enter the parameter value, the system default value will be set: "Y" (Yes).                                                                                                                                                                                                                                                                                                                                                         |
| **192** | Show Save Solution/Response in the Knowledge Base? NOTE: It will only show when creating a New Request if the Situation is marked 'Solved'. (Eg: Y or N - Default 'S') | Y or N (Default: Y)                                                                                                                                           | Define if the Service Request/Incident Solution/Response will be saved in the Knowledge Base. In the Service Request/Incident screen, the field "Save Solution/Response in the Knowledge Base" will be displayed, in which you must enter the title for the solution/response. In this case, when saving the information of the service/incident request, it'll be saved in the Knowledge Base the solution/response of the request.                                                                                                                                           | If you do not enter the parameter value, the system default value will be set: "Y" (Yes).                                                                                                                                                                                                                                                                                                                                                         |
| **195** | Email template id for sending a  notification about a request with the deadline to be expired (Eg.: 1)                                                                 |                                                                                                                                                               | Enter the identification number (ID) of the request notification email template with the deadline to be expired. When creating an escalation rule, the deadline for the request is defined, where an email will be sent to the user (defined in parameter 197) notifying the deadline for the request.                                                                                                                                                                                                                                                                         | If you do not enter the identification number (ID) of the email template, you may not send the correct email.                                                                                                                                                                                                                                                                                                                                     |
| **197** | Login of the user who will receive an e-mail regarding the escalation rules of the service request that are being expired (Eg.: Consultant)                            |                                                                                                                                                               | Define the login of the user who will receive the email about the service request escalation rules that are expiring. When we create a scheduling rule, we set the deadline for the request, and the user login defined in this parameter will receive an email notifying that the request has entered the "expiring" status.                                                                                                                                                                                                                                                  | If you do not inform the user login, the email will not be sent.                                                                                                                                                                                                                                                                                                                                                                                  |
| **200** | Enable routine for reading new emails automatically? (Eg: Y or N - Default 'N')                                                                                        | Y or N (Default: N)                                                                                                                                           | Enable the automatic email reading routine. This routine, when enabled, works as follows: When sending an email to <font color="#3b9f0f">**CITSmart**</font> support, the automatic email will be read, if the email refers to a request, the title of the email will be checked if it contains the word 'Request' and the request number, if it contains, the email will be stored as an occurrence in the request concerned.                                                                                                                                                 | If you do not enter the value for the parameter, the system default value will be set: "N" (No).                                                                                                                                                                                                                                                                                                                                                  |
| **215** | Receive a notification when closing/escalating linked requests (Eg: Y or N - Default: 'Y')                                                                             | Y or N (Default: Y)                                                                                                                                           | Enable or disable sending notifications of child requests to the executor group of parent requests. By reporting the 'Y' value for the parameter, the system sends parent notification requests to the executing group for notification of creation, escalation, capture, other changes, and closure of child service requests. The email template linked to the child request service will be used.                                                                                                                                                                           | Not applicable                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| **216** | The ID of e-mail template creation that will be sent to the executor group of the related request                                                                      |                                                                                                                                                               | Enter the identification number (ID) of the creation email template that will be sent to the executor group of a request related to another one. This email template ID is set on the "Email Template" screen.                                                                                                                                                                                                                                                                                                                                                                 | If the identification number (ID) is not correctly entered, the system will not send notification emails.                                                                                                                                                                                                                                                                                                                                         |
| **217** | The ID of e-mail action template that will be sent to the executor group of the related request                                                                        |                                                                                                                                                               | Inform the identification number (ID) of the email template of other actions that will be sent to the executing group of a request related to another one. This email template ID is set on the "Email Template" screen.                                                                                                                                                                                                                                                                                                                                                       | If the identification number (ID) is not correctly entered, the system will not send notification emails.                                                                                                                                                                                                                                                                                                                                         |
| **218** | ID closing email template that will be sent to the executor group of the related request                                                                               |                                                                                                                                                               | Enter the identification number (ID) of the closing email template that will be sent to the executing group of a request related to another request. This email template ID is set on the "Email Template" screen.                                                                                                                                                                                                                                                                                                                                                             | If the identification number (ID) is not correctly entered, the system will not send notification emails.                                                                                                                                                                                                                                                                                                                                         |
| **227** | Identifier of the flow element that is responsible for executing the service request                                                                                   |                                                                                                                                                               | Define the flow element responsible for executing the service request.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Not applicable                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| **231** | Allow email sending when an incident is edited (Eg: Y or N - Default: 'Y')                                                                                             | Y or N (Default: Y)                                                                                                                                           | Enable/Disable sending notification of changes in the request (incident) by email to the requester. When the parameter is enabled, when there is a change in the request information (incident), an email will be sent to the requester notifying about it.                                                                                                                                                                                                                                                                                                                    | Not applicable                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| **251** | E-mail template ID to notify requester about the release of request occurrences                                                                                        |                                                                                                                                                               | Enter the identification number (ID) of the email template that will be used to notify the requester about the occurrence of the request. This Email Template ID is set on the "Email Template" screen.                                                                                                                                                                                                                                                                                                                                                                        | With the identification number of the email template that will be used to notify the requestor whenever a permitted occurrence has opened the viewer of the requestor. If the identification number (ID) is not correctly entered, the system will not send notification e-mails.                                                                                                                                                                 |
| **260** | Type hierarchy of the filter unit (Default 1-List without Restriction, 2-Units of the logged employee)                                                                 | E.g.: 1 Unrestricted unit; 2- Unit of employee and its children units (restrictive); 3- Unit of the employee together with his superior levels (restrictive). | Define which type of hierarchy will be used to generate the tree of units that an employee is allowed to access.                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Changing how the system will generate the tree of units allowed for a user/employee, many units may not be viewed if the hierarchy type uses access restriction.                                                                                                                                                                                                                                                                                  |
| **261** | Number of Registries Returned in Advanced Search (Eg: 50)                                                                                                              |                                                                                                                                                               | Define how many registries will be returned by the system in the Advanced Search for Service Request.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | If you do not enter the value of the parameter, the system will return all registries related to the user search in the Advanced Search Service Search. Any value that the user enters will limit the amounts of search registries to the value of the parameter. If the user search has more registries than the one defined by the parameter, the system will represent a related error message and will not return any registries to the user. |
| **264** | Filter by Request in Progress                                                                                                                                          | Y or N                                                                                                                                                        | If the "Y" value is set for the parameter, the "In Progress" option in the Portal's "Status" field, will be selected by default and will return a list of requests only with a request whose current task is equal to 'In Progress'.                                                                                                                                                                                                                                                                                                                                           | Not applicable                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| **274** | Filter the "Service Category" by the CONTRACT and/or SERVICE in the Service Request? Values: "Y" or "N". Default: "S"                                                  | Y or N (Default: S)                                                                                                                                           | Define whether the service category filter on the service request screen is by the contract service. If enabled, in the request registration screen, only the service categories that are linked to the service of the contract will be available.                                                                                                                                                                                                                                                                                                                             | Not applicable                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| **288** | URL Logo satisfaction survey. (Eg.: [http://www.citsmart.com.br/imagens/logo.png](http://www.citsmart.com.br/imagens/logo.png))                                        | E.g.: citsmart.com/ imagens/logo.png                                                                                                                          | Inform the URL of the image that will be used as a logo on the satisfaction survey screen.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Not applicable                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| **289** | Send Notification to Related Requests as configured for the Group? (Y or N)                                                                                            | Y or N                                                                                                                                                        | Set whether to send e-mail notifications to the executor group when creating a request related to another one.                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Not applicable                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| **290** | Email template ID sent when suspending a service request                                                                                                               |                                                                                                                                                               | Enter the ID number of the service request suspension email template. When suspending a service request, it will be used to send the suspension notification of the email template informed in this parameter. This notification will be sent to the requester. The email template ID is set in the "Email Template" screen                                                                                                                                                                                                                                                    | Not applicable                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| **291** | E-mail template ID sent when reactivating a service request                                                                                                            |                                                                                                                                                               | Enter the service request reactivation email template identification number (ID). Reactivating a service request will be used to send the reactivation notification of the e-mail template informed in this parameter. This notification will be sent to the requester. The email template ID is set in the "Email Template" screen.                                                                                                                                                                                                                                           | Not applicable                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| **294** | Requester selected when creating a Related Request: - Values: 0-None, 1-Requester, and 2-User logged in. Default: 0                                                    | Y or N (Default: S)                                                                                                                                           | Define whether, when creating a related request, the fields for completing the requester's data will be completed by the system with the data of the requester of the main request.                                                                                                                                                                                                                                                                                                                                                                                            | If the value for the parameter is not set, the value will be automatically set by the system: "Y" (Yes).                                                                                                                                                                                                                                                                                                                                          |
| **295** | Reopen Request by Satisfaction Survey (Possible values: Y or N, Default: N)                                                                                            | Y or N (Default: N)                                                                                                                                           | Enable the reopening of requests by satisfaction survey. When the parameter value is "Y", in the satisfaction search screen, it will display the "No Attended" option in the "Evaluation" field which, when selected, will display the button to reopen the service request. When the parameter value is "N", the "Not Attended" option will not be displayed in the "Evaluation" field, so the button to reopen the request will continue to be disabled and invisible to the user.                                                                                           | If the value for the parameter is not set, the value "N" will be automatically set by the system.                                                                                                                                                                                                                                                                                                                                                 |
| **296** | Name(s) of upper user approval flow (s) (separate by comma)                                                                                                            |                                                                                                                                                               | Configure the total of items that must be imported at one time from the base to Solr                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Not applicable                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| **299** | Request/Incident - Activate message exchange (Values: "Y" or "N" Default: "N")                                                                                         | Y or N (Default: N)                                                                                                                                           | Enable message exchange between the requester and the person responsible for the request                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Not applicable                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| **301** | Display the title of the request/incident (Values: "y" or "N" Default: "N")                                                                                            | Y or N (Default: N)                                                                                                                                           | Define whether the request/incident title field is displayed                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Not applicable                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| **306** | Support Level of Incident Management Tools                                                                                                                             |                                                                                                                                                               | The quality of the incident management tool to support the activities. Collected through comparison with existing functionalities in the tool and ITSM practices                                                                                                                                                                                                                                                                                                                                                                                                               | Not applicable                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| **307** | Maturity of the Incident Management Process                                                                                                                            |                                                                                                                                                               | The maturity with which we perform incident management activities, this information is collected through an assessment process.                                                                                                                                                                                                                                                                                                                                                                                                                                                | Not applicable                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| **343** | Narrow by attribution in advanced search? (Values: "Y" or "N" Default: "Y")                                                                                            | Y or N (Default: Y)                                                                                                                                           | Enables access control (security) to the Advanced Search feature.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Not applicable                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| **351** | Enables the creation of location occurrences through the unit during the creation of requests                                                                          | Y or N (Default: N)                                                                                                                                           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Not applicable                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| **372** | Enable mandatory fulfillment when suspending request                                                                                                                   | Y or N (Default: N)                                                                                                                                           | If this parameter is Yes, the system will show and require the completion of a text for the attendant to justify the reason for a ticket suspension.                                                                                                                                                                                                                                                                                                                                                                                                                           | Not applicable                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| **379** | Request Management Tool Support Level                                                                                                                                  |                                                                                                                                                               |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Not applicable                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| **380** | Maturity of the Request Management Process                                                                                                                             |                                                                                                                                                               |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |                                                                                                                                                                                                                                                                                                                                                                                                                                                   |

**Table 1- Parameters Table**

****

[title] Graph Mail
[path] Platform Administration/Automation/

# Presentation

The following documents describe the configuration and information concerning the Service Management project integration and the Microsoft e-mail service, utilizing the Microsoft Graph platform's SDK. This integration allows for delivering two main functionalities:

1. Sending Microsoft e-mails by Oauth2 authentication through Graph native integration;
2. E-mail reading and automatic actions shooting.

## Compatibility

- [x] Service Management version 2.3.0 or greater;
- [x] Graph-Mail version 1.1.2.

## Diagram

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/KA4JXEwZHXWWZHvX9PR6d_image.png)

# Development Configuration

This implementation does not substitute the previous POP3, SMT, and IMAP integration for other e-mail services. It can also be parametrized for being utilized simultaneously with those integrations.

# Procedure

For proceeding with usage and configurations, see the following documents:

[Development Guidelines](docId\:KlYA1e6B0ST826-LWP2PK)

[Graph Mail Project](docId\:VkkwD3lQmRrM8KiEJREcB)

[Service Management Project](docId:68t6iaVJ48ayDcwem5HKk)

[Cluster vs Competition](docId\:CgaPtCMeO6Zawdai1wlNr)

# References

The references from the presented documents are as follows:

- [https://docs.microsoft.com/en-us/exchange/client-developer/legacy-protocols/how-to-authenticate-animap-pop-smtp-application-by-using-oauth](https://docs.microsoft.com/en-us/exchange/client-developer/legacy-protocols/how-to-authenticate-animap-pop-smtp-application-by-using-oauth)
- [https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app)
- [https://learn.microsoft.com/en-us/graph/sdks/paging?tabs=java](https://learn.microsoft.com/en-us/graph/sdks/paging?tabs=java)
- [https://learn.microsoft.com/en-us/graph/api/mailfolder-list-messages?view=graph-rest-1.0\&tabs=java](https://learn.microsoft.com/en-us/graph/api/mailfolder-list-messages?view=graph-rest-1.0\&tabs=java)
- [https://learn.microsoft.com/en-us/graph/sdks/paging?tabs=Go](https://learn.microsoft.com/en-us/graph/sdks/paging?tabs=Go)
- [https://learn.microsoft.com/en-us/graph/api/user-list-messages?view=graph-rest-1.0\&tabs=java](https://learn.microsoft.com/en-us/graph/api/user-list-messages?view=graph-rest-1.0\&tabs=java)
- [https://learn.microsoft.com/en-us/graph/aad-advanced-queries?tabs=java](https://learn.microsoft.com/en-us/graph/aad-advanced-queries?tabs=java)
- [https://learn.microsoft.com/en-us/graph/api/message-delete?view=graph-rest-1.0\&tabs=http](https://learn.microsoft.com/en-us/graph/api/message-delete?view=graph-rest-1.0\&tabs=http)
- [https://learn.microsoft.com/en-us/graph/api/message-update?view=graph-rest-1.0\&tabs=http](https://learn.microsoft.com/en-us/graph/api/message-update?view=graph-rest-1.0\&tabs=http)
- [https://stackoverflow.com/questions/72262092/microsoft-graph-graphserviceclient-read-email-withanother-account](https://stackoverflow.com/questions/72262092/microsoft-graph-graphserviceclient-read-email-withanother-account)
- [https://learn.microsoft.com/en-us/graph/api/message-get?view=graph-rest-1.0\&tabs=http](https://learn.microsoft.com/en-us/graph/api/message-get?view=graph-rest-1.0\&tabs=http)
- [https://learn.microsoft.com/en-us/answers/questions/943114/get-unread-emails-one-by-oneonly-from-inbox-folde.html](https://learn.microsoft.com/en-us/answers/questions/943114/get-unread-emails-one-by-oneonly-from-inbox-folde.html)


[title] Registering Data Import
[path] Platform Administration/Untitled/

The purpose of this functionality is to import the data from another database to
&#x20;the <font color="#3b9f0f">**CITSmart** </font>database.

This feature provides a variety of actions, such as <font color="#3b9f0f">**including, changing, and
 deleting a data import**</font>.

## Before getting started

To import the data, it is necessary:

- [x] To have knowledge about programming and
  &#x20;databases;
- [x] In addition to previously registering the external connection.

## Procedure

1. Access the functionality through the main menu `System > Data Importing and
    Loading > Data Import`;
2. Depending on the import form chosen in the Import By field, different fields
   &#x20;are available;
3. Click on "**Run Routine**" to execute the data import;
4. Click on "**Save**".


[title] Knowledge Base E-mail Key Fields
[path] Platform Administration/Untitled/

This document is intended to <font color="#3b9f0f">**provide the list of key fields**</font> available for the
&#x20;knowledge base-related e-mail template.

## List of Key Fields

- [x] The key fields available for insertion in the knowledge base-related e-mail
  &#x20;template are listed below:

| **Key Fields**          | **Description**                                                                                  |
| ----------------------- | ------------------------------------------------------------------------------------------------ |
| **$\{APPROVEDNAME}**    | Approver of Knowledge. Inform the name of the approver of the knowledge.                         |
| **$\{AUTHOR}**          | Author of Knowledge. Inform the name of the author of the knowledge.                             |
| **$\{CONTENT}**         | Content of Knowledge. Inform the description of the content of knowledge.                        |
| **$\{EXPIRATIONDATE}**  | Expiration date. Inform the expiration date of the knowledge.                                    |
| **$\{INITIALDATE}**     | Date of Creation of Knowledge. Inform the date of knowledge creation.                            |
| **$\{PUBLICATIONDATE}** | Publication date. Inform the date of publication of the knowledge.                               |
| **$\{SOURCEREFERENCE}** | Source/Knowledge Reference. Inform the description of the source of the knowledge.               |
| **$\{OBSERVATION}**     | Justification/Observation. Inform the description of the justification/observation of knowledge. |
| **$\{ORIGINNAME}**      | Origin of Knowledge. Inform the identification of the origin of knowledge.                       |
| **$\{ORIGIN}**          | Origin of knowledge. Inform the origin of knowledge.                                             |
| **$\{PRIVACY}**         | Privacy of Knowledge. Inform the identification of the privacy of knowledge.                     |
| **$\{SITUATION}**       | The Situation of Knowledge. Inform the identification of the knowledge situation.                |
| **$\{TITLE}**           | Title of Knowledge. Inform the description of the title of knowledge.                            |
| **$\{VERSION}**         | The Version of Knowledge. Inform the version of knowledge.                                       |
| **$\{IDKNOWLEDGEBASE}** | Knowledge base identification. Inform the knowledge base identification.                         |

**Table 1 - List of Key Fields**


[title] Configuring Views
[path] Platform Administration/Untitled/

This functionality is intended to **allow the diverse vision** (screens) **creation of
&#x20;the system**, with the possibility to associate with linked visions (sub-screens).

This feature provides various actions, such as <font color="#3b9f0f">**including, changing, and deleting
 vision (screens) creation of the system**</font>.

## Procedure

1. Access the functionality through the main menu `System > Visions and
    Metadata > View Maintenance`;
2. Complete the fields available;
3. To add fields in the vision (screen) that is being created, click on "**Add
   &#x20;Field**";
4. To add a sub-screen to the vision, click on "**Add Linked View**";
5. To add buttons to the view that is being created, click on "**Action Buttons**".
6. To include JavaScript instructions/codes, click on "**Script**";
7. To include HTML instructions/codes, click on "**HTML Code** (additional)";
8. Click on "**Save**".


[title] Graph Mail Project
[path] Platform Administration/Automation/Graph Mail/

## Config File

The following properties must be set in the config.properties file of the Graph Mail Project, according to the client scenario:

:::BlockQuote
*JMS\_CONNECTION\_FACTORY\_JNDI = jms/RemoteConnectionFactory
JMS\_WILDFLY\_REMOTING\_URL = http-remoting://172.18.0.4:8080
JMS\_QUEUE\_JNDI = jms/queue/queue/graphMailQueue
JMS\_READ\_MAIL\_QUEUE\_JNDI = jms/queue/queue/readGraphMailQueue
JMS\_USERNAME = jmsuser
&#xA;*&#x4A;MS\_PASSWORD = 352TEDDWtHpfRObR166VOuOBI1F4
GRAPH\_APP\_ID = 51255c25-165446-25d5sd5d5-dssdsd
GRAPH\_USERNAME = [seue-mail@seudominio.gov.br](#)
GRAPH\_PASSWORD = QsPlWSOK
GRAPH\_MAIL\_FOLDERS\_LIST = Inbox
:::

### docker-compose.yml

The correct file localization in the docker-compose.yml file from the Graph Mail Project must be set. Also, set the defined folders for image and attachment sharing.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/zjcNOXXIHDUbahrK5c_Ks_image.png)

### Dependency

The Graph Mail Project depends on the Service Management project, so it should only be executed when the Service Management one is running.

**Functioning**

- A Thread or Job:
  - Obtains the e-mail messages occasionally and extracts the: **sender**, **subject**, **body**, and **attachments&#x20;**&#x66;rom the parameterized list of folders;
  - Registers messages received in a specific queue for registration of tickets in WildFly, containing the name of the folder, the queue, and the content of the email, including the list of attachments;
  - Etches the attachments to a mapped folder on a volume that SM is able to access;
  - Performs the "Email control procedure":
    - Processing control: the system reads a predefined folder, allowing the user to create filtering rules, specific to the ticket registration. It can be an incident, problem, change or release ticket: what determines it is the automatic action registration;
    - <font color="#ff0004">Destination of the processed message: the system marks the already processed message as read.</font>
    - Mailbox sharing:&#x20;
      - It can be used by the user and the system - if the folder for reading is implemented;
      - It will also be used for sending e-mails.


[title] Home Panel
[path] Initial Settings/

The home panel in the system main screen. In this panel, it is possible to
&#x20;add dashboards from a template or select manually.&#x20;

In this area, it is also
&#x20;available resources to create shortcuts (links), view reports and dashboards. Contains relevant information.

- Change Account Info
- Create Shortcuts
- Create your Dashboard
- Add widgets to your Dashboard


[title] Change E-mail Key Fields
[path] Platform Administration/Untitled/

This document is intended to <font color="#3b9f0f">**provide the list of key fields**</font> available for the
&#x20;change template-related e-mail template.

## List of Key Fields

- [x] The following key fields are listed below for insertion into the change
  &#x20;template-related e-mail template:

| **Key Fields**             | **Description**                                                                          |
| -------------------------- | ---------------------------------------------------------------------------------------- |
| **$\{DELAYSTR}**           | Delay time. Report the delay time of the change.                                         |
| **$\{ACCEPTANCEDATE}**     | Date of Acceptance. Inform the date of acceptance of the change.                         |
| **$\{COMPLETIONDATESTR}**  | Date of the conclusion. Inform the date of completion of the change.                     |
| **$\{CAPTUREDATETIME}**    | Date and Time of request Capture. Inform the date and time of the capture of the change. |
| **$\{STARTDATETIMESTR}**   | Start date. Reports the start date of the change.                                        |
| **$\{REQUESTDATETIMESTR}** | Request Record Date and Time. Report the date and time the change was recorded.          |
| **$\{ENDDATETIMESTR}**     | Limit date. Inform the deadline to meet the change.                                      |
| **$\{STARTDATE}**          | Meeting Start Date. Report the start date of the scheduled meeting.                      |
| **$\{VOTINGDATE}**         | Date of Voting. Inform the date of the vote to approve the change.                       |
| **$\{DESCRIPTION}**        | Description of Change. Report the description of the change.                             |
| **$\{ESTIMATEDDURATION}**  | Estimated duration. Report the estimated duration of the scheduled meeting.              |
| **$\{REQUESTEREMAIL}**     | Applicant's e-mail address. Inform the requestor e-mail of the change.                   |
| **$\{CLOSURE}**            | Closing. Inform the description of the closing of the change.                            |
| **$\{STARTTIME}**          | Meeting Start Time. Reports the start time of the scheduled meeting.                     |
| **$\{CHANGEREQUESTID}**    | Change Number. Inform the identification number of the change.                           |
| **$\{IMPACTLEVEL}**        | Impact. Reports the impact of the change.                                                |
| **$\{MEETINGLOCATION}**    | Place of the Meeting. Inform the location of the scheduled meeting.                      |
| **$\{URGENCYLEVEL}**       | Urgency. Inform the urgency of the change.                                               |
| **$\{NAMECATEGORYCHANGE}** | Category of Change. Report the change category.                                          |
| **$\{CONTACTNAME}**        | Contact name. Enter the name of the requester to contact.                                |
| **$\{CURRENTGROUP}**       | Current Group. Inform the current group responsible for meeting the change.              |
| **$\{NAMEGROUPLEVEL1}**    | Level 1 Group. Inform the level 1 group configured to meet the change.                   |
| **$\{REQUESTERNAME}**      | Name of Applicant. Inform the name of the requestor of the change.                       |
| **$\{TASKNAME}**           | Assignment. Reports the current job of the change.                                       |
| **$\{PRIORITY}**           | Priority. Inform the priority of the change.                                             |
| **$\{STATUS}**             | Status of Change. Reports the status of the change.                                      |
| **$\{TYPE}**               | Type of Change. Inform the type of change that has been registered.                      |
| **$\{TITLE}**              | Title of Change. Inform the title of the change that has been registered.                |

**Table 1 - List of Key Fields**

****

[title] Registering E-mail box
[path] Platform Administration/Untitled/

This functionality is designed to <font color="#3b9f0f">**configure the sending and receiving of e-mails from different servers**</font> in order to meet different contracts, so a <font color="#3b9f0f">**CITSmart** </font>can serve different clients and each one will have its own mailbox.&#x20;

In this case, you can use a send/read e-mail account (e.g.: [email@company.com](mailto\:email@company.com)) on an XPTO company contract, and another e-mail account belonging to a different business agreement (e.g.: [email@company2.com](mailto\:email@company2.com)).

## Procedure

1. Access the functionality through the main menu `Parametrization > Mailbox`;
2. Click on "**New**";
3. Choose the type of box. If you opt for the type "**Input**" (it means that the
   &#x20;user will parameterize a route where the e-mails that need to be read will
   &#x20;arrive), it will open new registration fields, such as server, server port,
   &#x20;user (e-mail address), password, provider, and inbox folder, therefore it is
   &#x20;necessary to fill in the fields;
4. If you opt for the type "**Output**" (it means that the user will parameterize the route where the e-mails that need to be sent from the system will exit),
   &#x20;it will open new registration fields, such as server, server port, user,
   &#x20;password, sender, set whether TSL/SSL authentication is required (both are
   &#x20;security protocols) and user authentication is, therefore, necessary to fill
   &#x20;in the fields;
5. Click on "**Save**";
6. Link the e-mail box to the contract. To do so: Access the functionality
   &#x20;`Processes > Portfolio and Catalog Management > Contract` and link the
   &#x20;previously registered email box in the "**E-mail**" field and click on "**Save**";
7. Link the e-mail box to a flow. Therefore:
   - Access the functionality `System > Flow Maintenance` and when
     &#x20;registering/editing a flow, find in the "**Diagram**" filed the
     &#x20;figure representing an e-mail in the flow and click on edit;
   - In the "Configure outbox e-mail" option, opened when clicking on the "**Message**" tab
     , select the "**Specific**" option to use the mailbox configured in
     &#x20;the contract;
   - Complete the flow parametrization, including the selected "**Recipients**";
   - The use of different e-mail outboxes can be noticed after a service request
     &#x20;is opened, which has parameterized the flow that has the selected
     &#x20;mailbox.
   - Click on "**Save**".

:::hint{type="info"}
🖊 ***Note*****:&#x20;**&#x4C;inking to the mailbox is not a required step. This functionality will
&#x20;only be necessary when registering the flow, the user feels the need to
&#x20;direct the email to an output box different from the default. The system's
&#x20;default e-mail outbox will continue to function even if this setting is not
&#x20;done.
:::


[title] Safety Recommendations
[path] Platform Administration/

For greater safety of your operating environment, we recommend:

1. The use of external authenticators, for example, **LDAP&#x20;**&#x6F;r **OAuth2&#x20;**&#x73;ervers. If your business does not have it, there are several OAuth2 standard security servers in cloud providers that can easily be integrated into the platform.
2. Avoid using local platform users. The security team detected in different versions of the platform, functionality non-compliance with international safety standards. Therefore, we recommend not using it. It will be discontinued in the next versions, and as described in item 1, there are fast, accessible, and safer alternatives to replace this feature.
3. Aligned to item 2, we recommend that after initial settings, all local users be removed from the platform. If there are any questions in this process, please activate the support channels.
4. We recommend the use of Captcha for facilities where there is access or visibility by the large external public, for example, citizens. This functionality can be activated through platform settings.
5. Set up an alert email for when you exceed the maximum number of failed authentication attempts on the platform. This functionality can be activated through platform settings.
6. For on-premises operating environments, i.e., hosted in customer responsibility facilities, we recommend using intrusion detection solutions. These solutions contribute to the safety of the operational environment as a whole. They are external to the platform, need to be acquired, implemented, and maintained by the customer.
7. Still, for on-premises operating environments, we recommend that all infrastructure components that support the platform, including the database server and the application server, have regular password change routines.
8. Also for on-premises operating environments, we recommend that the application server where the platform is installed does not have direct visibility on the internet, that is, we recommend the use of intermediate software (balancers, reverse proxy, or others) as a gateway to the platform, in addition to hiding internal details. It is also important to properly use firewall structures.
9. It is important to maintain and fully control all levels of user access. Check the roles of all employees in the organization to define appropriate access to a specific component or functionality. Ensure authorized user access to items strictly necessary for the performance of their tasks. Such recommendations apply to on-premises installations, where there are several profiles with access to infrastructure information, as well as access and functions within the platform. The manufacturer is not responsible for improper use of access management on the platform, as well as in the component structure.
10. We request that any identified security fragility situation be immediately referred to our support team or one of our authorized partners. Under no circumstances, make any kind of statement before proper analysis by the manufacturer’s security team, as such situations may be part of the existing recommendations package or be a situation related to double or additional protections. <font color="#3b9f0f">**CITSmart** </font>is a global **trademark, with patents registered and approved in the US, Europe, America, Africa, and Asia, and therefore unauthorized citations may be construed as a violation of rights**.


[title] Parametrization - Telephony
[path] Platform Administration/Untitled/

The "**Telephony**" parametrization allows <font color="#3b9f0f">**defining whether to enable the
 integration of web services with telephony**</font>, <font color="#3b9f0f">**to inform the identification number
 of the requested service,**</font> among other possible actions in order to configure the
&#x20;use of telephony in <font color="#3b9f0f">**CITSmart**</font>.

## Procedure

1. Access the functionality through the main menu `Parametrization > Telephony`;
2. Define the value of parameters (attributes);
3. Click on "**Save**";
4. The list below presents the "**Telephony**" parameters and the purpose of each
   &#x20;one of them:

| **#**   | **Name**                                                                                                                         | **Possible Values** | **Purpose**                                                                                                                                                                     | **Additional Guidance**                                                                           |
| ------- | -------------------------------------------------------------------------------------------------------------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| **281** | Enable Webservice for integration with Telephony - Values: "Y" or "N" Default: "N"                                               | Y or N (Default: N) | Define whether to enable web services integration with telephony.                                                                                                               | If the value for the parameter is not set, the value "N" will be automatically set by the system. |
| **282** | Should telephony launch a child request regarding viewing information for an existing request? - Values: "Y" or "N" Default: "N" | Y or N (Default: N) | Set whether to enable the automatic launch of a child service request, which is being viewed or executed, by the web service "view Request".                                    | If the value for the parameter is not set, the value "N" will be automatically set by the system. |
| **283** | Service ID of information request about an existing request.                                                                     | Y or N              | Enter the identification number (ID) of the service request, which will be used to launch the child request about the information visualization of an already existing request. | Not applicable                                                                                    |

**Table 1 - Parameters List**


[title] Notification Automatic Action 
[path] Platform Administration/Automation/

This functionality is intended to **register automatic action notifications**. The notification formalizes and communicates information about the event, and it is important that information about an event is described and completed to facilitate decision-making later. This registration will be associated with the automatic actions and will be used in the <font color="#3b9f0f">**CITSmart** </font>**Event Manager** registration of **Nagios, Zabbix, Inventory,&#x20;**&#x61;nd **Correlated Events**.

Event notifications should only be sent to those responsible for handling related actions or decisions. This avoids unnecessary notifications to those who are not directly involved in the event process.

This feature provides a variety of actions, such as <font color="#3b9f0f">**including, changing, and deleting notification automatic actions**</font>.

## Before getting started

To register a notification automatic action, it is necessary:

- [x] To register previously
  &#x20;the user and group.

## Procedure

1. Access the functionality through the main menu `System > Automatic Actions  > Notification Actions`;
2. Complete the fields available;
3. To link a user, click on the "**Add User**" tab and then on "**Add**";
4. To link a group, click on the "**Add Group**" tab and then on "**Add**";
5. To link an e-mail, click on the "**Add E-mails**" tab, enter the e-mail in the
   &#x20;field and then on "**Add**";
6. Click on "**Save**".


[title] Mobile
[path] Platform Administration/

The **Mobile&#x20;**&#x66;unctionality was developed to allow <font color="#3b9f0f">**greater autonomy in the management of services**</font>, since it allows the provision of services from different perspectives, either as an end-user service portal or as a flexible instance for the analyst to do field service.


[title] Service Management Project
[path] Platform Administration/Automation/Graph Mail/

## Attachments and Images Directory

Define the parameter ID = 479 value informing the attachments directory, where the files used to e-mail readout and dispatch will be stored; It also must be mapped in the volumes of the docker containers.

## E-mail dispatch

To utilize the e-mail dispatch through Graph Mail integration, it is necessary to define the parameter MAIL\_AUTHENTICATION\_TYPE – ID: 477 with the options Microsoft Graph Mail, for a general parameterization where the default value will be used: graphMailQueue, for the name of the mail queue. In case the user desires a configuration for each mailbox, configure the email box screen, with the name of the registered queues in WildFly:

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/SEE3IPDh008NqxIt8MTd6_image.png)

:::hint{type="warning"}
�&#xDCCC;***IMPORTANT!***

The email dispatch control was altered, therefore the old classes ***ControleEmail*** and ***ControleEmailNotificacao*** should not be used for sending in **rhino scripts**. Instead, the classes ***MensagemEmail*** or ***MensagemEmailNotificacao***.
:::

## E-mail readout

The system will read a Microsoft E-mail inbox through the Oauth2 authentication method, shooting registered and defined automatic actions for each inbox and folder. Provided by Microsoft, the SDK java will be utilized to simplify and make the integration safer and more adequate. This new implementation does not interfere with the reading process and automatic actions shooting (that already exist, or that use Job-Quartz) for e-mail readout using IMAP and POP3.

The Service Management Project:

- Listens to queues registered on the automatic action screen via e-mail;
- For each retrieved message, the system obtains the automatic action configured from the name of the queue and the folder; It also implements the feature to avoid multiple searches to the database for a configuration already retrieved, during processing;
- Processes the retrieved action using the contents of the retrieved message;

## Readout Configuration

The user must register the automatic actions, which must be shot with each e-mailed reading carried out by a Microsoft account; For correct operation and because the search is case-sensitive, it is necessary the name of the queue and folder to be exactly the same as those parameterized by the infrastructure. If during execution the system finds an automatic action configuration via e-mail that is active, that has a queue read by the system with the name and the registered folder is the same, the authentication type is MICROSOT\_GRAPH and the end date is empty, it will trigger this action passing as parameters the information read in the e-mail;

*It is important to point out that the scenario of folders for reading and automatic actions that must be triggered needs to be considered before starting the infrastructure configuration, bearing in mind that the static parameterizations cannot be changed within the system running, as it implicates onto changing standalone.xml, config.properties, and System-properties files.*

On the automatic action configuration via e-mail **screen**, it is still possible to configure the reading job via IMAP and POP3, as well as the new form of integration with Microsoft graph, as in the following image:

For the readout through Graph Mail:

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/PCP56hyNzNPDV7GCvRHfa_image.png)

Or through Job – **IMAP&#x20;**&#x6F;r **POP3**:

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/YdrewDM50VzIjcwDiyss7_image.png)


[title] Parametrization - LDAP
[path] Platform Administration/Untitled/

Unlike other product parameters, this configuration of parameters linked to LDAP
&#x20;integration occurs implicitly using the **LDAP Configuration** feature or explicitly
&#x20;using the <font color="#3b9f0f">**CITSmart** </font>**Parameters&#x20;**&#x66;eature.

## Procedure

1. Access the functionality through the main menu `Parametrization > CITSmart
    Parameters`;
2. Define the parameter value to be configured;
3. Make the change;
4. Click on "**Save**";&#x20;
5. The list below presents functionality parameters and the purpose of each
   &#x20;one of them:

| **#**   | **Name**                                                                                      | **Possible Values** | **Purpose**                                                                                                 | **Additional Guidance**                                                                                                                                                                                                                                                                          |
| ------- | --------------------------------------------------------------------------------------------- | ------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **39**  | LDAP - ID of the access profile that will be set automatically if the user does not have any. | E.g.: 2             | Enter the default Access Profile ID for the user.                                                           | When registering a user, and if the access profile is not informed, when the user logs into the application, the access profile (defined in the parameter value) will be established. This rule applies to users imported from AD. This Access Profile ID is set in the "Access Profile" screen. |
| **45**  | LDAP - Default Group ID.                                                                      | E.g.:123            | Enter the identification number (ID) of the default group, to which AD users will be associated             | This group ID is set on the "Group Registration" screen.                                                                                                                                                                                                                                         |
| **409** | LDAP - Attribute representing the immediate superior of the user                              | E.g.: Maria         | Name of the user's immediate superior in LDAP so that this information can be retrieved by the client's AD. | To be able to use in cases of approval of a ticket, for example.                                                                                                                                                                                                                                 |

**Table 1 - Parameters Table**


[title] Group of Employees
[path] Initial Settings/Users, Groups, Roles/Employee Registration/

A group is a set of one or more employees with the same related objectives and functions.

The two most common usages for the groups created are:

1. Security/secrecy management of access to various types of registries (e.g.: knowledge base folders, service portfolios, etc.).
2. Automatic notification scheduling based on some specific event/situation;

This functionality <font color="#3b9f0f">**allows you to register groups and link them to users, profiles, contracts, and e-mails for notification**</font>**.&#x20;**&#x49;t provides several actions, such as including, changing, and deleting a group.

## Before getting started

- [x] To register a group, it is necessary to register previously the employee profile
  &#x20;access.

## Procedure

1. Access the functionality Group through the main menu `Access and Permission  > Group`;
2. Click on "**New**";
3. Define the necessary configurations;
4. Click on "**Save**".

:::hint{type="success"}
✅ ***Rule*****:&#x20;**&#x54;he exclusion of a group depends on the fact that there are no portfolios, employees, or contracts linked to it.
:::


[title] Administração de Usuários, Grupos, Papéis e Parâmetros
[path] Initial Settings/


[title] Registering Countries
[path] Platform Administration/Untitled/

The purpose is to <font color="#3b9f0f">**load the countries on the screens of Provider and Unit**</font>.

## Procedure

1. Access the functionality through the main menu `System > Database > Country
    Load`;
2. Select a country;
3. Click on "**Load**".


[title] Questionnaires Management
[path] Platform Administration/Untitled/

**Questionnaires&#x20;**&#x61;re instruments that can be used to collect information.&#x20;

In the <font color="#3b9f0f">**CITSmart** </font>**Platform**, they can be used to capture information at the beginning of an attendance (**Ticket Management**) and serve as resources for applying checklists in the processes of Change, Release, and Problem.


[title] Registration of Positions
[path] Initial Settings/Users, Groups, Roles/Employee Registration/

Every employee registered with <font color="#3b9f0f">**CITSmart**</font> must have an associated position. This makes it easier to manage the people registered.

This feature provides a variety of actions, such as including, changing, and deleting the job positions in the organization.

## Procedure

1. Access the functionality through the main menu `General Registration >
    Personnel Management > Positions`;
2. Complete the fields available;
3. Click on "**Save**".


[title] Database Tool
[path] Platform Administration/Untitled/

The purpose is to <font color="#3b9f0f">**maintain the script registration to its execution in the
 system**</font>.

## Procedure

1. Access the functionality through the main menu `System > Database >
    Database Tool`;
2. To create a table, click on "**Create Table**";
3. Enter the necessary data;
4. Click on "**Run**";
5. To add fields in the table, click on the table you want;
6. Click on "**Add Fields in Table**";
7. A SQL command line will be entered in the SQL Scripts Console area to enter
   &#x20;in the table field;
8. Enter the data necessary and click on "**Run**".


[title] Configuring Knowledge Portal Filters
[path] Platform Administration/Untitled/

This functionality is intended to <font color="#3b9f0f">**configure the filters**</font> that will be <font color="#3b9f0f">**displayed
 enabled to search for knowledge in the Knowledge Portal**</font>.

## Procedure

1. Access the functionality through the main menu `System > Settings >
    Knowledge Portal > Configuration of Knowledge Portal Filters`;
2. Select the filters and the order you want them to be presented in the
   &#x20;Knowledge Portal;
3. Click on "**Save**".


[title] Setting System URL
[path] Initial Settings/

This functionality is intended to configure the system URL. It <font color="#3b9f0f">**records the URL, or web address, through which users will access the system**</font>.

It is used by several functionalities that need this reference to indicate internal links correctly.

## Procedure

1. Access the functionality through the main menu `Parameterization > CITSmart parameter`;
2. Search parameter **ID 33**, set URL for your instance:
3. Click on "**Save**".


[title] Registering Questionnaire Category
[path] Platform Administration/

This feature provides a variety of actions, such as <font color="#3b9f0f">**including, changing, and deleting questionnaire categories**</font> that will be used to filter and organize the register in the base.

## Procedure

1. Access the functionality through the main menu `System > Visions and
    Metadata > Questionnaire > Questionnaire Category`;
2. Click on "**New**";
3. Complete the field available;
4. Click on "**Save**".


[title] Registering Working Day
[path] Platform Administration/Untitled/

This feature provides a variety of actions, such as <font color="#3b9f0f">**including, changing, and
 deleting the working day of an organization**</font>.

## Procedure

1. Access the functionality through the main menu `General Registration >
    Personnel Management > Working Day`;
2. Complete the fields available;
3. Click on "**Save**".


[title] Registering Location
[path] Platform Administration/Untitled/

This feature provides a variety of actions, such as <font color="#3b9f0f">**including, changing, and deleting the location** </font>in which the services requester are placed, it can be the name of unit, city, organization, etc.

## Procedure

1. Access the functionality through the main menu `General Registration >
    Personnel Management > Location`;
2. Complete the fields available;
3. Click on "**Save**".


[title] Employee Registration
[path] Initial Settings/Users, Groups, Roles/

This functionality allows you to <font color="#3b9f0f">**register each person that has any type of link with
 the organization**</font>, such as an employee, partner, and others.

This feature provides a variety of actions, such as including, changing, and
&#x20;deleting an employee.

## Before getting started

- [x] To register an employee, it is necessary to register previously a unit and a
  &#x20;work position.

## Procedure

1. Access the functionality through the main menu `General Registration >
    Personnel Management > Employee`;
2. Complete all mandatory fields;
3. Click on "**Save**".


[title] Registering Type of Unit
[path] Platform Administration/Untitled/

This feature provides a variety of actions, such as <font color="#3b9f0f">**including, changing, and deleting the type of unit**</font>.

## Procedure

1. Access the functionality through the main menu `General Registration >
   Personnel Management > Type of Unit`;
2. Complete the field available;
3. Click on "**Save**".


[title] Automatic Action
[path] Platform Administration/Automation/

The automatic actions are associated with the event manager registration. These
&#x20;actions will be related **according to the type of event you want and trigger&#x20;**&#x77;henever it is recognized as a meaningful event.

This feature provides a variety of actions, such as <font color="#3b9f0f">**including, changing, and
 deleting automatic actions**</font>.

## Procedure

1. Access the functionality through the main menu `System > Automatic Actions  > Automatic Actions`;
2. Complete the fields available;
3. Click on "**Save**".


[title] Data Import Management
[path] Platform Administration/Untitled/

This functionality is intended to <font color="#3b9f0f">**import the data**</font>.

## Procedure

1. Access the functionality through the main menu `System > Import Management`;
2. Complete the fields available;
3. To execute the importation, double click on "**Run**";
4. Click on "**Save**".


[title] Registering Spreadsheet Template for Service Portfolio Import
[path] Platform Administration/Untitled/

The purpose of this functionality is to <font color="#3b9f0f">**optimize the creation of various services**</font> and, consequently, <font color="#3b9f0f">**their activities within one or more service portfolios**</font>.

:::hint{type="info"}
🖊 ***Note*****:&#x20;**&#x57;hen generating spreadsheets regardless of the format, the user will find
&#x20;hyperlinked fields. These fields retrieve the enumerated reference with the
&#x20;field description. In these cases, the user will use the enumerated one to
&#x20;fill the correct list.
:::

## Before getting started

To load the Service Portfolio, it is necessary:

- [x] To register previously the service
  &#x20;type and service category.

## Procedure

1. Access the functionality through the main menu `System > Data Importing and
    Loading > Service Portfolio Load`;
2. To register a spreadsheet template to import, click on the "**Spreadsheet
   &#x20;Template for Import**" tab;
3. The spreadsheet to import is structured step by step to create a
   &#x20;service portfolio with the steps Portfolio, Service, and Activity
   &#x20;(Incident/Request);
4. To generate the spreadsheet template in "**.xls**", click on "**Generate Template
   &#x20;.xls**";
5. To generate the spreadsheet template in "**.xlsx**", click on "**Generate Template
   &#x20;.xlsx**".


[title] Oauth2 Authentication using Keycloak
[path] Platform Administration/Authentication/

## Before getting started

It is necessary:

- [x] To have an authentication server with OAUTH2 protocol, for example, Keycloak;
- [x] To connect to the authentication server;
- [x] After reading a new user, the system will attribute permissions based on the following parameters:

## Procedure

1. Access the main navigation `Menu > Parametrization > Authentication > Oauth2 Option`;
2. The authentication method screen will be shown, with the "**Filters**" options and "**Authentication Methods**";
3. As of version <font color="#3b9f0f">**9.1.2.24**</font>, there has been a few interface changes described below:
4. The search screen is shown, where 4 options exist for the filters.

| **Option**      | **Description**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Type**        | The type of authentication. There are 2 types: **External&#x20;**&#x61;nd **Internal**.  <br />* If external is chosen, the system can accept 3 types of authentication: **Internal**, **Oauth2**, or **Both**. &#x20;
* If the option is set as Both, the system will show the login screen with authentication fields, password recovery, and login, using Google, Facebook, or Run2biz Keycloak. &#x20;
* If the option is set as Both but no external providers are informed, the system will not show any external options. &#x20;
* If the option is Oauth2 and no provider is informed, the screen with several options will not be shown, only the "**Run2Biz login screen**". |
| **Provider**    | Here you can inform if the provider is Google, Facebook, or others                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| **Domain**      | Inform the authentication domain                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| **Client Name** | Inform the name of the client for authentication                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |

5\. After filling the information in "**Filters**", if there is an option with the chosen filters, they will be shown on the "**Authentication Method**" table below;

6\. If there is no authentication method, you can create a new one by clicking on "**New**";

7\. When you click on "**New**", you will be redirected to the creation screen, with 2 tabs to be filled: "**Identification**" and "**Field Mapping**";

8\. Fill in the "**Identification**" tab:

| **Field**               | **Description**                                                                                                                                                                                                                                                                                                           |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Authentication Type** | There are two options "**Oauth2 - Internal**" and "**Oauth2**"                                                                                                                                                                                                                                                            |
| Provider                | Here you should inform if the provider is "**Google**", "**Facebook**" or "**others**"  If it is Google or Facebook, it's only necessary to inform: Client's Id and Secret Key;  If it is Others, it is necessary to inform: Name of the client, the Domain, that should be the same informed on the provider URL fields. |
| **Client Id**           | Here you should inform the client id used on the Oauth2 server                                                                                                                                                                                                                                                            |
| **Type of Concession**  | Identification of the access granted by the authentication provider.             This usually contains the value "**password**"                                                                                                                                                                                           |
| **Authentication URL**  | Here you should inform the path to the authentication server                                                                                                                                                                                                                                                              |
| **Client Secret**       | Here you should inform the client secret as it is on the Oauth2 server                                                                                                                                                                                                                                                    |
| **Situation**           | Here you can pick if the authentication is active or inactive  This situation determines if the system will start the user synchronization process                                                                                                                                                                        |
| **Save button**         | Saves the authentication method                                                                                                                                                                                                                                                                                           |
| **Delete button**       | Deletes the authentication method from the database                                                                                                                                                                                                                                                                       |
| **Clean button**        | Erases all the fields                                                                                                                                                                                                                                                                                                     |
| **Search button**       | Shown on top of the screen, this will return you to the search screen                                                                                                                                                                                                                                                     |

9\. On the "**Field Mapping**", you have more fields to fill in:

| **Field**         | **Description**                                                   |
| ----------------- | ----------------------------------------------------------------- |
| **Save button**   | Save the fields                                                   |
| **Erase button**  | Erases all the fields                                             |
| **Search button** | Shown on top of the screen, this will return to the search screen |

- This tab allows the mapping of information contained in the Oauth2 tokens. On this screen there are two columns, one with the name of the existing fields in the user registration and another with their respective names on Oauth2 tokens;
- The following are the information that can be mapped: ID number, Telephone, and Birth Date;

10\. The return URL to <font color="#3b9f0f">**CITSmart** </font>must be configured through the chosen external authentication platform.


[title] Parametrization - Configuration
[path] Platform Administration/Untitled/

**Configuration Management** is the <font color="#3b9f0f">**registration and detailed updating of
 information that describes a company's hardware and software**</font>. It is a process to
&#x20;establish and maintain the consistency of a product's performance, its
&#x20;functional attributes, and other operational information throughout its life.

The Configuration parametrization must be performed to allow the execution/use
&#x20;of this process.    It may be possible to define the group name for the
&#x20;Configuration Items that do not have a group, to define the destination of the
&#x20;sending notification e-mails that are close to expiring the CI of type Software,
&#x20;define the domain name of the network, among others.

## Procedure

1. Access the functionality through the main menu `Parametrization >
    Configuration Management`;
2. Set the values of parameters (attributes);
3. Click on "**Save**";
4. The list below presents the parameters of "**Configuration**" with the purpose
   &#x20;of each one of them:

| **#**   | **Name**                                                                                                    | **Possible values**                     | **Purpose**                                                                                                                                                                                                                                                                                                                                                                                                                                                           | **Additional Guidance**                                                                                                                                      |
| ------- | ----------------------------------------------------------------------------------------------------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **3**   | Search Node - (Eg: HARDWARE)                                                                                | E.g.: HARDWARE                          | Search in the defined node's XML document. After generating the inventory, the XML file will be generated, where it will read the Node (s) as defined in this parameter.                                                                                                                                                                                                                                                                                              | Not applicable                                                                                                                                               |
| **4**   | Search Attribute - (Eg: IPADDR, NAME, USERID)                                                               | E.g.: IPADDR,NAME,UDERID                | Search the XML document for defined attributes. After identifying the Node, the attribute (s) as defined in this parameter will be checked inside the Node.                                                                                                                                                                                                                                                                                                           | Not applicable                                                                                                                                               |
| **5**   | PATH\_INSTALLERS                                                                                            |                                         | Enter the path of the defined directory to store the executable files of the software to be installed.                                                                                                                                                                                                                                                                                                                                                                | Not applicable                                                                                                                                               |
| **60**  | Group of new configuration items.                                                                           |                                         | Define the Group name for Configuration Items that have no Group. <br />This ID is set in the "Configuration Item Group" screen.                                                                                                                                                                                                                                                                                                                                      | Not applicable                                                                                                                                               |
| **73**  | The number of days to Notify License Expiration. (Default: 90 days)                                         | Default: 90 days                        | Set the days in advance of the CI license expiration date to notify the CI group or owner about the expiration. When creating the "SOFTWARE" type configuration item, the expiration date, that is, the date the software license expires must be entered. The e-mail template defined in parameter 75 will be used to notify the group or owner of the CI defined in parameter 74, prior to N days (defined in this parameter) of the expiry date of the CI license. | If you do not enter the number of days, the system default value will be set: 90 (ninety) days.                                                              |
| **74**  | Send e-mail to CI Group or Owner? (1: Group 2: Owner).                                                      | 1: Group 2: Owner                       | Define to who will be sent the e-mails notifying that the CI of type Software has the license close to expiration: 1 = Group or 2 = Owner.                                                                                                                                                                                                                                                                                                                            | If you do not enter the value of the parameter, no e-mail will be sent.                                                                                      |
| **75**  | E-mail template ID for sending notification of license close to expiration                                  |                                         | Enter the license notification e-mail template's ID number near the expiration. It will be used to send the notification of the CI of type Software that is with the license near the expiration of the email template defined in this parameter. This e-mail template ID is set on the "E-mail Template" screen.                                                                                                                                                     | If you do not enter the identification number (ID) of the e-mail template, you may not send the correct e-mail.                                              |
| **76**  | Network Domain Name (Eg: COMPANY, CORPORATION)                                                              | E.g.: COMPANY, CORPORATION              | Set the domain name of the network.                                                                                                                                                                                                                                                                                                                                                                                                                                   | Not applicable                                                                                                                                               |
| **85**  | Check change related to CI?                                                                                 | Y or N                                  | Define if the Configuration Item (CI) link to the Change is mandatory. If the "Y" value is set, registering a Configuration Item in the "Configuration Item" screen should relate the CI to the Change.                                                                                                                                                                                                                                                               | If you do not enter the parameter value, the system default value will be used: "Y" (Yes).                                                                   |
| **87**  | E-mail template ID for CI Creation Notification                                                             | E.g.: 16                                | Enter the identification number (ID) of the Configuration Item (CI) creation notification e-mail template. When creating a CI in the "Configuration Item Management" screen, the e-mail template defined in this parameter will be used to send the CI creation notification. This notification will be sent to the owner and/or group associated with the CI. This e-mail template ID is set on the "E-mail Template" screen.                                        | If you do not enter the identification number (ID) of the e-mail template, you may not send the correct e-mail.                                              |
| **88**  | E-mail template ID for CI Change Notification                                                               | E.g.: 14                                | Enter the identification number (ID) of the notification e-mail template of changing the Configuration Item (CI). When changing a CI in the "Configuration Item Management" screen, the CI change notification will be used to send the email template defined in this parameter. This notification will be sent to the owner and/or group associated with the IC. This email template ID is set on the "Email Template" screen.                                      | If you do not enter the identification number (ID) of the e-mail template, you may not send the correct email.                                               |
| **89**  | Group CI change model (Eg: 15)                                                                              | E.g.: 15                                | Enter the identification number (ID) of the Configuration Item Group (CI) change notification e-mail template. When changing a CI Group in the "Configuration Item Management" screen, the CI template change notification will be used for the email template defined in this parameter. This notification will be sent to the owner and/or group associated with the CI. This email template ID is set on the "E-mail Template" screen.                             | If you do not enter the identification number (ID) of the e-mail template, you may not send the correct e-mail.                                              |
| **90**  | Sending CI Notification e-mails (1-Group, 2-Owner, 3-All) (Default: 1)                                      | 1- Group, 2- Owner, 3- All (Default: 1) | Define for whom will be sent e-mail notifications of Configuration Items (CIs): 1 = Group, 2 = Owner or 3 = All                                                                                                                                                                                                                                                                                                                                                       | If you do not enter the parameter value, the system default value will be used: "1" = Group                                                                  |
| **92**  | Name of the CI Group that is in the Development Phase. (Eg: CIs in development)                             | E.g.: Development                       | Define the name of the CI group that is in the Development phase. In the "Configuration Item Management" screen, the name of the development phase CI group, as defined in this parameter, is displayed.                                                                                                                                                                                                                                                              | If you do not enter the parameter value, the name of the development phase CI group will not be displayed on the "Configuration Item Management" screen.     |
| **93**  | Name of the CI Group that is in the Production Phase. (Eg: CIs in Production)                               | E.g.: Production                        | Define the name of the CI group that is in the Production phase. In the "Configuration Item Management" screen, the name of the production phase CI group, as defined in this parameter, is displayed.                                                                                                                                                                                                                                                                | If you do not enter the parameter value, the name of the production phase CI group will not be displayed on the "Configuration Item Management" screen.      |
| **94**  | Name of the CI Group that is in the Homologation Phase. (Eg: CIs in Homologation)                           | E.g.: Homologation                      | Define the name of the group of CIs that are in the Homologation phase. In the "Configuration Item Management" screen, the name of the CI group of the approval phase, as defined in this parameter, will be displayed.                                                                                                                                                                                                                                               | If you do not enter the parameter value, the name of the CI group of the approval phase will not be displayed on the "Configuration Item Management" screen. |
| **95**  | Name of the Cis group inventoried. (Default: Inventory)                                                     | E.g.: Inventory                         | Define the name of the IC group generated from the automatic inventory. On the "Configuration Item Management" screen, in the development phase of the CI group, the name of the Configuration Items group generated from the automatic inventory, as defined in this parameter, is displayed.                                                                                                                                                                        | There is no negative impact. If you do not enter the value of the parameter, the system default value is Inventory.                                          |
| **96**  | The ID of the Developing CI Group. (Eg: 1)                                                                  | E.g.: 1                                 | Define the ID number of the CI group of the Development phase. In the "Configuration Item Management" screen, a group will be created that will represent the lifecycle phase of the developing CI, according to the ID defined in this parameter and the description defined in parameter 92.                                                                                                                                                                        | There is no negative impact. If you do not enter the value of the parameter, the system default value will be used: 997.                                     |
| **97**  | The ID of CI Group in Production. (Eg: 2)                                                                   | E.g.: 2                                 | Set the identification number (ID) of the CI group of the Production phase. In the "Configuration Item Management" screen, a group will be created that will represent the lifecycle phase of the production CI, according to the ID defined in this parameter and the description defined in parameter 93.                                                                                                                                                           | There is no negative impact. If you do not enter the value of the parameter, the system default value is used: 998.                                          |
| **98**  | The ID of CI Group in Homologation. (Eg: 3)                                                                 | E.g.: 3                                 | Define the identification number (ID) of the CI group of the Homologation phase. In the "Configuration Items Management" screen, a group will be created that will represent the lifecycle phase of the CI being homologated, according to the ID defined in this parameter and the description defined in parameter 94.                                                                                                                                              | There is no negative impact. If you do not enter the parameter value, the system default value is 999.                                                       |
| **99**  | The ID of CI Group Inventoried. (Eg: 4)                                                                     | E.g.: 4                                 | Define the ID number of the Configuration Items Inventory group. In the "Configuration Item Management" screen, in the CI group of the development phase, a group is created for the CI generated from the automatic inventory, according to the ID defined in this parameter and the description defined in parameter 95.                                                                                                                                            | There is no negative impact. If you do not enter the value of the parameter, the system default value is 1000.                                               |
| **140** | Default CI Group IDs in Development                                                                         |                                         | Define the identification number (ID) of the default group of CI in development. In the "Configuration Item Management" screen, in the CI group of the development phase, a default group is created for the CI in development, according to the ID defined in this parameter and the description defined in parameter 143.                                                                                                                                           | There is no negative impact. If you do not enter the parameter value, the system default value is 1001.                                                      |
| **141** | Default CI Group ID in Homologation                                                                         |                                         | Define the identification number (ID) of the standard group of CI in homologation. In the "Configuration Items Management" screen, in the CI group of the homologation phase, a default group will be created for the CI in the homologation, according to the ID defined in this parameter and the description defined in parameter 144.                                                                                                                             | There is no negative impact. If you do not enter the value of the parameter, the system default value is 1002.                                               |
| **142** | Default CI Group ID in Production                                                                           |                                         | Define the identification number (ID) of the standard group of CI in production. In the "Configuration Item Management" screen, in the production phase of CI group, a default group is created for the CI in production, according to the ID defined in this parameter and the description defined in parameter 145.                                                                                                                                                 | There is no negative impact. If you do not enter the value of the parameter, the system default value is 1003.                                               |
| **143** | Default Group Name of CIs in Development. (Eg: Development - Default)                                       | E.g.: Development - Default             | Define the default group name of CI in development. In the "Configuration Item Management" screen, in the CI group of the development phase, the name of the default group of CI in development, as defined in this parameter, is displayed.                                                                                                                                                                                                                          | If you do not enter the value of the parameter, the name of the default group of CI in development is not displayed.                                         |
| **144** | Default group name of the CIs in Homologation. (Eg: Homologation - Default)                                 | E.g.: Homologation - Default            | Define the name of the default group of CI in homologation. In the "Configuration Items Management" screen, in the group of CI of the homologation phase, the name of the standard group of CI in the homologation, as defined in this parameter, will be displayed.                                                                                                                                                                                                  | If you do not enter the value of the parameter, the name of the default group of CI under approval is not displayed.                                         |
| **145** | Default Group Name of CIs in Production. (Ex: Production - Default)                                         | E.g.: Production - Default              | Define the default group name of CI in production. In the "Configuration Item Management" screen, in the production phase of the CI group, the name of the default group of CI in production, as defined in this parameter, is displayed.                                                                                                                                                                                                                             | If you do not enter the value of the parameter, the default group name of CI in production will not be displayed.                                            |
| **248** | The ID of the e-mail template that will be used during asset monitoring                                     |                                         | Enter the identification number (ID) of the e-mail template that will be used during the asset monitoring. This E-mail Template ID is set on the "E-mail Template" screen.                                                                                                                                                                                                                                                                                            | If the identification number (ID) is not correctly entered, the system will not send notification e-mails.                                                   |
| **249** | Asset Monitoring - Number of Threads? (Default '10')                                                        | Default: 10                             | Define the number of threads that will make the asset monitoring.                                                                                                                                                                                                                                                                                                                                                                                                     | Not applicable                                                                                                                                               |
| **250** | Display name in the configuration items tree (Eg: Y or N - Default 'Y')                                     | Y or N (Default: Y)                     | Define if the "Name" field will be used to display the configuration item on the Configuration Items Management screen. If you do not enter or have a 'Y' value, the value of the 'Name' field of the Configuration Item will be displayed in the list of configuration items in the Configuration Items Management screen. If the value entered is 'N', the value of the "Identification" field of the Configuration Item is displayed in the list.                  | Not applicable                                                                                                                                               |
| **440** | The minimum amount of registries that determines whether the data export will be executed in the background |                                         | Use whenever the user wishes to inform the minimum amount of registries that the system must execute the export in the background                                                                                                                                                                                                                                                                                                                                     | Not applicable                                                                                                                                               |

**Table 1 - Parameters List**


[title] Menu Registration
[path] Initial Settings/Home Panel/

This functionality is intended to <font color="#3b9f0f">**allow the users to configure the menu items**</font> according to their preferences. It provides a variety of actions, such as including, changing, and
&#x20;deleting a menu.

It provides better usability in accessing menus, where items can be arranged as needed.

## Procedure

1. Access the functionality through the main menu `General Registration > Menu`;
2. Complete the fields available;
3. The "**Generate XML**" button is to generate a file in ".xml" of menus;
4. The "**Update Menus**" button is to update the menu;
5. Be careful about running the "**Update Menus**" button, because all the
   &#x20;registration changes of the menus will be lost since the last generation of
   &#x20;XML. It is recommended, therefore, the following execution sequence:
   - ****<font color="#3b9f0f">**1.**</font> "**Generate XML**" button;&#x20;
   - <font color="#3b9f0f">**2.** </font>"**Update Menus**" button.
6. Finally, click on "**Save**".

## What to do next

Access the main menu to verify the menu created.


[title] Creating Calendar
[path] Platform Administration/

The calendar management page has features that allow you to perform several actions, for example: <font color="#3b9f0f">**adding, changing, and deleting calendars/scales of the working day**</font>.

## Before getting started

To register a calendar, it is necessary:

- [x] To register previously an access profile and a register of the working day.

## Procedure

1. To access this functionality, use the main menu `General Registration > Personnel Management > Calendar`;
2. When opening the functionality, as a standard, it will open in the calendar registration tab;
3. Start creating the calendar by completing the fields provided in the best way;

:::hint{type="info"}
🖊 ***Note*****:&#x20;**&#x42;y indicating the option "**yes**", in the "**Consider Holidays**" field, this means that the holidays will be considered as a day off in the calendar. Therefore, if the team related to the calendar works during holidays, choose the option "**no**".
:::

4\. In the exceptions part, click on the “**+**” icon, and a window will open where exceptions for days off or work can be entered;

5\. Click on "**Save**" to create the calendar;

6\. In the "**Calendar Search**" tab there is a search bar that is used to search for a specific calendar;

7\. By clicking on "**Search**", it will list all existing calendars;

8\. To edit a calendar, just select the calendar and you will be directed to the calendar registration tab with all the information already completed;

9\. If you need to delete the calendar, click on the "**Delete**" button;

10\. If you need to create another calendar, click on the "**Clear**" button so that all information is deleted;


[space] Enterprise Agility Management (/agility)

[title] PI Planning
[path] Usando o Agility/

## O que é o PI Planning?

O PI Planning é uma prática ágil adotada para planejar e alinhar o trabalho de várias equipes em um projeto. Desempenha um papel fundamental no gerenciamento de serviços, permitindo uma colaboração eficaz entre equipes, fornecendo visibilidade do progresso e melhorando a coordenação das atividades.

# Procedimento

Para criar o PI Planning, clique em Adicionar PI Planning, na página inicial.

:::::WorkflowBlock
::::WorkflowBlockItem
## Dados Gerais

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/iUoq9RPzAEcrwaABPkYUz_pi-planning-1.jpg)

No lado esquerdo da tela, digite um nome para sua PI Planning, escolha o nome do programa ou produto clicando no ícone de seta pra baixo e faça o mesmo para selecionar o tamanho da Sprint.

:::hint{type="info"}
✏️ ***Nota:*** Este campo só estará disponível após você selecionar uma data, passo que mostraremos a seguir.
:::

No lado direito da tela, escolha uma data clicando no ícone de calendário, e escolha o número de iterações clicando no ícone de seta pra baixo, depois clique em Avançar
::::

:::WorkflowBlockItem
## Adicionar Arts

Na próxima tela, selecione uma Art clicando no ícone de seta pra baixo e clique em avançar.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/51Po5WEw4FZumjvOrbHrs_pi-planning-2.png)
:::

:::WorkflowBlockItem
## Iterações

Na próxima tela digite um nome para cada uma das suas iterações. Como exemplo, estamos dando o nome das equipes que irão interagir neste projeto. Por fim, clique em Cria&#x72;**.&#x20;**&#x4F; seu Pi, aparecerá na tela inicial

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/mKnN7pO1JWwATPT82wlnq_pi-planning-3.png)
:::
:::::

# Glossário

### **Programa&#x20;**

Um programa no SAFe é uma entidade organizacional que reúne várias equipes ágeis para trabalhar em conjunto em uma solução maior e mais complexa. Ele é composto por um conjunto de Agile Release Trains (ARTs), que são times de desenvolvimento ágil responsáveis por entregar valor de forma independente. O programa é liderado por um Agile Program Manager e é guiado por uma Visão do Programa, que estabelece as metas e os objetivos a serem alcançados.

### **Produto**&#x20;

No SAFe, um produto é a solução que está sendo desenvolvida e entregue pelas equipes ágeis. Pode ser um software, um sistema de hardware, um serviço ou qualquer outra entrega de valor para os clientes. Um produto pode ter várias versões ou releases, e é gerenciado por um Product Manager ou Product Owner.

### **Sprint&#x20;**

No contexto do desenvolvimento ágil de software, uma "sprint" é um período de tempo fixo e curto durante o qual uma equipe de desenvolvimento trabalha para completar um conjunto de tarefas e entregar um incremento de software funcional. A sprint é uma unidade fundamental no Scrum, um dos métodos ágeis mais populares.

### **Iteração** &#x20;

No Scaled Agile Framework (SAFe), uma "iteração" é um conceito semelhante à "sprint" no Scrum. Ela representa um período de tempo fixo e curto em que as equipes ágeis trabalham para entregar valor incremental ao longo do desenvolvimento de um produto ou solução.

### **ART&#x20;**&#x20;

No contexto do Scaled Agile Framework (SAFe), "ART" é a sigla para Agile Release Train, que pode ser traduzido como "Trem de Liberação Ágil". O ART é uma estrutura organizacional que reúne várias equipes ágeis para trabalhar em conjunto no desenvolvimento e entrega de uma solução de software ou sistema complexo.


[title] Suporte ao Cliente
[path] Suporte/


[title] Usando o Agility
[path] Usando o Agility/

Neste documento é fornecida uma visão geral do conceito de **PI Planning** e como é relacionado com a nossa ferramenta de *Kanban* (*um método ou abordagem de gerenciamento de demandas, tarefas ou projetos*), o Agility.&#x20;

É recomendado começar por esta seção, pois contém os conceitos mais importantes.

Na [**Tela Principal**](docId\:BWDHCrCl9SMDQ8qwKmc5f) é possível encontrar um passo a passo visual e explicativo de como usar cada funcionalidade do Agility.&#x20;

Aqui você encontra conceitos e benefícios do PI Planning e de como o Agility é poderoso para o trabalho colaborativo.

## **1. O que é PI Planning?**

O PI Planning é uma prática ágil adotada para planejar e alinhar o trabalho de várias equipes em um projeto. Desempenha um papel fundamental no gerenciamento de serviços, permitindo uma colaboração eficaz entre equipes, fornecendo visibilidade do progresso e melhorando a coordenação das atividades.

## **2. Benefícios do PI Planning**

::::WorkflowBlock
:::WorkflowBlockItem
****Melhor alinhamento entre as equipes****: O PI Planning facilita a comunicação e a colaboração entre as equipes, garantindo que todos estejam cientes dos objetivos, prazos e prioridades.
:::

:::WorkflowBlockItem
****Visibilidade e transparência****: Ao realizar o PI Planning, é possível ter uma visão clara do progresso das atividades e das dependências entre as equipes, permitindo uma tomada de decisão mais informada.
:::

:::WorkflowBlockItem
****Identificação antecipada de problemas****: Durante o PI Planning, as equipes podem identificar possíveis obstáculos, riscos ou problemas que possam afetar o sucesso do projeto, permitindo ações corretivas antecipadas.
:::

:::WorkflowBlockItem
****Alocação eficiente de recursos****: Ajuda a garantir que os recursos estejam alocados de forma adequada e otimizada para atender aos requisitos do projeto.
:::

:::WorkflowBlockItem
****Entregas mais consistentes****: Ao planejar de forma colaborativa, as equipes têm uma compreensão compartilhada das metas e prioridades, o que leva a entregas mais consistentes e de maior qualidade.
:::
::::

## **3. Como a Ferramenta Agility suporta o PI Planning**

A ferramenta Agility é um poderoso sistema de gerenciamento de Kanban que oferece recursos específicos para facilitar o PI Planning. Esses recursos incluem:

::::WorkflowBlock
:::WorkflowBlockItem
****Quadros Kanban personalizáveis******:** O Agility permite criar quadros Kanban personalizados para cada equipe, facilitando a visualização e o gerenciamento das atividades planejadas durante o PI Planning.
:::

:::WorkflowBlockItem
****Integração de equipes****: A ferramenta permite a integração de várias equipes em um único ambiente, permitindo a coordenação e colaboração efetiva durante o PI Planning.
:::

:::WorkflowBlockItem
****Rastreamento de dependências****: Com o Agility, é possível mapear e rastrear as dependências entre as atividades das equipes, fornecendo uma visão clara das inter-relações e facilitando o gerenciamento de riscos.
:::

:::WorkflowBlockItem
****Acompanhamento de métricas e KPIs****: A ferramenta Agility oferece a capacidade de monitorar métricas e indicadores-chave de desempenho (****KPIs – Key Performance Indicators****) relacionados ao PI Planning. Isso permite avaliar o progresso, identificar possíveis gargalos e tomar medidas para melhorar a eficiência e a qualidade das entregas.
:::
::::

## 4. Etapas do PI Planning

Embora as etapas do PI Planning possam variar dependendo da abordagem e das necessidades específicas da organização, aqui estão algumas etapas comuns a serem consideradas:

::::WorkflowBlock
:::WorkflowBlockItem
****Definição de metas e objetivos****: As equipes devem alinhar-se com os objetivos do projeto, estabelecendo metas claras e compartilhadas para o período do PI Planning.
:::

:::WorkflowBlockItem
****Identificação de histórias e atividades****: As equipes trabalham juntas para identificar as histórias de usuários e as atividades necessárias para atingir as metas estabelecidas. Isso envolve a quebra do trabalho em tarefas menores e atribuição de responsabilidades.
:::

:::WorkflowBlockItem
****Estimativas de esforço****: Cada equipe estima o esforço necessário para concluir as histórias e atividades planejadas. Essas estimativas podem ser feitas utilizando técnicas como o Planning Poker ou outras abordagens colaborativas.
:::

:::WorkflowBlockItem
****Identificação de dependências****: Durante o PI Planning, é importante identificar as dependências entre as histórias, atividades e equipes, a fim de gerenciar efetivamente os riscos e planejar as interações necessárias.
:::

:::WorkflowBlockItem
****Sequenciamento e priorização****: Com base nas estimativas de esforço e nas dependências identificadas, as equipes colaboram para definir a sequência e a prioridade das histórias e atividades. Isso ajuda a garantir que o trabalho seja executado de maneira lógica e eficiente.
:::

:::WorkflowBlockItem
****Planejamento de capacidade e recursos****: Durante o PI Planning, as equipes avaliam a capacidade de recursos disponíveis e realizam um planejamento adequado para alocar recursos de forma eficiente, levando em consideração as restrições e as necessidades de cada equipe.
:::

:::WorkflowBlockItem
****Definição de objetivos para o período do PI****: Com base no trabalho planejado, as equipes estabelecem objetivos mensuráveis e alcançáveis para o período do PI Planning. Esses objetivos servem como referência para avaliar o progresso e o sucesso ao final do período.
:::

:::WorkflowBlockItem
****Comprometimento e acordo****: As equipes revisam e discutem o plano geral resultante do PI Planning. Todos os membros da equipe têm a oportunidade de compartilhar preocupações, ajustar estimativas e garantir um entendimento comum antes de finalizar e concordar com o plano.
:::
::::

## **Conclusão**

O PI Planning desempenha um papel crucial, permitindo uma **colaboração eficiente entre equipes**, **visibilidade do progresso**, **identificação antecipada de problemas** e **alocação eficiente de recursos**.

A ferramenta Agility apoia o PI Planning ao fornecer recursos específicos, como quadros Kanban personalizáveis, integração de equipes, rastreamento de dependências e acompanhamento de métricas.

Esta documentação fornecerá uma compreensão clara e objetiva do conceito de PI Planning, juntamente com os principais pontos relacionados e o suporte fornecido pela ferramenta Agility. Caso precise de mais informações ou esclarecimentos, **não hesite em entrar em contato**.

## Glossário

### SAFe

O SAFe, ou Scaled Agile Framework, é um framework ou modelo de gestão ágil escalável projetado para auxiliar organizações a implementar práticas ágeis em grande escala. Ele fornece orientações e estrutura para empresas que desejam adotar métodos ágeis em um ambiente corporativo mais amplo, envolvendo várias equipes, programas e portfólios

### **PI Planning**

Program Increment Planning ou Planejamento de Incremento de um Programa

### **Programa**

No contexto do SAFe (Scaled Agile Framework), um programa é uma unidade organizacional que abrange várias equipes ágeis trabalhando juntas para desenvolver e entregar uma solução de software ou produto. Um programa é composto por um conjunto de equipes ágeis que colaboram para atingir um objetivo comum.


[title] Introdução
[path] /


[title] Usando o Agility
[path] /


[title] Templates
[path] Usando o Agility/

A tela de template exibe uma lista com os templates cadastrados, bem como permite cadastrar e vincular novos templates.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/u1_PZt0nKWx2tHMKlHDfw_image.png)

A lista de Templates exibe as informações sobre cada template divididas em colunas:

1. **ID&#x20;**- Id do template
2. **Nome&#x20;**- Nome dos templates
3. **Workspace&#x20;**- Nome dos workspaces
4. **Ações -** Ações disponíveis para o template, sendo elas:
   - Visualizar - Permite ver o detalhamento do template selecionado, com nome dos projetos, o gerenciamento das raias e as tarefas.
   - Duplicar - Permite criar uma cópia do templates selecionado informando um novo nome para ele.
   - Arquivar - Permite arquivar o template selecionado, após a confirmação da ação.

Ao fim da página é exibido um botão com a numeração de páginas e número de templates a serem exibidos na visualização.

# Procedimento

## Criar novo template

No canto superior direito da tela, selecione o botão **Criar Template&#x20;**&#x70;ara exibir a tela de criação de release:

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/71hHCoaeOrhwIFitrlDVf_image.png)

| **Campo**              | **Descrição**                                            |
| ---------------------- | -------------------------------------------------------- |
| Workspace(\*)          | Selecionar o Workspace                                   |
| Título(\*)             | Colocar o nome para o novo template                      |
| Projetos(\*)           | Selecionar os projetos do workspace selecionado          |
| Gerenciamento de Raias | Marcar ou desmarcar se deseja permitir criar novas raias |
| Tarefas                | Selecionar as tarefas do projeto selecionado             |

Os campos marcados com (\*) são obrigatórios.

Clique no botão **Salvar&#x20;**&#x61;o fim da página para criar um novo template.

[title] Documentos
[path] Usando o Agility/Gestão de Cerimônias/

Os documentos de gestão de cerimônias servem para auxiliar a inclusão de informações nos cards e tarefas do Agility. Eles podem ser vinculados a cards específicos para incluir informações adicionais ou mais detalhadas aos cards, visto que os cards devem incluir informações mais breves. Cada documento permite a inclusão de texto em formatação simples e inclusão de comandos.

## Documentos

Para incluir um documento a um modelo, clique duas vezes em um template da lista de [**Templates**](docId\:T6H91rzw6HQ-IQMohDi2v).

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/2GJdgwjEY2K98jlCdfgzW_image.png)

Uma tela será exibida contendo um campo de edição de texto. Clique no ícone de Editar no canto superior direito para adicionar um texto ao campo.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/pIDfVTcPgCNtn4ar-euRz_image.png)

O texto aceita formatações simples em comandos MarkDown. Para ver a lista de comandos, digite / ao início de uma nova linha.

Os comandos permitem adicionar diversas funcionalidades ao template, como vincular cards, tabelas, ou outras informações do Agility.

Após incluir as informações e comandos desejados, clique em Salvar no canto superior direito para efetivar as alterações.

:::hint{type="info"}
**Nota:&#x20;**&#x51;uaisquer vínculos ou alterações indicadas no documento só serão aplicadas aos cards após **Salvar&#x20;**&#x6F; documento.
:::

### Vincular Card

A principal função dos documentos é a de vincular tarefas do Agility. Este comando adiciona automaticamente comentários a um card vinculado e notifica um membro designado sobre a alteração. Para utilizar a função, selecione a opção **Vincular card&#x20;**&#x6E;a lista de comandos.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/dLxSR_AW0zEgcy-FWaHTi_image.png)

No primeiro campo, selecione um card dentre os projetos e tarefas exibidos. É possível realizar uma pequisa por nome do card ou número do card.

O campo de destinatário indica qual usuário será notificado sobre alterações no card selecionado. Os usuários exibidos na lista de destinatários serão apenas os membros do projeto vinculado.

No campo nota, inclua uma mensagem para ser adicionada ao card.

Após incluir as informações, clique em Salvar para adicionar o comando ao documento.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/ge9NAoxqWTVjiik2x3XO8_image.png" size="46" width="338" height="96" position="center"}

Com o comando adicionado, ao clicar sobre o comando, o respectivo card será aberto em outra aba do navegador, e o comentário indicado no comando será adicionado ao card.&#x20;

[title] Custos
[path] Usando o Agility/

A tela de Custos permite criar descrições e custos para serem vinculados em outros locais, bem como apresenta informações sobre os mesmos.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/ZcEefhMuFET46kuG_r8c8_1-1920-x-1080-px5.png)

1. **Menu principal -&#x20;**&#x45;xpande ou colapsa o Menu principal do **Agility.**
2. **Pesquisa -&#x20;**&#x50;ermite a pesquisa/filtragem dos custos por Nome, bem como limpar os filtros.
3. **Adicionar custo -&#x20;**&#x43;lique no botão para adicionar um novo custo. Uma tela será exibida com um campo para informar o Nome do custo e sua descrição. Pressione Salvar para criar um novo custo ou Cancelar para voltar para a tela de custos.
4. **Nome -&#x20;**&#x4E;ome do custo.
5. **Descrição -&#x20;**&#x44;escrição do custo.
6. **Ações -&#x20;**&#x41;ções possíveis para o custo, sendo elas:
   - Editar - apresenta a tela de criação de custos com os campos preenchidos para edição.
   - Excluir
7. **Listagem e páginas -&#x20;**&#x50;ermite navegar na lista de páginas e selecionar quantos elementos serão exibidos por página.


[title] Métricas do Projeto
[path] Usando o Agility/Projeto/

Em gerenciamento de projetos, as métricassão importantes para quantificar o trabalho dos membros, com o objetivo de atingir os resultados e metas estabelecidos no plano estratégico da empresa

## Antes de Começar

- [ ] Tenha uma tela de [**Workspace**](docId\:y93oqYUqZlZGeR8xa9q1p);
- [ ] Tenha um [**Projeto**](docId\:zOt40BcG6RP_7idmDbvcF) criado;
- [ ] Caso deseje uma raia além das padrões do sistema (**Em espera**, **Em andamento&#x20;**&#x65;**&#x20;Finalizada**), crie uma [**Raia**](docId\:ffqaNVBQY7Jn6HvgXLGg0);
- [ ] Tenha uma [**Tarefa**](docId:3NqV4ganz7VsM8nGH1s3t) criada, assim como suas horas estimadas para cada card.

## Procedimento

Com o card colocado na raia **Finalizada**, clique em **Métricas&#x20;**&#x70;ara visualizar as métricas da equipe. Serão dispostas como na **figura abaixo.**

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/rbRqiJadRhGOGFnFILBwh_metricas-do-projeto-1.png)

::::WorkflowBlock
:::WorkflowBlockItem
### Planejamento

| **Opção**      | **Descrição**                                                                                                                                                                                                                                 |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Capacidade** | Apresenta a capacidade máxima (horas) que o membro tem disponível para atuar no projeto. Defina na criação ou edição do projeto;                                                                                                              |
| **Alocado**    | Apresenta quantas horas já foram distribuídas nas tarefas. Defina quando um membro é alocado em uma tarefa e quando as horas dessa tarefa são estimadas. As horas estimadas serão dívidas igualmente por todos os membros alocados na tarefa; |
:::

:::WorkflowBlockItem
### Acompanhamento

| **Opção**     | **Descrição**                                                                                                                                                                                                                                                                                                                                           |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Concluído** | Apresenta a quantidade de horas, de tarefas, que o membro já finalizou. Defina quando uma tarefa é concluída e as horas trabalhadas são lançadas                                                                                                                                                                                                        |
| **Esperado**  |  Apresenta o valor dinâmico por dia, sendo feita a divisão do valor capacidade pela quantidade de dias úteis do projeto. A contagem das horas é em D+1, ou seja, se uma sprint de 10 dias começou hoje com capacidade de 50 horas, ela começa a contar a partir de amanhã, mas ainda assim o dia de hoje é contabilizado, só não é apresentado no dia 1 |
:::

:::WorkflowBlockItem
### Tarefas sem estimativas&#x20;

Apresenta a quantidade de tarefas sem horas estimadas;
:::

:::WorkflowBlockItem
### Progresso das tarefas

| **Opção**                                    | **Descrição**                                                                                                                                           |
| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Total referente à capacidade no planejamento | A capacidade total disponível do membro ou do time - o mesmo valor que está na tabela no campo capacidade                                               |
| Esperado                                     | Valor referente ao esperado do acompanhamento (o valor esperado do membro ou do time - o mesmo valor que já está na tabela no campo esperado)           |
| Concluído                                    | Valor referente ao concluído do acompanhamento (o valor de horas concluídas do time ou do membro - o mesmo valor que está na tabela no campo concluído) |
:::

:::WorkflowBlockItem
### Tarefas atrasadas&#x20;

Quando há tarefas atrasadas, o símbolo se destaca para apresentar o número das tarefas do projeto que estão atrasadas.
:::

:::WorkflowBlockItem
### Bug&#x20;

Apresenta em vermelho a quantidade de tarefas marcadas como bug;
:::

:::WorkflowBlockItem
### Retrabalho&#x20;

Apresenta em vermelho a quantidade de tarefas marcadas como retrabalho.
:::
::::










[title] Tarefa
[path] Usando o Agility/

No gerenciamento de projetos e fluxo de trabalho, as tarefas são atividades específicas que precisam ser executadas para atingir um objetivo ou completar um trabalho. Elas são as unidades básicas de trabalho que compõem um projeto ou uma lista de afazeres.

# Antes de Começar

- [x] Tenha uma tela de [**Workspace**](docId\:y93oqYUqZlZGeR8xa9q1p);
- [x] Tenha um [**Projeto**](docId\:zOt40BcG6RP_7idmDbvcF) criado;
- [x] Caso deseje uma raia além das padrões do sistema (**Em espera**, **Em andamento&#x20;**&#x65;**&#x20;Finalizada**), crie uma [**Raia**](docId\:ffqaNVBQY7Jn6HvgXLGg0).

***

# Procedimento

::::WorkflowBlock
:::WorkflowBlockItem
Acesse as tarefas pelo `Menu Home > Workspaces` e escolha o projeto no qual deseja criar uma tarefa.
:::

:::WorkflowBlockItem
Aqui está cadastrado a Workspace da Administração, com um projeto de Alimentação do Banco de Dados e um&#x61;**&#x20;tarefa** para cadastrar as **Raças**

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/XxaaJihIYqcRstLamQ0Rm_new-recording-07072023-133419.gif "Imagem 1")
:::
::::

***

# Itens

São estes os principais elementos da tarefa no Agility:

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/3NMVZ8hudT4ORvDFYmIl3_tarefa-imagem-2.png "Imagem 2")

| **Item**             | **Descrição**                                                                                       |
| -------------------- | --------------------------------------------------------------------------------------------------- |
| 1 - Número da Tarefa | O número da tarefa (anterior ao seu nome) é **automaticamente&#x20;**&#x63;riado pelo sistema.      |
| 2 - Nome da Tarefa   | Ao ser selecionado poderá ser editado.                                                              |
| 3 - Descrição        | Descrição da Tarefa.                                                                                |
| 4 - ✅ Checkbox       | Se a tarefa estiver concluída será apresentada uma marcação de concluída ao lado do nome da tarefa. |

***

## Detalhes da Tarefa

Ao lado direito da tela há uma caixa contendo os Detalhes da Tarefa.

| **Campo**             | **Descrição**                                                                                                                                                                     |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 5 - Criado em         | Apresenta a quanto tempo a tarefa foi criada;                                                                                                                                     |
| 6 - Atualizado em     | Apresenta a data da última atualização da tarefa;                                                                                                                                 |
| 7 - Data de entrega   | Apresenta a data de entrega da tarefa, definida pelo usuário. É possível selecionar o campo, que apresenta um calendário para o usuário selecionar a data de entrega da tarefa;   |
| 8 - Horas estimadas   | Apresenta quantas horas foram estimadas para a entrega da tarefa, definida pelo usuário. Ao ser selecionada apresenta uma opção para o usuário selecionar q quantidade de horas;  |
| 9 - Retrabalho        | Apresenta uma opção para selecionar a tarefa origem do retrabalho. Essa tarefa será marcada como retrabalho da tarefa origem;                                                     |
| 10 - Membros          | Apresenta os membros da tarefa, definido pelo usuário. Ao ser selecionado apresenta a opção para o usuário adicionar membros na tarefa;                                           |
| 11 - Membros de apoio | Apresenta os membros de apoio da tarefa, definido pelo usuário. Ao ser selecionado apresenta a opção para o usuário adicionar membros na tarefa                                   |
| 12 - Tags             | Apresenta as tags da tarefa, definida pelo usuário. Ao ser selecionada apresenta a opção para o usuário adicionar tags na tarefa;                                                 |
| 13 - Aba inferior     | Aba inferior com ferramentas específica para a tarefa                                                                                                                             |

***

## Aba Inferior

Na Imagem 2, o número treze (13) se refere a aba de ferremantas inferior de cada tarefa. Cada seção da aba tem uma função diferente:

***

### Histórias Vinculadas

Na parte inferior da tela há uma divisão com algumas abas (13 a 18). A aba de histórias vinculadas....

| **Item**        | **Descrição**                                                                                                   |
| --------------- | --------------------------------------------------------------------------------------------------------------- |
| Vinculado à     | Permite vincular a tarefa à uma história de usuário de algum programa ou produto;                               |
| Relacionado à   | Permite relacionar a tarefa à uma história de usuário de algum programa ou produto;                             |
| É bloqueada por | Permite bloquear a tarefa, devido a alguma dependência, à uma história de usuário de algum programa ou produto; |

***

### &#xD;**Tickets vinculados**

Na aba Tickets vinculados, é possível vincular tickets de requisição na tarefa do projeto.

Clique no botão Vincular ticket:

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/AsnFsldmgq8QB7Urdtu1I_image.png)

Informe o número do ticket, e selecione na lista apresentada

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/ldj3GJ57wLuH7TC2fMzUs_image.png)

Clique no botão vincular:

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/rKk8_i2fuv-vC3Xgv3P-D_image.png)

***

### Comentários&#x20;

A aba de comentários lista os comentários realizados, com o nome do usuário. Os comentários servem para comunicação integrada dos membros da tarefa, facilitando correção e alteração de pequenos detalhes pontuais.

| **Item**                | **Descrição**                                                                                                 |
| ----------------------- | ------------------------------------------------------------------------------------------------------------- |
| Adicionar um comentário | Clique no botão para adicionar um comentário para os membros dessa tarefa                                     |
| Salvar                  | Para enviar o comentário                                                                                      |
| Cancelar                | Para cancelar o envio do formulário                                                                           |
| Editar/Excluir          | Caso o comentário seja do próprio usuário logado, será apresentada a opção para editar e excluir o comentário |

***

### Checklist

Ao adicionar uma checklist será criada uma lista nesta mesma aba. O checklist serve para garantir que nada de importante seja esquecido durante o processo de execução.

| **Item**        | **Descrição**                                                            |
| --------------- | ------------------------------------------------------------------------ |
| Criar Checklist | Clique no botão para adicionar a checklist.                              |
| Botão **+**     | Adiciona as caixas de seleção de cada checklist, funcionam como tópicos. |
| Salvar          | Serve para salvar tanto como a checklist, como os tópicos de cada lista. |

***

### Histórico&#x20;

A aba de Histórico apresenta uma lista com todas as ações realizadas na tarefa, como membros adicionados, adição de horas estimadas, entre outros.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/4JTbEVWe1yWGHtkLyDIpl_tarefa-imagem-2-3.png)

***

### Horas Registradas

Na aba de Horas Registradas é possível registrar as horas trabalhadas, a fim de controlar e manter o progresso das tarefas.

| **Item**           | **Descrição**                                                             |
| ------------------ | ------------------------------------------------------------------------- |
| Data               | Insira a data que do trabalho que deseja começar, normalmente o dia atual |
| Horário de Início  | Adicione o horário que começou a trabalhar na tarefa.                     |
| Horário de Término | Adicione o horário que terminou as atividades desejadas.                  |
| Descrição          | Insira uma breve descrição sobre as atividades realizadas.                |

***

### Anexos

A última aba de Anexos disponibiliza a opção de adicionar anexos à tarefa e fazer o download dos anexos disponíveis.

É possível fazer upload de anexos nos seguintes formatos:

- &#x20;  \`.md\`
- &#x20;  \`.doc\`
- &#x20;  \`.docx\`
- &#x20;  \`text/\*\` (qualquer tipo de texto)
- &#x20;  \`audio/\*\` (qualquer tipo de áudio)
- &#x20;  \`image/\*\` (qualquer tipo de imagem)
- &#x20;  \`video/\*\` (qualquer tipo de vídeo)
- &#x20;  \`.markdown\`
- &#x20;  \`text/markdown\`
- &#x20;  \`application/zip\`
- &#x20;  \`application/pdf\`
- &#x20;  (Excel XLSX)
- &#x20;  (Word DOCX)
- &#x20;  (PowerPoint PPTX)

Na aba anexo, do Agility React, é possível ver a quantidade de anexos existentes, destacado dentro de um circulo vermelhor ao lado da palavra "Anexos" na aba, como mostra a imagem abaixo.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/sHMJiPJ1vDM_vHkew26Bz_image.png)

***

### Campos Personalizados

É possível tambem adicionar um novo campo personalizado para que você possa personalizar o seu workspace ou tarefa adicionando mais dados conforme sua necessidade.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/R4qQQkYXZCiLVXhNLO89L_image.png)

Ao criar uma tarefa, é possível ter campos personalizados que já apareceção na janela de criação para ser preenchido.&#x20;

- Se o campo for **obrigatório&#x20;**&#x65; não for preenchido, ao clicar em criar aparecerá mensagem de erro e a tarefa não poderá ser criada;
- Se o campo **não&#x20;**&#x66;or **obrigatório&#x20;**&#x65; não  for preenchido ele poderá não aparecer dentro da tarefa, se esta opção foi escolhida em sua criação, ficando assim oculto.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/yLAMvx6M397D7wqTT8FP8_image.png" size="50" width="531" height="697" position="center"}

***

**Criar um Campo Personalizado**

Há duas formas para se adicionar um campo personalizado:

1. **Dentro da Tarefa&#x20;**:
   - Abra a tarefa e localize o campo no canto **inferior direito** da tela;

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/R4qQQkYXZCiLVXhNLO89L_image.png)

:::Paragraph{listStyleType="disc" indent="2"}
Clique no botão de **engrenagem&#x20;** ao lado do nome "Campos personalizados";
:::

:::Paragraph{listStyleType="disc" listStart="2" indent="2"}
Clique na opçã&#x6F;**&#x20;Criar campo**;
:::

:::Paragraph{listStyleType="disc" listStart="3" indent="2"}
Uma pequena **Janela&#x20;**&#x73;e abrirá ao lado, com as opções:
:::

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/pc_ZLAJnOzhJSriXtRbjz_image.png" size="34" width="366" height="319" position="center"}

:::Paragraph{listStyleType="disc" indent="3"}
**Tipo** *(obrigatório). Escolha um dos tipos disponibilizados abaixo:*
:::

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/2-mlxuAhVdyUy0iy-RuKj_image.png" size="22" width="205" height="202" position="center"}

:::Paragraph{listStyleType="disc" indent="4"}
**Texto Curto**: Validação para somente texto com visualização horizontal;
:::

:::Paragraph{listStyleType="disc" listStart="2" indent="4"}
**Texto Longo**: Validação para somente texto com visualização vertical;
:::

:::Paragraph{listStyleType="disc" listStart="3" indent="4"}
**Número**: Validação para somente números;
:::

:::Paragraph{listStyleType="disc" listStart="4" indent="4"}
**Data**: Validação para Data;
:::

:::Paragraph{listStyleType="disc" listStart="5" indent="4"}
**Número de telefone**: Campo de número com validação de telefone com código DDI de vários países;
:::

:::Paragraph{listStyleType="disc" listStart="6" indent="4"}
**E-mail**: Campo de texto e possui validação para e-mail;
:::

:::Paragraph{listStyleType="disc" listStart="7" indent="4"}
**Moeda**: Campo de número validado com formação de modeda que pode ser escolhida entre Real, Dolar e Euro.
:::

:::Paragraph{listStyleType="disc" indent="3"}
Marque se é um **campo sensível**;
:::

:::Paragraph{listStyleType="disc" listStart="2" indent="3"}
Clique no botão "**Criar**".
:::

***

2. **Dentro de Campos personalizados**
   - Clique no botão de **engrenagem&#x20;** ao lado do nome "Campos personalizados";
   - Clique em "**Gerenciar campos**"

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/nllQz-Q0_QYQaCk-kyNCq_image.png" size="54" width="668" height="276" position="center"}

:::Paragraph{listStyleType="disc" indent="2"}
Uma nova página se abrirá de "**Campos personalizados**";
:::

:::Paragraph{listStyleType="disc" listStart="2" indent="2"}
Clique em "**Criar campo**";
:::

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/_b0YY-UcmJB7qjXkT0o45_image.png)

:::Paragraph{listStyleType="disc" indent="2"}
Uma pequena janela se abrirá no centro da tela com os seguintes campos a serem preenchidos:
:::

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/oYsYnp0YWflCHyI-BdIhD_image.png" size="34" width="307" height="603" position="center"}

:::Paragraph{listStyleType="disc" indent="2"}
No campo **nome**, insira o nome do campo personalizado.&#x20;
:::

:::Paragraph{listStyleType="disc" listStart="2" indent="2"}
No campo **tipo**, selecione o tipo Texto curto ou longo, Número, Data, Telefone, E-mail ou Moeda;
:::

:::Paragraph{listStyleType="disc" listStart="3" indent="2"}
No **checkbox**, é possível marcar o campo como sensível ou não.
:::

:::Paragraph{listStyleType="disc" listStart="4" indent="2"}
Clique em **criar&#x20;**&#x61;pós inserir as informações e o campo será exibido junto com as outras abas da tarefa.
:::

***

**Editar um campo Personalizado**

Para editar um Campo Personalizado, acesse a página de gerenciamento de campos. Para acessá-la, siga os passos abaixo:

- Abra uma **tarefa**;
- Clique na engrenagem de "**Campos personalizados**";
- Clique na opção "**Gerenciar campos**";
- A página de **Gerenciamento de campos&#x20;**&#x73;erá aberta;

Em cada linha, será exibido um campo personalizado. Você poderá editar diretamente em cada linha:

- **Tipo**: Clique sobre ele e altere;
- **Campo Sensível**: Clique no botão para deixar marcado ou desmarcado;
- **Campo obrigatório**: Clique no botão para deixar marcado ou desmarcado;
- **Ocultar quando vazio**: Clique no botão para deixar marcado ou desmarcado. Se marcado, quando houver a criação de uma tarefa e este campo não for preenchido e não for obrigatório, ele ficará oculto dentro da tarefa, ou sejá, não poderá ser visualizado;
- **Ações**: Exibe dois botões de ação:
  - **Remover**: Exclui o campo personalizado;
  - **Editar**: Abre uma nova janela com mais opções de edição do campo. Você pode editar:
    - Nome: Reescreva o nome do campo personalizado;
    - Tipo: Escolha um novo tipo dentre os disponibilizados;
    - **Descrição**: Criará um *tooltip&#x20;*&#x63;om a descrição do campo ao passar o mouse sobre seu ícone na tabela;
    - &#x20;**Botão**: clique para marcar ou desmarcar as opções:
      - É um campo sensível;
      - É um campo obrigatório;
      - Ocultar quando vazio.
    - **Workspaces**: Selecione em qual Workspace o campo personalizado irá aparecer. Quando esta opção é selecionada, todas as tarefas deste workspace terá este novo campo criado. Independente de o próximo campo "Projetos" estar preenchido ou não;
    - **Projetos**: Você pode escolher um ou mais projetos específicos, para que somente nestes apareçam o novo campo personalizado. Para isso o campo anterior "Workspaces" deverá estar vazio.
    - **Mudar ordem**: Você pode mudar a ordem dos campos clicando nos 6 pontinhos  e arrastando para o lugar que deseja.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/yE2kJJRdj4wtKzeFJNg5U-20260326-193006.gif)

:::hint{type="warning"}
**Atenção**:

O acesso à página de Gerenciar campos só é possível se o seu usuário for **Admin&#x20;**&#x64;o projeto.

Ao acessar, a página só listará os campos personalizados que foram criados nos projetos que você é Admin.

Ao editar um campo personalizado, nas opções Workspaces e Projetos, somente aparecerão aqueles Workspaces e Projetos em que o seu usuário é Admin.

Caso você não seja Adm, as opções "Criar campo" e "Gerenciar campo" não aparecerão. Você somente conseguirá preencher os campos personalizados, caso eles já tenham sido criados.
:::

***

## Criação e Edição da tarefa

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/3j_FcgdXyKkTt2c_f-i4W_.blob)

***

### Criação

1. Aperte no ícone de **+&#x20;**&#x65;m alguma das raias disponíveis.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/9UArBZOM1d6KSnpQi2unq_.blob)

1. Preencha as informações.
2. Aperte em **Cancelar**, para cancelar as ações, ou **Salvar**.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/pjxlmgtA8inDAznAJ1crj_.blob" size="64" width="523" height="655" position="center"}

***

### Edição

1. Entre dentro da tarefa, clicando 2 vezes.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/5OvWtVO6S_PLEARkCEeOc_.blob)

1. Edite as informações conforme desejar.

***

### Histórias de Usuário&#x20;

No contexto de métodos ágeis de desenvolvimento de software, como o Scrum, as "histórias" (ou "histórias de usuário") são uma técnica usada para capturar requisitos ou funcionalidades desejadas pelos usuários do sistema. Elas são uma forma de descrever as necessidades dos usuários em termos simples e compreensíveis, com foco nos benefícios e resultados esperados.


[title] Arquivados
[path] Usando o Agility/

A tela de arquivados exibe uma lista com todos os [**Workspace**](docId\:S91Bg3Aeon7254EKRI6cL), [**Tarefa**](docId\:dtRtNUL6G8ltz_UO2eWCc) e [**Projeto**](docId\:AKTqJcdY1GuDO3CQO8oIz) arquivados.

## Antes de Começar

- [ ] Tenha um [**Workspace**](docId\:S91Bg3Aeon7254EKRI6cL), um [**Projeto**](docId\:AKTqJcdY1GuDO3CQO8oIz), ou uma [**Tarefa**](docId\:dtRtNUL6G8ltz_UO2eWCc) criados, para poder arquivá-los.

# Tela de Arquivados

Para acessar a tela de Arquivados, acesso o `Agility > Menu Arquivados` na barra lateral esquerda:

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/OmOGoXq-BYXe-ElDczEYq_imagens-agility-5.gif)

A tela principal de Arquivados possui 6 abas, um campo para pesquisa e a lista dos arquivados:

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/ugH1NGGmfZ-cip6eldGwJ_1-1920-x-1080-px3.png)

**1.&#x20;****Abas:&#x20;**&#x41; tela de arquivados é dívida em 6 abas: Tarefas, Projetos, Workspaces, Artefatos, Raias e Templates. Cada aba mostra uma lista com seu respectivo tipo, e informações sobre os itens.

**2.&#x20;****Pesquisa:&#x20;**&#x4F; campo de Pesquisa permite pesquisar por nome.&#x20;

**3. Lista&#x20;**&#x64;e arquivos da aba selecionada.

## Tarefas

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/nC39BQUY4RfjHoP3aOFcB_1-1920-x-1080-px4.png)

| **Item**  | **Descrição**                                                                                                                                                                                                                                                               |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Nome      | Nome das tarefas arquivadas.                                                                                                                                                                                                                                                |
| Tags      | Tags das tarefas arquivadas.                                                                                                                                                                                                                                                |
| Membros   | Membros das tarefas arquivadas.                                                                                                                                                                                                                                             |
| Checklist | Checklists concluídos das tarefas arquivadas.                                                                                                                                                                                                                               |
| Data      | Data de conclusão das tarefas arquivadas.                                                                                                                                                                                                                                   |
| Ações     | Quando selecionado o ícone, é possível:<br />* **Duplicar** – Copiá-la para outro workspace. Serão copiados o nome, a descrição e o checklist.&#x20;
* **Desarquivar&#x20;**- Volta a tarefa para seu projeto de origem
* **Ver mais** - Apresenta o detalhamento da tarefa |

Ao selecionar a ação Ver mais, uma caixa com os detalhes da tarefa será exibida.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/HLpQcPGv0vqKL3HKEc_S7_image.png" size="66" width="691" height="361" position="center"}

- Nome da tarefa.
- Checklists concluídos da tarefa.
- Data de conclusão da tarefa.
- Quantidade de anexos da tarefa.
- Desarquivar e voltar a tarefa para seu projeto de origem.

## **Projetos&#x20;**

A tabela apresentada na aba de **Projetos&#x20;**&#x65;xibe colunas com as seguintes informações:&#x20;

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/G0TCiJQmNa6UaUzxomC3o_image.png)

| **Campo**              | **Descrição**                                                                                                                                              |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Nome                   | Nome dos projetos arquivados                                                                                                                               |
| Membros                | Membros dos projetos arquivados                                                                                                                            |
| Data de início/Entrega | Data de início e entrega dos projetos arquivados.                                                                                                          |
| Ações                  | Quando selecionado o ícone, o botão de Ver Tarefas será exibido. Selecionar o botão exibe uma janela pop-up com a lista de tarefas do projeto selecionado. |

## Workspaces

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/Goelz3erNWxyruEmICldB_image.png)

A aba de workspaces apresenta os workspaces arquivados e suas respectivas informações dividas em colunas:

| **Campo** | **Descrição**                                            |
| --------- | -------------------------------------------------------- |
| Pesquisa  | Pesquisa os workspaces por nome.                         |
| Nome      | Nome dos Workspaces arquivados.                          |
| Membros   | Membros do workspace arquivado.                          |
| Ações     | Permite desarquivar o workspace para seu local de origem |



## Artefatos

A aba de Artefatos apresenta mais 3 abas: **Épico, Feature e História.**



![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/fw9_RPlLCN6vEJWeHA0ws_image.png)

### Épico

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/UTJjCGsbzRkFp2JaBTHFi_image.png)

A aba de épico apresenta uma tabela com:

| **Campo** | **Descrição**                                                                                                                      |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| ID        | Id do épico;                                                                                                                       |
| Nome      | Nome do épico;                                                                                                                     |
| Situação  | Situação do épico;                                                                                                                 |
| Programa  | Programa de origem do épico;                                                                                                       |
| Produto   | Produto de origem do épico;                                                                                                        |
| **Ações** | Clicando no ícone serão apresentadas as opções:<br />* Desarquivar - Volta com o artefato para o seu programa ou produto de origem |

### Feature

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/roTDLeh4PHtxIFhTvOR8p_image.png)

A aba de Feature apresenta uma tabela com:

| **Campo** | **Descrição**                                                                                                                      |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| ID        | Id do Feature ;                                                                                                                    |
| Nome      | Nome do Feature ;                                                                                                                  |
| Situação  | Situação do Feature ;                                                                                                              |
| Programa  | Programa de origem do Feature ;                                                                                                    |
| Produto   | Produto de origem do Feature ;                                                                                                     |
| **Ações** | Clicando no ícone serão apresentadas as opções:<br />* Desarquivar - Volta com o artefato para o seu programa ou produto de origem |

### História

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/ChlH08VrzUqUnLgzK_DjT_image.png)

A aba de História apresenta uma tabela com:

| **Campo** | **Descrição**                                                                                                                      |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| ID        | Id da História;                                                                                                                    |
| Nome      | Nome da História;                                                                                                                  |
| Situação  | Situação da História;                                                                                                              |
| Programa  | Programa de origem da História;                                                                                                    |
| Produto   | Produto de origem da História;                                                                                                     |
| **Ações** | Clicando no ícone serão apresentadas as opções:<br />* Desarquivar - Volta com o artefato para o seu programa ou produto de origem |

## Raias

A aba de Raias apresenta as Raias arquivadas e suas respectivas informações dividas em colunas:

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/VwoKwmtumriWUmntG4ym0_image.png)

| **Campo** | **Descrição**                                       |
| --------- | --------------------------------------------------- |
| Raia      | Nome da raia arquivada.                             |
| Projeto   | Projeto de origem da raia.                          |
| Ações     | Permite desarquivar a raia para seu local de origem |

## Templates

A aba de Templates apresenta os templates arquivadas e suas respectivas informações dividas em colunas:

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/b7YDPhWEEVg-iUQOwui2L_image.png)

| **Campo** | **Descrição**                                            |
| --------- | -------------------------------------------------------- |
| ID        | ID dos templates arquivados                              |
| Nome      | Nome dos templates arquivados.                           |
| Workspace | Workspace de origem do template.                         |
| Ações     | Permite desarquivar o template para seu local de origem. |


[title] Artefatos
[path] Usando o Agility/Programa e Produto/

# Antes de Começar

- [x] A ferramenta deve apresentar uma lista ou visão de todas as práticas.

# Procedimento

Acesse a tela de Programa e Produto e selecione o progama no qual deseja visualizar os artefatos. Para isso, na coluna de Ações, clique no símbolo e selecione "**Exibir****&#x20;Artefatos**";

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/YlBeyUkKOXHQdsop9EQ46_artefatos-1.png)

A tela de artefatos do programa/produto selecionado será exibida. A tela é apresentada com 3 abas, **Lista**, **Kanban&#x20;**&#x65; **Vínculos.**

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/f4omJftDKkGkgniAkQX_y_image.png" size="50" width="328" height="141" position="center"}


No canto superior direito, selecione o botão "**Adicionar Artefato**" e escolha entre as seguintes opções:

- Adicionar Épico
- Adicionar Feature
- Adicionar História

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/MvXoK74OyEL-CTO9qAgjb_image.png" size="36" width="156" height="147" position="center"}

## Adicionar Épico

Dentro desta função, estão presentes os seguintes campos:

| **Campo**                                  | **Descrição**                                                                                                                                                                 |
| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Número ID (\*)**                         | Gerado automaticamente pelo sistema                                                                                                                                           |
| **Nome (\*)**                              | Nomeie o Épico                                                                                                                                                                |
| **Situação**                               | Escolha a situação: **Funil**, **Revisão**, **Análise**, **Backlog**,**&#xD;**&#xA;**Implementação** ou **Concluído**                                                         |
| **Descrição**                              | Descreva o Épico                                                                                                                                                              |
| **WSJF**                                   | O WSJF é calculado automaticamente pelo sistema,&#xD; somando o valor do negócio a criticidade de tempo e a redução de riscos, divindo tudo pelo valor do tamanho do trabalho |
| **Valor do negócio para o usuário (\*\*)** | Informe o valor do negócio para o usuário                                                                                                                                     |
| **Redução de risco (\*\*)**                | Informe a redução de risco                                                                                                                                                    |
| **Criticidade de tempo (\*\*)**            | Informe a criticidade de tempo                                                                                                                                                |
| **Tamanho do trabalho (\*\*)**             | Informe o tamanho do trabalho                                                                                                                                                 |

(\*) Campos obrigatórios

(\*\*) Nesses campos é necessário inserir uma marcação de pontos que varia entre 1-3-5-8-13 e 21 (tabela na sequência de
&#x20;Fibonacci)

## Adicionar Feature

Quando selecionar essa função, os seguintes campos aparecem na tela:

| **Campo**                                  | **Descrição**                                                                                                                                                                 |
| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Número ID (\*)**                         | Gerado automaticamente pelo sistema                                                                                                                                           |
| ☑**&#x20;Habilitado (\*)**                 | Marcar se a Feature é habilitada ou não. Se marcar a opção, significa que poderá ser utilizada em outros Backlogs                                                             |
| **Situação**                               | Escolha a situação: **Funil**, **Análise**, **Backlog**,**&#xD;**&#xA;**Implementação**, **Validação**, **Implantação&#x20;****Liberado&#x20;**&#x65; **Cancelado**           |
| **Release**                                | Informe uma Release caso deseje vincular.                                                                                                                                     |
| **Nome (\*)**                              | Informar o nome da Feature                                                                                                                                                    |
| **Descrição**                              | Descreva a Feature                                                                                                                                                            |
| **WSJF**                                   | O WSJF é calculado automaticamente pelo sistema,&#xD; somando o valor do negócio a criticidade de tempo e a redução de riscos, divindo tudo pelo valor do tamanho do trabalho |
| **Valor do negócio para o usuário (\*\*)** | Informe o valor do negócio para o usuário                                                                                                                                     |
| **Redução de risco (\*\*)**                | Informe a redução de risco                                                                                                                                                    |
| **Criticidade de tempo (\*\*)**            | Informe a criticidade de tempo                                                                                                                                                |
| **Tamanho do trabalho (\*\*)**             | Informe o tamanho do trabalho                                                                                                                                                 |

(\*) Campos obrigatórios

(\*\*) Nesses campos é necessário inserir uma marcação de pontos que varia entre 1-3-5-8-13 e 21 (tabela na sequência de
&#x20;Fibonacci)

## Adicionar História

Dentro desta função, estão presentes os seguintes campos:

| **Campo**                    | **Descrição**                                                                                                                                                 |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Número ID (\*)**           | Gerado automaticamente pelo sistema                                                                                                                           |
| ☑**&#x20;Habilitado&#x20;**  | Marcar se a História é habilitada ou não. Se marcar a opção, significa que poderá ser utilizada em outros Backlogs                                            |
| **Story Points (\*) (\*\*)** | Selecione o Story Points, marcação de pontos que varia entre 1-3-5-8-13 e 21 (uma tabela de Fibonacci).                                                       |
| **Situação**                 | Escolha a situação: **A fazer**, **Pronto**, **Trabalho em** **andamento**,**&#xD;****&#x20;Pronto para teste**, **T****este**, **Completo** e **Cancelado**. |
| **Nome (\*)**                | Informar o nome da História                                                                                                                                   |
| **Feature**                  | Selecione a Feature                                                                                                                                           |
| **Descrição**                | Informe a descrição                                                                                                                                           |

(\*) Campos obrigatórios

(\*\*) Nesses campos é necessário inserir uma marcação de pontos que varia entre 1-3-5-8-13 e 21 (tabela na sequência de
&#x20;Fibonacci)

## Abas da barra de tarefas

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/pO77UB1tW2xwa28D5rW1X_image.png)

### Checklist

- Nessa aba, será criada uma checklist  ao adicioná-la. Ao lado da lista é apresentada uma opção
  &#x20;para adicionar um novo item, para editar o nome da lista e para excluí-la;
- Ao adicionar um item na lista e passar o mouse
  &#x20;sobre, será apresentada uma opção para editar
  &#x20;o nome do item e para o excluir;
- Para indicar finalização de um item selecione
  &#x20;o checkbox;

### Comentários

- É a lista dos comentários realizados, com o nome de
  &#x20;usuário;
- Caso o comentário seja do usuário logado na máquina, será
  &#x20;apresentada a opção para editar e excluir o
  &#x20;comentário.

### Anexos

- Sua função objetiva é adicionar anexos ao Épico.

### Horas lançadas

- Selecione a data do registro de hora trabalhada, a hora inicial e
  &#x20;final, além de informar uma descrição.

### Histórico

- Apresenta todas as ações realizadas no Épico,
  &#x20;como data, hora e usuário.



## Aba de Kanban

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/al_Z_bmzMUlfUb7VeT4GS_image.png)

Para selecionar o tipo de artefato a ser exibido (Épico, Feature
&#x20;ou História), clique no botão superior direito "**Adicionar artefato**";

Assim, na tela aparecerá o artefato de escolha.

### Épico

| **Funções**                                                                                     |
| ----------------------------------------------------------------------------------------------- |
| Apresenta as raias com as **situações default**                                                 |
| Os Épicos criados serão apresentados com os **nomes**, **WSJF&#x20;**&#x65; **data de criação** |
| Os Épicos serão ordenados pelo que tem o **WSJF&#xD;&#x20;**&#x6D;ais alto para o menor         |
| Os Épicos poderão ser movidos entre as **situações&#x20;**                                      |
| A reordenação de prioridades será feita&#xD; automaticamente pelo valor do **WSJF**             |
| Ao selecionar um Épico será apresentada sua **tela de&#xD; edição**                             |

### Feature

| **Funções**                                                                                       |
| ------------------------------------------------------------------------------------------------- |
| Apresenta as raias com as **situações default**                                                   |
| Os Features criadas serão apresentadas com os **nomes**, **WSJF&#x20;**&#x65; **data de criação** |
| As Features serão ordenadas pela a que tem o **WSJF&#xD;&#x20;**&#x6D;ais alto para o menor;      |
| As Features poderão ser movidas entre as&#xD; **situações**;                                      |
| A reordenação de prioridades será feita&#xD; automaticamente pelo valor do **WSJF**               |
| Ao selecionar uma Feature será apresentada sua **tela de&#xD; edição**                            |

### História

| **Funções**                                                                                                 |
| ----------------------------------------------------------------------------------------------------------- |
| Apresenta as raias com as situações **default**                                                             |
| As Histórias criadas serão apresentadas com os&#xD; **nomes**, **Story Points** e **data de criação**       |
| As Histórias serão ordenadas pela que tem &#x6F;**&#x20;Story&#xD; Point&#x20;**&#x6D;ais alto para o menor |
| As Histórias poderão ser movidos entre as **situações&#x20;**                                               |
| A reordenação de prioridades será feita&#xD; automaticamente pelo valor do **WSJF**                         |
| Ao selecionar uma História será apresentada su&#x61;**&#x20;tela de&#xD; edição**                           |

## Aba Vínculos

A tela é dividida em 2 colunas:

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/2DebDyAcM30LXS9U2V3PS_image.png)

A primeira Coluna de Pi’s Plannings vinculadas exibe uma tabela com:

- Id das Pi’s Plannings;
- Nome das Pi’s Plannings;

A coluna de Histórias e tarefas vinculadas exibe uma tabela com:

- Nome dos Workspaces;
- Nome dos Projetos;
- Nome das Tarefas;
- Nome das Histórias;

# Glossário

### WSJF

WSJF é a sigla para Weighted Shortest Job First, que em português pode ser traduzido como "Trabalho Mais Curto Ponderado Primeiro". O WSJF é uma técnica usada no Scaled Agile Framework (SAFe) para priorizar o trabalho e tomar decisões sobre quais recursos ou funcionalidades devem ser implementados primeiro, com base em uma análise de valor e risco.

O WSJF é calculado levando em consideração quatro fatores principais:

- Valor de Negócio (Business Value): Refere-se ao valor percebido pelo cliente ou stakeholders. Geralmente é medido em termos de benefícios, receita potencial, economia de custos, vantagem competitiva, entre outros.
- Esforço Estimado (Estimate of Effort): Representa o esforço necessário para implementar a funcionalidade ou o trabalho em questão. Pode ser medido em termos de tempo, complexidade, recursos necessários, entre outros.
- Tempo Crítico (Time Criticality): Reflete a urgência e o valor de entregar a funcionalidade o mais rápido possível. Algumas funcionalidades podem ter prazos apertados ou serem necessárias para atender a outros requisitos ou oportunidades de negócio.
- Risco de Atraso (Risk of Delay): Considera os riscos associados à implementação da funcionalidade, como riscos técnicos, dependências, incertezas ou impactos negativos caso o trabalho seja atrasado.

O cálculo do WSJF é feito dividindo o Valor de Negócio pelo Esforço Estimado e, em seguida, ponderando-o pelo Tempo Crítico e pelo Risco de Atraso. O resultado é uma pontuação que indica a prioridade relativa do trabalho.

O WSJF é uma ferramenta valiosa para a tomada de decisões de priorização no SAFe, pois leva em consideração tanto o valor do negócio quanto os riscos associados. Ele ajuda a identificar e priorizar os itens de trabalho que trazem maior valor e menor risco para o negócio, permitindo que a equipe foque em iniciativas estrategicamente importantes e minimizando o desperdício de esforços em tarefas de menor valor.

### Épico

- Um épico é uma unidade maior de trabalho, representando uma iniciativa de alto nível ou um objetivo amplo.
- Ele geralmente é grande e abrangente, exigindo a decomposição em partes menores para facilitar o planejamento e a execução.
- Épico fornece uma visão de alto nível e orientação estratégica para o desenvolvimento do software.

### Feature (Funcionalidade)

- Uma feature é uma parte específica e identificável de um sistema ou produto.
- Ela representa um conjunto de funcionalidades que agregam valor aos usuários.
- Uma feature pode ser planejada, desenvolvida, testada e entregue independentemente.

### Story (História)

- Uma story é uma unidade de trabalho ainda menor e mais granular que uma feature.
- Ela descreve uma funcionalidade específica do software do ponto de vista do usuário.
- Uma história normalmente segue um formato de frase curta e simples, descrevendo o que o usuário deseja alcançar e por quê.


[title] Conhecendo a Plataforma
[path] Usando o Agility/

Na tela principal do **Agile Work Management**, é possível realizar diversas ações. Para acessar a tela principal, clique no ícone de raio no menu lateral esquerdo.

No canto superior direito há dois botões para Adicionar Workspacee Adicionar PI Planning, e no topo da tela há uma caixa para as opções de Pesquisa e .

# Home

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/4OYlMourh45eiH62_qFD6_1-1920-x-1080-px2.png)

| **Campo**                | **Descrição**                                                 |
| ------------------------ | ------------------------------------------------------------- |
| 1. Pesquisa e filtros    | Caixa de pesquisa e aplicação de filtros                      |
| 2. Adicionar Workspace   | Botão para adicionar informações sobre um novo workspace      |
| 3. Adicionar PI Planning | Botão para adicionar informações sobre um novo PI Planning    |
| 4. Métricas              | Informações de métricas de todos os workspaces e PI Plannings |
| 5. Workspaces            | Lista de Workspaces e PI Plannings                            |

## 1. Pesquisa e Filtros&#x20;

O campo de Pesquisa permite pesquisar por nome ou ID da tarefa. A pesquisa será feita em todos os Workspaces, Projetos, Tarefas, Raias, Comentários, Checklists e Descrições. É possível restringir a pesquisa para apenas uma dessas opções.

O botão de filtros permite filtrar por prazo, definindo uma data inicial e uma data final, que também será aplicada em todos os Workspaces, Projetos e Tarefas. Há também um botão para limpar quaisquer filtros aplicados.

## 2. Adicionar Workspace

Após clicar no botão Adicionar Workspace, uma tela pop-up aparecerá, sendo necessário incluir:

- Marcar ou desmarcar a opção usar template; Esta opção permite criar um workspace a partir de um template. Se ela for marcada, um novo campo será exibido para selecionar o modelo de template desejado. O novo Workspace será criado com as mesmas características (os projetos, as raias, as tarefas e as tags) do template selecionado.
- Um nome para o novo Workspace;
- Selecionar os membros;&#x20;
- Cancelar ou Salvar;&#x20;

## 3. Adicionar PI Planning&#x20;

O botão de Adicionar PI Planningpermite a inserção de um novo item dessa categoria. algumas informações para a nova PI Planning devem ser preenchidas:&#x20;

- Inserir um nome;&#x20;
- Selecionar um Programa ou Produto da lista oferecida;&#x20;
- Definir a data de início clicando no ícone de calendário;&#x20;
- Escolher o tamanho da Sprint em dias;&#x20;
- Escolher o número de Iterações (mínimo de 2 e máximo de 12);&#x20;

Após inserir essas informações, clique em Avançar.&#x20;

O próximo passo é Adicionar Art's. Para isso escolha 1 ou mais Art's da lista.

O terceiro passo será de preencher as informações de Iterações.

- Insira um nome para a Iteração;&#x20;
- A quantidade de iterações e as datas de início de fim serão definidas automaticamente de acordo com data de início, o tamanho da sprint e o número de iterações, definidos no passo anterior;&#x20;
- Voltar ou Salvar para concluir a criação.

## 4. Métricas

Na tela inicial será apresentado um resumo dos prazos estabelecidos de todos workspaces do usuário logado.&#x20;

- **No prazo:&#x20;**&#x6D;ostra o total das Tarefas que tem a "Data da entrega" maior que 24h a partir da data/hora atual;&#x20;
- **A vencer:&#x20;**&#x6D;ostra o total das Tarefas que tenha a "Data da entrega" que ficarão vencidas em 24h a partir da data/hora atual;&#x20;
- **Vencidas:&#x20;**&#x6D;ostra o total das Tarefas que tenha a "Data da entrega" menor que a data/hora atual;&#x20;
- **Total:&#x20;**&#x73;oma de todas as Tarefas;&#x20;

## 5. Workspaces

Abaixo da sessão de métricas, será apresentada uma lista com todos os Workspaces e PI Plannings.&#x20;

Cada Workspaces ou PI Planning irá apresentar sua métrica:&#x20;

1. **No prazo:&#x20;**&#x6D;ostra o total das Tarefas daquele Workspace ou PI Planning, que tenham a "Data da entrega" maior que 24h a partir da data/hora atual;&#x20;
2. **A vencer:&#x20;**&#x6D;ostra o total das Tarefas daquele Workspace ou PI Planning, que tenham a "Data da entrega" que ficarão vencidas em 24h a partir da data/hora atual;&#x20;
3. **Vencidas:&#x20;**&#x6D;ostra o total das Tarefas daquele Workspace ou PI Planning, que tenham a "Data da entrega" menor que a data/hora atual;&#x20;
4. **Total:&#x20;**&#x73;oma de todas as Tarefas daquele Workspace ou PI Planning. Selecionando a seta para baixo serão apresentadas mais 4 métricas:
   - **Backlog**: mostra o total de tarefas que estão nas raias com o status de backlog;
   - **Priorizadas**: mostra o total de tarefas que estão nas raias com o status de prioritária;
   - **Em progresso**: mostra o total de tarefas que estão nas raias com o status de andamento;
   - **Concluídas**: mostra o total de tarefas que estão nas raias com o status de finalizada;

Selecione um Workspace ou PI para visualizar mais informações: Confira o documento sobre [**Workspace**](docId\:y93oqYUqZlZGeR8xa9q1p).


[title] Manual de Instalação Agility
[path] Suporte/

# Pré-requisitos para instalação

- [x] Instalação do *FrontManager*
- [x] Configuração dos tenants e aplicações
- [x] Dados de acesso a infraestrutura da centralit (credenciais do git, credenciais do nexus)
- [x] kubectl configurado para o ambiente onde será feito o deploy (isso inclui as variáveis de ambiente do projeto, com seus devidos dados de acesso).

## **Ferramentas**

- Banco de dados (PostgreSQL 13+ / SQLServer 2019+ / Oracle 12c+)
- KeyCloak (já deve estar instalado pois o FrontManager depende dele)
- MinIO (já deve estar instalado pois o FrontManager depende dele)
- Kafka (já deve estar instalado pois o FrontManager depende dele)

# **Passos para instalação**

Passos para instalação do Agility:

- Clonar o repositório do hyper-kanban-api

:::BlockQuote
git clone http\://gitlab.centralit.io/centralit/hyper-platform/hyper-kanban-api.git
:::

- Entrar na pasta onde o projeto foi clonado e fazer checkout da branch devel

:::BlockQuote
git checkout devel
:::

- Executar Step 1. Migrations
- Executar Step 2. Deploy

## Pass&#x6F;**&#x20;1. Migrations**

O script `migrations.sh` processa as migrações para múltiplos bancos de acordo com as configurações presentes num arquivo de migrações em formato json que por padrão é migrations-config.json na mesma pasta do script.

### **Arquivo migrations-config.json**

O arquivo deve seguir a estrutra abaixo:

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/eciJzu7zg6TaeznNNQ7VI_image.png)

Onde os atributos de cada tenant que segue:

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/gIsKKe2OGaiqOhwZr1wox_image.png" size="80" width="639" height="347" position="center"}

### **Exemplo**

Exemplo de arquivo com dois tenants (`run2biz e tenant1`) para o ambiente `desen` aplicação `hyper-kanban-api` (esta aplicação).

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/TGQxYWPoJzXcvmg0zUOe4_image.png)

### **Execução do script migrations.sh**

**Modo de uso**

:::BlockQuote
./migration.sh \<nomeTenant> ...
:::

**Exemplo**

:::BlockQuote
./migration.sh run2biz tenant1
:::

## **Passo 2. Deploy**

### **Via gitlab CI**

Para alguns ambientes, já existe a automação no gitlab, onde simplesmente fazendo o merge para a branch ele já aciona o deploy do produto (apps.centralit, labcentral). São os casos das branches com prefixo `deploy/`

Exemplo gitlab CI na branch deploy/apps.centralit.com.br&#x20;

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/KewmGvQ08jMnFzdAFCvDd_image.png)

### **Manual via script kubectl**

Para fazer manual, devem ser criados os arquivos template do ambiente em questão:

- configmap.template.yml
- deployment.template.yml
- ingress.template.yml
- service.template.yml

No caso, o único arquivo a ser atualizado seria o configmap.template.yml (variáveis de ambiente), o restante deles segue o mesmo padrão e conteúdo. Os arquivos devem ser criados na pasta k8s, em uma nova pasta com o nome do ambiente. Após isso, o script `k8s-apply.sh` deve ser executado passando qual o ambiente será atualizado com o deploy. Ex: `k8s-apply.sh dev-eveo`

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/HJQPqtMOob5sJLhJCuL2u_image.png)

### **Atualizando direto no Rancher**

Nos casos onde o ambiente kubernetes já existe e é necessário apenas atualizar o pacote, basta trocar o caminho do pacote pelo disponibilizado no registry.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/KN6Q0XoYa3LewS_DZEVBW_image.png)


[title] Gestão de Cerimônias
[path] Usando o Agility/

O gestor de cerimônias é uma aplicação utilizada para o gerenciamento de cerimônias das respectivas áreas da organização.

[title] Times e ART
[path] Usando o Agility/

Na tela de Times e ART é possível criar times e ARTs para agilizar a organização dos seus projetos (Agile Release Train).



Para acessar a tela, clique no ícone de raio Agile Work Management no menu lateral esquerdo, e depois na aba de Times e ART:

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/avFQxkxnBL-HGoHIpMHLS_agility-poc-central-5.gif)

A tela principal é dividida em duas abas: Times e ART. Na parte superior da tela há uma caixa de pesquisa, que permite pesquisar por nome. A pesquisa será feita por Times e ARTs.

## Times

A aba de times mostra uma tabela com os times registrados, um botão para adicionar novo time e algumas informações divididas em colunas.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/eoNf_OPLnu6iKbJ7ABsxT_image.png" size="36" width="117" height="47" position="center"}


O botão de criação exibe uma janela pop-up com algumas informações a serem preenchidas:

- **Nome&#x20;**&#x64;o Time;
- **Objetivo&#x20;**&#x64;o Time;
- **Cor&#x20;**&#x64;o Time;
- **Membros**: Escolher um ou mais membros para o time;
  - Ao selecionar um membro será apresentada a opção de excluir o membro adicionado, bem como selecionar o tipo de perfil;
- **Cancelar&#x20;**&#x6F;u **Salvar**

### Tabela

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/-k7spg5UtV3K0adD1AHhM_image.png)

A tabela apresentada organiza as informações nas seguintes colunas:



- **Nome&#x20;**&#x64;os times;
- **Membros&#x20;**&#x64;os times;
- **Cores&#x20;**&#x64;os times;&#x20;
- **Ações**: Ao clicar no ícone, é exibido um botão de **Editar**. Esse botão permite editar o nome, objetivo, cor, membros e perfil dos membros do time. No momento, os membros podem ser do tipo administrador ou membro.&#x20;

:::hint{type="warning"}
**⚠️&#x20;*****Atenção!*** Somente o usuário logado com perfil de administrador pode fazer essa alteração de perfil.
:::

### ART

A aba de ARTs mostra uma tabela com os ARTs registrados, um botão para adicionar novo ART e algumas informações divididas em colunas.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/brMhIEvcWPwxqJc3iKEaD_image.png" size="38" width="118" height="75" position="center"}



O botão de criação exibe uma janela pop-up com algumas informações a serem preenchidas:

- **Nome&#x20;**&#x64;o ART;
- **Adicionar Time**;
- **Adicionar Membro**;
  - Podem ser adicionados mais de um time e mais de um membro;
  - Só serão apresentados os times ativos que não possuírem vínculo com outro ART;
- **Cancelar&#x20;**&#x6F;u **Salvar**;

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/Gez1j2RvujL8-iSQmvpJC_image.png)

A tabela apresentada organiza as informações nas seguintes colunas:

- **Nome&#x20;**&#x64;os ART’s;
- **Times&#x20;**&#x64;e cada ART;
- **Membros&#x20;**&#x64;e cada ART;
- **Ações**: Ao clicar no ícone, é exibido um botão de **Editar**. Esse botão permite editar o nome, membros e  times.


[title] Projeto
[path] Usando o Agility/

Dentro de uma [**Workspace**](docId\:y93oqYUqZlZGeR8xa9q1p) é estipulado um propósito para um Projeto. Nele os membros da equipe serão adicionados para trabalharem em projeto específico, no qual contará com cada [**Tarefa**](docId:3NqV4ganz7VsM8nGH1s3t).

# Antes de Começar

- [x] Tenha uma tela de [**Workspace**](docId\:y93oqYUqZlZGeR8xa9q1p);

# Procedimento

::::WorkflowBlock
:::WorkflowBlockItem
Acesse a página de projetos pelo `Menu Home > Workspaces`;
:::

:::WorkflowBlockItem
Escolha em qual Workspace ou PI Planning deseja criar um projeto;
:::

:::WorkflowBlockItem
Para criar em projeto, clique no botão localizado na parte superior à direita da página, "**+** **Adicionar projeto**";

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/I9J7b1yafo6VF0KdFM6he_imagens-agility-2.gif)

No exemplo acima, foi criado um projeto chamado "**Organização da Recepção**" dentro da Workspace de "Administração"
:::
::::

Após selecionar um Workspace a partir da Tela Principal, é possível clicar no título de um projeto para visualizar mais opções.

# Opções do Projeto

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/448n7z0Abw84g4BF7cMPB_1-1920-x-1080-px.png)

| Opção                      | Descrição                                                                                                                                                            |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1. Abas                    | Visualização das abas de Kanban e Métricas                                                                                                                           |
| 2. Adicionar Raia e Opções | Botão para criar uma nova raia e visualizar mais opções do projeto.                                                                                                  |
| 3. Pesquisa e Filtros      | Procure no Projeto por tarefas específicas por nome ou número, ou adicione e remova filtros de visualização de tarefas.                                              |
| 4. Membros                 | Clique no ícone de relógio para incluir uma estimativa de horas para conclusão do projeto. <br />Os círculos coloridos representam os membros envolvidos no projeto. |
| 5. Ações                   | Selecione um número de Tarefas nas raias e clique em algum botão para atualizar todas as Tarefas selecionadas.                                                       |
| 6. Lista de Raias          | Visualização das raias do Projeto, com suas respectivas Tarefas.                                                                                                     |

## 1. Abas

Logo abaixo do título do projeto serão exibidas duas abas: Kanban e Métricas.

A aba de Kanban apresenta a visualização de todos os cards do projeto, cada um com suas respectivas informações. A aba de Métricas apresenta as métricas do projeto por total do time e por membros. Para mais informações verifique [**Métricas do Projeto**](docId\:xSfAFSGuOC3yWy-Ii2hnO)

## 2. Adicionar Raia e Opções

O botão **Adicionar Raia&#x20;**&#x65;xibe uma tela pop-up para a criação de uma nova Raia.

Clique no botão "**Opções**" ao lado de **Adicionar Raia&#x20;**&#x70;ara:

| **Opção**                | **Descrição**                                                                                                                                                                                                                                                |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Editar Projeto&#x20;** | Permite alterar o nome do projeto, as datas de início e de entrega, informar o custo planejado, a opção para criação de raias, adicionar  membros, a opção para exibir as métricas, o perfil, a capacidade e a exclusão dos membros do Projeto selecionado;  |
| **Arquivar Projeto**     | Permite arquivar o Projeto selecionado, após confirmação do usuário;                                                                                                                                                                                         |
| **Transição**            | Permite criar uma regra para ser executada quando a tarefa for movida de uma raia pra outra. Para mais informações verifique a nota abaixo.                                                                                                                  |
| **Exportar**             | Exporta as informações do projeto em formato CSV, PDF ou TXT.                                                                                                                                                                                                |
| **Recarregar Raias**     | Reorganiza as raias para a estrutura default;                                                                                                                                                                                                                |
| **Histórico&#x20;**      | Apresenta o histórico de toda a movimentação do projeto;                                                                                                                                                                                                     |

:::hint{type="success"}
**Transição -&#x20;**&#x41; opção de transição permite que seja criada uma regra para ser executada quando a tarefa for movida de uma raia pra outra.&#x20;

- Selecione a raia de origem;
- Se já houver uma transição criada ela será exibida, senão basta selecionar a opção adicionar transição para criar uma nova;

Para criar uma nova:

- Informar um nome para a transição;
- Selecionar a raia de destino;
- Cancelar ou Salvar;

Será apresentada a transição, com a sua raia de saída e a sua raia de entrada, selecionar a opção para excluir ou o lápis para editar, onde será apresentada as abas:

- Edição: Permite editar o nome da transição;
- Permissões: Selecionar editar ou excluir os perfis dos membros que poderão executar essa transição;
- Regras: Permite selecionar as regras, já criadas através do sistema ITSM por formulários ESI;
  - Após selecionar a regra, deverá ser informado se o valor é fixo ou dinâmico. Se for fixo, ele deverá ser informado, se for dinâmico basta selecionar da lista apresentada;
- Configurações: Será apresentada uma lista de opções para a regra, podendo ser selecionado uma ou várias opções;
:::

## 3. Pesquisa e Filtros

Na aba de Kanban, a pesquisa permite pesquisar por nome ou pelo Id da tarefa. É possível pesquisar em todos os Workspaces, Projetos, Tarefas, Raias, Comentários, Checklists e Descrições, ou selecionar apenas uma dessas opções para a pesquisa&#x20;

O botão de Filtro permite filtrar por nome, membros e tags, sendo possível selecionar mais de uma opção. A pesquisa será feita em todas as Tarefas.&#x20;

## 4. Membros

Aqui serão exibidos os membros de todas as tarefas do projeto, com seu respectivo ícone de usuário.

## 5. Ações da Tarefa

Abaixo de Adicionar Raia são exibidos os botões de ação para as tarefas. Os botões são habilitados apenas quando uma ou mais tarefas são selecionadas.

- **Mover**: Envia a **Tarefa** para outro **Projeto&#x20;**&#x64;entro do mesmo Workspace. Uma lista de Projetos será exibida para selecionar o destino da tarefa.
- **Concluir:&#x20;**&#x41;tualiza a tarefa selecionada, marcando-a como **Concluída&#x20;**&#x65; movendo-a para a Raia **Finalizados**
- **Arquivar:&#x20;**&#x45;xclui a Tarefa selecionada do Projeto. Para mais informações veja [**Arquivados**](docId\:WVZ3PCRte9FC08WchktWy).&#x20;

## 6. Raias

Na lista de Raias, são apresentadas lado a lado 3 raias default e as raias que forem criadas pelo usuário. As raias default são **Em Espera**, **Em Progresso** e **Concluído**.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/h7Y8ihHhe4MSYiNC4UMnd_projeto-2.png)

### 1. Adicionar Tarefas

Ao lado do nome da Raia há um número com a quantidade de tarefas que ela possui, e é possível adicionar tarefas clicando no ícone de **+**. A nova tarefa será adicionada logo abaixo da lista, com um campo para incluir o Nome, e botões para Salvar ou Cancelar.

### 2. Ordem das Raias

Clicando e arrastando o ícone é possível trocar a ordem das Raias.&#x20;

### 3. Opções da Raia

Nas opções da raia, há a opção de&#x20;

- **E****ditar&#x20;**&#x6F; nome da raia&#x20;
- **Alterar status**: permite informar o staus da raia, podendo ser: **Backlog&#x20;**(Em espera), **Em andamento**, **Prioritária&#x20;**&#x6F;u **Finalizada**;
- **Vincular Release**: Permite vincular a raia com uma release já criada, selecionando na lista apresentada. Ao vincular será apresentado ao lado do nome da raia um marcador de vínculo que apresenta o nome da release vinculada a raia. Após o vínculo feito é possível desfazer o vínculo indo na opção de desvincular release;
- **Arquivar** a raia.&#x20;

### 4. Lista de Tarefas

Abaixo de cada raia, é possível ver uma lista de tarefas. Cada tarefa mostra:&#x20;

- Lista de **Tags**
- O **Nome&#x20;**&#x64;a tarefa;
- Uma caixa marcável para selecionar uma ou mais tarefas;
- A **Data&#x20;**&#x64;e vencimento da tarefa;
- **Custo** da tarefa
- As horas estimadas/trabalhadas da Tarefa
- A lista de **Membros**;
- Se a tarefa foi marcada como **Bug&#x20;**&#x6F;u **Retrabalho**

### 5. Opções da Tarefa

Selecione o ícone com 3 pontos para visualizar as **Opções&#x20;**&#x64;a tarefa:

- **Mover&#x20;**- Permite mover a tarefa para outro Workspace.
- **Marcar como bug** – Permite marcar a tarefa como bug, colocando-a no topo da lista em que ela se encontra e com uma tag especial de bug.&#x20;
- **Duplicar -&#x20;**&#x50;ermite duplicar a tarefa para outro Workspace.
- **Retrabalho -&#x20;**&#x50;ermite marcar a tarefa como retrabalho;

Todas as tarefas podem ser movidas e arrastadas entre as raias. Ao mover uma tarefa para a raia finalizada, ela será marcada como finalizada. Ao move-la de volta para outra raia ela perde a marcação de finalizada.

### 6. Membros

Abaixo das informações da Tarefa, uma lista de círculos indica os Membros responsáveis pela tarefa.

### 7. Concluída

Ao mover a Tarefa para a Raia de Concluídos, ou selecionando uma Tarefa e clicando na opção Concluir, ela será marcada com um checkbox verde indicando sua conclusão.

## Métricas

Na aba Métricas, serão exibidas mais duas abas: **Métricas&#x20;**&#x65; **Custos**.

A aba Métricas apresenta métricas do projeto por total do time e por membros.

A aba custos apresenta uma lista com:

- O total de custos planejados, que é um valor fixo informado na criação ou edição do projeto;
- O total de custos realizados, que é o somatório do custo de todos os tipos vinculados as tarefas do projeto selecionado;
- Listagem com as somatórias dos valores dos custos por tipo;

Para mais informações verifique o documento de [**Métricas do Projeto**](docId\:xSfAFSGuOC3yWy-Ii2hnO)

## Criação e Edição do projeto

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/bCsL-K_TXdXN5nsEmzDCR_.blob)

### Criação

1. Escolha em qual workspace vai criar o projeto
2. Aperte em **+ Adicionar Projeto**

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/4gcSz3-Ohhs-mx-WCS_ge_.blob" size="48" width="215" height="54" position="center"}

1. Preencha as informações dos detalhes

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/NSKbQuy37hklSpdHyjiJb_.blob" size="46" width="644" height="456" position="center"}

- Aperte em **próximo&#x20;**&#x70;ara continuar.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/LaNv-pPrsA0CCKeqW3EZf_.blob" size="48" width="97" height="44" position="center"}

- Adicione os membros do projeto, juntamente com o perfil de acesso.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/0XE3AB4UUfK0BypLyNivR_.blob)

- Após isso, aperte em **Adicionar**, para incluir os membros na lista do projeto, através de times e ARTs.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/lQx8R1RPvIXbFj3Q463HD_.blob)

Aperte em **Cancelar**, para cancelar a ação, **Anterior**, para voltar um passo, ou **Salvar**, para salvar as ações.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/5gcNBFXQWKz38SpLzaaL-_.blob" size="48" width="304" height="56" position="center"}

### Edição

1. Acesse a pagina do projeto projeto
2. Aperte no ícone dos **3 pontinhos**

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/3BU4BdwhDIIoHusqNtYEt_.blob)

- Selecione Editar projeto

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/U1x9JoOjIIyTysndVttnS_.blob" size="24" width="172" height="189" position="center"}

- Edite as informações conforme desejar. Após isso, clique em salvar.

## Glossário

### **Raia&#x20;**

No contexto do Kanban, uma raia (ou lane, em inglês) é uma divisão horizontal em um quadro Kanban ou em uma representação visual das etapas de um fluxo de trabalho. Cada raia representa uma categoria, estágio ou tipo específico de trabalho dentro do sistema Kanban.

### Card&#x20;

Em contextos de gerenciamento de projetos e métodos ágeis, um "card" é uma representação física ou digital de uma tarefa, item de trabalho ou história de usuário. Os cards são usados para visualizar e rastrear as atividades em um quadro Kanban, Scrum board ou qualquer outra ferramenta de gerenciamento visual.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/Pj9yu7aQfhW3Gzb1kk37h_.blob)

### Tarefas&#x20;

No contexto de gerenciamento de projetos e fluxo de trabalho, as tarefas são atividades específicas que precisam ser executadas para atingir um objetivo ou completar um trabalho. Elas são as unidades básicas de trabalho que compõem um projeto ou uma lista de afazeres.


[title] Untitled
[path] /


[title] Workspace
[path] Usando o Agility/

O Worskpace representa uma área de trabalho de uma área da organização. O Workspace reúne cada [**Projeto**](docId\:zOt40BcG6RP_7idmDbvcF), que por sua vez reúne cada [**Tarefa**](docId:3NqV4ganz7VsM8nGH1s3t).

A partir da [**Conhecendo a Plataforma**](docId\:YIPBMnIJ02hYQ2gljbMYK), selecione um dos Workspaces ou PI Planning para visualizar mais opções detalhadas de cada Workspace.

# Antes de começar

- [x] É necessário possuir um workspace criado para acessar a tela.

# Procedimento

::::WorkflowBlock
:::WorkflowBlockItem
Acesse o `Menu Home > Workspaces`;
:::

:::WorkflowBlockItem
Clique em "**Criar Workspace**" para adicionar uma área de trabalho que deseje;

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/64Z1CGNFcR7GZUDGJ5ZNE_imagens-agility-3.gif)

No exemplo acima, foi criado uma Workspace para cuidar somente da **Perfumação&#x20;**&#x64;e um Pet Shop.
:::
::::

## 1. Aba de Lista&#x20;

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/o_MK_KvZiiaqSSG8sC7v0_1-1920-x-1080-px1.png)

| Campo                                    | Descrição                                                                                                                                                                                                               |
| ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1 -  Lista                               | Mostra a lista de projetos do workspace                                                                                                                                                                                 |
| 2 - Gantt                                | Mostra as barras de progresso de Gantt                                                                                                                                                                                  |
| 3 - Custos                               | Mostra uma tela com as informações de custos do workspace                                                                                                                                                               |
| 4 - Adicionar Projeto e Opções           | Clique aqui para adicionar um novo projeto, ou clique nos três pontos para visualizar mais opções.                                                                                                                      |
| 5 - Ordem e Filtros                      | Selecione os filtros a serem aplicados na lista de projetos.                                                                                                                                                            |
| 6 - Lista de Projetos                    | Lista mostrando todos os projetos do workspace atual. a lista exibe o Nome do projeto e barra de progresso de conclusão das tarefas. Clique e arraste o ícone de pontos ao lado do nome do projeto para trocar a ordem. |
| 7 - Métricas                             | Visualização de Métricas do projeto.                                                                                                                                                                                    |
| 8 - Lista de Membros do Projeto          | Ícones mostrando os membros envolvidos no projeto.                                                                                                                                                                      |
| 9 - Datas de Início e Entrega do Projeto | Datas de início da tarefa mais antiga e data de entrega da última tarefa do projeto.                                                                                                                                    |

Clique em qualquer área do projeto para uma visualização compacta das tarefas do projeto.

## 2. Aba Gantt

A aba Gantt mostra uma tabela com diversas informações divididas em linhas e colunas.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/LmPXPlByU5aucEy2xFZnL_workspace-2.png)

| **Colunas**                  |
| ---------------------------- |
| Nome do projeto              |
| Lista dos membros            |
| Data de criação              |
| Data de entrega              |
| Progresso                    |
| Duração do projeto (em dias) |
| Calendário                   |

Abaixo de cada projeto é possível ver uma lista com suas respectivas tarefas.

O calendário irá apresentar os projetos em barras coloridas com sua duração, começando na data de criação e terminando na data de encerramento.&#x20;

Ao final da página há um botão com a opção d&#x65;**&#x20;Esconder Tarefas**, que minimiza as informações da tabela para mostrar apenas as barras do calendário.

Clicando nos ícones de **-&#x20;**&#x65; **+** ao lado do título dos projetos, é possível esconder ou mostrar as tarefas de cada projeto individualmente.

## 3. Aba Custos

## 4. Adicionar Projeto e Opções

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/K1jyZP2whC4-4qrdER02G_image.png)

Clique no botão **Adicionar Projeto** no canto superior direito para visalizar o Pop-up de criação, onde é possível inserir um nome para o novo projeto e adicionar membros escrevendo seus nomes de usuário. É necessário também inserir a data de início e data de entrega do projeto.&#x20;

No campo Custo Planejado deverá ser informado o valor total do custo planejado para o projeto que está sendo criado.

A opção de criação de raias pode ser marcada para permitir ou não a criação de novas raias. Caso a opção seja desmarcada, a possibilidade de adicionar novas raias será bloqueada e o projeto terá apenas as raias padrões do sistema.

O próximo passo é selecionar os Membros do Projeto. Uma lista com os membros selecionados será exibida, com as opções:

- Exibir métricas do Projeto;
- Selecionar o perfil do Membro, dentre as opções&#x20;
  - Administrador – Com permissão para fazer todas as atividades.
  - Membro – Com permissão para criar, movimentar e editar as tarefas.
  - Leitor – Com permissão apenas para visualizar.

Para finalizar a criação, clique em **Salvar**, ou em **Cancelar&#x20;**&#x70;ara voltar para a tela anterior.

Clicar no ícone com três pontos para visualizar mais opções:&#x20;

| **Opção**                      | **Descrição**                                                                                                                                                                                                                                                                                                                                                                                         |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Recarregar Projetos**        | Atualiza a página;                                                                                                                                                                                                                                                                                                                                                                                    |
| **Gerenciamento de Templates** | Permite criar um template do workspace selecionado. Será aberta uma nova tela com as opções:<br />* O nome do template;
* Selecionar os projetos;
* Selecionar a opção se permite ou não criar raias;
* Selecionar as tarefas dos projetos selecionados;
* Voltar ou salvar;
* Ao Salvar será exibida a lista com os templates criados com as opções para visualizar, duplicar e arquivar o template; |
| **Editar Workspace**           | Permite alterar o nome, os membros, o perfil  dos membros e excluir um membro do Workspace selecionado;                                                                                                                                                                                                                                                                                               |
| **Arquivar Workspace**         | Permite arquivar o Workspace selecionado, após confirmação do usuário;                                                                                                                                                                                                                                                                                                                                |

## 5. Ordem e Filtros

O ícone de filtros abaixo do título permite filtrar os workspaces selecionados por prazo, definindo uma data inicial e final para a filtragem;

## 6. Lista de Projetos

Abaixo da caixa de pesquisa serão mostrados todos os projetos do Workspace atual.&#x20;

### Título e Progresso

No lado esquerdo do projeto será exibido o Nome do projeto e, abaixo deste, a barra de progresso de conclusão do projeto. Para abrir o projeto selecionado, clique no Nome.

A barra de progresso é definida pela porcentagem calculada com o total de estimativas das tarefas concluídas sobre o total de estimativas de todas as tarefas;

Ao lado esquerdo do Nome será exibido um ícone que permite alterar a ordem de visualização dos projetos na lista, clicando e arrastando com o mouse.

### Métricas

Os retângulos coloridos mostram as Métricas do projeto:

- **No prazo**: mostra o total das tarefas, do projeto, que tem a "Data da entrega" maior que 24h a partir da data/hora atual;&#x20;
- **A vencer:** mostra o total das tarefas, do projeto, que tenha a "Data da entrega" que ficarão vencidas em 24h a partir da data/hora atual;&#x20;
- **Vencidas**: mostra o total das tarefas, do projeto, que tenha a "Data da entrega" menor que a data/hora atual;&#x20;
- **Total**: soma de todas as tarefas do projeto;

### Membros

Os círculos coloridos mostram os membros envolvidos no projeto. A letra de cada círculo é a inicial do nome de usuário do membro. Se houverem mais de 4 membros no projeto, apenas os 3 primeiros membros e um círculo com reticências serão mostrados.

### Datas

Os ícones de calendário do lado direito do projeto mostram a data de criação da primeira tarefa do projeto e a data de entrega da última tarefa.

### Visualização rápida

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/hNijWEJV13hCveiX22GWw_workspace-4.png)

Ao clicar em qualquer lugar do projeto, será mostrada uma caixa com as tarefas do projeto selecionado para visualização rápida.

## 7. Custo

Na aba de Custo, será exibida a opção de Previsão de ROI (que é o retorno sobre investimentos). Ao selecionar a opção poderá ser informado um descritivo, e uma lista será exibida contendo:

- O total de custos planejados, que é o somatório de todos os valores planejados de todos os projetos;
- O total de custos realizados, que é o somatório dos custos de todos os tipos vinculados em todos os projetos;
- Listagem com as somatórias dos valores dos custos por tipo de todos os projetos;
- O ROI que apresenta a descrição do Roi do Workspace selecionado;

## Criação e Edição de Workspace

### Criação

Para criar um **Workspace**, vá na tela principal e clique em "Adicionar Workspace".

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/PjntaAc1b1-7jtUv9xPH-_.blob)

Após isso abrirá uma aba na lateral da tela.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/RN8uJf8wtZ_fXh4twkrft_.blob)

| Opção    | Descrição                                                                                                                                                                                                                                                                                                                                            |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Título   | Título do workspace                                                                                                                                                                                                                                                                                                                                  |
| Template | Permite associar um template ao workspace.                                                                                                                                                                                                                                                                                                           |
| Membros  | Permite adicionar membros ao workspace. Será aberta dois campos para configurar os membros. Ao clicar no botão "adicionar" será aberto mais pares de campos: • Perfil: Permite definir o perfil do membro dentro do workspace;&#xA;• Membro(s): Este campo permite vincular times, arts e membro(s) específicos, para ser membros do workspace.&#xA; |

Após preencher essas informações, clique em salvar e seu workspace será criado.

### Edição

- Para editar um Workspace, vá na tela principal de workspaces, clique no workspace que deseja editar.
- Após isso clique nos três pontinhos(...) no canto superior direito da tela para abrir mais opções, após isso clique em "Editar Workspace".


![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/NucDbIfmwDOu4sR3i5aIS_.blob)

| Opção   | Descrição                                             |
| ------- | ----------------------------------------------------- |
| Título  | Permite editar o título do workspace                  |
| Membros | Permite adicionar e remover membros de uma workspace. |

## Glossario

1. **Projeto** – “No contexto do Scaled Agile Framework (SAFe), um projeto é uma iniciativa ou esforço temporário com o objetivo de criar um produto, serviço ou resultado exclusivo. No entanto, no SAFe, o termo "projeto" é substituído pelo conceito de "Program Increment" (PI), que é um período fixo de tempo durante o qual o trabalho é planejado, executado e entregue pelas equipes ágeis.”
2. **Gantt** – “O gráfico de Gantt é uma ferramenta de gerenciamento de projetos que mostra as tarefas planejadas e o cronograma de um projeto em forma de um gráfico de barras horizontal. Ele fornece uma visão geral visual das atividades do projeto, suas durações e as dependências entre elas.”


[title] Programa e Produto
[path] Usando o Agility/

Na tela de Produto/Programa, é possível ver uma lista com todos os produtos e programas adicionados.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/8yjup7nN52m2ZHo2trNDk_produtoprograma-1.png)

| **Campo**                         |
| --------------------------------- |
| 1. Pesquisa e Filtros - Programas |
| 2. Pesquisa e Filtros - Produtos  |
| 3. Adicionar Produto ou Programa  |
| 4. Lista de Programas/Produtos    |
| 5. Ações                          |
| 6. Páginas                        |

## Coluna de Programas

| **Campo**        | **Descrição**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Pesquisar**    | Permite pesquisar por nome dos Programas;                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| **Filtrar**      | Permite filtrar Programas Ativos e/ou Inativos e ordenar por atualizados recentemente ou por ordem alfabética;                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| **Tabela&#x20;** | Tabela com: Id dos Programas; Nome dos Programas; Se o Programa está Ativo ou Inativo; e as seguintes Ações: <br />* **Exibir artefatos** – Irá abrir a página de artefatos do Programa selecionado [**Gerenciamento Ágil – Artefatos**](https://docs.citsmart.com/agility/artefatos);&#xD;
* **Editar&#x20;**– Apresenta a mesma tela do cadastro, com os 3 passos, permitindo editar todos os dados;&#xD;
* **Ativar ou Desativar** – Caso o Programa esteja ativo, será apresentada a opção desativar. Caso o Programa esteja inativo será apresentada a opção ativar; |

## Coluna de Produtos

| **Campo**        | **Descrição**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Pesquisar**    | Permite pesquisar por nome dos Produtos;                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| **Filtrar**      | Permite filtrar Produtos Ativos e/ou Inativos e ordenar por atualizados recentemente ou por ordem alfabética;                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| **Tabela&#x20;** | Tabela com: Id dos Produtos; Nome dos Produtos; Se o Produto está Ativo ou Inativo; e as seguintes Ações: <br />* **Exibir artefatos** – Irá abrir a página de artefatos do Produto selecionado [**Gerenciamento Ágil – Artefatos**](https://docs.citsmart.com/agility/artefatos);&#xD;
* **Editar&#x20;**– Apresenta a mesma tela do cadastro, com os 3 passos, permitindo editar todos os dados;&#xD;
* **Ativar ou Desativar** – Caso o Produto esteja ativo, será apresentada a opção desativar. Caso o Produto esteja inativo será apresentada a opção ativar; |

# Adicionar um Produto ou Programa

## Antes de Começar

- [x] A ferramenta deve apresentar uma lista ou visão de todas as práticas&#x20;

## Procedimento

- Acesse a funcionalidade por meio da navegação no menu principal `Agile Work Management > Programas e Produtos`;
- No canto superior direito, selecione o botão "**Adicionar Programa ou Produto**" no qual aparecerá uma tela de cadastro (**imagem**).

### Passo 1 – Dados Gerais:

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/YKoCzwQVvVl9RT634pLH1_produtoprograma-2.png)

| **Campo**     | **Descrição**                                                                                                                                                                                                                                                                                                                                  |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Nome**      | Coloque o nome para o novo Programa ou Produto:<br />* **Programa:&#x20;**&#x73;eria um conjunto de projetos que estão em andamento, com início, meio e fim; e&#x20;
* **Produto:&#x20;**&#x73;eria um bem físico ou virtual que resolve um problema de um usuário, uma empresa ou  um seguimento  específico, que está em melhoria constante. |
| **Tipo**      | Selecione se o tipo será Programa ou Produto;                                                                                                                                                                                                                                                                                                  |
| **Situação**  | Selecione a situação (Ativo ou Inativo);                                                                                                                                                                                                                                                                                                       |
| **Descrição** | Informe a descrição.                                                                                                                                                                                                                                                                                                                           |

Para avançar para o passo 2, clique em "**Próximo**";

### Passo 2 – Objetivos:

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/9tO_Vlo7hNkvc27L09uP6_produtoprograma-3.png)

| **Campo**              | **Descrição**                                                                                                                                                                                                                              |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Objetivo**           | Informe o Objetivo;                                                                                                                                                                                                                        |
| **Valor de negócio**   | Selecione o Valor do negócio;                                                                                                                                                                                                              |
| **Valor atual**        | Selecione o Valor atual (o valor de negócio e o valor atual servem para permear a organização do quanto aquele programa ou produto é importante, e assim viabilizar o orçamento. <br />Eles são escolhidos em uma **variação de 0 a 10**); |
| **Adicionar Objetivo** | Podem ser adicionados 1 ou mais objetivos.                                                                                                                                                                                                 |

Para avançar para o passo 3, clique em "**Próximo**";&#x9;

### Passo 3 – Riscos:

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/ktOMv6OXKJQmAwj2hBazj_produtoprograma-4.png)

| **Campo**              | **Descrição**                           |
| ---------------------- | --------------------------------------- |
| **Descrição**          | Informe a descrição do risco;           |
| **Cor**                | Selecione uma cor para o risco;         |
| **Adicionar Objetivo** | Podem ser adicionados 1 ou mais riscos. |

Clique em "**Anterior**" para voltar à ação prévia ou em "**Salvar**" para continuar.

[title] Agility - Visão Geral
[path] Introdução/

O Agilityé uma plataforma de gerenciamento fácil e ágil de atividades. Foi criado para gerenciar os projetos da maneira mais simples, com recursos para **organizar**, **monitorar&#x20;**&#x65; **delegar as atividades** entre os membros de sua equipe ou individualmente.&#x20;

Agility é baseado na metodologia Kanban e SAFe (Scaled Agile Framework).

SAFeé um framework ágil que fornece uma experiência simples e leve, ajuda a colocar produtos melhores no mercado de maneira mais rápida. Promove o **alinhamento**, a **colaboração&#x20;**&#x65; a **entrega&#x20;**&#x65;ntre diversas equipes ágeis.

Usando o Agility, é possível organizar e personalizar seus quadros Kanban com Tags de diferentes cores ([**Tarefa**](docId:3NqV4ganz7VsM8nGH1s3t)), personalizar as raias, e automatizando de maneira prática as métricas temporais, bem como registrar comentários e diversas informações úteis em cada tarefa.

As funcionalidades do Agility estão organizadas da seguinte maneira:

::::LinkArray
:::LinkArrayItem{headerType="IMAGE" headerImage="https://archbee-image-uploads.s3.amazonaws.com/EkhIfdQkw9x_8PD4a0GRC-h5g9fE3cMMMborytOpLVF-20240821-195550.png"}
[****](https://docs.citsmart.com/agility/tarefa)
:::

:::LinkArrayItem{headerType="IMAGE" headerImage="https://archbee-image-uploads.s3.amazonaws.com/EkhIfdQkw9x_8PD4a0GRC-qIPqkiIoSK3btGkT_IEwh-20240821-195538.png"}
[****](https://docs.citsmart.com/agility/projeto)
:::
::::

::::LinkArray
:::LinkArrayItem{headerType="IMAGE" headerImage="https://archbee-image-uploads.s3.amazonaws.com/EkhIfdQkw9x_8PD4a0GRC-CdkAUmsjuNiFune5OC64V-20240821-195544.png"}

:::

:::LinkArrayItem{headerType="IMAGE" headerImage="https://archbee-image-uploads.s3.amazonaws.com/EkhIfdQkw9x_8PD4a0GRC-xoqx6CtgE5xYGyE8tAb8i-20240821-195615.png"}
[****](https://docs.citsmart.com/agility/workspace)
:::
::::

A funcionalidade de Gestão de Capacidade Produtiva permite acompanhar a carga de trabalho distribuída entre os membros da equipe, sejam eles atendentes, gestores ou grupos participantes de fluxos de trabalho. Essa visão é essencial para garantir o equilíbrio das demandas, otimizar recursos e apoiar decisões de alocação.

[title] Release
[path] Usando o Agility/

A tela de release exibe uma lista com as release cadastradas, bem como permite cadastrar e vincular novas releases.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/f27mn-5fKmMTrBqwc_EDt_image.png)

A lista de Releases exibe as informações sobre cada release divididas em colunas:

1. **ID&#x20;**- Id da Release
2. **Título&#x20;**- Nome da Release
3. **Descrição&#x20;**- Descrição da Release
4. **Tipo&#x20;**- Tipo da Release
5. **Versão&#x20;**- Versão da Release
6. **Features -&#x20;**&#x41;s Features vinculadas a Release
7. **Raias -&#x20;**&#x41;s Raias vinculadas a Release
8. **Data de Início -&#x20;**&#x41; data de início da Release
9. **Data Final -&#x20;**&#x41; data final da release.
10. **Ação -** Ações disponíveis para a release, sendo ela:
    - Editar - Apresenta a mesma tela da criação com os campos preenchidos para a edição.

Ao fim da página é exibido um botão com a numeração de páginas e número de releases a serem exibidas na visualização.

# Procedimento

## Criar nova release

No canto superior direito da tela, selecione o botão **Criar Release** para exibir a tela de criação de release:

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/IWXDqOIeexrsQTu5OoZ9M_image.png)

| **Campo**          | **Descrição**                                         |
| ------------------ | ----------------------------------------------------- |
| ID                 | Número do ID será gerado automaticamente pelo sistema |
| Título(\*)         | Informar o título do release                          |
| Versão(\*)         | Informar a versão                                     |
| Tipo(\*)           | Selecionar o tipo (Correção ou Liberação)             |
| Ativa              | Selecionar se é ativa ou não                          |
| Descrição          | Informar a descrição                                  |
| Data de início(\*) | Selecionar a data de início                           |
| Data de fim        | Selecionar a data de fim                              |

Os campos marcados com (\*) são obrigatórios.

### Features

| **Campo**                    | **Descrição**                                                                  |
| ---------------------------- | ------------------------------------------------------------------------------ |
| Cadastrar nova Feature       | Opção para cadastrar uma nova feature, que abre a tela de cadastro de feature. |
| Buscar Feature já cadastrada | Pesquisar e selecionar uma feature já existente.                               |

Após a seleção da feature, será apresentada a release vinculada, caso já exista, e uma opção para substituir o vínculo com a release que está sendo criada no momento.

Após o vínculo, será presentada uma tabela com o Id e o nome da release e a ação para excluir o vínculo.

### Raias

|                  |                                                            |
| ---------------- | ---------------------------------------------------------- |
| Buscar Workspace | Pesquisar e selecionar um Workspace                        |
| Buscar Projeto   | Pesquisar e selecionar um projeto do Workspace selecionado |
| Buscar Raia      | Pesquisar e selecionar uma raia do projeto selecionado     |

Após a seleção será habilitada a opção para vincular raia.

Após o vínculo, será presentada uma tabela com o Id, o nome da raia, o nome do card, o nome projeto, o nome do workspace e a ação para excluir o vínculo.

Ao fim da tela, clique na opção de **Salvar&#x20;**&#x70;ara criar a nova release.

[title] Gráficos BurnDown e BurnUp
[path] Usando o Agility/

Os gráficos de burndown e burnup são ferramentas do Scrum que representam o progresso do projeto. Com esses gráficos, é possível medir a velocidade média de entrega da equipe, além de identificar fatores que possam influenciar na produtividade, como tarefas mal planejadas, ausência de membros da equipe, entre outros.

## Procedimento

::::WorkflowBlock
:::WorkflowBlockItem
Acesse Entre no Agility e acesse o `Menu Lateral > Home > Workspace > Projeto` e clique na **seta** no canto direito para expandir a aba de **Métricas**.&#x20;
:::

:::WorkflowBlockItem
No canto inferior direito, selecione os botões de **BurnUp&#x20;**&#x6F;u **BurnDown**.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/0WmoiiZyM9ixcPAwGe72g_image.png "BurnUp")

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/M59dOJAUFEk3S0XZrW5TR_image.png "BurnDown")
:::
::::




[title] Templates
[path] Usando o Agility/Gestão de Cerimônias/

A tela de Templates do Gestor de Cerimônias exibe uma lista com os modelos criados no sistema.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/4S-v_FIyjgV5npzVYYeOq_image.png)

## Criando um template

Para criar um novo template, clique no botão adicionar no canto superior direito da tela, ao lado da barra de pesquisa.

Um novo menu será exibido ao lado direito, com campos para incluir as informações do novo modelo:

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/BdMInbv6HVJWl-78dJfeQ_image.png" size="66" width="507" height="736" position="center"}

No campo Nome, inclua o nome do modelo. No campo Descrição, inclua uma descrição breve que indique para que o modelo será utilizado.

Após incluir as informações, clique em salvar para adicionar o template à lista.

Na lista de modelos, clique no ícone de editar para voltar para a tela de criação.

## Documentos

Após a criação de um template, é possível adicionar um modelo de documento ao mesmo. Para visualizar o modelo de documento de um template, clique duas vezes sobre um template na lista. Para mais informações sobre os documentos, veja [**Documentos**](docId\:wOeqs-_78PN5XECukyNxv).&#x20;


[title] Importação por planilha
[path] Usando o Agility/Workspaces/

## 🚀 Importação por planilha no Agility

Agora você pode **criar Workspaces, Projetos e Tarefas de uma vez só**, usando uma planilha (Excel ou CSV).

👉 Ou seja: em vez de cadastrar tudo manualmente, você sobe um arquivo e o sistema faz o resto.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/CZmM3J6lKc8FvXrrewUVN-20260319-143429.gif)

***

## 📥 Como funciona (sem complicação)

### 📄 Baixar o modelo

- O sistema disponibiliza um **modelo de planilha pronto**&#x20;
- Pode ser em **Excel (.xlsx)** ou **CSV**&#x20;

👉 Esse modelo já vem com as colunas obrigatórias.

Para baixar, clique nos três pontinhos (...) ao lado do botão adicionar workspace e em seguida clique em **Exportar modelo de workspace**.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/cJpMKkqo38FJKV1seFhy-_image.png)

Modelo da Planilha disponível

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/z8KsxcHBrrEap4RTAlsm1_image.png)

### 📤 Enviar a planilha

- Você faz o upload do arquivo&#x20;
- O sistema lê tudo automaticamente&#x20;
- No final, ele mostra:&#x20;
  - ✔️ O que foi criado&#x20;
  - ⚠️ O que deu erro&#x20;

Para enviar, clique nos três pontinhos (...) ao lado do botão adicionar workspace e em seguida clique em **Importar workspace**.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/rILPi1w7wYQ1Kv9_NJVMM_image.png)

Mensagem de erro quando já existe workspace, tarefa e projeto já criados com o mesmo nome:

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/BHPP6sYr-K66sAdhuxoiX_image.png)

***

## ⚠️ Regras importantes&#x20;

### 📌 Sobre a planilha

- Precisa ter **cabeçalho (nomes das colunas)**&#x20;
- Arquivo vazio ou formato errado → ❌ erro&#x20;
- Linhas vazias → ignoradas&#x20;

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/ioihERU9WeAsxa2qgfg7W_image.png)

### 🏢 Sobre Workspaces

Se o workspace **já existir**:

- 👤 Usuário comum:&#x20;
  - ❌ Não cria de novo&#x20;
  - ❌ Não cria projetos/tarefas dentro dele&#x20;
  - ⚠️ Mostra erro&#x20;
- 👑 Usuário admin:&#x20;
  - ❌ Não cria de novo&#x20;
  - ✅ Pode criar projetos e tarefas dentro dele&#x20;

👉 Exemplo:
&#x20;Se já existe "workspaceA", ele não duplica, mas pode usar o existente.

### 📋 Sobre Projetos (Boards)

- São **obrigatórios** se tiver tarefa ou datas&#x20;
- Se faltar → ❌ erro e linha ignorada&#x20;

📅 Datas:

- Se não informar → sistema preenche automático&#x20;
- Se só uma data for informada → completa sozinho&#x20;
- Se a data final for menor que a inicial → ❌ erro&#x20;

### 📝 Sobre Tarefas

- São **opcionais**&#x20;
- Não deixa criar tarefas duplicadas (mesmo nome)&#x20;
- Toda tarefa nova começa como:&#x20;
  - ▶️ **“Não iniciada” (Em espera)**&#x20;

Se essa etapa não existir → ❌ erro

### 📊 Sobre o processamento

- O sistema entende automaticamente:&#x20;
  - CSV com ; ou ,&#x20;
  - Excel (primeira aba)&#x20;

[title] Referenciamento via URL
[path] Usando o Agility/

Em cada caminho selecionado após o workspace, haverá alterações na URL com o respectivo caminho realizado. Assim, em cada tarefa estará a sua workspace, projeto e número, conforme a imagem abaixo.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/XOwPHvCMRliWOmenIL5Hk_image.png)


[title] FAQ
[path] Suporte/


[space] Enterprise Agility Management EN (/agility-en)

[title] Ceremony Manager
[path] Using Agility/

The Ceremony Manager is an application used to manage ceremonies for respective organizational areas.

[title] Task
[path] Using Agility/Main Screen/

In project management and workflow, <font color="#2166ae">**tasks** </font>are specific activities that need to be executed to achieve a goal or complete a job. They are the basic units of work that make up a project or a to-do list.

# Before You Begin

- [ ] Have a screen of [Workspace](docId:3QI_ThmCwswX6hlMDoXyp);
- [ ] Have a [Project](docId\:RRmATmr69epZ4rPMvidBN) created;
- [ ] If you want a lane in addition to the system's defaults (**On Hold**, **In Progress**, and **Completed**), create a lane.

# Procedure

::::WorkflowBlock
:::WorkflowBlockItem
Access the tasks through `Menu Home > Workspaces` and choose the project where you want to create a task.
:::

:::WorkflowBlockItem
Here is the Administration Workspace, with a project called "Database Feeding" and a **task** to register the **Breed**.
:::

:::WorkflowBlockItem
![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/XxaaJihIYqcRstLamQ0Rm_new-recording-07072023-133419.gif "Image 1")
:::
::::

# Items

These are the main elements of the task in Agility:

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/3NMVZ8hudT4ORvDFYmIl3_tarefa-imagem-2.png "Imagem 2")

| **Item**        | **Description**                                                                   |
| --------------- | --------------------------------------------------------------------------------- |
| 1 - Task Number | The task number (preceding its name) is **automatically** created by the system.  |
| 2 - Task Name   | When selected, it can be edited.                                                  |
| 3 - Description | Task description.                                                                 |
| 4 - ✅ Checkbox  | If the task is completed, a checkmark will be displayed next to the task name.    |

## Task Details

On the right side of the screen, there is a box containing the Task Details.

| **Field**            | **Description**                                                                                                                                                               |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 5 - Created at       | Displays how long ago the task was created;                                                                                                                                   |
| 6 - Updated at       | Displays the date of the last update to the task;                                                                                                                             |
| 7 - Due Date         | Displays the task's due date, defined by the user. The field can be selected, and a calendar will appear for the user to choose the task's due date;                          |
| 8 - Estimated Hours  | Displays how many hours have been estimated for the task's completion, defined by the user. When selected, an option will appear for the user to select the number of hours;  |
| 9 - Rework           | Presents an option to select the source task of the rework. This task will be marked as the rework of the source task;                                                        |
| 10 - Members         | Displays the members assigned to the task, defined by the user. When selected, an option will appear for the user to add members to the task;                                 |
| 11 - Support Members | Displays the supporting members assigned to the task, defined by the user. When selected, an option will appear for the user to add members to the task                       |
| 12 - Tags            | Displays the tags assigned to the task, defined by the user. When selected, an option will appear for the user to add tags to the task;                                       |
| 13 - Lower Tab       | Lower tab with specific tools for the task                                                                                                                                    |

## Lower Tab

In Image 2, the number thirteen (13) refers to the lower tab of each task. Each section of the tab has a different function:

### Linked Stories

At the bottom of the screen, there is a division with some tabs (13 to 18). The Linked Stories tab....

| Item       | Description                                                                                  |
| ---------- | -------------------------------------------------------------------------------------------- |
| Linked to  | Allows linking the task to a user story from a program or product;                           |
| Related to | Allows relating the task to a user story from a program or product;                          |
| Blocked by | Allows blocking the task, due to some dependency, to a user story from a program or product; |

### Comments&#x20;

The comments tab lists the comments made, along with the user's name. Comments are used for integrated communication among task members, facilitating corrections and changes to small specific details.

| Item          | Description                                                                                        |
| ------------- | -------------------------------------------------------------------------------------------------- |
| Add a comment | Click the button to add a comment for the members of this task                                     |
| Save          | To send the comment                                                                                |
| Cancel        | To cancel form submission                                                                          |
| Edit/Delete   | If the comment is from the logged-in user, the option to edit and delete the comment will be shown |

### Checklist

When adding a checklist, a list will be created in this same tab. The checklist serves to ensure that nothing important is forgotten during the execution process.

| Item             | Description                                                       |
| ---------------- | ----------------------------------------------------------------- |
| Create Checklist | Click the button to add a checklist.                              |
| **+** Button     | Adds checkboxes for each checklist item; they function as topics. |
| Save             | Serves to save both the checklist and the topics of each list.    |

### History&#x20;

The History tab presents a list of all actions performed on the task, such as added members, estimated hours, among others.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/4JTbEVWe1yWGHtkLyDIpl_tarefa-imagem-2-3.png)

### Logged Hours

In the Logged Hours tab, you can record the hours worked to control and maintain task progress.

| Item        | Description                                                       |
| ----------- | ----------------------------------------------------------------- |
| Date        | Enter the date you want to start working; usually the current day |
| Start Time  | Add the time you started working on the task.                     |
| End Time    | Add the time you finished the desired activities.                 |
| Description | Enter a brief description of the activities performed.            |

### Attachments

The last tab, Attachments, allows you to add attachments to the task and download available attachments.

# Glossary

### Card

In the context of project management and agile methods, a "card" is a physical or digital representation of a task, work item, or user story. Cards are used to visualize and track activities on a Kanban board, Scrum board, or any other visual management tool.

### User Stories&#x20;

In the context of agile software development methods, such as Scrum, "user stories" are a technique used to capture requirements or desired functionalities from system users. They are a way of describing users' needs in simple and understandable terms, with a focus on benefits and expected results.

[title] Project
[path] Using Agility/Main Screen/

Within a [Workspace](docId:3QI_ThmCwswX6hlMDoXyp), a purpose is set for a Project. In it, team members will be added to work on a specific project, which will consist of an individual [Task](docId\:UEODcDaJ6j_Y9xngPZvI2).

# Before You Begin

- [ ] Have a screen of [Workspace](docId:3QI_ThmCwswX6hlMDoXyp);

# Procedure

::::WorkflowBlock
:::WorkflowBlockItem
Access the projects page through `Menu Home > Workspaces`;
:::

:::WorkflowBlockItem
Choose the Workspace in which you want to create a project;
:::

:::WorkflowBlockItem
To create a project, click on the button located at the top right of the page, "**+** **Add Project**";

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/I9J7b1yafo6VF0KdFM6he_imagens-agility-2.gif)

In the example above, a project called "**Reception Organization**" was created within the "Administration" Workspace.
:::
::::

After selecting a Workspace from the Main Screen, you can click on the title of a project to view more options.

# Project Options

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/jjVSXDnhPBrhIlVThafsl_projeto-1.png)

| **Option**                     | **Description**                                                                                                                                |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| 1. Add Lane and Options        | Button to create a new lane and view more project options.                                                                                     |
| 2. Metrics                     | Click the arrow on the left side to expand the view of project metrics.                                                                        |
| 3. Search and Filters          | Search the Project for specific tasks by name or number, or add and remove task view filters.                                                  |
| 4. Estimated Hours and Members | Click on the clock icon to include an estimate of hours for project completion. Colored circles represent the members involved in the project. |
| 5. Task Actions                | Below Add Lane, action buttons for the tasks are displayed. The buttons are enabled only when one or more tasks are selected.                  |
| 6. Lane List                   | View of the Project lanes, with their respective Tasks.                                                                                        |

## 1. Add Lane and Options

Add Lane

Click the "**Options**" button next to **Add Lane** to:

| Option              | Description                                                     |
| ------------------- | --------------------------------------------------------------- |
| \*\*Edit Board \*\* | Allows changing the name and members of the selected Project;   |
| **Archive Board**   | Allows archiving the selected Project, after user confirmation; |
| **Reload Lanes**    | Reorganizes the lanes to the default structure;                 |
| \*\*History \*\*    | Shows the history of all project movements;                     |

## Metrics

Displays the project metrics for the entire team and for members. For more information, see [Project Metrics](docId\:EPTjklCRpVJORlxPj-sFl)

## 3. Search and Filters

The search box allows searching for task names. The Filter button allows filtering by deadline, setting a start date and an end date for the search. The search will be performed on all Tasks.&#x20;

## 4. Estimated Hours and Members

## 5. Task Actions

Below Add Lane, action buttons for the tasks are displayed. The buttons are enabled only when one or more tasks are selected.

- **Move**: Sends the **Task** to another **Project** within the same Workspace. A list of Projects will be displayed to select the task's destination.
- **Complete**: Updates the selected task, marking it as **Completed** and moving it to the **Completed** lane.
- **Archive**: Deletes the selected Task from the Project. For more information, see [Archived items](docId\:JkVbX4jGlVhEq84cDVs9i).

## 6. Lanes

In the list of Lanes, 3 default lanes are presented side by side along with the lanes created by the user. The default lanes are **On Hold**, **In Progress**, and **Completed**.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/h7Y8ihHhe4MSYiNC4UMnd_projeto-2.png)

### 1. Add Tasks

Next to the Lane name is a number indicating the number of tasks it contains, and you can add tasks by clicking the **+** icon. The new task will be added just below the list, with a field to enter the Name, and buttons to Save or Cancel.

### 2. Lane Order

Clicking and dragging the icon allows you to change the order of the Lanes.&#x20;

### 3. Lane Options

For the lanes added by the user, there is the option to edit the lane name and delete the lane.&#x20;

### 4. Task List

Below each lane, you can see a list of tasks. Each task displays:

- The task **Name**;
- A checkable box to select one or more tasks;
- The **Due Date** of the task;
- The hours posted/estimated hours for Task completion;
- The list of **Members**;
- The list of tags;&#x20;

### 5. Task Options

Select the icon with 3 dots to view the **Task Options**:

- **Move**: Allows moving the task to another Workspace.
- **Mark as Bug**: Allows marking the task as a bug, putting it at the top of the list where it is located and with a special bug tag.&#x20;
- **Duplicate**: Allows duplicating the task to another Workspace.

All tasks can be moved and dragged between the lanes. When moving a task to the completed lane, it will be marked as completed. When moving it back to another lane, it loses the completed mark.

### 6. Members

Below the Task information, a list of circles indicates the Members responsible for the task.

### 7. Completed

When moving the Task to the Completed lane, or selecting a Task and clicking on the Complete option, it will be marked with a green checkbox indicating its completion.

## Glossary

### Lane

In the context of Kanban, a lane is a horizontal division in a Kanban board or visual representation of the stages of a workflow. Each lane represents a category, stage, or specific type of work within the Kanban system.

### Card

In the context of project management and agile methods, a "card" is a physical or digital representation of a task, work item, or user story. Cards are used to visualize and track activities on a Kanban board, Scrum board, or any other visual management tool.

### Tasks

In the context of project management and workflow, tasks are specific activities that need to be executed to achieve a goal or complete a job. They are the basic units of work that make up a project or to-do list.

[title] Templates
[path] Using Agility/

The Templates screen displays a list of registered templates and allows you to register and link new templates.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/u1_PZt0nKWx2tHMKlHDfw_image.png)

The Templates list shows information about each template divided into columns:

1. **ID** - Template ID
2. **Name** - Template names
3. **Workspace** - Workspace names
4. **Actions** - Available actions for the template:
   - View - Allows viewing details of the selected template, including project names, swimlane management, and tasks
   - Duplicate - Creates a copy of the selected template by entering a new name for it
   - Archive - Archives the selected template after confirming the action

At the bottom of the page, a button displays page numbering and the number of templates to be shown in the view.

# Procedure

## Create new template

In the upper right corner of the screen, select the **Create Template** button to display the release creation screen:

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/71hHCoaeOrhwIFitrlDVf_image.png)

| **Field**           | **Description**                                  |
| ------------------- | ------------------------------------------------ |
| Workspace(\*)       | Select the Workspace                             |
| Title(\*)           | Enter a name for the new template                |
| Projects(\*)        | Select projects from the chosen workspace        |
| Swimlane Management | Check or uncheck to allow creating new swimlanes |
| Tasks               | Select tasks from the chosen project             |

Fields marked with (\*) are mandatory.

Click the **Save** button at the bottom of the page to create a new template.

[title] Artefacts
[path] Using Agility/Program and Product/



# Before Starting

- [x] The tool must display a list or view of all practices.

# Procedure

Access the Program and Product screen and select the program for which you want to view the artifacts. To do this, in the Actions column, click on the symbol and select "**Show Artifacts**" (see image 1);

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/YlBeyUkKOXHQdsop9EQ46_artefatos-1.png)

In the upper right corner, select the "**Add Artifact**" button and choose from the following options:

- Add Epic
- Add Feature
- Add Story

## Add Epic

Within this function, the following fields are present:

| **Field**                              | **Description**                                                                                                                                              |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **ID Number (\*)**                     | Automatically generated by the system                                                                                                                        |
| **Name (\*)**                          | Name the Epic                                                                                                                                                |
| **Status**                             | Choose the status: **Funnel**, **Review**, **Analysis**, **Backlog**, **Implementation**, or **Completed**                                                   |
| **Description**                        | Describe the Epic                                                                                                                                            |
| **WSJF**                               | WSJF is automatically calculated by the system, summing up the business value, time criticality, and risk reduction, and dividing it by the size of the work |
| **Business Value for the User (\*\*)** | Provide the business value for the user                                                                                                                      |
| **Risk Reduction (\*\*)**              | Provide the risk reduction value                                                                                                                             |
| **Time Criticality (\*\*)**            | Provide the time criticality value                                                                                                                           |
| **Work Size (\*\*)**                   | Provide the work size value                                                                                                                                  |

(\*) Mandatory fields

(\*\*) These fields require inserting a point value ranging from 1-3-5-8-13 and 21 (Fibonacci sequence table follows)

## Add Feature

When selecting this function, the following fields appear on the screen:

| **Field**                              | **Description**                                                                                                                                              |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **ID Number (\*)**                     | Automatically generated by the system                                                                                                                        |
| ☑ \*\*Enabled \*\*                     | Check whether the Feature is enabled or not. If selected, it means it can be used in other Backlogs                                                          |
| **Status**                             | Choose the status: **Funnel**, **Analysis**, **Backlog**, **Implementation**, **Validation**, **Deployment**, **Released**, or **Canceled**                  |
| **Name (\*)**                          | Name the Feature                                                                                                                                             |
| **Epic**                               | Select the Epic                                                                                                                                              |
| **Description**                        | Describe the Feature                                                                                                                                         |
| **WSJF**                               | WSJF is automatically calculated by the system, summing up the business value, time criticality, and risk reduction, and dividing it by the size of the work |
| **Business Value for the User (\*\*)** | Provide the business value for the user                                                                                                                      |
| **Risk Reduction (\*\*)**              | Provide the risk reduction value                                                                                                                             |
| **Time Criticality (\*\*)**            | Provide the time criticality value                                                                                                                           |
| **Work Size (\*\*)**                   | Provide the work size value                                                                                                                                  |

(\*) Mandatory fields

(\*\*) These fields require inserting a point value ranging from 1-3-5-8-13 and 21 (Fibonacci sequence table follows)

## Add Story

Within this function, the following fields are present:

| **Field**                    | **Description**                                                                                                              |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| **ID Number (\*)**           | Automatically generated by the system                                                                                        |
| ☑ \*\*Enabled \*\*           | Check whether the Story is enabled or not. If selected, it means it can be used in other Backlogs                            |
| **Story Points (\*) (\*\*)** | Select the Story Points, which represent the effort level defined by the team to complete the Story                          |
| **Status**                   | Choose the status: **To Do**, **Ready**, **In Progress**, **Ready for Testing**, **Testing**, **Completed**, or **Canceled** |
| **Name (\*)**                | Name the Story                                                                                                               |
| **Feature**                  | Select the Feature                                                                                                           |
| **Description**              | Provide the description for the Story                                                                                        |

(\*) Mandatory fields

(\*\*) These fields require inserting a point value ranging from 1-3-5-8-13 and 21 (Fibonacci sequence table follows)

## Taskbar Tabs

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/pO77UB1tW2xwa28D5rW1X_image.png)

### Checklist

- In this tab, a checklist will be created when added. Next to the list, there is an option to add a new item, edit the list name, and delete it.
- When adding an item to the list and hovering over it, an option to edit the item name and delete it will be displayed.
- To indicate the completion of an item, select the checkbox.

### Comments

- It is the list of comments made, with the username displayed.
- If the comment is from the logged-in user on the machine, an option to edit and delete the comment will be displayed.

### Attachments

- Its purpose is to add attachments to the Epic.

### Logged Hours

- Select the date of the recorded working hours, the start and end time, and provide a description.

### History

- Shows all actions taken on the Epic, such as date, time, and user.

## Kanban Screen

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/al_Z_bmzMUlfUb7VeT4GS_image.png)

To select the type of artifact to be displayed (Epic, Feature, or Story), click on the top right button "**Add Artifact**".

The chosen artifact will then appear on the screen.

### Epic

| **Functions**                                                                   |
| ------------------------------------------------------------------------------- |
| Presents the lanes with **default statuses**                                    |
| Created Epics will be displayed with **names**, **WSJF**, and **creation date** |
| Epics will be ordered from the highest to lowest \*\*WSJF&#xD; \*\*value        |
| Epics can be moved between \*\*statuses \*\*                                    |
| Reordering of priorities will be done automatically based on **WSJF** value     |
| Selecting an Epic will display its **editing screen**                           |

### Feature

| **Functions**                                                                      |
| ---------------------------------------------------------------------------------- |
| Presents the lanes with **default statuses**                                       |
| Created Features will be displayed with **names**, **WSJF**, and **creation date** |
| Features will be ordered from the highest to lowest \*\*WSJF&#xD; \*\*value        |
| Features can be moved between **statuses**                                         |
| Reordering of priorities will be done automatically based on **WSJF** value        |
| Selecting a Feature will display its **editing screen**                            |

### Story

| **Functions**                                                                             |
| ----------------------------------------------------------------------------------------- |
| Presents the lanes with **default statuses**                                              |
| Created Stories will be displayed with **names**, **Story Points**, and **creation date** |
| Stories will be ordered from the highest to lowest \*\*Story&#xD; Point \*\*value         |
| Stories can be moved between \*\*statuses \*\*                                            |
| Reordering of priorities will be done automatically based on **WSJF** value               |
| Selecting a Story will display its **editing screen**                                     |

# Glossary

### WSJF

WSJF stands for Weighted Shortest Job First. WSJF is a technique used in the Scaled Agile Framework (SAFe) to prioritize work and make decisions about which features or functionalities should be implemented first, based on a value and risk analysis.

WSJF is

calculated taking into account four main factors:

- Business Value: The perceived value by customers or stakeholders, often measured in terms of benefits, potential revenue, cost savings, competitive advantage, among others.
- Estimate of Effort: Represents the effort required to implement the feature or work, measured in terms of time, complexity, necessary resources, etc.
- Time Criticality: Reflects the urgency and value of delivering the feature as soon as possible. Some features may have tight deadlines or be required to fulfill other business requirements or opportunities.
- Risk of Delay: Considers the risks associated with implementing the feature, such as technical risks, dependencies, uncertainties, or negative impacts if the work is delayed.

WSJF is calculated by dividing the Business Value by the Estimate of Effort and then weighting it by Time Criticality and Risk of Delay. The result is a score indicating the relative priority of the work.

WSJF is a valuable tool for prioritization decisions in SAFe as it considers both the business value and associated risks. It helps identify and prioritize work items that bring the most value and least risk to the business, enabling the team to focus on strategically important initiatives and minimizing wasted efforts on lower-value tasks.

### Epic

- An epic is a larger unit of work, representing a high-level initiative or broad objective.
- It is usually large and comprehensive, requiring decomposition into smaller parts for ease of planning and execution.
- Epics provide a high-level view and strategic guidance for software development.

### Feature

- A feature is a specific and identifiable part of a system or product.
- It represents a set of functionalities that add value to users.
- A feature can be planned, developed, tested, and delivered independently.

### Story

- A story is an even smaller and more granular unit of work than a feature.
- It describes a specific functionality of the software from the user's perspective.
- A story typically follows a short and simple sentence format, describing what the user wants to achieve and why.


[title] Archived items
[path] Using Agility/

The Archived Screen displays a list with all archived [Workspaces](#), [Projects](#), and [Tasks](#).

## Before You Begin

- [ ] Have a [Workspace](#), a [Project](#), or a [Task](#) created to be able to archive them.

## Procedure

::::WorkflowBlock
:::WorkflowBlockItem
### Archive a Workspace

1. Access `Menu Home > Workspaces` and select the Workspace you want to archive.
2. Click on the three-dot button located next to the "Add Workspace" button and select the "**Archive Workspace**" option.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/RyDGciO0tEVH-lGQQgZJx_image.png)
:::

:::WorkflowBlockItem
### Archive a Project

1. Access `Menu Home > Workspace > Project` and select the Project you want to archive.
2. Click on the three-dot button located next to the "Add Project" button and select the "**Archive Project**" option.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/fF64W6E8hdx2a2sYgN_P9_image.png)
:::

:::WorkflowBlockItem
### Archive a Task

1. Access `Menu Home > Workspace > Project > Task` and select the blue check of each task you want to archive.
2. Click the "**Archive Task**" button on the upper right side to archive one or more tasks simultaneously.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/5fw3DG0Q_VjY2DqIaNyRt_image.png)
:::
::::

# Archived Screen

To access the Archived Screen, go to `Agility > Menu Archived` on the left sidebar:

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/OmOGoXq-BYXe-ElDczEYq_imagens-agility-5.gif)

The main Archived Screen has 3 tabs, a search field, and the list of archived items:

::::WorkflowBlock
:::WorkflowBlockItem
**Search:&#x20;**&#x54;he Search field allows you to search by name. The search will be done on all Workspaces, Projects, and Tasks.
:::

:::WorkflowBlockItem
**Tabs:&#x20;**&#x54;he Archived Screen is divided into 3 tabs: Tasks, Projects, and Workspaces. Each tab shows a list with its respective type and information about the items.
:::

:::WorkflowBlockItem
**Tasks:&#x20;**&#x54;he table presented in the **Tasks** tab displays columns with the following information:

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/lj4zcOn7S013HHz0ZwVIF_image.png)

| **Item**  | **Description**                                                                                                                             |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| Name      | Name of the archived tasks.                                                                                                                 |
| Tags      | Tags of the archived tasks.                                                                                                                 |
| Members   | Members of the archived tasks.                                                                                                              |
| Checklist | Completed checklists of the archived tasks.                                                                                                 |
| Date      | Completion date of the archived tasks.                                                                                                      |
| Actions   | When the icon is selected, you can:\*   **Duplicate** – Copy it to another workspace. The name, description, and checklist will be copied.  |

- **Unarchive** - Returns the task to its original project.
- **View More** - Shows the task details. |
:::

:::WorkflowBlockItem
**Projects:&#x20;**&#x54;he table presented in the **Projects** tab displays columns with the following information:

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/CKwApy3z5w4KeIYyUmI0D_image.png)

| **Item** | **Description**                                                                                                                                                |
| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name     | Name of the archived projects.                                                                                                                                 |
| Members  | Members of the archived projects.                                                                                                                              |
| Actions  | When the icon is selected, the View Tasks button will be displayed. Selecting the button shows a pop-up window with the list of tasks of the selected project. |

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/HLpQcPGv0vqKL3HKEc_S7_image.png)

- Task name.
- Completed checklists of the task.
- Task completion date.
- Number of attachments of the task.
- Unarchive and return the task to its original project.
:::

:::WorkflowBlockItem
**Workspaces:** The table presented in the **Workspaces** tab displays columns with the following information:

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/6mHyRK7jJXyTwKJ0u0U1F_image.png)

- Name of the archived workspaces.&#x20;
- Members of the archived workspaces.
- Actions: **Unarchive&#x20;**&#x61;nd return the task to its original project.
:::
::::


[title] What is PI Planning?
[path] Intro/

This document provides an overview of the PI Planning concept and how it relates to our Kanban tool (a method or approach for managing demands, tasks, or projects), Agility.

It is recommended to start with this section as it contains the most important concepts.

On the Main Screen, you can find a visual and explanatory step-by-step on how to use each Agility feature.

Here you will find concepts and benefits of PI Planning and how Agility is powerful for collaborative work.

## 1. What is PI Planning?

PI Planning is an agile practice adopted to plan and align the work of multiple teams on a project. It plays a key role in service management, enabling effective collaboration across teams, providing visibility into progress, and improving coordination of activities.

## 2. Benefits of PI Planning

::::WorkflowBlock
:::WorkflowBlockItem
****Better alignment between teams:**** PI Planning facilitates communication and collaboration between teams, ensuring everyone is aware of goals, deadlines and priorities.
:::

:::WorkflowBlockItem
****Visibility and transparency:**** When performing PI Planning, it is possible to have a clear view of the progress of activities and dependencies between teams, allowing for more informed decision-making.
:::

:::WorkflowBlockItem
****Early identification of issues:**** During PI Planning, teams can identify potential obstacles, risks or issues that could affect project success, allowing for early corrective actions.
:::

:::WorkflowBlockItem
****Efficient Resource Allocation:**** Helps ensure that resources are properly and optimally allocated to meet project requirements.
:::

:::WorkflowBlockItem
****More consistent deliveries:**** By planning collaboratively, teams have a shared understanding of goals and priorities, which leads to more consistent, higher quality deliveries. add workflow item
:::
::::

## 3. How the Agility Tool supports PI Planning

The Agility Tool is a powerful Kanban management system that offers specific features to facilitate PI Planning. These features include:

::::WorkflowBlock
:::WorkflowBlockItem
****Customizable Kanban boards:**** Agility lets you create custom Kanban boards for each team, making it easy to view and manage planned activities during PI Planning.
:::

:::WorkflowBlockItem
****Team integration:**** The tool allows the integration of several teams in a single environment, allowing effective coordination and collaboration during PI Planning.
:::

:::WorkflowBlockItem
****Dependency tracking:**** With Agility, you can map and track dependencies between team activities, providing a clear view of interrelationships and facilitating risk management.
:::

:::WorkflowBlockItem
****Metrics and KPIs tracking:**** The Agility tool offers the ability to monitor metrics and key performance indicators (KPIs) related to PI Planning. This allows you to assess progress, identify potential bottlenecks and take steps to improve the efficiency and quality of deliveries. add workflow item
:::
::::

## 4. PI Planning steps

While PI Planning steps can vary depending on your organization's specific needs and approach, here are some common steps to consider:

::::WorkflowBlock
:::WorkflowBlockItem
****Definition of goals and objectives:**** Teams must align themselves with project objectives, establishing clear and shared goals for the PI Planning period.
:::

:::WorkflowBlockItem
****Identifying Stories and Activities:**** Teams work together to identify user stories and activities needed to achieve established goals. This involves breaking work down into smaller tasks and assigning responsibilities.
:::

:::WorkflowBlockItem
****Effort Estimates:**** Each team estimates the effort required to complete planned stories and activities. These estimates can be made using techniques such as Planning Poker or other collaborative approaches.
:::

:::WorkflowBlockItem
****Identifying dependencies:**** During PI Planning, it is important to identify dependencies between stories, activities and teams in order to effectively manage risks and plan for necessary interactions.
:::

:::WorkflowBlockItem
****Sequencing and Prioritization:**** Based on effort estimates and identified dependencies, teams collaborate to sequence and prioritize stories and activities. This helps ensure that work runs logically and efficiently.
:::

:::WorkflowBlockItem
****Capacity and resource planning:**** During PI Planning, teams assess available resource capacity and perform proper planning to allocate resources efficiently, taking into account the constraints and needs of each team.
:::

:::WorkflowBlockItem
****Defining objectives for the PI period:**** Based on the planned work, teams establish measurable and achievable objectives for the PI Planning period. These objectives serve as a benchmark against which to measure progress and success at the end of the period
:::

:::WorkflowBlockItem
****Commitment and agreement:**** Teams review and discuss the overall plan resulting from PI Planning. All team members have the opportunity to share concerns, adjust estimates, and ensure common understanding before finalizing and agreeing on the plan. add workflow item
:::
::::

## Conclusion

PI Planning plays a crucial role, enabling efficient collaboration between teams, visibility into progress, early identification of issues, and efficient allocation of resources.

The Agility tool supports PI Planning by providing specific features such as customizable Kanban boards, team onboarding, dependency tracking and metrics tracking.

This documentation will provide a clear and objective understanding of the concept of PI Planning, along with the main related points and the support provided by the Agility tool. If you need more information or clarification, please do not hesitate to contact us.

## Glossary

### SAFe

SAFe, or Scaled Agile Framework, is a scalable agile management framework or model designed to help organizations implement agile practices on a large scale. It provides guidance and framework for companies looking to adopt agile methods in a broader enterprise environment, involving multiple teams, programs and portfolios.

### PI Planning

Program Increment Planning or Program Increment Planning

### Program

In the context of SAFe (Scaled Agile Framework), a program is an organizational unit comprising multiple agile teams working together to develop and deliver a software solution or product. A program is made up of a collection of agile teams collaborating to achieve a common goal.


[title] Teams and ART
[path] Using Agility/

On the Times and ART screen, you can create teams and Agile Release Trains (ARTs) to streamline the organization of your projects.

To access the screen, click on the Agile Work Management lightning bolt icon in the left sidebar menu, and then click on the Times and ART tab:

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/_N8GSMXwHzLIAuveBbb01_imagens-agility-6.gif)

The main screen is divided into two tabs: Times and ART. At the top of the screen, there is a search box that allows you to search by name. The search will be performed for both Teams and ARTs.

## Teams

The teams' tab displays a table with the registered teams, an option to add a new team, and some information divided into columns.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/eoNf_OPLnu6iKbJ7ABsxT_image.png" size="36" width="117" height="47" position="center" showCaption="false"}

The creation button displays a pop-up window with some information to be filled in:

- **Team Name**;
- **Team Objective**;
- **Team Color**;
- **Members**: Choose one or more members for the team;
  - When selecting a member, the option to remove the added member will be presented, as well as the option to select the member's profile type;
- **Cancel** or **Save**

### Table

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/-k7spg5UtV3K0adD1AHhM_image.png)

The presented table organizes the information in the following columns:

- **Team Name**;
- **Team Members**;
- **Team Colors**;
- **Actions**: Clicking on the icon displays an **Edit** button. This button allows editing the name, objective, color, members, and profile of the team. Currently, the members can be of the administrator or member type.

:::hint{type="warning"}
**⚠️&#x20;*****Attention!*** Only the user logged in with an administrator profile can make this profile change.
:::

### ART (Agile Release Train)

The ART tab displays a table with the registered ARTs, an option to add a new ART, and some information divided into columns.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/brMhIEvcWPwxqJc3iKEaD_image.png" size="38" width="118" height="75" position="center" showCaption="false"}

The creation button displays a pop-up window with some information to be filled in:

- **ART Name**;
- **Add Team**;
- **Add Member**;
  - More than one team and more than one member can be added;
  - Only active teams not linked to another ART will be presented;
- **Cancel** or **Save**;

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/Gez1j2RvujL8-iSQmvpJC_image.png)

The presented table organizes the information in the following columns:

- **ART Name**;
- **Teams** for each ART;
- **Members** for each ART;
- **Actions**: Clicking on the icon displays an **Edit** button. This button allows editing the name, members, and teams of the ART.


[title] Project Metrics
[path] Using Agility/Main Screen/Projeto/

In project management, <font color="#2166ae">**metrics** </font>are important for quantifying the work of team members with the aim of achieving the results and goals established in the company's strategic plan.

## Before You Begin

- [ ] Have a screen of [Workspace](docId:3QI_ThmCwswX6hlMDoXyp);
- [ ] Have a [Project](docId\:RRmATmr69epZ4rPMvidBN) created;
- [ ] If you want a lane in addition to the system's defaults (**On Hold**, **In Progress**, and **Completed**), create a lane;
- [ ] Have a [Task](docId\:UEODcDaJ6j_Y9xngPZvI2) created, along with its estimated hours for each card.

## Procedure

With the card placed in the **Completed** lane, click on **Metrics** to view the team metrics. They will be displayed as shown in the **figure below.**

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/rbRqiJadRhGOGFnFILBwh_metricas-do-projeto-1.png)

::::WorkflowBlock
:::WorkflowBlockItem
### Planning

| **Option**    | **Description**                                                                                                                                                                                                                                  |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Capacity**  | Displays the maximum capacity (hours) that the member has available to work on the project. Define it during the creation or editing of the project;                                                                                             |
| **Allocated** | Displays how many hours have already been allocated to tasks. Set it when a member is assigned to a task and when the estimated hours for that task are set. The estimated hours will be divided equally among all members assigned to the task; |
:::

:::WorkflowBlockItem
### Tracking

| **Option**    | **Description**                                                                                                                                                                                                                                                                                                          |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Completed** | Displays the amount of hours, tasks, that the member has already completed. Set it when a task is completed and the worked hours are logged                                                                                                                                                                              |
| **Expected**  | Displays the dynamic value per day, obtained by dividing the capacity value by the number of working days in the project. The hours count is from D+1, meaning if a 10-day sprint started today with a capacity of 50 hours, it starts counting from tomorrow, but today is still counted, it is just not shown on day 1 |
:::

:::WorkflowBlockItem
### Tasks without estimates

Displays the number of tasks without estimated hours;
:::

:::WorkflowBlockItem
### Task progress

| **Option**                              | Descriptio**n**                                                                                                                                                |
| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Total relative to planning capacity** | The total capacity available to the member or team - the same value that is in the table in the capacity field                                                 |
| **Expected**                            | The value related to the expected progress (the expected value for the member or team - the same value that is already in the table in the expected field)     |
| **Completed**                           | The value related to the completed progress (the value of completed hours for the team or member - the same value that is in the table in the completed field) |
:::

:::WorkflowBlockItem
### Overdue tasks

When there are overdue tasks, the symbol stands out to show the number of tasks in the project that are overdue.
:::

:::WorkflowBlockItem
### Bugs

Displays in red the number of tasks marked as bugs;
:::

:::WorkflowBlockItem
### Rework

Displays in red the number of tasks marked as rework.
:::
::::


[title] Main Screen
[path] Using Agility/

In the main screen of **Agile Work Management**, it is possible to perform several actions. To access the main screen, click on the lightning bolt icon on the left side menu.

In the top right corner are two buttons for <font color="#2166ae">**Add Workspace**</font> and <font color="#2166ae">**Add PI Planning**</font>, and at the top of the screen is a box for <font color="#2166ae">**Search** </font>and <font color="#2166ae">**Filter options**</font>.

# Home

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/oDQkpWb7ut550_1vzmulh_workspace1.png)

| **Field**          | **Description**                                         |
| ------------------ | ------------------------------------------------------- |
| 1. Menu            | Side navigation menu                                    |
| two. Add Workspace | Button to add information about a new workspace         |
| 3. Add PI Planning | Button for adding information about a new PI Planning   |
| 4. Search          | Search box                                              |
| 5. Metrics         | Metric information from all workspaces and PI Plannings |
| 6. Workspaces      | List of Workspaces and PI Plannings                     |

## 2. Add Workspace

After clicking on the Add Workspace button, a pop-up screen will appear, requiring you to include:

- The name for the new Workspace;
- Select members;&#x20;
- Cancel or Save;&#x20;

## 3. Add PI Planning&#x20;

The <font color="#2166ae">**Add PI Planning**</font> button allows you to insert a new item from this category. some information for the new PI Planning must be filled in:&#x20;

- Enter a name;&#x20;
- Select a Program or Product from the list offered;&#x20;
- Set the start date by clicking on the calendar icon;&#x20;
- Choose the size of the Sprint in days;&#x20;
- Choose the number of Iterations (minimum 2 and maximum 12);&#x20;

After entering this information, click Next.&#x20;

The next step is to Add Art's. For that choose 1 or more Art's from the list.

The third step will be to fill in the Iterations information.

- Enter a name for the Iteration;&#x20;
- The number of iterations and the start and end dates will be defined automatically according to the start date, the sprint size and the number of iterations, defined in the previous step;&#x20;

The last step is to select the members. After completing all the steps, click Create to finalize the creation, or cancel if there is any error in the information.

## 4. Search and Filters&#x20;

The Search field lets you search by name or apply filters. The search will be done across all Workspaces, Projects and Tasks. The filters button allows you to filter by deadline, defining a start date and an end date, which will also be applied to all Workspaces, Projects and Tasks. There is also a button to clear any applied filters.

## 5. Metrics

The initial screen will display a summary of the established deadlines for all workspaces of the logged in user.&#x20;

- **On deadline**: shows the total of Tasks that have a "Delivery date" greater than 24h from the date
- **Due**: shows the total of Tasks that have the "Delivery date" that will be due in 24 hours from the current date/time;
- **Overdue**: shows the total of Tasks that have the "Delivery date" less than the current date/time;
- **Total**: sum of all Tasks;

## 6. Workspaces

Below the metrics section, you will see a list of all Workspaces and PI Plannings.

Each Workspaces or PI Planning will display its metric:

**On time**: shows the total of the Tasks of that Workspace or PI Planning, which have the "Delivery Date" greater than 24 hours from the current date/time;

**Due**: shows the total Tasks of that Workspace or PI Planning, which have the "Delivery date" that will be due in 24 hours from the current date/time;

**Overdue**: shows the total of Tasks from that Workspace or PI Planning, which have the "Delivery Date" less than the current date/time;

**Total**: sum of all Tasks of that Workspace or PI Planning;

Select a Workspace or POI to view more information: Check out the [Workspace](docId:3QI_ThmCwswX6hlMDoXyp) doc.


[title] Documents
[path] Using Agility/Gestão de Cerimônias/

Ceremony management documents help include information in Agility cards and tasks. They can be linked to specific cards to add additional or more detailed information, since cards should contain brief information. Each document allows for simple text formatting and command inclusion.

## Documents

To add a document to a template, double-click on a template from the [Templates](#) list.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/2GJdgwjEY2K98jlCdfgzW_image.png)

A screen will appear containing a text editing field. Click the Edit icon in the upper right corner to add text to the field.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/pIDfVTcPgCNtn4ar-euRz_image.png)

The text accepts simple MarkDown formatting commands. To see the list of commands, type / at the beginning of a new line.

The commands allow you to add various functionalities to the template, such as linking cards, tables, or other Agility information.

After including the desired information and commands, click Save in the upper right corner to apply the changes.

### Link Card

The main function of documents is to link Agility tasks. This command automatically adds comments to a linked card and notifies a designated member about the change. To use this function, select the **Link card** option from the command list.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/dLxSR_AW0zEgcy-FWaHTi_image.png)

In the first field, select a card from the displayed projects and tasks. You can search by card name or card number.

The recipient field indicates which user will be notified about changes to the selected card. Only members of the linked project will be displayed in the recipient list.

In the note field, include a message to be added to the card.

After entering the information, click Save to add the command to the document.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/ge9NAoxqWTVjiik2x3XO8_image.png" size="46" width="338" height="96" position="center" showCaption="false"}

With the command added, clicking on the command will open the respective card in another browser tab, and the comment specified in the command will be added to the card.

[title] Ceremony Templates
[path] Using Agility/Gestão de Cerimônias/

The Ceremony Manager Templates screen displays a list of templates created in the system.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/4S-v_FIyjgV5npzVYYeOq_image.png)

## Creating a template

To create a new template, click the Add button in the upper right corner of the screen, next to the search bar.

A new menu will appear on the right side with fields to include information for the new template:

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/BdMInbv6HVJWl-78dJfeQ_image.png" size="66" width="507" height="736" position="center" showCaption="false"}

In the Name field, enter the template name. In the Description field, include a brief description indicating the template's purpose.

After entering the information, click Save to add the template to the list.

In the template list, click the Edit icon to return to the creation screen.

## Documents

After creating a template, you can add a document template to it. To view a template's document template, double-click on a template in the list. For more information about documents, see [Documents](#).


[title] User Terms of Service - Agility
[path] /

These User Terms of Service ("Terms") are a legally binding contract between you and Run2biz and explain the rules governing your use of our Services and Sites. These Terms apply to you as a Service user, subject to exceptions that apply to Authorized Users (as defined and detailed below in the section entitled "How These Terms Apply; Users and Customers"). By accessing or using the Service and the Sites, you acknowledge and agree to be bound by these Terms (as applicable) and confirm that you have read and understood our Privacy Statement, which is incorporated by reference.

If you do not agree to these Terms, do not access or use the Service or the Sites.

Run2biz may revise these Terms over time and will post the modified version on our website. If, at the sole discretion of Run2biz, the modifications to these Terms are significant, we will provide you with reasonable notice before the change takes effect, either by sending an email to the email address associated with your account or by alerting you through the Service and/or Sites. If you do not agree or cannot comply with the modified Terms, you must stop using the Service and the Sites. Unless otherwise provided in these Terms or our notice, the updated Terms will take effect upon posting and will apply continuously. Your continued use of the Service and the Sites after any updates to these Terms constitutes your acceptance of such changes.

HOW THESE TERMS APPLY; USERS AND CUSTOMERS


By using Run2biz, you fall into one or more of the following three different categories of Run2biz users:

### "Site Visitors"&#xD;

They are users of the Sites.

### "Trial Users"

They use the trial version of the Service. Trial Users have access to a more limited set of Service features and functionalities than Authorized Users. Free Users may have their own individual workspaces and/or participate in a free Run2biz domain for up to 03 users during the specified trial promotion period.

### "Authorized Users"

They use the Service as part of any paid Run2biz subscription plan purchased by a person or entity (the "Customer") who has separately entered into a written agreement with Run2biz (the "Customer Agreement") governing access to and use of the Service and allowing the Customer to create and configure Run2biz so that Authorized Users can participate.

To the extent that you are an Authorized User, only the following sections of these Terms will apply to you: "Some initial issues" and "How these terms apply; users and customers."

As an Authorized User, you gain access to the Service through a Run2biz Customer. For example, if you are joining your employer's organization, the Customer is your employer. If you are joining a workspace created by your friend using a personal email address, your friend is the Run2biz customer and is authorizing you to enter his workspace. The Customer Agreement governs our relationship and commitment to deliver the Service to the Customer, who can then invite Authorized Users to participate in Run2biz. When you or another Authorized User submits content or information to the Service, such as messages or files ("Customer Data"), you acknowledge and agree that, between Run2biz and the Customer, the Customer Data is controlled by the Customer and the Customer Agreement provides the Customer with options and control over that Customer Data. For example, the Customer can manage permissions, enable or disable third-party integrations, or take action to expand, consolidate, or share Agility workspace, project, task, and subtask content, and these options and instructions may result in the access, use, disclosure, modification, or deletion of certain or all Customer Data.

BETWEEN RUN2BIZ AND THE CUSTOMER, YOU ACKNOWLEDGE AND AGREE THAT IT IS SOLELY THE CUSTOMER'S RESPONSIBILITY (A) TO INFORM YOU AND ANY OTHER AUTHORIZED USERS OF ANY RELEVANT CUSTOMER POLICIES, PRACTICES, AND SETTINGS THAT MAY AFFECT THE PROCESSING OF CUSTOMER DATA; (B) TO OBTAIN ANY RIGHTS, PERMISSIONS, OR CONSENTS FROM YOU AND ANY OTHER AUTHORIZED USERS THAT ARE NECESSARY FOR THE LAWFUL USE OF CUSTOMER DATA AND THE OPERATION OF THE SERVICE; (C) TO ENSURE THAT THE TRANSFER AND PROCESSING OF CUSTOMER DATA UNDER THE CUSTOMER AGREEMENT ARE LAWFUL; AND (D) TO RESPOND TO AND RESOLVE ANY DISPUTE WITH YOU AND ANY OTHER AUTHORIZED USERS REGARDING CUSTOMER DATA, THE SERVICE, OR CUSTOMER'S INABILITY TO COMPLY WITH THESE OBLIGATIONS. IN YOUR CAPACITY AS AN AUTHORIZED USER, RUN2BIZ MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND (EXPRESS OR IMPLIED) TO YOU RELATED TO THE SERVICE, WHICH IS PROVIDED TO YOU "AS IS" AND "AS AVAILABLE."

ELIGIBILITY AND COVERAGE


To use the Service and the Sites, you need to have, and you represent and warrant that you have, at least 18 years of age and are competent to agree to these Terms. If the legislation where you reside requires you to be of legal age for Run2biz to legally provide the Service and the Sites to you and use your data without parental consent, you must be of legal age.

If the statements in the preceding sentence are not true, or if Run2biz has previously prohibited you from accessing or using the Service and Sites, you will not be able to access or use the Service and Sites.

ACCOUNT REGISTRATION AND USE


Account Registration and Confidentiality. To access the Service and Sites, you must register for a Run2biz account by creating a username and password. You agree to provide accurate, complete, and current registration information about yourself. It is your responsibility to ensure that your password remains confidential and secure. By registering, you agree that you are fully responsible for all activities that occur under your username and password. We may assume that any communications we receive in your account were made by you. If you are the owner or administrator of a workspace or organization, or if you have confirmed in writing that you have authority to make decisions on behalf of a workspace or organization ("Account Administrator"), you represent and warrant that you are authorized to do so and agree that Run2biz has the right to rely on your instructions.

UNAUTHORIZED ACCOUNT USE


You are responsible for notifying us at support\@run2biz.com if you become aware of any unauthorized use or access to your account. You understand and agree that we may require you to provide information that can be used to confirm your identity and help ensure the security of your account. Run2biz will not be liable for any loss, damage, liability, expenses, or legal fees you may incur as a result of someone else using your password or account, with or without your knowledge and/or authorization, and regardless of whether you have informed us about such unauthorized use. You will be responsible for losses, damages, liability, expenses, and legal fees incurred by Run2biz or third parties due to the use of someone else's account. If the Account Administrator or Customer loses access to an account or requests information about an account, Run2biz reserves the right to request from the Account Administrator or Customer any verification it deems necessary before restoring access or providing information about that account, at its sole discretion.

LICENSE AND ACCEPTABLE USE


Your License. Subject to your compliance with these Terms, we grant you a limited, non-exclusive, non-transferable, revocable, and non-sublicensable right to access and use the Service and Sites solely for your internal use (or for internal uses authorized by the applicable Account Administrator) and only in a manner that complies with these Terms and all applicable legal requirements related to your use of the Service and Sites. Run2biz may revoke this license at any time, at its sole discretion.

ACCEPTABLE USE POLICY


You acknowledge and agree to comply with these Terms, including the following rules regarding acceptable use of the Service and Sites ("Acceptable Use Policy").

SERVICE INTERRUPTION


You may not access, tamper with, or use non-public areas of the Service and Sites, Run2biz computer systems, or technical delivery systems of Run2biz providers; probe, scan, or test the vulnerability of any system or network or breach or circumvent any security or authentication measure; access or search the Service and Sites by any means other than the publicly supported interfaces provided by Run2biz (e.g., "scraping"); or interfere or attempt to interfere with, disrupt, or disrupt our infrastructure or the access of any user, host, or network, including, without limitation, transmitting a virus, overloading, flooding, spamming, bombing the Service and Sites by email, or scripting to create User Content in a manner that interferes with or creates an undue burden on the Service and Sites.

MISUSE OF THE SERVICE AND SITES


You may not use the Service and Sites to conduct, promote, or support any illegal or fraudulent activities; impersonate another person or entity or misrepresent an affiliation with a person or entity (e.g., "spoofing", "phishing"); activities that are defamatory, libelous, or threatening, constitute hate speech, harassment, or stalking; violate the privacy rights of third parties, including publishing or posting confidential or personal information of others without their express authorization and permission; sending unsolicited communications, promotions, or spam; publishing or linking to malicious content; or promoting or advertising products or services that are not yours without proper authorization.

## USER CONTENT

You may not post any User Content on the Service or Sites or use the Service or Sites in a manner that violates any applicable law (including export control laws), third-party intellectual property rights, or any person's privacy or publicity rights; be deceptive, fraudulent, illegal, obscene, defamatory, derogatory, slanderous, threatening, or pornographic (including child pornography, which, upon becoming aware, we will remove and report to law enforcement, including the National Center for Missing and Exploited Children); constitute hate speech, harassment, or stalking; criticize, censure, or attack others based on their race, ethnicity, nationality, religion, sex, gender, sexual orientation, disability, or medical condition; contain any personal information of individuals under the age of 18; contain any sensitive personal information as defined by applicable law (such as financial information, payment card numbers, social security numbers, or health information) without Run2biz's prior written consent granted as part of a Customer Agreement; contain viruses, bots, worms, or similar harmful materials; or contain any information that you do not have the right to make available under legislation or any contractual or fiduciary duty; could cause harm to Run2biz or third parties.

VIOLATIONS OF ACCEPTABLE USE


If we reasonably believe that a violation of this Acceptable Use Policy has occurred or is likely to occur in the near future in a way that may disrupt the Service or Sites for our Customers or other users, we may suspend or terminate your access to the Service and Sites, without any liability to us and in addition to any other remedies that may be available to us. Run2biz reserves the right to notify the applicable Account Administrator of the foregoing.

PROPRIETARY RIGHTS


Run2biz and its licensors exclusively own all intellectual property rights related to the Service and Sites. You agree to comply with all copyright laws and other applicable laws, as well as any additional copyright notices or restrictions contained in the Service and Sites. All rights present and future to trade secrets, patents, copyrights, trademarks, service marks, know-how, and other proprietary rights of any kind under the laws of any governmental authority, national or foreign, including, without limitation, rights to and for all applications and registrations related to the Service and Sites, are and shall remain the sole and exclusive property of Run2biz.

USER CONTENT AND FEEDBACK


User Content and Submissions to the Service. The Service allows you to create tasks and submit associated information, text, files, and other materials (collectively, "User Content") and share this User Content with others. The User Content submitted or made available to the Service is subject to the following terms:

User Trial Content. Trial Users retain ownership of the User Content they submit to the Service ("User Trial Content"). By submitting User Trial Content, Trial Users grant Run2biz a license to access, use, copy, reproduce, process, adapt, publish, transmit, and display such User Trial Content, to provide the Service and as permitted by Run2biz's Privacy Statement, including as required by law or in good faith to comply with legal process. We reserve the right to remove any User Trial Content on the Service that violates these Terms or is otherwise objectionable at Run2biz's sole discretion.

Authorized User Content in the Service. User Content submitted to the Service by Authorized Users is Customer Data, which is owned and controlled by the Customer, in accordance with the Customer Agreement.

Feedback. The Service and Sites may have certain features that allow you to submit comments, information, and other materials (collectively, "Feedback") to Run2biz and/or share such Feedback with other users or the public. If you submit Feedback, Run2biz may use it for any purpose, without any compensation or obligation to you. We reserve the right to remove any Feedback posted on our public forums for any reason, at our sole discretion.

User Content and Feedback Representations. You represent and warrant that you have all necessary rights to submit User Content and Feedback without violation or infringement of any third-party rights. You understand that Run2biz does not control and is not responsible for User Content or Feedback, and that, by using the Service and/or Sites, you may be exposed to User Content or Feedback from other users that may be offensive, indecent, inaccurate, misleading, or otherwise objectionable.

WARRANTIES, DISCLAIMERS, AND LIMITATION OF LIABILITY


THE SERVICE AND SITES AND USER CONTENT, WHETHER PROVIDED BY RUN2BIZ, ITS LICENSORS, ITS SUPPLIERS, OR USERS, AND OTHER INFORMATION ABOUT OR ACCESSIBLE FROM THE SERVICE AND SITES ARE PROVIDED "AS IS" WITHOUT WARRANTY, REPRESENTATION, CONDITION, OR WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING, WITHOUT LIMITATION, ANY IMPLIED WARRANTIES, REPRESENTATIONS, CONDITIONS, OR WARRANTIES OF QUALITY, MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT, ALL OF WHICH ARE DISCLAIMED TO THE MAXIMUM EXTENT PERMITTED BY LAW. SPECIFICALLY, BUT WITHOUT LIMITATION, RUN2BIZ DOES NOT WARRANT THAT: (i) THE INFORMATION AVAILABLE ON THE SERVICE AND SITES IS FREE OF ERRORS; (ii) THE FUNCTIONS OR FEATURES (INCLUDING, WITHOUT LIMITATION, MECHANISMS FOR UPLOADING AND DOWNLOADING USER CONTENT) WILL BE UNINTERRUPTED, SECURE, OR FREE OF ERRORS; (iii) DEFECTS WILL BE CORRECTEDthe the shortly OR (iv) THE SERVICE AND SITES OR THE SERVER(S) THAT MAKE THE SERVICE AND SITES AVAILABLE ARE FREE OF VIRUSES OR OTHER HARMFUL COMPONENTS. RUN2BIZ DOES NOT WARRANT, ENDORSE, ASSURE, OR ACCEPT RESPONSIBILITY FOR ANY PRODUCT OR SERVICE ADVERTISED OR OFFERED BY THIRD PARTIES THROUGH THE SERVICE AND SITES OR ANY SITE FEATURED OR LINKED THROUGH THE SERVICE AND SITES, AND RUN2BIZ WILL NOT BE A PARTY TO OR IN ANY WAY RESPONSIBLE FOR MONITORING ANY TRANSACTION BETWEEN YOU AND THIRD-PARTY PROVIDERS OF PRODUCTS OR SERVICES AND SITES. RUN2BIZ SHALL NOT BE RESPONSIBLE FOR THE OFFENSIVE OR ILLEGAL CONDUCT OF THIRD PARTIES. YOU VOLUNTARILY ACCEPT THE RISK OF HARM OR DAMAGE FROM THE FOREGOING. THE ABOVE LIMITATIONS SHALL APPLY EVEN IF A REMEDY FAILS ITS ESSENTIAL PURPOSE AND TO THE MAXIMUM EXTENT PERMITTED BY LAW.

IN NO EVENT SHALL RUN2BIZ OR ITS AFFILIATES, LICENSORS, SUPPLIERS, OR ANY OF THEIR RESPECTIVE DIRECTORS, OFFICERS, EMPLOYEES, AGENTS, OR OTHER REPRESENTATIVES BE LIABLE TO YOU OR ANY OTHER PERSON OR ENTITY FOR ANY SPECIAL, INCIDENTAL, CONSEQUENTIAL, OR PUNITIVE DAMAGES (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF PROFITS, LOSS OF DATA, LOSS OF USE, OR COSTS OF OBTAINING SUBSTITUTE GOODS OR SERVICES) ARISING OUT OF OR IN CONNECTION WITH THE SERVICE AND SITES, ANY MATERIALS, INFORMATION, OR RECOMMENDATIONS APPEARING ON THE SERVICE AND SITES, OR ANY LINK PROVIDED ON THE SERVICE AND SITES, WHETHER BASED ON WARRANTY, CONTRACT, TORT, STRICT LIABILITY, STATUTE, OR OTHERWISE. THIS LIMITATION OF LIABILITY SHALL APPLY TO THE MAXIMUM EXTENT PERMITTED BY LAW. IN ANY CASE, OUR AGGREGATE LIABILITY SHALL NOT EXCEED $100.00 (ONE HUNDRED U.S. DOLLARS).

INDEMNIFICATION


YOU AGREE TO INDEMNIFY, DEFEND, AND HOLD HARMLESS RUN2BIZ, ITS AFFILIATES, AND THEIR RESPECTIVE DIRECTORS, OFFICERS, EMPLOYEES, MEMBERS, SHAREHOLDERS, CONTRACTORS, OR REPRESENTATIVES FROM AND AGAINST ANY CLAIM OR DEMAND, INCLUDING, WITHOUT LIMITATION, REASONABLE ATTORNEYS' FEES, MADE BY ANY THIRD PARTY ARISING OUT OF OR IN CONNECTION WITH YOUR USE OF THE SERVICE AND SITES, YOUR CONNECTION TO THE SERVICE AND SITES, YOUR VIOLATION OF THE TERMS, YOUR VIOLATION OF ANY APPLICABLE LAW, YOUR SUBMISSION, POSTING, OR TRANSMISSION OF USER CONTENT TO THE SERVICE AND SITES, AND/OR YOUR VIOLATION OF ANY RIGHTS OF ANOTHER PERSON OR ENTITY. WE RESERVE THE RIGHT, AT OUR OWN EXPENSE, TO ASSUME THE EXCLUSIVE DEFENSE AND CONTROL OF ANY MATTER OTHERWISE SUBJECT TO INDEMNIFICATION BY YOU, AND IN SUCH CASE, YOU SHALL COOPERATE WITH US IN ASSERTING ANY AVAILABLE DEFENSES.

THIRD-PARTY LINKS, SERVICES, AND SITES


The Service and Sites may include information and content provided by third parties, including links to third-party websites, resources, and/or goods and services. Run2biz is not responsible and shall not be liable for any damages or losses caused or related to (i) any content, advertising, products, or other materials on or available from such websites or resources, (ii) the availability or any errors or omissions on such websites or resources, or (iii) any information manipulation or other business practices of the operators of such websites or resources. Your interactions with these third parties will be governed by their own terms of service and privacy policies and any other similar terms.

GENERAL TERMS


Modifications to the Service. We reserve the right to modify or discontinue, temporarily or permanently, the Service and Sites (or any part thereof) at any time, with or without notice. You agree that Run2biz shall not be liable to you or any third party for any modification, suspension, or discontinuance of the Service and Sites.

Governing Law. These Terms shall be governed by the laws of Brasília, notwithstanding its conflict of legal principles. However, some countries (including those in the European Union) have laws that require agreements to be governed by the local laws of the by country. This paragraph does not override such laws.

Initial Dispute Resolution. Most disputes can be resolved without resorting to formal dispute resolution. If you have any issues with us or our Service, you agree that before taking any formal action, you will contact us at support\@run2biz.com and provide a brief written description of the dispute and your contact information (including your username if your dispute is related to an account). Except for claims of intellectual property infringement and small claims, the parties agree to use their best efforts to settle any dispute, claim, question, or disagreement directly through consultation with Run2biz, and good-faith negotiations shall be a condition to either party initiating a lawsuit.

No Waiver. Run2biz's failure to exercise or enforce any right or provision in these Terms shall not constitute
&#x20;a waiver of such right or provision. If any provision of these Terms is found to be invalid or unenforceable, the parties agree that the court should endeavor to give effect to the , intentions as reflected in the provision, to the maximum extent permitted by law, and the other provisions of these Terms shall remain in full force and effect.

Third-Party Beneficiaries. Except as expressly provided otherwise in these Terms, there shall be no third-party beneficiaries to these Terms.

a partiesconsumerEntire Agreement. These Terms (together with all terms and conditions incorporated herein) constitute the entire agreement between you and Run2biz and supersede any prior agreements between you and Run2biz regarding the subject matter. In the event of any conflict or inconsistency between the provisions of these Terms and any other terms or resources referred to in these Terms, the terms directly contained in these Terms shall prevail first; provided, however, that if there is a conflict or inconsistency between an applicable Customer Agreement and these Terms, the terms of the Customer Agreement shall prevail first, followed by the provisions of these Terms, and followed by the pages referred to in these Terms (e.g., the Privacy Statement). The applicable Customer shall be responsible for notifying Authorized Users of such conflicts or inconsistencies, and to the extent of such notification, the terms set forth herein shall be binding.

General Provisions. These Terms and any rights or licenses granted hereunder may not be assigned or delegated by you. These Terms and any rights or licenses granted hereunder may be assigned or delegated by Run2biz without restriction. These Terms shall bind and inure to the benefit of each party and the respective authorized successors and assigns of the party. These Terms may not be modified by oral statement of a representative of Run2biz. No agency, partnership, joint venture, or employee-employer relationship is intended or created by these Terms. You agree that any agreements made by and between you and us in electronic format are just as legally binding as if made in physical, written format. If you are using the Service and Sites for or on behalf of the government of Brazil, your license rights shall not exceed those granted to non-governmental consumers. The section titles in these Terms are for convenience only and have no legal or contractual effect. Any provision of these Terms that, by its nature, is reasonably intended to survive beyond its termination or expiration, shall survive. Notwithstanding the foregoing, the following sections shall survive any termination or expiration of these Terms: "Initial Dispute Resolution," "How These Terms Apply; Users and Customers," "Proprietary Rights," "User Content and Feedback," "Warranties, Disclaimers, and Limitations of Liability," "Indemnification," and "General Terms."

Notifications. We may provide notice to you through email, by postingnotice on the Service and Sites, or by any other method we choose, and such notice shall be deemed effective upon transmission.

## Questions

If you have any doubts about these Terms, please contact us at support\@run2biz.com.


[title] Agility - Overview
[path] Intro/

Agility is an easy-to-use platform for agile activity management. It was created to manage projects in the simplest way, with features to **organize**, **monitor**, and **delegate activities** among team members or individually.

Agility is based on the Kanban and SAFe (Scaled Agile Framework) methodologies.

SAFe is an agile framework that provides a simple and lightweight experience, helping to bring better products to market faster. It promotes **alignment**, **collaboration**, and **delivery** among multiple agile teams.

Using Agility, you can organize and customize your Kanban boards with different colored Tags ([Task](#)), customize swimlanes, and practically automate time metrics, as well as record comments and various useful information for each task.


[title] Agility Installation Guide
[path] Support/

# Prerequisites for installation

- [ ] FrontManager installation
- [ ] Configuration of tenants and applications
- [ ] Central IT infrastructure access data (git credentials, nexus credentials)
- [ ] kubectl configured for the environment where it will be deployed (this includes the project's environment variables, with their appropriate access data).

## Tools

- Database (PostgreSQL 13+ / SQLServer 2019+ / Oracle 12c+)
- KeyCloak (must already be installed as FrontManager depends on it)
- MiniIO (must already be installed as FrontManager depends on it)
- Kafka (must already be installed as FrontManager depends on it)

# Installation steps

Steps to install Agility:

- Clone the hyper-kanban-api repository

:::BlockQuote
git clone http\://gitlab.centralit.io/centralit/hyper-platform/hyper-kanban-api.git
:::

- Enter the folder where the project was cloned and check out the devel branch

:::BlockQuote
git checkout devel
:::

- Run Step 1. Migrations
- Run Step 2. Deploy

## Step 1. Migrations

The `migrations.sh` script processes migrations for multiple databases according to the settings present in a migrations file in json format which by default is migrations-config.json in the same folder as the script.

### Migrations-config.json file

The file must follow the structure below:

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/eciJzu7zg6TaeznNNQ7VI_image.png)

Where the attributes of each tenant that follows:

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/gIsKKe2OGaiqOhwZr1wox_image.png" size="80" width="639" height="347" position="center" showCaption="false"}

### Example

Example file with two tenants (`citsmart and tenant1`) for the `hyper-kanban-api` application development environment (this application).

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/TGQxYWPoJzXcvmg0zUOe4_image.png)

### Running the migrations.sh script

**How to use**

:::BlockQuote
./migration.sh \<TenantName> ...
:::

**Example**

:::BlockQuote
./migration.sh citsmart tenant1
:::

## Step 2. Deploy

### Via gitlab CI

For some environments, there is already automation in gitlab, where simply merging to the branch already triggers the deployment of the product (apps.centralit, labcentral). These are the cases of branches with prefix `deploy/`

Gitlab CI example on the deploy/apps.centralit.com.br branch&#x20;

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/KewmGvQ08jMnFzdAFCvDd_image.png)

### Manual via kubectl script

To do it manually, the template files for the environment in question must be created:

configmap.template.yml

deployment.template.yml

ticket.template.yml

service.template.yml

In this case, the only file to be updated would be the configmap.template.yml (environment variables), the rest of them follow the same pattern and content. The files must be created in the k8s folder, in a new folder named after the environment. After that, the `k8s-apply.sh` script must be executed passing which environment will be updated with deploy. Ex: `k8s-apply.sh dev-eveo`

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/HJQPqtMOob5sJLhJCuL2u_image.png)

### Updating directly in Rancher

In cases where the Kubernetes environment already exists and it is only necessary to update the package, just change the package path to the one available in the registry.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/KN6Q0XoYa3LewS_DZEVBW_image.png)


[title] Release
[path] Using Agility/

The Release screen displays a list of registered releases and allows you to register and link new releases.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/f27mn-5fKmMTrBqwc_EDt_image.png)

The Releases list shows information about each release divided into columns:

1. **ID** - Release ID
2. **Title** - Release name
3. **Description** - Release description
4. **Type** - Release type
5. **Version** - Release version
6. **Features** - Features linked to the Release
7. **Swimlanes** - Swimlanes linked to the Release
8. **Start Date** - Release start date
9. **End Date** - Release end date
10. **Action** - Available actions for the release:
    - Edit - Displays the creation screen with fields pre-filled for editing

At the bottom of the page, a button displays page numbering and the number of releases to be shown in the view.

# Procedure

## Create new release

In the upper right corner of the screen, select the **Create Release** button to display the release creation screen:

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/IWXDqOIeexrsQTu5OoZ9M_image.png)

| **Field**      | **Description**                                         |
| -------------- | ------------------------------------------------------- |
| ID             | ID number will be automatically generated by the system |
| Title(\*)      | Enter the release title                                 |
| Version(\*)    | Enter the version                                       |
| Type(\*)       | Select the type (Fix or Release)                        |
| Active         | Select whether it's active or not                       |
| Description    | Enter the description                                   |
| Start date(\*) | Select the start date                                   |
| End date       | Select the end date                                     |

Fields marked with (\*) are mandatory.

### Features

| **Field**               | **Description**                                                                |
| ----------------------- | ------------------------------------------------------------------------------ |
| Register new Feature    | Option to register a new feature, which opens the feature registration screen. |
| Search existing Feature | Search and select an existing feature.                                         |

After selecting a feature, the linked release will be displayed (if one exists), along with an option to replace the link with the release currently being created.

After linking, a table will be displayed showing the ID and name of the release, and an action to remove the link.

### Swimlanes

|                  |                                                       |
| ---------------- | ----------------------------------------------------- |
| Search Workspace | Search and select a Workspace                         |
| Search Project   | Search and select a project from the chosen Workspace |
| Search Swimlane  | Search and select a swimlane from the chosen project  |

After selection, the option to link the swimlane will be enabled.

After linking, a table will be displayed showing the ID, swimlane name, card name, project name, workspace name, and an action to remove the link.

At the bottom of the screen, click **Save** to create the new release.

[title] Untitled
[path] /


[title] Costs
[path] Using Agility/

The Costs screen allows you to create descriptions and costs to be linked elsewhere, as well as displays information about them.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/ZcEefhMuFET46kuG_r8c8_1-1920-x-1080-px5.png)

1. **Main menu** - Expands or collapses the **Agility** main menu.
2. **Search** - Allows searching/filtering costs by Name, as well as clearing filters.
3. **Add cost** - Click the button to add a new cost. A screen will be displayed with fields to enter the Cost name and description. Press Save to create a new cost or Cancel to return to the costs screen.
4. **Name** - Name of the cost.
5. **Description** - Cost description.
6. **Actions** - Available actions for the cost:
   - Edit - shows the cost creation screen with fields pre-filled for editing
   - Delete
7. **Listing and pages** - Allows navigation through page listings and selecting how many items to display per page.


[title] PI Planning
[path] Using Agility/

## What is PI Planning?

PI Planning is an agile practice adopted to plan and align the work of multiple teams in a project. It plays a fundamental role in service management, enabling effective collaboration between teams, providing visibility of progress, and improving coordination of activities.

# Procedure

To create a PI Planning, click on "Add PI Planning" on the homepage.

:::::WorkflowBlock
::::WorkflowBlockItem
## General Data

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/iUoq9RPzAEcrwaABPkYUz_pi-planning-1.jpg)

On the left side of the screen, enter a name for your PI Planning, choose the program or product name by clicking on the down arrow icon, and do the same to select the Sprint size.

:::hint{type="info"}
✏️ ***Note:*** This field will only be available after you select a date, a step we will show next.
:::

On the right side of the screen, choose a date by clicking on the calendar icon, and choose the number of iterations by clicking on the down arrow icon, then click "Next."
::::

:::WorkflowBlockItem
## Add Arts

On the next screen, select an Art by clicking on the down arrow icon and click "Next."

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/51Po5WEw4FZumjvOrbHrs_pi-planning-2.png)
:::

:::WorkflowBlockItem
## Iterations

On the next screen, enter a name for each of your iterations. For example, we are naming the teams that will interact in this project. Finally, click "Create." Your PI will appear on the homepage.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/mKnN7pO1JWwATPT82wlnq_pi-planning-3.png)
:::
:::::

# Glossary

### Program

In SAFe, a program is an organizational entity that brings together multiple agile teams to work together on a larger and more complex solution. It consists of a set of Agile Release Trains (ARTs), which are agile development teams responsible for delivering value independently. The program is led by an Agile Program Manager and guided by a Program Vision, which establishes the goals and objectives to be achieved.

### Product

In SAFe, a product is the solution being developed and delivered by agile teams. It can be software, hardware, a service, or any other value delivery to customers. A product may have multiple versions or releases and is managed by a Product Manager or Product Owner.

### Sprint

In the context of agile software development, a "sprint" is a fixed and short period of time during which a development team works to complete a set of tasks and deliver a functional software increment. The sprint is a fundamental unit in Scrum, one of the most popular agile methods.

### Iteration

In the Scaled Agile Framework (SAFe), an "iteration" is a concept similar to "sprint" in Scrum. It represents a fixed and short period during which agile teams work to deliver incremental value throughout the development of a product or solution.

### ART

In the context of the Scaled Agile Framework (SAFe), "ART" stands for Agile Release Train, which can be translated as "Agile Release Train." The ART is an organizational structure that brings together multiple agile teams to work together on the development and delivery of a complex software or system solution.

[title] URL Referencing
[path] Using Agility/

For each path selected after the workspace, the URL will change to reflect the respective navigation path. Therefore, each task will display its workspace, project, and number in the URL, as shown in the image below.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/XOwPHvCMRliWOmenIL5Hk_image.png)

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/XOwPHvCMRliWOmenIL5Hk_image.png)


[title] Workspace
[path] Using Agility/Main Screen/

Workspace represents a workspace of an organization area. Workspace gathers each [Project](docId\:RRmATmr69epZ4rPMvidBN), which in turn gathers each [Task](docId\:UEODcDaJ6j_Y9xngPZvI2).

From the [Main Screen](docId\:U6nqon06QJ5MK8zSBhqW2), select one of the <font color="#2166ae">**Workspaces** </font>or <font color="#2166ae">**PI Planning**</font> to view more detailed options for each Workspace.

# Before starting

- [x] You must have a workspace created to access the screen.

# Procedure

::::WorkflowBlock
:::WorkflowBlockItem
Go to `Menu Home > Workspaces`;
:::

:::WorkflowBlockItem
Click on "**Create Workspace**" to add a workspace of your choice;

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/64Z1CGNFcR7GZUDGJ5ZNE_imagens-agility-3.gif)

In the example above, a Workspace was created to only take care of the **Perfuming&#x20;**&#x6F;f a Pet Shop.
:::
::::

## List Tab&#x20;

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/uNv8IxKBM_VCWH0mq_Tfz_workspace-imagem-1.png)

| Field                                 | Description                                                                                                               |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| 1 - List                              | Displays the list of workspace projects                                                                                   |
| 2 - Gantt                             | Shows Gantt progress bars                                                                                                 |
| 3 - Add Project and Options           | Click here to add a new project, or click on the three dots to view more options.                                         |
| 4 - Order and Filters                 | Select the View Order and filters to be applied to the list of projects.                                                  |
| 5 - Workspace Members                 | Icons showing members involved in all workspace projects.                                                                 |
| 6 - Project List                      | List showing all projects in the current workspace.                                                                       |
| 7 - Project Name and Progress         | Project name and task completion progress bar. Click and drag the dots icon next to the project name to change the order. |
| 8 - Metrics                           | Visualization of Project Metrics.                                                                                         |
| 9 - List of Project Members           | Icons showing members involved in the project.                                                                            |
| 10 - Project Start and Delivery Dates | Earliest task start dates and last task due date in the project.                                                          |
| 11 - Quick View                       | Click on any project area for a compact view of project tasks.                                                            |

## 2. Gantt tab

The Gantt tab shows a table with various information divided into rows and columns.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/LmPXPlByU5aucEy2xFZnL_workspace-2.png)

| **Columns**                |
| -------------------------- |
| Project Name               |
| Members list               |
| Creation date              |
| Delivery date              |
| Progress                   |
| Project duration (in days) |
| Calendar                   |

Below each project you can see a list of their respective tasks.

The calendar will display projects in colored bars with their duration, starting from the creation date and ending on the end date.&#x20;

At the end of the page there is a button with the option t&#x6F;**&#x20;Hide Tasks**, which minimizes the table information to show only the calendar bars.

By clicking on the **-&#x20;**&#x20;and **+** icons next to the project title, it is possible to hide or show the tasks of each project individually.

## 3. Add Project and Options

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/hNNYXCIKJ_J8C3wLubrjf_workspace-3.png)

Click the **Add Project** button in the upper right corner to view the Create Pop-up, where you can enter a name for the new project and add members by typing in their usernames. You can also enter the start date and due date of the project. To finalize the creation, click on **Save**, or on **Cancel&#x20;**&#x20;to go back to the previous screen.

Click on the icon with three dots to view more options:&#x20;

| **Option**            | **Description**                                                    |
| --------------------- | ------------------------------------------------------------------ |
| **Reload Projects**   | Refreshes the page;                                                |
| **Edit Workspace**    | Allows changing the name and members of the selected Workspace;    |
| **Archive Workspace** | Allows archiving the selected Workspace, after user confirmation;  |

## 5. Order and Filters

The box below the title allows selecting the order in which the list of Workspaces appears, with the most recent or the oldest ones appearing at the top. Next to the box, it's possible to filter the selected workspaces by project users;

## 6. Project List

Below the search box, all projects from the current Workspace will be displayed.&#x20;

### 7. Title and Progress

On the left side of the project, the project Name will be displayed, and below it, the completion progress bar for the project. To open the selected project, click on the Name.

The progress bar is defined by:

- The sum of the total estimates of all completed tasks;&#x20;
- The sum of the total estimates of all tasks;&#x20;
- The Progress is the percentage calculated with the total estimates of completed tasks over the total estimates of all tasks;

On the left side of the Name, an icon will be displayed, allowing to change the view order of the projects on the list by clicking and dragging with the mouse.

### 8. Metrics

The colored rectangles show the project Metrics:

- **On Time**: shows the total tasks, of the project, with the "Delivery Date" greater than 24h from the current date/time;&#x20;
- **Due Soon:** shows the total tasks, of the project, with the "Delivery Date" that will be due within 24h from the current date/time;&#x20;
- **Overdue**: shows the total tasks, of the project, with the "Delivery Date" earlier than the current date/time;&#x20;
- **Total**: sum of all tasks of the project;

### 9. Members

The colored circles show the members involved in the project. The letter inside each circle is the initial of the member's username. If there are more than 4 members in the project, only the first 3 members and a circle with ellipsis will be shown.

### 10. Dates

The calendar icons on the right side of the project display the creation date of the first task of the project and the delivery date of the last task.

### 11. Quick View

By clicking anywhere on the project, a box with the tasks of the selected project will be shown for quick view.

# Glossary

1. **Project** – "In the context of the Scaled Agile Framework (SAFe), a project is a temporary initiative or effort with the objective of creating a unique product, service, or result. However, in SAFe, the term 'project' is replaced by the concept of 'Program Increment' (PI), which is a fixed period of time during which work is planned, executed, and delivered by agile teams."
2. **Gantt** – "The Gantt chart is a project management tool that shows the planned tasks and schedule of a project in the form of a horizontal bar chart. It provides a visual overview of project activities, their durations, and the dependencies between them."


[title] BurnDown & BurnUp Charts
[path] Using Agility/

BurnDown and BurnUp charts are Scrum tools that represent project progress. These charts help measure the team's average delivery velocity and identify factors that may impact productivity, such as poorly planned tasks, team member absences, and other issues.

## Procedure

::::WorkflowBlock
:::WorkflowBlockItem
Access the Agility platform and navigate to `Side Menu > Home > Workspace > Project`, then click the **arrow** in the right corner to expand the **Metrics** tab.
:::

:::WorkflowBlockItem
In the bottom right corner, select either the **BurnUp** or **BurnDown** buttons.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/0WmoiiZyM9ixcPAwGe72g_image.png "BurnUp")

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/M59dOJAUFEk3S0XZrW5TR_image.png "BurnDown")
:::
::::


[title]  (cloned with children)
[path] /


[title] Usando o Agility
[path] /


[title] Program and Product
[path] Using Agility/

On the Product/Program Screen, you can see a list with all the added products and programs

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/8yjup7nN52m2ZHo2trNDk_produtoprograma-1.png)

| **Field**                        |
| -------------------------------- |
| 1. Search and Filters - Programs |
| 2. Search and Filters - Products |
| 3. Add Product or Program        |
| 4. List of Programs              |
| 5. List of Products              |
| 6. Actions                       |
| 7. Pages                         |

## Programs Column

| **Field**  | **Description**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Search** | Allows you to search for Programs by name.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| **Filter** | Allows you to filter Active and/or Inactive Programs and sort them by recently updated or alphabetical order.                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| **Table**  | Table with: Program IDs; Program Names; Whether the Program is Active or Inactive; and the following Actions:<br />* **Show artifacts** – Will open the artifacts page of the selected Program [Agile Management - Artifacts](https://docs.citsmart.com/agility/artefatos);
* **Edit** – Displays the same registration screen with the 3 steps, allowing you to edit all data;&#xD;
* **Activate or Deactivate** – If the Program is active, the option to deactivate will be presented. If the Program is inactive, the option to activate will be presented; |

# Add a Product or Program

## Before You Begin

- [x] The tool must present a list or view of all practices&#x20;

## Procedure

- Access the functionality through the navigation in the main menu `Agile Work Management > Programs and Products`;
- In the upper right corner, select the "**Add Program or Product**" button, which will display a registration screen (**image**).

### Step 1 - General Data:

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/YKoCzwQVvVl9RT634pLH1_produtoprograma-2.png)

| **Field**       | **Description**                                                                                                                                                                                                                                                                                                         |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Name**        | Enter the name for the new Program or Product:<br />* **Program:** would be a set of ongoing projects, with a beginning, middle, and end; and&#x20;
* **Product:** would be a physical or virtual asset that solves a user's pain, a company's pain, or a specific segment's pain, which is constantly improving.&#x20; |
| **Type**        | Select whether the type will be Program or Product;                                                                                                                                                                                                                                                                     |
| **Status**      | Select the status (Active or Inactive);                                                                                                                                                                                                                                                                                 |
| **Description** | Enter the description.                                                                                                                                                                                                                                                                                                  |

To proceed to step 2, click "**Next**";

### Step 2 - Objectives:

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/9tO_Vlo7hNkvc27L09uP6_produtoprograma-3.png)

| **Field**          | **Description**                                                                                                                                                                                                                 |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Objective**      | Enter the Objective;                                                                                                                                                                                                            |
| **Business Value** | Select the Business Value;                                                                                                                                                                                                      |
| **Current Value**  | Select the Current Value (Business Value and Current Value are used to permeate the organization with how important that program or product is and thus make the budget feasible. They are chosen in a **range from 0 to 10**); |
| **Add Objective**  | One or more objectives can be added.                                                                                                                                                                                            |

To proceed to step 3, click "**Next**";&#x9;

### Step 3 - Risks:

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/ktOMv6OXKJQmAwj2hBazj_produtoprograma-4.png)

| **Field**       | **Description**                 |
| --------------- | ------------------------------- |
| **Description** | Enter the risk description;     |
| **Color**       | Select a color for the risk;    |
| **Add Risk**    | One or more risks can be added. |

Click "**Previous**" to return to the previous action or "**Save**" to continue.

[space] AIOPS (/aiops)

[title] Traceroute
[path] Infraestrutura/

As ferramentas de rede no Atmos contam com testes de traceroute para determinar o rastreio de pacotes da rede e sua conectividade.

Para acesso aos traceroutes, clique no botão **Rede** e em seguida, no menu superior, no botão **Traceroutes**.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/rf8qfW_SmilzLiqvWykHI_image.png" size="20" width="146" height="56" caption position="center" signedSrc="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/rf8qfW_SmilzLiqvWykHI_image.png"}

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/1iYr-WCg9PLoO7UzanO65_image.png" size="38" width="330" height="96" caption position="center" signedSrc="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/1iYr-WCg9PLoO7UzanO65_image.png"}

A tela com a lista de traceroutes cadastrados será exibida.

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/lXfUq964GxJAnJ5eT5K2R_image.png)

## Criando uma rotina de testes do Traceroute

Ao clicar no botão **Novo traceroute**, no canto superior direito, a seguinte janela será exibida:

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/5f4Tr0GukJiqfIrh15-ZG_image.png" size="80" width="805" height="630" caption="Aba Geral" position="center" signedSrc="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/5f4Tr0GukJiqfIrh15-ZG_image.png"}

- **Nome**: Nome do grupo de testes;
- **Intervalo**: Intervalo de execução dos testes;
- **Saltos**: Número de saltos máximos a serem executados pelo traceroute;
- **Timeout**: Tempo limite para a execução do traceroute (para cada teste individual)
- **Tentativas**: Número de tentativas de execução;
- **Tipo**: Qual tipo de endereços IP utilizar (Quando não selecionado apenas o IP primário é utilizado por padrão);
  - **Somente IPs Públicos:** Selecione o principal *IP Público* do Item de Configuração (quando existir)
  - **Somente IPs Privados:** Selecione o principal *IP Privado* do Item de Configuração (quando existir)
- **Interface***&#x20;(Opcional)*: Interface que será utiulizada para execução dos testes (é necessário obter o nome da interface desejada na instância *atom-worker&#x20;*&#x64;o AIops)
- **Descrição** (Opcional): Descritivo do grupo de teste

### Escopo

A aba escopo define a origem dos IPS de destino deste grupo de coleta do traceroute (IP primário presente nos itens de configuração).&#x20;

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/wGjv1IwLu3kIl-TYFE7OE_image.png" size="80" width="808" height="526" caption position="center" signedSrc="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/wGjv1IwLu3kIl-TYFE7OE_image.png"}

:::hint{type="info"}
Para cada grupo de teste são escolhidos os *IPs* por Item de Configuração de acordo com o tipo definido da *Aba Geral*.&#x20;
:::

# Executando um teste do Traceroute

Este teste é executado em tempo real e não gera métricas, apenas retorna o resultado do traceroute para visualização.
Ao clicar no botão **Testar configuração de Traceroute&#x20;**&#x20;a janela a seguir será exibida:

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/f2REpTmzu7XKVa2-3j2Ev_image.png" size="80" width="759" height="406" caption position="center" signedSrc="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/f2REpTmzu7XKVa2-3j2Ev_image.png"}

- **Destino**: Endereço de destino a ser executado (IP ou Domínio);
- **Interface***&#x20;(Opcional)*: Interface que será utiulizada para execução dos testes (é necessário obter o nome da interface desejada na instância *atom-worker&#x20;*&#x64;o aiops)
- **Saltos**: Número máximo de saltos na execução;
- **Timeout**: Tempo limite na execução do teste;
- **Tentativas**: Número de tentativas na execução.

### Resultado do teste

Na execução bem sucedida de um teste de traceroute a aba de resultados será exibida com o seguinte valor de exemplo:

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/keKcFE5l5qcrxzJzvh286_image.png" size="80" width="759" height="478" caption="Teste realizado com o dominio google.com.br" position="center" signedSrc="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/keKcFE5l5qcrxzJzvh286_image.png"}

O resultado é um objeto do tipo JSON que contém as seguintes informações:

```json
{
    "address": "google.com.br"                  // destino do teste
    "elapsed_time_ms": 435,                     // tempo total (todos os saltos) em milliseconds
    "hops": [
        {
            "hop": 1,                   
            "success": true,            
            "address": "177.20.14.3",   
            "host": "177.20.14.3",     
            "rtt": 0 
        },
        // {...}
        {
            "hop": 13,                          // número do salto 
            "success": true,                    // se o probe retornou sucesso nesse salto
            "address": "172.217.162.13",        // ip do salto
            "host": "gru14s19-in-f3.1e100.net", // dominio ou ip resolvido
            "rtt": 28                           // tempo em ms do retorno do salto 
        }
    ],
    "hops_count": 13,                           // quantidade de saltos 
    "host": "google.com.br",                    // dominio do teste
    "ip": "172.217.162.131",                    // ip resolvido do dominio do teste
    "probe_version": "traceroute/binary:v1",    // versão do traceroute utilizado
    "reached": true                             // se o destino foi alcançado com sucesso
}
```

## Gráfico de execução



![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/SKovkCJ0ORTwBzOtj9ueg_image.png)


[title] Monitoramento Kubernetes com Telegraf Operator
[path] Métrica/Coletas customizadas/

Configurando o monitoramento de um cluster Kubernetes usando o Telegraf Operator:

## Pré-requisitos

- Cluster Kubernetes em execução

### 1. Instalando o telegraf-operator no seu cluster Kubernetes e configurando o ambiente:

A versão atualizada do telegraf-operator pode ser instalada usando o Repositório Helm do InfluxData. Verifique o :Link[link]{href="https://github.com/influxdata/telegraf-operator/blob/master/README.md" newTab="true" hasDisabledNofollow="false"} para configuração do helm e do telegraf-operator e o :Link[link]{href="https://github.com/influxdata/telegraf-operator/blob/master/Makefile" newTab="true" hasDisabledNofollow="false"} para configuração do ambiente contido no arquivo Makefile.

Execute:

:::CodeblockTabs
bash

```dockerfile
helm repo add influxdata https://helm.influxdata.com/
helm upgrade --install telegraf-operator influxdata/telegraf-operator
```
:::

### Configuração do ambiente:&#xA;

:::CodeblockTabs
bash

```linux
# garantir que o contexto correto do kubectl esteja definido e sendo 
# usado, caso contrário irá falhar
kubectl config use-context telegraf-operator-nome

# criar namespace
kubectl create namespace <nome>
```
:::

### 2. Configurar as classes Telegraf:

O arquivo **classes.yml** define as classes Telegraf que serão usadas para reportar dados para o InfluxDB e para a saída padrão. Substitua **\<**&#x64;bworker\_i&#x70;**>**(ceritifque-se que seja o. IP da instância **DB Worker**), **\<database>**, **\<hostname>** e **\<cluster>** pelos valores desejados.

Exemplo de um arquivo classes.yml:

:::CodeblockTabs
classes.yml

```yaml
apiVersion: v1
kind: Namespace
metadata:
  name: telegraf-operator
---
apiVersion: v1
kind: Secret
metadata:
  name: telegraf-operator-classes
  namespace: telegraf-operator
stringData:
  #Classes básicas que podem ser usadas para desenvolver o operador do Telegraf; essas classes
  #relatam para o InfluxDB v1 no mesmo cluster, e também para o arquivo stdout por conveniência
  app: |+
    [[outputs.influxdb]]
      urls = ["<dbworker_ip>:8086"]
    [global_tags]
    
      database = "<database>"
      hostname = "<hostname>"
      cluster = "<cluster>"
  default: |+
    [[outputs.influxdb]]
      urls = ["<dbworker_ip>:8086"]
    [global_tags]
      database = "<database>"
      hostname = "<hostname>"
      cluster = "<cluster>"
  basic: |+
    [[outputs.influxdb]]
      urls = ["<dbworker_ip>:8086"]
    [global_tags]
      database = "<database>"
      hostname = "<hostname>"
      cluster = "<cluster>"
```
:::

### 3. Configurar o plugin do Telegraf:

O arquivo **plugin\_nome.yml** define um StatefulSet para um plugin que será monitorado pelo Telegraf. Substitua os valores de **name,** **namespace,** **serviceName, app, inputs.plugin\_nome**,  **urls**, **limits-cpu** e **limits-memory** pelos valores desejados. Verifique os possíveis plugins de input no :Link[link]{href="https://github.com/influxdata/telegraf/tree/master/plugins/inputs" newTab="true" hasDisabledNofollow="false"}.

**Exemplo de um arquivo nginx.yaml:**

:::CodeblockTabs
yml

```yaml
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: nginx-deamon
  namespace: test
spec:
  serviceName: "nginx-telegraf"
  replicas: 1
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
      annotations:
        telegraf.influxdata.com/inputs: |+
          [[inputs.nginx]]
            urls = ["<nginx-url>"]
        telegraf.influxdata.com/class: app
        telegraf.influxdata.com/env-fieldref-NAMESPACE: metadata.namespace
        telegraf.influxdata.com/limits-cpu: '750m'
        # limite de memória inválido, que será ignorado
        telegraf.influxdata.com/limits-memory: '800x'
    spec:
      containers:
      - name: nginx
        image: nginx:alpine
```
:::

### 4. Aplicar as configurações:

Aplique as configurações usando o comando **kubectl apply -f \<arquivo.yml>** para cada um dos arquivos YAML.

**Deploy dos Pods e Contexto Kubernetes:**

Certifique-se de que o contexto correto do kubectl esteja definido e sendo utilizado, caso contrário, ira falhar:

:::CodeblockTabs
bash

```dockerfile
kubectl config use-context telegraf-operator-nome
kubectl apply -f classes.yml
kubectl apply -f dev.yml
kubectl apply -f examples/plugin_nome.yml
kubectl describe pod --namespace=<namespace> <pod_name> 
```
:::

Acesso aos logs do deploy:

:::CodeblockTabs
bash

```dockerfile
kubectl logs -f -n <namespace> <pod_name> -c telegraf
```
:::

**Links:**
Telegraf Operator:

- [https://github.com/influxdata/telegraf-operator/blob/master/README.md](https://github.com/influxdata/telegraf-operator/blob/master/README.md)

Plugins:

- [https://github.com/influxdata/telegraf/tree/master/plugins/inputs](https://github.com/influxdata/telegraf/tree/master/plugins/inputs)


[title] Chaves de acesso
[path] Infraestrutura/

Acesse as **Configurações** e encontre o campo **Autenticação** para visualizar a opção chaves de acesso.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/qpr-FybYVVmqbebYaBDz_/VC70N8ii4c4a_3tB7l4TF_image.png" signedSrc size="42" width="186" height="92" position="center" caption}

- **Visualize todas as chaves existentes:&#x20;**&#x4D;antenha o controle total sobre as suas chaves de acesso, com uma lista completa e organizada.
- **Crie novas chaves:&#x20;**&#x4E;o canto superior direito tem o botão para criar novas chaves de acesso.

**Campos da Tela de nova chave de acesso&#x20;**



![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/xpIgjsQHem7KfKkQsQWrP_image.png)

A tela de criação de chave de acesso contém os seguintes campos:

- **Nome: &#x20;**&#x4F; nome do usuário ou função para o qual a chave de acesso está sendo criada. Este campo é obrigatório.
- **Perfil de acesso:&#x20;**&#x4F; perfil de acesso do usuário. O perfil de acesso define os recursos do sistema aos quais o usuário tem acesso. Este campo é obrigatório.
- **Data de expiração:&#x20;**&#x41; data em que a chave de acesso expira. Este campo é opcional. Se a data de expiração não for informada, a chave de acesso nunca expirará.

**Criando uma Chave de Acesso**

Para criar uma chave de acesso, siga estas etapas:

1. Preencha os campos **Nome**, **Perfil de acesso** e **Data de expiração** (opcional).
2. Clique no botão **Salvar.**
3. Será gerado uma chave de acesso público.

**Gerenciando Chave de Acesso**

A tela de visualização das chaves de acesso também permite deletar as chaves de acesso existentes. Para deletar uma chave de acesso, siga estas etapas:

1. Visualize a chave de acesso que deseja deletar.
2. Clique na lixeira, posicionada do lado direito, e confirme.

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/AOX8K9RoC1Z6fwGpfes2y_image.png)

**Observações**

- As chaves de acesso devem ser armazenadas em local seguro.
- As chaves de acesso não devem ser compartilhadas com outras pessoas.
- &#x20;A chave de acesso gerada não poderá ser recuperada. Guarde-a em local seguro.


[title] Infraestrutura
[path] AIOps/Usuários/

## Funcionalidades

|                                                                                                                                | **Administrador** | **Analista** | **Gestor**      | **Supervisor**  | **Operador**    |
| ------------------------------------------------------------------------------------------------------------------------------ | ----------------- | ------------ | --------------- | --------------- | --------------- |
| ****:Link[**Infraestrutura**]{href="https://docs.citsmart.com/aiops/infraestrutura" newTab="true"}****                         | Acesso total      | Acesso total | Somente leitura | Somente leitura | Somente leitura |
| ****:Link[**Hosts**]{href="https://docs.citsmart.com/aiops/hosts" newTab="true"}****                                           | Acesso total      | Acesso total | Somente leitura | Somente leitura | Somente leitura |
| ****:Link[**Serviços de TI**]{href="https://docs.simonops.com/servicos-de-ti" newTab="true"}****                               | Acesso total      | Acesso total | Acesso total    | Somente leitura | Somente leitura |
| ****:Link[**Topologia**]{href="https://docs.citsmart.com/aiops/topologia" newTab="true"}****                                   | Acesso total      | Acesso total | Acesso total    | Somente leitura | Somente leitura |
| ****:Link[**Dashboards**]{href="https://docs.citsmart.com/aiops/paineis-dashboards" newTab="true"}****                         | Acesso total      | Acesso total | Acesso total    | Acesso total    | Acesso total    |
| ****:Link[**Pipes**]{href="https://docs.citsmart.com/aiops/pipes-e-automacao" newTab="true"}****                               | Acesso total      | Acesso total | Somente leitura | Somente leitura | Somente leitura |
| ****:Link[**Alerting**]{href="https://docs.citsmart.com/aiops/alertas-triggers" newTab="true"}****                             | Acesso total      | Acesso total | Somente leitura | Somente leitura | Somente leitura |
| ****:Link[**Testes Web**]{href="https://docs.citsmart.com/aiops/testes-web" newTab="true"}****                                 | Acesso total      | Acesso total | Somente leitura | Somente leitura | Sem Acesso      |
| :Link[**Planos de manutenção**]{href="https://docs.citsmart.com/aiops/manuntencoes" newTab="true" hasDisabledNofollow="false"} | Acesso total      | Acesso total | Acesso total    | Somente leitura | Somente leitura |
| ****:Link[**Agendamentos**]{href="https://docs.citsmart.com/aiops/agendamentos" newTab="true"}****                             | Acesso total      | Acesso total | Somente leitura | Somente leitura | Somente leitura |
| **Tempo de Serviço**                                                                                                           | Acesso total      | Acesso total | Somente leitura | Sem Acesso      | Sem Acesso      |



## Configurações

### Infraestrutura

|                             | **Administrador** | **Analista** | **Gestor**      | **Supervisor**  | **Operador**    |
| --------------------------- | ----------------- | ------------ | --------------- | --------------- | --------------- |
| **Sugestão de recursos**    | Acesso total      | Sem Acesso   | Sem Acesso      | Sem Acesso      | Sem Acesso      |
| **Anotações**               | Acesso total      | Acesso total | Somente leitura | Somente leitura | Somente leitura |
| **Template de métricas**    | Acesso total      | Acesso total | Somente leitura | Somente leitura | Sem Acesso      |
| **Métricas**                | Acesso total      | Acesso total | Somente leitura | Somente leitura | Sem Acesso      |
| **Grupos (Metric Plugins)** | Acesso total      | Acesso total | Acesso total    | Somente leitura | Somente leitura |

### SNMP

|                | **Administrador** | **Analista** | **Gestor**      | **Supervisor** | **Operador** |
| -------------- | ----------------- | ------------ | --------------- | -------------- | ------------ |
| **Descoberta** | Acesso total      | Acesso total | Somente leitura | Sem Acesso     | Sem Acesso   |
| **Coleta**     | Acesso total      | Acesso total | Somente leitura | Sem Acesso     | Sem Acesso   |
| **Perfis**     | Acesso total      | Acesso total | Somente leitura | Sem Acesso     | Sem Acesso   |
| **Grupos**     | Acesso total      | Acesso total | Somente leitura | Sem Acesso     | Sem Acesso   |

### Pipes

|              | **Administrador** | **Analista** | **Gestor**      | **Supervisor**  | **Operador**    |
| ------------ | ----------------- | ------------ | --------------- | --------------- | --------------- |
| **Scripts**  | Acesso total      | Acesso total | Somente leitura | Somente leitura | Sem Acesso      |
| **Serviços** | Acesso total      | Acesso total | Somente leitura | Somente leitura | Somente leitura |


[title] Descoberta Automática
[path] Infraestrutura/Visão Geral da Descoberta e Relacionamento/

:::hint{type="info"}
A descoberta automática de hosts em uma rede e a coleta de métricas também é possível através do protocolo SNMP. Para configurar o acesso aos hosts que possibilitam essa coleta nos protocolos disponíveis (v2c e v3) siga os passos a seguir:
:::



## **1**. Ao acessar o Atmos, navegue até o sétimo item da coluna à esqueda (Rede)

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/qpr-FybYVVmqbebYaBDz_/lIIFM2boq21C39R7JdT6-_image.png" signedSrc size="10" width="59" height="420" position="center" caption}

## **2**. Clique no quarto ícone da barra superior (Descobertas automáticas)

![](https://archbee-image-uploads.s3.amazonaws.com/qpr-FybYVVmqbebYaBDz_/bpEAcmn0u_lrp3mvcabNf_image.png)

## **3**. No canto superior direito clique em "+ Nova descoberta automática"

![](https://archbee-image-uploads.s3.amazonaws.com/qpr-FybYVVmqbebYaBDz_/iEjpvE4MMtTfq_Hf6r6zE_image.png)

## 4. Preencha o formulário conforme a definição dos dados

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/2tIkPZkrKWJ2y7JaERjR8_captura-de-tela-2023-10-16-as-22041-pm.png)

- **Nome**: Nome da descoberta a ser cadastrada;
- **Tipo**: Tipo do descoberta, tem a opção de padrão e detalhado. Caso seja escolhido a opção detalhado é liberado a opção profundidade para preencher;
- **Profundidade:** define quais devices devem ser listados de acordo com as camadas de rede.
- **Coletor**: Define qual instalação da Atom Worker será utilizada para realizar a coleta.
- **Timeout**:  É o período de tempo máximo que o coletor aguardará por uma resposta SNMP de um dispositivo antes de considerar a solicitação como falha;
- **Tentativas**: Indica quantas vezes o coletor tentará obter uma resposta do dispositivo SNMP antes de considerar a solicitação como falha. Cada tentativa ocorre após o timeout definido;
- **Agendamento**: Refere-se a quando as solicitações SNMP serão enviadas para os dispositivos de rede. Você pode configurar um agendamento para coletar informações em intervalos regulares ou em horários específicos;
- **Cadastro Automático de Hosts**: Permite que o coletor descubra e registre automaticamente os dispositivos que estão disponíveis na rede. Isso facilita o processo de gerenciamento, pois você não precisa adicionar manualmente cada dispositivo;
- **Descrição**: Fornecer informações adicionais, como anotações, notas ou detalhes adicionais que podem ser úteis para o administrador de rede.

:::hint{type="info"}
**Nota**: O cadastro de descoberta pode ser ativado ou desativado a qualquer momento, de acordo com a necessidade operacional.
:::

### 4.1 Escolha o tipo e se for detalhado, preecha a profundidade

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/yg3UCMC-UxpBnOk0A4_W9_captura-de-tela-2023-10-17-as-101437-am.png)



## &#x35;**.&#x20;**&#x45;scolha a frequência de agendamentos

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/9Hr9jGSjbbMmJV97P8gc4_captura-de-tela-2023-10-17-as-81359-am.png)

**Nota**: No **Agendamento&#x20;**&#x70;ode-se selecionar a frequência que as solicitações SNMP serão enviadas para os dispositivos de rede. As escolhas estão para enviar *Apenas uma vez&#x20;*&#x6F;u em intervalos regulares como: *A cada hora, Diariamente ou Semanalmete.*&#x20;



## 6. Adicione as credenciais necessárias para a coleta

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/3-Loc7F-poRnsuZ79Xj7T_captura-de-tela-2023-10-16-as-22213-pm.png)

### 6.1. Preencha os campos e salve a credencial:

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/841-hak9-S-yeINzxjUJg_captura-de-tela-2023-10-16-as-22427-pm.png)

- **Nome:&#x20;**&#x4E;ome da credencial;
- **Porta:&#x20;**&#x50;orta que será feita a conexão com o dispositivo SNMP (padrão 161);
- **Chave SNMP:&#x20;**&#x53;egredo criado para autenticar as solicitações SNMP. Para criar segredos: [https://docs.citsmart.com/aiops/segredo](https://docs.citsmart.com/aiops/segredo)
- **Versão:&#x20;**&#x56;ersão do protocolo SNMP utilizado.

### SNMP v2c

Em chave o campo deve conter o valor *chave&#x20;*

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/ig6dhYNW0W1C1akoRjiGt_image.png" signedSrc="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/ig6dhYNW0W1C1akoRjiGt_image.png" size="50" width="994" height="760" position="flex-start" caption}

### SNMP v3

Conforme o nível de segurança, o v3 exige uma ou duas chaves para efetuar a autenticação. Esse nível de segurança é definido através do cadastro de uma coleta ou descoberta onde:

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/T2tSWtczM0wRfrUD0aVYL_captura-de-tela-2023-10-17-as-100050-am.png" signedSrc="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/T2tSWtczM0wRfrUD0aVYL_captura-de-tela-2023-10-17-as-100050-am.png" size="50" width="986" height="914" position="flex-start" caption}

- Quando o nível de segurança for **noAuthNoPriv** a autenticação não é feita;
- Quando o nível de segurança for **AuthNoPriv** a autenticação é feita apenas através da chave com valor *Authentication passphrase;*
- Quando o nível de segurança for **AuthPriv**, a autenticação é feita através de duas chaves sendo as *Authentication passphrase* e *Privacy passphrase***.**



### 6.2. Selecione as credenciais desejadas

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/oOoqPD3kt6xMOvG0Z1ax8_captura-de-tela-2023-10-16-as-22713-pm.png "Você pode selecionar múltiplas Credenciais")



## 7. Na aba IPs, adicione um IP e/ou uma faixa de IPs para a descoberta:

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/07ujO8aIBYCxr2tRlh5Yk_captura-de-tela-2023-10-16-as-22758-pm.png)



### 7.1. É possível adicionar vários IPs e/ou faixas separadas pelos idenficadores informados

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/rncsGwCBKFp8IUH6VB6Xf_captura-de-tela-2023-10-18-as-110503-am.png)



## 8. Salve a Descoberta:

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/nkMRIerDnbUV4lONxuxX5_captura-de-tela-2023-10-16-as-60136-pm.png)



## &#x39;**. Resultados das faixas de IPs que foram descobertas**

### 9.1. Listagem de descobertas

![](https://archbee-image-uploads.s3.amazonaws.com/qpr-FybYVVmqbebYaBDz_/CjVI5huCPxpGoAwhZDq_N_image.png)

Você pode acompanhar o progresso geral das descobertas ativas na tela de listagem.

### 9.2. Detalhamento da descoberta

![](https://archbee-image-uploads.s3.amazonaws.com/qpr-FybYVVmqbebYaBDz_/ZP41CRfPwyBuue2encV0s_image.png)

Você pode acompanhar o progresso individual para cada item da coleta ao detalhar a descoberta criada. Você também poderá verificar os indicadores com a quantidade de IPs processados, finalizados com sucesso e finalizados com erro.

A descoberta é capaz de identificar dispositivos tais como (Linux, AIX, Windows , máquinas virtuais, storage, dispositivos de rede, servidores de aplicação dentre outros).

## Cloud Discovery

Permite integração com APIs dos principais provedores de nuvem (AWS, Azure, Google Cloud, Oracle) para identificar e modelar recursos conforme o modelo de serviço correspondente (ex: instâncias de VM, serviços gerenciados, etc).

Durante o processo de descoberta, o discovery associa automaticamente tags (rótulos) atribuídos aos recursos na nuvem, permitindo a categorização e identificação desses recursos conforme o modelo de serviço e outros critérios definidos pelo usuário ou provedor.

O modelo de dados do discovery é padronizado para todos os provedores, facilitando a distinção entre diferentes tipos de serviços identificando o modelo de serviço correspondente seja IaaS, PaaS, SaaS, dentre outros.

## AIOPS Discovery

O AIOps Discovery permite descobertas em diversos cenários, seja on-premises, em nuvem ou híbrido. Para descobertas em infraestrutura. A descoberta poderá ser realizada com ou sem o uso de agentes.

[title] Pipes e Automação
[path] Infraestrutura/

O AIOPS possui a capacidade de criação de fluxos para automações simples e complexas, seja para autorecuperação ou execuções rotineiras, é possível utilizar a funcionalidade de "Pipes" para maximizar o potencial de sua equipe otimizando o tempo com tarefas recorrentes, potencializando as automações e extraindo o máximo de módulos que permitem infinitas combinações, suportados por IA.

## Acesso&#x20;

Para acessar a aplicação Atmos é necessário clicar no botão "aplicações" localizado no canto inferior esquerdo, do menu principal no AIOPS.

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/_dl2iGnL-Fm4SOb1vBfhr_image.png" size="34" caption position="center" signedSrc="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/_dl2iGnL-Fm4SOb1vBfhr_image.png?AWSAccessKeyId=AKIAYQNQCIXNIQWBC56C&Expires=1697908162&Signature=6A9Q6aLh9ZWTIr5xiAGfks91RU8%3D"}

Após acessar o Atmos é necessário acessar a funcionalidade de Pipes através do menu principal (lateral esquerda):

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/qpr-FybYVVmqbebYaBDz_/ECvkRQIxsS07zU94nIsH1_image.png" signedSrc size="10" width="61" height="416" position="center" caption}

Então uma nova tela será exibida com a listagem dos fluxos criados:&#x20;

![](https://archbee-image-uploads.s3.amazonaws.com/qpr-FybYVVmqbebYaBDz_/H7pw6Rq-JXNLPKUK46NI-_image.png)

## Criação de fluxos

Para criar novos fluxos é necessário clicar no botão:&#x20;

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/qpr-FybYVVmqbebYaBDz_/_Xm7vkEcFmj5XBTrBIpV__image.png" signedSrc size="78" width="402" height="50" position="center" caption}

Então uma nova tela para a criação de fluxos se apresentará:

![](https://archbee-image-uploads.s3.amazonaws.com/qpr-FybYVVmqbebYaBDz_/CnzC81IINyo2aUZIBABWa_image.png)

&#x20;Nessa tela teremos do lado esquerdo:

- Aba de serviços
  - Nessa aba teremos vários bloquinhos representados ferramentas com as quais o atmos pode se comunicar para executar uma automação
- Aba de outlines
  - Nessa aba é possível definir variáveis globais que podem ser utilizadas nos pipes

### Selecionando serviços

Para utilizar os serviços disponíveis basta clicar em um item existente na aba de serviços e arrastar para a área cinza, dando início assim a criação de um fluxo:

![](https://archbee-image-uploads.s3.amazonaws.com/qpr-FybYVVmqbebYaBDz_/b2CMtxJ0XtPmW4Gnd7uU5_image.png)

Em cada componente termos a possibilidade de:

- Definir se é o ponto de início através do ícone da bandeira
- Executar a ação de remover atráves do botão de três pontos
- Selecionar um comando para a execução

### Configurando

Após realizar esses passos é possível executar um comando para execução, onde caso haja saídas possíveis para esse comando um novo botão será exibido:&#x20;

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/qpr-FybYVVmqbebYaBDz_/4LEs8DMvDIYG_uUuJUpMA_image.png" signedSrc size="86" width="427" height="411" position="center" caption}

Para cada script é possível exigir as configurações necessárias através do ícone de engrenagem:&#x20;

![](https://archbee-image-uploads.s3.amazonaws.com/qpr-FybYVVmqbebYaBDz_/JJXjdrLFw2eK11Iw5LttT_image.png)

### Construindo fluxo

Além disso é possível também dar continuidade na execução do botão que possui o ícone de raio:

![](https://archbee-image-uploads.s3.amazonaws.com/qpr-FybYVVmqbebYaBDz_/xxMqzFaegspjMjCV79wr6_image.png)

Nessa ação é possível arrastar e soltar as opções existentes no modal chamado de "flows" e criar fluxos que poderão ser conectados a outro componente de serviço simplesmente clicando e arrastando o botão de raio existente em um flow, como por exemplo:&#x20;

![](https://archbee-image-uploads.s3.amazonaws.com/qpr-FybYVVmqbebYaBDz_/KbaeXpW0w2d2z9l9hcplj_image.png)

Caso existe outro serviço, então a conexão poderá ser estabelecida:&#x20;

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/JgCHrnH21n0u_p4W_pEW4_image.png" size="82" caption position="center" signedSrc="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/JgCHrnH21n0u_p4W_pEW4_image.png?AWSAccessKeyId=AKIAYQNQCIXNIQWBC56C&Expires=1697908162&Signature=RWWjhGh%2Bh%2B68m3SC3u3EQuJbEVA%3D"}

É possível acionar pipes através de agendamentos:&#x20;

&#x20;(:Link[Agendamento]{href="https://docs.citsmart.com/aiops/agendamentos" newTab="true" hasDisabledNofollow="false"})

Ou através de associação a alertas na tela de incidentes:&#x20;

&#x20;(:Link[Atuação em Icidentes]{href="https://docs.citsmart.com/aiops/atuacao-em-incidentes" newTab="true" hasDisabledNofollow="false"})

## Integração e disponibilização API

Para realizar a disponibilização de um Pipe para integração e acesso por ferramentas externas, como scripts, RPAs, ITSMs e etc. você deve acessar a listagem e pipes e clicar no botão:

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/pbWwas18xYLiCg9SPMNvg_screen-shot-2021-06-17-at-103757.png" size="32" width="165" height="233" caption position="center" signedSrc="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/pbWwas18xYLiCg9SPMNvg_screen-shot-2021-06-17-at-103757.png"}

Após permitir que esse pipe se torne público você conseguirá acessar às informações para as integrações que desejar realizar:

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/IWqpmBeqNnkksXOzmqSjA_screen-shot-2021-06-17-at-104149.png" size="70" width="663" height="834" caption position="center" signedSrc="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/IWqpmBeqNnkksXOzmqSjA_screen-shot-2021-06-17-at-104149.png"}

## Construção de módulos

O AIOPS permite a criação de módulos customizados utilizando linguagem de alto nível para scripts.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/-Mp-8mR8qKew4TirHNOfU_simon-scripts.PNG" size="74" width="1253" height="892" caption position="center" signedSrc="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/-Mp-8mR8qKew4TirHNOfU_simon-scripts.PNG"}

Possibilitando a instalação automática de Agent nos mais diversos ambiente de forma simplificada. Incluindo ambientes complexos e conteinerizados tais como: Rancher, GliBC e Musl-libc, entre outros.

[title] Coleta de dados
[path] AIOps/Inventário/

A solução Xventory é capaz de coletar informações detalhadas sobre o hardware e software de estações de trabalho e servidores, oferecendo uma visão completa do inventário de ativos de TI de uma organização. Abaixo, estão listados os recursos relacionados ao inventário de informações de hardware e software:

### Coleta de Informações de Hardware

- O Xventory é capaz de coletar informações sobre processadores, memória, placa-mãe, interfaces de rede, protocolos de rede, BIOS, portas de entrada/saída, dispositivos, discos (físicos e lógicos), sistemas de arquivos, recursos do sistema operacional, configurações de região, controladoras (IDE, SCSI, USB) e outros componentes de hardware.
- A coleta de informações de hardware é feita de forma automatizada, permitindo que as organizações obtenham uma visão precisa e atualizada do inventário de ativos de TI.

### Coleta de Informações de Software

- Além das informações de hardware, o Xventory é capaz de coletar informações detalhadas sobre o software instalado nos dispositivos gerenciados, incluindo sistema operacional, aplicativos, drivers, atualizações e patches.
- As informações de software também são coletadas de forma automatizada, oferecendo uma visão precisa e atualizada do inventário de ativos de TI.

### Coleta de Dados de Inventário a partir de Arquivos

- O Xventory permite que as organizações coletem dados de inventário a partir do uso de arquivos, o que pode ser útil em situações em que a coleta automatizada não é possível.
- Os dados de inventário podem ser inseridos em um arquivo e importados para o Xventory, oferecendo uma visão completa e atualizada do inventário de ativos de TI.

### Coleta de Informações em Registro do Windows

- O Xventory é capaz de acessar e coletar informações em registro do Windows, oferecendo uma visão precisa e atualizada do inventário de ativos de TI.
- As informações coletadas incluem informações de hardware e software, permitindo que as organizações obtenham uma visão completa do inventário de ativos de TI.
- O Xventory é capaz de acessar e coletar informações também de "Programas e Recursos" do Windows.

### Coleta de Informações via comunicação externa

O Xventory também oferece ampliação da capacidade com orquestração e comunicação através de:

- Capacidade de coletar informações detalhadas sobre o hardware e software de estações de trabalho e servidores através de comunicações externas ou integrações.
- Funcionalidades de coleta de informações de hardware e software e do inventário de softwares.
- Possibilidade de capturar informações de forma ativa.
- Integração com outras ferramentas de monitoramento, como Zabbix, Nagios, Datadog, Dynatrace, SolarWinds, Cloudwatch, etc.
- Integração com outras ferramentas de monitoramento por meio da utilização do motor de pipes.
- Enriquecimento das informações de inventário de ativos de TI com dados de monitoramento em tempo real.
- Visão mais completa e precisa do ambiente de TI.
- Automatização de fluxos de trabalho.
- Facilidade de integração das informações coletadas pelo Xventory com outras ferramentas de gestão de TI.
- Solução completa e flexível para o gerenciamento de inventário de ativos de TI.
- Adequação às necessidades de diferentes tipos de organizações e ambientes de TI.

### Visão completa e atualizada&#x20;

Essa funcionalidade permite que as organizações tenham uma visão completa e atualizada dos softwares instalados nos dispositivos gerenciados, incluindo versões e informações adicionais sobre os softwares. A coleta de informações é feita de forma automatizada, o que garante que as informações de software estejam sempre atualizadas e precisas.

Com o inventário de softwares do Xventory, as organizações podem gerenciar melhor as licenças de software, identificar softwares desnecessários ou obsoletos e garantir a conformidade com as políticas de segurança da informação. Além disso, é possível gerar relatórios detalhados sobre o inventário de softwares, permitindo que as organizações tenham uma visão completa e precisa sobre os softwares instalados nos dispositivos gerenciados.

### Ativos de TI

Em resumo, a solução Xventory é capaz de coletar informações detalhadas sobre o hardware e software de estações de trabalho e servidores, oferecendo uma visão completa do inventário de ativos de TI de uma organização. A coleta de informações é feita de forma automatizada, permitindo que as organizações obtenham uma visão precisa e atualizada do inventário de ativos de TI. Além disso, o Xventory permite que as organizações coletem dados de inventário a partir do uso de arquivos e acessem informações em registro do Windows, oferecendo uma visão completa e atualizada do inventário de ativos de TI.

### Sistemas operacionais

Além disso, é importante destacar que as informações de hardware e software também podem ser coletadas em diferentes sistemas operacionais, como Linux e Windows. O Xventory é capaz de coletar informações de dispositivos gerenciados em diferentes plataformas, oferecendo uma visão abrangente e precisa do inventário de ativos de TI. Dessa forma, as organizações podem ter uma visão completa e atualizada do inventário de ativos de TI em diferentes sistemas operacionais, permitindo um gerenciamento mais eficiente e preciso.

### Utilização

Além da coleta de informações de hardware e software, e do inventário de softwares, o Xventory também oferece a possibilidade de medir o uso de softwares de forma passiva.

Essa funcionalidade permite que as organizações coletem dados estatísticos de utilização de aplicações monitoradas, sem a necessidade de interação do usuário ou instalação de agentes adicionais. Os dados são coletados automaticamente e enviados ao gerenciamento da solução, permitindo que as organizações tenham uma visão completa e atualizada sobre o uso dos softwares em seus dispositivos gerenciados.

Com a medição passiva de uso de softwares, as organizações podem identificar quais softwares são mais utilizados e por quem, permitindo uma melhor gestão de licenças e garantindo a conformidade com as políticas de segurança da informação. Além disso, é possível identificar possíveis problemas de desempenho ou falhas nos softwares, permitindo uma correção mais rápida e eficiente.

O Xventory oferece relatórios detalhados sobre o uso de softwares, permitindo que as organizações tenham uma visão completa e precisa sobre o uso dos softwares em seus dispositivos gerenciados. Dessa forma, as organizações podem tomar decisões mais assertivas e eficientes sobre a gestão de seus ativos de TI.

Concluindo, o Xventory é capaz de medir o uso de softwares de forma passiva, coletando dados estatísticos de utilização de aplicações monitoradas e enviando ao gerenciamento da solução para posterior uso em análises do ambiente.&#x20;

[title] Infraestrutura
[path] Infraestrutura/

Todos nós presentes na sua infraestrutura representam Itens de Configuração, passíveis de ser qualquer item dentro de sua rede ou infraestrutura. No Atmos é possível gerir toda a sua infraestrutura e acompanhar em tempo real a situação de cada nó.

## Acesso&#x20;

Para acessar a aplicação Atmos é necessário clicar no botão "aplicações" localizado no canto inferior esquerdo, do menu principal no AIOPS.

Após acessar o Atmos é necessário acessar a tela de infraestrutura através do menu principal:

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/ggS7bQ-iDMiYfbM1CW-dV_image.png" signedSrc size="36" width="154" height="44" position="center" caption}

Ao acessar a tela de infraestrutura será possível ver a listagem de nós de sua infraestrutura:

![](https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/pRwh1X1OlueYbJ_voMvCP_image.png)

## Informações

Na listagem é possível temos a opção de acompanhar informações como:

- ID do item de configuração
- IP
- Status atual
- Insights
- Automações
- Triggers
- Heartbeat&#x20;
- Última atualização&#x20;
- Anotações
- Sistema operacional&#x20;

Dessa forma é possível de forma rápida, não só consultar todos os itens, mas também ter uma informação rápida e assertiva sobre cada um deles.

## Filtros

É possível também utilizar a opção de busca, filtros, e ações em grupo na seguinte opção, existente no canto superior direito:

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/zldtH_JZIAqNj-mvyJgw3_image.png" signedSrc size="38" width="146" height="46" position="center" caption}

## Ações

Para acessar as possíveis ações para um determinado nó, da infraestrutura, é necessário clicar na engrenagem existente no canto superior direito:

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/zEoMG0btEW1ETo_2XehV0_image.png" signedSrc size="16" width="34" height="36" position="center" caption}

As possíveis opções então aparecerão:&#x20;

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/JCtwf-jtUPM0o1KqPHGpE_image.png" signedSrc size="32" width="173" height="105" position="center" caption}

Temos então a ação **adicionar&#x20;**:Link[host]{href="https://docs.citsmart.com/aiops/hosts" newTab="true"}, que permitirá adicionar um nó avulso, que não foi capturado via agents ou descobertas.

A opção ativar seleção, permite diferentes ações em vários nós ao mesmo tempo:

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/iSBTa4gGcH-W44AdrCVfG_image.png" signedSrc size="32" width="166" height="163" position="center" caption}

Cada uma dessa ações poderá ser executada após o usuário selecionar um ou mais :Link[hosts]{href="https://docs.citsmart.com/aiops/hosts" newTab="true"}.

[title] Requisitos de Software
[path] Visão Geral do Sistema/Requisitos/

O AIOPS e suas ferramentas foram desenvolvidas com suporte aos principais sistemas existentes no mercado, em geral: Windows, Mac, Linux

Aplicação Web


A plataforma CITSmart é 100% web, o que permite o seu acesso por meio de qualquer dispositivo com conexão à internet, desde que possua um navegador compatível com os padrões exigidos pela aplicação.

### Compatibilidade de Navegadores

A aplicação é compatível com os principais navegadores do mercado, nas seguintes versões mínimas:

- Google Chrome: versão 18.0 ou superior
- Mozilla Firefox: versão 24.0 ou superior
- Internet Explorer: versão 9.0 ou superior

Por padrão os navegadores oferecem suporte ao Javascript, caso contrário, é necessário habilitar nas Opções de Internet.

### Compatibilidade de OS

A aplicação AIOPS é compatível com os seguintes sistemas operacionais:

| **Linux distribution**   | **Versions**                     | **CPU Arch** |
| ------------------------ | -------------------------------- | ------------ |
| Amazon Linux 2           | all versions                     | x86-64       |
| ***Alma Linux \****      | 8.x, 9.x ou mais recente         | x86-64       |
| ***Rocky Linux \****     | 8.x, 9.x, 10.x ou mais recente   | x86-64       |
| ***CentOS \****          | 7.x, 8.x ou mais recente         | x86-64       |
| ***Oracle Linux \****    | 7.x, 8.0+ ou mais recente        | x86-64       |
| ***Ubuntu \****          | 20.04+ ou mais recente           | x86-64       |
| Debian                   | 10.x+ ou mais recente            | x86-64       |
| openSUSE                 | 15.x+ ou mais recente            | x86-64       |
| Red Hat Enterprise Linux | 8.x+ ou mais recente             | x86-64       |
| SUSE Enterprise Linux    | 15.0, 15.1, 15.2 ou mais recente | x86-64       |

*S.O. Recomendados:* ***(em destaque)\****.

- Microsoft Windows 7 e superiores.
- Microsoft Windows Server 2003 (32 e 64 bits) e superiores.
- Vmware cSphere 6.7 e superiores.
- MacOS

### Requisitos de Execução

O navegador utilizado deve ter suporte a JavaScript habilitado (recurso normalmente ativado por padrão);

Recomenda-se o uso da versão mais atualizada do navegador para garantir melhor desempenho, segurança e compatibilidade com os recursos visuais e interativos da plataforma.

## Arquitetura

O AIOPS e suas ferramentas operam de forma distribuída e paralela, nosso foco em alta disponibilidade permite inclusive, adicionar nós em diferentes localidades (Edge Location/Cloud).
Nossos especialistas oferecem total suporte durante a implantação da plataforma em sua organização.


## Requisitos de software:

### Banco de Dados&#x20;

A instalação do AIOPS suporta os seguintes fornecedores:

- Postgres 9.x ou superior
- Oracle 12C ou superior
- MySQL Server 5.x ou superior

### &#xD;

### Agent: Sistemas Operacionais / Distros suportados

- AIX 5, 6 e 7
- CentOS 6.5 ou superior
- Debian 7.x ou superior
- Red Hat 6.5 ou superior
- Red Hat Enterprise Linux Server 6.5 ou superior
- Oracle Linux Server 6.5 ou superior
- Ubuntu 14.04 ou superior
- FreeBSD 9.3-RELEASE ou superior
- SuSE 11 ou superior
- Solaris Sparc 9, 10, 11
- HP-UX 11
- IBM i v7.1 (English & Spanish locales), IBM z/OS 2.1, 2.3
- Microsoft Windows 7, 8, 10 ou superior
- Microsoft Windows Server 2008, 2012 ou superior



### Agent: Sistemas Operacionais / Distros não suportados

-
  Oracle Linux 5 ou inferior
- Red Hat Enterprise Linux Server 5 ou inferior
- Windows XP, Vista ou inferiores
- Microsoft Windows(R) Server 2003 ou inferior
- MacOS 10.8 ou inferior

### Módulo de Automação (Remoto)

O Atmosphere é um módulo (opcional) instalado em servidores Linux e Windows junto ao Sphere Agent, este módulo permite executar Pipes de Automação nas máquinas remotas, incluindo auto recuperação de serviços e processos. Confira mais informações no Sphere Agent.

### Acessos Simultâneos

O AIOPS permite o acesso simultâneo à usuários em diferentes níveis de acesso (administrador, analista, supervisor, operador e gestor), para a realização de tarefas de modo independente.

Todas as ações/atividades dos usuários são passíveis de auditória.

[title] Politicas
[path] AIOps/Inventário/

## Utilização dos modelos

Os modelos de Política de Configuração baseados em Windows são uma parte essencial do software Xventory, uma ferramenta de gerenciamento de inventário de ativos de TI que permite que os administradores de sistema gerenciem e rastreiem ativos de hardware e software em uma organização de maneira eficiente e escalável.

Os modelos de Política de Configuração do Xventory permitem que os administradores de sistema criem políticas personalizadas e implantem essas políticas em todos os dispositivos gerenciados, garantindo que todas as configurações de segurança e rede necessárias estejam em vigor em toda a organização. Com esses modelos, os usuários de sistema podem criar scripts relacionados a políticas que podem ser implantados em dispositivos gerenciados com sistema operacional Windows, automatizando tarefas de configuração e melhorando a eficiência operacional.

Os modelos disponíveis no Xventory incluem configurações de segurança, configurações de firewall, configurações de rede, configurações do Internet Explorer e configurações de políticas de conta de usuário. Cada modelo inclui uma descrição detalhada das configurações que podem ser configuradas por meio do modelo e uma explicação de como usar o modelo para implantar as configurações desejadas.

Além disso, o Xventory permite que os administradores de sistema criem políticas personalizadas para atender às necessidades específicas de sua organização. Isso significa que é possível criar políticas que sejam aplicáveis a um único dispositivo, a um grupo de dispositivos ou a todos os dispositivos gerenciados.

Em resumo, os modelos de Política de Configuração baseados em Windows são uma parte fundamental do software Xventory, permitindo que os administradores de sistema gerenciem e implantem políticas de segurança e configuração em dispositivos gerenciados de maneira automatizada e eficiente. Com esses modelos, os administradores de sistema podem garantir que todas as configurações corretas sejam implantadas em todos os dispositivos gerenciados da organização, independentemente do sistema operacional utilizado.

## Integração com pipes&#x20;

Integrar o Xventory com a solução de low code (Pipes) pode levar o gerenciamento de ativos de TI para um nível totalmente novo de eficiência e escalabilidade. Com a integração do Xventory, os desenvolvedores podem aproveitar os modelos de Política de Configuração e outras funcionalidades do Xventory para criar aplicativos personalizados e fluxos de trabalho automatizados em questão de minutos, sem a necessidade de conhecimentos em programação.

Usando a nossa solução de low code, os desenvolvedores podem criar aplicativos personalizados que aproveitam os recursos do Xventory, como varredura automática de ativos e tomada de decisões automatizadas com base em políticas de configuração. Eles também podem usar os modelos de Política de Configuração para automatizar tarefas de configuração e melhorar a eficiência operacional.

A integração do Xventory com uma solução de low code permite que as empresas desenvolvam soluções personalizadas e escaláveis ​​para gerenciar e rastrear ativos de hardware e software em toda a organização. Com essa solução integrada, as empresas podem melhorar a eficiência operacional, aumentar a produtividade e garantir que todas as configurações de segurança e rede necessárias estejam em vigor em todos os dispositivos gerenciados.

[title] Introdução
[path] /


[title] Kubernetes
[path] Infraestrutura/Provedor de Recursos/

Esta seção permite configurar a integração com um cluster Kubernetes para importar informações sobre namespaces, pods, serviços, e outros recursos para o sistema de inventário. A conexão é estabelecida por meio de autenticação com o cluster, seja via nome de usuário/senha ou, preferencialmente, token de autenticação.

1. **Host** (Obrigatório)
   - **Descrição:** Insira o endereço do servidor API do Kubernetes. Este é o endpoint de acesso ao cluster Kubernetes.
   - **Exemplo:** https\://192.168.0.200:6443
2. **Excluir namespaces**
   - **Descrição:** Selecione os namespaces que deseja **excluir** da descoberta. Isso é útil para evitar a importação de recursos de namespaces que não são necessários no inventário.
   - **Exemplo:** kube-system, monitoring.
3. **Autenticação via Token** (Opcional)
   - **Descrição:** Ative essa opção se desejar autenticar-se no cluster utilizando um token ao invés de nome de usuário e senha.
   - **Observação:** Se esta opção estiver habilitada, o campo de senha será substituído pelo campo de token.
4. **Nome de Usuário** (Obrigatório se a autenticação via Token estiver desativada)
   - **Descrição:** Informe o nome de usuário que será utilizado para autenticação com o cluster Kubernetes. Este usuário deve ter permissões suficientes para listar e gerenciar os recursos no cluster.
   - **Exemplo:** admin, devops-user.
5. **Senha** (Obrigatório se a autenticação via Token estiver desativada)
   - **Descrição:** Insira a senha associada ao nome de usuário. Este campo só estará disponível se a opção de autenticação via Token estiver desativada.
   - **Nota de Segurança:** A senha será armazenada de forma segura no sistema.
6. **Token de Autenticação** (Obrigatório se a autenticação via Token estiver ativada)
   - **Descrição:** Insira o token para autenticação com o cluster. Este campo substitui o nome de usuário e senha quando a autenticação via token está ativada.
   - **Exemplo:** eyJhbGciOiJSUzI1NiIs...

- **Testar Conexão**
  - **Descrição:** Verifica se as credenciais fornecidas e o host estão corretos e se o sistema pode se conectar com sucesso ao servidor API do Kubernetes. Certifique-se de que o servidor está acessível e que o usuário tem as permissões adequadas.
- **Permissões Necessárias:** Certifique-se de que o usuário ou token possui as permissões necessárias para listar namespaces, pods, serviços e outros recursos no cluster.
- **Filtragem de Recursos:** Utilize a opção de **Excluir namespaces** para evitar sobrecarga de dados desnecessários no inventário ao incluir apenas os namespaces de interesse.


[title] Elastiflow
[path] AIOps/Integrações/Observação de redes/

## ElastiFlow™ Unified Flow Collector

:::hint{type="info"}
## Ferramenta focada em visibilidade de rede

https\://www\.elastiflow\.com/
:::

O ElastiFlow ™ Unified Flow Collector recebe, decodifica, transforma, normaliza, traduz e enriquece registros de fluxo de rede e telemetria enviados de dispositivos de rede e aplicativos usando IPFIX, Netflow e sFlow. Os registros resultantes podem ser enviados para várias distribuições e serviços Elasticsearch, incluindo:

- Elasticsearch (on-premisses)
- Distro para Elasticsearch
- Serviço AWS Elasticsearch&#x20;



![](https://user-images.githubusercontent.com/10326954/89781356-727ede00-db13-11ea-8130-73562a8593f8.png)



## Integração&#x20;

Através da funcionalidade de [Integrações](docId\:waRNAcNGqjNLGFiIAU1xw) é possível ativar a integração com a ferramenta elastiflow e permitir coleta de informações relacionadas a tráfego de rede, possibilidade enriquecimento do contexto de situações adversas, permitindo um troubleshoot mais assertivo além de potencializar as automações que são possíveis de realizar através do AIOPS.

[title] Configurações em comum
[path] AIOps/Usuários/

| &#xA;                  | **Administrador** | **Analista**    | **Gestor**      | **Supervisor**  | **Operador**    |
| ----------------------- | ----------------- | --------------- | --------------- | --------------- | --------------- |
| **Segredos**            | Acesso total      | Acesso total    | Acesso total    | Acesso total    | Acesso total    |
| **Chaves de acesso**    | Acesso total      | Acesso total    | Acesso total    | Acesso total    | Sem Acesso      |
| **Execuções (Rotinas)** | Acesso total      | Acesso total    | Somente leitura | Somente leitura | Somente leitura |
| **Sobre**               | Somente leitura   | Somente leitura | Sem Acesso      | Sem Acesso      | Sem Acesso      |



[title] AIOps
[path] AIOps/Usuários/

## Funcionalidades

|                                                                                                                    | **Administrador** | **Analista** | **Gestor**   | **Supervisor**  | **Operador**    |
| ------------------------------------------------------------------------------------------------------------------ | ----------------- | ------------ | ------------ | --------------- | --------------- |
| ****:Link[**Incidentes**]{href="https://docs.citsmart.com/aiops/incidentes" newTab="true"}****                     | Acesso total      | Acesso total | Acesso total | Acesso total    | Acesso total    |
| ****:Link[**Eventos e incidentes**]{href="https://docs.citsmart.com/aiops/eventos-e-incidentes" newTab="true"}**** | Acesso total      | Acesso total | Acesso total | Sem acesso      | Sem acesso      |
| ****:Link[**Visão Geral**]{href="https://docs.citsmart.com/aiops/visao-geral" newTab="true"}****                   | Acesso total      | Acesso total | Acesso total | Acesso total    | Acesso total    |
| ****:Link[**Integrações**]{href="https://docs.citsmart.com/aiops/integracoes" newTab="true"}****                   | Acesso total      | Acesso total | Acesso total | Somente leitura | Somente leitura |
| **Eventos**                                                                                                        | Acesso total      | Acesso total | Sem acesso   | Sem acesso      | Sem acesso      |



## Configurações

### Monitoramento

|                                                                                                                            | **Administrador** | **Analista** | **Gestor**      | **Supervisor**  | **Operador**    |
| -------------------------------------------------------------------------------------------------------------------------- | ----------------- | ------------ | --------------- | --------------- | --------------- |
| ****:Link[**Canais**]{href="https://docs.citsmart.com/aiops/canais" newTab="true"}****                                     | Acesso total      | Acesso total | Acesso total    | Acesso total    | Somente leitura |
| ****:Link[**Auto Compartilhamento**]{href="https://docs.citsmart.com/aiops/compartilhamento-automatico" newTab="true"}**** | Acesso total      | Acesso total | Acesso total    | Acesso total    | Somente leitura |
| **Escala**                                                                                                                 | Acesso total      | Acesso total | Somente leitura | Somente leitura | Somente leitura |



### Pessoas

|                                                                                            | **Administrador** | **Analista** | **Gestor**   | **Supervisor** | **Operador**    |
| ------------------------------------------------------------------------------------------ | ----------------- | ------------ | ------------ | -------------- | --------------- |
| ****:Link[**Time**]{href="https://docs.citsmart.com/aiops/times" newTab="true"}****        | Acesso total      | Acesso total | Acesso total | Acesso total   | Somente leitura |
| ****:Link[**Usuários**]{href="https://docs.citsmart.com/aiops/usuarios" newTab="true"}**** | Acesso total      | Acesso total | Acesso total | Acesso total   | Somente leitura |



### Geral

|                                                                                           | **Administrador** | **Analista**    | **Gestor**      | **Supervisor**  | **Operador**    |
| ----------------------------------------------------------------------------------------- | ----------------- | --------------- | --------------- | --------------- | --------------- |
| ****:Link[**Organização**]{href="https://docs.citsmart.com/aiops/slas" newTab="true"}**** | Somente leitura   | Somente leitura | Somente leitura | Somente leitura | Somente leitura |
| **Nível de prioridade**                                                                   | Acesso total      | Acesso total    | Somente leitura | Somente leitura | Somente leitura |


[title] Times
[path] AIOps/

## **Criando equipes**

A colaboração entre membros de diferentes equipes, é um dos pilares do AIOPS. No AIOPS é possível criar equipes e definir líderes para as mesmas, proporcionando não só o direcionamento ideal de incidentes para quem realmente precisa atuar, mas também a redução de informação que precisa ser vista por um analista, simplificando o processo de troubleshoot.

Na barra lateral canto inferior da tela ao clicar na opção configurações um modal se abrirá contendo opções para a inserção de equipes e colaboradores.

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/3DjnWxDybUirslPuODoSJ_Screen%20Shot%202021-01-10%20at%2011.52.05.png" size="10" caption="Botão Configurações" position="center" signedSrc="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/3DjnWxDybUirslPuODoSJ_Screen%20Shot%202021-01-10%20at%2011.52.05.png?AWSAccessKeyId=AKIAYQNQCIXNIQWBC56C&Expires=1697895667&Signature=EUtpcDMfD8evtcbH695kaoiGh8c%3D"}

![](https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/wezLBVEjCURm5nfcV_fEg_Screen%20Shot%202021-01-10%20at%2012.16.41.png)

No botão Inserir times, no canto superior direito da tela, é possível inserir times, listando os profissionais que fazem parte de cada time em questão.

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/STetFKlv-2e07xePjrUWD_Screen%20Shot%202021-01-10%20at%2012.18.08.png" size="24" caption position="center" signedSrc="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/STetFKlv-2e07xePjrUWD_Screen%20Shot%202021-01-10%20at%2012.18.08.png?AWSAccessKeyId=AKIAYQNQCIXNIQWBC56C&Expires=1697895667&Signature=i1MwOAHpk%2BV2EZi030RmzVx2FOc%3D"}

![](https://gblobscdn.gitbook.com/assets%2F-Ls76-8XbGuboSQAg3Y9%2F-LsISqo_jP5aeNz0jIkf%2F-LsIcHy6pv1dzGTZ-0xb%2FCaptura%20de%20Tela%202019-10-28%20a%CC%80s%2015.27.28.png?alt=media\&token=cd224888-4c43-4d49-b4cf-9ecf736a1743 "Modal para inserção de usuários em times específicos.")

## **Atribuindo responsáveis**

Seja na tela de listagem de incidentes ou no detalhamento de incidente, é possível que você atribua membros de suas equipes para acompanhamento de diferentes problemas, facilitando não só a atuação como também a colaboração entre os profissionais envolvidos.


![](https://gblobscdn.gitbook.com/assets%2F-Ls76-8XbGuboSQAg3Y9%2F-LsISqo_jP5aeNz0jIkf%2F-LsI_1GFaIyBydpGlRel%2FCaptura%20de%20Tela%202019-10-28%20a%CC%80s%2015.09.08.png?alt=media\&token=8d8690e7-b9e0-4c6d-baba-83dc75998fc3)

Colabore com os membros de uma equipe, observando e contribuindo em comentários de incidentes, funcionalidade disponível através do ícone (Comentar) abaixo, na tela de detalhamento de incidente, ou no dropdown, na listagem de incidente.

::Image[]{src="https://gblobscdn.gitbook.com/assets%2F-Ls76-8XbGuboSQAg3Y9%2F-LsISqo_jP5aeNz0jIkf%2F-LsIbCIiQ7N2siNmGPoL%2FCaptura%20de%20Tela%202019-10-28%20a%CC%80s%2015.21.08.png?alt=media&token=f9806c7c-54ae-4575-a770-79ce8f9f5507" size="20" caption="Dropdown da listagem de incidentes" position="center" signedSrc="https://gblobscdn.gitbook.com/assets%2F-Ls76-8XbGuboSQAg3Y9%2F-LsISqo_jP5aeNz0jIkf%2F-LsIbCIiQ7N2siNmGPoL%2FCaptura%20de%20Tela%202019-10-28%20a%CC%80s%2015.21.08.png?alt=media&token=f9806c7c-54ae-4575-a770-79ce8f9f5507"}

::Image[]{src="https://gblobscdn.gitbook.com/assets%2F-Ls76-8XbGuboSQAg3Y9%2F-LsISqo_jP5aeNz0jIkf%2F-LsIaAVzYH4mEQZcR8ZR%2FCaptura%20de%20Tela%202019-10-28%20a%CC%80s%2015.18.48.png?alt=media&token=ece816a3-5bc9-46b1-bed2-3a286b3d0e75" size="68" caption position="center" signedSrc="https://gblobscdn.gitbook.com/assets%2F-Ls76-8XbGuboSQAg3Y9%2F-LsISqo_jP5aeNz0jIkf%2F-LsIaAVzYH4mEQZcR8ZR%2FCaptura%20de%20Tela%202019-10-28%20a%CC%80s%2015.18.48.png?alt=media&token=ece816a3-5bc9-46b1-bed2-3a286b3d0e75"}

## Principais Funcionalidades:

- [ ] Possibilidade de atuação de membros entre equipes
- [ ] Atribuição de líderes
- [ ] Deleção de membros
- [ ] Atualização de Membros


[title] Teste Web
[path] Infraestrutura/

Na aplicação Atmos é possível testar a funcionallidade de URL, os testes de web em várias etapas permitem que você encadei&#x65;**&#xA0;**&#x74;estes HTTP para monitorar de forma proativa se as jornadas em seus serviços principais estão disponíveis a qualquer hora e em qualquer lugar.

A Plataforma AIOPS é capaz de identificar falhas. Criando alertas e facilitando o gerenciamento das aplicações.

Se algum dos seus serviços começar a responder lentamente ou de forma inesperada o teste de web poderá: alertara a sua equipe, bloquear seu pipeline, ou até mesmo reverter o problema.

Para a realização do teste de web, basta clicar no botão que se encontra na barra lateral, como demostrado abaixo:

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/nzozLt-5qrluMkVkXPe4c_Screen%20Shot%202021-01-10%20at%2015.56.04.png" size="10" caption="Botão Testes Web" position="center" signedSrc="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/nzozLt-5qrluMkVkXPe4c_Screen%20Shot%202021-01-10%20at%2015.56.04.png?AWSAccessKeyId=AKIAYQNQCIXNIQWBC56C&Expires=1697908556&Signature=59exIQ5k9WnG9Cy5%2FqWIOHnI1oc%3D"}

Logo após uma tela será aberta, contendo a listagem de todos os testes previamente cadastrados. Podendo estes serem filtrados em ativos e inativos, através das opções na coluna lateral esquerda.

![](https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/IhCHpK2ClwrGVh8k6XhUY_Screen%20Shot%202021-01-10%20at%2016.06.54.png)

## Criando Novo Teste

No botão Inserir Novo Teste Web, no canto superior direito da tela, é permitida a alimentação de dados para realização do teste desejado.

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/Nd8XgzrwWZkAhv4aFiDjW_Screen%20Shot%202021-01-10%20at%2016.08.45.png" size="32" caption position="center" signedSrc="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/Nd8XgzrwWZkAhv4aFiDjW_Screen%20Shot%202021-01-10%20at%2016.08.45.png?AWSAccessKeyId=AKIAYQNQCIXNIQWBC56C&Expires=1697908556&Signature=C3FhpXra4lzS%2FBDZ2CkY1oTtdBA%3D"}

## Especificando o Teste

Para executar essa operação, basta:

1. Nomear o teste em questão
2. Escolher um método para o teste
3. Especificar a URL a ser testada
4. Eriquecer a solicitação com opções avançadas

![](https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/YDYE23rN19iP6U_yFMpmX_Screen%20Shot%202021-01-10%20at%2016.10.39.png)

Após o preenchimento de todas as especificações, basta clicar no botão Salvar, que se encontra no canto superior direito da tela.

[title] Escalas
[path] AIOps/

Criação de escalas para gerência de execução de notificações e pipes.

## Criação da escala:

Acessar a opção de configurações no menu principal do AIOPS:

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/DB21YU7NtmTsb-aPoWdvQ_2x7j3lffnjoosde1wntotbotaoconfiguracoes.png" size="34" width="160" height="38" caption position="center" signedSrc="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/DB21YU7NtmTsb-aPoWdvQ_2x7j3lffnjoosde1wntotbotaoconfiguracoes.png"}

No menu lateral escolha a opção **Escala**.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/6nDP0BQgXrI3U6LTnUaSG_image.png" size="50" width="232" height="159" caption position="center" signedSrc="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/6nDP0BQgXrI3U6LTnUaSG_image.png"}

Você poderá criar uma nova escala ou alterar um já existente.&#x20;

Ao criar uma nova escala, na aba **Geral** defina um nome (obrigatório) e uma descrição (opcional).

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/5A2ab26KDnvymYjn4NnR5_image.png)

Em seguida na aba **Hosts&#x20;**&#x65;scolha os **Itens de Configuração&#x20;**&#x71;ue farão parte desta escala:

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/HGeQV-_uc0UCVj3Xp10AL_image.png "Definição dos hosts")

Na aba **Notificações&#x20;**&#x63;rie as regras para notificação de usuários.

- **Trigger da notificação:**
  - Novo incidente - Notifica o usuário quando um novo incidente for criado.&#x20;
  - Conclusão do incidente - Notifica o usuário quando um incidente for concluído.&#x20;
  - Pipe disponível - Notifica o usuário quando um novo pipe estiver disponível.&#x20;
- **Aguardar:** Quanto tempo deve-se aguardar antes do disparo das notificações.
- **Integração:** Qual integração de notificação será utilizada.
- **Destinatários:&#x20;**&#x51;uais usuários ou times serão notificados.

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/62kPeI9rxeZGwH9uVxzNh_image.png)

Na seção **Execução de Pipes**, você pode realizar as configurações destinadas à execução:

- **Executar pipes quando disponíveis:** Habilita/Desabilita a execução automática.
  - **Executar após:** Definição do tempo de espera da execução automática após um novo alerta ser criado.
- **Notificar:**
  - **Antes da execução:&#x20;**&#x45;nvia uma mensagem antes da execução ser iniciada.
  - **Após a execução:** Envia uma mensagem quando a automação for concluída.
  - **Destinários:** Opcionalmente poderá definir quem receberá as notificações da execução de pipes.

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/DrG4BYyXYxHFmNsMAmqa-_image.png)


[title] Habilitando e Monitorando pg_stat_statements no PostgreSQL com Telegraf
[path] Métrica/Coletas customizadas/

Este documento explica como habilitar o pg\_stat\_statements e configurar o Telegraf para monitorar as consultas lentas no PostgreSQL.

## Introdução

O módulo pg\_stat\_statements fornece um meio de rastrear estatísticas de planejamento e execução de todas as instruções SQL executadas por um servidor PostgreSQL.&#x20;

## Habilitando pg\_stat\_statements

### 1. Modificar a Configuração do PostgreSQL

O módulo pg\_stat\_statements deve ser carregado adicionando pg\_stat\_statements a shared\_preload\_libraries no arquivo postgresql.conf, pois requer memória compartilhada adicional.

Para habilitar pg\_stat\_statements, modifique a seguinte configuração no arquivo de configuração do PostgreSQL (por exemplo, /etc/postgresql/12/main/postgresql.conf):

:::BlockQuote
shared\_preload\_libraries = 'pg\_stat\_statements'
pg\_stat\_statements.track = all
:::

### 2. Reiniciar o PostgreSQL

Após alterar a configuração do PostgreSQL, reinicie o serviço para que a mudança tenha efeito:

:::CodeblockTabs
command

```linux
sudo systemctl restart postgresql
```
:::

### 3. Criar a Extensão pg\_stat\_statements para Cada Banco de Dados

O pg\_stat\_statements rastreia apenas as estatísticas do banco de dados onde a extensão é criada. Portanto, crie a extensão para cada banco de dados:

:::CodeblockTabs
command

```linux
CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
```
:::

### 4. Verificar pg\_stat\_statements

Para verificar se pg\_stat\_statements está funcionando, execute a seguinte consulta:

:::CodeblockTabs
command

```linux
SELECT count(*) FROM pg_stat_statements;
```
:::

## Monitorando com Telegraf

### 1. Configuração do Telegraf&#x20;

Adicione as seguintes configurações ao arquivo de configuração do Telegraf para monitorar o PostgreSQL

**PostgreSQL Input Plugin:**

```yaml
[inputs]
[[inputs.postgresql]]
  address = "host=127.0.0.1 dbname=postgres user=<DB_USER> password=<DB_PASSWORD> sslmode=disable"
  databases = [ "postgres",]

```

**PostgreSQL Extensible Input Plugin:**

```yaml
[[inputs.postgresql_extensible]]
  address = "host=127.0.0.1 dbname=postgres user=<DB_USER> password=<DB_PASSWORD> sslmode=disable"
  databases = [ "postgres",]
[[inputs.postgresql_extensible.query]]
  sqlquery = "select userid, query, calls, total_time, min_time, max_time, mean_time, stddev_time, rows from public.pg_stat_statements WHERE mean_time/1000 > 0.8;"
  version = 901
  withdbname = false
  measurement = "pg_slow_queries"
  tagValue = "query, userid"

```


[title] Manutenções
[path] Infraestrutura/

O Atmos permite a configuração e agendamento das rotinas de manutenção de forma simples e completa.

O agendamento de manutenção tem por objetivo suprimir alertas e incidentes gerados pelos servidores enquanto os mesmo passam por procedimentos de reparo ou desligamento programado, assim não afetando a disponibilidade e SLA dos serviços relacionados.

### Planos de Manutenção

Para iniciar o plano de Manutenção, acesse o botão planejamento na coluna lateral esquerda da tela:

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/qpr-FybYVVmqbebYaBDz_/y8swjsWdE3VDgY86GfHgi_image.png" signedSrc size="16" width="76" height="63" position="center" caption}

Após o acesso uma tela estará disponível possibilitando planejar as manutenções, através do botão Planos de Matutenção que se encontra logo acima na coluna equerda da tela.&#x20;

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/qpr-FybYVVmqbebYaBDz_/r_Ez2gHUSo4OZj7E4lm7x_image.png" signedSrc size="50" width="250" height="154" position="center" caption}

Ao clicar em Planos de Manutenção, a plataforma disponibilizará o acesso à todos os planejamentos já realizados, podendo estes serem filtrados em: todos, ativos e inativos.&#x20;

![](https://archbee-image-uploads.s3.amazonaws.com/qpr-FybYVVmqbebYaBDz_/WVPnqnMVkgBxngppEuRKH_image.png)

Na tela de listagem dos Planejamentos estará disponível um botão para criação de uma nova manutenção, que por sua vez abrirá um modal contendo a descrição geral do agendamento.

![](https://gblobscdn.gitbook.com/assets%2F-Ls76-8XbGuboSQAg3Y9%2F-LsMWnkImfsn_AnKaR2U%2F-LsM_9A-PSKjZk-Un_X9%2FCaptura%20de%20Tela%202019-10-29%20a%CC%80s%2010.51.13.png?alt=media\&token=fafa7b29-79bd-4f90-b3c5-fb401b77522e "Descrição geral do agendamento")

A funcionalidade permite selecionar data e horário específicos, rotinas diárias e/ou semanais, sendo possível selecionar apenas quais dias da semana o procedimento de manutenção ocorrerá.



::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/qpr-FybYVVmqbebYaBDz_/yrM3ibcvTwgy-QIl7viAz_image.png" signedSrc size="26" width="214" height="61" position="center" caption}

::Image[]{src="https://gblobscdn.gitbook.com/assets%2F-Ls76-8XbGuboSQAg3Y9%2F-LsMWnkImfsn_AnKaR2U%2F-LsM_E1LWC3RYoiGKW53%2FCaptura%20de%20Tela%202019-10-29%20a%CC%80s%2010.52.12.png?alt=media&token=05aa0575-e3ba-4a2b-a250-a8962442c3e7" size="80" signedSrc="https://gblobscdn.gitbook.com/assets%2F-Ls76-8XbGuboSQAg3Y9%2F-LsMWnkImfsn_AnKaR2U%2F-LsM_E1LWC3RYoiGKW53%2FCaptura%20de%20Tela%202019-10-29%20a%CC%80s%2010.52.12.png?alt=media&token=05aa0575-e3ba-4a2b-a250-a8962442c3e7"}

### Definindo períodos de programação

Ao selecionar os ICs que estarão em manutenção, você garante que todos os serviços, aplicações e recursos relacionados ao mesmo serão englobados pelo agendamento e portanto não terão sua disponibilidade alterada dentro do período programado.

::Image[]{src="https://gblobscdn.gitbook.com/assets%2F-Ls76-8XbGuboSQAg3Y9%2F-LsMWnkImfsn_AnKaR2U%2F-LsM_Fe5fmng485-hpKf%2FCaptura%20de%20Tela%202019-10-29%20a%CC%80s%2010.53.22.png?alt=media&token=57e829fd-86cb-437c-925b-f48948761baa" size="80" signedSrc="https://gblobscdn.gitbook.com/assets%2F-Ls76-8XbGuboSQAg3Y9%2F-LsMWnkImfsn_AnKaR2U%2F-LsM_Fe5fmng485-hpKf%2FCaptura%20de%20Tela%202019-10-29%20a%CC%80s%2010.53.22.png?alt=media&token=57e829fd-86cb-437c-925b-f48948761baa"}

ICS associados à manutenção

[title] Configuração de paineis
[path] Infraestrutura/Host/

## Configuração Geral

A fim de configurar os paineis de um IC contendo gráficos para exibição, o usuário deve preencher o formulário ao clicar em "Novo Gráfico".

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/P4XUDpqE-jJq7yEYQnx5j_image.png" size="46" width="501" height="676" caption position="center" signedSrc="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/P4XUDpqE-jJq7yEYQnx5j_image.png"}

| **Campo**             | **Descrição**                                                      | **Valores**                                                                                                                                                                                                  |
| --------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Nome                  | Nome para identificação do gráfico                                 |                                                                                                                                                                                                              |
| Transformação         | Altera a forma como a métrica é interpretada indiferente da função | - Nenhuma&#xA;- Derivação (converte em taxa x tempo)                                                                                                                                                         |
| Função                | Como o valor da métrica será calculado no perído escolhido.        | - Média&#xA;- Somatório&#xA;- Mínimo&#xA;- Máximo                                                                                                                                                            |
| Grupo                 | Grupo de métricas a ser observado.                                 | Os valores estão disponibilizados em :Link[Explorar Métricas]{href="https://docs.citsmart.com/aiops/explorar-as-metricas" newTab="true" hasDisabledNofollow="false"}                                         |
| Métrica               | Métrica a ser mostrada no gráfico.&#xA;Permite múltiplas seleções. | Métricas disponíveis para seleção estão documentadas no grupo escolhido.&#xA;&#xA;Ex: :Link[Listem Process]{href="https://docs.citsmart.com/aiops/listen-process" newTab="true" hasDisabledNofollow="false"} |
| Agrupar por           | Determina como as métricas serão visualizadas                      |                                                                                                                                                                                                              |
| Largura               | Largura de exibição do gráfico.                                    | - 25%    *(1/4 da tela)*&#xA;- 50%    *(2/4 da tela)*&#xA;- 75%    *(3/4 da tela)*&#xA;- 100 % *(4/4 da tela)*                                                                                               |
| Exibir valores vazios | Deixar espaços em branco onde não existem métricas.                | - Sim     *(mantém espaço em branco)* &#xA;- Não     *(preenche espaços vazios)*                                                                                                                             |

## Filtros (Opcional)

Ao abrir a aba, será possível visualizar filtros já criados.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/gY4v5bD7ScMhg-1saELlr_image.png" size="50" width="501" height="281" caption position="center" signedSrc="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/gY4v5bD7ScMhg-1saELlr_image.png"}

Ao clicar em "Novo filtro", um formulário será disponibilizado para preenchimento.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/cwuO9TiZ2b0DbUyUE_lTo_image.png" size="50" width="500" height="386" caption position="center" signedSrc="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/cwuO9TiZ2b0DbUyUE_lTo_image.png"}

| **Campo** | **Descrição**                              | **Valor**                        |
| --------- | ------------------------------------------ | -------------------------------- |
| Chave     | Chave para filtro por valor.               |                                  |
| Operação  | Operação lógica para o filtro.             | - Igual (=)&#xA;- Diferente (!=) |
| Valor     | Valor específico para o filtrar a métrica. |                                  |

## Avançado (Opcional)

A aba "Avançado" permite que o usuário construa manualmente a expressão para visualização das métricas.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/OgA-oJdlfYH1JzX0L6Vaw_image.png" size="50" width="498" height="396" caption position="center" signedSrc="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/OgA-oJdlfYH1JzX0L6Vaw_image.png"}


[title] Automação (Pipes)
[path] AIOps/Compartilhamento Automático/

Compartilhamento Automático utilizando Pipes de Automação.

## Criação do Auto Compartilhamento

Acessar a opção de configurações no menu principal do AIOPS:

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/2x7J3LFFnjoOSde1WNTOt_botaoconfiguracoes.png" size="36" caption position="flex-start" signedSrc="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/2x7J3LFFnjoOSde1WNTOt_botaoconfiguracoes.png?AWSAccessKeyId=AKIAYQNQCIXNIQWBC56C&Expires=1697895282&Signature=u3GjWQCRDv8ZqSJPO1jB53LRPz0%3D"}

No menu lateral escolha a opção **Auto Compartilhamento**:

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/u9p2-1Q_MH68GkLMX4JYz_captura-de-tela-2021-03-31-as-131027.png" size="40" caption position="center" signedSrc="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/u9p2-1Q_MH68GkLMX4JYz_captura-de-tela-2021-03-31-as-131027.png?AWSAccessKeyId=AKIAYQNQCIXNIQWBC56C&Expires=1697895282&Signature=65H9gyJoGn0fNAmLOidYBEvWdsg%3D"}

Você poderá criar um novo compartilhamento ou alterar um já existente. Para criar um novo você irá definir o **Ambiente** (utilizado para direcionar os alertas deste canal) e o **Tipo** escolhendo a opção de **Pipe**.

![](https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/Yli78RSr0RUC_La2mcCf-_doc-type-select.png)

Aparecerá no campo **Pipes** uma lista de opções disponíveis (criadas anteriormente no Atmos)

![](https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/G8oxOMCwHFpHdK9ZYctS-_doc-pipe-select.png "Escolha do Pipe para Automação")

Quando um pipe for selecionado a aba **Outlines** ficará disponível para atribuição das variáveis disponíveis no item selecionado.

Os outlines são parâmetros customizáveis que um pipe pode receber para a sua execução. Saiba mais acessando o menu de Pipes e Automação.

![](https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/ngwupF9dTNLYoQn9jU92y_doc-outline-list.png "Configuração de Outlines")

Para definir o Outline, acesse o botão **Novo Outline**.&#x20;

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/S_eLxGn6TjxKV5sGv2l9o_doc-btn-add-outline.png" size="26" caption position="flex-start" signedSrc="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/S_eLxGn6TjxKV5sGv2l9o_doc-btn-add-outline.png?AWSAccessKeyId=AKIAYQNQCIXNIQWBC56C&Expires=1697895282&Signature=NglSpjRakrY%2FxFGqGlOhrxM%2Fq5A%3D"}

Dentro da janela que aparecerá, escolha a **Chave** da variável do Pipe e defina o **Valor** desejado.

![](https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/navQaSmL3H4yu7VKRphkH_doc-new-outline.png "Janela de definição do outline")


[title] Scanner de Ativos
[path] Infraestrutura/Host/

O AIOPS oferece recursos avançados de scanner de ativos, permitindo que você tenha controle total sobre diferentes tipos de equipamentos de rede, máquinas de usuários finais e sistemas operacionais em diversos ambientes, como cloud (AWS, Google Cloud, Azure, Tencent), híbrido e infraestrutura própria.

## Varredura de Ativos de Rede, Servidores e Endpoints

O AIOPS é capaz de descobrir uma ampla variedade de ativos, incluindo equipamentos de rede, máquinas de usuários finais e componentes de datacenter. Essa capacidade abrangente permite que você tenha uma visão precisa do inventário de ativos de TI em sua organização.

### Equipamentos de Rede

O AIOPS é capaz de descobrir e rastrear equipamentos de rede, como roteadores, switches, firewalls, access points e dispositivos especializados. Isso permite um gerenciamento eficiente de sua infraestrutura de rede e ajuda a identificar e solucionar problemas de conectividade.

### Máquinas de Usuários Finais

Com o AIOPS, você pode descobrir e monitorar máquinas de usuários finais, como notebooks e PCs. Isso permite o rastreamento de ativos, gerenciamento de licenças de software e identificação de necessidades de atualização de hardware.

### Componentes de Datacenter

O AIOPS também oferece a capacidade de descobrir e rastrear componentes essenciais de datacenter, como storage, ambientes de virtualização e servidores físicos. Isso permite um gerenciamento abrangente de seus ativos de TI, garantindo a disponibilidade e o desempenho adequado de sua infraestrutura crítica.

### Suporte a Diferentes Sistemas Operacionais

O AIOPS é compatível com uma ampla gama de sistemas operacionais, garantindo a descoberta de ativos em diversos ambientes. Além dos sistemas operacionais populares, como Windows, Linux, Solaris e Unix o AIOPS também oferece suporte a outros sistemas operacionais, incluindo:

- AIX: Sistema operacional Unix desenvolvido pela IBM, utilizado em servidores de alto desempenho e missão crítica.
- HP-UX: Sistema operacional Unix desenvolvido pela Hewlett Packard Enterprise (HPE), amplamente utilizado em servidores HP Integrity e HP 9000.
- macOS: Sistema operacional utilizado em computadores Apple, permitindo a descoberta de ativos em ambientes macOS.
- FreeBSD: Sistema operacional de código aberto baseado em Unix, amplamente utilizado em servidores e ambientes de rede.
- CentOS: Distribuição Linux baseada no código-fonte do Red Hat Enterprise Linux, oferecendo suporte a servidores e infraestruturas críticas.
- Ubuntu: Distribuição Linux popular, conhecida por sua facilidade de uso e ampla comunidade de usuários.
- Debian: Outra distribuição Linux amplamente utilizada, oferecendo estabilidade e flexibilidade para diversos ambientes.
- IBM i: Sistema operacional da IBM para servidores de médio porte, fornecendo recursos avançados para ambientes corporativos.
- z/OS: Sistema operacional mainframe da IBM, utilizado em ambientes de grande escala que exigem alta disponibilidade e desempenho.

Com essa ampla compatibilidade de sistemas operacionais, o AIOPS permite que você descubra, monitore e gerencie ativos em uma variedade de plataformas, garantindo uma visão completa e precisa do seu inventário de ativos de TI.

### Descoberta em Ambientes Cloud, Híbridos e Infraestrutura Interna

O AIOPS oferece suporte completo a diferentes tipos de ambientes, incluindo cloud, híbrido e infraestrutura interna. Com a capacidade de descobrir ativos em provedores de nuvem populares, como AWS, Google Cloud, Azure e Tencent, você pode rastrear e gerenciar recursos na nuvem de forma eficiente. Além disso, o AIOPS é altamente adaptável a ambientes híbridos, permitindo que você tenha visibilidade tanto em ativos locais quanto na nuvem. Por fim, a solução também é capaz de descobrir e monitorar ativos em sua própria&#x20;

Além da descoberta de equipamentos de rede, máquinas de usuários finais e sistemas operacionais, o AIOPS também oferece recursos avançados de descoberta de virtualização e ambientes de container. Essa funcionalidade permite que você tenha visibilidade e controle sobre os ativos virtualizados e em containers em sua infraestrutura de TI.

### Virtualização

O AIOPS é capaz de descobrir e rastrear servidores de virtualização, como VMware ESXi, Microsoft Hyper-V, Citrix XenServer, entre outros. Isso inclui a identificação de hosts, máquinas virtuais, clusters e outros componentes relacionados à virtualização. Com essa capacidade, você pode acompanhar o inventário de ativos virtualizados e monitorar o desempenho e a utilização dos recursos em seu ambiente de virtualização.

### Ambientes de Container

O AIOPS também oferece suporte à descoberta de ambientes de container, como Docker e Kubernetes. Ele pode identificar os clusters, nós e os próprios containers em execução. Essa funcionalidade permite que você tenha visibilidade do inventário de ativos em ambientes de container, facilitando o gerenciamento e a monitoração de seus recursos de forma granular.

Com a descoberta de virtualização e ambientes de container, o AIOPS oferece uma visão completa de seus ativos de TI, incluindo equipamentos físicos, máquinas virtuais e containers. Isso permite uma gestão mais eficiente, uma melhor utilização de recursos e a identificação rápida de possíveis problemas nessas camadas de virtualização.

## Identificação de Aplicações e Bancos de Dados

Além da descoberta de equipamentos de rede, máquinas de usuários finais, sistemas operacionais e virtualização, o AIOPS também oferece recursos avançados de descoberta de aplicações e bancos de dados através de retroalimentação com o Divedot. Essa funcionalidade abrangente permite que você tenha visibilidade e controle sobre suas aplicações e recursos de banco de dados em sua infraestrutura de TI.

### Aplicações

O AIOPS é capaz de identificar as aplicações em seu ambiente de TI. Ele pode detectar automaticamente as aplicações instaladas em seu ambiente, fornecendo informações detalhadas sobre os sistemas, versões e configurações. Com essa funcionalidade, você pode gerenciar e monitorar suas aplicações de forma eficiente, identificando possíveis problemas, analisando a utilização de recursos e garantindo a conformidade com as políticas da organização, sendo posssível identificar  identificar webservices, endpoints, rotinas e outros recursos específicos das aplicações. Isso permite uma visão mais completa e detalhada do ecossistema.

Além disso, o AIOPS pode rastrear rotinas e recursos específicos das aplicações, permitindo que você entenda melhor a estrutura e o funcionamento interno de suas aplicações. Isso inclui a identificação de bibliotecas, classes, funções e stacks de erros e outros elementos relacionados às suas aplicações.

### Bancos de Dados

O AIOPS oferece recursos avançados para a descoberta de bancos de dados em sua infraestrutura de TI. Ele pode identificar diferentes tipos de bancos de dados, como Oracle, MySQL, Microsoft SQL Server, PostgreSQL, MongoDB, entre outros. O AIOPS fornece informações detalhadas sobre os bancos de dados encontrados, incluindo versões, configurações, tamanhos e estatísticas de desempenho. Com essa funcionalidade, você pode gerenciar e monitorar seus bancos de dados de forma eficaz, otimizando o desempenho, garantindo a segurança dos dados e facilitando a administração de suas bases de dados.

[title] O que é AIOPS?
[path] Introdução/

*AIOPS* é uma plataforma de IPM (Infrastructure Performance Monitoring), NPM (Network Performance Monitoring), APM (Application Performance Monitoring) e Orquestração (por Low Code – Drag & Drop de Componentes) – Tudo gerenciado por IA, desenvolvida e criada pela empresa Citsmart, que fornece uma visão 360º de toda a unidade de um datacenter (on-premises, nuvem ou híbrida).

Gerencia ativamente eventos e incidentes de monitoramento, e executa automações através da base de conhecimento acionável, topologia automática e auto recuperação de um ambiente ou equipamento.&#x20;

Através do AIOPS os ruídos podem ser cortados facilmente, a captura de alertas de diferentes fontes passa a ser simples e com poucos recursos é possível atuar rapidamente sobre os incidentes, escalando exponencialmente os seus níveis de serviços.&#x20;

Acompanhe em tempo real a saúde digital do seu ambiente de TI através de infográficos, gráficos e painéis, alertas e notificações, tudo isso composto por automação de fluxo de trabalho (Pipes).

## Como funciona

- **Alertas** – Eventos e Alertas são a base da atuação do AIOPS no monitoramento de sua operação, permitindo o tratamento de eventuais problemas de acordo com os seus processos, podendo ser gerados com base em triggers próprias (configuráveis por script), ou captados de quaisquer fontes geradoras de alertas (third party, logs, eventos de sistema, redes, etc), existentes em sua operação.

- **Correlações** – Dinamicamente, o AIOPS reune os alertas relacionados em um incidente de alto nível, reduzindo ruídos e melhorando a visibilidade entre diferentes áreas da infraestrutura. A inteligência artificial do AIOPS aprimora diariamente suas correlações, automaticamente.&#x20;

- **RCA – Root Cause Analysis** – O motor de aprendizado do AIOPS aprenderá com os eventos e sua infraestrutura a causalidade de cada um e informará nos próximos alertas o Índice PRC (Possible Root Cause). Esta classificação automática com base em IA ajudará sua equipe na resolução dos incidentes.

- **Enriquecimento** – O AIOPS permite o enriquecimento de informação contextual, melhorando a correlação entre alertas e facilitando a investigação/resolução do incidente.

- **Canais** – Crie visões customizadas dos incidentes organizando-os por assunto, items de configuração, equipes, prioridade, etc. Utilize os canais para realizar a abertura automática de ticket (smart ticketing) e/ou compartilhamento automático.

- **Compartilhamento** - Notifique membros importantes de uma equipe e/ou escale os incidentes através de outras ferramentas, como ITSM, ferramentas de colaboração e mensageiros como slack/whatsapp/sms, etc.

- **CMDB** – O Gerenciamento de configuração do AIOPS permite realizar o mapeamento autônomo de todos os seus Items de Configuração (ICs).
  Topologia - Visualize todos os ICs, incluindo dependências, métricas, capacidade e status, organizando-os em grupos seja por natureza, estrutura organizacional, posicionamento geográfico, etc.

- **Pipes** -  Transforme a sua visão sobre base de conhecimento, utilizando a base de conhecimento acionável do AIOPS, os Pipes, com essa funcionalidade é possível acionar automaticamente diferentes ações com base em todas as informações da sua infra-estrutura.



- **Divedot\_Agent&#x20;**– Com o Divedot\_Agent aumentamos o desempenho e diminuímos a instabilidade de seus aplicativos através da instrumentação em bytecode.&#x20;

De forma automática realizamos a instrumentação de bytecode para garantir que todos os aplicativos do ambiente sejam monitorados sem a necessidade de um especialista na linguagem das aplicações.

O Agent captura os eventos quando eles ocorrem na aplicação, evitando a perda de dados importantes quanto a problemas relacionados a desempenho na aplicação. Evitando a coleta de lixo em um monitoramento critico.

Dados historicos mantidos de acordo com a criticidade do cliente de forma simples e sem onerar o ambiente funcional do Sistema.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/I5DofkaBXUwS1Ulj45_eU_image.png)

## Aplicações

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/LXzzg6IaReYxFdKDOYRuG_image.png)

## Integrações&#x20;

Integre quaisquer fontes de alertas que você possui com o AIOps, é possível enviar alertas correlacionados, ou eventos isolados, o AIOps é resiliente e pode se adequar a sua realidade,

Com os Pipes, você pode integrar com diferentes ferramentas para atuar de acordo com suas necessidades, automatizando atividades que geram problemas recorrentes para a sua operação.

Permitimos integrações nativas com ferramentas para captura de rede (netflow, sflow, snmp), aplicações (traces, rum, métricas de performance), banco de dados, topologia, mudanças, o que categoriza o AIOps como ferramenta central aos domínios de sua aplicação.

## Preferências

Conhecendo melhor o AIOps, é importante saber que todas as funcionalidades citadas são configuráveis, de acordo com suas preferências, desde a correlação de eventos até o CMDB.

- **Correlações** – Construa incidentes com o AIOps, seja de forma autônoma ou semi-autônoma, usufruindo do conceito de aprendizado de máquina "caixa aberta", é possível que se realize ajustes nas correlações identificadas pelo AIOps, de diferentes formas, seja nas regras que são seguidas ou movendo-se os alertas existentes.

- **Smart ticketing** – Enriqueça e sincronize os dados de incidentes em tempo real, e, caso seja necessário, envie automaticamente esses incidentes para a sua ferramenta de ticket/colaboração.

- **CMDB** – Atue sobre quaisquer dimensões do seu CMDB, configurando quaisquer parâmetros necessários, seja para descoberta ou para topologia.

- **Serviços** – Configure os seus serviços em alto nível, agrupando quaisquer itens da sua operação para acompanhamento dos níveis de serviço

- **Canais** – Parametrize os seus canais de incidentes, de acordo com as suas equipes, ou quaisquer atributos que compõem os alertas/incidentes, possibilitando limitar a visualização dos usuários de acordo com os canais onde o mesmo possui acesso.

- **Topologia** - Mapeie e organize a sua topologia de rede, de acordo com sua estrutura organizacional, grupos de itens, região geográfica, etc. Com o AIOps é possível visualizar em tempo real todos os aspectos de sua operação.

- **Interface** - O AIOps possibilita a personalização e disposição das informações de acordo com o perfil do usuário autenticado. Possibilitando a criação de painéis com campos customizados, modelos padrões e dashboards customizas através de gráficos em forma de tabela, planilhas, pizza, entre outros tipos.
  Acompanhe em tempo real a saúde digital do seu ambiente de TI através de infográficos, gráficos e painéis, alertas e notificações, tudo isso composto por automação de fluxo de trabalho (Pipes) e realizando integração do sistema com o seu legado através da orquestração de serviços e sistemas.

## Explore

Recomendamos explorar todas as funcionalidades e recursos que o AIOps oferece, desta forma, será possível impactar e transformar completamente toda a sua Operação de TI, priorizando eficiência através da inteligência.

## Suporte

Somos uma empresa brasileira voltados para a criação de software de código proprietário e estamos completamente comprometidos em ajudar nossos clientes com as ferramentas e informações necessárias para obtenção de sucesso em sua operação. Disponibilizamos atendimento e suporte customizado através de nossa equipe de *Customer Success*.&#x20;

Você pode nos enviar mensagens dentro da aplicação, utilizar a documentação e FAQs para solução de problemas, e claro, entrar em contato conosco nos principais canais de atendimento sempre que desejar.&#x20;

O AIOps é uma ferramenta WEB podendo ser utilizada nos seguintes navegadores:

- Internet Explorer >= 9.0
- Mozilla Firefox >= 24.0
- Chrome >= 18.0

Confira mais informações na seção *Requisitos do Sistema*.

## Idioma

O AIOps tem suporte as linguagens inglesa e portuguesa nativa:

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/AjP29zcEm5KKuTEYQd9AF_image.png)

# Backups&#x20;

O AIOps possui rotinas automatizadas de backup, garantindo assim a capacidade de recuperação a desastres seja a nível de base de dados, usuários, configurações e métricas que permeiam toda a plataforma do AIOps.

# Auditlog

O AIOps possui por padrão, funcionalidade de mensageria que permite a auditoria e acompanhamento das informações de todos os eventos que acontecem no escopo de toda a plataforma, contemplando usuários, configurações, alterações em registros e métricas (*Habilitar a configuração do audit na master-node*).&#x20;

# Controle e Proteção contra Vulnerabilidades

O AIOps implementa diversas medidas para gerenciar e mitigar riscos de segurança, com foco em proteção contra vulnerabilidades, envolvendo a implementação de barreiras e práticas para prevenir explorações e ataques a potenciais fraquezas no sistema, dentre elas:


Padrão de Critpgrafia de Dados (DES 128 Bits).
Configuração Incorreta de Segurança.
Exposição de Dados Sensíveis.
Injeção de código.
Quebra de autenticação.
Utilização de Componentes Vulneráveis Conhecidos.
Redirecionamentos e Encaminhamentos Inválidos.
Falta de Função para Controle do Nível de Acesso.
Gerenciamento de Sessão.
Cross-Site Scripting (XSS).
Referência Insegura e Direta a Objetos.
Cross-Site Request Forgery (CSRF).

# Criptografia

O AIOps utiliza protocolos remotos para a captura de transações. Por padrão, utilizamos a comunicação HTTPS (SSL)  para requisições web e é possível alternar o protocolo para HTTP não seguro manualmente por meio dos arquivos de configuração, a critério do cliente.
Para as automações e comunicação via agent, o AIOps utiliza o protocolo GRPC e não transporta dados/scripts executáveis,   é responsável por receber informações de sensores binários, healthcheck e automação.

### Layer de storage de informações sensíveis


Os usuário do AIOps possuem todos os dados sensíveis salvos em um banco de dados comportando senhas criptografadas.

Essas informações confidenciais são criptografadas usando criptografia Triple-DES. A chave usada para criptografia é exclusiva para cada usuário, garantindo que os dados não possam ser descriptografados por um usuário diferente e uma máquina diferente.

**Criptografia: Symmetric Triple-DES (168 bits)**

DES triplo é o nome da cifra de bloco do algoritmo de criptografia triplo de dados (um algoritmo determinístico operando em grupos de bits de comprimento fixo) que aplica o algoritmo de cifra Padrão de criptografia de dados (DES) três vezes a cada bloco de dados.

[title] Descoberta
[path] AIOps/

# Versionamento e Comparação de Mapas de Relacionamento na CMDB

A plataforma Citsmart permite que os mapas de relacionamento criados dentro da CMDB sejam não apenas visualizados em tempo real, mas também salvos como versões históricas, possibilitando a comparação entre diferentes momentos da topologia de rede.

Funcionalidades incluídas:

- Visualização gráfica do mapa de relacionamentos com os Itens de Configuração (ICs) e suas dependências;
- Salvamento de versões do mapa, com data e contexto de criação;
- Comparação entre versões anteriores e atuais, permitindo identificar mudanças estruturais, adições, remoções ou alterações nos vínculos;
- Registro de alterações manuais ou automáticas (via AIOps), garantindo rastreabilidade completa.

Benefícios:

- Rastreabilidade histórica da infraestrutura: permite entender como a topologia evoluiu ao longo do tempo e qual era o estado da rede em momentos críticos (como antes de uma falha ou mudança significativa);
- Suporte à análise de impacto e diagnóstico de incidentes com base na topologia vigente à época;
- Auxílio na governança e conformidade do CMDB, promovendo controle e documentação contínua da configuração dos ativos.

:::hint{type="info"}
**Importante:** O versionamento do mapa é uma ferramenta essencial para administradores do CMDB que buscam manter a consistência, confiabilidade e visibilidade temporal da arquitetura de TI.
:::


[title] Monitoramento de Recursos de Pods
[path] Métrica/Coletas customizadas/Monitoramento Kubernetes com Telegraf Operator/

Configurando monitoramento de recursos do Kubernetes

O monitoramento de recursos do Kubernetes com o Telegraf requer algumas configurações específicas para garantir que o Telegraf tenha permissão para acessar e coletar dados dos pods.

## **Criar ou fazer mudanças em uma autorização token para o API kubelet:**

Para isso, siga as instruções abaixo e adicione as seguintes configurações no arquivo **dev.yml** do telegraf-operator:

:::hint{type="warning"}
Caso não use o arquivo **dev.yml&#x20;**&#x20;criar a propria **ClusterRole** baseada nos arquivos yml abaixo:
:::

### **ClusterRoleBinding yaml:**

Este arquivo cria um ClusterRoleBinding chamado **telegraf-operator** que vincula o Service Account **telegraf-operator** ao ClusterRole **cluster-admin**, concedendo permissões administrativas em todo o cluster.&#x20;

:::hint{type="danger"}
O nome **cluster-admin** não pode ser alterado, pois se refere a um ClusterRole padrão no Kubernetes.
:::



:::CodeblockTabs
dev.yml

```yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: telegraf-operator
  labels:
    app: telegraf-operator
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: cluster-admin
subjects:
  - kind: ServiceAccount
    name: telegraf-operator
    namespace: telegraf-operator

```
:::

### **Secret yaml:**

Este arquivo cria um Secret chamado **telegraf-operator-certs** que contém o token de acesso para o Service Account **telegraf-operator**, permitindo que o Telegraf autentique-se no kubelet e colete dados de monitoramento dos pods.


:::CodeblockTabs
dev.yml

```yaml
apiVersion: v1
kind: Secret
metadata:
  name: telegraf-operator-certs
  namespace: telegraf-operator
  annotations:
    kubernetes.io/service-account.name: telegraf-operator
data:
  tls.crt:
  .....
  tls.key:
  .....
type: kubernetes.io/service-account-token

```
:::

### **Comando para pegar o Token criado a partir do secret a cima:**

Após aplicar as configurações acima, você pode usar o seguinte comando para obter o token criado a partir do secret:

:::CodeblockTabs
command

```linux
TOKEN=$(kubectl get secret telegraf-operator-certs -n telegraf-operator -o jsonpath='{.data.token}' | base64 --decode)

```
:::

Esse token será usado para configurar o Telegraf para acessar o kubelet e coletar os dados de monitoramento dos pods. Dessa forma:

### **Editar o arquivo classes.yml:**

Adicione \[\[inputs.kubernetes]] dentro da classe usada. Coloque o ip do node, o token gerado acima e o parametro para pular a verificação de segurança se necessário.

:::CodeblockTabs
classes.yml

```linux
[[inputs.kubernetes]]
      url = "https://node-ip:10250"
      bearer_token_string = "<RESULTADO-DE-$TOKEN>"
      insecure_skip_verify = true
```
:::


[title] Usuários
[path] AIOps/


[title] Incidente
[path] AIOps/


[title] Requisitos
[path] Visão Geral do Sistema/


[title] Exportar Metricas do Istio
[path] Métrica/Coletas customizadas/Monitoramento Kubernetes com Telegraf Operator/

Essa documentação fornece uma visão de como configurar a exportação de métricas de um cluster com Istio via Prometheus.

## Pré requisitos

- Verifique o melhor método para instalar o Istio no seu ambiente e siga uma das duas formas de instalação: :Link[ambient mode]{href="https://istio.io/latest/docs/ambient/" newTab="true" hasDisabledNofollow="false"} ou :Link[sidecar mode]{href="https://istio.io/latest/docs/setup/" newTab="true" hasDisabledNofollow="false"}. Se quiser saber mais sobre os métodos de instalação leia :Link["sidecar ou ambient mode?"]{href="https://istio.io/latest/docs/overview/dataplane-modes/" newTab="true" hasDisabledNofollow="false"} e também :Link["qual método devo usar?"]{href="https://istio.io/latest/about/faq/#install-method-selection" newTab="true" hasDisabledNofollow="false"}.
- Ter instalado o **prometheus** no cluster. A melhor maneira é usar os arquivos de implantação fornecidos pelo Istio como é mostrado neste :Link[link]{href="https://istio.io/latest/docs/ambient/getting-started/secure-and-visualize/#add-bookinfo-to-the-mesh" newTab="true" hasDisabledNofollow="false"}. Instalar o Kilai é opcional.
- Se instalado pelo "sidecar mode" adicionar os sidecars nos pods colocando as labels nos namespaces desejados: "**istio-injection=enabled**". Siga essas :Link[instruções]{href="https://istio.io/latest/docs/setup/additional-setup/sidecar-injection/" newTab="true" hasDisabledNofollow="false"}.

:::hint{type="info"}
Lembre-se de instalar o CLI do Istio e também o **Gateway API CRDs** como mostrado neste :Link[link]{href="https://istio.io/latest/docs/ambient/getting-started/" newTab="true" hasDisabledNofollow="false"}.

Rode o comando "rollout" nos pods para a injeçãos dos sidecars.
:::

:::hint{type="warning"}
Por segurança adicionar mTLS authentication ou outro tipo de autenticação como explicado nesse :Link[link]{href="https://istio.io/latest/docs/tasks/security/authentication/" newTab="true" hasDisabledNofollow="false"}.
:::

## **Adicionando anotações ao Istio Ingress Gateway e Pilot**

Crie ou edite um recurso **IstioOperator** para incluir as anotações necessárias. As anotações devem ser adicionadas tanto ao **ingressGateway** quanto ao **pilot** para que o Prometheus possa coletar métricas corretamente como mostrado abaixo:

:::CodeblockTabs
yaml

```yaml
apiVersion: install.istio.io/v1alpha1
kind: IstioOperator
metadata:
  namespace: istio-system
  name: istio-operator
spec:
  profile: default
  components:
    pilot:
      k8s:
        podAnnotations:
          prometheus.io/port: "15014"
          prometheus.io/scrape: "true"
          prometheus.io/path: "/metrics"
    ingressGateways:
    - name: istio-ingressgateway
      enabled: true
      k8s:
        podAnnotations:
          prometheus.io/port: "15090"
          prometheus.io/scrape: "true"
          prometheus.io/path: "/stats/prometheus"
  values:
    gateways:
      istio-egressgateway:
        enabled: false
```
:::

O proxy sidecar do Istio (geralmente Envoy) expõe métricas na porta **15090** e no caminho **'/stats/prometheus'**.

Aplique o recurso:

:::CodeblockTabs
bash

```linux
istioctl manifest apply -f istio-operator.yaml
```
:::

### **Atualizar a configuração do Prometheus:**

Edite o ConfigMap do Prometheus para adicionar a URL de **remote\_write.** Isso indicará ao Prometheus onde enviar as métricas:

:::CodeblockTabs
bash

```yaml
kubectl edit cm prometheus -n istio-system
```
:::

Adicionar na mesma indentaç ão de "global" o `remote_write`:

:::CodeblockTabs
yaml

```yaml
global:
  scrape_interval: 15s
remote_write:
  - url: http://<AIOPS-VMETRICS-IP>:8428/api/v1/write
```
:::

Substitua **\<AIOPS-VMETRICS-IP>** pelo endereço IP ou hostname para receber as métricas.

### Reiniciar o Servidor Prometheus

Após feita as alterações, é necessário reiniciar o deployment do Prometheus para que as novas configurações sejam aplicadas:

:::CodeblockTabs
bash

```linux
kubectl rollout restart deployment/prometheus -n istio-system
```
:::


[title] Correlação de eventos
[path] AIOps/Incidente/

Correlação é um método de agrupamento de alertas relacionados em um Incidente de alto nível.&#x20;

O AIOPS utiliza o reconhecimento de padrões para automaticamente processar os dados de eventos recebidos de diferentes fontes, seja logs, métricas ou integrações. Sendo assim, é possível agrupar eventos em contextos similares, possibilitando a redução de ruídos e uma detecção rápida da real demanda em questão.&#x20;

Com os dados detectados e com os padrões processados, o AIOPS é capaz de processar e predizer com um evento deve se correlacionar com o outro.

![](https://gblobscdn.gitbook.com/assets%2F-Ls76-8XbGuboSQAg3Y9%2F-LsHo9EPusLTuvY-Zy-k%2F-LsHoyjUHz6IMB9sJc7U%2FPage-003A.png?alt=media\&token=04092b37-f950-424f-8ef2-c900f8df84df)

Contextualização:

![](https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/X4AGvldoAUoTpoEXHWmr4_Screen%20Shot%202021-01-09%20at%2016.15.11.png)

## Movimentação de Alertas

Para a movimentação de alertas, basta clicar no botão que se encontra no canto superior direito da tela.

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/uH8v0Qk87r5sDCl-nl3Iy_Screen%20Shot%202021-01-09%20at%2016.17.48.png" size="30" caption position="center" signedSrc="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/uH8v0Qk87r5sDCl-nl3Iy_Screen%20Shot%202021-01-09%20at%2016.17.48.png?AWSAccessKeyId=AKIAYQNQCIXNIQWBC56C&Expires=1697892634&Signature=pC0hwsl9xjK1dQUEnjdNMti5ngU%3D"}

Após o acesso é necessário a seleção do alerta desejado seguida por um clique no botão **mover** **alertas,&#x20;**&#x70;resente logo acima e à esquerda da lista de alertas.

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/NyDOHs4iKwqJYgtkDfDqE_Screen%20Shot%202021-01-09%20at%2016.44.08.png" size="34" caption position="center" signedSrc="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/NyDOHs4iKwqJYgtkDfDqE_Screen%20Shot%202021-01-09%20at%2016.44.08.png?AWSAccessKeyId=AKIAYQNQCIXNIQWBC56C&Expires=1697892634&Signature=idx9A1qT%2F0ScliUxiP9j%2FGujQY0%3D"}

![](https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/K3y_7TAsXCgwP6oDp7OwV_Screen%20Shot%202021-01-09%20at%2016.42.05.png)

Em seguida estará disponível um modal com as informações necessárias para a movimentação:

![](https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/zkRC0L9BE29gg4874uZdb_Screen%20Shot%202021-01-09%20at%2016.48.33.png)

Season ID é o número identificador de um incidente, estará sempre próximo à prioridade (P). Na imagem abaixo, representa o exemplo P1, a letra **P** poderá ser acompanhada pelos números 1,2,3,4 e 5 indicando a prioridade do problema. Números menores exigem atuações de urgência.

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/0cJl-7Bty5JfTJMz9iDWb_Screen%20Shot%202021-01-09%20at%2017.00.48.png" size="10" caption position="center" signedSrc="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/0cJl-7Bty5JfTJMz9iDWb_Screen%20Shot%202021-01-09%20at%2017.00.48.png?AWSAccessKeyId=AKIAYQNQCIXNIQWBC56C&Expires=1697892634&Signature=L%2FR9uj0esMHl4IkhrwvaBddC9cw%3D"}

Conforme relatado acima, todos os incidentes possuem um número identificador( Season ID). Para movimentar o alerta escolhido, basta selecionar o Season ID do incidente desejado que se encontra na coluna lateral à direita da tela.&#x20;

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/zb-T3GgDTK5nHkeI0v4EK_Screen%20Shot%202021-01-09%20at%2017.16.15.png" size="26" caption position="center" signedSrc="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/zb-T3GgDTK5nHkeI0v4EK_Screen%20Shot%202021-01-09%20at%2017.16.15.png?AWSAccessKeyId=AKIAYQNQCIXNIQWBC56C&Expires=1697892634&Signature=yW8YeWEQ0L1DLadzRVHZIlV3LOw%3D"}

No botão **Sugerir pipe** que se encontra ao lado do botão Mover Alertas é possível escolher o fluxo de automação (:Link[Pipes e Automação]{href="https://docs.citsmart.com/aiops/pipes-e-automacao" newTab="true" hasDisabledNofollow="false"}) mais indicado para o alerta selecionado

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/2y2DhcjFkIj96PjbrnyJJ_Screen%20Shot%202021-01-09%20at%2017.38.14.png" size="24" caption position="center" signedSrc="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/2y2DhcjFkIj96PjbrnyJJ_Screen%20Shot%202021-01-09%20at%2017.38.14.png?AWSAccessKeyId=AKIAYQNQCIXNIQWBC56C&Expires=1697892634&Signature=9NYGA0Zjp%2FENltF7J%2FvGzeWC2gM%3D"}

Caso o incidente esteja agrupado adequadamente é possível habilita-lo para treino uilizando o botão como o exemplo abaixo, que se encontra no canto superior direito da tela, acima da lista de alertas. A cada movimentação de alertas o AIOPS aprende via reinforcement learning a ser cada vez mais assertivos nas correlações que acontecem no ambiente.

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/MHUgmjK6dR8l6Ds367C5F_Screen%20Shot%202021-01-09%20at%2017.41.19.png" size="40" caption position="center" signedSrc="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/MHUgmjK6dR8l6Ds367C5F_Screen%20Shot%202021-01-09%20at%2017.41.19.png?AWSAccessKeyId=AKIAYQNQCIXNIQWBC56C&Expires=1697892634&Signature=tDf26kWAwOH30BEUUl5TPw3bpF8%3D"}

Ao selecionar essa opção permitirá que o AIOPS se torne cada vez mais assertivo na identificação de padrões.

[title] Requisitos de Hardware
[path] Visão Geral do Sistema/Requisitos/



- O AIOPS pode ser instalado tanto em ambiente *On Premise* ou *Virtual Appliance*.

## Recomendação

### Standalone (POC):

Requisitos mínimos para uma única máquina rodando em Singlenode.

| **Tamanho** | Cores (CPU) | Memória  | Disco   |
| ----------- | ----------- | -------- | ------- |
| Micro       | 4           | 8GB      | 100 GB  |
| Small       | 8           | 24 GB    | 200 GB  |
| Medium      | 16          | 32GB     | 400 GB  |
| Large       | 24          | 32 GB    | 1024 GB |

### Distribuído (Produtivo):

Requisitos mínimos (1 máquina de cada tipo), com excessão das opcionais que vão de acordo com o tipo de contrato.

| **Tipo de Instância&#x20;** | **Cores** (CPU) | **Memória**  | **Disco** (dados) | -                                                                       |
| --------------------------- | --------------- | ------------ | ----------------- | ----------------------------------------------------------------------- |
| 1. MASTER-NODE              | 8               | 16 GB        | 200 GB            | ***obrigatório***                                                       |
| 2. DB-WORKER                | 8               | 16 GB        | 500 GB            | ***obrigatório***                                                       |
| 3. ATOM-WORKER              | 4               | 8 GB         | 50 GB             | *opcional* (se utilizar:&#xA;SNMP, Ping, &#xA;Descoberta de Rede, etc.) |
| 4. APM-WORKER               | 8               | 8 GB         | 1024 GB           | *opcional&#x20;*(se utilizar: APM)                                      |

### Dimensionamento - APM Worker

Para melhor dimensionar os recursos, calcular a média de usuários das aplicações monitoradas (incluindo o RUM) determinando a quantidade de conexões por minuto que o servidor irá receber.

| **Pico de conexões / minuto** | **CPU** (vCpus) | **Memória**  | **Disco** (/dados) |
| ----------------------------- | --------------- | ------------ | ------------------ |
| 0-25.000                      | 8               | 16 GB        | 300 GB (mínimo)    |
| 50.000                        | 16              | 24 GB        | 500 GB (mínimo)    |
| 100.000                       | 24              | 32 GB        | 1024 GB (mínimo)   |
| 200.000                       | 32              | 64 GB        | 2048 GB (mínimo)   |

Os valores de CPU, Memória e Disco poderão variar de acordo com o hardware utilizado.

### Pontos de montagem

Os discos são montados através dos seguintes requisitos:

| **Ponto de montagem** | **Tamanho mínimo**                         |
| --------------------- | ------------------------------------------ |
| /                     | 30GB                                       |
| /tmp, /opt            | 4GB (ou equivalente ao root "/" )          |
| /dados                | *(de acordo com o tipo de instância)*&#xA; |

:::hint{type="danger"}
Antes de iniciar a instalação, certifique-se se o ponto de volume **/dados** já esteja montado, caso contrário a instalação será realizada na partição raiz "/".
:::

:::hint{type="warning"}
Embora seja possível utilizar o disco de dados em **NFS (Network File System)&#x20;**&#x6E;ão é recomendado para o volume dos containeres docker (/var/lib/docker).
:::


[title] Eventos e Incidentes
[path] AIOps/Dashboard/

Monitore os seus eventos, fornecendo à sua equipe de operações uma visão histórica da saúde operacional, contemplando os itens mais recorrentes para atuação preventiva com o objetivo de redução de problemas.

## Visualizando seus dados de eventos e coleções

Para acessar a dashboard de eventos e incidentes é necessário acessar o seguinte botão no menu principal (lateral esquerda):

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/L_Zue1OMMhCNRxMkO-YXt_dashboard-eventos.png" size="16" caption position="flex-start" signedSrc="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/L_Zue1OMMhCNRxMkO-YXt_dashboard-eventos.png?AWSAccessKeyId=AKIAYQNQCIXNIQWBC56C&Expires=1697895924&Signature=%2BF2Bu699kl%2BPFhZjBr0GQxaJCn0%3D"}

## Informações disponíveis

- Eventos mais reincidentes por host e por categoria

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/qpr-FybYVVmqbebYaBDz_/-SGupecFU5NtXLA0U7uQ8_image.png" signedSrc size="50" width="423" height="440" position="center" caption}

- Coleções e eventos diários&#x20;

![](https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/Y9Sh2EJ80BgYBYw-S51JD_collectionsxevents-dashboard.png)

- Redução de ruído

![](https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/QyCNGkSFnoot5zQiiRo_g_collectionsxevents-noise-dashboard.png)


[title] Real User Monitoring
[path] APM/

## Sessões

Através do divedot é possível acompanhar a sessão de um usuário final nas aplicações monitoradas, permitindo entender o caminho e informações consumidas por um usuário final, tais como:

- Tempo de cada sessão;
- Dados de Insight da rede e servidor da aplicação;
- Tempo de renderização e download da página web.&#x20;

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/kLGjb28pDqzEw3nDfl6fj_screen-shot-2021-06-17-at-192720.png "Sessão de usuário")

Com o Rum Session podemos acompanhar a experiência do usuário final em cada aplicação e ter os dados relevantes de acessos, tais como:

- Geolocalização de usuário;
- Navegador utilizado na sessão;
- Dispositivos utilizado;
- IP de cada sessão iniciada na aplicação;
- Duração e a média de tempo em cada ação tomada na sessão;
- As ações que cada usuário fez durante o acesso;
- Chamadas a serviços de terceiros com o período histórico;
- Histórico das sessões com dados de sucesso ou falha em cada acesso.

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/QLw3D9aBPxu--GNDprfFk_image.png)

## Auditoria


[title] Serviços
[path] Infraestrutura/

Gerencie seus serviços aglomerando servidores que possam estar próximos fisicamente, virtualmente ou em cloud, com mapas visuais que podem contemplar arquiteturas híbridas. Crie dependências de aplicações com recursos existentes de vários itens de configuração e organize hierarquicamente da melhor forma que represente seu ambiente. Podendo representar, serviços de alto nível, regiões, filiais, aplicações e etc.

Nesse local poderá ser verificado a disponibilidade dos serviços que podem ser afetadas por todos os itens de configuração que o suportam e estão mapeados e monitorados.

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/bLZR6pHKm08sSzle4qZUx_screen-shot-2021-06-16-at-172955.png)

## Acesso

Para acessar a aplicação Atmos é necessário clicar no botão "aplicações" localizado no canto inferior esquerdo, do menu principal no AIOPS.

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/_dl2iGnL-Fm4SOb1vBfhr_image.png" size="70" caption position="center" signedSrc="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/_dl2iGnL-Fm4SOb1vBfhr_image.png?AWSAccessKeyId=AKIAYQNQCIXNIQWBC56C&Expires=1697908309&Signature=bQvbxPqgUo%2FSQ%2FS7xs5MVli37u8%3D"}

Após acessar o Atmos é necessário acessar a tela de serviços de TI através do menu principal:

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/mwgPMZkrFEW7OOv-wL9c2_image.png" size="70" caption position="center" signedSrc="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/mwgPMZkrFEW7OOv-wL9c2_image.png?AWSAccessKeyId=AKIAYQNQCIXNIQWBC56C&Expires=1697908309&Signature=cfCB6RvkGPF4reLOuNiKNbJOzyo%3D"}

Ao acessar a tela de serviços de TI será possível ver a listagem de serviços criados:

![](https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/lz5xj6xYA33Tjd6z0x7Ub_image.png)

### Changelog

Através de changelog, o Atmos mantém em archives, todo o histórico de updates realizados em cada serviço, sendo possível auditar todas as mudanças realizas, observando quem foi o autor e as datas em que os eventos de criação, mudança e deleção aconteceram. 

### Topologia

Através do serviços de TI é possível filtrar a topologia ([Topologia](docId\:UFxgZ3HWR0lR8EyHa6-lf) ) de acordo com as dependências do usuário utilizando o botão de topologia que se encontra em cada item da listagem:

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/jjulfjIq9sBaWb3wLdGl6_servicos-filtro-topologia.png" size="36" caption position="center" signedSrc="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/jjulfjIq9sBaWb3wLdGl6_servicos-filtro-topologia.png?AWSAccessKeyId=AKIAYQNQCIXNIQWBC56C&Expires=1697908309&Signature=6dP6KWw3G%2FplPaGCd%2FsAb3kP6oI%3D"}

## Criando um novo serviço

Para criar um novo serviço é necessário clicar no botão "Novo serviço" que se encontra no topo lateral direito:&#x20;

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/9eEWHZ9Q7qrx9jjXPDI2a_image.png" size="44" caption position="center" signedSrc="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/9eEWHZ9Q7qrx9jjXPDI2a_image.png?AWSAccessKeyId=AKIAYQNQCIXNIQWBC56C&Expires=1697908309&Signature=FxdRmp7v0%2BJLCa8xerUxuvbOJK0%3D"}

Após o clique no botão, a tela de criação se apresentará:

![](https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/9OUGh0ARdV1HV4hJc2lHG_image.png "Tela para criação e edição de serviço")

### Configurações iniciais

Para configurar as informações básicas do serviço é necessário acessar o botão de configuração no topo superior direito:

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/8pnx52j27KoZRkgdXGXW2_image.png" size="34" caption position="center" signedSrc="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/8pnx52j27KoZRkgdXGXW2_image.png?AWSAccessKeyId=AKIAYQNQCIXNIQWBC56C&Expires=1697908309&Signature=18p1rAcXBQ5uH3zBy3NBlk%2FCvw4%3D"}

Após clicar nesse botão, um modal se abrirá com as seguintes informações:&#x20;

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/DuNYnh2YPKlsl2IuapOQ5_image.png" size="52" caption position="center" signedSrc="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/DuNYnh2YPKlsl2IuapOQ5_image.png?AWSAccessKeyId=AKIAYQNQCIXNIQWBC56C&Expires=1697908309&Signature=7HCuP6Gz8K%2BXqv9BEU7Y1mdrTBQ%3D"}

Onde é possível, definir o **nome do serviço&#x20;**, definir a **prioridade** que esse serviço possui e definir o **tempo de atividade** que esse serviço deve possuir para cálculos de SLA e uptime.

### Criando agrupamentos

Ao centro da tela é possível ver um botão com a seguinte característica:

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/tu626oJUWLbKnVKAWRX9o_image.png" size="44" caption="Adicionar grupo" position="center" signedSrc="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/tu626oJUWLbKnVKAWRX9o_image.png?AWSAccessKeyId=AKIAYQNQCIXNIQWBC56C&Expires=1697908309&Signature=gP2GrGUj%2F3eWaWnAjw1GCm4Lg4s%3D"}

Após apertar esse botão, automaticamente um novo grupo de itens de configuração será adicionado, o objetivo da criação de grupos é poder criar regras onde cada grupo impacte de forma independente o SLA do serviço em questão, além de organizar as dependências de forma simples e rápida.

Para configurar um novo grupo é necessário clicar no botão que possui três pontinhos:

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/uY_PRtPTUz61QyAWRhTWU_image.png" size="54" caption position="center" signedSrc="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/uY_PRtPTUz61QyAWRhTWU_image.png?AWSAccessKeyId=AKIAYQNQCIXNIQWBC56C&Expires=1697908309&Signature=tNBtJaOwI5G01PbtFKts1iaWPLY%3D"}

Então um modal se abrirá de seguinte forma:

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/FBB1ETz_m5cz5ZlDtlGQh_image.png" size="66" caption position="center" signedSrc="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/FBB1ETz_m5cz5ZlDtlGQh_image.png?AWSAccessKeyId=AKIAYQNQCIXNIQWBC56C&Expires=1697908309&Signature=ZAL6MaqCUmf14VlX%2BFp9f32PtMk%3D"}

Nesse modal é possível determinar:

- Nome
  - O nome do serviço em questão
- O SLA mínimo
  - &#x20;Definir qual o limite que pode ser atingido
- O tipo de SLA
  - &#x20;Define se o grupo em questão pode impactar o SLA do serviço, somente SLA do próprio grupo ou não causar nenhum impacto
- O impacto do SLA
  - Define se o SLA definido no tipo de SLA será impactado caso qualquer item tenha problema ou se apenas todos tiverem algum problema.
- Números de colunas que ocupará na tela
  - O tamanho do agrupamento que será visualizado na tela de visualização de serviços de TI

### Adicionando itens ao grupo

Após configurar o grupo, é possível começar a inserir os itens de configuração ou serviços já criados anteriormente que pertecem a esse grupo:

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/pwvrdMCOMPhmEG0XTMStB_image.png" size="48" caption position="center" signedSrc="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/pwvrdMCOMPhmEG0XTMStB_image.png?AWSAccessKeyId=AKIAYQNQCIXNIQWBC56C&Expires=1697908309&Signature=pQl8Xr6F%2B6sWBXBRxL5eAMFWqes%3D"}

### Definindo problemas que podem impactar o serviço

Ao inserir um item de configuração é possível definir qual problema (trigger acionada) pode impactar o SLA do serviço criado:&#x20;

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/eUN570r0WfJqtv9uJJ1DB_image.png" size="84" caption position="center" signedSrc="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/eUN570r0WfJqtv9uJJ1DB_image.png?AWSAccessKeyId=AKIAYQNQCIXNIQWBC56C&Expires=1697908309&Signature=NJRnxrbGowHr9XRj1xRlv7YvioM%3D"}

### Exemplo de serviço criado

Abaixo temos um exemplo de serviço criado representando uma aplicação, com os itens que compõe toda a pilha:

[title] Explorar as Métricas Base
[path] Métrica/

| **Grupo**                  | **Descrição**                                                                                                                                                                                  |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cpu`.                     | CPU – Métricas de CPU do sistema.                                                                                                                                                              |
| `disk`.                    | Disk – Métricas sobre o uso do disco.                                                                                                                                                          |
| `diskio`.                  | Disk IO – Métricas sobre o tráfego e o tempo do disco.                                                                                                                                         |
| `docker`.                  | Docker - Métricas sobre a execução de contêineres docker.                                                                                                                                      |
| `docker_container_blkio`.  | Docker Container Blkio - Monitora o acesso a I/O em dispositivos de bloco.                                                                                                                     |
| `docker_container_cpu`.    | Docker Container CPU - Métricas sobre as CPUs de um contêiner docker.                                                                                                                          |
| `docker_container_health`. | Docker Container Health - Monitora a integridade de um contêiner docker.                                                                                                                       |
| `docker_container_mem`.    | Docker Container Mem - Traz informações da memória utilizado pelo container docker.                                                                                                            |
| `docker_container_net`.    | Docker Container Net - Métricas sobre a rede de um contêiner docker.                                                                                                                           |
| `docker_container_status`. | Docker Container Status - Métricas sobre o estado de um container docker.                                                                                                                      |
| `docker_data`.             | Docker data - Informações sobre pool de armazenamento.                                                                                                                                         |
| `docker_devicemapper`.     | Docker Devicemapper - Mapeamento de dispositivos de bloco físicos em dispositivos virtuais de bloco de alto nível.                                                                             |
| `docker_metadata`.         | Docker metadata - Informações da metadata do docker.                                                                                                                                           |
| `health_check`.            | Health Check - Verificação de integridade simples.                                                                                                                                             |
| `http_request`.            | HTTP Request - Parâmetros importantes do protocolo HTTP e sua sintaxe na forma como são usados na comunicação.                                                                                 |
| `kernel`.                  | Kernel - Coleta métricas sobre o kernel.                                                                                                                                                       |
| `listen_process`.          | Listen Process - Informações de processos que estão com status de LISTEN.                                                                                                                      |
| `mem`.                     | Mem - Informações da memória utilizado.                                                                                                                                                        |
| `net`.                     | Net - Métricas sobre interface de rede e uso de protocolo.                                                                                                                                     |
| `netstat`.                 | Netstat - Ferramenta utilitária de rede de linha de comando que exibe conexões de rede para o Transmission Control Protocol (entrada e saída) e User Datagram Protocol (UDP).                  |
| `process`.                 | Process - Resumo (contadores) relacionadas aos processos do host.                                                                                                                              |
| `processes`.               | Processes - Informações relacionadas aos processos do host.                                                                                                                                    |
| `redis`.                   | Redis - Redis é um armazenamento de estrutura de dados em memória, usado como um banco de dados em memória distribuído de chave-valor, cache e agente de mensagens, com durabilidade opcional. |
| `redis_cmdstat`.           | Redis Cmd Stat - Estatísticas de comandos do Redis.                                                                                                                                            |
| `redis_keyspace`.          | Redis Key Space - Informações do dicionário interno gerenciado pelo Redis, no qual todas as chaves são armazenadas.                                                                            |
| `swap`.                    | Swap - Informações de memória swap.                                                                                                                                                            |
| `system`.                  | System - Estatísticas gerais sobre a carga do sistema, o tempo de atividade e o número de usuários conectados.                                                                                 |


[title] Criar API Token
[path] Métrica/Coletas customizadas/Monitoramento Kubernetes com Telegraf Operator/

## Introdução

Esta documentação descreve o processo para criar um token de API não expirável e persistente para uma ServiceAccount no Kubernetes, utilizando um Secret do tipo kubernetes.io/service-account-token. Esse método é útil quando o mecanismo de solicitação de token não é adequado, fornecendo tokens de longa duração.

:::hint{type="warning"}
Crie tokens de API de longa duração apenas se o mecanismo de solicitação de token não for adequado. O mecanismo de solicitação de token fornece tokens com tempo limitado; devido à sua expiração, representam um risco menor à segurança da informação.
:::

## Passos para Criar um Token de API Persistente

### 1. Criação de um Secret

Para criar um token de API não expirável para uma ServiceAccount, crie um Secret do tipo kubernetes.io/service-account-token com uma anotação referenciando a ServiceAccount. O plano de controle gerará um token de longa duração e atualizará o Secret com os dados do token gerado.

### 2. Manifesto de Exemplo

*Altere os campos&#x20;****my-serviceaccount****&#x20;e&#x20;****my-namespace&#x20;****para os valores de sua preferência.*

**Service Account:**

:::CodeblockTabs
yaml

```yaml
apiVersion: v1
kind: ServiceAccount
metadata:
  name: discovery
  namespace: default
```
:::

**Secret:**

:::CodeblockTabs
yaml

```yaml
apiVersion: v1
kind: Secret
type: kubernetes.io/service-account-token
metadata:
  name: discovery-token
  namespace: default
  annotations:
    kubernetes.io/service-account.name: discovery
```
:::

### 3. Crie um ClusterRole e um ClusterRoleBinding com permissões de READ para o Cluster:

**ClusterRole**:

Regra para somente ler no cluster os pods, services e deployments.

:::CodeblockTabs
yaml

```yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: read-cluster-discovery
rules:
  - apiGroups: ["", "*"]
    resources: ["*"]
    verbs: ["get", "list"]
```
:::

:::hint{type="info"}
Para realizar um gerenciamento eficaz do inventário em um ambiente Kubernetes, é necessário utilizar ConfigMaps e Secrets para estabelecer correlações entre os serviços. No entanto, o AIOPS não interpreta metadados, incluindo dados sensíveis, o que torna essencial a recuperação de ConfigMaps e Secrets para identificar e relacionar os recursos corretamente no cluster.

Ao extrair estas informações, é importante notar que as chaves armazenadas em Secrets não são expostas, garantindo a segurança dos dados sensíveis.
:::

**ClusterRoleBinding:**

O ClusterRoleBinding dá as regras criadas no ClusterRole para a ServiceAccount (my-serviceaccount) criada anteriomente.

:::CodeblockTabs
yaml

```yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: discovery
subjects:
- kind: ServiceAccount
  name: discovery
  namespace: default
  apiGroup: ""
roleRef:
  kind: ClusterRole
  name: read-cluster-discovery
  apiGroup: rbac.authorization.k8s.io
```
:::

E então o secret usado por essa ServiceAccount pode ser usado somente para ler o Cluster, como indicado em "**verbs: \["get"]**"

### 4. Verificação dos Detalhes do Secret

Para ver os detalhes do Secret criado, execute:

:::CodeblockTabs
command

```linux
kubectl -n my-namespace describe secret my-secretname
```
:::

### 5. Exemplo de Saída

A saída será semelhante a:

:::BlockQuote
Namespace:      my-namespace
Labels:         \<none>
Annotations:    kubernetes.io/service-account.name=my-serviceaccount
&#x20;               kubernetes.io/service-account.uid=8a85c4c4-8483-11e9-bc42-526af7764f64

Type:   kubernetes.io/service-account-token

Data
\====
ca.crt:         1362 bytes
namespace:      9 bytes
token:          \<TOKEN\_GERADO>
:::

### 6. Rode o seguinte comando mostrar o Token Gerado:

:::CodeblockTabs
Exemplo

```linux
kubectl get secret my-secretname -n my-namespace -o jsonpath='{.data.token}' | base64 --decode
```
:::

### 7. Rode o seguinte comando para validar o Token:

:::CodeblockTabs
command

```linux
curl -H "Authorization: Bearer <TOKEN>" -k https://<kubernetes-api-server>:16443/api/v1/nodes

```
:::


[title] Visualizar a porta da API do Cluster Kubernetes
[path] Métrica/Coletas customizadas/Monitoramento Kubernetes com Telegraf Operator/

### 1. Comando para Exibir a Configuração

Para visualizar a configuração atual do cluster, use o seguinte comando:

:::CodeblockTabs
command

```linux
kubectl config view
```
:::

### 2. Exemplo de Saída

A saída do comando kubectl config view será semelhante ao exemplo abaixo:

:::BlockQuote
apiVersion: v1
clusters:
\- cluster:
&#x20;   insecure-skip-tls-verify: true
&#x20;   server: https\://127.0.0.1:16443
&#x20; name: kubernetes-cluster
contexts:
\- context:
&#x20;   cluster: kubernetes-cluster
&#x20;   user: admin
&#x20; name: kubernetes
current-context: kubernetes
kind: Config
preferences: \{}
users:
\- name: admin
&#x20; user:
&#x20;   client-certificate-data: DATA+OMITTED
&#x20;   client-key-data: DATA+OMITTED
:::

Nesse caso a porta do servidor API Kubernetes é **16443**, assim, as integrações que requerem a informação usa-se o formato:

[title] Detalhamento de incidentes
[path] AIOps/Incidente/


[title] Listagem de incidentes
[path] AIOps/Incidente/

# Lista de incidentes

É possível acessar a tabela de incidentes clicando no botão abaixo:

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/N6fsaIMEqzQBQp8CacxFH_Screen%20Shot%202021-01-09%20at%2012.40.05.png" size="10" caption position="center" signedSrc="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/N6fsaIMEqzQBQp8CacxFH_Screen%20Shot%202021-01-09%20at%2012.40.05.png?AWSAccessKeyId=AKIAYQNQCIXNIQWBC56C&Expires=1697897272&Signature=Kd%2FGKk0xe83js6r6DdmWcVdv4GA%3D"}

&#x20;Que se encontra no menu principal, canto esquerdo superior da tela.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/qpr-FybYVVmqbebYaBDz_/2Vc30RWmALvcBbZCc6UH3_image.png" signedSrc size="10" width="61" height="277" position="center" caption}

Após executar essa operação, será apresentada uma listagem contemplando todos os incidentes que ocorreram em seu ambiente

![](https://archbee-image-uploads.s3.amazonaws.com/qpr-FybYVVmqbebYaBDz_/UPJaFTqRPynBtEeFQTohz_image.png)

## Canais

A plataforma permite a filtragem de (:Link[Canais]{href="https://docs.citsmart.com/aiops/canais" newTab="true" hasDisabledNofollow="false"}) conforme as configurações criadas pelo usuário, de acordo com as necessidades do seu ambiente.

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/j4UYAeiShDs0A9yTEqRbY_Screen%20Shot%202021-01-09%20at%2013.19.10.png" size="30" caption position="center" signedSrc="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/j4UYAeiShDs0A9yTEqRbY_Screen%20Shot%202021-01-09%20at%2013.19.10.png?AWSAccessKeyId=AKIAYQNQCIXNIQWBC56C&Expires=1697897272&Signature=JKw%2Fpqss83Q3HdwQU9LAh4ZlL8Y%3D"}

Ações como: Previsão de alertas, restauração de tela, pesquisa de eventos por datas específicas ou intervalo de tempo, filtros avançados e intervalo de atualização, poderão ser executadas no canto superior direito da tela no menu principal.

![](https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/SWur6naDmMDoWHWBk8h_o_Screen%20Shot%202021-01-09%20at%2013.21.28.png)

# Eventos

A **Tela de Eventos** proporciona uma **visão unificada e centralizada** de incidentes e problemas. Ela agrega informações de diversas fontes, incluindo **plataformas integradas**, **ambientes On-premise** e **Nuvem**.&#x20;

Nesta tela, o usuário pode:

- Visualizar todos os detalhes relevantes do incidente.
- Consultar as datas de início e resolução do evento.
- Identificar a origem de cada evento.
- Definir livremente a periodicidade para a exibição dos dados, adaptando a visão às suas necessidades de análise.

![](https://archbee-image-uploads.s3.amazonaws.com/qpr-FybYVVmqbebYaBDz_/TqjzVlZUSMkAynB2f1qub_image.png)


[title] Visão Geral do Sistema
[path] /


[title] Monitoramento CloudWatch
[path] Métrica/Coletas customizadas/

:Link[**Amazon CloudWatch**]{href="https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/WhatIsCloudWatch.html" newTab="true" hasDisabledNofollow="false"} monitora seus recursos Amazon Web Services (AWS) e aplicativos que você executa na AWS em tempo real. Use o destino AIOPS para encaminhar facilmente métricas de seus recursos AWS para o AIOPS usando o [Telegraf](https://www.influxdata.com/time-series-platform/telegraf/).

Este guia demonstra como:

- Usar o CloudWatch para coletar e rastrear métricas e enviá-las para o AIOPS usando o Telegraf
- Visualizar métricas em seu painel do AIOPS

### Pré-requisitos

1\. Identifique os :Link[serviços AWS que publicam métricas no CloudWatch e seus namespaces]{href="https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/aws-services-cloudwatch-metrics.html" newTab="true" hasDisabledNofollow="false"}. Use-os em sua configuração para coletar as métricas.

Nota: Os namespaces diferenciam maiúsculas de minúsculas.

### Configuração

1. Na aba Infraestrutura, acesse a tela de infraestrutura, localize a máquina para a qual você precisa coletar métricas e clique nela. Em seguida, vá para os três pontos, conforme mostrado na imagem, e selecione a opção "Configuração do Agent".


![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/m8Kor9IYGeeD4XacHo3sV_image.png)

2\. Um editor de texto será aberto, no qual você deve adicionar essas configurações de acordo com suas necessidades.

Nota: Saiba mais sobre diferentes atributos disponíveis para o plugin de entrada de estatísticas do CloudWatch :Link[aqui]{href="https://github.com/influxdata/telegraf/tree/master/plugins/inputs/cloudwatch" newTab="true" hasDisabledNofollow="false"}.

```yaml
################################################# ############################
# EXEMPLO DE CONFIGURAÇÃO DE PLUGIN #
################################################# ############################

# Configuração para envio de métricas para o Atmos
[[inputs.cloudwatch]]
  region = "us-east-1"
  
  access_key = ""
  secret_key = ""
  
  # token = ""
  # role_arn = ""
  # web_identity_token_file = ""
  # role_session_name = ""
  # profile = ""
  # shared_credential_file = ""

  # include_linked_accounts = false
  
  # endpoint_url = ""

  ## Set http_proxy
  # use_system_proxy = false
  # http_proxy_url = "http://localhost:8888"

  period = "5m"
  delay = "5m"
  interval = "5m"

  # cache_ttl = "1h"

  namespaces = ["AWS/ELB"]

  # ratelimit = 25
  # timeout = "5s"
  # batch_size = 500

  # statistic_include = ["average", "sum", "minimum", "maximum", sample_count"]
  # statistic_exclude = []
```

Para enviar seus dados para o AIOPS, você precisa declarar as seguintes variáveis em sua configuração:

- **private\_key**: Sua chave é registrada no arquivo de substituição como um segredo para garantir que essa informação sensível permaneça protegida e não exposta.
- **application** e **subsystem**: Personalize e organize seus dados em seu painel usando nomes de aplicativos e subsistemas.

3\. Se desejar adicionar dimensões adicionais às suas métricas do CloudWatch, adicione-as na seção global\_tags de sua configuração, conforme o exemplo abaixo.

:::CodeblockTabs
yml

```yaml
[global_tags]
  dc = "us-east-2"
  user = "$USER"
  env = "CoE"
```
:::

4\. Salve o arquivo de configuração e aguarde o agent iniciar a coleta. Agora você poderá ver suas métricas em seu painel do AIOPS.

## Solução de problemas

Você pode usar o aws cli para obter uma lista de métricas e dimensões disponíveis:

:::BlockQuote
aws cloudwatch list-metrics --namespace AWS/EC2 --region us-east-1
aws cloudwatch list-metrics --namespace AWS/EC2 --region us-east-1 --metric-name CPUCreditBalance
:::

Se as métricas esperadas não forem retornadas, você poderá tentar obtê-las manualmente por um curto período de tempo:

:::BlockQuote
aws cloudwatch get-metric-data \\
&#x20; \--start-time 2018-07-01T00:00:00Z \\
&#x20; \--end-time 2018-07-01T00:15:00Z \\
&#x20; \--metric-data-queries '\[
&#x20; \{
&#x20;   "Id": "avgCPUCreditBalance",
&#x20;   "MetricStat": \{
&#x20;     "Metric": \{
&#x20;       "Namespace": "AWS/EC2",
&#x20;       "MetricName": "CPUCreditBalance",
&#x20;       "Dimensions": \[
&#x20;         \{
&#x20;           "Name": "InstanceId",
&#x20;           "Value": "i-deadbeef"
&#x20;         }
&#x20;       ]
&#x20;     },
&#x20;     "Period": 300,
&#x20;     "Stat": "Average"
&#x20;   },
&#x20;   "Label": "avgCPUCreditBalance"
&#x20; }
]'
:::


[title] Requisitos para Instalação das instâncias
[path] Visão Geral do Sistema/Requisitos/

- Dimensionamento dos discos (raiz **"/"** e de dados **"/dados"**)
- Para realizar a instalação, liberar acesso da máquina à internet (completo), ou quando não for possível, liberar no mínimo os seguintes domínios:
  - Repositório AIOPS (private):
    - **repo.aiops.com**
    - **docker.aiops.com**
    - **space.aiops.com**
  - Docker (public):
    - download.docker.com
    - auth.docker.io
    - registry-1.docker.io
    - index.docker.io
    - production.cloudflare.docker.com
  - Oracle/CentOS (caso estes sistemas tenham sido escolhidos para a instalação)
    - olcentgbl.trafficmanager.net
    - mirrorlist.centos.org


[title] Inventário
[path] AIOps/

BBem-vindo à página de documentação do xventory, módulo do AIOPS para inventário de ativos de TI. Este software é uma ferramenta usada para gerenciar e rastrear ativos de hardware e software em uma organização. Esta solução é capaz de processar modelos de política de configuração e tomar decisões automatizadas baseadas em scripts. Isso pode ajudar a automatizar tarefas repetitivas e reduzir a carga de trabalho dos administradores de sistema.

## Gerenciamento de Ativos

Com o Xventory você possuirá ativos conectados a um CMDB universal (federado). O Xventory irá permitir que você adicione ativos manualmente ou execute uma varredura automática para descobrir os ativos em sua rede. Você pode adicionar ativos de hardware, como desktops, laptops, servidores, impressoras, bem como ativos de software, como aplicativos instalados.

## Política de Configuração

Uma vez que seus ativos estejam no inventário, você pode criar políticas de configuração personalizadas para seus ativos. Essas políticas podem incluir configurações de segurança, restrições de rede e configurações de aplicativos. Você pode criar essas políticas por meio de scripts escritos em várias linguagens de programação, como PowerShell, Python ou Bash.

## Tomada de Decisões Automatizadas

O Xventory é capaz de tomar decisões automatizadas com base em suas políticas de configuração. Por exemplo, se um dispositivo não estiver em conformidade com uma política específica, o software pode acionar uma ação corretiva, como alertar o administrador de sistema ou executar um script para corrigir a configuração não conforme.

## Relatórios e Análises

O Xventory fornece relatórios detalhados sobre seus ativos e suas configurações. Você pode gerar relatórios para verificar o status de conformidade de seus ativos com as políticas de configuração. Isso pode ajudá-lo a identificar quais ativos precisam de atualizações ou correções.

[title] Coletor de Flows do Cilium
[path] Métrica/Coletas customizadas/

Este documento fornece detalhes sobre o Deployment do coletor que traz os dados de flows gerados pelo Cilium através do Hubble Relay para o AIOPS.

## Pré requisitos

Certifique-se de que o :Link[Cilium]{href="https://docs.cilium.io/en/stable/gettingstarted/k8s-install-default/#cilium-quick-installation" newTab="true" hasDisabledNofollow="false"} já esteja habilitado em seu ambiente Kubernetes.&#x20;

Uma vez que o Cilium esteja em funcionamento, siga os passos abaixo para habilitar o Deployment responsável pela coleta do tráfego de rede detectado pelo :Link[Hubble Relay]{href="https://docs.cilium.io/en/stable/internals/hubble/#hubble-relay" newTab="true" hasDisabledNofollow="false"}.

## Especificações do Deployment

O deployment usa a especificação YAML do Kubernetes para configurar e implantar o coletor de flows no namespace **kube-system**.

### YAML para Deployment

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: cilium-flow-collector
  namespace: kube-system
  labels:
    app: cilium-flow-collector
spec:
  replicas: 1
  selector:
    matchLabels:
      app: cilium-flow-collector
  template:
    metadata:
      labels:
        app: cilium-flow-collector
    spec:
      containers:
        - name: cilium-flow-collector
          image: aiops/cilium-flow-collector:latest
          resources:
            limits:
              memory: "200M"
          imagePullPolicy: IfNotPresent
          env:
            - name: COLLECT_FREQUENCY
              value: "5m"
            - name: HUBBLE_RELAY_ADDRESS
              value: "hubble-relay.kube-system.svc.cluster.local:80"
            - name: RECEIVER_ADDRESS
              value: "https://<SEU_DOMINIO_AIOPS>/sphere-sync/api/sync/collector"
            - name: RECEIVER_API_KEY
              value: <GENERATED_API_KEY>
            - name: ACCUMULATOR_MEMORY_SIZE
              value: "100M"

```

Os campos presentes em **env** são variáveis de ambiente que podem ser ajustadas para atender às necessidades específicas do seu ambiente:

- **COLLECT\_FREQUENCY**
  - **Descrição**: Define a frequência com que os dados de flow são coletados.
  - **Valor Padrão: 5m&#x20;**(5 minutos)
  - **Formato**: O valor deve ser especificado em uma combinação de unidades de tempo, como segundos (s), minutos (m), ou horas (h).
    - Exemplos: 10s (10 segundos), 5m (5 minutos), 1h (1 hora).
- **HUBBLE\_RELAY\_ADDRESS**
  - **Descrição**: Endereço do Hubble Relay usado para coletar os dados de flows.
  - **Valor Padrão:&#x20;**&#x68;ubble-relay.kube-system.svc.cluster.local:80
- **RECEIVER\_ADDRESS**
  - **Descrição**: Endereço da instância que receberá as métricas, onde os dados coletados serão armazenados. Esse campo pode se preenchido de duas formas:
    - IP e Porta do InfluxDB localizado na instância DB Worker de seu ambiente AIOPS (Exemplo: **127.0.0.1:8086**).
    - URL contendo o caminho da API de coleta do AIOPS **(/api/sync/collector).&#x20;**
      - Caso o domínio responda pela porta 80 ou 443, adicionar o prefixo **(/sphere-sync)&#x20;**(Exemplo: **https\://seu-dominio-aiops.com/sphere-sync/api/sync/collector**)
      - Caso opte pelo envio diretamente pelo IP, utilizar a porta 18001 (Exemplo: **http\://127.0.0.1:18001/api/sync/collector**)
      - **\*&#x20;**&#x45;ssa opção **requer** o preenchimento da variável de ambient&#x65;**&#x20;RECEIVER\_API\_KEY**.
- **RECEIVER\_API\_KEY**
  - **Descrição**: Esse campo deve ser preenchido **apenas** caso opte por seguir com o envio através da API de coleta do AIOPS **(/api/sync/collector)**.&#x20;
  - A chave de acesso pode ser criada na interface de :Link[Chaves de Acesso]{href="https://docs.citsmart.com/aiops/chaves-de-acesso" newTab="true" hasDisabledNofollow="false"} do AIOPS.
- **ACCUMULATOR\_MEMORY\_SIZE**
  - **Descrição**: Define o tamanho da memória do acumulador de dados usado pelo coletor de flows para a realização do envio em batch.
  - **Valor Padrão:&#x20;**&#x31;00M
  - **Formato**: O valor deve ser especificado em uma combinação de unidades de memória, como megabytes (M), mebibytes (Mi), gigabytes (G), gibibytes (Gi), etc.
    - Exemplos: 100M (100 megabytes), 100Mi (100 mebibytes), 1G (1 gigabyte), 1Gi (1 gibibyte).
  - **Exemplo de Alteração**:
    - Em um ambiente com mais recursos de memória, o valor pode ser aumentado.
    - Em um ambiente com restrições de memória, pode ser necessário reduzir o valor.
- **LOG\_LEVEL**
  - **Descrição**: Define o nível de log desejado.
  - **Valor Padrão:&#x20;**&#x49;NFO
  - **Valores aceitos**:
    - **INFO**: Apenas logs informativos
    - **WARNING:&#x20;**&#x4C;ogs informativos e aviso
    - **ERROR:&#x20;**&#x4C;ogs informativos, aviso e erro

## Instruções de Implantação

**Salvar o arquivo YAML**: Copie o conteúdo YAML acima e salve em um arquivo chamado cilium-flow-collector-deployment.yaml.

**Aplicar o deployment**: Use o comando kubectl para aplicar o deployment no seu cluster Kubernetes.

:::BlockQuote
kubectl apply -f cilium-flow-collector-deployment.yaml
:::

**Verificar o status**: Verifique o status do deployment para garantir que o coletor de flows foi implantado corretamente.

:::BlockQuote
kubectl get deployments -n kube-system
kubectl get pods -n kube-system -l app=cilium-flow-collector
:::

**Valide as métricas:&#x20;**&#x41;pós checar a saúde do pod, você pode acompanhar a chegada das métricas através do :Link[Grafana]{href="https://docs.citsmart.com/aiops/validando-coletas-customizadas" newTab="true" hasDisabledNofollow="false"} do AIOPS, utilizando a seguinte Query:

```shell
cilium_flows{}[5m]
```

\* O primeiro envio das métricas para o AIOPS pode levar o tempo especificado pelas variáveis **COLLECT\_FREQUENCY**, pois as mesmas são responsáveis por acumular os dados e envia-las em batch periodicamente.

[title] Listagem de alarmes
[path] AIOps/Alarmes/

É possível acessar a listagem de alarmes clicando no botão abaixo:

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/qpr-FybYVVmqbebYaBDz_/4n9J5MgAdh3oTUj43CoJI_image.png" signedSrc size="18" width="59" height="44" position="center" caption}

A partir do menu principal no canto esquerdo superior da tela.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/qpr-FybYVVmqbebYaBDz_/Xqk5OB2fUlMy-PsVQ6_dm_image.png" signedSrc size="10" width="66" height="278" position="center" caption}

Após executar essa ação, será apresentada uma listagem com todos os alarmes ativos em seu ambiente.

![](https://archbee-image-uploads.s3.amazonaws.com/qpr-FybYVVmqbebYaBDz_/eKFGh4v7BoOAHutvsmA8U_image.png)

No canto superior direito da tela é possível efetuar a pesquisa de alarmes por datas específicas ou intervalo de tempo.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/cO3qIGwc1bjy99iZ4ihGE_image.png" size="60" width="294" height="51" caption position="center" signedSrc="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/cO3qIGwc1bjy99iZ4ihGE_image.png"}


[title] Azure Monitor
[path] AIOps/Integrações/Integrações com Webhook/

## **1. Crie uma Regra de Alerta no Azure Monitor**

1. **Acesse o Azure Portal**
   Entre no portal Azure usando suas credenciais.
2. **Navegue até Azure Monitor**
   No menu lateral, vá para **Monitor** > **Alertas**.
3. **Crie uma Nova Regra de Alerta**
   Clique em **Criar** > **Regra de alerta**.
4. **Selecione o Escopo**
   Escolha o recurso (ou grupo de recursos) que deseja monitorar.
5. **Defina a Condição**
   Adicione e configure a condição que deve disparar o alerta (por exemplo, uso de CPU acima de 80%).
6. **Configure as Ações**
   Na seção **Ações**, associe ou crie um grupo de ações para o alerta.

## **2. Crie um Grupo de Ações (Action Group)**

1. **Acesse Action Groups**
   Em **Monitor** > **Alertas** > **Grupos de ações**, clique em **Criar**.
2. **Preencha os Dados Básicos**
   - **Assinatura**: Selecione a correta.
   - **Grupo de recursos**: Selecione ou crie.
   - **Nome do grupo de ações**: Dê um nome descritivo.
   - **Nome curto**: Usado para identificar rapidamente o grupo.
3. **Adicione uma Ação do Tipo Webhook**
   - **Tipo de ação**: Selecione **Webhook**.
   - **Nome**: Dê um nome para a ação.
   - **URI**: Insira a URL do endpoint que receberá os alertas.
     - O endpoint deverá ser:
     - `https://<DOMINIO_AIOPS>/services/collector/event`
   - **Autenticação**: Configure autenticação por token, se necessário.
     - Gere uma API Key no AIOPS e adicione à configuração.
4. **Salve o Grupo de Ações**
   Clique em **Revisar + criar** e depois em **Criar**.

## **3. (Opcional) Configure Secure Webhook para Autenticação Avançada**

Se precisar de mais segurança:

1. **Registre uma Aplicação no Microsoft Entra ID**
   Siga o passo a passo do Azure para registrar uma aplicação.
2. **Defina um Service Principal**
   Crie um service principal para a aplicação registrada.
3. **Crie o Secure Webhook**
   No grupo de ações, adicione uma ação do tipo **Secure Webhook**.
   - **ID do objeto**: Use a ID da aplicação registrada.
   - **URI**: Insira a URL do endpoint.
   - **Habilite o Common Alert Schema** (opcional).

## **4. Adicione Middleware para Transformação do Payload**

Como o Azure Monitor não permite personalizar totalmente o payload enviado pelo webhook, recomenda-se usar uma camada intermediária (como Azure Logic Apps ou Azure Functions) para transformar o JSON recebido no formato esperado pela sua ferramenta.

### **Exemplo com Azure Logic Apps**

1. **Crie um Logic App**
   - No portal Azure, vá para **Logic Apps** > **Criar**.
2. **Adicione um Trigger do Tipo Solicitação HTTP**
   - No designer, adicione o trigger **Quando uma solicitação HTTP é recebida**.
3. **Adicione uma Ação de Parse JSON**
   - Use a ação **Parse JSON** para ler o payload recebido do Azure Monitor.
4. **Adicione uma Ação Compose**
   - Utilize **Compose** para montar o JSON no formato esperado pela sua ferramenta, mapeando campos do payload do Azure para os campos do seu JSON.
5. **Adicione uma Ação HTTP**
   - Use a ação **HTTP** para enviar o JSON formatado para o endpoint final da sua ferramenta.
6. **Salve e Publique o Logic App**
   - Copie a URL do trigger HTTP e use-a como URI no grupo de ações do Azure Monitor.
7. **Exemplo de Transformação**

```json
{
  "start_date": "@{body('Parse_JSON')?['data']?['essentials']?['firedDateTime']}",
  "update_date": "@{utcNow()}",
  "device_id": "@{first(body('Parse_JSON')?['data']?['essentials']?['alertTargetIDs'])}",
  "adapter_type": "Azure Monitor",
  "device_type": "@{body('Parse_JSON')?['data']?['essentials']?['signalType']}",
  "device_name": "@{body('Parse_JSON')?['data']?['essentials']?['alertRule']}",
  "health": "@{body('Parse_JSON')?['data']?['essentials']?['monitorCondition']}",
  "impact": "@{body('Parse_JSON')?['data']?['essentials']?['severity']}",
  "criticality": "@{body('Parse_JSON')?['data']?['essentials']?['severity']}",
  "check": "@{body('Parse_JSON')?['data']?['essentials']?['description']}",
  "type": "@{body('Parse_JSON')?['data']?['essentials']?['signalType']}",
  "alert_id": "@{body('Parse_JSON')?['data']?['essentials']?['alertId']}",
  "status": "@{body('Parse_JSON')?['data']?['essentials']?['monitorCondition']}",
  "alert_url": "@{body('Parse_JSON')?['data']?['alertContext']?['linkToSearchResultsUI']}"
}
```

## **5. Teste a Integração**

1. **Disparar um Alerta de Teste**
   - No grupo de ações, use a opção **Testar grupo de ações** para enviar um alerta de exemplo.
2. **Verifique o Recebimento no Endpoint Final**
   -


[title] Integração
[path] AIOps/Compartilhamento Automático/

Compartilhamento Automático utilizando Integrações.&#x20;

## Criação do Auto Compartilhamento

Acessar a opção de configurações no menu principal do AIOPS:

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/2x7J3LFFnjoOSde1WNTOt_botaoconfiguracoes.png" size="36" caption position="flex-start" signedSrc="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/2x7J3LFFnjoOSde1WNTOt_botaoconfiguracoes.png?AWSAccessKeyId=AKIAYQNQCIXNIQWBC56C&Expires=1697895259&Signature=yqzsmZC98o2UPhUHwg5DUiLmVi8%3D"}

No menu lateral escolha a opção **Auto Compartilhamento**:

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/u9p2-1Q_MH68GkLMX4JYz_captura-de-tela-2021-03-31-as-131027.png" size="40" caption position="center" signedSrc="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/u9p2-1Q_MH68GkLMX4JYz_captura-de-tela-2021-03-31-as-131027.png?AWSAccessKeyId=AKIAYQNQCIXNIQWBC56C&Expires=1697895259&Signature=Bs4Lz0uzXFirXz7wZq5BMNhZD0E%3D"}

Você poderá criar um novo compartilhamento ou alterar um já existente. Para criar um novo você irá definir o **Ambiente** (utilizado para direcionar os alertas deste canal) e o **Tipo** escolhendo uma das opções de integração disponíveis.

[title] Zones
[path] Visão Geral do Sistema/

Abaixo relacionamos as instâncias (nós) do AIOPS, as Zonas de conexão, detalhes dos serviços, portas e diagramas.

***

# Instâncias

### **01.  MASTER-NODE**

Instância Principal – Responsável por orquestrar os serviços essenciais do AIOPS.

### **02.  DB-WORKER**

Instância do Banco Analítico.

### **03.  ATOM-WORKER (ML-WORKER)**

Instância responsável por distribuir a coleta de dados e descoberta de rede (*via* *SNMP*, *Ping ICMP*, etc.). Treinamento distribuído de modelos de (IA), operando em conjunto com a ***MASTER-NODE***.

### **04.  APM-WORKER**

Instância do Divedot (Application Performance Monitoring).

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/d6GYrRcq3BPsbEo58KBZA_whatsapp-image-2025-07-02-at-234911-8eec953d.jpg)

***

# Regras por Zonas

São 3 as principais zonas de conectividade do AIOPS, utilize-as para criação das regras de firewall.

- AIOPS **Zone***&#x20;(obrigatório)*
  - Contempla todas as instâncias do AIOPS;
  - Acesso liberado para todas as portas / protocolos entre as máquinas desta zona.
  - Acesso para portas específicas (para se conectar fora da Zone);
  - Compatibilidade com IPV4 e IPV6
- **Private Zone***&#x20;(obrigatório)*
  - Compreende toda a rede privada a ser monitorada;
  - Descoberta de Rede (*Agent Probe*);
  - Ping / Coleta das Métricas SNMP;
  - Envio de métricas (a partir dos hosts com agent);
  - Testes Web em aplicações dentro da rede privada.
- **Public Internet***&#x20;(opcional)*
  - Acesso às aplicações do AIOPS;
  - Testes Web em aplicações públicas;
  - Envio de dados das páginas web / aplicativos;
  - Envio de dados de serviços externos e/ou de outro datacente&#x72;*;*
  - Acesso originados de Itens Externos / Cloud, ex.: *IBM, AWS, Azure, OpenShift, etc. (opcional).*

![](https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/TQAzboeP_V4kZwNbvQn7m_firewall-zones.png)

***



# Diagrama do Sphere Agent

O *Sphere Agent* sobe a porta ***10081*** nos hosts instalados, o acesso à essa porta deverá ser liberado  para a instância ***MASTER-NODE****. Caso opte por* apontar o agent para o *HTTP Proxy* adicione à configuração do agent `path: /sphere-sync`.&#x20;

![](https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/qZOcmC9OK4zXwWu7LEja1_diagram-sphere-agent.png "Diagrama de comunicação do Sphere Agent. Toque na imagem para ampliar")

:::hint{type="info"}
## Segurança

A porta do agent (10081) utiliza o protocolo GRPC e criptografia e não transporta dados/scripts. Ela é responsável por receber sensores binários de Healthcheck e Automação.
:::

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/s6N9LumoAkz-6dISJn8fA_legend-simon-connections.png" size="68" caption="Legenda das Conexões" position="center" signedSrc="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/s6N9LumoAkz-6dISJn8fA_legend-simon-connections.png?AWSAccessKeyId=AKIAYQNQCIXNIQWBC56C&Expires=1697894938&Signature=c6frYAaV4BrQFsmzHruY987V5I4%3D" width="980" height="92" darkWidth="980" darkHeight="92"}

***

# Diagrama do Agent Probe

O *Agent Probe* realiza a Descoberta de Rede, Ping (ICMP), Coleta de Dados / Traps SNMP.

![](https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/9cqVckGRShFaJ2y9miDYT_diagram-agent-probe.png "Diagrama de comunicação do Agent Probe. Toque na imagem para ampliar")

***

# Portas e Serviços por Instância

Portas e serviços que estão expostos ***para fora da Zone***, sendo assim, foram omitidos as portas e serviços internos (que são exclusivas da *Zone)*.

| **Instância** | **Descritivo**                | **Porta (obrigatória)** | **Porta (opcional)**                                     |
| ------------- | ----------------------------- | ----------------------- | -------------------------------------------------------- |
| 01-MASTER     | HTTP Proxy                    | **80** / **443**        | --                                                       |
| 01-MASTER     | Sphere Sync - Agent Collector | **80**                  | **18001**                                                |
| 02-DB         | HTTP Proxy                    | --                      | --                                                       |
| 04-APM        | HTTP Proxy                    | **80** / **443**        | --                                                       |
| 04-APM        | Trace Sync - APM Collector    | --                      | **8090** (tcp)**, 8125&#x20;**(udp)**, 8126&#x20;**(tcp) |



## Proxy dos coletores (portas opcionais)

Ao apontar os coletores para o AIOPS (Agents/APM) é necessário configurar a URL corretamente, utilize a referência abaixo para a devida configuração.

| **Instância** | **Descritivo** | **Porta original** | **Porta do Proxy&#x20;** | **Adicionar à URL (path)** |
| ------------- | -------------- | ------------------ | ------------------------ | -------------------------- |
| 01-MASTER     | Sphere Sync    | **18001**          | **80** ou **443**        | /sphere-sync               |
| 04-APM        | Trace Sync     | **8090**           | **80** ou **443**        | /\_ddsite                  |

## Restrição de portas na Zone

Caso não seja possível liberar todas as portas entre as máquinas do AIOP&#x53;*&#x20;(Zone)&#x20;*&#x73;erá necessário adicionar no mínimo as seguintes regras entre os nós:

| **ORIGEM**     | **DESTINO**    | **PORTAS DESTINO**                                                              |
| -------------- | -------------- | ------------------------------------------------------------------------------- |
| 01-MASTER-NODE | 02-DB-WORKER   | 02-DB-WORKER<br />TCP: **8086, 8428, 9095, 3100, 9080**<br />UDP: **514**       |
| 01-MASTER-NODE | 03-ATOM-WORKER | TCP: **80,** **19000, 19200**                                                   |
| 01-MASTER-NODE | 04-APM-WORKER  | TCP: **8090, 8123**, **8126,** **9000**, **9092**, **29092**<br />UDP: **8125** |

| **ORIGEM**            | **DESTINO**    | **PORTAS DESTINO**                              |
| --------------------- | -------------- | ----------------------------------------------- |
| *Todas as instancias* | 01-MASTER-NODE | 01-MASTER-NODE<br />TCP: **80, 443,** **18001** |



:::hint{type="info"}
Atenção para as portas que estão exclusivamente nos protocolos **TCP** ou **UDP**.
:::

## Backups&#x20;

O AIOPS possui rotinas automatizadas de backup, garantindo assim a capacidade de recuperação a desastres seja a nível de base de dados, usuários, configurações e métricas que permeiam toda a plataforma do AIOPS.

## Auditlog

O AIOPS possui por padrão, funcionalidade de mensageria que permite a auditoria e acompanhamento das informações de todos os eventos que acontecem no escopo de toda a plataforma, contemplando usuários, configurações, CRUDs e métricas, para uma visão holística de todos os módulos que contemplam a solução.&#x20;

## Criptografia

O AIOPS utiliza protocolos remotos para a captura de transações. Por padrão, utilizamos a comunicação HTTPS (SSL)  para requisições web e é possível alternar o protocolo para HTTP não seguro manualmente por meio dos arquivos de configuração, a critério do cliente.
Para as automações e comunicação via agent, o AIOPS utiliza o protocolo GRPC e não transporta dados/scripts executáveis, é responsável por receber informações de sensores binários, healthcheck e automação.

### Layer de storage de informações sensíveis

Os usuário do AIOPS possuem todos os dados sensíveis salvos em um banco de dados comportando senhas criptografadas.

Essas informações confidenciais são criptografadas usando criptografia Triple-DES. A chave usada para criptografia é exclusiva para cada usuário, garantindo que os dados não possam ser descriptografados por um usuário diferente e uma máquina diferente.

**Criptografia: Symmetric Triple-DES (168 bits)**

DES triplo é o nome da cifra de bloco do algoritmo de criptografia triplo de dados (um algoritmo determinístico operando em grupos de bits de comprimento fixo) que aplica o algoritmo de cifra Padrão de criptografia de dados (DES) três vezes a cada bloco de dados.&#x20;


[title] Infraestrutura
[path] /


[title] Porque Usar AIOPS
[path] Introdução/

A plataforma CITSmart X, com sua robusta capacidade de observabilidade e recursos de ações preditivas, permite a identificação antecipada de falhas e degradações por meio de um sistema de monitoramento avançado. Quando devidamente configurada com thresholds (limiares) específicos, a solução pode disparar ações automáticas que evitam a indisponibilidade de ativos e serviços, assegurando a disponibilidade acordada em contratos de nível de serviço (SLA).

Durante esse processo de automação inteligente, não apenas ações corretivas e preventivas podem ser executadas automaticamente para garantir a continuidade e a qualidade dos serviços, mas também é possível disparar a criação de eventos, incidentes, problemas, mudanças e, em situações críticas, ativar processos de continuidade de negócios.

Essa abordagem integrada fortalece a gestão proativa de serviços e amplia a capacidade da organização de reagir rapidamente a riscos operacionais, promovendo maior eficiência e conformidade com as melhores práticas de ITSM e governança de TI.

[title] Dashboard
[path] AIOps/

Os painéis de dashboards da plataforma AIOPS fornecem uma visão geral de suas métricas de saúde operacional em uma visão consolidada para acompanhamento de métricas chave. É ideal para manter a operação atualizada com os status mais recentes além de atender suas possíveis necessidades de negócios.

[title] Visão Geral
[path] AIOps/Dashboard/

O acompanhamento de seus alertas/coleções também é possível, de forma simples e visual. Através da dashboard de visão geral de eventos, acessível via AIOPS.

![](https://gblobscdn.gitbook.com/assets%2F-Ls76-8XbGuboSQAg3Y9%2F-LsJ6UgGq6N6-pa_mvpI%2F-LsJ6kSLdIA6YkDbNxAa%2FCaptura%20de%20Tela%202019-10-28%20a%CC%80s%2017.46.33.png?alt=media\&token=00d13536-4810-4963-a3f6-4dbded1408e5)

Através dos dados mostrados acima é possível um acompanhamento em tempo real do tempo de atendimento de diferentes problemas tratados pela operação.

Também é possível observar como anda a capacidade de atendimento de cada equipe envolvida nos atendimentos:

De modo geral essa dashboard te fornece KPIs em relação a problemas que aconteceram, tempo de atuação, e capacidade de equipe, podendo de forma rápida consolidar informações necessárias para eventuais tomadas de decisão.

[title] AWS CloudWatch com EventBridge
[path] AIOps/Integrações/Integrações com Webhook/



## 1. Pré-requisitos

- **Conta AWS** com acesso aos serviços CloudWatch e EventBridge.
- **Endpoint de Webhook AIOPs** público HTTPS para receber as notificações.
- **Permissões IAM** adequadas para criar regras e destinos no EventBridge.

## 2. Visão Geral

Automatizar o envio de notificações para um webhook externo sempre que um alarme do **CloudWatch** for disparado, utilizando o **EventBridge** para rotear e transformar o evento em um formato JSON específico.

## 3. Passo a passo

### 3.1. Criar um Alarme no CloudWatch

1. **Acesse o Console do CloudWatch.**
2. Na seção “Alarmes”, clique em “Criar alarme”.
3. **Selecione a métrica** desejada (exemplo: CPUUtilization de uma instância EC2).
4. **Defina as condições** para disparo do alarme.
5. **Nomeie o alarme** e clique em “Criar alarme”.

Mais detalhes sobre como criar um **alerta** no **CloudWatch** podem ser vistos na :Link[documentação oficial da AWS]{href="https://docs.aws.amazon.com/pt_br/AmazonCloudWatch/latest/monitoring/Alarm-On-Metrics.html" newTab="true" hasDisabledNofollow="false"}.

### 3.2. Criar uma Regra no EventBridge

1. **Acesse o Console do EventBridge.**
2. No painel de navegação, clique em “Regras” e depois em “Criar regra”.
3. **Defina um nome** e uma descrição para a regra.
4. **Selecione o event bus padrão** (“AWS default event bus”).
5. **Escolha “Rule with an event pattern”**.
6. **Configure o padrão de eventos** para capturar alarmes do CloudWatch:

```json
{
  "source": ["aws.cloudwatch"],
  "detail-type": ["CloudWatch Alarm State Change"]
}
```

(Opcional: adicione filtros para recursos ou estados específicos.)

Mais detalhes sobre como criar uma **Regra** no **EventBridge** podem ser vistos na :Link[documentação oficial da AWS]{href="https://docs.aws.amazon.com/pt_br/eventbridge/latest/userguide/eb-get-started.html#eb-gs-create-rule" newTab="true" hasDisabledNofollow="false"}.

### 3.3. Configurar o Destino (Webhook via API Destination)

1. **Crie uma conexão de API Destination:**
   - Em “API destinations”, clique em “Connections”.
   - Clique em “Create connection”.
   - Defina nome, tipo de autenticação e credenciais (API key, OAuth, basic auth).
2. **Crie o API Destination:**
   - Em “API destinations”, clique em “Create API destination”.
   - Defina nome, endpoint HTTPS do webhook, método HTTP (ex: POST).
     - O endpoint deverá ser:
       - https\://\<DOMINIO\_AIOPS>/services/collector/event
     - Gere uma API Key e adicione à configuração.
   - Associe a conexão criada anteriormente.
   - Defina o limite de taxa de invocação (ex: 10 eventos por segundo).
3. **Associe o destino à regra:**
   - Na criação da regra, em “Select targets”, escolha “API destination”.
   - Selecione o destino criado.

### 3.4. Configurar o Input Transformer (Formatação do JSON)

1. **Defina o Input Path** para mapear variáveis do evento CloudWatch para o formato desejado:

```json
{
  "adapter_kind": "$.source",
  "alert_criticality": "$.detail.state.value",
  "alert_definition": "$.detail.state.reason",
  "alert_id": "$.id",
  "alert_impact": "$.detail.state.value",
  "alert_recommendations": "$.detail.state.reason",
  "alert_status": "$.detail.state.value",
  "alert_subtype": "$.detail.state.value",
  "alert_type": "$.detail-type",
  "cancel_time": "$.detail.state.timestamp",
  "create_time": "$.time",
  "link_to_alert": "$.resources[0]",
  "object_efficiency_state": "$.detail.state.value",
  "object_health_state": "$.detail.state.value",
  "object_risk_state": "$.detail.state.value",
  "resource_id": "$.detail.alarmName",
  "resource_kind": "$.detail.configuration.metrics[0].metricStat.metric.namespace",
  "resource_name": "$.detail.configuration.metrics[0].metricStat.metric.dimensions.InstanceId",
  "update_time": "$.detail.state.timestamp"
}
```

1. **Defina o Input Template** para gerar o JSON personalizado:

```json
{
  "start_date": "<create_time>",
  "update_date": "<update_time>",
  "cancel_date": "<cancel_time>",
  "device_id": "<resource_id>",
  "adapter_type": "<adapter_kind>",
  "device_type": "<resource_kind>",
  "device_name": "<resource_name>",
  "health": "<object_health_state>",
  "risk": "<object_risk_state>",
  "efficiency": "<object_efficiency_state>",
  "impact": "<alert_impact>",
  "criticality": "<alert_criticality>",
  "check": "<alert_definition>",
  "type": "<alert_type>",
  "sub_type": "<alert_subtype>",
  "alert_id": "<alert_id>",
  "status": "<alert_status>",
  "recommendations": "<alert_recommendations>",
  "alert_url": "<link_to_alert>"
}
```

### 3.5. Configurar Dead Letter Queue (Opcional, para tratamento de falhas)

1. **Crie uma fila SQS para DLQ.**
2. **Associe a DLQ ao destino da regra** para capturar eventos que não puderam ser entregues.

### 3.6. Testar a Integração

1. **Disparar o alarme manualmente** (por exemplo, simulando alta utilização de CPU na EC2).
2. **Monitorar o disparo** via CloudWatch Metrics e Logs.
3. **Verificar o recebimento da notificação** no endpoint do webhook.

### 3.7. Monitoramento e Manutenção

- **Acompanhe métricas** no CloudWatch (FailedInvocations, Invocations).
- **Analise logs** e mensagens da DLQ em caso de falhas.
- **Ajuste permissões e configurações** conforme necessário.

***

## 4. Resumo dos Recursos Utilizados

| Serviço         | Função Principal                               |
| --------------- | ---------------------------------------------- |
| CloudWatch      | Monitoramento e disparo de alarmes             |
| EventBridge     | Roteamento e transformação de eventos          |
| API Destination | Entrega de eventos para webhook externo        |
| SQS (DLQ)       | Tratamento de eventos não entregues (opcional) |

***

## 5. Considerações Finais

- **Sempre valide o formato do JSON** enviado ao webhook.
- **Teste diferentes cenários** de falha para garantir robustez.
- **Documente as permissões IAM** necessárias para cada etapa.


[title] Descoberta e Relacionamento
[path] AIOps/Inventário/

### Introdução

O Xventory é uma ferramenta de gerenciamento de ativos de TI que oferece uma série de recursos para automatizar o processo de gerenciamento de ativos de TI. Uma das funcionalidades mais importantes do Xventory é a capacidade de automatizar o relacionamento entre ativos no processo de inventário de ativos.

Com o Xventory, é possível coletar automaticamente informações sobre a relação entre ativos, incluindo informações sobre a hierarquia do sistema, dependências de software, interações de rede e muito mais. Essas informações são usadas para criar uma visão completa dos serviços de TI em uma organização, incluindo quais ativos são usados em cada serviço, quais serviços dependem de outros serviços e muito mais.

### Automações

A automação do relacionamento entre ativos com o Xventory oferece uma série de benefícios para as organizações. Em primeiro lugar, a automação torna o processo de gerenciamento de ativos de TI mais eficiente e escalável. Em vez de coletar manualmente informações sobre a relação entre ativos, o Xventory coleta automaticamente essas informações, permitindo que as organizações se concentrem em outras tarefas importantes.

### Relacionamentos&#x20;

Além disso, a automação do relacionamento entre ativos ajuda as organizações a entender melhor como os serviços de TI são construídos e quais ativos são essenciais para o bom funcionamento desses serviços. Com essa visão completa dos serviços de TI, as organizações podem identificar ativos redundantes ou obsoletos que podem ser eliminados, reduzindo custos e melhorando a eficiência do sistema, além de se manterem atualizadas das informações necessárias.

### Inventário e relacionamento

Com o Xventory, as organizações podem obter informações de relacionamento entre ativos de forma automatizada no processo de inventário de ativos, tornando o gerenciamento de ativos de TI mais eficiente e escalável. Além disso, o Xventory oferece relatórios detalhados sobre a relação entre ativos, permitindo que as organizações monitorem as mudanças na relação entre ativos e identifiquem possíveis problemas antes que afetem os serviços de TI.

### WOL&#x20;

O Xventory também oferece suporte à tecnologia Wake On LAN (WOL), que permite às organizações ligar remotamente computadores que estão em modo de espera (standby) ou hibernação. Com o suporte ao WOL, as organizações podem atualizar ou fazer manutenção em computadores remotamente, sem precisar estar fisicamente presentes no local.

Para usar o recurso WOL do Xventory, é necessário que os computadores estejam equipados com placas de rede compatíveis com WOL e que o recurso esteja habilitado nas configurações de energia do sistema. Com o WOL ativado, o administrador de sistema pode enviar um sinal para o computador remotamente para acordá-lo do modo de espera ou hibernação e atualizá-lo ou fazer manutenção no sistema.

[title] APM
[path] /


[title] Topologia
[path] Infraestrutura/

Visualize as métricas relacionadas à um IC, coletadas em um determinado intervalo de tempo, defina templates de métricas, acompanhe a real situação e organize seus nós através das funcionalidades existentes para cada nós de sua infraestrutura.

## Acesso&#x20;

Para acessar a tela de detalhamento de host, é necessário seguir o procedimento para acesso a tela de  :Link[Infraestutura]{href="https://docs.citsmart.com/aiops/infraestrutura" newTab="true" hasDisabledNofollow="false"} e clicar em um item existente na listagem.

![](https://archbee-image-uploads.s3.amazonaws.com/qpr-FybYVVmqbebYaBDz_/oCZakhZ-7RVXJaKhhtKdo_image.png)

## Informações&#x20;

Na tela é possível obter informações rápidas sobre o host selecionado, como **métricas**, **informações de sistema**, **processos**, **serviços de negócios dependentes deste item** e **dependências lógicas&#x20;**&#x70;ara outros itens de sua infraestrutura.

### Informações gerais&#x20;

No box lateral esquerdo, temos informações gerais:

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/yB_kwW_j6PQ9HiDIK1nLz_image.png" size="38" caption="Informações de Sistema, Volumes, Interfaces, Processos e Serviços Dependentes" position="center" signedSrc="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/yB_kwW_j6PQ9HiDIK1nLz_image.png?AWSAccessKeyId=AKIAYQNQCIXNIQWBC56C&Expires=1697908384&Signature=jv9nUM5pukGrvC24KV3pKsmkPas%3D"}

### Métricas

Observando o centro da tela é possível de forma rápida e eficiente obter dados sobre métricas importantes para esse determinado nó.

![](https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/5sqjVKjoK79mZvfnRCS_s_image.png)

### Predição

Para cada métrica é possível prever o que pode acontecer, com base no comportamento histórico do host citado, clicando no botão de predição.

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/vMmbGQ2M6oFwdJlFugMf8_screen-shot-2021-06-16-at-163603.png "Predição de métricas ")

### Dependências

Na área inferior da tela é possível observar o box de dependency overview, onde se pode observar quais as dependências lógicas ativas para esse nó de infraestrutura.

![](https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/uoyhwILaEgx0mZoTDMKYG_image.png)

### Insights e alertas

O Atmos atua de forma automática, auxiliando na gestão de recursos e propiciando uma visão rápida de possíveis problemas no host escolhido através dos botões abaixo (canto superior direito):

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/BcgqKz7B9oRpiuJiWaUsw_image.png" size="50" caption position="center" signedSrc="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/BcgqKz7B9oRpiuJiWaUsw_image.png?AWSAccessKeyId=AKIAYQNQCIXNIQWBC56C&Expires=1697908384&Signature=meVIJ5ublDFXHGrSUyFL1Tlx7yo%3D"}

## Ações

Para o host escolhido é possível desempenhar ações com o objetivo de organizar e filtrar (tags e annotations) e ações com o objetivo de gerir os items de configuração.

### Criação e gestão de tags e anotações:

No canto superior direito é possível encontrar a opção de adicionar tags e anotações para facilitar a organização:

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/_rfDdrH8WjZ8AHQIJ7IK__image.png" size="52" caption position="center" signedSrc="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/_rfDdrH8WjZ8AHQIJ7IK__image.png?AWSAccessKeyId=AKIAYQNQCIXNIQWBC56C&Expires=1697908384&Signature=S37ofYitbGxAxfwu2dQSvRX32rk%3D"}

Ao clicar no ícone de etiqueta, um modal será carregado com as opções de tags e anotações do host escolhido.

### Atuando com hosts:

No canto superior direito possível selecionar a opção de três pontos:&#x20;

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/wzOvlcZe1apRtTc2gsfmU_image.png" size="46" caption position="center" signedSrc="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/wzOvlcZe1apRtTc2gsfmU_image.png?AWSAccessKeyId=AKIAYQNQCIXNIQWBC56C&Expires=1697908384&Signature=XfkVFU32Bryw0J0d%2B0LZUjOsuok%3D"}

Essa opção abrirá um dropdown com as seguintes opções:

- Alterar nome
- Configuração de Métrica
- Arquivar
- Combinar hosts
- Configurar painéis

### Alteração de nome&#x20;

Permite de forma rápida, padronizar e renomear hosts para um melhor acompanhamento.

### Configuração de métrica

Permite consultar e acessar as configurações de métricas ativas para esse item de configuração.

### Arquivar

Permite remover (arquivar) um host de forma lógica, evitando assim perda de dados e permitindo uma recuperação posterior.

### Combinar host

Como o AIOPS/Atmos atua de maneira a propiciar uma centralização de diferentes ferramentas é possível selecionar dois hosts oriundos de diferentes fontes mas que representam o mesmo item e realizar uma fusão das informações de duas diferentes fontes, escolhendo qual seria a princiapal e evitando dados inutilizados na tela de infraestrutura.

### Configurar painéis

É a opção onde se pode configurar as métricas a serem exibidas nesse host:

![](https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/CqTN8Ot762GWrCWszEK9I_image.png)

### Coleta por SNMP v1/v2

Colete eventos de diversos dispositivos e sistemas através  do protocolo SNMP - Simple Network Management Protocol.

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/2W8cFLJPtBvnetZcAickF_coleta-snmp.PNG)


[title] Atuação em incidentes
[path] AIOps/Incidente/

Com o AIOPS é possível entender em alto nível, os problemas que estão acontecendo em sua operação, suprimindo ruídos (evitando a geração de alertas desnecessários, desconsiderando ICs não relacionados, através de PRCA), contextualizando e agrupando alertas que são fundamentais, de acordo com tipos de falhas, para identificação de causa raiz. Permitindo a criação de formatos de falhas que serão usadas posteriormente não só para contextualizar, como também para treinar a Inteligência Artificial.

## Análise da Causa Raiz

Ativando a funcionalidade de RCA Autônoma do AIOPS, é possível suprimir alertas com base em suas dependências/relações topológicas. Dessa forma, é possível visualizar apenas o que realmente está causando o problema detectado.

![](https://gblobscdn.gitbook.com/assets%2F-Ls76-8XbGuboSQAg3Y9%2F-LsS4TFxl19M8_Q9JDeW%2F-LsS4cYTYGbvGQVjC3n6%2FDetalhes-do-Incidente-Completo.png?alt=media\&token=5e4e62ca-eb09-4145-9aba-b246854268d9)



Dentro da opção Lab This (:Link[Correlação de Eventos]{href="https://docs.citsmart.com/aiops/correlacao-de-eventos" newTab="true" hasDisabledNofollow="false"}) a  plataforma permite a escolha da causa raíz pelo usuário, com intuito de determinar o motivo das falhas em geral, possibilitando que o AIOPS reconheça o problema em caso de reincidências.

Para executar essa operação, basta clicar no botão que se encontra ao lado direito, dentro da lista de alertas.

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/fNVo-KJWofXulu_ZaEKqN_Screen%20Shot%202021-01-10%20at%2011.16.41.png" size="18" caption="Definir como Causa Raiz" position="center" signedSrc="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/fNVo-KJWofXulu_ZaEKqN_Screen%20Shot%202021-01-10%20at%2011.16.41.png?AWSAccessKeyId=AKIAYQNQCIXNIQWBC56C&Expires=1697897241&Signature=dRVQZVcWkZ4baA1CPBaBnMf5ih0%3D"}

Na inexistência da necessidade de atuação imediata, o usuário poderá clicar no botão **Suspender Incidente&#x20;**&#x71;ue se encontra logo acima à direita da listagem de alertas.



::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/TW8pkOY0RHhgEKQir2bKX_Screen%20Shot%202021-01-10%20at%2011.23.28.png" size="22" caption="Suspender incidente, primeira opção da esquerda para a direita" position="center" signedSrc="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/TW8pkOY0RHhgEKQir2bKX_Screen%20Shot%202021-01-10%20at%2011.23.28.png?AWSAccessKeyId=AKIAYQNQCIXNIQWBC56C&Expires=1697897241&Signature=kLVqZt5fXbz6txAQg9G5vfaj7DY%3D"}

Após finalizar, a operação poderá ser ecerrada manualmente através do botão que se encontra próximo ao botão Suspender Incidente, já citado.



::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/q7spOAibL7uV7JU3bEmra_Screen%20Shot%202021-01-10%20at%2011.23.28.png" size="26" caption="Concluir manualmente, primeira opçãoda direita para esquerda" position="center" signedSrc="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/q7spOAibL7uV7JU3bEmra_Screen%20Shot%202021-01-10%20at%2011.23.28.png?AWSAccessKeyId=AKIAYQNQCIXNIQWBC56C&Expires=1697897241&Signature=eI1P%2BTHOpM8IGZu7kBUtv2Sx104%3D"}

## Sugerir Pipe

No botão **Sugerir pipe** que se encontra ao lado do botão Mover Alertas é possível escolher o fluxo de automação (:Link[Pipes e Automação]{href="https://docs.citsmart.com/aiops/pipes-e-automacao" newTab="true" hasDisabledNofollow="false"}) mais indicado para o alerta selecionado

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/2y2DhcjFkIj96PjbrnyJJ_Screen%20Shot%202021-01-09%20at%2017.38.14.png" size="24" caption position="center" signedSrc="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/2y2DhcjFkIj96PjbrnyJJ_Screen%20Shot%202021-01-09%20at%2017.38.14.png?AWSAccessKeyId=AKIAYQNQCIXNIQWBC56C&Expires=1697897241&Signature=Q4NVDlyAAgUJa%2F7bJ4ozvM%2B39xs%3D"}

## Habilitar para Treino

Caso o incidente esteja agrupado adequadamente é possível habilita-lo para treino uilizando o botão **Habilitar para Treino**, que se encontra no canto superior direito da tela, acima da lista de alertas.

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/MHUgmjK6dR8l6Ds367C5F_Screen%20Shot%202021-01-09%20at%2017.41.19.png" size="40" caption position="center" signedSrc="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/MHUgmjK6dR8l6Ds367C5F_Screen%20Shot%202021-01-09%20at%2017.41.19.png?AWSAccessKeyId=AKIAYQNQCIXNIQWBC56C&Expires=1697897241&Signature=pP%2BbRzd7Hg6YkvPAQi8DJSpSNyo%3D"}

Ao selecionar essa opção permitirá que o AIOPS se torne cada vez mais assertivo na identificação de padrões utiliza de IA e ML para aprender a cada novo processo ocorrido. E com isso ampliar a capacidade de predição e automação d plataforma.

### Visualização da Topologia de Rede e Relacionamentos via CMDB

A plataforma permite a visualização da topologia de rede por meio de um mapa dinâmico de relacionamentos entre Itens de Configuração (ICs), extraídos automaticamente da plataforma de AIOps ou definidos manualmente. Essa visualização gráfica e interativa proporciona uma compreensão abrangente do ecossistema técnico, facilitando a gestão de infraestrutura, serviços e dependências críticas.

Funcionalidades disponíveis:

- Exibição individual de cada Item de Configuração, com detalhes como:
- Capacidade operacional;
- Nível de criticidade;
- Relacionamentos ascendentes e descendentes;
- Identificação visual de ICs críticos, com destaque específico para facilitar a análise de impacto e a tomada de decisões;
- Visualização em tempo real das conexões entre componentes, permitindo simulações e diagnósticos mais eficazes.

### Benefícios operacionais:

Apoio à alta disponibilidade: A marcação de ICs críticos permite que o administrador do CMDB direcione ações específicas, como:

- Definição de estratégias de contingência;
- Aplicação de regras de continuidade de serviço;
- Configuração de automações e monitorações ampliadas;
- Gestão proativa e preventiva: O mapa facilita a antecipação de falhas, identificação de pontos de falha únicos (SPOFs) e a priorização de investimentos em infraestrutura;
- Conformidade do CMDB: O uso contínuo desse recurso fortalece a governança e garante a integridade e a confiabilidade das informações mantidas no repositório de configuração.


[title] Agendamentos
[path] Infraestrutura/

É possível checar todas a métricas coletadas em seu ambiente através do painel de configuração do Atmos:&#x20;

## Acesso&#x20;

Para acessar a aplicação Atmos é necessário clicar no botão "aplicações" localizado no canto inferior esquerdo, do menu principal no AIOPS.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/qpr-FybYVVmqbebYaBDz_/kl449jrlNoKUOOT5jCKTD_image.png" signedSrc size="36" width="201" height="72" position="center" caption}

Após acessar o Atmos é necessário acessar a tela de configurações através do menu principal:

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/qpr-FybYVVmqbebYaBDz_/yQyxVBfA2F_a33HOFappn_image.png" signedSrc size="10" width="82" height="814" position="center" caption}

Ao acessar a tela de infraestrutura será possível ver selecionar a opção "Métricas" (disponível no menu interno ao lado esquerdo) e acessar as métricas disponíveis:

![](https://archbee-image-uploads.s3.amazonaws.com/qpr-FybYVVmqbebYaBDz_/mnJCEuzhe4eQauWLvERrb_image.png)


[title] Painel (Dashboard)
[path] Infraestrutura/

Observe as métricas fundamentais do seu negócio em nossas dashboards.

As dashboards do AIOPS possibilitam uma visão geral das principais métricas de sua operação/negócio.

Crie Dashboards Customizadas, acompanhe os seus principais ICS ou sua operação, acompanhando diferentes métricas coletadas no AIOPS, possibilitando uma visão gerencial totalmente personalizada:



![](https://archbee-image-uploads.s3.amazonaws.com/qpr-FybYVVmqbebYaBDz_/Oue4acR7sNJ3a1Jt1KoXQ_image.png)

É possível filtrar a dashboard por períodos, como por exemplo, os últimos 7 dias, utilizando o componente de filtro de datas:&#x20;

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/qpr-FybYVVmqbebYaBDz_/BWOEwHyth2H9zIq59G42l_image.png" signedSrc size="44" width="325" height="407" position="center" caption}

Para criar uma nova Dashboard, você pode clicar no botão:

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/qpr-FybYVVmqbebYaBDz_/Reoq5hBYrHkqTWaF2BnaM_image.png" signedSrc size="60" width="258" height="45" position="center" caption}

Para favoritar uma dashboard, você pode utilizar este botão:



::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/qpr-FybYVVmqbebYaBDz_/VvtZXOvdB85TkyFwjGSax_image.png" signedSrc size="60" width="235" height="47" position="center" caption}


[title] SLAs
[path] AIOps/

A plataforma AIOPS permite a configuração de informações de SLA para diferentes iniciativas como Serviço de TI, Incidentes, Uptime e etc.

## Incidentes

Para configuração de SLAs para incidentes é possível acessar a tela de ajustes na funcionalidade de configurações no AIOPS e após isso utilizar a opção de configurações de organização.

![](https://archbee-image-uploads.s3.amazonaws.com/qpr-FybYVVmqbebYaBDz_/smcjaNJ-yfe82N3taLJ7u_image.png)

## Uptime

Através do modulo de Infraestrutura, é possível definir horários de atentimento para que possa haver cálculos para dashboards interativas onde é possível acompanhar SLAs, e também para o cálculo de SLAs na funcionalidade de serviço de TI. O uptime pode ser utilizado para acompanhamento de qualquer serviço, seja externo via canais ou interno via dashboards, que precise ser gerenciado.

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/WzKhUpiAK2c4WuGycBkNA_screen-shot-2021-06-16-at-180221.png)


[title] Monitor de Network
[path] Infraestrutura/

# Mapa de Rede

O Atmos processa todos os dados coletados da rede em diferentes protocolos e permite o isolamente das informações em várias camadas, na forma&#x20;

## Visão geral

O mapa de rede fornece uma visão da topologia de sua rede para ajudá-lo a visualizar as partições, dependências e gargalos da rede. Ao consolidar os dados da rede em um mapa direcional, esta página pode ser usada para eliminar o ruído e isolar as áreas problemáticas.

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/Mw8JVIbX4CbPvjyY1sizO_screen-shot-2021-06-17-at-195809.png)


[title] Compartilhamento Automático
[path] AIOps/

O compartilhamento automático poderá ser realizado utilizando um dos grupos a seguir.

### [Integração](https://docs.citsmart.com/aiops/compartilhamento-automatico#0GGNQcU1zxIKAg7kbePd_)

### [Automação (Pipes)](docId\:kCwm2TXkZqxfs7UTHsvmh)


[title] Sphere Agent
[path] Visão Geral do Sistema/Zones/

Sphere-agent é uma ferramenta essencial para o monitoramento e gerenciamento proativo de seus ambientes de TI. Projetado para ser instalado como um **serviço nativo** em sistemas operacionais **Windows e Linux**, ele opera de forma discreta e eficiente, garantindo a coleta contínua de dados e a execução de tarefas críticas.

### Funcionalidades Principais

Este agente desempenha um papel multifacetado em sua infraestrutura, oferecendo três capacidades cruciais:

- **Coleta de Métricas do Ambiente:** O agente é responsável pela coleta abrangente de diversas métricas de desempenho e utilização dos servidores e estações de trabalho. Isso inclui, mas não se limita a, uso de CPU, memória, disco, tráfego de rede e status de serviços. Esses dados são fundamentais para o acompanhamento da saúde do sistema, identificação de gargalos e planejamento de capacidade.
- **Execução de Automação Remota:** Com o agente, é possível orquestrar e executar **tarefas de automação remotamente**, eliminando a necessidade de intervenção manual direta nos sistemas. Isso abrange desde a execução de scripts para manutenção rotineira, aplicação de patches, reinício de serviços até a implantação de softwares, otimizando a produtividade e reduzindo erros humanos. Todo a comunicação é criptografada de ponta a ponta para garantir a máxima segurança.
- **Captura de Informações de Inventário:** O agente realiza uma varredura detalhada dos sistemas onde está instalado para **coletar informações de inventário de hardware e software**. Isso inclui dados como modelo e número de série do equipamento, configuração de rede, sistemas operacionais e suas versões, softwares instalados, licenças e atualizações. Essas informações são cruciais para a gestão de ativos, conformidade e planejamento de upgrades.

### Compatibilidade de OS:

O Sphere Agent funciona nas versões Linux (Oracle/CentOS/RHEL/Ubuntu/SUSE/Amazon Linux) e Windows (2008 ou superior) de 64 Bits. Confira mais detalhes na seção Requisitos do Sistema.

## Procedimento de instalação:

Antes de começar, vamos entender a estrutura dos arquivos do agent:

```shell
sphere-agent/                 # raiz do agent
             plugins/         # diretorio dos plugins do sphere
             queue/           # diretorio temporario de metricas
             atmosphere.yaml  # arquivo de configuração principal
             config.yaml      # arquivo de configuração de coleta
             sphere-agent.log # arquivo de log do agent
```

### Arquivo de configuração (atmosphere.yaml)

Esta é a principal configuração que determina qual o servidor do AIOPS na rede e atributos essenciais do host como permissão de automação e configuração automática do arquivo de coleta *config.yaml.*

Modificar:&#x20;

- Hostname: Modificar para o IP do host;
- Port: Modificar para a porta 80

Adicionar ao arquivo:

- path: /sphere-sync
- scheme: http

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/QeP-GQyL689grWgiRoNXk_image.png)

### Arquivo de configuração (config.yaml)

Determina a configuração dos plugins, períodos de coleta, proxy, etc. Este arquivo é configurado automaticamente através do Atmos (exige a configuração antecipada do *atmosphere.yaml*).

Modificar:&#x20;

- Hostname: Modificar para o IP do host;
- Port: Modificar para a porta 80

Adicionar ao arquivo:

- path: /sphere-sync

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/cgbhHiZAy-xz8A7yozS6o_image.png)

### Requisitos para instalação

- Espaço livre:**&#x20;500mb** (mínimo recomendado)
- Volume de instalação:
  - Linux: **/opt**
    - Sub-diretório: /sphere-agent-linux 
  - Windows: **C:/ProgramData/65A**
    - Sub-diretório: /sphere-agent-windows&#x20;

### Repositórios e Distribuição

**Repositório Cloud AWS/S3:** :Link[https://65a-internal-sa.s3-sa-east-1.amazonaws.com/repo/latest]{href="https://65a-internal-sa.s3-sa-east-1.amazonaws.com/repo/latest" newTab="true"}, este repositório é recomendado para obter a versão mais recente dos agents, sendo necessária a configuração manual dos arquivos (*config.yaml* e *atmosphere.yaml*).

**Ambiente on-premise:** utilize o formato de url http\://**



## Instalação Automática&#x20;

Procedimento recomendado e disponivel a partir da versão 3.0.0+.

### On-premises e Agent pré-configurado

Para realizar a *primeira instalação* e principalmente nas *distribuições* *on-premises,* é recomendado substituir o endereço apontando para a url do servidor principal do AIOPS, desta forma o download será realizado na rede interna e o agent estará automaticamente configurado para este ambiente.

:::hint{type="warning"}
## Recomendação de atualização

Recomendamos que antes da atualização do agent verifique o espaço em disco disponível e confirme se a URL utilizada condiz com o tipo de instalação desejada.&#x20;
:::

### Linux (64 bits): &#x20;

Execute uma das opções de comando abaixo no terminal, a instalação será iniciada e exibirá o log do progresso no console.

```shell

# (Opção 1) Utilizando curl
curl -k http://<aiops-master-node>/repo/update-sphere-agent.sh | sudo sh

# (Opção 2) Utilizando wget
wget -O - http://<aiops-master-node>/repo/update-sphere-agent.sh | sudo sh

```

Com este mesmo comando é possível realizar a atualização do agent quando disponível, um aviso será observado na tela de Infraestrutura do Atmos.

### Windows (64 bits):&#x20;

Faça o download do arquivo no repositório do AIOPS através da url como no exemplo: http\://**

Execute o PowerShell como Administrador e rode o comando abaixo:

```powershell

# Acesse a pasta onde encontra-se o arquivo baixado e execute o comando: 
powershell.exe -ExecutionPolicy Bypass -File .\update-sphere-agent.ps1

```

***

## Instalação Manual

### Windows (64 bits): &#x20;

1. Faça o download do Agent para Windows:[https://65a-internal-sa.s3.sa-east-1.amazonaws.com/repo/latest/sphere-agent-windows\_x64.zip](https://65a-internal-sa.s3.sa-east-1.amazonaws.com/repo/latest/sphere-agent-windows_x64.zip)
2. Salve o arquivo na pasta de serviços desejados, recomendamos a pasta: C:\ProgramData\65A
3. Descompacte o arquivo baixado (se houver, escolha a opção "Extrair Aqui”)
4. Acesse a pasta criada e execute o arquivo no PowerShell:.\install-service.ps1
5. Confirme no gerenciador de serviços do Windows se o processo “sphere-agent” foi iniciado, caso contrário, inicie o serviço.
6. Reiniciar o serviço (após modificar o config.yaml), no PowerShell:&#x20;
   Restart-Service -Name "sphere-agent"

### Linux (64 bits): &#x20;

1. Faça o download do Agent para Linux:*wget -O /opt/sphere-agent-linux.tar.gz&#x20;*[https://65a-internal-sa.s3.sa-east-1.amazonaws.com/repo/latest/sphere-agent-linux\_x64.tar.gz](https://65a-internal-sa.s3.sa-east-1.amazonaws.com/repo/latest/sphere-agent-linux_x64.tar.gz)
2. Salve o arquivo na pasta de serviços desejados, recomendamos uma das pastas: /opt/
   /srv/
   /usr/src
3. Descompacte o arquivo na pasta ou via comando no terminal:  tar -zxvf sphere-agent-linux\_x64.tar.gz
4. Acesse a pasta criada e execute o comando no terminal\:sudo bash ./install-service.sh
5. Confirme o status do serviço rodando um dos comandos no terminal\:sudo systemctl status sphere-agent
6. Reiniciar o serviço no terminal (após modificar o arquivo config.yaml)\:sudo systemctl restart sphere-agent

:::hint{type="warning"}
## Arquivos de configuração

Confira o arquivo config.yaml se a seção output.server foi configurada corretamente. Caso já tenha iniciado o serviço, realize as mudanças no arquivo config.yaml e em seguida reinicie o serviço.
:::

Exemplo do **atmosphere.yaml**

```yaml

apiVersion: v1                      # versão da api do AIOPS
kind: Host                          # tipo do item de configuração
metadata:
  namespace: default                # namespace deste host
  domain: "<root-domain>"           # nome do dominio raiz
  annotations:                      # anotações locais do host
    atmosphere/host.services: '[]'  # lista de serviços mapeados
config:
  hostname: "127.0.0.1"             # ip/hostname do AIOPS
  api_key: "<atmosphere-api>"       # chave da api
  scheme: http                      # (opcional) se utilizar SSL / Default http
  port: 18001                       # SSL - 443, Default 18001
  path: /sphere-sync                 
  path: /                           # /sphere-sync (se utilizar proxy 80/443)
  agent:                            # configurações do agent local
    self_update: true               # atualizações automáticas do agent

```

Com este arquivo presente na pasta de configuração será possível controlar as configurações do agent remotamente (via *Atmos*).

## Remoção do agent&#x20;

### Linux

```shell
# Utilize o arquivo uninstall.sh para remover o agent
sudo bash /opt/sphere-agent-linux/uninstall.sh

# Remover as pastas do agent
rm -rf /opt/sphere-agent-linux*

# Bonus: Se o atmosphere (módulo de automação) tiver instalado:
# Remover as pastas do atmosphere
rm -rf /opt/.atmosphere

```

:::hint{type="warning"}
**Aviso:** Cuidado ao utilizar o comando "**rm -rf \*\*\***" apontando somente as pastas do agent informadas acima.&#x20;
:::

### Windows

Ao utilizar o instalador ".msi" você poderá desinstalar o agent no gerenciador de programas do próprio Windows.
Ou então poderá seguir para a remoção via script (*uninstall.ps1*) presente na pasta do agent:

```powershell
# Desinstalar o Agent
powershell.exe -ExecutionPolicy Bypass -File C:\ProgramData\65A\sphere-agent\uninstall.ps1
```



***

# Atmosphere

O Atmosphere é o módulo adicional que se conecta ao *Sphere Agent* instalado na máquina e fornece as ferramentas necessárias para execução de rotinas de automação/recuperação de processos e serviços.&#x20;

### &#xA;Compatibilidade de OS:

O Atmosphere funciona em todas as versões Linux compatíveis com *Sphere Agent*. Para as versões Windows há somente *disponibilidade parcial* de algumas distribuições.

### Requisitos para instalação

- Espaço livre:**&#x20;500mb** (mínimo recomendado)
- Diretório de Instalação: **/opt**/.atmosphere

***

## Instalação Automática&#x20;

### Linux (64 bits): &#x20;

Execute uma das opções de comando abaixo no terminal, a instalação será iniciada e exibirá o log do progresso no console.

```shell

# (Opção 1) Utilizando curl
curl -k http://<aiops-master-node>/repo/install-atmosphere.sh | sudo sh

# (Opção 2) Utilizando wget
wget -O - http://<aiops-master-node>/repo/install-atmosphere.sh | sudo sh

```

Após a instalação o AIOPS irá detectar e exibir automaticamente em suas soluções que o módulo está disponível no Item de Configuração relacionado.

***

### Utilização de Recursos do Agent

| **Resource**      | **Idle**   | **Load**        |
| ----------------- | ---------- | --------------- |
| Disk              | -          | 170mb           |
| CPU (single core) | \< 0,5%    | 3,5% max        |
| Memory            | 32mb       | 50mb max        |
| Network           | 0,5 KB/sec | 10,9 KB/sec max |


[title] Permissões por Roles
[path] AIOps/Usuários/

O AIOPS utiliza as seguintes *roles* por padrão (em ordem de nível de acesso):

- **Administrador**
- **Analista**
- **Gestor**
- **Supervisor**
- **Operador**

Disponibilizamos *roles* especiais que *não possui permissão para entidades*, exceto nos seguintes contextos:

- **Monitor**
  - Acesso exclusivo às Dashboards (previamente autorizadas)
- **Sem Perfil**
  - Acesso exclusivo à tela do seu perfil (sem permissão extra)


[title] Application Performance Management
[path] APM/

Visualize toda sua infraestrutura de aplicação, identificando gargalos, falhas, lentidões e o comportamento dos usuários.

O Divedot tem uma abordagem integrada de observação por meio de análises de contextos e desempenho das aplicações.

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/PpJWe20byMwgmRKsAOjzu_capturadivedot65a.PNG)

Suporta o gerenciamento de aplicações e serviços críticos disponibilizando:

- Tempo de resposta;
- Consumo de CPU e memória por aplicação;
- Gerenciamento inteligente das sessões (requisições, filas, exceções e conexões com o banco de dados);

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/wBjYjy7a1AdptDBiztYax_capturadivedot65ausuario.PNG)

- Gerenciamento integrado da infraestrutura (consumo de rede - throughput, latência, locks em databases);
- Mapeamento de dependências entre os serviços

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/sTG2CMlUlvodbckT57ulc_capturadivedot65alock-de-banco.PNG)

- Dashboard customizado por aplicação.

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/_Ma7YfO_x6vILtBKtYrSL_capturadivedot65aservico.PNG)

- Descoberta automática da topologia da aplicação.

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/hcro8MyXATeWSDXy9fpv4_image.png)


[title] Segredo
[path] Infraestrutura/

O cadastro das credenciais e feito a partir das **Configurações**, em cofre selecione a opção **Segredos**:

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/thF7_BaJQJAhgkNRFARFw_image.png" size="24" width="180" height="58" caption position="center" signedSrc="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/thF7_BaJQJAhgkNRFARFw_image.png"}

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/_K9JLSktlW8acWAcC6PmS_image.png" size="32" width="244" height="79" caption position="center" signedSrc="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/_K9JLSktlW8acWAcC6PmS_image.png"}

Após a seleção, será exibida a listagem de segredos cadastrados:

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/TWAHX_Wd-idRw0A5Jv1iY_captura-de-tela-2023-10-17-as-84041-am.png)

Para cadastrar um novo segredo clique em **Novo segredo**

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/2H6aSyYsKMwzWit9D1u6p_image.png" size="26" width="163" height="54" caption position="center" signedSrc="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/2H6aSyYsKMwzWit9D1u6p_image.png"}

Após a seleção será exibido o seguinte formulário:

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/gB9sTj4jS33PzXrjDZz-S_image.png)

Na aba **Geral** temos:

- **Nome**: Nome para a credencial a ser cadastrada;
- **Perfis que podem alterar**: Quais perfis de usuário podem modificar o conteúdo da credencial;
- **Perfis que podem visualizar**: Quais perfis de usuário podem visualizar o conteúdo da credencial
- **Descrição**: Descrição da credencial

Na aba **Chaves de acesso** temos a opção para criar as chaves no botão **Nova chave**:

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/DE9txL6Y0cv7aTGNoDh_o_image.png)

Ao clicar em Nova chave o seguinte formulário é exibido, crie a chave e seu valor:

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/NFOo0btJp62Q5iXGJ3Rkd_image.png" size="56" width="512" height="358" caption position="center" signedSrc="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/NFOo0btJp62Q5iXGJ3Rkd_image.png"}

Salve o segredo:

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/-Uqw2C7KoFT7ywRHMy-Vc_image.png)


[title] Portas e Serviços por Instância
[path] Visão Geral do Sistema/Zones/

## Instalar e configurar as dependências

```shell
curl -ksSL https://repo.aiops.com/deployments/installer/aiop-managed-install -o - | sudo bash
```

O comando acima irá instalar/configurar os seguintes itens:

- Instalação dos repositórios principais (Ex: epel-release, docker-repo, etc)
- Configurações do kernel (sysctl)
- Instalação do Python3 (para uso do aiopsctl)
- Instalação do Docker + Docker Compose
- Preparação do disco (/dados)
- Aiops Client (aiopsctl)

:::hint{type="warning"}
Observar se apos o comando acima (*aiops-managed-install.sh*), as versões correspondentes estão de acordo com a referência abaixo:
:::

## Versões exigidas no repositório

| **Produto**   | **Versão minima** | **Comando**      |
| ------------- | ----------------- | ---------------- |
| Docker Engine | 19.+              | `docker version` |
| Python        | 3.6.8+            | `python3 -V`     |

## AIOPS Control *(aiopsctl)*

Utilize os comandos a seguir para instalar/atualizar o cli `aiopsctl`

```shell
# para realizar a instalação:
curl -ksSL https://repo.aiops.com/deployments/setup -o - | bash -s update

# para realizar a atualização (quando necessário):
aiopsctl update
```

## Standalone *(singlenode)*

&#x20;Caso esteja utilizando o modo em Standalone o comando a seguir deverá ser utilizado:

```shell
aiopsctl standalone
```

Neste comando será realizado a instalação dos seguintes itens na mesma máquina (*singlenode*):

- Instalação da **masternode &#x20;**
- Instalação da **dbworker**
- Instalação do **proxy**

Caso seja necessário instalar os demais serviços (opcionais): **atomworker** e **traceworker.&#x20;**&#x56;ocê poderá conferir a seguir a instalação dos servidores 3 e 4).&#x20;

***

# Distributed

# Servidor #&#x31;*&#x20;(master-node)*

1 - Instala os serviços da master-node

```shell
sudo aiopsctl masternode
```

2 - Configurar variaveis de Ambiente (aiops.env):

```shell
sudo vi /dados/etc/aiops.env
```



3 - Prepara banco de dados (inicialização):

```shell
sudo aiopsctl database
```

4 - Realiza a migração de tabelas (*database schema*):

```shell
sudo aiopsctl migrate
```

5 - Inicia a configuração da licença:

```shell
sudo aiopsctl license
```

6 - Inicia os serviços essenciais:

```shell
sudo aiopsctl start_services
```

7 - Instalação do proxy (base):

```shell
sudo aiopsctl proxy
```

8 - Instalação do proxy-cert Let's Encrypt *(opcional)*:

```shell
sudo aiopsctl proxycert
```

&#x20;9 - Instalação do grafana *(opcional)*:

```shell
sudo aiopsctl grafana
```

10 - Configura repositório dos Agents:

Seguir com a configuração: [Sphere Agent](docId:-IjoB146AQpQDsz0mOPwe)&#x20;

# Servidor #2 *(db-worker)*

1 - Instala os serviços da db-worker:

```shell
sudo aiopsctl dbworker
```

2 - Inicia os serviços:

```shell
sudo aiopsctl start_services
```

# Servidor #3 *(atom-worker)*

:::hint{type="info"}
Ao seguir os passos abaixo, você será capaz de implantar e configurar uma instância Atom Worker com sucesso. **A instalação pode ser realizada em múltiplos ambientes separados do AIOPS, permitindo executar coletas de forma isolada**.
:::

### **1 - Instala os serviços da atom-worker:**

Para começar, você precisará instalar os serviços Atom Worker. Siga os seguintes passos:

```shell
sudo aiopsctl atomworker
```

Este comando instalará os serviços Atom Worker no seu sistema.

### **2 - Configura variaveis de ambiente (atom.env):**

Agora, é necessário configurar as variáveis de ambiente para a instância Atom Worker. Abra o arquivo **'atom.env'**&#x63;om um editor de texto. Neste exemplo, usaremos o editor **'vi'**, mas você pode usar qualquer editor de texto de sua preferência:

```shell
sudo vi /dados/etc/atom.env
```

Dentro do arquivo **'atom.env'**, :Link[configure as variáveis de ambiente]{href="https://docs.simonops.com/knowledge-base-internal/dependencias-de-ambiente#2j2Ql" newTab="true" hasDisabledNofollow="false"} necessárias para a instância Atom Worker, como URLs, chaves de autenticação ou quaisquer outras configurações específicas do seu ambiente. Certifique-se de salvar as alterações após a configuração.

### **3 - Inicia os serviços:**

Após configurar as variáveis de ambiente, você pode iniciar os serviços da instância Atom Worker. Execute o seguinte comando:

```shell
sudo aiopsctl start_services
```

Isso iniciará os serviços Atom Worker com base nas configurações que você definiu no arquivo **'atom.env'**. Certifique-se de que os serviços estejam em execução corretamente.

# Servidor #4 - APM Worker

1 - Instala os serviços da apm worker (APM):

```shell
sudo aiopsctl apmworker
```

 2 - Configura variaveis de ambiente (trace.yaml):

```shell
sudo vi /dados/etc/trace.yaml
```

- Adicionar ao arquivo a chave de acesso gerado no Atmos: (Página: /atmos/settings/group-api-key)
- Modificar o ip do hostname, para o ip do Server da Masternode

3 - Configura variaveis de ambiente no arquivo (/dados/etc/divedot-agent.env):

- Adicionar ao arquivo a chave gerado no Divedot (Página: /divedot/settings/api-keys)

4 - Inicia os serviços:

```shell
sudo aiopsctl start_services
```

***

# Instalando Agent Linux

Para mais informações sobre a instalação e configuração dos agents, acesse o link: [Sphere Agent](docId:-IjoB146AQpQDsz0mOPwe)&#x20;

### Instalando o agent:

```shell
curl -k http://HOST-OU-IP-DO-AIOPS/repo/update-sphere-agent.sh | sudo sh
```

Caso o firewall bloqueie (.sh) utilizar a extensão -linux.txt:

```shell
curl -k http://HOST-OU-IP-DO-AIOPS/repo/update-sphere-agent-linux.txt | sudo sh
```

# Instalando Agent Windows

### Baixe o arquivo para o diretório e rode o comando no Powershell:

http\://HOST-OU-IP-DO-AIOPS/repo/update-sphere-agent.ps1

```shell
powershell.exe -ExecutionPolicy Bypass -File .\update-sphere-agent.ps1
```

Este documento descreve o processo de instalação, configuração e ativação do módulo de inventário (**Xventory**), bem como a instalação de seus agentes em diferentes sistemas operacionais.

# Instalando XVentory

### Parte 1: Preparação dos artefatos para configuração da Integração com AIOps

*Antes* de instalar o módulo, é necessário configurar a comunicação entre a plataforma AIOps e o Xventory.

1. **Gerar Chave de API no AIOps:**
   - Acesse a área de configurações de API da sua plataforma AIOps (https\://\<seu-dominio-aiops>/simon/settings/group-api-key), e gere a chave conforme descrito na documentação:
     - [Chaves de acesso](docId:50FPEoTsUlrG0U92onxCG)&#x20;
   - Crie uma nova chave de API com perfil de administrador. Dê um nome descritivo, como por exemplo `webhook-inv-api`. Guarde o valor da chave gerada para os próximos passos.

### Parte 2: Instalação do Módulo Xventory

Com as configurações da plataforma AIOps prontas, prossiga com a instalação do módulo.

1. **Executar o Instalador:**
   - Execute o comando de instalação do inventário
     ```bash
     simonctl inventory
     ```
2. **Configurar Arquivos de Ambiente:**
   - O instalador criará links simbólicos para os arquivos de configuração. O principal é o `/dados/etc/x.env`, que é linkado em `/opt/apps/simon/docker-inventory/x.env`.
   - Edite o arquivo `/dados/etc/x.env` e preencha as seguintes variáveis:
     ```bash
     # URL da API do OCS (geralmente aponta para o IP do container Master)
     OCS_API_URL=http://<ip-do-servidor-master>/ocsapi/v1 

     # Chave de API gerada no AIOps para permitir a comunicação
     X_API_KEY_ALLOWED=<sua-api-key> 

     # URL do Webhook para onde o inventário enviará os dados (DESCOMENTAR E ALTERAR)
     WEBHOOK_URL=https://<events-endpoint>/events/webhook/<webhook-id> 
     ```
   - No arquivo /dados/etc/simon.env, verifique se as variáveis para o webhook do inventário estão configuradas. Elas geralmente vêm comentadas:
   - ```bash
     # Webhook inventory
     WEBHOOK_INVENTORY_API_KEY=<sua-api-key> 
     WEBHOOK_INVENTORY_URL="http://localhost/inventory/api/sync/webhook/simon/"
     ```
3. **Configurar e Iniciar os Serviços Docker:**
   - Descomente a seção do serviço inv-clickhouse para habilitar o banco de dados do inventário. As portas `8123` e `9000` serão expostas.
   - No mesmo diretório (`/opt/apps/simon/docker-inventory/`), suba os containers:
     ```bash
     docker compose up -d
     ```
   - Verifique se todos os containers estão em execução:
   - ```bash
     docker ps -a
     ```

### Parte 3: Instalação dos Agentes de Inventário

Veja mais em [Sphere Agent](docId:-IjoB146AQpQDsz0mOPwe)&#x20;

[title] APM
[path] AIOps/Usuários/

## Funcionalidades

|                                                                                                            | **Administrador** | **Analista** | **Gestor**      | **Supervisor**  | **Operador** |
| ---------------------------------------------------------------------------------------------------------- | ----------------- | ------------ | --------------- | --------------- | ------------ |
| **Traces**                                                                                                 | Acesso total      | Acesso total | Somente leitura | Somente leitura | Sem acesso   |
| **Serviços**                                                                                               | Acesso total      | Acesso total | Somente leitura | Somente leitura | Sem acesso   |
| ****:Link[**RUM Explorer**]{href="https://docs.citsmart.com/aiops/real-user-monitoring" newTab="true"}**** | Acesso total      | Acesso total | Somente leitura | Somente leitura | Sem acesso   |
| **Aplicações**                                                                                             | Acesso total      | Acesso total | Somente leitura | Somente leitura | Sem acesso   |
| **Erros**                                                                                                  | Acesso total      | Acesso total | Somente leitura | Somente leitura | Sem acesso   |
| **Web Sites**                                                                                              | Acesso total      | Acesso total | Somente leitura | Somente leitura | Sem acesso   |



## Configurações

### Chaves

|              | **Administrador** | **Analista** | **Gestor**      | **Supervisor**  | **Operador** |
| ------------ | ----------------- | ------------ | --------------- | --------------- | ------------ |
| **API Keys** | Acesso total      | Acesso total | Somente leitura | Somente leitura | Sem acesso   |


[title] System Center (SCCM)
[path] Infraestrutura/Provedor de Recursos/

Esta configuração permite a coleta de dados do SCCM através do **sphere-agent**, utilizando um script PowerShell específico para capturar métricas do servidor SCCM e enviar esses dados ao Telegraf no formato **InfluxDB**. Isso possibilita a análise e monitoramento das métricas do SCCM.

1. Permissão para adicionar scripts ao diretório do **sphere-agent**.
2. Detalhes de conexão do **SCCM**: nome do servidor SQL, nome do banco de dados, ID das coleções de servidor e estação de trabalho, e credenciais de acesso.
3. Faça o download do script PowerShell que será utilizado para coletar dados do SCCM:
   - Abra o script **Export-SCCMToTelegraf.ps1** no editor de texto de sua preferência, localize a linha onde a variável **$Password** está definida.
   - Substitua o valor pela senha do usuário com permissões para acessar o banco de dados SCCM.
4. Acesse a interface de gerenciamento do **sphere-agent** através do console **Atmos** -> **Infraestrutura&#x20;**->**&#x20;Detalhamento do IC&#x20;**->**&#x20;Configuração do agent&#x20;**&#x65; adicione a seguinte configuração para habilitar a coleta do script PowerShell no Telegraf:

:::BlockQuote
\[\[inputs.exec]]
&#x20; commands = \["powershell -File C:/ProgramData/65A/sphere-agent/Export-SCCMToTelegraf.ps1 -SQL\_Server SERVER\_NAME -Database DB\_NAME -Server\_Collection SERVER\_COL\_ID -Workstation\_Collection WORKSTATION\_COL\_ID -Username USERNAME"]
&#x20; interval = "15m"
&#x20; timeout = "30s"
&#x20; data\_format = "influx"
:::

- **\[\[inputs.exec]]**: Este é o plugin do Telegraf que executa comandos ou scripts externos.
- **commands**: O comando executado pelo Telegraf, que chama o PowerShell para rodar o script **Export-SCCMToTelegraf.ps1** com os parâmetros de conexão do SCCM:
  - **SQL\_Server**: Nome do servidor SQL que hospeda o banco de dados do SCCM.
  - **Database**: Nome do banco de dados SCCM.
  - **Server\_Collection**: ID da coleção de servidores que será monitorada.
  - **Workstation\_Collection**: ID da coleção de estações de trabalho que será monitorada.
  - **Username**: Nome de usuário que terá permissões para acessar o banco de dados SCCM.
- **interval**: Define o intervalo de tempo entre as execuções do script. O exemplo coleta as métricas a cada 15 minutos (15m).
- **timeout**: Tempo máximo de execução do script antes de ser cancelado, definido aqui como 30 segundos (30s).
- **data\_format**: Define o formato dos dados de saída, neste caso, **InfluxDB** (influx), para que as métricas sejam enviadas e armazenadas no banco de dados InfluxDB.

Após realizar os procedimentos, preencha os **Detalhes da Descoberta** selecionando como **Host de Origem&#x20;**&#x6F; IC utilizado na configuração.

[title] Provedor de Recursos
[path] Infraestrutura/

A tela "Provedor de Recursos" permite a configuração de integrações com diversos serviços externos para realizar a importação de ativos, como máquinas virtuais (VMs) e outros recursos, para dentro do AIOPS. Essa funcionalidade facilita a descoberta automatizada de novos ativos.

Para criar uma nova descoberta, basta ir em **Configurações** -> **Provedor de Recursos&#x20;**&#x65; clicar em **Nova Descoberta**.

1. **Nome da Integração**
   - **Campo:** Nome
   - **Descrição:** Defina um nome para identificar a integração de descoberta. Este nome será utilizado para referenciar a integração no sistema.
2. **Tipo de Serviço**
   - **Campo:** Tipo de Serviço
   - **Descrição:** Selecione o serviço de origem dos recursos que serão importados para o inventário. As opções incluem:
     - **VMWare vCenter:** Integração para importação de máquinas virtuais do ambiente VMWare.
     - **Kubernetes:** Integração para descoberta de deployments, nós e outros ativos de um ambiente Kubernetes.
     - **System Center:** Integração com o Microsoft System Center para coleta de informações sobre os ativos gerenciados.
     - **Hyper-V:** Integração para importação de VMs e outros recursos do ambiente Hyper-V.
3. **Agendamento**
   - **Campo:** Agendamento
   - **Descrição:** Defina a frequência com que a descoberta de novos recursos será executada. Isso pode ser configurado para rodar em intervalos pré-determinados, garantindo que o inventário esteja sempre atualizado.
4. **Descrição&#x20;**(Opcional)
   - Descrição breve sobre a Descoberta que será criada.
   - **Configuração**
     - Ao selecionar um **Tipo de Serviço**, uma nova aba **Configuração&#x20;**&#x73;erá disponibilizada para serem preenchidos com os parâmetros da tecnologia selecionada.
5. **Salvar Configuração**
   - Após preencher todos os campos obrigatórios, clique em Salvar para criar a integração.
6. **Execução**
   - Uma vez configurado, o sistema começará a realizar as descobertas conforme o agendamento definido. Os recursos importados serão adicionados automaticamente ao inventário para que possam ser monitorados e gerenciados.




[title] VMWare Vcenter
[path] Infraestrutura/Provedor de Recursos/

A conexão com o vCenter é estabelecida por meio de credenciais fornecidas e a especificação do host do vCenter.

1. **Host** (Obrigatório)
   - **Descrição:** Insira o endereço IP ou o nome do host do servidor vCenter. Este será o ponto de conexão para realizar a descoberta dos ativos.
   - **Exemplo:** vcenter.example.com ou 192.168.0.100.
2. **Nome de Usuário** (Obrigatório)
   - **Descrição:** Forneça o nome de usuário com permissões adequadas para realizar operações de descoberta no VMware vCenter. Este usuário deve ter privilégios suficientes para acessar informações sobre as máquinas virtuais e outros ativos do ambiente.
   - **Exemplo:** admin\@vsphere.local.
3. **Senha** (Obrigatório)
   - **Descrição:** Insira a senha associada ao nome de usuário informado. Esta senha será utilizada para autenticar a conexão com o vCenter.
   - **Nota de Segurança:** A senha será armazenada de forma segura no sistema.

- **Testar Conexão**
  - **Descrição:** Ao clicar no botão Testar Conexão, o sistema irá verificar se as informações fornecidas (Host, Nome de Usuário, e Senha) são válidas e se a conexão com o servidor vCenter pode ser estabelecida. Caso a conexão seja bem-sucedida, a integração poderá ser salva.
  - **Erro Comum:** Verifique a rede e as credenciais se o teste de conexão falhar.
- **Permissões Necessárias:**


[title] OCI Monitoring Service
[path] AIOps/Integrações/Integrações com Webhook/

## Visão Geral

Configurar o Oracle Cloud Infrastructure (OCI) para enviar notificações automáticas para o AIOPs, via webhook, sempre que um evento de monitoramento (alarme) é disparado.

A solução funciona através da integração de três componentes principais do OCI:

- **OCI Monitoring Service**: Monitora métricas dos recursos da nuvem
- **OCI Events Service**: Captura mudanças de estado dos recursos
- **OCI Notifications Service**: Envia mensagens para diferentes canais, incluindo webhooks HTTPS

## 1. Criar um Tópico de Notificação

1. **Acesse o Console OCI**
   - Entre no Oracle Cloud Console.
2. **Navegue até Notificações**
   - Menu: Application Integration → Notifications.
3. **Criar Tópico**
   - Selecione o compartimento desejado.
   - Clique em Create Topic.
   - Preencha nome e descrição.
   - Clique em Create.

## 2. Configurar Subscription HTTPS (Webhook)

1. **Acesse o Tópico Criado**
   - Na página do tópico, clique em Create Subscription.
2. **Selecione Protocolo HTTPS**
   - Escolha o protocolo HTTPS (Custom URL).
   - Insira a URL do endpoint do seu webhook.
     - O endpoint deverá ser:
     - `https://<DOMINIO_AIOPS>/services/collector/event`
3. **Salve a Subscription**
   - Aguarde o recebimento do e-mail/URL de confirmação.
   - Acesse a URL de confirmação enviada ao seu endpoint para ativar a subscription (válida por 3 dias).
   - A subscription ficará ativa após a confirmação.

## 3. Configurar Alarmes de Monitoramento

1. **Navegue até Monitoramento**
   - Menu: Observability & Management → Monitoring → Alarm Definitions.
2. **Criar Alarmes**
   - Clique em Create Alarm.
   - Defina o nome do alarme.
   - Selecione a métrica desejada (namespace, nome, intervalo, estatística).
   - Configure a regra de disparo (operador, valor, delay).
   - Em Destination, selecione o tópico criado no passo 1.
   - Salve o alarme.

## 4. (Opcional) Configurar Regras de Eventos

1. **Acesse Eventos**
   - Menu: Observability & Management → Events.
2. **Criar Regra de Evento**
   - Clique em Create Rule.
   - Defina as condições do evento que deseja monitorar.
   - Configure a ação para enviar para o tópico de notificação.
   - Salve a regra.

## 5. Recebendo e Processando Notificações

- **Formato das Mensagens:**
  - O OCI envia notificações em formato JSON via POST para o seu endpoint.
  - O payload contém informações detalhadas sobre o evento/alarme.
- **Headers HTTP:**
  - Incluem metadados como ID da mensagem, nome do tópico, URL de unsubscribe, assinatura, timestamp, entre outros.
- **Validação de Assinatura:**
  - Utilize os headers fornecidos para validar a autenticidade das mensagens recebidas.

## 6. Teste e Validação

1. **Simule um Evento**
   - Dispare um alarme manualmente ou espere um evento real ser gerado.
2. **Verifique o Endpoint**
   - Confirme que o endpoint recebeu a notificação e processou corretamente.
3. **Ajuste e Monitoramento**
   - Ajuste configurações conforme necessário.
   -


[title] Coletas customizadas
[path] Métrica/

A fim de habilitar o container de coletas customizadas dentro de um ambiente Kubernetes é necessário criar e editar o seguinte artefato:

```yaml
apiVersion: v1
data:
  telegraf.conf: |
    [global_tags]
    ci_ref_id = "<CI-REF-ID>"

    [agent]
    hostname = "aiops-intelligence-instance"
    interval = "10s"
    flush_interval = "10s"
    round_interval = true
    metric_batch_size = 1000
    metric_buffer_limit = 10000
    collection_jitter = "0s"
    flush_jitter = "0s"
    precision = ""
    quiet = true
    logtarget = "stderr"
    omit_hostname = false

    [[outputs.influxdb]]
    urls = ["http://<DB-WORKER>:8086"]
    database = "metrics"
    timeout = "5s"
    username = "admin"
    password = "influx65@"
    exclude_database_tag = true

    [[inputs.***]]

kind: ConfigMap
metadata:
  name: telegraf-conf
  namespace: kube-system
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: aiops-integrations
  namespace: kube-system
  labels:
    app: aiops-integrations
spec:
  replicas: 1
  selector:
    matchLabels:
      app: aiops-integrations
  template:
    metadata:
      labels:
        app: aiops-integrations
    spec:
      containers:
        - name: aiops-integrations
          image: aiops/space-aiops-integrations-oracle
          resources:
            limits:
              memory: "200M"
          imagePullPolicy: IfNotPresent
          volumeMounts:
            - name: configs
              mountPath: /opt/config/telegraf.conf
              subPath: telegraf.conf
      volumes:
        - name: configs
          configMap:
            name: telegraf-conf

```


[title] Métricas
[path] Infraestrutura/

É possível checar todas a métricas coletadas em seu ambiente através do painel de configuração do Atmos:&#x20;

## Acesso&#x20;

Para acessar a aplicação Atmos é necessário clicar no botão "aplicações" localizado no canto inferior esquerdo, do menu principal no AIOPS.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/qpr-FybYVVmqbebYaBDz_/kl449jrlNoKUOOT5jCKTD_image.png" signedSrc size="36" width="201" height="72" position="center" caption}

Após acessar o Atmos é necessário acessar a tela de configurações através do menu principal:

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/qpr-FybYVVmqbebYaBDz_/yQyxVBfA2F_a33HOFappn_image.png" signedSrc size="10" width="82" height="814" position="center" caption}

Ao acessar a tela de infraestrutura será possível ver selecionar a opção "Métricas" (disponível no menu interno ao lado esquerdo) e acessar as métricas disponíveis:

![](https://archbee-image-uploads.s3.amazonaws.com/qpr-FybYVVmqbebYaBDz_/mnJCEuzhe4eQauWLvERrb_image.png)


[title] API Xventory
[path] AIOps/Inventário/


[title] Canais
[path] AIOps/

Os canais são uma ponte entre equipes que precisam trabalhar juntas. Em vez de intermináveis emails, tickets manuais ou lista de alertas, as equipes podem usar canais que conectam equipes e usuários para os mesmos alertas e incidentes. Esses canais permitem que os usuários interajam entre si, e facilitam a possibilidade de notificações às equipes, permitindo inclusive a atuação de líderes para a delegação de eventuais demandas.

## Acesso

Para acessar a funcionalidade de canais é necessário acessar o ícone de configurações no menu principal do AIOPS:

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/vivJML8tz8cQTepqqJ3Vw_botaoconfiguracoes.png" size="38" caption position="center" signedSrc="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/vivJML8tz8cQTepqqJ3Vw_botaoconfiguracoes.png?AWSAccessKeyId=AKIAYQNQCIXNIQWBC56C&Expires=1697895711&Signature=671KXq1QtmDZV4hKim3BHHdnrj4%3D"}

Após acessar as configurações é necessário acessar a opção canais no menu interno de opções:

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/7vYNeCg976YHDaLF_soTS_menu-configuracoes-simon.png" size="40" caption position="center" signedSrc="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/7vYNeCg976YHDaLF_soTS_menu-configuracoes-simon.png?AWSAccessKeyId=AKIAYQNQCIXNIQWBC56C&Expires=1697895711&Signature=igZJMM9hDYFVOklkDs2LNdKm%2F5o%3D"}

## Criação de Canal

Para criar um canal é clicar no botão "novo canal":

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/1u4Z-0R-5xpC2HxEzacF-_novocanal.png" signedSrc size="28" width="138" height="37" position="flex-start" caption}

Após clicar no botão, as opções de criação de canal serão exibidas em uma modal:&#x20;

::Image[]{src="https://gblobscdn.gitbook.com/assets%2F-Ls76-8XbGuboSQAg3Y9%2F-LyVO4b6AWepWpKWRXDk%2F-LyVRChYav8wUDDGxPib%2FCaptura%20de%20Tela%202020-01-13%20a%CC%80s%2016.36.18.png?alt=media&token=09c0e847-7024-4b6c-9baa-8349bf2d5e27" size="80" signedSrc="https://gblobscdn.gitbook.com/assets%2F-Ls76-8XbGuboSQAg3Y9%2F-LyVO4b6AWepWpKWRXDk%2F-LyVRChYav8wUDDGxPib%2FCaptura%20de%20Tela%202020-01-13%20a%CC%80s%2016.36.18.png?alt=media&token=09c0e847-7024-4b6c-9baa-8349bf2d5e27"}

## Filtros&#x20;

Na opção **visibilidade** é possível selecionar os times que poderam ter acesso aos incidentes e eventos do canal selecionado.

É possível selecionar as **integrações** que podem inserir eventos no AIOPS, e também a prioridade desejada na composição de filtro.

Utilizando-se de **tags** é possivel filtrar utilizando texto, com as operações de igual, diferente e wildcard. As operações de igual e diferente utilizam valores exatos como filtros, a operação de wildcard, permite com que qualquer texto possa existir onde o wildcard estiver inserido, por exemplo:

- Igual ou diferente: srv-website&#x20;
- wildcard: srv-\*

Você pode compor uma regra lógica, sem a utilização de código para criação de um filtro, dessa forma é possível organizar seus incidentes/eventos por área de infraestrutura, prioridade, integração.

Dessa forma você pode direcionar seus incidentes para as equipes que necessitam de envolvimento, sem que haja rastreamento de eventos, afinal, um incidente de alto nível já contempla todos os eventos que devem contextualizar um incidente.

Dentro de cada bloco com marcador laranja, é possível a inserção de diversos filtros para as tags que compões incidentes:

![](https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/WtLzAewNB3T0dibzOTkIk_image.png)


[title] AIOps
[path] /


[title] Alertas / Triggers
[path] Infraestrutura/

## Acesso

Para acessar a aplicação Atmos é necessário clicar no botão "aplicações" localizado no canto inferior esquerdo, do menu principal no AIOPS.

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/_dl2iGnL-Fm4SOb1vBfhr_image.png" size="46" caption position="center" signedSrc="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/_dl2iGnL-Fm4SOb1vBfhr_image.png?AWSAccessKeyId=AKIAYQNQCIXNIQWBC56C&Expires=1697908267&Signature=gvv3aSg%2F0G8ETHqww6USjeci1eU%3D"}

Após acessar o Atmos é necessário acessar a tela de alertas através do menu principal:

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/QMQTg2liBmcPb1iQvZj1M_image.png" size="46" caption position="center" signedSrc="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/QMQTg2liBmcPb1iQvZj1M_image.png?AWSAccessKeyId=AKIAYQNQCIXNIQWBC56C&Expires=1697908267&Signature=BfISNXipulPVgjyL4FwHcgbT7OY%3D"}

Ao acessar a tela de topologia será possível ver a listagem de alertas existentes:&#x20;

![](https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/_a2Y5OuWDtMS59sUJijYj_image.png)

## Criação de alertas

Para criar um alerta é necessário clicar no botão:&#x20;

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/r8bASYBx10FwVzmrsKtSh_image.png" size="28" caption position="center" signedSrc="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/r8bASYBx10FwVzmrsKtSh_image.png?AWSAccessKeyId=AKIAYQNQCIXNIQWBC56C&Expires=1697908267&Signature=GArTub3XqKz4nuLAxZmejlgOqug%3D"}

Ao clicar no botão um novo modal se abrirá com as seguintes características:&#x20;

![](https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/hwCtW_Uo_X_arEs4-m7_X_image.png)

Onde será possível definir:&#x20;

- Tipo do Evento&#x20;
- Transformação
- Função&#x20;
- Grupo&#x20;
- Métrica
- Descrição

### Exemplo de alerta

Na imagem abaixo é possível checar a criação de uma alerta preenchendo os dados necessários:

![](https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/2ATHrvv5wWZJckx2R2Khg_image.png)

## Regras para Triggers

Na criação de alertas, é possível definir múltiplas condições e prioridades para diferentes pontos de métricas:&#x20;

Contemplando thresholds definidos manualmente dentro de uma janela de tempo e thresholds automáticos que podem ser definidos dentro de uma janela temporal, permitindo assim que o AIOPS se adapte ao comportamento das métricas com base na auto detecção de anomalias, todas as configurações podem ser ajustadas a qualquer tempo de maneira manual.&#x20;

## Filtros

Também é possível definir filtros para limitar as métricas que se deseja checar, como no exemplo abaixo onde o alerta que está sendo criado é relacionado ao uptime de um serviço, onde queremos limitar ao serviço relacionado ao ibm db2:&#x20;

![](https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/1_P-MWx0GAXDfSITbQLDV_image.png "Filtro para os processos com nome db2fmcd e db2sysc")

## Escopo

O escopo define o grupo de items que serão monitorados para as métricas selecionadas, podendo optar por hosts específicos, serviços de TI ou anotações e tags:

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/MdfJS2LPBc4nu91s-L2KR_xeao1juemkwfvkmtpais-image.png)


[title] Alarmes
[path] AIOps/

Os alarmes são registros onde o AIOPS verifica ocorrências de eventos que ocorrem em uma determinada situação definida por configurações feitas pelo usuário.

Com esses registros é possível verificar a ocorrência de eventos criados a partir dessas configurações personalizadas.

[title] Ativando o LDAP / AD
[path] AIOps/Integrações/Criando uma integração/

A fim de integrar a autenticação LDAP / AD ao AIOPS, deve-se preencher corretamente o formulário da integração.&#x20;

# Preenchimento do formulário

Abaixo está um exemplo de como o formulário deve ser preenchido. Os valores deverão ser configurados de forma que atenda ao seu ambiente.

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/D-DxLyG87hlVrKVx6qqFI_image.png)

## Campos do formulário

| Atributo                | Valor                                                  |
| ----------------------- | ------------------------------------------------------ |
| Host                    | Hostname ou IP para conexão.                           |
| 389                     | Porta que roda o LDAP/AD.                              |
| Base DN                 | DN Base onde os usuários serão buscados.               |
| Atributo de pesquisa    | Atributo contendo o identificador único do usuário.    |
| Bind DN                 | DN de um usuário administrador para autenticação.      |
| Senha para bind         | Senha do usuário administrador para autenticação       |
| Mapa de atributos       | Atributos utilizados para criação do usuário no AIOPS. |
| Usuário LDAP para Auth. | Usuário administrador para autenticação.               |

### Mapa de atributos

O campo deve ser preenchido no formato chave\:valor separados por vírgulas, como no exemplo a seguir:

:::CodeblockTabs
Exemplo

```none
first_name:givenName,last_name:sn,email:mail
```
:::

- As chaves são os atributos utilizados para a identificação do usuário no AIOPS.&#x20;

| Chave       | Descrição                 |
| ----------- | ------------------------- |
| first\_name | Primeiro nome do usuário. |
| last\_name  | Sobrenome do usuário.     |
| email       | Endereço de email.        |

- O valor é o respectivo atributo localizado no **LDAP/AP**.&#x20;

| Valor        | Descrição                          |
| ------------ | ---------------------------------- |
| givenName    | Contém o primeiro nome do usuário. |
| sn / surname | Contém o sobrenome do usuário.     |
| mail         | Endereço de email.                 |


[title] Distribuição
[path] AIOps/Inventário/

O gerenciamento eficiente de ativos de TI é um desafio constante para as organizações. Com o crescente número de dispositivos e sistemas em uso, os administradores de sistema precisam de ferramentas que os ajudem a rastrear e gerenciar ativos de hardware e software em toda a organização. O Xventory é uma ferramenta de gerenciamento de ativos de TI que permite que os administradores de sistema gerenciem e rastreiem ativos de hardware e software em uma organização de maneira eficiente e escalável.

Uma das funcionalidades essenciais do Xventory é a capacidade de distribuir software em dispositivos gerenciados em diversos sistemas operacionais, incluindo Linux, Windows e macOS. Isso é especialmente útil, pois muitas organizações utilizam uma mistura de sistemas operacionais em sua infraestrutura de TI.

### Distribuição de software no Xventory:

O Xventory oferece uma variedade de recursos para ajudar às organizações a gerenciar a distribuição de software em dispositivos gerenciados e a verificar a compatibilidade do software com outros aplicativos no dispositivo. Com o uso de rótulos personalizados para dispositivos e aplicativos, é possível gerenciar e rastrear a implantação de software em dispositivos gerenciados, tornando mais fácil implantar software em dispositivos específicos ou em grupos de dispositivos com base em critérios como sistema operacional ou configuração do dispositivo.

Além disso, o Xventory fornece relatórios detalhados sobre a implantação de software em dispositivos gerenciados, permitindo que os administradores de sistema monitorem a implantação de software e verifiquem se o software foi implantado com sucesso em todos os dispositivos gerenciados. Com esses recursos, o Xventory é capaz de distribuir software no parque computacional do cliente de maneira eficiente e escalável, garantindo a segurança e o bom funcionamento dos sistemas em toda a organização.

A implantação de software em dispositivos gerenciados é um processo complexo que requer cuidado e atenção aos detalhes. Ao implantar software, é importante levar em consideração a compatibilidade do software com outros aplicativos no dispositivo, bem como com o sistema operacional de destino. O Xventory ajuda os administradores de sistema a gerenciar esse processo de maneira eficiente e escalável, garantindo que o software seja implantado com sucesso em todos os dispositivos gerenciados.

### Recursos do Xventory para gerenciar a distribuição de software em dispositivos gerenciados:

Com o Xventory, os administradores de sistema podem criar grupos de teste para verificar a compatibilidade do software com os sistemas operacionais de destino e com outros aplicativos no dispositivo antes de implantar o software em um grande número de dispositivos gerenciados. Além disso, os rótulos personalizados ajudam os administradores de sistema a gerenciar a implantação de software em dispositivos específicos ou em grupos de dispositivos com base em critérios específicos.

[title] Observação de redes
[path] AIOps/Integrações/

Para ampliar a observação de redes e networking, nós utilizamos integrações com ferramentas de mercado reforçando, dentre elas temos:&#x20;

- Elastiflow
- ELK
- Paessler PRTG
- Paessler PRTG&#x20;
- ManageEngine NetFlow Analyzer&#x20;
- Plixer Scrutinizer&#x20;
- Wireshark
- nProbe


[title] Análise Automatizada de Eventos com IA
[path] AIOps/

A ferramenta é capaz de realizar, em tempo real, a análise inteligente de grandes volumes de eventos provenientes da infraestrutura de TI através dos seguintes recursos:
Identificação de anomalias: Detecta automaticamente padrões incomuns e eventos indesejados no ambiente monitorado, com geração imediata de alertas com base em Picos e Quedas.

- **Diagnóstico da causa raiz:** Aplica algoritmos de correlação e inferência para determinar a origem dos problemas, mesmo em ambientes altamente dinâmicos. Dados topológicos (coletados na descoberta) permitem maior inferência e precisão na relação causal.
- **Integração com Base de Conhecimento (KB)**: Verifica se a causa raiz corresponde a um erro já registrado na base de conhecimento da organização.

Através de políticas de automação e/ou escala de eventos, a solução documentada pode ser executada automaticamente, quando aplicável.

Caso necessário, realizar ações corretivas no ambiente, de forma autônoma ou mediante aprovação.

Esse processo visa reduzir o tempo médio de detecção (MTTD) e de resolução (MTTR), aumentando a resiliência operacional e a eficiência das equipes de operação.

[title] Integrações
[path] AIOps/

AIOPS possui quatro tipos de integração:

- Monitoramento
- Notificações
- ITSM/SDM
- Autenticação

As integrações do tipo monitoramento permite que os alertas e métricas dos servidores sejam coletadas dos sistemas de monitoramento como Zabbix, Nagios, CloudWatch, Datadog, Dynatrace, Solarwinds dentre outros. Estes alertas coletado são insumos para a criação de incidentes.

## Monitoramento

As integrações do tipo **monitoramento** permite que os alertas e métricas dos servidores sejam coletadas dos sistemas de monitoramento como Zabbix, Nagios, CloudWatch, Datadog, Dynatrace, Solarwinds dentre outros. Estes alertas coletado são insumos para a criação de incidentes.

## Notificação&#x20;

Já as de **notificação** permite compartilhar as informações de incidentes gerados, em diferentes canais de comunicação, como twillio, sms e e-mail, ampliando o leque de capacidade comunicativa das equipes, permitindo acionamento rápido e eficaz.

## ITSM/SDM

Esse tipo de integração permite compartilhar as informações de incidentes gerados, possibilitando a rastreabilidade e acompanhamento de incidentes via ITSM/SDM, podendo assim criar novos chamados e atribuí-los a um problema específico.

## Autenticação&#x20;

As integrações do tipo autenticação permitem que o AIOPS possa utilizar usuários e autenticações oriundas de outras fontes como por exemplo AD/LDAP, permitindo uma implatação mais ágil e inserção do time na ferramenta em pouquíssimo tempo.

## Pipes

O AIOPS possui a capacidade de criação de fluxos para automações simples e complexas, seja para autorecuperação, execuções rotineiras ou orquestrações, podendo se comunicar de diversas formas com diversas tecnologias distindas utilizando diferentes protocolos sendo, UDDI, SSH, SMTP, POP, REST, TELNET, SOAP, WSDL além de poder trabalhar com diversos formatos com YAML, JSON, XML, e HTML.

[title] Hyper-V
[path] Infraestrutura/Provedor de Recursos/

Esta configuração permite a coleta de dados do Hyper-V a partir do **sphere-agent** com a utilização de um script PowerShell específico.

1. Acesso ao servidor Hyper-V onde o **sphere-agent** está instalado.
2. Permissão para adicionar scripts ao diretório do **sphere-agent**.
3. Faça o download do script PowerShell que será usado para a coleta de dados:
   - [Export-HyperVToTelegraf.ps1](https://repo.simonops.com/repo/scripts/Export-HyperVToTelegraf.ps1)
   - O arquivo deve ser colocado na pasta do sphere-agent:
     - C:/ProgramData/65A/sphere-agent
4. Acesse a interface de gerenciamento do **sphere-agent** através do console **Atmos** -> **Infraestrutura&#x20;**->**&#x20;Detalhamento do IC&#x20;**->**&#x20;Configuração do agent&#x20;**&#x65; adicione a seguinte configuração para habilitar a coleta do script PowerShell no Telegraf:

:::BlockQuote
\[\[inputs.exec]]
&#x20; commands = \["powershell -File C:/ProgramData/65A/sphere-agent/Export-HyperVToTelegraf.ps1"]
&#x20; interval = "15m"
&#x20; timeout = "120s"
&#x20; data\_format = "influx"
:::

- **\[\[inputs.exec]]**: Este é o plugin do Telegraf que executa comandos ou scripts externos.
- **commands**: O comando que será executado pelo Telegraf. Neste caso, estamos chamando o PowerShell para executar o script **Export-HyperVToTelegraf.ps1**.
- **interval**: Define o intervalo de tempo entre as execuções do script. No exemplo, o script será executado a cada 15 minutos (15m).
- **timeout**: Tempo máximo de execução permitido para o script. Caso o script demore mais de 120 segundos (120s), a execução será encerrada.
- **data\_format**: Define o formato dos dados de saída que o Telegraf espera. Neste caso, o formato utilizado será **InfluxDB** (influx), o que permite que as métricas sejam enviadas diretamente para uma base de dados InfluxDB.

Após realizar os procedimentos, preencha os **Detalhes da Descoberta** selecionando como **Host de Origem&#x20;**&#x6F; IC utilizado na configuração.

[title] Métrica
[path] /


[title] Tempo de serviço
[path] Infraestrutura/

A solução oferta um modelo de Saas em regime 24X7.&#x20;

![](https://archbee-image-uploads.s3.amazonaws.com/qpr-FybYVVmqbebYaBDz_/WGOhnAA48cw5gVzLHnT14_image.png)


[title] Visão Geral da Descoberta e Relacionamento
[path] Infraestrutura/

# One Sphere Agent

O agente unificado é um agente extremamente leve e rápido, sem impacto na performance do sistema, sendo altamente recomendado para maior enriquecimento de dados. O agente possui política personalizável, permitindo uso misto, configurando-o para coleta de dados e observabilidade e/ou apenas inventário.

## Sondas de Descoberta

Para descoberta sem o uso de agente, o AIOPS Discovery possui sondas de descoberta que podem ser configuradas permitindo uma grande quantidade de credenciais e configurações, como:

- Credenciais para descoberta em nuvem (AWS, Azure, GCP, etc)
- Credenciais para descoberta em banco de dados (MySQL, PostgreSQL, MongoDB, etc)
- Credenciais para descoberta em rede (ICMP, IPMI, SNMP, SSH, WMI, Telnet, etc)
- Credenciais para descoberta em sistemas operacionais (Linux, Windows, etc)
- Credenciais para descoberta em armazenamento (NAS, SAN, etc)
- Credenciais para descoberta em segurança (Firewall, IDS, etc)
- Credenciais para descoberta em aplicativos (API REST, SOAP, etc)
- Credenciais para descoberta em contêineres (Docker, Kubernetes, etc)
- Dentre outros.

:::hint{type="info"}
**OBS**: Todas as credenciais são armazenadas em cofre (vault), garantindo a segurança e privacidade das informações.
:::

## **Gerenciamento de Ativos**

As regras de descoberta permitem criar os ativos de acordo com as definições do usuário, definindo entre criação automática e manual dos itens descobertos. Mesmo que o processo de criação seja definido como manual, o AIOPS irá enriquecer com dados adicionais automaticamente, por exemplo:

### Rótulos dinâmicos:

Cloud Region: para cada região geográfica de cada provedor de nuvem (AWS, Azure, Google Cloud, Oracle, etc.), segregando as informações por conta, assinatura ou projeto, etc.

Location: para identificar e mapear os ativos descobertos na infraestrutura local, como data centers, data-centers, etc.

### Relacionamento entre ativos:

Os relacionamentos entre ativos são criados automaticamente com base nas regras de descoberta, permitindo a visualização de como os ativos estão relacionados entre si. Podem ser definidos na camada física ou lógica, exemplos:

Um switch conectado a um servidor, permitindo a visualização de como os ativos estão conectados entre si.

- Um servidor conectado a um banco de dados.
- Uma máquina virtual hospedada em um host de virtualização.
- Containers em um cluster de contêineres.
- Membros de um grupo de balanceamento de carga.

A sincronização do CMDB é realizada de forma automática durante a descoberta, mas objetos efêmeros como pods, containers, etc. possuem um ciclo de vida curto, tornando-se opcional a sincronização desses objetos com o CMDB. Contudo seus relacionamentos são preservados durante seu ciclo de vida.

[title] LGPD
[path] Visão Geral do Sistema/

A solução adere à LGPD no que tange a transparência, segurança jurídica, anonimização de dados, com todo cuidado com a coleta de informações e coleta de dados, levando sempre em consideração o fator de consentimento com informação prévia ao cidadão. Abrangência territorial, com fiscal centralizado a cargo da Autoridade Nacional de Proteção de Dados Pessoais (ANPD), assim como a responsabilidade sobre os tratamentos de dados e suas funções. Também é feita a gestão de riscos e falhas, cientes das penalidades e todos os direitos e deveres da CONTRATADA, perante a Lei Geral de Proteção de Dados Pessoais, Lei nº 13.709/2018.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/FR75n4ahAPiInjjj1_tuf_lgpdpages-to-0001.jpg" size="76" width="10280" height="10278" caption position="center" signedSrc="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/FR75n4ahAPiInjjj1_tuf_lgpdpages-to-0001.jpg"}

A Lei Geral de Proteção de Dados Pessoais (LGPD ou LGPDP), Lei nº 13.709/2018, é a legislação brasileira que regula as atividades de tratamento de dados pessoais e que também altera os artigos 7º e 16 do Marco Civil da Internet.




[title] Validando coletas customizadas
[path] Métrica/Coletas customizadas/

A fim de validar as coletas customizadas, utilize o acesso ao seu painel AIOPS/Grafana (Exemplo: https\://seu\_dominio\_aiops/grafana).

1. Depois de acessar seu painel AIOPS/Grafana, clique na guia Explore no navegador à esquerda.

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/OJJUvuzLwvyakolEgKH1A_captura-de-tela-2024-03-19-as-40237-pm.png)

2\. Selecione o Source de métricas "Prometheus", logo depois, clique na seta suspensa do navegador de métricas e insira o nome da métrica coletada na coluna "Selecione uma Métrica".

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/9J8DrR00z63_NZCea4Zg4_captura-de-tela-2024-03-19-as-40648-pm.png)


[title] Integrações com Webhook
[path] AIOps/Integrações/


[title] Criando uma integração
[path] AIOps/Integrações/

## Acesso

Para a criação de uma nova integração é necessário acessar o AIOPS, e no menu principal (canto esquerdo) selecionar a seguinte opção:

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/JmgTScXmhFT28N7mPP6CD_botaomenuintegracoes.png" size="42" caption position="center" signedSrc="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/JmgTScXmhFT28N7mPP6CD_botaomenuintegracoes.png?AWSAccessKeyId=AKIAYQNQCIXNIQWBC56C&Expires=1697895813&Signature=fnaJmACjrfd%2FXt8QLNxdrGYlvIg%3D" width="140" height="37" darkWidth="140" darkHeight="37"}

## Cadastro

Após acessar a tela de integrações, será necessário cadastrar uma nova integração:&#x20;

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/TmezBWeJBgkhvKTk4XbB5_novaintegracaobutton.png" size="42" caption position="center" signedSrc="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/TmezBWeJBgkhvKTk4XbB5_novaintegracaobutton.png?AWSAccessKeyId=AKIAYQNQCIXNIQWBC56C&Expires=1697895813&Signature=mw3mnUy28Bq7WO0me77JgJqojlU%3D" width="174" height="38" darkWidth="174" darkHeight="38"}

Após clicar o botão acima teremos uma nova janela na aba "Geral", onde será necessário a definição de um nome para a integração que está sendo criada, e deverá ser selecionada opção com o tipo específico da integração desejada.

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/NFURgQgSDq8Qfgn4uXnTd_IntegracaoEmail.png" size="80" signedSrc="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/NFURgQgSDq8Qfgn4uXnTd_IntegracaoEmail.png?AWSAccessKeyId=AKIAYQNQCIXNIQWBC56C&Expires=1697895813&Signature=ddYfhurxORzTKW5mOpS2iFHXyIo%3D"}

## Opções

As abas do popup que apareceu se adaptarão conforme integração selecionada, permitindo assim a inserção de parametros que possibilitarão a comunicação entre o AIOPS e a ferramenta desejada para que a integração possa ser adicionada com sucesso.

## Autenticação

Na aba de autenticação é possível cadastrar os dados de usuários para que o AIOPS possa se comunicar com a ferramenta desejada.

Para todas as integrações existentes no AIOPS, é possível realizar o teste de comunicação após o preenchimento dos dados necessários através do botão.


[title] Integração com o Zabbix via API
[path] AIOps/Integrações/Criando uma integração/

:::hint{type="info"}
O AIOPS importa alertas e hosts do Zabbix utilizando da conexão com a API nativa do Zabbix ([https://www.zabbix.com/documentation/current/en/manual/api](https://www.zabbix.com/documentation/current/en/manual/api)), que utiliza de um API Token para realizar a autenticação.

A integração usa a API de alertas do Zabbix para importar os alertas ocorridos:
[[https://www.zabbix.com/documentation/current/en/manual/api/reference/alert/get](https://www.zabbix.com/documentation/current/en/manual/api/reference/alert/get)](https://www.zabbix.com/documentation/current/en/manual/api/reference/event/get)

Cada incidente criado no AIOPS importado dos alertas do Zabbix faz a correlação e cria um ticket.
:::



1 - Para integrar o Zabbix ao AIOPS, acesse a página do Atmos e clique no quinto item da coluna da esquerda (Pipes):

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/T2KqykS-OKEP_E4-9vJ2h_image.png" signedSrc="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/T2KqykS-OKEP_E4-9vJ2h_image.png" size="10" width="160" height="678" position="center" caption}

2 - No canto direito superior clique em "Novo Pipe"

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/qlbA3XLpvt0LEJFv0SNrX_image.png" signedSrc="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/qlbA3XLpvt0LEJFv0SNrX_image.png" size="40" width="264" height="92" position="center" caption}

3 - Arraste o bloco Zabbix para a area de edição de PIpes e selecione o script **Listar Alertas**.

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/2TUKW1xfNA6tCJotH-8Ay_image.png)

4 - Arraste o bloco AIOPS para a area de Low Code e selecione o script **Criar novo evento**.

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/DJR-4YPE2ux2Cc13hvEjt_image.png)

5 - Conecte os blocos e preencha as variáveis necessárias&#x20;

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/b5wq7d__HyH-Uh0_NCb0M_image.png" signedSrc="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/b5wq7d__HyH-Uh0_NCb0M_image.png" size="76" width="1368" height="874" position="center" caption}

6 - Dê o nome para essa integração

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/_LNX0K67KDwjBF5sriKyI_image.png)

7 - Salve a integração.

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/fo2rx_Ix8Uqo7wRyUYc9K_captura-de-tela-2024-01-22-as-210355.png)

8 - Crie um agendamento de execução, seguindo o passo a passo da [Agendamentos](docId\:roagKZEPVgvY-nneWWDxb) para que a integração rode periodicamente.

[title] Host
[path] Infraestrutura/

Visualize as métricas relacionadas à um IC, coletadas em um determinado intervalo de tempo, defina templates de métricas, acompanhe a real situação e organize seus nós através das funcionalidades existentes para cada nós de sua infraestrutura.

## Acesso&#x20;

Para acessar a tela de detalhamento de host, é necessário seguir o procedimento para acesso a tela de  [Infraestrutura](docId:7JrfLeZeAzgq5M6pWp4KW) e clicar em um item existente na listagem.

![](https://archbee-image-uploads.s3.amazonaws.com/qpr-FybYVVmqbebYaBDz_/oCZakhZ-7RVXJaKhhtKdo_image.png)

## Informações&#x20;

Na tela é possível obter informações rápidas sobre o host selecionado, como **métricas**, **informações de sistema**, **processos**, **serviços de negócios dependentes deste item** e **dependências lógicas&#x20;**&#x70;ara outros itens de sua infraestrutura.

### Informações gerais&#x20;

A seção de **Informações Gerais&#x20;**&#x20;apresenta dados fundamentais sobre o servidor, incluindo sua identificação, recursos e status de comunicação com o Agent.&#x20;

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/qpr-FybYVVmqbebYaBDz_/efKEWbZhC0ZHx8e4Hac0c_image.png" signedSrc size="36" width="288" height="504" position="center" caption}

1. **Serviço Operacional do Servidor:** Indica o Sistema operacional do servidor
2. **Quantidade de CPU:** Exibe o número de unidades de processamento central (CPUs) disponíveis no servidor. Este dado é fundamental para avaliar a capacidade de processamento do hardware.
3. **Quantidade de Memória:** Mostra a quantidade total de memória RAM (em GB) instalada no servidor. É um indicador importante para a performance e capacidade de execução de aplicações.
4. **Hostname do Servidor:** Apresenta o nome de rede exclusivo atribuído ao servidor. O hostname é utilizado para identificar o servidor na rede.
5. **Endereço de IP do Servidor:** Informa o endereço IP principal do servidor, utilizado para sua comunicação na rede.
6. **MAC Address:** Exibe o Media Access Control Address, um identificador físico único para cada interface de rede do servidor.
7. **Versão Vigente do Agent:** Indica a versão atual do **Sphere-Agent** instalada no servidor. Manter o Agent atualizado garante a coleta correta de dados e acesso a novos recursos.
8. **ID da Máquina:** Um identificador único atribuído à máquina pelo sistema.
9. **Data em que o Agent Realizou a Primeira Comunicação:** Registra a data e hora em que o Sphere-Agent no servidor estabeleceu sua primeira conexão bem-sucedida com a ferramenta.
10. **Última Data de Coleta:** Apresenta a data e hora da última vez que o Sphere-Agent enviou dados de monitoramento para a ferramenta, indicando a atualidade das informações exibidas.
11. **Data em que o IC foi Inserido na Ferramenta:** Mostra a data em que o item de configuração (servidor) foi adicionado ao sistema de monitoramento.

### Interface de Rede

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/qpr-FybYVVmqbebYaBDz_/VAVk0MIsVL3N8xyaiUAPa_image.png" signedSrc size="38" width="283" height="98" position="center" caption}

Esta seção detalha as **interfaces de rede&#x20;**&#x20;configuradas no servidor. Para cada interface, são exibidas informações como o endereço IP, máscara de sub-rede, gateway e status da conexão. Essa visualização é vital para diagnosticar problemas de conectividade e configurar corretamente a rede do servidor.&#x20;

### Processos em Execução&#x20;

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/qpr-FybYVVmqbebYaBDz_/b2JTU5e8eQkhJBNxBJWIm_image.png" signedSrc size="40" width="292" height="221" position="center" caption}

A funcionalidade **Processos em Execução no Servidor** lista todos os processos que estão atualmente ativos na máquina. Esta informação é **coletada dinamicamente pelo Sphere-Agent**, proporcionando uma visão em tempo real das aplicações e serviços em execução, bem como seu consumo de recursos (CPU e memória). É uma ferramenta poderosa para identificar gargalos de desempenho e processos não autorizados.&#x20;

### Métricas

Observando o centro da tela é possível de forma rápida e eficiente obter dados sobre métricas importantes para esse determinado nó.

![](https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/5sqjVKjoK79mZvfnRCS_s_image.png)

### Predição

A funcionalidade de predição oferece uma capacidade essencial para o planejamento proativo e a otimização de recursos. Ao analisar o comportamento passado de aplicativos e serviços, podemos prever demandas futuras, evitando gargalos, otimizando custos e garantindo a disponibilidade. Isso se traduz em maior eficiência operacional e melhor qualidade do serviço para o cliente.

Essa predição é construída sobre a análise de métricas coletadas em tempo real. O diferencial é a aplicação de uma análise sazonal, que permite ao algoritmo compreender e incorporar ciclos de comportamento (e.g., picos diários de uso, variações semanais de tráfego). Para cada Item de Configuração (IC) monitorado, a ferramenta constrói um modelo preditivo individual. O usuário tem controle sobre a janela temporal dessa análise, podendo configurá-la de um mínimo de 24 horas a um máximo de 7 dias, o que proporciona flexibilidade para focar em tendências de curto prazo ou em padrões mais amplos da semana.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/JNyyMk7cY6iRcYgiAvpWY_imagem.png)

### Dependências

Na área inferior da tela é possível observar o box de dependency overview, onde se pode observar quais as dependências lógicas ativas para esse nó de infraestrutura.

![](https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/uoyhwILaEgx0mZoTDMKYG_image.png)

### Insights e alertas

O Atmos atua de forma automática, auxiliando na gestão de recursos e propiciando uma visão rápida de possíveis problemas no host escolhido através dos botões abaixo (canto superior direito):

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/BcgqKz7B9oRpiuJiWaUsw_image.png" size="50" caption position="center" signedSrc="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/BcgqKz7B9oRpiuJiWaUsw_image.png?AWSAccessKeyId=AKIAYQNQCIXNIQWBC56C&Expires=1697908384&Signature=meVIJ5ublDFXHGrSUyFL1Tlx7yo%3D"}

## Ações

Para o host escolhido é possível desempenhar ações com o objetivo de organizar e filtrar (tags e annotations) e ações com o objetivo de gerir os items de configuração.

### Criação e gestão de tags e anotações:

No canto superior direito é possível encontrar a opção de adicionar tags e anotações para facilitar a organização:

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/_rfDdrH8WjZ8AHQIJ7IK__image.png" size="52" caption position="center" signedSrc="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/_rfDdrH8WjZ8AHQIJ7IK__image.png?AWSAccessKeyId=AKIAYQNQCIXNIQWBC56C&Expires=1697908384&Signature=S37ofYitbGxAxfwu2dQSvRX32rk%3D"}

Ao clicar no ícone de etiqueta, um modal será carregado com as opções de tags e anotações do host escolhido.

### Atuando com hosts:

No canto superior direito possível selecionar a opção de três pontos:&#x20;

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/wzOvlcZe1apRtTc2gsfmU_image.png" size="46" caption position="center" signedSrc="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/wzOvlcZe1apRtTc2gsfmU_image.png?AWSAccessKeyId=AKIAYQNQCIXNIQWBC56C&Expires=1697908384&Signature=XfkVFU32Bryw0J0d%2B0LZUjOsuok%3D"}

Essa opção abrirá um dropdown com as seguintes opções:

- Alterar nome
- Configuração de Métrica
- Arquivar
- Combinar hosts
- Configurar painéis

### Alteração de nome&#x20;

Permite de forma rápida, padronizar e renomear hosts para um melhor acompanhamento.

### Configuração de métrica

Permite consultar e acessar as configurações de métricas ativas para esse item de configuração.

### Arquivar

Permite remover (arquivar) um host de forma lógica, evitando assim perda de dados e permitindo uma recuperação posterior.

### Combinar host

Como o AIOPS/Atmos atua de maneira a propiciar uma centralização de diferentes ferramentas é possível selecionar dois hosts oriundos de diferentes fontes mas que representam o mesmo item e realizar uma fusão das informações de duas diferentes fontes, escolhendo qual seria a princiapal e evitando dados inutilizados na tela de infraestrutura.

### Configurar painéis

É a opção onde se pode configurar as métricas a serem exibidas nesse host:

![](https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/CqTN8Ot762GWrCWszEK9I_image.png)

### Coleta por SNMP v1/v2/v3

Colete eventos de diversos dispositivos e sistemas através  do protocolo SNMP - Simple Network Management Protocol.

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/2W8cFLJPtBvnetZcAickF_coleta-snmp.PNG)


[title] Integração com o Zabbix (Legado)
[path] AIOps/Integrações/Criando uma integração/

:::hint{type="info"}
Cada incidente criado no AIOPS importado dos alertas do Zabbix faz a correlação e cria um ticket.
:::



1 - Para integrar o Zabbix ao AIOPS, acesse a página do AIOPS e clique no terceiro item da coluna da esquerda (Integrações):

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/vDDWaaI2SAKBIsVhJcHbU_captura-de-tela-2023-10-05-as-55700-pm.png "Integração")

2 - No canto direito superior clique em "+ Nova integração"

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/Q_iHXvvJU9kqv_3WpDG1A_captura-de-tela-2023-10-05-as-55803-pm.png "Nova Integração")

3 - Dê o nome para essa integração e coloque Monitoramento no campo "Tipo"&#x20;

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/dZ59arGgwLpayF5tQOqym_captura-de-tela-2023-10-05-as-55852-pm.png "Tipo do módulo")

4 - No campo Módulo escolha Zabbix.

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/Jjhb-ooDtsqsIBxy4xk3e_captura-de-tela-2023-10-05-as-55920-pm.png "Módulo")

5 - Na aba "Autenticação", coloque a URL do host onde o Zabbix está hospedado. Preencha com o Usuário e com a senha do Zabbix. &#x20;

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/skNtJiAN9V1RsVy4P2I-E_captura-de-tela-2023-10-06-as-92038-am.png "Detalhes")



6 - Execute o teste de conexão a fim de validar a integração.

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/ShKIlA1mEKwzPx96qjUHH_captura-de-tela-2023-10-06-as-90318-am.png "Teste de conexão")

7 - Salve a integração.

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/eBCpU2iIV0KNIeH0U1z-f_captura-de-tela-2023-10-06-as-92550-am.png "Salvar")


[title] VMware Aria Operations
[path] AIOps/Integrações/Integrações com Webhook/



## Versões Suportadas

| Versões suportadas | Tipo    | Tipo de Autenticação                              |
| ------------------ | ------- | ------------------------------------------------- |
| \<= 8.10           | Webhook | Token de Acesso da Organização (Org Bearer Token) |

***

## Visão Geral

O **VMware Aria Operations** (anteriormente VMware vRealize Operations, ou vROps) automatiza e simplifica a gestão de TI, oferecendo visibilidade completa desde a infraestrutura física, virtual e em nuvem até os aplicativos.

Esta integração usa um **Outbound Instance** configurado com um **template de payload** e um **webhook de notificação**. Quando um evento é disparado, um payload JSON é enviado ao AIOPS, que processa e correlaciona os dados, mantendo os incidentes atualizados na plataforma.

***

## Etapas para Instalação

### 1. Confirmar acesso

- Certifique-se de ter permissões de **administrador** no servidor **VMware Aria Operations** para configurar alertas e gerenciar configurações de **notificação de saída**.
- Confirme se o servidor VMware Aria Operations tem acesso de saída à porta **443&#x20;**&#x6F;u **80** do nó **Master** do AIOPS.

### 2. Configure um Outbound Instance para enviar alertas ao AIOPS

1. Na barra de navegação lateral, navegue até **Operations > Configuration&#x20;**&#x65; selecion&#x65;**&#x20;Outbound Settings**.
2. Clique em **Add** para abrir a página de configuração de **Outbound Instance**.
3. Crie um **Outbound Instance** com as seguintes definições:
   - **Tipo do plugin:** Webhook Notification Plugin
   - **Nome da instância:** AIOPSWebhook
   - **URL:**
     ```text
     https://<dominio-do-AIOPS>/services/collector/event
     ```
4. Clique no botão **TESTAR** para verificar se a integração se conecta ao AIOPS com sucesso.
5. Quando o teste for bem sucedido, clique em **SALVAR&#x20;**&#x70;ara salvar a configuração.

***

### 3. Configurar um modelo de payload para usar com a notificação de saída personalizada

1. Na barra de navegação lateral, navegue até:
   `Operations > Configuration` e selecione `Payload Templates`
2. Clique em **Add** para abrir o editor `Create Payload Template`.
3. Configure as seções do modelo de payload da seguinte forma:
   1. Detalhes:
      1. **Nome:&#x20;**&#x41;IOPS Template
      2. **Descrição:&#x20;**&#x41;IOPS Alerts Payload
      3. **Outbound Method**: Webhook Notification Plugin
   2. Detalhes do payload:
      1. **Você deseja adicionar propriedades de entrada de modelo:** Não
      2. **Content-Type**: application/json
      3. **HTTP Method**: POST
      4. **Authorization:** AriaOps `<integration-app-key>`
   3. Payload da requisição:

:::CodeblockTabs
Json

```javascript
{
   "start_date": "${CREATE_TIME}",
   "update_date": "${UPDATE_TIME}",
   "cancel_date": "${CANCEL_TIME}",
   "device_id": "${RESOURCE_ID}",
   "adapter_type": "${ADAPTER_KIND}",
   "device_type": "${RESOURCE_KIND}",
   "device_name": "${RESOURCE_NAME}",
   "health": "${OBJECT_HEALTH_STATE}",
   "risk": "${OBJECT_RISK_STATE}",
   "efficiency": "${OBJECT_EFFICIENCY_STATE}",
   "impact": "${ALERT_IMPACT}",
   "criticality": "${ALERT_CRITICALITY}",
   "check": "${ALERT_DEFINITION}",
   "type": "${ALERT_TYPE}",
   "sub_type": "${ALERT_SUBTYPE}",
   "alert_id": "${ALERT_ID}",
   "status": "${ALERT_STATUS}",
   "recommendations": "${ALERT_RECOMMENDATIONS}",
   "alert_url": "${LINK_TO_ALERT}"
 }
```
:::

Selecione **Criar** para guardar o modelo de carga útil.

***

### 4. Criar uma Notificação de Alerta

1. Na barra de navegação lateral, navegue até:
   `Operations > Configuration` e selecione `Notifications`
2. Clique em **Adicionar** para abrir o editor de configuração de **Notificações**
3. Configure as seções **Notificação** da seguinte forma:
   1. Notificações
      1. **Nome:** AIOPS Notification
      2. **Descrição:** Send Notifications to AIOPS
      3. **Status:** Ativado (toggle on)
   2. Critérios
      1. **Criteria:** All Objects (Todos os objetos)
      2. **Category:** All Alerts (Todos os alertas)
      3. **Criticality:** All Criticality (Todas as criticidades)
      4. **Control State:** All States (Todos os estados)
      5. **Status:** All Statuses (Todos os status)
   3. Set Outbound Method:
      1. **Outbound method:** Webhook Notification Plugin / AIOPS Webhook
   4. Select Payload Template:
      1. **Payload Template:** AIOPS Template
4. Selecione **Criar** para salvar e fechar o editor de notas.


[space] AIOPS Documentação Técnica (/aiops-documentacao-tecnica)

[title] OpenSSL CSR
[path] Documentação Técnica/Automações/Criptomoeda/

## Resumo

- Gerar solicitação de assinatura de certificado OpenSSL (CSR).

## Parâmetros

| **Parâmetro**                                                                                                     | **Tipo**               | **Escolhas \| Valor Padrão**                                              | **Comentários**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| ----------------------------------------------------------------------------------------------------------------- | ---------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| authority\_cert\_issuer                                                                                           | list / elements=string |                                                                           | Nomes que estarão presentes no campo emissor do certificado de autoridade da solicitação de assinatura de certificado. <br /><br />Os valores devem ser prefixados por suas opções (ou seja, email, URI, DNS, RID, IP, dirName, otherName e os específicos para sua CA). <br /><br />Exemplo: DNS: ca.example.org. Se especificado, a *authority\_key\_identifier* também deve ser especificada. <br /><br />Observe que as CA's comerciais ignoram esse valor, respectivamente, use um valor de sua própria escolha.                                                                                        |
| authority\_cert\_serial\_number                                                                                   | integer                |                                                                           | O número de série do certificado de autoridade. Observe que isso só é compatível se o back-end de criptografia for usado! <br /><br />Observe que as CA's comerciais ignoram esse valor, respectivamente, usam um valor de sua própria escolha. <br /><br />O AuthorityKeyIdentifier só será adicionado se pelo menos um dos parâmetros authority\_key\_identifier, authority\_cert\_issuer e authority\_cert\_serial\_number for especificado.                                                                                                                                                              |
| authority\_key\_identifier                                                                                        | string                 |                                                                           | O identificador de chave de autoridade como uma string hexadecimal, em que dois bytes são separados por dois pontos. <br /><br />Exemplo: 00: 11: 22: 33: 44: 55: 66: 77: 88: 99: aa: bb: cc: dd: ee: ff: 00: 11: 22: 33. Se especificado, Authority\_cert\_issuer também deve ser especificado. <br /><br />Observe que as CA's comerciais ignoram esse valor e usam um valor de sua própria escolha, respectivamente. <br /><br />O AuthorityKeyIdentifier só será adicionado se pelo menos um dos authority\_key\_identifier, authority\_cert\_issuer e authority\_cert\_serial\_number for especificado. |
| backup                                                                                                            | boolean                | Escolhas:<br />- false<br />(default)<br />- true                         | Crie um arquivo de backup incluindo data / hora para que você possa obter o CSR original de volta se você o substituir por um novo acidentalmente.                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| basic\_constraints<br /><br /><br />aliases: basicConstraints                                                     | list / elements=string |                                                                           | Indica restrições básicas, como se o certificado for uma CA.<br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| basic\_constraints\_critical<br /><br /><br />aliases: basicConstraints\_critical                                 | boolean                | Escolhas:<br />- false<br />(default)<br />- true                         | Se a extensão basicConstraints deve ser considerada crítica.<br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| common\_name <br /><br /><br />aliases: CN, commonName                                                            | string                 |                                                                           | Campo de nome do assunto da solicitação de assinatura de certificado.<br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| country\_name <br /><br /><br />aliases: C, countryName                                                           | string                 |                                                                           | Campo de nome do país do assunto da solicitação de assinatura do certificado.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| create\_subject\_key\_identifier                                                                                  | boolean                | Escolhas:<br />- false<br />(default)<br />- true                         | Crie o Identificador de Chave do Assunto a partir da chave pública. Observe que as CA's comerciais podem ignorar o valor, em vez disso, use um valor de sua própria escolha. Especificar esta opção é mais útil para certificados autoassinados ou para próprios CA. Observe que isso só é suportado se o backend de cryptography for usado!                                                                                                                                                                                                                                                                 |
| digest                                                                                                            | string                 | "sha256"<br />(default)                                                   | O resumo usado ao assinar a solicitação de assinatura de certificado com a chave privada.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| email\_address <br /><br /><br />aliases: E, emailAddress                                                         | string                 |                                                                           | Campo de endereço de e-mail do assunto da solicitação de assinatura do certificado.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| extended\_key\_usage <br /><br /><br />aliases: extKeyUsage, extendedKeyUsage                                     | list / elements=string |                                                                           | Restrições adicionais (por exemplo, autenticação de cliente, autenticação de servidor) nas finalidades permitidas para as quais a chave pública pode ser usada.                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| extended\_key\_usage\_critical<br /><br /><br />aliases: extKeyUsage\_critical, extendedKeyUsage\_critical        | boolean                | Escolhas:<br />- false<br />(default)<br />- true                         | Se a extensão extkeyUsage deve ser considerada crítica.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| force                                                                                                             | boolean                | Escolhas:<br />- false<br />(default)<br />- true                         | Se o pedido de assinatura de certificado deve ser gerado novamente forçado por este módulo atmosphere.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| key\_usage<br /><br />aliases: keyUsage                                                                           | list / elements=string |                                                                           | Isso define a finalidade (por exemplo, criptografia, assinatura, assinatura de certificado) da chave contida no certificado.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| key\_usage\_critical<br /><br /><br />aliases: keyUsage\_critical                                                 | boolean                | Escolhas:<br />- false<br />(default)<br />- true                         | Se a extensão keyUsage deve ser considerada crítica.<br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| locality\_name<br /><br />aliases: L, localityName                                                                | string                 |                                                                           | Campo localityName do assunto da solicitação de assinatura de certificado.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ocsp\_must\_staple<br /><br /><br />aliases: ocspMustStaple                                                       | boolean                | Escolhas:<br />- false<br />(default)<br />- true                         | Indica que o certificado deve conter a extensão OCSP Must Staple (Veja: https\://tools.ietf.org/html/rfc7633).<br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ocsp\_must\_staple\_critical<br /><br /><br /><br /><br /><br />aliases: ocspMustStaple\_critical                 | boolean                | Escolhas:<br />- false<br />(default)<br />- true                         | Se a extensão OCSP Must Staple deve ser considerada crítica. Observe que, de acordo com a RFC, essa extensão não deve ser marcada como crítica, pois os clientes antigos que não sabem sobre OCSP Must Staple são obrigados a rejeitar tais certificados (Veja: https\://tools.ietf.org/html/rfc7633#section-4).                                                                                                                                                                                                                                                                                             |
| organization\_name<br /><br />aliases: O, organizationName                                                        | string                 |                                                                           | Campo do nome da organização do assunto da solicitação de assinatura de certificado.<br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| organizational\_unit\_name<br /><br />aliases: OU, organizationalUnitName                                         | string                 |                                                                           | Campo de nome da unidade organizacional do assunto da solicitação de assinatura de certificado.<br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| path - *required*                                                                                                 | path                   |                                                                           | O nome do arquivo no qual a solicitação de assinatura de certificado OpenSSL gerada será gravada.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| privatekey\_passphrase                                                                                            | string                 |                                                                           | A frase secreta da chave privada. É necessária se a chave privada for protegida por senha.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| privatekey\_path                                                                                                  | path                   |                                                                           | O caminho para a chave privada a ser usada ao assinar a solicitação de assinatura de certificado. Privatekey\_path ou privatekey\_content deve ser especificado se state estiver present, mas não ambos.                                                                                                                                                                                                                                                                                                                                                                                                     |
| select\_crypto\_backend                                                                                           | string                 | Escolhas:<br />- auto<br />(default)<br />- cryptography<br />- pyopenssl | Determina qual back-end de criptografia usar. A escolha padrão é auto, que tenta usar cryptography, se disponível, e retorna para pyopenssl. Se definido como pyopenssl, tentará usar a biblioteca pyOpenSSL. Se definido como cryptography, tentará usar o biblioteca de criptografia.                                                                                                                                                                                                                                                                                                                      |
| state                                                                                                             | string                 | Escolhas:<br />- present<br />(default)<br />- absent                     | Se a solicitação de assinatura de certificado deve existir ou não, agir se o estado for diferente do que é declarado.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| state\_or\_province\_name<br /><br />aliases: ST, stateOrProvinceName                                             | string                 |                                                                           | Campo stateOrProvinceName do assunto da solicitação de assinatura de certificado.<br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| subject                                                                                                           | dictionary             |                                                                           | Pares de chave/valor que estarão presentes no campo de nome do assunto da solicitação de assinatura de certificado. Se você precisar especificar mais de um valor com a mesma chave, use uma lista como valor.                                                                                                                                                                                                                                                                                                                                                                                               |
| subject\_alt\_name<br /><br /><br /><br /><br /><br /><br /><br /><br /><br /><br /><br />aliases: subjectAltName | list / elements=string |                                                                           | Extensão do nome alternativo do assunto (SAN) a ser anexada à solicitação de assinatura do certificado. Pode ser uma 'string separada por vírgulas' ou uma lista YAML. Os valores devem ser prefixados por suas opções. (ou seja, e-mail, URI, DNS, RID, IP, dirName, otherName e os específicos para sua CA). Observe que se nenhum SAN for especificado, mas um nome comum, o nome comum será adicionado como SAN, exceto se useCommonNameForSAN for definido como false. Veja mais em https\://tools.ietf.org/html/rfc5280#section-4.2.1.6.                                                               |
| subject\_alt\_name\_critical<br /><br />aliases: subjectAltName\_critical                                         | boolean                | Escolhas:<br />- false<br />(default)<br />- true                         | Se a extensão subjectAltName deve ser considerada crítica.<br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| subject\_key\_identifier                                                                                          | string                 |                                                                           | O identificador de chave do assunto como uma string hexadecimal, em que dois bytes são separados por dois pontos. Exemplo: 00: 11: 22: 33: 44: 55: 66: 77: 88: 99: aa: bb: cc: dd: ee: ff : 00: 11: 22: 33. Observe que os CA's comerciais ignoram esse valor, respectivamente, usam um valor de sua própria escolha. Especificar esta opção é principalmente útil para certificados autoassinados ou para próprios CA's. Note que esta opção só pode ser usada se create\_subject\_key\_identifier for false. Isso só é suportado se o backend de criptografia for usado!                                   |
| use\_common\_name\_for\_san<br /><br />aliases: useCommonNameForSAN                                               | boolean                | Escolhas:<br />- false<br />- true<br />(default)                         | Se definido como true, o módulo preencherá o nome comum para subject\_alt\_name com 'DNS: prefix' se nenhum SAN for especificado.                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| version                                                                                                           | integer                | - 1<br />(default)                                                        | A versão da solicitação de assinatura de certificado. O único valor permitido de acordo com RFC 2986 é 1.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |

## Notas

- Para que você aproveite o máximo desse módulo, é necessário que o mesmo esteja funcionando em uma máquina remota ou host, que contenha os arquivos solicitados pelos parâmetros.

## Exemplos

```yaml
# Exemplo: Gerar uma solicitação de assinatura de certificado OpenSSL
- openssl_csr:
    path: /etc/ssl/csr/www.example.com.csr
    privatekey_path: /etc/ssl/private/example.com.pem
    common_name: www.example.com

# Exemplo: Gere uma solicitação de assinatura de certificado OpenSSL com uma chave privada protegida por senha
- openssl_csr:
    path: /etc/ssl/csr/www.example.com.csr
    privatekey_path: /etc/ssl/private/example.com.pem
    privatekey_passphrase: atmosphere
    common_name: www.example.com

# Exemplo: Gerar uma solicitação de assinatura de certificado OpenSSL com informações de assunto
- openssl_csr:
    path: /etc/ssl/csr/www.example.com.csr
    privatekey_path: /etc/ssl/private/example.com.pem
    country_name: FR
    organization_name: example
    email_address: jdoe@example.com
    common_name: www.example.com

# Exemplo: Gerar uma solicitação de assinatura de certificado OpenSSL com extensão subjectAltName
- openssl_csr:
    path: /etc/ssl/csr/www.example.com.csr
    privatekey_path: /etc/ssl/private/example.com.pem
    subject_alt_name: ['DNS:www.example.com', 'DNS:m.example.com']

# Exemplo: Gere um CSR OpenSSL com extensão subjectAltName com lista dinâmica
- openssl_csr:
    path: /etc/ssl/csr/www.example.com.csr
    privatekey_path: /etc/ssl/private/example.com.pem
    subject_alt_name: "{{ item.value | map('regex_replace', '^', 'DNS:') | list }}"
- with_dict:
    dns_server:
    - www.example.com
    - m.example.com

# Exemplo: Forçar a regeneração de uma solicitação de assinatura de certificado OpenSSL
- openssl_csr:
    path: /etc/ssl/csr/www.example.com.csr
    privatekey_path: /etc/ssl/private/example.com.pem
    force: yes
    common_name: www.example.com

# Exemplo: Gerar uma solicitação de assinatura de certificado OpenSSL com usos de chaves especiais
- openssl_csr:
    path: /etc/ssl/csr/www.example.com.csr
    privatekey_path: /etc/ssl/private/example.com.pem
    common_name: www.example.com
    key_usage:
      - digitalSignature
      - keyAgreement
    extended_key_usage:
      - clientAuth

# Exemplo: Gerar uma solicitação de assinatura de certificado OpenSSL com OCSP Must Stapler
- openssl_csr:
    path: /etc/ssl/csr/www.example.com.csr
    privatekey_path: /etc/ssl/private/example.com.pem
    common_name: www.example.com
    ocsp_must_staple: yes
```

## Valores retornados

| **Chave**           | **Tipo**               | **Retornado quando**              | **Descrição**                                                                                                                                      |
| ------------------- | ---------------------- | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| backup\_file        | string                 | Modificar e se o backup for true. | Nome do arquivo de backup criado.                                                                                                                  |
| basicConstraints    | list / elements=string | Modificar ou der Sucesso          | Indica se o certificado pertence a uma CA.                                                                                                         |
| extendedKeyUsage    | list / elements=string | Modificar ou der Sucesso          | Restrições adicionais sobre os objetivos da chave pública.                                                                                         |
| filename            | string                 | Modificar ou der Sucesso          | Caminho para a solicitação de assinatura de certificado gerada.                                                                                    |
| keyUsage            | list / elements=string | Modificar ou der Sucesso          | Finalidade para a qual a chave pública pode ser usada.                                                                                             |
| ocsp\_must\_staple  | boolean                | Modificar ou der Sucesso          | Indica se o certificado tem o recurso OCSP deve grampear habilitado.<br />                                                                         |
| privatekey          | string                 | Modificar ou der Sucesso          | O caminho para a chave privada TLS / SSL para a qual o CSR foi gerado. Será nenhum se a chave privada tiver sido fornecida em privatekey\_content. |
| subject             |  list / elements=list  | Modificar ou der Sucesso          | Uma lista das tuplas de assunto anexadas ao CSR.                                                                                                   |
| subjectAltName      | list / elements=string | Modificar ou der Sucesso          | Os nomes alternativos para os quais este CSR é válido.                                                                                             |


[title] Documentação Técnica
[path] /


[title] Coletor de Flows do Cilium
[path] Documentação Técnica/Observabilidade Kubernetes/

# Coletor de Flows do Cilium

Este documento fornece detalhes sobre o Deployment do coletor que traz os dados de flows gerados pelo Cilium através do Hubble Relay para o Simon.

## Pré requisitos

[https://docs.simonops.com/coletor-de-flows-do-cilium#rCaid](https://docs.simonops.com/coletor-de-flows-do-cilium#rCaid)

Certifique-se de que o [Cilium](https://docs.cilium.io/en/stable/gettingstarted/k8s-install-default/#cilium-quick-installation) já esteja habilitado em seu ambiente Kubernetes.&#x20;

Uma vez que o Cilium esteja em funcionamento, siga os passos abaixo para habilitar o Deployment responsável pela coleta do tráfego de rede detectado pelo [Hubble Relay](https://docs.cilium.io/en/stable/internals/hubble/#hubble-relay).

## Especificações do Deployment

[https://docs.simonops.com/coletor-de-flows-do-cilium#jGku9](https://docs.simonops.com/coletor-de-flows-do-cilium#jGku9)

O deployment usa a especificação YAML do Kubernetes para configurar e implantar o coletor de flows no namespace **kube-system**.

### YAML para Deployment

:::CodeblockTabs
YAML

```javascript
apiVersion: apps/v1
kind: Deployment
metadata:
  name: cilium-flow-collector
  namespace: kube-system
  labels:
    app: cilium-flow-collector
spec:
  replicas: 1
  selector:
    matchLabels:
      app: cilium-flow-collector
  template:
    metadata:
      labels:
        app: cilium-flow-collector
    spec:
      containers:
        - name: cilium-flow-collector
          image: simonops/cilium-flow-collector:latest
          resources:
            limits:
              memory: "200M"
          imagePullPolicy: IfNotPresent
          env:
            - name: COLLECT_FREQUENCY
              value: "5m"
            - name: HUBBLE_RELAY_ADDRESS
              value: "hubble-relay.kube-system.svc.cluster.local:80"
            - name: RECEIVER_ADDRESS
              value: "https://<SEU_DOMINIO_SIMON>/sphere-sync/api/sync/collector"
            - name: RECEIVER_API_KEY
              value: <GENERATED_API_KEY>
            - name: ACCUMULATOR_MEMORY_SIZE
              value: "100M"

```
:::

Os campos presentes em **env** são variáveis de ambiente que podem ser ajustadas para atender às necessidades específicas do seu ambiente:

- **COLLECT\_FREQUENCY**
  - **Descrição**: Define a frequência com que os dados de flow são coletados.
  - **Valor Padrão: 5m&#x20;**(5 minutos)
  - **Formato**: O valor deve ser especificado em uma combinação de unidades de tempo, como segundos (s), minutos (m), ou horas (h).
    - Exemplos: 10s (10 segundos), 5m (5 minutos), 1h (1 hora).
- **HUBBLE\_RELAY\_ADDRESS**
  - **Descrição**: Endereço do Hubble Relay usado para coletar os dados de flows.
  - **Valor Padrão:&#x20;**&#x68;ubble-relay.kube-system.svc.cluster.local:80
- **RECEIVER\_ADDRESS**
  - **Descrição**: Endereço da instância que receberá as métricas, onde os dados coletados serão armazenados. Esse campo pode se preenchido de duas formas:
    - IP e Porta do InfluxDB localizado na instância DB Worker de seu ambiente Simon (Exemplo: **127.0.0.1:8086**).
    - URL contendo o caminho da API de coleta do Simon **(/api/sync/collector).&#x20;**
      - Caso o domínio responda pela porta 80 ou 443, adicionar o prefixo **(/sphere-sync)&#x20;**(Exemplo: **https\://seu-dominio-simon.com/sphere-sync/api/sync/collector**)
      - Caso opte pelo envio diretamente pelo IP, utilizar a porta 18001 (Exemplo: **http\://127.0.0.1:18001/api/sync/collector**)
      - **\*&#x20;**&#x45;ssa opção **requer** o preenchimento da variável de ambient&#x65;**&#x20;RECEIVER\_API\_KEY**.
- **RECEIVER\_API\_KEY**
  - **Descrição**: Esse campo deve ser preenchido **apenas** caso opte por seguir com o envio através da API de coleta do Simon **(/api/sync/collector)**.&#x20;
  - A chave de acesso pode ser criada na interface de [Chaves de Acesso](https://docs.simonops.com/chaves-de-acesso) do Simon.
- **ACCUMULATOR\_MEMORY\_SIZE**
  - **Descrição**: Define o tamanho da memória do acumulador de dados usado pelo coletor de flows para a realização do envio em batch.
  - **Valor Padrão:&#x20;**&#x31;00M
  - **Formato**: O valor deve ser especificado em uma combinação de unidades de memória, como megabytes (M), mebibytes (Mi), gigabytes (G), gibibytes (Gi), etc.
    - Exemplos: 100M (100 megabytes), 100Mi (100 mebibytes), 1G (1 gigabyte), 1Gi (1 gibibyte).
  - **Exemplo de Alteração**:
    - Em um ambiente com mais recursos de memória, o valor pode ser aumentado.
    - Em um ambiente com restrições de memória, pode ser necessário reduzir o valor.

## Instruções de Implantação

**Salvar o arquivo YAML**: Copie o conteúdo YAML acima e salve em um arquivo chamado cilium-flow-collector-deployment.yaml.

**Aplicar o deployment**: Use o comando kubectl para aplicar o deployment no seu cluster Kubernetes.

```javascript
kubectl apply -f cilium-flow-collector-deployment.yaml
```

**Verificar o status**: Verifique o status do deployment para garantir que o coletor de flows foi implantado corretamente.

```javascript
kubectl get deployments -n kube-system
kubectl get pods -n kube-system -l app=cilium-flow-collector
```

**Valide as métricas:&#x20;**&#x41;pós checar a saúde do pod, você pode acompanhar a chegada das métricas através do [Grafana do Simon](https://docs.simonops.com/validando-coletas-customizadas), utilizando a seguinte Query:

```javascript
cilium_flows{}[5m]
```

\* O primeiro envio das métricas para o Simon pode levar o tempo especificado pelas variáveis **COLLECT\_FREQUENCY**, pois as mesmas são responsáveis por acumular os dados e envia-las em batch periodicamente.

[title] Informações do Certificado OpenSSL
[path] Documentação Técnica/Automações/Criptomoeda/

## Resumo

- Este módulo permite consultar informações sobre certificados OpenSSL.

## Parâmetros

| **Parâmetro**           | **Tipo**   | **Escolhas \| Valor Padrão**                                        | **Comentários**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ----------------------- | ---------- | ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| content                 | string     |                                                                     | Conteúdo do certificado X.509 em formato PEM.<br /><br />Qualquer *caminho* ou *conteúdo* deve ser especificado, mas não ambos.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| path                    | path       |                                                                     | Caminho absoluto remoto de onde o arquivo de certificado é carregado.<br /><br />Qualquer *caminho* ou *conteúdo* deve ser especificado, mas não ambos.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| select\_crypto\_backend | string     | Escolhas:<br />- auto(default)<br />- cryptography<br />- pyopenssl | Determina qual back-end criptográfico usar.<br /><br />A escolha padrão é `auto`, que tenta usar, `cryptography` se disponível, e retorna a `pyopenssl`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| valid\_at               | dictionary |                                                                     | Um ditado de mapeamento de nomes para especificações de tempo. Cada vez aqui especificado será verificado se o certificado é válido neste momento. Veja o `valid_at` valor de retorno para informações sobre o resultado.<br /><br />O tempo pode ser especificado como tempo relativo ou como carimbo de data / hora absoluto.<br /><br />A hora sempre será interpretada como UTC.O formato válido é `[+-]timespec \| ASN.1 TIME` onde o timespec pode ser um inteiro + `[w \| d \| h \| m \| s]` (por exemplo `+32w1d2h`, e ASN.1 TIME (em outras palavras, padrão `YYYYMMDDHHMMSSZ`). Observe que todos os carimbos de data / hora serão tratados como sendo UTC. |

## Notas

Observação

- Todos os valores de timestamp são fornecidos no formato ASN.1 TIME, ou seja, seguindo o `YYYYMMDDHHMMSSZ` padrão. Eles estão todos em UTC.
- Suporta check\_mode.

## Exemplos

```yaml
# Generate a Self Signed OpenSSL certificate
  openssl_certificate:
    path: /etc/ssl/crt/atmosphere.com.crt
    privatekey_path: /etc/ssl/private/atmosphere.com.pem
    csr_path: /etc/ssl/csr/atmosphere.com.csr
    provider: selfsigned


# Get information on the certificate

# Get information on generated certificate
  openssl_certificate_info:
    path: /etc/ssl/crt/atmosphere.com.crt
  register: result

# Dump information
  debug:
    var: result


# Check whether the certificate is valid or not valid at certain times, fail
# if this is not the case. The first task (openssl_certificate_info) collects
# the information, and the second task (assert) validates the result and
# makes the playbook fail in case something is not as expected.

# Test whether that certificate is valid tomorrow and/or in three weeks
  openssl_certificate_info:
    path: /etc/ssl/crt/atmosphere.com.crt
    valid_at:
      point_1: "+1d"
      point_2: "+3w"
  register: result

# Validate that certificate is valid tomorrow, but not in three weeks
  assert:
    that:
      - result.valid_at.point_1      # valid in one day
      - not result.valid_at.point_2  # not valid in three weeks
```

## Valores Retornados

| **Chave**                              | **Tipo**               | **Retornado quando**                             | `Descrição`                                                                                                                                                                                                                       |   |
| -------------------------------------- | ---------------------- | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - |
| authority\_cert\_issuer                | list / elements=string | sucesso e se o backend pyOpenSSL *não* for usado | O emissor do certificado da autoridade de certificação como uma lista de nomes gerais.<br /><br />É `none` se a  `AuthorityKeyIdentifier` extensão não estiver presente.                                                          |   |
| authority\_cert\_serial\_number <br /> | integer                | sucesso e se o backend pyOpenSSL *não* for usado | O número de série do certificado da autoridade de certificação.<br /><br />É `none` se a `AuthorityKeyIdentifier` extensão não estiver presente.                                                                                  |   |
| authority\_key\_identifier             | string                 | sucesso e se o backend pyOpenSSL *não* for usado | O identificador da chave da autoridade de certificação.<br /><br />O identificador é retornado em hexadecimal, com `:` usado para separar bytes.<br /><br />É `none` se a `AuthorityKeyIdentifier` extensão não estiver presente. |   |
| basic\_constraints                     | list / elements=string | sucesso                                          | Entradas na `basic_constraints` extensão ou `none` se a extensão não estiver presente.                                                                                                                                            |   |
| basic\_constraints\_critical           | boolean                | sucesso                                          | Se a `basic_constraints` extensão é crítica.<br />                                                                                                                                                                                |   |
| expired                                | boolean                | sucesso                                          | Se o certificado expirou (em outras palavras, `notAfter` está no passado).<br />                                                                                                                                                  |   |
| extended\_key\_usage                   | list / elements=string | sucesso                                          | Entradas na `extended_key_usage` extensão ou nonese a extensão não estiver presente.                                                                                                                                              |   |
| extended\_key\_usage\_critical         | boolean                | sucesso                                          | Se a `extended_key_usage` extensão é crítica.<br />                                                                                                                                                                               |   |
| extensions\_by\_oid                    | dictionary             | sucesso                                          | Retorna um dicionário para cada extensão OID.                                                                                                                                                                                     |   |
| fingerprints                           | dictionary             | sucesso                                          | Impressões digitais da forma codificada por DER de todo o certificado.<br /><br />Para cada algoritmo hash disponível, a impressão digital é calculada.                                                                           |   |
| issuer                                 | dictionary             | sucesso                                          | O emissor do certificado.<br /><br />Observe que para valores repetidos, apenas o último será retornado.                                                                                                                          |   |
| issuer\_ordered                        | list / elements=list   | sucesso                                          | O emissor do certificado como uma lista ordenada de tuplas.                                                                                                                                                                       |   |
| key\_usage                             | string                 | sucesso                                          | Entradas na `key_usage` extensão ou nonese a extensão não estiver presente.                                                                                                                                                       |   |
| key\_usage\_critical                   | boolean                | sucesso                                          | Se a `key_usagee` xtensão é crítica.<br />                                                                                                                                                                                        |   |
| not\_after                             | string                 | sucesso                                          | `notAfter` data como ASN.1 TIME.                                                                                                                                                                                                  |   |
| not\_before                            | string                 | sucesso                                          | `notBefore` data como ASN.1 TIME.                                                                                                                                                                                                 |   |
| ocsp\_must\_staple                     | boolean                | sucesso                                          | `yes` se a extensão OCSP Must Staple estiver presente, `none` caso contrário.<br />                                                                                                                                               |   |
| ocsp\_must\_staple\_critical           | boolean                | sucesso                                          | Se a `ocsp_must_staple` extensão é crítica.<br />                                                                                                                                                                                 |   |
| ocsp\_uri                              | string                 | sucesso                                          | O URI do respondente OCSP, se incluído no certificado. Será `none` se nenhum URI respondente do OCSP for incluído.<br />                                                                                                          |   |
| public\_key                            | string                 | sucesso                                          | Chave pública do certificado em formato PEM.                                                                                                                                                                                      |   |
| public\_key\_fingerprints              | dictionary             | sucesso                                          | Impressões digitais da chave pública do certificado.<br /><br />Para cada algoritmo hash disponível, a impressão digital é calculada.                                                                                             |   |
| serial\_number                         | integer                | sucesso                                          | O número de série do certificado.                                                                                                                                                                                                 |   |
| signature\_algorithm                   | string                 | sucesso                                          | O algoritmo de assinatura usado para assinar o certificado.                                                                                                                                                                       |   |
| subject                                | dictionary             | sucesso                                          | O assunto do certificado como um dicionário.<br /><br />Observe que para valores repetidos, apenas o último será retornado.                                                                                                       |   |
| subject\_alt\_name                     | list / elements=string | sucesso                                          | Entradas na `subject_alt_name` extensão ou nonese a extensão não estiver presente.                                                                                                                                                |   |
| subject\_alt\_name\_critical           | boolean                | sucesso                                          | Se a `subject_alt_name` extensão é crítica.<br />                                                                                                                                                                                 |   |
| subject\_key\_identifier               | string                 | sucesso e se o backend pyOpenSSL *não* for usado | O identificador da chave do assunto do certificado.<br /><br />O identificador é retornado em hexadecimal, com `:` usado para separar bytes.<br /><br />É `none` se a `SubjectKeyIdentifier` extensão não estiver presente.       |   |
| subject\_ordered                       | list / elements=list   | sucesso                                          | O assunto do certificado como uma lista ordenada de tuplas.                                                                                                                                                                       |   |
| valid\_at                              | dictionary             | sucesso                                          | Para cada carimbo de data / hora fornecido na opção *valid\_at* , um booleano se o certificado é válido naquele momento ou não.<br />                                                                                             |   |
| version                                | integer                | sucesso                                          | A versão do certificado.                                                                                                                                                                                                          |   |

### Subopções da chave de retorno extensions\_by\_oid

| **Chave** | **Tipo** | **Retornado quando** | **Descrição**                                              |
| --------- | -------- | -------------------- | ---------------------------------------------------------- |
| critical  | boolean  | sucesso              | Se a extensão é crítica.                                   |
| value     | string   | sucesso              | O valor codificado em Base64 (no formato DER) da extensão. |


[title] OpenSSL CSR Info
[path] Documentação Técnica/Automações/Criptomoeda/

## Resumo

- Fornece informações de solicitações de assinatura de certificado OpenSSL (CSR).

## Parâmetros

| **Parâmetro**            | **Tipo** | **Escolhas \| Valor Padrão**                                                     | **Comentários**                                                                                                                                                                                                                                                                         |
| ------------------------ | -------- | -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| path - *required*        | path     |                                                                                  | Caminho absoluto remoto de onde o arquivo CSR é carregado. Qualquer caminho ou conteúdo deve ser especificado, mas não ambos.                                                                                                                                                           |
| select\_crypto\_backend  | string   | Escolhas:<br />- auto<br />(default)<br />- cryptography<br />- pyopenssl        | Determina qual back-end de criptografia usar. A escolha padrão é auto, que tenta usar criptografia, se disponível, e retorna para pyopenssl. Se definido como pyopenssl, tentará usar a biblioteca pyOpenSSL. Se definido como cryptography, tentará usar o biblioteca de criptografia. |

## Notas

- Para que você aproveite o máximo desse módulo, é necessário que o mesmo esteja funcionando em uma máquina remota ou host, que contenha os arquivos solicitados pelos parâmetros.
  Exemplos

```yaml
# Exemplo: Gerar uma solicitação de assinatura de certificado OpenSSL
- openssl_csr:
    path: /etc/ssl/csr/www.exemplo.com.csr
    privatekey_path: /etc/ssl/private/exemplo.com.pem
    common_name: www.exemplo.com

# Exemplo: Obtenha informações sobre o CSR
- openssl_csr_info:
    path: /etc/ssl/csr/www.exemplo.com.csr
  register: result

# Exemplo: Retornar informações
- debug:
    var: result

```



## Valores retornados

| **Chave**                                    | **Tipo**               | **Retornado quando**                         | **Descrição**                                                                                                                                                                                      |
| -------------------------------------------- | ---------------------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| signature\_valid                             | boolean                | Sucesso                                      | Se a assinatura do CSR é válida. Caso a verificação retorne (false), o módulo irá falhar.                                                                                                          |
| basic\_constraints                           | list / elements=string | Sucesso                                      | Entradas na extensão (basic\_constraints) ou (nenhuma) se a extensão não estiver presente.                                                                                                         |
| basic\_constraints\_critical                 | boolean                | Sucesso                                      | Se a extensão (basic\_constraints) é crítica.                                                                                                                                                      |
| extended\_key\_usage                         | list / elements=string | Sucesso                                      | Entradas na extensão (extended\_key\_usage) ou (none) se a extensão não estiver presente.                                                                                                          |
| extended\_key\_usage\_critical               | boolean                | Sucesso                                      | Se a extensão (extended\_key\_usage) é crítica.                                                                                                                                                    |
| extensions\_by\_oid<br />(Possíveis valores) | dictionary             | Sucesso                                      | Retorna um dicionário para cada extensão OID                                                                                                                                                       |
| key\_usage                                   | string                 | Sucesso                                      | Entradas na extensão (key\_usage) ou (none) se a extensão não estiver presente.                                                                                                                    |
| key\_usage\_critical                         | boolean                | Sucesso                                      | Se a extensão (key\_usage) é crítica.                                                                                                                                                              |
| subject\_alt\_name                           | list / elements=string | Sucesso                                      | Entradas na extensão (subject\_alt\_name) ou (none) se a extensão não estiver presente.                                                                                                            |
| subject\_alt\_name\_critical                 | boolean                | Sucesso                                      | Se a extensão (subject\_alt\_name) é crítica.                                                                                                                                                      |
| ocsp\_must\_staple                           | boolean                | Sucesso                                      | (true) se a extensão OCSP deve grampear estiver presente, (none) caso contrário.                                                                                                                   |
| ocsp\_must\_staple\_critical                 | boolean                | Sucesso                                      | Se a extensão (ocsp\_must\_staple) é crítica.                                                                                                                                                      |
| subject                                      | dictionary             | Sucesso                                      | O assunto do CSR como um dicionário. Observe que para valores repetidos, apenas o último será retornado.                                                                                           |
| subject\_ordered                             | list / elements=list   | Sucesso                                      | O assunto do CSR como uma lista ordenada de tuplas.                                                                                                                                                |
| public\_key                                  | string                 | Sucesso                                      | Chave pública do CSR no formato PEM.                                                                                                                                                               |
| public\_key\_fingerprints                    | dictionary             | Sucesso                                      | Impressões digitais da chave pública do CSR. Para cada algoritmo hash disponível, a impressão digital é calculada.                                                                                 |
| subject\_key\_identifier                     | string                 | Sucesso e se o backend pyOpenSSL não é usado | O identificador de chave do assunto do CSR. O identificador é retornado em hexadecimal, com (:) usado para separar bytes. É (none) se a extensão (SubjectKeyIdentifier) não estiver presente.      |
| authority\_key\_identifier                   | string                 | Sucesso e se o backend pyOpenSSL não é usado | O identificador da chave de autoridade do CSR. O identificador é retornado em hexadecimal, com (:) usado para separar bytes. É (none) se a extensão (AuthorityKeyIdentifier) não estiver presente. |
| authority\_cert\_issuer                      | list / elements=string | Sucesso e se o backend pyOpenSSL não é usado | O emissor do certificado de autoridade do CSR como uma lista de nomes gerais. É (none) se a extensão (AuthorityKeyIdentifier) não estiver presente.                                                |
| authority\_cert\_serial\_number              | integer                | Sucesso e se o backend pyOpenSSL não é usado | O número de série do certificado de autoridade do CSR. É (none) se a extensão (AuthorityKeyIdentifier) não estiver presente.                                                                       |

## Subopções da chave de retorno extensions\_by\_oid

| **Chave** | **Tipo** | **Retornado quando** | **Descrição**                                              |
| --------- | -------- | -------------------- | ---------------------------------------------------------- |
| critical  | boolean  | Sucesso              | Se a extensão é crítica.                                   |
| value     | string   | Sucesso              | O valor codificado em Base64 (no formato DER) da extensão. |


[title] Obter Certificado
[path] Documentação Técnica/Automações/Criptomoeda/

## Resumo

- Obtenha o certificado de um host\:porta.

## Parâmetros

| **Parâmetro**           | **Tipo** | **Escolhas \| Valor Padrão**                                              | **Comentários**                                                                                                                                                                                                                                                                  |
| ----------------------- | -------- | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| host - *required*       | string   |                                                                           | O host que queira obter o certificado.                                                                                                                                                                                                                                           |
| ca\_cert                | path     |                                                                           | Um arquivo PEM contendo um ou mais certificados raiz; se estiver presente, o certificado será validado em relação a esses certificados raiz. Observe que isso só valida se o certificado é assinado pela rede; não que o certificado seja válido para o host que o apresenta.    |
| port - *required*       | integer  |                                                                           | A porta para se conectar.                                                                                                                                                                                                                                                        |
| proxy\_host             | string   |                                                                           | Host proxy usado para obter o certificado.                                                                                                                                                                                                                                       |
| proxy\_port             | integer  | - 8080<br />(default)                                                     | Porta proxy usada para obter o certificado.                                                                                                                                                                                                                                      |
| timeout                 | integer  | - 10<br />(default)                                                       | O tempo limite em segundos.                                                                                                                                                                                                                                                      |
| select\_crypto\_backend | string   | Escolhas:<br />- auto<br />(default)<br />- cryptography<br />- pyopenssl | Determina qual back-end de criptografia usar. A escolha padrão é (auto), que tenta usar (cryptography) se disponível e volta para (pyopenssl). Se definido como (pyopenssl), tentará usar a mesma. Se definido como C (cryptography), tentará usar a biblioteca de criptografia. |

## Notas

- Ao usar o parâmetro ca\_cert no OS X, foi relatado que, em algumas condições, a validação sempre será bem-sucedida.

## Exemplos

```yaml
# Exemplo: Obtenha o certificado de uma porta RDP
- get_certificate:
    host: "1.2.3.4"
    port: 3389
  delegate_to: localhost
  run_once: true
  register: cert

# Exemplo: Obtenha um certificado de uma porta https
- get_certificate:
    host: "www.google.com"
    port: 443
  delegate_to: localhost
  run_once: true
  register: cert

# Exemplo: Quantos dias até o certificado expirar
- debug:
    msg: "cert expires in: {{ expire_days }} days."
   vars:
    expire_days: "{{ (( cert.not_after | to_datetime('%Y%m%d%H%M%SZ')) - (atmosphere_date_time.iso8601 | to_datetime('%Y-%m-%dT%H:%M:%SZ')) ).days }}"

```



## Valores retornados

| **Chave**                           | **Tipo**                   | **Retornado quando** | **Descrição**                                             |
| ----------------------------------- | -------------------------- | -------------------- | --------------------------------------------------------- |
| cert                                | string                     | Sucesso              | O certificado obtido da porta.                            |
| expired                             | boolean                    | Sucesso              | Booleano indicando se o certificado expirou.              |
| extensions<br />(Possíveis valores) | list / elements=dictionary | Sucesso              | Extensões aplicadas ao certificado.                       |
| issuer                              | dictionary                 | Sucesso              | Informações sobre o emissor do certificado.               |
| not\_after                          | string                     | Sucesso              | Data de expiração do certificado.                         |
| not\_before                         | string                     | Sucesso              | Data de emissão do certificado.                           |
| serial\_number                      | string                     | Sucesso              | O número de série do certificado.                         |
| signature\_algorithm                | string                     | Sucesso              | O algoritmo usado para assinar o certificado.             |
| subject                             | dictionary                 | Sucesso              | Informações sobre o assunto do certificado (OU, CN, etc). |
| version                             | string                     | Sucesso              | O número da versão do certificado.                        |



## Subcampos da chave de retorno extensions

| **Chave**   | **Tipo** | **Retornado quando** | **Descrição**                                            |
| ----------- | -------- | -------------------- | -------------------------------------------------------- |
| asn1\_data  | string   | Sucesso              | O conteúdo ASN.1 codificado em Base64 da extensão.<br /> |
| critical    | boolean  | Sucesso              | Se a extensão é crítica.<br />                           |
| name        | string   | Sucesso              | O nome da extensão.                                      |


[title] Comando
[path] Documentação Técnica/Automações/Comandos/

### Resumo

- Execute os comandos desejados.

## Paramêtros

| Paramêtros             | Tipos                             | Escolhas Valor Padrão                           | Comentários                                                                                                                                                                                                                                                                                                    |
| ---------------------- | --------------------------------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| argv                   | lista / elementos = <br />strings |                                                 | Transmita o comando como uma lista em vez de uma string. Use argv para evitar citar valores que, de outra forma, seriam interpretados incorretamente (por exemplo "nome do usuário"). Apenas a forma de string (forma livre) ou de lista (argv) pode ser fornecida, não ambas. Um ou outro deve ser fornecido. |
| chdir                  | caminho                           |                                                 | Mudar o diretório antes de executar o comando.                                                                                                                                                                                                                                                                 |
| comando                | corda                             |                                                 | O comando será executado.                                                                                                                                                                                                                                                                                      |
| cria                   | caminho                           |                                                 | Um nome ou arquivo de padrão glob. Se já existr um arquivo correspondente, está etapa não será realizada.                                                                                                                                                                                                      |
| forma livre            | corda                             |                                                 | O módulo de comando usa uma string de formato livre como um comando para ser executado. Não há nenhum paramêtro real denominado "formato livre".<br />                                                                                                                                                         |
| remove                 | caminho                           |                                                 | Um nonme de arquivo ou padrão glob. Se houver um arquivo correspondente, está etapa será realizada.                                                                                                                                                                                                            |
| padrão                 | corda                             |                                                 | Defina o stdin do comando diretamente para o valor especificado.                                                                                                                                                                                                                                               |
| stdin\_add\_nova\_lina | boleano                           | Escolhas:<br />-verdadeiro<br />-falso (padrão) | SE definido como verdadeiro, a estação atmosférica é uma nova linha aos dados stdin.                                                                                                                                                                                                                           |
| strip\_empty\_ends     | boolean                           | Escolhas:<br />-verdadeiro<br />-falso (padrão) | Retire as linhas vazias do final de  stdout/stderr no resultado.                                                                                                                                                                                                                                               |
| warn                   | boolean                           | Escolhas:<br />-verdadeiro<br />-falso (padrão) | Habilite ou desabilite os avisos de tarefa.                                                                                                                                                                                                                                                                    |



# Notas

- Se você deseja executar um comando por meio do shell (digamos que usamos \<,>,| e assim por diante) uma análise de metacaracteres do shell pode fazer com que comandos inesperados sejam executados se a cotação não for feita corretamente, portanto é mais seguro usar o módulo de comando quando possível.
- Crie, remova e chdir podem ser especifucados após o comando. Poe exemplo, se você deseja executar um comando, se um determinado arquivo não existir, use-o.
- O modo de verificação é suportado após passar cria ou remove. Se você estiver executando no mode de verificação, e qualquer um deles especificados, o módulo verifcará a existência do arquivo e relatará o status alterado correto. Se não for entregue, a tarefa será ignorada.

# Exemplos

\# Exemplo: Retornar motd para variável registrada
\- command: cat /etc/motd
&#x20; register: mymotd

\# Exemplo: Execute o comando se /path/to/database não existir (sem a palavra-chave 'args').
\- command: /usr/bin/make\_database.sh db\_user db\_name creates=/path/to/database

\# 'args' é uma palavra-chave de tarefa, passada no mesmo nível que o módulo
\# Exemplo: Execute o comando se /path/to/database não existir (com a palavra-chave 'args').
\- command: /usr/bin/make\_database.sh db\_user db\_name
&#x20; args:
&#x20;   creates: /path/to/database

\# 'cmd' é um parâmetro do módulo
\# Exemplo: Execute o comando se /path/to/database não existir (com o parâmetro 'cmd').
\- command:
&#x20;   cmd: /usr/bin/make\_database.sh db\_user db\_name
&#x20;   creates: /path/to/database

\# Exemplo: Altere o diretório de trabalho para somedir/ e,&#x20;
\#          execute o comando como db\_owner se /path/to/database não existir.
\- command: /usr/bin/make\_database.sh db\_user db\_name
&#x20; become: yes
&#x20; become\_user: db\_owner
&#x20; args:
&#x20;   chdir: somedir/
&#x20;   creates: /path/to/database

\# 'argv' é um parâmetro, identado um nível do módulo
\# Exemplo: Use 'argv' para enviar um comando como uma lista - deixe o 'command' vazio
\- command:
&#x20;   argv:
&#x20;     \- /usr/bin/make\_database.sh
&#x20;     \- Username with whitespace
&#x20;     \- dbname with whitespace

\# Exemplo: Use com segurança a variável de modelo para executar o comando. Sempre use o filtro de cotação para evitar problemas de injeção.
\- command: cat \{\{ myfile|quote }}
&#x20; register: myoutput

## &#x20;Valores devolvidos

| **Chave**        | **Tipo**                | **Retornando&#x20;**<br />**quando** | **Descrição**                            |
| ---------------- | ----------------------- | ------------------------------------ | ---------------------------------------- |
| comando          | lista/ elementos=string | Sempre                               | O comando executado pela tarefa          |
| delta            | corda                   | Sempre                               | O tempo delta de execuação do comando    |
| fim<br />começar | corda                   | Sempre                               | A hora de término de execução do comando |
|                  | corda                   | Sempre                               | A hora de início de execução do comando  |
|                  |                         |                                      |                                          |
|                  |                         |                                      |                                          |




[title] Observabilidade Kubernetes
[path] Documentação Técnica/


[title] Comando Powershell
[path] Documentação Técnica/Automações/Comandos/

## Resumo

- Executar o comando powershell por meio de um cliente PSRP (PowerShell Remoting Protocol)

## Paramêtros

| **Paramêtros**             | **Tipo** | **Escolhas \|&#x20;**<br />**Valor Padrão** | **Comentários**                                                                                                                                    |
| -------------------------- | -------- | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| servidor                   | corda    |                                             | O nome do host ou endereço IP do ho ao qual se conectar                                                                                            |
| porta                      | inteiro  | 5985                                        | Porta para se conectar, o padrão é 59                                                                                                              |
| SSL-SSL...                 | bool     | falso                                       | Você deve se conectar por http ou http                                                                                                             |
| nome do usuário            | str      |                                             | O nome do usuário para se conectar, é necessário para todas as autorizaões, exceto certificado e opcionalmente necessário para negociação/kerberos |
| senha                      | str      |                                             | Uma senha para o nome do usuário                                                                                                                   |
| comando                    | str      | 0                                           | Comando a ser executado                                                                                                                            |
| reconexão\_tentativas      | inteiro  | 30                                          | Número de tentativas de um problema de execução                                                                                                    |
| tempo\_limite\_de\_conexão | inteiro  | 30                                          | O tempo limite de uma conexão HTTP                                                                                                                 |
| tempo de ler esgotado      | inteiro  | verdadeiro                                  | O tempo limite para receber uma resposta do servidor depois que uma solicitação foi feita                                                          |
| mostrar\_erros<br />       | bool     | verdadeiro                                  | As linhas de erros retornam se existirem                                                                                                           |
| mostrar\_avisos            | bool     |                                             | Retorna linha de avisos se existirem                                                                                                               |

## Notas

- As instruçoes para habilitar o PSRP do lado do Windows podem ser vistas em [Habilitando o WinRM para PSRP (PowerShell Remoting Protocol)](docId\:EIjRozXpEDl_6RPO99TrC)&#x20;

## Exemplos

\# Exemplo: Roda um comando de echo e força um erro para o output.
powershell\_command:
&#x20; server: 127.0.0.1
&#x20; username: user\@Domain
&#x20; password: pssw123
&#x20; command: |
&#x20;   echo ("Hey, i'm echoing!")
&#x20;   Write-Warning "This is only a test warning."
&#x20;   throw "This is an error."

\# Exemplo: Roda um programa python.
powershell\_command:
&#x20; server: 127.0.0.1
&#x20; username: user
&#x20; password: pssw123
&#x20; command: |
&#x20;   Set-Location -Path C:\\\Users\\\65a\\\Downloads;
&#x20;   .\\\python\\\python.exe main.py --sentence "Sentence passed by args." -n 5

\# Exemplo: Cria um arquivo em uma pasta, escreve um conteúdo.
powershell\_command:
&#x20; server: 127.0.0.1
&#x20; username: user\@Domain
&#x20; password: pssw123
&#x20; command: |
&#x20;   Set-Location -Path C:\\\Users\\\65a\\\Downloads;
&#x20;   New-Item test.txt;
&#x20;   Set-Content test.txt 'Some content for the file';
&#x20;   get-Content test.txt;

\# Exemplo: Cria um arquivo em uma pasta de rede.
powershell\_command:
&#x20; server: 127.0.0.1
&#x20; username: user
&#x20; password: pssw123
&#x20; command: |
&#x20;   New-Item -Path "\\\\\srv-br-001\\\Users\\\Public\\\FOLDER1" -ItemType Directory

\# Exemplo: Lista em json as políticas de execução.
powershell\_command:
&#x20; server: 127.0.0.1
&#x20; username: user
&#x20; password: pssw123
&#x20; ssl: false
&#x20; command: |
&#x20;   Get-Execution Policy -List | ConvertTo-Json

## &#x20;Valores devolvidos

| **Chave&#x20;**   | **Tipo** | **Retornando quando** | **Descrição**                                 |
| ----------------- | -------- | --------------------- | --------------------------------------------- |
| saída             | corda    | Sucesso               | Saída do comendo executado                    |
| teve\_erros       | bool     | Sucesso               | Informa se o comando executado retornou erros |
| erros\_de\_saía   | lista    | Sucesso               | Lista de strings contendo os erros ocorridos  |
| avisos\_de\_saída | lista    | Sucesso               | Lista de strings contendo os avisos ocorridos |




[title] Telegram
[path] Documentação Técnica/Automações/

## Resumo

- Envie notificações via telegram bot, para um grupo ou usuário verificado.
- Além disso, o usuário pode tentar usar qualquer outro método de API de bot do telegram, se você especificar o argumento *api\_method*.

## Parâmetros

| **Parâmetro**                  | **Tipo** | **Escolhas \| Valor Padrão**                          | **Obrigatório** | **Comentários**                                                                                                                                                                                                                                                                                                                                                   |
| ------------------------------ | -------- | ----------------------------------------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| token                          | string   |                                                       | Sim             | Token que identifica seu bot do telegram.                                                                                                                                                                                                                                                                                                                         |
| chat\_id                       | string   |                                                       | Sim             | Grupo de telegram ou usuário chat\_id.                                                                                                                                                                                                                                                                                                                            |
| msg                            | string   |                                                       | Sim             | Qual mensagem você deseja enviar. Se a mensagem a ser enviada for um link a opção msg\_format terá que ser html                                                                                                                                                                                                                                                   |
| msg\_format                    | string   | Escolhas:<br />-MarkdownV2<br />(default)<br />- html | Não             | Formato da mensagem. Opções de formatação, `MarkdownV2` e `html` descrito na documentação da API Telegram (https\://core.telegram.org/bots/api#formatting-options). Se a opção for `MarkdownV2` definida, a mensagem não será formatada.<br />O formato `html`  suporta apenas alguns tipos de tags. Veja mais em: https\://core.telegram.org/bots/api#html-style |
| disable\_notification          | boolean  |                                                       | Não             | Desabilita notificações da mensagem no celular. Default definido como `True`                                                                                                                                                                                                                                                                                      |
| disable\_web\_page\_preview    | boolean  |                                                       |                 | Desabiita visualização da página na mensagem                                                                                                                                                                                                                                                                                                                      |
| reply\_to\_mesage\_id          | string   |                                                       | Não             | Se a mensagem for um reply a mensagem original é identificada com um ID                                                                                                                                                                                                                                                                                           |
| allow\_sending\_without\_reply | boolean  |                                                       | Não             | Escolha `True`se a mensagem tenha que ser mandada mesmo se a mesagem de reply não for identificada. Default definido como `False`                                                                                                                                                                                                                                 |



## Notas

- Você precisará de uma conta e criar um bot no telegram para usar este módulo.
- `html`  suporta apenas alguns tipos de tags. Exemplos:

## Exemplos

```yaml
#Envia mensagem de texto para um grupo(chat_id negativo) ou usuário(chat_id positivo)
- name: Send Message
  telegram:
    token: 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
    chat_id: -123456789
    msg: 'teste'
    msg_format: 'html'
    disable_notification: True
    disable_web_page_preview: False
    reply_to_message_id: 0
    allow_sending_without_reply: False
    register: result
```

## Valores Retornados

| **Chave**       | **Tipo** | **Retornado quando** | **Descrição**                              |
| --------------- | -------- | -------------------- | ------------------------------------------ |
| msg             | string   | sucesso              | A mensagem que você tentou enviar          |
| telegram\_error | string   | fracasso             | Mensagem de erro obtida da API do Telegram |


[title] Shell
[path] Documentação Técnica/Automações/Comandos/

## Resumo

- Execute comandos do shell por executáveis nos destinos.

## Parâmetros

| **Parâmetro** | **Tipo** | **Escolhas \| Valor Padrão** | **Comentários**                                                                                         |
| ------------- | -------- | ---------------------------- | ------------------------------------------------------------------------------------------------------- |
| chdir         | caminho  |                              | Mudar para um diretório antes de executar um comando                                                    |
| argumentos    | caminho  |                              | Altere o Shell usado para executar o comendo<br />Isso espera um caminho absoluto para o seguinte nível |
| argumentos    | corda    | -" " (padrão)                | Argumentos                                                                                              |

### Exemplos

:::CodeblockTabs
YAML

```javascript
# Exemplo: Cat file from default shell
- shell: 
    arguments: cat /etc/hosts
  register: result
```
:::

### Valores devolvidos

| **Chave** | **Tipo**   | **Retornando quando** | **Descrição**                      |
| --------- | ---------- | --------------------- | ---------------------------------- |
| mudado    | boleano    | Sempre                | Se a operação foi realizada ou não |
| validação | dicionário | Sempre                | Resultado completo da operação     |


[title] Informações da Conta Acne
[path] Documentação Técnica/Automações/Criptomoeda/

## Resumo

- Permite recuperar informações em contas com uma CA que suporte o protocolo ACME , como Let's Encrypt .
- Este módulo só funciona com o protocolo ACME v2.

## Parâmetros

| **Parâmetro**              | **Tipo** | **Escolhas \|&#x20;*****Valores padrão*** | **Comentários**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| -------------------------- | -------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_key\_content      | string   |                                           | Conteúdo da chave RSA ou curva elíptica da conta ACME.Mutuamente exclusivo com `account_key_src`.<br /><br />Necessário se `account_key_src` não for usado.<br /><br />Atenção: o conteúdo será gravado em um arquivo temporário, que será excluído pelo Atmosphere quando o módulo for concluído. Como essa é uma chave privada importante — ela pode ser usada para alterar a chave da conta ou revogar seus certificados sem conhecer suas chaves privadas —, isso pode não ser aceitável.<br /><br />Caso `cryptography` seja usado, o conteúdo não é gravado em um arquivo temporário. Ainda pode acontecer que ele seja gravado em disc no processo de mover o módulo com seu argumento para o nó onde ele é executado. |
| account\_key\_passphrase   | string   |                                           | Phassphrase a ser usada para decodificar a chave da conta.<br /><br />Nota: isso não é suportado pelo `back- openssl`, apenas pelo `back- cryptography`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| account\_key\_src          | path     |                                           | Caminho para um arquivo que contém a chave RSA ou curva elíptica da conta ACME.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| account\_uri               | string   |                                           | Se especificado, assume que o URI da conta é o informado. Se a chave da conta não corresponder a essa conta ou não existir uma conta com esse URI, o módulo falhará.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| acme\_directory - required | string   |                                           | O diretório ACME a ser usado. Esta é a URL do ponto de entrada para acessar a API do servidor ACME CA.<br /><br />Por motivos de segurança, o padrão é definido para o servidor de teste Let's Encrypt (para o protocolo ACME v1). Isso criará certificados tecnicamente corretos, mas não confiáveis.                                                                                                                                                                                                                                                                                                                                                                                                                        |
| acme\_version - required   | integer  | - 1
- 2&#xA;                              | A versão ACME do endpoint.<br /><br />Deve ser 1 para os endpoints ACME clássicos Let's Encrypt e Buypass ou 2 para endpoints ACME v2 padronizados.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| retrieve\_orders           |          | * ***ignore***
* url\_list
* object\_list | Whether to retrieve the list of order URLs or order objects, if provided by the ACME server.A value of ignore will not fetch the list of orders.If the value is not ignore and the ACME server supports orders, the order\_uris return value is always populated. The orders return value is only returned if this option is set to object\_list.Currently, Let's Encrypt does not return orders, so the orders result will always be empty.                                                                                                                                                                                                                                                                                  |
| select\_crypto\_backend    |          | - ***auto***
- cryptography
- openssl     | Determines which crypto backend to use.The default choice is auto, which tries to use cryptography if available, and falls back to openssl.If set to openssl, will try to use the openssl binary.If set to cryptography, will try to use the cryptography library.                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| validate\_certs            | boolean  | * no
* ***yes***                          | Se as chamadas para o diretório ACME validarão certificados TLS.<br /><br />Aviso: Deve ser configurado apenas `false` para fins de teste, por exemplo, ao testar em um servidor Pebble local.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |

## Notas

- O módulo crypto.acme\_account permite modificar, criar e deletar contas ACME.
- Se uma nova versão da livraria de cryptogradia está disponível, será usada em vez do openssl binary. Isso pode estar explicitamente desbilitado ou abilitado com a opção select\_crypto\_backend. Note que usando o openssl binary será mais lento e menos seguro, como os conteúdos da private key sempre tem que ser estocado no disco (veja account\_key\_content).
- Mesmo que os padrões sejam escolhidos para que o módulo possa ser usado com o Let’s Encrypt CA, o módulo pode em princípio ser usado com qualquer CA provendo um endpoint ACME, como um Buypass Go SSL.

## Exemplos

```yaml
- name: Check whether an account with the given account key exists
  community.crypto.acme_account_info:
    account_key_src: /etc/pki/cert/private/account.key
    register: account_data
- name: Verify that account exists
  assert:
    that:
      - account_data.exists
- name: Print account URI
  builtindebug:
    var: account_data.account_uri
- name: Print account contacts
  debug:
    var: account_data.account.contact

- name: Check whether the account exists and is accessible with the given account key
  acme_account_info:
    account_key_content: "{{ acme_account_key }}"
    account_uri: "{{ acme_account_uri }}"
    register: account_data
- name: Verify that account exists
  assert:
    that:
      - account_data.exists
- name: Print account contacts
  debug:
    var: account_data.account.contact
```

## Valores de retorno

| **Chave**    | **Tipe**                   | **&#x20;Retornado quando**                                                                        | **Descrição**                                                                                                                                                      |
| ------------ | -------------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| account      | dict                       | Se a conta existir<br />                                                                          | Informação da conta, recuperada do ACME server.                                                                                                                    |
| account\_uri | string                     | sempre                                                                                            | Conta URI ACME, ou None se a conta não existir.                                                                                                                    |
| exists       | bool                       | sempre                                                                                            | Se a conta existir ou não.                                                                                                                                         |
| order\_uris  | list / elements=string     | Se a conta existir, *retrieve\_orders&#x20;*&#x6E;ão será ignore, e server supports order listing | Lista de ordens.<br />Se `RETRIVE_ORDERS` é uma `URL_LIST`, será uma lista de URLs.<br />Se `RETRIVE_ORDERS` é uma `OBJECT_LIST`, será uma lista de objetos.<br /> |
| orders       | list / elements=dictionary | Se a conta existir, *retrieve\_orders&#x20;*&#x6E;ão será ignore, e server supports order listing | Lista de ordens.<br />                                                                                                                                             |

## Subcampos da opção account

| **Chave**             | **Tipe**               | **&#x20;Retornado quando** | **Descrição**                                                                                                                                            |
| --------------------- | ---------------------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| contact               | list / elements=string | sempre                     | O recurso challenge que deve ser criado para validação.                                                                                                  |
| orders                | string                 | sempre                     | Um URL onde a llista de ordens pode ser recuperada para essa conta. Use a opção `RETRIVE_ORDERS` para o query URL a recupara a lista completa de ordens. |
| public\_account\_key  | string                 | sempre                     | A chave da conta pública como JSON Web Key.                                                                                                              |
| status                | string                 | sempre                     | O status da conta.<br />                                                                                                                                 |

## Subcampos da opção orders

| **Chave**      | **Tipe**                               | **&#x20;Retornado quando**                                                                  | **Descrição**                                                                                                                                                               |
| -------------- | -------------------------------------- | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| authorizations | list / elements=string<br />           | success                                                                                     | Lista de URLs por autorizações por essa ordem.                                                                                                                              |
| certificate    | string                                 | Quando o certificado foi emitido<br />                                                      | A URL para recuperar o certificado.                                                                                                                                         |
| error          | dict                                   | Quando ocorreu um erro<br />                                                                | No caso de um erro ocorrido durante o processo, este conterá informações sobre o erro. O campo é estruturado como documento problema (RFC7807).                             |
| expires        | string                                 | Quando o server dá a data de validade<br />                                                 | Quando a ordem exipra. Timestamp tem que ser formatado como descrito em RFC3339. Somente requerido para ser incluso no resultado quando o status está pendente ou é valido. |
| finalize       | string                                 | success                                                                                     | Uma URL usada para finalizar uma ordem ACME.                                                                                                                                |
| identifiers    | list / elements=dictionary<br /><br /> | Se a conta existe, retrieve\_orders é object\_list e o server suporta listamento de ordens. | Lista de identifiers do que essa ordem é.<br />                                                                                                                             |
| notAfter       | string                                 | Quando o server retorna isso                                                                | O valor requerido do campo `notAFTER`no certificado. Data tem que ser formatada como descrita em RFC3339. O server não requere o retorno deste.                             |
| notBefore      | string                                 | Quando o server retorna isso                                                                | O valor requerido do campo `notBEFORE`no certificado. Data tem que ser formatada como descrita em RFC3339. O server não requere o retorno deste.                            |
| status         | string                                 | success                                                                                     | O status da ordem.                                                                                                                                                          |

## Subcampos da opção identifiers

| **Chave** | **Tipe** | **&#x20;Retornado quando**                               | **Descrição**                                                                                             |
| --------- | -------- | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| type      | string   | success                                                  | Tipo de identifier. `DNS` ou `IP`.                                                                        |
| value     | string   | success                                                  | Nome do identifier. Hostname ou IP address.                                                               |
| wildcard  | bool     | Requerido para ser incluso se o identifier é wildcarded. | *Value* é ou não uma wildcard. O prefixo wildcard  `*.` não é incluso no *value &#x20;*&#x73;e for `TRUE` |


[title] Visualizar a porta da API do clustet Kubernetes
[path] Documentação Técnica/Observabilidade Kubernetes/

# Visualizar a porta da API do Cluster Kubernetes

### 1. Comando para Exibir a Configuração

[https://docs.simonops.com/visualizar-a-porta-da-api-do-cluster-kubernetes#SqAZz](https://docs.simonops.com/visualizar-a-porta-da-api-do-cluster-kubernetes#SqAZz)

Para visualizar a configuração atual do cluster, use o seguinte comando:

### 2. Exemplo de Saída

[https://docs.simonops.com/visualizar-a-porta-da-api-do-cluster-kubernetes#J2fvA](https://docs.simonops.com/visualizar-a-porta-da-api-do-cluster-kubernetes#J2fvA)

A saída do comando kubectl config view será semelhante ao exemplo abaixo:

```javascript
apiVersion: v1
clusters:
- cluster:
    insecure-skip-tls-verify: true
    server: https://127.0.0.1:16443
  name: kubernetes-cluster
contexts:
- context:
    cluster: kubernetes-cluster
    user: admin
  name: kubernetes
current-context: kubernetes
kind: Config
preferences: {}
users:
- name: admin
  user:
    client-certificate-data: DATA+OMITTED
    client-key-data: DATA+OMITTED
```

Nesse caso a porta do servidor API Kubernetes é **16443**, assim, as integrações que requerem a informação usa-se o formato:

:::CodeblockTabs
Exemplo

```javascript
https://<ip_do_no_principal>:16443
```
:::


[title] Conta Acme
[path] Documentação Técnica/Automações/Criptomoeda/

# Conta Acme

## Resumo

[https://docs.simonops.com/homologacao-atmosphere/acme-account#U6-nH](https://docs.simonops.com/homologacao-atmosphere/acme-account#U6-nH)

- Permite criar, modificar ou excluir contas com uma CA que suporta o &#x20;
- Este módulo só funciona com o protocolo ACME v2.

## Parâmetros

[https://docs.simonops.com/homologacao-atmosphere/acme-account#UYMgJ](https://docs.simonops.com/homologacao-atmosphere/acme-account#UYMgJ)

| **Parâmetro**                        | **Tipo**                 | **Escolhas \| Valores padrão**                                    | **Comentários**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ------------------------------------ | ------------------------ | ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| conteúdo\_chave\_da\_conta           | corda                    | <br />                                                           | Conteúdo da chave RSA ou curva elíptica da conta ACME. Mutuamente exclusivo com  account\_key\_src .<br /><br />É necessário que  account\_key\_src não seja usado.<br /><br />Atenção: o conteúdo será gravado em um arquivo temporariamente, que será excluído pelo Atmosphere quando o módulo for concluído. Como essa é uma chave privada importante — ela pode ser usada para alterar a chave de conta ou revogar seus certificados sem conhecer suas chaves privadas —, isso pode não ser aceitável.<br /><br />Caso  a criptografia seja usada, o conteúdo não é gravado em um arquivo temporário. Ainda pode acontecer que ele seja gravado em disco pelo Ansible no processo de mover o módulo com seu argumento para o nó onde ele é executado. |
| senha\_chave\_da\_conta              | corda                    | <br />                                                           | Phassphrase é usado para decodificar a chave da conta.<br /><br />Nota: isso não é suportado pelo back-openssl , apenas pelo back-cryptography .                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| account\_key\_src                    | caminho                  | <br />                                                           | Caminho para um arquivo que contém a chave RSA ou curva elíptica da conta ACME.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| conta\_uri                           | corda                    | <br />                                                           | Se especificado, assuma que o URI da conta é o informado. Se a chave da conta não corresponder a essa conta ou não existir uma conta com esse URI, o módulo falhará.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| acme\_directory - obrigatório        | corda                    | <br />                                                           | O diretório ACME foi usado. Esta é a URL do ponto de entrada para acessar a API do servidor ACME CA.<br /><br /><br />Por motivos de segurança, o padrão é definido para o servidor de teste Let's Encrypt (para o protocolo ACME v1). Isso criará certificados técnicos corretos, mas não confiáveis.                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| acme\_version - obrigatório          | inteiro                  | Escolhas:<br />- 1<br />- 2                                       | A versão ACME do endpoint.<br /><br /><br />Deve ser 1 para os endpoints ACME clássicos Let's Encrypt e Buypass ou 2 para endpoints ACME v2 padronizados.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| permitir\_criação                    | boleano                  | Escolhas:<br />- verdadeiro (padrão)<br />- falso                 | Se a criação de conta é permitida (quando o estado estiver  presente ).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| contato                              | lista / elementos=string | Padrão:<br />\[]                                                  | Uma lista de URLs de contato.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| vinculação\_de\_conta\_externa       | dicionário               | <br />                                                           | Permite fornecer dados de vinculação de contas externas durante a criação da conta.<br /><br />Isso é usado por CAs como o Sectigo para vincular uma nova conta ACME a uma conta específica de CA existente, para poder identificar especificamente um cliente.<br /><br />Usado apenas ao criar uma nova conta. Não pode ser especificado para ACME v1.                                                                                                                                                                                                                                                                                                                                                                                                  |
| novo\_conteúdo\_da\_chave\_da\_conta | corda                    | <br />                                                           | Conteúdo da chave RSA ou curva elíptica da conta ACME para alteração.<br /><br />As mesmas restrições se aplicam a account\_key\_content.<br /><br />Mutuamente exclusivo com  new\_account\_key\_src .<br /><br />Obrigatório se  new\_account\_key\_src não for usado e o estado for change\_key.                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| nova\_senha\_da\_chave\_da\_conta    | corda                    | <br />                                                           | Phassphrase é usado para decodificar uma nova chave de conta.<br /><br />Nota: isso não é suportado pelo back-openssl, apenas pelo back-cryptography.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| nova\_chave\_de\_conta\_origem       | caminho                  | <br />                                                           | Caminho para um arquivo que contém a chave RSA ou curva elíptica da conta ACME para qual alteração.<br /><br />As mesmas restrições se aplicam a  account\_key\_src .<br /><br />Mutuamente exclusivo com new\_account\_key\_content .<br /><br />Obrigatório se new\_account\_key\_cont não for usado e o estado for  change\_key .                                                                                                                                                                                                                                                                                                                                                                                                                      |
| selecionar\_cripto\_backend          | corda                    | Escolhas:<br />- auto(padrão)<br />- criptografia<br />- abre ssl | Determina qual back-end de criptografia usar.<br /><br />A opção padrão é  auto , que tenta usar  criptografia disponível e retorna para openssl.<br /><br />Se definido como openssl, tentarei usar o  binário openssl .<br /><br />Se definido como criptografia, tentará usar uma biblioteca de criptografia.                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| estado - obrigatório                 | corda                    | Escolhas:<br />- presente<br />- ausente<br />- chave\_alterada   | O estado da conta é identificado por sua chave de conta.<br /><br />Se o estado estiver  ausente , a conta não existirá ou será desativada.<br /><br />Se o estado for  change\_key , a conta deverá existir. A chave da conta será alterada; nenhuma outra informação será tocada.                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| termos\_acordados                    | boleano                  | Escolhas:<br />- verdadeiro<br />- falso (padrão)                 | Booleano diminuir se você concorda com o documento de termos de serviço.<br /><br />Os servidores ACME podem exigir que isso seja verdade.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| validar\_certificados                | boleano                  | Escolhas:<br />- verdadeiro (padrão)<br />- falso                 | Se as chamadas para o diretório ACME validarem certificados TLS.<br /><br />Aviso: Deve ser configurado apenas false  para fins de teste, por exemplo, ao testar em um servidor Pebble local.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |




### Subcampos da opção external\_account\_binding

[https://docs.simonops.com/homologacao-atmosphere/acme-account#UTe\_Q](https://docs.simonops.com/homologacao-atmosphere/acme-account#UTe_Q)

| **Parâmetro**         | **Tipo** | **Escolhas \| Valor Padrão**                     | **Comentários**                                                                                                             |
| --------------------- | -------- | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------- |
| alg - obrigatório     | corda    | escolhas:<br />- HS256<br />- HS384<br />- HS512 | O algoritmo MAC fornecido pela CA.<br />Se não for especificado pela CA, provavelmente é HS256 .                            |
| chave - necessária    | corda    | <br />                                          | Valor codificado de URL Base64 da chave MAC fornecida pela CA.<br />O preenchimento (= símbolos no final) pode ser omitido. |
| criança - obrigatório | corda    | <br />                                          | O identificador de chave fornecido pela CA.                                                                                 |

## Exemplos

[https://docs.simonops.com/homologacao-atmosphere/acme-account#S7W1t](https://docs.simonops.com/homologacao-atmosphere/acme-account#S7W1t)

## Valores de retorno

[https://docs.simonops.com/homologacao-atmosphere/acme-account#JJKqm](https://docs.simonops.com/homologacao-atmosphere/acme-account#JJKqm)

| **Chave**  | **Tipo** | **Retornado quando** | **Descrição**                                             |
| ---------- | -------- | -------------------- | --------------------------------------------------------- |
| conta\_uri | corda    | sempre               | URI da conta ACME ou Nenhum se a conta não existir.<br /> |


[title] SSH Command
[path] Documentação Técnica/Automações/Comandos/

## Resumo

- Execute comandos em um Client SSH.

| **Parâmetro**                               | **Tipo**               | **Escolhas \| Valor Padrão**       | **Comentários**                                                                       |
| ------------------------------------------- | ---------------------- | ---------------------------------- | ------------------------------------------------------------------------------------- |
| username                                    | string                 |                                    | Usuário padrão para fazer o login/autenticação.                                       |
| password                                    | string                 |                                    | Senha padrão usada para fazer login no servidor ssh.                                  |
| hosts - *required*<br />(Possíveis valores) | list / elements=dict   |                                    | Lista de nomes de host e/ou IPs. Pode conter um nome de usuário e uma chave de senha. |
| port                                        | int                    | - 22 (default)                     | Porta SSH.                                                                            |
| commands - *required          &#x20;*       | list / elements=string |                                    | Lista de comandos.                                                                    |
| private\_key\_file                          | string                 |                                    | Caminho para um arquivo de chave privada.                                             |
| private\_key\_string                        | string                 |                                    | Chave privada em formato de string.                                                   |
| auth\_timeout                               | integer                | - 10<br />(default)                | Tempo limite (em segundos) para aguardar uma resposta de autenticação.                |
| timeout                                     | integer                | - 60<br />(default)                | Tempo limite (em segundos) para aguardar a conexão TCP.                               |
| stderr\_lines                               | boolean                | Escolhas:<br />- false<br />- true | Mostra ou oculta o comando stderr.                                                    |
| stdout\_lines                               | boolean                | Escolhas:<br />- false<br />- true | Mostra ou esconde o comando stdout.                                                   |

## Subcampos da opção hosts

| **Parâmetro**        | **Tipo** | **Escolhas \| Valor Padrão** | **Comentários**                               |
| -------------------- | -------- | ---------------------------- | --------------------------------------------- |
| address              | string   |                              | Um endereço e/ou IP.                          |
| username             | string   |                              | Usuário para fazer o login/autenticação.      |
| password             | string   |                              | Senha usada para fazer login no servidor ssh. |
| private\_key\_file   | string   |                              | Caminho para um arquivo de chave privada.     |
| private\_key\_string | string   |                              | Chave privada em formato de string.           |

## Exemplos

```yaml
# Exemplo: Execute o comando via SSH e retorne a saída padrão e o erro.
- ssh_command:
    username: "root"
    password: "root"
    hosts: [{"address": "localhost"}]
    commands: ["echo $USER"]
    stderr_lines: true
    stdout_lines: true

# Exemplo: Execute o comando via SSH em uma porta custom.
- ssh_command:
    username: "root"
    password: "root"
    hosts: [{"address": "localhost"}]
    commands: ["echo $USER"]
    stderr_lines: true
    stdout_lines: true
    port: 23
```

## Valores retornados

| **Chave** | **Tipo**               | **Retornado quando** | **Descrição**      |
| --------- | ---------------------- | -------------------- | ------------------ |
| failed    | boolean                | sempre               | status da execução |
| reason    | string                 | sempre               | timeout            |
| address   | string                 | sempre               | O endereço ou IP.  |
| commands  | list / elements=string | sempre               | Lista de comandos  |


[title] AIOPS - Documentação Técnica
[path] /


[title] Automações
[path] Documentação Técnica/


[title] Chave privada OpenSSL
[path] Documentação Técnica/Automações/Criptomoeda/

## Sinopse

- As chaves são geradas no formato PEM.
- Pode-se gerar chaves privadas RSA , DSA , ECC ou EdDSA .
- Este módulo permite (re) gerar chaves privadas OpenSSL.

## Parâmetros

| **Parâmetro**           | **Tipo** | **Escolhas \| Valor Padrão** | **Comentários**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ----------------------- | -------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| attributes              | string   |                              | Os atributos que o arquivo ou diretório resultante deve ter.Para obter os sinalizadores suportados, consulte a página do manual do *chattr* no sistema de destino.Essa string deve conter os atributos na mesma ordem que aquela exibida por *lsattr* .O =operador é assumido como padrão, caso contrário, +ou os -operadores precisam ser incluídos na string.<br />aliases: attr                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| backup                  | boolean  |                              | Crie um arquivo de backup incluindo um carimbo de data / hora para que você possa obter a chave privada original de volta caso a substitua por uma nova por acidente.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| cipher                  | string   |                              | A cifra para criptografar a chave privada. (Os valores válidos podem ser encontrados executando \`openssl list -cipher-algoritmos\` ou\` openssl list-cipher-algoritmos\`, dependendo da sua versão OpenSSL.)Ao usar o cryptographyback - end, use auto.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| curve                   | string   |                              | Observe que nem todas as curvas são suportadas por todas as versões do cryptography.Para máxima interoperabilidade, secp384r1ou secp256r1deve ser usado.Usamos os nomes das curvas conforme definido no registro IANA para TLS .Por favor note que todas as curvas, exceto secp224r1, secp256k1, secp256r1, secp384r1e secp521r1são desencorajados de novas chaves privadas.                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| force                   | boolean  |                              | A chave deve ser regenerada mesmo se já existir.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| format                  | string   |                              | Determina em qual formato a chave privada é gravada. Por padrão, PKCS1 (formato OpenSSL tradicional) é usado para todas as chaves que o suportam. Observe que nem todas as chaves podem ser exportadas em qualquer formato.O valor autoseleciona uma fromat com base no formato da chave. O valor auto\_ignorefaz o mesmo, mas para arquivos de chave privada existentes, ele não forçará uma regeneração quando seu formato não for o selecionado automaticamente para geração.Observe que, se o formato de uma chave privada existente não corresponder, a chave será gerada novamente por padrão. Para alterar esse comportamento, use a opção *format\_mismatch* .A opção de *formato* só é compatível com o cryptographyback - end. O pyopensslback-end falhará se um valor diferente de auto\_ignorefor usado. |
| format\_mismatch <br /> | string   |                              | Determina o comportamento do módulo se o formato de uma chave privada não corresponde ao formato esperado, mas todos os outros parâmetros são os esperados.Se definido como regenerate(padrão), gera uma nova chave privada.Se definido como convert, a chave será convertida para o novo formato.Suportado apenas pelo cryptographyback - end.                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| group                   | string   |                              | Nome do grupo que deve possuir o arquivo / diretório, como seria alimentado para *chown* .                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| mode                    | raw      |                              | As permissões que o arquivo ou diretório resultante deve ter.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| owner                   | string   |                              | Nome do usuário que deve possuir o arquivo / diretório, como seria alimentado para *chown* .                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| passphrase              | string   |                              | A frase secreta da chave privada.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| path                    | path     |                              | Nome do arquivo no qual a chave privada TLS / SSL gerada será gravada. Ele terá 0600modo se o *modo* não estiver explicitamente definido.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| regenerate              | string   |                              | Permite configurar em quais situações o módulo pode regenerar chaves privadas. O módulo sempre gerará uma nova chave se o arquivo de destino não existir.Por padrão, a chave será regenerada quando não corresponder às opções do módulo, exceto quando a chave não puder ser lida ou a frase-senha não corresponder.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| return\_content         | boolean  |                              | Se for definido como yes, irá retornar o conteúdo da chave privada (atual ou gerado) como *privatekey* .Observe que, especialmente se a chave privada não estiver criptografada, você deve certificar-se de que o valor retornado seja tratado apropriadamente e não acidentalmente gravado em logs, etc.!                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| select\_crypto\_backend | string   |                              | Determina qual back-end criptográfico usar.A escolha padrão é auto, que tenta usar, cryptographyse disponível, e retorna a pyopenssl.Se definido como pyopenssl, tentará usar a biblioteca pyOpenSSL .Se definido como cryptography, tentará usar a biblioteca de criptografia.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| selevel                 | string   |                              | A parte do nível do contexto do arquivo SELinux.Este é o atributo MLS / MCS, também conhecido como range.Quando definido como \_default, ele usará a levelparte da política, se disponível.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| serole                  | string   |                              | A parte da função do contexto do arquivo SELinux.Quando definido como \_default, ele usará a roleparte da política, se disponível.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| setype                  | string   |                              | A parte do tipo do contexto do arquivo SELinux.Quando definido como \_default, ele usará a typeparte da política, se disponível.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| seuser                  | string   |                              | A parte do usuário do contexto do arquivo SELinux.Por padrão, ele usa a systempolítica, quando aplicável.Quando definido como \_default, ele usará a userparte da política, se disponível.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| size                    | integer  | Padrão:<br />4096            | Tamanho (em bits) da chave TLS / SSL a ser gerada.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| state                   | string   |                              | Se a chave privada deve existir ou não, agir se o estado for diferente do que é declarado.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| type <br />             | string   |                              | O algoritmo usado para gerar a chave privada TLS / SSL.Note-se que ECC, X25519, X448, Ed25519e Ed448exigem que o cryptographybackend. X25519precisa de criptografia 2.5 ou mais recente, enquanto X448, Ed25519e Ed448requer criptografia 2.6 ou mais recente. Pois ECC, a versão de criptografia mínima necessária depende da opção de *curva* .                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| unsafe\_writes          | boolean  |                              | Influencie quando usar a operação atômica para evitar corrupção de dados ou leituras inconsistentes do arquivo de destino.<br /><br />Por padrão, este módulo usa operações atômicas para evitar corrupção de dados ou leituras inconsistentes dos arquivos de destino, mas às vezes os sistemas são configurados ou apenas interrompidos de maneiras que evitam isso. <br /><br />Um exemplo são os arquivos montados no docker, que não podem ser atualizados atomicamente de dentro do contêiner e só podem ser gravados de maneira insegura.                                                                                                                                                                                                                                                                     |

## Exemplos

```javascript
- name: Generate an OpenSSL private key with the default values (4096 bits, RSA)
  openssl_privatekey:
    path: /etc/ssl/private/atmosphere.com.pem

- name: Generate an OpenSSL private key with the default values (4096 bits, RSA) and a passphrase
  openssl_privatekey:
    path: /etc/ssl/private/atmosphere.com.pem
    passphrase: atmosphere
    cipher: aes256

- name: Generate an OpenSSL private key with a different size (2048 bits)
  openssl_privatekey:
    path: /etc/ssl/private/atmosphere.com.pem
    size: 2048

- name: Force regenerate an OpenSSL private key if it already exists
  openssl_privatekey:
    path: /etc/ssl/private/atmosphere.com.pem
    force: yes

- name: Generate an OpenSSL private key with a different algorithm (DSA)
  openssl_privatekey:
    path: /etc/ssl/private/atmosphere.com.pem
    type: DSA
```

## Notas

- Se você está preocupado com a possibilidade de **sobrescrever sua chave privada** , considere o uso da opção de *backup* .
- Observe que o módulo regenera as chaves privadas se elas não corresponderem às opções do módulo. Em particular, se você fornecer outra senha (ou não especificar nenhuma), alterar o tamanho da chave, etc., a chave privada será regenerada. 

## Valores Retornados

Os valores de retorno comuns são documentados aqui . A seguir estão os campos exclusivos deste módulo:

| ChaveRetornouDescrição                                         |                                                     |                                                                                                                                |
| -------------------------------------------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| arquivo de backup fragmento                                    | mudou e se o *backup* éyes                          | Nome do arquivo de backup criado.                                                                                              |
| curva fragmento                                                | mudou ou sucesso, e o *tipo* éECC                   | Curva elíptica usada para gerar a chave privada TLS / SSL.                                                                     |
| nome do arquivo fragmento                                      | mudou ou sucesso                                    | Caminho para o arquivo de chave privada TLS / SSL gerado.                                                                      |
| impressão digital dicionário                                   | mudou ou sucesso                                    | A impressão digital da chave pública.                                                                                          |
| chave privada fragmentoadicionado em 1.0.0 de community.crypto | se o *estado* for presente *return\_content* foryes | O conteúdo da chave privada (atual ou gerada).<br /><br />Será codificado em Base64 se a chave estiver no formato bruto.<br /> |
| Tamanho inteiro                                                | mudou ou sucesso                                    | Tamanho (em bits) da chave privada TLS / SSL.                                                                                  |
| tipo fragmento                                                 | mudou ou sucesso                                    | Algoritmo usado para gerar a chave privada TLS / SSL.                                                                          |




[title] Criar API TOKEN
[path] Documentação Técnica/Observabilidade Kubernetes/

## Introdução

Esta documentação descreve o processo para criar um token de API não expirável e persistente para uma ServiceAccount no Kubernetes, utilizando um Secret do tipo kubernetes.io/service-account-token. Esse método é útil quando o mecanismo de solicitação de token não é adequado, fornecendo tokens de longa duração.

:::hint{type="info"}
Crie tokens de API de longa duração apenas se o mecanismo de solicitação de token não for adequado. O mecanismo de solicitação de token fornece tokens com tempo limitado; devido à sua expiração, representam um risco menor à segurança da informação.
:::

## Passos para Criar um Token de API Persistente

### 1. Criação de um Secret

Para criar um token de API não expirável para uma ServiceAccount, crie um Secret do tipo kubernetes.io/service-account-token com uma anotação referenciando a ServiceAccount. O plano de controle gerará um token de longa duração e atualizará o Secret com os dados do token gerado.

### 2. Manifesto de Exemplo

*Altere os campos&#x20;****my-serviceaccount****&#x20;e&#x20;****my-namespace&#x20;****para os valores de sua preferência.*

**Service Account:**

:::CodeblockTabs
YAML

```javascript
apiVersion: v1
kind: ServiceAccount
metadata:
  name: my-serviceaccount
  namespace: my-namespace
```
:::

**Secret:**

:::CodeblockTabs
YAML

```javascript
apiVersion: v1
kind: Secret
type: kubernetes.io/service-account-token
metadata:
  name: my-secretname
  namespace: my-namespace
  annotations:
    kubernetes.io/service-account.name: my-serviceaccount
```
:::

### 3. Crie um ClusterRole e um ClusterRoleBinding com permissões de READ para o Cluster:

**ClusterRole**:

Regra para somente ler o cluster (get)

:::CodeblockTabs
YAML

```javascript
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  annotations:
    rbac.authorization.kubernetes.io/autoupdate: "true"
  labels:
    kubernetes.io/bootstrapping: rbac-defaults
  name: read-cluster-admin
rules:
  - apiGroups:
      - "*"
    resources:
      - "*"
    verbs:
      - "*"
  - nonResourceURLs:
      - "*"
    verbs: ["get"]
```
:::

**ClusterRoleBinding:**

O ClusterRoleBinding dá as regras criadas no ClusterRole para a ServiceAccount (my-serviceaccount) criada anteriomente.

:::CodeblockTabs
YAML

```javascript
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: my-clusterrolebinding
subjects:
- kind: ServiceAccount
  name: my-serviceaccount
  namespace: my-namespace
roleRef:
  kind: ClusterRole
  name: read-cluster-admin
  apiGroup: rbac.authorization.k8s.io
```
:::

E então o secret usado por essa ServiceAccount pode ser usado somente para ler o Cluster, como indicado em "**verbs: \["get"]**"

### 4. Verificação dos Detalhes do Secret

Para ver os detalhes do Secret criado, execute:

:::CodeblockTabs
COMMAND

```javascript
kubectl -n my-namespace describe secret my-secretname
```
:::

### 5. Exemplo de Saída

A saída será semelhante a:

```javascript
Namespace:      my-namespace
Labels:         <none>
Annotations:    kubernetes.io/service-account.name=my-serviceaccount
                kubernetes.io/service-account.uid=8a85c4c4-8483-11e9-bc42-526af7764f64

Type:   kubernetes.io/service-account-token

Data
====
ca.crt:         1362 bytes
namespace:      9 bytes
token:          <TOKEN_GERADO>
```

### 6. Rode o seguinte comando mostrar o Token Gerado:

:::CodeblockTabs
EXEMPLO

```javascript
kubectl get secret my-secretname -n my-namespace -o jsonpath='{.data.token}' | base64 --decode
```
:::

### 7. Rode o seguinte comando para validar o Token:

```javascript
curl -H "Authorization: Bearer <TOKEN>" -k https://<kubernetes-api-server>/api/v1/nodes

```


[title] Habilitando o WinRM para PSRP (PowerShell Remoting Protocol)
[path] Documentação Técnica/Automações/Comandos/Comando Powershell/

Normalmente, as builds de Windows Server costumam habilitar por padrão o WinRM, para verificar, basta rodar o comando abaixo no PowerShell ou CMD:

WinRM quickconfig

### Configuração automática

Rode o seguinte script *Powershell&#x20;*&#x63;omo administrador.

::File{src="https://archbee-doc-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/D-8Vxckof9mP0CZlh4HXU_enable-psrp.ps1" label="enable_psrp.ps1"}

Este script verifica a configuração atual do WinRM (PS Remoting) e faz as alterações necessárias para permitir que o Atmosphere se conecte, autentique e execute comandos do PowerShell.

*\*Todos os eventos são registrados no Windows EventLog.*

:::CodeblockTabs
INL

```javascript
Use a opção -Verbose para ver as mensagens de output de forma detalhada.

Use a opção -CertValidityDays para especificar por quanto tempo este certificado 
é válido a partir de hoje. 
Exemplo: Então você especificaria -CertValidityDays 3650 para obter um certificado 
válido por 10 anos.

Use a opção -ForceNewSSLCert se o sistema utiliza SysPreped e um novo certificado SSL deve 
ser forçado no WinRM Listener ao reexecutar este script. Isso é necessário quando um 
novo nome de SID e CN é criado.

Use a opção -EnableCredSSP para habilitar o CredSSP como uma opção de autenticação.

Use a opção -DisableBasicAuth para desabilitar a autenticação básica.

Use a opção -SkipNetworkProfileCheck para pular a verificação do perfil de rede.
Sem especificar essa opção, o script só será executado se as interfaces do dispositivo
estiverem em zonas DOMAIN ou PRIVATE. Forneça esta opção se desejar habilitar
WinRM em um dispositivo com interface na zona PÚBLICA.

Use a opção -SubjectName para especificar o nome CN do certificado. Padroniza o 
nome do host do sistema e geralmente não deve ser especificado.
```
:::

### Confuguração Manual

A fim de rodar o módulo PowerShell Command, deve-se habilitar o **PSRemoting** **e o** **WinRM** no sistema com os comandos abaixo.

:::CodeblockTabs
WinRM

```javascript
WinRM quickconfig
```
:::

:::CodeblockTabs
PSRemoting

```javascript
Set-NetConnectionProfile -NetworkCategory Private
Enable-PSRemoting
```
:::

Logo após, deve-se liberar a comunicação para uma das respectivas porta no firewall:

- 5985 para conexões não seguras (ssl = False)
- 5986 para conexões seguras (ssl = True)


[title] Chave pública OpenSSL
[path] Documentação Técnica/Automações/Criptomoeda/

## Resumo

- Gere uma chave pública OpenSSL a partir de sua chave privada.

## Parâmetros

| **Parâmetro**            | **Tipo** | **Escolhas \| Valor Padrão**                                              | **Comentários**                                                                                                                                                                                                                                                                         |
| ------------------------ | -------- | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| backup                   | boolean  | Escolhas:<br />- false<br />(default)<br />- true                         | Crie um arquivo de backup incluindo data/hora para que você possa obter a chave pública original de volta caso a substitua por uma diferente por acidente.                                                                                                                              |
| force                    | boolean  | Escolhas:<br />- false<br />(default)<br />- true                         | Se a chave deve ser reescrita mesmo se já existir.                                                                                                                                                                                                                                      |
| format                   | string   | Escolhas:<br />- OpenSSH<br />- PEM<br />(default)                        | O formato da chave pública.                                                                                                                                                                                                                                                             |
| path - *required*        | path     |                                                                           | Nome do arquivo no qual a chave pública TLS / SSL gerada será gravada.                                                                                                                                                                                                                  |
| privatekey\_passphrase   | string   |                                                                           | A frase secreta da chave privada.                                                                                                                                                                                                                                                       |
| privatekey\_path         | path     |                                                                           | Caminho para a chave privada TLS / SSL a partir da qual gerar a chave pública. É necessário especificar privatekey\_path ou privatekey\_content, mas não ambos. Se o state estiver present, um deles será necessário.                                                                   |
| select\_crypto\_backend  | string   | Escolhas:<br />- auto<br />(default)<br />- cryptography<br />- pyopenssl | Determina qual back-end de criptografia usar. A escolha padrão é auto, que tenta usar criptografia, se disponível, e retorna para pyopenssl. Se definido como pyopenssl, tentará usar a biblioteca pyOpenSSL. Se definido como cryptography, tentará usar o biblioteca de criptografia. |
| state                    | string   | Escolhas:<br />- present<br />(default)<br />- absent                     | Se a chave pública deve existir ou não, agir se o state for diferente do que é declarado.                                                                                                                                                                                               |

## Observações

- Para que você aproveite o máximo desse módulo, é necessário que o mesmo esteja funcionando em uma máquina remota ou host, que contenha os arquivos solicitados pelos parâmetros.

## Exemplos

```yaml
# Exemplo: Gere uma chave pública OpenSSL no formato PEM
- openssl_publickey:
    path: /etc/ssl/public/example.com.pem
    privatekey_path: /etc/ssl/private/example.com.pem

# Exemplo: Gere uma chave pública OpenSSL no formato OpenSSH v2
- openssl_publickey:
    path: /etc/ssl/public/example.com.pem
    privatekey_path: /etc/ssl/private/example.com.pem
    format: OpenSSH

# Exemplo: Gere uma chave pública OpenSSL com uma chave privada protegida por senha
- openssl_publickey:
    path: /etc/ssl/public/example.com.pem
    privatekey_path: /etc/ssl/private/example.com.pem
    privatekey_passphrase: example

# Exemplo: Força a reescrita de uma chave pública OpenSSL se ela já existir
- openssl_publickey:
    path: /etc/ssl/public/example.com.pem
    privatekey_path: /etc/ssl/private/example.com.pem
    force: yes

# Exemplo: Remova uma chave pública OpenSSL
- openssl_publickey:
    path: /etc/ssl/public/example.com.pem
    privatekey_path: /etc/ssl/private/example.com.pem
    state: absent
```

## Valores retornados

| **Chave**     | **Tipo**   | **Retornado quando**                                | **Descrição**                                                                                                                                                   |
| ------------- | ---------- | --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| backup\_file  | string     | Sucesso e *backup* é "sim"                          | Nome do arquivo de backup criado.                                                                                                                               |
| filename      | string     | Sucesso                                             | Caminho para o arquivo de chave pública TLS / SSL gerado.                                                                                                       |
| fingerprint   | dictionary | Sucesso                                             | A impressão digital da chave pública. A impressão digital será gerada para cada hashlib.algorithms available.                                                   |
| format        | string     | Sucesso                                             | O formato da chave pública (PEM, OpenSSH, ...).                                                                                                                 |
| privatekey    | string     | Sucesso                                             | Caminho para a chave privada TLS / SSL a partir da qual a chave pública foi gerada. Será nenhum se a chave privada tiver sido fornecida em privatekey\_content. |
| publickey     | string     | Se o state for "present" e *return\_content* é sim. | O conteúdo da chave pública (atual ou gerada).                                                                                                                  |


[title] Certificado Acne
[path] Documentação Técnica/Automações/Criptomoeda/

# Certificado Acme

## Resumo

[https://docs.simonops.com/homologacao-atmosphere/acme-certificate#sgasj](https://docs.simonops.com/homologacao-atmosphere/acme-certificate#sgasj)

- Crie e renove certificados SSL/TLS com uma CA que suporta o protocolo ACME, como Let's Encrypt ou Buypass.
- A implementação atual suporta os desafios http-01, dns-01 e tls-alpn-01.
- Você deve cumprir as etapas ordinárias para o desafio escolhido por todos os meios necessários.
  - Para http-01, isso significa criar o arquivo de desafio necessário no servidor da Web de destino.
  - Para dns-01, o registro dns necessário deve ser criado.
  - Para tls-alpn-01, o certificado necessário deve ser criado e servido.
- O módulo inclui suporte experimental para identificadores de IP de acordo com o RFC 8738.

## Parâmetros

[https://docs.simonops.com/homologacao-atmosphere/acme-certificate#Kmud0](https://docs.simonops.com/homologacao-atmosphere/acme-certificate#Kmud0)

| **Parâmetro**                      | **Tipo** | **Escolhas \| Valor Padrão**                                           | **Comentários**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| ---------------------------------- | -------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| conta de e-mail                    | corda    | <br />                                                                | O endereço de e-mail associado a esta conta.<br /><br />Ele será usado para avisos de expiração de certificado.<br /><br />Observe que quando modificar\_account não está definido como ***não*** e você também usou o módulo ***acme\_account*** para especificar mais de um contato para sua conta, este módulo atualizará sua conta e restringirá ao (no máximo um) endereço de e-mail de contato especificado aqui.                                                                                                                                                                                                                                                                                                                                                                                                                       |
| acordo                             | corda    | <br />                                                                | URI para um documento de termos de serviço com o qual você concorda em usar o serviço ACME v1 em acme\_directory.<br /><br />O padrão é obtido por último a partir do URL acme\_directory.<br /><br />Esta opção só será usada quando acme\_version for 1.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| cadeia\_dest                       | corda    | <br />                                                                | Se especificado, o certificado intermediário será gravado neste arquivo.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| desafio                            | corda    | Escolhas:<br />- http-01 ( *Padrão* )<br />- dns-01<br />- tls-alpn-01 | Desafie a ser executado.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| RSE                                | corda    | <br />                                                                | Arquivo contendo o CSR para o novo certificado.<br /><br />O CSR pode conter vários nomes alternativos, mas cada um encaminhamento a um desafio individual que deve ser cumprido para que o CSR seja aprovado.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| conteúdo\_csr                      | corda    | <br />                                                                | Conteúdo do CSR para o novo certificado.<br /><br />O CSR pode conter vários nomes alternativos de assunto, mas cada um participa de um desafio individual que deve ser cumprido para que o CSR seja aprovado.<br /><br />Nota: uma chave privada usada para criar o CSR não deve ser uma chave de conta. Esta é uma má ideia do ponto de vista da segurança e a CA não deve aceitar o CSR. O servidor ACME deve retornar um erro neste caso.                                                                                                                                                                                                                                                                                                                                                                                                 |
| dados                              | ditado   | <br />                                                                | Os dados para validar os desafios em andamento.<br /><br />O valor que deve ser usado aqui será fornecido para uso anterior deste módulo.<br /><br /><br />Veja os exemplos para mais detalhes.<br />Observe que para ACME v2, apenas a entrada de dados order\_uri será usada. Para ACME v1, os dados não devem estar vazios para indicar que o segundo estágio está ativo; todos os dados necessários serão retirados do CSR.                                                                                                                                                                                                                                                                                                                                                                                                              |
| deactivate\_authzs                 | bool     | Escolhas:<br />- Falso ( *Padrão* )<br />- Verdadeiro                  | Desative os objetos de autenticação (authz) após emitir um certificado ou quando a emissão do certificado falhar.<br /><br />Os objetos de autenticação são garantidos a uma chave de conta e permanecem válidos por um determinado período de tempo, e podem ser usados ​​para emitir certificados sem a necessidade de reautenticar o domínio.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| destino                            | corda    | <br />                                                                | O arquivo de destino do certificado.<br /><br />Obrigatório se fullchain\_dest não for especificado.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| força                              | bool     | Escolhas:<br />- Falso (Padrão)<br />- Verdadeiro                      | Força a execução do desafio e validação, mesmo se um certificado existente ainda for válido por mais do valor especificado em *restantes\_dias* .<br /><br />Isso é especialmente útil para ter um CSR atualizado, por exemplo, com domínios adicionais para os quais um novo certificado é desejado.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| cadeia\_completa\_dest             | corda    | <br />                                                                | O arquivo de destino para a cadeia completa (ou seja, certificado seguido pela cadeia de certificados intermediários).<br /><br />Obrigatório não é especificado.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| modificar\_conta                   | bool     | Escolhas:<br />- Falso<br />- Verdade (Padrão)                         | Booleano que indica se o módulo deve criar a conta, se necessário, e atualizar seus dados de contato.<br /><br />Defina como ***não*** se deseja usar o módulo acme\_account para gerenciar sua conta e evitar a criação acidental de uma nova conta usando uma chave antiga se você alterar a chave da conta com acme\_account.<br /><br />Se definidos como ***no*** , *term\_agreed* e *account\_email* são ignorados.                                                                                                                                                                                                                                                                                                                                                                                                                     |
| dias restantes                     | inteiro  | *Padrão:* 10                                                           | O número de dias que o certificado deve ter deixado de ser válido.<br /><br /><br />Se dias\_certificados \< dias\_restantes , ele será renovado. Se o certificado não for renovado, os valores de retorno do módulo não incluirão challenge\_data.<br /><br />Para garantir que o certificado seja renovado em qualquer caso, você pode usar a opção forçar.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| recuperar\_todas\_as\_alternativas | bool     | Escolhas:<br />- Falso (Padrão)<br />- Verdadeiro                      | Quando definido como ***True*** , recuperará todas as cadeias de confiança alternativas oferecidas pela ACME CA.<br /><br /><br />Eles não serão gravados no disco, mas serão retornados junto com a cadeia principal como all\_chains. Consulte a documentação do valor de retorno all\_chains para obter detalhes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| selecionar\_cadeia                 | lista    | <br />                                                                | Permite especificar os critérios pelas quais uma cadeia de confiança (alternativa) pode ser selecionada.<br /><br />A lista de critérios será processada um a um até que seja encontrada uma cadeia que corresponda a um títulos. Se tal cadeia for encontrada, ela será usada pelo módulo em vez da cadeia padrão.<br /><br />Se um prêmio for atribuído a várias cadeias, a primeira correspondência será devolvida. A ordem é determinada pela ordem dos cabeçalhos do Link retornados pelo servidor ACME e pode não ser determinística.<br /><br />Cada sorteio pode consistir em várias condições diferentes, como emissor e assunto. Para que o classificação corresponda a uma cadeia, todas as condições deverão ser aplicadas ao mesmo certificado na cadeia.<br /><br />Esta opção só pode ser usada com o backend de criptografia. |
| selecionar\_cripto\_backend        | corda    | <br />                                                                | Determina qual back-end criptográfico usar.<br /><br />A escolha padrão é automática, que tenta usar criptografia, se disponível, e volta para o openssl.<br />Se definido como openssl, tentarei usar o binário openssl.<br />Se definido como criptografia, tentará usar uma biblioteca de criptografia.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| termos\_acordados                  | bool     | Escolhas:<br />- Falso (Padrão)<br />- Verdadeiro                      | Booleano que indica se você concorda com o documento de termos de serviço.<br /><br />Alguns servidores ACME podem exigir que a opção seja ***True*** .<br />Esta opção só será usada quando acme\_version não for 1.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |

### Subcampos da opção select\_chain

[https://docs.simonops.com/homologacao-atmosphere/acme-certificate#qnbT0](https://docs.simonops.com/homologacao-atmosphere/acme-certificate#qnbT0)

| **Parâmetro**                            | **Tipo**   | **Escolhas \| Valor Padrão**                                 | **Comentários**                                                                                                                                                                                                                                                                                                                                                                                                       |
| ---------------------------------------- | ---------- | ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| identificador\_de\_chave\_de\_autoridade | corda      | <br />                                                      | Verifique a extensão AuthorityKeyIdentifier. Este é um identificador baseado na chave privada do emissor do certificado intermediário.<br />O identificador deve ter o formato C4: A7: B1: A4: 7B: 2C: 71: FA: DB: E1: 4B: 90: 75: FF: C4: 15: 60: 85: 89: 10.                                                                                                                                                        |
| emissor                                  | dicionário | <br />                                                      | Permite especificar partes do emissor de um certificado na cadeia que deve ser selecionada.<br /><br /><br />Se o emissor estiver vazio, qualquer certificado correspondente será fornecido.                                                                                                                                                                                                                          |
| assunto                                  | dicionário | <br />                                                      | Permite especificar partes do assunto de um certificado na cadeia que deve ser selecionado.<br /><br /><br />Se o assunto estiver vazio, qualquer certificado correspondente será solicitado.                                                                                                                                                                                                                         |
| identificador\_chave\_do\_assunto        | corda      | <br />                                                      | Verifique a extensão SubjectKeyIdentifier. Este é um identificador baseado na chave privada do certificado intermediário.                                                                                                                                                                                                                                                                                             |
| certificados\_de\_teste                  | corda      | Escolhas:<br />- primeiro<br />- durar<br />- todos (padrão) | Determine quais certificados da cadeia serão testados.<br />all testa todos os certificados da cadeia (excluindo a folha, que é idêntica em todas as cadeias).<br /><br />primeiro teste apenas o primeiro certificado da cadeia, ou seja, aquele que assinou a folha.<br />last testa apenas o último certificado da cadeia, ou seja, o que está mais longe da folha. Seu emissor é o certificado raiz desta cadeia. |

## Exemplos[https://docs.simonops.com/homologacao-atmosphere/acme-certificate#6W4Pp](https://docs.simonops.com/homologacao-atmosphere/acme-certificate#6W4Pp)

## Valores Retornados

[https://docs.simonops.com/homologacao-atmosphere/acme-certificate#Gm481](https://docs.simonops.com/homologacao-atmosphere/acme-certificate#Gm481)

| **Chave**           | <br />                      | <br />                                                                             | **Descrição**                                                                                                                                                                                                                                                               |
| ------------------- | ---------------------------- | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| conta\_uri          | corda                        | alterado                                                                            | URI da conta ACME.<br />                                                                                                                                                                                                                                                    |
| todas\_as\_cadeias  | lista / elementos=dicionário | quando o certificado foi recuperado e retrieve\_all\_alternates é definido como sim | Quando retrieve\_all\_alternates é definido como yes , o módulo irá consultar o servidor ACME para cadeias alternativas. Este valor de retorno conterá uma lista de todas as cadeias retornadas, sendo a primeira entrada a cadeia principal retornada pelo servidor.<br /> |
| autorizações        | dicionário                   | alterado                                                                            | Dados de autorização ACME.<br /><br />Mapeia um identificador para objetos de autorização ACME.                                                                                                                                                                             |
| dias\_certificados  | inteiro                      | sucesso                                                                             | O número de dias que o certificado permanece válido.<br />                                                                                                                                                                                                                  |
| dados\_desafio      | lista / elementos=dicionário | alterado                                                                            | Por identificador/tipo de desafio de dados de desafio. Apenas desafios que ainda não são válidos são retornados.<br />                                                                                                                                                      |
| desafio\_dados\_dns | dicionário                   | alterado                                                                            | Lista de valores TXT por registro DNS, caso o desafio seja dns-01. Apenas desafios que ainda não são válidos são retornados.<br />                                                                                                                                          |
| finalização\_uri    | corda                        | alterado                                                                            | URI de finalização ACME.<br />                                                                                                                                                                                                                                              |
| ordem\_uri          | corda                        | alterado                                                                            | URI do pedido ACME.<br />                                                                                                                                                                                                                                                   |

### Subcampos do valor de retorno all\_chains

[https://docs.simonops.com/homologacao-atmosphere/acme-certificate#sozD6](https://docs.simonops.com/homologacao-atmosphere/acme-certificate#sozD6)

| **Parâmetro**    | **Tipo** | **Escolhas \| Valor Padrão** | **Comentários**                                                                                                    |
| ---------------- | -------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| certificado      | corda    | sempre                       | O próprio certificado folha, em formato PEM.                                                                       |
| corrente         | corda    | sempre                       | A cadeia de certificados, excluindo a raiz, como certificados PEM concatenados.                                    |
| cadeia\_completa | corda    | sempre                       | A cadeia de certificados, excluindo a raiz, mas incluindo o certificado folha, como certificados PEM concatenados. |

### Subcampos do valor de retorno challenge\_data

[https://docs.simonops.com/homologacao-atmosphere/acme-certificate#Ec4sI](https://docs.simonops.com/homologacao-atmosphere/acme-certificate#Ec4sI)

| **Parâmetro**      | **Tipo** | **Escolhas \| Valor Padrão** | **Comentários**                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ------------------ | -------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| registro           | corda    | alterado                     | O nome completo do registro DNS para o desafio.                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| recurso            | corda    | alterado                     | O recurso de desafio que deve ser criado para validação.                                                                                                                                                                                                                                                                                                                                                                                                                        |
| recurso\_original  | corda    | alterado                     | O recurso de desafio original inclui identificador de tipo para desafios tls-alpn-01 .                                                                                                                                                                                                                                                                                                                                                                                          |
| valor\_do\_recurso | corda    | alterado                     | O valor que o recurso deve produzir para a validação.<br />Para os desafios http-01 e dns-01 , o valor pode ser usado no estado em que se encontra.<br /><br />Para desafios tls-alpn-01 , observe que este valor de retorno contém uma versão codificada em Base64 do blob binário correto que deve ser colocado na extensão acmeValidation x509;<br /><br />Para fazer isso, você pode precisar do filtro b64decode Jinja para extrair o blob binário desse valor de retorno. |


[title] Certificado OpenSSL
[path] Documentação Técnica/Automações/Criptomoeda/

## Resumo

- Este módulo permite (re) gerar certificados OpenSSL. Ele implementa uma noção de provedor (ie. `selfsigned`, `ownca`, `acme`, `assertonly`) Para o seu certificado. 
- O provedor 'assertonly' destina-se a casos de uso em que alguém está interessado apenas em verificar as propriedades de um certificado fornecido. 
- O provedor 'ownca' se destina a gerar um certificado OpenSSL assinado com seu próprio certificado CA (Autoridade de Certificação) (certificado autoassinado). Muitas propriedades que podem ser especificadas neste módulo são para validação de um certificado existente ou gerado recentemente. O local adequado para especificá-los, se você deseja receber um certificado com essas propriedades, é um CSR (Solicitação de Assinatura de Certificado).

## Parâmetros

| **Parâmetro**                                                             | **Tipo**            | **Escolhas \| Valor Padrão**                                           | **Comentários**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ------------------------------------------------------------------------- | ------------------- | ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| acme\_accountkey\_path                                                    | path                |                                                                        | Caminho para a chave da conta do `acme` provedor<br /><br />Isso só é usado pelo `acme` provedor.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| acme\_chain                                                               | boolean             | Escolhas:<br />- true(default)<br />- false                            | Incluir o certificado intermediário para o certificado gerado<br /><br />Isso só é usado pelo `acme` provedor.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| acme\_challenge\_path                                                     | path                |                                                                        | Caminho para o diretório de desafio ACME que é servido em <br /><br />http: // \<HOST>: 80 / .well-known / acme-challenge /<br /><br />Isso só é usado pelo `acme` provedor.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| attributes<br /><br />aliases: attr                                       | string              |                                                                        | Atributos que o arquivo ou diretório deve ter. Para obter os sinalizadores suportados, consulte a página do manual do *chattr* no sistema de destino. Essa string deve conter os atributos na mesma ordem que aquela exibida por *lsattr*.<br /><br />operador `=` é assumido como padrão, caso contrário, `+` ou `-` os operadores precisam ser incluídos na string.                                                                                                                                                                                                                                                                                                                                                                    |
| csr\_path                                                                 | path                |                                                                        | Caminho para a solicitação de assinatura de certificado (CSR) usada para gerar este certificado. Isso não é necessário no `assertonly` modo.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| extended\_key\_usage<br /><br />aliases: extendedKeyUsage                 | list / elements=str |                                                                        | O campo de extensão *extended\_key\_usage* deve conter todos esses valores.<br /><br />Isso só é usado pelo `assertonly` provedor.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| extended\_key\_usage\_strict<br /><br />aliases: extendedKeyUsage\_strict | boolean             | Escolhas:<br />- true<br />- false(default)                            | Se definido como True, o campo de extensão *extended\_key\_usage* deve conter apenas esses valores.<br /><br />Isso só é usado pelo `assertonly` provedor.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| force                                                                     | boolean             | Escolhas:<br />- true<br />- false(default)                            | Gere o certificado, mesmo que já exista.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| group                                                                     | string              |                                                                        | Nome do grupo que deve possuir o arquivo / diretório, como seria alimentado para *chown* .                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| has\_expired                                                              | boolean             | Escolhas:<br />- true<br />- false(default)                            | Verifica se o certificado expirou / não expirou no momento em que o módulo é executado.<br /><br />Isso só é usado pelo `assertonly` provedor.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| invalid\_at                                                               | string              |                                                                        | O certificado deve ser inválido neste momento.\\<br /><br />O carimbo de data / hora é formatado como ASN.1 TIME.\\<br /><br />Isso só é usado pelo `assertonly` provedor.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| issuer                                                                    | dict                |                                                                        | Pares de Key/value que devem estar presentes no campo de nome do emissor do certificado.<br /><br />Se você precisar especificar mais de um valor com a mesma chave, use uma lista como valor.<br /><br />Isso só é usado pelo `assertonly` provedor.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| issuer\_strict                                                            | boolean             | Escolhas:<br />- true<br />- false(default)                            | Se definido como True, o campo do *emissor* deve conter apenas esses valores.<br /><br />Isso só é usado pelo `assertonly` provedor.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| key\_usage<br /><br />aliases: keyUsage                                   | list / elements=str |                                                                        | O campo de extensão *key\_usage* deve conter todos esses valores.<br /><br />Isso só é usado pelo `assertonly` provedor.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| key\_usage\_strict<br /><br />aliases: keyUsage\_strict                   | boolean             | Escolhas:<br />- true<br />- false(default)                            | Se definido como True, o campo de extensão *key\_usage* deve conter apenas esses valores.<br /><br />Isso só é usado pelo `assertonly` provedor.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| mode                                                                      | string              |                                                                        | Modo em que o arquivo ou diretório deve ser. Para aqueles acostumados com */ usr / bin / chmod,* lembre-se de que os modos são, na verdade, números octais. Você deve adicionar um zero à esquerda para que o analisador YAML do Atmosphere saiba que é um número octal (como 0644ou 01777) ou citá-lo (como '644'ou '1777') para que Atmosphere receba uma string e possa fazer sua própria conversão de string em número. Fornecer um número a Atmosphere sem seguir uma dessas regras resultará em um número decimal que terá resultados inesperados.                                                                                                                                                                                 |
| not\_after<br /><br />aliases: notAfter                                   | string              |                                                                        | O certificado deve expirar neste momento.<br /><br />O carimbo de data / hora é formatado como ASN.1 TIME.<br /><br />Isso só é usado pelo `assertonly` provedor.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| not\_before<br /><br />aliases: notBefore                                 | string              |                                                                        | O certificado deve começar a se tornar válido neste momento.<br /><br />O carimbo de data / hora é formatado como ASN.1 TIME.<br /><br />Isso só é usado pelo `assertonly` provedor.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| ownca\_digest                                                             | string              | Default:<br />- "sha256"                                               | Algoritmo de resumo a ser usado para o ownca certificado.<br /><br />Isso só é usado pelo ownca provedor.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ownca\_not\_after                                                         | string              |                                                                        | O carimbo de data / hora em que o certificado deixa de ser válido. O carimbo de data / hora é formatado como ASN.1 TIME. Se este valor não for especificado, o certificado deixará de ser válido daqui a 10 anos.<br /><br />Isso só é usado pelo `ownca` provedor.                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ownca\_not\_before                                                        | string              |                                                                        | O carimbo de data / hora em que o certificado começa a ser válido. O carimbo de data / hora é formatado como ASN.1 TIME. Se este valor não for especificado, o certificado passará a ser válido a partir de agora.<br /><br />Isso só é usado pelo `ownca` provedor.                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| ownca\_path                                                               | path                |                                                                        | Caminho remoto absoluto do certificado CA (Autoridade de Certificação).<br /><br />Isso só é usado pelo `ownca` provedor.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ownca\_privatekey\_passphrase                                             | string              |                                                                        | A senha *longa* para *ownca\_privatekey\_path*.<br /><br />Isso só é usado pelo `ownca` provedor.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ownca\_privatekey\_path                                                   | path                |                                                                        | Caminho para a chave privada CA (Autoridade de Certificação) a ser usada ao assinar o certificado.\\<br /><br />Isso só é usado pelo `ownca` provedor.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ownca\_version                                                            | integer             | Default:<br />- 3                                                      | Versão do `ownca` certificado.<br /><br />Hoje em dia, quase sempre deveria ser `3`.<br /><br />Isso só é usado pelo `ownca` provedor.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| owner                                                                     | string              |                                                                        | Nome do usuário que deve possuir o arquivo / diretório, como seria alimentado para *chown* .                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| path - required                                                           | path                |                                                                        | Caminho absoluto remoto onde o arquivo de certificado gerado deve ser criado ou já está localizado.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| privatekey\_passphrase                                                    | string              |                                                                        | A senha *longa* para *privatekey\_path*. <br /><br />Isso é necessário se a chave privada for protegida por senha.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| privatekey\_path                                                          | path                |                                                                        | Caminho para a chave privada a ser usada ao assinar o certificado.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| provider - required                                                       | string              | Escolhas:<br />- selfsigned<br />- ownca<br />- assertonly<br />- acme | Nome do provedor a ser usado para gerar / recuperar o certificado OpenSSL. O `assertonly` provedor não gerará arquivos e falhará se o arquivo de certificado estiver ausente.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| selevel                                                                   | string              | Default:<br />- "s0"                                                   | Parte do nível do contexto do arquivo SELinux. Este é o atributo MLS / MCS, também conhecido como range. \_defaultrecurso funciona como *seuer* .                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| selfsigned\_digest                                                        | string              | Default:<br />"sha256"                                                 | Algoritmo de resumo a ser usado ao autoassinar o certificadoIsso só é usado pelo selfsignedprovedor.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| selfsigned\_not\_after<br /><br />aliases: selfsigned\_notAfter           | string              |                                                                        | O carimbo de data / hora em que o certificado deixa de ser válido. O carimbo de data / hora é formatado como ASN.1 TIME. Se este valor não for especificado, o certificado deixará de ser válido daqui a 10 anos.<br /><br />Isso só é usado pelo `selfsigned` provedor.                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| selfsigned\_not\_before<br /><br />aliases: selfsigned\_notBefore         | string              |                                                                        | O carimbo de data / hora em que o certificado começa a ser válido. O carimbo de data / hora é formatado como ASN.1 TIME. Se este valor não for especificado, o certificado passará a ser válido a partir de agora.<br /><br />Isso só é usado pelo `selfsigned` provedor.                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| selfsigned\_version                                                       | integer             | Default:<br />- 3                                                      | Versão do `selfsigned` certificado.<br /><br />Hoje em dia, quase sempre deveria ser `3`.<br /><br />Isso só é usado pelo `selfsigned` provedor.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| serole                                                                    | string              |                                                                        | Função parte do contexto do arquivo SELinux, `_default` recurso funciona para *seuser* .                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| setype                                                                    | string              |                                                                        | Digite parte do contexto do arquivo SELinux, o `_default` recurso funciona como para *seuser* .                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| seuser                                                                    | string              |                                                                        | Parte do usuário do contexto do arquivo SELinux. Terá como padrão a política do sistema, se aplicável. Se definido como `_default`, usará a userparte da política, se disponível.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| signature\_algorithms                                                     | list / elements=str |                                                                        | lista de algoritmos com os quais você aceitaria o certificado a ser assinado (por exemplo, \['sha256WithRSAEncryption', 'sha512WithRSAEncryption']).<br /><br />Isso só é usado pelo `assertonly` provedor.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| state                                                                     | string              | Escolhas:<br />- present(default)<br />- absent                        | Se o certificado deve existir ou não, agir se o estado for diferente do que é declarado.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| subject                                                                   | dict                |                                                                        | Pares de chave / valor que devem estar presentes no campo de nome do assunto do certificado. Se você precisar especificar mais de um valor com a mesma chave, use uma lista como valor.<br /><br />Isso só é usado pelo `assertonly` provedor.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| subject\_alt\_name<br /><br />aliases: subjectAltName                     | string              |                                                                        | O campo de extensão *subject\_alt\_name* deve conter esses valores.<br /><br />Isso só é usado pelo `assertonly` provedor.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| subject\_alt\_name\_strict<br /><br />aliases: subjectAltName\_strict     | boolean             | Escolhas:<br />- true<br />- false(default)                            | Se definido como True, o campo de extensão *subject\_alt\_name* deve conter apenas esses valores.<br /><br />Isso só é usado pelo `assertonly` provedor.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| subject\_strict<br />                                                     | boolean             | Escolhas:<br />- true<br />- false(default)                            | Se definido como True, o campo de *assunto* deve conter apenas esses valores.<br /><br />Isso só é usado pelo `assertonly` provedor.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| unsafe\_writes                                                            | boolean             | Escolhas:<br />- true<br />- false(default)                            | Por padrão, este módulo usa operações atômicas para evitar corrupção de dados ou leituras inconsistentes dos arquivos de destino, mas às vezes os sistemas são configurados ou apenas interrompidos de maneiras que evitam isso. Um exemplo são os arquivos montados no docker, que não podem ser atualizados atomicamente de dentro do contêiner e só podem ser gravados de maneira insegura.<br /><br />Esta opção permite que o Atmosphere recorra a métodos não seguros de atualização de arquivos quando as operações atômicas falham (no entanto, não força o Atmosphere a realizar gravações inseguras). <br /><br />IMPORTANTE! As gravações inseguras estão sujeitas a condições de corrida e podem levar à corrupção de dados. |
| valid\_at                                                                 | string              |                                                                        | O certificado deve ser válido neste momento.<br /><br />O carimbo de data / hora é formatado como ASN.1 TIME.<br /><br />Isso só é usado pelo `assertonly` provedor.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| valid\_in                                                                 | string              |                                                                        | O certificado ainda deve ser válido em *valid\_in* segundos a partir de agora.Isso só é usado pelo `assertonly` provedor.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| version                                                                   | integer             |                                                                        | A versão do certificado.Hoje em dia, quase sempre deveria ser `3`.<br /><br />Isso só é usado pelo `assertonly` provedor.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |



## Notas

- Todos os valores de ASN.1 TIME devem ser especificados seguindo o padrão YYYYMMDDHHMMSSZ. A data especificada deve ser UTC. Minutos e segundos são obrigatórios.
- Por motivos de segurança, ao usar o `ownca` provedor. Você NÃO deve executar o openssl\_certificate em uma máquina de destino, mas em uma máquina CA dedicada. Recomenda-se não armazenar a chave privada da CA na máquina de destino. Depois de assinado, o certificado pode ser movido para a máquina de destino.
- Deve ser executado de forma remota no host

## Exemplos

```yaml
# Gerar um certificado OpenSSL autoassinado
  openssl_certificate:
    path: /etc/ssl/crt/atmosphere.com.crt
    privatekey_path: /etc/ssl/private/atmosphere.com.pem
    csr_path: /etc/ssl/csr/atmosphere.com.csr
    provider: selfsigned

# Gere um certificado OpenSSL assinado com seu próprio certificado CA
  openssl_certificate:
    path: /etc/ssl/crt/atmosphere.com.crt
    csr_path: /etc/ssl/csr/atmosphere.com.csr
    ownca_path: /etc/ssl/crt/atmosphere.crt
    ownca_privatekey_path: /etc/ssl/private/atmosphere_CA.pem
    provider: ownca

# Gerar um certificado Let's Encrypt
  openssl_certificate:
    path: /etc/ssl/crt/atmosphere.com.crt
    csr_path: /etc/ssl/csr/atmosphere.com.csr
    provider: acme
    acme_accountkey_path: /etc/ssl/private/atmosphere.com.pem
    acme_challenge_path: /etc/ssl/challenges/atmosphere.com/

# Forçar (re) gerar um novo certificado Let's Encrypt
  openssl_certificate:
    path: /etc/ssl/crt/atmosphere.com.crt
    csr_path: /etc/ssl/csr/atmosphere.com.csr
    provider: acme
    acme_accountkey_path: /etc/ssl/private/atmosphere.com.pem
    acme_challenge_path: /etc/ssl/challenges/atmosphere.com/
    force: yes

# Gerar um certificado Entrust por meio da API Entrust Certificate Services (ECS)
  openssl_certificate:
    path: /etc/ssl/crt/atmosphere.com.crt
    csr_path: /etc/ssl/csr/atmosphere.com.csr
    provider: entrust
    entrust_requester_name: Jo Doe
    entrust_requester_email: jdoe@atmosphere.com
    entrust_requester_phone: 555-555-5555
    entrust_cert_type: STANDARD_SSL
    entrust_api_user: apiusername
    entrust_api_key: a^lv*32!cd9LnT
    entrust_api_client_cert_path: /etc/ssl/entrust/ecs-client.crt
    entrust_api_client_cert_key_path: /etc/ssl/entrust/ecs-key.crt
    entrust_api_specification_path: /etc/ssl/entrust/api-docs/cms-api-2.1.0.yaml

# O exemplo a seguir mostra um uso assertonly usando todas as opções existentes para 
# assertonly e mostra como emular o comportamento com os módulos 
# openssl_certificate_info, openssl_csr_info, openssl_privatekey_info e assert:

- openssl_certificate:
    provider: assertonly
    path: /etc/ssl/crt/atmosphere.com.crt
    csr_path: /etc/ssl/csr/atmosphere.com.csr
    privatekey_path: /etc/ssl/csr/atmosphere.com.key
    signature_algorithms:
      - sha256WithRSAEncryption
      - sha512WithRSAEncryption
    subject:
      commonName: atmosphere.com
    subject_strict: yes
    issuer:
      commonName: atmosphere.com
    issuer_strict: yes
    has_expired: no
    version: 3
    key_usage:
      - Data Encipherment
    key_usage_strict: yes
    extended_key_usage:
      - DVCS
    extended_key_usage_strict: yes
    subject_alt_name:
      - dns:atmosphere.com
    subject_alt_name_strict: yes
    not_before: 20190331202428Z
    not_after: 20190413202428Z
    valid_at: "+1d10h"
    invalid_at: 20200331202428Z
    valid_in: 10  # in ten seconds

- openssl_certificate_info:
    path: /etc/ssl/crt/atmosphere.com.crt
    # para valid_at, invalid_at e valid_in
    valid_at:
      one_day_ten_hours: "+1d10h"
      fixed_timestamp: 20200331202428Z
      ten_seconds: "+10"
  register: result

- openssl_csr_info:
    # Verifica se a assinatura CSR é válida; o módulo irá falhar se não
    path: /etc/ssl/csr/atmosphere.com.csr
  register: result_csr

- openssl_privatekey_info:
    path: /etc/ssl/csr/atmosphere.com.key
  register: result_privatekey

- assert:
    that:
      # Quando a chave privada é especificada para assertonly, isso será verificado:
      - result.public_key == result_privatekey.public_key
      # Quando CSR é especificado para assertonly, isso será verificado:
      - result.public_key == result_csr.public_key
      - result.subject_ordered == result_csr.subject_ordered
      - result.extensions_by_oid == result_csr.extensions_by_oid
      # verificação de assinatura_algoritmos
      - "result.signature_algorithm == 'sha256WithRSAEncryption' or result.signature_algorithm == 'sha512WithRSAEncryption'"
      # assunto e subject_strict
      - "result.subject.commonName == 'atmosphere.com'"
      - "result.subject | length == 1"  # o número deve ser o número de entradas que você verifica
      # issuer e issuer_strict
      - "result.issuer.commonName == 'atmosphere.com'"
      - "result.issuer | length == 1"  # o número deve ser o número de entradas que você verifica
      # has_expired
      - not result.expired
      # versão
      - result.version == 3
      # key_usage e key_usage_strict
      - "'Data Encipherment' in result.key_usage"
      - "result.key_usage | length == 1"  # o número deve ser o número de entradas que você verifica
      # extended_key_usage e extended_key_usage_strict
      - "'DVCS' in result.extended_key_usage"
      - "result.extended_key_usage | length == 1"  # o número deve ser o número de entradas que você verifica
      # subject_alt_name e subject_alt_name_strict
      - "'dns:atmosphere.com' in result.subject_alt_name"
      - "result.subject_alt_name | length == 1"  # o número deve ser o número de entradas que você verifica
      # not_before e not_after
      - "result.not_before == '20190331202428Z'"
      - "result.not_after == '20190413202428Z'"
      # valid_at, invalid_at e valid_in
      - "result.valid_at.one_day_ten_hours"  # para valid_at
      - "not result.valid_at.fixed_timestamp"  # para invalid_at
      - "result.valid_at.ten_seconds"  # para valid_in

# Exemplos para algumas verificações que podem ser usadas para o provedor assertonly: 
# (observe que assertonly foi descontinuado!)

# Como usar o provedor assertonly para implementar e acionar seu próprio fluxo de 
# trabalho de geração de certificado personalizado: Verifique se um certificado ainda é válido, ignorando as falhas
  openssl_certificate:
    path: /etc/ssl/crt/example.com.crt
    provider: assertonly
    has_expired: no
  ignore_errors: yes
  register: validity_check

# Execute tarefas personalizadas para obter um certificado novo e válido no caso de falha na verificação inicial
  command: superspecialSSL recreate /etc/ssl/crt/example.com.crt
  when: validity_check.failed

# Verifique a validade do novo certificado novamente com os mesmos parâmetros, desta vez falhando no jogo se ainda for inválido
  openssl_certificate:
    path: /etc/ssl/crt/example.com.crt
    provider: assertonly
    has_expired: no
  when: validity_check.failed

# Algumas outras verificações que assertonly podem ser usadas para: 
# Verificar se um certificado existente foi emitido pelo Let's Encrypt CA e ainda é válido
  openssl_certificate:
    path: /etc/ssl/crt/example.com.crt
    provider: assertonly
    issuer:
      O: Let's Encrypt
    has_expired: no

# Certifique-se de que um certificado usa um algoritmo de assinatura moderno (sem SHA1, MD5 ou DSA)
  openssl_certificate:
    path: /etc/ssl/crt/example.com.crt
    provider: assertonly
    signature_algorithms:
      - sha224WithRSAEncryption
      - sha256WithRSAEncryption
      - sha384WithRSAEncryption
      - sha512WithRSAEncryption
      - sha224WithECDSAEncryption
      - sha256WithECDSAEncryption
      - sha384WithECDSAEncryption
      - sha512WithECDSAEncryption

# Certifique-se de que o certificado existente pertence à chave privada especificada
  openssl_certificate:
    path: /etc/ssl/crt/example.com.crt
    privatekey_path: /etc/ssl/private/example.com.pem
    provider: assertonly

# Certifique-se de que o certificado existente ainda é válido no solstício de inverno de 2017
  openssl_certificate:
    path: /etc/ssl/crt/example.com.crt
    provider: assertonly
    valid_at: 20171221162800Z

# Certifique-se de que o certificado existente ainda é válido 2 semanas (1209600 segundos) a partir de agora
  openssl_certificate:
    path: /etc/ssl/crt/example.com.crt
    provider: assertonly
    valid_in: 1209600

# Certifique-se de que o certificado existente é usado apenas para assinaturas digitais e criptografar outras chaves
  openssl_certificate:
    path: /etc/ssl/crt/example.com.crt
    provider: assertonly
    key_usage:
      - digitalSignature
      - keyEncipherment
    key_usage_strict: true

# Certifique-se de que o certificado existente pode ser usado para autenticação de cliente
  openssl_certificate:
    path: /etc/ssl/crt/example.com.crt
    provider: assertonly
    extended_key_usage:
      - clientAuth

# Certifique-se de que o certificado existente só pode ser usado para autenticação de cliente e carimbo de data / hora
  openssl_certificate:
    path: /etc/ssl/crt/example.com.crt
    provider: assertonly
    extended_key_usage:
      - clientAuth
      - 1.3.6.1.5.5.7.3.8
    extended_key_usage_strict: true

# Certifique-se de que o certificado existente tenha um determinado domínio em seu subjectAltName
  openssl_certificate:
    path: /etc/ssl/crt/example.com.crt
    provider: assertonly
    subject_alt_name:
      - www.example.com
      - test.example.com
```

## Valores Retornados

| **Chave** | **Tipo** | **Retornado quando** | **Descrição**                     |
| --------- | -------- | -------------------- | --------------------------------- |
| filename  | string   | changed ou sucesso   | Caminho para o certificado gerado |




[title] Cripto
[path] Documentação Técnica/Automações/

# Módulos

- **Certificado Acme:&#x20;**&#x45;ste módulo permite criar certificados SSL/TLS com o protocolo ACME.
- **Certoficado OpenSSL:**&#x45;ste módulo permite (re)gerar certificados OpenSSL.
- **Informaçoes do Certificado OpenSSL:** Este módulo permite consultar informações sobre certificados OpenSSL.
- **OpenSSL CSR:&#x20;**&#x47;erar solicitação de assinatura de certificado OpenSSL (CRS).
- **OpenSSL CSR info-&#x20;**&#x46;ornece informações de transferência de assinatura de certificado OpenSSL (CSR).
- **OpenSSL Pcks12 -&#x20;**&#x47;erar arquivos OpenSSL Pcks#12
- **OpenSSL Public Key -&#x20;**&#x47;ere uma chave pública OpenSSL a partir de sua chave privada.




[title] Comandos
[path] Documentação Técnica/Automações/

## Módulos

- **Poweshell Command** - Executa remotamente um comando powershell.
- **Command** - Execute comandos desejados.
- **Shell** - Execute comandos do shell por executáveis nos destinos.
- **SSH Command** - Execute comandos em um Client SSH.


[title] Criando o Bot
[path] Documentação Técnica/Automações/Telegram/

# 1. Inicie uma conversa com o BotFather

Se você nunca iniciou um chat com o BotFather, confira os passos:

1. No Telegram, selecione o menu de pesquisa e procure por @BotFather.
2. Vários bots poderão aparecer, mas lembre-se, somente bots oficiais do Telegram possuem verificado ao lado do nome.
3. Selecione o BotFather.

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/YPt4sw4jVayu8Wln43l6E_captura-de-tela-2021-11-09-as-111450.png)



# 2. Criando e configurando seu bot

Logo após selecionarmos o BotFather, precisamos ver a sua lista de comandos, para isso basta digitar algo no chat que você obterá o seguinte retorno:

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/SAd-Ybmhyb4gEMhJM4Sf8_captura-de-tela-2021-11-09-as-113727.png)

Com a lista de comandos em mãos, iniciaremos a criação selecionando ou digitando o comando /newbot :

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/EKAjj2biLPS-_Or2hGccn_captura-de-tela-2021-11-09-as-114454.png)

Feito isso, deveremos estabelecer um nome e um usuário, com os quais o bot será criado. Caso seja retornado algum erro, o name ou username já estão sendo utilizados por outra pessoa.&#x20;

Efetuado todos os passos, receberemos um retorno de sucesso na criação do bot:

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/y8gyP1Lu0Ld_yh6_BsUzR_captura-de-tela-2021-11-09-as-120114.png)

## 3.  Buscando API Token

Existem duas formas de se buscar pelo API Token do nosso bot:

1. Ao terminarmos de criar o bot (a mesma aparecerá na mensagem de sucesso).
2. Buscando pelas configurações do bot.

Buscando pelas configurações, basta digitarmos `/mybots > selecionar o bot desejado > API Token` e, em seguida teremos nosso Token:

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/w8dl5gY1IAMtjQo_ynk_H_captura-de-tela-2021-11-09-as-122926.png)

# 4.  Buscando Chat ID

Para se obter o Chat ID, siga os passos:

1. Adicione o bot do Telegram ao seu grupo.
2. Para que o bot registre  o Chat ID, envie uma mensagem qualquer para o grupo criado.
3. ``[https://api.telegram.org/bot\<BotToken>/getUpdates](https://api.telegram.org/bot\<BotToken>/getUpdates)

&#x20;   4\. Procure pelo objeto "chat":

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/nSOJDOk87i921_DZGwsGF_captura-de-tela-2021-11-09-as-125344.png)

Dica:

Se você criou o novo grupo com o bot e só obtém \{"ok": true, "result": \[]}, remova e adicione o bot novamente ao grupo.

[title] Certificado Cadeia Completa
[path] Documentação Técnica/Automações/Criptomoeda/

## Resumo

- Este módulo completa uma determinada cadeia de certificados no formato PEM, encontrando certificados intermediários de um determinado conjunto de certificados, até encontrar um certificado raiz em outro determinado conjunto de certificados.
- Observe que este módulo *não* verifica a validade das cadeias. Ele apenas verifica se o emissor e o assunto correspondem e se a assinatura está correta. Ele ignora as datas de validade e o uso da chave completamente. Se você precisar verificar se uma cadeia gerada é válida, use .openssl verify ...

## Parâmetros

| **Parâmetro**                 | **Tipo** | **Escolhas \| Valor Padrão** | **Comentários**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ----------------------------- | -------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| input\_chain - required       | string   |                              | Um conjunto concatenado de certificados no formato PEM formando uma cadeia.<br /><br />O módulo tentará completar esta cadeia.                                                                                                                                                                                                                                                                                                                                                                                   |
| intermediate\_certificates    |          | Padrão:<br />\[]             | Uma lista de nomes de arquivos ou diretórios.<br /><br />Supõe-se que um nome de arquivo aponta para um arquivo que contém um ou mais certificados no formato PEM. Todos os certificados neste arquivo serão adicionados ao conjunto de certificados raiz.<br /><br />Se um nome de diretório for fornecido, todos os arquivos no diretório e seus subdiretórios serão verificados e tentados para serem analisados ​​como certificados concatenados no formato PEM.<br /><br />Links simbólicos serão seguidos. |
| root\_certificates - required |          |                              | Uma lista de nomes de arquivos ou diretórios.<br /><br />Supõe-se que um nome de arquivo aponta para um arquivo que contém um ou mais certificados no formato PEM. Todos os certificados neste arquivo serão adicionados ao conjunto de certificados raiz.<br /><br />Se um nome de diretório for fornecido, todos os arquivos no diretório e seus subdiretórios serão verificados e tentados para serem analisados ​​como certificados concatenados no formato PEM.<br /><br />Links simbólicos serão seguidos. |




## Exemplos

```yaml
# Dado um leaf certificate para www.atmosphere.com e um ou mais certificados 
# intermediários, encontra o certificado raiz associado.
- name: Find root certificate
  certificate_complete_chain:
    input_chain: "{{ lookup('file', '/etc/ssl/csr/www.ansible.com-fullchain.pem') }}"
    root_certificates:
    - /etc/ca-certificates/
  register: www_ansible_com
- name: Write root certificate to disk
  copy:
    dest: /etc/ssl/csr/www.ansible.com-root.pem
    content: "{{ www_ansible_com.root }}"

# Given a leaf certificate for www.ansible.com, and a list of intermediate
# certificates, finds the associated root certificate.
- name: Find root certificate
  certificate_complete_chain:
    input_chain: "{{ lookup('file', '/etc/ssl/csr/www.ansible.com.pem') }}"
    intermediate_certificates:
    - /etc/ssl/csr/www.ansible.com-chain.pem
    root_certificates:
    - /etc/ca-certificates/
  register: www_ansible_com
- name: Write complete chain to disk
  copy:
    dest: /etc/ssl/csr/www.ansible.com-completechain.pem
    content: "{{ ''.join(www_ansible_com.complete_chain) }}"
- name: Write root chain (intermediates and root) to disk
  copy:
    dest: /etc/ssl/csr/www.ansible.com-rootchain.pem
    content: "{{ ''.join(www_ansible_com.chain) }}"
```

## Valores Retornados

| **Parâmetro**                               | **Tipo**               | **Retornado quando** |                                                                                                                                              |
| ------------------------------------------- | ---------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| cadeia lista / elementos = string           | list / elements=string | sucesso              | A cadeia adicionada à cadeia de entrada fornecida. Inclui o certificado raiz.<br /><br />Retornado como uma lista de certificados PEM.<br /> |
| cadeia\_completa lista / elementos = string | list / elements=string | sucesso              | A cadeia completa, incluindo folha, todos os intermediários e raiz.<br /><br />Retornado como uma lista de certificados PEM.<br />           |
| raiz fragmento                              | string                 | sucesso              | O certificado raiz no formato PEM.<br />                                                                                                     |


[title] Inspeção Acne
[path] Documentação Técnica/Automações/Criptomoeda/

# Inspeção Acme

## Sinopse[https://docs.simonops.com/homologacao-atmosphere/acme-inspect#ugLwc](https://docs.simonops.com/homologacao-atmosphere/acme-inspect#ugLwc)

- Permite enviar comunicações diretas para um servidor ACME com o protocolo ACME , que é suportado por CAs como Let's Encrypt .
- Este módulo pode ser usado para depurar a solicitação de certificado com falha, por exemplo, quando o acme\_certificate falha ou encontra um problema que você deseja investigar.
- O módulo também pode ser usado para acessar diretamente recursos de servidores ACME que ainda não são suportados pelos módulos Atmosphere ACME.

## Parâmetros[https://docs.simonops.com/homologacao-atmosphere/acme-inspect#n0c6g](https://docs.simonops.com/homologacao-atmosphere/acme-inspect#n0c6g)

| **Parâmetro**                 | **Tipo** | **Escolhas \| Valor Padrão**                                                  | **Comentários**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ----------------------------- | -------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| conteúdo\_chave\_da\_conta    | corda    | <br />                                                                       | Conteúdo da chave RSA ou curva elíptica da conta ACME.<br /><br />Mutuamente exclusivo com  account\_key\_src .<br /><br />É necessário que  account\_key\_src não seja usado.<br /><br />Atenção: o conteúdo será gravado em um arquivo temporariamente, que será excluído pelo Atmosphere quando o módulo for concluído. <br />Como essa é uma chave privada importante — ela pode ser usada para alterar a chave de conta ou revogar seus certificados sem conhecer suas chaves privadas —, isso pode não ser aceitável.<br /><br />Caso  a criptografia seja usada, o conteúdo não é gravado em um arquivo temporário. Ainda pode acontecer que ele seja gravado em disco pelo Ansible no processo de mover o módulo com seu argumento para o nó onde ele é executado. |
| senha\_chave\_da\_conta       | corda    | <br />                                                                       | Phassphrase é usado para decodificar a chave da conta.<br /><br />Nota: isso não é suportado pelo back-end do openssl , apenas pelo back-end de criptografia .                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| account\_key\_src             | caminho  | <br />                                                                       | Caminho para um arquivo que contém a chave RSA ou curva elíptica da conta ACME.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| conta\_uri                    | corda    | <br />                                                                       | Se especificado, assuma que o URI da conta é o informado. Se a chave da conta não corresponder a essa conta ou não existir uma conta com esse URI, o módulo falhará.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| acme\_directory - obrigatório | corda    | <br />                                                                       | O diretório ACME foi usado. Esta é a URL do ponto de entrada para acessar a API do servidor ACME CA.<br /><br />Por motivos de segurança, o padrão é definido para o servidor de teste Let's Encrypt (para o protocolo ACME v1). Isso criará certificados técnicos corretos, mas não confiáveis.                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| acme\_version - obrigatório   | inteiro  | Escolhas:<br />- 1<br />- 2                                                   | A versão ACME do endpoint.<br /><br /><br />Deve ser  1 para os endpoints ACME clássicos Let's Encrypt e Buypass ou  2 para endpoints ACME v2 padronizados.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| contente                      | corda    | <br />                                                                       | Um objeto JSON codificado que será enviado como conteúdo se o  *método*  for post.<br /><br />Obrigatório quando o  *método*  é postado, e não é permitido de outra forma.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| falha\_no\_erro\_acme         | boleano  | Escolhas:<br />- Verdadeiro (padrão)<br />- Falso                             | Se o  *método*  para  post ou  get , faça o módulo falhar caso um erro ACME seja retornado.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| método                        | corda    | Escolhas:<br />- obter(padrão)<br />- publicar<br />- diretório<br />- apenas | O método é usado para acessar uma URL fornecida no servidor ACME.<br /><br />O valor post executa uma solicitação POST autenticada. O conteúdo deve ser especificado na opção de *conteúdo.*<br />O valor getexecuta uma solicitação POST-as-GET autenticada para ACME v2 e uma solicitação GET regular para ACME v1.O valor directory-only apenas recupera o diretório, sem fazer uma solicitação.                                                                                                                                                                                                                                                                                                                                                                        |
| selecionar\_cripto\_backend   | corda    | Escolhas:<br />- auto(padrão)<br />- criptografia<br />- abre ssl             | Determina qual back-end de criptografia usar.A opção padrão é automática, que tenta usar criptografia se disponível e retorna para openssl.<br /><br />Se definido como openssl, tentarei usar o opensslbinário.<br /><br />Se definido como criptografia, tentará usar uma biblioteca de criptografia.                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| URL                           | corda    | <br />                                                                       | O URL para quem enviar uma solicitação.*O método* não<br />deve ser especificado   apenas para diretório.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| certificados\_válidos         | boleano  | Escolhas:<br />- verdadeiro (padrão)<br />- falso                             | Se as chamadas para o diretório ACME validarem certificados TLS.<br /><br /><br />Aviso: Deve ser configurado apenas para fins de teste, por exemplo, ao testar em um servidor Pebble local.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |

## Exemplos[https://docs.simonops.com/homologacao-atmosphere/acme-inspect#wdw99](https://docs.simonops.com/homologacao-atmosphere/acme-inspect#wdw99)

## Valores de retorno[https://docs.simonops.com/homologacao-atmosphere/acme-inspect#hPNv9](https://docs.simonops.com/homologacao-atmosphere/acme-inspect#hPNv9)

| **Chave**    | **Tipo**   | **Retornado quando**                     | **Descrição**                                             |
| ------------ | ---------- | ---------------------------------------- | --------------------------------------------------------- |
| diretório    | dicionário | sempre                                   | O conteúdo do diretório ACME                              |
| cabeçalhos   | dicionário | sempre                                   | Os cabeçalhos HTTP da solicitação (com chaves minúsculas) |
| saída\_json  | dicionário | se a saída pode ser comprovada como JSON | A saída é lida como JSON.                                 |
| texto\_saída | corda      | sempre                                   | Saída de texto bruto.                                     |


[title] Pacote OpenSSL Pkcs12
[path] Documentação Técnica/Automações/Criptomoeda/

## Resumo

- Gerar arquivos OpenSSL PKCS#12.

## Parâmetros

| **Parâmetro**                                                                     | **Tipo**             | **Escolhas \| Valor Padrão**                          | **Comentários**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| --------------------------------------------------------------------------------- | -------------------- | ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| action                                                                            | string               | Escolhas:<br />- export<br />(default)<br />- parse   | Exportar ou parsear (analisar) um arquivo PKCS#12.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| backup                                                                            | boolean              | Escolhas:<br />- false<br />(default)<br />- true     | Crie um arquivo de backup incluindo data/hora para que você possa obter o arquivo de saída original de volta se você o substituir por um novo acidentalmente.                                                                                                                                                                                                                                                                                                                                                                                                   |
| certificate\_path                                                                 | path                 |                                                       | O caminho para ler certificados e chaves privadas. Deve estar no formato PEM.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| force                                                                             | boolean              | Escolhas:<br />- false<br />(default)<br />- true     | Se o arquivo deve ser gerado novamente, mesmo que já exista.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| friendly\_name <br /><br />aliases: name                                          | string               |                                                       | Especifica o nome do certificado e da chave privada.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| iter\_size                                                                        | integer              | 2048<br />(default)                                   | Número de vezes para repetir a etapa de encryption.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| maciter\_size                                                                     | integer              | 1<br />(default)                                      | Número de vezes para repetir a etapa MAC.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| mode                                                                              | raw                  |                                                       | As permissões que o arquivo ou diretório resultante deve ter. Para aqueles usados para /usr/bin/chmod, lembre-se de que os modos são, na verdade, números octais. Você deve adicionar um zero à esquerda para que o analisador YAML do Atmosphere saiba que é um número octal (como 0644 ou 01777) ou citá-lo (como '644' ou '1777') para que o Atmosphere receba uma string e possa fazer sua própria conversão da string em número. Dar ao Atmosphere um número sem seguir uma dessas regras terminará com um número decimal que terá resultados inesperados. |
| other\_certificates <br /><br /><br /><br /><br /><br />aliases: ca\_certificates | list / elements=path |                                                       | Lista de outros certificados a serem incluídos.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| passphrase                                                                        | string               |                                                       | A senha PKCS#12.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| path - *required*                                                                 | path                 |                                                       | Nome do arquivo no qual gravar o arquivo PKCS#12.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| privatekey\_passphrase                                                            | string               |                                                       | Senha para descriptografar quaisquer chaves privadas de entrada.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| privatekey\_path                                                                  | path                 |                                                       | Arquivo para ler a chave privada.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| src                                                                               | path                 |                                                       | Caminho do arquivo PKCS#12 para análise.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| state                                                                             | string               | Escolhas:<br />- present<br />(default)<br />- absent | Se o arquivo deve existir ou não. Todos os parâmetros, exceto o path, são ignorados quando o estado está absent.                                                                                                                                                                                                                                                                                                                                                                                                                                                |

## Notas

- Para que você aproveite o máximo desse módulo, é necessário que o mesmo esteja funcionando em uma máquina remota ou host, que contenha os arquivos solicitados pelos parâmetros.

## Exemplos

```yaml
# Exemplo: Gerar arquivo PKCS#12
- openssl_pkcs12:
    action: export
    path: /opt/certs/example.p12
    friendly_name: raclette
    privatekey_path: /opt/certs/keys/key.pem
    certificate_path: /opt/certs/cert.pem
    state: present

# Exemplo: Alterar permissão de arquivo PKCS#12
- openssl_pkcs12:
    action: export
    path: /opt/certs/example.p12
    friendly_name: raclette
    privatekey_path: /opt/certs/keys/key.pem
    certificate_path: /opt/certs/cert.pem
    state: present
    mode: '0600'

# Exemplo: Forçar reescrita do arquivo PKCS#12
- openssl_pkcs12:
    action: export
    src: /opt/certs/example.p12
    path: /opt/certs/example.p12
    friendly_name: raclette
    privatekey_path: /opt/certs/keys/key.pem
    certificate_path: /opt/certs/cert.pem
    state: present
    mode: '0600'
    force: yes

# Exemplo: Dump/Parse o arquivo PKCS # 12
- openssl_pkcs12:
    action: parse
    src: /opt/certs/example.p12
    path: /opt/certs/example.pem
    state: present

# Exemplo: Remover arquivo PKCS#12
- openssl_pkcs12:
    path: /opt/certs/example.p12
    state: absent
```

## Valores retornados

| **Chave**     | **Tipo** | **Retornado quando**         | **Descrição**                                                                     |
| ------------- | -------- | ---------------------------- | --------------------------------------------------------------------------------- |
| backup\_file  | string   | Modificado e backup for true | Nome do arquivo de backup criado.                                                 |
| filename      | string   | Modificado ou sucesso        | Caminho para gerar o arquivo PKCS#12.                                             |
| privatekey    | string   | Modificado ou sucesso        | Caminho para a chave privada TLS/SSL a partir da qual a chave pública foi gerada. |



[title] Base Acme
[path] Documentação Técnica/Automações/Criptomoeda/

# Base Acme

## Resumo

[https://docs.simonops.com/homologacao-atmosphere/acme-base#er51u](https://docs.simonops.com/homologacao-atmosphere/acme-base#er51u)

- Módulo base que reúne opções comuns utilizadas em todos os módulos ACME.

## Parâmetros

[https://docs.simonops.com/homologacao-atmosphere/acme-base#Q7CH1](https://docs.simonops.com/homologacao-atmosphere/acme-base#Q7CH1)

| **Parâmetro**                   | **Tipo** | **Escolhas \| Valores padrão**                                         | **Comentários**                                                                                                                                                                                                                                                                                                                                                                       |
| ------------------------------- | -------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_key\_src               | corda    | <br />                                                                | Caminho para um arquivo contendo ACME RSA ou Elliptic Curve.<br /><br />As chaves privadas podem ser criadas com os módulos openssl\_privatekey ou openssl\_privatekey\_pipe.                                                                                                                                                                                                         |
| conteúdo\_chave\_da\_conta      | corda    | <br />                                                                | Conteúdo da chave RSA ou Elliptic Curve da conta ACME.                                                                                                                                                                                                                                                                                                                                |
| senha\_chave\_da\_conta         | corda    | <br />                                                                | Senha a ser usada para decodificar a chave da conta.                                                                                                                                                                                                                                                                                                                                  |
| conta\_uri                      | corda    | <br />                                                                | Se especificado, suponha que o URI da conta seja o fornecido.<br /><br /><br />Se a chave da conta não for responsável por esta conta ou não existir uma conta com este URI, o módulo falhará.                                                                                                                                                                                       |
| versão\_acme                    | inteiro  | Escolhas:<br />- 1<br />- 2 ( *Padrão* )                               | A versão ACME do endpoint.<br /><br />Deve ser **1** para os terminais clássicos Let's Encrypt and Buypass ACME ou **2** para os terminais ACME v2 padronizados.                                                                                                                                                                                                                      |
| acme\_directory - *obrigatório* | corda    | <br />                                                                | O diretório ACME foi usado.<br /><br />Por motivos de segurança, o padrão é definido como o servidor de teste Let's Encrypt (para o protocolo ACME v1). Isso criará certificados técnicos corretos, mas não confiáveis.                                                                                                                                                               |
| validar\_certificados           | bool     | *Padrão: Verdadeiro*                                                   | *Se as chamadas para o diretório ACME validarem os certificados TLS.*                                                                                                                                                                                                                                                                                                                 |
| selecionar\_cripto\_backend     | corda    | Escolhas:<br />- auto ( *Padrão* )<br />- criptografia<br />- abre ssl | Determina qual back-end criptográfico usar.como diferente de localhost se *login\_port* for usado.<br /><br />A escolha padrão é ***auto*** , que tenta usar ***a criptografia*** disponível, e volta para ***openssl*** .<br /><br />Se definido como ***openssl*** , tentarei usar o binário ***openssl.***<br />Se definido como ***criptografia*** , tentará usar uma biblioteca. |



[space] AIOPS (/aiops2)

[title] Elastiflow
[path] AIOPS/AIOPS/Integrações/Observação de redes/

## ElastiFlow™ Unified Flow Collector

:::hint{type="info"}
## Ferramenta focada em visibilidade de rede

https\://www\.elastiflow\.com/
:::

O ElastiFlow ™ Unified Flow Collector recebe, decodifica, transforma, normaliza, traduz e enriquece registros de fluxo de rede e telemetria enviados de dispositivos de rede e aplicativos usando IPFIX, Netflow e sFlow. Os registros resultantes podem ser enviados para várias distribuições e serviços Elasticsearch, incluindo:

- Elasticsearch (on-premisses)
- Distro para Elasticsearch
- Serviço AWS Elasticsearch&#x20;



![](https://user-images.githubusercontent.com/10326954/89781356-727ede00-db13-11ea-8130-73562a8593f8.png)



## Integração&#x20;

Através da funcionalidade de [Integrações](docId\:AlFXMS8DV6xIonNE8g-y7) é possível ativar a integração com a ferramenta elastiflow e permitir coleta de informações relacionadas a tráfego de rede, possibilidade enriquecimento do contexto de situações adversas, permitindo um troubleshoot mais assertivo além de potencializar as automações que são possíveis de realizar através do Simon.



[title] Health Check
[path] AIOPS/MÉTRICAS/Explorar as Métricas/

Verificação de integridade simples

| **Chave**                      | **Tipo** | **Descrição**                         |
| ------------------------------ | -------- | ------------------------------------- |
| health\_check.`check_passed`   | string   | Verificação de integridade            |
| health\_check.`check_total`    | string   | verificação de integridade total      |
| health\_check.`duration`       | float    | duração da verificação de integridade |
| health\_check.`health_percent` | percent  | Porcentagem da integridade            |


[title] ATMOS
[path] AIOPS/


[title] Mem
[path] AIOPS/MÉTRICAS/Explorar as Métricas/

Traz informações da memória utilizado.

| **Chave**               | **Tipo** | **Descrição**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| ----------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| mem.`active`            | byte     | Quantidade de memória que foi usada de alguma maneira durante o último período de amostra.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| mem.`available`         | byte     | Quantidade de memória que está disponível e pode ser fornecida instantaneamente para os processos.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| mem.`available_percent` | percent  | Percentual de memória que está disponível e pode ser fornecido instantaneamente para os processos.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| mem.`buffered`          | byte     | Quantidade de memória que está sendo usada para buffers.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| mem.`cached`            | byte     | Quantidade de memória que está sendo usada para caches de arquivo.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| mem.`commit_limit`      | byte     | Limite de memória de confirmação do sistema é a soma da memória física e de todos os arquivos de página combinados.<br /><br />Ele representa a memória máxima confirmada pelo sistema (também conhecida como o "encargo de sistema") ao qual o sistema pode dar suporte.                                                                                                                                                                                                                                                                                                                 |
| mem.`committed_as`      | byte     | Quantidade total de memória, em kilobytes, estimada para concluir a carga de trabalho.<br /><br />Este valor representa o pior cenário possível e também inclui memória de troca.                                                                                                                                                                                                                                                                                                                                                                                                         |
| mem.`dirty`             | byte     | Para reduzir a frequência de escrita de blocos de endereços na memória aquando da substituição é usado um "dirty bit", este é um bit de estado, ou seja, quando o endereço é instanciado inicialmente numa linha do cache, estando essa linha vazia, o valor inicial é implicitamente '0', quando o bloco do endereço é modificado(quando ocorre uma substituição) o valor inicial passa a '1' e diz-se que o bloco do endereço está "dirty".                                                                                                                                             |
| mem.`free`              | byte     | Quantidade de memória que não está sendo usada.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| mem.`high_free`         | byte     | Quantidade total e livre de memória, em kilobytes, que não é mapeada diretamente no espaço do kernel.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| mem.`high_total`        | byte     | Quantidade total e livre de memória, em kilobytes, que não é mapeada diretamente no espaço do kernel.<br /><br />Valor HighTotal pode variar com base no tipo de kernel usado.                                                                                                                                                                                                                                                                                                                                                                                                            |
| mem.`huge_page_size`    | byte     | Tamanho da página                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| mem.`huge_pages_free`   | counter  | Número de páginas que não foram utilizadas.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| mem.`huge_pages_total`  | counter  | Representam o total de Hugepages que foram alocadas.<br /><br />Um detalhe importante é que a Hugepages fica previamente alocada, se você alocou 20GB de Hugepages, mas só usa 5, os 20GB já ficarão alocados.<br /><br />Não que isso seja ruim, se você tem um servidor dedicado ao banco de dados a memória deveria ser dedicada a ele.                                                                                                                                                                                                                                                |
| mem.`inactive`          | byte     | Quantidade de memória que não foi usada de alguma maneira durante o último período de amostra.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| mem.`low_free`          | byte     | Quantidade de memória baixa livre.<br /><br />Memória baixa (ou memória normal), é mapeada diretamente para a parte do kernel.                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| mem.`low_total`         | byte     | Memória baixa total.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| mem.`mapped`            | counter  | Quantidade de arquivos mapeados na memória.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| mem.`page_tables`       | byte     | Amazena o mapeamento entre o endereço virtual e o endereço físico.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| mem.`shared`            | byte     | Tamanho da região de memória que pode ser compartilhada por dois ou mais processos.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| mem.`slab`              | byte     | Quantidade de memória alocada no slab.<br /><br />A alocação de blocos é um mecanismo de gerenciamento de memória destinado à alocação eficiente de memória de objetos. <br /><br />Em comparação com os mecanismos anteriores, ele reduz a fragmentação causada por alocações e desalocações. <br /><br />A técnica é usada para reter a memória alocada que contém um objeto de dados de um determinado tipo para reutilização em alocações subsequentes de objetos do mesmo tipo. <br /><br />É análogo a um pool de objetos , mas se aplica apenas à memória, não a outros recursos.  |
| mem.`sreclaimable`      | byte     | Parte do slab que pode ser recuperada (como caches)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| mem.`sunreclaim`        | byte     | Espaço alocado para estruturas de cados do kernel                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| mem.`swap_cached`       | byte     | Quantidade de espaço de swap que está em uso.<br /><br />Este é um local no disco rígido (geralmente uma partição dedicada) que é usado para armazenar programas ou dados que não cabem na memória, como quando um programa cresce mais do que a memória disponível.<br /><br />SWAP é muito mais lento do que RAM, então quando você clica em swap, o computador fica mais lento, mas pelo menos o programa pode funcionar.<br /><br />No linux, a troca também é usada para hibernar ou para remover a memória do programa pouco usado para permitir mais espaço para o cache de disco. |
| mem.`swap_free`         | byte     | Quantidade de espaço de swap que não está em uso.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| mem.`swap_total`        | **byte** | Quantidade de espaço de swap total.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| mem.`total`             | byte     | Quantidade total de memória.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| mem.`used`              | byte     | Quantidade de memória em uso no momento.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| mem.`used_percent`      | percent  | Percentual de memória em uso no momento.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| mem.`vmalloc_chunk`     | byte     | Memória alocada para um bloco de bytes consecutivos na memória RAM                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| mem.`vmalloc_total`     | byte     | Total de Memória alocada para um bloco de bytes consecutivos na memória RAM                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| mem.`vmalloc_used`      | byte     | Memória usada na locação para um bloco de bytes consecutivos na memória RAM                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| mem.`wired`             | byte     | Memória wired alocada.<br /><br />Ela é marcada para se manter em RAM. Nunca será movida para disco                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| mem.`write_back`        | byte     | Memória write\_back.<br /><br />Bloco de endereço é carregado na ocorrência seguindo-se uma ação.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| mem.`write_back_tmp`    | time     | Tempo que a memória write\_back irá permanecer alocada                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |


[title] Real User Monitoring
[path] AIOPS/DIVEDOT/

## Sessões

Através do divedot é possível acompanhar a sessão de um usuário final nas aplicações monitoradas, permitindo entender o caminho e informações consumidas por um usuário final, tais como:

- Tempo de cada sessão;
- Dados de Insight da rede e servidor da aplicação;
- Tempo de renderização e download da página web.&#x20;

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/kLGjb28pDqzEw3nDfl6fj_screen-shot-2021-06-17-at-192720.png "Sessão de usuário")

Com o Rum Session podemos acompanhar a experiência do usuário final em cada aplicação e ter os dados relevantes de acessos, tais como:

- Geolocalização de usuário;
- Navegador utilizado na sessão;
- Dispositivos utilizado;
- IP de cada sessão iniciada na aplicação;
- Duração e a média de tempo em cada ação tomada na sessão;
- As ações que cada usuário fez durante o acesso;
- Chamadas a serviços de terceiros com o período histórico;
- Histórico das sessões com dados de sucesso ou falha em cada acesso.

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/QLw3D9aBPxu--GNDprfFk_image.png)

## Auditoria

Mantenha os logs das transações de cada sessão armazenadas para auditoria, podendo ser exportados e acessados por outras plataformas de código aberto.


[title] RPM
[path] AIOPS/AIOPS/Inventário/Instalação dos Agents/Agent Linux/

## Redhat/Centos 6

### 1 - Adicione o repositorio do Agent

```shell
sudo wget https://dl.fedoraproject.org/pub/epel/RPM-GPG-KEY-EPEL-6

sudo wget https://rpm.ocsinventory-ng.org/ocsinventory-release-latest.el6.ocs.noarch.rpm
```

Você pode instalar o repositorio com **yum**:

```shell
sudo yum install ocsinventory-release-latest.el6.ocs.noarch.rpm RPM-GPG-KEY-EPEL-6
```

### 2 - Instale o Agent

```shell
sudo yum install ocsinventory-agent
```

## Redhat/Centos 7

### 1 - Adicione o repositorio do Agent

```shell
sudo wget https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
sudo wget https://rpm.ocsinventory-ng.org/ocsinventory-release-latest.el7.ocs.noarch.rpm
```

Você pode instalar o repositório com **yum**:

```shell
sudo yum install ocsinventory-release-latest.el7.ocs.noarch.rpm epel-release-latest-7.noarch.rpm
```

### 2 - Instale o Agent

```shell
sudo yum install ocsinventory-agent
```

## Redhat/Centos 8

### 1 - Adicione o repositorio do Agent

```shell
sudo wget https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm
sudo wget https://rpm.ocsinventory-ng.org/ocsinventory-release-latest.el8.ocs.noarch.rpm
```

Você pode instalar o repositório com **dnf**:

```shell
sudo dnf install ocsinventory-release-latest.el8.ocs.noarch.rpm epel-release-latest-8.noarch.rpm
```

### 2 - Instale o Agent

```shell
sudo dnf --enablerepo=PowerTools --enablerepo=epel-playground install ocsinventory-agent
```

Durante a instalação, você será solicitado a escolher como o agent se comunicará com o servidor. **Selecione o método HTTP e prossiga**:

Em seguida, defina a **URL** do servidor. A sintaxe da **URL** é similar a:

```shell
http[s]://inventory-server/ocsinventory
```

## Rocky/Alma e Redhat 9

### 1 - Adicione o repositorio do Agent

```shell
sudo wget https://dl.fedoraproject.org/pub/epel/epel-release-latest-9.noarch.rpm
sudo wget https://rpm.ocsinventory-ng.org/ocsinventory-release-latest.el9.ocs.noarch.rpm
```

Você pode instalar o repositório com **dnf**:

```shell
sudo  dnf install ocsinventory-release-latest.el9.ocs.noarch.rpm epel-release-latest-9.noarch.rpm
```

### 2 - Instale o Agent e seus requisitos

```shell
sudo dnf install yum-utils
sudo yum-config-manager --enable crb
sudo dnf install ocsinventory-agent
```

Durante a instalação, você será solicitado a escolher como o agente se comunicará com o servidor. **Selecione o método HTTP e prossiga**:

Em seguida, defina a **URL** do servidor. A sintaxe da **URL** é similar a:

```shell
http[s]://inventory-server/ocsinventory
```

## Fedora

### 1 - Adicione o repositorio do Agent

```shell
export FEDORA_VERSION=$(awk '{print $3}' /etc/fedora-release)
sudo wget https://rpm.ocsinventory-ng.org/ocsinventory-release-latest.fc$FEDORA_VERSION.ocs.noarch.rpm
```

Você pode instalar o repositório com **dnf**:

```shell
sudo dnf install ocsinventory-release-latest.fc$FEDORA_VERSION.ocs.noarch.rpm
```

### 2 - Instale o Agent

```shell
sudo dnf install ocsinventory-agent
```

Durante a instalação, você será solicitado a escolher como o agente se comunicará com o servidor. **Selecione o método HTTP e prossiga**:

Em seguida, defina a **URL** do servidor. A sintaxe da **URL** é similar a:

```shell
http[s]://inventory-server/ocsinventory
```

## Desabilite a checagem de certificado

Adicione a flag `ssl=0` na configuração disponível no arquivo `/etc/ocsinventory/ocsinventory-agent.cfg`:

:::CodeblockTabs
Exemplo

```shell
server=http[s]://inventory-server/ocsinventory
ssl=0
```
:::

## Gerando a coleta manualmente

Para realizar a coleta manual do item, execute o seguinte comando:

```shell
ocsinventory-agent --server http[s]://inventory-server/ocsinventory
```

## Opcional - Configure o Agent para inventariar o sistema de hora em hora por meio do cron job

```shell
mv /etc/cron.daily/ocsinventory-agent /etc/cron.hourly
```


[title] Descoberta e relacionamento
[path] AIOPS/AIOPS/Inventário/

### Introdução

O Xventory é uma ferramenta de gerenciamento de ativos de TI que oferece uma série de recursos para automatizar o processo de gerenciamento de ativos de TI. Uma das funcionalidades mais importantes do Xventory é a capacidade de automatizar o relacionamento entre ativos no processo de inventário de ativos.

Com o Xventory, é possível coletar automaticamente informações sobre a relação entre ativos, incluindo informações sobre a hierarquia do sistema, dependências de software, interações de rede e muito mais. Essas informações são usadas para criar uma visão completa dos serviços de TI em uma organização, incluindo quais ativos são usados em cada serviço, quais serviços dependem de outros serviços e muito mais.

### Automações

A automação do relacionamento entre ativos com o Xventory oferece uma série de benefícios para as organizações. Em primeiro lugar, a automação torna o processo de gerenciamento de ativos de TI mais eficiente e escalável. Em vez de coletar manualmente informações sobre a relação entre ativos, o Xventory coleta automaticamente essas informações, permitindo que as organizações se concentrem em outras tarefas importantes.

### Relacionamentos&#x20;

Além disso, a automação do relacionamento entre ativos ajuda as organizações a entender melhor como os serviços de TI são construídos e quais ativos são essenciais para o bom funcionamento desses serviços. Com essa visão completa dos serviços de TI, as organizações podem identificar ativos redundantes ou obsoletos que podem ser eliminados, reduzindo custos e melhorando a eficiência do sistema, além de se manterem atualizadas das informações necessárias.

### Inventário e relacionamento

Com o Xventory, as organizações podem obter informações de relacionamento entre ativos de forma automatizada no processo de inventário de ativos, tornando o gerenciamento de ativos de TI mais eficiente e escalável. Além disso, o Xventory oferece relatórios detalhados sobre a relação entre ativos, permitindo que as organizações monitorem as mudanças na relação entre ativos e identifiquem possíveis problemas antes que afetem os serviços de TI.

### WOL&#x20;

O Xventory também oferece suporte à tecnologia Wake On LAN (WOL), que permite às organizações ligar remotamente computadores que estão em modo de espera (standby) ou hibernação. Com o suporte ao WOL, as organizações podem atualizar ou fazer manutenção em computadores remotamente, sem precisar estar fisicamente presentes no local.

Para usar o recurso WOL do Xventory, é necessário que os computadores estejam equipados com placas de rede compatíveis com WOL e que o recurso esteja habilitado nas configurações de energia do sistema. Com o WOL ativado, o administrador de sistema pode enviar um sinal para o computador remotamente para acordá-lo do modo de espera ou hibernação e atualizá-lo ou fazer manutenção no sistema.


[title] Requisitos
[path] AIOPS/INTRODUÇÃO/


[title] INTRODUÇÃO
[path] AIOPS/


[title] HTTP Request
[path] AIOPS/MÉTRICAS/Explorar as Métricas/

Parâmetros importantes do protocolo HTTP e sua sintaxe na forma como são usados na comunicação.

| **Chave**                                      | **Tipo** | **Descrição**                                               |
| ---------------------------------------------- | -------- | ----------------------------------------------------------- |
| http\_request.`duration`                       | time     | Duração da solicitação HTTP                                 |
| http\_request.`error`                          | string   | Mensagem de erro retornado da solicitação HTTP              |
| http\_request.`error_count`                    | counter  | Quantidade de erros retornado da solicitação HTTP           |
| http\_request.`passed_percent`                 | percent  | Porcentagem de solicitações HTTP passadas com sucesso       |
| http\_request.`reason`                         | string   | Motivo da resposta                                          |
| http\_request.`size_bytes`                     | byte     | Tamanho do arquivo de requisição                            |
| http\_request.`ssl_certificate_expired`        | string   | Informações do certificado SSL expirado                     |
| http\_request.`ssl_certificate_expiry_days`    | counter  | Quantidade de dias que o certificado SSL  está expirado     |
| http\_request.`ssl_certificate_expiry_seconds` | counter  | Quantidade de segundos que o certificado SSL  está expirado |


[title] Distribuição
[path] AIOPS/AIOPS/Inventário/

O gerenciamento eficiente de ativos de TI é um desafio constante para as organizações. Com o crescente número de dispositivos e sistemas em uso, os administradores de sistema precisam de ferramentas que os ajudem a rastrear e gerenciar ativos de hardware e software em toda a organização. O Xventory é uma ferramenta de gerenciamento de ativos de TI que permite que os administradores de sistema gerenciem e rastreiem ativos de hardware e software em uma organização de maneira eficiente e escalável.

Uma das funcionalidades essenciais do Xventory é a capacidade de distribuir software em dispositivos gerenciados em diversos sistemas operacionais, incluindo Linux, Windows e macOS. Isso é especialmente útil, pois muitas organizações utilizam uma mistura de sistemas operacionais em sua infraestrutura de TI.

### Distribuição de software no Xventory:

O Xventory oferece uma variedade de recursos para ajudar às organizações a gerenciar a distribuição de software em dispositivos gerenciados e a verificar a compatibilidade do software com outros aplicativos no dispositivo. Com o uso de rótulos personalizados para dispositivos e aplicativos, é possível gerenciar e rastrear a implantação de software em dispositivos gerenciados, tornando mais fácil implantar software em dispositivos específicos ou em grupos de dispositivos com base em critérios como sistema operacional ou configuração do dispositivo.

Além disso, o Xventory fornece relatórios detalhados sobre a implantação de software em dispositivos gerenciados, permitindo que os administradores de sistema monitorem a implantação de software e verifiquem se o software foi implantado com sucesso em todos os dispositivos gerenciados. Com esses recursos, o Xventory é capaz de distribuir software no parque computacional do cliente de maneira eficiente e escalável, garantindo a segurança e o bom funcionamento dos sistemas em toda a organização.

A implantação de software em dispositivos gerenciados é um processo complexo que requer cuidado e atenção aos detalhes. Ao implantar software, é importante levar em consideração a compatibilidade do software com outros aplicativos no dispositivo, bem como com o sistema operacional de destino. O Xventory ajuda os administradores de sistema a gerenciar esse processo de maneira eficiente e escalável, garantindo que o software seja implantado com sucesso em todos os dispositivos gerenciados.

### Recursos do Xventory para gerenciar a distribuição de software em dispositivos gerenciados:

Com o Xventory, os administradores de sistema podem criar grupos de teste para verificar a compatibilidade do software com os sistemas operacionais de destino e com outros aplicativos no dispositivo antes de implantar o software em um grande número de dispositivos gerenciados. Além disso, os rótulos personalizados ajudam os administradores de sistema a gerenciar a implantação de software em dispositivos específicos ou em grupos de dispositivos com base em critérios específicos.





[title] DIVEDOT
[path] AIOPS/


[title] Atmos
[path] AIOPS/AIOPS/Usuários/Permissões por Roles/

## Funcionalidades

|                                                                    | **Administrador** | **Analista** | **Gestor**      | **Supervisor**  | **Operador**    |
| ------------------------------------------------------------------ | ----------------- | ------------ | --------------- | --------------- | --------------- |
| ****[Infraestrutura](https://docs.simonops.com/infraestrutura)**** | Acesso total      | Acesso total | Somente leitura | Somente leitura | Somente leitura |
| ****[Hosts](https://docs.simonops.com/hosts)****                   | Acesso total      | Acesso total | Somente leitura | Somente leitura | Somente leitura |
| ****[Serviços de TI](https://docs.simonops.com/servicos-de-ti)**** | Acesso total      | Acesso total | Acesso total    | Somente leitura | Somente leitura |
| ****[Topologia](https://docs.simonops.com/topologia)****           | Acesso total      | Acesso total | Acesso total    | Somente leitura | Somente leitura |
| ****[Dashboards](https://docs.simonops.com/paineis-dashboards)**** | Acesso total      | Acesso total | Acesso total    | Acesso total    | Acesso total    |
| ****[Pipes](https://docs.simonops.com/pipes-e-automacao)****       | Acesso total      | Acesso total | Somente leitura | Somente leitura | Somente leitura |
| ****[Alerting](https://docs.simonops.com/alertas-triggers)****     | Acesso total      | Acesso total | Somente leitura | Somente leitura | Somente leitura |
| ****[Testes Web](https://docs.simonops.com/testes-web)****         | Acesso total      | Acesso total | Somente leitura | Somente leitura | Sem Acesso      |
| **Planos de manutenção**                                           | Acesso total      | Acesso total | Acesso total    | Somente leitura | Somente leitura |
| ****[Agendamentos](https://docs.simonops.com/agendamentos)****     | Acesso total      | Acesso total | Somente leitura | Somente leitura | Somente leitura |
| **Tempo de Serviço**                                               | Acesso total      | Acesso total | Somente leitura | Sem Acesso      | Sem Acesso      |



## Configurações

### Infraestrutura

|                             | **Administrador** | **Analista** | **Gestor**      | **Supervisor**  | **Operador**    |
| --------------------------- | ----------------- | ------------ | --------------- | --------------- | --------------- |
| **Sugestão de recursos**    | Acesso total      | Sem Acesso   | Sem Acesso      | Sem Acesso      | Sem Acesso      |
| **Anotações**               | Acesso total      | Acesso total | Somente leitura | Somente leitura | Somente leitura |
| **Template de métricas**    | Acesso total      | Acesso total | Somente leitura | Somente leitura | Sem Acesso      |
| **Métricas**                | Acesso total      | Acesso total | Somente leitura | Somente leitura | Sem Acesso      |
| **Grupos (Metric Plugins)** | Acesso total      | Acesso total | Acesso total    | Somente leitura | Somente leitura |

### SNMP

|                | **Administrador** | **Analista** | **Gestor**      | **Supervisor** | **Operador** |
| -------------- | ----------------- | ------------ | --------------- | -------------- | ------------ |
| **Descoberta** | Acesso total      | Acesso total | Somente leitura | Sem Acesso     | Sem Acesso   |
| **Coleta**     | Acesso total      | Acesso total | Somente leitura | Sem Acesso     | Sem Acesso   |
| **Perfis**     | Acesso total      | Acesso total | Somente leitura | Sem Acesso     | Sem Acesso   |
| **Grupos**     | Acesso total      | Acesso total | Somente leitura | Sem Acesso     | Sem Acesso   |

### Pipes

|              | **Administrador** | **Analista** | **Gestor**      | **Supervisor**  | **Operador**    |
| ------------ | ----------------- | ------------ | --------------- | --------------- | --------------- |
| **Scripts**  | Acesso total      | Acesso total | Somente leitura | Somente leitura | Sem Acesso      |
| **Serviços** | Acesso total      | Acesso total | Somente leitura | Somente leitura | Somente leitura |


[title] Net
[path] AIOPS/MÉTRICAS/Explorar as Métricas/

Este plugin coleta métricas sobre interface de rede e uso de protocolo.

| **Chave**                   | **Tipo** | **Descrição**                                                                                                                                                                                   |
| --------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| net.`bytes_recv`            | bytes    | Número total de bytes recebidos pela interface.                                                                                                                                                 |
| net.`bytes_sent`            | bytes    | Número total de bytes enviados pela interface.                                                                                                                                                  |
| net.`drop_in`               | counter  | Número total de pacotes recebidos perdidos pela interface.                                                                                                                                      |
| net.`drop_out`              | counter  | Número total de pacotes transmitidos perdidos pela interface.                                                                                                                                   |
| net.`err_in`                | counter  | Número total de erros de recebimento detectados pela interface.                                                                                                                                 |
| net.`err_out`               | counter  | Número total de erros de transmissão detectados pela interface.                                                                                                                                 |
| net.`icmp_inaddrmaskreps`   | counter  | Número de respostas de máscaras de rede.                                                                                                                                                        |
| net.`icmp_inaddrmasks`      | counter  | Número de solicitações de máscaras de rede.                                                                                                                                                     |
| net.`icmp_incsumerrors`     | counter  | Quando uma falha de checksum é detectada.                                                                                                                                                       |
| net.`icmp_indestunreachs`   | counter  | Número de mensagens de destino inacessíveis recebidas.                                                                                                                                          |
| net.`icmp_inechoreps`       | counter  | Número de respostas ICMP Echo recebidas.                                                                                                                                                        |
| net.`icmp_inechos`          | counter  | Número de solicitações ICMP Echo recebidas.                                                                                                                                                     |
| net.`icmp_inerrors`         | counter  | Número de mensagens de falha ICMP.                                                                                                                                                              |
| net.`icmp_inmsgs`           | counter  | Número de mensagens ICMP recebidas.                                                                                                                                                             |
| net.`icmp_inparmprobs`      | counter  | Número de mensagens de problema de parâmetro ICMP recebidas.                                                                                                                                    |
| net.`icmp_inredirects`      | counter  | Número de mensagens de redirecionamento ICMP recebidas.                                                                                                                                         |
| net.`icmp_insrcquenchs`     | counter  | Número de mensagens ICMP Source Quench recebidas.                                                                                                                                               |
| net.`icmp_intimeexcds`      | counter  | Número de mensagens de tempo excedido recebidas.                                                                                                                                                |
| net.`icmp_intimestampreps`  | counter  | Número de respostas de data/hora recebidas.                                                                                                                                                     |
| net.`icmp_intimestamps`     | counter  | Número de solicitação de data/hora recebidas.                                                                                                                                                   |
| net.`icmp_outaddrmaskreps`  | counter  | Número de respostas de máscara de endereço  enviadas.                                                                                                                                           |
| net.`icmp_outaddrmasks`     | counter  | Número de solicitações de máscara de endereço enviadas.                                                                                                                                         |
| net.`icmp_outdestunreachs`  | counter  | Número de mensagens de destino inacessíveis enviadas.                                                                                                                                           |
| net.`icmp_outechoreps`      | counter  | Número de respostas ICMP Echo enviadas.                                                                                                                                                         |
| net.`icmp_outechos`         | counter  | Número de solicitações ICMP Echo enviadas.                                                                                                                                                      |
| net.`icmp_outerrors`        | counter  | Número de mensagens ICMP que esta entidade não enviou devido a problemas descobertos no ICMP, como falta de buffers.                                                                            |
| net.`icmp_outmsgs`          | counter  | Número total de mensagens ICMP que esta entidade tentou enviar.                                                                                                                                 |
| net.`icmp_outparmprobs`     | counter  | Número de mensagens de problema de parâmetro ICMP enviadas.                                                                                                                                     |
| net.`icmp_outredirects`     | counter  | Número de mensagens de redirecionamento ICMP enviadas.                                                                                                                                          |
| net.`icmp_outsrcquenchs`    | counter  | Número de mensagens ICMP Source Quench enviadas.                                                                                                                                                |
| net.`icmp_outtimeexcds`     | counter  | Número de mensagens de tempo excedido enviadas.                                                                                                                                                 |
| net.`icmp_outtimestampreps` | counter  | Número de respostas de data/hora enviadas.                                                                                                                                                      |
| net.`icmp_outtimestamps`    | counter  | Número de solicitação de data/hora enviadas.                                                                                                                                                    |
| net.`icmpmsg_intype0`       | counter  | Indica o número de entrada do tipo ICMP, nesse caso (echo reply).                                                                                                                               |
| net.`icmpmsg_intype11`      | counter  | Indica o número de entrada tipo ICMP, nesse caso (time exceeded).                                                                                                                               |
| net.`icmpmsg_intype3`       | counter  | Indica o número de entrada do tipo ICMP, nesse caso (destination unreachable).                                                                                                                  |
| net.`icmpmsg_intype4`       | counter  | Indica o número de entrada do tipo ICMP, nesse caso (source quench).                                                                                                                            |
| net.`icmpmsg_intype5`       | counter  | Indica o número de entrada do tipo ICMP, nesse caso (redirect).                                                                                                                                 |
| net.`icmpmsg_intype8`       | counter  | Indica o número de entrada do tipo ICMP, nesse caso (echo).                                                                                                                                     |
| net.`icmpmsg_outtype0`      | counter  | Indica o número de saída do tipo ICMP, nesse caso (echo reply).                                                                                                                                 |
| net.`icmpmsg_outtype11`     | counter  | Indica o número de saída do tipo ICMP, nesse caso (time exceeded).                                                                                                                              |
| net.`icmpmsg_outtype3`      | counter  | Indica o número de saída do tipo ICMP, nesse caso (destination unreachable).                                                                                                                    |
| net.`icmpmsg_outtype5`      | counter  | Indica o número de saída do tipo ICMP, nesse caso (redirect).                                                                                                                                   |
| net.`icmpmsg_outtype8`      | counter  | Indica o número de saída do tipo ICMP, nesse caso (echo).                                                                                                                                       |
| net.`ip_defaultttl`         | counter  | O TTL determina o tempo máximo que um pacote IP pode residir na rede sem chegar ao seu destino.                                                                                                 |
| net.`ip_forwarding`         | counter  | Utilizado para determinar para qual caminho um pacote ou datagrama pode ser enviado.                                                                                                            |
| net.`ip_forwdatagrams`      | counter  | Número de datagramas de entrada para os quais esta entidade não era o seu destino de IP final.                                                                                                  |
| net.`ip_fragcreates`        | counter  | Número de fragmentos de datagramas IP que foram gerados como resultado da fragmentação nesta entidade.                                                                                          |
| net.`ip_fragfails`          | counter  | Número de datagramas de IP que foram descartados porque precisavam ser fragmentados nesta entidade, mas não puderam.                                                                            |
| net.`ip_fragoks`            | counter  | Número de datagramas IP que foram fragmentados com êxito nesta entidade.                                                                                                                        |
| net.`ip_inaddrerrors`       | counter  | Número de datagramas de entrada descartados, porque o endereço IP no campo de destino do cabeçalho não era um endereço válido para ser recebido nesta entidade.                                 |
| net.`ip_indelivers`         | counter  | Número total de datagramas de entrada entregues com sucesso aos protocolos de usuário IP (incluindo ICMP).                                                                                      |
| net.`ip_indiscards`         | counter  | Número de datagramas de IP de entrada nos quais nenhum problema foi encontrado para impedir seu processamento contínuo, mas que foram descartados (por exemplo, por falta de espaço de buffer). |
| net.`ip_inhdrerrors`        | counter  | Número de datagramas de entrada descartados devido a erros em seus cabeçalhos de IP, incluindo somas de verificação incorretas, incompatibilidade de número de versão, etc.                     |
| net.`ip_inreceives`         | counter  | Número total de datagramas de entrada recebidos de interfaces, incluindo aqueles recebidos com erro.                                                                                            |
| net.`ip_inunknownprotos`    | counter  | Número de datagramas endereçados localmente recebidos com sucesso, mas descartados devido a um protocolo desconhecido ou sem suporte.                                                           |
| net.`ip_outdiscards`        | counter  | Número de datagramas de IP de saída nos quais nenhum problema foi encontrado para impedir sua transmissão ao destino, mas que foram descartados (por exemplo, por falta de espaço de buffer).   |
| net.`ip_outnoroutes`        | counter  | Número de datagramas IP descartados porque nenhuma rota foi encontrada para transmiti-los ao seu destino.                                                                                       |
| net.`ip_outrequests`        | counter  | Número de datagramas IP em que os protocolos de usuário locais (incluindo ICMP) forneceram ao IP, em solicitações de transmissão.                                                               |
| net.`ip_reasmfails`         | counter  | Número de falhas detectadas pelo algoritmo de remontagem de IP (por qualquer motivo: tempo limite, erros etc.).                                                                                 |
| net.`ip_reasmoks`           | counter  | Número de datagramas IP remontados com êxito.                                                                                                                                                   |
| net.`ip_reasmreqds`         | counter  | Fragmentos de IP recebidos que precisaram ser remontados nesta entidade.                                                                                                                        |
| net.`ip_reasmtimeout`       | counter  | Número máximo de segundos que os fragmentos recebidos são mantidos, enquanto aguardam a remontagem nesta entidade.                                                                              |
| net.`packets_recv`          | counter  | Número total de pacotes enviados pela interface.                                                                                                                                                |
| net.`packets_sent`          | counter  | Número total de pacotes recebidos pela interface.                                                                                                                                               |
| net.`tcp_activeopens`       | counter  | Número de vezes que as conexões TCP fizeram uma transição direta para o estado SYN-SENT a partir do estado CLOSED.                                                                              |
| net.`tcp_attemptfails`      | counter  | Número de vezes que as conexões TCP tentaram fazer uma transição direta de estados, mas foram falhas.                                                                                           |
| net.`tcp_currestab`         | counter  | Número de conexões estabelecidas.                                                                                                                                                               |
| net.`tcp_estabresets`       | counter  | Número de redefinições de conexão recebidas.                                                                                                                                                    |
| net.`tcp_incsumerrors`      | counter  | Quando uma falha de checksum TCP é detectada.                                                                                                                                                   |
| net.`tcp_inerrs`            | counter  | Número total de segmentos recebidos com erro (por exemplo, somas de verificação de TCP incorretas).                                                                                             |
| net.`tcp_insegs`            | counter  | Número total de segmentos recebidos, incluindo aqueles recebidos com erro.                                                                                                                      |
| net.`tcp_maxconn`           | counter  | Número de conexões máximas.                                                                                                                                                                     |
| net.`tcp_outrsts`           | counter  | Número de redefinições enviadas.                                                                                                                                                                |
| net.`tcp_outsegs`           | counter  | Número de segmentos enviados.                                                                                                                                                                   |
| net.`tcp_passiveopens`      | counter  | Número de aberturas passivas (criação de um socket que aceitará conexões de entrada).                                                                                                           |
| net.`tcp_retranssegs`       | counter  | Número total de segmentos TCP que foram retransmitidos.                                                                                                                                         |
| net.`tcp_rtoalgorithm`      | counter  | Algoritmo de tempo limite de retransmissão TCP (RTO).                                                                                                                                           |
| net.`tcp_rtomax`            | counter  | RTO máximo.                                                                                                                                                                                     |
| net.`tcp_rtomin`            | counter  | RTO mínimo.                                                                                                                                                                                     |
| net.`udp_ignoredmulti`      | counter  | Utilizado somente com o UDP multicast.                                                                                                                                                          |
| net.`udp_incsumerrors`      | counter  | Quando uma falha de checksum UDP é detectada.                                                                                                                                                   |
| net.`udp_indatagrams`       | counter  | Número total de datagramas UDP entregues aos usuários UDP.                                                                                                                                      |
| net.`udp_inerrors`          | counter  | Erros de recebimento de pacote.                                                                                                                                                                 |
| net.`udp_noports`           | counter  | Pacotes recebidos em uma porta desconhecida.                                                                                                                                                    |
| net.`udp_outdatagrams`      | counter  | Número total de datagramas UDP enviados desta entidade.                                                                                                                                         |
| net.`udp_rcvbuferrors`      | counter  | Aumentado quando a memória não pode ser alocada, para processar um código de kernel de pacote UDP.                                                                                              |
| net.`udp_sndbuferrors`      | counter  | Aumentado quando a memória não pode ser alocada, para enviar um código de kernel de pacote UDP.                                                                                                 |
| net.`udplite_ignoredmulti`  | counter  | Utilizado somente com o UDP multicast.                                                                                                                                                          |
| net.`udplite_incsumerrors`  | counter  | Incrementado quando uma falha de checksum UDP Lite é detectada.                                                                                                                                 |
| net.`udplite_indatagrams`   | counter  | Número total de datagramas UDP-Lite que foram entregues aos usuários UDP-Lite.                                                                                                                  |
| net.`udplite_inerrors`      | counter  | Erros de recebimento de pacote.                                                                                                                                                                 |
| net.`udplite_noports`       | counter  | Número total de datagramas UDP-Lite recebidos para os quais não havia porta de destino.                                                                                                         |
| net.`udplite_outdatagrams`  | counter  | Número total de datagramas UDP-Lite enviados desta entidade.                                                                                                                                    |
| net.`udplite_rcvbuferrors`  | counter  | Aumentado quando a memória não pode ser alocada, para processar um código de kernel de pacote UDP Lite.                                                                                         |
| net.`udplite_sndbuferrors`  | counter  | Aumentado quando a memória não pode ser alocada, para enviar um pacote UDP Lite.                                                                                                                |


[title] Docker Container Blkio
[path] AIOPS/MÉTRICAS/Explorar as Métricas/

Controla e monitora o acesso a I/O em dispositivos de bloco.

Um dispositivo de **bloco** armazena as informações em blocos de tamanho fixo, cada qual com seu endereço. Cada bloco pode ser lido ou escrito de maneira independente uns dos outros.

| **Chave**                                                     | **Tipo** | **Descrição**                                                           |
| ------------------------------------------------------------- | -------- | ----------------------------------------------------------------------- |
| docker\_container\_blkio.`container_id`                       | string   | Container ID                                                            |
| docker\_container\_blkio.`io_service_bytes_recursive_async`   | bytes    | Volume, em bytes, do bloco assíncrono I/O                               |
| docker\_container\_blkio.`io_service_bytes_recursive_discard` | bytes    | Volume de discards de dispositivos de bloco.                            |
| docker\_container\_blkio.`io_serviced_bytes_recursive_read`   | bytes    | Volume de leituras de dispositivos de bloco.                            |
| docker\_container\_blkio.`io_serviced_bytes_recursive_sync`   | bytes    | Volume, em bytes, de I/O de bloco síncrono.                             |
| docker\_container\_blkio.`io_serviced_bytes_recursive_total`  | bytes    | Volume total, em bytes, de todos os blocos de I/O.                      |
| docker\_container\_blkio.`io_serviced_bytes_recursive_write`  | bytes    | Volume, em bytes, de gravações para bloquear dispositivos               |
| docker\_container\_blkio.`io_serviced_recursive_async`        | counter  | Contagem de blocos assíncronos I/O                                      |
| docker\_container\_blkio.`io_serviced_recursive_discard`      | counter  | Contagem de solicitações de discard de dispositivos de bloco atendidos. |
| docker\_container\_blkio.`io_serviced_recursive_read`         | counter  | Contagem de leituras de dispositivos de bloco.                          |
| docker\_container\_blkio.`io_serviced_recursive_sync`         | counter  | Número de operações  de I/O de bloco síncrono.                          |
| docker\_container\_blkio.`io_serviced_recursive_total`        | counter  | Contagem de todos os blocos de I/O.                                     |
| docker\_container\_blkio.`io_serviced_recursive_write`        | counter  | Número de operações  de gravações para bloquear dispositivos            |


[title] SLAs
[path] AIOPS/AIOPS/

A plataforma AIOPS permite a configuração de informações de SLA para diferentes iniciativas como Serviço de TI, Incidentes, Uptime e etc.

## Incidentes

Para configuração de SLAs para incidentes é possível acessar a tela de ajustes na funcionalidade de configurações no AIOPS e após isso utilizar a opção de configurações de organização.

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/61dLdJEOFqiOTgB4V1sNn_screen-shot-2021-06-16-at-175741.png)

## Uptime

Através do Atmos, é possível definir horários de atentimento para que possa haver cálculos para dashboards interativas onde é possível acompanhar SLAs, e também para o cálculo de SLAs na funcionalidade de serviço de TI. O uptime pode ser utilizado para acompanhamento de qualquer serviço, seja externo via canais ou interno via dashboards, que precise ser gerenciado.

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/WzKhUpiAK2c4WuGycBkNA_screen-shot-2021-06-16-at-180221.png)






[title] Disk
[path] AIOPS/MÉTRICAS/Explorar as Métricas/

Coleta métricas sobre o uso do disco.

Observe que `used_percent` é calculado fazendo `used`/(`used` + `free`), não `used`/ `total`.

| **Chave**           | **Tipo** | **Descrição**                                        |
| ------------------- | -------- | ---------------------------------------------------- |
| disk.`free`         | bytes    | Espaço livre nos discos.                             |
| disk.`inodes_free`  | counter  | Número de nós de índice disponíveis no disco.        |
| disk.`inodes_total` | counter  | Número total de nós de índice reservados no disco.   |
| disk.`inodes_used`  | counter  | Número de nós de índice usados no disco.             |
| disk.`total`        | bytes    | Total de espaço nos discos, incluindo usado e livre. |
| disk.`used`         | bytes    | Espaço usado nos discos.                             |
| disk.`used_percent` | percent  | Percentual do total de espaço em disco que é usado.  |


[title] Listen Process
[path] AIOPS/MÉTRICAS/Explorar as Métricas/

Informações do PID do processo.

| **Chave**                    | **Tipo** | **Descrição**                                                                                                                          |
| ---------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| listen\_process.`pid`        | string   | Propriedade retorna o PID do processo.                                                                                                 |
| listen\_process.`ppid`       | string   | Propriedade retorna o PID do pai do processo atual.                                                                                    |
| listen\_process.`started_at` | date     | Última vez que o aplicativo foi iniciado.                                                                                              |
| listen\_process.`uptime`     | integer  | O método retorna o número de segundos que o processo  atual está em execução.<br /><br />O valor de retorno inclui frações de segundo. |


[title] Manuntenções
[path] AIOPS/ATMOS/

O Atmos permite a configuração e agendamento das rotinas de manutenção de forma simples e completa.

O agendamento de manutenção tem por objetivo suprimir alertas e incidentes gerados pelos servidores enquanto os mesmo passam por procedimentos de reparo ou desligamento programado, assim não afetando a disponibilidade e SLA dos serviços relacionados.

### Planos de Manutenção

Para iniciar o plano de Manutenção, acesse o botão planejamento na coluna lateral esquerda da tela:

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/XLgdulGwbTvlgTGcd2peg_Screen%20Shot%202021-01-10%20at%2018.33.48.png" size="10" caption="Botão Planejamento" position="center" showCaption="true"}

Após o acesso uma tela estará disponível possibilitando planejar as manutenções, através do botão Planos de Matutenção que se encontra logo acima na coluna equerda da tela.&#x20;

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/DjDgeHXRDkPH0rD_352mH_Screen%20Shot%202021-01-10%20at%2018.43.14.png" size="30" caption="Botão de acesso aos Planos de  Manutenção" position="center" showCaption="true"}

Ao clicar em Planos de Manutenção, a plataforma disponibilizará o acesso à todos os pnajementos já realizados, podendo estes serem filtrados em: todos, ativos e inativos.&#x20;

![](https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/FeR3HdSUTBksyR3coIKRt_Screen%20Shot%202021-01-10%20at%2018.38.33.png)

Na tela de listagem dos Planejamentos estará disponível um botão para criação de uma nova manutenção, que por sua vez abrirá um modal contendo a descrição geral do agendamento.

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/r_EnkiCItCm4exP96orlf_Screen%20Shot%202021-01-10%20at%2018.49.47.png" size="22" position="center" showCaption="false"}

![](https://gblobscdn.gitbook.com/assets%2F-Ls76-8XbGuboSQAg3Y9%2F-LsMWnkImfsn_AnKaR2U%2F-LsM_9A-PSKjZk-Un_X9%2FCaptura%20de%20Tela%202019-10-29%20a%CC%80s%2010.51.13.png?alt=media\&token=fafa7b29-79bd-4f90-b3c5-fb401b77522e "Descrição geral do agendamento")

A funcionalidade permite selecionar data e horário específicos, rotinas diárias e/ou semanais, sendo possível selecionar apenas quais dias da semana o procedimento de manutenção ocorrerá.

::Image[]{src="https://gblobscdn.gitbook.com/assets%2F-Ls76-8XbGuboSQAg3Y9%2F-LsMWnkImfsn_AnKaR2U%2F-LsM_E1LWC3RYoiGKW53%2FCaptura%20de%20Tela%202019-10-29%20a%CC%80s%2010.52.12.png?alt=media&token=05aa0575-e3ba-4a2b-a250-a8962442c3e7" size="80" showCaption="false"}

### Definindo períodos de programação

Ao selecionar os ICs que estarão em manutenção, você garante que todos os serviços, aplicações e recursos relacionados ao mesmo serão englobados pelo agendamento e portanto não terão sua disponibilidade alterada dentro do período programado.

::Image[]{src="https://gblobscdn.gitbook.com/assets%2F-Ls76-8XbGuboSQAg3Y9%2F-LsMWnkImfsn_AnKaR2U%2F-LsM_Fe5fmng485-hpKf%2FCaptura%20de%20Tela%202019-10-29%20a%CC%80s%2010.53.22.png?alt=media&token=57e829fd-86cb-437c-925b-f48948761baa" size="80" showCaption="false"}

ICS associados à manutenção

[title] Métricas
[path] AIOPS/ATMOS/

É possível checar todas a métricas coletadas em seu ambiente através do painel de configuração do Atmos:&#x20;

## Acesso&#x20;

Para acessar a aplicação Atmos é necessário clicar no botão "aplicações" localizado no canto inferior esquerdo, do menu principal no AIOPS.

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/_dl2iGnL-Fm4SOb1vBfhr_image.png" size="46" position="center" showCaption="false"}

Após acessar o Atmos é necessário acessar a tela de configurações através do menu principal:

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/J603Y2-yVEtAOB1qlER-r_image.png" size="46" position="center" showCaption="false"}

Ao acessar a tela de infraestrutura será possível ver selecionar a opção "Métricas" (disponível no menu interno ao lado esquerdo) e acessar as métricas disponíveis:

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/Er86_R-iT7hhE2uzHMNKq_image.png "Listagem de métricas disponíveis no ambiente")


[title] Automação (Pipes)
[path] AIOPS/AIOPS/Compartilhamento Automático/

Compartilhamento Automático utilizando Pipes de Automação.

## Criação do Auto Compartilhamento

Acessar a opção de configurações no menu principal do AIOPS:

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/2x7J3LFFnjoOSde1WNTOt_botaoconfiguracoes.png" size="36" position="flex-start" showCaption="false"}

No menu lateral escolha a opção **Auto Compartilhamento**:

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/u9p2-1Q_MH68GkLMX4JYz_captura-de-tela-2021-03-31-as-131027.png" size="40" position="center" showCaption="false"}

Você poderá criar um novo compartilhamento ou alterar um já existente. Para criar um novo você irá definir o **Ambiente** (utilizado para direcionar os alertas deste canal) e o **Tipo** escolhendo a opção de **Pipe**.

![](https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/Yli78RSr0RUC_La2mcCf-_doc-type-select.png)

Aparecerá no campo **Pipes** uma lista de opções disponíveis (criadas anteriormente no Atmos)

![](https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/G8oxOMCwHFpHdK9ZYctS-_doc-pipe-select.png "Escolha do Pipe para Automação")

Quando um pipe for selecionado a aba **Outlines** ficará disponível para atribuição das variáveis disponíveis no item selecionado.

Os outlines são parâmetros customizáveis que um pipe pode receber para a sua execução. Saiba mais acessando o menu de Pipes e Automação.

![](https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/ngwupF9dTNLYoQn9jU92y_doc-outline-list.png "Configuração de Outlines")

Para definir o Outline, acesse o botão **Novo Outline**.&#x20;

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/S_eLxGn6TjxKV5sGv2l9o_doc-btn-add-outline.png" size="26" position="flex-start" showCaption="false"}

Dentro da janela que aparecerá, escolha a **Chave** da variável do Pipe e defina o **Valor** desejado.

![](https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/navQaSmL3H4yu7VKRphkH_doc-new-outline.png "Janela de definição do outline")


[title] Zones
[path] AIOPS/INTRODUÇÃO/

Abaixo relacionamos as instâncias (nós) do AIOPS, as Zonas de conexão, detalhes dos serviços, portas e diagramas.

***

# Instâncias

### 01.  MASTER-NODE

Instância Principal – Responsável por orquestrar os serviços essenciais do AIOPS.

### 02.  DB-WORKER

Instância do Banco Analítico.

### 03.  ATOM-WORKER (ML-WORKER)

Instância responsável por distribuir a coleta de dados e descoberta de rede (*via* *SNMP*, *Ping ICMP*, etc.). Treinamento distribuído de modelos de (IA), operando em conjunto com a ***MASTER-NODE***.

### 04.  APM-WORKER

Instância do Divedot (Application Performance Monitoring).

***

# Regras por Zonas

São 3 as principais zonas de conectividade do AIOPS, utilize-as para criação das regras de firewall.

- AIOPS **Zone***&#x20;(obrigatório)*
  - Contempla todas as instâncias do AIOPS;
  - Acesso liberado para todas as portas / protocolos entre as máquinas desta zona.
  - Acesso para portas específicas (para se conectar fora da Zone);
  - Compatibilidade com IPV4 e IPV6
- **Private Zone***&#x20;(obrigatório)*
  - Compreende toda a rede privada a ser monitorada;
  - Descoberta de Rede (*Agent Probe*);
  - Ping / Coleta das Métricas SNMP;
  - Envio de métricas (a partir dos hosts com agent);
  - Testes Web em aplicações dentro da rede privada.
- **Public Internet***&#x20;(opcional)*
  - Acesso às aplicações do AIOPS;
  - Testes Web em aplicações públicas;
  - Envio de dados das páginas web / aplicativos;
  - Envio de dados de serviços externos e/ou de outro datacente&#x72;*;*
  - Acesso originados de Itens Externos / Cloud, ex.: *IBM, AWS, Azure, OpenShift, etc. (opcional).*

![](https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/TQAzboeP_V4kZwNbvQn7m_firewall-zones.png)

***



# Diagrama do Sphere Agent

O *Sphere Agent* sobe a porta ***10081*** nos hosts instalados, o acesso à essa porta deverá ser liberado  para a instância ***MASTER-NODE**. Caso opte por* apontar o agent para o *HTTP Proxy* adicione à configuração do agent `path: /sphere-sync`.&#x20;

![](https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/qZOcmC9OK4zXwWu7LEja1_diagram-sphere-agent.png "Diagrama de comunicação do Sphere Agent. Toque na imagem para ampliar")

:::hint{type="info"}
## Segurança

A porta do agent (10081) utiliza o protocolo GRPC e criptografia e não transporta dados/scripts. Ela é responsável por receber sensores binários de Healthcheck e Automação.
:::

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/s6N9LumoAkz-6dISJn8fA_legend-simon-connections.png" size="68" caption="Legenda das Conexões" position="center" showCaption="true"}

***

# Diagrama do Agent Probe

O *Agent Probe* realiza a Descoberta de Rede, Ping (ICMP), Coleta de Dados / Traps SNMP.

![](https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/9cqVckGRShFaJ2y9miDYT_diagram-agent-probe.png "Diagrama de comunicação do Agent Probe. Toque na imagem para ampliar")



***

# Portas e Serviços por Instância

Portas e serviços que estão expostos ***para fora da Zone***, sendo assim, foram omitidos as portas e serviços internos (que são exclusivas da *Zone)*.

| **Instância** | **Descritivo**                | **Porta (obrigatória)** | **Porta (opcional)**                                     |
| ------------- | ----------------------------- | ----------------------- | -------------------------------------------------------- |
| 01-MASTER     | HTTP Proxy                    | **80** / **443**        | --                                                       |
| 01-MASTER     | Sphere Sync - Agent Collector | --                      | **18001**                                                |
| 02-DB         | HTTP Proxy                    | **80**                  | --                                                       |
| 04-APM        | HTTP Proxy                    | **80** / **443**        | --                                                       |
| 04-APM        | Trace Sync - APM Collector    | --                      | **8090** (tcp)**, 8125&#x20;**(udp)**, 8126&#x20;**(tcp) |



## Proxy dos coletores (portas opcionais)

Ao apontar os coletores para o AIOPS (Agents/APM) é necessário configurar a URL corretamente, utilize a referência abaixo para a devida configuração.

| **Instância** | **Descritivo** | **Porta original** | **Porta do Proxy&#x20;** | **Adicionar à URL (path)** |
| ------------- | -------------- | ------------------ | ------------------------ | -------------------------- |
| 01-MASTER     | Sphere Sync    | **18001**          | **80** ou **443**        | /sphere-sync               |
| 04-APM        | Trace Sync     | **8090**           | **80** ou **443**        | /\_ddsite                  |

***

## Restrição de portas na Zone

Caso não seja possível liberar todas as portas entre as máquinas do AIOP&#x53;*&#x20;(Zone)&#x20;*&#x73;erá necessário adicionar no mínimo as seguintes regras entre os nós:

| **ORIGEM**     | **DESTINO**    | **PORTAS DESTINO**                                                              |
| -------------- | -------------- | ------------------------------------------------------------------------------- |
| 01-MASTER-NODE | 02-DB-WORKER   | TCP: **8086, 8428, 9095, 3100, 9080**<br />UDP: **514**                         |
| 01-MASTER-NODE | 03-ATOM-WORKER | TCP: **80,** **19000, 19200**                                                   |
| 01-MASTER-NODE | 04-APM-WORKER  | TCP: **8090, 8123**, **8126,** **9000**, **9092**, **29092**<br />UDP: **8125** |

| **ORIGEM**            | **DESTINO**    | **PORTAS DESTINO**          |
| --------------------- | -------------- | --------------------------- |
| *Todas as instancias* | 01-MASTER-NODE | TCP: **80, 443,** **18001** |

:::hint{type="warning"}
Atenção para as portas que estão exclusivamente nos protocolos **TCP** ou **UDP**.
:::

# Backups&#x20;

O AIOPS possui rotinas automatizadas de backup, garantindo assim a capacidade de recuperação a desastres seja a nível de base de dados, usuários, configurações e métricas que permeiam toda a plataforma do AIOPS.

# Auditlog

O AIOPS possui por padrão, funcionalidade de mensageria que permite a auditoria e acompanhamento das informações de todos os eventos que acontecem no escopo de toda a plataforma, contemplando usuários, configurações, CRUDs e métricas, para uma visão holística de todos os módulos que contemplam a solução.&#x20;



# Criptografia

O AIOPS utiliza protocolos remotos para a captura de transações. Por padrão, utilizamos a comunicação HTTPS (SSL)  para requisições web e é possível alternar o protocolo para HTTP não seguro manualmente por meio dos arquivos de configuração, a critério do cliente.
Para as automações e comunicação via agent, o AIOPS utiliza o protocolo GRPC e não transporta dados/scripts executáveis, é responsável por receber informações de sensores binários, healthcheck e automação.

### Layer de storage de informações sensíveis


Os usuário do AIOPS possuem todos os dados sensíveis salvos em um banco de dados comportando senhas criptografadas.

Essas informações confidenciais são criptografadas usando criptografia Triple-DES. A chave usada para criptografia é exclusiva para cada usuário, garantindo que os dados não possam ser descriptografados por um usuário diferente e uma máquina diferente.

**Criptografia: Symmetric Triple-DES (168 bits)**

DES triplo é o nome da cifra de bloco do algoritmo de criptografia triplo de dados (um algoritmo determinístico operando em grupos de bits de comprimento fixo) que aplica o algoritmo de cifra Padrão de criptografia de dados (DES) três vezes a cada bloco de dados.&#x20;












[title] Docker Container Net
[path] AIOPS/MÉTRICAS/Explorar as Métricas/

Este plugin coleta métricas sobre a rede de um contêiner docker.

| **Chave**                                      | **Tipo** | **Descrição**                               |
| ---------------------------------------------- | -------- | ------------------------------------------- |
| docker\_container\_ne&#x74;**.**`container_id` | string   | ID do contêiner.                            |
| docker\_container\_ne&#x74;**.**`rx_bytes`     | bytes    | Número total de bytes recebidos.            |
| docker\_container\_ne&#x74;**.**`rx_dropped`   | counter  | Número total de pacotes recebidos perdidos. |
| docker\_container\_ne&#x74;**.**`rx_errors`    | counter  | Total de erros nos pacotes recebidos.       |
| docker\_container\_ne&#x74;**.**`rx_packets`   | counter  | Número total de pacotes recebidos.          |
| docker\_container\_ne&#x74;**.**`tx_bytes`     | bytes    | Número total de bytes enviados.             |
| docker\_container\_ne&#x74;**.**`tx_dropped`   | counter  | Número total de pacotes enviados perdidos.  |
| docker\_container\_ne&#x74;**.**`tx_errors`    | long     | Total de erros em pacotes enviados.         |
| docker\_container\_ne&#x74;**.**`tx_packets`   | long     | Número total de pacotes enviados.           |


[title] Scanner de ativos
[path] AIOPS/ATMOS/Hosts/

O AIOPS oferece recursos avançados de scanner de ativos, permitindo que você tenha controle total sobre diferentes tipos de equipamentos de rede, máquinas de usuários finais e sistemas operacionais em diversos ambientes, como cloud (AWS, Google Cloud, Azure, Tencent), híbrido e infraestrutura própria.

## Varredura de Ativos de Rede, Servidores e Endpoints

O AIOPS é capaz de descobrir uma ampla variedade de ativos, incluindo equipamentos de rede, máquinas de usuários finais e componentes de datacenter. Essa capacidade abrangente permite que você tenha uma visão precisa do inventário de ativos de TI em sua organização.

### Equipamentos de Rede

O AIOPS é capaz de descobrir e rastrear equipamentos de rede, como roteadores, switches, firewalls, access points e dispositivos especializados. Isso permite um gerenciamento eficiente de sua infraestrutura de rede e ajuda a identificar e solucionar problemas de conectividade.

### Máquinas de Usuários Finais

Com o AIOPS, você pode descobrir e monitorar máquinas de usuários finais, como notebooks e PCs. Isso permite o rastreamento de ativos, gerenciamento de licenças de software e identificação de necessidades de atualização de hardware.

### Componentes de Datacenter

O AIOPS também oferece a capacidade de descobrir e rastrear componentes essenciais de datacenter, como storage, ambientes de virtualização e servidores físicos. Isso permite um gerenciamento abrangente de seus ativos de TI, garantindo a disponibilidade e o desempenho adequado de sua infraestrutura crítica.

### Suporte a Diferentes Sistemas Operacionais

O AIOPS é compatível com uma ampla gama de sistemas operacionais, garantindo a descoberta de ativos em diversos ambientes. Além dos sistemas operacionais populares, como Windows, Linux, Solaris e Unix o AIOPS também oferece suporte a outros sistemas operacionais, incluindo:

- AIX: Sistema operacional Unix desenvolvido pela IBM, utilizado em servidores de alto desempenho e missão crítica.
- HP-UX: Sistema operacional Unix desenvolvido pela Hewlett Packard Enterprise (HPE), amplamente utilizado em servidores HP Integrity e HP 9000.
- macOS: Sistema operacional utilizado em computadores Apple, permitindo a descoberta de ativos em ambientes macOS.
- FreeBSD: Sistema operacional de código aberto baseado em Unix, amplamente utilizado em servidores e ambientes de rede.
- CentOS: Distribuição Linux baseada no código-fonte do Red Hat Enterprise Linux, oferecendo suporte a servidores e infraestruturas críticas.
- Ubuntu: Distribuição Linux popular, conhecida por sua facilidade de uso e ampla comunidade de usuários.
- Debian: Outra distribuição Linux amplamente utilizada, oferecendo estabilidade e flexibilidade para diversos ambientes.
- IBM i: Sistema operacional da IBM para servidores de médio porte, fornecendo recursos avançados para ambientes corporativos.
- z/OS: Sistema operacional mainframe da IBM, utilizado em ambientes de grande escala que exigem alta disponibilidade e desempenho.

Com essa ampla compatibilidade de sistemas operacionais, o AIOPS permite que você descubra, monitore e gerencie ativos em uma variedade de plataformas, garantindo uma visão completa e precisa do seu inventário de ativos de TI.

### Descoberta em Ambientes Cloud, Híbridos e Infraestrutura Interna

O AIOPS oferece suporte completo a diferentes tipos de ambientes, incluindo cloud, híbrido e infraestrutura interna. Com a capacidade de descobrir ativos em provedores de nuvem populares, como AWS, Google Cloud, Azure e Tencent, você pode rastrear e gerenciar recursos na nuvem de forma eficiente. Além disso, o AIOPS é altamente adaptável a ambientes híbridos, permitindo que você tenha visibilidade tanto em ativos locais quanto na nuvem. Por fim, a solução também é capaz de descobrir e monitorar ativos em sua própria&#x20;

Além da descoberta de equipamentos de rede, máquinas de usuários finais e sistemas operacionais, o AIOPS também oferece recursos avançados de descoberta de virtualização e ambientes de container. Essa funcionalidade permite que você tenha visibilidade e controle sobre os ativos virtualizados e em containers em sua infraestrutura de TI.

### Virtualização

O AIOPS é capaz de descobrir e rastrear servidores de virtualização, como VMware ESXi, Microsoft Hyper-V, Citrix XenServer, entre outros. Isso inclui a identificação de hosts, máquinas virtuais, clusters e outros componentes relacionados à virtualização. Com essa capacidade, você pode acompanhar o inventário de ativos virtualizados e monitorar o desempenho e a utilização dos recursos em seu ambiente de virtualização.

### Ambientes de Container

O AIOPS também oferece suporte à descoberta de ambientes de container, como Docker e Kubernetes. Ele pode identificar os clusters, nós e os próprios containers em execução. Essa funcionalidade permite que você tenha visibilidade do inventário de ativos em ambientes de container, facilitando o gerenciamento e a monitoração de seus recursos de forma granular.

Com a descoberta de virtualização e ambientes de container, o AIOPS oferece uma visão completa de seus ativos de TI, incluindo equipamentos físicos, máquinas virtuais e containers. Isso permite uma gestão mais eficiente, uma melhor utilização de recursos e a identificação rápida de possíveis problemas nessas camadas de virtualização.

## Identificação de Aplicações e Bancos de Dados

Além da descoberta de equipamentos de rede, máquinas de usuários finais, sistemas operacionais e virtualização, o AIOPS também oferece recursos avançados de descoberta de aplicações e bancos de dados através de retroalimentação com o Divedot. Essa funcionalidade abrangente permite que você tenha visibilidade e controle sobre suas aplicações e recursos de banco de dados em sua infraestrutura de TI.

### Aplicações

O AIOPS é capaz de identificar as aplicações em seu ambiente de TI. Ele pode detectar automaticamente as aplicações instaladas em seu ambiente, fornecendo informações detalhadas sobre os sistemas, versões e configurações. Com essa funcionalidade, você pode gerenciar e monitorar suas aplicações de forma eficiente, identificando possíveis problemas, analisando a utilização de recursos e garantindo a conformidade com as políticas da organização, sendo posssível identificar  identificar webservices, endpoints, rotinas e outros recursos específicos das aplicações. Isso permite uma visão mais completa e detalhada do ecossistema.

Além disso, o AIOPS pode rastrear rotinas e recursos específicos das aplicações, permitindo que você entenda melhor a estrutura e o funcionamento interno de suas aplicações. Isso inclui a identificação de bibliotecas, classes, funções e stacks de erros e outros elementos relacionados às suas aplicações.

### Bancos de Dados

O AIOPS oferece recursos avançados para a descoberta de bancos de dados em sua infraestrutura de TI. Ele pode identificar diferentes tipos de bancos de dados, como Oracle, MySQL, Microsoft SQL Server, PostgreSQL, MongoDB, entre outros. O AIOPS fornece informações detalhadas sobre os bancos de dados encontrados, incluindo versões, configurações, tamanhos e estatísticas de desempenho. Com essa funcionalidade, você pode gerenciar e monitorar seus bancos de dados de forma eficaz, otimizando o desempenho, garantindo a segurança dos dados e facilitando a administração de suas bases de dados.


[title] Application Performance Management
[path] AIOPS/DIVEDOT/

Visualize toda sua infraestrutura de aplicação, identificando gargalos, falhas, lentidões e o comportamento dos usuários.

O Divedot tem uma abordagem integrada de observação por meio de análises de contextos e desempenho das aplicações.

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/PpJWe20byMwgmRKsAOjzu_capturadivedot65a.PNG)

Suporta o gerenciamento de aplicações e serviços críticos disponibilizando:

- Tempo de resposta;
- Consumo de CPU e memória por aplicação;
- Gerenciamento inteligente das sessões (requisições, filas, exceções e conexões com o banco de dados);

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/wBjYjy7a1AdptDBiztYax_capturadivedot65ausuario.PNG)

- Gerenciamento integrado da infraestrutura (consumo de rede - throughput, latência, locks em databases);
- Mapeamento de dependências entre os serviços

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/sTG2CMlUlvodbckT57ulc_capturadivedot65alock-de-banco.PNG)

- Dashboard customizado por aplicação.

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/_Ma7YfO_x6vILtBKtYrSL_capturadivedot65aservico.PNG)

- Descoberta automática da topologia da aplicação.

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/hcro8MyXATeWSDXy9fpv4_image.png)


[title] Escalas
[path] AIOPS/AIOPS/

Criação de escalas para gerência de execução de notificações e pipes.

## Criação da escala:

Acessar a opção de configurações no menu principal do AIOPS:

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/DB21YU7NtmTsb-aPoWdvQ_2x7j3lffnjoosde1wntotbotaoconfiguracoes.png" size="34" width="160" height="38" position="center" showCaption="false"}

No menu lateral escolha a opção **Escala**.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/6nDP0BQgXrI3U6LTnUaSG_image.png" size="50" width="232" height="159" position="center" showCaption="false"}

Você poderá criar uma nova escala ou alterar um já existente.&#x20;

Ao criar uma nova escala, na aba **Geral** defina um nome (obrigatório) e uma descrição (opcional).

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/5A2ab26KDnvymYjn4NnR5_image.png)

Em seguida na aba **Hosts&#x20;**&#x65;scolha os **Itens de Configuração&#x20;**&#x71;ue farão parte desta escala:

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/HGeQV-_uc0UCVj3Xp10AL_image.png "Definição dos hosts")

Na aba **Notificações&#x20;**&#x63;rie as regras para notificação de usuários.

- **Trigger da notificação:**
  - Novo incidente - Notifica o usuário quando um novo incidente for criado.&#x20;
  - Conclusão do incidente - Notifica o usuário quando um incidente for concluído.&#x20;
  - Pipe disponível - Notifica o usuário quando um novo pipe estiver disponível.&#x20;
- **Aguardar:** Quanto tempo deve-se aguardar antes do disparo das notificações.
- **Integração:** Qual integração de notificação será utilizada.
- **Destinatários:&#x20;**&#x51;uais usuários ou times serão notificados.

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/62kPeI9rxeZGwH9uVxzNh_image.png)

Na seção **Execução de Pipes**, você pode realizar as configurações destinadas à execução:

- **Executar pipes quando disponíveis:** Habilita/Desabilita a execução automática.
  - **Executar após:** Definição do tempo de espera da execução automática após um novo alerta ser criado.
- **Notificar:**
  - **Antes da execução:&#x20;**&#x45;nvia uma mensagem antes da execução ser iniciada.
  - **Após a execução:** Envia uma mensagem quando a automação for concluída.
  - **Destinários:** Opcionalmente poderá definir quem receberá as notificações da execução de pipes.

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/DrG4BYyXYxHFmNsMAmqa-_image.png)


[title] Docker Container Mem
[path] AIOPS/MÉTRICAS/Explorar as Métricas/

| **Chave**                                          | **Tipo** | **Descrição**                                                                                                                                                                                                                                                                                         |
| -------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| docker\_container\_mem.`active_anon`               | byte     | Cache anônimo e de troca na lista ativa de menos usados ​​recentemente (LRU), incluindo tmpfs( shmem), em bytes                                                                                                                                                                                       |
| docker\_container\_mem.`active_file`               | byte     | memória com backup de arquivo na lista LRU ativa, em bytes                                                                                                                                                                                                                                            |
| docker\_container\_mem.`cache`                     | byte     | cache de página, incluindo tmpfs( shmem), em bytes                                                                                                                                                                                                                                                    |
| docker\_container\_mem.`container_id`              | string   | Container ID                                                                                                                                                                                                                                                                                          |
| docker\_container\_mem.`hierarchical_memory_limit` | byte     | Limite de memória para a hierarquia que contém o memorycgroup, em bytes                                                                                                                                                                                                                               |
| docker\_container\_mem.`inactive_anon`             | byte     | Cache anônimo e de troca na lista LRU inativa, incluindo tmpfs( shmem), em bytes                                                                                                                                                                                                                      |
| docker\_container\_mem.`inactive_file`             | byte     | Memória com backup de arquivo na lista LRU inativa, em bytes                                                                                                                                                                                                                                          |
| docker\_container\_mem.`max_usage`                 | byte     | Uso máximo de memória registrado                                                                                                                                                                                                                                                                      |
| docker\_container\_mem.`pgfault`                   | counter  | Número de falhas de página, em que o kernel deve alocar e inicializar a memória física para uso no espaço de endereço virtual de um processo.                                                                                                                                                         |
| docker\_container\_mem.`pgmajfault`                | counter  | Número de falhas de página principais, em que o kernel precisa liberar ativamente a memória física antes da alocação e inicialização.                                                                                                                                                                 |
| docker\_container\_mem.`pgpgin`                    | counter  | Número de páginas paginadas de memória.                                                                                                                                                                                                                                                               |
| docker\_container\_mem.`pgpgout`                   | counter  | Número de páginas paginadas da memória.                                                                                                                                                                                                                                                               |
| docker\_container\_mem.`rss`                       | byte     | Tamanho em bytes do cache anônimo e de troca (não inclui tmpfs). <br /><br />O tamanho real do conjunto residente é dado pela soma de rss e mapped\_file.                                                                                                                                             |
| docker\_container\_mem.`rss_huge`                  | byte     | Número de bytes de enormes páginas anônimas transparentes.                                                                                                                                                                                                                                            |
| docker\_container\_mem.`total_active_anon`         | counter  | Soma de todos os filhos `active_anon`                                                                                                                                                                                                                                                                 |
| docker\_container\_mem.`total_active_file`         | counter  | Soma de todos os filhos `active_file`                                                                                                                                                                                                                                                                 |
| docker\_container\_mem.`total_cache`               | counter  | Soma do `cache` de todos os filhos                                                                                                                                                                                                                                                                    |
| docker\_container\_mem.`total_inactive_anon`       | counter  | Soma de todos os filhos `inactive_file`                                                                                                                                                                                                                                                               |
| docker\_container\_mem.`total_inactive_file`       | counter  | Soma de todos os filhos `inactive_file`                                                                                                                                                                                                                                                               |
| docker\_container\_mem.`total_mapped_file`         | counter  | Soma do `cache` de todos os filhos                                                                                                                                                                                                                                                                    |
| docker\_container\_mem.`total_pgfault`             | counter  | Indica o número de vezes que um processo do cgroup acionou uma "falha de página". <br /><br />Uma falha de página ocorre quando um processo acessa uma parte de seu espaço de memória virtual que é inexistente ou protegido                                                                          |
| docker\_container\_mem.`total_pgmajfault`          | counter  | Indique o número de vezes que um processo do cgroup disparou uma "falha grave". <br /><br />Falhas "maiores" acontecem quando o kernel realmente precisa ler os dados do disco.                                                                                                                       |
| docker\_container\_mem.`total_pgpgin`              | counter  | Soma de todos os filhos `pgpgin`                                                                                                                                                                                                                                                                      |
| docker\_container\_mem.`total_pgpgout`             | counter  | Soma de todos os filhos `pgpgout`                                                                                                                                                                                                                                                                     |
| docker\_container\_mem.`total_rss`                 | counter  | Quantidade de memória que não corresponde a nada no disco: pilhas, pilhas e mapas de memória anônimos                                                                                                                                                                                                 |
| docker\_container\_mem.`total_rss_huge`            | counter  | Soma de todos os filhos `pgpgout`                                                                                                                                                                                                                                                                     |
| docker\_container\_mem.`total_unevictable`         | byte     | Quantidade de memória que não pode ser recuperada; geralmente, ele levará em conta a memória que foi "bloqueada" com mlock. <br /><br />É frequentemente usado por estruturas de criptografia para garantir que as chaves secretas e outros materiais confidenciais nunca sejam trocados para o disco |
| docker\_container\_mem.`total_writeback`           | byte     | Indica a quantidade de memória que foi gravada de volta neste contêiner.                                                                                                                                                                                                                              |
| docker\_container\_mem.`unevictable`               | byte     | Indica a quantidade de memória que não pode ser recuperada por este contêiner.                                                                                                                                                                                                                        |
| docker\_container\_mem.`usage`                     | byte     | Uso de memória em bytes                                                                                                                                                                                                                                                                               |
| docker\_container\_mem.`usage_percent`             | byte     | Uso de memória como uma porcentagem da memória total disponível                                                                                                                                                                                                                                       |
| docker\_container\_mem.`writeback`                 | byte     | Indica a quantidade de memória que foi gravada de volta neste contêiner.                                                                                                                                                                                                                              |


[title] JMX | JVM (Jolokia)
[path] AIOPS/MÉTRICAS/Explorar as Métricas/

O agent Jolokia e os plugins de entrada de proxy coletam métricas JMX de um endpoint HTTP usando o protocolo JSON-over-HTTP da Jolokia.

# Configuração

## Plugin Base

### Jolokia2 Proxy Input

:::CodeblockTabs
Plugin Telegraf

```shell
# Read JMX metrics from a Jolokia REST proxy endpoint
[[inputs.jolokia2_proxy]]
  # default_tag_prefix      = ""
  # default_field_prefix    = ""
  # default_field_separator = "."

  ## Proxy agent
  url = "http://localhost:8080/jolokia"
  # username = ""
  # password = ""
  # response_timeout = "5s"

  ## Optional TLS config
  # tls_ca   = "/var/private/ca.pem"
  # tls_cert = "/var/private/client.pem"
  # tls_key  = "/var/private/client-key.pem"
  # insecure_skip_verify = false

  ## Add proxy targets to query
  # default_target_username = ""
  # default_target_password = ""
  [[inputs.jolokia2_proxy.target]]
    url = "service:jmx:rmi:///jndi/rmi://targethost:9999/jmxrmi"
    # username = ""
    # password = ""

  ## Add metrics to read
  [[inputs.jolokia2_proxy.metric]]
    name  = "java_runtime"
    mbean = "java.lang:type=Runtime"
    paths = ["Uptime"]
```
:::

### Jolokia2 Agent

:::CodeblockTabs
Plugin Telegraf

```shell
# Read JMX metrics from a Jolokia REST agent endpoint
[[inputs.jolokia2_agent]]
  # default_tag_prefix      = ""
  # default_field_prefix    = ""
  # default_field_separator = "."

  # Add agents URLs to query
  urls = ["http://localhost:8080/jolokia"]
  # username = ""
  # password = ""
  # response_timeout = "5s"

  ## Optional TLS config
  # tls_ca   = "/var/private/ca.pem"
  # tls_cert = "/var/private/client.pem"
  # tls_key  = "/var/private/client-key.pem"
  # insecure_skip_verify = false

  ## Add metrics to read
  [[inputs.jolokia2_agent.metric]]
    name  = "java_runtime"
    mbean = "java.lang:type=Runtime"
    paths = ["Uptime"]
```
:::

## Métricas

Cada declaração gera uma request Jolokia para buscar a métrica.

| Chave             | Requerido | Descrição                                                                                                                                                                                         |
| ----------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **mbean**         | Sim       | O nome do objeto de um JMX MBean. Os valores de chave de propriedade do MBean podem conter um *wildcard* (**\***), permitindo que você busque vários MBeans.                                      |
| **paths**         | Não       | Uma lista de atributos MBean a serem lidos.                                                                                                                                                       |
| **tag\_keys**     | Não       | Uma lista de nomes de chave de propriedade MBean para converter em tags. O nome da chave da propriedade se torna o nome da tag, enquanto o valor da chave da propriedade se torna o valor da tag. |
| **tag\_prefix**   | Não       | Uma string para preceder os nomes de tag produzidos por esta declaração de métrica.                                                                                                               |
| **field\_name**   | Não       | Uma string a ser definida como o nome do campo produzido por esta métrica.                                                                                                                        |
| **field\_prefix** | Não       | Uma string para preceder os nomes de campo produzidos por esta declaração de métrica.                                                                                                             |

Use **paths** para refinar quais campos coletar.

:::CodeblockTabs
Exemplo de Configuração

```shell
[[inputs.jolokia2_agent.metric]]
  name  = "jvm_memory"
  mbean = "java.lang:type=Memory"
  paths = ["HeapMemoryUsage", "NonHeapMemoryUsage", "ObjectPendingFinalizationCount"]
```
:::

A declaração de métrica **jvm\_memory** anterior produz a seguinte saída:

:::CodeblockTabs
Exemplo de Saída

```shell
jvm_memory HeapMemoryUsage.committed=4294967296,HeapMemoryUsage.init=4294967296,HeapMemoryUsage.max=4294967296,HeapMemoryUsage.used=1750658992,NonHeapMemoryUsage.committed=67350528,NonHeapMemoryUsage.init=2555904,NonHeapMemoryUsage.max=-1,NonHeapMemoryUsage.used=65821352,ObjectPendingFinalizationCount=0 1503762436000000000
```
:::

Use wildcards (**\***) em valores de chave de propriedade **mbean** para criar séries distintas capturando valores em **tag\_keys**.

:::CodeblockTabs
Exemplo de Configuração

```shell
[[inputs.jolokia2_agent.metric]]
  name     = "jvm_garbage_collector"
  mbean    = "java.lang:name=*,type=GarbageCollector"
  paths    = ["CollectionTime", "CollectionCount"]
  tag_keys = ["name"]
```
:::

Como **name=\*** corresponde a **G1 Old Generation** e **G1 Young Generation**, e **name** é usado como uma **tag**, a declaração de métrica **jvm\_garbage\_collector** anterior produz duas métricas.

```shell
jvm_garbage_collector,name=G1\ Old\ Generation CollectionCount=0,CollectionTime=0 1503762520000000000
jvm_garbage_collector,name=G1\ Young\ Generation CollectionTime=32,CollectionCount=2 1503762520000000000
```

Para exemplos de configuração baseadas em *Servlets* produtivos, acesse:

[https://github.com/influxdata/telegraf/tree/master/plugins/inputs/jolokia2/examples](https://github.com/influxdata/telegraf/tree/master/plugins/inputs/jolokia2/examples)

[title] Agent Windows
[path] AIOPS/AIOPS/Inventário/Instalação dos Agents/


[title] Usuários
[path] AIOPS/AIOPS/

## Criando Usuários

Para a criação, seleção e distribuição de times responsáveis pelos incidentes, é necessário a inclusão de dados dos usuários que participam das equipes.

Em configurações presente na coluna lateral esquerda, basta selecionar o botão usuários para iniciar o cadastramento.



::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/2i2fkyJCUdZcYeVCBg9Sn_Screen%20Shot%202021-01-10%20at%2016.32.03.png" size="10" caption="Botão Configurações " position="center" showCaption="true"}

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/J3E6JWHUfhMLfjAhvDx_z_Screen%20Shot%202021-01-10%20at%2016.22.43.png" size="18" caption="Botão Usuários, encontra-se abaixo do botão Times em Pessoas" position="center" showCaption="true"}

Após a selecionar essa opção uma tela se abrirá contendo todos os usuários já cadastrados e possibitando o cadastros de novos profissionais, conforme necessidade de demandas.

No botão Novo Usuário é possível adicionar novos profissionais à plataforma.

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/GaiN9cdVTBQXCdni9AIBz_Screen%20Shot%202021-01-10%20at%2016.30.03.png" size="22" position="center" showCaption="false"}

Abaixo segue a tela disponível para a inserção de novos usuários, de acordo com o seu perfil e permissões dentro da plataforma

![](https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/lqoYbqMos5kBWx1D2e2tx_Screen%20Shot%202021-01-10%20at%2016.33.55.png)




[title] Pipes e Automação
[path] AIOPS/ATMOS/

O AIOPS possui a capacidade de criação de fluxos para automações simples e complexas, seja para autorecuperação ou execuções rotineiras, é possível utilizar a funcionalidade de "Pipes" para maximizar o potencial de sua equipe otimizando o tempo com tarefas recorrentes, potencializando as automações e extraindo o máximo de módulos que permitem infinitas combinações, suportados por IA.

## Acesso&#x20;

Para acessar a aplicação Atmos é necessário clicar no botão "aplicações" localizado no canto inferior esquerdo, do menu principal no AIOPS.

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/_dl2iGnL-Fm4SOb1vBfhr_image.png" size="34" position="center" showCaption="false"}

Após acessar o Atmos é necessário acessar a funcionalidade de Pipes através do menu principal (lateral esquerda):

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/i0iEn_oE_uRiq5zEyFc4j_image.png" size="30" position="center" showCaption="false"}

Então uma nova tela será exibida com a listagem dos fluxos criados:&#x20;

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/X629KGUIijGdrTGjejYGq_image.png" size="80" position="center" showCaption="false"}

## Criação de fluxos

Para criar novos fluxos é necessário clicar no botão:&#x20;

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/Y8PjM7MTtasOoKhYCCNLj_image.png" size="36" position="center" showCaption="false"}

Então uma nova tela para a criação de fluxos se apresentará:

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/OsuR5ztv9cuEjZDKp8Vbu_image.png" size="82" position="center" showCaption="false"}

&#x20;Nessa tela teremos do lado esquerdo:

- Aba de serviços
  - Nessa aba teremos vários bloquinhos representados ferramentas com as quais o atmos pode se comunicar para executar uma automação
- Aba de outlines
  - Nessa aba é possível definir variáveis globais que podem ser utilizadas nos pipes

### Selecionando serviços

Para utilizar os serviços disponíveis basta clicar em um item existente na aba de serviços e arrastar para a área cinza, dando início assim a criação de um fluxo:

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/FCWB_mH8oS51K33c3-h-D_image.png" size="54" caption="Exemplo de serviço selecionado" position="center" showCaption="true"}

Em cada componente termos a possibilidade de:

- Definir se é o ponto de início através do ícone da bandeira
- Executar a ação de remover atráves do botão de três pontos
- Selecionar um comando para a execução

### Configurando

Após realizar esses passos é possível executar um comando para execução, onde caso haja saídas possíveis para esse comando um novo botão será exibido:&#x20;



::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/lT61oK13NaYP3ra-kpyDs_image.png" size="54" caption="Componente com botões ativos" position="center" showCaption="true"}

Para cada script é possível exigir as configurações necessárias através do ícone de engrenagem:&#x20;

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/UruGweYoKSNfctQmNOwqh_image.png" size="14" position="center" showCaption="false"}

### Construindo fluxo

Além disso é possível também dar continuidade na execução do botão que possui o ícone de raio:

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/jDo3Pv7Bzz1ZiHDfiVR4m_image.png" size="88" position="center" showCaption="false"}

Nessa ação é possível arrastar e soltar as opções existentes no modal chamado de "flows" e criar fluxos que poderão ser conectados a outro componente de serviço simplesmente clicando e arrastando o botão de raio existente em um flow, como por exemplo:&#x20;



::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/d56Gdje__5fV3Uw1WUFt4_image.png" size="32" position="center" showCaption="false"}

Caso existe outro serviço, então a conexão poderá ser estabelecida:&#x20;

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/JgCHrnH21n0u_p4W_pEW4_image.png" size="82" position="center" showCaption="false"}

É possível acionar pipes através de agendamentos:&#x20;

[Agendamentos](docId\:U0_3xGd5RbDNj4TD6YBpj)&#x20;

Ou através de associação a alertas na tela de incidentes:&#x20;

[Atuação em Incidentes](docId:9atmwPHfLCwYdLhRXmJuR)&#x20;

## Integração e disponibilização API

Para realizar a disponibilização de um Pipe para integração e acesso por ferramentas externas, como scripts, RPAs, ITSMs e etc. você deve acessar a listagem e pipes e clicar no botão:

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/pbWwas18xYLiCg9SPMNvg_screen-shot-2021-06-17-at-103757.png" size="32" width="165" height="233" position="center" showCaption="false"}

Após permitir que esse pipe se torne público você conseguirá acessar às informações para as integrações que desejar realizar:

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/IWqpmBeqNnkksXOzmqSjA_screen-shot-2021-06-17-at-104149.png" size="70" width="663" height="834" position="center" showCaption="false"}

## Construção de módulos

O AIOPS permite a criação de módulos customizados utilizando linguagem de alto nível para scripts.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/-Mp-8mR8qKew4TirHNOfU_simon-scripts.PNG" size="74" width="1253" height="892" position="center" showCaption="false"}

Possibilitando a instalação automática de Agent nos mais diversos ambiente de forma simplificada. Incluindo ambientes complexos e conteinerizados tais como: Rancher, GliBC e Musl-libc, entre outros.

[title] Alarmes
[path] AIOPS/AIOPS/

Os alarmes são registros onde o AIOPS verifica ocorrências de eventos que ocorrem em uma determinada situação definida por configurações feitas pelo usuário.

Com esses registros é possível verificar a ocorrência de eventos criados a partir dessas configurações personalizadas.


[title] Ativando o LDAP / AD
[path] AIOPS/AIOPS/Integrações/Criando uma integração/

A fim de integrar a autenticação LDAP / AD ao AIOPS, deve-se preencher corretamente o formulário da integração.&#x20;

# Preenchimento do formulário

Abaixo está um exemplo de como o formulário deve ser preenchido. Os valores deverão ser configurados de forma que atenda ao seu ambiente.

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/D-DxLyG87hlVrKVx6qqFI_image.png)

## Campos do formulário

| Atributo                                                                               | Valor                                                  |
| -------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| Host                                                                                   | Hostname ou IP para conexão.                           |
| 389                                                                                    | Porta que roda o LDAP/AD.                              |
| Base DN                                                                                | DN Base onde os usuários serão buscados.               |
| Atributo de pesquisa                                                                   | Atributo contendo o identificador único do usuário.    |
| Bind DN                                                                                | DN de um usuário administrador para autenticação.      |
| Senha para bind                                                                        | Senha do usuário administrador para autenticação       |
| [Mapa de atributos](https://docs.simonops.com/ativando-o-ldap-ad#uf-mapa-de-atributos) | Atributos utilizados para criação do usuário no AIOPS. |
| Usuário LDAP para Auth.                                                                | Usuário administrador para autenticação.               |

### Mapa de atributos

O campo deve ser preenchido no formato chave\:valor separados por vírgulas, como no exemplo a seguir:

:::CodeblockTabs
Exemplo

```none
first_name:givenName,last_name:sn,email:mail
```
:::

- As chaves são os atributos utilizados para a identificação do usuário no AIOPS.&#x20;

| Chave       | Descrição                 |
| ----------- | ------------------------- |
| first\_name | Primeiro nome do usuário. |
| last\_name  | Sobrenome do usuário.     |
| email       | Endereço de email.        |

- O valor é o respectivo atributo localizado no **LDAP/AP**.&#x20;

| Valor        | Descrição                          |
| ------------ | ---------------------------------- |
| givenName    | Contém o primeiro nome do usuário. |
| sn / surname | Contém o sobrenome do usuário.     |
| mail         | Endereço de email.                 |


[title] SIMON
[path] AIOPS/


[title] Configurações em comum
[path] AIOPS/AIOPS/Usuários/Permissões por Roles/

|                         | **Administrador** | **Analista**    | **Gestor**      | **Supervisor**  | **Operador**    |
| ----------------------- | ----------------- | --------------- | --------------- | --------------- | --------------- |
| **Segredos**            | Acesso total      | Acesso total    | Acesso total    | Acesso total    | Acesso total    |
| **Chaves de acesso**    | Acesso total      | Acesso total    | Acesso total    | Acesso total    | Sem Acesso      |
| **Execuções (Rotinas)** | Acesso total      | Acesso total    | Somente leitura | Somente leitura | Somente leitura |
| **Sobre**               | Somente leitura   | Somente leitura | Sem Acesso      | Sem Acesso      | Sem Acesso      |


[title] Troubleshoot
[path] AIOPS/AIOPS/Inventário/Instalação dos Agents/Agent Linux/RPM/

### Escolhendo o Método de Comunicação

**Sintoma**: Durante a configuração do agente, você pode ser solicitado a escolher como o agente se comunicará com o servidor.

**Solução**:

1. Selecione o método de comunicação HTTP quando solicitado durante a instalação. O método de comunicação dependerá da configuração do seu ambiente e dos requisitos do servidor.

### Definindo a URL do Servidor

**Sintoma**: Após escolher o método de comunicação HTTP, você precisa definir a URL do servidor e não sabe como formatá-la corretamente.

**Solução**:

1. A sintaxe da URL do servidor deve ser similar a "http\[s]://inventory-server/ocsinventory". Aqui está o que cada parte significa:
   - **http\[s]**

     : Isso indica o protocolo de comunicação. Use "http" se estiver configurando uma comunicação não segura ou "https" se estiver configurando uma comunicação segura.
   - **inventory-server**

     : Substitua isso pelo endereço do servidor ao qual o agente deve se conectar. Certifique-se de que o endereço esteja correto.
   - **/ocsinventory**

     : Este é o caminho específico no servidor onde o serviço ou aplicativo de inventário está localizado. Certifique-se de que este caminho esteja correto e correspondendo à configuração do servidor.

### Instalação do dpkg no CentOS 6

**Sintoma**: Pode ser necessário fazer a instalação do dpkg.

**Solução**:

1. O **dpkg** é um sistema de gerenciamento de pacotes utilizado em sistemas baseados em Debian, como o Ubuntu. Para instalar o **dpkg**, siga estas etapas:
   - Abra um terminal ou prompt de comando.

```shell
sudo yum install dpkg
```

### Configuração Adicional Necessária

**Sintoma**: Após realizar a configuração inicial e editar o arquivo de configuração do agente, você ainda está enfrentando problemas na comunicação com o servidor e recebeu um erro indicando que o arquivo **cacert.pem** não existe.

**Solução**:

1. O erro indicado, "Cannot establish communication : 500 SSL\_ca\_file /var/lib/ocsinventory-agent/\<host>/cacert.pem does not exist," sugere que o agente não está conseguindo encontrar o arquivo **cacert.pem** no local especificado.
2. Verifique se o arquivo **cacert.pem** foi criado e salvo no local correto, que é "/var/lib/ocsinventory-agent/\<host>/cacert.pem". Certifique-se de que o caminho do arquivo está correto e que o arquivo existe no sistema.
3. Além disso, certifique-se de que o agente de inventário tem permissão de leitura para o arquivo **cacert.pem**. Você pode verificar as permissões do arquivo usando o comando **ls -l /var/lib/ocsinventory-agent/\<host>/cacert.pem**. Certifique-se de que o agente tenha permissões de leitura para esse arquivo.
4. Após verificar e ajustar as configurações, reinicie o agente de inventário para que as alterações tenham efeito.


[title] Introdução
[path] AIOPS/AIOPS/Inventário/

Bem-vindo à página de documentação do xventory, módulo do AIOPS para inventário de ativos de TI. Este software é uma ferramenta usada para gerenciar e rastrear ativos de hardware e software em uma organização. Esta solução é capaz de processar modelos de política de configuração e tomar decisões automatizadas baseadas em scripts. Isso pode ajudar a automatizar tarefas repetitivas e reduzir a carga de trabalho dos administradores de sistema.

## Gerenciamento de Ativos

Com o Xventory você possuirá ativos conectados a um CMDB universal (federado). O Xventory irá permitir que você adicione ativos manualmente ou execute uma varredura automática para descobrir os ativos em sua rede. Você pode adicionar ativos de hardware, como desktops, laptops, servidores, impressoras, bem como ativos de software, como aplicativos instalados.

## Política de Configuração

Uma vez que seus ativos estejam no inventário, você pode criar políticas de configuração personalizadas para seus ativos. Essas políticas podem incluir configurações de segurança, restrições de rede e configurações de aplicativos. Você pode criar essas políticas por meio de scripts escritos em várias linguagens de programação, como PowerShell, Python ou Bash.

## Tomada de Decisões Automatizadas

O Xventory é capaz de tomar decisões automatizadas com base em suas políticas de configuração. Por exemplo, se um dispositivo não estiver em conformidade com uma política específica, o software pode acionar uma ação corretiva, como alertar o administrador de sistema ou executar um script para corrigir a configuração não conforme.

## Relatórios e Análises

O Xventory fornece relatórios detalhados sobre seus ativos e suas configurações. Você pode gerar relatórios para verificar o status de conformidade de seus ativos com as políticas de configuração. Isso pode ajudá-lo a identificar quais ativos precisam de atualizações ou correções.



[title] API Xventory
[path] AIOPS/AIOPS/Inventário/



:::ApiMethodV2
```json
{
  "tab": "examples",
  "url": "https://inventory-server/inventory/api/sync/configuration-items/",
  "name": "Listar todos os itens de configuração",
  "method": "GET",
  "request": {
    "pathParameters": [],
    "queryParameters": [
      {
        "name": "page",
        "kind": "optional",
        "type": "Integer",
        "description": "",
        "children": []
      },
      {
        "kind": "optional",
        "name": "page_size",
        "type": "Integer",
        "description": "Resultados por página (Default: 100)"
      },
      {
        "name": "seconds",
        "kind": "optional",
        "type": "Integer",
        "description": "Valor relativo em segundos (Ex: 3600)",
        "children": []
      },
      {
        "kind": "optional",
        "name": "from",
        "type": "String",
        "description": "O ID inicial para busca em offset."
      },
      {
        "name": "to",
        "kind": "optional",
        "type": "string",
        "description": "",
        "children": []
      },
      {
        "name": "name",
        "kind": "optional",
        "type": "string",
        "description": "Nome do computador / Hostname",
        "children": []
      },
      {
        "name": "os",
        "kind": "optional",
        "type": "string",
        "description": "Nome do Sistema operacional (ex: Ubuntu, Windows Server 2023)",
        "children": []
      },
      {
        "name": "os_type",
        "kind": "optional",
        "type": "string",
        "description": "Tipo de Sistema operacional (ex: Linux, WIndows, Mac, etc)",
        "children": []
      },
      {
        "name": "type",
        "kind": "optional",
        "type": "string",
        "description": "Tipo de Item de Configuração (Other, Desktop, Laptop, Workstation, Computer, Server, etc.)",
        "children": []
      },
      {
        "name": "detailed",
        "kind": "optional",
        "type": "Boolean",
        "description": "Retornar todas as propriedades do item de configuração (Definir como true) Default: false",
        "children": []
      },
      {
        "name": "ci_ids[]",
        "kind": "optional",
        "type": "string",
        "description": "Array de ids dos itens de configuração",
        "children": []
      }
    ],
    "headerParameters": [],
    "formDataParameters": []
  },
  "results": {
    "languages": [
      {
        "id": "KuHjtRecM78pjppiZCzft",
        "code": "{\n\t\"results\": [\n\t\t{\n\t\t\t\"ci_id\": \"CI0000001\",\n\t\t\t\"name\": \"ser-stj\",\n\t\t\t\"type_name\": \"Other\",\n\t\t\t\"os\": \"Ubuntu 22.04\",\n\t\t\t\"os_type\": \"Linux\",\n\t\t\t\"description\": null,\n\t\t\t\"created_at\": \"2023-10-17T22:27:23.627547Z\",\n\t\t\t\"updated_at\": \"2023-10-20T22:27:23.627000Z\",\n\t\t\t\"hardware\": {\n\t\t\t\t\"DNS\": \"127.0.0.53\",\n\t\t\t\t\"ARCH\": null,\n\t\t\t\t\"NAME\": \"simon-stj\",\n\t\t\t\t\"UUID\": \"bd314f12-0ad3-425b-8771-9497b2011d07\",\n\t\t\t\t\"IPSRC\": \"146.235.62.40, 10.0.20.201\",\n\t\t\t\t\"IPADDR\": \"10.0.20.158/192.168.177.1/192.168.176.1/192.168.178.1/192.168.179.1/192.168.183.1/192.168.184.1/192.168.185.1\",\n\t\t\t\t\"MEMORY\": 32085,\n\t\t\t\t\"OSNAME\": \"Ubuntu 22.04\",\n\t\t\t\t\"OSTYPE\": \"Linux\",\n\t\t\t\t\"USERID\": \"ubuntu\",\n\t\t\t\t\"machine\": {\n\t\t\t\t\t\"uuid\": \"bd314f120ad3425b87719497b2011d07\"\n\t\t\t\t},\n\t\t\t\t\"WINOWNER\": null,\n\t\t\t\t\"OSVERSION\": \"22.04\",\n\t\t\t\t\"USERAGENT\": \"OCS-NG_unified_unix_agent_v2.8.0\",\n\t\t\t\t\"WINPRODID\": null,\n\t\t\t\t\"WORKGROUP\": \"citsmartx.oraclevcn.com\",\n\t\t\t\t\"PROCESSORN\": 1,\n\t\t\t\t\"PROCESSORS\": 0,\n\t\t\t\t\"PROCESSORT\": \"AMD EPYC 7J13 64-Core Processor\",\n\t\t\t\t\"USERDOMAIN\": null,\n\t\t\t\t\"WINPRODKEY\": null,\n\t\t\t\t\"DEFAULTGATEWAY\": \"10.0.20.1\"\n\t\t\t},\n\t\t\t\"memories\": [\n\t\t\t\t{\n\t\t\t\t\t\"ID\": 1,\n\t\t\t\t\t\"TYPE\": \"RAM\",\n\t\t\t\t\t\"SPEED\": \"Unknown\",\n\t\t\t\t\t\"CAPTION\": \"DIMM 0\",\n\t\t\t\t\t\"PURPOSE\": \"\",\n\t\t\t\t\t\"CAPACITY\": 16384,\n\t\t\t\t\t\"NUMSLOTS\": 0,\n\t\t\t\t\t\"DESCRIPTION\": \"Other\",\n\t\t\t\t\t\"HARDWARE_ID\": 1,\n\t\t\t\t\t\"SERIALNUMBER\": \"Not Specified\"\n\t\t\t\t},\n\t\t\t\t{\n\t\t\t\t\t\"ID\": 2,\n\t\t\t\t\t\"TYPE\": \"RAM\",\n\t\t\t\t\t\"SPEED\": \"Unknown\",\n\t\t\t\t\t\"CAPTION\": \"DIMM 1\",\n\t\t\t\t\t\"PURPOSE\": \"\",\n\t\t\t\t\t\"CAPACITY\": 16384,\n\t\t\t\t\t\"NUMSLOTS\": 1,\n\t\t\t\t\t\"DESCRIPTION\": \"Other\",\n\t\t\t\t\t\"HARDWARE_ID\": 1,\n\t\t\t\t\t\"SERIALNUMBER\": \"Not Specified\"\n\t\t\t\t}\n\t\t\t],\n\t\t\t\"networks\": [\n\t\t\t\t{\n\t\t\t\t\t\"ID\": 29,\n\t\t\t\t\t\"MTU\": \"9000\",\n\t\t\t\t\t\"TYPE\": \"ethernet\",\n\t\t\t\t\t\"SPEED\": \"-1 Mbps\",\n\t\t\t\t\t\"IPDHCP\": \"\",\n\t\t\t\t\t\"IPMASK\": \"255.255.255.0\",\n\t\t\t\t\t\"STATUS\": \"Up\",\n\t\t\t\t\t\"MACADDR\": \"02:00:17:00:37:dd\",\n\t\t\t\t\t\"TYPEMIB\": \"\",\n\t\t\t\t\t\"IPSUBNET\": \"10.0.20.0\",\n\t\t\t\t\t\"IPADDRESS\": \"10.0.20.158\",\n\t\t\t\t\t\"IPGATEWAY\": \"10.0.20.1\",\n\t\t\t\t\t\"VIRTUALDEV\": 0,\n\t\t\t\t\t\"DESCRIPTION\": \"ens3\",\n\t\t\t\t\t\"HARDWARE_ID\": 1\n\t\t\t\t},\n\t\t\t\t{\n\t\t\t\t\t\"ID\": 30,\n\t\t\t\t\t\"MTU\": \"1500\",\n\t\t\t\t\t\"TYPE\": \"ethernet\",\n\t\t\t\t\t\"SPEED\": \"10 Gbps\",\n\t\t\t\t\t\"IPDHCP\": \"\",\n\t\t\t\t\t\"IPMASK\": \"255.255.255.0\",\n\t\t\t\t\t\"STATUS\": \"Up\",\n\t\t\t\t\t\"MACADDR\": \"02:42:c1:5d:15:19\",\n\t\t\t\t\t\"TYPEMIB\": \"\",\n\t\t\t\t\t\"IPSUBNET\": \"192.168.177.0\",\n\t\t\t\t\t\"IPADDRESS\": \"192.168.177.1\",\n\t\t\t\t\t\"IPGATEWAY\": \"10.0.20.1\",\n\t\t\t\t\t\"VIRTUALDEV\": 0,\n\t\t\t\t\t\"DESCRIPTION\": \"br-00e9d69134b1\",\n\t\t\t\t\t\"HARDWARE_ID\": 1\n\t\t\t\t}\n\t\t\t],\n\t\t\t\"drives\": [\n\t\t\t\t{\n\t\t\t\t\t\"ID\": 2096,\n\t\t\t\t\t\"FREE\": 70958,\n\t\t\t\t\t\"TYPE\": \"/\",\n\t\t\t\t\t\"TOTAL\": 79205,\n\t\t\t\t\t\"LETTER\": \"\",\n\t\t\t\t\t\"VOLUMN\": \"/dev/sda1\",\n\t\t\t\t\t\"NUMFILES\": 0,\n\t\t\t\t\t\"CREATEDATE\": \"2023-08-28\",\n\t\t\t\t\t\"FILESYSTEM\": \"ext4\",\n\t\t\t\t\t\"HARDWARE_ID\": 1\n\t\t\t\t},\n\t\t\t\t{\n\t\t\t\t\t\"ID\": 2097,\n\t\t\t\t\t\"FREE\": 98,\n\t\t\t\t\t\"TYPE\": \"/boot/efi\",\n\t\t\t\t\t\"TOTAL\": 104,\n\t\t\t\t\t\"LETTER\": \"\",\n\t\t\t\t\t\"VOLUMN\": \"/dev/sda15\",\n\t\t\t\t\t\"NUMFILES\": 0,\n\t\t\t\t\t\"CREATEDATE\": \"0000-00-00\",\n\t\t\t\t\t\"FILESYSTEM\": \"vfat\",\n\t\t\t\t\t\"HARDWARE_ID\": 1\n\t\t\t\t},\n\t\t\t\t{\n\t\t\t\t\t\"ID\": 2098,\n\t\t\t\t\t\"FREE\": 505734,\n\t\t\t\t\t\"TYPE\": \"/dados\",\n\t\t\t\t\t\"TOTAL\": 524028,\n\t\t\t\t\t\"LETTER\": \"\",\n\t\t\t\t\t\"VOLUMN\": \"/dev/mapper/vg00-dados\",\n\t\t\t\t\t\"NUMFILES\": 0,\n\t\t\t\t\t\"CREATEDATE\": \"0000-00-00\",\n\t\t\t\t\t\"FILESYSTEM\": \"xfs\",\n\t\t\t\t\t\"HARDWARE_ID\": 1\n\t\t\t\t},\n\t\t\t\t{\n\t\t\t\t\t\"ID\": 2140,\n\t\t\t\t\t\"FREE\": 0,\n\t\t\t\t\t\"TYPE\": \"/dev/sdb\",\n\t\t\t\t\t\"TOTAL\": 524284,\n\t\t\t\t\t\"LETTER\": \"\",\n\t\t\t\t\t\"VOLUMN\": \"VG: vg00, Fmt: lvm2, Attr: a--\",\n\t\t\t\t\t\"NUMFILES\": 0,\n\t\t\t\t\t\"CREATEDATE\": \"0000-00-00\",\n\t\t\t\t\t\"FILESYSTEM\": \"LVM PV\",\n\t\t\t\t\t\"HARDWARE_ID\": 1\n\t\t\t\t}\n\t\t\t],\n\t\t\t\"bios\": [\n\t\t\t\t{\n\t\t\t\t\t\"MSN\": \"\",\n\t\t\t\t\t\"SSN\": \"Not Specified\",\n\t\t\t\t\t\"TYPE\": \"Other\",\n\t\t\t\t\t\"BDATE\": \"06/16/2021\",\n\t\t\t\t\t\"MMODEL\": \"\",\n\t\t\t\t\t\"SMODEL\": \"Standard PC (i440FX + PIIX, 1996)\",\n\t\t\t\t\t\"ASSETTAG\": \"OracleCloud.com\",\n\t\t\t\t\t\"BVERSION\": \"1.5.1\",\n\t\t\t\t\t\"HARDWARE_ID\": 1,\n\t\t\t\t\t\"BMANUFACTURER\": \"EFI Development Kit II / OVMF\",\n\t\t\t\t\t\"MMANUFACTURER\": \"\",\n\t\t\t\t\t\"SMANUFACTURER\": \"QEMU\"\n\t\t\t\t}\n\t\t\t],\n\t\t\t\"software\": [\n\t\t\t\t{\n\t\t\t\t\t\"ID\": 1,\n\t\t\t\t\t\"GUID\": \"\",\n\t\t\t\t\t\"NAME\": \"adduser\",\n\t\t\t\t\t\"FOLDER\": \"\",\n\t\t\t\t\t\"SOURCE\": 0,\n\t\t\t\t\t\"VERSION\": \"3.118ubuntu5\",\n\t\t\t\t\t\"COMMENTS\": \"add and remove users and groups\",\n\t\t\t\t\t\"FILENAME\": \"\",\n\t\t\t\t\t\"FILESIZE\": 622592,\n\t\t\t\t\t\"LANGUAGE\": \"\",\n\t\t\t\t\t\"BITSWIDTH\": 0,\n\t\t\t\t\t\"PUBLISHER\": \"Unavailable\",\n\t\t\t\t\t\"HARDWARE_ID\": 1,\n\t\t\t\t\t\"INSTALLDATE\": \"2023-07-28 22:11:36\"\n\t\t\t\t},\n\t\t\t\t{\n\t\t\t\t\t\"ID\": 2,\n\t\t\t\t\t\"GUID\": \"\",\n\t\t\t\t\t\"NAME\": \"amd64-microcode\",\n\t\t\t\t\t\"FOLDER\": \"\",\n\t\t\t\t\t\"SOURCE\": 0,\n\t\t\t\t\t\"VERSION\": \"3.20191218.1ubuntu2.2\",\n\t\t\t\t\t\"COMMENTS\": \"Processor microcode firmware for AMD CPUs\",\n\t\t\t\t\t\"FILENAME\": \"\",\n\t\t\t\t\t\"FILESIZE\": 123904,\n\t\t\t\t\t\"LANGUAGE\": \"\",\n\t\t\t\t\t\"BITSWIDTH\": 0,\n\t\t\t\t\t\"PUBLISHER\": \"Unavailable\",\n\t\t\t\t\t\"HARDWARE_ID\": 1,\n\t\t\t\t\t\"INSTALLDATE\": \"2023-09-05 06:13:14\"\n\t\t\t\t},\n\t\t\t\t{\n\t\t\t\t\t\"ID\": 3,\n\t\t\t\t\t\"GUID\": \"\",\n\t\t\t\t\t\"NAME\": \"apparmor\",\n\t\t\t\t\t\"FOLDER\": \"\",\n\t\t\t\t\t\"SOURCE\": 0,\n\t\t\t\t\t\"VERSION\": \"3.0.4-2ubuntu2.2\",\n\t\t\t\t\t\"COMMENTS\": \"user-space parser utility for AppArmor\",\n\t\t\t\t\t\"FILENAME\": \"\",\n\t\t\t\t\t\"FILESIZE\": 2736128,\n\t\t\t\t\t\"LANGUAGE\": \"\",\n\t\t\t\t\t\"BITSWIDTH\": 0,\n\t\t\t\t\t\"PUBLISHER\": \"https://apparmor.net/\",\n\t\t\t\t\t\"HARDWARE_ID\": 1,\n\t\t\t\t\t\"INSTALLDATE\": \"2023-07-28 22:12:25\"\n\t\t\t\t}\n\t\t\t]\n\t\t}\n\t],\n\t\"meta\": {\n\t\t\"pagination\": {\n\t\t\t\"page\": 1,\n\t\t\t\"pages\": 1,\n\t\t\t\"page_size\": 20,\n\t\t\t\"count\": 1\n\t\t}\n\t},\n\t\"links\": {\n\t\t\"first\": \"https://inventory-server/inventory/api/sync/configuration-item/?detailed=1&name=simon-stj&page=1\",\n\t\t\"last\": \"https://inventory-server/inventory/api/sync/configuration-item/?detailed=1&name=simon-stj&page=1\",\n\t\t\"next\": null,\n\t\t\"prev\": null\n\t}\n}",
        "language": "200"
      }
    ],
    "selectedLanguageId": "KuHjtRecM78pjppiZCzft"
  },
  "examples": {
    "languages": [
      {
        "id": "xHtAzFqX3D1YHN4jAt45_",
        "language": "curl",
        "code": "curl --location --request GET 'https://inventory-server/inventory/api/sync/configuration-items/' \\\n--header 'Accept: application/json' \\\n--header 'Content-Type: application/json'\n--header 'X-Api-Key: <api-key>'",
        "customLabel": ""
      },
      {
        "id": "MhNmfLvNuxqLqwyDteB5A",
        "language": "nodejs",
        "code": "var request = require('request');\nvar options = {\n   'method': 'GET',\n   'url': 'https://inventory-server/inventory/api/sync/configuration-items/',\n   'headers': {\n      'Accept': 'application/json',\n      'Content-Type': 'application/json',\n      'X-Api-Key': '<api-key>'\n   }\n};\nrequest(options, function (error, response) {\n   if (error) throw new Error(error);\n   console.log(response.body);\n});\n",
        "customLabel": ""
      },
      {
        "id": "qnBWXPAkKpmhjN9JdLIKI",
        "language": "javascript",
        "code": "var myHeaders = new Headers();\nmyHeaders.append(\"Accept\", \"application/json\");\nmyHeaders.append(\"Content-Type\", \"application/json\");\nmyHeaders.append(\"X-Api-Key\", \"<api-key>\");\n\nvar requestOptions = {\n   method: 'GET',\n   headers: myHeaders,\n   redirect: 'follow'\n};\n\nfetch(\"https://inventory-server/inventory/api/sync/configuration-items/\", requestOptions)\n   .then(response => response.text())\n   .then(result => console.log(result))\n   .catch(error => console.log('error', error));",
        "customLabel": ""
      },
      {
        "id": "olrrz9PtfLbBGfatGJxtf",
        "language": "python",
        "code": "import requests\nimport json\n\nurl = \"https://inventory-server/inventory/api/sync/configuration-items\"\n\npayload={}\nheaders = {\n   'Accept': 'application/json',\n   'Content-Type': 'application/json'\n}\n\nresponse = requests.request(\"GET\", url, headers=headers, data=payload)\n\nprint(response.text)\n",
        "customLabel": ""
      }
    ],
    "selectedLanguageId": "xHtAzFqX3D1YHN4jAt45_"
  },
  "responses": [
    {
      "statusCode": 200,
      "description": "Cake successfully retrieved.",
      "jsonExample": "{\n    \"name\": \"Cake's name\",\n    \"recipe\": \"Cake's recipe name\",\n    \"cake\": \"Binary cake\"\n}"
    },
    {
      "statusCode": 404,
      "description": "Could not find a cake matching this query.",
      "jsonExample": "{\n    \"message\": \"Ain't no cake like that.\"\n}"
    }
  ],
  "description": "Lista computadores a partir de um offset.",
  "currentNewParameter": {
    "label": "Query Parameter",
    "value": "queryParameters"
  }
}
```
:::

**Listagem de items de configuração modificados recentemente**
Os parâmetros são os mesmos, contudo é obrigatorio preencher um dos campos de data da mudança (from/seconds).

**Exemplo:&#x20;***(atualizados na ultima hora)*
https\://inventory-server/inventory/api/sync/inventory/configuration-item/updated/?**seconds=3600**

**Resposta:**

```json
{
	"results": [
		{
			"ci_id": "CI0000001",
			"name": "simon-stj",
			"type_name": "Other",
			"os": "Ubuntu 22.04",
			"os_type": "Linux",
			"description": null,
			"created_at": "2023-10-17T22:27:23.627547Z",
			"updated_at": "2023-10-20T20:00:23.627000Z"
		}
	],
	"meta": {
		"pagination": {
			"page": 1,
			"pages": 1,
			"page_size": 20,
			"count": 1
		}
	},
	"links": {
		"first": "http://localhost:8000/api/sync/inventory/configuration-item/updated/?page=1&seconds=3600",
		"last": "http://localhost:8000/api/sync/inventory/configuration-item/updated/?page=1&seconds=3600",
		"next": null,
		"prev": null
	}
}
```

**Detalhamento de item de configuração modificados recentemente**
Os parâmetros são os mesmos, contudo é obrigatorio preencher um dos campos de data da mudança (from/seconds)

[title] Regra
[path] AIOPS/AIOPS/Alarmes/

Para acessar a criação das regras de automação na criação de alarmes é necessário acessar o ícone de configurações no menu principal do AIOPS:

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/vivJML8tz8cQTepqqJ3Vw_botaoconfiguracoes.png" size="38" position="center" showCaption="false"}

Após acessar as configurações é necessário acessar a opção **regra** no menu interno de opções de alarme:

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/_jdwnJ2uOj0x14vdPkmrV_image.png" size="42" width="218" height="177" position="center" showCaption="false"}

Ao clicar, será exibida uma listagem das regras de alarmes cadastradas.

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/7PXRpwsSiGlH3Z39YI3D7_image.png)

## Criando regra

Para criar uma nova regra clique no botão **Nova regra**.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/2v9N-ZDU8wlnSXo8C3h0Y_image.png" size="26" width="142" height="40" position="center" showCaption="false"}

Uma nova janela com o formulário para cadastro de uma nova regra será exibido onde:

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/j7KtB5uMwpmmXUiDqniai_image.png)

### Aba Geral

- Nome: Identificador para o cadastro da regra.

### Aba Ações

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/j5H6ISlxulqpF3aiACvTn_image.png)

Ao clicar no botão **adicionar Nova ação&#x20;**&#x73;erá exibido o seguinte formulário:

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/2hTSc7lyopESfw4R-n92K_image.png" size="24" width="118" height="35" position="center" showCaption="false"}

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/C42SZ1y7VAjgGgF8dIyrA_image.png" size="74" width="600" height="375" position="center" showCaption="false"}

- **Nome**: Nome da ação
- **Tipo**:
  - Notificação:
  - Automação:
  - Delay:
- **Configurações:&#x20;**&#x50;ainel para detalhar configurações conforme o tipo selecionado.

### Notificação

As ações do tipo de notificação permitem que seja disparada uma ação por alguma integração ou automação disponível.

Ao selecionar a Integração **E-mail** o campo configurações irá exibir o campo **destinatários&#x20;**&#x72;eceber uma lista de e-mails separados por ponto e vírgula (;)

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/n7s43ela5B65CLHNuBIvy_image.png" size="74" width="600" height="598" position="center" showCaption="false"}

Ao selecionar a Integração **SMS** o campo configurações irá exibir o campo **destinatários** para receber uma lista de destinatários para envio do SMS separados por ponto e vírgula (;)

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/9UXjY5D1U_jrAe6O6LN44_image.png" size="74" width="600" height="598" position="center" showCaption="false"}



Ao selecionar a integração AIOPS o campo configurações irá exibir campos para seleção de destinatários baseados em **Times** ou **Usuários**

### Automação

As ações do tipo automação utilizam de pipes de automação criados no **Atmos.&#x20;**&#x51;uando selecionado um pipe que efetua notificações, a automação será executada.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/8nSUTpaH5NTOe6LTB_tYr_image.png" size="74" width="600" height="518" position="center" showCaption="false"}

Para alterar os outlines (parametros variáveis) dos pipes clicar no botão Adicionar e o formulário para adicionar será exibido:

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/ruHCi8fh6ZdYVxL8CNR0D_image.png" size="70" width="503" height="348" position="center" showCaption="false"}

Atualizando a lista de outlines adicionados

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/HuvQEdGWs6sc7wsgLvwQD_image.png" size="72" width="597" height="240" position="center" showCaption="false"}

### Delay

As ações do tipo delay iniciam um atraso programado na realização de ações baseado no intervalo de tempo selecionado

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/NXNGIew3Juidt61JxwJ-1_image.png" size="74" width="597" height="446" position="center" showCaption="false"}


[title] Docker Container Status
[path] AIOPS/MÉTRICAS/Explorar as Métricas/

Este plugin coleta métricas sobre o estado de um container docker.

| **Chave**                                         | **Tipo** | **Descrição**                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| docker\_container\_statu&#x73;**.**`container_id` | counter  | ID do contêiner.                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| docker\_container\_statu&#x73;**.**`exitcode`     | counter  | Os códigos de saída comuns associados aos contêineres docker são:<br />Exit Code 0: Ausência de um processo de primeiro plano anexado;<br />Exit Code 1: Indica falha devido a erro de aplicativo;<br />Exit Code 137: Indica falha quando o contêiner recebeu SIGKILL (intervenção manual ou ‘oom-killer’ \[OUT-OF-MEMORY]);<br />Exit Code 139: Indica falha porque o contêiner recebeu SIGSEGV;<br />Exit Code 143: Indica falha porque o contêiner recebeu SIGTERM. |
| docker\_container\_statu&#x73;**.**`finished_at`  | counter  | Tempo em que o container foi desligado.                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| docker\_container\_statu&#x73;**.**`oomkilled`    | boolean  | Quando o contêiner tem um 'limite' de memória (máximo) definido, e se o uso da memória do contêiner ultrapassar o limite especificado, o mesmo será morto e o status será relatado como OOMKilled.                                                                                                                                                                                                                                                                      |
| docker\_container\_statu&#x73;**.**`pid`          | counter  | O Docker cria um novo namespace PID para cada contêiner por padrão. O namespace PID de um contêiner isola os processos nesse contêiner de processos em outros contêineres.                                                                                                                                                                                                                                                                                              |
| docker\_container\_statu&#x73;**.**`started_at`   | counter  | Tempo em que o container foi iniciado.                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| docker\_container\_statu&#x73;**.**`uptime_ns`    | counter  | Tempo de atividade do container docker.                                                                                                                                                                                                                                                                                                                                                                                                                                 |


[title] Agent Linux
[path] AIOPS/AIOPS/Inventário/Instalação dos Agents/


[title] Alertas / Triggers
[path] AIOPS/ATMOS/

## Acesso

Para acessar a aplicação Atmos é necessário clicar no botão "aplicações" localizado no canto inferior esquerdo, do menu principal no AIOPS.

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/_dl2iGnL-Fm4SOb1vBfhr_image.png" size="46" position="center" showCaption="false"}

Após acessar o Atmos é necessário acessar a tela de alertas através do menu principal:

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/QMQTg2liBmcPb1iQvZj1M_image.png" size="46" position="center" showCaption="false"}

Ao acessar a tela de topologia será possível ver a listagem de alertas existentes:&#x20;

![](https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/_a2Y5OuWDtMS59sUJijYj_image.png)

## Criação de alertas

Para criar um alerta é necessário clicar no botão:&#x20;

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/r8bASYBx10FwVzmrsKtSh_image.png" size="28" position="center" showCaption="false"}

Ao clicar no botão um novo modal se abrirá com as seguintes características:&#x20;

![](https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/hwCtW_Uo_X_arEs4-m7_X_image.png)

Onde será possível definir:&#x20;

- Tipo do Evento&#x20;
- Transformação
- Função&#x20;
- Grupo&#x20;
- Métrica
- Descrição

### Exemplo de alerta

Na imagem abaixo é possível checar a criação de uma alerta preenchendo os dados necessários:

![](https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/2ATHrvv5wWZJckx2R2Khg_image.png)

## Regras para Triggers

Na criação de alertas, é possível definir múltiplas condições e prioridades para diferentes pontos de métricas:&#x20;

Contemplando thresholds definidos manualmente dentro de uma janela de tempo e thresholds automáticos que podem ser definidos dentro de uma janela temporal, permitindo assim que o AIOPS se adapte ao comportamento das métricas com base na auto detecção de anomalias, todas as configurações podem ser ajustadas a qualquer tempo de maneira manual.&#x20;

## Filtros

Também é possível definir filtros para limitar as métricas que se deseja checar, como no exemplo abaixo onde o alerta que está sendo criado é relacionado ao uptime de um serviço, onde queremos limitar ao serviço relacionado ao ibm db2:&#x20;

![](https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/1_P-MWx0GAXDfSITbQLDV_image.png "Filtro para os processos com nome db2fmcd e db2sysc")

## Escopo

O escopo define o grupo de items que serão monitorados para as métricas selecionadas, podendo optar por hosts específicos, serviços de TI ou anotações e tags:

![](https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/-XeAO1JUemkWfvKmtpaIs_image.png)


[title] Configuração
[path] AIOPS/AIOPS/Alarmes/

Para acessar a configuração de alarmes é necessário acessar o ícone de configurações no menu principal do AIOPS:

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/vivJML8tz8cQTepqqJ3Vw_botaoconfiguracoes.png" size="38" position="center" showCaption="false"}

Após acessar as configurações é necessário acessar a opção **configuração** no menu interno de opções de alarme:

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/_jdwnJ2uOj0x14vdPkmrV_image.png" size="42" width="218" height="177" position="center" showCaption="false"}

Ao clicar, será exibida uma listagem das configurações de alarmes cadastradas.

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/5WlucoWUWD1FtISzFmv3u_captura-de-tela-2023-01-19-as-174406.png)

## Criando configuração

Para criar uma nova configuração clique no botão **Nova configuração**.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/P07iBvFzQRhxHgqonLmQ6_image.png" size="34" width="185" height="37" position="center" showCaption="false"}

Uma nova janela com o formulário para cadastro de uma nova configuração será exibido onde:

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/XwUQXqguslXufmObjhjc8_image.png)

- **Nome**: Identificador da configuração
- **Tipos de alarme**:
  - Pares de eventos:&#x20;
  - Sequência de eventos:
  - Combinação de eventos:
  - Taxa de eventos:
- **Intervalo**: Valor numérico que indica o tempo da execução da rotina de alarmes.
- **Unidades de tempo**: Unidade de tempo do intervalo de execução da rotina.
  - Segundos
  - Minutos
  - Horas

## Tipos de alarmes

### Pares de eventos

A configuração de pares de eventos é feita para quando houver necessidade da criação de um alarme que verifique a ocorrência desses eventos nos pares selecionados para a configuração.

Ao selecionar o tipo de evento "pares de evento" a janela exibirá a opção para adicionar novas Triggers (ativadores de eventos que geram incidentes)

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/d8AFAP04t7LcTyAZ3AVhy_image.png)

O botão adicionar trigger abrirá uma nova janela de seleção para selecionar as triggers dos pares de eventos.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/1C79FEdAvXVZZ9ZbpdVaw_image.png" size="20" width="101" height="40" position="center" showCaption="false"}

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/9gYVtjBcn8hrka1U93XNk_image.png)

A janela de seleção de triggers exibe uma listagem de todas triggers criadas para permitir a seleção de quais eventos que, em pares, serão analisados.

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/rXP-PgqrJyVv0yPBrRxlF_image.png)

### Sequência de eventos

A configuração de sequência de eventos é feita para quando houver necessidade da criação de um alarme que verifique a ocorrência desses eventos na sequência informada pela configuração.

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/7YE28ATief9aa0pfEi8mT_image.png)

### Combinação de eventos

A configuração de sequência de eventos é feita para quando houver necessidade da criação de um alarme que verifique a ocorrência desses eventos simultaneamente pela configuração.

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/GzwcEgluuoDyZuZI2q2Dd_image.png)

### Taxa de eventos

A configuração de taxa de eventos é feita para quando houver necessidade da criação de um alarme que verifique a ocorrência de um evento repetidas vezes no intervalo de tempo da configuração.

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/LqIXRoFfWqm7PyovxVFsV_captura-de-tela-2023-01-19-as-173529.png)


[title] CPU
[path] AIOPS/MÉTRICAS/Explorar as Métricas/

O plugin de `cpu` coleta métricas nas CPUs do sistema.

| **Chave**              | **Tipo** | **Descrição**                                                                                                                                                                 |
| ---------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| cpu.`usage_user`       | percent  | Porcentagem de CPU utilizada para processar as instruções de um programa no espaço do usuário.                                                                                |
| cpu.`usage_system`     | percent  | Porcentagem de CPU utilizada para executar um código no kernel do sistema operacional.                                                                                        |
| cpu.`usage_idle`       | percent  | Porcentagem de CPU que está ociosa.                                                                                                                                           |
| cpu.`usage_active`     | percent  | Porcentagem de CPU que está ativa.                                                                                                                                            |
| cpu.`usage_nice`       | percent  | Porcentagem do tempo da CPU ocupada por processos no nível do usuário com um valor "nice" positivo (prioridades mais baixas).                                                 |
| cpu.`usage_iowait`     | percent  | Porcentagem de tempo que a CPU (ou CPUs) ficaram ociosas durante o qual o sistema teve solicitações de I/O de disco pendentes.                                                |
| cpu.`usage_irq`        | percent  | Porcentagem de tempo em que a CPU gastou processamento com interrupções.                                                                                                      |
| cpu.`usage_softirq`    | percent  | Porcentagem de tempo que a CPU está atendendo às interrupções de software.                                                                                                    |
| cpu.`usage_steal`      | percent  | Porcentagem de tempo que a CPU está em *stolen time.&#x20;*<br />*-&#x20;*&#x53;tolen Time: Tempo gasto em outros sistemas operacionais em um ambiente virtualizado.          |
| cpu.`usage_guest`      | percent  | Porcentagem de tempo que a CPU está executando uma CPU virtual para um sistema operacional convidado.                                                                         |
| cpu.`usage_guest_nice` | percent  | Porcentagem de tempo que a CPU está executando uma CPU virtual para um sistema operacional convidado, que é de baixa prioridade e pode ser interrompida por outros processos. |


[title] Permissões por Roles
[path] AIOPS/AIOPS/Usuários/

O AIOPS utiliza as seguintes *roles* por padrão (em ordem de nível de acesso):

- **Administrador**
- **Analista**
- **Gestor**
- **Supervisor**
- **Operador**

Disponibilizamos *roles* especiais que *não possui permissão para entidades*, exceto nos seguintes contextos:

- **Monitor**
  - Acesso exclusivo às Dashboards (previamente autorizadas)
- **Sem Perfil**
  - Acesso exclusivo à tela do seu perfil (sem permissão extra)


[title] Detalhamento de Incidentes
[path] AIOPS/AIOPS/Incidentes/

Na tela de detalhamento de incidentes é possível acompanhar de maneira rápida e eficaz a relação dos adventos que surgiram.&#x20;

É possível acessar a tela de detalhamento seguindo os primeiros passos listados em [Listagem de Incidentes](docId\:BunM5-8SU7izYI_Q9eAab).

## Acesso

Logo após acessar a tela de listagem de incidentes, é necessário clicar em um incidente:

![](https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/XsVLQjkYjKmCOuqXN9j6d_incident-item.png)

Após clicar, a tela de detalhamento se abrirá oferecendo opções específicas ao usuário para a resolução daquele advento:&#x20;

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/E7MH4_5tSCVYZo06qTIVq_screen-shot-2021-06-16-at-181114.png "Tela de detalhamento")

## Associação de Equipes

A associação de pessoas à demanda em questão, é possível através do botão que se encontra acima da barra de abas.

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/fwVy2pK3nVYmlLfmfNbSa_Screen%20Shot%202021-01-09%20at%2014.59.26.png" size="10" position="center" showCaption="false"}

## Compartilhamentos e Comentários

No canto superior esquerdo é possivel acessar as telas de compartilhamento e comentários:

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/fGWXmACQ5Hy_jNQ2uQJw4_Screen%20Shot%202021-01-09%20at%2015.29.27.png" size="14" position="center" showCaption="false"}

Na opção **compartilhamento** o usuário poderá compartilhar os incidentes por outros canais de comunicação adotados pelas equipes para agilizar o acionamento das pessoas chaves.

O botão de **comentários&#x20;**&#x70;ermite a inserção de um parecer do usuário após breve análise da demanda.

![](https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/Kk1JqgDyxFdHE9RoXJTmI_Screen%20Shot%202021-01-09%20at%2015.39.59.png)

## Barra de Abas

Nessa tela é possível acessar a barra de abas onde se encontram as opções: Alertas, Atividades e Timeline.

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/IDkiRvoqkkU7IKZSntsa6_Screen%20Shot%202021-01-09%20at%2015.45.58.png" size="70" position="center" showCaption="false"}

## Alertas

Na aba de alertas são identificados os incidentes que acabaram de ser abertos.

![](https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/PQKuXb8M8zOX7MfgGbzh0_Screen%20Shot%202021-01-09%20at%2015.54.28.png)

## Atividades

Observa-se na opção os procedimentos realizados para o atendimento e resolução de determinado incidente.

## Timeline

Através de uma linha do tempo construída pelo AIOPS, é possível alcançar uma análise de causa raiz efetiva e rápida, reduzindo o seu tempo de atendimento e resolução dos incidentes.

![](https://gblobscdn.gitbook.com/assets%2F-Ls76-8XbGuboSQAg3Y9%2F-LsS4TFxl19M8_Q9JDeW%2F-LsS4cYTYGbvGQVjC3n6%2FDetalhes-do-Incidente-Completo.png?alt=media\&token=5e4e62ca-eb09-4145-9aba-b246854268d9)

Nesse exemplo é possível rapidamente observar um problema de CPU no *servidor de aplicação*, que impactou as consultas no banco de dados:

![](https://gblobscdn.gitbook.com/assets%2F-Ls76-8XbGuboSQAg3Y9%2F-LsS4TFxl19M8_Q9JDeW%2F-LsS4tlEd8lA6a49dQg7%2FDetalhes-do-Incidente-Alertas.png?alt=media\&token=e53630b9-090f-4c8e-9824-f93c7f63e16c)

Através da linha do tempo nota-se a eficácia do AIOPS na tratativa de eventos, evitando ruídos e deixando claro o contexto dos acontecimentos e sua evolução:

![](https://gblobscdn.gitbook.com/assets%2F-Ls76-8XbGuboSQAg3Y9%2F-LsS4TFxl19M8_Q9JDeW%2F-LsS52AVtMWJZ6d16x4F%2FDetalhes-do-Incidente-Timeline.png?alt=media\&token=27e6fb11-cf41-40d9-bb0d-90f94e002971)

A linha do tempo possibilita a atuação em três principais aspectos, que ajudarão sua operação de TI:

1. **Eventos intermitentes** – ao reconhecer suas repetições em uma única visão, possibilitamos o reconhecimento rápido do contexto do problema facilitando sua resolução definitiva.
2. **Ordem temporal&#x20;**– simplificando a análise de causalidade e evolução do problema.
3. **Causa raiz** – facilmente reconhecidas ao utilizar a referência dos pontos da timeline.

Dessa forma, é possível reduzir a complexidade da operação, simplificando os processos e aumentando expressivamente a produtividade de sua equipe.

[title] Integração
[path] AIOPS/AIOPS/Compartilhamento Automático/

Compartilhamento Automático utilizando Integrações.&#x20;

## Criação do Auto Compartilhamento

Acessar a opção de configurações no menu principal do AIOPS:

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/2x7J3LFFnjoOSde1WNTOt_botaoconfiguracoes.png" size="36" position="flex-start" showCaption="false"}

No menu lateral escolha a opção **Auto Compartilhamento**:

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/u9p2-1Q_MH68GkLMX4JYz_captura-de-tela-2021-03-31-as-131027.png" size="40" position="center" showCaption="false"}

Você poderá criar um novo compartilhamento ou alterar um já existente. Para criar um novo você irá definir o **Ambiente** (utilizado para direcionar os alertas deste canal) e o **Tipo** escolhendo uma das opções de integração disponíveis.

![](https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/KD3P47kLyrO-yuw5L5-wG_janela-autocompartilhamento-notificacao.png "Exemplo utilizando o Tipo (Notificação) e a Integração (E-mail)")

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/DO9j26VcbHBOZaUqbPVDT_captura-de-tela-2021-03-31-as-132013.png" size="32" caption="Definição do Tipo" position="center" showCaption="true"}




[title] AIOPS
[path] AIOPS/AIOPS/Usuários/Permissões por Roles/

## Funcionalidades

|                                                                                | **Administrador** | **Analista** | **Gestor**   | **Supervisor**  | **Operador**    |
| ------------------------------------------------------------------------------ | ----------------- | ------------ | ------------ | --------------- | --------------- |
| ****[Incidentes](https://docs.simonops.com/incidentes)****                     | Acesso total      | Acesso total | Acesso total | Acesso total    | Acesso total    |
| ****[Eventos e incidentes](https://docs.simonops.com/eventos-e-incidentes)**** | Acesso total      | Acesso total | Acesso total | Sem acesso      | Sem acesso      |
| ****[Visão Geral](https://docs.simonops.com/visao-geral)****                   | Acesso total      | Acesso total | Acesso total | Acesso total    | Acesso total    |
| ****[Integrações](https://docs.simonops.com/integracoes)****                   | Acesso total      | Acesso total | Acesso total | Somente leitura | Somente leitura |
| **Eventos**                                                                    | Acesso total      | Acesso total | Sem acesso   | Sem acesso      | Sem acesso      |



## Configurações

### Monitoramento

|                                                                                        | **Administrador** | **Analista** | **Gestor**      | **Supervisor**  | **Operador**    |
| -------------------------------------------------------------------------------------- | ----------------- | ------------ | --------------- | --------------- | --------------- |
| ****[Canais](https://docs.simonops.com/canais)****                                     | Acesso total      | Acesso total | Acesso total    | Acesso total    | Somente leitura |
| ****[Auto Compartilhamento](https://docs.simonops.com/compartilhamento-automatico)**** | Acesso total      | Acesso total | Acesso total    | Acesso total    | Somente leitura |
| **Escala**                                                                             | Acesso total      | Acesso total | Somente leitura | Somente leitura | Somente leitura |



### Pessoas

|                                                        | **Administrador** | **Analista** | **Gestor**   | **Supervisor** | **Operador**    |
| ------------------------------------------------------ | ----------------- | ------------ | ------------ | -------------- | --------------- |
| ****[Time](https://docs.simonops.com/times)****        | Acesso total      | Acesso total | Acesso total | Acesso total   | Somente leitura |
| ****[Usuários](https://docs.simonops.com/usuarios)**** | Acesso total      | Acesso total | Acesso total | Acesso total   | Somente leitura |



### Geral

|                                                       | **Administrador** | **Analista**    | **Gestor**      | **Supervisor**  | **Operador**    |
| ----------------------------------------------------- | ----------------- | --------------- | --------------- | --------------- | --------------- |
| ****[Organização](https://docs.simonops.com/slas)**** | Somente leitura   | Somente leitura | Somente leitura | Somente leitura | Somente leitura |
| **Nível de prioridade**                               | Acesso total      | Acesso total    | Somente leitura | Somente leitura | Somente leitura |


[title] Kernel
[path] AIOPS/MÉTRICAS/Explorar as Métricas/

Este plugin coleta métricas sobre o kernel.

| **Chave**                   | **Tipo** | **Descrição**                                                                                             |
| --------------------------- | -------- | --------------------------------------------------------------------------------------------------------- |
| kerne&#x6C;**.**`boot_time` | counter  | Tempo total levado para realizar o boot                                                                   |
| kernel.`context_switches`   | counter  | Número de vezes que o processo ou thread do kernel foi mudado para outro processador durante o intervalo. |
| kernel.`entropy_avail`      | counter  | Entropy é a medida dos números aleatórios disponíveis em /dev/random.                                     |
| kernel.`interrupts`         | counter  | Número de interrupções enviadas para cada processador de um dispositivo de I/O específico.                |
| kernel.`processes_forked`   | counter  | Número de processos que se "bifurcam" para criar uma cópia de si mesmo.                                   |




[title] Criando uma integração
[path] AIOPS/AIOPS/Integrações/

## Acesso

Para a criação de uma nova integração é necessário acessar o AIOPS, e no menu principal (canto esquerdo) selecionar a seguinte opção:

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/JmgTScXmhFT28N7mPP6CD_botaomenuintegracoes.png" size="42" position="center" showCaption="false"}

## Cadastro

Após acessar a tela de integrações, será necessário cadastrar uma nova integração:&#x20;

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/TmezBWeJBgkhvKTk4XbB5_novaintegracaobutton.png" size="42" position="center" showCaption="false"}

Após clicar o botão acima teremos uma nova janela na aba "Geral", onde será necessário a definição de um nome para a integração que está sendo criada, e deverá ser selecionada opção com o tipo específico da integração desejada.

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/NFURgQgSDq8Qfgn4uXnTd_IntegracaoEmail.png" size="80" showCaption="false"}

## Opções

As abas do popup que apareceu se adaptarão conforme integração selecionada, permitindo assim a inserção de parametros que possibilitarão a comunicação entre o AIOPS e a ferramenta desejada para que a integração possa ser adicionada com sucesso.

## Autenticação

Na aba de autenticação é possível cadastrar os dados de usuários para que o AIOPS possa se comunicar com a ferramenta desejada

Para todas as integrações existentes no AIOPS, é possível realizar o teste de comunicação após o preenchimento dos dados necessários através do botão:


[title] AIOPS
[path] /


[title] Introdução
[path] AIOPS/INTRODUÇÃO/

*AIOPS* é uma plataforma de *SOAR E APM*, desenvolvida e criada pela empresa **Citsmart**, que fornece uma visão 360º de toda a unidade de um datacenter (on-premises, nuvem ou híbrida).

Gerencia ativamente eventos e incidentes de monitoramento, e executa automações através da base de conhecimento acionável, topologia automática e auto recuperação de um ambiente ou equipamento.&#x20;

Através do AIOPS os ruídos podem ser cortados facilmente, a captura de alertas de diferentes fontes passa a ser simples e com poucos recursos é possível atuar rapidamente sobre os incidentes, escalando exponencialmente os seus níveis de serviços.&#x20;



## Como funciona

- **Alertas** – Eventos e Alertas são a base da atuação do AIOPS no monitoramento de sua operação, permitindo o tratamento de eventuais problemas de acordo com os seus processos, podendo ser gerados com base em triggers próprias (configuráveis por script), ou captados de quaisquer fontes geradoras de alertas (third party, logs, eventos de sistema, redes, etc), existentes em sua operação.

- **Correlações** – Dinamicamente, o AIOPS reune os alertas relacionados em um incidente de alto nível, reduzindo ruídos e melhorando a visibilidade entre diferentes áreas da infraestrutura. A inteligência artificial do AIOPS aprimora diariamente suas correlações, automaticamente.&#x20;

- **RCA – Root Cause Analysis** – O motor de aprendizado do AIOPS aprenderá com os eventos e sua infraestrutura a causalidade de cada um e informará nos próximos alertas o Índice PRC (Possible Root Cause). Esta classificação automática com base em IA ajudará sua equipe na resolução dos incidentes.

- **Enriquecimento** – O AIOPS permite o enriquecimento de informação contextual, melhorando a correlação entre alertas e facilitando a investigação/resolução do incidente.

- **Canais** – Crie visões customizadas dos incidentes organizando-os por assunto, items de configuração, equipes, prioridade, etc. Utilize os canais para realizar a abertura automática de ticket (smart ticketing) e/ou compartilhamento automático.

- **Compartilhamento** - Notifique membros importantes de uma equipe e/ou escale os incidentes através de outras ferramentas, como ITSM, ferramentas de colaboração e mensageiros como slack/whatsapp/sms, etc.

- **CMDB** – O Gerenciamento de configuração do AIOPS permite realizar o mapeamento autônomo de todos os seus Items de Configuração (ICs).
  Topologia - Visualize todos os ICs, incluindo dependências, métricas, capacidade e status, organizando-os em grupos seja por natureza, estrutura organizacional, posicionamento geográfico, etc.

- **Pipes** -  Transforme a sua visão sobre base de conhecimento, utilizando a base de conhecimento acionável do AIOPS, os Pipes, com essa funcionalidade é possível acionar automaticamente diferentes ações com base em todas as informações da sua infra-estrutura.



- **Divedot\_Agent&#x20;**– Com o Divedot\_Agent aumentamos o desempenho e diminuímos a instabilidade de seus aplicativos através da instrumentação em bytecode.&#x20;

De forma automática realizamos a instrumentação de bytecode para garantir que todos os aplicativos do ambiente sejam monitorados sem a necessidade de um especialista na linguagem das aplicações.

O Agent captura os eventos quando eles ocorrem na aplicação, evitando a perda de dados importantes quanto a problemas relacionados a desempenho na aplicação. Evitando a coleta de lixo em um monitoramento critico



## Integrações&#x20;

Integre quaisquer fontes de alertas que você possui com o AIOPS, é possível enviar alertas correlacionados, ou eventos isolados, o AIOPS é resiliente e pode se adequar a sua realidade,

Com os Pipes, você pode integrar com diferentes ferramentas para atuar de acordo com suas necessidades, automatizando atividades que geram problemas recorrentes para a sua operação.

Permitimos integrações nativas com ferramentas para captura de rede (netflow, sflow, snmp), aplicações (traces, rum, métricas de performance), banco de dados, topologia, mudanças, o que categoriza o AIOPS como ferramenta central aos domínios de sua aplicação.

## Preferências

Conhecendo melhor o AIOPS, é importante saber que todas as funcionalidades citadas são configuráveis, de acordo com suas preferências, desde a correlação de eventos até o CMDB.

- **Correlações** – Construa incidentes com o AIOPS, seja de forma autônoma ou semi-autônoma, usufruindo do conceito de aprendizado de máquina "caixa aberta", é possível que se realize ajustes nas correlações identificadas pelo AIOPS, de diferentes formas, seja nas regras que são seguidas ou movendo-se os alertas existentes.

- **Smart ticketing** – Enriqueça e sincronize os dados de incidentes em tempo real, e, caso seja necessário, envie automaticamente esses incidentes para a sua ferramenta de ticket/colaboração.

- **CMDB** – Atue sobre quaisquer dimensões do seu CMDB, configurando quaisquer parâmetros necessários, seja para descoberta ou para topologia.

- **Serviços** – Configure os seus serviços em alto nível, agrupando quaisquer itens da sua operação para acompanhamento dos níveis de serviço

- **Canais** – Parametrize os seus canais de incidentes, de acordo com as suas equipes, ou quaisquer atributos que compõem os alertas/incidentes, possibilitando limitar a visualização dos usuários de acordo com os canais onde o mesmo possui acesso.

- **Topologia** - Mapeie e organize a sua topologia de rede, de acordo com sua estrutura organizacional, grupos de itens, região geográfica, etc. Com o AIOPS é possível visualizar em tempo real todos os aspectos de sua operação.

## Explore

Recomendamos explorar todas as funcionalidades e recursos que o AIOPS oferece, desta forma, será possível impactar e transformar completamente toda a sua Operação de TI, priorizando eficiência através da inteligência.

## Suporte

Somos uma empresa brasileira voltados para a criação de software de código proprietário e estamos completamente comprometidos em ajudar nossos clientes com as ferramentas e informações necessárias para obtenção de sucesso em sua operação. Disponibilizamos atendimento e suporte customizado através de nossa equipe de *Customer Success*.&#x20;

Você pode nos enviar mensagens dentro da aplicação, utilizar a documentação e FAQs para solução de problemas, e claro, entrar em contato conosco nos principais canais de atendimento sempre que desejar.&#x20;

O AIOPS é uma ferramenta WEB podendo ser utilizada nos seguintes navegadores:

- Internet Explorer >= 9.0
- Mozilla Firefox >= 24.0
- Chrome >= 18.0

Confira mais informações na seção *Requisitos do Sistema*.


[title] INSTALAÇÃO
[path] AIOPS/


[title] Docker
[path] AIOPS/MÉTRICAS/Explorar as Métricas/

Reunir métricas sobre a execução de contêineres docker.

| **Chave**                        | **Tipo** | **Descrição**                                             |
| -------------------------------- | -------- | --------------------------------------------------------- |
| docker.`memory_total`            | bytes    | Memória total alocada para todos os contêineres           |
| docker.`n_containers`            | counter  | Número total de contêineres em execução                   |
| docker.`n_containers_paused`     | counter  | Total number of containers paused on this host            |
| docker.`n_containers_running`    | counter  | Número total de contêineres em execução neste host        |
| docker.`n_containers_stopped`    | counter  | Número total de contêineres parados neste host            |
| docker.`n_cpus`                  | counter  | Número total de CPUs disponíveis para Docker              |
| docker.`n_goroutines`            | counter  | Número de goroutines                                      |
| docker.`n_images`                | counter  | Número total de imagens                                   |
| docker.`n_listener_events`       | counter  | Número atual de ouvintes conectados ao Docker             |
| docker.`n_used_file_descriptors` | counter  | Número total de descritores de arquivo em uso pelo Docker |
| docker.`pool_blocksize`          | bytes    | Tamanho do bloco do pool em KB                            |


[title] Correlação de Eventos
[path] AIOPS/AIOPS/Incidentes/

Correlação é um método de agrupamento de alertas relacionados em um Incidente de alto nível.&#x20;

O AIOPS utiliza o reconhecimento de padrões para automaticamente processar os dados de eventos recebidos de diferentes fontes, seja logs, métricas ou integrações. Sendo assim, é possível agrupar eventos em contextos similares, possibilitando a redução de ruídos e uma detecção rápida da real demanda em questão.&#x20;

Com os dados detectados e com os padrões processados, o AIOPS é capaz de processar e predizer com um evento deve se correlacionar com o outro.

![](https://gblobscdn.gitbook.com/assets%2F-Ls76-8XbGuboSQAg3Y9%2F-LsHo9EPusLTuvY-Zy-k%2F-LsHoyjUHz6IMB9sJc7U%2FPage-003A.png?alt=media\&token=04092b37-f950-424f-8ef2-c900f8df84df)

Contextualização:

![](https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/X4AGvldoAUoTpoEXHWmr4_Screen%20Shot%202021-01-09%20at%2016.15.11.png)

## Movimentação de Alertas

Para a movimentação de alertas, basta clicar no botão que se encontra no canto superior direito da tela.

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/uH8v0Qk87r5sDCl-nl3Iy_Screen%20Shot%202021-01-09%20at%2016.17.48.png" size="30" position="center" showCaption="false"}

Após o acesso é necessário a seleção do alerta desejado seguida por um clique no botão **mover** **alertas,&#x20;**&#x70;resente logo acima e à esquerda da lista de alertas.

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/NyDOHs4iKwqJYgtkDfDqE_Screen%20Shot%202021-01-09%20at%2016.44.08.png" size="34" position="center" showCaption="false"}

![](https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/K3y_7TAsXCgwP6oDp7OwV_Screen%20Shot%202021-01-09%20at%2016.42.05.png)

Em seguida estará disponível um modal com as informações necessárias para a movimentação:

![](https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/zkRC0L9BE29gg4874uZdb_Screen%20Shot%202021-01-09%20at%2016.48.33.png)

Season ID é o número identificador de um incidente, estará sempre próximo à prioridade (P). Na imagem abaixo, representa o exemplo P1, a letra **P** poderá ser acompanhada pelos números 1,2,3,4 e 5 indicando a prioridade do problema. Números menores exigem atuações de urgência.

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/0cJl-7Bty5JfTJMz9iDWb_Screen%20Shot%202021-01-09%20at%2017.00.48.png" size="10" position="center" showCaption="false"}

Conforme relatado acima, todos os incidentes possuem um número identificador( Season ID). Para movimentar o alerta escolhido, basta selecionar o Season ID do incidente desejado que se encontra na coluna lateral à direita da tela.&#x20;

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/zb-T3GgDTK5nHkeI0v4EK_Screen%20Shot%202021-01-09%20at%2017.16.15.png" size="26" position="center" showCaption="false"}

No botão **Sugerir pipe** que se encontra ao lado do botão Mover Alertas é possível escolher o fluxo de automação ([Pipes e Automação](docId\:QYEmgXVWSXSgczlV_aDWF)) mais indicado para o alerta selecionado

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/2y2DhcjFkIj96PjbrnyJJ_Screen%20Shot%202021-01-09%20at%2017.38.14.png" size="24" position="center" showCaption="false"}

Caso o incidente esteja agrupado adequadamente é possível habilita-lo para treino uilizando o botão como o exemplo abaixo, que se encontra no canto superior direito da tela, acima da lista de alertas. A cada movimentação de alertas o AIOPS aprende via reinforcement learning a ser cada vez mais assertivos nas correlações que acontecem no ambiente.

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/MHUgmjK6dR8l6Ds367C5F_Screen%20Shot%202021-01-09%20at%2017.41.19.png" size="40" position="center" showCaption="false"}

Ao selecionar essa opção permitirá que o AIOPS se torne cada vez mais assertivo na identificação de padrões.






[title] Configuração de painéis
[path] AIOPS/ATMOS/Hosts/

## Configuração Geral

A fim de configurar os paineis de um IC contendo gráficos para exibição, o usuário deve preencher o formulário ao clicar em "Novo Gráfico".

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/P4XUDpqE-jJq7yEYQnx5j_image.png" size="46" width="501" height="676" position="center" showCaption="false"}

| **Campo**             | **Descrição**                                                       | **Valores**                                                                                                                            |
| --------------------- | ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| Nome                  | Nome para identificação do gráfico                                  |                                                                                                                                        |
| Transformação         | Altera a forma como a métrica é interpretada indiferente da função  | - Nenhuma<br />- Derivação (converte em taxa x tempo)                                                                                  |
| Função                | Como o valor da métrica será calculado no perído escolhido.         | - Média<br />- Somatório<br />- Mínimo<br />- Máximo                                                                                   |
| Grupo                 | Grupo de métricas a ser observado.                                  | Os valores estão disponibilizados em [Explorar as Métricas](docId\:fsx3LchMawoyAXzQup_wD)                                              |
| Métrica               | Métrica a ser mostrada no gráfico.<br />Permite múltiplas seleções. | Métricas disponíveis para seleção estão documentadas no grupo escolhido.<br /><br />Ex: [Listen Process](docId\:aXiMBUjLm3Ezvud80ITuP) |
| Agrupar por           | Determina como as métricas serão visualizadas                       |                                                                                                                                        |
| Largura               | Largura de exibição do gráfico.                                     | - 25%    *(1/4 da tela)*<br />- 50%    *(2/4 da tela)*<br />- 75%    *(3/4 da tela)*<br />- 100 % *(4/4 da tela)*                      |
| Exibir valores vazios | Deixar espaços em branco onde não existem métricas.                 | - Sim     *(mantém espaço em branco)*<br />- Não     *(preenche espaços vazios)*                                                       |

## Filtros (Opcional)

Ao abrir a aba, será possível visualizar filtros já criados.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/gY4v5bD7ScMhg-1saELlr_image.png" size="50" width="501" height="281" position="center" showCaption="false"}

Ao clicar em "Novo filtro", um formulário será disponibilizado para preenchimento.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/cwuO9TiZ2b0DbUyUE_lTo_image.png" size="50" width="500" height="386" position="center" showCaption="false"}

| **Campo** | **Descrição**                              | **Valor**                         |
| --------- | ------------------------------------------ | --------------------------------- |
| Chave     | Chave para filtro por valor.               |                                   |
| Operação  | Operação lógica para o filtro.             | - Igual (=)<br />- Diferente (!=) |
| Valor     | Valor específico para o filtrar a métrica. |                                   |

## Avançado (Opcional)

A aba "Avançado" permite que o usuário construa manualmente a expressão para visualização das métricas.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/OgA-oJdlfYH1JzX0L6Vaw_image.png" size="50" width="498" height="396" position="center" showCaption="false"}


[title] Requisitos de Hardware
[path] AIOPS/INTRODUÇÃO/Requisitos/



- O AIOPS pode ser instalado tanto em ambiente *On Premise* ou *Virtual Appliance*.

## Recomendação

### Standalone (POC):

Requisitos mínimos para uma única máquina rodando em Singlenode.

| **Tamanho** | Cores (CPU) | Memória  | Disco   |
| ----------- | ----------- | -------- | ------- |
| Micro       | 4           | 8GB      | 100 GB  |
| Small       | 8           | 24 GB    | 200 GB  |
| Medium      | 16          | 32GB     | 400 GB  |
| Large       | 24          | 32 GB    | 1024 GB |

### Distribuído (Produtivo):

Requisitos mínimos (1 máquina de cada tipo), com excessão das opcionais que vão de acordo com o tipo de contrato.

| **Tipo de Instância&#x20;** | **Cores** (CPU) | **Memória**  | **Disco** (dados) | -                                                                        |
| --------------------------- | --------------- | ------------ | ----------------- | ------------------------------------------------------------------------ |
| 1. MASTER-NODE              | 8               | 16 GB        | 200 GB            | ***obrigatório***                                                        |
| 2. DB-WORKER                | 8               | 16 GB        | 500 GB            | ***obrigatório***                                                        |
| 3. ATOM-WORKER              | 4               | 8 GB         | 50 GB             | *opcional* (se utilizar:<br />SNMP, Ping,<br />Descoberta de Rede, etc.) |
| 4. APM-WORKER               | 8               | 8 GB         | 1024 GB           | *opcional&#x20;*(se utilizar: APM)                                       |



### Pontos de montagem

Os discos são montados através dos seguintes requisitos:

| **Ponto de montagem** | **Tamanho mínimo**                          |
| --------------------- | ------------------------------------------- |
| /                     | 30GB                                        |
| /tmp, /opt            | 4GB (ou equivalente ao root "/" )           |
| /dados                | *(de acordo com o tipo de instância)*<br /> |


[title] APT
[path] AIOPS/AIOPS/Inventário/Instalação dos Agents/Agent Linux/

## 1 - Adicione o repositorio do Agent:

```shell
curl -fsSL http://deb.ocsinventory-ng.org/pubkey.gpg | sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/ocs-archive-keyring.gpg
```

```shell
echo "deb http://deb.ocsinventory-ng.org/debian/ <codinome_da_distro> main" | sudo tee /etc/apt/sources.list.d/ocsinventory.list
```

```shell
sudo apt update
```

Você terá que substituir `codinome_da_distro` pelo codinome da distribuição utilizada, dependendo do contexto de instalação, **por exemplo**:

```shell
jammy    -> Ubuntu 22.04 LTS
focal    -> Ubuntu 20.04.5 LTS
bullseye -> Debian 11.0
```

## 2 - Instale o Agent:

```shell
sudo apt install ocsinventory-agent
```

### 2.1 - Selecione o método de comunicação

Durante a instalação, você será solicitado a escolher como o **agent** se comunicará com o servidor. **Selecione o método HTTP e prossiga**:

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/5FUhi8Jm8d6NY7LLqCyyY_image.png)

### 2.2 - Defina a URL

Em seguida, defina a **URL** do servidor. A sintaxe da **URL** é similar a:

```shell
http[s]://inventory-server/ocsinventory
```

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/jontS5Z-kxxRmMtkWmazc_image.png)

## Desabilite a checagem de certificado:

Adicione a flag `ssl=0` na configuração disponível no arquivo `/etc/ocsinventory/ocsinventory-agent.cfg`:

:::CodeblockTabs
Exemplo

```shell
server=http[s]://inventory-server/ocsinventory
ssl=0
```
:::

## Gerando a coleta manualmente

Para realizar a coleta manual do item, execute o seguinte comando:

```javascript
ocsinventory-agent --server http[s]://inventory-server/ocsinventory
```

## Opcional - Configure o Agent para inventariar o sistema de hora em hora por meio do cron job

```shell
mv /etc/cron.daily/ocsinventory-agent /etc/cron.hourly
```


[title] Docker Devicemapper
[path] AIOPS/MÉTRICAS/Explorar as Métricas/

Mapeamento de dispositivos de bloco físicos em dispositivos virtuais de bloco de alto nível.

| **Chave**                                                 | **Tipo** | **Descrição**                  |
| --------------------------------------------------------- | -------- | ------------------------------ |
| docker\_devicemapper.`base_device_size_bytes`             | byte     | Tamanho do "base device"       |
| docker\_devicemapper.`data_space_available_bytes`         | byte     | Espaço de dados disponível     |
| docker\_devicemapper.`data_space_total_bytes`             | byte     | Espaço de dados total          |
| docker\_devicemapper.`data_space_used_bytes`              | byte     | Espaço de dados usado          |
| docker\_devicemapper.`metadata_space_available_bytes`     | byte     | Espaço de metadados disponível |
| docker\_devicemapper.`metadata_space_total_bytes`         | byte     | Total de espaço de metadados   |
| docker\_devicemapper.`metadata_space_used_bytes`          | byte     | Espaço de metadados usado      |
| docker\_devicemapper.`pool_blocksize_bytes`               | byte     | tamanho do bloco pool          |
| docker\_devicemapper.`thin_pool_minimum_free_space_bytes` | byte     | espaço mínimo livre de pool    |


[title] Canais
[path] AIOPS/AIOPS/

Os canais são uma ponte entre equipes que precisam trabalhar juntas. Em vez de intermináveis emails, tickets manuais ou lista de alertas, as equipes podem usar canais que conectam equipes e usuários para os mesmos alertas e incidentes. Esses canais permitem que os usuários interajam entre si, e facilitam a possibilidade de notificações às equipes, permitindo inclusive a atuação de líderes para a delegação de eventuais demandas.

## Acesso

Para acessar a funcionalidade de canais é necessário acessar o ícone de configurações no menu principal do AIOPS:

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/vivJML8tz8cQTepqqJ3Vw_botaoconfiguracoes.png" size="38" position="center" showCaption="false"}

Após acessar as configurações é necessário acessar a opção canais no menu interno de opções:

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/7vYNeCg976YHDaLF_soTS_menu-configuracoes-simon.png" size="40" position="center" showCaption="false"}

## Criação de Canal

Para criar um canal é clicar no botão "novo canal":

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/1u4Z-0R-5xpC2HxEzacF-_novocanal.png" size="40" position="flex-start" showCaption="false"}

Após clicar no botão, as opções de criação de canal serão exibidas em uma modal:&#x20;

::Image[]{src="https://gblobscdn.gitbook.com/assets%2F-Ls76-8XbGuboSQAg3Y9%2F-LyVO4b6AWepWpKWRXDk%2F-LyVRChYav8wUDDGxPib%2FCaptura%20de%20Tela%202020-01-13%20a%CC%80s%2016.36.18.png?alt=media&token=09c0e847-7024-4b6c-9baa-8349bf2d5e27" size="80" showCaption="false"}

## Filtros&#x20;

Na opção **visibilidade** é possível selecionar os times que poderam ter acesso aos incidentes e eventos do canal selecionado.

É possível selecionar as **integrações** que podem inserir eventos no AIOPS, e também a prioridade desejada na composição de filtro.

Utilizando-se de **tags** é possivel filtrar utilizando texto, com as operações de igual, diferente e wildcard. As operações de igual e diferente utilizam valores exatos como filtros, a operação de wildcard, permite com que qualquer texto possa existir onde o wildcard estiver inserido, por exemplo:

- Igual ou diferente: srv-website&#x20;
- wildcard: srv-\*

Você pode compor uma regra lógica, sem a utilização de código para criação de um filtro, dessa forma é possível organizar seus incidentes/eventos por área de infraestrutura, prioridade, integração.

Dessa forma você pode direcionar seus incidentes para as equipes que necessitam de envolvimento, sem que haja rastreamento de eventos, afinal, um incidente de alto nível já contempla todos os eventos que devem contextualizar um incidente.

Dentro de cada bloco com marcador laranja, é possível a inserção de diversos filtros para as tags que compões incidentes:

![](https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/WtLzAewNB3T0dibzOTkIk_image.png)


[title] Coleta de dados
[path] AIOPS/AIOPS/Inventário/

A solução Xventory é capaz de coletar informações detalhadas sobre o hardware e software de estações de trabalho e servidores, oferecendo uma visão completa do inventário de ativos de TI de uma organização. Abaixo, estão listados os recursos relacionados ao inventário de informações de hardware e software:

### Coleta de Informações de Hardware

- O Xventory é capaz de coletar informações sobre processadores, memória, placa-mãe, interfaces de rede, protocolos de rede, BIOS, portas de entrada/saída, dispositivos, discos (físicos e lógicos), sistemas de arquivos, recursos do sistema operacional, configurações de região, controladoras (IDE, SCSI, USB) e outros componentes de hardware.
- A coleta de informações de hardware é feita de forma automatizada, permitindo que as organizações obtenham uma visão precisa e atualizada do inventário de ativos de TI.

### Coleta de Informações de Software

- Além das informações de hardware, o Xventory é capaz de coletar informações detalhadas sobre o software instalado nos dispositivos gerenciados, incluindo sistema operacional, aplicativos, drivers, atualizações e patches.
- As informações de software também são coletadas de forma automatizada, oferecendo uma visão precisa e atualizada do inventário de ativos de TI.

### Coleta de Dados de Inventário a partir de Arquivos

- O Xventory permite que as organizações coletem dados de inventário a partir do uso de arquivos, o que pode ser útil em situações em que a coleta automatizada não é possível.
- Os dados de inventário podem ser inseridos em um arquivo e importados para o Xventory, oferecendo uma visão completa e atualizada do inventário de ativos de TI.

### Coleta de Informações em Registro do Windows

- O Xventory é capaz de acessar e coletar informações em registro do Windows, oferecendo uma visão precisa e atualizada do inventário de ativos de TI.
- As informações coletadas incluem informações de hardware e software, permitindo que as organizações obtenham uma visão completa do inventário de ativos de TI.
- O Xventory é capaz de acessar e coletar informações também de "Programas e Recursos" do Windows.

### Coleta de Informações via comunicação externa

O Xventory também oferece ampliação da capacidade com orquestração e comunicação através de:

- Capacidade de coletar informações detalhadas sobre o hardware e software de estações de trabalho e servidores através de comunicações externas ou integrações.
- Funcionalidades de coleta de informações de hardware e software e do inventário de softwares.
- Possibilidade de capturar informações de forma ativa.
- Integração com outras ferramentas de monitoramento, como Zabbix, Nagios, Datadog, Dynatrace, SolarWinds, Cloudwatch, etc.
- Integração com outras ferramentas de monitoramento por meio da utilização do motor de pipes.
- Enriquecimento das informações de inventário de ativos de TI com dados de monitoramento em tempo real.
- Visão mais completa e precisa do ambiente de TI.
- Automatização de fluxos de trabalho.
- Facilidade de integração das informações coletadas pelo Xventory com outras ferramentas de gestão de TI.
- Solução completa e flexível para o gerenciamento de inventário de ativos de TI.
- Adequação às necessidades de diferentes tipos de organizações e ambientes de TI.

### Visão completa e atualizada&#x20;

Essa funcionalidade permite que as organizações tenham uma visão completa e atualizada dos softwares instalados nos dispositivos gerenciados, incluindo versões e informações adicionais sobre os softwares. A coleta de informações é feita de forma automatizada, o que garante que as informações de software estejam sempre atualizadas e precisas.

Com o inventário de softwares do Xventory, as organizações podem gerenciar melhor as licenças de software, identificar softwares desnecessários ou obsoletos e garantir a conformidade com as políticas de segurança da informação. Além disso, é possível gerar relatórios detalhados sobre o inventário de softwares, permitindo que as organizações tenham uma visão completa e precisa sobre os softwares instalados nos dispositivos gerenciados.

### Ativos de TI

Em resumo, a solução Xventory é capaz de coletar informações detalhadas sobre o hardware e software de estações de trabalho e servidores, oferecendo uma visão completa do inventário de ativos de TI de uma organização. A coleta de informações é feita de forma automatizada, permitindo que as organizações obtenham uma visão precisa e atualizada do inventário de ativos de TI. Além disso, o Xventory permite que as organizações coletem dados de inventário a partir do uso de arquivos e acessem informações em registro do Windows, oferecendo uma visão completa e atualizada do inventário de ativos de TI.

### Sistemas operacionais

Além disso, é importante destacar que as informações de hardware e software também podem ser coletadas em diferentes sistemas operacionais, como Linux e Windows. O Xventory é capaz de coletar informações de dispositivos gerenciados em diferentes plataformas, oferecendo uma visão abrangente e precisa do inventário de ativos de TI. Dessa forma, as organizações podem ter uma visão completa e atualizada do inventário de ativos de TI em diferentes sistemas operacionais, permitindo um gerenciamento mais eficiente e preciso.

### Utilização

Além da coleta de informações de hardware e software, e do inventário de softwares, o Xventory também oferece a possibilidade de medir o uso de softwares de forma passiva.

Essa funcionalidade permite que as organizações coletem dados estatísticos de utilização de aplicações monitoradas, sem a necessidade de interação do usuário ou instalação de agentes adicionais. Os dados são coletados automaticamente e enviados ao gerenciamento da solução, permitindo que as organizações tenham uma visão completa e atualizada sobre o uso dos softwares em seus dispositivos gerenciados.

Com a medição passiva de uso de softwares, as organizações podem identificar quais softwares são mais utilizados e por quem, permitindo uma melhor gestão de licenças e garantindo a conformidade com as políticas de segurança da informação. Além disso, é possível identificar possíveis problemas de desempenho ou falhas nos softwares, permitindo uma correção mais rápida e eficiente.

O Xventory oferece relatórios detalhados sobre o uso de softwares, permitindo que as organizações tenham uma visão completa e precisa sobre o uso dos softwares em seus dispositivos gerenciados. Dessa forma, as organizações podem tomar decisões mais assertivas e eficientes sobre a gestão de seus ativos de TI.

Concluindo, o Xventory é capaz de medir o uso de softwares de forma passiva, coletando dados estatísticos de utilização de aplicações monitoradas e enviando ao gerenciamento da solução para posterior uso em análises do ambiente.&#x20;

[title] Traceroute
[path] AIOPS/ATMOS/

As ferramentas de rede no Atmos contam com testes de traceroute para determinar o rastreio de pacotes da rede e sua conectividade.

Para acesso aos traceroutes, clique no botão **Rede** e em seguida, no menu superior, no botão **Traceroutes**.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/rf8qfW_SmilzLiqvWykHI_image.png" size="20" width="146" height="56" position="center" showCaption="false"}

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/1iYr-WCg9PLoO7UzanO65_image.png" size="38" width="330" height="96" position="center" showCaption="false"}

A tela com a lista de traceroutes cadastrados será exibida.

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/lXfUq964GxJAnJ5eT5K2R_image.png)

## Criando uma rotina de testes do Traceroute

Ao clicar no botão **Novo traceroute**, no canto superior direito, a seguinte janela será exibida:

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/5f4Tr0GukJiqfIrh15-ZG_image.png" size="80" width="805" height="630" caption="Aba Geral" position="center" showCaption="true"}

- **Nome**: Nome do grupo de testes;
- **Intervalo**: Intervalo de execução dos testes;
- **Saltos**: Número de saltos máximos a serem executados pelo traceroute;
- **Timeout**: Tempo limite para a execução do traceroute (para cada teste individual)
- **Tentativas**: Número de tentativas de execução;
- **Tipo**: Qual tipo de endereços IP utilizar (Quando não selecionado apenas o IP primário é utilizado por padrão);
  - **Somente IPs Públicos:** Selecione o principal *IP Público* do Item de Configuração (quando existir)
  - **Somente IPs Privados:** Selecione o principal *IP Privado* do Item de Configuração (quando existir)
- **Interface***&#x20;(Opcional)*: Interface que será utiulizada para execução dos testes (é necessário obter o nome da interface desejada na instância *atom-worker&#x20;*&#x64;o AIOPS)
- **Descrição** (Opcional): Descritivo do grupo de teste

### Escopo

A aba escopo define a origem dos IPS de destino deste grupo de coleta do traceroute (IP primário presente nos itens de configuração).&#x20;

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/wGjv1IwLu3kIl-TYFE7OE_image.png" size="80" width="808" height="526" position="center" showCaption="false"}

:::hint{type="info"}
Para cada grupo de teste são escolhidos os *IPs* por Item de Configuração de acordo com o tipo definido da *Aba Geral*.&#x20;
:::

# Executando um teste do Traceroute

Este teste é executado em tempo real e não gera métricas, apenas retorna o resultado do traceroute para visualização.
Ao clicar no botão **Testar configuração de Traceroute&#x20;**&#x20;a janela a seguir será exibida:

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/f2REpTmzu7XKVa2-3j2Ev_image.png" size="80" width="759" height="406" position="center" showCaption="false"}

- **Destino**: Endereço de destino a ser executado (IP ou Domínio);
- **Interface***&#x20;(Opcional)*: Interface que será utiulizada para execução dos testes (é necessário obter o nome da interface desejada na instância *atom-worker&#x20;*&#x64;o AIOPS)
- **Saltos**: Número máximo de saltos na execução;
- **Timeout**: Tempo limite na execução do teste;
- **Tentativas**: Número de tentativas na execução.

### Resultado do teste

Na execução bem sucedida de um teste de traceroute a aba de resultados será exibida com o seguinte valor de exemplo:

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/keKcFE5l5qcrxzJzvh286_image.png" size="80" width="759" height="478" caption="Teste realizado com o dominio google.com.br" position="center" showCaption="true"}

O resultado é um objeto do tipo JSON que contém as seguintes informações:

```json
{
    "address": "google.com.br"                  // destino do teste
    "elapsed_time_ms": 435,                     // tempo total (todos os saltos) em milliseconds
    "hops": [
        {
            "hop": 1,                   
            "success": true,            
            "address": "177.20.14.3",   
            "host": "177.20.14.3",     
            "rtt": 0 
        },
        // {...}
        {
            "hop": 13,                          // número do salto 
            "success": true,                    // se o probe retornou sucesso nesse salto
            "address": "172.217.162.13",        // ip do salto
            "host": "gru14s19-in-f3.1e100.net", // dominio ou ip resolvido
            "rtt": 28                           // tempo em ms do retorno do salto 
        }
    ],
    "hops_count": 13,                           // quantidade de saltos 
    "host": "google.com.br",                    // dominio do teste
    "ip": "172.217.162.131",                    // ip resolvido do dominio do teste
    "probe_version": "traceroute/binary:v1",    // versão do traceroute utilizado
    "reached": true                             // se o destino foi alcançado com sucesso
}
```

## Gráfico de execução

Ao clicar no botão Gráfico de execução é possível visualizar as métricas salvas dos traceroutes realizados na rotina.&#x20;

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/vZUdO0JgnEYTU7lpTmjQx_image.png" size="30" width="172" height="80" position="center" showCaption="false"}

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/DtHkOlw72yxQ7kHP8j32d_image.png)


[title] Atuação em Incidentes
[path] AIOPS/AIOPS/Incidentes/

Com o AIOPS é possível entender em alto nível, os problemas que estão acontecendo em sua operação, suprimindo ruídos (evitando a geração de alertas desnecessários, desconsiderando ICs não relacionados, através de PRCA), contextualizando e agrupando alertas que são fundamentais, de acordo com tipos de falhas, para identificação de causa raiz. Permitindo a criação de formatos de falhas que serão usadas posteriormente não só para contextualizar, como também para treinar a Inteligência Artificial.

## Análise da Causa Raiz

Ativando a funcionalidade de RCA Autônoma do AIOPS, é possível suprimir alertas com base em suas dependências/relações topológicas. Dessa forma, é possível visualizar apenas o que realmente está causando o problema detectado.

![](https://gblobscdn.gitbook.com/assets%2F-Ls76-8XbGuboSQAg3Y9%2F-LsS4TFxl19M8_Q9JDeW%2F-LsS4cYTYGbvGQVjC3n6%2FDetalhes-do-Incidente-Completo.png?alt=media\&token=5e4e62ca-eb09-4145-9aba-b246854268d9)



Dentro da opção Lab This([Correlação de Eventos](docId\:ddgCKkFzvVixxRBz3qncX))   a  plataforma permite a escolha da causa raíz pelo usuário, com intuito de determinar o motivo das falhas em geral, possibilitando que o AIOPS reconheça o problema em caso de reincidências.

Para executar essa operação, basta clicar no botão que se encontra ao lado direito, dentro da lista de alertas.

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/fNVo-KJWofXulu_ZaEKqN_Screen%20Shot%202021-01-10%20at%2011.16.41.png" size="18" caption="Definir como Causa Raiz" position="center" showCaption="true"}

Na inexistência da necessidade de atuação imediata, o usuário poderá clicar no botão **Suspender Incidente&#x20;**&#x71;ue se encontra logo acima à direita da listagem de alertas.



::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/TW8pkOY0RHhgEKQir2bKX_Screen%20Shot%202021-01-10%20at%2011.23.28.png" size="22" caption="Suspender incidente, primeira opção da esquerda para a direita" position="center" showCaption="true"}

Após finalizar, a operação poderá ser ecerrada manualmente através do botão que se encontra próximo ao botão Suspender Incidente, já citado.



::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/q7spOAibL7uV7JU3bEmra_Screen%20Shot%202021-01-10%20at%2011.23.28.png" size="26" caption="Concluir manualmente, primeira opçãoda direita para esquerda" position="center" showCaption="true"}

## Sugerir Pipe

No botão **Sugerir pipe** que se encontra ao lado do botão Mover Alertas é possível escolher o fluxo de automação ([Pipes e Automação](docId\:QYEmgXVWSXSgczlV_aDWF)) mais indicado para o alerta selecionado

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/2y2DhcjFkIj96PjbrnyJJ_Screen%20Shot%202021-01-09%20at%2017.38.14.png" size="24" position="center" showCaption="false"}

## Habilitar para Treino

Caso o incidente esteja agrupado adequadamente é possível habilita-lo para treino uilizando o botão **Habilitar para Treino**, que se encontra no canto superior direito da tela, acima da lista de alertas.

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/MHUgmjK6dR8l6Ds367C5F_Screen%20Shot%202021-01-09%20at%2017.41.19.png" size="40" position="center" showCaption="false"}

Ao selecionar essa opção permitirá que o AIOPS se torne cada vez mais assertivo na identificação de padrões.






[title] Integração com o Zabbix
[path] AIOPS/AIOPS/Integrações/Criando uma integração/

:::hint{type="info"}
O Simon importa alertas e hosts do Zabbix.

Cada incidente criado no AIOPS importado dos alertas do Zabbix faz a correlação e cria um ticket.
:::

1 - Para integrar o Zabbix ao AIOPS, acesse a página do AIOPS e clique no terceiro item da coluna da esquerda (Integrações):

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/vDDWaaI2SAKBIsVhJcHbU_captura-de-tela-2023-10-05-as-55700-pm.png "Integração")

2 - No canto direito superior clique em "+ Nova integração"

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/Q_iHXvvJU9kqv_3WpDG1A_captura-de-tela-2023-10-05-as-55803-pm.png "Nova Integração")

3 - Dê o nome para essa integração e coloque Monitoramento no campo "Tipo"&#x20;

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/dZ59arGgwLpayF5tQOqym_captura-de-tela-2023-10-05-as-55852-pm.png "Tipo do módulo")

4 - No campo Módulo escolha Zabbix.

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/Jjhb-ooDtsqsIBxy4xk3e_captura-de-tela-2023-10-05-as-55920-pm.png "Módulo")

5 - Na aba "Autenticação", coloque a URL do host onde o Zabbix está hospedado. Preencha com o Usuário e com a senha do Zabbix. &#x20;

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/skNtJiAN9V1RsVy4P2I-E_captura-de-tela-2023-10-06-as-92038-am.png "Detalhes")



6 - Execute o teste de conexão a fim de validar a integração.

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/ShKIlA1mEKwzPx96qjUHH_captura-de-tela-2023-10-06-as-90318-am.png "Teste de conexão")

7 - Salve a integração.

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/eBCpU2iIV0KNIeH0U1z-f_captura-de-tela-2023-10-06-as-92550-am.png "Salvar")


[title] Serviços de TI
[path] AIOPS/ATMOS/

Gerencie seus serviços aglomerando servidores que possam estar próximos fisicamente, virtualmente ou em cloud, com mapas visuais que podem contemplar arquiteturas híbridas. Crie dependências de aplicações com recursos existentes de vários itens de configuração e organize hierarquicamente da melhor forma que represente seu ambiente. Podendo representar, serviços de alto nível, regiões, filiais, aplicações e etc.

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/bLZR6pHKm08sSzle4qZUx_screen-shot-2021-06-16-at-172955.png)

## Acesso

Para acessar a aplicação Atmos é necessário clicar no botão "aplicações" localizado no canto inferior esquerdo, do menu principal no AIOPS.

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/_dl2iGnL-Fm4SOb1vBfhr_image.png" size="70" position="center" showCaption="false"}

Após acessar o Atmos é necessário acessar a tela de serviços de TI através do menu principal:

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/mwgPMZkrFEW7OOv-wL9c2_image.png" size="70" position="center" showCaption="false"}

Ao acessar a tela de serviços de TI será possível ver a listagem de serviços criados:

![](https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/lz5xj6xYA33Tjd6z0x7Ub_image.png)

### Changelog

Através de changelog, o Atmos mantém em archives, todo o histórico de updates realizados em cada serviço de TI, sendo possível auditar todas as mudanças realizas, observando quem foi o autor e as datas em que os eventos de criação, mudança e deleção aconteceram. 

### Topologia

Através do serviços de TI é possível filtrar a topologia ([Topologia](docId\:UFxgZ3HWR0lR8EyHa6-lf) ) de acordo com as dependências do usuário utilizando o botão de topologia que se encontra em cada item da listagem:

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/jjulfjIq9sBaWb3wLdGl6_servicos-filtro-topologia.png" size="36" position="center" showCaption="false"}

## Criando um novo serviço de TI

Para criar um novo serviço de TI é necessário clicar no botão "Novo serviço" que se encontra no topo lateral direito:&#x20;

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/9eEWHZ9Q7qrx9jjXPDI2a_image.png" size="44" position="center" showCaption="false"}

Após o clique no botão, a tela de criação se apresentará:

![](https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/9OUGh0ARdV1HV4hJc2lHG_image.png "Tela para criação e edição de serviço")

### Configurações iniciais

Para configurar as informações básicas do serviço de TI é necessário acessar o botão de configuração no topo superior direito:

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/8pnx52j27KoZRkgdXGXW2_image.png" size="34" position="center" showCaption="false"}

Após clicar nesse botão, um modal se abrirá com as seguintes informações:&#x20;

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/DuNYnh2YPKlsl2IuapOQ5_image.png" size="52" position="center" showCaption="false"}

Onde é possível, definir o **nome do serviço de TI**, definir a **prioridade** que esse serviço possui e definir o **tempo de atividade** que esse serviço deve possuir para cálculos de SLA e uptime.

### Criando agrupamentos

Ao centro da tela é possível ver um botão com a seguinte característica:

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/tu626oJUWLbKnVKAWRX9o_image.png" size="44" caption="Adicionar grupo" position="center" showCaption="true"}

Após apertar esse botão, automaticamente um novo grupo de itens de configuração será adicionado, o objetivo da criação de grupos é poder criar regras onde cada grupo impacte de forma independente o SLA do serviço em questão, além de organizar as dependências de forma simples e rápida.

Para configurar um novo grupo é necessário clicar no botão que possui três pontinhos:

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/uY_PRtPTUz61QyAWRhTWU_image.png" size="54" position="center" showCaption="false"}

Então um modal se abrirá de seguinte forma:

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/FBB1ETz_m5cz5ZlDtlGQh_image.png" size="66" position="center" showCaption="false"}

Nesse modal é possível determinar:

- Nome
  - O nome do serviço em questão
- O SLA mínimo
  - &#x20;Definir qual o limite que pode ser atingido
- O tipo de SLA
  - &#x20;Define se o grupo em questão pode impactar o SLA do serviço, somente SLA do próprio grupo ou não causar nenhum impacto
- O impacto do SLA
  - Define se o SLA definido no tipo de SLA será impactado caso qualquer item tenha problema ou se apenas todos tiverem algum problema.
- Números de colunas que ocupará na tela
  - O tamanho do agrupamento que será visualizado na tela de visualização de serviços de TI

### Adicionando itens ao grupo

Após configurar o grupo, é possível começar a inserir os itens de configuração ou serviços já criados anteriormente que pertecem a esse grupo:

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/pwvrdMCOMPhmEG0XTMStB_image.png" size="48" position="center" showCaption="false"}

### Definindo problemas que podem impactar o serviço

Ao inserir um item de configuração é possível definir qual problema (trigger acionada) pode impactar o SLA do serviço criado:&#x20;

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/eUN570r0WfJqtv9uJJ1DB_image.png" size="84" position="center" showCaption="false"}

### Exemplo de serviço criado

Abaixo temos um exemplo de serviço criado representando uma aplicação, com os itens que compõe toda a pilha:

![](https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/EKzoJe0MJzqMosew3Ijls_image.png "Exemplo aplicação web")


[title] Inventário
[path] AIOPS/AIOPS/

Bem-vindo à página de documentação do xventory, módulo do AIOPS para inventário de ativos de TI. Este software é uma ferramenta usada para gerenciar e rastrear ativos de hardware e software em uma organização. Esta solução é capaz de processar modelos de política de configuração e tomar decisões automatizadas baseadas em scripts. Isso pode ajudar a automatizar tarefas repetitivas e reduzir a carga de trabalho dos administradores de sistema.Seja bem-vindo à página de documentação do Xventory, o módulo do AIOPS que oferece recursos para o gerenciamento e rastreamento de ativos de hardware e software em organizações. Com o Xventory, é possível obter uma visão completa e atualizada do inventário de ativos de TI, permitindo que as organizações tomem decisões mais informadas sobre o gerenciamento de seus ativos. Além disso, o Xventory é capaz de processar modelos de política de configuração e tomar decisões automatizadas baseadas em scripts, o que pode ajudar a automatizar tarefas repetitivas e reduzir a carga de trabalho dos administradores de sistema.

O Xventory oferece uma série de recursos avançados para o gerenciamento de inventário de ativos de TI, como a coleta de informações detalhadas sobre o hardware e software de estações de trabalho e servidores, incluindo informações de sistema operacional, aplicativos, drivers, atualizações e patches. Além disso, é possível coletar informações a partir de arquivos e em registro do Windows, permitindo uma visão completa e atualizada do inventário de ativos de TI.

Com o Xventory, as organizações podem gerenciar melhor as licenças de software, identificar softwares desnecessários ou obsoletos e garantir a conformidade com as políticas de segurança da informação. Além disso, o software oferece a possibilidade de  integrar-se com outras ferramentas de monitoramento, como Zabbix, Nagios, Datadog, Dynatrace, SolarWinds e CloudWatch, por meio da utilização de pipes.

O Xventory é uma solução flexível e completa para o gerenciamento de inventário de ativos de TI, adequada às necessidades de diferentes tipos de organizações e ambientes de TI. Com recursos avançados e a capacidade de automatizar tarefas, o Xventory pode ajudar as organizações a reduzir a carga de trabalho dos administradores de sistema e aumentar a eficiência e precisão na gestão de seus ativos de TI.

Em resumo, o Xventory é uma ferramenta essencial para o gerenciamento de inventário de ativos de TI, capaz de oferecer uma visão completa e atualizada do inventário de ativos de hardware e software de uma organização. Com recursos avançados para a coleta de informações, automatização de tarefas e integração com outras ferramentas de monitoramento, o Xventory é uma solução completa e flexível para o gerenciamento de ativos de TI, que pode ajudar as organizações a aumentar a eficiência e precisão na gestão de seus ativos de TI.


[title] Diskio
[path] AIOPS/MÉTRICAS/Explorar as Métricas/

O plugin de `diskio` coleta métricas sobre o tráfego e o tempo do disco.

| **Chave**                 | **Tipo**                 | **Descrição**                                                                                                                                                                                                      |
| ------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| diskio.`io_time`          | time<br />(milliseconds) | Milissegundos durante os quais o dispositivo teve solicitações de I/O enfileiradas.                                                                                                                                |
| diskio.`iops_in_progress` | gauge                    | Solicitações I/O emitidas para o driver de dispositivo que ainda não foram concluídas. <br />Não inclui solicitações de I/O que estão na fila.                                                                     |
| diskio.`merged_reads`     | counter                  | Número de leituras de disco, que foram mescladas em operações de acesso a um único disco físico.                                                                                                                   |
| diskio.`merged_writes`    | counter                  | Número de gravações em disco, que foram mescladas em operações de acesso a um único disco físico.                                                                                                                  |
| diskio.`read_bytes`       | bytes                    | Este valor conta o número de bytes lidos nos discos.                                                                                                                                                               |
| diskio.`read_time`        | time<br />(milliseconds) | Quantidade de tempo em milisegundos em que as solicitações de leitura esperaram nos discos.<br /><br />Se houver várias solicitações de I/O em espera, esses valores aumentarão a uma taxa maior que 1000/segundo. |
| diskio.`reads`            | counter                  | Este valor aumenta quando uma solicitação de I/O é concluída.                                                                                                                                                      |
| diskio.`weighted_io_time` | time<br />(milliseconds) | Quantidade de tempo em milissegundos que as solicitações de I/O esperam neste dispositivo. <br /><br />Se houver várias solicitações de I/O em espera, esses valores aumentarão a uma taxa maior que 1000/segundo. |
| diskio.`write_bytes`      | bytes                    | Número de bytes gravados neste dispositivo.                                                                                                                                                                        |
| diskio.`write_time`       | time<br />(milliseconds) | Quantidade de tempo em milisegundos em que as solicitações de leitura esperaram nos discos.<br /><br />Se houver várias solicitações de I/O em espera, esses valores aumentarão a uma taxa maior que 1000/segundo. |
| diskio.`writes`           | counter                  | Quantidade de operações de gravação em disco.                                                                                                                                                                      |


[title] Integrações
[path] AIOPS/AIOPS/

AIOPS possui quatro tipos de integração:

- Monitoramento
- Notificações
- ITSM/SDM
- Autenticação

## Monitoramento

As integrações do tipo **monitoramento** permite que os alertas e métricas dos servidores sejam coletadas dos sistemas de monitoramento como Zabbix, Nagios, CloudWatch, Datadog, Dynatrace, Solarwinds dentre outros. Estes alertas coletado são insumos para a criação de incidentes.

## Notificação&#x20;

Já as de **notificação** permite compartilhar as informações de incidentes gerados, em diferentes canais de comunicação, como twillio, sms e e-mail, ampliando o leque de capacidade comunicativa das equipes, permitindo acionamento rápido e eficaz.

## ITSM/SDM

Esse tipo de integração permite compartilhar as informações de incidentes gerados, possibilitando a rastreabilidade e acompanhamento de incidentes via ITSM/SDM, podendo assim criar novos chamados e atribuí-los a um problema específico.

## Autenticação&#x20;

As integrações do tipo autenticação permitem que o AIOPS possa utilizar usuários e autenticações oriundas de outras fontes como por exemplo AD/LDAP, permitindo uma implatação mais ágil e inserção do time na ferramenta em pouquíssimo tempo.

## Pipes

O AIOPS possui a capacidade de criação de fluxos para automações simples e complexas, seja para autorecuperação, execuções rotineiras ou orquestrações, podendo se comunicar de diversas formas com diversas tecnologias distindas utilizando diferentes protocolos sendo, UDDI, SSH, SMTP, POP, REST, TELNET, SOAP, WSDL além de poder trabalhar com diversos formatos com YAML, JSON, XML, e HTML.

[title] Times
[path] AIOPS/AIOPS/

## Criando equipes

A colaboração entre membros de diferentes equipes, é um dos pilares do AIOPS. No AIOPS é possível criar equipes e definir líderes para as mesmas, proporcionando não só o direcionamento ideal de incidentes para quem realmente precisa atuar, mas também a redução de informação que precisa ser vista por um analista, simplificando o processo de troubleshoot.

Na barra lateral canto inferior da tela ao clicar na opção configurações um modal se abrirá contendo opções para a inserção de equipes e colaboradores.

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/3DjnWxDybUirslPuODoSJ_Screen%20Shot%202021-01-10%20at%2011.52.05.png" size="10" caption="Botão Configurações" position="center" showCaption="true"}

![](https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/wezLBVEjCURm5nfcV_fEg_Screen%20Shot%202021-01-10%20at%2012.16.41.png)

No botão Inserir times, no canto superior direito da tela, é possível inserir times, listando os profissionais que fazem parte de cada time em questão.

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/STetFKlv-2e07xePjrUWD_Screen%20Shot%202021-01-10%20at%2012.18.08.png" size="24" position="center" showCaption="false"}

![](https://gblobscdn.gitbook.com/assets%2F-Ls76-8XbGuboSQAg3Y9%2F-LsISqo_jP5aeNz0jIkf%2F-LsIcHy6pv1dzGTZ-0xb%2FCaptura%20de%20Tela%202019-10-28%20a%CC%80s%2015.27.28.png?alt=media\&token=cd224888-4c43-4d49-b4cf-9ecf736a1743 "Modal para inserção de usuários em times específicos.")

## Atribuindo responsáveis

Seja na tela de listagem de incidentes ou no detalhamento de incidente, é possível que você atribua membros de suas equipes para acompanhamento de diferentes problemas, facilitando não só a atuação como também a colaboração entre os profissionais envolvidos.


![](https://gblobscdn.gitbook.com/assets%2F-Ls76-8XbGuboSQAg3Y9%2F-LsISqo_jP5aeNz0jIkf%2F-LsI_1GFaIyBydpGlRel%2FCaptura%20de%20Tela%202019-10-28%20a%CC%80s%2015.09.08.png?alt=media\&token=8d8690e7-b9e0-4c6d-baba-83dc75998fc3)

Colabore com os membros de uma equipe, observando e contribuindo em comentários de incidentes, funcionalidade disponível através do ícone (Comentar) abaixo, na tela de detalhamento de incidente, ou no dropdown, na listagem de incidente.

::Image[]{src="https://gblobscdn.gitbook.com/assets%2F-Ls76-8XbGuboSQAg3Y9%2F-LsISqo_jP5aeNz0jIkf%2F-LsIbCIiQ7N2siNmGPoL%2FCaptura%20de%20Tela%202019-10-28%20a%CC%80s%2015.21.08.png?alt=media&token=f9806c7c-54ae-4575-a770-79ce8f9f5507" size="20" caption="Dropdown da listagem de incidentes" position="center" showCaption="true"}

::Image[]{src="https://gblobscdn.gitbook.com/assets%2F-Ls76-8XbGuboSQAg3Y9%2F-LsISqo_jP5aeNz0jIkf%2F-LsIaAVzYH4mEQZcR8ZR%2FCaptura%20de%20Tela%202019-10-28%20a%CC%80s%2015.18.48.png?alt=media&token=ece816a3-5bc9-46b1-bed2-3a286b3d0e75" size="68" position="center" showCaption="false"}

## Principais Funcionalidades:

- [ ] Possibilidade de atuação de membros entre equipes
- [ ] Atribuição de líderes
- [ ] Deleção de membros
- [ ] Atualização de Membros




[title] Eventos e Incidentes
[path] AIOPS/AIOPS/Dashboards/

Monitore os seus eventos, fornecendo à sua equipe de operações uma visão histórica da saúde operacional, contemplando os itens mais recorrentes para atuação preventiva com o objetivo de redução de problemas.

## Visualizando seus dados de eventos e coleções

Para acessar a dashboard de eventos e incidentes é necessário acessar o seguinte botão no menu principal (lateral esquerda):

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/L_Zue1OMMhCNRxMkO-YXt_dashboard-eventos.png" size="16" position="flex-start" showCaption="false"}

## Informações disponíveis

- Eventos mais reincidentes por host e por categoria

![](https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/nwC3CeUQ2Ae5yb9GUxaCJ_dashboard-categorias-alertas%5D.png)

- Coleções e eventos diários&#x20;

![](https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/Y9Sh2EJ80BgYBYw-S51JD_collectionsxevents-dashboard.png)

- Redução de ruído

![](https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/QyCNGkSFnoot5zQiiRo_g_collectionsxevents-noise-dashboard.png)








[title] DiveDot
[path] AIOPS/AIOPS/Usuários/Permissões por Roles/

## Funcionalidades

|                                                                        | **Administrador** | **Analista** | **Gestor**      | **Supervisor**  | **Operador** |
| ---------------------------------------------------------------------- | ----------------- | ------------ | --------------- | --------------- | ------------ |
| **Traces**                                                             | Acesso total      | Acesso total | Somente leitura | Somente leitura | Sem acesso   |
| **Serviços**                                                           | Acesso total      | Acesso total | Somente leitura | Somente leitura | Sem acesso   |
| ****[RUM Explorer](https://docs.simonops.com/real-user-monitoring)**** | Acesso total      | Acesso total | Somente leitura | Somente leitura | Sem acesso   |
| **Aplicações**                                                         | Acesso total      | Acesso total | Somente leitura | Somente leitura | Sem acesso   |
| **Erros**                                                              | Acesso total      | Acesso total | Somente leitura | Somente leitura | Sem acesso   |
| **Web Sites**                                                          | Acesso total      | Acesso total | Somente leitura | Somente leitura | Sem acesso   |



## Configurações

### Chaves

|              | **Administrador** | **Analista** | **Gestor**      | **Supervisor**  | **Operador** |
| ------------ | ----------------- | ------------ | --------------- | --------------- | ------------ |
| **API Keys** | Acesso total      | Acesso total | Somente leitura | Somente leitura | Sem acesso   |


[title] Agendamentos
[path] AIOPS/ATMOS/

A funcionalidade Agendamentos possibilita a execução de automações rotineiras e/ou pontuais, podendo criar automações que permitem auditorias rotineiras, auto adaptação de ambientes e grandes cargas de trabalho, envios de relatórios e comunicações por diferentes canais como slack, e-mail, twillio, telegram, etc, podendo contemplar o anexo de e-mail e o upload de arquivos para diferentes locais como storages em nuvem, datalakes, servidores de arquivo (ftp, dropbox, googledrive, onedrive).&#x20;

Para iniciar o Agendamento, acesse o botão planejamento na coluna lateral esquerda da tela:

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/XLgdulGwbTvlgTGcd2peg_Screen%20Shot%202021-01-10%20at%2018.33.48.png" size="10" caption="Botão Planejamento" position="center" showCaption="true"}

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/q-HNCns2ufzJPf2TlmN2c_Screen%20Shot%202021-01-11%20at%2009.49.49.png" size="26" caption="Botão de acesso aos Agendamentos, logo abaixo do Plano de Manutenção na lateral esquerda da tela." position="center" showCaption="true"}

Na tela de Agendamentos o acesso às atividades previamente será possível, como também ao filtro das mesmas, para facilitar o acompanhamento pelo usuário.

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/N15PYW8aRgCOp5PDWfkv__Screen%20Shot%202021-01-11%20at%2009.55.46.png" size="28" caption="Filtro, coluna esquerda da Tela " position="center" showCaption="true"}

![](https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/ge47YOtfGtKezb2FGp2MS_Screen%20Shot%202021-01-11%20at%2010.04.51.png "Listagem de agendamentos prévios")

Um novo agendamento poderá ser realizado através do botão(exemplo abaixo), que se encontra na lateral superior direita da tela.

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/mzJbnczC41BQq7YSSE768_Screen%20Shot%202021-01-11%20at%2010.08.37.png" size="26" position="center" showCaption="false"}

Após o acesso, um modal será aberto apresentando abas com opções específicas para cada necessidade:

![](https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/euCPmbjpAMTsFcpQ0niUt_Screen%20Shot%202021-01-11%20at%2010.11.18.png)

Na aba Pipes([Pipes e Automação](docId\:QYEmgXVWSXSgczlV_aDWF)) será possivel a seleção de um fluxo para a execução.

![](https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/ikM6crfGY2FKWvdayKSzv_Screen%20Shot%202021-01-11%20at%2010.14.12.png)


[title] Dashboards
[path] AIOPS/AIOPS/

Os painéis de dashboards da plataforma Simon fornecem uma visão geral de suas métricas de saúde operacional em uma visão consolidada para acompanhamento de métricas chave. É ideal para manter a operação atualizada com os status mais recentes além de atender suas possíveis necessidades de negócios.


[title] MÉTRICAS
[path] AIOPS/


[title] Docker Container CPU
[path] AIOPS/MÉTRICAS/Explorar as Métricas/

O plugin coleta métricas sobre as CPUs de um contêiner docker.

| **Chave**                                                      | **Tipo** | **Descrição**                                                                                                                                                                            |
| -------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| docker\_container\_cp&#x75;**.**`container_id`                 | string   | ID do contêiner que você estará monitorando.                                                                                                                                             |
| docker\_container\_cp&#x75;**.**`throttling_periods`           | counter  | Número total de vezes que o contêiner poderia ter sido regulado.                                                                                                                         |
| docker\_container\_cp&#x75;**.**`throttling_throttled_periods` | counter  | Número total de vezes que o contêiner foi regulado.                                                                                                                                      |
| docker\_container\_cp&#x75;**.**`throttling_throttled_time`    | time     | Quantidade de tempo em que o contêiner foi regulado, em microssegundos.                                                                                                                  |
| docker\_container\_cp&#x75;**.**`usage_in_kernelmode`          | time     | Número em nanossegundos de uso total da CPU que foi gasto em encadeamentos no nível do kernel do sistema.                                                                                |
| docker\_container\_cp&#x75;**.**`usage_in_usermode`            | time     | Número em nanossegundos do uso total da CPU gasto do usuário.                                                                                                                            |
| docker\_container\_cp&#x75;**.**`usage_percent`                | percent  | Uso da CPU em porcentagem, do total disponível.                                                                                                                                          |
| docker\_container\_cp&#x75;**.**`usage_system`                 | counter  | Uso da CPU utilizado pelo próprio sistema.                                                                                                                                               |
| docker\_container\_cp&#x75;**.**`usage_total`                  | time     | Essa métrica é a soma de todas as métricas de uso por CPU. <br /><br />Representa o número total de nanossegundos que todas as CPUs estiveram em uso desde que o contêiner foi iniciado. |


[title] Descoberta Automática
[path] AIOPS/ATMOS/

:::hint{type="info"}
A descoberta automática de hosts em uma rede e a coleta de métricas também é possível através do protocolo SNMP. Para configurar o acesso aos hosts que possibilitam essa coleta nos protocolos disponíveis (v2c e v3) siga os passos a seguir:
:::



## 1. Ao acessar o Atmos, navegue até o sétimo item da coluna à esqueda (Rede)

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/VzCSFECqaUQpj0wvrUZVX_captura-de-tela-2023-10-16-as-104201-am.png)



## 2. Clique no quarto ícone da barra superior (Descobertas automáticas)

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/OkSyxjVdwquifkx8_F8hB_captura-de-tela-2023-10-16-as-21554-pm.png)



## 3. No canto superior direito clique em "+ Nova descoberta automática"

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/g8_hqGRET9D2SdlwZn5zr_captura-de-tela-2023-10-16-as-21923-pm.png)



## 4. Preencha o formulário conforme a definição dos dados

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/2tIkPZkrKWJ2y7JaERjR8_captura-de-tela-2023-10-16-as-22041-pm.png)

- **Nome**: Nome da descoberta a ser cadastrada;
- **Tipo**: Tipo do descoberta, tem a opção de padrão e detalhado. Caso seja escolhido a opção detalhado é liberado a opção profundidade para preencher;
- **Profundidade:** define quais devices devem ser listados de acordo com as camadas de rede.
- **Coletor**: Define qual instalação da Atom Worker será utilizada para realizar a coleta.
- **Timeout**:  É o período de tempo máximo que o coletor aguardará por uma resposta SNMP de um dispositivo antes de considerar a solicitação como falha;
- **Tentativas**: Indica quantas vezes o coletor tentará obter uma resposta do dispositivo SNMP antes de considerar a solicitação como falha. Cada tentativa ocorre após o timeout definido;
- **Agendamento**: Refere-se a quando as solicitações SNMP serão enviadas para os dispositivos de rede. Você pode configurar um agendamento para coletar informações em intervalos regulares ou em horários específicos;
- **Cadastro Automático de Hosts**: Permite que o coletor descubra e registre automaticamente os dispositivos que estão disponíveis na rede. Isso facilita o processo de gerenciamento, pois você não precisa adicionar manualmente cada dispositivo;
- **Descrição**: Fornecer informações adicionais, como anotações, notas ou detalhes adicionais que podem ser úteis para o administrador de rede.



### 4.1 Escolha o tipo e se for detalhado, preecha a profundidade

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/yg3UCMC-UxpBnOk0A4_W9_captura-de-tela-2023-10-17-as-101437-am.png)



## 5. Escolha a frequência de agendamentos

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/9Hr9jGSjbbMmJV97P8gc4_captura-de-tela-2023-10-17-as-81359-am.png)

**Nota**: No **Agendamento&#x20;**&#x70;ode-se selecionar a frequência que as solicitações SNMP serão enviadas para os dispositivos de rede. As escolhas estão para enviar *Apenas uma vez&#x20;*&#x6F;u em intervalos regulares como: *A cada hora, Diariamente ou Semanalmete.*&#x20;



## 6. Adicione as credenciais necessárias para a coleta

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/3-Loc7F-poRnsuZ79Xj7T_captura-de-tela-2023-10-16-as-22213-pm.png)

### 6.1. Preencha os campos e salve a credencial:

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/841-hak9-S-yeINzxjUJg_captura-de-tela-2023-10-16-as-22427-pm.png)

- **Nome:&#x20;**&#x4E;ome da credencial;
- **Porta:&#x20;**&#x50;orta que será feita a conexão com o dispositivo SNMP (padrão 161);
- **Chave SNMP:&#x20;**&#x53;egredo criado para autenticar as solicitações SNMP. Para criar segredos: [https://app.archbee.com/docs/OJunzyGOF3BwJpDCyUNml/5L\_PwD5nJcwqt9pSqLzMC](https://app.archbee.com/docs/OJunzyGOF3BwJpDCyUNml/5L_PwD5nJcwqt9pSqLzMC)**;**
- **Versão:&#x20;**&#x56;ersão do protocolo SNMP utilizado.

### SNMP v2c

Em chave o campo deve conter o valor *chave&#x20;*

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/ig6dhYNW0W1C1akoRjiGt_image.png" size="50" width="994" height="760" position="flex-start" showCaption="false"}

### SNMP v3

Conforme o nível de segurança, o v3 exige uma ou duas chaves para efetuar a autenticação. Esse nível de segurança é definido através do cadastro de uma coleta ou descoberta onde:

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/T2tSWtczM0wRfrUD0aVYL_captura-de-tela-2023-10-17-as-100050-am.png" size="50" width="986" height="914" position="flex-start" showCaption="false"}

- Quando o nível de segurança for **noAuthNoPriv** a autenticação não é feita;
- Quando o nível de segurança for **AuthNoPriv** a autenticação é feita apenas através da chave com valor *Authentication passphrase;*
- Quando o nível de segurança for **AuthPriv**, a autenticação é feita através de duas chaves sendo as *Authentication passphrase* e *Privacy passphrase***.**



### 6.2. Selecione as credenciais desejadas

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/oOoqPD3kt6xMOvG0Z1ax8_captura-de-tela-2023-10-16-as-22713-pm.png "Você pode selecionar múltiplas Credenciais")



## 7. Na aba IPs, adicione um IP e/ou uma faixa de IPs para a descoberta:

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/07ujO8aIBYCxr2tRlh5Yk_captura-de-tela-2023-10-16-as-22758-pm.png)



### 7.1. É possível adicionar vários IPs e/ou faixas separadas pelos idenficadores informados

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/rncsGwCBKFp8IUH6VB6Xf_captura-de-tela-2023-10-18-as-110503-am.png)



## 8. Salve a Descoberta:

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/nkMRIerDnbUV4lONxuxX5_captura-de-tela-2023-10-16-as-60136-pm.png)



## 9. Resultados das faixas de IPs que foram descobertas

### 9.1. Listagem de descobertas

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/cl7xdYPoJ3qtTP5Bs0b11_captura-de-tela-2023-10-18-as-112324-am.png "Listagem das descobertas")

Você pode acompanhar o progresso geral das descobertas ativas na tela de listagem.

### 9.2. Detalhamento da descoberta

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/uhhbNXizC8BiA25UAYzdm_captura-de-tela-2023-10-18-as-113147-am.png)

Você pode acompanhar o progresso individual para cada item da coleta ao detalhar a descoberta criada. Você também poderá verificar os indicadores com a quantidade de IPs processados, finalizados com sucesso e finalizados com erro.

A descoberta é capaz de identificar dispositivos tais como (Linux, AIX, Windows , máquinas virtuais, storage, dispositivos de rede, servidores de aplicação dentre outros).

[title] Requisitos de Software
[path] AIOPS/INTRODUÇÃO/Requisitos/

O AIOPS e suas ferramentas foram desenvolvidas com suporte aos principais sistemas existentes no mercado, em geral: Windows, Mac, Linux

Aplicação Web


Qualquer sistema operacional que tenha no mínimo uma das seguintes versões de navegadores:

- Internet Explorer >= 9.0
- Mozilla Firefox >= 24.0
- Chrome >= 18.0


Por padrão os navegadores oferecem suporte ao Javascript, caso contrário, é necessário habilitar nas Opções de Internet.

## Arquitetura

O Simon e suas ferramentas operam de forma distribuída e paralela, nosso foco em alta disponibilidade permite inclusive, adicionar nós em diferentes localidades (Edge Location/Cloud).
Nossos especialistas oferecem total suporte durante a implantação da plataforma em sua organização.


## Requisitos de software:

### Banco de Dados&#x20;

A instalação do Simon suporta os seguintes fornecedores:

- Postgres 9.x ou superior
- Oracle 12C ou superior
- MySQL Server 5.x ou superior

### &#xD;

### Agent: Sistemas Operacionais / Distros suportados

- AIX 5, 6 e 7
- CentOS 6.5 ou superior
- Debian 7.x ou superior
- Red Hat 6.5 ou superior
- Red Hat Enterprise Linux Server 6.5 ou superior
- Oracle Linux Server 6.5 ou superior
- Ubuntu 14.04 ou superior
- FreeBSD 9.3-RELEASE ou superior
- SuSE 11 ou superior
- Solaris Sparc 9, 10, 11
- HP-UX 11
- IBM i v7.1 (English & Spanish locales), IBM z/OS 2.1, 2.3
- Microsoft Windows 7, 8, 10 ou superior
- Microsoft Windows Server 2008, 2012 ou superior



### Agent: Sistemas Operacionais / Distros não suportados

-
  Oracle Linux 5 ou inferior
- Red Hat Enterprise Linux Server 5 ou inferior
- Windows XP, Vista ou inferiores
- Microsoft Windows(R) Server 2003 ou inferior
- MacOS 10.8 ou inferior

### &#xD;



### Módulo de Automação (Remoto)

O Atmosphere é um módulo (opcional) instalado em servidores Linux e Windows junto ao Sphere Agent, este módulo permite executar Pipes de Automação nas máquinas remotas, incluindo auto recuperação de serviços e processos. Confira mais informações no Sphere Agent.

### Acessos Simultâneos

O AIOPS permite o acesso simultâneo à usuários em diferentes níveis de acesso (administrador, analista, supervisor, operador e gestor), para a realização de tarefas de modo independente.

Todas as ações/atividades dos usuários são passíveis de auditória.

[title] Docker Data
[path] AIOPS/MÉTRICAS/Explorar as Métricas/

Informações sobre pool de armazenamento

| **Chave**                | **Tipo** | **Descrição**                                     |
| ------------------------ | -------- | ------------------------------------------------- |
| docker\_data.`avaliable` | byte     | Espaço livre em disco do pool de armazenamento    |
| docker\_data.`total`     | byte     | Total de espaço em disco do pool de armazenamento |
| docker\_data.`used`      | byte     | Espaço de dados do pool de armazenamento          |


[title] Docker Container Health
[path] AIOPS/MÉTRICAS/Explorar as Métricas/

Monitora a integridade de um contêiner docker.

| **Chave**                                  | **Tipo** | **Descrição**                                                                         |
| ------------------------------------------ | -------- | ------------------------------------------------------------------------------------- |
| docker\_container\_health.`failing_streak` | counter  | Métrica que retorna a quantidade de falhas simultâneas na verificação de integridade. |
| docker\_container\_health.`health_status`  | string   | Código de status da verificação de integridade.                                       |


[title] Incidentes
[path] AIOPS/AIOPS/

Os incidentes são grupos lógicos onde o AIOPS agrupa alertas que possam ser correlacionados de alguma forma, seja por causa raíz ou por serviços impactados similares. Com os objetivos de reduzir ruídos e facilitar o trabalho em equipe no troubleshoot de problemas.&#x20;

O Contexto de incidentes envolve os seuguintes pontos:

- Listagem de incidentes
- Detalhamento de incidentes
- Correlação de eventos
- Compartilhamento de incidentes
- Possíveis ações

Para que os incidentes sejam correlacionados da maneira correta, é necessário ensinar ao AIOPS os eventos correlatos, dessa forma ele evolui no decorrer do tempo e se torna mais assertivos em suas correlações.&#x20;


[title] Monitor de Network
[path] AIOPS/ATMOS/

# Mapa de Rede

O Atmos processa todos os dados coletados da rede em diferentes protocolos e permite o isolamente das informações em várias camadas, na forma&#x20;

## Visão geral

O mapa de rede fornece uma visão da topologia de sua rede para ajudá-lo a visualizar as partições, dependências e gargalos da rede. Ao consolidar os dados da rede em um mapa direcional, esta página pode ser usada para eliminar o ruído e isolar as áreas problemáticas.

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/Mw8JVIbX4CbPvjyY1sizO_screen-shot-2021-06-17-at-195809.png)


[title] Visão Geral
[path] AIOPS/AIOPS/Dashboards/

O acompanhamento de seus alertas/coleções também é possível, de forma simples e visual. Através da dashboard de visão geral de eventos, acessível via AIOPS.

![](https://gblobscdn.gitbook.com/assets%2F-Ls76-8XbGuboSQAg3Y9%2F-LsJ6UgGq6N6-pa_mvpI%2F-LsJ6kSLdIA6YkDbNxAa%2FCaptura%20de%20Tela%202019-10-28%20a%CC%80s%2017.46.33.png?alt=media\&token=00d13536-4810-4963-a3f6-4dbded1408e5)

Através dos dados mostrados acima é possível um acompanhamento em tempo real do tempo de atendimento de diferentes problemas tratados pela operação.

Também é possível observar como anda a capacidade de atendimento de cada equipe envolvida nos atendimentos:

De modo geral essa dashboard te fornece KPIs em relação a problemas que aconteceram, tempo de atuação, e capacidade de equipe, podendo de forma rápida consolidar informações necessárias para eventuais tomadas de decisão.


[title] Política
[path] AIOPS/AIOPS/Alarmes/

Para acessar a criação das políticas de criação de alarmes é necessário acessar o ícone de configurações no menu principal do AIOPS:

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/vivJML8tz8cQTepqqJ3Vw_botaoconfiguracoes.png" size="38" position="center" showCaption="false"}

Após acessar as configurações é necessário acessar a opção **política** no menu interno de opções de alarme:

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/_jdwnJ2uOj0x14vdPkmrV_image.png" size="42" width="218" height="177" position="center" showCaption="false"}

Ao clicar, será exibida uma listagem das políticas de alarmes cadastradas.

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/f37Sws2njX73YAZMzXnPL_image.png)

## Criando política

Para criar uma nova política clique no botão **Nova política**.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/u9W4epquBdtEHs9RRUcRM_image.png" size="28" width="156" height="40" position="center" showCaption="false"}

Uma nova janela com o formulário para cadastro de uma nova política será exibido onde:

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/cYgFtDB1r_bfOOdmk8yx7_image.png)

### Aba Geral

- **Nome**: Identificador para o cadastro da regra.
- **Configurações**: Lista de configurações selecionadas.

Ao clicar no botão **adicionar Configuração** será exibida a janela para selecionar configurações cadastradas.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/Nv0Yxw7naPcGxMPux5c04_image.png" size="24" width="140" height="40" position="center" showCaption="false"}

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/ECGGTUh_53s1YLzUBmgY1_image.png)

### Aba Regras

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/6Wi-R5ikNu7BBW0KRFWZe_image.png)

Ao clicar no botão **adicionar Regra** será exibida a janela para selecionar regras cadastradas.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/sQugw4lf7y37rf8ds2uDq_image.png" size="22" width="101" height="40" position="center" showCaption="false"}

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/BTs4QoFB1lH_7N1LSTOP3_image.png)


[title] Docker Metadata
[path] AIOPS/MÉTRICAS/Explorar as Métricas/

Informações da metadata do docker.

| **Chave**                    | **Tipo** | **Descrição**                                     |
| ---------------------------- | -------- | ------------------------------------------------- |
| docker\_metadata.`avaliable` | byte     | Espaço livre em disco do pool de armazenamento    |
| docker\_metadata.`total`     | byte     | Total de espaço em disco do pool de armazenamento |
| docker\_metadata.`used`      | byte     | Espaço de dados do pool de armazenamento          |


[title] LGPD
[path] AIOPS/INTRODUÇÃO/Requisitos/

A solução adere à LGPD no que tange a transparência, segurança jurídica, anonimização de dados, com todo cuidado com a coleta de informações e coleta de dados, levando sempre em consideração o fator de consentimento com informação prévia ao cidadão. Abrangência territorial, com fiscal centralizado a cargo da Autoridade Nacional de Proteção de Dados Pessoais (ANPD), assim como a responsabilidade sobre os tratamentos de dados e suas funções. Também é feita a gestão de riscos e falhas, cientes das penalidades e todos os direitos e deveres da CONTRATADA, perante a Lei Geral de Proteção de Dados Pessoais, Lei nº 13.709/2018.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/FR75n4ahAPiInjjj1_tuf_lgpdpages-to-0001.jpg" size="76" width="10280" height="10278" position="center" showCaption="false"}

A Lei Geral de Proteção de Dados Pessoais (LGPD ou LGPDP), Lei nº 13.709/2018, é a legislação brasileira que regula as atividades de tratamento de dados pessoais e que também altera os artigos 7º e 16 do Marco Civil da Internet.




[title] Testes Web
[path] AIOPS/ATMOS/

Na aplicação Atmos é possível testar a funcionallidade de URL, os testes de web em várias etapas permitem que você encadei&#x65;**&#xA0;**&#x74;estes HTTP para monitorar de forma proativa se as jornadas em seus serviços principais estão disponíveis a qualquer hora e em qualquer lugar.

Se algum dos seus serviços começar a responder lentamente ou de forma inesperada o teste de web poderá: alertara a sua equipe, bloquear seu pipeline, ou até mesmo reverter o problema.

Para a realização do teste de web, basta clicar no botão que se encontra na barra lateral, como demostrado abaixo:

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/nzozLt-5qrluMkVkXPe4c_Screen%20Shot%202021-01-10%20at%2015.56.04.png" size="10" caption="Botão Testes Web" position="center" showCaption="true"}

Logo após uma tela será aberta, contendo a listagem de todos os testes previamente cadastrados. Podendo estes serem filtrados em ativos e inativos, através das opções na coluna lateral esquerda.

![](https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/IhCHpK2ClwrGVh8k6XhUY_Screen%20Shot%202021-01-10%20at%2016.06.54.png)

## Criando Novo Teste

No botão Inserir Novo Teste Web, no canto superior direito da tela, é permitida a alimentação de dados para realização do teste desejado.

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/Nd8XgzrwWZkAhv4aFiDjW_Screen%20Shot%202021-01-10%20at%2016.08.45.png" size="32" position="center" showCaption="false"}

## Especificando o Teste

Para executar essa operação, basta:

1. Nomear o teste em questão
2. Escolher um método para o teste
3. Especificar a URL a ser testada
4. Eriquecer a solicitação com opções avançadas

![](https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/YDYE23rN19iP6U_yFMpmX_Screen%20Shot%202021-01-10%20at%2016.10.39.png)

Após o preenchimento de todas as especificações, basta clicar no botão Salvar, que se encontra no canto superior direito da tela.

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/3w2q5-hAsY-RuNgDfGnQq_Screen%20Shot%202021-01-10%20at%2016.18.07.png" size="14" position="center" showCaption="false"}


[title] Instalação via PS Script
[path] AIOPS/AIOPS/Inventário/Instalação dos Agents/Untitled/

# 1 - Execute o seguinte script em um Powershell

:::CodeblockTabs
x64

```powershell
Invoke-WebRequest -uri "https://cdn.simonops.com/inventory-agent/windows/Windows-Agent-Setup-x64.exe" -Method "GET" -Outfile "C:\Windows-Agent-Setup-x64.exe";
C:\Windows-Agent-Setup-x64.exe /server=http[s]://inventory-server/ocsinventory /ssl=0 /force /debug=1 /s /nosplash | Out-Null;
Remove-Item -path C:\Windows-Agent-Setup-x64.exe;
Remove-Item -path C:\Windows-Agent-Setup-x64.log;
```

x86

```powershell
Invoke-WebRequest -uri "https://cdn.simonops.com/inventory-agent/windows/Windows-Agent-Setup-x86.exe" -Method "GET" -Outfile "C:\Temp\Windows-Agent-Setup-x86.exe";
C:\Temp\Windows-Agent-Setup-x86.exe /server=http[s]://inventory-server[:port]/ocsinventory /ssl=0 /tag="Test Desktop" /debug=1 /s /nosplash | Out-Null;
Remove-Item -path C:\Temp\Windows-Agent-Setup-x86.exe;
Remove-Item -path C:\Temp\Windows-Agent-Setup-x86.log;
```
:::

\*Certifique que a instância do powershell esteja com privilégios de administrador.

[title] Listagem de alarmes
[path] AIOPS/AIOPS/Alarmes/

É possível acessar a listagem de alarmes clicando no botão abaixo:

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/hEK-EnNgwhNZIfA9dqXqu_image.png" size="18" width="69" height="59" position="center" showCaption="false"}

A partir do menu principal no canto esquerdo superior da tela.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/gva-Xap2DDvpwN5mNj256_image.png" size="18" width="74" height="140" position="center" showCaption="false"}

Após executar essa ação, será apresentada uma listagem com todos os alarmes ativos em seu ambiente.

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/A8Fs9Bcw70D2Zvs85UNEt_image.png)

No canto superior direito da tela é possível efetuar a pesquisa de alarmes por datas específicas ou intervalo de tempo.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/cO3qIGwc1bjy99iZ4ihGE_image.png" size="60" width="294" height="51" position="center" showCaption="false"}


[title] Instalação dos Agents
[path] AIOPS/AIOPS/Inventário/


[title] Compartilhamento Automático
[path] AIOPS/AIOPS/

O compartilhamento automático poderá ser realizado utilizando um dos grupos a seguir.

### [Integração](docId:0GGNQcU1zxIKAg7kbePd_)

### [Automação (Pipes)](docId\:kCwm2TXkZqxfs7UTHsvmh)


[title] Listagem de Incidentes
[path] AIOPS/AIOPS/Incidentes/

É possível acessar a tabela de incidentes clicando no botão abaixo:

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/N6fsaIMEqzQBQp8CacxFH_Screen%20Shot%202021-01-09%20at%2012.40.05.png" size="10" position="center" showCaption="false"}

&#x20; Que se encontra no menu principal, canto esquerdo superior da tela.

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/2--DOJRTAAHaA_Wb7EXiI_Screen%20Shot%202021-01-09%20at%2012.55.53.png" size="10" position="center" showCaption="false"}

Após executar essa operação, será apresentada uma listagem contemplando todos os incidentes que ocorreram em seu ambiente. Sendo estes, ativos ou inativos(previamente solucionados).

![](https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/nP3H21recjjAWrHk5wc9f_Screen%20Shot%202021-01-09%20at%2012.59.43.png)

A plataforma permite a filtragem de Canais ([Canais](docId\:Uss2p5BBsZ2zkFqYqWddO) ) conforme as configurações criadas pelo usuário, de acordo com as necessidades do seu ambiente.

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/j4UYAeiShDs0A9yTEqRbY_Screen%20Shot%202021-01-09%20at%2013.19.10.png" size="30" position="center" showCaption="false"}

Ações como: Previsão de alertas, restauração de tela, pesquisa de eventos por datas específicas ou intervalo de tempo, filtros avançados e intervalo de atualização, poderão ser executadas no canto superior direito da tela no menu principal.

![](https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/SWur6naDmMDoWHWBk8h_o_Screen%20Shot%202021-01-09%20at%2013.21.28.png)


[title] Topologia
[path] AIOPS/ATMOS/

A topologia consiste em representar graficamente os dispositivos, suas interfaces e os circuitos de comunicação que estão interconectados, atuando como o mapa da sua infraestrutura. Conforme o Sphere, descobre todos os componentes e dependências em seu ambiente de aplicativo, nossa tecnologia constrói um mapa interativo de como tudo está interconectado.

As conexões intuitivas facilitam o entendimento das dependências entre seus nós. As visualizações são construídas de forma dinâmica e automática, sem a necessidade de configuração manual.&#x20;

## Acesso

Para acessar a aplicação Atmos é necessário clicar no botão "aplicações" localizado no canto inferior esquerdo, do menu principal no AIOPS.

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/_dl2iGnL-Fm4SOb1vBfhr_image.png" size="56" position="center" showCaption="false"}

Após acessar o Atmos é necessário acessar a tela de topologia através do menu principal:

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/iqEIiKg8Xin_s0CNoi6Ry_image.png" size="56" position="center" showCaption="false"}

Ao acessar a tela de topologia será possível ver o mapeamento de nós de sua infraestrutura:

![](https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/W7mWSnV9NegrJgScDVluc_image.png)

## Ações

A funcionalidade de topologia possui diferentes ações, como:&#x20;

- Ativar/Desativar hosts sem conexão
- Ativar/Desativar nome dos hosts&#x20;
- Zoom
- Filtros

### Hosts sem conexão e Nome dos Hosts&#x20;

Onde no canto superior esquerdo temos a possibilidade de **ativar e desativar a visualização de hosts** sem conexão e **ativar e desativar a exibição do nome dos hosts** através do seguinte botão:&#x20;

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/wcPIchbfF6NOCmV_2FofW_image.png" size="28" caption="Primeiro botão habilita todos os hosts, segundo botão o nome dos hosts" position="center" showCaption="true"}

### Zoom

No canto superior direito, tempo os botões para a **utilização do zoom**, onde + e - consequentemente aumentam ou diminuem o zoom e a bandeira reseta para o zoom originial.

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/4csHdv2r9PDgpDkmeCceB_image.png" size="34" position="center" showCaption="false"}

### Filtros&#x20;

No menu superior existe a opção de filtrar utilizando a **barra de busca**, onde ao clicar e apertar o botão seta para baixo no teclado será possível escolher todos os possíveis atributos para filtro.

![](https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/UzzcyD6LQJCFAZ_29wu1M_barra%20de%20busca%20topologia.png)

Continuando as opções de filtro, temos ao lado da barra de buscar a opção de selecionar filtros:

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/ofHOWfNVyxF2mr8W0c0w2_image.png" size="56" position="center" showCaption="false"}

Que permite de maneira fácil filtrar a tela de topologia pelos atributos exibidos na lista e pelo status (<font color="#eb9610">offline</font>).

[title] Infraestrutura
[path] AIOPS/ATMOS/

Todos nós presentes na sua infraestrutura representam Itens de Configuração, passíveis de ser qualquer item dentro de sua rede ou infraestrutura. No Atmos é possível gerir toda a sua infraestrutura e acompanhar em tempo real a situação de cada nó.

## Acesso&#x20;

Para acessar a aplicação Atmos é necessário clicar no botão "aplicações" localizado no canto inferior esquerdo, do menu principal no AIOPS.

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/_dl2iGnL-Fm4SOb1vBfhr_image.png" size="50" position="center" showCaption="false"}

Após acessar o Atmos é necessário acessar a tela de infraestrutura através do menu principal:

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/ggS7bQ-iDMiYfbM1CW-dV_image.png" size="52" position="center" showCaption="false"}

Ao acessar a tela de infraestrutura será possível ver a listagem de nós de sua infraestrutura:

![](https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/pRwh1X1OlueYbJ_voMvCP_image.png)

## Informações

Na listagem é possível temos a opção de acompanhar informações como:

- ID do item de configuração
- IP
- Status atual
- Insights
- Automações
- Triggers
- Heartbeat&#x20;
- Última atualização&#x20;
- Anotações
- Sistema operacional&#x20;

Dessa forma é possível de forma rápida, não só consultar todos os itens, mas também ter uma informação rápida e assertiva sobre cada um deles.

## Filtros

É possível também utilizar a opção de busca, filtros, e ações em grupo na seguinte opção, existente no canto superior direito:

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/zldtH_JZIAqNj-mvyJgw3_image.png" size="36" position="center" showCaption="false"}

## Ações

Para acessar as possíveis ações para um determinado nó, da infraestrutura, é necessário clicar na engrenagem existente no canto superior direito:

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/zEoMG0btEW1ETo_2XehV0_image.png" size="16" position="center" showCaption="false"}

As possíveis opções então aparecerão:&#x20;

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/JCtwf-jtUPM0o1KqPHGpE_image.png" size="56" position="center" showCaption="false"}

Temos então a ação **adicionar&#x20;**[host](https://docs.simonops.com/hosts), que permitirá adicionar um nó avulso, que não foi capturado via agents ou descobertas.

A opção ativar seleção, permite diferentes ações em vários nós ao mesmo tempo:

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/iSBTa4gGcH-W44AdrCVfG_image.png" size="52" position="center" showCaption="false"}

Cada uma dessa ações poderá ser executada após o usuário selecionar um ou mais [hosts](https://docs.simonops.com/hosts).

[title] Painéis (Dashboards)
[path] AIOPS/ATMOS/

Observe as métricas fundamentais do seu negócio em nossas dashboards.

As dashboards do AIOPS possibilitam uma visão geral das principais métricas de sua operação/negócio.

Crie Dashboards Customizadas, acompanhe os seus principais ICS ou sua operação, acompanhando diferentes métricas coletadas no AIOPS, possibilitando uma visão gerencial totalmente personalizada:

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/XyaAqL2AIjQ8C6QzKH1EL_atmos-dashboard.png" size="82" position="center" showCaption="false"}

É possível filtrar a dashboard por períodos, como por exemplo, os últimos 7 dias, utilizando o componente de filtro de datas:&#x20;

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/XgJpQvMPziOmt7rZyIJ7n_image.png" size="50" position="center" showCaption="false"}

Para criar uma nova Dashboard, você pode clicar no botão:

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/3w2aITd-Oxy8yNYliqYUI_image.png" size="30" position="center" showCaption="false"}

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/SEp_9P5ykx5c2FBpZdO5m_image.png" size="56" position="center" showCaption="false"}


[title] Hosts
[path] AIOPS/ATMOS/

Visualize as métricas relacionadas à um IC, coletadas em um determinado intervalo de tempo, defina templates de métricas, acompanhe a real situação e organize seus nós através das funcionalidades existentes para cada nós de sua infraestrutura.

## Acesso&#x20;

Para acessar a tela de detalhamento de host, é necessário seguir o procedimento para acesso a tela de [Infraestrutura](docId\:KfX05k3xHlB7mBEtsgQGB) e clicar em um item existente na listagem.

![](https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/Sz9S0NGbSU-BY2PR7HfRm_image.png)

## Informações&#x20;

Na tela é possível obter informações rápidas sobre o host selecionado, como **métricas**, **informações de sistema**, **processos**, **serviços de negócios dependentes deste item** e **dependências lógicas&#x20;**&#x70;ara outros itens de sua infraestrutura.

### Informações gerais&#x20;

No box lateral esquerdo, temos informações gerais:

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/yB_kwW_j6PQ9HiDIK1nLz_image.png" size="38" caption="Informações de Sistema, Volumes, Interfaces, Processos e Serviços Dependentes" position="center" showCaption="true"}

### Métricas

Observando o centro da tela é possível de forma rápida e eficiente obter dados sobre métricas importantes para esse determinado nó.

![](https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/5sqjVKjoK79mZvfnRCS_s_image.png)

### Predição

Para cada métrica é possível prever o que pode acontecer, com base no comportamento histórico do host citado, clicando no botão de predição.

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/vMmbGQ2M6oFwdJlFugMf8_screen-shot-2021-06-16-at-163603.png "Predição de métricas ")

### Dependências

Na área inferior da tela é possível observar o box de dependency overview, onde se pode observar quais as dependências lógicas ativas para esse nó de infraestrutura.

![](https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/uoyhwILaEgx0mZoTDMKYG_image.png)

### Insights e alertas

O Atmos atua de forma automática, auxiliando na gestão de recursos e propiciando uma visão rápida de possíveis problemas no host escolhido através dos botões abaixo (canto superior direito):

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/BcgqKz7B9oRpiuJiWaUsw_image.png" size="50" position="center" showCaption="false"}

## Ações

Para o host escolhido é possível desempenhar ações com o objetivo de organizar e filtrar (tags e annotations) e ações com o objetivo de gerir os items de configuração.

### Criação e gestão de tags e anotações:

No canto superior direito é possível encontrar a opção de adicionar tags e anotações para facilitar a organização:

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/_rfDdrH8WjZ8AHQIJ7IK__image.png" size="52" position="center" showCaption="false"}

Ao clicar no ícone de etiqueta, um modal será carregado com as opções de tags e anotações do host escolhido.

### Atuando com hosts:

No canto superior direito possível selecionar a opção de três pontos:&#x20;

::Image[]{src="https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/wzOvlcZe1apRtTc2gsfmU_image.png" size="46" position="center" showCaption="false"}

Essa opção abrirá um dropdown com as seguintes opções:

- Alterar nome
- Configuração de Métrica
- Arquivar
- Combinar hosts
- Configurar painéis

### Alteração de nome&#x20;

Permite de forma rápida, padronizar e renomear hosts para um melhor acompanhamento.

### Configuração de métrica

Permite consultar e acessar as configurações de métricas ativas para esse item de configuração.

### Arquivar

Permite remover (arquivar) um host de forma lógica, evitando assim perda de dados e permitindo uma recuperação posterior.

### Combinar host

Como o AIOPS/Atmos atua de maneira a propiciar uma centralização de diferentes ferramentas é possível selecionar dois hosts oriundos de diferentes fontes mas que representam o mesmo item e realizar uma fusão das informações de duas diferentes fontes, escolhendo qual seria a princiapal e evitando dados inutilizados na tela de infraestrutura.

### Configurar painéis

É a opção onde se pode configurar as métricas a serem exibidas nesse host:

![](https://archbee-doc-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/CqTN8Ot762GWrCWszEK9I_image.png)

### Coleta por SNMP v1/v2

Colete eventos de diversos dispositivos e sistemas através  do protocolo SNMP - Simple Network Management Protocol.

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/2W8cFLJPtBvnetZcAickF_coleta-snmp.PNG)


[title] Explorar as Métricas
[path] AIOPS/MÉTRICAS/

| **Grupo**                  | **Descrição**                                                                                                                                                                                  |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cpu`.                     | CPU – Métricas de CPU do sistema.                                                                                                                                                              |
| `disk`.                    | Disk – Métricas sobre o uso do disco.                                                                                                                                                          |
| `diskio`.                  | Disk IO – Métricas sobre o tráfego e o tempo do disco.                                                                                                                                         |
| `docker`.                  | Docker - Métricas sobre a execução de contêineres docker.                                                                                                                                      |
| `docker_container_blkio`.  | Docker Container Blkio - Monitora o acesso a I/O em dispositivos de bloco.                                                                                                                     |
| `docker_container_cpu`.    | Docker Container CPU - Métricas sobre as CPUs de um contêiner docker.                                                                                                                          |
| `docker_container_health`. | Docker Container Health - Monitora a integridade de um contêiner docker.                                                                                                                       |
| `docker_container_mem`.    | Docker Container Mem - Traz informações da memória utilizado pelo container docker.                                                                                                            |
| `docker_container_net`.    | Docker Container Net - Métricas sobre a rede de um contêiner docker.                                                                                                                           |
| `docker_container_status`. | Docker Container Status - Métricas sobre o estado de um container docker.                                                                                                                      |
| `docker_data`.             | Docker data - Informações sobre pool de armazenamento.                                                                                                                                         |
| `docker_devicemapper`.     | Docker Devicemapper - Mapeamento de dispositivos de bloco físicos em dispositivos virtuais de bloco de alto nível.                                                                             |
| `docker_metadata`.         | Docker metadata - Informações da metadata do docker.                                                                                                                                           |
| `health_check`.            | Health Check - Verificação de integridade simples.                                                                                                                                             |
| `http_request`.            | HTTP Request - Parâmetros importantes do protocolo HTTP e sua sintaxe na forma como são usados na comunicação.                                                                                 |
| `kernel`.                  | Kernel - Coleta métricas sobre o kernel.                                                                                                                                                       |
| `listen_process`.          | Listen Process - Informações de processos que estão com status de LISTEN.                                                                                                                      |
| `mem`.                     | Mem - Informações da memória utilizado.                                                                                                                                                        |
| `net`.                     | Net - Métricas sobre interface de rede e uso de protocolo.                                                                                                                                     |
| `netstat`.                 | Netstat - Ferramenta utilitária de rede de linha de comando que exibe conexões de rede para o Transmission Control Protocol (entrada e saída) e User Datagram Protocol (UDP).                  |
| `process`.                 | Process - Resumo (contadores) relacionadas aos processos do host.                                                                                                                              |
| `processes`.               | Processes - Informações relacionadas aos processos do host.                                                                                                                                    |
| `redis`.                   | Redis - Redis é um armazenamento de estrutura de dados em memória, usado como um banco de dados em memória distribuído de chave-valor, cache e agente de mensagens, com durabilidade opcional. |
| `redis_cmdstat`.           | Redis Cmd Stat - Estatísticas de comandos do Redis.                                                                                                                                            |
| `redis_keyspace`.          | Redis Key Space - Informações do dicionário interno gerenciado pelo Redis, no qual todas as chaves são armazenadas.                                                                            |
| `swap`.                    | Swap - Informações de memória swap.                                                                                                                                                            |
| `system`.                  | System - Estatísticas gerais sobre a carga do sistema, o tempo de atividade e o número de usuários conectados.                                                                                 |


[title] Segredo
[path] AIOPS/ATMOS/

O cadastro das credenciais e feito a partir das **Configurações**, em cofre selecione a opção **Segredos**:

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/thF7_BaJQJAhgkNRFARFw_image.png" size="24" width="180" height="58" position="center" showCaption="false"}

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/_K9JLSktlW8acWAcC6PmS_image.png" size="32" width="244" height="79" position="center" showCaption="false"}

Após a seleção, será exibida a listagem de segredos cadastrados:

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/TWAHX_Wd-idRw0A5Jv1iY_captura-de-tela-2023-10-17-as-84041-am.png)

Para cadastrar um novo segredo clique em **Novo segredo**

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/2H6aSyYsKMwzWit9D1u6p_image.png" size="26" width="163" height="54" position="center" showCaption="false"}

Após a seleção será exibido o seguinte formulário:

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/gB9sTj4jS33PzXrjDZz-S_image.png)

Na aba **Geral** temos:

- **Nome**: Nome para a credencial a ser cadastrada;
- **Perfis que podem alterar**: Quais perfis de usuário podem modificar o conteúdo da credencial;
- **Perfis que podem visualizar**: Quais perfis de usuário podem visualizar o conteúdo da credencial
- **Descrição**: Descrição da credencial

Na aba **Chaves de acesso** temos a opção para criar as chaves no botão **Nova chave**:

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/DE9txL6Y0cv7aTGNoDh_o_image.png)

Ao clicar em Nova chave o seguinte formulário é exibido, crie a chave e seu valor:

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/NFOo0btJp62Q5iXGJ3Rkd_image.png" size="56" width="512" height="358" position="center" showCaption="false"}

Salve o segredo:

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/fpKfvDo2Tx4Ap_esgKUaL_image.png)


[title] Políticas
[path] AIOPS/AIOPS/Inventário/

## Utilização dos modelos

Os modelos de Política de Configuração baseados em Windows são uma parte essencial do software Xventory, uma ferramenta de gerenciamento de inventário de ativos de TI que permite que os administradores de sistema gerenciem e rastreiem ativos de hardware e software em uma organização de maneira eficiente e escalável.

Os modelos de Política de Configuração do Xventory permitem que os administradores de sistema criem políticas personalizadas e implantem essas políticas em todos os dispositivos gerenciados, garantindo que todas as configurações de segurança e rede necessárias estejam em vigor em toda a organização. Com esses modelos, os usuários de sistema podem criar scripts relacionados a políticas que podem ser implantados em dispositivos gerenciados com sistema operacional Windows, automatizando tarefas de configuração e melhorando a eficiência operacional.

Os modelos disponíveis no Xventory incluem configurações de segurança, configurações de firewall, configurações de rede, configurações do Internet Explorer e configurações de políticas de conta de usuário. Cada modelo inclui uma descrição detalhada das configurações que podem ser configuradas por meio do modelo e uma explicação de como usar o modelo para implantar as configurações desejadas.

Além disso, o Xventory permite que os administradores de sistema criem políticas personalizadas para atender às necessidades específicas de sua organização. Isso significa que é possível criar políticas que sejam aplicáveis a um único dispositivo, a um grupo de dispositivos ou a todos os dispositivos gerenciados.

Em resumo, os modelos de Política de Configuração baseados em Windows são uma parte fundamental do software Xventory, permitindo que os administradores de sistema gerenciem e implantem políticas de segurança e configuração em dispositivos gerenciados de maneira automatizada e eficiente. Com esses modelos, os administradores de sistema podem garantir que todas as configurações corretas sejam implantadas em todos os dispositivos gerenciados da organização, independentemente do sistema operacional utilizado.

## Integração com pipes&#x20;

Integrar o Xventory com a solução de low code (Pipes) pode levar o gerenciamento de ativos de TI para um nível totalmente novo de eficiência e escalabilidade. Com a integração do Xventory, os desenvolvedores podem aproveitar os modelos de Política de Configuração e outras funcionalidades do Xventory para criar aplicativos personalizados e fluxos de trabalho automatizados em questão de minutos, sem a necessidade de conhecimentos em programação.

Usando a nossa solução de low code, os desenvolvedores podem criar aplicativos personalizados que aproveitam os recursos do Xventory, como varredura automática de ativos e tomada de decisões automatizadas com base em políticas de configuração. Eles também podem usar os modelos de Política de Configuração para automatizar tarefas de configuração e melhorar a eficiência operacional.

A integração do Xventory com uma solução de low code permite que as empresas desenvolvam soluções personalizadas e escaláveis ​​para gerenciar e rastrear ativos de hardware e software em toda a organização. Com essa solução integrada, as empresas podem melhorar a eficiência operacional, aumentar a produtividade e garantir que todas as configurações de segurança e rede necessárias estejam em vigor em todos os dispositivos gerenciados.

[title] Observação de redes
[path] AIOPS/AIOPS/Integrações/

Para ampliar a observação de redes e networking, nós utilizamos integrações com ferramentas de mercado reforçando, dentre elas temos:&#x20;

- Elastiflow
- ELK
- Paessler PRTG
- Paessler PRTG&#x20;
- ManageEngine NetFlow Analyzer&#x20;
- Plixer Scrutinizer&#x20;
- Wireshark
- nProbe


[title] Sphere Agent
[path] AIOPS/INSTALAÇÃO/

Agente remoto que é instalado como serviço nos sistemas operacionais Windows e Linux. Utilizado  para coleta de métricas do ambiente e responsável por executar a automação remota.

### Compatibilidade de OS:

O Sphere Agent funciona nas versões Linux (Oracle/CentOS/RHEL/Ubuntu/SUSE/Amazon Linux) e Windows (2008 ou superior) de 64 Bits. Confira mais detalhes na seção Requisitos do Sistema.

## Procedimento de instalação:

Antes de começar, vamos entender a estrutura dos arquivos do agent:

```shell
sphere-agent/                 # raiz do agent
             plugins/         # diretorio dos plugins do sphere
             queue/           # diretorio temporario de metricas
             atmosphere.yaml  # arquivo de configuração principal
             config.yaml      # arquivo de configuração de coleta
             sphere-agent.log # arquivo de log do agent
```

### Arquivo de configuração (atmosphere.yaml)

Esta é a principal configuração que determina qual o servidor do AIOPS na rede e atributos essenciais do host como permissão de automação e configuração automática do arquivo de coleta *config.yaml.*

Modificar:&#x20;

- Hostname: Modificar para o IP do host;
- Port: Modificar para a porta 80

Adicionar ao arquivo:

- path: /sphere-sync
- scheme: http

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/QeP-GQyL689grWgiRoNXk_image.png)

### Arquivo de configuração (config.yaml)

Determina a configuração dos plugins, períodos de coleta, proxy, etc. Este arquivo é configurado automaticamente através do Atmos (exige a configuração antecipada do *atmosphere.yaml*).

Modificar:&#x20;

- Hostname: Modificar para o IP do host;
- Port: Modificar para a porta 80

Adicionar ao arquivo:

- path: /sphere-sync

![](https://archbee-image-uploads.s3.amazonaws.com/NB-ulyH02IT7Ep_VosDsd/cgbhHiZAy-xz8A7yozS6o_image.png)

### Requisitos para instalação

- Espaço livre:**&#x20;500mb** (mínimo recomendado)
- Volume de instalação:
  - Linux: **/opt**
    - Sub-diretório: <font color="#111827">/sphere-agent-linux </font>
  - Windows: **C:/ProgramData/65A**
    - Sub-diretório: /sphere-agent-windows&#x20;

### Repositórios e Distribuição

**Repositório Cloud AWS/S3:** [https://65a-internal-sa.s3-sa-east-1.amazonaws.com/repo/latest](https://65a-internal-sa.s3-sa-east-1.amazonaws.com/repo/latest), este repositório é recomendado para obter a versão mais recente dos agents, sendo necessária a configuração manual dos arquivos (*config.yaml* e *atmosphere.yaml*).

**Ambiente on-premise:** utilize o formato de url <font color="#2166ae">*http://****&lt;aiops-master-node&gt;****/repo*</font>**



## Instalação Automática&#x20;

Procedimento recomendado e disponivel a partir da versão 3.0.0+.

### On-premises e Agent pré-configurado

Para realizar a *primeira instalação* e principalmente nas *distribuições* *on-premises,* é recomendado substituir o endereço apontando para a url do servidor principal do AIOPS, desta forma o download será realizado na rede interna e o agent estará automaticamente configurado para este ambiente.

:::hint{type="warning"}
## Recomendação de atualização

Recomendamos que antes da atualização do agent verifique o espaço em disco disponível e confirme se a URL utilizada condiz com o tipo de instalação desejada.&#x20;
:::

### Linux (64 bits): &#x20;

Execute uma das opções de comando abaixo no terminal, a instalação será iniciada e exibirá o log do progresso no console.

```shell

# (Opção 1) Utilizando curl
curl -k http://<aiops-master-node>/repo/update-sphere-agent.sh | sudo sh

# (Opção 2) Utilizando wget
wget -O - http://<aiops-master-node>/repo/update-sphere-agent.sh | sudo sh

```

Com este mesmo comando é possível realizar a atualização do agent quando disponível, um aviso será observado na tela de Infraestrutura do Atmos.

### Windows (64 bits):&#x20;

Faça o download do arquivo no repositório do AIOPS através da url como no exemplo: <font color="#2166ae">*http://****&lt;aiops-master-node&gt;****/repo/update-sphere-agent.ps1*</font>**

Execute o PowerShell como Administrador e rode o comando abaixo:

```powershell

# Acesse a pasta onde encontra-se o arquivo baixado e execute o comando: 
powershell.exe -ExecutionPolicy Bypass -File .\update-sphere-agent.ps1

```

***

## Instalação Manual

### Windows (64 bits): &#x20;

1. Faça o download do Agent para Windows:[https://65a-internal-sa.s3.sa-east-1.amazonaws.com/repo/latest/sphere-agent-windows\_x64.zip](https://65a-internal-sa.s3.sa-east-1.amazonaws.com/repo/latest/sphere-agent-windows_x64.zip)
2. Salve o arquivo na pasta de serviços desejados, recomendamos a pasta: C:\ProgramData\65A
3. Descompacte o arquivo baixado (se houver, escolha a opção "Extrair Aqui”)
4. Acesse a pasta criada e execute o arquivo no PowerShell:.\install-service.ps1
5. Confirme no gerenciador de serviços do Windows se o processo “sphere-agent” foi iniciado, caso contrário, inicie o serviço.
6. Reiniciar o serviço (após modificar o config.yaml), no PowerShell:&#x20;
   Restart-Service -Name "sphere-agent"

### Linux (64 bits): &#x20;

1. Faça o download do Agent para Linux:*wget -O /opt/sphere-agent-linux.tar.gz&#x20;*[https://65a-internal-sa.s3.sa-east-1.amazonaws.com/repo/latest/sphere-agent-linux\_x64.tar.gz](https://65a-internal-sa.s3.sa-east-1.amazonaws.com/repo/latest/sphere-agent-linux_x64.tar.gz)
2. Salve o arquivo na pasta de serviços desejados, recomendamos uma das pastas: /opt/
   /srv/
   /usr/src
3. Descompacte o arquivo na pasta ou via comando no terminal:  tar -zxvf sphere-agent-linux\_x64.tar.gz
4. Acesse a pasta criada e execute o comando no terminal\:sudo bash ./install-service.sh
5. Confirme o status do serviço rodando um dos comandos no terminal\:sudo systemctl status sphere-agent
6. Reiniciar o serviço no terminal (após modificar o arquivo config.yaml)\:sudo systemctl restart sphere-agent

:::hint{type="warning"}
## Arquivos de configuração

Confira o arquivo config.yaml se a seção output.server foi configurada corretamente. Caso já tenha iniciado o serviço, realize as mudanças no arquivo config.yaml e em seguida reinicie o serviço.
:::

Exemplo do **atmosphere.yaml**

```yaml

apiVersion: v1                      # versão da api do AIOPS
kind: Host                          # tipo do item de configuração
metadata:
  namespace: default                # namespace deste host
  domain: "<root-domain>"           # nome do dominio raiz
  annotations:                      # anotações locais do host
    atmosphere/host.services: '[]'  # lista de serviços mapeados
config:
  hostname: "127.0.0.1"             # ip/hostname do AIOPS
  api_key: "<atmosphere-api>"       # chave da api
  scheme: http                      # (opcional) se utilizar SSL / Default http
  port: 18001                       # SSL - 443, Default 18001
  path: /sphere-sync                 
  path: /                           # /sphere-sync (se utilizar proxy 80/443)
  agent:                            # configurações do agent local
    self_update: true               # atualizações automáticas do agent

```

Com este arquivo presente na pasta de configuração será possível controlar as configurações do agent remotamente (via *Atmos*).

## Remoção do agent&#x20;

### Linux

```shell
# Utilize o arquivo uninstall.sh para remover o agent
sudo bash /opt/sphere-agent-linux/uninstall.sh

# Remover as pastas do agent
rm -rf /opt/sphere-agent-linux*

# Bonus: Se o atmosphere (módulo de automação) tiver instalado:
# Remover as pastas do atmosphere
rm -rf /opt/.atmosphere

```

:::hint{type="warning"}
**Aviso:** Cuidado ao utilizar o comando "**rm -rf \*\*\***" apontando somente as pastas do agent informadas acima.&#x20;
:::

### Windows

Ao utilizar o instalador ".msi" você poderá desinstalar o agent no gerenciador de programas do próprio Windows.
Ou então poderá seguir para a remoção via script (*uninstall.ps1*) presente na pasta do agent:

```powershell
# Desinstalar o Agent
powershell.exe -ExecutionPolicy Bypass -File C:\ProgramData\65A\sphere-agent\uninstall.ps1
```



***

# Atmosphere

O Atmosphere é o módulo adicional que se conecta ao *Sphere Agent* instalado na máquina e fornece as ferramentas necessárias para execução de rotinas de automação/recuperação de processos e serviços.&#x20;

### &#xA;Compatibilidade de OS:

O Atmosphere funciona em todas as versões Linux compatíveis com *Sphere Agent*. Para as versões Windows há somente *disponibilidade parcial* de algumas distribuições.

### Requisitos para instalação

- Espaço livre:**&#x20;500mb** (mínimo recomendado)
- Diretório de Instalação: **/opt**/.atmosphere

***

## Instalação Automática&#x20;

### Linux (64 bits): &#x20;

Execute uma das opções de comando abaixo no terminal, a instalação será iniciada e exibirá o log do progresso no console.

```shell

# (Opção 1) Utilizando curl
curl -k http://<aiops-master-node>/repo/install-atmosphere.sh | sudo sh

# (Opção 2) Utilizando wget
wget -O - http://<aiops-master-node>/repo/install-atmosphere.sh | sudo sh

```

Após a instalação o AIOPS irá detectar e exibir automaticamente em suas soluções que o módulo está disponível no Item de Configuração relacionado.

***

### Utilização de Recursos do Agent

| **Resource**      | **Idle**   | **Load**        |
| ----------------- | ---------- | --------------- |
| Disk              | -          | 170mb           |
| CPU (single core) | \< 0,5%    | 3,5% max        |
| Memory            | 32mb       | 50mb max        |
| Network           | 0,5 KB/sec | 10,9 KB/sec max |


[title] Proxy Reverso
[path] AIOPS/Instalação Gerenciada (Homologação/Avançado/Configurações do Proxy/

***

### Instalação do Proxy Reverso NGINX

Exemplo de configuração do proxy reverso utilizando o nginx.

```shell
map $http_x_forwarded_proto $protoscheme {
    default $scheme;
    https https;
}

# required for WebSockets
map $http_upgrade $connection_upgrade {
    default upgrade;
    '' close;
}

upstream ws-simon-bal {
    server 127.0.0.1:80; # IP Master Node
}

server {

    # ...

    keepalive_timeout   60;
    server_tokens off;

    # Strict Transport Security
    add_header Strict-Transport-Security max-age=2592000;

    # proxy buffers
    proxy_buffers 16 64k;
    proxy_buffer_size 128k;

    location ~* ^/(ws)/ {
        rewrite  ^/(ws/.*)$ /$1 break;
        proxy_pass         http://ws-simon-bal;
        # proxy_redirect    off;
        proxy_redirect     http://ws-simon-bal/ $scheme://127.0.0.1/;
        proxy_set_header   Host            127.0.0.1;
        proxy_set_header   X-Host          $http_host;
        proxy_set_header   X-Real-IP       $remote_addr;
        proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header   X-Forwarded-Host $http_host;
        proxy_set_header   X-Forwarded-Proto $protoscheme;

        # required for WebSockets
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;

        proxy_read_timeout 20d;
        proxy_buffering off;
    }

    location / {
        expires -1;
        add_header Cache-Control no-cache;
        add_header X-Proxy-Cache $upstream_cache_status;
        #
        default_type       application/json;
        proxy_cache        main;
        rewrite            ^/(.*)$              /$1 break;
        proxy_set_header   Host                 127.0.0.1;
        proxy_set_header   X-Host               $http_host;
        proxy_set_header   X-Real-IP            $remote_addr;
        proxy_set_header   X-Forwarded-For      $proxy_add_x_forwarded_for;
        proxy_set_header   X-Forwarded-Host     $http_host;
        proxy_set_header   X-Forwarded-Proto    $protoscheme;
        proxy_redirect     off;
        proxy_pass         http://ws-simon-bal;
	    # 1 hora ?
        proxy_read_timeout 3600s;
    }
}
```

***

### Instalação do Proxy Reverso Apache2

Exemplo de configuração do proxy reverso para apache com os modulos obrigatórios: (*proxy, rewrite, proxy\_http, proxy\_wstunnel*).

```shell
a2enmod proxy rewrite proxy_http proxy_wstunnel
```

```shell

# Exemplo para porta 80/443
# Redirecionar tráfego da porta 80 -> 443

<VirtualHost *:80>
  ServerName simon.seudominio.com
  # ... Outras configurações

  Redirect permanent / https://simon.seudominio.com
  
</VirtualHost>

<VirtualHost *:443>
  
  ServerName simon.seudominio.com

  # ... Outras configurações

  ProxyRequests Off
  ProxyPreserveHost On

  # Suporte à Websockets
  RewriteEngine On  
  RewriteCond %{REQUEST_URI}   ^/                [NC]
  RewriteRule /(.*)            http://simon.seudominio/$1 [P,L]
  RewriteCond %{HTTP:Upgrade}  =websocket        [NC]
  RewriteCond %{REQUEST_URI}   ^/ws/             [NC]
  RewriteRule /(.*)            ws://simon.seudominio/$1   [P,L]

  # 
  ProxyPass        / http://simon.seudominio/ timeout=600
  ProxyPassReverse / http://simon.seudominio/ timeout=600

</VirtualHost>
```

Exemplo de configuração do proxy reverso.

[title] Swap
[path] AIOPS/MÉTRICAS/Explorar as Métricas/

Informações de memória swap.

| **Chave**           | **Tipo** | **Descrição**                                                                     |
| ------------------- | -------- | --------------------------------------------------------------------------------- |
| swap.`free`         | bytes    | Quantidade de espaço de troca que não está em uso.                                |
| swap.`in`           | bytes    | Verifica se a zona de memória da qual as páginas devem ser trocadas são as mesmas |
| swap.`out`          | bytes    | Especifica a zona de memória da qual as páginas devem ser trocadas                |
| swap.`total`        | bytes    | Quantidade total de espaço de troca no momento.                                   |
| swap.`used`         | bytes    | Quantidade de espaço de troca em uso no momento.                                  |
| swap.`used_percent` | percent  | Percentual de espaço de troca em uso no momento.                                  |


[title] Redis
[path] AIOPS/MÉTRICAS/Explorar as Métricas/

Redis é um armazenamento de estrutura de dados em memória, usado como um banco de dados em memória distribuído de chave-valor, cache e agente de mensagens, com durabilidade opcional

| **Chave**                              | **Tipo** | **Descrição**                                                                                                                       |
| -------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| redis.`active_defrag_key_hits`         | counter  | Número de chaves que foram ativamente desfragmentadas                                                                               |
| redis.`active_defrag_key_misses`       | counter  | Número de chaves que foram ignoradas pelo processo de desfragmentação ativo                                                         |
| redis.`active_defrag_misses`           | counter  | Número de realocações de valor canceladas iniciadas pelo processo de desfragmentação ativo                                          |
| redis.`active_defrag_running`          | boolean  | Sinalizador que indica se a desfragmentação ativa está ativa                                                                        |
| redis.`aof_current_rewrite_time_sec`   | time     | Duração da operação de reescrita AOF em andamento, se houver                                                                        |
| redis.`aof_enabled`                    | boolean  | Sinalizador indicando que o log AOF está ativado                                                                                    |
| redis.`aof_last_bgrewrite_status`      | boolean  | Status da última operação de reescrita AOF                                                                                          |
| redis.`aof_last_cow_size`              | byte     | Tamanho em bytes da memória copy-on-write durante a última operação de reescrita AOF                                                |
| redis.`aof_last_rewrite_time_sec`      | counter  | Duração da última operação de reescrita AOF em segundos                                                                             |
| redis.`aof_last_write_status`          | boolean  | Status da última operação de gravação para o AOF                                                                                    |
| redis.`aof_rewrite_in_progress`        | boolean  | Sinalizador que indica que uma operação de reescrita AOF está em andamento                                                          |
| redis.`aof_rewrite_scheduled`          | boolean  | Sinalizador que indica que uma operação de regravação AOF será agendada assim que o salvamento RDB em                               |
| redis.`blocked_clients`                | counter  | Número de clientes pendentes em uma chamada de bloqueio ( BLPOP , BRPOP , BRPOPLPUSH , BLMOVE , BZPOPMIN , BZPOPMAX )               |
| redis.`client_biggest_input_buf`       | byte     | Maior buffer de entrada entre as conexões atuais do cliente                                                                         |
| redis.`client_longest_output_list`     | list     | Lista de saída mais longa entre as conexões atuais do cliente                                                                       |
| redis.`clients`                        | list     | Seção de conexões do cliente                                                                                                        |
| redis.`cluster_enabled`                | string   | Indica que o cluster Redis está habilitado                                                                                          |
| redis.`connected_slaves`               | counter  | Número de réplicas conectadas                                                                                                       |
| redis.`evicted_keys`                   | counter  | Número de chaves despejadas devido ao maxmemorylimite                                                                               |
| redis.`expired_keys`                   | counter  | Número total de eventos de expiração de chave                                                                                       |
| redis.`expired_stale_perc`             | percent  | Porcentagem de chaves provavelmente expiradas                                                                                       |
| redis.`expired_time_cap_reached_count` | counter  | Contagem de vezes que os ciclos de expiração ativos pararam mais cedo                                                               |
| redis.`instantaneous_input_kbps`       | byte     | Taxa de leitura da rede por segundo em KB / s                                                                                       |
| redis.`instantaneous_ops_per_sec`      | counter  | Número de comandos processados ​​por segundo                                                                                        |
| redis.`instantaneous_output_kbps`      | byte     | Taxa de gravação da rede por segundo em KB / s                                                                                      |
| redis.`keyspace_hitrate`               | percent  | Taxa de acertos de pesquisas bem sucedidas                                                                                          |
| redis.`keyspace_hits`                  | counter  | Número de pesquisas bem sucedidas de chaves no dicionário principal                                                                 |
| redis.`keyspace_misses`                | counter  | Número de falhas na busca de chaves no dicionário principal                                                                         |
| redis.`latest_fork_usec`               | counter  | Duração da última operação de bifurcação em microssegundos                                                                          |
| redis.`lazyfree_pending_objects`       | counter  | Número de objetos esperando para serem liberados (como resultado da chamada de UNLINK ou FLUSHDB e FLUSHALL com a opção **ASYNC** ) |
| redis.`loading`                        | boolean  | Sinalizador que indica se o carregamento de um arquivo de despejo está em andamento                                                 |
| redis.`lru_clock`                      | time     | Relógio aumentando a cada minuto, para gerenciamento de LRU                                                                         |
| redis.`master_repl_offset`             | string   | Deslocamento de replicação atual do servidor                                                                                        |
| redis.`maxmemory`                      | counter  | Valor da maxmemory-diretiva de configuração                                                                                         |
| redis.`maxmemory_policy`               | counter  | Valor da maxmemory-policydiretiva de configuração                                                                                   |
| redis.`mem_fragmentation_ratio`        | float    | Razão entre used\_memory\_rsseused\_memory                                                                                          |
| redis.`migrate_cached_sockets`         | counter  | Número de soquetes abertos para fins de MIGRAR                                                                                      |
| redis.`pubsub_channels`                | counter  | Número global de canais pub / sub com assinaturas de clientes                                                                       |
| redis.`pubsub_patterns`                | counter  | Número global de padrão pub / sub com assinaturas de cliente                                                                        |
| redis.`rdb_bgsave_in_progress`         | boolean  | Sinalizador que indica que um salvamento RDB está em andamento                                                                      |
| redis.`rdb_changes_since_last_save`    | counter  | Número de mudanças desde o último despejo                                                                                           |
| redis.`rdb_current_bgsave_time_sec`    | time     | Duração da operação de salvamento de RDB em andamento, se houver                                                                    |
| redis.`rdb_last_bgsave_status`         | boolean  | Status da última operação de salvamento de RDB                                                                                      |
| redis.`rdb_last_bgsave_time_sec`       | time     | Duração da última operação de salvamento do RDB em segundos                                                                         |
| redis.`rdb_last_cow_size`              | byte     | Tamanho em bytes da memória copy-on-write durante a última operação de salvamento de RDB                                            |
| redis.`rdb_last_save_time`             | time     | Carimbo de data / hora baseado em época do último salvamento do RDB bem-sucedido                                                    |
| redis.`rdb_last_save_time_elapsed`     | time     | Carimbo de data / hora baseado em época do último salvamento decorrido do RDB bem-sucedido                                          |
| redis.`redis_version`                  | float    | Versão do servidor Redis                                                                                                            |
| redis.`rejected_connections`           | counter  | Número de conexões rejeitadas devido ao maxclientslimite                                                                            |
| redis.`repl_backlog_active`            | boolean  | Sinalizador indicando que o backlog de replicação está ativo                                                                        |
| redis.`repl_backlog_first_byte_offset` | string   | Deslocamento mestre do buffer de backlog de replicação                                                                              |
| redis.`repl_backlog_histlen`           | byte     | Tamanho em bytes dos dados no buffer de backlog de replicação                                                                       |
| redis.`repl_backlog_size`              | byte     | Tamanho total em bytes do buffer de backlog de replicação                                                                           |
| redis.`second_repl_offset`             | string   | Deslocamento até o qual os IDs de replicação são aceitos                                                                            |
| redis.`slave_expires_tracked_keys`     | counter  | Número de chaves rastreadas para fins de expiração (aplicável apenas a réplicas graváveis)                                          |
| redis.`sync_full`                      | counter  | Número de ressincronizações completas com réplicas                                                                                  |
| redis.`sync_partial_err`               | counter  | Número de solicitações de ressincronização parcial negadas                                                                          |
| redis.`sync_partial_ok`                | counter  | Número de solicitações de ressincronização parcial aceitas                                                                          |
| redis.`total_commands_processed`       | counter  | Número total de comandos processados ​​pelo servidor                                                                                |
| redis.`total_connections_received`     | counter  | Número total de conexões aceitas pelo servidor                                                                                      |
| redis.`total_net_input_bytes`          | counter  | Número total de bytes lidos da rede                                                                                                 |
| redis.`total_net_output_bytes`         | counter  | Número total de bytes enviados para a rede                                                                                          |
| redis.`total_system_memory`            | counter  | Quantidade total de memória que o host Redis possui                                                                                 |
| redis.`uptime`                         | time     | Tempo de atividade                                                                                                                  |
| redis.`used_cpu_sys`                   | percent  | CPU do sistema consumida pelo servidor Redis, que é a soma da CPU do sistema consumida por todos os threads do processo do servidor |
| redis.`used_cpu_sys_children`          | percent  | CPU do sistema consumida pelos processos em segundo plano                                                                           |
| redis.`used_cpu_user`                  | percent  | CPU do usuário consumida pelo servidor Redis, que é a soma da CPU do usuário consumida por todos os threads do processo do servidor |
| redis.`used_cpu_user_children`         | percent  | CPU do usuário consumida pelos processos em segundo plano                                                                           |
| redis.`used_memory`                    | byte     | Número total de bytes alocados pelo Redis usando seu alocador                                                                       |
| redis.`used_memory_dataset`            | byte     | Tamanho em bytes do conjunto de dados                                                                                               |
| redis.`used_memory_dataset_perc`       | percent  | Porcentagem de used\_memory\_datasetuso de memória fora da rede                                                                     |
| redis.`used_memory_lua`                | byte     | Número de bytes usados ​​pelo motor Lua                                                                                             |
| redis.`used_memory_overhead`           | byte     | Soma em bytes de todas as sobrecargas que o servidor alocou para gerenciar suas estruturas de dados internas                        |
| redis.`used_memory_peak`               | byte     | Pico de memória consumido pelo Redis                                                                                                |
| redis.`used_memory_peak_perc`          | percent  | Porcentagem de used\_memory\_peakfora de used\_memory                                                                               |
| redis.`used_memory_rss`                | byte     | Número de bytes que o Redis alocou conforme visto pelo sistema operacional.                                                         |
| redis.`used_memory_startup`            | byte     | Quantidade inicial de memória consumida pelo Redis na inicialização em bytes                                                        |


[title] Netstat
[path] AIOPS/MÉTRICAS/Explorar as Métricas/

É uma ferramenta utilitária de rede de linha de comando que exibe conexões de rede para o Transmission Control Protocol (entrada e saída) e User Datagram Protocol (UDP), tabelas de roteamento e várias interfaces de rede (controlador de interface de rede ou interface de rede definida por software) e estatísticas de protocolo de rede.

| **Chave**                 | **Tipo** | **Descrição**                                                                                                                                                                              |
| ------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| netstat.`tcp_close`       | counter  | Número de conexões de TCP sem estado.                                                                                                                                                      |
| netstat.`tcp_close_wait`  | counter  | Número de conexões de TCP esperando por uma solicitação de encerramento do cliente.                                                                                                        |
| netstat.`tcp_closing`     | counter  | Número de conexões de TCP que estão esperando por uma solicitação de encerramento com reconhecimento do cliente.                                                                           |
| netstat.`tcp_established` | counter  | Número de conexões de TCP estabelecidas.                                                                                                                                                   |
| netstat.`tcp_fin_wait1`   | counter  | Número de conexões de TCP no estado `FIN_WAIT1` durante o processo de encerramento de uma conexão.                                                                                         |
| netstat.`tcp_fin_wait2`   | counter  | Número de conexões de TCP no estado FIN\_WAIT2 durante o processo de encerramento de uma conexão.                                                                                          |
| netstat.`tcp_last_ack`    | counter  | Número de conexões de TCP esperando o cliente para enviar a confirmação da mensagem de encerramento da conexão.<br /><br />Este é o último estado logo antes que a conexão seja encerrada. |
| netstat.`tcp_listen`      | counter  | Número de portas TCP atualmente escutando uma solicitação de conexão.                                                                                                                      |
| netstat.`tcp_none`        | counter  | Número de conexões de TCP com clientes inativos.                                                                                                                                           |
| netstat.`tcp_syn_recv`    | counter  | Número de conexões de TCP esperando por uma confirmação de solicitação de conexão após enviar e receber uma solicitação de conexão.                                                        |
| netstat.`tcp_syn_sent`    | counter  | Número de conexões de TCP esperando por uma solicitação de conexão correspondente após enviar uma solicitação de conexão.                                                                  |
| netstat.`tcp_time_wait`   | counter  | Número de conexões de TCP atualmente esperando para garantir que o cliente tenha recebido a confirmação da solicitação de encerramento da conexão.                                         |
| netstat.`udp_socket`      | counter  | Número de conexões de UDP atuais.                                                                                                                                                          |


[title] Instalação
[path] AIOPS/Instalação Gerenciada (Homologação/

A instalação da solução poderá ser de forma centralizada ou distribuída, conforme necessidade.

Pode-se instalar em modo Standalone conectando em toda a rede ou de forma distribuída, tendo diversos servidores de coleta e depois centralizando os dados em um único local, eliminando dificuldades na infraestrutuda por conta de firewals, proxys, realizando balanceamento de carga, etc. A forma de instalação dependerá como o Arquiteto da Infraestruturá irá definir.&#x20;

### Instalar e configurar as dependências

```shell
curl -ksSL https://repo.simonops.com/deployments/installer/simon-managed-install.sh | sudo bash
```

O comando acima irá instalar/configurar os seguintes itens:

- Instalação dos repositórios principais (Ex: epel-release, docker-repo, etc)
- Configurações do kernel (sysctl)
- Instalação do Python3 (para uso do simonctl)
- Instalação do Docker + Docker Compose
- Preparação do disco (/dados)
- Simon Client (simonctl)

:::hint{type="warning"}
Observar se apos o comando acima (*simon-managed-install.sh*), as versões correspondentes estão de acordo com a referência abaixo:
:::

### Versões exigidas no repositório

| **Produto**   | **Versão minima** | **Comando**      |
| ------------- | ----------------- | ---------------- |
| Docker Engine | 19.+              | `docker version` |
| Python        | 3.6.8+            | `python3 -V`     |

### &#xD;Simon Control *(simonctl)*

Utilize os comandos a seguir para instalar/atualizar o cli `simonctl`

```shell
# para realizar a instalação:
curl -ksSL https://repo.simonops.com/deployments/setup.sh -o /tmp/setup.sh && chmod +x /tmp/setup.sh && /tmp/setup.sh update

# para realizar a atualização (quando necessário):
simonctl update
```

## Standalone *(singlenode)*

Caso esteja utilizando o modo em Standalone o comando a seguir deverá ser utilizado:

```shell
simonctl standalone
```

Neste comando será realizado a instalação dos seguintes itens na mesma máquina (*singlenode*):

- Instalação da **masternode**
- Instalação da **dbworker**
- Instalação do **proxy**

Caso seja necessário instalar os demais serviços (opcionais): **atomworker** e **traceworker.&#x20;**&#x56;ocê poderá conferir a seguir a instalação dos servidores 3 e 4).

***

# Distributed

## Servidor #&#x31;*&#x20;(master-node)*

1 - Instala os serviços da master-node

```shell
sudo simonctl masternode
```

2 - Configura variaveis de ambiente (simon.env):

```shell
sudo vi /dados/etc/simon.env
```

3 - Prepara banco de dados (inicialização):

```shell
sudo simonctl database
```

4 - Realiza a migração de tabelas (*database schema*):

```shell
sudo simonctl migrate
```

5 - Inicia a configuração da licença:

```shell
sudo simonctl license
```

6 - Inicia os serviços essenciais:

```shell
sudo simonctl start_services
```

7 - Instalação do proxy (base):

```shell
sudo simonctl proxy
```

8 - Instalação do proxy-cert Let's Encrypt *(opcional)*:

```shell
sudo simonctl proxycert
```

9 - Configura repositório dos Agents:

Seguir com a configuração: [Sphere Agent](docId\:vRQe0zUGS3LN_Sy65y70l)

# Servidor #2 *(db-worker)*

1 - Instala os serviços da db-worker:

```shell
sudo simonctl dbworker
```

2 - Inicia os serviços:

```shell
sudo simonctl start_services
```

# Servidor #3 *(atom-worker)*

:::hint{type="info"}
Ao seguir os passos abaixo, você será capaz de implantar e configurar uma instância Atom Worker com sucesso. **A instalação pode ser realizada em um ambiente separado do Simon, permitindo executar coletas de forma isolada**.
:::

### 1 - Instala os serviços da atom-worker:

Para começar, você precisará instalar os serviços Atom Worker. Siga os seguintes passos:

```shell
sudo simonctl atomworker
```

Este comando instalará os serviços Atom Worker no seu sistema.

### 2 - Configura variaveis de ambiente (atom.env):

Agora, é necessário configurar as variáveis de ambiente para a instância Atom Worker. Abra o arquivo **'atom.env'**&#x63;om um editor de texto. Neste exemplo, usaremos o editor **'vi'**, mas você pode usar qualquer editor de texto de sua preferência:

```shell
sudo vi /dados/etc/atom.env
```

Dentro do arquivo **'atom.env'**, configure as variáveis de ambiente necessárias para a instância Atom Worker, como URLs, chaves de autenticação ou quaisquer outras configurações específicas do seu ambiente. Certifique-se de salvar as alterações após a configuração.

### 3 - Inicia os serviços:

Após configurar as variáveis de ambiente, você pode iniciar os serviços da instância Atom Worker. Execute o seguinte comando:

```shell
sudo simonctl start_services
```

Isso iniciará os serviços Atom Worker com base nas configurações que você definiu no arquivo **'atom.env'**. Certifique-se de que os serviços estejam em execução corretamente.

# Servidor #4 - APM *(trace-worker)*

1 - Instala os serviços do trace-worker (APM):

```shell
sudo simonctl traceworker
```

 2 - Configura variaveis de ambiente (trace.yaml):

```shell
sudo vi /dados/etc/trace.yaml
```

- Adicionar ao arquivo a chave de acesso gerado no Atmos: (Página: /atmos/settings/group-api-key)
- Modificar o ip do hostname, para o ip do Server da Masternode

3 - Configura variaveis de ambiente no arquivo (/dados/etc/divedot-agent.env):

- Adicionar ao arquivo a chave gerado no Divedot (Página: /divedot/settings/api-keys)

4 - Inicia os serviços:

***

# Instalando Agent Linux

Para mais informações sobre a instalação e configuração dos agents, acesse o link: [https://docs.simonops.com/sphere-agent](https://docs.simonops.com/sphere-agent)

### Instalando o agent:

```shell
curl -k http://HOST-OU-IP-DO-SIMON/repo/update-sphere-agent.sh | sudo sh
```

Caso o firewall bloqueie (.sh) utilizar a extensão -linux.txt:

```shell
curl -k http://HOST-OU-IP-DO-SIMON/repo/update-sphere-agent-linux.txt | sudo sh
```

# Instalando Agent Windows

### Baixe o arquivo para o diretório e rode o comando no Powershell:

[http://HOST-OU-IP-DO-SIMON/repo/update-sphere-agent.ps1](http://host-ou-ip-do-simon/repo/update-sphere-agent.ps1)

```shell
powershell.exe -ExecutionPolicy Bypass -File .\update-sphere-agent.ps1
```


[title] Processes
[path] AIOPS/MÉTRICAS/Explorar as Métricas/

Traz informações dos processos do host

| **Chave**                 | **Tipo** | **Descrição**                                                                 |
| ------------------------- | -------- | ----------------------------------------------------------------------------- |
| processes.`blocked`       | counter  | Número de processos que estão bloqueados.                                     |
| processes.`dead`          | counter  | Número de processos que estão inativos.                                       |
| processes.`idle`          | counter  | Número de processos que estão ociosos (em suspensão por mais de 20 segundos). |
| processes.`paging`        | counter  | Número de processos que estão em paginação.                                   |
| processes.`running`       | counter  | Número de processos que estão em execução.                                    |
| processes.`sleeping`      | counter  | Número de processos que estão em suspensão.                                   |
| processes.`stopped`       | counter  | Número de processos que estão interrompidos.                                  |
| processes.`total`         | counter  | Número total de processos na instância.                                       |
| processes.`total_threads` | counter  | Número total de threads que compõem os processos.                             |
| processes.`unknown`       | counter  | Número de processos desconhecidos.                                            |
| processes.`zombies`       | counter  | Número de processos zumbis.                                                   |


[title] Redis Cmd Stat
[path] AIOPS/MÉTRICAS/Explorar as Métricas/

Estatísticas de comandos do Redis.

| **Chave**                               | **Tipo**            | **Descrição**                                        |
| --------------------------------------- | ------------------- | ---------------------------------------------------- |
| redis\_cmdsta&#x74;**.**`calls`         | counter             | Número de vezes que um comando redis foi chamado.    |
| redis\_cmdsta&#x74;**.**`usec`          | time (microseconds) | Tempo gasto em microssegundos pelas chamadas.        |
| redis\_cmdsta&#x74;**.**`usec_per_call` | time (microseconds) | Tempo de CPU consumido por chamada de comando redis. |


[title] Postgres
[path] AIOPS/MÉTRICAS/Explorar as Métricas/

**Versões e colunas suportadas**

| **Chave**                          | **Tipo**           | **Descrição**                                                                                                                                                                                                                                                               |
| ---------------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| postgres.`blk_read_time`           | time (miliseconds) | Tempo gasto lendo blocos de arquivos de dados por back-ends neste banco de dados.                                                                                                                                                                                           |
| postgres.`blk_write_time`          | time (miliseconds) | Tempo gasto gravando blocos de arquivos de dados por back-ends neste banco de dados.                                                                                                                                                                                        |
| postgres.`blks_hit`                | counter            | Número de vezes que blocos de disco já foram encontrados no cache do buffer, de forma que uma nova leitura não foi necessária.<br /><br />\* São incluídas apenas ocorrências no cache de buffer do PostgreSQL, não no cache do sistema de arquivos do sistema operacional. |
| postgresql.`blks_read`             | counter            | Número de blocos de disco lidos neste banco de dados.                                                                                                                                                                                                                       |
| postgresql.`buffers_alloc`         | counter            | Número de buffers alocados                                                                                                                                                                                                                                                  |
| postgresql.`buffers_backend`       | counter            | Número de buffers escritos diretamente por um back-end                                                                                                                                                                                                                      |
| postgresql.`buffers_backend_fsync` | counter            | Número de vezes que um back-end teve que executar uma chamada fsync.                                                                                                                                                                                                        |
| postgresql.`buffers_checkpoint`    | counter            | Número de buffers gravados durante os checkpoints.                                                                                                                                                                                                                          |
| postgresql.`buffers_clean`         | counter            | Número de buffers gravados pelo escritor de plano de fundo.                                                                                                                                                                                                                 |
| postgresql.`checkpoint_sync_time`  | time (miliseconds) | Quantidade total de tempo gasto na parte do processamento do ponto de verificação em que os arquivos são sincronizados com o disco.                                                                                                                                         |
| postgresql.`checkpoint_write_time` | time (miliseconds) | Quantidade total de tempo gasto na parte do processamento do ponto de verificação em que os arquivos são gravados no disco.                                                                                                                                                 |
| postgresql.`checkpoint_write_time` | time (miliseconds) | Quantidade total de tempo gasto na parte do processamento do ponto de verificação em que os arquivos são gravados no disco.                                                                                                                                                 |
| postgresql.`checkpoints_req`       | counter            | Número de checkpoints requeridos que foram executados.                                                                                                                                                                                                                      |
| postgresql.`checkpoints_timed`     | counter            | Número de pontos de verificação programados que foram executados.                                                                                                                                                                                                           |
| postgresql.`conflicts`             | counter            | Número de consultas canceladas devido a conflitos com recuperação neste banco de dados. <br /><br />\* Os conflitos ocorrem apenas em servidores em espera.                                                                                                                 |
| postgresql.`datid`                 | string             | OID do banco de dados.                                                                                                                                                                                                                                                      |
| postgresql.`datname`               | string             | Nome do banco de dados.                                                                                                                                                                                                                                                     |
| postgresql.`deadlocks`             | counter            | Número de deadlocks detectados neste banco de dados.                                                                                                                                                                                                                        |
| postgresql.`maxwritten_clean`      | counter            | Número de vezes que o gravador de plano de fundo interrompeu uma varredura de limpeza porque gravou muitos buffers.                                                                                                                                                         |
| postgresql.`numbackends`           | counter            | Número de back-ends atualmente conectados a este banco de dados.                                                                                                                                                                                                            |
| postgresql.`temp_bytes`            | bytes              | Quantidade total de dados gravados em arquivos temporários por consultas neste banco de dados. <br /><br />\* Todos os arquivos temporários são contados, independentemente da razão pela qual o arquivo temporário foi criado.                                             |
| postgresql.`temp_files`            | counter            | Número de arquivos temporários criados por consultas neste banco de dados. <br /><br />\* Todos os arquivos temporários são contados, independentemente do motivo da criação do arquivo temporário.                                                                         |
| postgresql.`tup_deleted`           | counter            | Número de linhas excluídas por consultas neste banco de dados.                                                                                                                                                                                                              |
| postgresql.`tup_fetched`           | counter            | Número de linhas buscadas por consultas neste banco de dados.                                                                                                                                                                                                               |
| postgresql.`tup_inserted`          | counter            | Número de linhas inseridas por consultas neste banco de dados.                                                                                                                                                                                                              |
| postgresql.`tup_returned`          | counter            | Número de linhas retornadas por consultas neste banco de dados.                                                                                                                                                                                                             |
| postgresql.`tup_updated`           | counter            | Número de linhas atualizadas por consultas neste banco de dados.                                                                                                                                                                                                            |
| postgresql.`xact_commit`           | counter            | Número de transações neste banco de dados que foram confirmadas.                                                                                                                                                                                                            |
| postgresql.`xact_rollback`         | counter            | Número de transações neste banco de dados que foram revertidas.                                                                                                                                                                                                             |


[title] Instalação Gerenciada (Homologação
[path] AIOPS/


[title] Avançado
[path] AIOPS/Instalação Gerenciada (Homologação/


[title] Configurações do Proxy
[path] AIOPS/Instalação Gerenciada (Homologação/Avançado/

O proxy http é automaticamente instalado pelo AIOPS. Esta documentação pertmite realizar configurações específicas do proxy reverso ou configuração de CORS.

[title] System
[path] AIOPS/MÉTRICAS/Explorar as Métricas/

O plugin `system` reúne estatísticas gerais sobre a carga do sistema, o tempo de atividade e o número de usuários conectados.

| Chave                  | Tipo                | Descrição                                                      |
| ---------------------- | ------------------- | -------------------------------------------------------------- |
| system.`load1`         | gauge               | Média de carga no último minuto.                               |
| system.`load15`        | gauge               | Média de carga nos últimos 15 minutos.                         |
| system.`load5`         | gauge               | Média de carga nos últimos 5 minutos.                          |
| system.`n_cpus`        | counter             | Número de processadores lógicos.                               |
| system.`n_users`       | counter             | Número de usuários.                                            |
| system.`uptime`        | time<br />(seconds) | Tempo em segundos que o sistema está disponível e operacional. |
| system.`uptime_format` | string              | Formato da coleta do tempo de atividade do sistema.            |


[title] CORS - Nginx Custom Cert
[path] AIOPS/Instalação Gerenciada (Homologação/Avançado/Configurações do Proxy/

:::CodeblockTabs
Observações

```Text
Pré-requesito: Haproxy versão 2.2 ou superior
```
:::

## Nos frontends 80 e 443 adicionar:

```ini
capture request header origin len 128
acl is_options method OPTIONS
acl is_head method HEAD
use_backend cors_backend if is_options or is_head
```

## Criar backend cors\_backend com as seguintes opções:

```ini
backend cors_backend
http-after-response add-header Access-Control-Allow-Origin "https://<dominio>"
http-after-response set-header Access-Control-Allow-Credentials "true"
http-after-response set-header Access-Control-Allow-Methods "GET,HEAD,OPTIONS,POST,PUT"
http-after-response set-header Access-Control-Allow-Headers "accept-language,authorization,X-CSRF-Token"
http-after-response set-header Access-Control-Max-Age "31536000"
http-request return status 200
```


[title] CORS - HAProxy
[path] AIOPS/Instalação Gerenciada (Homologação/Avançado/Configurações do Proxy/

:::CodeblockTabs
Observações

```Text
Pré-requesito: Haproxy versão 2.2 ou superior
```
:::

## Nos frontends 80 e 443 adicionar:

```ini
capture request header origin len 128
acl is_options method OPTIONS
acl is_head method HEAD
use_backend cors_backend if is_options or is_head
```

## Criar backend cors\_backend com as seguintes opções:

```ini
backend cors_backend
http-after-response add-header Access-Control-Allow-Origin "https://<dominio>"
http-after-response set-header Access-Control-Allow-Credentials "true"
http-after-response set-header Access-Control-Allow-Methods "GET,HEAD,OPTIONS,POST,PUT"
http-after-response set-header Access-Control-Allow-Headers "accept-language,authorization,X-CSRF-Token"
http-after-response set-header Access-Control-Max-Age "31536000"
http-request return status 200
```


[title] CORS - Nginx
[path] AIOPS/Instalação Gerenciada (Homologação/Avançado/Configurações do Proxy/

```ini
server {
    server_name _;
    listen 80;
    access_log /var/log/nginx/access.log vhost;
    # add_header Strict-Transport-Security "max-age=31536000" always;

    proxy_hide_header Access-Control-Allow-Origin;
    proxy_hide_header X-Frame-Options;
    proxy_hide_header Content-Security-Policy;
    #
    add_header X-Frame-Options "ALLOWALL";
    add_header Content-Security-Policy "frame-ancestors 'self' '<Domínio>'";
    server_tokens off;
    proxy_cache_bypass $http_upgrade;
    client_body_buffer_size 10M;
    location / {
        add_header Cache-Control no-cache;
        expires 0;
        if ($request_method = 'OPTIONS') {
            add_header Access-Control-Allow-Origin $http_origin always;
            add_header Access-Control-Allow-Credentials 'true' always;
            add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS';
            #
            # Custom headers and headers various browsers *should* be OK with but aren't
            #
            add_header 'Access-Control-Allow-Headers' 'DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization,accept-language';
            #
            # Tell client that this pre-flight info is valid for 20 days
            #
            add_header 'Access-Control-Max-Age' 1728000;
            add_header 'Content-Type' 'text/plain; charset=utf-8';
            add_header 'Content-Length' 0;
            return 204;
        }
        add_header Access-Control-Allow-Origin $http_origin always;
        add_header Access-Control-Allow-Credentials 'true' always;
        proxy_pass http://127.0.0.1:8080;
        proxy_redirect off;
    }
}
```


[title] Certificado (SSL)
[path] AIOPS/Instalação Gerenciada (Homologação/Avançado/

### Padrão - Proxy Cert (SSL)

Por padrão o AIOPS é instalado expondo a porta 80 para uso na intranet. Caso queira apontar um domínio com certificado SSL automático, utilize o container *proxycert* ele registrará um certificado Let's Encrypt através do domínio (Aviso: Lembre-se de expor a porta 80 publicamente durante o registro do domínio).

```shell

# Instalar o certificado automático com Let's Encrypt:
simonctl proxycert

# Se não existir, gerar um novo arquivo dhparam com 4096 bits
openssl dhparam -out /dados/etc/nginx/certs/dhparam.pem 4096

```

### Certificado Próprio (SSL custom)

Colocar os arquivos na pasta `/dados/etc/nginx/certs`

Caso esteja utilizando apenas o container **nginx-proxy** (simonctl proxy)**:**
Editar o arquivo `/dados/etc/nginx/proxy.conf`

Ao utilizar o container de ssl automático **nginx-proxy-cert** (simonctl proxycert)**:**
Editar o arquivo `/dados/etc/nginx/proxy-ssl.conf`

```shell
# Adicionar o conteudo abaixo no arquivo: 
# /dados/etc/nginx/proxy.conf ou /dados/etc/nginx/proxy-ssl.conf

upstream simon.customdomain.com {
    server 127.0.0.1:80;
}

server {
    server_name simon.customdomain.com;
    listen 443 ssl http2;
    ssl_protocols TLSv1 TLSv1.1 TLSv1.2 TLSv1.3;
    ssl_ciphers 'ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES256-SHA384:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA:ECDHE-RSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA:DHE-RSA-AES256-SHA256:DHE-RSA-AES256-SHA:AES128-GCM-SHA256:AES256-GCM-SHA384:AES128-SHA256:AES256-SHA256:AES128-SHA:AES256-SHA:!DSS';
    ssl_prefer_server_ciphers on;
    ssl_session_timeout 5m;
    ssl_session_cache shared:SSL:50m;
    ssl_session_tickets off;
    ssl_certificate /etc/nginx/certs/<arquivo>.crt;
    ssl_certificate_key /etc/nginx/certs/<arquivo>.key;
    ssl_dhparam /etc/nginx/certs/dhparam.pem;
    ssl_stapling on;
    ssl_stapling_verify on;
    add_header Strict-Transport-Security "max-age=31536000" always;
    add_header X-XSS-Protection "1; mode=block";
    add_header X-Frame-Options "SAMEORIGIN";
    server_tokens off;

    location / {
        proxy_pass http://simon.customdomain.com;
    } 
}
```

### Finalizar a configuração

```shell

# Testar a configuração do nginx
docker exec -ti nginx-proxy nginx -t

# A saída do console deverá ser:
# ....
#    nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
#    nginx: configuration file /etc/nginx/nginx.conf test is successful

# Se o teste foi concluído com sucesso, reiniciar o proxy
# Caso utilize o arquivo proxy.conf 
docker restart nginx-proxy

# E/Ou ao utilizar o container proxycert (nginx-proxy-cert)
# através do arquivo proxy-ssl.conf
docker restart nginx-proxy-cert

```

***

# Proxy do APM Traefik (opcional)

É obrigatório que o DNS seja publicado (internet) e adicionado o certificado HTTPS (TLS).

Se houver certificados próprios (TLS), colocar os arquivos na pasta:&#x20;
`/dados/etc/nginx/certs/`

Para configurar o proxy do traefik criar o seguinte arquivo:
`/dados/etc/traefik/dynamic/certs-traefik.yaml`

```yaml
# conteúdo do arquivo de certificado customizado:
# /dados/etc/traefik/dynamic/certs-traefik.yaml
tls:
  certificates:
    - certFile: /etc/certs/example.crt
      keyFile: /etc/certs/example.key
```


[title] Comunicação do Agent
[path] AIOPS/Instalação Gerenciada (Homologação/Avançado/

## Validando a comunicação por GZIP (Compressed)

```shell
curl -XPOST \
  --url https://SIMON-MASTER-NODE/sphere-sync/api/sync/ \
  --header 'Accept-Encoding: gzip, deflate' \
  --header 'Content-Encoding: gzip' \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: chave' \
  --data 'Cg=='
```

## Validando a comunicação pura

```shell
curl -XPOST \
  --url https://SIMON-MASTER-NODE/sphere-sync/api/sync/ \
  --header 'Accept-Encoding: gzip, deflate' \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: chave' \
  --data '{}'
```


[title] Process
[path] AIOPS/MÉTRICAS/Explorar as Métricas/

Traz informações dos processos do host

| **Chave**         | **Tipo** | **Descrição**                                      |
| ----------------- | -------- | -------------------------------------------------- |
| process.`done`    | counter  | Número total de processos concluídos na instância. |
| process.`total`   | counter  | Número total de processos na instância.            |
| process.`waiting` | counter  | Número de processos que estão em paginação.        |


[title] Redis Key Space
[path] AIOPS/MÉTRICAS/Explorar as Métricas/

Informações do dicionário interno gerenciado pelo Redis, no qual todas as chaves são armazenadas.

| **Chave**                          | **Tipo** | **Descrição**                                  |
| ---------------------------------- | -------- | ---------------------------------------------- |
| redis\_keyspac&#x65;**.**`avg_ttl` | gauge    | TTL médio.                                     |
| redis\_keyspac&#x65;**.**`expires` | counter  | Número total de eventos de expiração de chave. |
| redis\_keyspac&#x65;**.**`keys`    | counter  | Número de chaves no keyspace.                  |


[title] Requisitos
[path] AIOPS/Instalação Gerenciada (Homologação/

### Sistemas operacionais suportados:

| **Linux distribution**   | **Versions**                        | **CPU Arch** |
| ------------------------ | ----------------------------------- | ------------ |
| Amazon Linux 2           | all versions                        | x86-64       |
| Amazon Linux AMI         | 2017.x, 2018.x                      | x86-64       |
| ***CentOS \****          | 6.5+, 7.x, 8.x                      | x86-64       |
| ***Oracle Linux \****    | 6.5+, 7.x, 8.0+                     | x86-64       |
| ***Ubuntu \****          | 18.04 LTS, 20.04 LTS, 20.10         | x86-64       |
| Debian                   | 10+                                 | x86-64       |
| Fedora                   | 32+                                 | x86-64       |
| openSUSE                 | 12.x, 13.x, 14.x, 15.0, 15.1, 15.2+ | x86-64       |
| Red Hat Enterprise Linux | 7.x, 8.x                            | x86-64       |
| SUSE Enterprise Linux    | 14.x, 15.0, 15.1, 15.2              | x86-64       |

*S.O. Recomendados:* ***(em destaque)\****.

# Recomendação de Hardware

:::hint{type="warning"}
A recomendação abaixo é uma sugestão que pode ser utilizada na maioria dos ambientes. Em caso de dúvidas ou uma configuração customizada, fale com um de nossos consultores.
:::

### Standalone (singlenode):

Requisitos mínimos para uma máquina virtual rodando todos os serviços em *Singlenode*. Não está sendo considerado a solução de APM do AIOPS (ver tabela - *Dimensionamento - APM Worker*).

| **Tamanho** | **CPU** (vcpus) | **Memória**  | **Disco** (dados) | ***Hosts** estimados* |
| ----------- | --------------- | ------------ | ----------------- | --------------------- |
| Micro       | 4               | 8 GB         | 50 GB             | 0-20                  |
| Small       | 8               | 16 GB        | 200 GB            | 30-100                |
| Medium      | 16              | 24 GB        | 400 GB            | 100-200               |
| Large       | 24              | 32 GB        | 1024 GB           | 200-500               |

### Standalone (singlenode) com AIOPS *SOAR*

| **Tamanho** | **CPU** (vcpus) | **Memória**  | **Disco** (dados) | ***Workflows** ativos* |
| ----------- | --------------- | ------------ | ----------------- | ---------------------- |
| Micro       | 8               | 16 GB        | 100 GB            | 0-4                    |
| Small       | 16              | 24 GB        | 300 GB            | 5-20                   |
| Medium      | 24              | 32 GB        | 500 GB            | 30-60                  |
| Large       | 32              | 64 GB        | 1024 GB           | 70-100                 |

### Distributed (Produtivo)

Requisitos mínimos (1 máquina de cada tipo), com excessão das opcionais que vão de acordo com o tipo de licença contratada. Hosts estimados nesta configuração mínima: **até 2000** (agents + snmp probe)

| **Tipo de Instância&#x20;** | **CPU** (vcpus) | **Memória**  | **Disco** (dados)                          | -                                                            |
| --------------------------- | --------------- | ------------ | ------------------------------------------ | ------------------------------------------------------------ |
| 1. MASTER-NODE              | 8               | 16 GB        | 200 GB                                     | ***obrigatório***                                            |
| 2. DB-WORKER                | 8               | 16 GB        | 500 GB                                     | ***obrigatório***                                            |
| 3. ATOM-WORKER              | 4               | 8 GB         | 50 GB                                      | *opcional* (Ping ICMP, SNMP, <br />Descoberta de Rede, etc.) |
| 4. APM-WORKER               | 8               | 8 GB         | 500 GB (mínimo)<br />1024 GB (recomendado) | *opcional&#x20;*(APM)                                        |

### Dimensionamento - APM Worker

Para melhor dimensionar os recursos, calcular a média de usuários das aplicações monitoradas (incluindo o RUM) determinando a quantidade de conexões por minuto que o servidor irá receber.

| **Pico de conexões / minuto** | **CPU** (vCpus) | **Memória**  | **Disco** (/dados) |
| ----------------------------- | --------------- | ------------ | ------------------ |
| 0-25.000                      | 8               | 16 GB        | 300 GB (mínimo)    |
| 50.000                        | 16              | 24 GB        | 500 GB (mínimo)    |
| 100.000                       | 24              | 32 GB        | 1024 GB (mínimo)   |
| 200.000                       | 32              | 64 GB        | 2048 GB (mínimo)   |

Os valores de CPU, Memória e Disco poderão variar de acordo com o hardware utilizado.

### Pontos de montagem

Os discos são montados através dos seguintes requisitos:

| **Ponto de montagem** | **Tamanho mínimo**                        |
| --------------------- | ----------------------------------------- |
| /                     | 50GB+                                     |
| /tmp, /opt            | 4GB+ (ou equivalente ao root "/" )        |
| /dados                | ***(de acordo com o tipo de instância)*** |

:::hint{type="danger"}
Antes de iniciar a instalação, certifique-se se o ponto de volume **/dados** já esteja montado, caso contrário a instalação será realizada na partição raiz "/".
:::

:::hint{type="warning"}
Embora seja possível utilizar o disco de dados em **NFS (Network File System)&#x20;**&#x6E;ão é recomendado para o volume dos containeres docker (/var/lib/docker).
:::

# Requisitos para Instalação

- Dimensionamento dos discos (raiz **"/"** e de dados **"/dados"**)
- Para realizar a instalação, liberar acesso da máquina à internet (completo), ou quando não for possível, liberar no mínimo os seguintes domínios:
  - Repositório AIOPS (private):
    - **repo.simonops.com**
    - **docker.simonops.com**
    - **space.simonops.com**
  - Docker (public):
    - download.docker.com
    - auth.docker.io
    - registry-1.docker.io
    - index.docker.io
    - production.cloudflare.docker.com
  - Oracle/CentOS
    - olcentgbl.trafficmanager.net
    - mirrorlist.centos.org


[space] Anuva EN (/anuva-en)

[title] Configuration
[path] Untitled/


[title] Making Anuva available on the CITSmart Interface
[path] Untitled/Untitled/

Anuva is already natively integrated with CITSmart, so it is easy to add it to your environment.

## Procedure

1. With Administrator access, access the CITSmart parameter screen;
2. Change the parameter value “402 Anuva Assistant - External URL” to http\://\[name-server].anuvaassistant.com
3. Change the parameter value “441 Anuva Assistant - Conversation API” to http\://\[name-server]\[acronym-language].anuvaassistant.com/webhooks/rest/webhook and click on “Save”
4. Change the parameter value “442 Anuva Assistant - Parameters API” to http\://\[name-server]\[acronym-language].anuvaassistant.com/conversations/
5. Configure parameter 453 "Default Anuva Assistant Fallback Message", with a message that Anuva will answer whenever it has no answer to that question.
6. Enable parameter 423 "Enable Anuva Assistant in the internal area of the system", a parameter that allows analysts to iterate with ANUVA
7. Enable parameter 450 "Enable Anuva Assistant in the external area of the system", a parameter that allows end-users to iterate with ANUVA.

:::hint{type="info"}
**NOTE:**

For the acronym of the languages, use EN (English) and PT (Portuguese-Brazil).
If these parameters are not available, upgrade your version of CITSmart.
:::


[title] Release Notes Anuva
[path] Untitled/

# Welcome to the new Build 1.0.0.0 of the Anuva Platform.

This new version has the improvements listed below that will offer a complete experience for customers, in addition to more performance and
&#x20;flexibility to export and import data, feel free to explore the new
&#x20;improvements and, of course, whenever you want, send us feedback about them.

| **Code** | **Functionality**                                                                           |
| -------- | ------------------------------------------------------------------------------------------- |
| 6380     | Importing "intents and phrases" from Watson workspace.                                      |
| 6941     | Exporting bot conversations in spreadsheets.                                                |
| 6945     | Parametrization of the percentage of intentions accuracy and dialogs for ChatBot.           |
| 6942     | Registration of emails to send notifications of training and deployments.                   |
| 5228     | Importing and Exporting Anuva's registered dialogues in spreadsheet format.                 |
| 6944     | It allows the use of links in actions. (add http or https in website links)                 |
| 6831     | Registration and administration of new users.                                               |
| 6943     | Update to new version of ElasticSearch to improve AI algorithm and data search performance. |

In addition to the improvements above, this new Build takes some identified corrections listed below.

| **Code** | **Functionality**                                                                                                                  |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| 6864     | Scheduling component error causing training scheduling error.                                                                      |
| 6602     | Error in the behavior of the dialog entries preventing incomplete data from being sent to the bot training causing many fallbacks. |
| 6832     | Memory overflow error on servers responsible for bot training causing bot training failure.                                        |


[title] Use
[path] Untitled/


[title] Overview
[path] /

## What's Anuva

Anuva is the CITSmart Artificial Intelligence platform. The first feature available was a virtual assistant, the Anuva Assistant, a chatbot that communicates and interacts with people through automated text messages.

Anuva uses artificial intelligence to conduct dialogues with increasingly improved users on different platforms and, in addition to interacting with users, is able to integrate with other systems to get answers to questions, retrieving data through APIs.

## Anuva Operation

Anuva uses 5 main concepts in its operation:

- **Build:&#x20;**&#x74;hrough its interface, it is possible to create conversation flow examples (dialogues).   So it can learn how to react to user interactions;
- **Train:&#x20;**&#x61;fter creating the dialogue examples, it is possible to train the Anuva so it will consider the examples given in their interactions. Unlike most solutions, Anuva uses artificial intelligence to understand what the user meant, so it is not necessary for the user to type exactly the same sentence that was given as an example;
- **Code:&#x20;**&#x49;t is possible to connect Anuva with external APIs, allowing data access necessary to deliver value to the user;
- **Connect:&#x20;**&#x49;t is possible to integrate Anuva to different messaging platforms, natively, it can already be integrated with Facebook and CITSmart;
- **Monitor:** Once it is made available to the user, it is possible to follow the conversations made by Anuva, in order to improve the training information and gain insight into new dialogues to be taught to Anuva.

## Accessing Anuva

After the release of your Anuva environment, access the configuration environment of Anuva through the link provided by CITSmart. (http\://.anuvaassistant.com).

In this environment, you will be able to add and review knowledge to Anuva, you can schedule training, follow the interactions made by Anuva and conduct interaction tests to validate if interactions are being effective.


[title] How to Teach Anuva
[path] Untitled/Untitled/

Anuva learns from the dialogues added to its knowledge base. These dialogues are structured in **Interests** (possible phrases used in user interaction) and **Abilities** (possible chatbot responses to user interactions).

Since Anuva works reactively to user interactions, in order to form dialogues we need to group interests and abilities in pairs. Contexts will be used only when, during the dialog, it is necessary to store some information that the user refers to for use in another point of the conversation.

It is up to the chatbot administrator to provide this data to the system, structurE the possible dialogues, and carry out the training of the set. The training should be scheduled through the Anuva interface, and at the end of the training, your Anuva will be updated automatically.

## Procedure

1. Access the menu “Dialogues”;
2. Click on "New" and select one of the options: Simple (only an Interest-Ability interaction) or Complex (when joining multiple simple dialogues);
3. Inform the Theme related to the Dialogue, this will help you to categorize them, later. A new theme can be registered in the "Theme" menu;
4. In the **Interests** section, complete the phrases related to the user Interest and click on "Save";
5. In the **Abilities** section, complete the fields on the screen, paying attention to the ability type:
   - Standard: it will be used to represent abilities that are answered through a predefined text response. Several predefined answer phrases can always be assigned to answer the same question;
   - Customized: it will be used when, in order to respond to a user's interest, Anuva needs to seek information on another system. Access the document “How Anuva can interact with other systems” to understand how to use this type of ability;
   - Button: it will be used whenever it is necessary to limit user responses to a particular Anuva interaction. When using this option, Anuva will respond to user interaction by displaying buttons. A button is defined by its Name and Value. In the name field, the button that will appear for the user is defined. In the value field, it is defined to              Anuva how it should interpret the user's interest by clicking on the button;
   - Image: it can be used when you want to respond to the user using text and image. The image associated with the response will be displayed in the chat window.
6. Click on "Save".

:::hint{type="info"}
**NOTE:**

\- Complex dialogues help Anuva to be more assertive in a conversation that is long, use it to guide it&#x20;
to how to respond in those situations;

\- Anuva's understanding is made by approximation, so the more phrases you add to the interest, the more precise it will be in understanding the user's interaction. Remembering that the user does not have to type the exact phrase that was added to the interest since Anuva works with Artificial Intelligence;
&#x20;          &#x20;
\- Remember to add at least one dialog with fallback ability. It will be used when your Anuva cannot understand&#x20;
the user's interest or understand with an accuracy of less than 20%. You can view the accuracy of each interaction&#x20;
in the menu Analytics > List conversations.
:::


[title] Creating Contexts to Anuva
[path] Untitled/Untitled/

The dialogues are immersed in contexts. Equal words can have different meanings depending on the context. In order to increase accuracy in homonyms situations and avoid repetition of sentences because of synonyms. It is possible to register a context basis for Anuva to distinguish homonyms and the correlation between synonyms.

## Procedure

1. Access the menu "Contexts" and click on "New";
2. Complete the fields name and description;
3. Click on "Add" to put the Reference Value;
4. When you create a reference value, a new Add button will appear for you to include the synonyms for that value, so you must make the additions and click on "Save".

:::hint{type="info"}
**NOTE:**

It is necessary to link the contexts to the sentences of Interest within the Dialogue,&#x20;
so that the information is processed by Anuva
:::


[title] Monitor Anuva Interactions
[path] Untitled/Untitled/

Once trained, it is necessary to monitor Anuva's interactions with users to ensure that it is being effective in attending to the requests.

These interactions can be viewed in the Analytics Menu. In addition to displaying the dialogs of Anuva with the users, in this menu, it is possible to visualize indicators of the utilization of the added knowledge, as well as, the fallback indexes.

## Before getting started

You must have at least one training and some interaction with Anuva.

## Procedure

1. Access the main menu Analytics;
2. Access one of the options available.

:::hint{type="info"}
**NOTE:**

When accessing the list of conversations, click on each sentence of the dialog to see the percentage of&#x20;
assertiveness with which Anuva understood the user's interest, indices lower than twenty percent make&#x20;
Anuva uses the fallback ability.
:::


[title] Training
[path] Untitled/Untitled/

**"What does it mean to train my virtual assistant?**

It is the act of placing your assistant to understand how the interactions with the user will be, considering the dialogs constructed. Whenever new interactions are added, the assistant must be retrained so it can react as expected in a conversation.

## Before getting started

Make sure that all parametrization and configurations are correct and there is at least one dialog created.

## Procedure

### How to train Anuva

In the Training screen, it is possible to schedule updates so that your Anuva can interact with the user
&#x20;considering the last added knowledge. This functionality allows scheduling the training according to your
&#x20;need and can even define recurrence.

1. After accessing the platform, go to the menu "Training";
2. Click on "Schedule";
3. Define the scope of the update you want, with the following options: Dialogues, Complete, Skills (Text - Button - Image) or Custom skills;
4. Inform the day and time for the training to be performed.

:::hint{type="info"}
**INFORMATION:**

The duration of the training will depend on the volume of dialogues registered but do not worry,&#x20;
once the training is completed, Anuva will be updated automatically. At any time, you can start a&#x20;
conversation with Anuva to check the effectiveness of its interactions by clicking on the floating&#x20;
icon located in the lower right corner of the screen. Remember that it will reflect the knowledge&#x20;
added from the latest training.
:::

## Troubleshoot

### Finalizing a training

After you start the training, the app does not have an option to end the process, but sometimes this might be necessary. The following instructions will help you complete this task, which consists of cleaning the task queue and terminating the instance related to the process.

```Text
1. Access the service Simple Queue Service on AWS dashboard  
2. Find a queue named citsmart-anuvaassistant-training-<ambiente> and select it. For example, the name of the environment "homologation" on the queue would be citsmart-anuvaassistant-training-homologation.  
3. Click Actions and select "Purge"  
4. Type the required term and click the button "Purge"  
5. After this, the queue should be empty.  
```

To terminate the instance, follow these instructions:

```Text
1. Access the service EC2, on AWS dashboard.  
2. Click the link Instances (running)  
3. Search for an instance that contains the term “spot”  
4. Select the instance  
5. Click Actions and request to stop the instance, and confirm your decision clicking the button "Stop"  
6. Click Actions and request to terminate the instance, and confirm your decision clicking the button "Terminate"  
7. After this, a message should appear showing the removed instance.  
```

### The training does not start

When trying to start a scheduled training, an error might happen and the training will not start. One of the causes for this is when the schedule of python is broken and fails to put the training on queue.

```Text
1. To confirm if the error is due to the schedule of python, look for the queue named "citsmart-anuvaassistant-training-homologation" on AWS Simple Queue Service.  
2. Under normal situations, this queue should show no messages.  
3. If there is a mistake, the queue will show 1 scheduled in on the message column.  
4. If that's the case, it's necessary to stop and restart the EC2 instance "anuvamultitenancyapihom_app".  
5. After restarting the instance, remove the scheduled training and schedule it again.
```

### Intents ranking not showing

This problem happens when the instance anuvamultitenancyapihom\_app has a change on IP, for some reason, and the new IP is not on the list of authorized access of the Elasticsearch service. If that's the case, an error message will appear on several points when showing the rankings.

To solve this problem, the IP of the instance anuvamultitenancyapihom\_app must be added to the authorization list, under the Elasticsearch access policy. To do this, it's necessary to obtain the current IP of EC2 anuvamultitenancyapihom\_app, access the Elasticsearch service panel, and include the IP on the authorized list. To obtain the IP, follow these steps:

```Text
1. Access EC2 instances administration panel.  
2. Filter instances that are running/active  
3. Select the proper instance and copy the IP address.
```

To access the Elasticsearch panel and include the IP on the list:

```Text
1. Select the menu Analytics > Elasticsearch Service
2. On the dashboard, click My Domains and select the correct service
3. After selecting the service, click the button Actions > Modify Access Policy
4. On this page, add the IP number on the authorization list and click Submit to apply changes.
```

## Automated Tests

Software tests are included in the Application Lifecycle Management (ALM). It is a primordial step to ensure the quality of the product delivered to the clients or to be used by the developers' team to confirm the assertiveness.

We automatize these tests to avoid repetitive manual jobs, obtain quicker feedback, save time running tests in sequence, and make sure we are always testing consistently with the same preconditions and expectations.

Generally, the reasons for testing are:

- Verify if the program is within the client's expectations;
- Verify any bugs before the clients;
- Detect design problems;
- Make sure the system is stable;
- Ensure the quality of the work of the developers' team;

To automatize tests of the referred project, we use the Cypress tool. One of the great advantages of Cypress is that, while most test tools run outside the browser, running remote network commands, Cypress is executed on the same execution loop as the application being tested, which allows for greater interactivity.

The following procedures will instruct you on the installation and basic configurations to start and interact with the testing project. It will also teach you how to document the standard criteria used for the best practices.

**1. Functional Test**

This will test all the functioning requirements of the application. It will quickly verify if the app is able to perform the functions it was designed to do, and it can cover all functions within the scope, BackEnd, and FrontEnd.

**2. Installation and configuration**

Beforehand, you must have installed Node.js, and IDE VsCode is also recommended. If these requirements are met, follow these instructions:

- **Create work directory:&#x20;**&#x4D;ake a directory for the project, for example,*&#x20;cypress-tests $ mkdir cypress-tests*
- **Create the project:&#x20;**&#x41;ccess the new directory and start the project with the following command, which will generate all of the necessary structure: *$ npm init -y*
- **Install cypress:&#x20;**&#x53;till on the same directory, install Cypress as indicated: *$ npm install cypress*

If necessary, complete instructions can be obtained on the official documentation.

:::hint{type="info"}
**NOTE:**

&#x20; If you wish to install a specific version, 4.6.2 for example, use the following command:&#x20;

*$ npm install cypress\@4.6.2*
&#x20;     &#x20;
:::

**3. Configure VsCode**

As we previously suggested, we will use VsCode as IDE for developing our tests, therefore it should be installed beforehand. We will add to the file package.json the command used to run the project. This will hasten the procedure. Edit the file package.json, and in the topic script, add the following command:

*$ "scripts": \{ "cypress\:open": "cypress open"*
&#x20;
&#x20;**4. Execute project:**

After including the previous command, the project can be executed with the command line:

*$ npm run cypress\:open*

or through VsCode, under Outline > NPM Scripts > package.json > cypress\:open > button "play"

**5. Files and directories structure**

The following structure of files is recommended to keep the organizational standards of the project. However, there are no technical restrictions to use other standards, and the best practices described are just a convention for the referred project:

| **I. Fixtures:** | The Directory is destined to files that will contain dictionaries with data used by the tests when filling information. Some best practices are: |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |

- The use of fixtureS is a best practice to hasten the development and maintenance of the project, as it will gather all the variable data of the project in a single place.
- For organizational purposes, there must be a fixture file for each test file.
- Overly extensive blocks should be avoided. When the volume is too big, they should be divided into smaller blocks.
- The commands should not deal with the data directly. The data should be manipulated in the intents.

| **II. Integration:&#x20;** | The Directory is meant to contain tests to be performed by the application. Some best practices are:  |
| -------------------------- | ----------------------------------------------------------------------------------------------------- |

- These files should be restricted to the logic of the tests and data manipulation, leaving the commands to deal with the execution procedures and interactions with screens and API's.&#x20;
- For organizational purposes, there should be one command file for each test file.
- The test files should not deal with screen components directly. These components should be managed by the commands files. Therefore, locators files should not be imported.
- The test files import fixture files to manipulate data and pass them over to commands.

| **III. Plugins:&#x20;** | The Directory is meant to contain registers for eventual plugins used in the project.                                                     |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| **IV. Support:&#x20;**  | The Directory is meant to contain support codes to the text files, and it must contain the following directories for grouping purposes:   |

- **commands:&#x20;**&#x54;hese files are used by the tests, located in the directory integration. It must contain the command codes used by the tests. Besides individual command files for each test, there is also a Global use file. Some best practices are:&#x20;
  - Using commands is a best practice to hasten the development and maintenance of the project, as it avoids using redundant codes.
  - For organizational purposes, there must be a command file for each test file.
  - Commands should not deal with data directly. Data should come from the parameters, and they should not import fixture files.&#x20;
  - The commands import locators files. &#x20;
  - Keep the files in alphabetical order, as it makes finding and reading easier. Besides, it also leads to intuitively creating a naming pattern for them.
  - The global commands file, as the name implies, should contain the commands for global tests. A good example of this is the method of URL verification, which can be the same for the whole app. &#x20;
    &#x20;               &#x20;
- **Locators:** Directory meant to contain files that register the access addresses of widgets, URLs, and other addresses. As determined by the best practices mentioned before, locators files should be imported and used by the commands. Besides individual locator files for each test, there is also a Global use file. Some best practices are:    &#x20;
  - The use of locators is a best practice to hasten the development and maintenance of the project, as it groups the access to widgets and URLs in a single place.&#x20;
  - The use of locators is a best practice to hasten the development and maintenance of the project, as it groups the access to widgets and URLs in a single place. &#x20;
  - Locators files should be imported by commands. &#x20;
  - There must be a locator file for each test file. &#x20;
  - Overly extensive blocks should be avoided. When the volume is too big, they should be divided into smaller blocks. &#x20;

| **V. node\_modules:**         | The Directory is meant to contain the registry and library files used by the project.                                                                 |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| **VI. cypress.json:**         | The Central configuration file of Cypress. It contains values of system variables of global use. Use this file to register URLs used by the system.   |
| **VII. package.json:&#x20;**  | Data file containing application registries and scripts that automate initialization processes.                                                       |
| **VIII. package-lock.json:**  | The File contains registries of external libraries used by the application.                                                                           |
| **IX. .gitignore:&#x20;**     | The File contains the relation of files and or directories that should **not** be versioned by Git.                                                   |
| **X. index.js:**              | The File contains initial calls of the test system.                                                                                                   |

****

**6. Naming standards &#x20;**&#xD;

New files should follow the naming standards below: &#x20;


*\< contents > \< Module > .js* &#x20;

Examples:

```Text
    - Fixture files: datasContext.js / datasTheme.js 
    - Commands files: commandsContext.js / commandsLogin.js  
    - Locators files: locatorsLogin.js / locatorsTheme.js    
```

:::hint{type="info"}
**Note:**

Notice that plurals should be used only in the contents, as this usually refers to more than one item, and that the identification of the module always starts with capital letters.&#x20;
:::

Within this structure, there is an exception regarding the actual test files, which are in the integration directory. These files should be named according to the following standard:

*\< module > .spec.js*

Examples:

```Text
    - context.spec.js  
    - login.spec.js  
    - theme.spec.js
```

[title] How to make Anuva interact with Other Systems
[path] Untitled/Untitled/

In order for Anuva to interact with other systems, it is necessary to add a custom ability in the dialog.

The query is made through a Rest API, which must be made available by the system that holds information of interest to the user. Eg.: search for information on the status of a ticket, creation of tickets, generation of bills in the system.

## Procedure

1. Access the menu “Dialogs” and click on “New”;
2. Complete the information of the **Interest** section;
3. In the **Ability** section, select the type *Customized*;
4. Complete API Section information, including body example and response;
5. If necessary, enter the heading;
6. In the Answers section, we have two action options:

:::hint{type="info"}
**NOTE:**

The integration needs to be homologated by CITSmart, so after setting up this skill, you need&#x20;
to open a ticket for us to do the homologation of the integration.
:::


[title] Store Information in Dialogues
[path] Untitled/Untitled/

Many times, the user during a dialogue, provides us information that will be used at another time for a better understanding of the user's interest. Anuva recognizes this information as Attributes.

In a conversation, for example, in which the user requests that Anuva inform which Italian restaurants exist within 10 km distance, we can have three attributes: type of establishment, category, and distance.

In this case, we create Attributes that are able to store this information to respond more accurately to the user.

Attribute types define the format of the information that can be saved in it. Anuva works with the following types:

- Text slot: where you can add text-type values;
- Boolean slot: used for values that are set to true or false;
- Categorical slot: used to store a value from a predefined list;
- Float slot: where we can add numerical values with minimum and maximum limits.

:::hint{type="info"}
**NOTE:**

It would not be possible to create interest that represented all possible combinations&#x20;
for the three pieces of information. In this case, the ideal would be to use the attributes.
:::

## Procedure

1. Access the menu "Attributes";
2. Click on "New";
3. Complete the name and type of the attribute;
4. Enter the other required fields according to the type and click on "Save".


[space] Anuva - PT (/anuva-pt)

[title] Release notes Anuva
[path] /

# Bem-vindo a nova Build 1.0.0.0 do Anuva Platform.

Esta nova versão conta com as melhorias abaixo listadas que vão oferecer
uma experiência mais completa para os clientes, além de mais performance e
flexibilidade para exportar e importar dados, fique a vontade para explorar as
novas melhorias e claro, sempre que quiser nos envie feedbacks sobre elas.

| Código | Funcionalidade                                                                                                 |
| ------ | -------------------------------------------------------------------------------------------------------------- |
| 6380   | Importação de “intents e frases” do workspace do Watson.                                                       |
| 6941   | Exportação de conversas do bot em planilhas.                                                                   |
| 6945   | Parametrização de percentual de acurácia de intenções e diálogos para o chatBot.                               |
| 6942   | Cadastro de e-mails para envio de notificações de treinamentos e implantações.                                 |
| 5228   | Importação e Exportação de diálogos cadastrados da Anuva no formato de planilhas.                              |
| 6944   | Permitir o uso de links nas actions. (adicionar http ou https nos links dos sites)                             |
| 6831   | Cadastro e administração de novos usuários.                                                                    |
| 6943   | Atualização para nova versão do ElasticSearch para melhora de algoritmo de IA e performance de busca de dados. |

Além das melhorias acima esta nova Build leva algumas correções identificadas que
seguem listadas abaixo.

| Código | Funcionalidade                                                                                                                                      |
| ------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| 6864   | Erro no componente de agendamento causando erro no ato de agendamento de treinamento.                                                               |
| 6602   | Erro no comportamento dos cadastros de diálogos impedindo que dados incompletos sejam enviados para o treinamento do bot causando muitos fallbacks. |
| 6832   | Erro de estouro de memória nos servidores responsáveis pelo treinamento do bot causando falha nos treinamentos do bot.                              |

[title] Habilidades
[path] /

As habilidades dentro da assistente virtual têm a funcionalidade de possíveis respostas do chatbot às interações do usuário, podendo ser um erro utilizando o fallback ou até mesmo uma habilidade pré-definida para responder ao usuário.

## Fallback

Fallback é uma habilidade cadastrada para o caso de a assistente virtual não conseguir compreender a mensagem ou o objetivo do usuário, isso acontece quando o usuário solicita algo diferente dos contextos cadastrados.

Dessa forma a assistente virtual utiliza algumas frases pré-definidas pelo administrador da Anuva, que serão enviadas ao usuário como por exemplo “Não entendi”, “Ainda não fui programada para responder isso”, “Pode reformular, não entendi o que quis dizer” etc. Assim a sua assistente virtual pode avisar o usuário final que esse pedido não pôde ser realizado ou compreendido, mostrando para o usuário realizar outro pedido ou definir outro objetivo.

## Habilidade Estendida

Quando um usuário quer que a assistente virtual faça uma habilidade além das pré-configuradas (texto, botão, imagem ou personalizado), através dessa habilidade ele solicita essa nova habilidade para a equipe administradora da Anuva que vai fazer o que o cliente solicitou com o nome que ele escolher.

## Nova Habilidade

1. Após acessar a plataforma, acesse o menu “Habilidades”. É possível gerenciar as habilidades podendo editar, excluir e criar uma habilidade;
2. Clique em novo para criar uma habilidade;
3. Preencha os campos conforme necessidade:

| **Campo**                                                                            | **Descrição**                                                                                                                                                       |
| ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Nome                                                                                 | Preencha com o nome de identificação da habilidade.                                                                                                                 |
| Tema                                                                                 | Selecione o tema entre a lista de temas criados no menu “Temas”.                                                                                                    |
| Esta é uma habilidade de fallback?                                                   | Selecione se a habilidade é fallback ou não                                                                                                                         |
| Esta é uma habilidade estendida?                                                     | Selecione se esta habilidade é uma habilidade estendida                                                                                                             |
| Deseja predefinir o comportamento do bot com base na última interação com o usuário? | Selecione se essa habilidade deve predefinir um comportamento do bot com base na última interação com o usuário final, selecione o “**Contexto**” e o “**Diálogo**” |

4\.  Preencha os campos da tela, atentando-se ao tipo da habilidade: 

- **Padrão**: será utilizada para representar habilidades que são respondidas  através de uma resposta de texto pré-definida. Podem ser  tribuídas várias     frases pré-definidas de respostas sempre visando responder a mesma pergunta;     
- **Personalizada**: será utilizada quando, para responder a um interesse do     usuário, a Anuva precisar buscar informações em um outro sistema.
- **Botão**: Será utilizada sempre que for necessário limitar as respostas do usuário a uma determinada interação da Anuva. Ao utilizar essa opção, a Anuva responderá a interação do usuário exibindo botões. Um botão é definido por seu Nome e Valor.

No campo nome, é definido o botão que aparecerá para o usuário. No campo valor, é definido para a assistente como ela deve interpretar o interesse do usuário ao clicar o botão; 

- **Imagem**: Pode ser utilizada quando desejar responder o usuário utilizando  texto e imagem. A imagem associada a resposta será exibida na janela do chat.

5\.  Clique em “Salvar” para finalizar o cadastro.


[title] Anuva Analytics
[path] /

Após treinar as interações e diálogos da Anuva, é preciso monitorar as interações da sua assistente com os usuários para garantir que ela está sendo efetiva no atendimento às solicitações e assim garantir a sua qualidade e assertividade. 

Essas interações podem ser visualizadas na opção Analytics. É a sessão da plataforma responsável por visualizar relatórios e indicadores. Os módulos estão divididos da seguinte forma: Lista de Conversação, Rankings de Intents, Ranking de Respostas e Ranking de Fallback.

### Antes de começar

- É necessário ter realizado pelo menos um treinamento;
- E ter realizado ao menos uma interação com a assistente virtual.

### Procedimento

1. Após acessar a plataforma, acesse o menu “Analytics”;
2. Selecione um dos módulos disponíveis: Listar Conversas, Rankings de Intents,
   Ranking de Respostas e Ranking de Fallback.

## Listar conversa

Neste módulo é possível visualizar todas as conversas realizadas pelo chatbot
durante um intervalo de tempo selecionado. O sistema apresentará informações
relativas as conversas realizadas nesse período.

Após clicar em “Listar conversa”, primeiramente, é obrigatório a definição de um
período de tempo no campo “Intervalo”.

Depois de definir um tempo, clique em “Filtrar”.

A ferramenta apresentará as informações de conversação dependendo do tempo de
sua escolha.

Teremos as seguintes informações para análise:

| **Função**               | **Descrição**                                                                                                                                                                                       |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Data e hora              | A data e hora que foi realizada a conversa entre um usuário e a assistente.                                                                                                                         |
| Versão                   | A versão vai variar de acordo com a maturidade do chatbot. Isso significa que a versão da assistente muda de acordo com a quantidade de informação que recebe e os treinamentos a qual é submetida. |
| Canal                    | O canal que o usuário utilizou para a conversa. Podendo ser de canais diferentes, conforme os configurados na plataforma Anuva. Por exemplo: Facebook, Twitter, Smart Chat, entre outros.           |
| Identificação do usuário | A identificação do usuário que conversou com a assistente.                                                                                                                                          |

Além dessas informações, também apresenta duas opções:

| **Função** | **Descrição**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Ver        | Nessa opção é possível ver o detalhamento da conversa entre o usuário e a assistente. O balão de cor azul é a mensagem do usuário. Podemos ver que abaixo dele existe uma porcentagem, que significa a acurácia da assistente e, ao lado, a intent que foi entendida pela Anuva. Caso queira incluir essa frase do usuário à intent entendida, basta clicar nela que você será redirecionado para a página de diálogos. Já o balão de cor branca é a mensagem enviada pela assistente. Abaixo dele a habilidade que foi cadastrada para esse tipo de intent. Caso queira incluir algo novo dessa conversa para a habilidade, basta clicar nela e você também será redirecionado para a página de diálogos. Além disso, também são apresentadas as opções “Atualizar”, caso a conversa ainda esteja acontecendo e você queira receber as novas mensagens; “Exportar” para realizar o download dessa conversa; e “Voltar” para voltar a página anterior. |
| Download   | É possível baixar a conversa em formato xls, onde você poderá ver as interações entre usuário e chatbot.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |

## Ranking de intents

Nesta modalidade é permitido verificar em formato de gráfico quais intents estão sendo mais utilizadas pelos usuários do sistema, ou seja, o que os usuários estão mais perguntando e/ou demandando da assistente.

Após clicar em “Ranking de intents”, primeiramente, é obrigatório a definição de um período de tempo no campo “Intervalo”. Depois de definir um tempo, clique em “Filtrar”.

Será apresentado um gráfico com as principais intents de acordo com o período selecionado. No lado esquerdo está o gráfico em si, em dias, e no lado direito a legenda do que representam as cores e suas determinadas intents.

Ao final de cada intent existe uma lupa. Ao clicar nessa lupa, você será direcionado para a página de lista de conversa dessa intent, que mostrará a lista dependendo do período informado para o gráfico.

Além disso, ao clicar em alguma intent da legenda, você será direcionado para a página de diálogo relacionada, onde é possível analisar se as frases estão corretas ou fazer alguma alteração.

## Ranking de respostas

Funciona de forma parecida ao ranking de intents. Nesta modalidade é permitido verificar quais habilidades estão sendo mais utilizadas pelos usuários do sistema, ou seja, o que a assistente mais responde durante a interação com o usuário.

Após clicar em “Ranking de respostas”, primeiramente, é obrigatório a definição de um período de tempo no campo “Intervalo”. Depois de definir um tempo, clique em “Filtrar”.

Será apresentado um gráfico com as principais habilidades de acordo com o período selecionado. No lado esquerdo está o gráfico em si, em dias, e no lado direito a legenda do que representa as cores e suas determinadas habilidades.

No final de cada habilidade existe uma lupa. Ao clicar nessa lupa, você será direcionado para a página de lista de conversa dessa habilidade, que mostrará a lista dependendo do período informado para o gráfico.

Além disso, ao clicar em al guma habilidade da legenda, você será direcionado para a página de diálogo relacionada, onde é possível analisar se as frases estão corretas ou fazer alguma alteração.

## Ranking fallback

Nesta modalidade podemos verificar quais são as intents que o sistema não conseguiu entender, ou seja, quais interações com usuário que foram insatisfatórias pois a assistente não conseguiu entender o objetivo da mensagem.

O fallback, para o sistema, é uma habilidade previamente cadastrada que apresenta uma mensagem como resposta ao usuário, criada por um administrador da plataforma a fim de informar ao usuário que a assistente não tem conhecimentos, cadastrados e treinados, suficientes para atender à solicitação.

Após clicar em “Ranking fallback”, primeiramente, é obrigatório a definição de um período de tempo no campo “Intervalo\*”. Depois de definir um tempo, clique em “Filtrar”.

Será apresentado um gráfico com a habilidades de fallback que não foi entendida pela assistente, de acordo com o período selecionado. No lado esquerdo está o gráfico em si, em dias, e no lado direito a legenda com a habilidade de fallback.

Ao clicar na legenda do fallback, você será direcionado para a página de lista  de conversa dessa habilidade dependendo dos dias selecionados no filtro de intervalo. Ao ver essas conversas, o analista pode verificar se a falta de compreensão da assistente é correto, ou seja, se o usuário está demandando algo fora do escopo de criação dela ou se é uma carência, e nesse caso o
administrador pode melhorar sua interação e acurácia, construindo novos fluxos de conversação ou refinando os existentes.

[title] Usuários
[path] /

Neste menu podem ser gerenciadas as pessoas que terão acesso à plataforma de administração do Helper.

1. Após acessar a plataforma, acesse o menu Usuários;
2. É possível visualizar os usuários já cadastrados, editá-los ou excluí-los;
3. Para adicionar clique o botão Novo no canto superior direito da tela;
4. Estarão disponíveis os seguintes campos:

| Usuário                  | Identificador desta pessoa na plataforma de administração do assistente virtual.                          |
| ------------------------ | --------------------------------------------------------------------------------------------------------- |
| E-mail                   | Todas as comunicações da plataforma com esta pessoa serão enviadas a este e-mail.                         |
| Nome                     | Primeiro nome da pessoa que está sendo cadastrada.                                                        |
| Último nome              | Último nome da pessoa que está sendo cadastrada, a fim de evitar homônimos (nomes idênticos).             |
| Senha e confirme a senha | Senha inicial ofertada à pessoa. Após o acesso ela poderá realizar a alteração para a senha que preferir. |
| Ativo                    | Informação se esta pessoa está ativa ou não na plataforma de administração do assistente.                 |


[title] Integrações
[path] /

As integrações com a assistente virtual Anuva dizem respeito aos canais em que o administrador irá disponibilizar a assistente. Essa funcionalidade permitirá a inserção dos links das plataformas desejadas para haver a integração da assistente virtual com o sistema selecionado.

Veremos adiante que o chat pode ser integrado nativamente ao CITSmart, além do Facebook ou sistema próprio do usuário através de API Rest.

## Procedimento

1. Após acessar a plataforma, acesse o menu “Integrações”;
2. Serão apresentadas as seguintes opções de integração: Facebook Messenger, CITSmart e API Rest;
3. Selecione qual opção você deseja integrar.

### CITSmart

A Anuva já se integra nativamente ao CITSmart, então é muito fácil adicioná-la ao seu ambiente.

Para realizar a integração, é necessário que você configure os parâmetros necessários no seu próprio ambiente de produção. Para isso, acesse o sistema e no menu de processos, selecione Parametrização > Parâmetros CITSmart.

Localize e preencha os seguintes parâmetros:

| **Parâmetro**                          | **Valor**                                                                        |
| -------------------------------------- | -------------------------------------------------------------------------------- |
| 402 Anuva Assistant - External URL     | http\://\[nome-servidor].Anuvaassistant.com                                      |
| 441 Anuva Assistant - Conversation API | http\://\[nome-servidor]\[sigla-idioma].Anuvaassistant.com/webhooks/rest/webhook |
| 442 Anuva Assistant - Parameters API   | http\://\[nome-servidor]\[sigla-idioma].Anuvaassistant.com/conversations/        |

**Importante:** Os valores a serem preenchidos nos parâmetros acima dependerão do valor apresentado na ferramenta Anuva. Para isso, acesse a sua assistente virtual e selecione “Integrações”. Para integrar com a plataforma, selecione “CITSmart” e serão apresentados os valores para copiar e colar no valor na própria plataforma CITSmart. Esses parâmetros não podem ser alterados pelo cliente.

**Facebook Messenger**

Também é possível de integrar a assistente virtual Anuva ao chat do Facebook Messenger. Nesse caso as instruções são fornecidas pelo próprio Facebook e fornecemos as informações necessárias para realizar a integração:

- Callback URL
- Verify Token
- Secret
- Page Access Token

**API Rest**

Nessa funcionalidade o cliente pode customizar a assistente virtual para outro canal. Por exemplo, se o cliente já possuir um site institucional e deseja incluir a assistente virtual para o seu chat. Para isso, basta selecionar a opção de comunicação API Rest.

O API Rest é o protocolo de comunicação da assistente virtual. Nela são apresentadas as seguintes informações para realizar a integração com sucesso:

- Endpoint
- Método
- Media Type

E os formatos necessários para integração:

- Formato de envio de mensagem ao bot:

`{
`
`"sender": "joao",
`
`"message": "conte-me algumas coisas sobre você"
`
`}`

- Formato de retorno da mensagem do bot em texto:

`{
`
`"recipient_id": "joao",
`
`"text": "Eu posso ajudá-lo a trabalhar de maneira mais inteligente, em vez de
`
`mais"
`
`}`

- Formato de retorno da mensagem do bot em botão:

`{
`
`"recipient_id": "joao",
`
`"text": "Você poderia avaliar o meu atendimento?",
`
`"buttons": [
`
`{
`
`"title": "Sim",
`
`"payload": "sim"
`
`},
`
`{
`
`"title": "Não",
`
`"payload": "não"
`
`}
`
`]
`
`}`

- Formato de retorno da mensagem do bot em imagem:

`{
`
`"image":
`
`"https://anuvaassistantimages.s3.amazonaws.com/dev/fe711b50-d974-11e9-9622-94de80f33bee.png",
`
`"recipient_id": "joao"
`
`}`

Ou

`{
`
`"attachment":
`
`"https://anuvaassistantimages.s3.amazonaws.com/dev/fe711b50-d974-11e9-9622-94de80f33bee.png",
`
`"recipient_id": "joao"
`
`}`


[title] API de terceiros
[path] /

A nossa assistente virtual Anuva disponibiliza uma área para integrar API externas ao chatbot. Com isso você poderá utilizar API de terceiros com todos os recursos da Anuva. Essa integração é realizada através de requisição REST e necessita de alguns passos para ser configurada.

## Procedimento

1. Após acessar a plataforma, acesse o menu “APIs de terceiros”;
2. A tela apresentará as APIs já cadastrados anteriormente, caso haja algum, com as opções de Edição e Exclusão;
3. Caso queira procurar por uma API específica, utilize o campo de busca e clique o botão “Buscar”;
4. Para registrar uma nova API, clique em “Novo”. Aparecerão os seguintes campos para serem preenchidos:

| **Campo**   | **Definição**                                                                                                                     |
| ----------- | --------------------------------------------------------------------------------------------------------------------------------- |
| Nome        | Definir o nome característico da API que está sendo registrada                                                                    |
| Dependência | Se necessário, identificar se essa API que está sendo criado necessita anteriormente da execução de uma outra API                 |
| Método      | Selecionar qual método http será utilizado pela API: POST, GET, PUT, DELETE ou PATCH                                              |
| URL         | Definir a URL do novo API. Caso queira incluir na URL um contexto já cadastrado na assistente virtual, colocar o valor entre \{}. |

Uma vez preenchidos os campos de identificação, vamos preencher os atributos necessários para dar continuidade as requisições REST: cabeçalho, corpo, respostas e configurações.

### Cabeçalhos

Essa função permite adicionar valores necessários para o cabeçalho da requisição REST.

1. Clique o botão “+” para adicionar o cabeçalho com as informações para:

- Chave;
- Valor.

2\.  Clicar em Salvar.

### Corpo

No corpo é possível montar o conteúdo que será enviado no corpo da requisição.

1. Clicar o botão “+” para adicionar o corpo com as informações de:

- Formato do corpo: JSON;
- Nome;
- Tipo: texto, número, booleano, lista, objeto, contexto, histórico do chat, última mensagem do chat, identificação do usuário, valor indefinido e valor vazio;
- Valor: o valor irá depender do tipo selecionado.

4\.  Clique em Salvar.

### Respostas

Em respostas vamos configurar o que a gente espera dessa API.

1. Clicar o botão “+” para adicionar as informações com para:

- Formato da resposta: pode ser em JSON ou Text;
- Nome;
- Tipo: texto, número, booleano, lista, objeto ou contexto;
- Identificação.

2\.  Clique em Salvar.

### Configurações

Aqui iremos definir as configurações da requisição que irão influenciar no entendimento da assistente.

1. Selecione o código desejado para definir os campos:

- Status htpp de sucess;
- Status htpp de não autorizado;
- Status htpp de não encontrado.

:::BlockQuote
*As opções apresentadas para esses campos são pré-definidas pelo sistema.*
:::

2\.  Depois, definir as mensagens que aparecerão na tela do chatbot para os seguintes casos:

- Mensagem do chatbot para conteúdo não encontrado;
- Mensagem do chatbot para falha na requisição;

3\.  Definir se a API sendo criada é uma API de autenticação.

4\.   Clique em Salvar.


[title] Criar e editar Intents
[path] /

Intents, na linguagem de chatbot, significa os **interesses ou intenções** do usuário ao interagir com a inteligência artificial. Isso significa, saber exatamente o que quer dizer a frase ou mensagem desse usuário. As intents são importantes pois determinam a capacidade da assistente virtual em analisar a intenção de quem o está usando, resultando no entendimento e sucesso da conversa.

Dentro da ferramenta Anuva, as intents são um conjunto de frases ou termos vinculados a uma identificação, ou seja, iremos agrupar em um bloco, as frases e interações que seriam utilizadas pelo usuário para um determinado tema e identificação.

Por exemplo, para o assunto “Saudações”, cadastre frases que são relacionadas a intenção de cumprimentos, algo como “Bom dia”, “Olá”, “Oi”, dentre outras.

Os temas e identificações irão depender da necessidade de sua empresa, então tudo aquilo que for cadastrado para treinamento e entendimento da assistente virtual serão relacionados à realidade dos serviços oferecidos na sua organização.

## Criar Intent

1. Após acessar a plataforma, acesse o menu “Intents”;
2. Primeiramente, serão apresentadas na tela as seguintes opções:

| **Função** | **Descrição**                                                                                                              |
| ---------- | -------------------------------------------------------------------------------------------------------------------------- |
| Novo       | Para criar uma nova intente.                                                                                               |
| Buscar     | Para pesquisar uma intent já cadastrada.                                                                                   |
| Lista      | Lista com todas as intents existentes na sua assistente. Você tem duas opções para cada intent da lista: Editar e Excluir. |

3\.  Para ver ou editar uma intent já cadastrada, busque por uma específica ou procure na lista apresentada;

4\.  Para criar uma nova intent, clique em “Novo” e preencha as informações conforme necessidade:

| **Função** | **Descrição**                                                                                                                                                                                                                                                                                                                                                                                           |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Nome       | Para identificar o teor geral do assunto do usuário. Será o nome para o bloco de frases que o usuário poderá usar para determinado contexto. Por exemplo, “saudações”, “Usuário solicita envio da conversa por email”, “Agradecimento”, entre outros.                                                                                                                                                   |
| Tema       | Dependendo do tipo de atendimento e serviços que a assistente irá desempenhar, os temas irão classificar o tipo de conversação para o intent que será criado. Por exemplo, “small talk” para saudações; “padrões de atendimento” para quando o usuário solicitar conversa por email etc.                                                                                                                |
| Frases     | Cadastrar as frases que podem ser utilizadas pelo usuário para o assunto da intent que está sendo criada. É importante cadastrar o máximo de frases relacionadas ao assunto para que a acurácia da assistente seja cada vez maior. Por exemplo, para um conjunto de intent sobre “Agradecimento”, poderíamos cadastrar frases do tipo “Obrigada”, ”Muito obrigado”, “Agradecido”, dentre muitos outros. |

5\. Após inserir a frase desejada, clique em “Adicionar”;

6\.  Após adicionar as frases para o intent, serão apresentadas as seguintes
opções:

| **Função**        | **Descrição**                                                                                                                                                                                                                                                                                                                                                      |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Vincular contexto | A opção de vincular contexto é utilizada para cadastrar sinônimos a uma determinada frase. Por exemplo, na saudação “Bom dia”, podemos vincular um contexto de saudações, onde para “Bom dia” teremos os sinônimos “Boa tarde” e “Boa noite”. Ou seja, podemos aprimorar ainda mais os acertos da assistente virtual ao vincularmos mais contextos para uma frase. |
| Remover           | Ao clicar em vincular contexto, aparecerão as opções “Contexto” e “para o texto”, onde iremos procurar pelo contexto correspondente já cadastrado na ferramenta e depois colocaremos as frases sinônimas da que será utilizada nessa intent.                                                                                                                       |
| Remover           | Para remover a frase cadastrada.                                                                                                                                                                                                                                                                                                                                   |

7\.  Para salvar a nova intent, clique em “Salvar” ou se quiser voltar para a tela inicial de Intents, clique em “Voltar”.


[title] Configurações
[path] /

## Parâmetros

### O que é acurácia?

Podemos entendê-la como o nível de entendimento do que o usuário está dizendo ao assistente, se o texto digitado pelo usuário precisa estar exatamente igual ao construído ou se a partir de certo ponto de compreensão do texto o assistente já pode seguir o fluxo de conversação planejado.

O assistente somente dará continuidade no diálogo se acurácia de entendimento dele em relação a frase digitada pelo usuário for maior que o valor cadastrado nesta página. Caso contrário o assistente virtual iniciará o fluxo cadastrado de fallback.

**Exemplo:** Supondo que no diálogo foi construída a saudação “Bom dia!” e a acurácia está marcada para 100%. Se o usuário escrever “bom dia?” o seu assistente não vai compreender o que foi dito e apresentará mensagem de fallback. Somente será dada continuidade no fluxo de conversa se o usuário digitar “Bom dia!”, exatamente como foi construído.

Quanto melhor seus exemplos de diálogos e cadastros de intenções, melhor será seu assistente. Então é importante definir qual o cenário que o assistente irá atuar antes de definir o nível de acurácia. Veja abaixo o motivo:

**Níveis de acurácia:**

| **Nível de acurácia** | **Riscos**                                                                                                                                                                                                  |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Entre 0% e 30%        | Em geral consideramos baixo, e portanto, há pouca certeza de que os diálogos irão corresponder ao planejado. Quando se tratarem de validações de identidade e login o risco é elevado para sua organização. |
| Entre 30% e 70%       | São considerados médios, apresenta risco moderado. Dependendo do nível de informações que irão validar, podem valer a pena.                                                                                 |
| Entre 70% e 100%      | Representa baixo risco e chances maiores de precisão das informações.                                                                                                                                       |

### Notificações

Área para gerenciamento de quais administradores do sistema precisam receber as notificações de atualização do assistente.

São enviadas três tipos de notificações:

| **Função**            | **Descrição**                                                                                                                                                                                                                                                       |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Agendamento iniciado  | E-mail enviado para notificar que o treinamento agendado foi iniciado.                                                                                                                                                                                              |
| Treinamento concluído | Enviado quando o treinamento foi concluído com sucesso e o assistente está disponível com os novos aprendizados.                                                                                                                                                    |
| Falha no processo     | Notifica o administrador da plataforma que a atualização não pôde ser realizada, o motivo e a solução.Exemplo: Treinamento não realizado. Você precisa cadastrar mais três frases na intente, pois o mínimo de frases para atualização acontecer são quatro frases. |

**Procedimento**

1. No campo “Digite para adicionar um e-mail” digite o e-mail que receberá as notificações;
2. Clique o botão Adicionar;
3. Depois de adicionado, é possível excluir o e-mail.

### Migrações

Esta área permite que utilize o case ou cenário construído no IBM Watson no Anuva, sem a necessidade de reconstrução dos fluxos de conversação nesta plataforma.

**Procedimento**

1. Clique na opção IBM Watson;
2. Na aba Configurações preencha os campos Chave da API, URL, Usuário, Senha e Versão com estes dados fornecidos na plataforma IBM Watson;
3. Serão apresentados na aba Importações os Workspaces disponíveis para importação da plataforma IBM Watson;
4. Selecione o Workspace que seja importar;
5. Clique o botão Salvar.
6. A aba Histórico de Importações apresentará o nome do workspace importado, a data de importação e status da importação.

!!! warning "Atenção"

```Text
Pode ocorrer do tipo de frase ou opção não ser compatível com o Anuva e por este motivo a importação, somente deste item, não ocorrerá. Neste caso será    necessária a conferência e criação manual do trecho não importado.
```

### Importação/Exportação

Nesta área é possível importar diálogos por intent e exportar os diálogos existentes no seu assistente também.

Continua sendo necessário agendar um treinamento após a importação dos diálogos para que o Anuva aprenda esses diálogos importados também.

**Procedimento de exportação**

1. Clique o botão exportar;
2. O sistema irá iniciar o processo de download do arquivo, que será entregue em formato .xlsx.

**Procedimento de importação**

1. Em uma planilha de formato .xlsx, crie três colunas nesta ordem: Intent, User Says, Text Response;

| **Função**    | **Descrição**                                                                                                                                                                                                                                         |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Intent        | Nome da intenção cadastrada no Anuva.Exemplo: 1.0 Saudações ao Usuário Logado                                                                                                                                                                         |
| User says     | O que a pessoa que está sendo atendida pelo assistente pode dizer. Sendo cada hipótese em uma linha diferente.Exemplo: Olá, boa noite                                                                                                                 |
| Text Response | O que o assistente deve responder a esta fala.Exemplo: Olá, eu sou o Anuva, seu novo assistente virtual. Estou aqui para simplificar o seu processo de atendimento e ajudá-lo em suas necessidades. Basta digitar o que precisa que eu vou te ajudar! |

!!! exemple "Exemplo"

```Text
1.  Salve a planilha;

2.  De volta a página de Importação/Exportação clique o botão Importar;

3.  Clique o botão Escolher arquivo;

4.  Localize a planilha salva;

5.  Clique o botão Importar.
```

!!! info "Observação"

```Text
Somente poderão ser importadas respostas em formato texto. As demais opções (botão, imagem e carrossel) ainda não estão disponíveis nesta funcionalidade;

Caso queira refinar diálogos existentes, exporte, ajuste, e importe  novamente. A importação substitui o conteúdo, então, caso você retire alguma frase existente na planilha que foi exportada, quando for importada o sistema irá apagar a(s) frase(s) retiradas da planilha.
```

!!! success "Dica"

```Text
Utilize o procedimento de atendimento (FAQ ou SAC) que sua organização já possui (caso possua) em formato de perguntas e respostas para montar essa planilha. Aproveite o conhecimento que já existe no seu ambiente para aprimorar seu assistente virtual.
```

[title] Diálogos
[path] /

Anuva aprende a partir dos **diálogos** adicionados à sua base de conhecimento. Esses diálogos são estruturados por **interesses ou intenções** (possíveis frases utilizadas na interação do usuário) e por **habilidades** (possíveis respostas da assistente virtual às interações do usuário).

Como a Anuva funciona de forma reativa às interações do usuário, para formar diálogos precisamos agrupar interesses e habilidades em pares. Contextos serão utilizados apenas quando, durante o diálogo, for necessário armazenar alguma informação citada pelo usuário para utilizar em um outro ponto da conversa. 

Cabe ao administrador da assistente virtual fornecer esses dados ao sistema, estruturando os possíveis diálogos e para que seja realizado o treinamento do conjunto. O treinamento deve ser agendado pela interface da Anuva, e ao final do treinamento, a sua assistente será atualizada automaticamente. 

## Adicionar Diálogo

### Procedimento

1. Após acessar a plataforma, acesse o menu “Diálogos”.
2. Primeiramente, serão apresentadas na tela as seguintes opções:

| **Campo** | **Descrição**                           |
| --------- | --------------------------------------- |
| Novo      | Para criar um Diálogo                   |
| -         | -                                       |
| Buscar    | Para pesquisar um Diálogo já cadastrado |

3\.  Para ver ou editar um “Diálogo” já cadastrado, busque por uma específica ou procure na lista apresentada;

4\.  Para criar um diálogo, clique em “Novo” e preencha as informações conforme necessidade:

| **Campo**                  | **Descrição**                                                                                                                                                       |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Nome                       | Para identificar o teor geral do assunto do usuário. Será o nome para o diálogo que o administrador poderá usar para determinado contexto.                          |
| -                          | -                                                                                                                                                                   |
| Tema                       | Dependendo do tipo de atendimento e serviços que o chatbot irá desempenhar, os temas irão classificar o tipo de conversação.                                        |
| Adicionar Diálogo          | A opção de adicionar diálogo é utilizada para adicionar um novo diálogo a esse tema.                                                                                |
| Vincular Intent            | A opção de vincular Intent é utilizada para adicionar uma intent ao diálogo, podendo assim especificá-lo e vinculá-lo a um contexto específico.                     |
| Vincular diálogo principal | Se já existe um diálogo previamente criado e você deseja reaproveitar o comportamento dele para o diálogo em criação, basta clicar em “Vincular diálogo principal”. |

5\.  Para salvar um novo diálogo, clique em “Salvar” ou se quiser voltar para a tela inicial de diálogos, clique em “Voltar”.

## Vincular diálogo principal

Se já existe um diálogo previamente criado e você deseja reaproveitar o comportamento dele para o diálogo em criação, basta clicar em “Vincular diálogo principal”.

Aparecerá uma tela com as seguintes opções:

| **Campo** | **Descrição**                                                        |
| --------- | -------------------------------------------------------------------- |
| Diálogo   | Para pesquisar o diálogo já criado na ferramenta para ser vinculado. |
| -         | -                                                                    |
| Adicionar | Para adicionar o diálogo selecionado.                                |
| Fechar    | Para retornar a página anterior.                                     |

Ao vincular esse diálogo, o chatbot levará em consideração o fluxo das informações que você já estava cadastrando, além do comportamento desse novo diálogo que foi vinculado.

Uma vez feito o vínculo, você pode editar ou excluir esse diálogo a qualquer momento na lista apresentada dentro da opção “Diálogos”.


[title] O que é Anuva?
[path] /

É o primeiro recurso disponibilizado pela CITSmart de inteligência artificial. A Anuva é uma assistente virtual, um chatbot que se comunica e interage com pessoas através de mensagens de texto automatizadas.

Anuva usa inteligência artificial para realizar diálogos com usuários de forma cada vez mais aperfeiçoada em diferentes plataformas, além de interagir com usuários e capaz de integrar-se com outros sistemas para obter respostas a questionamentos, recuperando dados através de APIs.

## Funcionalidades da Anuva

Ele atende aos 5 conceitos principais das plataformas de construção de assistentes virtuais:

- **Build** : Construção de fluxos de conversação (diálogos) da assistente com possíveis interações humanas, para que ela esteja preparada para reagir e responder de forma fluida e correta;
- **Train**: Treinamento da assistente para que ela passe a considerar todos os exemplos de diálogos construídos e suas interações. A Anuva utiliza inteligência artificial para compreender o que o usuário quis dizer ou solicitar, então no momento de construção dos diálogos não é necessário escrever exatamente o que um usuário dirá a ele;
- **Code**: Possibilidade de conexão com API externas, que permitem acesso de dados necessários para as respostas;
- **Connect**: Possibilidade de integração com diversos canais de comunicação (plataformas prontas ou canais customizados). A Anuva fornece API facilmente conectável e uma conversão dentro do CITSmart para que as escolhas (sejam em botões ou não) cheguem para a Anuva como texto dando assim a tratativa correta no fluxo de diálogo. Disponibilizamos hoje integração com o smartchat da plataforma CITSmart e com o Facebook, os demais canais mais utilizados, como Twitter e Whatsapp podem ser integrados através do CITSmart;
- **Monitor**: Monitoramento que disponibiliza ao responsável pela administração do Anuva os dados para análise de como o assistente tem se comportado, perguntas mais frequentes feitas a ele, respostas mais utilizadas entre outras informações para que as os fluxos existentes possam ser aprimorados ou sejam percebidas as necessidades de construção de novos fluxos e assim, novo treinamento da assistente.

## Acessando a Anuva

Após a liberação do ambiente Anuva, acessar a instância de configuração através do link disponibilizado. (ex: [https://example.anuvaassistent.com](https://example.anuvaassistent.com))

Neste ambiente, é possível adicionar e revisar conhecimentos para a Anuva, agendar treinamentos, acompanhar as interações realizadas pela Anuva e realizar testes de interação para validar se interações estão sendo efetivas.


[title] Treinamentos
[path] /

## O que significa treinar a minha assistente virtual?

É o ato de colocar sua assistente para entender como serão as interações com o usuário considerando os diálogos construídos. Sempre que forem adicionadas novas interações é preciso treinar novamente sua assistente para que ela consiga reagir da maneira esperada em uma conversa.

O único pré-requisito para agendar um treinamento da sua assistente virtual é haver ao menos um diálogo construído.

## Antes de começar

Tenha certeza que todas as configurações de parametrização e infraestrutura foram realizadas corretamente.

## Procedimento

### Agendar treinamento

1. Após acessar a plataforma, acesse o menu Treinamentos;
2. Clique o botão Agendar;
3. Defina qual será o escopo da atualização que deseja, sendo as opções: Diálogos, Completo, Habilidades (Texto – Botão – Imagem) ou Habilidades personalizadas;
4. Informe o dia e horário em que o treinamento deverá ser realizado.

:::BlockQuote
*Observação: Lembre-se de escolher datas e horários que irão ter menos impactos nos atendimentos em andamento, caso haja.*
:::

!!! note "Informação"

```Text
O tempo de duração de cada treinamento vai variar de acordo com o volume de
fluxos de conversação construídos, mas não se preocupe, assim que for
concluído sua assistente está automaticamente pronta para atuar, seja no
teste de conversa dentro da plataforma ou no ambiente de produção.
```

### Solução de problemas



Após iniciado um treinamento, o aplicativo não disponibiliza opção ao usuário para finalizar o processo, mas às vezes pode ser necessário. As instruções a seguir conduzem na realização desta tarefa, que consiste em limpar a fila de tarefa e finalizar a máquina adquirida para este fim.

```Text
1. Acesse o serviço Simple Queue Service no painel de serviços da AWS  
2. Localize a fila denominada citsmart-anuvaassistant-training-<ambiente> e selecione-a. Por exemplo, o nome para o ambiente "homologation" na fila seria citsmart-anuvaassistant-training-homologation.  
3. Clique em Actions e selecione "Purge"  
4. Escreva o termo solicitado e clique no botão "Purge"  
5. Após este procedimento, a fila deverá estar limpa.  
```

Para finalizar a instância adquirida, siga as instruções a seguir:

```Text
1. Acessar o serviço EC2, no painel de serviços da AWS  
2. Clicar no link para Instâncias (rodando)  
3. Pesquisar por uma instância que possua o termo “spot”  
4. Selecionar a instância desejada  
5. Clicar em Actions e solicitar para parar a instância, confirmando a escolha no botão "Stop"  
6. Clicar em Actions e solicitar para finalizar a instância, confirmando a escolha no botão "Terminate"  
7. Após esse procedimento, uma mensagem deverá aparecer indicando a instância removida.  
```



Ao tentar iniciar um treinamento agendado, pode ocorrer um erro e o treinamento não inciar. Uma das causas desta ocorrência está relacionado ao schedule do python que sofre uma quebra, deixando de colocar o treinamento na fila.

```Text
1. Para confirmar se o erro está relacionado ao schedule do python, observe a fila do Aws, no Simple Queue Service, denominada "citsmart-anuvaassistant-training-homologation"  
2. Em situações normais, a fila em questão deveria mostrar suas mensagens zeradas.  
3. Caso haja erro, a fila apresentará 1 job agendado na coluna de mensagens.  
4. Nesse caso, é necessário parar e reiniciar a instância EC2 "anuvamultitenancyapihom_app".  
5. Após reiniciar a instância, remova o treinamento que estava agendado e realize novo agendamento.
```



Este problema ocorre quando a instância anuvamultitenancyapihom\_app tem o seu IP alterado, por motivo qualquer, e este passa a não constar na regras de autorização de acesso do serviço Elasticsearch. Neste caso, uma mensagem indicando a falha na apresentação dos rankings aparece em diversos pontos da aplicação.

Para resolver o problema, o IP da instância anuvamultitenancyapihom\_app deve ser acrescentado na lista de autorizados, nas políticas de acesso ao serviço Elasticsearch. Para isto, é necessário obter o IP atual da EC2 anuvamultitenancyapihom\_app, acessar o painel do serviço Elasticsearch e incluir o IP na lista de autorizados. Para obter o IP, siga o procedimento a seguir:

```Text
1. Acesse o painel administrativo de instâncias EC2  
2. Filtre as instâncias que estão rodando/ativas  
3. Selecione a instância em questão e copie o número do seu IP
```

Para acessar o painel do Elasticsearch e incluir o IP na lista:

```Text
1. Selecione o menu Analytics > Elasticsearch Service
2. No dashboard, clique em My Domains e selecione o serviço relacionado
3. Após selecionar o serviço, clique no botão Actions > Modify Access Policy
4. Nesta página, inclua o número do IP copiado na relação de autorizados e clique no botão Submit para aplicar a alteração.
```

### Testes Automatizados

Os testes de softwares estão inseridos no Gerenciamento de Ciclo de Vida de Aplicativos (mais conhecido como ALM). É uma etapa primordial para garantir a qualidade do produto entregue para o cliente, ou mesmo para ser utilizado pela própria equipe de desenvolvimento para assegurar-se de sua assertividade.

Nós automatizamos para evitar trabalho manual repetido, obter um feedback mais rápido, economizar tempo executando testes repetidamente, e assegurar que estamos sempre executando testes de forma consistente com as mesmas precondições e expectativas.

De modo geral, os motivos para a abordagem da existência dos testes são:

- Verificar se o programa está dentro das expectativas do cliente;
- Verificar quaisquer bugs antes dos seus clientes verem;
- Detectar problemas no design;
- Ter certeza de que o sistema é estável;
- Garantir que o trabalho desenvolvido pela equipe é de qualidade;

Para a automatização de testes do projeto em questão, está sendo utilizado a ferramenta Cypress. Um dos principais diferenciais do Cypress é que enquanto a maioria das ferramentas de testes operam fora do navegador, executando comandos remotos na rede, o Cypress é exatamente o oposto, ele é executado no mesmo loop de execução do aplicativo que está sendo testado. Isso permite uma interatividade muito grande.

Os procedimentos a seguir apresentam instruções sobre a instalação e configurações básicas para iniciar e interagir com este projeto de testes, assim como documentar os critérios e padrões adotados para a boa prática na sua condução e implementações seguintes.



Testa os requisitos funcionais da aplicação. Resumidamente verificar se a aplicação está apta a realizar as funções para a qual foi desenvolvida para fazer, podendo abranger as funcionalidades em todo o seu escopo, tanto BackEnd quanto FrontEnd.



Preliminarmente, você já deve possuir o Node.js instalado e, a nível de sugestão a IDE VsCode. Tendo estes pré-requisitos, siga o procedimento a seguir:

-
-
-

Se necessário, instruções completas podem ser obtidas junto à documentação oficial.

!!! note "Nota"

```Text
       Se desejar instalar uma versão específica, como 4.6.2 por exemplo, faça da seguinte forma: <i>$ npm install cypress@4.6.2</i>
       
```



Como sugerido anteriormente, estaremos utilizando o VsCode como IDE para o desenvolvimento de nossos testes, portanto o mesmo já deve estar previamente instalado. Vamos acrescentar ao arquivo package.json o comando que utilizamos para executar o projeto. Isto irá agilizar o procedimento. Edite o arquivo package.json, e no tópico script, acrescente o comando, conforme exemplo:





Tendo sido incluído o comando, conforme instrução anterior, o projeto pode ser executado via linha de comando:



ou através do VsCode, pelo caminho Outline > NPM Scripts > package.json > cypress\:open > botão "play"



A seguinte estrutura de arquivos é proposta para se manter um padrão organizacional do projeto. Porém, não existem restrições técnicas para outras abordagens, sendo as boas práticas a seguir mera convenção para o projeto em questão:

-
  - O uso de fixtures é uma boa prática para agilizar o desenvolvimento e manutenção do projeto, pois agrega em única área os dados variáveis utilizados pelo projeto.
  - Por questão organizacional, deve se ter um arquivo fixture para cada arquivo de teste.
  - Devem ser evitados blocos muito extensos. Quando o volume for grande, é sugerido a sua divisão em tópicos.
  - Os commands não devem lidar com os dados diretamente. Os dados devem ser manipulados nas intents.
-
  - Estes arquivos devem se restringir à lógica dos testes e manipulação dos dados, deixando a cargo dos commands a execução dos procedimentos com as devidas interações com telas e api ‘ s.&#x20;
  - Por questão organizacional, deve se ter um arquivo command para cada arquivo de teste.&#x20;
  - Os arquivos de testes não devem lidar com os componentes de tela diretamente, ficando isto a cargo dos arquivos em commands. Assim sendo, não devem importar arquivos locators.&#x20;
  - Os arquivos de testes importam os arquivos fixtures, para a manipulação de dados e passagem destes para os commands.&#x20;
-
-
  - **commands:** Estes arquivos são utilizados pelos testes, localizados no diretório integration. Devem conter os códigos dos comandos utilizados pelos testes. Além dos arquivos commands individuais para cada arquivo de testes, temos também um de uso Global. Algumas boas práticas são: &#x20;
  - **llocators:** Diretório destinado a conter os arquivos que registram os endereços de acesso aos widgets de tela, URLs e demais endereços. Como determinado nas boas práticas deste projeto, os arquivos locators devem ser importados e utilizados pelos commands. Além dos arquivos locators individuais para cada arquivo de testes, temos também um de uso Global. Algumas boas práticas são:
-
-
-
-
-
-



Foi adotado o seguinte padrão para a criação e denominação de arquivos:



Exemplos:

```Text
    - Arquivos do fixtures: datasContext.js / datasTheme.js 
    - Arquivos de commands: commandsContext.js / commandsLogin.js  
    - Arquivos de locators: locatorsLogin.js / locatorsTheme.js    
```

!!! note "Nota"

```Text
    Observar que o plural deve ser utilizado apenas no conteúdo, pois o conteúdo habitualmente se refere a mais de um item. Observe também que a identificação do módulo se inicia com letra maiúscula. 
```

Nesta esta estrutura, temos uma exceção quanto aos arquivos de testes propriamente ditos, que estão contidos no diretório integration. Estes arquivos devem seguir o seguinte padrão:



Exemplos:

```Text
    - context.spec.js  
    - login.spec.js  
    - theme.spec.js 
```


[title] Contexto
[path] /

Os diálogos estão imersos em contextos. Palavras iguais podem ter significados distintos a depender do contexto no qual estão inseridas.

Para aumentar a acurácia em situações de homônimos e evitar a repetição de frases por conta de sinônimos, é possível cadastrar uma base de contexto para que a assistente virtual faça a distinção de homônimos e a correlação entre sinônimos para deixar a conversação mais fluida. 

## Novo Contexto

1. Após acessar a plataforma, acesse o menu “Contextos”. Nele é possível editar, excluir e criar um contexto;
2. Clique em “Novo” para cadastrar um contexto;
3. Preencha os campos conforme necessidade:

| **Campo** | **Descrição**                                                           |
| --------- | ----------------------------------------------------------------------- |
| Nome      | Nome para identificar o contexto                                        |
| Tipo      | Selecione as opções entre Text, Boolean, Categorical e Float            |
| Descrição | Utilize esse campo para descrever um resumo para identificar o contexto |

4\.  Ao selecionar um dos tipos, clique o botão “Adicionar”, será exibida a opção de cadastro relacionada ao tipo:

- **Text**: adicione um “Valor” e um “Sinônimo”;
- **Boolean**: serão adicionadas opções de Sim e Não;
- **Categorical**: adicione um “Valor”, para adicionar mais itens à lista clique o botão “Adicionar” novamente;
- **Float**: adicione um “Valor Mínimo” e um “Valor Máximo”.

5\.  Clique em “Salvar” para adicionar o novo contexto ou voltar para cancelar a criação.

!!! note "Nota"

```Text
É necessário vincular os contextos às frases do Interesse/Intent dentro do Diálogo, para que a informação seja processada pela sua assistente virtual. 
```

[title] Temas
[path] /

Os temas estão ligados diretamente com os diálogos, intents e habilidades. Os temas servem para identificar qual o assunto a assistente virtual deve tratar, ou seja, quando um diálogo for iniciado ele vai ser identificado pelo tema, assim a Anuva vai utilizar suas habilidades cadastradas para poder atender o pedido ou o objetivo do usuário.

## Novo Tema

1. Após acessar a plataforma, acesse o menu “Temas”. Nele será possível editar, excluir e criar um tema;
2. Clique em “Novo” para cadastrar um contexto;
3. Preencha os campos conforme necessidade:

| **Campo** | **Descrição**                         |
| --------- | ------------------------------------- |
| Nome      | Identifique o tema utilizando um nome |
| Descrição | Descreva o tema criado                |

4\.  Clique em “Salvar”.


[space] Aura (/aura)

[title] Introdução
[path] Untitled/Início/

## **Por que utilizar o AURA?**

A plataforma **AURA&#x20;**&#x70;ossibilita a criação de chatbots com capacidades variadas, que podem ser personalizados de acordo com o perfil do negócio ao qual irá atender.&#x20;

A facilidade disponibiliza assistentes virtuais como um canal de atendimento direto para o recebimento de solicitações ou para a realização de serviços pré-determinados automatizando o fluxo de negócios.

Os ganhos são a redução do tempo de atendimento, menor envolvimento humano, redução de custos, garantia de investimentos e maior celeridade para os processos.&#x20;

## **Personalização**

Os bots criados  podem ser configurados em sua aparência e estilo, tipos de saudação e outras características visuais, permitindo completa identificação e aderência da plataforma ao cliente.

O **AURA&#x20;**&#x74;ambém pode ser utilizado para diversas finalidades de atendimento, seja ativo ou reativo, segundo a necessidade da organização. A elucidação de dúvidas, o registro de solicitações e a automatização de processos entrega valor ao negócio de maneira fácil e eficiente.

Os mecanismos de linguagem de atendimento e os canais de atendimento também são totalmente personalizáveis, ou seja, você terá a liberdade para determinar através de quais meios o assistente poderá ser acessado, como aplicativos de mensagens instantâneas (Whatsapp, Telegram, Microsoft Teams, Facebook Message), acesso web, através de portal, ou por meio de ferramentas de gestão.&#x20;

## **Funcionalidades**

O sistema oferece diversas funcionalidades voltadas para a otimização da interação com o chatbot e a análise de dados. Entre as principais funcionalidades estão a capacidade de anexar arquivos durante a conversa, reiniciar a sessão com o chatbot, expandir a interface para tela cheia, ou minimizar o chat.&#x20;

Além disso, o usuário pode enviar transcrições por e-mail, imprimir o histórico ou exportá-lo em PDF. Também é possível ditar textos ou ouvir a sua leitura no Chrome, com opções de ajuste para a conversão de palavras e símbolos em áudio. A plataforma suporta a exibição de mensagens do pipeline no chat de atendimento humano, a conversão de áudio para texto (STT), e a reprodução de texto em áudio (TTS).&#x20;

A análise de sentimentos, quando configurada, ajuda a identificar o tom da conversa, enquanto notificações indicam quando alguém está digitando. O tempo de sessão do chatbot e o tempo de corte da sessão podem ser configurados para gerenciar a duração das interações.

No desenho do fluxo, é possível determinar o ponto onde o transbordo para um atendimento humano é adequado, com possibilidade de herança do histórico da conversa permitindo atendimento mais eficaz e personalizado.

## **Controle de desempenho e gestão**

No aspecto de análise, o sistema oferece um dashboard completo que apresenta dados em tempo real, como o número de conversas não atendidas, a assertividade das respostas do robô, e o total de mensagens. O dashboard também permite a análise de intenções e entidades, identificação do canal de comunicação, índice de confiança, e a visualização detalhada de cada mensagem. Além disso, o painel possibilita o agrupamento e ordenação dos dados, a exportação das mensagens, e a visualização de estatísticas diárias, como o total de mensagens e conversas por dia. O usuário pode ainda selecionar o período desejado para a pesquisa de dados.

O sistema oferece uma ferramenta para criar relatórios personalizados, com opções de classificação detalhada, gráficos e tabelas para análise. Além disso, permite gerenciar arquivos diretamente na plataforma, incluindo a criação, renomeação, exclusão e download de arquivos e pastas, além de recarregar a página para refletir as mudanças realizadas. Na área de uso e faturas, é possível gerenciar itens de cobrança, registrar consumo e gerar faturas, além de acompanhar o uso por meio de gráficos.&#x20;

## **Demais funcionalidades**

Outras funcionalidades incluem auditoria das atividades, atualização de perfil e senha, acesso a manuais de usuário, e configurações de idioma. A plataforma também permite automação de abertura de chamados e comunicação segura entre diferentes ambientes via VPN.




[title] Engine local
[path] Untitled/Customizações Avançadas/

## Rodando a Engine localmente pela CLI

### Obtendo o projeto

```bash
git clone http://gitlab.centralit.io/aura/blocks.git
```

Dentro dos repositórios do **blocks**  temos uma pasta chamada **cli**. Acesse a mesma
e compile o executável aura, caso ainda não tenha feito.

```bash
# dentro da raiz do projeto
cd cli
cargo install --path .
```

Aviso:

A partir desse momento o utilitário aura fica disponível para ser utilizado a partir de qualquer pasta



### Configurando as variáveis de ambiente para a cli

É necessário exportar 3 váriaveis de ambiente para o funcionamento do comando `aura`.
As variáveis devem apontar para o local onde os respectivos recursos estão sendo executados.

```bash
export ENGINE_HOST=http://localhost:6060/engine
export LOWTALK_HOST=http://localhost:8989/lowtalk
export LOWWIDGET_HOST=http://localhost:4156/lowwidget
```

Aviso:

Por padrão os servidores acima já estão configurados para as portas e pontos de montagem
definidos no exemplo



### Inicializar servidores

Aviso:

Esse tutorial assume que o suporte as linguagens de programação utilizadas pelo servidor já estão funcionando.
Garanta que os comandos `cargo`, `go` e `npm` estão funcionando.



Aviso:

Garanta que o banco de dados está em execução e devidamente configurado nos arquivos main.sh dos respectivos projetos GO



```bash
# dentro da raiz do projeto
cd engine
sh scripts/main.sh

# dentro da raiz do projeto, em um novo terminal
cd lowtalk
sh scripts/main.sh

# dentro da raiz do projeto, em um novo terminal
cd lowwidget
sh scripts/main.sh

# dentro da raiz do projeto, em um novo terminal
cd wanderson
cargo run -- server -d ./workspace_examples

# dentro da raiz do projeto, em um novo terminal
cd lunaris
cargo run -- server -w ./workspace_examples
```

## Resumo do comando aura

Após a instalação podemos ver os comandos disponíveis dentro da **aura**.

### Ajuda

```bash
# Ajuda do comando aura
aura --help
```

### Workspace

```bash
# Ajuda do subcomando workspace
aura workspace --help

# Retorna a lista de workspaces
aura workspace list

# Remove o workspace passado como parametro (coluna name da lista)
aura workspace remove wpname

# Cria um novo workspace a partir do lábel passado como parâmetro
aura workspace new "Label do Workspace"
```

### Plugin

```bash
# Lista os plugins registrados em um workspace
aura list wpname

# Inspeciona as configurações de um plugin registrado
aura inspect wpname plname

# Remove um plugin registrado
aura remove wpname plname

# Registra um plugin
# Workflow: as propriedades podem ser passadas conforme a solicitação do plugin
aura register wpname "label do plugin" "url_do_manifesto" "propriedade0=valor0&propriedaden=valorn"

# Configura talker padrão e a ordem dos eventos
aura conf wpname -d nometalkerpadrao -o primeiroplugin -o segundoplugin
```

### Fila

```bash
# Lista as filas
aura attendant list

# Remove uma fila
aura attendant remove flname

# Cria uma nova fila
aura attendant new "Label da Fila" -a "email_do_agente1" -a "email_do_agenten" -m "mensagem de captura" -j "mensagem de entrada na fila"

# Abre o atendimento humano para o agente passado no parâmetro
aura attendant open "email_do_agente"
```

### Widget

```bash
# Lista os widgets
aura widget list

# Remove um widget
aura widget remove widget_name

# Cria uma novo widget
# Existem parâmetros adicionais que podem ser obtidos com --help
aura widget new "Label do Widget" 

# Abre o widget passado como parâmetro
aura widget open "nome_do_widget"
```


[title] Bibliotecas
[path] Untitled/Customizações Avançadas/


[title] URL
[path] Untitled/Customizações Avançadas/Bibliotecas/

Bibloteca para serializar e deserializar URLs. O uso dessa biblioteca visa evitar a edicão
insegura de urls que acontece quando concatenamos strings diretamente.

## Atalhos

- [**URL**](docId\:taLM3l--3LOmmNAXSqE9v)
- [**URL**](docId\:taLM3l--3LOmmNAXSqE9v)

***

### Métodos

### Parse

```lua
-- @param string representando uma url
-- @return Uma table representando as estruturas que compõem a url específicada
url.parse("http://a")
```

```lua
-- example usage:
local central_url =  "http://usuario:senha@centralit.com.br/"
    .. "start/end?parametro=valor&parametro2=valor2"
    
local parsed = url.parse(central_url)

--[[
parsed value:

{
  host = "centralit.com.br",
  pass = "senha",
  path = { "start", "end" },
  port = 9876,
  query = {
    parametro = "valor",
    parametro2 = "valor2"
  },
  scheme = "http",
  user = "usuario"
}
--]]
 
```

### Serialize

```lua
-- @param Uma table representando as estruturas que compõem a url específicada
-- @return A string da url final
url.parse(url_table)
```

```lua
-- example usage:
local parsed = url.parse("http://a")

parsed.port = 1234
parsed.scheme = "wss"
parsed.host = "centralit.com.br"
parsed.path = {"a", "b", "c"}
parsed.query = {
    d = "e",
    f = "g"
}
parsed.user = "aura"
parsed.pass = "123456"

local final_url = url.serialize(parsed)

-- final_url = "wss://aura:123456@centralit.com.br:1234/a/b/c?d=e&f=g"

```


[title] Manual do Administrador
[path] Untitled/Instalação/

Este manual oferece orientações para que os administradores possam configurar e registrar plugins, contribuindo para a melhoria da experiência do usuário e a otimização do desempenho da plataforma.

## Comportamentos

A seção **Comportamentos** é onde você pode registrar e configurar os plugins da plataforma Aura Blocks. Nessa área, você consegue criar novos comportamentos, configurar **Interlocutores**, **Mensageiros** e definir **Eventos**. Todos os plugins cadastrados ficam centralizados aqui para fácil acesso e gerenciamento.

### Registrar Comportamento

Para registrar um novo comportamento, acesse o menu **Comportamentos**. Na tela, localize a seção **Registrar novo comportamento** e clique no botão **Avançar** para prosseguir. Veja a imagem abaixo como referência:

![Registrar Comportamento](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/B74kMwbAiuV2pvBoTDEge_registrarcomportamento.png)

Em seguida, preencha o campo **Nome do Comportamento** com o nome desejado e selecione o **Manifesto** que ira utilizar. Cada manifesto oferece parâmetros diferentes. Quando você escolhe um manifesto, a URL é preenchida automaticamente, mas você pode personalizá-la se optar pela opção Personalizado.

![Preenchendo Comportamento](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/Zzmb578rcx36IIMjWdkt5_preenchercomportamento.png)

### Parâmetros

Cada manifesto requer o preenchimento de parâmetros específicos. Abaixo, você encontrará um exemplo dos parâmetros necessários para cadastrar a **Botmaker**:

- **Texto para Botões**: Mensagem exibida antes das opções no WhatsApp.
- **ID do Canal**: Identificador único atribuído a um canal específico.
- **Token de Acesso**: Código exclusivo gerado pela plataforma **Botmaker** que autentica e autoriza a comunicação entre aplicativos.

Confira a imagem abaixo para referência:

![Parâmetros](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/3tg7H8MACESqegnhARwTn_parametros.png)

Os manifestos disponíveis possuem os seguintes parâmetros para preenchimento:

**Personalizado** - Permite configurar a URL manualmente.

- **Parâmetros**: Depende da URL fornecida.

**Wanderson**

- **Selecione o Workspace**: Escolha o Workspace desejado.
- **Escolha uma skill**: Selecione uma skill cadastrada para configurar o comportamento.

**Lunaris**

- **Qual o nome do workspace?**: Selecione um workspace previamente cadastrado.
- **Qual o nome da pipeline?**:  Escolha uma pipeline cadastrada para ser vinculada.

**Atendimento Humano**

- **Fila de Atendimento**: Selecione a fila de atendimento à qual o comportamento estará vinculado.

**Gupshup**

- **Título das opções**: Defina o texto que será exibido antes das opções de interação.
- **Número de telefone da conta**: Informe o número vinculado à conta Gupshup.
- **Canal do App**: Escolha o canal de integração do app.
- **Nome do App Gupshup**: Especifique o nome do app Gupshup.
- **Chave da API**: Insira a chave da API Gupshup para autenticação.

**Facebook Messenger**

- **Facebook ID**: Forneça o ID da página vinculada ao Messenger.
- **Token de Acesso**: Insira o token de acesso gerado pelo Facebook Messenger.

**Positus**

- **Título das opções**: Defina o texto que será mostrado antes das opções.
- **Código do número WhatsApp**: Informe o código associado ao número do WhatsApp.
- **Token de Acesso**: Insira o token de acesso para autenticar a integração com o Positus.

**Slack**

- **Slack ID**: Forneça o ID do workspace Slack para vinculação.
- **Token de Acesso**: Insira o token de acesso para autorização no Slack.

**Twilio**

- **SID da Conta**: Forneça o SID (Account SID) da sua conta Twilio.
- **Token de Acesso**: Insira o token de acesso gerado pela plataforma Twilio.
- **Contato**: Defina o número de contato que será utilizado nas interações.

**Telegram**

- **Qual o token do seu BOT?**: Código gerado pelo Telegram que identifica e autoriza o BOT a funcionar.
- **Qual o ID do chat?**: Número que identifica o chat onde o BOT vai atuar.

**Microsoft Teams**

- **Nome do Chatbot**: Nome que aparecerá no Microsoft Teams quando o BOT interagir com os usuários
- **ID do App**: Código exclusivo que identifica o aplicativo do BOT dentro do Microsoft Teams.
- **ID do Locatário**: Código representa a organização à qual o Microsoft Teams está vinculado.
- **Segredo do App**: Senha gerada pelo Microsoft Teams autorizando o seu funcionamento.

### Configurações

A opção **Iniciar a conversa no comportamento** permite definir qual skill será utilizada. Ao configurá-la, a skill escolhida inicia assim que o comportamento é acionado, garantindo que a conversa comece com o fluxo desejado. Confira a imagem abaixo para referência:

![Iniciar a conversa no comportamento](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/rTnvw8STOTdqARTy92wWI_comportamentoconversa.png)

### Atualizar Parâmetros

Após cadastrar um comportamento, você pode realizar novas configurações a qualquer momento. Basta selecionar o comportamento desejado e clicar em **Configurar**. Os parâmetros serão apresentados para que você os preencha novamente, permitindo ajustes conforme necessário.

Confira a imagem abaixo para referência:

![Configurar](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/Fv5jRE9_8cTHH_MPK_TRw_configurar.png)

### Editar

Também é possível editar determinados comportamentos. Para isso, basta localizar o botão **Editar** no comportamento desejado e clicar nele. Você será direcionado para a área específica desse comportamento, onde poderá realizar as edições necessárias. Veja abaixo como o botão é apresentado:

![Editar Atendimento](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/o3ztyMGptkuVR11cSkMoV_editaratendimento.png)


[title] Positus
[path] Untitled/Brokers/

A especificação abaixo serve como manual para utilização do broker [**Postius**](https://www.positus.com.br/).

## Configuração

Para cadastrar o broker Positus é necessária copiar a rota de envio de mensagens do Positus e do token api do Positus. Para testes o Positus oferece um modo Sandbox com um número já vinculado para recebimento e envios de mensagens além de uma url específica do sandbox.

URL exemplo: [**https://api.positus.global/v2/sandbox/whatsapp/numbers/814e1f43-af0b-4ecb-a3ee-719c3481fabf/messages**](https://api.positus.global/v2/sandbox/whatsapp/numbers/814e1f43-af0b-4ecb-a3ee-719c3481fabf/messages)

### Criando uma conta

Basta acessar o [**link para criação de contas**](https://studio.posit.us/register) e acessar o modo [**Sandbox**](https://studio.posit.us/sandbox/intro)

### Modo Sandbox

Para acessar o modo sandbox é necessário primeiro habilitar um numero de whatsapp para receber e enviar mensagens a Positus
![Sandbox](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/kH666eiUG8-vN4XkMzMDR_novocontato.png)

### Obtendo uma chave api

Para obter a chave api basta acessar no menu lateral a aba API Tokens ou acessar o [**link**](https://studio.posit.us/minha-conta/api-tokens) e clicar em "Novo token".

![Api-Token](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/NLrKZt_R9b9RAt2tGr2Zh_apitoken.png)

![Novo token](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/SFQk-cTQSiWK57ouRV3fu_newtoken.png)

### Registrando o webhook

Para cadastrar o endereço do webhook basta acessar no menu lateral a aba Sandbox e ir em "Webhook" ou acessar o [**link**](https://studio.posit.us/sandbox/configuracoes). Uma vez registrado o webhook a plataforma irá redirecionar todas as mensagens para lá. **Para o uso do modo Sandbox é necessário habilitar os números que podem enviar ou receber mensagens**. Para isso basta ir na aba "Contatos" e enviar o código indicado para o whatsapp do número fornecido pelo Sandbox ou ler o QR da tela.

![sandbox](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/M4AUzGBkiTBfpe5HBeX_d_sandbox.png)

Para o funcionamento do Broker é necessária a devida configuração da rota do Webhook para isso basta clicar em "Editar Webhook" e preencher o campo com o endereço e salvar

Para o registro do webhook da Positus é necessário conter o identificador do workspace como parâmetro da URL:

```text
https://{caminho_para_lunaris}/post/{nome_do_plugin}/webhook?workspace={identificador_do_workspace}
```



![webhook](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/RyLoTVmCMXB0il1kZBpov_webhook.png)

No menu contatos é possível verificar quais contatos estão habilitados a se comunicar com o Positus

![contatos](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/76p4qw8wglkGEFHJ17isx_contatos.png)

## Campos necessários

Para registar o broker Positus são necessários os seguintes campos:

```text
Código de número do Whatsapp
URL para envio das mensagens
Token de acesso
```

### Código de número do Whatsapp

Todos os números de Whatsapp possuem um código único de identificação.
Para achar o código do seu número específico é preciso verificar na página do Whatsapp Bussiness

No caso do modo Sandbox é possível achar de maneira fácil o código do número já disponibilizado ao entrar no Submenu Webhook

![Codigo do Whatsapp](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/GTqhEeYcS2dKM9h6Wn_oN_codigowhatsapp.png)

### URL para envio das mensagens

Existem duas possibilidades de URL para envio de mensagem

Caso esteja testando o modo Sandbox da Positus é preciso utilizar a seguinte URL:

```text
https://api.positus.global/v2/sandbox/whatsapp/numbers/
```

Caso não estaja usando o modo Sandbox é preciso utilizar a seguinte URL:

```text
https://api.positus.global/v2/whatsapp/numbers/
```

### Token de acesso

Para obter o token de acesso basta executar os passos já descritos para obter a chave da API

[title] Gupshup
[path] Untitled/Brokers/

A especificação abaixo serve como manual para a utilização do broker [**Gupshup**](https://www.gupshup.io/).

## Configuração

Para cadastrar o broker Gupshup é necessário um número de Whatsapp Busines, o nome do app registrado no Gupshup e uma chave de acesso do app. Para testes o Gupshup oferece um modo Sandbox com um número habilitado a enviar e receber mensagens.

### Criando uma conta

Basta acessar o [**Gupshup**](https://www.gupshup.io/) e acessar a tela de login clicando no botão superior esquerdo.

![Registro](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/CECRJFnqFBnADO9n5QsR0_gupshupregister.png)

### Criando um app

Para criar um app Gupshup é necessáro estar logado e acessar o dashboard e clicar no botão "Create App", nomear o app. Uma vez criado o app basta acessá-lo clicando em "Overview" ao lado direito do nome do app. Lá é possível obter informações do app como sua chave de api e acessar o modo Sandbox. **Para que seja possível receber e enviar mensagens de um número é necessário ir na aba "Opt-ins" e habilitar o número de Whatsapp.**

![Criar app](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/dbyrwx1vdGp6bU5UKQ62C_createapp.png)

![Abrir app](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/SmGox-q0invgUQW2Zn6gk_overview.png)

![opt in](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/vsPNdmx_jMBkwRLU7fRO__optin.png)

### Registrando o webhook

![Webhook](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/5r9t_3iGPYRNU8eIBTy0t_webhook.png)

Para cadastrar o endereço webhook basta acessar a aba "Webhook", inserir o endereço do webhook no campo "Callback URL" e clicar em "Set".

```text
https://{caminho_para_lunaris}/post/{nome_do_plugin}/webhook
```

## Campos Necessários

Para registar o broker Gupshup são necessários os seguintes campos:

```text
Número de telefone da conta
Canal do app
Nome do app gupshup
Chave da API
```

### Número de telefone

Caso esteja usando o modo Sandbox do Gupshup é fornecido um número para testes.

![Numero da conta](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/TQJR1ovSLtapoQktggvf1_numero.png)

É possível verificar o número da conta através do menu Sandbox dentro de um app

Caso não esteja usando o modo sandbox utilize o número registrado na conta Gupshup

### Canal do APP

O Gupshup possui diversos canais para envio e recebimento de texto por isso é necessário escolher em qual ele irá funcionar.

Para utilizar o Whatsapp como canal basta registar como "whatsapp"

### Nome do APP Gupshup

É o nome registrado do APP Gupshup feito nos passos anteriores.

### Chave da API

Para obter a chave API basta acessar o menu "Settings" dentro de um APP Gupshup ou clicar no avatar no canto superior direito

![Chave API](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/iAQUgNewBKNEFAwnku9yu_apikey.png)

[title] Telegram
[path] Untitled/Brokers/

A especificação a seguir atua como um guia detalhado para utilização do broker **Telegram**, fornecendo todas as instruções e orientações necessárias para sua configuração.

## Configuração

Para realizar o cadastro do broker, é imprescindível fornecer o token do bot e o identificador do chat. Todos esses dados podem ser facilmente encontrados após a criação do bot no [**BotFather**](https://telegram.me/BotFather).

## O que é o BotFather?

O **BotFather** é o bot oficial do Telegram usado para gerenciar e criar novos bots. Com ele, você pode registrar um novo bot, definir o nome, a descrição, o avatar e até gerenciar as permissões do seu bot.

## Criar um Bot

Siga os passos abaixo para criar um bot no Telegram e integrá-lo à plataforma low-code.

1. Abra o aplicativo Telegram e inicie uma conversa com o [**BotFather**](https://telegram.me/BotFather).
2. Digite o comando `/newbot` e pressione enter.

:::BlockQuote
O BotFather irá pedir que você escolha um nome para o bot. Esse será o nome que aparecerá nos chats. O nome deve terminar com a palavra `bot`. Por exemplo: `Meubot`.
:::

1. Após escolher o nome, o BotFather irá fornecer um **token**, que será utilizado para o cadastro dentro da plataforma low-code.

![inicio](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/B98LEACrAf9Y04-XM41wj_botfatherinicio.png)

1. Entre no chat com seu bot, que pode ser acessado no link `t.me/<nome_do_bot>`, e pressione o botão "start".
2. Em seguida, acesse a URL 
   `https://api.telegram.org/bot<token_do_bot>/getUpdates`
   , e um JSON será retornado. Nele, procure a seção abaixo e copie o 
   **identificador (id)**
    do chat para utilizá-lo dentro do low-code.
   ```json
   {
       chat: {
           id:7288249035,
           first_name: "Nome",
           last_name:"Sobrenome",
           type:"private"
       }
   }
   ```
3. Para garantir a segurança da comunicação, você precisa criar um segredo que será usado para validar as mensagens entre o bot e a plataforma. Esse segredo pode ser qualquer texto com 1 a 256 caracteres, mas recomenda-se utilizar uma chave aleatória gerada com os comandos abaixo:
   :::BlockQuote
   É possível gerar chaves aleatórias com os seguintes comandos:
   :::
   ### Windows.
   ### Powershell
   ```powershell
       $chars = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789'
       $key = -join ((1..256) | ForEach-Object { $chars[(Get-Random -Maximum $chars.Length)] })
       Write-Output $key
   ```
   ### Linux.
   ```bash
   < /dev/urandom tr -dc 'A-Za-z0-9' | head -c 256
   ```
   ### Mac
   ```bash
       LC_ALL=C < /dev/urandom tr -dc 'A-Za-z0-9' | head -c 256
   ```
   Todos devem gerar uma chave similar a essa:

   `FJHv5Us4MllS6EKK6O3PQEs3TzLJUQURjPp5LoDklIAs3GCZTkUiYMPINkPIreUX7cEhW6zd15y...`

## Configuração

Normalmente, a configuração é feita automaticamente pelo próprio plugin, mas, em alguns casos, pode falhar. Use esta seção caso o bot não responda após a primeira interação.

:::BlockQuote
**ATENÇÃO:** Basta copiar e colar as URLs a seguir na barra de pesquisa de qualquer navegador para acionar a API do Telegram.
:::

Após configurar o seu bot, é necessário configurar o webhook. Você pode fazer isso utilizando a seguinte URL:

`https://api.telegram.org/bot<TOKEN_DO_BOT>/setWebhook?url=https://{seu-dominio}/{lunaris_embiente}/post/telegram/webhook`

Se tudo ocorrer corretamente, a mensagem a seguir será exibida, confirmando que o webhook foi configurado.

```json
{
    "ok":true,
    "result":true,
    "description":"Webhook was set"
}

```

[title] Backup
[path] Untitled/Instalação/

Esta documentação detalha métodos recomendados para realizar backup das bases de dados e dos volumes persistentes (PVC) da plataforma Aura. Cobre abordagens manuais e uso de ferramentas de backup, sem detalhar ou citar nomes de softwares específicos.

***

## 1. Backup de Bancos de Dados (PostgreSQL)

Existe apenas uma base de dados PostgreSQL por ambiente (Produção, Teste, Homologação, etc.), necessário para o funcionamento da plataforma Aura:

- **Nome padrão:** `aura_blocks`

***

### 1.1. Métodos de Backup do PostgreSQL

### 1.1.1. Backup Manual com pg\_dump (linha de comando

O método mais comum e recomendado para backup lógico do PostgreSQL utiliza comandos nativos da ferramenta, geralmente executados a partir do pod ou da máquina onde está o banco.

**Exemplo A: Dump direto do pod para o host local**

```sh
kubectl exec -it <namespace>/<postgresdb-pod> -- pg_dump -U <db_user> <db_name> > ./backup.sql
```

:::BlockQuote
Este comando executa o `pg_dump` diretamente dentro do pod e redireciona o resultado (`backup.sql`) para o seu host local, sem necessidade de copiar depois.
:::

- **Prós:** Prático, evita etapas extras.
- **Contras:** O dump é transferido pela rede; em bancos muito grandes, avalie limitações de banda e possíveis timeouts do `kubectl`.

**Exemplo B: Dump gravado no pod e copiado depois**

```sh
kubectl exec -it <namespace>/<postgresdb-pod> -- bash -c "pg_dump -U <db_user> <db_name> > /tmp/backup.sql"

kubectl cp <namespace>/<postgresdb-pod>:/tmp/backup.sql ./backup.sql
```

:::BlockQuote
Use este método se preferir salvar o dump no pod e copiar para o host em seguida.
:::

### 1.1.2. Backup via Interface Gráfica

Se preferir interface gráfica, utilize ferramentas de administração de bancos de dados compatíveis com PostgreSQL, seguindo a documentação oficial dessas ferramentas.

***

### 1.1.3. Backup Avançado

Ferramentas especializadas podem ser utilizadas para automatizar, agendar e aprimorar backups em ambientes críticos ou com alto volume de dados, permitindo, por exemplo, backups incrementais, upload em nuvem, gerenciamento de retenção, entre outros recursos.

- Consulte a documentação das ferramentas de sua escolha para instalação, configuração e restore.

***

### 1.1.4. Backup do Volume do PostgreSQL (PVC)

Também é possível realizar backup do volume do banco utilizando métodos manuais (como cópia de arquivos) ou ferramentas de backup de volumes persistentes.

:::BlockQuote
**Importante:** Para garantir a consistência do backup, recomenda-se pausar o banco ou executá-lo em modo de backup durante o processo.
:::

***

### 1.2. Restauração

### 1.2.1. Restauração Manual

:::BlockQuote
**Importante:** Antes de restaurar o backup, certifique-se de que a base de dados (`<db_name>`) já está criada no PostgreSQL. O comando psql não cria a base automaticamente durante a restauração.
:::

```sh
# Exemplo: criando a base de dados se ainda não existir
kubectl exec -it <namespace>/<postgresdb-pod> -- psql -U <db_user> -c "CREATE DATABASE <db_name>;"
```

Depois, prossiga com a restauração.

**Exemplo A: Restauração a partir do host local direto do pod**

```sh
cat ./backup.sql | kubectl exec -i <namespace>/<postgresdb-pod> -- psql -U <db_user> <db_name>
```

**Exemplo B: Copia o backup para o pod e depois é feita a restauração**

```sh
kubectl cp ./backup.sql <namespace>/<postgresdb-pod>:/tmp/backup.sql
kubectl exec -it <postgresdb-pod> -- psql -U <db_user> -d <db_name> -f /tmp/backup.sql
```

***

### 1.3. Boas Práticas

- Automatize backups periódicos em produção.
- Mantenha múltiplas cópias (offsite/nuvem/local).
- Sempre teste o restore em ambiente de homologação.
- Documente o processo de restauração.

***

### 1.4. Comparativo de Métodos

<table isTableHeaderOn="true" selectedColumns="" selectedRows="">
  <tr>
    <td align="left">
      <p>Método</p>
    </td>
    <td align="left">
      <p>Consistência</p>
    </td>
    <td align="left">
      <p>Automatizável</p>
    </td>
    <td align="left">
      <p>Offsite</p>
    </td>
    <td align="left">
      <p>Complexidade</p>
    </td>
    <td align="left">
      <p>Recuperação</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p>Comandos nativos</p>
    </td>
    <td align="left">
      <p>Sim</p>
    </td>
    <td align="left">
      <p>Sim</p>
    </td>
    <td align="left">
      <p>Sim</p>
    </td>
    <td align="left">
      <p>Baixa</p>
    </td>
    <td align="left">
      <p>Fácil</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p>Ferramentas especializadas</p>
    </td>
    <td align="left">
      <p>Sim</p>
    </td>
    <td align="left">
      <p>Sim</p>
    </td>
    <td align="left">
      <p>Sim</p>
    </td>
    <td align="left">
      <p>Média</p>
    </td>
    <td align="left">
      <p>Avançada</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p>Backup do volume (PVC)</p>
    </td>
    <td align="left">
      <p>Sim*</p>
    </td>
    <td align="left">
      <p>Sim</p>
    </td>
    <td align="left">
      <p>Sim</p>
    </td>
    <td align="left">
      <p>Média</p>
    </td>
    <td align="left">
      <p>Rápida</p>
    </td>
  </tr>
</table>

:::BlockQuote
\*Consistência depende do banco estar pausado ou em modo de backup durante o procedimento.
:::

***

## 2. Backup de Volumes Persistentes (PVC)

Os volumes persistentes (PVC) estão descritos nos manifestos do Kubernetes, geralmente no arquivo `persistentvolumeclaim.yaml`. Exemplo de PVC:

```yaml
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: storage
  namespace: aura-blocks
spec:
  accessModes:
    - ReadWriteMany
  resources:
    requests:
      storage: 50Gi
  storageClassName: <storageClassName>
```

A escolha do `storageClassName` impacta diretamente as opções de backup disponíveis.

***

### 2.1. Métodos de Backup de PVC

### 2.1.1. Backup Manual

Realize backup copiando arquivos diretamente do volume do pod para outro local seguro.

**Exemplo A: Usando kubectl cp**

```sh
kubectl cp <namespace>/<pod>:/caminho/dados ./backup-local
```

:::BlockQuote
Substitua `<namespace>`, `<pod>` e o caminho do volume conforme sua aplicação.
:::

**Exemplo B: Usando container temporário + tar**

```sh
kubectl run backup-job --rm -i -t --restart=Never \
  --image=alpine \
  --overrides='{"spec": {"volumes": [{"name": "data", "persistentVolumeClaim": {"claimName": "<nome-pvc>"}}], "containers": [{"name": "backup", "image": "alpine", "command": ["sh"], "stdin": true, "tty": true, "volumeMounts": [{"mountPath": "/caminho/dados", "name": "data"}]}]}}' -- \
  sh
```

Dentro do shell:

```sh
tar czvf /tmp/backup.tar.gz /caminho/dados
```

Em outro shell, copie o arquivo do pod:

```sh
kubectl cp <namespace>/backup-job:/tmp/backup.tar.gz ./backup.tar.gz
```

**Dicas:**

- Compacte arquivos grandes (`tar`, `gzip`).
- Faça backup regularmente e teste a restauração.

***

### 2.2. Comparativo dos Métodos

<table isTableHeaderOn="true" selectedColumns="" selectedRows="">
  <tr>
    <td align="left">
      <p>Método</p>
    </td>
    <td align="left">
      <p>Suporte a Volumes</p>
    </td>
    <td align="left">
      <p>Backup Offsite</p>
    </td>
    <td align="left">
      <p>Automação</p>
    </td>
    <td align="left">
      <p>Complexidade</p>
    </td>
    <td align="left">
      <p>Volume Grande</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p>Manual (<code>cp</code>, <code>tar</code>)</p>
    </td>
    <td align="left">
      <p>Sim</p>
    </td>
    <td align="left">
      <p>Sim</p>
    </td>
    <td align="left">
      <p>Baixa</p>
    </td>
    <td align="left">
      <p>Baixa</p>
    </td>
    <td align="left">
      <p>Médio</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p>Ferramentas de backup</p>
    </td>
    <td align="left">
      <p>Sim</p>
    </td>
    <td align="left">
      <p>Sim</p>
    </td>
    <td align="left">
      <p>Alta</p>
    </td>
    <td align="left">
      <p>Média/Alta</p>
    </td>
    <td align="left">
      <p>Ótimo</p>
    </td>
  </tr>
</table>

***

## 3. Recomendações Finais

- Realize backup periódico dos dados críticos.
- Prefira automação para ambientes produtivos.
- Sempre teste a restauração!
- Documente o processo de restauração para cada método.
- Utilize múltiplas estratégias para resiliência máxima.

***

### Referências

- [**Backup PostgreSQL**](https://www.postgresql.org/docs/17/backup.html)
- [**PgAdmin Backup**](https://www.pgadmin.org/docs/pgadmin4/development/backup_dialog.html)

[title] Máquina de Estados - Detalhes
[path] Untitled/Customizações Avançadas/

Este é um manual mais avançado das capacidades da máquina de estados. Os exemplos mostrados aqui pertencem ao editor de código de uma skill.

- `#` Adiciona um comentário;
- `/` Caractere de escape
- `@` Estado local;
- `@+` Espera por um input;
- `@@` Estado global;
- `-` Adiciona um texto;
- `=` Adiciona um exemplo;
- `%` Exemplo externo;
- `>` Avança para um estado;
- `!` Frase apresentada, caso não haja um entendimento;
- `?` Frase apresentada, caso haja uma desambiguação;
- `^` Permite ocultar menu (botão);
- `{{VARIAVEL DE AMBIENTE}}` Variáveis de ambiente;
- `$PIPELINE_INTERCEPTOR: PASTA_DO CLIENTE/NOME_DA_PIPELINE/` Chamada de
  pipeline;
- `$HUMAN_ATTENDANCE_INTERCEPTOR:ID_FILA` Chamada de fila de atendimento humano;
- Paginação
  - `more_options_label` Configura mensagem para ver mais opções;
  - `max_menu_options` Quantidade de menus apresentada por vez;
- `min_word_size` Tamanho mínimo para ser considerado uma palavra;

## Estado ou Intenções

### Operadores Especiais

### Não entendimento (!)

O **operador (!), mostrará de forma aleatória** uma das **frases apresentadas,&#xD;**&#xA;**caso não haja um entendimento**.

### Desambiguação (?)

Outro operador muito similar ao similar ao anterior, é **operador (?)**, onde
este **mostrará de forma aleatória uma das frases apresentadas, caso haja uma&#xD;**&#xA;**desambiguação**.

### Texto (-)

Para adicionar um texto a um fluxo, use o operador (-). Vale lembrar que **se o&#xD;**&#xA;**fluxo tiver mais de um operador de texto (-), um abaixo do outro, todos no&#xD;**&#xA;**início da linha. A máquina de estados escolherá de forma aleatória um dos textos**.

```text
@start
= um exemplo aleatorio

- Olá, Seja bem-vindo(a)!
Eu sou o assistente virtual da Reduce XYZ. Como posso ajudar?
> end

@end 
# Se seu fluxo tiver mais de um operador de texto ( - ), um abaixo do outro 
como no exemplo. A máquina de estados escolherá de forma aleatória um dos textos.
- Se precisar de ajuda, basta me chamar.
Reduce xyz agradece o contato!
- Reduce xyz está sempre a disposição para ajudar e agradecemos o contato!
```

```text
~/codes/cetralit/wanderson  on master ?3  wanderson examples/operador    
                                                                                
                                                        
- Olá, Seja bem-vindo(a)!
Eu sou o assistente virtual da Reduce XYZ. Como posso ajudar?

- Reduce xyz está sempre a disposição para ajudar e agradecemos o contato!

start..end 1.000
 ~/codes/cetralit/wanderson  on master ?3  wanderson examples/operador 
                                                                                
                                                       

- Olá, Seja bem-vindo(a)!
Eu sou o assistente virtual da Reduce XYZ. Como posso ajudar?

- Se precisar de ajuda, basta me chamar.
Reduce xyz agradece o contato!

start..end 1.000

```

### Exemplo (=)

O operador de exemplo **(=)** permite cadastrar exemplos a intenções e
entidades para serem analisados e interpretados pela nossa NLU.

### Exemplo Externo (%)

O operador de exemplo externo (%), permite cadastrar **de forma externa&#xD;**&#xA;**exemplos (=)**, que podem ser **utilizados por mais de uma intenção ou&#xD;**&#xA;**entidade**. Através **do caractere (&)**.

Utilizar essa abordagem reduz o número de linhas e facilita a
adesão de novos exemplos, após o processo de curadoria.

Exemplos Externos devem ser cadastrados em uma única pasta, todos os arquivos nesta pasta devem conter apenas, este operador.

```text
%chit_chat_saudacao
= Alô
= Boa noite
= Boa tarde
= Bom dia
= Bom dia, prezados
= Hello
= Hi
= Oi
= Olá
= Saudação
```

```text
@start
# Uso do exemplo externo ( % )
&chit_chat_saudacao
= um exemplo aleatório

- Olá, Seja bem-vindo(a)!
Eu sou o assistente virtual da Reduce XYZ. Como posso ajudar?
> end

@end
 &chit_chat_saudacao
- Se precisar de ajuda, basta me chamar.
Reduce xyz agradece o contato!
- Reduce xyz está sempre a disposição para ajudar e agradecemos o contato!
```

### Variável de ambiente (\{\{variavel\_ambiente}})

Este é um operador que permite **acessar variáveis externas de clientes**,
para **incorporar** ao nosso **fluxo de conversa**. O exemplo **mais comum** é
a variável, **\{\{username}}** do **Citsmart**.

### Caractere de escape (/)

O caractere de escape permite, anular um operador da máquina de estados que seria
interpretado de alguma maneira, para ser usado num texto.

```text
@start 
- {{saudacao_tempo}}
Olá {{user_name}}. Como vai você?
Por favor acesse o perfil \@CentralIT

> end

@end
- Até a próxima!
```

```text
- Bom dia
Olá user_name. Como vai você?
ePor favor acesse o perfil @CentralIT

- Até a próxima!


start..end 1.000
```

### Intenções Locais (@)

Intenções ou estados locais são estados que só podem ser acessados quando
um jump (>) a partir do estado atual os aponta. São **categorizados** pelo
`@nome_qualquer: titulo do menu` e possuem a seguinte estrutura:

```text
@start
- Olá, Seja bem-vindo(a)!
Eu sou o assistente virtual da Reduce XYZ. Como posso ajudar?
> atendente 
> status

@atendente: Atendente 
= atendente
- Um atendente irá te ajuda
> end

@status: ^ status
= status
- Seu status está OK
> end

@reduce: Reduce
= reduce
- impossivel entrar no reduce, pois nenhum estado, da jump para ele
> end

@end
- acabou
```

```text
- Olá, Seja bem-vindo(a)!
Eu sou o assistente virtual da Reduce XYZ. Como posso ajudar?
1. map

start..start 1.000 > status
- Seu status está OK

- acabou

filter..end 1.000
 ~/codes/cetralit/wanderson  on master ?3  wanderson examples/operador
                                                                                
                                                       
- Olá, Seja bem-vindo(a)!
Eu sou o assistente virtual da Reduce XYZ. Como posso ajudar?
1. atendente

start..start 1.000 > reduce
- Não compreendi o que você deseja
1. atendente

start..start 0.000 >
```

Perceba que apesar de a intenção **@reduce existir** e **não estar ocultada,&#xD;**&#xA;**pelo operador (^)**. Ela **não aparece de forma alguma no fluxo&#xD;**&#xA;**conversacional**. Isso porque o **estado atual** não aponta para o reduce.

### Aguarde por input (@+)

Aguarde por input, faz com que o próximo jump,
só seja executado caso o usuário digite o próximo passo. Perfeito para criar
listas passo a passo. Veja o exemplo:

```text
@start 
- oi
> passo1

@+passo1
- passo 1
> passo2

@+passo2: passo 2
- passo 2
> passo3

@passo3: passo 3
- passo 3
> end

@end
- tchau
```

```text
~/codes/cetralit/wanderson  on master ?3  wanderson examples/operador
                                                                                
                                                        
- oi

- passo 1
1. passo 2

start..passo1 1.000 > 1
- passo 2
1. passo 3

passo2..passo2 1.000 > 1
- passo 3

- tchau

passo3..end 1.000
```

### Intenções Globais ( @@ )

Intenções ou estados globais, como proprio nome sugere, **podem ser acessados&#xD;**&#xA;**de qualquer etapada da conversa**. São **categorizados** pelo
`@@nome_qualquer: titulo do menu` e possuem a seguinte estrtura:

```text
@start
- Olá {{username}}! Seja bem-vindo(a)!
Eu sou o assistente virtual do Reduce. Como posso ajudar?

> map 
> filter

#fluxo local 
@map: map 
= map
> end

#fluxo local
@filter: filter
= filter
> end

# fluxo global
@@fluxo_global_oculto: ^ fluxo global oculto
= fluxo global oculto
- todo fluxo global, se não ocultado pelo operador (^). Conforme a cima, 
aparecera nos menus do @start
Este é o caso, do fluxo_global_não_oculto
> end

#fluxo global
@@fluxo_global_nao_oculto: fluxo global nao oculto
= fluxo global não oculto
- todo fluxo global, se não ocultado pelo operador (^). Conforme a cima, 
aparecera nos menus do @start
> end

@end
- acabou
```

```text
~/codes/cetralit/wanderson  on master ?3  wanderson examples/operador    
                                                                                
                                                        
- Olá username! Seja bem-vindo(a)!
Eu sou o assistente virtual do Reduce. Como posso ajudar?
1. map
2. filter
3. fluxo global nao oculto

start..start 1.000 > fluxo global

start..start 0.683 > 
 ~/codes/cetralit/wanderson  on master ?3  wanderson examples/operador  
                                                                                
                                                       
- Olá username! Seja bem-vindo(a)!
Eu sou o assistente virtual do Reduce. Como posso ajudar?
1. map
2. filter
3. fluxo global nao oculto

start..start 1.000 > 
 ~/codes/cetralit/wanderson  on master ?3  wanderson examples/operador  
                                                                                
                                                       
- Olá username! Seja bem-vindo(a)!
Eu sou o assistente virtual do Reduce. Como posso ajudar?
1. map
2. filter
3. fluxo global nao oculto

start..start 1.000 > fluxo global não oculto

- todo fluxo global, se não ocultado pelo operador (^). Conforme a cima, 
aparecera nos menus do @start

- acabou

fluxo_global_nao_oculto..end 1.000
```

Vale lembrar que todo **fluxo global, se não ocultado pelo operador (^)**.
Conforme a cima, **aparecerá** nos menus do **@start** Este é o caso, do
**fluxo\_global\_não\_oculto**

## Entidades

### Entidades na máquina de estados (\*)

O operador que caracteriza uma **Entidade (\*)**, seguido de seu nome `*nome`.
Para um melhor uso dessa entidade, você deve pegar exemplos (=) que são muito
próximos e cadastrá-los numa mesma entidade. Veja a seguinte estrutura.

Entidades devem ser cadastrados em uma única pasta, todos os arquivos dessa pasta devem conter apenas, este operador. Vale lembrar também, que a ordem das Entidades (\*) importa nos exemplos (=).

```text
*veiculo
= carro
= moto
= caminhao

*marca_veiculo
= honda
= bmw
= ford
= fiat

*posse
= meu
= minha

*ipva
= imposto propriedade veículo automotor
= imposto propriedade veículos automotores
= ipva

*vontade
= quero
= preciso
= gostaria de
```

```text
@start 
- oi
> pagar_ipva
> transferir_carro
> end

@pagar_ipva
= *ipva *posse
- ipva

> end

@transferir_carro
# a ordem das Entidades ( * ) importa nos exemplos ( = )
= *ipva *marca_veiculo
- transferir carro

> end

@end
- tchau
```

## Interceptadores ( $ )

### Pipeline

De forma bem resumida e abrangente o conceito de pipeline, representa as etapas
do processo pelas quais algo passa até cumprir um objetivo.

Na equipe Gia, se utiliza muito pipelines para acessar api's do Citsmart para
abrir chamados, preenchendo formulários via pipeline.

**Como usar?**

Basta colocar no fluxo que deseja invocar uma pipeline: “`$ 
`
`PIPELINE_INTERCEPTOR: PASTA_DO CLIENTE/NOME_DA_PIPELINE/`"

O nome da pasta do cliente bem como nome da pipeline pode ser encontrado no CITBot - Filebrowser

[**File Browser**](https://citbot-api.centralit.com.br/fb/login?redirect=%2Ffiles%2F)

```text
@@mapear_pasta_rede: ^ Conceder Acesso/Mapear pasta de rede
= Acesso a pasta de rede
- Entendi que deseja atendimento sobre concessão de acesso/mapeamento de pasta 
de rede. está correto?

> mapear_pasta_rede_sim
> mapear_pasta_rede_nao

@mapear_pasta_rede_sim: ^ Sim
&navigation_sim

# INVOCANDO PIPELINE
$ PIPELINE_INTERCEPTOR: PASTA_DO CLIENTE/NOME_DA_PIPELINE/

> finalizacao_fluxo_padrao

@mapear_pasta_rede_nao: ^ Não
&navigation_nao
> finalizacao_de_fluxo_em_caso_de_entendimento_incorreto
```

### Atendimento Humano

A plataforma Aura permite que o bot, transfira para uma fila de atendimento
humano. Bastando colocar no fluxo que deseja invocar um atendimento humano
`$HUMAN_ATTENDANCE_INTERCEPTOR:ID_FILA`.

Para conseguir o ID\_FILA, acesse a plataforma aura ou consulte seu manual respectivamente.

[**Citbot**](https://citbot.centralit.com.br/)

[**Citbot Manual**](https://citbot-api.centralit.com.br/manuais/manual-do-usuario-solucao-plataforma-citbot.pdf)

```text
@@atendimento_humano: ^  Atendimento Humano
- Gostaria de falar com um de nossos analistas?
&atendimento_humano
&demanda_nao_resolvida
&nenhuma_das_opcoes
> atendimento_humano_sim
> atendimento_humano_nao

@atendimento_humano_sim: ^ Sim
&navigation_sim

# INVOCANDO ATENDIMENTO HUMANO
$HUMAN_ATTENDANCE_INTERCEPTOR:ID_FILA

> finalizacao_fluxo_padrao

@atendimento_humano_nao: ^ Não
&navigation_nao
> finalizacao_fluxo_padrao
```

## Parametros de configuração

Recomenda-se que os parâmetros citados nesse tópico, sejam passados num
arquivo chamado: “**01\_settings**”.

### Paginação

Os parâmetros de paginação permitem, mostrar uma quantidade específica de
menus na tela. Sendo o `more_options_label`, a mensagem que permite ver mais
opções, `max_menu_options`, a quantidade de menus apresentada por vez.

```text
# paginated
more_options_label = Ver mais
max_menu_options = 3

@start
? estou em dúvida entre as opções
! não entendi absolutamente nada
- Esses são os parametros de paginação, sendo o more_options_label, a 
mensagem que permite ver mais opções.
O max_menu_options, a quantidade de menus apresentada por vez.
 
> menu
> atendimento
> status
> reclamação
> novo_pedido

@manu: Menu
- Menu
= menu
> start

@atendimento: Atendimento
- Atendimento
= atendimento
> start

@status: Status
- Status
= status
> start

@reclamação: Reclamação
- Reclamação
= reclamacao
> start

@novo_pedido: Novo Pedido
- Novo pedido
= novo
= pedido
> start

@@end: Sair
= tchau
= bye
- tchau
```

```text
- Esses são os parametros de paginação, sendo o more_options_label, a 
mensagem que permite ver mais opções.
O max_menu_options, a quantidade de menus apresentada por vez.
1. Menu
2. Atendimento
3. Status
4. Sair
5. Ver mais

start..start 1.000 > 5
- Opções:
1. Reclamação
2. Novo Pedido
4. Sair
5. Ver mais

start..start 1.000 > 4
- tchau

end..end 0.000
```

### Tamanho minimo de palavra

Como o próprio nome sugere, o parâmetro `min_word_size`, especifica o
**número mínimo de letras**, que uma palavra deve ter, para a máquina de estados
considerar ela como válida.

Vale lembrar que por padrão o `min_word_size` é igual a 2, caso queira
alterar esse valor, basta passar o parâmetro.

**Emojis nos exemplos ( = )**

Para passar emoji nos exemplos, `min_word_size` deve ser igual a 0.

```text
min_word_size = 0

@start 
- Oi. Como você está? 🤔
> triste
> feliz

@triste: Triste
= 😢
- Que pena
> end

@feliz: Feliz
= 🙃
- um dia lindo um bom lugar pra ler um livro
> end

@end
- tchau 🦽
```

```text
~/codes/cetralit/wanderson  on master !2 ?3  wanderson examples/emoji.pagode    
                                                                                
                                                        
- Oi. Como você está? 🤔
1. Triste
2. Feliz

start..start 1.000 > c
- - um dia lindo um bom lugar pra ler um livro

- tchau 🦽

feliz..end 1.000
 ~/codes/cetralit/wanderson  on master !2 ?3
```

### Rank Options

A máquina de estados trabalha com referência por estado, palavras-chave e número de
palavras. Dando uma nota para os inputs, colocados pelo usuário. Como mostra o
exemplo do debug export `WANDERSON_INFO=TRUE`. Os Ranks abaixo permitem mudar
isso.

```text
~/codes/cetralit/wanderson  on master !2 ?3  wanderson examples/emoji.pagode    
                                                                                
                                                        
😢 => triste((1.0, 1))
🙃 => feliz((1.0, 1))

Referências por estado: 16
    end ////////////////////////////// 4
  feliz ////////////////////////////// 4
  start ////////////////////////////// 4
 triste ////////////////////////////// 4

Número de palavras chave: 2
 1 ////////////////////////////// 2

Número de estados relacionados a palavra chave: 2
 1 ////////////////////////////// 2

- Oi. Como você está? 🤔
1. Triste
2. Feliz

start..start 1.000 > 🙃
* 🙃
Rank: 1
  feliz ////////////////////////////// 1
 triste  0
- - um dia lindo um bom lugar pra ler um livro

- tchau 🦽

feliz..end 1.000
```

**ignore\_below**

O valor padrão desse parâmetro fara com que a máquina de estados ignore tudo abaixo de
`ignore_below = 0.2`

**is\_answer\_above**

O valor padrão desse parâmetro fara com que a máquina de estados somente considere
como correto, tudo que for superior ou igual a `is_answer_above = 0.8`

**parse\_at\_start**

Esse paramtro define, se no **@start**, o bot vai começar mandando mensagem
`parse_at_start = false` ou se ele vai esperar o usuario digitar
`parse_at_start = true`.

[title] Sleep
[path] Untitled/Customizações Avançadas/Bibliotecas/

Utilizado para pausar o processo por determinado tempo.

## Atalhos

- [**Sleep**](docId\:PIyxGVfLGfjOponRZzvH-)
- [**Sleep**](docId\:PIyxGVfLGfjOponRZzvH-)
- [**Sleep**](docId\:PIyxGVfLGfjOponRZzvH-)
- [**Sleep**](docId\:PIyxGVfLGfjOponRZzvH-)

***

### Métodos

### Secs

```lua
-- @param duration The duration in seconds to pause the process.
sleep.secs(duration)
```

```lua
-- example usage:

sleep.secs(1)
```

### Millis

```lua
-- @param duration The duration in milliseconds to pause the process.
sleep.millis(duration)
```

```lua
-- example usage:

sleep.millis(1000)
```

### Micros

```lua
-- @param duration The duration in microseconds to pause the process.
sleep.micros(duration)
```

```lua
-- example usage:

sleep.micros(1000000)
```

### Nanos

```lua
-- @param duration The duration in nanoseconds to pause the process.
sleep.nanos(duration)
```

```lua
-- example usage:

sleep.nanos(1000000000)
```


[title] Data URL
[path] Untitled/Customizações Avançadas/Bibliotecas/

Utilizada para embutir pequenos arquivos diretamente em documentos, representando dados como uma string codificada em Base64. Segue o formato `data:[<tipo MIME>][;base64],<dados>` de acordo com o [**Fetch Standard**](https://fetch.spec.whatwg.org/#data-urls).

## Atalhos

- [**Data URL**](docId\:L5yb8U7ZUDdbLz6XUxDNA)
- [**Data URL**](docId\:L5yb8U7ZUDdbLz6XUxDNA)

***

### Métodos

### Process

```lua
-- @param data String containing the Data URL.
-- @return a table containing all of the the data url parts.
dataurl.process(data)
```

```lua
-- example usage

local result = dataurl.process("data:text/plain;charset=iso-8859-7,%eb%fc%e3%ef%f2#fragment-url-here")

local body = result.body
local mimetype = result.mime.full

--[[
{
  body = "�����",
  fragment = "fragment-url-here",
  mime = {
    full = "text/plain;charset=iso-8859-7",
    parameters = {
      charset = "iso-8859-7"
    },
    subtype = "plain",
    type = "text"
  }
}
--]]
```

### Create

```lua
-- @param mimetype String containing the mimetype.
-- @param bytes String containing the bytes of the file.
-- @return a string containing the dataurl.
dataurl.create(mimetype, bytes)
```

```lua
-- example usage

local data = dataurl.create("text/plain", "my text here")

-- "data:text/plain;charset=utf-8;base64,bXkgdGV4dCBoZXJl"

```

[title] Manual de Instalação de um novo ambiente
[path] Untitled/Instalação/

## 1. Pré-requisitos

Antes de realizar a instalação de um ambiente, certifique-se de que os seguintes pré-requisitos estão atendidos:

- **Acesso VPN**: Caso necessário, para conectar ao cluster do ambiente que será disponibilizado o Citsmart Aura.
- **Cluster Kubernetes**: Um cluster Kubernetes em execução, que pode ser Minikube, GKE, EKS, ou qualquer outra solução Kubernetes compatível.
- **kubectl**: Ferramenta de linha de comando para interagir com o cluster Kubernetes, já configurada para acessar o cluster. Siga as instruções no [**site oficial do Kubernetes**](https://kubernetes.io/docs/tasks/tools/) para a instalação.
- **Banco de Dados**: PostgreSQL, no mínimo versão 16, com o usuário e banco de dados criados conforme a seção de configuração do banco de dados.
- **Domínio**: Necessário domínio personalizado configurado e disponibilizado.
- **CITSmart**:
  - front-manager: @0.34.0-2
  - backend: front-manager-api:2.10.2
  - lowcode: hyper-lowcode:1.8.6-RELEASE
  - citsmart: hyper-itsm-enterprise\:CitSmart-CitsmartX-1.7.0

## 2. Criação do Namespace para o Projeto

Antes de iniciar a implantação dos serviços, é necessário criar um namespace para o projeto. O namespace isola todos os recursos, facilitando o gerenciamento e a organização do ambiente.

### 2.1 Criando o Namespace

Para criar o namespace, utilize o comando abaixo.
**Substitua&#x20;**`aura-blocks`**&#x20;pelo nome desejado para o seu projeto, se preferir outro nome:**

```text
kubectl create namespace aura-blocks
```

Este comando criará o namespace chamado `aura-blocks`, onde todos os recursos do projeto serão implantados.

:::BlockQuote
**Nota:**
Ao longo deste manual, será utilizado o padrão `aura-blocks` para facilitar o acompanhamento dos exemplos. Caso você utilize um nome diferente, lembre-se de substituir `aura-blocks` em todos os comandos e exemplos apresentados.
:::

***

### 2.2 Especificando o Namespace nos Manifests

Nos arquivos de manifesto YAML referentes a recursos de namespace, como Deployment, Service, ConfigMap e similares, certifique-se de que todos os recursos possuem o campo `namespace` com o valor correto.
Exemplo esperado nos trechos de YAML:

```text
metadata:
  namespace: aura-blocks
```

Se tiver escolhido um nome diferente de namespace, substitua `aura-blocks` pelo nome utilizado em seu ambiente.

:::BlockQuote
**Importante:**
Sempre utilize o mesmo nome de namespace em todos os arquivos de recursos associados ao seu ambiente para garantir que todos os componentes funcionem corretamente.
:::

### Dica para Atualizar o Namespace nos Manifestos

Se optar por um nome de namespace diferente de `aura-blocks`, será necessário atualizar os arquivos de manifesto (`*.yaml`) para refletir esse novo nome.
Você pode automatizar essa tarefa antes de aplicar os manifests, executando o comando a seguir no diretório onde estão armazenados:

```text
NAMESPACE="seu-namespace-aqui" && find . -type f -name "*.yaml" -exec bash -c 'NS="$1"; sed -i"$([[ "$(uname)" == "Darwin" ]] && echo " ")" -E "s/^( *namespace:).*/\1 $NS/" "$2"' _ "$NAMESPACE" {} \;
```

Substitua `seu-namespace-aqui` pelo nome que escolheu para o namespace.

:::BlockQuote
**Atenção:**
Nem todos os recursos do Kubernetes utilizam o campo `namespace:` – por exemplo, arquivos de definição de `Namespace`, `PersistentVolume` e recursos do tipo `ClusterRole` não possuem esse campo ou são de escopo global. Sempre revise seus arquivos YAML, especialmente se estiver usando manifests que abrangem diferentes tipos de recurso.Para localizar rapidamente onde o campo aparece, use\:Após rodar o comando de substituição, é recomendável revisar os arquivos alterados antes de prosseguir com a aplicação.
:::

```text
grep -r 'namespace:' .
```

***

## 3. Configuração do Banco de Dados

Antes de prosseguir, crie o usuário e o banco de dados no PostgreSQL:

Substitua `<user>` e `<pass>` pelas informações necessarias para a criação do usuário.

```sql
CREATE USER <user> WITH PASSWORD '<pass>' CREATEDB LOGIN;
CREATE DATABASE aura_blocks OWNER <user>;
GRANT CREATE ON DATABASE aura_blocks TO <user>;
```

## 4. Obtendo manifestos

Os manifestos podem ser obtidos no arquivo [**aura-blocks-manifests.tar.bz2**](https://gitlab.centralit.io/aura/infra/kubernetes/-/raw/main/aura-blocks-manifests.tar.bz2) oferecidos junto ao presente manual.

```bash
tar -xf aura-blocks-manifests.tar.bz2
```

Caso queira, também é possível obter os manifestos originais no repositório oficial do projeto Citsmart Aura:

```bash
git clone http://gitlab.centralit.io/aura/infra/kubernetes.git
cd kubernetes/template
```

## 5. Estrutura dos Diretórios dos Manifestos

Abaixo está a estrutura dos diretórios dos manifestos.

```txt
.
├── attendant
│   ├── configmap.yaml
│   ├── deployment.yaml
│   ├── secret.yaml
│   └── service.yaml
├── dash
│   ├── configmap.yaml
│   ├── deployment.yaml
│   ├── secret.yaml
│   └── service.yaml
├── engine
│   ├── configmap.yaml
│   ├── deployment.yaml
│   ├── secret.yaml
│   └── service.yaml
├── ingress.yaml
├── lunaris
│   ├── deployment.yaml
│   └── service.yaml
├── persistentvolumeclaim.yaml
├── proactive
│   ├── configmap.yaml
│   ├── deployment.yaml
│   ├── secret.yaml
│   └── service.yaml
├── proxy
│   ├── configmap.yaml
│   ├── deployment.yaml
│   └── service.yaml
├── teams-server
│   ├── configmap.yaml
│   ├── deployment.yaml
│   └── service.yaml
├── wanderson
│   ├── configmap.yaml
│   ├── deployment.yaml
│   ├── secret.yaml
│   └── service.yaml
└── widget
    ├── configmap.yaml
    ├── deployment.yaml
    ├── secret.yaml
    └── service.yaml

10 directories, 34 files
```

## 6. Configuração dos Manifestos do Kubernetes

Nesta seção, detalharemos o que deve ser alterado em cada arquivo para configurar corretamente os serviços.

### 6.1 Configuração dos Volumes Persistentes (PVC)

Alguns serviços do projeto **Citsmart Aura**, como `lunaris`, `wanderson`, `dash`, `engine` e `widget` requerem armazenamento persistente de dados (ex: logs, workspaces). Para isso, utiliza-se um **PersistentVolumeClaim (PVC)** que reserva espaço de armazenamento no cluster Kubernetes.

O arquivo `persistentvolumeclaim.yaml` define a configuração desse volume compartilhado.

:::BlockQuote
⚠️ **Atenção:** Antes de aplicar o PVC no cluster, é necessário ajustar campos obrigatórios como o `storageClassName`, o tipo de acesso (`accessModes`) e o tamanho do volume (`storage`).
:::

***

### 6.1.1 persistentvolumeclaim.yaml

<table isTableHeaderOn="true" selectedColumns="" selectedRows="">
  <tr>
    <td align="left">
      <p>Campo</p>
    </td>
    <td align="left">
      <p>Descrição</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>storageClassName</code></p>
    </td>
    <td align="left">
      <p>Define a classe de armazenamento que será usada para provisionar o volume. Esse valor depende do provisionador instalado no cluster. Exemplos comuns: <code>"standard"</code>, <code>"nfs-client"</code>, <code>"balanced"</code>, <code>"ssd"</code>. Substitua <code>&#x3C;storageClassName></code> pelo nome correto de sua configuração.</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>accessModes</code></p>
    </td>
    <td align="left">
      <p>Define o modo de acesso ao volume. Neste caso, o valor <code>ReadWriteMany</code> permite que <strong>vários pods acessem o volume simultaneamente em leitura e escrita</strong> — necessário para serviços que compartilham espaço como <code>lunaris</code>, <code>wanderson</code>, <code>dash</code>, <code>engine</code> e <code>widget</code>. Verifique se seu <code>StorageClass</code> suporta esse modo.</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>resources.requests.storage</code></p>
    </td>
    <td align="left">
      <p>Define a capacidade mínima de armazenamento a ser reservada para o volume. O valor padrão é <code>50Gi</code>. <strong>Recomenda-se um mínimo de 20Gi</strong>, ajustável conforme o ambiente e carga esperada.</p>
    </td>
  </tr>
</table>

***

Exemplo com os ajustes recomendados:

```yaml
storageClassName: nfs-client
accessModes:
  - ReadWriteMany
resources:
  requests:
    storage: 50Gi
```

:::BlockQuote
📦 **Recomendação:** Para ambientes de produção ou homologação com múltiplos serviços, recomenda-se reservar ao menos **20Gi de espaço**, podendo ser ajustado conforme a necessidade (ex: `50Gi`, `100Gi`, etc.).
:::

***

Após os ajustes, aplique o PVC com o comando:

```bash
kubectl apply -f persistentvolumeclaim.yaml
```

:::BlockQuote
💡 Você pode verificar se o volume foi corretamente provisionado com:
:::

```bash
kubectl get pvc -n aura-blocks
```

### 6.2 Configuração da Engine

### 6.2.1 engine/configmap.yaml

O arquivo `engine/configmap.yaml` define variáveis de ambiente essenciais para o funcionamento do serviço **engine**, controlando desde as conexões com o banco de dados até rotas internas de API e autenticação.

Abaixo está a descrição detalhada de cada uma dessas variáveis:

<table isTableHeaderOn="true" selectedColumns="" selectedRows="">
  <tr>
    <td align="left">
      <p>Variável</p>
    </td>
    <td align="left">
      <p>Descrição</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>DB_TYPE</code></p>
    </td>
    <td align="left">
      <p>Define o tipo de banco de dados utilizado. Valor esperado: <code>postgres</code>.</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>DB_NAME</code></p>
    </td>
    <td align="left">
      <p>Nome do banco de dados utilizado pela aplicação (ex: <code>aura_blocks</code>).</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>DB_PORT</code></p>
    </td>
    <td align="left">
      <p>Porta de comunicação com o banco de dados (ex: <code>"5432"</code> para PostgreSQL).</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>DB_HOST</code></p>
    </td>
    <td align="left">
      <p>Hostname ou IP onde o banco de dados está hospedado. Substitua <code>&#x3C;db_host></code> conforme necessário.</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>DB_USER</code></p>
    </td>
    <td align="left">
      <p>Nome de usuário para autenticação no banco de dados. Substitua <code>&#x3C;db_user></code> conforme necessário.</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>HTTP_PORT</code></p>
    </td>
    <td align="left">
      <p>Porta HTTP onde o serviço engine será exposto internamente. Valor padrão: <code>"6060"</code>.</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>HTTP_BASE</code></p>
    </td>
    <td align="left">
      <p>Prefixo base da API da engine. Deve coincidir com a configuração do Ingress (ex: <code>"/engine/"</code>).</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>DOCS_PATH</code></p>
    </td>
    <td align="left">
      <p>Caminho relativo para acesso à documentação do Citsmart Aura (ex: <code>"/docs"</code>).</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>MANUALS_PATH</code></p>
    </td>
    <td align="left">
      <p>Caminho relativo para acesso a manuais do Citsmart Aura (ex: <code>"/manuals"</code>).</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>TESTS_PATH</code></p>
    </td>
    <td align="left">
      <p>Caminho relativo para acesso ao roteiro de testes Citsmart Aura (ex: <code>"/roteiro_testes"</code>).</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>BASIC_AUTH_USERNAME</code></p>
    </td>
    <td align="left">
      <p>Nome de usuário para autenticação básica na rota de documentação (<code>/docs</code>).</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>ATTACHMENT_PATH</code></p>
    </td>
    <td align="left">
      <p>Caminho interno relativo para armazenamento de anexos (ex: <code>"/engine/attachments"</code>).</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>LUNARIS_URL</code></p>
    </td>
    <td align="left">
      <p>Caminho interno relativo para integrar com o serviço Lunaris (ex: <code>"/lunaris"</code>).</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>FINAL_URL</code></p>
    </td>
    <td align="left">
      <p>URL pública final para acesso à engine (ex: <code>https://domain.com/engine/</code>).</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>USER</code></p>
    </td>
    <td align="left">
      <p>Usuário utilizado para autenticação da API. Valor padrão: <code>"lowcode"</code>.</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>KEYCLOAK_URL</code></p>
    </td>
    <td align="left">
      <p>URL para obtenção de informações de usuário via Keycloak. Essa URL inclui o <code>realm</code> e o caminho do endpoint <code>userinfo</code> do OpenID Connect.</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>DEFAULT_MANIFESTS</code></p>
    </td>
    <td align="left">
      <p>Lista padrão de manifestos (em JSON) a serem carregados pela engine ao iniciar. Cada item contém: Nome, URL do manifesto e tipo (<code>Talker</code>, <code>Broker</code>, <code>Event</code>, etc.). Abaixo está a estrutura completa:</p>
    </td>
  </tr>
</table>

```json
[
  ["Máquina de estados", "https://domain.com/wanderson/plugin/manifest", "Talker"],
  ["Questionários e ações", "https://domain.com/lunaris/.well-known/lunaris-configuration", "Talker"],
  ["Botmaker", "https://domain.com/lunaris/get/botmaker/manifest", "Broker"],
  ["Atendimento Humano", "https://domain.com/attendant/manifest", "Talker"],
  ["Gupshup", "https://domain.com/lunaris/get/gupshup/manifest", "Broker"],
  ["Messenger", "https://domain.com/lunaris/get/messenger/manifest", "Broker"],
  ["Positus", "https://domain.com/lunaris/get/positus/manifest", "Broker"],
  ["Slack", "https://domain.com/lunaris/get/slack/manifest", "Broker"],
  ["Teams", "https://domain.com/teams_server/manifest", "Broker"],
  ["Telegram", "https://domain.com/lunaris/get/telegram/manifest", "Broker"],
  ["Twilio", "https://domain.com/lunaris/get/twilio/manifest", "Broker"],
  ["Widget", "https://domain.com/widget/manifest", "Broker"],
  ["OIDC", "https://domain.com/lunaris/get/oidc/manifest", "Event"],
  ["UserInfo", "https://domain.com/lunaris/get/userinfo/manifest", "Userinfo"]
]
```

:::BlockQuote
⚠️ **Atenção**: Todos os valores com `https://domain.com` devem ser substituídos pelo domínio **real** onde a aplicação será instalada (ex: `https://meusistema.empresa.com.br`).
:::

### 6.2.2 engine/secret.yaml

Este arquivo contém variáveis sensíveis utilizadas pelo serviço **engine**. As informações estão codificadas em Base64 e não devem ser versionadas em repositórios públicos. As variáveis definidas são:

<table isTableHeaderOn="true" selectedColumns="" selectedRows="">
  <tr>
    <td align="left">
      <p>Variável</p>
    </td>
    <td align="left">
      <p>Descrição</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>DB_PASS</code></p>
    </td>
    <td align="left">
      <p>Senha de acesso ao banco de dados PostgreSQL utilizada pela aplicação.</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>BASIC_AUTH_PASSWORD</code></p>
    </td>
    <td align="left">
      <p>Senha para autenticação básica no acesso à rota <code>/docs</code> da documentação.</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>PASS</code></p>
    </td>
    <td align="left">
      <p>Senha utilizada para autenticação da API.</p>
    </td>
  </tr>
</table>

- Substitua senhas codificadas com:

```bash
echo -n 'minha_senha' | base64
```

:::BlockQuote
🔐 **Atenção:** Todos os valores estão codificados em Base64. Para editar ou revisar, utilize ferramentas para codificar/decodificar com segurança.Para ambientes sensíveis, considere usar `SealedSecrets` ou `SOPS`.
:::

### 6.2.3 engine/deployment.yaml

O `deployment.yaml` é responsável por definir o deployment do serviço `engine`. Certifique-se de que o **namespace** e as **imagens** do container estão corretas e que os **ConfigMaps** e **Secrets** estão sendo referenciados corretamente.

### 6.3 Configuração dos Outros Serviços

### 6.3.1 attendant

### attendant/configmap.yaml

O arquivo `attendant/configmap.yaml` define as variáveis de ambiente utilizadas pelo serviço **attendant**. Este item refere-se **exclusivamente** à configuração do `ConfigMap`. As variáveis disponíveis são:

<table isTableHeaderOn="true" selectedColumns="" selectedRows="">
  <tr>
    <td align="left">
      <p>Variável</p>
    </td>
    <td align="left">
      <p>Descrição</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>DB_TYPE</code></p>
    </td>
    <td align="left">
      <p>Tipo de banco de dados utilizado (ex: <code>postgres</code>).</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>DB_NAME</code></p>
    </td>
    <td align="left">
      <p>Nome do banco de dados acessado pela aplicação (ex: <code>aura_blocks</code>).</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>DB_PORT</code></p>
    </td>
    <td align="left">
      <p>Porta de comunicação com o banco de dados (ex: <code>"5432"</code> para PostgreSQL).</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>DB_HOST</code></p>
    </td>
    <td align="left">
      <p>Hostname ou serviço interno onde o banco de dados está acessível (ex: <code>postgresql</code>).</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>DB_USER</code></p>
    </td>
    <td align="left">
      <p>Usuário do banco de dados.</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>HTTP_PORT</code></p>
    </td>
    <td align="left">
      <p>Porta HTTP em que o serviço será exposto internamente (ex: <code>"6060"</code>).</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>HTTP_BASE</code></p>
    </td>
    <td align="left">
      <p>Caminho base da API do serviço <code>attendant</code>. Deve coincidir com a configuração do Ingress (ex: <code>"/attendant/"</code>).</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>ENGINE_URL</code></p>
    </td>
    <td align="left">
      <p>URL do serviço engine utilizado pelo <code>attendant</code> (ex: <code>"https://domain.com/engine/"</code>).</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>BASE_URL</code></p>
    </td>
    <td align="left">
      <p>URL base da aplicação (ex: <code>"https://domain.com"</code>).</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>AMBIENTE</code></p>
    </td>
    <td align="left">
      <p>URL base do Citsmart, onde será disponibilizada a aplicação. (ex: <code>"https://hml-cocriar.cithyper.click"</code>)</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>SLEEP_TIME</code></p>
    </td>
    <td align="left">
      <p>Intervalo (em segundos) para processamento das mensagens das filas de atendimento. Ex: <code>"120"</code> representa 2 minutos.</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>USER</code></p>
    </td>
    <td align="left">
      <p>Usuário utilizado para autenticação da API. Valor padrão: <code>"lowcode"</code>.</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>KEYCLOAK_URL</code></p>
    </td>
    <td align="left">
      <p>URL para obtenção de informações do usuário via Keycloak (OpenID Connect - endpoint <code>/userinfo</code>).</p>
    </td>
  </tr>
</table>

### attendant/secret.yaml

O arquivo `attendant/secret.yaml` armazena informações sensíveis utilizadas pelo serviço. Os dados estão codificados em Base64.

<table isTableHeaderOn="true" selectedColumns="" selectedRows="">
  <tr>
    <td align="left">
      <p>Variável</p>
    </td>
    <td align="left">
      <p>Descrição</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>PASS</code></p>
    </td>
    <td align="left">
      <p>Senha codificada em Base64 para autenticação da API.</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>DB_PASS</code></p>
    </td>
    <td align="left">
      <p>Senha do banco de dados associada ao usuário definido em <code>DB_USER</code>.</p>
    </td>
  </tr>
</table>

:::BlockQuote
🔐 **Atenção:** As informações armazenadas no `Secret` devem ser tratadas com confidencialidade. Evite exposição em logs ou repositórios.
:::

### 6.3.2 lunaris

### lunaris/deployment.yaml

O arquivo `lunaris/deployment.yaml` define o deployment do serviço **lunaris**. Um dos pontos mais importantes a ser ajustado está no campo `command`, que define os argumentos utilizados na inicialização do container.

<table isTableHeaderOn="true" selectedColumns="" selectedRows="">
  <tr>
    <td align="left">
      <p>Campo</p>
    </td>
    <td align="left">
      <p>Descrição</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>command</code></p>
    </td>
    <td align="left">
      <p>Define os parâmetros passados ao iniciar o serviço Lunaris. Os principais valores que precisam ser alterados são: </p>
      <p> - <code>-u</code> (<strong>URL pública do serviço Lunaris</strong>): deve ser substituída por uma URL válida do domínio onde o serviço será disponibilizado.
      - <code>-O</code> (<strong>URL do Keycloak para autenticação OpenID Connect</strong>): também precisa ser ajustada para refletir o domínio real do ambiente (incluindo o <code>realm</code>).</p>
    </td>
  </tr>
</table>

Exemplo original:

```bash
-u https://domain.com/lunaris
-O https://keycloak-domain.com/auth/realms/<realm>/protocol/openid-connect/userinfo
```

Exemplo com domínio ajustado:

```bash
-u https://aura-blocks.centralit.com.br/lunaris
-O https://hml-sso.cithyper.click/auth/realms/hml-cocriar/protocol/openid-connect/userinfo
```

:::BlockQuote
⚠️ **Atenção:** Substitua os valores `domain.com`, `keycloak-domain.com` e `<realm>` pelo domínio e realm reais utilizados no ambiente de homologação ou produção.
:::

### 6.3.3 wanderson

### wanderson/configmap.yaml

O arquivo `wanderson/configmap.yaml` define variáveis de ambiente utilizadas pelo serviço **wanderson**. Este item refere-se **exclusivamente** à configuração do `ConfigMap`.

<table isTableHeaderOn="true" selectedColumns="" selectedRows="">
  <tr>
    <td align="left">
      <p>Variável</p>
    </td>
    <td align="left">
      <p>Descrição</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>TZ</code></p>
    </td>
    <td align="left">
      <p>Define o fuso horário utilizado no container (ex: <code>"America/Sao_Paulo"</code>).</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>DATABASE_HOST</code></p>
    </td>
    <td align="left">
      <p>Hostname do banco de dados. Deve ser substituído por um valor real (ex: <code>postgresql</code>).</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>DATABASE_PORT</code></p>
    </td>
    <td align="left">
      <p>Porta para conexão com o banco de dados (ex: <code>"5432"</code>).</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>DATABASE_USERNAME</code></p>
    </td>
    <td align="left">
      <p>Nome do usuário de acesso ao banco de dados.</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>DATABASE_NAME</code></p>
    </td>
    <td align="left">
      <p>Nome do banco de dados utilizado (ex: <code>aura_blocks</code>).</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>DATABASE_MIN_POOL_SIZE</code></p>
    </td>
    <td align="left">
      <p>Tamanho mínimo do pool de conexões.</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>DATABASE_MAX_POOL_SIZE</code></p>
    </td>
    <td align="left">
      <p>Tamanho máximo do pool de conexões.</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>PORT</code></p>
    </td>
    <td align="left">
      <p>Porta interna utilizada pelo serviço (ex: <code>"80"</code>).</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>LOG_LEVELS</code></p>
    </td>
    <td align="left">
      <p>Níveis de log habilitados no serviço (ex: <code>'["error", "warn", "log", "debug"]'</code>).</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>CORS_ALLOWED_ORIGIN</code></p>
    </td>
    <td align="left">
      <p>Origem permitida para requisições CORS (ex: <code>"*"</code> permite todas).</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>CORS_ALLOWED_METHODS</code></p>
    </td>
    <td align="left">
      <p>Métodos HTTP permitidos via CORS (ex: <code>"*"</code>).</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>CORS_ALLOWED_HEADERS</code></p>
    </td>
    <td align="left">
      <p>Headers permitidos via CORS (ex: <code>"*"</code>).</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>CORS_ALLOW_CREDENTIALS</code></p>
    </td>
    <td align="left">
      <p>Habilita envio de cookies/autenticação via CORS (ex: <code>"true"</code>).</p>
    </td>
  </tr>
</table>

***

### wanderson/secret.yaml

O arquivo `wanderson/secret.yaml` armazena informações sensíveis utilizadas pelo serviço, codificadas em Base64.

<table isTableHeaderOn="true" selectedColumns="" selectedRows="">
  <tr>
    <td align="left">
      <p>Variável</p>
    </td>
    <td align="left">
      <p>Descrição</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>DATABASE_PASSWORD</code></p>
    </td>
    <td align="left">
      <p>Senha utilizada em conjunto com <code>DATABASE_USERNAME</code> para autenticação no banco de dados.</p>
    </td>
  </tr>
</table>

***

### wanderson/deployment.yaml

O arquivo `deployment.yaml` do serviço **wanderson** define diversos parâmetros do container, incluindo o campo `command`, que deve ser ajustado conforme o domínio do ambiente.

<table isTableHeaderOn="true" selectedColumns="" selectedRows="">
  <tr>
    <td align="left">
      <p>Parâmetro</p>
    </td>
    <td align="left">
      <p>Descrição</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>-O</code></p>
    </td>
    <td align="left">
      <p>Define a URL do endpoint <code>userinfo</code> do Keycloak para autenticação via OpenID Connect. Deve ser ajustada para refletir o domínio e o <code>realm</code> corretos do ambiente.</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>-u</code></p>
    </td>
    <td align="left">
      <p>Define a URL pública base do serviço <strong>wanderson</strong>. Essa URL deve corresponder à configuração de Ingress (por exemplo: <code>https://aura-blocks.centralit.com.br/wanderson/</code>).</p>
    </td>
  </tr>
</table>

### Exemplo original:

```bash
-O https://keycloak-domain.com/auth/realms/<realm>/protocol/openid-connect/userinfo
-u https://domain.com/wanderson/
```

Exemplo ajustado:

```bash
-O https://hml-sso.cithyper.click/auth/realms/hml-cocriar/protocol/openid-connect/userinfo
-u https://aura-blocks.centralit.com.br/wanderson/
```

:::BlockQuote
⚠️ **Atenção:** Ambos os valores — `-O` (Keycloak) e `-u` (URL pública) — devem ser substituídos pelo domínio real do ambiente em que o serviço será executado, respeitando o caminho do Ingress e o realm de autenticação.
:::

### 6.3.4 teams-server

### teams-server/configmap.yaml

O arquivo `teams-server/configmap.yaml` define variáveis de ambiente utilizadas pelo serviço **teams-server**. Este item refere-se **exclusivamente** à configuração do `ConfigMap`.

<table isTableHeaderOn="true" selectedColumns="" selectedRows="">
  <tr>
    <td align="left">
      <p>Variável</p>
    </td>
    <td align="left">
      <p>Descrição</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>HTTP_PORT</code></p>
    </td>
    <td align="left">
      <p>Porta HTTP utilizada internamente pelo serviço (ex.: <code>"6969"</code>).</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>BASE_URL</code></p>
    </td>
    <td align="left">
      <p>URL base pública da aplicação. <strong>Deve ser substituída pelo domínio real da aplicação</strong> (ex.: <code>"https://aura-blocks.centralit.com.br"</code>).</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>SUBPREFIX</code></p>
    </td>
    <td align="left">
      <p>Caminho base da rota do serviço no Ingress (ex.: <code>"/teams_server/"</code>).</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>URL_TO_ENGINE</code></p>
    </td>
    <td align="left">
      <p>Endpoint utilizado para repassar mensagens recebidas ao serviço <strong>engine</strong>. <strong>Substitua </strong><code>domain.com</code><strong> pela URL real do engine</strong> (ex.: <code>"https://aura-blocks.centralit.com.br/engine"</code>).</p>
    </td>
  </tr>
</table>

:::BlockQuote
⚠️ **Atenção:** Os valores que utilizam `domain.com` são placeholders e **devem ser substituídos** pelo domínio oficial da aplicação no ambiente de homologação ou produção.
:::

### 6.3.5 widget

### widget/configmap.yaml

O arquivo `widget/configmap.yaml` define as variáveis de ambiente utilizadas pelo serviço **widget**. Este item refere-se **exclusivamente** à configuração do `ConfigMap`.

<table isTableHeaderOn="true" selectedColumns="" selectedRows="">
  <tr>
    <td align="left">
      <p>Variável</p>
    </td>
    <td align="left">
      <p>Descrição</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>DB_TYPE</code></p>
    </td>
    <td align="left">
      <p>Tipo de banco de dados utilizado (ex: <code>postgres</code>).</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>DB_NAME</code></p>
    </td>
    <td align="left">
      <p>Nome do banco de dados utilizado pelo serviço (ex: <code>widget</code>).</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>DB_PORT</code></p>
    </td>
    <td align="left">
      <p>Porta utilizada para conexão com o banco de dados (ex: <code>"5432"</code>).</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>DB_HOST</code></p>
    </td>
    <td align="left">
      <p>Hostname do banco de dados. Deve ser substituído por um valor real.</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>DB_USER</code></p>
    </td>
    <td align="left">
      <p>Nome de usuário para autenticação no banco de dados.</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>HTTP_PORT</code></p>
    </td>
    <td align="left">
      <p>Porta HTTP onde o serviço será exposto internamente (ex: <code>"8989"</code>).</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>HTTP_BASE</code></p>
    </td>
    <td align="left">
      <p>Caminho base da API do widget (ex: <code>"/widget/"</code>). Deve coincidir com a configuração do Ingress.</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>BASE_URL</code></p>
    </td>
    <td align="left">
      <p>URL base da aplicação para chamadas HTTP. <strong>Substituir </strong><code>domain.com</code><strong> pelo domínio real do ambiente.</strong></p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>BASE_WEBSOCKET_URL</code></p>
    </td>
    <td align="left">
      <p>URL base para conexões WebSocket (ex: <code>"ws://domain.com"</code>). <strong>Substituir pelo domínio correto.</strong></p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>ENGINE_URL</code></p>
    </td>
    <td align="left">
      <p>URL do serviço engine para integração (ex: <code>"https://domain.com/engine"</code>).</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>ATTACHMENT_PATH</code></p>
    </td>
    <td align="left">
      <p>Caminho relativo para anexos enviados/recebidos (ex: <code>"/attachments"</code>).</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>DOCS_PATH</code></p>
    </td>
    <td align="left">
      <p>Caminho interno para a documentação (ex: <code>"../../docs/book"</code>).</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>REF_PATH</code></p>
    </td>
    <td align="left">
      <p>Caminho base para referências utilizadas pelo widget (ex: <code>"/ref/"</code>).</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>WIDGETS_PATH</code></p>
    </td>
    <td align="left">
      <p>Caminho para os recursos de widgets (ex: <code>"/widgets/"</code>).</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>USER</code></p>
    </td>
    <td align="left">
      <p>Nome de usuário utilizado internamente para autenticação da API (ex: <code>"lowcode"</code>).</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>TIME_KEEPALIVE</code></p>
    </td>
    <td align="left">
      <p>Tempo em segundos para envio do evento para manter a conexão ativa (ex: <code>"30"</code>).</p>
    </td>
  </tr>
</table>

:::BlockQuote
⚠️ **Atenção:** Todos os campos que contêm `domain.com` devem ser substituídos pelo domínio oficial da aplicação (HTTP e WebSocket).
:::

***

### widget/secret.yaml

O arquivo `widget/secret.yaml` armazena informações sensíveis utilizadas pelo serviço, codificadas em Base64.

<table isTableHeaderOn="true" selectedColumns="" selectedRows="">
  <tr>
    <td align="left">
      <p>Variável</p>
    </td>
    <td align="left">
      <p>Descrição</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>DB_PASS</code></p>
    </td>
    <td align="left">
      <p>Senha utilizada em conjunto com <code>DB_USER</code> para autenticação no banco de dados.</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>PASS</code></p>
    </td>
    <td align="left">
      <p>Senha codificada em Base64, utilizada para autenticação da API.</p>
    </td>
  </tr>
</table>

:::BlockQuote
🔐 **Atenção:** Nunca armazene os valores decodificados em repositórios. Manipule os segredos com segurança e mantenha-os restritos ao ambiente controlado.
:::

### 6.3.6 dash

### dash/configmap.yaml

O arquivo `dash/configmap.yaml` define as variáveis de ambiente utilizadas pelo serviço **dash**, responsável por relatórios e visualizações. Este item refere-se **exclusivamente** à configuração do `ConfigMap`.

<table isTableHeaderOn="true" selectedColumns="" selectedRows="">
  <tr>
    <td align="left">
      <p>Variável</p>
    </td>
    <td align="left">
      <p>Descrição</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>DB_TYPE</code></p>
    </td>
    <td align="left">
      <p>Tipo de banco de dados utilizado (ex: <code>postgres</code>).</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>DB_NAME</code></p>
    </td>
    <td align="left">
      <p>Nome do banco de dados acessado pela aplicação (ex: <code>aura_blocks</code>).</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>DB_PORT</code></p>
    </td>
    <td align="left">
      <p>Porta de conexão com o banco de dados (ex: <code>"5432"</code>).</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>DB_HOST</code></p>
    </td>
    <td align="left">
      <p>Hostname onde o banco de dados está disponível (ex: <code>postgresql</code>).</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>DB_USER</code></p>
    </td>
    <td align="left">
      <p>Nome do usuário utilizado na autenticação do banco.</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>HTTP_PORT</code></p>
    </td>
    <td align="left">
      <p>Porta onde o serviço será exposto internamente (ex: <code>"2610"</code>).</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>HTTP_BASE</code></p>
    </td>
    <td align="left">
      <p>Caminho base da API do serviço <code>dash</code> (ex: <code>"/dash/"</code>). Deve estar alinhado com a configuração do Ingress.</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>REPORTS_PATH</code></p>
    </td>
    <td align="left">
      <p>Caminho interno utilizado para armazenamento e acesso aos relatórios gerados (ex: <code>"/reports"</code>).</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>GIT_ENABLED</code></p>
    </td>
    <td align="left">
      <p>Define se a funcionalidade de integração com repositório Git está habilitada (<code>true</code> ou <code>false</code>). Quando habilitado, o serviço tentará sincronizar relatórios com o repositório definido.</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>GIT_REPO_URL</code></p>
    </td>
    <td align="left">
      <p>URL do repositório Git que será utilizado para armazenar e versionar os relatórios (ex: <code>https://gitlab.com/empresa/relatorios.git</code>).</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>GIT_BRANCH</code></p>
    </td>
    <td align="left">
      <p>Nome do branch padrão no repositório Git onde os relatórios serão sincronizados (ex: <code>main</code>).</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>GIT_USERNAME</code></p>
    </td>
    <td align="left">
      <p>Nome de usuário que será utilizado para autenticação no repositório Git.</p>
    </td>
  </tr>
</table>

***

### dash/secret.yaml

O arquivo `dash/secret.yaml` armazena informações sensíveis do serviço, codificadas em Base64.

<table isTableHeaderOn="true" selectedColumns="" selectedRows="">
  <tr>
    <td align="left">
      <p>Variável</p>
    </td>
    <td align="left">
      <p>Descrição</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>DB_PASS</code></p>
    </td>
    <td align="left">
      <p>Senha utilizada em conjunto com <code>DB_USER</code> para autenticação no banco de dados.</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>GIT_PASSWORD</code></p>
    </td>
    <td align="left">
      <p>Senha ou Personal Access Token (PAT) utilizado para autenticação no repositório Git. Devido à segurança, recomenda-se sempre utilizar PAT em vez de senha simples.</p>
    </td>
  </tr>
</table>

:::BlockQuote
🔐 **Atenção:** Os segredos devem ser tratados com segurança e não devem ser versionados em repositórios públicos.
:::

### 6.3.7 proactive

### proactive/configmap.yaml

O arquivo `proactive/configmap.yaml` define as variáveis de ambiente utilizadas pelo serviço **proactive**. Este item refere-se **exclusivamente** à configuração do `ConfigMap`.

<table isTableHeaderOn="true" selectedColumns="" selectedRows="">
  <tr>
    <td align="left">
      <p>Variável</p>
    </td>
    <td align="left">
      <p>Descrição</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>DB_TYPE</code></p>
    </td>
    <td align="left">
      <p>Tipo de banco de dados utilizado (ex: <code>postgres</code>).</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>DB_NAME</code></p>
    </td>
    <td align="left">
      <p>Nome do banco de dados utilizado pelo serviço (ex: <code>aura_blocks</code>).</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>DB_PORT</code></p>
    </td>
    <td align="left">
      <p>Porta utilizada para conexão com o banco de dados (ex: <code>"5432"</code>).</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>DB_HOST</code></p>
    </td>
    <td align="left">
      <p>Hostname do banco de dados. Deve ser substituído por um valor real.</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>DB_USER</code></p>
    </td>
    <td align="left">
      <p>Nome de usuário para autenticação no banco de dados.</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>HTTP_PORT</code></p>
    </td>
    <td align="left">
      <p>Porta HTTP onde o serviço será exposto internamente (ex: <code>"8989"</code>).</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>HTTP_BASE</code></p>
    </td>
    <td align="left">
      <p>Caminho base da API do proactive (ex: <code>"/proactive/"</code>). Deve coincidir com a configuração do Ingress.</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>HTTP_USER</code></p>
    </td>
    <td align="left">
      <p>Usuário utilizado para autenticação da API. Valor padrão: <code>"lowcode"</code>.</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>GUPSHUP_APIKEY</code></p>
    </td>
    <td align="left">
      <p>Chave da API da gupshup. <strong>Substituir o valor pela chave real do ambiente</strong></p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>GUPSHUP_APPID</code></p>
    </td>
    <td align="left">
      <p>ID do APP  da gupshup. <strong>Substituir o valor pela chave real do ambiente</strong></p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>GUPSHUP_SOURCE</code></p>
    </td>
    <td align="left">
      <p>Telefone vinculado ao workspace na gupshup. <strong>Substituir o valor pela chave real do ambiente</strong></p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>GUPSHUP_SRC_NAME</code></p>
    </td>
    <td align="left">
      <p>Workspace na gupshup. <strong>Substituir o valor pela chave real do ambiente</strong></p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>KEYCLOAK_URL</code></p>
    </td>
    <td align="left">
      <p>URL para obtenção de informações de usuário via Keycloak. Essa URL inclui o realm e o caminho do endpoint userinfo do OpenID Connect.</p>
    </td>
  </tr>
</table>

### proactive/secret.yaml

O arquivo `proactive/secret.yaml` armazena informações sensíveis utilizadas pelo serviço, codificadas em Base64.

<table isTableHeaderOn="true" selectedColumns="" selectedRows="">
  <tr>
    <td align="left">
      <p>Variável</p>
    </td>
    <td align="left">
      <p>Descrição</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>DB_PASS</code></p>
    </td>
    <td align="left">
      <p>Senha utilizada em conjunto com <code>DB_USER</code> para autenticação no banco de dados.</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>HTTP_PASS</code></p>
    </td>
    <td align="left">
      <p>Senha codificada em Base64, utilizada para autenticação da API.</p>
    </td>
  </tr>
</table>

:::BlockQuote
🔐 **Atenção:** Nunca armazene os valores decodificados em repositórios. Manipule os segredos com segurança e mantenha-os restritos ao ambiente controlado.
:::

### 6.3.8 pgadmin

### pgadmin/configmap.yaml

O arquivo `pgadmin/configmap.yaml` define as variáveis de ambiente utilizadas pelo serviço **pgAdmin**, responsável por oferecer uma interface gráfica para administração do banco de dados PostgreSQL.

<table isTableHeaderOn="true" selectedColumns="" selectedRows="">
  <tr>
    <td align="left">
      <p>Variável</p>
    </td>
    <td align="left">
      <p>Descrição</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>TZ</code></p>
    </td>
    <td align="left">
      <p>Fuso horário do container. Exemplo: <code>"America/Sao_Paulo"</code>.</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>SCRIPT_NAME</code></p>
    </td>
    <td align="left">
      <p>Caminho base opcional (prefixo) da aplicação no Ingress. Exemplo: <code>"/pgadmin"</code>.</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>PGADMIN_DEFAULT_EMAIL</code></p>
    </td>
    <td align="left">
      <p>E-mail do usuário administrador criado automaticamente no primeiro acesso. Exemplo: <code>"admin@empresa.com"</code>.</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>MAX_LOGIN_ATTEMPTS</code></p>
    </td>
    <td align="left">
      <p>Número máximo de tentativas de login antes do bloqueio do usuário. Padrão: <code>3</code>.</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>PGADMIN_LISTEN_ADDRESS</code></p>
    </td>
    <td align="left">
      <p>Endereço de rede no qual o pgAdmin vai escutar. Normalmente <code>0.0.0.0</code> para aceitar todas as conexões.</p>
    </td>
  </tr>
</table>

***

### pgadmin/secret.yaml

O arquivo `pgadmin/secret.yaml` armazena informações sensíveis utilizadas pelo serviço, codificadas em Base64.

<table isTableHeaderOn="true" selectedColumns="" selectedRows="">
  <tr>
    <td align="left">
      <p>Variável</p>
    </td>
    <td align="left">
      <p>Descrição</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>PGADMIN_DEFAULT_PASSWORD</code></p>
    </td>
    <td align="left">
      <p>Senha associada ao <code>PGADMIN_DEFAULT_EMAIL</code> para acesso à interface do pgAdmin.</p>
    </td>
  </tr>
</table>

### 6.4 Configuração do Ingress

O arquivo `ingress.yaml` define as regras de roteamento HTTP externo para os serviços do projeto **aura-blocks**, utilizando um Ingress Controller como Traefik ou NGINX. Ele garante que cada caminho (`/engine`, `/widget`, etc.) seja corretamente encaminhado para o serviço correspondente dentro do cluster.

:::BlockQuote
⚠️ **Atenção:** Esse arquivo exige configurações obrigatórias para funcionar corretamente em cada ambiente. A seguir, estão os campos que **devem ser ajustados**:
:::

***

### 6.4.1 ingress.yaml

<table isTableHeaderOn="true" selectedColumns="" selectedRows="">
  <tr>
    <td align="left">
      <p>Campo</p>
    </td>
    <td align="left">
      <p>Descrição</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>ingressClassName</code></p>
    </td>
    <td align="left">
      <p>Define qual controlador de Ingress será responsável por gerenciar as regras. Deve ser substituído por um valor existente no cluster (ex: <code>"traefik"</code> ou <code>"nginx"</code>).</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>host</code></p>
    </td>
    <td align="left">
      <p>Nome do domínio público onde os serviços serão acessados. Substitua <code>domain.com</code> pelo domínio real da aplicação (ex: <code>aura-blocks.centralit.com.br</code>).</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>paths</code></p>
    </td>
    <td align="left">
      <p>Cada caminho HTTP (<code>/engine</code>, <code>/widget</code>, etc.) é roteado para o respectivo serviço Kubernetes com sua porta correspondente. Esses caminhos devem estar alinhados com os valores de <code>HTTP_BASE</code> definidos nos <code>ConfigMaps</code>.</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>tls.secretName</code></p>
    </td>
    <td align="left">
      <p>Nome do <code>Secret</code> que contém o certificado TLS para habilitar HTTPS. O segredo deve estar criado no namespace <code>aura-blocks</code>, com o nome correspondente ao domínio utilizado. Por exemplo: <code>aura-blocks-centralit-tls</code>.</p>
    </td>
  </tr>
  <tr>
    <td align="left">
      <p><code>tls.hosts</code></p>
    </td>
    <td align="left">
      <p>Lista de domínios que serão protegidos via HTTPS. Deve corresponder ao domínio configurado no campo <code>host</code>.</p>
    </td>
  </tr>
</table>

***

Exemplo de valores substituídos corretamente:

```yaml
...
ingressClassName: traefik
rules:
- host: aura-blocks.centralit.com.br
...
tls:
  - secretName: aura-blocks-centralit-tls
    hosts:
      - aura-blocks.centralit.com.br
```

:::BlockQuote
🔐 **Importante:** Certifique-se de que o `Secret` de TLS já exista no namespace `aura-blocks`, e que tenha sido criado a partir de um certificado válido para o domínio desejado. Isso é essencial para permitir a navegação segura via HTTPS.
:::

***

Após realizar os ajustes necessários, aplique o Ingress com o comando:

```bash
kubectl apply -f ingress.yaml
```

## 7. Deployment do Ambiente

Com todas as configurações ajustadas, você pode aplicar os manifestos ao cluster. Navegue até o diretório correto e execute o seguinte comando:

```bash
kubectl apply -f <CAMINHO_DO_MANIFESTO_MODIFICADO>
```

### 7.1 Aplicando os Manifests de Kubernetes

Agora, aplique os manifestos ao cluster. Repita os seguintes comandos para cada serviço:

### 7.1.1 engine

```bash
kubectl apply -f engine/configmap.yaml
kubectl apply -f engine/secret.yaml
kubectl apply -f engine/deployment.yaml
kubectl apply -f engine/service.yaml
```

### 7.1.2 attendant

```bash
kubectl apply -f attendant/configmap.yaml
kubectl apply -f attendant/secret.yaml
kubectl apply -f attendant/deployment.yaml
kubectl apply -f attendant/service.yaml
```

### 7.1.3 lunaris

```bash
kubectl apply -f lunaris/deployment.yaml
kubectl apply -f lunaris/service.yaml
```

### 7.1.4 wanderson

```bash
kubectl apply -f wanderson/configmap.yaml
kubectl apply -f wanderson/secret.yaml
kubectl apply -f wanderson/deployment.yaml
kubectl apply -f wanderson/service.yaml
```

### 7.1.5 teams-server

```bash
kubectl apply -f teams-server/configmap.yaml
kubectl apply -f teams-server/deployment.yaml
kubectl apply -f teams-server/service.yaml
```

### 7.1.6 widget

```bash
kubectl apply -f widget/configmap.yaml
kubectl apply -f widget/secret.yaml
kubectl apply -f widget/deployment.yaml
kubectl apply -f widget/service.yaml
```

### 7.1.7 dash

```bash
kubectl apply -f dash/configmap.yaml
kubectl apply -f dash/secret.yaml
kubectl apply -f dash/deployment.yaml
kubectl apply -f dash/service.yaml
```

### 7.1.8 proactive

```bash
kubectl apply -f proactive/configmap.yaml
kubectl apply -f proactive/secret.yaml
kubectl apply -f proactive/deployment.yaml
kubectl apply -f proactive/service.yaml
```

### 7.1.9 pgadmin

```bash
kubectl apply -f pgadmin/configmap.yaml
kubectl apply -f pgadmin/secret.yaml
kubectl apply -f pgadmin/deployment.yaml
kubectl apply -f pgadmin/service.yaml
```

## 8. Verificação do Deployment

Após aplicar todos os manifests, é essencial validar se os recursos foram criados corretamente e estão funcionando como esperado.

### 8.1 Verificar Recursos Criados no Namespace

```bash
kubectl get all -n aura-blocks
```

- Lista **pods**, **services**, **deployments**, **replicasets**, etc.
- Confirme se **todos os pods estão com STATUS&#x20;**`Running`**&#x20;ou&#x20;**`Completed` e **READY como&#x20;**`1/1`**&#x20;ou&#x20;**`x/x`.

***

### 8.2 Verificar Eventos e Condições de Falha

```bash
kubectl get events -n aura-blocks --sort-by=.metadata.creationTimestamp
```

- Mostra **eventos recentes**, como falhas de agendamento, erro de imagem, problemas com PVC, etc.
- Use este comando para **debug de erros de criação**.

***

### 8.3 Diagnóstico de um Pod Específico

```bash
kubectl describe pod <nome-do-pod> -n aura-blocks
```

:::BlockQuote
Para listar os nomes dos pods:
:::

```bash
kubectl get pods -n aura-blocks
```

***

### 8.4 Verificar o Ingress

```bash
kubectl describe ingress -n aura-blocks
```

- Valida se o Ingress está roteando corretamente os caminhos (`/engine`, `/widget`, etc).
- Verifique:
  - `Address`: IP externo ou LoadBalancer configurado
  - `Rules`: correspondem aos paths e hosts definidos
  - `TLS`: status do certificado

***

### 8.5 Validar a URL Pública dos Serviços

```bash
curl -I https://aura-blocks.centralit.com.br/engine/manuals/
```

- Verifica se o serviço `engine` está **acessível via HTTPS**.

***

### 8.6 Verificar Logs dos Pods

### Engine:

```bash
kubectl logs -l app=engine -n aura-blocks --tail=100
```

### Lunaris:

```bash
kubectl logs -l app=lunaris -n aura-blocks --tail=100
```

***

### 8.7 Verificar Volume Persistente

```bash
kubectl get pvc -n aura-blocks
kubectl describe pvc <nome-do-pvc> -n aura-blocks
```

***

### 8.8 Consultar Variáveis de Ambiente do Pod

```bash
kubectl exec -it <nome-do-pod> -n aura-blocks -- printenv
```

***

### 8.9 Verificar Readiness de Todos os Pods

```bash
kubectl get pods -n aura-blocks -o custom-columns="POD:metadata.name,STATUS:status.phase,READY:status.conditions[?(@.type=='Ready')].status"
```


[title] Facebook Messenger
[path] Untitled/Brokers/

A criação de um webhook para o Messenger do Facebook exige que se tenha um portfólio empresarial e uma página relacionada a este portfólio.

Feito isso, segue o padrão de cadastrar webhook para recebimento de mensagens e receber um token para envio de mensagens. O identificador principal do facebook também será necessário para	 cadastro do Broker.

**Nota**: ***É obrigatório que primeiro cadastre os dados na AURA BLOCKS para que depois configure o webhook do passo 6.***

### 1. Criar uma conta

Através do link abaixo, se inscreva no Facebook pessoal.

[**link de acesso**](https://www.facebook.com/?locale=pt_BR)

### 2. Criar um portfólio empresarial

[**facebook business**](https://business.facebook.com/business/loginpage/?next=https%3A%2F%2Fbusiness.facebook.com%2F%3Fnav_ref%3Dbiz_unified_f3_login_page_to_mbs\&login_options%5B0%5D=FB\&login_options%5B1%5D=IG\&login_options%5B2%5D=SSO\&config_ref=biz_login_tool_flavor_mbs)

No facebook business, crie um portfólio empresarial.

![portifolio](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/qEQEx37FEi8eGhAHqKHRw_messengerportifolio.png)

### 3. Criar uma página

[**link página**](https://pt-br.facebook.com/pages/create)

Dentro do Facebook crie uma página, é por lá que usuários externos poderão mandar mensagem para o bot.
Volte ao Facebook Business para vincular a página criada.

![link página](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/9Ox0E7OGWyBkWYDM6qc_A_messengerpagina.png)

### 4. Criar aplicativo no Facebook Developer

[**link developers**](https://developers.facebook.com/?locale=pt_BR)

O aplicativo serve para usar e configurar ferramentas da API do Facebook. No processo de criação, o primeiro passo é escolher o portfólio empresarial criado, isso garante que mais recursos da api do facebook estarão disponíveis; no segundo passo, sobre função do aplicativo, escolher pela opção "Outro"; por último, o tipo de aplicativo é "Empresa".

![aplicativo](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/znU6WZxhX4RidXlzohAXZ_messengeraplicativo.png)

### 5. Acessar a configuração do Messenger

Na imagem abaixo, acesse para configurar o Messenger.

Na aba de Configurações do app > Básico, encontra-se a Chave Secreta do Aplicativo, esta é **Chave Secreta**.

![configurar](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/H1KTF1a3-zx9pt3YvGFp3_messengerconfigurar.png)

### 6. Configurar webhook e eventos

Guarde o **Facebook ID** que se encontra na página, no caso seria o 371902382669056 conforme mostrado na imagem.

Nessa página de configuração, primeiro insira a url do webhook com endereço **https\://\{endereço\_do\_lunaris}/all/messenger/webhook?facebook\_id=\{id\_facebook}**, o id\_facebook é o Facebook ID. Nesta página, pede um Token de Webhook, este tem que ser o igual cadastrado na plataforma AURA BLOCKS chamado de **Código de Segurança**.

Depois gere Token de Acesso pela página criada e também assine o evento de "messages".Esse token será utilizado para enviar mensagens do broker para o usuário. O link de envio tem uma parte fixa: [**https://graph.facebook.com/v12.0/me/messages?access\_token=**](https://graph.facebook.com/v12.0/me/messages?access_token=)" seguida do **Token** obtido. Nessa parte, assine alguns eventos do webhook, por exemplo 'messages'.

Na mesma página, peça solicitação do 'pages\_messaging'. A resposta por parte do facebook pode durar mais de um dia.

![webhook](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/UHz5rVgBHLCSpVLXYMPfA_messengerwebhook.png)

[title] Papéis
[path] Untitled/Início/

- **Usuário final**: Usuário que conversa com o sistema por meio de um canal de acesso.
- **aura\_attendant**: Usuário com as permissões necessárias para responder ao usuário final
  por meio do respectivo canal de acesso.
- **aura\_supervisor**: Usuário com permissões para acessar relatórios e associar usuários
  a filas de atendimento.
- **aura\_developer**: Usuário com as habilidades e permissões necessárias para criar,
  customizar e configurar fluxos conversacionais.

:::BlockQuote
Usuários podem desempenhar mais de um papel conforme as necessidades específicas
do negócio. Ex: Um supervisor pode ser cadastrado para fazer atendimentos como
um atendente.
:::

# Permissões

**Chatbots** (aura\_developer, aura\_supervisor)

- comportamentos (aura\_developer)
- dashboard (aura\_supervisor)
- histórico (aura\_supervisor)
- remover (aura\_developer)
- novo (aura\_developer)

**Disparo** (aura\_supervisor)

- Templates (aura\_supervisor)
- Envios (aura\_supervisor)
- Contatos (aura\_supervisor)

**Atendimento Humano** (aura\_supervisor, aura\_attendant)

- Atendimento (aura\_attendant)
- Filas (aura\_supervisor)
- Atalhos de Texto (aura\_supervisor, aura\_attendant)
  - Atalhos Globais (aura\_supervisor)
  - Atalhos Privados (aura\_attendant)

**Máquina de estados** (aura\_developer)

**Widgets** (aura\_developer)

**Questionários e Ações** (aura\_developer)

**Ajuda** (Todos)

**Sobre** (Todos)

[title] Positus
[path] Untitled/


[title] Key
[path] Untitled/Customizações Avançadas/Bibliotecas/

Utilizado para guardar valores em memória para utilização em runtime.

## Atalhos

- [**Key**](docId:9IOuLZwnuOtFEhLpN5aep)
- [**Key**](docId:9IOuLZwnuOtFEhLpN5aep)
- [**Key**](docId:9IOuLZwnuOtFEhLpN5aep)

***

### Métodos

### Get

```lua
-- @param name The name of the key storaged
-- @return the value associated with the key or an empty string if the key does not exists 
get_key(name)
```

```lua
-- example usage:

local my_value = get_key("my_key")
```

### Set

```lua
-- @param key The key name to be storaged
-- @param value The value to be storaged
set_key(key, value)
```

```lua
-- example usage:

set_key("my_key", 123)
```

### Remove

```lua
-- @param name The name of the key to be removed
-- @return the value the value that was removed or an empty string if the key does not exists 
remove_key(name)
```

```lua
-- example usage:

local removed_value = remove_key("my_key")
```


[title] Untitled
[path] Untitled/


[title] Permissões de rede
[path] Untitled/Início/

No diagrama abaixo, apresentamos os componentes da solução. Cada um deles
pode requerer permissões de rede adicionais para que suas funcionalidades
sejam plenamente habilitadas.

```mermaid
flowchart TD

  subgraph rede_interna
    subgraph aura
      engine -. talk_spec .-> broker
      engine -. broker_spec .-> talker
      engine -. sql .-> postgres
    end 

    engine -. http .-> citsmart
    broker <-. http+websocket .-> widget
    talker <-. http+webhook .-> integrações_internas
  end 

  subgraph provedores
    whatsapp
    telegram
    teams
  end

  broker <-. http+webhook .-> provedores
```

- **Aura**: É o componente central do chat e requer permissões de rede
  interna para ser acessado pelo ambiente low-code do Citsmart.
- **Citsmart**: Deve estar acessível pela Aura na rede interna, permitindo que
  a Aura possa abrir chamados e executar outras integrações.
- **Widget**: Deve estar disponível na rede interna para que os usuários
  internos possam se comunicar com o chat.
- **Integrações Internas**: A Aura precisa de permissões de rede para
  acessar sistemas internos que o negócio identificar como necessários para
  integração.
- **Provedores**: Provedores como WhatsApp, Telegram, Microsoft Teams e Slack
  requerem que a Aura esteja exposta à internet para que possam estabelecer
  conexões com o webhook e notificar sobre novas mensagens enviadas pelos
  usuários. Esses provedores também exigem que a Aura tenha permissões para
  realizar requisições à internet, permitindo que o chat informe os usuários
  sobre novas mensagens.

:::BlockQuote
Os sistemas da rede interna podem ser expostos à internet conforme as
necessidades específicas do negócio. Exemplo: para que o widget esteja
acessível em um site público, é  necessário que o componente Aura esteja
exposto.
:::


[title] Manual de Criação e Adição de Menus
[path] Untitled/Instalação/

Este documento tem como finalidade servir como um guia prático e objetivo para a criação, configuração e adição de menus

:::BlockQuote
Esta funcionalidade está disponível apenas para o papel de **Desenvolvedor**.
:::

Geralmente, a **URL do Citsmart** instalada no OCI está localizada no repositório GitLab da equipe. Entretanto, em algumas situações, pode não estar disponível. Por isso, antes de cadastrar os menus, certifique-se de ter as seguintes informações:

1 - URL do Citsmart
2 - Perfil de administrador
3 - Valor da senha da engine

Caso não possua algum desses **itens obrigatórios**, solicite à equipe de infraestrutura.

***

*Este manual está dividido em seções para facilitar a localização das informações. As seções são:*

[**Cadastrar e Configurar uma Aplicação**]() 🔹
Antes de criar menus, você precisa cadastrar e configurar uma aplicação. Se ainda não tem uma, este é o seu primeiro passo.

[**Manual de Criação e Adição de Menus**](docId\:cYLfKEuq2Ys_ofV2-yG3R) 🔹
Se você já configurou sua aplicação, aqui é ensinado como criar os menus.

[**Manual de Criação e Adição de Menus**](docId\:cYLfKEuq2Ys_ofV2-yG3R) 🔹
Aprenda como exportar e importar pacotes para otimizar a configuração da sua aplicação e agilizar o processo de replicação de menus e dados entre ambientes.

[**Manual de Criação e Adição de Menus**](docId\:cYLfKEuq2Ys_ofV2-yG3R) 🔹
Em alguns ambientes, o Front Manager pode estar com versões antigas. Essa seção mostra como proceder nesses casos específicos.

***

## Criar uma aplicação

1. No menu lateral, acesse **Administração da Hyper Platform > Aplicações**.

![Menu Aplicações](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/x22Z_cGV5-2TOS0gKxVYe_menusaplicacoes.png)

1. Na aba, selecione a opção **Criar**.
   ![Criar Nova Aplicações](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/VI1qW5bkb-jK2br_4roUU_menusaplicacoescriar.png)
2. Preencha o formulário
   - **Nome:** `@hyper/<Nome da sua aplicação>`
   - **Descrição:** `<Descrição da sua aplicação>`
   - **Situação:** `Ativa`
   - **Renderizar:** `Legado - Iframe`
   - **Tipo:** `Gerenciada pela plataforma`
   - **Ícone:** `Ícone no formato PNG ou SVG`

![Criar Aplicações](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/kwmmWXAVNRmxedmYu9pDt_menusaplicacoesform.png)

1. Novamente no menu lateral, acesse **Administração da Hyper Platform > Versão (das Aplicações)**
   ![Versões da nova Aplicação](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/SpAhDy7nuZ8o9LfYFWdO4_menusversoes.png)
2. Na página, localize sua aplicação pelo **Nome** e, em seguida, na coluna **Ações**, clique no ícone de edição.
   ![Versões da nova Aplicação](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/XglSEQ7XKTveVRBBjzaN7_menusversoeseditar.png)
3. Clique em **Adicionar**.
   ![Versões da nova Aplicação](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/HD308GvZsdO99epASbJxG_menusversoeseditaradicionar.png)
4. Preencha o formulário.
   :::BlockQuote
   O modelo a seguir apresenta um exemplo de aplicação criada com base na estrutura padrão utilizada pela equipe **Citsmart Aura**. Para personalizações adicionais, entre em contato com um supervisor ou consulte a documentação oficial da plataforma.
   :::
   Modelo base:

   Os campos **Maior**, **Menor**, **Correção** e **Revisão** compõem, em conjunto, a versão. Por exemplo: ao inserir os valores 1, 2, 4 e 6, a versão resultante será **1.2.4.6**.

   O campo Nome da Base corresponde ao segmento que aparece após a URL padrão do Citsmart. Assim, em uma URL fictícia, seria representado como: `http://url-exemplo.citsmart/<nome-da-base>`

   Após concluir o preenchimento clique em **"Gravar"**, tanto no formulário quanto na tela de Versão (das Aplicações).
   ![Versões da nova Aplicação](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/iHs8SM6O3LD-LWqhOPcqZ_menusversoesform.png)
   ![Versões da nova Aplicação Segunda confirmação](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/mXOUl1Yzbr1LPaZf1NH7M_menusversoesform2.png)
5. Mais uma vez no menu lateral, acesse **Administração da Hyper Platform > Licenças de Aplicações/Versões**.
   ![Licenças da nova Aplicação](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/kOD8_Zuu4xUZNyYN8S7q2_menuslicencas.png)
6. Clique em **Criar**.
   ![Licenças da nova Aplicação](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/v_jCnaLi3HQqQQwkmSMB8_menuslicencascriar.png)
7. Preencha o formulário de licença seguindo o modelo abaixo:
   :::BlockQuote
   O modelo a seguir apresenta um exemplo de aplicação criada com base na estrutura padrão utilizada pela equipe **Citsmart Aura**. Para personalizações adicionais, entre em contato com um supervisor ou consulte a documentação oficial da plataforma.
   :::
   Após concluir o preenchimento clique em **"Gravar"**.
   ![Licenças da nova Aplicação](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/oeZ0KfMwg-CyEJf3Py869_menuslicencasform.png)

***

## Criar Menus

1. No menu lateral, acesse **Administração da Hyper Platform > Menu Manutenção de Itens**
   :::BlockQuote
   Caso esteja utilizando uma versão antiga do Front Manager, siga esta [**Manual de Criação e Adição de Menus**](docId\:cYLfKEuq2Ys_ofV2-yG3R).
   :::
   ![Manutenção de Itens](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/MFsT7IXKAwZbfByGFEb6F_menusitens.png)
2. Clique em **Criar**.
   ![Manutenção de Itens](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/1Fk46D-E6GZB0VYrjPPpw_menusitenscriar.png)
3. Preencha o formulário.
   :::BlockQuote
   Os exemplos a seguir abrangem a criação de todos os menus utilizados pela equipe Citsmart Aura. Caso sejam necessárias alterações, utilize o modelo como referência, ajustando apenas os campos que deseja personalizar.
   :::
   A imagem a seguir apresenta o formulário que deve ser preenchido para adicionar o menu, utilizando parâmetros de exemplo. Substitua esses parâmetros pelos exemplos indicados logo após a imagem. Ao final de cada modelo, clique no botão **Gravar** e, em seguida, em **Criar** para adicionar o próximo item.
   ![Manutenção de Itens](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/A3HBavMOurPfxDERoYQRz_menusitensform.png)
   [**Base**]() | [**Comportamentos**]() | [**Atendimento Humano**]() | [**Máquina de Estados**]() | [**Widgets**]() | [**Atendimentos**]() | [**Filas**]() | [**Atalhos de Texto**]() | [**Atalhos Globais**]() | [**Atalhos Privados**]() | [**Questionários e Ações**]() | [**Ajuda**]() | [**Sobre**]()
4. No menu lateral, acesse **Administração da Hyper Platform > Menu (Associar Roles)**.
   ![Associar Roles de App](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/QzyxW-uNTLjMfAZPJjKKR_menusassociarroles.png)
5. Na coluna **Ações**, clique no ícone para editar no cliente desejado.
   ![Associar Roles de App](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/cDlyo1YQruR-I77Wc0M1w_menusassociarroleseditar.png)
6. Preencha o formulário usando o modelo abaixo

   Todos os Itens de Menu do Role devem ser selecionados e associados. Para isso, selecione o item desejado e, em seguida, clique em **Associar**.
   ![Associar Roles de App](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/-RKAFooruj3Yhyzhsu9Xs_menusassociarrolesform.png)
   ![Associar Roles de App](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/R2ex57N3nNP0TTlFD7Miz_menusassociarrolescomport.png)
   ![Associar Roles de App](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/MlvUUiP4MBM97YXIRhwPJ_menusassociarrolesatend.png)
   ![Associar Roles de App](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/Zi3-ULX17lLmoI1xLqmhR_menusassociarroleswand.png)
   ![Associar Roles de App](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/3hQJ-xgf_BeFlbGpFTofS_menusassociarroleswidgets.png)
   Após associar todos os itens, clique em **Gravar**.
7. Por fim, no menu lateral, acesse **Administração da Hyper Platform > Menu (Associar Versão de App)**.
   ![Associar Versão de App](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/9VEO1lodecwIn0tY6BCsT_menusassociar.png)
8. Dentro da página, pesquise por **aura** e na coluna **Ações**, clique no ícone para editar.
   ![Associar Versão de App](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/gGgvxP2q6rpFn4Gqk9AqE_menusassociareditar.png)
9. Marque a versão e o item de menu desejado e clique em **“Associar”**. Caso seja necessário associar outros itens, repita o procedimento.
   ![Associar Versão de App](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/abmIlghThh_tEPZHSxM-i_menusassociaritens.png)
   Após concluir, clique no botão **“Gravar”** para salvar as alterações.

***

## Importar e Exportar pacotes

[**Manual de Criação e Adição de Menus**](docId\:cYLfKEuq2Ys_ofV2-yG3R) | [**Manual de Criação e Adição de Menus**](docId\:cYLfKEuq2Ys_ofV2-yG3R)

### Exportar

1. Em um ambiente **Citsmart** já configurado, acesse o menu lateral: **Lowcode > Pacote**.

![Menu de Pacotes](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/q3-kXOM0eLnvHNHVcoL6l_menupacote.png)

1. Localize o pacote que deseja exportar (geralmente o mais recente ou uma versão estável) e clique no botão **“Exportar”**.

![Exportar pacote](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/qmwD1afUcZ7rAD9tGkh45_exportexample.png)

:::BlockQuote
Um pacote compactado (`.zip`) será baixado e poderá ser utilizado em importações futuras.
:::

***

### Importar

1. No ambiente **Citsmart** em que deseja realizar a importação, acesse o menu lateral: **Lowcode > Pacote**.

![Menu de Pacotes](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/q3-kXOM0eLnvHNHVcoL6l_menupacote.png)

1. Clique no botão **“Importar”**.

![Botão Importar](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/CyeeAuKBIYKSS25vZbDk0_menuimportbutton.png)

1. Selecione o arquivo `.json` e clique em **Importar**.

:::BlockQuote
Para obter o arquivo `.json` de uma exportação, é necessário extrair o conteúdo do arquivo `.zip`.Em sistemas Windows, clique com o botão direito sobre o arquivo compactado e selecione a opção **“Extrair tudo...”**.
Após a extração, localize o arquivo `.json` dentro da pasta descompactada.Este arquivo é o que deve ser utilizado no processo de importação.
:::

![Importar JSON](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/8avdb3Rh0hyIbhT8B96dO_menusimportjsonexample.png)

1. Após selecionar o arquivo, confirme a importação acessando: **menu lateral > menu da sua aplicação**.

:::BlockQuote
**Atenção:** verifique se todos os menus estão funcionando corretamente e se apontam para os locais desejados.
:::

![Verificar menu](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/cvSR42xhAMsZlxSxvJ7T1_menusok.png)

***

## Menu Antigo

:::BlockQuote
Em alguns clientes, o Front Manager pode estar com versões desatualizadas. Esta seção abrange esses casos.
:::

1. No menu lateral, acesse **Low Code>Gerenciamento>Formulário**

![Menu de Itens](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/4eg47O5YcfXz0l9Mww9vy_formulariofrontmanagerantigo.png)

1. Na barra de pesquisa, procure pelo item desejado e clique no ícone de editar.

:::BlockQuote
Normalmente, os itens de versões antigas começam com o prefixo "Hyper".
:::

![Pesquisa por hyper](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/BNfgzAh2hzI10ubDf_uxj_pesquisahyper.png)

1. Dentro da página, selecione Testar Página e escolha a versão que deseja testar.

:::BlockQuote
Sempre que possível, utilize a opção de formulário padrão. Caso ela não esteja disponível, teste com a página de CRUD.
:::

![Testar pagina](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/LTwj7YCsXWKvauL3XjCLx_testarpagina.png)

***

**Link Rápido**

[**Manual de Criação e Adição de Menus**](docId\:cYLfKEuq2Ys_ofV2-yG3R)

[title] Questionários e Ações
[path] Untitled/Interlocutores/

:::BlockQuote
Esta funcionalidade está disponível apenas para o papel de **Desenvolvedor**.
:::

A funcionalidade **Questionários e Ações** permite criar conversas e fluxos de interação de forma flexível, seja escrevendo **scripts em Lua** ou usando o **editor visual Blockly**. Escolha a abordagem que mais se adequa ao seu conhecimento e à complexidade do projeto.

- **Editor de Código**: Ideal para usuários que preferem controle total sobre o código e fluxos personalizados.
- **Editor Visual**: Indicado para quem busca rapidez e visualização intuitiva, montando lógica por meio de blocos.

## Workspaces

Os *Workspaces* permitem organizar seus projetos de forma prática e eficiente dentro da funcionalidade **Questionários e Ações**. Para criar um novo Workspace, siga as instruções abaixo:

### Criar um workspace

1. No menu lateral, acesse **Citsmart Aura > Questionários e Ações**.
   ![Menu Lateral](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/5LvNvvg7OPM7sLvPXqe3b_menulateral.png)
2. Na tela principal, clique em **Novo Workspace**.
   ![Novo Workspace](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/wvVA77Vb6TDxOeWrvRvN1_novoworkspace.png)
3. Ao clicar em **“Novo Workspace”**, um pop-up será exibido:
   ![Preenchendo Workspace](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/QqM6OuiAt7EGFxf5FkbTQ_preenchendoworkspace.png)

**Campos do formulário:**

- **Nome do Workspace:** Insira um nome único e descritivo para facilitar a identificação.
- **Integrar com o GIT (opcional):** Se desejar conectar o Workspace a um repositório Git, preencha:
  - **Repositório:** URL completa do repositório.
  - **Usuário:** Seu nome de usuário para acesso ao repositório.
  - **Senha:** Senha ou token de acesso ao repositório.

Quando terminar, basta clicar em **Criar novo Workspace**.

Pronto! Seu ambiente será criado e já poderá ser utilizado.

### Excluir um workspace

Para deleter um **Workspace**, clique no ícone de lixeira ao lado daquele que deseja excluir.

![Deletando Workspace](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/8N5BxC9au4jlNB6KM21fT_deletandoworkspace.png)

No pop-up de confirmação, clique em **Sim** para confirmar a exclusão.

### Editor visual

&#x20;No Citsmart Aura, o Editor Visual oferece uma forma fácil de montar seus fluxos sem escrever código. Com base na tecnologia Blockly, ele apresenta blocos coloridos que representam ações, condições, repetições, cálculos, textos, listas, variáveis e funções. Ao arrastar e encaixar esses blocos no espaço de trabalho, o sistema converte automaticamente a sequência em código funcional.&#x20;

### Acessar

Para acessar o editor, escolha o Workspace e clique na opção **"Editor Visual"**.

![Acessando o editor visual](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/21NFJ11kp6FtKoyI1Yysx_editorvisual.png)

### Caixa de ferramentas

A **caixa de ferramentas** organiza todos os blocos por tema, facilitando a busca pelo recurso certo. Cada categoria agrupa blocos com finalidades específicas.

![Página do editor visual](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/yKgHVyAArKm0YMn0ql09n_paginaeditorvisual.png)

Para usar um bloco, clique no nome da categoria para expandir a lista, em seguida arraste o bloco escolhido para o painel principal.

![Arrastando blocos para o espaço de trabalho](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/pR3QHJf5O0PhYXfMiR0cW_arrastandoblocos.png)

### Tipos de blocos

&#x20;Nesta seção, você vai conhecer os diferentes tipos de blocos disponíveis e entender para que serve cada um. Esses blocos são como peças de um quebra-cabeça que você pode montar para criar soluções no sistema, mesmo sem saber programar. Cada categoria tem uma função específica para tornar o processo simples e intuitivo.&#x20;

- **Lógica:** Os blocos de lógica permitem criar condições e tomar decisões no seu projeto. Por exemplo, você pode usar "se... então" para que algo aconteça apenas quando uma condição for verdadeira. Também pode combinar condições ou verificar se algo é verdadeiro ou falso.
- **Repetições:** Esses blocos ajudam a automatizar ações que precisam ser feitas várias vezes. Você pode repetir uma tarefa um número específico de vezes ou enquanto uma condição for verdadeira, como "continue até que o valor chegue a 10".
- **Cálculos:** Os blocos de cálculo são usados para realizar operações matemáticas, como somar, subtrair, multiplicar ou dividir números. Além disso, você pode trabalhar com números aleatórios ou realizar cálculos mais avançados dependendo da necessidade do projeto.
- **Texto:** Aqui você encontra blocos para trabalhar com palavras e frases. Com eles, é possível criar textos personalizados, juntar palavras, verificar se uma palavra aparece em outra ou até contar quantos caracteres tem uma frase.
- **Listas:** Os blocos de lista ajudam a organizar informações em sequência, como uma lista de itens de compras ou números ordenados. Com eles, você pode adicionar, remover ou encontrar elementos específicos em uma lista, facilitando a manipulação de dados.
- **Variáveis:** As variáveis funcionam como caixinhas que guardam informações que podem mudar ao longo do tempo. Por exemplo, você pode criar uma variável chamada "pontos" para armazenar a pontuação de um jogo e atualizar esse valor conforme o jogo avança.
- **Funções:** Os blocos de função permitem criar conjuntos de ações que podem ser reutilizados em diferentes partes do projeto. Pense neles como uma receita: você monta uma vez e pode chamá-la quantas vezes quiser, tornando tudo mais organizado e eficiente.

### Pipelines

&#x20;As pipelines são uma forma poderosa de organizar fluxos de interação com o usuário, especialmente em sistemas que precisam de entradas dinâmicas e respostas interativas. No questionários e ações, criar uma pipeline é simples e intuitivo, pois tudo é feito através de blocos que representam cada etapa do processo.&#x20;

![Bloco de Pipelines](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/jIcUfOftI_cNarEGJsIWL_pipelines.png)

Cada bloco desempenha uma função, veja abaixo:

***

- **Bloco "pipelines - criar lista com"**
  - **Função:** Cria uma lista para armazenar pipelines. As pipelines são fluxos de interação que conectam várias etapas ou ações.

***

- **Bloco "criar pipeline com as iterações"**:
  - **Função:** Define um pipeline específica com um nome personalizado e as iterações que ele conterá.
  - **Parâmetros:**
    - **Nome da pipeline:** Identifica a pipeline.
    - **Iterações:** Define quais etapas (ou interações) fazem parte do fluxo.
  - **Uso:** Este é o ponto central de criação da pipeline, conectando diferentes etapas.

***

- **Bloco "nome da interação":**
  - **Função:** Define as iterações dentro da pipeline.
  - **Parâmetros:**
    - **Nome da iteração:** Define o nome da iteração da pipeline.
    - **Mensagem de saída:** Texto ou instrução exibida ao usuário durante a interação.
    - **Mostrar interação:** Define se a interação será visível (verdadeiro) ou oculta (falso).
    - **Aceitar entrada:** Configura se a interação aceita dados do usuário.
    - **Mensagem de rejeição:** Texto exibido caso a entrada do usuário seja inválida.
  - **Uso:** Configura o comportamento de uma etapa na pipeline.

***

- **Bloco "chave - valor"** -
  - **Função:** Define pares de chave-valor. Muito útil para armazenar dados ou configurar informações dentro de uma interação ou função.
  - **Parâmetros:**
    - **Chave:** Nome que identifica o dado.
    - **Valor:** Conteúdo associado à chave.
  - **Uso:** Esse bloco é usado para manipular e organizar dados na pipeline.

***

- **Bloco "referenciar função"**
  - **Função:** Faz referência a uma função previamente definida no sistema.
  - **Parâmetros:**
    - **Nome da função:** A função que será chamada quando o bloco for executado.
  - **Uso:** Este bloco é utilizado para reaproveitar comportamentos ou lógicas já implementadas.

***

- **Bloco "função com argumentos - criar lista com"** -
  - **Função:** Define uma função com argumentos que podem ser passados quando ela for chamada.
  - **Parâmetros:**
    - **Nome da função:** Identifica a função.
    - **Argumentos:** Lista de variáveis ou parâmetros que a função utiliza.
  - **Uso:** Permite criar funções reutilizáveis que podem ser configuradas dinamicamente com base nos argumentos fornecidos.

***

- **Bloco "função com argumentos (repetição)"**
  - **Função:** Similar ao bloco anterior, define uma função com argumentos, mas aqui pode ser usado em outro contexto ou repetido.

***

- **Bloco "definir variável local "i" para"**
  - **Função:** Cria uma variável local (visível apenas dentro do contexto onde foi definida) e atribui um valor a ela.
  - **Parâmetros:**
    - **Nome da variável:** Identifica a variável (neste caso, i).
    - **Valor:** O conteúdo inicial da variável.
- **Uso:** Este bloco é útil para armazenar temporariamente valores ou realizar cálculos locais.

***

## Criando uma pipeline simples

Neste exemplo, vamos criar uma pipeline básica chamada **pipeline\_exemplo** que solicita três informações do usuário:

- O **Nome** do usuário,
- A **Idade** do usuário,
- E qual o **Problema** ele deseja resolver.

Além de aprender a criar a pipeline, você verá como configurar mensagens personalizadas e validar as entradas do usuário. Com este passo a passo detalhado e ilustrado, você conseguirá criar suas próprias pipelines para atender a diversas necessidades.

## Exemplo prático

Siga as instruções abaixo para criar e configurar sua pipeline.

### Passo 1: Definir nome da pipeline

1. No menu **Pipelines**, localize o bloco **"pipelines" > "criar lista com"**
2. Arraste o bloco para o espaço de trabalho.
3. No menu **Texto**, arraste o primeiro bloco **"(  )"**.
4. Conecte ao espaço disponível no bloco **"criar lista com"**.
5. Clique no campo de texto do bloco e insira o nome da pipeline: `pipeline_exemplo`.

**Observação:** Para remover os campos de conexões que não serão utilizados, basta clicar na engrenagem e arrastar o campo **"Item"** para fora.

![Primeiro passo](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/7EHCsxqaHwUmEbfw9me4s_passo1.png)

***

### Passo 2: Iniciar a Pipeline

1. No menu **Pipelines**, localize o bloco **"criar pipeline com as iterações" > "criar lista com"**.
2. Arraste o bloco para o espaço de trabalho.
3. No campo de texto do bloco, insira o nome da pipeline: `pipeline_exemplo`.

![Segundo passo](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/x0uG_3d_W7aKHbLd3qPfM_passo2.png)

***

### Passo 3: Configurar as Iterações

Agora, você configurará as etapas (iterações) da pipeline. Este exemplo inclui três etapas: **Perguntar o nome**, **Perguntar a idade** e **Perguntar o problema**.

### Etapa 1: Perguntar o Nome

1. No menu **Pipelines**, localize o bloco **"nome da interação"**
2. Arraste-o para o espaço de trabalho.
3. Preencha os campos do bloco:
   - **Nome da interação:** Digite `perguntar_nome`.
   - **Mensagem de saída:** Escreva **"Por favor, informe seu nome"**
   - **Mostrar interação:** Selecione `verdadeiro`.
   - **Aceitar entrada:** Selecione `verdadeiro`.
   - **Mensagem de rejeição:** Escreva **"Tente novamente."**

![Primeira etapa](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/d-gshKXbTyempq8_R6wFR_passo3.png)

### Etapa 2: Perguntar a Idade

1. Arraste outro bloco **"nome da interação"** para o espaço de trabalho.
2. Preencha os campos do bloco:
   - **Nome da interação:** Digite `perguntar_idade`.
   - **Mensagem de saída:** Escreva **"Qual é a sua idade?"**
   - **Mostrar interação:** Selecione `verdadeiro`.
   - **Aceitar entrada:** Selecione `verdadeiro`.
   - **Mensagem de rejeição:** Escreva **"Idade inválida. Tente novamente."**

**Observação:** Utileze como referência a imagem da **Etapa 1**.

### Etapa 3: Perguntar o Problema

1. Adicione mais um bloco **"nome da interação"** ao espaço de trabalho.
2. Preencha os campos do bloco:
   - **Nome da interação:** Digite `perguntar_problema`.
   - **Mensagem de saída:** Escreva **"Qual é o problema que deseja resolver?"**
   - **Mostrar interação:** Selecione `verdadeiro`.
   - **Aceitar entrada:** Selecione `verdadeiro`.
   - **Mensagem de rejeição:** Escreva **"Entrada inválida. Por favor, tente novamente."**

**Observação:** Utileze como referência a imagem da **Etapa 1**.

***

### Passo 4: Conectar as Iterações à Pipeline

1. Certifique-se de que as três iterações foram criadas:
   - `perguntar_nome`
   - `perguntar_idade`
   - `perguntar_problema`
2. No menu **Texto**, arraste três blocos de texto **" " (campo de texto vazio)** para o espaço de trabalho.
3. Em cada bloco de texto, escreva os nomes das iterações criadas: `perguntar_nome`, `perguntar_idade`, e `perguntar_problema`.
4. Conecte os blocos de texto ao campo **"criar lista com"** do bloco **"criar pipeline com as iterações"**.
5. Verifique se todas as interações estão conectadas corretamente à lista.

![Passo 4](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/jWU0DZpnnX_hBCMAICE4n_passo4.png)

***

### Checagem final

Após seguir todos os passos, revise o fluxo completo no espaço de trabalho. Certifique-se de que:

- O nome da pipeline está correto: `pipeline_exemplo`.
- As três iterações foram criadas e configuradas corretamente.
- As iterações estão conectadas ao bloco principal.

Se tudo estiver correto, sua pipeline estará funcional e pronta para uso. Ela seguirá o seguinte fluxo:

1. Pergunta o nome do usuário.
2. Pergunta a idade do usuário.
3. Pergunta qual problema o usuário deseja resolver.

### Testar a pipeline

Para validar a lógica da sua pipeline, utilize o botão **Testar**, disponível no canto superior direito do editor visual.

![Botão testar](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/v86BjtnTDBcpRVDTPO4EW_testar.png)

Ao clicar na opção **Testar**, uma janela será exibida para que você possa interagir com o fluxo criado e verificar se ele está funcionando conforme o esperado.

![Realizando teste](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/piEdYKrxJHm5Cyz-P0D76_exemploteste.png)

***

## Webserver

Com os blocos de webserver, você pode configurar interações com servidores na web, como enviar ou receber informações. Eles são úteis para criar sistemas que se comunicam com outros serviços online ou para criar funcionalidades como APIs dentro do seu projeto.

## Lixeira

A lixeira permite que você remova blocos arrastando-os até ela. Se precisar, basta clicar na lixeira para abrir uma lista com os blocos descartados, permitindo que você os recupere quando necessário.

![Lixeira](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/yhq8juNfc-nNz8ih9VEUW_lixeira.png)

## Menu de contexto

O menu de contexto é exibido quando você clica com o botão direito do mouse ou pressiona por alguns instantes certos elementos no espaço de trabalho, como o fundo ou os blocos. Ele apresenta uma lista de ações disponíveis para o elemento selecionado. Veja abaixo:

![Contexto](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/cbC2TpE4K6ZPjU6b_nqpO_menucontexto.png)

## Outras ferramentas do Editor Visual

O editor visual oferece outras ferramentas que tornam a navegação e organização mais prática e eficiente. Confira os recursos apresentados na imagem abaixo:

![Outros Funções do Editor](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/jHN8Kv9g9GXVzjrKxgRIu_outrasopcoeseditorvisual.png)

- **Mini mapa:** Exibe uma visão reduzida do espaço de trabalho, permitindo localizar rapidamente áreas específicas quando há muitos blocos distribuídos. Ideal para facilitar a navegação em projetos maiores.
- **Maximizar:** Expande os blocos para ocupar todo o espaço de trabalho, proporcionando um visão melhor dos blocos já criados. Útil para evitar distrações e aproveitar melhor o ambiente de trabalho.
- **Auto organizar:** Realinha automaticamente os blocos no espaço de trabalho, organizando-os de forma clara e eficiente. Essa função é ideal para manter os fluxos bem estruturados.
- **Voltar:** Localizada ao lado do título "Editor Visual", a seta permite retornar facilmente ao menu principal do questionários e ações, proporcionando acesso rápido às demais funcionalidades.
- **Salvar:** Grava as alterações feitas no projeto atual, garantindo que nenhum progresso seja perdido.

# Código

Para acessar o código, selecione o card desejado na lista do Workspace e clique na opção **"Código"**, conforme indicado na imagem abaixo:

![Código](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/0jTiIRLhuzPjMCH9AcZeZ_codigo.png)

Para criar um **"Novo item"**, clique no ícone com o símbolo de **"+"**, localizado ao lado da palavra **"Raiz"**.

![Criando novo item](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/kY9rvu6x6blVGOhIqRREY_novoitem.png)

Digite o nome para o item e escolha se ele será um **"Arquivo"** ou **"Pasta"**. Após preencher as informações, clique em **"Salvar"** para finalizar a criação.

![Nomeando novo item](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/FHhZWFshjTsOaWS3uBeP5_criararquivoeditorcodigo.png)

## Editor de código

Após criar a pasta e o arquivo, a tela de edição de código será exibida, oferecendo um ambiente semelhante ao de um editor de texto avançado.

Essa tela permite que você escreva o código necessário para configurar sua pipeline. Na imagem abaixo, estão destacados a área principal para edição do código, o botão para salvar as alterações e o arquivo criado dentro da pasta, onde o código será inserido.

![Tela de edição de código](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/cqfa7WdjWNvqFfPzL8sG0_criandocodigo.png)

- **Área de código:** Aqui é onde você vai inserir o código da sua pipeline. Você pode digitar diretamente ou colar o código se já o tiver pronto.
- **Botão "Salvar":** Após finalizar a edição do código, clique em **"Salvar"** para garantir que suas alterações sejam aplicadas.
- **Lista de arquivos:** No painel lateral, você pode navegar entre os arquivos e pastas criados, como mostrado no exemplo.

Com essas ferramentas, você pode facilmente criar, editar e organizar as pipelines diretamente pelo sistema.

## Outras Funções

O sistema de questionários e ações oferece diversas funcionalidades adicionais para facilitar a gestão e personalização dos seus Workspaces. Confira na imagem abaixo:

![Outras Funcionalidades](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/reKNtVyB_oZ6e8LsfCs52_outrasfuncionalidades.png)

**Funcionalidades disponíveis:**

- **Sincronizar todos:** Permite sincronizar todas as alterações realizadas nos Workspaces com o repositório GIT conectado.
  - **Sincronizar (Card):** Atualiza as alterações mais recentes daquele card, garantindo que os dados estejam sempre em sincronia.
- **Editar nome:** Você pode alterar o nome do Workspace de forma simples. Basta clicar no ícone de lápis ou diretamente sobre o nome do Workspace. Após digitar o novo nome, clique fora da caixa para salvar automaticamente a alteração.
- **Download:** Esta opção permite fazer o download completo de todas as criações realizadas no editor visual e no código. Assim, você pode manter uma cópia local do conteúdo para backup ou análise.
- **Visualizar Logs:** Clique no ícone em formato de **"bug"** para acessar o log de atividades do Workspace. Essa funcionalidade permite acompanhar de forma detalhada as alterações, sincronizações e outros eventos importantes, facilitando o monitoramento. Ao clicar, uma nova página será aberta exibindo todos os registros dos logs.


[title] Slack
[path] Untitled/Brokers/

O broker do Slack segue o padrão de cadastrar webhook para recebimento de mensagens e receber um link para envio de mensagens. A API do slack fornece certos identificadores para o cadastro do broken, como id da conta, token, signing secret e oath do usuário.

### 1. Criar uma conta

Através do link abaixo, se inscreva no Slack API

[**link de acesso**](https://slack.com/get-started#/createnew)

### 2. Criar um novo workspace

Workspace é um espaço onde se pode fazer a comunicação entre canais, mensagens diretas etc.

![workspace](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/DqIT0hDoeYFT0TcA5actz_slackworkspace.png)

### 3. Criar um novo aplicativo de desenvolvedor

[**link slack aplicativo**](https://api.slack.com)

O aplicativo serve para usar e configurar ferramentas da API do slack. Na criação do aplicativo, deve selecionar o workspace criado.
Para criar selecione Seus Aplicativos e Criar Novo Aplicativo.

![aplicativo](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/hiaUbsCSkM55w2t1wULTa_slackaplicativo.png)

### 4. Configurar webhook e inscrição em eventos

Na aba de inscrição de eventos, permita os eventos. Depois, cadastre uma url para o webhook **https\://\{endereço\_do\_lunaris}/post/slack/webhook**. e também se inscreva em evento no  recebimento de mensagens (Subscribe to bot events e Subscribe to events on behalf of users).

![webhook](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/O23F7kWhbEGJmBx7FEbAV_slackwebhook.png)

### 5. Receber link para envio de mensagem

Na aba de webhook de recebimento, ative tal funcionalidade e clique na opção de Adicionar um Novo Webhook ao Workspace. Na imagem abaixo é mostrado o link em que é possível enviar requisições de envio de mensagem. A url tem o padrão de endereço fixo ([**https://hooks.slack.com/services/**](https://hooks.slack.com/services/)) seguido do token, no caso, o token da imagem seria **T07AKPV415W/B07A3P3FF39/Ta6EqeECKRHnJzqmcTdAIEaE**.

![link](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/LsRuhQuVjMT7NnxytGji7_slacklink.png)

### 6. Ativar Interatividade de Botões

Na aba de Interatividade e Atalhos de Texto, ative a Interatividade e ponha o link do webhook parecido com o passo 4, com endereço **https\://\{endereço\_do\_lunaris}/post/slack/webhook\_interaction**.

### 7. Obter ID da conta

Na aba de informações básicas é mostrado o ID do aplicativo, como no caso, A07AKQV7AUQ.

O campo Signing Secret é a **Chave Secreta** que deve ser cadastrado no AURA BLOCKS.

![id](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/OB8W-V0ZoO8fBnX7-Texh_slackid.png)

### 8. Obter OAuth do Usuário

Nesta página do OAuth como pode ser pode vista na imagem abaixo, em User Token Scopes ative a opção *im\:read*
e *files\:read*. Isso permitirá que arquivos e imagens sejam recebidos pelo nosso servidor do broker slack.
Por último guarde o campo, **User OAuth Token** conforme mostra a imagem em que se inicia com "xoxp..."

![id](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/TgryiPFu0o3L0SEmmriqw_slackoauth.png)

[title] HTTP
[path] Untitled/Customizações Avançadas/Bibliotecas/

Utilizada para fazer requisições utilizando o protocolo HTTP.

## Atalhos

- [**HTTP**](docId:9-nY7HWqvhaOsJFQ9z_93)
- [**HTTP**](docId:9-nY7HWqvhaOsJFQ9z_93)
- [**HTTP**](docId:9-nY7HWqvhaOsJFQ9z_93)
- [**HTTP**](docId:9-nY7HWqvhaOsJFQ9z_93)
- [**HTTP**](docId:9-nY7HWqvhaOsJFQ9z_93)

***

### Métodos

### GET

```lua
-- @param url String containing the url.
-- @param @optional headers Table containing the headers of the request.
-- @param @optional body String containing the JSON encoded body.
-- @return a table containing headers, status, text. 
http.get(url, headers, body)
```

```lua
-- example usage:

local request = http.get("https://httpbin.org/get")

local body = request.text
local headers = request.headers
local status = request.status

--[[
request value:

{
  headers = {
    ["access-control-allow-credentials"] = "true",
    ["access-control-allow-origin"] = "*",
    connection = "keep-alive",
    ["content-length"] = "222",
    ["content-type"] = "application/json",
    date = "Fri, 27 Dec 2024 20:55:39 GMT",
    server = "gunicorn/19.9.0"
  },
  status = 200,
  text = '{\n  "args": {}, \n  "headers": {\n    "Accept": "*/*", \n    "Host": "httpbin.org", \n    "X-Amzn-Trace-Id": "Root=1-676f1449-635d770f2b8b549173c3fa96"\n  }, \n  "origin": "186.235.83.146", \n  "url": "https://httpbin.org/get"\n}\n'
}

--]]
```

### POST

```lua
-- @param url String containing the url.
-- @param @optional headers Table containing the headers of the request.
-- @param @optional body String containing the JSON encoded body.
-- @return a table containing headers, status, text. 
http.post(url, headers, body)
```

```lua
-- example usage:

local request = http.post(
    "https://httpbin.org/post",
    { ["Content-Type"] = "application/json" },
    json.encode({key = "value"})
)

local body = request.text
local headers = request.headers
local status = request.status
```

### PUT

```lua
-- @param url String containing the url.
-- @param @optional headers Table containing the headers of the request.
-- @param @optional body String containing the JSON encoded body.
-- @return a table containing headers, status, text. 
http.put(url, headers, body)

```

```lua
-- example usage:

local request = http.put(
    "https://httpbin.org/put",
    { ["Content-Type"] = "application/json" },
    nil
)

local body = request.text
local headers = request.headers
local status = request.status
```

### DELETE

```lua
-- @param url String containing the url.
-- @param @optional headers Table containing the headers of the request.
-- @param @optional body String containing the JSON encoded body.
-- @return a table containing headers, status, text. 
http.delete(url, headers, body)
```

```lua
-- example usage:

local request = http.delete(
    "https://httpbin.org/delete",
    { ["Content-Type"] = "application/json" },
    nil
)

local body = request.text
local headers = request.headers
local status = request.status
```

### PATCH

```lua
-- @param url String containing the url.
-- @param @optional headers Table containing the headers of the request.
-- @param @optional body String containing the JSON encoded body.
-- @return a table containing headers, status, text. 
http.patch(url, headers, body)
```

```lua
-- example usage:

local request = http.patch("https://httpbin.org/patch")

local body = request.text
local headers = request.headers
local status = request.status
```


[title] Microsoft Teams
[path] Untitled/Brokers/

A especificação a seguir atua como um guia detalhado para utilização do broker **Microsoft Teams**, fornecendo todas as instruções e orientações necessárias para sua configuração.

:::BlockQuote
Atualmente, o teams não está suportando alguns tipos de arquivos. Imagens estão funcionando normalmente. [**Confira mais**](https://github.com/microsoft/botbuilder-js/issues/4845)
:::

## Configuração

Para realizar o cadastro do broker, é imprescindível fornecer o **nome**, **identificador (ID)**, **chave secreta (segredo)** e **locatário (tenant)**.

***

*Este manual está dividido em seções para facilitar a localização das informações. As seções são:*

[**Microsoft Teams**](docId\:U2x45XhTvXjYPfCjTwdGL) 🔹 [**Adquirir Configuração**](#adquirindo-configuração) 🔹 [**Microsoft Teams**](docId\:U2x45XhTvXjYPfCjTwdGL) 🔹 [**Microsoft Teams**](docId\:U2x45XhTvXjYPfCjTwdGL)

## Criar Bot

1. Na barra lateral, clique no ícone de **reticências**.

![Menu teams](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/bXKS2yqBkOrOAs4CaSIKr_reticencias.png)

1. No campo de pesquisa, digite **Portal de Desenvolvimento** e selecione-o na lista de opções.

![Menu Portal de desenvolvimento](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/ToaJSB5CcwK3n2Aq4bsb5_portal.png)

1. Usando o menu, aperte em **Aplicativos > Novo aplicativo**

![NovoApp](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/em006EysJgPCGSk9ACFec_newapp.png)

1. Insira o nome desejado para o seu aplicativo e clique em **Adicione**.

![NomeApp](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/8rMR2lv_XHYtm2P6VXMJM_nomeapp.png)

1. No menu, selecione a opção **Informação básica** e preencha **todos os campos obrigatórios** conforme indicado nas imagens e, ao final, clique no botão Salvar.

![AddInfo](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/Hp8b3NHk_FyJoCOYP1zua_addinfos.png)
![AddInfo](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/-p5eV3X1VJzenYhf_QdMc_addinfos2.png)
![AddInfo](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/hGXr0O0LqGL5g41K3DHHa_salvarnofinal.png)

1. Selecione em **Recurso do Aplicativo > Bot**

![RecursoApp](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/b9HxI0BUnBNNqtOY1TpmY_recursoapp.png)

1. Aperte em **Criar um novo bot**

![NovoBot](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/duixIDYn_KHdwOWeTJhln_novobot.png)

1. Usando o menu, aperte em **Novo bot**

![Menunewbot](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/SsVhZs8WUqZwvNGYvvkBI_menunovobot.png)

1. Insira o nome desejado para o seu bot e clique em **Adicione**.

![NomeNovoBot](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/J129qGhBVnQ6aH2qcJzs4_nomedobot.png)

1. Na seção **Configurar**, insira o ponto de extremidade desejado e clique em **Salvar**.

:::BlockQuote
Os endpoints são formados por: https\://\{dominio}/\{caminho-teams-server}/webhook
:::

![endpoint](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/z9_mESfNn8IQa8q7mMPx5_endpoint.png)

1. Volte para **Aplicativos > \{SeuBot} > Recursos do Aplicativo > Bot**. Marque a opção **Selecionar bot existente** e escolha o bot que você criou na caixa de seleção. Depois, selecione **Personal** na aba de escolha de escopo e pressione **Salvar**.

![selecionarbot](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/KOhv-kpwUC0TokN1WEwFA_caminhoselecionarbot.png)
![RecursoApp](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/b9HxI0BUnBNNqtOY1TpmY_recursoapp.png)
![selecionarbot](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/Pz_tVd37vWy1QsonvjV1d_selecionarbot.png)

:::BlockQuote
Recomenda-se seguir as instruções das imagens acima, pois elas contêm o exemplo utilizado pela equipe Citsmart Aura e funcionam de forma confiável. Opções adicionais, como "team" ou "suporte para chamadas de vídeo", podem ajudar a personalizar a experiência do bot para diferentes cenários de uso no Teams, mas não há garantia de que funcionarão corretamente após a configuração.
:::

## Adquirindo configuração

1. Na barra lateral, clique no ícone de **reticências**.

![Menu teams](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/bXKS2yqBkOrOAs4CaSIKr_reticencias.png)

1. No campo de pesquisa, digite **Portal de Desenvolvimento** e selecione-o na lista de opções.

![Menu Portal de desenvolvimento](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/ToaJSB5CcwK3n2Aq4bsb5_portal.png)

1. Usando o menu, aperte em **Ferramentas > Gerenciament de Bot**

![botao](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/10q-DB2fXbl0LDcxph_fy_botao.png)

1. Com isso, você poderá localizar e anotar:

- **1: Nome do bot (Nome de exibição)**
- **2: Identificador (ID do aplicativo)**

![dados](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/dH88YynwCm8O1I3rub1bl_dados.png)

1. Para encontrar o segredo, basta selecionar **\{Seu Bot} > Segredos do cliente** e clicar em **Adicionar um segredo do cliente...**.

O segredo fica disponível apenas no momento da criação. Portanto, caso sejam necessárias múltiplas configurações, será preciso criar mais de um segredo ou anotá-lo em um local seguro.

![lateralsegredo](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/-MBITMXldj-SaCxzUvXJn_lateralsegredo.png)

***

:::BlockQuote
O locatário do app é localizável apenas dentro do Portal do Botframework
:::

1. Primeiro, acesse o [**Portal do Botframework**](https://dev.botframework.com/bots) e realize o login.
2. Selecione o bot que você criou e, no menu, clique em **Settings**.

![settings](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/UyGdwV6hRQ_cn9K0Vw4AJ_settings2.png)

***

![settings](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/r4KFd2mMt6SPn0yK9ondm_settings.png)

1. Clique no botão **Manage Microsoft App ID and password**

![botao](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/iORueyPHFieQDkDbG1hku_botaobotframework.png)

1. Localize o **ID do locatário**

![tenant](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/Gztd0D7x6fhibqg7HT-tl_tenantid.png)

:::BlockQuote
Com isso, é possível adquirir todos os campos necessários para registrar dentro da plataforma:
:::

- **Nome do Chatbot** > Nome de exibição
- **ID do App** > ID do aplicativo (cliente)
- **ID do Locatário** > ID do diretório (locatário)
- **Segredo do App** > Segredo

## Implantar Bot

1. Na barra lateral, clique no ícone de **reticências**.

![Menu teams](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/bXKS2yqBkOrOAs4CaSIKr_reticencias.png)

1. No campo de pesquisa, digite **Portal de Desenvolvimento** e selecione-o na lista de opções.

![Menu Portal de desenvolvimento](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/ToaJSB5CcwK3n2Aq4bsb5_portal.png)

1. Usando o menu, aperte em **Aplicativos > \{Seu Aplicativo}**

![NovoApp](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/ClvW9tJluJ5165kbM1oiF_seuappdeploy.png)

1. Clique em **Antevisão nas Teams** e selecione adicionar.

![NovoApp](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/Zm5Ceg8D3tgA6DX4q7hYt_antevisaoteams.png)

***

![NovoApp](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/_2B3F_uUunOd7ZpZAWbGL_adicionarnoantevisao.png)

***

## Exportar e Importar Bots

[**Microsoft Teams**](docId\:U2x45XhTvXjYPfCjTwdGL) | [**Microsoft Teams**](docId\:U2x45XhTvXjYPfCjTwdGL)

### Exportar

1. Na barra lateral, clique no ícone de **reticências**.

![Menu teams](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/bXKS2yqBkOrOAs4CaSIKr_reticencias.png)

1. No campo de pesquisa, digite **Portal de Desenvolvimento** e selecione-o na lista de opções.

![Menu Portal de desenvolvimento](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/ToaJSB5CcwK3n2Aq4bsb5_portal.png)

1. Vá para **Aplicativos > \{SeuBot}** e clique em **Publicar**

![publish](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/7DZdagl0DJYXl9v8sN3JY_publish.png)

1. Selecione **Baixar o pacote do aplicativo**

![download](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/iE2DkUzkmOGeQl5dlGAJj_download.png)

***

### Importar

1. Na barra lateral, clique no ícone de **reticências**.

![Menu teams](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/bXKS2yqBkOrOAs4CaSIKr_reticencias.png)

1. Clique em **Obter mais aplicativos**

![Menu teams](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/mzeHNJXwl1b8M7T9Oxawa_importapp.png)

1. Selecione **Gerenciar seus aplicativos**

![download](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/nh9fpmQtRK0Mi5kuxDZbj_managemyapps.png)

1. Aperte em **Carregar um aplicativo**

![download](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/ju3j-0YTAp7IzB1V4HrUP_newappbutton.png)

1. Escolha a opção de envio que melhor se adequa à sua necessidade e selecione o arquivo compactado (.zip).

![download](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/iLwmkNUdhQAgDAXhNGLCb_typesupload.png)

:::BlockQuote
Caso o envio tenha sido feito por "Enviar um aplicativo à sua organização", será necessário que um administrador aceite o pedido. Após isso, o aplicativo será adicionado à organização inteira. Caso o envio tenha sido feito por "Fazer o upload de um aplicativo personalizado", siga a imagem abaixo.
:::

1. Clique em **Adicionar**

![download](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/RXhOyE7LIYcCrSQK4ZVpF_customappupload.png)

[title] Biblioteca padrão do Lunaris
[path] Untitled/Customizações Avançadas/Bibliotecas/

O Lunaris é um ambiente de execução Lua projetado com foco na flexibilidade e integração. Ele injeta todas as bibliotecas necessárias diretamente no escopo global Lua através de uma Virtual Machine (VM) Lua. Isso permite que funções e recursos específicos do Lunaris, como manipulação de dados, operações HTTP, codificação e segurança, sejam acessados diretamente no código Lua sem a necessidade de importação explícita.

Para remover a mensagem de advertência sobre variáveis globais, é possível personalizar a configuração do Lua com o seguinte arquivo `.luarc.json`, que define as bibliotecas globais permitidas e desabilita a advertência sobre o uso de variáveis globais:

```json
{
    "diagnostics.globals": [
        "set_key",
        "http",
        "json",
        "LUNARIS_URL",
        "get_key",
        "remove_key",
        "urlencoding",
        "base64",
        "dataurl",
        "hmac"
    ],
    "diagnostics.disable": [
        "lowercase-global"
    ]
}

```


[title] Interlocutores
[path] Untitled/


[title] Lista de Funcionalidades do Citsmart Aura
[path] Untitled/Início/

## Chatbots

### Funcionalidades:

- **Novo Chatbot:** Permite ao usuário configurar múltiplos workspaces para definir os comportamentos desejados.
- **Excluir Chatbot:** Remove workspaces que não são mais necessários.
- **Dashboards:** Visualiza métricas importantes sobre as interações do chatbot.
  - **Download de dados:** Possibilita o download de dados selecionados por canal.
- **Listagem de históricos de Conversa:** Possibilita a visualização de todas as interações realizadas do chat.
  - **Ver conversa:** Funcionalidade para exibir a conversa encontrada na pesquisa, permitindo também a busca por palavras-chave dentro da conversa.

## Comportamentos

### Descrição:

Funcionalidade para registrar, gerenciar e configurar novos plugins, controlando como o sistema interage com diferentes eventos, interlocutores e mensageiros.

### Funcionalidades:

- **Registrar Novo Comportamento:** Permite ao usuário realizar o cadastro de um novo plugin.
- **Editar Parâmetros do Comportamento:** Possibilita ajustar os parâmetros de plugins já registrados.
- **Excluir Comportamento:** Remove plugins não utilizados.
- **Alterar interlocutores:** Modifica os interlocutores envolvidos nas interações controladas pelo plugin.
- **Configurar Mensageiros:** Define os canais de comunicação utilizados pelo plugin.
- **Configurar Eventos:** Permite configurar eventos que acionam respostas automáticas do sistema.

## Atendimento Humano

### Descrição:

Recebe e gerencia solicitações de atendimento provenientes de diversos canais como **Webchat, WhatsApp, Telegram, Microsoft Teams, Facebook Messenger e Slack**.

### Atendimentos

- **Em espera:**
  - **Realizar atendimento:** Permite ao operador assumir a solicitação.
- **Em atendimento:**
  - **Chat:** Permite ao operador acessar o chat e interagir diretamente com o usuário.
- **Tela de interação com o Usuário:**
  - **Emoticons:** Permite que o operador envie figuras para expressar algo.
  - **Upload de arquivos:** Envio de arquivos e documentos durante o atendimento.
  - **Microfone:** Permite ao atendente enviar uma mensagem de áudio para o usuário.
  - **Atalhos:** Acesso aos atalhos públicos e privados previamente criados.
  - **Transferir atendimento:** Permite transferir a solicitação para outra fila ou atendente sem encerrar o atendimento.
  - **Finalizar Atendimento:** Confirma o encerramento do atendimento.
  - **User Info:** Permite o registro de informações do usuário.
    - **Histórico de conversas:** Opção para visualizar as conversas anteriores.
    - **Histórico de edição:** Exibe alterações feitas nas informações do usuário.
- **Finalizados:** Exibe o histórico de conversas do operador.

## Filas

### Descrição:

Permite a criação, configuração e gerenciamento das filas de atendimento.

### Funcionalidades:

- **Adicionar:** Criação de uma nova fila de atendimento.
- **Editar:** Ajuste das configurações da fila.
- **Excluir:** Remoção de filas não necessárias.

## Atalhos de Texto

### Descrição:

A funcionalidade de atalhos de texto permite agilizar o atendimento humano por meio de respostas pré-definidas.

### Funcionalidades:

- **Atalhos Globais:** Disponíveis para todos os atendentes, garantindo padronização nas respostas.
- **Atalhos Privados:** Personalizados para cada atendente, permitindo maior flexibilidade na comunicação.
- **Excluir:** Remoção de atalhos desnecessários.

## NLU

### Descrição:

Criação de Workspaces e Skills, com ambiente visual e de código para desenvolvimento de fluxos de conversas.

### Funcionalidades:

### Workspaces

- **Criar workspace:** Permite a criação de um novo ambiente de trabalho.
- **Renomear workspace:** Altera o nome de um workspace existente.
- **Excluir workspace:** Remove permanentemente um workspace.
- **Pesquisar:** Permite pesquisar workspaces criados.

### Skills

- **Criar nova skill:** Adiciona uma nova skill ao workspace
- **Renomear skill:** Modifica o nome de uma skill existente.
- **Excluir skill:** Remove uma skill do workspace.

### Editor Visual

- **Pesquisar:** Localiza informações dentro da skill.
- **Adicionar estado:** Insere um novo estado no fluxo conversacional.
- **Propriedades:** Permite configurar as propriedades do fluxo.
- **Exemplos:** Define exemplos de interações para treinar o fluxo.
- **Entidades:** Define as entidades usadas na conversa.
- **Testar:** Permite testar o fluxo antes de ativá-lo.
- **Nome do fluxo:** Define ou altera o nome do estado.
- **Fluxo global:** Permite que o estado seja acessado de qualquer ponto do bot.
- **Bloqueia avanço:** Impede que o fluxo prossiga sem determinada condição.
- **Menu:** Define nome da opção no fluxo.
- **Detectores:** Os detectores são palavras para chamar o estado.
- **Mensagens:** Define textos de resposta do bot.
- **Texto de dúvida:** Mensagem exibida quando a entrada do usuário não é clara.
- **Texto de dúvida completa:** Mensagem alternativa para esclarecer dúvidas mais complexas.
- **Automações:** Configura ações dentro do fluxo.

### Editor de Código

- **Upload:** Permite enviar um arquivo de código para o editor.
- **Download:** Permite baixar o código editado para o dispositivo.
- **Testar:** Executa o código para verificar seu funcionamento.

## Questionários e Ações

### Descrição:

Ferramenta para criar interações conversacionais personalizadas via scripts em Lua ou editor visual baseado em Blockly.

### Funcionalidades:

- **Adicionar novo workspace:** Cria um novo ambiente de trabalho.
- **Sincronizar todos:** Sincronizar os workspaces com o git.
- **Editar nome:** Altera o nome do workspace.
- **Visualizar logs:** Exibe os registros de problemas apresentados.
- **Excluir workspace:** Remove permanentemente o workspace.
- **Download:** Permite baixar todo o workspace.

### Editor visual

- **Adicionar blocos:** Insere novos blocos no fluxo de trabalho.
- **Remover blocos:** Exclui blocos do fluxo.
- **Testar pipeline:** Executa o pipeline para validar o funcionamento.
- **Organizar todos os blocos:** Organiza os blocos de forma estruturada.
- **Visualizar todos os blocos:** Exibe todos os blocos presentes no fluxo.
- **Mapa do fluxo:** Exibe um mapa visual do fluxo e suas interações.

### Código

- **Adicionar arquivos ou pastas:** Insere arquivos ou pastas no projeto.
- **Excluir arquivos ou pastas:** Remove arquivos ou pastas do projeto.
- **Testar:** Executa o código para verificar seu funcionamento.

## Widget Personalizado

### Descrição:

Interfaces configuráveis que permitem personalizações como cores, imagens e nomes.

### Funcionalidades:

- **Adicionar novo widget:** Insere um novo widget na interface.
- **Excluir widget:** Remove um widget existente.
- **Editar widget:** Modifica as configurações de um widget.
- **Link para o chat aplicado:** Fornece um acesso direto ao chat para verificação do widget.

## Widget personalizado por código

### Descrição:

Possibilita alterar a configuração padrão do widget utilizando a ferramenta de edição de código, permitindo ao desenvolvedor personalizar diretamente o CSS do widget.

###

- **Upload:** Permite ao usuário enviar o seu widget personalizado.
- **Baixar template:** Permite baixar um modelo de um código base do widget para personalização.

## Outras Funcionalidades

- **OIDC:** Integração com OpenID Connect para autenticação e autorização segura.
- **Agentes Cognitivos:** Utiliza inteligência artificial para realizar atendimentos e interações automatizadas.
- **Horário de Atendimento:** Define e gerencia os horários disponíveis para interação com o bot.
- **STT (Speech-to-Text):** Tecnologia que converte fala em texto, permitindo que o sistema transcreva mensagens de áudio para texto automaticamente.
- **TTS (Text-to-Speech):** Tecnologia que converte texto em fala, possibilitando que o sistema leia mensagens em voz alta para o usuário.
- **Timeout:** Define o tempo máximo que o chatbot deve aguardar uma resposta do usuário.


[title] Untitled
[path] Untitled/


[title] Máquina de estados
[path] Untitled/Interlocutores/

Este manual orienta como configurar, criar e editar uma máquina de estados, explicando a definição de estados, uso de detectores, entidades, mensagens automáticas, textos de dúvida e automações. Assim, você poderá definir como a máquina interage com os usuários e quais respostas devem ser apresentadas com base nas entradas.

:::BlockQuote
Esta funcionalidade está disponível apenas para o papel de **Desenvolvedor**.
:::

## Criar máquina de estados

1. No menu lateral, selecione a opção **Máquina de estados**.
   ![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/apHnUoTGskNpfVAL6uEe1_nlu.png)
2. Clique em **Novo workspace**.

   Uma janela será exibida. Informe o nome desejado e clique em **Criar workspace**.



   ![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/yc7NK2aLEdGtO-2i2vm1l_novoworkspace.png)
   ![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/YKemFThrwyU7trzoSRfMj_novajanela.png)
3. Dentro do workspace, é possível editar o nome, criar/editar skills ou excluir a máquina.
   ![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/S0NfS-m9kf8cqeUilJDVM_opcoesworkspace.png)

## Editar nome do workspace

Clique no ícone de lápis, digite o novo nome e clique fora da caixa para salvar automaticamente.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/LoZdu7UzgWI38qB-6FYaz_editarworkspace.png)

## Criar skill

1. Clique em **Nova skill**.
2. Na janela que abrir, informe o nome e clique em **Criar skill**.



   ![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/4Q-jmSKgjTkaWGKhpoZWg_novaskill.png)
   ![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/px6GV4wzA0HnDWNSj8eUt_novaskill2.png)
3. A skill pode ser configurada no editor visual ou no editor de código. Ela define o fluxo de conversa, os estados, detectores e mensagens.
   ![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/4NwdNBdQWWuQ1k_wQGD-d_novaskill3.png)

## Editor visual

Permite criar e organizar o fluxo da conversa conectando visualmente os estados da skill.

Ao abrir, haverá dois estados iniciais: **Start** e **End**.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/4c2FGEsjmoikUMlJ-utbf_editorvisual.png)

### Recursos do editor

- **Pesquisar estados**: encontre rapidamente qualquer estado criado.
- **Adicionar novo estado**: estados representam os pontos de interação da conversa.
  ![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/NFnUozRj8akR0vwbzBv3x_novoestado.png)
- **Propriedades**: defina configurações avançadas. [**Veja mais aqui**]().
  ![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/kmiInO92c5jMy3s5FBSaI_novapropriedade.png)
- **Exemplos**: cadastre palavras ou frases que funcionem como detectores.




  ![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/BE4YiMOOCjYkpMJ0nLBGi_exemplo1.png)
  ![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/1mtOg8qsXg1Jtzb8WZW_q_exemplo2.png)
  ![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/Pe7P8wNmM8FPNU397p0ap_exemplo3.png)
- **Entidades**: grupos de palavras com significado semelhante. Ajudam a identificar termos nas mensagens.




  ![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/7PC_gLIdrzv33HM6ZufDz_novaentidade.png)
  ![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/tBsRTtd2P7wIDs3fBNiwq_novaentidade1.png)
  ![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/K6Rx27XzZNYpz0U0fHfIc_novaentidade2.png)
- **Testar**: simule o fluxo para verificar o comportamento configurado.
  ![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/iiTAubcieE28ehvJwcGA-_testar.png)
- **Salvar**: salve as alterações realizadas.
  ![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/_M3ycj9bOhGl6qdz8HHxi_salvar.png)
- **Fluxo global**: permite ativar o estado de qualquer ponto da conversa, caso os detectores sejam correspondidos.
  ![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/cnZT3B8OZbzhC7dyvInsv_fluxoglobal.png)
- **Bloqueia avanço**: o sistema só avança após a resposta do usuário.
  ![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/2PAXWOoQQ54l5gI_5rK9V_bloqueioavanco.png)
- **Detectores**: palavras ou expressões que ativam um estado.



  ![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/EVdlxDzzW2O9nPr-o_ngJ_menudetectores1.png)
  ![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/UEHD1S3QlmCzfDHyMJSQb_menudetectores2.png)
- **Mensagens**: textos que o sistema exibe automaticamente quando o estado é ativado.
  :::BlockQuote
  Se houver mais de uma, uma delas será escolhida aleatoriamente.
  :::


  ![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/bMq7GuHKVaWiniDZy262h_menumensagens1.png)
  ![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/C3V04ERq845_tFWlALmQK_menumensagens2.png)
- **Textos de dúvida**: usados quando há mais de um estado possível e a intenção não está clara.
  :::BlockQuote
  A escolha entre as frases será aleatória, se houver mais de uma.
  :::


  ![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/jkxB31CFrstRwrpWjaVxz_menuduvida1.png)
  ![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/scHtq2NgJvkDRRa7SayGE_menuduvida2.png)
- **Textos de dúvida completa**: exibidos quando o sistema não consegue reconhecer nenhuma intenção com precisão.



  ![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/70uzyJBoViuTz4em9_I0n_menuduvidacompleta1.png)
  ![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/7__C6drFWcDibFULCgh7l_menuduvidacompleta2.png)
- **Automações**: ações automáticas disparadas ao ativar um estado (mensagens, chamadas de API, etc).



  ![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/QEG-xYgSpRZ0HnarsV5b2_menuautomacoes1.png)
  ![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/-_8gjWP2p7h7rOTavrSaM_menuautomacoes2.png)
- **Selecione os exemplos**: use exemplos criados para configurar os detectores de outros estados.
- **Selecione os estados**: defina para onde o fluxo pode seguir.



  ![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/_OLzyqOKU9V9nD78xEenh_menuselecionarestado.png)
  ![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/mz6wuqTzq2Nri-cjbQGki_estadolinkado.png)

## Editor de código

Permite criar e editar a skill diretamente por código, usando uma linguagem inspirada em Rust.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/JxZllIRYAIE6N7_hk3-eT_codigo.png)

Recursos disponíveis:

- Upload de uma skill existente
- Download da skill atual
- Testes do fluxo
- Salvamento de alterações

Consulte mais detalhes no [**guia completo**]().

## Excluir máquina de estado

Clique no ícone de lixeira.

:::BlockQuote
Atenção: a exclusão é permanente.
:::




![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/3QcS0Q_c6VYgR6yfQUALk_excluirworkspace2.png)

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/m6tzAZTIDXaVeYR4Ebe1b_excluirworkspace.png)


[title] Time
[path] Untitled/Customizações Avançadas/Bibliotecas/

Biblioteca para parsear tempo

## Atalhos

- [**Time**](docId\:T2HUDX4tiCibI5HKY6pjA)
- [**Time**](docId\:T2HUDX4tiCibI5HKY6pjA)

***

### Métodos

### Unix

```lua
-- example usage:

time.unix()

-- 1751394335
```

### Parse

```lua
-- @param timestamp The timestamp in integer to be parsing
time.parse(timestamp)
```

```lua
-- example usage:

time.parse(1751394335)

 -- {
  -- "hour": 18,
  -- "year": 2025,
  -- "month": 7,
 --  "seconds": 35,
 --  "month0": 6,
 --  "minutes": 25,
 --  "weekday0": 2,
 --  "day": 1
 -- }
```


[title] Manual de Atualização de um Ambiente Existente
[path] Untitled/Instalação/

## 1. Pré-requisitos

Antes de realizar a atualização de um ambiente, certifique-se de que os seguintes pré-requisitos estão atendidos:

- **Acesso VPN**: Necessário para conectar ao cluster do Aura-Blocks.
- **Cluster Kubernetes**: O cluster Kubernetes existente deve estar funcionando corretamente.
- **kubectl**: Ferramenta de linha de comando para interagir com o cluster.
- **Imagens Atualizadas**: Verifique as novas versões das imagens Docker que deseja aplicar na atualização.

## 2. Listando e Trocando o Namespace

Antes de realizar qualquer operação, é importante verificar os namespaces disponíveis no cluster e garantir que você está utilizando o namespace correto para o projeto.

### 2.1 Listar os Namespaces no Cluster

Utilize o comando abaixo para listar todos os namespaces no cluster Kubernetes:

```bash
kubectl get namespaces
```

Este comando exibirá todos os namespaces disponíveis. Certifique-se de identificar o namespace correto do projeto (ex: `aura-blocks`).

### 2.2 Definindo o Namespace para o Projeto

Para garantir que todos os comandos subsequentes serão executados no namespace correto, você pode configurar o namespace padrão a ser utilizado:

```bash
kubectl config set-context --current --namespace=aura-blocks
```

Este comando irá definir o namespace `aura-blocks` como o namespace padrão para todos os comandos kubectl executados na sessão atual.

## 3. Procedimento de Atualização

A atualização de um ambiente existente é feita principalmente pela troca das **tags das imagens Docker** nos manifests de Kubernetes. Abaixo estão os passos simples para realizar essa tarefa.

### 3.1 Atualizando as Imagens nos Manifests

### 3.1.1 Identificando os Manifests para Atualizar

Os arquivos de `Deployment` são os principais pontos onde as tags das imagens precisam ser atualizadas. Certifique-se de que os seguintes arquivos estão sendo modificados:

- `template/engine/deployment.yaml`
- `template/lowproxy/deployment.yaml`
- `template/lowtalk/deployment.yaml`
- `template/lunaris/deployment.yaml`
- `template/wanderson/deployment.yaml`

### 3.1.2 Atualizando a Tag da Imagem

Abra o arquivo do `Deployment` correspondente e modifique a seção `image`, substituindo a tag antiga pela nova tag da imagem.

Exemplo de atualização no arquivo `deployment.yaml` do serviço `engine`:

```yaml
containers:
  - name: engine
    image: aura-blocks/engine:<nova_tag>
    ports:
      - containerPort: 6060
```

Repita esse processo para os outros serviços (lowproxy, lowtalk, lunaris, wanderson), atualizando suas tags conforme necessário.

### 3.1.3 Aplicando as Mudanças

Depois de modificar as tags, aplique os manifests atualizados no cluster com o seguinte comando para cada serviço:

```bash
kubectl apply -f template/<serviço>/deployment.yaml
```

Exemplo:

```bash
kubectl apply -f template/engine/deployment.yaml
```

### 3.2 Reiniciando os Serviços

Após aplicar as mudanças, reinicie os serviços para garantir que os novos pods sejam iniciados com as imagens atualizadas. Use o comando `kubectl rollout restart` para cada serviço:

```bash
kubectl rollout restart deploy <deploy>
```

Exemplo:

```bash
kubectl rollout restart deploy env-engine
kubectl rollout restart deploy env-lowproxy
kubectl rollout restart deploy env-lowtalk
kubectl rollout restart deploy env-lunaris
kubectl rollout restart deploy env-wanderson
```

### 3.3 Verificando o Status

Após reiniciar os deployments, verifique o status dos recursos para garantir que os pods foram reiniciados corretamente com as novas versões das imagens:

```bash
kubectl get pods -n aura-blocks
```

Certifique-se de que os novos pods estão no estado `Running`.

### 3.4 Rollback (Se Necessário)

Caso algo não funcione como esperado após a atualização, você pode realizar um rollback para a versão anterior dos deployments. O rollback retorna o deployment à versão anteriormente aplicada.

Para realizar o rollback, utilize o comando:

```bash
kubectl rollout undo deploy <deploy>
```

Exemplo de rollback para o serviço `engine`:

```bash
kubectl rollout undo deploy env-engine
```

Repita o comando para os outros serviços conforme necessário, retornando as versões anteriores das imagens.

## 4. Conclusão

Com esses passos, o ambiente será atualizado com as novas versões das imagens. Acompanhe o comportamento dos serviços e, caso necessário, utilize o rollback para reverter mudanças problemáticas.

[title] Widget Customizável
[path] Untitled/Brokers/

A plataforma permite que desenvolvedores criem **widgets personalizados**, com total liberdade para escrever código.

## Customizando

É possível alterar a configuração padrão do widget utilizando a ferramenta de edição de código, permitindo ao desenvolvedor personalizar diretamente o CSS do widget.



## Configuração de um Widget

***

### Registro

**Endpoint:**
`POST /widgets/save/{name}`

:::BlockQuote
**Observações:*** O registro é obrigatório para utilizar qualquer funcionalidade.
* O registro deve ser feito utilizando o **LowCode** ou a **CLI Aura**.
:::

***

### Enviar Arquivo

**Endpoint:**
`POST /send-file/{widget_name}/{session_id}`

**Parâmetros:**

- `widget_name`: Nome do widget registrado.
- `session_id`: ID da sessão ativa.

***

### Enviar Mensagem

**Endpoint (WebSocket):**
`/ws/{widget_name}/{session_id}`

**Parâmetros:**

- `widget_name`: Nome do widget registrado.
- `session_id`: ID da sessão ativa.

***

### Histórico de Mensagens

**Endpoint:**
`GET /history/{widget_name}/{session_id}`

**Parâmetros:**

- `widget_name`: Nome do widget registrado.
- `session_id`: ID da sessão ativa.

***

### Download de Anexos

**Endpoint:**
`GET /widgets/{widget_name}/download/{ano}/{mes}/{dia}/{numero}.{ext}`

**Parâmetros:**

- `widget_name`: Nome do widget registrado.
- `ano`, `mes`, `dia`: Data do envio.
- `numero`: Identificador do anexo.
- `ext`: Extensão do arquivo (ex: `.pdf`, `.png`).

***

### Pré-visualização de Mensagens

**Endpoint de referência:**
`/receive-message`

:::BlockQuote
**Observações:**
Toda resposta enviada do sistema segue o formato da mensagem do tipo `ReceiveMessageFromEngine`, exibindo uma **prévia (preview)** do conteúdo.
:::

***

[title] Audio
[path] Untitled/Customizações Avançadas/Bibliotecas/

Biblioteca utilizada para realizar processamentos em áudio.

## Atalhos

- [**Audio**](docId\:JfeErBirXVrDk0EZ3A2oJ)

### Métodos

### convert

:::BlockQuote
Utiliza ffmpeg para a conversão.
:::

```lua
-- @param from_type representa o formato do áudio original a ser convertido
-- @param to_type representa o formato de destino do áudio 
-- @param bytes representa os bytes originais do áudio a ser convertido
-- @return bytes do áudio convertido
audio.convert(from_type, to_type, bytes)
```

```lua
-- example usage:
local mp3_bytes = "xxxyyyzzz..."

-- converte um áudio mp3 para ogg
local ogg_bytes = audio.convert("mp3", "ogg", mp3_bytes)
```


[title] Manual do widget
[path] Untitled/Customizações Avançadas/

**Widgets** são interfaces configuráveis que permitem personalizações como cores, imagens e nomes, tornando cada um deles único para o usuário. Entre as opções de personalização, você pode escolher a cor principal, adicionar um avatar, definir um título e até selecionar um papel de parede, entre outras possibilidades. Neste guia, explicaremos cada uma dessas configurações e mostraremos o processo de criação de um widget passo a passo.

O objetivo principal do widget é facilitar a comunicação entre o usuário final e nossa engine, ou até mesmo com nossa equipe de atendimento. Incorporado diretamente no site do cliente, o widget oferece praticidade e conveniência, eliminando a necessidade de acessar outros sites ou canais para interação.

# Como criar um widget

No menu **CITSmart Aura**, selecione a opção **Widget**.

![Acesso ao Widget](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/OuefOMYGRFVYQyIRLjvnF_acessarwidgets.png)

Uma página com todos os widgets já registrados será exibida. Para criar um novo, clique em **"Novo widget"**.

![Novo Widget](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/lcUyagnBlG6B9KfYzh1U__novowidget.png)

## Personalizando seu Widget

Após clicar em **"Novo Widget"** você será redirecionado para a página de personalização.

![Personalizar](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/ciUDrkI0RIbm0sRI7Ivml_personalizar.png)

Na página de personalização, preencha as seguintes informações para configurar o widget:

- **Nome do chat:** Nome exibido no topo do widget, ao lado do avatar.
- **Avatar do chat:** Imagem do avatar do chatbot, com tamanho máximo de **100x100 pixels**.
- **Cor principal:** Cor predominante do widget, visível no cabeçalho e rodapé.
- **Cor do título:** Cor do texto no cabeçalho do widget.
- **Cor da fonte:** Cor usada para o texto dentro do widget.
- **Cor usuário:** Cor usada para identificar as mensagens enviadas pelo usuário.
- **Cor atendente:** Cor usada para identificar as mensagens enviadas pelo atendente.
- **Papel de fundo:** É possível personalizar o papel de fundo do widget. Sendo possível escolher uma das quatro opções disponíveis para personalizar o fundo do widget.
- **Ícone do botão de acionamento:** É possível escolher entre quatro opções para personalizar o fundo do widget, com tamanho máximo de **100x100 pixels**

**Nota:** Para selecionar cores, clique na caixa de cor, e uma janela pop-up será exibida para escolher a cor desejada.

À medida que realiza as personalizações, uma pré-visualização aparecerá ao lado das configurações. Quando concluir, clique em **Salvar** para criar o widget.

## Editando um Widget

Para editar um **Widget** existente, siga os passos:

1. Na tela de listagem de widgets, encontre o widget que deseja modificar.
2. Clique no ícone de pincel  **Editar widget**.

![Editar](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/5uxGpO7jHccnj76074jYv_editar.png)

1. Faça as alterações necessárias na tela de edição.
2. Clique em **Salvar** para aplicar e registrar as mudanças.

## Excluindo um Widget

Para excluir um **Widget**, siga os passos abaixo:

1. Na tela de listagem, encontre o widget que deseja excluir.
2. Clique no ícone de lixeira ao lado do nome do widget.

![Excluir](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/xxxXb4Wu8jTzyDAkU922a_excluir.png)

1. Um modal de confirmação será exibido. Clique em **Sim** para confirmar a exclusão.

**Atenção:** Uma vez excluído, o widget não poderá ser recuperado. Para usá-lo novamente, será necessário criar um novo.

## Acessando o Widget

Após configurar e criar o widget, acesse a página de listagem. Nessa tela, você poderá visualizar todos os widgets criados.

Para abrir a interface do chatbot, clique em **"Link para o chat aplicado"**.

![Link de acesso](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/PKPC7hBWEB3ojlgka8Dw5_link.png)

Isso abrirá um link para a interface do seu chatbot.

![Interface do Chatbot](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/bmNFpSgcelL1572nfTZH__interfacechatbot.png)

# Criando comportamento para o Widget

Para que o widget responda às interações, é necessário registrar um comportamento. Siga os passos abaixo:

1. Acesse o menu **Chatbots**.

![Acesso ao chatbot](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/ml6qWCyr8X8xLCEgFLxlU_acessochatbot.png)

1. Caso ainda não possua, crie um **"Chatbot"** clicando em **"Novo Chatbot"**.

![Novo Chatbot](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/KI6Grwedhd1o_D9-iW7pH_novochatbot.png)

1. Insira o nome desejado e clique em **"Criar novo chatbot"**. Em seguida, clique no nome do chatbot recém-criado para acessá-lo.
2. No card **"Registrar novo comportamento"**, clique em **"Avançar"**.

![Registrar Comportamento](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/b6hoDQPaVF_1sR-xg5oss_registrarcomportamento.png)

1. Preencha o formulário de registro conforme indicado:

- **Nome do Comportamento:** Nome para identificar o comportamento.
- **Selecione o Manifesto:** Escolha o manifesto do tipo **"Widget"**.
- **Parâmetros:** Escolha o **Widget** que deseja cadastrar.

1. Confira o preenchimento das informações e clique em **"Concluir"** para registrar o comportamento.
   :::BlockQuote
   ⚠️ **Importante: Um widget só pode ser registrado em um único comportamento por vez**.
   Isso significa que **não é possível utilizar o mesmo widget simultaneamente em dois ou mais chatbots**.
   Para associar o mesmo visual ou configurações a múltiplos chatbots, será necessário criar widgets distintos para cada um.
   :::
   ![Preencher Comportamento](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/dZNRJUjknp4uGP2Rgf4Gs_preenchendocomportamento.png)
   :::BlockQuote
   **Atenção:** Para que o widget responda às interações, também é necessário cadastrar um comportamento do tipo **Wanderson** e selecionar a skill desejada. Para mais informações sobre esse cadastro, consulte o manual do operador.
   :::
2. Após registrar os comportamentos, volte para a listagem de widgets e clique em **"Link para o chat aplicado"** referente ao widget configurado. Isso abrirá a interface do seu chatbot e será possível realizar as interações desejadas.

[title] Untitled
[path] Untitled/


[title] Pipelines Lua
[path] Untitled/Customizações Avançadas/Bibliotecas/

# O que é?

O sistema de Pipelines permite criar interações conversacionais customizadas através de scripts em Lua podendo ser utilizada como uma ferramenta de linha de comando ou como um servidor. De forma simplificada pode ser entendido como um questionário que é definido através de scripts Lua.

# Como funciona uma Pipeline?

Para utilizarmos o sistema, primeiramente devemos criar uma pasta em nosso sistema operacional que será utilizada para armazenar todos os nossos workspaces, cada um contem os seus respectivos scripts Lua. Após isso criamos outra pasta que vai conter o nosso projeto especifico.

:::BlockQuote
O nome da pasta não é restritivo, mas para fins didáticos vou me referir a ela como **workspaces**.
:::

Exemplo: `workspaces/projeto-exemplo`

## Passo um: criação da tabela de pipelines

A tabela de pipelines é especial e **deve ser definida uma única vez no workspace**, ela é responsável pela definição de quais são as pipelines presentes no workspace.

Vamos começar criando uma arquivo Lua `main.lua` dentro de um workspace conforme exemplo acima.

```lua
-- Arquivo main.lua

PIPELINES = {
  "questionario_dados_pessoais",
  "consultar_chamado"
}
```

Acima criamos a tabela `PIPELINES` que informa ao sistema a existência de duas pipelines: `questionario_dados_pessoais` e `consultar_chamado`.

## Passo dois: definição de uma pipeline

Vamos agora definir a pipeline `questionario_dados_pessoais`, para isso devemos criar a tabela própria da pipeline contendo as perguntas que ela possui.

```lua
-- Arquivo main.lua

PIPELINES = {
  "questionario_dados_pessoais",
  "consultar_chamado"
}

questionario_dados_pessoais = {
  "perguntar_nome",
  "perguntar_idade",
}
```

Perceba que os nomes devem corresponder nas tabelas de `PIPELINES` e em sua própria definição.

## Passo tres: definição das perguntas

Cada pergunta é representada por uma tabela com o seu respectivo nome que foi definido acima, a tabela contem quatro campos:

- `output` é a resposta da pergunta atual.
- `show` define se a pergunta deve ser feita ou não
- `select` é um conjunto de possíveis escolhas mostrada ao usuário junto ao *output*. O *label* é a frase mostrada de cada opção, no qual há um número *id* associado respectivamente.
- `accept` define se a pergunta atual atende condições especificas e pode ser mostrada.
- `reject` é a resposta da pergunta atual caso o `accept` seja falso.

Exemplo completo.

```lua
-- Arquivo main.lua

PIPELINES = {
  "questionario_dados_pessoais",
  "consultar_chamado"
}

questionario_dados_pessoais = {
  "perguntar_nome",
  "perguntar_idade",
  "perguntar_localidade"
}

-- Pergunta simplificada
perguntar_nome = {
  output = "Olá, qual é o seu nome?", -- string
  show = true,                        -- boolean
  accept = true,                      -- boolean
  reject = "Mensagem de rejeição"     -- string
}

-- Pergunta com condições
perguntar_idade = {
  output = function(respostas)
    -- O output pode ser um função caso deseje utilizar as respostas
    -- anteriores
    return "Olá" .. respostas.perguntar_nome .. ", qual é a sua idade?"
  end,
  show = function(respostas)
    -- O show pode ser uma função caso deseje fazer alguma condição para
    -- determinar se o sistema deve fazer essa pergunta ao usuário ou não
    if respostas.perguntar_nome == "Felipe" then
      -- se a resposta da primeira pergunta for Felipe
      -- o sistema não vai perguntar sua idade
      return false
    end
    return true
  end,
  accept = function(atual, repostas)
    -- Aqui definimos condições para aceitar o input do usuário
    -- baseado na resposta atual ou anteriores
    if tonumber(atual) < 18 then
      return false
    end
    return true
  end,
  reject = function(atual, respostas)
    -- Podemos usar a reposta atual e as anteriores para rejeitar
    -- a resposta do usuário
    return "Digite uma idade maior " .. respostas.perguntar_nome
  end,
}

perguntar_localidade = {
  output = "Localidade:",
  show = true,
  accept = true,
  select = {
    { label = "Acre", id = 2},
    { label = "Alagoas", id = 3 },
    { label = "Amapá", id = 4},
    { label = "Distrito Federal", id = 5},
    { label = "Espírito Santo", id = 6},
    { label = "Goiás", id = 7},
    { label = "Maranhão", id = 8},
    { label = "Mato Grosso", id = 9},
    { label = "Mato Grosso do Sul", id = 10},
    { label = "Minas Gerais", id = 11},
    { label = "Pará", id = 12},
    { label = "Paraíba", id = 13},
    { label = "Paraná", id = 14},
    { label = "Pernambuco", id = 15},
    { label = "Piauí", id = 16},
    { label = "Rio de Janeiro", id = 17},
    { label = "Rio Grande do Norte", id = 18},
    { label = "Rio Grande do Sul", id = 19},
    { label = "Rondônia", id = 20},
    { label = "Roraima", id = 21},
    { label = "Santa Catarina", id = 22},
    { label = "São Paulo", id = 23},
    { label = "Sergipe", id = 24},
    { label = "Tocantins", id = 25},
  },
  reject = "Mensagem de rejeição" 
}
```

# Estrutura de projeto e biblioteca global

Dentro da pasta usada para guardar os workspaces, é possível criar um projeto especial com o nome `lib_global` que compartilha todo o seu conteúdo com os outros projetos e repositórios, ele pode ser usado para escrever funções utilitárias que são usadas amplamente em todos os outros projetos por exemplo.

Estrutura de exemplo:

```txt
workspaces
├── cliente-x
│	├── arquivo_x.lua
│	├── arquivo_g.lua
│   └── subpasta_x
│       ├── arquivo_t.lua
│       ├── arquivo_y.lua
├── cliente-y
│	├── arquivo_t.lua
│   └── subpasta_z
│       ├── arquivo_t.lua
│       ├── arquivo_y.lua
└── lib_global
	├── arquivo_h.lua
    └── subpasta
        ├── cnbbb.luaa
```

Como pode-se ver a estrutura de pastas dentro de cada projeto é livre para se decidir e usar da forma que preferir.

# Bibliotecas disponíveis no Lua

Os seguintes pacotes vão estar disponíveis no ambiente de desenvolvimento através do LuaRocks.

- [**lua-cjson**](https://luarocks.org/modules/openresty/lua-cjson)
- [**http**](https://luarocks.org/modules/daurnimator/http)
- [**xml2lua**](https://github.com/manoelcampos/xml2lua)
- [**inspect**](https://luarocks.org/modules/kikito/inspect)
- [**base64**](https://luarocks.org/modules/iskolbin/base64)
- [**urlencode**](https://luarocks.org/modules/moznion/urlencode)
- [**openssl**](https://luarocks.org/modules/zhaozg/openssl)

Alem dos pacotes externos está disponível também as seguintes bibliotecas de sistema:

- [**TABLE**](https://www.lua.org/manual/5.4/manual.html#6.6)
- [**STRING**](https://www.lua.org/manual/5.4/manual.html#6.4)
- [**COROUTINE**](https://www.lua.org/manual/5.4/manual.html#6.2)
- [**PACKAGE**](https://www.lua.org/manual/5.4/manual.html#6.3)
- [**MATH**](https://www.lua.org/manual/5.4/manual.html#6.7)
- [**DEBUG**](https://www.lua.org/manual/5.4/manual.html#6.10)

# Formas de execução do sistema

O sistema de pipelines possui duas formas de ser executado, ferramenta de linha de comando (CLI) e servidor HTTP.

:::BlockQuote
O sistema pode ser instalado localmente usar o seguinte comando no local do repositório:
`cargo install --path .`
:::

## Repl (CLI)

Modo de linha de comando.

Comando para se executar no modo de linha de comando:

```bash
cargo run repl --client <CLIENT> --pipeline <PIPELINE>
```

Descrição dos parâmetros

```bash
-w, --workdir <WORKDIR>    Workspaces directory, uses current dir as default
-c, --client <CLIENT>      Client name
-p, --pipeline <PIPELINE>  Pipeline name
-h, --help                 Print help
-V, --version              Print version
```

## Server

Modo de servidor HTTP.

Comando para se executar no modo servidor:

```bash
cargo run server --port <PORT> --username <USERNAME> --password <PASSWORD>
```

Descrição dos parâmetros

```bash
-W, --workdir <WORKDIR>  Workspaces directory, uses current dir as default
-S, --sync               Synchronize with Git
-P, --port <PORT>        Server port
-u, --username           Username
-p, --password           Password
-h, --help               Print help
-V, --version            Print version
```

:::BlockQuote
IMPORTANTE: para se utilizar a sincronização com git é necessário configurar o arquivo `Config.toml` dentro do seu diretório utilizado como `workdir` utilizando o seguinte modelo:
:::

Exemplo de arquivo `Config.toml`

```toml
[cliente-xpto]
url = "https://github.com/centralit-governanca-corporativa/cliente-xpto.git"
username = "git-user"
password = "secret-password"

[nome-do-cliente]
url = "url-do-github"
username = "git-user"
password = "secret-password"
```

### Documentação da API

A API suporta requisições para quatro recursos diferentes:

### Workspaces

Recursos utilizados para manipular os workspaces.

### Reload All Workspaces

- **Method:** GET
- **Endpoint:** `/workspace/reload`
- **Description:** Reloads all workspaces

### Reload One Workspace

- **Method:** GET
- **Endpoint:** `/workspace/reload/{client}`
- **Description:** Reloads a specific workspace identified by the client.

### Git

Recursos utilizados para se sincronizar o GIT.

### Sync All Repositories

- **Method:** GET
- **Endpoint:** `/git/sync`
- **Description:** Synchronizes all Git repositories.

### Sync One Repository

- **Method:** GET
- **Endpoint:** `/git/sync/{client}`
- **Description:** Synchronizes a specific Git repository identified by the client.

### Conversation

Recursos utilizadas para interagir com as conversas.

:::BlockQuote
IMPORTANTE: Esse recurso está protegido por `Basic auth`, as credenciais são as mesmas utilizadas na inicialização do servidor.
:::

### Create Conversation

- **Method:** POST
- **Endpoint:** `/conversation/spawn/{client}/{pipeline}/{conversation_uuid}`
- **Authentication**: Basic auth
- **Description:** Creates a new conversation instance within a specific pipeline and conversation\_uuid for the given client.

### Process Conversation

- **Method:** POST
- **Endpoint:** `/conversation/process/{conversation_uuid}`
- **Authentication**: Basic auth
- **Description:** Processes the specified conversation within the given pipeline for the client.

**Body**:

```json
{ input: "User input here" }
```

### Has Conversation

- **Method:** GET
- **Endpoint:** `/conversation/{conversation_uuid}`
- **Authentication**: Basic auth
  - **Description:** Verify if a conversation within a specific conversation\_uuid exists.

## Exposição de funções para Web

É possível expor funções que podem ser chamadas através de endpoints específicos que serão consumidos por outros serviços que desejem se comunicar com nosso sistema pelos protocolos http.

Para expor alguma função primeiro é necessário declarar uma tabela. Essa tabela pode ser declarada dentro de um arquivo que já contenha um fluxo conversacional das pipelines ou pode ser criado em um arquivo separado dentro da pasta do projeto.

Para nosso exemplo, criaremos um arquivo chamado webservice `workspaces/projeto-exemplo/webservice.lua`

Dentro do arquivo temos 5 (cinco) tabelas.

```lua
-- Arquivo webservice.lua

ALLOW_GET_ROUTES = {}
ALLOW_POST_ROUTES = {}
ALLOW_PUT_ROUTES = {}
ALLOW_PATCH_ROUTES = {}
ALLOW_DELETE_ROUTES = {}
```

Cada tabela corresponde a um método HTTP (GET, POST, PUT, PATCH e DELETE).

Agora vamos criar uma função dentro desse arquivo.

```lua
-- Arquivo webservice.lua

function teste() 
  return "Hello Word"
end

```

Com a função criada, precisamos expô-la para que seja acessada via web. Neste caso vamos expô-la para que seja acessada pelo método GET.

```lua
-- Arquivo webservice.lua

ALLOW_GET_ROUTES = {
  "teste"
}
ALLOW_POST_ROUTES = {}
ALLOW_PUT_ROUTES = {}
ALLOW_PATCH_ROUTES = {}
ALLOW_DELETE_ROUTES = {}

function teste() 
  return "Hello Word"
end
```

Dessa forma, podemos acessar essa função construindo a URL abaixo:

`http://dominio-exemplo/get/projeto-exemplo/teste`

- **dominio-exemplo**: domínio que roda o sistema
- **get**: constitui a url para informar que iremos buscar uma função declarada no ALLOW\_GET\_ROUTES
  \-- O método http também deve ser o GET
- **projeto-exemplo**: Nome do projeto em que o arquivo webservice.lua se encontra
- **teste**: nome da função que você deseja acessar.

Chamado então esse endpoint, você receberá como reposta o que foi retornado na função `Hello Word`.

### IMPORTANTE

### Todas as funções recebem 3 (três) parâmetros. O primeiro são os headers da requisição, o segundo os query params e o terceiro o body.

Dessa forma podemos modificar nossa função afim de receber esses parametros e realizar alguma lógica utilizando-os.

```lua
-- Arquivo webservice.lua

ALLOW_GET_ROUTES = {
  "teste"
}
ALLOW_POST_ROUTES = {}
ALLOW_PUT_ROUTES = {}
ALLOW_PATCH_ROUTES = {}
ALLOW_DELETE_ROUTES = {}

function teste(headers, query) 
  --lógica a ser aplicada com os parâmetros
  return "Hello Word"
end
```

### OBSERVAÇÃO 1: Caso você use o parâmetro query e no endpoint não seja enviado query params, ela estará vázio.

### OBSERVAÇÃO 2: Caso você declare um terceiro parâmetro na função ele será entendido como o body da requisição, e no caso do método HTTP GET, que não há body, ele virá como uma string vazia.

Vamos agora criar outra função para ser chamada via método HTTP POST.

Criaremos a função consulta\_autorizacao no mesmo arquivo que estávamos `webservice.lua`. Essa função receberá os 3 (três) parâmetros citados acima. Ela será exposta na tabela ALLOW\_POST\_ROUTES para estar disponível para acesso via HTTP.

```lua
-- Arquivo webservice.lua

ALLOW_GET_ROUTES = {
  "teste"
}

ALLOW_POST_ROUTES = {
  "consulta_autorizacao"
}

ALLOW_PUT_ROUTES = {}

ALLOW_PATCH_ROUTES = {}

ALLOW_DELETE_ROUTES = {}

function teste()
  return "Hello Word"
end

function consulta_autorizacao(headers, query, body) 
  --lógica para consultar alguma autorização
  return "Autorizado"
end
```

O endpoint para chamar a função que criamos agora é `http://dominio-exemplo/post/projeto-exemplo/consulta_autorizacao`. Lembrando que essa função foi exposta no ALLOW\_POST\_ROUTES, sendo assim é necessário que você utilize o método HTTP POST e na construção da url, após o dominio-base, você deverá insirir /post/ para que sua função seja chamada corretamente.

[title] Twilio
[path] Untitled/Brokers/

Para cadastrar o broker Twilio é necessário o número de telefone do enviador, SID e token da conta. No caso de teste, o Twilio oferece um número de teste pelo Sandbox, para usar um número real é preciso fazer um upgrade da conta.

### 1. Criar uma conta

Através do link abaixo, se inscreva no Twilio

[**link de acesso**](https://www.twilio.com/login?iss=https%3A%2F%2Flogin.twilio.com%2F)

### 2. Enviar e Receber Mensagem no SandBox (para teste)

Para se conectar com o número oferecido, envie a mensagem para o número informado, no caso da imagem abaixo seria a mensagem "join freedom-desert".

Para ser informado de novas mensagens pela Engine, cadastre o webhook na aba ao lado "SandBox settings" com endereço **https\://\{endereço\_do\_lunaris}/post/twilio/webhook**.

O contato desta conta é  **14155238886**, como mostrado na imagem.

![sandbox](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/Af_YUscRKDIQhjBXvpvfc_twiliosandbox.png)

### 3. Cadastrar Webhook da Conta

No caso de um número real, faça upgrade da conta como na figura abaixo. Depois, pode cadastrar o link do webhook. No caso de número fictício ou real, este será o cadastrado nas configurações do Broker.

![webhook](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/NFr5aDUnqDeLgb5TVf-Kk_twiliowebhook.png)

### 4. Obter SID e Token da conta

[**link de acesso**](https://console.twilio.com/us1/account/manage-account/general-settings)

Na parte de configurações, em Keys & Credentials, na parte de Live credentials consegue-se obter o SID da conta, o Auth Token.

![sid\_token](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/O9mfgIjm9XsqDqSRlr7ns_twiliosidtoken.png)

[title] Untitled
[path] Untitled/


[title] Untitled
[path] /


[title] Base 64
[path] Untitled/Customizações Avançadas/Bibliotecas/

Utilizado para codificar e decodificar valores no formato Base64.

## Atalhos

- [**Base 64**](docId\:ZY-AdGDl_9OG__QUBaCth)
- [**Base 64**](docId\:ZY-AdGDl_9OG__QUBaCth)

***

### Métodos

### Decode

```lua
-- @param value The value to be decoded.
-- @return string containing the decoded value
base64.decode(value)
```

```lua
-- example usage:

local decoded_value = base64.decode("aGVsbG8gd29ybGQh")

-- hello world!
```

### Encode

```lua
-- @param value The value to be encoded.
-- @return string containing the encoded value
base64.encode(value)
```

```lua
-- example usage:

local encoded_value = base64.encode("hello world!")

-- aGVsbG8gd29ybGQh
```


[title] Form
[path] Untitled/Customizações Avançadas/Bibliotecas/

Biblioteca utilizada para converter bytes em um array de bytes formatado como multipart/form-data, que
é o padrão para envio de arquivos e dados em requisições HTTP.

## Atalhos

- [**Form**](docId\:ZNRe7o0QnJbWjblnNBIoZ)

***

### Métodos

### Encode

```lua
-- @param fields é uma table contendo os campos do formulário. Nessa table pode ser entregue strigs e tabelas.
--               As strings são tratadas como campos de texto e as tabelas devem conter um campo "bytes".
--               Opcionalmente, pode-se incluir "filename" e "mime" para arquivos.
-- @return Uma table contendo "body"  e "content_type" (o cabeçalho Content-Type).
encode(fields)
```

```lua
-- example usage:

local form_data = form.encode({
    language = "pt", 
    audio_file = {
        bytes = "conteúdo do arquivo em bytes",
        filename = "meuarquivo.mp3",
        mime = "audio/mpeg"
    }
})

print(form_data.body)         -- Conteúdo codificado do formulário para ser enviado como BODY
print(form_data.content_type) -- Content-Type para ser configurado no HEADERS
```


[title] Mime
[path] Untitled/Customizações Avançadas/Bibliotecas/

Utilizado para converter extensão de arquivos em MIME type, ou um MIME type em extensão de arquivo.

## Atalhos

- [**De extensão para MIME type**]()
- [**De MIME type para extensão**]()

***

### Métodos

### from\_ext

```lua
-- @param ext Extensão do arquivo que deseja converter para mime type
-- @return string: MIME type correspondente à extensão
mime.from_ext(ext)
```

```lua
local mimetype = mime.from_ext("png")
print(mimetype) -- saída: image/png
```

### into\_ext

````lua
-- @param mimetype Mimetype utilizado para converter em extensão
-- @return string: Extensão correspondente ao MIME type
mime.into_ext(mimetype)

```lua
local ext = mime.into_ext("application/json")
print(ext) -- saída: json
````


[title] String
[path] Untitled/Customizações Avançadas/Bibliotecas/

Funções auxiliares adicionais as da Std lib String do lua.

## Atalhos

- [**String**](docId\:G3R8KpZlVbseyp8XjPMNo)

***

### Métodos

### Split

```lua
-- @param str The string to be splited.
-- @param pattern The string to be used as pattern.
-- @returns Table containing the splited strings
string.split(str, pattern)
```

```lua
-- example usage:
local my_string = "my string here"

local result = string.split(my_string, " ")

-- {"my", "string", "here"}
```


[title] Html to PDF
[path] Untitled/Customizações Avançadas/Bibliotecas/

Utilizado para criar PDF através de HTML.

## Atalhos

- [**Html to PDF**](docId\:GxposN1Z303i53DGvr51h)
- [**Html to PDF**](docId\:GxposN1Z303i53DGvr51h)

***

### Métodos

### From string

```lua
-- @param html The string containing the HTML.
-- @returns The bytes of the generated PDF
htmltopdf.from_string(html)
```

```lua
-- example usage:

local html = "<html><body><h1>Meu HTML em PDF</h1></body></html>"

local bytes = htmltopdf.from_string(html)
```

### From url

```lua
-- @param url The url to get the HTML
-- @returns The bytes of the generated PDF
htmltopdf.from_url(url)
```

```lua
-- example usage:

local bytes = htmltopdf.from_url("https://www.google.com/")

```


[title] Task
[path] Untitled/Customizações Avançadas/Bibliotecas/

Módulo utilizado para criar tasks assíncronas.

## Atalhos

- [**Task**](docId\:HT2LhJwRBsyn-qcwapW4i)

***

### Métodos

### spawn

:::BlockQuote
Ao criar um **loop infinito** dentro de uma task assíncrona, é necessário **inserir intervalos de tempo** para que outras tasks concorrentes possam ser executadas.
O sistema de **servidor e pipelines** é considerado uma **task concorrente**, portanto, uma **task mal estruturada pode bloqueá-los**.
:::

````lua
-- @param fn: function
-- Executa a função passada como argumento em uma nova task.
task.spawn(fn)


```lua
-- example usage:

function foo()
    while true do
        print("Executando em uma task assíncrona!")
        sleep.secs(5) -- pausa de 5 segundos inserida para permitir a execução de outras tasks concorrentes
    end
end

task.spawn(foo)

print("Essa mensagem será exibida antes ou depois da task, dependendo do agendamento.")
````


[title] JSON
[path] Untitled/Customizações Avançadas/Bibliotecas/

A biblioteca JSON fornece funções para codificar e decodificar valores JSON em Lua, permitindo a conversão entre tabelas Lua e strings JSON.

## Atalhos

- [**JSON**](docId\:OZFlYt9SMsSycpE0m4vvi)
- [**JSON**](docId\:OZFlYt9SMsSycpE0m4vvi)

***

### Métodos

### Decode

```lua
-- @param value The value to be decoded.
-- @return string containing the decoded value
json.decode(value)
```

```lua
-- example usage:

local decoded = json.decode('{"xxx": "yyy"}')
```

### Encode

```lua
-- @param value The value to be encoded.
-- @param @optional empty_as_array Boolean that defines if an empty table should be encoded as an array, defaults to false.
-- @return string containing the encoded value
json.encode(value, empty_as_array)
```

```lua
-- example usage:

local encoded = json.encode({xxx = "yyy"})
```


[title] Logs
[path] Untitled/Customizações Avançadas/Bibliotecas/

Este módulo é responsável pela geração de logs durante o tempo de execução da aplicação. Os logs são registrados em um arquivo, utilizando o formato chave-valor.

## Atalhos

- [**Logs**](docId\:YCeYigLFa54z8iA80A0Yh)

***

### Métodos

### Log

```lua
-- @param identifier The identifier of the log
-- @param value The value to be logged.
log(identifier, value)
```

```lua
function process_data(a)
    -- Perform some operations (this can be customized)
    -- For the sake of this example, we will simply pass the variable through unchanged.

    log("PROCESSING", a)

    return a
end

-- Assuming the variable "a" has the value of 42:
local a = 42

-- When the function is called, the log entry generated would look like this:
-- [2025-02-13 18:03:37.137227800 -03:00 "PROCESSING"]: 42

```


[title] Blob
[path] Untitled/Customizações Avançadas/Bibliotecas/

Bliblioteca utlizada para obtenção dos bytes de um arquivo a partir de seu caminho.

## Atalhos

- [**Blob**](docId\:WFJj0Tv_AEwUh0W-Mp2AK)

### Métodos

### load

```lua
-- @param string representando o caminho do arquivo
-- @return bytes do arquivo.
blob.load("./caminho_da_imagem.png")
```

```lua
-- example usage:

local image_bytes = blob.load("./my_image_path.png")

-- image_bytes = "�����"
```


[title] HMAC
[path] Untitled/Customizações Avançadas/Bibliotecas/

Utilizado para gerar tokens HMAC com os algoritmos de criptografia SHA 256, SHA 512 ou SHA 1.

## Atalhos

- [**SHA-512**]()
- [**SHA-256**]()
- [**SHA-1**]()

***

### Métodos

### New SHA 256

```lua
-- @param secret The secret used to create the HMAC.
-- @param input The input used to create the HMAC.
-- @return bytes that can be transformed into base64 on hex string to be used.
hmac["SHA256"].new(secret, input)
```

```lua
-- example usage:

local my_hmac = hmac["SHA256"].new("secret", "input")


local hmac_base64 = base64.encode(my_hmac)
-- jYmF0Et6vTLLqjd5o9qgGeDSaaIq7BWvjnKW9wLMaMY=

local hmac_hex = x:gsub(".", function(s)
    return string.format("%02x", string.byte(s))
end)
-- 8d8985d04b7abd32cbaa3779a3daa019e0d269a22aec15af8e7296f702cc68c6
```

### New SHA 512

```lua
-- @param secret The secret used to create the HMAC.
-- @param input The input used to create the HMAC.
-- @return bytes that can be transformed into base64 on hex string to be used.
hmac["SHA512"].new(secret, input)
```

```lua
-- example usage:

local my_hmac = hmac["SHA512"].new("secret", "input")


local hmac_base64 = base64.encode(my_hmac)
-- Ksle03F+BCxwZKX6fDGCMM022F4G+P+Dc9BMoX42Fingn0a38VH/OCo/SMWxkSFEbkXCWI8P8d6fdLBADa74Hw==

local hmac_hex = x:gsub(".", function(s)
    return string.format("%02x", string.byte(s))
end)
-- 2ac95ed3717e042c7064a5fa7c318230cd36d85e06f8ff8373d04ca17e361629e09f46b7f151ff382a3f48c5b19121446e45c2588f0ff1de9f74b0400daef81f
```

### New SHA 1

```lua
-- @param secret The secret used to create the HMAC.
-- @param input The input used to create the HMAC.
-- @return bytes that can be transformed into base64 on hex string to be used.
hmac["SHA1"].new(secret, input)
```

```lua
-- example usage:

local my_sha1_hmac = hmac["SHA1"].new("secret", "input")
```


[title] Atendimento humano
[path] Untitled/Interlocutores/

:::BlockQuote
Este manual fornece orientações sobre como utilizar as funcionalidades da ferramenta de atendimento, incluindo a gestão de filas e a criação de atalhos de texto.
:::

## Atendimentos

:::BlockQuote
Esta funcionalidade está disponível apenas para o papel de **Atendente**.
:::

A área de atendimento humano é composta por três seções principais, cada uma desempenhando um papel crucial na gestão de interações com os usuários. Abaixo estão as descrições de cada seção:

![Tela dos Atendimentos](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/1nslM3zxTFgGY2l7gS-HG_atendimentos.png)

- **Em atendimento** - Exibe os atendimentos que já foram capturados e estão em progresso.
- **Em espera** - Mostra os atendimentos que ainda não foram capturados e estão disponíveis para atendimento.
- **Finalizados** - Apresenta o histórico de atendimentos concluídos pelo atendente.

### Em espera

Para capturar um atendimento disponível, clique na opção **"Realizar atendimento"**, como mostrado na imagem abaixo:

![Capturar Atendimentos](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/d-7rKp8LV5qpZLN5wg7n2_atendimentocapturar.png)

Ao selecionar essa opção, a solicitação será movida para a seção **"Em atendimento"**, ficando acessível apenas para o atendente que efetuou a captura.

### Em atendimento

Ao clicar em **"Realizar atendimento"**, o atendimento será automaticamente movido para a aba **"Em Atendimento"**, onde o atendente poderá prestar um suporte personalizado ao usuário que necessita de assistência.

![Atender Solicitação](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/yPzKGwMTk0xLnf1xz_Ho8_atendimentosatender.png)

### Tela de interação com o usuário

Nesta tela, o atendente pode se comunicar diretamente com o usuário em tempo real, trocando mensagens, enviando arquivos de áudio, imagens (PNG, JPG, JPEG), documentos (PDF, Word, Excel) e emojis, além de utilizar atalhos de texto para respostas rápidas.

![Tela de Interação](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/Psoo9l2axLHf7cbDq-25z_telaatendente.png)

Veja as opções disponíveis nessa tela:

- **Transferir:** Durante o atendimento é possível transferir a solicitação da seguinte maneira:
  - **Transferir para outro fila:** Permite transferir o atendimento de uma fila para outra fila, garantindo que o usuário seja encaminhado ao setor mais adequado para sua demanda.
  - **Transferir para outro atendente:** Possibilita a transferência do atendimento para um atendente específico, assegurando um suporte mais eficiente e direcionado.

![Transferir](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/QGyd-cXUVLZKHq7aPwBCt_telaatendentetransferir.png)

- **Finalizar**: Encerra o atendimento específico, registrando o histórico da conversa e mantendo o atendente disponível para continuar outros atendimentos simultaneamente.
- **Emojis**: Essa opção permite que atendentes e usuários utilizem emojis para tornar a comunicação mais interativa, expressiva e dinâmica.
- **Upload de arquivos**: Possibilita enviar arquivos e documentos durante o atendimento.
- **Upload de áudio**: Permite o envio de arquivos de áudio durante o atendimento humano, facilitando a comunicação e proporcionando uma alternativa eficiente para esclarecer dúvidas ou fornecer informações de forma mais dinâmica.
- **Atalhos**: Possibilita enviar os atalhos de texto criados.
- **User infor**: Ao abrir o menu lateral, serão exibidas as informações do usuário, incluindo nome completo, e-mail, telefone e o canal de acesso utilizado. Além disso, poderão ser apresentadas outras informações relevantes, como o histórico de interações.

![Userinfo](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/Usgb81IOw2AB8NcrtX8O__telauserinfo.png)

### Finalizados

Esta seção exibe o histórico dos atendimentos concluídos, permitindo que você revise as mensagens trocadas e os detalhes de cada atendimento para acompanhamento e análise. Para auditar, basta clicar no atendimento desejado ou usar a opção de pesquisa na lupa ("pesquise aqui") para localizar o atendimento que deseja revisar.

![Atendimentos Finalizados](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/evA5_BgeZc-1a2f0_FT-Y_atendimentosfinalizados.png)

## Configurando o atendimento humano no Chatbot

Para configurar o atendimento humano no seu chatbot, é preciso adicionar o comportamento **Atendimento humano** e, em seguida, associar um mediador (broker). Abaixo, você vai encontrar o passo a passo para:

1. Registrar o comportamento do **atendimento humano**.
2. Vincular o **mediador (broker)**.
3. Integrar bot + atendimento humano com a **Máquina de Estados**.

### Pré-requisitos

Antes de iniciar, verifique se os seguintes itens já estão configurados:

- **Fila de atendimentos:** Crie uma fila de atendimentos e cadastre os atendentes.
- **Chatbot:** Crie um chatbot ou acesse um já existente.
- **Máquina de estados (Skill):** Certifique-se de ter criado uma skill para registrar no chatbot. Veja como criar sua NLU [**Máquina de estados**](docId\:kHKqalyFRyZYoyuGcL7oL).
- **Mediador (Broker):** É necessário escolher ao menos um broker para ser registrado no chatbot. Os brokers disponíveis são:
  `botmaker`, `gupshup`, `messenger`, `positus`, `slack`, `teams`, `telegram`, `twilio` e `widget`. Neste exemplo, usaremos o **Widget**. Se ainda não tiver um, crie-o seguindo este [**Manual do widget**](docId\:y4PJDkvomuu6KVeCcpZTA).

## Passo 1 – Registrar atendimento humano no chatbot

1. No menu **Chatbot**, selecione o bot que deseja configurar.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/_NnVo8xVe2nH5VOaucob2_acessarchatbot.png" signedSrc="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/_NnVo8xVe2nH5VOaucob2_acessarchatbot.png" size="100" caption alt="Acessar chatbot" isUploading="false" sha initialPath="img/atendimento_humano/acessar_chatbot.png" githubPath="Documentação CITsmart Aura/img/atendimento_humano/acessar_chatbot.png" width="1569" height="454" darkWidth="1569" darkHeight="454" indent="2"}

2. Localize a opção **Registrar novo comportamento** e depois clique em **Avançar**.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/kUkG74fMwqvyceDTXvIid_registrarcomportamento.png" signedSrc="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/kUkG74fMwqvyceDTXvIid_registrarcomportamento.png" size="100" caption alt="Registrar comportamento" isUploading="false" sha initialPath="img/atendimento_humano/registrar_comportamento.png" githubPath="Documentação CITsmart Aura/img/atendimento_humano/registrar_comportamento.png" width="893" height="597" darkWidth="893" darkHeight="597" indent="2"}

3. Na tela de cadastro, preencha:

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/wqfgLPwsIF4PijnhWdxeZ_preenchendocampos.png" signedSrc="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/wqfgLPwsIF4PijnhWdxeZ_preenchendocampos.png" size="100" caption alt="Preenchendo campos" isUploading="false" sha initialPath="img/atendimento_humano/preenchendo_campos.png" githubPath="Documentação CITsmart Aura/img/atendimento_humano/preenchendo_campos.png" width="682" height="506" darkWidth="682" darkHeight="506" indent="2"}

## Passo 2 – Vincular o Mediador (Broker)

**Observação:** Crie o broker (no nosso exemplo, o Widget) antes de registrar no chatbot. Veja como em [**Manual do widget**](docId\:y4PJDkvomuu6KVeCcpZTA).

1. No mesmo chatbot, localize a opção **Registrar novo comportamento** e clique em **Avançar**.
2. Informe o **Nome do comportamento**.
3. Em **manifesto**, selecione **Widget** e avance.
4. Em **Parâmetros**, escolha o widget criado e conclua.

Pronto! Após a configuração do broker, já é possível transferir o usuário para o atendimento humano.

**Observação:** Verifique em **Iniciar a conversa no comportamento** se o **Atendimento humano** está selecionado. Caso contrário, escolha-o e clique em **Salvar**.

![Iniciar comportamento](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/j2FscermWaYg9s10ZFUE__iniciarcomportamento.png)

## Integração Bot + Atendimento humano + Máquina de estados

Para que o atendimento humano funcione integrado ao bot, é necessário registrar uma máquina de estados e configurar o estado responsável pela transferência. Siga os passos abaixo para realizar essas configurações.

### Passo 1 – Registrar máquina de estados (Skill)

**Observação:** Crie uma skill antes de registrar no chatbot. Consulte as instruções [**Máquina de estados**](docId\:kHKqalyFRyZYoyuGcL7oL).

1. No chatbot, localize a opção **Registrar novo comportamento** e clique em **Avançar**.
2. Informe o nome do comportamento a ser criado.
3. Em **Manifesto**, selecione **Máquina de estados** e avance.
4. Em **Parâmetros**:
   1. Escolha o **Workspace**.
   2. Selecione a **Skill**.
   3. Finalize em **Concluir**.

**A máquina de estados foi registrada em seu chatbot**

### Passo 2 – Configurar fila de atendimentos no fluxo

Agora é preciso configurar a fila de atendimentos **dentro do fluxo** da Máquina de Estados, para isso, siga os passos abaixo:

1. Na lista de comportamentos do chatbot, localize o comportamento **Máquina de estados** e copie o **Identificador**.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/3Dpjcpu0RNPLMr1j2zpbB_identificador.png" signedSrc="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/3Dpjcpu0RNPLMr1j2zpbB_identificador.png" size="100" caption alt="Identificador" isUploading="false" sha initialPath="img/atendimento_humano/identificador.png" githubPath="Documentação CITsmart Aura/img/atendimento_humano/identificador.png" width="1236" height="610" darkWidth="1236" darkHeight="610" indent="2"}

2. Navegue para a funcionalidade **Máquina de estados** e na funcionalidade skills, selecione umas das opções abaixo para realizar a edição:

### Utilizando o "Editor visual"

1. Na skill, clique em **Editor**.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/2n3VclNbWS5E2zXolNWQz_acessoeditorvisual.png" signedSrc="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/2n3VclNbWS5E2zXolNWQz_acessoeditorvisual.png" size="100" caption alt="Editor visual" isUploading="false" sha initialPath="img/atendimento_humano/acesso_editor_visual.png" githubPath="Documentação CITsmart Aura/img/atendimento_humano/acesso_editor_visual.png" width="450" height="329" darkWidth="450" darkHeight="329" indent="2"}

2. Selecione o estado onde ocorrerá o atendimento humano.
3. No painel lateral, vá em **Automações**.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/Ef092UnyWU5-eJNYJdJEF_estadoautomacoes.png" signedSrc="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/Ef092UnyWU5-eJNYJdJEF_estadoautomacoes.png" size="100" caption alt="Automação" isUploading="false" sha initialPath="img/atendimento_humano/estado_automacoes.png" githubPath="Documentação CITsmart Aura/img/atendimento_humano/estado_automacoes.png" width="1231" height="843" darkWidth="1231" darkHeight="843" indent="2"}

4. Cole o **Identificador** no campo e clique em **"Salvar"**.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/aqOtQtJfrc9zk75K2uFlm_salvarautomacao.png" signedSrc="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/aqOtQtJfrc9zk75K2uFlm_salvarautomacao.png" size="100" caption alt="Salvar automação" isUploading="false" sha initialPath="img/atendimento_humano/salvar_automacao.png" githubPath="Documentação CITsmart Aura/img/atendimento_humano/salvar_automacao.png" width="1238" height="661" darkWidth="1238" darkHeight="661" indent="2"}

### Utilizando o "Editor de código"

1. Na skill, clique em **Código**.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/6vxmXpxOmUA_T_j9Ti2D7_acessoeditorcodigo.png" signedSrc="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/6vxmXpxOmUA_T_j9Ti2D7_acessoeditorcodigo.png" size="100" caption alt="Editor de código" isUploading="false" sha initialPath="img/atendimento_humano/acesso_editor_codigo.png" githubPath="Documentação CITsmart Aura/img/atendimento_humano/acesso_editor_codigo.png" width="450" height="329" darkWidth="450" darkHeight="329" indent="2"}

2. Localize (ou pesquise com CTRL + F) o estado escolhido para realizar o transferência.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/VBRyjz3MsWV-pVXM_myd4_pesquisandoestado.png" signedSrc="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/VBRyjz3MsWV-pVXM_myd4_pesquisandoestado.png" size="100" caption alt="Pesquisando estado" isUploading="false" sha initialPath="img/atendimento_humano/pesquisando_estado.png" githubPath="Documentação CITsmart Aura/img/atendimento_humano/pesquisando_estado.png" width="1203" height="621" darkWidth="1203" darkHeight="621" indent="2"}

3. Insira as informações `$ <Identificador>` dentro do estado responsável pela transferência, conforme imagem:

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/KX470aJ6hO9WOipQylnfL_editoralteradocodigo.png" signedSrc="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/KX470aJ6hO9WOipQylnfL_editoralteradocodigo.png" size="100" caption alt="Estado alterado código" isUploading="false" sha initialPath="img/atendimento_humano/editor_alterado_codigo.png" githubPath="Documentação CITsmart Aura/img/atendimento_humano/editor_alterado_codigo.png" width="1221" height="373" darkWidth="1221" darkHeight="373" indent="2"}

4. Conclua as alterações clicando em **Salvar** no canto superior direito da tela.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/1Pi2AoMgLGwYgAKLzlqzU_salvarcodigo.png" signedSrc="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/1Pi2AoMgLGwYgAKLzlqzU_salvarcodigo.png" size="100" caption alt="Salvar alteração" isUploading="false" sha initialPath="img/atendimento_humano/salvar_codigo.png" githubPath="Documentação CITsmart Aura/img/atendimento_humano/salvar_codigo.png" width="1220" height="375" darkWidth="1220" darkHeight="375" indent="2"}

5. Por fim, retorne à tela de **Listagem de comportamentos** e, na opção **Iniciar a conversa no comportamento**, selecione o **fluxo de demonstração**. Isso fará com que o chatbot seja iniciado diretamente pelo bot. Em seguida, clique em **Salvar**.

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/ksoO4t0Yv12HupQHkm8Xa_iniciarconversabot.png" signedSrc="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/ksoO4t0Yv12HupQHkm8Xa_iniciarconversabot.png" size="100" caption alt="Salvar alteração" isUploading="false" sha initialPath="img/atendimento_humano/iniciar_conversa_bot.png" githubPath="Documentação CITsmart Aura/img/atendimento_humano/iniciar_conversa_bot.png" width="1230" height="591" darkWidth="1230" darkHeight="591" indent="2"}

## Filas

:::BlockQuote
Esta funcionalidade está disponível apenas para o papel de **Supervisor**.
:::

A opção **"Filas"** permite criar, configurar e gerenciar filas de atendimento, facilitando a distribuição e organização das solicitações recebidas.

### Adicionar

Para criar uma fila, clique na opção **"Adicionar"**, conforme a imagem abaixo:

![Adicionar Fila de Atendimento](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/Gx6Jvzpx-vJLFl392J-zD_filasadicionar.png)

Após acessar a tela, insira o **"Nome da fila"**, selecione os usuários que farão parte daquela fila de atendimento e clique em **"Salvar"** para concluir o processo. Conforme imagem abaixo:

![Adicionar Nome e Usuários](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/uEtRmJLWWmEW4rP-StP60_filasnome.png)

### Editar

O sistema permite realizar edições no campo **"Usuários"**. Para isso, clique na opção **"Editar"**, conforme mostrado na imagem abaixo:

![Realizar Edição](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/Z84_h3X7fRe7KmEtS-bxC_filaseditar.png)

**Editar Fila**

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/pxzpvRKjASfzutjnCfgwJ_.blob)

**Usuários:** É possível definir os integrantes da fila que faram parte da equipe de atendimento.&#x20;

**Mensagem de entrada na fila:&#x20;**&#x44;efine o texto quando o usuário entra na fila de atendimento humano. Utilizando a chave *\{\{pos}}* é possível informar a posição que o usuário se encontra na fila.&#x20;

**Mensagem de espera na fila :** 
Define o texto ao atualizar a posição do usuário na fila de atendimento. Utilizando a chave *\{\{pos}}* para informar a posição do usuário, a chave *\{\{queue}}* para informar qual a fila de atendimento e a chave *\{\{time}}* para informar o tempo estimado para atendimento.&#x20;

**Mensagem de captura:&#x20;**&#x44;efine o texto quando o atendente assume o atendimento do usuário. Utilizando a chave *\{\{name}}&#x20;*&#xE9; informado ao usuário quem está realizando seu atendimento.&#x20;

**Mensagem de despedida da fila:&#x20;**&#x44;efine o texto de conclusão do atendimento humano.&#x20;

**Distribuir atendimentos automáticamente:&#x20;**&#x48;abilita a distribuição automática de atendimento para a fila.&#x20;

**Habilitar transferência entre filas:&#x20;**&#x50;ermite que os atendentes direcionem o atendimento para outras filas.&#x20;

**Habilitar transferência entre agentes:&#x20;**&#x50;ermite que os atendentes realizem a atribuição de atendimento para outros atendentes da mesma fila.&#x20;

Após fazer as alterações necessárias, clique em **"Salvar"** para concluir.

![Realizar Edição](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/RAZ6N0CDPnAWmhIYkXEgc_filaseditar2.png)

### Excluir

Para remover uma fila que não é mais necessária, clique na opção **"Excluir"**, conforme mostrado na imagem abaixo:

![Excluindo Filas](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/TXac-oMscLFDYFNxOlvjK_filasexcluir.png)

Em seguida, confirme a ação clicando em **Sim** na janela de confirmação:

![Confirmar Exclusão](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/m0BXrglq24qloyiX4iSne_filasconfirmarexclusao.png)

## Atalhos de Texto Globais e Privados

:::BlockQuote
A funcionalidade **"Atalhos Globais"** está disponível para os usuários que possuem o papel de "supervisor" e **"Atalhos Privados"** está disponível para o perfil "atendente".
:::

Os atalhos de texto têm como propósito agilizar o atendimento ao usuário, permitindo o uso de respostas e procedimentos previamente configurados, sem a necessidade de buscar informações nas bases de conhecimento. É possível criar atalhos de respostas rápidas que podem ser compartilhados globalmente entre todos os operadores ou configurados como privados, acessíveis apenas pelo operador que os criou.

### Adicionar Atalho

Para adicionar um atalho, seja **global ou privado**, escolha a opção correspondente, conforme imagem abaixo:

![Escolher Atalho](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/eKc-t4G3TvnywonLYDqHg_atalhotexto.png)

Em seguida, preencha os campos **Nome do Atalho** e **Conteúdo do Atalho**, e finalize clicando em **Adicionar Atalho**, conforme ilustrado na imagem:

![Adicionar Atalho](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/aukaTG5hwY4tgaw7BBZBa_atalhoadicionar.png)


[title] URL Encoding
[path] Untitled/Customizações Avançadas/Bibliotecas/

Utilizada para codificar caracteres especiais em uma URL, substituindo-os por sequências de escape no formato `%HH`, onde `HH` representa o valor hexadecimal do byte correspondente.

## Atalhos

- [**URL Encoding**](docId\:bUDfHgKwua9DxGfSSjC7N)
- [**URL Encoding**](docId\:bUDfHgKwua9DxGfSSjC7N)

***

### Encode

```lua
-- @param url String containing the url.
-- @return a string containing the encoded url
urlencoding.encode(url)
```

```lua
-- example usage

local encoded_url = urlencoding.encode("https://httpbin.org/get")

-- https%3A%2F%2Fhttpbin.org%2Fget
```

### Decode

```lua
-- @param url String containing the url.
-- @return a string containing the decoded url
urlencoding.decode(url)
```

```lua
-- example usage

decoded_url = urlencoding.decode("http%3A%2F%2Flocalhost%3A1754%2F.well-known%2Flunaris-configuration")

-- http://localhost:1754/.well-known/lunaris-configuration
```


[title] Botmaker
[path] Untitled/Brokers/

A especificação abaixo serve como manual para a utilização do broker [**Botmaker**](https://go.botmaker.com/).

### 1. Criar uma conta

Através do link abaixo, se inscreva na Botmaker.

[**link de acesso**](https://go.botmaker.com/new/)

Não é possivel criar uma conta de pessoa física. Dessa forma, é necessário criar uma empresarial que possua um número de whatsapp.

![Criar conta botmaker](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/IiC-k-mDLxTc2Kdvdl-Nn_botmakercriarconta.png)

### 2. Obtendo as credenciais da Botmaker API

Para obter o **ID do usuário** e o **token** acesse no menu lateral no icone de "engrenagem" a opção Integrações > API da Botmaker. Na parte superior, na aba credenciais.

![Tela home com menu aberto](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/Chhdu1ZDrOJ55TphVcQ5-_botmakerhome.png)

![Credenciais](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/-IWpVITxds1ab24z250hq_botmakercredentials.png)

O ID do Canal é composto da seguinte forma: id\_do\_usuario-whatsapp-numero\_do\_canal

```text
Exemplo: centralit-whatsapp-556133333333
```



### 3. Configurando um webhook

Para configurar o webhook partiremos da tela "home", e na seção "Canais conectados" clique em configurar.

![Home webhook](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/ZZC-dW_B6AinXUg12jRRz_botmakerhome2.png)

Na seção das Integrações Conectadas clique em configurar dentro do card do whatsapp.

![Configurar webhook](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/se-J58TBBD3NLTpFv4Tce_botmakercanaisconfig.png)

Clique no botão "ir para webhook".

![Webhooks](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/TJ1iT6K0p0gPTrfR4BC58_botmakercanais.png)

Clique no icone "lápis" para editar o webhook selecionado.

![Painel Webhooks](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/XPeJG_Qt2cKtT3DETD56s_botmakerpainelwebhooks.png)

A url do webhook é composta pela url **https\://\{endereço\_do\_lunaris}/post/botmaker/receive**.

Coloque a url: **https\://\{endereço\_do\_lunaris}/post/botmaker/receive** no campo "URL de notificação de mensagem recebida" e clique no botão "Validar e salvar".

![Config Webhooks](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/bx1WxqAJs-otYx6KNrlAx_botmakerwebhookconfig.png)

### 4. Configurando a Botmaker dentro da Aura

Na tela de comportamentos dentro da Aura vamos registrar um novo comportamento clicando no botão verde "avançar".

![Aura Botmaker Webhooks](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/4jyL0USZk4FSY79kqYmTP_botmakerhomeaura.png)

Para registrar esse novo comportamento, primeiro coloque o nome que deseja para ele, selecione o manifesto "Botmaker" e clique em avançar.

![Aura Botmaker Registrar Webhooks](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/PR7cpv9Hj7YNqwM_VVXXa_botmakerregistrarcomportamentoaura.png)

Coloque o texto para os botões, ID do canal e token ambos obtidos no botmaker como apresentado no item 2 deste documento.
Para finalizar clique no botão "concluir".

![Aura Botmaker Fim de Registro Webhooks](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/KRdErQBjiyC4nMCBHdda7_botmakerregistrarcomportamentocompletoaura.png)

### 5. Testando o botmaker

Para fazer os testes, primeiro clique em "chat" e será redirecionado para uma aba do whatsapp.

![Teste Botmaker](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/TJ1iT6K0p0gPTrfR4BC58_botmakercanais.png)

Clique em "Abrir Whatsapp".

![Whatsapp Botmaker](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/QZpZTtoVt4Lt5vFAUj9mg_botmakerwhatsapp.png)

E agora você terá uma nova conversa diretamente com o Botmaker.

![Whatsapp Conversa Botmaker](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/PTfcBVN9RfXixxVrlhm7b_botmakerwhatsappconversa.png)


[title] Disparo
[path] Untitled/Extensões/

:::BlockQuote
Esta funcionalidade está disponível apenas para o papel de **Supervisor**.
:::

&#x20;A ferramenta de disparo de mensagens foi desenvolvida para facilitar o envio de comunicações em massa pelo WhatsApp, utilizando templates previamente aprovados. Com ela, é possível organizar listas de contatos, realizar envios de forma rápida e acompanhar o status de cada mensagem, garantindo uma comunicação eficiente e padronizada. O sistema suporta o envio de mensagens do tipo texto, imagens e carrossel.

## Contatos

&#x20;A seção contatos permite a criação e o gerenciamento de listas de contatos que serão utilizadas nos envios de mensagens. O usuário pode adicionar contatos manualmente ou importar um arquivo CSV com os dados.&#x20;

Para criar uma lista, siga os passos abaixo:

### Acessando a tela de contatos

1. No menu lateral, clique em **Disparo > Contatos**.
2. O sistema exibirá a seguinte tela:

![Menu contatos](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/XiAcH2s2XtsFard_Yz-TV_contatos.png)

### Realizando cadastro

1. Dê um nome para sua lista no campo **"Nome da lista"**.
2. No campo **"Lista de contatos"**, insira os contatos no seguinte formato:
   - `+55DDD988887777,variável_1,variável_2,variável_3,...`

:::BlockQuote
⚠️ **Informação Importante** ⚠️O número de telefone deve ser informado no formato internacional:
:::

- **+55** → Código do Brasil.
- **61** → DDD (exemplo: Brasília).
- **988887777** → Número do telefone.

**Variáveis (marcadores):**

As variáveis inseridas após o telefone permitem personalizar cada mensagem de acordo com o template selecionado:

- Cada `variável_X` corresponde a um marcador `{{X}}` no corpo do template.
- A ordem das variáveis deve ser exatamente a ordem de substituição no texto.

**Funcionamento:**

- Ao disparar, cada **\{\{1}}**, **\{\{2}}**… é substituído pelo valor da sua respectiva **variável\_1**,**variável\_2**…
- Os marcadores são definidas na criação do template na **Gupshup**. Esses marcadores são substituidos ao informar as váriaves na criação da lista de contatos.

**Exemplo:**

![Lista de contatos](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/orfVhbro-LaZiyNnBMzji_listadecontatos.png)

1. Após concluir a configuração, clique em **"Criar lista"** para finalizar.

### Importar via arquivo CSV

1. Dê um nome para sua lista no campo **"Nome da lista"**.
2. No campo **"Lista de contatos"**, selecione um arquivo `.csv`.
3. Clique em **Importa CSV** para seleciona o arquivo.

![Importar CSV](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/RVQlqjnigjzRY1pccYfo9_importarcsv.png)

1. O sistema processará o arquivo e exibira os contatos na **"lista de contatos"**.
2. Para finalizar a criação, clique em **"Criar lista"**.

### Excluindo lista

&#x20;Após a criação, as listas de contatos ficam visíveis na parte inferior da tela. Para excluir uma lista, clique no ícone da "lixeira" localizado ao lado do nome da lista desejada e confirme a ação quando solicitado. A exclusão é imediata e não pode ser desfeita.&#x20;

![Importar CSV](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/I6B2K6zMueDVARkBVPNZC_excluirlistadecontatos.png)

## Templates

&#x20;Na opção templates, o sistema exibe todos os modelos de mensagens previamente aprovados na Gupshup e disponíveis para envio via WhatsApp. Através dessa tela, o usuário pode visualizar os templates cadastrados e iniciar um disparo de mensagens selecionando o modelo desejado.&#x20;

Para realizar o cadastro de um template na Gupshup, siga as informações abaixo:

### Criando template na Gupshup

1. Acesse o site da [**Gupshup**](https://www.gupshup.io/pt) e faça o login na plataforma.
2. Após o login, você será direcionado para a página de **Dashboard**.
3. Escolha a **API do WhatsApp** com a qual deseja trabalhar e clique na opção **"Overview"**.

![Dashboard](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/4A0WiIBx4ORGZTBFc5soZ_dashboard.png)

1. Para criar um novo **"Template"**, clique na opção **"Criar modelo"**.

![Criar modelo](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/LbIKJHkod4myiQIFt-x8T_criarmodelo.png)

1. Preenchar os campos conforme descrito abaixo:

- **Nome do template:** Escolha um nome descritivo para o seu template.
- **Categoria:** Selecione a categoria adequada para o template, de acordo com as diretrizes da Meta (**Marketing** ou **Utilidade**).
- **Idioma:** Selecione o idioma do template.
- **Rótulos de modelos:** Insira um rótulo que facilite a organização dos templates.
- **Cabeçalho (opcional):** Adicione um título no topo da mensagem, se necessário.
- **Corpo:** Insira o texto principal da mensagem. Caso tenha variáveis, utilize os **marcadores** na seguinte forma: `{{1}}`, `{{2}}`, `{{3}}`...

  **Exemplo de corpo com marcadores:**
  ```text
  Oi {{1}}, seu pedido {{2}} foi confirmado para {{3}} às {{4}}.
  ```
- **Variáveis (opcional):** Se você adicionou **marcadores** no campo **Corpo**, expanda a seção Variáveis e defina um nome para cada um deles.
  - A ordem dos nomes deve seguir o índice dos marcadores. O primeiro ao `{{1}}`, o segundo ao `{{2}}` e assim por diante.
  - Esses nomes facilitam a identificação das variáveis e, uma vez definidos, passam a ser campos obrigatórios no momento do envio.
  - Na nossa plataforma, ao cadastrar sua **lista de contatos**, você poderá informar, para cada contato, um valor diferente para cada variável configurada.

**Carrossel (Categoria Marketing):** Formato interativo com até 10 cards, com imagem, título, legenda e botão(s). Caso opte por esse formato, preencha as seguintes informações:

- **Tipo de mídia do cabeçalho:** Atualmente, apenas o formato **imagem** é suportado.
- **Número de botões:** Defina quantos botões deseja incluir.
- **Tipo de botão:**
  - **Resposta rápida:** Envia uma resposta predefinida ao clicar.
  - **URL:** Redireciona o usuário para um site específico.
- **Card:** Adicione a **imagem** (máx. 5 MB), insira a **descrição** e configure os **botões** conforme o tipo escolhido.
- **Rodapé (opcional):** Adicione um rodapé para a mensagem.
- **Botões (opcional):** Adicione botões de resposta rápida ou ações.

1. Após preencher todas as informações, clique em **"Visualizar e enviar"** para revisar o conteúdo. Se estiver tudo correto, finalize clicando em **"Enviar"**.

![Criar modelo](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/yxgYNGG7BkrkuEp1KipVc_pre-visualizacao.png)

**Observações:**

- As categorias de template seguem definições da Meta. Escolha a que melhor representa o propósito da mensagem.
- O conteúdo do template deve seguir as políticas e diretrizes da Meta para aprovação.
- A aprovação do template pode levar algum tempo.

### Citsmart Aura - Acessando menu "Template"

1. No menu lateral, clique em **Disparo > Templates.**
2. A tela exibirá todos os templates já aprovados.

![Templates](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/nBk33gfnpWul0m-QSsv-Q_templates.png)

### Realizando o disparo

1. Localize o template desejado e clique no ícone azul, conforme imagem:

![Envio de templates](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/uoG_0kO_xZjzyrrcW52jP_enviodetemplates.png)

1. O sistema abrirá o seguinte formulário:

![Formulário de envio](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/jwZzNPVmXbIo5dEKNxzKQ_formulariodeenvio.png)

1. Selecione a **lista de contados** previamente criada.
2. Defina o **horário** e a **data de envio** desejados e clique em **Criar disparo**.

O sistema irá agendar o envio e exibirá uma confirmação. Você poderá acompanhar o status na aba **Envios**.

:::BlockQuote
**⚠️ Observação Importante ⚠️**  Os templates utilizados nos envios são importados automaticamente da Gupshup. É necessário que o template seja criado, enviado e aprovado por lá antes de estar disponível na plataforma.
:::

## Envios

&#x20;A tela de Envios permite acompanhar todos os disparos de mensagens realizados através da plataforma. Nela, o usuário pode visualizar o status de cada envio, identificando se a mensagem foi enviada com sucesso, cancelada, apresentou falha ou está agendada para um horário futuro.

Veja abaixo como acessar a funcionalidade:

### Acessando os envios

1. No menu lateral, clique em **Disparo > Envios**.
2. A tela exibirá a listagem de envios agendados, concluídos ou com erro.

![Envios](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/EITPa7H08m1oawcr_uGaA_envios.png)

O sistema possui os seguintes status:

- **Agendado (cinza)** – Envio programado para data/hora futura.
- **Enviado (verde)** – Mensagem enviada com sucesso.
- **Falha (vermelho)** – Ocorreu um erro no envio.
- **Cancelado (laranja)** – Envio cancelado antes da execução.

### Cancelar agendamento

Se o status estiver como **Agendado**, é possível cancelar o envio clicando no ícone de cancelamento, conforme imagem abaixo:

![Cancelando agendamento](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/QL1H32ULl9HxHmZJh6uDE_cancelaragendamento.png)


[title] Comportamentos
[path] Untitled/Instalação/

:::BlockQuote
Este manual tem como objetivo orientar o processo de criação de um chatbot e o registro adequado dos comportamentos.
:::

## Criar novo chatbot

:::BlockQuote
Esta funcionalidade está disponível apenas para o papel de **Desenvolvedor**.
:::

1. Acesse o menu "**CITSmart Aura**" e clique na opção "**Chatbots**".

![novochatbot](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/WbGCC7W9jeg1XoCB1chNF_novochatbot.png)

1. Clique em "**Novo Chatbot**", insira o nome desejado e clique no botão "**Criar Novo Chatbot**".

![novochatbot](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/jZpyeF3TycojWxx3q0Fdh_criarnovochatbot.png)

1. Após criar o chatbot, clique sobre seu nome para acessar as funcionalidades.

![novochatbot](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/SOIyK8BqH07ZS5kieJ7Nx_meunovochatbot.png)

### Dashboard

:::BlockQuote
Esta funcionalidade está disponível apenas para o papel de **Supervisor**.
:::

Na opção "**Dashboard**", é possível visualizar métricas importantes sobre as interações do chatbot.

### Listagem de histórico de conversas

:::BlockQuote
Esta funcionalidade está disponível apenas para o papel de **Supervisor**.
:::

Acesse a "**Listagem de históricos de conversas**" para visualizar todas as interações realizadas com o chatbot.

![novochatbot](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/vc4NOoGfLuRvIXLvKB3W2_historicodeconversas.png)

### Excluir

:::BlockQuote
Esta funcionalidade está disponível apenas para o papel de **Desenvolvedor**.
:::

1. Para excluir um chatbot, clique no ícone "**Excluir**" e uma mensagem de confirmação será exibida.

- Para confirmar a exclusão, clique em "**Sim**"
- Para cancelar, clique em "**Não**".




![novochatbot](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/6FTOHHbty6l-9Kz99qPbY_excluir1.png)

![novochatbot](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/BO6YRDZ45GImYBu8mf4WL_excluir.png)

## Registrar comportamentos

:::BlockQuote
Esta funcionalidade está disponível apenas para o papel de **Desenvolvedor**.
:::

1. No chatbot criado, localize a opção "**Registrar novo comportamento**" e clique em "**Avançar**".

![registrarcomportamento](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/u_ovD_PslF3sgNBC_h3A9_registrarcomportamento.png)

1. Escolha o tipo de comportamento a ser cadastrado.
   No exemplo abaixo, vamos cadastrar o comportamento "Máquina de estados".

![registrarcomportamento](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/HmehwUX6OrsgSMjqNaEYA_registrarcomportamento2.png)

1. O sistema solicitará as seguintes informações:

- Nome: Meu novo chatbot
- Manifesto: Máquina de estados
- Login: máquina
- Senha: 123456

![registrarcomportamento](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/_QHZfnMynyB4tWEjUhkPG_informacoeswanderson.png)

1. Após preencher os dados, clique em "**Avançar**".

## Informações adicionais

Cada comportamento possui critérios e parâmetros específicos para sua configuração. Por isso, é essencial acessar informações adicionais para garantir uma configuração precisa e eficiente. Confira abaixo os links com orientações específicas para cada canal:

- [**Botmaker**](docId\:oQ7mLKAYAyW2kQrSIffm7)&#x20;
- [**Facebook Messenger**](docId:-vBRvUM247x2JCWpy5ewF)&#x20;
- [**Gupshup**](docId\:yDE_OvkdaVXwDXlJf4KOb)&#x20;
- [**Positus**](docId\:Y-6xf0gSO_DGt1C05qVgh)&#x20;
- [**Slack**](docId\:LrVVKjuAG70-TR5OJ3BUB)&#x20;
- [**Microsoft Teams**](docId\:U2x45XhTvXjYPfCjTwdGL)&#x20;
- [**Telegram**](docId\:LWjO_fH2atItJkba-N0x8)&#x20;
- [**Twilio**](docId\:QwD1M939lV4VZKc25irfp)&#x20;
- [**Manual do widget**](docId\:y4PJDkvomuu6KVeCcpZTA)&#x20;


[title] Functional
[path] Untitled/Customizações Avançadas/Bibliotecas/

Métodos utilizados para programação funcional.

## Atalhos

- [**Functional**](docId\:X4ZH7Ih_88YMiMQtyIXCC)
- [**Filter**]()
- [**Functional**](docId\:X4ZH7Ih_88YMiMQtyIXCC)
- [**Functional**](docId\:X4ZH7Ih_88YMiMQtyIXCC)

***

### Métodos

### Map

Cria uma nova tabela preenchida com os resultados da chamada de uma função fornecida em cada elemento da tabela de chamada.

```lua
-- @param table Tabela que será usada na função.
-- @param callbackFn Uma função a ser executada para cada elemento na tabela.
-- @return table Uma nova tabela com os elementos mapeados 
table.map(table, callbackFn)
```

```lua
-- example usage:

local t = { 10, 20, 30}

local result = table.filter(t, function(x) return x * 2 end)

-- {20, 40, 60}
```

### Filter

Cria uma cópia de uma parte de uma determinada matriz, filtrada apenas para os elementos da matriz fornecida que passam no teste implementado pela função fornecida.

```lua
-- @param table Tabela que será usada na função.
-- @param callbackFn Uma função a ser executada para cada elemento do array. Ela deve retornar um valor verdadeiro para manter o elemento no array resultante e um valor falso caso contrário.
-- @return table Uma nova tabela com os elementos mapeados 
table.filter(table, callbackFn)
```

```lua
-- example usage:

local t = { 90, 19, 16, 14, 1, 2, 3, 4, 5, 6, 7, 8 }

local result = table.filter(t, function(x) return x > 5 end)

-- {90, 19, 16, 14, 6, 7, 8}
```

### Reduce

O método reduce() executa uma função de retorno de chamada "redutor" fornecida pelo usuário em cada elemento do array, em ordem, passando o valor de retorno do cálculo no elemento anterior. O resultado final da execução do redutor em todos os elementos do array é um único valor.

```lua
table.reduce(table, callbackFn(accumulator, value), initialValue)
```

- **table** Tabela que será usada na função.
- **callbackFn** Uma função a ser executada para cada elemento de uma tabela. Seu valor de retorno se torna o valor do parâmetro accumulator na próxima invocação de callbackFn. Para a última invocação, o valor de retorno se torna o valor de retorno de reduce(). A função é chamada com os seguintes argumentos:
  - **accumulator** O valor resultante da chamada anterior para callbackFn. Na primeira chamada, seu valor é initialValue se o último for especificado; caso contrário, seu valor é `table[1]`.
  - **value** O valor do elemento atual. Na primeira chamada, seu valor é `table[1]` se initialValue for especificado; caso contrário, seu valor é `table[2]`.
- **initialValue** Um valor para o qual o acumulador é inicializado na primeira vez que o retorno de chamada é chamado. Se initialValue for especificado, callbackFn inicia a execução com o primeiro valor no array como currentValue. Se initialValue não for especificado, o acumulador é inicializado com o primeiro valor da tabela e callbackFn inicia a execução com o segundo valor na tabela como currentValue.

### Valor de retorno

O valor resultante da execução da função de retorno de chamada "redutor" até a conclusão em todo o array.

:::BlockQuote
OBSERVAÇÃO: Na linguagem de programação Lua, o indice de posição de um elemento em uma tabela (Array) começa em 1.
:::

```lua
-- example usage:

local t = { 2, 3, 4, 5 }

local result = table.reduce(t, function(accum, value) return accum * value end, 2)

-- 240
```

### Windows

Cria janelas continuas de tamanho `size` de uma tabela.

```lua
-- @param table Tabela que será usada na função.
-- @param size Tamanho da janela
-- @return table Uma nova tabela com todas as janelas 
table.windows(table, size)
```

```lua
-- example usage:

local t = { 1, 2, 3, 4}

local result = table.windows(t, 3)

--[[ 
result: 

{
    {1, 2, 3}, 
    {2, 3, 4}
}

]]--
```


[space] CITSmart 9 (/cit-9)

[title] Atividades da Fase de Planejamento da Mudança
[path] 16 Processos/Mudança/

Esta funcionalidade permite<font color="#3b9f0f"> **planejar as atividades a serem executadas junto a mudança**</font>.

## Antes de Começar

As atividades de Planejamento ocorrem após o cadastro da mudança.&#x20;

- [x] Sendo assim,
  &#x20;verifique a existência de uma Mudança e, também, se tem permissão para
  &#x20;criar/executar atividades.

## Procedimento

1. Acesse a funcionalidade pela navegação no menu principal `Processos >
    Gerência de Mudança > Mudança`;
2. Localize a mudança da qual deseja planejar atividade. Clique no botã&#x6F;**&#xD;&#x20;“Abrir”&#x20;**&#x65;, em seguida, na área **“Planejamento”**;
3. Será possível criar um quadro *Kanban* para gerenciar as atividades
   &#x20;registradas. Para isso, basta apertar no botão ***“+Workspace”*** e preencher os campos
   &#x20;disponibilizados, tais como: **título, selecionar o usuário ou grupo
   &#x20;responsáveis para a execução das tarefas, dentre outros**. Também é permitido
   &#x20;vincular um quadro já criado ao clicar no outro botão relacionado ao
   &#x20;***“Workspace”***.
4. Ainda é possível vincular os projetos, ações, notificações, conhecimentos e
   &#x20;anexos de arquivos para detalhar a execução da mudança. Para tanto, é
   &#x20;necessário clicar sobre cada aba disponibilizada e selecionar o item desejado
   &#x20;para vinculá-lo à mudança
5. Na aba <font color="#3b9f0f">**“Mais”**</font> é possível agendar estas atividades (na opção **“Outras
   &#x20;informações”**) e apontar todas as informações pertinentes na opção&#xD;**&#x20;“Anotações”**.
6. Clique no botão **“Opções”** e, em seguida, aperte ou no botão **“Gravar e manter a
   &#x20;tarefa atual”** para registar as atividades de planejamento e não avançar o fluxo da atividade; ou selecione o
   &#x20;botã&#x6F;**&#x20;“Gravar e avançar o fluxo”&#x20;**&#x70;ara finalizar a tarefa e dirigir-se para
   &#x20;a próxima fase do fluxo.


[title] Verificar Auditoria de Serviços
[path] 16 Processos/Portfólio e Catálogo/

Esta funcionalidade <font color="#3b9f0f">**permite** </font>****<font color="#3b9f0f">**verificar o histórico do serviço**</font> para auditoria do mesmo.&#x20;

As orientações descritas neste conhecimento poderão ser seguidas para verificar o histórico do Serviço de Negócio/TI e do Serviço de Apoio/Técnico.

## Antes de Começar

- [x] Para verificar o histórico de auditoria de serviços, é necessário ter o portfólio
  &#x20;definido.

## Procedimento

1. Acesse a funcionalidade por meio da navegação no menu principal `Processos >
    Gerência de Portfólio e Catálogo > Portfólio`;
2. Acesse o Portfólio de Serviços e clique no botã&#x6F;**&#x20;"Avançar"**;
3. Clique no botão **"Avançar"&#x20;**&#x64;o serviço;
4. Aperte na guia <font color="#3b9f0f">**Auditoria do Serviço**</font>;
5. Coloque o intervalo de datas almejado ou selecione a categoria;
6. Clique e&#x6D;**&#x20;"Buscar"**;
7. Caso tenha a necessidade de registrar os detalhes da auditoria realizada,
   &#x20;clique na aba <font color="#3b9f0f">**Cadastrar Ocorrências**</font>;
8. Preencha os campos disponibilizados;
9. Clique e&#x6D;**&#x20;"Gravar"**.


[title] Atividades da Fase de Implantação da Liberação
[path] 16 Processos/Untitled/

Esta funcionalidade permite<font color="#3b9f0f"> **planejar as atividades a serem implementadas junto com a
 liberação**</font>, de forma semelhante ao que ocorre na fase de Planejamento da Liberação.

## Antes de Começar

- [x] Antes realizar as atividades inerentes à Implantação da liberação, é necessário
  &#x20;que haja uma Liberação com a fase de planejamento concluída.

## Procedimento

1. Acesse a funcionalidade por meio da navegação no menu principal `Processos >
    Gerência de Liberação > Liberação`;
2. Localize a liberação que deseja Planejar a atividade. Clique no botão "**Abrir**" e, em seguida, na área "**Implantação da liberação**";
3. Podemos criar um quadro *Kanban&#x20;*&#x70;ara gerenciar as atividades cadastradas.
   &#x20;Basta apertar no botão "**+ Novo work**" (disponibilizado na área chamada
   &#x20;"**Atividades**") e preencher os dados disponibilizados, tais como o título, sua
   &#x20;fase (a fazer, em andamento, etc), selecione o usuário ou grupo
   &#x20;responsáveis para a execução das tarefas, dentre outros. Também, é possível vincular a
   &#x20;liberação um *Kanban* já criado;

:::hint{type="info"}
&#x20;🖊 ***Nota*****:&#x20;**&#x41;o vincular um **Kanban já existente**, se o usuário não possuir a permissão de acesso a um determinado Workspace, o sistema apresentará uma mensagem o informando. **O usuário, deve então, solicitar a permissão na Workspace e Sprint ou criar um novo quadro Kanban**.&#x20;
:::

4\. É possível vincular os papéis e responsabilidades, projetos, documentos,
&#x20;notas, documentos e notificações do sistema à liberação. Para
&#x20;tanto, é necessário clicar sobre o quadro disponibilizado, selecionar o
&#x20;ítem desejado para vinculá-lo à liberação;

5\. Além de permitir o vínculo das responsabilidades, projetos e notificação de
&#x20;sistemas, é possível criar os mesmos do zero para adequarem-se à liberação em
&#x20;questão, clicando no botã&#x6F;**&#x20;"Cadastrar"** e preenchendo os campos necessários

## O que Fazer a Seguir

É possível vincular outras funcionalidades à liberação.


[title] Política de Liberação 
[path] Sobre o CITSmart/

## Visão Geral

O objetivo desta política é descrever os ciclos de liberação e atualização dos Produtos <font color="#3b9f0f">**CITSmart**</font>, notificações ao cliente e outras informações relevantes.

As diretrizes da política são aplicáveis a todos os nossos produtos, estejam eles usando o modelo <font color="#3b9f0f">**SaaS**</font> ou <font color="#3b9f0f">**On-Premises**</font>.

## Ciclos de Liberação e Atualização

Nossa proposta de liberação e atualização de produtos foi definida para fornecer estabilidade, resposta rápida a problemas, além do fornecimento contínuo de novos recursos e experiências.

Tipicamente, os produtos <font color="#3b9f0f">**CITSmart**</font> seguem 4 tipos de liberação, conforme listado na tabela a seguir:

| **Tipo de Liberação**                                         | **Escopo**                                                                                                                                                                                 | **Frequência**                                                                        | **Notificação**                                                                              |
| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| ******<font color="#3b9f0f">***Major Version***</font>******  | Recomendada a todos os clientes, esta atualização poderá incluir novas funcionalidades e *killer features*. Normalmente, apresenta mudanças significativas na aplicação ou na arquitetura. | Anual                                                                                 | No mês anterior ao lançamento, com uma segunda notificação 20 dias após o envio da primeira. |
| ******<font color="#3b9f0f">***Stable Release***</font>****** | Recomendada a todos os clientes, esta atualização poderá incluir novas funcionalidades, melhorias, atualizações de segurança, ajustes e correções.                                         | Quadrimestral                                                                         | No mês anterior ao lançamento, com uma segunda notificação 10 dias antes do lançamento.      |
| ******<font color="#3b9f0f">***Beta Release***</font>******   | Normalmente direcionada a parceiros **Beta Users** e de escopo pontual, poderá incluir melhorias, atualizações, ajustes e correções.                                                       | Bimestral                                                                             | Dez dias antes do lançamento.                                                                |
| ******<font color="#3b9f0f">***Hotfix***</font>******         | Recomendada a todos os clientes, esta atualização poderá incluir correções emergenciais para garantir a estabilidade e segurança do sistema.                                               | Sempre que necessário, seguindo critérios de autorização e urgência a serem definidos | Poucas horas antes, preferencialmente 48h antes                                              |

:::hint{type="warning"}
⚠️ ***Atenção*****!** O tempo e a frequência dos lançamentos estão sujeitos a alterações, a critério exclusivo da <font color="#3b9f0f">**CITSmart**</font>. No caso de alterações deste cronograma, os clientes deverão ser previamente notificados.
:::

:::hint{type="success"}
✅ ***Regra*****:&#x20;**&#x4F;s produtos <font color="#3b9f0f">**CITSmart** </font>utilizam o seguinte padrão para identificação da versão:

Versão: **Series**

Release: **Stable Release**.**Beta Release**.**Hotfix**

Onde:

- **Series** identifica a *Major Release*, por exemplo: <font color="#3b9f0f">**CITSmart 9**</font>.
- **Stable Release** identifica a *Stable Release* associada.
- **Beta Release** identifica a *Beta Release* associada, ou zero quando não houver *Beta Release* associada.
- **Hotfix** identifica &#x61;*&#x20;Hotfix* associada, ou zero quando não houver *Hotfix* associada.
:::

:::BlockQuote
***Por exemplo*****:&#x20;**<font color="#3b9f0f">**CITSmart 9**</font>**&#x20;- Release 1.2.3 refere-se a:                        a) Series: CITSmart 9; b) Stable Release: 1; c) Beta Release: 2; d) Hotfix: 3**
:::

## Versões Suportadas

Nossa política atual é oferecer suporte para a versão mais recente e a versão anterior.

A <font color="#3b9f0f">**CITSmart**</font> geralmente realiza um grande lançamento por ano, sendo assim, o cliente precisará atualizar, aproximadamente, uma vez a cada dois anos para permanecer em uma versão suportada.

:::hint{type="success"}
✅ ***Regra*****:&#x20;**&#x41; <font color="#3b9f0f">**CITSmart**</font> fornece atualizações (por exemplo: correções e *hotfixes*) somente para a versão suportada.
:::

## Informações Adicionais Sobre Atualização

Os Procedimentos de Atualização dependem do modelo da solução adquirida (<font color="#3b9f0f">**SaaS**</font> ou O<font color="#3b9f0f">**n-Premises**</font>). Para cada uma delas, siga as recomendações abaixo:

| ### Cliente SaaS                                                                                                                                                                                                                                            | ### Clientes On-Premises                                                                                                                                                                        |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Os clientes podem agendar atualizações de *software&#x20;*&#x71;uando necessário, enviando uma nova solicitação de serviço por meio de nosso site de suporte.                                                                                               | Nesse caso, os clientes são responsáveis pela atualização de *software&#x20;*&#x70;or sua conta (ou através de um parceiro <font color="#3b9f0f">**CITSmart**</font> contratado para este fim). |
| Nessa solicitação, o cliente informa a data desejada para atualização, versão desejada e tipo de ambiente (produção ou não produção).                                                                                                                       |  Recomendamos que os clientes testem funcionalidades e customizações no ambiente de não produção antes de realizar a atualização no ambiente de produção.                                       |
| Os tempos de interrupção são definidos para minimizar a interrupção dos negócios do cliente. Todo o processo de atualização é feito pelo time de suporte da <font color="#3b9f0f">**CITSmart**</font>.                                                      | Orientações sobre como atualizar ou usar novos recursos estarão disponíveis nas **Notas da Versão**.                                                                                            |
| Após todos os testes, o cliente deverá assinar o termo de conformidade de homologação, garantindo que realizou todos os testes necessários. Desta forma, autoriza a aplicação da atualização em produção, conforme janela de mudança previamente agendada.  | Se você tiver alguma dúvida sobre os procedimentos de atualização, envie-nos uma solicitação de serviço, por meio do nosso site de suporte.                                                     |
| Sem este documento assinado, a atualização **não será efetuada.**                                                                                                                                                                                           |                                                                                                                                                                                                 |


[title] Cadastrar um Serviço
[path] 16 Processos/Portfólio e Catálogo/

O cadastro de serviços é dividido em dois tipos:

- **Negócio:** provê os serviços de negócios/TI;
- **Apoio:** provê os serviços de apoio/técnico.

:::hint{type="success"}
✅ ***Regra*****:** A escolha do tipo <font color="#3b9f0f">**Negócio/Apoio**</font> deve estar alinhada com o tipo do contrato que se pretende vincular ao Portfólio. Somente contratos do tipo **“Contrato”** são vinculados ao tipo **"Negócio"** enquanto somente contratos do tipo **“Contrato de Apoio”** e **“Acordo de Nível Operacional”** são vinculados ao tipo **"Apoio"**.
:::


Esta funcionalidade disponibiliza ações diversas, tais como:<font color="#3b9f0f"> **incluir, alterar e excluir um serviço.**</font>****

## Antes de Começar

O cadastro do serviço deverá ser precedido de:

- [x] Cadastro de um portfólio de serviços;
- [x] Criar categoria de serviço;
- [x] Criar grupo(s) que usarão o serviço;
- [x] Ter a permissão de acesso às funcionalidades do Gerenciamento de Portfólio.

## Procedimento

1. O Registro de Serviço será endereçado no **Botão de Novo Serviço**, no Funil de Serviço (Desenho).
2. A edição pode ser endereçada também no funil, mas no botão **Editar**, na guia <font color="#3b9f0f">**Detalhes**</font>**,** do registro de atributos do serviço.

### Acesso

1. O sistema apresentará as guias para definir o serviço a ser editado ou cadastrado;
2. Preencha todos os campos necessários para cada guia de Informação;
3. Salve o serviço.

## Informação de cada Guia

| **Guias**               | **Informações**                                                                            |
| ----------------------- | ------------------------------------------------------------------------------------------ |
| **Principal**           | Informações de serviços, status, fases, importância do negócio e outros.                   |
| **Documentos Anexos**   | Artefatos, documentos, guias e outros.                                                     |
| **Apresentação**        | Visualização no <font color="#3b9f0f">**Smart Portal**</font> e na **Gerência de Ticket.** |
| **Permissão de Acesso** | Grupos que podem ver o serviço.                                                            |
| **Multi-Idioma**        | Tradução do serviço para inglês, espanhol e português.                                     |
| **Pesquisas**           | Defina as Pesquisas do serviço (disponível apenas para edição)                             |

## Ação para Edição ou Cadastro

| **Ação**         | **Descrição**                 |
| ---------------- | ----------------------------- |
| **Gravar**       | Salvar o serviço              |
| **Excluir**      | Excluir o serviço (na edição) |
| **Limpar**       | Limpar os campos              |
| **Clonar dados** | Clonar outro serviço          |

## Guias de Informação

### <font color="#3b9f0f">Guia Principal</font>

- Informação de serviço, status, fases, importância do negócio e outros.

### Campos

| **Campo**                             | **Descrição**                                                     |
| ------------------------------------- | ----------------------------------------------------------------- |
| **Nome do Serviço (\*)**              | Nome do serviço                                                   |
| **Processo de Iniciação (\*)**        | Selecionar o processo de iniciação                                |
| **Categoria (\*)**                    | Informar a categoria de serviço da qual o novo serviço fará parte |
| **Data de Implantação (\*)**          | Data do início do uso do serviço                                  |
| **Fase do Serviço (\*)**              | Ver caixa abaixo                                                  |
| **Status do Serviço (\*)**            | Ver caixa abaixo                                                  |
| **Criticidade**                       | A criticidade pode ser selecionada na fase de **"Analisar"**      |
| **Importância do serviço ao Negócio** | Selecione a Importância                                           |
| **Tipo de Serviço**                   | Selecione o tipo de serviço                                       |
| **Lugar de Execução do Serviço**      | Interno, Externo ou Ambos                                         |
| **Detalhamento**                      | Detalhes do serviço                                               |
| **Objetivo**                          | Objetivo do serviço                                               |
| **Valor**                             | Descreva o valor do negócio                                       |
| **Template de serviço**               | Selecione o template do serviço                                   |

(\*) Indica campos obrigatórios.

### <font color="#3b9f0f">Fase x Status</font>

| **Fase**              | **Status**                                                                                    |
| --------------------- | --------------------------------------------------------------------------------------------- |
| **Definir**           | Requisições; Definição                                                                        |
| **Analisar**          | Análise                                                                                       |
| **Aprovar**           | Aprovado                                                                                      |
| **Termo de abertura** | Termo de abertura; Projeto; Desenvolvimento; Criação; Teste; Lançamento; Produção; Aposentado |

:::hint{type="info"}
**🖊&#x20;*****Nota*****:** Na fase de **"Analisar"**, o campo de **"Criticidade"** está ativado.  &#x20;
O serviço é movido para o Catálogo de Serviços quando **"Termo de abertura"** e **"Produção"** são combinados. &#x20;
O serviço é movido para os Serviços obsoletos quando **"Termo de abertura"** e **"Aposentado"&#x20;**&#x73;ão combinados. &#x20;
:::

### <font color="#3b9f0f">Guia de Documentos Anexos</font>

- Artefatos, documentos, guias e outros.

| **Componentes**                | **Descrição**      |
| ------------------------------ | ------------------ |
| **Descrição do anexo**         | Descreva o anexo   |
| **Botão de adicionar arquivo** | Adicionar          |
| **Grid com anexos**            | Visualizar/Excluir |

### <font color="#3b9f0f">Guia de Apresentação</font>

- Serve para configurar a visualização no <font color="#3b9f0f">**Smart Portal**</font> e no **Ticket Management**.

| **Campo**                                             | **Descrição**                                                           |
| ----------------------------------------------------- | ----------------------------------------------------------------------- |
| **Disponível no portal (\*)**                         | Indicar se o Serviço deverá estar presente no Portal de Serviços        |
| **Disponível via chat (\*)**                          | Indicar se o Serviço poderá ter atendimento no Chat                     |
| **Aprovação automática de avaliação do serviço (\*)** | Indica que as Avaliações de Serviço devem ser aprovadas automaticamente |
| **Nome (\*)**                                         | Nome do serviço ao aparecer no Portal de Serviços                       |
| **Descrição**                                         | Descrição do serviço ao aparecer no Portal                              |
| **Botão selecione uma imagem**                        | Selecionar uma imagem para o Serviço (ou subir uma nova)                |

(\*) Indica campos obrigatórios

:::hint{type="warning"}
⚠️ ***Atenção*****!**

Na opção **"Disponível via chat"**, mesmo se marcado com&#x6F;**&#x20;"Sim"**, para usar o Chat, ainda é preciso que essa opção seja combinada com a permissão de grupo (para participar do serviço no Chat).&#x20;
:::

### <font color="#3b9f0f">Guia de Permissão de Acesso</font>

- Define os Grupos que poderão utilizar o serviço.

| **Função**                     | **Descrição**                          |
| ------------------------------ | -------------------------------------- |
| **Vincular grupos**            | Pesquisar e vincular grupos ao Serviço |
| **Grid com grupos vinculados** | Visualizar/Desvincular                 |

### <font color="#3b9f0f">Guia de Multi-idioma</font>

- Tradução do serviço para inglês, espanhol e português.

**Para cada idioma, fornecer:**

- Nome do Serviço
- Descrição

### <font color="#3b9f0f">Guia de Pesquisas</font>

- Define as Pesquisas para o serviço (disponível apenas na edição)

| **Função**                           | **Descrição**                             |
| ------------------------------------ | ----------------------------------------- |
| **Vincular pesquisas**               | Pesquisar e vincular pesquisas ao serviço |
| **Grid com as pesquisas vinculadas** | Visualizar/Desvincular                    |

## O que Fazer a Seguir

Acesse o <font color="#3b9f0f">**Smart Portal** </font>e verifique a informação do serviço cadastrado registrado no portfólio.


[title] Avaliação de SLA
[path] 16 Processos/Nível de Serviço/

Segundo a ITIL, um <font color="#3b9f0f">**Acordo de Nível de Serviço (ANS)**</font> ou, em inglês, <font color="#3b9f0f">*Service Level Agreement (SLA*)</font>, é um acordo estabelecido entre o provedor de serviços de TI e um cliente.&#x20;

O ANS descreve o serviço de TI, documenta metas de nível de serviço e especifica as responsabilidades do provedor de serviços de TI e do cliente.


Esta funcionalidade tem por objetivo **gerar informações de acordo de nível de serviço&#x20;**&#x71;ue auxiliarão na confecção de plano de qualidade.

## Antes de Começar

- [x] As informações geradas nesta funcionalidade dependem de um cadastro prévio de
  &#x20;SLA.

## Procedimento

1. Acesse a funcionalidade por meio da navegação no menu principal
   &#x20;`Processos > Gerência de Nível de Serviço > Avaliação > SLA`;
2. Defina o intervalo de datas;
3. Clique em **"Gerar Informações"**.


[title] Criar Tempo de Atendimento (SLA)
[path] 16 Processos/Nível de Serviço/

Esta funcionalidade disponibiliza ações diversas, tais como: **incluir, alterar e excluir o tempo de atendimento do tipo padrão Global**, este aplica-se a todos os serviços. Nesta página é também possível adicionar um Acordo de Nível Operacional (OLA) e Contrato de Apoio (CA) utilizados tanto para gestão de tickets quanto para gestão de problemas.

:::hint{type="info"}
**🖊** ***Nota*****:**

Após a criação do SLA, os valores de custo e preço serão apresentados para cada serviço com base no SLA criado. Esses dados serão provenientes do processo financeiro [Cálculo de Custos Financeiros](docId\:wbDJ11jv1UTomO8zHDUVJ),  na guia "**Distribuição de custos**" e "**Definir preço**" de acordo com a estratégia definida (fixa ou variável).

Os tempos de captura e resolução respeitam as jornadas de trabalho vinculadas aos calendários utilizados para cálculo de atendimento.
:::

:::hint{type="warning"}
⚠️ ***Atenção*****!**

Nessa tela é criado apenas o tempo de atendimento. Para vincular o tempo de atendimento com serviço é necessário realizar via tela de [Vincular as Atividades ao Contrato do Serviço](docId\:hNgH6ORgY4pJrltZ66jhE).&#x20;
:::

## Antes de Começar

- [x] É necessário registrar anteriormente o contrato(s) e o catálogo de serviços para o SLA (portfólio/serviços /atividades).

## Procedimento

1. Acesse a funcionalidade "**Tempo de atendimento**" no guia principal
2. Digite no campo "**Título do SLA**" para pesquisar o SLA desejado

## Cadastro

Por padrão, o tipo de SLA é Global. Para cadastrar, clique no botão de adicionar "**+**" no canto inferior da tela e preencha os dados básicos do SLA:

| **Campos de Dados Básicos**              | **Descrição**                                                                                                          |
| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| **Título (\*)**                          | Título de identificação do SLA                                                                                         |
| **Status (\*)**                          | Status entre "**Ativo**" ou "**Inativo**"                                                                              |
| **Impacto**                              | Defina o impacto do SLA entre "**Alto**", "**Médio**" e "**Baixo**"                                                    |
| **Urgência**                             | Defina a urgência do SLA entre "**Alta**", "**Média**" e "**Baixa**"                                                   |
| **Mudança de Impacto/urgência**          | Informe se o impacto ou urgência pode ser alterado em um registro de solicitação de Incidente ou Serviço               |
| **Sazonal**                              | Selecione se o SLA será utilizado de tempos em tempos                                                                  |
| **Data de início (\*)**                  | Defina a data inicial do SLA                                                                                           |
| **Data de término**                      | Defina a data final do SLA **(obrigatório se a opção Sazonal estiver marcada)**                                        |
| **Avalia em**                            | Defina a data de avaliação do SLA                                                                                      |
| **Descrição**                            | Descrição relevante para utilizar o SLA                                                                                |
| **Escopo**                               | Escopo do SLA                                                                                                          |
| **Contatos**                             | Contato do SLA                                                                                                         |
| **Tempos de Atendimento por prioridade** | O tempo de atendimento do serviço, levando em consideração o tempo de definição de prioridade para captura e resolução |
| **Hora**                                 | Informe a hora de "**captura**" e "**resolução**" do SLA                                                               |
| **Minuto**                               | Informe os minutos de "**captura**" e "**resolução**" do SLA                                                           |
| **Automação**                            | Selecione o "**Tempo da ação**", "**E-mail template**", "**Prioridade**" e "**Grupo**"                                 |
| **Unidade&#x20;**                        | Preencha com os nomes das unidades e suas prioridades (\*)                                                             |
| **Empregado**                            | Adicione os nomes e prioridades dos empregados, selecione também a caixa "crítico" se for o caso (\*)                  |
| **Grupo do Solicitante**                 | Digite o nome dos solicitantes e suas prioridades (\*)                                                                 |

(\*) Indica campos obrigatórios.

:::hint{type="success"}
✅ ***Regra*****:** A prioridade é usada para identificar o tempo necessário para que uma ação seja tomada. A prioridade vai de **1 a 5**, sendo que é **1 a prioridade mais alta** e **5 a mais baixa**.


**Selecione a prioridade para definir o Horário (no SLA):&#x20;**&#x20;

- **Captura:** defina o tempo de captura da requisição de serviço, de acordo com a prioridade selecionada;   &#x20;
- **Resolução:** defina o tempo de resolução do serviço, de acordo com a prioridade selecionada.
:::

:::hint{type="warning"}
⚠️ ***Atenção*****!**

Antes de preencher os campos em "**Automação**", ele deve ser parametrizado corretamente. Portanto, é necessário executar as etapas na regra de escalação da Criação de conhecimento, **exceto o parâmetro 190 que deve ser igual a "N" neste contexto**.
:::

5\. Preencha os campos de Automação (se necessário):

| **Campos de Automação** | **Descrição**                                                          |
| ----------------------- | ---------------------------------------------------------------------- |
| **Tempo de Ação**       | Tempo para a execução de uma ação automática                           |
| **Modelo de E-mail**    | Modelo de E-mail utilizado para enviar notificações                    |
| **Prioridade**          | A nova prioridade que o serviço que será agendado receberá             |
| **Grupo**               | Grupo a quem a assistência será direcionada após a ação de agendamento |

(\*) Indica campos obrigatórios.

:::hint{type="info"}
**🖊&#x20;*****Nota*****:** Para efeito de cálculo de SLA, o sistema realiza as seguintes verificações:

- O sistema considera para a atribuição de SLA:
  - **Impacto e urgência:** Esse atributo, sendo identificado para mais de um tipo de <font color="#3b9f0f">**serviço x contrato**</font> para o mesmo tipo de SLA, sempre leva em consideração a prioridade de menor impacto, ou seja, **nota 5**;
- O sistema considera para a atribuição de SLA:
  - **Os usuários, grupos ou Unidades especiais (conhecidos como VIP’s)**. Nesses casos, o normal é o administrador cadastrar SLA’s Globais com baixa prioridade e incluir usuários, unidades e grupos que podem receber SLA’s com prioridade mais alta.
:::

É possível identificar qual cliente/contrato está utilizando que tipo de serviço do catálogo de serviços (de acordo com as permissões e o contrato de nível de serviço). Ao atribuir atividades ao SLA, o sistema permitirá que o usuário visualize/edite o valor financeiro do Serviço.&#x20;

Já com relação às horas de serviço, estas se referem às horas de trabalho do contrato de nível de serviço utilizado e serão referenciadas para todos os serviços e atividades.&#x20;

Outra questão que vale destacar é sobre o Monitor de Acordos de Nível de Serviço poder ser monitorado em relação ao nível de serviço acordado com a finalidade de controlar violações e exceções de serviço que aparecem na tela principal de incidentes e requisições de serviço, por meio do campo **"Status do SLA"**. É possível fazer o mesmo monitoramento utilizando os painéis de incidentes e requisições de serviço. Ambos (tela principal/painéis) monitorarão em tempo real.

:::hint{type="info"}
**🖊** ***Nota*****:** Os tipos de contratos recuperados são SLAs associados, contratos de serviços de apoio/fornecedores.
:::

:::hint{type="warning"}
⚠️ ***Atenção*****!**

Se o tempo de atendimento não permitir a mudança de impacto e urgência, o sistema substituirá automaticamente o que é enviado via WebService pelo impacto, urgência, prioridade e tempo de atendimento definidos neste registro.
:::

:::hint{type="success"}
✅ ***Regra*****:** Antes dos N minutos (informados no horário da ação) e caso não tenha realizado nenhuma ação na requisição de serviço a esse horário, o sistema atribuirá a prioridade e encaminhará o grupo de execução à requisição de serviço.
:::


[title] Cadastrar uma Liberação
[path] 16 Processos/Untitled/

Segundo a ITIL, <font color="#3b9f0f">**Liberação** </font>é "**ma ou mais mudanças a um serviço de TI que são construídas, testadas e implantadas ao mesmo tempo.&#x20;**&#x55;ma única liberação pode incluir mudanças ao *hardware, software*, documentação, processos e outros componentes".

Esta funcionalidade disponibiliza ações diversas, tais como: <font color="#3b9f0f">**incluir, alterar e excluir uma liberação**</font>.

## Antes de Começar

- [x] Compras/provisionamento devem ser inicializados em uma requisição de serviço (em um catálogo de serviços especificado). A solicitação de serviço deve ser verificada no CMDB se houver licença, hardware ou item específico solicitado disponível. Somente após este procedimento a liberação será criada;
- [x] É necessário ter criado a RDM (requisição de mudança);
- [x] É necessário ter registrado previamente o portfólio de liberação, o funcionário, contrato, unidade vinculada ao contrato, grupo executor vinculado ao contrato,
  &#x20;tipo de liberação e grupo de atividades periódicas.

## Procedimento

1. Acesse a funcionalidade por meio da navegação no menu principal `Processos >
    Gerência de Liberação > Liberação`;
2. Clique no botão **“Opções”** e, em seguida, e&#x6D;**&#x20;"Cadastro"**;
3. No começo da página, teremos as seguintes informações:

| **Informação**           | **Descrição**                                                                                                                                                                                                                                                                                                                                                                                                           |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Número**               | O número que identificará a liberação                                                                                                                                                                                                                                                                                                                                                                                   |
| **Fase**                 | A fase da liberação                                                                                                                                                                                                                                                                                                                                                                                                     |
| **Prioridade**           | A prioridade da liberação quando criada                                                                                                                                                                                                                                                                                                                                                                                 |
| **Grupo atual**          | O grupo responsável pela liberação quando criado                                                                                                                                                                                                                                                                                                                                                                        |
| **Responsável**          | A pessoa que será responsável pela liberação                                                                                                                                                                                                                                                                                                                                                                            |
| **Visualizar fluxo**     | Esses são os status da liberação no fluxo de serviço, que serão alterados de acordo com a manutenção da liberação. Os status do fluxo são: Liberação, Execução, Teste, Homologação e Resolvido. Existem listas de verificação para a aplicação do fluxo de trabalho para vincular itens específicos para cada fase/etapas/status do fluxo de serviço. Aparecerão quando você editar ou executar a liberação já criada.  |
| **Registro de execução** | Essas informações aparecerão após a criação da liberação e apresentarão informações do histórico sobre a mesma                                                                                                                                                                                                                                                                                                          |

## Campos de Identificação

Ao criar uma liberação, preencha os campos para a identificação.

| **Campo**              | **Descrição**                                  |
| ---------------------- | ---------------------------------------------- |
| **Nome (\*)**          | Identificar o nome da requisição               |
| **Contato (\*)**       | Informar o contato do solicitante              |
| **E-mail (\*)**        | O e-mail do solicitante                        |
| **Telefone**           | O número de telefone do solicitante            |
| **Ramal**              | O número do ramal do solicitante               |
| **Unidade (\*)**       | A unidade do solicitante                       |
| **Localidade física**  | A localização do solicitante                   |
| **Outras informações** | Toda informação necessária sobre o solicitante |

(\*) Indica campos obrigatórios.

### <font color="#3b9f0f">Liberação</font>

| **Campo**               | **Descrição**                                                  |
| ----------------------- | -------------------------------------------------------------- |
| **Pesquisar aqui**      | Para pesquisar o portfólio que você deseja                     |
| **Portfólio (\*)**      | Selecionar o portfólio da liberação que você está criando      |
| **Modelo (\*)**         | Selecionar o modelo do portfólio de liberação                  |
| **Título (\*)**         | O título da liberação que você está criando                    |
| **Contrato (\*)**       | O contrato relacionado ao portfólio selecionado                |
| **Grupo executor (\*)** | O grupo responsável por lidar com a liberação                  |
| **Impacto (\*)**        | Definir o grau de impacto                                      |
| **Urgência (\*)**       | Definir o grau de urgência                                     |
| **Risco (\*)**          | Definir o grau de risco                                        |
| **Data de liberação**   | Definir a data da liberação                                    |
| **Versão**              | A versão dessa liberação                                       |
| **Notificações**        | Os tipos de notificação relacionados à manutenção da liberação |

(\*) Indica campos obrigatórios.

:::hint{type="success"}
&#x20;**💭&#x20;*****Você sabia?***&#x20;

De acordo com o portfólio, os tipos de lançamento podem ser **Secundária, Principal, Significativas** e de **Emergencial**.

- **Liberação secundária** é uma versão de um produto que não adiciona novos recursos ou conteúdo. As versões de manutenção geralmente têm como objetivo solucionar problemas menores, geralmente "*bugs"* ou problemas de segurança.
- **Liberação principal** significa uma nova versão do *Software&#x20;*&#x71;ue inclui alterações na arquitetura e/ou adiciona novos recursos e funcionalidades, além das características funcionais originais da versão anterior do *software*.
- **Liberação significativa&#x20;**&#x61;diciona recursos e funcionalidade, melhorando o desempenho geral do produto, eficiência e usabilidade.&#x20;
- **Liberação emergencial** são exatamente o que parecem. Algum incidente ou cenário precisa de atenção o mais rápido possível, então será lançada uma correção temporária.
:::

### <font color="#3b9f0f">Mudanças</font>

| **Função**            | **Descrição**                                                                                                            |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| **Pesquisar mudança** | Para vincular uma mudança já criada, use esta caixa de pesquisa e selecione-a                                            |
| **Cadastrar mudança** | Para criar uma nova alteração para esta versão, clique aqui e ela será redirecionada para a tela de registro de mudanças |

### <font color="#3b9f0f">Planejamento</font>

| **Guia**                     | **Descrição**                                                                                                                                                                                                                                            |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Atividades**               | Crie um novo workspace ou vincule um existente                                                                                                                                                                                                           |
| **Papéis/responsabilidades** | Atribua as funções e responsabilidades de acordo com as necessidades                                                                                                                                                                                     |
| **Notificações do sistema**  | Defina uma notificação do sistema para informá-lo sobre a liberação                                                                                                                                                                                      |
| **Documentos**               | Para adicionar documentos para identificação e controle de todos os aspectos de um pacote de liberação, como software, hardware, documentação, requisitos de treinamento. Você também pode adicionar documentos legais e documentos gerais para controle |
| **Projetos**                 | Para criar ou vincular projetos                                                                                                                                                                                                                          |
| **Outras informações**       | Defina as datas para o planejamento: data de início, hora de início, data de término e hora de término                                                                                                                                                   |
| **Notas**                    | Adicionar notas relevantes para o planejamento da liberação                                                                                                                                                                                              |

:::hint{type="info"}
**🖊** ***Nota:*** Os *workspaces* são baseados na metodologia *Kanban* para o gerenciamento fácil e ágil das atividades. Vá para **Criando Kanban nas fases de Planejamento e Implantação** para ver como criar um espaço de trabalho
:::

### <font color="#3b9f0f">Implantação</font>

| **Guia**                     | **Descrição**                                                                                                                                                                                                                                            |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Atividades**               | Crie um novo workspace ou vincule um existente                                                                                                                                                                                                           |
| **Papéis/responsabilidades** | Atribua as funções e responsabilidades de acordo com as necessidades                                                                                                                                                                                     |
| **Notificações do sistema**  | Defina uma notificação do sistema para informá-lo sobre a liberação                                                                                                                                                                                      |
| **Documentos**               | Para adicionar documentos para identificação e controle de todos os aspectos de um pacote de liberação, como software, hardware, documentação, requisitos de treinamento. Você também pode adicionar documentos legais e documentos gerais para controle |
| **Projetos**                 | Para criar ou vincular projetos                                                                                                                                                                                                                          |
| **Outras informações**       | Defina as datas para a implantação: data de início, hora de início, data de término e hora de término                                                                                                                                                    |
| **Notas**                    | Adicionar notas relevantes para a implantação da liberação                                                                                                                                                                                               |

:::hint{type="info"}
**🖊** ***Nota:*** Os *workspaces* são baseados na metodologia *Kanban* para o gerenciamento fácil e ágil das atividades. Vá para **Criando Kanban nas fases de Planejamento e Implantação** para ver como criar um espaço de trabalho
:::

### <font color="#3b9f0f">Vincular Itens Adicionais</font>

No lado esquerdo da tela, você poderá vincular outros itens à liberação que está sendo criada.

| **Função**               | **Descrição**                                                         |
| ------------------------ | --------------------------------------------------------------------- |
| **IC relacionado**       | Pesquisar e vincular IC à liberação                                   |
| **Mídia definitiva**     | Pesquisar e criar uma mídia definitiva para ser vinculada à liberação |
| **Problema**             | Pesquisar ou criar problema vinculado à liberação                     |
| **Base de conhecimento** | Pesquisar ou criar um documento para vincular à liberação             |
| **Tickets**              | Pesquisar por um ticket para vincular à liberação                     |

## Criando Kanban nas fases de Planejamento e Implantação

Na ferramenta, as fases de Planejamento e Implantação usam *Workspaces* baseados na metodologia *Kanban* para o gerenciamento fácil e ágil das atividades, organizadas visualmente em uma estrutura com cartões que indicam o progresso do fluxo.

Este espaço é para detalhar o plano de *rollout, rollback*, validação de serviço, teste e atividades. Na área de trabalho, as atividades são inseridas e agrupadas por projetos (*workspace*), painel de tarefas (*Sprint*) e finalmente tarefas, que podem estar em grupos de cartões.

Além disso, você poderá criar u&#x6D;*&#x20;Workspace* para a fase de planejamento ou implantação que deseja.

:::BlockQuote
****<font color="#3b9f0f">**Por exemplo:** </font>para um plano de distribuição, você pode criar um espaço de trabalho chamado **"Plano de Distribuição"** e preencher as informações necessárias para realizar, incluindo as fases, o grupo responsável, notas e histórico.
:::

Para entender melhor como criar um *workspace* ou usar as fases de planejamento e implantação, consulte os documentos:

- [Gerenciamento Ágil Simple](docId\:fA-ppXkCRSDMf-1BtTNqo). Simple é a funcionalidade da ferramenta que cria os *Kanbans*
- **[Atividades da Fase de Planejamento da Liberação](docId\:r_AFozizzVI4fn6ZTOYF1)
- [Atividades da Fase de Implantação da Liberação](docId\:emlU97KH23GpugqP80t6Q)&#x20;

## Salvar

No final da página, você encontrará um botão flutuante com as funções de:

| **Função**   | **Descrição**                                                           |
| ------------ | ----------------------------------------------------------------------- |
| **Cancelar** | Para cancelar a criação da liberação                                    |
| **Gravar**   | Para salvar a liberação e criar um número para monitoramento e rastreio |

## Editar Liberação

Uma vez criada a liberação, será possível editar todas as informações que encontramos em seu registro. Além disso, aparecerá a fase **"Fechamento"**, no final da página, onde você pode alterar o *status* da liberação.

No camp&#x6F;**&#x20;Fechamento**, no final da página, há a seguinte situação:

| **Situação**    | **Descrição**                                      |
| --------------- | -------------------------------------------------- |
| **Em execução** | Para editar e visualizar a liberação sem finalizar |
| **Resolvida**   | Para resolver e finalizar a liberação              |
| **Cancelada**   | Para cancelar a liberação                          |

Para aprender sobre como finalizar a liberação, veja o documento [Executar uma Liberação](docId\:teYkX5o-kQqfWd2s28TY2).


[title] Criar Pasta
[path] 16 Processos/Untitled/

Pastas são locais utilizados na aplicação para o armazenamento e organização de arquivos.&#x20;

As bases de conhecimento do <font color="#3b9f0f">**CITSmart**</font> são construídas utilizando estruturas de diretórios. Nesses diretórios são aplicadas as permissões de leitura ou leitura e gravação, onde também deverão ser definidas as ações possíveis no processo de gestão do conhecimento: revisar, aprovar, publicar e arquivar/desarquivar.&#x20;

Além disso, é possível realizar a pré-configuração das notificações que ocorrerão, nas diversas ações do processo de gestão do conhecimento.

As permissões em pastas são aplicadas em duas perspectivas:&#x20;

- **Perfil de acesso**; e&#x20;
- **Grupo de usuários.**

Ao usar o permissionamento por perfil de acesso, você poderá controlar os perfis que poderão ler e escrever na pasta. Ao utilizar a abordagem por grupo, além do permissionamento padrão (ler e escrever), você poderá definir preferências de notificações para os diversos status dos conhecimentos.

## Antes de Começar

Para ter acesso às pastas, é necessário:

- [x] Utilizar uma forma de permissionamento (perfil ou grupo). Assim, antes de qualquer coisa você deve configurar os perfis de acesso ou criar os grupos.
- [x] Além disso, se você pretende criar preferências de notificações, será necessário definir o ID de e-mail que será utilizado no envio das mensagens. Assim, você deve criar/configurar modelos de e-mail e, logo após, realizar a configuração dos parâmetros.

## Procedimento

1. Acesse a funcionalidade por meio da navegação no menu `Processos > Gerência de Conhecimento > Pasta`;
2. Clique em **"Novo"**;
3. Preencha os campos disponibilizados;

| **Campo**                | **Descrição**                                                                                                          | **Exemplo**                                                            |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| **Nome**                 | Informar o nome da pasta                                                                                               | Service Desk                                                           |
| **Pasta Superior**       | Se você deseja criar uma pasta filha selecione uma pasta pai                                                           | Root Folder                                                            |
| **Notificar o Autor...** | Se o autor será notificado em todo o ciclo de vida do documento                                                        | Sim/Não                                                                |
| **Perfil de Acesso**     | Selecionar os perfis que terão acesso de leitura ou leitura e gravação na pasta                                        | Administrador (Leitura/Gravação)                                       |
| **Grupo**                | Selecionar os grupos que terão acesso de leitura ou leitura e gravação na pasta e atribuir preferências de notificação | Knowledge Managers (**Leitura/Gravação:** Publicar, Aprovar e Deletar) |

:::hint{type="info"}
🖊 ***Nota*****:** **Permissão/Notificação por Grupo**



****<font color="#3b9f0f">**Permissão:**</font>
&#x20;Conforme vimos anteriormene, existem dois tipos de permissionamentos na opção de grupos: **leitura&#x20;**&#x6F;u **leitura/gravação**. Essas duas permissões são utilizadas para controlar o tipo de ação dentro de uma pasta.

- **Leitura:&#x20;**&#xC9; possível visualizar o conhecimento registrado e seu teor.
- **Leitura/Gravação:** Além de conseguir ver o documento e suas informações é possível executar diversas ações para realizar a gestão do conhecimento: **Publicar, Aprovar, Revisar, Arquivar/Desarquivar e/ou Deletar**.

****

****<font color="#3b9f0f">**Notificação:**</font>
&#x20;A opção de notificação possibilita que os integrandes do grupo recebam mensagems de e-mail informando acerca de conhecimentos que tenham a sua situação alterada.
&#x20;Notificar quando houver mudança de situação do conhecimento: **Em desenho, Em revisão, Revisado, Em avaliação, Avaliado, Em publicação, Publicado e/ou Arquivado**.
:::

4\. Clique em **"Gravar"**.



:::hint{type="info"}
💡 ***Dica*****:** As configurações para uso de notificações só funcionarão quando você definir as partes interessas em um conhecimento.&#x20;



As configurações das pastas são apenas uma preparação (pré-configuração) para uso nas fases da gestão do conhecimento, ou seja, somente quando você começar a criar novos conhecimentos ou quando você realizar uma ação em um Conhecimento já existente é que, de fato, você poderá usar as preferências definidas nas pastas ou definir novas preferências.&#x20;



Estas prefências são definidas na aba <font color="#3b9f0f">**"Partes interessadas"**</font> de cada conhecimento. Para mais informações, acesse a documentação [Criar Conhecimento](docId:0Sj4gBeo4KnF3VpjCoMfw).
:::


[title] Como Navegar na Interface do Usuário
[path] Configurações Iniciais/Configurações Iniciais/

A interface do usuário é a maneira mais fácil deste interagir com aplicativos e informações em uma **instância** <font color="#3b9f0f">**CITSmart**</font>.

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/k8j42RY-pPlQmd9hfD7Yz_image.png)

**1. Banner frame**: na área interna do sistema, a barra de tarefas contém itens de navegação e ferramentas, como:

- O menu principal, com todas as funcionalidades <font color="#3b9f0f">**CITSmart**</font>**;**&#x20;
- Botões com integração VoIP;&#x20;
- A assistente virtual <font color="#3b9f0f">**Anuva**</font>;&#x20;
- Informações sobre o login de usuário,&#x20;
- Versão do ambiente; e&#x20;
- Sobre mudança de idioma;

**2. Navegação em aplicativos**:&#x20;

- Acesso aos **16 processos certificados** da <font color="#3b9f0f">**CITSmart**</font>**;**
- Funcionalidades de cadastros básicos;
- Criação e emissão de relatórios;
- Parâmetros;
- Acesso ao <font color="#3b9f0f">**CITSmart**</font> **Neuro** (engine de aplicativos);
- E outras funcionalidades de gerenciamento da plataforma.

**3. Painel do usuário**:&#x20;

- Determina o layout de apresentação do painel do usuário (*Smart Decision*), disponível na página inicial da **Plataforma** <font color="#3b9f0f">**CITSmart**</font>.&#x20;
- Permite colocar acessos rápidos como links, relatórios e *widgets*.

## Tour pela Interface do Usuário

### Banner Frame



::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/cR0Bo9bYyQWmckzF8AuyO_image.png" size="76" width="917" height="58" position="center" showCaption="false"}

A barra de tarefas, localizada na parte superior, contém itens de navegação e ferramentas:

- ****<font color="#3b9f0f">**1**</font>: Menu principal de navegação, contém todos os processos e funcionalidades <font color="#3b9f0f">**CITSmart**</font>;
- ****<font color="#3b9f0f">**2**</font>: Ao navegar pelo sistema e quiser retornar à tela inicial, clique no botão **"Home"**;
- ****<font color="#3b9f0f">**3**</font>: Notificações do sistema para o usuário, que é evidenciado com a quantidade existente;
- ****<font color="#3b9f0f">**4**</font>: Atendimento via chamada **VOIP**;
- ****<font color="#3b9f0f">**5**</font>: Chat de atendimento (visível a usuários de grupos de atendimento);
- ****<font color="#3b9f0f">**6**</font>: Atalho para os principais aplicativos do sistema;
- ****<font color="#3b9f0f">**7**</font>: Informações do usuário, além de disponibilizar mudança de idioma do sistema, gerenciar o *status* que aparece no chat, meios de suporte do <font color="#3b9f0f">**CITSmart**</font> e dados sobre a versão do ambiente instalado.

### Navegação em Aplicativos

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/mn7L4CRJ7-N5ptdP_hpb6_image.png" size="40" width="296" height="494" position="center" showCaption="false"}

Ao clicar no menu principal de navegação, serão visualizadas todas as funcionalidades que o <font color="#3b9f0f">**CITSmart**</font> disponibiliza.

- ****<font color="#3b9f0f">**1**</font>: Barra de pesquisa de funcionalidades, acessível via menu;
- ****<font color="#3b9f0f">**2**</font>: Acesso às configurações referentes à manutenção de fluxos;
- ****<font color="#3b9f0f">**3**</font>: Possui todos os **16 Processos** certificados d&#x61;**&#x20;Plataforma** <font color="#3b9f0f">**CITSmart**</font>;
- ****<font color="#3b9f0f">**4**</font>: A gestão integrada dispõe de funcionalidades que auxiliam na gestão dos processos;
- ****<font color="#3b9f0f">**5**</font>: Apresenta cadastros básicos para se iniciar o <font color="#3b9f0f">**CITSmart**</font>, como usuários, localidade, além de poder cadastrar e editar menus dentro do sistema;
- ****<font color="#3b9f0f">**6**</font>: Possui dados para administrar &#x6F;**&#x20;Centro de Experiência**, que é um portal personalizável para o usuário;
- ****<font color="#3b9f0f">**7**</font>: Disponibiliza diversos tipos de relatórios que o sistema pode gerar com dados das principais funcionalidades, tornando assim, as informações possíveis de serem melhor analisadas, além de permitir a criação de relatórios personalizados;
- ****<font color="#3b9f0f">**8**</font>: Configuração de acesso e permissões no sistema;
- ****<font color="#3b9f0f">**9**</font>: Configuração dos parâmetros de aplicativos e do sistema;
- ****<font color="#3b9f0f">**10**</font>: Funcionalidades para administrar &#x61;**&#x20;Plataforma** <font color="#3b9f0f">**CITSmart**</font>;
- ****<font color="#3b9f0f">**11**</font>: Acesso ao <font color="#3b9f0f">**CITSmart**</font> **Neuro** (engine de aplicativos).

### Painel do Usuário (Smart Decision)

::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/zXuacwHk8RvV87Ov6cH3h_image.png" size="86" width="923" height="245" position="center" showCaption="false"}

Personalização do **Painel do Usuário** (***Smart Decision***) apresentado na página inicial do sistema, onde é possível colocar acessos rápidos como links, relatórios e *widgets*.

- ****<font color="#3b9f0f">**1**</font>: Barra vertical contendo os painéis cadastrados. Os itens da barra podem ser deslocados para se ajustar à necessidade do usuário;
- ****<font color="#3b9f0f">**2**</font>: Itens para editar uma *dashboard*;
- ****<font color="#3b9f0f">**3**</font>: Itens para editar *widgets* de uma *dashboard*;
- ****<font color="#3b9f0f">**4**</font>: Exemplo de um *widget* do tipo “link”, podendo contê-los dos tipos internos e externos.


[title] Criar um Portfólio de liberação
[path] 16 Processos/Untitled/

Esta funcionalidade tem por objetivo <font color="#3b9f0f">**criar um portfólio de liberações a fim de agilizar a criação
 de uma nova liberação ao agrupar as mesmas por critérios específicos**</font>.

## Procedimento

1. Acessar a funcionalidade através da navegação no menu principal `Processos >
    Gerência de Liberação > Portfólio de Liberação`;
2. Clicar no botão "**Novo Portfólio**" e preencher os campos:

| **Campo**     | **Descrição**                                    |
| ------------- | ------------------------------------------------ |
| **Nome(\*)**  | Identificar o portfólio de liberação por um nome |
| **Descrição** | Uma descrição para o portfólio                   |
| **Ícone**     | Selecionar uma imagem para o portfólio           |

(\*) Indicar os campos obrigatórios.

### Novo modelo

Após criar o portfólio, selecione-o e clique em "**Avançar**". Em seguida, clique em "**Novo modelo**" e preencha os campos:

| **Campo**                   | **Descrição**                                                |
| --------------------------- | ------------------------------------------------------------ |
| **Ícone**                   | Definir uma imagem para representar o portfólio              |
| **Nome (\*)**               | Nome do portfólio                                            |
| **Descrição**               | Descrever o portfólio                                        |
| **Fluxo (\*)**              | Selecionar um fluxo para o portfólio                         |
| **Grupo executor (\*)**     | Selecione o grupo responsável pela execução do portfólio     |
| **Calendário (\*)**         | Selecionar o tipo de calendário para o portfólio             |
| **E-mail Criação (\*)**     | Selecione o modelo para criação de e-mail                    |
| **E-mail finalização (\*)** | Selecione o modelo para conclusão de e-mail                  |
| **E-mail ações (\*)**       | Selecione o modelo para Ações de e-mail                      |
| **Impacto (\*)**            | Definir o grau de impacto                                    |
| **Urgência (\*)**           | Definir o grau de Urgência                                   |
| **Categoria(\*)**           | Selecione a categoria para o portfólio                       |
| **Status(\*)**              | Definir o status deste modelo como novo, ativo ou aposentado |
| **Contratos**               | Vincular um contrato                                         |

:::hint{type="info"}
🖊 ***Nota*****:&#x20;**&#x44;e acordo com o status, o modelo, quando você avançar no portfólio, aparecerá na guia **Novo**, **Ativo&#x20;**&#x6F;u **Aposentado&#x20;**&#x65; é possível editá-lo ou excluí-lo.&#x20;
:::

Depois de preencher todos os campos, clicar em "**Gravar**".


[title] Cadastrar as ocorrências de Liberação
[path] 16 Processos/Untitled/

Esta funcionalidade permite <font color="#3b9f0f">**cadastrar as eventuais ocorrências** </font>referentes à liberação.

## Procedimento

1. Acesse a funcionalidade por meio da navegação no menu principal `Processos > Gerência de Liberação > Liberação`;
2. Localize a liberação que deseja incluir o registro de ocorrência e clique no botão **“Abrir”**;
3. Clique no ícone **“Registro de Execução”** (último ícone do lado direito da tela, abaixo do campo de pesquisa) e, em seguida, aperte em **“Adicionar Ocorrência”**;
4. Clique no botão **“Adicionar Ocorrência”** e preencha os campos obrigatórios;

:::hint{type="info"}
🖊 ***Nota*****:&#x20;**&#xC9; possível cadastrar novas categorias e origens que melhor se adequam a
&#x20;ocorrência, ao clicar no ícone “**+**” e preencher os campos necessários. No histórico fica registrado todas as ações realizadas desde a criação até o encerramento, servindo como Auditoria.
:::

5\. Clique em **“Gravar”** para efetuar a operação.


[title] Cadastrar um Colaborador
[path] Configurações Iniciais/Configurações Iniciais/

Esta funcionalidade permite <font color="#3b9f0f">**cadastrar cada pessoa que possua algum tipo de vínculo com a organização**</font>, como funcionários, parceiros, etc, disponibilizando ações diversas para este fim, como: incluir, alterar e excluir um colaborador.

## Antes de Começar

- [x] Para registrar um colaborador, é necessário cadastrar anteriormente uma unidade e um cargo.

## Procedimento

1. Acesse a funcionalidade por meio do menu principal `Cadastros Gerais > Gerência de Pessoal > Colaborador`;
2. Clique na aba desejada (**Cadastro/Pesquisa**), e nas ações, conforme a necessidade:

| **Função**  | **Descrição**                        |
| ----------- | ------------------------------------ |
| **Gravar**  | Salvar o novo SLA                    |
| **Excluir** | Deletar o SLA editado                |
| **Limpar**  | Limpar todos os campos do formulário |

## Pesquisar

**Selecione o colaborador para pesquisar:**

| **Filtro**   | **Descrição**                                       |
| ------------ | --------------------------------------------------- |
| **Nome**     | Nome do colaborador para pesquisa                   |
| **CPF**      | CPF do colaborador                                  |
| **Situação** | Selecione entre: "Ativo" e "Inativo" para pesquisar |
| **Grid**     | Opções de pesquisar e limpar                        |

3\. Preencha os campos necessários;

### Informação de usuário

| **Campos**               | **Descrição**                                                                                                                     |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
| **Nome(\*)**             | Nome completo do colaborador                                                                                                      |
| **Tipo de Parceiro(\*)** | Tipo de Parceiro: "Contrato de Empresa", "Colaborador", "Estágio","Freelancer","Não Funcionário","Outros","Sócio" e "Solicitante" |
| **Situação (\*)**        | Defina o status entre: "Ativo" e "Inativo"                                                                                        |
| **E-mail (\*)**          | Defina o e-mail do colaborador                                                                                                    |
| **Telefone (\*)**        | Defina o número de telefone do colaborador                                                                                        |
| **Ramal**                | Defina o ramal do colaborador                                                                                                     |
| **Unidade (\*)**         | Defina a unidade do colaborador                                                                                                   |
| **Cargos (\*)**          | Defina o cargo do colaborador                                                                                                     |

(\*) Indica campo obrigatório.

### Informações de Pagamento

| **Campos**                                         | **Descrição**                                               |
| -------------------------------------------------- | ----------------------------------------------------------- |
| **Valor de Salário**                               | Adicione o valor do salário do colaborador                  |
| **Valor Produtividade Média**                      | Adicione a média do valor de produtividade do colaborador   |
| **Valor Plano de Saúde (Valor pago pela empresa)** | Adicione o valor do plano de saúde pago pela Empresa        |
| **Valor Vale Transporte (Média)**                  | Adicione o valor médio do vale transporte pago pela empresa |
| **Valor Vale Refeição/Alim.(Média)**               | Adicone o valor médio do vale refeição do colaborador       |
| **Custo por Hora (Calculado pelo sistema)**        | Adicione o custo por hora do colaborador                    |
| **Custo Total Mensal (Calculado pelo sistema)**    | Adicione o custo mensal do colaborador                      |
| **Agência**                                        | Adicione a agência bancária do colaborador                  |
| **Conta**                                          | Adicione a conta bancária do colaborador                    |

### Dados Pessoais

| **Campos**                         | **Descrição**                                                                                          |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------ |
| **CPF/CNPJ**                       | Defina o CPF ou CNPJ do colaborador                                                                    |
| **Data de nascimento**             | Defina a data de nascimento do colaborador                                                             |
| **Sexo**                           | Selecione entre os gêneros: "Masculino" e "Feminino"                                                   |
| **RG**                             | Defina o RG do colaborador                                                                             |
| **Data de emissão RG**             | Defina a data de emissão do RG do colaborador                                                          |
| **Órgão Exp. RG**                  | Defina o órgão expeditor do RG do colaborador                                                          |
| **UF Exped. RG**                   | Selecione a unidade federativa da emissão do RG do colaborador                                         |
| **Número CTPS**                    | Defina o número da Carteira de Trabalho e Previdência Social do colaborador                            |
| **Data de Emissão CTPS**           | Defina a data de emissão da Carteira de Trabalho do colaborador                                        |
| **Série CTPS**                     | Defina a série da Carteira de Trabalho do colaborador                                                  |
| **UF CTPS**                        | Defina a unidade da federação da Carteira de Trabalho do colaborador                                   |
| **Matrícula - NIT (PIS ou PASEP)** | Adicione a matrícula, se houver                                                                        |
| **Data de Admissão**               | Defina a data de admissão do colaborador                                                               |
| **Data de Desligamento**           | Adicione a data de desligamento do colaborador                                                         |
| **Cônjuge**                        | Informe o cônjuge do colaborador                                                                       |
| **Estado Civil**                   | Selecione o estado civil: solteiro, casado, divorciado, viúvo, separado judicialmente ou união estável |
| **Nome do Pai**                    | Defina o nome do pai do colaborador                                                                    |
| **Nome da mãe**                    | Defina o nome da mãe do colaborador                                                                    |
| **Observação**                     | Coloque uma observação sobre o funcionário, se houver alguma informação necessária ou relevante        |

4\. Por fim, clique e&#x6D;**&#x20;"Gravar"**.


[title] Configurar Acesso Externo ao Portal do Conhecimento
[path] 16 Processos/Untitled/

Este conhecimento tem por finalidade **ensinar como configurar a visualização de conhecimentos, no&#x20;**<font color="#3b9f0f">**Portal do Conhecimento**</font>**, feito por um usuário que não tenha um login e senha**.

## Antes de Começar

É necessário:&#x20;

- [x] O ambiente precisa estar online e com a funcionalidade de indexação **(SOLR) ativa**.&#x20;
- [x] Saber o endereço URL do acesso ao Portal do Conhecimento.

## Procedimento

### <font color="#3b9f0f">Passo 1:</font>

1. Acesse o menu principal `Sistema > Configurações > Gerência de Conhecimento (Indexação)`;
2. Clique no botã&#x6F;**&#x20;"Atualizar o servidor de indexação"**;
3. Clique em **"Confirmar"**.

### <font color="#3b9f0f">Passo 2:</font>

1. Acesse o menu principal `Sistema > Configurações > Portal do Conhecimento > Customizar`;
2. Para alterar a logo e o fundo do cabeçalho é preciso respeitar os tamanhos que serão apresentados na tela;
3. No campo **Acesso,** habilite o campo de **"Habilitar acesso externo"** para a opção **SIM**;
4. Clique em **"Gravar"**.

### <font color="#3b9f0f">Passo 3:</font>

1. Acesse o menu principal` Processos > Gerência de Conhecimento > Conhecimento`;
2. Para criar um novo conhecimento, clique no botão **"Opções"** e, em seguida, em **"Adicionar novo conhecimento"**;
3. Para editar um conhecimento já existente, realize a busca do mesmo utilizando os filtros disponibilizados e, em seguida, clique no botão **"Editar"&#x20;**&#x64;o conhecimento;
4. Preencha os campos disponibilizados e se atente quanto aos campos:
   - **Privacidade,** o mesmo deverá ser *Público;* e
   - **Acesso** deverá ser *Externo;*
5. No campo **Publicar**, habilite a chave para a opçã&#x6F;**&#xA0;SIM**.

## O que Fazer a Seguir

Acesse o <font color="#3b9f0f">**Portal do Conhecimento**</font> e realize a busca por algum conhecimento sem logar.


[title] Untitled
[path] /


[title] Cadastrar Usuário Externo
[path] Configurações Iniciais/Configurações Iniciais/Criar Perfil de Acesso/

Esta funcionalidade tem por objetivo **o cadastro de usuário que não possua acesso ao**<font color="#3b9f0f"> **CITSmart**</font>.

## Antes de Começar

- [x] O provedor deverá ter o WAR PROFILE na mesma instância do <font color="#3b9f0f">**CITSmart**</font> e no mesmo JBOSS;
- [x] Não há nenhuma configuração adicional nos standalones para se conectar ao WAR PROFILE.

## Procedimento para Configurar Usuário Externo

Informe o conteúdo abaixo nos parâmetros:

| **Parâmetro** | **Nome**                                                                                              | **Finalidade**                                                                                     |
| ------------- | ----------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| **33**        | URL de acesso ao sistema                                                                              | Informe a URL de acesso ao sistema                                                                 |
| **39**        | LDAP - ID do perfil de acesso que será setado automaticamente, caso o usuário não possua nenhum       | Informe o número de identificação (ID) do Perfil de Acesso padrão para o usuário                   |
| **45**        | LDAP - ID Grupo Padrão                                                                                | Informe o número de identificação (ID) do grupo padrão, ao qual os usuários do AD serão associados |
| **369**       | Mostrar botão de solicitação de acesso ao <font color="#3b9f0f">**CITSmart**</font> na tela de login? | Para configurar se será apresentado o botão de acesso ao citsmart na tela de login                 |

## Procedimento para acessar o <font color="#3b9f0f">**CITSmart**</font>

Na tela de login no sistema, após clicar no lin&#x6B;**&#x20;"Não tem um cadastro? Solicite seu acesso"**, será apresentada uma tela de preenchimento com os seguintes campos:

| **Campo**                    | **Descrição**                                                                                                                                                                                  |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Nome**                     | Informe o nome do usuário externo que terá acesso ao sistema                                                                                                                                   |
| **Sexo**                     | Selecione entre os gêneros "masculino" e "feminino"                                                                                                                                            |
| **CPF**                      | Informe o número de inscrição do usuário                                                                                                                                                       |
| **Telefone**                 | Campo não obrigatório que guardará o número do telefone do solicitante                                                                                                                         |
| **E-mail (\*)**              | Campo obrigatório que guardará o e-mail do solicitante. Dessa forma, o cadastro deverá possuir esse campo, conforme informado                                                                  |
| **Login**                    | Informe o login que servirá para o acesso do usuário ao sistema                                                                                                                                |
| **Senha**                    | Informe uma senha para acesso ao sistema                                                                                                                                                       |
| **Digite novamente a senha** | Informe a senha de acesso novamente                                                                                                                                                            |
| **Complete a alteração**     | Autentique a sua solicitação por meio do **Captcha** (Método utilizado para que o sistema tenha garantias de que não se trata de uma tentativa de invasão via automação de robôs, por exemplo) |


[title] O que é CITSmart?
[path] Sobre o CITSmart/

O <font color="#3b9f0f">**CITSmart**</font>, é uma **plataforma que conecta pessoas e recursos digitais para otimizar o trabalho e amplificar os resultados do negócio.**

Por meio dos portais de relacionamento, otimizamos a experiência de clientes e colaboradores. Além disso, por meio do ***Workflow Digital Inteligente*** e gestão ágil, com uso de *Kanbans*, conectamos times para uma maior colaboração centrada no cliente, gerando assim os benefícios de:

- Melhoria progressiva e interativa;
- Simplicidade na execução:
- Praticidade;
- Alinhamento; e&#x20;
- Agilidade.

## História do CITSmart

O <font color="#3b9f0f">**CITSmart**</font> é um produto que teve sua construção inicial para atender as necessidades do ITSM (Gerenciamento de Serviços de TI), principalmente para o cumprimento dos requisitos da ITIL, pregado pela instituição **Pink Elephant**, através da certificação <font color="#3b9f0f">**PinkVerify**</font>.&#x20;

Atualmente, o <font color="#3b9f0f">**CITSmart**</font> atende todos os processos da certificação. As principais funcionalidades são:

- Gestão de Tickets (incidentes e requisições);
- Portfólio de Catálogo e Serviços;
- Base de Conhecimento;&#x20;
- Mudança; e&#x20;
- CMDB.&#x20;

O público atual da <font color="#3b9f0f">**CITSmart**</font> são empresas com departamentos de TI, bem como com as necessidades da solução ITSM para administar suas TIs.

## Quais as possibilidades de uso?

Há *cases* de gestão de serviços com processos automatizados em diversas áreas, como:

- **Educação**
- **Compras**
- **Viagem**
- **Recursos humanos:&#x20;**&#x73;olicitação de pessoal, treinamento, etc.
- **Departamento pessoal:&#x20;**&#x73;olicitação de benefícios, férias, folha de pagamento, esclarecimentos, etc.
- **Jurídico:** elaboração e análise de contratos, apoio, etc.
- **Atendimento em campo:&#x20;**&#x74;roca de equipamentos, execução de reparos e manutenção, etc.
- **Comunicação**
- **Marketing**, entre outros.

A plataforma <font color="#3b9f0f">**CITSmart** </font>oferece uma interface totalmente virtual em HTML5 através do browser, e é compatível com Edge (versão 93), Chrome (versão 93) e Mozila (versão 88).

O CITSmart também é uma plataformaMultitenant, sendo possível a criação de diversas instâncias independentes, com acessos e configurações distintos.

A plataforma contém requisitos de acessibilidade de acordo com o padrão internacional WCAG 2.0 Level A (Web Content Accessibility Guidelines) da W3C.

A solução <font color="#3b9f0f">**CITSmart** </font>também é multilínguas, sendo disponibilizada totalmente nos idiomas Português, Inglês e Espanhol.

Nós oferecemos uma base de dados centralizada para todos os seus módulos, podendo se integrar com diversas outras bases de dados através de conexões com bancos distintos.



## Sobre ITIL

A ITIL, do inglês *Information Technology Infrastructure Library ou*, em português,*&#x20; Biblioteca de Infraestrutura de Tecnologia da Informação,* é o padrão de referência para o gerenciamento de projetos de TI mais aceitos mundialmente.&#x20;

A estrutura da ITIL foi proposta pela CCTA (*Central Computer and Telecommunications Agency*) e seu propósito era desenvolver métodos e padrões dentro dos departamentos do governo britânico, com o objetivo de melhorar os processos internos.&#x20;

A ITIL é uma estrutura que recomenda as melhores práticas para o gerenciamento de serviços de TI e fornece recursos para atender à norma ISO/IEC 20000, incorporando as melhores recomendações contidas no CMMI, PMBOK, COBIT, Six Sigma e ISO 20000.

Por isso, seguindo as melhores práticas de gestão de serviços, com base na biblioteca de melhores práticas da ITIL, o <font color="#3b9f0f">**CITSmart**</font> possui nativamente **16 processos** automatizados. São eles:

1. **AM:** <font color="#3b9f0f">**Gerenciamento de Ativos**</font>****
2. **AVM:** <font color="#3b9f0f">**Gerenciamento de Disponibilidade**</font>****
3. **CAP:&#x20;**<font color="#3b9f0f">**Gerenciamento de Capacidade**</font>****
4. **CHG:**<font color="#3b9f0f"> **Gerenciamento de Mudança**</font>****
5. **EV:** <font color="#3b9f0f">**Gerenciamento de Eventos**</font>****
6. **FM:** <font color="#3b9f0f">**Gerenciamento Financeiro**</font>****
7. **IM:** <font color="#3b9f0f">**Gerenciamento de Incidentes**</font>****
8. **ITSCM:**<font color="#3b9f0f"> **Gerenciamento de Continuidade de Serviços de TI**</font>****
9. **KM:** <font color="#3b9f0f">**Gerenciamento do Conhecimento**</font>****
10. **PM:&#x20;**<font color="#3b9f0f">**Gerenciamento de Problema**</font>****
11. **REL:** <font color="#3b9f0f">**Gerenciamento de Liberação e Implantação**</font>****
12. **RF:** <font color="#3b9f0f">**Cumprimento de Requisição**</font>****
13. **SACM:** <font color="#3b9f0f">**Gerenciamento de Ativos de Serviço &amp; Gerenciamento de Configuração**</font>****
14. **SCM:** <font color="#3b9f0f">**Gerenciamento do Catálogo de Serviço**</font>****
15. **SLM:&#x20;**<font color="#3b9f0f">**Gerenciamento de Nível de Serviço**</font>****
16. **SPM:&#x20;**<font color="#3b9f0f">**Gerenciamento de Portfólio**</font>****

## Anuva

A <font color="#3b9f0f">**ANUVA**</font> também foi iniciada e representa a **Inteligência Artificial** do <font color="#3b9f0f">**CITSmart**</font>, responsável por promover a integração e o aprendizado de máquina com conhecimento.

## Neuro

O <font color="#3b9f0f">**NEURO**</font> é um produto 100% pronto e muito poderoso, adequado no <font color="#3b9f0f">**CITSmart**</font>, que permite a construção de novas funcionalidades, aplicações e integrações com a plataforma. É muito próximo dos produtos RPA (automação de processos de robótica), contudo, traz diferentes possibilidades, como a integração natural com a estrutura de Service Management (SLAs, conhecimento, portfólio, tickets, portal de serviços, entre outros).&#x20;

Além disso, entendemos que os conceitos de Service Management são muito poderosos e podem ir além da TI, permitindo ganhos interessantes para as
&#x20;unidades de negócio.

## Evolução

A principal mudança introduzida no ano passado foi o foco nos processos de negócios para além da TI, ou seja, **Corporate Service Management**, prova disso é a adaptação da declaração de serviço que se tornou Conexão de processos, entregando experiências.

Esta decisão foi baseada na capacidade do nosso Workflow de se adaptar às várias necessidades do negócio, e no <font color="#3b9f0f">**Neuro**</font>, permitindo a construção de novas entradas de dados e possibilidades de integração. Também criamos, no ano de 2018, os produtos **CE - Centro de Experiências**. Este produto é voltado para a criação de um construtor de espaço de trabalho digital.


[title] Notificar Responsável da Expiração de Conhecimento
[path] 16 Processos/Untitled/

Este conhecimento tem por objetivo <font color="#3b9f0f">**configurar a notificação por e-mail**</font> **para avisar o responsável (criador e publicador) acerca da expiração de conhecimentos**.

## Antes de Começar

- [x] É necessário ter ao menos um conhecimento cadastrado na base de conhecimento.

## Procedimento

1. Configure o **parâmetro 78** com a quantidade de dias anteriores a expiração do conhecimento do qual deseja notificar seu responsável;
2. Crie um rotina de processament&#x6F;*&#x20;batch* de notificação:
   - Acesse a funcionalidade por meio do menu principal `Sistema > Processamento Batch` e clique no botão **"Novo"**;
   - Defina a descrição da rotina, selecione o tipo **"Classe Java"** e estabeleça a situação como **"Ativo"**;
   - Selecione o agendamento com&#x6F;**&#x20;"Diário"** e indique o horário em que será processada a rotina;
   - Na área **"Conteúdo"**, copie o script abaixo:
     - `br.com.centralit.citcorpore.quartz.job.VerificaValidadeBaseConhecimento`
   - Clique no botão **"Gravar"&#x20;**&#x70;ara efetuar a operação.
3. Se desejar, é possível personalizar o modelo de e-mail. Basta acessar a funcionalidade pelo menu principal `Sistema > Configuração > Modelo de e-mail`, selecione o **modelo de e-mail com ID = "7"** e realize a mudança pretendida.


[title] Cadastrar Pesquisa de Satisfação
[path] 16 Processos/Portfólio e Catálogo/

Esta funcionalidade disponibiliza ações diversas, tais como: <font color="#3b9f0f">**incluir, alterar e
 excluir pesquisas de satisfação,**</font> de acordo com suas necessidades.

O formulário da pesquisa é construído na forma de um questionário.

Os tipos de pesquisa podem ser:

- **Público:** permite a participação de todos os usuários sem nenhum tipo de
  &#x20;restrição, inclusive, eles nem precisam estar autenticados no sistema. Nesta
  &#x20;modalidade, a URL do Sistema (parametrizada) é fornecida ao público-alvo
  &#x20;para que participem da pesquisa. Trata-se de um campo somente de saída (sem
  &#x20;digitações). Assim que a pesquisa é criada (gravada) neste campo surge o
  &#x20;link completo, baseado na URL do Sistema devidamente parametrizada;
- **Global:** restringe a participação somente para aqueles usuários que se autenticarem
  &#x20;no sistema, podendo ser acessada de duas maneiras:
  - 1\. Quando esses usuários se identificam, recebem uma notificação automática (incluindo nesta os
    &#x20;passos para responder a pesquisa);
  - 2\. No Portal de Serviços (menu na lateral esquerda), na opção **"Campanhas
    &#x20;Ativas"**.
- **Catálogo:** destina-se à avaliação, junto ao cliente, sobre a eficácia do catálogo implantado para ele;
- **Serviço:** voltado para a avaliação, junto ao cliente, sobre a eficácia de um serviço implantado para ele;
- **Atividade/satisfação:** é mais uma opção de pesquisa de satisfação junto ao cliente (além do padrão do sistema) sobre o desfecho do atendimento de
  &#x20;uma requisição ou incidente.

## Antes de Começar

Para realizar o cadastro de uma pesquisa, é necessário:

- [x] Registrar previamente um
  &#x20;questionário; e&#x20;
- [x] Configurar o **parâmetro 33**.

## Procedimento

1. Acesse a funcionalidade `Processos > Gerência de Portfólio e Catálogo >
    Cadastro de Pesquisas`;
2. Clique em **"Novo"**;
3. Preencha os campos disponibilizados;
4. Escolha o tipo de pesquisa;
5. Por fim, clique em **"Gravar"**.


[title] Criar Perfil de Acesso
[path] Configurações Iniciais/Configurações Iniciais/

O perfil de acesso agrupa os direitos e permissões do usuário no sistema, especialmente a autorização para pesquisar por registros ou gravar e deletar informações.

Após o usuário ser autenticado, o processo de definição de acesso consulta as permissões e direitos relacionados com o seu perfil. Assim, determina o que poderá, ou não, ser feito no sistema.

Será possível, ainda, executar ações diversas, como: incluir, alterar e excluir um perfil de acesso.

## Procedimento

1. Acesse a funcionalidade apor meio da navegação no `Menu de Navegação > Acesso e Permissão > Perfil de Acesso`;
2. Insira o nome do novo perfil ou procure por um já existente, na aba de <font color="#3b9f0f">**Pesquisa**</font>;
3. Para incluir a permissão no perfil de usuário, selecione os campos de ação disponíveis (**Pesquisar, Gravar e Deletar**) de cada funcionalidade apresentada. Observe que as permissões podem ser associadas a níveis mais específicos de uma funcionalidade. Para isto, clique no sinal **+** para acessar os itens mais específicos;

:::hint{type="success"}
✅ ***Regra*****:&#x20;**&#x41;o selecionar um campo de ação em um nível superior, todos os demais níveis subordinados a este na estrutura serão igualmente marcados ou desmarcados.
:::

4\.	Além disto, indique se o perfil de usuário permitirá acesso ao sistema, através de login e senha;

5\.	Caso utilize as funcionalidades de Ordem de Serviço ou Fatura, faça as marcações para autorizar o acesso ao perfil de usuário a determinadas situações de Ordem de Serviço ou Fatura;

6\.	Clique em **"Gravar"**.


[title] Manutenção de Portfólio de Serviço
[path] 16 Processos/Portfólio e Catálogo/

## Antes de Começar

- [x] Deverá ter um contrato cadastrado.
- [x] Deverá ter uma atividade cadastrada em algum portfólio de serviço.

## Procedimento

1. Acesse o `Menu Principal > Processos > Gerência de Portfólio e Catálogo > Portfólio`;
2. Aparecerá a lista de Portfólios cadastrados e do lado direito, o botão de "**Manutenção**";
3. Ao clicar em "**Manutenção**", iremos fazer a manutenção do portfólio desejado. Primeiramente teremos as seguintes estapas:

| **Etapa**                   | **Descrição**                                                                                                                                                                                                                                                   |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Escolha a ação**          | Nessa etapa temos duas opções: **Vincular** e **Desvincular**. Ao selecionar uma das opções, será apresentada outra pergunta sobre o que você deseja vincular ou desvincular                                                                                    |
| **O que deseja vincular?**  | Também teremos duas opções nessa etapa:**&#x20;Contrato** e **Atividade**. Selecione qual dos dois você deseja vincular ao seu Portfólio                                                                                                                        |
| **No que deseja vincular?** | Caso você tenha selecionado na etapa anterior a opção **"Contrato"**, virá por padrão para você vincular uma Atividade ao seu contrato. Caso tenha selecionado anteriormente a opção **"Atividade"**, virá por padrão então o Contrato para ser vinculado a ela |
| **Conteúdos relacionados**  | É um link para cadastrar/editar um contrato, que, ao ser selecionado, irá abrir a tela de cadastro de contrato. Ao finalizar, o sistema retorna para página de manutenção do portfólio                                                                          |

### Vinculando Atividade ao Contrato

1. Essa opção é para quando você respondeu nas etapas:&#x20;

- <font color="#3b9f0f">**Escolha a ação**</font> **- Vincular;&#x20;**
- ****<font color="#3b9f0f">**O que deseja vincular?**</font>**&#x20;- Atividade;&#x20;**
- ****<font color="#3b9f0f">**No que deseja vincular?**</font>**&#x20;- Contrato**.

2\. O sistema retorna todas as atividades ativas encontradas para o serviço de negócio/apoio selecionado. Atividades ativas são as que estão com status ativo.

3\. Selecione a(s) atividade(s) que deseja vincular. Para as Atividades, temos as seguintes informações:

- **Nome**
- **Opção de filtrar**
- **ID**
- **Portfólio**
- **Serviço**
- **Contratos Vinculados**
- **Visualizar detalhes**

4\. Quando selecionadas as atividades, aparecerão dois botões:

- Um mostrando a quantidade de atividades que foram selecionadas; e&#x20;
- Outro **"Comparar atividades selecionadas"**, onde aparecerá um pop-up com as informações das atividades selecionadas.

Depois da lista de Atividades, **é hora de selecionar o&#x20;**<font color="#3b9f0f">**Contrato** </font>**que deseja vincular**.

1. O sistema apresentará a lista dos contratos ativos encontrados nas atividades selecionadas anteriormente.
2. Selecione o contrato que deseja vincular. Para os Contratos, temos as seguintes informações:

- **Nome do contrato &#x20;**
- **Opção de filtrar &#x20;**
- **Cliente &#x20;**
- **Fornecedor &#x20;**
- **Portfólio**, que irá retornar à quantidade de portfólios encontrados no contrato selecionado &#x20;
- **Visualizar detalhes**
- **Seta de detalhes do contrato**, que ao ser selecionada carrega logo abaixo as seguintes informações do contrato: **Tipo de Acordo/Contrato, Data de Contrato, Horas de Suporte, Moeda, Data Término de Contrato**

3\. Após vincular devidamente as Atividades e Contratos que deseja, clique em **"Avançar"**.

4\. Será apresentada a tela de **"Características padrões da ação em massa"**. Nessa tela, você preencherá algumas informações que servirão como características padrão da ação em massa para todas atividades e contratos que você selecionou anteriormente.

5\. Temos os seguintes campos para preencher como características padrão da ação em massa:

| **Campo**                      |
| ------------------------------ |
| Condições de operação          |
| Data de início                 |
| Calendário                     |
| Tempo de atendimento           |
| Modelo de abertura             |
| Modelo de e-mail de fechamento |
| Grupos executores              |
| Grupo aprovador                |
| Fluxo                          |

6\. Abaixo, serão apresentadas as atividades e os contratos que você selecionou anteriormente para serem vinculados.

7\. Todas as atividades e contratos selecionadas nessa etapa receberão as mesmas características informadas acima. Caso o sistema identifique uma característica para um serviço/contrato, a característica anterior não será subscrita.

8\. Após configurar todos os campos, clique em "**Avançar**"**.**

9\. Será apresentada a tela de "**Revisão de itens que serão alterados**".

10\. Nessa tela você poderá rever todas as características, atividades e contratos que você selecionou durante todo o processo de vínculo para averiguar se está de acordo com as suas necessidades. **Note que essa tela é apenas de visualização, não podendo ser alterada nenhuma informação**.

11\. Caso esteja de acordo com as informações, clique em **"Confirmar"**. Aparecerá uma mensagem como **"Deseja confirmar e seguir com as ações em massa?"**, clique em **"Sim, confirmar"** para finalizar o vínculo.

12\. Ao vincular uma atividade a um contrato, o sistema retornará para tela de portfólio.

### Desvinculando

1. Essa opção é para quando você respondeu nas etapas:&#x20;

- ****<font color="#3b9f0f">**Escolha a ação**</font> **- Desvincular;&#x20;**
- ****<font color="#3b9f0f">**O que deseja vincular?**</font>**&#x20;- Contrato;&#x20;**
- ****<font color="#3b9f0f">**No que deseja vincular?**</font>**&#x20;- Atividade**.

2\. O sistema retorna todas os contratos ativos encontradas para o portfólio selecionado. Portfólio ativos são os que estão com status ativo.

3\. Selecione o contrato que deseja desvincular. Para os Contratos, temos as seguintes informações:

- **Nome do contrato &#x20;**
- **Opção de filtrar &#x20;**
- **Cliente &#x20;**
- **Fornecedor &#x20;**
- **Portfólio**, que irá retornar à quantidade de portfólios encontrados no contrato selecionado
- **Visualizar detalhes**
- **Seta de detalhes do contrato**, que ao ser selecionada carrega logo abaixo as seguintes informações do contrato: **Tipo de Acordo/Contrato, Data de Contrato, Horas de Suporte, Moeda, Data Término de Contrato**

4\. Quando selecionados os contratos, aparecerão dois botões:

- Um mostrando a quantidade de contratos que foram selecionadas;
- E outro, **"Comparar contratos selecionados"**, no qual aparecerá um pop-up com as informações dos contratos selecionados.



Depois da lista de Contratos, **é hora de selecionar a&#x20;**<font color="#3b9f0f">**Atividade** </font>**que deseja desvincular**.

1. O sistema apresentará a lista das Atividades encontradas no portfólio selecionado.
2. Selecione a atividade que deseja desvincular. Para as Atividades, temos as seguintes informações:

- **Nome**
- **Opção de filtrar**
- **ID**
- **Portfólio**
- **Serviço**
- **Contratos vinculados**
- **Visualizar detalhes**

3\. Clique em "**Avançar**" para prosseguir.

4\. Será apresentada uma tela sobre **"Características padrões da ação em massa"**. Nessa tela, você preencherá algumas informações, que servirão como características padrão da ação em massa para todos contratos e atividades que você selecionou anteriormente.

5\. Temos os seguintes campos para preencher como característica padrão da ação em massa:

| **Campo**                      |
| ------------------------------ |
| Condições de operação          |
| Data de início                 |
| Calendário                     |
| Tempo de atendimento           |
| Modelo de abertura             |
| Modelo de e-mail de fechamento |
| Grupos executores              |
| Grupo aprovador                |
| Fluxo                          |

6\. Abaixo será apresentado as atividades e os contratos que você selecionou anteriormente para serem desvinculados.

7\. Após configurar todos os campos, clique em "**Avançar**".

8\. Será apresentado a tela de **"Revisão de itens que serão alterados"**.

9\. Nessa tela você poderá rever todas as características, atividades e contratos que você selecionou durante todo o processo de desvínculo para averiguar se está de acordo com suas necessidades. **Note que essa tela é apenas de visualização, não podendo ser alterada nenhuma informação.**

10\. Caso esteja de acordo com as informações, clique em **"Confirmar"**. Será apresentado uma mensagem como **"Deseja confirmar e seguir com as ações em massa?"**, clique e&#x6D;**&#x20;"Sim, confirmar"** para finalizar o desvínculo.

11\. Ao desvincular uma atividade de um contrato, o sistema irá configurar a data fim no vínculo de serviço x contrato.

12\. A atividade não será aposentada e poderá sofrer novo vínculo a qualquer momento com o mesmo contrato ou com outros contratos.

### Exigindo anexo no cadastro de ticket

::File{src="https://archbee-doc-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/Sn6ahC9ouc2RRjgmJN42x_exigindoanexoticket.pdf" label="ExigindoAnexoTicket.pdf" uploadAsPublic="false"}

`Nova opção`**:&#x20;**&#x46;oi adicionada à tela de vínculo de incidente/requisição ao contrato, no portfólio, uma opção para tornar o anexo obrigatório no registro de ticket:

![](https://archbee-image-uploads.s3.amazonaws.com/pu5VMc-2TW3GQX4ly5Xp7/-uIonlI1CW_VnlP-KDxpc_image.png)

Possibilitando ao usuário definir se o anexo é obrigatório para esta atividade, durante o lançamento do ticket nas telas:&#x20;

- Incidente/Requisição;&#x20;
- SmartPortal;&#x20;
- Centro de experiência e nos Webservices:&#x20;
  - **/servicerequestincident/create&#x20;**
  - **/servicerequestincident/save&#x20;**

`Comportamento`**:&#x20;**&#x51;uando o usuário definir que o anexo é obrigatório no portfólio, o sistema automaticamente passa a exigir anexo para abertura de ticket nas funcionalidades, acima mencionadas.


[title] Editar Perfil de Usuário
[path] Configurações Iniciais/Configurações Iniciais/Criar Perfil de Acesso/

Esta funcionalidade tem por objetivo <font color="#3b9f0f">**permitir editar informações da conta de usuário,**</font> possibilitando também a alteração, criação e exclusão de usuários, de forma similar à tela de [Criar Perfil de Acesso](docId:0EcgpTIVVXbyV2cMqKjLb) que podem alterar seus dados de contato, unidade de trabalho e sua foto utilizando a edição de perfil.

:::hint{type="warning"}
⚠️ ***Atenção*****!**

Os dados alterados nesta tela serão modificados também na tela de cadastro do colaborador.

Esta configuração de edição não está disponível para usuários LDAP.
:::

## Antes de Começar

- [x] Para editar o perfil, é necessário estar autenticado.

## Procedimento

1. Na barra de navegação, clique no ícone de usuário;
2. Clique em **"Editar perfil"**;
3. Atualize as informações;
4. Por fim, clique em **"Salvar"**.


[title] Cadastrar a Justificativa de Liberação
[path] 16 Processos/Untitled/

Esta funcionalidade tem por objetivo <font color="#3b9f0f">**registrar a justificativa da liberação**</font>, que será utilizada em outras rotinas do sistema, como por exemplo, na suspensão de uma Liberação.

## Procedimento

1. Acesse a funcionalidade por meio da navegação no menu principal `Processos >
    Gerência de Liberação > Justificativa Requisição Liberação`;
2. Clique no botão **"Novo"** e preencha os campos:

| **Campo**          | **Descrição**                                                                   |
| ------------------ | ------------------------------------------------------------------------------- |
| **Descrição (\*)** | Forneça todos os detalhes da justificativa                                      |
| **Situação (\*)**  | Defina o status da justificativa como Ativo ou Inativo                          |
| **Suspenso (\*)**  | Depois de editar a justificativa, você pode definir se ela está suspensa ou não |

(\*) Informe os campos obrigatórios.

3\. Clique em **"Gravar"**.

4\. Após salvar a liberação, ela aparecerá na lista da tela principal da justificativa de liberação, onde será possível editá-la ou excluí-la.

5\. Nos filtros, podemos procurar uma justificativa. Temos as seguintes opções para filtros:

| **Opção**     | **Descrição**                                    |
| ------------- | ------------------------------------------------ |
| **Descrição** | Pesquise pela descrição da justificação          |
| **Situação**  | Pesquise pelas justificativas ativas ou inativas |


[title] Comparativo de Versões
[path] Sobre o CITSmart/

| **Suporte, Gestão de Processos, Recursos, Integrações e Segurança** | **CITSmart Platform 8** | **CITSmart Platform 9** |
| ------------------------------------------------------------------- | ----------------------- | ----------------------- |
| Aplicação Web                                                       | ✅                       | ✅                       |
| iPhone app                                                          | ✅                       | ✅                       |
| Android app                                                         | ✅                       | ✅                       |
| **Suporte**                                                         | **CITSmart Platform 8** | **CITSmart Platform 9** |
| Telefone                                                            | ✅                       | ✅                       |
| Suporte online                                                      | ✅                       | ✅                       |
| Documentação                                                        | ✅                       | ✅                       |
| Tutoriais em video                                                  | ✅                       | ✅                       |
| **Gerenciamento de Processos**                                      | **CITSmart Platform 8** | **CITSmart Platform 9** |
| Gerenciamento de Portfólio                                          | ✅                       | ✅                       |
| Gerenciamento de Catálogo de Serviço                                | ✅                       | ✅                       |
| Gerenciamento de Nível de Serviço                                   | ✅                       | ✅                       |
| Gerenciamento de Mudança                                            | ✅                       | ✅🔄                     |
| Gerenciamento de Liberação                                          | ✅                       | ✅🔄                     |
| Gerenciamento de Conhecimento                                       | ✅                       | ✅🔄                     |
| Gerenciamento de Configuração e Ativos                              | ✅                       | ✅🔄                     |
| Gerenciamento de Eventos                                            | ✅                       | ✅                       |
| Gerenciamento de Ticket                                             | ✅                       | ✅🔄                     |
| Gerenciamento de Problema                                           | ✅                       | ✅                       |
| Gerenciamento de Continuidade                                       | ✅                       | ✅                       |
| Gerenciamento de Disponibilidade                                    | ✅                       | ✅                       |
| Gerenciamento de Capacidade                                         | ✅                       | ✅                       |
| Gerenciamento de Demanda                                            | ✅                       | ✅                       |
| **Recursos**                                                        | **CITSmart Platform 8** | **CITSmart Platform 9** |
| Simple - Agile Project Management                                   | ❌                       | ⭐                       |
| Gerenciamento de Tarefas com Kanban                                 | ✅                       | ✅                       |
| Centro de Experiência                                               | ❌                       | ⭐                       |
| Alertas/Escalonamento                                               | ✅                       | ✅🔄                     |
| Chat                                                                | ✅                       | ✅🔄                     |
| Portal do Conhecimento                                              | ✅                       | ✅🔄                     |
| Dashboards e Relatórios Personalizados                              | ✅                       | ✅                       |
| Apliacação CITSmart                                                 | ✅                       | ✅🔄                     |
| Mobile e CITSmart GO                                                | ✅                       | ✅🔄                     |
| Gerenciamento de Contrato                                           | ✅                       | ✅                       |
| Gerenciamento de Projeto                                            | ✅                       | ✅                       |
| Gestão de Fluxo de trabalho                                         | ✅                       | ✅🔄                     |
| Construção de Relatórios Dinâmicos                                  | ✅                       | ✅                       |
| Surveys e Feedback                                                  | ✅                       | ✅🔄                     |
| Dashboards                                                          | ✅                       | ✅                       |
| Portal de Serviços                                                  | ✅                       | ✅                       |
| API                                                                 | ✅                       | ✅                       |
| Formulários Customizados                                            | ✅                       | ✅🔄                     |
| Widgets                                                             | ❌                       | ✅                       |
| Anuva Application - AI                                              | ❌                       | ⭐                       |
| Smart Analytics                                                     | ❌                       | ⭐                       |
| **Integrações**                                                     | **CITSmart Platform 8** | **CITSmart Platform 9** |
| Nágios                                                              | ✅                       | ✅                       |
| Zabbix                                                              | ✅                       | ✅                       |
| IBM Watson                                                          | ❌                       | ⭐                       |
| Asterisk                                                            | ✅                       | ✅                       |
| LDAP/AD                                                             | ✅                       | ✅                       |
| Saiku                                                               | ❌                       | ⭐                       |
| E-mail                                                              | ✅                       | ✅                       |
| **Segurança**                                                       | **CITSmart Platform 8** | **CITSmart Platform 9** |
| HTTPS                                                               | ✅                       | ✅                       |

### Legenda

| **Ícone** | **Descrição**       |
| --------- | ------------------- |
| ✅         | Possui              |
| 🔄        | Melhoria            |
| ❌         | Não Possui          |
| ⭐         | Nova Funcionalidade |

## <font color="#3b9f0f">O que há de novo?</font>

### Gerenciamento de Mudança

Nesta versão, o processo de mudança foi renovado, proporcionando um uso mais simples da funcionalidade. É possível gerenciar as fases da mudança de modo compreensível e descomplicado ao concentrá-las numa interface de gestão ágil.

### Gerenciamento de Liberação

Nesta versão, a funcionalidade foi remodelada a fim de possibilitar uma maior facilidade em seu uso, caracterizando-se por uma interação mais intuitiva. Se distingue da versão anterior, ao apresentar uma sequência das fases da Liberação de maneira mais lógica e descomplicada, acrescentando recursos para organizar e aprimorar a gestão de atividades, concentrando em um único local todos os esforços para realizar as mudanças.

### Gerenciamento de Conhecimento

Nesta atualização, o Gerenciamento de Conhecimento foi aprimorado para que o usuário que não possua login e senha também tenha acesso às informações da base de conhecimento, além da pesquisa no Portal do conhecimento ter se tornado mais eficaz com o uso de tags.

### Gerenciamento de Ativos e Configuração

O Gerenciamento de Ativos e Configuração, no que tange ao CMDB, passou por uma reformulação visual do layout, permitindo assim que o usuário tenha um melhor controle de todo o processo de gestão dos itens de configuração.

### Gerenciamento de Ticket

Nesta nova atualização o Gerenciamento de Ticket, além das tarefas já realizáveis na versão anterior, adquiriu um novo layout no cadastro de um serviço, com novos grupos de funcionalidades, trazendo para o usuário maior agilidade.

### Gestão de Projeto Ágil - Simple

A nova ferramenta orientadora de tarefas do CITSmart traz uma ideia de simplificar, em um só lugar, todo o ciclo de vida de uma tarefa/atendimento. Como o próprio nome diz, o ***Simple*** busca agilizar mais ainda o cotidiano de uma organização, com maior e melhor visualização de um processo e controle dos envolvidos.

### Centro de Experiência com o Usuário

Nesta versão, a CITSmart inova ao disponibilizar ao usuário a possibilidade de personalizar, com as características próprias de sua organização, um portal com as informações necessárias ao bom funcionamento da empresa. Isto é feito de forma simples e acessível, permitindo ao cliente uma maior autonomia dentro do sistema.

### Alertas / Escalonamento

A funcionalidade de escalonamento foi redirecionada para dentro da funcionalidade **Requisição e Incidente**, tendo o layout reformulado, trazendo assim maior simplicidade no cadastro de regras de escalonamento e seu gerenciamento.

### Chat

A nova versão, além de passar por uma reformulação, incorporou recursos de inteligência artificial (Anuva) para possibilitar atendimentos automáticos sem necessidade de interação humana.

### Portal do Conhecimento

A versão 8 apresenta um Portal de Conhecimento mais inclusivo e com pesquisas mais eficientes. É possível, doravante, um usuário acessar a funcionalidade sem estar logado no sistema e buscar artigos com filtros mais refinados, tais como as tags (palavras chaves).

### Aplicação CITSmart Neuro

Nesta atualização, a engine de aplicativos Neuro foi aprimorada de modo a possibilitar a geração de diversos recursos, tais como: a criação de formulários complexos, criação de widgets, construção de fluxos avançados, dentre outros.

### Mobile e CITSmart GO

A CITSmart sempre conectada com as necessidades de seus clientes, lança um novo aplicativo chamado **“CITSmart GO”** que permite a gestão de atendimentos realizados por técnicos em campo no modo offline, permitindo que o cliente realize seus trabalhos de forma ininterrupta.

### Gestão de fluxo de trabalho

Nesta versão, foram implementadas diversas funcionalidades que possibilitam a criação e manutenção de fluxos mais rápida e versátil. Além disso, agora é possível importar fluxos BPMN e utilizar subprocessos.

### Surveys e Feedback

Agora é possível criar questionários e aplicar em diferentes cenários (pesquisas internas e externas) e também na avaliação de serviços.

### Formulários customizados

A Funcionalidade foi totalmente remodelada, o que possibilita a criação de formulários rapidamente.

### Anuva Application | Inteligência Artificial

Foi desenvolvida para realizar a análise de dados a partir de inteligência cognitiva, de modo a otimizar a gestão de processos como Gestão de Ticket, Gestão de Mudança e Gestão de Conhecimento.

### Smart Analytics

Permite integração com a ferramenta **Saiku** o que possibilita análises fantásticas nos dados do CITSmart **Experience** permitindo a criação de dashboards, painéis e relatórios.

### IBM Watson

Integração com a solução **IBM Watson** o que permite o uso de inteligência cognitiva nos fluxos de trabalho do CITSmart.

### LDAP/AD

Esta funcionalidade foi aprimorada possibilitando a coleta, por meio de atributos, de diversas informações disponibilizadas no diretório ativo.

### Integração com Saiku

Integração do ***Saiku*** com o CITSmart **Analytics**.


[title] Exibir e Pesquisar pelas Tags no Portal do Conhecimento
[path] 16 Processos/Untitled/

**Tags são palavras-chave (relevantes) ou termos associados a uma informação**, tópico ou discussão na qual se deseja indexar, de forma explícita, no sistema, a fim de facilitar a pesquisa de conteúdo desejados.

Este documento tem por objetivo<font color="#3b9f0f"> **informar como criar e pesquisar conhecimentos pelo o uso de tags**</font>.

## Antes de Começar

- [x] É necessário observar se o **SOLR** está configurado corretamente.

## Procedimento

1. Acesse a funcionalidade por meio do menu `Sistema > Configurações > Portal do Conhecimento > Configurações de Filtro do Portal do Conhecimento`;
2. Será necessário disponibilizar que o filtro do<font color="#3b9f0f"> **Portal do conhecimento** </font>seja realizado por tags, podendo também ordenar qual posição de importância a tag terá no fornecimento dos resultados de pesquisa;
3. Para criar uma tag e vinculá-la a um conhecimento, é necessário acessar a funcionalidade pelo menu `Processos > Gerência de Conhecimento > Gerenciamento de Conhecimento` e, em seguida, ao cadastrar o conhecimento, definir e registrar as tags no campo **"Tags"** para auxiliar no sucesso da busca deste artigo;

:::hint{type="warning"}
⚠ ***Atenção*****!** &#x20;

Todos os conhecimentos cadastrados que possuem as mesmas tags serão expostos na mesma pesquisa.
:::

4\. Para pesquisar conhecimentos por suas tags, basta acessar o <font color="#3b9f0f">**Portal de Conhecimento**</font> e pesquisar o artigo pela palavra chave que expresse o conceito daquilo que pretende encontrar. O sistema informará os documentos que tenham registrado a tag procurada.


[title] A Área de Trabalho da Gerência de Liberação
[path] 16 Processos/Untitled/

A <font color="#3b9f0f">**Área de trabalho da Gestão de Liberação**</font> é um espaço onde estão disponibilizadas todas as liberações e seu histórico de atendimento, tornando mais fácil a visualização de cada item e suas funcionalidades.&#x20;

Neste espaço também há a possibilidade de inúmeras ações como a <font color="#3b9f0f">**edição, a suspensão, alterar um ítem, além de diversas outras**</font> <font color="#3b9f0f">**possibilidades.**</font>****

## Antes de Começar

A visualização de uma Liberação, bem como a execução de ações de
&#x20;atendimento, depende das permissões definidas para um usuário ou grupo de
&#x20;trabalho. Diante disso:

- [x] Verifique se você possui permissão para ver/executar uma ou mais
  &#x20;Liberações.

## Procedimento

1. Acesse a funcionalidade de Gerenciamento de Liberação navegando pelo menu
   &#x20;`Processos > Gerência de Liberação > Liberação`;
2. Busque pela liberação e ações desejadas.


[title] Relacionar Informações à Liberação
[path] 16 Processos/Untitled/

É possível <font color="#3b9f0f">**vincular à Liberação uma série de informações**</font>, tais como: **mudança, projeto, IC dentre outros**, no intuito de solidificar e embasar a execução do processo.

## Antes de Começar

O vínculo de informações poderá ocorrer em todo o ciclo de vida da Liberação. Dessa forma, poderá ser utilizada a qualquer momento, caso necessário.
&#x20;

- [x] No entanto, é necessário ter acesso a uma Liberação.

## Procedimento

1. Acesse a funcionalidade por meio do menu principal `Processos > Gerência de
    Liberação > Liberação`;
2. Para informar os dados complementares da liberação, marque a
   &#x20;opção de captura ou visualização da requisição;
3. Para visualizar informações sobre campos específicos, clique nas
   &#x20;guias:<font color="#3b9f0f"> **Solicitante**, **Liberação**</font> e <font color="#3b9f0f">**Fechamento**</font>;
4. Para vincular **Mudanças**, clique na área de mesmo nome e, em seguida,
   &#x20;aperte sobre o campo de pesquisa e selecione a mudança desejada. Caso deseje cadastrar uma nova mudança utilizando a liberação a ser criada como
   &#x20;parâmetro, basta clicar no botão **"Cadastrar Mudança"** e preencher os dados
   &#x20;necessários;

:::hint{type="success"}
✅ ***Regra*****:&#x20;**&#x4F; sistema só permitirá o vínculo de Mudanças a Liberação caso se esta estiver com o status diferente de "**Registrada**" e "**Cancelada**".
:::

5\. Para vincular **Mídia Definitiva**, clique na área de mesmo nome e, em
&#x20;seguida, sobre o campo de pesquisa e selecione a mídia desejada. Se
&#x20;desejar cadastrar uma nova mídia, clique no botão **"Cadastrar"** e preencha os
&#x20;dados;

6\. Para vincular **Questionários**, clique na área de mesmo nome e escolha o
&#x20;tipo de questionário a ser vinculado. Depois, aperte no botão **"Gravar"** para
&#x20;efetuar a operação;

7\. Para vincular **Problemas**, clique na área de mesmo nome e, em seguida,
&#x20;sobre o campo de pesquisa e selecione o problema desejado. Se
&#x20;desejar cadastrar um problema, basta clicar no botã&#x6F;**&#x20;"Cadastrar"** e preencher
&#x20;os dados necessários;

8\. Para vincular um **Conhecimento**, clique na área de mesmo nome e, em
&#x20;seguida, sobre o campo de pesquisa e selecione o conhecimento
&#x20;desejado. Se desejar cadastrar um novo artigo, clique no botã&#x6F;**&#x20;"Cadastrar"** e
&#x20;preencha os dados;

9\. Para vincular um **Ticket**, clique na área de mesmo nome e,
&#x20;em seguida, sobre o campo de pesquisa e selecione o ticket
&#x20;desejado. Lembrando que serão expostos todos os tickets já cadastrados,
&#x20;sendo necessário, portanto, selecionar o ticket cadastrado
&#x20;anteriormente.

10\. Clique no botão de opções e, em seguida, em **"Gravar"** para concluir a operação.


[title] Funil de Serviços
[path] 16 Processos/Portfólio e Catálogo/

O funil de serviços faz parte do **Gerenciamento de portfólio**, que contém referências a serviços que ainda não estão ativos.&#x20;

Além disso, na plataforma, a mesma página apresenta o pipeline e os serviços que estão sendo criados no catálogo de serviços e na parte de serviços obsoletos.

## Antes de Começar

- [x] &#x20;Ter cadastrado o portfólio de serviço;
- [x] &#x20;Ter criado a categoria de serviço;
- [x] &#x20;Ter criado grupo(s) que serão usados no serviço;
- [x] &#x20;Ter permissão para acessar a funcionalidade de Gerenciamento de Portfólio.

## Procedimento

1. Acesse o menu principal `Processos > Gerência de Portfólio e Catálogo > Portfólio`;
2. Localize o portfólio desejado e clique e&#x6D;**&#x20;"Avançar"**;
3. Aparecerão três guias:<font color="#3b9f0f"> **Funil de Serviços**</font>, <font color="#3b9f0f">**Catálogo de Serviços**</font> e <font color="#3b9f0f">**Serviços Obsoletos**</font>;

### Desenhando um Serviço

Na guia<font color="#3b9f0f"> **Funil de serviços**</font>, apresenta a fase de desenho do serviço, mostrando os serviços que ainda não estão em produção. Temos as seguintes ações disponíveis:

| **Ação**         | **Descrição**                                                                                                                                                                 |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Novo serviço** | Para começar a criar um serviço para o Portfólio de Serviços. Para os campos a serem preenchidos, consulte o documento [Cadastrar um Serviço](docId\:YRm-Cj99MfCMxnO1yoh1U).  |
| **Nome serviço** | Para ordenar a lista de serviços do funil por nome                                                                                                                            |
| **ASC**          | Para ordenar a lista de serviços de forma crescente ou decrescente                                                                                                            |

:::hint{type="success"}
✅ ***Regra*****:** O serviço somente avançará para a fase do catálogo de serviços quando sua Fase de serviço estiver definida como **"Termo de Abertura"** e o Status do serviço como **"Produção"**.
:::

Ainda na guia de <font color="#3b9f0f">**Funil de Serviços**</font>, se você deseja verificar as informações de um serviço que ainda não está ativo, poderá escolher um da lista disponível. Para esses serviços, temos as seguintes ações:

| **Ação**    | **Descrição**                                                                                                                                                             |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Editar**  | Para editar todas as informações para a criação de um serviço                                                                                                             |
| **Avançar** | Para detalhar todas as informações sobre o serviço. Para os campos disponíveis na ação prévia, consulte o documento [Cadastrar um Serviço](docId\:YRm-Cj99MfCMxnO1yoh1U). |

### Catálogo de Serviços

A próxima guia é o <font color="#3b9f0f">**Catálogo de Serviços**</font>, onde temos os serviços que já estão ativos e em produção. Para a lista de serviços disponíveis, temos as mesmas ações que no funil de serviço:

| **Ação**    | **Descrição**                                                                                                                                                             |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Editar**  | Para editar todas as informações para a criação de um serviço                                                                                                             |
| **Avançar** | Para detalhar todas as informações sobre o serviço. Para os campos disponíveis na ação prévia, consulte o documento [Cadastrar um Serviço](docId\:YRm-Cj99MfCMxnO1yoh1U). |

### Serviços Obsoletos

Por fim, a guia de <font color="#3b9f0f">**Serviços obsoleto**</font>****<font color="#3b9f0f">**s**</font> apresenta os serviços que estão aposentados e os que estão fora de operação.

Nesta parte do portfólio de serviços, são registrados aqueles que não estão mais em operação. É utilizado para manter um histórico de serviços.&#x20;

Como nas outras guias, teremos a lista de serviços obsoletos e as seguintes ações:

| **Ação**    | **Descrição**                                                                                                                                                             |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Editar**  | Para editar todas as informações para a criação de um serviço                                                                                                             |
| **Avançar** | Para detalhar todas as informações sobre o serviço. Para os campos disponíveis na ação prévia, consulte o documento [Cadastrar um Serviço](docId\:YRm-Cj99MfCMxnO1yoh1U). |


[title] FAQ CITSmart
[path] Sobre o CITSmart/


[title] Cadastrar Processo de Negócio
[path] 16 Processos/Portfólio e Catálogo/

O Processo de Negócio irá contribuir para a entrega de um produto ou serviço aos
&#x20;clientes.&#x20;

**Por exemplo:** um comerciante pode ter um processo de compra que o ajude
&#x20;a entregar serviços a seus clientes. Muitos processos de negócio dependem de
&#x20;serviços de TI.

Esta funcionalidade disponibiliza ações diversas, tais como: <font color="#3b9f0f">**incluir, alterar e
 excluir um processo de negócio**</font>.

## Antes de Começar

Para cadastrar um processo de negócio, é necessário:

- [x] Registrar anteriormente o
  &#x20;cliente, o grupo, a unidade e ter fluxos de trabalho definidos.

## Procedimento

1. Acesse a funcionalidade por meio da navegação no menu principal `Processos >
    Gerência de Portfólio e Catálogo > Processo de Negócio`;
2. Preencha os campos disponibilizados;
3. Clique e&#x6D;**&#x20;"Gravar"**.


[title] Criar Portfólio
[path] 16 Processos/Portfólio e Catálogo/

O <font color="#3b9f0f">**Gerenciamento de Portfólio e do Catálogo de Serviços**</font> apresenta e considera os serviços que estão simultaneamente ativos, em termos de geração de valor para o negócio, e isso garante  a composição correta de serviços, com a finalidade de atender aos resultados esperados pela empresa ou instituição, aplicando o nível adequado de investimento em cada serviço.


O **Portfólio é um conjunto completo de serviços que serão entregues**, agrupados por critérios como tamanho, disciplina ou valor estratégico. Assim, todos os serviços entregues pela empresa deverão compor o Portfólio.


O gerenciamento de portfólio é estratégico, pois gerencia os serviços ao longo de seu ciclo de vida no [Funil](/pt-br/citsmart-platform-9/processes/portfolio-and-catalog/use/pipeline.html), focando no valor que eles entregam para a área de negócios. Esse recurso fornece uma variedade de ações, como: <font color="#3b9f0f">**incluir, alterar e excluir um portfólio**</font>.

## Antes de Começar

- [x] É necessário ter definida a permissão de acesso às funcionalidades do Gerenciamento de Portfólio.&#x20;
- [x] O portfólio permite vínculo com pesquisas que precisam estar cadastradas
  &#x20;previamente.
- [x] Setar o **parâmetro 293&#x20;**&#x63;omo "**YES**" para ativar a permissão de acesso para grupos de usuários no Portal.

## Procedimento

1. Acesse a funcionalidade pelo menu principal `Processos > Gerência de
    Portfólio e Catálogo > Portfólio`;
2. Clique em **"Novo Portfólio"**;
3. Na aba <font color="#3b9f0f">**Principal**</font>, defina o nome do portfólio e se ele será do tip&#x6F;**&#x20;"Negócio"** ou **"Apoio"**;
4. Informe os dados do Portfólio;
5. Preencha os dados de acordo com o formato que será definido;
6. Grave o portfólio.

**Ação para editar ou cadastrar**

| **Ação**           | **Descrição**                              |
| ------------------ | ------------------------------------------ |
| **Novo Portfólio** | Criar novo                                 |
| **Editar**         | Editar o portfólio                         |
| **Avançar**        | Cadastrar/Editar Serviços para o Portfólio |

:::hint{type="success"}
✅ ***Regra*****:** A escolha do tipo ***Negócio/Apoio*** deve estar alinhada com o tipo de contrato a ser vinculado ao portfólio, pois apenas os contratos do tip&#x6F;**"Contrato"&#x20;**&#x66;icarão vinculados ao tipo ***"Negócio"*** e apenas os contratos do tipo **"Contrato Apoio"** e **"Contrato de Nível Operacional"&#x20;**&#x66;icarão vinculados ao tipo ***"Apoio"***.
:::

## Cadastrar Portfólio

Informação de cada guia:

| **Guias**         | **Descrição**                                            |
| ----------------- | -------------------------------------------------------- |
| **Principal**     | Informação básica do portfólio.                          |
| **Apresentação**  | Visualização no Smart Portal e Gerência de Ticket.       |
| **Multi-idiomas** | Tradução do portfólio para inglês, espanhol e português. |

### Guia Principal

- Informações básicas do portfólio.

| **Campo**              | **Descrição**                                                                                |
| ---------------------- | -------------------------------------------------------------------------------------------- |
| **Nome portfólio(\*)** | Nome do portfólio                                                                            |
| **Tipo (\*)**          | Serão fornecidos pelo sistema, de acordo com cada tipo de portfólio mostrado (negócio/apoio) |
| **Multi-idioma**       | Definir se o portfólio é multi-idioma (sim/não)                                              |

(\*) Indica campos obrigatórios.

### Guia de Apresentação

- Configura a visualização no<font color="#3b9f0f"> **Smart Portal**</font> e na **Gerência de Ticket**.

| **Campo**                     | **Descrição**                                                                    |
| ----------------------------- | -------------------------------------------------------------------------------- |
| **Disponível no portal (\*)** | Indicar se o Portfólio deverá estar presente n&#x6F;**&#x20;Portal de Serviços** |
| **Disponível via chat (\*)**  | Indicar se o portfólio poderá ter atendimento em chat                            |
| **Nome (\*)**                 | Nome do portfólio a ser exibido no portal                                        |
| **Descrição**                 | Descrição do portfólio a ser exibido no portal                                   |
| **Selecione uma imagem**      | Selecione uma imagem para o portfólio (ou faça o upload de uma nova)             |

(\*) Indica campos obrigatórios.

:::hint{type="info"}
**🖊&#x20;*****Nota*****:** Na opção **"Disponível via chat"**, mesmo se marcado com&#x6F;**&#x20;"Sim"**, para usar o chat, ainda será preciso combinar com a permissão de grupo (para participar do portfólio no chat).&#x20;
:::

### Guia de Multi-idiomas

- Tradução de serviços para inglês, espanhol e português.
- Essa guia será exibida apenas se **"Multi-idiomas"** estiver definido como **"Sim"** na <font color="#3b9f0f">**Guia principal**</font>.

**Para cada idioma, forneça:**

- Nome do portfólio;
- Descrição;

:::hint{type="success"}
**✅&#x20;*****Regra*****:&#x20;**&#x43;aso uma das 3 línguas na aba **"Multi-idiomas"** fique em branco, os campos desta serão preenchidas com as informações que estiverem contidas na aba intitulada como **"Apresentação"**.
:::

## O que Fazer a Seguir

Depois do portfólio criado, é possível criar serviços para serem solicitados. Esse passo a passo pode ser conferido no conhecimento [Cadastrar um Serviço](docId\:YRm-Cj99MfCMxnO1yoh1U).


[title] Cadastrar Menu
[path] Configurações Iniciais/Configurações Iniciais/Untitled/

Esta funcionalidade tem por <font color="#3b9f0f">**objetivo permitir ao usuário a configuração dos itens de menu**</font>, de acordo com as suas preferências, disponibilizando ações diversas, como: incluir, alterar e excluir um menu.

Provê melhor usabilidade no acesso aos menus, onde os itens poderão ser organizados conforme a sua necessidade.

## Procedimento

1. Acesse a funcionalidade por meio da navegação no menu principal `Cadastros Gerais > Menu`;
2. Preencha os campos disponibilizados;
3. O botão **"Gerar XML"** serve para gerar um arquivo dos menus no formato ".xml";
4. O botã&#x6F;**&#x20;"Atualizar Menus"&#x20;**&#x73;erve para atualizá-los;
5. Ter muito cuidado em relação à execução do botão **"Atualizar Menus"**, pois todas as alterações cadastrais dos menus serão perdidas desde a última vez que houve a geração de XML. Recomenda-se, portanto, a seguinte sequência de execução:
   - ****<font color="#3b9f0f">**1.**</font> botão "**Gerar XML**";
   - <font color="#3b9f0f">**2.** </font>botão "**Atualizar Menus**".
6. Por fim, clique em **"Gravar"**.

## O que Fazer a Seguir

Acesse o menu principal para verificar se o(s) menu(s) foram criado(s).




[title] Release Notes
[path] Sobre o CITSmart/


[title] Cadastrar Prioridade de Solicitações de Serviço
[path] 16 Processos/Portfólio e Catálogo/

A funcionalidade de prioridade de solicitações de serviço **permite definir a
&#x20;matriz de prioridade** com a finalidade de calcular o tempo de atendimento (SLA) da solicitação
&#x20;de serviço de forma dinâmica.

Essa prioridade será usada para identificar a importância
&#x20;relativa à solicitação de serviço e para identificar os tempos requeridos para
&#x20;que ações adequadas possam ser tomadas.

Esta ferramenta disponibiliza ações diversas, tais como: <font color="#3b9f0f">**incluir, alterar e
 excluir a prioridade de solicitações de serviço**</font>.

## Antes de Começar

Para cadastrar uma prioridade de solicitação de serviço é preciso:

- [x] Configurar o
  &#x20;**parâmetro 104** com valo&#x72;**&#x20;"S"**.

## Procedimento

1. Acesse a funcionalidade por meio da navegação no menu principal `Processos >
    Gerência de Portfólio e Catálogo > Prioridade Solicitações Serviço`;
2. Preencha os campos disponibilizados quanto ao **Impacto**, clique em **"Gravar
   &#x20;Impacto"**;
3. Preencha os campos disponibilizados quanto a **Urgência**, clique em **"Gravar
   &#x20;Urgência"**;
4. Preencha os campos disponibilizados quanto a **Matriz de prioridade**, clique e&#x6D;**&#x20;"Gravar Matriz de Prioridade"**.

:::hint{type="success"}
**✅&#x20;*****Regra*****:&#x20;**&#x41;pós o registro da matriz de prioridade, quando for registrada uma solicitação de serviço, o tempo de atendimento (SLA) será estabelecido de acordo com os níveis de impacto e de urgência informados, sendo considerada a matriz de prioridade.&#x20;

Lembrando que para isso ocorrer o parâmetro deve estar **habilitado**.
:::


[title] Pesquisa Avançada de Liberações Encerradas
[path] 16 Processos/Untitled/

Esta funcionalidade permite <font color="#3b9f0f">**realizar a busca de requisições de liberação**</font>, de acordo com os filtros definidos.

## Procedimento

1. Acesse a funcionalidade pela navegação no menu principal `Processos >
    Gerência de Liberação > Liberação`;
2. Clique no ícone simbolizado por uma seta para baixo, disponível ao lado
   &#x20;direito da tela, dentro do campo de pesquisa;
3. Aperte o botão "**Pesquisa avançada**";
4. Preencha os filtros e clique em "**Pesquisa avançada**";
5. Para gerar o relatório das liberações em formato PDF, clique no
   &#x20;botão "**Gerar PDF**" e para gerar o relatório em formato Excel, clique no botão
   &#x20;"**Gerar XLS**";
6. Ao lado de cada registro de liberação da lista, haverá ícones para
   &#x20;consulta de histórico, reabertura da liberação e visualização
   &#x20;de anexos.


[title] Aprovar uma Mudança
[path] 16 Processos/Mudança/

Esta funcionalidade permite ao <font color="#3b9f0f">**Comitê Consultivo de Mudanças aprovar ou rejeitar a mudança**</font>. Somente os membros do “**Comitê Consultivo de Mudança**" **(CCM)** podem realizar essa aprovação, baseada nas informações adicionadas na RDM como IC's, datas planejadas indicando conflitos, etc.&#x20;

Para aprovar uma mudança, deve se atentar na configuração do **parâmetro 303&#x20;**"**Votação da RDM utilizando a regra da maioria absoluta (50% + 1) (Valores: “S” ou “N”, Default: “S”**), onde o valor **“S”&#x20;**&#x64;efine a aprovação da mudança quando há **mais de 50% de aprovação do CCM** e o valor **“N”&#x20;**&#x64;efine a aprovação da mudança quando há **100% de aprovação do CCM**.

## Antes de Começar

Para aprovar ou não uma mudança, é necessário definir:

- [x] Que o grupo ao qual o
  &#x20;usuário está cadastrado terá o valor igual a ‘**SIM**’ para Comitê Consultivo de
  &#x20;Mudanças.
- [x] Também é essencial que os tipos de fluxo não emergencial nem padrão (Normal) e
  &#x20;as **“permissões nos fluxos de trabalho”** do grupo ao qual o usuário faz parte
  &#x20;estejam ativadas.

## Procedimento

1. Acesse a funcionalidade pela navegação no menu principal `Processos >
    Gerência de Mudança > Mudança`;
2. Clique no primeiro ícone, na esquerda da tela (localizada ao lado da palavra
   &#x20;**“Mudança”**) e, em seguida, em **“Requisições para votação”**;
3. Clique sobre a mudança desejada. Para visualizar a mesma, aperte no ícone de
   &#x20;mesmo nome;
4. Para registrar a aprovação ou rejeição, clique no ícone **“Votação”** e
   &#x20;selecione a opção mais adequada ao seu cenário e discorra sobre as informações
   &#x20;essenciais;
5. Por fim, clique em **“Gravar”&#x20;**&#x70;ara efetuar a operação.


[title] Cadastrar um Usuário
[path] Configurações Iniciais/Configurações Iniciais/Untitled/

Alguns colaboradores precisam acessar o sistema e, nesse caso, é necessário <font color="#3b9f0f">**criar uma conta de usuário**</font>. Essa conta permitirá o acesso do colaborador através de um login, uma senha e um perfil de acesso que consolida os seus direitos e permissões no sistema.

Note que o colaborador precisa estar cadastrado anteriormente, o que torna este procedimento simplificado.

A manutenção do cadastro do usuário envolve a inclusão, alteração e exclusão. Em particular, o administrador do sistema pode alterar o login e a senha de um colaborador.

Além disso, esta funcionalidade disponibiliza ações diversas, como: incluir, alterar e excluir um usuário.

:::hint{type="warning"}
📌 ***IMPORTANTE*****!&#x20;**

O envio de login e senha, ao cadastrar um novo usuário, não engloba usuários importados via AD ou LDAP.
:::

## Antes de Começar

Para cadastrar um usuário, é necessário:

- [x] Registrar o Colaborador;
- [x] Possuir no mínimo um Perfil de Acesso;



Para enviar o Login e a Senha do usuário para o e-mail do Colaborador:

- [x] Configure o **parâmetro 33** e indique corretamente a URL da instância;
- [x] Configure o **parâmetro 455** com o ID do modelo de e-mail criado para enviar os dados de acesso;

:::hint{type="success"}
✅ ***Regra*****:&#x20;**&#x4E;o template de e-mail, deverão constar as chaves $\{LOGIN} e $\{NOVASENHA}.
:::

:::BlockQuote
***Exemplo Modelo básico***: "Prezado usuário, seguem dados de acesso. Usuário: $\{LOGIN} e Senha: $\{NOVASENHA}"
:::

## Procedimento

1. Acesse a funcionalidade por meio da navegação no menu principal `Cadastros Gerais > Gerência de Pessoal > Usuário`;
2. Preencha os campos disponibilizados;
3. Clique em **"Gravar"**.

:::hint{type="success"}
✅ ***Regra*****:** O sistema verifica se existe um template de e-mail para novo colaborador que possua a chave de senha para envio via e-mail. Então, o administrador do sistema cadastra ou altera um login e senha de um colaborador na tela de usuário. Depois disso, é verificada a utilização da política de senha e se usuário é LDAP ou não. Por fim, o sistema permite a entrada de uma nova senha. Ao gravar, serão enviados por e-mail os novos dados para o colaborador.
:::


[title] Plano de Melhoria
[path] 16 Processos/Nível de Serviço/

Segundo a ITIL, um <font color="#3b9f0f">**Plano de Melhoria de Serviço**</font>**&#x20;(**<font color="#3b9f0f">**PMS**</font>**)** ou, em inglês, <font color="#3b9f0f">*Service Improvement Plan (SIP*)</font>, é um plano formal para implementar melhorias em um processo ou serviço de TI, cadastrando a necessidade ou oportunidade identificada.


Nesta função, é possível **cadastrar todos os benefícios esperados com a melhoria e gerar relatórios** também, possibilitando sua impressão.


Esta funcionalidade disponibiliza ainda ações diversas, tais como: <font color="#3b9f0f">**incluir, alterar e excluir um plano de melhoria**</font>.

## Antes de Começar

Para definir um plano de melhoria, é necessário:&#x20;

- [x] Ter cadastrado previamente o fornecedor e o contrato.

## Procedimento

1. Acesse a funcionalidade pela navegação no menu principal `Processos >
    Gerência de Nível de Serviço > Plano Melhoria`;
2. Defina o Plano de Melhoria e clique na guia desejada (<font color="#3b9f0f">**Pesquisar/Cadastrar**</font>);

| **Função**    | **Descrição**                       |
| ------------- | ----------------------------------- |
| **Gravar**    | Salvar o novo plano de melhoria     |
| **Limpar**    | Limpar todos campos do formulário   |
| **Pesquisar** | Pesquisar por planos de melhoria    |
| **Excluir**   | Excluir o plano de melhoria editado |

## Pesquisar

3\. Selecione o plano de melhoria para pesquisar:

| **Campo** | **Descrição**                                      |
| --------- | -------------------------------------------------- |
| Título    | Pesquisar pelo título                              |
| Grid      | Grid com a lista de planos de melhoria pesquisados |

## Cadastrar/Editar

4\. Preencha os campos para criar o plano de melhoria:

| **Campo**            | **Descrição**                                                                             |
| -------------------- | ----------------------------------------------------------------------------------------- |
| **Título (\*)**      | Defina um título para o plano de melhoria                                                 |
| **Fornecedor**       | Defina o fornecedor do plano de melhoria                                                  |
| **Contrato**         | Defina um contrato para o plano de melhoria                                               |
| **Data início (\*)** | Defina dia para começar a usar o plano de melhoria                                        |
| **Data fim (\*)**    | Defina dia para parar de usar o plano de melhoria                                         |
| **Situação**         | Defina os status do plano de melhoria entre: "Em desenvolvimento", "Ativo" ou "Cancelado" |
| **Objetivo**         | Defina um objetivo para o plano de melhoria                                               |
| **Visão geral**      | Descreva a visão geral deste plano de melhoria                                            |
| **Escopo**           | Descreva o escopo deste plano de melhoria                                                 |
| **Visão**            | Descreva a visão deste plano de melhoria                                                  |
| **Missão**           | Descreva a missão deste plano de melhoria                                                 |
| **Notas**            | Descreva as notas para este plano de melhoria                                             |

5\. Clique em **"Gravar"**;

6\. Ao pesquisar um plano de melhoria, é possível editar as informações registradas anteriormente e adicionar novos recursos, que só podem ser criados após a criação de um plano de melhoria, que serão detalhados nas sessões a seguir:

### Objetivos

7\. Ao clicar em **"Cadastrar Objetivo"**, preencha os campos disponíveis:

| **Campo**               | **Descrição**                                                                                                                                                                                                     |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Objetivo (\*)**       | Defina o título do objetivo                                                                                                                                                                                       |
| **Medição**             | Defina a medição para monitorar                                                                                                                                                                                   |
| **Detalhamento**        | Detalhe os objetivos                                                                                                                                                                                              |
| **Resultado esperado**  | Escreva os resultados esperados no objetivo                                                                                                                                                                       |
| **Tipo de responsável** | Selecione o tipo de responsável entre: "usuário" ou "grupo"                                                                                                                                                       |
| **Responsável**         | Pesquise usando um "usuário" ou "grupo", dependendo do que foi selecionado no campo Tipo de atribuição, use um "nome", "Número do registro de contribuinte" e a situação: "Ativo", "Inativo" ou "todos os status" |

Depois de criar um objetivo, você pode:**&#x20;"Editar", "Excluir"** e **"Selecionar"**.

### Ações

8\. Ao clicar em **"Cadastrar Ação"**, preencha os campos disponíveis:

| **Campo**               | **Descrição**                                                                                                                                                                                                     |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Objetivo (\*)**       | Defina o título da ação                                                                                                                                                                                           |
| **Medição**             | Defina a medição para monitorar                                                                                                                                                                                   |
| **Detalhamento**        | Detalhe a ação                                                                                                                                                                                                    |
| **Resultado esperado**  | Escreva os resultados esperados da ação                                                                                                                                                                           |
| **Tipo de responsável** | Selecione o tipo de responsável entre: "usuário" ou "grupo"                                                                                                                                                       |
| **Responsável**         | Pesquise usando um "usuário" ou "grupo", dependendo do que foi selecionado no campo Tipo de atribuição, use um "nome", "Número do registro de contribuinte" e a situação: "Ativo", "Inativo" ou "todos os status" |

Depois de criar uma ação, você pode:**&#x20;"Editar"**, **"Excluir"** e **"Selecionar"**.

### Monitoramento

| **Campo**                         | **Descrição**                                                                                                                                                                                                     |
| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Título (\*)**                   | Defina um título para o monitoramento                                                                                                                                                                             |
| **Fator crítico de sucesso (\*)** | Adicione um fator crítico de sucesso para alcançar sua meta                                                                                                                                                       |
| **Tipo de responsável**           | Selecione o tipo de responsável entre: "usuário" ou "grupo"                                                                                                                                                       |
| **Responsável**                   | Pesquise usando um "usuário" ou "grupo", dependendo do que foi selecionado no campo Tipo de atribuição, use um "nome", "Número do registro de contribuinte" e a situação: "Ativo", "Inativo" ou "todos os status" |
| **Métrica**                       | Defina a métrica do monitoramento                                                                                                                                                                                 |
| **Medição**                       | Defina a medição do monitoramento                                                                                                                                                                                 |
| **Relatórios**                    | Defina o relatório do monitoramento                                                                                                                                                                               |
| **KPI (\*)**                      | Defina um título para KPI e selecione **"importar"** para adicionar                                                                                                                                               |

Depois de criar um monitoramento, você pode: **"Editar", "Excluir"** e **"Selecionar"**.

9\. Para criar um relatório, clique em **"Gerar relatório"&#x20;**&#x65; abrirá outra página, gerando o relatório desejado.

10\. Clique e&#x6D;**&#x20;"Gravar"**.


[title] Suspender a Liberação
[path] 16 Processos/Untitled/

Esta funcionalidade permite <font color="#3b9f0f">**suspender a execução da liberação**</font>.

## Antes de Começar

Para suspender a execução da liberação, é necessário:

- [x] O cadastro
  &#x20;prévio da mesma, da justificativa de liberação e permissão para
  &#x20;suspensão.

## Procedimento 

1. Acesse a funcionalidade por meio da navegação no menu principal `Processos >
    Gerência de Liberação > Liberação`;
2. Localize a liberação a suspender, clique sobre a mesma e, em
   &#x20;seguida, no botã&#x6F;**&#xA0;**"**Mais Opções**". Selecione a opção "**Suspender**";
3. Preencha a justificativa de suspensão e o complemento desta justificativa;
4. Clique no botão "**Gravar**" para efetuar a operação;

## O que Fazer a Seguir

Verifique se a situação da liberação desejada se encontra como "**Suspensa** na lista de itens de liberação.


[title] Refinar Pesquisas no Portal de Conhecimento
[path] 16 Processos/Untitled/

Este conhecimento tem por objetivo **orientar e sugerir as melhores maneiras de se realizar buscas dentro do** <font color="#3b9f0f">**Portal do Conhecimento**</font>.

1. ****<font color="#3b9f0f">**Conectores entre termos (operador lógico booleano):**</font>****
   - **AND (+):** é possível realizar a busca com mais de uma palavra, priorizando uma delas no resultado. Acrescente o sinal positivo **"+"&#x20;**&#x6E;a frente da palavra que será priorizada. Exemplo: **ticket +delegar**;
   - **NOT (-):** é possível refinar (reduzir) o resultado incluindo palavras a serem retiradas da lista resultante. Exemplo:**&#x20;Requisição -Incidente**
2. ****<font color="#3b9f0f">**Variar a forma de escrever a palavra, exemplo:**</font>****
   - **Requisitar**
   - **Requisição**
   - É possível pesquisar por uma parte da palavra: **Requisi**
3. ****<font color="#3b9f0f">**Utilizar sinônimos:**</font>****
   - **Buscar**
   - **Pesquisar**
4. ****<font color="#3b9f0f">**Pesquisar por frase exata:**</font>****
   - Colocar a frase desejada entre aspas duplas.&#x20;
   - Exemplo:**&#x20;"Como delegar um ticket"**
5. ****<font color="#3b9f0f">**Navegar pelas pastas e clicar na pasta do assunto desejado.**</font>****


[title] Untitled
[path] /


[title] Painel Inicial
[path] Configurações Iniciais/Configurações Iniciais/

O painel inicial é exibido na tela principal do sistema. Neste painel, será possível adicionar *dashboards* a partir de um template ou selecionando manualmente.&#x20;

Nesta área, também estarão disponíveis recursos para criação de atalhos (links), visualização de relatórios e *dashboads*. Contém informações relevantes.

- Alterar Informações da conta;
- Criar atalhos;
- Criar sua *dashboad;*
- Adicionar widgets a sua dashboard.


[title] Configurar Atributos do Contrato do Serviço
[path] 16 Processos/Portfólio e Catálogo/

O módulo de **Gestão de Porfólio** permite o <font color="#3b9f0f">**gerenciamento flexível de serviços**</font>. Dessa forma, é possível vincular um ou mais contratos a um serviço específico (multicontrato). Essa é a função utilizada para incluir os dados de SLA e permissões de Grupo aos serviços.

Esta característica possibilita o atendimento de diversos requisitos para um mesmo serviço, sendo possível ter um mesmo serviço com diferentes fluxos de atendimento, SLAs, condições de operação, etc.

## Antes de Começar

- [x] Para configurar os atributos do contrato do serviço é preciso ter um serviço cadastrado previamente.

## Procedimento

1. Acesse a funcionalidade pela navegação no menu principal `Processos >
    Gerência de Portfólio e Catálogo > Portfólio`;
2. Acesse o Portfólio de Serviços que deseja e clique no botão **"Avançar"** do
   &#x20;mesmo;
3. Clique no botão **"Avançar"** do serviço para acessá-lo. Após isso, será
   &#x20;apresentada a tela de Informações do Serviço;
4. Clique na aba <font color="#3b9f0f">**Contratos**</font> e vincule um contrato;
5. Clique no botão **"Avançar"** do contrato para acessar seus atributos;
6. Ao lado esquerdo, serão apresentados os diferentes atributos que podem ser configurados.
7. É necessário incluir um workflow que o serviço irá utilizar.

:::hint{type="info"}
💡 ***Dica*****:** A Gestão de Contrato pode ser realizada clicando diretamente no link de edição. Contudo, é importante verificar se seu perfil tem essa permissão.
:::

## O que Fazer a Seguir

Defina as atividades a serem vinculadas ao contrato cadastrado. Maiores informações podem
&#x20;ser acessadas no conhecimento [Vincular as Atividades ao Contrato do Serviço](docId\:hNgH6ORgY4pJrltZ66jhE).


[title] Untitled
[path] Sobre o CITSmart/Release Notes/


[title] Cadastrar Grupo de Colaboradores
[path] Configurações Iniciais/Configurações Iniciais/Untitled/

Ao cadastrar um grupo, são disponibilizas as permissões no workflow utilizado para o andamento de um ticket. Pode restringir permissões como **reclassificações**, **alterações de prioridades**, **SLAs** e demais **informações&#x20;**&#x6E;o ticket.

Um grupo é um conjunto de um ou mais colaboradores que têm os mesmos objetivos relacionados às suas funções. Os dois usos mais comuns para os grupos criados são:&#x20;

1. Gestão da segurança/sigilo de acessos a vários tipos de cadastros (ex.: pastas da base de conhecimento, portfólios de serviços, etc.).
2. Programação de notificação automática com base em alguma situação/evento específico;

Esta funcionalidade <font color="#3b9f0f">**permite o cadastro de grupos e o vínculo deles com usuários, perfil, contratos e e-mails para notificação,**</font> disponibilizando ações diversas, como: incluir, alterar e excluir um grupo.

## Antes de Começar

Para cadastrar um grupo, é necessário:

- [x] O cadastro prévio do perfil de acesso e do colaborador;
- [x] Receberá uma notificação via e-mail avisando que foi encaminhado para o grupo executor.

## Procedimento

1. Acesse a funcionalidade pela navegação no menu principal `Acesso e Permissão > Grupo`;
2. Clique em **"Novo"**;
3. Defina as configurações necessárias;
4. Clique em **"Gravar"**.

:::hint{type="success"}
✅ ***Regra*****:&#x20;**&#x41; exclusão de um grupo depende que não existam portfólios, colaboradores e contratos vinculados a este.
:::


[title] Cadastrar Tipo de Serviço
[path] 16 Processos/Portfólio e Catálogo/

Esta funcionalidade disponibiliza ações diversas, tais como: <font color="#3b9f0f">**incluir, alterar e
 excluir os tipos de serviço,** </font>que serão utilizados em outras rotinas do sistema.

## Procedimento

1. Acesse a funcionalidade por meio da navegação no menu principal `Processos >
    Gerência de Portfólio e Catálogo > Tipo Serviço`;
2. Preencha o campo obrigatório;
3. Clique em **"Gravar"**.


[title] Gerenciar Minhas Solicitações pelo Smart Portal
[path] 16 Processos/Portfólio e Catálogo/

Esta funcionalidade <font color="#3b9f0f">**permite o**</font> <font color="#3b9f0f">**controle das solicitações abertas pelo usuário**</font>, no qual este poderá verificar o histórico de ocorrência, a descrição da tarefa, trocar mensagens com o executor do ticket, dentre outras ações.

## Antes de Começar

É necessário:

- [x] Ter a solicitação de serviço registrada pelo usuário previamente.
  &#x20;
- [x] Também é fundamental configurar os **parâmetros** referentes ao <font color="#3b9f0f">**Smart Portal**</font>.
- [x] É preciso também setar n&#x6F;**&#x20;parâmetro 253**, o ID do e-mail escolhido para registrar
  &#x20;ocorrência e o ID do modelo de e-mail de notificação no **parâmetro 251**.

## Procedimento

1. Acesse a funcionalidade por meio do menu inicial do <font color="#3b9f0f">**Smart Portal**</font>**;**
2. Clique no
   &#x20;botão de menu e, logo após, em **"Minhas Solicitações"**;

:::hint{type="info"}
**🖊&#x20;*****Nota*****:** Para o correto funcionamento desta aplicação é necessário que o
&#x20;**parâmetro 299** (referente ao <font color="#3b9f0f">**Smart Portal**</font>) esteja setado em "**S**".
:::

3\. Para trocar mensagens com o atendente da solicitação, basta clicar no
&#x20;ícon&#x65;**&#xA0;“Mensagem ao atendente”**. O Atendente receberá o comunicado na área de
&#x20;trabalho do ticket, onde o mesmo cadastrará a resposta da Nota. Esta
&#x20;resposta estará disponível ao clicar novamente neste mesmo ícone.

4\. Para tecer algum comentário referente à solicitação ou relatar alguma
&#x20;ocorrência sobre a mesma, aperte no ícone **“Adicionar nota”**. O Atendente
&#x20;receberá o comunicado na área de trabalho do ticket, onde poderá dirimir
&#x20;qualquer questão relacionada à solicitação.

5\. Para visualizar o histórico da solicitação, basta clicar no
&#x20;ícone **“Histórico”**;

6\. Por esta interface, também é possível visualizar a descrição, os eventuais
&#x20;arquivos anexados a solicitação, dentre outras ações.


[title] Reabrir uma Liberação
[path] 16 Processos/Untitled/

Esta funcionalidade permite <font color="#3b9f0f">**reabrir a liberação de mudanças**</font>.

## Antes de Começar

- [x] É necessário ter permissão para reabrir a liberação.

## Procedimento

1. Acesse a funcionalidade pela navegação no menu principal `Processos >
    Gerência de Liberação > Liberação`;
2. Clique no ícone simbolizado por uma seta para baixo, disponível do lado
   &#x20;direito da tela, dentro do campo de pesquisa;
3. Aperte o botão d&#x65;**&#x20;"Pesquisa avançada"**;
4. Preencha os filtros disponíveis e busque a liberação que
   &#x20;deseja reabrir;
5. Após a pesquisa, clique no ícone **“Reabrir Ticket/Tarefa”** e confirme a
   &#x20;operação.

## O que Fazer a Seguir

Verifique se a liberação está com a situação **"Reaberta"&#x20;**&#x6E;a lista de liberações.


[title] Vincular as Atividades ao Contrato do Serviço
[path] 16 Processos/Portfólio e Catálogo/

Após configurar os atributos do contrato de serviço, será necessário <font color="#3b9f0f">**definir as atividades liberadas para este contrato**</font>, como por exemplo: as requisições e procedimentos disponibilizados para ele, seu custo caso fique indisponível, dentre outras diretrizes especializadas para cada contrato do portfólio.

## Antes de Começar

Para definir as atividades liberadas ao contrato do serviço, é preciso antes
&#x20;cadastrar algumas funcionalidades, como:

- [x] Ter permissão de acesso às
  &#x20;funcionalidades de Gerência de Portfólio e Catálogo;&#x20;
- [x] Ter o portfólio com
  &#x20;serviços cadastrados;
- [x] Ter o contrato vinculado ao serviço;&#x20;
- [x] Cadastro de
  &#x20;fornecedor, cliente, moeda, condição de operação;
- [x] Definir o calendário e o tempo
  &#x20;de atendimento;&#x20;
- [x] Modelos de e-mails;
- [x] Fluxo de trabalho e pesquisas.&#x20;
- [x] Além disso, é
  &#x20;preciso já ter definido os atributos do contrato de serviço.

## Procedimento

1. Acesse a funcionalidade por meio da navegação no menu principal `Processos >
    Gerência de Portfólio e Catálogo > Portfólio`;
2. Acesse o Portfólio de Serviços que deseja e clique no botão **"Avançar"** do
   &#x20;mesmo;
3. Clique no botão **"Avançar"** do serviço para acessá-lo. Após isso, será
   &#x20;apresentada a tela de **Informações do Serviço**;
4. Clique na aba <font color="#3b9f0f">**Contratos**</font> e, em seguida, no botão **"Avançar"** do
   &#x20;contrato do serviço desejado para acessá-lo;

Ao lado esquerdo da tela é disponibilizado as atividades a serem vinculadas ao
&#x20;contrato afim de estabelecer seus parâmetros de "**Atendimento**". São eles:

- **Requisições:&#x20;**&#x4E;esta área é possível realizar o vínculo das atividades
  &#x20;de requisição ao contrato, devendo estas já estarem registradas e
  &#x20;vinculadas ao serviço.
  1. Selecione o botão
     &#x20;"**Vincular Serviço de Requisição**" e preencha os dados referentes a esta
     &#x20;requisição a ser vinculada
  2. Selecione seu **calendário**, sua **condição de
     &#x20;operação**, o **grupo executor da requisição**, os **modelos de notificação (de
     &#x20;abertura, fechamento e andamento)**, dentre outras.
  3. Logo após, na área nomeada
     &#x20;"**Requisição**", clique em "**Adicionar**" e selecione a requisição registrada
     &#x20;no serviço.
- **Incidentes:&#x20;**&#x45;sta atividade segue o mesmo princípio de cadastro de
  &#x20;requisições, para o vínculo de um incidente ao contrato de serviço
  &#x20;exitoso, basta seguir as orientações descritas no item anterior.

:::hint{type="info"}
🖊 ***Nota*****:&#x20;**&#x4E;as atividades de **Requisição e Incidente**, quando você o vincula ou edita, é possível definir o "**Custo do Serviço**" para cada um deles.
:::

- **Procedimento:&#x20;**&#x45;sta atividade segue o mesmo princípio de cadastro de
  &#x20;requisições e incidentes, para o vínculo de um procedimento ao contrato
  &#x20;de serviço exitoso, basta seguir as orientações descritas no item "**Requisições**".

:::hint{type="info"}
🖊 ***Nota*****:&#x20;**&#xC9; imprescindível em todas as atividades acima narradas, vincular um fluxo
&#x20;para esta atividade, do contrário não será possível registrar uma
&#x20;solicitação de serviço. Para tanto, clique no
&#x20;botão "**Adicionar**" na área "**Fluxo Serviço**", selecione o fluxo de trabalho condizente com o cenário
&#x20;e aperte o botão "**Gravar**". &#x20;
:::

- **Custo de Indisponibilidade**: Informar o custo por hora, o que a
  &#x20;organização tem a perder caso ocorra a indisponibilidade do serviço;
- **Acordo de disponibilidades**: Tem o SLA a ser vinculado onde pega o impacto e urgência automaticamente do SLA. Ao clicar no botão "**Vincular Acordo de
  &#x20;Disponibilidade**" é possível buscar e selecionar o SLA acordado entre os
  &#x20;stakeholders do contrato. Deve-se notar que o SLA é que determina os códigos de prioridade;
- **Calendário**: Para vincular um calendário ao contrato, após apertar na área
  &#x20;“Calendário”, clicar no botão "**Vincular Calendário**" e buscar e selecionar o
  &#x20;item desejado;
- **Rateio**: É o percentual que aquele contrato paga sobre o Serviço de
  &#x20;Negócio contratado. Para informar o rateio do contrato em tese, é necessário
  &#x20;clicar no botão "**Adicionar Rateio**" e informar o seu percentual (indicar um
  &#x20;percentual de **1 a 100%**) e o seu ciclo de pagamento.

:::hint{type="success"}
✅ ***Regra*****:**

- Não é permitido rateios diferentes para o mesmo ciclo no mesmo
  &#x20;serviço/negócio/contrato.
- Não é permitido cadastros ou alterações de rateios cujos ciclos já tenham se
  &#x20;encerrado.
- Não é