Network Service Manager REST API Users Guide

Transcription

1 Netcool Configuration Manager Version 641 Network Serice Manager REST API Users Guide for R2E3

2

3 Netcool Configuration Manager Version 641 Network Serice Manager REST API Users Guide for R2E3

4 Note Before using this information and the product it supports, read the information in Notices on page 155 This edition applies to ersion 6, release 4 of IBM Tioli Netcool Configuration Manager (5725-F56) and to all subsequent releases and modifications until otherwise indicated in new editions Copyright IBM Corporation 2012, 2014 US Goernment Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp

5 Contents About this publication Intended audience What this publication contains Publications i Accessibility x Tioli technical training x Support information x Conentions used in this publication x Chapter 1 Oeriew of the Network Serice Manager REST API 1 About the NSM REST API 1 NSM architecture 1 NSM serice lifecycle 2 NSM parameter calculation 4 NSM roles 5 Chapter 2 Designing a NSM serice template 7 Structure of a NSM serice template 7 Parameters 8 <implementations> element 9 Configuring rules 11 Configuring serice operations 12 Deleting NSM serice template instances 16 Controlling the order and merging of serice operations 18 Posting a NSM serice template 22 Submitting a NSM serice template for execution 22 Chapter 3 Network Serice Manager parameters 27 Constant parameters 27 Constant parameter rules 28 Configuring constant parameters 28 Client parameters 29 Client parameter rules 30 Configuring client parameters 30 Client parameter list parameters 31 Client parameter list parameter rules 35 Configuring client parameter lists 35 Inject parameters 36 Inject parameter rules 37 Types of inject parameters 38 Configuring inject parameters 40 JaaScript restrictions 41 SQL parameters 41 Database connection tags 42 SQL parameter element and tags 43 SQL parameter rules 44 Configuring SQL parameters 44 HTTP parameters 45 HTTP parameter rules 47 Configuring HTTP parameters 47 Chapter 4 Understanding predefined Network Serice Manager functions 49 concat 49 diide 49 ifequals 50 ifgreaterthan 51 ifgreaterthanorequalto 52 multiply 53 replace 54 replaceall 55 substring 55 substringfrombeginindex 56 subtract 57 sum 57 Chapter 5 Network serice management command line interface tool 59 Running the CLI tool 59 CLI commands and options 60 clone command 63 create command 64 delete command 65 disable command 65 disableall command 66 exportall command 66 exportdate command 67 exportdaterange command 68 exportid command 69 exportname command 70 exportendor command 70 getersion command 71 import command 72 importlist command 73 list command 74 purge command 74 read command 75 readall command 75 update command 76 remoesericeinstance command 77 NSM command-line logging 77 Chapter 6 Understanding the Network Serice Manager URIs 79 Realm URIs 80 HTTP GET for /realm 80 HTTP GET for /realm/{realm-id} 82 Deice URIs 83 Short and long formats for deice URIs 87 HTTP GET for /deice/{deice-id}/ currentnatieconfiguration 90 HTTP GET for /deice/{deice-id}/ currentmodeledconfiguration 91 Copyright IBM Corp 2012, 2014 iii

6 HTTP GET for /deice/{deice-id}/ currentsupplementalinformation 92 Serice template URIs 93 HTTP GET for /sericetemplate/ {sericetemplate-id}/deiceid/{deice-id} 94 HTTP GET for /sericetemplate 97 HTTP GET for /sericetemplate/deiceid/ {deice-id} 98 Serice URIs 99 HTTP GET for /serice 100 HTTP GET for /serice/{serice-id} 103 HTTP GET for /serice/referenceid/{referenceid} 105 HTTP GET for /serice/{serice-id}/status 107 HTTP GET for /serice/{serice-id}/deice 108 HTTP GET for /serice/{serice-id}/workitem 109 HTTP GET for /serice/{serice-id}/workitem/ {workitem-id} 110 HTTP GET for /serice/{serice-id}/input 112 HTTP POST for /serice 113 HTTP POST for /serice/{reference-id} 115 HTTP DELETE for /serice/{serice-id} 118 XSD URIs 119 Chapter 7 Understanding automatically generated NSM serice templates 121 Rename action 121 Moe action 122 Edit action 122 Delete action 123 Chapter 8 Troubleshooting 125 Interpreting NSM serice execution status codes 125 Interpreting HTTP status codes and NSM error codes 125 Checking the NSM REST API installation 130 Checking NSM when Netcool Configuration Manager Recoers 130 Checking the Intellidenlog file 130 Checking the nsmadminlog file 131 Working with the database connection pool 131 Appendix A Sample XML responses for operation types 133 Appendix B XSD files 139 Appendix C Example NSM serice templates 145 Notices 155 Trademarks 157 Index 159 i IBM Tioli Netcool Configuration Manager: Network Serice Manager REST API

