Installing the Event Orchestration runbook

A runbook is a collection of pre-built workflows using a set of adapters and modules that enable you to implement end-to-end use cases. 

When you install the runbook, you can choose to configure adapters and modules required for the out-of-the-box Service Down and Host Down use cases. The runbook is designed to allow addition of new custom use cases in a pluggable manner.

Use these sections to install the runbook.

Preparing to install the runbook

  • Download the TrueSight Orchestration Content installation files.
    See, Downloading-the-installation-files. 

  • Install a compatible version of TrueSight Orchestration Platform. 
    For instructions, see Installing – Classic mode.

  • After installing the CDP, ensure that you provide administrator permissions to the CDP. 

    Do these steps to log on to the CDP as an administrator

    1. On the server where the CDP is installed, run the services.msc command on the command prompt.

    2. From the list of services running, select TrueSight Orchestration Configuration Distribution Peer service, right-click and select Properties.

    3. Click the Logon tab and select This account option.

    4. Click Browse and select the Administrator user account.

    5. Specify the password for the account.

    6. Save and restart the service.

  • Event Orchestration runbook is compatible with the following product versions:

    Product

    Supported version

    TrueSight Presentation Server

    11.3.02

    BMC Remedy AR System

    9.1.03

    TrueSight Orchestration Platform

    8.2.00

Installing the runbook by using the wizard

  1. Navigate to the folder where you have downloaded the installation files and start the installation program.
    • Windows: setup.cmd
    • Linux or Solaris: setup.sh
  2. On the Welcome to TrueSight Orchestration panel, review the information, and on the next page, agree with the License Agreements, and click Next.
  3. On the Directory Selection panel, accept the default location, or click Browse to select a different location. 
  1. On the Repository Communications Settings panel, enter the repository settings:
    • Web Server Protocol: Select https or http 
    • Host Name or IP Address: Enter the fully qualified domain name of the repository server.
    • Web Server Port Number: Enter the port number where the repository is installed. 

    • Repository User: Enter the user name of the account created in Remedy Single Sign-On that you use to log on to the repository.

      Warning

      Ensure that the repository user is not the same as the default Remedy Single Sign-On user.

    • Repository Password: Enter the password that matches the specified user account.
  2. On the Installation Type panel, select BSM Solutions and click Next.
  3. On the Solution feature selection panel, select Event Orchestration and click Next.
  4. On the Adapter feature selection pane, the adapters required for the out-of-the-box use cases are already selected.

  1. (Optional) To configure and enable the adapters on the grid directly from the installer, select the Configure Adapters check box and click Next. 

    Note

    You can choose to not configure content from the installer, however, in that case, you must configure and enable the adapters after the installation is complete. If selected, the Solution Configuration panel is displayed in the installer where you can provide the configuration details.

  2. On the Module feature selection pane, the modules required for the out-of-the-box use cases are already selected. 

  3. (Optional) To activate and configure the modules on the grid directly from the installer, select the Configure Modules check box that ensures that the modules selected here are activated and on your grid and click Next.

    Note

    You can choose to not configure content from the installer, however, in that case, you must configure and enable the adapters after the installation is complete. If selected, the Solution Configuration panel is displayed in the installer where you can provide the configuration details.

  4. On the Solution Configuration panel, provide the configuration details for the Event Orchestration runbook: 

    Note

    The Solution Configuration panel is displayed only if you select the Configure Adapters or Configure Modules check box in the previous panel.

    1. On the ITSM tab, provide the following details:

      Field name

      Description and values

      AR Server host name

      Specify the name or the IP address of the computer running the BMC Remedy AR System server.

      AR Server port

      Select Port mapper or assign a specific port of the computer running the BMC Remedy AR System (if known).

      If the BMC Remedy AR System server is configured to use a port mapper, set the port number to 0.
      If the BMC Remedy AR System server is configured to use a specific port to receive requests, assign that specific port number. 

      User name

      Specify the user required to access the BMC Remedy AR Server

      Password

      Specify the password that matches the specified user name.

    2. Click the CDP tab and provide the following details: 

      Field name

      Description and values

      Web Server Protocol

      Select https

      Host Name or IP Address

      Specify the fully qualified domain name where the CDP is installed.

      Web Server Port Number

      Specify the port number of the CDP.

      Default value: 38080

      CDPUser

      Specify the username required to log on to the grid.

      CDP Password

      Specify the password that matches the specified user name.

    3. Click the Applications tab and provide the following details and click Next: 

      Field name

      Description and values

      Presentation Server URL

      Specify the URL for the TrueSight Presentation Server

      Presentation Server username

      Specify the username required to log on to the TrueSight Presentation Server

      Note

      Use must have super admin privileges

      Mid-tier URL

      Specify the URL required to log on to the BMC Remedy AR System mid-tier server

      Mid-tier user

      Type the user name required to log on to the BMC Remedy AR System mid-tier server

  5. On the Installation preview panel, review the features to be installed, and then click Install.
  6. When the installation finishes, click Done.
    The Event Orchestration run book is installed successfully and you can view the install log at the location displayed on the installer.

