OA消息说明文档

OA消息设计文档

简介

蜜蜂的普通应用消息只能用来显示通知信息，缺乏消息发送者、接受者间的交互手段，这里OA消息就是为了解决这个问题而出现，其基本需求如下：

OA消息支持简单的交互功能，有OA流程处理按钮。
OA消息有状态，客户应用服务器调用openapi可以设置OA消息的状态；客户端依消息的不同状态显示不同的内容。
OA消息文本内容支持富文本；可以定制显示文本的：字号、颜色、样式( 加粗、斜体)

总体设计

OA消息工作流程如图所示，OA服务器（客户应用服务器）可以在OA消息的流通中，根据消息格式规则构建消息内容，推送互动流程的进行。

OA消息根据不同状态显示不同的内容； 当处于未处理状态时，有供交互点击处理的按钮； 当处于已处理状态时，显示OA消息的状态和内容。
OA消息的操作按钮的名称和行为由OA消息定义，OA消息按钮的点击触发后台发起一次HTTP请求， HTTP请求的URL由OA消息定义。
OA服务器调用API（openapi）接口修改OA消息的状态，蜜蜂服务器通知客户端（发起方、处理方）更新指定OA消息的显示。

消息状态定义

OA消息状态是一个0-20的数值。
OA消息状态分为两类：1-10是已处理状态; 11-20未处理状态; 0:保留。 
已处理状态：客户端每次显示OA消息时，不需要再次向蜜蜂服务器查询消息状态。
未处理状态：客户端每次显示OA消息时，都必须向蜜蜂服务器查询此OA消息的当前状态。
OA消息状态默认是0。

OA消息定义

OA消息内容组成如上图，描述了一个OA消息的组成结构：

每个消息由消息标题与若干个消息元素构成， 消息元素最多10个。
消息标题的内容有OA消息给出，是一个固定的元素，每个OA消息必须有。
每个元素显示时独占消息的一行， 元素与消息显示控件同宽。高度由消息内容定义，针对消息内容自适应。
每个消息元素可以指定一个状态值，只有当消息的当前状态与元素的状态值相等时，才会显示此消息元素； 如果元素没有定义status值，此元素在任何状态下都显示。

一条OA消息实例如下：
{
    "appId":3,
    "color":"blue",
    "detailAuth":1,
    "detailURL":"http://192.168.35.145/msgtest2/event/detail?eventIdx=%7BDA92EB17-FE75-E7E8-2DE6-4CA6EE2D3BBB%7D",
    "elements":[
    {
        "imageId":"NjIwNzY1MjIvMjU2L3FpbmdqaWEuanBnXl5edGFuZ2hkZnNeXl5GRjA2OTNBQUE5NUM0NzQ5Mjc1MjQ0NjUyMzQ4OTczRV5eXnRhbmdoZGZzXl5eMTI0Mzk$",
        "imageType":"fileid",
        "type":"image"
    },
    {
        "content":[
            {
                "bold":1,
                "color":"#000000",
                "size":1,
                "text":"2016-01-21 13:24:54 "
            },
            {
                "color":"#808080",
                "text":"审批类型："
            },
            {
                "color":"#000000",
                "text":"请假 "
            },
            {
                "color":"#808080",
                "text":"申请人："
            },
            {
                "color":"#000000",
                "text":"maoyandev_b1 "
            },
            {
                "color":"#808080",
                "text":"审批人："
            },
            {
                "color":"#000000",
                "text":"maoyandev_b1 "
            },
            {
                "color":"#808080",
                "text":"申请内容："
            },
            {
                "color":"#000000",
                "text":"请一天假，望批准 "
            },
            {
                "color":"#000000",
                "name":"opinion",
                "text":"审核意见："
            }
        ],
        "type":"text"
    },
    {
        "buttons":[
            {
                "needSuggestion":"1",
                "noEmptySuggestion":"0",
                "suggestionName":"opinion",
                "suggestionTitle":"审核意见 ",
                "title":"同意",
                "url":"http://192.168.35.145/msgtest2/event/process?forAction=true&eventIdx=%7BDA92EB17-FE75-E7E8-2DE6-4CA6EE2D3BBB%7D&eventStatus=1",
                "urlauth":1
            },
            {
                "needSuggestion":"1",
                "noEmptySuggestion":"0",
                "suggestionName":"opinion",
                "suggestionTitle":"审核意见 ",
                "title":"拒绝",
                "url":"http://192.168.35.145/msgtest2/event/process?forAction=true&eventIdx=%7BDA92EB17-FE75-E7E8-2DE6-4CA6EE2D3BBB%7D&eventStatus=2",
                "urlauth":1
            },
            {
                "needSuggestion":"1",
                "noEmptySuggestion":"0",
                "suggestionName":"opinion",
                "suggestionTitle":"审核意见 ",
                "title":"无认证测试",
                "url":"http://192.168.35.145/msgtest2/event/noauthtest?status=15",
                "urlauth":0
            }
        ],
        "status":15,
        "type":"action"
    },
    {
        "content":[
            {
                "color":"#808080",
                "text":"状态："
            },
            {
                "color":"#0000FF",
                "size":3,
                "text":"待审批"
            }
        ],
        "status":16,
        "type":"text"
    },
    {
        "content":[
            {
                "color":"#808080",
                "text":"状态："
            },
            {
                "color":"#0000FF",
                "size":3,
                "text":"已同意"
            }
        ],
        "status":7,
        "type":"text"
    },
    {
        "content":[
            {
                "color":"#808080",
                "text":"状态："
            },
            {
                "color":"#FF0000",
                "size":3,
                "text":"已拒绝"
            }
        ],
        "status":8,
        "type":"text"
    }],
    "status":15,
    "title":"审批",
    "titleElements":[
    {
        "color":"red",
        "status":1,
        "title":"已同意"
    },
    {
        "color":"yellow",
        "status":2,
        "title":"已拒绝"
    },
    {
        "color":"red",
        "status":7,
        "title":"已同意"
    },
    {
        "color":"yellow",
        "status":8,
        "title":"已拒绝"
    },
    {
        "color":"gray",
        "status":15,
        "title":"审批"
    }],
    "toUsers":[
        "maoyandev_b1"
    ]
}

