Configuring audit trails

Use NexJ Studio to configure audit trails. Audit trails record actions that users perform in NexJ CRM.

Use event audit trails when you want to log create, update, and delete actions for all auditable objects in the system. For example, enable event audit trails to log user actions such as creating, modifying, and deleting contacts.

Use attribute audit trails when you want to log create, read, update, and delete actions only for object attributes that you specify. For example, configure attribute audit trails to log the history of all changes to a contact's name to meet legal and business requirements.

To enable event audit trails for your deployments, specify the following audit mode in the environment file:

eventAudit
Specify true to log create, update, and delete actions that users perform on objects, for example, creating or deleting a lead. This mode logs actions for all auditable objects in NexJ CRM. For update actions, original and changed values are recorded.

To enable attribute audit trails for your deployments, you specify the object attributes that you want to audit. Then, you specify one or both of the following audit modes in the environment file:

readAudit
Specify the audit level for read actions that users perform on objects, for example, viewing a contact. 

You can specify one of three read audit levels:

access
Logs the object that was read.

attributes
Logs the object and object attributes that were read.

values
Logs the object, object attributes, and attribute values that were read.

To disable read audit, specify none.

You can modify the default list of objects to audit based on attributes selected for read audit in the NexJ model.

updateAudit
Specify true to log create, update, and delete actions that users perform on object attributes, for example, changing a contact name. You can modify the default list of objects to audit based on attributes selected for update audit in the NexJ model. Original and modified attribute values are recorded for update actions.

You can also enable user login auditing to log details about NexJ CRM user logins in the NexJ Audit database.

Info

Event audit trails are enabled by default. Attribute audit trails are disabled by default.

Audit trails display in the following locations:

• Attribute audit trails display in the Audit Trail tab on applicable workspaces in NexJ CRM.

• Event audit trails display on the Audit Trail page in NexJ Admin Console.

For more information, see Audit trails.

Configuring object attributes for read and update auditing

In NexJ Studio, you can specify attributes to log in the audit trail for read and update auditing.

When the readAudit or updateAudit modes are enabled for a deployment, you can specify the attributes to audit or modify the default attributes that are audited. For example, you can log when tasks are read or updated. After selecting an attribute for read and update auditing, auditing is triggered when a read, create, update or delete event is executed against the object associated with the attribute.

To select the objects to audit in your deployments:

1. In NexJ Studio, navigate to the Business Model Layer and, in the Classes tab, open the Act class.
2. To select attributes to audit:
   1. In the Attributes tab, in the Attributes area, select an attribute to audit.
   2. In the Security subtab, set the values for Read Audit, Update Audit, or both to true.
   3. Repeat these steps to enable auditing for another attribute.
3. Click the Save button

   

   to save your changes to the class.

The attributes to audit in your deployment are selected. When you deploy your application, if the readAudit or updateAudit modes are enabled, user actions for the selected object types are audited when they are performed in NexJ CRM.

If your NexJ application is currently running, you must redeploy the application for changes to take effect.

Changing the audit mode for a deployment

Change the audit mode for a deployment to enable auditing, change what types of user actions to audit, or disable auditing in a single deployment of NexJ CRM or NexJ Admin Console.

To enable event audit trails for your deployments, specify the following audit mode in the environment file:

eventAudit
Specify true to log create, update, and delete actions that users perform on objects, for example, creating or deleting a lead. This mode logs actions for all auditable objects in NexJ CRM. For update actions, original and changed values are recorded.

To enable attribute audit trails for your deployments, you specify the object attributes that you want to audit. Then, you specify one or both of the following audit modes in the environment file:

readAudit
Specify the audit level for read actions that users perform on objects, for example, viewing a contact. 

You can modify the default list of objects to audit based on attributes selected for read audit in the NexJ model.

updateAudit
Specify true to log create, update, and delete actions that users perform on object attributes, for example, changing a contact name. You can modify the default list of objects to audit based on attributes selected for update audit in the NexJ model. Original and modified attribute values are recorded for update actions.

The audit mode determines the types of user actions that are recorded in an audit trail. You can specify event, read, and update audit modes. Each mode logs the date and time of the action, the name of the user who performed the action, and additional information depending on the audit mode.

You cannot specify different read and update audit settings for different deployments. Read and update audit settings for objects apply to all enabled deployments.

To change the audit mode for a deployment:

1. In NexJ Studio, navigate to the Deployment layer and, in the Environments tab, open the environment in which to change the audit mode.

