ACC-V: Trouble shooting guide for SAM Total Usage Metric - Support and Troubleshooting

ACC-V: Trouble shooting guide for SAM Total Usage Metric Summary .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: ; } } .kb-wrapper{font-family:Lato,sans-serif;font-size:12pt;line-height:1.7;color:#000;max-width:100%} .kb-wrapper p{margin:0 0 12px 0}

Troubleshoot issues with Software Asset Management (SAM) Software Total Usage metrics in the Agent Client Collector (ACC) for ITOM Visibility Content plugin. This article covers common errors, data collection failures, and staging pipeline issues, and describes how to verify that usage data flows correctly from Windows endpoints to your ServiceNow instance.

Facts .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: ; } } .kb-wrapper{font-family:Lato,sans-serif;font-size:12pt;line-height:1.7;color:#000;max-width:100%} .kb-wrapper p{margin:0 0 12px 0} .kb-wrapper ul{margin:0 0 12px 0;padding-left:24px} .kb-wrapper li{margin-bottom:8px} .kb-wrapper strong{font-weight:700;color:#032D42} .kb-wrapper code{background:#e6f0f5;color:#032D42;border:1px solid #b8cfd8;padding:1px 5px;border-radius:3px;font-size:11pt;font-family:'Courier New',monospace}

SAM Total Usage Metric collects process-level usage data from Windows endpoint devices only. Linux endpoints and Windows servers are not supported. Modifying policy conditions to target Windows servers does not produce reliable results and is not supported. The ACC for ITOM Visibility Content plugin ( com.sn_acc_vis_content ) and SAM Premium plugin ( com.snc.samp ) must both be active for usage data to persist in the staging table. If either plugin is inactive, the staging handler returns silently with no error logged. Staging table: Software Usage Staging [ sn_acc_vis_content_sam_software_usage_staging ] Final table: Software Usage [ samp_sw_usage ] Release .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: ; } } .kb-wrapper{font-family:Lato,sans-serif;font-size:12pt;line-height:1.7;color:#000;max-width:100%} .kb-wrapper p{margin:0 0 12px 0} .kb-wrapper code{background:#e6f0f5;color:#032D42;border:1px solid #b8cfd8;padding:1px 5px;border-radius:3px;font-size:11pt;font-family:'Courier New',monospace}

Agent Client Collector for ITOM Visibility Content ( com.sn_acc_vis_content )

Instructions .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: ; } } .kb-wrapper{font-family:Lato,sans-serif;font-size:12pt;line-height:1.7;color:#000;max-width:100%} .kb-wrapper p{margin:0 0 12px 0} .kb-wrapper ul,.kb-wrapper ol{margin:0 0 12px 0;padding-left:24px} .kb-wrapper li{margin-bottom:7px} .kb-wrapper strong{font-weight:700;color:#032D42} .kb-wrapper a{color:#032D42} .kb-wrapper h2{ font-size:14pt;font-weight:900;color:#032D42; border-bottom:2px solid #e8fce4;padding-bottom:5px; margin-top:32px;margin-bottom:14px } .kb-wrapper h3{ font-size:12pt;font-weight:900;color:#032D42; border-bottom:1px solid #e8fce4;padding-bottom:3px; margin-top:20px;margin-bottom:8px } .kb-wrapper code{ background:#e6f0f5;color:#032D42;border:1px solid #b8cfd8; padding:1px 5px;border-radius:3px;font-size:11pt; font-family:'Courier New',monospace } .kb-wrapper pre{ background:#e6f0f5;color:#032D42;border:1px solid #b8cfd8; padding:12px 16px;border-radius:4px;font-size:10pt; font-family:'Courier New',monospace;overflow-x:auto; margin:8px 0 16px 0;white-space:pre-wrap;word-break:break-all } .kb-wrapper ol.steps{ list-style:none;padding-left:0; counter-reset:step;margin:10px 0 16px 0 } .kb-wrapper ol.steps > li{ counter-increment:step;padding-left:38px; position:relative;margin-bottom:10px } .kb-wrapper ol.steps > li::before{ content:counter(step);background:#032D42;color:#63DF4E; font-weight:900;font-size:10pt;width:24px;height:24px; border-radius:50%;display:inline-flex;align-items:center; justify-content:center;position:absolute;left:0;top:2px;line-height:1 } .kb-wrapper .callout-warning{ background:#fff4e0;border-left:4px solid #e6a817; padding:10px 14px;margin:12px 0 18px 0;border-radius:0 4px 4px 0 } .kb-wrapper .callout-warning p{margin:0} .kb-wrapper .callout-info{ background:#e6f4ff;border-left:4px solid #52B8FF; padding:10px 14px;margin:12px 0 16px 0;border-radius:0 4px 4px 0 } .kb-wrapper .callout-info p{margin:0 0 10px 0} .kb-wrapper .callout-info p:last-child{margin-bottom:0} .kb-wrapper .callout-info ol.steps{margin:10px 0 10px 0} Table of Contents SAM background policy errors on Windows Verify MID Server and agent status Verify osqueryd is running on target endpoints Verify the osqueryd installation path Verify osqueryd configuration files Validate osqueryd output SAM discovery policy errors on Windows Verify the marker.json file Data not persisting in the staging table Verify the SAM Premium plugin is active Check the agent payload Verify reclamation rules Verify process name matching Verify software installation record normalization Verify user mapping Understanding the data flow from payload to staging table Data not stored in the final table Verify the scheduled job is active and has run Check system logs for staging errors SAM folder not created Verify service account consistency Update osqueryd configuration files Add the background log check to the Enhanced Discovery policy Run Host data collection SAM background policy errors on Windows Verify the following when troubleshooting the SAM background policy.

Verify MID Server and agent status Confirm that the MID Server and ACC agent are running. If either is down, data collection cannot proceed.

Verify osqueryd is running on target endpoints Confirm that the osqueryd process is running on each target endpoint.

Verify the osqueryd installation path By default, osqueryd is installed at C:\Program Files\osquery . If osqueryd is installed at a different location, find the path to its logs folder and add it as a parameter to the check instance command in the SAM background policy:

sam_processor.rb --osquery_log=" " To update the check instance command:

Go to Agent Client Collector > Policies and open the SAM background policy. Select the check instance for sam_processor.rb . Update the command with the --osquery_log parameter pointing to the custom logs folder. Verify osqueryd configuration files Confirm that osquery.conf and osquery.flags are present and correctly configured in C:\Program Files\osquery . If you need to replace them, extract osquery.conf.txt and osquery.flags.txt from the attached configuration files, rename them by removing the .txt extension, and copy them to C:\Program Files\osquery , replacing the existing files.

For required parameter values, see Related Links.

Validate osqueryd output After completing the preceding configuration steps, start the osqueryd service. Confirm that osqueryd.snapshots.log is created at C:\Program Files\osquery\log and contains entries in the following format:

{"snapshot":[{"elapsed_time":"1097178","name":"System","pid":"4","start_time":"1656696357","system_time":"2145468","user_time":"0","username":"SYSTEM"}]} SAM discovery policy errors on Windows Verify the following when troubleshooting the SAM discovery policy.

Verify the marker.json file Confirm that marker.json exists at the following location, where is the profile of the user configured for ACC:

\AppData\Local\AgentClientCollector\SAM This file is updated automatically every five minutes and should contain data in the following format:

{"data": {}, "lastReadUnixTime": } If marker.json is not present, see SAM folder not created later in this article.

Data not persisting in the staging table Note: The staging table was renamed from sn_acc_visibility_sam_software_usage_staging to sn_acc_vis_content_sam_software_usage_staging in December 2023.

If usage data is not appearing in the Software Usage Staging [ sn_acc_vis_content_sam_software_usage_staging ] table, verify the following.

Verify the SAM Premium plugin is active Confirm that the SAM Premium plugin ( com.snc.samp ) is active. To check, go to System Definition > Plugins , search for SAM Premium , and verify the status is Active . If the plugin is not active, no data is written to the staging table and no error is logged. This is the most common cause of an empty staging table when checks appear to be running normally.

Check the agent payload Inspect the agent payload for the following entries under the SAM payload section:

Marker File does not exist will retry in the next run — see SAM folder not created . "unixTime": -1 — see SAM background policy errors on Windows . Verify reclamation rules Confirm that reclamation rules of type Total Usage Time exist and include all software products for which you want to collect usage data.

Go to Software Asset Management > Reclamation Rules . Confirm at least one rule with reclamation type Total Usage Time is active. Confirm all relevant software products are added to the rule. Verify process name matching The process names in the agent payload must match entries in either of the following tables:

Software Product Process [ samp_sw_product_process ] Software Installation [ cmdb_sam_sw_install ] If a process name does not match any entry in these tables, the staging handler skips that record without logging an error.

Verify software installation record normalization Confirm that records in the Software Installation [ cmdb_sam_sw_install ] table are normalized. Unnormalized records are not matched during staging.

Verify user mapping The user name in the agent payload must match a record in the User [ sys_user ] table. If no matching user record exists, create one for that account.

To check the field used for user resolution, go to System Properties and review the value of sn_acc_vis_content.column_name_for_user_mapping .

Understanding the data flow from payload to staging table When the ACC agent sends a SAM Advanced Discovery check result, the instance processes it through EnhancedDiscoveryHandler.persistSAMAdvancedStagingData() . For each process entry in the payload, the handler evaluates the following conditions in sequence. If any condition is not met, the entry is silently skipped — no error is logged:

The SAM Premium plugin ( com.snc.samp ) is active. The process name matches a record in Software Product Process [ samp_sw_product_process ]. The matched SAM product has an installation record in Software Installation [ cmdb_sam_sw_install ] for the reporting CI. A reclamation rule exists for the product in Reclamation Rules [ samp_m2m_rule_product ], unless the property sn_acc_vis_content.disable_sam_reclamation_rules_for_licensable_softwares is set to true . Because all skips are silent, an empty staging table does not necessarily indicate an error — it indicates that one or more of the preceding conditions were not met.

Data not stored in the final table If data is present in the Software Usage Staging table but is not appearing in the Software Usage [ samp_sw_usage ] table, verify the following.

Verify the scheduled job is active and has run Confirm that the SAM - Update Software Total Usage Metric scheduled job is active and has run recently.

Go to System Scheduler > Scheduled Jobs . Search for SAM - Update Software Total Usage Metric . Confirm the job is active and review the Last Run and Next Run fields. Check system logs for staging errors To check for script errors during staging processing:

Go to System Logs > System Log . Search for entries beginning with the following prefix: Exception in EnhancedDiscoveryHandler.persistSAMAdvancedStagingData() SAM folder not created If the AgentClientCollector\SAM folder is not created at \AppData\Local — and therefore marker.json is also missing — verify the following.

Verify service account consistency Confirm that the osqueryd and ACC services are running under the same user account. If they are running under different accounts, update one service so both use the same account.

Update osqueryd configuration files Add the required parameters to the osqueryd configuration files. For the specific parameters, see Related Links.

Add the background log check to the Enhanced Discovery policy Add samadvanced-background-log-check to the Enhanced Discovery policy.

Run Host data collection After completing the preceding steps, run Host data collection. The marker.json file should then be created for the ACC service account user.

Related Links .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: ; } } .kb-wrapper{font-family:Lato,sans-serif;font-size:12pt;line-height:1.7;color:#000;max-width:100%} .kb-wrapper ul{list-style:none;padding-left:0;margin:0} .kb-wrapper li{margin-bottom:10px} .kb-wrapper a{color:#032D42} .kb-wrapper .disclaimer{font-size:10pt;font-style:italic;color:#444;display:block;margin-top:2px;margin-left:0}

Configure osqueryd schedule for SAM Total Usage metrics Configure osqueryd logs for SAM Total Usage metrics Use Agent Client Collector with Software Asset Management Troubleshoot SAM Total Usage Metric in Agent Client Collector for Visibility Troubleshoot Agent Client Collector for Visibility Content