Cisco Broadband Access Center (BAC) is a GUI-based, data-driven provisioning system for subscriber customer premises equipment (CPE) based upon the concept of service profiles, provisioning profiles, and task profiles. The purpose of this API is to enhance the BAC GUI capabilities by allowing a client to write in-house flow-through interface programs (scripts) to automate provisioning of the CPEs. The following topics are discussed in this chapter:
The flow-through APIs in BAC can be divided into several categories:
Inventory Manager (INV_Server)
Service Provisioning Manager (SPM), (see note)
Profile Analyzer (PA)
Profile Manager (PM)
Service Template Manager (ServiceTempMgr)
These APIs are provided as IDL files. Profile-based provisioning, shown in Figure 1-1, consists of several basic IDL modules to which you have access.
Note SPM, PA, and PM are part of one server process designated SPM_Plus.
Figure 1-1 Broadband Access Center (BAC) API Architecture.
Service Profile
Service profile defines the multi-service package to be provisioned for customer premises equipment (CPE) in the service provider network. Service profile is technology neutral, it only describes the service offering, not the technology to be used to implement the service. A provisioning profile describes the information needed to provision related devices to fulfill the service offering. A provisioning profile contains templates, default template data for each device type, and device model. It also contains other information such as the technology type and delivery method.
Service Profile Example
Profile rules are described by a DTD file, which is part of the XML script language.
<description>Basic Data Service with IP connectivity and public IP address</description>
<type>DataService</type>
<classOfService>bronze</classOfService>
<serviceFeature>NA</serviceFeature>
</ServiceProfile>
Provision Profile
A provisioning profile defines the mapping to network specifics for a service profile. It defines the technology used to implement a service profile, the network elements, and their configurations related to the network technology. All keyword attributes for a provisioning profile start with PP. Unlike service profile attributes, some attributes here are generated using variable values from the profile itself.
Provision Profile Example
Provisioning profile rules are in the DTD file listing that follows:
The Inventory Manager (IM) employs an action-based model in which the OSS communicates with it using XML over CORBA IDL. The Inventory Manager provides a set of XML schemas that describes actions, objects, and attributes for the operation.
Actions
An action request is initialized by a call to the action() operation (in the inv_mgr.idl) and requires two parameters, the security token and a string representing an XML-based action. VcScopeGetAction can be used to retrieve a list of objects of specified class under a given node, where a list of objects can be all ATM cards or all Ethernet cards under a router. The Broadband Access Center (BAC) supports the following external actions (each action is described in the Specific Action Examples section that follows):
VcCreateAction
VcGetAction
VcSetAction
VcDeleteAction
VcSetAssociationAction
VcGetAssociationAction
VcDeleteAssociationAction
VcScopeGetAction
DiscoverAction
These actions provide the user with the ability to create, retrieve, modify and delete the following objects:
AdministrativeNetwork
Aggregator
CPE
Network Devices (Generic Devices)
TemplateFeature
GenericResource
ISP Service Provider, SubscriberGroup, and Subscriber
Multiple actions can be bundled into an OperationRequestList object.
Objects
Objects are managed elements in the object model which are managed by the BAC. BAC supports the CPE, Aggregator, Switch, and Router objects. Typically, objects are specified within an action request. For example, the OSS can create an aggregator object using VcCreateAction by specifying VcAggregator object and its attributes.
Attributes
Each supported object has a set of attributes. Objects and their attributes are listed later in this chapter in the appropriate tables.
IM Action XML Schema Examples
Inventory Manager (IM) supports a request for a single action or a batch operation. Each action is identified by an operation tag (VcCreateAction, VcDeleteAction, and so on), actionObject, and attributes associated with each actionObject type. Each action request has a corresponding action response returned to the client as CreateActionResponse, if successful, or ActionFailResponse if the request fails.
Single Request Generic XML Structure
The generic format for a single action request and the expected response is given below:
<operation-tag>
<actionId/>
<description/>
<actionObject CType="actionObjectType">
<!--- action ObjectType specific attributes --->
</actionObject>
</operation-tag>
The generic XML response is as follows:
<operation-response-tag>
<actionId/>
<statusCode/>
<statusMessage>
<!--- operator response specific information --->
</operation-response-tag>
The actionId is a client-specific identifier that is returned by IM in action response. The description is a client description. Both attributes are optional.
Specific Action Examples
This section offers specific examples of DTDs and corresponding XMLs for each IM action.
VcCreateAction Example
The following DTD shows the common portion of VcCreateAction XML DTD. The valid elements for the actionObject depend on the value of the CType attributes of the actionObject. The parentFDN and objectRDN elements are mandatory for all CType.
The VcCreateActionResponse returns the actionId that is passed in during VcCreateAction. BAC does not guarantee the uniqueness of this value. A sample response follows:
The following DTD shows the common portion of VcGetActionResponse XML DTD. The valid elements for the actionObject depend on the value of the CType attributes of the actionObject.
The following DTD shows the common portion of VcSetAction XML DTD. The valid elements for the actionObject depend on the value of the CType attributes of the actionObject. The parentFDN and objectRDN elements are mandatory for all CType.
Valid values of CType for VcSetAction are listed below:
The association actions (including VcSetAssociationAction, VcGetAssociationAction, and VcDeleteAssociationAction) are used to associate/disassociate a resource to an Administrative Network or to a Network Device.
VcSetAssociationAction Example
VcSetAssociationAction allows users to associate a GenericResource object to an Administrative Network (VcAdministrativeNetwork) or to a Network Device (VcCPE or VcAggregator). The opFlag field of VcAssociationInfo can be either append or replace.
VcGetAssociationAction retrieves GenericResource objects that are associated to an Administrative Network (VcAdministrativeNetwork) or to Network Device (VcCPE or VcAggregator). The opFlag field of VcAssociationInfo can be full or fdnOnly; if not specified, the opFlag will be set to fdnOnly. If opFlag is full, the whole VcGenericResource object is returned, otherwise, only parentFDN and objectRDN are returned. The type field of VcAssociationInfo specifies the type of resource to be retrieved. If the user does not pass the associationInfoList, it will return all resource association. The complete supported resource is specified in $INSTALL_DIR/common/XMLProperties/VcSupportedResourceList.xml.
<!-- Resource_XXX can be Resource_DHCP, Resource_TelnetGateway, etc. -->
<type>Resource_XXXX</type>
<opFlag>full</opFlag>
</VcAssociationInfo>
</associationInfoList>
</actionObject>
</VcGetAssociationAction>
VcGetAssociationAction Response (DTD and XML)
This action returns the list of resources attached to the associationPoint. If the Resource is associated directly to the associationPoint, the opFlag will be set to self, otherwise the opFlag contains the FDN of the object where the resource is associated on.
The VcDeleteAssociationAction breaks the association between the resource and the Administrative Network or Device object. During DeleteAssociation, if you define the FDN of the resource, it will ignore type type variable. If the FDN is empty, then it will delete all resources of the given type.
The "scope" in ScopeGet request has three options: nthlevel, basetonth and entiresubtree. Based on this option, scopeget returns: one level of child nodes, multiple level of child nodes and ALL the child nodes.
The "returnType" has three options:
ALL—all the attributes of the objrct will be returned in the response;
FDN_ONLY—only the FDNs of the object will be returned;
SELECTED_ATTRS—only selected attributes will be returned.
Note If there are more than 100 objects specified under the current node, only 100 "maxObject" will be
returned.
VcScopeGetAction retrieves objects that meet the filtering criteria. The VcScopeGetAction is a very expensive operation, especially if the filtering results in a large amount of objects. The valid elements of objectList follow:
The DiscoverAction is used to retrieve physical interface information such as card, module, and port from a given device. To use this action, you must:
Set up the connectivity information of the given device
Set up the device to have proper snmp read community string
Inventory Manager executes a request based on the Action and ActionObject. The following sections describe the valid elements for each supported ActionObject.
VcAdminNetwork
Table 1-1 lists valid elements for actionObject with CType VcAdminNetwork.
Table 1-1 Valid elements for actionObject with CType VcAdminNetwork
Attribute Name
CreateAction
GetAction
SetAction
DeleteAction
parentFDN
Mandatory
Mandatory
Mandatory
Mandatory
objectRDN
Mandatory
Mandatory
Mandatory
Mandatory
ownerList
Mandatory
Returned
Not Required
Not Required
domainName
Optional
Returned
Yes
Not Required
description
Optional
Returned
Yes
Not Required
locationName
Optional
Returned
Yes
Not Required
VcAggregator and VcCPE
Table 1-2 lists valid elements for actionObject with CType VcAggregator and CType VcCPE.
Table 1-2 Valid elements for actionObject with CType VcAggregator and VcCPE.
Attribute Name
CreateAction
GetAction
SetAction
DeleteAction
parentFDN
Mandatory
Mandatory
Mandatory
Mandatory
objectRDN
Mandatory
Mandatory
Mandatory
Mandatory
objType
Mandatory
Returned
No
Not Required
objModel
Mandatory
Returned
No
Not Required
objSubtype
See Note 1
Returned
No
Not Required
hostname
Mandatory
Returned
Yes
Not Required
ipAddress
See Note 2
Returned
See Note 3
Not Required
subnetMask
See Note 2
Returned
See Note 3
Not Required
ipAutoAllocate
See Note 2
Returned
No
Not Required
provisioningState
Not Required
Returned
No
Not Required
description
Optional
Returned
Yes
Not Required
locationName
Optional
Returned
Yes
Not Required
ownerList
Mandatory
Returned
Not Required
Not Required
Note Note 1.
objSubtype is only required for some devices. The list of supported device types is listed in
Table 1-3.
Note Note 2.
ipAutoAllocate is either True or False, it cannot be modified after creation
- if ipAutoAllocate is true, then the ipAddress and subnetMask has to be null
- if ipAutoAllocate is false, then the ipAddress and subnetMask must not be null
Note Note 3.
Once the object is created, user can modify ipAddress and subnetMask to overwrite the rule specified in
Note 2. However, the ipAddress and subnetMask can be modified only when ipAutoAllocate is false.
Note Note 4.
During the VcCreateAction, the provisioningState is set to 4002. BAC will overwrite the value provided
by user
Use the attributes in the code that follows to enable SSH and set it either through DES or 3DES. If the router uses "ssh" as the download method, set SSH attribute when using create or set device by VcCreateAction or VcSetAction.
<useSSH>true</useSSH>
<attributeList CType="VcldValueList">
<id>sshEncryption</id>
<value>3des</value
...
</attributeList>
Table 1-3 shows the supported devices for a Broadband solution.
Table 1-3 Valid objType, objModel, objSubtype for VcAggregator object.
DeviceType
objType
objModel
objSubtype
Technology
7206
Aggregator
7206
Not used
Broadband
C10K
Aggregator
C10K
Not used
Broadband
7401
Aggregator
7401
Not used
Broadband
Table 1-4 lists the supported devices for a VoIP over Ethernet solution.
Table 1-4 Valid objType, objModel, objSubtype for VcCPE object VoIP over Ethernet solution.
DeviceType
objType
objModel
objSubtype
Technology
2421 Commercial
CPE
2421
Commercial
VoIPoE
2421 Residential
CPE
2421
Residential
VoIPoE
2611 Digital
CPE
2611
Digital
VoIPoE
2611 Analog
CPE
2611
Analog
VoIPoE
2621 Digital
CPE
2621
Digital
VoIPoE
2621 Analog
CPE
2621
Analog
VoIPoE
VcTemplateFeature
Table 1-5 lists valid elements for actionObjects with CType VcTemplate Feature. The CreateAction, SetAction, and DeleteAction are not supported.
Table 1-5 Valid elements for CType VcTemplate Feature.
Attribute Name
GetAction
parentFDN
Mandatory
objectRDN
Mandatory
featureType
Returned
attributeList
Returned
Note The featureType is defined in Service Profile.
The attributeList contains the name/value pairs of the Configuration Template variables.
VcGenericResource
Table 1-6 lists the supported resourceType and the required attributes in attributeList.
Table 1-6 Generic Resource Table
Attribute Name
CreateAction
GetAction
SetAction
DeleteAction
parentFDN
Mandatory
Mandatory
Mandatory
Mandatory
objectRDN
Mandatory
Mandatory
Mandatory
Mandatory
resourceType
Mandatory
Returned
No
Not Required
attributeList
Mandatory
Returned
Yes
Not Required
Mandatory Name/Value Pairs for VcGenericResource
Table 1-7 shows the supported resourceType and the required attributes in the attributeList for ConfigRegistrar.
Table 1-7 Valid Name/Value pairs for the Config Registrar Resource
parentFDN
Resource toCreate Under ConfigRegistrar
resourceType
Resource_ConfigEngine
attributeList
hostname
ipAddress
Table 1-8 shows the supported resource Type and the required attributes in the attributeList for AAA.
Table 1-8 Valid Name/Value pairs for AAA Resource
parentFDN
Resource to Create Under AAA
resourceType
Resource_AAA
attributeList
aaaHostName
aaaIpAddress
aaaType
aaaInstallationPath
aaaHostRootPasswd
aaaServerLoginId
aaaServerLoginPasswd
aaaAuthPort
aaaAccountPort
Table 1-9 shows the supported resource Type and the required attributes in the attributeList for TermServer.
Table 1-9 TermServer Resource
parentFDN
Resource to Create Under TermServer
resourceType
Resource_TermServer
attributeList
hostName
termServerIp
termServerUserId
termServerUserPwd
termServerSecretUserPwd
termServerPortUserPwd
VcProvider
Table 1-10 lists valid elements for actionObject with CType VcProvider.
Table 1-10 VcProvider valid elements
Attribute Name
CreateAction
GetAction
SetAction
DeleteAction
parentFDN
Mandatory
Mandatory
Mandatory
Mandatory
objectRDN
Mandatory
Mandatory
Mandatory
Mandatory
attributeList
Optional
Returned
Yes
Not Required
VcSubscriber
Table 1-11 lists valid elements for actionObject with CType VcSubscriber.
Table 1-11 VcSubscriber Valid Elements
Attribute Name
create
get
set
delete
parentFDN
Mandatory
Mandatory
Mandatory
Mandatory
objectRDN
Mandatory
Mandatory
Mandatory
Mandatory
name
Required
Returned
No
Not Required
domainList
Required
Returned
Yes
N/R
address1
Optional
Returned
Yes
N/R
address2
Optional
Returned
Yes
N/R
city
Optional
Returned
Yes
N/R
zip
Optional
Returned
Yes
N/R
state
Optional
Returned
Yes
N/R
country
Optional
Returned
Yes
N/R
contractNumber
Optional
Returned
Yes
N/R
businessPhoneNumber
Optional
Returned
Yes
N/R
VcSubscriberGroup
Table 1-12 lists valid elements for actionObject with CType VcSubscriberGroup.
Table 1-12 VcSubscriberGroup valid elements
Attribute Name
create
get
set
delete
parentFDN
Mandatory
Mandatory
Mandatory
Mandatory
objectRDN
Mandatory
Mandatory
Mandatory
Mandatory
accountNumber
Mandatory
Returned
No
N/R
firstname
Optional
Returned
Yes
N/R
middleinitial
Optional
Returned
Yes
N/R
address1
Optional
Returned
Yes
N/R
address2
Optional
Returned
Yes
N/R
city
Optional
Returned
Yes
N/R
state
Optional
Returned
Yes
N/R
county
Optional
Returned
Yes
N/R
zip
Optional
Returned
Yes
N/R
phoneNumber
Optional
Returned
Yes
N/R
email
Optional
Returned
Yes
N/R
userName
Optional
Returned
Yes
N/R
userPassword
Optional
Returned
Yes
N/R
BAC Security
The BAC security is based on Cisco CNS Authentication Framework. The Authentication Framework provides support for a simple username-password mechanisms as well as more secure mechanisms. The Authentication Services generates tokens that contain information obtained during authentication and authorization. This information is used by other sevices to check for user's privileges for performing various operations. Access to CNS Security Services is through CORBA interface (see CNS Security Services CORBA IDL Specification, EDCS-138857). The CORBA API is listed in "cns.idl," of this document. In addition, see "Building Service Requests," for client example code showing how to access the CORBA interface.
The authentication process typically involves verifying the credentials of the principal (the user that the authentication component authenticates) using a single of a set of data stores. The information regarding the users that can access the system is stored. The kind of attributes that an authentication system accepts during the authentication process defines the mechanism that the system supports.
Depending on the authentication mechanism used, the system might require single-stepped or multi-stepped inputs from the user. The username-password mechanism depends on a username-password data store for validation of the username and password in the authentication request.
Authorization
The Cisco CNS Security Policy Engine provides a common set of authentication and authorization services. The authorization framework is based on the Role Based Access Control (RBAC) model. Objects in RBAC are defined programmatic entities, not as an attribute in the schema but a conceptual pre-defined resource. In the RBAC model users do not have a discretionary access to protected objects. Instead, access permissions are associated with Roles and users are made member of Roles. The RBAC model allows the definition of security policies that closely match the enterprise operations. Users are assigned roles that have the privileges to perform certain high-level application-specific operations.
Access to CORBA Objects
The APIs for Inventory Manager, Profile Manager, Profile Analyzer, Service Provisioning Manager, and Service Template Manager, and their descriptions, are listed in the tables that follow. You can access them through CORBA. Example code on how to register with and exercise the servers is described in "Creating a Client Application,"
Inventory Manager (INV_Server)
The Inventory Manager API (inv_mgr.idl) shown in Table 1-13 supports VcCreateAction, VcGetAction, VcSetAction, VcDeleteAction, VcSetAssociationAction, VcGetAssociationAction, and VcDeleteAssociationAction.
Table 1-13 Inventory Manager API and its Use
API
Description or Use
action()
Request a new action in the inventory.
Profile Manager (PM)
The Profile Manager manages three types of profiles (service, provisioning, and task). It allows the client to create, delete, or modify profiles and associate a service profile with one or more provisioning profiles.
Associate a service profile to a list of provisioning profiles
create_group()
Create a new group
create_profile()
Create a new profile
de_associate()
De-associate a set of profiles from the source
delete_group()
Delete a group
delete_profile()
Delete all associations, then delete the profile
get_associated_profiles()
Returns a set of associated profiles
get_profile()
Retrieve profile type data
get_profile_list()
List profile header information within a group
get_subgroups()
Return a list of subgroups
modify_profile()
Modify an existing profile
ProfileUtility (PU)
A service profile, described by the ProfileUtility.idl file, can be associated with provisioning profiles. A service profile describes the service offering. A provisioning profile describes the information needed to provision related devices in order to fulfill the service offering. A provisioning profile contains templates, default template data for each device type, and the device model. It also contains other information such as the technology type and delivery method. The Profile Analyzer API allows a client to retrieve this information by passing appropriate filtering criteria.
Table 1-15 shows PU APIs and their functional descriptions.
Table 1-15 Profile Utility APIs and Their Use
API
Description or Use
get_device_download_config()
Returns a download config object for the given device
get_service_features()
Returns a string array of service features for the given service profile
get_service_features_for_device()
Returns a string array of service features for the given device
get_service_profile()
Returns a ServiceProfile object for the given profile FDN
get_technologies()
Returns a string array of technologies for the given service profile
get_template_info()
Returns a device template info object for the device
get_touched_device()
Returns an array of DeviceTemplateInfo objects for the given service feature
Service Provisioning Manager (SPM_Server)
The Service Provisioning Manager API is is used to process a provisioning request and is described by the ServiceProvisioning.idl file.
Table 1-16 Service Provisioning Manager API and its Description
API
Description or Use
process_provision_request()
Process a provision request
CSTMServer
This API is contained in the CSTMServer.idl file. A template is a configuration file with configurable variables. Each configurable variable is called a template variable and is replaced with corresponding template data in order to generate a configuration file.
Table 1-17 shows the CSTMServer APIs and their descriptions.
Table 1-17 CSTMServer APIs and their Descriptions
API
Description or Use
get_template_variables()
This idl is used to connect to CSTM
get_template_variables_and_data()
Retrieve the template attributes and data for a template data
Listening to External Events
Currently, external events are sent over Tibco interface, requiring Tibco Ver. 6.4.8 to be installed. The Tibco events that are published right now are listed below:
Thus, depending on the event, the following code could be used for creation, attribute change, and deletion, respectively:
sent event...com.cisco.insmbu.ccnsc_sp.mo_events.creation
sent event...com.cisco.insmbu.ccnsc_sp.mo_events.attr_value_change
sent event...com.cisco.insmbu.ccnsc_sp.mo_events.deletion
The XML format is the same for all the events, what differs is the payload. For create event the complete MOC object would be published, as in example below; for the delete event only the parentFDN, RDN, and classIdentifier would be published; for modify event only the variables which are changed for the MOC object would be published.
Creation Event XML Format
In this case, the entire MocObject would be published, since the user needs to know what object type is being created and which parameters are used.
In this event type, only the ReferenceByList has changed, so only that information would be published along with the parentFDN, objectRDN, and classIdentifier.
In delete event only the parentFDN, objectRDN, and classIdentifier of the deleted object would be published, user doesn't need to know what were the attributes of the deleted object.
