4.4.4 List of methods

The method returns the configuration information of each product in JSON format. When host name is written to target host definition file for configuration collection (imdd_target_host.conf), in the Intelligent Integrated Management Base, call this method only when checking the return value of the adapter command after it is called and finding the value is 0.

• If the configuration information is collected successfully

  In the __configurationGet method, call the args.setResult (configuration information in JSON format) method.

• If the method fails to collect the configuration information

  Call the args.setError (error message) method, instead of the args.setResult method.

In the __configurationGet method, either the args.setResult or args.setError method must be called if the __configurationGet method can process the component.

The __configurationGet method is called within the jddcreatetree command that creates the system management tree of the Intelligent Integrated Management Base.

Each user-created plug-in should refer to the value of args.component to determine if the plug-in can deal with the component.

The following table lists and describes the parameters of the __configurationGet method.

The following describes the list of configuration information returned by the __configurationGet method.

Formats

{
  "meta":{
    "timestamp":"created-time(ISO8601-formatted-UTC-time)",
    "objectRoot":[
        {
           "type":"object-root-node-type",
           "defaultSystem":
           {
             "name":"name-of-the-structured-identifier-of-the-default-system-node",
             "label":"display-name-of-the-default-system-node"
           }
        },...
                   ]
          },
    "simtData":[
             {"sid":"<SID>","value":{structured identifier}},
    ...
                 ]
}

Describe

The following table lists and describes what is contained in the list of obtained infrastructures.

Table 4‒8: Description in the list of obtained infrastructures

No.	Item	Data types	Description
1	meta	Object	An object that stores file information
2	timestamp	string	Returns the date and time of file creation as the UTC time in ISO8601 format. This attribute cannot be omitted. The time is the server time of JP1/IM - Manager.
3	objectRoot	array	An array that stores the object root node type and the default system node information. This attribute can be omitted.
4	type	string	Indicates the object root node type (such as a network device (NETWORKDEVICE) or storage (STORAGE)) placed under the root node of the tree and under the system node. The host (HOST) does not have to be specified. Make sure that it is placed under the root node of the tree and under the system node. This attribute can be omitted. If it is omitted, only the host is placed under the root node of the tree and under the system node.
5	defaultSystem	Object	Specify the attribute if you create a default system node whose parent node is the object root node. If this attribute is omitted, the default tree node of the object root node specified in type is placed directly under AllSystems.
6	name	string	Specifies the name of the configuration information SID for the default system node. If this attribute is omitted, the object root node type is set as the SID name of configuration information.
7	label	string	Specifies the label of the default system node. If this attribute is omitted, the label attribute is not set for the additional information of the default system node.
8	simtData	array	An array of configuration information
9	sid	string	Indicates the configuration information SID.
10	value	Object	Indicates a structured identifier

For details on the information the __configurationGet method retrieves from each product, see 7.1.4 Information retrieved from each product.

The following table lists and describes the functions that are affected by the configuration information set by setResult and its impact.

Similar to the __configurationGetAdapterless method, this method returns the configuration of the application in JSON format. Implement and use this method if you cannot implement adapter commands, such as monitoring SaaS. Intelligent Integrated Management Base invokes this method if you do not write host name in target host definition file for configuration collection (imdd_target_host.conf) only.

If you want to implement this method on each user-created plug-in, refer to value of args.component to determine if it can be processed.

The specific environment information required to implement this method (for example, information related to authentication when monitoring SaaS) is described in file defined in user-created plug-in. For details, see 4.6.1 Definition files used by user-created plug-ins.

The following table lists and describes the parameters of the __configurationGetAdapterless method.

• When acquisition of configuration information ends normally

  Invoke the args.setResult in __configurationGetAdapterless method (JSON format configuration information).

• When acquisition of configuration information fails

  Call args.setError (error message) method instead of args.setResult method.

In the __configurationGetAdapterless method, if the component can be processed by itself, be sure to call either args.setResult method or args.setError method.

The __configurationGetAdapterless method is called in jddcreatetree command that creates Intelligent Integrated Management Base system-managed tree.

