7. WBEM subscription manager

New in pywbem 0.9 as experimental and finalized in 0.10.

The WBEM subscription manager API supports viewing and managing subscriptions for indications on a WBEM server.

See WBEM indication listener for the API for creating and managing a WBEM listener.

7.1. WBEMSubscriptionManager

New in pywbem 0.9 as experimental and finalized in 0.10.

The WBEMSubscriptionManager class is a subscription manager that provides for creating and removing indication subscriptions (including indication filters and listener destinations) for multiple WBEM servers and multiple WBEM listeners and for getting information about existing indication subscriptions.

The SubscriptionManager only manages CIM/XML listener destinations and does not view, add, or remove other destinations such as files, etc.

The CIM/XML WBEM listener is identified through its URL, so it may be the pywbem listener (that is, a WBEMListener object) or any other WBEM listener.

This subscription manager supports three types of ownership of the CIM instances in WBEM servers that represent subscriptions, filters and listener destinations:

Owned

Owned CIM instances are created via the subscription manager and their life cycle is bound to the life cycle of the registration of that WBEM server with the subscription manager via add_server().

Owned CIM instances are deleted automatically when their WBEM server is deregistered from the subscription manager via remove_server() or remove_all_servers(). In addition, they can be deleted by the user via the removal methods of the WBEMSubscriptionManager class.
Permanent

Permanent CIM instances are created via the subscription manager and their life cycle is independent of the life cycle of the registration of that WBEM server with the subscription manager.

Permanent CIM instances are not deleted automatically when their WBEM server is deregistered from the subscription manager. The user is responsible for their lifetime management: They can be deleted via the removal methods of the WBEMSubscriptionManager class.
Static

Static CIM instances pre-exist in the WBEM server and cannot be deleted (or created) by a WBEM client.

If a client creates a subscription between a filter and a listener destination, the types of ownership of these three CIM instances may be arbitrarily mixed, with one exception:

A permanent subscription cannot be created on an owned filter or an owned listener destination. Allowing that would prevent the automatic life cycle management of the owned filter or listener destination by the subscription manager. This restriction is enforced by the WBEMSubscriptionManager class.

The WBEMSubscriptionManager object remembers owned subscriptions, filters, and listener destinations. If for some reason that object gets deleted before all servers could be removed (e.g. because the Python program aborts or the client is terminated), the corresponding CIM instances in the WBEM server still exist, but the knowledge is lost that these instances were owned by that subscription manager. Therefore, the subscription manager discovers owned subscriptions, filters, and listener destinations when a server is added. For this discovery, is based upon the Name property. Therefore, if the Name property is set by the user (e.g. because a management profile requires a particular name), the filter must be permanent and cannot be owned.

Since WBEMSubscriptionManager does not directly modify existing instances of filter or destinations or subscriptions, the user must do this directly through the ModifyInstance WBEM request method and then update the local owned instances list by executing get_all_filters(), get_all_destinations(), or get_all_subscriptions().

7.1.1. Examples

The following example code demonstrates the use of a subscri tion manager to subscribe for a CIM alert indication on a WBEM server. The WBEM listener is assumed to exist somewhere and is identified by its URL:

from pywbem import WBEMConnection, WBEMServer, WBEMSubscriptionManager

server_url = 'http://myserver'
server_credentials = ('myuser', 'mypassword')

listener_url = 'http://mylistener'

conn = WBEMConnection(server_url, server_credentials)
server = WBEMServer(conn)
sub_mgr = WBEMSubscriptionManager(subscription_manager_id='fred')

# Register the server in the subscription manager:
server_id = sub_mgr.add_server(server)

# Add a listener destination in the server:
dest_inst = sub_mgr.add_destination(
    server_id, listener_url, owned=True, destination_id='id1')

