IBM Tivoli Monitoring, Version 6.3

SOAP methods

Use the predefined SOAP methods to compose requests for invocation by PERL, Javascript, VBSCRIPT, JSCRIPT, C++, Java™, and through a browser. With each method is a list of supported tags and usage examples. Each SOAP method provided by IBM® and its supported tags is described here.

CT_Acknowledge

Send an event acknowledgement into the IBM Tivoli® Monitoring platform.

<name>: The name of the situation. This is required.
<source>: The source of the event (agent name or monitoring server name). The acknowledge applies to all the active sources of the named alert if the source is not supplied.
<data>: "No data was provided" is inserted if not provided.
<item>: Display item.
<userid>: Optional. The user ID to access the hub monitoring server. "nnn.nnn.nnn.nnn" is inserted if not provided.
<password>: Optional. The password to access the hub monitoring server. Required for monitoring server/hub logon validation.
<type>: Optional. Specifies the event type. The value can be "sampled" or "0", "pure" or "1", and "meta" or "2". Default: "sampled"
<hub>: Optional. Specifies the alias name of a remote hub that has been configured in the hubs list. The SOAP request is routed to this hub.
<expire>: Optional. Expires the acknowledgement after the number of minutes entered here.

Example:

<CT_Acknowledge> 
  <hub>z/OSPROD</hub>
  <name>situation_from_CT</name> 
  <source>CT_supported_system</source>
  <data>Jack is taking care of this failure</data>
  <item>subsystem</item>
  <userid>sysadmin</userid>
  <password>xxxxxxxx</password>
  <type>pure</type>
  <expire>60</expire> 
</CT_Acknowledge>

CT_Activate

Start a situation or a policy running on the IBM Tivoli Monitoring platform.

Note: Situations for agents connecting to a remote Tivoli Enterprise Monitoring Server cannot be started using this method.

<name>: The name of the situation. This is required.
<type>: The type of object being activated. This is required.
<userid>: Optional. The user ID to access the hub monitoring server. "nnn.nnn.nnn.nnn" is inserted if not provided.
<password>: The password to access the hub monitoring server. Required for monitoring server/hub logon validation.
<hub>: Optional. Specifies the alias name of a remote hub that has been configured in the hubs list. The SOAP request is routed to this hub.

Example:

<CT_Activate> 
  <hub>z/OSPROD</hub> 
  <name>name_of_situation_or_policy</name>
  <type> situation</type>  
  <userid>sysadmin</userid>
  <password>xxxxxxxx</password> 
</CT_Activate>

CT_Alert

Send an event into the IBM Tivoli Monitoring platform.

<name>: The name of the situation. This is required.
<source>: The source of the event (agent name or monitoring server name). This is required
<data>: "No data was provided" is inserted if not provided or if no optional object.attribute tag provided..
<item>: Display item.
<userid>: Optional. The user ID to access the hub monitoring server. "nnn.nnn.nnn.nnn" is inserted if not provided.
<password>: Optional. The password to access the hub monitoring server. Required for monitoring server/hub logon validation.
<type>: Optional. Specifies the event type. The value can be "sampled" or "0", "pure" or "1", and "meta" or "2". Default: "sampled"
<hub>: Optional. Specifies the alias name of a remote hub that has been configured in the hubs list. The SOAP request is routed to this hub.

<data><object.attribute>: Returns the value of the attribute (or attributes) specified to the Initial Attributes view of the Event results workspace.

Example:

<CT_Alert>
  <hub>z/OSPROD</hub> 
  <name>situation_from_XXX</name>
  <source>XXX_supported_system</source>
  <data><NT_Logical_Disk.Disk_Name>C:</NT_Logical_Disk.Disk_Name></data>
  <item>subsystem</item>
  <userid>sysadmin</userid>
  <password>xxxxxxxx</password>
</CT_Alert>

Note: When you specify object.attribute in the data tag, leave out any non-alphanumber characters other than the underscore (_). For example, NT_System.%_Total_Processor_Time is entered as NT_System.Total_Processor_Time.

CT_Deactivate

Stop a situation or policy on the IBM Tivoli Monitoring platform.

