SOAP

1
SOAP

• The Basics of SOAP Messaging

2
What is SOAP?

• SOAP is a simple XML based protocol to let
  applications exchange information over HTTP.
• Or more simply SOAP is a protocol for accessing
  a Web Service.
• SOAP stands for Simple Object Access Protocol but
  this has now been dropped.
• SOAP specification is currently maintained by the
  XML Protocol Working Group of the World Wide Web
  Consortium
• It has several advantages
• SOAP is platform independent
• SOAP is language independent
• SOAP allows you to get around firewalls

3
Why SOAP?

• SOAP provides a method to communicate between
  applications running on heterogeneous operating
  systems, using different technologies and
  programming languages.
• Today's applications communicate using RPC
  between objects like DCOM and CORBA, but HTTP was
  not designed for this.
• RPC represents a compatibility and security
  problem firewalls and proxy servers will
  normally block this kind of traffic.
• A better way to communicate between applications
  is over HTTP, because HTTP is supported by all
  Internet browsers and servers. SOAP was created
  to accomplish this.

4
Advantages and Disadvantages

• Advantages
• Open standard
• XML messaging is simple
• XML widely used
• Firewall friendly
• Multiple languages Java, Perl, C, etc.

• Disadvantages
• XML is verbose
• XML is about 10 times slower than binary network
  protocols such as RMI CORBA

5
How SOAP works
lt?xml version"1.0"?gt ltSOAP-ENVEnvelope
xmlnsSOAP-ENV"http//schemas.xmlsoap.org/soap/e
nvelope/" SOAP-ENVencodingStyle"http//schemas
.xmlsoap.org/soap/encoding/"gt ltSOAP-ENVHeadergt
lt/SOAP-ENV Header gt ltSOAP-ENVBodygt ltSOAP-ENV
Faultgt lt/SOAP-ENVFaultgt lt/SOAP-ENVBodygt lt/SOAP
-ENVEnvelopegt
6
SOAP

• Techniques available for using SOAP within the
  ITM 6.1 environment

7
SOAP and ITM6.1

• IBM provides numerous SOAP methods that allow
  dynamic query and control of ITM 6.1.
• Using IBMs SOAP methods, you can
• start and stop policies and situations
  (CT_Activate and CT_Deactivate)
• forward AF/Remote trapped messages and display
  them on a Universal Message console (CT_WTO)
• retrieve attribute data that you can display in
  charts or reports (CT_Get)
• open and close events (CT_Alert and
  CT_Acknowledge)
• make real-time requests for data (CT_Get)
• issue SOAP requests as system commands in
  policies or in situations (stored in a text file)
  in Tivoli Enterprise Portal (CT_Execute)

8
ITM6.1 Example

• ltSOAP-ENVBodygt
• ltCT_Getgt
• ltuseridgtsysadminlt/useridgt
• ltpassword/gt
• ltobjectgtManagedSystemlt/objectgt
• lt/CT_Getgt
• lt/SOAP-ENVBodygt

Request
9
Accessing the ITM6.1 SOAP Interface
There are 3 options for accessing the SOAP
information within ITM 6.1

• Web page
• Probably best used as a learning Tool
• Limited to browser output
• Command line using kshsoap
• This allows for calls to be added to scripts
• But requires various k.dlls to be used off-TEMS
• Code
• There are many SOAP libraries for most languages,
  e.g. Suns SOAP with Attachments API for Java
  (SAAJ), PERL, Javascript, VBSCRIPT, JSCRIPT and
  C
• This allows for maximum control
• There are no dependencies, just need the TEMS
  SOAP URL

10
Accessing the ITM6.1 SOAP Interface via a Web Page

• http//ltTEMS_SERVERgt1920///cms/soap/kshhsoap.htm

11
Accessing the ITM6.1 SOAP Interface from the
Command Line

• The SOAP client command-line utility, kshsoap, is
  an http client.
• It is found in the directory CANDLE_HOME\cms
• To use it you will need to create 2 files
• SoapReq.txt - specifying the userid, password
  and SOAP call

ltCT_Getgt ltuseridgtsysadminlt/useridgtltpasswordgtlt/pass
wordgt ltobjectgtNT_Processlt/objectgtlttargetgtPrimaryE
UROPENTlt/targetgt lt/CT_Getgt

• URLS.txt specifying the URL to the SOAP server

http//ltTEMS-SERVERgt1920///cms/soap
12
CLI Example

• cd CANDLE_HOME\cms
• kshsoap SoapReq.txt URLS.txt
• ltlt SoapResponse 'http//europe1920///cms/s
  oap' l'112964
• lt?xml version"1.0" encoding"UTF-8"?gt
• ltSOAP-ENVEnvelope xmlnsSOAP-ENVhttp//schemas.x
  mlsoap.org/soap/envelope/
• SOAP-ENVencodingStyle"http//schemas.xmlsoap.o
  rg/soap/encoding/"gt ltSOAP-ENVBodygtltSOAP-CHKSucce
  ss xmlnsSOAP-CHK "http//soaptest1/soaptest/"
  xmlns"urncandle-soapattributes"gtltTABLE
  name"KNT.WTPROCESS"gt
