Getting Started with Custom Inventory

Custom inventory is your own data about your Windows endpoints, for example the office an endpoint belongs to. A script writes the data on the endpoint, and the CapaOne Agent sends it with its hardware inventory. CapaOne shows it on the endpoint’s page, under Inventory → Custom.

In this walkthrough, you create a script that writes custom inventory, run it on a test endpoint, and remove the data again.

Before you start

• Scripts require Application Manager.
• You need a Windows endpoint to test on, with CapaOne Agent 1.2.273 or later. Agents update automatically.

1. Create a script

1. Go to Windows → Applications and select the Scripts tab.
2. Click New.
3. Enter a Name, for example Custom Inventory Demo, and a Version, for example 1.0.
4. Under PowerBricks, click Open PowerBrick Editor.
5. Search for Execute PowerShell Snippet, and add it to the Install tab of the Execution Sequence.
6. Add a second Execute PowerShell Snippet to the Uninstall tab. It removes the demo data when you uninstall the script.

Leave the editor open for the next step. Create a Script describes the script’s other settings, and Execute PowerShell Snippet describes the brick.

2. Add the demo code

The code uses the custom inventory functions of the PowerShell Scripting Library, which you call in the snippet as $cs.CustomInventory_*. It writes two categories:

• Office is a category without instances. The endpoint has one set of values, written with the instance ''. Replace the values with your own, for example in one script per office.
• Printers is a category with instances: one instance per printer, with its driver, its port, and whether it’s shared. The code also removes printers that are gone since the script last ran.

1. Open the brick on the Install tab, and paste this code into PowerShell Snippet:

   # A category without instances: one set of values for the device.
   # Replace the values with your own, for example in one script per office.
   $cs.CustomInventory_SetValue('Office', '', 'City', 'Copenhagen')
   $cs.CustomInventory_SetValue('Office', '', 'Floor', 3)
   $cs.CustomInventory_SetValue('Office', '', 'Has Parking', $true)
   
   # A category with instances: one instance per printer.
   $printers = @{}
   foreach ($printer in Get-Printer -ErrorAction SilentlyContinue) {
       # Names can only contain letters, digits, spaces and -, so replace other characters with a space.
       $instance = ($printer.Name -replace '[^\p{L}\p{Nd} -]', ' ' -replace ' {2,}', ' ').Trim()
       $printers[$instance] = $true
       $cs.CustomInventory_SetValue('Printers', $instance, 'Driver', $printer.DriverName)
       $cs.CustomInventory_SetValue('Printers', $instance, 'Port', $printer.PortName)
       $cs.CustomInventory_SetValue('Printers', $instance, 'Shared', $printer.Shared)
   }
   
   # Remove the printers that are gone since the script last ran.
   foreach ($instance in $cs.CustomInventory_GetInstanceNames('Printers')) {
       if (-not $printers.ContainsKey($instance)) {
           $cs.CustomInventory_RemoveInstance('Printers', $instance)
       }
   }

2. Click Apply changes.

3. Open the brick on the Uninstall tab, and paste this code into PowerShell Snippet:

   $cs.CustomInventory_RemoveCategory('Office')
   $cs.CustomInventory_RemoveCategory('Printers')

4. Click Apply changes, and then Close.

5. Click Create. The script is created with the release status Testing.

Category, instance, and value names can only contain letters, digits, spaces, and -. That’s why the code replaces the other characters in printer names: OneNote (Desktop) becomes OneNote Desktop. A name with other characters makes the script fail, and the installation log says which characters aren’t allowed. Open the log with View logs in the endpoint’s row menu on the script’s Endpoints tab.

3. Run the script on a test endpoint

1. Open the script, select the Assignment tab, and assign the script to your test endpoint under Direct. CapaOne asks you to confirm, because the script is in Testing. See Assign and Redeploy Windows Applications.
2. Select the script’s Endpoints tab, and wait until the script has run on the endpoint.
3. Open the endpoint’s page, open the actions menu (⋮) in the header, point to Request, and select Scan hardware. The agent sends custom inventory with its hardware inventory, so the request delivers it now instead of with the next scan.
4. Select Inventory → Custom.

The Custom tab lists your categories. Office has one card, named after the category, and Printers has one card per printer. Each card ends with Last Updated, the time a value on the card last changed.

4. Keep the data current

The values stay on the endpoint until a script removes them, and the agent sends them with every hardware inventory. The script itself runs once on each endpoint that it’s assigned to.

To run the script again, for example every week so the list of printers stays current, use a workflow with the Install script action and Redeploy if assigned. See Repeat a Company App or script on a schedule.

5. Remove the demo data

1. On the script’s Endpoints tab, open the endpoint’s row menu and select Uninstall. The Uninstall sequence removes both categories.
2. When the script has been uninstalled, send Scan hardware again.

The endpoint’s Custom tab shows No Custom Inventory again, unless other scripts write custom inventory on the endpoint.

Next steps

Find endpoints by their custom inventory

Use the MCP server or the REST API to search, count, and group endpoints by their custom inventory. For example, find the endpoints in the Copenhagen office. A new field can be filtered on within an hour after an endpoint first reports it. See Custom inventory fields.

Custom inventory functions

The PowerShell Scripting Library has these functions for custom inventory:

Function	What it does
$cs.CustomInventory_SetValue	Writes a value, optionally with a unit such as bytes or date. Creates the category and instance if they don’t exist.
$cs.CustomInventory_GetValue	Reads a value without its unit.
$cs.CustomInventory_GetInstance	Returns all values of an instance.
$cs.CustomInventory_GetCategory	Returns all instances of a category with their values.
$cs.CustomInventory_GetCategoryNames	Returns the names of the categories on the endpoint.
$cs.CustomInventory_GetInstanceNames	Returns the names of the instances in a category.
$cs.CustomInventory_RemoveValue	Removes a value.
$cs.CustomInventory_RemoveInstance	Removes an instance with all its values.
$cs.CustomInventory_RemoveCategory	Removes a category with all its instances and values.

$cs.CustomInventory_SetValue also describes the names, the units, and the value types in detail.