Configuring event selection for running custom Orchestration actions

When you create a custom use case (on TrueSight Orchestration), the custom Orchestration actions are enabled on all the events (irrespective of context) on the TrueSight console. If you run such an Orchestration action from a relevant event, it works as needed. However, you need to be careful about running custom Orchestration actions from relevant events only.

For example, you cannot run a custom Orchestration action for upgrading the RAM of a server from a critical event indicating insufficient disk space. 

You can avoid analyzing events to run custom Orchestration actions by configuring context-based event selection. This means you can configure the events on which particular Orchestration actions must be enabled.

Before you begin

Ensure that you have already added the custom use case for the custom Orchestration action. Also, note the Orchestration ID of the custom use case created.

For more information about creating the custom use case and obtaining the Orchestration ID, see  Adding a custom use case to enable Orchestration actions.

Configuring context-based event selection 

Use the following steps to perform basic as well as advanced configurations.

Step A: (Basic) Learn how to restrict the Orchestration action to an event class

The following steps help you perform basic configuration steps for restricting the Orchestration actions to display on a particular event class.

  1. Identify the events on which you want to enable the custom Orchestration action. Also, get details of the events by exporting the BAROC file for those events. For more information, see  Exporting events from the TrueSight console.
  2. Navigate to the %TRUESIGHTPSERVER_HOME%\truesightpserver\conf\ directory and open the aoActionsContextConditions.json file.

    Tip

    Ensure that word wrap is turned on while viewing the aoActionsContextConditions.json file for a better viewing experience.

    Best practice

    Before you make any changes in the aoActionsContextConditions.json file, ensure that you back it up.

  3. Copy all the contents of aoActionsContextConditions.json file in a JSON viewer.

  4. Copy the following lines in a separate text file and replace the variables with appropriate values. These lines are the base for defining a new Orchestration action.

    Custom Orchestration action definition
    {"aoaction_id":"<NewOrchestrationID>",  "advanceFilter":{"name":"","eventClass":"<EventClass>","status":"","severity":"","application":"","service":"","groups":"","devices":"","monitors":"","global_filter":0,"filter_type":1,"filterConditions":[{"condition_order":0,"slot_name":"mc_ueid","condition_bracket":"","condition_operator":"AND","slot_operator":"equals","slot_value":"DUMMY","end_bracket":""},{"condition_order":1,"slot_name":"status","condition_bracket":"","condition_operator":"AND","slot_operator":"not_equals","slot_value":"CLOSED","end_bracket":""}]}}


    The following variables need to be replaced with appropriate values:

    • <NewOrchestrationID> refers to the Orchestration ID of the new custom use case created earlier.

    • <EventClass> refers to the event class name for which you want to enable the Orchestration action: The value can be one of the following:

      • If you want to restrict the Orchestration action to a single event class: Specify the name of the event class as given in the event's BAROC file (the first line in the file). 

      • If you want to restrict the Orchestration action to multiple event classes: Refer to the following table.

        To include...Do this...
        To include all the sub-classes of the EVENT classSpecify the value, EVENT
        To include particular event classes (more than one)Specify the value, EVENT. Additionally, in the subsequent step, add appropriate filter conditions to restrict the Orchestration action to the desired event classes.

  5. Copy the lines from the text file (given in the previous step) into the JSON viewer. Add the lines at the end of the contents in the following way:

    • Add the copied lines on a new line after the line for "condition_order":18 and before the last two paranthesis.

    • Before the copied lines, ensure that you add a comma separator as shown in the following example.

    In the following example, notice the aoaction_id parameter (in other words, the Orchestration ID) is set to "BMC_TrueSight-MemoryFull-1" and the eventClass parameter is set to "EVENT"

    The Orchestration ID indicates the custom use case association and the event class indicates the events on which the Orchestration action must be enabled; in this case it will be enabled on PATROL events only.

    Example of a custom Orchestration action definition added
    {"condition_order":18,"slot_name":"mc_parameter_value","condition_bracket":"","condition_operator":"AND","slot_operator":"greater_than","slot_value":"1.0","end_bracket":"))"}]}},
    {"aoaction_id":"BMC_TrueSight-MemoryFull-1", "advanceFilter":{"name":"","eventClass":"EVENT","status":"","severity":"","application":"","service":"","groups":"","devices":"","monitors":"","global_filter":0,"filter_type":1,"filterConditions":[{"condition_order":0,"slot_name":"mc_ueid","condition_bracket":"","condition_operator":"AND","slot_operator":"equals","slot_value":"DUMMY","end_bracket":""},{"condition_order":1,"slot_name":"status","condition_bracket":"","condition_operator":"AND","slot_operator":"not_equals","slot_value":"CLOSED","end_bracket":""}]}}]}
  6. On the JSON viewer, verify if the new Orchestration action is displayed correctly after the first two out-of-the-box Orchestration actions. 0 and 1 indicate the out-of-the-box Orchestration actions. 

  7. The following image is an example of how the new Orchestration action might look on the JSON viewer.

    In the preceding image, the following definitions apply:
    1. Indicates the Out-of-the-box Orchestration actions.
    2. Indicates the custom Orchestration action added.
    3. Displays the custom use case action ID used for creating the Orchestration action.
    4. Displays the event class used for creating the Orchestration action.
    5. Indicates the mandatory filter conditions used for identifying the event. The parameters in this filter condition must not be modified.
    6. Indicates the events that are not closed (in other words, open events). This is a basic filter condition which must be included for a custom Orchestration action. 
  8. After verifying the new Orchestration action on the JSON viewer, copy all the text from the JSON viewer into the aoActionsContextConditions.json file and save the file. 
  9. On the TrueSight console, verify if the custom Orchestration action is correctly displayed as per the event class specified.

