REST API Guide–OpenManage Essentials Abstract This technical white paper provides assistance 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.
Revisions 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.
Acknowledgements Contents Revisions.............................................................................................................................................................................2 Acknowledgements .............................................................................................................................................................2 Acronyms ....................................................................................................................
Acknowledgements 2.3.9 Device capabilities ............................................................................................................................................25 2.3.10 Warranty information ....................................................................................................................................26 2.3.11 Physical disk drive .....................................................................................................................................
Acknowledgements 2.16.2 Getting reports ..............................................................................................................................................49 2.16.3 Generic report format ...................................................................................................................................50 2.17 Manage Discovery ranges ................................................................................................................................
Acronyms Acronyms 6 Acronym Expansion REST RO ROA OME OMM Representational State Transfer Resource Oriented Resource Oriented Architecture OpenManage Essentials OpenManage Mobile REST API Guide–OpenManage Essentials
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. 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.
Key integration concepts An example of a base URI for OpenManage Essentials is as follows: https://192.168.0.1:2607/api/OME.svc/ The rest of the document will reference this example as . Security The REST services will be exposed only through HTTPS to ensure that the common threats associated with HTTP traffic are mitigated.
Key integration concepts HTTP method GET POST PUT DELETE HEAD Description 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. Used to create a new instance of a resource or append to the existing resource reference. Used to update a specific instance or create a specific resource instance with a specific identifier.
Key integration concepts Role Is user local administrator? Yes No HTTP Method PUT GET POST OmeAdministrators Yes Yes Yes DELETE 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.
Key integration concepts 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.
Key integration concepts 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. Response Header ContentType ContentEncoding LastModified Allow Location x-dell-apiversion 12 Description Example Specifies the format of the content that is returned by the server.
OpenManage Essentials-Specific Resource Model 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.
OpenManage Essentials-Specific Resource Model /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 resource URI can be used to retrieve information about a specific group: /DeviceGroups/ This URI returns the group attributes information described in the earlier table.
OpenManage Essentials-Specific Resource Model 2.1.2 Create Devices Group The following resource URI can be used to create device groups in OpenManage Essentials: /DeviceGroups Operation: POST 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.
OpenManage Essentials-Specific Resource Model 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
OpenManage Essentials-Specific Resource Model Devices The URI for accessing devices in OpenManage Essentials could be either based on the parent group resource or by directly accessing the devices.
OpenManage Essentials-Specific Resource Model Enum Value 8 9 10 11 12 13 14 15 16 18 19 20 21 22 23 24 26 28 29 30 Description Switch Chassis KVM Printer Tape EMC FC SWITCH MD Storage EqualLogic Group PDU UPS Client PowerEdge C Compellent NAS Appliance Network Appliance EqualLogic Member VxRail XC Series MX Chassis The type enumeration for the GlobalStatus is defined in the following table: Enum Value 0 2 4 8 16 Description None Unknown Normal Warning Critical For sorting devices, enter attribute names
OpenManage Essentials-Specific Resource Model /Devices/$sort(colu mn=Name,Id;direction=0,1)?Glo balStatus=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.
OpenManage Essentials-Specific Resource Model Upon successful completion, the specified device will be deleted from OME. If the user provides devices ID which are invalid, an error response will be returned. Only OmeAdministrators, OmePowerUsers, and OmeSiteAdministrators will have the permission to delete device from OME through REST, provided they also have local admin privilege. In case of insufficient permissions, the operation will fail and returns an error message.
OpenManage Essentials-Specific Resource Model Retrieving changed device information 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.
OpenManage Essentials-Specific Resource Model //Processor The attributes associated with each processor instance are described in the following table: Attribute Name MaxSpeed CurSpeed Cores Brand Model 2.3.3 Description The maximum speed of the processor. The current speed of the processor. The number of cores in the processor. The brand name of the processor. The model of the processor.
OpenManage Essentials-Specific Resource Model Attribute Name Name Manufacturer PartNumber Description The name associated with the DIMM. The manufacturer of the DIMM. The part number of the DIMM. All DIMMS that are currently installed in the device will be returned. At the end of the envelope, the total memory installed will be returned. The following is an example of the returned XML payload: Total memory 2.3.
OpenManage Essentials-Specific Resource Model The attributes associated with each software entity instance are described in the following table: Attribute Name Description Version Type Description The description of the software entity. The version of the software entity. The type of the software entity. The software type is described in the following table: Type APAC APP BIOS DRVR FRMW 2.3.
OpenManage Essentials-Specific Resource Model Agent information The values for the Status reported by the agent are defined in the following table: Enum Value 0 2 4 8 16 2.3.8 Description None – The status information is not available. Unknown – The status is unknown. Normal – The status is normal. Warning – Warning status reported by the agent. Critical – Critical status reported by the agent.
OpenManage Essentials-Specific Resource Model Enum Value 0 1 2 3 4 5 6 7 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 2.3.
OpenManage Essentials-Specific Resource Model DeviceModelType DeviceType ServiceTag ShippedDate StartDate EndDate ServiceLevelCode ServiceProvider WarrantyDescription WarrantyType OrderNumber DaysRemaining Model type of the device Type of the device Service Tag of the device The date the device originally shipped Date when the warranty started End date of the warranty Code to describe what level of service the warranty provides Name of the provider for the warranty Description of the warranty’s term of ser
OpenManage Essentials-Specific Resource Model The following is an example for service tag 6CP362S: Warranty information 2.3.
OpenManage Essentials-Specific Resource Model Attribute Name SerialNumber ModelNumber Revision PartNumber MediaType Vendor RemainingRatedWriteEdurance SupportedEncryptionTypes 2.3.12 Description The serial number of the drive. The model number of the drive. The revision number of the drive. Part number. The type of the media. Vendor name of the drive.
OpenManage Essentials-Specific Resource Model Attribute Name DataBusWidth Description Manufacturer SlotLength SlotNumber SlotType 2.3.15 Description Width of the data bus. Description of the card. Name of the manufacturer. Length of the slot. Slot number. Type of the slot.
OpenManage Essentials-Specific Resource Model Attribute Name LogicalDeviceCount CacheSizeInMB MemorySize Vendor CurrentMode 2.3.18 Description Logical device count. Size of the cache (in MB). Size of the memory. Vendor name. Current mode.
OpenManage Essentials-Specific Resource Model Attribute Name 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 32 Description Device Agent ArrayDisk CmcSlot ContactInfo Controller CostOfOwnership DeviceCard Enclosure EnclosureManagementModule Firmware FruInformation HyperVGuestNICView HyperVHostGuestView MaserInfo MemoryDevice ModularChassisAssociation NIC OperatingSystem PDUDeviceProperty PowerSupply PrinterCover P
OpenManage Essentials-Specific Resource Model 2.5 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.
OpenManage Essentials-Specific Resource Model Attribute Name Id DeviceGroupId ParentDeviceGroupId Description The identifier of the relationship. The device group identifier of the child device group. The device group identifier of the parent device group. The attributes associated with the individual entries of the DeviceGroupToDevice section of the returned payload are described in the following table: Attribute Name Id DeviceId ParentGroupId 2.5.1 Description The identifier of the relationship.
OpenManage Essentials-Specific Resource Model 2.7 Alert Filters OpenManage Essentials alert filters enable the filtering of alerts by severity, time, event category and source, acknowledged status, and devices/device groups.
OpenManage Essentials-Specific Resource Model Alerts (sorted): /Alerts/$sort(column=;direction=) 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: Attribute Name Id Severity Status Time Message EventCategory EventSource DeviceIdentifier DeviceNa
OpenManage Essentials-Specific Resource Model The enumerated values for the Status field are described in the following table: Enum Value 1 2 Description Not Acknowledged 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.
OpenManage Essentials-Specific Resource Model The response will be in the following format: PAGE 39OpenManage Essentials-Specific Resource Model The attributes associated with the alert subscription is described here: Attribute Name Id IdSubscriberService UserName Description IsEnabled AlertFilterId Token Description The unique identifier for the subscription. The enumerated type or identifier of the subscription service. This enables association with the correct notification mechanism. The user name of the subscriber. The description of the subscriber (for example, mobile device model).
OpenManage Essentials-Specific Resource Model Note: The field for Id is read-only and its value is only applicable on a GET operation. For the POST operation, this field is ignored; the recommendation is to set it to 0. The following screenshot shows the result of executing an AlertSubscription POST command using SoapUI 4.5.0.
OpenManage Essentials-Specific Resource Model Error 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.
OpenManage Essentials-Specific Resource Model AlertFilterId NewAlertCount LastEventId NotificationTimestamp The filter identifier associated with the subscription. The number of new alerts associated with this subscription notification. The last event identifier that is associated with the notification. The timestamp associated with the last time data was pushed.
OpenManage Essentials-Specific Resource Model 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.
OpenManage Essentials-Specific Resource Model 1 2 3 4 Administrator Dell1234 1 The attributes associated with the power control type enumeration are defined in the following table. Enum Value 0 1 2 3 4 2.12.2 Description None Shutdown PowerCycle Reset PowerOn LED control task LED control task can be utilized for controlling system LED on iDRAC.
OpenManage Essentials-Specific Resource Model A sample XML that would comprise the payload when initiating a POST operation to create a LED control task is as follows: 0 Blink LED Start blinking LED of 1,2,3 -1 1 1 2 3 username password The attributes associated with the LED
OpenManage Essentials-Specific Resource Model The attributes associated with the task status and progress information are described in the following table. Attribute Name StartTime EndTime TaskState PercentComplete LastUpdated Description The start time of the task. The end time of the task. The enumerated state of the task. The completion status of the task in percent. The time at which the task was last updated. The values of the TaskState are defined in the following table.
OpenManage Essentials-Specific Resource Model 2.13 Application information The following resource URI can be used to access information about the OME application: /Application Operations supported: GET The attributes associated with the application information are described in the following table: Attribute Name Name Description Vendor Version Build Number URL GUID 2.14 Description The name of the application. Description of the application. The vendor of the application. The software version.
OpenManage Essentials-Specific Resource Model This API returns the permissions associated with the loggedin 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.
OpenManage Essentials-Specific Resource Model The format of the XML output with the report types is as follows: 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.
OpenManage Essentials-Specific Resource Model 2.16.3 Generic report format The following is an example of a generic report: 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.
OpenManage Essentials-Specific Resource Model 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. Note: The dates and time are all in UTC format and are consistent with other XML date and time formats. 2.
OpenManage Essentials-Specific Resource Model Attribute Name Name RangeID Description The name of the range. The unique identifier for the range. SubnetMask Subnet mask for the discovery range. GroupName GroupID Timeout Retries WSManUserName WSManPassword Port SecureModeEnabled SkipNameCheck TrustedSiteEnabled CertificateFile The name of the discovery group. The unique identifier for the group. Timeout Number of attempts for ICMP/WSMan configuration iDRAC user name. iDRAC password.
OpenManage Essentials-Specific Resource Model 2.17.
OpenManage Essentials-Specific Resource Model Default value for the subnet mask is 255.255.255.0. Maximum supported ICMP timeout is 5000 ms and retries is 10. Maximum supported WSMan time out is 360s and retries is 10. 2.17.
OpenManage Essentials-Specific Resource Model IPrange rangename IPrange 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.
OpenManage Essentials-Specific Resource Model 4. This URI will return the first {top} number of devices after skipping {skip} number of devices from the first which are non-compliant with respect to system update portal: /Devices/SystemUpdateCompliance/NonCompliant/$skip={skip}&$top={top} 2.18.2 Non-Compliant devices for DeviceGroups Following are URI’s used to fetched non-compliant device from input device group id. These URI also support paging of output data. 1.
OpenManage Essentials-Specific Resource Model 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.
OpenManage Essentials-Specific Resource Model Broadcom Corp iDRAC.Embedded.1 100.96.26.171 44:A8:42:30:8C:47 2 bond0 100.96.25.102 4c:76:25:4f:1f:cd 1 idrac HS2RG52 VMware ESXi 6.5.
OpenManage Essentials-Specific Resource Model LW64 true 1 2.
OpenManage Essentials-Specific Resource Model 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.
OpenManage Essentials-Specific Resource Model OldValue Old(Template) value of the attribute. Enum value for ComplianceResult Attribute. Enum Value 0 1 2 3 2.19.1 Description Unknown – The status is unknown. Added – The status is Added. Missing – The status is missing. Different – The status is different. Configuration Compliance For Devices Following are the URIs used to fetch non-compliant configuration details for all Devices or for specific Device based on input device ID.
OpenManage Essentials-Specific Resource Model 2. Get top {top} non-compliant devices for all groups: /DeviceGroups/ConfigurationCompliance/NonCompliant/$top={top} 3. Get top {top} non-compliant devices for group id {id}: /DeviceGroups/{id}/ConfigurationCompliance/NonCompliant/$top={top} 4. Get top {top} non-compliant devices by skipping {skip} for group id {id}: /DeviceGroups/{id}/ConfigurationCompliance/NonCompliant/$skip={skip}&$top={top} 5.
OpenManage Essentials-Specific Resource Model A Technical support and resources • • Dell.com/support is focused on meeting customer needs with proven services and support. To watch quick and short videos about handling the PowerEdge server components, visit the QRL video website. A.1 Related resources A.1.1 Contacting Dell EMC Dell provides several online and telephone-based support and service options. Availability varies by country and product, and some services may not be available in your area.
