开发人员指南 > 开发人员指南 > Codebeamer 开发 > 自定义工作流操作
自定义工作流操作
使用 Java 语言开发专属/自定义工作流操作时，需使用 Java 7 或更新的标准版 (SE) Java Development Kit (JDK) 外加以下框架/库：
框架/库
组件
版本
3.4
spring-core
5.3.x
spring-context
5.3.x
spring-beans
5.3.x
若要开发新的自定义工作流操作，还需要从 Codebeamer 7.8.0 或更新安装版本的 ~/CB-../tomcat/webapps/cb/WEB-INF/lib 目录下获取 cb.jar。工作流操作是 Java 类的方法。例如：创建新基线：


package com.intland.codebeamer.example.actions;

import javax.servlet.http.HttpServletRequest;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Component;

import com.intland.codebeamer.controller.ArtifactController;
import com.intland.codebeamer.manager.workflow.ActionCall;
import com.intland.codebeamer.manager.workflow.ActionParam;
import com.intland.codebeamer.manager.workflow.WorkflowAction;
import com.intland.codebeamer.manager.workflow.ActionParam.Type;
import com.intland.codebeamer.manager.workflow.WorkflowPhase;
import com.intland.codebeamer.persistence.dto.ArtifactDto;
import com.intland.codebeamer.persistence.dto.TrackerDto;
import com.intland.codebeamer.persistence.dto.UserDto;

@Component("baselineCreator")
@WorkflowAction(value="baselineCreator", iconUrl="/images/Snapshot.png", helpUrl="https://codebeamer.com/cb/wiki/816624")
public class BaselineCreator {
@Autowired
private ArtifactController artifactController;

@ActionCall(WorkflowPhase.After)
public ArtifactDto createBaseline(HttpServletRequest request, UserDto user, TrackerDto tracker,
@ActionParam(value="baselineScope", options={"project", "tracker"}, required=true) String scope,
@ActionParam(value="baselineName", required=true, width=60) String name,
@ActionParam(value="baselineDescription", type=Type.wikitext, width=60, height=2) String description
) throws Exception {
ArtifactDto baseline = ...

artifactController.createArtifact(request, user, tracker.getProject(), baseline, null);

return baseline;
}
}
我们建议，自定义操作的包 应为 com.intland.codebeamer 的子包，例如：

com.intland.codebeamer.<mycompany>.actions
您可以使用任何包名称，但在使用 com.intland.codebeamer 的子包时，组件 扫描可在启动 Codebeamer 期间自动检测并部署您的新操作：


package com.intland.codebeamer.example.actions;

import org.springframework.stereotype.Component;

@Component("baselineCreator")
public class BaselineCreator {
...
}
组件 ID/名称 (如有) 应与 @WorkflowAction ID/名称相同 (请参阅下文)。
如果您的自定义工作流操作不是 com.intland.codebeamer 的子包中的组件，则必须在以下位置为自定义工作流操作提供额外的 <bean> 配置：

~/CB-../tomcat/webapps/cb/WEB-INF/classes/my-ApplicationContext.xml
提供工作流操作的类必须注释为 @WorkflowAction。


import com.intland.codebeamer.manager.workflow.WorkflowAction;

@WorkflowAction(value="baselineCreator", iconUrl="/images/Snapshot.png", helpUrl="https://codebeamer.com/cb/wiki/816624")
public class BaselineCreator {
...
}
没有要实现的专用接口，也没有要扩展的基类。
@WorkflowAction 注释 具有以下属性：
• value 工作流操作的 ID/名称。在操作的生命周期内不能更改此 value，否则，配置的操作调用将不再起作用!
• iconUrl 此工作流操作的图标/图像的相对路径 (可选)。图标/图像必须位于 ~/CB-../tomcat/webapps/cb (的子文件夹) 中。
• helpUrl 此工作流操作的联机帮助 (wiki) 页面的 URL (可选)。可以是绝对 URL，也可以是相对 URL。
如果操作实现需要访问其他 Codebeamer API，则操作类应仅声明相应的 @Autowired 变量：


import org.springframework.beans.factory.annotation.Autowired;
import com.intland.codebeamer.controller.ArtifactController;