7 About this publication Intended audience IBM Tioli Netcool Configuration Manager proides configuration management capabilities for network deices, as well as extensie configuration policy thresholding capabilities The IBM Tioli Netcool Configuration Manager NSM REST API Guide describes the Network Serice Manager REST API, hereinafter referred to as the NSM REST API This publication is intended for network engineers who need to use the NSM REST API Specifically, the audience consists of NSM serice designers who design serice templates and NSM client users who make use of these serice templates What this publication contains This publication contains the following sections: Chapter 1, Oeriew of the Network Serice Manager REST API, on page 1 Proides an introduction to the NSM REST API Chapter 2, Designing a NSM serice template, on page 7 Proides information about how to design a NSM serice template Chapter 3, Network Serice Manager parameters, on page 27 Describes the types of NSM parameters Chapter 4, Understanding predefined Network Serice Manager functions, on page 49 Describes the predefined NSM functions that can be used inside inject parameters to create and edit NSM serice templates Chapter 5, Network serice management command line interface tool, on page 59 Proides information about the NSM command-line (CLI) tool Chapter 6, Understanding the Network Serice Manager URIs, on page 79 Proides information about the Network Serice Management URIs Chapter 7, Understanding automatically generated NSM serice templates, on page 121 Describes automatically generated NSM serice templates Chapter 8, Troubleshooting, on page 125 Proides information about how to troubleshoot NSM issues when there are errors Appendix A, Sample XML responses for operation types, on page 133 Proides sample XML responses for the EXTRACTION, DEVICESYNC, and COMMANDSET operation types Appendix B, XSD files, on page 139 Proides XSD files for the NSM REST API Appendix C, Example NSM serice templates, on page 145 Proides example NSM serice templates that NSM serice designers can use as models for creating their own NSM serice templates Copyright IBM Corp 2012, 2014

8 Publications This section lists publications in the Netcool Configuration Manager PDF document set The prerequisite publications in the IBM Tioli Network Manager IP Edition and IBM Tioli Netcool/OMNIbus library are also listed here The section also describes how to access Tioli publications online and how to order Tioli publications Netcool Configuration Manager PDF document set The following documents are aailable in the Netcool Configuration Manager library: IBM Tioli Netcool Configuration Manager Installation and Configuration Guide Describes how to install IBM Tioli Netcool Configuration Manager It also describes necessary and optional post-installation configuration tasks This publication is for administrators who need to install and set up IBM Tioli Netcool Configuration Manager IBM Tioli Netcool Configuration Manager User Guide Describes user tasks for IBM Tioli Netcool Configuration Manager, such as how to access reports, use deices, and execute the different utilities to maintain and support Auto-Discoery This publication is for users working with IBM Tioli Netcool Configuration Manager IBM Tioli Netcool Configuration Manager Administration Guide Describes administration tasks for IBM Tioli Netcool Configuration Manager, such as how to set up user accounts, create and manage the OS registry, administer database and policy exports and imports, and perform housekeeping and security tasks This publication is for administrators who are responsible for the maintenance and aailability of IBM Tioli Netcool Configuration Manager IBM Tioli Netcool Configuration Manager Reference Guide Contains reference information about IBM Tioli Netcool Configuration Manager IBM Tioli Netcool Configuration Manager API Guide Proides information about how to use the Jaa API to programmatically access IBM Tioli Netcool Configuration Manager IBM Tioli Netcool Configuration Manager NSM REST API Guide Describes the Serice Management Interface API IBM Tioli Netcool Configuration Manager Integration Guide Describes how to integrate Netcool Configuration Manager with Tioli Netcool/OMNIbus and Network Manager IBM Tioli Netcool Configuration Manager Quick Start Guide Gets you started with a typical installation for IBM Tioli Netcool Configuration Manager IBM Tioli Netcool Configuration Manager Release Notes Gies important and late-breaking information about IBM Tioli Netcool Configuration Manager This publication is for deployers and administrators, and should be read first Prerequisite publications: IBM Tioli Network Manager IP Edition To use the information in this publication effectiely when dealing with an integrated installation of Netcool Configuration Manager, Network Manager, and i IBM Tioli Netcool Configuration Manager: Network Serice Manager REST API

9 Tioli Netcool/OMNIbus, you must hae some prerequisite knowledge, which you can obtain from the Network Manager documentation, especially the following publications: IBM Tioli Network Manager IP Edition Release Notes Gies important and late-breaking information about IBM Tioli Network Manager IP Edition This publication is for deployers and administrators, and should be read first IBM Tioli Network Manager Getting Started Guide Describes how to set up IBM Tioli Network Manager IP Edition after you hae installed the product This guide describes how to start the product, make sure it is running correctly, and discoer the network Getting a good network discoery is central to using Network Manager IP Edition successfully This guide describes how to configure and monitor a first discoery, erify the results of the discoery, configure a production discoery, and how to keep the network topology up to date Once you hae an up-to-date network topology, this guide describes how to make the network topology aailable to Network Operators, and how to monitor the network The essential tasks are coered in this short guide, with references to the more detailed, optional, or adanced tasks and reference material in the rest of the documentation set IBM Tioli Network Manager IP Edition Product Oeriew Gies an oeriew of IBM Tioli Network Manager IP Edition It describes the product architecture, components and functionality This publication is for anyone interested in IBM Tioli Network Manager IP Edition IBM Tioli Network Manager IP Edition Installation and Configuration Guide Describes how to install IBM Tioli Network Manager IP Edition It also describes necessary and optional post-installation configuration tasks This publication is for administrators who need to install and set up IBM Tioli Network Manager IP Edition IBM Tioli Network Manager IP Edition Administration Guide Describes administration tasks for IBM Tioli Network Manager IP Edition, such as how to administer processes, query databases and start and stop the product This publication is for administrators who are responsible for the maintenance and aailability of IBM Tioli Network Manager IP Edition IBM Tioli Network Manager IP Edition Discoery Guide Describes how to use IBM Tioli Network Manager IP Edition to discoer your network This publication is for administrators who are responsible for configuring and running network discoery IBM Tioli Network Manager IP Edition Eent Management Guide Describes how to use IBM Tioli Network Manager IP Edition to poll network deices, to configure the enrichment of eents from network deices, and to manage plug-ins to the Tioli Netcool/OMNIbus Eent Gateway, including configuration of the RCA plug-in for root-cause analysis purposes This publication is for administrators who are responsible for configuring and running network polling, eent enrichment, root-cause analysis, and Eent Gateway plug-ins IBM Tioli Network Manager IP Edition Network Troubleshooting Guide Describes how to use IBM Tioli Network Manager IP Edition to troubleshoot network problems identified by the product This publication is for network operators who are responsible for identifying or resoling network problems IBM Tioli Network Manager IP Edition Network Visualization Setup Guide About this publication ii

