产品介绍

服务列表

产品文档

关于我们

一、总体介绍
二、功能介绍
三、实践用例
- 3-1 用例一：简单的审批流
- 3-2 用例二：并行的审批流
四、附录

[toc]

文档修订记录：

序号	修订内容	修订时间
1	发布文档。文档版本1.0	2022.4.1
2	新增流程模型编辑基本概念、流程规则内容，流程实例生命周期管理、流转通知、意外重启，接口返回错误码等内容。文档版本1.1	2022.5.30
3	新增补全功能内容，包括基于租户管理流程模型、用户体系管理、配置节点负责人、会签、或签、表单读写权限、获取用户待办等.文档版本1.2	2022.8.26
4	更新端口号映射错误和部分请求路径错误，补充了部分返回结果示例并新增结果错误示例说明及相关注意事项。文档版本1.3	2023.11.10
5	修复了目录跳转的问题，补充了相关接口的注释说明和使用方法等。文档版本1.4	2023.12.7
6	补充了用户、用户组及角色间的关系说明；完善了用户待办获取规范功能，可通过流程+角色获取待办，新增查询结果字段node_name(用于标识流程所属的当前节点名称)，以上功能的更新基于datahub4.1.9.2。文档版本1.5	2024.3.28

一、总体介绍

作为一款纯Web应用的流程引擎产品，本产品提供完备的、安全的、单Post请求规范的WebAPI开发接口。与其他流程引擎产品不同，本产品除了完整的流程引擎能力之外，还提供了非常强大的数据能力，包括数据建模、数据校验、数据持久化存储、数据查询等。作为具备诸多能力的产品，交互方式却非常简单，类似于常见数据库的交互方式，只需要开发者了解数据库的基本操作，便能很快上手。除此之外，本产品可以对接多个第三方应用，并且整体非常轻便，通过简单几步便可安装在私有化环境中。

简单易用
第三方应用通过符合单Post请求规范的WebAPI接口与流程引擎进行交互，交互方式简单易用，接口语法与数据库SQL语法相似，只需要应用开发者具备数据库基本知识便能很快上手，可以理解为流程引擎和第三方应用通过一张虚拟的“数据库表”进行交互，表中有部分字段流程引擎负责维护、更新，而另外部分字段由第三方应用维护、更新，流程引擎和第三方应用都可以读取这张”数据库表“的所有字段数据，从而达到第三方应用与流程引擎交互的效果。通过这种交互方式，第三方应用可以用非常简单的方式接入流程引擎，只需要像操作数据库表一样，就可以完成获取流程状态和当前流转情况、驱动流程流转等操作。
强大的数据能力
通过流程表单建模，以一种类似定义数据库表的方式定义表单各个数据字段类型、取值，第三方应用在与流程引擎进行交互时，流程引擎会对数据进行校验，包括类型、取值、字段是否存在等校验，校验不通过，会返回相应的错误信息，校验通过，会将相关数据进行持久化存储。在第三方应用与流程引擎交互过程中，不管是第三方应用的业务数据，还是流程引擎的流转记录、状态、与第三方应用的交互记录，都会被记录下来，第三方应用可以用类似数据库表查询的方式，以某些条件组合，通过流程引擎提供的WebAPI接口将这些记录查询回来使用。
完备的流程引擎能力
本产品具备完备的流程引擎能力，为开发者提供GUI流程建模工具，可以用于流程模型编辑、流程模型加载。除此之外还为应用开发提供了一系列WebAPI开发接口，用于流程实例发起、流程实例驱动、流程实例查询。

除了可以通过WebAPI与流程引擎进行交互，使用者还可通过登陆基础使能平台从UI上查看流程的相关信息，如查看应用的流程模型或特定应用下用户的信息。平台的用户体系由超级管理员、管理员、开发者三级组成。超级管理员是平台最高职能的角色，拥有平台所有的权限，可以对管理员和开发者进行添加或者删除的操作。一般来说，超级管理员主要职责是管理平台的管理员。第二级的角色是平台管理员，平台管理员主要负责管理平台的开发者账号、将开发者编辑好的流程模型生成对应的流程服务并审核授权给开发者。此外，管理员可以禁用、删除开发者账号。对于开发者，此角色是平台的服务对象，由应用开发者登陆。开发者可以管理旗下的应用账号，包括禁用和删除的操作。应用账号是开发者独有的概念用来隔离开发的不同应用，具体会在下文中介绍。

总而言之，平台的用户关键职能如下：

超级管理员：可以添加新的平台管理员、新的开发者。对于管理员，超级管理员可以设置其是否有权查看和修改开发者应用下的流程模型。可以禁用、恢复开发者及旗下所有的应用。可以将开发者编辑好的流程模型生成对应的流程服务并审核授权给开发者。
管理员 ：可以添加新的开发者，可以禁用、恢复开发者及旗下所有的应用。被禁用的开发者将无法登录系统，其下属的应用账户将无法访问任何流程。可以将开发者编辑好的流程模型生成对应的流程服务并审核授权给开发者。
开发者：可以管理账号下的所有应用账号，包括新建、删除、禁用、恢复应用账号。可以申请对流程服务的使用权限。

二、功能介绍

2-1 管理应用账号

2-1-1 基本概念

应用账号

一位应用开发者可能同时负责多个应用的研发，且不同应用面向的场景和用户也有所不同。因此，本产品引入了应用账号的概念来隔离区分不同的应用。对于每一个应用账号来说，都有且只有一套对应的用户体系，并且基于不同的应用账号可以通过GUI来创建应用所需的多个流程。在应用通过WebAPI接口与流程引擎进行交互时，需要提供应用账号进行认证后方可驱动流程。

2-1-2 新建应用账号

应用开发者通过账号密码登陆进基础使能平台后，方可进行应用账号创建的操作：在左侧菜单栏中点击”应用接入“模块，接着在弹出的二级菜单中点击”应用账户“进入页面。此处会显示应用开发者账号下所有的应用账户，点击右上角的”添加“按钮，完成对应内容的填写即可成功添加应用账号。

2-2 流程用户服务

2-2-1 基本概念

流程用户

流程用户是指在流程里面使用的人的统称。由三个部分组成：

·用户：指某一个特定的人，流程中可以有多个用户。

·用户组：由多个用户共同组成的一个组别、团体。

·角色：指在流程里充当某种类型或特定职能的人的名称。

一个应用账户（一个应用）有且只有一套绑定的流程用户。而且此套流程用户被应用里的所有流程共用。

2-2-3 查看流程用户

应用开发者登陆进基础使能平台后，可以按顺序点击左侧”流程模型-流程用户“查看应用下的流程用户列表。流程用户页面分为两部分，左侧为应用的选择栏，选择栏里的显示的应用名称与查看应用账号页面里的应用名称是一致的，应用开发者可以点击具体某一个应用来查看其下同步的流程用户有哪些。右侧则是通过点击导航菜单来选择查看应用中用户、用户组、角色的信息。如下图所示：

2-3 流程用户接口

2-3-1 基本概念

流程用户接口主要用于维护流程中的用户、用户组、角色。

用户：流程引擎服务中可配置的用户，业务系统可以通过同步接口，将业务系统中的用户同步到流程引擎。
用户组：由多个用户形成的组。
角色：与用户组相似，可以给某个或多个用户赋予不同的角色。

注：用户和用户组，用户和角色之间属于一对多的关系，一个用户组可以包含多个用户，一个角色也可以包含多个用户，目前这里并没有对于角色和用户组成员做限制，同一个用户也可以属于多个角色或存在于多个用户组中（不推荐使用）

以上三个基本概念在开发者基于流程引擎服务开发应用系统时，一般使用流程如下：

2-3-2 同步流程用户

2-3-2-1 单个用户同步

本接口提供给开发者同步单个流程用户到流程引擎的服务。

properties参数及取值（请求头请求体等参数详情附录4.1-接口规范- 流程用户服务接口规范）

参数	取值	类型	说明	是否必填
mgmt_op	user_add	字符串	操作符	是
user_key	用户唯一标识	数值	由开发者定义用户的唯一标识	是
user_name	用户名	字符串	由开发者自定义的用户名	是

请求示例参数

POST /Pes/pes/idm HTTP/1.1
Host: localhost:3001   // 请将localhost替换为服务器主机IP
Content-Type: application/json
TD-Timestamp: [当前unix时间戳]
TD-Authorization: [用户名加TOKEN加时间戳的HMAC计算值]
TD-Account: [用户名]
TD-Charset: utf-8
TD-Topic: $META/PESEXT/User

{
  "project_token": "PESEXT",
  "event": "User",
  "timestamp": 1536850292000,
  "properties": {
    "mgmt_op": "user_add", // 操作类型：添加
    "user_key": "user0",
    "user_name": "路人0"
  }
}

使用接口时主要修改user_key及user_name字段即可，新增的用户会显示在当前应用账户下，即由TD-Account的用户名决定新增用户的所属账户

返回示例

{
  "code": 0,
  "msg": "[DACE_OK]:success"
}

状态码为0表示操作成功，其他返回码均为操作失败

2-3-2-2 批量用户同步

本接口提供给开发者批量同步流程用户到流程引擎的服务。

properties参数及取值（请求头请求体等参数详情附录4.1-接口规范- 流程用户服务接口规范）

参数	取值	类型	说明	是否必填
mgmt_op	user_batch_add	字符串	操作符	是
user_list	json类型的数组	数组	json类型数组，每个json对象里存有user_key、user_name两个字段	是

请求示例参数

POST /Pes/pes/idm HTTP/1.1
Host: localhost:3001        // 请将localhost替换为服务器主机IP
Content-Type: application/json
TD-Timestamp: [当前unix时间戳]
TD-Authorization: [用户名加TOKEN加时间戳的HMAC计算值]
TD-Account: [用户名]
TD-Charset: utf-8
TD-Topic: $META/PESEXT/User

{
    "project_token": "PESEXT",
    "event": "User",
    "timestamp": 1536850292000,
    "properties": {
        "mgmt_op": "user_batch_add",  // 操作类型：批量添加
        "user_list": [
            {
                "user_key": "test01",
                "user_name": "测试1"
            },
            {
                "user_key": "test02",
                "user_name": "测试2"
            }
        ]
    }
}

使用接口时主要修改user_list的用户列表即可，批量添加时用户数目不限

返回示例

{
  "code": 0,
  "msg": "[DACE_OK]:success"
}

状态码为0表示操作成功，其他返回码均为操作失败

2-3-3 维护流程用户

2-3-3-1 更新用户

本接口用于根据已有的用户唯一标识进行用户名重命名的操作。

properties参数及取值（请求头请求体等参数详情附录4.1-接口规范- 流程用户服务接口规范）

参数	取值	类型	说明	是否必填
mgmt_op	user_add	字符串	操作符	是
user_key	用户唯一标识	数值	需要更新的用户唯一标识	是
user_name	用户名	字符串	由开发者自定义的用户名	是

请求示例参数

POST /Pes/pes/idm HTTP/1.1
Host: localhost:3001         // 请将localhost替换为服务器主机IP
Content-Type: application/json
TD-Timestamp: [当前unix时间戳]
TD-Authorization: [用户名加TOKEN加时间戳的HMAC计算值]
TD-Account: [用户名]
TD-Charset: utf-8
TD-Topic: $META/PESEXT/User

{
    "project_token": "PESEXT",
    "event": "User",
    "timestamp": 1536850292000,
    "properties": {
        "mgmt_op":  "user_update",   // 操作类型：更新用户
        "user_key": "test01",
        "user_name": "测试3"
    }
}

测试接口时主要更改user_key及user_name字段即可

返回示例

{
    "code": 0,
    "msg": "[DACE_OK]:success",
    "results": [
        {
            "_sys_write_time": 1699337913772371,
            "user_id": 4,
            "user_is_deleted": false,
            "user_key": "test01",
            "user_name": "测试3"
        }
    ]
}

状态码为0表示操作成功，其他状态码均为操作失败

更新用户时，只能更新由对应账户创建的用户，请确保操作的账户与账户的TD-Authroization匹配，如果不匹配，则可能会导致如下错误：

返回示例（失败）

{"code":"30101","msg":"update_user_error"}

2-3-3-2 编辑用户组

此接口有两重含义，如果用户组名称未被添加，即会新建此用户组，若用户组名称已存在，则此接口会往用户组里添加用户。另外，在添加用户组时，并不会确认用户组内成员是否已经创建，即用户组和用户组成员之间并无强耦合关系，因此在创建用户组时，需要根据业务需求考虑用户组的有效性。

properties参数及取值（请求头请求体等参数详情附录4.1-接口规范- 流程用户服务接口规范）

参数	取值	类型	说明	是否必填
mgmt_op	group_add	字符串	操作符	是
group_name	用户组名称	字符串	开发者自定义的用户组名称	是
group_user_array	用户数组	字符串数组	由用户唯一标识符形成的数组，该数组的用户将会被添加到用户组中	是
group_id	用户组ID	数值	用户组唯一标识	否

请求示例参数

POST /Pes/pes/idm HTTP/1.1
Host: localhost:3001        // 请将localhost替换为服务器主机IP
Content-Type: application/json
TD-Timestamp: [当前unix时间戳]
TD-Authorization: [用户名加TOKEN加时间戳的HMAC计算值]
TD-Account: [用户名]
TD-Charset: utf-8
TD-Topic: $META/PESEXT/UserGroup

{
    "project_token": "PESEXT",
    "event": "UserGroup",
    "timestamp": 1536850292000,
    "properties": {
        "mgmt_op": "group_add",        // 操作类型：添加组
        "group_name": "组织3",
        "group_user_array": ["test05","test06","test07"]  // 数组内为用户组成员列表
    }
}

测试接口时主要更改group_name及group_user_array字段即可，其中group_user_array中的值为数组内用户成员列表user_key，请尽量确保在创建用户组时当前用户已创建

返回示例

{
    "code": 0,
    "msg": "[DACE_OK]:success"
}

状态码为0表示操作成功，其余返回码均为操作失败

2-3-3-3 用户组全量更新用户

此接口用于重洗用户组里包含的用户，即用户组里原有的所有用户会被删除并且被group_user_array即用户数组里的用户取代。若更新的用户组在之前尚未被创建出来，则无法进行全量更新，会有报错信息提示。

properties参数及取值（请求头请求体等参数详情附录4.1-接口规范- 流程用户服务接口规范）

参数	取值	类型	说明	是否必填
mgmt_op	group_add	字符串	操作符	是
group_name	用户组名称	字符串	开发者自定义的用户组名称	是
group_user_array	用户数组	字符串数组	由用户唯一标识符形成的数组，该数组的用户将会被添加到用户组中	是

请求示例参数

