Custom properties for devices
Applies to: Configuration Manager (current branch)
Many customers have other data that's external to Configuration Manager but useful for deployment targeting, collection building, and reporting. This data is typically non-technical in nature, not discoverable on the client, and comes from a single external source. For example, a central IT Infrastructure Library (ITIL) system or asset database, which has some of the following device attributes:
- Physical location
- Organizational priority
- Category
- Cost center
- Department
Starting in version 2107, you can use the administration service to set this data on devices. The site stores the property's name and its value in the site database as the Device Custom Properties class. You can then use the custom properties in Configuration Manager for reporting or to create collections.
Starting in version 2111, you can create and edit these custom properties in the Configuration Manager console. This new user interface makes it easier to view and edit these properties.
Note
You can use unicode characters for custom property values, but not the property names. For more information, see Unicode and ASCII support in Configuration Manager.
Prerequisites
The account that makes the API calls requires the following permissions on a collection that contains the target device:
- To set properties: Modify Resource
- To view properties: Read Resource
- To remove properties: Delete Resource
Set properties via UI
Applies to version 2111 or later
In the Configuration Manager console, go to the Assets and Compliance workspace, and select the Devices node.
Select a device, and then in the ribbon select Properties
Switch to the Custom Properties tab.
Select the gold star icon
to create a new custom property. Provide a name for the property and set a value for this device. Select OK to save the properties.
Set properties via API
Applies to version 2107 or later
To set properties on a device, use the SetExtensionData API. Make a POST call to the URI https://<SMSProviderFQDN>/AdminService/v1.0/Device(<DeviceResourceID>)/AdminService.SetExtensionData with a JSON body. The resource ID is an integer value, for example 16777345.
This JSON example sets two name-value pairs for the device's asset tag and location:
{
"ExtensionData": {
"AssetTag":"0580255",
"Location":"Dublin"
}
}
View properties
Use the GetExtensionData API to view your custom properties.
To view properties on a single device, make a GET call to the URI https://<SMSProviderFQDN>/AdminService/v1.0/Device(<DeviceResourceID>)/AdminService.GetExtensionData.
To view properties on all devices, make a GET call to the URI https://<SMSProviderFQDN>/AdminService/v1.0/Device/AdminService.GetExtensionData. This call returns property values from devices to which you have read permission.
Remove properties
To remove properties values from all devices, use the DeleteExtensionData API without a device ID. Include a device resource ID to only remove properties from a specific device. Make a POST call to the URI https://<SMSProviderFQDN>/AdminService/v1.0/Device/AdminService.DeleteExtensionData.
Create a collection
Use the following steps to create a collection with a query rule based on the custom properties:
In the Configuration Manager console, Create a collection.
On the Membership Rules page, in the Add Rule list, select Query rule.
In the Query Rule Properties window, specify a Name for the query. Then select Edit Query Statement.
In the Query Statement Properties window, switch to the Criteria tab. Then select the golden asterisk (
*) to add new criteria.In the Criterion Properties window, Select the following values:
- Attribute class: Device Custom Properties
- Attribute: PropertyName
Select an Operator and then specify the name of the property as the Value.
At this point, the Criterion Properties window should look similar to the following image:
Select OK to save the criterion.
Repeat the steps to add a criterion for the PropertyValue attribute.
At this point, the collection Query Statement Properties window should look similar to the following image:
Select OK to close all property windows. Then complete the wizard to create the collection.
Example WQL statement
You can also use the following sample query. In the query statement properties window, select Show Query Language to paste the query statement.
select SMS_R_SYSTEM.ResourceID,SMS_R_SYSTEM.ResourceType,SMS_R_SYSTEM.Name,SMS_R_SYSTEM.SMSUniqueIdentifier,SMS_R_SYSTEM.ResourceDomainORWorkgroup,SMS_R_SYSTEM.Client
from SMS_R_System inner join SMS_G_System_ExtensionData on SMS_G_System_ExtensionData.ResourceId = SMS_R_System.ResourceId
where SMS_G_System_ExtensionData.PropertyName = "AssetTag" and SMS_G_System_ExtensionData.PropertyValue = "0580255"
Note
To use custom properties WQL statements with incremental collection updates, use Configuration Manager version 2107 with the update rollup or later.