Step B: (Advanced) Learn how to restrict Orchestration actions with other conditions

The following steps help you restrict Orchestration actions to display on events with a particular object class only. Similarly, other conditions can be defined.

  1. Navigate to the %TRUESIGHTPSERVER_HOME%\truesightpserver\conf\ directory and open the aoActionsContextConditions.json file.

    Tip

    Ensure that word wrap is turned on while viewing the aoActionsContextConditions.json file for a better viewing experience.

    Best practice

    Before you make any changes in the aoActionsContextConditions.json file, ensure that you back it up.

  2. Copy all the contents of aoActionsContextConditions.json file in a JSON viewer.

  3. Copy the following lines in a separate text file and replace the variables with appropriate values. These lines define the conditions for context-based event selection.

    Condition line
    {"condition_order":<Number>,"slot_name":"<SlotName>","condition_bracket":"","condition_operator":"<LogicalOperator>","slot_operator":"<SlotOperator>","slot_value":"<SlotValue>","end_bracket":""}


    The following variables need to be replaced with appropriate values:

    • <Number> refers to the numerical sequence of the condition that you are adding. The first two conditions (0 and 1) are mandatory conditions that must not be changed. The new condition will get the condition order number 2 and will increase incrementally as you keep adding new conditions.

    • <SlotName> refers to the name of the slot based on which the condition must filter events. The slot name should be the same as it appears in the BAROC file.

    • <LogicalOperator> can be AND or OR.
    • <SlotOperator> defines the operator based on which slot values are matched.

       View the slot operators


      Operator

      Description

      Slot types

      equalsEvents are listed only if the slot value matches the comparison value.

      Enum, String, Number, List of String

      not_equalsEvents are listed only if the slot value does not match the comparison value.Enum, String, Number, List of String
      greater_thanEvents are listed only if the slot value is greater than the comparison value.Enum, String, Number
      less_thanEvents are listed only if the slot value is less than the comparison value.Enum, String, Number
      greater_or_equalsEvents are listed only if the slot value is greater than or equal to the comparison value.Enum, String, Number
      less_or_equalsEvents are listed only if the slot value is less than or equal to the comparison value.Enum, String, Number
      has_prefixEvents are listed only if the slot value starts with the comparison value.String, Number
      has_suffixEvents are listed only if the slot value ends with the comparison value.String, Number
      containsEvents are listed only if the slot value contains the comparison value.String, Number, List of String
      withinEvents are listed only if the slot value is an exact match with one of the comma-separated list of comparison values.String, Number
      contains_one_ofEvents are listed only if the slot value is an exact match with one of the comma-separated list of comparison values.String, Number
      outsideEvents are listed only if the slot value does not match with any of the comma-separated list of comparison values.String, Number
      matches

      Events are listed only if the slot value contains the comparison value.

      You can provide the following parameters in addition to the comparison value:
      %d - decimal integer number
      %f - floating point real number
      %c - single character
      %s - string value

      Consider the following example values in the message slot of eight events:

      Event 1Memory Consumption - 10 MB – on machine clm-dev-008700
      Event 2CPU utilization 85.35% – on machine clm-dev-007890
      Event 3Memory Consumption - 5 MB – on machine clm-dev-108781
      Event 4CPU utilization 75.95% – on machine clm-dev-087654
      Event 5Memory Consumption – 894  MB – on machine clm-dev-54657
      Event 6CPU utilization 68.45% – on machine clm-dev-37878
      Event 7Consumption of storage space is high on vm-dev-45 machine
      Event 8Utilization taking higher trend

      When you use the matches operator for the message slot:

      • Message matchesConsumption – %d
        Events 1, 3, and 5 are displayed, as the following criteria matches:
        Consumption as a constant and an integer variable listed after Consumption.
      • Message matchesmachine %s
        Events 1, 2, 3, 4, 5, and 6 are displayed as the following criteria matches:
        machine as a constant and a string variable listed after machine.
      String, List of String

      subclass_of

      Events are listed only if they are a subclass or child class of the provided class.Class
      superclass_ofEvents are listed only if they are a super-class or parent class of the provided class.Class

    • <SlotValue> refers to the corresponding slot value for adding the condition.

    Example: Suppose you want to restrict the Orchestration action to events related to the Windows platform. Based on the BAROC file for such an event, you need to add the condition after replacing the slot name and value variables. In the following example, notice the slot_name parameter is set to "mc_object_class", the slot_operator set to "equals" and the slot_value parameter is set to "NT_REMOTE_HOST".

    About condition order

    Each time you add a new condition, the condition order value needs to be defined incrementally.

    In the following example, condition order with the value 2 is the new condition added. Similarly, you can add additional conditions as per your needs.

    Condition line example
    {"condition_order":2,"slot_name":"mc_object_class","condition_bracket":"","condition_operator":"AND","slot_operator":"equals","slot_value":"NT_REMOTE_HOST","end_bracket":""}

    The following table can help you visualize and understand the condition in a better way. This table is only meant to help you understand how the conditions are constructed in the JSON format. 

    Condition orderCondition bracketSlot nameSlot operatorSlot valueEnd bracketCondition operator
    2(mc_object_classequalsNT_REMOTE_HOST)AND (plus)

  4. Copy the lines from the text file (given in the previous step) into the JSON viewer. Add the lines at the end of the contents in the following way:

    • Add the copied lines on a new line after the line for "condition_order":1 that was added in the previous procedure (in Step A 5).

    • Before the copied lines, ensure that you add a comma separator as shown in the following example.

    Example of a new condition line added
    {"condition_order":18,"slot_name":"mc_parameter_value","condition_bracket":"","condition_operator":"AND","slot_operator":"greater_than","slot_value":"1.0","end_bracket":"))"}]}},
    {"aoaction_id":"BMC_TrueSight-MemoryFull-1", "advanceFilter":{"name":"","eventClass":"EVENT","status":"","severity":"","application":"","service":"","groups":"","devices":"","monitors":"","global_filter":0,"filter_type":1,"filterConditions":
    [{"condition_order":0,"slot_name":"mc_ueid","condition_bracket":"","condition_operator":"AND","slot_operator":"equals","slot_value":"DUMMY","end_bracket":""},{"condition_order":1,"slot_name":"status","condition_bracket":"","condition_operator":"AND","slot_operator":"not_equals","slot_value":"CLOSED","end_bracket":""},{"condition_order":2,"slot_name":"mc_object_class","condition_bracket":"","condition_operator":"AND","slot_operator":"equals","slot_value":"NT_REMOTE_HOST","end_bracket":""}]}}]}
  5. On the JSON viewer, verify if the new condition line is displayed correctly after the first two filter conditions: 0 and 1. 
    The following image is an example of how the new condition line might look on the JSON viewer.
  6. After verifying the new condition line on the JSON viewer, copy all the text from the JSON viewer into the aoActionsContextConditions.json file and save the file. 
  7. On the TrueSight console, verify if the custom Orchestration action is correctly displayed as per the conditions specified.

