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.

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.
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.
Copy all the contents of aoActionsContextConditions.json file in a JSON viewer.
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.
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":""}]}}]}
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.
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.
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.
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.

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.
Copy all the contents of aoActionsContextConditions.json file in a JSON viewer.
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
- <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.
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":""}]}}]}
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.
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.
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:

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.
Copy all the contents of aoActionsContextConditions.json file in a JSON viewer.
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":""}]}}
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.
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 (%).
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.
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.