Summary of changes in the REST API for v2.0.0

This documentation includes new methods and parameters that apply to the current XClarity Administrator release and later. If you are using an earlier release of XClarity Administrator, you can use the REST API Reference PDF for a list of methods and parameters that apply to that specific release. To find PDFs for the release that you need, see PDF files.

The following methods were added or updated in this release.

• Discovery and management resources

  • (New) GET /ipDuplication. Checks whether the specified IP addresses are duplicate in the network.

  • (New) GET /ipSettings. Retrieves information about whether XClarity Administrator checks for duplicate IP addresses in the same subnet.

  • (New) PUT /ipSettings. Enables or disables checking for duplicate IP addresses in the same subnet.

  • GET /manageRequest/jobs/<job_id>. Added the summary response parameter to specify information about the job summary.
  • GET /unmanageRequest/jobs/<job_id>. Added the summaryresponse parameter to specify information about the job summary.
  • POST /manageRequest. Added the management-processor-type request parameter to specify the type of management controller in a chassis or server.

• Inventory

  • GET /canisters and GET /canisters/<UUID>. Added the userDefineName response parameter to retrieve the name of the device that was defined by the user.

  • GET /chassis and GET /chassis/<UUID_list>. Added the publicAccess response parameter to indicate whether the device can be accessed by all role groups. Added the roleGroups response parameter to retrieve the list of role groups that are permitted to view and manage this device. Added the userDefineName response parameter to retrieve the name of the device that was defined by the user.

    Deprecated the activeAlerts response parameters. Use GET /events/activeAlerts/<UUID> instead.

  • PUT /chassis/<UUID>. Added the publicAccess request parameter to indicate whether the device can be accessed by all role groups. Added the roleGroups request parameter to specify the list of role groups that are permitted to view and manage this device.
  • GET /cmms andGET /cmms/<UUID_list>. Added the userDefineName response parameter to retrieve the name of the device that was defined by the user.
  • GET /nodes. Added the publicAccess response parameter to indicate whether the device can be accessed by all role groups. Added the roleGroups response parameter to retrieve the list of role groups that are permitted to view and manage this device. Added the userDefineName response parameter to retrieve the name of the device that was defined by the user.
  • GET /nodes/<UUID_list>. Added support for specifying a Flex System storage controller (canister) UUID in the URL. Added the publicAccess response parameter to indicate whether the device can be accessed by all role groups. Added the roleGroups response parameter to retrieve the list of role groups that are permitted to view and manage this device. Added the userDefineName response parameter to retrieve the name of the device that was defined by the user.
  • PUT /nodes/<UUID>. Added the publicAccess request parameter to indicate whether the device can be accessed by all role groups. Added the roleGroups request parameter to specify the list of role groups that are permitted to view and manage this device.
  • GET /storage and GET /storage/<UUID_list>. Added the securityDescriptor response parameter to retrieve information about authentication enablement, support for managed authentication, public-access setting, the list of role groups that are permitted to view and manage this device, and stored credentials. Added the userDefineName response parameter to retrieve the name of the device that was defined by the user.
  • PUT /storage/<UUID>. Added the securityDescriptor response parameter to retrieve information about authentication enablement, support for managed authentication, public-access setting, the list of role groups that are permitted to view and manage this device, and stored credentials..
  • GET /switches and GET /switches/<UUID_list>. Added the securityDescriptor response parameter to retrieve information about authentication enablement, support for managed authentication, public-access setting, the list of role groups that are permitted to view and manage this device, and stored credentials.. Added the userDefineName response parameter to retrieve the name of the device that was defined by the user.
  • PUT /switches/<UUID>. Added the securityDescriptor response parameter to retrieve information about authentication enablement, support for managed authentication, public-access setting, the list of role groups that are permitted to view and manage this device, and stored credentials..