OA消息元素

由元素json对象中type确定，分别是：文本（text）,图片（image）,action。

文本元素

显示富文本，富文本支持定制字号(预定义字号：大,中,小等)、颜色、格式（加粗）。文本元素的高度以文本内容为准，像聊天消息显示那样，自适应高度。

图片元素

此元素显示一个图片，元素的高度有最大值。

当图片的宽度大于元素宽度时，图片以拉伸显示；高度不得超过最大高度。当图片的宽度小于元素宽度且高度不大于元素最大高度时，图片不拉伸；如果图片高度大于最大高度，则拉伸显示。

点击此图片时，在独立的窗口中显示完整的图片。

3) Action元素

Action元素是预定义若干按钮的元素；最多4个按钮。

点击按钮时，后台向OA消息指定的URL发起HTTP请求，按钮的“标题”、“点击动作URL”由OA消息定义("实例OA消息button\url元素")。

button执行后，对应URL接口要返回执行操作后的状态（$newStatus），审核意见附加数据（externalData）。Eg: { “externalData”:{ “text”:{ “opinion”:”value1”, //opinion：本次意见名，value1：意见内容 } }, “reqId”: "1452158164.83546800.11292", “status”:7 } 以方便客户端能根据响应即时显示操作结果。附加数据

消息内容格式

1) OA消息定义

title: 字符串，OA消息的标题，如果此字段为null或“”，则UI中标题栏位隐藏不显示。
Status: 整形，OA消息的默认状态值；缺省默认是0。
Color: 字符串， 预定义标题配色模版，可选名称值(大小写不敏感)：
    "red", 赤红
    "yellow", 蜜蜂黄
    "green", 柳绿
    "gray", 铅灰
    "blue", 主题蓝
    "lightblue", 薄蓝
    默认值：主题蓝
Elements：一个元素的JSON格式字符串，是消息元素对象的数组
    “elements”: [  
        { <elem>}, 
        {elem2},
        …… 
    ];
DetailURL: 消息详情URL；
DetailAuth: 数值型，指定打开详情URL时，是否带上认证信息。1:带上认证信息;0:不带，默认0。
titleElements:标题栏扩展元素，定义了不同状态下标题栏对应的颜色与内容； 定义格式上节所示； 有以下几点说明：
    "titleElements":[{
        "stauts": 15
        "title": "asdfasdrqwerqwer",
        "color": "blue",
    },
    {
        "stauts":18
        "title": "asdfasdrqwerqwer",
        "color": "red"
    }]
    如果有titleElements字段，且有OA消息状态对应的标题栏元素时，显示元素定义的内容与颜色。
    如果有titleElements字段，但是没有OA消息状态对应的标题栏元素时，显示OA消息title, color字段定义的内容与颜色。
    如果没有titleElements字段，显示OA消息title, color字段定义的内容与颜色。

2) 文本元素

{
    "type": “text”,      // 元素类型
    "status":  1,         // 当前元素的状态
    "content": {},      // type为text时， 指定文本元素的内容； 仅在type为text时有效。
}
type：字符串，指定消息的类型，文本元素类型值：text。
status:  整形, 指定此消息元素对应的消息状态值, 缺省默认是null，在任何状态下都显示。
content: 字段有三种数据格式，纯文本、JSON对象、JSON数组对象。

当content字段的内容是纯文本时， UI直接以默认的颜色、字号显示文本内容，不加粗、斜体；如：

content”: “Hello, world”

当content字段是一个JSON对象时，描述的是一段富文本，具体定义如下：

"content": {
    "size": 1, 
    "color": “#ff00ff”,
    "bold": 1, 
    "urlauth": 1, 
    "url": “http://www.baidu.com”, // 文本连接URL
    "text": "文本内容"
}
size：整形；定义显示文字的大小，共有3(大)，2（中）,1（小）三种字号，默认值：2。
color: 字符串, 颜色值定义格式“#<RGB颜色的十六进制值>”, 如：黑色 #000000, 红色　#FF0000； 默认是黑色(参照视觉给定的颜色，不是纯黑色)。
bold：整形，指定是否加粗显示文字；候选值：1(加粗)，0（不加粗），默认值：0。
urlauth: 整形，指定打开本json对象描述的链接时，是否附上统一认证信息。
url: 字符串，定义一个URL连接；当此字段存在且不为空时，忽略color的用户定义值，color显示使用默认颜色，建议用：#0000ff, 且带有下划线。
text: 字符串， UTF-8格式的文本内容。

3) 图片元素

