Re: BEAST configuration

["Kasemir, Kay" <kasemirk@ornl.gov>]

Hi:

You're right that the XML format is not documented in detail beyond some basic schema file, https://github.com/ControlSystemStudio/cs-studio/blob/master/applications/plugins/org.csstudio.alarm.beast.configtool/AlarmConfigurationSchema.xsd.
That schema does not include the <automated_action>, which was added to support the ITER-provided alarm notifier.

The XML format is mostly used as a backup and restore of the alarm configuration, using the AlarmConfigTool to import/export the alarm configuration to/from RDB <-> XML.
The CSS dokbook Alarm System chapter, http://cs-studio.sourceforge.net/docbook/ch14.html, has some examples for that:
# Display all parameters
AlarmConfigTool -help

# List alarm tree root names
AlarmConfigTool -list

# Export alarm configuration to XML file
AlarmConfigTool -export -root demo -file demo.xml
 
If you want to create the XML-based configuration from for example some custom script of yours, you're of course free to do that, comparing the configuration you see in the GUI with the XML elements.

> I have an idea what "guidance" is, but what is the difference between "display" and "command"?
The fundamental description of each alarm configuration aspect is meant to be described in the online help of the alarm system.
(https://github.com/ControlSystemStudio/cs-studio/blob/master/applications/plugins/org.csstudio.alarm.beast.ui/html/alarm_system.html )

See there:

---------
Guidance messages:
    If there are guidance messages configured for the item, it will be displayed here one by one.

Related displays:
    If there are related displays configured for the item, it will be displayed
    here one by one. When you click one of them, the related display will be launched.

Commands:
    If there are related commands configured for the item, it will be displayed
    here one by one. When you click one of them, the related command will be executed.
---------


-> That's the  "guidance", "display" and "command" you also see in the XML.

Later there's more on each:

---------
Guidance

A list of guidance messages for this item. Note
that items also "inherit" all guidance messages
of the higher-level components (System, Subsystem, ...) under which
they are listed, i.e. their "parent" components from
the alarm configuration hierarchy.

Each guidance is separated into two parts:
Title: The title to be displayed as a context menu item and in the
    title of the guidance information dialog. 
    The max length of title is 30 characters.
Details: Details of the guidance to be displayed in the guidance
    information dialog. May span multiple lines.


Related Displays

A list of related displays. Supported formats:

Operator Interface Display Files
    If your CSS setup contains support for an operator interface panel tool,
    its screens can be opened by simply providing the screen file name within the workspace.
    /CSS/Share/DisplayFiles/Section/TheFile.opi

    If the path name contains spaces, it has to be enclosed in quotes:
   "/CSS/Share/My Display Files/TheFile.opi"
   
 Additional parameters can be provided after the file name.
    For BOY *.opi screens this is a list of macros and their values,
    separated by comma, enclosed in quotes:
    /CSS/Share/DisplayFiles/Section/TheFile.opi  "macro1=Value 1, macro2=Another Value"

    To use a web link as the display file name, it has to be prefixed by "opi:"
    to prevent it from being opened in a web browser:
    opi:http://my_display_file_server/get_display.cgi?name=TheFile.opi
Web Pages
    Related displays starting in "http:" or "https:"
    are recognized as web page links. A web browser will be
    launched when the user selects this related display:
    http://some.web.server/page/foo.html
Workspace Files
    Arbitrary workspace files, for example a Data Browser configuration file,
    can be opened via a URL starting in "file:":
   file:/Path/to/the_file.extension
External Programs
    To start external display tools like EDM or MEDM, enter a command-line like
    startedm -m macro=value some_screen
    Related displays are executed as described under "Commands",
    see below, so this requires a script like "startedm" to be available
    on your computer that can launch EDM with the appropriate settings.
    Note that the command to be executed must be on the path
    or in the "Command Directory". It is not possible to provide
    a full path to the external display command because a path starting with "/"
    would be treated as a display file name, not an external command.
   
    The main reason for listing EDM etc. as related displays and
    not commands is the different way they appear to the end user.

As with guidance, each display item is separated into "Title"
and the "Command" which in this case is the actual related display link.




Commands

A list of commands that the user might want to invoke.
Enter a suitable command-line for executing the command,
for example

/usr/local/bin/do_something MyPVName "another parameter"


… I'll stop copying the online help at this point.
---------


> How does automated_action work?

See "<h3>Automated Notifications</h3>" in the manual.

When you run an AlarmNotifier in addition to an AlarmServer, it will perform the automated actions.

> How does automated_action work? I always get an error "Unrecognized command pattern" if I try to write something in the

>From the manual:

-----
mailto:user@my.org
log:Cryo, Maintenance&level=Problem&tags=session_leader
cmd:caput SomePV 1
-----

Example entries would be 


<automated_action>
 <title>Send Email</title>
 <details>mailto:user@my.org</details>
 <delay>900</delay>
</automated_action>

==>  If an alarm is not acknowledged within 900 seconds, the action is performed, i.e. email is sent.

Note that the automated_action is NOT meant to implement interlocks, like pressure rises -> alarm -> open relieve valve.
The cmd:caput SomePV 1 may be a bad example.
Doesn't mean you use the notifier to automate essential actions.
That caput should not open/close a valve. That should be done directly on IOCs without going through the alarm system.
Such a caput from an <automated_action> may enable/disable some horn, something that's part of an alarm/warning system.

The Automated Notifications are meant to augment the alarm system:
An alarm happens, and operator action is required to handle it, because it's not possible to automate this on an IOC.
So operators acknowledge the alarm, try to fix it, and eventually all's fine again.
But if there's nobody available to even acknowledge the alarm within say 15 minutes, that could trigger an email via these Automated Notifications.

Thanks,
Kay




On Sep 5, 2014, at 2:48 AM, Florian Feldbauer <florian@ep1.ruhr-uni-bochum.de>
 wrote:

> Hey all,
> 
> I'm currently trying to configure BEAST (The Alarm Server from CSS)...
> Using the alarm-gui I found the following configuration options:
> 
> <delay>...</delay>
> <count>...</count>
> <filter>...</filter>
> <guidance>
>  <title>...</title>
>  <details>...</details>
> </guidance>
> <display>
>  <title>...</title>
>  <details>...</details>
> </display>
> <command>
>  <title>...</title>
>  <details>...</details>
> </command>
> <automated_action>
>  <title>...</title>
>  <details>...</details>
>  <delay>...</delay>
> </automated_action>
> 
> I could not find these things in the Documentation.
> What do these fields stand for?
> I have an idea what "guidance" is, but what is the difference between "display" and "command"? They both need a
> command as "detail"
> How does automated_action work? I always get an error "Unrecognized command pattern" if I try to write something in the
> details field...
> 
> I'm still using CSS version 3.1.1
> 
> Best regards,
> Florian