public class BaselineCreator {
@Autowired
private ArtifactController artifactController;

...
}
注释为 @WorkflowAction 的每个类必须 (至少) 具有一个使用 @ActionCall 注释的方法：


import com.intland.codebeamer.manager.workflow.ActionCall;
import com.intland.codebeamer.manager.workflow.WorkflowAction;
import com.intland.codebeamer.manager.workflow.WorkflowPhase;

@WorkflowAction(value="baselineCreator", iconUrl="/images/Snapshot.png", helpUrl="https://codebeamer.com/cb/wiki/816624")
public class BaselineCreator {
...

@ActionCall(WorkflowPhase.After)
public ArtifactDto createBaseline(...) {
...
}
}
操作方法可以具有任何名称和返回类型，并且应为公开。
@ActionCall 注释 仅包含一个参数，用于定义事件处理的 phase，其中方法应称为：
• Before 在对主题项实际执行触发事件之前调用此方法。在事件处理的此阶段，此方法可以对主题项进行修改，也可以通过抛出 VetoException 拒绝执行事件。
• After 在对主题项成功执行触发事件之后调用此方法。在事件处理的此阶段，不允许/不再保留对主题项进行的修改，但该方法仍可以通过抛出异常来中止事件处理。
注释为 @ActionCall 的方法必须是
必须将方法所需的上下文特定信息声明为参数。以下上下文信息可供使用：
• BaseEvent<ArtifactDto,TrackerItemDto,ActionData>，用于接收触发事件，其中：
◦ getUser() 是启动事件/操作的用户。
◦ getRequest() 是触发事件/操作的请求 (对于上报等自动触发的事件，可以为 null)。
◦ getSource() 是操作源/上下文，例如：
▪ WorkflowTransitionDto
▪ TrackerItemEscalationRuleDto
▪ TrackerViewDto
◦ getSecondarySource() 是跟踪器项，即触发事件的主题。
◦ getData() 是有关操作源/上下文/环境的其他信息。
• UserDto，用于接收执行操作的用户 (这不必与请求发起者相同)。
• HttpServletRequest，用于接收触发事件/操作的请求。对于上报等自动触发的事件，可以为 null。
• ActionData，用于接收有关操作源/上下文/环境的其他信息。
• ArtifactDto，用于接收操作源/上下文，例如
◦ WorkflowTransitionDto
◦ TrackerItemEscalationRuleDto
◦ TrackerViewDto
• ProjectDto，用于接收事件/操作的上下文项目。
• TrackerDto，用于接收事件/操作的上下文跟踪器。
• WorkflowActionDto，用于接收要执行的当前操作 (包括参数) (只读)。
• TrackerItemDto，用于接收要处理的当前跟踪器项。
也可以声明具有特定源/上下文类型的参数，例如 WorkflowTransitionDto。如果实际源/上下文不是此类型的对象，则此类参数的值将为 null。操作特定参数必须注释为 @ActionParam，并且可具有以下受支持的类型：
• 对于 (Wiki)Text、Country、Language 和 Color 参数：String
• 对于整数：int 或 Integer
• 对于浮点数：double 或 Double
• 对于持续时间 (毫秒)：long 或 Long
• 对于日期/时间：Date
• 对于 true 或 false：boolean 或 Boolean
• 对于用户：UserDto
• 对于用户组：ArtifactDto
• 对于角色：RoleDto
• 对于项目成员：NamedDto
◦ 对于用户：UserDto
◦ 对于角色：RoleDto
◦ 对于用户组：ArtifactDto
◦ 对于成员字段：TrackerLayoutLabelDto
• 对于项目：ProjectDto
• 对于跟踪器：TrackerDto
• 对于跟踪器字段：TrackerLayoutLabelDto
• 对于选择选项：TrackerChoiceOptionDto
• 对于跟踪器项：TrackerItemDto
• 对于关联：AssociationDto
具有简单类型 (int、double、long 和 boolean) 的参数为隐式必需参数。对于其他参数，值可以为 null，除非将其显式声明为 required=true。如果参数可以有多个值，则必须按如下方式声明其相应类型：
• Collection、
• List 或
• Set
@ActionParam 注释 支持以下属性：
• value 是参数名称 (必需)。在操作的生命周期中不能更改此 value，否则，配置的操作调用的实际参数值不再赋值给此参数!
• type 是参数类型。参数类型通常为 implicit 类型，但需要为模糊类型显式指定，例如，String 可以是 Text，也可以是 Country、Language、Color，甚至是 Choice。
◦ implicit
◦ text
◦ wikitext
◦ integer
◦ decimal
◦ bool
◦ date
◦ duration
◦ country
◦ language
◦ choice
◦ user
◦ group
◦ role
◦ member
◦ project
◦ tracker
◦ field
◦ item
◦ reference
◦ association
• required，用于指定参数值是必需值 (true) 还是可选值 (false)。默认值为 required=false。
• options，是 choice 参数的可用选择选项名称。例如：


