Netcool/Impact XML DSA Guide 3.0 and Later - e IBM Tivoli ...
Netcool/Impact XML DSA Guide 3.0 and Later - e IBM Tivoli ...
Netcool/Impact XML DSA Guide 3.0 and Later - e IBM Tivoli ...
You also want an ePaper? Increase the reach of your titles
YUMPU automatically turns print PDFs into web optimized ePapers that Google loves.
frontmatter.fm May 3, 2005<br />
<strong>Netcool</strong>®/<strong>Impact</strong>TM <strong>3.0</strong> <strong>and</strong> <strong>Later</strong><br />
Supporting Products<br />
<strong>XML</strong> <strong>DSA</strong> <strong>Guide</strong>
© 2005 Micromuse Inc., Micromuse Ltd.<br />
All rights reserved. No part of this work may be reproduced in any form or by any<br />
person without prior written permission of the copyright owner. This document is<br />
proprietary <strong>and</strong> confidential to Micromuse, <strong>and</strong> is subject to a confidentiality<br />
agreement, as well as applicable common <strong>and</strong> statutory law.<br />
Micromuse Disclaimer of Warranty <strong>and</strong> Statement of Limited Liability<br />
Micromuse provides this document "as is", without warranty of any kind, either<br />
express or implied, including, but not limited to, the implied warranties of<br />
merchantability, fitness for a particular purpose or non-infringement. This<br />
document may contain technical inaccuracies or typographical errors. Micromuse<br />
may make improvements <strong>and</strong> changes to the programs described in this document<br />
or this document at any time without notice. Micromuse assumes no responsibility<br />
for the use of the programs or this document except as expressly set forth in the<br />
applicable Micromuse agreement(s) <strong>and</strong> subject to terms <strong>and</strong> conditions set forth<br />
therein. Micromuse does not warrant that the functions contained in the programs<br />
will meet your requirements, or that the operation of the programs will be<br />
uninterrupted or error-free. Micromuse shall not be liable for any indirect,<br />
consequential or incidental damages arising out of the use or the ability to use the<br />
programs or this document.<br />
Micromuse specifically disclaims any express or implied warranty of fitness for high<br />
risk activities.<br />
Micromuse programs <strong>and</strong> this document are not certified for fault tolerance, <strong>and</strong><br />
are not designed, manufactured or intended for use or resale as on-line control<br />
equipment in hazardous environments requiring fail-safe performance, such as in<br />
the operation of nuclear facilities, aircraft navigation or communication systems,<br />
air traffic control, direct life support machines, or weapons systems ("High Risk<br />
Activities") in which the failure of programs could lead directly to death, personal<br />
injury, or severe physical or environmental damage.<br />
Compliance with Applicable Laws; Export Control Laws<br />
Use of Micromuse programs <strong>and</strong> documents is governed by all applicable federal,<br />
state <strong>and</strong> local laws. All information therein is subject to U.S. export control laws<br />
<strong>and</strong> may also be subject to the laws of the country where you reside.<br />
All Micromuse programs <strong>and</strong> documents are commercial in nature. Use,<br />
duplication or disclosure by the United States Government is subject to the<br />
restrictions set forth in DFARS 252.227-7015 <strong>and</strong> FAR 52.227-19.<br />
Trademarks <strong>and</strong> Acknowledgements<br />
Micromuse <strong>and</strong> <strong>Netcool</strong> are registered trademarks of Micromuse.<br />
Other Micromuse trademarks include but are not limited to: <strong>Netcool</strong>/OMNIbus,<br />
<strong>Netcool</strong>/OMNIbus for Voice Networks, <strong>Netcool</strong>/Reporter, <strong>Netcool</strong>/Internet<br />
Service Monitors, <strong>Netcool</strong>/ISM, <strong>Netcool</strong>/ISM Global Perspective, <strong>Netcool</strong>/NT<br />
Service Monitors, <strong>Netcool</strong>/Wireless Service Monitors, <strong>Netcool</strong>/WSM,<br />
<strong>Netcool</strong>/Usage Service Monitors, <strong>Netcool</strong>/USM, <strong>Netcool</strong>/Telco Service<br />
Monitors, <strong>Netcool</strong>/TSM, <strong>Netcool</strong>/Fusion, <strong>Netcool</strong>/Data Center Monitors,<br />
<strong>Netcool</strong> DCM, <strong>Netcool</strong>/<strong>Impact</strong>, <strong>Netcool</strong>/Visionary, <strong>Netcool</strong>/Precision, <strong>Netcool</strong><br />
Probes & Monitors, <strong>Netcool</strong> Desktops, <strong>Netcool</strong> Gateways, <strong>Netcool</strong> <strong>Impact</strong>/Data<br />
Source Adaptors, <strong>Netcool</strong> EventList, <strong>Netcool</strong> Map, <strong>Netcool</strong> Virtual Operator,<br />
<strong>Netcool</strong>/Precision for IP Networks, <strong>Netcool</strong>/Precision for Transmission<br />
Networks, <strong>Netcool</strong>/Firewall, <strong>Netcool</strong>/Wave, <strong>Netcool</strong>/Webtop, <strong>Netcool</strong> TopoViz,<br />
<strong>Netcool</strong>/SM Operations, <strong>Netcool</strong>/SM Configuration, <strong>Netcool</strong>/OpCenter,<br />
<strong>Netcool</strong>/System Service Monitors, <strong>Netcool</strong>/SSM, <strong>Netcool</strong>/Application Service<br />
Monitors, <strong>Netcool</strong>/ASM, <strong>Netcool</strong>/ISM WAM, <strong>Netcool</strong>/SM Reporter, <strong>Netcool</strong><br />
for Asset Management, <strong>Netcool</strong>/Realtime Active Dashboards,<br />
<strong>Netcool</strong>/Dashboards, <strong>Netcool</strong>/RAD, <strong>Netcool</strong> for Voice over IP, <strong>Netcool</strong> for<br />
Security Management, <strong>Netcool</strong> Security Manager, <strong>Netcool</strong>/Portal 2.0 Premium<br />
Edition, <strong>Netcool</strong> ObjectServer, <strong>Netcool</strong>/RAD, <strong>Netcool</strong>/Software Developers Kit,<br />
Micromuse Alliance Program, Micromuse Channel Partner, Authorized <strong>Netcool</strong><br />
Reseller, <strong>Netcool</strong> Ready, <strong>Netcool</strong> Solutions, <strong>Netcool</strong> Certified, <strong>Netcool</strong> Certified<br />
Consultant, <strong>Netcool</strong> Certified Trainer, <strong>Netcool</strong> CCAI Methodology, Micromuse<br />
University, Microcorrelation, Acronym, Micromuse Design, Integration Module<br />
for <strong>Netcool</strong>, The <strong>Netcool</strong> Company, VISIONETCOOL, <strong>and</strong> Network Slice.<br />
Micromuse acknowledges the use of I/O Concepts Inc. X-Direct 3270 terminal<br />
emulators <strong>and</strong> hardware components <strong>and</strong> documentation in <strong>Netcool</strong>/Fusion.<br />
X-Direct ©1989-1999 I/O Concepts Inc. X-Direct <strong>and</strong> Win-Direct are<br />
trademarks of I/O Concepts Inc.<br />
<strong>Netcool</strong>/Fusion contains <strong>IBM</strong> Runtime Environment for AIX®, Java<br />
Technology Edition Runtime Modules © Copyright <strong>IBM</strong> Corporation 1999. All<br />
rights reserved.<br />
<strong>Netcool</strong>/Precision IP includes software developed by the University of California,<br />
Berkeley <strong>and</strong> its contributors.<br />
Micromuse acknowledges the use of MySQL in <strong>Netcool</strong>/Precision for IP<br />
Networks. Copyright © 1995, 1996 TcX AB & Monty Program KB & Detron<br />
HB Stockholm SWEDEN, Helsingfors FINLAND <strong>and</strong> Uppsala SWEDEN. All<br />
rights reserved.<br />
Micromuse acknowledges the use of the UCD SNMP Library <strong>Netcool</strong>/ISM.<br />
Copyright © 1989, 1991, 1992 by Carnegie Mellon University. Derivative Work<br />
- Copyright © 1996, 1998, 1999, 2000 The Regents of the University of<br />
California. All rights reserved.<br />
Portions of the <strong>Netcool</strong>/ISM code are copyright ©2001, Cambridge Broadb<strong>and</strong><br />
Ltd. All rights reserved.<br />
Portions of the <strong>Netcool</strong>/ISM code are copyright © 2001, Networks Associates<br />
Technology, Inc. All rights reserved.<br />
Micromuse acknowledges the use of Viador Inc. software <strong>and</strong> documentation for<br />
<strong>Netcool</strong>/Reporter. Viador © 1997-1999 is a trademark of Viador Inc.<br />
Micromuse acknowledges the use of software developed by the Apache Group for<br />
use in the Apache HTTP server project. Copyright © 1995-1999 The Apache<br />
Group. Apache Server is a trademark of the Apache Software Foundation<br />
(http://www.apache.org/). All rights reserved.<br />
Micromuse acknowledges the use of software developed by Edge Technologies,<br />
Inc. 2003 Edge Technologies, Inc. <strong>and</strong> Edge enPortal are trademarks or registered<br />
trademarks of Edge Technologies Inc. All rights reserved.<br />
Micromuse acknowledges the use of Merant drivers. Copyright © MERANT<br />
Solutions Inc., 1991-1998.<br />
The following product names are trademarks of <strong>Tivoli</strong> Systems or <strong>IBM</strong><br />
Corporation: AIX, <strong>IBM</strong>, OS/2, RISC System/6000, <strong>Tivoli</strong> Management<br />
Environment, <strong>and</strong> TME10.<br />
<strong>IBM</strong>, NetView/6000, Domino, Lotus, Lotus Notes, <strong>and</strong> WebSphere are either<br />
trademarks or registered trademarks of <strong>IBM</strong> Corporation. VTAM is a trademark<br />
of <strong>IBM</strong> Corporation.<br />
Omegamon is a trademark of C<strong>and</strong>le Corporation.<br />
Netspy is a trademark of Computer Associates International Inc.<br />
The Sun logo, Sun Microsystems, SunOS, Solaris, SunNet Manager, Java are<br />
trademarks of Sun Microsystems Inc.<br />
SPARC is a registered trademark of SPARC International Inc. Programs bearing<br />
the SPARC trademark are based on an architecture developed by Sun<br />
Microsystems Inc. SPARCstation is a trademark of SPARC International Inc.,<br />
licensed exclusively to Sun Microsystems Inc.<br />
UNIX is a registered trademark of the X/Open Company Ltd.<br />
Sybase is a registered trademark of Sybase Inc. Adaptive Server is a trademark of<br />
Sybase Inc.<br />
Action Request System <strong>and</strong> Remedy are registered trademarks of Remedy<br />
Corporation.<br />
Peregrine System <strong>and</strong> ServiceCenter are registered trademarks of Peregrine Systems<br />
Inc.<br />
HP, HP-UX <strong>and</strong> OpenView are trademarks of Hewlett-Packard Company.<br />
InstallShield is a registered trademark of InstallShield Software Corporation.
Microsoft, Windows 95/98/Me/NT/2000/XP are either registered trademarks or<br />
trademarks of Microsoft Corporation.<br />
Microsoft Internet Information Server/Services (IIS), Microsoft Exchange Server,<br />
Microsoft SQL Server, Microsoft perfmon <strong>and</strong> Microsoft Cluster Service are<br />
registered trademarks of Microsoft Corporation.<br />
BEA <strong>and</strong> WebLogic are registered trademarks of BEA Systems Inc.<br />
FireWall-1 is a registered trademark of Check Point Software Technologies Ltd.<br />
Netscape <strong>and</strong> Netscape Navigator are registered trademarks of Netscape<br />
Communications Corporation in the United States <strong>and</strong> other countries.<br />
Netscape's logos <strong>and</strong> Netscape product <strong>and</strong> service names are also trademarks of<br />
Netscape Communications Corporation, which may be registered in other<br />
countries.<br />
Micromuse acknowledges the use of Xpm tool kit components.<br />
SentinelLM is a trademark of Rainbow Technologies Inc.<br />
GLOBEtrotter <strong>and</strong> FLEXlm are registered trademarks of Globetrotter Software<br />
Inc.<br />
Red Hat, the Red Hat "Shadow Man" logo, RPM, Maximum RPM, the RPM<br />
logo, Linux Library, PowerTools, Linux Undercover, RHmember, RHmember<br />
More, Rough Cuts, Rawhide <strong>and</strong> all Red Hat-based trademarks <strong>and</strong> logos are<br />
trademarks or registered trademarks of Red Hat Inc. in the United States <strong>and</strong> other<br />
countries.<br />
Linux is a registered trademark of Linus Torvalds.<br />
Nokia is a registered trademark of Nokia Corporation.<br />
WAP Forum <strong>and</strong> all trademarks, service marks <strong>and</strong> logos based on these<br />
designations (Trademarks) are marks of Wireless Application Protocol Forum Ltd.<br />
Micromuse acknowledges the use of InstallAnywhere software in <strong>Netcool</strong>/WAP<br />
Service Monitors. Copyright © Zero G Software Inc.<br />
Orbix is a registered trademark of IONA Technologies PLC. Orbix 2000 is a<br />
trademark of IONA Technologies PLC.<br />
Micromuse acknowledges the use of Graph Layout Toolkit in <strong>Netcool</strong>/ Precision<br />
for IP Networks. Copyright © 1992 - 2001, Tom Sawyer Software, Berkeley,<br />
California. All rights reserved.<br />
Portions of <strong>Netcool</strong>/Precision for IP Networks are © TIBCO Software, Inc.<br />
1994-2003. All rights reserved. TIB <strong>and</strong> TIB/Rendezvous are trademarks of<br />
TIBCO Software, Inc.<br />
Portions of <strong>Netcool</strong>/Precision for IP Networks are Copyright © 1996-2003,<br />
Daniel Stenberg, .<br />
Micromuse acknowledges the use of Digital X11 in <strong>Netcool</strong>/Precision for IP<br />
Networks. Copyright 1987, 1988 by Digital Equipment Corporation, Maynard,<br />
Massachusetts, All Rights Reserved. DIGITAL DISCLAIMS ALL<br />
WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL<br />
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN<br />
NO EVENT SHALL DIGITAL BE LIABLE FOR ANY SPECIAL, INDIRECT<br />
OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER<br />
RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN<br />
AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS<br />
ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR<br />
PERFORMANCE OF THIS SOFTWARE.<br />
<strong>Netcool</strong>/SM Operations, <strong>Netcool</strong>/SM Configuration <strong>and</strong> <strong>Netcool</strong>/OpCenter<br />
include software developed by the OpenSSL Project for use in the OpenSSL<br />
Toolkit (http://www.openssl.org/).<br />
Micromuse acknowledges the use of software developed by ObjectPlanet. ©2003<br />
ObjectPlanet, Inc, Ovre Slottsgate, 0157 Oslo, Norway.<br />
Micromuse acknowledges the use of Expat in <strong>Netcool</strong>/ASM. Copyright 1998,<br />
1999, 2000 Thai Open Source Software Center Ltd <strong>and</strong> Clark Cooper. Copyright<br />
2001, 2002 Expat maintainers. THE EXPAT SOFTWARE IS PROVIDED<br />
HEREUNDER "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS<br />
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES<br />
OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND<br />
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR<br />
COPYRIGHT HOLDERS OF THE EXPAT SOFTWARE BE LIABLE FOR<br />
ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN<br />
ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,<br />
OUT OF OR IN CONNECTION WITH THE EXPAT SOFTWARE OR<br />
THE USE OR OTHER DEALINGS IN THE SOFTWARE. Expat explicitly<br />
grants its permission to any person obtaining a copy of any Expat software <strong>and</strong><br />
associated documentation files (the "Expat Software") to deal in the Expat<br />
Software without restriction, including without limitation the rights to use, copy,<br />
modify, merge, publish, distribute, sublicense, <strong>and</strong>/or sell copies of the Expat<br />
Software. Expat's permission is subject to the following conditions: The above<br />
copyright notice <strong>and</strong> this permission notice shall be included in all copies or<br />
substantial portions of the Expat Software. Except as set forth hereunder, all<br />
software provided by Micromuse hereunder is subject to the applicable license<br />
agreement.<br />
Micromuse acknowledges that <strong>Netcool</strong> Security Manager includes Hypersonic<br />
SQL. Copyright (c) 2001-2002, The HSQL Development Group. All rights<br />
reserved.<br />
JABBER® is a registered trademark <strong>and</strong> its use is granted under a sublicense from<br />
the Jabber Software Foundation.<br />
Micromuse acknowledges the use of MySQL in <strong>Netcool</strong>/Precision for IP<br />
Networks <strong>and</strong> in <strong>Netcool</strong>/Precision for Transmission Networks. Copyright ©<br />
1995, 1996 TcX AB & Monty Program KB & Detron.<br />
Micromuse acknowledges the use of Cryptix in <strong>Netcool</strong>/Precision IP. Copyright<br />
(c) 1995-2004 The Cryptix Foundation Limited. All rights reserved.<br />
Redistribution <strong>and</strong> use in source <strong>and</strong> binary forms, with or without modification,<br />
are permitted provided that the following conditions are met:<br />
1. Redistributions of source code must retain the copyright notice, this list of<br />
conditions <strong>and</strong> the following disclaimer.<br />
2. Redistributions in binary form must reproduce the above copyright notice, this<br />
list of conditions <strong>and</strong> the following disclaimer in the documentation <strong>and</strong>/or other<br />
materials provided with the distribution.<br />
THIS SOFTWARE IS PROVIDED BY THE CRYPTIX FOUNDATION<br />
LIMITED AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR<br />
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE<br />
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A<br />
PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE<br />
CRYPTIX FOUNDATION LIMITED OR CONTRIBUTORS BE LIABLE<br />
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,<br />
OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED<br />
TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS<br />
OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)<br />
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,<br />
WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT<br />
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY<br />
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE<br />
POSSIBILITY OF SUCH DAMAGE.<br />
All other trademarks, registered trademarks <strong>and</strong> logos are the property of their<br />
respective owners.<br />
Micromuse Inc., 139 Townsend Street, San Francisco, USA CA 94107<br />
www.micromuse.com<br />
Document Version Number: 1.2
Contents<br />
<strong>Netcool</strong>/<strong>Impact</strong> <strong>XML</strong> <strong>DSA</strong> <strong>Guide</strong>. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1<br />
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2<br />
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2<br />
System Requirements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2<br />
Licensing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2<br />
Architecture. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4<br />
Concepts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5<br />
<strong>XML</strong> Documents. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5<br />
<strong>XML</strong> DTD <strong>and</strong> XSD Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5<br />
<strong>XML</strong> Data Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5<br />
Create Data Types Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6<br />
<strong>XML</strong> Configuration Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6<br />
<strong>XML</strong> Document <strong>and</strong> Data Type Mapping. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7<br />
Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7<br />
Setting Up the <strong>DSA</strong> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9<br />
Installing the <strong>DSA</strong> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9<br />
Contents<br />
Installation Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10<br />
Creating <strong>XML</strong> Data Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11<br />
Running the Create Types Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11<br />
Setting Up Data Type Mappings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13<br />
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13<br />
Setting Up Mappings for <strong>XML</strong> Files <strong>and</strong> Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13<br />
Setting Up Mappings for <strong>XML</strong> Over HTTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15<br />
<strong>Netcool</strong>/<strong>Impact</strong> <strong>3.0</strong> <strong>and</strong> <strong>Later</strong> <strong>XML</strong> <strong>DSA</strong> <strong>Guide</strong> i
Contents<br />
ii<br />
Reading <strong>XML</strong> Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17<br />
Retrieving the Document Data Item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17<br />
Retrieving the Root-Level Element Data Item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19<br />
Retrieving Child Element Data Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20<br />
Accessing Attribute Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20<br />
Sample Policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21<br />
XmlStringTestPolicy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21<br />
XmlFileTestPolicy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21<br />
XmlHttpTestPolicy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22<br />
XmlXsdFileTestPolicy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23<br />
Contact Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25<br />
<strong>Netcool</strong>/<strong>Impact</strong> <strong>3.0</strong> <strong>and</strong> <strong>Later</strong> <strong>XML</strong> <strong>DSA</strong> <strong>Guide</strong>
section.fm May 4, 2005<br />
<strong>Netcool</strong>/<strong>Impact</strong> <strong>XML</strong> <strong>DSA</strong> <strong>Guide</strong><br />
This guide contains information on installing <strong>and</strong> using the <strong>Netcool</strong>/<strong>Impact</strong> <strong>XML</strong> <strong>DSA</strong>.<br />
It contains the following sections:<br />
• Introduction on page 2<br />
Architecture on page 4<br />
Concepts on page 5<br />
<strong>XML</strong> Document <strong>and</strong> Data Type Mapping on page 7<br />
Setting Up the <strong>DSA</strong> on page 9<br />
Creating <strong>XML</strong> Data Types on page 11<br />
Setting Up Data Type Mappings on page 13<br />
Reading <strong>XML</strong> Documents on page 17<br />
Sample Policies on page 21<br />
<strong>Netcool</strong>/<strong>Impact</strong> <strong>3.0</strong> <strong>and</strong> <strong>Later</strong> <strong>XML</strong> <strong>DSA</strong> <strong>Guide</strong> 1
<strong>Netcool</strong>/<strong>Impact</strong> <strong>XML</strong> <strong>DSA</strong> <strong>Guide</strong><br />
Introduction<br />
Overview<br />
2<br />
This section contains an introduction to the <strong>Netcool</strong>®/<strong>Impact</strong> <strong>XML</strong> <strong>DSA</strong>. It contains the following<br />
topics:<br />
Overview<br />
System Requirements<br />
Licensing<br />
The <strong>XML</strong> <strong>DSA</strong> is an add-in component that allows <strong>Netcool</strong>/<strong>Impact</strong> to read <strong>XML</strong> data from strings, files,<br />
<strong>and</strong> HTTP servers.<br />
The <strong>DSA</strong> works by providing a mapping between an <strong>XML</strong> document <strong>and</strong> a set of <strong>Netcool</strong>/<strong>Impact</strong> data<br />
types. The <strong>DSA</strong> uses the information in an <strong>XML</strong> DTD or XSD file to underst<strong>and</strong> the structure of the <strong>XML</strong><br />
data <strong>and</strong> to map the data to the corresponding data types in <strong>Netcool</strong>/<strong>Impact</strong>.<br />
To set up <strong>Netcool</strong>/<strong>Impact</strong> to read <strong>XML</strong> data, you run a script that creates the <strong>XML</strong> data types <strong>and</strong> then you<br />
specify the associated mapping information in an <strong>XML</strong> configuration file. Once you have set up<br />
<strong>Netcool</strong>/<strong>Impact</strong>, you can read the <strong>XML</strong> data in a policy using the GetByFilter <strong>and</strong> GetByLinks<br />
functions.<br />
System Requirements<br />
Licensing<br />
The <strong>XML</strong> <strong>DSA</strong> requires <strong>Netcool</strong>/<strong>Impact</strong> <strong>3.0</strong> or 3.1. Refer to the appropriate version of the <strong>Netcool</strong>/<strong>Impact</strong><br />
Administration <strong>Guide</strong> for a list of supported platforms.<br />
The license file format <strong>and</strong> license feature codes have changed in <strong>Netcool</strong>/<strong>Impact</strong> 3.1 to provide support for<br />
Quorum licensing.<br />
For <strong>Netcool</strong>/<strong>Impact</strong> <strong>3.0</strong>, the <strong>DSA</strong> for <strong>XML</strong> uses the nci_dsamediator_xml license feature<br />
code.<br />
For <strong>Netcool</strong>/<strong>Impact</strong> 3.1, the <strong>DSA</strong> for <strong>XML</strong> uses the cro_ncidsamediator_xml license feature<br />
code.<br />
Contact the Micromuse licensing team at<br />
http://support.micromuse.com/helpdesk/licenses for more information on installing<br />
licenses.<br />
<strong>Netcool</strong>/<strong>Impact</strong> <strong>3.0</strong> <strong>and</strong> <strong>Later</strong> <strong>XML</strong> <strong>DSA</strong> <strong>Guide</strong>
<strong>Netcool</strong>/<strong>Impact</strong> <strong>3.0</strong> <strong>and</strong> <strong>Later</strong> <strong>XML</strong> <strong>DSA</strong> <strong>Guide</strong><br />
Introduction<br />
To install licenses, follow the instructions for licensing <strong>Netcool</strong>/<strong>Impact</strong> components in the <strong>Netcool</strong>/<strong>Impact</strong><br />
Administration <strong>Guide</strong>.<br />
3
<strong>Netcool</strong>/<strong>Impact</strong> <strong>XML</strong> <strong>DSA</strong> <strong>Guide</strong><br />
Architecture<br />
4<br />
The following figure shows the logical relationship between the <strong>Netcool</strong>/<strong>Impact</strong> server, the <strong>XML</strong> <strong>DSA</strong>, <strong>and</strong><br />
<strong>XML</strong> data sources.<br />
<strong>Netcool</strong>/<br />
<strong>Impact</strong><br />
Server<br />
<strong>DSA</strong><br />
Figure 1: <strong>XML</strong> <strong>DSA</strong> Architecture<br />
Internet or<br />
Intranet<br />
HTTP<br />
Services<br />
<strong>XML</strong> Files<br />
<strong>XML</strong> Strings<br />
<strong>Netcool</strong>/<strong>Impact</strong> <strong>3.0</strong> <strong>and</strong> <strong>Later</strong> <strong>XML</strong> <strong>DSA</strong> <strong>Guide</strong>
Concepts<br />
This section contains information about concepts related to the <strong>DSA</strong>. It contains the following topics:<br />
<strong>XML</strong> Documents<br />
<strong>XML</strong> DTD Files<br />
<strong>XML</strong> XSD Files<br />
<strong>XML</strong> Data Types<br />
<strong>XML</strong> Documents<br />
Create Data Types Scripts<br />
<strong>XML</strong> Configuration Files<br />
<strong>Netcool</strong>/<strong>Impact</strong> <strong>3.0</strong> <strong>and</strong> <strong>Later</strong> <strong>XML</strong> <strong>DSA</strong> <strong>Guide</strong><br />
Concepts<br />
The <strong>DSA</strong> considers an <strong>XML</strong> document to be any well-formed set of <strong>XML</strong> data that descends from a single<br />
root element. This document can be located in a string, in a text file, or on an HTTP server.<br />
<strong>XML</strong> DTD <strong>and</strong> XSD Files<br />
<strong>XML</strong> DTD <strong>and</strong> XSD files contain a document type description. You must provide an <strong>XML</strong> DTD or XSD<br />
file for each type of <strong>XML</strong> document that you want the <strong>DSA</strong> to read.<br />
<strong>XML</strong> Data Types<br />
<strong>XML</strong> data types are <strong>Netcool</strong>/<strong>Impact</strong> data types that represent <strong>XML</strong> documents <strong>and</strong> their contents. The <strong>DSA</strong><br />
uses the following <strong>XML</strong> data types:<br />
Super data types<br />
Element data types<br />
Super Data Types<br />
Super data types are data types that represent types of <strong>XML</strong> documents. The <strong>DSA</strong> uses one such data type<br />
for each type of document that it reads.<br />
A super data type contains a single data item, called the document data item. This data item represents the<br />
instance of the document that is currently in use by the <strong>DSA</strong>. The display name of the document data item<br />
is the same as the name of the super data type. The document data item contains a static link to the element<br />
data item that represents the root-level element of the document.<br />
5
<strong>Netcool</strong>/<strong>Impact</strong> <strong>XML</strong> <strong>DSA</strong> <strong>Guide</strong><br />
6<br />
Element Data Types<br />
Element data types represent the elements in an <strong>XML</strong> document. The <strong>DSA</strong> requires one such data type for<br />
each type of <strong>XML</strong> element. An element data type contains one field for each attribute in the corresponding<br />
<strong>XML</strong> element. In addition, the data type contains a field that corresponds to the element’s PCDATA value,<br />
if any.<br />
Element data types contain one or more data items called element data items. Each such data item represents<br />
an instance of the element in the document.<br />
The hierarchical relationship between <strong>XML</strong> elements is represented at the data item level by static links.<br />
Element data items are statically linked in such a way that each data item contains links to other data items<br />
that represent the child elements of the corresponding element in the <strong>XML</strong> document.<br />
Element namespaces are a convention used by the <strong>DSA</strong> to show that a set of element data types are related<br />
to a single <strong>XML</strong> document. The <strong>DSA</strong> uses element namespaces to avoid ambiguity in cases where more than<br />
one type of <strong>XML</strong> document used by the <strong>DSA</strong> has an element of the same name.<br />
Create Data Types Scripts<br />
The <strong>XML</strong> <strong>DSA</strong> provides two scripts that you can use to create <strong>XML</strong> data types in <strong>Netcool</strong>/<strong>Impact</strong>. You use<br />
one script to create data types from an <strong>XML</strong> DTD <strong>and</strong> the other to create data types from an <strong>XML</strong> XSD.<br />
On UNIX platforms, these scripts are named CreateDtdTypes.sh <strong>and</strong> CreateXsdTypes.sh.<br />
On Windows platforms, these scripts are named CreateDtdTypes.bat <strong>and</strong><br />
CreateXsdTypes.bat. These scripts are located in the $IMPACT_HOME/dsa/XmlDsa/bin<br />
directory.<br />
For more information on these scripts, see Creating <strong>XML</strong> Data Types on page 11.<br />
<strong>XML</strong> Configuration Files<br />
<strong>XML</strong> configuration files are text files that store mapping information for <strong>XML</strong> data types. The <strong>DSA</strong> reads<br />
the configuration files at startup <strong>and</strong> uses the information during run time to locate the DTD or XSD file<br />
<strong>and</strong> data source for each <strong>XML</strong> document. For more information about <strong>XML</strong> configuration files, see Setting<br />
Up Data Type Mappings on page 13.<br />
<strong>Netcool</strong>/<strong>Impact</strong> <strong>3.0</strong> <strong>and</strong> <strong>Later</strong> <strong>XML</strong> <strong>DSA</strong> <strong>Guide</strong>
<strong>XML</strong> Document <strong>and</strong> Data Type Mapping<br />
Example<br />
<strong>Netcool</strong>/<strong>Impact</strong> <strong>3.0</strong> <strong>and</strong> <strong>Later</strong> <strong>XML</strong> <strong>DSA</strong> <strong>Guide</strong><br />
<strong>XML</strong> Document <strong>and</strong> Data Type Mapping<br />
The <strong>XML</strong> <strong>DSA</strong> works by providing a mapping between an <strong>XML</strong> document <strong>and</strong> a set of <strong>Netcool</strong>/<strong>Impact</strong><br />
data types. The <strong>DSA</strong> uses the information in an <strong>XML</strong> DTD or XSD file to underst<strong>and</strong> the structure of the<br />
<strong>XML</strong> data <strong>and</strong> to map the data to the corresponding data types in <strong>Netcool</strong>/<strong>Impact</strong>.<br />
One aspect of the structure of the <strong>XML</strong> data is the hierarchical relationship between <strong>XML</strong> elements. The<br />
<strong>DSA</strong> maps this relationship to the <strong>XML</strong> data types using static links, where each element data item is linked<br />
to its logical child data item by a static link. When you read the <strong>XML</strong> data in a policy, you traverse the<br />
resulting structure using the GetByLinks function. You can also traverse the structure using<br />
<strong>Netcool</strong>/<strong>Impact</strong>’s embedded linking syntax.<br />
This example shows an <strong>XML</strong> document <strong>and</strong> the linking relationship between the corresponding element<br />
data items in <strong>Netcool</strong>/<strong>Impact</strong>.<br />
The following is a sample partial <strong>XML</strong> document:<br />
<br />
<br />
Micromuse<br />
Alert<br />
<br />
<br />
NodeXYZ<br />
Node not responding<br />
<br />
<br />
Figure 2 on page 8 <strong>and</strong> Figure 1 on page 4 show the linking relationship between the corresponding element<br />
data items:<br />
7
<strong>Netcool</strong>/<strong>Impact</strong> <strong>XML</strong> <strong>DSA</strong> <strong>Guide</strong><br />
8<br />
Data Type:<br />
<strong>XML</strong>_sender<br />
PCDATA:<br />
Micromuse<br />
Data Type:<br />
<strong>XML</strong>_head<br />
Data Type:<br />
<strong>XML</strong>_subject<br />
PCDATA:<br />
Alert<br />
Data Type:<br />
<strong>XML</strong>_alert<br />
ID:<br />
0123456789<br />
Data Type:<br />
<strong>XML</strong>_node<br />
PCDATA:<br />
NodeXYZ<br />
Figure 2: Linking Relationships between Corresponding Element Data Items<br />
Data Type:<br />
<strong>XML</strong>_body<br />
Data Type:<br />
<strong>XML</strong>_summary<br />
PCDATA:<br />
Node not<br />
responding<br />
<strong>Netcool</strong>/<strong>Impact</strong> <strong>3.0</strong> <strong>and</strong> <strong>Later</strong> <strong>XML</strong> <strong>DSA</strong> <strong>Guide</strong>
Setting Up the <strong>DSA</strong><br />
To set up the <strong>XML</strong> <strong>DSA</strong>, do the following:<br />
Install the <strong>DSA</strong><br />
Create the <strong>XML</strong> data types<br />
Set up data type mapping<br />
Installing the <strong>DSA</strong><br />
<strong>Netcool</strong>/<strong>Impact</strong> <strong>3.0</strong> <strong>and</strong> <strong>Later</strong> <strong>XML</strong> <strong>DSA</strong> <strong>Guide</strong><br />
Setting Up the <strong>DSA</strong><br />
To install the <strong>DSA</strong>, you run the install script <strong>and</strong> follow the on-screen prompts. On UNIX platforms, the<br />
script is named is named installMediator.sh. On Windows platforms, the script is named<br />
install.bat. Before you run the installation script, make sure the <strong>Netcool</strong>/<strong>Impact</strong> server is running.<br />
The install script copies the <strong>DSA</strong> program files to the $IMPACT_HOME/dsa/XmlDsa directory, inserts<br />
sample policies <strong>and</strong> the data types needed for the sample policies, <strong>and</strong> initializes the <strong>DSA</strong>.<br />
The install script prompts you for the information in Table 1:<br />
Table 1: <strong>DSA</strong> Install Script Prompts<br />
Prompt Description<br />
<strong>Netcool</strong>/<strong>Impact</strong> server name Name of the <strong>Netcool</strong>/<strong>Impact</strong> server where you want to<br />
install the <strong>DSA</strong>. The default is NCI.<br />
Username <strong>and</strong> password Valid <strong>Netcool</strong> Security Manager username <strong>and</strong> password.<br />
Additional jar files Not used by the <strong>XML</strong> <strong>DSA</strong> installer.<br />
Installing on UNIX Platforms<br />
To install on UNIX platforms:<br />
1. Obtain the <strong>DSA</strong> tar file from the Micromuse support site or product CD.<br />
2. Copy the tar file to a temporary directory.<br />
3. At a comm<strong>and</strong> prompt, unpack the tar file using the following comm<strong>and</strong>:<br />
tar -xf XmlDsa*.tar<br />
4. Run the install script by typing the following comm<strong>and</strong>:<br />
./installMediator.sh<br />
5. Follow the on-screen prompts.<br />
9
<strong>Netcool</strong>/<strong>Impact</strong> <strong>XML</strong> <strong>DSA</strong> <strong>Guide</strong><br />
10<br />
After installation, you must stop <strong>and</strong> restart the <strong>Netcool</strong>/<strong>Impact</strong> server.<br />
Installing on Windows Platforms<br />
To install on Windows platforms:<br />
1. Obtain the <strong>DSA</strong> tar file from the Micromuse support site or product CD-ROM.<br />
2. Copy the tar file to a temporary directory.<br />
3. Extract the contents of the <strong>DSA</strong> tar file to a temporary directory using a file compression utility.<br />
4. At a comm<strong>and</strong> prompt, change the current directory to the location where you extracted the files <strong>and</strong><br />
run the install script as follows:<br />
cd C:\Windows\directory<br />
install.bat<br />
5. Follow the on-screen prompts.<br />
After installation, you must stop <strong>and</strong> restart the <strong>Netcool</strong>/<strong>Impact</strong> server.<br />
Installation Files<br />
The following table shows the files installed by the install script:<br />
Table 2: Installation Files<br />
File Description<br />
<strong>DSA</strong> jar file XmlDsadate.jar, where date is the build date for the <strong>DSA</strong>. Located in<br />
$IMPACT_HOME/dsa/XmlDsa.<br />
<strong>DSA</strong> properties file XmlDsa.properties. Located in $IMPACT_HOME/dsa/XmlDsa .<br />
<strong>XML</strong> setup scripts Located in $IMPACT_HOME/dsa/XmlDsa/bin.<br />
<strong>XML</strong> configuration<br />
scripts<br />
XmlFileTypes <strong>and</strong> XmlHttpTypes. Located in $IMPACT_HOME/dsa/XmlDsa.<br />
Sample policies Installed on the target <strong>Netcool</strong>/<strong>Impact</strong> server.<br />
Sample <strong>XML</strong>, DTD <strong>and</strong><br />
XSD files<br />
TOC.xml,TOC.dtd, <strong>and</strong> TOC.xsd files. Located in $IMPACT_HOME/dsa/XmlDsa.<br />
<strong>Netcool</strong>/<strong>Impact</strong> <strong>3.0</strong> <strong>and</strong> <strong>Later</strong> <strong>XML</strong> <strong>DSA</strong> <strong>Guide</strong>
Creating <strong>XML</strong> Data Types<br />
<strong>Netcool</strong>/<strong>Impact</strong> <strong>3.0</strong> <strong>and</strong> <strong>Later</strong> <strong>XML</strong> <strong>DSA</strong> <strong>Guide</strong><br />
Creating <strong>XML</strong> Data Types<br />
After you have installed the <strong>DSA</strong>, you must create a set of <strong>XML</strong> data types that corresponds to the structure<br />
of the <strong>XML</strong> document you want to read using <strong>Netcool</strong>/<strong>Impact</strong>.<br />
To create the <strong>XML</strong> data types, you run either the create DTD types script or the create XSD types script,<br />
depending on which type of schema you are using.<br />
On UNIX platforms, these scripts are named CreateDtdTypes.sh <strong>and</strong> CreateXsdTypes.sh.<br />
On Windows platforms, these scripts are named CreateDtdTypes.bat <strong>and</strong><br />
CreateXsdTypes.bat. These scripts are located in the $IMPACT_HOME/dsa/XmlDsa/bin<br />
directory.<br />
When you run a create types script, it creates a super data type <strong>and</strong> then reads the <strong>XML</strong> DTD or XSD file<br />
<strong>and</strong> creates one element data type for each type of element defined in the file, including the root-level<br />
element. The script uses the names of the elements in the DTD or XSD file for the names of the element<br />
data types. If you specify an element namespace, it is prepended to the name of each element data type. The<br />
script then inserts the data types into <strong>Netcool</strong>/<strong>Impact</strong> using the comm<strong>and</strong> line service.<br />
Note: The create types scripts replace any colon character that appears in <strong>XML</strong> element names with an<br />
underscore when creating the data types. For example, if a DTD file contains an element named<br />
netcool:alert, the create DTD types script creates a corresponding element data type named<br />
netcool_alert.<br />
Running the Create Types Scripts<br />
You run the create types scripts from the comm<strong>and</strong> line <strong>and</strong> provide the required comm<strong>and</strong> line options.<br />
Make sure that the <strong>Netcool</strong>/<strong>Impact</strong> server is running before you start the script.<br />
The following table shows the comm<strong>and</strong> line options for the script:<br />
Table 3: CreateTypes Options (1 of 2)<br />
Option Description<br />
server_name Name of the server where <strong>Netcool</strong>/<strong>Impact</strong> is running.<br />
user Name of the <strong>Netcool</strong>/<strong>Impact</strong> user.<br />
password <strong>Netcool</strong>/<strong>Impact</strong> user’s password.<br />
dtdFileName Path <strong>and</strong> filename of the <strong>XML</strong> DTD file that describes the <strong>XML</strong> document. The<br />
path is relative to the $IMPACT_HOME/dsa/XmlDsa/bin directory.<br />
xsdFileName Path <strong>and</strong> filename of the <strong>XML</strong> XSD file that describes the <strong>XML</strong> document. The<br />
path is relative to the $IMPACT_HOME/dsa/XmlDsa/bin directory.<br />
11
<strong>Netcool</strong>/<strong>Impact</strong> <strong>XML</strong> <strong>DSA</strong> <strong>Guide</strong><br />
12<br />
Table 3: CreateTypes Options (2 of 2)<br />
Option Description<br />
type_name Name of the resulting super data type. The string specified using the<br />
NameSpacePrefix argument is not prepended to the name of the super data<br />
type.<br />
namespace_prefix Optional string prepended to the names of element data types.<br />
To run the create data types scripts, do the following:<br />
1. Make sure that the <strong>Netcool</strong>/<strong>Impact</strong> server is running.<br />
2. At a comm<strong>and</strong> prompt, change the current directory to $IMPACT_HOME/dsa/XmlDsa/bin.<br />
3. Enter the following:<br />
./CreateDtdTypes.sh server_name user password dtdFile type_name<br />
[namespace_prefix]<br />
or<br />
./CreateXsdTypes.sh server_name user password xsdFile type_name<br />
[namespace_prefix]<br />
where the comm<strong>and</strong> line arguments are as described in the table above.<br />
<strong>Netcool</strong>/<strong>Impact</strong> <strong>3.0</strong> <strong>and</strong> <strong>Later</strong> <strong>XML</strong> <strong>DSA</strong> <strong>Guide</strong>
Setting Up Data Type Mappings<br />
Overview<br />
<strong>Netcool</strong>/<strong>Impact</strong> <strong>3.0</strong> <strong>and</strong> <strong>Later</strong> <strong>XML</strong> <strong>DSA</strong> <strong>Guide</strong><br />
Setting Up Data Type Mappings<br />
This section contains information on setting up data type mappings. It contains the following topics:<br />
Overview<br />
Setting Up Mappings for <strong>XML</strong> Files <strong>and</strong> Strings<br />
Setting Up Mappings for <strong>XML</strong> Over HTTP<br />
After you have created <strong>XML</strong> data types, you must set up data type mappings. A data type mapping is a set<br />
of information that shows the relationship between an <strong>XML</strong> data source, an <strong>XML</strong> document <strong>and</strong> <strong>XML</strong> data<br />
types. The <strong>DSA</strong> uses this information to map the contents of an <strong>XML</strong> document to the data types in<br />
<strong>Netcool</strong>/<strong>Impact</strong>. You must set up one data type mapping for each type of <strong>XML</strong> document you want<br />
<strong>Netcool</strong>/<strong>Impact</strong> to read.<br />
Data type mapping information is stored in <strong>XML</strong> configuration files. The <strong>DSA</strong> uses the following <strong>XML</strong><br />
configuration files:<br />
XmlFileTypes<br />
XmlHttpTypes<br />
These files are located in the $IMPACT_HOME/dsa/XmlDsa directory.<br />
Note: After you have edited the data types, you must stop <strong>and</strong> restart the <strong>Netcool</strong>/<strong>Impact</strong> server.<br />
Setting Up Mappings for <strong>XML</strong> Files <strong>and</strong> Strings<br />
For each <strong>XML</strong> string or file that you want the <strong>DSA</strong> to read, you must add the following mapping<br />
information to the XmlFileTypes file:<br />
Name of the super data type<br />
Path <strong>and</strong> filename of the corresponding <strong>XML</strong> DTD/XSD file<br />
Path <strong>and</strong> filename of the corresponding <strong>XML</strong> file (<strong>XML</strong> files only)<br />
Namespace prefix used for the element data types (optional)<br />
13
<strong>Netcool</strong>/<strong>Impact</strong> <strong>XML</strong> <strong>DSA</strong> <strong>Guide</strong><br />
14<br />
You specify mapping information in the file using the following format:<br />
XmlDsa.fileTypes.n.property .value<br />
where n is a numeric value that identifies the mapping, property is the name of the mapping property,<br />
<strong>and</strong> value is the value.<br />
The following table shows the mapping properties in the XmlFileTypes file:<br />
Table 4: XmlFileTypes Mapping Properties<br />
Property Description<br />
typeName Name of the corresponding super data type.<br />
dtdFile Path <strong>and</strong> filename of a corresponding <strong>XML</strong> DTD file. The path can be an absolute<br />
path or a path relative to the $IMPACT_HOME directory. Used only if the <strong>XML</strong><br />
schema is a DTD.<br />
xsdFile Path <strong>and</strong> filename of a corresponding <strong>XML</strong> XSD file. The path can be an absolute<br />
path or a path relative to the $IMPACT_HOME directory. Used only if the <strong>XML</strong><br />
schema is an XSD.<br />
isXsd This boolean variable specifies whether the schema is defined in XSD or DTD<br />
format. If it is not specified, the default is DTD format.<br />
xmlFile For <strong>XML</strong> files, the path <strong>and</strong> filename of the corresponding file. The path is relative<br />
to the $IMPACT_HOME directory. For <strong>XML</strong> strings, use the hyphen character as a<br />
placeholder.<br />
prefix Namespace prefix used to identify the corresponding element data types<br />
(optional).<br />
Examples<br />
The following example shows a set of mapping properties for an <strong>XML</strong> document contained in a file.<br />
XmlDsa.fileTypes.1.typeName <strong>XML</strong>_file_superType<br />
XmlDsa.fileTypes.1.dtdFile dsa/XmlDsa/file.dtd<br />
XmlDsa.fileTypes.1.xmlFile dsa/XmlDsa/file.xml<br />
XmlDsa.fileTypes.1.prefix <strong>XML</strong>_<br />
The following example shows a set of mapping properties for an <strong>XML</strong> document contained in a string.<br />
XmlDsa.fileTypes.2.typeName <strong>XML</strong>_string_superType<br />
XmlDsa.fileTypes.2.dtdFile dsa/XmlDsa/string.dtd<br />
XmlDsa.fileTypes.2.xmlFile -<br />
XmlDsa.fileTypes.2.prefix <strong>XML</strong>_<br />
Note that this example uses the hyphen character (-) for the xmlFile property.<br />
<strong>Netcool</strong>/<strong>Impact</strong> <strong>3.0</strong> <strong>and</strong> <strong>Later</strong> <strong>XML</strong> <strong>DSA</strong> <strong>Guide</strong>
<strong>Netcool</strong>/<strong>Impact</strong> <strong>3.0</strong> <strong>and</strong> <strong>Later</strong> <strong>XML</strong> <strong>DSA</strong> <strong>Guide</strong><br />
Setting Up Data Type Mappings<br />
The following example shows an expression using the XmlFileTOC data type with isXsd set to true.<br />
The name space prefix is FTEST. This prefix should be added to all data types that are a part of the <strong>XML</strong> file.<br />
XmlDsa.fileTypes.1.typeName XmlFileTOC<br />
XmlDsa.fileTypes.1.dtdFile dsa/XmlDsa/TOC.xsd<br />
XmlDsa.fileTypes.1.xmlFile dsa/XmlDsa/TOC.xml<br />
XmlDsa.fileTypes.1.prefix FTEST_<br />
XmlDsa.fileTypes.1.isXsd true<br />
Setting Up Mappings for <strong>XML</strong> Over HTTP<br />
For each <strong>XML</strong> document that you want the <strong>DSA</strong> to read over HTTP, you must add the following mapping<br />
information to the XmlHttpTypes file:<br />
Name of the super data type.<br />
Base URL for the HTTP server.<br />
Username, password <strong>and</strong> authentication realm (optional). Required only if the <strong>XML</strong> document is<br />
located in a password-protected area of the HTTP server.<br />
Namespace prefix used for the element data types (optional).<br />
You specify mapping information in the file using the following format:<br />
XmlDsa.httpTypes.n.property value<br />
where n is a numeric value that identifies the mapping, property is the name of the mapping property,<br />
<strong>and</strong> value is the value.<br />
The following table shows the mapping properties in the XmlHttpTypes file:<br />
Table 5: XmlHttpTypes Mapping Properties (1 of 2)<br />
Property Description<br />
typeName Name of the corresponding super data type.<br />
dtdFile Path <strong>and</strong> filename of the corresponding <strong>XML</strong> DTD file. The path can be an<br />
absolute path or a path relative to the $IMPACT_HOME directory.<br />
xsdFile Path <strong>and</strong> filename of a corresponding <strong>XML</strong> XSD file. The path can be an absolute<br />
path or a path relative to the $IMPACT_HOME directory. Used only if the <strong>XML</strong><br />
schema is an XSD.<br />
isXsd This boolean variable specifies whether the schema is defined in XSD or DTD<br />
format. If it is not specified, the default is DTD format.<br />
15
<strong>Netcool</strong>/<strong>Impact</strong> <strong>XML</strong> <strong>DSA</strong> <strong>Guide</strong><br />
16<br />
Table 5: XmlHttpTypes Mapping Properties (2 of 2)<br />
Property Description<br />
url Base URL for the HTTP server. The base URL includes the server’s hostname, as<br />
well as the path where the script or executable that provides the <strong>XML</strong> data is<br />
located. You do not need to specify the trailing backslash in the base URL. This<br />
URL is combined with the contents of the FilePath parameter to form the<br />
complete URL when you retrieve the <strong>XML</strong> data in a policy.<br />
user Username valid under HTTP server authentication (optional).<br />
password Password valid under HTTP server authentication (optional).<br />
realm Authentication realm on the HTTP server (optional).<br />
prefix Namespace prefix used to identify the corresponding element data types<br />
(optional).<br />
Example<br />
The following example shows a set of mapping properties for <strong>XML</strong> data provided by an HTTP server.<br />
XmlDsa.httpTypes.1.typeName <strong>XML</strong>_http_superType<br />
XmlDsa.httpTypes.1.dtdFile dsa/XmlDsa/http.dtd<br />
XmlDsa.httpTypes.1.url http://localhost:8080/cgi-bin<br />
XmlDsa.httpTypes.1.user jsmith<br />
XmlDsa.httpTypes.1.password micromuse<br />
XmlDsa.httpTypes.1.realm primary<br />
<strong>Netcool</strong>/<strong>Impact</strong> <strong>3.0</strong> <strong>and</strong> <strong>Later</strong> <strong>XML</strong> <strong>DSA</strong> <strong>Guide</strong>
Reading <strong>XML</strong> Documents<br />
<strong>Netcool</strong>/<strong>Impact</strong> <strong>3.0</strong> <strong>and</strong> <strong>Later</strong> <strong>XML</strong> <strong>DSA</strong> <strong>Guide</strong><br />
Reading <strong>XML</strong> Documents<br />
This section contains information about reading <strong>XML</strong> documents from within a policy. It contains the<br />
following topics:<br />
Retrieving the Document Data Item<br />
Retrieving the Root-Level Element Data Item<br />
Retrieving the Child Element Data Item<br />
Accessing Attribute Values<br />
Retrieving the Document Data Item<br />
The first step in reading an <strong>XML</strong> document is to retrieve the document data item. You retrieve the data item<br />
by calling the GetByFilter function <strong>and</strong> passing the name of the super data type <strong>and</strong> a filter string. The<br />
content of the filter string varies depending on whether the data source is an <strong>XML</strong> string, <strong>XML</strong> file, or <strong>XML</strong><br />
data located on an HTTP server.<br />
<strong>XML</strong> Strings<br />
For <strong>XML</strong> strings, the filter is the entire <strong>XML</strong> string that you want to read.<br />
The following example shows how to retrieve the document data item associated with an <strong>XML</strong> string, where<br />
the corresponding super type is named <strong>XML</strong>_string_SuperType.<br />
// Call GetByFilter <strong>and</strong> pass the name of the super type<br />
// <strong>and</strong> the filter string<br />
Type = "<strong>XML</strong>_string_superType";<br />
Filter = "Node1234Node not responding";<br />
CountOnly = False;<br />
DocDataItem = GetByFilter(Type, Filter, CountOnly);<br />
17
<strong>Netcool</strong>/<strong>Impact</strong> <strong>XML</strong> <strong>DSA</strong> <strong>Guide</strong><br />
18<br />
<strong>XML</strong> Files<br />
For <strong>XML</strong> files, the filter is an empty string.<br />
The following example shows how to retrieve the document data item associated with an <strong>XML</strong> file, where<br />
the corresponding super type is named <strong>XML</strong>_file_superType.<br />
// Call GetByFilter <strong>and</strong> pass the name of the super type<br />
// <strong>and</strong> the filter string<br />
Type = "<strong>XML</strong>_file_superType";<br />
Filter = "";<br />
CountOnly = False;<br />
DocDataItem = GetByFilter(Type, Filter, CountOnly);<br />
<strong>XML</strong> Over HTTP<br />
For <strong>XML</strong> over HTTP, the filter string is an expression that specifies the method to use in retrieving the <strong>XML</strong><br />
data <strong>and</strong> the path to a script or executable that provides the data on the HTTP server. The <strong>XML</strong> <strong>DSA</strong> uses<br />
either the GET or POST method to retrieve the <strong>XML</strong> data.<br />
The syntax for the filter is:<br />
Operation = 'method' AND FilePath = 'path'<br />
where method is either GET or POST <strong>and</strong> path is the location of the script or executable relative to the<br />
base URL. You specify the base URL when you set the mapping information for the document in the<br />
XmlHttpTypes file.<br />
Note: The FilePath specification can include query string values. This allows you to retrieve <strong>XML</strong><br />
documents from the HTTP server that are dynamically created depending on values sent by <strong>Netcool</strong>/<strong>Impact</strong><br />
as part of the HTTP request.<br />
<strong>Netcool</strong>/<strong>Impact</strong> <strong>3.0</strong> <strong>and</strong> <strong>Later</strong> <strong>XML</strong> <strong>DSA</strong> <strong>Guide</strong>
<strong>Netcool</strong>/<strong>Impact</strong> <strong>3.0</strong> <strong>and</strong> <strong>Later</strong> <strong>XML</strong> <strong>DSA</strong> <strong>Guide</strong><br />
Reading <strong>XML</strong> Documents<br />
The following example shows how to retrieve the document data item associated with <strong>XML</strong> data using an<br />
HTTP GET request. In this example, the name of the super data type is <strong>XML</strong>_http_superType <strong>and</strong><br />
the location of the script that provides the <strong>XML</strong> data is get<strong>XML</strong>doc.pl.<br />
// Call GetByFilter <strong>and</strong> pass the name of the super type<br />
// <strong>and</strong> the filter string<br />
Type = "<strong>XML</strong>_http_superType";<br />
Filter = "Operation = 'GET' AND FilePath = 'get<strong>XML</strong>doc.pl?node=NodeXYZ'";<br />
CountOnly = False;<br />
DocDataItem = GetByFilter(Type, Filter, CountOnly);<br />
Retrieving the Root-Level Element Data Item<br />
After you have retrieved the document data item, you can retrieve the root-level element data item using the<br />
GetByLinks function. When you call GetByLinks, you must pass the name of the root-level element<br />
data type, an empty filter string <strong>and</strong> the document data item.<br />
The following example shows how to retrieve the root-level element data item using<br />
GetByLinks.<br />
// Call GetByLinks <strong>and</strong> pass the name of the<br />
DataTypes = {"<strong>XML</strong>_alert"};<br />
Filter = "";<br />
MaxNum = "10000";<br />
DataItems = DocDataItem;<br />
RootDataItem = GetByLinks(DataTypes, Filter, MaxNum, DataItems);<br />
19
<strong>Netcool</strong>/<strong>Impact</strong> <strong>XML</strong> <strong>DSA</strong> <strong>Guide</strong><br />
Retrieving Child Element Data Items<br />
20<br />
After you have retrieved the root-level element data item, you can retrieve child element data items by<br />
making successive calls to the GetByLinks function or by using the embedded linking syntax.<br />
The following example shows how to use the linking syntax to retrieve the first child element data item<br />
linked to the root-level element data item, where the data type of the child data item is <strong>XML</strong>_body.<br />
ChildNode = RootDataItem[0].links.<strong>XML</strong>_body.first;<br />
The following example shows how to retrieve an array that contains all child element data items linked to<br />
the root-level element data item.<br />
ChildNodes = RootDataItem[0].links.<strong>XML</strong>_body.array;<br />
Accessing Attribute Values<br />
Once you have retrieved an element data item, you can access its attribute values by referencing the<br />
corresponding data type fields.<br />
The following example shows how to log the value of the ID attribute associated with the current element<br />
data item:<br />
log(“The message ID is: “ + OrgNode.id);<br />
The following example shows how to log the PCDATA value associated with the current element data item:<br />
log(OrgNode.PCDATA);<br />
<strong>Netcool</strong>/<strong>Impact</strong> <strong>3.0</strong> <strong>and</strong> <strong>Later</strong> <strong>XML</strong> <strong>DSA</strong> <strong>Guide</strong>
Sample Policies<br />
The <strong>DSA</strong> provides the following sample policies:<br />
XmlStringTestPolicy<br />
XmlFileTestPolicy<br />
XmlHttpTestPolicy<br />
XmlXsdFileTestPolicy<br />
These policies are configured to use the TOC.dtd, TOC.xsd <strong>and</strong> TOC.xml files located in the<br />
$IMPACT_HOME/dsa/XmlDsa directory.<br />
XmlStringTestPolicy<br />
<strong>Netcool</strong>/<strong>Impact</strong> <strong>3.0</strong> <strong>and</strong> <strong>Later</strong> <strong>XML</strong> <strong>DSA</strong> <strong>Guide</strong><br />
Sample Policies<br />
XmlStringTestPolicy shows how to use the <strong>XML</strong> <strong>DSA</strong> to read data from an <strong>XML</strong> string. The policy<br />
reads the contents of an <strong>XML</strong>-formatted string <strong>and</strong> then prints the data to the policy log.<br />
Before you use this policy, you must run the create DTD types script as follows:<br />
./CreateDtdTypes.sh NCI admin netcool ../TOC.dtd XmlStringTOC STEST_<br />
You do not need to edit the contents of the XmlFileTypes configuration file. By default, this file<br />
contains the necessary data type mappings. The following are the data type mappings:<br />
XmlDsa.fileTypes.2.typeName <strong>XML</strong>StringTOC<br />
XmlDsa.fileTypes.2.dtdFile dsa/XmlDsa/TOC.dtd<br />
XmlDsa.fileTypes.2.xmlFile -<br />
XmlDsa.fileTypes.2.prefix STEST_<br />
XmlFileTestPolicy<br />
XmlFileTestPolicy shows how to use the <strong>XML</strong> <strong>DSA</strong> to read data from an <strong>XML</strong> file. This policy reads<br />
the contents of the TOC.xml file <strong>and</strong> then prints the data to the policy log.<br />
Before you use this policy, you must run the create DTD types script as follows:<br />
./CreateDtdTypes.sh NCI admin netcool ../TOC.dtd XmlFileTOC FTEST_<br />
21
<strong>Netcool</strong>/<strong>Impact</strong> <strong>XML</strong> <strong>DSA</strong> <strong>Guide</strong><br />
22<br />
You do not need to edit the contents of the XmlFileTypes configuration file. By default, this file<br />
contains the necessary data source mappings. The following are the data type mappings:<br />
XmlDsa.fileTypes.1.typeName XmlFileTOC<br />
XmlDsa.fileTypes.1.dtdFile dsa/XmlDsa/TOC.dtd<br />
XmlDsa.fileTypes.1.xmlFile dsa/XmlDsa/TOC.xml<br />
XmlDsa.fileTypes.1.prefix FTEST_<br />
XmlHttpTestPolicy<br />
XmlHttpTestPolicy shows how to use the <strong>XML</strong> <strong>DSA</strong> to read data from a location on an HTTP<br />
server. This policy reads the <strong>XML</strong> data from an HTTP server <strong>and</strong> then prints it to the policy log.<br />
Before you use this policy, you must run the CreateDtdTypes script as follows:<br />
./CreateDtdTypes.sh NCI admin netcool ../TOC.dtd XmlHttpTOC HTEST_<br />
You must also install a Perl CGI script on the HTTP server that generates the <strong>XML</strong> output requested by the<br />
<strong>DSA</strong>. This script is named xml.cgi <strong>and</strong> is located in $IMPACT_HOME/dsa/XmlDsa. You must<br />
check to make sure that the first line of the script references the actual location of the Perl executable on the<br />
system before you install the script. To install, copy the script into the cgi-bin directory used by the<br />
HTTP server.<br />
After you have installed the script, you must modify the XmlHttpTypes configuration file to reflect the<br />
location of the script <strong>and</strong> to include a valid username <strong>and</strong> password for the authentication realm, if any.<br />
The following are the data type mappings:<br />
XmlDsa.httpTypes.1.typeName XmlHttpTOC<br />
XmlDsa.httpTypes.1.dtdFile dsa/XmlDsa/TOC.dtd<br />
XmlDsa.httpTypes.1.prefix HTEST_<br />
XmlDsa.httpTypes.1.url http://localhost:8080<br />
XmlDsa.httpTypes.1.user John<br />
XmlDsa.httpTypes.1.password Smith<br />
XmlDsa.httpTypes.1.realm basicrealm<br />
<strong>Netcool</strong>/<strong>Impact</strong> <strong>3.0</strong> <strong>and</strong> <strong>Later</strong> <strong>XML</strong> <strong>DSA</strong> <strong>Guide</strong>
XmlXsdFileTestPolicy<br />
<strong>Netcool</strong>/<strong>Impact</strong> <strong>3.0</strong> <strong>and</strong> <strong>Later</strong> <strong>XML</strong> <strong>DSA</strong> <strong>Guide</strong><br />
Sample Policies<br />
XmlXsdFileTestPolicy shows how to use the <strong>XML</strong> <strong>DSA</strong> to read data from an <strong>XML</strong> file. This policy<br />
reads <strong>XML</strong> data returned from a URL <strong>and</strong> then prints the data to the policy log.<br />
Before you use this policy, you must run the create XSD script as follows:<br />
./CreateXsdTypes.sh NCI admin netcool ../TOC.xsd XmlXsdFileTOC XSDFTEST_<br />
where filename is the name <strong>and</strong> path of an <strong>XML</strong> file stored on the file system.<br />
You do not need to edit the contents of the XmlFileTypes configuration file. By default, this file<br />
contains the necessary data source mappings. The following are the data type mappings:<br />
XmlDsa.fileTypes.2.typeName XmlXsdFileTOC<br />
XmlDsa.fileTypes.2.xsdFile dsa/XmlDsa/TOC.xsd<br />
XmlDsa.fileTypes.2.xmlFile dsa/XmlDsa/TOC.xml<br />
XmlDsa.fileTypes.2.prefix XSDFTEST_<br />
XmlDsa.fileTypes.2.isXsd true<br />
23
<strong>Netcool</strong>/<strong>Impact</strong> <strong>XML</strong> <strong>DSA</strong> <strong>Guide</strong><br />
24<br />
<strong>Netcool</strong>/<strong>Impact</strong> <strong>3.0</strong> <strong>and</strong> <strong>Later</strong> <strong>XML</strong> <strong>DSA</strong> <strong>Guide</strong>
ackmatter.fm May 4, 2005<br />
Contact Information<br />
Corporate<br />
Region Address Telephone Fax World Wide Web<br />
USA Micromuse Inc. (HQ)<br />
139 Townsend Street<br />
San Francisco<br />
CA 94107<br />
USA<br />
Europe Micromuse Ltd.<br />
Disraeli House<br />
90 Putney Bridge Road<br />
London SW18 1DA<br />
United Kingdom<br />
Asia-Pacific Micromuse Ltd.<br />
Level 2<br />
26 Colin Street<br />
West Perth<br />
Perth WA 6005<br />
Australia<br />
Technical Support<br />
1-800-<strong>Netcool</strong> (638 2665)<br />
+1 415 538 9090<br />
Region Telephone Fax<br />
USA 1-800-<strong>Netcool</strong> (800 638 2665)<br />
+1 415 538 9090 (San Francisco)<br />
+1 415 538 9091 http://www.micromuse.com<br />
+44 (0) 20 8875 9500 +44 (0) 20 8875 9995 http://www.micromuse.co.uk<br />
+61 (0) 8 9213 3400 +61 (0) 8 9486 1116 http://www.micromuse.com.au<br />
+1 415 538 9091<br />
Europe +44 (0) 20 8877 0073 (London, UK) +44 (0) 20 8875 0991<br />
Asia-Pacific +61 (0) 8 9213 3470 (Perth, Australia)<br />
Online<br />
+10 800 852 1012 (North China)<br />
+10 800 152 1012 (South China)<br />
+61 (0) 8 9486 1116<br />
Team E-Mail World Wide Web<br />
Licensing Temporary Licenses: temp.licensing@micromuse.com<br />
Permanent Licenses: perm.licensing@micromuse.com<br />
support.micromuse.com/helpdesk/licenses<br />
Support support@micromuse.com support.micromuse.com<br />
<strong>Netcool</strong>/<strong>Impact</strong> <strong>3.0</strong> <strong>and</strong> <strong>Later</strong> <strong>XML</strong> <strong>DSA</strong> <strong>Guide</strong> 25
Contact Information<br />
26<br />
<strong>Netcool</strong>/<strong>Impact</strong> <strong>3.0</strong> <strong>and</strong> <strong>Later</strong> <strong>XML</strong> <strong>DSA</strong> <strong>Guide</strong>