The UserRole function

The UserRole function is used in a Competence Wrap to temporarily assign a dynamic Role to a User from inside the Wrap, with an expiration timestamp.

Most Roles are static, i.e. permanent, and assigned to Users on the Wrapsite’s Administration dashboard. The UserRole allows you to temporarily assign a User a Role that is dynamic, from inside a Wrap. This allows you to create so-called Competence Wraps that keep track of your Users, their skills, and the related Roles.

If you are new to the concepts of Users and Roles, you may first want to learn a bit more about the ExcelWraps permissions model.

The Competence Wrap

Screenshot of a Competence Wrap

The Competence Wrap above can be used at the end of a certification or course. Users have new skills and will be rewarded with a new Role.

Each UserRole function in the Wrap can assign a single Role to a single User.

  • Column A contains UserSelector widgets. When the Wrap is open in a web browser, one User can be chosen for each row in the table.
  • Column B contains the dynamic Role to temporarily assign to the respective User.
  • Column C contains the expiration timestamp. The User will automatically lose the dynamic Role at the designated instant. If you don’t want the Role to be temporary, use a date very far in the future.
  • Column D contains the UserRole functions.
  • Cell D9 contains a WrapSignOff signature field, which must be for a Freeze signature.

When the Competence Wrap is signed, the User that is selected in the dropdown for column A will be temporarily assigned the role in column B until the expiration date in column C.

Static and Dynamic Roles

If a User has been assigned a dynamic Role, it has an expiration date instead of the tick in the box that the permanent Roles have. The User in the screenshot below has the Client Role until the expiry date, and the C-Mech Role until it is revoked.

Screenshot of User definition with a temporary role

Normally, you shouldn’t tick the checkbox for a dynamic Role. If you do, you disable the automatic expiration and the Role becomes permanent – the User retains the Role at least until you untick the box. If you tick the box and then untick it, the User still retains the Role until it expires automatically.

To edit or completely revoke a dynamic Role before it expires, you need to locate the instance of the Competence Wrap that you used to assign the Role, and Unsign it. This immediately revokes the dynamic Roles assigned by this Wrap. You can then make changes to the Wrap and sign it again, e.g. to change the Roles or the expiration dates. We recommend that you do not delete an instance of a Competence Wrap, at least not without unsigning the instance first, since it is the source for the dynamic Role.

If you have more than one instance of a Competence Wrap and you have assigned the same Role to the same User from more than one of the instances, you must unsign all the instances to revoke or change the dynamic role.

Function reference

Screenshot of a Competence Wrap

Example

In the example above, up to three Users can be selected using the UserSelector widgets in column A. They will all be temporarily assigned a dynamic Client role until the expiration date.

This is what this UserRole function call will look like:

=UserRole(A5,B5,C5)

Format and parameters

=UserRole(user_name, role_name, expiration_timestamp)

user_name

Specify the name of the User that is to be temporarily assigned a dynamic Role. You may refer to a cell containing a UserSelector widget, like in the example above. You can also specify the name as a text string, e.g. “JaneDoe”.

role_name

Specify the Role you want to assign, either as a string or as a cell reference.

expiration_timestamp

Specify the date and time when the user automatically loses the dynamic Role, in ISO 8601 format. You can calculate the expiration date dynamically, e.g. as thirty days in the future, using this formula in B8:

=NOW()+30

You can then format this as an ISO 8601 date like this:

=YEAR(B8)&"-"&RIGHT("0"&MONTH(B8),2)&"-"&RIGHT("0"&DAY(B8),2)&"T00:00:00-05:00"

The string “-05:00” at the end sets your local time zone, e.g. -5 is Eastern Standard Time.

For Western European Time, use +00 or the letter “Z”.

Special considerations

The cell containing the UserRole function must be named.

The Wrap containing the UserRole function must be signed with a Freeze signature for the dynamic roles in the Wrap to be assigned.