---
title: "Endpoint custom fields"
description: "Define a custom field for facts inventory does not collect, fill it with a collector script or by hand, and filter the endpoint list on it."
url: "https://support.outpostplatform.com/automation/custom-fields/"
product: "depot"
type: "how-to"
status: "draft"
ai_summary: "Scripts > Custom fields defines endpoint custom fields: a fixed key, a name, and a fixed kind (Text, Number, Date, Yes or no, Choice). A collector script writes its output into one, or a technician edits it on the endpoint's Overview tab. Fields can be offered as endpoint list filters. Values are stored unencrypted. Needs script:manage to define."
availability:
  plans: ["home-lab", "essentials", "enterprise", "msp"]
  permission: "script:manage"
  preview: false
source: "https://gitlab.com/outpostplatform/docs/-/edit/main/src/content/docs/automation/custom-fields.md"
license: "CC BY 4.0"
---

# Endpoint custom fields

An endpoint custom field holds a fact about an endpoint that inventory does not
collect, such as an asset tag, a warranty date, or the result of a check you
script yourself. A collector script fills it in on every run, or a technician
types it in. This page defines a field, fills it, and uses it to filter the
endpoint list.

## Before you begin

- To define, edit, or remove a field you need `script:manage`. To see field
  definitions you need `script:read`. To edit a value on an endpoint you need
  `endpoint:write`.
- On the MSP plan, open the client's workspace first. Fields belong to one
  client.

:::danger
Custom field values are stored unencrypted. Do not collect passwords, keys, or
personal data into them.
:::

## Define a field

1. Go to **Scripts** > **Custom fields** and select **New field**.
2. In **Key**, enter the name collectors and filters use, such as
   `asset_tag`. Use lower-case letters, numbers, and underscores, starting
   with a letter, up to 64 characters. The key cannot be changed later.
3. In **Name**, enter the name people see, such as `Asset tag`.
4. In **Kind**, choose **Text**, **Number**, **Date**, **Yes or no**, or
   **Choice**. The kind cannot be changed later. For **Choice**, enter the
   **Choices**.
5. Select **Offer it as a filter on the endpoint list** to filter the fleet on
   this field.
6. Select **Add field**.

You can change a field's name, choices, and list setting later with **Edit**.
**Remove** hides the field and keeps the values already recorded.

## Fill it with a collector script

A collector is a script whose output is written into a custom field on the
endpoint it ran on.

1. Open the script in **Scripts** > **Library**, or write a new one. See
   [Write and approve a script](/automation/write-and-approve-scripts/).
2. Under **Collector**, select **This script's output fills in an endpoint
   field**.
3. In **Endpoint field**, enter or choose the field's key.
4. In **Read the output as**, choose how the output becomes the value:

   | Option | The script prints |
   | --- | --- |
   | **Whole output** | The value and nothing else. The output is trimmed. |
   | **JSON** | A single JSON value, or a JSON object with a member named after the field's key or named `value`. |
   | **Key and value** | Lines of `key=value` or `key: value`. The line whose key matches the field's key is used. |

5. Save and approve the script, then run it or schedule it. See
   [Run scripts on endpoints](/automation/run-scripts/).

If no field with that key exists yet, the **Collector** card says **No endpoint
field is defined for** the key, and offers to create one. The
[built-in collector scripts](/automation/script-library/#collectors) write to
fixed keys, such as `bios_serial`, so create a field with that key before you
run one.

A run that prints nothing to store leaves the previous value in place.

## Fill it by hand

1. Open the endpoint. The **Custom fields** card is on its **Overview** tab.
2. Select **Edit**, enter the values, and select **Save**.

Each value records whether a script or a person set it, and when.

## Verify

Open an endpoint the collector ran on. The **Custom fields** card on its
**Overview** tab shows the value. A field with no value shows **Not collected
yet**. If you offered the field as a filter, filter the endpoint list on it.

## If something goes wrong

| Symptom | Cause | Fix |
| --- | --- | --- |
| The field stays **Not collected yet** after a run | The collector's field key does not match the field's key, or the run failed. | Check the key on the script's **Collector** card, and the run's result in **Scripts** > **Batches**. |
| A **Number**, **Date**, or **Yes or no** field is not updated | The output could not be read as that kind. | Print a number, a date as `YYYY-MM-DD` or an RFC 3339 timestamp, or a yes or no value. |
| The key is refused | It has characters other than lower-case letters, numbers, and underscores, does not start with a letter, or is already taken. | Choose another key. |

## Next steps

- [Built-in script library](/automation/script-library/)
- [Run scripts on endpoints](/automation/run-scripts/)