ARTICLE DETAIL

资讯详情

深耕网站建设、视觉设计与SEO优化的一线实战洞察。

泛微E9 workflowService接口调用三要素与实战指南

泛微E9 workflowService接口调用三要素与实战指南 简介本资源是一套面向Java开发者与泛微E9流程定制实施人员的实战型流程开发Demo聚焦workflowService RESTful接口的全流程实践解决企业级流程增删改查、跨系统集成与自动化触发等核心需求。压缩包共41个文件含11个Java源码与12个编译后class文件覆盖流程创建、查询、启动、回退等关键逻辑8个依赖jar包如fastjson、httpclient、fel-all等5个XML配置文件含流程定义与Spring Boot集成配置以及RSA密钥、README说明和IDEA项目配置文件整体24.75MB结构完整、开箱即用。已有1955人学习下载可直接导入IDE运行调试快速掌握E9流程引擎对外API调用规范、RESTful风格设计实践及与业务系统如CRM的对接方式特别适合需落地审批流、采购流等真实场景的二次开发工程师。1. 泛微 E9 workflowService 接口不是“调用即生效”的黑盒而是需明确流程定义、实例绑定与权限上下文的三段式开发链路很多刚接触泛微 E9 流程开发的同学看到workflowService这个名字第一反应是“调个接口就能启动流程”结果在测试环境反复 POST 却始终返回null或403甚至查日志只看到No permission to access workflow。真相是E9 的workflowService并非独立服务它严格依赖三个前置锚点——已发布的流程模板含唯一 workflowId、合法且具备操作权限的登录态Session/Token、符合该模板字段约束的业务数据载体如 formId fieldMap。缺一不可。本 demo 不做“封装一层就万事大吉”的假抽象而是还原真实开发闭环从后台配置流程模板开始到 Java 后端调用workflowService.addNewProcess()创建实例再到通过getProcessInfo()查看状态、deleteProcess()清理测试数据、updateProcessField()动态修改字段——每一步都对应 E9 管理后台可验证的操作痕迹。适合已有 E9 系统管理权限、需对接 OA 流程引擎的 Java 开发者或正在做泛微二次开发交付的技术负责人。2. 在 E9 后台完成流程模板发布与权限配置是 workflowService 调用成功的前提条件泛微 E9 的流程引擎不接受“裸调用”。所有workflowService方法的执行都以workflowId为索引而这个 ID 只能来自后台已正式发布的流程模板。未发布、仅保存、或处于草稿/停用状态的流程其 ID 对workflowService完全不可见。这与部分轻量级工作流框架如 Flowable 的 REST API 直接部署 BPMN有本质区别。2.1 获取 workflowId 的唯一可靠路径从流程模板管理页导出 XML 并解析登录 E9 管理后台 → 【流程管理】→【流程模板管理】→ 找到目标流程例如“合同审批流程”→ 点击【导出】按钮。导出文件为.xml格式打开后搜索workflow idxxx标签。此处的xxx即为workflowService所需的workflowId。注意该 ID 是 UUID 格式如a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8而非流程名称或编号。网络热词中“泛微获取流程id”常被误导向数据库表workflow_base查询但 E9 8.0 版本起workflowId已与数据库主键解耦直接查表可能返回无效值。提示若导出 XML 中无workflow id...说明该流程尚未完成“发布”操作。必须点击流程右侧【发布】按钮选择“立即发布”并确认否则后续所有接口调用均会因workflow not found失败。2.2 配置“无监控权限也能点开”的关键流程模板级操作权限继承热词中高频出现的“怎么配置没有监控权限也能点开”本质是解决普通用户调用workflowService.getProcessInfo()查看自己发起的流程时因缺少“流程监控”角色权限而被拦截的问题。E9 的权限模型采用“模板级授权”而非“接口级授权”。解决方案是进入该流程模板的【权限设置】页 → 【操作权限】标签页 → 勾选【允许发起人查看流程】和【允许发起人操作流程】→ 保存。此时即使用户未分配“流程监控”全局角色只要他是该流程实例的发起人starterId即可成功调用getProcessInfo()和updateProcessField()。此配置直接影响workflowService的getProcessInfo()返回结果是否包含processStatus、currentNodeName等关键字段。2.3 验证流程模板可用性的最小化检查清单执行以下三步确保workflowId可被workflowService正确识别状态检查后台流程模板列表中“状态”列必须显示为“已发布”非“草稿”“停用”“待发布”版本检查同一模板名可能有多个版本workflowService默认使用最新发布版本。确认导出 XML 中version标签值与后台显示一致字段映射检查若流程含自定义表单formId需在【表单设计】中确认所有必填字段requiredtrue已在addNewProcess()的fieldMap参数中提供值否则addNewProcess()会直接抛出FieldValidationException。3. 使用 Java SDK 调用 workflowService 实现流程实例的增删改查参数与异常需逐层对齐泛微 E9 提供weaver.common.webservice.WorkflowService接口类其方法签名与底层 SOAP 协议强绑定。直接使用HttpURLConnection构造 SOAP 请求极易出错官方推荐方式是通过 E9 自带的weaver.jar位于WEB-INF/lib/加载客户端。以下代码基于 E9 9.0 环境所有参数均经生产环境验证。3.1 初始化 workflowService 客户端必须携带有效 SessionId// 1. 获取登录态以账号密码方式为例实际项目应使用统一认证Token String loginUrl http://your-e9-domain/weaver/weaver.servlet.LoginServlet; MapString, String loginParams new HashMap(); loginParams.put(username, admin); loginParams.put(password, encryptedPassword); // 注意密码需按E9规则MD5加密 String loginResponse sendPost(loginUrl, loginParams); String sessionId extractSessionId(loginResponse); // 从响应Cookie或JSON中提取JSESSIONID // 2. 构建WorkflowService客户端关键URL末尾必须带?wsdl String wsdlUrl http://your-e9-domain/weaver/weaver.webservice.WorkflowService?wsdl; WorkflowService service new WorkflowService(new URL(wsdlUrl)); WorkflowServiceSoap port service.getWorkflowServiceSoap(); // 3. 设置HTTP Header传递SessionIdE9 9.0 强制要求 BindingProvider bp (BindingProvider) port; MapString, Object requestContext bp.getRequestContext(); requestContext.put(BindingProvider.SESSIONID_PROPERTY, sessionId);注意BindingProvider.SESSIONID_PROPERTY是 E9 特定常量值为javax.xml.ws.session.id。若使用 Spring-WS 或 Apache CXF需手动注入 Cookie 头Cookie: JSESSIONIDxxx否则addNewProcess()必报Authentication failed。3.2 创建新流程实例addNewProcess() 的 5 个必需参数详解int workflowId 123456789; // 从XML解析出的整数型ID非UUID字符串 int userId 1001; // 发起人userId必须是E9系统内真实存在的用户ID int nodeId 0; // 起始节点ID0表示流程第一个节点若流程有多个入口需指定具体nodeId String remark Demo发起; // 流程备注非空字符串 MapString, Object fieldMap new HashMap(); fieldMap.put(field001, 合同编号-HT2024001); // 表单字段编码必须与模板定义完全一致 fieldMap.put(field002, 100000.00); // 金额字段注意类型匹配String转BigDecimal fieldMap.put(field003, 张三,李四); // 多人审批人字段用英文逗号分隔 // 调用创建 int requestId port.addNewProcess(workflowId, userId, nodeId, remark, fieldMap); System.out.println(新流程ID requestId); // 返回值为processId整数非workflowId参数名类型是否必需说明workflowIdint✅模板ID必须为后台导出XML中workflow id...的数值部分如a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8→123456789userIdint✅发起人用户ID非用户名。可通过HrmResourceService.getUserByLoginName()查询nodeIdint✅起始节点ID0代表默认首节点若流程启用“多入口”需在模板中查节点属性remarkString✅流程标题/摘要长度限制50字符为空则报错fieldMapMapString,Object⚠️键为表单字段编码非中文名值类型需与模板定义匹配文本→String数字→Double日期→Stringyyyy-MM-dd3.3 查询、更新、删除流程实例参数组合与状态边界// 查询流程详情需发起人权限或监控权限 ProcessInfo processInfo port.getProcessInfo(requestId, userId); System.out.println(当前状态 processInfo.getProcessStatus()); // 1运行中, 2已完成, 3已终止 System.out.println(当前节点 processInfo.getCurrentNodeName()); // 更新流程字段仅限发起人或当前审批人 MapString, Object updateFields new HashMap(); updateFields.put(field004, 已加急处理); // 修改备注字段 boolean updateSuccess port.updateProcessField(requestId, userId, updateFields); System.out.println(更新结果 updateSuccess); // 删除流程实例仅限发起人且流程状态为运行中 boolean deleteSuccess port.deleteProcess(requestId, userId); System.out.println(删除结果 deleteSuccess);提示deleteProcess()有严格状态校验。若流程已归档processStatus2或被驳回processStatus3调用将返回false且无异常。需先调用getProcessInfo()确认processStatus1再执行删除。4. 解决 workflowService 常见报错从 SOAP Fault 到业务逻辑阻塞的定位路径当workflowService调用失败时E9 返回的 SOAP Fault 信息高度结构化但错误码含义需结合上下文解读。以下是生产环境高频问题的定位树。4.1SOAPFaultException: errorCode1001, errorMsgNo permission to access workflow此错误不表示用户无登录权限而是指workflowId对应的流程模板未发布或当前用户对该模板无“操作权限”。验证步骤登录后台用该workflowId搜索流程模板确认状态为“已发布”进入模板【权限设置】→【操作权限】确认勾选了【允许发起人操作流程】检查addNewProcess()中的userId是否与登录态一致常见错误用 admin 登录却传入普通用户ID。4.2FieldValidationException: field field001 is required but null字段校验失败。E9 对必填字段requiredtrue执行严格空值检查。解决方案查看流程模板的表单设计找到field001对应的字段属性确认fieldMap中put(field001, ...)的值不为null且类型正确如日期字段必须为2024-01-01字符串不能传new Date()若字段为下拉框select值必须是选项编码code而非显示文本name。4.3SOAPFaultException: errorCode2003, errorMsgInvalid node idnodeId参数错误。E9 流程节点 ID 并非连续整数而是模板定义时生成的唯一标识。获取正确nodeId的方法进入流程模板【流程图设计】页右键点击目标起始节点 → 【属性】→ 查看nodeid属性值如10001若流程启用“动态路由”需调用getStartNodeList()先获取可用节点列表再选其一。4.4NullPointerException在getProcessInfo()返回值中processInfo对象本身不为null但processInfo.getCurrentNodeName()返回null。原因通常是流程刚创建尚未触发第一个审批动作currentNodeName在首节点审批提交后才赋值流程被管理员强制终止状态变为3currentNodeName清空用户无权限查看该流程即使getProcessInfo()调用成功部分字段仍为null。验证方式打印processInfo.getProcessStatus()若为1且getCurrentNodeName()null说明流程卡在首节点未提交。5. 实战技巧用 curl 快速验证 workflowService 接口连通性绕过 Java SDK 依赖当 Java 环境无法调试或需快速验证服务端连通性时直接使用curl发送 SOAP 请求是最高效手段。以下命令基于 E9 9.0 的 WSDL 结构已去除所有敏感信息可直接替换域名和参数复用。5.1 构造 addNewProcess() 的最小化 curl 请求curl -X POST http://your-e9-domain/weaver/weaver.webservice.WorkflowService \ -H Content-Type: text/xml; charsetutf-8 \ -H Cookie: JSESSIONIDABC123XYZ \ -d ?xml version1.0 encodingUTF-8? soapenv:Envelope xmlns:soapenvhttp://schemas.xmlsoap.org/soap/envelope/ xmlns:webhttp://weaver.com/ soapenv:Header/ soapenv:Body web:addNewProcess web:workflowId123456789/web:workflowId web:userId1001/web:userId web:nodeId0/web:nodeId web:remarkDemo发起/web:remark web:fieldMap web:item web:keyfield001/web:key web:valueHT2024001/web:value /web:item /web:fieldMap /web:addNewProcess /soapenv:Body /soapenv:Envelope | xmllint --format -注意xmllint用于格式化输出便于查看响应。若未安装可去掉| xmllint --format -。关键点Cookie头必须携带有效的JSESSIONIDfieldMap中每个字段需包裹在web:item内web:key和web:value标签名不可简写。5.2 解析 SOAP 响应中的 processId成功响应的 XML 中addNewProcessResponse标签下addNewProcessResult的文本内容即为processIdsoap:Envelope xmlns:soaphttp://schemas.xmlsoap.org/soap/envelope/ soap:Body addNewProcessResponse xmlnshttp://weaver.com/ addNewProcessResult987654321/addNewProcessResult /addNewProcessResponse /soap:Body /soap:Envelope提取命令Linux/macOScurl -s ... | xmllint --xpath //addNewProcessResult/text() - # 输出9876543215.3 用 getProcessInfo() 验证流程状态的三步法确认 processId 存在curl -s ... | grep processId987654321/processId检查 processStatuscurl -s ... | xmllint --xpath //processStatus/text() -返回1表示运行中验证字段值curl -s ... | xmllint --xpath //fieldValue[../fieldNamefield001]/text() -返回HT2024001表示字段写入成功。此方法无需编译 Java 代码5 分钟内即可定位是网络问题、权限问题还是参数问题是泛微 E9 流程开发调试的黄金组合技。本文还有配套的精品资源点击获取
返回列表