fwDeviceComment 9.3.0
fwDeviceComment Users Manual

Introduction

The fwDeviceComment component is part of the UNICOS framework and it provides a convenient way to attach short comments to UNICOS devices. A typical use case of the component is for a user to indicate a degraded mode of operation of a remote device, such as being out of order or undergoing maintenance, or to signal to other interested parties some other special conditions, such as upper and lower limits for various parameters, the meaning of a specific set-point, etc.

About this document

The present user manual provides a brief overview of the component capabilities and describes the most common functionality regularly employed in a production environment. The intended readership of this document consists of new users wanting to get acquainted with the fwDeviceComment component.

All the functionality and illustrations presented herein refer to the fwDeviceComment version 8.3.0. The source code of the component is hosted in a GitLab repository available at: https://gitlab.cern.ch/jcopfw/tools/fwDeviceComment

Device comments for single devices

This section will explain how to make use of the device comment functionality for single devices, in the framework of a UNICOS project, detailing the most common operations performed in production.

Prerequisites

In order to use the fwDeviceComment component, a WinCC OA project with the UNICOS framework installed is required. Since device comments can only be attached to devices, a UNICOS application must imported prior to employing the component.

Means of user interaction

The user can typically interact with the device comments via three main mechanisms, by using the following objects of the human-machine interface in the Management table:

  • Widget: Shows a status indicator signaling that comments are active for the associated device. No other comment information is displayed.
  • Faceplate/Panel: Displays the text of the active comments, along with other meta-data. Comments are displayed read-only.
  • Editing panel: Displays the text and all the meta-data of all comments, active and inactive, for the selected device. The user can add, activate or deactivate one comment at a time and can delete one or multiple comments.

There is also a fourth possibility of interacting with the device comments of multiple devices:

  • Management panel: Displays the text and all the meta-data of all comments, active and inactive, for multiple devices. The user can perform complex queries for device comments on multiple systems in addition to activating, deactivating or deleting multiple comments simultaneously.

Details of the interaction with the device comments via each of the mentioned graphical objects are provided further in the document.

Classification

The device comments can be in either one of two states:

  • Activated: Enables the dedicated indicator of the device widget that there are active comments; the comment information is displayed in the comment panel and/or in the device faceplate.
  • Deactivated: Does not enable the dedicated indicator of the device widget; the comment information is hidden in the comment panel and/or in the device faceplate.

The widget

The widget graphical object provides a simple mean to indicate whether any of the comments for its associated device are active. The Figure 1, Widget with comment, illustrates a widget for a device having active comments, while the Figure 2, Widget without comment, shows the widget for the same device, but with no active comments. The widget provides, thus, only a read-only, high-level binary indication of whether a device has, or does not have, any active comments.

Widget with comment
Widget without comment

The comments panel and the faceplate

While the widget provides a way to identify at a cursory glance whether a device has any active comments or not, it does not actually provide any information about the content and the meta-data of the comments themselves.

The simplest way to display the active comments associated with a device is to open comments panel by right-clicking the device to bring up the contextual menu and selecting the Comments entry, as illustrated in Figure 3, Widget Contextual Menu, and Figure 4, Device Without Comments.

Widget Contextual Menu
Device Without Comments

The illustration pertains to the case of a device with no active comments.

Alternatively, the device comments can also be displayed in the faceplate of the device. The graphical display of the comments is identical, with the exception that in this case the comments panel is embedded in the faceplate. To activate this view, either double-click or right-click the device to bring up the contextual menu and then select the Faceplate entry, as shown in Figures 5 and 6. The list of active comments will be displayed in the Comments tab of the faceplate.

As can be seen in Figure 6, Widget Device Comments Panel, the embedded comments panel displays the following information pertaining to the active comment:

  • The time-stamp when the comment was either created or last activated.
  • The user who added the comment (next to the time-stamp).
  • The comment text itself (first line below the time-stamp).
  • The additional information for the comment (second line below the time-stamp).
Widget Contextual Menu Faceplate
Widget Device Comments Panel