Installing the runbook silently

In a silent installation, you run the installation program from a command line. To execute a silent installation, you specify an options file to feed the installation settings to the program. The options file is a text file that defines all the required installation properties.


Click here to expand...

To run the silent installation:

  1. On a computer that has network access to the repository, navigate to the directory that contains the installation program. 

  2. From the command line, execute the command in the following format to install the Event Orchestration runbook.

    <ContentInstallerLocation>\Content\Disk1\setup.cmd -i silent -DOPTIONS_FILE="fullPathToOptionsFile/optionsFile"

    The following figure shows a sample options file for installing and configuring the runbook. Use the sample and replace the variable with values that match your environment.

    -P installLocation=C:\Program Files\BMC Software\AO
    -J AO_INSTALLING_FEATURES=EventOrchestration
    -J AO_REPOSITORY_PROTOCOL=https
    -J AO_REPOSITORY_HOST=<hostname>
    -J AO_REPOSITORY_PORT=28080
    -J AO_REPOSITORY_USER_NAME=aoadmin
    -J AO_REPOSITORY_PASSWORD=admin123
    -J AO_CONTENT_INSTALL_TYPE=INSTALL_TYPE_SOLUTIONS
    -J REMEDY_PORT_NUMBER=0
    -J REMEDY_USER_NAME=Ian
    -J REMEDY_HOSTNAME=<hostname>
    -J REMEDY_PASSWORD=password
    -J ITSM_AUTHORING_COMPANY=
    -J ITSM_AUTHORING_ORGANIZATION=
    -J ITSM_AUTHORING_GROUP=
    ###########################################Event Orchestration properties######################################
    -J CONFIGURE_ADAPTERS=true
    -J CONFIGURE_MODULES=true
    -J AO_CDP_HOST=<hostname>
    -J AO_CDP_PORT=38080
    -J AO_CDP_PROTOCOL=https
    -J AO_CDP_USER_NAME=aoadmin
    -J AO_CDP_PASSWORD=admin123
    -J TSPS_URL=<PROTOCOL://HOST:PORT>/tsws/10.0/api
    -J TSPS_USER_NAME=admin
    -J TSPS_TENANT=*
    -J MIDTIER_URL=<PROTOCOL://HOST:PORT>//arsys/services/ARService?server=<AR_SERVER_HOST>
    -J MIDTIER_USER_NAME=Username

    The following table describes the silent installation properties for the options file.

    Property group

    Property name

    Description

    Required

    Installer location

    -P installLocation

    Specify the directory where the content installer is located.

    Yes

    Repository communication settings

    -J AO_REPOSITORY_PROTOCOL=https
    -J AO_REPOSITORY_HOST=<hostname>
    -J AO_REPOSITORY_PORT=28080
    -J AO_REPOSITORY_USER_NAME=aoadmin
    -J AO_REPOSITORY_PASSWORD=<RepoPassword>

    Specify the communication settings for the repository where you want to install the runbook. Default port is 28080.

    Yes

    Content install type

    -J AO_CONTENT_INSTALL_TYPE=INSTALL_TYPE_SOLUTIONS

    Specify the content installation type. Do not change this value.

    Yes

    Remedy integration settings

    -J REMEDY_PORT_NUMBER=0
    -J REMEDY_USER_NAME=<username>
    -J REMEDY_HOSTNAME=<hostname>
    -J REMEDY_PASSWORD=password
    -J ITSM_AUTHORING_COMPANY=
    -J ITSM_AUTHORING_ORGANIZATION=
    -J ITSM_AUTHORING_GROUP=


    No

    Configure content settings

    -J CONFIGURE_ADAPTERS=true
    -J CONFIGURE_MODULES=true

    Specify true if you want to configure and enable the adapters and modules included in the runbook.

    Conditional; required if you want to configure content from the installer

    BMC Remedy AR Server settings

    #-J REMEDY_PORT_NUMBER=0
    #-J REMEDY_USER_NAME=<RemedyARServerUser>
    #-J REMEDY_HOSTNAME=<RemedyARServerHostname>
    #-J REMEDY_PASSWORD=<password>

    If choosing to integrate with BMC Remedy AR System from the installer, specify the BMC Remedy AR Server values with encrypted password.

    Conditional; required if you want to configure content from the installer

    CDP connection settings

    -J AO_CDP_HOST=<CDPHostname>
    -J AO_CDP_PORT=38080
    -J AO_CDP_PROTOCOL=https
    -J AO_CDP_USER_NAME=aoadmin
    -J AO_CDP_PASSWORD=<password>

    Specify the connection settings for the CDP where the runbook is to be installed. Default port is 38080.

    Yes

    TrueSight Presentation Server settings

    -J TSPS_URL=<PROTOCOL://HOST:PORT>/tsws/10.0/api
    -J TSPS_USER_NAME=admin
    -J TSPS_TENANT=*

    Specify the connection settings to connect with TrueSight Presentation Server.-J TSPS_TENANT can be *

    Conditional; required if you want to configure content from the installer

    BMC Remedy AR System - Mid-tier Host settings

    -J MIDTIER_URL=<PROTOCOL://HOST:PORT>//
    arsys/services/ARService?server=<AR_SERVER_HOST>
    -J MIDTIER_USER_NAME=Username

    Specify the BMC Remedy AR System – mid-tier host connection settings.

    Conditional; required if you want to configure content from the installer

    The Event Orchestration run book is installed successfully and you can view the install log at the location displayed on the installer.

  3. After successfully installing the runbook, you can now verify whether the artifacts are installed and then complete the post-installation tasks.

