3.6.5 Definition file manipulation function

(a) Host to retrieve

A single host can retrieve a list of definition files that can be retrieved in a single run. If you want to get a list of definition files from more than one host, you must run it multiple times.

(b) List of definition files to be acquired

Retrieves a list of user-created definition files that are defined in a definition file that can be updated by JP1/IM - Manager or JP1/IM - Agent, or user-created-definition file list definition file (imdd_user_deffile_list) or user-definition file list file (.json).

For details on the definition files that can be updated by JP1/IM - Manager or JP1/IM - Agent, and the files that can be defined by user-created-definition file list definition file and user-definition file list file, see the note of List of definition files in Chapter 2. Definition Files in the JP1/Integrated Management 3 - Manager Command, Definition File and API Reference.

For details on user-created-definition file list definition file and user-definition file list file, see the appropriate file in Chapter 2. Definition Files refer to the appropriate file in the JP1/Integrated Management 3 - Manager Command, Definition File and API Reference.

The following table shows the items for each file that are retained as internal information in the list.

For files with incorrect user-created-definition file list definition file or user-definition file list file definitions, add them to the list as files with invalid definitions.

(a) Host to retrieve

You can retrieve definition files from a single host for a host that you can retrieve in a single run. If you want to retrieve the definition file from more than one host, you must run it multiple times.

(b) Definition file that received the acquisition request

Returns the definition file requested for retrieval in a single zip file. Returns a zip file-whether the destination is a Windows, Linux. The name of zip file is "hostname from which the definition file is retrieved_current time of the Integration Manager host (YYYYMMDDhhmmssSSS).zip"(YYYYMMDDhhmmssSSS is the local time of the Integration Manager host). If a file name is duplicated when a file is created, the current time is acquired again. When retrieving from integrated operation viewer window, the upper limit of the file size is 10 files for 1MB, retrieval. In addition to the definition file, the contents of zip file are included in definition file properties file.

The extension fields that are set in zip file created by the definition file manipulation function use the "Extended Timestamp Extra Field" supported by Go. The update date and time of the definition file created when zip file is extracted is expressed in the time zone of JP1/IM - Manager host.

Important

When extracting zip files, use a tool that supports Extended Timestamp Extra Field. If you use an unsupported zip decompression tool, the update date and time of the definition file created when you extract zip file is not represented by JP1/IM - Manager time zone when JP1/IM - Agent time zone differs. Also, Windows Server standard zip does not support "Extended Timestamp Extra Field".

(c) Definition file properties file

For details about definition file properties file that summarizes the information in the definition file, see Definition file properties file (imdd_file_properties.json) in Chapter 2. Definition Files in the JP1/Integrated Management 3 - Manager Command, Definition File and API Reference. Place this file in zip when the definition file is retrieved. When you use the definition file update facility or the definition file deletion facility, you can use information about the location of the definition file or the post-placement import operation.

(a) Files that can be deleted

The files that can be deleted are those that are defined in user-created-definition file list definition file or user-definition file list file and that actually contain the files.

If you want to use the definition file manipulation function for a file that can be created in any folder of the definition files of the Integration Manager, you must place it in Manager path \conf\imdd\user. For a logical system, replace "Manager-path" with "shared-folder\JP1IMM".

For details about the files that can be defined in user-created-definition file list definition file or user-definition file list file, see the note in List of definition files in Chapter 2. Definition Files in the JP1/Integrated Management 3 - Manager Command, Definition File and API Reference.

(b) Backing Up Files to Delete

Leave only one generation of backups before deleting files. After the deletion is complete, the backup file is deleted.

(c) Importing definitions after file deletion

After the file is deleted, the content described in updateaction of user-definition file list file is executed, and the definition information is updated.

(d) Recovery when an operation for definition import fails

If the operation for definition import fails, the deleted file is restored from the file that was being backed up. After that, the system executes the information described in user-created-definition file list definition file's updateaction again for definition import and recovers the definition information to the state that existed prior to the deletion of the file.

(e) Deleting backup files

After deleting a file or executing an operation for importing a file, the file that was being backed up is deleted regardless of whether the operation succeeded or failed. When executing the process of deleting a file, if a file with an update date of at least one day before the time of deletion exists in the destination of the backup file, the file is also deleted. Even if the deletion of the backup file fails, the deletion function of the definition file continues.

(f) Printing Integrated Trace Logs and issuing JP1 events

Outputs success and failure information about the delete operation of the definition file to the consolidation tray log. If the deletion is successful, it issues a JP1 event for the event ID:00007640. If the deletion fails, it issues a JP1 event for the event ID:00007641.

If the status is 200 in the definition file deletion API, the displayed message is KAJY68115-I. It is KAJY68116-E when the status is other than 200.

For output of the integrated trace log, deletion of the definition file of integrated agent is also output by the deletion function of the definition file of the integration manager.

Important

• If you delete a user-created definition file, edit user-created-definition file list definition file to delete the deleted file. If you do not delete the file information, KAJY68102-W message is displayed when the definition file list is retrieved.

