Who is this article for?

Ideagen EHSQ Enterprise or Decani Admins or Module Developer

A Module Developer license and Area access is required.

Before enabling any access control rules, it is important to understand the proper setup. Please take some time to carefully read through the following articles in full:

• Understanding security
• Understanding reporting authorities
• Configuring reporting authorities
• Understanding Record Access Control (RAC)
• Understanding data confidentiality
• Understanding classified information labels

In a module, all roles within that module automatically have the Access all objects property role. This lets users search for and open objects from that module. If you remove the Access all objects property role, it creates restricted access for that role.

When a role has restricted access, users with that role won’t be able to access the module’s objects unless they are assigned to the object in a workflow step. Once assigned, they will keep access to that object indefinitely as long as their user is active. So, the default access rule for restricted roles is based on workflow assignments.

If you want users with restricted access to have access based on rules other than the workflow assignments a module developer can enable special access control rules from the module builder Module tab or Access tab. 

Many roles across various modules have restricted access but do not currently have access control rules enabled. Please keep in mind that enabling access control rules for these existing modules will change how access works and affect which users can access existing objects.

We recommend making changes to existing roles only after thorough consideration and careful testing.

When access control rules are in place for a module each object will populate an access list, consisting of all the PersonIDs and TeamIDs, who have access to that object. 

During the Save process (or sub-process), the permission access list with person and team id's is placed in the database Permissions Table and fed to the application search engine. The permission access list is then used to build the session context for individual users when they log in and to drive what objects each user can search for and open.

Data Security Alert
Enabling this feature may grant access to objects, also known as records, and data to users who should not have it. On the other hand, it could also restrict access for users who should have it. 

There are a few ways a module could accidentally cause serious problems if access control isn't set up correctly. It's helpful to be aware of these potential issues and follow these best practices when configuring access control:

• Use access control rules only when roles, reporting authorities, and other settings can't achieve what you need. They shouldn't be used just for convenience.
• If the module doesn't require access control, it's best to leave it as is—everything will continue to work normally.
• Keep your access control setup as straightforward as possible. Simplicity is key.
• Make sure there is at least one role in the module with Access to all objects (such as Admin, Debug, or similar).
• Create a custom rule for each access control entry.
• Set up access rules that check the access expressions properly.
• When you change security settings, remember to manually save or update the object using Query Builder to apply changes to existing records.

Access control "Gotchas"

1. Access Control Rule setup can render records inaccessible to everyone if any of the following are true:
   1. DXL returns no IDs that are valid users/teams, rendering the record inaccessible to users with restricted access
   2. The record is created by a batch process or system user and has no security targets automatically defined
2. If an individual is not explicitly excluded by a single access entry, they may still gain access to a record if they are included in any one of the other access entries. This is because the access control list is an aggregation of all access list entries.
3. Anonymous users who create a record could grant unwanted access. As a rule, access control rules should not be used in a module where anonymous access is enabled.
4. For existing modules with saved search notifications that include attachments, disabling notification attachments will not currently remove the attachments from those existing notifications. This will need to be manually checked for and remedied until a process can be created to automatically notify builders and remove attachments.
5. Records without access control can still reference and display information from a record with access control. A common scenario would be displaying fields from a parent record onto the child record through a reference field.

Configuring access control rules

The Access all objects role property is the key that unlocks the capabilities of access control rules. Access rules for a module can be defined and applied to all roles in that module that do not have the Access all objects property.

Basic configuration steps

1. Determine which roles should have restricted access.
2. Remove the Access all objects role property from those roles.
3. Open the module's Security behaviors screen and add access rule entries (see "Creating Access Entries" below).
4. For each access rule define the Type and select an appropriate rule (see "Creating Access Rules" below)
5. For Persons or Teams entry types, specify a DXL Expression that will return a list of Person or Team IDs.
6. Add a new field (small text or picklist) for the Classified Information Label text. This text will be used to denote the data security or classification level (e.g. "Official Use Only", "Classified", "Personally Identifiable Information", etc.)
7. Map this new field to the Common Field called "Classified Information Label" (requires updating BI after the module is compiled).
8. If needed, disable search notification attachments in the Module Properties region in module builder (see "Search, Reporting, and Notifications" below)
9. Compile the module.
10. If needed, run all existing records through dirty objects to populate the Permissions Table and the Classified Information Label for each record.
11. Perform testing and verification using access-specific test scripts.

Creating Access Entries

