InfoPlus APIs

Glossary

InfoPlus official APIs for Workflow & InfoPlus Apps developers.

General

• App：应用，分三种，后面详述
• Process：流程的一个实例（instance），有唯一的流水号
• Task：一个具体的任务，可被一个或多个用户办理，一个task仅能被办理一次
• Enterprise: 一个企业（或租户），参见 https://en.wikipedia.org/wiki/Multitenancy (opens new window)
• Triple (User, Dept, Post): 企业实体（用户、院系、岗位）构成的一组三元关系
  • Triple作为权限信息，标记用户在企业中的位置（Position）
  • Position表示三元组中，院系和部门的交点，支持通配符表示一行或一列
  • Position的格式为: {dept}:{post}，例如：CS:Students, CS:*, *:Faculty；与UserFilters格式相同。

OAuth2

• 访问地址是：
  • https://form.sjtu.edu.cn/infoplus/oauth2/authorize ：认证地址
  • https://form.sjtu.edu.cn/infoplus/oauth2/token ：Token地址
• 如无特殊说明，InfoPlus的API均使用OAuth2 (opens new window)协议保护
• 调用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针对的流程数据是测试数据
  其访问地址分别是（后面所有API介绍均不含此部分路径）：
  • https://form.sjtu.edu.cn/infoplus/apis/v2/
  • https://form.sjtu.edu.cn/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，请参考：https://datatracker.ietf.org/doc/html/rfc6750 (opens new window)

Data Types

• Object 如无特殊说明，所有调用采用RESTful风格；复杂对象的数据格式使用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 (opens new window)级别的支持。
  • 所有时间类型使用long型，即Unix时间戳 (opens new window)：到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.1(s)格式的Id表示此API可同时支持user和sys两种token，但事实上有两点不同：
  • /me/profile仅支持user类型的token，相应的sys版的接口需要换成 /user/{userId}/profile
  • sys版本的scope需要前缀sys_，本例中应该申请 sys_profile

[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},               // 该用户手机     
    "TenantApps": [ {string} ],     // 租户Favorite的应用id （仅在接口1.3-1.5查询/维护FavoriteApps时返回）
    "FavoriteApps": [ {string} ],   // Favorite的应用id
    "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建议为标签本身

• 可任意指定
• 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},         // 是否可发起
    "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},           // 流程实例流水号
    "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}]    // 祖先流程，近当前流程为“子流程”时有效
}

• 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.已做，3.子流程 
    "thing": {                    // 任务物品
        "id":{uuid},              // 物品Id
        "code":{string},          // 物品条形码
        "name":{string}           // 物品名称
    }
    "actions":[{                     // 可一键办理的步骤
         "id":{integer},             // actionId
         "name":{string},            // 显示名
         "code":{string},            // action code
         "remarkRequired":{boolean}, // 是否备注必填
    }],
    "executors": [{profile}],      // 可办理人列表。仅在返回实例详情且指定了includeExecutors=true时返回
    "reviewers": [{profile}],      // 被抄送人列表  
    "permission": {
        "print":{boolean},         // 该步骤是否支持打印
        "remind":{boolean}         // 该步骤是否允许催办，2020/03新增
    }
}

