Custom Fields

How It Works

1. Define a field on the Custom Fields tab of the Scripts page. A field has a name, a key, and a type.
2. Write a collector script that finds the value and reports it with a one-line helper.
3. Mark the script as a collector on the Scripts page and choose how often it runs.
4. Every Windows device runs it on its next check-in, then again on the cadence you chose.

Only the latest value per device is kept.

Defining a Field

1. Go to Scripts, open the Custom Fields tab and click New Field.
2. Fill in:
   • Name - The label shown in the portal (e.g. "EDR Type").
   • Key - The identifier your script uses (e.g. edr_type). Lowercase letters, digits and underscores; must start with a letter. Cannot be changed later.
   • Type - Text, Number, Yes / No, or Date. Values that do not match the type are rejected and shown as an error on the device. Can be changed later; collected values are converted where possible.
3. Click Create Field.

Deleting a field removes its values from every device and stops any group rule that references it from matching.

Changing the type later. The key is fixed once a field exists; the type is not. Edit the field and pick a new type: values that read as the new type are converted in place, values that do not are marked with an error until the next collector run replaces them, and dynamic groups with a rule on the field are re-evaluated. The dialog shows those counts before you save. A date collected into a Text field is the common case: change the field to Date and the stored timestamps convert, so they compare chronologically from then on.

Writing a Collector Script

A collector is an ordinary PowerShell script. The only rule is that it reports values with the helper Pckgr provides automatically inside collector scripts. There is nothing to paste into the portal:

Custom fields are available for Windows devices only for now. macOS support will follow.

Call the helper once per field. A single script can set as many fields as you like. Keys are not case-sensitive. Values are sent as text and converted to the field's type on the server; an empty value clears the field on that device.

From agent 1.1.28, your script runs on the device unchanged from its own file, with the helper supplied by a signed runner script installed with the agent, so a collector you sign with your own certificate keeps its signature. Earlier agents add the helper to the top of the file before running it. See Hardened Environments for the allow-list rules that apply.

Example: EDR type and health (PowerShell)

Define edr_type (Text) and edr_healthy (Yes / No) first, then upload this as a collector:

# Detects which EDR agent is present and whether its service is running.
# [ordered] matters: a plain hashtable enumerates in no guaranteed order.
$known = [ordered]@{
    SentinelAgent   = 'SentinelOne'
    CSFalconService = 'CrowdStrike Falcon'
    SAVService      = 'Sophos'
    WinDefend       = 'Microsoft Defender'
}

$type = 'None'
$healthy = $false

foreach ($service in $known.Keys) {
    $svc = Get-Service -Name $service -ErrorAction SilentlyContinue
    if ($svc) {
        $type = $known[$service]
        $healthy = ($svc.Status -eq 'Running')
        if ($service -ne 'WinDefend') { break }
    }
}

Set-PckgrField -Name edr_type -Value $type
Set-PckgrField -Name edr_healthy -Value $healthy

Tips

• Keep collectors fast and read-only. They run on every Windows device.
• Use System context unless the value only exists in the logged-in user's profile. A User-context collector waits until someone is logged in and retries within the hour if nobody is.
• Normal script output is ignored; only helper calls are recorded, so diagnostics can stay in place.

Marking a Script as a Collector

1. Go to Scripts and create a new script or open an existing one.
2. Turn on Collect custom fields.
3. Choose how often it runs: every hour, every 4 hours, every 12 hours, daily, or weekly.
4. Save.

Collectors are not scheduled against groups. They run on every Windows device, and only while the device is otherwise idle, so they never compete with an app install. The toggle is only offered for PowerShell scripts. Forcing a device check-in from the Devices page re-runs every collector on that device immediately, which is the quickest way to test a new script.

Where Values Appear

• Device detail page - Switch the Device Info card to its Custom Fields tab to see every field with its value. Hover a value to see when it was collected and by which script; a rejected value shows its error in red.
• Devices list - Click Columns above the table to add custom fields as columns. Your choice is remembered in the browser.
• Custom Fields tab (Scripts page) - The list icon on a field shows its value on every device.

Using Custom Fields in Dynamic Groups

On a group's detail page, the rule builder offers every custom field alongside Hostname and OS Version. The operators depend on the field's type:

A device must match all of a group's rules to be a member; there is no "any of" option, so "EDR is Sophos or missing" needs two groups.

When membership is recalculated

Membership is not a one-off check at creation. A device is re-evaluated:

• When the group is created or its rules are saved, against every device in the tenant.
• Every time the device checks in, roughly every five minutes.
• Every time a collector reports values for that device, so a changed field moves it in or out of groups in the same cycle.
• When the device enrolls, so it lands in the right groups before its first check-in.

Devices that join a group receive that group's app assignments automatically, which is what turns a collected fact ("EDR type is None") into an action (install the EDR agent). Leaving a group stops future assignments but does not uninstall anything already deployed.

Troubleshooting

Open the collector script and check the Collector Runs card. Each device shows its last run time, status, exit code, how many fields it set, and any problem:

• Unknown field key(s) - The script set a key that is not defined under Custom Fields. Check the spelling; case does not matter.
• The script completed but did not set any fields - The script never called the helper. Printing the value is not enough.
• Deferred - A User-context collector ran while nobody was logged in. It retries within the hour.
• Nothing in the runs list at all - The device may still be on an older agent that does not support collectors, or it has not checked in yet.
• A field shows an error instead of a value - The reported value could not be converted to the field's type. The error is shown in place of the value on the device's Custom Fields tab.
• A date shows as a long raw timestamp - The field was created as Text rather than Date. Edit the field and change its type to Date; the stored timestamps convert in place.