OA工作流之“接口设计”
OA的核心是工作流，单位中需要流转的工作，都应该使用OA工作流进行处理。单位中可能有多个业务和管理系统，这些系统需要流转审批的东西应集成到OA中，这就要求OA工作流必须提供“外部接口”，其它系统才能集成进来。各系统的开发技术和运行平台可能各不相同，接口技术应与平台无关，才能方便集成。新一代钛生智能办公系统的工作流提供了WebService接口供外部系统调用，下面我们来看一下接口的设计。
1、WebService简述
WebService技术与平台无关，使用SOAP协议通过http传输，请求报文和返回报文都是XML格式。WebService由服务端和客户端组成，各种开发技术都支持WebService服务端和客户端的开发，这就使WebService成为最常用、最简单的系统接口和集成技术。
WebService服务端将一个系统中的功能，以Web API的形式暴露出来，供外部其它系统调用。服务端也就是我们所说的WebService接口。
WebService客户端就是外部系统编写的，用于调用WebService服务端API的程序。
2、WebService接口设计
系统设计了“创建工作”和“查询工作”两个接口，通过创建工作接口可以创建工作、填入表单数据和附件、然后保存或提交工作，通过查询工作接口可以查询工作的办理情况并返回数据。
接口的参数和返回值均采用json格式字符串，附件采用base64编码方式的字符串进行传输。
调用接口的参数必须包含用户名和密码做为身份认证。接口用户也是一个“人员”，由系统管理员在组织机构中专门为接口创建一个“人员”，人员姓名就是接口用户名，接口用户在组织机构中一般设为“停用”状态，这样只有接口调用能够使用。
（1）接口地址
接口地址为：
http://服务器地址:8080/taioa8/webservice/taiWebService?wsdl
（2） 创建工作接口
创建工作接口方法名为createWork，通过该接口可以创建工作，并填写表单数据和附件，然后保存到指定人员的拟办工作中，或者直接提交流转。填写表单数据时，受流程创建环节的可编辑字段控制，只有可编辑的字段才能填写进去。
接口方法：
public String createWork (String jsonStr)
参数说明：
{
userName : ’用户名’,
password : ‘密码’,
flowName : ‘流程名称’, //指定用于创建工作的流程
isSubmit : false/true, //是否提交
operator : ‘人员姓名’, //指定拟办人员，或提交的办理人（办理人由上一环节指定时）
stepName : ‘环节名称’, //指定提交的后续环节（后续环节需要选择时）
subject : ‘工作标题’,
importance : ‘重要性’, //一般，重要
urgency : ‘缓急’, //一般，加急，特急
//表单数据（支持除“正文”外的所有字段类型。注意：(1) 附件字段的格式有别于其它字段，用name和files。(2) 富文本字段中如果包含有图片，应使用base64 img标签。）
data : [{
name : ‘字段名’,
value : ‘值’ //值得类型应与表单字段匹配，可能是字符串、数值或日期。日期和时间字段的值，使用YYYY-MM-ddTHH:mm:ss格式字符串。
} , {
//附件字段
name : ‘字段名’,
files : [… ] //文件数组，格式与附件数据相同
} , ……
],
//附件数据（文件数组），这里是指附件字段之外的附件。
files : [{
fileName : ‘文件名’,
content : ‘base64编码的文件内容字符串’,
contentType : ‘类型’ //可有可无
} , ……
]
}
返回值说明：
{
success : true/false, //是否创建成功
message : “字符串 ”, //失败时，返回的失败信息
workToken :“字符串” , //创建成功时，返回该工作对应的令牌，用于该工作的后续查询。
}
（3）查询工作接口
查询工作接口方法名为queryWork，通过该接口可以查询createWork接口创建的工作，可返回状态，以及指定的表单字段数据和附件数据。
接口方法：
public String qureyWork(String jsonStr)
参数说明：
{
userName : ’用户名’,
password : ‘密码’,
workToken : ‘要查询工作的令牌’,
returnMode : 0/1/2, //流程未结束时的数据返回模式。0：不返回表单字段值和附件，1：返回表单字段值和附件，2：只返回表单字段值
returnData : ‘字符串’, //需要返回的表单字段，字段名用逗号连接。
isReturnFiles: false/true, //是否返回附件（这里是指附件字段之外的附件）
}
返回值说明：
{
success : true/false, //是否查询成功
message : “字符串 ”, //失败时，失败信息
isEnd : false/true, //工作是否流转结束
currentStep : ‘当前环节’, //未流转结束时，返回当前环节名称
currentOperator : ‘当前办理人’, //未流转结束时，返回当前办理人
//返回的表单数据
data : [{
name : ‘字段名’,
value : ‘值’ //根据表单字段的类型，可能是字符串、数值或日期。日期和时间字段的值，使用YYYY-MM-ddTHH:mm:ss格式字符串。富文本字段中如果包含有图片，是使用base64 img标签。
} , {
//附件字段的格式
name : ‘字段名’,
files : [… ] //文件数组
} , ……
],
//返回的附件数据（文件数组）
files : [{
fileName : ‘文件名’,
content : ‘base64编码的文件内容字符串’,
contentType : ‘类型’
} , ……
]
}
3、接口测试程序
为了帮助第三方开发人员直观地了解接口，系统中自带了一个接口测试的WebService客户端程序。该程序可使用当前表单数据发送一个“创建工作”接口调用，还可发送“查询工作”接口调用。
（1） 测试程序的使用
首先在系统中创建一个接口用户，姓名：webservice，密码：123456 。在任一流程中创建一个名为“WebServiceTest”的环节，当工作流转到该环节时，表单操作条上会有“WebServiceTest创建”和“WebServiceTest查询”两个按钮。
点击“WebServiceTest创建”，会使用当前表单中的数据（字段和附件）发送一个“创建工作“接口调用。调用的参数可在WebServiceTest.properties文件中配置（该文件在webapps/taioa8/properties目录中）。如果未进行配置会使用一组默认值去调用，默认是：使用表单中所有有值的字段，带附件，使用和当前工作同样的流程，创建一个工作不提交，保存为admin的拟办工作。
点击“WebServiceTest查询”，会发送一个“查询工作“接口调用，查询刚才创建成功的工作。调用的参数也可在WebServiceTest.properties文件中配置。如果未进行配置会使用一组默认值去调用，默认是：流转未结束时不返回数据，只返回状态，流转结束时返回当前表单中所有无值的字段，并带附件。
上述接口调用，会将发送的参数和返回的信息打印到系统控制台，开发人员可以通过参数和返回的格式直观的理解接口。
（2）测试程序配置文件WebServiceTest.properties文件
通过配置文件可以改变接口调用的参数，配置文件如下：
#WebServiceTest（客户端）参数配置文件
#WebService服务器的url，用户名和密码
url = http://127.0.0.1:8080
userName = webservice
password = 123456
#WebServiceTest创建:
#流程名称。为空时（默认值）使用当前工作的流程名称
flowName =
#是否提交。0：保存为拟办，1：提交
isSubmit = 0
#提交时，如需指定后续办理环节，或者需要选择后续办理环节，由stepName指定或选择。
stepName =
#保存为拟办时，指定拟办人姓名
#提交时，如果后续环节的办理人由上环节指定，在这里指定办理人姓名（如果多人，用逗号连接）
operator = admin
#当前表单中需要发送的字段名称，多个字段用逗号连接。
#为空时，（默认值）使用当前表单中所有有值的字段名连接成字符串。
sendData =
#是否发送附件（这里指的是附件字段之外的附件）。0：不发送，1：发送
isSendFiles = 1
#WebServiceTest查询:
#流程未结束时的返回模式。0：不返回表单字段值和附件，1：返回表单字段值和附件，2：只返回表单字段值
returnMode = 0
#要返回的表单字段名称，多个字段用逗号连接。
#为空时，（默认值）使用当前表单中所有无值的字段名连接成字符串。
returnData =
#是否返回附件（这里指的是附件字段之外的附件）。0：不返回，1：返回
isReturnFiles = 1
（3）测试程序中WebService客户端部分代码
测试程序是用java编写的，使用Apache CXF WebService客户端，代码如下（供参考）：
import org.apache.cxf.endpoint.Client;
// WebService动态客户端
public class MyClient {
public static String request(String wsdlUrl, String method, String jsonStr) {
// CXF动态客户端工厂
JaxWsDynamicClientFactory dcf = JaxWsDynamicClientFactory.newInstance();
Object[] objects = null;
try {
// 获取CXF客户端
Client client = dcf.createClient(wsdlUrl);
// 设置超时单位为毫秒
HTTPConduit conduit = (HTTPConduit) client.getConduit();
HTTPClientPolicy policy = new HTTPClientPolicy();
policy.setConnectionTimeout(15000);
policy.setAllowChunking(false);
policy.setReceiveTimeout(30000);
conduit.setClient(policy);
// 调用Web Service方法
objects = client.invoke(method, jsonStr);
} catch (Exception e) {
e.printStackTrace();
}
// 获取调用结果
String result = “”;
if (objects[0] != null) {
result = String.valueOf(objects[0]);
}
return result;
}
结语： OA工作流提供了WebService接口供外部系统调用，其它系统需要编写WebService客户端程序调用接口实现集成。如果其它系统提供了接口，也可以在OA中编写客户端程序进行调用实现集成。两个系统集成的方式就是：一方提供接口，另一方编写调用程序；如果都没有接口，那就要大费周折了。