All actions taken by the web service are logged in the following log files:

<OMi_HOME>/log/jboss/opr-webapp.log

<OMi_HOME>/log/jboss/opr-configserver.log

To enable debugging:

<OMi_HOME>/conf/core/Tools/log4j/jboss/opr-webapp.properties

In the opr-webapp.properties file, set the loglevel to the desired value. The debug loglevel (loglevel=DEBUG, cs_loglevel=DEBUG) is useful for finding problems.

Objects returned in the response include several references that you can use in subsequent requests involving the referenced object.

id and <target_id>

The XML tags id and <target_id> represent the object ID and the ID of a referenced object, respectively.

self and <target_href>

The XML tags self and <target_href> represent the object URL and the URL of a referenced object, respectively.

type and <target_type>

The XML tags type and <target_type> represent a reference for the object and a reference for a referenced object, respectively.

<link>

The XML tag <link> specifies additional navigation possibilities such as requesting verbose output, requesting a list of deployment jobs for the assignment being created, and so on.

<management_template_version_ref version="9.20" 
    type="urn:x-hp:2009:software:data_model:opr:type:reference:
        management_template_version"> 
   
    <target_id>d6f9cf24-244a-bce7-1e37-c5446c81e773</target_id>
    <target_type>urn:x-hp:2009:software:data_model:opr:type:
        management_template_version</target_type>
    <target_href>
        https://server.example.com/opr-config-server/rest/ws/9.20/
        management_template_version_list/d6f9cf24-244a-bce7-1e37-c5446c81e773
    </target_href> 

    <display_label>MTCIAttResolution</display_label> 
    <major_version>1</major_version> 
    <minor_version>0</minor_version>
   
</management_template_version_ref>

You can manage automatic assignments by using the Monitoring Automation Web Service Interface. The following examples show the XML structure for different requests:

GET - https://<server>:<port>/opr-config-server/rest/ws/10.12/auto_assignment_list

<auto_assignment_list>
    <management_template_version_auto_assignment>
        <id>
        <auto_assigned_view>
            <name>
        <is_enabled>
        <link>
        <management_template_version_ref>
            <target_id>
            <target_type>
            <target_href>
    <management_template_version_auto_assignment>
        <id>
        <auto_assigned_view>
            <name>
        <is_enabled>
        <link>
        <management_template_version_ref>
            <target_id>
            <target_type>
            <target_href>
    <aspect_template_version_auto_assignment>
        <id>
        <auto_assigned_view>
            <name>
        <is_enabled>
        <link>
        <management_template_version_ref>
            <target_id>
            <target_type>
            <target_href>

GET - https://<server>:<port>/opr-config-server/rest/ws/10.12/auto_assignment_list/draft/view/<viewName>/management_template_version/<mtvId>

<management_template_version_auto_assignment>
    <auto_assigned_view>
        <name>
    <is_enabled>
    <parameter_value_list>
        <parameter_value>
            <parameter_context>
                <topo_path>
                <aspect_version_id>
            <parameter>
                <id>
                <display_label>
                <type>
                <base_parameter_id>
                <parameter_value_instance_list>
                    <parameter_value_instance>
                        <order>
                        <value>
                        <is_default>
                    <dependent_parameter_value_list>
                        <parameter_value>
                            <value>
                            <is_default>
                            <parameter_context>
                                <topo_path>
                                <aspect_version_id>
                            <parameter>
                                <id>
                                <display_label>
                                <type>
                                <base_parameter_id>
                        <parameter_value>
                            <value>
                            <is_default>
                            <parameter_context>
                                <topo_path>
                                <aspect_version_id>
                            <parameter>
                                <id>
                                <display_label>
                                <type>
                                <base_parameter_id>
    <link>
    <management_template_version_ref>
        <target_id>
        <target_type>
        <target_href>

Post https://<server>:<port>/opr-config-server/rest/ws/10.12/auto_assignment_list

<management_template_version_auto_assignment>
    <auto_assigned_view>
        <name>
    <is_enabled>
    <parameter_value_list>
        <parameter_value>
            <parameter_context>
                <topo_path>
                <aspect_version_id>
            <parameter>
                <id>
                <display_label>
                <type>
                <base_parameter_id>
                <parameter_value_instance_list>
                    <parameter_value_instance>
                        <order>
                        <value>
                        <is_default>
                    <dependent_parameter_value_list>
                        <parameter_value>
                            <value>
                            <is_default>
                            <parameter_context>
                                <topo_path>
                                <aspect_version_id>
                            <parameter>
                                <id>
                                <display_label>
                                <type>
                                <base_parameter_id>
                        <parameter_value>
                            <value>
                            <is_default>
                            <parameter_context>
                                <topo_path>
                                <aspect_version_id>
                            <parameter>
                                <id>
                                <display_label>
                                <type>
                                <base_parameter_id>
    <link>
    <management_template_version_ref>
        <target_id>
        <target_type>
        <target_href>

