27.02.2013 Views

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 ...

SHOW MORE
SHOW LESS

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>

Hooray! Your file is uploaded and ready to be published.

Saved successfully!

Ooh no, something went wrong!