Cisco ACNS Software API Guide Copyright Cisco Systems, Inc. All rights reserved.

Transcription

1 Cisco ACNS Software API Guide Release 5.5 Corporate Headquarters Cisco Systems, Inc. 170 West Tasman Drive San Jose, CA USA Tel: NETS (6387) Fax: Text Part Number:

2 THE SPECIFICATIONS AND INFORMATION REGARDING THE PRODUCTS IN THIS MANUAL ARE SUBJECT TO CHANGE WITHOUT NOTICE. ALL STATEMENTS, INFORMATION, AND RECOMMENDATIONS IN THIS MANUAL ARE BELIEVED TO BE ACCURATE BUT ARE PRESENTED WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. USERS MUST TAKE FULL RESPONSIBILITY FOR THEIR APPLICATION OF ANY PRODUCTS. THE SOFTWARE LICENSE AND LIMITED WARRANTY FOR THE ACCOMPANYING PRODUCT ARE SET FORTH IN THE INFORMATION PACKET THAT SHIPPED WITH THE PRODUCT AND ARE INCORPORATED HEREIN BY THIS REFERENCE. IF YOU ARE UNABLE TO LOCATE THE SOFTWARE LICENSE OR LIMITED WARRANTY, CONTACT YOUR CISCO REPRESENTATIVE FOR A COPY. The Cisco implementation of TCP header compression is an adaptation of a program developed by the University of California, Berkeley (UCB) as part of UCB s public domain version of the UNIX operating system. All rights reserved. Copyright 1981, Regents of the University of California. NOTWITHSTANDING ANY OTHER WARRANTY HEREIN, ALL DOCUMENT FILES AND SOFTWARE OF THESE SUPPLIERS ARE PROVIDED AS IS WITH ALL FAULTS. CISCO AND THE ABOVE-NAMED SUPPLIERS DISCLAIM ALL WARRANTIES, EXPRESSED OR IMPLIED, INCLUDING, WITHOUT LIMITATION, THOSE OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OR ARISING FROM A COURSE OF DEALING, USAGE, OR TRADE PRACTICE. IN NO EVENT SHALL CISCO OR ITS SUPPLIERS BE LIABLE FOR ANY INDIRECT, SPECIAL, CONSEQUENTIAL, OR INCIDENTAL DAMAGES, INCLUDING, WITHOUT LIMITATION, LOST PROFITS OR LOSS OR DAMAGE TO DATA ARISING OUT OF THE USE OR INABILITY TO USE THIS MANUAL, EVEN IF CISCO OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. CCSP, CCVP, the Cisco Square Bridge logo, Follow Me Browsing, and StackWise are trademarks of Cisco Systems, Inc.; Changing the Way We Work, Live, Play, and Learn, and iquick Study are service marks of Cisco Systems, Inc.; and Access Registrar, Aironet, BPX, Catalyst, CCDA, CCDP, CCIE, CCIP, CCNA, CCNP, Cisco, the Cisco Certified Internetwork Expert logo, Cisco IOS, Cisco Press, Cisco Systems, Cisco Systems Capital, the Cisco Systems logo, Cisco Unity, Enterprise/Solver, EtherChannel, EtherFast, EtherSwitch, Fast Step, FormShare, GigaDrive, GigaStack, HomeLink, Internet Quotient, IOS, IP/TV, iq Expertise, the iq logo, iq Net Readiness Scorecard, LightStream, Linksys, MeetingPlace, MGX, the Networkers logo, Networking Academy, Network Registrar, Packet, PIX, Post-Routing, Pre-Routing, ProConnect, RateMUX, ScriptShare, SlideCast, SMARTnet, The Fastest Way to Increase Your Internet Quotient, and TransPath are registered trademarks of Cisco Systems, Inc. and/or its affiliates in the United States and certain other countries. All other trademarks mentioned in this document or Website are the property of their respective owners. The use of the word partner does not imply a partnership relationship between Cisco and any other company. (0601R) Cisco ACNS Software API Guide Copyright Cisco Systems, Inc. All rights reserved.

3 CONTENTS Preface vii Audience vii Document Organization vii Document Conventions viii Additional Documentation ix Obtaining Documentation ix Cisco.com ix Product Documentation DVD ix Ordering Documentation x Documentation Feedback x Cisco Product Security Overview x Reporting Security Problems in Cisco Products xi Obtaining Technical Assistance xi Cisco Technical Support & Documentation Website Submitting a Service Request xii Definitions of Service Request Severity xii Obtaining Additional Publications and Information xiii xii CHAPTER 1 Introduction to Cisco ACNS Software APIs 1-1 Calling the APIs 1-2 Interactive Calls 1-2 Programmed Calls 1-3 Sample Java Program 1-3 API Error Messages 1-6 API Tasks 1-8 Replication Status API 1-8 Provisioning APIs 1-8 Channel Provisioning API 1-8 Location Provisioning API 1-9 Content Engine Provisioning API 1-9 Program API 1-9 Listing API 1-10 Statistics API 1-10 Monitoring Statistics API 1-10 iii

4 Contents Streaming Statistics API 1-10 CHAPTER 2 Replication Status API 2-1 Replication Status API Actions 2-1 getchannels 2-1 getcesofchannel 2-2 getchannelsofce 2-2 getreplicatedcontent 2-2 getnonreplicatedcontent 2-3 getcontent 2-4 getstatusofcontentitems 2-4 getstatusofcontentiteminchannel 2-5 XML Formatted Output 2-5 CHAPTER 3 Provisioning APIs 3-1 Channel Provisioning API Actions 3-1 createchannel 3-2 addmanifest 3-3 assignces 3-3 assigndgs 3-4 fetchnow 3-5 modifychannel 3-5 modifymanifest 3-6 unassignces 3-7 unassigndgs 3-8 deletechannels 3-8 createcontentprovider 3-9 modifycontentprovider 3-9 deletecontentprovider 3-10 createwebsite 3-10 modifywebsite 3-10 deletewebsites 3-11 Location Provisioning API Actions 3-11 createlocation 3-12 modifylocation 3-12 deletelocation 3-12 Content Engine Provisioning API Actions 3-13 activatece 3-13 changecelocation 3-13 iv

5 Contents deletece 3-14 contentroutingquery 3-14 Program API Actions 3-15 createprogram 3-15 validateprogramfile 3-16 assignchannel 3-16 assignces 3-17 assigndgs 3-17 fetchnow 3-18 modifyprogramfile 3-18 unassignchannel 3-19 unassignces 3-19 unassigndgs 3-20 deleteprograms 3-20 startsession 3-20 pausesession 3-21 stopsession 3-21 CHAPTER 4 Listing API 4-1 Listing API Actions 4-1 getwebsites 4-1 getchannels 4-2 getces 4-2 getclusters 4-2 getcontentproviders 4-3 getlocations 4-3 getdevicegroups 4-3 getdevicestatus 4-4 getobjectbyid 4-4 getobjectbyname 4-5 getprograms 4-5 getpgmmcastaddrinuse 4-6 getmcastaddrinuse 4-6 getpgmmcastaddrrange 4-6 CHAPTER 5 Statistics APIs 5-1 Monitoring Statistics API 5-1 Monitoring Statistics API Actions 5-1 getcestats 5-1 v

6 Contents getlocationstats 5-2 getcdnstats 5-3 Streaming Statistics API 5-5 Streaming Statistics API Actions 5-5 gethttp 5-5 getciscostreaming 5-5 getwmt 5-6 getrealproxy 5-6 XML Formatted Output 5-6 APPENDIX A Program Files in ACNS Software A-1 Program File DTD A-2 Program File Examples A-7 WMT Multicast Live Event A-7 WMT Multicast Rebroadcast Event A-8 Cisco Streaming Engine Multicast Event A-9 Cisco Streaming Engine Live-Split Event A-9 I NDEX vi

7 Preface This preface describes who should read the Cisco ACNS Software API Guide, how it is organized, and its document conventions. It contains the following sections: Audience, page vii Document Organization, page vii Document Conventions, page viii Additional Documentation, page ix Obtaining Documentation, page ix Documentation Feedback, page x Obtaining Technical Assistance, page xi Obtaining Additional Publications and Information, page xiii Audience This application program interface (API) guide is written for the knowledgeable application programmer who understands the basic architecture of the Cisco ACNS software product and Java servlets. The user should be fluent in the Java programming language and have prior practical experience developing content networking solutions. This guide is not intended to direct the user in how to program in the Java language and limits itself to describing how related ACNS software servlets are used. Document Organization This API guide includes the following chapters: Chapter Title Description Chapter 1 Introduction to Cisco ACNS Software APIs Provides an introduction to the ACNS 5.5 software application program interfaces. Chapter 2 Replication Status API Describes the Replication Status API and the servlet actions it performs. vii

8 Document Conventions Preface Chapter Title Description Chapter 3 Provisioning APIs Describes the Channel Provisioning API, Location Provisioning API, Content Engine Provisioning API, and describes Program API and the servlet actions they perform. Chapter 4 Listing API Describes the Listing API and the servlet actions it performs. Chapter 5 Statistics APIs Describes the Monitoring and Streaming Statistics APIs and the servlet actions they perform. Appendix A Program Files in ACNS Software Describes the attributes of program files and examples for different program types. Document Conventions This API guide uses basic conventions to represent text and table information. Convention boldface font italic font screen font boldface screen font italic screen font plain font ^D or Ctrl-D string Description Commands, keywords, and button names are in boldface. Variables for which you supply values are in italics. Directory names and filenames are also in italics. Terminal sessions and information the system displays are printed in screen font. Information you must enter is in boldface screen font. Variables you enter are printed in italic screen font. Enter one of a range of options as listed in the syntax description. Hold the Ctrl key while you press the D key. Defined as a nonquoted set of characters. For example, when setting a community string for SNMP to public, do not use quotation marks around the string, or the string will include the quotation marks. vertical bars ( ) Vertical bars separate alternative, mutually exclusive, elements. { } Elements in braces are required elements. [ ] Elements in square brackets are optional. {x y z} Required keywords are grouped in braces and separated by vertical bars. [x y z] Optional keywords are grouped in brackets and separated by vertical bars. [{ }] Braces within square brackets indicate a required choice within an optional element. viii

9 Preface Additional Documentation Note Means reader take note. Notes contain helpful suggestions or references to materials not contained in the manual. Tip Means the following information will help you solve a problem. The tips information might not be troubleshooting or even an action, but could be useful information, similar to a Timesaver. Additional Documentation For additional information on Cisco Content Delivery Networking products, refer to the following documentation. Cisco ACNS Software Configuration Guide for Locally Managed Deployments, Release 5.5 Cisco ACNS Software Configuration Guide for Centrally Managed Deployments, Release 5.5 Cisco ACNS Software Migration Guide, Release 5.x Cisco ACNS Software Command Reference, Release 5.5 Release Notes for Cisco ACNS Software, Release 5.5 Obtaining Documentation Cisco documentation and additional literature are available on Cisco.com. Cisco also provides several ways to obtain technical assistance and other technical resources. These sections explain how to obtain technical information from Cisco Systems. Cisco.com You can access the most current Cisco documentation at this URL: You can access the Cisco website at this URL: You can access international Cisco websites at this URL: Product Documentation DVD The Product Documentation DVD is a comprehensive library of technical product documentation on a portable medium. The DVD enables you to access multiple versions of installation, configuration, and command guides for Cisco hardware and software products. With the DVD, you have access to the same HTML documentation that is found on the Cisco website without being connected to the Internet. Certain products also have.pdf versions of the documentation available. ix

