Previous page

Next page

Locate page in Contents

Print this page

subscribe

Summary:

Subscribes to system event notifications.

Request specification:

Name

Min/Max

Type

Description

subscribe

 

 

 

{

 

 

 

name

1..[]

string

Subscription name. See Events/Elements for the available subscriptions.

}

 

 

 

Returns:

Name

Min/Max

Type

Description

event

1..1

eventType

Event data.

Description:

Subscription is a mechanism allowing to monitor the system for critical events, such as the server status changes, Server configuration changes, and some others. It also allows to receive automatic notifications if an alert is raised on the server due to resource allocation problems. To subscribe to the event or an alert notification service, execute this call passing the subscription name.

As soon as the event takes place (or an alert is raised), a message is sent to your client program containing the event data. You recognize the message by examining the value of the target element in the message header, which should contain the same event subscription name as the one you used when you subscribed to the event notifications. Please remember that an Agent message may have more than one target element. When searching for a particular value, always remember to look through all occurrences of the target element.

A subscription remains in effect for the duration of the user session. If the client program disconnects and then re-connects again, the subscription is canceled and the client has to subscribe again. The events that triggered during that time (if any) will be unknown to this client. However, the majority of the events are logged internally by Agent, so you can retrieve this information later. The even log can be accessed using the event_log interface.

For information on the available events and alerts, see the Events section.

To stop receiving the event notifications, use the unsubscribe call.

Example:

Input

Subscribing to the environment status change events.

<packet version="4.0.0" id="2">

<data>

<system>

<subscribe>

<name>env_status_subscription</name>

</subscribe>

</system>

</data>

</packet>

Output

Subscription was a success.

<packet priority="0" version="4.0.0" id="2">

<origin>servd</origin>

<target>vzclient1</target>

<data>

<system>

<ok/>

</system>

</data>

</packet>

Output

The following is a notification message received when one of the Environments was stopped. The message contains the Server ID that generated the event, the text message describing the event, and the event data (the old and the new server state and transition codes). Note that one of the target elements contains the same value as the one we used in the name element in the request, which is env_status_subscription -- that's how you recognize the message. Please also note that the inner data structure contains the elements specific to this event type, which in this particular case is the env_status_event element.

<packet version="4.0.0">

<target>events_subscription</target>

<target>env_status_subscription</target>

<data>

<event>

<eid>849c9be9-5fbb-4e7d-b100-f841f86c150e</eid>

<time>1155317636</time>

<source></source>

<category>env_status_subscription</category>

<sid>XXX</sid>

<data>

<env_status_event>

<eid>62ec514e-bc38-4aee-830d-cc802ee2aadd</eid>

<new>

<state>3</state>

</new>

<old>

<state>3</state>

<transition>5</transition>

</old>

</env_status_event>

</data>

<info>

<message>

RW52aXJvbm1lbnQgJWVpZCUgc3RhdHVzIGNoYW5nZWQgZnJvbSAlb2xkJSB0byAlbmV3JQ==

</message>

<name></name>

<translate/>

<parameter>

<message>NjJlYzUxNGUtYmMzOC00YWVlLTgzMGQtY2M4MDJlZTJhYWRk</message>

<name>eid</name>

</parameter>

<parameter>

<message>Mw==</message>

<name>new</name>

<translate/>

</parameter>

<parameter>

<message>Mw==</message>

<name>old</name>

<translate/>

</parameter>

</info>

</event>

</data>

<src>

<director>gend</director>

</src>

</packet>

Please send us your feedback on this help page