Configuring File Observer jobs

Using the File Observer functionality, you can write bespoke data to a file in a specific format, upload this data to the topology service, and then visualize this data as a topology view in the Agile Service Manager UI.

The File Observer is installed as part of the core installation procedure.

The File Observer reads topology data from files located in the $ASM_HOME/data/file-observer/ directory, and uploads it. You must create these files manually.

Topology data in a file is comprised of vertices (nodes) and edges. A vertex represents an object (resource), while an edge represents the relationship between two objects.

Each line of the file you create should be in one of the formats below, loading a single resource vertex (including optional relationships in the _references field) or a single edge, deleting a single vertex, or pausing execution.

Lines starting with V: (vertex), E: (edge), D: (delete) or W: (wait) are treated as instruction lines to be processed. Other lines, for example lines that are empty or commented out, are ignored.

Line format
V:
Load a resource vertex, with a JSON representation as documented for the body of the topology service API method: POST /resources
If specifying the _status element, acceptable state values are open, closed, or clear, and acceptable severity values are clear, indeterminate, warning, minor, major, or critical.
E:
Load an edge, with a JSON representation as documented for the _references section of the body of the topology service API method POST /resources
D:
Delete a resource vertex, identified by it's uniqueId
W:
Pause for the given duration (for testing purposes only).
Takes an integer period followed by a string specifying the units.
Tip:
  • An example file is available in the $ASM_HOME/data/file-observer directory.
  • See the related links for more information on available timestamps formats.
Important: Ensure that the file is structured correctly. For each line of the file, information included after the closing } that matches an opening { is ignored, and no error is recorded.
File Load job
By default, these jobs are one-off, transient jobs that perform a full upload of all requested topology data as soon as they are triggered.
You can also run these jobs (again) manually from the Observer UI, or schedule them to run at set times when configuring them.
Table 1. File Observer job parameters
Parameter Action Details
Unique ID Enter a unique name for the job Required
File Name Specify the name of the file to be loaded. Required. Must be relative to the $ASM_HOME/data/file-observer/ directory (rather than absolute).
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.
Observer job description Enter additional information to describe the job. Optional
  1. From the Observer Configuration UI, click Configure under the File icon, or select an existing File job to be edited.
  2. Enter or edit the following parameters:
    • Unique ID
    • File Name
  3. Optional: Define a Job schedule (for Load jobs only) by setting the time 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, if required. 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.
  4. Optional: Enter an Observer job description to explain the purpose of the job in more detail.
  5. Click Run job to save your job and begin retrieving information.
The File Observer job loads all requested topology data from the file specified. This job runs only once.
Run this job whenever the content in your file has been updated.
Optional configuration: The size of file posted to the File Observer is set to 8Mb by default for on-prem deployments. A limit is useful in guarding against, for example, some types of denial-of-service (DOS) attacks. You can change the default.
On-prem
Access the /opt/ibm/netcool/asm/etc/nginx/conf.d/nasm-file-observer.rules file and change the following property: 
client_max_body_size 8m
On OCP
No limits exist.