As noted above in Default Behaviors, when there are no access entries for restricted access roles the default behavior is that All Assignees have access. Adding access entries overrides this default behavior and allows custom access lists to be built and for access to be granted by rules that are driven by other settings. There are four types of access entries: Persons, Teams, All, and All Assignees. The use cases for each are slightly different.

• Persons and Teams Access Types: Use these access types to build custom access lists for people or teams. These entries must include an expression. The expression is custom DXL that returns the list of persons (PersonIDs) and/or teams (TeamIDs).

  Expression Must Return At least One Value The expressions for Persons and Teams entries must return at least one valid Person or Team ID, otherwise a situation might be created where no one has access (see "Access Rules Best Practices" below).

• All and All Assignees Access Types: These access types cannot use expressions. Use these to grant access when the record meets certain defined criteria. For example, if you want "All" users with restricted access roles to have access to records that are not "Official Use Only" the records may have a flag or other setting that denotes which records are for "Official Use Only" - then the restricted access users would not have access to those "OUO" records, but all restricted access users would have access to all non-OUO records.

Creating Access Rules

There is a single access list for each record. This means that the access list is built by aggregating all Person and Team IDs returned by all TRUE rules for a given record and the access list applies to all restricted roles. The access list is stored in the database OPD_OBJECT_PERMISSION table and in the NEED_TO_KNOW_WHITELIST SOLR field.

All access entry types explained above must be tied to a rule. When no rules are TRUE for any access entries, the default behavior is to allow access to all assignees. Follow these guidelines for creating rules for access control entries:

• Create Unique Rules for Each Access Control Entry: It is highly recommended that rules used for access control be used only for that purpose and are not applied to any other behaviors within a module. Following this guidance will ensure that security access rules will not be accidentally modified when changing a rule to meet some other need. There may be cases where it is acceptable to use the same security rule on multiple access entries but do so with caution.
• Create Rules that Validate Expressions: Problems can occur when the entry expression DXL returns NULL. (see "Access Rules Best Practices"). To avoid these potential issues, the rule used for each Persons or Teams access entry should validate that the expression will return at least one valid person or team ID. This means if the expression DXL did not return any valid IDs that the rule used should also be FALSE. See the example below that illustrates how this may be done.

Validating Expressions

Access rules validate access expressions. Consider the example where the module has an access entry to allow people access to records who are at a child level and who are managers. The access expression DXL might be something like this:
LIST(C2:U1, C2:U1 != NULL AND C2:P1:MEANING - "Manager")

In that example, the rule used for that specific access entry should validate that the DXL will return at least one valid ID. If not, the rule should also be FALSE. In order to achieve that, the rule should contain something like this:
NUM(C2:U1, C2:U1 != NULL AND C2:P1:MEANING - "Manager") > 0

When concatenating multiple reference fields in a single expression there needs to be a check to determine if the references are NULL to avoid leading or trailing commas in the expression. 

For example use  #{REPLACE(H:R3:U1||H:R5:U1,' ',',')}  as opposed to #{H:R3:U1},#{H:R5:U1} which are the Replace accounts for adding or removing the commas between references.

When writing an access expression, the system doesn’t allow DXL field codes to be used without being used within a DXL function. 

For example, to grant access to an individual, who is captured within a reference field (e.g., H:R1:U1), then wrap the reference field code within a VAL() (e.g., VAL(H:R1:U1)) or escape the DXL using #{ } to create a valid expression.

Comments in Access Entries

Comments in Access Entries will cause the DXL parser to error unless the comments are added within the parentheses ( ) of DXL functions or inside the curly brackets #{ }of escaped DXL.

Search, Reporting, and Notifications: There are some special behaviors for Access Control Rules that apply in the search and reporting screens and for saved search notifications:

• In the context of mobile development, access rules can be leveraged to reduce the results returned from the search query defined for the reference field.
• In all search screens (list, grid, and report views) it is possible to show the custom-defined access level text. When a module with access control rules has been properly set up with a field mapped to the "Classified Information Label" common field, then the values for that field will show up automatically in all search screens in bold red text.
• Search notifications can contain PDFs or spreadsheets as attachments that include all the data shown in the search/report. Disable these attachments to mitigate the risk of unintentionally transmitting sensitive data via an attached file. To do this, check the Disable Notification Attachments box in Module Properties and compile the module. Users will be blocked from including the attachment but may still create the notification.

Public Reference Data: Similar to the Access All Objects checkbox, the Public Reference Data checkbox enables access to all objects for all roles associated with the module and disregards all access rules.