5.17.4 Updated definition file

Description

Update JP1/IM - Manager or JP1/IM - Agent definition file.

Execution permissions

Following permissions are required:

When specify "Manager" at hostCategory

JP1 resource group: *
JP1 permission level: JP1_Console_Admin

When specify "Agent" at hostCategory

JP1 permission level: JP1_Console_Admin

API version

Format

Request line

POST /application/component/apiVersion/fileOperation/updateFile httpVersion

Request header

Authorization:BeareranAxYWRtaW46TUdGa01tTTJNMlV3TURFNFh6STNYekE0T2pJME9qTXpYMTlmWDE5ZlgxOWZYMTlmWDE5ZlgycHdNV0ZrYldsdUlDQWdJQ0FnSUNBZ0lDQWdJQ0FnSUNBZ0lDQWdJQ0Fn
Accept-Language: ja

Follow the request header in 5.2.3 Request format.However, Content-Type has the following format:

Content-Type: multipart/form-data; boundary=-----5a6a576p44OV44Kh44Kk44Or5pu05paw
Content-Length: 1024000
Accept: application/json

Request message body

[
-----5a6a576p44OV44Kh44Kk44Or5pu05paw
Content-Disposition: form-data; name="hostCategory"
 
"host-type"
-----5a6a576p44OV44Kh44Kk44Or5pu05paw
Content-Disposition: form-data; name="managerHostName"
 
"manager-host-name-for-definition-file-destination"
-----5a6a576p44OV44Kh44Kk44Or5pu05paw
Content-Disposition: form-data; name="agentHostName"
 
"agent-host-name-for-definition-file-destination"
-----5a6a576p44OV44Kh44Kk44Or5pu05paw
Content-Disposition: form-data; name="file"; filename="/C:/Users/xxxxx/Desktop/sample.zip"
Content-Type: application/zip
 
Binary data of a zip file
-----5a6a576p44OV44Kh44Kk44Or5pu05paw
]

Parameters

Here are the parameters that you specify for message body of the request:

Parameter	Optional	Description
filename	No	Specify the absolute path to file named after zip has been compressed. File number must be between 1 and 200 bytes. Does not check the file size limit and checks the request body size limit.
hostCategory	No	Specify "Manager" or "Agent" as host type. Performs an action on the defined file of the specified host type.
managerHostName	See Description column	When hostCategory is "Manager" Ignores the specified item. Assuming that your host is the manager host for JP1/IM, refresh file of the manager host in JP1/IM. When hostCategory is "Agent" Specify a value from 1 to 255 bytes for the JP1/IM manager host name that manages the agent to which the definition file is to be updated.
agentHostName	See Description column	When hostCategory is "Manager" Ignores the specified item. When hostCategory is "Agent" Specify the agent host name of the definition file update destination with 1 to 255 bytes.

Status codes

The following table describes the status codes that are returned as a response to the request:

Status code	Message	Description
200	--	API operation was successful.
200	KAJY68126-W	JP1/IM agent control base encountered a warning.
400	KAJY68111-E	Request parameter is invalid.
400	KAJY68205-E	Integrated agent host name specified in the request does not exist in JP1/IM - Manager Logged in as does not have read/manipulate permissions for integrated agent specified in the request The information of the integration agent or the host specified in the request is not in the unified agent host management DB
403	KAJY01000-E	The privilege of the user used for authentication is insufficient.
500	KAJY68104-E	JP1/IM agent control base encountered an error.
	KAJY00009-E	Request body limit exceeded.
	KAJY00007-E	System error has occurred (out of disk, out of memory, etc.).
	KAJY68203-E	Cannot connect to Intelligent Integrated Management Base.
	KAJY68212-E	Cannot connect to JP1/IM agent base.
	KAJY68501-E	Unable to connect to the manager's unified agent host management DB.

Response

If the status code is 200, the following is returned to the response body in JSON format:

