POST /osImages

Use this 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:

Start a job to import the file using POST /osImages.
Import the file using POST /files/osImages?jobId={job_id} method, where the job ID is the ID that was returned in step 1.
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 username 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)

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

{
   "Action": "Init",
   "fileSize": "338763776"
}

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.

This following 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	Comments
200	OK	The request completed successfully.
403	Forbidden	The orchestrator server was prevented from fulfilling the request. A descriptive error message is returned in the response body. Ensure that you have privileges to perform the request. For XClarity Administrator advanced functions, ensure that you have active licenses for each managed server that supports the advanced functions.
500	Internal Server Error	An internal error occurred. 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

The following example is returned if the request is successful.

{
    "jobId": "1", 
    "result": "success",
    "messages": []
}

The following example is returned if the request is not successful.

{
    "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.", 
    }]
}

Give documentation feedback

POST /osImages

Authentication​

Request URL​

Query parameters​

Request body​

Response codes​

Response body​