Cisco Prime Fulfillment API Programmer Guide 6.2

Common APIs

This chapter describes the Cisco Prime Fulfillment APIs for operations that are common to all Prime Fulfillment services. These operations include; creating inventory in the Prime Fulfillment respository, session login, auditing, deployment and collection tasks, database event notifications, and general purpose XML requests.

This chapter contains the following sections:

•Inventory

•Devices

•Session

•Tasks

•General Purpose APIs

•Date/Time Format in API Requests

Inventory

You can create, modify, delete, or view any inventory object in the Prime Fulfillment repository. Use the following API operations to:

•Create an object—createInstance

•Modify an object—modifyInstance (Resource pools do not support the Modify operation.)

•Delete an object—deleteInstance

•View an object—enumerateInstances

Note When you send a view request (enumerateInstances) for an object, the response returns the create and modify date information.

Inventory APIs are divided into the following categories:

•Devices—Physical devices in the network

•Resource Pools—IP address pools, VLAN pools, route target, route distinguisher

•Topology—CE routing communities (CERCs), virtual private networks (VPNs), and named physical circuits (NPCs)

•Groupings—Access domains, device groups, collection zones.

Note XML examples for all APIs are available at: Cisco Prime Fulfillment API Programmer Reference 6.2

Devices

The inventory APIs for devices allow you to define a physical device in the Prime Fulfillment repository. Every network element that Prime Fulfillment manages must be defined as a device in the system. An element is any device from which Prime Fulfillment can collect configuration information.

Table 3-1 shows the devices available as inventory objects.

Resource Pools

Resource pools allow you to manage various pool types and to associate a pool with any service model object in the Prime Fulfillment repository. Pools help to automate service deployment.

Prime Fulfillment supports the following resource pools:

•IP address pools—Defined and assigned to regions.

•Multicast pools—Used for multicast MPLS VPNs.

•Route Distinguisher (RD) pool—The IP subnets advertised by the CPE devices to the PE devices are augmented with a 64-bit prefix, which is the route distinguisher.

•Route Target (RT) pool—The MPLS mechanism that informs PEs which routes to insert into the appropriate VPN routing and forwarding table (VRF). Every VPN route is tagged with one or more route targets when it is exported from a VRF and offered to other VRFs.

•Site-of-origin pool—The pool of values for the site-of-origin attribute. The site-of-origin attribute prevents routing loops when a site has multiple connections to the MPLS VPN backbone.

•VLAN ID pool—VLAN ID pools are attached to an access domain. To have Prime Fulfillment automatically assign VLANs to end-to-end wire links (for L2VPN provisioning), you can specify the AutoPickVlanId option.

•VC ID pool—A 32-bit identifier that is shared between the two PEs. The VC ID is a globally unique value.

Note The Modify operation is not supported with resource pools.

Table 3-2 shows the resource pools available as inventory objects.

Topology

In complex topologies, it is sometimes necessary to further define the connectivity between CE and PE devices into groups, such as CE routing communities (CERCs), virtual private networks (VPNs), and named physical circuits (NPCs).

Tip Use the Topology tool in the GUI to check CERC memberships and the resulting VPNs.

Table 3-3 shows the topology elements available as Prime Fulfillment inventory objects.

Tip Use ViewVRF.xml to view the VRF routing tables.

Groupings

Prime Fulfillment is designed to provision a large number of devices through its distributed architecture. Groupings are provided to simplify management tasks of devices for administrative or geographical reasons or for scalability.

•Access domain—The access domain object is associated with the provider access domain (PAD). Each PE-POP is assigned to an access domain.

•Device groups—Devices that are organized for collection and management purposes.

•Organization (Customer)— A requestor of VPN services from an Internet service provider (ISP).

•Site—A set of IP systems with mutual IP connectivity between them without the use of a VPN.

•Provider— An enterprise that provides internet services for customers.

•Region—A group of PE devices within a single border gateway protocol autonomous system (BGP AS).

•Collection zones—Collection servers are used to off load the work of the master server when the number of devices in the network increases. Network devices are associated with these collection servers using collection zones.

Table 3-4 shows the groupings as inventory objects.

Session

Sessions are specialized API operations. Prime Fulfillment supports the following session operations:

•createSession—Login

•deleteSession—Logout

The first XML request sent by the client is a login request. The login request generates a session ID, which is used each time you access the system. The session ID is valid for a configurable period of time. During this time, you can make an indefinite amount of calls to the server, using the session ID for authentication. Each call to the server resets the time-to-live (ttl) time back to the original period of time. The default session time is 20 minutes.

The API license is global to the installation and is checked at the start of each session. If the API license does not exist, the session is not granted. During the session, if a user attempts to provision a service that is not licensed, an error is returned.

