You want to customize the set of UI components (actions or other UI elements) that the administrators of the site, organization or containers can manage using the role-based visibility feature.

The role-based UI functionality enables administrators to optimize the number of actions presented to users, so as not to confuse users by seeing actions they don’t need or use for their role. Initially this support was just for container managers (in particular, project managers). It has been extended to a concept called profiles which sets action visibility at the site or organization level.

A site administrator, organization administrator or container administrator can specify which users have visibility to the actions defined. For site and organization administrators this can be done through profiles. Profiles can be created at Site->Profiles or Org->Profiles. The actions defined will be presented with their default settings, and the administrator can choose to hide those actions. The administrator can then specify which participants (users, groups, orgs) belong to the profile. All members of the profile will have that visibility. If a member is in multiple profiles, the greatest visibility is provided.

At the container level, the administrator can specify the visibility based on user roles. Anyone in those roles will have the visibility specified. Container-level role visibility will override any profile in which the member might be a participant.

See About Configuring Action Visibility by Role for more details about profile and role-based visibility administration.

When configuring visibility by roles and configuring profiles, the administrator is presented with a list of UI components that can be managed. The administrator is unable to manage the visibility for any UI components that are not included in this list.

As a customizer, you have the ability to customize the list of UI components available to administrators. You can:

At the site or organization level your intention is to manage the list presented when creating profiles:

At the container level, you are managing the equivalent list presented when configuring visibility by roles:

Modify the roleaccessprefs.xml file (and associated files as needed).

To achieve this objective, you need to have an understanding of the following:

In actions.xml (and all *actions.xml files), an action can be assigned a uicomponent attribute value. The uicomponent attribute provides a name for a UI component that can be referenced from the roleaccessprefs.xml and roleAccessResource.rbInfo files. Multiple actions can use the same uicomponent value; this provides the ability to manage those actions as a single UI component. If an action does not have a uicomponent, then the action name can be used to reference it as a UI component instead. However, in this case it cannot be grouped with other actions into a single UI component.

The roleaccessprefs.xml file consists of a <uics> element containing several elements (or sections) that correspond to the primary tabs in the Windchill user interface. For example, the <project> section corresponds to the Project tab. Each section contains zero or more <uic> elements, each representing a UI component whose visibility within that tab can be administered. Each UI component, specified with the name attribute of the <uic> element, can appear in one or more sections. This allows the default visibility settings for that UI component to be assigned independently for different tabs.

The roleaccessprefs.xml file applies to the UI component lists for visibility administration based both on profiles (at the site and organization levels) and on roles (at the container levels). However, the <global> section applies only to visibility administration using profiles. If a UI component is not tied to a specific tab (such as is the case with the Search link in the Windchill UI header) or the UI component is a first-level tab itself, it should be listed in the <global> section of roleaccessprefs.xml.

Each UI component must have an entry in roleAccessResource.rbInfo that provides a user-friendly label for that UI component. These labels are used for the UI components in the lists that are presented to the administrator when configuring visibility. In this file the resource entry constant identifies the UI component; it must match either the uicomponent from the action definition or the action name if the action has no uicomponent. The resource entry value provides the user-friendly label.

In this example, you provide the administrator with the ability to manage the visibility of the Create Folder action in the Project, Program, Product, and Library tabs.

Steps 1 through 3 above can be performed in any order. Note that “PROJECT_CREATE_FOLDERS” is used for the uic name, the resource entry constant (but without the quotes), and the action uicomponent. It is necessary for all three of these items to share the same value in order to tie the customized behavior together.

Upon completion of this procedure, an administrator can now configure the visibility to the Create Folder action under the Project, Program, Product, and Library tabs, based on profiles defined at the site or organization level, and based on roles at the container level.

Each UIC in roleaccessprefs.xml represents a UIComponent or action to be controlled.

Making a customized action available to visibility administration is essentially the same procedure as making an out of the box action available. A tab, however, cannot be managed by container administrators (configuring role-based visibility). Therefore you can only make a customized tab available to site and organization administrators for configuring visibility profiles. This means you can add a <uic> element for the tab only to the <global> section of roleaccessprefs.xml. For example, assume that you have already created a customized tab, and have an associated <MyTab>actions.xml file. You can add the tab to the list for profile-based visibility administration as follows:

If you want to tie one UI component to multiple actions, you need to specify the uicomponent attribute for each of those actions, using the same value. For example, the procedure described in the section "Procedure – Making an Action Available to Visibility Administration" creates a UI component called PROJECT_CREATE_FOLDERS associated with the folder_create action. You can assign the list_create_folder action to the same UI component by specifying the uicomponent attribute for that action in actions.xml as follows:

As a result, the “Create Folders” entry in the Configure Roles and Create Profile pages will affect the visibility for both folder_create and list_create_folder actions.

You can alter the label used for a UI component in the Configure Roles or Create Profile pages, without making any other changes to that UI component. Simply change the associated resource entry value in the roleAccessResource.rbInfo file, and regenerate your bundles. For example:

Example of multiple actions using the same uicomponent: The Team pages in Product/Project/Library share the same code, but each action is defined separately for each object. Each action has the same uicomponent of “PROJECT_TEAM”. This allows the same resource (rbInfo) entry to be used, and helps to minimize the size of the action display table in the Create Profile page. PROJECT_TEAM still needs to be defined in roleaccessprefs.xml for each tab type in which it is used, and different defaults can be set for each.