Content artifacts installed with the runbook

When you install the runbook, the adapters, modules, and workflows that constitute the runbook framework and logic for the out-of-the-box use cases are installed in the repository and available in the Grid Manager. These adapters and modules are configured with basic configuration and enabled on the grid. 

The following table lists the adapters and modules installed with the runbook. 

Content type

Name

Type

Adapter name on the grid

Adapters

BMC Remedy AR System

ro-adapter-remedy-actor

ARSAdapter_EO

Command Line

ro-adapter-command-line

Command Line_EO

SSH

ro-adapter-ssh

SSHAdapter_EO

REST

ro-adapter-rest

RESTAdapter_EO

Web Services

ro-adapter-ws

SOAPAdapter_EO

Windows Command

ro-adapter-windows-command

WindowsCommandAdapter_EO

Modules

  • AMP-AD-BMC-Remedy-ARS
  • AutoPilot-AD-Utilities
  • 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
  • BMC-SA-Event_Orchestration_Host_Down
  • BMC-SA-Event_Orchestration_Service_Dow

NA

NA

Complete the post-installation tasks

Perform these tasks if you have chosen to configure and activate the adapters and modules from the installer. 

Note

If you have just installed the runbook without configuring and enabling content from the installer, you must perform additional configuration steps before you can start using/implementing the solution. For more information, see the Where to go from here section in this topic.