{
  "filelist":[
    {
      "filename": "file-name",
      "filepath": "absolute-path-of-file",
      "result": "result-of-file-updating",
      "message": "message"
    }, ...
  ]
}

Member name	Description
filename	Describes file name.
filepath	Describes the absolute path where file will be placed.
result	Describes the outcome of file updating. See Table 5-16 for the strings to be described.
filelist:message	Provides the error message ID and its body if file refresh attempt fails. If it succeeds, omit this item. If result is recovery fail, the error message in the table indicates message when the import operation failed.

Table 5‒16: Contents of the result
Overriding File	Operations for importing definition	Recovery process	Content of result
Y	Y	--	success
N	--	--	update fail
Y	N	Y	action fail
Y	N	N	recovery fail

Legend: Y: Succeeded, N: Failed, --: No processing

Return values

When the status code is 200

None

When the status code is other than 200

In message body of the response, the exception object in the response format described in 5.2.6 Error response message when an error occurs is returned.

If JP1/IM - Manager is version 13-10 or later and JP1/IM - Agent of Agent hostto which the definition file is updated is version 13-10 or later, and all definition files fail to be updated, set the following information in extensions (extended information):

Item	Description
filelist	JSON format shown in the response body of the explanation item "Response" in this API

Examples

Request:

POST http://hostname:20703/im/api/v1/fileOperation/updateFile HTTP/1.1
Content-Type: multipart/form-data;boundary=-----5a6a576p44OV44Kh44Kk44Or5pu05paw
[
-----5a6a576p44OV44Kh44Kk44Or5pu05paw
Content-Disposition: form-data; name="hostCategory"
 
"Agent"
-----5a6a576p44OV44Kh44Kk44Or5pu05paw
Content-Disposition: form-data; name="managerHostname"
 
"immanager"
-----5a6a576p44OV44Kh44Kk44Or5pu05paw
Content-Disposition: form-data; name="agentHostname"
 
"imagent"
-----5a6a576p44OV44Kh44Kk44Or5pu05paw
Content-Disposition: form-data; name="file"; filename="/C:/Users/xxxxx/Desktop/sample.zip"
Content-Type:application/zip
 
Binary data of a zip file
-----5a6a576p44OV44Kh44Kk44Or5pu05paw--
]

Response:

HTTP/1.1 200 OK
Content-Type:application/json
... (omitted) ...
 
{
  "filelist":[
    {
      "filename": "user_file_sd_config_test2.yml",
      "filepath": "C:\\Program Files\\Hitachi\\jp1ima\\conf\\user",
      "result": "update fail",
      "message": "KAJY68126-W A warning occurred in the integrated agent control platform. (detailed-information : KNBC20020-W Failed to update a definition file. (details = specified file not included in user-definition file list file. filename=C:\\Program Files\\Hitachi\\jp1ima\\conf\\user\\user_file_sd_config_test2.yml))"
    }, ...
  ]
}

Notes

Prior to updating file definition, make sure that the definition file format, character code, etc. are correct manually.

If file is invalid, updating might fail. If updating of the defined file fails, an JP1 event is sent. Check the details of JP1 event that occurred and take appropriate action.
Some services are automatically restarted when file is updated.

The monitoring operation may be temporarily stopped by restart of the service. Also, in a clustered configuration, a setup^# in outage detection times for the monitored services in the cluster software might cause a failover. Therefore, you should refresh file during system-maintenance hours.

#

The estimate of the stop detection time depends on the machine specification and the load condition. However, since the service is restarted for each update of one definition file, consider that it is about one minute for each definition file.

For example, if you are updating 10 files at the same time, set setup for the cluster software shutdown detection period to 10 minutes.

If you cannot increase the detection time, do not use the definition file manipulation feature and login the host. Then, refresh the direct definition file.

You cannot execute the REST API for updating definition files from response actions.

For details, see 3.15.7(3)(l) Notes on Executing REST API from response actions in the JP1/Integrated Management 3 - Manager Overview and System Design Guide.

To Page Top