Campos personalizados

Campos personalizados acrescentam informações aos formulários sem alterar o código. Somente owner e admin podem criar, editar ou excluir definições.

Onde os campos aparecem

Escopo	Uso atual
Projeto	Formulários de criação e edição de projeto
Atualização de projeto	Publicação e edição de atualizações, inclusive no campo
Evento	Criação e edição da agenda operacional
Ocorrência	Criação e edição de ocorrências, inclusive no campo
Cliente	Pode ser definido na administração, mas os formulários atuais de cliente não carregam esse escopo
Equipe	Pode ser definido na administração, mas os formulários atuais de equipe não carregam esse escopo

Não crie campos de cliente ou equipe esperando exibição imediata. Eles estão previstos no catálogo de escopos, porém ainda não são consumidos pelos respectivos formulários.

Tipos disponíveis

Tipo	Quando usar	Configuração adicional
text	Resposta curta	Placeholder, ajuda e validação
textarea	Texto longo	Placeholder, ajuda e validação
expression	Expressão ou texto técnico	Ajuda e validação
number	Quantidade, medida ou valor numérico	Mínimo e máximo
select	Escolha em lista fechada	Opções JSON
boolean	Sim ou não	Valor padrão opcional
json	Estrutura JSON livre	Orientação clara para o operador
grid_form	Lista de linhas com subcampos	Definição JSON dos subcampos
info	Texto informativo sem valor persistido	Ajuda ou conteúdo de orientação

Criar um campo

1. Abra Campos personalizados e selecione criar.
2. Escolha o escopo.
3. Informe uma chave técnica estável, como numero_serie.
4. Informe o rótulo que o usuário verá.
5. Escolha o tipo.
6. Marque se o preenchimento é obrigatório.
7. Configure valor padrão, ajuda e placeholder quando fizerem sentido.
8. Para listas ou grades, informe JSON válido.
9. Defina a ordem entre 0 e 999.
10. Marque o campo como ativo e salve.

Regras da chave

• Deve começar com letra minúscula.
• Pode conter somente letras minúsculas, números e _.
• Tem no máximo 120 caracteres.
• Deve ser única por empresa, escopo e segmento.
• Evite renomear a chave depois que o campo possuir valores; ela é a referência técnica do dado.

Exemplos

Opções de um campo select:

[
  { "value": "preventiva", "label": "Preventiva" },
  { "value": "corretiva", "label": "Corretiva" }
]

Subcampos de uma grade:

[
  { "key": "item", "label": "Item", "type": "text" },
  { "key": "concluido", "label": "Concluído", "type": "boolean" }
]

Validação numérica:

{ "min": 0, "max": 100 }

JSON inválido nos campos de configuração é convertido para lista vazia. Sempre valide o resultado no formulário de destino.

Obrigatoriedade e validação

• Campo obrigatório bloqueia o envio quando vazio, exceto o tipo informativo.
• Número aceita apenas valor numérico.
• Boolean aceita valor verdadeiro ou falso.
• JSON e grade são enviados pelo formulário como texto e normalizados pelo serviço.
• Opções configuradas limitam o valor aos respectivos value.
• Mínimo e máximo são incorporados às regras quando forem numéricos.
• Campos inativos não são carregados nos formulários.

Editar, desativar ou excluir

• Editar: altera a definição usada nos próximos carregamentos.
• Desativar: preserva definição e valores, mas esconde o campo dos formulários ativos.
• Excluir: remove a definição e os valores associados por cascata. Use somente depois de confirmar que o histórico pode ser descartado.

Se um campo obrigatório for ativado em uma operação já existente, novos envios passarão a exigir o valor; registros antigos não são preenchidos automaticamente.

Como validar

1. Crie o campo como ativo no escopo correto.
2. Abra um novo formulário do módulo.
3. Confirme rótulo, ajuda, ordem e valor padrão.
4. Tente salvar sem um campo obrigatório.
5. Preencha e salve.
6. Reabra o registro e confirme o valor.
7. No caso de atualização ou ocorrência, repita no modo campo.

Erros comuns

• Campo não aparece: está inativo, no escopo errado ou em cliente/equipe, que ainda não carregam campos dinâmicos.
• Chave rejeitada: contém maiúscula, espaço, hífen ou já existe no mesmo escopo e segmento.
• Lista vazia: o JSON de opções não é uma lista válida.
• Valor rejeitado: não pertence às opções ou viola mínimo, máximo ou tipo.
• Dados desapareceram: a definição foi excluída; desativar é a alternativa quando os valores precisam ser preservados.

Segurança

Não use campos personalizados para senhas, tokens, chaves privadas ou dados pessoais sem necessidade e base de tratamento definida.

Próximos assuntos

• Empresa e segmentos
• Projetos
• Operação de campo