• ltOBJECTgtNT_Processlt/OBJECTgt
• ltDATAgt
• ltROWgt
• ltServer_NamegtPrimaryEUROPENTlt/Server_Namegt
• ltTimestampgt1060602185223163lt/Timestampgt
• ltProcess_NamegtTNR_prog1lt/Process_Namegt
• ltVirtual_kBytes_Peak dt"number"gt1808lt/Virtual_kBy
  tes_Peakgt
• ltHandle_Count dt"number"gt281lt/Handle_Countgt
• ltBinary_Pathgtlt/Binary_Pathgt
• lt/ROWgt
• lt/DATAgt
• lt/TABLEgt

13
Useful Tags
To define a useful query we must know the
following information

14
Useful Tags
In this example we use all these TAGS to query
when free disk space has been exceeded 30GB

ltCT_Getgt ltobjectgtNT_Logical_Disklt/objectgt ltattribu
tegtDisk_Namelt/attributegt ltattributegtFreelt/attribut
egt ltafiltergtFreeGT30lt/afiltergt lthistorygtYlt/histo
rygt lttargetgtPrimaryW2K-TEMSNTlt/targetgt lt/CT_Getgt
15
Determining SOAP Object and Attribute Names

• Objects and attributes are defined in .atr files
  in the directory
• CANDLE_HOME/cms/ATTRLIB
• Look for lines starting name (e.g. grep name
  .atr)
• e.g. in the file knt.atr see the line
• name NT_System.User_Name, name
  NT_System.Server_Name

This would appear like this in SOAP ltobjectgtNT_Sy
stemlt/objectgt ltattributegtUser_Namelt/attributegtltatt
ributegtServer_Namelt/attributegt
16
Workspaces and SOAP Objects

• System SOAP Objects
• NT_Monitored_Logs_Report
• NT_Devices
• NT_Services

• Process SOAP Objects
• NT_Process
• Job_Object
• Job_Object_Details

17
Workspaces and SOAP Objects

• Processor SOAP Objects
• NT_Processor

• Printer SOAP Objects
• Print_Queue
• NT_Printer
• NT_Print_Job

18
Workspaces and SOAP Objects

• Network SOAP Objects
• DHCP_Server
• DNS_Memory
• IP_Statistics
• Network_Interface
• TCP_Statistics

• Disk SOAP Objects
• NT_Logical_Disk

19
Workspaces and SOAP Objects

• Memory SOAP Objects
• NT_Memory
• NT_Cache
• NT_Memory

• Universal Agent SOAP Objects
• UAGENTDPLOG00
• UAGENTACTION00
• INTERNETMANAGED_URL00
• INTERNETURL_OBJECTS00

20
Accessing TEMS database

• Tables and fields are defined in .db .idx
  binary files in the directory
• CANDLE_HOME/cms
• These can be read using something like ultraedit
  in Hex mode (www.ultraedit.com) but be very
  careful not to edit the files!

_at_ 5139O4SRV TRANKENT TYPE NSEY _at_
5140O4SRV TSITDESC ADVISE NSEY _at_
5140O4SRV TSITDESC AFFINITIESNSEY _at_
5140O4SRV TSITDESC ALERTLIST NSEY _at_
5140O4SRV TSITDESC AUTOSOPT NSEY _at_
5140O4SRV TSITDESC AUTOSTART NSEY _at_
5140O4SRV TSITDESC CMD NSEY _at_
5140O4SRV TSITDESC DESTNODE NSEY _at_
5140O4SRV TSITDESC HUB NSEY _at_
5140O4SRV TSITDESC SENDMSGQ NSEY _at_
5140O4SRV TSITDESC SITINFO NSEY _at_
5140O4SRV TSITDESC SITNAME YSEY _at_
5140O4SRV TSITDESC SOURCE NSEY _at_
5140O4SRV TSITDESC TEXT NSEY _at_
5221O4SRV CLACTION ACTPRTY NILN
Sample File QA1CIOBJ.DB
21
Accessing TEMS database

• These definitions can then be used to extract
  data via SOAP using lttablegt and ltsqlgt tags
• For example the file QA1CIOBJ.DB defines the
  table TSITDESC which shows Situation Definitions

ltCT_Getgtltuseridgtsysadminlt/useridgtltpasswordgtlt/passw
ordgt lttablegtO4SRV.UTCTIMElt/tablegtltsqlgtSELECT
ADVISE, AFFINITIES, ALERTLIST, AUTOSOPT,
AUTOSTART, CMD, DESTNODE, HUB, LOCFLAG, LSTCCSID,
LSTDATE, LSTRELEASE, LSTUSRPRF, NOTIFYARGS,
NOTIFYOPTS, OBJECTLOCK, PDT, PRNAMES, QIBSCOPE,
REEV_DAYS, REEV_TIME, REFLEXOK, SENDMSGQ,
SITINFO, SITNAME, TEXT FROM O4SRV.TSITDESClt/sqlgt lt
/CT_Getgt