The format of retrieving the list of configuration information returned by the __configurationGetAdapterless method, the description, and the effect of the configuration information set by setResult are the same as those of the __configurationGet method.

The main differences between the __configurationGet and __configurationGetAdapterless methods are listed below.

Therefore, the __configurationGet method and the __configurationGetAdapterless method are used differently as shown in the tables below.

The method collects the tree SID that corresponds to simtData in the input information together with additional information, and returns them in JSON format.

If a user-created plug-in implements the __createTreeNode method, the default tree of JP1/IM can be customized. For details on the default tree, see 7.4.2 Node generation function.

The user-created plug-in generates a tree node object and sets it with setResult if the tree SID of simtData is the target of the tree node to be customized. If simtData objects have identical values in both the object type and name of the target, they will be the same node in the tree. Therefore, configure simtData objects that have identical values in both the object type and name to return the same tree SID.

If you do not customize the parent node of the tree node to be customized, use the treeNodeCreator object to get the tree SID of the parent node portion and use it as a part of the tree SID.

• If the tree SID and additional information can be retrieved successfully

  Call the args.setResult (tree SID in JSON format) method within the __createTreeNode method.

• If the tree SID and additional information cannot be retrieved

  Call the args.setError (error message) method, not the args.setResult method.

If the __createTreeNode method itself can process SimtData, make sure to call either the args.setResult method or artgs.setError method within the __createTreeNode method.

The __createTreeNode method is called in the jddcreatetree command that creates a system management tree for the Intelligent Integrated Management Base.

The following table lists and describes the parameters of the __createTreeNode method.

The following describes the format of the tree SID and additional information returned by the __createTreeNode method.

Formats

{
    "meta":{
        "componentName":"name-of-the-component-from-which-tree-information-is-retrieved"
    },
    "simtData":[
        {"sid":"tree-SID","value":{structured-identifier}},
        ...
   ]
}

Describe

The following table lists and describes the items of the retrieved tree SID and additional information.

Table 4‒14: Items of the retrieved tree SID and additional information

No.	Item	Data types	Description
1	meta	Object	Indicates meta information.
2	componentName	string	Indicates the name of the component from which the tree information is retrieved.
3	simtData	Object	Indicates a simtData
4	sid	string	Indicates a tree SID
5	value	Object	Indicates a structured identifier

The following shows an example of retrieving information with the __createTreeNode method.

{
    "meta":{
        "componentName":"/HITACbHI/JP1/OA/CONFINFO"
    },
    "simtData":[
        {
           "sid":"_ROOT_AllSystems/_HOST_host1/_CATEGORY_job
           /_SUBCATEGORY_JP1%2FAJS3%20-%20Manager/_OBJECT_AJSROOT1",
           "value":
             {
                "target":["_JP1AJS-M_host1/_HOST_host1/_JP1SCHE_AJSROOT1"],
                "label":"AJSROOT1"}}
             }
        }
    ]
}

The following table lists and describes the function that is affected by the IM management node tree information set by setResult and its impact.

This method returns the configuration information SIDs corresponding to all JP1 events issued by each product. Each user-created plug-in must return the configuration information SID to the individual JP1 events issued by the corresponding product. Each user-created plug-in refers to the value, such as args.productName, and determines that the plug-in itself can deal with the event.

• If a configuration information SID has been successfully generated for each one of the issued JP1 events:

  Call the args.setTargetSid (configuration information SID) method in the __eventGet method.

• If an attempt to generate a configuration information SID corresponding to an issued JP1 event fails due to missing data in the JP1 event:

  Without calling the args.setError (error message) method, return from the method and exit the process.

The __eventGet method is called when the Intelligent Integrated Management Base gets the JP1 event.

The following table lists and describes the parameters of the __eventGet method.

The following table lists and describes the function that is affected by the SID information with setTargetSid set for it and its impact.

This method converts JSON format data to JP1 events.

The __transformEvent method, which is implemented in user-created plug-in, or product plugin, can convert an external system-generated event received in JP1 event transformation API into a JP1 event.

The following table lists and describes the parameters of the __ transformEvent method.

