Configuring and Using the Tivoli SOAP Server...If Security: Validate User is not enabled and no...

Configuring and Using the

Tivoli Monitoring SOAP Server

Technote

Written By : John Harris [email protected]

Version : 1.3 23 April 2012

© Copyright IBM Corporation 20© Copyright IBM Corporation 20© Copyright IBM Corporation 20© Copyright IBM Corporation 2011111111----2012201220122012

This document is the sole property of IBM Tivoli. No part of this document may be reproduced in any

form or by any means - electronic, mechanical, photocopying, recording or otherwise without the

prior written permission of IBM Tivoli.

© Copyright IBM Corporation, 2012 2

SPECIAL NOTICES

This document is presented “As-Is” and IBM does not assume responsibility for the statements expressed herein.

It reflects the opinions of the IBM Tivoli organization and these opinions are based solely on the authors’

experiences. If you have questions about the contents of this document, please contact the author at

[email protected].

Trademarks

The following are trademarks or registered trademarks of International Business Machines Corporation in the United States, other

countries, or both. IBM, the IBM logo, Candle, DB2, developerWorks, iSeries, Passport Advantage, pSeries, Redbooks, Tivoli Enterprise Console,

WebSphere, z/OS, xSeries, zSeries, System z, z/VM, AIX.

A full list of U.S. trademarks owned by IBM may be found at http://www.ibm.com/legal/copytrade.shtml.

NetView, Tivoli and TME are registered trademarks and TME Enterprise is a trademark of Tivoli Systems, Inc. in the United States

and/or other countries.

Microsoft, Windows, Windows NT, Internet Explorer, and the Windows logo are registered trademarks of Microsoft Corporation in

the United States and/or other countries.

Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States,

other countries, or both.

Linux is a trademark of Linus Torvalds in the United States, other countries, or both.

UNIX is a registered trademark in the United States and other countries licensed exclusively through The Open Group.

Intel and Pentium are registered trademarks and MMX, Pentium II Xeon and Pentium III Xeon are trademarks of Intel Corporation in

the United States and/or other countries.

Other company, product and service names may be trademarks or service marks of others.


Table of contents

Special Notices .................................................................................................................................................. 2

1. Introduction ............................................................................................................................................... 5

1.1 Acknowledgements.................................................................................................................................. 5

2. Getting Started........................................................................................................................................... 5

3. Configuring the SOAP Server .................................................................................................................... 6

2.1 Windows.................................................................................................................................................. 6

Adding HUBS............................................................................................................................................ 6

Adding Users ............................................................................................................................................. 8

2.2 Linux/Unix .............................................................................................................................................. 9

Adding HUBS via GUI .............................................................................................................................. 9

Adding HUBS via Command line ............................................................................................................ 11

Adding Users via GUI.............................................................................................................................. 12

Adding users to HUBS via Command line ............................................................................................... 12

2.3 z/OS....................................................................................................................................................... 14

Adding HUBS.......................................................................................................................................... 14

Adding Users ........................................................................................................................................... 17

2.4 Note....................................................................................................................................................... 18

4. Testing the SOAP Server via a browser.................................................................................................... 19

5. Constructing Requests - XML Payload .................................................................................................... 23

4.1 Locating Table and Column(s) Information............................................................................................ 25

4.1.1 TEPS Query Editor.......................................................................................................................... 25

4.1.2 TEPS Workspaces and the dockxx file(s) ......................................................................................... 27

4.2 Constructing Requests............................................................................................................................ 29

4.3 Directing SOAP request to remote systems ............................................................................................ 31

4.4 Configuring for Security ........................................................................................................................ 31

4.5 Creating Alerts....................................................................................................................................... 32

4.6 Returned Results .................................................................................................................................... 33

4.7 Exporting Data into an external file ........................................................................................................ 35

4.8 Using SOAP Requests in Situations ....................................................................................................... 36

4.9 Using SOAP from Tivoli System Automation/Netview.......................................................................... 38

Appendix A – Sample KSHXHUBS File ......................................................................................................... 41


1. Introduction

The purpose behind this technote is to clarify and expand on the official Tivoli documentation related to

configuring and using the Tivoli SOAP Server component.

1.1 Acknowledgements

I would like to thank Mike Bonett and Joe Means for their respective inputs.

2. Getting Started

I would suggest that you configure and test your SOAP Server either during the initial installation of

your TEMS environment or before you turn on the Security : Validate User option. Testing the

