AlarmScreenNg
0.9.5
|
The AS EWO is called AS.ewo, it can be found in component installation directory under
This sections describes API of AS EWO for WinCC OA panel, where EWO is placed: properties, methods and events.
This is the most important property of AS EWO because AS EWO is not able to operate without the name of internal DP containing the valid basic configuration in JSON format.
Furthermore, all other settings for AS EWO (except for admin settings) are tightly coupled with basic configuration, and it is reflected in the structure of DP types, used for storing those other settings. For example, the filter that contains alarm property named 'alias' was saved by user when working with particular basic configuration. Later this filter, in principle, can be used also for other basic configuration, but: what if that 'other basic configuration' just does not contain the alarm property named 'alias', or if the meaning of 'alias' is dfifferent in other basic configuration? Of course, in such case previously saved filter will not wotk as expected - just because the filter was saved for another basic configuration.
The alarm data, read from AS EWO, are passed to CTRL script in panel (in methods or events) as CTRL data type mapping
, where keys are the names of alarm properties.
The value of this EWO property determines what shall be the values in such mapping
. Two values are possible:
bool
with two possible values: true
and false
string
, exactly as they appear to user in The Alarm Table. In such case, the alarm property holding boolean value can be returned as strings "YES"/"NO", or "CAME"/"WENT", or in some other format, selected for displaying this particular property in table. Note that some (but not all!) of methods of AS EWO have an argument, allowing to override this 'default' setting.
During operation AS EWO may produce some text messages: to inform about critical errors, warnings, or just to produce messages for debugging (for developer). These messages are sent into two places:
Every message is assosiated with one of possible levels of severity: Debug, Info, Warnign, Critical.
The following properties of AS EWO control the process of producing such messages, as we as content of produced messages.
Property | Description |
---|---|
logSeverity | Mininum level of severity for messages which shall appear in WinCC OA log; the default value is Warning |
userlogSeverity | Minimum level of severity for messages which shall be buffered (and observed by user) in AS EWO itself; the default value is Warning. |
logTimestamp | true if message text shal include timestamp when message was produced by AS EWO; the default value is false |
logFunction | true if message text shall include the name of function that produced the message; the default value is false |
The methods in this secction of document are grouped according to their purpose (intended usage). In principle, methods described can be used for other purposes if needed.
When new basic configuration is set to AS EWO, the EWO shall notify the panel in order to make necessary adjustments for new basic configuration. This can include, for example: loading and applying default user settings, connecting to all (or some) of systems etc.
The problem occurs when panel, containing AS EWO, is just created/opened: there is (short) period of time when EWO itself is ready, and may fire events for CTRL code in panel, but the panel is not ready yet to process the events from EWO. The dedicated method of EWO was introduced, that normally shall be called from the Initialize event of panel;
The method returns the name of currently used basic configuration DP.
As described in basic configuration, the configuration may contain string for FROM and WHERE clauses of query. They can be not only fixed strings, but also parametrizable strings.
The following two methods of EWO are used for passing to EWO list of strings which will substitute parameters in FROM and WHERE clause templates.
is used to pass parameter for FROM template of query,
is used to pass parameter for WHERE template of query.
Both method may return non-empty string, containing error description, if calls were not successful. Note that 'successful' doesn't mean that query with passed parameters will work as expected, this doesn't even mean that query syntax is correct: 'success' here just means that parameters were passed to alarm source.
The methods described here are used for operations with alarm properties, defined in basic configuration, and with set of columns shown in table.
Get all alarm properties, defined by basic configuration. Every mapping in returned list contains the following information for alarm property:
string
with internal identifier of this alarm property, see Alarm properties. string
with the name of attribute of _alert_hdl DPE config, corresponding to this alarm property. Empty string if alarm property does not directly correspond to one of attributes of _alert_hdl config. true
if this property is part of atime
for alarms (reminder: atime
includes alarm DPE, alarm time and count of alarm within 1 msec)
Get all columns of Alarm Table, defined in basic configuration. Every mapping in returned list contains the following information for table column (see constants AS_TABLE_COL_xxx in CTRL library AlarmScreenNg.ctl). The method was introduced for UNICOS-style popup menu where column visibility can be modified from menu.
int
with enumerated value for the source of this column. See constants AS_TABLE_SOURCE_xxx in CTRL library AlarmScreenNg.ctl for possible values. string
, containing internal name (ID) of alarm property for this table column, see Alarm properties. string
, containing header for this table column. int
- current width of this column in table [Pixels] bool
indicating if user is allowed to hide this column of not bool
indicating if this column is currently visible in table or not
Toggle the visibility of column with given index, the index must correspond to one of columns returned by method getTableColumns()
Set all columns of table to 'visible' state.
The methods of this group are used to force connection/disconnection of AS EWO to WinCC OA systems.
Connect to system with given name; returns true
if connection was successful. If current source mode for AS EWO is not Live, then AS EWO first switches to Live mode, and only after tries to connect to given system
Disconnect from system with given name; returns true
if disconnection was successful. The method only works if AS EWO's source mode for AS EWO is Live.
Get list of all systems names to which AS EWO is connected now. If current source mode for AS EWO is not Live, then the method returns list of systems to which AS EWO was connected when it was in Live mode.
Starts query for data from archive. If current source mode for AS EWO is not History, then AS EWO first siwtches to History mode, then starts the query. Current filter remains unchanged, i.e. the query will be performed with current filter.
The methods of this group are used to read details of alarms shown in Alarm Table. Note that 'details' includes not only alarm properties, visible in table columns, but rather all alarm properties known inside AS EWO. The data for one alarm is mapping
with keys = names of alarm properties, and values = value of that alarm property.
Get details of all alarms in table. The argument format
allows to override default setting for alarmDataRole EWO property. Two values are allowed for this argument:
string
shown in table
Get details of all alarms in selected row(s) in table. The format
argument is the same as for getAllRowsData()
method above.
If alarms are displayed as hierarcical tree, then selecting any group node in the tree is interpreted as selecting all alarms = descendants of this group node.
Get details of all alarms in currently visible rows in table. The format
argument is the same as for getAllRowsData()
method above.
Get details of all unacknowledged alarms in table. Note that alarms for acknowledgement are always returned using "edit" data role, independently of the value of alarmDataRole EWO property.
Get details of all unacknowledged alarms, found in selected rows in table in table. Note that alarms for acknowledgement are always returned using "edit" data role, independently of the value of alarmDataRole EWO property.
The interpretaion of 'selected' for hierarchical tree is different from getSelectedRowsData()
method: here only explicitly selected rows with alarms are considered, the selection of group nodes is not propagated down in tree hierarchy.
Get details of all unacknowledged alarms with direction WENT in table. Note that alarms for acknowledgement are always returned using "edit" data role, independently of the value of alarmDataRole EWO property.
Very specific method, used for functionality like 'copy to clipboard' of popup menu. The method returns string with space-separated values in columns of given table row.
The argument row
really describes the single row in table, but why dyn_int
? In case of flat alarm table the row
argument shall contain just one item: the index of required row in table (zero-based). However, if alarms are displayed in hierarchical tree, then dyn_int
shall contain the list of numbers, describing the 'route' from root of tree to required row with alarm data. This is illustrated on the following picture (tree with 2 levels of grouping):
In this example dyn_int
shall contain 3 values {2, 1, 3} in order to address highlighted row with alarm data.
I.e. in case of tree view, the row
argument shall contain number of values equal to number of grouping levels plus one.
The AS EWO itself doesn't make any assumptions on how exactly access control is configured and operated, Instead, AS EWO just provides methods, allowing to modify appearance of different elements (widgets) in EWO according to access rights of given user. The approach is simple, see Action names.
Set the state of widget inside EWO according to the ability of current user to execute given named action. The state
shall conatin one of supported values (see constant ALARM_SCREEN_ACCESS_ACTION_xxx in CTRL library AsNgAccessControl.ctl):
Set the state of widget inside EWO to the fixed state, independent on the ability of current user to execute given named action. The method was introduced for initial configuration of AS EWO's appearance,in particular, to hide controls which do not make sense for current project configuration.
The state
shall conatin one of supported values (see constant ALARM_SCREEN_ACCESS_ACTION_xxx in CTRL library AsNgAccessControl.ctl):
Discard the fixed state for action, previously set using setFixedActionState(). After this call action will return to 'normal' state control, based on access rights.
Get the names of all actions, known to AS EWO. This method, together with previous one, can be used in processing the changes in access rights of current user, using the following algorithm:
setActionEnabled()
Add the custom button to toolbar in the footer area of AS EWO. The EWO itself doesn't know what to do with added buttons, EWO just fires corresponding event, which shall be processed by CTRL code in panel.
Arguments:
getPath()
function of CTRL, see WinCC OA online help. This argument can be empty, in such case label argument must be non-empty. In case of success method returns empty string; in case of error the string with error description is returned.
The method is used to read the value of specific option, given in basic configuration. The parameter is the name (ID) of specific option as it is specified in basic configuration.
Get the current structured filter of EWO as a string in JSON format, suitable for saving current filter to DP. The compact
argument allows to choose between compact and pretty formatted JSON string. See filter JSON syntax.
Apply previously saved filter to AS EWO. Normally the value of jsonString
argument is read from DP where filter was saved before; the value shall contain the definition of structured filter in JSON format. The method returns string
with description of error if parsing/applying filter has failed; or empty string if processing was successful
Get the current user settings of EWO (see User Settings) as a string in JSON format, suitable for saving current user settings to DP. The compact
argument allows to choose between compact and pretty formatted JSON string.
Apply previously saved user settings to AS EWO. Normally the value of jsonString
argument is read from DP where user settings were saved before; the value shall contain the user settings in JSON format. The method returns string
with description of error if parsing/applying user settings has failed; or empty string if processing was successful
Get the current statistics, collected by single filter in Filter View of AS EWO (see also Filter View editor). The filterId
argument shall contain not the name of filter, but rather the name of DP where definition of this filter is stored. This must correspond to one of filters, shown in filter view area. In case of success the method returns mapping
, containing values for all keys, listed in the table, plus two more keys:
Key | Value |
---|---|
itemTextFormat | The text format used for visible text of all items in filter view (see text templates) |
itemToolTipTextFormat | The text format used for tooltip text of all items oinfilter view (see text templates) |
In case of error, the returned mapping
contains the only key "error", where value is a string
with error description.
The AS EWO has a button for exporting table content to CSV file. In addition, the exporting operation can be initiated from CTRL code using the method
The method has the following arguments:
true
means writing all rows to output file, false
- only selected rows. true
then column headers will also be written to output file. true
means that content of grouping column shall also be written to output file.
Get the string, uniquely identifying this instance of AS EWO in UI manager. The method is used in CTRL code for building name of module, working with particular EWO. The unique identifier can also be used for other purposes if needed.
It was mentioned in Actions description that:
AS EWO needs to have notifications about event like connection/disconnection of individual systems in distributed system. One of mechanism, provided by WinCC OA for this purpose, is sysConnect() function (see WinCC OA help). However, the sysConnect() is not available in WinCC OA API, hence, C++ code of AS EWO can't use the sysConnect() call directly.
One possible solution is the following:
AS EWO has also some methods which are not supposed to be used in normal operation. These methods were added to be used by integration tests and/or for debugging.
The method is used when testing the process of reading alarms from RDB archive, It was observed during the test preparation that in one case filter condition, passed to alarm source, was not converted to query predicate, while it should be converted. However, that was very indirect observation (looking at query text at WinCC OA log). In order to make it possible for automatic test procedure to check for such kind of problems, this method was introduced. The keys in this map are (see class AbstractAlarmSource in C++ code for more details):
time
: time when query preparation has startedtime
: time when query has been sent to DB servertime
: time when first results of query have arrived from DB servertime
: time when query was finished, successfully or otherwiseint
: number of filters passed to alarm sourceint
: number of filters converted to query predicates This method is used to display total number of alarms instances in alarm source, plus total number of alarm attributes in these alarm instance. Calculated counters are not returned to caller, instead they are just pronted in WinCC OA log.
Probably, the most important and widely used event of this EWO. This event is fired on many occasions, including change of basic configuration, activating different controls (widgets) inside AS EWO.
The general meaning of this event is: something happened inside AS EWO, that can't be processed by EWO itself, and this requires some processing by CTRL code.
Normally this event shall be processed by CTRL function
which is defined in CTRL library AlarmScreenNgEwo.ctl
The only argument of this event contains the following keys (all keys are strings):
string
identifying requested action, see Action names. string
, containing the name of CTRL library to be loaded for processing this event. See Basic configuration. string
, containing the name of CTRL function to be called for processing this event. See Basic configuration. int
, enumerating current source type for AS EWO; the following values are possible:
Next important event, which is fired in response to user's mouse button events on table row with alarm data. The only argument for this event contains all keys for event ctrlActionRequested()
, plus some more keys:
mapping
with information on event source, contains the following keys of type string
: int
, indicating which mouse button caused this event int
, X-ccordinate of mouse event that caused this event. The coordinate is in screen's coordinate system int
, Y-ccordinate of mouse event that caused this event. The coordinate is in screen's coordinate system dyn_int
, containing the index of table row where mouse event occured. See the EWO's method getTableRowAsString() for description of content of this dyn_int
int
, enumerated source of information for column where mouse event occured. See constants AS_TABLE_SOURCE_xxx in CTRL library AlarmScreenNg.ctl for possible values. string
, identifying the alarm property shown in column where mouse event occured, see Alarm properties mapping
with all properties of alarm in a row where mouse event occured, see Alarm properties
This event is fired when the state of alarm source in EWO has changed. Initially event was introduced for testing, but it can also be used for other purposes. The only argument of this event contains the following keys (all keys are strings):
int
, enumerating current source type of AS EWO; the following values are possible: AS_NG_EWO_SOURCE_xxx
in CTRL library AlarmScreenNgEwo.ctl
This event is fired when the number of alarms, processed by source in EWO, have changed. Initially this event was introduced for testing, but it can also be used for other purposes. The only argument of this event contains the following keys (all keys are strings):
int
, enumerating current source type of AS EWO; the following values are possible:
This event is fired when one of custom buttons was clicked by user. The only argument of this event contains the following keys (all keys are strings):
string
identifying requested action. The value corresponds to actionName
argument for addCustomButton() method which added this button. string
, containing the name of CTRL library to be loaded for processing this event. See Basic configuration. string
, containing the name of CTRL function to be called for processing this event. See Basic configuration. int
, enumerating current source type of AS EWO; the following values are possible: int
, X-ccordinate of center of custom button that was activated. The coordinate is in screen's coordinate system. int
, Y-ccordinate of center of custom button that was activated. The coordinate is in screen's coordinate system. The values screenX and screenY are added to arguments in order to allow for CTRL code to display menu when processing this event, see popupMenuXY()
in WinCC OA online help.