When using __transformEvent method in a plug-in, it is necessary to implement it so that the __transformEvent method determines whether the data of the input event information is data to be processed by the plug-in.

In addition, depending on the judgment result, it is necessary to implement the JP1 event to be returned to be set to setResult only when the data should be processed by the plug-in. If the data is not to be processed by your plug-in, return it without setting anything.

The JP1 event to be set to setResult returned by the __transformEvent method is set in the following format.

The format of the returned JP1 event is checked by the caller's JP1 event conversion API. If malformed, the JP1 event conversion API outputs a KAJY67000-W message in the response body.

In addition, JP1 events exceeding 100 cannot be issued. If more than 100 JP1 events are set in setResult, JP1/IM - Manager issues up to 100 events from the beginning of the JP1 event sequence and does not issue subsequent events. In the plug-in, please be able to determine the details of events that were not issued by outputting them to a log.

Note that __transformEvent method does not check whether the value of the attribute for the JP1 event to be created is invalid or not. If the value of the attribute is invalid, JP1/IM - Manager's JP1 event conversion API will fail, and the JP1 event with the error will not be issued.

Format

{
  "pluginName":Plug-in name,
  "exceedJp1eventMaxDetected":Detection of exceeding the upper limit of the number of converted JP1 events
  "events":[
    {
      "eventId":Event ID, 
      "message":Message,
      "attrs":{Extended attribute name: Extended attribute value, ...}
    },
    ...
  ]
}

Parameters

#

For details of JP1 event conversion API, see 5.6.5 JP1 Event converter.

Example

{
  "pluginName":"PFMCS",
  "exceedJp1eventMaxDetected":false
  "events":[
    {
    "eventId":"2FFF",
    "message":"xxxxx",
    "attrs":{"SEVERITY":"Error","JP1_SOURCEHOST":"HOSTB"}
    },
    ...
  ]
}

The method generates a relation between retrieved configurations and returns it in JSON format.

• If the relation between retrieved configurations is generated successfully

  In the __createLink method, call the addResult (relation information between the retrieved configurations in JSON format) method.

• If the configuration information could not be retrieved

  Call the args.setError (error message) method, instead of the addResult method.

Make sure you call either the addResult or args.setError method.

The __createLink method is called within the jddcreatetree command that creates the system management tree of the Intelligent Integrated Management Base.

The following table lists and describes the parameters of the __createLink method.

The following describes the format of relation information between retrieved configurations returned by the __createLink method.

Formats

Format of the configuration information set for setResult:

{
"meta":{
    "format":"file-type",
    "componentName":"name-of-the-component-whose-relation-information-is-to-be-retrieved",
    "timestamp":"generation-time-of-relation-information"
    },
    "links":[
        {
        "from":"SID-of-the-preceding-node",
        "to":"SID-of-the-succeeding-node",
        "type":"type-of-operation-target",
        "value":structured-identifier
     }, ...
  ],
}

Describe

The following table lists and describes the items of relation information between the retrieved configurations.

Table 4‒24: Items to describe the relation information between the retrieved configurations

