Cisco DCNM Web Services API Guide, Release 4.2
ImageInstallApp Service
Downloads: This chapterpdf (PDF - 108.0KB) The complete bookPDF (PDF - 7.93MB) | Feedback

ImageInstallApp Service

Table Of Contents

ImageInstallApp Service

Information About ImageInstallApp Service

abortJob

abortTask

createJob

deleteJob

fetchDiskFreeSpace

fetchDiskFreeSpaceFromStandbySup

getAllInstallTasks

getAllJobs

getFailureLog

getJob

getStatusOfJobInNetworkElement

modifyJob

performVersionCompatability

resumeJob

suspendJob


ImageInstallApp Service


This chapter describes the DCNM web services' API methods for the ImageInstallApp service.

Information About ImageInstallApp Service

The ImageManagement component allows you to upgrade the devices with the latest images with nondisruptive (dual supervisor devices) and disruptive (single supervisor devices) modes. The ImageInstallJob may contain more than one ImageInstallTask. One ImageInstallTask corresponds to one device within a job. If the device is deleted from the server, all of its corresponding tasks get deleted. ImageInstallApp interface defines the various APIs that handle the image upgrade process.

abortJob

This API is used to abort(delete) the jobs which are scheduled for image upgradation before execution of the job .

ValidationException is thrown if any of the following situation occurs:

If jobIdList collection is null or it is empty.

If jobIdList collection contains an element that is not of type ImageInstallJob InstanceNameId.

If jobIdList collection contains a ImageInstallJob that does not exist in the database.

ImageInstallException is thrown if any of the following situation occurs:

If the user is trying to abort the currently running ImageInstallJob object

Parameters

opContext—Operational context

jobIdList—jobIdList is the list of jobs info which the user is going to abort.

Return Value

void

abortTask

This API is used to abort the selected installation task from the job. (One job may contain more than one tasks.)

ValidationException is thrown if any of the following situation occurs:

If installTaskCol collection is null or it is empty.

If installTaskCol collection contains an element that is not of type ImageInstallTask InstanceNameId.

If installTaskCol collection contains a ImageInstallTask that does not exist in the database.

Parameters

opContext—Operational context

installTaskCol—taskcol is list of tasks which the user is going to abort from the job.

Return Value

void

createJob

This API is used to schedule a new job for image upgradation. Creates jobInstance. Job cannot be created without ImageInstallTask association. One ImageInstallJob may contain more than one ImageInstallTask.One ImageInstallTask corresponds to one device with in a job.

Following associations are to be provided for the given ImageInstallJob:

1. ImageInstallTaskReference corresponding to the specified ImageInstallJob. ImageInstallTask reference

2. AbstractNetworkElementReference corresponding to the specified ImageInstallTask AbstractNetworkElement reference

ValidationException is thrown if any of the following situation occurs:

If newJobInfoCol is null or empty.

If elements in newJobInfoCol is not a valid type of ImageInstallJOb or with ImageInstallTask reference not specified.

IntegrityException is thrown if any of the following situation occurs:

If a Job with same jobId already exist.

Parameters

opContext—Operational context

newJobInfoCol—List of ImageInstallJob objects to be created.

Return Value

List of InstanceNameId corresponding to the newly created ImageInstallJob.

deleteJob

This API is used to delete the scheduled job. Deletes the job objects corresponding to the given list of InstanceNameId. The corresponding ImageInstallJob and its associations will be deleted.

ValidationException is thrown if any of the following situation occurs:

If jobIdList collection is null or it is empty.

If jobIdList collection contains an element that is not of type ImageInstallJob InstanceNameId.

If jobIdList collection contains a ImageInstallJob that does not exist in the database.

If the user is trying to delete the currently running job

ImageInstallException is thrown if any of the following situation occurs:

If the user is trying to delete the currently running ImageInstallJob object

Parameters

opContext—Operational context

jobIdList—is the List of jobs that needs to be deleted.

Return Value

void

fetchDiskFreeSpace

This API is used to know the free avialable disk space in bootflash.

Parameters

opContext—Operational context

neInstanceNameId—neInstanceNameId is the InstanceNameId for a given network element.

Return Value

List free availble disk space.

fetchDiskFreeSpaceFromStandbySup

This API is used to know the free avialable disk space in bootflash for standby.

Parameters

opContext—operational context

neInstanceNameId—neInstanceNameId is the InstanceNameId for a given network element.

Return Value

List free availble disk space for the given devices.

getAllInstallTasks

This API is used to fetch all the ImageInstalltionTask objects for the given Network Element.If null is passed for network Element InstanceNameId return all the list of ImageInstallTask objects.

ValidationException is thrown if any of the following situation occurs:

If neInstanceNameId is not InstanceNameId of AbstractNetworkElement.