# Subscribe to a static filter of a given name:
filter1_name = "DMTF:Indications:GlobalAlertIndicationFilter"
filter1_insts = sub_mgr.get_all_filters(server_id)
for inst in filter1_insts:
    if inst['Name'] == filter1_name:
        sub_mgr.add_subscriptions(server_id, inst.path, dest_inst.path)
        break

# Create a dynamic alert filter and subscribe to it:
filter2_source_ns = "root/cimv2"
filter2_query = "SELECT * FROM CIM_AlertIndication " \
                "WHERE OwningEntity = 'DMTF' " \
                "AND MessageID LIKE 'SVPC0123|SVPC0124|SVPC0125'"
filter2_language = "DMTF:CQL"
filter2_inst = sub_mgr.add_filter(
    server_id, filter2_source_ns, filter2_query, filter2_language,
    owned=True, filter_id="myalert")
sub_mgr.add_subscriptions(server_id, filter2_inst.path, dest_inst.path)

The following example code briefly shows how to use a subscription manager as a context manager, in order to get automatic cleanup of owned instances:

with WBEMSubscriptionManager('fred') as sub_mgr:
    server_id = sub_mgr.add_server(server)
    . . .
# The exit method automatically calls remove_all_servers(), which deletes
# all owned subscription, filter and destination instances in the servers
# that were registered.

The Tutorial section contains a tutorial about the subscription manager.

class pywbem.WBEMSubscriptionManager(subscription_manager_id)[source]

New in pywbem 0.9 as experimental and finalized in 0.10.

A class for managing subscriptions for CIM indications in a WBEM server.

The class may be used as a Python context manager, in order to get automatic clean up (see __exit__()).

Parameters:

subscription_manager_id (string) –

A subscription manager ID string that is used as a component in the value of the Name property of indication filter and listener destination instances and thus allows identifying these instances in a WBEM server.

Must not be None.

The string must consist of printable characters, and must not contain the character ‘:’ because that is the separator between components within the value of the Name property.

Raises:

ValueError – Incorrect input parameter values.
TypeError – Incorrect input parameter types.

Methods:

`__enter__`()	New in pywbem 0.10.
`__exit__`(exc_type, exc_value, traceback)	New in pywbem 0.10.
`__repr__`()	Return a representation of the `WBEMSubscriptionManager` object with all attributes, that is suitable for debugging.
`__str__`()	Return a representation of the `WBEMSubscriptionManager` object with a subset of its attributes.
`add_destination`(server_id, listener_url[, ...])	Add a listener destination to be the target of indications sent by a WBEM server, by creating an instance of CIM class "CIM_ListenerDestinationCIMXML" in the Interop namespace of the server.
`add_filter`(server_id, source_namespaces, query)	Add a dynamic indication filter to a WBEM server, by creating an indication filter instance (of CIM class "CIM_IndicationFilter") in the Interop namespace of the server.
`add_server`(server)	Register a WBEM server with the subscription manager.
`add_subscriptions`(server_id, filter_path[, ...])	Add subscriptions to a WBEM server for a particular set of indications defined by an indication filter and for a particular set of WBEM listeners defined by the instance paths of their listener destinations, by creating indication subscription instances (of CIM class "CIM_IndicationSubscription") in the Interop namespace of that server.
`get_all_destinations`(server_id)	Return all listener destinations in a WBEM server.
`get_all_filters`(server_id)	Return all indication filters in a WBEM server.
`get_all_subscriptions`(server_id)	Return all indication subscriptions in a WBEM server.
`get_owned_destinations`(server_id)	Return the listener destinations in a WBEM server owned by this subscription manager.
`get_owned_filters`(server_id)	Return the indication filters in a WBEM server owned by this subscription manager.
`get_owned_subscriptions`(server_id)	Return the indication subscriptions in a WBEM server owned by this subscription manager.
`remove_all_servers`()	Remove all registered WBEM servers from the subscription manager.
`remove_destinations`(server_id, destination_paths)	Remove listener destinations from a WBEM server, by deleting the listener destination instances in the server.
`remove_filter`(server_id, filter_path)	Remove an indication filter from a WBEM server, by deleting the indication filter instance in the WBEM server.
`remove_server`(server_id)	Remove a registered WBEM server from the subscription manager.
`remove_subscriptions`(server_id, sub_paths)	Remove indication subscription(s) from a WBEM server, by deleting the indication subscription instances in the server.

