Overview

The common mechanism for performing actions or informing operators is the procedure.  Procedures are used to instruct an operator on what to do and in what order during an alarm.  They are also used to perform system roles such as running scripts or sending emails based on schedules which can control any aspect of the Limelight XE infrastructure.

Prerequisites

• Completion of Understanding Alarm Management and Procedures - Part 3.

Introduction

Procedures are used for two major purposes... one is to instruct an operator on how to handle a specific alarm and the other is to automatically perform tasks when alarms or schedule events occur.  Automatic procedures such as those performed when a scheduled event occurs (e.g. start of a work shift) may have comments, but there is no user interaction.  If user interface tasks are added to automatic procedures, then the tasks will run as if the user completed each tasks immediately and all decisions result in default selections.  So it is best to separate them into these two major categories even though they both exist in the manager as procedures.

One simple way to do this is via a naming convention - you could use "Automatic" or "Scheduled" as a prefix for the procedure name and "Alarm" or "UI" for operator procedures.  Also, procedures can be triggered by both schedules and alarm events - so when the procedure is run by the system when a schedule event occurs, there is no user interaction.  When it is triggered by an alarm event, then it operates with the user interface as any normal procedure.  By design, it is best practice to separate these two distinct categories.

Below is the Procedures tab view shown with no entries (e.g. before any procedures have been created).  There are two minor tabs within the manager - the Procedure Editor where procedures are created and tasks added to the procedure, and the Trigger Editor which is used to assign what type of event executes the procedure.  As stated above triggers can include alarm or scheduled events.

Procedure Manager Tab Overview showing the Procedure Editor

Below are the definitions of each control

Procedure Window and Controls (left side)

• Procedure Add (+) - this button is located on the bottom left of this tab adjacent to the delete (-) button.  Click this button to create a new blank procedure.
• Procedure Delete (-) - this button is located on the bottom left of this tab adjacent to the add (+) button.  To remove a procedure, select it in the tree-view window above the button labeled "Procedures" and click this button. A warning dialog will appear indicating that the operation is permanent - Click 'OK' to delete the procedure and all associated tasks. 

• Test - this button is located on the bottom left of this tab to the right of to the right of the Delete (-) button.  While compiling procedures a developer can use this button to test the procedure as if it had been triggered.

Procedure Editor and Controls (right side)

Procedure Details Group

• Name - Edit this field to alter the procedure name.
• Description - Edit this field to alter the procedure's description (e.g. how it is used).
• Enabled (check box) - This control enables or disabled the procedure from running.

Procedure Items / Tasks Group

• Task Add (+) - Click this button to add a new task to the currently selected procedure.
• Task Delete (-) - Click this button to delete a task.
• Move Task Up (up arrow) - Use this control to reorder tasks - this will move the selected task up on position per click.
• Move Task Down (down arrow) - use this control to reorder tasks - this will move the selected task down one position per click.

Procedure Item Settings

• Item Title - The name of the currently selected task. This is displayed in the procedure block of the Alarms tab for operators, so be descriptive (e.g. use "Run Diagnostic Script" instead of "Script Task").
• Item Type - This defines what this task does and how it interoperates with the system and operators.  There are 5 options.
  • Comment - Provided for developers to understand various sections of the procedure - no action is taken.
  • Run Script - Will execute a script (note: it does not wait for an operator unless bracketed by UI based item types).
  • Wait for Operator - Will wait until the operator signals complete by clicking the COMPLETED button in the Alarms tab.
  • Wait for Operator Function - Will wait until the operator selects a predefined option in the Alarms tab controls.  This is set within this task (more on this below).
  • Wait for Acknowledge - Will wait until an operator acknowledges the alarm before proceeding.  This gives procedure developers the ability to execute automatic scripts (e.g. to shut down a process, etc.) prior to the alarm being handled by an operator.
• Time Out - Provides a time-out value in seconds if the operator doesn't complete a task or make a decision in a fixed period of time.  If the value is zero (the default) there is no timeout and will wait indefinitely for user interaction.  Using the optional Auto Escalate function will cause the severity of the alarm to be increased after some period of time if not serviced.
• Script (only applies to Run Script) - Select the script to run when using the Run Script item type.
• Defaults Tab - Select what item is executed next based on the operator's action. A minus one (-1) indicates "Next Item" in the list.
  • Complete Item - When the task item type is set to Wait for Operator and the operator clicks COMPLETED, this item will execute.
  • Fail Item - If there is a problem with a task (e.g. a script fails to run or returns a failure code), this item will execute.
  • Timeout Item - if the operator fails to click COMPLETED or any required function buttons before the timeout, this item will execute.
