Cisco VNMC XML API Reference Guide, Release 2.0
Introducing the Cisco VNMC XML API
Downloads: This chapterpdf (PDF - 608.0KB) The complete bookPDF (PDF - 1.59MB) | Feedback

Introducing the Cisco VNMC XML API

Table Of Contents

Introducing the Cisco VNMC XML API

Overview of VNMC and XML APIs

VNMC

VNMC Management Information Model

VNMC Components

Management Controller

Service Registry

Resource Manager

Policy Manager

VM Manager

VNMC XML API

VNMC Data Model Schema

Accessing VNMC Services

Object Naming

Distinguished Name

Relative Name

API Method Categories

Authentication Methods

Query Methods

Query Filters

Simple Filters

Property Filters

Composite Filters

Modifier Filters

Configuration Methods

Data Validation

Event Subscription Methods

Subscribing to Event Notification

UML Diagrams

Classes

Associations

Inheritance

Aggregations and Compositions

Capturing XML Interchange Between the VNMC GUI and Server

Success or Failure Responses

Successful Responses

Failure Responses

Empty Result Responses


Introducing the Cisco VNMC XML API


The following sections provide general information about Cisco Virtual Network Management Center (VNMC) and the XML application programming interface (API):

Overview of VNMC and XML APIs

API Method Categories

Data Validation

Event Subscription Methods

UML Diagrams

Capturing XML Interchange Between the VNMC GUI and Server

Success or Failure Responses

Overview of VNMC and XML APIs

The following sections provide an overview of VNMC and the XML API:

VNMC

VNMC Management Information Model

VNMC Components

VNMC XML API

VNMC Data Model Schema

Accessing VNMC Services

Object Naming

Authentication Methods

VNMC

VNMC is a virtual appliance that provides centralized device and security policy management for Cisco virtual services. Designed to support enterprise and multiple-tenant cloud deployments, VNMC provides transparent, seamless, and scalable management for securing virtualized data center and cloud environments.

With a built-in GUI and an XML API, VNMC enables you to configure, deploy, and manage virtual services throughout the data center from a central location.

VNMC is built on an information model-driven architecture in which each managed device is represented by its subcomponents (or objects), which are parametrically defined. This model-centric approach provides a flexible and simple mechanism for securing a virtualized infrastructure with compute and edge firewalls.

VNMC supports multiple client organizations, or tenants, that have their own virtualized compute, network, and storage resources, and that are deployed across a shared physical infrastructure. Multiple tenants can coexist on the same infrastructure, with each tenant maintaining administrative privileges for its virtualized resources. This multiple-tenancy design enables you to meet the specified service level agreement (SLA) for each tenant, including compute, network, storage, and security policies.

VNMC Management Information Model

All physical and logical components that comprise a VNMC service component are represented in a hierarchical management information model. This model is referred to as the management information tree. The hierarchical structure starts at the top and contains parent and child nodes. Each node in the tree represents a managed object (or group of objects) and displays the object's administrative and operational states. Each object has a unique distinguished name (DN) that describes the object and its location in the tree.

