XClarity Administrator - POST /compliancePolicies

Authentication

Authentication with user name and password is required.

Request URL

POST https://{management_server_IP}/compliancePolicies

Query parameters

Parameters	Required / Optional	Description
action=`{action}`	Required	Action type. This can be one of the following values. create. Add a compliance policy. copy. Copy a compliance policy. import. Upload a compliance policy from the local system.

The following example creates a compliance policy.

POST https://192.0.2.0/compliancePolicies?action=create

Request body

Table 1. Create a compliance policy.
Attributes				Required / Optional	Type	Description
policy				Required	Object	Information about the compliance policy
	action			Required	String	Action to take. This is always create.
	description			Optional	String	Compliance policy description
	details			Required	Array of objects	Details about the compliance policy
		baseVersion		Required	String	For CMMs or switches, this is the fix ID of the package. For servers, the following is returned. `xxxx_utl_uxsp_xxxxxx-1.00_xxxx_32-64`
		components		Required	Array of objects	Information about each firmware component
			isDefault	Required	String	Specifies if the component update is the default component (the latest component update). This can be one of the following values. yes. This firmware component is the default. no. This firmware component not is the default.
			name	Required	String	Component name
			rule	Required	String	Rule for raising a non-compliant alert. This can be one of the following values. alertIfNotExactMatch. Show non-compliance when the installed version on device does not exactly match the compliance target. alertIfDownlevel. Show non-compliance when the installed version on device is earlier than the compliance target. noAlerting. Never show non-compliance.
			targetVersion	Required	String	Firmware level that is the baseline for the specified device type
			type	Required	String	(Servers only) Package type. This can be one of the following values. IMM IMM UEFI UEFI-Backup
		id		Required	String	System type used to identify the CMM. Internal use only
		isDefault		Required	String	Indicates whether the update package is the default package (the latest package). This can be one of the following values. yes. This is the default update package. no. This is not the default update package.
		isDoNotUpdate		Required	String	Indicates whether the policy is set to do not update. +++This can be one of the following values. yes. The policy is set to Do not update. no. The policy is not set to Do not update.
		isUXSP		Required	String	Indicates whether this update package is a UXSP package. This can be one of the following values. yes. This is a UXSP package. no. This is not a UXSP package.
		rule		Required	String	Rule for raising a non-compliant alert. This can be one of the following values. alertIfNotExactMatch. Show non-compliance when the installed version on device does not exactly match the compliance target. alertIfDownlevel. Show non-compliance when the installed version on device is earlier than the compliance target. noAlerting. Never show non-compliance. custom. Follow the detailed rules of each firmware component.
		systemType		Required	String	Type of device for which the policy applies
	filterType			Required	String	Filter type. This can be one of the following values. all. All supported machine types managed. Only managed machine types.
	name			Required	String	Compliance policy name
	oldPolicyName			Required	String	Specify an empty value when creating a compliance policy
	updateRule			Required	String	Internal use only
	user			Required	String	Name of the user that requested to create the policy

The following example creates a new compliance policy when the query parameter action=create is specified.

{
   "policy": {
      "action": "create",
      "description": "",
      "details": [{
         "baseVersion": "xxxx_utl_uxsp_xxxxxx-1.00_xxxx_32-64",
         "components": [{
            "name": "Integrated Management Module 2 (IMM2) Update (Standby)",
            "rule": "alertIfDownlevel",
            "type": "IMM-Backup",
            "targetVersion": "DoNotUpdate_ibm_fw_imm2_1aoo81a-6.60_anyos_noarch",
            "isDefault": "yes"
         }],
         "id": "8737",
         "isDefault": "no",
         "isDoNotUpdate": "yes",
         "isUXSP": "no",
         "rule": "custom",
         "systemType": "8737",
      }],
      "filterType": "managed",
      "name": "4234234234",
      "oldPolicyName": ""
      "updateRule": "",
      "user": "USERID"
   }
}

Table 2. Copy a compliance policy
Attributes	Required / Optional	Type	Description
oldPolicyName	Required	String	Name of policy to be copied
prefix	Required	String	Prefix of copied policy name
user	Required	String	Name of the user that requested to copy the policy

The following example copies an existing policy when the query parameter action=copy is specified.

{
   "oldPolicyName": "test",
   "user": "USERID",
   "prefix": "Copy"
}

Response codes

Code	Description	Comments
200	OK	The request completed successfully.
307	Temporary Redirect	The URL changed for this REST API. The response header returns the correct URL in the Location attribute. The URL changed for this REST API when action=import is specified.
400	Bad Request	A query parameter or request attribute is missing or not valid, or the operation is not supported. A descriptive error message is returned in the response body.
403	Forbidden	The orchestrator server was prevented from fulfilling the request. A descriptive error message is returned in the response body. Ensure that you have privileges to perform the request.
409	Conflict	There is a conflict with the current state of the resource. A descriptive error message is returned in the response body.
500	Internal Server Error	An internal error occurred. A descriptive error message is returned in the response body.