Note: Situations for agents connecting to a remote Tivoli Enterprise Monitoring Server cannot be stopped with this method.

<name>: The name of the situation or policy. This is required.
<type>: The type of object (situation or policy). This is required.
<userid>: The user ID to access the hub monitoring server. "nnn.nnn.nnn.nnn" is inserted if not provided.
<password>: The password to access the hub monitoring server. Required for monitoring server/hub logon validation.
<hub>: Optional. Specifies the alias name of a remote hub that has been configured in the hubs list. The SOAP request is routed to this hub.

Example:

<CT_Deactivate> 
  <hub>z/OSPROD</hub>
  <name>name_of_situation_or_policy</name>
  <type>situation</type>
  <userid>sysadmin</userid>
  <password>xxxxxxxx</password>
</CT_Deactivate>

CT_EMail

Send the output from another CT SOAP method, such as CT_Get, using e-mail through an SMTP server to a defined e-mail address (not available on z/OS®).

<server>

The smtp server name/network address is required.

<sender>

Sender's e-mail address is required.

<receiver>

Receiver's e-mail address is required.

<subject>

Optional. E-mail subject.

<message>

Optional. E-mail message.

<attachmenttitle>

Optional. Title of an attachment.

<request>

When specifying a second-level request, such as CT_Get, each sub-request must be included within a <request> </request> tag.

Optional: An id=" " element added to the <request> tag generates a <request id="XMLID"> element enclosing the corresponding response for that sub-request.

If additional security is enabled (SOAP_IS_SECURE=YES in the monitoring server environment variables) the following tags are also required:

<userid>: The user ID to access the hub monitoring server.
<password>: The password to access the hub monitoring server. Required for monitoring server logon validation.

Example:

<CT_EMail>  
  <server>smtp.server</server>
  <sender>myemail@something.com </sender> 
  <receiver>youremail@whatever.com </receiver> 
  <subject>Here's your data.</subject>
  <message>Table data supplied as attachment below. It is 
  presented in csv format to be used by MS/Excel.</message>
  <attachmenttitle>tabledata.csv</attachmenttitle> 
  <request id="XMLID">
    <CT_Get>
      <object>NT_Process </object>
      <target>TlPrimary:DCSQLSERVER:NT</target>
      <userid>sysadmin</userid>
      <password>xxxxxxxx</password>
    </CT_Get>
  </request>
</CT_EMail>

Example with additional security:

<CT_EMail>  
  <userid>sysadmin</userid>
  <password>xxxxxxxx</password>
  <server>smtp.server</server>
  <sender>myemail@something.com </sender> 
  <receiver>youremail@whatever.com </receiver> 
  <subject>Here's your data.</subject>
  <message>Table data supplied as attachment below. It is 
  presented in csv format to be used by MS/Excel.</message>
  <attachmenttitle>tabledata.csv</attachmenttitle> 
  <request id="XMLID">
    <CT_Get>
			<userid>sysadmin</userid>
			<password>xxxxxxxx</password>
      	<object>NT_Process </object>
      	<target>TlPrimary:DCSQLSERVER:NT</target>
    </CT_Get>
  </request>
</CT_EMail>

With the additional security, the user ID and password are requested by CT_EMail in order to be authorized. If a CT_Get is specified the same credentials are used to issue the CT_Get.

CT_Execute

Runs the SOAP request that is stored in a file.

<filename>: Specifies the file name that contains the SOAP request to be run. The file must reside in the \html directory. On z/OS, it must reside in RKANDATV. This is required.

Example:

<CT_Execute>
  <filename>execute1.xml</filename>
</CT_Execute>

CT_Export

Send the output from another CT SOAP method, such as CT_Get, to a defined file (not available on z/OS).

<filename>

The name of the file to contain the exported data. This is required.

Note: When inserting the file name tag into a quoted string literal of certain programming languages, such as C++, back slashes must be doubled.

To the <filename> tag, you can add an optional date/time stamp variable. The variable is enclosed in dollar signs ($) and can contain a combination of yy/mm/dd/hh/mm/ss (for year/month/day/hours/minutes/seconds). The date/time stamp attributes can be specified in any order, except mm must be preceded by yy or hh to identify it as either month (after year) or minutes (after hours). For example:

