Overview

Pims is a complex multi-module application suite. Security-wise, each Pims product module has its own set of permissions & access checks and it might seem complex to setup new users.

Fortunately, managing person records, user logins and product permissions is easy when using the Pims Persons page. This user management page provides intuitive functionality for personal data and login management. It is an ideal one-stop-shop from where all such tasks can be effortlessly managed without any fuss.

The following article describes the Pims Persons page functionality. It consists of 4 main parts:

1. Persons, Companies & Users setup
2. Creating new user logins
3. Person details and product permissions
4. Technical details for product integration

1. Persons

Persons is the register for creating and maintaining person records. Please note that not all persons registered in Pims are necessarily having user accounts. Some records just hold personal contact information used in Pims modules.

Persons can be accessed from the related main menu option under the General section as shown in the figure below:

By default the page shows only a list of existing persons from current Domain selected by user. "Show Persons from all Domains" checkbox allows users with the necessary permissions to view persons from all domains. To display persons from all domains, users must have additional permissions granted through a role with the "projectsetup_view_persons_teammembers" capability. See in the figure below (existing records maintenance is reviewed in the second part of this article):

It is also possible to filter persons by roles by clicking "Filter by Roles" button at the top of persons list, as highlighted in the figure below:

This opens a modal where roles which to filter can be selected. Also there is a checkbox with which it is possible to filter persons having all of the selected roles or any of the selected roles. It is needed to press on the "Filter" button in order to filter.

Then the modal will close and desired roles will be highlighted in Roles in current Domain column as seen in the figure below:

When pressing the bar menu option New Person, a form will be displayed to create a new record. The UI hierarchy on this form starts with baseline "person" data.

Secondary tabs on this form for setting up & maintaining login settings for each Pims product will appear after selecting a login (more details in part 2 of this article).

Drop-down combo boxes on this form allow to either select an existing option (Company, Login), or create a new option if required via the adjacent + button, as shown in the figure below:

For example, clicking on the Company link opens the Companies page in a separate tab as shown in the figure below:

The + button adjacent to Companies opens a New Company form:

Similarly, when a login is already assigned to a person, users can view details for that login by clicking on the Login link. This action will open the System-user-details page in a separate tab, providing quick access to view and manage details associated with the selected login as shown in the figure below:

The + button adjacent to Login makes the login input editable for users that meet permissions (more in 2nd part) so when all of the required information is saved both new person and user will be created:

2. Creating new user logins

To be able to use Pims, a person needs to have a login. If the login is already available, it can be selected using the login lookup on Person Details page. Logins that already have a person associated with them will not show up in the Login lookup. If the login is not available, it can be created by other users with sufficient permissions for new user creation. There are two options for the user to be allowed to create logins for other persons:

1. The user must have Security Admin (or higher) permissions, or
2. The user needs to be a Pims User Creator.

Users with Security Admin (or higher) permissions can provide other users with the ability to create new users by granting them Pims User Creator role. This can be done by clicking Pims User Creator checkbox as shown in the figure below. Note that the checkbox is only visible for users with Security Admin (or higher) permissions and Pims User Creators themselves.

When a user meets any of the two conditions that allow creating new logins, a button with a + sign appears on the right part of the login lookup as can be seen in the figure above. Clicking this button opens a dialog for new login creation. For users with Security Admin (or higher) permissions, a standard dialog for user creation is displayed as shown figure below.

Pims user creators are presented with a simplified version of the dialog as shown in the figure below.

In order to use Pims User Creator feature, PimsUserCreatorJob must be running in the Scheduler (recommended running interval: 1 minute). For more details on what permissions are required to be able to use Pims User Creator feature, see section 5.1. Permissions for Pims User Creator.

Once the person has been provided with the login, Domain Assignments can be managed as described in the next section.

3. Person details and product permissions

Clicking on the Name of a Person record in the Persons page main list opens the Person Details page for maintenance purposes as shown in the figure below. Person details can be viewed from the side panel of the Persons page or an external web page.

Updating First name, Last name, Email or Phone for a person also updates the information for the user assigned to the person for consistency reasons.

A new Domain Assignment can be added via the bottom starred new line in the corresponding grid under the User tab. It is worth noting that only domains that the administering user has permissions to are listed as shown in the figure below.

Existing assignments can be modified or removed and Roles for each domain can be assigned using the edit ("pencil") button at the end of each row. After clicking the edit button, a dialog for editing the Domain assignment is opened as shown in the figure below:

Also existing domain assignment Team Member status can be modified using the Domain Assignments grid by clicking "Is TM" or "TM Expired" checkboxes. Whole domain assignment can be removed by pressing the delete ("trash can") button next to the edit button as highlighted below:

Administering Roles requires additional permissions (a role with af_manage_user_role_domains capability). Having an assigned Role provides the person permissions to view and/or edit the data available for the role in the domain.

The main functionality of Domain assignment management is provided in the table below:

Element	Description
	Allows assigning or removing the Person to/from the selected Domain. Team members can be actively involved in the actions happening in the selected domain. They appear in lookups, can be assigned to documents, actions and participate in any regular activities that happen in Pims.
	Allows expiring the domain assignment. Note that this does not expire Person or User records, only removes the Person from the selected Domain.
	Shows of hides Roles that are managed by Workflows or PES modules. This allows switching between the full list of Roles the user is assigned and a limited list of Roles that are controlled using the Person Details page. Note that Workflows or PES controlled Roles cannot be added or removed using this dialog and has to be controlled separately in the corresponding product-specific tabs. Read below for more details.

Roles Membership section may be hidden if the administering user does not have appropriate permissions. More access can otherwise be requested via the Request More Access hyperlink on the top-right of the grid.

Note that domain-independent roles are shown in a separate row in Domain Assignments and marked as (domainless). These roles can otherwise be managed the same way as usual Domain-related roles using the edit ("pencil") button. 

A Domain Assignment includes a Role-Based View with a toggle element for switching between grids. This enables granting access based on roles and extending it to multiple domains. 

Users have the option to expand roles by clicking Expand Roles checkbox in the "Domain Assignments" grid. After clicking the checkbox, the role field expands, displaying all roles assigned to the user. Additionally, after switching a Role-Based view toggle between grids and clicking the Expand Domains checkbox, Users have the option to expand domains field and view all domains assigned to the user.

Users can copy domain assignments from another person by clicking the Copy Assignments button in the "Domain Assignments" grid. Upon clicking, a modal will open, allowing users to select a source person from which to copy domain assignments.

Once a source person is selected, a new grid will appear, displaying a preview of the domain assignments available for copying. Users can select which domain assignments to copy and choose to copy only team members, roles, or both by using the checkboxes provided ("Copy Team members" and "Copy Roles").

In case any errors occur during the copying process, a "Result" column will appear in the grid, displaying an error message indicating the issue encountered.

There is a possibility to set Default Domain if a person has a login using "Set Default Domain" in the Tasks menu on the top right of the page:

There is also a possibility to reset selected users OTP in the Tasks menu (only available for users with Pims User Creator or Security Admin permissions):

The change log of a person's details can be accessed by clicking on the Change Log button in the top toolbar. A modal window will open, showing the log of updated, inserted and deleted changes performed:

Please note that users must have the capability 'af_manage_user_role_domains' to access the Change Log feature.

There may be other permissions management options in product-specific tabs next to the User tab.

For example, Omega Pims Completion Management has additional permission settings by Projects, Contractors and Handover Groups that can all be managed directly from their corresponding tab, subtabs and via the 3-dots button on the right side of each table row, for each domain. A Copy Role/Domains feature is also available to accelerate the setup of multiple users with the same permissions for the same domain:

With Omega Pims Document Control, Contracts Memberships are managed via either the bottom starred row for additions or the bin button for removals as shown in the figure below:

The Pims Workflows tab has sub-tabs allowing to manage all permission, roles, confidentiality, and other aspects for users:

4. Technical details

Integration between the Person Details page and a specific product set of permissions occurs via setting up a record in atbl_ProjectSetup_ProductModules connecting to the relevant product snippet article:

The Persons Details page picks up such product-specific permissions snippets and accordingly adds them as tabs:

The Persons page belongs to the General namespace. 

Any Omega Pims product group interested in integrating their specific permissions snippet into the Person Details page shall consult with the Omega Pims General team for more technical information on integration.

5. Permissions for User Management

5.1. Permissions for Pims User Creator

A role with a role code GeneralPimsUserCreator is available that contains a minimal list of permissions required to use PimsUserCreator functionality. It should be assigned to users that are provided with this feature. GeneralPimsUserCreator_RoleManagementJob must be scheduled to run at recommended intervals of 2 minutes for the role to be synchronized.

In the creator's Default Domain, make sure to enable the "Allow sending 'New User Notification' email" checkbox. Refer to the example figure below:

To ensure required permissions are in place for GeneralSecurityAdmin role that is assigned for SecurityAdmin context user, the procedure astp_General_SecurityAdminEnsurePermissions can be used. Also, for Pims User Creator functionality to work properly, SecurityAdmin context user requires GRANT ALTER ANY Role, GRANT ALTER ANY USER. These are included in SQL Server roles db_securityadmin and db_accessadmin respectively and are assigned by default Appframe setup.