The illustration pertains to the case of a device with a single active comment.

Both mean of displaying comment information presented in this subsection are read-only, i.e. there is no way through which the user can interact with the device comments, in order to add, (de)activate or delete them. To modify the comments, the editing panel needs to be employed. In order to open the editing panel, the Manage ldots button in Figures Device Without Comments or Widget Device Comments Panel needs to be clicked.

The Editing Panel

The device comments editing panel is depicted in Figure 7. It can be employed to add, activate and deactivate single comments and to delete one or multiple comments.

Warning! Once a comment is created, its text, additional information and any other meta-data become immutable, i.e. it is no longer possible to edit any of the information. The only permitted operations are changing the active or inactive status and deleting the comment.

Device Comments Edit Panel

The comments editing panel consists of a main tabular interface displaying all the comments associated with the device in reverse chronological order, whether active or inactive. The following fields are listed in the central table of the panel:

  • The time-stamp when the comment was either created or last activated.
  • The user who has authored the comment.
  • The comment text.
  • The additional information for the comment.
  • The name of the WinCC OA system which contains the device. Warning! This may be a different system than the one where the comment originated from.
  • The hostname where the WinCC OA system containing the device is running.
  • The status of the comment, which can be either active or inactive.

The interface also presents various controls for deleting a single or multiple comments on the top right side of the panel. For adding a new comment, the user may fill in the comment text and any additional information using the two text fields below the main table, selecting the state of the comment via the combo box (active/inactive) and by pressing the comment insertion button.

An option to export the comment information table for the current device is also provided and can be activated by clicking the button in the lower left corner of the interface.

Warning! It may occur that some or all of the graphical interface elements are disabled, i.e. their appearance is grayed-out. This usually indicates that the currently logged-in user does not have the privileges required to perform certain operations on the device comments. The user may check the required privileges by clicking on the Comment rights button which will open the management panel for comment access rights, illustrated in Figure 8. Using this panel requires specific knowledge regarding the users access rights and privileges and should be done only by the industrial controls expert or system administrator.

Device Comment Access Rights

Advanced management of device comments

The previous section has discussed the mechanisms through which a user can interact with the device comments of a single device. However, there is sometimes the need to apply bulk operations, i.e. activation, deactivation and deletion, to a large number of comments distributed among a multitude of devices. One such use-case could be, for instance, deleting all the old comments for the devices of a subsystem that has just come out of maintenance mode. For this and other similar purposes the device comments management panel, illustrated in Figure 9, is the appropriate interface.

Device Comment Management Panel

The top part of the panel presents the user with a plethora of filtering options, through which device comments meeting certain criteria will be retrieved and displayed in the central tabular part. The array of filtering options is diverse and allows searching for comments that, e.g., belong to a specific system or application, have been last activated or created within a specified time interval, refer to a specific device or to a class of devices, are active or not, etc.

The right side of the main table contains navigation button which enable the user with to scroll through the comments one item at a time or one page at a time, in addition to jumping directly to the top and bottom of the list.

The lower left part holds three buttons that allow bulk operations on the items that have been selected in the main table, such as activating, deactivating or deleting them — before any of these operations are carried out, the user must confirm the action via a pop-up dialog. A fourth button in this group opens the device comment import/export panel, depicted in Figure Device Comment Import/Export. This panel enables the user to save and eventually restore the device comments, e.g. such as when transferring a WinCC OA project to a new machine, etc.

Device Comment Import/Export

Management of the access rights for device comments

Warning! This section discusses topics that require specific knowledge regarding the users access rights and privileges. The operations described herein should only be attempted by specially trained individuals, such as industrial controls expert or system administrators.

This following material describes the recommended way of implementing access rights. As such, is should be treated as being advisory, rather than mandatory, in nature.

The fwDeviceComment component relies on fwAccessControl to enable or disable parts of the user interface that allow a user to add, activate, deactivate and delete comments. The access rights of the user are checked against a list of privileges, in the form DOMAIN:privilege. If the user holds the necessary DOMAIN:privilege for a comment action (e.g. delete all), then the graphical interface part related to this action (e.g. the Delete all button) will be enabled.