{
    "type":"image", 
    "status": 1,  
    "imageType": ""
    "imageId": ""
}
type：字符串，指定消息的类型，图片元素类型值：image。
status: 整形，指定此消息元素对应的消息状态值,缺省默认是null，在任何状态下都显示。
imageType: 字符串, 指定imageId值的类型，候选值:fileid,url。默认url。
imageId： 字符串，指定图片文件的地址。
当imageType是fileid时， imageid字段的内容是一个Image文件在FS中的ID。如：“imageid”: “123123kjsdkfjsdkfsdlfsdfksdfksdfjsdfl”,当imagetype是url时，imageid字段的内容是一个图片文件的URL， 如：“imageid”: “http://www.baidu.com/icon.png”。

4) Action元素

{
    “type”: “action”, 
    “status”:  1, 
    “buttons”: [{
        “title”, “按钮标题“,
        “url”: “http://www.qanshi.com/url.php?”,
        “urlauth”: 0,
        “needSuggestion”:1,
        “noEmptySuggestion”:1,
        “suggestionTitle”:”测试审核意见”,
        “suggestionName”:”opinion1”   //审核意见对象名（见审核意见文档）
    }]
}
type：字符串，指定消息的类型，action元素类型值：action。
status: 整形，指定此消息元素对应的消息状态值, 缺省默认是null，在任何状态下都显示。
buttons: JSON数组，每个数组元素定义个按钮；按钮元素的JSON字段定义如下：
    title: 字符串,按钮的标题。
    url： 字符串，按钮被Click时，触发的URL链接。
    urlauth: 数值，打开URL时是否要带上认证信息，1：带，0：不带；默认0.
    needSuggestion: 整形， 1：需要意见， 0：不需要意见; 默认不需要。
    noEmptySuggestion: 整形， 1: 意见内容不能为空， 0: 意见内容可为空：默认0.
    sggestionTitle:”审核意见”输入框图的标题，如下图的“红色框”。默认“审核意见”，PC端有效。
    suggestionName：审核意见对象名。

消息URL约定

1) 链接URL

文本元素的内容JSON描述部分可以赋值一个URL，显示的时候就像网页的URL连接；点击此链接时， PC客户端直接在浏览器中打开URL，移动客户端在内嵌的WebView中打开此URL。

除URL外，还可以指定一个附加属性；当附加属性设置“urlauth”为1时，则打开URL的规则与打开应用中心的应用是一样的，会带上统一认证的信息，默认”urlauth”为0.

2) Action URL

Action元素按钮的URL, 不使用浏览器或者WebView打开；在后台发起一个HTTP请求。

所有Action按钮打开URL方式还有一个附加属性；当附加属性设置“urlauth”为1时，则打开URL的规则与打开应用中心的应用是一样的，会带上统一认证的信息，默认”urlauth”为0.

Action URL的答复约定为一个Json格式的数据；定义如下：

{
    “externalData”:{
        “text”:{
            “opinion1”:”value1”,//opinion1：本次意见名，value1：意见内容
        }      
    },  
    “status”: <newstatus>
}
status： OA消息新的消息状态， 客户端要以此消息状态刷新消息的显示;

3) 详情URL

每个OA消息有一个对应的详情URL字段，当在客户端界面点击详情的区域(由产品定义)时，PC客户端直接在浏览器中打开URL，移动客户端在内嵌的WebView中打开此URL。由独立的字段detailAuth定义是否在打开时带上认证信息。

4) 统一认证信息

统一认证信息是附在URL上的，本质是2个URL变量，统一认证信息变量定义如下：

uc_account: 蜜蜂客户端当前用户登录名作为此变量的值。
uc_token:蜜蜂客户端当前用户SessionId作为此变量的值。
举例说明：http://www.baidu.com/a/b/c?uc_account=xxxxxxx&uc_token=xxxxxxxx;