REST API Guide – OpenManage Essentials Dell EMC Engineering January 2018
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 January 2018 Additional features included with OpenManage Essentials version 2.
Contents Revisions.............................................................................................................................................................................2 Introduction .........................................................................................................................................................................6 1 Key Integration Concepts ...........................................................................................................
2.3.7 Agent information..............................................................................................................................................27 2.3.8 Contact information ..........................................................................................................................................28 2.3.9 Device capabilities ............................................................................................................................................29 2.3.
2.13 Application information .....................................................................................................................................54 2.14 Current user information ...................................................................................................................................55 2.15 User permissions ..............................................................................................................................................55 2.16 Reports ...
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. 1.7 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.
Is user local administrator? Yes No Role GET HTTP Method POST PUT DELETE OmeAdministrators Yes Yes Yes Yes OmePowerUsers Yes Yes Yes Yes OmeUsers Yes No No No OmeAdministrators Yes Yes No No OmePowerUsers Yes Yes No No OmeUsers Yes No* No No *For Site Administrators not having local administrator privilege, the POST method is permitted if the specified operation is allowed by using the GUI. 1.
The devices with a health status identified by 16 (Critical) are returned. The number of devices returned could be less than the maximum of 100 that was requested. 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.
1.12 Invalid parameter 400 – Invalid parameter Authorization 401 – Authorization failure 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.1.
In this POST operation, user has to provide the name and description of the group to be created in the payload. Optionally, user can provide a list of device IDs to be added to the group in the payload.
Attribute Name Description Name Name of the device group Description A short description of the device group AddDevices List of DeviceIDs to be added to the group RemoveDevices List of DeviceIDs to be removed from the group The payload for this PUT operation is as follows: Group 2 This is new group description 4 5 6 1 2 3
This operation deletes the specified custom group if it exists in OME. If the specified group is not present in OME, a corresponding error is returned. Any groups other than custom groups cannot be deleted. Only OmeAdministrators, OmePowerUsers, and OmeSiteAdministrators will have the permission to delete a custom device group, provided they also have the local admin privilege. In case of insufficient permissions, the operation will fail and returns an error message.
NodeId The specific node identifier rather than the Service Tag that is used to identify a device such as the PowerEdge FM120x4 sled. LaunchURL The URL for the portal page for the iDRAC, if the device is a server. AssetTag The asset tag of the device. 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.
18 PDU 19 UPS 20 Client 21 PowerEdge C 22 Compellent 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.
URI Result /Devices/$sort(column=Name,Id; direction=0,1) Devices sorted by Name (Ascending) then by Id (Descending) /Devices/$top=5&$sort(column=N First 5 devices from the list of devices sorted by Name ame,Id;direction=0,1) (Ascending) then by Id (Descending) 2.2.
Figure 1 Timestamps The AddedOrUpdatedTimestamp and DeletedTimestamp denote the latest timestamps associated with the device payload just returned. These timestamps can be used to retrieve delta information by a consumer. 2.2.2 Delete Device The following URI allows user to delete device from OME until it is discovered next time. This will remove the device from the device tree and it will not be shown under any group.
Figure 2 2.3 Retrieving changed device information 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.2 Name The name of the firmware. Version The version of the firmware. Processor The following resource URI can be used to retrieve information about the CPUs associated with a specific server identified by : //Processor The attributes associated with each processor instance are described in the following table. 2.3.3 Attribute Name Description MaxSpeed The maximum speed of the processor. CurSpeed The current speed of the processor.
//OS The attributes associated with each operating system instance are described in the following table. 2.3.5 Attribute Name Description Type The operating system type. Name The name of the operating system. Revision The operating system revision. ServicePackVersion The service pack version.
Figure 3 2.3.6 Total memory 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.
Description The description of the software entity. Version The version of the software entity. Type The type of the software entity. The software type is described in the following table. 2.3.
responsive before surfacing the URL to the actual consumer. The following is an example of the URL for OMSA as returned in the REST XML payload. Figure 4 Agent information The values for the Status reported by the agent are defined in the following table. 2.3.8 Enum Value Description 0 None – The status information is not available. 2 Unknown – The status is unknown. 4 Normal – The status is normal. 8 Warning – Warning status reported by the agent.
2.3.9 Device capabilities The following resource URI can be used to retrieve the list of device capabilities associated with a specific device identified by : //DeviceCapabilities The attributes associated with each device capability entity instance is described in the following table. Attribute Name Description DeviceId The device identifier. DeviceCapabilityId The identifier of the device capability. DeviceCapabilityName The name of the device capability.
2.3.
Device Model Type Model type of the device Device Type Type of the device Service Tag Service Tag of the device Shipped Date The date the device originally shipped Start Date Date when the warranty started End Date End date of the warranty Service Level Code Code to describe what level of service the warranty provides Service Provider Name of the provider for the warranty Warranty Description Description of the warranty’s term of service Warranty Type Type of the warranty Order Number O
The following is an example for service tag 6CP362S: Figure 5 2.3.11 Warranty information Physical disk drive The following resource URI can be used to retrieve information about the Physical disk drives associated with a specific server identified by : //PhysicalDisk The attributes associated with each physical drive instance are described in the following table: 32 Attribute Name Description Name The name of the physical drive.
2.3.12 EnclosureID ID of the enclosure. Channel Channel number. TargetID ID of the target. LunID LUN ID. SizeInGB Size of the disk (in GB). BusType Type of the bus. SerialNumber The serial number of the drive. ModelNumber The model number of the drive. Revision The revision number of the drive. PartNumber Part number. MediaType The type of the media. Vendor Vendor name of the drive.
2.3.13 Power supply unit (PSU) The following resource URI can be used to retrieve information about the PSUs associated with a specific server identified by : //PowerSupply The attributes associated with each PSU instance are described in the following table: 2.3.14 Attribute Name Description Location Location of the PSU. OutputInWatts Power supply output (in Watt). Type Type of the PSU. PowerMonitoringCapable Power monitoring capability.
2.3.16 Attribute Name Description Description Description of the device. Manufacturer Name of the manufacturer. Enclosure slot The following resource URI can be used to retrieve information about the Enclosure slots associated with a specific server identified by : //EnclosureSlot The attributes associated with each enclosure slot instance are described in the following table. 2.3.17 Attribute Name Description Slot Enclosure slot number.
2.3.18 PhysicalDeviceCount Physical device count. LogicalDeviceCount Logical device count. CacheSizeInMB Size of the cache (in MB). MemorySize Size of the memory. Vendor Vendor name. CurrentMode Current mode.
SwitchRole 2.4 Indicates if the unit is a management unit, standby unit, stack unit, and local unit. Table inventory This is a generic API that returns the data of individual tables defined in OpenManage Essentials: /TableInventory/{table id} To request the table inventory for a specific device: /{device id}/TableInventory/{table id} The following table describes the table IDs.
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 TapeDrive 33 TapeLibrary 34 TPMInfo 35 UPSPhysicalBattery 36 VirtualDisk 37 VirtualFlash 38 VMDeviceInfoView 39 VMHostInfo 40 EventCatalog 41 EventCategory 42 EventSource 43 HyperVGuestInfo 44 HyperVGuestMemoryInfo 45 HyperVGuestNICInfo 46 Hyper
2.5 49 NASApplianceNode 50 SoftwareInventoryOOB Device Group Hierarchy Some consumers of the OpenManage Essentials REST API services will require the capability of retrieving information that has changed since a particular point in time. The OpenManage Essentials server continuously updates its database with new device information, new hierarchical information, and information that has been deleted.
DeviceGroupToDevice A collection of device group to device relationships. This relationship is defined in a later table. DeletedDeviceGroupToDeviceGroup A collection of integers that define the device group to device group identifiers that have been deleted since the last HierarchyDeletedTimestamp was specified. DeletedDeviceGroups A collection of integers that define the device group identifiers that have been deleted since the last DeviceGroupDeletedTimestamp was specified.
For example, to get the complete device hierarchy, the following API can be used: https://:2607/api/OME.svc/DeviceGroupHierarchy To retrieve device hierarchy information that has changed use a command such as the following: https://OME_SERVER>:2607/api/OME.svc/DeviceGroupHierarchy/0,0,0,0,0,2,32,205&0,0 ,0,0,0,2,32,205&0,0,0,0,0,2,32,204&0,0,0,0,0,2,32,204&0,0,0,0,0,2,32,207&0,0,0,0 ,0,2,32,207 2.
Attribute Name Description Id The unique identifier for the filter. Name The name of the filter. Type The type of filter (for example, view filter, action filter, and so on). IsEnabled A flag indicating whether the filter is enabled or disabled. IsReadOnly A flag indicating whether the filter is read-only or editable.
Operations supported: GET, DELETE, and PUT Attributes (filtering): Id, Severity, and Status Attributes (sorting): Timestamp Desc (by default), Id, Severity, Status, Message, and DeviceName The attributes associated with the alerts are described in the following table. 43 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).
‘True’ or ‘False’. It signifies whether the device that generated the alert is an iDRAC device. IsIdrac The enumerated values for the Severity field are described in the following table. 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.
/Alerts/$sort(column=Id,Status; direction=0,1)?Severity=8 2.8.1 All warning alerts sorted by Id (Ascending) and then by Status(Descending) Delete Alerts /Alerts/{id}{|{id}} Operation: DELETE To delete an alert use the standard HTTP DELETE operation. 2.8.2 Acknowledge Alerts /Alerts/{id}{|{id}} Operation: PUT To acknowledge an alert or clear the acknowledgement use the standard HTTP PUT operation.
2.8.3 Last alert IDs /Alerts/LastAlertId This API returns the ID of the last alert inserted in the OpenManage Essentials database. 2.8.4 Alerts since /AlertsSince/{id} This API returns the alerts since the identifier provided ({id}). This identifier will typically be obtained by a call to /Alerts/LastAlertId at some time in the past. 2.9 Alert subscriptions Alert subscriptions provide an option to register or subscribe for alerts that match a filter.
2.9.1 IdSubscriberService number Description 1 Google Cloud AlertSubscription GET command To get the associated subscription that is assigned to a mobile device, you must specify the device ID that is associated to the particular device. The GET command suffix is as follows: /AlertSubscriptions/ 2.9.2 AlertSubscription DELETE command Deletion of the subscription (or unsubscribe) is accomplished using the standard HTTP DELETE operation.
Figure 6 Alert subscription Figure 7 Error REST API Guide – OpenManage Essentials | Revision A02
2.9.4 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.
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. URI: < BASE_URI>/Tasks/PowerControl Operations: POST 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. Name The name of the 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
Description A short description of the task. ControlType An enumerated value indicating the type of LED control (Start LED, Stop LED) 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.
*/1 * * * : day of month : weekly : monthly : yearly 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.
The details for task execution on multiple devices can be queried by /ExecutionDetails The attributes associated with task execution on multiple devices are described in the following table. 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.
2.14 Description Description of the application. Vendor The vendor of the application. Version The software version. Build Number The build number. URL The URL for the web-based management application. GUID A unique identifier for the OpenManage Essentials instance.
This is typically an API that will be used by third party consumers programmatically. The {SID} needs to be provided as parameter. This API returns the permissions associated with the logged in user ID. The permissions are represented as a collection of integers. 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.
19 NicInformation 20 PciDeviceInformation 21 PerformanceMinimumMaximum 22 PerformanceAveragePeak 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: 57 REST API Guide – OpenManage Essenti
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.
Operations supported: GET, POST, PUT, and DELETE Attributes (filtering): RangeID, and GroupID The attributes associated with manage discovery groups and discovery ranges are described in the following table: Attribute Name Description Address IP address of the discovery range. HostName Name of the host. Name The name of the range. RangeID The unique identifier for the range. SubnetMask Subnet mask for the discovery range. GroupName The name of the discovery group.
The attributes associated with the discovery action enumeration are defined in the following table. 2.17.
hostname netmask timeout retries iDRACUserName iDRACPassword timeout retries portnumber true/false true/false<
IPrange rangename netmask IPrange netmask hostname netmask Note: 1. Comma separated Host names are not allowed. 2. Default value for the subnet mask is 255.255.255.0. 2.17.
2.17.5 Delete Discovery Range The following resource URI can be used to delete discovery range in OpenManage Essentials: /DiscoveryRanges/Ranges/{RangeID} Operations supported: DELETE 2.17.6 Delete Discovery Group The following resource URI can be used to delete discovery group in OpenManage Essentials: /DiscoveryRanges/Groups/{GroupID} Operations supported: DELETE 2.
/DeviceGroups//SystemUpdateCompliance/NonCompliant/Devices 2. This URI will return the count of devices which are non-compliant with respect to the group. If the group is custom group and associated to custom catalog, the devices which are non-compliant with associated catalog will be considered.
2.18.4 Non-Compliant Package for DeviceGroups Following are URIs used to fetched non-compliant pacakges for devices. These URI also support paging of output data: 1. This URI will return all the non-compliant packages for the devices which are non-compliant with respect to the group. If the group is custom group and associated to custom catalog, the devices which are noncompliant with associated catalog will be considered.
true false https://100.96.26.171:443 Broadcom Gigabit Ethernet BCM5720 - 44:A8:42:30:8C:44 44:A8:42:30:8C:44 Broadcom Corp iDRAC.Embedded.1 100.96.26.
http://www.dell.com/support/home/us/en/19/Drivers/DriversDetails?driverId=HRP 1V 3 DCIM:INSTALLED#308_C_Enclosure.Internal.0-1:RAID.Integrated.1-1 5d3bd680-549c-30ca-8656-989782b6de7e 1 Microsoft Windows 2016 Server, Standard x64 Edition Firmware_HRP1V_WN64_2.25_A00-00_01.
SA = Serial ATA AS = SAS SF = SAS RAID SE = SAS Non RAID BI = BIOS Chipset = Chipset FC = Fibre Channel PC = PCIe ES = ESM TH = Tape Drives AU = Audio VI = Video DI = Diagnostics SV = Lifecycle Controller FW = Firmware SG = Storage Controller CE = Chassis System Management IN = Input AP = Application iDRAC with Lifecycle Controller = iDRAC with Lifecycle Controller Express Flash PCIe SSD = Express Flash PCIe SSD ImportanceID Installation Services Package Services OOBCapability SixyBitSupport 2.
Sample output for non-compliant devices attribute details. Attributes Description AttributeName Name of configuration attribute. ComplianceResult Compliance status of the attribute. ComponentName Component name of the attribute. DeviceId Device Id NewValue New(Inventory) value of the attribute. OldValue Old(Template) value of the attribute. Enum value for ComplianceResult Attribute. 2.19.1 Enum Value Description 0 Unknown – The status is unknown. 1 Added – The status is Added.
1. Get all non-compliant configuration details for all devices: /Devices/ConfigurationCompliance/NonCompliant/NonComplianceDetails 2. Get count of non-compliant configuration details for all devices: /Devices/ConfigurationCompliance/NonCompliant/NonComplianceDetails/Count 3. Get top {top} non-compliant configuration details: /Devices/ConfigurationCompliance/NonCompliant/NonComplianceDetails/$top={top} 4.
5. Get count of non-compliant configuration details for group id {id}: /DeviceGroups/{id}/ConfigurationCompliance/NonCompliant/NonComplianceDetails/ Count 6. Get all non-compliant configuration details for group id {id}: /DeviceGroups/{id}/ConfigurationCompliance/NonCompliant/NonComplianceDetails 7. Get top {top} non-compliant configuration details for group id {id}: /DeviceGroups/{id}/ConfigurationCompliance/NonCompliant/NonComplianceDetails/ $top={top} 8.
A 74 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