No.	Item	Data type	Description
1	meta	array	Array that stores the data of the file
2	format	string	The file format Always set this to conf. This attribute cannot be omitted.
3	componentName	string	Name of the component whose relation information is to be retrieved This attribute cannot be omitted.
4	timestamp	string	Returns the date and time of file creation as the UTC time in ISO8601 format. This attribute cannot be omitted. The time is the server time of JP1/IM - Manager that generated the relation information.
5	links	array	Array for relation information between configurations. The order of the array is irrelevant. If multiple pieces of relation information with the same from, to, and type values are found, these values are output with the jddcreatetree command, but the last relation information that appeared takes effect if the jddupdatetree is used to apply the information to the system. However, if the configuration information is from a JP1/AJS plug-in (componentName is /HITACHI/JP1/AJS3/CONFINFO) and type is rootJobnetExecutionOrder (root jobnet execution order) and from and to have the same value, the Intelligent Integrated Management Base merges objects stored in the value.unit array into a single link object and outputs it as an IM management node link file.
6	from	string	Preceding node. It specifies the SID of the preceding node. Example _ToolA-M_hostA/_HOST_hostA If the to attribute is specified, this attribute can be omitted. It cannot accept any control character.
7	to	string	Succeeding node. It specifies the SID of the succeeding node. Example _ToolA-M_hostA/_ToolA-A_hostB/_HOST_hostB If the from attribute is specified, this attribute can be omitted. It cannot accept any control character.
8	type	string	Specifies the type of relation information. It cannot accept a string starting with an underscore (_) or any control characters. Alphanumeric characters are available. The maximum number of characters is 255 bytes. type describes a grouping of relations that have the same meaning. On the Related node tab in the Integrated Operation Viewer window, you can filter relations to display only those belonging to a specific type. For relations within a JP1/IM product or between a JP1/IM product and another product, the following types are used. In addition to these types, the use of user-specified types is also allowed. rootJobnetExecutionOrder: Relation of the execution order of root jobnets rootJobnetAgent: Relation between a root jobnet and an AJS agent managerAgent: Relation between the manager and agent of a JP1 product sameNode: Relation between nodes with the same name L2Connection: Relation between layer-2 connection lines managed by JP1/NNMi Infrastructure: Relation between infrastructure resources managed by JP1/OA monitoringConfiguration: Relation between a product and a monitoring target in a monitoring product configuration The user can also specify any type in addition to this type.
9	value	Object	Specifies additional information for relation information between configurations. The following shows parameters supported by default when type is rootJobnetAgent: precedingJob: Specifies the preceding job of a linked job by its full name. succeedingJob: Specifies the succeeding job of a linked job by its full name. This attribute can be omitted.

The following shows an example of retrieving information with the __createLink method.

{
  "meta":{
      "format":"conf"
      "componentName":"/HITACHI/JP1/AJS3/CONFINFO"
      "timestamp":"2018-11-11T00:00:00Z"
  },
  "links":[
      {
          "from":"JP1AJS-M_AJSM1/_HOST_AJShost1/_JP1SCHE_S1/_JP1JOBG_JG1/_JP1ROOTJOBNET_root1",
          "to":"JP1AJS-M_AJSM2/_HOST_AJShost2/_JP1SCHE_S2/_JP1JOBG_JG2/_JP1ROOTJOBNET_root2",
          "type":"rootJobnetExecutionOrder",
          "value":
             {
                       "precedingJob":"root1/job1",
                       "succeedingJob":"root2/job2",
             }
      }, ...
  ],
}

The following table lists and describes the functions that are affected by the relation information set by addResult and its impact.

A method that adds dynamic grant information to the value parameter and returns an array of link information in the given JSON format.

If the plugin contains link information that cannot be processed, the link information will be returned as is.

The following table lists and describes the parameters of the __linkValueGet method.

"value":{
    "unit": [
        {
           "precedingJob":"job1",
           "succeedingJob":"job2"
           "impact":true
        }
    ]
 }

The following describes the format of link information returned by the __linkValueGet method.

Formats

{
   "links": [
      {
          "from": "the-preceding-node-SID",
          "to": "the-succeeding-node-SID",
          "type": "type-of-the-target",
          "value": structured-identifier
       },  ...
  ]
}

Describe

The following table lists and describes the items of retrieved link information.

Table 4‒27: Items of the retrieved link information

No.	Item	Data types	Description
1	links	array	An array of link information
2	from	string	SID of the preceding node
3	to	string	SID of the succeeding node
4	type	string	Type of the target
5	value	Object	Specifies additional information of relation information between configurations.

The following shows an example of retrieving information with the __linkValueGet method.