If the corresponding object for neInstanceNameId does not exist.

Parameters

opContext—Operational context

Return Value

List list of installtasks.

getAllJobs

This API is used to get the ImageInstallJob objects corresponding to a status passed as a parameter. If the status passed is null then the all ImageInstalljob objects will be returned irrespective of the status.

Parameters

opContext—Operational context

aInstallationStatus—aInstallationStatus is the status which the user needs the list of jobInfo aInstallationStatus might be any of the following: 1)InstallationStatus.COMPLETED return all the list of completed jobs. 2)InstallationStatus.RUNNING return all the list of active jobs. 3)InstallationStatus.SCHEDULED return all the list of pending jobs.

Return Value

List list of all the installJobs of specified status type.

getFailureLog

Returns the failure log for a job collection.

Parameters

opContext—Operational context

jobCol—List of InstanceNameId for jobs.

Return Value

List of failure logs.

getJob

This API is used to get the specific job and corresponding task details.

Parameters

opContext—Operational context

jobNameId—InstanceNameId of the job

Return Value

ImageInstallJob specific(jobNameId) job and correspomding task details.

getStatusOfJobInNetworkElement

This API is used to get last completed job or current job status for a given NetworkElement. If no current or last completed jobs found in the given network element, API returns null.

ValidationException is thrown if any of the following situation occurs:

If neInstanceNameId is null or not an InstanceNameId of AbstractNetworkElement.

Parameters

opContext—Operational context

neInstanceNameId—neInstanceNameId is the InstanceNameId for a given network element.

aInstallationStatus—If null is passed for aInstallationStatus,return last completed job status for a given network element. If InstallationStatus.Running is passed for anstallationStatus, return the current job status for a given networkelement.

Return Value

InstallationStatus, last completedjob or current job status for a given network element.

modifyJob

This API is used to Modifies the scheduled job with modified job info. Modify attributes for ImageInstallJob instances. User cannot modify the jobId. User can update the scheduleTime and also can update the ImageInstallTask association.That is user can add or delete the ImageInstallTask from the given ImageInstallJob instance.

ValidationException is thrown if any of the following situation occurs:

If the modifiedJobInfo is null

If the corresponding ImageInstallJob object does not have equivalent persisted IamgeInstallJob object.

PropertiesException is thrown if any of the following situation occurs:

If any of the IamgeInstallJob attribute is not valid.

ImageInstallException is thrown if any of the following situation occurs:

If the user is trying to modify the currently running ImageInstallJob object

Parameters

opContext—Operational context

modifiedJobInfo—modifiedJobInfoCol is the modifiedInfo of the scheduled jobs.

Return Value

void

performVersionCompatability

This API is used to get the version compatibility log info between kickstart and system images. For example if the specified kickstart and system images not compatible(belonging to different versions) API return log info contain the log messages will be as following. "Install has failed. Return code 0x40930024 (Images specified are not upgradeable). Please identify the cause of the failure, and try 'install all' again."

ValidationException is thrown if any of the following situation occurs:

If neIdCol collection is null or it is empty.

If neIdCol collection contains an element that is not of type AbstractNetworkElement InstanceNameId.

If taskCol collection is null or it is empty.

If taskCol collection contains an element that is not of type ImageInstallTask InstanceNameId.

If jobCol collection is null or it is empty.

If jobCol collection contains an element that is not of type ImageInstallJob InstanceNameId.

Parameters

opContext—Operational context

neIdCol—InstanceNameId of the network elements

taskCol—is the collection of ImageInstallTask objects

jobCol—is the collection of ImageInstallJob objects

Return Value

List is the log information ,by specifying whether both the kickstart and system images are compatible or not.

resumeJob

This API is used to resume the job which is suspended form the execution

ValidationException is thrown if any of the following situation occurs:

If jobIdList collection is null or it is empty.

If jobIdList collection contains an element that is not of type ImageInstallJob InstanceNameId.

If jobIdList collection contains a ImageInstallJob that does not exist in the database.

ImageInstallException is thrown if any of the following situation occurs:

If the user is trying to resume the unsuspended ImageInstallJob object

Parameters

opContext—Operational context

jobIdList—jobIdList is jobs info which the user is going to resume.

Return Value

void

suspendJob

This API is used to suspend(stop) the jobs form the execution and may resume some time later

ValidationException is thrown if any of the following situation occurs:

If jobIdList collection is null or it is empty.

If jobIdList collection contains an element that is not of type ImageInstallJob InstanceNameId.

If jobIdList collection contains a ImageInstallJob that does not exist in the database.

ImageInstallException is thrown if any of the following situation occurs:

If the user is trying to suspend the currently running ImageInstallJob object

Parameters

opContext—Operational context

jobIdList—jobIdList is jobs info which the user is going to suspend.

Return Value

void