Configure the SSH adapter

SSH adapter is used to run commands on a remote host using the SSH protocol. SSH adapter is enabled on your grid, but you must provide the remote host details in the adapter configuration. 

Click here to expand...
  1. On the Grid Manager, click the Manage tab and then click the Adapters tab.
  2. From the Adapters on Grid list, click the SSHAdapter_EO adapter.

  3. On the Edit an Adapter Configuration page, provide the following details:

    Element

    Description

    Required

    Target

    Specifies the host name or the IP address of the remote host computer

    Yes

    Port

    Specifies the port on which the remote host listens.  Default value: 22

    No

    Username

    Specifies the user name required for remote host authentication

    Yes

    Password

    Specifies the password corresponding to the specified user name 

    The <private-key-file> element is used if you do not provide the <password> element. 

    The <password> element can contain an encryption-type attribute.

    If you provide the <password> and <private-key-file>elements in the grid configuration, the <private-key-file> approach is used and the <password> element is ignored.

    Yes

    Encryption Type

    Indicates whether the password specified is encrypted; is an attribute of the <password> element, not an element itself 

    Valid values: Base64, Plain (default)

    No

  4. Click Save and enable the adapter on the grid.

Update BMC-SA-Event_Orchestration_Configuration module configuration

When you configure content from the installer, modules with connection details for BMC Remedy ITSM and TrueSight Presentation Server are configured and activated on the grid. Installer does not provide the option to specify passwords for the target connections. You must specify the password for connecting to BMC Remedy ITSM and TrueSight Presentation Server environments. 

Click here to expand...
  1. On the Grid Manager, click the Manage tab and then click the Modules tab.
  2. From the Activated On Grid list, click the BMC-SA-Event_Orchestration_Configuration module.
  3. To specify the CDP connection details used for the runbook, on the Edit Module Configuration page, go to Specifics > BAO and provide the TrueSight Orchestration URL, username, and password required to log on to the CDP.
  4. To specify password for the BMC Remedy mid-tier host, on the Edit Module Configuration page, go to Specifics > BMC_AR_System > WebServiceConnectionData and provide the password for the mid-tier host specified in the URL field.
  5. To specify password for the TrueSight Presentation Server host, go to Specifics > BMC_TrueSight > WebServiceConnectionData and provide the password for the host specified in the BASE_URL field.
  6. Save changes.

Update Credentials Store module configuration

The Credentials Store module contains encrypted passwords for all target servers. Credentials for TrueSight Orchestration, TrueSight Presentation Server, and BMC Remedy IT Service Management are stored in the BMC-SA-Event_Orchestration_Configuration module. Assuming that in an organization, each component type (OS type) can have its own set of credentials, definitions for storing UNIX and Windows Credentials are provided in the module out-of-the-box.

Click here to expand...
  1. On the Grid Manager, click Manage > Modules and click the AutoPilot-OA-Credentials_Store module.
  2. Expand the configuration tree until you can navigate to the configuration item that you want to modify.
  3. Click the configuration item that you want to modify, edit the value, and click OK to save changes.
  4. After successfully configuring the module, click the Modules tab and from the Modules in Repository list, select the module and click Activate. Module with the updated changes is successfully activated on the grid. 

Use this section to understand the module configuration items and the configuration items that you must update to use the runbook. 

Configuration item

Description

Update required?

Event Orchestration > Credentials

Stores the credentials for the operating systems.

  • WindowsCredentials: Specify the password for hosts using Windows operating system, in a secure manner.
  • UnixCredentials: Specify the password for hosts using Unix operating system, in a secure manner.


Yes

ComponentType
ToOSMappings

Contains the mappings for target host systems to operating systems for the out-of-box service down and host down use cases in an XML format.

<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>
</mappings>

Conditional; required if adding a custom use case

Event Orchestration > InfrastructureMappings

Contains the mappings between targets and credentials in an XML format. In addition, the mappings contain the settings for adapter invocation mechanism and the options to be passed to the adapter request and the command options.

