* 适用插件：工作流插件 * 优先封装：（暂无 commons 封装） * 原生兜底：IWorkflowPlugin、AgentExecution、WorkflowServiceHelper * 相关 lint 规则：（暂无） *
* 使用场景： * 1. filterParticipant 过滤审批参与人（排除创建人、取上游源单创建人）； * 2. notify 审批节点回调（审批意见反写、拒绝通知第三方、写流程变量）； * 3. afterSuspendProcess 流程挂起通知单据创建人； * 4. calcUserIds 动态计算审批参与人； * 5. hasTrueCondition 条件分支判断； * 6. notifyByWithdraw 流程撤回补偿处理； * 7. WorkflowServiceHelper 辅助能力速查（inProcess / getAllApprovalRecord）。 */ public class SampleWorkflowPlugin implements IWorkflowPlugin { private static final Log log = LogFactory.getLog(SampleWorkflowPlugin.class); // =================================================================== // 一、filterParticipant —— 过滤/替换审批参与人 // =================================================================== /** * 场景 1：排除单据创建人，避免自己审批自己。 *
* AgentExecution 上下文要点：
* - getBusinessKey() → 单据主键（字符串）
* - getEntityNumber() → 单据实体编码
*/
@Override
public List
* 工作流传参 [nodeName] → 指定反写字段标识。
* AgentExecution 上下文要点：
* - getCurrentTaskResult(WFTaskResultEnum.auditMessage) → 审批意见（JSON，含多语言）
* - getCurrentTaskResult(WFTaskResultEnum.auditName) → 审批动作名称（同意/驳回）
* - getCurrentTask().getAssigneeId() → 实际审批人 ID
* - getCurrentWFPluginParams() → 工作流节点上配置的自定义参数
*/
@Override
public void notify(AgentExecution execution) {
// 获取审批意见
Object approvalObj = execution.getCurrentTaskResult(WFTaskResultEnum.auditMessage);
if (approvalObj == null) {
return;
}
// 从工作流节点参数中获取需要反写的字段标识
String nodeName = execution.getCurrentWFPluginParams().get("nodeName").toString();
String entityName = execution.getEntityNumber();
String businessKey = execution.getBusinessKey();
DynamicObject bill = BusinessDataServiceHelper.loadSingle(businessKey, entityName);
// 审批人信息
List
* 通过 WorkflowServiceHelper.getAllApprovalRecord() 获取完整审批记录，
* 取最后一条记录组的拒绝原因，推送给外部系统。
*/
private void notifyRejectToThirdParty(AgentExecution execution) {
String entityNumber = execution.getEntityNumber();
String businessKey = execution.getBusinessKey();
if (businessKey == null) {
return;
}
// 获取审批拒绝原因（从完整审批记录中提取）
StringBuilder rejectReason = getLastApprovalMessage(businessKey);
log.info("审批拒绝，单据={}, 原因={}", businessKey, rejectReason);
}
/**
* 从审批记录中获取最后一个节点的审批意见。
*
* WorkflowServiceHelper.getAllApprovalRecord(businessKey) → List<IApprovalRecordGroup>
* IApprovalRecordGroup.getChildren() → List<IApprovalRecordItem>
* IApprovalRecordItem：getActivityName() / getMessage() / getResult()
*/
private StringBuilder getLastApprovalMessage(String businessKey) {
StringBuilder message = new StringBuilder();
List
* SuspendInfo 上下文：
* - getBusinessKey() → 单据主键
* - getEntityNumber() → 单据实体编码
* - getErrMsg() → 挂起错误原因
*
* 通知渠道：MessageCenterServiceHelper.sendMessage() → 消息中心 + 云之家
*/
@Override
public void afterSuspendProcess(SuspendInfo suspendInfo) {
try {
String pk = suspendInfo.getBusinessKey();
String entityId = suspendInfo.getEntityNumber();
DynamicObject bill = BusinessDataServiceHelper.loadSingle(pk, entityId);
// 获取单据创建人
DynamicObject creator = bill.getDynamicObject("creator");
Long userId = DynamicObjectUtils.nullSafeGet(creator, "id");
if (EntityUtils.isEmptyPk(userId)) {
log.info("afterSuspendProcess: creator is empty, pk={}", pk);
return;
}
String billNo = bill.getString("billno");
// 构建消息
MessageInfo messageInfo = new MessageInfo();
LocaleString title = new LocaleString();
title.setLocaleValue_zh_CN("流程异常挂起");
LocaleString content = new LocaleString();
content.setLocaleValue_zh_CN("您的单据编号为" + billNo + "的流程已挂起，请联系系统管理员。\n"
+ "挂起原因：" + suspendInfo.getErrMsg());
messageInfo.setMessageTitle(title);
messageInfo.setMessageContent(content);
messageInfo.setUserIds(Collections.singletonList(userId));
messageInfo.setType(MessageInfo.TYPE_WARNING);
// notifyType：mcenter=消息中心, yunzhijia=云之家, email=邮件
messageInfo.setNotifyType("mcenter,yunzhijia");
MessageCenterServiceHelper.batchSendMessages(Collections.singletonList(messageInfo));
} catch (Exception e) {
log.warn("流程挂起通知失败", e);
}
}
// ===================================================================
// 四、calcUserIds —— 动态计算审批参与人
// ===================================================================
/**
* 根据单据字段/流程变量动态返回审批人列表。
*
* 典型场景：根据单据金额、部门等信息动态决定审批人。
*/
@Override
public List
* 返回 true → 流程走当前分支；false → 跳过。
*/
@Override
public boolean hasTrueCondition(AgentExecution execution) {
Object amount = execution.getVariable("amount");
return amount instanceof Number && ((Number) amount).doubleValue() > 100000D;
}
// ===================================================================
// 六、notifyByWithdraw —— 流程撤回补偿
// ===================================================================
/**
* 流程撤回时的补偿处理。
*
* 注意：notify 和 notifyByWithdraw 应成对设计，保证状态可恢复。
*/
@Override
public void notifyByWithdraw(AgentExecution execution) {
execution.setVariable("lastNodeName", "withdraw");
// TODO 恢复单据状态或清理之前 notify 写入的数据
}
// ===================================================================
// 七、formatFlowRecord —— 审批记录格式化
// ===================================================================
/**
* 定制审批记录的显示文本。
*
* IApprovalRecordItem：getActivityName() / getMessage() / getResult() / setMessage(...)
*/
@Override
public IApprovalRecordItem formatFlowRecord(IApprovalRecordItem item) {
// 示例：在审批记录中追加自定义说明
// item.setMessage(item.getMessage() + " [已同步]");
return item;
}
// ===================================================================
// 八、WorkflowServiceHelper 辅助能力速查
// ===================================================================
/**
* WorkflowServiceHelper 常用静态方法速查。
*
* 这些方法不属于 IWorkflowPlugin 接口事件，但在操作插件、表单插件中经常配合使用。
*/
private void workflowServiceHelperCheatSheet() {
String billId = "123456";
// 1. 判断单据是否在审批流程中（常用于下推前校验）
boolean inProcess = WorkflowServiceHelper.inProcess(billId);
// 2. 获取完整审批记录（常用于拒绝通知、审批意见展示）
List