Managed objects are abstractions of VNMC-managed entities, such as policies, rules, security profiles, and compute and edge firewalls. By invoking the API, objects are read from and written to the management information tree. The information model of an individual VNMC service component is centrally stored and managed by the data management engine (DME). When a user initiates an administrative change to a VNMC service component (for example, by associating an edge firewall profile to an ASA 1000V, the DME first applies that change to the information model, and later the change is applied to the actual ASA 1000V. This approach is called a model-driven framework.

VNMC Components

VNMC consists of multiple service components that provide modularized functions for management, tenant management, policy management, resource management, and so on. These components are also called service providers or applications. Each component is accessed through a unique URL.

The following sections describe the VNMC components:

Management Controller

Service Registry

Resource Manager

Policy Manager

VM Manager

Each component has its own data model and a DME that processes the model-driven service requests. Each component maintains its own management information tree storage (both in memory and in the persistent storage). Data sharing across different service components is achieved with ad-hoc interservice API communications or by using a publish or subscribe method.

Management Controller

Management Controller, also known as the core service, provides system-related services for the VNMC virtual machine, such as:

Authenticates and authorizes user logins in local or LDAP mode.

Provides access control, such as locales, roles, and trusted points.

Maintains system information, such as the IP address, subnet mask, gateway, and hostname.

Upon user input, performs system maintenance operations, such as database backup, data export, and data import.

Maintains system diagnostic information, such as audit logs, faults, event logs, and core dump files.

The Management Controller type is mgmt-controller. Use this service type in the API URL for all requests related to the Management Controller.

Service Registry

Service Registry is the central service repository that holds information about all registered managed endpoints (such as ASA 1000Vs or VSGs) and the service providers (such as Policy Manager or Resource Manager).


Note Service endpoints are referred as clients in the GUI.


Service endpoints and the service providers register themselves dynamically with the Service Registry and retrieve information about service components from the Service Registry. The Service Registry is also responsible for tenant management and provides the following services:

Upon user input, creates, deletes, and updates organizations (tenants, data centers, applications, and tiers). Organization changes are automatically propagated to Policy Manager and Resource Manager when policies and resources are attached to the intended organizations.

Maintains information about the registered services (such as providers, endpoints, and Management Controller).

Maintains diagnostic information, such as audit logs, faults, and event logs.

The Service Registry type is service-reg. Use this service type in the API URL for all requests related to the Service Registry.

Resource Manager

Resource Manager manages logical compute and edge firewalls and their association with VSGs and ASA 1000Vs, respectively. When an edge firewall is associated with an ASA 1000V, the device configuration profile information (defined by the edge firewall) is pushed to the ASA 1000V which, in turn, triggers the ASA 1000V to download the security profiles and policies from Policy Manager.

Resource Manager is responsible for the following services:

Maintains an inventory of ASA 1000Vs, VSGs, and Cisco Virtual Supervisor Modules (VSMs).

With user input, defines compute firewalls and associates them with VSGs for provisioning.

With user input, defines edge firewalls and associates them with ASA 1000Vs for provisioning.

Interacts with VMware vCenter instances to retrieve Virtual Machine (VM) attributes.

Maintains an inventory of discovered VMs and distributes them to the VSGs with the following information:

VM attributes, such as name, hypervisor, parent vApp, and cluster

vNIC attributes, such as port profile name and IP address

Manages pools of VSGs and ASA 1000Vs.

Maintains health states and faults for VSGs and ASA 1000Vs.

Maintains diagnostic information, such as audit logs, faults, and event logs.

The Resource Manager type is resource-mgr. Use this service type in the API URL for all requests related to Resource Manager.

Policy Manager

Policy Manager is the central repository for device configuration profiles, service policies, service profiles, and all associated artifacts. When a compute firewall is associated with a VSG from Resource Manager, the VSG queries Policy Manager to resolve the device profile, service profiles, and all referenced policies. The VSG then configures itself according to the information retrieved from Policy Manager. The same process is used when an edge firewall is associated with an ASA 1000V.

Policy Manager provides the following services:

Using the user input, defines:

Firewall device profiles

Object groups

Policies

Policy rules with conditions on:

—Network attributes such as protocol, source or destination, IP address, and port.

—VM attributes such as instance name, guest OS, zone, parent application, port profile, cluster, resource pool, hostname, and hypervisor.

—Custom attributes.

Policy sets

Security profile dictionary and custom attributes

Service profiles

VNMC system management device profiles and policies for NTP, DNS, syslog, and faults.

Virtual zones (vZones)

Using the user input, assigns policies and policy sets.

Distributes service policies, service profiles, device profiles, and associated objects to edge and compute firewall instances.

Maintains diagnostic information such as audit logs, faults, and event logs.

The Policy Manager service type is policy-mgr. Use this service type in the API URL for all requests related to Policy Manager.

VM Manager

VM Manager is responsible for interacting with VMware vCenter and maintaining the VM information retrieved from vCenter. It is a backend service without any user-accessible services. The VM Manager service type is vm-mgr.

VNMC XML API

The VNMC XML API is a programmatic way of integrating and interacting with VNMC. The API interface accepts XML documents by using the HTTPS protocol. Developers can use any programming language to generate XML documents that contain the API methods. Configuration and state information is stored in a hierarchical tree structure known as the management information tree, and is completely exposed through the XML API.

The API model is recursively driven and provides major functionality for application development. For example, changes can be made on a single object, an object subtree, or the entire object tree. Changes can be made to a single attribute on an object or applied to the entire VNMC structure with a single API call.

The API operates in forgiving mode. Missing attributes are substituted with default values (if applicable) that are maintained in the DME. If multiple managed objects (such as policies) are being configured, and any of the managed objects cannot be configured, the API stops the operation, returns the configuration to its prior state, and then stops the API process with a fault notification.

The API leverages an asynchronous operations model to improve scalability and performance. Processes that require time to complete are nonblocking or asynchronous; that is, faster API processes are not blocked or delayed by those that require more time. A process receives a success message upon a valid request and a completion message when the task is finished.

Full event subscription is supported. VNMC sends notifications to all subscribers for the events that occur (such as changes to managed objects), and indicates the type of state change.

Future updates to the managed object data model will conform to the existing object model to ensure backward compatibility. If existing properties are changed during a product upgrade, it will be handled during the database load after the upgrade. New properties will be assigned default values.

VNMC uses a model-driven architecture, where changes are first applied to logical constructs in the form of managed objects. The managed objects then apply the changes to the endpoints to achieve the required state (that is, configuration) of the endpoint.

Operation of the API is transactional and terminates on a single data model. VNMC is responsible for all endpoint (ASA 1000V, VSG, and VSM) communication (such as state updates). API users cannot communicate directly with endpoints, which relieves the users from administering isolated, individual component configurations.

The VNMC API model includes the following programmatic entities:

Classes—Objects and their properties and states in the management information tree.

Methods—Actions that the API performs on one or more objects.

Types—Collections or ranges of allowed values for object properties.

A typical request comes into a service component's DME and is placed in the transactor queue in first-in, first-out (FIFO) order. The transactor gets the request from the queue, interprets the request, and performs an authorization check. When the request is confirmed, the transactor updates the management information tree. This process is done in a single transaction.

VNMC Data Model Schema

The data model HTML documents and schemas for all VNMC service providers are packaged with the VNMC server and can be accessed from either of the following URLs:

https://vnmc-ip-address/doc, which includes:

core

policy-mgr

resource-mgr

service-reg

https://vnmc-ip-address/schema, which includes:

core.in.xsd—Management controller configuration APIs and data model.

core.out.xsd—Management controller query APIs and data model.

policy-mgr.in.xsd—Policy manager configuration APIs and data model.

policy-mgr.out.xsd—Policy manager query APIs and data model.

resource-mgr.in.xsd—Resource manager configuration APIs and data model.

resource-mgr.out.xsd—Resource manager query APIs and data model.

service-reg.in.xsd—Service registry configuration APIs and data model.

service-reg.out.xsd—Service registry query APIs and data model.

Accessing VNMC Services

You can access VNMC services using XML API requests over HTTPS protocol. The HTTPS request URL format is:

https://vnmc-ip-address/xmlIM/service-type
 
   

where service-type is the service type of the intended service provider as described in VNMC Components. For example, to submit a request to the Policy Manager, use the service type policy-mgr as shown in the following example:

https://vnmc-ip-address/xmlIM/policy-mgr
 
   

Object Naming

You can identify a specific object by its distinguished name (DN) or by its relative name (RN) as described in the following sections:

Distinguished Name

Relative Name

Distinguished Name

A DN enables you to unambiguously identify a target object. DNs use the following format, which consists of a series of relative names:

dn = rn/rn/rn/rn...
 
   

For example, a series of relative names might resemble the following example:

org-root/org-tenant1/zone-trustedServers-0
 
   

In the following example, the DN provides a fully qualified path for a Zone (vZone in the GUI) object (zone-trustedServers-0) from the top of the object tree to the object. The DN specifies the exact managed object on which the API call is operating.

< ...dn = "org-root/org-tenant1/zone-trustedServers-0" />
 
   

Relative Name

An RN identifies an object within the context of its parent object. The DN of an object consists of the parent DN and the RN in the following format:

dn = parent-dn/rn
 
   

For example, a Zone (vZone in the GUI) object with the name trustedServers-0 that resides under the tenant Tenant1 has the following related RN and DNs:

The object's RN is zone-trustedServers-0.

The object's parent tenant DN is org-root/org-Tenant1.

The object's DN is org-root/org-Tenant1/zone-trustedServers-0.

API Method Categories

Four method categories are used to interact with VNMC. Each API is a method, and each method corresponds to an XML document. The following sections describe method categories in more detail and how to use query filters to retrieve the required information:

Authentication Methods

Query Methods

Query Filters

Configuration Methods

Event Subscription Methods


Note Several code examples in this guide substitute the term <real_cookie> for an actual cookie such as 1217377205/85f7ff49-e4ec-42fc-9437-da77a1a2c4bf. The VNMC cookie is a 47-character string. It is not the type of cookie that web browsers store locally to maintain session information.


Authentication Methods

Authentication methods initiate and maintain active VNMC sessions. A successful authentication must be performed before other API calls are allowed. API requests are cookie authenticated.

After a connection session is established and authenticated, a cookie is returned in the response. It is valid for 7200 seconds (120 minutes). The cookie must be refreshed during the session period to prevent it from expiring. Each refresh operation creates a cookie valid for the default interval.

A maximum of 256 sessions to VNMC can be opened at any one time. Subsequent login requests are rejected after the maximum session limit is reached.

Operations are performed by using the HTTP POST method. VNMC supports only the HTTPS protocol on port 443. The HTTP envelope contains the XML configuration.

Table 1-1 describes the available authentication methods.

Table 1-1 Authentication Methods 

Method
Description

aaaLogin

Initial method for logging into VNMC.

Establishes a connection session and obtains a valid cookie.

aaaRefresh

Maintains the session and refreshes the current authentication cookie.

aaaLogout

Terminates the current session and deactivates the current authentication cookie.


Query Methods

Query methods obtain information on the current configuration state of a VNMC object.

Most query methods have the argument inHierarchical, with a Boolean value of true/yes or false/no. If true, the inHierarchical argument returns all child objects. For example:

<configResolveDn ... inHierarchical="false"></>
<configResolveDn ... inHierarchical="true"></>
 
   

API query methods can also include an inRecursive argument that specifies whether or not the call should be recursive; that is, whether the call should follow objects that point back to the referring objects or to the parent object.

Table 1-2 describes the available query methods.

Table 1-2 Query Methods 

Method
Description

configResolveDn

Retrieves objects by DN.

configResolveDns

Retrieves objects by a set of DNs.

configResolveClass

Retrieves objects of a given class.

configResolveClasses

Retrieves objects of multiple classes.

configFindDnsByClassId

Retrieves the DNs of a specified class.

configResolveChildren

Retrieves the child objects of an object.

configResolveParent

Retrieves the parent object of an object.

configScope

Performs class queries on a DN in the management information tree.


Query Filters

The API includes filters that increase the usefulness of the query methods. These filters can be passed as part of a query and are used to identify the wanted result set. The following sections describe the available filters:

Simple Filters

Property Filters

Composite Filters

Modifier Filters

Simple Filters

There are two simple filters: true and false. These filters react to the simple states of true or false, as follows:

True filter—Result set objects carry the Boolean condition of true.

False filter—Result set objects carry the Boolean condition of false.

For more information, see Simple Filters.

Property Filters

Property filters use object property values as the criteria for inclusion in a result set. To create most property filters, the classId and propertyId of the target object and property are required, along with a value for comparison.

Table 1-3 describes the types of property filters.

Table 1-3 Property Filters 

Filter
Description

Equality

Result set contains objects with the identified property of equal to the provided property value.

Not equal

Result set contains objects with the identified property of not equal to the provided property value.

Greater than

Result set contains objects with the identified property of greater than the provided property value.

Greater than or equal

Result set contains objects with the identified property of greater than or equal to the provided property value.

Less than

Result set contains objects with the identified property of less than the provided property value.

Less than or equal

Result set contains objects with the identified property of less than or equal to the provided property value.

Wildcard

Result set contains objects with the identified property that satisfies the wildcard criteria. Supported wildcards are:

%—Percent sign, matching a single character.

*—Asterisk, matching zero or more characters.

?—Question mark, matching zero or one character.

- —Dash, indicating a range to match. For example, [a-e] would match any character between a and e.

+—Plus sign, matching one or more characters.

Any bits

Result set contains objects with the identified property that has at least one of the passed bits set. (Available for use only on bitmask properties.)

All bits

Result set contains objects with the identified property that has all the passed bits set. (Available for use only on bitmask properties.)


For more information, see Property Filters.

Composite Filters

Composite filters are composed of two or more component filters and thereby enable greater flexibility in creating result sets. For example, a composite filter could restrict the result set to only those objects that were accepted by at least one of the contained filters.

Table 1-4 describes the available composite filters.

Table 1-4 Composite Filters 

Filter
Description

AND

Result set must pass the filtering criteria of each component filter. For example, to obtain all compute blades with totalMemory greater than 64 megabytes and operability of operable, the filter is composed of one greater than filter and one equality filter.

OR

Result set must pass the filtering criteria of at least one of the component filters. For example, to obtain all the service profiles that have an assignmentState of unassigned or an associationState value of unassociated, the filter is composed of two equality filters

Between

Result set contains those objects that fall between the range of the first specified value and second specified value. For example, all faults that occurred between two dates.

XOR

Result set contains those objects that pass the filtering criteria of no more than one of the composite's component filters.


For more information, see Composite Filters.

Modifier Filters

Modifier filters change the results of a contained filter. Only the NOT modifer filter is supported. This filter negates the result of a contained filter. Use this filter to obtain objects that do not match contained criteria.

For more information, see Modifier Filters.

Configuration Methods

Several methods enable you to make configuration changes to managed objects. Depending on the configuration method you use, the changes can be applied to the whole tree, a subtree, or an individual object. Examples of configuration methods include the following:

configConfMo—Affects a single subtree, that is, a DN.

configConfMos—Affects multiple subtrees, that is, several DNs.

configConfMoGroup—Makes the same configuration changes to multiple subtree structures or managed objects.

Most configuration methods use the argument inHierarchical. These values do not play a significant role during configuration because child objects are included in the XML document and the DME operates in the forgiving mode.

Data Validation

VNMC validates all configuration information that is entered via the API for each property, including the data type (such as integer, boolean, or string) and any additional constraints (such as an integer range or string regular expression). If the information supplied via the API does not meet the requirements for the specified property, VNMC stops the transaction and issues a failure response.

For more information about failure responses, see Success or Failure Responses.

Event Subscription Methods

When an object is created, changed, or deleted because of a user- or system-initiated action, an event is generated. Applications can receive VNMC state change information by regular polling or subscribing to events. Because polling is resource-expensive, event subscription is the preferred method of notification.

Event subscription allows a client application to register for event notification from VNMC. When an event occurs, VNMC sends a notification of the event and its type to the subscribing client applications. Only actual change events are sent, not the object's unaffected attributes. This process applies to all object changes in the system.

Subscribing to Event Notification

To subscribe to event notification:


Step 1 Log into VNMC to obtain a valid cookie for event subscription. If you are not logged in, the event subscription request will be rejected with an error response.

Step 2 Open an HTTP session and keep the session open.

Step 3 Post the eventSubcribe request through the HTTP session as follows:

<eventSubscribe cookie="<real_cookie>"></eventSubscribe> 
 
   

After the eventSubscribe request is accepted by VNMC, VNMC will send all new events as they occur through the HTTP session.


Each event has a unique event identifier (ID). Event IDs operate as counters and are included in all event notifications. When an event is generated, the event ID counter increments and a new event is assigned a new event ID. This process enables tracking of events and ensures that no event is missed. If an event is missed by the client, you can use loggingSyncOcns to retrieve the missed event.


Note For VNMC, only the HTTP protocol is supported for event subscription. Use HTTP when posting the event subscription request.


The asynchronous event notifications for the following methods do not use the same format as other methods. Instead, event notifications for these methods use the format and syntax shown in the examples.

configMoChangeEvent

<xs:element name="configMoChangeEvent" type="configMoChangeEvent" 
substitutionGroup="externalMethod"/>
        <xs:complexType name="configMoChangeEvent" mixed="true">
            <xs:attribute name="cookie" type="xs:string"/>
            <xs:attribute name="response" type="YesOrNo"/>
            <xs:attribute name="errorCode" type="xs:unsignedInt"/>
            <xs:attribute name="errorDescr" type="xs:string"/>
            <xs:attribute name="invocationResult" type="xs:string"/>
        </xs:complexType>
 
   

methodVessel

<xs:element name="methodVessel" type="methodVessel" 
substitutionGroup="externalMethod"/>
        <xs:complexType name="methodVessel" mixed="true">
            <xs:attribute name="cookie" type="xs:string"/>
            <xs:attribute name="response" type="YesOrNo"/>
            <xs:attribute name="errorCode" type="xs:unsignedInt"/>
            <xs:attribute name="errorDescr" type="xs:string"/>
            <xs:attribute name="invocationResult" type="xs:string"/>
        </xs:complexType>
 
   

UML Diagrams

Unified Modeling Language (UML) diagrams complement the object-oriented development approach used for VNMC. These diagrams display classes and associations between classes, along with attributes and methods, so that you can gain an overall view of VNMC classes and how the classes relate to one another.

The VNMC UML diagrams include the following attributes, as described in the subsequent topics:

Classes

Associations

Inheritance

Aggregations and Compositions

To view sample VNMC UML diagrams, see "UML Diagrams."

Classes

In UML, a class is a representation of an object. In VNMC, examples of objects, and therefore classes, are tenants, compute firewalls, edge firewalls, policies, and profiles. In general, anything that you can create in VNMC can be considered a class.

Classes are the primary components of UML and are presented as rectangles in UML diagrams, as shown in Figure 1-1.

Figure 1-1 Representation of a Class in UML

The class representation contains the following three sections:

Class name—Name of the object.

Attribute—Information that is stored about the object.

Method—Operations that the object or class can perform.

Figure 1-2 shows an example of a class with example entries in each section.

Figure 1-2 Example Class in UML

Not all class diagrams contain content in all sections. For example, you might see UML class diagrams with class name and attributes, but without methods. In these situations, the three sections are displayed, but the method section contains no information.

Associations

An association in UML diagrams indicates that a link or dependency exists between two or more classes. Associations are represented in a number of ways, as shown in Figure 1-3 and described in Table 1-5.

Figure 1-3 Associations in a UML Diagram

Table 1-5 UML Association Conventions 

Convention
Description
Lines

Solid line

When used with a closed, unfilled arrowhead, indicates inheritance with the arrowhead pointing to the higher class object (or superclass).

When used with an open arrowhead, indicates an association to the known class.

Dashed line

Indicates a named reference, with the arrow originating from the referencing object.

Arrowheads

Closed unfilled arrowhead

When used with a solid line, indicates inheritance, with the arrowhead pointing to the superclass.

Filled arrowhead

Indicates a nested flow of control or a procedure call.

Open arrowhead

When used with a solid line, indicates a unidirectional association with the arrowhead pointing to the known class.

Single arrowhead

When used with a solid line, indicates inheritance with the arrowhead pointing to the superclass.

When used with a dashed line, indicates a unidirectional association, in the direction of the arrowhead.

Two or no arrowheads

When used with a solid line, indicates a bidirectional association.

Diamonds

Empty diamond

Indicates a basic aggregation between objects with the empty diamond at the parent end.

Filled diamond

Indicates a composition aggregation between objects with the filled diamond at the parent end.

Multiplicity Indicators

Indicate the number of instances of the object that can be associated with the connected object.

0..1

Zero or one.

1

Only one.

0..*

Zero or more.

1..*

One or more.

n

Only n, where n > 1.

0..n

Zero to n, where n > 1.

1..n

One to n, where n > 1.


Inheritance

Similar or closely related classes often use many of the same attributes or methods. To prevent repetitive coding for multiple classes, UML employs an inheritance mechanism that enables you to reuse existing attributes and methods.

In an inheritance situation, the class that inherits the information is referred to as the subclass, and the class that is inherited from is referred to as the superclass. If all attributes and methods of one class are inherited by another class, that situation is referred to as pure inheritance.

In UML diagrams, inheritance is indicated by solid line with a closed arrowhead pointing from the subclass to the superclass.

Aggregations and Compositions

Aggregations and compositions are types of associations that have unique characteristics. When working with UML diagrams, it is important to understand the differences between aggregations and compositions, and how they are presented in the diagrams.

Table 1-6 describes the differences between aggregation and composition associations.

Table 1-6 Aggregation and Composition Characteristics 

In an Aggregation...
In a Composition...

The aggregate object does not affect the existence of the component object.

That is, if the aggregate object is removed from the system, the component objects continue to exist.

The aggregate object affects the existence of the component object.

That is, if the aggregate object is removed from the system, all component objects are also removed.

A component object can be aggregated by other classes in the system.

A component object cannot be used by any object other than its aggregate (or parent) object.

Changes in the component object can be propagated to the rest of the system.

Changes in the component object cannot be propagated to the rest of the system.

In UML diagrams, aggregations are represented by a solid line with an empty diamond at the parent end:

In UML diagrams, compositions are represented by a solid line with a filled diamond at the parent end:


Capturing XML Interchange Between the VNMC GUI and Server

The VNMC GUI is a web-based application that is developed using an Adobe Flex GUI framework. As a result, you can capture the XML interchange between the GUI and the VNMC server by installing a debug version of Adobe Flash Player. After you install the debug version of Adobe Flash Player, the log output is stored in a log file under your home directory. (In Windows 7, the log file can be found under C:\Users\username\AppData\Roaming\Macromedia\Flash Player\Logs\flashlog.txt.) Most of the sample request and response content included in the Example sections in Chapter 3 "VNMC XML API Methods" is captured in this manner.

Success or Failure Responses

VNMC responds almost immediately to any API request. If the request cannot be completed, a failure is returned. For a query or login method, the actual results are returned. For configuration methods, a successful response indicates that the request is valid, but does not indicate that the operation was completed. For example, after a database backup request is accepted with a successful response from VNMC, the VNMC server might take a longer time to finish the actual backup.

The following sections describe response types in more detail:

Successful Responses

Failure Responses

Empty Result Responses

Successful Responses

Upon a successful response, an XML document is returned with the requested information or a confirmation that changes were made.

The following example shows a configResolveDn request on a policy with the DN org-root/org-tenant d3337/pol-pl:

<configResolveDn cookie="<real_cookie>"
	dn="org-root/org-tenant_d3337/pol-p1" 
	inHierarchical="false"/>
 
   

The response includes the following details:

<configResolveDn
	dn="org-root/org-tenant_d3337/pol-p1"
	cookie="<real_cookie>"
	commCookie="7/13/0/a3c"
	srcExtSys="10.193.34.70"
	destExtSys="10.193.34.70"
	srcSvc="sam_extXMLApi"
	destSvc="policy-mgr_dme"
	response="yes">
	<outConfig>
		<policyRuleBasedPolicy
			descr=""
			dn="org-root/org-tenant_d3337/pol-p1"
			intId="10811"
			name="p1"/>
	</outConfig>
</configResolveDn></configResolveDn>

Failure Responses

Responses to failed requests include XML attributes for errorCode and errorDescr. The following example shows the response to a failed request that tried to create a policy with the same name as another policy already in the system:

<configConfMo
	dn="org-root/org-tenant_d3337/pol-p1"
	cookie="<real_cookie>"
	commCookie="7/13/0/2038"
	srcExtSys="10.193.34.70"
	destExtSys="10.193.34.70"
	srcSvc="sam_extXMLApi"
	destSvc="policy-mgr_dme"
	response="yes"
	errorCode="103"
	invocationResult="unidentified-fail"
	errorDescr="can't create; object already exists.">
 </configConfMo>
 
   

Empty Result Responses

A query request for a nonexistent object is not treated as a failure. If the object does not exist, a success message is returned, but the XML document contains an empty data field, <outConfig> </outConfig>, which indicates that the requested object was not found.

The following example shows resolution by DN on a nonexistent policy:

<configResolveDn
	dn="org-root/org-tenant_d3337/pol-p1"
	cookie="<real_cookie>"
	commCookie="7/13/0/203e"
	srcExtSys="10.193.34.70"
	destExtSys="10.193.34.70"
	srcSvc="sam_extXMLApi"
	destSvc="policy-mgr_dme"
	response="yes">
	<outConfig>
	</outConfig>
</configResolveDn>