2. In the Source tab, edit the <Environment> tag and add any of the following attributes: eventAudit, readAudit, updateAudit
   For example, to set the audit mode to log all read and update actions for your deployment, the attribute values should look similar to the following: 
   <Environment ... readAudit="values" updateAudit="true">

3. Click the Save button 

   

   to save your changes to the environment.

The audit mode for your deployment is changed. When you deploy your application, user actions in NexJ CRM are audited based on the specified audit modes.

If your NexJ application is currently running, you must redeploy it for changes to take effect.

You can use the Admin Console to specify a time period in which to fold multiple reads on an object into a single read audit record. For more information, see Working with audit trails in NexJ Admin Console.

Changing the audit mode for all deployments

Change the audit mode for your deployments to enable auditing, change what types of user actions to audit, or disable auditing in all deployments of NexJ CRM or NexJ Admin Console.

The audit mode determines the types of user actions that are recorded in an audit trail. You can specify event, read, and update audit modes. Each mode logs the date and time of the action, the name of the user who performed the action, and additional information depending on the audit mode.

To enable event audit trails for your deployments, specify the following audit mode in the environment file:

eventAudit
Specify true to log create, update, and delete actions that users perform on objects, for example, creating or deleting a lead. This mode logs actions for all auditable objects in NexJ CRM. For update actions, original and changed values are recorded.

To enable attribute audit trails for your deployments, you specify the object attributes that you want to audit. Then, you specify one or both of the following audit modes in the environment file:

readAudit
Specify the audit level for read actions that users perform on objects, for example, viewing a contact. 

You can modify the default list of objects to audit based on attributes selected for read audit in the NexJ model.

updateAudit
Specify true to log create, update, and delete actions that users perform on object attributes, for example, changing a contact name. You can modify the default list of objects to audit based on attributes selected for update audit in the NexJ model. Original and modified attribute values are recorded for update actions.

To change the audit mode for your deployments:

1. In NexJ Studio, navigate to the Resources layer and, in the Components tab, open the System.Auditor component.
2. In the Overview tab, in the area on the left, expand the Properties node.

3. For any of the following properties, update the Property Value field: eventAuditEnabled, readAuditLevel, updateAuditEnabled.

4. Click the Save button

   

   to save your changes to the component.

The audit mode for your deployments is changed. When you deploy your applications, user actions in NexJ CRM are audited based on the specified audit mode. If your NexJ applications are currently running, you must redeploy them for changes to take effect.

Enabling user login auditing

You can enable user login auditing to track login activity of NexJ CRM users. User login auditing records the name of the user who logged in, IP address of the machine used to log in, and time of the login for audit and tracking purposes. User login information is stored in the NexJ Audit database.

Info

By default, user login auditing is not enabled.

To enable user login auditing for NexJ CRM:

1. In NexJ Studio, navigate to the Deployment layer and, in the Environments tab, open the environment in which to enable user login auditing.
2. In the Source, in the <Environment> tag, add the authAudit="true" attribute, as shown in the following example:
   <Environment ... authAudit="true">
3. Click the Save button

   

   to save your changes to the environment.

User login auditing is enabled for your deployment. When you deploy your application, details about NexJ CRM user logins are stored in the LGAuthenticationAuditLog table of the NexJ Audit database.

If your NexJ application is currently running, you must redeploy it for changes to take effect.

Troubleshooting the creation of event audit trails

An event audit is only triggered when the event is called from an RPC call. If you have enabled auditing for a specific event, and the audit trail isn't being created, then you can increase logging for GenericServer. With increased logging you can observe all of the RPC calls being made. If the audited event isn't appearing as an RPC request, then you would need to change your code accordingly.

-Dlog4j.logger.genericServer.name=nexj.core.rpc.GenericServer
-Dlog4j.logger.genericServer.level=ALL

Testing event audit trails

To test event auditing from the Scheme Console or a unit test, an RPC request needs to be made, and sent to the server. Calling an event directly from the Scheme Console will not trigger auditing. Below is an example of calling the read event from SysReader. The arguments of the event become fields in the request message.

(define server ((invocation-context)'getComponentInstance "Server.Generic"))
(define request (nexj.core.rpc.Request'new))

(request'commit #f)
(request'addInvocation
   (message
      (: :class "SysReader")
      (: :event "read")
      (: class 'TelcomType)
      (: where '(not (null? (@ name))))
   )
)
(server'invoke request)