POST /Pes/pes/idm HTTP/1.1
Host: localhost:3001         // 请将localhost替换为服务器主机IP
Content-Type: application/json
TD-Timestamp: [当前unix时间戳]
TD-Authorization: [用户名加TOKEN加时间戳的HMAC计算值]
TD-Account: [用户名]
TD-Charset: utf-8
TD-Topic: $META/PESEXT/UserGroup

{
    "project_token": "PESEXT",
    "event": "UserGroup",
    "timestamp": 1536850292000,
    "properties": {
        "mgmt_op": "group_update",
        "group_name": "组织3",
        "group_user_array": ["test01","test02","test03"]  // 新的组成员列表
    }
}

测试接口时主要更改"group_name"及"group_user_array"字段，将上述字段替换为需要的组织名称和组织成员用户列表（内容为user_key），可批量添加，用户成员数不限

返回示例

{
    "code": 0,
    "msg": "[DACE_OK]:success",
    "results": [
        {
            "_sys_write_time": 1699414964570165,
            "group_id": 3,
            "group_name": "组织3",
            "group_user_array": [
                "test01",
                "test02",
                "test03"
            ]
        }
    ]
}

状态码为0表示操作成功，其余状态码均为操作失败

返回示例（失败）

{
    "code": "30301",
    "msg": "update_group_error"
}

操作失败的可能原因有用户Auth不匹配，用户组在操作前未被创建等

2-3-3-4 编辑角色

此接口有两重含义，如果角色角色未被添加，即会新建此角色，若角色名称已存在，则此接口会往角色里添加用户。

properties参数及取值（请求头请求体等参数详情附录4.1-接口规范- 流程用户服务接口规范）

参数	取值	类型	说明	是否必填
mgmt_op	role_add	字符串	操作符	是
role_name	角色名	字符串	开发者自定义的角色名称	是
role_user_array	用户数组	字符串数组	由用户唯一标识符形成的数组，该数组的用户将会被添加到角色中	是

请求示例参数

POST /Pes/pes/idm HTTP/1.1
Host: localhost:3001        // 请将localhost替换为服务器主机IP
Content-Type: application/json
TD-Timestamp: [当前unix时间戳]
TD-Authorization: [用户名加TOKEN加时间戳的HMAC计算值]
TD-Account: [用户名]
TD-Charset: utf-8
TD-Topic: $META/PESEXT/Role

{
    "project_token": "PESEXT",
    "event": "Role",
    "timestamp": 1536850292000,
    "properties": {
        "mgmt_op": "role_add",
        "role_name": "角色2",
        "role_user_array": ["test01"]
    }
}

使用接口时主要更改"role_name"字段和"role_user_array"字段，分别代表角色名称和角色用户数组列表，一个角色可匹配多个用户

返回示例

{
  "code": 0,
  "msg": "[DACE_OK]:success"
}

状态码为0表示操作成功，其他返回结果均失败

2-3-3-5 角色全量更新用户

此接口用于重洗角色里包含的用户，即角色里原有的所有用户会被删除并且被role_user_array即用户数组里的用户取代。若更新的用户组在之前尚未被创建出来，则无法进行全量更新，会有报错信息提示。

properties参数及取值（请求头请求体等参数详情附录4.1-接口规范- 流程用户服务接口规范）

参数	取值	类型	说明	是否必填
mgmt_op	role_add	字符串	操作符	是
role_name	角色名	字符串	开发者自定义的角色名称	是
role_user_array	用户数组	字符串数组	由用户唯一标识符形成的数组，该数组的用户将会被添加到角色中	是
role_id	角色ID	数值	角色唯一标识	否

请求示例参数

POST /Pes/pes/idm HTTP/1.1
Host: localhost:3001        // 请将localhost替换为服务器主机IP
Content-Type: application/json
TD-Timestamp: [当前unix时间戳]
TD-Authorization: [用户名加TOKEN加时间戳的HMAC计算值]
TD-Account: [用户名]
TD-Charset: utf-8
TD-Topic: $META/PESEXT/Role

{
    "project_token": "PESEXT",
    "event": "Role",
    "timestamp": 1536850292000,
    "properties": {
        "mgmt_op": "role_update",    // 操作类型：更新角色
        "role_name": "角色1",
        "role_user_array": ["userD","userE"]
    }
}

使用接口时主要更改"role_name"和"role_user_array"字段即可，分别代表角色名称及角色对应用户列表，列表内以user_key作为标识

返回示例

{
    "code": 0,
    "msg": "[DACE_OK]:success",
    "results": [
        {
            "_sys_write_time": 1661415665213026,
            "role_id": 30,
            "role_name": "角色1",
            "role_user_array": [
                "userD",
                "userE"
            ]
        }
    ]
}

状态码为0表示操作成功，其余状态码均为操作失败，其中"results"字段返回的是更新完成后新的角色用户对应关系

2-3-4 查询用户待办

2-3-4-1 获取用户相关流程

properties部分参数及取值（请求头请求体等参数详情附录4.1-接口规范- 用户待办接口规范）

参数	取值	类型	说明	是否必填
resource_uri	$META/PESEXT/UserNodeMapView	字符串	接口唯一标识	是

第一个condition取值及说明

参数	取值	类型	说明	是否必填
attr_name	user_key	字符串	用户唯一标识的字段名	是
attr_val	用户唯一标识	字符串	由开发者定义的用户唯一标识	是
op_type	=	字符串	操作符	是
set_op	NAN	字符串	多个条件间的连接符，可参考SQL	是

请求示例参数

POST /Daas/sp1/bms HTTP/1.1
Host: localhost:3001        // 请将localhost替换为服务器主机IP
Content-Type: application/json
TD-Timestamp: [当前unix时间戳]
TD-Authorization: [用户名加TOKEN加时间戳的HMAC计算值]
TD-Account: [用户名]
TD-Charset: utf-8

{
    "event": "Request",
    "project_token": "SLUIS_SYNC",
    "properties": {
        "condition": [
            {
                "attr_name": "user_key",
                "op_type": "=",
                "attr_val": "userE",
                "set_op": "NAN"
            }
        ],
        "event_type": "STATE",
        "request_type": "total",
        "resource_uri": "$META/PESEXT/UserNodeMapView",
        "sp_name": "sp1",
        "version": "v1.0"
    },
    "timestamp": 1645955496
}

使用该接口时主要修改"condition"中的字段信息，此处的语义为查询用户user_key为"userE"的所有相关的流程信息

重要字段说明

参数	类型	说明
pes_process_key	字符串	用户相关流程接口路径。
pes_node_key_array	数组	用户所在流程中担任节点负责人的节点ID。

返回示例

{
    "ack_code": "1",
    "ack_reason": "success",
    "data": [
        {
            "pes_node_key_array": [
                "Activity_1yqym4u",
                "zWHeKvblDryezzrq"
            ],
            "pes_process_key": "100_second/Form",
            "user_id": 129,
            "user_key": "userE"
        }
    ]
}

返回码为1表示操作成功，其他返回码均为操作失败，此处的"pes_process_key"的值即为该用户关联的流程流程模型"process_key"的信息，"pes_node_key_array"即为该流程模型所包含的所有节点的节点名称信息

2-3-4-2 获取用户待办

properties部分参数及取值（请求头请求体等参数详情附录4.1-接口规范- 用户待办接口规范）

参数	取值	类型	说明	是否必填
resource_uri	$META/PESEXT/ListTodo	字符串	接口唯一标识	是

第一个condition取值及说明

参数	取值	类型	说明	是否必填
attr_name	process_key	字符串	流程模型唯一标识字段名	是
attr_val	流程模型唯一标识	字符串	用户相关的流程模型唯一标识	是
op_type	=	字符串	操作符	是
set_op	AND	字符串	多个条件间的连接符，可参考SQL	是

第二个condition取值及说明

参数	取值	类型	说明	是否必填
attr_name	user_key	字符串	用户唯一标识的字段名	是
attr_val	用户唯一标识	字符串	由开发者定义的用户唯一标识	是
op_type	=	字符串	操作符	是
set_op	NAN	字符串	多个条件间的连接符，可参考SQL	是

请求示例1

POST /Daas/sp1/bms HTTP/1.1
Host: localhost:3001        // 请将localhost替换为服务器主机IP
Content-Type: application/json
TD-Timestamp: [当前unix时间戳]
TD-Authorization: [用户名加TOKEN加时间戳的HMAC计算值]
TD-Account: [用户名]
TD-Charset: utf-8

{
    "event": "Request",
    "project_token": "SLUIS_SYNC",
    "properties": {
        "condition": [
            {
                "attr_name": "process_key",
                "attr_val": "100_second/Form",
                "op_type": "=",
                "set_op": "AND"
            },
            {
                "attr_name": "user_key",
                "attr_val": "userF",
                "op_type": "=",
                "set_op": "NAN"
            }
        ],
        "event_type": "STATE",
        "request_type": "total",
        "resource_uri": "$META/PESEXT/ListTodo",
        "sp_name": "sp1",
        "version": "v1.0"
    },
    "timestamp": 1645955496
}

该接口为查询用户待办的一个核心接口，其中codition中封装的是对应的查询条件，多个查询条件之间用"AND"连接，最后一个查询条件后用"NAN"结尾，若使用或语义查询，也可以使用"OR"关键字（关于更详细的使用语法，可参看Daas文档），以上查询示例的语义是查询"process_key"为"100_second/Form"的流程下userF用户的所有用户待办信息

返回示例说明： 如下图，返回的信息是用户在特定的流程模型中不同流程实例的待办信息。下图查询回来共两个涉及到100_second/Form流程模型的流程实例，可以看到除了流程引擎系统字段外，还有三个业务字段，分别是my_num，my_str，my_text。这三个业务字段因为在该流程节点把三个字段的可读权限都打开了，所以在查询用户待办时候会显示，为空值且等待用户填写，至于这些字段能否赋值也要取决于节点权限中这三个字段是否勾选了可写属性

返回示例1

{
    "ack_code": "1",
    "ack_reason": "success",
    "data": [
        {
            "current_node": "zWHeKvblDryezzrq",
            "form_status": "waiting_submit",
            "from_node": "start_node",
            "job_key": "721f87fb-b9a1-40e1-9cf8-00c412397972",
            "my_num": "",
            "my_str": "",
            "my_text": "",
            "node_ext_info": "",
            "process_key": "100_second/Form",
            "step_id": 2,
            "to_node": null,
            "write_mode": "submit"
        },
        {
            "current_node": "zWHeKvblDryezzrq",
            "form_status": "waiting_submit",
            "from_node": "start_node",
            "job_key": "7729e636-a4b4-4e86-b4ba-97ea6d77d4d7",
            "my_num": "",
            "my_str": "",
            "my_text": "",
            "node_ext_info": null,
            "process_key": "100_second/Form",
            "step_id": 2,
            "to_node": null,
            "write_mode": "edit"
        }
    ]
}

返回码为1表示操作成功，其余返回码均为操作失败，其中data中的数据就包含了该用户在该流程下的所有待办信息列表，所有待办信息列表的状态均为"waiting_submit"等待提交状态，其中"current_node"为用户待办的所处节点名称，"job_key"为对应的流程实例ID,"write_mode"为查询前流程表单所处的操作状态，其他字段为相应的业务/系统字段，主要关注"current_node"、"form_status"、"job_key"、"step_id"及表单对应的业务字段信息等

请求示例 2（通过流程+角色的方式过滤待办信息）

POST /Daas/sp1/bms HTTP/1.1
Host: localhost:3001            // 请将locahost替换为服务器主机IP
Content-Type: application/json
TD-Timestamp: [当前unix时间戳]
TD-Authorization: [用户名加TOKEN加时间戳的HMAC计算值]
TD-Account: [用户名]
TD-Charset: utf-8

{
    "event": "Request",
    "project_token": "SLUIS_SYNC",
    "properties": {
        "condition": [
            {
                "attr_name": "process_key",
                "attr_val": "1010_LWZY_SP_P/Form",
                "op_type": "=",
                "set_op": "AND"
            },
            {
                "attr_name": "role_name",
                "attr_val": "政数局审核员",
                "op_type": "=",
                "set_op": "AND"
            },
            // 以下可以继续在获取待办时添加其他过滤条件，语法和Daas请求语法格式相同
            // {
            //     "attr_name": "apply_unit_name",
            //     "attr_val": "政数局",
            //     "op_type": "=",
            //     "set_op": "NAN"
            // }
        ],
        "event_type": "STATE",
        "request_type": "total",
        "resource_uri": "$META/PESEXT/ListTodo",
        "sp_name": "sp1",
        "version": "v1.0"
    },
    "timestamp": 1705042315404
}

该接口为查询用户待办的一个核心接口，通过以上请求方式获取待办的语义是：获取当前流程下属于该角色（此处示例为政数局审核员）的所有待办信息（注：可能有多个用户属于同一种角色的情况，那么不论是那个用户，只要属于该角色，都可通过以上接口，查询到该角色所对应的待办信息）

返回示例2：

{
    "ack_code": "1",
    "ack_reason": "success",
    "data": [
        {
            "current_node": "BTeascmKSPMQydep",
            "form_status": "waiting_submit",
            "from_node": "Gateway_05jeu9d",
            "job_key": "00411ade-6396-426a-990a-ad34b40bb4c6",
            "node_ext_info": "",
            "node_name": "政数局审批",
            "process_key": "1010_LWZY_SP_P/Form",
            "step_id": 3,
            "to_node": null,
            "write_mode": "submit",
            "资源信息": "[{\"is_agree_to_share\":\"有条件共享\",\"remarks\":\"EX_GXPT_08_PERSON_UP\",\"source_name\":\"人口基本信息表（上报）\"},{\"is_agree_to_share\":\"无条件共享\",\"remarks\":\"EX_XXZX_09_AQSCHMD_AJ\",\"source_name\":\"安全生产黑名单\"}]",
            "资源共享类型": "",
            "资源申请主编号": "父流程实例ID-XXXX",
            "资源申请子编号": "子流程实例ID-XXXXX",
            "资源申请流程名": "NA",
            // 其他字段信息
            // ...
        }
    ]
}

注：在以上返回示例结果中，可以看到node_name节点信息名称，该节点信息名称与流程图处流程节点信息名称保持一致，方便用户在查询待办列表时明确当前流程进行情况。（node_name字段的更新使用所对应的datahub版本不低于datahub4.1.9.2版本，在datahub4.1.9.2版本之前，该字段不可用）

2-4 流程模型编辑

2-4-1 基本概念

流程模型的查看

与流程用户一样，流程模型是绑定在某个应用底下的，是基于某个应用下创建的。因此，在查看应用流模型时，需要选择一个应用才能显示相关信息。

流程模型的新建

在编辑流程模型之前，需要先新建一个流程模型并定义模型名称和描述。新建的流程模型处于一个初始化的状态，开发者可以对其表单和流程图进行设计。具体的操作为：点击一级菜单”流程模型“-”模型列表“，在弹出的页面左侧选择对应的应用，点击右侧的添加按钮添加模型。

