Example of adding a custom use case

This topic describes the end-to-end process for adding a new use case by using the Event Orchestration runbook framework with an example of an alarm type of an event. 

Use case – Overview

A TrueSight Operations Management operator receives a critical severity alarm for a UNIX device where the total memory utilization has reached 75% of the threshold for continuous five minutes. From the TrueSight Presentation Server, an operator goes to the Monitoring > Events page, and from the alarm selects the Launch Orchestration Action > Show Top 10 Memory Processes action. TrueSight Orchestration performs the triage action and displays the list of top 10 processes that are consuming the maximum memory on the target UNIX device. 

When an IT operator launches the Orchestration action, remote actions in the form of related events for the alarm that provide a real-time status of the entire process appear in the TrueSight Console. No remediation action is required for this use case. 

To view the Show Top 10 Memory Processes Orchestration action in the TrueSight Console for the relevant alarm, you must perform the steps described in this section. 

Assumptions

For this example use case, it is assumed that all tasks required for generating an alarm for crossing 75% of the memory threshold. These tasks may include (not restricted to) the following: 

• PATROL Agent (version 11.3.02 or later) is running on the target device. 
• Policies for monitoring the total memory utilization of the UNIX device are configured and applied. 
• Each time the threshold is breached on the device (crosses 75% for five minutes), an ALARM event is generated with severity set to critical. 

Step 1. Preparing to add a new custom use case

Before you begin adding a new use case, you must ensure that the following prerequisite tasks are complete: 

• Add TrueSight Orchestration as a component in TrueSight Presentation Server. 
• Install and configure the Event Orchestration runbook version 20.19.01. 

• Import the Even Orchestration framework modules in the TrueSight Orchestration Development Studio. 

   Click here to expand...

  AMP-AD-BMC-Remedy-ARS
  AutoPilot-AD-Utilities
  AutoPilot-OA-Errors
  AutoPilot-OA-Common_Utilities
  AutoPilot-OA-Credentials_Store
  AutoPilot-OA-BAOGridManagement
  AutoPilot-OA-Event_Orchestration
  AutoPilot-OA-ITSM_Automation
  AutoPilot-OA-Network_Utilities
  BMC-SA-Event_Orchestration
  BMC-SA-Event_Orchestration_Configuration

Step 2. Creating a new Memory Utilization module 

To add a new use case, you must first create a new module with a use-case specific name. Commands required for an individual use case are stored in the module configuration part of this module. Workflows required for the use case are also created in this module. 

To create a new module

1. On the TrueSight Orchestration Development Studio Launch Pad, click Designer.
2. In the Project Navigator tree, right-click the name of the grid and select Create New Module.
3. In the New Module dialog box, select Projects from the Module Type list.

4. In the Name field, specify BMC-SA-Event_Orchestration_Memory_Utilization and click OK.

To update BMC-SA-Event_Orchestration_Memory_Utilization module configuration

1. Go to BMC-SA-Event_Orchestration_Memory_Utilization module > configuration and create a new configuration group  called MemoryUtilizationCommands.

2. In the MemoryUtilizationCommands group, create a new configuration item, enter a name, and select the type as XML and provide the following details in the XML.

   <commands>
     <command component-type="unix" invocation-mechanism="ssh">COLUMNS=200 top -cb -o +%MEM | head -n \[N\]</command>
   </commands>

   Element	Description
   <commands>	Contains the command and other attributes for finding the top 10 memory consuming processes on a remote device.
   <command>	Specifies the command for identifying the top 10 memory consuming processes on a UNIX device. Valid value: COLUMNS=200 top -cb -o +%MEM | head -n \[N\] Here, \[N\] specifies the number of processes that you want to retrieve. For this use case, the exact command should be – COLUMNS=200 top -cb -o +%MEM | head -n 10
   <component-type>	Specifies the component type (Windows/UNIX) of the remote device. Valid value: unix
   <invocation-mechanism>	Specifies the adapter invocation mechanism used to run the command. Valid value: ssh

3. Save changes. 

To develop the Perform Triage workflow

For the memory utilization use case, you only need to create a triage workflow. 

1. On the TrueSight Orchestration Development Studio Launch Pad, click Designer.
2. In the Project Navigator tree, right-click the module name and select New Process.

3. In the Create New Process dialog, type Perform Triage in the Process Name field and click OK.

   Important

   Workflow name must be Perform Triage. Do not provide any other workflow name. BMC recommends that you provide meaningful values in the Category, Process Version, Supported Systems, Keywords, and Description fields. Enable Record Metrics to help monitor value realization by implementing the automation.

4. For the Perform Triage workflow, create the following input parameters in the Start activity.

   Input element	Description
   event data	Accept event data in common event model format passed from TrueSight Operations Management.
   target connection data	Accept connection details for target host extracted from the credentials store configuration

5. For the Perform Triage workflow, create the following output parameters in the End activity.

   Output element

   Description

   triage output

   Contains output of the triage process and associated status information, in an XML format. It will also include any error message, in case of errors. Triage process is used to prove and validate that the event is valid. So, set triage status to success, if the event exists. For example, if a service is down, triage status is set to 'success' if the service is really down. Otherwise, set the status to 'failure'. <triage-output> <status /> <command /> <command-output /> <remediation-required /> <start-time /> <end-time /> </triage-output> Output contains the following elements: <status>: Contains the status of the workflow (success or failure) <command>: Contains the command run as part of the workflow. <command-output>: Contains the output of the command <remediation-required>: Specifies whether remediation action is required. Specify false, as remediation is not required. <start-time>: Time (in an epoch format) when the Perform Triage workflow starts. <end-time>: Time (in an epoch format) when the Perform Triage workflow ends.