<management_template_version_auto_assignment>
    <auto_assigned_view>
        <name>
    <is_enabled>
    <parameter_value_list>
        <parameter_value>
            <parameter_context>
                <topo_path>
                <aspect_version_id>
            <parameter>
                <id>
                <display_label>
                <type>
                <base_parameter_id>
                <parameter_value_instance_list>
                    <parameter_value_instance>
                        <order>
                        <value>
                        <is_default>
                    <dependent_parameter_value_list>
                        <parameter_value>
                            <value>
                            <is_default>
                            <parameter_context>
                                <topo_path>
                                <aspect_version_id>
                            <parameter>
                                <id>
                                <display_label>
                                <type>
                                <base_parameter_id>
                        <parameter_value>
                            <value>
                            <is_default>
                            <parameter_context>
                                <topo_path>
                                <aspect_version_id>
                            <parameter>
                                <id>
                                <display_label>
                                <type>
                                <base_parameter_id>
    <link>
    <management_template_version_ref>
        <target_id>
        <target_type>
        <target_href> 

This section explains what parameters are, and how to set them when assigning management templates, aspects, or policy templates to CIs.

Considerations

When executing web service requests, the following should be taken into consideration with regard to Monitoring Automation (MA) parameters:

• Parameter values can be of the type string, numeric, password, or enum.

• Certain XML tags are only visible in verbose mode. Examples of these are the following tags:

  • Possible enumeration values of enum parameters.

  • Minimum and maximum values of numeric parameters.

  • Expert flag.

• The web service returns parameters only in response to web service requests dealing with assignments. To get a list of parameters contained in a management template, aspect, or policy template, request a draft assignment for the artifact.

• The response to a GET /assignment_list/draft/ci/<CIID>/management_template_version/<MTVersionID> request contains only parameters that are relevant to the CI with ID <CIID>; parameters that are contained in the management template with version ID <MTVersionID> that do not apply to this CI are omitted.

• The response to a GET /auto_assignment_list?filterFor=notLatest request provides a list of all automatic assignment rules that do not contain the latest version of the associated management template or aspect.

• When creating an assignment, parameter specifications require the parameter's ID and its context. HPE recommends copying the context from the response to GET assignment_list/<assignmentID> or GET assignment_list/draft/… request, rather than trying to construct the context programmatically.

• The context of a parameter in a management template specifies the configuration object the parameter is defined in (the context of parameters in aspects and policy templates has no special meaning). Typically the context consists of the topology path, which describes how the aspects contained in a management template link sub-CIs to CIs, and the version ID of the aspect containing the parameter, as defined in the management template being assigned.
• In verbose mode, the context provided in a draft response includes the label and description of the aspect containing the parameter to assist users in resolving the parameter reference.

• If you omit a parameter from an assignment creation request, its default value is used.

• HPE recommends setting as few parameters as possible when creating assignments. The number of parameters to be set during assignment can be minimized by creating good default values for the parameters. For more information about management template, aspect, or policy template parametrization, see Management Templates and Aspects.

• When creating an assignment using the web service, the CI to which the assignment is to be made must be known. Therefore, any conditions affecting parameter values are resolved and no longer conditional in the responses provided by the web service. As an example, consider a parameter value with a conditional value of 10 for Windows and 20 for Unix. When retrieving assignment information from the web service, the value is resolved and specified as 10 in a response for a CI on Windows, and as 20 for a CI on Linux.

• In contrast to parameter values changed by using the tuning functionality in the MA user interface, parameter values set using the web service can be overwritten by assignments created from automatic assignment rules. For this reason, HPE recommends not using the assignment web service in conjunction with active auto-assignment rules.

• When upgrading an assignment to a different management template, aspect, or policy template version, all parameter values set by the web service assignments are overwritten by the values as specified in the new management template, aspect, or policy template version, unless you specify the useExisting=true URL parameter when calling one of the draft-assignment generation calls. Specifying the useExisting=true URL parameter causes the parameter values from an existing assignment to be reused for a new assignment, when neither the parameter type not the value range changed between versions.

• In OMi versions 10.11 and higher, the parameter XML is also provided with the base_parameter_id XML tag. If the base_parameter_id is identical for a parameter in two management template, aspect, or policy template versions, then the existing parameter values are used. Existing parameter values cannot be reused, for example, when the parameter type changed from string to password, or when an enum type parameter with the choices yes and no is expanded to include the maybe option in a new version. Additionally, when a parameter is removed in a new policy version, the existing parameter values cannot be reused, even if a parameter with the same name was added in the new version.

