PAWS Client¶

The PAWSClient provides access to Platform Administrative Web Services for hardware details, software versions, cluster topology, installed options, deployment mode, and upgrade/restart/switch-version operations.

Unlike the other SXML clients which use a single WSDL, PAWS consists of multiple independent SOAP services. The client lazily initializes each service on first use, so only the services you call will have their WSDLs fetched.

[!NOTE] PAWS requires platform/OS admin credentials.

Quick Example¶

from axltoolkit import PAWSClient

paws = PAWSClient(
    username="platformadmin",
    password="secret",
    server_ip="ucm-pub.example.com",
    tls_verify=True,
)

# Platform information
version = paws.get_active_version()
nodes = paws.get_cluster_nodes()
hw = paws.get_hardware_information()
model = paws.get_hardware_model()
mode = paws.get_deployment_mode()

# Upgrade operations
stage = paws.get_upgrade_stage()
valid = paws.is_upgrade_valid("UCSInstall_UCOS_14.0.1.zip")

Class Reference¶

axltoolkit.paws_client.PAWSClient ¶

PAWSClient(username: str, password: str, server_ip: str, *, tls_verify: Union[bool, str] = True, timeout: int = 30, max_retries: int = 3)

Bases: BaseClient

Client for Cisco UCM Platform Administrative Web Services (PAWS).

This client provides access to platform-level APIs that return information about the hardware, software, cluster topology, and installed options on UCM servers.

Unlike the AXL and SXML APIs which use a single WSDL, PAWS consists of multiple independent SOAP services. This client lazily initializes each service on first use, so only the services you call will have their WSDLs fetched.

Parameters:

Name	Type	Description	Default
`username`	`str`	Platform/OS Administration user name.	required
`password`	`str`	Platform password.	required
`server_ip`	`str`	UCM server IP address or FQDN.	required
`tls_verify`	`Union[bool, str]`	TLS verification setting (default `True`).	`True`
`timeout`	`int`	Request timeout in seconds (default 30).	`30`
`max_retries`	`int`	Retry count for transient failures (default 3).	`3`

Note

PAWS uses platform credentials (OS Administration), not AXL application user credentials.

get_hardware_information ¶

get_hardware_information() -> Dict[str, Any]

Retrieve hardware information from the UCM server.

Returns:

Type	Description
`Dict[str, Any]`	A dict containing hardware details (CPU, memory, disk, etc.).

Raises:

Type	Description
`PAWSError`	If the query fails.

Example::

hw = client.get_hardware_information()
print(hw)

get_active_version ¶

get_active_version() -> Dict[str, Any]

Retrieve the active software version of the UCM server.

Returns:

Type	Description
`Dict[str, Any]`	A dict with version information (activeServerVersion, etc.).

Raises:

Type	Description
`PAWSError`	If the query fails.

Example::

version = client.get_active_version()
print(version)

get_inactive_version ¶

get_inactive_version() -> Dict[str, Any]

Retrieve the inactive software version of the UCM server.

Returns:

Type	Description
`Dict[str, Any]`	A dict with inactive version information.

Raises:

Type	Description
`PAWSError`	If the query fails.

get_options ¶

get_options() -> Dict[str, Any]

Retrieve installed options/features on the UCM server.

Returns:

Type	Description
`Dict[str, Any]`	A dict with installed option information.

Raises:

Type	Description
`PAWSError`	If the query fails.

get_installed_products ¶

get_installed_products() -> Dict[str, Any]

Retrieve installed product information.

Returns:

Type	Description
`Dict[str, Any]`	A dict with installed product details.

Raises:

Type	Description
`PAWSError`	If the query fails.

get_inactive_options ¶

get_inactive_options() -> Dict[str, Any]

Retrieve installed options on the inactive partition.

Returns:

Type	Description
`Dict[str, Any]`	A dict with inactive option information.

Raises:

Type	Description
`PAWSError`	If the query fails.

get_product_name ¶

get_product_name() -> Dict[str, Any]