6. On the workflow design canvas, develop the Perform Triage workflow with the activities that match your requirements. 
   The following figure shows the workflow created for identifying the top 10 memory consuming processes. 
   

   Note

   Ensure that you add the start time and end time utilities. These utilities provide the workflow start time and end time in the output, which is required when related events are sent to the TrueSight Presentation Server.

   While designing the workflow, copy the Convert Target Connection Data to Connection Details utility workflow from the BMC-SA-Event_Orchestration_Host_Down module and add it to a Utilities folder. This workflow is used to convert an incoming target connection data into connection details used by existing AutoPilot-OA-Common_Utilties:Invoke Command workflow.

7. Save changes.

Step 3: Updating module configurations

After creating a new module with the workflows required for the use case, you must now update the configuration for the following modules:

• BMC-SA-Event_Orchestration_Configuration
• AutoPilot-OA-Credentials_Store

Add new event type in the BMC-SA-Event_Orchestration_Configuration module

1. In the TrueSight Orchestration Development Studio Launch Pad, click Designer.
2. In the Project Navigator tree, go to the BMC-SA-Event_Orchestration_Configuration module and open the module configuration. 
3. In the Module Configuration area, go to Specifics > BMC_TrueSight > EventTypes and click to add a new module configuration group for the custom use case. 
4. In the Group Name area, provide these details: 

   1. In the Name field, add Memory Utilization. 
      Do not use special characters or spaces while specifying the use case name. 

   2. Save changes. 
5. Under the newly created use case configuration group, add the following configuration items: 

   1. Add a new XML configuration item with the name Configurations using the following format.

      <configurations>
        <configuration>
          <id>1</id>
          <action-name>Show Top 10 Memory Processes</action-name>
          <incident-enabled>true</incident-enabled>
          <change-enabled>false</change-enabled>
          <change-template-name />
          <remediation-enabled>false</remediation-enabled>
          <change-type></change-type>
        </configuration>
      </configurations>

      Element	Description	Required
      <id>	Specifies the value is used to form action_id.Must be unique for each event type.	Yes
      <action-name>	Specifies the name of the action that will appear on the TrueSight Presentation Server via the Launch Orchestration Actions menu. Specify Show Top 10 Memory Processes.	Yes
      <incident-enabled>	Specify true if you want to create or update incidents for the use case from TrueSight Integration after the triage is successful.	No
      <change-enabled>	Specifies whether to create a change request. Not applicable for this use case as no remediation action is to be performed.	No
      <remediation-enabled>	Specifies whether to execute a remediation action. Not applicable for this use case.	No

   2. Add a new configuration item with the name ModuleName and provide the name of the module that you created in Step 2 with a ":" – :BMC-SA-Event_Orchestration_Memory_Utilization.
   3. Save changes.

Update the AutoPilot OA Credentials Store module

Credentials store module stores passwords used to connect to target servers to perform triage and remediation actions. 

1. In the Project Navigator tree, go to the AutoPilot-OA-Credentials_Store module and open the module configuration. 

2. In the ComponentTypeToOSMappings configuration item, specify the use case mappings. 
   

   <mappings>
     <!-- Related to Service Down Use Case -->
     <component-type name="NT_SERVICES">windows</component-type>
     <component-type name="NUK_Process">unix</component-type>
    
     <!-- Related to Host Down Use Case -->
     <component-type name="NT_REMOTE_HOST">windows</component-type>
     <component-type name="NUK_LINUX_REMOTE_HOSTS">unix</component-type>
    
     <!-- Related to (NEW) Memory Utilization Use Case -->
     <component-type name="NUK_Memory">unix</component-type>
   </mappings>

   Important

   Ensure that you specify the <component-type name> as the value specified for the event object class used in the event.

Step 4: Activating modules

1. On the TrueSight Orchestration Development Studio Launch Pad, click the Library Manager button.

2. In Library Manager, click the Export Modules tab.

3. In the Export Modules table select the modules to export by clicking in the Export check box next to the following modules:

   • AutoPilot-OA-Credentials_Store 
   • BMC-SA-Event_Orchestration_Configuration
   • BMC-SA-Event_Orchestration_Memory_Utilization
4. Click the Export to Repository button and on the Export Confirmation window, verify the information and click Proceed.
   When the export workflow is finished, the Export Confirmation window disappears, and TrueSight Orchestration Development Studio displays the message Export Successful in the bottom left corner of the window. You can now see the modules on the Grid Manager. 
5. To activate modules in the the Grid Manager application, do these steps: 
   1. In the Grid Manager application, select the Manage tab, and then select the Modules tab. 
      The table on the left of the page displays all the modules in the repository.
   2. From the list of modules, activate the following modules on the grid:
      • AutoPilot-OA-Credentials_Store 
      • BMC-SA-Event_Orchestration_Configuration
      • BMC-SA-Event_Orchestration_Memory_Utilization
   3. Click Activate.
      The modules that you selected are activated on the grid.

After successfully adding a new use case, verify whether the Show Top 10 memory Processes Orchestration action is displayed on the TrueSight Console for events. 

Now, you can choose to configure event selection to display the Orchestration action on relevant events only or you can directly initiate the Show Top 10 memory Processes Orchestration action from a relevant event.

Step 5: (Optional) Configure event selection

Now that you have performed the steps required to add a custom use case in TrueSight Orchestration, you can configure context-based event selection so that Orchestration actions are displayed on relevant events only. This is an optional step, if you do not perform this configuration, custom actions are displayed on all events irrespective of the context. 

To understand how to configure context-based event selection and the end-to-end process involved for this example, see  Example of configurations required for a custom use case

While configuring context-based event selection you need to provide the <action-id> for the custom use case. You can obtain this ID by running the Get Supported Actions workflow in TrueSight Orchestration Development Studio.