__enter__()[source]

New in pywbem 0.10.

Enter method when the class is used as a context manager. Returns the subscription manager object

__exit__(exc_type, exc_value, traceback)[source]

New in pywbem 0.10.

Exit method when the class is used as a context manager.

It cleans up by calling remove_all_servers().

__repr__()[source]: Return a representation of the WBEMSubscriptionManager object with all attributes, that is suitable for debugging.

__str__()[source]: Return a representation of the WBEMSubscriptionManager object with a subset of its attributes.

add_destination(server_id, listener_url, owned=True, destination_id=None, name=None, persistence_type=None)[source]

Add a listener destination to be the target of indications sent by a WBEM server, by creating an instance of CIM class “CIM_ListenerDestinationCIMXML” in the Interop namespace of the server.

The Name property of the created listener destination instance can be set in one of two ways:

directly by specifying the name parameter.

In this case, the Name property is set directly to the name parameter.

This should be used in cases where the user needs to have control over the destination name (e.g. because a DMTF management profile requires a particular name).

The name parameter can only be specified for permanent destinations.
indirectly by specifying the destination_id parameter.

In this case, the value of the Name property will be:

"pywbemdestination:" {submgr_id} ":" {destination_id}

where:
- {submgr_id} is the subscription manager ID
- {destination_id} is the value of the destination_id parameter
The destination_id parameter can only be specified for owned destinations.

If an owned listener destination instance for the specified listener URL and PersistenceType already exists, it is returned without creating a new instance.

If a listener destination instance with the specified or generated Name property already exists, the method raises CIMError(CIM_ERR_ALREADY_EXISTS). Note that this is a more strict behavior than what a WBEM server would do, because the Name property is only one of four key properties.

Parameters:

server_id (string) – The server ID of the WBEM server, returned by add_server().
listener_url (string) –
The URL of the WBEM listener that should receive the indications.

The WBEM listener may be a WBEMListener object or any external WBEM listener.

The listener URL string must have the format:

[{scheme}://]{host}:{port}

The following URL schemes are supported:
- https: Causes HTTPS to be used.
- http: Causes HTTP to be used. This is the default
The host can be specified in any of the usual formats:
- a short or fully qualified DNS hostname
- a literal (= dotted) IPv4 address
- a literal IPv6 address, formatted as defined in RFC3986 with the extensions for zone identifiers as defined in RFC6874, supporting - (minus) for the delimiter before the zone ID string, as an additional choice to %25.
The port is required in the listener URL.

See WBEMConnection for examples of valid URLs, with the caveat that the port in server URLs is optional.
owned (bool) – Defines the ownership type of the created listener destination instance: If True, it will be owned. Otherwise, it will be permanent. See WBEMSubscriptionManager for details about these ownership types.
destination_id (string) –
A destination ID string that is used as a component in the value of the Name property of owned destination instances to help the user identify these instances in a WBEM server, or None if the name parameter is specified.

The string must consist of printable characters, and must not contain the character ‘:’ because that is the separator between components within the value of the Name property.

This parameter is required for owned destinations and is rejected for permanent destinations.
name (string) –
The destination name to be used directly for the Name property of permanent destination instances, or None if the destination_id parameter is specified.

This parameter is required for permanent destinations and is rejected for owned destinations.
persistence_type (string) –
Optional string where the allowed strings are “transient” and “permanent” and the default is None. The strings are used to set the PersistenceType property, an integer property with the values of 2 (Permanent) or 3 (Transient)

The default value is None so that the PersistenceType property is not created on the destination instance for permanent filters. and is created with PersistenceType 3 (Transient) for owned destinations.

Most WBEM servers set the PersistenceType value to 2 (Permanent) if no value is provided.

This method does not provide for adding the OtherPersistenceType property.

Returns:

The created listener destination instance for the defined listener URL.

Return type:

CIMInstance

:raises Exceptions raised by WBEMConnection.: :raises CIMError(CIM_ERR_ALREADY_EXISTS): A filter with the specified or generated Name property already exists in the server. :raises ValueError: Incorrect input parameter values.

add_filter(server_id, source_namespaces, query, query_language='WQL', owned=True, filter_id=None, name=None, source_namespace=None)[source]

Add a dynamic indication filter to a WBEM server, by creating an indication filter instance (of CIM class “CIM_IndicationFilter”) in the Interop namespace of the server.

The Name property of the created filter instance can be set in one of two ways:

directly by specifying the name parameter.

In this case, the Name property is set directly to the name parameter.

This should be used in cases where the user needs to have control over the filter name (e.g. because a DMTF management profile requires a particular name).

The name parameter can only be specified for permanent filters.
indirectly by specifying the filter_id parameter.

In this case, the value of the Name property will be:

"pywbemfilter:" {submgr_id} ":" {filter_id}

where:
- {submgr_id} is the subscription manager ID
- {filter_id} is the filter ID
The filter_id parameter can only be specified for owned filters.

If an indication filter instance with the specified or generated Name property already exists, the method raises CIMError(CIM_ERR_ALREADY_EXISTS). Note that this is a more strict behavior than what a WBEM server would do, because the Name property is only one of four key properties.

Parameters:

server_id (string) – The server ID of the WBEM server, returned by add_server().
source_namespaces (string, list of string, or None) – Source namespace or list of source namespaces of the indication filter. The values will be inserted into the CIM_IndicationFilter SourceNamespaces property. If None, the SourceNamespaces property will not be created. and the WBEM server will use the Interop namespace as the source namespace for the indication filter.
query (string) – Filter query in the specified query language.
query_language (string) –
Query language for the specified filter query.

Examples: ‘WQL’, ‘DMTF:CQL’.
owned (bool) – Defines the ownership type of the created indication filter instance: If True, it will be owned. Otherwise, it will be permanent. See WBEMSubscriptionManager for details about these ownership types.
filter_id (string) –
A filter ID string that is used as a component in the value of the Name property of filter instances to help the user identify these instances in a WBEM server, or None if the name parameter is specified.

The string must consist of printable characters, and must not contain the character ‘:’ because that is the separator between components within the value of the Name property.

This parameter is required for owned filters and is rejected for permanent filters.

There is no requirement that the filter ID be unique. This can be used to identify groups of filters by using the same value for multiple filters.
name (string) –
New in pywbem 0.10.

The filter name to be used directly for the Name property of the filter instance, or None if the filter_id parameter is specified.

This parameter is required for permanent filters and is rejected for owned filters.
source_namespace (string) – Optional source namespace of the indication filter. If the parameter is provided the value will be inserted into the CIM_IndicationFilter SourceNamespace property. Otherwise the SourceNamespace property will not be created. The SourceNamespace property is deprecated in the DMTF CIM_IndicationFilter class in favor of SourceNamespaces (see the SourceNamespaces parameter above). This parameter is provided only to support calls to add_filter() that use the source_namespace as a keyword parameter or to support very old WBEM servers (prior to DMTF schema version 2.22) that require the SourceNamespace property.

Returns:

The created indication filter instance.

Return type:

CIMInstance

:raises Exceptions raised by WBEMConnection.: :raises CIMError(CIM_ERR_ALREADY_EXISTS): A filter with the specified or generated Name property already exists in the server. :raises ValueError: Incorrect input parameter values. :raises TypeError: Incorrect input parameter types.

add_server(server)[source]

Register a WBEM server with the subscription manager. This is a prerequisite for adding listener destinations, indication filters and indication subscriptions to the server.

This method discovers listener destination, indication filter, and subscription instances in the WBEM server owned by this subscription manager, and registers them in the subscription manager as if they had been created through it.

In this discovery process, listener destination and indication filter instances are matched based upon the value of their Name property. Subscription instances are matched based upon the ownership of the referenced destination and filter instances: If a subscription references a filter or a destination that is owned by this subscription manager, it is considered owned by this subscription manager as well.

Parameters:: server (WBEMServer) – The WBEM server.
Returns:: An ID for the WBEM server, for use by other methods of this class.
Return type:: string

:raises Exceptions raised by WBEMConnection.: :raises ValueError: Incorrect input parameter values. :raises TypeError: Incorrect input parameter types.

add_subscriptions(server_id, filter_path, destination_paths=None, owned=True)[source]

Add subscriptions to a WBEM server for a particular set of indications defined by an indication filter and for a particular set of WBEM listeners defined by the instance paths of their listener destinations, by creating indication subscription instances (of CIM class “CIM_IndicationSubscription”) in the Interop namespace of that server.

The specified indication filter may be owned, permanent or static.

The specified listener destinations may be owned, permanent or static.

When creating permanent subscriptions, the indication filter and the listener destinations must not be owned.

Owned subscriptions are added conditionally: If the subscription instance to be added is already registered with this subscription manager and has the same path, it is not created or modified. In that case, the instance already registered is returned. This method does not modify subscriptions.

Permanent subscriptions are created unconditionally, and it is up to the user to ensure that such an instance does not exist yet.

Upon successful return of this method, the added subscriptions are active, so that the specified WBEM listeners may immediately receive indications.

Parameters:

server_id (string) – The server ID of the WBEM server, returned by add_server().
filter_path (CIMInstanceName) – Instance path of the indication filter instance in the WBEM server that specifies the indications to be sent.
destination_paths (CIMInstanceName or list of CIMInstanceName) –
Instance paths of the listener destination instances in the WBEM server that specify the target WBEM listener.

If None, subscriptions will be created for all owned listener destinations registered to this subscription manager.
owned (bool) – Defines the ownership type of the created subscription instances: If True, they will be owned. Otherwise, they will be permanent. See WBEMSubscriptionManager for details about these ownership types.

Returns:

The indication subscription instances created in the WBEM server or the instance already in the WBEM server if the new instance is owned and there is already an owned subscription with the same path.

Return type:

list of CIMInstance

:raises Exceptions raised by WBEMConnection.: :raises ValueError: Incorrect input parameter values.

get_all_destinations(server_id)[source]

Return all listener destinations in a WBEM server.

This function contacts the WBEM server and retrieves the listener destinations by enumerating the instances of CIM class “CIM_ListenerDestinationCIMXML” in the Interop namespace of the WBEM server.

Parameters:: server_id (string) – The server ID of the WBEM server, returned by add_server().
Returns:: The listener destination instances.
Return type:: list of CIMInstance

:raises Exceptions raised by WBEMConnection.:

get_all_filters(server_id)[source]

Return all indication filters in a WBEM server.

This function contacts the WBEM server and retrieves the indication filters by enumerating the instances of CIM class “CIM_IndicationFilter” in the Interop namespace of the WBEM server.

Parameters:: server_id (string) – The server ID of the WBEM server, returned by add_server().
Returns:: The indication filter instances.
Return type:: list of CIMInstance

:raises Exceptions raised by WBEMConnection.:

get_all_subscriptions(server_id)[source]

Return all indication subscriptions in a WBEM server.

This function contacts the WBEM server and retrieves the indication subscriptions by enumerating the instances of CIM class “CIM_IndicationSubscription” in the Interop namespace of the WBEM server.

Parameters:: server_id (string) – The server ID of the WBEM server, returned by add_server().
Returns:: The indication subscription instances.
Return type:: list of CIMInstance

:raises Exceptions raised by WBEMConnection.:

get_owned_destinations(server_id)[source]

Return the listener destinations in a WBEM server owned by this subscription manager.

This function accesses only the local list of owned destinations; it does not contact the WBEM server. The local list of owned destinations is discovered from the WBEM server when the server is registered with the subscription manager, and is maintained from then on as changes happen through this subscription manager.

Parameters:: server_id (string) – The server ID of the WBEM server, returned by add_server().
Returns:: The listener destination instances.
Return type:: list of CIMInstance

get_owned_filters(server_id)[source]

Return the indication filters in a WBEM server owned by this subscription manager.

This function accesses only the local list of owned filters; it does not contact the WBEM server. The local list of owned filters is discovered from the WBEM server when the server is registered with the the subscription manager, and is maintained from then on as changes happen through this subscription manager.

Parameters:: server_id (string) – The server ID of the WBEM server, returned by add_server().
Returns:: The indication filter instances.
Return type:: list of CIMInstance

get_owned_subscriptions(server_id)[source]

Return the indication subscriptions in a WBEM server owned by this subscription manager.

This function accesses only the local list of owned subscriptions; it does not contact the WBEM server. The local list of owned subscriptions is discovered from the WBEM server when the server is registered with the subscription manager, and is maintained from then on as changes happen through this subscription manager.

Parameters:: server_id (string) – The server ID of the WBEM server, returned by add_server().
Returns:: The indication subscription instances.
Return type:: list of CIMInstance

remove_all_servers()[source]

Remove all registered WBEM servers from the subscription manager. This also unregisters listeners from these servers and removes all owned indication subscriptions, owned indication filters, and owned listener destinations.

:raises Exceptions raised by WBEMConnection.:

remove_destinations(server_id, destination_paths)[source]

Remove listener destinations from a WBEM server, by deleting the listener destination instances in the server.

The listener destinations must be owned or permanent (i.e. not static).

This method verifies that there are not currently any subscriptions on the listener destinations to be removed, in order to handle server implementations that do not ensure that on the server side as required by DSP1054.

Parameters:

server_id (string) – The server ID of the WBEM server, returned by add_server().
destination_paths (CIMInstanceName or list of CIMInstanceName) – Instance path(s) of the listener destination instance(s) in the WBEM server.

:raises Exceptions raised by WBEMConnection.: :raises CIMError: CIM_ERR_FAILED, if there are referencing subscriptions.

remove_filter(server_id, filter_path)[source]

Remove an indication filter from a WBEM server, by deleting the indication filter instance in the WBEM server.

The indication filter must be owned or permanent (i.e. not static).

This method verifies that there are not currently any subscriptions on the specified indication filter, in order to handle server implementations that do not ensure that on the server side as required by DSP1054.

Parameters:

server_id (string) – The server ID of the WBEM server, returned by add_server().
filter_path (CIMInstanceName) – Instance path of the indication filter instance in the WBEM server.

:raises Exceptions raised by WBEMConnection.: :raises CIMError: CIM_ERR_FAILED, if there are referencing subscriptions.

remove_server(server_id)[source]

Remove a registered WBEM server from the subscription manager. This also unregisters listeners from that server and removes all owned indication subscriptions, owned indication filters and owned listener destinations.

Parameters:: server_id (string) – The server ID of the WBEM server, returned by add_server().

:raises Exceptions raised by WBEMConnection.:

remove_subscriptions(server_id, sub_paths)[source]

Remove indication subscription(s) from a WBEM server, by deleting the indication subscription instances in the server.

The indication subscriptions must be owned or permanent (i.e. not static).

Parameters:

server_id (string) – The server ID of the WBEM server, returned by add_server().
sub_paths (CIMInstanceName or list of CIMInstanceName) – Instance path(s) of the indication subscription instance(s) in the WBEM server.

:raises Exceptions raised by WBEMConnection.: