在 JCA 中配置参与者选取器
目标
参与者选取器使您能够使用各种搜索条件搜索参与者,并能够选取选择性参与者。
背景
参与者选取器使您能够搜索类型为用户、组和组织的参与者。提供了各种各样的搜索范围条件,使您能够缩小搜索范围。
范围/适用性/假设
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 类定义了四个字符串常量,每个常量均可传递到该属性。所述常量为 ALL_PARTICIPANT、USER、GROUP 和 ORG。
使用此元素可将默认值设置为任何参与者类型。com.ptc.windchill.enterprise.picker.principal.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
标记属性
传递目录服务列表以执行搜索。默认情况下,不提供此属性。此映射包含要在“服务”下拉列表中显示的上下文键值对。键是表示目录服务器的 Java 字符串文字。值是在“服务”下拉列表中显示的本地化字符串。
includeInternal
标记属性
将其设置为 "true" 可搜索内部组。默认值为 "false"。
disableRestrictedSearchScope
标记属性
将其设置为 "true" 可绕过组织中设置的受限搜索范围。默认值为 "false"。
enforceRestrictedSearchScope
标记属性
无论其在组织中的设置为何,只要将其设置为 "true" 即可强制受限制的搜索范围。默认值为 "false"。
showRoles
标记属性
将其设置为 "true" 可在搜索时添加筛选器,以将搜索范围限制为选定角色。仅当类型选项为“用户”时,才会显示此选项。
其值为 true 时,将在搜索条件中提供可用角色的下拉列表。这些角色将来自于上下文中传递的值。
默认值为 "false"。
resourcePool
标记属性
此元素将用于提供要搜索的承担者的池。
所有访问控制规则仍将适用。
searchProfileGroups
标记属性
将其设置为 "true" 可以仅搜索系统中的配置文件组。
默认值为 "false"。
searchDisconnectedPrincipals
标记属性
将其设置为 "PrincipalBean.LDAP" 可在目录服务器中仅搜索断开连接的承担者。
将其设置为 "PrincipalBean.DB" 可在 DB 中仅搜索断开连接的承担者。
默认值为 "false"。
title
标记属性
此元素将用于提供参与者选取器窗口的标题。
默认值为 "Find Participant"。
showSearchIn
标记属性
此元素将用于确定是否在参与者选取器中显示“搜索范围:”字段。默认值为 "true" 可保留现有功能。
helpSelectorKey
标记属性
此元素将用于设置选取器的帮助链接,如果未提供任何内容,则将默认为 ParticipantPickerHelp 的 service.properties 值。
enforceModifyPermission
标记属性
此元素将用于筛选搜索结果,以仅返回当前用户具有 MODIFY 权限的对象。
过程 - 在参与者选取器中提供关联
您想要在参与者选取器中包括关联。需要将标记属性 associationMap、defaultAssociation 和 associationLabel 提供给参与者选取器标记。
下面“示例代码”部分中的第二个示例介绍如何将关联添加到参与者选取器的代码示例。
过程 - 包含“在上下文内搜索”的参与者选取器
您想要将搜索范围缩小到不同的上下文。需要将标记属性 contextMap 和 defaultContext 提供给参与者选取器标记。上下文可以是“组织”、“站点”、“产品”、“项目”和“存储库”。
过程 - 在其他目录服务器中搜索参与者
您想要在其他目录服务器中搜索参与者。需要提供 serviceMap 标记属性。
配置 Windchill 以支持多个目录服务器。每个目录服务器都将由一个名称来标识。必须以键的形式提供目录服务器的名称,而以值的形式提供本地化的显示标签。当您提供 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>
-
接下来将呈现如下所示的基本参与者选取器。
根据搜索条件执行搜索。将所需参与者移至参与者列表,然后单击“确定”。此组件会调用参与者选取器标记属性 actionClass 和 actionMethod。需要在 actionClass 中写入 actionMethod。下面给出了示例代码。
package com.ptc.core.components.rendering.guicomponents;
import java.util.List;
import com.ptc.core.components.forms.FormProcessingStatus;
import com.ptc.core.components.forms.FormResult;
import com.ptc.core.components.forms.FormResultAction;
import com.ptc.netmarkets.user.PrincipalPickerHelper;
import com.ptc.netmarkets.util.beans.NmCommandBean;
import com.ptc.windchill.enterprise.picker.principal.PrincipalBean;
import wt.util.WTException;
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;
}
List<String> selectedPrincipals = PrincipalPickerHelper.retrievePrincipalListFromPickerPrincipals(principals);
// 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>
上述代码将呈现关联下拉列表,如下图所示。
在上述示例中,您将尝试为参与者添加角色。将所需参与者移动到参与者列表,从关联列表中选择一个角色,然后单击“确定”。actionMethod 代码将如下所示。
package com.ptc.core.components.rendering.guicomponents;
import java.util.ArrayList;
import com.ptc.core.components.forms.FormProcessingStatus;
import com.ptc.core.components.forms.FormResult;
import com.ptc.core.components.forms.FormResultAction;
import com.ptc.netmarkets.role.NmRoleHelper;
import com.ptc.netmarkets.user.PrincipalPickerHelper;
import com.ptc.netmarkets.util.beans.NmCommandBean;
import com.ptc.windchill.enterprise.picker.principal.PrincipalBean;
import wt.util.WTException;
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 = (ArrayList) PrincipalPickerHelper
.retrievePrincipalListFromPickerPrincipals(principals);
String role = cb.getTextParameter(PrincipalBean.PARAM_ASSOCIATION);
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>
上述代码将呈现电子邮件订阅字段,如下图所示。
“最近的产品” > “团队” > “将参与者添加到团队中” > “查找参与者”下的 Email Invitation 输入框中输入的值进行验证:
单击 Add - 验证电子邮件格式。如果电子邮件格式不正确,则系统会显示错误消息。如果电子邮件格式正确,则系统会将用户成功添加到右侧的 Participant List 面板中。
单击 Ok - 验证 Atlas 中用户记录条目的电子邮件。如果 Atlas 中存在电子邮件,则系统会将用户添加到团队中的特定角色。如果 Atlas 中不存在电子邮件,则系统会在横幅级别显示错误消息。在下列情况下,系统会显示消息:
所有电子邮件均已成功添加到团队中。
未添加任何电子邮件。
仅添加了少数电子邮件,而未向团队中添加其他电子邮件。
启动选取器并将选取器值发送回文本框的示例 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>
返回到参与者选取器,在特性选取器中启动参与者选取器时,可获取 pickerCallback JavaScript 函数名称作为请求参数。
<c:set var="pickerCallback" value="<%=request.getParameter(\"pickerCallback\")%>"/>
<jca:participantPicker
actionClass=""
actionMethod="JavaScript:${pickerCallback}()"
participantType="<%= PrincipalBean.GROUP %>"
>
</jca:participantPicker>
将空白字符串传递给参与者选取器的 actionClass 属性。从请求参数获取的 JavaScript 回调函数名称会附加到 "JavaScript:" 字符串,并作为值传递给 actionMethod。此 "JavaScript:" 字符串在选取器内部用于标识,因为需要使用 PickerCallBack 机制。用户选择所需的参与者并单击“确定”后,这些值会作为 JSON 对象发送回 JavaScript 函数 (如特性选取器中所定义)。
解决方案元素示例
元素
类型
说明
custom.site.xconf
XCONF
此元素是 XCONF 文件,用于配置 wt.properties 文件中的特性。
在模块中的位置:
<customizationRootDirectory>/configurations/xconf
AcmePartClient-actions.xml
XML
用于定义系统中的操作的默认 XML 文件。
在模块中的位置:
<customizationRootDirectory>/module1/main/resources/Acme-actions
CustomPicker.jsp
JSP
用于配置参与者选取器和相关配置的 JSP 文件。示例包括选取器回调、参与者类型等。
在模块中的位置:
<customizationRootDirectory>/module1/main/src_web/netmarkets/jsp/custompart
defineCustomItemAttributesWizStep.jsp
JSP
用于配置 propertyPicker 标记以呈现文本框和查找按钮的 JSP 文件。
在模块中的位置:
<customizationRootDirectory>/module1/main/src_web/WEB-INF/jsp/custom/newwizard/custompart
用于自定义的模块化结构
<customizationRootDirectory>
├── configurations
│ ├── deploy.xml
│ └── xconf
│ └── custom.site.xconf
└── module1
├── descriptor.xml
└── main
├── resources
│ └── Acme-actions
│ └── AcmePartClient-actions.xml
└── src_web
├── netmarkets
│ └── jsp
│ └── custompart
│ └── customPicker.jsp
└── WEB-INF
└── jsp
└── custom
└── newwizard
└── custompart
└── defineCustomItemAttributesWizStep.jsp
Windchill 代码中的使用示例
所有位置均位于 \<WT_HOME>\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)
这对您有帮助吗?