connections and responses to the SOAP Server is a lot easier without having to diagnose security related

issues which can dramatically length the testing and resolution time frame.

If you are going to configure the SOAP Server after installation and the security features have been

turned on you will be need to include the <userid> and <password> elements in the SOAP requests. As

the data will need to be entered in plain text in the soap request this could pose a security risk if it is

going to be a reusable component.

Security is based upon where the HUB monitoring server (TEMS) is running and the user ID and

passwords will be validated on that platform. As I do not have an LDAP installed I have not tested it

against that option in order to determine whether it would be problematic or not.


3. Configuring the SOAP Server

The following files/member contains the SOAP HUB definitions for the respective platforms and will be

created once a hub as been defined.

Windows : ITM_INSTALL_DIR\cms\html\kshxhubs.xml

Linux/Unix : ITM_INSTALL_DIR/tables/TEMS/HTML/kshxhubs.xml

z/OS : &rhilev.&rte.RKANPARU(KSHXHUBS)

a list from the above member is maintained in the global table KDSTHUBS

The files will on be created once a hub as been defined. See Appendix A for a sample of the file contents.

The following sections describe the processes for configuring the SOAP server component of a TEMS

installed on the supported host systems.

2.1 Windows

Adding HUBS

Run the Manage Tivoli Monitoring Services application from the Start�All Programs list.

Highlight and Right click on the Tivoli Enterprise Monitoring Server, select Advanced and

then Configure SOAP Server Hubs from the drop down menus as shown in Figure 1 below.

Figure 1.


The dialogue box shown in Figure 2 below is used to define both local and remote HUB SOAP

Servers.

Figure 2.

Press the Add Hub button and provide the following information as shown in Figure 3 below.

Figure 3.


Protocol : Select the appropriate protocol from the drop down control.

Alias : The alias for the local hub must always be "SOAP".

For hubs with which the local SOAP Server communicates, you

may choose any alias (for example, HUB2). Alias names can be

a minimum of 3 characters and a maximum of 8 characters.

Hostname or IP Address : Enter the target servers DNS resolvable name or IP Address

Port number : Enter the port number that will be used by the SOAP Server.

Not to be confused with the HTTP server port 1920. Requests will

be routed to this port via the HTTP server process.

Adding Users

Provide the following information as shown in Figure 4 below and then press the Add User

button.

Figure 4.

User name : Enter the user name. See the Note below regarding security dependencies.

Access : Select the appropriate access requirements.

See the ITM Installation guide for a detailed list of the applicable access

rights.

Recycle the TEMS in order to ensure that the new parameters are loaded.


2.2 Linux/Unix

Adding HUBS via GUI

Navigate to the product installation directory where the execution programs are placed, normally

/opt/IBM/ITM/bin. From here enter the command:

./itmcmd manage

The following GUI environment will be loaded. Highlight and Right click on the Tivoli

Enterprise Monitoring Server, select Configure from the drop down menus as shown in Figure

5a below.

Figure 5a.


Press the Save button when the initial TEMS configuration dialogue screen in Figure 5b below is

displayed.

Figure 5b.

This will present the SOAP Server configuration dialogue screen as shown in Figure 6 below.

Figure 6.


Provide the information required and then press the Add Host button

Host : Enter the target server’s DNS resolvable name or it's IP Address

Port number : Enter the port number that will be used by the SOAP Server process

Alias : The alias for the local hub must always be "SOAP".

For hubs with which the local SOAP Server communicates, you may

choose any alias (for example, HUB2). Alias names can be a minimum

of 3 characters and a maximum of 8 characters.

Protocol : Select the appropriate protocol from the drop down control.

Adding HUBS via Command line


/opt/IBM/ITM/bin and issue the following command

./itmcmd config –s –t tems_name

Accept the default values until you the following text appears

*************************

Editor for SOAP hubs list

*************************

Hubs

## CMS_Name

1 ip.pipe:TEMS_NAME[port_#]

1) Add, 2) Remove ##, 3) Modify Hub ##, 4) UserAccess ##, 5) Cancel, 6) Save/exit:

To add a HUB, enter 1 and press Enter and follow the prompts


Adding Users via GUI

Provide the following information as shown in Figure 7 below and then press the Add User

button.

Figure 7.

User name : Enter the user name. See the Note below regarding security dependencies.

Access : Select the appropriate access requirements.

See the ITM Installation guide for a detailed list of the applicable access