Example of event selection configuration

Scenario: Suppose you see an event on the TrueSight console indicating that more than 75% memory is getting utilized on a particular computer. 

Assumption: You have already created a custom use case to understand the top 10 processes that are consuming the maximum memory on the affected computer. For more information, see the steps listed at  Adding a custom use case to capture processes consuming the maximum memory.

Context for configuring event selection: You want to enable the custom Orchestration action on Linux events with the memory parameter value greater than 75%.

Configuration steps:

  1. Navigate to the %TRUESIGHTPSERVER_HOME%\truesightpserver\conf\ directory and open the aoActionsContextConditions.json file.

    Tip

    Ensure that word wrap is turned on while viewing the aoActionsContextConditions.json file for a better viewing experience.

    Best practice

    Before you make any changes in the aoActionsContextConditions.json file, ensure that you back it up.

  2. Copy all the contents of aoActionsContextConditions.json file in a JSON viewer.

  3. Copy the following lines:

    Example of the new condition lines added for selecting memory events on Linux
    {"condition_order":18,"slot_name":"mc_parameter_value","condition_bracket":"","condition_operator":"AND","slot_operator":"greater_than","slot_value":"1.0","end_bracket":"))"}]}},
    {"aoaction_id":"BMC_TrueSight-MemoryUtilization-1",  "advanceFilter":{"name":"","eventClass":"ALARM","status":"","severity":"","application":"","service":"","groups":"","devices":"","monitors":"","global_filter":0,"filter_type":1,"filterConditions":[{"condition_order":0,"slot_name":"mc_ueid","condition_bracket":"","condition_operator":"AND","slot_operator":"equals","slot_value":"DUMMY","end_bracket":""},{"condition_order":1,"slot_name":"status","condition_bracket":"","condition_operator":"AND","slot_operator":"not_equals","slot_value":"CLOSED","end_bracket":""},{"condition_order":2,"slot_name":"mc_object_class","condition_bracket":"","condition_operator":"AND","slot_operator":"equals","slot_value":"NUK_Memory","end_bracket":""},{"condition_order":3,"slot_name":"mc_parameter_value","condition_bracket":"","condition_operator":"AND","slot_operator":"greater_than","slot_value":"75","end_bracket":""}]}}
  4. In the JSON viewer, add the copied lines at the end of the contents in the following way:

    • Add the copied lines on a new line after the line for "condition_order":18 and before the last two paranthesis.

    • Before the copied lines, ensure that you add a comma separator as shown in the following example.

    Example of the new condition lines added for selecting memory events on Linux
    {"condition_order":18,"slot_name":"mc_parameter_value","condition_bracket":"","condition_operator":"AND","slot_operator":"greater_than","slot_value":"1.0","end_bracket":"))"}]}},
    {"aoaction_id":"BMC_TrueSight-MemoryUtilization-1",  "advanceFilter":{"name":"","eventClass":"ALARM","status":"","severity":"","application":"","service":"","groups":"","devices":"","monitors":"","global_filter":0,"filter_type":1,"filterConditions":[{"condition_order":0,"slot_name":"mc_ueid","condition_bracket":"","condition_operator":"AND","slot_operator":"equals","slot_value":"DUMMY","end_bracket":""},{"condition_order":1,"slot_name":"status","condition_bracket":"","condition_operator":"AND","slot_operator":"not_equals","slot_value":"CLOSED","end_bracket":""},{"condition_order":2,"slot_name":"mc_object_class","condition_bracket":"","condition_operator":"AND","slot_operator":"equals","slot_value":"NUK_Memory","end_bracket":""},{"condition_order":3,"slot_name":"mc_parameter_value","condition_bracket":"","condition_operator":"AND","slot_operator":"greater_than","slot_value":"75","end_bracket":""}]}}

    Notice the AO action ID is set to BMC_TrueSight-MemoryUtilization-1 and the event class is set to ALARM

    The following table represents the condition lines added in the JSON viewer in a tabular way. The More Information column describes the conditions added. This table is only meant to help you understand and visualize the JSON conditions in a better way.

    Condition orderCondition bracketSlot nameSlot operatorSlot valueEnd bracketCondition operatorMore information
    0(

    mc_ueid

    equalsDUMMY)AND (plus)Mandatory condition required to identify events; must not be changed.
    1(statusnot_equalsCLOSED)AND (plus)Condition required to enable Orchestration actions on events with the status not equal to Closed; in other words open events.
    2(mc_object_classequalsNUK_Memory)AND (plus)Represents a new condition line. Indicates that the Orchestration action will be restricted to events with the mc_object_class slot value equals NUK_Memory. In other words, the Orchestration action is restricted to memory-related events on the Linux platform.
    3(mc_parameter_valuegreater_than75)AND (plus)Represents a new condition line. Indicates that the Orchestration action is restricted to events with the mc_parameter_value slot value greater than 75. In other words, the Orchestration action will be restricted to events with the memory parameter value greater than 75 (%).
  5. On the JSON viewer, verify if the new condition line is displayed correctly after the first two filter conditions. 
    The following image is an example of how the new condition line might look on the JSON viewer.

    In the preceding image, the following definitions apply:
    1. Displays the custom use case action ID used for creating the Orchestration action.
    2. Displays the event class used for creating the Orchestration action, in this case the value is ALARM.
    3. Indicates the mandatory filter conditions used for identifying the event. The parameters in this filter condition must not be modified.
    4. Indicates the events that are not closed (in other words, open events). This is a basic filter condition which must be included for a custom Orchestration action. 
    5. Indicates that the Orchestration action is restricted to memory-related events on the Linux platform.
    6. Indicates that the Orchestration action is restricted to events with the memory parameter value greater than 75 (%).
  6. After verifying the new conditions on the JSON viewer, copy all the text from the JSON viewer into the aoActionsContextConditions.json file and save the file. 
  7. On the TrueSight console, verify if the custom Orchestration action is correctly displayed as per the conditions specified.

Where to go from here

After verifying that the custom Orchestration action is getting displayed correctly, you can directly initiate the Orchestration action to perform triage or remediation based on your use case. For more information about initiating Orchestration actions, see Using Orchestration actions to enable triage and remediation of events.

Was this page helpful? Yes No Submitting... Thank you

Comments