The following example shows the XML response to a login request. The SessionId is indicated in bold.

<?xml version="1.0" encoding="UTF-8"?>

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:ns0="http://www.cisco.com/cim-cx/2.0" xmlns:ns1="urn:CIM">

  <soapenv:Header>

    <ns0:message id="87855" timestamp="2003-10-10T19:43:16.380Z" 
sessiontoken="93E0A400406693604270C6B6A07731A4" />

  </soapenv:Header>

  <soapenv:Body>

    <ns1:createSessionResponse>

      <returns xsi:type="ns1:CIMPropertyList" soapenc:arrayType="ns1:CIMProperty[]">

        <item xsi:type="ns1:CIMProperty">

          <name xsi:type="xsd:string">SessionId</name>

          <value xsi:type="xsd:string">93E0A400406693604270C6B6A07731A4</value>

        </item>

      </returns>

    </ns1:createSessionResponse>

  </soapenv:Body>

</soapenv:Envelope>

Tasks

Task APIs are used for auditing, deployment, and collection activities. Tasks follow the same service order/service request structure as other Prime Fulfillment services, where the service request is executed as part of a service order.

•For device-related tasks (Collection and SLA Collection), you must enter the device or device group.

•For service request-related tasks (Certificate Enrollment Audit, Configuration Audit, Service Deployment, and MPLS Functional Audits), you must enter the service request Locator ID.

Tasks are scheduled using the DesiredDueDate field in the service request or service order. A task with a DesiredDueDate that is in the past, or within 5 minutes of the current time, is executed immediately. Tasks with due dates in the future are scheduled.

Prime Fulfillment uses the following guidelines for DesiredDueDate

•If there is no due date in the service request, the task uses the service order due date.

•If there is a date in the service request, the service request due date overrides the service order due date for that particular task.

•If there is no due date specified in the service order or the service request, the service is not deployed.

Tasks can be created, deleted, and viewed using the API. However, you can only modify the DesiredDueDate field in a Task.

All Tasks are deployed using a service order that specifies a service request with Type=Task.

Viewing a Task

To obtain information about task service requests, run a view of the task (ViewTask.xml), using the TaskLocatorId.

Use this process to retrieve the TaskLocatorId:

Step 1 Record the service order LocatorId that is returned in the XML response.

When you submit a service order XML request for any task, Prime Fulfillment returns a LocatorId in the XML response. This Locator ID is associated with the service order or request Name.

Step 2 Run a view of the service order using ViewServiceOrder.xml, and the LocatorId from Step 1.

Step 3 Record the TaskLocatorId that is returned in the XML response.

Step 4 Run a view of the Task using ViewTask.xml. Specify className=PersistentTask and use the TaskLocatorId from Step 3.

The API supports the following tasks:

•Certificate Enrollment Audit

•Collection

•Service Decommission

•Configuration Audit

•Service Deployment

•MPLS Functional Audit

•MPLS Functional Audit

•SLA Collection

Certificate Enrollment Audit

A certificate enrollment audit is performed on devices to verify the certificates issued to them by a certificate authority (CA).

A certificate enrollment audit does the following:

•Verifies the certificates issued by the CA to a device or device groups.

•Confirms the presence of the root certificate and device certificate for the certificate chain of the specified trust point.

•Returns a summary that indicates the certificate enrollment status and expiration status on the audited devices.

Collection

A collection operation collects configuration information from network devices and serves the following purposes:

•It loads the current configuration information for the devices that populate many of the configuration cells.

•It verifies reachability and passwords for the devices from which it collects configuration files.

Tip Performing a device collection on your network is more accurate and efficient than manually entering individual device information.

Service Decommission

Decommissioning a service request removes a service from all devices associated with the service request.

Note To decommission a service request that includes templates, you must first negate the template information on the device. See the "Removing Template Configurations" section for more information.

During the decommission process, Prime Fulfillment creates the necessary removal configuration to delete the service from each device and automatically audits the configuration to ensure that the service is completely removed. Once audited, the service request changes to a Closed state.

If you do not want the configuration audit to occur, change the value for the Audit parameter. The Audit parameter supports these values:

•Audit—This is the default. A successfully deployed decommission service request is automatically audited unless this flag is changed.

•NoAudit—Do not perform a configuration audit when the decommission service request is deployed.

•ForceAudit—Perform a configuration audit even if the deployment of the decommission service request is not successful.

Configuration Audit

A configuration audit is executed as part of a service request deployment. During a configuration audit, Prime Fulfillment verifies that all Cisco IOS commands are present and that they have the correct syntax. A configuration audit also verifies that there were no errors during service deployment.

Service Deployment