10 Describes how to configure the IBM Tioli Network Manager IP Edition network isualization tools to gie your network operators a customized working enironment This publication is for product administrators or team leaders who are responsible for facilitating the work of network operators IBM Tioli Network Manager IP Edition Management Database Reference Describes the schemas of the component databases in IBM Tioli Network Manager IP Edition This publication is for adanced users who need to query the component databases directly IBM Tioli Network Manager IP Edition Topology Database Reference Describes the schemas of the database used for storing topology data in IBM Tioli Network Manager IP Edition This publication is for adanced users who need to query the topology database directly IBM Tioli Network Manager IP Edition Language Reference Describes the system languages used by IBM Tioli Network Manager IP Edition, such as the Stitcher language, and the Object Query Language This publication is for adanced users who need to customize the operation of IBM Tioli Network Manager IP Edition IBM Tioli Network Manager IP Edition Perl API Guide Describes the Perl modules that allow deelopers to write custom applications that interact with the IBM Tioli Network Manager IP Edition Examples of custom applications that deelopers can write include Polling and Discoery Agents This publication is for adanced Perl deelopers who need to write such custom applications IBM Tioli Monitoring for Tioli Network Manager IP User's Guide Proides information about installing and using IBM Tioli Monitoring for IBM Tioli Network Manager IP Edition This publication is for system administrators who install and use IBM Tioli Monitoring for IBM Tioli Network Manager IP Edition to monitor and manage IBM Tioli Network Manager IP Edition resources Prerequisite publications: IBM Tioli Netcool/OMNIbus To use the information in this publication effectiely when dealing with an integrated installation of Netcool Configuration Manager, Network Manager, and Tioli Netcool/OMNIbus, you must hae some prerequisite knowledge, which you can obtain from the Tioli Netcool/OMNIbus documentation, especially the following publications: IBM Tioli Netcool/OMNIbus Installation and Deployment Guide Includes installation and upgrade procedures for Tioli Netcool/OMNIbus, and describes how to configure security and component communications The publication also includes examples of Tioli Netcool/OMNIbus architectures and describes how to implement them IBM Tioli Netcool/OMNIbus User's Guide Proides an oeriew of the desktop tools and describes the operator tasks related to eent management using these tools IBM Tioli Netcool/OMNIbus Administration Guide Describes how to perform administratie tasks using the Tioli Netcool/OMNIbus Administrator GUI, command-line tools, and process control The publication also contains descriptions and examples of ObjectSerer SQL syntax and automations IBM Tioli Netcool/OMNIbus Probe and Gateway Guide iii IBM Tioli Netcool Configuration Manager: Network Serice Manager REST API

11 Contains introductory and reference information about probes and gateways, including probe rules file syntax and gateway commands IBM Tioli Netcool/OMNIbus Web GUI Administration and User's Guide Describes how to perform administratie and eent isualization tasks using the Tioli Netcool/OMNIbus Web GUI Accessing terminology online The IBM Terminology website consolidates the terminology from IBM product libraries in one conenient location You can access the Terminology website at the following Web address: Accessing publications online IBM posts publications for this and all other Tioli products, as they become aailable and wheneer they are updated, to the Tioli Information Center website at: Note: If you print PDF documents on other than letter-sized paper, set the option in the File > Print window that allows Adobe Reader to print letter-sized pages on your local paper Ordering publications You can order many Tioli publications online at the following website: You can also order by telephone by calling one of these numbers: In the United States: In Canada: In other countries, contact your software account representatie to order Tioli publications To locate the telephone number of your local representatie, perform the following steps: 1 Go to the following website: 2 Select your country from the list and click Go The Welcome to the IBM Publications Center page is displayed for your country 3 On the left side of the page, click About this site to see an information page that includes the telephone number of your local representatie About this publication ix