rights.

Adding users to HUBS via Command line


/opt/IBM/ITM/bin and issue the following command

./itmcmd config –s –t tems_name

Accept the default values until you the following text appears

*************************

Editor for SOAP hubs list

*************************

Hubs

## CMS_Name

1 ip.pipe:TEMS_NAME[port_#]

1) Add, 2) Remove ##, 3) Modify Hub ##, 4) UserAccess ##, 5) Cancel, 6) Save/exit:


To define users and assign access privileges, enter 4 followed by a space, and then the number

(in the list shown above) of the hub you want to configure.

To define a user with Query access, enter 1 followed by a space and the user ID.

To define a user with Update access, enter 2 followed by a space and the user ID.

Recycle the TEMS in order to ensure that the new parameters are loaded.


2.3 z/OS

Configuring the Tivoli infrastructure components on z/OZ is done be means of the IBM

Configuration and Tuning Tool (ICAT), which consists of related ISPF panels used to enter the

relevant information.

Adding HUBS

Navigate to TSO option 6.

Load the ICAT menus by executing &rhilev.INSTLIB from the TSO command line

Enter 3 (Configure products)

Enter 1 (Select product to configure) and proceed to Selecting the product to configure.

In this case it is OMEGAMON XE for z/OS which consists of the HUB TEMS address space as

shown in the Figure 8 below

Figure 8.

Enter C next to the applicable Run Time Environment

Select 1 (Tivoli Enterprise Monitoring Server)

Enter 3 (Specify configuration parameters)

Press Enter


Change the Access TEMS List via SOAP Server field to Y as shown and highlighted in Red in

Figure 9 below and press Enter

Figure 9.

Enter S (Secure TEMS) next to the applicable RTE Name as shown in Figure 10 below and press

Enter

Figure 10.


Enter the applicable information as shown in Figure 11 below and press Enter

Figure 11.

Adding Users

The following panel will be displayed and you can add any additional user IDs as required.


Figure 12.

Continually press PF3 until you exit ICAT.

All the changes can be verified in the KSHXHUBS member.

Recycle the TEMS address space in order to ensure that the new parameters are loaded.

2.4 Note

If Security: Validate User is not enabled and no users are added to the server definition, the

SOAP server honors all requests regardless of the sender. If Security: Validate User is enabled on

the hub monitoring server, the SOAP server honors requests only from users defined to the

operating system or security authorization facility of the monitoring server host.

If any users are added to the SOAP server definition, only those users who have also been defined

to the operating system or the security authorization facility of the monitoring server host have

access to the server, regardless of whether or not Security: Validate User is enabled.

See Appendix A for an example of a KSHXHUBS file/member.


4. Testing the SOAP Server via a browser

After completing the process of configuring the SOAP server hub(s), load your preferred browser and in

the address line enter the address of your Tivoli HTTP server as shown in Figure 13 below.

Figure 13.

As I have 3 SOAP HUBs defined (1 local and 2 remotes) on my system there are 3 entries displayed

under the Service Point: system.ibm-6331b003b53_cms entry. Unfortunately, it does not identify each

one individually and it requires a trial and error as to which target destination HUB you want to connect

to.

The browser’s address line (URL) will be your indicator as to which HUB you will be communicating

with as it will return a different http address line when any of the above links are selected and you will

be presented with a browser page as follows.

Alternatively enter the target address on the SOAP Server in the address line in the following formats

http://SOAP-Server-Name:1920///cms/soap or

http://SOAP-Server-Name:1920/soap

The Tivoli documentation mentions using the following URL which I have found to be non-functional

in ITM v622 FP5.


http://SOAP-Server-Name:1920///cms/kshhsoap.htm

The following example shows how to access a HUB SOAP server (demomvs.demopkg.ibm.com) from

a local browser as shown in Figure 14 below.

http://demomvs.demopkg.ibm.com:1920///cms/soap

Figure 14.

In order to access HUB on a separate platform from where the SOAP definitions were created use the

following URL format:

http://Local_HUB:1920///cms/Remote_Alias

Where Local_Hub is where the HUB definitions where defined and the Remote_Alias is the alias

defined for the remote HUB (See Appendix A).


When presented with the initial screen as shown in Figure 14 above, copy the address from the address