<filename>g:\exchange\excel\ntprocess$yymmdd$.htm</filename>

<warehouse/>

Specifies that data is to be exported to the Tivoli Enterprise Portal data warehouse through ODBC. <filename> and <warehouse/> are mutually exclusive, but one must be supplied.

<request>

When specifying a second-level request, such as CT_Get, each sub-request must be included within a <request> </request> tag.

Optional: An id=" " element added to the <request> tag generates a <request id="XMLID"> element enclosing the corresponding response for that sub-request.

If additional security is enabled (SOAP_IS_SECURE=YES in the monitoring server environment variables) the following tags are also required:

<userid>: The user ID to access the hub monitoring server.
<password>: The password to access the hub monitoring server. Required for monitoring server logon validation.

Example:

<CT_Export>
  <filename>g:\exchange\excel\ntprocess$yymmddhhmmss$.htm</filename> 
  <request>
    <attach>prefix.xsl</attach> 
  </request>
  <request id="XMLID">
    <CT_Get>
      <object>NT_Process</object>
      <target>Primary:DCSQLSE RVER:NT</target>
      <userid>sysadmin</userid>
      <password>xxxxxxxx</password>
    </CT_Get>
  </request>
  <request> 
    <attach>suffix.xsl</attach> 
  </request>
</CT_Export>

Example with additional security:

<CT_Export>
  <userid>sysadmin</userid>
  <password>xxxxxxxx</password>
  <filename>g:\exchange\excel\ntprocess$yymmddhhmmss$.htm</filename> 
  <request>
    <attach>prefix.xsl</attach> 
  </request>
  <request id="XMLID">
    <CT_Get>
			<userid>sysadmin</userid>
			<password>xxxxxxxx</password>
      	<object>NT_Process</object>
      	<target>Primary:DCSQLSE RVER:NT</target>
    </CT_Get>
  </request>
  <request> 
    <attach>suffix.xsl</attach> 
  </request>
</CT_Export>

With the additional security, the user ID and password are requested by CT_Export in order to be authorized. If a CT_Get is specified the same credentials are used to issue the CT_Get.

CT_Get

Receive a group of XML objects or individual XML objects from any IBM Tivoli Monitoring platform agent. You can use this to obtain real time data.

Important: When issuing a CT_Get request against a particular agent type, the monitoring server where the SOAP server is running must be configured and seeded for that agent type.

<object>: The name of the object to be retrieved. Required (by default, retrieves all the public elements of an object).
<userid>: The user ID to access the hub monitoring server. "nnn.nnn.nnn.nnn" is inserted if not provided.
<password>: The password to access the hub monitoring server. Required for monitoring server/hub logon validation.
<target>: Name of the agent.
Caution: Defaults to "*ALL". Retrieves all available targets.
<history>: Y retrieves historical data if available.
<results>: PARSE retrieves status history event attributes. Only valid for Status_History object.Multiple: more than one can be specified.
<attribute>: Attribute name of object. This tag can be specified multiple times.
<hub>: Specifies the alias name of a remote hub that has been configured in the hubs list. The SOAP request is routed to this hub.
<afilter>: Returns rows meeting filter criteria, such as attribute; operator; value operators: EQ, NE, GE, GT, LE, LT, LIKE. Like pattern characters: '*' matches one or more characters. Only supported for character attributes. Multiple afilters are only supported as conjuncts, for example, using AND to join together.

Example:

<CT_Get> 
  <hub>z/OSPROD</hub>
  <object>NT_System</object>
  <target>Primary:DCSQLSERVER:NT</target>
  <userid>sysadmin</userid> 
  <password></password>
  <history>Y</history>
  <attribute>Server_Name</attribute>
  <attribute>Processor_Queue_Length</attribute>
  <afilter>Write_Time;GT;1020804</afilter> 
  <afilter>Write_Time;LT;1020805</afilter> 
</CT_Get>

Note: When you specify an attribute in the attribute tags, leave out any non-alphanumeric characters other than the underscore (_). For example, %_Total_User_Time is entered as Total_User_Time.

CT_Redirect

Reroute a SOAP request to another registered SOAP method outside of the domain of the IBM Tivoli Monitoring platform.