Click here to view the default Infrastructure Mappings
<mappings>
 <datacenters>
   <datacenter name="default">
     <domains>
       <domain name="*">
         <component type="patrol" name="*">
           <username>patrol</username>
           <password-configuration-name>UnixCredentials</password-configuration-name>
           <invocation-mechanism>ssh</invocation-mechanism>
           <adapter-options />
           <command-options />
         </component>
         <component type="patrol" name="hostname">
           <username>patrol</username>
           <password-configuration-name>WindowsCredentials</password-configuration-name>
           <invocation-mechanism>windows-command</invocation-mechanism>
           <adapter-options />
           <command-options />
         </component>
         <component type="unix" name="*">
           <username>root</username>
           <password-configuration-name>UnixCredentials</password-configuration-name>
           <invocation-mechanism>ssh</invocation-mechanism>
           <ping-mechanism>command-line</ping-mechanism>
           <adapter-options />
           <command-options />
         </component>
         <component type="unix" name="u1">
           <username>root</username>
           <password-configuration-name>UnixCredentials</password-configuration-name>
           <invocation-mechanism>ssh</invocation-mechanism>
           <ping-mechanism>command-line</ping-mechanism>
           <adapter-options />
           <command-options />
         </component>
         <component type="windows" name="*">
           <username>Administrator</username>
           <password-configuration-name>WindowsCredentials</password-configuration-name>
           <invocation-mechanism>windows-command</invocation-mechanism>
           <ping-mechanism>command-line</ping-mechanism>
           <adapter-options />
           <command-options />
         </component>
         <component type="windows" name="hostname">
           <username>Administrator</username>
           <password-configuration-name>WindowsCredentials</password-configuration-name>
           <invocation-mechanism>windows-command</invocation-mechanism>
           <ping-mechanism>command-line</ping-mechanism>
           <adapter-options />
           <command-options />
         </component>
         <component type="unix" name="hostname">
           <username>root</username>
           <password-configuration-name>UnixCredentials</password-configuration-name>
           <invocation-mechanism>ssh</invocation-mechanism>
           <ping-mechanism>command-line</ping-mechanism>
           <adapter-options />
           <command-options />
         </component>
         <component type="unix" name="hostname">
           <username>root</username>
           <password-configuration-name>UnixCredentials</password-configuration-name>
           <invocation-mechanism>ssh</invocation-mechanism>
           <ping-mechanism>command-line</ping-mechanism>
           <adapter-options />
           <command-options />
         </component>
         <component type="database" name="oradb1">
           <url />
           <username>sys</username>
           <password-configuration-name>DatabaseCredentials</password-configuration-name>
           <invocation-mechanism>sql</invocation-mechanism>
         </component>
       </domain>
       <domain name="bmc.com">
         <component type="patrol" name="*">
           <username>patrol</username>
           <password-configuration-name>UnixCredentials</password-configuration-name>
           <invocation-mechanism>ssh</invocation-mechanism>
           <adapter-options />
           <command-options />
         </component>
         <component type="patrol" name="hostname.bmc.com">
           <username>patrol</username>
           <password-configuration-name>WindowsCredentials</password-configuration-name>
           <invocation-mechanism>windows-command</invocation-mechanism>
           <adapter-options />
           <command-options />
         </component>
         <component type="unix" name="*">
           <username>root</username>
           <password-configuration-name>UnixCredentials</password-configuration-name>
           <invocation-mechanism>ssh</invocation-mechanism>
           <ping-mechanism>command-line</ping-mechanism>
           <adapter-options />
           <command-options />
         </component>
         <component type="unix" name="u1.bmc.com">
           <username>root</username>
           <password-configuration-name>UnixCredentials</password-configuration-name>
           <invocation-mechanism>ssh</invocation-mechanism>
           <ping-mechanism>command-line</ping-mechanism>
           <adapter-options />
           <command-options />
         </component>
         <component type="windows" name="*">
           <username>Administrator</username>
           <password-configuration-name>WindowsCredentials</password-configuration-name>
           <invocation-mechanism>windows-command</invocation-mechanism>
           <ping-mechanism>command-line</ping-mechanism>
           <adapter-options />
           <command-options />
         </component>
         <component type="windows" name="hostname.bmc.com">
           <username>Administrator</username>
           <password-configuration-name>WindowsCredentials</password-configuration-name>
           <invocation-mechanism>windows-command</invocation-mechanism>
           <ping-mechanism>command-line</ping-mechanism>
           <adapter-options />
           <command-options />
         </component>
         <component type="unix" name="hostname.bmc.com">
           <username>root</username>
           <password-configuration-name>UnixCredentials</password-configuration-name>
           <invocation-mechanism>ssh</invocation-mechanism>
           <ping-mechanism>command-line</ping-mechanism>
           <adapter-options />
           <command-options />
         </component>
         <component type="unix" name="hostname.bmc.com">
           <username>root</username>
           <password-configuration-name>UnixCredentials</password-configuration-name>
           <invocation-mechanism>ssh</invocation-mechanism>
           <ping-mechanism>command-line</ping-mechanism>
           <adapter-options />
           <command-options />
         </component>
         <component type="database" name="oradb1">
           <url />
           <username>sys</username>
           <password-configuration-name>DatabaseCredentials</password-configuration-name>
           <invocation-mechanism>sql</invocation-mechanism>
         </component>
       </domain>
     </domains>
   </datacenter>
 </datacenters>
