泛微e-cology 8 Webservice接口对接实战：从WSDL到流程创建

简介泛微OA e-cology 8 最新webservice接口文档面向需要对接泛微OA系统的开发人员解决通过Webservice方式操作文档管理的需求。资源为1个docx文件大小330KB内容涵盖接口部署说明、方法定义与参数返回示例并完整列出DocInfo文档对象的属性字段。接口方法包括login、createDoc、updateDoc、deleteDoc、getDoc、getDocCount、getList可实现对文档增删改查及权限范围内的列表获取部署步骤清晰附有services.xml配置代码和WSDL验证方式。文档尤其详细地说明了文档ID、类型、标题、编号、目录、部门、语言等核心属性便于二次开发时快速定位。已有6765人学习下载适合泛微OA实施顾问、集成开发工程师及企业IT运维人员参考能够有效缩短接口联调时间提升系统集成效率。1. e-cology 8 的 webservice 接口到底能做什么做企业系统集成的工程师迟早会撞上泛微 OA。e-cology 8 是泛微前几年主推的版本目前仍然有大量政府机关和企业在跑。只要涉及「让 OA 和 SAP、HR、ERP 或者自研平台产生数据来往」就会看到一份名为《泛微 OA e-cology 8 webservice 接口文档》的 PDF 在甲方手里传来传去。很多人拿到这份文档的第一反应是崩溃里面没有统一的技术框架说明也没有示例工程有的只是几张大表、几个 URL 片段和大量的字段注释。这个标题的关键词拆开来看「webservice」说明对接方式走的是 SOAP 协议而非 REST「e-cology 8」说明它的服务端基于 Axis2 实现接口路径、命名空间、数据封装都沿用了泛微 v8 那套固定结构「接口文档」则意味着你真正需要的是几类东西——服务地址、WSDL 文件、认证方式、每个业务动作的请求报文样例以及字段含义。这篇文章会把这几样东西按你实际去甲方现场做集成的顺序讲清楚从找接口、拉 WSDL 开始到调通创建流程、上传附件再到查待办和排错每一段都可以直接复用到真实环境里。2. 先定位接口清单地址、WSDL 与 Axis2 服务列表做泛微 e-cology 8 的接口开发第一步不是写代码而是搞清楚这台 OA 服务器上到底发布了哪些服务。泛微的 webservice 是基于 Axis2 部署的服务本身安装在 OA 应用目录下端口和路径由系统配置文件决定。这一章的价值在于哪怕你手上没有任何接口文档也能在半小时内把服务器上的服务清单摸出来。2.1 接口地址与端口默认配置泛微 e-cology 8 的 webservice 服务默认部署在应用服务器的 webapps 目录中。常见的部署方式是 Tomcat 或 Resin。假设 OA 地址是http://192.168.1.100:8080那么 webservice 的服务根路径是http://192.168.1.100:8080/services/在浏览器直接访问这个路径Axis2 会返回一个 HTML 页面列出当前发布的所有服务名称。如果你看到一个类似workflowService、fileService、hrmService的列表就可以点进具体的服务链接来查看 WSDL。以创建流程最常用的接口为例它的 WSDL 地址是http://192.168.1.100:8080/services/workflowService?wsdl?wsdl是 Axis2 的标准查询参数通过这个 URL 可以直接拿到 XML 格式的接口定义。除了8080这个默认端口部分客户环境会在前端做 Nginx 反向代理把 OA 域名映射到80或443端口这种情况直接用域名拼接/services/路径即可。2.2 从安装目录找官方接口文档很多项目的接口文档是直接放在 OA 服务器上的。e-cology 8 安装完成后在应用目录的classic或ecology文件夹下能找到一个名为webservice的目录里面存放着接口说明的压缩包。依次进入ApacheJetspeed/webapps/ecology/webservice你通常能看到类似webservice_java_api.zip的文件。解压之后是 Java 版的说明文档和示例代码。它里面的内容比甲方转发的 PDF 更完整因为包含了接口报文的完整 SOAP 示例和返回结果的结构说明。如果客户环境里找不到还有一个办法直接在 OA 服务器上执行find / -name *webservice*这个命令系统会打印出所有包含 webservice 的文件路径定位速度比翻文档快得多。2.3 使用 SoapUI 或 Cool Request 快速浏览服务结构拿到 WSDL 地址后下一步是把接口的结构看明白。老工程师习惯用 SoapUI但新版工具里 Cool Request 也值得推荐它导出接口文档的能力适合给甲方交付存档。在 SoapUI 中新建 SOAP Project把 WSDL 地址粘贴进去工具会自动解析出这个服务的所有操作方法。以workflowService为例解析后你能看到getCreateWorkflowRequest、submitWorkflowRequest、getForwardWorkflowRequest等十几个方法。每个方法展开后Request 和 Response 的报文骨架就自动生成了。这里需要特别留意的是泛微的接口方法名和参数类型之间没有统一规则有的方法接受一个自定义对象有的方法接受字符串数组所以必须在 SoapUI 里逐个点开看参数结构不能靠猜。首次对接时建议把 SoapUI 的请求报文保存成xml文件方便后续用脚本回放。3. 认证与 token 获取调通第一个接口泛微 e-cology 8 的 webservice 对安全认证的控制比老版本严格。在 v5、v6 时代很多接口只要知道 URL 就能直接调用到 v8 之后统一要求先获取 token再拿着 token 去请求业务接口。这一章把认证这一步彻底拆开从原理讲到代码。3.1 认证方式与 token 有效期e-cology 8 的 webservice 认证走的是 token 机制。流程如下调用getUserToken方法传入用户名和密码服务器验证通过后返回一个加密字符串这就是 token。之后调用其他任何业务接口之前都要先调用checkUserToken方法验证 token 是否有效或者直接在请求报文里携带 token 参数。token 默认的有效期由 OA 系统参数webservice.token.timeout控制单位是毫秒默认值通常是 1800000也就是 30 分钟。调通认证之后你会发现一个很实际的问题有些业务接口要求 token 必须在报文头里有些则要求放在业务数据的某个字段里。这在你们自己写调用代码时需要非常小心顺序错了或者位置错了返回的错误信息并不直观排查起来很费劲。3.2 用 Java 代码获取 token我一般用 Java 和 Axis2 的客户端库来做这块因为 e-cology 8 自带的示例代码也是这套。用 Maven 管理依赖时加入以下两个核心依赖dependency groupIdorg.apache.axis2/groupId artifactIdaxis2-kernel/artifactId version1.7.9/version /dependency dependency groupIdorg.apache.axis2/groupId artifactIdaxis2-transport-http/artifactId version1.7.9/version /dependency先用wsdl2java工具把 WSDL 生成 Java 类然后在代码里调用WorkflowServiceStub stub new WorkflowServiceStub(http://192.168.1.100:8080/services/workflowService); // 创建请求对象并设置用户名密码 GetUserToken getUserToken new GetUserToken(); getUserToken.setLoginid(admin); getUserToken.setPassword(123456); GetUserTokenResponse response stub.getUserToken(getUserToken); String token response.getGetUserTokenResult(); System.out.println(获取到的token: token);参数说明loginid是 OA 中的用户登录名password是登录密码。注意 e-cology 8 的密码校验走的是 OA 自身登录逻辑不是简单的 MD5 或 Base64你不需要在客户端做任何额外加密处理直接传明文。返回结果getUserTokenResult是 String 类型这就是后续所有请求要携带的 token。3.3 调用业务接口时携带 token获取 token 之后调业务接口的方式也不复杂。以查询待办列表为例需要在业务方法参数中传入刚才拿到的 tokenGetForwardWorkflowRequest request new GetForwardWorkflowRequest(); request.setToken(token); request.setUserid(admin); request.setCrequestid(12345); GetForwardWorkflowRequestResponse resp stub.getForwardWorkflowRequest(request); System.out.println(resp.getGetForwardWorkflowRequestResult());这里的userid不是登录名而是 OA 系统内部的用户 ID可以在 OA 后台的用户管理界面看到。如果只拿到了登录名需要通过getUserByLoginId之类的接口把它转成用户 ID。这两者在接口文档里非常容易混淆实际对接中报「用户不存在」的错误时十有八九是把loginid当成userid传了。4. 高频接口流程创建、附件上传与待办查询认证打通之后你基本可以开始干正事了。泛微 e-cology 8 的 webservice 接口数量很多但如果从真实业务发生的频率来看大约有 80% 的集成需求都集中在三类操作上创建流程、上传附件、查询待办。这三类接口有一个共同特点入参结构非常重字段嵌套深文档里含糊的地方也多。所以这一章会逐个给出可运行的请求报文和代码示例。4.1 创建流程实例的报文结构创建流程是外部系统向泛微 OA 发起审批的入口。比如你的 SAP 系统要发起一笔采购申请就是调用这个接口。它的核心方法是doCreateWorkflowRequest传入参数是一个叫做WorkflowRequestInfo的复杂对象。这个对象里面嵌套了主表字段、明细表字段、创建人信息、流程 ID 等多个子对象。以下是用 Java 构造请求的代码骨架WorkflowRequestInfo requestInfo new WorkflowRequestInfo(); requestInfo.setWorkflowid(100); // 流程ID在OA后台流程设计里查看 requestInfo.setRequestname(采购申请单-20240516-001); // 表单标题 requestInfo.setCreatorid(20); // 创建人用户ID requestInfo.setRequestlevel(0); // 紧急程度0普通 1重要 2紧急 // 主表字段 WorkflowMainTableFields mainFields new WorkflowMainTableFields(); ArrayOfWorkflowMainTableField fieldList new ArrayOfWorkflowMainTableField(); WorkflowMainTableField field new WorkflowMainTableField(); field.setFieldname(sqr); // 字段内部名称表单设计时定义 field.setFieldvalue(张三); fieldList.addWorkflowMainTableField(field); mainFields.setWorkflowMainTableField(fieldList); requestInfo.setWorkflowMainTableFields(mainFields);workflowid是最容易填错的参数。它不是你在 OA 后台看到的流程显示名称而是流程设计界面 URL 上显示的数字 ID。如果把名称填进去接口会返回「流程不存在」的错误。另外fieldname是字段在数据库层面的内部标识不是表单上的中文标签。要拿到这个内部标识需要在 OA 后台的表单设计器中查看字段属性它通常和数据库表字段名一致。4.2 上传附件到流程业务流程几乎都会带上附件。上传附件的接口是fileService里的/services/fileService。这个接口接受字节数组形式的文件内容和元信息。我遇到的常见场景是外部系统把 PDF 账单推送给 OA 作为审批附件实现方式如下FileServiceStub fileStub new FileServiceStub(http://192.168.1.100:8080/services/fileService); byte[] fileBytes Files.readAllBytes(Paths.get(invoice.pdf)); UploadFile uploadFile new UploadFile(); uploadFile.setFilename(invoice.pdf); uploadFile.setContent(fileBytes); uploadFile.setToken(token); UploadFileResponse resp fileStub.uploadFile(uploadFile); String fileId resp.getUploadFileResult();返回的fileId是 OA 服务器上的附件唯一标识拿到后可以拼接到流程请求的附件字段中。需要注意设置fileBytes时如果文件较大超过 10MB很可能出现 SOAP 报文超时的情况。在测试环境里调通很容易但生产环境建议提前调整 Tomcat 的连接超时参数connectionTimeout和maxPostSize都放开一些否则上传到一半连接被切断排查起来很难受。4.3 查询待办与流程状态外部系统需要知道某个流程走到哪一步了或者某个人的待办有多少这是集成的另一个常见需求。查询待办的接口方法名在不同版本的接口文档里叫法不一样e-cology 8 的workflowService中通常是getForwardWorkflowRequest传入userid和token返回的是待办列表的 XML 字符串。解析这段 XML 时建议直接使用 XPath 定位节点不要用正则去匹配。因为泛微返回的 XML 里字段顺序在不同流程类型之间不固定正则匹配很容易因为换行或缩进而失效。待办查询返回的数据结构里有一个值得注意的字段requestid它是每个流程实例在 OA 中的唯一编号。后续要用 webservice 做流程撤销、催办或者查看审批记录时都需要用到这个requestid所以它在你的外部系统库里应该与业务单据号建立一对一的映射关系。5. 接口排错的关键参数与调优技巧e-cology 8 的 webservice 接口整体稳定性不错但真正把它接到生产环境时那些让你熬到凌晨的问题往往不在业务逻辑层面而是集中在几个固定的技术点上。这一章直接把这些点拿出来逐个击破。5.1 常见错误提示与定位方法甲方运维手里那张截图里经常出现的「提示代码:-16」、o a 系统访问失败等问题相当一部分原因并非泛微服务器本身挂了而是 webservice 调用端的请求被前置 Nginx 或负载均衡拦截了。遇到这类无需看日志就可以确认的状况时先做一件事curl -X POST http://192.168.1.100:8080/services/workflowService -d SOAP报文 -H Content-Type: text/xml; charsetutf-8 -H SOAPAction: urn:getUserToken如果 curl 能正常返回说明网络链路没有问题问题在代码的程序逻辑上。反之如果 curl 超时或返回 502应该优先检查 Nginx 对8080端口的转发配置以及 OA 应用服务器的线程池状态。另一个常见的报错是「token expired」或「session invalid」。这种情况通常不是代码逻辑错误而是你的业务系统调用频率过高。比如一个定时行情同步程序每 5 分钟调一次 OA 接口但 token 有效期只有 30 分钟逻辑上应该复用同一个 token 而不是每次新建。仔细审查你们的客户端代码确认 token 是否存储并复用了。5.2 调整 WSDL 生成代码避免踩坑用wsdl2java生成客户端代码时默认生成的stub文件对泛微的接口支持很好但有一个地方几乎所有人都翻过车默认的Options对象里没有设置超时时间。一旦 OA 服务器响应稍微慢一点客户端就会抛出SocketTimeoutException。因此在初始化 stub 之后务必加上这段配置Options options stub._getServiceClient().getOptions(); options.setTimeOutInMilliSeconds(60000); options.setProperty(org.apache.axis2.transport.http.HTTPConstants.CONNECTION_TIMEOUT, 60000);第一行设置的是 SOAP 请求的全局超时第二行设置的是 TCP 连接超时。这两个值在生产环境里至少要设置到 60 秒。不要听信某些资料里说的 5 秒、10 秒因为 OA 后台一旦有用户的流程引擎繁忙接口响应时间超过 20 秒是常见现象。如果把超时设得太短你会反复收到连接重置的错误而这其实并非接口本身的问题。5.3 外部系统下载泛微 OA 附件的正确姿势很多人关注泛微 OA 的附件下载这个动作在 webservice 接口文档里反而着墨不多。e-cology 8 提供了一套专门的附件下载服务接口名是fileService中的getFile方法传参是文件 ID返回的是字节数组。但注意这个接口对请求报文的大小非常敏感如果文件的 ID 是多个需要用ArrayOfString封装不能拼接成带逗号的字符串。下载附件后先在本地临时目录写入文件确认文件头是正确的 PDF 或 ZIP 格式再去做后续入库或者推送 SAP 的操作。这样做的好处是当函数执行到报文解析那一段时不会被一个残缺的文件流干扰报错时你也能快速判断到底是下载坏了还是解析坏了。另外下载接口对于超大文件超过 50MB支持并不理想。如果你的业务确实要处理这么大的附件建议直接在服务器上写一个独立的文件处理服务让它把文件放入共享目录外部系统通过文件服务读取而不是走 SOAP 流程这样性能和稳定性都会好很多。本文还有配套的精品资源点击获取