Defining ALM Observer jobs

Using the Agile Lifecycle Manager Observer, you can define jobs that dynamically load data associated with intent from the Agile Lifecycle Manager for analysis by Netcool Agile Service Manager.

Before you begin

Important: The ALM Observer supports IBM Agile Lifecycle Manager Version 2.2.

Attention:

The ALM observer supports the discovery of Cloud Pak for Network Automation (CP4NA) and has been tested against versions 2.3.x and 2.4.x.

The ALM observer was first developed to integrate with the legacy Telco Network Cloud Manager (TNCM) Orchestrator (TNCO/ALM). A re-branding from ALM (Agile Lifecycle Manager) to CP4NA happened, while the observer retained its ALM name.

The observer has some level of backward compatibility with the legacy ALM.

Ensure you have the Agile Lifecycle Manager Kafka server host and topics to hand, such as the Agile Lifecycle Manager server, the Kafka port, and the topics used for lifecycle events.

Important: To access Agile Lifecycle Manager remotely, you must ensure that the Agile Lifecycle Manager installation has been configured with the KAFKA_ADVERTISED_HOST_NAME so as to allow remote connections. For more information, see the Configuration reference topic in the Agile Lifecycle Manager documentation at the following location: https://www.ibm.com/support/knowledgecenter/SS8HQ3_2.2.0/GettingStarted/r_alm_quickreference.html

The Agile Lifecycle Manager Observer is installed as part of the core installation procedure.

About this task

The Agile Lifecycle Manager Observer jobs listen to the Kafka 'state change' topics of Agile Lifecycle Manager, as well as the Agile Lifecycle Manager Resource Manager. Information is extracted from Agile Lifecycle Manager about Assemblies and Resources and a topology is created.

alm_observer_common.sh: The configuration file you use to customize the listening job for the Agile Lifecycle Manager lifecycle events topic.; The parameters defined here are then used by the alm_observer_listen_start.sh script to trigger the ALM Observer job.
alm_observer_common_rm.sh: The configuration file you use to customize the listening job for the Agile Lifecycle Manager Resource Manager lifecycle events topic.; The parameters defined here are then used by the alm_observer_listen_start_rm.sh script to trigger the ALM Observer job.

After installation, you define and start the following two jobs. You must edit the parameters in the configuration file before running these jobs.

Listener for Agile Lifecycle Manager lifecycle events: A long-running job that monitors its source for updates and runs until it is explicitly stopped, or until the observer is stopped.; This job is started by the alm_observer_listen_start.sh script.
Listener for Agile Lifecycle Manager Resource Manager lifecycle events: A long-running job that monitors its source for updates and runs until it is explicitly stopped, or until the observer is stopped.; This job is started by the alm_observer_listen_start_rm.sh script.

Remember: Swagger documentation for the observer is available at the following default location: https://<your host>/1.0/alm-observer/swagger

Procedure

Edit the following parameters in the alm_observer_common.sh configuration file:

Table 1. ALM Observer parameters for **alm** jobs
Parameter	Action	Details
Unique ID	Enter a unique name for the job	Required
IBM Agile Lifecycle Manager instance name	Use this to identify the Agile Lifecycle Manager installation and any associated Resource Managers.	Required
Group ID	Use this to identify the Kafka group ID to be used.	Required
Connection	Use this to specify the Kafka Host and Port to be used.	Required
ALM State Change Topic	Use this to identify the Agile Lifecycle Manager Kafka topic name to be consumed.	Required
ALM Service State Transition Topic	Use this to identify the Agile Lifecycle Manager State Transition Kafka topic name to be consumed.	Required
Secured or unsecured Kafka connection	Select false or true to make secured or unsecured connection to the CP4NA server. The default is 'false'.	Required. When set to 'true', you must also provide the credentials and target system certificate parameters. See the following topic for more information on obtaining connection and credential details: IBM Cloud Pak for Network Automation: Configuring Kafka connections
Kafka username	Enter the username of the secured Kafka cluster.	Required only if the parameter for secured connection has been set to 'true'.
Kafka password	Enter the password of the secured Kafka cluster.	Required only if the parameter for secured connection has been set to 'true'.
Certificate	Enter the certificate of the secured Kafka cluster.	Required only if the parameter for secured connection has been set to 'true'. For more information, see Configuring observer job security. On-prem Create and store the certificate in the ASM_HOME/security directory. OCP Obtain the authentication certificate using OpenSSL and store it as a secret.
Access scope	Enter text to provide a scope for the resources. Access scope can help map alerts to resources when resources in different scopes share the same parameters, such as matchTokens.	Optional. Tip: You can define access scope for locations, project names, namespaces, etc.
Generate debug support file	Set the optional Generate debug support file parameter to 'True' in order to capture the output of the next scheduled job run as a file. This file will be stored with an observer's log files and can be used to debug observer issues, for example at the request of your designated Support team, or while using a test environment. For one-off jobs (that is, Load jobs), this parameter reverts to 'False' after the next completed run. To examine the output produced, you can load the generated debug file using the File Observer. The file is saved to the following locations: On-prem $ASM_HOME/logs/<obs>-observer/ On OCP /var/log/itsm/<obs>-observer	Optional
Observer job description	Enter additional information to describe the job.	Optional
Job schedule	Specify when the job should run, and whether it should run at regular intervals. By default the job runs immediately, and only once. Optionally you can specify a future date and time for the job to run, and then set it to run at regular intervals after that.	Optional. Transient (one-off) jobs only. If you set a job schedule, the run intervals must be at least 90 seconds apart, and if you set them at less than 15 minutes, a warning is displayed, as the frequency can impact system performance.