12 Accessibility Tioli technical training Support information Accessibility features help users with a physical disability, such as restricted mobility or limited ision, to use software products successfully With this product, you can use assistie technologies to hear and naigate the interface You can also use the keyboard instead of the mouse to operate all features of the graphical user interface For Tioli technical training information, refer to the following IBM Tioli Education website: If you hae a problem with your IBM software, you want to resole it quickly IBM proides the following ways for you to obtain the support you need: Online Go to the IBM Software Support site at support/probsubhtml and follow the instructions IBM Support Assistant The IBM Support Assistant (ISA) is a free local software sericeability workbench that helps you resole questions and problems with IBM software products The ISA proides quick access to support-related information and sericeability tools for problem determination To install the ISA software, go to Conentions used in this publication This publication uses seeral conentions for special terms and actions and operating system-dependent commands and paths Typeface conentions This publication uses the following typeface conentions: Bold Italic Lowercase commands and mixed case commands that are otherwise difficult to distinguish from surrounding text Interface controls (check boxes, push buttons, radio buttons, spin buttons, fields, folders, icons, list boxes, items inside list boxes, multicolumn lists, containers, menu choices, menu names, tabs, property sheets), labels (such as Tip: and Operating system considerations:) Keywords and parameters in text Citations (examples: titles of publications, diskettes, and CDs) Words defined in text (example: a nonswitched line is called a point-to-point line) x IBM Tioli Netcool Configuration Manager: Network Serice Manager REST API

13 Emphasis of words and letters (words as words example: "Use the word that to introduce a restrictie clause"; letters as letters example: "The LUN address must start with the letter L") New terms in text (except in a definition list): a iew is a frame in a workspace that contains data Variables and alues you must proide: where myname represents Monospace Examples and code examples File names, programming keywords, and other elements that are difficult to distinguish from surrounding text Message text and prompts addressed to the user Text that the user must type Values for arguments or command options Operating system-dependent ariables and paths This publication uses the UNIX conention for specifying enironment ariables and for directory notation When using the Windows command line, replace $ariable with %ariable% for enironment ariables, and replace each forward slash (/) with a backslash (\) in directory paths For example, on UNIX systems, the $NCHOME enironment ariable specifies the directory where the Network Manager core components are installed On Windows systems, the same enironment ariable is %NCHOME% The names of enironment ariables are not always the same in the Windows and UNIX enironments For example, %TEMP% in Windows enironments is equialent to $TMPDIR in UNIX enironments If you are using the bash shell on a Windows system, you can use the UNIX conentions About this publication xi

14 xii IBM Tioli Netcool Configuration Manager: Network Serice Manager REST API

15 Chapter 1 Oeriew of the Network Serice Manager REST API About the NSM REST API Use this information to obtain an oeriew of the Network Serice Manager REST API Netcool Configuration Manager is an intelligent tool for managing network operations and compliance It includes a new REST API called the Network Serice Manager REST API (NSM REST API) that allows client users to access the features that the Netcool Configuration Manager tool proides Netcool Configuration Manager offers features that include configuration management, deice discoery, configuration backup, configuration extraction, and command sets The NSM REST API allows NSM client users to integrate their existing systems to Netcool Configuration Manager to benefit from the Netcool Configuration Manager product features NSM architecture The NSM REST API offers a comprehensie REST API to enable easy integration with client user systems to the Netcool Configuration Manager system Specifically, the NSM REST API offers access to the following objects: Deices Realms Serice templates Serices NSM allows the NSM client user to access the Netcool Configuration Manager deice inentory through the NSM REST API by using the NSM deice URIs This allows client users to access deice information gathered from the Netcool Configuration Manager deice discoery features such as the deice Vendor, Type, Model, and OS (VTMOS) NSM can also retriee the deice's current configuration as stored on the Netcool Configuration Manager system The NSM client user can also use the NSM realm URIs to search Netcool Configuration Manager realms Searching realms through the NSM REST API enables client users to iew the Netcool Configuration Manager artifacts within realms Netcool Configuration Manager realms are used to structure the command sets, deices, and other Netcool Configuration Manager artifacts on the Netcool Configuration Manager system NSM has a framework that NSM serice designers use to define NSM serice templates that can be used to create network serices Network serices can be any network serice from simple Firewall Zones established for a client user on a single deice, to a VLAN being created across a network To create a network serice, the configuration of the network deices need to be changed Netcool Configuration Manager command sets are used to apply this configuration in a controlled manner on the network deices Copyright IBM Corp 2012,

16 NSM serice templates allow for the easy and consistent execution of Netcool Configuration Manager command sets NSM serice templates allow the execution of Netcool Configuration Manager deice synchronizations and extractions NSM serice templates also allow client users to: Simplify the creation, modification, and deletion of network serices on network deices Hide the complexity of the network serice away from the client user Support multiple deice types with the one NSM serice template Create a robust and reproducible network configuration serice solution NSM Architecture Client System GET POST DELETE NSM URIs NSM REST API NSM Parameter Engine Submit work Retriee status C:\> NSM command line tools Netcool Configuration Manager Managed Deices Figure 1 NSM Architecture NSM serice lifecycle NSM proides the NSM client user with NSM serice URIs to enable the creation of network serices from the NSM serice templates NSM allows for network serices to be managed from creation to deletion Figure 2 on page 3 depicts the flow of the NSM serice lifecycle 2 IBM Tioli Netcool Configuration Manager: Network Serice Manager REST API

