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"
 
"Definition file destination agent host management destination Manger host name"
-----5a6a576p44OV44Kh44Kk44Or5pu05paw
Content-Disposition: form-data; name="agentHostName"
 
"Definition file destination agent host name"
-----5a6a576p44OV44Kh44Kk44Or5pu05paw
Content-Disposition: form-data; name="file"; filename="/C:/Users/xxxxx/Desktop/sample.zip"
Content-Type: application/zip
 
zip data
-----5a6a576p44OV44Kh44Kk44Or5pu05paw
]

Parameters

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

Parameter	Optional	Description
filename	No	Specifies 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.
400	KAJY68111-E	Request parameter is invalid.
403	KAJY01000-E	The privilege of the user used for authentication is insufficient.
500	KAJY68104-E	JP1/IM agent control base encountered an error.
500	KAJY00009-E	Request body limit exceeded.
500	KAJY00007-E	System error has occurred (out of disk, out of memory, etc.).

Response

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

{
  "filelist":[
    {
      "filename": "File name",
      "filepath": "File's absolute path",
      "result": "Updating file result",
      "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.

Examples

Request:

POST http://hostname:20703/im/api/v1/fileOperation/updateFile HTTP/1.1
Content-Type:application/json
[
-----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
 
zip data
-----5a6a576p44OV44Kh44Kk44Or5pu05paw
]

Response:

HTTP/1.1 200 OK
Content-Type:application/json
... (omitted) ...
 
{
  "filelist":[
    {
      "filename": "jpc_imagent.json",
      "filepath": "C:\\Program Files\\HITACHI\\jp1ima\\conf",
      "result": "update fail",
      "message": "KAJY68112-W Failed to delete a definition file. (File name: jpc_imagent.json, File path: C:\\Program Files\\HITACHI\\jp1ima\\conf, Cause: Definition file is locked.)"
    }, ...
  ]
}

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.

To Page Top