• Button 1 Tab (only visible when Wait for Operator Function type is selected)
  • This provides an optional "button" for operators to click to perform some action (e.g. run a script).  The caption on the button is programmable and can be tied to any other valid task in this procedure.
  • Enabled - Will enable the button (make it visible) which will appear under the "Current Action / Task" window on the lower right of the Alarms tab view.
• Button 2 Tab (same as above, but for an additional button #2)
• Button 3 Tab (same as above, but for an additional button #3)

Procedure Item Description Editor

• Use the editor controls to write the actual task the operator must accomplish.  This is a Rich Text Format (RTF) field and can use multiple fonts, sizes and colors to communicate.  It has the ability to add bullets and indent.  One powerful feature are tags which provide a mechanism for live data to be inserted into the task operation.  For example, the entire contents of the account that is associated with the alarm can be inserted using the <%AccountFullInfo%>.  These tags can be manually inserted or via the editor.

Lesson 1 - Create a New Procedure with Tasks

1. Log into the Limelight XE server as an administrator using the console and select the Procedures tab.
2. Add a procedure by clicking the "+" button on the lower left (hint will say, "Create a new procedure"). A new procedure named "New Procedure" will appear in the Procedures tree view.
3. Make sure you are in the Procedure Editor tab (not the Trigger Editor tab).
4. Select the new procedure and rename it to "Test Procedure 1" and hit enter (note: enter is equivalent to "save" in this tab)
5. Next, change the description and save your updates.
6. Add the first task by clicking the "+" button under the Procedure Items / Tasks window. This will create a new task called "New Procedure Item".
7. Select the new task (procedure item) and rename it to "Show Account Information". Hit enter to save.
8. Now select the Item Type to be "Wait for Operator", set the timeout to 60, leave Script empty and hit enter to save.
9. Leave all defaults at "(-1) Next Item.
10. Now in the Procedure Item Description Editor main window, type "Account Information" and an enter (note: When editing, the "enter" key is captive to the editor, so it serves to add new lines to the text).
11. Select "Account - Info Full" in the drop down to the right of the yellow tag button (see image)  
12. Next, click the yellow tag button to insert this tag into the task description and click UPDATE to save.
13. Select all the contents of the task description editor (where you inserted the tag) and change the font size to 12 and the color to red or green (this illustrates how it will be displayed to the operator).
14. Save your changes. 
15. To test your procedure, click the TEST button in the lower right and then select the Alarms tab to view the new procedure within a test alarm.

Lesson 2 - Adding Triggers to Procedures

We are going to tie the procedure from the previous lesson to a trigger when a user logs in.  Before we can do this, we need to enable that event code to trigger an alarm (lowest level is Advisory, so we'll use that).

1. If you are not logged in to the Limelight XE server, log back in now with the same credentials used above.
2. On the main menu, click Tools -> Alarm Priorities... the Alarm Priority Manager will appear.
3. Scroll down to code 0x00010750 (67408) - "Security - Login Successful" and select it.
4. Change the Alarm Priority to "Advisory" and update the database by clicking UPDATE. This has enabled this event to cause an alarm of priority "Advisory" - the lowest level alarm.
5. Close the dialog.
6. Return to the Procedures tab and select the "Show Account Information" procedure created in the lesson 1.
7. On the main Procedures tab, select the Trigger Editor tab to select a trigger (or multiple triggers).
8. Click the column labeled Alarm Description to sort the alarm events alphabetically which will make it easier to locate the Security event we just enabled above.
9. Find "Security - Login Success" in the Available Alarms list, select it and click the left arrow (between the Triggers and Available Alarms lists near the top).  This will move the selected alarm event to the triggers list (It saves automatically).
10. The "Security - Login Success" alarm event will disappear from the Available Alarms list and appear in the Triggers (Alarms / Events) list window.  The procedure now has a trigger - when any user logs in successfully, the alarm will appear in the Alarms tab and the above procedure which dumps the user's account information will execute.

Lesson 3 - Testing the Trigger

1. Start a second copy of the Limelight XE console and log in with your credentials.
2. Note that in the first console's Alarms tab a new alarm appears.
3. Select that alarm and note the Current Task / Action window (lower right corner).  Your account information should appear in the window.
4. Press F4 to launch the Procedure Manager window which shows larger areas of the same information.  This is useful on dual monitor systems where the primary console can be displayed on one monitor and the Procedure Manager window on the other for operator clarity.  To hide the Procedure Manager window, simply close it or press F4 again.