NexJ Add-In security integration and configuration

You can customize the security functionality in NexJ Add-In to match the specific needs of your deployment.

Security integration overview

Functional requirements

When filing an email or creating a task from an email using NexJ Add-In, the user can:

Control which NexJ CRM users have view and edit access to the email or task.
Specify view security and edit security options independently.
Set public, group, or private security levels.

Setup and prerequisites

To enable a NexJ Add-In user to use this functionality, ensure that the following prerequisites have been met:

Set the ShowSecurityDialog registry key to 1. (In the Registry Editor, this key is located at HKEY_CURRENT_USER > Software > NexJ > Office Add-In. The key type is REG_DWORD.)
Ensure that the user can connect to the NexJ CRM server.

Technical overview

The following diagram shows the request-response flow between NexJ Add-In and the security model. The model does the following when the NexJ Add-In user issues the File With command and then clicks the Security button in the Save Email to NexJ CRM dialog:

Provides NexJ Add-In with information about the type of security supported for the specified object type.
If "group" security level is selected, provides the add-in with the list of groups that are available to the user.
Commits the object to the database with the selected security options.

NexJ Add-In obtains the user-selected security arguments using the getSecurityOptions and getSecurityDetail methods. It then passes the arguments to the createEmail method.

Requests and responses between NexJ Add-In and the security model

This diagram uses email as the object type. Security for tasks is also supported, using the createTaskFromMail method.

Security integration core methods

The following methods are used throughout the NexJ Add-In security process. The following method descriptions include customization points that can be used by clients to ensure that NexJ Add-In supports their specific security models. When present, the args parameter represents a variable-length collection that can optionally be supplied to the method.

getSecurityOptions

Syntax

`SystemPreference.getSecurityOptions(string class)`

Security-relevant parameters
class: string

Returns
Security options available for the class: message

Description
This is the first security API call and reflects step 2 from the request-response workflow diagram. The default set of returned messages corresponds to the most frequently used security options.

In order to customize this method, the client can add or modify the values in the SecurityTypeEnum enumeration and then modify the messages returned by the getGroupSecurityOptions and getCustomSecurityOptions methods.

Workflow for the getSecurityOptions method

getSecurityDetail

Syntax

`SystemPreference.getSecurityDetail(string class, string category, string selection, list args)`

Security-relevant parameters

class: string
category: OID; Example values: (oid "GROUP" "VIEW"), (oid "GROUP" "EDIT")
selection: OID; Example values: (oid "GROUP" "VIEW" "1"), (oid "GROUP" "EDIT" "1")

Returns
User groups: collection

Description
The second request from the request-response workflow diagram. If group security is specified, this method provides the add-in with a list of groups available for the specified class, category, and selection values. In order to support client customization, this method needs to be updated to include a call to a new getCustomSecurityDetail method.

Workflow for the getSecurityDetail method

createEmail

Syntax

`Email.createEmail(fromEmail, toEmail, forEntities, assignToEntities, msgId, emailDate, status, clientVersion, list args)`

Security-relevant parameters
The following parameters are specified through the parameter:

viewSecurityType: integer; Example values: 0 (public), 1 (group), 2 (private)
editSecurityType: integer; Example values: 0 (public), 1 (group), 2 (private)
security: message consisting of the category OID and selection OID specified in the getSecurityDetail method described above

Returns
Email object

Description

This is the third call required to file an email and corresponds to step 8 in the request-response workflow diagram.

The setSecurity action in this method handles the security aspect of the request from the add-in. It sets the email's security options according to whether the security message is present in the args parameter:

If the args parameter does not contain a security parameter, the view and edit security is set to public.
If the selection parameter in the getSecurityMessage method specifies group security, the view and edit security is set to the group ID specified in the security message.
If the selection parameter in the getSecurityMessage method specifies private security, the securityRule attribute is set accordingly. (The securityRule attribute value depends on how the Access Control List (ACL) security model is defined and implemented for the client.)

createTaskFromMail

Syntax

`Task.createTaskFromMail(assignToEntities, msgId, clientVersion, list args)`

Security-relevant parameters
The following parameters are specified through the args parameter:

viewSecurityType: integer; Example values: 0 (public), 1 (group), 2 (private)
editSecurityType: integer; Example values: 0 (public), 1 (group), 2 (private)
security: message consisting of the category OID and selection OID specified in the getSecurityDetail method described above

Returns
Task object

Description
If the user is creating a task from an email, rather than saving an email, this corresponds to step 8 in the request-response workflow diagram.

The setSecurity action for this method mirrors the setSecurity action for the createEmail method.