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.

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.

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 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
• Run scripts on endpoints