-
Glossary
- General
- OAuth2
- Apps
-
InfoPlus APIs
- User API
- Task API
- Task Execution API
- Admin API
- Triple API
- Triple Grant API
- Access Grant API
- Stats API
- Tenant/Code API
- Entrust API
- Thing API
- InfoPlus Push API
- InfoPlus Messenger API
- InfoPlus Data API
-
Platform APIs
- Enterprise API
- Notification API
- File API
- Task Integration API
- Export API
InfoPlus official APIs for Workflow & InfoPlus Apps developers.
- App:应用,分三种,后面详述
- Process:流程的一个实例(instance),有唯一的流水号
- Task:一个具体的任务,可被一个或多个用户办理,一个task仅能被办理一次
- Enterprise: 一个企业(或租户),参见 https://en.wikipedia.org/wiki/Multitenancy
- Triple (User, Dept, Post): 企业实体(用户、院系、岗位)构成的一组三元关系
- Triple作为权限信息,标记用户在企业中的位置(Position)
- Position表示三元组中,院系和部门的交点,支持通配符表示一行或一列
- Position的格式为: {dept}:{post},例如:CS:Students, CS:*, *:Faculty;与UserFilters格式相同。
- 相对于平台的访问地址是:
- /infoplus/oauth2/authorize :认证地址
- /infoplus/oauth2/token :Token地址
- 如无特殊说明,InfoPlus的API均使用OAuth2协议保护
- 调用API必须拥有一个合法的App身份(appId + secret),可在IDE中查询到
- OAuth2支持4种授权方式(如下),InfoPlus仅支持第1,2,4种
- Authorization Code
- Implicit
- Resource Owner Password Credentials
- Client Credentials
- 第1,2种授权方式获得的Token称为User Token;第4种称为System Token
- 不同的API支持不同类型的Token,用u/s区别
- 用户token在某些API中涉及到权限的情况下会限定影响范围仅对该用户
- 例如:对于发起流程的API而言,User Token只能为该用户发起流程而不能为其他人发起
App分为三种类型:
Type |
Enterprise |
Project |
Explain |
Global |
null |
null |
全局应用,不隶属于任何企业或工作流项目,如TaskCenter |
Enterprise |
tenantId |
null |
企业应用,隶属于特定租户,用于和企业那个各种系统集成 |
Workflow |
tenantId |
code |
工作流应用,即一个流程,典型应用如一个Messenger |
- 以Workflow/Enterprise类型App调用某些API会把数据限定在该工作流/租户之内
- 例如:对于发起流程的API而言,WorkflowApp拿到的token只能发起该流程而不能发起其他流程
- By evolution
InfoPlus当前API版本是v2,但部分v1的API依然支持。如无特殊说明,本文档后面提及的api均为v2版
- By mode
InfoPlus API同时提供两个语法上完全一致的版本:
v2和v2d,区别是:v2针对的流程数据是正式数据;v2d针对的流程数据是beta数据
其访问地址分别是(后面所有API介绍均不含此部分路径):
- /infoplus/apis/v2/
- /infoplus/apis/v2d/
-
如无特殊说明,
- 所有调用采用 RESTful 风格
- 所有传入参数,均采用 "multipart/form-data" 格式或 QueryString 格式
- 所有返回参数,均采用 "application/json" 格式
-
复杂对象的返回值格式使用JSON表示。比如:
{
"id": "a55a00cc-164f-11e5-b54f-deb2e04cda62"
"name": "John Doe",
"uri": "http://example.com/",
"account": "john-doe",
"enterprise":
{
"id":"a55a2408-164f-11e5-b54f-deb2e04cda62",
"name":"Foxhound"
}
}
{
"errno": {int}, // 错误代码,仅0表示成功
"ecode": {string}, // 字符串类型的错误代码,增加代码可读性
"error": {string}, // 人可读的错误信息,内容会随HTTP头的Accept-Language而异
"total": {int}, // 当分页有效时,此字段给出所有数据的总数(可能比entities.length大);否则为0
"entities": [ {T} ] // 真正的返回数据。当返回的数据不是列表时,请访问entities[0]
}
Id |
Method |
EndPoint |
Scope |
Token |
Description |
1.1(s) |
GET |
/me/profile |
profile |
u/s |
获取用户信息 |
1.3(s) |
GET |
/me/preference/{k} |
profile |
u/s |
获取用户偏好 |
1.4(s) |
PUT |
/me/preference/{k}/{v} |
profile_edit |
u/s |
增加用户偏好条目 |
1.5(s) |
DEL |
/me/preference/{k}/{v} |
profile_edit |
u/s |
删除用户偏好条目 |
1.6(6.1s) |
GET |
/me/positions |
triple |
user |
获取用户岗位 |
1.7(7.1s) |
GET |
/me/accesses |
access |
user |
获取用户权限 |
1.8(s) |
GET |
/preference/{k}/{v}/users |
sys_profile |
sys |
按照偏(单值)好获取用户列表 |
1.9(s) |
GET |
/preference/{k}/{vs}/users/count |
sys_profile |
sys |
对某些偏好(多值)的用户计数 |
- 注意:形如1.1(s)格式的Id表示此API可同时支持user和sys两种token,但有两点不同:
- /me/profile仅支持user类型的token,相应的sys版的接口需要换成 /user/{userId}/profile
- 如果 u/s 类型的API,并非 /me/ 开头的,那么可在API参数中使用 userId 参数指定用户,该参数可使用用户的uuid,或者用户account,或者 account@domain(仅当全局应用时需要)
- sys版本的scope需要前缀
sys_
,本例中应该申请 sys_profile
- 对于同时支持user和sys两种token的(
u/s
类型)的API,后续列表中scope列都会省略前缀 sys_
,调用者需根据token授权类型的不同决定是否使用带sys_
前缀的scope
[1.1] GET "/me/profile" @returns Response<Profile>
- sys版为 GET /user/{id}/profile,后面类似接口不再赘述
- 获取用户信息,包括用户所在企业的信息和用户偏好
// TYPE {profile}
{
"id":{guid}, // 无意义的唯一id
"name":{string}, // 实名
"account":{string}, // 租户内的用户id,租户唯一
"email":{string}, // 该用户邮箱
"phone":{string}, // 该用户手机
"favoriteApps": [ {string} ], // Favorite的应用code
"favoriteTasks": [ {integer} ], // Favorite的任务id
"favoriteTags": [ {string} ], // Favorite的标签
"enterprise":
{
"id":{guid},
"name":{string}, // 所属单位名称
"domain":{string}, // 所属单位域名,用于唯一表示改企业
"style":{string},
"logo":{uri}, // 所属单位图标
"banner":{uri}, // 所属单位banner
"copyright":{string} // 所属单位版权信息
}
}
[1.3] GET "/me/preference/{key}" @returns Response<Profile>
[1.4] PUT "/me/preference/{key}/{value}" @returns Response<Profile>
[1.5] DEL "/me/preference/{key}/{value}" @returns Response<Profile>
- 获取、增、删用户偏好
- 内置key必须是如下枚举之一:
Key |
Type |
ElementType |
Description |
FavoriteApps |
集合 |
String |
用户收藏的应用,Element建议为应用代码 |
FavoriteTasks |
集合 |
Integer |
用户置顶的流程,Element建议为流水号 |
FavoriteTags |
集合 |
String |
用户收藏的标签,Element建议为标签本身 |
FavoriteForwarders |
集合 |
JSON |
常用转交人,用于自由流 |
- 可任意指定
- value 即集合中元素,1.4和1.5分别用于在集合中增加、删除一个元素
[1.6(6.1s)] GET "/me/positions" @returns Response<Position>
[1.7(7.1s)] GET "/me/accesses" @returns Response<Access>
请分别参见6.1s和7.1s:GET "/user/{userId}/positions",GET "/user/{userId}/accesses"
Task API 提供工作流、任务相关的查询接口
Id |
Method |
EndPoint |
Scope |
Token |
Description |
2.1 |
GET |
/me/apps |
app |
u/s |
获取用户可办应用 |
2.2 |
GET |
(reserved, @see 4.3) |
|
|
保留 |
2.3 |
GET |
/me/tasks/todo |
task |
u/s |
获取用户待办 |
2.4 |
GET |
/me/processes/doing |
process |
u/s |
获取用户在办 |
2.5 |
GET |
/me/processes/done |
process |
u/s |
获取用户已办 |
2.6 |
GET |
/me/processes/completed |
process |
u/s |
获取用户doing+done |
2.7 |
GET |
/me/processes/{cate} |
process |
u/s |
获取用户“某类”流水(具体参考后面解释) |
2.8 |
GET |
/process/{id} |
process |
u/s |
获取指定流程的详情 |
2.9 |
GET |
/process/{id}/data |
process |
u/s |
获取指定流程的数据 |
2.10 |
GET |
/process/{id}/data/{format} |
process |
u/s |
导出指定流程的数据到Word/PDF |
2.11 |
POST |
/process/{id}/data |
process_edit |
u/s |
修改指定流程的数据 |
简而言之,任务部分的数据结构,分三个层次:
// TYPE {app}
{
"id":{guid}, // 无意义的唯一id
"name":{string}, // 服务事项名称
"uri":{string}, // 启动uri
"code":{string}, // 应用代码,可用于部分api调用,表示该app的发布版
"abbreviation":{string}, // 缩略名
"description":{string}, // 服务摘要
"tags":{string}, // 应用标签,可以有多个,以逗号分隔,第一个作为主分类
"icon":{uri}, // 图标uri
"palette":{string}, // 调色板颜色,形如:#ff0000
"department":{string}, // 负责院系
"contact":{string}, // 联系人及其方式描述
"recommend":{integer}, // 推荐度
"rating":{integer}, // 评价汇总,0到100分
"rated":{integer}, // 评价次数
"visible":{boolean}, // 是否可见
"ready":{boolean}, // 是否可发起
"release":{boolean}, // 是否上线(v2d检查beta标志),仅 API 4.3 有效,仅检查有权限的版本,2020/08/25新增
"system":{string}, // 所属系统。“工作流应用”的system为空。
"currentVersion":{version},// 当前版本的详细配置,仅 API 4.1/4.2 含有此信息
"versions":[{version}] // 所有版本列表,仅 API 4.1 可指定返回此信息
}
- Process:工作流应用的实例。一个App可以被发起多个Process
// TYPE {process}
{
"id":{guid}, // 流程实例的guid
"name":{string}, // 流程实例名称
"uri":{string}, // 查看流程用到的uri
"tags":{string}, // 该流程实例的标签,可以有多个,以逗号分隔
"entry":{string}, // 流程实例流水号
"entryTop":{string}, // 主流程流水号。2020/04新增
"create":{long}, // 流程实例创建时间
"update":{long}, // 流程实例最后操作时间(本用户)
"read":{long}, // 最后一次阅读时间,仅支持抄送,2018/06新增
"ccCreate":{long}, // 首次抄送给该用户的时间,2018/06新增
"ccUpdate":{long}, // 最新抄送给该用户的时间,2018/06新增
"sort":{long}, // 排序值,会根据排序方式而不同,可参考order参数,目前均为时间戳。
"app":{app}, // 所属应用
"owner":{profile}, // 流程实例所有者,用于区分是我的事宜还是别人的事宜
"actualUser":{profile}, // 委托发起的流程的实际发起人
"status":{string}, // 流程状态:doing、suspended、done、killed
"states":[{ // 流程当前停留节点的状态,2019/11新增
"code": {string}, // 步骤节点code和名称
"nameEx": {string}
}],
"version":{long}, // 所属工作流的创建时间戳,2016/03/02新增
"rating":{int}, // 评价星级,1-5
"review":{string}, // 评价内容
"screen":{string}, // 发起人使用的终端:desktop/mobile/ios/android/wechat 之一
"pendingTasks":{string}, // 当前的待办
"priority":{string}, // 优先级:normal、important,可为空默认normal
"tasks":[{task}] // 任务列表,仅当GET /process/{id} 时有效
// TYPE {milestone}
"milestone":{ // 本流程经到达的最后一个里程碑
"name": {string}, // 里程碑描述
"percent": {int}, // 里程碑百分比,0-100
"status": {string}, // 里程碑状态:[todo|doing|done]
"nameIn": {string}, // 里程碑到达时条件的描述
"branch": {string} // 里程碑所属分支,层次关系即branch间的前缀关系
},
"milestones":[{milestone}], // 进度条信息,仅当GET /process/{id} 时有效
"flow":[{milestone}], // 同上,但包括所有分支信息,可作为完整流程图
"activities":[{
"user": {profile}, // 动态相关的用户
"description": {string},// 动态的内容
"level": {string}, // 级别:[VERBOSE|INFO|WARNING|ERROR]
"timestamp": {long}, // 时间戳
"tags": {string} // 动态的类型:[INSTANCE_ADMIN|INSTANCE_KILL|INSTANCE_WITHDRAW]
}],
"ancestors": [{process}], // 祖先流程,近当前流程为“子流程”时有效
"permission": { // 注意:此结构默认不返回,需通过参数指定 `includePermission = true`
"ccUser": {boolean} // 该流程实例是否有可手工抄送的步骤,2023/11新增
}
}
- Task:需要用户办理的任务。不存在并发的Process最多只有一个当前任务;并发后可有多个。
// Type: {task}
{
"id":{guid},
"name":{string}, // 当前任务名,如:"待审核"、"申请单填写"
"uri":{string}, // 展示表单所需的url
"description":{string}, // 摘要
"process":{process}, // 所属流程实例
"sub":{process}, // 对应的子流程,仅对子流程任务有效。2020/04新增
"assignUser":{profile}, // 指派给的用户,可能为空,表示未指定具体用户
"actionUser":{profile}, // 办理用户,仅对doing|done有效
"actualUser":{profile}, // 实际操作的用户,"被委托人",2017/04/01新增
"assignTime":{long}, // 指派时间
"actionTime":{long}, // 办理时间
"actionName":{string}, // 办理时选择的动作名称
"expireTime":{long}, // 承诺办理时间
"renderTime":{long}, // 此任务表单第一次渲染的时间,2018/11/30新增
"remark":{string}, // 办理用户填写的备注信息
"review":{string}, // 办理用户填写的批注信息
"screen":{string}, // 办理用户使用的终端:desktop/mobile/ios/android/wechat 之一
"status":{int}, // 状态:待做(1),已做(2),子流程(4)
"withdrawTo":{int}, // 撤回标记。此字段存在则表示本任务无效(已被撤回)
"thing": { // 任务物品
"id":{uuid}, // 物品Id
"code":{string}, // 物品条形码
"name":{string} // 物品名称
}
"actions":[{ // 可一键办理的步骤
"id":{integer}, // actionId
"name":{string}, // 显示名
"code":{string}, // action code
"remarkRequired":{boolean}, // 是否备注必填
}],
"actioners": [{profile}], // 可办理人列表,仅用于GraphQL查询,2018/09新增
"reviewers": [{profile}], // 被抄送人列表,仅用于GraphQL查询,2018/09新增
"permission": {
"print": {boolean}, // 该步骤是否支持打印
"remind": {boolean}, // 该步骤是否允许催办,2020/03新增
"ccUserFilters": {string} // 对于允许手工抄送的步骤,可抄送的用户身份(格式参考UserFilter文档)。2023/10新增
}
}
[2.1] GET "/me/apps" @returns Response<App>
- 获取当前用户可使用(有权限)的服务(工作流应用)
- 不支持分页
[2.3] GET "/me/tasks/todo" @returns Response<Task>
- 获取当前用户可管理/查看的待办任务
- 支持分页(2018之后)
Parameter |
Type |
Description |
sep |
boolean |
是否别人发起的,为空表示全部 |
thing |
boolean |
是否是物品待收,为空表示全部 |
entrust |
boolean |
是否是委托待办,为空表示false |
appTags |
string |
按应用标签筛选,可逗号多值(逻辑或)(20210815版新增) |
start |
integer |
分页起始条序号,0下标 |
limit |
integer |
分页返回条数,不给此参数则返回条目数由系统来决定。 |
[2.4] GET "/me/processes/doing" @returns Response<Process>
[2.5] GET "/me/processes/done" @returns Response<Process>
[2.6] GET "/me/processes/completed" @returns Response<Process>
[2.7] GET "/me/processes/{cate}" @returns Response<Process>
- 此部分API均可表述为2.7的形式,除2.4-2.6外为了便于描述和说明均归为2.7。cate参数目前支持:
- unrated:该用户未评价的流程实例
- cc:抄送给该用户的流程实例(2018/06新增)
- entrusted:委过给该用户的流程实例(2017/05新增)
- admin|guest|operator:参考 API 4.4
- 获取当前用户在办(用户已经参与过,但流程未结束)、已办(用户已经参与过的已结束的流程)实例
- 排序可通过order参数指定,可选值:[update|create|action|auto],默认update(最后修改时间)
- action仅支持 doing|done|completed,含义是:该用户参与过的步骤的办理时间,如参与过多步按最新的计算。2019/01新增
- 可使用 desc|asc 指定排序方向,可选,默认 desc
- 已完成(completed) = doing + done
- 待评级,返回由用户发起的、已经结束当尚未评价的Process
- 上述接口均支持搜索、分页,参数为:
Parameter |
Type |
Description |
app |
string |
应用的code,只查询该应用的 processes |
appTags |
string |
按应用标签筛选,可逗号多值(逻辑或)(20210815版新增) |
entry |
integer |
流水号(20170116版新增) |
owner |
string |
发起人用户标识(20210716版新增) |
keyword |
string |
搜索关键字,搜索范围包括:标题(name)和标签(tags) |
fullText |
boolean |
keyword搜索是否使用全文检索。默认false。需数据库支持。 |
timestamps |
string |
发起时间戳范围,格式:"1476000000~1477000000" |
lastUpdate |
string |
更新时间戳范围,格式同上 |
milestones |
string |
里程碑范围,格式:"60~100" |
ratings |
string |
评价范围,格式:"-1~5",负数表示未评价(201912新增) |
statuses |
string |
流程运行状态范围,格式:"draft,doing,suspended,done,killed" |
states |
string |
流程完成状态范围,即逗号分割的自动机终止态(201901新增,仅支持2.7) |
sep |
boolean |
是否是"别人的事情(somebody else's problem)" |
thing |
boolean |
代收物品还是待办任务;null表示全部 |
unread |
boolean |
是否未读,仅支持查询抄送流程,2018/06新增 |
archive |
boolean |
是否查询已删除(归档)的流程,默认false。2020/04新增 |
start |
integer |
分页起始条序号,0下标 |
limit |
integer |
分页返回条数,不给此参数则返回条目数由系统来决定。 |
order |
string |
格式 "{field} [desc|asc]",2018/10新增 |
includeAncestors |
boolean |
如果为true且为子流程,额外返回ancestors结构*(2020/04新增) |
includePermission |
boolean |
如果为true,额外返回 permission 结构(2023/11新增) |
includeOwnerDepts |
boolean |
如果为true,额外返回创建人有权限的部门列表(2025/01新增) |
- 搜索逻辑(keyword参数)详述
- keyword的分词逻辑是"空格或逗号分隔"
- 分词后多个查询条件的关系是"或"
- 查询范围包括标题、标签、所有者的账号和姓名、流水号
- 将来搜索优化之后可能会有所不同
[2.8] GET "/process/{id}" @returns Response<Process>
- 获取指定Process的详细信息,包括其Task列表
Parameter |
Type |
Description |
visibility |
string |
如果为"all",不隐藏步骤。要起应用token或者管理员token |
entryRef |
int |
用户参与过的流水号,用于子流程查询的权限判断(2020/04新增) |
includeAncestors |
boolean |
如果为true且为子流程,额外返回ancestors结构*(2020/04新增) |
includeCcUserFilters |
boolean |
如果为true且为子流程,额外返回手工抄送权限信息(2023/10新增) |
- 注:由于某些步骤可能对用户不可见,ancestors不一定连续,且最大返回16层。
[2.10] GET "/process/{id}/data/{format}" @returns bytes[]
- 导出指定流水号的数据到Word/PDF
- 正确时返回文件流,错误时将设置非200的HTTP状态码,并返回json格式的Response
- 参数:
Parameter |
Type |
Description |
format |
string |
docx、pdf、png |
docTemplate |
string |
可选。流程中配置的Word模版的名称或者Id,使用名称时必须唯一。如不给出,使用该流程配置的导出模版。 |
[2.11] POST "/process/{id}/data" @returns Response<Map<String, Object>>
- 修改表单数据。
- 除非指定
skipStatusCheck=true
,否则仅允许修改未结束流程的数据。
- 参数:
Parameter |
Type |
Description |
data |
string |
JSON格式的表单数据,Map<字段, 数据>,可仅给出要修改的字段 |
remark |
string |
可选。备注信息,会记录在操作日志(Activity)中,可通过API 4.13 查询 |
skipStatusCheck |
boolean |
可选,默认false。设置为true可强制修改已结束流程的数据。2022/10新增。 |
Id |
Method |
EndPoint |
Scope |
Token |
Description |
3.1u(4.8s) |
POST |
/task/{id} |
submit |
u/s |
办理一个任务 |
3.2 |
PUT |
/process |
start |
u/s |
发起一个新流程 |
3.3u(4.5s) |
POST |
/process/{id} |
process_edit |
u/s |
评价(等)一个流程 |
3.4 |
POST |
/app/{code} |
app_edit |
u/s |
推荐一个应用 |
3.5 |
GET |
/thing/{code}/tasks |
task |
u/s |
查询待收物品去向 |
[3.1] POST "/task/{id}" @returns Response<>
- 办理一个任务,其中任务{id}为GUID,需从用户待办列表或发起成功后的Task结构中获得
- 注意:API 4.5s也包含“办理一个任务”的功能,简述区别是API 4.5s:
a)根据流水号和步骤代码定位待办任务,无法支持并发结构内的任务
b)需对"步骤"勾选"允许系统用户办理",而API 3.1则不需要。因此,前者显示的是系统用户(在租户内配置,唯一)自动办理
- 参数:
Parameter |
Type |
Description |
userId* |
string |
可选。该任务的办理人,仅当access_token不含用户信息时可用,否则以授权用户为准 |
actionId |
integer |
动作id,对于"动作"勾选过"支持一键办理",可在Task数据结构的actions获得 |
actionCode |
string |
动作code,作用同上,id和code两者给一个即可,id优先。在工作流编辑器中可查看action的id和code,但如果aciton被删除重画,id会发生变化 |
remark |
string |
办理任务时,填写的备注信息,是否必需在工作流中配置 |
thing |
string |
物品码,收取物品时必须 |
pickup |
string |
取件码,取件步骤给出,会验证此码并标记为已使用 |
- 注(*):userId为空或者和pickup.user不一致时,逻辑是:
- 如果userId为空,且系统用户可办,则会使用系统用户
- 如果pickup.user存在,则作为userId;参数的userId或者系统用户会被记录为委托人
[3.2] PUT "/process" @returns Response<String>
- 发起一个新流程实例
- 返回值Response.entities数组中:
a)0为流水号
b)1为步骤号
c)2为第一步的URL
d)3为完整的第一步Task数据结构的JSON
- API发起的第一步自动进入用户待办,而界面上发起的第一步用户不保存的话视为草稿状态关闭后作废
- 参数(标记s的仅限于sys类型token):
Parameter |
Type |
Description |
userId(s) |
string |
可选。所有者,仅当access_token不含用户信息时可用,否则以token颁发给的用户为准 |
assignTo(s) |
string |
可选。第一步可执行人,仅当access_token不含用户信息时可用,否则以token颁发给的用户为准 |
secureURIExpire |
long |
可选。仅当assignTo为快捷用户时,表示返回URL的有效期(秒)。比如希望一天内有效,应给86400(24*60*60) |
code |
string |
可选。工作流code,仅当使用非Workflow类型app时才需要给出,参见Apps
|
entrance |
string |
可选。工作流入口自动节点的code(入口为人工节点请不要给此参数),仅多入口流程需要。 |
businessId |
string |
可选。额外信息的业务对象id,用于和业务系统的关联,可选 |
data |
string |
可选。初始化数据,为JSON序列化的hashmap,例如:{ "fieldUser": "marstone", "fieldAge": 18 } ,具体可参考FormData
|
修改流程状态、数据
[3.3] POST "/process/{id}" @returns Response<>
- 此接口与API 4.5格式相同,用于“改变”一个流程实例,详情参见API 4.5
- 用于评价、终止一个流程等,支持4.5除办理外的所有动作
[3.4] POST "/app/{code}" @returns Response<>
[3.5] GET "/thing/{code}/tasks" @returns Response<Task>
- 按照物品代码查询物品相关的任务。返回值中会包含三种类型的任务:
- 等待当前用户收取该物品的任务:可待收
- 等待其他用户收取该物品的任务:可代收
- 当前用户曾收取过该物品的任务:可查看
Id |
Method |
EndPoint |
Scope |
Token |
Description |
4.1 |
GET |
/app/{idc} |
app |
u/s |
获取app的meta信息(含表单字段、版本) |
4.2 |
POST |
/app/{idc} |
app_edit |
u/s |
修改app的meta信息、上下线 |
4.3 |
GET |
/me/apps/{access} |
app |
u/s |
按权限获取当前用户的应用列表 |
4.4 |
GET |
/me/processes/{access} |
process |
u/s |
按权限获取当前用户的实例列表 |
4.5 |
POST |
/process/{id} |
sys_process_edit |
sys |
可对实例执行终止挂起等多种动作 |
4.6 |
GET |
/task/{id}/candidates |
task |
u/s |
获取指定任务的可办理用户列表 |
4.7 |
POST |
/task/{id}/candidates |
task_edit |
u/s |
修改指定任务的可办理用户 |
4.8 |
DEL |
/task/{id} |
task_edit |
u/s |
撤回指定任务,应用token暂不支持 |
4.9 |
PUT |
/task/{id}/notification |
sys_task_edit |
sys |
对指定任务的可办理用户发督办通知 |
4.10 |
GET |
/apps/recommended |
sys_app |
sys |
获取推荐应用列表(请参考后面**注释); |
4.11 |
GET |
/app/{idc}/ratings |
sys_app |
sys |
获取应用下所有带评价的实例 |
4.12 |
GET |
/process/{id}/{cate} |
process |
u/s |
获取指定实例的管理员列表,cate:[admin |
4.13 |
GET |
/process/{id}/activities |
process |
u/s |
获取此实例日志,id可为*或__ALL__,视为不限流水号 |
- idc 表示id或code均可
- ** 对于 API 4.3:access 可选值:
admin
(管理) guest
(查询) operator
(运维) devel
(开发) completed
(参与)
- ** 对于 API 4.10: 会返回所有可见的app列表,需调用端;Global类型的App需指定domain参数。
[4.1] GET "/app/{idc}" @returns Response<App>
Parameter |
Type |
Description |
version |
string |
可选,用于查询指定版本的schema信息 |
includeForms |
boolean |
可选,默认false。是否返回表单信息 |
includeVersions |
boolean |
可选,默认false。是否返回该应用的版本列表信息 |
includeDefinition |
boolean |
可选,默认false。是否返回原始流程图定义 |
- Version对象:表示一个工作流版本的所有配置,定义如下:
// TYPE {version}
{
"id":{string},
"name":{string},
"current":{boolean}, // 是否当前版本
"schema":{schema}, // 数据表、字段定义
"graph":{graph}, // 流程图节点、边的定义
"events":[{event}] // 回调事件
}
[4.2] POST "/app/{idc}" @returns Response<App>
Parameter |
Type |
Description |
online |
string |
要上线的流程版本的id |
offline |
string |
要下线的流程版本的id |
beta |
boolean |
指定是正式还是测试发布,对于调试版api强制为true |
recommendation |
integer |
修改应用的推荐度 |
ready |
boolean |
修改应用的ready属性 |
visible |
boolean |
修改应用的visible属性 |
department |
string |
修改应用的主管部门属性 |
contact |
string |
修改应用的联系方式属性 |
[4.3] GET "/me/apps/{access}" @returns Response<App>
[4.4] GET "/me/processes/{access}" @returns Response<Process>
- 其中access可以为:admin或guest,分别表示"可管理的"和"可查看的"。具体参数参考 API-2.7
[4.5] POST "/process/{id}" @returns Response<>
- 修改一个流程实例,通过action参数指定具体动作:
Action名 |
含义 |
rate |
默认值,评价此流程实例 |
submit |
办理此流程实例下的某待办任务,具体参见其他参数说明 |
kill |
终止此流程实例 |
suspend |
挂起,挂起后此流程实例所有的待办任务暂时从用户待办中移除 |
resume |
挂起恢复 |
compensate |
补偿,作用是触发Messenger API的Compensate事件 |
archive |
归档,使流程对用户不可见。仅发起人可对无其他人参与过的流程归档。 |
tag |
保留 |
mark |
修改优先级 |
read |
标记抄送的流程实例为“已读”(2018/06新增) |
unread |
标记抄送的流程实例为“为读”(2018/06新增) |
dismiss |
删除该流水的抄送,可指定用户(2020/04新增) |
Parameter |
Type |
Description |
action |
string |
可选,具体含义参见上面表格 |
userId |
string |
系统token时可给出作为操作人(submit动作不支持),并需保障该用户有权限。不给出则使用系统用户。此外,对于dismiss动作,userId为要删除的用户的抄送;userId=* 可删除此流水所有用户的抄送。 |
rating |
int |
评价星等,0-5 |
remark |
string |
评价内容、挂起理由、办理备注 |
stepCode |
string |
仅用于submit动作。指定要办理的任务所在步骤代码(*) |
actionCode |
string |
仅用于submit动作。指定要办理的任务的动作代码 |
nextSteps |
string |
仅用于submit动作。可选。逗号分割的后续步骤代码列表(*) |
nextUsers |
string |
仅用于submit动作。可选。逗号分割的后续步骤执行人id |
splitPath |
string |
仅用于submit动作。可选。动态并行的路径序号(*) |
thing |
string |
仅用于submit动作。可选。待收物品编码 |
priority |
string |
仅用于mark动作,支持 low |
- 根据stepCode可定位到的待办任务必须唯一,即不支持并行结构内的某步骤存在多于一个待办任务
- nextSteps/nextUsers共同指定后续步骤(s)的可办理用户,必须同时给出或同时不给出
- splitPath:对于重复节嵌套情况,按第x节(0下标)中的第y节并行,应该出路径为:"x/y"
/* 修改指定任务的可办理用户 */
[4.7] POST "/task/{id}/candidates" @returns Response<>
Parameter |
Type |
Description |
userIds |
string |
逗号分隔的用户id列表 |
[4.11] GET "/app/{idc}/ratings" @returns Response<Process>
[4.13] GET "/process/{id}/activities" @returns Response<Activity>
- Activity对象:表示一次操作、事件等活动的日志记录,定义如下:
// TYPE {activity}
{
"id":{string},
"description":{string}, // 日志内容
"level":{string}, // 日志级别,四级[VERBOSE|INFO|WARNING|ERROR]
"timestamp":{integer}, // 日志产生的时间戳
"category":{string}, // 日志大类,参考后面说明。
"tags":{string}, // 日志小类
"user":{string}, // 操作人或涉及到的用户
"entryId":{integer}, // 涉及到的流程实例的流水号
}
Parameter |
Type |
Description |
userId |
string |
用户账号或id |
keyword |
string |
关键字,用于查询日志内容 |
timestamps |
string |
时间戳范围,格式:"1476000000~1477000000" |
app |
string |
应用code或id |
categories |
string |
逗号分隔的分类列表 |
levels |
string |
逗号分隔的级别列表 |
start |
int |
分页参数,返回的第一条下标,按时间戳逆序 |
limit |
int |
分页参数,每页大小 |
- 查询、操纵企业内的三元组实体(用户、岗位、院系)
- 2017年3月29日修改1:将 enterprise/{type} 修改为 triple/{type},并保持一段时期兼容
- 2017年3月29日修改2:移除原5.1/5.2,重新编排序号
Id |
Method |
EndPoint |
Scope |
Token |
Description |
5.1s |
GET |
/triple/{type}/{id} |
sys_triple |
sys |
查询(用户/岗位/院系)详情 |
5.2s |
PUT |
/triple/{type} |
sys_triple_edit |
sys |
新增(用户/岗位/院系) |
5.3s |
POST |
/triple/{type}/{id} |
sys_triple_edit |
sys |
修改(用户/岗位/院系) |
5.4s |
DEL |
/triple/{type}/{id} |
sys_triple_edit |
sys |
删除(用户/岗位/院系) |
5.5s |
GET |
/triple/{type}s |
sys_triple |
sys |
查询列表(用户/岗位/院系) |
[5.1] GET "/triple/{type}/{idc}" @returns Response<{type}>
- type可选值包括:[user|dept|post]
- 返回的post格式中会包含一个apps列表,即使用到该岗位的所有应用。
- 可增加 verbose=true 参数来返回每个应用下哪些步骤节点用到该岗位。
- 注意目前idc参数,只能使用code,对于全局应用,需要通过 code@domain,或者额外的domain参数来指定租户
[5.2] PUT "/triple/{type}" @returns Response<{type}>
- type可选值包括:[user|dept|post]
Parameter |
Type |
Description |
code |
string |
实体代码 |
name |
string |
实体名称 |
description |
string |
实体描述信息 |
source |
string |
实体来源,默认PUSH |
tags |
string |
(仅dept、post)标签,一般用于分类 |
meta |
string |
(仅dept、post)JSON的key/value的自定义信息 |
email |
string |
(仅user)邮件地址 |
phone |
string |
(仅user)手机号码 |
title |
string |
(仅user)称谓,如校长、院士等 |
express |
string |
(仅user)是否外部非sso用户 |
parent |
string |
(仅dept)父组织机构 |
independent |
string |
(仅dept)是否独立部门 |
formal |
string |
(仅post)是否身份岗 |
[5.3] POST "/triple/{type}/{idc}" @returns Response<{type}>
- 对于 type=post或dept 时支持的可修改参数有(20170626版起):
Parameter |
Type |
Description |
description |
string |
修改描述信息 |
tags |
string |
打标签,一般用于分类 |
meta |
string |
JSON的key/value的meta信息,用于存储其他客户端自行解释的信息 |
[5.4] DELETE "/triple/{type}/{idc}" @returns Response<{type}>
- 删除一个三元组实体,type参考5.1节介绍
- 可选参数source:如果要删除的实体的source不是PUSH,则需指定要删除的实体的source,用于验证客户端的合法性防止误删除其他来源的三元组信息。参数source支持使用*或者逗号分割的多个,含义是不限来源或者限制多个来源。
[5.5] GET "/triple/{type}s" @returns Response<{type}>
- type可选值包括:[user|dept|post],其中dept和post返回全集不支持分页和查询
- user类型支持的查询参数列表:
Parameter |
Type |
Description |
start |
int |
分页参数,开始下标,零下标 |
limit |
int |
分页参数,页面大小,不给出时由系统决定 |
keyword |
string |
查询关键字,逗号或空格分割,同User控件使用方式 |
positions |
string |
岗位、院系限定,同User控件的UserFilters参数 |
accounts |
string |
逗号分隔的账号列表,2021/06新增 |
- 与Triple API的区别是:Triple API是三元组实体的接口,本节是三元组关系的接口。
- 获取用户Position信息;指定Position,并对其下的用户进行增删改
Id |
Method |
EndPoint |
Scope |
Token |
Description |
6.1(1.6u) |
GET |
/user/{id}/positions |
sys_triple |
sys |
|
6.2s |
GET |
/position/{position}/users |
sys_triple |
sys |
|
6.3s |
PUT |
/position/{position}/users |
sys_triple_edit |
sys |
|
6.4s |
DEL |
/position/{position}/users |
sys_triple_edit |
sys |
|
// TYPE {position}
{
// TYPE {dept}
"dept":{ // 部门(dept)对象
"code":{string}, // 部门代码,可能为通配符(*)
"name":{string}, // 部门名称
"parent":{string}, // 父部门代码,可以为空
"independent":{boolean}, // 是否独立部门,详见
"tags":{string} // 标签
},
// TYPE {post}
"post":{ // 岗位(post)对象
"code":{string}, // 岗位代码,可能为通配符(*)
"name":{string}, // 岗位名称
"tags":{string}, // 岗位分类,尚未支持
"formal":{boolean}, // 是否是身份岗
"tags":{string} // 标签
}
}
[6.3] PUT "/position/{dept}:{post}/users" @returns Response<Void>
Parameter |
Type |
Description |
code |
string |
用户账号或用户Id |
number |
string |
可选,学/工号 |
source |
string |
可选,来源 |
Id |
Method |
EndPoint |
Scope |
Token |
Description |
7.1(1.7u) |
GET |
/user/{id}/accesses |
sys_access |
sys |
|
7.2 |
GET |
/access/{scope}/{object}/users |
sys_access |
user |
|
7.3 |
PUT |
/access/{scope}/{object}/users |
access_edit |
user |
|
7.4 |
DEL |
/access/{scope}/{object}/users |
access_edit |
user |
|
// TYPE {access}
{
"scope":{enum}, // 对象类型,参见后续解释
"permission":{string}, // 权限字,可选:[RWX]
"object":{string}, // 权限对象,具体含义因scope而异
"position": {position} // 仅当scope为position时,object的详情
}
- scope: 可选值: [position|engine|enterprise|workflow|instance|code]
- 注:API 7.2/7.3/7.4 目前仅支持position
- object: 因scope而异,当scope为position时,object为Position格式。
[7.2] GET "/access/{scope}/{object}/users" @returns Response<User+Position>
Parameter |
Type |
Description |
includePositions |
boolean |
可选,是否也返回该权限对象的管理岗,false(默认)只返回管理员 |
[7.3] PUT "/access/{scope}/{object}/users" @returns Response<Void>
Parameter |
Type |
Description |
code |
string |
授权到的用户账号或用户Id |
position |
string |
授权到的部门、岗位,即 Position
|
permission |
string |
R(读)、W(写)、X(特殊),具体解释因scope而异 |
- code 和 position 二选一,至少也只能给出一种
- API-7.4 的参数也是 code 或 position 二选一
- 注意:统计API部分,所有的API结果均有2分钟的缓存,并非反应实时状态
- 注意:统计API部分默认关闭,仅保留结构,数据不保障实时/准确。可按租户显示开启兼容原有模式(2020/05/03版本新增)
Id |
Method |
EndPoint |
Scope |
Token |
Description |
8.1 |
GET |
/stats/apps |
stats |
u/s |
按应用、分类的统计 |
8.2 |
GET |
/stats/app/{id}/processes/status |
stats |
u/s |
按时间区间的实例状态统计 |
8.3 |
GET |
/stats/app/{id}/processes/recent |
stats |
u/s |
按时间轴的实例行为统计 |
8.4 |
GET |
/stats/app/{id}/tasks/todo |
stats |
u/s |
按任务的等待时间统计 |
8.5 |
GET |
/stats/user/{id}/tasks/todo |
stats |
u/s |
按用户统计待办任务数量 |
[8.1] GET "/stats/apps" @returns Response<App>
Parameter |
Type |
Description |
start |
long |
统计范围:流程发起时间最小值的Unix时间戳 |
finish |
long |
统计范围:流程发起时间最大值的Unix时间戳 |
- App主要字段: { processCount, creationDate, release, tags }
- 前台可呈现的统计结果建议:
a) 按tag分类的应用(即流程)数饼图
b) 按tag分类的实例数饼图
c) 本月(周)同比的新增应用数变化指标或曲线
d) 按照release区分是已发布的还是未上线(或已下线的)
/* 按时间区间的实例状态统计 */
[8.2] GET "/stats/app/{id}/processes/status" @returns Response<Status, Integer>
Parameter |
Type |
Description |
start |
long |
时间区间:开始时间Unix时间戳 |
finish |
long |
时间区间:结束时间Unix时间戳 |
- app的id可以为"*"(或__ALL__),表示不限应用
- 实例的状态有4种,进行/挂起/终止/结束
- 在给出的时间范围(start, finish)内对所有“发起时间”在这个范围内的实例
- 返回示例:
{
"running":10,
"suspend":1,
"killed":2,
"completed":15
}
/* 按时间轴的实例行为统计 */
[8.3] GET "/stats/app/{id}/processes/recent" @returns Response<Timestamp, RecentCounters>
Parameter |
Type |
Description |
cycle |
string |
统计周期,[hour |
-
app的id可以为"*"(或__ALL__),表示不限应用
-
cycle取不同值时默认对应的周期数是:hour/24, day/7, week/52, month/3, year/5
-
RecentCounters定义:
{
"started":{integer}, // 该时间段内发起的实例数
"completed":{integer}, // 办理完成的
"killed":{integer} // 终止的
}
/* 按任务的等待时间统计 */
[8.4] GET "/stats/app/{id}/tasks/todo" @returns Response<Timestamp, Integer>
- app的id可以为"*"(或__ALL__),表示不限应用
- 参数同8.3, cycle
/* 按任务的等待时间统计 */
[8.5] GET "/stats/user/{id}/tasks/todo" @returns Response<String, Integer>
- user的id仅支持"*"(或__ALL__,用来避免某些WAF),表示统计所有用户
- 参数同8.3, cycle
- 查询企业内(租户)的设置或实体(membership|tag|setting)
- 包括代码表(Code Table)中,代码表项及其属性的CRUD操作。
Id |
Method |
EndPoint |
Scope |
Token |
Description |
9.1s |
GET |
/enterprise/{type}/{id} |
sys_enterprise |
sys |
查询(membership)详情 |
9.3s |
POST |
/enterprise/{type}/{id} |
sys_enterprise_edit |
sys |
触发缓存同步,2021/06新增 |
9.5s |
GET |
/enterprise/{type}s |
sys_enterprise |
sys |
查询列表(tag) |
9.6s |
CRUD |
/code/{cid}/item/{iid} |
sys_code |
sys |
code items |
// TYPE {tag}
{
"id":{guid}, // 无意义的唯一id
"name":{string}, // Tag名称,租户内唯一
"description":{string}, // 描述
"index":{int}, // 排序号
"palette":{string}, // 调色板,格式 #rrbbgg
"visible":{boolean} // 可见性
}
/* 触发缓存同步,2021/06新增 */
[9.3s] POST "/enterprise/{type}/{id}" @returns Response<>
Parameter |
Type |
Description |
type |
string |
仅支持 cache
|
id |
string |
TRIPLE_REMOTE :外部三元组数据到infoplus数据库;TRIPLE_MEMORY :内部数据库到缓存的同步 |
timestmap |
long |
可选。用于调整上cache次同步成功的增量时间戳。0表示重制,触发全量同步。负数表示相对向前调整的秒数 |
/* CodeAPI,代码表项及其属性做CURD(增删改查)操作 */
[9.6] CRUD "/code/{tableCode}/item/{itemCode}" @returns Response<Code>
- CRUD,是PUT(增)/GET(查)/POST(改)/DELETE(删)四种操作的简写,后同
- PUT时,无需itemCode及其前面斜杠部分
- GET时,itemCode可以为"*",表示全部
// TYPE {code}
{
"id":{guid}, // 无意义的唯一id
"name":{string}, // 代码表项名称,租户内唯一
"code":{string}, // 代码表项代码(itemCode),表内唯一
"parentCode":{string}, // 父表项代码,不要求在同一个表内
"description":{string}, // 描述
"index":{int}, // 排序号
"attributes":{map}, // 属性集,Map<String, String>类型
}
Parameter |
Type |
Description |
code |
string |
代码,仅PUT时需要,其他API需放在URL的itemCode位置 |
name |
string |
代码表项名称 |
parent |
string |
父代码 |
description |
string |
描述 |
index |
string |
排序号 |
attributes |
string |
属性map的JSON表示 |
Id |
Method |
EndPoint |
Scope |
Token |
Description |
10.1(s) |
GET |
/user/{id}/{relationship} |
entrust |
u/s |
查询用户的委托人、被委托人列表 |
10.2(s) |
PUT |
/user/{id}/{relationship}/{other} |
entrust_edit |
u/s |
增加委托 |
10.3(s) |
DEL |
/user/{id}/{relationship}/{other} |
entrust_edit |
u/s |
删除委托 |
- {relationship}格式:[entrusters|entrustees],分别表示委托人、被委托人。
/* 增加一个委托关系 */
[10.2] PUT "/user/{id}/{relationship}/{other}" @returns Response<Entrust>
Parameter |
Type |
Description |
app |
string |
委托的应用。委托仅支持办理,不支持发起。 |
from |
long |
时间区间:委托生效的Unix时间戳。注:20190107版之前参数名是start |
to |
long |
时间区间:委托失效的Unix时间戳。注:20190107版之前参数名是finish |
Id |
Method |
EndPoint |
Scope |
Token |
Description |
11.1s |
PUT |
/thing/{code}/pickup |
sys_thing_edit |
sys |
创建一个取件码 |
11.2s |
GET |
/thing/{code} |
sys_thing |
sys |
查询物品详情 |
11.3s |
GET |
/pickup/{pickup}/things |
sys_thing |
sys |
查询指定收件码的可收物品 |
11.4s |
GET |
/pickup/{pickup} |
sys_thing |
sys |
查询取件码信息 |
11.5s |
POST |
/pickup/{pickup} |
sys_thing_edit |
sys |
修改取件码信息 |
11.6s |
GET |
/me/pickups |
thing |
u/s |
查询当前用户(或指定用户)有效的取件码,2020/10/20 |
InfoPlus Push API (Long polling)
- 用于长链接的方式订阅服务端的事件,比如订阅用户的待办、抄送等的变化。
/* 前端js通过长连接方式订阅 */
GET "https://{平台域名}/infoplus/message/sub"
Parameter |
Type |
Description |
uid |
string |
用户id,可以是GUID或 TenantUserId@Domain |
tid |
string |
事件类型,多个使用逗号分隔。目前支持:"task"(待办)、"cc"(抄送,201810) |
since |
long |
时间戳,精确到毫秒,仅sub该时间之后的事件 |
callback |
string |
用于JSONP的回调函数 |
- 后台调用接口发布一个消息,平台会通知所有符合条件的订阅者(sub)
- 所需scope为:sys_message_edit
/* 发布一个消息 */
[0.2] POST "/message" @returns MessageResult
Parameter |
Type |
Description |
uid |
string |
用户id,可以是GUID或 TenantUserId@Domain |
tid |
string |
消息类型。目前支持:"task"(待办)、"cc"(抄送,201810) |
eid |
string |
事件id,具体视消息类型而定。 |
// TYPE {MessageResult}
{
"error":{string}, // 错误信息
"time":{long}, // 时间戳。注意是单位为"毫秒数"的Unix时间戳
"message":{ // Message数据结构,仅当pub时有效
"uid":{string}, // 用户的GUID
"type":{string}, // 消息类型
"eid":{string}, // 事件id(如有)
"time":{long}, // 该消息的产生时间戳,单位是毫秒
"payload":{string} // 尚不支持
},
"messages":[{Message}], // Message数据结构的数组,仅当sub时有效
}
-
Messenger是InfoPlus平台和第三方系统之间的事件驱动的互操作机制
- Messenger API为引擎和Messneger之间传输的标准接口
- 其细节一般由SDK封装一般来说开发者无需关注,请参考InfoPlus SDK访问开源项目和架构文档
- 如果您使用Python、Perl、NodeJS等我们尚未支持的SDK,请阅读Write your own SDK
除InfoPlus引擎提供的上述API外,作为InfoPlus的平台还需要周边的API符合一些规范。
用于集成企业三元组信息,参见: https://github.com/infoplus/docs/wiki/EnterpriseAPI
两个作用:
- 发送Email通知,和SMTP服务器集成
- 集成其他渠道的通知
参见: Notification API