• If you delete information about a file that you plan to delete from user-created-definition file list definition file prior to deleting a user-created definition file, the file cannot be deleted, leaving unnecessary definition files. If this happens, add the information of the file to be deleted to user-created-definition file list definition file. After adding the file, delete the file using the definition file deletion facility, or delete the file by logging in directly to the host where the definition file is located.

(a) Updatable file

The files that can be updated are files that actually exist and can be updated from the list of definition files.

If you want to use the definition file manipulation function for a file that can be created in any folder of the definition files of the Integration Manager, you must place it in Manager path\conf\imdd\user. For a logical system, replace "Manager-path" with "shared-folder\JP1IMM".

For details about the files that can be acquired in the definition file list, see 3.6.5(1)(b) List of definition files to be acquired.

(b) Backing up files to update

Leave only one generation of backups before updating the file.

(c) Importing definitions after file update

After updating the file, execute the information described in updateaction of user-definition file list file and update the definition information.

Out of the definition files of JP1/IM3 - Manager, for the definition files that import the definition contents by executing the jco_spmd_reload command import the definition at the same time as the definition file is updated. For definition files that import the definition contents by a command other than the jco_spmd_reload command, execute the command in Manual execution of a response action to reflect the definition information.

(d) Recovery when an operation for definition import fails

If the operation for definition import fails, the updated file is restored from the file that was being backed up. Executes the information described in user-definition file list file's updateaction for redefinition import, and then recovers the definition information to the status prior to the file update.

(e) Deleting Backup Files

After the operation execution processing for updating the file or for importing the file is completed, the file that was being backed up is deleted regardless of whether the operation succeeded or failed. When executing the process of deleting a file, if a file whose update date is at least one day earlier than the time of deletion exists in the backup file storage location, the file is also deleted. Even if the deletion of the backup file fails, the deletion function of the definition file continues.

(f) Printing Integrated Trace Logs and issuing JP1 events

Outputs success and failure information for update processing of the definition file to the integrated trace log. If the update is successful, it issues a JP1 event for the event ID:00007642. If the update fails, issue JP1 event of the event ID:00007643.

If the status is 200 in the definition file update API, the message that is output is KAJY68119-I. If the status is anything other than 200, the message is KAJY68120-E.

For the log output of the integrated trace log, the update function of the definition file of the integration manager also outputs the update of the definition file of integrated agent.

(g) Definition files that reflect definition information using jco_spmd_reload

If the definition file is updated with an error in the definition information for a definition file that reflects definition information using jco_spmd_reload, the following behavior occurs.

• The integrated operation viewer or the result of running of REST API does not result in an error.

• The definition file recovery process is not performed, and the definition file with incorrect definition information is placed on the manager host.

• An error message stating that the definition information is incorrect is output in the integrated trace log.

If the definition cannot be reflected correctly after the definition information is reflected, modify the definition information according to the response to the message output in the integration trace log, and update the definition information again.

The definition files that use the jco_spmd_reload to reflect definition information are as follows:

• File that defines the event source host mapping (user_hostmap.conf)

• Health check definition file (jcohc.conf)

• Event guide information file (jco_guide.txt)

• Correlation event generation system profile (egs_system.conf)

• Severity changing definition file (jcochsev.conf)

• Definition file for extended event attributes

• Definition file for extended event attributes (extended file)

• File that defines which items are displayed for common exclusionconditions (common_exclude_filter_attr_list.conf)

• File that defines automatic input of common exclusionconditions (common_exclude_filter_auto_list.conf)

• File that defines which items are displayed for repeated event conditions (event_storm_attr_list.conf)

• File that defines automatic input of repeated event conditions (event_storm_auto_list.conf)

• File that defines which items are displayed for severity changing definitions (chsev_attr_list.conf)

• File that defines automatic input of severity changing definitions (chsev_auto_list.conf)

• Definition file for opening monitor windows

• Definition file for changed display messages (jcochmsg.conf)

• File that defines automatic input of display message change definitions (chmsg_auto_list.conf)

• File that defines which items are displayed for display message change definitions (chmsg_attr_list.conf)

(h) Notes

• It takes time to check whether the operation for importing the definition has been reflected correctly. The confirmation time of the reflection process is set in item "service_startup_wait_time" of the imagent configuration file (jpc_imagent.json).

  In addition, update processing of the definition file is performed for each file to be updated. When updating multiple files, it takes time to complete depending on the number of files.

  Note that if you update more than one file, the timeout for file manipulation specified in imbase configuration file (jpc_imbase.json) "file_operation_timeout" field may be exceeded. If the timeout period is exceeded, update will fail. Adjust the setting so that the following conditions are met:

  Confirmation time of reflection process (service_startup_wait_time) × number of concurrent update files < timeout period for file operation processing (file_operation_timeout)

  Because the timeout period for file operation processing is the timeout period for the entire file operation processing, set a value with plenty of time.

  For details about the above definition files, see imagent configuration file (jpc_imagent.json) and imbase configuration file (jpc_imbase.json) in Chapter 2. Definition Files in JP1/Integrated Management 3 - Manager Command, Definition File and API Reference.