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, userid, password)

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 of the HMC user to be used. Must not be None.

  • password (string) – Password of the HMC user to be used. Must not be None.

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

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, userid, password)

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.