<request endpoint=" ">: The <request endpoint= " "> value must specify the target of the redirected SOAP request. The entire XML supplied as the value of the request element is sent to that endpoint. When CT_Redirect is specified within a second- level request, such as, CT_Export, the <endpoint=" "> attribute is specified only within the CT_Redirect method. This is required.

Example:

<CT_Redirect>
  <request endpoint= \"http://services.xmethods.net:80/soap/servlet/rpcrouter\">
    <SOAP-ENV:Envelope xmlns:SOAP-ENV=\"http://schemas.xmlsoap.org/soap/envelope/\">
      <SOAP-ENV:Body>
        <ns1:getTemp xmlns:ns1=\"urn:xmethods-Temperature\"SOAP-ENV:
        encodingStyle=\"http://schemas.xmlsoap.org/soap/encoding/\">
          <zipcode>93117</zipcode> 
        </ns1:getTemp> 
      </SOAP-ENV:Body> 
    </SOAP-ENV:Envelope> 
  </request> 
</CT_Redirect>

CT_Reset

Send an event reset (close event) to the IBM Tivoli Monitoring platform.

<name>: The name of the situation. This is required.
<source>: The source of the event (agent name or monitoring server name). The reset applies to all the active sources of the named alert if the source is not supplied.
<item>: Display item.
<userid>: Optional. The user ID to access the hub monitoring server. "nnn.nnn.nnn.nnn" is inserted if not provided.
<password>: Optional. The password to access the hub monitoring server. Required for monitoring server/hub logon validation.
<hub>: Optional. Specifies the alias name of a remote hub that has been configured in the hubs list. The SOAP request is routed to this hub.
<type>: Optional. Specifies the event type. The value can be "sampled" or "0", "pure" or "1", and "meta" or "2". Default: "sampled"

Example:

<CT_Reset> 
  <hub>z/OSPROD</hub> 
  <name>situation_from_CT</name>
  <source>CT_supported_system</source>
  <item>subsystem</item>
  <userid>sysadmin</userid>
  <password>xxxxxxxx</password> 
</CT_Reset>

Note: Sampled events can be closed only if the situation has been stopped or deleted. Use the <type> tag if CT_Reset will be closing a pure event.

CT_Resurface

Resurface an acknowledged event in the IBM Tivoli Monitoring platform.

<name>: The name of the situation. This is required.
<source>: The source of the event (agent name or monitoring server name). The resurface applies to all the active sources of the named alert if the source is not supplied.
<item>: Display item.
<userid>: Optional. The user ID to access the hub monitoring server. "nnn.nnn.nnn.nnn" is inserted if not provided.
<password>: Optional. The password to access the hub monitoring server. Required for monitoring server/hub logon validation.
<hub>: Optional. Specifies the alias name of a remote hub that has been configured in the hubs list. The SOAP request is routed to this hub.
<type>: Optional. Specifies the event type. The value can be "sampled" or "0", "pure" or "1", and "meta" or "2". Default: "sampled"

Example:

<CT_Resurface> 
  <hub>z/OSPROD</hub> 
  <name>situation_from_CT</name> 
  <source>CT_supported_system</source> 
  <item>subsystem</item> 
  <userid>sysadmin</userid> 
  <password>xxxxxxxx</password> 
</CT_Resurface>

CT_WTO

Send a Universal Message into the IBM Tivoli Monitoring Platform.

<data>: The message to be sent. This is required.
<category>: Optional. Blank is the default.
<severity>: Optional. Blank is the default.
<userid>: Optional. The user ID to access the hub monitoring server. "nnn.nnn.nnn.nnn" is inserted if not provided.
<password>: Optional. The password to access the hub monitoring server. Required for monitoring server/hub logon validation.
<hub>: Optional. Specifies the alias name of a remote hub that has been configured in the hubs list. The SOAP request is routed to this hub.

Example:

<CT_WTO>
  <hub>z/OSPROD</hub>
  <data>This is Universal Message</data>
  <category>Critical Messages</category>
  <severity>High Severity</severity>
  <userid>sysadmin</userid>
  <password>xxxxxxxx</password>
</CT_WTO>

Feedback