Warning! It is not recommended to use a global, catch-all, domain/privilege combination to set this up, such as UNICOS:expert, UNICOS:operator, etc.

Instead, the creation of a dedicated domain is endorsed, domain that must be called e.g. DEVICECOMMENT, eventually prefixed by an system or application name or any other relevant term, such as for instance CV/DEVICECOMMENT.

The domain should contain the following privileges:

  • DEVICECOMMENT:canAddMine: A user holding this privilege can add, activate, deactivate and delete only the comments that he/she has authored.
  • DEVICECOMMENT:canDeactivateAll: A user holding this privilege can activate and deactivate any comment, including those authored by other users.
  • DEVICECOMMENT:canDeleteAll: A user holding this privilege can delete any comment, including those authored by other users.
  • DEVICECOMMENT:canEditCommentRights: A user holding this privilege can edit the required privileges for actions on comments. Wanirng! By default, the root user account always has this privilege.

At installation time, the fwDeviceComment component will scan the system for the recommended domains and privileges and will automatically set up the appropriate access controls for device comments. Thus, if a system is configured in the aforementioned way before installing the component, little to no extra work is required for setting up the appropriate access controls.

Warning! The component will not overwrite access control settings if they are already configured on the system where it is being installed, i.e. in case of upgrading fwDeviceComment to a newer version, except when this is explicitly stated in the release notes.

There are cases, however, when an advanced user will want to manually adjust the access controls for comments. For such situations, the generic access control panel, illustrated in Figure 8, Device Comment Access Rights, provides an intuitive interface through which fine-grained control can be exerted over the required privileges for specific operations on comments.

Propagation of the access rights for device comments to remote systems

Warning! This section discusses topics that require specific knowledge regarding the users access rights and privileges. The operations described herein should only be attempted by specially trained individuals, such as industrial controls expert or system administrators.

In the case of a hierarchy of WinCC OA distributed systems it is sometimes convenient to have the same access controls across all systems. In the case of a large-scale migration to new computing facilities or of the re-installation of projects this can be easily achieved by setting up the recommended domains and privileges. The fwDeviceComment component will then automatically configure the comments access rights. But in the situation where a large-scale change occurs on systems already in production, this is no longer an option.

In order to avoid the situation where a user would have to manually alter the access rights on each individual system, an expert tool is provided for this purpose, in the form of a panel depicted in Figure 11.

Propagation of Comments Access Rights Panel

Warning! The panel is only accessible to users having the privilege to modify the access control settings for device comments, i.e. the root user account and any other user holding the privileges the listed in the lower right part of the management panel for comment access rights (see Figure 8, Device Comment Access Rights).

Warning! The panel can be opened by pressing the [CTRL]-[SHIFT]-[R] key combination while having the management panel for comment access rights open (see Figure 8).

As can be seen from Figure 8, the top part of the interface displays access control information pertaining to the local system. The system name, host name and WinCC OA numeric ID, along with the installed version of the component are shown. Also shown are the minimum compatible versions of fwDeviceComment with the current access control scheme and the local domains used to determine the comment privileges.

The central and main part of the panel in Figure 11, Propagation of Comments Access Rights Panel, is taken up by a tabular display of all the remote peers know to the current system. The table columns list their WinCC OA system name and numeric ID along with the remote host name, and the corresponding installed version of fwDeviceComment. The rows for the systems having versions of the component that are either unknown or incompatible with the current access rights scheme are hatched. The next two columns indicate whether the comment access rights of the remote system are identical to the ones on the local system and if all the local domains used to determine comment privileges also exist on the remote peer.

The local access rights privileges for device comments will be identically configured only on the remote systems that have a check mark in the corresponding column of the main table. The selection can be undone by refreshing the table from the button in the lower-left corner of the panel, which will also trigger a new query for remote peers and for the relevant fwDeviceComment information. The propagation of the access rights will take place once the user has clicked the Propagate to remote systems button. Status about the result of this operation will by indicated for each remote system in the last column of the table.