@ActionParam(value="baselineScope", options={"project", "tracker"}, required=true) String scope
• project，是 project 参数的可选限定符。例如：


@ActionParam(value="projects", project=@Project({"Team", "Department"}), required=true) Collection<ProjectDto> projects
用于将允许的参数值限制为类别为 "Team" 或 "Department" 的项目。
• tracker，是 tracker 参数的可选限定符。例如：


@ActionParam(value="tracker", tracker=@Tracker({"Bug", "Task"}), required=true) TrackerDto tracker
用于将允许的参数值限制为跟踪器，其中：
◦ value，跟踪器具有 (其中一种) 指定类型 (TrackerTypeDto 名称)。
◦ referring
▪ true：可能的值为跟踪器 (具有指定类型)，通过引用字段 (具有指定的 refType) 引用当前跟踪器。
▪ false：可能的值为当前项目中的跟踪器 (具有指定类型)。这是默认设置。
◦ refType，采用字符串或字符串数组形式的引用字段名称。默认值为任何引用字段。
• field，是 field 参数的可选限定符。例如：


@ActionParam(value="signer", field=@Field({Type.text, Type.user})) TrackerLayoutLabelDto signerField,
@ActionParam(value="signature", field=@Field(Type.text), required=true) TrackerLayoutLabelDto signatureField
用于将允许的参数值限制为这些跟踪器字段，其中：
◦ value，字段具有 (其中一个) 指定值 type
◦ refType，字段是引用具有指定类型 (之一) 的实体的 type=reference 字段，
◦ multiple，是否仅允许具有多个值的字段 (true)。默认值为 false。
注释为 @ActionCall 的方法可抛出任何类型的异常。两种类型的异常具有特殊含义：
• com.intland.codebeamer.event.util.VetoException 可以抛出以故意放弃事件处理 (最好在 WorkflowPhase.Before 中)。例如，如果签名/密码验证失败，验证用户签名 (密码) 将抛出 VetoException。
• com.intland.codebeamer.manager.workflow.ActionWarning 可以抛出以发出操作异常/失败信号，应仅记录该信号，但不应放弃事件处理。ActionWarning 的日志记录级别可以是
◦ WARNING (默认) 或
◦ ERROR
在执行 @ActionCall 期间发生的所有异常 (ActionWarning 除外) 都会中止对触发事件的处理 (在 WorkflowPhase.Before 中) 或回滚对触发事件的处理 (在 WorkflowPhase.After 中)。
操作配置本地化
工作流操作配置 GUI 将使用以下项显示操作和自定义操作参数：
• @WorkflowAction value(name)
• @ActionParam value(name)
通过自定义语言资源文件 (请参阅 Codebeamer 本地化指南)，可以为操作和参数名称提供语言特定文本。例如：~/CB-../tomcat/webapps/cb/WEB-INF/classes/my-ApplicationResources.properties

tracker.action.baselineCreator.label=Create a new baseline
tracker.action.baselineCreator.baselineScope.label=Scope
tracker.action.baselineCreator.baselineScope.tooltip=The scope of the new baseline
tracker.action.baselineCreator.baselineScope.tracker.label=Tracker
tracker.action.baselineCreator.baselineScope.tracker.tooltip=Create a new baseline on the current tracker
tracker.action.baselineCreator.baselineScope.project.label=Project
tracker.action.baselineCreator.baselineScope.project.tooltip=Create a new baseline on the whole project
tracker.action.baselineCreator.baselineName.label=Name
tracker.action.baselineCreator.baselineName.tooltip=The name of the new baseline
tracker.action.baselineCreator.baselineDescription.label=Description
tracker.action.baselineCreator.baselineDescription.tooltip=The description of the new baseline
中的英语文本
例如：~/CB-../tomcat/webapps/cb/WEB-INF/classes/my-ApplicationResources_de.properties 中的德语文本