Retrieve the product name of the UCM server.

Returns:

Type	Description
`Dict[str, Any]`	A dict with product name information.

Raises:

Type	Description
`PAWSError`	If the query fails.

get_cluster_nodes ¶

get_cluster_nodes() -> Dict[str, Any]

Retrieve the list of nodes in the UCM cluster.

Returns:

Type	Description
`Dict[str, Any]`	A dict with cluster node information.

Raises:

Type	Description
`PAWSError`	If the query fails.

Example::

nodes = client.get_cluster_nodes()
print(nodes)

get_my_cluster_node ¶

get_my_cluster_node() -> Dict[str, Any]

Retrieve information about the cluster node being contacted.

Returns:

Type	Description
`Dict[str, Any]`	A dict with the current node's details (IP, hostname, etc.).

Raises:

Type	Description
`PAWSError`	If the query fails.

get_api_version ¶

get_api_version() -> Dict[str, Any]

Retrieve the PAWS API version.

Returns:

Type	Description
`Dict[str, Any]`	A dict with the API version information.

Raises:

Type	Description
`PAWSError`	If the query fails.

get_deployment_mode ¶

get_deployment_mode() -> Dict[str, Any]

Retrieve the deployment mode (Enterprise, HCS, or HCS-LE).

Returns:

Type	Description
`Dict[str, Any]`	A dict with the deployment mode and result code.

Raises:

Type	Description
`PAWSError`	If the query fails.

set_deployment_mode ¶

set_deployment_mode(mode: str) -> Dict[str, Any]

Set the deployment mode.

Parameters:

Name	Type	Description	Default
`mode`	`str`	One of `'Enterprise'`, `'HCS'`, or `'HCS-LE'`.	required

Returns:

Type	Description
`Dict[str, Any]`	A dict with the result code.

Raises:

Type	Description
`PAWSError`	If the operation fails.

get_hardware_model ¶

get_hardware_model() -> Dict[str, Any]

Retrieve the hardware model, serial number, and VM status.

Returns:

Type	Description
`Dict[str, Any]`	A dict with hardware model details.

Raises:

Type	Description
`PAWSError`	If the query fails.

prepare_remote_upgrade ¶

prepare_remote_upgrade(upgrade_file: Dict[str, Any], session_id: str, override_session: bool = False) -> Dict[str, Any]

Download and prepare an upgrade or COP file for installation.

This call should always be made asynchronously.

Parameters:

Name	Type	Description	Default
`upgrade_file`	`Dict[str, Any]`	A dict with keys `name`, `path`, `password`, `server`, `upgradeLocation`, `upgradeType`, `user`.	required
`session_id`	`str`	Unique session ID provided by the client.	required
`override_session`	`bool`	If `True`, overrides an existing session.	`False`

Returns:

Type	Description
`Dict[str, Any]`	A dict with the result, remote messages, and upgrade file info.

Raises:

Type	Description
`PAWSError`	If the operation fails.

start_upgrade ¶

start_upgrade(session_id: str, override_session: bool = False, auto_switch: bool = False) -> Dict[str, Any]

Start an upgrade or COP file installation.

This call should always be made asynchronously.

Parameters:

Name	Type	Description	Default
`session_id`	`str`	Unique session ID provided by the client.	required
`override_session`	`bool`	If `True`, overrides an existing session.	`False`
`auto_switch`	`bool`	If `True`, auto-switch to the new version on successful upgrade.	`False`

Returns:

Type	Description
`Dict[str, Any]`	A dict with the result and any remote messages.

Raises:

Type	Description
`PAWSError`	If the operation fails.

cancel_upgrade ¶

cancel_upgrade(session_id: str) -> Dict[str, Any]

Cancel an in-progress upgrade or COP file installation.

This call should always be made asynchronously.

Parameters:

Name	Type	Description	Default
`session_id`	`str`	The session ID associated with the upgrade.	required

Returns:

Type	Description
`Dict[str, Any]`	A dict with the result and any remote messages.

