Chapter 6   Defining Groups and Roles


This chapter explains creating groups and roles and defining their properties.

This chapter includes these sections:

• Groups and Roles Overview

• Creating Groups and Roles

• Prioritizing Groups and Roles

• Deleting Groups and Roles

Groups and Roles Overview

---

For a Process Manager application, user roles and groups determine which users see which forms and which users perform which tasks. Scripts can also use the groups and roles. Groups are a collection of users in an application. Roles are the parts users play in a specific process instance. For example, you could have a group composed of all employees in the company. If someone in that group submits a time off request, for that particular process instance that employee has the role of creator. The creator role is defined automatically when you create a new application, however, you can create other roles. The user and group information in the corporate user directory is the source of user information when you set up groups and roles.

The following types of groups and roles are available:

Application Group. A group defined in a particular application that points to user data in the corporate user directory. The group information is stored in the configuration directory, and the user information is stored in the corporate user directory. Because these groups are stored in the configuration directory, you do not need to have write access to the corporate user directory to create one. The context of this group is the application, since it cannot be used by other applications.

Corporate Group. A group that points to a group defined for the corporation in the corporate user directory. The application's corporate group is exactly the same as the group in the corporate user directory; when the group in the corporate user directory is updated, the corporate group automatically uses those changes. Using corporate groups you can leverage the groups already defined in the corporate user directory. The context of this group is in the corporation; it can be used for many things besides applications.

Dynamic Group. This group uses a filter to list members in the corporate user directory that match the attributes in the search filter. Unlike a corporate group, which is already defined as a group in the corporate user directory, the dynamic group uses corporate user directory information to create a group dynamically. This group is defined in the context of the corporation (it changes based on changes in the corporate user directory) but it also is used only for the application.

Field Role. A role represented as a data field. The value of the field varies by process instance, so the role's context is the particular process instance. For example, the creator role (the person who starts a particular process instance) is a field role. The field role can only be one user; you cannot use a field role to assign an activity to a group.

Internal Group/Role. An internal group or role is defined by default in Process Manager. For example, the all group, which represents all users in the corporate user directory, is an internal group.

There are three high-level steps in creating groups and roles:

1. Choose the type of group or role you want.

   You can do this by asking yourself what the context of the group or role is. Is it just for this application, or is it a group that has corporation-wide implications?

2. Choose valid users for the group or role.

3. Prioritize all of the groups and roles in an application.

   You need to prioritize the groups and roles so that if a user is assigned to multiple roles, the form access system can determine what precedence to give each role. For more information, see Prioritizing Groups and Roles.

Default Groups and Roles

When you create an application, the following groups and roles are created by default:

all. The group of all users in the corporate user directory.

creator. The person who initiates a particular process instance.

admin. The group of people allowed to administer the application's process instances using Process Business Manager. You need to add the names of the people who can administer the application to the application's default "admin" group. These people must also belong to the WF Admin Auth ACL for the Enterprise Servers. Anyone who is allowed to administer by the WF Admin Auth ACL can administer the application at the application level, but only users who belong to the application's "admin" group can administer the application at the process instance level.

trusted users. A group that can start a subprocess as another user. The parent process redefines the initiator of the child process. If no one will need to start a subprocess as someone else, you need not assign anyone to the trusted users group.

You can customize some aspects of these groups and roles, but you cannot delete them. If you don't need them for your particular application (for example, if your application deals with sensitive information that you do not want to expose to the "all" group) you don't need to define forms for particular groups or roles. See Setting Access to Forms for more information.

In addition to the above groups and roles, each application has an assignee role. It is set for every step in the process in which someone must perform an action. However, since it is a special role, it doesn't appear in the application tree view and you cannot set properties for it. It works in concert with other groups and roles. For example, a step may be assigned to a group, but the actual user from that group who performs the task in a particular process instance is the assignee.

Creating Groups and Roles

---

To begin defining a role or group, follow these steps:

1. From the Insert menu, choose Group & Role.

2. In the Create a New Role or Group dialog box, choose the type of role and fill in the fields.

   See The Create a New Role or Group Dialog Box for details.

3. Click either the Add button or the "Add & Define" button.
   • Click Add & Define if you want to define the new item right away. A dialog box for the type of group or role you chose (for example, an application group) appears.

   • Click Add to define the item later. The Create a New Role or Group dialog box remains open, and you can add additional items.

4. If you clicked Add & Define, fill in the fields of the next dialog box that appears.

   When you close the dialog box, your changes are saved automatically.

