====功能介绍====
工单外部扩展，指的是工单自定义字段中的两种字段类型（文本，资产表）可支持数据源来自于第三方，及绑定帮我吧客户档案的资产表的数据，然后赋值到工单中，使得工单满足多方对接。对接类型有两大类，一类是文本字段，一类是资产表字段。
====适用客户====
不希望同步一些数据到帮我吧绑定工单模块的资产表中，但是工单又需要使用这些数据的时候，便可通过外部扩展实现。
比如：备件信息，项目信息等
====文本字段-数据源-帮我吧资产表====
使工单的自定义文本字段在开启外部扩展（启用外部数据源）后能够操作帮我吧自定义资产表，并将数据中的数据对应工单的自定义字段值中。
**配置地址**
https://www.bangwo8.com/osp2016/SDK/Tables/ticketAssetTable.php
**配置参数**
^ 名称 ^ 类型 ^ 必填 ^ 注释 ^
| tableId | int | tableId与tableName参数至少填写一个 |资产表id |
| tableName | string | ::: |资产表唯一标识，两个参数同时存在但又不是同一个资产表时，以该参数指向的资产表为准。 |
| cPara | string | 是 |资产表的字段与工单自定义字段对应参数,该参数用于配置选中的资产里的哪些资产字段取值回填到工单的哪些字段中；如asset_field_1:ticket_price,_id:ticket_name ；其中asset_field_1为资产表字段唯一标识，ticket_price和ticket_name为工单自定义字段唯一标识；特殊字段标识说明：_id为选中资产的对应资产id、tid为系统字段工单id、如果资产表使用关联表单，可以使用关联字段唯一标识.被关联表想获取的字段唯一标识来获取；参数有多个时，以逗号分隔|
| filter | string |否 |筛选资产表数据的条件（模糊搜索），资产表字段:取值, 取值可以是固定值，也可以是工单字段的占位符，如：asset_field_1：电子，按资产表中自定义字段asset_field_1包含电子的条件筛选资产表的数据，然后返回筛选后的数据给用户;asset_field_2:{ {ticket_status }},按资产表中自定义字段asset_field_2包含当前工单字段中唯一标识为ticket_status的字段值的条件筛选资产表的数据，然后返回筛选后的数据给用户。判断是否传filter，传了再判断是否有值，有值就按值的内容筛选，没有就不用筛选；没传filter，也不用筛选。filter参数可用于筛选资产表所属人的数据，如在弹框时要显示的是所属人为工单当前公司的所有资产表数据，则配置为ownerType:company,owner:{ {company.companyId}}|
| precise_filter| string |否 |已经放入filter字段中的资产表筛选字段，写入到这个字段后面，将会进行精准搜索；即资产字段的值完全等于filter中对应的赋值内容。配置方式：precise_filter=asset_field_1,asset_field_2|
| display | string | 否 |用于初始化设置，如第一次配置该资产表时，配置参数display=asset_field_1,asset_field_2，则显示这两列数据，但是可视化选项中是展示所有资产表字段，但是如果右上角的按钮选择显示/隐藏字段选中field_a,field_b，field_d这三个不同字段，则以这三个字段为准来显示，即display参数与可视化操作冲突时以可视化为准；可视化的操作以客服偏好为准，及每个客服之间选择显示的数据互不影响； |
| multiSelect | int | 否 |值为1时代表多选，cPara中配置的几个字段皆为多选一一对应值，以一个值一行的样式展示；不传此参数时默认为单选 |
| symbol | string | 否 |设置多选时，每个选项之间分割的符号：①换行：\n ②空格：nbsp ③; ④, ⑤、 备注：ios系统不支持换行显示 |
| assignment | string | 否 |带该参数时：传值1表示回将所选资产表的所属人信息客户信息赋值在工单的客户信息中，仅单选有效 |
**注意：**
①filter参数用于筛选资产表所属人的数据时，固定传两个参数：ownerType；owner 非必填，如果owner不为空，则ownerType也不能为空，否则显示所有数据
②ownerType：资产表数据的所属人类型，所属人类型为联系人取值：contacter，所属人类型为公司取值：company
③owner ：资产表数据的所属人，所属人类型为联系人占位符取值为：{ {user.cId} }（联系人id），所属人类型为公司占位符取值为：{ {company.companyId} }（公司id）
④非占位符时直接写联系人id或者公司id值;
该占位符获取的是当前页面数据，非数据库数据;如果配置了这两个参数，但是工单页面数据为空，则这两个参数不生效，显示所有数据；
如果owner不为空，则ownerType也不能为空，否则显示所有数据
⑤没有设置display参数时，第一次配置该外部扩展：默认显示所有字段，可视化选项选择中所有字段。
⑥有传display参数，第一次配置该外部扩展：显示的是该参数列，可视化选中的也是显示的字段。再次添加字段参数，不会再生效。
⑦symbol参数中传的分割多个选项的符号一定要确定所传的数据中不包含此分隔符，否则将出现数据混乱问题。
⑧assignment参数仅在单选时有效，链接中配置了多选参数时，传入此参数无效；配置好后在工单创建时可带入联系人信息或者公司信息（以及公司默认联系人），如果联系人离职则不带入；工单提交后，修改选择资产客户信息不会再随之改变。
**配置地址示例**
https://www.bangwo8.com/osp2016/SDK/Tables/ticketAssetTable.php?tableId=12&cPara=_id:ticket_price,asset_field_2:ticket_name&filter=asset_field_1:电子,asset_field_2:{{ticket_status}},ownerType:company,owner:{{company.companyId}}&precise_filter=asset_field_1&display=asset_field_1,asset_field_2&assignment=1
**操作视图**
{{:帮我吧文档:数据接口:工单:配置.png?800|}}
{{:帮我吧文档:数据接口:工单:文本外部扩展.png?800|}}
{{:帮我吧文档:数据接口:工单:8文本外部扩展赋值.png?800|}}
**工单字段与资产表字段可赋值类型对应表**
^工单字段类型 ^资产表字段类型^
| 单行文本| 单行文本 正整数 小数 日期 |
| 多行文本| 单行文本 多行文本 正整数 小数 日期 |
| 正整数| 正整数 |
| 日期 | 日期 |
| 小数| 小数|
====文本字段-数据源-第三方数据源====
当帮我吧工单和第三方页面互动时，工单页面内使用iframe（PS2）嵌套第三方页面；第三方页面内展现数据，选择数据，当选择完数据，帮我吧会使用选择的数据来回填工单内容
**配置**
在帮我吧配置文本字段如下：
{{:帮我吧文档:数据接口:工单:配置.png?800|}}
接口地址是第三方提供的url，帮我吧必传一个参数：cPara
该参数是指第三方字段和帮我吧字段的对应关系，当第三方页面给帮我吧回传数据时使用。格式为field_1:bw8_field_1,field_2:bw8_field_2；
field_1,field_2为第三方页面里字段的名称，bw8_field_1, bw8_field_2为帮我吧内字段的名称，参数有多个时，以逗号分隔。
**工单内使用**
{{:帮我吧文档:数据接口:工单:使用.png?800|}}
在工单页，双击A这个位置，就会弹出B,B是iframe，内部嵌套的是一里面配置的url。
**对接方需要做的**
当在第三方界面选择完数据，设置一个按钮，点击此按钮时，首先组装一个数组变量（详见下方注意），如叫param，封装为新对象data，参数msgType为本次对接标志,固定为字符串'textFieldExtend'，组装完成调用函数如下：
window.parent.postMessage(data,'*');
具体示例如下：
//表单数据
var param = [
{key:'field_181',value:'value field_181'},
{key:'field_182',value:'value field_182'},
];
//封装为新数据格式
var data = {
msgType: 'textFieldExtend', //添加消息类型
data: param, //表单数据
};
window.parent.postMessage(data,'*'); //发送消息
此时便可以给工单回填数据。
注意：
1.根据传过来的参数cPara，使用第三方field_1的值给对应的bw8_field_1赋值，组装成如下的数组（数组的元素是json）格式：
new Array({'key':’bw8_field_1’,'value':'hello'},{'key':':bw8_field_2','value':'world'})
2.Iframe的宽度是1000px，高度是500px
====资产表字段-数据源-第三方数据源====
当帮我吧工单的自定义字段--资产表类型字段的元数据来自于第三方数据时，工单页面内使用第三方系统提供的元数据，由帮我吧接入元数据，展示第三方数据在资产表页面内；选择数据，当选择完数据，帮我吧会使用选择的数据来回填工单本字段内容。 可用于配件库等业务场景。
实现界面如图：
{{:帮我吧文档:数据接口:工单:1.png?800|}}
**配置**
如果开启了启用外部数据源，则请选择表单选项不用选择，在帮我吧配置资产表字段如下：
{{:帮我吧文档:数据接口:工单:微信图片_20210412145328.png?800|}}
启用外部数据源后，接口地址是第三方提供的接口url
**对接方式**
首先创建资产表时，资产表的自定义字段唯一标识要与第三方接口返回的参数名一致
**请求方式**
psot
**请求参数**
^参数名 ^类型 ^必传 ^注释^
|custominfo |string |否|自定义参数传第三方接口的参数，可通过占位符获取当前工单页面数据传给第三方,多个参数时分号分隔，如： custominfo=servicerUserName:{ {ticket.currentServicerAccount} };ticketId:{ {ticket.ticketId} }; currentServicerAccount,ticketId参数名由第三方系统决定 通过占位符获取工单信息的，只能获取工单id（ticketId），还有当前登录的客服账号（currentServicerAccount）和名称（currentServicerName）|
|page| string| 是|每页可选择返回10、25、50,100条数据，不可随意更改|
|currentpage |string |是 |获取第几页的数据|
|query| string |否|固定字段多个模糊查询（不支持全局搜索，支持搜索字段类型：多行文本，单行文本，小数，整数） query=[ { "value":"贵阳青汇铸造有限公司", "columnName":"companyName" }, { "value":"广东省深圳市南山区", "columnName":"address" }, { "value":6941311, "columnName":"uId" }, { "value":0.21, "columnName":"price" } ]|
**第三方返回给帮我吧的数据格式**
当帮我吧单击资产表字段时请求第三方提供的url的数据，第三方接口按要求返回格式,这两个参数必须回传：
"ownerType":"agent",//资产表数据的所属人类型，取值为：agent-服务商//servicer-客服，contacter-联系人，company-公司
"owner":"测试公司"//服务商认证名称/客服名称/联系人名称/公司名称
**返回格式示例**
{
"rows":[
{ "ownerType":"agent",
"owner":"测试公司",
"uId":6941323,
"companyName":"一个测试公司",
"area":"0",
"address":"",
"date":"2020-01-21",
"price":0.12
},
{
"ownerType":"agent",
"owner":"测试公司2",
"uId":6941356,
"companyName":"另一个公司",
"area":"0",
"address":"",
"date":"2020-01-21",
"price":0.12
}
],
"total":2000,
"page":25,
"currentpage":1
}
**返回格式错误处理**
如果返回格式错误，则在页面显示：数据有误，请检查接口返回格式是否正确！
{{:帮我吧文档:数据接口:工单:4.png?800|}}
如果返回数据为空，则显示：
{{:帮我吧文档:数据接口:工单:5.png?800|}}
如果配置错误，如：custominfo多个参数传参没有按分号分隔或者格式错误，则显示：
{{:帮我吧文档:数据接口:工单:6.png?800|}}
====资产表字段-数据源-帮我吧客户资产表数据源====
当帮我吧工单的自定义字段--资产表类型字段的元数据来自于关联模块是客户管理的资产表数据时，工单页面内使用该资产表提供的元数据，由关联模块是工单的资产表接入元数据，展示该资产表数据在工单资产表页面内；选择数据，当选择完数据，帮我吧会使用选择的数据来回填工单本字段内容。
实现界面如图：
{{:帮我吧文档:数据接口:工单:q3jv3ehnqbzqz2wo_original.png?800|}}
选择添加以后的页面：
{{:帮我吧文档:数据接口:工单:bslgdsa3koe9nlhs_original.png?800|}}
**配置**
首先创建一个跟关联模块是客户管理的资产表结构一模一样的关联工单的资产表，然后启用外部数据源，请选择表单选项选择关联模块为工单的资产表，在帮我吧配置资产表字段如下：
{{:帮我吧文档:数据接口:工单:img.png?800|}}
启用外部数据源后，接口地址是自己根据下面文档配置的接口url
**请求方式**
post
**配置参数**
^ 名称 ^ 类型 ^ 必填 ^ 注释 ^
| ownerType| string|否 |资产表数据的所属人类型，取值为：contacter-联系人，company-公司|
| owner| string | 否 |资产表数据的所属人，取值为：contacter-联系人id（{ {user.userId} }），company-公司id（{ {company.companyId} }|
| tableId| string |是 |资产表id（该资产表为绑定客户管理模块的资产表），tableId必传，如果不传或者为空，则提示配置错误，详情见：返回格式错误处理|
| page| string|是 |每页可选择返回10、25、50,100条数据，不可随意更改|
| currentpage| string | 是 |获取第几页的数据|
|filter| string |否| 筛选资产表数据的条件（模糊搜索），资产表字段:取值, 取值可以是固定值，也可以是工单字段的占位符，如：asset_field_1：电子，按资产表中自定义字段asset_field_1包含电子的条件筛选资产表的数据，然后返回筛选后的数据给用户;asset_field_2:{ {ticket_status }},按资产表中自定义字段asset_field_2包含当前工单字段中唯一标识为ticket_status的字段值的条件筛选资产表的数据，然后返回筛选后的数据给用户。判断是否传filter，传了再判断是否有值，有值就按值的内容筛选，没有就不用筛选；没传filter，也不用筛选。filter参数可用于筛选资产表所属人的数据，如在弹框时要显示的是所属人为工单当前公司的所有资产表数据，则配置为ownerType:company,owner:{ {company.companyId}}|
| precise_filter| string | 否 |已经放入filter字段中的资产表筛选字段，写入到这个字段后面，将会进行精准搜索；即资产字段的值完全等于filter中对应的赋值内容。配置方式：precise_filter=asset_field_1,asset_field_2|
**配置地址示例**
https://www.bangwo8.com/osp2016/SDK/Tables/getAssetTableDate.php?tableId=292488&owner={{user.userId}}&ownerType=contacter
**第三方返回数据格式**
当帮我吧单击资产表字段时请求接口地址的数据，接口按要求返回格式,这两个参数必须回传：
"ownerType":"agent",//资产表数据的所属人类型，取值为：agent-服务商//servicer-客服，contacter-联系人，company-公司
"owner":"武汉华菲工匠工程服务有限责任公司"//服务商认证名称/客服名称/联系人名称/公司名称
返回格式示例：
{
"rows":[
{ "ownerType":"agent",
"owner":"武汉华菲工匠工程服务有限责任公司",
"uId":6941311,
"companyName":"贵阳青汇铸造有限公司",
"area":"0",
"address":"",
"date":"2020-01-21",
"price":0.12
},
{
"ownerType":"agent",
"owner":"武汉华菲工匠工程服务有限责任公司",
"uId":6941311,
"companyName":"贵阳青汇铸造有限公司",
"area":"0",
"address":"",
"date":"2020-01-21",
"price":0.12
},
{
"ownerType":"agent",
"owner":"武汉华菲工匠工程服务有限责任公司",
"uId":6941311,
"companyName":"贵阳青汇铸造有限公司",
"area":"0",
"address":"",
"date":"2020-01-21",
"price":0.12
},
{
"ownerType":"agent",
"owner":"武汉华菲工匠工程服务有限责任公司",
"uId":6941311,
"companyName":"贵阳青汇铸造有限公司",
"area":"0",
"address":"",
"date":"2020-01-21",
"price":0.12
}
],
"total":2000,
"page":25,
"currentpage":1
}
**返回格式错误处理**
如果返回格式错误，则在页面显示：数据有误，请检查接口返回格式是否正确！
{{:帮我吧文档:数据接口:工单:1_original.png?800|}}
如果返回数据为空，则显示：
{{:帮我吧文档:数据接口:工单:2_original.png?800|}}
如果配置错误，如：custominfo多个参数传参没有按分号分隔或者格式错误，则显示
{{:帮我吧文档:数据接口:工单:3_original.png?800|}}