17 NSM Serice Lifecycle Network serice design Serice remoal Command set creation Client checks serice status OK Cancel Full change history and control XML Serice template creation NSM executes serice C:\> Client requests new serice Client iews new serice Import serice templates Figure 2 NSM Serice Lifecycle As the figure shows, the NSM serice lifecycle consists of the following: Network serice design The NSM serice designer plans the type of network serice that client users want to offer Command set creation The NSM serice designer uses the Netcool Configuration Manager tools to create and maintain the command sets associated with the network serice on the network deices Serice template creation The NSM serice designer uses the NSM serice template XML to design how the serice should be exposed to client users The NSM serice designer also decides how the parameters for the command sets should be calculated and in what order they should execute Import NSM serice templates The NSM serice designer uses the NSM command line tools to import the NSM serice template design XML files into the Netcool Configuration Manager database Client iews new serice The client user uses the NSM serice template REST URIs to iew the new network serice being offered Client requests new serice The client user can now request the NSM serice of choice using the NSM REST URIs NSM executes serice NSM executes the network serice as dictated by the NSM serice template NSM communicates with Netcool Configuration Manager to create the work items needed to complete the serice on the network deice Client checks for serice status The client user can iew serice execution status using the NSM serice URIs The client user can also check for specific configuration changes using extractions Chapter 1 Oeriew of the Network Serice Manager REST API 3

18 Serice remoal Depending on how the NSM serice template was designed, either the client user can request for a network serice to be deleted using the NSM REST API or the serice designer can create a schedule for when the network serice can be remoed NSM parameter calculation NSM proides the NSM serice designer the ability to decide how to calculate parameters used in the NSM serice lifecycle Figure 3 shows the NSM parameter calculation engine and how it calculates NSM parameters NSM Parameter Calculation SQL parameters JaaScript parameters Client parameters NSM parameter engine HTTP parameters NCM command sets Figure 3 NSM Parameter Calculation Specifically, the NSM parameter engine calculates the following types of parameters: Client parameters NSM can accept parameter name/alues from the client to pass directly to command sets or NSM can use the parameter name/alues in the NSM parameter engine to calculate other parameters SQL parameters NSM can query external or internal databases to retriee parameter alues The arguments to the SQL query can be proided by the client user or can be injected by the NSM serice designer JaaScript parameters NSM allows the execution of NSM proided JaaScript methods to manipulate parameters NSM also allows the NSM serice designer to proide their own controlled JaaScript HTTP parameters NSM allows the retrieal of parameters by calling an HTTP client using the URL that the NSM serice designer proides Figure 3 also shows that Netcool Configuration Manager command sets apply parameter alues as calculated by the NSM parameter engine The NSM serice designer sets up parameters in the NSM serice template so that: 4 IBM Tioli Netcool Configuration Manager: Network Serice Manager REST API

19 Client users can specify alues for the client parameters Client users can specify inject parameters through preset NSM functions or user-defined JaaScript functions NSM can query external or internal databases to retriee parameter alues for SQL queries NSM can retriee parameter alues using an HTTP request NSM roles Users with the roles of NSM serice designer, NSM client user, and Netcool Configuration Manager administrator can complete tasks on a Netcool Serice Manager system This topic describes the main responsibilities for each NSM role The users are referred to throughout NSM information topics Table 1 NSM user roles and functions NSM role NSM serice designer Responsibilities The NSM serice designer designs NSM serice templates that can be used by NSM client users The NSM serice designer can create NSM serice templates so that the NSM serice execution engine will call the Netcool Configuration Manager artifacts such as command sets, extractions, and deice synchronizations with the required parameters The NSM serice templates are designed so that NSM client users can populate the correct information for some parameters while other parameters are calculated by the NSM Parameter Engine By using the command-line tool, NSM serice designers can create and maintain these NSM serice templates NSM serice designers must hae the actiity Serice Template Management assigned to them by the Netcool Configuration Manager administrator In addition, the NSM serice designer can also use any NSM REST API URI that an NSM client user can access Note: NSM serice designers require the Netcool Configuration Manager administrator to grant them access to the realms that hold deices they want to retriee and access to realms that hae the command sets and extractions that the NSM serice templates need to execute NSM client user The NSM client user uses NSM REST API URIs to retriee proisioned NSM serice templates lists, retriee deice inentory, search realms and submit and monitor serices from a client application Depending on how the NSM serice designer defines the NSM serice template, these NSM client users might need to proide alues for some parameters NSM client users do not require any knowledge of underlying Netcool Configuration Manager command sets that the NSM Serice Engine executes NSM client users must hae the actiity Serice Management assigned to them by the Netcool Configuration Manager administrator NSM client users do not hae permission to create NSM serice templates Note: NSM client users require the Netcool Configuration Manager administrator to grant them access to the realms that hold deices they want to retriee and access to realms that hae the command sets and extractions that the NSM serice templates need to execute Chapter 1 Oeriew of the Network Serice Manager REST API 5

20 Table 1 NSM user roles and functions (continued) NSM role Responsibilities Netcool Configuration Manager administrator The Netcool Configuration Manager administrator is responsible for administering Netcool Configuration Manager in the context of users, access, configuration, installations, upgrade, and so forth After Netcool Configuration Manager is installed and configured, the Netcool Configuration Manager administrator does not need to be actie on NSM The Netcool Configuration Manager administrator is responsible for assigning the actiities Serice Template Management to NSM serice designers and Serice Management to NSM client users The Netcool Configuration Manager is also responsible for granting NSM serice designers and NSM client users access to the necessary realms The Netcool Configuration Manager administrator must ensure that the NSM serice designer has execute permissions for the nsmadminsh command line script NSM client users can skip to Chapter 6, Understanding the Network Serice Manager URIs, on page 79 and Chapter 8, Troubleshooting, on page 125 NSM serice designers should read the entire guide 6 IBM Tioli Netcool Configuration Manager: Network Serice Manager REST API

21 Chapter 2 Designing a NSM serice template NSM serice designers configure NSM serice templates to allow NSM client users to initiate serices for execution This information unit explains the main tasks inoled in designing a NSM serice template To illustrate the main tasks, an example to design a NSM serice template to create zones for a firewall is used Structure of a NSM serice template The following sample XML shows the basic structure of a NSM serice template to create zones for a firewall The sample XML identifies the main tags that a NSM serice template can contain <sericetemplate name="firewallcreatezones" description="create a Firewall Zone" timetodelete="1" > <clientparameter> <name>firewallzonename</name> <description>the Customer Zone Name eg cz_8262</description> </clientparameter> <implementations> <implementation> <rules> <rule type="deicetype"> <ruleproperty name="vendor" alue="ibm"/> <ruleproperty name="type" alue="router"/> <ruleproperty name="model" alue="*"/> <ruleproperty name="os" alue="*"/> </rule> </rules> <sericeoperations> <sericeoperation type="create"> <operations> <operation name="itncm/firewallcreatezones" type="commandset"> <parameters> <parameter name="firewallzonename"/> </parameters> </operation> </operations> </sericeoperation> </sericeoperations> </implementation> </implementations> </sericetemplate> Note: Some of the XML tags can include additional optional attributes that are not shown in this NSM serice template Copyright IBM Corp 2012,

22 Parameters NSM serice designers use parameters in NSM serice templates to enable appropriate alues to be passed on to Netcool Configuration Manager command sets as command set parameters NSM serice designers can use the following types of parameters when defining how parameters alues can be calculated: Constant parameters NSM serice designers can define constant parameters in the NSM serice template XML using the <constantparameter> element and assign alues to them using the <name> and <alue> tags when they design NSM serice templates Client parameters NSM serice designers can define client parameters in the NSM serice template XML using the <clientparameter> element and their alues are populated by NSM client users The <clientparameter> element makes use of the <name> tag Inject parameters NSM serice designers can define inject parameters in the NSM serice template XML using the <injectparameter> element and their alues are populated by ealuating the results of functions when the serice is executed The <injectparameter> element makes use of the <name>, <methodcall>, and <arguments> tags SQL parameters NSM serice designers can define SQL parameters in the NSM serice template XML using the <sqlparameter> element SQL parameter alues are alidated when they are submitted and before the serice is run The <sqlparameter> element makes use of the <name> and <sql> tags HTTP parameters NSM serice designers can define HTTP parameters in the NSM serice template XML using the <httpparameter> element HTTP parameters are populated by running a GET command and are ealuated when the serice is run The <httpparameter> element makes use of the <name>, <arguments>, and <url> tags Client parameter lists NSM serice designers can define client parameter lists in the NSM serice template XML using the <clientparameterlist> element and their alues are populated by NSM client users The <clientparameterlist> element makes use of the name attribute and the <parameter name> and <alue> tags Each parameter type can be either global or local Global parameters are used by all implementations Local parameters are specific to the <implementation> element in which they are defined For example, if there is a global client parameter called ZONENAME and a local SQL parameter also called ZONENAME then the alue of the local SQL parameter will be used Client parameters that are global are sent to the NSM client user to be populated irrespectie of the <implementation> element that is selected for the NSM serice template The data is set in the <alue> tag of the <clientparameter> element SQL, HTTP, and inject parameters that are global are also used by the <implementation> element that is selected for the NSM serice template The data is set in the <alue> tags of these parameters when the serice is executed Local parameters are specific to their own <implementation> element, and they do not affect anything outside this implementation For client parameters that are local, if the <implementation> element in which they are contained is selected based on the deice type, only then are they sent to the NSM client user to be populated at serice run time 8 IBM Tioli Netcool Configuration Manager: Network Serice Manager REST API

