[ACC] Additional information for populating "Assigned To" attribute in Computer CI - Support and Troubleshooting

[ACC] Additional information for populating "Assigned To" attribute in Computer CI .ns-kb-css-body-editor-container { p { font-size: 12pt; font-family: Lato; color: var(--now-color--text-primary, #000000); } span { font-size: 12pt; font-family: Lato; color: var(--now-color--text-primary, #000000); } h2 { font-size: 24pt; font-family: Lato; color: var(--now-color--text-primary, black); } h3 { font-size: 18pt; font-family: Lato; color: var(--now-color--text-primary, black); } h4 { font-size: 14pt; font-family: Lato; color: var(--now-color--text-primary, black); } a { font-size: 12pt; font-family: Lato; color: var(--now-color--link-primary, #00718F); } a:hover { font-size: 12pt; color: var(--now-color--link-primary, #024F69); } a:target { font-size: 12pt; color: var(--now-color--link-primary, #032D42); } a:visited { font-size: 12pt; color: var(--now-color--link-primary, #00718f); } ul { font-size: 12pt; font-family: Lato; } li { font-size: 12pt; font-family: Lato; } img { display: ; max-width: ; width: ; height: ; } } Table of Contents Introduction Summary Permissions required for collection of Username data Payload format Matching collected Username to sys_user System Properties Troubleshooting Introduction

This article contains supplemental information regarding the population of "Assigned To" attribute on Computer CIs using Agent Client Collector for Visibility Content.

Product Documentation

Agent Client Collector for Visibility Content may be used to populate the assigned_to value for host CIs. It is a default option in the "Enhanced Discovery" check to collect local user information - this article will explain how this data is collected and processed.

Summary The population of "Assigned To" attribute [assigned_to] is supported only for Windows and Mac OS end-user Computer class CIs - [cmdb_ci_computer]. It is not supported for Server class CIs (Windows Server or Linux Server), or other child classes of [cmdb_ci_computer].

The "Assigned To" attribute in ACC is populated based on the currently logged in user. If no users are presently logged in to the device, the payload section below contains no user information.

The information is collected as part of a Discovery check using the "endpoint_discovery.rb" command when including the "local_users" module. This module is included in the default check configuration for the Enhanced Discovery check.

Permissions required for collection of Username data To collect locally logged on users, the default permissions granted by the Windows Installer may not be sufficient. Additionally, many administrators install the agent with different permissions for Windows based on security policies.

Review expected permissions matrix for ACC installation here

The default "servicenow" local user created by the Windows Installer grants "Log On as a Service", "Backup", and "Debug Programs" privileges, but administrators are encouraged to review and apply principle of least privilege for the required ACC features.

To query currently logged on users, Windows requires local logon rights - which are not granted automatically to the default "servicenow" user. The "Allow Log on Locally" privilege may be granted in the local security policy to provide permission to query locally logged on users. This permission is often granted by default for Domain Joined service accounts - or by inclusion in the "Users" group.

Consider carefully the rights you wish to provide to collect logged in user data - it is recommended to provide granular permissions for each feature used in ACC.

Though the "Local Admin" or "Local System" rights will also grant access to this data, it is not recommended to deploy the ACC Agent with this data unless also using features that require such high privileges (for example, using the Agent Self-Upgrade feature).

No additional permissions are required on Mac devices to collect logged on users.

Payload format The user information is added to the check response output in the "assigned_to_users" section of the payload. This payload section contains different information for Windows vs Mac:

Windows:

"assigned_to_users": {"logged_in_users": [],"computer_system_username":""} Mac:

"assigned_to_users": {"logged_in_users": []} Within this section, there are two subsections:

1. logged_in_users - this attribute is collected via the "osquery" tool packaged within the agent on both Windows and Mac OS using the following query:

For Windows: SELECT l.user FROM logged_in_users l JOIN users u ON l.sid = u.uuid WHERE u.type != 'special' For Mac: SELECT distinct(l.user) FROM logged_in_users l JOIN users u ON l.user = u.username 2. computer_system_username - this attribute is collected via WMI/CIM Query on Windows - depending if wmic is disabled on the OS:

wmic COMPUTERSYSTEM GET USERNAME Get-CIMInstance -ClassName Win32_ComputerSystem Example payload:

"assigned_to_users":{"logged_in_users":["example.employee1","example.employee2"],"computer_system_username":"example.employee1","ad_domain":"company"} Matching collected Username to sys_user The users from the payload are evaluated to find a match in the sys_user table in the instance.

Default system behaviour searches against the "User ID" [user_name] field on the [sys_user] table and ignores ad_domain information, first checking the "computer_system_username" then the "logged_in_users".

The following system properties are used to control this behaviour:

System Properties The following System Properties are considered when processing "Assigned To" data in Agent Client Collector for Visibility Content.

sn_acc_vis_content.set_assigned_to True or False - used to determine if ACC-VC will override existing "Assigned To" data sn_acc_vis_content.assigned_to_user_order Used to lookup "logged_in_users" or "computer_system_username" first, based on preference Valid values are either of the below: "computer_system_username,logged_in_users" "logged_in_users,computer_system_username" Note: If this property is deleted, empty, or any value other than the two valid values above the assigned_to data will not be populated sn_acc_vis_content.column_name_for_user_mapping Only used for querying users on Windows devices Used to determine which column on "sys_user" to query Setting this property to any value will additionally add the "ad_domain" information to the query Users on Macs ignore this property - they only use "User ID" [user_name] field Example matching logic, using the sample payload:

"logged_in_users":["example.employee1","example.employee2"] "computer_system_username":"example.employee1" "ad_domain":"company" Windows:

For each scenario, the system would perform the following queries in order based on the section of the payload used.

If a match is found at any point, use that sys_user record.

If no match is found, no user can be used and therefore "Assigned To" is not populated.

Note: it is common for queries to repeat, as the same username is likely in both sections on Windows.

Scenario 1: Default system behaviour

Set username query value to the username only.

Query first for "computer_system_username", then each of the values in "logged_in_users".

Query to "User ID" [user_name] field on sys_user table for value "example.employee1" Query to "User ID" [user_name] field on sys_user table for value "example.employee1" Query to "User ID" [user_name] field on sys_user table for value "example.employee2" Scenario 2: Changing system property "sn_acc_vis_content.assigned_to_user_order" to value: "logged_in_users,computer_system_username":

Set username query value to the username only.

Query first for each of the values in "logged_in_users", then for "computer_system_username".

Query to "User ID" [user_name] field on sys_user table for value "example.employee1" - from the "logged_in_users" section Query to "User ID" [user_name] field on sys_user table for value "example.employee2" - from the "logged_in_users" section Query to "User ID" [user_name] field on sys_user table for value "example.employee1" - from the "computer_system_username" section Scenario 3: Changing "sn_acc_vis_content.column_name_for_user_mapping" to value: "u_samaccountname":

This is an example to represent a custom field with label "sAMAccountName" to collect sAMAccountName from an LDAP sync, if the original user_name field does not match sAMAccountName.

Additionally, in this scenario the value of "sn_acc_vis_content.assigned_to_user_order" would be reset to value: "computer_system_username,logged_in_users".

Set username query value to the username + the value of ad_domain from the payload using an OR query and two username formats:

Format 1: domain\username

Format 2: username@domain

Query to "sAMAccountName" [u_samaccountname] field on sys_user table for values "company\example.employee1" OR "example.employee1@company" Query to "sAMAccountName" [u_samaccountname] field on sys_user table for values "company\example.employee1" OR "example.employee1@company" Query to "sAMAccountName" [u_samaccountname] field on sys_user table for values "company\example.employee2" OR "example.employee2@company" Mac:

Though the properties are also set for Mac, they don't really apply. There will only be a logged_in_users section, domain is never used, and the query always is against "User ID" [user_name] field. Therefore, all scenarios are the same for Mac.

Query to "User ID" [user_name] field on sys_user table for value "example.employee1" - from the "logged_in_users" section Query to "User ID" [user_name] field on sys_user table for value "example.employee2" - from the "logged_in_users" section Troubleshooting If the assigned_to field is not set for the host CI, there are a few possible reasons, but they ultimately are always one of the following two issues:

1. Username data not collected

2. Username data is collected, but not updated on CI record

Some common examples of each - these lists are not exhaustive, but are good places to start troubleshooting:

Username data not collected is commonly for one of the following reasons:

No users were logged in at the time of check execution Please note that check execution on an agent will occur as long as the device is powered on and connected, there is no requirement for a user to be logged in and therefore it is possible that no users were logged in at the time of check execution Insufficient permissions to collect logged in users Please note that the default "servicenow" user created during installation of ACC on Windows will not have sufficient permission to collect logged in users. Review above permissions section for further information. Command produces no results "logged_in_users" are collected from osquery, and "computer_system_username" is collected by direct windows commands these commands may fail to produce results for various reasons, including but not limited to: osquery temp folder file permission issues (see KB2579296 ) asset sync failure wmic deprecation (note, wmic deprecation has been addressed in v1.5.0 of Agent Client Collector for Visibility Content - make sure that there are no skipped upgrades) Check execution failure for another reason (e.g., timeout, or failure to launch check entirely)

Username data may be collected but not updated on CI record for the following common reasons:

Incorrect CI type: The CI must be a computer, such as a desktop or laptop - the value is not set for Server class CIs or customer OS Classes No matching sys_user: There must be an associated sys_user in the instance to match to There must also be a valid field to match to Incorrect configuration of system properties Review System Properties section above The value from the payload must match a field on the sys_user table - consider how the system properties are evaluated to make these queries Is the "sn_acc_vis_content.set_assigned_to" set correctly? Reconciliation Rules Business rules It's not uncommon for Business Rules to block updates to CIs, possibly even aborting transactions for reasons unrelated to "Assigned To" value Payload Processing failure Check system logs, and appnode localhost logs (Node Log File Browser) during the payload processing to identify why the payload may have failed to update Look for TypeError, or NullPointerException Consider debugging the payload in the script debugger Audit History If auditing this field, check if the field was correctly set at the time of payload processing but updated afterwards by an integration/scheduled job/user Further information and troubleshooting steps can be found in the following KB:

ITOM Agent Client Collector documentation material