POST /osImages

Use the POST method to create a job that can be used to import an OS image, device driver, boot file, and custom files (such as configuration settings, installation scripts, software, and unattend files), or to customize OS image profile.

This method returns the job ID, which you can then use with the POST /files/osImages?jobId=<job_id> method.

To import a new file, follow these steps:
  1. Start a job to import the file using POST /osImages.
  2. Import the file using POST /files/osImages?jobId=<job_id> method, where the job ID is the ID that was returned in step 1.
  3. Monitor the status of the import job using GET /tasks/<job_list>, where the job ID is the ID that was returned in step 1.

When you import an OS image, Lenovo XClarity Administrator creates one or more OS-image profiles in the OS image repository. The profile includes both the OS image and the installation options for that image.

Authentication

Authentication with user name and password is required.

Request URL

POST https://<management_server_IP>/osImages

Query parameters

Parameters Required / Optional Description
imageType=<type> Optional Imports an image of the specified type. 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)
Note: Unattend files and custom configuration-schema files are specific to a custom OS-image profile and are added and modified using PUT /hostPlatforms.
importByContent=<type> Optional When imageType is UNATTEND or CONFIG , indicates the type of import method to use. This can be one of the following values.
  • true. Import using this POST method to by specifying the file metadata and contents in the request body. A job will not be generated.

  • false. (default) Import using this POST method to create a job, and then using the POST /files/osImages?jobId=<job_id> method to import the file.

The following example starts a job to import an operating-system image.
POST https://192.0.2.0/osImages
The following example starts a job to import a device driver.
POST https://192.0.2.0/osImages?imageType=DUD
The following example starts a job to import a boot file.
POST https://192.0.2.0/osImages/?imageType=BOOT
The following example starts a job to import a customized OS image profile.
POST https://192.0.2.0/osImages?imageType=OSPROFILE
The following example starts a job to import a custom configuration-settings file without using a job and using this POST method to by specifying the file metadata and contents in the request body.
POST https://ajsga200.labs.lenovo.com/osImages?imageType=CUSTOM_CONFIG&importByContent=true

Request body

Table 1. Import by creating a job
Attributes Required / Optional Type Description
Action Required String This value must be init.
fileSize Optional String Size of the file to be imported (in bytes)
Table 2. Import by specifying metadata and content
Attributes Required / Optional Type Description
associatedFileId Optional String If imageType=CONFIG, this is the ID of the associated unattend file

If imageType=UNATTEND, this is the ID of the associated configuration-settings file.

content Required String Contents of the file to be imported

This cannot be null or an empty string.

description Optional String Description of the file
deviceType Optional String Type of device that is associated with the uploaded file. This can be one of the following values.
  • hba

  • nic

  • storage

  • other

fileSize Optional String Size of the file to be imported (in bytes)
name Optional String Name of the file
os Required String Operating system that is associated with the uploaded file. This can be one of the following values.
  • esxi

  • rhels

  • sles

  • win

Note: This attribute is ignore when imageType=CONFIG.
osrelease Required if imageType is UNATTEND String Operating-system release that is associated with the uploaded file
Note: This attribute is ignore when imageType=CONFIG.

Request example

This example creates a job that can be used to import a file using the POST /files/osImages?jobId=<job_id>.

{
   "Action": "Init",
   "fileSize": "338763776"
}
This example imports a file without using a job.
{
"content": [{
   "category": "dynamic",
   "content": [{
      "category": "dynamic",
      "common": false,
      "name": "server-settings",
      "optional": false,
      "template": [{
         "autoCreateInstance": true,
         "category": "dynamic",
         "common": false,
         "content": [{
            "category": "dynamic",
            "choices": ["en_US", "pt_BR", "ja_JP"],
            "common": false,
            "description": "This parameter defines the OS language locale to use with this deployment. 
                            English, Brazilian Portuguese, and Japanese are supported.",
            "label": "OS Locale",
            "name": "locale",
            "optional": false,
            "type": "string",
            "value": "en_US"
         },
         {
            "category": "dynamic",
            "choices": ["english-us", "pt_BR", "ja_JP"],
            "common": false,
            "description": "This parameter defines the keyboard locale to use with this deployment. 
                           English, Brazilian Portuguese, and Japanese are supported.",
            "label": "Keyboard Locale",
            "name": "keyboardLocale",
            "optional": false,
            "type": "string",
            "value": "english-us"
         }],
         "name": "server",
         "optional": false,
         "type": "assoc_array"
      }],
      "type": "assoc_array"
   },
   {
      "category": "dynamic",
      "common": true,
      "description": "NTP Servers",
      "label": "NTP Servers",
      "maxElements": 3,
      "minElements": 0,
      "name": "common-ntpservers",
      "optional": true,
      "template": [{
         "category": "dynamic",
         "common": true,
         "description": "A NTP Server",
         "label": "NTP Server",
         "name": "ntpserver",
         "optional": true,
         "regex": "[\\w\\.]{1,64}$",
         "type": "string"
      }],
      "type": "array"
   },
   {
      "category": "static",
      "common": true,
      "description": "Directory for post-installation script logging.",
      "name": "logpath",
      "optional": false,
      "type": "string",
      "value": "/tmp/mylogger.log"
   }],
   "description": "Custom configuration file for deployment of custom locale, NTP server, 
                   and directory for post-installation script logs.",
   "label": "My Custom Deployment",
   "name": "myCustomDeploy",
   "optional": false,
   "type": "array"
},
"description": "My file description."
"devicetype": "other"
"name": "myconfigfile.json"
"os": "win"
}

Response codes

Code Description
200 OK. The request completed successfully.
500 Internal server error. A descriptive error message is returned in the response body.

Response body

Attributes Type Description
jobId String ID for the job. This ID can be used by the POST /files/osImages?jobId=<job_id> method to import an image into the OS image repository.
Note: This attribute is returned only when a job is created.
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.
messages Array Information about one or more messages

If the result is successful, an empty array is returned.

  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

The following example is returned when a job is successfully created.

{
    "jobId": "1", 
    "result": "success",
    "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": "The management server supports a maximum of 5 imported operating system
                        images.", 
        "id": "FQXHMFC0057M", 
        "recovery": {
            "URL": "", 
            "text": "Delete an operating system image and attempt to import the image again."
        }
        "text": "The maximum number of imported operating systems has been reached.", 
    }]
}