Edit the following parameters in the alm_observer_common_rm.sh configuration file:

Table 2. ALM Observer parameters for ALM rm (Resource Manager) jobs
Parameter	Action	Details
Unique ID	Enter a unique name for the job	Required
IBM Agile Lifecycle Manager instance name	Use this to identify the Agile Lifecycle Manager installation and any associated Resource Managers.	Required
Group ID	Use this to identify the Kafka group ID to be used.	Required
Connection	Use this to specify the Kafka Host and Port to be used.	Required
Topic	Use this to identify the Agile Lifecycle Manager Resource Manager Kafka topic.	Required
Secured or unsecured Kafka connection	Select false or true to make secured or unsecured connection to the CP4NA server. The default is 'false'.	Required. When set to 'true', you must also provide the credentials and target system certificate parameters. See the following topic for more information on obtaining connection and credential details: IBM Cloud Pak for Network Automation: Configuring Kafka connections
Kafka username	Enter the username of the secured Kafka cluster.	Required only if the parameter for secured connection has been set to 'true'.
Kafka password	Enter the password of the secured Kafka cluster.	Required only if the parameter for secured connection has been set to 'true'.
Certificate	Enter the certificate of the secured Kafka cluster.	Required only if the parameter for secured connection has been set to 'true'. For more information, see Configuring observer job security. On-prem Create and store the certificate in the ASM_HOME/security directory. OCP Obtain the authentication certificate using OpenSSL and store it as a secret.
Access scope	Enter text to provide a scope for the resources. Access scope can help map alerts to resources when resources in different scopes share the same parameters, such as matchTokens.	Optional. Tip: You can define access scope for locations, project names, namespaces, etc.
Generate debug support file	Set the optional Generate debug support file parameter to 'True' in order to capture the output of the next scheduled job run as a file. This file will be stored with an observer's log files and can be used to debug observer issues, for example at the request of your designated Support team, or while using a test environment. For one-off jobs (that is, Load jobs), this parameter reverts to 'False' after the next completed run. To examine the output produced, you can load the generated debug file using the File Observer. The file is saved to the following locations: On-prem $ASM_HOME/logs/<obs>-observer/ On OCP /var/log/itsm/<obs>-observer	Optional
Observer job description	Enter additional information to describe the job.	Optional
Job schedule	Specify when the job should run, and whether it should run at regular intervals. By default the job runs immediately, and only once. Optionally you can specify a future date and time for the job to run, and then set it to run at regular intervals after that.	Optional. Transient (one-off) jobs only. If you set a job schedule, the run intervals must be at least 90 seconds apart, and if you set them at less than 15 minutes, a warning is displayed, as the frequency can impact system performance.

Note: The value of the almInstall parameter needs to be the same for both jobs to allow for the topology to be combined.

Tip: Alternatively, you can set the appropriate environment variables. If an environment variable is set, it takes precedence over the configuration file settings.

To start the Agile Lifecycle Manager Observer Listener for Agile Lifecycle Manager lifecycle events job, use the following command:
```
$ASM_HOME/bin/alm_observer_load_start_rm.sh
```
The Listener for Agile Lifecycle Manager lifecycle events job monitors its source for updates and runs until it is stopped, or until the observer is stopped.
To start the ALM Observer Listener for Agile Lifecycle Manager Resource Manager lifecycle events job, use the following command:
```
$ASM_HOME/bin/alm_observer_listen_start_rm.sh
```
The Listener job monitors its source for updates and runs until it is stopped, or until the Observer is stopped.

What to do next

You can also use the following scripts:

alm_observer_listen_stop.sh: This script stops the Listener job for Agile Lifecycle Manager lifecycle events.
alm_observer_listen_stop_rm.sh: This script stops the Listener job for Agile Lifecycle Manager Resource Manager lifecycle events.
alm_observer_job_list.sh: This script lists the current job status.
alm_observer_log_level.sh: This script sets the log level.

Remember: As an alternative to being configured using the Observer Configuration UI, observer jobs have scripts to start and stop all available jobs, to list the status of a current job, and to set its logging levels. These scripts can be run with -h or --help to display help information, and with -v or --verbose to print out the details of the actions performed by the script, including the full cURL command. For the on-prem version of Agile Service Manager, observer scripts are configured for specific jobs by editing the script configuration files.