帮我吧文档:数据接口:工单:工单外部扩展

功能介绍

工单外部扩展,指的是工单自定义字段中的两种字段类型(文本,资产表)可支持数据源来自于第三方,及绑定帮我吧客户档案的资产表的数据,然后赋值到工单中,使得工单满足多方对接。对接类型有两大类,一类是文本字段,一类是资产表字段。

适用客户

不希望同步一些数据到帮我吧绑定工单模块的资产表中,但是工单又需要使用这些数据的时候,便可通过外部扩展实现。 比如:备件信息,项目信息等

文本字段-数据源-帮我吧资产表

使工单的自定义文本字段在开启外部扩展(启用外部数据源)后能够操作帮我吧自定义资产表,并将数据中的数据对应工单的自定义字段值中。

配置地址

https://www.bangwo8.com/osp2016/SDK/Tables/ticketAssetTable.php

配置参数

名称 类型 必填 注释
tableId int 资产表id
cPara string 资产表的字段与工单自定义字段对应参数,如asset_feild_1:ticket_price,asset_feild_2:ticket_name,asset_feild_1和asset_feild_2为资产表字段唯一标识,ticket_price和ticket_name为工单自定义字段唯一标识,参数有多个时,以逗号分隔,该参数用于定义资产表里的哪些字段取值回填到工单的哪些字段中
filter string 筛选资产表数据的条件,资产表字段:取值, 取值可以是固定值,也可以是工单字段的占位符,如:asset_feild_1:电子,按资产表中自定义字段asset_feild_1等于电子的条件筛选资产表的数据,然后返回筛选后的数据给用户;asset_feild_2:{ {ticket_status }},按资产表中自定义字段asset_feild_2等于当前工单字段中唯一标识为ticket_status的字段值的条件筛选资产表的数据,然后返回筛选后的数据给用户。判断是否传filter,传了再判断是否有值,有值就按值的内容筛选,没有就不用筛选;没传filter,也不用筛选。filter参数可用于筛选资产表所属人的数据,如在弹框时要显示的是所属人为工单当前公司的所有资产表数据,则配置为ownerType=company&owner={ {company.companyId} }
display string 用于初始化设置,如第一次配置该资产表时,配置参数display=asset_feild_1,asset_feild_2,则显示这两列数据,但是可视化选项中是展示所有资产表字段,但是如果右上角的按钮选择显示/隐藏字段选中feild_a,feild_b,feild_d这三个不同字段,则以这三个字段为准来显示,即display参数与可视化操作冲突时以可视化为准;可视化的操作以客服偏好为准,及每个客服之间选择显示的数据互不影响;

注意:

filter参数用于筛选资产表所属人的数据时,固定传两个参数:ownerType;owner 非必填,如果owner不为空,则ownerType也不能为空,否则显示所有数据

ownerType:资产表数据的所属人类型,所属人类型为联系人取值:contacter,所属人类型为公司取值:company

owner :资产表数据的所属人,所属人类型为联系人占位符取值为:{ {user.cId} }(联系人id),所属人类型为公司占位符取值为:{ {company.companyId} }(公司id)

非占位符时直接写联系人id或者公司id值; 该占位符获取的是当前页面数据,非数据库数据;如果配置了这两个参数,但是工单页面数据为空,则这两个参数不生效,显示所有数据; 如果owner不为空,则ownerType也不能为空,否则显示所有数据

没有设置display参数时,第一次配置该外部扩展:默认显示所有字段,可视化选项选择中所有字段。

有传display参数,第一次配置该外部扩展:显示的是该参数列,可视化选中的也是显示的字段。再次添加字段参数,不会再生效。

配置地址示例

https://www.bangwo8.com/osp2016/SDK/Tables/ticketAssetTable.php?tableId=12&cPara=asset_feild_1:ticket_price,asset_feild_2:ticket_name&filter=asset_feild_1:电子,asset_feild_2:{{ticket_status}},ownerType:company,owner:{{company.companyId}}&display=asset_feild_1,asset_feild_2,

操作视图

工单字段与资产表字段可赋值类型对应表

工单字段类型 资产表字段类型
单行文本 单行文本 正整数 小数 日期
多行文本 单行文本 多行文本 正整数 小数 日期
正整数 正整数
日期 日期
小数 小数

文本字段-数据源-第三方数据源

当帮我吧工单和第三方页面互动时,工单页面内使用iframe(PS2)嵌套第三方页面;第三方页面内展现数据,选择数据,当选择完数据,帮我吧会使用选择的数据来回填工单内容

配置

在帮我吧配置文本字段如下:

接口地址是第三方提供的url,帮我吧必传一个参数:cPara 该参数是指第三方字段和帮我吧字段的对应关系,当第三方页面给帮我吧回传数据时使用。格式为field_1:bw8_field_1,field_2:bw8_field_2; field_1,field_2为第三方页面里字段的名称,bw8_field_1, bw8_field_2为帮我吧内字段的名称,参数有多个时,以逗号分隔。

工单内使用

在工单页,双击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

资产表字段-数据源-第三方数据源

当帮我吧工单的自定义字段–资产表类型字段的元数据来自于第三方数据时,工单页面内使用第三方系统提供的元数据,由帮我吧接入元数据,展示第三方数据在资产表页面内;选择数据,当选择完数据,帮我吧会使用选择的数据来回填工单本字段内容。 可用于配件库等业务场景。

实现界面如图:

配置

如果开启了启用外部数据源,则请选择表单选项不用选择,在帮我吧配置资产表字段如下: 启用外部数据源后,接口地址是第三方提供的接口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":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
 }

返回格式错误处理

如果返回格式错误,则在页面显示:数据有误,请检查接口返回格式是否正确!

如果返回数据为空,则显示:

如果配置错误,如:custominfo多个参数传参没有按分号分隔或者格式错误,则显示:

资产表字段-数据源-帮我吧客户资产表数据源

当帮我吧工单的自定义字段–资产表类型字段的元数据来自于关联模块是客户管理的资产表数据时,工单页面内使用该资产表提供的元数据,由关联模块是工单的资产表接入元数据,展示该资产表数据在工单资产表页面内;选择数据,当选择完数据,帮我吧会使用选择的数据来回填工单本字段内容。

实现界面如图: 选择添加以后的页面:

配置

首先创建一个跟关联模块是客户管理的资产表结构一模一样的关联工单的资产表,然后启用外部数据源,请选择表单选项选择关联模块为工单的资产表,在帮我吧配置资产表字段如下:

启用外部数据源后,接口地址是自己根据下面文档配置的接口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 获取第几页的数据
query string 固定字段多个模糊查询(不支持全局搜索,支持搜索字段类型:多行文本,单行文本,小数,整数) query=[ { “value”:“贵阳青汇铸造有限公司”, “columnName”:“companyName” }, { “value”:“广东省深圳市南山区”, “columnName”:“address” }, { “value”:6941311, “columnName”:“uId” }, { “value”:0.21, “columnName”:“price” } ]

配置地址示例

http://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
 }

返回格式错误处理 如果返回格式错误,则在页面显示:数据有误,请检查接口返回格式是否正确!

如果返回数据为空,则显示:

如果配置错误,如:custominfo多个参数传参没有按分号分隔或者格式错误,则显示


页面工具