6. Notifications

The HMC supports the publishing of notifications for specific topics. This includes for example asynchronous job completion, property or status changes, and operating system messages issued in an LPAR or DPM partition.

The zhmcclient package supports receiving HMC notifications in an easy-to-use way, as shown in the following example that receives and displays OS messages for a DPM partition:

import zhmcclient

hmc = ...
userid = ...
password = ...

session = zhmcclient.Session(hmc, userid, password)
client = zhmcclient.Client(session)
cpc = client.cpcs.find(name=cpcname)
partition = cpc.partitions.find(name=partname)

topic = partition.open_os_message_channel(include_refresh_messages=True)

print("Subscribing for OS messages for partition %s on CPC %s using "
      "notifications..." % (partition.name, cpc.name))

receiver = zhmcclient.NotificationReceiver(
    topic, hmc, session.session_id, session.session_credential)

try:
    for headers, message in receiver.notifications():
        print("HMC notification #%s:" % headers['session-sequence-nr'])
        os_msg_list = message['os-messages']
        for os_msg in os_msg_list:
            msg_txt = os_msg['message-text'].strip('\n')
            msg_id = os_msg['message-id']
            print("OS message #%s:\n%s" % (msg_id, msg_txt))
except zhmcclient.NotificationError as exc:
    print("Notification Error: {}".format(exc))
except KeyboardInterrupt:
    print("Keyboard Interrupt - Leaving notification receiver loop...")
finally:
    print("Closing notification receiver...")
    receiver.close()

When running this example code in one terminal, and stopping or starting the partition in another terminal, one can monitor the shutdown or boot messages issued by the operating system. The following commands use the zhmc CLI provided in the zhmccli project to do that:

$ zhmc partition stop {cpc-name} {partition-name}
$ zhmc partition start {cpc-name} {partition-name}
class zhmcclient.NotificationReceiver(topic_names, host, userid, password, port=61612)[source]

A class for receiving HMC notifications that are published to particular HMC notification topics.

Experimental: This class is considered experimental at this point, and its API may change incompatibly as long as it is experimental.

Creating an object of this class establishes a JMS session with the HMC and subscribes for the specified HMC notification topic(s).

Notification topic strings are created by the HMC in context of a particular client session (i.e. Session object). However, these topic strings can be used by any JMS message listener that knows the topic string and that authenticates under some valid HMC userid. The HMC userid used by the JMS listener does not need to be the one that was used for the client session in which the notification topic was originally created.

Parameters:

  • topic_names (string or list/tuple thereof) – Name(s) of the HMC notification topic(s). Must not be None.

  • host (string) – HMC host. For valid formats, see the host property. Must not be None.

  • userid (string) –

    Userid for logging on to the HMC message broker. Must not be None.

    If the HMC userid is configured to use MFA, this must be the session ID of a session that user has with the HMC. Otherwise, it can either be the session ID, or the HMC userid.

  • password (string) –

    Password for logging on to the HMC message broker. Must not be None.

    If userid specifies a session ID, this must be the session credential for that session ID. If userid specifies an HMC userid, this must be the password for that userid.

  • port (integer) – STOMP TCP port. Defaults to DEFAULT_STOMP_PORT.

subscribe(topic_name)[source]

Subscribe this notification receiver for a topic.

Parameters:

topic_name (string) – Name of the HMC notification topic. Must not be None.

Returns:

Subscription ID

Return type:

string

unsubscribe(topic_name)[source]

Unsubscribe this notification receiver from a topic.

If the topic is not currently subscribed for by this receiver, SubscriptionNotFound is raised.

Parameters:

topic_name (string) – Name of the HMC notification topic. Must not be None.

Raises:

SubscriptionNotFound – Topic is not currently subscribed for.

is_subscribed(topic_name)[source]

Return whether this notification receiver is currently subscribed for a topic.

Parameters:

topic_name (string) – Name of the HMC notification topic. Must not be None.

get_subscription(topic_name)[source]

Return the subscription ID for a topic this notification receiver is subscribed for.

If the topic is not currently subscribed for by this receiver, SubscriptionNotFound is raised.

Parameters:

topic_name (string) – Name of the HMC notification topic. Must not be None.

notifications()[source]

Generator method that yields all HMC notifications (= JMS messages) received by this notification receiver.

Example:

desired_topic_types = ('security-notification',
                       'audit-notification')
topics = session.get_notification_topics()
topic_names = [t['topic-name']
               for t in topics
               if t['topic-type'] in desired_topic_types]

receiver = zhmcclient.NotificationReceiver(
    topic_names, hmc, session.session_id,
    session.session_credential)

for headers, message in receiver.notifications():
    . . . # processing of topic-specific message format
Yields:

A tuple (headers, message) representing one HMC notification, with:

  • headers (dict): The notification header fields.

    Some important header fields (dict items) are:

    • ‘notification-type’ (string): The HMC notification type (e.g. ‘os-message’, ‘job-completion’, or others).

    • ‘session-sequence-nr’ (string): The sequence number of this HMC notification within the session created by this notification receiver object. This number starts at 0 when this receiver object is created, and is incremented each time an HMC notification is published to this receiver.

    • ‘class’ (string): The class name of the HMC resource publishing the HMC notification (e.g. ‘partition’).

    • ‘object-id’ (string) or ‘element-id’ (string): The ID of the HMC resource publishing the HMC notification.

    For a complete list of notification header fields, see section “Message format” in chapter 4. “Asynchronous notification” in the HMC API book.

  • message (JSON object): Body of the HMC notification, converted into a JSON object. None for notifications that have no content in their response body.

    The properties of the JSON object vary by notification type.

    For a description of the JSON properties, see the sub-sections for each notification type within section “Notification message formats” in chapter 4. “Asynchronous notification” in the HMC API book.

Raises:

  • NotificationJMSError – Received JMS error from the HMC.

  • NotificationParseError – Cannot parse JMS message body as JSON.

close()[source]

Disconnect and close the JMS session with the HMC.

This implicitly unsubscribes from the notification topic this receiver was created for, and causes the notifications() method to stop its iterations.