10 Documentation Feedback Preface The Product Documentation DVD is available as a single unit or as a subscription. Registered Cisco.com users (Cisco direct customers) can order a Product Documentation DVD (product number DOC-DOCDVD= or DOC-DOCDVD=SUB) from Cisco Marketplace at this URL: Ordering Documentation Registered Cisco.com users may order Cisco documentation at the Product Documentation Store in the Cisco Marketplace at this URL: Nonregistered Cisco.com users can order technical documentation from 8:00 a.m. to 5:00 p.m. (0800 to 1700) PDT by calling in the United States and Canada, or elsewhere by calling You can also order documentation by at tech-doc-store-mkpl@external.cisco.com or by fax at in the United States and Canada, or elsewhere at Documentation Feedback You can rate and provide feedback about Cisco technical documents by completing the online feedback form that appears with the technical documents on Cisco.com. You can submit comments about Cisco documentation by using the response card (if present) behind the front cover of your document or by writing to the following address: Cisco Systems Attn: Customer Document Ordering 170 West Tasman Drive San Jose, CA We appreciate your comments. Cisco Product Security Overview Cisco provides a free online Security Vulnerability Policy portal at this URL: From this site, you will find information about how to: Report security vulnerabilities in Cisco products. Obtain assistance with security incidents that involve Cisco products. Register to receive security information from Cisco. A current list of security advisories, security notices, and security responses for Cisco products is available at this URL: x

11 Preface Obtaining Technical Assistance To see security advisories, security notices, and security responses as they are updated in real time, you can subscribe to the Product Security Incident Response Team Really Simple Syndication (PSIRT RSS) feed. Information about how to subscribe to the PSIRT RSS feed is found at this URL: Reporting Security Problems in Cisco Products Cisco is committed to delivering secure products. We test our products internally before we release them, and we strive to correct all vulnerabilities quickly. If you think that you have identified a vulnerability in a Cisco product, contact PSIRT: For Emergencies only security-alert@cisco.com An emergency is either a condition in which a system is under active attack or a condition for which a severe and urgent security vulnerability should be reported. All other conditions are considered nonemergencies. For Nonemergencies psirt@cisco.com In an emergency, you can also reach PSIRT by telephone: Tip We encourage you to use Pretty Good Privacy (PGP) or a compatible product (for example, GnuPG) to encrypt any sensitive information that you send to Cisco. PSIRT can work with information that has been encrypted with PGP versions 2.x through 9.x. Never use a revoked or an expired encryption key. The correct public key to use in your correspondence with PSIRT is the one linked in the Contact Summary section of the Security Vulnerability Policy page at this URL: The link on this page has the current PGP key ID in use. If you do not have or use PGP, contact PSIRT at the aforementioned addresses or phone numbers before sending any sensitive material to find other means of encrypting the data. Obtaining Technical Assistance Cisco Technical Support provides 24-hour-a-day award-winning technical assistance. The Cisco Technical Support & Documentation website on Cisco.com features extensive online support resources. In addition, if you have a valid Cisco service contract, Cisco Technical Assistance Center (TAC) engineers provide telephone support. If you do not have a valid Cisco service contract, contact your reseller. xi

12 Obtaining Technical Assistance Preface Cisco Technical Support & Documentation Website The Cisco Technical Support & Documentation website provides online documents and tools for troubleshooting and resolving technical issues with Cisco products and technologies. The website is available 24 hours a day, at this URL: Access to all tools on the Cisco Technical Support & Documentation website requires a Cisco.com user ID and password. If you have a valid service contract but do not have a user ID or password, you can register at this URL: Note Use the Cisco Product Identification (CPI) tool to locate your product serial number before submitting a web or phone request for service. You can access the CPI tool from the Cisco Technical Support & Documentation website by clicking the Tools & Resources link under Documentation & Tools. Choose Cisco Product Identification Tool from the Alphabetical Index drop-down list, or click the Cisco Product Identification Tool link under Alerts & RMAs. The CPI tool offers three search options: by product ID or model name; by tree view; or for certain products, by copying and pasting show command output. Search results show an illustration of your product with the serial number label location highlighted. Locate the serial number label on your product and record the information before placing a service call. Submitting a Service Request Using the online TAC Service Request Tool is the fastest way to open S3 and S4 service requests. (S3 and S4 service requests are those in which your network is minimally impaired or for which you require product information.) After you describe your situation, the TAC Service Request Tool provides recommended solutions. If your issue is not resolved using the recommended resources, your service request is assigned to a Cisco engineer. The TAC Service Request Tool is located at this URL: For S1 or S2 service requests, or if you do not have Internet access, contact the Cisco TAC by telephone. (S1 or S2 service requests are those in which your production network is down or severely degraded.) Cisco engineers are assigned immediately to S1 and S2 service requests to help keep your business operations running smoothly. To open a service request by telephone, use one of the following numbers: Asia-Pacific: (Australia: ) EMEA: USA: For a complete list of Cisco TAC contacts, go to this URL: Definitions of Service Request Severity To ensure that all service requests are reported in a standard format, Cisco has established severity definitions. xii

13 Preface Obtaining Additional Publications and Information Severity 1 (S1) An existing network is down, or there is a critical impact to your business operations. You and Cisco will commit all necessary resources around the clock to resolve the situation. Severity 2 (S2) Operation of an existing network is severely degraded, or significant aspects of your business operations are negatively affected by inadequate performance of Cisco products. You and Cisco will commit full-time resources during normal business hours to resolve the situation. Severity 3 (S3) Operational performance of the network is impaired, while most business operations remain functional. You and Cisco will commit resources during normal business hours to restore service to satisfactory levels. Severity 4 (S4) You require information or assistance with Cisco product capabilities, installation, or configuration. There is little or no effect on your business operations. Obtaining Additional Publications and Information Information about Cisco products, technologies, and network solutions is available from various online and printed sources. The Cisco Product Quick Reference Guide is a handy, compact reference tool that includes brief product overviews, key features, sample part numbers, and abbreviated technical specifications for many Cisco products that are sold through channel partners. It is updated twice a year and includes the latest Cisco offerings. To order and find out more about the Cisco Product Quick Reference Guide, go to this URL: Cisco Marketplace provides a variety of Cisco books, reference guides, documentation, and logo merchandise. Visit Cisco Marketplace, the company store, at this URL: Cisco Press publishes a wide range of general networking, training and certification titles. Both new and experienced users will benefit from these publications. For current Cisco Press titles and other information, go to Cisco Press at this URL: Packet magazine is the Cisco Systems technical user magazine for maximizing Internet and networking investments. Each quarter, Packet delivers coverage of the latest industry trends, technology breakthroughs, and Cisco products and solutions, as well as network deployment and troubleshooting tips, configuration examples, customer case studies, certification and training information, and links to scores of in-depth online resources. You can access Packet magazine at this URL: iq Magazine is the quarterly publication from Cisco Systems designed to help growing companies learn how they can use technology to increase revenue, streamline their business, and expand services. The publication identifies the challenges facing these companies and the technologies to help solve them, using real-world case studies and business strategies to help readers make sound technology investment decisions. You can access iq Magazine at this URL: or view the digital edition at this URL: xiii

14 Obtaining Additional Publications and Information Preface Internet Protocol Journal is a quarterly journal published by Cisco Systems for engineering professionals involved in designing, developing, and operating public and private internets and intranets. You can access the Internet Protocol Journal at this URL: Networking products offered by Cisco Systems, as well as customer support services, can be obtained at this URL: Networking Professionals Connection is an interactive website for networking professionals to share questions, suggestions, and information about networking products and technologies with Cisco experts and other networking professionals. Join a discussion at this URL: World-class networking training is available from Cisco. You can view current offerings at this URL: xiv

15 CHAPTER 1 Introduction to Cisco ACNS Software APIs Cisco Application and Content Networking System (ACNS) 5.5 software provides eight sets of application program interfaces (APIs): Replication Status Channel Provisioning Location Provisioning Content Engine Provisioning Program Listing Monitoring Statistics Streaming Statistics These HTTPS APIs are Java servlets whose return outputs are generated in XML format. ACNS 5.5 software uses these eight servlets to monitor and modify specified content acquisition and distribution parameters. Table 1-1 describes the eight APIs. In each case, a unique website and channel name must be provided to the API so that the channel can be located. Table 1-1 Cisco ACNS Software APIs API Replication Status Provisioning APIs Description s a list of channels, Content Engines, or contents, and for each channel, an indication whether replication of content for the specified channel is complete or not. Provides the Content Distribution Manager with ACNS channel, location, and Content Engine information. Channel Provisioning API Monitors and modifies ACNS network channels. Location Provisioning API Creates, modifies, or deletes an ACNS network location object. Content Engine Provisioning API Activates, locates, or deletes a specified Content Engine. Program API Creates, modifies, validates, or deletes programs, and assigns or unassigns Content Engines, device groups, and channels to programs. 1-1

16 Calling the APIs Chapter 1 Introduction to Cisco ACNS Software APIs Table 1-1 Cisco ACNS Software APIs (continued) API Listing API Monitoring Statistics API Streaming Statistics API 1. WMT = Windows Media Technologies Description Obtains object information from the local embedded database. Obtains monitoring statistics data about a single Content Engine or all the Content Engines in the ACNS network. Reports WMT 1, HTTP, RealProxy, and Cisco Streaming Engine data collected from the Content Engines or device groups and sends this data to the Content Distribution Manager. Data obtained with the Streaming Statistics API can be saved and a customized report generated. ACNS 5.5 software also provides authentication, authorization, and accounting (AAA) functions to support users who access external servers and local databases. Authentication verifies the identity and IP address of a user, authorization permits or denies access privileges for authenticated users in the ACNS network, and accounting logs authorized usage of network services. These AAA functions are enforced by the APIs so that user credentials must be validated before an API can be executed. This chapter contains the following sections: Calling the APIs, page 1-2 Sample Java Program, page 1-3 API Error Messages, page 1-6 API Tasks, page 1-8 Calling the APIs You can execute these ACNS 5.5 software APIs interactively or through a caller program. API calls must follow the correct syntax. If the user credential is invalid or the syntax is incorrect, the API is not executed. If a user error occurs, a warning is returned that explains the nature of the error along with the syntax of the particular API. Interactive Calls Use a browser or lynx command to execute the API interactively. The user is prompted to enter a username and password for authentication and authorization. Once the user is validated, the API is executed. If the execution is successful and an output is to be returned as a result, the output is displayed in the browser if a browser was used to make the API call, or the output can be redirected to a file if a lynx command was used to make the API call. If the execution is unsuccessful, an error message is returned. 1-2

