White Paper Updating Firmware using OpenManage Enterprise APIs Abstract This document shows the workflow and the APIs involved in the firmware update process for OpenManage Enterprise v3.0, v3.1, v3.2 and OpenManage Enterprise – Modular Edition v1.0 and v1.00.
Revisions Revisions Date Description September 2019 Initial release Acknowledgements This paper was produced by the following: Author: Vandana Mallempati Support: OpenManage Enterprise and OpenManage Enterprise Modular engineering teams The information in this publication is provided “as is.” Dell Inc.
Table of contents Table of contents Revisions.............................................................................................................................................................................2 Acknowledgements .............................................................................................................................................................2 Table of contents .................................................................................................
Executive summary Executive summary This document shows the workflow and the APIs involved in the firmware update process for OpenManage Enterprise v3.0, v3.1, v3.2 and OpenManage Enterprise – Modular Edition v1.0 and v1.00.10.
Introduction 1 Introduction OpenManage Enterprise (OME) supports firmware update/downgrade actions across supported devices using one of the two possible workflows: 5 Update/downgrade devices or a group (of devices) using a single DUP Update/downgrade devices or a group (of devices) using a catalog Updating Firmware using OpenManage Enterprise APIs
Workflow 2 Workflow 2.1 Update using a Catalog 1. Create a catalog from an online source or point to a remote repository that hosts a catalog and the associated DUP files referenced in the catalog. The online catalog source is https://downloads.dell.com. The supported offline catalog sources are: ‐ ‐ ‐ ‐ HTTP HTTPS CIFS NFS 2. Create a firmware baseline for the targets (device/devices/group of devices) using the catalog specified in step 1a. 3.
APIs 3 APIs POST /api/UpdateService/Catalogs Description: This method creates a catalog Result Codes: HTTP Response Code Description 201 Catalog successfully created Privilege: Users with BASELINE_MANAGEMENT, JOB_MANAGEMENT and DEVICE_UPDATE privilege can create catalogs and baselines, and update firmware. These privileges map to the Admin user role.
APIs Example: Request Payload to create a catalog from Dell support site (downloads.dell.com) { "Filename": "", "SourcePath": "", "Repository": { "Name": “Test”, "Description": "Dell Online test", "RepositoryType": "DELL_ONLINE", "Source": "downloads.dell.com", "DomainName": "", "Username": "", "Password": "", "CheckCertificate": False } } Example: Request Payload to create a catalog from a CIFS share { "Filename":"Catalog.xml", "SourcePath":"DUPS\\R520\\", "Repository":{ "Name":"CIFS", "Description":"CIFS
APIs Example: Request Payload to create a catalog from a HTTPS location { "Filename":"catalog.xml", "SourcePath":"install_packages/Packages", "Repository":{ "Name":"HTTPS-again", "Description":"HTTPS Desc", "RepositoryType":"HTTPS", "Source":"", "DomainName":"", "Username":"", "Password":"", "CheckCertificate":false } } Example: Response on successful catalog creation (HTTP 201) Note: Catalog creation is an asynchronous process.
APIs "AssociatedBaselines": [] } GET /api/UpdateService/Catalogs Description: This method returns all existing catalogs Result Codes: HTTP Response Code Description 200 Returns an enumeration of catalogs. Privilege: View Response: Attribute Name Type Description Filename String File name of the catalog SourcePath String Relative path of the catalog file from the repository (for example: downloads.dell.com/catalog/catalog.
APIs Attribute Name Type Description Name String Name of the repository Description String Description of the repository provided by users Source String URL or location of the repository DomainName String Domain for the user credentials (CIFS only) Username String Username to access the share containing the catalog (CIFS/HTTPS) Password String Password to access the share containing the catalog (CIFS/HTTPS) CheckCertificate String Whether certificate checking was enabled for the HTTP
APIs "Source": "downloads.dell.com", "DomainName": null, "Username": null, "Password": null, "CheckCertificate": false, "RepositoryType": "DELL_ONLINE" } } ] } The following response payload indicates that there are multiple baselines associated with this catalog. { "@odata.context": "/api/$metadata#Collection(UpdateService.Catalogs)", "@odata.count": 1, "value": [ { "@odata.type": "#UpdateService.Catalogs", "@odata.id": "/api/UpdateService/Catalogs(22)", "Id": 22, "Filename": "catalog.
APIs { "BaselineId": 7, "BaselineName": "Test 100" }, { "BaselineId": 8, "BaselineName": "Test 2500+" } ], "Repository": { "@odata.type": "#UpdateService.Repository", "Id": 12, "Name": "Dell", "Description": "", "Source": "downloads.dell.com", "DomainName": null, "Username": null, "Password": null, "CheckCertificate": false, "RepositoryType": "DELL_ONLINE" } } ] } 3.1 Create firmware baseline Create a firmware baseline to associate a catalog with one or more devices or groups of devices.
APIs Attribute Name Type Description Required CatalogId Integer ID of the catalog—Users must enumerate all catalogs and match the “Name” of the repository with the input provided while creating the catalog Yes RepositoryId Integer ID of the repository – Derived from the catalog response Yes DowngradeEnabled Boolean Indicates if the firmware can be downgraded No Is64Bit Boolean This must always be set to true—The size of the DUP files used is 64-bits.
APIs "CatalogId": 24, "RepositoryId": 14, "RepositoryName": null, "RepositoryType": null, "DowngradeEnabled": false, "Is64Bit": false, "TaskId": 25113, "ComplianceSummary": null, "Targets": [ { "Id": 25004, "Type": { "Id": 0, "Name": "DEVICE" } } ], "DeviceComplianceReports": [] } Note: Creation of baselines is an asynchronous process – Until the job to compute the compliance report for the baseline is completed, the baseline ID remains 0 and some of the baseline properties default to “null”.
APIs Attribute Name Type Description RepositoryType String Type of the repository LastRun String Date and time when the baseline was last run.
APIs "Id": 6000, "Name": "GROUP" } } ], "ComplianceSummary": { "ComplianceStatus": "CRITICAL", "NumberOfCritical": 7761, "NumberOfWarning": 1, "NumberOfNormal": 12, "NumberOfDowngrade": 1 }, "DeviceComplianceReports@odata.navigationLink": "/api/UpdateService/Baselines(8)/DeviceComplianceReports" } ] } 3.2 View firmware baseline compliance The firmware baseline compliance report displays the compliance of the selected devices or device groups. The compliance specifies if an action is required.
APIs Attribute Name Type Description DeviceName String Name of the device FirmwareStatus String Indicates if firmware is compliant or not ComplianceStatus String Indicates the compliance status DeviceTypeId Integer Numeric value for the device type such as server(1000) RebootRequired Boolean Indicates if a reboot is required to make the device compliant. Link Link to the component compliance report, identifying the software components on the device and if they match up against the catalog.
APIs "SourceName": "DCIM:INSTALLED#802__DriverPack.Embedded.1:LC.Embedded.1", "PrerequisiteInfo": "", "ImpactAssessment": "", "Uri": "http://www.dell.com/support/home/us/en/19/Drivers/DriversDetails?driverId=1HPN9 ", "RebootRequired": false, "ComplianceStatus": "WARNING", "ComplianceDependencies": [] }, { "@odata.type": "#UpdateService.ComponentComplianceReport", "Id": 39, "Version": "4247A1", "CurrentVersion": "0", "Path": "FOLDER03035031M/1/Diagnostics_Application_D5TM2_WN64_4247A1_4247.2.
APIs "@odata.id": "/api/UpdateService/Baselines(6)/DeviceComplianceReports(1)", "Id": 1, "DeviceId": 25013, "ServiceTag": "B5JLMN2", "DeviceModel": "PowerEdge C6420", "DeviceTypeName": "SERVER", "DeviceName": "idrac-B5JLMN2", "FirmwareStatus": "Non-Compliant", "ComplianceStatus": "CRITICAL", "DeviceTypeId": 1000, "RebootRequired": true, "ComponentComplianceReports@odata.navigationLink": "/api/UpdateService/Baselines(6)/DeviceComplianceReports(1)/ComponentComplianceR eports" } ] } Note: In OME 3.
APIs Attribute Name Type Description SourceName String String identifier of the software component. It also identifies the location on the device. More information on the software inventory and source name mappings to devices can be found at /api/DeviceService/Devices()/InventoryDetails('deviceSoftware') PrerequisiteInfo String Indicates if there are any prerequisites for updating the component to the new version ImpactAssessment String Similar to criticality, but largely not filled.
APIs "ComplianceStatus": "CRITICAL", "ComplianceDependencies": [] }, … } } 3.3 Update the firmware Update firmware by using the firmware baseline compliance report In this case, you can update the firmware for one or more components on one or more devices, by referring to the compliance report for the devices against the catalog.
APIs Attribute Name Type Description Required catalogID String Catalog ID derived from enumerating catalogs Yes operationName String Type of operation (install firmware) Yes complianceUpdate Boolean Indicates if this update must match compliance Yes signVerify Boolean Indicates if the DUP signature must be verified Yes stagingValue Boolean If “true” stages updates and runs them on the next reboot of the system ID Integer Identifier of the device to be updated Yes Data String Str
APIs "Key":"repositoryId", "Value":"14" }, { "JobId":0, "Key":"catalogId", "Value":"24" }, { "JobId":0, "Key":"operationName", "Value":"INSTALL_FIRMWARE" }, { "JobId":0, "Key":"complianceUpdate", "Value":"true" }, { "JobId":0, "Key":"signVerify", "Value":"true" }, { "JobId":0, "Key":"stagingValue", "Value":"false" } ], "Targets":[ { "Id":25013, "Data":"DCIM:INSTALLED#301_C_RAID.Mezzanine.
APIs "EndTime": null, "Schedule": "startNow", "State": "Enabled", "CreatedBy": "admin", "UpdatedBy": null, "LastRunStatus": { "Id": 2200, "Name": "NotRun" }, "JobType": { "Id": 5, "Name": "Update_Task", "Internal": false }, "JobStatus": { "Id": 2080, "Name": "New" }, "Targets": [ { "JobId": 25125, "Id": 25013, "Data": "DCIM:INSTALLED#301_C_RAID.Mezzanine.
APIs { "JobId": 25125, "Key": "complianceUpdate", "Value": "true" }, { "JobId": 25125, "Key": "signVerify", "Value": "true" }, { "JobId": 25125, "Key": "stagingValue", "Value": "false" } ], "Visible": true, "Editable": true, "Builtin": false } Monitoring Jobs to completion: GET on /api/JobService/Jobs to determine job status and monitor to completion.
Behavioral differences 4 Behavioral differences This section explains the behavioral differences between OpenManage Enterprise and OpenManage Enterprise – Modular after the firmware update operation. In OpenManage Enterprise – Modular auto-start of the inventory task is not done and it is initiated manually by clicking on “Check Compliance” in the UI The API workflow has a small change specific to OpenManage Enterprise – Modular.
Behavioral differences The equivalent action to clicking on “Check Compliance” is to issue a POST on /api/JobService/Actions/JobService.RunJobs with the payload specified below { "JobIds": [27734] } Once this completes the inventory will be refreshed and subsequent calls to check the compliance against /api/UpdateService/Baselines()/DeviceComplianceReports should succeed and indicate current status.
Technical support and resources A Technical support and resources Dell.com/support is focused on meeting customer needs with proven services and support. A.1 Related resources Provide a list of documents and other assets that are referenced in the paper; include other resources that may be helpful.