Response body

Table 3. Create a compliance policy.
Attributes				Type	Description
`{message_attributes}`				`varies`	Status messages (see Status messages) The result attribute can be one of the following values. informational. The request completed successfully. minor. The request failed with a minor issue. major. The request failed with a major issue.

The following example is returned if the request is successful.

{
    "result": "informational",
    "messages": [
        {
            "id": "FQXHMUP3006I",
            "text": "Policy operation completed successfully."
        }
    ]
}

Table 4. Copy a compliance policy.
When the request is successful, the following attributes are returned in the response body. If the request fails, standard message attributes are returned (see Status messages), where the result attribute can be one of the following values: **informational**, **minor**, or **major**.
Attributes	Type	Description
description	String	Compliance policy description
filterType	String	Filter type. This can be one of the following values. all. All supported machine types managed. Only managed machine types.
id	String	Compliance policy ID
inUse	String	Identifies whether the compliance policy is in use. This can be one of the following values. true. The compliance policy is in use. false. The compliance policy is not in use.
lastAction	String	Last action that was performed on the compliance policy. This can be one of the following values. Predefined. The compliance policy is predefined. Created by `{user_name}`. The user-defined compliance policy was created by the specified user. Edited by `{user_name}`. The user-defined compliance policy was edited by the specified user.
lastModified	String	Timestamp of the last change to the compliance policy
lastEdited	String	Timestamp of the last change to the compliance policy
name	String	Compliance policy name
updateRule	String	Internal use only
userDefined	String	Identifies whether the compliance policy is user-defined. This can be one of the following values. yes. The compliance policy is user-defined. no. The compliance policy is predefined.

The following example is returned if the request is successful.

{
    "description": "",
    "filterType": "all",
    "id": "1624433666597",
    "inUse": false,
    "lastAction": "Created by USERID",
    "lastEdited": "2021-06-23T07:34:26Z",
    "lastModified": "This policy was created by USERID on 2021-06-23T07:34:26Z",
    "name": "Copy1-test",
    "updateRule": "",
    "userDefined": "yes"
}

Table 5. Import a compliance policy.
Attributes				Type	Description
errorMsg				Object	Information about firmware-compliance policy files that are not valid
	result			String	Results of the request. This can be one of the following values. success. The request completed successfully. failed. The request failed. A descriptive error message was returned.
	messages			Array of objects	Information about one or more messages
		id		String	Message identifier of a returned message
		text		String	Message text associated with the message identifier
		explanation		String	Additional information to clarify the reason for the message
		recovery		Array of objects	Recovery information
			text	String	User actions that can be taken to recover from the event
popMsg				Object	Information about firmware-compliance policy files that exist on the management server
	result			String	Results of the request. This can be one of the following values. success. The request completed successfully. failed. The request failed. A descriptive error message was returned.
	messages			Array of objects	Information about one or more messages
		id		String	Message identifier of a returned message
		text		String	Message text associated with the message identifier
		explanation		String	Additional information to clarify the reason for the message
		recovery		Array of objects	Recovery information
			text	String	User actions that can be taken to recover from the event
successMsg				Object	Information about firmware-compliance policy files that were imported successfully
	result			String	Results of the request. This can be one of the following values. success. The request completed successfully. failed. The request failed. A descriptive error message was returned.
	messages			Array of objects	Information about one or more messages
		id		String	Message identifier of a returned message
		text		String	Message text associated with the message identifier
		explanation		String	Additional information to clarify the reason for the message
		recovery		Array of objects	Recovery information
			text	String	User actions that can be taken to recover from the event

The following example is returned if the request is successful.

{
   "errorMsg": {
      "result": "major",
      "messages": [{
         "id": "FQXHMUP3033L",
         "text": "Some files failed to import and are discarded.",
         "explanation": "The following files are invalid and have been discarded: TestB.xml.",
         "recovery": {
            "text": "Please check the contents of files. Ensure that the uploaded files include
                     the correct .xml file."
         }
      }]
   },
   "popMsg": {
      "result": "warning",
      "messages": [{
         "id": "FQXHMUP3032F",
         "text": "Some files failed to import and are discarded.",
         "explanation": "The following policy files already exist on system and have been 
                         discarded: DEFAULT-2015-04-25.xml.",
         "recovery": {
            "text": "Rename or delete the existing compliance policy in the Compliance Policy
                     page, and retry the import."
         }
      }]
   },
   "successMsg": {
      "result": "informational",
      "messages": [{
         "id": "FQXHMUP3030I",
         "text": "Policy import completed successfully."
      }]
   }
}