tracker.action.baselineCreator.label=Den aktuellen Versionsstand sichern
tracker.action.baselineCreator.baselineScope.label=Umfang
tracker.action.baselineCreator.baselineScope.tooltip=Der Umfang des neuen Versionsstands
tracker.action.baselineCreator.baselineScope.tracker.label=Tracker
tracker.action.baselineCreator.baselineScope.tracker.tooltip=Sichere den Versionsstand des aktuellen Trackers
tracker.action.baselineCreator.baselineScope.project.label=Projekt
tracker.action.baselineCreator.baselineScope.project.tooltip=Sichere den Versionstands des kompletten Projekts
tracker.action.baselineCreator.baselineName.label=Name
tracker.action.baselineCreator.baselineName.tooltip=Der Name des neuen Versionstands
tracker.action.baselineCreator.baselineDescription.label=Beschreibung
tracker.action.baselineCreator.baselineDescription.tooltip=Die Beschreibung des neuen Versionstands
工作流操作的标签和工具提示的资源名称如下：
• tracker.action.<name>.label
• tracker.action.<name>.tooltip
工作流操作参数的标签和工具提示的资源名称如下：
• tracker.action.<name>.<param>.label
• tracker.action.<name>.<param>.tooltip
工作流操作选择参数 option 标签和工具提示的资源名称如下：
• tracker.action.<name>.<param>.<option>.label
• tracker.action.<name>.<param>.<option>.tooltip
其中，<name> 为 @WorkflowAction value(name)，<param> 为 @ActionParam value(name)，<option> 为选择参数 option。
上下文特定操作
如果自定义工作流操作仅适用于特定上下文，例如仅适用于特定类型的跟踪器/项，则实施类应声明使用 @ActionPredicate 注释的附加谓词/方法：


import com.intland.codebeamer.manager.workflow.ActionPredicate;
import com.intland.codebeamer.persistence.dto.TrackerTypeDto;

@WorkflowAction(value="scmChangeFileZipper", iconUrl="/images/cvs_view.gif")
public class ScmChangeFileZipper {

@ActionPredicate
public boolean isApplicable(TrackerTypeDto type) {
return TrackerTypeDto.isTrackerType(type);
}

...
}
使用 @ActionPredicate 注释的方法必须是
• 公共的
• 如果操作适用，则返回布尔值 true，否则返回 false。
方法必须声明所有必需上下文信息的参数，才能做出决策。以下上下文信息可供使用：
• ProjectDto 是用于配置工作流操作的项目
• TrackerDto 是用于配置工作流操作的跟踪器
• TrackerTypeDto 是用于配置工作流操作的跟踪器的类型
• TrackerTypeDto.Kind 是用于配置工作流操作的跟踪器的种类
◦ 工作项的跟踪器
◦ 配置项的类别
◦ 源代码提交/推送存储库
部署工作流操作
要部署自定义工作流操作，必须编译 Java 代码，并将生成的 *.class 文件上传到 ~/CB-.../tomcat/webapps/cb/WEB-INF/classes/... 下的相应子目录，其中子目录等同于操作的包名称。如果您具有多个自定义操作 (以及自定义 Wiki 插件等)，则可以选择将所有自定义类 (连同自定义语言资源文件) 打包成一个 Java 存档 (*.jar) 并放入 ~/CB-.../tomcat/webapps/cb/WEB-INF/lib 中。对于不在 com.intland.codebeamer 下或未注释为 @Component 的操作，还必须在以下位置额外提供 <bean> 配置：

~/CB-../tomcat/webapps/cb/WEB-INF/classes/my-ApplicationContext.xml
最后，必须重新启动 Codebeamer 才能加载新部署的操作。
这对您有帮助吗?