Understanding CygNet Alarm Manager Operations
The CygNet Alarm Manager (CAM) has four operations. They are:
- COUNT — Calculates the number of current alarms for a given filter
- HISTCOUNT — Calculates the number of alarms in a period window
- REPORT — Compiles various predefined reports. A report operation is a superset of a single query operation.
- QUERY — Compiles a single predefined report
Each operation is described below.
COUNT Operation
The COUNT operation uses the defined CAS services along with the filter defined in the <Filter> node to calculate the number of alarms. The result is posted to the point defined in the <CountPoint> node with the time of execution as the timestamp.
The following is a sample of the XML format for this operation:
<Job>
<Operation>Count</Operation>
<Description>System - Standing Alarms Total</Description>
<Filter Name="System - Standing Alarms Total">
<FilterFilePath>System - Standing Alarms Total.xml</FilterFilePath>
</Filter>
<Output>
<CountPoint>QAQBQCQD.UIS:QAQBQCQD_CTSTATOT</CountPoint>
</Output>
</Job>The following table describes the configuration elements of the COUNT operation.
| Element | Description |
|---|---|
|
<Operation> |
The type of CAM operation defined. |
|
<Description> |
A description of the job. The text provided in the element is only used in logging to the Output File. |
|
<Filter> |
The file name of a valid filter file and filter. See Filtering CygNet Alarm Manager Operations for more information. |
|
<FilterFilePath> |
The name of the filter file. This file name will be used along with the Default Filters Path defined in the CAM Module Configuration to form a fully qualified file path. |
|
<Output> |
The destination of the operation's output. |
|
<CountPoint> |
A valid CygNet Tag String specifying the point to post the result. |
HISTCOUNT Operation
The HISTCOUNT operation is used to calculate alarm counts based upon the defined historical alarm logging services (ELSALM), the supplied time range and a filter.
The HISTCOUNT operation has two modes. The <Backfill> node determines each mode. Valid values for <Backfill> are "Yes" and "No".
When <Backfill> is set to "No", the HISTCOUNT operation is based on the execution time. At execution time, a time window is computed based on the <Period> and <Period Type> node values. The <Period> node defines the "width" of the time window in minutes. The <Period_Type> node defines if the window is "Fixed" or "Sliding".
- Fixed — A period that is bound to an increment of the <Period>. For example, if the current time is 10:05:15 and the <Period> node is set to 10 minutes, the current "Fixed" time window would be 10:00:00 to 10:09:59
- Sliding — A period that is based strictly on the current time. Given the same example of the current time being 10:05:15 and the <Period> node set to 10 minutes, the current "Sliding" time window would be 9:55:15 to 10:05:15.
Once a time window has been determined, the defined ELSALM services are queried with the supplied filter and time range to calculate the number of alarms. The point defined in the <CurPeriodPoint> node is used to post the value calculated for the current time period with a time of execution as the timestamp.
When <Backfill> is set to "Yes", the HISTCOUNT operation will determine the time windows within the date range specified by the relative time strings defined the <Start_Date> and <End_Date> nodes. The <Period_Type> is assumed to be "Fixed" for the backfill option.
The execution of the HISTCOUNT operation in backfill mode is similar to what is described above. Once the <Start_Date> has been calculated, the engine will use it to define the time window based on the <Period> and will iterate the calculation until it reaches the <End_Date>. A result value will be posted at each window to the point defined in <CurPeriodPoint>.
The following is a sample showing the XML format for this job:
<Job>
<Operation>HISTCOUNT</Operation>
<Description>10-Minute - Total</Description>
<Period>10</Period>
<Period_Type>Fixed</Period_Type>
<Contract_OffSet>0</Contract_OffSet>
<Backfill>No</Backfill>
<Start_Date>d=1</Start_Date>
<End_Date>H</End_Date>
<Filter Name="ELSALM Alarm Filter">
<FilterFilePath>System - History Total.xml</FilterFilePath>
</Filter>
<Output>
<CurPeriodPoint>QAQBQCQD.UIS:QAQBQCQD_CTAMCRTTOT</CurPeriodPoint>
</Output>
</Job>The following table describes the configuration elements of the HISTCOUNT operation.
| Element | Description |
|---|---|
|
<Operation> |
The type of CAM operation defined. |
|
<Description> |
A description of the job. The text provided in the element is only used in logging to the Output File. |
|
<Period> |
The "width" of a period in minutes to use for the calculation. For example, a value of 10 would mean a 10-minute window. |
|
<Period_Type> |
Used to set the type of time window. Valid values are "Fixed" or "Sliding". See HISTCOUNT Operation for more information on type. |
|
<Contract_OffSet> |
The contract hour offset to use in the calculation. Use 0 for no contract hour. |
|
<Backfill> |
The backfill value is used to set the Backfill option. Valid values are "Yes" or "No". |
|
<Start_Date> |
The starting date to use when the <Backfill> is set to "Yes". Valid values are relative timestamps. For example:
In the above examples, "d" and "h" represent the interval. Other intervals include:
|
|
<End_Date> |
The ending date to use when the <Backfill> is set to "Yes". See <Start_Date> for valid values. |
|
<Filter> |
The file name of a valid filter file and filter. See Filtering CygNet Alarm Manager Operations for more information. |
|
<FilterFilePath> |
The name of the filter file. This file name will be used along with the Default Filters Path defined in the CAM Module Configuration to form a fully qualified file path. |
|
<Output> |
The destination of the operation's output. |
|
<CountPoint> |
A valid CygNet Tag String specifying the point to post the result. |
REPORT Operation
The REPORT operation provides the ability for reporting of the KPI values as well as other derived Alarm Management metrics. The following is the format for the REPORT operation:
<?xml version="1.0" encoding="utf-16"?>
<KpiJobDefinition>
<Config>
<OutFile>System Reports.txt</OutFile>
<AudServices></AudServices>
<!--Semicolon separated list of AUD services -->
<CasServices></CasServices>
<!--Semicolon separated list of CAS services -->
<CvsServices></CvsServices>
<!--Semicolon separated list of CVS services -->
<ElsAlmServices></ElsAlmServices>
<!--Semicolon separated list of ELSALM services -->
<Status_Point>SITE.UIS:QAQBQCQD_STKPIR</Status_Point>
<ExecTime_Point>SITE.UIS:QAQBQCQD_TMKPIR</ExecTime_Point>
</Config>
<Jobs>
<Job>
<Operation>Report</Operation>
<!--List of filters used by report sections -->
<Filter Name="System Total">
<FilterFilePath>System - History Total.xml</FilterFilePath>
</Filter>
<Report>
<FileName>System Reports</FileName>
<!--The base file name of the report file. -->
<FilePath></FilePath>
<!--The location where the report file is stored. -->
<TemplateFile></TemplateFile>
<!--The location of the template file to use. -->
<FileFormat>xlsx</FileFormat>
<!--The file format of the report: XLSX, PDF, XML, CSV -->
<FileNameDateAppend>3</FileNameDateAppend>
<!--Used to append date and time to file name: 1=yyyyMMdd 2=hhmm 3=yyyyMMdd hhmm -->
<!-- See each report for Section details -->
<Section>
<Title> xxxxxxx </Title>
<KPI Specific Elements>
</Section>
<Section>
<Title> xxxxxxx </Title>
<KPI Specific Elements>
</Section>
</Report>
</Job>
</Jobs>
</ KpiJobDefinition>The following table lists the nodes contained within the REPORT operation.
| Element | Description |
|---|---|
|
<Operation> |
The type of CAM operation defined. |
|
<Filter> |
The file name of a valid filter file and filter. The Name attribute of the <Filter> node is referenced by the <Section> nodes and must be unique. See Filtering CygNet Alarm Manager Operations for more information. |
|
<FilterFilePath> |
The name of the filter file. This file name will be used along with the Default Filters Path defined in the CAM Module Configuration to form a fully qualified file path. |
|
<Report> |
Marks the report node of the job definition file. |
|
<FileName> |
The base file name of the report file. The name cannot exceed 34 characters. This includes the date and time if appended. |
|
<FilePath> |
The location where the report file is stored. This can be left blank if the default file path is to be used. |
|
<TemplateFile> |
The location of the template file to use. This can be left blank if the default file path is to be used. |
|
<FileFormat> |
The file format of the report. Valid values include XLSX, PDF, XML, CSV. |
|
<FileNameDateAppend> |
Used to append date and time to file name. Valid values: 0 — No date time 1 — Date formatted as yyyyMMdd 2 — Time formatted as hhmm 3 — Date and time formatted as yyyyMMdd hhmm |
|
<Section> |
There can be one or more sections to the report. See CygNet Alarm Manager Reports for more information. If the output format is XLSX, then each section will be an individual Worksheet Tab in the Excel File. If the output format is CSV, an individual file will be created for each section. Important: If the <Section> node (in a Report or Query job definition) contains a <Filter> name, that name must match exactly with the filter Name attribute specified in the <Filter> element at the top of the <Jobs> node and with the Name of the filter the filter file. See Filtering CygNet Alarm Manager Operations for more information. |
QUERY Operation
The QUERY operation offers the same abilities as reports but without the formatted output. The QUERY operation performs the same as the REPORT operation with a few exceptions. A QUERY will output to a file and will just return an XML string. Used in combination with JobRunner, a QUERY is used by CygNet Studio screens to obtain the same raw data a report. The raw data can be used for building screens and workflows. This is useful in building ad-hoc reporting screens where the output is presented to the user in a grid, for example. The major difference between a QUERY and a REPORT is that a QUERY can only contain a single Report section.
Here is a sample configuration:
<?xml version="1.0" encoding="utf-16"?>
<KpiJobDefinition>
<Config>
<OutFile>System Reports.txt</OutFile>
<AudServices></AudServices>
<CasServices></CasServices>
<CvsServices></CvsServices>
<ElsAlmServices></ElsAlmServices>
<Status_Point>QAQBQCQD.UIS:QAQBQCQD_STKPIR</Status_Point>
<ExecTime_Point>QAQBQCQD.UIS:QAQBQCQD_TMKPIR</ExecTime_Point>
</Config>
<Jobs>
<Job>
<Operation>Report</Operation>
<!--List of filters used by report sections -->
<Filter Name="System Total">
<FilterFilePath>System - History Total.xml</FilterFilePath>
</Filter>
<Report>
<Section>
<Title>Alarm Event Records</Title>
<QueryType>ElsCollect</QueryType>
<FilterType>ELSALMQUERY</FilterType>
<Start_Date>H=0 M=0 S=0</Start_Date>
<End_Date>H=23 M=59 S=59</End_Date>
<Contract_OffSet>0</Contract_OffSet>
<Filters>
<Filter>System Total</Filter>
</Filters>
<Columns>
<Column item="facility" text="Facility"/>
<Column item="udc" text="UDC"/>
<Column item="almtagl" text="Long ID"/>
<Column item="description" text="Description"/>
<Column item="pt_value" text="Value">
<SummaryCalc>Sum</SummaryCalc>
<SummaryCalc>Average</SummaryCalc>
<SummaryCalc>Min</SummaryCalc>
<SummaryCalc>Max</SummaryCalc>
</Column>
<Column item="eventtime" text="Time"/>
<Column item="key" text="Key"/>
<Column item="details" text="Details"/>
<Column item="comments" text="Comments"/>
</Columns>
</Section>
</Report>
</Job>
</Jobs>
</ KpiJobDefinition>Queries are used in the CAM in the sample CygNet Studio screens. See CygNet Alarm Manager Screens for more information.
More:
Filtering CygNet Alarm Manager Operations
