在 JCA 中配置参与者选取器
目标
参与者选取器使您能够使用各种搜索条件搜索参与者，并能够选取选择性参与者。
背景
当前选取参与者的方法仅限于用户和组，且在 Windchill 中不一致。新的参与者选取器公用组件在 Windchill 中的行为一致。参与者选取器使您能够搜索类型为用户、组和组织的参与者。提供了各种各样的搜索范围条件，使您能够缩小搜索范围。
 |
本主题介绍了如何在 JCA 表格中自定义基于 JCA 的参与者选取器以供使用。在 Windchill 11.0 中，已引入基于 AngularJS 的新参与者选取器，PTC 建议将其用于基于 AngularJS、HTML 或 Javascript 的独立单页应用程序。有关详细信息，请参阅在 AngularJS 中配置参与者选取器。
|
范围/适用性/假设
• 在 Windchill 客户端体系结构表格中使用时：您应定义 Windchill 客户端体系结构操作，并将该操作指向具有参与者选取器标记的 JSP 页面。为参与者选取器标记提供 "action Class" 和 "action Method" 必需属性。在所需的 Windchill 客户端体系结构表格中添加创建的 Windchill 客户端体系结构操作。单击该操作时，将启动参与者选取器向导。选择所需的参与者，然后单击“确定”。选取器将调用已提供的 action Class 的 action Method。在该方法中，您将以所需的方式耗用或处理选定的参与者。
• 将参与者选取器与特性选取器配合使用时：假定您了解如何使用特性选取器。特性选取器的操作属性应指向具有参与者选取器标记的 JSP 页面。必需属性 "action Class" 应为 "" (空)，"action Method" 应为 "JavaScript:${pickerCallback}()"。${pickerCallback} 是您提供给特性选取器的 pickerCallback JavaScript 函数。在向导中选择所需的参与者并单击“确定”后，将使用包含已选取参与者的 JSON 对象调用 pickerCallback JavaScript 函数。
预期结果
选定的参与者可在 Windchill 客户端体系结构表格或在特性选取器的文本框中进行填充。
解决方案
使用参与者选取器搜索参与者，并将选定的参与者添加到 Windchill 客户端体系结构表格中或特性选取器的文本框中。
必备知识
要实现此目标，需要了解以下内容：
• 如何在 Windchill 客户端体系结构表格中添加 Windchill 客户端体系结构操作，以及如何动态更新表格中的选定参与者。
• 如何配置特性选取器，以及如何编写 JavaScript 选取器回调函数。
解决方案元素
|
元素
|
类型
|
说明
|
|---|---|---|
|
actionClass
|
标记属性
|
需要在处理选定的参与者时调用的操作类的名称。
|
|
actionMethod
|
标记属性
|
需要在处理选定的参与者时调用的操作方法的名称。
|
|
select
|
标记属性
|
此元素可用于确定选取器是允许多选 ("multi")，还是仅允许单选 ("single")。
|
|
participantType
|
标记属性
|
使用此元素可将默认值设置为任何参与者类型。com.ptc.core.components.beans.
PrincipalBean 类定义了四个字符串常量，每个常量均可传递到该属性。所述常量为 ALL_PARTICIPANT、USER、GROUP 和 ORG。
|
|
singleParticipantType
|
标记属性
|
使用此元素可将 participantType 标记属性中指定的默认参与者类型设置为唯一支持的类型。其取值为 true/false。其值设置为 true 时，参与者类型将被限制为 participantType 属性中指定的单一类型。其值设置为 false 或未指定时，选取器支持 ALL_PARTICIPANT、USER、GROUP 和 ORG 参与者类型。
|
|
associationMap
|
标记属性
|
此映射包含要在关联下拉列表中显示的关联键值对。键是在选择任何关联时返回给用户的 Java 字符串文字。值是在关联下拉列表中显示的本地化字符串。
|
|
defaultAssociation
|
标记属性
|
想要在下拉列表中预先选择的关联应在此属性中进行传递。
|
|
associationLabel
|
标记属性
|
关联的显示标签的本地化字符串。
|
|
emailAllowed
|
标记属性
|
将其设置为 "true" 可呈现电子邮件文本框。可以键入您想要邀请的任何逗号或空格分隔电子邮件。
|
|
contextMap
|
标记属性
|
想要在其中执行“搜索范围”操作的上下文列表。此映射包含要在“搜索范围”下拉列表中显示的上下文键值对。键是表示 Windchill 对象 OID 的 Java 字符串文字。值是在“搜索范围”下拉列表中显示的本地化字符串。
|
|
filterEmail
|
标记属性
|
如果在搜索用户时将此属性设置为 "true"，则仅返回具有电子邮件地址的用户。默认值为 "false"。
|
|
recentAllowed
|
标记属性
|
将其设置为 "false" 可防止呈现最近的参与者文本框。默认值为 "true"。
|
|
applicationContextSearch
|
标记属性
|
如果在搜索用户时将此属性设置为 "true"，则仅返回指定应用程序上下文中的用户。默认值为 "false"。
|
|
defaultContext
|
标记属性
|
想要在下拉列表中预先选择的上下文应在此属性中进行传递。
|
|
serviceMap
|
标记属性
|
传递 LDAP 服务器的列表可执行搜索。默认情况下，不提供此属性。此映射包含要在“服务”下拉列表中显示的上下文键值对。键是表示 LDAP 服务器的 Java 字符串文字。值是在“服务”下拉列表中显示的本地化字符串。
|
|
includeInternal
|
标记属性
|
将其设置为 "true" 可搜索内部组。默认值为 "false"。
|
|
disableRestrictedSearchScope
|
标记属性
|
将其设置为 "true" 可绕过组织中设置的受限搜索范围。默认值为 "false"。
|
|
enforceRestrictedSearchScope
|
标记属性
|
无论其在组织中的设置为何，只要将其设置为 "true" 即可强制受限制的搜索范围。默认值为 "false"。
|
|
showRoles
|
标记属性
|
将其设置为 "true" 可在搜索时添加筛选器，以将搜索范围限制为选定角色。仅当类型选项为“用户”时，才会显示此选项。
其值为 true 时，将在搜索条件中提供可用角色的下拉列表。这些角色将来自于上下文中传递的值。
默认值为 "false"。
|
|
resourcePool
|
标记属性
|
此元素将用于提供要搜索的承担者的池。
所有访问控制规则仍将适用。
|
|
searchProfileGroups
|
标记属性
|
将其设置为 "true" 可以仅搜索系统中的配置文件组。
默认值为 "false"。
|
|
searchDisconnectedPrincipals
|
标记属性
|
将其设置为 "PrincipalBean.LDAP" 可在 LDAP 中仅搜索断开连接的承担者。
将其设置为 "PrincipalBean.DB" 可在 DB 中仅搜索断开连接的承担者。
默认值为 "false"。
|
|
title
|
标记属性
|
此元素将用于提供参与者选取器窗口的标题。
默认值为 "Find Participant"。
|
|
showSearchIn
|
标记属性
|
此元素将用于确定是否在参与者选取器中显示“搜索范围:”字段。默认值为 "true" 可保留现有功能。
|
|
helpSelectorKey
|
标记属性
|
此元素将用于设置选取器的帮助链接，如果未提供任何内容，则将默认为 ParticipantPickerHelp 的 service.properties 值。
|
|
enforceModifyPermission
|
标记属性
|
此元素将用于筛选搜索结果，以仅返回当前用户具有 MODIFY 权限的对象。
|
过程 - 在参与者选取器中提供关联
您想要在参与者选取器中包括关联。需要将标记属性 associationMap、defaultAssociation 和 associationLabel 提供给参与者选取器标记。
下面示例代码中的第二个示例介绍了如何将关联添加到参与者选取器的代码示例。
过程 - 包含“在上下文内搜索”的参与者选取器
您想要将搜索范围缩小到不同的上下文。需要将标记属性 contextMap 和 defaultContext 提供给参与者选取器标记。上下文可以是“组织”、“站点”、“产品”、“项目”和“存储库”。
过程 - 在其他 LDAP 中搜索参与者
您想要在其他 LDAP 中搜索参与者。需要提供 serviceMap 标记属性。
配置 Windchill 以支持多个 LDAP 服务器。每个 LDAP 服务器都将由一个名称来标识。必须以键的形式提供 LDAP 服务器的名称，而以值的形式提供本地化的显示标签。当您提供 serviceMap 时，您会在参与者选取器中看到一个下拉列表，其中包含 "Service" 标签。参与者选取器会将选定的键作为服务参数发送给 Info*Engine 任务。
过程 - 在参与者选取器中提供电子邮件邀请
您想要在参与者选取器中添加电子邮件邀请文本框。需要设置标记属性 emailAllowed="true"。
下面示例代码一节中的第三个示例介绍了如何在参与者选取器中获取电子邮件邀请文本框的代码示例。
过程 - 单选参与者选取器
您想要一次只选择一个参与者。需要设置标记属性 select="single"。这会将参与者选择列表呈现为每次可保存一个值的文本框。
过程 - 限制为单一参与者类型搜索
您想要将搜索的参与者类型数量限制为一个。需要设置标记属性 singleParticipantType="true"。
示例代码
包含参与者选取器标记的示例 JSP
为用于启动参与者选取器的操作创建条目后，编写与操作标记同名的 JSP (例如 participantPickerSample.jsp)。
<%@ page import="com.ptc.windchill.enterprise.picker.principal.PrincipalBean"%>
<%@ taglib uri="http://java.sun.com/jsp/jstl/core" prefix="c"%>
<%@ taglib uri="http://www.ptc.com/windchill/taglib/components" prefix="jca"%>
<jca:participantPicker
actionClass="com.ptc.netmarkets.principal.CustomPrincipalCommands"
actionMethod="addPrincipal"
participantType="<%= PrincipalBean.GROUP %>">
>
</jca:participantPicker>
-
<%@ taglib uri="http://java.sun.com/jsp/jstl/core" prefix="c"%>
<%@ taglib uri="http://www.ptc.com/windchill/taglib/components" prefix="jca"%>
<jca:participantPicker
actionClass="com.ptc.netmarkets.principal.CustomPrincipalCommands"
actionMethod="addPrincipal"
participantType="<%= PrincipalBean.GROUP %>">
>
</jca:participantPicker>
-
接下来将呈现如下所示的基本参与者选取器。
根据搜索条件执行搜索。将所需参与者移至参与者列表，然后单击“确定”。此组件会调用参与者选取器标记属性 actionClass 和 actionMethod。需要在 actionClass 中写入 actionMethod。下面给出了示例代码。
public class CustomPrincipalCommands {
public static FormResult addPrincipal(NmCommandBean cb) throws WTException {
FormResult result = new FormResult(FormProcessingStatus.SUCCESS);
result.setNextAction(FormResultAction.REFRESH_OPENER);
String principals = cb.getTextParameter(PrincipalBean.PARAM_SELECTED_PRINCIPALS);
if (principals == null) {
result.setStatus(FormProcessingStatus.FAILURE);
return result;
}
ArrayList<String> selectedPrincipals = new ArrayList<String>();
int start = 0;
int pos = principals.indexOf("#", start);
while (pos != -1) {
String principal = principals.substring(start, pos);
selectedPrincipals.add(principal);
start = pos + 1;
pos = principals.indexOf("#", start);
}
// Now process selectedPrincipals
return result;
}
}
public static FormResult addPrincipal(NmCommandBean cb) throws WTException {
FormResult result = new FormResult(FormProcessingStatus.SUCCESS);
result.setNextAction(FormResultAction.REFRESH_OPENER);
String principals = cb.getTextParameter(PrincipalBean.PARAM_SELECTED_PRINCIPALS);
if (principals == null) {
result.setStatus(FormProcessingStatus.FAILURE);
return result;
}
ArrayList<String> selectedPrincipals = new ArrayList<String>();
int start = 0;
int pos = principals.indexOf("#", start);
while (pos != -1) {
String principal = principals.substring(start, pos);
selectedPrincipals.add(principal);
start = pos + 1;
pos = principals.indexOf("#", start);
}
// Now process selectedPrincipals
return result;
}
}
应将静态方法编写为 actionMethod。其中将仅使用一个自变量，即 NmCommandBean。选定的参与者会作为文本参数发送到此方法。在此组件中，这些值存储在隐藏的变量中。隐藏变量的名称在 "com.ptc.windchill.enterprise.picker.principal.PrincipalBean" 中定义为 static String。要提取选定的参与者，请使用 PrincipalBean.PARAM_SELECTED_PRINCIPALS。这将返回 "#" 分隔的 DN (可分辨名称)。
添加关联
要在参与者选取器中添加关联，需在以下示例中提供突出显示的三个属性。associationMap 属性取值 LinkedHashMap。为此映射提供键值对。键是 java 字符串文字。当用户选择一个关联时，此键字符串文字会作为文本参数传递回 actionMethod。值是显示在下拉列表中的本地化字符串。在下拉列表中显示时，此组件使用 LinkedHashMap 来保留键值对的添加顺序。
<%@ taglib uri="http://java.sun.com/jsp/jstl/core" prefix="c"%>
<%@ taglib uri="http://www.ptc.com/windchill/taglib/components" prefix="jca"%>
<%@ page import="java.util.LinkedHashMap"%>
<%@ page import = "com.ptc.windchill.enterprise.picker.principal. PrincipalBean" %>
<%
LinkedHashMap associationMap = new LinkedHashMap();
associationMap.put("GUEST", "Guest");
associationMap.put("MEMBERS", "Members");
associationMap.put("PROJECT MANAGER", "Project Manager");
%>
<c:set var="associationMap" value="<%= associationMap %>"/>
<c:set var="participantType" value="<%= PrincipalBean.USER %>"/>
<jca:participantPicker
actionClass="com.ptc.netmarkets.principal.CustomPrincipalCommands"
actionMethod="addPrincipal"
participantType="${participantType}"
emailAllowed="true"
defaultAssociation="GUEST"
associationMap="${associationMap}"
associationLabel="Add to Role"
>
</jca:participantPicker>
<%@ taglib uri="http://www.ptc.com/windchill/taglib/components" prefix="jca"%>
<%@ page import="java.util.LinkedHashMap"%>
<%@ page import = "com.ptc.windchill.enterprise.picker.principal. PrincipalBean" %>
<%
LinkedHashMap associationMap = new LinkedHashMap();
associationMap.put("GUEST", "Guest");
associationMap.put("MEMBERS", "Members");
associationMap.put("PROJECT MANAGER", "Project Manager");
%>
<c:set var="associationMap" value="<%= associationMap %>"/>
<c:set var="participantType" value="<%= PrincipalBean.USER %>"/>
<jca:participantPicker
actionClass="com.ptc.netmarkets.principal.CustomPrincipalCommands"
actionMethod="addPrincipal"
participantType="${participantType}"
emailAllowed="true"
defaultAssociation="GUEST"
associationMap="${associationMap}"
associationLabel="Add to Role"
>
</jca:participantPicker>
上述代码将呈现关联下拉列表，如下图所示。
在上述示例中，您将尝试为参与者添加角色。将所需参与者移动到参与者列表，从关联列表中选择一个角色，然后单击“确定”。actionMethod 代码将如下所示。
public class CustomPrincipalCommands {
public static FormResult addPrincipal(NmCommandBean cb) throws WTException {
FormResult result = new FormResult(FormProcessingStatus.SUCCESS);
result.setNextAction(FormResultAction.REFRESH_OPENER);
String principals = cb.getTextParameter(PrincipalBean.PARAM_SELECTED _PRINCIPALS);
if (principals == null) {
result.setStatus(FormProcessingStatus.FAILURE);
return result;
}
ArrayList<String> selectedPrincipals = new ArrayList<String>();
int start = 0;
int pos = principals.indexOf("#", start);
while (pos != -1) {
String principal = principals.substring(start, pos);
selectedPrincipals.add(principal);
start = pos + 1;
pos = principals.indexOf("#", start);
}
String role = cb.getTextParameter(PrincipalBean.PARAM_ASSOCIATION);
ArrayList result = NmRoleHelper.service.addUsersToRole(cb, role, selectedPrincipals);
return result;
}
}
public static FormResult addPrincipal(NmCommandBean cb) throws WTException {
FormResult result = new FormResult(FormProcessingStatus.SUCCESS);
result.setNextAction(FormResultAction.REFRESH_OPENER);
String principals = cb.getTextParameter(PrincipalBean.PARAM_SELECTED _PRINCIPALS);
if (principals == null) {
result.setStatus(FormProcessingStatus.FAILURE);
return result;
}
ArrayList<String> selectedPrincipals = new ArrayList<String>();
int start = 0;
int pos = principals.indexOf("#", start);
while (pos != -1) {
String principal = principals.substring(start, pos);
selectedPrincipals.add(principal);
start = pos + 1;
pos = principals.indexOf("#", start);
}
String role = cb.getTextParameter(PrincipalBean.PARAM_ASSOCIATION);
ArrayList result = NmRoleHelper.service.addUsersToRole(cb, role, selectedPrincipals);
return result;
}
}
您可以从文本参数中提取选定关联，如上述代码中突出显示。
添加电子邮件订阅
用于获取电子邮件订阅的标记代码将如下所示。
<%@ taglib uri="http://java.sun.com/jsp/jstl/core" prefix="c"%>
<%@ taglib uri="http://www.ptc.com/windchill/taglib/components" prefix="jca"%>
<%@ page import="java.util.LinkedHashMap"%>
<%@ page import = "com.ptc.windchill.enterprise.picker.principal. PrincipalBean" %>
<%
LinkedHashMap associationMap = new LinkedHashMap();
associationMap.put("GUEST", "Guest");
associationMap.put("MEMBERS", "Members");
associationMap.put("PROJECT MANAGER", "Project Manager");
%>
<c:set var="associationMap" value="<%= associationMap %>"/>
<c:set var="participantType" value="<%= PrincipalBean.USER %>"/>
<jca:participantPicker
actionClass="com.ptc.netmarkets.principal.CustomPrincipalCommands"
actionMethod="addPrincipal"
participantType="${participantType}"
emailAllowed="true"
defaultAssociation="GUEST"
associationMap="${associationMap}"
associationLabel="Add to Role"
>
</jca:participantPicker>
<%@ taglib uri="http://www.ptc.com/windchill/taglib/components" prefix="jca"%>
<%@ page import="java.util.LinkedHashMap"%>
<%@ page import = "com.ptc.windchill.enterprise.picker.principal. PrincipalBean" %>
<%
LinkedHashMap associationMap = new LinkedHashMap();
associationMap.put("GUEST", "Guest");
associationMap.put("MEMBERS", "Members");
associationMap.put("PROJECT MANAGER", "Project Manager");
%>
<c:set var="associationMap" value="<%= associationMap %>"/>
<c:set var="participantType" value="<%= PrincipalBean.USER %>"/>
<jca:participantPicker
actionClass="com.ptc.netmarkets.principal.CustomPrincipalCommands"
actionMethod="addPrincipal"
participantType="${participantType}"
emailAllowed="true"
defaultAssociation="GUEST"
associationMap="${associationMap}"
associationLabel="Add to Role"
>
</jca:participantPicker>
上述代码将呈现电子邮件订阅字段，如下图所示。
启动选取器并将选取器值发送回文本框的示例 JSP。
可以使用特性选取器标记来呈现文本框，以及使用“查找”按钮来启动参与者选取器。“查找”按钮必须在 actions.xml 中声明，如上面各节中所述。默认情况下，特性选取器提供一个 JavaScript 回调函数，由选取器调用以从任何选取器中发送回已选取的值。特性选取器还具有定义可由选取器调用的自定义 JavaScript 函数的功能。例如：
<p:propertyPicker label="${label}" field="${textbox}" action="participantPickerSample2" type="participantpicker">
<p:populate from="${displayAttribute}" to="${displayFieldId}"/>
<p:populate from="oid" to="${id}" />
<p:pickerParam name="pickerId" value="${id}" />
<p:pickerParam name="objectType" value="wt.org.WTGroup"/>
<p:pickerParam name="componentId" value="${componentId}"/>
<p:pickerParam name="pickedDataFetcher" value="${pickedDataFetcher}" />
<p:pickerParam name="pickerCallback" value="${pickerCallBack}" />
<p:pickerParam name="containerRef" value="${containerRef}"/>
<p:pickerParam name="baseWhereClause" value="${baseWhereClause}" />
<p:pickerParam name="pickerTitle" value="${pickerTitle}"/>
<p:pickerParam name="multiSelect" value="${multiSelect}"/>
</p:propertyPicker>
<p:populate from="${displayAttribute}" to="${displayFieldId}"/>
<p:populate from="oid" to="${id}" />
<p:pickerParam name="pickerId" value="${id}" />
<p:pickerParam name="objectType" value="wt.org.WTGroup"/>
<p:pickerParam name="componentId" value="${componentId}"/>
<p:pickerParam name="pickedDataFetcher" value="${pickedDataFetcher}" />
<p:pickerParam name="pickerCallback" value="${pickerCallBack}" />
<p:pickerParam name="containerRef" value="${containerRef}"/>
<p:pickerParam name="baseWhereClause" value="${baseWhereClause}" />
<p:pickerParam name="pickerTitle" value="${pickerTitle}"/>
<p:pickerParam name="multiSelect" value="${multiSelect}"/>
</p:propertyPicker>
返回到参与者选取器，当在特性选取器中启动参与者选取器时，可将 JavaScript 回调 函数名称作为请求参数。
<c:set var="pickerCallback" value="<%=request.getParameter("pickerCallback")%>"/>
<jca:participantPicker
actionClass=""
actionMethod="JavaScript:${pickerCallback}()"
participantType="<%= PrincipalBean.GROUP %>"
<jca:participantPicker>
<jca:participantPicker
actionClass=""
actionMethod="JavaScript:${pickerCallback}()"
participantType="<%= PrincipalBean.GROUP %>"
<jca:participantPicker>
将空白字符串传递给参与者选取器的 actionClass 属性。从请求参数获取的 JavaScript 回调函数名称会附加到 "JavaScript:" 字符串，并作为值传递给 actionMethod。此 "JavaScript:" 字符串在选取器内部用于标识，因为需要使用 PickerCallBack 机制。用户选择所需的参与者并单击“确定”后，这些值会作为 JSON 对象发送回 JavaScript 函数 (如特性选取器中所定义)。
Windchill 代码中的使用示例
所有位置均位于 \Windchill\codebase\netmarkets\jsp 中：
• \roleAccess\profile_addMembers.jsp
• \subscription\subscrPrincipalPicker.jsp
• \team\addUsersToRole.jsp
• \object\findParticipant.jsp
• \work\addUsersToRole.jsp (resourcePool)
• \principal\find_disconnected.jsp (searchDisconnectedPrincipals)
• \group\addProfileToList.jsp (enforceModifyPermission & searchProfileGroups)
• \user\addToAdmin.jsp (enforceRestrictedSearchScope)
• \agreements\findParticipant.jsp (disableRestrictedSearchScope)