外观
lib-alarm 库参考
原文: https://finproducts.atlassian.net/wiki/spaces/JIDD3/pages/34793881723/FIN+5.3.1+lib-alarm 中文整理基于 FIN 5.3.1
导读： 本页为
lib-alarm的 API / 标签 / 函数参考文档。
以下为 API 参考，保留英文以便对照源码；目录已列出（英文标题便于检索）；概述已尽量中译。
目录（导读）
- lib
- meta
- tags
- funcs
- def
- supertypes
- tags
- alarmAck(alarms, message: null)
- alarmDigest(groupBy: "site", includeUnknown: false)
- alarmHistoryCount(target: null)
- alarmHistoryQuery(query)
- alarmNavCounts(grid)
- alarmTargets(root)
- alarms(targets: null, span: null, filter: null, pollHandle: null)
- alarmsGetById(alarmId)
- alarmsRemove(alarms)
- clearAlarmHistory(spanOrBefore: null, rebuild: false)
- clearAlarmHistoryBefore(date)
- readAlarmHistory(targets: null, span: null)
- toAlarm(target, nsOrState, messageOrTags: null, occurred: null, priority: null, meta: null)
- toNormal(targets, nsOrMessage: null, occurredOrTags: null, meta: null)
概述（中译）
警报扩展
API 正文（英文）
tags
| ackErr | This tag is set when there is an error acknowledging alarm and contains the reason for the error |
| ackInProgress | This alarm is current being acknowledged |
| ackMessage | Message or reason for acknowledgement |
| ackMessageRequired | This alarm requires a message when acknowledging |
| ackRequired | This alarm requires acknowledgement |
| acked | Time that the alarm was acknowledged |
| ackedBy | Who acknowledged the alarm |
| alarmAckAccessFilter | String filter applied to a user record which defines which alarms a user may acknowldege |
| alarmHistory | Alarm history record |
| alarmRoute | Alarm route |
| alarmRule | Alarm rule |
| fromState | State of the entity prior to alarm transition |
| funcName | Name of function associated with route |
| message | Message describing the alarm or reason for the alarm |
| metadata | Information related to the alarm that will live with the lifecycle of the alarm |
| occurred | Date/Time that the alarm actually occurred |
| routeOn | Filter that will select alarms to route |
| sourceRef | Reference to the source of the alarm |
| state | State of the alarm |
| targetFilter | Filter which matches points to be commanded by this route |
| toState | State of the entity when going into alarm |
| value | Value to write to the selected points |
funcs
| alarmAck | Given a set of alarms (or alarm ids), acknowledge them and return the updated alarm records |
| alarmDigest | Generate an alarm digest grouped by a given parent type |
| alarmHistoryCount | Given an optional target, return the count of alarm history records |
| alarmHistoryQuery | Given a Haystack query string, return the alarm history records as a grid |
| alarmNavCounts | Given a grid of target records with id, enrich it with rolled-up alarm counts per row |
| alarmTargets | Given a root object, return all alarm target records associated with it |
| alarms | Given optional targets and/or a time span, return the current alarm records as a grid |
| alarmsGetById | Given an alarm id, return the corresponding alarm record |
| alarmsRemove | Given a set of alarms (or alarm ids), remove them from the database and return the removed alarm records |
| clearAlarmHistory | Clear alarm history records in the database based on the given parameters |
| clearAlarmHistoryBefore | Clear alarm history records before the given date in the database |
| readAlarmHistory | Given optional targets and/or a time span, query the alarm history as a grid |
| toAlarm | Given a target and either a legacy namespace or a new-style alarm state, transition the given namespace/target to the alarm state |
| toNormal | Given targets, transition alarms back to normal state using either the legacy API (namespace-based) or the new API (message/occurred/meta) |
def
ackErr
This tag is set when there is an error acknowledging alarm and contains the reason for the error
meta
| def | ackErr |
| is | str |
| lib | lib:alarm |
| tagOn | alarm |
supertypes
| val | Data value type |
| scalar | Scalar is an atomic value kind |
| str | Unicode string of characters |
def
ackInProgress
This alarm is current being acknowledged
meta
| def | ackInProgress |
| is | marker |
| lib | lib:alarm |
| tagOn | alarm |
supertypes
| marker | Marker labels a dict with typing information |
def
ackMessage
Message or reason for acknowledgement
meta
| def | ackMessage |
| is | str |
| lib | lib:alarm |
| tagOn | alarm |
supertypes
| val | Data value type |
| scalar | Scalar is an atomic value kind |
| str | Unicode string of characters |
def
ackMessageRequired
This alarm requires a message when acknowledging
meta
| def | ackMessageRequired |
| is | marker |
| lib | lib:alarm |
| tagOn | alarm |
supertypes
| marker | Marker labels a dict with typing information |
def
ackRequired
This alarm requires acknowledgement
meta
| def | ackRequired |
| is | marker |
| lib | lib:alarm |
| tagOn | alarm |
supertypes
| marker | Marker labels a dict with typing information |
def
acked
Time that the alarm was acknowledged
meta
| def | acked |
| is | dateTime |
| lib | lib:alarm |
| tagOn | alarm |
supertypes
| val | Data value type |
| scalar | Scalar is an atomic value kind |
| dateTime | ISO 8601 timestamp followed by timezone identifier |
def
ackedBy
Who acknowledged the alarm
meta
| def | ackedBy |
| is | str |
| lib | lib:alarm |
| tagOn | alarm |
supertypes
| val | Data value type |
| scalar | Scalar is an atomic value kind |
| str | Unicode string of characters |
def
alarmAckAccessFilter
String filter applied to a user record which defines which alarms a user may acknowldege. See <doc#ackSecurity>.
meta
| def | alarmAckAccessFilter |
| is | str |
| lib | lib:alarm |
supertypes
| val | Data value type |
| scalar | Scalar is an atomic value kind |
| str | Unicode string of characters |
def
alarmHistory
Alarm history record
meta
| def | alarmHistory |
| is | alarm |
| lib | lib:alarm |
supertypes
| marker | Marker labels a dict with typing information |
| alarm | Notification of a condition which requires attention |
tags
| ackErr | This tag is set when there is an error acknowledging alarm and contains the reason for the error |
| ackInProgress | This alarm is current being acknowledged |
| ackMessage | Message or reason for acknowledgement |
| ackMessageRequired | This alarm requires a message when acknowledging |
| ackRequired | This alarm requires acknowledgement |
| acked | Time that the alarm was acknowledged |
| ackedBy | Who acknowledged the alarm |
| created | The timestamp when entity was created |
| curStatus | Status of point's current value reading |
| curVal | Current value of a point |
| fromState | State of the entity prior to alarm transition |
| message | Message describing the alarm or reason for the alarm |
| metadata | Information related to the alarm that will live with the lifecycle of the alarm |
| occurred | Date/Time that the alarm actually occurred |
| sourceRef | Reference to the source of the alarm |
| state | State of the alarm |
| toState | State of the entity when going into alarm |
def
alarmRoute
Alarm route. value is set to the type name of the routing implementation
meta
| def | alarmRoute |
| is | str |
| lib | lib:alarm |
| mandatory | ✓ |
supertypes
| val | Data value type |
| scalar | Scalar is an atomic value kind |
| str | Unicode string of characters |
tags
| funcName | Name of function associated with route |
| routeOn | Filter that will select alarms to route |
| targetFilter | Filter which matches points to be commanded by this route |
| value | Value to write to the selected points |
| writeLevel | Current priority level for writeVal as number between 1 and 17 |
def
alarmRule
Alarm rule. value is set to the type name of the rule implementation
meta
| def | alarmRule |
| is | str |
| lib | lib:alarm |
| mandatory | ✓ |
supertypes
| val | Data value type |
| scalar | Scalar is an atomic value kind |
| str | Unicode string of characters |
tags
| message | Message describing the alarm or reason for the alarm |
| metadata | Information related to the alarm that will live with the lifecycle of the alarm |
| ruleOn | Target filter for a rule or rule ready func |
| state | State of the alarm |
def
fromState
State of the entity prior to alarm transition
meta
| def | fromState |
| is | str |
| lib | lib:alarm |
| tagOn | alarmHistory |
supertypes
| val | Data value type |
| scalar | Scalar is an atomic value kind |
| str | Unicode string of characters |
def
funcName
Name of function associated with route
meta
| def | funcName |
| is | str |
| lib | lib:alarm |
| tagOn | alarmRoute |
supertypes
| val | Data value type |
| scalar | Scalar is an atomic value kind |
| str | Unicode string of characters |
def
func:alarmAck
alarmAck(alarms, message: null)
Given a set of alarms (or alarm ids), acknowledge them and return the updated alarm records.
Parameters:
- alarms (required) - Alarm(s) to acknowledge in any of the following formats: (Grid, Dict[], Ref[], Dict, Str, Ref)
- message (optional) - acknowledgement message
Examples:
alarmAck(alarms())
alarmAck(@alarmId, "Investigating")
alarmAck("r:demo:alarm123", "Cleared by operator")
alarmAck(readAll(alarm).keepCols(["id"]))meta
| def | func:alarmAck |
| is | func |
| lib | lib:alarm |
| name | alarmAck |
supertypes
| feature | Feature namespace of definitions formatted as feature:name |
| func | Axon function |
def
func:alarmDigest
alarmDigest(groupBy: "site", includeUnknown: false)
Generate an alarm digest grouped by a given parent type.
Parameters:
- groupBy (optional) - the parent type to group by. Default is "site".
- includeUnknown (optional) - if true, includes alarms with unknown sources in
meta
| def | func:alarmDigest |
| is | func |
| lib | lib:alarm |
| name | alarmDigest |
supertypes
| feature | Feature namespace of definitions formatted as feature:name |
| func | Axon function |
def
func:alarmHistoryCount
alarmHistoryCount(target: null)
Given an optional target, return the count of alarm history records.
Parameters:
- target (optional) - this is the rec or id of the target. If omitted, it will count all records in the database.
meta
| def | func:alarmHistoryCount |
| is | func |
| lib | lib:alarm |
| name | alarmHistoryCount |
supertypes
| feature | Feature namespace of definitions formatted as feature:name |
| func | Axon function |
def
func:alarmHistoryQuery
alarmHistoryQuery(query)
Given a Haystack query string, return the alarm history records as a grid.
Parameters:
- query (required) - Haystack query string to filter alarm history
meta
| def | func:alarmHistoryQuery |
| is | func |
| lib | lib:alarm |
| name | alarmHistoryQuery |
supertypes
| feature | Feature namespace of definitions formatted as feature:name |
| func | Axon function |
def
func:alarmNavCounts
alarmNavCounts(grid)
Given a grid of target records with id, enrich it with rolled-up alarm counts per row.
Parameters:
- grid (required) - grid of target records with id
meta
| def | func:alarmNavCounts |
| is | func |
| lib | lib:alarm |
| name | alarmNavCounts |
supertypes
| feature | Feature namespace of definitions formatted as feature:name |
| func | Axon function |
def
func:alarmTargets
alarmTargets(root)
Given a root object, return all alarm target records associated with it.
Parameters:
- root (required) - the root object to find alarm targets for
meta
| def | func:alarmTargets |
| is | func |
| lib | lib:alarm |
| name | alarmTargets |
supertypes
| feature | Feature namespace of definitions formatted as feature:name |
| func | Axon function |
def
func:alarms
alarms(targets: null, span: null, filter: null, pollHandle: null)
Given optional targets and/or a time span, return the current alarm records as a grid.
Parameters:
- targets (optional) - list of targets to query alarms for. If this parameter is null it will query everything
- span (optional) - DateSpan used to filter alarms. If this is null it will return alarms for all dates
- filter (optional) - filter used to filter alarm result
- pollHandle: when provided, performs an incremental poll and returns only changes since the given handle (legacy compatibility). The returned grid includes a new <pollHandle> you can pass back on the next call.
Return:
- A Grid of alarm records. The grid meta includes:
- pollHandle: an integer handle representing the time of this query.
Examples:
alarms()
alarms(@someEquipId)
alarms(readAll(equip and siteRef==@siteId))
alarms(null, today())
alarms(null, null, null, 123456) // poll using previous handlemeta
| def | func:alarms |
| is | func |
| lib | lib:alarm |
| name | alarms |
supertypes
| feature | Feature namespace of definitions formatted as feature:name |
| func | Axon function |
def
func:alarmsGetById
alarmsGetById(alarmId)
Given an alarm id, return the corresponding alarm record.
Parameters:
- alarmId: Ref of the alarm to retrieve
Examples:
alarmsGetById(@alarmId)meta
| def | func:alarmsGetById |
| is | func |
| lib | lib:alarm |
| name | alarmsGetById |
supertypes
| feature | Feature namespace of definitions formatted as feature:name |
| func | Axon function |
def
func:alarmsRemove
alarmsRemove(alarms)
Given a set of alarms (or alarm ids), remove them from the database and return the removed alarm records.
Parameters:
- alarms (required) - Alarm(s) to remove in any of the following formats: (Grid, Dict[], Ref[], Dict, Str, Ref)
Examples:
alarmsRemove(alarms())
alarmsRemove(@alarmId)
alarmsRemove("r:demo:alarm123")
alarmsRemove(readAll(alarm).keepCols(["id"]))meta
| admin | ✓ |
| def | func:alarmsRemove |
| is | func |
| lib | lib:alarm |
| name | alarmsRemove |
supertypes
| feature | Feature namespace of definitions formatted as feature:name |
| func | Axon function |
def
func:clearAlarmHistory
clearAlarmHistory(spanOrBefore: null, rebuild: false)
Clear alarm history records in the database based on the given parameters.
Parameters:
- spanOrBefore (optional) - DateSpan of entries to clear
- rebuild (optional) - if spanOrBefore is null and this is true, it will destroy the history database and recreate its schema.
meta
| admin | ✓ |
| def | func:clearAlarmHistory |
| is | func |
| lib | lib:alarm |
| name | clearAlarmHistory |
supertypes
| feature | Feature namespace of definitions formatted as feature:name |
| func | Axon function |
def
func:clearAlarmHistoryBefore
clearAlarmHistoryBefore(date)
Clear alarm history records before the given date in the database.
Parameters:
- date (required) - Deletes all alarm history entries before the specified date.
meta
| admin | ✓ |
| def | func:clearAlarmHistoryBefore |
| is | func |
| lib | lib:alarm |
| name | clearAlarmHistoryBefore |
supertypes
| feature | Feature namespace of definitions formatted as feature:name |
| func | Axon function |
def
func:readAlarmHistory
readAlarmHistory(targets: null, span: null)
Given optional targets and/or a time span, query the alarm history as a grid.
Parameters:
- targets (optional) - List/Grid of targets or target ids to query database for. If omitted this will query the database for all entities
- span (optional) - DateSpan to used to query the history database. If omitted this will return records for all dates in the database
meta
| def | func:readAlarmHistory |
| is | func |
| lib | lib:alarm |
| name | readAlarmHistory |
supertypes
| feature | Feature namespace of definitions formatted as feature:name |
| func | Axon function |
def
func:toAlarm
toAlarm(target, nsOrState, messageOrTags: null, occurred: null, priority: null, meta: null)
Given a target and either a legacy namespace or a new-style alarm state, transition the given namespace/target to the alarm state.
Parameters:
- targets (required) - list of targets to transition
- state (required) - to transition targets to (offNormal, normal, fault, ...)
- message (optional) - the message for the alarm transition
- occurred (optional) - the time the alarm occurred. If this is omitted, the system will use the current time
- priority (optional) - priority of the alarm. if this is omitted, the system will use this priority configured for the state.
- metadata (optional) - this is a miscellaneous dictionary of tags that will follow the lifecycle of the alarm. For compatibility, if "ackRequired" is set on the metadata, it will take precedence over the state's configured ackRequired flag.
This is an adapter kept for backward compatibility.
- If <nsOrState> contains ":", it is treated as a legacy namespace
Return:
- Legacy path returns a single <Alarm>.
- New path returns <Alarm[]>.
Examples:
toAlarm(@equipId, "highTemp", "Over temperature")
toAlarm(@equipId, "legacy:ns", {message:"Over temperature"})meta
| def | func:toAlarm |
| is | func |
| lib | lib:alarm |
| name | toAlarm |
supertypes
| feature | Feature namespace of definitions formatted as feature:name |
| func | Axon function |
def
func:toNormal
toNormal(targets, nsOrMessage: null, occurredOrTags: null, meta: null)
Given targets, transition alarms back to normal state using either the legacy API (namespace-based) or the new API (message/occurred/meta).
Parameters:
- targets (required) - list of targets to transition to normal
- message (optional) - the message for the alarm transition
- occurred (optional) - the time the alarm occurred. If this is omitted, the system will use the current time
- metadata (optional) - this is a miscellaneous dictionary of tags that will follow the lifecycle of the alarm. For compatibility, if "ackRequired" is set on the metadata, it will take precedence over the state's configured ackRequired flag.
This is an adapter kept for backward compatibility:
- If <nsOrMessage> contains ":", it is treated as a legacy namespace
Return:
- Legacy path returns a single <Alarm?>.
- New path returns <Alarm[]>.
Examples:
toNormal(@equipId)
toNormal(@equipId, "Cleared by operator")
toNormal(@equipId, "legacy:ns", {message:"Cleared"})meta
| def | func:toNormal |
| is | func |
| lib | lib:alarm |
| name | toNormal |
supertypes
| feature | Feature namespace of definitions formatted as feature:name |
| func | Axon function |
def
message
Message describing the alarm or reason for the alarm
meta
| def | message |
| is | str |
| lib | lib:alarm |
| tagOn | alarm, alarmRule |
supertypes
| val | Data value type |
| scalar | Scalar is an atomic value kind |
| str | Unicode string of characters |
def
metadata
Information related to the alarm that will live with the lifecycle of the alarm
meta
| def | metadata |
| is | dict |
| lib | lib:alarm |
| tagOn | alarm, alarmRule |
supertypes
| val | Data value type |
| dict | Map of name/value tag pairs |
def
occurred
Date/Time that the alarm actually occurred
meta
| def | occurred |
| is | dateTime |
| lib | lib:alarm |
| tagOn | alarm |
supertypes
| val | Data value type |
| scalar | Scalar is an atomic value kind |
| dateTime | ISO 8601 timestamp followed by timezone identifier |
def
routeOn
Filter that will select alarms to route
meta
| def | routeOn |
| is | str |
| lib | lib:alarm |
| tagOn | alarmRoute |
supertypes
| val | Data value type |
| scalar | Scalar is an atomic value kind |
| str | Unicode string of characters |
def
sourceRef
Reference to the source of the alarm. This is usually the entity that went into alarm
meta
| def | sourceRef |
| is | ref |
| lib | lib:alarm |
| tagOn | alarm |
supertypes
| val | Data value type |
| scalar | Scalar is an atomic value kind |
| ref | Reference to an entity |
def
state
State of the alarm
meta
| def | state |
| is | str |
| lib | lib:alarm |
| tagOn | alarm, alarmRule |
supertypes
| val | Data value type |
| scalar | Scalar is an atomic value kind |
| str | Unicode string of characters |
def
targetFilter
Filter which matches points to be commanded by this route
meta
| def | targetFilter |
| is | str |
| lib | lib:alarm |
| tagOn | alarmRoute |
supertypes
| val | Data value type |
| scalar | Scalar is an atomic value kind |
| str | Unicode string of characters |
def
toState
State of the entity when going into alarm
meta
| def | toState |
| is | str |
| lib | lib:alarm |
| tagOn | alarmHistory |
supertypes
| val | Data value type |
| scalar | Scalar is an atomic value kind |
| str | Unicode string of characters |
def
value
Value to write to the selected points
meta
| def | value |
| is | scalar |
| lib | lib:alarm |
| tagOn | alarmRoute |
supertypes
| val | Data value type |
| scalar | Scalar is an atomic value kind |