Raises:

Type	Description
`PAWSError`	If the operation fails.

get_upgrade_stage ¶

get_upgrade_stage() -> Dict[str, Any]

Retrieve the current overall upgrade/COP installation stage.

Returns:

Type	Description
`Dict[str, Any]`	A dict with the current upgrade stage (e.g. downloading,
`Dict[str, Any]`	validating, installing).

Raises:

Type	Description
`PAWSError`	If the query fails.

get_current_upgrade_progress_stage ¶

get_current_upgrade_progress_stage() -> Dict[str, Any]

Retrieve detailed progress for an in-progress upgrade.

Must be called after :meth:start_upgrade has been initiated.

Returns:

Type	Description
`Dict[str, Any]`	A dict with the detailed upgrade progress stage.

Raises:

Type	Description
`PAWSError`	If the query fails.

get_upgrade_type ¶

get_upgrade_type() -> Dict[str, Any]

Retrieve the type of the current upgrade (L2 or RU).

Can only be called after an upgrade has started.

Returns:

Type	Description
`Dict[str, Any]`	A dict with the upgrade type information.

Raises:

Type	Description
`PAWSError`	If the query fails.

is_upgrade_valid ¶

is_upgrade_valid(filename: str) -> Dict[str, Any]

Determine if the specified upgrade file is valid.

Parameters:

Name	Type	Description	Default
`filename`	`str`	The upgrade file name to validate.	required

Returns:

Type	Description
`Dict[str, Any]`	A dict with the result and `upgradeValid` boolean.

Raises:

Type	Description
`PAWSError`	If the query fails.

upgrade_filter ¶

upgrade_filter(upgrade_type: str, filenames: List[str]) -> Dict[str, Any]

Return a list of valid upgrade files from the provided list.

Parameters:

Name	Type	Description	Default
`upgrade_type`	`str`	The upgrade type (e.g. `'patch'`).	required
`filenames`	`List[str]`	A list of upgrade file names to filter.	required

Returns:

Type	Description
`Dict[str, Any]`	A dict with the result and valid upgrade files.

Raises:

Type	Description
`PAWSError`	If the query fails.

restart_system ¶

restart_system() -> Optional[Dict[str, Any]]

Reboot the system without switching partitions.

The server may reboot before the SOAP response can be returned, so the response may be None or incomplete. Use :meth:get_restart_system_status to check the reboot status.

Returns:

Type	Description
`Optional[Dict[str, Any]]`	A dict with the result and remote messages, or `None`
`Optional[Dict[str, Any]]`	if the server rebooted before responding.

Raises:

Type	Description
`PAWSError`	If the operation fails before reboot initiates.

get_restart_system_status ¶

get_restart_system_status() -> Dict[str, Any]

Retrieve the status of the last restart system call.

Returns:

Type	Description
`Dict[str, Any]`	A dict with the result and `restartSystemStatus`
`Dict[str, Any]`	(`internal.request.processing` or
`Dict[str, Any]`	`internal.request.complete`).

Raises:

Type	Description
`PAWSError`	If the query fails.

switch_versions ¶

switch_versions() -> Optional[Dict[str, Any]]

Switch the running software version to the upgrade version.

The server reboots as part of this operation; the response may not be received. Use :meth:get_switch_version_status to check the status.

Returns:

Type	Description
`Optional[Dict[str, Any]]`	A dict with the result and remote messages, or `None`
`Optional[Dict[str, Any]]`	if the server rebooted before responding.

Raises:

Type	Description
`PAWSError`	If the operation fails.

get_switch_version_status ¶

get_switch_version_status() -> Dict[str, Any]

Retrieve the status of the last switch version call.

Returns:

Type	Description
`Dict[str, Any]`	A dict with the result and `switchVersionStatus`
`Dict[str, Any]`	(`internal.request.processing` or
`Dict[str, Any]`	`internal.request.complete`).

Raises:

Type	Description
`PAWSError`	If the query fails.