• There are two types of parameters, simple and multi-instance parameters, where the latter have an XML tag <is_instance_parameter> set to true. Simple parameters have a value, whereas instance parameters have an instance list. Each instance in the list consists of an instance value and a list of dependent parameters.

  Example: Consider a multi-instance parameter fileSystem with the dependent parameters usageThreshold (in %) and messageSeverity (a number of severity indicators such as warning or critical). fileSystem is used to monitor two instances: C: and D:. For C: the threshold for creating a message with severity critical is 90%, while for D: the threshold for severity warning is 95%.

  Note the following when using multi-instance parameters in web service requests:

  • Unless multiple instance definitions are specified, a multi-instance parameter is created for only one instance.

  • When specifying multiple instances in the definition of a multi-instance parameter, you can give each instance a sequence number to ensure policy template conditions are processed in the correct order.

  • Dependent parameters can be overwritten by another instance associated with the multi-instance parameter they depend on if that instance has a higher priority, as defined by the value of XML tag <ui_order>. Typically, the instance with the highest priority has a ui_order value of 0.

• A response to a web service request for information related to an existing assignment can contain the following flags:

  • is_default: Set to the value false if the parameter was overwritten.

  • is_tuned: Specified if the parameter value was changed using the Monitoring Automation tuning user interface.

  • mandatory: Specified if the management template, aspect, or policy template defines the parameter as mandatory.
  • readonly: Specified if the management template, aspect, or policy template defines the parameter as read-only.
  • expert: Specified if the management template, aspect, or policy template defines the parameter as an expert parameter.

• Parameter defaults can be specified as a literal using the attribute value, or symbolically using the attribute model_property with the value set to the name of the CI attribute to provide the value.

  • When symbolic notation is used the parameter default value is calculated from the CI or sub-CI the assignment refers to.

  • Literals take precedence over calculated values.

  • HPE recommends never changingmodel_property, in order to avoid ambiguities with regard to the property's CI type and resolvability.

• The following parameter attributes can be modified:

  • value

  • model_property

  • Creation of additional instances for a multi-instance parameter.

  All other parameter attributes are for information only.

• The values of mandatory parameters must be provided when requesting assignment creation.

• Input validation is done at assignment creation time. If the validation fails (for example, if a mandatory parameter is not specified) the web service returns a descriptive error.

The encoding used for XML requests and responses does not depend on the type of request. This enables a response to be reused for a POST request creating an assignment.

The XML encoding used for assignment-related HTTP requests and responses uses the same format. This enables a GET response to be reused for a POST request when creating an assignment, as follows:

1. Execute a GET request for the assignment to be created:

   • To create an assignment differing from an existing assignment only in the value of a few parameters, it is useful to start with an /assignment_list/<assignmentID> request, resulting in a response containing all parameter values for the assignment with ID <assignmentID>.

   • To start an assignment from scratch, use the GET /assignment_list/draft/ci/<CIID>/management_template_version/<MTVersionID> request, which results in a response representing a draft of the input needed for the assignment creation request (the same procedure can be applied to aspects and policy templates). The draft contains all parameters contained in management template <CIID> to be assigned, initialized to their default values. Alternatively, you can use the URL parameter useExisting=true in the draft-call to use parameters from an existing assignment to the same CI and configuration artifact.

2. Modify the response by overwriting the parameter values to be changed in the assignment to be created.

3. Post the modified response as a POST /assignment_list request to create the new assignment.

Using this method makes your automation algorithm independent of those XML elements not involved in the modification, which greatly increases the robustness of your code compared to manually creating the input.

To verify that the assignment was created, execute a GET request for the new assignment or the deployment jobs it should have created, or inspect the assignment using the OMi MA user interface.

XML schema

The following file contains the XML schema used for encoding object information:

<OMi_HOME>/opr/api/schema/OprDataModel.xsd

JAXB annotated classes

The following file contains the JAXB annotated classes:

<OMi_HOME>/lib/opr-external-api.jar

If you are programming in Java, you can use these classes directly instead of generating classes from the schema. See the Javadoc API Documentation for details about the classes provided.

See also the example source code for a java web service client in the following files:

• <OMi_Home>/opr/examples/assignment-ws-client
• <OMi_Home>/opr/examples/mgmt-templates-ws-client

The level of detail in the input and output data for a web service request can be determined by specifying verbose or minimal mode:

• In minimal mode, input and output data contain a minimal set of XML tags needed to define an object. The minimal set is a true subset of the set of XML tags used in verbose mode.
• Default is minimal mode.
• To use verbose mode, add the suffix ?view=verbose to the URL when calling the web service.
• When using minimal mode, the XML response contains the XML tag <link rel="verbose">, the value of which is a URL that provides the verbose version of the response file when called.