流程表单

流程表单是提供强大数据能力的基础，可以理解为一个流程表单就是一张“表”，这张表的字段由两部分组成，一部分是流程引擎负责更新维护的字段，可以称之为系统字段，另一部分是提供给第三方应用需要用的字段，称为业务字段。业务字段可以在流程模型的“表单格式”中编辑，此部分内容会在下文具体介绍。第三方应用将基于这张“表”与流程引擎进行交互，应用可以通过这张“表“获取当前流程实例的状态和驱动流程实例。

系统字段与业务字段
一个流程表单的字段由系统字段和业务字段组成，业务字段由第三方应用开发者按照业务需求和应用开发需要自行设计，系统字段为流程表单的必要字段，由流程引擎负责维护，其中系统字段包括下面字段。

字段名	类型	说明
process_key	STRING	流程模型唯一标识，在创建流程模型时由系统生成，一般为“{表单项目名}/{表单模型名}”，在流程流转时系统会将此值写入表单中，供第三方应用查询。
job_key	STRING	流程实例唯一标识，在发起实例时由系统生成，在流程流转时系统会将此值写入表单中，供第三方应用查询。
step_id	ID	在流程实例进行流转时由系统生成并写入表单，第三方应用可以通过查询本字段，得知流程实例目前流转了几步。
write_mode	STRING	表单数据写模式，第三方应用在提交表单时，必须要填写此字段，取值有submit、edit、revise；submit表示提交表单后，驱动流程实例流转；edit表示对流程实例当前环节数据进行修改，不驱动流程实例继续流转；revise表示修改流程实例流转时的历史数据。
form_status	STRING	表单状态，取值有 init、 processing、 waiting_submit、 deprecated、 finished、 completed。在流程流转时，系统会将当前表单流转状态写入表中，第三方应用可以通过查询此值，判断流程实例目前状态，详细说明请查阅本文档2.4.1章节
from_node	STRING	来源节点，当流程实例流转到某一节点时，会将上一个节点的ID写入此值。
current_node	STRING	当前节点，当流程实例流转到某一节点时，会将当前节点的ID写入此值，第三方应用可以通过查询此值知道当前流程实例位于哪一个环节。
to_node	STRING	去向节点，当第三方应用提交表单驱动流程实例流转时，流程引擎通过判断对应流程模型的流转规则得知下一个节点，并将该ID写入此值。
node_ext_info	TEXT	第三方应用自定义信息，在编辑流程模型时由应用开发者配置，在流程实例流转时，流程引擎会去读取相关配置，写到此值中，供应用读取使用。

流程表单中，记录着每一个流程实例，每一个节点环节的数据，即一条记录为一个流程实例中一个节点环节的数据。在进入一个节点环节时，流程引擎通过process_key job_key确定流程实例，生成step_id，并获取上一个节点IDfrom_node、上一个节点业务字段的数据、当前节点IDcurrent_node、当前节点配置的node_ext_info内容，然后将表单状态form_status设为“init”，随后系统将上述内容写入流程表单中，在此过程中，应用无法对该流程实例进行操作，只能够读取信息。当流程引擎将系统内部信息处理完后，会将表单状态form_status修改成“wait_submit”，此时为等待第三方应用提交表单，应用可以对处于该状态的流程实例进行提交表单操作，在提交表单时，必须填写process_key job_key step_id write_mode四个系统字段以及在配置流程模型时配置的，用于流转的业务字段，用于给流程引擎判断当前操作的流程实例、步骤、操作类型，流程引擎会对此进行校验，验证通过后，流程引擎会将流转字段内容与流转规则做比对进行下一步流转。

流程拓扑

流程拓扑能直接反应流程模型的流转逻辑，一个流程拓扑由多个节点和边组成，节点、边、图等概念与BPMN规范一致，此处不再赘述。在本产品中，提供的有“人工填报节点”、“排他网关节点、并行网关节点、合并网关节点、包容网关节点” 。

节点名称	节点描述
人工操作节点	支持在节点中预设置表单的值、该节点会等待用户提交流程当前节点的表单数据并基于表单字段判断是否符合流程流转条件并出边。
排他网关节点	网关节点所有分支会判断条件是否为true来选择执行且只会执行第一个为true的分支执行。
并行网关节点	并行网关会无条件执行它所连接的所有分支路径。
合并网关节点	所有到达合并网关的分支路径会汇聚于此并等待，直到每个分支都执行完毕并到达网关才会继续流转，若有分支未执行则此网关会永久等待
包容网关节点	与排他网关不同，包容网关会依次执行所有判断条件为true的分支路径。

负责人 负责人也叫节点负责人，是指某一节点接收数据并进行处理的人。一个流程通常由多个节点组成，流程中的不同节点(阶段)需要配置相应的节点负责人来指定在此节点谁有权或应该由谁来处理数据以推动流程的流转。

流转通知

流程流转通知服务是一种基于流程节点的流程实例流转通知，在流程满足某种设置好的条件后会触发流转通知的事件。例如，当流程流转进入到某一个特定的流程节点时会触发通知事件。具体的触发条件会在下文中具体介绍。流转通知可以通过在流程模型的编辑页面上对通知服务进行配置并使用。

对流程规则编辑中操作前、操作后的理解

在编辑流程规则时，可以对流程里各个节点进行操作前、操作后的编辑操作，来保证流程可以进行正常流转。

规则编辑中，“操作前”可以视为准备工作，即在用户进行操作之前预设表单里字段的值。
规则编辑中，“操作后”可以视为对于结果的处理，即流程任务根据某种配置的逻辑得出结果并根据结果进行后续的操作，如流程会流向哪一个后续节点。

本章节所使用概念的解释

概念	概念描述
边	连接两个节点的有向线称为节点的边，它对指向节点而言是出边，被指节点而言是入边。
埋点	配置流转通知的概念，指针对某种特定行为进行捕获。例如，”当流程流转或进入到A节点“可作为一种埋点，当满足埋点这种特定的行为时会触发某种机制。

2-4-2 流程表单

流程表单是第三方应用与流程引擎交流的窗口。流程表单包含了流程实例的系统状态与业务信息，其中系统状态由流程引擎维护，业务信息由第三方应用更新。这样，第三方应用通过查询流程表单获取流程实例状态与业务信息，并通过更新流程表单来驱动流程实例。

流程表单的字段分为系统字段与业务字段。系统字段由流程引擎维护，说明了流程实例当前的系统状态（如流程实例ID、当前节点、表单状态等），其字段组成是固定的。业务字段由第三方应用更新，其组成可按业务需求自定义。下面将以一个报销业务的流程表单结构为例进行说明。

字段名	类型	说明	交互说明	字段分类
process_key	字符串	流程模型唯一标识	流程实例发起后由流程引擎更新	系统字段
job_key	字符串	流程实例唯一标识	流程实例发起后由流程引擎更新	系统字段
step_id	ID	流程实例步骤标识	流程实例驱动后由流程引擎更新	系统字段
write_mode	字符串	表单数据写模式	流程实例驱动后由流程引擎更新	系统字段
form_status	字符串	表单状态	流程实例驱动后由流程引擎更新	系统字段
from_node	字符串	来源节点	流程实例驱动后由流程引擎更新	系统字段
current_node	字符串	当前节点	流程实例驱动后由流程引擎更新	系统字段
to_node	字符串	去向节点	流程实例驱动后由流程引擎更新	系统字段
node_ext_info	文本	节点扩展信息	存储于该节点的辅助信息，第三方应用可读取	系统字段
reviewer_result	层级字典	处理人处理结果	由第三方应用驱动流程实例更新	业务字段
reviewer	字符串	处理部门（人）	由第三方应用驱动流程实例更新	业务字段
applicant_name	字符串	申请人名称	由第三方应用驱动流程实例更新	业务字段
amount	数值	报销金额	由第三方应用驱动流程实例更新	业务字段

应用开发者创建好流程模型后可以配置流程表单。依次点击”流程模型-模型列表“来查看某一应用下的流程模型列表，通过点击模型名称进入模型后可以看到基础信息、表单格式、流程图、控制面板四个关于模型的板块。点击表单格式模块以进入页面编辑流程表单。

流程表单的编辑页面分为三部分，左侧一栏是表单的基础字段，也称作控件库。此处共支持八种基础字段：

控件名	控件描述
字符串	数字、字母、下划线组成的一串字符。
文本	允许多行输入，可在在框内填写相应内容；
数值	整型数字字段；
时间戳	使用Unix时间戳格式，可为10、13、16、19位长度，分别对应秒、毫秒、微妙、纳秒精度；
布尔值	是“真” True 或“假” False 中的一个，数据表中为字符串型字段；
字符数组	报文中以JSON ARRY形式存在，（如，“要素名”：["e1","e2","e3"]）；数据表中表现为字符型字段，字段内容与JSON报文中相同；
数值数组	报文中以JSON ARRY形式存在，（如，“要素名”：[1,2,3]）；数据表中表现为字符型字段，字段内容与JSON报文中相同。
层级字典	层级字典以“层级+枚举”的组合限制层级字典要素的取值范围。层级字典具有确定层级数，层级之间具有关联关系，每个层级的取值可枚举。

可以将左侧控件拖拽至中间一栏生成对应类型字段的输入框，此处的展示内容与流程用户在实际填写数据时表单的展现形式一致。在将控件拖入到中间一栏后，点击控件会在右侧一栏显示对应的设置页面。右侧一栏会显示并允许编辑此控件的相关信息：字段名、字段类型和字段中文名。其中字段名是开发者自定义的用户键值(key)，字段类型在创建字段的时候就会自动生成且不可变更，字段中文名则是字段的描述。目前需要对每一个流程表单里的字段编辑后点击右下角保存按钮单独保存，比如下图有"myStr"，"myText"，"myNum"三个字段，则需要分别保存一次共三次

2-4-3 流程拓扑

编辑流程拓扑：人为操作节点、排他网关、并行网关、合并网关、包容网关节点介绍

人为操作节点：形状是矩形的节点，人为操作节点是流程中唯一需要等待用户提交的节点，没有出入边数量的限制。

排他网关：形状是菱形内包含“X”的节点，没有入边数量的限制，但是出边数量需要大于等于2。

并行网关：形状是菱形内包含“+”的节点，一般只有一条入边且伴随多条出边。并行网关无需配置任何条件，其有多少条出边就会直接分流到多个环节。

合并网关：与并行网关共用一个形状，但是他们的功能却是不相同的，在流程拓扑编辑中以图形的旁白文字来辨识。合并网关一般有多条入边，出边没有限制。

编辑流程拓扑：基础操作

通过点击模型名称进入模型后在流程图模块编辑拓扑。如下图为流程的初始默认拓扑，包含一个开始节点、结束节点和一个人为操作节点。

流程拓扑节点类型的介绍：目前流程拓扑共有四种节点，开始节点、结束节点、人为操作节点、条件网关节点、并行网关节点和合并网关节点，每个流程拓扑只有一个开始节点和结束节点。

流程拓扑节点的添加：流程拓扑是由节点连接而成的，想要添加节点，需要点击你想要拓展的节点然后点击“+”图标，如下图所示，为开始节点添加一个人为操作节点。

下图为成功添加节点后的流程拓扑

流程拓扑节点连接与移动：把鼠标放到想要移动的节点身上并保持左键的按下可以拖动目标节点，若想要连接两个节点A和B，则可以通过以下操作来完成，点击节点A-点击箭头图标-点击节点B。示意图如下：

下图为连接后的流程拓扑：

流程拓扑节点的移除：删除流程拓扑的节点可以通过点击想要删除的节点后，点击垃圾桶图标来完成。需要注意的是：删除节点需要保留流程拓扑的完整性，需要保留至少一条路线从开始到结束节点，路线某节点不能脱离拓扑单独存在(某一个节点没有连接其他任何节点)。

以下为成功删除节点的流程拓扑：

2-4-4 编辑负责人

节点负责人的配置栏可以通过打开流程拓扑中节点的编辑页面中找到。打开节点配置页面后可以看到“负责人”一栏，点击加号图标为此节点添加负责人。节点的负责人可以是一位或者多位用户，也可以是一个用户组或一种角色等，支持不同类型负责人的组合搭配。此处所显示的用户、用户组、角色信息与此前介绍的流程用户里的信息是一致的。当成功添加一位用户、一个用户组、一种角色后，系统会根据用户名称生成图标，图标上显示的用户的名称用来帮助使用者确认节点负责人是否配置正确，在图标右侧可以进行删除的操作。如下图所示：

为节点设置好负责人后，可以为其配置会签、或签的多人操作类型。会签要求所有节点负责人都要进行处理操作后流程才会流转到下一节点。而或签只需要多名节点负责人中的其中一名完成操作即可。

需要注意的是，因为配置会签后需要多个节点负责人进行表单的操作提交，若某一个表单字段因为负责人提交表单有所出入，则会以最后一名节点负责人的字段值为准。即字段值会被最后提交的表单字段值覆盖。

2-4-5 表单权限

对于每一个流程模型来说，都有一与之对应的流程表单。在流程的不同阶段，节点负责人所接收到的信息都有所不同，可能表单里的某个字段在此节点不应该显示或者是否可以赋值。这时，需要对流程表单根据不同的场景和需求做权限的限制，因此流程表单的权限设置就显得尤为重要。其设置步骤为：打开流程模型的流程拓扑，在拓扑的某一节点中打开设置页面，会在弹出页面中找到“表单展示”一栏，在此处即可设置流程表单的权限。对于每一个表单字段，可以配置其可读、可写的权限。无误后点击下方保存按钮完成操作。

2-4-6 流转规则

流程流转的白名单机制

若想要流程按照既定的路线流转，需要配置相应的流转规则(判断条件)。流程引擎会应用白名单的机制来判断流程是否流转，即流程只会按照配置了的流转规则进行流转。除此之外的任何条件都不能驱动流程。

编辑流转规则

在提供的建模工具前端页面，可以选中某个节点进入节点规则编辑页面。可以通过配置各个节点的条件设置，定义整个流程模型的流转规则。如下图，在”提交报销申请“节点设置了表单字段的”申请报销金额“的预设值。

若想要驱动流程拓扑，需要满足节点配置的流转条件(即在此节点的流转规则)，如下图所示，配置”提交报销申请“节点的流转规则，若想驱动流程至下一节点“部门经理审核”，则需要满足“报销说明”表单字段的值等于“医疗保险药品”的条件。当不止一个条件时，用户也可以新增额外的条件来驱动流程。

流转规则条件判断类型
如上图使用的是名为“字符串相等“的条件判断类型。除此之外，该流程引擎还支持其他不同的条件判断类型供使用，详情如下：

