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

Navigate to the folder where you have downloaded the installation files and start the installation program.
- Windows: setup.cmd
- Linux or Solaris: setup.sh
On the Welcome to TrueSight Orchestration panel, review the information, and on the next page, agree with the License Agreements, and click Next.
On the Directory Selection panel, accept the default location, or click Browse to select a different location.
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.
On the Installation Type panel, select BSM Solutions and click Next.
On the Solution feature selection panel, select Event Orchestration and click Next.
On the Adapter feature selection pane, the adapters required for the out-of-the-box use cases are already selected.
(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.
On the Module feature selection pane, the modules required for the out-of-the-box use cases are already selected.
(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.

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.

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.

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.

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

On the Installation preview panel, review the features to be installed, and then click Install.
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:

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

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.

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...

On the Grid Manager, click the Manage tab and then click the Adapters tab.
From the Adapters on Grid list, click the SSHAdapter_EO adapter.

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

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...

On the Grid Manager, click the Manage tab and then click the Modules tab.
From the Activated On Grid list, click the BMC-SA-Event_Orchestration_Configuration module.
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.
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.
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.
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...

On the Grid Manager, click Manage > Modules and click the AutoPilot-OA-Credentials_Store module.
Expand the configuration tree until you can navigate to the configuration item that you want to modify.
Click the configuration item that you want to modify, edit the value, and click OK to save changes.
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.

Product	Supported version
TrueSight Presentation Server	11.3.02
BMC Remedy AR System	9.1.03
TrueSight Orchestration Platform	8.2.00

Installing the Event Orchestration runbook

Preparing to install the runbook

Installing the runbook by using the wizard

Installing the runbook silently

Content artifacts installed with the runbook

Complete the post-installation tasks

Configure the SSH adapter

Update BMC-SA-Event_Orchestration_Configuration module configuration

Update Credentials Store module configuration

Where to go from here

Comments