[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
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
• 获取当前用户在办（用户已经参与过，但流程为结束）、已办（用户已经参与过的已结束的流程）实例
• doing|done|completed支持通过order参数指定排序，可选值：[update|create|action|auto]，默认auto。
  • update：流程实例的最后更新时间
  • create：流程实例的发起时间
  • action：用户办理该流程实例的时间，如办理过多次按最新的计算
  • auto：如果用户是流程实例的发起人，以流程实例的最后更新时间参与排序；否则以用户最后一次办理流程的时间参与排序
  • 可使用 desc|asc 指定排序方向，可选，默认 desc
• 已完成(completed) = doing + done
• 待评级，返回由用户发起的、已经结束当尚未评价的Process
• 上述接口均支持搜索、分页，参数为：

Parameter	Type	Description
app	string	应用的code，只看该应用processes
entry	integer	流水号（20170116版新增）
keyword	string	搜索关键字，搜索范围包括：标题（name）和标签（tags）
fullText	boolean	keyword搜索是否使用全文检索。默认false。需数据库支持。
timestamps	string	发起时间戳范围，格式："1476000000~1477000000"
lastUpdate	string	更新时间戳范围，格式同上
orderTimes	string	排序时间戳范围，格式同上。order确定的排序时间位于所指定的范围内
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 (opens new window)）"
thing	boolean	代收物品还是待办任务；null表示全部
unread	boolean	是否未读，仅支持查询抄送流程，2018/06新增
archive	boolean	是否查询已删除（归档）的流程，默认false。2020/04新增
start	integer	分页起始条序号，0下标
limit	integer	分页返回条数，不给此参数则返回条目数由系统来决定。
order	string	格式 "{field} [desc|asc]"，2018/10新增

• 搜索逻辑（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新增）
includeExecutors	boolean	如果为true，对tasks中的待办步骤额外返回executors结构➁（2023/01新增）

➀ 由于某些步骤可能对用户不可见，ancestors不一定连续，且最大返回16层。
➁ 步骤的可执行人多于50人时仅返回前50条，且顺序不可预测

[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，使用名称时必须唯一。如不给出，使用该流程配置的导出模版。

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	user	查询待收物品去向

[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}	sys_app	u/s	获取app的meta信息（含表单字段、版本）
4.2	POST	/app/{idc}	sys_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	sys	获取指定任务的可办理用户列表
4.7	POST	/task/{id}/candidates	task_edit	sys	修改指定任务的可办理用户
4.8	DEL	/task/{id}	task_edit	sys	撤回指定任务
4.9	PUT	/task/{id}/notification	task_edit	sys	对指定任务的可办理用户发督办通知
4.10	GET	/apps/recommended	sys_app	sys	获取推荐应用列表，Global类型的App需指定domain
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可为*

• idc 表示id或code均可

[4.1] GET "/app/{idc}" @returns Response<App>   

• 参数：

Parameter	Type	Description
version	string	可选，用于查询指定版本的schema信息
includeVersions	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时可给出作为操作人，并需保障该用户有权限。不给出则使用系统用户。此外，对于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 normal important critical

• 根据stepCode可定位到的待办任务必须唯一，即不支持并行结构内的某步骤存在多于一个待办任务
• nextSteps/nextUsers共同指定后续步骤(s)的可办理用户，必须同时给出或同时不给出
• splitPath：对于重复节嵌套情况，按第x节（0下标）中的第y节并行，应该出路径为："x/y"

[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.5] GET "/triple/{type}s" @returns Response<{type}>  

• type可选值包括：[user|dept|post]，其中dept和post返回全集不支持分页和查询
• user类型支持的查询参数列表：

Parameter	Type	Description
start	int	分页参数，开始下标，零下标
limit	int	分页参数，页面大小，不给出时由系统决定
accounts	string	账号列表，逗号分割，明确限制查询的用户范围
keyword	string	查询关键字，逗号或空格分割，同User控件使用方式
positions	string	岗位、院系限定，同User控件的UserFilters参数

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.6)	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":{guid},             // 对象类型，参见后续解释
    "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.1] GET "/stats/apps" @returns Response<App>  

• 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可以为"*"，表示不限应用
• 实例的状态有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可以为"*"，表示不限应用

• 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可以为"*"，表示不限应用
• 参数同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.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}             // 可见性
}

/* 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	查询指定收件码的可收物品

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.sdk.js (opens new window) 来使用此功能

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封装一般来说开发者无需关注
• 目前仅支持JAVA版InfoPlus SDK (opens new window)

Platform APIs

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

Enterprise API

用于集成企业三元组信息，参见: Enterprise API

Notification API

两个作用：

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

File API

• 用于存储文件，生成持久化链接。
• 参见非结构化存储

Task Integration API

• 集成企业内其他系统的任务，统一呈现于任务中心
• 参见Task Integration API

Export API

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