A service deployment downloads the Prime Fulfillment-generated configlet, created for a service order, to the device configuration file.

You can specify the following options for service deployment:

•ForceDeploy—Takes a configlet for a service request that is already in the Deployed state and downloads it to the network device. Use ForceDeploy when a device configuration is lost or when you replace or change equipment.

MPLS Functional Audit

An MPLS functional audit verifies that the links in a service request or VPN are working correctly. The audit checks the routes to remote CPE devices in the VRF route tables on the PE devices.

SLA Collection

Prime Fulfillment uses the Cisco SA Agent MIB to monitor service level agreement (SLA) metrics. SLAs monitor the network performance by measuring response time, jitter, connect time, throughput, and packet loss. The SA Agent allows you to configure probes for performance measurements and uses a router monitor (RTRMON) MIB for access through SNMP. The MIB also supports SNMP notifications.

An SLA collection task collects all SLA data from SLA-enabled devices. Prime Fulfillment collects the relevant performance data and stores it persistently in the database. To view the data, you must execute a task to aggregate the data and run the SLA Report.

Note To collect SLA data from a device, it must have SA Agent and SNMP enabled, and SNMP parameters must already be set.

SLA collection includes performance data on Jitter (voice jitter) and the following protocols:

•Dynamic Host Configuration Protocol (DHCP)

•Domain Name System (DNS)

•File Transfer Protocol (FTP)

•Internet Control Message Protocol Echo (ICMP Echo)

•Transmission Control Protocol Connect (TCP Connect)

•User Datagram Protocol Echo (UDP Echo)

•Hypertext Transfer Protocol (HTTP)

General Purpose APIs

The following general purpose API XML examples are provided with Prime Fulfillment:

•CreateConfigServiceOrderDownload—Creates a service order to download an inline configuration to a device.

•Create Inventory—Can be used to populate a database with sample inventory and is commonly used for testing or demonstration. The service order adds one type of each inventory element to the repository and enters the host name, domain name, management IP address, and the login and password for each device.

•CreateNPCInventory—Creates several physical links in a network, including the source and destination devices and relevant interfaces.

•CreateExecCommandServiceOrder—Creates a service order to execute a command on a device or device group. You can execute any command allowed by the device console.

•CreateServiceOrderResponse—Returns the following values for a service order:

–ServiceName (for the service order)

–ServiceRequestName

–LocatorId (for the service request)

•CreateSLAInventory—Can be used to populate a database with sample inventory and is commonly used for testing. The service order adds the host name, domain name, and SLA data to devices in device groups.

•CreateResourceLock_Device, CreateResourceLock_Device_Batch, CreateResourceUnlock_Device, ViewResourceLock_Device—See the "Device Locking" section.

•DeleteServiceOrder—Deletes a service order.

•DeleteServiceOrder_purge—Deletes a service request of a specified subtype (Type = L2VPN, Mpls), with a given Locator ID and Force=true.

•ViewConfiglet—View the Prime Fulfillment generated configlet for a specified service request. Returns the ViewConfigletResponse.

•ViewConfigletResponse—Returns the following values:

–ConfigletClob

–LocatorId

–Device

–ConfigletText—Contains the configlet.

•ViewConfiguration—View the configuration of a specified device. Returns the ViewConfigurationResponse.

•ViewConfigurationResponse—Returns the following values:

–LocatorId

–Device

–DeviceConfig—Contains the device configuration.

•ViewCpe_propList_level—Provides a sample of a properties list and level usage. Returns the ViewCpe_propList_level_Response.

•ViewCpe_propList_level_Response—Returns the following values:

–LocatorId

–Site

–Device

•ViewMPLSServiceRequest_propList_level—Provides a sample of a properties list and level usage. Returns the ViewMPLSServiceRequest_propList_level_Response.

•ViewMPLSServiceRequest_propList_level_Response—Returns the following values:

–OpType (operation type; ADD or DELETE)

–LocatorId

–MplsVpnLink (and link attributes)

–CERCMembership

•ViewServiceOrder—View the status of any service order, with a given service order name or Locator ID. If the service order employs a task, the task locator ID is returned. The TaskLocatorId is required to view a task service order (ViewTask).

Date/Time Format in API Requests

For all API requests where the date and time needs to be specified, the zulu format is used. Zulu is the military designation for "Greenwich Mean Time."

Use the following format: 2011-03-17T15:05:38.885Z

Local time cannot be specified. Therefore, outside the UK any time difference has to be taken into consideration.

In the current format, the desired due date has to be followed by "Z", which means that the task will be executed one hour after the specified date.

So for example, when the clock is moved back one hour in the UK in October, the Zulu time will be equal to the UK time.