The WorkgroupSelector function

The WorkgroupSelector function in WrapCreator allows an authorized user in one workgroup to temporarily trust another workgroup to share a wrap instance.

The WorkgroupSelector function demonstrates the powerful instance-level permission model in ExcelWraps. It gives you full control over the user groups that can access each wrap instance, enabling flexible collaboration between workgroups while strongly protecting all the instances that aren’t shared.

Example: A wrap is used to document an overhaul process. Access is normally only granted to the workgroup that handles the overhaul project. A contractor needs to be brought in to perform some of the work. To simplify the administration of the work to be performed, the wrap instance is temporarily entrusted to the contractor using ExcelWraps. After the work has been completed. the contractor’s trust to access the wrap instance is revoked.

If you want to trust more than one workgroup to temporarily access a wrap instance, you can insert additional WorkgroupSelector functions. Every dropdown allows authorized users to trust one more workgroup.

What each user in a trusted workgroup can do with the shared wrap instance is governed by their user roles. Depending on each user’s qualification, tabs may be unlocked, signatures may be enabled, etc.

Using tags to organize workgroups

In ExcelWraps, Users have Roles and Passwords, and may belong to a Workgroup. All this is defined on the Users tab of your wrapsite, i.e. company.live.excelwraps.com.

Screenshot of the Users link in the wrapsite navigation sidebar

You can create arbitrary “groups of workgroups” by assigning “tags” to your workgroups. All the workgroups with a specific tag can be referred to as a group using that tag. The WorkgroupSelector function creates a dropdown list with the names of all the workgroups that have a designated tag.

Screenshot of the Edit Workgroups setting on the server

The link to the window above is Administrator dashboard > Users page > Workgroups.

Separate multiple tags with a comma.

Example: The Common Supplier Wrap

A company has multiple suppliers. A common Wrap is used by all the suppliers. Each supplier creates its own instances. The challenge is to make each new instance accessible only for the customer and for the supplier that created it.

The common supplier Wrap is a member of the Wrapgroup Default, which has a Workgroup setting of None. With these settings, its instances initially become accessible to all users.

  • Supplier A is part of Workgroup A.
  • Supplier B is part of Workgroup B.
  • The Customer is part of Workgroup C.

A permanent Workgroup trust is set up so that the customer always has access to all instances of the Wrap.

  • Workgroup A trusts Workgroup C.
  • Workgroup B trusts Workgroup C.

We must also ensure that the suppliers have the role permissions required to create new instances.

  • User A from Supplier A has role_create.
  • User B from Supplier B has role_create.

When User A creates an instance of the common supplier Wrap, he/she sets a WorkgroupSelector in the Wrap to Workgroup A. Since this makes this specific instance part of the supplier’s Workgroup A, the instance becomes inaccessible for all other users. Due to the permanent trust, however, the instance is also accessible in the customer’s Workgroup C – and we have solved the challenge.

Parameters

Workgroup Tag

Tags are used to select the workgroups that will appear in the WorkgroupSelector dropdown list. Follow the instructions under Using tags to organize workgroups below to define a descriptive tag name and assign it to all the workgroups you want to be eligible in the dropdown. If no workgroups have the designated tag, the dropdown list will be empty.

Roles for entrust

Users with the “entrust” role can trust an eligible workgroup to share the wrap instance. Users with the “distrust” role can change the trusted workgroup, or revoke a previously issued trust.

Users must have a certain combination of roles to be able to entrust the wrap instance to another workgroup using the WorkgroupSelector. Select the first role that users must have. If additional roles are required for a user to be eligible, add them to the same group. A user must have all the roles in the group to qualify, e.g. “users must be both Administrator and Supervisor”.

To add another combination of roles that also makes users eligible, click on Add New Group and add all the rules to the group that a user must alternatively have. A user must have all the roles in at least one of the groups to qualify.

The entrust permission applies only if no trust has been previously granted. If the WorkgroupSelector dropdown is empty, and a user without sufficient entrust authority tries to select a workgroup, an error message is issued during Submit.

If trust has already been granted, the previous trust must first be revoked. Authorized users may then trust a different workgroup. This requires different permission, see below.

Roles for distrust

Enter a combination of roles that the user must have to revoke trust from a previously selected workgroup by removing its name from the WorkgroupSelector function.

Qualified users can also change the workgroup name in the dropdown to entrust the wrap instance to a different workgroup.

When sharing is disabled for a particular workgroup and the wrap instance is submitted, this immediately prevents members of the previously selected workgroup to access the wrap instance. If you want your users to be able to entrust a wrap instance to two or more other workgroups, you must insert the same number of WorkgroupSelector functions into the Wrap.

If a user without sufficient authority tries to clear or modify a previous selection, an error message is issued during Submit.

Function reference

Screenshot of a WordGroupSelector function call

Example

In the example above, users with a Manager role will be able to entrust the wrap instance to any workgroup that has the Installer tag. Users with a Client role can revoke such trust, or grant it to a different workgroup in the list.

The following cell formula is inserted in the cell.

=WorkgroupSelector("Installer","Manager","Client")

Format and parameters

=workgropupselector(“tag”, “roles_for_entrust”, “roles_for_distrust”)

tag

The tag selects the workgroup names that appear in the dropdown. Assign this tag to the workgroups you want to be eligible in the list.

roles_for_entrust

Enter the user selection logic (read more below) that designates the users that can entrust a wrap instance to an eligible workgroup.

roles_for_distrust

Enter the user selection logic (read more below) that designates the users that can distrust a previously trusted workgroup, or trust a different workgroup in the list.

User Selection Logic

The workgroupselector() function allows you to select users by defining groups of user roles. A user is considered qualified if he or she has all the roles in at least one of the groups.

  • “+” is used to combine the roles of a group. A user must have all the roles in a group to qualify, so you can read the plus sign as “and”.
  • “,” is used between the role combination groups. A user only needs to have all the roles in one of the groups to qualify, so you can read the comma sign as “or”.

Example

"Supervisor+Administrator,Manager+Administrator"

This rule selects all users that are

  • either both Supervisors and Administrators
  • or both Managers and Administrators.

Known issues

  • A WorkgroupSelector can theoretically be part of a Unique Key and used in a WrapLink, but the effects can be unpredictable. As an example, after a new wrap instance has been saved once, it won’t be possible to change the workgroup selector – you cannot change any of the components of the Unique Key for a wrap instance.
  • If a user tries to access a wrap instance without proper trust, an Access Denied message appears. Even if a WorkgroupSelector is modified in order to grant the user access to the wrap instance, this error message may persist when the user tries to refresh the page. This is due to the design of the web browser and not something we can bypass. A circumvention may be for the user to copy the link to the wrap instance, paste it into the Address field again and start over.