{
   "links": [
      {
         "from":"_JP1AJS-M_HOST1/_HOST_HOST1/_JP1SCHE_schedulerserv/_JP1JOBG_jobgroup/_JP1ROOTJOBNET_jobnet1",
         "to":"_JP1AJS-M_HOST1/_HOST_HOST1/_JP1SCHE_schedulerserv/_JP1JOBG_jobgroup/_JP1ROOTJOBNET_jobnet2",
         "type":"rootJobnetExecutionOrder",
         "value":{
              "unit": [
                   {
                     "precedingJob":"job1",
                     "succeedingJob":"job2"
                     "succeedingJobStartTime":"2019-05-14T00:00:00Z",
                     "precedingJobURL":"http://10.220.196.82:22252/ajs/...",
                     "succeedingJobURL":"http://10.220.196.82:22252/ajs/...",
                     "impact":"error"
                   }   ...
               ],
               "msg":"KAJY04254-E The collecting information process could not be generated."
           }
      }, ...
  ]
}

The following table lists and describes the functions that are affected by the additional information (value) of a link set by setResult and its impact.

This method is called to collect the required related information when IM management node is loaded. Called from simt service when the managed node is updated with the following actions:

• When simtData loading is completed at service startup

• When simtData loading is completed when the jddupdatetree command is executed

Collected information can be provided to other methods, for example, by setting the information to a global variable. For example, if the __simtLoad method collects AJS manager host name and AJS Agent host and set it global variable, you can refer to it in other methods (__eventGet method).

• When related information retrieval is completed normally

  You can provide information about other methods, for example by setting the global variable.

• Failed to get related information

  Ensure that you call args.setError (error message) method.

The following table lists and describes the parameters of the __simtLoad method.

The method retrieves the list of metrics that can be displayed for time-series data and returns it in JSON format.

The following table lists and describes the parameters of the __metricListGet method.

The following shows the list of metrics returned by the __metricListGet method.

Formats