17 Chapter 1 Introduction to Cisco ACNS Software APIs Sample Java Program Programmed Calls To make an API call, write a caller program using an HTTPS request. The username and password are set in the HTTPS request for AAA validation. If validation and execution are successful and an output is to be returned as a result, the output or a success code is returned. If the execution is unsuccessful, a failure code is returned. Sample Java Program The following is a sample Java client program that requires two Simple API for XML (SAX) parsing APIs. This sample code requires the org.xml.sax.* API and org.xml.sax.helpers.* API for the parser and the HTTPS URL package for the connection. public class Client { private static ApiParser parser_ = null; public static void main (String[] args) { parser_ = new ChannelApiServletParser(); HttpsUrlStreamHandlerFactory factory = new HttpsUrlStreamHandlerFactory(); factory.setseed("test seed".getbytes()); HttpsUrlStreamHandler handler = (HttpsUrlStreamHandler)factory.createURLStreamHandler("https"); String sauth = "admin:default"; String sencodedauth = new sun.misc.base64encoder().encode(sauth.getbytes()); Url url = new URL(null, " + cdmaddress_ + ":" + cdmport_ + "/servlet/" + "com.cisco.unicorn.ui.channelapiservlet?action=addmanifest" + "&channel=" + channelid_ + "&manifest= + "&quota=10&ttl=20&user=user&password=password", handler); } } HttpsUrlConnection conn = (HttpsUrlConnection)url.openConnection(); conn.setheadproperty("authorization: Basic " + sencodedauth); conn.setrequestmethod("get"); InputSource source = new InputSource(conn.getInputStream()); parser_.parse(source); This program requires the parser to parse the output; a sample parser looks like this: public class ApiParser extends DefaultHandler { private XMLReader adapter_ = null; private String status_ = null; private String message_ = null; private String syntax_ = null; private String action_ = null; private int count_ = 0; private HashMap channels_ = new HashMap(); private String thischannel_ = null; private ArrayList clusters_ = new ArrayList(); private ArrayList dgs_ = new ArrayList(); public ChannelApiServletParser() { String parsername = "org.apache.xerces.parsers.saxparser"; 1-3

18 Sample Java Program Chapter 1 Introduction to Cisco ACNS Software APIs } try { adapter_ = XMLReaderFactory.createXMLReader(parserName); adapter_.setcontenthandler(this); adapter_.seterrorhandler(this); adapter_.setentityresolver(this); adapter_.setdtdhandler(this); } catch(saxexception saxe) { GlobalErrorHandler.recoverable(saxe); } public void endelement (String auri, String alocalname, String aqname) throws SAXException { if (aqname.equals("record") && action_.equals("getchannels")) { HashMap channeldetails = (HashMap)channels_.get(thisChannel_); if (clusters_.size()!= 0) { channeldetails.put("clusters", clusters_); } if (dgs_.size()!= 0) { channeldetails.put("devicegroups", dgs_); } } } thischannel_ = null; clusters_ = new ArrayList(); dgs_ = new ArrayList(); return; public void parse(inputsource source) throws IOException, SAXException { adapter_.parse(source); } public void startelement(string auri, String alocalname, String aqname, Attributes anattributes) throws SAXException { if (aqname.equals("message")) { status_ = anattributes.getvalue("status"); message_ = anattributes.getvalue("message"); return; } if (aqname.equals("syntax")) { syntax_ = anattributes.getvalue("syntax"); return; } 1-4

19 Chapter 1 Introduction to Cisco ACNS Software APIs Sample Java Program if (aqname.equals("channelprovisioning")) { action_ = anattributes.getvalue("action"); return; } if (aqname.equals("listing")) { action_ = anattributes.getvalue("action"); } String countstring = anattributes.getvalue("count"); try { count_ = Integer.parseInt(countString); } catch (NumberFormatException nfe) {} return; if (aqname.equals("record")) { if (action_.equals("getchannels")) processchanneldetails(anattributes); } return; if (aqname.equals("entry")) { if (action_.equals("getchannels")) processassignmentdetails(anattributes); } } return; public HashMap getchannels() { return channels_; } public int getcount() { return count_; } public String getmessage() { return message_; } public String getstatus() { return status_; } private void processassignmentdetails(attributes anattributes) { String id = anattributes.getvalue("id"); if (id.startswith("cluster")) { clusters_.add(id); } 1-5

20 API Error Messages Chapter 1 Introduction to Cisco ACNS Software APIs } else if (id.startswith("device")) { dgs_.add(id); } private void processchanneldetails(attributes anattributes) { HashMap channeldetails = new HashMap(); String value = anattributes.getvalue("name"); channeldetails.put("name", value); value = anattributes.getvalue("websiteid"); channeldetails.put("websiteid", value); value = anattributes.getvalue("weakcertification"); channeldetails.put("weakcertification", value); value = anattributes.getvalue("skipencryption"); channeldetails.put("skipencryption", value); value = anattributes.getvalue("description"); channeldetails.put("description", value); value = anattributes.getvalue("manifesturl"); channeldetails.put("manifesturl", value); value = anattributes.getvalue("cachequota"); channeldetails.put("cachequota", value); value = anattributes.getvalue("manifestttl"); channeldetails.put("manifestttl", value); value = anattributes.getvalue("manifestuser"); channeldetails.put("manifestuser", value); value = anattributes.getvalue("manifestpassword"); channeldetails.put("manifestpassword", value); value = anattributes.getvalue("checkmanifest"); channeldetails.put("checkmanifest", value); value = anattributes.getvalue("rootce"); channeldetails.put("rootce", value); } } value = anattributes.getvalue("id"); channels_.put(value, channeldetails); thischannel_ = value; API Error Messages When a server error occurs while the APIs are invoked, an XML-formatted message is returned. For example, when Internal Server Error (500) occurs, the client sees the following output: <?xml version="1.0"?> <Error> <message status="fail" message="internal Server Error - 500"/> </Error> 1-6

21 Chapter 1 Introduction to Cisco ACNS Software APIs API Error Messages The following common errors are supported in the message syntax: Bad Request 400 Authorization Required 401 Forbidden 403 File Not Found 404 Request Timeout 408 Internal Server Error 500 Typically, APIs return error messages when API execution fails. If the execution is successful, APIs do not return any error messages. However, APIs may return warning messages even when the execution is successful. APIs use numeric error and warning codes. Table 1-2 describes the generic numeric codes used for errors and warnings. Table 1-3 describes the numeric codes for the Program API errors and warnings. Table 1-2 Numeric Codes for Errors and Warnings in APIs Error or Warning Code Description 0 None 1 error 2 Input error 3 Constraint error 4 Input warnings Table 1-3 Numeric Codes for Errors and Warnings in the Program API Error or Warning Code Description 101 Unable to fetch program file 102 Program file syntax error 103 Invalid value in program file 104 Related system error 105 Program file unused input - Warning For example, when you enter the following URL to execute an API to delete a selected type of program and no programs of that type exist: =type=tvout the API returns the following warning: <?xml version="1.0"?> <programapi action="deleteprograms"> <message status="success" message="the program(s) are deleted." /> <warning code="4" message="no Program(s) that matched the request were found" /> </programapi> 1-7

22 API Tasks Chapter 1 Introduction to Cisco ACNS Software APIs Similarly, when you enter the following URL to execute an API to delete a channel with invalid channel ID: Channel_333 the API returns the following error: <?xml version="1.0"?> <channelprovisioning action="deletechannels"> <message status="fail" message="input Error: Cannot locate channel using channel ID Channel_333" /> <error code="2" message="input Error: Cannot locate channel using channel ID Channel_333" /> </channelprovisioning> API Tasks The following sections provide a brief list of tasks performed by the Replication Status, Provisioning, Program, Listing, and Statistics APIs. Replication Status API The Replication Status API performs one or more of the following tasks when executed: Obtains the replication status of content on specified channels Obtains the replication status of content for all Content Engines assigned to the specified channel Obtains the replication status of content for all channels assigned to the specified Content Engine Lists all replicated items of a specified Content Engine on a specified channel, with or without search criteria Lists all nonreplicated items of a specified Content Engine on a specified channel, with or without search criteria Lists all content items of a Content Engine on a specified channel, with or without search criteria Provisioning APIs The Provisioning APIs include the Channel Provisioning API, Location Provisioning API, Content Engine Provisioning API, and Program API. Channel Provisioning API The Channel Provisioning API performs one or more of the following tasks when executed: Creates channels Adds a manifest file to a specified channel Assigns Content Engines to a specified channel Assigns device groups to a specified channel Immediately fetches the manifest file 1-8

23 Chapter 1 Introduction to Cisco ACNS Software APIs API Tasks Modifies channel settings Modifies manifest file settings Removes Content Engines from a specified channel Removes device groups from a specified channel Deletes channels Creates content providers Modifies content provider settings Deletes content providers Creates websites Modifies website settings Deletes website settings Location Provisioning API Content Engine Provisioning API Program API The Location Provisioning API performs one or more of the following tasks when executed: Creates a specified location Modifies a specified location Deletes a specified location The Content Engine Provisioning API performs one or more of the following tasks when executed: Activates a specified Content Engine Changes the location of a specified Content Engine Deletes a specified Content Engine The Program API performs one or more of the following tasks when executed: Creates a program file Validates a program file Assigns channels to a specified program Assigns Content Engines to a specified program Assigns device groups to a specified program Fetches a program file Modifies a program file Removes channels from a specified program Removes Content Engines from a specified program Removes device groups from a specified program 1-9

24 API Tasks Chapter 1 Introduction to Cisco ACNS Software APIs Listing API The Listing API performs one or more of the following tasks when executed: Lists selected website names and related content provider name or lists every website Lists selected channel names and related website ID or lists every channel Lists selected Content Engine names or lists every Content Engine Lists the location of the specified Content Engines Lists selected cluster names or lists every cluster Lists selected content provider names or lists every content provider Lists selected device group names or lists every device group Lists the status of a device or device group Lists an object, based on its string ID Lists an object, based on its name Lists all programs specified Lists all multicast addresses currently in use by programs Lists all multicast addresses currently in use Lists the multicast address range reserved for programs Statistics API The Statistics APIs include the Monitoring Statistics API and the Streaming Statistics API. Monitoring Statistics API Streaming Statistics API The Monitoring Statistics API performs one or more of the following tasks when executed: Obtains monitoring statistics for each Content Engine Obtains monitoring statistics for all the Content Engines in a location Obtains monitoring statistics for all the Content Engines in the ACNS network The Streaming Statistics API performs one or more of the following tasks when executed: Reports HTTP statistics for each Content Engine or device group Reports Cisco Streaming Engine statistics for each Content Engine or device group Reports WMT statistics for each Content Engine or device group Reports RealProxy statistics for each Content Engine or device group 1-10

25 CHAPTER 2 Replication Status API This chapter describes the Replication Status API and the servlet actions it performs. The Replication Status API returns a list of channels, Content Engines, or contents, and for each channel, an indication whether replication of content for the specified channel is complete or not. Replication Status API Actions The Replication Status API is the ReplicationStatusApiServlet. This servlet performs one or more of the following actions: getchannels getcesofchannel getchannelsofce getreplicatedcontent getnonreplicatedcontent getcontent getstatusofcontentitems getstatusofcontentiteminchannel getchannels Obtains the status of content replication of specified channels. Either a list of channel IDs or the keyword all is required. A list of the channels, and for each channel, a flag whether replication for the specified channel is complete or incomplete. 2-1

26 Replication Status API Actions Chapter 2 Replication Status API action=getchannels&channel=[all <channel_id>,<channel_id>, ] getcesofchannel Obtains the status of content replication for all Content Engines assigned to the specified channel. Channel ID (required). Refetch (optional) The default is false. If refetch is set to true, a background request to obtain a newly updated status is sent to all Content Engines assigned to this channel. To view the newly available information, the user must call the API again after several minutes without a refetch. A list of all Content Engines assigned to a specified channel and, for each specified Content Engine, a flag whether replication for the specified Content Engine is complete or incomplete. action=getcesofchannel&channel=<channel_id>[&refetch=<true false>] getchannelsofce Obtains the status of content replication for all channels assigned to the specified Content Engine. Content Engine ID (required). Refetch (optional) The default is false. If refetch is set to true, a background request to obtain a newly updated status is sent to all Content Engines assigned to this channel. To view the newly available information, the user must call the API again after several minutes without a refetch. A list of all channels assigned to a specified Content Engine and, for each channel, a flag whether replication for the specified channel is complete or incomplete. action=getchannelsofce&ce=<ce_id>[&refetch=<true false>] getreplicatedcontent Lists all replicated items of a specified Content Engine on a specified channel, with or without search criteria. 2-2

