泛微OA e-cology 8 webservice接口集成实战：认证、调用与避坑

简介面向泛微OA e-cology 8的二次开发与运维人员这份文档是调用其最新文档WebService接口的官方参考资料重点解决文档创建、删除、更新、查看等接口的部署配置与方法参数问题。资源为docx格式压缩包共1个文件、大小约330KB内容围绕文档服务展开包含接口总体说明、部署配置、方法概览与对象字段说明结构紧凑适合开发时快速查阅。已有6785人学习下载能显著减少OA集成开发中的接口调试成本。文档完整列出了login、createDoc、updateDoc、deleteDoc、getDoc、getDocCount、getList共7个核心方法login方法支持数据库验证、动态密码验证和LDAP验证三种方式DocInfo对象覆盖文档ID、类型、标题、编号、版本、状态、主目录、分目录、子目录、部门、语言、关键字、创建人、修改人、批准人、归档人、作废人等字段并提供services.xml中服务名称、命名空间、服务类、实现类的注册示例。读者可据此直接对接OA文档模块快速完成接口联调减少摸索成本。1. 泛微OA e-cology 8 的webservice接口为什么系统集成总在认证这一步卡壳做泛微OA与外部系统对接时几乎躲不开webservice。我经手的项目里无论是把ERP的审批数据推到OA走流程还是把OA审批结果回传给财务系统最终都会落到同一个问题上e-cology 8的webservice接口文档里的示例代码能不能直接跑通答案通常是不能。最常见的情况是文档里给的Java示例是泛微代码生成器生成的旧版客户端而现场的webservice版本、密码加密策略、sessionid有效期都不一样导致认证环节就翻车。这篇文章会把泛微e-cology 8的webservice从服务地址、认证头、Java调用到踩坑排查完整讲清楚适合正在做OA二次开发或系统集成的Java工程师也适合需要评估接口可行性的实施顾问。2. 拆e-cology 8的webservice接口体系服务地址、认证头与WSDL定位2.1 服务地址怎么定位从安装目录到WSDL的一分钟路径第一次拿到泛微环境不要急着翻接口文档。我一般先在服务器上做两步确认第一步找到ecology安装目录第二步打开部署的服务列表页。e-cology 8部署在Resin环境的话oa代码通常在安装根目录\webapps\ecology\WEB-INF\lib\下能看到ecology_SDK.jar以及一堆依赖的jar包。这个SDK jar里封装了大部分webservice相关的类但它不是让你直接拿来引用的很多类跟服务器内部实现绑定。真正要用的是每个服务对应的WSDL地址。浏览器访问http://OA服务器IP:端口/services/如果部署正常页面上会列出当前环境可用的webservice服务名。以工作流服务为例它的WSDL地址通常是http://OA服务器IP:端口/services/workflowService?wsdl这个WSDL地址不只是代码生成的依据也是判断服务是否正常启动的探针。我见过一个项目内部调用IP加8080完全正常外部系统访问却因为防火墙策略把8080端口封了对方第一反应以为是服务没起。先把端口和访问路径确认好能省掉一半排查时间。拿到WSDL之后第一件事就是另存为一份本地文件并标记好日期和版本号。这一步看着简单但价值很大后续所有代码生成、接口联调、版本升级对比都以这份WSDL为准。泛微OA打了补丁或升级小版本之后同一个服务接口的入参结构完全可能变化有这份基线才能快速查差异。2.2 认证头怎么构造userid、password、sessionid三者关系泛微的webservice认证信息放在SOAP Header里不是放在URL参数或者普通HTTP Header里。这一点很多第一次接触泛微接口的开发者会忽略直接在Query String里拼账号密码结果一直拿不到数据。标准的认证头结构如下soapenv:Header auth xmlnshttp://www.weaver.com.cn/webservice/ userid1/userid passworde10adc3949ba59abbe56e057f20f883e/password sessionid/sessionid usertype0/usertype loginnamesysadmin/loginname /auth /soapenv:Header各节点含义userid对应HrmResource表里的用户ID也就是数字主键不是登录名。loginname才是登录名可以作为辅助信息一起传。password在多数e-cology 8版本里是MD5加密后的值上面的示例是123456的MD5只适合本地联调生产环境务必换掉。如果后台开启了RSA密钥传递需要先调RSA服务对密码做加密再塞进这个字段不能直接放明文。调用接口时通常有两种认证模式一种是userid加password直连每次请求都带另一种是先登录拿sessionid之后请求只带sessionid。我的经验是直连方式更省心sessionid方式响应更快但一定要处理过期问题。如果你不确定当前版本支持哪种就把两种都传——服务端会优先校验sessionidsessionid无效时再回退到账号密码认证这样能减少一半的报错。2.3 常用服务清单哪个接口解决哪个场景e-cology 8的webservice服务会按业务模块拆分虽然不同补丁版本的服务名略有差异但以下几个是实际项目里高频出现的服务名常见用途典型集成场景workflowService发起流程、获取待办、获取流程状态、提交/退回ERP推送单据到OA审批读取审批结果integrationService封装常用表单数据读写面向外部系统MES系统获取OA里的检验单数据rbacService用户、部门、岗位等组织数据查询从HR系统同步人员到OAattachmentService附件的上传、下载和删除把ERP生成的PDF挂到OA流程附件里建模引擎相关服务读写建模实体的表单数据主数据同步、临时业务数据归档注意建模引擎相关的服务名在不同版本里经常变我见过builderService也见过modelService。如果现场启用了泛微的建模引擎最可靠的方式是到服务列表页去看而不是凭记忆去猜服务名。接口文档只能是索引真正的地图在你自己的OA环境里。提示把当前环境的WSDL列表页截图存档升级前和升级后各一份排查问题时能少吵很多架。3. Java调用泛微webservice的完整过程从wsimport生成代码到创建一条流程3.1 用wsimport生成客户端代码命令与产物清单在本地写好一个Java工程先把目标WSDL保存到项目目录下然后执行JDK自带的wsimport工具生成客户端代码wsimport -d ./src -keep -p com.company.weaver \ -extension http://192.168.1.10:8080/services/workflowService?wsdl参数说明-d指定代码输出目录-keep保留生成的.java源文件-p自定义包名避免跟泛微SDK自带类重名-extension允许使用JAX-WS未标准化的扩展。泛微老版本的WSDL里带一些多态元素不加这个参数可能直接报解析错误。生成完成后常见的产物包括WorkflowService.java服务入口类用来创建端口WorkflowServiceSoap.java端口接口里面是所有可调用的方法一系列业务对象WorkflowRequestInfo、WorkflowMainTableInfo、WorkflowDetailTableInfo、WorkflowRequestLogInfo等内嵌或独立的schema定义文件如果你生成后找不到WorkflowRequestInfo多半是WSDL解析不完整。这时先确认WSDL地址能否直接访问再看JDK版本。JDK 8自带的wsimport对复杂schema支持有限换成Apache CXF的wsdl2java通常能解决问题。还有一个野路子经验把WSDL里的s:element refns:...改成s:element name... type...再跑一次生成但这种做法只适合临时应急改过后的代码要格外小心验证。3.2 用SOAPHandler注入认证头代码与实现细节生成的客户端默认不带认证头直接调用会返回认证错误。JAX-WS的标准做法是写一个Handler在请求发出去之前把SOAP Header补上。import javax.xml.namespace.QName; import javax.xml.soap.SOAPElement; import javax.xml.soap.SOAPException; import javax.xml.soap.SOAPFactory; import javax.xml.ws.handler.MessageContext; import javax.xml.ws.handler.soap.SOAPHandler; import javax.xml.ws.handler.soap.SOAPMessageContext; import java.util.Set; public class WeaverAuthHandler implements SOAPHandlerSOAPMessageContext { private final String userId; private final String passwordMd5; public WeaverAuthHandler(String userId, String passwordMd5) { this.userId userId; this.passwordMd5 passwordMd5; } Override public boolean handleMessage(SOAPMessageContext context) { Boolean outbound (Boolean) context.get(MessageContext.MESSAGE_OUTBOUND_PROPERTY); if (Boolean.TRUE.equals(outbound)) { try { SOAPFactory factory SOAPFactory.newInstance(); SOAPElement auth factory.createElement( new QName(http://www.weaver.com.cn/webservice/, auth, weaver)); SOAPElement useridEl factory.createElement( new QName(http://www.weaver.com.cn/webservice/, userid, weaver)); useridEl.addTextNode(userId); auth.addChildElement(useridEl); SOAPElement pwdEl factory.createElement( new QName(http://www.weaver.com.cn/webservice/, password, weaver)); pwdEl.addTextNode(passwordMd5); auth.addChildElement(pwdEl); if (context.getMessage().getSOAPPart().getEnvelope().getHeader() null) { context.getMessage().getSOAPPart().getEnvelope().addHeader(); } context.getMessage().getSOAPPart().getEnvelope().getHeader().addChildElement(auth); } catch (SOAPException e) { throw new RuntimeException(泛微认证头构造失败, e); } } return true; } }逻辑说明这段代码只处理出站请求响应方向直接放行。构造auth元素时使用SOAPFactory创建并绑定QName保证命名空间和前缀正确。如果直接调addChildElement(auth)生成出来的元素不带泛微要求的命名空间服务端会返回“无法定位到服务”之类的错误但网络层看起来又是通的特别容易误导排查方向。3.3 组装创建流程的请求主表字段怎么塞拿到端口之后先设置超时。泛微接口在流程数据量大时响应可能很慢默认超时太短容易被误判为失败。import java.net.URL; import javax.xml.namespace.QName; import javax.xml.ws.BindingProvider; import java.util.Collections; WorkflowService service new WorkflowService( new URL(http://192.168.1.10:8080/services/workflowService?wsdl), new QName(http://www.weaver.com.cn/webservice/, workflowService)); WorkflowServiceSoap port service.getWorkflowServiceSoap(); BindingProvider bp (BindingProvider) port; bp.getRequestContext().put(com.sun.xml.internal.ws.connect.timeout, 10000); bp.getRequestContext().put(com.sun.xml.internal.ws.request.timeout, 60000); ((SOAPBinding) bp.getBinding()).setHandlerChain( Collections.singletonList(new WeaverAuthHandler(1, md5(admin123)))); WorkflowRequestInfo requestInfo new WorkflowRequestInfo(); requestInfo.setWorkflowId(32); requestInfo.setCreatorId(1); requestInfo.setRequestName(采购合同审批-2024-11-29); WorkflowMainTableInfo mainTable new WorkflowMainTableInfo(); mainTable.setFieldName(new String[] {htbh, htmc, sqje, gysmc}); mainTable.setFieldValue(new String[] {HT-2024001, 办公楼保洁服务合同, 150000.00, XX环境工程有限公司}); requestInfo.setMainTableInfo(mainTable); String requestId port.createWorkflowRequest(userId, passwordMd5, requestInfo); System.out.println(流程实例ID requestId);两个参数细节要特别留意。第一个是setWorkflowId(32)这里是流程定义的ID不是流程的名称。这个ID可以从泛微后台流程建模的URL参数里看到也可以去数据库workflow_base表里查。把流程名称当成ID传进去接口返回一个看似正常的空串后台却找不到这条流程这是典型翻车现场。第二个是主表字段名。setFieldName里填的htbh、htmc这一类必须是泛微表单设计里的字段名也就是字段属性面板里看到的英文名不是界面上显示的中文标签。字段名和字段值的数组长度必须一致下标一一对应。3.4 返回结果解析requestId、错误码和空值判断创建流程接口的返回值在不同补丁版本里不完全一致。多数情况下返回的是流程requestId字符串拿到之后就能拿它查询流程状态、做提交或退回。但有些版本返回的是整数状态码0表示失败、1表示成功拿不到具体的requestId。我一般的做法是不管返回什么先打印出来看类型如果是数字再调getWorkflowRequestInfo这一类的查询接口按workflowId加主表数据的条件反查requestId。千万别在代码里写死“返回0就是成功”泛微不同模块的返回码含义并不统一。提示接口文档里给的都是理想情况下的返回格式真实环境里最常遇到的是“接口返回成功但后台查无此单”。所以每一次创建请求都要配套做一次查询来确认数据真的落进去了。4. e-cology 8 webservice调试避坑认证失败、字段名不匹配的5个真实案例4.1 密码MD5还对不上密码策略和RSA加密的坑现象Java代码里把密码做了MD5按文档构造认证头调用接口却一直报“认证失败”或“用户名或密码不正确”。原因e-cology 8不同版本的密码策略不一样。有的版本内部直接校验MD5值有的版本在MD5之后又做了加盐处理还有的现场启用了RSA加密传递导致你算出来的MD5和服务端保存的密文不是一回事。接口文档通常只写“密码采用MD5加密”不会写现场实际开的策略。解决不要一上来就调加密算法。先用泛微自带的接口调试工具或者AnyProxy这类抓包工具在浏览器里登录一次OA拿到登录成功后的sessionid放到认证头的sessionid字段里先确认SOAP整体结构没问题。然后再回头处理账密认证。如果必须用账密去OA后台查一下“系统设置”里的密码安全策略确认是否勾选了“启用RSA加密传递”。勾选了的话得先调用泛微的RSA服务拿公钥加密密码这一步躲不掉。4.2 sessionid超时泛微OA登录时长设置影响接口稳定现象联调阶段一切正常上线一周后每天早上第一次调用都报sessionid过期重试一次又好了。原因e-cology 8对登录会话有时长限制后台对应一个“登录时长设置”默认值可能只有两小时左右。超过这个时间的sessionid会被服务端清理。很多人的代码逻辑是启动时拿一次sessionid就一直复用一旦被清理后面所有请求都跟着失败。解决两种做法。第一种是改OA后台的登录时长设置把它调成8小时同时在代码里加一个定时任务在过期前重新获取sessionid。第二种更稳不依赖sessionid改成账密认证每次请求都带上userid和password。泛微服务端在账密有效的前提下不会强制校验sessionid等于绕开了会话时长这个变量。我后来接的项目都默认走账密省心得多。4.3 字段名对不上主表、明细表与建模引擎字段差异现象接口返回成功但OA后台查不到数据或者数据写到了错误的字段里。原因这是最常见也最坑的一条。泛微表单里的“字段标签”和“字段名”是两回事。界面上看到的“申请金额”字段名可能是sqje也可能是表单ID加序号生成的一串编码。用显示标签去传值服务端不报错只是把数据写进未知字段或者直接丢弃。解决去流程设计器或者建模引擎里打开表单找到字段属性面板看真正的英文标识。主表字段和明细表字段要分开处理明细表数据要单独构造WorkflowDetailTableInfo对象不能混在主表字段数组里。还有一个实用办法先调用创建流程配套的模板查询接口拿到这个流程模板自带的字段列表直接按字段列表组装数据字段名和必填项一次都确认了。4.4 日期和金额格式接口里的格式陷阱现象流程创建成功但OA表单里日期变成1970-01-01金额多了小数位或者变成了0.00。原因泛微webservice对日期字段默认按yyyy-MM-dd HH:mm:ss解析部分版本也接受yyyy/MM/dd但如果直接传yyyyMMdd解析失败后字段会落到默认值。金额字段需要用字符串传入不能带千分位分隔符150,000.00传进去会截断成150看起来像是数据丢了一半。解决日期统一格式化到时分秒比如2024-11-29 08:00:00不要偷懒只传日期。金额去掉千分位保留两位小数按字符串传。如果流程字段是数字型泛微内部会做转换传150000.00是安全的。这条规则对建模引擎同样适用。4.5 前端代码块不执行隐藏字段、下拉框类型和合计计算公式的真相现象通过webservice创建流程后发现表单里根据筛选框的值隐藏字段的逻辑没有生效明细表下拉框类型也没按预期切换合计字段更没有重新计算。原因很多泛微表单会用到“流程插入代码块”在字段变更时触发隐藏、下拉框类型切换或者触发合计字段计算公式变化。这些逻辑是跑在浏览器前端JavaScript里的。webservice直接往服务端写数据根本不加载表单页面自然也就不会触发这些前端脚本。解决常见的做法有两个。一是在流程设计时把这些计算逻辑放到服务端代码块里而不是前端代码块二是调整调用顺序先创建流程拿到requestId再调用字段更新接口把关联字段补传进去让服务端的逻辑在二次更新时触发。如果二次更新仍然不生效说明这些逻辑和浏览器事件绑定得太深只能考虑改用模拟登录的方式或者把单子留在用户待办里让人工补充。5. 泛微OA与外部系统集成的三种落地模式待办推送、主数据同步与审批回传5.1 统一待办中心拉取OA待办推到钉钉和企业微信很多企业要把OA待办聚合到钉钉或者企业微信的工作台里这一步的核心就是从OA拉出待办数据。常见做法是直接用workflowService的待办查询接口按登录用户身份获取待办列表。这里有一个权限边界要提前确认泛微的待办是按人隔离的不要试图用管理员账号去拉所有人的待办。要么模拟每个用户的身份调用一次要么确认接口入参里是否直接支持传入目标用户的ID。// 拉取指定用户的待办列表方法名以wsimport生成的实际代码为准 WorkflowRequestInfo[] todoList port.getTodoWorkflowRequestList(userId, pwd, 0, 50); for (WorkflowRequestInfo item : todoList) { String requestId item.getRequestId(); String title item.getRequestName(); String creator item.getCreatorName(); // 推送企业微信应用消息 wecomApi.sendTextMessage(all, 新增审批待办 title); // 也可以同时走短信网关例如云MAS平台的http接口触达没装App的同事 smsGateway.send(180****1234, 您有新的OA审批待办); }逻辑说明这里先拉待办列表再逐条推给企业微信和短信网关。云MAS平台这类短信网关的HTTP接口很简单拿accessToken组装文本POST出去就行但要注意推送频率和去重避免同一个待办被重复提醒。5.2 主数据同步把ERP组织架构写入建模引擎很多ERP、HR系统需要把部门、成本中心、供应商主数据同步到OA。直接写OA的hrmdepartment表风险很高泛微有缓存机制改了库不一定立即生效而且一旦字段写错还影响登录。更稳的做法是把主数据落到建模引擎的实体表里再通过建模的事件机制同步到组织表。具体步骤大致是先在OA建模引擎里创建一张“外部组织同步表”字段用deptCode、deptName、parentCode、syncTime然后从ERP侧拉取组织数据转为JSON或XML调用建模引擎的webservice逐条写入。建模引擎接口的服务名和入参类型因版本而异但大多数情况下会提供按表单ID写入数据的方法入参结构跟workflowService的主表字段模式类似都是字段名和字段值数组。这个方案的优点是不碰系统表出问题可以随时删掉同步表重建。缺点是建模引擎在不同版本的接口稳定性差异较大上线前一定要做压测。如果发现大批量写入时响应变慢常见做法是分成小批量写入每批100条中间加短暂间隔比一次塞几千条成功率高得多。5.3 审批结果回传让ERP知道OA这边批没批流程审批完成之后外部系统需要知道结果。回传方式通常有两种。第一种是OA主动回调。在流程最后一个节点的操作按钮里写一段调用外部HTTP接口的代码把审批结果POST回ERP。这种方式实时性好但对外部系统的接口稳定性要求高ERP接口一波动OA节点操作就报错影响用户体验。第二种是外部系统主动轮询。外部系统定时调用workflowService的流程状态查询接口根据requestId拿到当前节点和状态对比自己的业务单据号。这种方式实现简单不容易受单点故障影响但有延迟还要注意控制轮询频率别把OA的webservice压垮。实际项目里我一般推荐第二种做底第一种做补充。重要的审批结果用回调推送拿不到回执时再靠轮询兜底。不要只依赖一种线上故障的血泪经验告诉我回调通道一旦静默失败等业务方发现数据对不上往往已经是几天后的事了。6. 用WSDL对比和日志定位e-cology 8接口版本变化泛微OA隔几个月打一次补丁打完补丁接口行为可能就变了。比较常见的翻车场景是小版本升级后原来一直正常的创建流程接口忽然报错但代码一行没改。我的习惯是升级前把关键服务的WSDL存一份带日期的文件。升级后再导出一份新的然后做一次对比diff -u workflowService_20240101.wsdl workflowService_20250101.wsdl | grep -E ^[-] | head -80输出里凡是带-和的行就是接口入参、返回类型或方法名变化的直接证据。常见的差异有两种一是某个方法整体没了说明服务端做了接口收拢二是某个元素的类型从string变成了int或者多了一个必填的element这类变化不报错但会导致数据落库异常。看到这种diff结果直接按新WSDL重新生成客户端再对照改动点调整代码不需要把整个接口文档再读一遍。如果升级后没有保留旧WSDL也没有做diff那就只能靠日志定位了。e-cology 8的日志一般在安装目录\ecology\log\下可以先找跟soap、workflow相关的日志文件再把同名请求在升级前后的日志翻出来对比。平时调接口出问题第一反应不是重新看文档而是先翻日志定位到时间点对应的异常栈大部分问题一目了然。还有一点是回归验证。项目里我会维护一个最小化的接口冒烟脚本包含创建流程、查待办、获取流程状态、上传附件这几个核心动作。每次OA升级完先跑一遍冒烟确认四条主链路都通再让业务方去做大范围验证。这样可以把升级影响控制在半小时内。之前有个项目升级后流程附件接口静默失效所有上传的附件都是空文件。因为没有保存升级前的WSDL排查了整整两天最后是拿备份环境的接口日志逐字段对才发现附件服务的返回值多了一层编码包装。从那以后我每接手一个泛微集成项目第一周就建立WSDL基线并且写进项目交接文档里。希望这个习惯能帮到你省得下次升级后再花两个通宵从头查起。本文还有配套的精品资源点击获取