User activity history auditing
User activity history auditing provides functionality to audit user actions within cases and in the portal management area. System administrators can use settings on the Portal Options page to enable activity history auditing for the portal management area and for newly created cases.
Note: This feature is not available for existing cases.
Like coding history, the activity history audit records are stored in Elasticsearch. This first release provides the ability to capture and store the audit history, and system and portal administrators can use new features in the Connect API Explorer to download activity history logs for analysis.
Important: This feature requires the user audit log service and Elasticsearch to be deployed in the portal environment.
Providing a broader scope of auditing than coding history, which captures audit records related to actions that users take on documents and entity records, the new activity history auditing captures audit records for all other types of user activities throughout Nuix Discover.
Here are some examples:
Case-level auditing:
When a user uploads or downloads files
When a user downloads a report
When a user deletes a document or entity
When a user images a document
When a user changes the security for a feature or object
When a user creates or updates objects such as fields, issues, binders, and so forth
Portal-level auditing:
When a user logs in or out of the application
When a user adds, updates, deletes, or reinstates a user account
When a user adjusts portal or case options settings
After a system administrator enables this feature, portal or system administrators can use the Nuix Discover Connect API to download audit history logs for analysis in a tool such as Splunk.
Note: You can currently access the log files through the Nuix Discover Connect API, but not through the Nuix Discover user interface.
High-level workflow
The high-level workflow is as follows:
Step 1: Enable activity history auditing for portal management activities or case activities.
A system administrator enables the feature for the portal management area or the newly created cases in a portal.
Step 2: Configure the user audit log download repository.
A system administrator configures the file repository to use as a staging location for user audit log downloads.
Step 3: A portal or system administrator uses the Connect API Explorer to do the following:
Step 3.a.: Run mutation to gather user audit log data and generate an RPF ID.
Step 3.b.: Run query to check status of RPF job and return file path to zip file for download.
Step 3.c.: Download user audit log files.
Enable and configure the user activity history auditing feature
A system administrator must do the following on the Portal Management > Settings page:
Enable activity history auditing for portal management activities or case activities
Configure the user audit log download repository
Enable activity history auditing for portal management activities or case activities
A system administrator can enable activity history auditing for the portal management area and for new cases.
To enable the activity history audit feature for the portal management area:
Warning: Once you enable this option, you cannot disable it.
On the Portal Management > Settings > Portal Options page, select Enable activity history audit for portal management activities.
Click Save.
To enable the activity history audit feature for newly created cases:
Note: You cannot enable activity history auditing for existing cases.
On the Portal Management > Settings > Portal Options page, select Enable activity history audit in new cases.
Click Save.
Configure the user audit log download repository
A system administrator configures the user audit log download repository.
Caution: This should be a dedicated repository for user audit log download use only and should not be assigned to any organizations or cases.
To configure the user audit log download repository:
On the Portal Management > Settings > Portal Options page, in the User audit log download repository box, enter the name of the internal File Repository where user audit log files will be staged for download.
Retrieve the user audit log data using the Connect API Explorer
System and portal administrators can download the activity history user audit logs from specific areas using the auditDownloadLogSubmit mutation based on their user role.
System Administrators: Can access user audit logs for all cases and the portal management area.
Portal Administrators: Can access user audit logs for all cases in their organization.
Using the Connect API Explorer, system or portal administrators must do the following to retrieve the user audit log data:
Run mutation to gather user audit log data and generate an RPF ID
Run query to check status of RPF job and return file path to zip file for download
Run mutation to gather user audit log data and generate an RPF ID
The auditDownloadLogSubmit mutation submits a job request that gathers the user audit log files and packages them into a .zip file for download. This job gathers audit records from elastic indexes based on specified parameters, and generates log files with the requested data, which is packaged into the .zip file and staged in the network share repository configured by a system administrator.
Note: If there is no audit history data for the date range specified in the mutation, then no logs are generated.
The following list describes the input parameters for running the auditDownloadLogSubmit mutation.
Required fields:
startDate: Audit records that fall on or after this date are included in the results.
endDate: Audit records that are earlier than this date are included in the results.
includePortal: If set to True, portal activity history audit records are included in the download logs.
Note: Only system administrators can download portal activity user audit logs when set to True. Portal administrators, even when set to True, do not have access to download portal activity history user audit logs.
Optional fields:
caseIds: To generate logs for specific cases, enter the caseIds as a comma-separated list surrounded by square [ ] brackets. If no caseIds are specified, then the logs are generated for all cases available to the requesting user. For system administrators, this would be all cases in the portal. For portal administrators, this would be all cases in their organization.
userIds: To generate logs for specific users, enter the userIds as a comma-separated list surrounded by square [ ] brackets. If no userIds are specified, then the logs include audit data for all users who have audit records that meet the other parameters in the mutation request.
deleteDaysExpiredLogFiles: When submitting a mutation request for logs, if this parameter is not included, then, by default, older log files that are 3 days old or older are deleted from the staging repository. Enter a different value to specify a different number of days to delete expired logs.
deleteOldLogFiles: When submitting a mutation request for logs, if this parameter is not included, then, by default, older log files are deleted from the staging repository based on the deleteDaysExpiredLogFiles setting. If you do not want previous logs to be deleted, then set this value to False.
The following describes the output data results from the auditDownloadLogSubmit mutation.
rpfJobId: This field should be included for retrieving the job ID. This job ID is needed for retrieving the download repository URL location.
The following mutation example generates logs for all cases available to the requesting user and includes audit data for all users who have audit records within the specified date range. The example does not not include the portal activity history audit records.
Sample mutation:
mutation MySampleMutation {
auditDownloadLogSubmit(input:
{
includePortal: false,
startDate: "04/01/2021",
endDate: "04/26/2021",
})
{
rpfJobId
}
}
The following mutation example generates logs for the two specified cases and includes audit data for the two specified users who have audit records within the specified date range. The example also includes the portal activity history audit records for those users.
Sample mutation:
mutation MySampleMutation {
auditDownloadLogSubmit(input:
{
includePortal: true,
startDate: "06/01/2021",
endDate: "06/03/2021",
caseIds: [1048, 1],
userIds: [243, 32]
})
{
rpfJobId
}
}
The following example shows the results returned for either of the above sample mutations. The returned rpfJobId is used in the auditDownloadLogStatus query for retrieving the repository location of the zip for download.
Sample results:
{
"data": {
"auditDownloadLogSubmit": {
"rpfJobId": 27971
}
}
}
Note: If the user submits a mutation including caseIds for cases that do not have auditing enabled, a warning message appears containing those IDs in the task output stating: Warning: These case IDs do not have coding history audit enabled: [IDs] or Warning: These case IDs do not have case activity audit enabled: [IDs]. If the user submits a mutation with the includePortal field set to True, but the portal does not have auditing enabled, an error appears in the task output stating: Warning: Portal management activity audit is not enabled.
Run query to check status of RPF job and return file path to zip file for download
The auditDownloadLogStatus query checks the job status and obtains a file path for downloading user audit log files. When the mutation job is complete, the query returns the file path to the staged zip file on the repository that contains the logs for download.
The following list describes the parameters for running the auditDownloadLogStatus query.
Required fields:
rpfJobId: Enter the rpfJobId returned from the auditDownloadLogSubmit mutation.
The following list describes the output data results from the auditDownloadLogStatus query.
filePaths: When running the query, be sure to include filePaths as an output field so that it will return the path to download the zip with the logs when the job is complete.
status: Optionally include Status as an output field to return the current status of the job.
Sample query:
query MySampleQuery {
auditDownloadLogStatus(rpfJobId: 27971) {
status
filePaths
}
}
The query returns the current status of the mutation job, including the overall job status, of Processing, Succeeded, Succeeded with warnings, or Failed. When the job is complete, the query returns the zip file path to be used in an HTTP GET call for downloading the log files.
Sample status query results:
{
"data": {
"auditDownloadLogStatus": {
"status": "Succeeded",
"filePaths”: [
“27971\\Logs_27971_1620968181.zip”
]
}
}
}
Download user audit log files
User audit log files can be downloaded only by the user who initiated the job through the auditDownloadLogSubmit mutation.
You need the following items to download the user audit log files:
Your Nuix Discover API token. Retrieve this information from the Portal Home > User Administration > Users > API Access page.
The file path from the auditDownloadLogStatus query.
To retrieve your Nuix Discover API token:
On the Portal Home page, from the user name menu on the navigation bar at the top of the page, select Account Settings.
On the Account Settings page, in the navigation pane, select API Access.
On the API Access page, under API token, click Copy API token.
The application copies the token to your local clipboard for pasting when needed.
To download the user audit log files for analysis, in the third-party tool of your choice, make an HTTP GET call to the api/auditdownload endpoint to download the logs. Enter your API token and the file path returned from the auditDownloadLogStatus query. For example: GET http://allinone/Ringtail-Svc-Portal/api/auditdownload?filePath=27971\\Logs_27971_1620968181.zip.