Who is this article for?

Please Review Users creating external groups.

Please Review Administrators with permissions to create external groups.

Advanced role mapping in Please Review enables organisations to fine-tune user permissions and access levels, tailoring document review and collaboration processes to their specific needs. This feature allows for intricate control over who can view, edit, or approve documents, enhancing document management and compliance.

1. Automatically Mapping Workgroup Roles from External Groups
2. Advanced Role Mapping
3. Further Reading

Automatically Mapping Workgroup Roles from External Groups

Mapping external groups into workgroups allows the System Administrator to mandate the role of a given user in a mapped workgroup. This allows the workgroup role administration to be done completely in the external system.

• Please Review will automatically suffix group names and role names with an underscore character and map any users in the suffixed group/role.
• This overrides any default role set in the system connector’s configuration file on the Please Review server.
• For example, if a group is created in the external system called ‘Clinical’ and there is also a group called ‘Clinical Author’ any user in the ‘Clinical Author’ group will have the preset Please Review role of ‘Author’ and they will appear in the workgroup in Please Review called ‘Clinical’. 

Note: If the System Administrator or the workgroup administrator changes the user’s role, then this will automatically be set back to the mapped role when Please Review synchronises the workgroup’s member list with the external group, unless they are not in a suffixed group.
For example, if a user only exists in the ‘Clinical’ group they will not have their workgroup membership changed.

The following is the list of the default workgroup roles that are pre-set within Please Review:

• Reviewer
• Author
• Contributor
• Author-Contributor
• Admin Only
• Admin-Reviewer
• Admin-Author
• Admin-Contributor
• Admin-Author-Contributor

Note: this feature is not configurable and is always active.

The automatic synchronisation takes place by default at midnight every night. This can be changed to suit your requirements. It is also possible to manually run the sync whenever it is required, and can be done in two ways:

1. Via the ‘Queue’ menu option in the Admin Client (this will synchronise all members in all workgroups).
2. From the ‘user management' screen when you select ‘Members’ against a workgroup (this will only synchronise the members of the selected workgroup).

Advanced Role Mapping

For customers who cannot control the structure and naming of groups, another option is available that requires listing all the groups to be used, along with the role any members of a specific group will have.

Important: This functionality is not enabled by default as it requires site-specific configuration.

The extra elements should be added into the 'CustomRoleMappings.xml.sample' file located in the runtime\config directory.

• Remove the .sample suffix so that the file is used.
• The new configuration file is only required for directory servers that need it.
• The sample file can be edited with a text editor or XML editor.
• Open the file and search for “[[“. This is used to mark values that need to be manually replaced.
• Replace each marker with its value from the following table. Remove any [[and]] markers from the file once the editing is complete.

The table below explains the parameter notes:

Groups that will be read from the external source can be identified either by their name or their internal group identifier within the external system (their ExtRef). This identifier will be different for each system and has system specific formats.

By allowing the external workgroups to be identified by their external reference, workgroups with matching names but different external sources to be easily distinguished. When specifying the workgroup name or external reference, only the item being used need appear in the file. For example, if you identify the group by name, there is no need for the ExtRef field to be included.

In the example below, two groups from an Active Directory source will be loaded. Users in the group with the group name ad123 will be mapped as authors and users in the group that has an external reference

(the Active Directory ObjectGUID) of 3b24-2c88-4ec1-9c36-bf4e will be mapped as reviewers.
<CustomRoleMappingSets>
<CustomRoleMappingSet>
<ExtSource>ActiveDirectory:ad123</ExtSource>
<Mappings>
<Mapping>
<WorkgroupName>ad123</WorkgroupName>
<Role>Author</Role>
</Mapping>
<Mapping>
<WorkgroupExtRef>3b24-2c88-4ec1-9c36-bf4e</WorkgroupExtRef>
<Role>Reviewer</Role>
</Mapping>
</Mappings>
</CustomRoleMappingSet>
</CustomRoleMappingSets>

Restart IIS and the TaraService for these changes to take effect.

1. Search for groups in your external system and select one of the groups returned by the Mapping section in the config file.
2. This will then pull in the users from the selected group as well as all the other groups mentioned in the MappingSet section, producing a single workgroup in Please Review.
3. You may change the workgroup name during this load stage, before pressing the ‘Save’ button.
4. If other roles need to be mapped in the future, just add an additional Mapping element alongside the existing ones. For example, to add all the users in the directory group ad789 as contributors you would add:

<Mapping>
<WorkgroupName>ad789</WorkgroupName>
<Role>Contributor</Role>
</Mapping>
Remember to restart IIS and the TaraService for these changes to take effect.

• If you want to create multiple sets of mappings, you can do so by creating multiple
  <CustomRoleMappingSet> elements underneath the <CustomRoleMappingSets>.
• Sets can come from different external sources by specifying the source in the <ExtSource> element.

The value entered here should be one of the entries in your SystemConnectors file. The sample file provided contains example formatting for two sources, each with one Mapping Set and containing two workgroups each, one mapped by name and one by ExtRef.

Important: Do not create multiple <CustomRoleMappingSets> within the configuration file, or multiple <Mappings> elements within a single <CustomRoleMappingSet> or the configuration will fail.
There can be as many <CustomRoleMappingSet> sections in the file as required, and each set of <Mappings> can have as many <Mapping> elements as there are workgroups.

Further Reading

• How to Configure External Systems Integration
• How to Use External Groups