</mappings>

You can update the Infrastructure Mappings based on your requirement. Infrastructure Mappings include information for the following elements:

  • <datacenters>: Specifies the root node that contains information about one or more data centers. Includes the <datacenter> element, which contains all the information related to a datacenter. If more than one exists, then, they are distinguished using name attribute.

    <datacenter name="default">
  • <domains>: Contains the <domain> child elements for specifying more than one domain. Out-of-the-box, a "*" domain is specified.
    • <domain name= "*">: Specifies the domain name where the event occurs. If no domain information is available in the event, a default domain named "*" is used.

    • <domain name= "acme.com">: Specifies a placeholder for a domain in your environment.

      Note

      If event data and target host information does not contain information related to a domain, then, an attempt will be made to extract component information from the default "*" domain.

    • <component>: Contains mapping information for a target. Component can have two attributes:
      type: Specifies the component type, whether it is a windows host or a Unix host.
      name: Specifies the name of the host. If host name is not known, specify "*".

      Example: <component type="windows" name="*">

      <component> contains the following child elements:

      • <username>: Specifies the username required to log on to the component.
      • <password>: Specifies the password that matches the username.
      • <invocation-mechanism>: Specifies the ways to invoke workflows. For example, if the component is a Windows computer, you can use windows-command as the invocation mechanism. The Command Line adapter is used. For Unix, the SSH adapter is used to invoke the workflows.
      • <ping-mechanism>: Specifies the mechanism to perform typical ping operations. Typically, a ping command can be performed from the local peer by using a command line adapter. 
      • <adapter-options>: Contains a comma-separated list of options to be passed to the adapter based on the adapter invocation mechanism. For example: use-ssl=true, use-unsigned-certificates=true.
      • <command-options>: Contains a comma-separated list of options to be passed to the command.

Yes

Where to go from here

Choose one of the following options:

  • Orchestration actions – Restart Service and Check Host Connection are now available in TrueSight Presentation Server for the out-of-the box use cases, Service Down and Host Down respectively. For more information about using the Orchestration actions for your remediation solutions, see "Using Orchestration actions to enable triage and remediation of events  
  • If you have installed the runbook without configuring and enabling content from the installer, you must perform additional configuration steps before you can start using/implementing the solution. For instructions, see Configuring-content-in-the-Event-Orchestration-runbook.
  • If you want to start adding new Orchestration actions for custom use cases, see Adding-a-custom-use-case-to-enable-Orchestration-actions. 

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*