1. Retainer使用手册

1. Retainer使用手册
2. 基本概念
3. 操作说明

历程（Retainer）的含义是广泛的，它可以是一个故障、可以是一个报警、可以是一个生产计划、可以是一个工作任务、也可以是一个订单流程。

历程记录了事件的开始时间、结束时间、持续时长、流水记录等过程，同时还可以对相关的数据进行统计。

假设一个高温报警历程，温度高于100时历程开始、温度低于100时历程结束，期间统计温度的平均值。

参考上图，流程说明如下：

终端采集设备温度数据，20秒一次向系统上报；
系统拼接数据，温度大于100发布一个高温事件、温度小于100发布一个常温事件；
历程服务收到高温事件开启历程，并发布一个历程开放事件；
终端持续上报数据，历程服务进行温度平均值统计；
历程服务收到常温事件关闭历程，并发布一个历程关闭事件。

2. 基本概念

2.1. 开始结束

历程（Retainer）的开始和结束由马赛克服务（Mpapping）事件驱动，其中马赛克服务发布的是逻辑条件事件（比如温度大于100或温度小于100等）；历程开始或关闭时历程服务也会发布历程开放和历程关闭事件。

历程服务发布的事件消息会驱动更多的业务：显示板（Dashboard）可以实时监控历程信息，信使服务（Messenger）收到事件将发送通知消息，工单服务（workflow）收到信息将生成工单等。

2.2. 统计函数

历程数据统计是一个数据的垂直统计，比如在一次生产中数据取样上报了 n 次，需要统计生产期间某个参数的平均值、最大值、最小值等。

2.2.1. 函数支持

函数名	函数说明
sum	求和，返回参数的总和
avg	平均值，返回参数平均值
count	计数，返回参数的个数
first	起始值，返回第一个值
last	最新值，返回最后一个值
max	最大值，返回最大值
min	最大值，返回最小值
spread	极差值，返回最大值减最小值的差
stddev	标准差，返回参数的标准差
accumulate	读数转用量，返回参数的读数累计值

2.2.2. 函数示例

假设一个历程中，数据(x)按时间先后顺序上报分别为：1、2、3、4、5。

求和(sum)

sum(x) = 1+2+3+4+5 = 15 // 根据公式计算结果为 15

平均值(avg)

avg(x) = (1+2+3+4+5)/5 = 3 // 根据公式计算结果为 3

计数(count)

count(x) = 5 // 共5个数据，结果为 5

起始值(first)

first(x) = 1 // 第一个数为 1，结果为 1

最新值(last)

last(x) = 5 // 最后一个数为 5， 结果为 5

最大值(max)

max(x) = 5 // 最大值为 5， 结果为 5

最小值(min)

min(x) = 1 // 最小值为 1， 结果为 1

极差值(spread)

spread(x) = 5-1 = 4 // 最大值减最小值， 结果为 4

标准差(stddev)

// 已知x的平均值为3
spread(x) = (((1-3)^2+(2-3)^2+(3-3)^2+(4-3)^2+(5-3)^2)/5)^1/2 = 2^1/2 = 1.41 // 根据公式计算结果为 1.41

读数转用量(accumulate)

accumulate(x) = (2-1) + (3-2) + (4-3) + (5-4) + (6-5) = 5

2.3. 历程脚本

Mixiot中，一个历程通过6列的Json脚本定义。

2.3.1. 脚本规范

[
  ["RV","Label_En","Label_Cn","EventCode_Start","EventCode_Stop",{"ticker":"0s","statistics_fv": "S01","statistics_func": "avg","statistics_filter": ""}] 
]

第一列 RV：为历程变量（又叫历程编码），定义时不能重复、且不超过64个字符
第二列 Label_En：为历程的英文注释
第三列 Label_Cn：为历程的中文注释
第四列 EventCode_Start：为历程开始事件code，是马赛克的条件事件code（需预先在映射表脚本配置）
第五列 EventCode_Stop：为历程结束时间code，是马赛克的条件事件code（需预先在映射表脚本配置）
第六列 {}：为历程统计参数设置
- ticker: 可选，设置防抖动，默认"0s" 即不防抖动
- statistics_fv: 为需要统计变量，是马赛克的FV变量（需预先在映射表脚本配置），如果不需要统计则不填写
- statistics_func: 为需要统计方法，可选值参考 2.2，如果不需要统计则不填写
- statistics_filter: 为需要统计过滤模型，如果不需要统计则不填写

2.3.2. 脚本示例

假设映射表（Mapping）脚本中：S01为采集的温度数据，当温度S01大于100发布高温事件C1001、当温度S01小于100发布常温事件C1002。

[
    ["S01", "Temperature", "温度", "STA", "$AprusID-1", "L1_2_3", "", "", {}],
    ["C1001", "HighTemperature", "高温事件", "EVNT", "$AprusID-1", "L1_2_3", "", "S01>100", {}],
    ["C1002", "RoomTemperature", "常温事件", "EVNT", "$AprusID-1", "L1_2_3", "", "S01<100", {}]
]

当S01值为200，则马赛克发布事件数据如下(code字段为定义的C1001)：

{
    "event": "trigger_event",
    "block": "mosaic",
    "uniqueid": "PUB1323431200006",
    "datetime": "2021-10-28 10:15:34",
    "object_id": "OBJ1315925700001",
    "terminal_id": "AX202110080001",
    "code": "C1001",
    "label_en": "HighTemperature",
    "label_local": "高温事件",
    "value": {
        "S01": 200
    }
}

当S01值为80，则马赛克发布事件数据如下(code字段为定义的C1002)：

{
    "event": "trigger_event",
    "block": "mosaic",
    "uniqueid": "PUB1323431200123",
    "datetime": "2021-10-28 12:15:34",
    "object_id": "OBJ1315925700001",
    "terminal_id": "AX202110080001",
    "code": "C1002",
    "label_en": "RoomTemperature",
    "label_local": "常温事件",
    "value": {
        "S01": 80
    }
}

历程（Retainer）脚本中，历程R1001为一个报警历程，该历程根据马赛克事件C1001开始、根据马赛克事件C1002结束，历程期间统计数据S01的平均值。

[
    ["R1001", "AlarmProcess", "报警历程", "C1001", "C1002", {"statistics_fv": "S01", "statistics_func": "avg"}]
]

历程记录如下

3. 操作说明

3.1. 历程应用

历程应用是Fidis平台的一个卡片应用，可以界面化操作管理历程。

3.1.1. 历程配置

配置管理历程脚本

配置列表页面

配置详情页面

3.1.2. 历程记录

生成实际的历程记录

记录列表页面

记录详情页面

3.2. 历程组件

3.2.1. 标准组件

历程支持显示板组件实时监控历程信息

3.2.2. 组合使用

显示板组件结合其他组件可以查看更多信息，更多组件说明详见显示板设计工具使用说明。

3.3. 更多应用

除了马赛克事件方式生成历程，还可以由外部应用通过接口生成，同时可以记录详细流水记录。更多应用请看Mixiot活学活用案例！

历程(retainer)脚本