Downloads |
 Feedback
|
Table Of Contents
Using Object Grouping Services
Getting Started with OGS Server
Customizing OGS Server Interfaces
Creating a Custom OGS Event Processor
Understanding ASA Infrastructure Modules
About Composite Rule Expressions
Customizing ASA Infrastructure Modules
Customizing the Rule Validator
Customizing the Generic Schema
Customizing the Rule Evaluator
Customizing the Mapping Schema
Customizing the Rule Convertor and Rule Expressions
Customizing the ASA Change Alerter
Creating the ASA Configuration File
Example: Using the Generic SQL ASA
Using Secure Views With DCR IDs
Using Secure Views with Object Selector
Using Secure Views With the OGS Administrative GUI
Customizing Your Secure Views Implementation
Specifying a Non-Default Implementation
Using Secure Views Without DCR IDs
Using OGS Common and Shared Groups
Configuring OGSServer.properties
Configuring SharedGroups.properties
Implementing the SharedGroupObjectMapperIf Interface
OGS Utility Class for Common and Shared Groups
Using OGS 1.3 Client Side Enhancements
About the Enhanced OGS 1.3 Classes and Data Structures
Controlling the Display of Wizard Steps
Integrating OGS 1.3 With Your Application
Integrating OGS 1.4 With Your Application
Integrating Configurable Display Name for Class Names Feature with Applications
Using Object Grouping Services
The CWCS Object Grouping Service (OGS) provides a generic means for creating, managing and sharing groups of objects, regardless of type.
The following topics describe the OGS and how to use it in your applications:
•
Using OGS Common and Shared Groups
•
For more information about OGS, refer to the following resources:
•
•
•
•
•
•
•
•
•
•
•
Understanding OGS
OGS allows applications to create, manage, and share persistent groups of objects.
OGS is a generic grouping service. It does not supply you with predefined groups. Instead, it provides tools that allow you to define groups useful to your application. Once you have defined the groups you want, you can supply them in predefined form with your application.
OGS places no limits on the types of objects you can group. Most developers use OGS to group network devices. However, you can also use it to manage groups of scheduled jobs, policies, users, tasks, VLANs, subnets, IP phones, user interface views, fault conditions, or any other kind of object that can be grouped based on shared attributes.
The following topics explain the basics of OGS:
About the OGS Components
A complete OGS system includes the following components
•
•
•
Basic OGS Concepts
OGS makes use of several concepts whose definitions differ from the commonly used definitions:
•
An OGS class describes the representation of a set of application abstractions. This differs from traditional object-oriented systems, where a class defines a set of attributes and the operations that can be performed on instances of that class.
An OGS class is concerned only with the representation and retrieval of attributes. Class hierarchies are supported and are interpreted in the conventional sense; that is, a subclass inherits all the attributes of its superclasses. An instance of an OGS class can be used in any context where an instance of one of its superclasses is expected.
•
An OGS object is a collection of attribute values. The OGS class of an object determines the set of attributes associated with that object. Associated with every object is a unique and immutable object ID (OID). When an ASA evaluates a rule, the data returned to the OGS Server is a collection of proxy objects that contains:
–
–
These proxy objects are referred to as OGS objects in the rest of this document.
•
An OGS group is a named aggregate entity comprising a set of objects belonging to a single class or a set of classes with a common superclass. Groups can be shared between users or applications, subject to access-control restrictions. The membership of a group is determined by a rule.
•
An OGS rule consists of one or more rule expressions combined by operators, which can be AND, OR or EXCLUDE. A rule always evaluates to objects of a particular class defined in an application schema.
About OGS Groups
A group in OGS is a named aggregate entity comprised of a set of objects. Each group has:
•
•
OGS Servers represent the group membership as a list of object IDs. Besides the OID list, attributes associated with the objects in a group may also be queried. The attributes of a class and the hierarchical relationship of classes are defined in the Application Service Adaptor schema, which must be registered with the OGS.
Each OGS group has a set of properties, including a unique name. Table 28-1 describes these properties.
About OGS Group Types
OGS groups can be either dynamic or static (see also the "About OGS Container Groups" section).
A dynamic group is one whose membership list is effectively computed every time a user views its members. For each request to view the group, the OGS Server may automatically request the relevant Application Service Adapter to recompute the group's rule. The Server is not required to store a dynamic group's membership list (although it may cache the results of the last re-evaluation), and viewing a dynamic group will always give the latest group membership.
Example
A user creates the dynamic group "MyDevices", which has the rule "IPAddress in Subnet 172.20.32.0/24". At creation time, the rule evaluates to devices D1, D2, and D3. If a user attempts to view the group membership at any later time, the OGS Server will return the current membership.
If new devices D4 and D5 joined subnetwork 172.20.32.0/24 in between the time the group was created and the time its membership was queried, OGS will return devices D1, D2, D3, D4 and D5 as the current members of the group.
A static group is one whose membership is refreshed only when a user explicitly requests it. Between re-evaluations, the OGS Server stores the static group's membership list and group definition. Whenever a user views a static group, OGS returns the membership list the ASA created the last time the group rule was evaluated.
Note that the OGS may cache the membership and maintain the cache by other means. Group definitions are always stored, regardless of whether the group is static or dynamic.
Example
A user creates the static group "MyDevices", which has the rule "IPAddress in Subnet 172.20.32.0/24". The rule evaluates to devices D1, D2, and D3, and the OIDs for these devices is stored along with the group definition.
If a user attempts to view the group, he will see only devices D1, D2 and D3, as these were the devices that satisfied the group rule when the group was created.
If the user wants to refresh the membership of the group, then he must explicitly request it. The OGS Server will then ask the ASA to reevaluate the rule.
If new devices D4 and D5 joined subnetwork 172.20.32.0/24 in between the time the group was created and the time the user requested the refresh, OGS will return devices D1, D2, D3, D4 and D5 as the current members of the group. This device list will also be stored as the membership of "MyDevices" until the next refresh.
Most OGS groups are dynamic. Static groups are useful when you want users to be able to "snapshot" a group's membership and maintain it until a later time, when the user can quickly update it without having to change the group definition.
Example
A network administrator in a large enterprise is responsible for the management of all operational Catalyst 6K series switches. Switches in this enterprise must go through several configuration stages before they are considered operational. Configuration is done by a department to which the Network Administrator does not belong. Before becoming operational, the switches may also be available on the network.
To cope with this, the Network Administrator could create a static group called "My Cat6K Devices" with the rule "DeviceType == Catalyst 6K". This would allow him to accomplish the following:
•
•
•
About OGS Container Groups
Container groups are a separate type of group, on par with normal groups. This is because they are groups who have no membership of their own. A container group is an "empty" container, whose membership is simply the union of the membership of all its subgroups.
This is different from normal groups that must have a rule to determine its membership. Instead, a container group's effective rule consists of:
•
•
•
Container groups are can be static or dynamic depending on the behavior of their subgroups:
•
•
About OGS Group Hierarchy
OGS manages groups in a hierarchical fashion and supports subgrouping. Each child group is a subgroup of a parent group and its group membership will be a subset of its parent group. OGS also supports container groups. Container groups are groups with no rule, whose membership is simply the union of the membership of its children.
Regardless of whether a group's parent is static or dynamic, the result of evaluating a group is the intersection of the objects that satisfy its rule and the objects that satisfy its parent's effective rule.
The effective rule for a static group is a rule that enumerates its members. When a static group is reevaluated, all its descendant static groups will also be reevaluated.
The effective rule for a dynamic group is an expression that is formed by applying the operator AND to the operands that are the group's rule and its parent's effective rule.
How Rules Are Constructed
A group rule consists of one or more expressions, which can be combined using the operators AND, OR or NOT. Each expression has the following components, concatenated with a ":"separator
•
•
•
•
•
•
Example
The following rule will select Devices which are either Routers or have an IOS Version greater than 11.3 and that are assigned IP Addresses beginning with the octets "172.20":
MYAPP:RME:Device.DeviceTypeEquals "Router" or MYAPP:RME:Device.IOSVersion > "11.3" AND MYAPP:RME:Device.IPAddressContains "172.20"Choosing to Implement OGS
If you want to implement OGS in your application without extensive customization, you must also:
•
•
•
•
•
In addition to these requirements, your application must support JDK 1.3.1.
Implementing OGS Servers
The OGS Server performs the following tasks:
•
•
–
–
–
The OGS Server provides its clients with a unified and consistent view of group definitions and results of rule evaluation. It does this by recording any change to the group information (through creation, modification, deletion or evaluation of a group).
The OGS Server relies on:
•
•
•
The following topics discuss OGS Server and its implementation in detail:
•
•
•
Getting Started with OGS Server
Setting up a running OGS Server instance normally requires you to create an Application Service Adaptor (ASA) for your application and then set the OGS Server to use it.
You can also create a very simple OGS Server implementation using the test ASA supplied on the SDK. The following steps explain how to install OGS Server and configure it to use TestASA. via a script file.
For details on writing an ASA that performs work useful to your application, see "Creating OGS ASAs" section.
Step 1
Step 2
•
•
Step 3
Step 4
Step 5
Step 6
How OGS Server Works
OGS Server makes use of five classes to instantiate its most important behaviors:
•
This class models the OGS notion of classes (see the "Basic OGS Concepts" section). The OGS Server creates instances of OGSClassDefinition using the definitions of OGS classes in an application schema. An OGSClass instance holds information about an application class. such as its name, its domain and the application to which it belongs, the attributes associated with it, attributes that can be used in composing rules, the operations that are permitted on those attributes, and the allowable target values.
•
This class models the OGS notion of objects (see the "Basic OGS Concepts" section). ASAs create instances of OGSObject and return lists of them to the OGS Server whenever the ASAs evaluate rules. Each OGSObject instance contains the OID of the application class object it represents, and the values of the other attributes that were requested by a client.
•
These two classes model the expressions used in rules and the rules themselves.
•
This class models OGS groups in a straightforward manner. It has instance variables that store group information, such as group ID, name, ownership, creation and modification times, and so on.
An active OGS Server instance is an executing operating system process that runs as a daemon. Developers should use the CWCS Daemon Manager (see Chapter 18, "Using the Daemon Manager") to manage OGS Server states.
Upon activation, an OGS Server process performs initialization tasks, such as reading static ASA registration and group definitions from its persistent store.
If initialization is completed successfully, OGS Server publishes its URN to CSTM and waits for requests. When it receives requests, it passes them to the appropriate registered ASA, and returns the result.
Using the OGS Server APIs
The OGS Server API allows you to:
•
•
•
•
•
•
•
Usage, input arguments and other details for each OGSServer API call are fully documented in the OGS Javadoc available on the OGS Portal at https://mco.cisco.com/ubiapps/portal/go.jsp?portal_id=6625.
The following example demonstrates how to implement the API as part of a client application.
Example 28-1 A Sample OGS Client
package com.cisco.nm.xms.ogs.client;import java.util.ArrayList;import com.cisco.nm.xms.ogs.server.OGSInterface;import com.cisco.nm.xms.ogs.util.OGSOid;import com.cisco.nm.xms.ogs.util.OGSSecurityContext;import com.cisco.nm.xms.ogs.util.OGSObjectList;import com.cisco.nm.xms.ogs.util.OGSObject;import com.cisco.nm.xms.ogs.util.ClassPath;import com.cisco.nm.xms.ogs.client.OGSServerProxy;public class GetDeviceGroups {// This program retrieves all groups managed by an OGS Server// that have at least one device object as a member. The program// is invoked with a single argument that names the class that// represents device objects.public static void main(String[] args){if (args.length != 1) {System.out.println("usage: GetDeviceGroups device-class-name");System.exit(-1);}_devClassName = args[0];_devClassLength = _devClassName.length();try {_devClassElements = new ClassPath(args[0]).elements();} catch (Exception ex0) {System.err.println("Error getting elements of class: " + args[0]+ ": " + ex0.getMessage());}TaskID task=new TaskID ("OGS", "OGSOPERATION", null); OGSSecurityContext ctxt=new OGSSecurityContext(_adminName,task);try {// Get the hierarchical membership of the root of all// groups. Having retrieved the membership in this// fashion, we can now examine the membership of// all the descendant groups and determine the ones// whose membership contains at least one device object.OGSServerProxy pxy = new OGSServerProxy();Integer mtype = new Integer(OGSInterface.HIERARCHICAL_MEMBERSHIP);OGSObjectList list= pxy.evaluateGroup(ctxt,null,null,_root,null,mtype,Boolean.FALSE);String[] devices = getDeviceGroups(list);for (int i = 0; i < devices.length; ++i) {System.out.println(devices[i]);}} catch (Exception ex) {System.err.println("Error getting device groups: " +ex.getMessage());}}private static String[] getDeviceGroups(OGSObjectList list){ArrayList result = new ArrayList();OGSObjectList[] children = list.children();for (int i = 0; i < children.length; ++i) {getDeviceGroups(list, result);}return (String[])result.toArray(new String[0]);}// This method gathers the names of all the groups// (in the hierarchy rooted at the group represented by 'list')// have at least one device object as a member.private static boolean getDeviceGroups(OGSObjectList list, ArrayList result){boolean hasDevice = false;OGSObjectList[] children = list.children();for (int j = 0; j < children.length; ++j) {if (getDeviceGroups(children[j], result)) {hasDevice = true;}}// If any descendant has a device member, this group// has it too.if (hasDevice) {result.add(list.name());return true;}// This group has no descendants that have a device// member, so check the membership of the group for// devices.OGSObject[] objects = list.objects();for (int i = 0; i < objects.length; ++i) {String oid = objects[i].objectId();try {String objClass = OGSOid.getClassFromOid(oid);if (isDeviceClass(objClass)) {result.add(list.name());return true;}} catch (Exception ex) {System.err.println("Error processing object: " + oid);}}return false;}// Returns true if the class named by 'cname' is the same// as the device class or is a subclass.private static boolean isDeviceClass(String cname){if (cname.length() < _devClassLength) {return false;} else if (cname.equals(_devClassName)) {return true;}// The following can also be achieved by verifying that// _devClassName is a prefix of cname and that the character// following the matching prefix is ':'.try {ArrayList classElements = new ClassPath(cname).elements();if (classElements.size() < _devClassElements.size()) {return false;}for (int i = 0; i < _devClassElements.size(); ++i) {String s1 = (String)classElements.get(i);String s2 = (String)_devClassElements.get(i);if (!s1.equals(s2)) {return false;}}return true;} catch (Exception ex) {System.err.println("Error getting elements of: " + cname);return false;}}private static int _devClassLength;private static String _devClassName;private static ArrayList _devClassElements;private static String _root = "/";private static String _adminName = "admin";}
Note
Customizing OGS Server Interfaces
All OGS Server interfaces that you can customize are listed as settable parameters in the OGSServer.properties file. These customizable interfaces include:
•
This is an implementation of the interface OGSGroupCacheIf (see Figure 28-1). OGS uses an instance of this class as a source of grouping data. Though an ASA ultimately evaluates the rule, this abstraction is defied so that group membership can be cached. The OGS Server uses an instance of the class specified for this property for every ASA that is registered. A limitation in this release of OGS is that instances of only a single class can be used for caching, even when multiple ASAs are used (that is, the caching strategy cannot be customized for the individual ASAs). The default value is com.cisco.nm.xms.ogs.server.GroupCacheImpl. Use the default implementation if possible, or subclass GroupCacheImpl (as Kilner does).
•
An implementation of the interface OGSGroupPersistorIf (see Figure 28-1). The OGS Server uses this class to persist and retrieve group definitions. The default value for this property is com.cisco.nm.xms.ogs.server.GroupPersistorImpl. This implementation uses the CWCS database to persist group definitions. Use the default implementation unless your product has special requirements.
•
This is an implementation of the interface GroupCachePersistorIf (seeFigure 28-2 and the caching information in this topic). Instances of GroupCacheImpl use an instance of this class to persist cached membership data, so this property is relevant if the OGS is configured to use class GroupCacheImpl (or its subclass) only.
The default value for this property is com.cisco.nm.xms.ogs.server.GroupCachePersistorImpl. Use the default implementation unless your product has special requirements.
•
This is an implementation of OGSSecurityHandlerIf (see Figure 28-1). OGS uses an instance of this class to enforce access control on groups, but not on the group membership.
The default value for this property is com.cisco.nm.xms.ogs.server.DummySecurityHandler, which allows unrestricted access by all users. You can find examples of implementations that follow different security requirements (those for Campus Manager and Kilner) in the OGS VOB.
•
This specifies the XML file used to register ASAs with the OGS Server and identifies the ASA implementation to be used. See the "Registering the ASA with OGS" section for an example ASA Registration File and its DTD.
•
The file that contains the definitions of any predefined groups you have customized for your product and that you will ship with OGS. For a sample version of this, see Kilner's System Groups file, vasa-system-groups.xml.
•
This specifies the name of the creator of the system predefined groups given in the SystemGroupsFile. This can be any string, but your security module may place some restrictions on what this should be. The default value is "ogs".
•
This class can be used to do any postprocessing operation after the OGSServer starts in the environment.
For example, the published URNs need to be unpublished URNs need to be unpublished when the daemon manager stops the OGS server. This is done by the implementation of OGSEnvironmentAdapterIf interface. Another related property is OGSEnvRegistrationName which specifies the process or daemon name of the OGS server.
Figure 28-1 shows the relationships among these OGS Server properties.
Figure 28-1 OGS Server Interfaces
In addition to these interfaces, the default OGS Cache Manager (class GroupCacheImpl) has three cache update mechanisms that it activates periodically. All three update mechanisms use implementations of the interface CacheUpdaterIf shown in Figure 28-2:
1.
2.
3.
Figure 28-2
OGS Cache Manager Interfaces
Of these three updater mechanisms, the first two (BasicCacheUpdater and ReactiveCacheUpdater) can be customized. To customize the two updaters, you can set the following OGSServer.properties parameters:
•
Sets the interval in seconds between activations of the BasicCacheUpdater. A value of -1 disables this updater. The default value is 60.
•
Specifies the name of the class that implements CacheUpdaterIf (see Figure 28-2). This is normally the default class or one of its subclasses: ReactiveCacheUpdater in com.cisco.nm.xms.ogs.server. For an example of a custom reactive updater, see KilnerReactiveUpdater in com.cisco.nm.xms.ogs.Kilner10.
•
Sets the interval in seconds between activations of the reactive updater. A value of -1 disables this updater. The default value is -1 (that is, the reactive updater is disabled in the default configuration.
OGSServer.properties also allows you to customize the following properties:
•
Sets the string representing the ID of the product in which this OGS implementation is used. This is used to create strings for names of events published by this instance of OGS.
•
Sets the string representing this instance of OGS. This is reserved for future use.
•
Specifies whether you want cache initialization errors to be ignored when creating dynamic groups, so that dynamic group creation will not fail. This property does not affect static groups, since these groups, by definition, require that their membership be completely determined at creation time. We recommend that you set this property value to True; the default value is False.
•
Specifies the name of the class that implements OGSEventProcessorIf (see Figure 28-2). This interface allows a product to customize how OGS events are dispatched. Normally, this is the default class DefaultEventProcessor, which dispatches OGS events with no modifications.
For an example of a custom Event Processor, see KilnerEventConsolidator in com.cisco.nm.xms.ogs.Kilner10 and the "Creating a Custom OGS Event Processor" section, which examines KilnerEventConsolidator in detail.
Creating a Custom OGS Event Processor
The DefaultEventProcessor in OGS dispatches OGS events without modifications. Each such event is dispatched as a message, with a subject name that looks like this:
cisco.mgmt.cw.product_id.ip_address.ogs.alertWhere:
•
•
The subject of the message describes an atomic change to the data OGS manages, including group creation, deletion, modification, renaming, or membership change. This can often result in hundreds of messages.
For example, consider a group high in a group hierarchy that is deleted. In this case, atomic "deletion" messages will be generated for every subgroup. If there are 50 such subgroups, the default Event Processor will forward 51 "group deletion" messages. Similarly, a single modification in a group containing 1000 objects would result in 1000 group-membership change events.
You can create your own Event Processor, and use the OGSServer.properties parameter "EventProcessorImplClass" to implement it (see the "Customizing OGS Server Interfaces" section). The custom Event Processor can handle events in any way you wish, up to and including suppressing all events.
Kilner offers an example of a custom Event Processor: KilnerEventConsolidator in com.cisco.nm.xms.ogs.Kilner10. This processor dispatches customized "consolidated events", which logically group or aggregate atomic OGS event information based on the operation that triggered those events.
The subject name for a consolidated event in Kilner looks like this:
cisco.mgmt.cw.kilner.ip_address.ogs.alert.consolidatedeventWhere consolidatedevent is a single message that consolidates the individual events that are the results of a single "groupcreation", "groupdeletion", "groupmodification", "grouprename", "membershipchange", or "serverstart" operation. The body of the message will contain the atomic event data consolidated under that "heading".
For every consolidated event, an instance of class ConsolidatedOGSEvent in com.cisco.nm.xms.ogs.kilner10 is sent in an object message.
Processing requires:
1.
–
–
–
2.
For more on creating a consolidated Event Processor, see:
•
•
Handling OGS Exceptions
The OGS API defines the exception classes shown in Table 28-2. The list includes a description of the kinds of operations that typically result in these exceptions. All of these exception classes are subclasses of OGSException. In addition to these exceptions, you should be sure that your application is prepared to handle instances of OGSException that represent internal errors.
Creating OGS ASAs
In order to use OGS, you must create and associate with your application an Application Service Adapter (ASA). The OGS Server depends on ASAs to:
•
•
•
•
The remainder of this topic explains what is needed to create an OGS ASA, including:
•
•
About ASA Implementations
There is no default ASA supplied with OGS. However, the OGS team provides a set of libraries and tools to assist in ASA development, and default or example implementations for most modules.
Application developers and the OGS Team have also collaborated in creating OGS ASAs for several applications. These serve as ready-made examples of how to create customized ASAs, and their code is available on a read-only basis to Cisco developers with access to ClearCase:
•
•
•
Managing ASA Processes
OGS Server will load an ASA into its JVM if the ASA Registration File (see the "Running a Customized ASA" section) specifies a Location type of "local". OGS Server will manage startup and shutdown, and registration with CSTM, of any local ASA.
Developers should use the CWCS Daemon Manager (also known as Process Manager; see Chapter 18, "Using the Daemon Manager") to manage startup and shutdown of the OGS Server.
A "local" ASA is the only ASA type allowed in this release of OGS. Future OGS versions will allow ASAs to run remotely, either alone or within the JVM of a non-OGSServer application.
When planning your application's use of OGS in future releases, please note that remote ASAs will need to register themselves with OGSServer and with CSTM, and must be controlled by the CWCS Daemon Manager, to ensure they are available to requests from OGS Servers.
Using ASAs to Aggregate Data
Under normal circumstances, OGSServer is responsible for aggregating data resulting from the evaluation of a query on multiple instances of an ASA. However, it is possible to customize ASAs to perform this function if requirements make this necessary.
For example, an ASA may require tight cooperation between its instances to evaluate rules. In this case, the ASA can register a single instance that will then be responsible for communicating client requests to the other instances and aggregating the results before returning them to the OGS Server.
About the OGSServer-ASA Interface
Provided as ASAInterface in com.cisco.nm.xms.ogs.asa, this component allows the ASA and OGSServer to exchange commands, queries and result data via the Common Services Transport Mechanism.
All current ASA structures implement this interface. However, the interface is pluggable, which means that you can substitute your own ASA structure for the one described here.
You may want to do this if you have a very simple object grouping requirement.
For example, you may require OGS to parse a flat file containing nothing but a list of user names. In this case, you can write your own simple ASA class and implement it. However, your ASA class must:
•
•
•
Understanding ASA Infrastructure Modules
The basic function of your application's ASA is to validate and evaluate rules passed to it by the OGS Server. To perform these functions, your ASA needs the following modules:
1.
2.
3.
4.
5.
6.
7.
8.
Figure 28-3 shows the relationships among these modules.
For guidelines and examples on how to customize these infrastructure modules for your application, see the "Customizing ASA Infrastructure Modules" section.
For other examples of custom ASAs, see the ClearCase VOBs listed in the "Creating OGS ASAs" section.
Figure 28-3 ASA Infrastructure Modules
About the Rule Validator
The Rule Validator ensures that:
1.
2.
3.
4.
5.
In addition to these tasks, the Rule Validator can also check the validity of any:
•
•
The Rule Validator depends on the Generic Schema to perform these tasks.
About the Generic Schema
The Generic Schema consists of a Parser and XML Schema file describing the groupable classes, attributes, operators and values (including any value ranges and enumerations) valid for all objects. The Parser supplies this structure to the Rule Validator.
About the Rule Evaluator
The Rule Evaluator:
1.
2.
3.
4.
5.
When combining Rule Expressions, the Rule Evaluator must group them into queries specific to the needs of the data-storage resource. These queries can be:
•
•
The Rule Evaluator depends on the Mapping Schema to format the query appropriately.
About the Mapping Schema
The Mapping Schema consists of a Parser and XML Schema file that specifies the mapping between groupable OGS classes and the elements in the application's data-storage resource where the data for these objects is actually stored. The Rule Evaluator uses this information to convert rules into data-store-specific queries.
About the Rule Converter
The ASA infrastructure notation for a Rule Expression is different from the notation used by the OGS Server. This is necessary because the ASA can store extra information in the rule to help the Rule Evaluator generate queries.
Example
A Rule Expression for use with a SQL ASA can contain the entire query formed by the Query generator. The Rule Expression to be used with the Kilner VMSA can contain other types of information specific to a SMARTS Repository.
The Rule Converter converts any rule passed by the OGS Server into a rule format used by the Rule Validator and Rule Evaluator.
About Node Rule Expressions
A Node Rule Expression contains four elements:
1.
2.
3.
4.
For example: In the Node Rule Expression Device IpAddress contains "172.20", the class is Device, the attribute is IpAddress, the operator is contains, and the value is "172.20".
Similar examples of Node Rule Expressions would include: Device SystemLocation contains "US", or Device SystemLocation contains"San Jose".
About Composite Rule Expressions
A Composite Rule Expression contains two or more Rule Expressions combined by the operators AND, OR or EXCLUDE.
The Rule Expressions combined in this way can be either Node Rule Expressions or other Composite Rule Expressions.
For example, we can create a Composite Rule Expression using just two Node Rule Expressions: Device IpAddress contains"172.20"AND Device SystemLocation contains "US"
We can also create a Composite Rule Expression that combines the foregoing Composite Rule Expression with another Node Rule Expression: (Device IpAddress contains"172.20" AND Device SystemLocation contains "US") OR Device SystemLocation contains"San Jose".
About the ASA Change Alerter
The ASA Change Alerter informs the OGS Server whenever a change to an object takes place in the data-storage resource containing the object data. The ASA Change Alerter must inform OGS Server whenever:
•
•
•
•
•
•
Customizing ASA Infrastructure Modules
The ASA infrastructure modules must be customized depending upon your application's requirements for:
•
•
•
The following topics provide guidelines and examples for customizing each of the ASA Infrastructure Modules:
•
•
•
•
•
•
Customizing the Rule Validator
The Rule Validator function is provided by the default validator class GenericValidatorImpl in com.cisco.nm.xms.ogs.asa. You will rarely need to extend this class to customize it.
Customizing the Generic Schema
The Generic Schema parser has been designed for reuse with very little change. The Generic Schema parser function is provided by a default schema parser class, OGSSchemaParser in com.cisco.nm.xms.ogs.server.parser. You should reuse this class as needed.
It is not possible to create a default Generic Schema file that will work with any application. However, you can create a Generic Schema file for practically any combination of classes, attributes, operators and values using the following XML DTD:
<?xml version="1.0"?><!DOCTYPE domain [<!ELEMENT domain (application)><!ATTLIST domainname CDATA #REQUIRED><!ELEMENT application (class+,complexType+,group+)><!ATTLIST applicationname CDATA #REQUIRED><!ELEMENT class EMPTY><!ATTLIST classname CDATA #REQUIREDtype CDATA #REQUIREDgroupable (yes|no) #REQUIRED ><!ELEMENT complexType (extension? , attribute*) ><!ATTLIST complexTypename CDATA #REQUIRED><!ELEMENT extension EMPTY><!ATTLIST extensionbase CDATA #REQUIRED><!ELEMENT attribute (operatorGroup?,restriction?) ><!ATTLIST attributename CDATA #REQUIREDtype CDATA #REQUIREDgroupable (yes|no) #REQUIREDdisplayable (yes|no) #IMPLIEDreturnable (yes|no) #IMPLIED><!ELEMENT operatorGroup EMPTY><!ATTLIST operatorGroupref CDATA #REQUIRED><!ELEMENT restriction (enumeration*,minInclusive?,maxInclusive?) ><!ELEMENT enumeration EMPTY><!ATTLIST enumerationvalue CDATA #REQUIREDalias CDATA #IMPLIED><!ELEMENT minInclusive EMPTY><!ATTLIST minInclusivevalue CDATA #REQUIRED><!ELEMENT maxInclusive EMPTY><!ATTLIST maxInclusivevalue CDATA #REQUIRED><!ELEMENT group (extension? , operator*) ><!ATTLIST groupname CDATA #REQUIRED><!ELEMENT operator EMPTY><!ATTLIST operatorname CDATA #REQUIRED>]>The following example of a Generic Schema XML file conforms to the foregoing DTD:
<domain name="Kilner"><application name="TIS"><class name = "ISDevice" type="DeviceType" groupable="yes"/><class name = "DataCollectorStatus" type="CollectorType" groupable="no" /><complexType name="DeviceType"><attribute name="DisplayName" type="string" groupable="yes" displayable="yes" returnable="yes"><operatorGroup ref="StringOperatorsGroup"/></attribute><attribute name="State" type="numeric" groupable="yes" displayable="no" returnable="yes"><operatorGroup ref="NumericOperatorsGroup"/><restriction><enumeration value="Unknown" alias="0" /><enumeration value="Learning" alias="1" /><enumeration value="Questioned" alias="2" /><enumeration value="Known" alias="3" /><enumeration value="Aware" alias="4" /><enumeration value="Pending" alias="5" /></restriction></attribute><attribute name="DataCollectorStatus" type="DataCollectorStatus" groupable="no" displayable="no" returnable="no"/></complexType><complexType name="CollectorType"><attribute name="ErrorCode" type="numeric" groupable="yes" displayable="no" returnable="yes"><operatorGroup ref="NumericOperatorsGroup"/><restriction><enumeration value="Undetermined" alias="0" /><enumeration value="Collector_Process_Down" alias="1" /><enumeration value="Insufficient_Credentials" alias="2" /><enumeration value="Unreachable_by_Ping" alias="3" /><enumeration value="HTTP_Authentication_Failure" alias="4" /><enumeration value="HTTP_Server_Down" alias="5" /><enumeration value="SNMP_Timeout" alias="6" /><enumeration value="Unsupported" alias="7" /></restriction></attribute></complexType><group name="StringOperatorsGroup"><operator name="equals" /><operator name="contains" /></group><group name="NumericOperatorsGroup"><operator name="!=" /><operator name="=" /><operator name=">" /><operator name="<" /></group></application></domain>Customizing the Rule Evaluator
The Rule Evaluator must implement the interface QueryGeneratorIf in class com.cisco.nm.xms.ogs.asa.
As the Rule Evaluator must query the application's data resource, no generic implementation of the Rule Evaluator exists. You must create a custom Rule Evaluator for your application and the data-storage resource with which your application works.
However, implementations of the Rule Evaluator can be found at:
•
•
SQLQueryGenerator uses the Generic SQL ASA module SQLEvaluatorIf to evaluate SQL queries in the database. The default version of the SQLEvaluatorIf interface is CMFEvaluator in com.cisco.nm.xms.ogs.asa.genericsqlasa. CMFEvaluator uses the CWCS database utility DBService2 to evaluate SQL queries.
You must configure CMFEvaluator for your application by changing the "Database_Name" value in the DBServer.properties file to give the database name (e.g., "RME") followed by "_Implementation_Details.properties".
You need not provide the user name, password, data source URL, or other database properties. They will be picked up from DBServer.properties automatically.
Customizing the Mapping Schema
The Mapping Schema's task of modeling the data source for the Rule Evaluator means that no default Mapping Schema implementation can exist, as the data-storage resource for each application can vary widely.
For example, the elements in the data resource can be:
•
•
•
Accordingly, you must write a Mapping Schema appropriate for the way your application sources and organizes its data. Since the Mapping Schema parser requires an XML file to parse, you must also create a Mapping Schema XML file customized for your application's data structure.
The Generic SQL ASA is a customization of the ASA infrastructure for querying a SQL-compliant RDBMS. It uses a custom Mapping Schema parser (RDBMSSchemaValidator in class com.cisco.nm.xms, ogs.asa.genericsqlasa) which is in turn used by the SQLQueryGenerator Rule Evaluator.
RDBMSSchemaValidator was written to parse a Mapping Schema XML file conforming to the following DTD:
<?xml version="1.0"?><!DOCTYPE Domain [<!ELEMENT Domain (Application)><!ATTLIST DomainName CDATA #REQUIRED><!ELEMENT Application (Mappings)><!ATTLIST ApplicationName CDATA #REQUIRED><!ELEMENT Mappings (ClassMap+,group*)><!ATTLIST ApplicationName CDATA #REQUIRED><!ELEMENT ClassMap (OGSClass,ToTable,HierarchyInfo,PropertyMap+) ><!ELEMENT OGSClass EMPTY><!ATTLIST OGSClassName CDATA #REQUIRED><!ELEMENT ToTable (PrimaryKey) ><!ATTLIST ToTableName CDATA #REQUIRED><!ELEMENT PrimaryKey (Column+)><!ELEMENT Column (ColumnName,JDBC_Type,Operator)><!ELEMENT ColumnName (#PCDATA) ><!ELEMENT JDBC_Type (#PCDATA) ><!ELEMENT Operator (#PCDATA) ><!ELEMENT HierarchyInfo (HierarchyType,ConditionalColumnInfo?) ><!ELEMENT HierarchyType (#PCDATA) ><!ELEMENT ConditionalColumnInfo (ColumnName,JDBC_Type,Operator,ColumnCondition) ><!ELEMENT ColumnCondition (#PCDATA) ><!ELEMENT PropertyMap (OGSAttribute,(AttributeToColumnMapping | AttributeToTableDireCSTMapping | AttributeToTableIndireCSTMapping | AttributeToTableConditionalDireCSTMapping),operatorMapGroup?)><!ELEMENT OGSAttribute EMPTY><!ATTLIST OGSAttributeName CDATA #REQUIRED><!ELEMENT AttributeToColumnMapping (ColumnName,JDBC_Type)><!ELEMENT AttributeToTableDireCSTMapping (MappedTable,PrimaryToMappedAssociation)><!ELEMENT MappedTable EMPTY ><!ATTLIST MappedTableName CDATA #REQUIRED><!ELEMENT PrimaryToMappedAssociation (PrimaryTableColumnNames+,MappedTableColumnNames+)><!ELEMENT PrimaryTableColumnNames (PrimaryTableColumn+)><!ELEMENT PrimaryTableColumn (ColumnName) ><!ELEMENT MappedTableColumnNames (MappedTableColumn+) ><!ELEMENT MappedTableColumn (ColumnName) ><!ELEMENT AttributeToTableConditionalDireCSTMapping (MappedTable,PrimaryToMappedAssociation,MappedConditionalColumnName,MappedConditionalColum nValue,MappedValueColumnName)><!ELEMENT MappedConditionalColumnName (#PCDATA) ><!ELEMENT MappedConditionalColumnValue (#PCDATA) ><!ELEMENT MappedValueColumnName (#PCDATA) ><!ELEMENT AttributeToTableIndireCSTMapping (MappedTable,IndirectTable,IndirectToMappedAssociation,IndirectToPrimaryAssociation) ><!ELEMENT IndirectTable EMPTY ><!ATTLIST IndirectTableName CDATA #REQUIRED><!ELEMENT IndirectToMappedAssociation (IndirectTableColumnNames+,MappedTableColumnNames+) ><!ELEMENT IndirectTableColumnNames (IndirectTableColumn+) ><!ELEMENT IndirectTableColumn (ColumnName) ><!ELEMENT IndirectToPrimaryAssociation (IndirectTableColumnNames+,PrimaryTableColumnNames+) ><!ELEMENT operatorMapGroup EMPTY><!ATTLIST operatorMapGroupref CDATA #REQUIRED><!ELEMENT group (OperatorMap+) ><!ATTLIST groupName CDATA #REQUIRED><!ELEMENT OperatorMap (OGSOperator,ToOperator) ><!ELEMENT OGSOperator EMPTY><!ATTLIST OGSOperatorName CDATA #REQUIRED><!ELEMENT ToOperator (SQLOperator) ><!ELEMENT SQLOperator EMPTY><!ATTLIST SQLOperatorName CDATA #REQUIRED>]>The RDBMSSchemaValidator DTD was written to allow you to map data from any SQL-compliant relational DBMS. It lets you specify exactly how individual OGS classes map to RDBMS tables and how to map OGS attributes, operators and values to table columns.
With it, you can create Mapping Schema XML files that will handle all aspects of the task of mapping OGS classes to RDBMS tables.
The following examples demonstrate how to do this for many of the most typical cases.
Example: One Table Maps to One Concrete Class
In this case, the RDBMS contains a table called "DeviceTable". It has many columns, including "SysName" and "SysLocation". Using the RDBMSSchemaValidator DTD, we can specify that the OGS class "Device" maps directly to "DeviceTable".
Similarly, the OGS class "Device" can have the attributes "SysName" and "SysLocation". These OGS attributes map directly to the corresponding columns in "DeviceTable".
In the Mapping Schema XML file, you can make this type of mapping explicit by supplying the value ONE_TABLE_PER_CONCRETE_CLASS for the element HierarchyType inside the element HierachyInfo.
Note
Example: One Table Maps to a Hierarchy of Classes
In this example, the RDBMS table called "Device Table" covers all device types. Each row in the table can contain data for a different type of device, such as "Router", "Switch", or "PhoneAccessSwitch". Every row has the column "DeviceType", which has a different value depending on the type of device described in that row.
Using the RDBMSSchemaValidator DTD, we can design many OGS classes for this mapping. One of the simplest would be to define a base OGS class called "Device", with many subclasses for "Router", "Switch", etc.
All of these subclasses can also map to "DeviceTable", but with a condition on the "DeviceType" column. In the XML file, the <HierarchyType> for these classes will be ONE_TABLE_PER_HIERARCHY.
Note
Example: Multiple Tables Map to One Abstract Class
In this case, the RDBMS has no single "Device" table. Instead, it has a table for each kind of device: "Router", "Switch", "PhoneAccessSwitch", and so on.
To handle this, we create an abstract base OGS class called "Device" which does not map to any DB table, and concrete subclasses of "Device", like "Router" and "Switch", each of which maps to the corresponding RDBMS table.
The objects in the "Device" class are just a summation of the objects in the concrete subclasses. The set of OGS attributes common to each of the concrete subclasses belongs to the parent "Device" OGS class, so the similarly named columns in the tables for individual devices are integrated into the class hierarchy. In the Mapping Schema XML file, the HierarchyType for these classes is ONE_TABLE_PER_CLASS.
Note
Example: Mapping Class Attributes to Table Columns
We have the OGS class "Device" mapped to the RDBMS table "Device", and the OGS "Device" attribute "SystemLocation" mapped to the column "SystemLocation" in the "Device" table. We could write this in the Mapping Schema XML file as:
<Domain Name="SomeDomainName"><Application Name="OGS"><Mappings><ClassMap><OGSClass Name="Device"/><ToTable Name="Device"><PrimaryKey><Column><ColumnName>DeviceID</ColumnName><JDBC_Type>INTEGER</JDBC_Type><Operator>=</Operator></Column></PrimaryKey></ToTable><HierarchyInfo><HierarchyType>ONE_TABLE_PER_CONCRETE_CLASS</HierarchyType></HierarchyInfo><PropertyMap><OGSAttribute Name="SystemLocation"/><AttributeToColumnMapping><ColumnName>SystemLocation</ColumnName><JDBC_Type>VARCHAR</JDBC_Type></AttributeToColumnMapping><operatorMapGroup ref="StringOperatorMap"/></PropertyMap></ClassMap><group Name="StringOperatorMap"><OperatorMap><OGSOperator Name="equals"/><ToOperator><SQLOperator Name="="/></ToOperator></OperatorMap><OperatorMap><OGSOperator Name="contains"/><ToOperator><SQLOperator Name="LIKE"/></ToOperator></OperatorMap></group></Mappings></Application></Domain>In this example, the column "SystemLocation" is of type "VARCHAR". The mappings for the OGS operators for this OGS attribute type, "equals" and "contains", are defined in the operators group, "StringOperatorMap".
Note
Examples: Mapping Attributes Across Tables Using Foreign Keys
If you want to have an OGS class called "Device" with the attributes "IPAddress" and "IPSubnetMask". But the RDBMS tables have:
•
•
You could design the classes and mapping as follows:
•
•
•
•
•
The Mapping Schema XML file for this design would contain:
<Domain Name="SomeDomainName"><Application Name="OGS"><Mappings><ClassMap><OGSClass Name="Device"/><ToTable Name="Device"><PrimaryKey><Column><ColumnName>DeviceID</ColumnName><JDBC_Type>INTEGER</JDBC_Type><Operator>=</Operator></Column></PrimaryKey></ToTable><HierarchyInfo><HierarchyType>ONE_TABLE_PER_CONCRETE_CLASS</HierarchyType></HierarchyInfo><PropertyMap><OGSAttribute Name="IP"/><AttributeToTableDireCSTMapping><MappedTable Name="IPTable" /><PrimaryToMappedAssociation><PrimaryTableColumnNames><PrimaryTableColumn><ColumnName>DeviceID</ColumnName></PrimaryTableColumn></PrimaryTableColumnNames><MappedTableColumnNames><MappedTableColumn><ColumnName>DevID</ColumnName></MappedTableColumn></MappedTableColumnNames></PrimaryToMappedAssociation></AttributeToTableDireCSTMapping></PropertyMap></ClassMap><ClassMap><OGSClass Name="IP"/><ToTable Name="IPTable"><PrimaryKey><Column><ColumnName>DevID</ColumnName><JDBC_Type>INTEGER</JDBC_Type><Operator>=</Operator></Column><Column><ColumnName>IPAddress</ColumnName><JDBC_Type>VARCHAR</JDBC_Type><Operator>=</Operator></Column></PrimaryKey></ToTable><HierarchyInfo><HierarchyType>ONE_TABLE_PER_CONCRETE_CLASS</HierarchyType></HierarchyInfo><PropertyMap><OGSAttribute Name="IPAddress"/><AttributeToColumnMapping><ColumnName>IPAddress</ColumnName><JDBC_Type>VARCHAR</JDBC_Type></AttributeToColumnMapping><operatorMapGroup ref="StringOperatorMap"/></PropertyMap><PropertyMap><OGSAttribute Name="IPSubnetMask"/><AttributeToColumnMapping><ColumnName>IPSubnetMask</ColumnName><JDBC_Type>VARCHAR</JDBC_Type></AttributeToColumnMapping><operatorMapGroup ref="StringOperatorMap"/></PropertyMap></ClassMap><group Name="StringOperatorMap"><OperatorMap><OGSOperator Name="equals"/><ToOperator><SQLOperator Name="="/></ToOperator></OperatorMap><OperatorMap><OGSOperator Name="contains"/><ToOperator><SQLOperator Name="LIKE"/></ToOperator></OperatorMap></group></Mappings></Application></Domain>
Note
Example: Mapping Attributes Across Multiple Tables
You want to have an OGS class "ICS" to represent a chassis containing multiple devices. "ICS" must have an attribute "IPAddress" for each one of its contained SPE devices, so that we can sort on it.
The RDBMS tables are as follows:
•
•
•
–
–
•
–
–
You can design a solution as follows:
•
•
•
The Mapping Schema XML file for this design is as follows:
<Domain Name="SomeDomainName"><Application Name="OGS"><Mappings><ClassMap><OGSClass Name="Device"/><ToTable Name="Device"><PrimaryKey><Column><ColumnName>DeviceID</ColumnName><JDBC_Type>INTEGER</JDBC_Type><Operator>=</Operator></Column></PrimaryKey></ToTable><HierarchyInfo><HierarchyType>ONE_TABLE_PER_CONCRETE_CLASS</HierarchyType></HierarchyInfo><PropertyMap><OGSAttribute Name="IP"/><AttributeToTableIndireCSTMapping><MappedTable Name="IP" /><IndirectTable Name="Device" /><IndirectToMappedAssociation><IndirectTableColumnNames><IndirectTableColumn><ColumnName>DeviceID</ColumnName></IndirectTableColumn></IndirectTableColumnNames><MappedTableColumnNames><MappedTableColumn><ColumnName>DevID</ColumnName></MappedTableColumn></MappedTableColumnNames></IndirectToMappedAssociation><IndirectToPrimaryAssociation><IndirectTableColumnNames><IndirectTableColumn><ColumnName>ICSID</ColumnName></IndirectTableColumn></IndirectTableColumnNames><PrimaryTableColumnNames><PrimaryTableColumn><ColumnName>ICSID</ColumnName></PrimaryTableColumn></PrimaryTableColumnNames></IndirectToPrimaryAssociation></AttributeToTableIndireCSTMapping></PropertyMap></ClassMap><ClassMap><OGSClass Name="IP"/><ToTable Name="IPTable"><PrimaryKey><Column><ColumnName>DevID</ColumnName><JDBC_Type>INTEGER</JDBC_Type><Operator>=</Operator></Column><Column><ColumnName>IPAddress</ColumnName><JDBC_Type>VARCHAR</JDBC_Type><Operator>=</Operator></Column></PrimaryKey></ToTable><HierarchyInfo><HierarchyType>ONE_TABLE_PER_CONCRETE_CLASS</HierarchyType></HierarchyInfo><PropertyMap><OGSAttribute Name="IPAddress"/><AttributeToColumnMapping><ColumnName>IPAddress</ColumnName><JDBC_Type>VARCHAR</JDBC_Type></AttributeToColumnMapping><operatorMapGroup ref="StringOperatorMap"/></PropertyMap><PropertyMap><OGSAttribute Name="IPSubnetMask"/><AttributeToColumnMapping><ColumnName>IPSubnetMask</ColumnName><JDBC_Type>VARCHAR</JDBC_Type></AttributeToColumnMapping><operatorMapGroup ref="StringOperatorMap"/></PropertyMap></ClassMap><group Name="StringOperatorMap"><OperatorMap><OGSOperator Name="equals"/><ToOperator><SQLOperator Name="="/></ToOperator></OperatorMap><OperatorMap><OGSOperator Name="contains"/><ToOperator><SQLOperator Name="LIKE"/></ToOperator></OperatorMap></group></Mappings></Application></Domain>
Note
Customizing the Rule Convertor and Rule Expressions
The default implementation of the Rule Converter is RuleConverterImpl in com.cisco.nm.xms.ogs.asa. This Rule Converter is re-used by most applications.
The Node Rule Expression is modeled by class NodeRuleExpression in com.cisco.nm.xms.ogs.asa. The class CompositeRuleExpression in com.cisco.nm.xms.ogs.asa models the Composite Rule Expression. Extensions of NodeRuleExpression and CompositeRuleExpression created to hold ASA-specific information must be maintained in product-specific directories.
For examples of custom Rule Expressions, see the following Generic SQL ASA implementations:
•
•
Customizing the ASA Change Alerter
ASA Change Alerters are rarely customized. The interface that defines the ASA Change Alerter functions is ASAChangeAlertIf in the class com.cisco.nm.xms.ogs.asa. The default implementation is ASAChangeAlerterBase, also in com.cisco.nm.xms.ogs.asa.
Running a Customized ASA
After you have created your application ASA, you must implement it, to ensure that the OGS Server will instantiate it at runtime.
The following topics explain the tasks necessary to run your customized ASA:
•
•
Registering the ASA with OGS
To register an ASA with the OGS Server, you must create a registration file for the ASA and specify it in the OGSServer.properties file.
The OGS Server uses the ASA registration file to:
•
•
The ASA registration file's name must appear in the OGSServer.properties file as the value of the ASARegistrationFile parameter. You are free to assign this file any unique name, although it is customary to name it as follows:
ASARegistrationFile=XXXX-mapping.xmlwhere XXX is the application name.
The only real restrictions on the ASA registration file are that its filename must end in the extension "xml" and that it must conform to the following DTD:
<?xml version="1.0"?><!DOCTYPE ASA_Mappings [<!ELEMENT ASA_Mappings (Mapping+) ><!ELEMENT Mapping (OGSSchemaFile+,Location+,ClassName+,Specialization+)><!ELEMENT OGSSchemaFile EMPTY><!ATTLIST OGSSchemaFilename CDATA #REQUIRED ><!ELEMENT Location EMPTY><!ATTLIST Locationtype (Remote|Local) #REQUIRED ><!ELEMENT ClassName EMPTY><!ATTLIST ClassNamename CDATA #REQUIRED ><!ELEMENT Specialization EMPTY><!ATTLIST Specializationname CDATA #REQUIRED >]>Example
You have created an ASA for one of the applications in Kilner, called "VMSA". You have created an ASA Registration File, called vmsa-mapping.xml, for the VMSA ASA. It has the following content:
<?xml version="1.0"?><!DOCTYPE ASA_Mappings [<!ELEMENT ASA_Mappings (Mapping+) ><!ELEMENT Mapping (OGSSchemaFile+,Location+,ClassName+,Specialization+)><!ELEMENT OGSSchemaFile EMPTY><!ATTLIST OGSSchemaFilename CDATA #REQUIRED ><!ELEMENT Location EMPTY><!ATTLIST Locationtype (Remote|Local) #REQUIRED ><!ELEMENT ClassName EMPTY><!ATTLIST ClassNamename CDATA #REQUIRED ><!ELEMENT Specialization EMPTY><!ATTLIST Specializationname CDATA #REQUIRED >]><ASA_Mappings><Mapping><OGSSchemaFile name="vms-ogs-schema.xml"/><Location type="Local"/><ClassName name="com.cisco.nm.xms.ogs.asa.ASABaseImpl"/><Specialization name="VMSA"/></Mapping></ASA_Mappings>When creating an ASA Registration file, note that:
•
•
•
Creating the ASA Configuration File
The ASA configuration file tells a newly instantiated ASA which infrastructure modules to use when validating and evaluating rules. It acts, essentially, as a list of all the customizations performed on the generic ASA implementation modules.
The ASA configuration filename must always:
•
•
Example
You have created an ASA for one of the applications in Kilner, called "VMSA". The ASA configuration file for this application will be named "VMSA_Implementation_Details.properties".
The ASA configuration file content must list:
•
•
•
The ASA Configuration File lists this information using the parameters shown in Table 28-4. The Configuration File is a simple ASCII text file containing name=value pairs. The order in which the parameters appear in the file is not important.
However, you must:
•
•
The VMSA ASA Configuration File might look like this:
Rule_Validator = com.cisco.nm.xms.ogs.asa.GenericValidatorImplSchema_Validator_Class = com.cisco.nm.xms.ogs.server.parser.OGSSchemaParserGeneric_Schema_File = /vms-ogs-schema.xmlRule_Evaluator = com.cisco.nm.xms.ogs.kilner10.vmsa.VMSAQueryGeneratorClass_Mapping_Parser = com.cisco.nm.xms.ogs.kilner10.vmsa.VMSAValidatorMapping_File = /vms-mapping-schema.xmlRule_Converter = com.cisco.nm.xms.ogs.asa.RuleConverterImplNode_Expression_Class = com.cisco.nm.xms.ogs.kilner10.vmsa.VMSANodeRuleExpressionComposite_Expression_Class = com.cisco.nm.xms.ogs.kilner10.vmsa.VMSACompositeRuleExpressionAsa_Change_Alerter = com.cisco.nm.xms.ogs.kilner10.vmsa.VmsaChangeAlerterExample: Using the Generic SQL ASA
The Generic SQL ASA is a customization of the ASA infrastructure for querying a relational database using OGS. It uses the generic or customized components shown in Table 28-5.
.
Creating an OGS GUI
The UII (User Interface Initiative) Object Selector provides a convenient and versatile tree-display component that gives users GUI access to OGS group data. When implemented, it provides users with:
•
•
Object Selector is part of the UII release package available at the User Experience web site, which is available to Cisco employees at http://picasso (be sure to use version 6.1 or later of the UII release package).
Object Selector comes in standard "Content Area" and space-conserving "Sliding" versions, and has a complete set of API functions. If you plan on using Object Selector in your application, please remember:
•
•
•
–
–
•
To use the Object Selector in your application:
Step 1
Step 2
•
•
•
Step 3
<action path="/objselcaching" type="com.cisco.nm.xms.ogs.client.uii.ObjectSelectorCachingAction"/><action path="/objselsliding" type="com.cisco.nm.xms.ogs.client.uii.ObjectSelectorSlidingPanelAction"/>Step 4
Step 5
If you are not using Dreamweaver, insert directly into the corresponding JSP file the code appropriate for the type of Object Selector you want to create:
•
<%@ taglib uri="/WEB-INF/tlds/ogs-objectselector-taglib.tld" prefix="ogs" %><ogs:slidingSelectorosName="YOUR_OBJECT_SELECTOR_NAME"selectionMode="multiple"preserveSelection="false"isGroupSelector="false"mixSelection="false"showFilter="true"showQuickFilter="true"showSaveBtn="true"treeGenerator="com.cisco.nm.xms.ogs.test.TestTreeGenerator"/>
•
<%@ taglib uri="/WEB-INF/tlds/ogs-objectselector-taglib.tld" prefix="ogs" %><ogs:contentAreaSelectorosName="YOUR_OBJECT_SELECTOR_NAME"selectionMode="multiple"preserveSelection="false"isGroupSelector="false"mixSelection="false"width="200"height="300"treeGenerator="com.cisco.nm.xms.ogs.test.TestTreeGenerator"/>
•
Step 6
Step 7
Step 8
a.
b.
If you do not do this, the Object Selector will call the default tree generator class, ObjectSelectorTreeGenerator in com.cisco.nm.xms.ogs.client.ostaglib.util. This class also extends from BasicObjectSelectorTreeGenerator and is provided by the application.
For reference information on the Tree Generator, see the UII SDK.
c.
getTreeEntries REQUIREDgetUserFilterEntries OPTIONAL (For sliding object selector only).getAppletParameterImages OPTIONALgetAppletParameterImageFile OPTIONALgetAppletParameterToolTipFile OPTIONALgetAppletParameterToolTipLineContinue OPTIONALgetAppletParameterToolTipWidth OPTIONALgetAppletParameterBkgColor OPTIONALgetAppletParameterBkgColorSelect OPTIONALgetAppletParameterBkgColorHover OPTIONALgetAppletParameterTabOpenColor OPTIONALgetAppletParameterTabCloseColor OPTIONALgetAppletParameterFontName OPTIONALgetAppletParameterfont size OPTIONALgetAppletParameterPadding OPTIONALgetAppletParameterOnSelect OPTIONALgetAppletParameterOnUnSelect OPTIONALgetAppletParameterOnCachingExpand OPTIONALgetAppletParameterSelectAllChild OPTIONALgetAppletParameterUnSelectAllChild OPTIONALgetAppletParameterSelectAncestors OPTIONALgetAppletParameterUnSelectAncestors OPTIONALgetAppletParameterTabs OPTIONALgetAppletParameterCheckWhenLabelClick OPTIONALgetAppletParameterOnHighLight OPTIONALgetAppletParameterDisable OPTIONALgetAppletParameterSort OPTIONALgetAppletParameterXml OPTIONALgetAppletParameterXmlSource OPTIONALgetAppletParameterDeDuplicate OPTIONALgetAppletParameterNumberOfSelectedLeaves OPTIONAL
For more information about these methods, see the UII SDK.
Using OGS Secure Views
Starting with CWCS 3.0, OGS supports Secure Views. OGS Secure Views allow your application to control user access to individual members of a group, instead of just to groups as a whole.
Using the user ID, application ID, and task ID (and optionally, the session ID) of the requesting client, and an interface to the CAM-maintained ACS Server security system, Secure Views can return a subset of the total membership of a group. This subset will contain only those devices to which the user has access.
OGS Secure Views are explained in the following topics:
•
How Secure Views Work
OGS Secure Views filter the memberships of a group based on the IDs of:
•
•
•
The basic process flow proceeds as follows:
1.
2.
3.
a.
b.
c.
OGS Secure Views accomplishes this using the following classes and methods new in CWCS 3.0:
•
The default implementation is OGSFilterImpl in the same package. OGSFilterImpl looks up the value of the "DeviceClasses" property in OGSClient.properties, uses it to identify all of the device classes that need to be filtered, and checks in the CAM-returned list for objects of those classes.
Only when the class of object in the CAM list matches the "DeviceClasses" value will the object be filtered. Applications using SQLASA need to use the OGSSQLFilterImpl implementation.
•
•
For details, see the "Using Secure Views With the OGS Administrative GUI" section).
•
For details, see the "Using OGS SecurityContext" section
The design of OGS Secure Views imposes several requirements on applications using it:
•
It therefore requires that your application operate in ACS (TACACS+) mode, not in CMF security mode. If your application operates in CMF mode, the default implementation of Secure Views will not perform any filtering at all. In this case, evaluating a group or rule will result in all members of that group being returned.
•
For example: An OGSClient.properties entry of DeviceClasses="CMF:DCR:Device" specifies that objects of the class "CMF:DCR:Device", and only this class, represent devices. Similarly, the entry DeviceClasses="CMF:DCR:Device","CMF:DCR:Interface" specifies that both these classes represent devices.
If you do not do this, your Secure Views implementation will pass all device objects through to the client, regardless of the user's authorizations (just as it does with non-device objects).
•
For more information about DCR, see Chapter 14, "Using the Device Credentials Repository"). The simplest way to do this is to ensure that:
–
–
–
For example: If you are using the class CMF:DCR:Device to represent devices, and one of these devices has the DCR ID 123456, your ASA must return the Object ID for this device as CMF:DCR:Device$123456.
If you do not do this, your Secure Views implementation will be unable to match any of entries in the CAM-returned list of authorized objects (which is a list of DCR IDs) against the OGSObjectList, and will not return any of them to the client (even though the user may be authorized to see them).
Note that you can work around the requirement of an ASA that preserves DCR IDs, as long as you can supply these IDs in another way (see the "Using Secure Views Without DCR IDs" section).
•
This restriction is imposed by the current implementation of CAM, which by default expects all of its clients to be servlets executing in the same servlet engine. CAM can be packaged with the process using OGSServerProxy.
•
Implementing Secure Views
Secure Views is intended for use in applications where:
•
•
•
As long as your implementation observes the requirements explained in the "How Secure Views Work" section, using Secure Views is relatively simple, as explained in the following topics:
•
•
•
The requirement for ACS mode is an absolute requirement. If your application cannot observe the requirements for device-only filtering and use of DCR IDs for devices, see the "Customizing Your Secure Views Implementation" section
Installing Secure Views
To implement Secure Views, OGS 1.1 must be packaged with your application. You will need to extract the file ogs1.1.war from the OGS SDK, and to include the following packages in your build:
•
•
•
Using OGS SecurityContext
The OGS interface specifies filtering of a group's membership based on the user/application/task context in which a request is made. Additionally, class OGSSecurityContext defines a constructor that accepts the user ID, application ID, and task ID (and, optionally, the session ID) that CAM requires to identify the devices for which the user has access.
If your application requires Secure Views, be sure that you are passing the proper information to this constructor before you make the request for group evaluation. If you do not do this, CAM will not have a chance to return the list of authorized devices before group evaluation is conducted.
The normal process for creating and using instances of OGSSecurityContext is:
Step 1
Step 2
Step 3
Step 4
Using Secure Views With DCR IDs
If you are using standard Object IDs that include the standard DCR ID for all group members that are devices, the reference OGSFilterImpl class and its DoFiltering method perform all of the following tasks automatically:
DoFiltering(){Check if CiscoWorks is in ACS Mode;If CiscoWorks is not in ACS Mode, return OGSObjectList without filtering;If CiscoWorks is in ACS Mode;Get Admin Groups from CAM.Get Admin Device Groups that User is authorized to use for the given TaskID andApplicationIDGet the DCR ID of the devices in these Admin Device Groups;Avoid Filtering all non-device objects, using the property "DeviceClasses" inOGSClient.propertiesGet the Device Objects in the OGSObjectList passed to the function as a parameter;Get the Value portion of the Device Object. This is assumed to be the DCR ID;Intersect the list and return an OGSObjectList containing all non-device objectsand only filtered device objectsUsing Secure Views with Object Selector
As explained in the "Creating an OGS GUI" section, integrating OGS with an Object Selector GUI is fairly simple. If your OGS implementation also includes Secure Views, however, you have a few extra tasks to perform:
•
•
As a reference, the default Tree Generator uses method getOGSUserContext to perform all the steps mentioned in the "Using OGS SecurityContext" section. This includes:
–
–
–
To adapt your application Object Selector for use with Secure Views:
Step 1
Step 2
Step 3
For example: Let us assume that your:
•
•
•
Using these names, you would modify your Object Selector Action Class as follows:
public ActionForward perform (ActionMapping mapping)ActionForm formHttpServletRequest requestHttpServletResponse response)throws IOException ServletException{String YOUR-OBJECT-SELECTOR-NAME="FH.OGScontent"String YOUR-APPLICATION-ID="iptm"String YOUR-TASK-ID="write-priv"HttpSession session=request.getSession();session.setAttribute("AppID"+YOUR-OBJECT-SELECTOR-NAME, YOUR-APPLICATION-ID);OGSObjectSelectorAdapter osAdapter=newOGSObjectSelectorAdapter(request,"FH.OGScontent");osAdapter.setObjectTaskIdList("write_priv");...Using Secure Views With the OGS Administrative GUI
As long as you have observed the limits described in the "How Secure Views Work" section, your Secure Views implementation class will filter all device requests from all clients by default.
This can be a problem if your application uses the OGS Administrative GUI to allow users with sufficient authority to define groups. The OGS Client performing the filtering must be able to distinguish between normal client requests and those from an Administrative GUI, so that the Administrative GUI user has access to all devices when defining groups and their rules.
To distinguish them, make sure that the OGS Administrative GUI you have implemented in your application identifies itself to CAM with an Application ID of "OGS" and a TaskID of "OGSOPERATION" when issuing requests (these two IDs are case-sensitive and must be entered exactly as shown here).
These two values, when passed with OGSSecurityContext, turn off filtering functions in Secure Views implementations automatically.
If your application is used in a CiscoWorks suite, you may want to consider whether you want to implement the OGS Administrative GUI in your application at all.
CWCS 3.0 supplies the OGS Administrative GUI at the CiscoWorks level, with filtering turned off by default (that is, the CiscoWorks implementation of the OGS Administrative GUI already identifies itself with the Application ID "OGS" and the Task ID "OGSOPERATION").
If you must implement a separate OGS Administrative GUI for your application, you will probably want to keep filtering turned on.
Customizing Your Secure Views Implementation
It is possible to adapt Secure Views to some special requirements, including:
•
•
Specifying a Non-Default Implementation
In the default OGS packaging, the OGSClientProperties parameter SecurityFilterImpl= is explicitly set to OGSFilterImpl. This is the default or reference implementation of OGSFilterIf in com.cisco.nm.xms.ogs.client.
If you must handle special filtering requirements, you must either override the OGSFilterImpl implementation's DoFilter () function or create a new class which implements OGSFilterIf (you are likely to do the latter if you are using Secure Views without DCR IDs, as explained in the "Using Secure Views Without DCR IDs" section.)
If you have created a new implementation of OGSFilterIf, you must set SecurityFilterImpl to the name of your new class. For example: SecurityFilterImpl=MyOGSFilterImpl.
Using Secure Views Without DCR IDs
If your application does not use the DCR ID as the value of the Object ID for devices, you will need to create a new implementation of OGSFilterIf or extension of OGSFilterImpl that maps between whatever you are using in the Value portion of a Device Object and the actual DCR IDs.
Example
If you are using a Device Name for the Value portions of the Object ID for devices, you will need to create a new class with a DoFiltering() method that implements OGSFilterIf. You can do this mapping in any way that is convenient to you, but it must be performed before OGSServerProxy attempts to compare the CAM and OGS object lists:
DoFiltering()
{
Check if CiscoWorks is in ACS Mode;
If CiscoWorks is not in ACS Mode, return OGSObjectList without filtering;
If CiscoWorks is in ACS Mode;
Get Admin Device Groups from CAM.
Get Admin Device Groups that User is authorized to use for the given TaskID and
ApplicationID
Get the DCR ID of the devices in these Admin Device Groups;
Avoid filtering all non-device objects in the OGSObjectList returned by OGS Server
Get the Device Objects in the OGSObjectList passed to the function as a parameter;
Get the Value portion of the Device Object. This will be something other than DCRID;
Map the OGS Value to DCRID and return the ObjectList with DCR IDs in Value position
Intersect the list and return an OGSObjectList containing all non-device objects
and only filtered device objects
Using OGS Common and Shared Groups
OGS Common Groups are groups created based on DCR attributes. They are propagated to other OGS Servers running on the same server and to peer servers in the same DCR cluster.
For example, the CWCS Common Groups will be propagated to the RME OGS Server, if RME is installed, so users of RME OGS Server will also be able the view these Common Groups.
OGS Shared Groups are application groups propagated to CWCS and other applications on the same server and to peer servers in the same DCR cluster.
For example, all Campus Manager groups are propagated to the RME OGS Server on the same server.
Common Groups have enumerated rules. Their membership is cached in a way similar to caching of a local group. Shared Groups are remote links to the respective OGSServer and are evaluated at runtime. Membership is not cached locally for Shared Groups, so group-membership change events are not sent for them.
A Provider Group refers to the root group name under each hierarchy.
For example, the Provider Group for a Common Services group hierarchy is CS@hostname, and for the RME hierarchy, it is RME@hostname. The hostname is appended to make the Provider Group unique, as Shared Groups are propagated across servers .
By default, the Provider Group name is of the format application@hostname. If the hostname changes, or the admin user configures the CWHP server name as the Provider Group suffix, the Provider Group name will be changed after a daemon restart.
For examples and User Interface of Common Groups and Shared Groups, see Chapter 5, Administering Groups, in User Guide for CiscoWorks Common Services.
Using Common and Shared Groups requires you to perform the tasks covered in the following topics:
•
•
•
Configuring OGSServer.properties
To enable Common and Shared Groups, applications should configure the following in OGSServer.properties:
# Application OGS instances that do not wish to participate# in group sharing should remove the following property.SharedGroupImplClass = com.cisco.nm.xms.ogs.sharedgroups.SharedGroupManagerConfiguring SharedGroups.properties
The following shows a generic SharedGroups.properties file, with explanation of the fields and how to set them.
# Uncomment this line and specify a different value if your OGS# publishes its own URN#LocalOgsURN = ogs_server_urn^M## Application OGS instances should uncomment the following line#LocalSgURN = remote_ogs_urn## Uncomment the following line and modify to match the URL of the CTMServlet# deployed by your application#LocalURL = :443/<application webapp>/CTMServlet#SrcDeviceClass = :CMF:DCR:Device## Application OGS instances should specify their device class here#DestDeviceClass = <Application Device class>## The following should match the value of the property ProductId# of CMF-OGS#RemoteOgsProductId = CS## Uncomment the following property and specify the desired# depth of the MDF hierarchy if you wish to limit the depth# of the MDF hierarchy in common groups##MDFHierarchyDepth = -1ClientRegistryFile = clients.reg#Application can uncomment the following to override the default rule for provider group from CS hierarchy#UseContainerForCommonGroups=trueImplementing the SharedGroupObjectMapperIf Interface
To map application-specific object IDs to a common representation, applications should implement SharedGroupObjectMapperIf.
If your application uses the DCR device ID as the application object ID for OGS objects, you need only configure the SrcDeviceClass and DestDeviceClass in the SharedGroups.properties file. The default implementation (com.cisco.nm.xms.ogs.sharedgroups.DefaultObjectMapper) will handle the object mapping.
If you do not use DCR device IDs as application object IDs, you must implement SharedGroupObjectMapperIf and provide the implementation in the SharedGroups.properties, as follows:
#Object ID mapper classObjectIdMapClass = Customized object mapper classThe customized object mapper class should be in the classpath for the OGSServer.
OGS Utility Class for Common and Shared Groups
The class com.cisco.nm.ogs.util.OGSUtil provides two APIs to get the common and local provider group name.
public static String getCommonRoot(); //for getting the CS root grouppublic static String getLocalRoot(); //for getting the local root group
Using OGS 1.3 Client Side Enhancements
Applications using OGS 1.3 have enhanced control over the display of GUI components. These client-side enhancements, which are not available with OGS 1.2, enable applications to determine:
•
•
Changes needed to support these client-side enhancements are available in the com.cisco.nm.xms.ogs.client package of the OGS module.
The following topics explain how to use these enhancements:
•
•
•
About the Enhanced OGS 1.3 Classes and Data Structures
Table 28-6 shows the OGS 1.3 classes enhanced to allow for GUI controls. Figure 28-4 shows how these classes interact with each other and with the GUI components.
.
Figure 28-4
OGS 1.3 Class and GUI Component Interactions
The following JSP files were also modified to check for the availability of the GUI components in the disabled Array List:
•
•
•
•
•
Based on the presence of the components in the disabled Array List, the display of the view components can be controlled.
Controlling the Display of Wizard Steps
You need to create new screen IDs for controlling the display of wizard steps while in Create or Edit mode. The new screen IDs need to be defined in the site-map XML files of the respective web application. The screen IDs are:
•
•
•
•
•
•
Configure the screen IDs to skip the Membership page during the Create and Edit wizard tasks of the group entries. However, support is not provided for skipping Rules, Properties and Summary pages, as these are required for group handling.
Note
Integrating OGS 1.3 With Your Application
To integrate OGS 1.3's enhanced client-side features with your application:
Step 1
Although all the changes were made in the ogs-client1.3.jar, we suggest that you refresh all jar files, to ensure that you have uniform versions throughout.
Step 2
For a complete set of entries related to UI components, which you can configure, see Example 28-2. This file can be placed under the WEB-INF/classes directory of the respective web application, under Tomcat.
Step 3
For an example system-groups.xml file, see Example 28-3. The file is currently available under the WEB-INF/classes directory of the respective web-app under Tomcat servlet.
Step 4
If the XML file has entries like these for representing Cisco Access Servers:
<GROUP><NAME>/System Defined Groups/Cisco Access Servers</NAME><DESCRIPTION>Group for Cisco Access Servers</DESCRIPTION><TYPE value="DYNAMIC" /><OGS_RULE_CONTAINER><OGSRULE> </OGSRULE></OGS_RULE_CONTAINER><TAGSTABLE ref="devicegrouptags" /><READ_PERMISSION_LIST ref="read_user_list" /><WRITE_PERMISSION_LIST ref="write_user_list" /><EVALUATE_PERMISSION_LIST ref="evaluate_user_list" /></GROUP><PROPERTYTABLE name="devicegrouptags"><PROPERTY><KEY>MEMBERSHIP_TYPE</KEY><VALUE>DEVICE</VALUE></PROPERTY></PROPERTYTABLE>Then the OGSClientUIDisplay.properties file can have entries like:
DEVICE.privateVisibility=disabledThe string "DEVICE" in the properties file needs to match the string defined in the XML file. However applications can use any convenient string that is relevant in their application space.
Step 5
The entries in struts-config.xml are:
forward name="ogsSkipMemberCreateProperties" path="/WEB-INF/screens/uii/index.jsp?sid=ogsSkipMemberCreateProperties" /><forward name="ogsSkipMemberCreateRules" path="/WEB-INF/screens/uii/index.jsp?sid=ogsSkipMemberCreateRules" /><forward name="ogsSkipMemberCreateSummary" path="/WEB-INF/screens/uii/index.jsp?sid=ogsSkipMemberCreateSummary" /><forward name="ogsSkipMemberEditProperties" path="/WEB-INF/screens/uii/index.jsp?sid=ogsSkipMemberEditProperties" /><forward name="ogsSkipMemberEditRules" path="/WEB-INF/screens/uii/index.jsp?sid=ogsSkipMemberEditRules" /><forward name="ogsSkipMemberEditSummary" path="/WEB-INF/screens/uii/index.jsp?sid=ogsSkipMemberEditSummary" />The entries in site-map.xml are:
<appWizard><appWizardItem><label>Properties</label><appContentArea screenID="ogsSkipMemberCreateProperties"contentAreaTitle="Properties"helpTag="group_administration "fileRef="/WEB-INF/screens/OGS/ogsCreateProperties.jsp" /></appWizardItem><appWizardItem><label>Rules</label><appContentArea screenID="ogsSkipMemberCreateRules"contentAreaTitle="Rules"helpTag="group_administration "fileRef="/WEB-INF/screens/OGS/ogsCreateRules.jsp" /></appWizardItem><appWizardItem><label>Summary</label><appContentArea screenID="ogsSkipMemberCreateSummary"contentAreaTitle="Summary"helpTag="group_administration "fileRef="/WEB-INF/screens/OGS/ogsCreateSummary.jsp" /></appWizardItem></appWizard><appWizard><appWizardItem><label>Properties</label><appContentArea screenID="ogsSkipMemberEditProperties"contentAreaTitle="Properties"helpTag="group_administration "fileRef="/WEB-INF/screens/OGS/ogsEditProperties.jsp" /></appWizardItem><appWizardItem><label>Rules</label><appContentArea screenID="ogsSkipMemberEditRules"contentAreaTitle="Rules"helpTag="group_administration "fileRef="/WEB-INF/screens/OGS/ogsEditRules.jsp" /></appWizardItem><appWizardItem><label>Summary</label><appContentArea screenID="ogsSkipMemberEditSummary"contentAreaTitle="Summary"helpTag="group_administration "fileRef="/WEB-INF/screens/OGS/ogsEditSummary.jsp" /></appWizardItem></appWizard>Example 28-2 OGSClientUIDisplay.properties
# Properties file for the OGS Client UI display# This file is mainly used to control the display of UI components based on group types# and is valid only for OGS Admin GUI.# It is assumed that all the OGS GUI components are enabled by default.# The respective components along with the group types for which they need to be disabled# can be mentioned here.# ----------------------------------# Copyright (c) 2004 Cisco Systems, Inc.# All rights reserved## THIS SOFTWARE IS THE PROPERTY OF CISCO SYSTEMS INC.# 2004# THE RECIPIENT BY ACCEPTING THIS MATERIAL AGREES THAT THE# MATERIAL WILL NOT BE USED, COPIED OR REPRODUCED IN WHOLE OR# IN PART NOR ITS CONTENTS REVEALED IN ANY MANNER WITHOUT THE# EXPRESS WRITTEN PERMISSION OF CISCO SYSTEMS, INC.# ----------------------------------## The names which refer to the various components are mentioned below.# creategroupSelect -> Group Select button in Properties:Create page# createparentChange -> Change Parent button in Properties:Create page# DynamicEvaluation -> Radio button for Automatic# StaticEvaluation -> Radio button for Based Upon User Request# publicVisibility ->Visibility scope radio button "Available to all users"# privateVisibility -> Visibility scope radio button "Available to created user only"# createORoperator -> OR operator in the Rules:Create page# createANDoperator -> AND operator in the Rules:Create page# createEXCLUDEoperator -> EXCLUDE operator in the Rules:Create page# createMembershipWizard ->Disabling the Membership page step in the Creation Wizard# editORoperator -> OR operator in the Rules:Edit page# editANDoperator -> AND operator in the Rules:Edit page# editEXCLUDEoperator -> EXCLUDE operator in the Rules:Edit page# editMembershipWizard ->Refers to the Membership page step in the Edition Wizard# browseViewParentRule -> View Parent Rule button related to Properties:Details page# browseMembershipDetails - > Membership Details button related to Properties:Details page# EditGroupName -> Text field related to the Group Name in the Edit:Properties page# The KEY value contains a string separated by "."# The first token of the key should match the value given for the MEMBERSHIP_TYPE in the# PROPERTY_TABLE pertaining to XML file containing the group definition.# Sample examples are given below:##DEVICE.createGroupSelect=disabled#DEVICE.createParentChange=disabledDEVICE.DynamicEvaluation=disabled#DEVICE.StaticEvaluation=disabledDEVICE.privateVisibility=disabledDEVICE.publicVisibility=disabledDEVICE.createAddRuleExpression=disabledDEVICE.createSyntaxCheck=disabledDEVICE.createViewParentRule=disabledDEVICE.createORoperator=disabledDEVICE.createANDoperator=disabledDEVICE.createEXCLUDEoperator=disabledDEVICE.editORoperator=disabledDEVICE.editANDoperator=disabledDEVICE.editEXCLUDEoperator=disabledDEVICE.editAddRuleExpression=disabledDEVICE.editSyntaxCheck=disabledDEVICE.editViewParentRule=disabledDEVICE.createMembershipWizard=disabledDEVICE.editMembershipWizard=disabledINTERFACE.createGroupSelect=disabledINTERFACE.createParentChange=disabledExample 28-3 System-Groups.xml
<?xml version="1.0"?><!DOCTYPE SYSTEMGROUPS [<!ELEMENT SYSTEMGROUPS (GROUP+,PROPERTYTABLE+,USERLIST+) ><!ELEMENT GROUP (NAME,DESCRIPTION?,TYPE,OGS_RULE_CONTAINER,TAGSTABLE?,READ_PERMISSION_LIST,WRITE_PERMISSIO N_LIST,EVALUATE_PERMISSION_LIST)><!ELEMENT NAME (#PCDATA)><!ELEMENT DESCRIPTION (#PCDATA)><!ELEMENT TYPE EMPTY><!ATTLIST TYPE value (DYNAMIC|STATIC) #REQUIRED ><!ELEMENT OGS_RULE_CONTAINER (OGSRULE?)><!ELEMENT OGSRULE (#PCDATA) ><!ELEMENT TAGSTABLE EMPTY><!ATTLIST TAGSTABLE ref CDATA #REQUIRED ><!ELEMENT READ_PERMISSION_LIST EMPTY><!ATTLIST READ_PERMISSION_LIST ref CDATA #REQUIRED ><!ELEMENT WRITE_PERMISSION_LIST EMPTY><!ATTLIST WRITE_PERMISSION_LIST ref CDATA #REQUIRED ><!ELEMENT EVALUATE_PERMISSION_LIST EMPTY><!ATTLIST EVALUATE_PERMISSION_LIST ref CDATA #REQUIRED ><!ELEMENT PROPERTYTABLE (PROPERTY+)><!ATTLIST PROPERTYTABLEname CDATA #REQUIRED ><!ELEMENT PROPERTY (KEY,VALUE)><!ELEMENT KEY (#PCDATA)><!ELEMENT VALUE (#PCDATA)><!ELEMENT USERLIST (USER*)><!ATTLIST USERLISTname CDATA #REQUIRED ><!ELEMENT USER (#PCDATA)>]><SYSTEMGROUPS><GROUP><NAME>/System Defined Groups/Unknown Devices</NAME><DESCRIPTION>Group for devices whose MDFId is unknown</DESCRIPTION><TYPE value="DYNAMIC" /><OGS_RULE_CONTAINER><OGSRULE>:CMF:DCR:Device.MDFId equals "UNKNOWN" </OGSRULE></OGS_RULE_CONTAINER><TAGSTABLE ref="devicegrouptags" /><READ_PERMISSION_LIST ref="read_user_list" /><WRITE_PERMISSION_LIST ref="write_user_list" /><EVALUATE_PERMISSION_LIST ref="evaluate_user_list" /></GROUP><GROUP><NAME>/System Defined Groups/Cisco Access Servers</NAME><DESCRIPTION>Group for Cisco Access Servers</DESCRIPTION><TYPE value="DYNAMIC" /><OGS_RULE_CONTAINER><OGSRULE> </OGSRULE></OGS_RULE_CONTAINER><TAGSTABLE ref="devicegrouptags" /><READ_PERMISSION_LIST ref="read_user_list" /><WRITE_PERMISSION_LIST ref="write_user_list" /><EVALUATE_PERMISSION_LIST ref="evaluate_user_list" /></GROUP><GROUP><NAME>/System Defined Groups/Cisco Cable Devices</NAME><DESCRIPTION>Group for Cisco Cable Devices</DESCRIPTION><TYPE value="DYNAMIC" /><OGS_RULE_CONTAINER><OGSRULE> </OGSRULE></OGS_RULE_CONTAINER><TAGSTABLE ref="interfacegrouptags" /><READ_PERMISSION_LIST ref="read_user_list" /><WRITE_PERMISSION_LIST ref="write_user_list" /><EVALUATE_PERMISSION_LIST ref="evaluate_user_list" /></GROUP><GROUP><NAME>/System Defined Groups/Cisco Cable Devices/Cisco 6900 Series Multiplexers</NAME><DESCRIPTION>Group for Cisco 6900 Series Multiplexers</DESCRIPTION><TYPE value="DYNAMIC" /><OGS_RULE_CONTAINER><OGSRULE> </OGSRULE></OGS_RULE_CONTAINER><TAGSTABLE ref="interfacegrouptags" /><READ_PERMISSION_LIST ref="read_user_list" /><WRITE_PERMISSION_LIST ref="write_user_list" /><EVALUATE_PERMISSION_LIST ref="evaluate_user_list" /></GROUP><PROPERTYTABLE name="systemdefinedgrouptags"><PROPERTY><KEY>SYSTEM_PREDEFINED</KEY><VALUE>TRUE</VALUE></PROPERTY></PROPERTYTABLE><PROPERTYTABLE name="customizablegrouptags"><PROPERTY><KEY>CUSTOMIZABLE_GROUP</KEY><VALUE>TRUE</VALUE></PROPERTY></PROPERTYTABLE><PROPERTYTABLE name="hiddengrouptags"><PROPERTY><KEY>HIDDEN</KEY><VALUE>TRUE</VALUE></PROPERTY></PROPERTYTABLE><PROPERTYTABLE name="devicegrouptags"><PROPERTY><KEY>MEMBERSHIP_TYPE</KEY><VALUE>DEVICE</VALUE></PROPERTY></PROPERTYTABLE><PROPERTYTABLE name="interfacegrouptags"><PROPERTY><KEY>MEMBERSHIP_TYPE</KEY><VALUE>INTERFACE</VALUE></PROPERTY></PROPERTYTABLE>
Using OGS 1.4 Enhancements
The following enhancements are part of OGS 1.4 release:
Template Based Groups
Template based groups simplify group creation. You can create frequently used groups easily. If you want to create a group based on a device attribute (such as Location) you must select the Location based groups template, and enter the location values for the rule.
However, for group creation with more than one attribute (such as Location and IP Address) you must use the regular Rule based group creation.
Group ID
Group ID is introduced to the OGSGroupDefinition (com.cisco.nm.xms.ogs.util) class. Group ID is unique for a particular group. However, when a group is deleted, and then recreated, the group will not have the same group ID. A Getter method (groupId()) is added to the OGSGroupDefinition class for the applications to use the group ID.
Only the evaluateGroup method in the OGSInterface is overloaded to use the group ID, instead of the group name. The others such as deleteGroup and copyGroup continue to use group name.
The evaluateGroup() API is used from the application backend, and require the group ID.
A new class - com.cisco.nm.xms.ogs.util.OGSGroupId is added.This will encapsulate the group ID of a particular group as a string.
Configurable Display Name for Class Names
In group administration UIs, the internal class names (:CMF:DCR:Device or Kilner:VASA:KilnerObject:Device:Host) are displayed. This is not very useful for the end users.
With configurable display name for class names, you can have more user-friendly UI display names (such as Device or Host).
OGSClient.properties contains the mapping definitions. Applications can enable this feature using a specified property (EnableClassNameMapping=true in OGSClient.properties), and provide the mapping from the internal class name to the external class name.
Configurable Root (Provider) Group
In a single-server setup (DCR in standalone mode), the root group name is of the format Application. In a multi-server setup (DCR in Master / Slave mode), the root group name is of the format Application-CWHP Display Name.
Both the formats are available as templates in a configuration file, NMSROOT/objects/groups/RootGroupTemplate.properties. The default content of the file is:
# This property file is for configuring the template to be used for # root (provider) group of all group hierarchies in this server ProviderTemplateForSingleServer = $ProductId$ ProviderTemplateForMultiServer = "$ProductId$-$CWHPServerName$"When the CiscoWorks administrator changes the DCR mode from standalone to master/slave, the root (provider) group name of all group hierarchies will be changed according to the template.
This change will be done automatically, and does not need the daemons to be restarted. Similarly, the root group name will be changed when the DCR mode is changed from Master/Slave to Standalone.
In a multi-server setup, the template can be changed to $CWHPServerName$ - $ProductId$. This change is global, applies to all OGS servers in the CiscoWorks machine, and takes effect only after the daemons are restarted. Hence, the properties file is shipped by Common Services and there will be only one properties file in a CiscoWorks installation.
The Common Services root group hierarchy will always be CS, irrespective of whether the server is in single-server mode or multi-server mode. Since there will be only one CS group hierarchy in a multi-server setup, there is no need to uniquely identify the CS group hierarchy by adding the CWHP display name.
com.cisco.nm.xms.ogs.util.OGSUtil will be augmented with the following APIs:
•
•
•
Integrating OGS 1.4 With Your Application
To integrate the client-side features of OGS 1.4 with your application:
Step 1
Step 2
TemplateSupportEnabled = trueTemplateFile=\\cwhp\\WEB-INF\\classes\\Templates.serDefaultTemplateToBeSelected=<Template String which needs to be selected default>(\\Indicates the relative location of the path from webapps directory).
The default location of OGSClient.properties file is the WEB-INF\classes directory, relative to MDC\tomcat\webapps\app-name.
By default, the template support is disabled because it is not consumed by all applications.
Step 3
The DTD for the XML file is provided here, along with sample entries. Applications should specify the entries accordingly so that they would be made available out of the box.
Note
Sample entries for creating templates in a XML file. Here the ITM application has been taken as an example for integration.
DTD for the XML File
<?xml version="1.0"?><!--****************************************************--><!-- Copyright (c) 2005 Cisco Systems, Inc. --><!-- All rights reserved. --><!--****************************************************--><!DOCTYPE TEMPLATES [<!ELEMENT TEMPLATES (TEMPLATE+,PROPERTYTABLE+) ><!ELEMENT TEMPLATE (NAME,DESCRIPTION?,TEMPLATE_RULE_CONTAINER,DISPLAY_LABEL?,TAGSTABLE?)><!ELEMENT NAME (#PCDATA)><!ELEMENT DESCRIPTION (#PCDATA)><!ELEMENT TEMPLATE_RULE_CONTAINER (TEMPLATERULE?)><!ELEMENT TEMPLATERULE (#PCDATA) ><!ELEMENT DISPLAY_LABEL (#PCDATA)><!ELEMENT TAGSTABLE EMPTY><!ATTLIST TAGSTABLE ref CDATA #REQUIRED ><!ELEMENT PROPERTYTABLE (PROPERTY+)><!ATTLIST PROPERTYTABLE name CDATA #REQUIRED ><!ELEMENT PROPERTY (KEY,VALUE)><!ELEMENT KEY (#PCDATA)><!ELEMENT VALUE (#PCDATA)>]><TEMPLATES><TEMPLATE><NAME>Location Based template</NAME><DESCRIPTION>This template is used for creating groups based upon location</DESCRIPTION><TEMPLATE_RULE_CONTAINER><TEMPLATERULE>:ITM:VASA:ITMObject:Device.Location contains</TEMPLATERULE></TEMPLATE_RULE_CONTAINER><DISPLAY_LABEL>List of Locations</DISPLAY_LABEL><TAGSTABLE ref="Locationtemplates"/></TEMPLATE><TEMPLATE><NAME>Name Based template</NAME><DESCRIPTION>This template is used for creating groups based upon Name</DESCRIPTION><TEMPLATE_RULE_CONTAINER><TEMPLATERULE>:ITM:VASA:ITMObject:Device.Name contains</TEMPLATERULE></TEMPLATE_RULE_CONTAINER><DISPLAY_LABEL>List of MDFIds</DISPLAY_LABEL><TAGSTABLE ref="Nametemplates"/></TEMPLATE><TEMPLATE><NAME>Subnet Based template</NAME><DESCRIPTION>This template is used for creating groups based upon Subnet</DESCRIPTION><TEMPLATE_RULE_CONTAINER><TEMPLATERULE>:ITM:VASA:ITMObject:Device.IP.Netmask contains</TEMPLATERULE></TEMPLATE_RULE_CONTAINER><DISPLAY_LABEL>List of Subnets</DISPLAY_LABEL><TAGSTABLE ref="Subnettemplates"/></TEMPLATE><TEMPLATE><NAME>Service Based template</NAME><DESCRIPTION>This template is used for creating groups based upon Service</DESCRIPTION><TEMPLATE_RULE_CONTAINER><TEMPLATERULE>:ITM:VASA:ITMObject:Device.Type contains</TEMPLATERULE></TEMPLATE_RULE_CONTAINER><DISPLAY_LABEL>List of Series</DISPLAY_LABEL><TAGSTABLE ref="Servicetemplates"/></TEMPLATE><TEMPLATE><NAME>Model Based template</NAME><DESCRIPTION>This template is used for creating groups based upon Model</DESCRIPTION><TEMPLATE_RULE_CONTAINER><TEMPLATERULE>:ITM:VASA:ITMObject:Device.Model contains</TEMPLATERULE></TEMPLATE_RULE_CONTAINER><DISPLAY_LABEL>List of Models</DISPLAY_LABEL><TAGSTABLE ref="Modeltemplates"/></TEMPLATE><PROPERTYTABLE name="Locationtemplates"><PROPERTY><KEY>ATTRIBUTE</KEY><VALUE>Location</VALUE></PROPERTY></PROPERTYTABLE><PROPERTYTABLE name="Nametemplates"><PROPERTY><KEY>ATTRIBUTE</KEY><VALUE>Name</VALUE></PROPERTY></PROPERTYTABLE><PROPERTYTABLE name="Servicetemplates"><PROPERTY><KEY>ATTRIBUTE</KEY><VALUE>Type</VALUE></PROPERTY></PROPERTYTABLE><PROPERTYTABLE name="Modeltemplates"><PROPERTY><KEY>ATTRIBUTE</KEY><VALUE>Model</VALUE></PROPERTY></PROPERTYTABLE><PROPERTYTABLE name="Subnettemplates"><PROPERTY><KEY>ATTRIBUTE</KEY><VALUE>IP.NetMask</VALUE></PROPERTY></PROPERTYTABLE><PROPERTYTABLE name=""><PROPERTY><KEY>ATTRIBUTE</KEY><VALUE></VALUE></PROPERTY></PROPERTYTABLE></TEMPLATES>
Note
Step 4
Entries for struts-config.xml
The following entries must be added in the OGS related sections of struts-config.xml.
<forward name="ogsBrowseProperties" path="/WEB-INF/screens/uii/index.jsp?sid=ogsBrowseProperties" /><forward name="ogsBrowseRules" path="/WEB-INF/screens/uii/index.jsp?sid=ogsBrowseRules" /><forward name="ogsBrowseMembership" path="/WEB-INF/screens/uii/index.jsp?sid=ogsBrowseMembership" /><forward name="ogsBrowseSubgroups" path="/WEB-INF/screens/uii/index.jsp?sid=ogsBrowseSubgroups" /><forward name="ogsCreateProperties" path="/WEB-INF/screens/uii/index.jsp?sid=ogsCreateProperties" /><forward name="ogsTemplateCreateProperties" path="/WEB-INF/screens/uii/index.jsp?sid=ogsTemplateCreateProperties" /><forward name="ogsCreateRules" path="/WEB-INF/screens/uii/index.jsp?sid=ogsCreateRules" /><forward name="ogsDefaultCreateRules" path="/WEB-INF/screens/uii/index.jsp?sid=ogsDefaultCreateRules" /><forward name="ogsTemplateCreateRules" path="/WEB-INF/screens/uii/index.jsp?sid=ogsTemplateCreateRules" /><forward name="ogsCreateMembership" path="/WEB-INF/screens/uii/index.jsp?sid=ogsCreateMembership" /><forward name="ogsDefaultCreateMembership" path="/WEB-INF/screens/uii/index.jsp?sid=ogsDefaultCreateMembership" /><forward name="ogsTemplateCreateMembership" path="/WEB-INF/screens/uii/index.jsp?sid=ogsTemplateCreateMembership" /><forward name="ogsCreateAccessControl" path="/WEB-INF/screens/uii/index.jsp?sid=ogsCreateAccessControl" /><forward name="ogsCreateSummary" path="/WEB-INF/screens/uii/index.jsp?sid=ogsCreateSummary" /><forward name="ogsDefaultCreateSummary" path="/WEB-INF/screens/uii/index.jsp?sid=ogsDefaultCreateSummary" /><forward name="ogsTemplateCreateSummary" path="/WEB-INF/screens/uii/index.jsp?sid=ogsTemplateCreateSummary" /><forward name="ogsEditProperties" path="/WEB-INF/screens/uii/index.jsp?sid=ogsEditProperties" /><forward name="ogsTemplateEditProperties" path="/WEB-INF/screens/uii/index.jsp?sid=ogsTemplateEditProperties" /><forward name="ogsEditRules" path="/WEB-INF/screens/uii/index.jsp?sid=ogsEditRules" /><forward name="ogsTemplateEditRules" path="/WEB-INF/screens/uii/index.jsp?sid=ogsTemplateEditRules" /><forward name="ogsEditMembership" path="/WEB-INF/screens/uii/index.jsp?sid=ogsEditMembership" /><forward name="ogsTemplateEditMembership" path="/WEB-INF/screens/uii/index.jsp?sid=ogsTemplateEditMembership" /><forward name="ogsEditAccessControl" path="/WEB-INF/screens/uii/index.jsp?sid=ogsEditAccessControl" /><forward name="ogsEditSummary" path="/WEB-INF/screens/uii/index.jsp?sid=ogsEditSummary" /><forward name="ogsTemplateEditSummary" path="/WEB-INF/screens/uii/index.jsp?sid=ogsTemplateEditSummary" /><forward name="ogsMainSetup" path="/WEB-INF/screens/uii/index.jsp?sid=ogsMainSetup" /><forward name="ogsRoleAccessControl" path="/WEB-INF/screens/popup.jsp?sid=ogsRoleAccessControl" /><forward name="ogsServerError" path="/WEB-INF/screens/uii/index.jsp?sid=ogsServerError" /><forward name="ogsSkipMemberCreateProperties" path="/WEB-INF/screens/uii/index.jsp?sid=ogsSkipMemberCreateProperties" /><forward name="ogsSkipMemberCreateRules" path="/WEB-INF/screens/uii/index.jsp?sid=ogsSkipMemberCreateRules" /><forward name="ogsSkipMemberCreateSummary" path="/WEB-INF/screens/uii/index.jsp?sid=ogsSkipMemberCreateSummary" /><forward name="ogsSkipMemberEditProperties" path="/WEB-INF/screens/uii/index.jsp?sid=ogsSkipMemberEditProperties" /><forward name="ogsSkipMemberEditRules" path="/WEB-INF/screens/uii/index.jsp?sid=ogsSkipMemberEditRules" /><forward name="ogsSkipMemberEditSummary" path="/WEB-INF/screens/uii/index.jsp?sid=ogsSkipMemberEditSummary" />Entries for Sitemap XML File
The following entries must be added in the OGS-related section in the sitemap XML file of the respective webapp:<?xml version="1.0"?><contentAreaSet><navContentArea screenID="ogsMainSetup"contentAreaTitle="Group Administration"helpTag="group_administration"fileRef="/WEB-INF/screens/OGS/ogsMainSetup.jsp"></navContentArea><appContentArea screenID="ogsBrowseProperties"contentAreaTitle="Property Details"helpTag="cs_groups_admin_view "fileRef="/WEB-INF/screens/OGS/ogsBrowseProperties.jsp" /><appContentArea screenID="ogsBrowseMembership"contentAreaTitle="Membership Details"helpTag="cs_groups_admin_view "fileRef="/WEB-INF/screens/OGS/ogsBrowseMembership.jsp" /><appContentArea screenID="ogsServerError"contentAreaTitle="Group Administration Server Error"helpTag="ogs_server_error"fileRef="/WEB-INF/screens/OGS/serverError.jsp" /><appContentArea screenID="ogsDCRSecondary"contentAreaTitle=""helpTag="ogs_dcr_secondary"fileRef="/WEB-INF/screens/OGS/ogsDCRSecondary.jsp" /><appContentArea screenID="ogsNewPage"contentAreaTitle=""helpTag="ogs_dcr_secondary"fileRef="/WEB-INF/screens/OGS/ogsNewPage.jsp" /><appWizard><appWizardItem><label>Properties</label><appContentArea screenID="ogsTemplateCreateProperties"contentAreaTitle="Properties"helpTag="cs_groups_admin_create "fileRef="/WEB-INF/screens/OGS/ogsTemplateCreateProperties.jsp" /></appWizardItem ><appWizard><appWizardItem><label>Rules</label><appContentArea screenID="ogsDefaultCreateRules"contentAreaTitle="Rules"helpTag="cs_groups_admin_create"fileRef="/WEB-INF/screens/OGS/ogsCreateRules.jsp" /></appWizardItem><appWizardItem><label>Membership</label><appContentArea screenID="ogsDefaultCreateMembership"contentAreaTitle="Membership"helpTag="cs_groups_admin_create "fileRef="/WEB-INF/screens/OGS/ogsCreateMembership.jsp" /></appWizardItem><appWizardItem><label>Summary</label><appContentArea screenID="ogsDefaultCreateSummary"contentAreaTitle="Summary"helpTag="cs_groups_admin_create "fileRef="/WEB-INF/screens/OGS/ogsCreateSummary.jsp" /></appWizardItem></appWizard><appWizard><appWizardItem><label>Templates</label><appContentArea screenID="ogsTemplateCreateRules"contentAreaTitle="Templates"helpTag="cs_groups_admin_create "fileRef="/WEB-INF/screens/OGS/ogsTemplateCreateRules.jsp" /></appWizardItem><appWizardItem><label>Membership</label><appContentArea screenID="ogsTemplateCreateMembership"contentAreaTitle="Membership"helpTag="cs_groups_admin_create"fileRef="/WEB-INF/screens/OGS/ogsCreateMembership.jsp" /></appWizardItem><appWizardItem><label>Summary</label><appContentArea screenID="ogsTemplateCreateSummary"contentAreaTitle="Summary"helpTag="cs_groups_admin_create"fileRef="/WEB-INF/screens/OGS/ogsCreateSummary.jsp" /></appWizardItem></appWizard></appWizard><appWizard><appWizardItem><label>Properties</label><appContentArea screenID="ogsEditProperties"contentAreaTitle="Properties"helpTag="cs_groups_admin_modify"fileRef="/WEB-INF/screens/OGS/ogsEditProperties.jsp" /></appWizardItem><appWizardItem><label>Rules</label><appContentArea screenID="ogsEditRules"contentAreaTitle="Rules"helpTag="cs_groups_admin_modify"fileRef="/WEB-INF/screens/OGS/ogsEditRules.jsp" /></appWizardItem><appWizardItem><label>Membership</label><appContentArea screenID="ogsEditMembership"contentAreaTitle="Membership"helpTag="cs_groups_admin_modify"fileRef="/WEB-INF/screens/OGS/ogsEditMembership.jsp" /></appWizardItem><appWizardItem><label>Summary</label><appContentArea screenID="ogsEditSummary"contentAreaTitle="Summary"helpTag="cs_groups_admin_modify"fileRef="/WEB-INF/screens/OGS/ogsEditSummary.jsp" /></appWizardItem></appWizard><appWizard><appWizardItem><label>Properties</label><appContentArea screenID="ogsCreateProperties"contentAreaTitle="Properties"helpTag="cs_groups_admin_modify"fileRef="/WEB-INF/screens/OGS/ogsCreateProperties.jsp" /></appWizardItem><appWizardItem><label>Rules</label><appContentArea screenID="ogsCreateRules"contentAreaTitle="Rules"helpTag="cs_groups_admin_modify"fileRef="/WEB-INF/screens/OGS/ogsCreateRules.jsp" /></appWizardItem><appWizardItem><label>Membership</label><appContentArea screenID="ogsCreateMembership"contentAreaTitle="Membership"helpTag="cs_groups_admin_modify"fileRef="/WEB-INF/screens/OGS/ogsCreateMembership.jsp" /></appWizardItem><appWizardItem><label>Summary</label><appContentArea screenID="ogsCreateSummary"contentAreaTitle="Summary"helpTag="cs_groups_admin_modify"fileRef="/WEB-INF/screens/OGS/ogsCreateSummary.jsp" /></appWizardItem></appWizard><appWizard><appWizardItem><label>Properties</label><appContentArea screenID="ogsTemplateEditProperties"contentAreaTitle="Properties"helpTag="cs_groups_admin_modify"fileRef="/WEB-INF/screens/OGS/ogsEditProperties.jsp" /></appWizardItem><appWizardItem><label>Templates</label><appContentArea screenID="ogsTemplateEditRules"contentAreaTitle="Templates"helpTag="cs_groups_admin_modify"fileRef="/WEB-INF/screens/OGS/ogsTemplateEditRules.jsp" /></appWizardItem><appWizardItem><label>Membership</label><appContentArea screenID="ogsTemplateEditMembership"contentAreaTitle="Membership"helpTag="cs_groups_admin_modify"fileRef="/WEB-INF/screens/OGS/ogsEditMembership.jsp" /></appWizardItem><appWizardItem><label>Summary</label><appContentArea screenID="ogsTemplateEditSummary"contentAreaTitle="Summary"helpTag="cs_groups_admin_modify"fileRef="/WEB-INF/screens/OGS/ogsEditSummary.jsp" /></appWizardItem></appWizard><appWizard><appWizardItem><label>Properties</label><appContentArea screenID="ogsSkipMemberCreateProperties"contentAreaTitle="Properties"helpTag=""fileRef="/WEB-INF/screens/OGS/ogsCreateProperties.jsp" /></appWizardItem><appWizardItem><label>Rules</label><appContentArea screenID="ogsSkipMemberCreateRules"contentAreaTitle="Rules"helpTag=""fileRef="/WEB-INF/screens/OGS/ogsCreateRules.jsp" /></appWizardItem><appWizardItem><label>Summary</label><appContentArea screenID="ogsSkipMemberCreateSummary"contentAreaTitle="Summary"helpTag=""fileRef="/WEB-INF/screens/OGS/ogsCreateSummary.jsp" /></appWizardItem></appWizard><appWizard><appWizardItem><label>Properties</label><appContentArea screenID="ogsSkipMemberEditProperties"contentAreaTitle="Properties"helpTag=""fileRef="/WEB-INF/screens/OGS/ogsEditProperties.jsp" /></appWizardItem><appWizardItem><label>Rules</label><appContentArea screenID="ogsSkipMemberEditRules"contentAreaTitle="Rules"helpTag=""fileRef="/WEB-INF/screens/OGS/ogsEditRules.jsp" /></appWizardItem><appWizardItem><label>Summary</label><appContentArea screenID="ogsSkipMemberEditSummary"contentAreaTitle="Summary"helpTag=""fileRef="/WEB-INF/screens/OGS/ogsEditSummary.jsp" /></appWizardItem></appWizard></contentAreaSet>
Note
Entry for Displaying Error Messages
Add the following entry in the appropriate property file for the webapp to display error messages:
ogs.noTemplateAttrValues=<Attribute value>
You must enter at least one value for this entry.
Generating Serialized File from the XML File
To generate a serialized file from the XML file, enter the following (where? CLI?):
com.cisco.nm.xms.ogs.client.templates.OGSTemplateGenerator XML_file_name serialized_file_nameTo run this command (?), the following files should be available in the classpath:
NMSROOT\MDC\tomcat\shared\lib\mice.jar;
NMSROOT\www\classpath;
NMSROOT\lib\classpath;
NMSROOT\MDC\tomcat\shared\lib\MICE.jar;
NMSROOT\lib\classpath\jconn2.jar;
NMSROOT\MDC\tomcat\webapps\cwhp\WEB-INF\lib\log4j.jar;
NMSROOT\MDC\tomcat\shared\lib\xerces.jar;
NMSROOT\MDC\tomcat\shared\lib\xalan.jar;
NMSROOT\MDC\tomcat\webapps\cwhp\WEB-INF\lib\ogs-client1.2.jar;
NMSROOT\MDC\tomcat\webapps\cwhp\WEB-INF\lib\cogs1.2.jar;
Integrating Configurable Display Name for Class Names Feature with Applications
In OGSClient.properties, the following properties are added to enable this feature.
•
•
Setting EnableClassNameMapping property to true enables this feature. ClassNameMappingFile property specifies the XML file where the mapping between internal classnames and external (displayable) class names are specified.
This XML file should be present in the "WEB-INF/classes" directory. The applications need to make sure that all classnames are entered properly in the XML mapping file.
The following is the DTD for the classname mapping file:
<?xml version="1.0"?><!DOCTYPE Mappings [<!ELEMENT Mappings (ClassNameMap+)><!ELEMENT ClassNameMap (InternalClass, ExternalClass)><!ELEMENT InternalClass (#PCDATA) ><!ELEMENT ExternalClass (#PCDATA) >]>The following is the sample classname mapping file:
<?xml version="1.0"?><!DOCTYPE Mappings [<!ELEMENT Mappings (ClassNameMap+)><!ELEMENT ClassNameMap (InternalClass, ExternalClass)><!ELEMENT InternalClass (#PCDATA) ><!ELEMENT ExternalClass (#PCDATA) >]><Mappings><ClassNameMap><InternalClass>:DFM:VASA:DFMObject</InternalClass><ExternalClass>DFMObject</ExternalClass></ClassNameMap><ClassNameMap><InternalClass>:DFM:VASA:DFMObject:AccessPort</InternalClass><ExternalClass>AccessPort</ExternalClass></ClassNameMap><ClassNameMap><InternalClass>:DFM:VASA:DFMObject:Device</InternalClass><ExternalClass>Device</ExternalClass></ClassNameMap><ClassNameMap><InternalClass>:DFM:VASA:DFMObject:Device:Cable</InternalClass><ExternalClass>Cable</ExternalClass></ClassNameMap><ClassNameMap><InternalClass>:DFM:VASA:DFMObject:Device:ContentNetworking</InternalClass><ExternalClass>ContentNetworking</ExternalClass></ClassNameMap></Mappings>
