InfoPlusAPI - infoplus/docs GitHub Wiki

Table of Contents

  1. Glossary
    1. General
    2. OAuth2
    3. Apps
  2. InfoPlus APIs
    1. User API
    2. Task API
    3. Task Execution API
    4. Admin API
    5. Triple API
    6. Triple Grant API
    7. Access Grant API
    8. Stats API
    9. Tenant/Code API
    10. Entrust API
    11. Thing API
  3. InfoPlus Push API
  4. InfoPlus Messenger API
  5. InfoPlus Data API
  6. Platform APIs
    1. Enterprise API
    2. Notification API
    3. File API
    4. Task Integration API
    5. Export API

Glossary

InfoPlus official APIs for Workflow & InfoPlus Apps developers.

General

  • 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格式相同。

OAuth2

  • 相对于平台的访问地址是:
    • /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只能为该用户发起流程而不能为其他人发起

Apps

App分为三种类型:

Type Enterprise Project Explain
Global null null 全局应用,不隶属于任何企业或工作流项目,如TaskCenter
Enterprise tenantId null 企业应用,隶属于特定租户,用于和企业那个各种系统集成
Workflow tenantId code 工作流应用,即一个流程,典型应用如一个Messenger
  • 以Workflow/Enterprise类型App调用某些API会把数据限定在该工作流/租户之内
    • 例如:对于发起流程的API而言,WorkflowApp拿到的token只能发起该流程而不能发起其他流程

InfoPlus APIs

Versions

  • 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/

Invocation

  • 所有API使用RESTful Style。如:GET https://taskcenter.net/infoplus/apis/v2/me/profile
  • REST的动词仅使用GET/PUT/UPDATE/DELETE四种
  • 所有Naming采用Camel命名法,access_token除外
  • Url和参数Case sensitive/大小写敏感
  • 所有语法正确的调用,均返回Status 200,但语义上的出错信息,通过Response结构返回(具体参见下节)
  • access_token参数的使用方式默认为Bearer,请参考:http://tools.ietf.org/html/rfc6750

Data Types

  • 如无特殊说明,

    • 所有调用采用 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"
    }
}
  • 一些通用说明:

    • 所有对象id使用GUID, 但一些外部数据结构可能拥有自己主键类型
    • 所有对象的通用属性,除id外还有name、code、uri、tags、description,但均可为空
    • 如无特殊说明,当API返回的某对象为"引用对象"时(比如查询process列表返回的process.app对象),只返回通用属性部分。如有需要请进一步使用其他API获得,暂不提供fields级别的支持。
    • 所有时间类型使用long型,即Unix时间戳:到UTC 1970年1月1日的秒数
  • Response<T> 所有接口 如无特殊说明,所有的接口返回值均为Response范型。
    类型描述:

{
    "errno": {int},        // 错误代码,仅0表示成功
    "ecode": {string},     // 字符串类型的错误代码,增加代码可读性
    "error": {string},     // 人可读的错误信息,内容会随HTTP头的Accept-Language而异
    "total": {int},        // 当分页有效时,此字段给出所有数据的总数(可能比entities.length大);否则为0
    "entities": [ {T} ]    // 真正的返回数据。当返回的数据不是列表时,请访问entities[0]
}

Scopes

  • 所有sys开头的token仅用于System Token,其他的用于User Token
  • 此处不再集中给出所有的scope列表,请参见每个API后面的说明

1.x User API

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"

2.x Task API

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 修改指定流程的数据

简而言之,任务部分的数据结构,分三个层次:

  • App:一个工作流应用。
// 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新增。

3.x Task Execution API

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>
  • 按照物品代码查询物品相关的任务。返回值中会包含三种类型的任务:
    1. 等待当前用户收取该物品的任务:可待收
    2. 等待其他用户收取该物品的任务:可代收
    3. 当前用户曾收取过该物品的任务:可查看

4.x Admin API

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>  
  • 修改该app的meta信息、对该流程上下线等。

  • 参数(所有参数均为可选,默认为null/false):

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},    // 涉及到的流程实例的流水号
}
  • category目前分为:[DEFINITION|INSTANCE|MESSENGER|NOTIFICATION|DATABINDING]

  • URL中的{id}可以为*表示不限定流程实例,或是某个流水号。

  • 其他参数(均为可选):

Parameter Type Description
userId string 用户账号或id
keyword string 关键字,用于查询日志内容
timestamps string 时间戳范围,格式:"1476000000~1477000000"
app string 应用code或id
categories string 逗号分隔的分类列表
levels string 逗号分隔的级别列表
start int 分页参数,返回的第一条下标,按时间戳逆序
limit int 分页参数,每页大小

5.x Triple API

  • 查询、操纵企业内的三元组实体(用户、岗位、院系)
  • 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新增

6.x Triple Grant API

  • 与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
  • Position:表示部门、岗位矩阵上的某些点、行或列,参见Position
// 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 可选,来源

7.x Access Grant API

  • 文档尚待完善
  • 访问引擎的ACL(访问控制列表)
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
  • Access:表示对某种对象的访问权限
// 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 二选一

8.x Stats API

  • 注意:统计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

9.x Tenant API

  • 查询企业内(租户)的设置或实体(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
  • membership的{id}可以为UUID或者provider,比如 wechat_enterprise,大小写不敏感。

  • type可选值包括:membership、tag、setting

  • Tag数据结构:

// 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表示

10.x Entrust API

  • 查询、设置委托
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

11.x Thing API

  • 物品、收件码管理
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
  • 更详细说明,请参考ThingAPI

InfoPlus Push API (Long polling)

  • 用于长链接的方式订阅服务端的事件,比如订阅用户的待办、抄送等的变化。

Sub(FrontEnd)

/* 前端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的回调函数
  • 注:此接口不建议直接使用。通过 infoplus的jssdk 来使用此功能,对断线重连等有更好的支持。

Sub(BackEnd)

  • 尚不支持。

Pub(BackEnd)

  • 后台调用接口发布一个消息,平台会通知所有符合条件的订阅者(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时有效   
}

InfoPlus Messenger API

  • Messenger是InfoPlus平台和第三方系统之间的事件驱动的互操作机制
  • Messenger API为引擎和Messneger之间传输的标准接口
  • 其细节一般由SDK封装一般来说开发者无需关注,请参考InfoPlus SDK访问开源项目和架构文档
  • 如果您使用Python、Perl、NodeJS等我们尚未支持的SDK,请阅读Write your own SDK

InfoPlus Data API

  • 表单数据的查询接口,GraphQL格式,具体参考InfoPlusDataAPI

Platform APIs

除InfoPlus引擎提供的上述API外,作为InfoPlus的平台还需要周边的API符合一些规范。

Enterprise API

用于集成企业三元组信息,参见: https://github.com/infoplus/docs/wiki/EnterpriseAPI

Notification API

两个作用:

  1. 发送Email通知,和SMTP服务器集成
  2. 集成其他渠道的通知 参见: Notification API

File API

Task Integration API

Export API

  • 用于导出Word/Excel/PDF等。
  • 参见Export API

Market API

⚠️ **GitHub.com Fallback** ⚠️