> For the complete documentation index, see [llms.txt](https://wiki.datadike.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.datadike.com/pt/sonar/administration/settings/custom-fields.md).

# Campos personalizados

Adicione campos próprios a clientes, sites e dispositivos, preencha-os nos formulários deles e use os valores em scripts.

## O que é e quando usar

Os campos personalizados acrescentam dados seus a clientes, sites e dispositivos: um número de contrato em um cliente, um prédio em um site, uma etiqueta de patrimônio ou um centro de custo em um dispositivo. Depois que um campo existe, ele aparece nos formulários desse tipo de objeto, o valor dele é exibido na aba **Home** do dispositivo, e os scripts podem lê-lo.

Um script também pode gravar em um campo personalizado, de modo que um campo pode guardar algo que o dispositivo informa, como uma configuração da BIOS ou a versão de um programa.

## Antes de começar

* Um papel com **View Core Settings** para abrir **Admin Center › Settings**, **View Custom Fields** para ver os campos, e **Manage Custom Fields** para adicioná-los, editá-los ou excluí-los (**Admin Center › Roles**, grupo **Settings**).
* Para preencher os valores: **Manage Clients**, **Manage Sites** ou **Edit Agent**, conforme o objeto.
* Um nome para o campo. Ele precisa ser único entre os campos do mesmo alvo.

## Passos

1. Abra **Admin Center › Settings** e a aba **Custom Fields**.
2. Escolha a aba do alvo: **Clients**, **Sites** ou **Agents**.
3. Clique em **Add custom field**. O formulário abre com esse alvo selecionado.
4. Preencha **Name** e escolha o **Field Type**.
5. Para **Dropdown Single** e **Dropdown Multiple**, digite cada opção em **Input Options** e pressione Enter depois de cada uma.
6. Defina um **Default Value** se o campo deve ter um.
7. Marque **Required**, **Hide in Dashboard** ou **Hide in Summary Tab** conforme a necessidade; veja a referência de campos.
8. Clique em **Submit**. O console confirma com `Custom field added!`.

Para alterar um campo, clique duas vezes na linha dele, ou clique nela com o botão direito e escolha **Edit**. **Target** e **Field Type** não podem ser alterados depois da criação. Para remover um campo, clique nele com o botão direito e escolha **Delete**; os valores guardados nele são removidos junto.

## O que você deve ver

O campo aparece na aba do seu alvo com **Name**, **Field Type**, **Hide in UI**, **Hide in Summary Tab**, **Default Value** e **Required**. Uma aba sem campos mostra `No custom fields defined for clients.` (com sites ou agents no lugar de clients).

Em seguida, o campo aparece:

* **Clients**: no formulário do cliente (**Create Client**, **Editing CLIENT-A**), em **Custom Fields**. Veja [Clientes e sites](https://wiki.datadike.com/pt/sonar/administration/devices/clients-and-sites.md).
* **Sites**: no formulário do site, em **Custom Fields**.
* **Agents**: no formulário **Edit** do dispositivo, na aba **Custom Fields**, e no quadro **Custom Fields** da aba **Home** dele assim que tiver um valor. Veja [A lista de dispositivos](https://wiki.datadike.com/pt/sonar/administration/devices/device-list.md#editar-um-dispositivo).

Cada campo de entrada mostra o valor padrão como dica, por exemplo `Default value: Unassigned`.

## Como verificar se funcionou

1. Abra o formulário de um objeto desse alvo: **Edit** em um dispositivo, ou **Edit** em um cliente ou site. O campo aparece em **Custom Fields**.
2. Preencha um valor e salve.
3. Para um campo de dispositivo, abra a aba **Home** do dispositivo: o valor aparece no quadro **Custom Fields**, a menos que o campo esteja configurado com **Hide in Summary Tab**.
4. **Reports & Audits › Audits** registra a criação do campo como uma ação **Add Object** no objeto **Custom Field**, e as alterações posteriores como **Modify Object** ou **Delete Object**.

## Usar campos personalizados em scripts

Os argumentos e as variáveis de ambiente de um script podem ler um campo personalizado pelo nome:

| Variável                     | Valor                                                                       |
| ---------------------------- | --------------------------------------------------------------------------- |
| `{{agent.Asset Tag}}`        | O valor do dispositivo no campo de agente `Asset Tag`                       |
| `{{site.Building}}`          | O valor do campo de site `Building` para o site do dispositivo              |
| `{{client.Contract Number}}` | O valor do campo de cliente `Contract Number` para o cliente do dispositivo |

Quando o objeto não tem valor, a variável assume o valor padrão do campo. Um valor **Dropdown Multiple** é passado como uma lista separada por vírgulas, e um valor **Checkbox** como um booleano do shell do script. Escreva o nome do campo exatamente como está grafado em **Name**. Veja [Variáveis de script](https://wiki.datadike.com/pt/sonar/reference/script-variables.md).

Para gravar em um campo, execute um script com a opção de saída **Save results to Custom Field** e escolha o campo em **Select custom field**. A última linha da saída é guardada, ou a saída inteira com **Save all output**. Um campo de cliente ou de site é gravado no cliente ou no site do dispositivo. Veja [Executar um comando ou um script em um dispositivo](https://wiki.datadike.com/pt/sonar/administration/automation/run-commands-and-scripts.md).

## Erros comuns

| Sintoma                                                                               | Causa                                                                                               | Correção                                                             |
| ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| `Failed to add custom field`                                                          | Já existe um campo com o mesmo nome para esse alvo, ou o seu papel não tem **Manage Custom Fields** | Use outro nome, ou peça que a permissão seja adicionada ao seu papel |
| `Default Value needs to be set for required fields`                                   | **Required** está marcado e **Default Value** está vazio                                            | Defina um valor padrão                                               |
| `Asset Tag is required` sob um campo de um formulário                                 | O campo é obrigatório e está sem valor                                                              | Preencha o campo                                                     |
| A aba **Custom Fields** do dispositivo diz que não há campos personalizados de agente | Não existe nenhum campo em **Agents**, ou todos estão configurados com **Hide in Dashboard**        | Adicione um campo em **Agents**, ou desmarque **Hide in Dashboard**  |
| O valor não aparece na aba **Home**                                                   | O campo está configurado com **Hide in Summary Tab**, ou não tem valor                              | Desmarque a opção, ou preencha o valor                               |

## Referência de campos

| Campo                            | O que faz                                                                                                                                                            | Valores aceitos                                                                              | Padrão                              |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | ----------------------------------- |
| Target                           | A quais objetos o campo pertence. Não pode ser alterado depois                                                                                                       | **Client**, **Site**, **Agent**                                                              | A aba a partir da qual você começou |
| Name                             | Nome exibido nos formulários e usado nas variáveis de script                                                                                                         | Até 100 caracteres, único dentro do alvo                                                     | (sem padrão)                        |
| Field Type                       | Tipo de entrada. Não pode ser alterado depois                                                                                                                        | **Text**, **Number**, **Dropdown Single**, **Dropdown Multiple**, **DateTime**, **Checkbox** | (sem padrão)                        |
| Input Options                    | As opções de uma lista suspensa. Só para **Dropdown Single** e **Dropdown Multiple**                                                                                 | Qualquer texto, uma entrada por opção                                                        | Vazio                               |
| Default Value / Default Value(s) | Valor usado quando um objeto não tem nenhum, como dica nos formulários e nas variáveis de script                                                                     | Compatível com o tipo do campo; uma das opções, nas listas suspensas                         | Vazio                               |
| Required                         | Marca o campo como obrigatório nos formulários, que mostram `NAME is required` enquanto ele está vazio. Exige um **Default Value**. Não disponível para **Checkbox** | Ligado, desligado                                                                            | Desligado                           |
| Hide in Dashboard                | Mantém o campo fora dos formulários de cliente, site e dispositivo. Os scripts ainda podem lê-lo e gravá-lo                                                          | Ligado, desligado                                                                            | Desligado                           |
| Hide in Summary Tab              | Mantém o valor fora do quadro **Custom Fields** na aba **Home** do dispositivo                                                                                       | Ligado, desligado                                                                            | Desligado                           |

## Páginas relacionadas

* [Variáveis de script](https://wiki.datadike.com/pt/sonar/reference/script-variables.md)
* [Clientes e sites](https://wiki.datadike.com/pt/sonar/administration/devices/clients-and-sites.md)
* [A lista de dispositivos](https://wiki.datadike.com/pt/sonar/administration/devices/device-list.md)
* [Executar um comando ou um script em um dispositivo](https://wiki.datadike.com/pt/sonar/administration/automation/run-commands-and-scripts.md)