line (http://demomvs.demopkg.ibm.com:1920///cms/soap) and paste it into the Endpoint field as shown

in Figure 15 below.

Do not bother selecting any options from the first Drop-down list, modify the Payload (XML) field

accordingly.

Figure 15.

The default SOAP request above in the Payload field returns a list of agents that have connected to the

ITM infrastructure. If you have Security enable for the HUB, ensure that you modify the values for the

<userid> and <password> elements.

Press the “Make SOAP Request” button.

If the SOAP Server has been correctly configured, you should get back a response similar the Figure xx

below, which should contain a status code “Status: 200 KDH1_STC_OK” on the right hand side below

the dialogue box. The successful request includes 2 informational sections, which in this case lists all the


Agents that have connected at sometime to the Managed System (TEMS), as either ONLINE or

OFFLINE.

The top right hand dialogue box contains the returned SOAP response in unparsed XML format

The bottom right contains the parsed data elements/fields constituting each row of information that was

returned.

Figure 16.

The SOAP request can be customized in order to return the necessary information from the management

infrastructure by modifying the information in the Payload XML field on the initial SOAP request web

page.

Alternatively you can use the kshsoap command line program, providing it with 2 file names as input

parameters. The first being the name of the file containing the SOAP CT method calls (Payload XML)

information and the second being the name of the file containing the targeted SOAP Server information,

which would be the URL of the target SOAP Server as follows.

http://ServerName:PortNo///cms/soap

The kshsoap program can be found in the following locations.


Windows : ITM_INSTALL_DIR\cms\kshsoap.exe

Linux/Unix : ITM_INSTALL_DIR/arch/ms/bin/kshsoap

5. Constructing Requests - XML Payload

SOAP messages consist of the Header and Payload sections. The Payload contains XML tags

representing the list of supported method calls described below. Each method call has its’ own specific

list of required and optional elements in order to satisfy that particular request.

The Tivoli CT SOAP method calls are encoded using stand XML shown below

<CT_Get> Tivoli SOAP Method call

<object></object>

<attribute></attribute>

……

</CT_Get>

When issuing either the browser or the command line interface, you only require the Tivoli SOAP

method call elements and NOT any of the SOAP-ENV elements. The resultant XMLmust adhere to

XML parsing rule requirements. The available list of Tivoli SOAP method calls available are as follows:

• CT_Acknowledge

Send an event acknowledgement to the Tivoli Monitoring platform

• CT_Activate Start a situation/alert or policy on the Tivoli Monitoring platform

• CT_Alert Send an alert to the Tivoli Monitoring platform

• CT_Deactivate Stop a situation/alert or policy on the Tivoli Monitoring platform

• CT_Email Send the output from another CT SOAP method (CT_Get) using e-mail through an SMTP server

to a defined email address (not available on z/OS)

• CT_Execute Runs the SOAP request which is stored in a file.

• CT_Export

Send the output from another CT SOAP method (CT_Get) to a defined file (not available on

z/OS)

• CT_Get Receive a group of XML objects or individual XML objects from any Tivoli Monitoring

platform agent. This can use be in order to obtain real-time data.

• CT_Redirect Reroute a SOAP request to another registered SOAP method outside of the domain of to the

Tivoli Monitoring platform

• CT_Reset Send and event reset (close event) to the Tivoli Monitoring platform

• CT_Resurface Resurface an acknowledged event in the Tivoli Monitoring platform


• CT_WTO Send a Universal Message into the Tivoli Monitoring platform

Refer to the IBM Tivoli Monitoring (ITM) Installation Guide – Appendix A for a detailed description of

all the required and optional elements for each type of requests listed above.


4.1 Locating Table and Column(s) Information

The million dollar question remains.

Where do you get a list of the tables and column(s) names that can be used in the SOAP

method calls?

There 2 methods of determining the Table/Column names, namely:

• Query Editor with the TEPS

• TEPS Workspaces and the dockxx files

4.1.1 TEPS Query Editor

This method of extracting the table/column name(s) is the simpler of the two. Navigate to the

Workspace/View containing the information which you want to query. Right click on the

Table/Graph containing the data and select Properties from the drop down menu and from the

following dialogue screen below select the Query Tab.


The following dialogue screen will appear which will provide both the table and column names.

In the tree display on the left the Table name in this case is Channel_Summary. The text below

it without the underscore is what appears as the title in the Table/Graph view.

The column names reflect either the contents of the *CAPT: tag (see next section) in the dockxx

files. In most cases the columns names highlighted above can be used as is, replacing the

spaces/blanks ‘ ‘ between the words with underscores. In the case where special characters such

as ‘%’ are used you would need to review the dockxx file (described in the following section

below) as to what it really represents.

In this case I can tell you that the “%’ represents the word Percent and therefore the applicable

column names highlighted above would be:

Channel_Name

Channel_Type

Percent_Max_Instances_per_Client

Percent_Maximum_Sharing_Conversations

Percent_Maximum_Instances

There still is no guarantee that the column names displayed here are totally correct or that the

developer has been consistent when creating the applicable dockxx files. As can be seen above

one column name has Max view and it is also represented as max in the dockxx file, but in

another instance the Max in (% Max Sharing Conversations) view is actually spelt out in full

in the dockxx file.


My Rule of Thumb is to always double check the information in the dockxx file(s) as described

below.

4.1.2 TEPS Workspaces and the dockxx file(s)

The table/column names correspond with the actual displayed names in the TEPS. These names

can be obtained from the application support files for each product that is added to the ITM

infrastructure. The naming convention of the application support files names is as follows:

dockxx

Where xx represents the 2 character product code as shown in the examples below:

mq=WebSphere MQ,

n3=Mainframe Networks

m5=z/OS etc.

These doc files can be found in the following locations:

Windows : ITM_INSTALL_DIR\CNPS\dockxx

Linux/Unix : ITM_INSTALL_DIR/arch/cq/data/dockxx

The dockxx files contain a list of the table names followed by their respective fields/column

names.

The *OBJECT: tag in the file represents the name of the View which is displayed in the TEPS

and corresponds to the <object> element in the SOAP method call.

This *OBJECT: tag is also associated with a *TABLE: tag, which in turn can be cross

referenced to the CATTR and ATTR files but not used in the SOAP Method calls.

The *OBJECT: tag can either precede or follow a *TABLE: tag.

The *ATTR: tag in the file represents the field/columns associated with the prior *OBJECT:

tag (table) and it corresponds with the <attribute> element in the SOAP method call.

The *CAPT: tag, if it exists, follows the *ATTR: tag and is used as a replacement column

heading in the TEPS. Use either to locate the correct column name and then use the *ATTR: tag

for the value of the <attribute> element.

Any ‘\’ or ‘/’ characters in the data are used to separate the column headings across multiple

lines.

Note Once you have extracted the Table name then submitting a SOAP CT_Get method call with

only the <object>Table_Name</Object> elements will return a list of all the columns names

and their respective values for each and every row returned. You can then use that output in

order to reduce the information to that which is of interest.

Steps to extract the required information from dockxx files

Proceed with the following steps in order ensure that you have the correct necessary

information available for constructing the SOAP Method call


• Navigate to the workspace containing the View of the table containing the

information you want to process.

• Record the name of the View or use the process described in 4.1.1 above, as well as

identifying the column names you want to include in the output.

• Open the applicable products’ dockxx file and locate the *OBJECT: tag which

corresponds to name of the View which you want to process and record the correct

name of the table that needs to be processed.

• Locate the *ATTR: tags for the column names that you want to include in the output

data. Not including any <attribute> elements in the SOAP call will result in all

column(s) being included in the output data. Column names that appear on separate

lines in the TEPS will include special characters in the docxx file.

My Rule of Thumb for translating the *OBJECT: and *ATTR: tag information into their

respective <object>/<attribute> element values. All blank spaces ‘ ‘ or special characters ‘\’

or ‘/’ in the Table/Column names need to be converted to an underscore ‘_’


4.2 Constructing Requests

Processing data from specific tables is done with the object element name. The following example

requests all column(s) from the Channel Summary table for all the MQ agents:

<CT_Get>

<object>Channel_Summary</object>

</CT_Get>

By default any request will be directed to all the active agents. In order to improve performance,

reduce the processing overhead or reduce the amount of data returned a request can be sent to one

or more specific agents for processing. This is done by adding one or more <target> elements to

the method call. The value of the <target> element can be obtained from the Manage System

Status workspace in the portal.

The following example requests the status of the agents connected to the TEMS

<CT_Get>

<object>ManagedSystem</object>

<target>ManagedSystemName</target>

</CT_Get>

The following example requests the Channel Summary information from the BROKER1 agent

only:

<CT_Get>

<object> Channel_Summary</object>

<target>BROKER1::MQ</target>

</CT_Get>

By default the SOAP server will return all the columns in the results. Restricting data from specific

column(s) within a table is done with one or more <attribute> elements. The following example

requests the data to be returned from only 3 columns in the Channel Summary table:

<CT_Get>


<attribute>Host_Name</attribute>

<attribute>MQ_Manager_Name</attribute>

<attribute>Channel_Name</attribute>

</CT_Get>

In order to request only specific rows based upon the contents of one or more column(s) values is

done by adding the <afilter> element to the method call. The following example expands on the

above request by only requesting information for a specific QMgr name only.

<CT_Get>





<afilter> MQ_Manager_Name;EQ;BROKER1</afilter>

</CT_Get>


The following example expands on the above request by requesting only information for specific

Channel names ending with SVRCONN, which are normally associated with client application

connections.

<CT_Get>





<afilter>Channel_Name;LIKE;*SVRCONN</afilter>

</CT_Get>

The following operators are supported, EQ, NE, GE, GT, LE, LT, LIKE. Pattern matching

character supported are ‘%’ for individual character matching or ‘*” matching one or more

characters.

Multiple <afilter> elements can be listed in the request and are treated as an AND construct.

There is no equivalent for an OR construct.


4.3 Directing SOAP request to remote systems

If your hub TEMS has been configured with one or more remote SOAP servers you can direct the

SOAP request to a remote hub using the <hub> element. The following example issues a request

from your local HUB TEMS to alias which was defined for a z/OS based hub TEMS with the alias

of DEMOMVS.

<CT_Get>

<hub>DEMOMVS</hub>






</CT_Get>

4.4 Configuring for Security

When security has been enabled, ensure that you include the values for the <userid> and

<password> elements as follows:

<CT_Get>

<userid>SYSADMIN</userid>

<password>MYPWD</password>

……

</CT_Get>


4.5 Creating Alerts

The SOAP method CT_Alert is used to send alerts into the Tivoli infrastructure. These alerts

appear in the Message Log view as depicted in Figure 17 below. I would suggest creating an

internal alert on the Message Log in to raise the awareness of these Alerts when they appear.

The following example is what was used in order to create the highlighted alerts as depicted in

Figure 17 below.

<CT_Alert>

<name>BB_Primary_Qmgr_Down</name>

<source>IBM-6331b003B53</source>

<data>

<Current_Queue_Manager_Status.MQ_Manager_Status>Soap_Alert_Test_Data</

Current_Queue_Manager_Status.MQ_Manager_Status>

</data>

<item>Queue_Manager_Status</item>

<userid>sysadmin</userid>

<password></password>

</CT_Alert>

Figure 17.


4.6 Returned Results

All results from the Tivoli SOAP method calls are returned in an XML formatted data format.

Review the returned data for any error messages; see Figure 18 below, which might have occurred

such as:

• Agents not started

• Cannot connect to the SOAP server

• Invalid XML in the initial request, etc

Figure 18.

The returned XML data will need to be parsed in order to extract and process the relevant

information required. Using the command line interface (kshsoap) the output can be directed to at

output file which can then be processed accordingly.


Sample SOAP Response Message Valid data will be returned in multiple <ROW> elements representing each row of information

from the

<TABLE> � internal name for the table being processed

<OBJECT> � corresponds to the table <object> element on the initial SOAP call

<DATA> � start of the returned data section

<ROW> � one or more elements will be returned matching the number of rows matching

the initial SOAP call

The following example represents the sample output from a SOAP return message.

The actual data returned from the Tivoli SOAP call is highlighted in bold text below.

Check the <SOAP-CHK:xxxxxxx ………> element for the status of the initial SOAP request as

highlighted below in RED.

<?xml version="1.0" encoding="UTF-8"?>

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" SOAP-

ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">

<SOAP-ENV:Body> <SOAP-CHK:Success xmlns:SOAP-CHK = "http://soaptest1/soaptest/" xmlns="urn:candle-soap:attributes">

<TABLE name="O4SRV.INODESTS">

<OBJECT>ManagedSystem</OBJECT>

<DATA>

<ROW>

<Timestamp>1110907101656000</Timestamp>

<Name>BROKER1:HARR:KQIB</Name>

<Managing_System>HARR:IBM-6331B003B53:KQIA</Managing_System>

<ORIGINNODE>BROKER1:HARR:KQIB</ORIGINNODE>

<Reason>FA</Reason>

<Status>*OFFLINE</Status>

<Product>QI</Product> <Version>07.10.00</Version>

<Type>V</Type>

<HLOCFLAG>L</HLOCFLAG>

<Host_Info>WinXP~5.1-SP3</Host_Info>

<HHOSTLOC></HHOSTLOC>

<Host_Address><![CDATA[ip.pipe:#9.9.97.82<NM>IBM-

6331B003B53</NM>]]></Host_Address>

</ROW>

<ROW>

…….

</ROW> <ROW>

…….

</ROW>

</DATA>

</TABLE>

</SOAP-CHK:Success> </SOAP-ENV:Body>

</SOAP-ENV:Envelope>


4.7 Exporting Data into an external file

The following example demonstrates exporting the data into a file and the results can be seen in

Figure 19 below.

<CT_Export>

<filename>c:\SOAPTEST.xml</filename>

<request>

<CT_Get>

<userid>sysadmin</userid>

<password></password>

<object>ManagedSystem</object>

<target>ManagedSystemName</target>

</CT_Get>

</request>

</CT_Export>

Figure 19.

Giving the file name an extension of XML will enable the browser to display the file without the

included XML tags. Alternatively you can just rename the output to include the HTM extension.


4.8 Using SOAP Requests in Situations

While the above examples demonstrate using the SOAP requests from either a browser or via the

kshsoap program, it is also possible to execute a SOAP request in response to a situation/alert

being triggered. This is done buy adding the following information to the System Command field

under Action tab when defining/configuring a situation/alert.

The format of the command is as follows and depicted in Figure 20 below.

soap:CT_Execute,filename=sample_filename

Figure 20.

The SOAP method call CT_Execute must be mixed case and must execute on the Managing

System as shown in Figure 20 above.

The filename (SOAP_MQ_Req.txt in Figure 20 above) must reside in the following locations for

the respective platforms taking the platforms naming conventions into consideration.

Windows : ITM_INSTALL_DIR\cms\html

Linux/Unix : ITM_INSTALL_DIR/tables/TEMS/HTML


z/OS : &rhilev.&rte.RKANDATV

Some uses for the above facility are as follows

• Write WTO messages to a z/OS console for automation tool processing or operator actions

• Create and forward emails containing daily summary data to management recipients

• Extract and process addition data

• Extract/analyze/combine and process data from multiple agents

• Raise additional alerts based upon multiple criteria.

The following example in the SOAP_MQ_Req.txt above will create a file containing the results of

the SOAP request. The results can be seen in Figure 21 below

<CT_Export>

<filename>c:\SOAPTEST.xml</filename>

<request>

<CT_Get>


<attribute>Origin_Node</attribute>





</CT_Get>

</request>

</CT_Export>


Figure 21.

4.9 Using SOAP from Tivoli System Automation/Netview

The Tivoli System Automation product provides access to the Netview INGOMX programming

interface that provides a mechanism to interface with the OMEGAMON products. It provides an

interface to communicate with an IBM Tivoli Monitoring SOAP server to issue SOAP messages

and to process the response from the SOAP server.

While INGOMX handles the communication and the envelope of the SOAP message, it is the

responsibility of the caller to provide an appropriate body either dynamically or in a data set of

choice. The body consists of specific elements in XML notation that denote the SOAP method

calls described above.

The format of the command is as follows:

INGOMX SOAPREQ SERVER=server [PORT=portno] PATH=”path” DATA=[*|DSN]

USER=”userid” PASSWD=”passwd” [PROTOCOL=HTTP|HTTPS]

The following examples have been extracted from the Tivoli System Automation v3.3

Programmer’s Reference manual available at the following link http://publib.boulder.ibm.com/infocenter/tivihelp/v3r1/index.jsp?topic=/com.ibm.sazos.doc_3.3/welcome.html

and demonstrates calling the INGOMX interface from within a REXX program.


The REXX/NETVIEW PIPE interface provides the initial call to INGOMX and also performs any

post processing on the returned data.

Example 3: Send SOAP Message Using the Default Safe This example assumes that the SOAP server SOAPHUB was defined in the

SA z/OS customization dialog SOAP SERVER policy. To request a list of address

spaces starting with TEST and analyze their CPU utilization, you can construct and

send a SOAP message like the one below to SOAPHUB in the following way:

smsg.1 = ’<CT_Get>’

smsg.2 = ’ <object>Address_Space_CPU_Utilization</object>’

smsg.3 = ’ <attribute>job_name</attribute>’

smsg.4 = ’ <attribute>asid</attribute>’

smsg.5 = ’ <attribute>tcb_percent</attribute>’

smsg.6 = ’ <afilter>Job_Name;LIKE;TEST*</afilter>’

smsg.7 = ’</CT_Get>’

smsg.0 = 7

’PIPE (NAME SOAPREQ)’,

’| STEM smgs.’,

’| SAFE *’,

’| NETV INGOMX SOAPREQ SERVER=SOAPHUB DATA=*’

Example 4: Send SOAP Message Using a Data Set As an alternative, the XML source in “Example 3: Send SOAP Message Using the

Default Safe” can also be stored in a data set. The invocation of INGOMX would

then be:

’PIPE (END % NAME SOAPREQ)’,

’| NETV (MOE) INGOMX SOAPREQ SERVER=SOAPHUB DATA=USER.SOAP.DATA(GET)’,

’| L: LOC 1.8 ’del||’DWO369I ’||del,

’| EDIT SKIPTO ’del||’RETURN CODE’||del,

’ UPTO ’del||’.’||del,

’ WORD 3 1’,

’| VAR my_retcode’,

’% L:’,

’| CON ONLY’

The variable del is a delimiter character that does not appear in the data stream

that is returned, for example, X'0D'.

Example 5: Explicit Specification of SOAP Server Here an example is shown where the SOAP server is not defined in a SOAP server policy but directly in the invocation of INGOMX:

Server = ’boekeya.boeblingen.de.ibm.com’

Path = ’///cms/soap’

Address Netvasis ’PIPE (END % NAME SOAPREQ)’,

’| NETVASIS NETV (MOE) INGOMX SOAPREQ SERVER=’Server,

’PORT=1920 PATH="’Path’" DATA=USER.SOAP.DATA(GET)’,

’| L: LOC 1.8 ’del||’DWO369I ’||del,



’ WORD 3 1’,


’% L:’,

’| CON ONLY’

Note that the path is passed in double-quotation marks to preserve its case.

Example 6: Explicit Specification of SOAP Server, User ID, and Password


The following is an example where the SOAP server, user ID, and password are

specified at the invocation of INGOMX:

Server = ’boekeya.boeblingen.de.ibm.com’

Userid = ’SoapUser’

Path = ’///cms/soap’

Address Netvasis ’PIPE (END % NAME SOAPREQ)’,

’| NETVASIS NETV (MOE) INGOMX SOAPREQ SERVER=’Server,

’USERID="’Userid’" PASSWORD="SAFPW"’,

’PORT=1920 PATH="’Path’" DATA=USER.SOAP.DATA(GET)’,

’| L: LOC 1.8 ’del||’DWO369I ’||del,



’ WORD 3 1’,


’% L:’,

’| CON ONLY’

Note that the path, user ID and password are passed in double quotation marks to preserve their case. If the specified password is “SAFPW”, the actual password is

taken from the NetView Password Data Set. The password must be stored in the

Password Data Set before it is used


Appendix A – Sample KSHXHUBS File

<?xml version="1.0"?>

<?xml-stylesheet type="text/xsl" href="hubdef.xsl" ?>

<ENTERPRISE>

<HUB>

<CMS_Name>IP.PIPE:dem17lnx.demopkg.ibm.com[1918]</CMS_Name>

<Service_Name>dem17lnx</Service_Name>

<Alias>dem17lnx</Alias>

</HUB>

<HUB>

<CMS_Name>IP.PIPE:demomvs.demopkg.ibm.com[9002]</CMS_Name>

<Service_Name>DEMOMVS</Service_Name>

<Alias>DEMOMVS</Alias>

<Access>

<Update>

<User>NETOP2</User>

</Update>

</Access>

</HUB>

<HUB>

<CMS_Name>IP.PIPE:ITMSVR[1918]</CMS_Name>

<Service_Name>SOAP</Service_Name>

<Alias>SOAP</Alias>

</HUB>

<HUB>

<CMS_Name>IP.PIPE:testmvs.demopkg.ibm.com[9002]</CMS_Name>

<Service_Name>TESTMVS</Service_Name>

<Alias>TESTMVS</Alias>

<Access>

<Update>

<User>NETOP2</User>

</Update>

</Access>

</HUB>

</ENTERPRISE>

Configuring and Using the Tivoli SOAP Server...If Security: Validate User is not enabled and no...

Documents

Transcript of Configuring and Using the Tivoli SOAP Server...If Security: Validate User is not enabled and no...