类型	名称	操作数数量	描述
bool.null	空值	1	变量对应字段是否不存在
bool.==	布尔相等	2	两个布尔操作数是否相等
bool.!=	布尔不等	2	两个布尔操作数是否不等
bool.~	布尔取反	1	布尔操作数取反
bool.&&	布尔与操作	2	两个布尔操作数与操作
bool.\	布尔或操作	2	两个布尔操作数或操作
bool.^	布尔异或操作	2	两个布尔操作数异或操作
str.null	空值	1	变量对应字段是否不存在
str.==	字符串相等	2	两个字符串操作数是否相等
str.!=	字符串不等	2	两个字符串操作数是否不等
str.in	字符串在枚举列表中	2	第一个操作数是否在第二个操作数枚举中，枚举应逗号分隔，如："a, b, c, d"
str.contains	字符串包含子串	2	第一个操作数是否包含第二个操作数
num.null	空值	1	变量对应字段是否不存在
num.==	数值相等	2	两个数值操作数是否相等
num.!=	数值不等	2	两个数值操作数是否不等
num.in	数值在枚举列表中	2	第一个操作数是否在第二个操作数枚举中，枚举应逗号分隔，如："1, 2, 3, 4"
num.>	数值大于	2	第一个数值操作数是否大于第二个操作数
num.<	数值小于	2	第一个数值操作数是否小于第二个操作数
num.>=	数值大于或等于	2	第一个数值操作数是否大于或等于第二个操作数
num.<=	数值小于或等于	2	第一个数值操作数是否小于或等于第二个操作数
num.()	数值在开区间内	3	第一个数值操作数是否在第二个操作数和第三个操作组成的开区间内
num.(]	数值在左开右闭区间内	3	第一个数值操作数是否在第二个操作数和第三个操作组成的左开右闭区间内
num.[)	数值在左闭右开区间内	3	第一个数值操作数是否在第二个操作数和第三个操作组成的左闭右开区间内
num.[]	数值在闭区间内	3	第一个数值操作数是否在第二个操作数和第三个操作组成的闭区间内

并行网关条件并行设置

并行网关分为有条件的并行和无条件的并行两种，通过节点设置的一个按钮来开启和关闭。当开启无条件并行时，并行节点后有多少条边，流程图经过并行节点就会分流出多少条边。如下图所示，并行节点后分出两条边，当开启无条件并行时，默认按全部边分出两条，而不需要对每一条分流进行条件判断的配置。

排他网关与并行网关在判断条件的不同

排他网关是一种执行唯一决策的网关节点，当条件列表里有多个判断条件时，网关会按顺序从第一个条件开始判断其条件是否为true，当有条件为true时，流程就会按照此条件流向的下一个节点进行流转且无视接下来的的条件。并行网关则不同，并行网关会判断列表里所有的条件，条件先后是无序的，只要条件判断为true，流程就会流转到对应的环节。

合并网关合并规则配置

当合并网关默认不进行任何配置时候，当所有入边汇聚到合并网关，自动执行合并。此外，合并网关支持配置入边的数量或者环节表单字段是否为空来判断是否执行合并的操作。在根据入边数量合并和根据字段是否为空合并都配置了的情况下，两种判断条件都生效，只有满足两种条件才会进行合并的操作。对于并行中不同环节的表单，以最后一个提交的表单为主，若最后的表单字段与之前提交的并行环节的表单字段有重复的，则最后提交的表单字段会覆盖之前的字段值。

流转通知配置

流程流转的通知支持不同的通知方式，包含HTTP和TOPIC两种，这两种不同通知方式所通知的内容是相同的。无论是HTTP或者TOPIC的流转通知，都需要配置一个或者多个埋点来独立触发流转通知事件。流程流转通知基于用户配置，对于同一节点可以添加多个配置项、配置方式。

在HTTP的方式下，流转通知会发送给配置的指定HTTP服务，需要实现对应的 HTTP Server 以接收并处理通知，请求的方法固定为POST，需要且必填HTTP服务的ip地址以及端口，对于HTTP服务路径以及服务请求头则为选填。配置如下图所示：

参数	类型	必填	描述
ip	STRING	是	HTTP服务ip
port	NUMBER	是	HTTP服务端口
path	ID	否	HTTP服务路径，默认为 `/`
header	OBJECT	否	HTTP服务请求头部，Key-Value形式

TOPIC 方式下流转服务会根据配置发送 MQTT 消息到指定本地话题，需要使用 MQTT Client 连接到流转通知服务所在服务器的 MQTT Server 并订阅该话题获取通知。MQTT 消息内容即为通知内容且消息话题的前缀固定位 PES/NOTICE，后缀可以配置用户名、流程信息或者其他业务相关信息以确保应用可以拿到正确的通知。配置具体如下：

参数	类型	必填	描述
ns	STRING	是	可指定为用户名、流程信息、或其他业务相关信息

节点扩展信息

在编辑流程模型的节点时，可以将第三方应用开发需要用到的信息存储在节点中，该信息将会和节点信息一同存储在相应的流程模型中，当流程实例流转到该节点，流程引擎还会信息写到流程表单的第三方应用自定义信息字段（node_ext_info）中,第三方应用可以通过读取该字段，获取到编辑时存储的信息。

2-5 流程模型加载

2-5-1 流程上线

编辑好的流程模型的上线可以通过界面UI按钮来控制，点击运行按钮后，流程模型会自动加载进入流程引擎。

用户可以通过调用WebAPI接口来调用并校验流程是否按既定的配置运行。

2-5-2 流程下线

可以对上线的流程模型执行下线操作，通过点击停止按钮来下线流程模型。

下线了的流程模型无法再被调用，会显示无法查找到相关流程拓步等错误提示。

2-6 流程实例发起

本章节将介绍流程实例的发起。通过详细的示例说明，帮助接口使用者更好地使用流程实例的发起和预设操作。

2-6-1 基本概念

本产品提供WebAPI给第三方应用进行流程实例各种操作，相关接口规范可查阅本文档4.1章节内容。在流程引擎中，由两个服务负责提供这些接口，分别是流程系统服务和流程数据服务。

流程系统服务

流程系统服务主要负责对流程实例的生命周期进行管理，目前提供了流程实例发起、预设表单信息等接口和发布流程实例结束的功能。

流程数据服务

流程数据服务主要负责对流程实例的数据进行管理，同时为第三方应用提供了与流程引擎进行交互的机制。目前提供了流程实例驱动、流程实例查询相关的接口。

2-6-2 流程实例发起

给定流程模型的唯一标识（process_key），并将job_mgmt_op字段设置为create操作符，即可发起一个流程实例，其中流程实例的唯一标识（job_key）由系统随机生成。在发起流程实例成功后，流程任务将会被自动启动。

流程实例管理接口IP端口和请求路径为：

IP端口：3001
请求路径：/pes/system

properties参数说明：

参数	必填	说明
job_mgmt_op	是	流程实例管理操作符
process_key	是	用于指定实例关联的流程模型key
job_name	是	用于指定实例的名称
job_desc	否	用于添加实例描述信息

以下是一个示例，用于发起流程实例：

POST /pes/system HTTP/1.1
Host: localhost:3001         // 请将localhost更改为服务器主机IP
TD-Topic: $META/PES/JobMgmt
TD-Timestamp: [当前unix时间戳]
TD-Authorization: [用户名加TOKEN加时间戳的HMAC计算值]
TD-Account: [用户名]
Content-Type: application/json

{
    "project_token": "PES",
    "event": "JobMgmt",
    "timestamp": 1648452767998,
    "properties": {
        "job_mgmt_op": "create",
        "process_key": "ProcessDemo/ExpAccount",  // 流程模型唯一标识
        "job_name": "测试任务"
        "job_desc": "任务描述"
    }
}

该接口是一个核心接口,用于发起流程实例，使用时主要更改"process_key"、"job_name"和"job_desc"字段，其中"process_key"为流程模型ID，可在管控平台（可通过http://主机IP:3001 进行访问）流程列表的流程基本信息中查看，"job_name"和"job_desc"为当前创建实例的名称及描述信息，其中process_key和job_name为必填项

返回示例

{
    "code": 0,
    "msg": "[OK]:success",
    "data": [
        {
            "_sys_write_time": 1648714819627053,
            "job_update_time": 1648714819626,
            "job_create_time": 1648714819626,
            "job_creator": 1,
            "job_key": "d7c900e1-bf50-40a0-92be-0cfddd29c64d", // 服务器生成的流程实例key
            "job_name": "测试任务",
            "job_status": "created",
            "process_key": "ProcessDemo/ExpAccount",
            "job_desc": "任务描述"
        }
    ]
}

状态码为0表示操作成功，其他状态码均为操作失败，使用时主要关注job_key，每个发起的流程实例都有唯一确定的job_key作为流程实例的ID,后续的流程实例的查询，表单的提交都需要用到该job_key

2-6-3 预设表单信息

预设表单信息是指在发起流程实例时，可以给流程表单里的业务字段预设一些值，这样在流程流转到第一个节点时，流程引擎会将这些预设信息填入流程表单之中，给第三方应用查询使用。在创建流程实例的同时，可以完成实例的表单信息预设，预设信息只需要填入job_init_data字段即可。

流程实例管理接口IP端口和请求路径为：

IP端口：3001
请求路径：/pes/system

properties参数说明：

参数	必填	说明
job_mgmt_op	是	流程实例管理操作符
process_key	是	用于指定实例关联的流程模型key
job_name	是	用于指定实例的名称
job_desc	否	用于添加实例描述信息
job_init_data	否	用于初始化流程实例表单数据（流程所对应表单格式的json字符串）

job_init_data格式介绍

参数	取值	说明	是否必填
project_token	表单项目名	流程实例管理操作符	是
event	表单模型名	用于指定实例关联的流程模型key	是
timestamp	当前时间戳	用于指定实例的名称	是
properties	json对象	对象内为应用希望预设的业务字段的值，可预设多个值	否

示例：

POST /pes/system HTTP/1.1
Host: localhost:3001        // 请将localhost更改为服务器主机IP
TD-Topic: $META/PES/JobMgmt
TD-Timestamp: [当前unix时间戳]
TD-Authorization: [用户名加TOKEN加时间戳的HMAC计算值]
TD-Account: [用户名]
Content-Type: application/json

{
    "project_token": "PES",
    "event": "JobMgmt",
    "timestamp": 1648452767998,
    "properties": {
        "job_mgmt_op": "create",
        "process_key": "ProcessDemo/ExpAccount",
        "job_name": "测试任务",
        "job_init_data": "{\"project_token\":\"ProcessDemo\",\"event\":\"ExpAccount\",\"timestamp\":1643527646953,\"properties\":{\"assignee\":\"A\"}}"  // 其中assignee为业务字段值
    }
}

以上接口与创建流程实例的接口类似，不同的是该接口可以在流程创建时预填表单信息，预填表单信息的字段为"job_init_data",其格式内容与其他Daas请求体内容类似，其中预设值的字段主要填写在"job_init_data"字段的"properties"属性中，需要注意其中字符串转义的格式。此实例的语义是：创建一个名为"测试任务"的流程实例，对应的流程模型为"ProcessDemo/ExpAccount",预填的表单字段值为assignee

预设表单字段可以不填写，也可以部分填写，但填写时请确保填写内容及格式正确，如果预填信息错误，流程实例创建后则无法运行，使用查询接口产看流程实例流转情况时"data"中的数据值为[]