23 For SQL, HTTP, and inject parameters that are local, they are only calculated during serice execution if the <implementation> element in which they are contained is selected based on the deice type Client parameter lists that are placed at the global leel of the NSM serice template can be used by all implementation Use of client parameter lists within an implementation is determined by the placement of the name attribute found in the <clientparameterlist> element, for example, <clientparameterlist name="cpl_01"> The name attribute should be placed in the list of parameters within an <operation> element The <clientparameterlist> elements at a global leel are similar to <clientparameter> elements at a global leel in that they are sent to the NSM client user to be populated irrespectie of the <implementation> element that is selected for the NSM serice template The data is set in the <alue> tag of the <clientparameterlist> element and can contain multiple alues that can be populated by the NSM client user Related reference: Constant parameters on page 27 Client parameters on page 29 Client parameter list parameters on page 31 Inject parameters on page 36 SQL parameter element and tags on page 43 HTTP parameters on page 45 <implementations> element <implementations> element The <implementations> element is a container that includes rules, local parameters, and the operations for the NSM serice template The purpose of the <implementations> element is to ensure that the NSM client user is presented with the correct implementation in a particular NSM serice template based on the deice that the NSM client user has selected to run the serice on Local client parameters such as inject, SQL, and HTTP parameters can also be contained in the <implementations> element and executed at this stage For example, if SQL parameters are configured, the SQL statement is executed on the database connection that is specified in the <databaseconnection> element Operations are also contained in the <implementations> element Operations can contain indiidual operations, all of which are selected for serice execution The following XML shows the full implementation details to create zones for a firewall serice Note that the <implementations> and </implementations> elements encapsulate the XML elements and tags that define the zones for a firewall serice with separate implementations for Juniper and CISCO Routers Thus, if the NSM client user wants the Firewall serice to run on a CISCO deice, the operation ITNCM/FirewallCreateZones-Cisco-Router (<operation name="itncm/firewallcreatezones-cisco-router") will run If the NSM client user wants to execute the Firewall serice on a Juniper router, then the operation ITNCM/FirewallCreateZones (<operation name="itncm/firewallcreatezones") will run <implementations> <implementation description="implementation Rule for all Cisco Routers"> <rules> <rule type="deicetype"> <ruleproperty name="vendor" alue="cisco"/> <ruleproperty name="type" alue="router"/> Chapter 2 Designing a NSM serice template 9

24 <ruleproperty name="model" alue="*"/> <ruleproperty name="os" alue="*"/> </rule> </rules> <databaseconnection> <drierclassname>oraclejdbcdrieroracledrier</drierclassname> <username>oracleuser</username> <password>password</password> </databaseconnection> <clientparameterlists> <clientparameterlist name="zoneid"> <parameter name="zone_name"/> </clientparameterlist> <clientparameterlist name="routedetails"> <parameter name="sourceroutetable"/> <parameter name="targetroutetable"/> <parameter name="virtualroutername"/> </clientparameterlist> </clientparameterlists> <sqlparameters> <sqlparameter> <name>sourceroutetable</name> <sql>select serername from task where id = 3</sql> </sqlparameter> </sqlparameters> <sericeoperations> <sericeoperation name="createoperation" type="create"> <operations> <operation name="itncm/firewallcreatezones-cisco-router" rollback="true" type="commandset"> <parameters> <parameter name="virtualroutername"/> <parameter name="name"/> <parameter name="sourceroutetable"/> <parameter name="targetroutetable"/> <parameter name="zoneid"/> <parameter name="routedetails"/> </parameters> </operation> </operations> </sericeoperation> </sericeoperations> </implementation> <implementation description="implementation Rule for all Juniper Routers"> <rules> <rule type="deicetype"> <ruleproperty name="vendor" alue="juniper"/> <ruleproperty name="type" alue="router"/> <ruleproperty name="model" alue="*"/> <ruleproperty name="os" alue="*"/> </rule> </rules> <clientparameters> <clientparameter> <name>ribgroupname</name> </clientparameter> </clientparameters> <sericeoperations> <sericeoperation name="createoperation" type="create"> <operations> <operation name="itncm/firewallcreatezones" rollback="true" type="commandset"> <parameters> <parameter name="virtualroutername"/> <parameter name="name"/> <parameter name="sourceroutetable"/> <parameter name="targetroutetable"/> <parameter name="ribgroupname"/> </parameters> </operation> </operations> </sericeoperation> </sericeoperations> </implementation> </implementations> Related concepts: Parameters on page 8 10 IBM Tioli Netcool Configuration Manager: Network Serice Manager REST API

25 Configuring rules A <rule> element includes one type called DeiceType The DeiceType includes four properties, which are attributes of the deice A <rule> element must include a type attribute and one or more <ruleproperty> elements which define the effect of the rule The <ruleproperty> element specifies a name and alue pair for each of the rule properties the rule contains At present only DeiceType rules are supported and the <ruleproperty> elements for this rule type define the attributes of deices to which the rules can be applied There are four attributes which can be specified for a deice: the endor or manufacturer of the deice, its type, model, and the operating system ersion of the onboard software Together these properties are known as VTMOS The VTMOS data is stored on the Netcool Configuration Manager presentation serer for eery deice that has been discoered The DeiceType rule for an implementation must specify all four alues for the VTMOS data of the deices to which it can be applied An indiidual <ruleproperty> element is expected within a DeiceType rule for each of the following four names: Vendor Type Model OS The name attribute of the <ruleproperty> element must be specified as shown in the procedure You can use regular expressions for each of the four names (for example, alue="*") Use the <rule> element to determine which implementation to select when an NSM client user requests a NSM serice template for serice execution If the NSM client user that is requesting the NSM serice template uses a deice id for a deice that equals the endor, type, model, and operating system that are specified in the following <ruleproperty> tags, then the implementation based on this rule is selected Procedure The NSM serice designer can manage, using regular expressions, which deices should be allowed to execute operations in this implementation based on the rule properties (using the <ruleproperty> tags) that they define For example, if an NSM serice designer wants an implementation that can run operations for all CISCO routers, regardless of model and operating system, then they would create a rule such as shown in the following example The "*" for Model and the OS in regular expression format means match anything for model and operating system Thus, the regular expression would select all CISCO routers <rules> <rule type="deicetype"> <ruleproperty name="vendor" alue="cisco"/> <ruleproperty name="type" alue="router"/> <ruleproperty name="model" alue="*"/> <ruleproperty name="os" alue="*"/> </rule> </rules> Chapter 2 Designing a NSM serice template 11

