Populate Custom Fields from Script Output in Atlas Reach

Turn a script check's output into a device custom field in Atlas Reach: collect values such as a BIOS version, and more.

Before you begin

  • Atlas Reach agents enrolled and approved on the devices you want to collect from (see Installing the Atlas Reach Agent)
  • An administrator account in Atlas AVD, to create checks on the Checks tab of Atlas Reach
  • A script in your Scripts library that prints the value you want to store. Windows devices can run PowerShell, CMD or Batch scripts; macOS and Linux devices run PowerShell scripts through PowerShell 7 (pwsh), which must be installed on the device

How it works

A script check runs a script from your Scripts library on each device it applies to, on a schedule you choose. Normally the check only looks at the exit code: 0 passes, anything else fails and can raise an alert. When you fill in Store output in field, the agent also sends back what the script printed, and Atlas saves it as that device's value for the field you named.

  • The value is saved on every run, whether the check passes or fails, so a failing check can still report useful text.
  • Each run replaces the previous value, so the field always shows the latest output.
  • Only standard output is stored. Error output is not, and leading and trailing blank space is trimmed.
  • A field holds up to 500 characters. Longer output is cut off at 500.
  • Only script checks can store output. Metric, service, ping, event log and the other check types do not have the option.

Step 1: Write a script that prints just the value

Whatever the script writes to standard output becomes the field's value, so print only the value itself, with no headings or extra lines. Exit with code 0 when everything is fine. Add the script to your Scripts library (Scripts in the sidebar) and note its library ID; the check refers to the script by that ID. For example, to collect each Windows device's BIOS version:

# PowerShell: print the BIOS version and nothing else
(Get-CimInstance -ClassName Win32_BIOS).SMBIOSBIOSVersion
exit 0

Keep the script quick and quiet. A script check is stopped after 60 seconds, and the script body can be up to 64 KB. Avoid Write-Host banners or progress text, because anything printed ends up in the field.

Step 2: Create a script check that stores its output

Open Atlas Reach (Atlas Operations → Reach in the sidebar), go to the Checks tab, and click New check. Then fill in the editor:

  1. Name: a clear name such as BIOS version. If the field does not exist yet, Atlas uses this name as the field's label.
  2. Type: Script.
  3. Target: the library ID of the script from Step 1.
  4. Store output in field: the key of the field to fill, for example bios_version. Keys are lower-case letters, numbers and underscores, starting with a letter, up to 64 characters.
  5. Interval (seconds): how often the script runs. The default is 300 seconds (5 minutes); you can choose anything from 30 seconds to 86,400 seconds (once a day). For values that rarely change, such as a BIOS version, a long interval is plenty.
  6. Scope: Tenant (every device), a Host pool, or a single Device.
  7. Leave Enabled on and save.

You do not need to create the field first. When you save a check with a field key that does not exist yet, Atlas defines it for the whole tenant using the check's name as the label, so the value shows on every device from the first run. If a field with that key already exists, Atlas keeps it and its label as they are.

Step 3: See the values

The agent picks up the new check automatically and runs it on its next interval. Once it has run, open a device from the Devices tab of Atlas Reach and go to its Notes & fields tab: the field appears under Custom fields with the script's latest output. A device the check has not run on yet shows Not set.

  • Notes & fields tab: the current value on each device, under the field's label.
  • Device CSV export: every tenant custom field is added as its own column at the end of the export, so you can take the values into a spreadsheet or asset register.
  • Scripts you run later: use {{device.custom.<key>}} in a script, its arguments or its environment values, and Atlas replaces it with that device's value before the script runs (empty if the device has no value). For example, {{device.custom.bios_version}}.

Example uses

  • Hardware and firmware: BIOS version, TPM version, battery health, or disk model.
  • Warranty and lifecycle: a warranty end date, or the date the OS was last reinstalled.
  • Software: the installed version of a line-of-business app, an antivirus definition date, or the Office update channel.
  • Configuration: the primary user, a BitLocker recovery-key ID, or the Wi-Fi profile in use.
  • Chaining scripts: collect a value with one check, then use it as {{device.custom.<key>}} in a fix-up script that you run against the same devices.

Alert when the value is not the one you want

The same check can also judge the value it stores. In the check editor, set Pass only when the output to a comparison such as equals and type the value you expect in Expected value. The field keeps showing the latest output, and the check fails and alerts on any device where the output does not match. For a full walkthrough with examples, see Check a Device Setting with a PowerShell Script.

macOS and Linux

On macOS and Linux, script checks run PowerShell scripts through PowerShell 7 (pwsh). Install pwsh on those devices, and write cross-platform PowerShell. A CMD or Batch script check only runs on Windows; on other devices it reports an error instead of a value. For example, to store the macOS version:

# PowerShell 7 on macOS: print the OS version
(sw_vers -productVersion).Trim()
exit 0

Things to know

  • The check overwrites the field on every run, including any value someone typed in by hand on Notes & fields. Use a separate field for values you want to edit manually.
  • To stop collecting, clear Store output in field on the check, or disable or delete the check. The last stored value stays on each device until you change or clear it.
  • Removing a field on the Notes & fields tab removes it for the whole tenant and clears its value on every device. If a check still stores into that key, Atlas defines the field again the next time you save that check.
  • A tenant can define up to 50 custom fields.
  • If the script is missing from the library, uses a language the agent cannot run, or is empty, the check is not sent to devices and no value is stored.

Field not filling in? Check the Checks tab for the check's latest status and detail: a script that times out or cannot start reports an error and stores nothing. Confirm the script prints the value to standard output, and that the device is online and running a current agent.

Next steps