Adding a new use case to the Event Orchestration runbook

In this release, the service down use case – Service Down event type, for which triage and remediation is applied, is available out-of-the-box. Use this topic to add new use cases to be supported by the Event Orchestration runbook. 

In this release, TrueSight Infrastructure Management is the event source and BMC Remedy IT Service Management (ITSM) is the ITSM system used for managing the event lifecycle.

• • Before you begin
  • Step 1: Add the event type to the enumeration to the main cell
  • Step 2: Add a rule to enrich the event related to the new event type in the main cell
  • Step 3: Add a new module for the use case
  • Step 4: Update BMC-SA-Event_Orchestration_Configuration module configuration
  • Step 5: Update AutoPilot-OA-Credentials_Store module configuration
  • Step 6: Activate modules on the grid

Before you begin

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

• PATROL Agent is configured to generate new events, which are sent to the TrueSight Infrastructure Management main cell and are visible in the TrueSight Presentation Server. 
• The TrueSight Infrastructure Management main cell is configured to propagate events of a certain event type to the TrueSight Orchestration gateway. 

Step 1: Add the event type to the enumeration to the main cell

1. On the TrueSight Infrastructure Management server, go to the Main_CELL_HOME/kb/classes location. 

2. Open the bii4p.baroc file and for the ENUMERATION EO_EVENT_TYPE attribute, specify the name of the event. 
   For example, 40 SQLServerDown.

   Click here to view the sample file with the enumeration type defined for the SQL server down event

   
   

   #################################################################################
   # File name: bii4p.baroc
   # Version: 11.0.0
   # Copyright 2017-2027 BMC Software, Inc. All Rights Reserved
   #
   # Module        : Event Orchestration
   # Date          : April 19, 2018
   # Author        :
   # Description   : Data classes required to support Event Orchestration
   # Revision      : 11.0.0
   # History       : Initial Creation.
   #################################################################################
   # Event classification to tag a specific event type
    
   ENUMERATION EO_EVENT_TYPE
      0   Unknown
      10 ServiceDown
      20 ServerDown
      30 DiskFull
      40 SQLServerDown
   END
    
   MC_EV_CLASS :
              PATROL_EV ISA EVENT
              DEFINES
               {
                  mc_tool:    default="PATROL Agent";
                  mc_host_address:    dup_detect=yes;
                  mc_origin_key:      dup_detect=yes;
    
                  p_agent:    STRING;
                  p_agent_address:    STRING;
                  p_agent_port:   INTEGER;
                  p_agent_version:    STRING;
                  p_application:  STRING;
                  p_catalog:  STRING;
                  p_class:    STRING;
                  p_diary:    STRING;
                  p_expectancy:   STRING;
                  p_handler:  STRING;
                  p_instance: STRING;
                  p_node:     STRING;
                  p_origin:   STRING, dup_detect=yes;
                  p_owner:    STRING;
                  p_source_id:    STRING;
                  p_status:   STRING;
                  p_type:     STRING;
                  p_args:     LIST_OF STRING;
                  pes:    INTEGER;
                  pes_tcp_port:   INTEGER;
                  pes_udp_port:   INTEGER;
                  pes_icon_name:  STRING;
                  pes_parent_instance:    STRING;
                  pes_param_status:   STRING;
                  pes_alert_date: STRING;
                  pes_alert_time: STRING;
                  pes_tz: STRING;
                  pes_last10: STRING;
                  pes_ave10:  STRING;
                  pes_last10_ts:  STRING;
                  pes_last10_tp:  REAL;
                  pes_user_defined:   STRING;
                  pes_alarm_min:  STRING;
                  pes_alarm_max:  STRING;
                  pes_patrol_home:    STRING;
                  pn_object_id : INTEGER, hidden=no, default = 0;
                  pn_object_class_id : INTEGER, hidden=no, default = 0;
                  eo_event_type  : EO_EVENT_TYPE,   default = Unknown ;
               };
          END
    
   #---------------------------------------------------------------------
   #   End Of file
   #---------------------------------------------------------------------
    

Step 2: Add a rule to enrich the event related to the new event type in the main cell

Event is enriched in the main cell before sent to the TrueSight Orchestration gateway.

The following figure shows a sample rule added for the SQLServerDown use case. In the following example, a new rule is added only for the events generated on a target server, which is on Windows OS.

Step 3: Add a new module for the use case

To add support for a new use case to the runbook, you must add a new module and add processes, related schedules, configurations, and rules for the new use case. You create a new module in TrueSight Orchestration Development Studio, export the module with the changed type to the repository and activate it on a grid for the change to take effect.

1. Open the Development Studio and connect to your grid. 
2. Create a new module with the name of the use case. 
   For example, BMC-SA-Event_Orchestration_SQL_Server_Down. 
   For more information, see Creating modules. 