27 Chapter 2 Replication Status API Replication Status API Actions Content Engine ID (required). Channel ID (required). Search criteria (optional). One or more content names or patterns must each be separated by a comma. Patterns can contain the wildcards * or?. Refetch (optional) The default is false. If refetch is set to true, a background request to retrieve the content is issued. The updated information is cached on the Content Distribution Manager and can be retrieved in the next call. A list of all replicated content items on a specified Content Engine for a specified channel that matches the search criteria, if the search criteria have been specified. action=getreplicatedcontent&ce=<ce_id>&channel=<channel_id>[&criteria=<criteria>] [&refetch=<true false>] getnonreplicatedcontent Lists all nonreplicated items of a specified Content Engine on a specified channel, with or without search criteria. Content Engine ID (required). Channel ID (required). Search criteria (optional). One or more content names or patterns, each separated by a comma. Patterns can contain the wildcards * or?. Refetch (optional) The default is false. If refetch is set to true, a background request to retrieve the content is issued. The updated information is cached in the Content Distribution Manager and can be retrieved in the next call. A list of all content items that are not replicated on a specified Content Engine of a specified channel that matches the search criteria, if search criteria have been specified. The list includes content items that are yet to be replicated, in the process of being replicated, or have failed to be replicated. action=getnonreplicatedcontent&ce=<ce_id>&channel=<channel_id>[&criteria=<criteria>] [&refetch=<true false>] 2-3

28 Replication Status API Actions Chapter 2 Replication Status API getcontent Lists all content items of a Content Engine on a specified channel, with or without search criteria. Content Engine ID (required). Channel ID (required). Search criteria (optional). One or more content names or patterns must each be separated by a comma. Patterns can contain the wildcards * or?. Refetch (optional) The default is false. If refetch is set to true, a background request to retrieve the content is issued. The updated information is cached on the Content Distribution Manager and can be retrieved in the next call. A list of all content items on the Content Engine of a specified channel that matches the specified criteria, if search criteria have been specified. getcontent&ce=<ce_id>&channel=<channel_id>[&criteria=<criteria>][&refetch=<true false>] getstatusofcontentitems Lists content items of a channel, with or without search criteria, in all the Content Engines assigned to that channel. Channel ID (required) Search criteria (optional) One or more content names or patterns, each separated by a comma. Patterns can contain the wildcards * or?. Refetch (optional) The default is false. If refetch is set to true, a background request to retrieve the content is issued. The updated information is cached in the Content Distribution Manager and can be retrieved in the next call. Note When refetch is set to true, the request is sent to the Content Engines assigned to the channel to obtain new information. This is a processor-intensive operation. A list of all content items in the channel and their status across Content Engines, or a list of content items that matches the specified criteria and their status across Content Engines, if search criteria have been specified. 2-4