The Create a New Role or Group Dialog Box

To supply basic information about the role or group you want to create, enter this information in the "Create a New Role or Group" dialog box, as shown in Figure 6-1.

Figure 6-1    The Create a New Role or Group dialog box

Types of Groups and Roles

There are four different types of groups and roles you can create:

Application group. A group defined in a particular application that points to user data in the corporate user directory. The group information is stored in the configuration directory, and the user information is stored in the corporate user directory. Because these groups are stored in the configuration directory, you do not need to have write access to the corporate user directory to create one. The context of this group is the application. Therefore, this group cannot be used by other applications.

Corporate group. A group that points to a group defined for the corporation in the corporate user directory. The application's corporate group is exactly the same as the group in the corporate user directory; when the group in the corporate user directory is updated, the corporate group automatically uses those changes. Using corporate groups you can leverage the groups already defined in the corporate user directory. The context of this group is in the corporation; it can be used for many things besides applications.

Dynamic group. This group uses a filter to list members in the corporate user directory that match the attributes in the search filter. Unlike a corporate group, which is already defined as a group in the corporate user directory, the dynamic group uses corporate user directory information to create a group dynamically. This group is defined in the context of the corporation (it changes based on changes in the corporate user directory) but it also is used only for the application.

Field role. A role represented as a data field. The value of the field varies by process instance, so the role's context is the particular process instance. For example, the creator role (the person who starts a particular process instance) is a field role. The field role can only be one user; you cannot use a field role to assign an activity to a group. Because it's related to a datafield, you cannot create a Field Role if your application has been deployed for testing or production.