• Resource-group resources

  • (New) GET /resourceGroups. Retrieves information about all resource groups.
  • (New) POST /resourceGroups. Creates and populates a resource group.
  • (New) GET /resourceGroups/<UUID>. Retrieve information about a specific resource group.
  • (New) PUT /resourceGroups and PUT /resourceGroups/<UUID>. Modify resource-group properties, adds devices to a specific static group, or changes the criteria of a dynamic resource group.
  • (New) PATCH /resourceGroups/<UUID>. Adds or removes devices from a static resource group.
  • (New) DELETE /resourceGroups/<UUID>. Deletes a resource group.
  • (New) GET /resourceGroups/criteriaProperties. Retrieves inventory properties that you can use to specify criteria for dynamic resource groups.

• Configuration Pattern resources

  • PUT /cryptoSettings. Added the applyToManagedDevices request parameter to indicate whether to apply the specified settings to all managed devices. Added the applyToMgmtServer requrest parameter to indicate whether to apply the specified settings to the XClarity Administrator management server.
  • GET /patterns/<id>/includeSettings. Added the raidVolumeName response parameter to specify RAID volume name.
  • GET /profiles and GET /profiles/<id>. Added the complianceStatus response parameter to return whether the server settings are in compliance with the server profile.

• Operating-system deployment resources

  • PUT /hostPlatforms. Added the customConfigValue request parameter to specify custom configuration settings, in JSON format. Added the "Success," "Warning," and "Error" deployment status values for the deployStatus response parameter. Added the unattendFileId request parameter to specify the ID of the unattend file to be used in the OS deployment.
  • (New) GET /hostPlatforms/<UUID>. Retrieves OS deployment status.
  • (New) PUT /hostPlatforms/<UUID>. Modifies OS deployment status.
  • GET /osdeployment/globalSettings. Added the ipDuplicationCheckEnabled response parameter to return information about whether the duplicate-IP check runs at the beginning of an OS deployment. Added the ipDuplicationCheckEnabled response parameter to return information about the amount of time, in seconds, to wait between status updates before failing the OS deployment.
  • PUT /osdeployment/globalSettings. Added the ipDuplicationCheckEnabled request parameter to set whether the duplicate-IP check runs at the beginning of an OS deployment. Added the ipDuplicationCheckEnabled request parameter to set the amount of time, in seconds, to wait between status updates before failing the OS deployment.
  • GET /osImages.

    • Added the imageType=OSPROFILE and id query parameters to return only information for a specified OS-image profile.

    • Added the configFileDiskUsage, scriptFileDiskUsage, softwareFileDiskUsage, and unattendFileDiskUsage response parameters to return information about disk space that is used by the custom files.

    • Added the customConfigFiles response parameter to return information about configuration-settings files that are imported and available to the OS image profiles, including a list of custom macros that are defined for the custom configuration settings file.

    • Added the customSoftware response parameter to return information about software payloads that are imported and available to the OS image profiles.

    • Added the installScriptFiles response parameter to return information about installation-script-files are imported and available to the OS image profiles.

    • Added the osBuildId response parameter to return the build number of the operating-system image.

    • Added the customConfigOptions, customSoftwareOptions, installScriptOptions, and unattendOptions response parameters to return a list of IDs for each custom file file that is associated with the OS-image profile.

    • Added the predefinedMacros response parameter to return a list of predefined macros that are associated with this customized OS-image profile.

    • Added the allowCustomConfigSchema, allowCustomInstallScriptFile, allowCustomSoftware, and allowCustomUnattendFile response parameter to indicate whether the specified image supports specific custom files.

    • Added the type response parameter to return information about the OS image type.

    • Added the unattendFiles response parameter to return information about unattend files are imported and available to the OS image profiles. Added new request body parameters to specify content and metadata to import unattend or configuration-settings files without creating a job.

  • POST /osImages. Added CONFIG, SCRIPT, SOFTWARE, and UNATTEND as a new values for the imageType query parameter. Added the importByContent query parameter to indicate the import method to use when imageType is UNATTEND or CONFIG.
  • POST /osImages?jobId=<job_id>. Added CONFIG, SCRIPT, SOFTWARE, and UNATTEND as a new values for the imageType query parameter.
  • GET /osImages/<id>. The tar.gz file that is returned by this method includes custom files (such as configuration-settings, installation scripts, software, and unattend files.
  • PUT /osImages/<id>. Added the imageType query parameter to specify the type of file to modify. Added a new set of request parameters to modify custom files (such as configuration settings, installation scripts, software, and unattend files). Added the customConfigOptions, customSoftwareOptions, installScriptOptions, and unattendOptions request parameters to specify the IDs of custom files (such as configuration settings, installation scripts, software, and unattend files) to associate with this custom OS-image profile.
  • POST /osImages/<id>. Added the customConfigOptions, customSoftwareOptions, installScriptOptions, and unattendOptions request parameters to specify the IDs of custom files (such as configuration settings, installation scripts, software, and unattend files) to associate with this custom OS-image profile.
  • DELETE /osImages/<images_list>. Supports deleting custom files (such as configuration settings, installation scripts, software, and unattend files) in the OS-images repository.
  • (New) POST /osImages/customSettings Validates a custom configuration settings (in JSON format), and if successful, returns a list of custom macros that are derived from the configuration settings.

• Monitoring and event resources

  • GET /events. Added the translations query parameter to return translated events based on the criteria that is specified using encoded JSON format. Added the escapeHTML query parameter to return special characters (for example, &quot;) in place of escape characters in the message. Added the descriptionArgs response parameter to return a list of dynamic arguments in the event message description. Added the userActionArgs response parameter to return a list of dynamic arguments in the event message action. Added the groupName and groupUUID response parameters to identify which resource groups the source of the event belongs.
  • (New) GET /events?translations=<JSON_filter>. Returns events based on the criteria that is specified using encoded JSON format.
  • GET /events/activeAlerts.

    • Added the escapeHTML query parameter to return special characters (for example, &quot;) in place of escape characters in the message.

    • Added the outputFormat query parameter to return Information about all active alerts (by default) or the number of active alerts per resource group.

    • Added the groupUID query parameter to specify the resource groups for which you want alert counts. Added the uids query parameter to return task information only for one or more specific groups and devices.

    • Added the args response parameter to return a list of dynamic arguments in the event message string.

    • Added the componentIdentifierText response parameter to return the component description.

    • Added the failFRUs response parameter to return a list of FRU numbers for FRUs associated to the fault.

    • Added the failSNs response parameter to return a list of FRUs associated to the fault

    • Added the groupName and groupUUID response parameters to identify which resource groups the source of the alert belongs.

    • Added the <group_UUID> response parameter to return the alert counts per resource group.

    • Added the severityText response parameter to return the severity text.

    • Added the following additional response parameters: bayText, chassisText, eventSourceText, failFRUNames, failFRUPartNumbers, failFRUUUIDs, fruSerialNumberText, isManagement, msgID, serviceabilityText, systemFruNumberText, systemSerialNumberText, systemText, systemTypeModelText, systemTypeText, and typeText.

  • GET /events/activeAlerts/<UUID>.

    • Added the escapeHTML query parameter to return special characters (for example, &quot;) in place of escape characters in the message.

    • Added the uids query parameter to return task information only for one or more specific groups and devices.

    • Added the componentIdentifierText response parameter to return a list of dynamic arguments in the event message string.

    • Added the componentIdentifierText response parameter to return the component description.

    • Added the failFRUs response parameter to return a list of FRU numbers for FRUs associated to the fault.

    • Added the failSNs response parameter to return a list of FRUs associated to the fault

    • Added the groupName and groupUUID response parameters to identify which resource groups the source of the alert belongs.

    • Added the severityText response parameter to return the severity text.

    • Added the following additional response parameters: bayText, chassisText, eventSourceText, failFRUNames, failFRUPartNumbers, failFRUUUIDs, fruSerialNumberText, isManagement, msgID, serviceabilityText, systemFruNumberText, systemSerialNumberText, systemText, systemTypeModelText, systemTypeText, and typeText.

  • (New) GET /events/activeAlerts/helptext/<alert_id>. Retrieves the description and recovery action for a specific alert.
  • GET /events/audit. Added the escapeHTML query parameter to return special characters (for example, &quot;) in place of escape characters in the message. Added the componentIdentifierText response parameter to return the component description.
  • GET /events/helptext/<event_id>. Added information about the JSON-formatted message description and user action. HTML format is not allowed. Added information about the response body, including the description and useraction parameters.
  • GET /events/monitors.

    • Added the format query parameter to specify what type of information is returned. Added the id query parameter to specify the remote event recipient ID when the content of the recipient is to be returned.

    • Added response parameters to specify the information about new OMS and REST recipients.

    • For email recipients:

      • Added the authenticationEmail response parameter to specify the authentication type for email (SMTP) server recipients.

      • Added the connectionEmail response parameter to specify the Connection type to secure connection to the email (SMTP) server recipients.

      • Added the enable response parameter to specify whether the recipient is enabled.

      • Added categories, severity and type response parameters to specify the event filter information.

      • Added the id response parameter to specify the recipient ID.

      • Added the ignoreExcluded response parameter to specify whether to disable the forwarding of excluded events.

      • Added the outputFormat response parameter to specify the output format for the forwarded event.

      • Added the requestTimeout response parameter to specify the amount of time, in seconds, that a remote event recipient has to forward events before the request times out.

      • Added the scheduler response parameter to specify the times and days when you want the specified events to be forwarded.

      • Added the senderDomain response parameter to specify the sender domain for email (SMTP) server recipients.

      • Added the senderUserName response parameter to specify the sender name for email (SMTP) server recipients.

    • For SNMP recipients

      • Added the authPasswordSet response parameter to specify the the password string.

      • Added the enable response parameter to indicate whether the recipient is enabled.

      • Added catetories , severity and type response parameters to specify the event filter information.

      • Added the id response parameter to specify the recipient ID.

      • Added the ignoreExcluded response parameter to specify whether to disable the forwarding of excluded events.

      • Added the outputFormat response parameter to specify the output format for the forwarded event.

      • Added the privacyPasswordSet response parameter to return the privacy password.

      • Added the oms_log_analytics and rest values for protocol response parameter.

      • Added the requestTimeout response parameter to specify the amount of time, in seconds, that a remote event recipient has to forward events before the request times out.

      • Added the scheduler response parameter to specify the times and days when you want the specified events to be forwarded.

    • For syslog recipients

      • Added catetories, severity and type response parameters to specify the event filter information.

      • Added the id response parameter to specify the recipient ID.

      • Added the ignoreExcluded response parameter to specify whether to disable the forwarding of excluded events.

      • Added the outputFormat response parameter to specify the output format for the forwarded event.

      • Added the oms_log_analytics and rest values for protocol response parameter.

      • Added the requestTimeout response parameter to specify the amount of time, in seconds, that a remote event recipient has to forward events before the request times out.

      • Added the scheduler response parameter to specify the times and days when you want the specified events to be forwarded.

  • PUT /events/monitors/<forwarder_id> and POST /events/monitors.

    • Added response parameters to return information about new OMS and REST recipients.

    • For email recipients:

      • Added the authenticationEmail request parameter to specify the authentication type for email (SMTP) server recipients.

      • Added the connectionEmail request parameter to specify the Connection type to secure connection to the email (SMTP) server recipients.

      • Added the enable request parameter to specify whether the recipient is enabled.

      • Added catetories, severity and type request parameters to return event filter information.

      • Added the ignoreExcluded request parameter to specify whether to disable the forwarding of excluded events.

      • Added the outputFormat request parameter to specify the output format for the forwarded event.

      • Added the requestTimeout request parameter to specify the amount of time, in seconds, that a remote event recipient has to forward events before the request times out.

      • Added the scheduler request parameter to specify the times and days when you want the specified events to be forwarded.

      • Added the senderDomain request parameter to specify the sender domain for email (SMTP) server recipients.

      • Added the senderUserName request parameter to specify the sender name for email (SMTP) server recipients.

    • For SNMP recipients

      • Added the authPasswordSet request parameter to return the password string.

      • Added the enable request parameter to indicate whether the recipient is enabled.

      • Added catetories, severity and type request parameters to return event filter information.

      • Added the ignoreExcluded request parameter to specify whether to disable the forwarding of excluded events.

      • Added the outputFormat request parameter to specify the output format for the forwarded event.

      • Added the privacyPasswordSet request parameter to return the privacy password.

      • Added the oms_log_analytics and rest values for protocol request parameter.

      • Added the requestTimeout request parameter to specify the amount of time, in seconds, that a remote event recipient has to forward events before the request times out.

      • Added the scheduler request parameter to specify the times and days when you want the specified events to be forwarded.

    • For syslog recipients

      • Added catetories, severity and type request parameters to return event filter information.

      • Added the ignoreExcluded request parameter to specify whether to disable the forwarding of excluded events.

      • Added the outputFormat request parameter to specify the output format for the forwarded event.

      • Added the oms_log_analytics and rest values for protocol request parameter.

      • Added the requestTimeout request parameter to specify the amount of time, in seconds, that a remote event recipient has to forward events before the request times out.

      • Added the scheduler request parameter to specify the times and days when you want the specified events to be forwarded.

  • (New) POST /events/monitors/certificate. Trusts a certificate for a remote event recipient.

• Job management resources

  • GET /tasks. Added information about the JSON-formatted message description and user action. HTML format is not allowed. Added the uuid query parameter to return task information only for one or more specific groups and devices. Added the hidden response parameter to return whether the alert is hidden in the web interface. Added the scheduleId response parameter for scheduled jobs to return the ID of the schedule that started the job. Added the scheduleType response parameter for scheduled jobs to return the type of schedule. Added the summary response parameter to return information about the job summary. Added the translatedStatus response parameter to return the translated status text.
  • GET /tasks/detail. Added information about the JSON-formatted message description and user action. HTML format is not allowed. Added the hidden response parameter to return whether the alert is hidden in the web interface. Added the scheduleId response parameter for scheduled jobs to return the ID of the schedule that started the job. Added the scheduleType response parameter for scheduled jobs to return the type of schedule. Added the summary response parameter to return information about the job summary. Added the translatedStatus response parameter to return the translated status text.
  • (New) GET /tasks/schedules. Retrieves information about scheduled jobs
  • (New) POST /tasks/schedules. Create a scheduled job (task).
  • (New) PUT /tasks/schedules/<job_id>. Modifies a scheduled job (task).
  • (New) DELETE /tasks/schedules/<job_list>. Deletes one or more scheduled jobs (tasks).
  • (New) GET /tasks/schedules/actions. Retrieves a list of actions that can be scheduled as jobs
  • (New) POST /tasks/schedules/actions. Registers a new predefined action at the runtime
  • PUT /jobs/<job_id>. Added new request attributes for modifying a job, including cancelURI, category, createdBy, hidden, id, messageBundle,messageID , messageParameters, currentStep, maxStep, summary, typeId, uuid.

• Remote control resources

  • (New) GET /remoteaccess/remoteControl. Retrieves a JNLP file or URL to open a remote-control session to a specific managed server.

• Service and support resources

  • (New) PUT /service/callHomeGeneral. Modifies the general Call Home configuration settings.
  • PUT /warranty. Added the groupUUID request parameter to refresh warranty information for specific resource groups.

• Security resources

  • (New) GET /resourceAccessControl. Retrieves the current access-control settings.
  • (New) PUT /resourceAccessControl. Modifies the current access-control settings.

• Energy metrics

  • (New) GET /storage/metrics. Retrieves a set of sample metrics for all storage devices.
  • (New) GET /storage/metrics/<UUID>. Retrieves a set of sample metrics for specific storage devices.

The following methods were deprecated in earlier releases and are no longer included in the documentation.

• Inventory resources

  • GET /switch. UseGET /switches instead.
  • GET /switch/<UUID>. UseGET /switches/<UUID_list> instead.
  • PUT /switch/<UUID>. UsePUT /switches/<UUID> instead.
  • GET /switch/metrics. UseGET /switches/metrics instead.
  • GET /switch/metrics/<UUID>. UseGET /switches/metrics/<UUID> instead.