The UserSelector widget

The UserSelector widget creates a dropdown list with user names that have certain combinations of roles. Only one of the eligible users can be selected.

The dropdown list created by the UserSelector widget is populated with the names of all the users that have all the roles in at least one of the combinations you have specified.

Example: A Wrap instance for bogie overhaul must reference the Supervisor responsible for the overhaul. A UserSelector widget automatically prefills a dropdown list with the names of all users that have the Supervisor role. The Supervisor just needs to select his/her own name in the list.

The UserSelector widget is a visual guide that helps you insert a userselector() function into the current cell.

Insert a UserSelector widget

  1. Select the cell where you want the user selector dropdown list to appear.
  2. Switch to the WrapCreator ribbon and click on Insert Widget.
  3. Select the UserSelector widget on the Widget tab in the task pane.
  4. Enter the required parameters and press Apply.
  5. Verify that a =userselector() function has been inserted into the cell.


Screenshot of the UserSelector widget with a holder cell

Cell Name

You must always name all input fields. It adds clarity to the spreadsheet but more importantly names the database column where each input field is saved.


You may require that users have a certain combination of roles to appear in the UserSelector. 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 H-Supervisor”.

To add an alternate combination of roles that also makes users eligible, click on Add New Group and add all the roles 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 UserSelector dropdown list will contain the users that have all the roles in at least one of the groups of roles that you have defined, and also satisfy the Workgroup membership of the current Wrap instance.

Holder cell

While you test the wrap in Excel, you can provide a test value in a special holder cell to verify that other formulas in the wrap return the correct results. When you upload the wrap, live data automatically replaces the test value in the holder cell. For a UserSelector widget, the holder cell contains the user name selected from the list.

When you select a holder cell, its settings appear on the Cell tab. Click on Setting -> in the settings for the UserSelector widget to automatically locate and select its holder cell.


If you enable a holder cell for the widget, the cell immediately to the right of the UserSelector widget is chosen by default. You can change the location of the holder cell by clicking on the “pen” symbol and then selecting a different cell as the holder cell.

Precedent Widget Cell

Many holder cells store results from a widget. To simplify editing, there is a Setting -> shortcut that shows the settings for this widget.


Holder cells sometimes contain information that you don’t want to show to the user of the wrap. In this case, tick this box to make the contents of the holder cell invisible in the wrap.

Dummy Value

This is the value that the holder cell will contain during testing in Excel. When the wrap is running on the server, real values from the database are used, and the dummy value has no meaning. For the UserSelector widget, you must enter a valid user name here. Example: “JaneDoe”.

Read more about testing Wraps in Excel.

Remove a UserSelector widget

To delete a field, widget, wrap function or signature that has been stored at least once in the live production database is not a trivial task. The instructions below are only applicable during the initial development of a wrap, before it has ever been used in production. Read more about making changes to your wraps.

To remove a UserSelector widget:

  1. Ensure that the task pane is visible.
  2. Select the widget’s cell.
  3. The task pane should now show the UserSelector widget’s settings on the Cell tab. If it doesn’t, you may have selected the wrong cell, or already removed the widget by mistake.
  4. If the UserSelector widget designates a holder cell, right-click on this cell and select Clear contents.
  5. Locate the Remove button at the bottom of the widget settings and click on it.

Function reference

Screenshot of the UserSelector widget with a holder cell Example

In this example, the resulting dropdown list will contain all users that are

  • either both Administrators and H-Managers
  • or both Administrators and H-Supervisors

Format and parameters



The userselector() 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”.

Technical note: The cell’s formula must have exactly the format above. You cannot perform any other calculations or use any other functions in the same formula. You cannot nest user groups using parentheses.

The holder cell

You can use a Holder Cell to provide a dummy value to test the wrap already in Excel. When the wrap is run on the server, the UserSelector widget extracts live user data from the cloud database and returns the selected username in the holder cell.

Format and parameters

=HOLDER(cell_name, dummy_value, hidden, holder_item)

cell_name points to the UserSelector cell using its cell name.

dummy_value contains a value you want the cell to provide during testing in Excel – at runtime, real values from the server are used instead. The dummy value must have the same data type as the value that will later be returned by the server.

hidden if set to TRUE, makes the contents of the holder cell invisible in the wrap.

holder_item is always empty for UserSelector widgets.

=HOLDER(user_name, "JaneDoe", TRUE, "")