3. Define module configuration for the use case module.
   For more information, see Configuration items. 
4. Ensure that you add the following workflows to the module:
   
   1. Perform Triage
   2. Perform Remediation (optional; required if you want to remediate the events)
   3. Perform Validation
5. Save changes and then export the module with the changed type to the repository and activate it on a grid for the change to take effect.

For more information, see Developing workflows in TrueSight Orchestration Platform documentation.

Step 4: Update BMC-SA-Event_Orchestration_Configuration module configuration

On the TrueSight Orchestration Grid Manager, update the Event Orchestration Configuration module on the peer where the BMC-SA-Event_Orchestration_Configuration module is installed and running. To add new module configuration items, you cannot change the value type within Grid Manager.

You can change the value type or add new configuration items only in TrueSight Orchestration Development Studio. 

1. Log on to TrueSight Orchestration Development Studio and go to the BMC-SA-Event_Orchestration_Configuration module.

2. To add a new use case, go to configuration > Specifics > BMC_TrueSight > EventTypes and click to add a new module configuration group for the new event. 

   For example, for the SQL Server Down event, add a new group with the name as SQLServerDown.

   Note

   Do not add spaces while specifying the configuration group name.

   

3. Under the newly added configuration group, SQLServerDown, click to add new configuration items and specify the values that match your environment:
   
   1. EventType: Enter the name of the event type. For example, SQLServerDown.
   2. IncidentEnabled: Specify true to create or update an incident for the event.
   3. ChangeEnabled: Specify true to create a change and an associated task for the event.
   4. ChangeTemplateName: Specify the name of the change template to be used to create a change for this event. Change templates are created in your BMC Remedy ITSM environment. 
   5. RemediationEnabled: Specify true if remediation is required for the event. If false, only triage actions are performed for the event and the event orchestration process is complete.
   6. ChangeType: If specified as normal, the change ticket requires manual approval process in BMC Remedy ITSM. The event orchestration processes does not proceed until a change ticket is approved. If specified as auto, in BMC Remedy ITSM, the change is auto-approved and the event orchestration process is continued.
      
      

4. Go to WorkflowDefinitions and expand the configuration group to specify the triage, remediation, and validation workflows for the new use case. 
   The following figure shows the workflow paths for the new use case in the following format: 

   <workflow eventType="<NameOfTheEvent>" action="triage">:BMC-SA-Event_Orchestration_<event_name>:Perform Triage</workflow>

   Example

   <workflow eventType="SQLServerDown" action="triage">:BMC-SA-Event_Orchestration_SQLServer_Down:Perform Triage</workflow>
   <workflow eventType="SQLServerDown" action="remediate">:BMC-SA-Event_Orchestration_SQLServer_Down:Perform Remediation</workflow>
   <workflow eventType="SQLServerDown" action="validation">:BMC-SA-Event_Orchestration_SQLServer_Down:Perform Validation</workflow>
5. Save changes and then export the module with the changed type to the repository and activate it on a grid for the change to take effect.
   For more information, see Editing active modules in TrueSight Orchestration Platform documentation.

Step 5: Update AutoPilot-OA-Credentials_Store module configuration

Credentials store module stores passwords used to connect to target servers to perform triage and remediation actions. In addition it also stores invocation mechanism (whether to use Windows specific adapter, SSH adapter, SQL adapter, and so on). For example, for SQLServerDown use case, specify the following database credentials and invocation mechanism configurations:

1. EventOrchestration > Credentials configuration group, add a credential parameter called SQLServerDBCredentials and specify the secure password.

2. EventOrchestration > InfrastructureMappings, specify the correct datacenter → domain element.
   Add component XML as shown in the following figure:

   <component type="database" name="mssqlserver1">
     <url>jdbc:sqlserver://<sqlserver-host-name>:4340;databaseName=<DBInstanceName></url>
     <username>sys</username>
     <password-configuration-name>SQLServerDBCredentials</password-configuration-name>
     <invocation-mechanism>sql</invocation-mechanism>
   </component>

Step 6: Activate modules on the grid

After configuring the module, activate the modules configured in the earlier steps on the TrueSight Orchestration Grid Manager. You must also activate a new workflow module that contains workflow processes for the new use case. Activating a module deploys it to the grid. Peers begin executing workflows according to the schedules defined in the activated modules. 

1. In the Grid Manager application, select the Manage tab, and then select the Modules tab.
2. Activate the following modules on the grid:
   • BMC-SA-Event_Orchestration_Config
   • AutoPilot-OA-Credentials_Store
   • BMC-SA-Event_Orchestration_<name_of_the_use_case>
3. Click Activate. 
   The modules that you selected are activated on the grid.
   For more information, see Activating modules.