Merge pull request #543 from hanshuaikang/feature/develop_by_han

Feature/develop by han

docs/wiki/access.md

@@ -0,0 +1,99 @@
+# 第三方系统对接ITSM 指南
+
+## 前提：
+
+在对接ITSM之前，请确保你已经可以熟练的使用ITSM创建属于自己的服务并可以正常提单，确保你对ITSM流程，服务，触发器，API 有了一个最基本的认识，如果使用过程中发现没有权限，则需要申请权限之后再使用。
+
+在 2.6.0 + 之上的版本，我们强烈的建议您创建一个专属的项目用于存放您系统涉及到的服务，字段，触发器以及API。这样更加容易管理。如果创建到默认项目下，您的服务会和其他的系统的服务混合在一起。
+
+在创建好您的服务之后，剩下的就是两个系统之间的交互了。如果您使用的是蓝鲸企业版or社区版，则需要使用ESB进行交互。如果您是内部版接入，这边建议您使用网关接入的方式。但不管使用哪种方式接入，都需要`app_code` 和 `app_secret` 进行权限认证。如果您的应用不是蓝鲸体系内的，比如您自己开发的第三方独立应用。则需要先在蓝鲸上创建一个应用，之后申请您所需要的接口的权限。用这个应用的 `app_code` 和 `app_secret`  进行认证。
+
+## 对接 ITSM 会需要的接口:
+
+对接ITSM，您一定会使用到的接口有`create_ticket`和`ticket_approval_result` 和`get_ticket_status`
+
+### create_ticket:
+
+对于创建单据接口而言，这里主要回答两个问题。
+
+#### 关于回调:
+
+**我如何指定回调链接，已经回调的规则是什么？**
+
+答：您可以在通过接口提单时，指定meta.callback_url 来指定您的`callback_url`。如下格式:
+
+```json
+	"meta": {
+		"callback_url": "http://***"
+	}
+```
+
+问题：**回调什么时候发生？**
+
+答: 单据正常结束都会触发回调，例如 单据被终止，被撤销，正常结束，都会触发回调。
+
+问题：**某个节点结束之后会回调告诉我这个节点执行结束了吗？比如审批结果**。
+
+答: 不会，回调只会在单据结束的时候执行，并且只会执行一次。如果需要在节点执行结束之后执行回调。那么可以配置全局触发器[API执行]解决这个问题。
+
+问题：**回调支持重试吗，或者说有重试机制吗？**
+
+答：回调只会触发一次。并没有重试，回调失败的单据会被记录，可以通过`callback_failed_ticket`接口查询。
+
+问题：**作为我的系统接受回调的接口，返回协议有要求吗?**
+
+答：有，要求您的接口尽量返回蓝鲸标准协议的结构，如下:
+
+```json
+{
+	"message": "success",
+	"code": 0,
+	"data": null,
+    "result": true
+}
+```
+
+问题：**回调的格式是什么？**
+
+答: 回调的方式为POST。参数格式为Json. 需要你的接口不校验登陆态。
+
+```json
+{
+	"title": "标题",
+	"current_status": "当前状态，为FINISHED为正常结束",
+	"sn": "单号",
+	"ticket_url": "单据链接",
+	"update_at": "单据更新时间",
+	"updated_by": "单据更新人",
+	"approve_result": "单据审批结果True or False",
+	"token": "token",
+	"last_approver": "最后一个节点的审批人",
+}
+```
+
+问题：`approve_result`的计算规则是什么样的？
+
+答: 单据的审批结果要求流程内所有的审批节点都为通过才会为通过。例如第一个审批节点被拒绝了，但是后面几个审批节点都被通过了。那么该单据的审批结果为`False`
+
+问题：**token的作用是什么?**
+
+答：为了使您的系统可以确认回调来自于ITSM，而不是第三方伪造的。拿到`token`您可以请求`token_verify`接口校验`token`是否来源于ITSM.
+
+#### 关于指定某个节点的处理人：
+
+关于如何指定某个节点的处理人，这里一共有两种方式:
+
+1. 在提单节点新增人员选择器类型的字段，然后在审批节点设置处理人为引用变量。提单的时候将审批人作为人员选择器字段的value即可。(审批节点比较少，比较推荐)
+2. 提单的时候指定meta.state_processers 即可指定某个节点的审批人:
+
+```python
+	"meta": {
+		"state_processors": {
+			"407": "xxx,xxxx"
+		}
+	}
+```
+
+答: 如果您只是固定对接环境。可以在前端f12 获取到某个节点的id(这点后期会优化) 或者调用`get_service_roles` 接口获取这个服务下所有的节点列表。然后根据`name`匹配到节点ID。注意，根据此种方式则意味着，您的节点name将不能再有变化。
+
+

readme.md

@@ -41,6 +41,7 @@ ITSM (IT 服务管理)是一套帮助企业对 IT 系统的规划、研发、实
 - [企业微信移动端配置说明](docs/install/qy_weixin_config.md)
 - [自定义表单渲染规则说明](docs/install/custom_form_config.md)
 - [API请求沙箱使用说明](docs/install/api_sandbox_guide.md)
+- [ITSM 接入指引](docs/wiki/access.md)
 
 ## Version plan
 - [版本日志](docs/RELEASE.md)

readme_en.md

@@ -41,6 +41,7 @@ ITSM is an upper layer SaaS application based on the Tencent Blueking product sy
 - [WeCom Configuration Instructions](docs/install/qy_weixin_config.md)
 - [Custom Form Rendering Rules Instructions](docs/install/custom_form_config.md)
 - [API_Request_Sandbox_Instructions](docs/install/api_sandbox_guide.md)
+- [ITSM Access Guidelines](docs/wiki/access.md)
 
 ## Version plan
 - [RELEASE](docs/RELEASE_EN.md)

requirements_open.txt

@@ -3,4 +3,4 @@
 # 请确保指定的包和版本号，通过pip安装
 
 #blueapps
-blueapps==4.1.0rc0
+blueapps==4.1.2