注意：如果使用层级字典的方式预设字段，需要在预设值中填入层级字典名称+_lvx，其中x表示层级等级，比如在表单中有一个层级字典，层级格式为xzdj(行政等级),下属一层级为gds(广东省),gds下属第二层级为gzs(广州市)，则预填表单时需要填写为{\"xzdj_lv1\":\"gds\",\"xzdj_lv2\":\"gzs\"}

返回示例

{
    "code": 0,
    "msg": "[OK]:success",
    "data": [
        {
            "_sys_write_time": 1648714819627053,
            "job_update_time": 1648714819626,
            "job_create_time": 1648714819626,
            "job_creator": 1,
            "job_key": "d7c900e1-bf50-40a0-92be-0cfddd29c64d",
            "job_name": "测试任务",
            "job_status": "created",
            "process_key": "ProcessDemo/ExpAccount"
        }
    ]
}

状态码为0表示操作成功，其他状态码均为操作失败

2-7 流程实例生命周期管理

根据上一章节的描述，流程实例可以通过接口进行创建，其创建时使用的操作为create，"job_mgmt_op": "create"。除了创建这个操作，在流程实例创建后，流程引擎还可以通过不同的操作以API的形式对其生命周期进行管理。通常来说，有以下几种常见的管理功能：

任务操作	操作符	描述
创建	create	创建并运行流程实例
修改	mod	修改任务信息
暂停	pause	暂停正在运行的流程实例
恢复	resume	恢复已经暂停的流程实例
撤销	halt	撤销流程实例，不可恢复

此章节会介绍流程实例关于修改实例信息、暂停、恢复以及撤销的相关管理。以下的修改流程实例信息相关操作的请求头与创建并运行流程实例示例的请求头一致，下述只给出对应的请求体。

2-7-1 流程实例信息修改

在创建流程实例时，部分字段信息如任务实例名称、任务实例描述可能会设定好，当用户想要对其进行修改时，可以使用操作命令job_mgmt_op": "mod"。修改流程实例的信息可以在任何时候进行，即使实例处于任何状态。系统会根据流程模型的process_key和流程实例的job_key唯一确认待更改流程实例的信息，请务必保证两者的统一性和正确性（修改时，请求头，预设脚本等信息与流程实例创建接口一致，此处不再赘述，以下只展示请求体）

{
    "project_token": "PES",
    "event": "JobMgmt",
    "properties": {
        "process_key": "1002_NewPesTest/Form", 
        "job_key":"501e0bf2-128c-440f-9dea-d987354392e3", //这里需要改为待更改实例的job_key
        "job_mgmt_op": "mod",
        "job_name": "流程实例名称",
        "job_desc": "流程实例描述",
        "other_bus_data":"其他业务字段"
    },
    "timestamp": 1636699890094
}

该接口主要用于修改流程实例表单信息，其中"process_key"+"job_key"唯一确定流程实例，其他业务信息可根据需要进行修改

示例结果

{
        "code": 0,
        "msg": "[OK]:success",
        "data": [
            {
                "_sys_write_time": 1699409217824091,
                "job_update_time": 1699409217824,
                "job_desc": "流程实例描述",
                "job_creator": 22000,
                "job_create_time": 1699341100359,
                "job_init_data": "{\"project_token\":\"1002_NewPesTest\",\"event\":\"Form\",\"timestamp\":1643527646953,\"properties\":{\"Target_Id\":2001}}",
                "job_key": "501e0bf2-128c-440f-9dea-d987354392e3",
                "process_key": "1002_NewPesTest/Form",
                "job_status": "running",
                "job_name": "流程实例名称"
            }
        ]
}

状态码为0表示操作成功，其他状态码均为操作失败

2-7-2 流程实例暂停与恢复

当流程实例正在运行时，可以对其实行暂停的操作。操作的命令为job_mgmt_op": "pause",在流程实例被暂停后，任何对流程实例的操作都会被弃用，直到流程实例被恢复。想要使流程实例继续正常运作，需要使用job_mgmt_op": "resume"操作命令。下图为流程实例在暂停状态被允许和不被允许的操作图示：

流程实例状态	暂停	恢复	撤销
暂停	×	√	√

暂停流程实例（暂停时，请求头，预设脚本等信息与流程实例创建接口一致，此处不再赘述，以下只展示请求体）

{
        "project_token": "PES",
        "event": "JobMgmt",
        "properties": {
            "process_key": "1002_NewPesTest/Form",
            "job_mgmt_op": "pause",
            "job_key": "501e0bf2-128c-440f-9dea-d987354392e3" 
        },
        "timestamp": 1636699890094
}

该接口主要用于暂停使用中的流程实例，使用时主要更改"process_key"和"job_key"信息即可

恢复流程实例（恢复时，请求头，预设脚本等信息与流程实例创建接口一致，此处不再赘述，以下只展示请求体）

{
        "project_token": "PES",
        "event": "JobMgmt",
        "properties": {
            "process_key": "1002_NewPesTest/Form",
            "job_mgmt_op": "resume",
            "job_key": "501e0bf2-128c-440f-9dea-d987354392e3" 
        },
        "timestamp": 1636699890094
}

该接口主要用于恢复暂停状态中的流程实例，使用时主要更改"process_key"和"job_key"信息即可

2-7-3 流程实例撤销

当流程实例满足已被创建且还没有完成结束时，可以进行撤销的操作，即叫停正在运行的流程实例。流程实例的撤销是一个不可逆的过程，只要提交了撤销流程实例的操作，被撤销的实例将不可恢复。下图为流程实例在撤销状态被允许和不被允许的操作图示：

流程实例状态	暂停	恢复	撤销
撤销	×	√	√

撤销流程实例（撤销时，请求头，预设脚本等信息与流程实例创建接口一致，此处不再赘述，以下只展示请求体）

{
        "project_token": "PES",
        "event": "JobMgmt",
        "properties": {
            "process_key": "1002_NewPesTest/Form",
            "job_mgmt_op": "halt",
            "job_key": "501e0bf2-128c-440f-9dea-d987354392e3" 
        },
        "timestamp": 1636699890094
}

该接口主要用于撤销流程实例，撤销时，主要更改"process_key"和"job_key"字段即可，撤销后的流程实例生命周期已完结，不可再更改及恢复

2-8 流程实例驱动

2-8-1 基本概念

流程环节
流程实例在从开始到结束节点流转过程中，每一个流转节点称之为一个流程环节。
流转步骤
由开始节点开始为第1步，流程实例每流转一个节点，该步骤加1，这个记录流程实例流转了多少步的数字，称为流转步骤（step_id）
流程实例（表单）状态
即基于流程模型发起一个流程实例后，流程实例将按照对应流程模型的流转规则在不同流程节点进行流转的状态，流程引擎会将这些状态记录在流程表单的form_status字段中，详细如下。

状态	说明
init	流程引擎通过创建流程实例时附带的预设表单信息对流程表单进行初始化
processing	流程引擎正在处理流程实例当前环节
waiting_submit	流程引擎等待用户提交表单，需要与流程使用者进行交互
deprecated	流程表单数据并行任务已合并，当前表单数据已被弃用
finished	流程实例当前环节已结束
completed	流程实例已完结

当流程引擎处于init processing状态时，说明流程引擎正在做系统内部的相关操作，此时第三方应用无法对该流程实例进行除查询外的操作；当处于waiting_submit时，应用可以对该实例进行提交表单操作，包括单次提交、多次提交、并行提交。deprecated finished completed三个状态时，应用仅能对流程实例进行查询，通过finished状态查询，应用可以获取到已完成节点的信息；通过completed状态，应用可以获取到所有已完成实例信息。

2-8-2 提交表单

当流程实例在特定环节的状态变更为waiting_submit时，用户可以提交该环节的表单数据。提交表单数据需要包含必要的流程实例系统字段，需要通过查询流程实例状态来获取。因此提交表单数据在使用时一般为有查询流程实例状态以及提交表单驱动流程实例两步。

2-8-2-1 查询流程实例状态

查询流程实例状态需要提供表单模型信息以及流程实例信息两部分信息。其中表单模型信息包括表单数据模型所属项目以及数据模型名称（假设分为别 103_final_test 和 Form），流程实例信息包含流程模型关键字以及流程实例的唯一ID（假设分别为 103_final_test/Form 和 xxxx-xxxx...）。查询流程实例允许提交表单的环节的请求体应如下（ 103_final_test、 Form 、103_final_test/Form 和 xxxx-xxxx... 需替换为实际表单及实例信息）：

POST /pes/data HTTP/1.1
Host: localhost:3001        // 请将localhost替换为服务器主机IP
Content-Type: application/json
TD-Timestamp: [当前unix时间戳]
TD-Authorization: [用户名加TOKEN加时间戳的HMAC计算值]
TD-Account: [用户名]
TD-Topic: [流程系统服务话题路径]

{
    "project_token": "SLUIS_SYNC",
    "event": "Request",
    "timestamp": 1644982456271,
    "properties": {
        "version": "v1.0",
        "sp_name": "sp1",
        "request_type": "total",
        "resource_uri": "$META/103_final_test/Form",
        "condition": [{"attr_name": "job_key", "op_type": "=", "attr_val": "1eefcdf9-a1f0-47a6-8330-1c604aa22cef", "set_op": "NAN"}]
    }
}

该接口是一个核心接口，用于查询流程实例流转情况。使用时主要更改"resource_uri及condition过滤条件即可"，若接口调用成功，则返回体中data部分的数据为该流程实例允许提交表单数据的所有环节信息。此时，需要记下数据中的 step_id 信息，用于后续的提交表单驱动流程实例。

2-8-2-2 提交表单驱动流程实例

通过在特定环节提交表单可以驱动流程实例的运行。提交表单驱动流程实例需要提供表单模型信息、流程实例信息、流程环节信息以及表单业务数据、表单提交用户四部分信息。同样的，表单模型信息假设分为别 103_final_test和 Form ；流程实例信息假设分别为 103_final_test/Form 和流程实例的唯一id(job-key)；流程环节信息包含查询流程实例状态接口返回的 step_id 信息，假设为 2；表单数据假设包含若干个业务字段，分别为myNum、myStr、... ，其值分别为555、通过、... ；表单提交用户的系统字段为submit_user_key，需要填写相应的流程用户账号，假设一名由用户账号为personA的用户提交表单，则请求体填写应如下：

POST pes/data HTTP/1.1
Host: localhost:3001        // 请将localhost替换为服务器主机IP
Content-Type: application/json
TD-Timestamp: [当前unix时间戳]
TD-Authorization: [用户名加TOKEN加时间戳的HMAC计算值]
TD-Account: [用户名]
TD-Topic: [流程系统服务话题路径]  // 格式为$META/{}  其中括号占位符代表的是流程模型唯一标识，即process_key 比如此处可以写作：$/META/103_final_test/Form

{
    "project_token": "103_final_test",
    "event": "Form",
    "properties": {
        "process_key": "103_final_test/Form", 
        "job_key": "1eefcdf9-a1f0-47a6-8330-1c604aa22cef",
        "step_id": 2,
        "write_mode": "submit",
        "submit_user_key": "personA",
        "myNum": 555,    // 其中myNum和MyStr为表单中的业务字段,可根据不同模型设定不同字段信息
        "myStr": "通过"
},
    "timestamp": 1536850292000
}

该接口是一个核心接口，用于提交表单驱动流程流转，在使用时需要注意更改请求头处的"TD-Topic"，请求体中的"process_key"、"job_key"和"step_id"等系统字段需要指定为待提交表单的信息，业务字段的更新区别于创建流程实例的接口，这里的业务字段与系统字段同级，业务字段数不限，使用时请确保业务字段和流程表单处的字段一致

注意：每次提交表单后，上一个节点保留的表单数据会被覆盖，所以在提交表单时，尽量填写完整的表单字段信息

只有处于waitting_submit状态的节点才可以被提交

结果示例

{
        "code": 0,
        "msg": "[DACE_OK]:trans msg success!"
}

状态码为0表示操作成功，其他状态码均为操作失败

结果示例（失败1）

{
        "code": 26,
        "msg": "[PEDSCE_JOB_STEP_NOT_MATCH]:job step not match"
}

如果显示该操作结果，证明节点已流转至下一节点或者尚未流转至当前节点，无法在当前状态提交表单

结果示例（失败2）

{
        "code": 26,
        "msg": "[PEDSCE_JOB_STEP_NOT_MATCH]:job step is locked"
}

如果显示该操作结果，证明节点状态为processing状态，还未达到waitting_submit状态

流转失败（表单提交失败）一般由两个可能原因造成，一个是当前流程还未流转到该节点步骤，表单提前提交；另一个是流程已经流转过该节点，表单重复提交。影响节点流转的关键因素为step_id,一般在提交表单前，需要先查询表单流转状态，根据表单流转状态，对于处于waiting_submit状态的节点进行提交,驱动流程流转。

2-8-3 表单编辑

流程表单允许在某环节进行多次提交，只有最后一次提交会驱动流程实例跳转到下一环节。若需要使用多次提交的功能，需要将除最后一次表单提交的 write_mode 设为 edit，最后一次设为 submit即可，当write_mode为edit时，提交表单操作不会驱动流程实例继续流转，因此，提交完后，流程实例仍然处于提交前的环节，只是修改了该环节的业务数据。（表单编辑的请求头与表单提交一致，此处仅给出请求体）

{
    "project_token": "103_final_test",
    "event": "Form",
    "properties": {
        "process_key": "103_final_test/Form", 
        "job_key": "1eefcdf9-a1f0-47a6-8330-1c604aa22cef",
        "step_id": 2,
        "write_mode": "edit",   
        "reviewer":"部门经理"
    },
    "timestamp": 1536850292000
}

表单编辑时主要检查"job_key"、"step_id"、"write_mode"填写是否正确

2-8-4 并行驱动

流程实例的并行驱动需要借助并行网关或包容网关节点来实现。当查询流程实例状态有不止一个环节正在等待提交表单数据时，即代表流程实例正在多个环节上并行运行。此时，可以在所有环节都提交表单，流程实例会按照流程模型的配置并行运行并在到达指定环节后自动将表单进行合并。流程实例的并行驱动依赖于流程如何建模，在提交表单上与非并行模型没有区别。

2-8-5 正确性校验

为保证流程实例的正确运行以及提升业务数据的质量，系统会对用户提交的表单进行正确性校验，包括以下几点：

流程实例校验：校验流程实例是否存在，关联的流程模型是否正确
流程环节校验：校验流程实例是否在指定流程环节是否允许提交表单
业务数据校验：校验表单业务数据部分是否符合表单建模规范，如字段类型是否匹配等

2-8-6 流转通知

在配置好流转通知所需的配置后，流程引擎会根据设置好的埋点和通知方式，在流程实例驱动过程中发布通知内容。流转通知的内容有统一的格式，为符合数据交换语言（DXL）标准的JSON格式且包含以下字段：

状态	类型	说明
process_key	STRING	流程模型key
job_key	STRING	流程任务key
step_id	ID	流程实例步骤ID
current_node	STRING	当前通知节点
notice_point	STRING	当前通知埋点

2-8-7 node_ext_info使用

在驱动流程实例时，可以将第三方应用开发需要用到的信息以自定义的形式存储在节点信息中。当流程实例流转到该节点时，第三方应用可以通过查询流程实例的状态来获取到自定义编辑的存储信息。

2-9 流程实例查询

本章节将介绍流程服务中如何对实例的查询，通过详细的示例说明，帮助接口使用者更好地使用流程服务实例的查询接口。

2-9-1 基本概念

2-9-1-1 流程实例的查询方式 通过给定的流程实例相关信息，对实例按照指定的状态、日志等方式进行查询。以下将介绍用户可更改的参数，其余为固定参数不可修改，否则服务无法正常使用。

流程实例查询接口IP端口和请求路径为：

IP端口：3001
请求路径：/pes/data

参数说明：

参数	必填	说明
resource_uri	STRING	流程实例对应的资源路径，由$META + process_key组成
condition	ARRAY	条件数组，数组内的元素以三元组为对象存在

三元组说明：

状态	必填	说明
attr_name	STRING	流程实例对应表单中的字段名称
op_type	STRING	操作符，有>、<、=这三种操作符，对attr_name指定的字段进行过滤
attr_val	STRING	attr_name对应字段的期望值
set_op	STRING	若有多个三元组，可通过此参数进行AND、OR的操作进行组合，最后一个三元组必须设置为NAN

2-9-1-2 流程实例的状态 在本章节中的操作中涉及流程实例的状态如下：

状态	说明
waiting_submit	流程任务等待用户提交表单，需要与流程使用者进行交互
completed	流程任务已完结

了解更多流程实例状态可查阅本文档第2.4.1章节

2-9-2 查询进行中流程实例

请求示例

POST /pes/data HTTP/1.1
Host: localhost:3001        // 请将localhost替换为服务器主机IP
Content-Type: application/json
TD-Timestamp: [当前unix时间戳]
TD-Authorization: [用户名加TOKEN加时间戳的HMAC计算值]
TD-Account: [用户名]
TD-Charset: utf-8

{
    "project_token": "SLUIS_SYNC",
    "event": "Request",
    "timestamp": 1644982456271,
    "properties": {
        "version": "v1.0",
        "sp_name": "sp1",
        "request_type": "total",
        "resource_uri": "$META/ProcessDemo/ExpAccount",
        "condition": [
            {"attr_name": "form_status", "op_type": "=", "attr_val": "waiting_submit", "set_op": "NAN"}]
    }
}

使用该接口时主要更改"resource_uri"和"condition"条件，其中condition条件可以编写多条，该接口在此处的语义是，查询所有流程模型为"ProcessDemo/ExpAccount"且处于等待提交状态的流程实例

返回示例

{
    "ack_code": "1",
    "ack_reason": "success",
    "data": [
        {
            "applicant_name": "张三",
            "from_node": "Activity_1wv0thz",
            "step_id": 4,
            "result": "审核通过",
            "process_key": "ProcessDemo/ExpAccount",
            "job_key": "2a2a33e3-d361-4b91-be0b-3c969960707b",
            "node_ext_info": "",
            "form_status": "waiting_submit",
            "current_node": "Gateway_0e2ns8a"
        },
        {
            "from_node": "start_node",
            "step_id": 2,
            "write_mode": "submit",
            "process_key": "ProcessDemo/ExpAccount",
            "job_key": "63458d91-0ac1-4c07-a9b3-9fbfd49387b1",
            "node_ext_info": "",
            "form_status": "waiting_submit",
            "current_node": "EIdbOeDpErZZVPll"
        },
        {
            "from_node": "Activity_1wv0thz",
            "step_id": 4,
            "cur_user": "李四",
            "result": "审核通过",
            "write_mode": "submit",
            "process_key": "ProcessDemo/ExpAccount",
            "job_key": "ba07bbaf-742d-47fe-9ede-9f356827d0a6",
            "node_ext_info": "",
            "form_status": "waiting_submit",
            "current_node": "Activity_0hg0ru2"
        }
    ]
}

状态码为1表示操作成功，其他状态码均为操作失败，返回信息中包含对应模型下所有处于等待提交状态中的流程实例及待提交节点信息

2-9-3 查询已完成流程实例

已完成的流转实例已流转至结束节点，并且流程引擎已将流程表单里form_status字段设置为completed的流程实例。

请求示例

POST /pes/data HTTP/1.1
Host: localhost:3001        // 请将localhost替换为服务器主机IP
Content-Type: application/json
TD-Timestamp: [当前unix时间戳]
TD-Authorization: [用户名加TOKEN加时间戳的HMAC计算值]
TD-Account: [用户名]
TD-Charset: utf-8

{
    "project_token": "SLUIS_SYNC",
    "event": "Request",
    "timestamp": 1644982456271,
    "properties": {
        "version": "v1.0",
        "sp_name": "sp1",
        "request_type": "total",
        "resource_uri": "$META/ProcessDemo/ExpAccount",
        "condition": [
              {"attr_name": "form_status", "op_type": "=", "attr_val": "completed", "set_op": "NAN"}]
    }
}

字段"completed"表示当前流程实例已流转完成，顺利流转至最后一个流程节点，此时该流程实例的生命周期已完结，无法在进行暂停，运行，撤销，提交等操作

返回示例（成功）

{
    "ack_code": "1",
    "ack_reason": "success",
    "data": [
        {
            "from_node": "Gateway_0e2ns8a",
            "step_id": 5,
            "result": "审核通过",
            "process_key": "ProcessDemo/ExpAccount",
            "job_key": "0a3ef1e0-fbbd-41ac-82cc-eb420e51ba0c",
            "node_ext_info": "",
            "form_status": "completed",
            "current_node": "end_node"
        },
        {
            "applicant_name": "张三",
            "from_node": "Gateway_0e2ns8a",
            "step_id": 5,
            "result": "审核通过",
            "process_key": "ProcessDemo/ExpAccount",
            "job_key": "a3043a66-6efc-4fa3-9154-4f0d1faf68bd",
            "node_ext_info": "",
            "form_status": "completed",
            "current_node": "end_node"
        },
        {
            "from_node": "Activity_1hg93r4",
            "step_id": 6,
            "process_key": "ProcessDemo/ExpAccount",
            "job_key": "4746c60e-bc35-4847-976c-e188a05d4d40",
            "node_ext_info": "",
            "form_status": "completed",
            "current_node": "end_node"
        }
    ]
}

状态码为1表示操作成功，其他状态码均为操作失败

2-9-4 查询流转记录

流转记录指一个流程实例在流转过程中所有的记录，存于流程表单中，这些记录的系统字段和业务字段都可以查询。值得注意名为done_user_array_json的字段，此字段会记录流程实例中每个步骤提交了表单的流程用户账号。如下面示例所示，在流程实例的第二步有用户账号为userB、userC、userE的三名用户提交了表单，他们先后不分顺序。

请求示例

POST /pes/data HTTP/1.1
Host: localhost:3001        // 请将localhost替换为服务器主机IP
Content-Type: application/json
TD-Timestamp: [当前unix时间戳]
TD-Authorization: [用户名加TOKEN加时间戳的HMAC计算值]
TD-Account: [用户名]
TD-Charset: utf-8

{
    "project_token": "SLUIS_SYNC",
    "event": "Request",
    "timestamp": 1644982456271,
    "properties": {
        "version": "v1.0",
        "sp_name": "sp1",
        "request_type": "total",
        "resource_uri": "$META/100_second/Form",
        "condition": [
                      {"attr_name": "job_key", "op_type": "=", "attr_val": "c817164b-e27c-4b5c-bc1c-c63fcd0b9a07", "set_op": "NAN"}]
    }
}

此接口的语义是查询指定job_key的流程实例流转信息

返回示例

{
    "ack_code": "1",
    "ack_reason": "success",
    "data": [
        {
            "to_node": "zWHeKvblDryezzrq",
            "process_key": "100_second/Form",
            "node_ext_info": "",
            "current_node": "start_node",
            "form_status": "finished",
            "job_key": "c817164b-e27c-4b5c-bc1c-c63fcd0b9a07",
            "step_id": 1
        },
        {
            "to_node": "Gateway_1egiksb",
            "process_key": "100_second/Form",
            "node_ext_info": "",
            "done_user_array_json": "{\"2\":[\"userB\",\"userC\",\"userE\"]}",
            "write_mode": "submit",
            "current_node": "zWHeKvblDryezzrq",
            "form_status": "finished",
            "my_str": "通过",
            "job_key": "c817164b-e27c-4b5c-bc1c-c63fcd0b9a07",
            "from_node": "start_node",
            "step_id": 2
        },
        {
            "to_node": "Activity_1yqym4u",
            "process_key": "100_second/Form",
            "node_ext_info": "",
            "done_user_array_json": "{\"2\":[\"userB\",\"userC\",\"userE\"]}",
            "current_node": "Gateway_1egiksb",
            "form_status": "finished",
            "my_str": "通过",
            "job_key": "c817164b-e27c-4b5c-bc1c-c63fcd0b9a07",
            "from_node": "zWHeKvblDryezzrq",
            "step_id": 3
        },
        {
            "process_key": "100_second/Form",
            "node_ext_info": "",
            "done_user_array_json": "{\"2\":[\"userB\",\"userC\",\"userE\"],\"4\":[\"userA\"]}",
            "write_mode": "edit",
            "current_node": "Activity_1yqym4u",
            "form_status": "waiting_submit",
            "my_str": "通过",
            "job_key": "c817164b-e27c-4b5c-bc1c-c63fcd0b9a07",
            "from_node": "Gateway_1egiksb",
            "step_id": 4
        }
    ]
}

状态码为1表示流转成功，其他状态码均为流转失败

2-9-5 条件组合查询

条件组合查询的接口规范与上述接口类似，可以根据需求对查询条件condition进行组合，比如查询指定job_key下的所有处于等待提交状态的流程及节点信息，可以设置组合查询条件如下：

POST /pes/data HTTP/1.1
Host: localhost:3001        // 请将localhost替换为服务器主机IP
Content-Type: application/json
TD-Timestamp: [当前unix时间戳]
TD-Authorization: [用户名加TOKEN加时间戳的HMAC计算值]
TD-Account: [用户名]
TD-Charset: utf-8

{
    "project_token": "SLUIS_SYNC",
    "event": "Request",
    "timestamp": 1644982456271,
    "properties": {
        "version": "v1.0",
        "sp_name": "sp1",
        "request_type": "total",
        "resource_uri": "$META/100_second/Form",
        "condition": [
            {"attr_name": "job_key", "op_type": "=", "attr_val": "c817164b-e27c-4b5c-bc1c-c63fcd0b9a07", "set_op": "AND"},
            {"attr_name": "form_status", "op_type": "=", "attr_val": "waitting_submit", "set_op": "AND"},
            {"attr_name": "step_id", "op_type": "=", "attr_val": "2", "set_op": "NAN"}
        ]
    }
}

以上接口就是一个组合查询的实例，语义为查询指定流程模型(process_key)、指定流程实例(job_key)、指定节点(step_id)的处于待提交状态的流程信息

2-10流程实例安全访问

2-10-1 安全限制

流程引擎提供的所有接口均有安全限制，在进行WebAPI接口请求时，需要HTTP请求的头部（header）带有以下三个必要键值

TD-Account 值为应用账户，需要填写经过相应授权的应用账户。
TD-Timestamp 值为当前时间戳，粒度为毫秒
TD-Authorization 值为"应用账户"+"应用token"+"TD-Timestamp的值"经过MD5加密之后取32为小写。

这里提供了一个填写安全限制信息的参考模板，如果使用测试工具测试接口，那么可以使用以下脚本作为前置操作：

// var time = Date.now().toString();
var time = "1678413907235";
//替换成授权的账户名
var account = "PES1";
//替换成授权的账户令牌
var token = "ZV701D1TNAsdUXOGLFON2KfPzXejbjgN";
pm.globals.set("auth", CryptoJS.MD5(account + token + time).toString());
pm.globals.set("timestamp", time);
pm.globals.set("account", account);

该前置脚本可以预先设置timestamp、account、auth值，并对获取到的token值进行md5加密处理，在发送请求时，请预先设置

2-10-2 安全配置

想要访问不同的流程实例需要获取对应实例的使用权限。现有两种不同的方法可以获取授权。

告知管理员或平台运营人员主动授予流程实例的访问权限。
对于想要访问的流程实例，应用方提出授权的申请，等待相关人员审批，待申请通过后即可使用。

应用方在申请后可以在相关页面查看申请的进度。

2-11 流程引擎可靠性

2-11-1 意外重启恢复

流程引擎具有可靠性，拥有能在潜在意外发生时保证执行指定的功能或任务。例如，流程实例在运行过程中，服务器意外断电，当电力恢复后，流程引擎可以恢复流程实例在断电前的状态并从上次中断的进程上继续运行流程，即流程实例不会因为意外而中断、丢失从开始到断电前的数据，具体很好的稳定性。

三、实践用例

3-1 用例一：简单的审批流

熟悉流程服务能力

本次示范的流程服务能力对应简单报销流程，流程图及表单格式可在平台流程服务能力的详情页查看，业务应用在具体流程事项中提交表单后，流程服务将根据更新的业务信息按流程图规则自动跳转。

流程图：

表单格式：

获取应用账户、令牌等信息

应用账户可以用来申请流程服务能力，在调用流程服务能力时需要使用授权的应用账户及其令牌来验证身份。

获取应用账户： 以开发者角色登录平台，在应用接入—应用账户标签页面可以获取应用账户，点击应用账户页面获取相关信息，包括查看已创建的应用账户或创建新的应用账户。

获取令牌：

在点击应用账户名后可获取账户的令牌。

本例以new_version应用账户为例，获取对应令牌为3zSS7zIcfkiy4HEOmt4Ba83xNOiXcukl

为应用账户申请流程服务能力的访问权限

以开发者角色登录平台，在能力详情-能力搜索标签页面找到想要使用的流程服务能力，可通过页面上不同类别快速搜索定位能力，在找到能力后点击查看按钮。

点击按钮进入能力详情页面后，点击访问权限标签并找到想要申请授权的应用账户，在权限框中打钩并点击申请，管理员审核通过后授权成功，授权成功后，每当进入流程服务能力，权限框下打钩即表明此应用账户已有流程服务的使用权限。

基础使用方法

应用开发中流程服务能力的基础使用方法有：

1，创建（发起）流程事项，成功后可以获取流程事项的唯一编码(job_key)，后续可通过该编码作为参数使用相应服务查询该事项的流程信息或提交表单。

2，以事项编码作为参数查询流程当前环节信息或流程业务信息。

3，在当前环节提交业务表单来驱动流程引擎，流程将按规则自动跳转。

创建流程事项

说明

使用流程服务能力的第一步，创建具体的流程事项。在本例中，流程事项为报销申请，成功后接口将返回事项编号，后续作为操作该事项的唯一标识。

接口示例

URL格式：http://localhost:3001/pes/system  // 请将localhost替换为服务器主机IP
请求方法： <HTTP> POST

Header

TD-Charset: utf-8
TD-Account: new_version
TD-Timestamp: 1649642875794
TD-Authorization: 378c5194c4ba5b6faff1a961d892a741
TD-Topic: $META/PES/JobMgmt

参数说明：

TD-Account：需要填入应用账户名称,在本例中为new_version

TD-Timestamp：填入当前时间的时间戳，长度为13位

TD-Authorization：填入利用对应用账户+令牌+当前时间时间戳组合成的字符串利用MD5加密后得出的32位小写的字符串。在本例中为MD5(new_version3zSS7zIcfkiy4HEOmt4Ba83xNOiXcukl1649642875794)即378c5194c4ba5b6faff1a961d892a741

TD-Topic：固定填写$META/PES/JobMgmt

Body(请求体)

{
    "project_token": "PES",
    "event": "JobMgmt",
    "properties": {
        "process_key": "ProcessDemo/ExpAccount", 
        "job_mgmt_op": "create",
        "job_name": "报销申请内网new3",
        "job_desc": "出差费用报销申请内网new3"
    },
    "timestamp": 1636699890094
}

参数说明：

process_key：流程的唯一编号(可在能力详情-访问权限中的接口路径查看)

job_mgmt_op：操作符，固定填写create

job_name：事项名称

job_desc：事项的描述信息

timestamp：当前时间戳，13位

其余参数为系统参数，固定填写

Response

{
    "code": 0,
    "data": [
        {
            "_sys_write_time": 1649661200988960,
            "job_create_time": 1649661200988,
            "job_creator": 1001,
            "job_desc": "出差费用报销申请内网new3",
            "job_key": "dc75fffd-290d-4bd7-97ed-cd4cb597b9a6",
            "job_name": "报销申请内网new3",
            "job_status": "created",
            "job_update_time": 1649661200988,
            "process_key": "ProcessDemo/ExpAccount"
        }
    ],
    "msg": "[OK]:success"
}

参数说明：

code：请求状态码，0为成功

msg：请求状态，成功返回[DACE_OK]:success，失败则返回失败原因。

data：请求成功后，返回信息。

job_update_time：事项更新时间

job_desc：事项描述信息

job_creator：事项创建人ID

job_create_time：事项创建时间

job_key：事项唯一编号，后续其他对于本事项的操作要以此为标识

process_key：流程唯一编号

job_status：事项的状态，创建成功时状态为created，事项全部流转结束后状态为completed。

job_name：事项名称

查询当前环节

说明

创建事项成功后，事项将会按照流程服务能力中的流程模型开始流转，流转至需要提交表单的环节时，才会停下等待表单提交，比如在本例中，创建待办事项成功后，事项会流转至提交报销申请。可以通过接口查询事项中的环节信息(此文档展示的是流程引擎文档中2.5.4的查询功能即查询事项的所有流转信息)。

接口示例

URL格式：http://localhost:3001/pes/data    // 请将localhost替换为当前服务器主机IP
请求方法： <HTTP> POST

Header

Content-Type: application/json
TD-Topic: $META/PES/JobMgmt
TD-Account: new_version
TD-Timestamp: 1649642875794
TD-Authorization: 378c5194c4ba5b6faff1a961d892a741

参数说明：

Content-Type 和 TD-Topic在查询功能中固定按上方内容填写。

TD-Account：需要填入应用账户名称,在本例中为new_version

TD-Timestamp：填入当前时间的时间戳，长度为13位

Body(请求体)

{
    "project_token": "SLUIS_SYNC",
    "event": "Request",
    "timestamp": 1644982456271,
    "properties": {
        "version": "v1.0",
        "sp_name": "sp1",
        "request_type": "total",
        "resource_uri": "$META/ProcessDemo/ExpAccount",
        "condition": [{"attr_name": "process_key", "op_type": "=", "attr_val": "ProcessDemo/ExpAccount", "set_op": "AND"},
                      {"attr_name": "job_key", "op_type": "=", "attr_val": "dc75fffd-290d-4bd7-97ed-cd4cb597b9a6", "set_op": "NAN"}]
    }
}

参数说明：

主要关注properties里condition中的attr_val，这里需要填写在创建事项时，返回的事项唯一编号即job_key和流程能力的唯一编号process_key。resource_uri也需要根据process_key修改META后的内容，其余为系统字段，固定填写。

Response

{
    "ack_code": "1",
    "ack_reason": "success",
    "data": [
        {
            "process_key": "ProcessDemo/ExpAccount",
            "node_ext_info": "",
            "to_node": "EIdbOeDpErZZVPll",
            "job_key": "dc75fffd-290d-4bd7-97ed-cd4cb597b9a6",
            "form_status": "finished",
            "current_node": "start_node",
            "step_id": 1
        },
        {
            "process_key": "ProcessDemo/ExpAccount",
            "write_mode": "submit",
            "node_ext_info": "",
            "job_key": "dc75fffd-290d-4bd7-97ed-cd4cb597b9a6",
            "node_ext_info": "{\"node_perm\": [{\"department\": \"研发部\",\"role\": \"申请人\",\"perm\": [\"提交申请\"]},
            "form_status": "waiting_submit",
            "current_node": "EIdbOeDpErZZVPll",
            "from_node": "start_node",
            "step_id": 2
        }
    ]
}

参数说明：

ack_code：请求状态码，"1"为成功

ack_reason：请求状态，成功返回success，失败则返回失败原因。

process_key：流程唯一编号

write-mode: 表单数据写模式，第三方应用在提交表单时，必须要填写此字段，取值有submit、edit、revise；submit表示提交表单后，驱动流程实例流转；edit表示对流程实例当前环节数据进行修改，不驱动流程实例继续流转；revise表示修改流程实例流转时的历史数据。

job_key：事项唯一编号

node_ext_info：应用自定义额外信息。在本例中以JSON格式定义了当前节点的权限信息，其中“node_perm”标志该对象为权限信息，该对象的值为数组，数组中每个对象对应着一个权限，其中“department”为部门，“role”为角色，“perm”为操作权限。

form_status: 表单状态，取值有 init、 processing、 waiting_submit、 deprecated、 finished、 completed。在流程流转时，系统会将当前表单流转状态写入表中，第三方应用可以通过查询此值，判断流程实例目前状态，详情请查看流程引擎文档2.4.1章节。

current_node：当前环节在流程图中的编号

from_node：来源节点，当流程实例流转到某一节点时，会将上一个节点的ID写入此值。

step_id：当前环节ID，后续进行提交当前环节的表单时需要用到job_key和step_id作为唯一标识

负责人提交表单

说明

当流程流转到某个环节时，该环节的负责人提交表单来使事项继续按照流程进行流转。下面分别以提交报销申请和部门经理审核两个环节举例负责人提交表单的操作。

接口示例

Url（两个环节是一样的）

URL格式：http://localhost:3001/pes/data    // 请将localhost替换为服务器主机IP
请求方法： <HTTP> POST

Header（两个环节是一样的）

TD-Charset: utf-8
TD-Account: new_version
TD-Timestamp: 1649642875794
TD-Authorization: 378c5194c4ba5b6faff1a961d892a741
TD-Topic: $META/ProcessDemo/ExpAccount

参数说明：

TD-Account：需要填入应用账户名称,在本例中为ExpAccountApp

TD-Timestamp：填入当前时间的时间戳，长度为13位

TD-Topic：$META/+process_key，本例process_key为ProcessDemo/ExpAccount

Body（提交报销申请环节）

{
    "project_token": "ProcessDemo",
    "event": "ExpAccount",
    "properties": {
        "process_key": "ProcessDemo/ExpAccount", 
        "job_key": "dc75fffd-290d-4bd7-97ed-cd4cb597b9a6",
        "step_id": 2,
        "write_mode": "submit"
},
    "timestamp": 1536850292000
}

参数说明：

project_token：表单模型的项目名，在本例中为ProcessDemo

event：表单模型的模型名，本例中为ExpAccount

process_key：流程的唯一编号

job_key：事项唯一编号

step_id：当前环节ID,常用的模式是配合查询当前环节功能来使用，结合流程图和环节信息来驱动流程服务能力。

timestamp：当前时间的时间戳，13位

Body（部门经理审核环节）

{
    "project_token": "ProcessDemo",
    "event": "ExpAccount",
    "properties": {
        "process_key": "ProcessDemo/ExpAccount", 
        "job_key": "6aee8349-03e5-4e57-894d-43372e0ec8fa",
        "step_id": 3,
        "reviewer_result": "审核通过",
        "write_mode": "submit"
},
    "timestamp": 1536850292000
}

参数说明：

project_token：表单模型的项目名，即process_key以/符号分隔的第一部分，在本例中为ProcessDemo

event：表单模型的模型名，即process_key以/符号分隔的第二部分，本例中为ExpAccount

process_key：流程的唯一编号

job_key：事项唯一编号

step_id：当前环节ID

reviewer_result：负责人处理结果，流程会根据这个字段的值进行流转，这个字段在创建流程模型时进行配置。在此处填写审批通过则事项会流转到财务拨款，填写审批不通过则会流转到结束，本事项流转结束。

timestamp：当前时间的时间戳，13位

Response（两个环节是一样的）

{
    "code": 0,
    "msg": "[DACE_OK]:success"
}

参数说明：

code：请求状态码，0为成功

msg：请求状态，成功返回[DACE_OK]:success，失败则返回失败原因。

3-2 用例二：并行的审批流

考虑如下情形：

某报销流程由A、B两个部门协作完成，员工在提交申请后需要有A、B两个部门的两个经理都审批通过后申请才有效，流程图如下：

需要先对流程表单进行建模，建模信息如下（已省略系统字段）：

字段	含义	类型
applicant_name	申请人名称	字符串
amount	报销金额	数值
reviewer	部门审批人	层级字典
reviewer_result	审批结果	层级字典

接着，需要编辑流程拓扑，将上述流程图编辑出来，并在各个流程环节上编辑流转规则。其中，并行审批 与合并是实现并行审批流的两个关键环节。

并行审批环节配置

对上述情形的并行审批网关进行配置时，需要将分流至A部门经理审批与B部门经理审批的条件均成立。

合并环节配置

对上述情形的合并网关进行配置时，需要满足两个条件，一是A、B部门的部门经理都审批过此申请，二是两个部门经理都审核通过了且表单中的审批结果字段值为通过。

为清晰整个流程，以下会具体介绍一个完成且成功的报销申请审批通过后经历的步骤：

步骤1：流程开始，到达“开始”节点。

步骤2：从开始节点流转到了“提交报销申请”节点。

步骤3：从“提交报销申请”节点至“并行审批”节点。

步骤4：流程并行并分流到第一条边，到达“A部门经理审批”节点，等待部门经理A审批。

步骤5：流程并行并分流到第一条边，到达“B部门经理审批”节点，等待部门经理B审批。

步骤6：部门经理A审批后，节点从“A部门经理审批”流转到“合并”网关节点，发现未满足合并网关条件，因为在合并网关等待。

步骤7：部门经理B审批后，节点从“B部门经理审批”流转到“合并”网关节点等待。

步骤8：通过步骤6,7，发现满足合并网关的条件：即两个部门经理都审批了，且审批都通过，触发合并。

步骤9：从“合并”网关节点流转至“审批结果”排他网关。

步骤10：因为合并后表单里面带有“审批通过”的字段，流程从“审批结果”节点流转至“财务拨款”节点。

步骤11：流程从”财务拨款“节点流转至结束节点，流程至此结束。共11步。

以下会贴出流程关键步骤的截图以供参考：

请注意，此并行了流程的并行网关勾选了”无条件并行“按钮，因此只要在步骤2提交了表单，经过并行网关后，流程一定会分成两个子流程并行运行。

如下图所示，步骤4和步骤5分并行出来的两个子流程，他们各自在”A部门经理审批“和”B部门经理审批“节点等待审批。

当部门A经理审批过后，也就是步骤4，此步骤的状态会从等待变成完成"finished"，子流程流转到步骤6-也就是合并网关节点，因为不满足合并条件，所以子流程会在合并网关节点等待合并，所以步骤6此时会变成运行中(processing)的状态，而另一个子流程因为部门B经理还未审批故还在等待提交状态，如下所示。

当B部门经理提交审核后，满足了合并的要求，此时步骤6-合并网关检查配置并确保此时满足了合并的要求，流程继续流转，而合并节点的状态也会变成已完成(finished)。

四、附录

4-1 接口规范

流程系统服务接口规范

接口协议：HTTP  
请求方法：POST  
请求端口：3001
请求URL：/pes/system

HTTP Header参数及取值

参数	取值	说明
TD-Account	通过授权的应用账户名	接口校验用的应用账户
TD-Timestamp	13位的当前时间戳	当前时间
TD-Authorization	MD5({TD-Account}+{应用账户token}+{TD-Timestamp})	用于接口校验
TD-Topic	$META/PES/JobMgmt	固定值，流程系统服务话题路径

HTTP Body参数及取值

参数	取值	类型	说明	是否必填
project_token	PES	字符串	固定值	是
event	JobMgmt	字符串	固定值	是
timestamp	13位的当前时间戳	时间戳	当前时间	是
properties	json对象	json	标识当前操作、操作对象、参数等信息，详见下方properties参数及取值	是

properties参数及取值

参数	取值	类型	说明	是否必填
process_key	流程模型唯一标识	字符串	操作的流程模型唯一标识	是
job_name	流程实例名称	字符串	自定义流程实例名称	是
job_desc	流程实例描述信息	字符串	自定义流程实例描述信息	否
job_init_data	json对象	json	初始化流程表单数据，详见本文档2.3.3章节	否

示例

POST /pes/system HTTP/1.1
Host: localhost:3001
TD-Topic: $META/PES/JobMgmt
TD-Timestamp: [当前unix时间戳]
TD-Authorization: [用户名加TOKEN加时间戳的HMAC计算值]
TD-Account: [用户名]
Content-Type: application/json

{
    "project_token": "PES",
    "event": "JobMgmt",
    "timestamp": 1648452767998,
    "properties": {
        "job_mgmt_op": "create",
        "process_key": "ProcessDemo/ExpAccount",
        "job_name": "测试任务",
        "job_init_data": "{\"project_token\":\"ProcessDemo\",\"event\":\"ExpAccount\",\"timestamp\":1643527646953,\"properties\":{\"assignee\":\"A\"}}"
    }
}

HTTP Response

参数	值	类型	说明
code	错误码	数值	成功时为0，其余为错误
msg	错误信息	字符串	错误详细信息
data	系统返回信息	json数值	成功时才会返回该字段，字段为json数组，数组一般只有一个元素，元素内容如下解析

data字段解析

参数	值	类型	说明
_sys_write_time	系统时间戳	时间戳	系统时间
job_update_time	流程实例更新时间戳	时间戳	流程实例更新时间
job_create_time	时间戳	时间戳	流程实例创建时间
job_creator	流程实例创建	字符串	流程实例创建应用账户
job_key	流程实例唯一标识	字符串	系统生成的流程实例唯一标识
job_name	流程实例名称	字符串	流程实例名称
job_status	create	字符串	流程实例状态
process_key	流程模型唯一标识	字符串	流程模型唯一标识

示例：

{
    "code": 0,
    "msg": "[OK]:success",
    "data": [
        {
            "_sys_write_time": 1648714819627053,
            "job_update_time": 1648714819626,
            "job_create_time": 1648714819626,
            "job_creator": 1,
            "job_key": "d7c900e1-bf50-40a0-92be-0cfddd29c64d",
            "job_name": "报销流程",
            "job_status": "created",
            "process_key": "ProcessDemo/ExpAccount"
        }
    ]
}

流程数据服务接口规范

1. 操作接口

接口协议：HTTP  
请求方法：POST  
请求端口：3001 
请求URL：/pes/data

HTTP Header参数及取值

参数	取值	说明
TD-Account	通过授权的应用账户名	接口校验用的应用账户
TD-Timestamp	13位的当前时间戳	当前时间
TD-Authorization	MD5({TD-Account}+{应用账户token}+{TD-Timestamp})	用于接口校验
TD-Topic	$META/{流程表单项目名}/{流程表单模型名}	指定流程表单的项目和模型

HTTP Body参数及取值

参数	取值	类型	说明	是否必填
project_token	流程表单项目名	字符串	操作的流程模型对应的流程表单项目名	是
event	流程表单模型名	字符串	操作的流程模型对应的流程表单模型名	是
timestamp	13位的当前时间戳	时间戳	当前时间	是
properties	json对象	json	标识当前操作、操作对象、参数等信息，详见下方properties参数及取值	是

properties参数及取值

参数	取值	类型	说明	是否必填
process_key	流程模型唯一标识	字符串	操作的流程模型唯一标识	是
step_id	流程步骤	数值	自定义流程实例名称	是
job_key	流程实例唯一标识	字符串	自定义流程实例描述信息	是
write_mode	submit、edit、revise	字符串	写入模式，详见第2.1.1、2.4章节	是
流程流转字段	开发者在配置流程模型时决定		若在配置流程模型时有配置，则必填，否则可以选填	否
其他业务字段	有开发者自行设计

示例

POST /pes/system HTTP/1.1
Host: localhost:3001         // 请将localhost替换为服务器主机IP
TD-Topic: $META/PES/JobMgmt
TD-Timestamp: [当前unix时间戳]
TD-Authorization: [用户名加TOKEN加时间戳的HMAC计算值]
TD-Account: [用户名]
Content-Type: application/json

{
    "project_token": "ProcessDemo",
    "event": "ExpAccount",
    "timestamp": 1530178791371,
    "properties": {
        "process_key": "ProcessDemo/ExpAccount",
        "step_id": 2,
        "job_key": "xxxx-xxxx...",
        "write_mode": "submit",
        "attr1": "v1",
        "attr2": "v2",
        ...
    }
}

HTTP Response

参数	值	类型	说明
code	错误码	数值	成功时为0，其余为错误
msg	错误信息	字符串	错误详细信息

HTTP Response示例：

{
    "code": 0,
    "msg": "[OK]:success"
}

2.查询接口

接口协议：HTTP  
请求方法：POST  
请求端口：3001 
请求URL：/pes/data

HTTP Header参数及取值

参数	取值	说明
TD-Account	通过授权的应用账户名	接口校验用的应用账户
TD-Timestamp	13位的当前时间戳	当前时间
TD-Authorization	MD5({TD-Account}+{应用账户token}+{TD-Timestamp})	用于接口校验

HTTP Body参数及取值

参数	取值	类型	说明	是否必填
project_token	SLUIS_SYNC	字符串	固定值	是
event	Request	字符串	固定值	是
timestamp	13位的当前时间戳	时间戳	当前时间	是
properties	json对象	json	标识当前操作、操作对象、参数等信息，详见下方properties参数及取值	是

properties参数及取值

参数	取值	类型	说明	是否必填
version	v1.0	字符串	固定值	是
sp_name	sp1	字符串	固定值	是
condition	条件三元组数组	数组	条件组合，详见2.5.1	是
request_type	可取值paging、count、total	字符串	paging分页模式，需要配合page_id、page_size使用。count总计，即会返回当前符合条件有多少条记录。total返回所有记录	是
page_id	分页时的页码	数值	制定页码	否
page_size	每页数量	数值	单页取数数目	否
event_type	STATE	字符串	固定值	是
resource_uri	$META/{表单项目名}/{表单模型名}	字符串	按照表单模型不同取不同值	是
order_by_mode	ASC(升序)、DESC(降序)	字符串	对返回结果进行排序，需要配合order_by_keys使用	否
order_by_keys	升序或降序依据的字段名	数组	排序依据字段	否

示例

POST /pes/system HTTP/1.1
Host: localhost:3001        // 请将localhost替换为服务器主机IP
TD-Topic: $META/PES/JobMgmt
TD-Timestamp: [当前unix时间戳]
TD-Authorization: [用户名加TOKEN加时间戳的HMAC计算值]
TD-Account: [用户名]
Content-Type: Application/json

{
    "project_token": "SLUIS_SYNC",
    "event": "Request",
    "timestamp": 1646045981606,
    "properties": {
        "version": "v1.0",
        "sp_name": "sp1",
        "request_type": "paging",
        "page_id": 0,
        "page_size": 2,
        "order_by_mode": "DESC",
        "event_type": "STATE",
        "resource_uri": "$META/QMJYYXX/MJYYQK",
        "order_by_keys": [
            "step_id"
        ],
        "condition": [
            {
                "attr_name": "process_key",
                "op_type": "=",
                "attr_val": "QMJYYXX/MJYYQK",
                "set_op": "AND"
            },
            {
                "attr_name": "job_key",
                "op_type": "=",
                "attr_val": "12b38aa2-920b-463b-a4b1-b9a033e7c0a1",
                "set_op": "NAN"
            }
        ]
    }
}

HTTP Response

参数	值	类型	说明
code	错误码	数值	成功时为1，其余为错误
msg	错误信息	字符串	错误详细信息
data	流程表单所有信息	json数组	数组中一个json元素便是一条记录

HTTP Response示例：

{
    "ack_code": "1",
    "ack_reason": "success",
    "data": [
        {
            "job_key": "8315b3d2-bd06-46c9-a87b-636c3ac32806",
            "process_key": "ProcessDemo/ExpAccount",
            "step_id": "2",
            "reviewer": "申请人",
            "reviewer_result": "提交审批",
            "applicant_name": "张三",
            "amount": "1229.0"
        }
    ]
}

流程用户服务接口规范

接口协议：HTTP  
请求方法：POST  
请求端口：3001
请求URL：/Pes/pes/idm

HTTP Header参数及取值

参数	取值	说明
TD-Account	通过授权的应用账户名	接口校验用的应用账户
TD-Timestamp	13位的当前时间戳	当前时间
TD-Authorization	MD5({TD-Account}+{应用账户token}+{TD-Timestamp})	用于接口校验
TD-Topic	$META/PESEXT/{管理接口名}	管理接口名根据接口类型取值，可取指为User、UserGroup、Role

HTTP Body参数及取值

参数	取值	类型	说明	是否必填
project_token	PESEXT	字符串	固定值	是
event	管理接口名	字符串	User、UserGroup、Role	是
timestamp	13位的当前时间戳	时间戳	当前时间	是
properties	json对象	json	标识当前操作、操作对象、参数等信息，详见各个小节中properties参数及取值	是

示例

POST /pes/idm HTTP/1.1
Host: localhost:3001
Content-Type: application/json
TD-Timestamp: [当前unix时间戳]
TD-Authorization: [用户名加TOKEN加时间戳的HMAC计算值]
TD-Account: [用户名]
TD-Charset: utf-8
TD-Topic: $META/PESEXT/User

{
  "project_token": "PESEXT",
  "event": "User",
  "timestamp": 1536850292000,
  "properties": {
    "mgmt_op": "user_add",
    "user_key": "user0",
    "user_name": "路人0"
  }
}

HTTP Response

参数	值	类型	说明
code	错误码	数值	成功时为0，其余为错误
msg	错误信息	字符串	错误详细信息

HTTP Response示例：

{
    "code": 0,
    "msg": "[OK]:success"
}

用户待办接口规范

接口协议：HTTP  
请求方法：POST  
请求端口：3001 
请求URL： Daas/sp1/bms

HTTP Header参数及取值

参数	取值	说明
TD-Account	通过授权的应用账户名	接口校验用的应用账户
TD-Timestamp	13位的当前时间戳	当前时间
TD-Authorization	MD5({TD-Account}+{应用账户token}+{TD-Timestamp})	用于接口校验

HTTP Body参数及取值

参数	取值	类型	说明	是否必填
project_token	SLUIS_SYNC	字符串	固定值	是
event	Request	字符串	固定值	是
timestamp	13位的当前时间戳	时间戳	当前时间	是
properties	json对象	json	标识当前操作、操作对象、参数等信息，详见各个小节中properties参数及取值	是

properties部分参数及取值

参数	取值	类型	说明	是否必填
event_type	STATE	字符串	固定值	是
request_type	total、pagging、count	字符串	请求类型，分别有total（全量）、pagging（分页）、count（总计）	是
version	v1.0	字符串	固定值	是
sp_name	sp1	字符串	固定值	是
resource_uri	根据接口不同，取值也不同	字符串	接口唯一标识	是
condition	json数组	json数组	与SQL类似的语法，数组中一个json对象为一个条件，详细可看condition取值及说明	是

condition取值及说明

参数	取值	类型	说明	是否必填
attr_name	字段名	字符串	需要查询的字段名	是
attr_val	字段值	字符串	需要查询的值	是
op_type	=、>、<、!=	字符串	操作符	是
set_op	AND、OR、NAN	字符串	多个条件间的连接符，可参考SQL	是

示例（通过流程+用户的方式过滤待办信息）

POST /Daas/sp1/bms HTTP/1.1
Host: localhost:3001            // 请将locahost替换为服务器主机IP
Content-Type: application/json
TD-Timestamp: [当前unix时间戳]
TD-Authorization: [用户名加TOKEN加时间戳的HMAC计算值]
TD-Account: [用户名]
TD-Charset: utf-8

{
    "event": "Request",
    "project_token": "SLUIS_SYNC",
    "properties": {
        "condition": [
            {
                "attr_name": "process_key",
                "attr_val": "75_test222/Form",
                "op_type": "=",
                "set_op": "AND"
            },
            {
                "attr_name": "user_key",
                "attr_val": "test",
                "op_type": "=",
                "set_op": "NAN"
            }
        ],
        "event_type": "STATE",
        "request_type": "total",
        "resource_uri": "$META/PESEXT/ListTodo",
        "sp_name": "sp1",
        "version": "v1.0"
    },
    "timestamp": 1645955496
}

通过以上请求方式获取待办的语义是：获取当前流程下属于该用户的所有待办信息列表

HTTP Response

参数	值	类型	说明
code	错误码	数值	成功时为1，其余为错误
msg	错误信息	字符串	错误详细信息
data	json数组	数组	根据接口不同，返回的数据不同，祥见各个小节data详细信息

HTTP Response示例：

{
    "ack_code": "1",
    "ack_reason": "success",
    "data": [
        {
            "current_node": "DOEprrougxhQZGAn",
            "form_status": "waiting_submit",
            "from_node": "start_node",
            "job_key": "3c46ed76-1c04-4d65-b70a-1bb3d6f98e37",
            "node_ext_info": "",
            "process_key": "75_test222/Form",
            "step_id": 1,
            "to_node": null,
            "write_mode": "edit"
        },
        {
            "current_node": "DOEprrougxhQZGAn",
            "form_status": "waiting_submit",
            "from_node": "start_node",
            "job_key": "4d8d3f0d-1d48-4d83-a368-e4cfc2168c2e",
            "node_ext_info": "",
            "process_key": "75_test222/Form",
            "step_id": 1,
            "to_node": null,
            "write_mode": null
        }
    ]
}

4-2 接口返回代码表

4-2-1 提交表单返回代码表

代码	代码描述	说明
0	DACE_OK	消息发送成功
1	DACE_RESOURCE_ERROR	请求url资源不存在
2	DACE_RUNTIME_ERROR	解析出错
3	DACE_USER_ERROR	用户信息错误
4	DACE_PERM_ERROR	用户权限不足
5	DACE_PATH_ERROR	消息话题不存在
6	DACE_JSON_ERROR	消息格式不正确
7	DACE_PATH_EMPTY	header中没有指定消息话题
8	DACE_DATA_OVER_LENGTH	消息内容(body)过长(大于5m)
9	DACE_PILE_SIZE_ERROR	pile数组大小错误
10	DACE_PILE_SIZE_PARSE_ERROR	pile数组大小解析错误
11	DACE_PILE_SIZE_NOT_MATCH	pile数组大小与实际消息不符
12	DACE_PILE_JSON_ERROR	pile消息体格式错误
13	DACE_SERVICE_BUSY	服务繁忙，稍候重试
14	DACE_PERSIST_ERROR	持久化错误
15	DACE_COMPRESS_METHOD_ERROR	解压方式不支持
16	DACE_COMPRESSION_ERROR	解压错误
17	DACE_TRANSCODE_NOT_SUPPORT	转码方式不支持
18	DACE_TRANSCODE_ERROR	转码错误
19	DACE_FROM_BRIDGE_NOT_FOUND	未找到桥接信息
20	DACE_BRIDGE_INFO_ERROR	桥接信息错误
21	DACE_HTTP_METHOD_ERROR	请求方法错误
22	DACE_FORBIDDEN	禁止访问
23	DACE_INVALID_STATE_OP	状态操作不支持
1000	DACE_CTRL_NOT_FOUND	未找到管理命令类型
1001	DACE_CTRL_TYPE_ERROR	管理命令类型不支持

4-2-2 流程驱动返回代码表

代码	代码描述	说明
0	PEDSCE_OK	操作成功
1	PEDSCE_RESOURCE_ERROR	无法解析请求
2	PEDSCE_RUNTIME_ERROR	运行时错误/系统内部错误
9	PEDSCE_HTTP_METHOD_ERROR	http请求方法错误
10	PEDSCE_HTTP_BODY_ERROR	http请求体错误
21	PEDSCE_HTTP_BODY_PROCESS_KEY_NOT_FOUND	找不到http请求体中的流程图ID
22	PEDSCE_HTTP_BODY_JOB_KEY_NOT_FOUND	找不到http请求体中的事项编号
23	PEDSCE_HTTP_BODY_STEP_ID_NOT_FOUND	找不到http请求体中的流程环节id
25	PEDSCE_CHECK_JOB_STEP_RUNTIME_ERROR	查询事项状态失败
26	PEDSCE_JOB_STEP_NOT_MATCH	流程环节与当前流程不匹配
28	PEDSCE_PROCESS_NOT_FOUND	未找到关联的流程
31	PEDSCE_CURRENT_NODE_NOT_FOUND	无法在流程中找到当前节点
32	PEDSCE_CURRENT_STEP_ID_NOT_FOUND	无法再流程中找到当前环节ID
38	PEDSCE_JOB_STEP_LOCKED	指定流程环节正在被提交，请稍后重试
39	PEDSCE_WRITE_DATA_FAILED	写入表单失败
40	PEDSCE_JOB_NOT_RUNNING	无法找到流程实例或未运行

4-3 常见问题

提交表单，请求体头部TD-Topic里模型主题带有中文字段。

如下图所示，流程接口路径若包含中文则会提示错误。

解决方法：将TD-Topic改成TD-UrlEn-Topic，然后通过Url编码工具(可以在网上搜索到)将带有中文的流程接口路径进行Component编码方式。再填入请求头即可。转换后的请求头如下：

产品介绍

服务列表

产品文档

关于我们

一、总体介绍

二、功能介绍

2-1 管理应用账号

2-1-1 基本概念

2-1-2 新建应用账号

2-2 流程用户服务

2-2-1 基本概念

2-2-3 查看流程用户

2-3 流程用户接口

2-3-1 基本概念

2-3-2 同步流程用户

2-3-3 维护流程用户

2-3-4 查询用户待办

2-4 流程模型编辑

2-4-1 基本概念

2-4-2 流程表单

2-4-3 流程拓扑

2-4-4 编辑负责人

2-4-5 表单权限

2-4-6 流转规则

2-5 流程模型加载

2-5-1 流程上线

2-5-2 流程下线

2-6 流程实例发起

2-6-1 基本概念

2-6-2 流程实例发起

2-6-3 预设表单信息

2-7 流程实例生命周期管理

2-7-1 流程实例信息修改

2-7-2 流程实例暂停与恢复

2-7-3 流程实例撤销

2-8 流程实例驱动

2-8-1 基本概念

2-8-2 提交表单

2-8-2-1 查询流程实例状态

2-8-2-2 提交表单驱动流程实例

2-8-3 表单编辑

2-8-4 并行驱动

2-8-5 正确性校验

2-8-6 流转通知

2-8-7 node_ext_info使用

2-9 流程实例查询

2-9-1 基本概念

2-9-2 查询进行中流程实例

2-9-3 查询已完成流程实例

2-9-4 查询流转记录

2-9-5 条件组合查询

2-10流程实例安全访问

2-10-1 安全限制

2-10-2 安全配置

2-11 流程引擎可靠性

2-11-1 意外重启恢复

三、实践用例

3-1 用例一：简单的审批流

3-2 用例二：并行的审批流

四、附录

4-1 接口规范

流程系统服务接口规范

流程数据服务接口规范

流程用户服务接口规范

用户待办接口规范

4-2 接口返回代码表

4-2-1 提交表单返回代码表

4-2-2 流程驱动返回代码表

4-3 常见问题

results matching ""

No results matching ""