• This can then be used to insert data (e.g.
  creating a new situation)

22
TEMS Query View Results
lt?xml version"1.0" encoding"UTF-8"?gt ltSOAP-ENVE
nvelope xmlnsSOAP-ENV"http//schemas.xmlsoap.org
/soap/envelope/" SOAP-ENVencodingStyle"http//s
chemas.xmlsoap.org/soap/encoding/"gt
ltSOAP-ENVBodygtltSOAP-CHKSuccess xmlnsSOAP-CHK
"http//soaptest1/soaptest/" xmlns"urncandle-soa
pattributes"gtltTABLE name"O4SRV.UTCTIME"gt ltOBJECT
gtUniversal_Timelt/OBJECTgt ltDATAgt . ltROWgt ltADVISEgtlt
!CDATAADVICE("klz"ISITSTSH.SITNAME)gtlt/ADV
ISEgt ltAFFINITIESgt0000000000000000000000G0000000000
0000000000lt/AFFINITIESgt ltALERTLISTgtlt/ALERTLISTgt ltA
UTOSOPTgtNNNlt/AUTOSOPTgt ltAUTOSTARTgtYESlt/AUTOSTARTgt
ltCMDgtNONElt/CMDgt ltDESTNODEgtlt/DESTNODEgt ltHUBgtlt/HUB
gt ltLOCFLAGgtlt/LOCFLAGgt ltPDTgtIF VALUE
Linux_CPU.Idle_CPU LT 10.0 AND VALUE
Linux_CPU.CPU_ID EQ Aggregatelt/PDTgt ltPRNAMESgtlt/PR
NAMESgt ltQIBSCOPEgtElt/QIBSCOPEgt ltREEV_DAYSgt0lt/REEV_D
AYSgt ltREEV_TIMEgt001500lt/REEV_TIMEgt ltREFLEXOKgtlt/REF
LEXOKgt ltSENDMSGQgtNONElt/SENDMSGQgt ltSITINFOgtSEVWar
ningATOMLNXCPU.CPUIDlt/SITINFOgt ltSITNAMEgtLinux_Hi
gh_CPU_Overloadlt/SITNAMEgt ltTEXTgtKlzKLZ2123lt/TEXTgt
lt/ROWgt
23
Sending an Event using SOAP

• In this example we use a script that can run
  intermittently to check the status of the agents
  and then create a situation called
  Heartbeat_Event
• The situation was created separately and
  associated with the Enterprise view
• The script uses the file called heartbeat.txt to
  pull back the status (shown below) and URLS.txt
  from the earlier example

ltCT_Getgtltuseridgtsysadminlt/useridgtltpasswordgtlt/passw
ordgtltobjectgtManagedSystemlt/objectgt lttargetgtManaged
SystemNamelt/targetgt ltattributegtNamelt/attributegtltat
tributegtStatuslt/attributegtlt/CT_Getgt
24
Sending an Event using SOAP

• The script is called heart_soap.pl and has 3
  important parts
• Get the data about the agents.

open(HBSTATUS,"CANDLE_HOME/cms/kshsoap
CANDLE_HOME/cms/heartbeat.txt CANDLE_HOME/cms/UR
LS.txt ") _at_input ltHBSTATUSgt close HBSTATUS

• Analyse the data

foreach (_at_input) if(/\ltName\gt(.)\(.)\lt\/Name
\gt/) host 1 component 2 x
1 if(/\ltStatus\gt\(.)\lt\/Status\gt/)
status 1 x 2 if (status eq
"OFFLINE")
25
Sending an Event using SOAP

• And lastly send the events to the TEMS using
  CT_Alert if they are OFFLINE.
• Note Any filters you put on a situation are
  bypassed if you send them directly via SOAP.

if (x 2) open(ALERT,"gtc/temp/host.txt") pr
int ALERT ltCT_Alertgtltuseridgtsysadminlt/useridgtltpas
swordgtlt/passwordgt" print ALERT
ltnamegtHeartbeat_Eventlt/namegtltsourcegthostcompon
entlt/sourcegt" print ALERT ltitemgthost is
statuslt/itemgt" print ALERT ltdatagtltUniversal_Mes
sages.Message_Textgtstatus" print ALERT
lt/Universal_Messages.Message_Textgtlt/datagtlt/CT_Ale
rtgt" close ALERT system("CANDLE_HOME/cms/kshsoa
p c/temp/host.txt CANDLE_HOME/cms/URLS.txt")
if (grep(/OFF/,status)) x 3
26
Sending an Event using SOAP
This should now raise the situations and display
them on the TEP.
Situations
27
Soap Documentation

• Appendix C of ITM 6.1 Administrators Guide
• http//publib.boulder.ibm.com/infocenter/tivihelp/
  v3r1/topic/com.ibm.itm.doc/cj195ad.pdf
• W3 Schools good SOAP tutorial
• http//www.w3schools.com/soap/default.asp
• ITM 6.1 IBM Forum
• http//www-128.ibm.com/developerworks/forums/tivol
  i_forums.jsp