POST /files/osImages?jobId=<job_id>

Use this POST method to import an OS image, OS image profile, device driver, boot file, or custom file (such as configuration settings, installation script, software, and unattend file) to the Lenovo XClarity Administrator OS images repository. Only the user that created the job has the permission to import a file using the job ID that was returned from that method.

Note: This API requires Lenovo XClarity Administrator v2.1.0 or later.

Before you can import , you must first create an import job using the POST /osImages method.

You can monitor the status of the import request using the GET /tasks/<job_list> method.

Note: The OS images repository can store up to ten operating-system images, if space is available to store the images (up to 50GB).
The following types of files can be imported based on the value specified for the imageType query parameter.
Image Type Supported File Type (extension)
BOOT For Linux and VMware, boot files are not supported.

For Windows, the boot files must be in the .zip format for WinPE.

BUNDLE For Linux and VMWare, bundle files are not supported.

For Windows, bundle files must be in the zip format.

Note: Only official bundle files that are released and signed by Lenovo are supported.
BUNDLESIG For Linux and VMWare, bundle signature files are not supported.

For Windows, bundle signature files must be in the asc format.

CONFIG JSON- formatted files are supported.
DUD For Linux, device drivers must be in the .iso or .rpm format. The .iso or .rpm file must contain a device driver in the Device Update Driver format.

For Windows, device drivers must be in the .zip format. The .zip file must contain a collection of raw device drivers in the .inf format.

For VMWare, device drivers are not supported.

OS All OS images must be in the .iso format.
OSPROFILE All profiles must be in the .tar.gz format.
SCRIPT For Linux, Bash (.sh), Perl (.pm or .pl), Python (.py) files are supported.

For Windows, Command file (.cmd), PowerShell (.ps1) files are supported.

For VMWare, installation scripts are not supported.

SOFTWARE For Linux, archive .tar.gz files are supported.

For Windows, archive.zip files are supported.

UNATTEND For Linux, Kickstart (.ks) and AutoYast (.xml) files are supported.

For Windows, Unattend .xml files are supported.

For VMWare, installation scripts are not supported.

Authentication

Authentication with user name and password is required.

Request URL

POST https://<management_server_IP>/files/osImages?jobId=<job_id>

where <job_id> is a ID of the import job that is returned by the POST /osImages method.

Query parameters

Parameters Required / Optional Description
jobID=<job_id> Required ID of the job that was created to import files using the last POST /osImages method
checksumType=<type> Optional Specify the type of checksum to be used. This can be one of the following values.
  • MD5
  • SHA1
  • SHA256

It is added as an item of the multi-part body.

checksumValue=<value> Optional Checksum string of the .ISO file. It is added as an item of the multi-part body
imageName=<name> Required Name of the OS image to which you want to add the device driver (for example, redhat7.0)
Note: The operating-system image must exist in the OS images repository.
imageType=<type> Required Type of image being imported. This can be one of the following values.
  • BOOT. Boot-options file. This is available for only customized Windows operating-system profiles.
  • BUNDLE. Bundle file (in .zip format). This is available for only customized Windows operating-system profiles.
  • BUNDLESIG. Bundle signature files (in .asc format). This is available for only customized Windows operating-system profiles.
  • CONFIG. Configuration-settings file (in JSON format)
  • DUD. Device driver. This is available for customized Windows and Linux operating-system profiles.
  • OS. (default) OS image
  • OSPROFILE. Customized OS image profile
  • SCRIPT. Installation-script file
  • SOFTWARE. Archive file (in .zip or .tar.gz format) that encapsulates the post-install software payload
  • UNATTEND. Unattend file (in kickstart .cfg, autoyast .xml, or Windows .xml format)
os=<os_type> Required when imageType is "BOOT," "CONFIG,""DUD," "SCRIPT," "SOFTWARE," or "UNATTEND" Operating system that is associated with the uploaded file. This can be one of the following values.
  • esxi

  • rhels

  • sles

  • win

path=<os_path> Optional Full path to the OS image on the remote file server
Note: This attribute is applicable only when serverId is specified.
serverId=<profile_id> Optional Profile ID for the remote file server
Tip: To obtain the profile ID, use the GET /osImages method.
The following example imports an OS image using job ID 1.
POST https://192.0.2.0/files/osImages?jobId=1
The following example imports a device driver for Red Hat v7.0 using job ID 4.
POST https://192.0.2.0/files/osImages?jobId=4&imageType=DUD&os=RHEL&imageName=redhat7.0
The following example imports a boot file for Windows using job ID 5.
POST https://192.0.2.0/files/osImages?jobId=4&imageType=BOOT&os=windows
The following example imports a customized OS image profile using job ID 22.
POST https://192.0.2.0/files/osImages?jobId=22&imageType=OSPROFILE

Request body

Use the "multipart/form-data" media type to import the ISO image. Use the attributes in the following table as the multipart name in the body. For more information about the multipart/form-data media type, see Returning Values from Forms: multipart/form-data webpage.

Request example

HTTP Header
Content-Type: multipart/form-data; boundary=AaB03x
Request body
--AaB03x
    Content-Disposition: form-data; name="checksumType"
    MD5
    --AaB03x
    Content-Disposition: form-data; name="checksumValue"
    DE232312323SXZEW3JDOIWOZLSWJWQ
    --AaB03x
    Content-Disposition: form-data; name="uploadedfile"; filename="redhat7.0.iso"
    Content-Type: application/octet-stream 
    ... {contents of redhat7.0.iso} ...
    --AaB03x--

Response codes

Code Description
201 OK. The OS image was imported successfully.
409 Conflict. The current state of the resource conflicts with the current request. Wait until the state is valid, and attempt the request again.
412 Precondition failed. The specified image type is not supported for import.
500 Internal server error. An internal error occurred.

Response body

Attributes Type Description
result String Result of the request. This can be one of the following values.
  • success. The request completed successfully.
  • failed. The request failed. A descriptive error message was returned.
  fileid String Identifier of the file that was successfully imported
messages Array Information about one or more messages
  explanation String Additional information to clarify the reason for the message
  id String Message identifier of a returned message
  recovery Array Recovery information
    text String User actions that can be taken to recover from the event
    URL String Link to the help system for more information, if available
  text String Message text associated with the message identifier

Response example

When the request is successful (response code of 201), a message body similar to the following is returned:

Note: If the request is successful, you can use the GET /tasks/<job_list> resource to monitor the progress of the deployment.
{
   "result": "success",
   "fileid": "2016120682241_WinPE_64.wim",
   "messages":[]
}

When the request is not successful (such as a response code of 409), a message body similar to the following is returned:

{
    "result": "failed",
    "messages": [{
        "explanation": "This issue can occur because of network issues or because the wrong
                        checksum file is in the directory.", 
        "id": "FQXHMFC0001M", 
        "text": "The checksum of the imported ISO image does not match the provided checksum
                 file.", 
        "recovery": {
            "URL": "", 
            "text": "Make sure that the checksum file matches the ISO image and attempt the
                     operation again. If the problem persists, contact Support."
        }
    }]
}