基本自訂 > User Interface Customization > Generic UI Customizations > Customizing Role-Based UI Functions - Attribute Visibility
  
Customizing Role-Based UI Functions - Attribute Visibility
Objective
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.
Background
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.
Scope/Applicability/Assumptions
The role-based visibility administration capability is turned on, that is, the preference com.ptc.netmarkets.roleAccess.enabled is set to true. The customization can be performed while the capability is turned off, but the results will not appear in the UI until the capability is turned on.
The customizer can manage both OOTB UI components and customized UI components with this capability.
Intended Outcome
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:
add UI components to the list,
remove UI components from the list,
specify default visibility settings for UI components,
change the order that UI components appear in the list, and
change the labels for the UI components on the list.
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:
Solution
Modify the roleaccessprefs.xml file (and associated files as needed).
Prerequisite Knowledge
To achieve this objective, you need to have an understanding of the following:
The behavior of user roles in Windchill
The administration of ad hoc access control policies in Windchill
The actions framework in the Windchill client architecture
The navigation framework in the Windchill client architecture
The management of XML file customizations
The management of RBINFO file customizations
* 
The Additional Resources section below includes references to many or all of these subjects.
Solution Elements
Element
Type
Description
*actionModels.xml
XML
Files which define the models where actions are used. If an action is not already defined in a model, one will need to be created for the validation code to find the action and properly set visibility. actionmodels.xml is located in <Windchills>/codebase; other *actionmodels.xml files are generally in <Windchill>/codebase /config/actions
*actions.xml
XML
Files where actions and other UI components are defined. Actions are optionally given a uicomponent value.
actions.xml is located in <Windchill>/codebase /config/actions along with other *actions.xml files.
roleaccessprefs.xml
XML
File for assigning default visibility to UI components. Setting items in this file can make them not appear at all for the site or containers. Whether or not the container manager can override the default value can also be changed here.
Located in <Windchill>/codebase.
roleAccessResource. rbInfo
XML
Defines the labels to provide in the Uis for the actions or UI components.
Located in <Windchill>/wtCustom/ com/ptc/netmarkets/roleAccess/.
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.
* 
Your UI component label should be a verb phrase. If your action/UI component name is not already a verb phrase, place ‘View’ in front, for example “View Team Page.”
Procedure – Making an Action Available to Visibility Administration
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.
* 
This example assumes that the Create Folder action is not already available for role-based visibility management; in the actual product, it is available out of the box.
1. Add a new <uic> to the roleaccessprefs.xml under the sections <project>, <program>, <product>, and <library>:
<uic name=”PROJECT_CREATE_FOLDERS” order=”00” enabled=”true” defaultAll=
”true”
defaultManager=”true” defaultGuest=”false” managerEnabled=”true” guestEn
abled=”false”/>
* 
See the section on the uic element below for attribute descriptions.
* 
For actions that are valid for multiple tab types, put the entry under all the sections you want it to affect.
2. In roleAccessResource.rbInfo, add a new resource entry for the action display name:
31.value=Create Folders
31.constant=PROJECT_CREATE_FOLDERS
Regenerate your bundles. The name of the uic should be the same as the constant for the entry in the resource bundle.
3. In <Windchill>/codebase/config/actions/actions.xml, modify the create folder action by: adding the attribute uicomponent=”PROJECT_CREATE_FOLDERS”
<action name=” folder_create” checkaccess=”true”
uicomponent=”PROJECT_CREATE_ FOLDERS”>
* 
Follow best practices in backing up your XML files when customizing them.
4. Restart the servlet engine and the method server.
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.
Customization Points
uic Element
Each UIC in roleaccessprefs.xml represents a UIComponent or action to be controlled.
Parameter
Default Value
Possible Values
Req?
Description
name
n/a
string
Y
The name of the UI component. This must match the value of the uicomponent (or name) attribute on an action element in actions.xml. This must also match the value of a resource entry constant in the resource bundle.
order
n/a
Integer
N
The position of this UI component in the wizard. UI components with lower numbers are placed before those with higher numbers.
enabled
true
true | false
N
Whether or not this uicomponent will be shown in the wizard and utilized by the system.
defaultAll
true
true | false
N
The default visibility value for All Members.
defaultManager
true
true | false
N
The default visibility value for Project Managers.
* 
The permissions are a union of all permissions across all roles; if you set defaultManager to false; you should also defaultAll to false, otherwise managers will still have access through the ALL_MEMBERS role.
defaultGuest
true
true | false
N
The default visibility value for people in the Guest role.
* 
Guests are not technically members of the Project; they are not unioned with the ALL_MEMBERS role.
managerEnabled
true
true | false
N
Whether or not this uicomponent can affect the manager role. Do not change this value in out-of-the-box UICs. For customized UICs, you may choose your own setting.
guestEnabled
true
true | false
N
Whether or not this uicomponent can affect the guest role. Do not change this value in out-of-the-box UICs. For customized UICs, you may choose your own setting.
Making a Customized Tab Available to Visibility Administration
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:
1. Add a new uic element to roleaccessprefs.xml under the <global> section with a unique name, for example, CUSTOMIZED_TAB.
<uic name=”CUSTOMIZED_TAB” order=”190” enabled=”true” defaultAll=”true”/>
2. Associate the appropriate actions in action.xml with the UIComponent.
<ooleanpe name=”customization” >

<action name=”list2” uicomponent=”CUSTOMIZED_TAB”>
<command windowType=”page”/>
</action>
3. Add a new entry to roleAccessResource.rbInfo with a constant that is the same as the uic name. The value is what will be displayed in the profile actions UI.
40.value=View Customized Tab

40.constant=CUSTOMIZED_TAB
Regenerate your bundles.
4. Restart the servlet engine and the MethodServer.
Assigning One uicomponent to Multiple Actions
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:
<action name=”list_create_folder”
uicomponent=”PROJECT_CREATE_FOLDERS” ajax=”row”>
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.
Changing the Labels for a UI Component
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:
31.value=Create Folders - My New Label

31.constant=PROJECT_CREATE_FOLDERS
Sample Code
Examples of Usage in OOTB Code
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.
Additional Resources
Related Customization Documentation
Managing Customizations
Other Related Windchill Documentation
About Configuring Action Visibility by Role
Access Control
Generic UI Customizations