29 Chapter 2 Replication Status API XML Formatted Output getstatusofcontentitems&channel=<channel_id>[&criteria=<criteria>][&refetch=<true false>] getstatusofcontentiteminchannel Lists the status of a specified content item in the channel on all the Content Engines assigned to the channel. Channel ID (required) Complete URL of the content item (required) The status of the specified content item on all the Content Engines assigned to the channel. Note This action must be called after the getstatusofcontentitems action; otherwise, unexpected output results. The URL must be one of the URLs listed in the output of the getstatusofcontentitems action. getstatusofcontentiteminchannel&channel=<channel_id>&criteria=<complete URL of the channel content item> XML Formatted Output The following is the Document Type Definition (DTD) of the XML-formatted output: <?xml version="1.0"?> <!DOCTYPE replicationstatus[ <!ELEMENT replicationstatus (message, CeStatus*, ChannelStatus*)> <!ATTLIST replicationstatus action CDATA #REQUIRED count CDATA #REQUIRED > <!ELEMENT message EMPTY> <!ATTLIST message status (success failure) "success" message CDATA #REQUIRED > <!ELEMENT CeStatus EMPTY> <!ATTLIST CeStatus ceid CDATA #REQUIRED cename CDATA #IMPLIED channelid CDATA #REQUIRED channelname CDATA #IMPLIED state CDATA #IMPLIED filesdone CDATA #IMPLIED filestodo CDATA #IMPLIED filesfailed CDATA #IMPLIED filesupdatefailed CDATA #IMPLIED 2-5

30 XML Formatted Output Chapter 2 Replication Status API totalfiles CDATA #IMPLIED updatetime CDATA #IMPLIED > <!ELEMENT ChannelStatus EMPTY> <!ATTLIST ChannelStatus id CDATA #REQUIRED totalnumces CDATA #REQUIRED numcescomplete CDATA #REQUIRED numcesinprocess CDATA #REQUIRED numcesfailed CDATA #REQUIRED numcesunknownstate CDATA #REQUIRED rootcestate CDATA #REQUIRED manifesterror CDATA #IMPLIED useddiskquota CDATA #IMPLIED validasof CDATA #IMPLIED > 2-6

31 CHAPTER 3 Provisioning APIs This chapter describes the Channel Provisioning API, Location Provisioning API, Content Engine Provisioning API, and Program API and the servlet actions they perform. This chapter contains the following sections: Channel Provisioning API Actions, page 3-1 Location Provisioning API Actions, page 3-11 Content Engine Provisioning API Actions, page 3-13 Program API Actions, page 3-15 Channel Provisioning API Actions The Channel Provisioning API is the ChannelApiServlet. This servlet performs one or more of the following actions: createchannel addmanifest assignces assigndgs fetchnow modifychannel modifymanifest unassignces unassigndgs deletechannels createcontentprovider modifycontentprovider deletecontentprovider createwebsite 3-1

32 Channel Provisioning API Actions Chapter 3 Provisioning APIs modifywebsite deletewebsites createchannel Creates a channel. Channel name (required). Website ID associated with the specified channel (required). Weak certification (optional) The default is false. Skip encryption (optional) The default is false. Channel priority (optional) The default is normal. The settings are: High Normal Low Multicast enable (optional) The default is false. The settings are: true unicast only false unicast and multicast unicast_only unicast only multicast_only multicast only unicast_multicast unicast and multicast Channel description (optional) The default is null. Live (optional) The default is false. The newly created channel ID. Note ACNS 5.3 software does not provide an API to create and assign a channel to a multicast cloud. Use the Content Distribution Manager GUI to assign a channel to a multicast cloud. &channel=<channel_name>&website=<website_id>[&weakcert=<true false>][&skipencrypt= <true false>][&priority=<high normal low>][&mcastenable=<true false unicast_only multicast_only unicast_multicast>][&desc=<description>][&live=<true false>] 3-2

33 Chapter 3 Provisioning APIs Channel Provisioning API Actions addmanifest Adds a manifest file to a specified channel. Channel ID (required). Manifest URL (required). Quota (required). TTL (required) in minutes. User ID (optional). User password (optional). User domain name (optional). Not basic authentication (optional) The default is false. No proxy (optional) The default is false. Proxy IP address or host name (optional). Proxy port (optional). Proxy username (optional). Proxy password (optional). Proxy NTLM user domain name (optional). Proxy not basic authentication (optional) The default is false. The updated channel record. channel=<channel_id>&manifest=<manifest_url>&quota=<quota>&ttl=<ttl>[&user= <user_name>][&password=<password>][&userdomainname=<user_domain_name>] [&notbasicauth=<true false>][&noproxy=<true false>][&proxyiphostname=<proxy_ip_hostname>] [&proxyport=<proxy_port>][&proxyuser=<proxy_user>][&proxypassword=<proxy_password>] [&proxyntlmuserdomainname=<proxy_ntlm_user_domain_name>][&proxynotbasicauth= <true false>] assignces Assigns Content Engines to a specified channel. This action need not be used if the assignchannel action has already been used. If a channel has already been assigned to a program, the assignces action executes successfully but returns a warning message. Channel ID (required). Root Content Engine ID (required if no root Content Engine is assigned; otherwise, this parameter is optional). 3-3

34 Channel Provisioning API Actions Chapter 3 Provisioning APIs Either a list of Content Engines or the keyword all (see the following rules). Either a list of clusters or the keyword all (see the following rules). Rules If a Content Engine parameter list is set to all, a cluster list cannot be specified. If the cluster list is set to all, a Content Engine list cannot be specified. Both a Content Engine list and a cluster list cannot be set to all at the same time. If these rules are violated, an error message is returned. None. Note The Content Engine and cluster form a one-to-one relationship. A cluster is considered a wrapper around the Content Engine. When assigning the Content Engine, specify one of the following options: List of Content Engines All Content Engines List of clusters All clusters List of Content Engines and clusters channel=<channel_id>[&rootce=<root_ce_id>][&ce=all <CE_ID>,<CE_ID>, ][&cluster=all <Cluster_ID>,<Cluster_ID>, ] assigndgs Assigns device groups (DGs) to a specified channel. This action need not be used if the assignchannel action has already been used. If a channel has already been assigned to a program, the assigndgs action executes successfully but returns a warning message. Channel ID (required) Root Content Engine ID (required if no root Content Engine is assigned; otherwise, this parameter is optional) List of device groups (required) Note You cannot use the keyword all because some device groups may not contain Content Engines. 3-4

35 Chapter 3 Provisioning APIs Channel Provisioning API Actions None. channel=<channel_id>[&rootce=<root_ce_id>]&dg=<dg_id>,<dg_id>, fetchnow Immediately fetches the manifest file. Generally, the ttl (Time-to-Live) value of the manifest is set to a reasonable value, such as 30 minutes. This servlet forces a freshness check of the manifest file before the normal Time-to-live interval expires on the channel specified. If the freshness check indicates that changes to the manifest file have occurred, the manifest file is parsed and the content processed. If you want the changes to the manifest file to be processed immediately, use the fetchnow action. Channel ID (required). None. channel=<channel_id> modifychannel Modifies channel settings. Channel ID (required) Name of the channel (optional) Weak certification (optional) Skip encryption (optional) Channel priority (optional) The settings are: High Normal Low Multicast enable (optional) The settings are: true unicast only 3-5

36 Channel Provisioning API Actions Chapter 3 Provisioning APIs false unicast and multicast unicast_only unicast only multicast_only multicast only unicast_multicast unicast and multicast Description (optional) Live (optional) Note If a parameter is not specified, no change is made to the original channel settings. The updated channel record. &channel=<channel_id>[&channelname=<channel_name>][&weakcert=<true false>] [&skipencrypt=<true false>][&priority=<high normal low>][&mcastenable=<true false> unicast_only multicast_only unicast_multicast][&desc=<description>][&live=<true false>] modifymanifest Modifies manifest file settings. Channel ID (required). Manifest URL (optional). Quota (optional). TTL (optional). User ID (optional). User password (optional). NTLM user domain name (optional). Not basic authentication (optional) The default is false. No proxy (optional) The default is false. Proxy IP address or host name (optional). Proxy port (optional). Proxy username (optional). Proxy password (optional). Proxy NTLM user domain name (optional). Proxy not basic authentication (optional) The default is false. 3-6

37 Chapter 3 Provisioning APIs Channel Provisioning API Actions Note If a parameter value is not specified, no change is made to the original manifest file setting. If the parameter values need to be removed, use the empty string mechanism to delete an existing setting. For example, if a manifest was originally set for a channel and you now want to remove that manifest from the channel, set the manifest parameter to an empty string (manifest= ) when using the modifymanifest action. Setting a manifest URL to null removes all the other settings. The updated channel record. modifymanifest&channel=<channel_id>[&manifest=<manifest_url>][&quota=<quota>] [&ttl=<ttl>][&user=<user_name>][&password=<password>][&userdomainname= <user_domain_name>][&notbasicauth=<true false>][&noproxy=<true false>] [&proxyiphostname=<proxy_ip_hostname>][&proxyport=<proxy_port>][&proxyuser= <proxy_user>][&proxypassword=<proxy_password>][&proxyntlmuserdomainname= <proxy_ntlm_user_domain_name>][&proxynotbasicauth=<true false>] unassignces Removes Content Engines from a specified channel. This action need not be used if the unassignchannel action has already been used. If a channel has already been assigned to a program, the unassignces action executes successfully but returns a warning message. Channel ID (required). Either a list of Content Engines or the keyword all is required (see the following rules). Either a list of clusters or the keyword all is required (see the following rules). Rules If a Content Engine list is set to all, a cluster list cannot be specified. If a cluster list is set to all, a Content Engine list cannot be specified. Both a Content Engine list and a cluster list cannot be set to all at the same time. If these rules are violated, an error message is returned. None. Note The Content Engine and cluster form a one-to-one relationship. A cluster is considered a wrapper around the Content Engine. 3-7

38 Channel Provisioning API Actions Chapter 3 Provisioning APIs When removing the Content Engine from the channel, specify one of the following options: List of Content Engines All Content Engines List of clusters All clusters List of Content Engines and clusters channel=<channel_id>[&ce=all <CE_ID>, <CE_ID> ][&cluster=all <Cluster_ID>, <Cluster_ID>, ] unassigndgs Removes device groups from a specified channel. This action need not be used if the unassignchannel action has already been used. If a channel has already been removed from a program, the unassigndgs action executes successfully but returns a warning message. Channel ID (required). Either a list of device groups or the keyword all is required. None. channel=<channel_id>&dg=all <DG_ID>, <DG_ID>, deletechannels Deletes channels. Either a list of channels or the keyword all is required. None. &channel=all <channel_id>, <channel_id> 3-8

39 Chapter 3 Provisioning APIs Channel Provisioning API Actions createcontentprovider Creates a content provider. Content provider name (required) Description (optional) Primary contact name (optional) Primary contact phone (optional) Primary contact (optional) A confirmation that a new content provider has been created and contact information for the newly created content provider has been saved. createcontentprovider&name=<content_provider_name>[&description=<description>] [&contactname=<primary_contact_name>][&contactphone=<primary_contact_phone>] [&contact =<primary_contact_ >] modifycontentprovider Modifies content provider settings. Content provider ID (required) Content provider name (optional) Description (optional) Primary contact name (optional) Primary contact phone (optional) Primary contact (optional) A confirmation that settings for a content provider have been modified and an updated record for the content provider. modifycontentprovider&cp=<content_provider_id>[&name=<name>][&description=<description>] [&contactname=<primary_contact_name>][&contactphone=<primary_contact_phone>] [&contact =<primary_contact_ >] 3-9

40 Channel Provisioning API Actions Chapter 3 Provisioning APIs deletecontentprovider Deletes content providers. Either a list of content provider IDs or the keyword all is required. A confirmation that the content providers have been deleted. deletecontentproviders&cp=all <cp_id>, <cp_id>, createwebsite Creates a website. Website name (required) Content provider ID (required) Origin server (required) Fully qualified domain name (FQDN) (optional) Note This is the FQDN used by the Content Router to route the requests to a Content Engine. For example, while processing a request for (origin server FQDN), the Content Router may route the request to a Content Engine using the FQDN WMT authentication (optional) The default is none. Basic NTLM Description (optional). A confirmation that the website has been created and the newly created website object. createwebsite&name=<website_name>&cp=<content_provider_id>&origin=<origin server>[&fqdn= <fqdn>][&wmtauth=<basic ntlm>][&description=<description>] modifywebsite Modifies website settings. 3-10

41 Chapter 3 Provisioning APIs Location Provisioning API Actions Website ID (required) Website name (optional) Content provider ID (required) Origin server (optional) FQDN (optional) WMT authentication (optional) None Basic NTLM Description (optional) A confirmation that website attributes have been modified and the modified website object. modifywebsite&website=<website_id>[&name=<website_name>][&origin=<origin server>][&fqdn =<fqdn>][&wmtauth=<none basic ntlm>][&description=<description>] deletewebsites Deletes websites. Either a list of website IDs or the keyword all is required. A confirmation that the websites have been deleted. deletewebsites&website=all <website_id>, <website_id>, Location Provisioning API Actions The Location Provisioning API is the LocationApiServlet. This servlet performs one or more of the following actions: createlocation modifylocation 3-11

42 Location Provisioning API Actions Chapter 3 Provisioning APIs deletelocation createlocation Creates a specified location. Location name (required) Parent location ID (optional) Description (optional) The newly created location object. createlocation&location=<location_name>[&parent=<parent_id>][&desc=<description>] modifylocation Modifies a specified location. Location ID (required) Location name (optional) Parent location ID (optional) Description (optional) The modified location object. modifylocation&location=<location_id>[&name=<location_name>][&parent=<parent_id>] [&desc=<description>] deletelocation Deletes a specified location. Location ID (required) A message that the specified location has been deleted. 3-12

43 Chapter 3 Provisioning APIs Content Engine Provisioning API Actions deletelocation&location=<location_id> Content Engine Provisioning API Actions The Content Engine Provisioning API is the CeApiServlet. This servlet performs one or more of the following actions: activatece changecelocation deletece contentroutingquery activatece Activates a specified Content Engine. Content Engine ID (required) Location ID (required) The modified Content Engine object. <ce_id>&location=<location_id> changecelocation Changes the location of a specified Content Engine. Content Engine ID (required) Location ID (required) The modified Content Engine object. 3-13

44 Content Engine Provisioning API Actions Chapter 3 Provisioning APIs ce=<ce_id>&location=<location_id> deletece Deletes a specified Content Engine. Content Engine ID (required) A message that the specified Content Engine has been deleted. <ce_id> contentroutingquery Determines the Content Engine that will be selected by the Content Router. Client IP address Only IPv4 addresses are supported. Fully qualified domain name (FQDN) of the website This FQDN should be the same as what is configured in the Request Routed FQDN field of the Content Distribution Manager GUI. Name of the Content Engine selected by the Content Router. FQDN> Note If the incoming API call format is incorrect, the call request is dropped. User side might experience a timeout or connection error or HTML file that describes the error. If a Content Engine is found, the Content Router responds with the following answer: <?xml version="1.0" encoding="iso "?> <ContentRoutingApiResponse> <Status> 0 </Status> <Error> None </Error> <CE> <name of ContentEngine> </CE> </ContentRoutingApiResponse> If no CE is found or if there is an error in processing the API call, the Status element is set to non-zero and the CE element is set to NotFound. 3-14

45 Chapter 3 Provisioning APIs Program API Actions The following are the status codes and the corresponding errors: Status Error 1 Unknown domain. 2 Not in coverage zone. 3 Temporarily unavailable. 4 Wrong API format Program API Actions The Program API is the ProgramApiServlet. Note You must have administrator-level access privileges to execute Program API actions. This servlet performs one or more of the following actions: createprogram validateprogramfile assignchannel assignces assigndgs fetchnow modifyprogramfile unassignchannel unassignces unassigndgs deleteprograms startsession pausesession stopsession createprogram Fetches a program file using HTTP, validates it, and creates a program based on the input. This action also reserves a multicast address, if the program requires one. The multicast address reserved for the program is not released until the program is deleted. 3-15

46 Program API Actions Chapter 3 Provisioning APIs Program file URL (required) Update interval (required) Interval (in minutes) at which to access the program file to check for updates User ID (optional) User password (optional) The newly created program record, with the program ID. If the program file fails validation, an error message is returned. Appendix A, Program Files in ACNS Software, provides a DTD for the information that is returned. createprogram&file=<program_file_url>&updateinterval=<update_interval_minutes>[&user= <user_name>][&password=<password>] validateprogramfile Fetches a program file using HTTP and validates it. Program file URL (required) None, if there are no errors. If there are errors, returns a list of errors. validateprogramfile&file=<program_file_url> assignchannel Assigns a channel to a program. When you assign a channel to a program, all Content Engines associated with the channel are associated with the program. Any modification to the Content Engine channel assignment also updates the program. This action should not be used if the assignces and assigndgs actions have already been used. If a Content Engine or device group has already been assigned to a program, the assignchannel action fails and returns the following error message: <?xml version="1.0"?> - <programapi action="assignchannel"> <message status="fail" message="constraint Error: Can not associate a channel with the playlist. Content engines are already assigned to the playlist." /> <error code="3" message="constraint Error: Can not associate a channel with the playlist. Content engines are already assigned to the playlist." /> </programapi> 3-16

47 Chapter 3 Provisioning APIs Program API Actions Program ID (required) Channel ID (required) The updated program record. assignchannel&program=<program_id>&channel=<channel_id> assignces Assigns Content Engines to a program. This action should not be used if the assignchannel action has already been used. If a channel has already been assigned to a program, the assignces action fails and returns the following error message: <?xml version="1.0"?> - <programapi action="assignces"> <message status="fail" message="constraint Error: Can not assign content engines to the playlist. The playlist is already associated with a channel." /> <error code="3" message="constraint Error: Can not assign content engines to the playlist. The playlist is already associated with a channel." /> </programapi> Note This action fails if the program represents a live event, because live programs must be assigned to a live channel. Program ID (required). Either the list of Content Engines or the keyword all is required. The updated program record. program=<program_id>&ce=all <CE_ID>, <CE_ID>,... assigndgs Assigns device groups to a program. This action should not be used if the assignchannel action has already been used. If a channel has already been assigned to a program, the assigndgs action fails and returns the following warning message: <?xml version="1.0"?> - <programapi action="assigndgs"> 3-17

48 Program API Actions Chapter 3 Provisioning APIs <message status="fail" message="constraint Error: Can not assign device engines to the playlist. The playlist is already associated with a channel." /> <error code="3" message="constraint Error: Can not assign device engines to the playlist. The playlist is already associated with a channel." /> </programapi> Note This action fails if the program represents a live event because live programs must be assigned to a live channel. Program ID (required) List of device groups (required) You cannot use the keyword all, because some device groups may contain Content Routers. The updated program record. program=<program_id>&dg=all <DG_ID>, <DG_ID>, fetchnow Fetches a program file immediately using HTTP and updates the program. Program ID (required) None, if there are no errors. Displays an error message if the program file fails validation. program=<program_id> modifyprogramfile Modifies program file settings. Program ID (required) Program file URL (optional) Update interval (optional) User ID (optional) User password (optional) 3-18

49 Chapter 3 Provisioning APIs Program API Actions If a parameter value is not specified, no change is made to the original program file setting. If the parameter values need to be removed, use the empty string mechanism to delete an existing setting. For example, if you now want to remove the user ID from the program file, set the user ID parameter to an empty string (user= ) when using the modifyprogramfile action. Note You cannot set the program file URL to an empty string. Setting the program file URL to null removes all the other settings. The updated program record. modifyprogramfile&program=<program_id>[&file=<program_file_url>][&updateinterval= <update_interval>][&user=<user_name>][&password=<password>] unassignchannel Removes a channel from the specified program. This action should not be used if the unassignces and unassigndgs actions have already been used. The unassignchannel action executes successfully even if a Content Engine or device group has already been unassigned from a program, but displays a warning that the channel is not assigned to the program. Program ID (required) Channel ID (required) The updated program record. unassignchannel&program=<program_id>&channel=<channel_id> unassignces Removes Content Engines from the specified program. This action need not be used if the unassignchannel action has already been used. The unassignces action executes successfully even if a channel has been already unassigned from a program, but displays a warning that the Content Engines are not assigned to the program. Program ID (required). Either a list of Content Engines or the keyword all is required. 3-19

50 Program API Actions Chapter 3 Provisioning APIs The updated program record. program=<program_id>&ce=all <CE_ID>, <CE_ID>, unassigndgs Removes device groups from the specified program. This API action need not be used if the unassignchannel action has already been used. The unassigndgs action executes successfully even if a channel has already been unassigned from a program, but displays a warning that the device groups are not assigned to the program. Program ID (required). Either a list of device groups or the keyword all is required. The updated program record. program=<program_id>&dg=all <DG_ID>, <DG_ID>, deleteprograms Deletes programs. A list of programs by service type (such as TV-out, export, WMT, RealMedia, or Cisco Streaming Engine) or program ID, or the keyword all is required. None. deleteprograms&program=all id=<program_id>, <program_id>,... type=<tvout export wmt real ciscostreamingengine> startsession Makes an HTTP GET request when the client selects Play or when the content starts to stream. 3-20

51 Chapter 3 Provisioning APIs Program API Actions s Subscriber or client IP address Subscriber or client destination port for content stream Content Engine IP address serving stream Content Engine port Request identifier returned from Camiant CDN Application Manager Authorization module during authorization 200 Ok Request was successful. 400 Bad request Request parameters were incomplete or invalid. QoS request was not successful. 500 Internal server error Internal error occurred. QoS request was not successful. /cdnam/startsession.do?subip=x.x.x.x&subport=n&ceip=y.y.y.y&ceport=m&rid=r pausesession Makes an HTTP GET request when the client selects Pause. Request identifier returned from Camiant CDN Application Manager Authorization module during authorization 200 Ok Request was successful. 400 Bad request Request parameter was unknown. No QoS action occurred. 500 Internal server error Internal error occurred. QoS request was not successful. /cdnam/pausesession.do?rid=r stopsession Makes an HTTP GET request when the client selects Stop, or when the content stops streaming. Request identifier returned from Camiant CDN Application Manager Authorization module during authorization 200 Ok Request was successful. 400 Bad request Request parameter was unknown. No QoS action occurred. 500 Internal server error Internal error occurred. QoS request was not successful. 3-21

52 Program API Actions Chapter 3 Provisioning APIs /cdnam/stopsession.do?rid=r 3-22

53 CHAPTER 4 Listing API This chapter describes the Listing API and the servlet actions it performs. Listing API Actions The Listing API is the ListingApiServlet. If there is a list inside the object, the listed items are printed as elements of the object. This servlet performs one or more of the following actions: getwebsites getchannels getces getclusters getcontentproviders getlocations getdevicegroups getdevicestatus getobjectbyid getobjectbyname getprograms getpgmmcastaddrinuse getmcastaddrinuse getpgmmcastaddrrange getwebsites Lists selected website names and related content provider name, or lists every website. 4-1

54 Listing API Actions Chapter 4 Listing API Either a list of website names or the keyword all is required. A list of all websites specified and their details. getwebsites& param=all <website_name>, <website_name>, getchannels Lists selected channel names and related website ID or lists all channels. A list of channel names with related website IDs, a Content Engine ID, a program ID, or the keyword all is required. A list of all channels specified and their details. param=all [name=]<website_id>:all <channel_name>... ce=<ceconfig_id> program=<playlist_id> getces Lists selected Content Engines by Content Engine name, channel, or location, or lists all Content Engines. When Content Engines are listed by location, all Content Engines in the given location and all Content Engines (child, grandchild, and so forth) in the subordinate locations are listed. A list of Content Engine names, a channel ID, a location ID, or the keyword all is required. A list of all Content Engines specified and their details. all [name=]<ce_name>, <ce_name>... channel=<channel_id> location=<location_id> getclusters Lists selected cluster names or lists every cluster. 4-2

55 Chapter 4 Listing API Listing API Actions Either a list of cluster IDs or the keyword all is required. A list of all clusters specified and their details. getclusters& param=all <Cluster_ID>, <Cluster_ID> getcontentproviders Lists selected content provider names or lists all content providers. Either a list of content provider names or the keyword all is required. A list of all content providers specified and their details. getcontentproviders&param=all <content_provider_name>, <content_provider_name> getlocations Lists the location of the specified Content Engines or the locations of all Content Engines. Either the Content Engine ID or the keyword all is required. The requested location record. param=all byceid=<ce_id> getdevicegroups Lists selected device group names or lists all device groups. Either a list of device group names or the keyword all is required. 4-3

56 Listing API Actions Chapter 4 Listing API A list of all device groups specified and their details. getdevicegroups& param=all <device_group_name>, <device_group_name>, getdevicestatus Lists the status of a device by name. Name of the device which contains the ID of the device or device group. If no parameter is specified, the status of all devices is returned. The name of the device is case sensitive. Note The &name parameter is required in the syntax. The device status servlet does not support the all device status query. A list of devices and their status. &name=<device_id> <devicegroup_id> getobjectbyid Lists an object, based on its string ID. Object string ID The following are the object types: CE Channel Cluster Content provider Device group Website Program The requested object. 4-4

57 Chapter 4 Listing API Listing API Actions getobjectbyid& param=<ceconfig_x Channel_X ClusterConfig_X ContentProvider_X DeviceGroup_X WebSite_X Playlist_X> Note You must have administrator-level access privileges to execute this action. getobjectbyname Lists an object, based on its name. Object type:object name The following are the object types: CE Channel CP DG Website Program The channel name format is website name:channel name The requested object. getobjectbyname&param=ce:<cename> Channel:<websiteName:channelName> CP:<cpName> DG:<dgName> Website:<websiteName> Program:<programName> Note If the type of object is a program, you must have administrator-level access privileges to execute this action. getprograms Lists all programs specified or all programs and their details. A list of program types, program names, channel ID, or program ID, or the keyword all is required. A list of all programs specified and their details. 4-5

58 Listing API Actions Chapter 4 Listing API param=all type=<tvout export wmt real ciscostreamingengine> name=<program_name>, <program_name> channel=<channelid> id=<programid> Note You must have administrator-level access privileges to execute this action. getpgmmcastaddrinuse Lists all multicast addresses currently in use by programs. None. A list of all the multicast addresses currently in use by programs. action=getpgmmcastaddrinuse Note You must have administrator-level access privileges to execute this action. getmcastaddrinuse Lists all multicast addresses currently in use, including addresses used by programs and others (for example, addresses used for multicast content distribution). None. A list of all the multicast addresses currently in use. action=getmcastaddrinuse Note You must have administrator-level access privileges to execute this action. getpgmmcastaddrrange Lists the multicast address range reserved for programs. 4-6

59 Chapter 4 Listing API Listing API Actions None. The starting and ending multicast addresses reserved for programs, or an empty list if none have been allocated. If the action returns an empty list, it implies that the ACNS network is not configured to support multicasting events. action=getpgmmcastaddrrange Note You must have administrator-level access privileges to execute this action. 4-7

60 Listing API Actions Chapter 4 Listing API 4-8

61 CHAPTER 5 Statistics APIs This chapter describes the Monitoring Statistics API and Streaming Statistics API, and the servlet actions they perform. This chapter contains the following sections: Monitoring Statistics API, page 5-1 Streaming Statistics API, page 5-5 Monitoring Statistics API This section describes the Monitoring Statistics API and the servlet actions it performs. The Monitoring Statistics API obtains monitoring statistics data about a single Content Engine or all the Content Engines in an ACNS network. Monitoring Statistics API Actions The Monitoring Statistics API is the MonitoringApiServlet. This servlet performs one or more of the following actions: getcestats getlocationstats getcdnstats getcestats Obtains monitoring statistics information for the specified Content Engine. Content Engine ID (required) Monitoring statistics type (required) The monitoring statistics types are: bytes_served 5-1

62 Monitoring Statistics API Chapter 5 Statistics APIs bandwidth_efficiency_gain streaming_sessions cpu_utilization Time frame (Optional) The time period over which monitoring statistics are obtained. The default is last_hour. The options are: last_hour last_day last_week last_month custom Note If you choose custom, you must specify the time frame using the End time from and End time to options. End time from (Optional) The date and time that collection of monitoring statistics data should start. You can specify only the date or the date and time. The date format is mm/dd/yyyy, and the time format is hh:mm. Optionally, you can specify the time in hh:mm:ss. End time to (Optional) The date and time that collection of monitoring statistics data should end. You can specify only the date or the date and time. The date format is mm/dd/yyyy, and the time format is hh:mm. Optionally, you can specify the time in hh:mm:ss. Time zone (Optional) The time zone used to generate the monitoring statistics data. The default is utc. The time zones are: utc Time in UTC (Coordinated Universal Time) ce_local_time Time zone specified on the Content Engine cdm_local_time Time zone specified on the Content Distribution Manager Requested monitoring statistics data for the selected time period for the Content Engine. id=<ceconfig_id>&type=<bytes_served bandwidth_efficiency_gain streaming_sessions cpu_utilization>[&time_frame=<last_hour last_day last_week last_month custom>] [&end_time_from=<mm/dd/yyyy [hh:mm[:ss]]>][&end_time_to=<mm/dd/yyyy [hh:mm[:ss]]>] [&time_zone=<utc ce_local_time cdm_local_time>] getlocationstats Obtains monitoring statistics information for all the Content Engines in the specified location. Location ID (required) 5-2

63 Chapter 5 Statistics APIs Monitoring Statistics API Monitoring statistics type (required) The monitoring statistics types are: bytes_served bandwidth_efficiency_gain streaming_sessions Time frame (Optional) The time period over which monitoring statistics are obtained. The default is last_hour. The options are: last_hour last_day last_week last_month custom Note If you choose custom, you must specify the time frame using the End time from and End time to options. End time from (Optional) The date and time that collection of monitoring statistics data should start. You can specify only the date or the date and time. The date format is mm/dd/yyyy, and the time format is hh:mm. Optionally, you can specify the time in hh:mm:ss. End time to (Optional) The date and time that collection of monitoring statistics data should end. You can specify only the date or the date and time. The date format is mm/dd/yyyy, and the time format is hh:mm. Optionally, you can specify the time in hh:mm:ss. Time zone (Optional) The time zone used to generate the monitoring statistics data. The default is utc. The time zones are: utc Time in UTC (Coordinated Universal Time) cdm_local_time Time zone specified on the Content Distribution Manager Requested monitoring statistics data for the selected time period for the Content Engines in the specified location. Stats&id=<Location_id>&type=<bytes_served bandwidth_efficiency_gain streaming_sessions> [&time_frame=<last_hour last_day last_week last_month custom>][&end_time_from= <mm/dd/yyyy [hh:mm[:ss]]>][&end_time_to=<mm/dd/yyyy [hh:mm[:ss]]>][&time_zone= <utc cdm_local_time>] getcdnstats Obtains monitoring statistics information for the entire ACNS network. 5-3

64 Monitoring Statistics API Chapter 5 Statistics APIs Monitoring statistics type (required) The monitoring statistics types are: bytes_served bandwidth_efficiency_gain streaming_sessions Time frame (Optional) The time period over which monitoring statistics are obtained. The default is last_hour. The options are: last_hour last_day last_week last_month custom Note If you choose custom, you must specify the time frame using the End time from and End time to options. End time from (Optional) The date and time that collection of monitoring statistics data should start. You can specify the date or the date and time. The date format is mm/dd/yyyy, and the time format is hh:mm. Optionally, you can specify the time in hh:mm:ss. End time to (Optional) The date and time that collection of monitoring statistics data should end. You can specify the date or the date and time. The date format is mm/dd/yyyy, and the time format is hh:mm. Optionally, you can specify the time in hh:mm:ss. Time zone (Optional) The time zone used to generate the monitoring statistics data. The default is utc. The time zones are: utc Time in UTC (Coordinated Universal Time) cdm_local_time Time zone specified on the Content Distribution Manager Requested monitoring statistics data for the selected time period for all the Content Engines in the ACNS network. &type=<bytes_served bandwidth_efficiency_gain streaming_sessions>[&time_frame=<last_hour last_day last_week last_month custom>][&end_time_from=<mm/dd/yyyy [hh:mm[:ss]]>] [&end_time_to=<mm/dd/yyyy [hh:mm[:ss]]>][&time_zone=<utc cdm_local_time>] 5-4

65 Chapter 5 Statistics APIs Streaming Statistics API Streaming Statistics API This section describes the Streaming Statistics API and the servlet actions it performs. The streaming statistics are collected from the ACNS network s Content Engines and device groups and sent to the Content Distribution Manager. The HTTP, Cisco Streaming Engine, WMT, and RealProxy streaming statistical data is monitored and displayed in the Content Distribution Manager GUI for all Content Engines, all device groups, or all the Content Engines within a selected device group. Streaming Statistics API Actions The Streaming Statistics API is the SprayerApiServlet. The Content Distribution Manager and its GUI must be running for the servlet to function. This servlet performs one or more of the following actions to collect statistics for each Content Engine (CE), device group (DG), or device group name for all the Content Engines in the specified device group: gethttp getciscostreaming getwmt getrealproxy gethttp Collects HTTP streaming statistics data from the ACNS network s Content Engines and device groups and sends it to the Content Distribution Manager. The keywords CE, DG, or the name of the device group is required. Requested streaming statistics data for the Content Engines or device groups. param=ce DG <DG_name>, <DG_name>,... getciscostreaming Collects Cisco Streaming Engine streaming statistics data from the ACNS network s Content Engines and device groups and sends it to the Content Distribution Manager. The keywords CE, DG, or the name of the device group is required. 5-5

66 Streaming Statistics API Chapter 5 Statistics APIs Requested streaming statistics data for the Content Engines or device groups. getciscostreaming&param=ce DG <DG_name>, <DG_name>,... getwmt Collects WMT streaming statistics data from the ACNS network s Content Engines and device groups and sends it to the Content Distribution Manager. The keywords CE, DG or the name of the device group is required. Requested streaming statistics data for the Content Engines or device groups. param=ce DG <DG_name>, <DG_name>,... getrealproxy Collects RealProxy streaming statistics data from the ACNS network s Content Engines and device groups and sends it to the Content Distribution Manager. The keywords CE, DG, or the name of the device group is required. Requested streaming statistics data for the Content Engines or device groups. param=ce DG <DG_name>, <DG_name>,... XML Formatted Output The following is the Document Type Definition (DTD) of the XML-formatted output: <?xml version="1.0"?> DOCTYPE <!DOCTYPE sprayerstats [ <!ELEMENT sprayerstats (message, (HttpStats* CiscoStreamingEngineStats* RealProxyStats WmtStats*) )> <!ATTLIST sprayerstats action (gethttp getciscostreaming getrealproxy getwmt)#required count CDATA #REQUIRED> <!ELEMENT message EMPTY> 5-6

67 Chapter 5 Statistics APIs Streaming Statistics API <!ATTLIST message status (success fail) success message CDATA #IMPLIED> <!ELEMENT HttpStats EMPTY> <!ATTLIST HttpStats name CDATA #REQUIRED requestspersec CDATA #REQUIRED bytespersec CDATA #REQUIRED servicetime CDATA #REQUIRED hitrate CDATA #REQUIRED> <!ELEMENT CiscoStreamingEngineStats EMPTY> <!ATTLIST CiscoStreamingEngineStats name CDATA #REQUIRED totalbytes CDATA #REQUIRED totalpackets CDATA #REQUIRED rtspconnections CDATA #REQUIRED allconnections CDATA #REQUIRED> <!ELEMENT RealProxyStats EMPTY> <!ATTLIST RealProxyStats name CDATA #REQUIRED requestspersec CDATA #REQUIRED bytespersec CDATA #REQUIRED hitrate CDATA #REQUIRED> <!ELEMENT WmtStats EMPTY> <!ATTLIST WmtStats name CDATA #REQUIRED requestspersec CDATA #REQUIRED bytespersec CDATA #REQUIRED hitrate CDATA #REQUIRED> ]> 5-7

68 Streaming Statistics API Chapter 5 Statistics APIs 5-8

69 APPENDIX A Program Files in ACNS Software ACNS 5.5 software uses programs to enable support for live multicast and scheduled rebroadcast events. A program in ACNS software is defined as a scheduled event in which the content is presented to the end user. The three attributes of a program are: Schedule Defines when the content is presented to the end user. Content Defines what is presented to the end user. In ACNS software, this can be pre-positioned or live content. Presentation Defines how the content is presented to the end user. The presentation attributes include the set of Content Engines that know about the program, and a service type that identifies the streaming server used to deliver the content. The streaming server can exist in the Content Engine (Windows Media Technologies [WMT], RealServer, or Cisco Streaming Engine) or outside (for example, in set top boxes). A program file contains the elements that define the schedule, content, and presentation parameters. It is a text file written in XML format, similar to the manifest file. For more information about manifest files, refer to the Cisco ACNS Software Configuration Guide for Centrally Managed Deployments, Release 5.5. Program types determine the hardware or software component involved in delivering content to the user. Different program types are: Cisco Streaming Engine WMT RealMedia TV-out Export (meant for a third-party device such as a set top box) The Content Distribution Manager manages multicast addresses to be used for programs. Each Content Engine assigned to the program uses the multicast address for broadcast. The Content Engine determines which multicast address is to be used based on the program data. A set of multicast addresses can be specified either in the Program API or by using the Content Distribution Manager. Each time a program requires a multicast address, the Content Distribution Manager associates one of the addresses with the program. Addresses are allocated for the life of a program. Programs can be configured with an autodelete feature, which allows program addresses to be freed up automatically about 24 hours after a program schedule is complete. When you configure a pool of addresses for programs, ACNS software ensures that none of these addresses are currently in use by any of the multicast clouds. When users request a specific address or a set of addresses to be used for a program, ACNS software issues only those addresses that have not been A-1

70 Program File DTD Appendix A Program Files in ACNS Software configured for multicast clouds and are not used by any of the existing programs. Users will receive an error message if there is no multicast address associated with the imported program file and no addresses are available to be configured from the pool or if the multicast pool has not been configured. When you define a Cisco Streaming Engine live program using the createprogram API, you can specify a single backup broadcast server for the program. To do this, you must specify the IP addresses of the primary and backup broadcast servers in the program file using the <media> tag. The <media> tag in the program file should be in the following format: <media index= number src= primary_broadcast_server:port;backup_broadcast_server:port /> Program File DTD This section describes the Document Type Definition (DTD) for ACNS software program files. You can use the DTD to create program files for importing programs from third-party systems or IP/TV, and exporting programs to set top boxes (STBs). The following is the DTD for an ACNS software program file: <?xml version="1.0"?> <!DOCTYPE program[ <!ELEMENT program (media+, ucastinfo?, mcastinfo?, overlay*, schedule*, attribute?)> <!ATTLIST program version CDATA "1.0" name CDATA #REQUIRED servicetype (tvout export wmt real ciscostreamingengine) "tvout" description CDATA #IMPLIED playtime CDATA #IMPLIED lastmodificationtime CDATA #IMPLIED gracefulexit (false true) "false" shuffle (false true) "false" autodelete (false true default) "default" live (false true) "false" > <!ELEMENT media EMPTY> <!ATTLIST media index CDATA #IMPLIED src CDATA #REQUIRED id CDATA #IMPLIED playtime CDATA #IMPLIED overlayname IDREF #IMPLIED > <!ELEMENT ucastinfo EMPTY> <!ATTLIST ucastinfo referenceurl CDATA #REQUIRED > <!ELEMENT mcastinfo (addrport*)> <!ATTLIST mcastinfo referenceurl CDATA #REQUIRED TTL CDATA #IMPLIED > <!ELEMENT addrport EMPTY> <!ATTLIST addrport addrval CDATA #REQUIRED portval CDATA #REQUIRED id CDATA #IMPLIED > <!ELEMENT overlay EMPTY> <!ATTLIST overlay name ID #REQUIRED src CDATA #REQUIRED A-2

71 Appendix A Program Files in ACNS Software Program File DTD > id CDATA #IMPLIED placement (center ll lr ul ur ) "lr" height CDATA "0" width CDATA "0" opacity CDATA "7" colortransparency (false true) "false" <!ELEMENT schedule (repeats?)> <!ATTLIST schedule timespec (local gmt) "local" starttime CDATA #IMPLIED activeduration CDATA #IMPLIED > <!ELEMENT repeats (dayoffset*)> <!ATTLIST repeats type (timeinterval days) "timeinterval" interval CDATA #IMPLIED endtime CDATA #IMPLIED > <!ELEMENT dayoffset EMPTY> <!ATTLIST dayoffset value ( ) "0" > <!ELEMENT attribute EMPTY> <!ATTLIST attribute value CDATA #REQUIRED > ]> Table A-1 describes the elements in the DTD and their attributes. Table A-1 Program File DTD Elements and Attributes Element Attributes Description program version Version of the program file. ACNS software, Release 5.5 generates playlist files with a version level of 1. name Name of the program. servicetype Type of program, which dictates the mode of delivery. This element identifies the software or hardware component involved in delivering the content to the user. description Brief description of the program. playtime Total playtime in seconds. This is the sum of the playtime values of the media files, if set. If there are files in the program that have invalid playtimes, then this field is set to 1. lastmodificationtime Time when the playlist was created or modified last, as recorded in the Content Distribution Manager. The format is hh:mm:ss. The assumption is that all devices in the ACNS network are time-synchronized (for example, using the Network Time Protocol [NTP]). gracefulexit Specifies how to handle scheduled exits. Options are: True Exit after the current media file is played completely. False Exit immediately. A-3

72 Program File DTD Appendix A Program Files in ACNS Software Table A-1 Program File DTD Elements and Attributes (continued) Element Attributes Description shuffle autodelete live Specifies whether the media files should play in any order. Options are: True Play media files at random. False Play media files in order. When this attribute is not specified, it is set to false by default. Specifies whether the program should be automatically deleted 24 hours after it is last played. Options are: True Delete the program 24 hours after it is last played. False Retain the program for more than 24 hours after it is last played. Default When the value for the live attribute is set to true, the default value is true for autodelete, and false if the live attribute is set to false. Specifies whether the program contains live content. Options are: True The program contains live content. False The program does not contain live content. media index Order of the media file in the list of files, ranging from 1 to mediacount (the number of media files in the program). The index attribute specifies the order of the media files when the shuffle attribute in the <media> tag is set to false. src Reference to the source of the media file. For live content, this field contains information about how the streaming server will correlate with the live feed. For pre-positioned content, this field contains the portion of the URL that follows the origin server, that is, the fully qualified domain name (FQDN). For example, if the source file URL is the value assigned to this field is mydirectory/myfile. Note When pre-positioned content is exported, this field contains the URL for the file that can be routed in the ACNS network, without the protocol specification. Live source failover is supported. For WMT live, multiple encoders or streaming servers can be specified. src=" For CSE live, only a single backup can be specified. src="sourceaddress1:destinationport1;sourceaddress2:destin ationport2" A-4

73 Appendix A Program Files in ACNS Software Program File DTD Table A-1 Program File DTD Elements and Attributes (continued) Element Attributes Description id playtime Media file identifier. For rebroadcast events, this field contains the ID of the channel containing this media file. In the case of live events, this field is used to correlate a stream source with a multicast address. Playtime for the file in seconds, when it is known. This attribute is used only for MPG media files. Options are: 2 If the file is not an MPG file 1 If the file is an MPG file but the ACNS software cannot determine the playtime 0 or greater If the playtime is correctly determined from the file overlayname Name of the overlay to be displayed along with this media clip. This field is optional. ucastinfo referenceurl URL used by the end user to request this program over the network. mcastinfo referenceurl URL used by the end user to request this program over the network. TTL Multicast Time To Live (TTL) value to be used for the packets sent using multicast. addrport addrval Address to be used when this program is multicast. portval Port (within the multicast address) to be used when this program is multicast. overlay name Unique name for identification (defined by the user). The name must start with a letter and should be a valid XML name. src Source of the given overlay file. For imported programs, the src attribute contains the portion of the URL that follows the origin server, that is, the FQDN. For example, if the source file URL is the value assigned to this field is mydirectory/myfile. id Note When pre-positioned content is exported, this field contains the URL for the file that can be routed in the ACNS network, without the protocol specification. Identifier to be used with the overlay file. This field is used only when programs are imported, and it contains the ID of the channel containing this media file. A-5

74 Program File DTD Appendix A Program Files in ACNS Software Table A-1 Program File DTD Elements and Attributes (continued) Element Attributes Description placement height width Placement of the overlay in the media file. This field is optional. Options are: Center Lower left Lower right Upper left Upper right The default value is lower right. Vertical placement of the overlay, from 40 to 40 pixels. 40 Moves the image to the lowest possible position on the display. 40 Moves the image to the topmost position on the display. Horizontal placement of the overlay, from 6 to 60 pixels. 6 Moves the image to the left-most possible position on the display. 60 Moves the image to the right-most possible position on the display. opacity Opacity of the overlay, from 0 to 15. A value of 0 makes the overlay completely opaque. A value of 15 renders the image nearly transparent. colortransparency Specifies whether a transparent color should be defined in the overlay. When set, the color of the pixel in the lower left corner is to be transparent over the entire image. When a transparent image is used, the background color of the overlay is not visible against the video playing behind it. The default value is false. schedule timespec Specifies how time values should be interpreted. Options are: starttime activeduration Local Greenwich mean time (GMT) Time (in seconds) since the epoch (January 1, 1970) when the program should start playing. Tip For UNIX operating systems, the epoch is 00:00:00 GMT, January 1, This represents the time and date corresponding to 0 in the UNIX operating system s date and time stamp. System time is measured in seconds past the epoch. Duration of the program (in seconds). For a scheduled rebroadcast, this value specifies how long the files should loop (that is, loop for x seconds). If there is no looping, this value is 0. For live programs, this value is the duration of the event. A-6

75 Appendix A Program Files in ACNS Software Program File Examples Table A-1 Program File DTD Elements and Attributes (continued) Element Attributes Description repeats type Type of repeat. For example, you can set the program to repeat every x seconds, or repeat on specified days of the week at the same time specified in the start time. Options are: interval TimeInterval Days Time interval (in seconds) for the repeat broadcast of the program. For example, if this value to seconds, the program repeats every 8 hours. endtime Time (in seconds) since the epoch (January 1, 1970) when program repeats should end. For a program that repeats forever, this value is 0. dayoffset value Day to repeat the program, for example, every Monday. The time (during the day) of the repeat is inherited from the starttime attribute. attribute value Element used if a third-party device such as a set top box is used to import some data that is transparent to an ACNS network, and that is directly used by the software or hardware component involved in delivering the content to the user. The Centralized Management System (CMS) relays the data without interpreting it. A recommended method for encoding this field is to use a name/value pair in the string, for example, name1=value1; name2=value2. Program File Examples This section contains program file examples, each describing the contents for specific event types. The examples are provided for the following event types: WMT Multicast Live Event, page A-7 WMT Multicast Rebroadcast Event, page A-8 Cisco Streaming Engine Multicast Event, page A-9 Cisco Streaming Engine Live-Split Event, page A-9 WMT Multicast Live Event The following example shows the program file for a WMT multicast live event in which the multicast address is chosen by the Content Distribution Manager. The addrport attribute is not shown in this example: <?xml version="1.0"?> <!DOCTYPE program SYSTEM "program.dtd"> <program version="1.0" name="prog1" servicetype="wmt" live="true"> <media src=" /> <mcastinfo referenceurl=" <schedule timespec="gmt" starttime=" " activeduration="3600"/> </program> A-7

76 Program File Examples Appendix A Program Files in ACNS Software The following example shows the program file for a WMT multicast live event in which the multicast address is specified using the addrport attribute. <?xml version="1.0"?> <!DOCTYPE program SYSTEM "program.dtd"> <program version="1.0" name="liveprogram" servicetype="wmt" description="test" autodelete="true" live="true"> <media index="1" src=" id="media0"/> <mcastinfo referenceurl=" TTL="22"> <addrport addrval=" " portval="61248" id="media0"/> </mcastinfo> <schedule timespec="gmt" starttime="0" activeduration="0"/> </program> WMT Multicast Rebroadcast Event This example shows the program file for a WMT multicast rebroadcast event: <?xml version="1.0"?> <!DOCTYPE program SYSTEM "program.dtd"> <program version="1.0" name="chanrebroad" servicetype="wmt" description="test" autodelete="false" live="false"> <media index="1" src="sen/beck.asf" id="channel_35748"/> <media index="2" src="sen/cscin53585.wmv" id="channel_35748"/> <media index="3" src="sen/starsnstripes.asf" id="channel_35749"/> <mcastinfo referenceurl=" <addrport addrval=" " portval="61248" id="channel_35748"/> </mcastinfo> <schedule timespec="local" starttime=" " activeduration="1300"> <repeats type="timeinterval" interval="2600"/> </schedule> </program> The referenceurl attribute is the link that the user clicks to join the program. You can provide the external IP address of the root Content Engine (for example, in the referenceurl attribute. Note A media file can be uniquely identified using a URL of the form <protocol>://<fqdn>/ <relative_url>. The id attribute in the media element specifies the ID of the channel containing the media file. Each channel is associated with the FQDN of a Content Engine or that of an origin server. The src attribute in the media element provides the relative part of the URL, which along with the id attribute identifies the file. You can provide the FQDN of the Content Engine that hosts the media file if a Content Router is used to direct the user request to the appropriate Content Engine. In this case, the FQDN must be associated with a website or channel that maps to the same Content Engines that can serve the program. You can provide the name of the Content Engine if the user request goes to a preselected Content Engine. If a third-party device such as a set top box assigns the Content Engines directly to the program, you can use any one of the Content Engines assigned to the program in the referenceurl attribute. If the third-party device assigns a channel to the program, you can use the name of any Content Engine in that channel (for example, the root Content Engine) in the referenceurl attribute. A-8

77 Appendix A Program Files in ACNS Software Program File Examples Cisco Streaming Engine Multicast Event This example shows the program file for a Cisco Streaming Engine multicast event. This event can also be accessed using unicast by specifying the referenceurl attribute in the ucastinfo element. <?xml version="1.0"?> <!DOCTYPE program SYSTEM "program.dtd"> <program version="1.0" name="prog5lfs_1673" servicetype="ciscostreamingengine" description="prog5lfs" playtime="3600" autodelete="false" live="true"> <media index="0" src="source_ip_address:destination_port" id="media0"/> <media index="1" src="source_ip_address:destination_port" id="media1"/> <ucastinfo referenceurl="rtsp://pm_fqdn_or_ip_addr/pm_1673.sdp"/> <mcastinfo referenceurl=" TTL="15"> <addrport addrval=" " portval="61036" id="media0"/> <addrport addrval=" " portval="61038" id="media1"/> </mcastinfo> <schedule timespec="gmt" starttime=" " type="playonce"/> <attribute value="unicastpushsdp: </program> Note The media source (src) is the live feed, pushed from Cisco IP/TV Broadcast Server. The src attribute contains the IP address of IP/TV Broadcast Server and the destination port of the root Content Engine. The root Content Engine listens for the program stream on the specified destination port. There is more than one media source, because audio, video, and other feeds may be broadcast on a separate stream, using a separate multicast address. The id attribute in the media element and the id attribute in the addrport element are used to correlate the address to the stream. Cisco Streaming Engine Live-Split Event This example shows the program file for a Cisco Streaming Engine live-split event: <?xml version="1.0"?> <!DOCTYPE program SYSTEM "program.dtd"> <program version="1.0" name="prog5lfs_1674" servicetype="ciscostreamingengine" description="prog52fs" playtime="3600" autodelete="false" live="true"> <media index="0" src="source_ip_address:destination_port" /> <media index="1" src="source_ip_address:destination_port" /> <ucastinfo referenceurl="rtsp://pm_fqdn_or_ip_addr/pm_1674.sdp"/> <schedule timespec="gmt" starttime=" " activeduration="7200" type="playonce"/> <attribute value="unicastpushsdp: </program> Note Attributes for the schedule element must be specified for the Cisco Streaming Engine streaming server. The id attribute is not required because there are no separate multicast addresses for the program streams. A-9

78 Program File Examples Appendix A Program Files in ACNS Software A-10

79 INDEX Symbols.sax 1-3 A AAA 1-2 ACNS network obtaining monitoring statistics information 5-3 ACNS network access privileges authentication and authorization 1-2 activatece action 3-13 activating a specified Content Engine 3-13 adding a manifest file to a specified channel 3-3 addmanifest action 3-3 APIs provided with ACNS software 1-1 XML format 1-1 assignces action 3-3, 3-17 assignchannel action 3-16 assigndgs action 3-4, 3-17 assigning channel to a program 3-16 Content Engines to a program 3-17 to a specified channel 3-3 device groups to a program 3-17 to a specified channel 3-4 audience intended for API guide vii authentication, authorization, and accounting. See AAA. C caller program API calls 1-2 calling APIs 1-2 changecelocation action 3-13 changing the location of a specified Content Engine 3-13 channel assigning to a program 3-16 creating 3-2 deleting 3-8 modifying 3-5 removing from a program 3-19 channel names and related website IDs listing 4-2 Channel Provisioning API 1-8, 3-1 Cisco Streaming Engine live split event example A-9 Cisco Streaming Engine multicast event example A-9 cluster names listing 4-2 collecting Cisco Straeming Engine streaming statistics 5-5 HTTP streaming statistics 5-5 RealProxy streaming statistics 5-6 WMT streaming statistics 5-6 common error messages supported 1-7 Content Distribution Manager obtaining monitoring statistics information 5-2 IN-1