Configuring REST Observer jobs

Use the REST Observer for obtaining topology data via REST endpoints. This observer is a counterpart to the File Observer.

Before you begin

The REST (or RESTful) Observer is installed as part of the core installation procedure.

About this task

The REST Observer passes topology data to Agile Service Manager using a RESTful set of interfaces, which provide REST APIs that enable the following functionality:

Management of Listen and bulk-replace job types.
The insert-update (HTTP POST) of resources.
The insert-update (HTTP POST) of relationships.
The insert-replacement (HTTP PUT) of resources.
The deletion (HTTP DELETE) of resources.
A REST API that supports the deletion (HTTP DELETE) of all relationships of a given type from a specified resource.
A REST API that supports the deletion (HTTP DELETE) of a specific relationship.
Restriction: Resources created via REST can have a provider, but not an observer.

Benefits

Using the REST Observer rather than the File Observer or Topology Service APIs includes the following benefits:

The ability to provide data to Agile Service Manager via HTTP REST Endpoints instead of files.
The processing performed by all observers in their framework ensures that meta-data about observations from observers is managed correctly.
A simple way of deleting all edges of a given type on a resource or a specific edge instance.

To use the REST Observer, a job request must be issued (HTTP POST) to the observer instance job management APIs before sending data to the Resource and Relationship APIs.

Listen

A long-running listen job capable of consuming topology data over a long period of time.

A listen job is designed to support scenarios where the input data stream is unpredictable, or there is little or no consistency or versioning of resources within the data stream.

Note: These examples assume that the environment variables have been set in rest_observer_common.sh.

start

$ASM_HOME/bin/rest_observer_listen_start.sh

stop

Default job:

./bin/rest_observer_listen_stop.sh

Named job:

env unique_id='My job name' $ASM_HOME/bin/rest_observer_listen_stop.sh

Synchronize (bulk replace)

A long-running job with the same resource replace semantics as the File Observer.

Bulk-replace jobs are designed to support scenarios where a known set of resources are subject to updates or versioning, and a prior observation about resources is to be replaced with a new one.

This job can provide a new set of resources and relationships and synchronize them to Agile Service Manager, thereby causing any previous data provided by the Observer to be deleted and replaced with the new data.

Note: These examples assume that the environment variables have been set in rest_observer_common.sh.

start

Default job:

./bin/rest_observer_bulk_replace_start.sh

Job with bulk_replace_unique_id and provider given:

env bulk_replace_unique_id=manageDataCenter provider=MyJavaProgram $ASM_HOME/bin/rest_observer_bulk_replace_start.sh

synchronize

Default job:

./bin/rest_observer_bulk_replace_synchronize.sh

Named job:

env unique_id='My job name' $ASM_HOME/bin/rest_observer_bulk_replace_synchronize.sh

stop

Default job

$ASM_HOME/bin/rest_observer_bulk_replace_stop.sh

Named job

env unique_id='My job name' $ASM_HOME/bin/rest_observer_bulk_replace_stop.sh

Note: In both cases, a provider job parameter is required to identify the origin of the data being provided to the Observer job.

Once a job request has been successfully submitted, you can start to provide data to the Resource and Relationship APIs on behalf of a given job instance.

The Resource and Relationship APIs may respond with an HTTP 503 Service Unavailable response with a Retry-After: 10 seconds in the header. This indicates that even though the request against those APIs is valid, the observer has not been able to ascertain that meta-data about the job is held in Agile Service Manager yet; this may be due to, for example, any prevailing conditions in the network that support the Agile Service Manager micro-services.

Tip: If such a response is received, try the request again later.

Important: Ensure that the body is structured correctly. When posting the body, information included in the body after the closing } that matches an opening { is ignored, and no error is recorded.

Tip: For sample code, see the 'Defining REST Observer jobs' topic:

Procedure

On the Observer jobs page, perform one of the following actions:

To edit an existing job

Open the List of options overflow menu next to the job and click View & edit.

To create a new job

Click Add a new job + and select the Rest Observer tile.

Choose either listen or bulk replace from the job type drop-down.

Configure the following parameters for the bulk replace or listen jobs, then click Save to save and then run your job.

Table 1. REST Observer **listen** and **bulk replace** job parameters
Parameter	Action	Details
Unique ID	Enter a unique name for the job	Required
Provider	Specify the name of the program or system to provide data.	Required
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 parameters, such as matchTokens.	Optional. Tip: You can define access scope for locations, project names, namespaces, and so on.
Generate debug support file	Set the optional Generate debug support file parameter to `True` to capture the output of the next scheduled job run as a file. This file is 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-premises $ASM_HOME/logs/<obs>-observer/ On OpenShift Container Platform /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. If you set them at less than 15 minutes, a warning is displayed, as the frequency can impact system performance.