.. _system-user-audit: System User Audit ----------------- .. _25.3|VOSS-1464: .. _25.4|EKB-27247: .. _25.4|EKB-27248: Overview ............. The system user audit feature addresses user and service association issues in VOSS. The ``data/User`` status may not be synchronized with the current services such as LDAP, Cisco UCM, Cisco Unity Connection (CUC), MS 365, Webex Teams and MS Teams assigned to users in the system at a selected hierarchy. For example: * Some users are absent from the system. * Users are not properly associated with the services present in the system. * Users exist without corresponding service associations. * Users are located at a site that is different form their associated service users. Such issues can result in performance degradation, inaccurate workflows and incorrect license audit data. VOSS provides both a command and a scheduled action to carry out this audit and address these issues. .. note:: * The *scheduled* action is available *only* if the global system level settings for VOSS called **Enable or disable system user audit** is enabled. By default, this setting is *not* enabled. The action is however available on the default **System Configuration** dashboard for an unscheduled run. When *cancelling* an unscheduled action, the cancelled transaction may take some time to show as done in the transaction log, but you can continue using the system. * To access the feature, the administrator's Access Profile must contain Create and Read permissions for the ``view/SystemUserAudit`` model type. .. rubric:: Related topics .. raw:: html See: Settings. .. raw:: latex See Settings under System Functions in the Core Feature Guide. How system user existence is determined '''''''''''''''''''''''''''''''''''''''''' When System User Audit runs, VOSS determines whether a system user (``data/User``) exists by evaluating both configured user field mappings and configured *MultivendorUserMappingMacros*. The audit does not rely on a single username field comparison. Instead, it evaluates multiple possible identifiers derived from the device user model (for example, MS 365 or MS Teams users) using configured *MultivendorUserMappingMacros* at the relevant hierarchy levels. This allows VOSS to correctly identify users in scenarios where the system username differs from the device or vendor-specific username, such as when the ``data/User`` username does not match the *User Principal Name* (UPN) of an MS Teams or MS 365 user. .. note:: Vendor-specific username fields (for example, ``username_cucm`` or ``username_ms_teams``) are populated and maintained by provisioning and import workflows. System User Audit uses these fields as part of its evaluation logic but is not responsible for their initial population. System User Audit command and schedule ........................................ The **System User Audit** link on the default **System Configuration** dashboard, **License Audit Setup** panel, provides an option to run a user audit or report on users and their associated services. The **System User Audit Report** link also lists generated report files. Run a system user audit '''''''''''''''''''''''' 1. In the VOSS Admin Portal, choose the hierarchy at which the task is to be carried out. .. important:: Running the audit tool at a high level hierarchy (many users at or below) can severely impact performance. It is strongly advised to initially only run reports on hierarchies - selecting hierarchy levels with fewer users, such as at site level. The reports can then be inspected to determine the number of changes required. A **Confirmation** option prompts the administrator to first verify a task. .. note:: System User Audit evaluates configured *MultivendorUserMappingMacros* in addition to User Field Mapping configuration when determining whether a system user exists. If no direct username match is found using User Field Mapping, the audit uses *MultivendorUserMappingMacros* to resolve possible matches between system users and device users. This reduces false audit failures and duplicate user creation attempts in environments where usernames differ across systems. 2. Choose **Create a Report** if *only* a ``.csv`` file report is required for download. If this option is selected, no changes are made to the users and system. See also *System User Audit report* below. 3. For the **Confirmation** dropdown, select "Yes, I confirm that the System User Audit can be run." 4. Click **Save** to carry out the task. .. note:: * System User Audit does not delete users from ``data/User``. * If ``data/User`` instances are moved to align with services and more than one device is misaligned, the user is moved to the hierarchy of the device with the highest priority. * If the system user audit transaction fails during the processing of an individual user, the associated sub-transaction will log this and roll back that sub-transaction, while continuing to process sub-transactions for subsequent users. System User Audit report '''''''''''''''''''''''''' Running **System User Audit** and can also simply create a report (**Create Report** checked on the input form) The generated report can be inspected to determine audit output, and is available from the list of files shown at the tool: **File Management**, where it can be downloaded. Audit results may reflect operations determined through *MultivendorUserMappingMacros*. For example, a user may be added, updated, or moved even when no direct username match exists, provided that a configured macro resolves the system user to a device user. The report file format is: ``user_audit_report _<%Y%m%d_%H%M%S>.csv`` The file contains headers: * ``username`` * ``hierarchy`` * ``operation`` * ``issue`` Behavior when user mappings change '''''''''''''''''''''''''''''''''''' System User Audit dynamically evaluates user mappings each time it runs. If User Field Mapping or *MultivendorUserMappingMacros* are added, removed, or modified after a previous audit run, subsequent audits will re-evaluate system user existence and alignment based on the updated configuration. This means that: * Users not previously identified may be added or updated * Existing users may be realigned to the correct hierarchy * Audit results may differ between runs if mapping configuration changes Automatic execution schedule .................................. The system user audit runs daily at 1:30 AM UTC, the same time as the license counting service. See :ref:`license-counting-process-commands`. .. note:: The execution time is not configurable. When the system user audit runs, a CSV file similar to the report is generated (``user_audit_operations_executed_``). This report allows administrators to see what operations were executed in the background every 24 hours.