{
    "metrics":[
      {
         "name":"metric",
         "label":"metric-display-name",
         "category":"category-of-the-metric",
         "description":"description-of-the-metric",
         "default":default-setting
    }
  ...
]

Describe

The following table lists and describes the items of the retrieved list of metrics.

Table 4‒30: Items of the retrieved list of metrics

No.	Item	Data types	Description
1	metrics	array	An array of metric information. You can specify up to 100 elements. An empty array cannot be specified. This item cannot be omitted.
2	name	string	The name of the metric. It can be specified with half-width alphanumeric characters and the following symbols: - (hyphen), _ (underscore) It must be specified between 1 and 255 characters. An empty string cannot be specified. This item cannot be omitted.
3	label	string	The display name of the metric. It can be specified between 1 and 255 characters, excluding control characters. An empty string cannot be specified. This item can be omitted.
4	category	string	The category of the metric. It can be specified between 1 and 255 characters, excluding control characters. An empty string cannot be specified. This item can be omitted.
5	description	string	The description of the metric. It can be specified between 1 and 1023 characters, excluding control characters. An empty string cannot be specified. This item can be omitted. If a long string is specified in this item, when you use the Integrated Operation Viewer window of JP1/IM - Manager (Intelligent Integrated Management Base), a string displayed as a tooltip for the metric display name in the Trends tab might be truncated by WWW browser limitations (maximum number of characters that can be displayed as the title attribute).
6	default	boolean	Specifies whether the metric is a default metric. true: It is a default metric. false: It is not a default metric. You can specify up to 10 metrics as the default metrics. This item cannot be omitted.

The following shows an example of retrieving information with the __metricListGet method.

{
    "metrics":[
      {
        "name":"CPU-Usage",
        "label":"CPU-used-rate",
        "category":"CPU",
        "description":"Show the CPU usage on a core basis. (Units: %)",
        "default":true
      }
     ...
    ]
}

The following table lists and describes the function that is affected by the list of metrics set by setResult and its impact.

The method retrieves time-series data and returns it in JSON format.

If the number of time-series data sets retrieved and the number of instances exceed the limits specified by countPerInstance and instanceCount respectively, the applicable member of the exceedCountDetected object in the response is set to true and the data is selected so that the numbers of data sets are below the limits of countPerInstance and instanceCount, and then the data is returned.

The following table lists and describes the parameters of the __timeSeriesDataGet method.

The following shows the time-series data returned by the __timeSeriesDataGet method.

Formats

{
    "metric":"metric",
    "timeSeriesData":[
            {
               "instance":"instance-name"
               "unit":"unit",
               "data":[
               {"time":"time","value":value},
                   ...
            ]
          },
          ...
    ],
    "exceedCountDetected": {
        countPerInstance:whether-an-excess-of-the-upper-limit-for-the-number-of-data-sets-per-instance-is-detected,
        instanceCount: whether-an-excess-of-the-upper-limit-for-the-number-of-instances-is-detected
    }
}

Describe

The following table lists and describes the items of the retrieved time-series data.

Table 4‒33: Items of the retrieved time-series data

No.	Item	Data types	Description
1	timeSeriesData	array	An array of time-series data. An empty array cannot be specified. This item cannot be omitted.
2	metric	string	The name of the metric. It can be specified with half-width alphanumeric characters and the following symbols: - (hyphen), _ (underscore) It must be specified between 1 and 255 characters. An empty string cannot be specified. This item cannot be omitted.
3	instance	string	The name of the instance. It can be specified between 1 and 255 characters, excluding control characters. An empty string cannot be specified. This item can be omitted.
4	unit	string	The unit for the metric. It can be specified between 1 and 255 characters, excluding control characters. An empty string cannot be specified. This item cannot be omitted.
5	data	array	An array of two-dimensional data consisting of the time and value. If no time-series data exists in the specified period, specify an empty array. This item cannot be omitted.
6	time	string	The time of data. It is the UTC time in ISO8601 format. The number of seconds after the decimal point cannot be specified. If data is empty: This item can be omitted. If data is not empty: This item cannot be omitted. An empty string cannot be specified.
7	value	number	A value of data. It should be the same as the accuracy of number in JavaScript. If data is empty: This item can be omitted. If data is not empty: This item cannot be omitted.
8	exceedCountDetected	Object	The object to detect the upper limit. This item cannot be omitted.
9	countPerInstance	boolean	Whether an excess of the upper limit for the number of data sets per instance is detected. If the upper limit is exceeded: true Otherwise: false This item cannot be omitted.
10	instanceCount	boolean	Whether an excess of the upper limit for the number of instances is detected. If the upper limit is exceeded: true Otherwise: false This item cannot be omitted.

The following shows an example of retrieving information with the __timeSeriesDataGet method.

{
    "metric":"CPU Usage",
    "timeSeriesData":[
            {
              "instance":"CPU_1"
              "unit":"%",
              "data":[
                  {"time":"2019-05-22T00:00:00Z","value":14.04},
                                 ...
              ]
          },
            {
              "instance":"CPU_2"
              "unit":"%",
              "data":[
                {"time":"2019-05-22T00:00:00Z","value":09.24},
                                 ...
            ]
          },
       ...
    ],
    "exceedCountDetected": {
        "countPerInstance": true,
        "instanceCount": false
    }
 
}

If no data exists for the specified metric and in the specified period

{
    "metric":"CPU Usage",
    "timeSeriesData":[
            {
              "unit":"%",
              "data":[
              ]
          }
    ],
    "exceedCountDetected": {
        "countPerInstance": false,
        "instanceCount": false
    }
 
}

The following table lists and describes the function that is affected by the time-series data set by setResult and its impact.

The method retrieves the URL for starting a monitor associated with the specified SID and returns it in JSON format.

The following table lists and describes the parameters of the __urlGet method.

The following shows the URL for starting the monitor returned by the __urlGet method.

Formats

{
    urlList:[
       {
            "url":"URL-for-starting-the-monitor",
            "name":"name-of-the-URL"
       },
       ...
    ]
}

Describe

The following table lists and describes the items of the retrieved URL for starting the monitor.

Table 4‒36: The items of the retrieved URL for starting the monitor

No.	Item	Data types	Description
1	urlList	array	An array of URL information objects
2	url	string	The URL string
3	name	string	The name of the URL

The following shows an example of retrieving information with the __urlGet method.

{
    urlList:[
       {
            "url":"http://10.220.196.82:22252/ajs/login.html?manager=10.220.196.82&type=monitor...",
            "name":"monitor-startup-window-for-rootJobNet1"
       }
    ]
}

The following table lists and describes the function that is affected by the URL information for starting the monitor set by setResult and its impact.