工作台待办接入指南
2023年10月13日大约 11 分钟
工作台待办接入指南
提示
该文档主要介绍第三方业务系统如何将业务系统待办任务接入至网办平台工作台中进行集成审批操作。
前置条件
- 需能访问网办平台服务地址。
- 需要联系实施人员进行接入应用授权，获取调用接口授权ID。
第三方业务系统集成步骤
- 创建待办任务流程
创建待办任务：当业务系统需要接入工作台时，首先调用
创建待办任务接口，拿到返回的待办任务id，以便后续业务中能更新待办状态。
- 处理待办任务流程
处理待办任务：待办任务创建成功后，拿着返回的待办任务id，在各业务系统自行控制的逻辑中，增加调用
处理待办任务接口反馈任务状态，
任务文件等信息，来处理待办任务。
步骤一、创建待办任务
注意
注：此接口存在鉴权限制，当遇到此问题时，接口返回结果的msg中会有体现。
创建单个待办任务
1. 接口描述
接口地址：/workflow-engine-service/workTask/applyTask
请求方式：POST
2. 请求参数
注意
参说说明：
- taskForm - 待办任务远程调用地址，当网办平台工作进行审核时会通过iframe方式嵌入该条待办审核页面, 例如：业务系统审核页面名称为
2023级班级获奖名单审核待办，引入地址为http://baidu.com则最终参数为showUrl: 显示名称:http://baidu.com
| 参数名称 | 参数发送方式 | 必选 | 长度 | 类型 | 描述 |
|---|---|---|---|---|---|
| applyType | Body | 否 | 9 | int | 申请类型(groupTask-分组任务) |
| applyUser | Body | 是 | 50 | String | 申请人-工号或学号 |
| taskType | Body | 是 | String | 任务类型-该参数由实施人员提供 | |
| taskForm | Body | 是 | String | 待办任务远程调用地址 | |
| approvalWay | Body | 是 | String | 审批方式（会签-allApproval、或签-signApproval） | |
| taskName | Body | 是 | 50 | String | 任务名称 |
| taskTypeName | Body | 否 | String | 任务类型名称 | |
| disposeUsers | Body | 是 | Arrays | 任务处理人 | |
| callbackParam | Body | 否 | String | 回调参数-备用字段 | |
| appid | Header | 是 | String | 授权ID-该参数由实施人员提供 |
3. 输出参数
| 参数名称 | 说明 | 类型 | 描述 |
|---|---|---|---|
| code | 状态码 | int | 状态码返回为0表示请求成功。 |
| msg | 消息内容 | String | 返回的提示消息。 |
| data | 返回结果数据 | Long | 返回数据 |
4. 请求示例
- 普通或签请求示例
{
"applyUser": "1",
"taskForm": "showUrl:2023级班级获奖名单审核待办:http://lightcode/workflow/apply?id=11",
"taskType": "task_pkpy",
"approvalWay": "signApproval",
"taskName": "2023级班级获奖名单审核待办",
"disposeUsers": ["1","2","3"]
}- 分组或签请求示例
注意
由于或签策略比较复杂，审核人员在业务系统中存在按角色分组场景，所有再遇到分组或签情况，需要业务系统对申请自行进行分组标识，不同之处再与请求参数 disposeUsers 数组中，当个对象 分组标识:用户标识 , 例如：辅导员与班长为一组审核人，定义标识 FDY , 院系领导审核为一组审核人，定义标识 YXLD , 则数据是为 ["FDY:1","FDY:2","YXLD:3","YXLD:4"]
{
"applyType": "groupTask",
"applyUser": "1",
"taskForm": "showUrl:2023级班级获奖名单审核待办:http://lightcode/workflow/apply?id=11",
"taskType": "task_pkpy",
"approvalWay": "signApproval",
"taskName": "2023级班级获奖名单审核待办",
"disposeUsers": ["FDY:1","FDY:2","YXLD:3","YXLD:4"]
}5. 返回示例
| 参数名称 | 数据类型 | 是否必须 | 参数说明 |
|---|---|---|---|
| 无 | Long | 是 | 任务实例id |
- 返回示例
{
"code": 0,
"msg": "操作成功",
"data": 1,
"ok": true
}创建批量待办任务
1. 接口描述
接口地址：/workflow-engine-service/workTask/batchApplyTask
请求方式：POST
2. 请求参数
注意
参说说明：
- taskForm - 待办任务远程调用地址，当网办平台工作进行审核时会通过iframe方式嵌入该条待办审核页面, 例如：业务系统审核页面名称为
2023级班级获奖名单审核待办，引入地址为http://baidu.com则最终参数为showUrl: 显示名称:http://baidu.com
| 参数名称 | 参数发送方式 | 必选 | 长度 | 类型 | 描述 |
|---|---|---|---|---|---|
| applyType | Body | 否 | 9 | int | 申请类型(groupTask-分组任务) |
| applyUser | Body | 是 | 50 | String | 申请人-工号或学号 |
| taskType | Body | 是 | 50 | String | 任务类型-该参数由实施人员提供 |
| taskForm | Body | 是 | String | 待办任务远程调用地址 | |
| approvalWay | Body | 是 | 50 | String | 审批方式（会签-allApproval、或签-signApproval） |
| taskName | Body | 是 | 50 | String | 任务名称 |
| taskTypeName | Body | 否 | 50 | String | 任务类型名称 |
| disposeUsers | Body | 是 | Arrays | 任务处理人 | |
| callbackParam | Body | 否 | String | 回调参数-备用字段 | |
| appid | Header | 是 | String | 授权ID-该参数由实施人员提供 |
3. 输出参数
| 参数名称 | 说明 | 类型 | 描述 |
|---|---|---|---|
| code | 状态码 | int | 状态码返回为0表示请求成功。 |
| msg | 消息内容 | String | 返回的提示消息。 |
| data | 返回结果数据 | Arrays | 返回任务数据列表 |
4. 请求示例
注意
由于或签策略比较复杂，审核人员在业务系统中存在按角色分组场景，所有再遇到分组或签情况，需要业务系统对申请自行进行分组标识，不同之处再与请求参数 disposeUsers 数组中，当个对象 分组标识:用户标识 , 例如：辅导员与班长为一组审核人，定义标识 FDY , 院系领导审核为一组审核人，定义标识 YXLD , 则数据是为 ["FDY:1","FDY:2","YXLD:3","YXLD:4"]
[
{
"applyUser": "1",
"taskType": "task_pkpy",
"taskForm": "showUrl:2023级软件1班-获奖名单审核待办:http://lightcode/workflow/apply?id=22",
"approvalWay": "signApproval",
"taskName": "2023级软件1班-获奖名单审核待办",
"disposeUsers": ["1","2","3"],
"callbackParam": "{\"id\":\"111\"}"
},
{
"applyType": "groupTask",
"applyUser": "1",
"taskForm": "showUrl:2023级软件2班-获奖名单审核待办:http://lightcode/workflow/apply?id=33",
"taskType": "task_pkpy",
"approvalWay": "signApproval",
"taskName": "2023级软件2班-获奖名单审核待办",
"disposeUsers": ["FDY:1","FDY:2","YXLD:3","YXLD:4"],
"callbackParam": "{\"id\":\"222\"}"
}
]5. 返回示例
| 参数名称 | 数据类型 | 是否必须 | 参数说明 |
|---|---|---|---|
| instanceId | String | 是 | 任务实例数据 |
| *** | String | 否 | 动态参数取callbackParam中传入数据 |
- 返回示例
{
"code": 0,
"msg": "操作成功",
"data": [
{
"id": "111",
"instanceId":"1711216898099208194"
},
{
"id": "222",
"instanceId":"1711218455565918210"
}
],
"ok": true
}步骤二、处理待办任务
注意
注：此接口存在鉴权限制，当遇到此问题时，接口返回结果的msg中会有体现。
1. 接口描述
接口地址：/workflow-engine-service/workTask/disposeTask
请求方式：POST
2. 请求参数
| 参数名称 | 参数发送方式 | 必选 | 长度 | 类型 | 描述 |
|---|---|---|---|---|---|
| taskInstanceId | Body | 是 | int | 任务实例id | |
| disposeUser | Body | 是 | String | 处理人 | |
| groupTag | Body | 否 | String | 分组标识 | |
| approvalWay | Body | 否 | String | 审批方式（会签-allApproval、或签-signApproval） | |
| disposeResult | Body | 是 | 2 | int | 处理结果(0-拒绝、1-通过) |
| appid | Header | 是 | String | 授权ID-该参数由实施人员提供 |
3. 输出参数
| 参数名称 | 说明 | 类型 | 描述 |
|---|---|---|---|
| code | 状态码 | int | 状态码返回为0表示请求成功。 |
| msg | 消息内容 | String | 返回的提示消息。 |
| data | 返回结果数据 | Long | 返回数据 |
4. 请求示例
- 普通任务示例
{
"taskInstanceId": "1",
"disposeUser": "1",
"disposeResult": 1
}- 分组任务示例
注意
注： groupTag 分组任务标识，需要创建任务系统时自己根据业务保存传入
{
"taskInstanceId": "1",
"disposeUser": "1",
"groupTag": "signApproval",
"approvalWay": "signApproval",
"disposeResult": 1
}5. 返回示例
| 参数名称 | 数据类型 | 是否必须 | 参数说明 |
|---|---|---|---|
| 无 | Boolean | 是 | 是否成功 |
- 返回示例
{
"code": 0,
"msg": "操作成功",
"data": true,
"ok": true
}步骤三、取消待办任务
注意
注：此接口存在鉴权限制，当遇到此问题时，接口返回结果的msg中会有体现。
1. 接口描述
接口地址：/workflow-engine-service/workTask/cancelTask
请求方式：POST
2. 请求参数
| 参数名称 | 参数发送方式 | 必选 | 长度 | 类型 | 描述 |
|---|---|---|---|---|---|
| instanceIds | Body | 是 | Array | 任务实例id集合 | |
| appid | Header | 是 | String | 授权ID-该参数由实施人员提供 |
3. 输出参数
| 参数名称 | 说明 | 类型 | 描述 |
|---|---|---|---|
| code | 状态码 | int | 状态码返回为0表示请求成功。 |
| msg | 消息内容 | String | 返回的提示消息。 |
| data | 返回结果数据 | Long | 返回数据 |
4. 请求示例
{
"taskInstanceId": ["1","2"]
}5. 返回示例
| 参数名称 | 数据类型 | 是否必须 | 参数说明 |
|---|---|---|---|
| 无 | Boolean | 是 | 是否成功 |
- 返回示例
{
"code": 0,
"msg": "操作成功",
"data": true,
"ok": true
}定制应用接入步骤
步骤一、定义流程Feign接口类
首先，需要准备一个Feign远程调用接口，在Feign的API文件中定义远程调用接口方法，代码如下：
@FeignClient(value = "workflow-engine-service", configuration = FeignConfig.class)
public interface WorkflowEngineServiceFeign {
/**
* 待办单个任务添加
*
* @author mrluo
* @date 2023/6/28 14:30
* @result JsonResult
**/
@PostMapping("/workTask/applyTask")
JsonResult applyTask(@RequestBody WorkflowApplyTask workflowApplyTask);
/**
* 待办任务批量添加
*
* @author mrluo
* @date 2023/6/28 14:30
* @result JsonResult
**/
@PostMapping("/workTask/batchApplyTask")
JsonResult applyTaskBatch(@RequestBody List<WorkflowApplyTask> works);
/**
* 取消待办任务
*
* @param param 请求参数
* @author mrluo
* @date 2023/6/28 16:40
* @result JsonResult
**/
@PostMapping("/workTask/cancelTask")
JsonResult cancelTask(@RequestBody WorkflowApplyCanalTask param);
/**
* 处理待办
*
* @param param 请求参数
* @author mrluo
* @date 2023/6/28 16:40
* @result JsonResult
**/
@PostMapping("/workTask/disposeTask")
JsonResult disposeTask(@RequestBody WorkflowDisposeTask param);
}创建调用对象，代码如下：
/**
* @author mrluo
* @version 1.0
* @description: 申请任务请求对象
* @date 2023/6/28 14:27
*/
@Setter
@Getter
public class WorkflowApplyTask {
/**
* 申请类型 (groupTask-分组任务)
*/
@Schema(description="申请类型(groupTask-分组任务)")
private String applyType;
/**
* 申请人
**/
private String applyUser;
/**
* 任务类型
**/
private String taskType;
/**
* 任务表单 （多个表单id以,分割。内嵌的展示地址必须为showUrl:百度:baidu.com格式！）
**/
private String taskForm;
/**
* 审批方式（会签-allApproval、或签-signApproval）
**/
private String approvalWay;
/**
* 任务名称
**/
private String taskName;
/**
* 任务类型名称
**/
private String taskTypeName;
/**
* 任务处理人
**/
private List<String> disposeUsers;
/**
* 回调参数
**/
private String callbackParam;
}
/**
* @author mrluo
* @version 1.0
* @description: 取消申请任务请求对象
* @date 2023/6/28 14:27
*/
@Setter
@Getter
public class WorkflowApplyCanalTask {
/**
* 实例编号列表
**/
private List<String> instanceId;
}
/**
* @author mrluo
* @version 1.0
* @description: 处理任务请求对象
* @date 2022/6/28 14:27
*/
@Setter
@Getter
public class WorkflowDisposeTask {
/**
* 实例编号
**/
private String taskInstanceId;
/**
* 处理用户
**/
private String disposeUser;
/**
* 处理结果（-1-未处理、1-通过、0-拒绝）
**/
private Integer disposeResult = 1;
/**
* 当任务applyType为groupTask 需要传递分组标签，分组任务完结要结束任务主体时不传递
*/
private String groupTag;
/**
* 审批方式（会签-allApproval、或签-signApproval）
**/
private String approvalWay;
public WorkflowDisposeTask() {
}
public WorkflowDisposeTask(String taskInstanceId, String disposeUser) {
this.taskInstanceId = taskInstanceId;
this.disposeUser = disposeUser;
}
}步骤二、创建待办任务
提示
详细参数说明，请查看 接口一、创建待办任务
try {
// 待办接受人员列表-学号或工号
List<String> ids = new ArrayList<>();
ds.add("1");
ids.add("1440893392285954675");
// 创建待办用户-学号或工号
String userId = "1";
// 定义待办任务对象
WorkflowApplyTask workflowApplyTask = new WorkflowApplyTask();
workflowApplyTask.setDisposeUsers(ids);
// 设置任务类型为或签任务
workflowApplyTask.setApprovalWay("signApproval");
workflowApplyTask.setApplyUser(userId);
// 设置任务标题
workflowApplyTask.setTaskName("软件1班综合素质测评评分");
// 设置任务类型：格式`T_XXX`，其中`XXX`业务标识
workflowApplyTask.setTaskType("T_RJYB");
// 设置任务类型名称
workflowApplyTask.setTaskTypeName("综合素质测评");
// 设置回调地址及参数信息
String score = String.format("showUrl:%s:/workbenchPage/comprehensiveAssessment/score.html?cpId={}&type={}", workflowApplyTask.getTaskName(), "1546422306528100354", "score");
workflowApplyTask.setTaskForm(score);
// 设置回调信息（暂时用于批量任务参数回调）
workflowApplyTask.setCallbackParam("{\"id\":\"" + userId + "\"}");
JsonResult result = workFlowService.applyTask(workflowApplyTask);
if (!result.isOK()){
log.error("处理待办任务失败，调用流程处理任务失败,返回结果{}",JSONUtil.toJsonStr(result));
throw new BusinessException("创建待办任务失败，调用流程引擎失败");
}
} catch(BusinessException e){
throw e;
} catch (Exception e) {
log.error("创建待办任务失败，发生系统错误", e);
throw e;
}步骤三、处理待办任务
提示
详细参数说明，请查看 接口二、创建待办任务
try {
// 待处理任务编号
String todoId = "1212121212";
// 操作用户
String userId = "1";
WorkflowDisposeTask workflow = new WorkflowDisposeTask(todoId, userId);
// 设置审批状态：1-通过、0-拒绝
workflow.setDisposeResult(1);
JsonResult result = workFlowService.disposeTask(workflow);
if (!result.isOK()) {
log.error("处理待办任务失败，调用流程处理任务失败,返回结果{}", JSONUtil.toJsonStr(result));
throw new BusinessException("处理待办任务失败,请联系管理员");
}
} catch(BusinessException e){
throw e;
} catch (Exception e) {
log.error("处理待办任务失败，发生系统错误", e);
throw e;
}步骤四、取消待办任务
提示
详细参数说明，请查看 接口三、取消待办任务
try {
// 待处理任务编号
List<String> todoIds = new ArrayList<>();
todoIds.add("1440893392285954674");
todoIds.add("1440893392285954675");
WorkflowApplyCanalTask workflowApplyCanalTask = new WorkflowApplyCanalTask();
workflowApplyCanalTask.setInstanceId(todoIds);
JsonResult result = workFlowService.cancelTask(workflowApplyCanalTask);
if (!result.isOK()) {
log.error("取消待办任务失败，调用流程处理任务失败,返回结果{}", JSONUtil.toJsonStr(result));
throw new BusinessException("取消待办任务失败,请联系管理员");
}
} catch(BusinessException e){
throw e;
} catch (Exception e) {
log.error("取消待办任务失败，发生系统错误", e);
throw e;
}