Name. Enter the name of the role or group. This field cannot contain the following characters: quotation marks ("), commas (,), plus signs (+), and semicolons (;). If you are creating a field role, the name cannot be more than 18 characters long, because the name is also used as the name of the field.

Description. An optional longer description of the role or group.

Adding a New Group or Role

To add a new group or role, click either the Add button or the "Add & Define" button.

Use the Add button to add several items in succession, without defining their properties. Each item will be added to the application tree view, but the "Create a New Role or Group" dialog box will remain open so that you can add subsequent items. After adding the desired items, you can define them by double-clicking them in the application tree view.

Use the "Add & Define" button to add an item and then immediately define it. Each item is added to the application tree view, but then a new dialog box appears, depending on the kind of group or role you are adding. One of the following dialog boxes will appear:

• The Application Group Dialog Box

• The Corporate Group Dialog Box

• The Dynamic Group Dialog Box

• The Field Role Dialog Box

The Application Group Dialog Box

The Application Group dialog box, shown in Figure 6-2, is where you identify which users are assigned to an application group. For example, if you are designing a time-off request application and have a role for HR approval, you could create an application group with the names of everyone in HR who is allowed to approve a time-off request.

Figure 6-2    The Application Group dialog box with Browse tab

The dialog box contains the following fields, which contain the values you entered in the Create a New Role or Group dialog box:

Name. The name of the group.

Description. The group's description.

Allow cache. If checked, allows group information to be cached. You must also set the User Cache Policy property for the application to All or Members to enable caching. See Setting Application Properties for more information.

Allow search. If checked, allows users in this group to search. If you do not make the group searchable, members of the group will not be able to use the search functionality to check the status of process instances or to find process instances related to specific criteria. They can still use the global search, though. See Chapter 13 "Setting Up Searching" for more information.

List of users. The list of people that are part of this group. This list displays the user RDNs (relative distinguished name) as stored in the corporate user directory. You can add users to the List of Users from the corporate user directory list in the right pane. You can use the Search tab in the right pane to find users, or user the Browse tab to find them.

Note. If no users are appearing in your Browse tab or when you search, make sure you have set a corporate user directory in the application's properties.

To see users in the Browse tab, expand the directory and groups by clicking the expansion icons (plus signs). The first time you click the icons the data loads from the corporate user directory. After that, a single click reloads cached data. To reload the information from the corporate user directory, double-click the directory and groups.

If you use the Browse tab, drag the users to the List of Users.

If you use the Search tab, use the buttons at the bottom of the right pane to add users to the List of Users. There are also Select All and Deselect All buttons.

To delete a user from the list of users, select the user name in the List of Users area and click the "X" box above the list.

To use the Search tab to quickly find and add users based on a wildcard pattern, follow these steps:

1. Click the Search tab, which is shown in Figure 6-3.

Figure 6-3    The Application Group dialog box with Search tab

2. Enter a search pattern (such as j* or *jan*).

   This pattern can be for any part of the user's name, such as first name, last name, or user ID.

3. Click the Search icon to get a list of all users that match the pattern.

   By default, the list displayed is sorted by user RDN (relative distinguished name). You can specify the sort order in the preferences.ini file, which is located in the builder folder. Add the following line to the file:

      sortAttribute = attribute

   where attribute is any LDAP attribute, such as cn or uid, that you want to appear first in each line of the list. For instance, if you entered sortAttribute = cn, the common name appears first in each line displayed.

   The search returns the number of records specified in the "Records to retrieve" box. By default, the amount of records retrieved is 1000. You can modify this default in the preferences.ini file; add the following line to the file:

      defaultSearchSize = number

   where number is the amount of records you want displayed by default.

4. Select one or more users from the list.

   To select multiple users, highlight a user and without releasing the mouse button brag to the last user you want to add, then release.

5. Click Add.

The Corporate Group Dialog Box

The Corporate Group dialog box, shown in Figure 6-4, is where you identify a corporate user directory group or set of groups as a group in your application. For example, if you want to have a group called "HR" that consists of all employees in the HR department, and a group like that already exists in the corporate user directory, you can create your group quickly by using the corporate group. Because it is tied to the corporate group, any changes made to the group in the corporate user directory are reflected in the application. Also, since the corporate groups are defined outside of applications, you can use the same group easily for multiple applications.

However, you cannot add or delete users from a corporate group in your application. You must use the corporate group exactly as it is set up in the corporate user directory. To manage your corporate directory, use the administration features of your Directory Server.

Figure 6-4    The Corporate Group dialog box with Browse tab

The dialog box contains the following fields:

Name. The name of the group.

Description. The group's description.

Allow cache. If checked, allows group information to be cached. You must also set the User Cache Policy property for the application to All or Members to enable caching. See Setting Application Properties for more information.

Allow search. If checked, allows users in this group to search. If you do not make the group searchable, members of the group will not be able to use the search functionality to check the status of process instances or to find process instances related to specific criteria. They can still use the global search, though. See Chapter 13 "Setting Up Searching" for more information.

List of groups. The list of groups that are part of this group. You can add a group or groups from the corporate user directory list in the right pane to the List of Groups. You can use the Search tab in the right pane to find groups, or use the Browse tab to find them.

Note. If no users are appearing in your Browse tab or when you search, make sure you have set a corporate user directory in the application's properties.

To see users in the Browse tab, expand the directory and groups by clicking the expansion icons (plus signs). The first time you click the icons the data loads from the corporate user directory. After that, a single click reloads cached data. To reload the information from the corporate user directory, double-click the directory and groups.

If you use the Browse tab, drag the groups to the List of Groups.

If you use the Search tab, use the buttons at the bottom of the right pane to add groups to the List of groups. There are also Select All and Deselect All buttons.

To delete a group from the List of groups, select the user name and click the "X" box above the List of groups area.

You can use the Search tab to quickly find and add groups based on a wildcard pattern. To do this:

1. Click the Search tab, which is shown in Figure 6-5.

Figure 6-5    The Corporate Group dialog box with Search tab

2. Enter a search pattern (such as a* or *adm*).

3. Click the Search icon to get a list of all users that match the pattern.

   By default, the list displayed is sorted by user RDN (relative distinguished name). You can specify the sort order in the preferences.ini file, which is located in the builder folder. Add the following line to the file:

      sortAttribute = attribute

   where attribute is any LDAP attribute, such as cn or uid, that you want to appear first in each line of the list. For instance, if you entered sortAttribute = cn, the common name appears first in each line displayed.

   The search returns the number of records specified in the "Records to retrieve" box. By default, the amount of records retrieved is 1000. You can modify this default in the preferences.ini file; add the following line to the file:

      defaultSearchSize = number

   where number is an integer number of records you want displayed by default.

4. Select one or more groups from the list.

   To select multiple users, highlight a user and without releasing the mouse button brag to the last user you want to add, then release.

5. Click Add.

The Dynamic Group Dialog Box

The Dynamic Group dialog box, shown in Figure 6-6, is where you define groups that are created dynamically. The application searches the corporate user directory using an LDAP filter, letting you take advantage of attributes in the corporate user directory.

Figure 6-6    The Dynamic Group dialog box

The dialog box contains the following fields:

Name. The name of the group.

Description. The group's description.

Allow cache. If checked, allows group information to be cached. You must also set the User Cache Policy property for the application to All or Members to enable caching. See Setting Application Properties for more information.

Allow search. If checked, allows users in this group to search. If you do not make the group searchable, members of the group will not be able to use the search functionality to check the status of process instances or to find process instances related to specific criteria. They can still use the global search, though. See Chapter 13 "Setting Up Searching" for more information.

LDAP Filter. Enter an LDAP filter and click Show Members to see a list of matches. You do not need to use the Show Members button, but it shows you what your filter fins. Process Builder does not check that the filter you enter is valid. If, after entering the filter string, nothing appears when you click Show Members, either your filter is invalid or it is a valid filter but there are no results that meet the criteria.

A search filter lets you search for an attribute in the corporate user directory. Here are a few sample searches you might use in this field:

• manager=smith*

  Searches for all users whose manager's user ID is smith* This syntax only works if the corporate user directory is set up to with the user ID as the RDN's first attribute. If the common name is first, the filter is manager=cn=smith*

• DepartmentNumber=444

  Searches for users whose department number is 444

• (&(manager=smith*)(employeetype=employee*))

  Searches for people whose manager's user ID is smith* and whose employee type is employee. The ampersand character (&) is the and operator.

• (|(manager=smith*)(manager=jones*))

  Searches for people whose managers are either smith* or jones*. The pipe (|) character is the or operator.

• (&(givenname>=j*)(givenname<=o*))

  Searches for people whose names begin with j, k, l, m, n, and o. The less than (<) and greater than or equal to (<=) characters specify the range.

For more information on LDAP filters, see the Netscape Directory Server Administrator's Guide.

Records to retrieve. The search returns the number of records specified in the "Records to retrieve" box. To obtain the next specified number of records, you click the More button. By default, the amount of records to retrieve is 1000. You can modify this default in the preferences.ini file, which is located in the builder folder. To modify this value, add this line to the file:

defaultSearchSize = number

where number is the amount of records you want displayed by default.

The Field Role Dialog Box

A field role is a role represented as a data field. For a particular process instance, the application uses the value in the data field to determine the user associated with the field role. When you create a field role, Process Builder automatically creates a data field to store the user role.

A field role can be used in an application in either of two ways:

• You can have the end user select a user for the role through the userpicker widget on a form.

• You can set the field role using the functions setRoleById or setRoleByDN.

Figure 6-7 shows the Field Role dialog box:

Figure 6-7    The Field Role dialog box

The dialog box contains the following fields:

Name. The name of the role. This name also becomes the name of the mapped field. The value of this property must be unique among the groups, roles, and data fields that are defined within a given application.

The name can contain only alphanumeric characters with no spaces. It cannot be longer than 18 characters. It's best to use all lower case, and use the underscore character (_) as a separator. Also, do not use a name that is a reserved SQL keyword (for example, select, integer, etc.), or the LiveWire reserved words project, request, server, and client.

Description. The role's description.

Mapped to field. The database field to which you are mapping this role. This field is created automatically, and has the same name as the role. It has the class ID TextField.

Prioritizing Groups and Roles

---

After setting up your groups and roles, you can prioritize them. Usually they are prioritized from most specific to most general. A user can belong to more than one group or role in the same application. Therefore, the priorities determine which forms the user gets.

The priority you set for Groups and Roles determines what order they appear in the Form Access window. See Setting Access to Forms for more information. To set the order, perform the following steps:

1. In the application tree view, double-click the Groups and Roles folder.

   The Inspector window appears.

2. In the Inspector window, click the Transitions tab.

   You see all the groups and roles listed, as shown in Figure 6-8:

Figure 6-8    Group and Role Order window

The assignee role is always at the top of the list, and the all role is at the bottom. You cannot change the priorities for these two.

3. To change the priority of a group or role, select it.

4. Click the Up and Down arrows to move the groups and roles. Items at the top of the list have the highest priority.

   For example, a user who belongs to both the HR Dept group and the Manager group in the example above gets the form for the HR Dept if it exists. If not, then the user gets the form for the Manager group. If that form doesn't exist, then the user gets the form for "all."

5. Close the window when you're done. Your changes are saved automatically.

The order you set in this window shows up in the Form Access window for forms.

Deleting Groups and Roles

---

To delete a group or role, follow these steps:

1. In the application tree view, select the group or role.

2. Right-click and choose Delete, or choose Delete from the File menu.

After deleting a field role, you must also delete the corresponding field. However, you cannot delete a field if you have already deployed your application to the Production stage.