26 Example To exactly match deices that hae a Model "10*", then the regular expression format in the <ruleproperty> tag must be written as follows: <ruleproperty name="model" alue="10\\*"/> where: the \ (backslash) is used to escape the (period) and * (asterisk) characters, which hae special meaning in regular expressions If the deice operating system that you want to match is C2600-IS-M-122(3), then the regular expression format in the <ruleproperty> tag must be written as follows: <ruleproperty name="model" alue="c2600-is-m-12\2\(3\)"/> where: the \ (backslash) is used to escape the (period) and () (left and right parentheses) characters, which hae special meaning in regular expressions If the deice operating system that you want to match is *M56*, then the regular expression format in the <ruleproperty> tag must be written as follows: <ruleproperty name="model" alue= "\*M56\*"/> where: the \ (backslash) is used to escape the * (asterisk) characters, which hae special meaning in regular expressions Configuring serice operations A serice operation specifies the type of serice operation to be carried out according to the specified operations Operations are encapsulated in the <sericeoperation> and </sericeoperation> elements There are two types of serice operations: CREATE and DELETE The operations themseles are encapsulated in <operation> and </operation> elements Each serice operation requires the type attribute This type attribute currently supports two types: CREATE, which sets up a serice and DELETE, which tears down a serice An optional name attribute can be specified to identify a serice operation An <operation> element includes a name attribute It also includes the parameter list that is used when the serice is submitted for execution and other attributes The NSM serice designer uses this parameter list to erify that the required parameters are specified in the NSM serice template during its creation The NSM serice designer also uses this parameter list to filter parameters so that only the required ones are submitted to execute the serice Procedure 1 As the NSM serice designer use the following example as a guide to configuring serice operations and operations The example presents a configured operation for creating zones for a firewall <sericeoperations> <sericeoperation name="createoperation" type="create"> <operations> <operation name="itncm/firewallcreatezones-cisco-router" rollback="true" type="commandset"> <parameters> <parameter name="virtualroutername"/> <parameter name="name"/> <parameter name="sourceroutetable"/> <parameter name="targetroutetable"/> <parameter name="zoneid"/> </parameters> 12 IBM Tioli Netcool Configuration Manager: Network Serice Manager REST API

27 </operation> </operations> </sericeoperation> </sericeoperations> 2 Specify alues for the <sericeoperation> element as follows: a (Optional) Enter the name of the serice operation in the name attribute In the example, the serice operation name is createoperation b Enter the serice operation type in the type attribute In the example, the serice operation type specified is CREATE, which specifies a create serice 3 Specify alues for the <operation> element as follows: a Enter the name of the operation in the name attribute In the example, the operation name is ITNCM/FirewallCreateZones-Cisco-Router, which is the fully qualified name of the command set on Netcool Configuration Manager b Set the alue for rollback in the rollback attribute to either true or false In the example, the rollback is set to true If an operation fails while it is being executed and rollback is set to "true", the operation is reerted and the deice is returned to its original configuration before the operation started If rollback is set to "false", then rollback is not configured and the operation is not reerted to its original configuration c Enter the operation type in the type attribute In the example, the operation type is COMMANDSET Valid alues for the type attribute are: COMMANDSET, EXTRACTION, DEVICESYNC, IMPORT, DISCOVER, and REMOVE 4 Populate the parameters list with the required parameters for the NSM serice designer to be used in serice execution If the operation type is COMMANDSET, the parameters specified in the name attributes must match the parameters that are required in the command set configured on the Netcool Configuration Manager presentation serer Note: For a client parameter list to specify the parameters to be used within an operation, the name attribute of the <clientparameterlist> element must be used to link the client parameter list to the operation For example: <clientparameterlists> <clientparameterlist name="cpl_name"> <parameter name="sourceroutetable"/> <parameter name="targetroutetable"/> <parameter name="virtualroutername"/> </clientparameterlist> </clientparameterlists> <sericeoperations> <sericeoperation name="createoperation" type="create"> <operations> <operation name="itncm/firewallcreatezones-cisco-router" rollback="true" type="commandset"> <parameters> <parameter name="cpl_name"/> </parameters> </operation> </operations> </sericeoperation> </sericeoperations> Related reference: Operation attributes and types on page 14 Chapter 2 Designing a NSM serice template 13