REST API Guide – OpenManage Essentials Dell EMC Engineering June 2017 A Dell EMC Technical White Paper
Revisions Date Description March 2014 Initial release September 2014 Additional features included with OpenManage Essentials version 2.0 September 2015 Revisions included with OpenManage Essentials version 2.1 July 2016 Additional features included with OpenManage Essentials version 2.2 June 2017 Additional features included with OpenManage Essentials version 2.3 The information in this publication is provided “as is.” Dell Inc.
Contents Revisions.............................................................................................................................................................................2 Introduction .........................................................................................................................................................................5 1 Key Integration Concepts ...........................................................................................................
2.4 Table inventory .................................................................................................................................................30 2.5 Device Group Hierarchy ...................................................................................................................................32 2.5.1 Retrieving Device Hierarchy Information That Has Changed ..........................................................................34 2.6 Device Logs ......................
Introduction This technical white paper provides a guide for integrating with OpenManage Essentials by using Representational State Transfer (REST) APIs. It provides examples of using REST to perform common tasks based on integration use cases with other products such as OpenManage Mobile, Repository Manager, and the Dell Software group portfolio. This document is not intended to be an introduction to REST.
1 Key Integration Concepts This section covers key integration concepts that are applicable to all of the use cases that are addressed in the next section. 1.1 Client Integration Overview The REST client makes standard HTTP(S) requests to the REST API end-point. Each request is sent using a HTTP verb (for example, PUT, GET, POST, DELETE, HEAD, and OPTIONS) and includes a message body in XML format. The response uses a standard HTTP status code.
1.3 Security The REST services will be exposed only through HTTPS to ensure that the common threats associated with HTTP traffic are mitigated. Administrator will have the option of updating the SSL self-signed certificate with a customer-provided certificate (for example, by uploading a PKCS-12 certificate or by signing an applicationgenerated CSR request). 1.4 Authentication mechanisms There are several common schemes for enabling authentication of REST requests.
1.6 Resource operations The standard HTTP methods are used for performing create, retrieve, update, and delete operations on the resources. The mapping of the HTTP methods to operational semantics is described in the following table. HTTP method Description Example GET Used to retrieve the resource representation. This method does not modify the resource across repeated invocations. The query parameters are appended to the URI to appropriately filter the resource instances.
1.7 Security considerations The OpenManage Essentials REST PUT and DELETE operations requires the user IDs used to run these commands have ‘write’ access to the base directory where the OpenManage Essentials REST services are installed. If the ‘write’ permission on this directory is not enabled for the user IDs used to access the DELETE and PUT operations, an error is returned indicated that the access is “Unauthorized”. 1.
1.10 Request headers The request header represents headers in the client HTTPS request that are used to communicate client preferences to the service end-point. The service will indicate the supported preference in the response header. The following table includes a few examples of request headers. For an extensive list of request headers, see List of HTTP header fields. 1.11 Request Header Description Example Accept Format of the data that is requested by the client.
1.12 Permission denied 403 – Permission denied Not found 404 – Resource not found Invalid request method 405 – Invalid request method Internal server error 500 – Internal server error Service unavailable 503 – Service unavailable Response headers The following table includes a few examples of response headers. For an extensive list of response headers, see List of HTTP header fields.
2 OpenManage Essentials-Specific Resource Model The following sub-sections represent a subset of the use cases that OpenManage Essentials supports. The REST API support and the operation support will be incrementally refined based on consumer feedback over multiple OpenManage Essentials releases. Also, see the data filtering/sorting and pagination sections for patterns that can be used for performing paged retrieval of large result sets in OpenManage Essentials (for example, alerts, devices, and so on).
The following resource URI can be used to retrieve the child groups of a specific group: /DeviceGroups//ChildGroups The following resource URIs can be used to retrieve the devices associated with a specific group: /DeviceGroups//ChildDevices (to retrieve all the immediate child devices) /DeviceGroups//Devices (to retrieve all the leaf devices for the group by performing a recursive traversal of the hierarchy rooted at the group identified by ) The following re
Rollup Health Enumeration The rollup health enumeration values are defined in the following table. Enum Value Description 0 None – Health status is not available. 2 Unknown – Health status is unknown. 4 Normal – Health status is normal. 8 Warning – Health status is warning. 16 Critical – Health status is critical. Device Group Type Enumeration The device group type enumeration values are defined in the following table.
2.2 Devices The URI for accessing devices in OpenManage Essentials could be either based on the parent group resource or by directly accessing the devices. For example: Devices by group (immediate child devices): /DeviceGroups//ChildDevices Devices by group (all devices): /DeviceGroups//Devices Devices by direct access :< BASE_URI>/Devices Any of the URIs specified earlier will be referenced as the in the subsequent sections of this document.
SystemModel The model of the device. ExpressServiceCode The service code associated with the device. DiscoveryTime The time when the device was last discovered. InventoryTime The time when the device was last inventoried. StatusTime The time when the device was last statused. OSName The name of the installed operating system. OSRevision The version of the operating system. NICS A collection of NIC elements identifying all the NICs associated with the particular device.
23 NAS Appliance 24 Network Appliance 26 EqualLogic Member 28 VxRail 29 XC Series The type enumeration for the GlobalStatus is defined in the following table. Enum Value Description 0 None 2 Unknown 4 Normal 8 Warning 16 Critical For sorting devices, enter attribute names and sort direction separated by commas in the corresponding place holders. Priority of sorting is implicit in ordering of attributes. The enumerated values for the sort direction are described in the following table.
/Devices/$sort(column=Name,Id; direction=0,1)?GlobalStatus=2&Type=2 2.2.1 All Unknown and Unclassified Devices sorted by Name (Ascending) and then by Id (Descending) Devices by direct access /Devices The resulting payload from this API is slightly different that the payload returned by the other device-related REST API calls.
2.2.2 Changed device information The changed device information can be obtained by the following REST API: /Devices/{AddedOrUpdatedTimestamp}&{DeletedTimestamp} The values of the AddedOrUpdatedTimestamp and DeletedTimestamp would have been obtained by a previous call to the /Devices REST API. This particular REST API will typically be used by a consumer that does its own device management and tracking periodically based on a particular polling cycle.
2.3 Device inventory The URIs described in this section can be used to retrieve more detailed inventory for each device. The DEVICE_BASE_URI is based on the parent group scope or the device scope. Operations supported: GET (for all inventory operations) 2.3.
2.3.3 NICs The following resource URI can be used to retrieve network interface information associated with a specific server identified by : //NIC The attributes associated with each NIC instance are described in the following table: 2.3.4 Attribute Name Description Description The description of the NIC. IPAddress The IP address of the NIC. MACAddress The MAC address of the NIC. Pingable A numeric indicator for whether the device can be pinged or not.
2.3.5 Memory The following resource URI can be used to retrieve memory information associated with a specific device with identified by : //Memory The attributes associated with each DIMM instance are described in the following table. Attribute Name Description Size The size of the DIMM in MB. Type The type of the DIMM. Name The name associated with the DIMM. Manufacturer The manufacturer of the DIMM. PartNumber The part number of the DIMM.
Figure 3 23 Total memory REST API Guide – OpenManage Essentials | Revision A02
2.3.6 Software inventory The following resource URI can be used to retrieve software inventory information associated with a specific device identified by : //Software The attributes associated with each software entity instance are described in the following table. Attribute Name Description Description The description of the software entity. Version The version of the software entity. Type The type of the software entity.
URL The management URL of the agent. Version The version of the agent. Note: In the case of the OpenManage Server Administrator (OMSA) agent, the value of the URL is a concatenated list of various URLs separated by the comma ‘,’ character. The consumer of this API will have to tokenize this output and attempt a web connection to each of the URLs to determine which URL is responsive before surfacing the URL to the actual consumer.
2.3.9 Attribute Name Description DeviceId The device identifier associated with the contact information. ContactName The name of the contact associated with the device. ContactInformation The information about the contact associated with the device. ContactDescription The description of the contact associated with the device.
16 iDRACInventory 17 NoOMSA 18 NoInvCollector 19 UnLicensedPlasma 20 LicensedPlasma 21 PlasmaPatch 22 PlasmaInventory 23 DellOEMServer 24 iDRACSixtyFourBit 25 DeviceConfigurationLicensed 26 DeviceConfigurationLicensable 27 iDRACMinVersionForISM 28 OSSixtyFourBit 29 FluidCache 30 ESXi 31 OOBAgent 32 InbandAgent 33 IOASupportsConfiguration 34 DellStorageNXtoNASApplicance 35 UnLicensedFX2 36 LicensedFX2 37 SwitchIsSupportedIoaModel 38 CmcSupportsXmlConfiguration
2.3.10 Warranty information The following resource URI can be used to retrieve the warranty information of a device identified by : //Warranty Operations Supported: GET The warranty information is defined in the following table.
The following is an example for service tag 6CP362S: Figure 5 2.3.11 Warranty information All inventory The following resource URI can be used to retrieve the entire inventory associated with a specific device identified by : //Inventory This URI would effectively return a concatenation of the individual components listed earlier (Firmware, Processor, NICs, Operating Systems, Memory, Software Inventory, Agents, ContactInfo, and DeviceCapabilities).
In addition to the components specified above, this command will return the following additional information: Enclosures There may be one or more enclosure entries. Each entry specifies the following attributes: Attribute Name Description EnclosureProductId The enclosure product ID. EnclosureServiceTag The Service Tag of the enclosure. EnclosureId The enclosure ID. SwitchInfos There may be one or more SwitchInfo entries. This section is applicable to switch devices only.
6 Controller 7 CostOfOwnership 8 DeviceCard 9 Enclosure 10 EnclosureManagementModule 11 Firmware 12 FruInformation 13 HyperVGuestNICView 14 HyperVHostGuestView 15 MaserInfo 16 MemoryDevice 17 ModularChassisAssociation 18 NIC 19 OperatingSystem 20 PDUDeviceProperty 21 PowerSupply 22 PrinterCover 23 PrinterInputTray 24 PrinterOutputTray 25 PrinterSupply 26 Processor 27 RACDevice 28 SoftwareInventory 29 StorageBattery 30 StorageGroup 31 SwitchDevice 32 T
2.
The attributes associated with the returned payload are described in the following table. 33 Attribute Name Description HierarchyAddedOrUpdatedTimestamp The last timestamp for the device group to device group hierarchy where an addition or update was performed. HierarchyDeletedTimestamp The last timestamp for the device group to device group hierarchy timestamp where a deletion was performed.
The attributes associated with the individual entries of the DeviceGroupToDeviceGroup section of the returned payload are described in the following table. Attribute Name Description Id The identifier of the relationship. DeviceGroupId The device group identifier of the child device group. ParentDeviceGroupId The device group identifier of the parent device group.
2.6 Device Logs The following resource URI can be used to retrieve the device logs: //HWLogs/SEL (to retrieve the SEL logs) OpenManage Essentials may expose Lifecycle Controller logs in the future and that would require a separate URI construct as the attributes exposed are slightly different (for example, recommended action and detailed description). Operations supported: GET The attributes associated with each log entry are represented in the following table. 2.
The following URI enables filtering the alerts based on the criteria defined by the alert filter. /AlertFilters//Alerts To get a summary by severity for each alert filter, the following URI can be used: /AlertFilters//Summary The attributes associated with the alert filter are described in the following table. 2.8 Attribute Name Description TotalAlerts The total number of alerts that match the filter criteria. CriticalCount The number if alerts with a critical severity.
Attribute Name Description Id The unique identifier for the alert. Severity The enumerated severity of the alert. Status The status of the alert (for example, to indicate whether the alert is acknowledged or not). Time The date/time for the alert. Message The message corresponding to the alert. EventCategory The event category for the alert. EventSource The OpenManage Essentials alert source name for the alert. DeviceIdentifier The device identifier associated with the alert.
Enum Value Description 1 Unknown 2 Informational 4 Normal 8 Warning 16 Critical The enumerated values for the Status field are described in the following table. Enum Value Description 1 Not Acknowledged 2 Acknowledged For sorting alerts enter attribute names and sort direction separated by commas in corresponding place holders. Priority of sorting is implicit in ordering of attributes. The enumerated values for the sort direction are described in the following table.
To delete an alert use the standard HTTP DELETE operation. To acknowledge an alert or clear the acknowledgement use the standard HTTP PUT operation. For the content of the URL PUT request use plain text (text/plain) and send ‘status=clear’ or ‘status=acknowledge’ to update the status. Requesting an acknowledgement or clearing an acknowledgement can be requested regardless of the current status. The requested status will become the current status. Any other operations will be considered an error.
The following URI can be used to perform alert subscription operations: Alert subscriptions: /AlertSubscriptions Operations supported: GET, POST, PUT, and DELETE Attributes (filtering): Id The attributes associated with the alert subscription is described below. Attribute Name Description Id The unique identifier for the subscription. IdSubscriberService The enumerated type or identifier of the subscription service. This enables association with the correct notification mechanism.
2.9.3 AlertSubscription POST example Data The payload for the POST command is an XML structure that defines the various fields that are needed to create an Alert Subscription. Note: All the values in the payload are case sensitive. Of particular importance are Boolean values such as the included in the following example. This type of attribute takes the values of ‘true’ or ‘false’ in lower case. Any other value, including ‘True’ and ‘False’ will create an invalid data error when posting.
Figure 7 2.9.4 Error AlertSubscription PUT command An update of the subscription information can be accomplished with a PUT operation. Note: The payload for the PUT operation is identical to the payload of the POST operation. Note: The subscription corresponding to the device identifier will be updated (if it exists). If the subscription with the corresponding device identifier does not exist, then the operation will return an error in the response header 2.
The attributes associated with the alert subscription notification are described in the following table. Attribute Name Description Id The unique identifier for the subscription notification. SubscriptionId The subscription identifier. AlertFilterId The filter identifier associated with the subscription. NewAlertCount The number of new alerts associated with this subscription notification. LastEventId The last event identifier that is associated with the notification.
2.12 Tasks The following URI can be used to create a new task: Task URI: < BASE_URI>/Tasks Operations supported: GET and POST Attributes (filtering): TaskId 2.12.1 Power control task The following resource URI can be used to create a power control task. Power control task URI: < BASE_URI>/Tasks/PowerControl (POST operation) The attributes associated with the power control task are described in the following table. Attribute Name Description Id Always set this to 0 when creating a new task.
A sample XML that would comprise the payload when initiating a POST operation to create a power control task is as follows: 0 Power Off - REST Power Off Task 46 22 */1 * * * 1 1 2 3 4 Administrator Dell1234 1 The attributes associate
Devices The list of selected device identifiers. If only one device is affected, the list will contain one element. The device identifier is the identifier associated with the device. Schedule The schedule for the task. This will be in cron format. If it is a run now task, the schedule will have a special value (“-1”). UserName The username required to run the task. Password The password required to run the task.
Therefore, the example translates to executing the task every day at 22:46 UTC. What this means is that particular attention needs to be paid to the locale where this REST command is executed and the necessary conversion to the hour field needs to be performed (conversion to UTC according to the locale) so that the right execution hour is persisted in the database. 2.12.
Attribute Name Description StartTime The start time of the task for the specific device. EndTime The end time of the task for the specific device. Status The status enumeration of the task for this device. DeviceId The device identifier for the task. Summary The summary of the task execution for the specific device. Details The details of the task execution for the specific device. The device Status enumeration is defined in the following table. 2.
2.14 URL The URL for the web-based management application. GUID A unique identifier for the OpenManage Essentials instance. Current user information The following resource URI can be used to access information about the currently authenticated user: /CurrentUser Operations supported: GET The attributes associated with the current user information is described in the following table.
2.16 Reports The currently available reports in OpenManage Essentials are provided through the REST API. These reports are identical to the reports found in OpenManage Essentials, including column names and sort order. 2.16.1 Report types The following resource URI can be used for accessing a list of currently available reports: /Reports Operations supported: GET The types of reports are defined in the following table.
23 ProcessorInformation 24 StorageControllerInformation 25 VirtualDiskInformation 26 WarrantyInformation 27 BiosConfiguration 28 IDracNetworkConfiguration 29 DeviceConfigurationCompliance 30 BaselineAssociation 31 AssignedIdentities 32 AllIdentityAttributes 33 AgentHealthStatus The format of the XML output with the report types is as follows: 51 REST API Guide – OpenManage Essentials | Revision A02
Figure 8 Report types Note: As new reports are added to OpenManage Essentials, they will be added to the list of report types. Using the /Reports operation provides the current list of supported reports. 2.16.2 Getting reports The following resource URI can be used for getting reports: /Reports/{Report Type} For the report types, see the Report Types section.
2.16.3 Generic report format The following is an example of a generic report: Figure 9 Generic report The title of the report is the same as the report in OpenManage Essentials. The TotalRowCount is the number of rows in the entire report. If paginiation has been used as described in Data , then the RowOffset will be the number of rows skipped and the CurrentRowCount will be the number of rows included in this part of the report that has been returned. The next part of the report are the column headers.
The data rows are a list of rows which include the cell data and the matching column number. There are no row numbers to indicate the order, rather it is the order in which the report is read. The following is an example of the data rows in the report: Figure 10 Data rows When parsing the data, note that data types in this report format are all strings. You can determine the best type to which you want to deserialize the data.
A 55 Glossary Term Meaning REST Representational State Transfer RO Resource Oriented ROA Resource Oriented Architecture OME OpenManage Essentials OMM OpenManage Mobile REST API Guide – OpenManage Essentials | Revision A02
