Service Node OSS/BSS Integration Guide - cisco.com · Contents iii Cisco Service Node OSS/BSS Integration Guide OL-16960-01 APPENDIX A Where to Go From Here A-1 Cisco Service Node

Americas HeadquartersCisco Systems, Inc.170 West Tasman DriveSan Jose, CA 95134-1706 USAhttp://www.cisco.comTel: 408 526-4000

800 553-NETS (6387)Fax: 408 527-0883

Service Node OSS/BSS Integration GuideRelease 3.0June 2008

Cisco Service Node

Text Part Number: OL-16960-01

http://www.cisco.com

CCDE, CCENT, Cisco Eos, Cisco Lumin, Cisco Nexus, Cisco StadiumVision, the Cisco logo, DCE, and Welcome to the Human Network are trademarks; Changing the Way We Work, Live, Play, and Learn is a service mark; and Access Registrar, Aironet, AsyncOS, Bringing the Meeting To You, Catalyst, CCDA, CCDP, CCIE, CCIP, CCNA, CCNP, CCSP, CCVP, Cisco, the Cisco Certified Internetwork Expert logo, Cisco IOS, Cisco Press, Cisco Systems, Cisco Systems Capital, the Cisco Systems logo, Cisco Unity, Collaboration Without Limitation, EtherFast, EtherSwitch, Event Center, Fast Step, Follow Me Browsing, FormShare, GigaDrive, HomeLink, Internet Quotient, IOS, iPhone, iQ Expertise, the iQ logo, iQ Net Readiness Scorecard, iQuick Study, IronPort, the IronPort logo, LightStream, Linksys, MediaTone, MeetingPlace, MGX, Networkers, Networking Academy, Network Registrar, PCNow, PIX, PowerPanels, ProConnect, ScriptShare, SenderBase, SMARTnet, Spectrum Expert, StackWise, The Fastest Way to Increase Your Internet Quotient, TransPath, WebEx, and the WebEx logo 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. (0805R)

Cisco Service Node OSS/BSS Integration Guide© 2008 Cisco Systems, Inc. All rights reserved.

OL-16960-01

C O N T E N T S

About This Guide v

Introduction v

Audience v

Organization v

Conventions ii-vi

Product Support Contact Information vi

Obtaining Documentation vii

Notices vii

OpenSSL/Open SSL Project vii

GNU General Public License Statement ix

C H A P T E R 1 Service Node Provisioning API 1-1

Introduction 1-1

About the Service Node Provisioning API 1-1

API Implementation (Secure HTTP POST) 1-2

Results and Error Handling 1-3

Validation 1-3

API Provisioning and Web GUI Provisioning 1-3

Releases, Feature Suites, and the Provisioning API 1-4

Related References 1-4

C H A P T E R 2 Provisioning API Function Reference 2-1

Overview 2-1

Function Reference 2-1

Customer Management Functions 2-2

addCustomer 2-3

updateCustomerNumbers 2-7

getCustomer 2-13

getCustomerAlerts 2-32

getCustomerList 2-34

getAvailableInventoryNumbers 2-38

updateCustomer 2-40

shutdownCustomer 2-56

iCisco Service Node OSS/BSS Integration Guide

Contents

suspendCustomer 2-58

unsuspendCustomer 2-60

Agent Management Functions 2-62

Calling API Functions at the Agent Level 2-62

addAgent 2-63

getAgent 2-65

getAgentList 2-67

updateAgent 2-69

deleteAgent 2-72

Connecting to the API 2-73

Error Messages 2-73

Supported Timezones 2-74

Specifying Custom Provisioning Parameters using the API 2-74

C H A P T E R 3 Provisioning API Programming Examples 3-1

Overview 3-1

addCustomer Example 3-2

updateCustomerNumbers Example 3-4

updateCustomer Example 3-6

addAgent and getAgent Example 3-10

addAgent and getAgent Example 3-11

C H A P T E R 4 Call Detail Records 4-1

Using the API to Retrieve CDRs 4-2

Syntax for Retrieving CDRs 4-2

CDR Retrieval Example Using the wget Command 4-4

CDR Format Specification 4-5

Additional Service Node-Specific Output Fields Supported 4-5

IPDR XML Schema 4-5

Sample CDRs 4-9

IPDR Format Example 4-9

Basic CDR Format Example 4-9

Extended Basic CDR Format 4-11

Purging Call Records (ap_purgecalls) 4-11

ap_purgecalls Syntax and Usage 4-12

Frequently Asked Questions about Service Node CDRs 4-12

iiCisco Service Node OSS/BSS Integration Guide

OL-16960-01

Contents

A P P E N D I X A Where to Go From Here A-1

Cisco Service Node Resources and Documentation A-1

Cisco SBCS Resources A-2

I N D E X

iiiCisco Service Node OSS/BSS Integration Guide

OL-16960-01

Contents

ivCisco Service Node OSS/BSS Integration Guide

OL-16960-01

About This Guide

IntroductionThis Cisco Service Node OSS/BSS Integration Guide documents the implementation strategy and application programming interface for integrating Managed Solution Provider (MSP) operations and business support systems (OSS/BSS) with the Cisco Service Node to provision and manage SBCS customers.

AudienceThis guide is targeted to application programmers who are integrating their backend OSS/BSS systems with the Service Node for customer provisioning and call detail record retrieval.

Note This guide covers Service Node Release 3.0 OSS/BSS integration features only. For Release 3.0, the Service Node provisioning API covers managed Cisco Smart Business Communications Systems (SBCS) only.

For Linksys One brands and CPE, the Service Node provisioning API works as documented for Release 2.2. For more information, see the Cisco Service Node OSS/BSS Guide for Release 2.2.

OrganizationThis guide includes the following sections:

Chapter Title Description

Chapter 1 Service Node Provisioning API Describes the overall implementation strategy for OSS/BSS integration using the provisioning API, including function results, error handling and validation.

Chapter 2 Provisioning API Function Reference

Provides detailed information for the functions supported by the Service Node provisioning API.

vCisco Service Node OSS/BSS Integration Guide

OL-16960-01

About This GuideConventions

Conventions

Note Means reader take note.

Tip Means the following information will help you solve a problem.

Caution Means reader be careful. In this situation, you might perform an action that could result in equipment damage or loss of data.

Product Support Contact Information• For Cisco Service Node and Cisco SBCS product support, contact the Cisco Technical Assistance

Center (TAC):

http://www.cisco.com/en/US/support/index.html (Cisco.com login required)

Or call:

800-GO-CISCO (Have your contract information ready for the agent.)

• Global access numbers can be found at the following URL:

http://www.cisco.com/warp/public/687/Directory/DirTAC.shtml

• For Cisco SBCS design information, contact the Planning, Design, and Implementation Help Desk:

www.cisco.com/go/pdihelpdesk (Cisco.com login required)

Or call:

800-GO-CISCO (Ask the agent for the “PDI Help Desk.”)

• If you experience problems with any Linksys One product at any time, contact your Value Added Reseller (VAR).

If you are a VAR, contact Linksys One Technical Support at:

866-870-5826

Chapter 3 Provisioning API Programming Examples

Contains simple programming examples in Perl for calling the addCustomer, updateCustomer, updateCustomerNumbers, addAgent, and getAgent functions.

Chapter 4 Call Detail Records Covers Service Node call detail records (CDRs), including retrieval, format specification, retention, capacity, and frequently asked questions.

Appendix A Where to Go From Here Provides URLs to Cisco.com product documentation and resources for the Service Node and Cisco SBCS.

Chapter Title Description

viCisco Service Node OSS/BSS Integration Guide

OL-16960-01


Obtaining DocumentationFor information on obtaining documentation, submitting a service request, and gathering additional information, see the monthly What’s New in Cisco Product Documentation, which also lists all new and revised Cisco technical documentation, at:

http://www.cisco.com/en/US/docs/general/whatsnew/whatsnew.html

Subscribe to the What’s New in Cisco Product Documentation as a Really Simple Syndication (RSS) feed and set content to be delivered directly to your desktop using a reader application. The RSS feeds are a free service and Cisco currently supports RSS version 2.0.

NoticesThe following notices pertain to this software license.

OpenSSL/Open SSL ProjectThis product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit (http://www.openssl.org/).

This product includes cryptographic software written by Eric Young ([email protected]).

This product includes software written by Tim Hudson ([email protected]).

License Issues

The OpenSSL toolkit stays under a dual license, i.e. both the conditions of the OpenSSL License and the original SSLeay license apply to the toolkit. See below for the actual license texts. Actually both licenses are BSD-style Open Source licenses. In case of any license issues related to OpenSSL please contact [email protected].

OpenSSL License:

Copyright © 1998-2007 The OpenSSL Project. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions, and the following disclaimer in the documentation and/or other materials provided with the distribution.

3. All advertising materials mentioning features or use of this software must display the following acknowledgment: “This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit (http://www.openssl.org/)”.

4. The names “OpenSSL Toolkit” and “OpenSSL Project” must not be used to endorse or promote products derived from this software without prior written permission. For written permission, please contact [email protected].

5. Products derived from this software may not be called “OpenSSL” nor may “OpenSSL” appear in their names without prior written permission of the OpenSSL Project.

viiCisco Service Node OSS/BSS Integration Guide

OL-16960-01

http://www.cisco.com/en/US/docs/general/whatsnew/whatsnew.html

http://www.openssl.org/



6. Redistributions of any form whatsoever must retain the following acknowledgment:

“This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit (http://www.openssl.org/)”.

THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT “AS IS”' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

This product includes cryptographic software written by Eric Young ([email protected]). This product includes software written by Tim Hudson ([email protected]).

Original SSLeay License:

Copyright © 1995-1998 Eric Young ([email protected]). All rights reserved.

This package is an SSL implementation written by Eric Young ([email protected]).

The implementation was written so as to conform with Netscapes SSL.

This library is free for commercial and non-commercial use as long as the following conditions are adhered to. The following conditions apply to all code found in this distribution, be it the RC4, RSA, lhash, DES, etc., code; not just the SSL code. The SSL documentation included with this distribution is covered by the same copyright terms except that the holder is Tim Hudson ([email protected]).

Copyright remains Eric Young’s, and as such any Copyright notices in the code are not to be removed. If this package is used in a product, Eric Young should be given attribution as the author of the parts of the library used. This can be in the form of a textual message at program startup or in documentation (online or textual) provided with the package.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

3. All advertising materials mentioning features or use of this software must display the following acknowledgement:

“This product includes cryptographic software written by Eric Young ([email protected])”.

The word ‘cryptographic’ can be left out if the routines from the library being used are not cryptography-related.

4. If you include any Windows specific code (or a derivative thereof) from the apps directory (application code) you must include an acknowledgement: “This product includes software written by Tim Hudson ([email protected])”.

THIS SOFTWARE IS PROVIDED BY ERIC YOUNG “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO

viiiCisco Service Node OSS/BSS Integration Guide

OL-16960-01



EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

The license and distribution terms for any publicly available version or derivative of this code cannot be changed. i.e. this code cannot simply be copied and put under another distribution license [including the GNU Public License].

GNU General Public License StatementVersion 2, June 1991

Copyright (C) 1989, 1991 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.

Preamble

The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change free software--to make sure the software is free for all its users. This General Public License applies to most of the Free Software Foundation's software and to any other program whose authors commit to using it. (Some other Free Software Foundation software is covered by the GNU Lesser General Public License instead.) You can apply it to your programs, too.

When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things.

To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the software, or if you modify it.

For example, if you distribute copies of such a program, whether gratis or for a fee, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights.

We protect your rights with two steps: (1) copyright the software, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the software.

Also, for each author's protection and ours, we want to make certain that everyone understands that there is no warranty for this free software. If the software is modified by someone else and passed on, we want its recipients to know that what they have is not the original, so that any problems introduced by others will not reflect on the original authors' reputations.

Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that redistributors of a free program will individually obtain patent licenses, in effect making the program proprietary. To prevent this, we have made it clear that any patent must be licensed for everyone's free use or not licensed at all.

The precise terms and conditions for copying, distribution and modification follow.

ixCisco Service Node OSS/BSS Integration Guide

OL-16960-01


• GNU GENERAL PUBLIC LICENSE

TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

This License applies to any program or other work which contains a notice placed by the copyright holder saying it may be distributed under the terms of this General Public License. The “Program”, below, refers to any such program or work, and a “work based on the Program” means either the Program or any derivative work under copyright law: that is to say, a work containing the Program or a portion of it, either verbatim or with modifications and/or translated into another language. (Hereinafter, translation is included without limitation in the term “modification”.) Each licensee is addressed as “you”.

Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running the Program is not restricted, and the output from the Program is covered only if its contents constitute a work based on the Program (independent of having been made by running the Program). Whether that is true depends on what the Program does.

1. You may copy and distribute verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and give any other recipients of the Program a copy of this License along with the Program.

You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee.

2. You may modify your copy or copies of the Program or any portion of it, thus forming a work based on the Program, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions:

a. You must cause the modified files to carry prominent notices stating that you changed the files and the date of any change.

b. You must cause any work that you distribute or publish, that in whole or in part contains or is derived from the Program or any part thereof, to be licensed as a whole at no charge to all third parties under the terms of this License.

c. If the modified program normally reads commands interactively when run, you must cause it, when started running for such interactive use in the most ordinary way, to print or display an announcement including an appropriate copyright notice and a notice that there is no warranty (or else, saying that you provide a warranty) and that users may redistribute the program under these conditions, and telling the user how to view a copy of this License. (Exception: if the Program itself is interactive but does not normally print such an announcement, your work based on the Program is not required to print an announcement.)

These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Program, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Program, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it.

Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Program.

In addition, mere aggregation of another work not based on the Program with the Program (or with a work based on the Program) on a volume of a storage or distribution medium does not bring the other work under the scope of this License.

xCisco Service Node OSS/BSS Integration Guide

OL-16960-01


3. You may copy and distribute the Program (or a work based on it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you also do one of the following:

a. Accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,

b. Accompany it with a written offer, valid for at least three years, to give any third party, for a charge no more than your cost of physically performing source distribution, a complete machine-readable copy of the corresponding source code, to be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,

c. Accompany it with the information you received as to the offer to distribute corresponding source code. (This alternative is allowed only for noncommercial distribution and only if you received the program in object code or executable form with such an offer, in accord with Subsection b above.)

The source code for a work means the preferred form of the work for making modifications to it. For an executable work, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the executable. However, as a special exception, the source code distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable.

If distribution of executable or object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place counts as distribution of the source code, even though third parties are not compelled to copy the source along with the object code.

4. You may not copy, modify, sublicense, or distribute the Program except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense or distribute the Program is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.

5. You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Program or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Program (or any work based on the Program), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Program or works based on it.

6. Each time you redistribute the Program (or any work based on the Program), the recipient automatically receives a license from the original licensor to copy, distribute or modify the Program subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties to this License.

7. If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Program at all. For example, if a patent license would not permit royalty-free redistribution of the Program by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Program.

If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply and the section as a whole is intended to apply in other circumstances.

xiCisco Service Node OSS/BSS Integration Guide

OL-16960-01


It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system, which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice.

This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License.

8. If the distribution and/or use of the Program is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Program under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License.

9. The Free Software Foundation may publish revised and/or new versions of the General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns.

Each version is given a distinguishing version number. If the Program specifies a version number of this License which applies to it and “any later version”, you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of this License, you may choose any version ever published by the Free Software Foundation.

10. If you wish to incorporate parts of the Program into other free programs whose distribution conditions are different, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally.

NO WARRANTY

11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

END OF TERMS AND CONDITIONS

xiiCisco Service Node OSS/BSS Integration Guide

OL-16960-01

OL-16960-01

C H A P T E R 1
Service Node Provisioning API
IntroductionThis chapter describes the implementation strategy and provisioning API provided for integrating backend systems with the Service Node. The following topics are covered:

• About the Service Node Provisioning API, page 1-1

• API Implementation (Secure HTTP POST), page 1-2

• Results and Error Handling, page 1-3

• Validation, page 1-3

• API Provisioning and Web GUI Provisioning, page 1-3

• Releases, Feature Suites, and the Provisioning API, page 1-4

• Related References, page 1-4

About the Service Node Provisioning APIBrand administrators, brand account users, and agents use the Service Node provisioning API to:

• Add, update, suspend, unsuspend, and delete customer accounts

• Optionally specify an external reference ID that can be correlated with the Service Node-generated customer ID

• Add, update, or remove phone numbers from customers

• Create and manage agents (brand administrator or brand account users only)

• View customer provisioning data

The information and examples in this guide assume that the Service Node is up and running at the Managed Services Provider (MSP) site and the brand and node configuration have already been established. Node and brand are static entries that must be pre-provisioned. Neither the node nor the brand can be dynamically created through the API, as they require the creation and maintenance of IP addresses, separate servers and DNS structures.

The Service Node currently has the following access levels:

• Node (HSP/system owner)

• Brand administrator and brand account users (HSP or VAR)

• Agent (VAR)

1-1Cisco Service Node OSS/BSS Integration Guide

Chapter 1 Service Node Provisioning API API Implementation (Secure HTTP POST)

Many carriers have their own BSS systems. Those systems may have their own levels of responsibility, as well as their own portals for those levels and give the provider various ways to manage their customers. While the Service Node has various hierarchical provisioning levels, it is not the goal of the API to replicate those levels for those leveraging the API. The API provides the necessary functions in order for upstream systems to send relevant information to the Service Node to provision customers.

The diagram in Figure 1-1 shows how the Service Node API accesses the SN over a secure connection and returns XML data that can be used by backend systems to activate and perform the initial provisioning for customers.

Figure 1-1 Service Node API Access

API Implementation (Secure HTTP POST)The Service Node provisioning API uses the HTTP POST method to query and manipulate data on the Service Node. All data is transmitted over a secure connection.

All data passed to the API is in the form of name-value pairs set in the header of the HTTP POST request to the API web application. The name-value pairs can be placed into the header of the request either via a HTML form or programmatically.

Most parameters have a single value (except for some of the phone number parameters, which can have multiple values). Most programming languages provide libraries to arbitrarily attach name-value pairs to any HTTP POST request. The API will consume the name-value pairs in the request header and, if valid, perform the requested function.

2717

50

SN

ServiceNode APIOSS

POST

XML

SSL HTTP


OL-16960-01

Chapter 1 Service Node Provisioning API Results and Error Handling

Results and Error HandlingThe HTTP response from the API is in XML, which is contained in the body of the HTTP response. The result value is either 1 (success) or 0 (failure) and indicates whether the call executed successfully or not. If the API call was unsuccessful, the result response will contain one or more <error> elements with a text string that indicates the reason or reasons for the failure.

For example, a successful response for addCustomer will be formatted as shown below:

<?xml version="1.0" encoding="UTF-8"?><response> <result>1</result> <errors/> <customer> <id>1000.domain.com</id> </customer></response>

In the above example, the customer was added successfully, so the result is 1, and no error messages are displayed.

ValidationThe API expects correct data for many fields. Unless specifically noted, values specified are not validated for duplicates and data validation is not performed. For example, the API will accept incorrect combinations of values for address fields.

The getCustomerAlerts function can be used to check the validity of the customer's configuration against the customer's release set. See the “getCustomerAlerts” section on page 2-32.

Note Phone numbers added through the API or the Service Node Web administration GUI are assumed to be routable E.164 numbers. These numbers are not validated through the API or the Web administration GUI.

API Provisioning and Web GUI ProvisioningThe Service Node provisioning API enables Managed Service Providers to add, retrieve or modify all customer data that can be input, edited or viewed through the Web-based Service Node administration GUI for customer provisioning. This includes all information needed to establish a customer on the system and ensure that calls can be routed. The API can also be used to create and manage agents of a brand. Many functions of the API can be called with agent-level credentials to limit access to customer data to only the customers that belong to that agent.

The api_id field, which is used for correlating a Service Node-generated customer ID with an external reference ID, is only accessible through the API and cannot be viewed, modified, or deleted through the Web-based Service Node provisioning portal.


OL-16960-01

Chapter 1 Service Node Provisioning API Releases, Feature Suites, and the Provisioning API

If your system requires correlation with an external reference ID, you must use the API to establish, maintain, or remove the correlation with the api_id field. Changes made to other fields using the Web interface do not affect the api_id.

The information that can be retrieved through the API includes all customer information fields that are input using the API, plus additional Service Node-generated configuration information, such as the installation handshake information, customer ID, and IP address.

You can modify the customer configuration settings supported by the API using the Web interface, and the API will correctly reflect the changes.

Releases, Feature Suites, and the Provisioning APIEach customer provisioning configuration page displayed on the Edit Customer page of the Brand Administration portal is defined as a widget and the file containing its definition is included in the set of files that comprise a release for a given product set, such as the UC500.

In order to be accessible to the provisioning API, the XML widget for a feature to be configured must also be referenced by the FEATURESUITE file for the release that is associated with the customer’s release group. The FEATURESUITE file is an XML file that lists all the feature configuration widgets that are included with the release.

For example, the provisioning page for configuring UC500 equipment options is defined through a widget named UC500. The UC500 widget is also found in the release as a file named UC500. In order for a widget to be an active part of the customer provisioning process, the widget must be defined within the release and referenced by the FEATURESUITE file.

• The provisioning API ignores any references to widgets that are not referenced by the FEATURESUITE file in the release associated with the customer, and no errors are displayed.

• Removing a widget from the FEATURESUITE file for a release does not remove any customer data previously associated with the widget. If the widget is re-added to the FEATURESUITE for the release, existing customer data is again available for viewing or editing through either the API or Brand Administration GUI.

For more information about releases, feature suites, and provisioning, see the Cisco Service Node Administration Guide.

Related ReferencesRefer to the following standards documents for more information:

• Hypertext Transfer Protocol 1.1, available at

http://www.w3.org/Protocols/rfc2616/rfc2616.html

• Hypertext Markup Language 2.02, available at

http://www.w3.org/MarkUp/html-spec/html-spec_toc.html


OL-16960-01

OL-16960-01

C H A P T E R 2
Provisioning API Function Reference
OverviewThis chapter provides a function reference for the Service Node provisioning API and is organized into the following sections:

• Function Reference, page 2-1

• Connecting to the API, page 2-73

• Error Messages, page 2-73

• Supported Timezones, page 2-74

• Specifying Custom Provisioning Parameters using the API, page 2-74

Function ReferenceThis section provides a complete function reference for the Service Node provisioning API. The following information is provided for each function:

• Intended usage

• Input parameters, including required/optional parameters, description, constraints, and whether or not multiple values can be specified

• Output fields

• Example XML output

The functions documented in this section are categorized as follows:

• Customer Management Functions, page 2-2

• Agent Management Functions, page 2-62


Chapter 2 Provisioning API Function Reference Customer Management Functions

Customer Management FunctionsThis section documents the following customer management functions:

• addCustomer, page 2-3

• updateCustomerNumbers, page 2-7

• getCustomer, page 2-13

• getCustomerAlerts, page 2-32

• getCustomerList, page 2-34

• getAvailableInventoryNumbers, page 2-38

• updateCustomer, page 2-40

• shutdownCustomer, page 2-56

• suspendCustomer, page 2-58

• unsuspendCustomer, page 2-60


OL-16960-01


addCustomerUse the addCustomer function to add a new customer account under a brand on the Service Node.

The addCustomer function only adds basic account information such as customer address, billing address, contact information, and the release group to use for provisioning.

None of the input parameters for addCustomer accept multiple values.

• To provision phone numbers, use the updateCustomerNumbers function (see updateCustomerNumbers, page 2-7).

• To provision customer premises equipment (CPE), use the updateCustomer function (see updateCustomer, page 2-40).

Input Parameters

Table 2-1 addCustomer — Input Parameters

Parameter Name Required? Description

addCustomer — API Access and Correlation

api_username Y Valid brand administrator, brand user, or agent username

api_password Y Brand administrator, brand user, or agent password for the specified api_username

api_action Y Name of the API function being called

This parameter is case-sensitive and must be “addCustomer” for this function.

api_id N External reference ID for correlation with Managed Services Provider (MSP) back-end systems (optional)

addCustomer — General Information

businessname Y Customer business name

If the number of characters specified is greater than can be displayed on CPE, the business name will be truncated on the phone display and on the installation handshake screen.

release_group Y Release group for this customer

The release group controls the equipment configuration selections that are available through the API and customer provisioning GUI and the configuration files and software that are downloaded to customer premises equipment during installation.

This parameter is case-sensitive and must be the name of a valid release group associated with the brand. Release groups are specified using the following format:

<product-set>, <release-ID>

For example: UC500, BRAND_RELASE_SN


OL-16960-01


timezone Y Local timezone at the customer site

This parameter is case-sensitive and must be a valid timezone in the supported Region/Timezone format.

For example: America/Chicago

For more information, see the “Supported Timezones” section on page 2-74.

agentname N Associates the specified agent with this customer

This value is case-sensitive and must be a valid agent name for this brand.

allow_updates N Specifies whether the customer is entitled to receive software updates (firmware upgrades)

• If Allow Software Updates is enabled at the brand level on the System > Settings page of the Brand Administration portal, this setting is ignored if it is specified through API. When getCustomer is called for customers of the brand, the output “yes, enabled at the System level” is displayed for this field.

• If Allow Software Updates is not enabled at the brand level, specify one of the following values:

– yes — Enable software updates for this customer. The customer’s CPE is assumed to be entitled to software upgrades through a SmartNET contract.

– no — Disable software updates for this customer.

addCustomer — Service Contact Information

service_address Y Customer site address (street address)

service_city Y Customer site address (city)

service_state N Customer site address (state)

A service_state is optional, because many international addresses do not include a state.

service_postal Y Customer site address (postal code)

service_country Y Customer site address (country)

Must be a valid ISO 3166-1 Alpha-2 country code. These codes can be obtained from www.iso.org.

service_firstname N Service contact first name

service_lastname N Service contact, last name

service_email N Service contact e-mail address. Must be a valid e-mail address.

service_phone1 N Service contact phone number, primary

service_phone2 N Service contact phone number, secondary

addCustomer — Billing Information

billing_address Y Customer billing address (street address)

billing_city Y Customer billing address (city)

Table 2-1 addCustomer — Input Parameters (continued)



OL-16960-01


Output Parameters

billing_state N Customer billing address (state). This parameter is optional, because it is not needed for some international addresses.

billing_postal Y Customer billing address (postal code)

billing_country Y Customer billing address (country). Must be a valid ISO 3166-1 Alpha-2 country code. These are listed at www.iso.org.

billing_firstname Y Customer billing contact, first name

billing_lastname Y Customer billing contact, last name

billing_email Y Customer billing contact, e-mail address. Must be a valid e-mail address.

billing_phone1 N Customer billing phone number, primary

billing_phone2 N Customer billing phone number, secondary

addCustomer — Security Information (Optional Customer-specified Password for Handshake

password N Customer-specified installation handshake password to be used in place of the Service Node-generated installation handshake password

If specified, must be an alphanumeric value and contain a minimum of 2 characters.

password_verify *N Second entry of customer-specified installation handshake password for verification

* Required if password parameter is specified. If specified, must match the password parameter (alphanumeric, minimum of 2 characters).

Table 2-2 addCustomer — Output Parameters

XML TagAlways Present?

Multiple Values?

Parent XML Tag Description

response Y N None Root XML tag

result Y N response “1” = Success.

“0” = Failure.

errors Y N response Base XML tag for error tags

error N* Y errors * Only present when result = 0.

Details problems with the API call

customer N* Y response Base XML tag for customer information

id N* N customer * Present when result = 1.

Returns the Service Node-generated customer ID, in the format <customer_number>.<brand-domain>, for example, 12345.mybrand.com.

Table 2-1 addCustomer — Input Parameters (continued)



OL-16960-01


Sample XML Output

<?xml version="1.0" encoding="UTF-8"?><response> <result>1</result> <errors/> <customer> <id>99999.mybrand.com</id> </customer></response>


OL-16960-01


updateCustomerNumbersUse the updateCustomerNumbers function to manage phone numbers and carrier settings for the customer’s account. Specify one of the following number actions when using updateCustomerNumbers:

• save_number — add a single phone number or a range of phone numbers to the customer’s account.

• save_carrier — add or update carrier settings for a customer.

• delete_carrier — remove carrier-specific settings related to the customer such as parent_ number or emergency_number for the specified carrier.

• delete_all — remove all phone numbers and carriers from the customer’s account.

• delete_number — remove a single phone number from the customer’s account. If the number being deleted is the last remaining customer number for that carrier, the carrier settings are also deleted.

For example, if the customer has three numbers that are associated with a particular carrier, the carrier settings are only removed when the third and final number is deleted from the account.

Tip The list of valid carriers and their settings are specific to a given Service Node and the call routing configuration for the node and the brand.

One way to determine the node- and carrier-specific parameters and values required for adding and updating customer phone numbers is to log in to the Brand Administration portal Web GUI and perform the steps to add or edit the customer’s phone numbers. You can also use browser-based tools to view HTML page source.

The following guidelines apply to using the updateCustomerNumbers function:

• Phone numbers can not be added without specifying a carrier.

It may be that carrier-customer settings cannot be applied until after the number has been stored for the customer, but the carrier field must always be present when adding numbers.

• The API does not enforce the same order of operations as the Edit Customer Web GUI. When the first phone number is added to the customer from a carrier, the system saves the carrier settings with default settings.

• Carrier-specific parameter names always begin with

<carrier-id>:

where <carrier-id> is case-sensitive and must exactly match the routlet ID of the carrier routlet associated with the phone numbers to be added or removed.

For example, if the carrier routlet ID on the Service Node is carrier-01.rg1.mynode.com, the value for <carrier-id> must also be specified as carrier-01.rg1.mynode.com

Note The Edit Customer > Configuration > Phone Numbers page on the Brand Administration portal displays the carrier routlet description in the pull-down menu for selecting the carrier, not the actual carrier routlet ID that is required by the provisioning API. The carrier description and the carrier routlet ID (in parentheses) are displayed in the Add Number section heading bar.

For example: Add Number - VoIP Carrier (carrier01.rg1.mynode.com).

You can also view the carrier routlet ID in the HTML page source.


OL-16960-01


• The specified carrier routlet must be in the same routegroup as the brand.

• Depending on the carrier, multiple calls to updateCustomerNumbers may be required.

Typically, two calls are required when adding phone numbers for a new customer:

– First, updateCustomerNumbers is called with the save_number action to add phone numbers for the specified carrier. To add a range of phone numbers, specify the first phone number and use the count parameter to add consecutive numbers.

– Next, updateCustomerNumbers is called with the save_carrier action to specify global settings required by the carrier such as designating one of the numbers added in the first step as the parent or emergency number.

• To replace a phone number with a different number, delete the old phone number, then add the replacement phone number.

• To remove multiple numbers from the customer’s account, you must call updateCustomerNumbers with the delete_number action once for each number to be deleted.

• Phone numbers for BRI, PRI and FXS lines are associated with different types of carrier routlets; make sure that the correct carrier is specified when adding these types of numbers.

• A customer can have multiple carriers, for example, one carrier for VoIP numbers and one POTS carrier for FXS-DID numbers.

• Once phone numbers have been added or modified, use the getCustomer function to retrieve and verify the new configuration, as described in the “getCustomer” section on page 2-13.

• None of the input parameters specified with updateCustomer can have multiple values.

Input Parameters

Table 2-3 updateCustomerNumbers— Input Parameters


updateCustomerNumbers — Required Input Parameters for all Actions

api_username Y Must be a valid brand administrator, brand user, or agent ID.

When updateCustomerNumbers is called with an agent ID and password, the customer_id or api_id specified must correspond to a customer that is associated with that agent.


api_action Y Name of the API function being called. This parameter is case-sensitive and must be “updateCustomerNumbers” for this function.

api_id N* ID for correlation with the customer’s back-end systems

* Required only if customer_id is not specified.

customer_id Y* * Not required if api_id is specified.

If both customer_id and api_id are specified, customer_id is used.

For example: 99999.mybrand.com


OL-16960-01


number_action Y Phone number provisioning action to perform. This parameter is case-sensitive and must be one of the following:

• save_number — adds a single phone number or a range of phone numbers to the customer’s account

• save_carrier — specifies global configuration settings required by the carrier for such as a parent number or emergency services number.

• delete_carrier — removes global carrier settings for the customer such as parent_number or emergency_number.

• delete_number — deletes a single number from the customer’s account. If the number being deleted is the last remaining customer number for that carrier, the carrier settings are also deleted.

• delete_all — deletes all carrier settings and phone numbers from the customer’s account.

updateCustomerNumbers — Example Input Parameters for save_number Action

<carrier-id>:carrier Y Carrier routlet ID associated with the numbers to be added

The parameter value is case-sensitive and must exactly match the carrier routlet ID as configured on the Node Administration portal. The carrier routlet must be in the same routegroup as the brand.

For example:

carrier-01.rg1.mynode_com:carrier = “carrier-01.rg1.mynode.com”

<carrier-id>:customer_id Y Service Node-generated customer ID, in the format <carrier-id>:<customer-ID>.<brand-domain>

For example:

carrier-01.rg1.mynode.com:customer_id = “carrier-01.rg1.mynode.com:4199.mybrand.com”

<carrier-id>:number Y Phone number to be added or first phone number in a range of phone numbers to be added

At least one phone number must be specified when using the save_number action.

The number can be selected from the inventory on the Service Node (see the “getAvailableInventoryNumbers” section on page 2-38) or a non-inventory number, but the number must be associated with the specified carrier.

For example:

carrier-01.rg1.mynode.com:number = “19998888888”

Table 2-3 updateCustomerNumbers— Input Parameters (continued)



OL-16960-01


<carrier-id>:count N Integer that specifies how many consecutive phone numbers to add

A count parameter is used in conjunction with <carrier-id>:number to specify a range of numbers.

For example:

If carrier-01.rg1.mynode.com:number = “12145558888”

and

carrier-01.rg1.mynode.com:count = “10”

then 10 numbers are added, beginning with 12145558888 and ending with 12145558897.

updateCustomerNumbers — Example Input Parameters for save_carrier Action

<carrier-id>:carrier Y Carrier routlet ID

This parameter name is case-sensitive and must match the carrier routlet ID as configured on the Node Administration portal. The carrier routlet must be in the same routegroup as the brand.

For example:

carrier-01_rg1_mynode_com:carrier = “carrier-01.rg1.mynode.com”


For example:

carrier-01.rg1.mynode_come:customer_id = “carrier-01.rg1.mynode.com:41299.mybrand.com”

<carrier-id>:parent_number N* Parent number for SIP registration or main number, if required by the carrier

* For CCA compatibility, a parent number for SIP registration is required for VoIP carrier phone numbers.

Local trunk phone numbers (FXS-DID, BRI, PRI) do not typically require a parent number.

For example: carrier-01.rg1.mynode.com:parentnumber = “12145558888”

<carrier-id>:emergency_number Y Phone number to use as the calling line ID for emergency calls. An emergency number is required and must be one of the customer’s existing numbers.

For example: carrier-01.rg1.mynode.com:emergencynumber = “12145558888”

Note Although the emergency_number parameter is required, CCA always uses the parent number for the emergency number and ignores this setting.

<carrier-id>:username N Username for SIP registration for VoIP phone numbers, if required by the carrier

For example: carrier-01.rg1.mynode.com:username = “jsmith0123”




OL-16960-01


<carrier-id>:password N Password for SIP registration for VoIP phone numbers, if required by the carrier

For example: carrier-01.rg1.mynode.com:password = “12345678”

<carrier-id>:significant_digits N For BRI phone numbers, this parameter specifies the number of significant digits, as required by the carrier (for example, 7 or 10 for NADP customers).

For example:

carrier-01.rg1_mynode.com:significant_digits = “7”

updateCustomerNumbers — Example Input Parameters for delete_number Action

<carrier-id>:carrier Y Carrier routlet ID associated with the number to be deleted

This parameter name is case-sensitive and must exactly match the carrier routlet ID as configured on the Node Administration portal. The carrier routlet must be in the same routegroup as the brand.

For example: carrier-01.rg1.mynode.com:carrier = “carrier-01.rg1.mynode.com”

<carrier-id>:number Y A single phone number to be deleted from the customer’s account


For example: carrier-01.rg1.mynode.com:customer_id: = “4199.mybrand.mynode.com”

updateCustomerNumbers — Example Input Parameters for delete_carrier Action

<carrier-id>:carrier Y The delete_carrier action removes all carrier-specific settings (such as parent number, emergency number, username, and password) for the specified carrier (phone numbers are not modified or removed).

Specify the carrier routlet ID that corresponds to the carrier whose settings will be deleted.

This parameter name is case-sensitive and must exactly match the carrier routlet ID as configured on the Node Administration portal. The carrier routlet must be in the same routegroup as the brand.

For example: carrier-01.rg1.mynode.com:carrier = “carrier-01.rg1.mynode.com”


For example: carrier-01.rg1.mynode_com:customer_id = “41299.mybrand.mynode.com”

updateCustomerNumbers — Example Input Parameters for delete_all Action

None N/A Deletes all phone numbers and carrier settings provisioned for this customer

No other parameters are needed when delete_all is specified as the number_action.




OL-16960-01


Output Parameters

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?><response> <result>1</result> <errors/></response>

Table 2-4 updateCustomerNumbers — Output Parameters


Multiple Values?




“0” = Failure.





OL-16960-01


getCustomerThe getCustomer function is a read-only function that returns all customer configuration data, including phone numbers and carrier settings. The following tips and guidelines apply to using the getCustomer function:

Note For Release 3.0 CPE, the XML output of getCustomer is also used internally to generate IOS device configuration and set additional configuration parameters. As a result, the XML output contains information that cannot be configured through the provisioning API, such as SIP proxy configuration data and translation rules for mapping phone numbers and extensions.

• You can call the getCustomer function before calling updateCustomer or shutdownCustomer to retrieve all of the required customer information from the database.

• Either the Service Node-generated customer_id or the api_id (or both) can be used when calling getCustomer. The customer_id is used if both are specified.

• getCustomer also returns the customer's installation handshake information (service provider ID, customer ID and customer password), as well as the public IP address for the customer's phone system.

• The ip value returned by getCustomer contains the IP address of the customer's UC500 platform. If the ip value returned by getCustomer is 0.0.0.0, this means that the customer has not completed the installation handshake that occurs when the CPE is first installed.

The <customer><id> value returned in the XML output from getCustomer is in the form <customer_id>.<brand_domain>. For example:

<customer><id>1000.my_brand.com</id>

• You can construct the fully qualified domain name (FQDN) of the UC500 by preceding the <customer><id> value returned with “proxy”, for example, “proxy.1000.my_brand.com”.

You can also display the complete XML output of getCustomer through the Brand Administration Web portal GUI by performing the following steps:

Step 1 Log in to the Service Node Brand Administration portal.

Step 2 Choose Customers to display the Customer List page.

Step 3 Locate a customer in the list and click on the customer name to select the customer.

Step 4 Choose View from the menu at the top of the Customers List page.

Step 5 Scroll to the bottom of the page and click View XML.

The XML configuration output displays in a new browser window.


OL-16960-01


Input Parameters

Note For more detailed descriptions of the output for getCustomer, see the input parameter listing in the “updateCustomer” section on page 2-40.

Output Parameters

Table 2-5 getCustomer — Input Parameters

Parameter Name Required?Multiple Values? Constraints

api_username Y N Must be a valid brand administrator, brand user, or agent ID.

When getCustomer is called using agent-level credentials, the customer_id or api_id specified must correspond to a customer that is associated with that agent.

api_password Y N Brand administrator, brand user, or agent password for the specified api_username

api_action Y N Name of the API function being called. This parameter is case-sensitive and must be “getCustomer” for this function.

api_id N* N * Required only if customer_id is not specified.

customer_id Y* N * Not required if api_id is specified.


Table 2-6 getCustomer — Output Parameters

XML Tag Always Present?

Multiple Values?


getCustomer — API Results



“0” = Failure.

errors Y N response Base XML tag for error tags.

error N* Y errors * Present when result = 0.

Details problems with the API call.

getCustomer — Customer Information

customer N* Y response Base XML tag for customer information.

* Present when result = 1.

id N* N customer * Present when result = 1.

api_id N* N customer * Present when result = 1.

businessname N* N customer * Present when result = 1.


OL-16960-01


release_group N* N customer * Present when result = 1.

timezone N* N customer * Present when result = 1.

agent_id N* N customer * Present when result = 1.

service_address N* N customer * Present when result = 1.

service_city N* N customer * Present when result = 1.

service_state N* N customer * Present when result = 1.

service_postal N* N customer * Present when result = 1.

service_country N* N customer * Present when result = 1.

service_firstname N* N customer * Present when result = 1.

service_lastname N* N customer * Present when result = 1.

service_email N* N customer * Present when result = 1.

service_phone1 N* N customer * Present when result =1 and a service phone number is specified for this field.

service_phone2 N* N customer * Present when result =1 and a service phone number is specified for this field.

billing_address N* N customer * Present when result = 1.

billing_city N* N customer * Present when result = 1.

billing_state N* N customer * Present when result = 1.

billing_postal N* N customer * Present when result = 1.

billing_country N* N customer * Present when result = 1.

billing_firstname N* N customer * Present when result = 1.

billing_lastname N* N customer * Present when result = 1.

billing_email N* N customer * Present when result = 1.

billing_phone1 N* N customer * Present when result =1 and a billing phone number is specified for this field.

billing_phone2 N* N customer * Present when result =1 and a billing phone number is specified for this field.

suspended N* N customer * Present when result = 1.

ip N* N customer * Present when result = 1.

allow_updates N* N customer *Present when result = 1.

The output indicates whether software updates are allowed for the customer and whether this setting overrides the brand-wide default (for example, “yes”, “no”, or “yes, enabled at the System level”.

getCustomer — Phone Numbers

phonenumbers N* N customer * Present when result = 1 and numbers are present for this customer

XML container tag for a list of E.164 phone numbers

Table 2-6 getCustomer — Output Parameters (continued)


Multiple Values?



OL-16960-01


numbers N* N phonenumbers * Present when result =1 and numbers are present for this customer.

XML container tag for a list of E.164 phone numbers

instance N* Y numbers * Present when result = 1 and numbers are present for this customer.

XML container tag for a phone number and its associated carrier

number N* Y instance * Present when result =1 and the customer has phone numbers associated with their account.

E.164 phone number

carrier N* Y instance * Present when result =1 and the customer has phone numbers associated with their account.

Carrier routlet ID for the carrier associated with the specified phone number

getCustomer XML Output — Carrier Settings

carriers N* N customer * Present when result = 1 and numbers are present for this customer.

XML container tag for a list of carriers

carrier N* Y carriers * Present when result = 1 and numbers are present for this customer.

XML container tag for a single carrier and its associated settings

carrier N* Y carrier * Present when result = 1 and numbers are present for this customer.

Carrier routlet ID

username N* N carrier * Present when result = 1, numbers are present for this customer, and the parameter is required for the associated carrier.

Username for SIP registration

password N* N carrier * Present when result = 1, numbers are present for this customer, and the parameter is required for the associated carrier.

Password for SIP registration

parent_number N* N carrier * Present when result = 1, numbers are present for this customer, and the parameter is required for the associated carrier.

Parent number for SIP registration



Multiple Values?



OL-16960-01


emergency_number N* N carrier * Present when result = 1 and numbers are present for this customer.

Calling Line ID phone number for Emergency Services calls

sip_proxysip_proxy_methodsip_registrarsip_registrar_methodrealmcca_provider_name

N* N carrier * Present when result = 1.

Additional SIP trunking information used internally for device configuration (not set through the API).

integrated_call_routing

N* N carrier * Present when result = 1 and phone numbers are present for this account.

This parameter is used internally for device configuration and is not set through the API.

• A value of “1” in this field indicates that the associated carrier is configured for integrated call routing (that is, calls are routed through the Service Node).

• A value of “0” indicates the customer is deployed with decoupled call routing or local trunks only.

getCustomer XML Output — UC500 Equipment Configuration Settings

uc500 N* N customer * Present when result = 1.

XML container for UC500 equipment configuration settings

description N* N uc500 * Present when result = 1.

ezvpnpasswd N* N uc500 * Present when result =1.

Service Node-generated password for EZVPN.


maxchannels N* N uc500 *Present when result=1 and UC500 parameters are present.

codecpref N* N uc500 *Present when result=1 and UC500 parameters are present. Selected audio codec preference: g711_first, g729_first, or g729_only.

qos_priorityqos_bandwidth

N* N uc500 *Present when result=1 and UC500 parameters are present.


model N* N uc500 *Present when result=1.

UC500 model (part number) for this UC500 configuration

expansionslot N* N uc500 *Present when result=1 and UC500 parameters are present.

Voice interface card part number for the UC500 expansion slot for this customer



Multiple Values?



OL-16960-01


fxs_mode N* N uc500 *Present when result=1 and UC500 parameters are present.

FXS signaling type, either fxs or did, for this customer

bri_switch_type N* N uc500 *Present when result=1, UC500 parameters are present, and the customer is provisioned with a UC500 model or expansion slot with BRI ports.

pri_switch_type N* N uc500 *Present when result=1 and UC500 parameters are present.

pri_type N* N uc500 *Present when result=1 and UC500 parameters are present.

linecode N* N uc500 *Present when result=1 and UC500 parameters are present.

framing N* N uc500 *Present when result=1 and UC500 parameters are present.

timeslots N* N uc500 *Present when result=1 and UC500 parameters are present.

upload_speed N* N uc500 * Present when result = 1 and UC500 parameters are present.

Customer’s broadband connection upload speed for this WAN connection

hostname N* N uc500 *Present when result=1 and UC500 parameters are present.

Host name for the customer’s UC500 device

enable_password N* N uc500 *Present when result=1 and UC500 parameters are present.

Cisco IOS enable password for the customer’s UC500 device

phone_firmware_filesfirmware_filefile_namemodelload_file_namebinary

N* N uc500 *Present when result=1

Phone firmware file names and version information associated with the release.

These parameters are used internally for device configuration and cannot be set through the API.

vid N* N uc500 *Present when result=1

Returns either “1” (the default) or the MAC address of the UC500 device.

When the value returned is “1,” the MAC address will be updated to the actual MAC address at the next handshake with the Service Node.

Note The remainder of the port information returned by getCustomer (bri_ports, bri_port, slot, port, pri_ports, fxo_ports, fxo_port, fxs_ports, fxs_ports, fxsdid_ports, fxsdid_port, ext_name, and ext_number) are used internally for device configuration and are not set through the API.

bri_ports N* N uc500 *Present when result=1 and the customer configuration specifies BRI ports.

XML container for BRI port information

bri_port N* Y bri_ports *Present when result=1 and the customer configuration specifies BRI ports.

XML container for BRI slot/port numbers



Multiple Values?



OL-16960-01


slot N* Y bri_portpri_portfxo_port fxs_portorfxsdid_port

*Present when result=1

UC500 slot number for the associated port type

port N* Y bri_portpri_portfxo_portfxs_portorfxsdid_port

*Present when result=1

UC500 port number for the associated port type

pri_ports N* N uc500 *Present when result=1 and the customer configuration specifies PRI ports.

XML container for PRI port information

pri_port N* Y pri_ports *Present when result=1 and the customer configuration specifies PRI ports.

XML container for PRI slot and port numbers

fxo_ports N* N uc500 *Present when result=1 and the customer configuration specifies FXO ports.

XML container for FXO port information

fxo_port N* Y fxo_ports *Present when result=1 and the customer configuration specifies FXO ports.

XML container for FXO slot and port numbers

fxs_ports N* N uc500 *Present when result=1 and the customer configuration specifies FXS ports.

XML container for FXS port information

fxs_port N* Y fxs_ports *Present when result=1 and the customer configuration specifies FXS ports.

XML container for FXS slot and port numbers

fxsdid_ports N* Y uc500 *Present when result=1 and the customer configuration specifies FXS ports.

XML container for FXS/DID port information

fxsdid_port N* Y fxsdid_ports *Present when result=1 and the customer configuration specifies FXS ports.

XML container for FXS/DID slot and port numbers

ext_number N* Y fxsdid_port *Present when result=1 and the customer configuration specifies FXS ports.

Extension name for this FXS/DID port



Multiple Values?



OL-16960-01


ext_name N* Y fxsdid_port *Present when result=1 and the customer configuration specifies FXS ports.

Extension number for this FXS/DID port

getCustomer — UC500 WAN Configuration Settings

wan N* N customer * Present when result = 1 and WAN configuration settings are present.

XML container tag for the UC500 WAN connection settings

type N* N wan * Present when result=1 and WAN configuration settings are present.

WAN connection type: DHCP or STATICIP

ip N* N wan * Present when result=1 and the WAN type is STATICIP.

IP address with CIDR for this WAN connection

gateway N* N wan * Present when result =1 and the WAN type is STATICIP.

IP address of the gateway for this STATICIP connection

dns1 N* N wan * Present when result=1 and the WAN type is STATICIP.

IP address of the primary DNS server for this STATICIP connection

dns2 N* N wan * Present when result=1 and the WAN type is STATICIP.

IP address of the primary DNS server for this STATICIP connection

getCustomer — Data and Voice LAN Settings

sbcs_lan N* N customer *Present when result=1 and the customer configuration includes these settings.

XML container for SBCS LAN settings

data_lan N* N sbcs_lan *Present when result=1 and the customer configuration includes these settings.

Fist three octets of the data LAN IP address for the customer’s SBCS

voice_lan N* N sbcs_lan *Present when result=1 and the customer configuration includes these settings.

Fist three octets of the voice LAN IP address for the customer’s SBCS

getCustomer — Extension Assignments

uc500extensions N* N uc500 * Present when result = 1 and the customer configuration includes these settings.XML container tag for UC500 extension information



Multiple Values?



OL-16960-01


vm_extension N* N uc500extensions

*Present when result=1 and the customer configuration includes these settings.

3-digit extension for voice mail

aa_extension N* N uc500extensions


3-digit extension for Auto Attendant

voip_extensions N* N uc500extensions


XML container tag for a single VoIP extension assignment

voip_extension N* Y voip_extensions


XML container tag for configuration data associated with a single VoIP extension

ext_number N* N voip_extension *Present when result=1 and the customer configuration includes these settings.

Number associated with this VoIP extension

fname N* N voip_extension *Present when result=1 and the customer configuration includes these settings.

First name of the user associated with this VoIP extension

lname N* N voip_extension *Present when result=1 and the customer configuration includes these settings.

Last name of the user associated with this VoIP extension

mac N* N voip_extension *Present when result=1.

MAC address of the device associated with this VoIP extension

model N* N voip_extension *Present when result=1; only used if the MAC address is provided.

Model identifier of the device associated with this VoIP extension

username N* N voip_extension *Present when result=1 and the customer configuration includes these settings.

Username associated with this VoIP extension

password N* N voip_extension *Present when result=1 and the customer configuration includes these settings.

Password associated with this VoIP extension

dn_number N* N voip_extension *Present when result=1 and VoIP extensions are specified for the customer.

This parameter is used internally for device configuration and cannot be set through the API.



Multiple Values?



OL-16960-01


ephone_number N* N voip_extension *Present when result=1 and VoIP extensions are specified for the customer.


fxs_ports N* N uc500extensions

*Present when result=1 and FXS ports are specified in the configuration.

XML container for FXS port information

fxs_port N* Y fxs_ports *Present when result=1 and FXS ports are specified in the configuration.

XML container tag for FXS port information

slot N* N fxs_port *Present when result=1 and FXS ports are specified in the configuration.

Slot number associated with this FXS port

port_number N* N fxs_port *Present when result=1 and FXS ports are specified in the configuration.

Port number associated with this FXS port.

dial_peer_number N* N fxs_port *Present when result=1 and FXS extensions are specified for the customer.

This parameters is used internally for device configuration and cannot be set through the API.

extension N* N fxs_port *Present when result=1 and FXS extensions are specified in the configuration.

Number associated with this FXS extension

fname N* N fxs_port *Present when result=1 and the customer configuration includes these settings.

First name of the user associated with this FXS extension

lname N* N fxs_port *Present when result=1 and the customer configuration includes these settings.

Last name of the user associated with this FXS extension

did N* N fxs_port *Present when result=1 and a DID number is associated with this port.

DID number associated with this FXS port

use_auto_assign N* N uc500extensions

*Present when result=1 and VoIP extensions are specified for the customer.




Multiple Values?



OL-16960-01


max_ephones N* N uc500extensions

*Present when result=1 and VoIP extensions are specified for the customer.


getCustomer — UC500 Line Assignments for Inbound Call Routing

uc500lines N* N customer *Present when result=1 and the customer configuration includes these settings.

XML container tag for UC500 inbound call routing information

cca_translation_rule,tr_number,rule, rule-numberrule_from, rule_to, did_type, tr_number, aa_or_vm_target,

N* Y cca_translation_rules

*Present when result=1 and extension assignments are configured.

These parameters are used internally for device configuration and are not set through the API.

fxo_inbound N* N uc500lines *Present when result=1 and the customer configuration includes these settings.

XML container tag for inbound FXO line information

aa_pilotvm_pilot

N* N uc500lines Pilot numbers for Auto Attendant and voice mail for CCA-compatible configuration


fxo_port N* Y fxo_inbound *Present when result=1 and the customer configuration includes these settings.

XML container tag for the port associated with this inbound FXO line

slot N* Y fxo_port *Present when result=1 and the customer configuration includes these settings.

Slot number for this FXO port

port_number N* Y fxo_port *Present when result=1 and the customer configuration includes these settings.

Port number for this FXO port

line_number N* Y fxo_port *Present when result=1 and the customer configuration includes these settings.

Phone number associated with this inbound FXO line

destination N* Y fxo_port *Present when result=1 and the customer configuration includes these settings.

Destination extension for to this inbound FXO line



Multiple Values?



OL-16960-01


getCustomer — Dial Plan Settings

dialplan N* N customer *Present when result=1 and the customer configuration includes these settings.

XML container tag for dial plan settings

area_code_size N* N dialplan *Present when result=1 and the customer configuration includes these settings.

Number of digits for the area code (this parameter is not set through the API).

phone_number_size N* N dialplan *Present when result=1 and the customer configuration includes these settings.

For NADP customers, returns 7 or 10 to indicate whether 7-digit or 10-digit dialing is used.

area_code N* N dialplan *Present when result=1 and the customer configuration includes these settings.

For NADP customers, returns the area code if phone_number_size is set to 7.

secondary_dialtone_access_code

N* N dialplan *Present when result=1 and the customer configuration includes these settings.

Returns a value from 0 to 9, inclusive, that specifies the access code for external calling.

getCustomer — User Permissions Settings

user_permissions N* N customer * Present when result = 1 and the customer configuration includes these settings.

XML container for user permissions associated with a particular feature (for the current release, this is used only for the archive account user and is not set through the API).

user N* N user_permissions

* Present when result = 1 and the customer configuration includes these settings.

XML container for the user associated with this feature

username N* N user * Present when result = 1 and the customer configuration includes these settings.

View-only archive account username in the format: archive.<customer-number>.<brand-domain>

password N* N user * Present when result = 1 and the customer configuration includes these settings.

Service-Node generated password for the archive user account



Multiple Values?



OL-16960-01


feature N* N user * Present when result = 1 and the customer configuration includes these settings.

For the current release, “archive” is always returned. The archive feature is used by the Service Node to access the UC500 device.

getCustomer — Installation Handshake Information

showhandshakeinfo N* N customer * Present when result = 1

XML container tag for installation handshake information

serviceproviderid N* N showhandshakeinfo

* Present when result = 1

Numeric Service Provider ID required for the installation handshake. This parameter is returned by the API, but is not set by the API.

customerid N* N showhandshakeinfo


Customer ID number required for the installation handshake. This parameter is returned by the API, but is not set by the API.

password N* N showhandshakeinfo


Password required for the installation handshake

emailaddress N* N showhandshakeinfo

* Present when result = 1 and the customer configuration includes this settings.

Destination e- mail address for installation handshake information

getCustomer — Maintenance Settings

maintwindow Y N customer *Present when result=1 and the customer configuration includes these settings.

XML container for maintenance settings

timeslot Y N maintwindow *Present when result=1 and the customer configuration includes these settings.

Local start time for maintenance.

Returns “never” or a 2-character value from “00” (12 AM local time) to “23” (11 PM local time).

firmware_update Y N maintwindow *Present when result=1 and allow_updates is enabled for this customer.

Indicates whether or not firmware updates are applied at the maintenance window for this customer.

• none — do not upgrade firmware during the maintenance window.

• upgrade — upgrade firmware during the maintenance window.



Multiple Values?



OL-16960-01


Sample XML Output

<?xml version="1.0" encoding="UTF-8"?><response> <result>1</result> <errors/> <customer> <id>4199.var-9.com</id> <api_id/> <businessname>ABC Suppplies</businessname> <release_group>UC500, MY_BRAND_RELEASE_SN</release_group> <timezone>America/Chicago</timezone> <agent_id/> <service_address>123 Main St.</service_address> <service_city>Anytown, USA</service_city> <service_state>TX</service_state> <service_postal>75093</service_postal> <service_country>us</service_country> <service_firstname>Jane</service_firstname> <service_lastname>Richards</service_lastname> <service_email>[email protected]</service_email> <billing_address>123 Main St.</billing_address> <billing_city>Anytown, USA</billing_city> <billing_state>TX</billing_state> <billing_postal>75093</billing_postal> <billing_country>us</billing_country> <billing_firstname>Jane</billing_firstname> <billing_lastname>Richards</billing_lastname> <billing_email>[email protected]</billing_email> <suspended/> <ip>12.19.95.2</ip> <allow_updates>yes, enabled at the system level</allow_updates> <phonenumbers> <numbers> <instance> <number>12144735696</number> <carrier>carrier-01.rg1.mynode.com</carrier> </instance> </numbers> <carriers>

getCustomer — Additional Configuration Information

cue_timezoneios_timezoneios_telephony_timezonebrand_ipddns_secretsn_dns_serverserver_netserver_net_maskserver_net_revmasksn_ntp_server

N* N customer * Present when result = 1.




Multiple Values?



OL-16960-01


<carrier> <carrier>carrier-01.rg1.mynode.com</carrier> <username>12144735696</username> <password>p5e0a243bfb</password> <parent_number>12144735696</parent_number> <emergency_number>12144735696</emergency_number> <sip_proxy>IP_Address</sip_proxy> <sip_proxy_method>ipv4</sip_proxy_method> <sip_registrar>docs-brand.mynode.com</sip_registrar> <sip_registrar_method>dns</sip_registrar_method> <realm>docs-brand.mynode.com</realm> <cca_provider_name>Generic SIP Trunk Provider</cca_provider_name> <integrated_call_routing>1</integrated_call_routing> </carrier> </carriers> </phonenumbers> <uc500> <description>Doc Test System</description> <ezvpn_passwd>df7e4ff8a9</ezvpn_passwd> <max_channels>11</max_channels> <codec_pref>g711_first</codec_pref> <qos_priority>990</qos_priority> <qos_bandwidth>55</qos_bandwidth> <model>UC520-8U-4FXO-K9</model> <expansion_slot>VIC-4FXS/DID</expansion_slot> <fxs_mode>fxs</fxs_mode> <bri_switch_type>basic-5ess</bri_switch_type> <pri_switch_type>primary-4ess</pri_switch_type> <pri_type>t1</pri_type> <linecode>ami</linecode> <framing>sf</framing> <timeslots>1</timeslots> <upload_speed>1536000</upload_speed> <hostname>site-4199</hostname> <enable_passwd>123123</enable_passwd> <disablewireless>1</disablewireless> <phone_firmware_files> <firmware_file> <file_name>SCCP11.8-0-3S.loads</file_name> <model>7906</model> <load_file_name>SCCP11.8-0-3S</load_file_name> <binary>true</binary> </firmware_file>

Similar output omitted for brevity...

</phone_firmware_files> <vid>default</vid> <bri_ports/> <pri_ports/> <fxo_ports> <fxo_port> <slot>1</slot> <port>0</port> </fxo_port> <fxo_port> <slot>1</slot> <port>1</port> </fxo_port> <fxo_port> <slot>1</slot> <port>2</port> </fxo_port> <fxo_port> <slot>1</slot>


OL-16960-01


<port>3</port> </fxo_port> </fxo_ports> <fxs_ports> <fxs_port> <slot>0</slot> <port>0</port> </fxs_port> <fxs_port> <slot>0</slot> <port>1</port> </fxs_port> <fxs_port> <slot>0</slot> <port>2</port> </fxs_port> <fxs_port> <slot>0</slot> <port>3</port> </fxs_port> </fxs_ports> <fxsdid_ports> <fxsdid_port> <slot>2</slot> <port>0</port> <ext_num/> <ext_name/> </fxsdid_port> <fxsdid_port> <slot>2</slot> <port>1</port> <ext_num/> <ext_name/> </fxsdid_port> <fxsdid_port> <slot>2</slot> <port>2</port> <ext_num/> <ext_name/> </fxsdid_port> <fxsdid_port> <slot>2</slot> <port>3</port> <ext_num/> <ext_name/> </fxsdid_port> </fxsdid_ports> </uc500> <wan> <type>DHCP</type> </wan> <sbcs_lan> <data_lan>192.168.10</data_lan> <voice_lan>10.1.1</voice_lan>

</sbcs_lan> <uc500extensions> <vm_extension>999</vm_extension> <aa_extension>998</aa_extension> <voip_extensions> <voip_extension> <ext_number>201</ext_number> <fname>User</fname> <lname>One</lname> <mac/>


OL-16960-01


<model>CIPC</model> <username>jbrown</username> <password>s3CR3t</password> <dn_number>1</dn_number> <ephone_number>1</ephone_number> </voip_extension> <voip_extension> <ext_number>202</ext_number> <fname>User</fname> <lname>Two</lname> <mac/> <model>CIPC</model> <username>jsmith</username> <password>123abc4t</password> <dn_number>2</dn_number> <ephone_number>2</ephone_number> </voip_extension> <voip_extension> <ext_number>203</ext_number> <fname>User</fname> <lname>Three</lname> <mac/> <model>CIPC</model> <username>rsmith</username> <password>456def5u</password> <dn_number>3</dn_number> <ephone_number>3</ephone_number> </voip_extension> <voip_extension> <ext_number>204</ext_number> <fname>User</fname> <lname>Four</lname> <mac/> <model>CIPC</model> <username>asmith</username> <password>789ghi6v</password> <dn_number>4</dn_number> <ephone_number>4</ephone_number> </voip_extension> </voip_extensions> <fxs_ports> <fxs_port> <slot>0</slot> <port_number>0</port_number> <dial_peer_number>78</dial_peer_number> <extension>281</extension> <fname>FXS</fname> <lname>Brown</lname> <did/> </fxs_port> <fxs_port> <slot>0</slot> <port_number>1</port_number> <dial_peer_number>79</dial_peer_number> <extension>282</extension> <fname>FXS</fname> <lname>Smith</lname> <did/> </fxs_port> <fxs_port> <slot>0</slot> <port_number>2</port_number> <dial_peer_number>80</dial_peer_number> <extension>283</extension>


OL-16960-01


<fname>FXS</fname> <lname>Richards</lname> <did/> </fxs_port> <fxs_port> <slot>0</slot> <port_number>3</port_number> <dial_peer_number>81</dial_peer_number> <extension>284</extension> <fname>FXS</fname> <lname>Davis</lname> <did/> </fxs_port> </fxs_ports> <use_auto_assign>1</use_auto_assign> <max_ephones>4</max_ephones> </uc500extensions> <uc500lines> <translation_rules> <translation_rule> <tr_number>1</tr_number> <rule> <rule_number>1</rule_number> <rule_from>12144735696</rule_from> <rule_to>998</rule_to> <did_type>VoIP</did_type> <aa_or_vm_target>1</aa_or_vm_target> <tr_number>1</tr_number> </rule> </translation_rule> </translation_rules> <fxo_inbound> <fxo_port> <slot>1</slot> <port_number>0</port_number> <line_number>15554432368</line_number> <destination>281</destination> </fxo_port> <fxo_port> <slot>1</slot> <port_number>1</port_number> <line_number>15554432369</line_number> <destination>282</destination> </fxo_port> <fxo_port> <slot>1</slot> <port_number>2</port_number> <line_number>15554432370</line_number> <destination>283</destination> </fxo_port> <fxo_port> <slot>1</slot> <port_number>3</port_number> <line_number>15554432371</line_number> <destination>284</destination> </fxo_port>

<aa_pilot>15554432368</aa_pilot><vm_pilot>15554432370</vm_pilot>

</fxo_inbound> </uc500lines> <dialplan> <area_code_size>3</area_code_size> <phone_number_size>10</phone_number_size> <secondary_dialtone_access_code>9</secondary_dialtone_access_code>


OL-16960-01


</dialplan> <wireless/> <user_permissions> <user> <username>archive.customer_ID</username> <password>passwd</password> <feature>archive</feature> </user> </user_permissions>

<showhandshakeinfo> <serviceproviderid>12-digit_SP_ID</serviceproviderid> <customerid>99999</customerid> <password>passwd</password> <emailaddress/> </showhandshakeinfo> <maintwindow/> <cue_timezone>clock timezone CST</cue_timezone> <ios_timezone>clock timezone CST -6 clock summer-time CDT recurring 2 Sun Mar 02:00 1 Sun Nov 02:00 60</ios_timezone> <brand_ip>IP_Address</brand_ip> <ddns_secret>12-digit_DNS_Secret</ddns_secret> <brand_domain>mybrand.mynode.com</brand_domain> <sn_dns_server>IP_Address</sn_dns_server> <server_net>Server_Net</server_net> <server_net_mask>255.255.255.192</server_net_mask> <server_net_revmask>0.0.0.63</server_net_revmask> <sn_ntp_server>IP_Address</sn_ntp_server> </customer></response>


OL-16960-01


getCustomerAlertsThe getCustomerAlerts function returns validation error messages, if any, for a given customer. This function provides the same capabilities as the Critical Alerts section displayed at the top of the Add/Edit Customer page on the Brand Administration portal.

Use this function to check the validity of the customer's configuration with the customer's release set.

Two sets of alerts are displayed:

• Alerts generated as a result of missing information that is required for configuration

• Alerts generated as a result of invalid configuration (invalid format, conflicting values)

Input Parameters

Output Parameters

Table 2-7 getCustomerAlerts — Input Parameters

Parameter Name Required? Description and Constraints


When getCustomerAlerts is called with agent-level credentials, the specified customer must be assigned to that agent.

api_password Y Brand administrator, brand user, or agent password for the specified api_username.

api_action Y Name of the API function being called. This parameter is case-sensitive and must be “getCustomerAlerts”.

api_id N* * Required only if customer_id is not specified.

customer_id Y* * Not required if api_id is specified.


Table 2-8 getCustomerAlerts— Output Parameters


Multiple Values?

Parent XML Tag

Description

response Y N None Root XML tag.


“0” = Failure.




customer N* Y response Base XML tag for individual customer in the customer list.

*Present when result = 1.

id N* N customer Service Node-generated customer ID.



OL-16960-01


Sample XML Output

The following XML output example shows a call to getCustomerAlerts that displays several alerts.

<response> <result>1</result> <errors/> <customer> <id>99999.mybrand.mynode.com</id> <missing_required_alerts> <alert>UC500</alert> <alert>UC500 - WAN Interface</alert> <alert>UC500 - Data and Voice LAN</alert> <alert>UC500 - Extension Assignments</alert> <alert>UC500 - Dial Plan</alert> </missing_required_alerts> <invalid_alerts> <alert>Phone Numbers - Carrier Settings - Dallas Metro - Required field missing: Parent Number</alert> <alert>Phone Numbers - Carrier Settings - Dallas Metro - Required field missing: Emergency Number</alert> <alert>UC500 - Call Routing - Field value conflict: Phone Number, Need the call target for all numbers.</alert> </invalid_alerts> </customer></response>


missing_required_alerts

Y N customer * Present when result =1.

XML container tag for a list of alerts due to missing configuration information that is required for a given configuration item.

invalid_alerts Y N customer XML container tag for a list of alerts due to invalid configuration items for a given section.

alert N* Y missing_required_alerts

or

invalid_alerts

* Present when result =1 and there are alerts to display.

Returns a list of alerts, similar to that displayed in the Critical Alerts section at the top of the Edit Customer page on the Brand Administration portal. The alert identifies the configuration item that generated the error.

Table 2-8 getCustomerAlerts— Output Parameters (continued)


Multiple Values?

Parent XML Tag

Description


OL-16960-01


getCustomerListThe getCustomerList function returns a list of all customers for the brand, including suspended customers. Optionally, you can specify limit, offset, search_customer_id, search_phone, search_agent_name, search_location, search_name, search_task, or search_release_group parameters to display specific customers or reduce the number of results displayed.

The information returned is the same as the information displayed in the Web-based administration GUI when listing customers.

Tip The following notes apply to the optional limit, offset and search parameters

• If more than one search parameter is specified, the results must match all search parameters (the search parameters are AND’ed).

For example, if you specify a search_phone parameter of “1972” and a search_name parameter of “Smith,” only records that contain phone numbers with “1972” and “Smith” in the businessname field will match.

• If a limit and/or offset and one or more search parameters are specified, the search parameters are only applied to the records specified by the limit and/or offset.

For example, if you specify an offset of 20 with a limit of 20 and a search_number pattern of “1972,” only records from 21 through 40 that contain phone numbers with “1972” will match.

Input Parameters

Table 2-9 getCustomerList — Input Parameters



When getCustomerList is called with agent-level credentials, only customers associated with that agent are returned in the list.


api_action Y Name of the API function being called. This parameter is case-sensitive and must be “getCustomerList”.

limit N When present, limits the number of records returned to the number specified.

offset N When present, the records displayed begin with the record numbered offset + 1.

For example, if there are 100 records that match, and the offset is 50, the records displayed begin with the 51st match.

search_customer_id N A customer ID or part of a customer ID that is used to search the Service Node-generated Customer ID field (nnnn.brand_domain)

search_phone N A phone number or part of a phone number that is used to search all of the inventory and non-inventory numbers associated with a customer

search_name N A customer name or part of a customer name used to search the “businessname” field for the brand’s customers. This parameter is case-sensitive.


OL-16960-01


Output Parameters

search_location N A customer location or part of a customer location that is used to search for a location in the customer list

search_agent_name N An agent name or part of an agent name that is used to search for an agent’s name in the customer list

search_release_group N Release group name or part of a release group name used to search the release_group field for the brand’s customers

search_task N Last task status search specifier. Valid values are as follows:

• f — Last task failed.

• t — Last task succeeded.

• “null” or ““(empty string) — Task status is not set.

Table 2-10 getCustomerList — Output Parameters


Multiple Values?

Parent XML Tag

Description



“0” = Failure.




customerlist N* N response Base XML tag for list of customers.

*Present when result =1.

customer N* Y customerlist Base XML tag for individual customer in the customer list.

*Present when result = 1.

id N* N customer Service Node-generated customer ID.



name N* N customer * Present when result = 1.

location N* N customer *Present when result = 1.

number N* N customer * Present when result = 1.

This field is empty if the customer does not have any assigned numbers.

Otherwise, the number in this field is the first number found by the API, either inventory or non-inventory. It does not represent a “primary number” for the customer.

Table 2-9 getCustomerList — Input Parameters



OL-16960-01


agent_id N* N customer *Present when result =1. This field is empty if an Agent is not associated with this customer.

agent_name N* N customer *Present when result = 1. This field is empty if an Agent is not associated with this customer.

suspended N* N customer * Present when result = 1.

If the suspended tag is empty, indicates customer is active.

Otherwise, this field contains a timestamp indicating the time the suspension was issued on the Service Node.

release_group N* N customer * Present when result = 1.

Name of the release group to which this customer is assigned

task_success N* N customer * Present when result = 1.

Indicates status of last task attempted. Displays one of the following values:

• t — Last task seceded for this customer.

• f — Last tasks failed for this customer.

• empty — Task status not set.

Table 2-10 getCustomerList — Output Parameters (continued)


Multiple Values?

Parent XML Tag

Description


OL-16960-01


Sample XML Output

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

<result>1</result><errors/><customerlist>

<customer><id>9997.mybrand.mynode.com</id><api_id/><name>Test Customer 1</name><location>Richardson, TX</location><number>19725555555</number><agent_id/><agent_name/><suspended/><release_group>UC500, SBCS_Mybrand</release_group><task_success>f</task_status>

</customer><customer>

<id>9999.mybrand.mynode.com</id><api_id/><name>Test Customer 2</name><location>Plano, TX</location><number>12145555555</number><agent_id>Agent001.brand.com</agent_id><agent_name>Agent001</agent_name><suspended>08/04 18:52</suspended><release_group>UC500, SBCS_Mybrand</release_group><task_success>t</task_status>

</customer></customerlist>

</response>


OL-16960-01


getAvailableInventoryNumbersThe getAvailableInventoryNumbers function returns available E.164 phone numbers from the number inventory on the Service Node for the specified carrier. Inventory numbers only apply to brands and customers deployed with integrated call routing.

A search pattern consisting of a phone number or part of a phone number can be specified to filter the results.

The search always starts from the beginning of the phone number. For example, enter 1214 as the search string to display only numbers beginning with 1214. UNIX wildcard searches are not supported.

The maximum number of records that can be returned with getAvailableInventoryNumbers is 100. To display additional numbers, specify a new search_pattern.

Input Parameters

Output Parameters

Table 2-11 getAvailableInventoryNumbers — Input Parameters

Parameter Name Required? Constraints



api_action Y Case-sensitive

Must be “getAvailableInventoryNumbers”.

carrier Y Carrier routlet ID

Must be a valid carrier routlet ID in the same routegroup as the brand. This parameter is case-sensitive and must be specified exactly as it appears on the Call Routing configuration pages on the Node Administration portal.

For example: carrier-01.rg1.mynode.com

search_pattern N A phone number or part of a phone number that is used to filter the search results

Table 2-12 getAvailableInventoryNumbers — Output Parameters


Multiple Values?

Parent XML Tag

Description


result Y N response “1” = Success

“0” = Failure





OL-16960-01


Sample XML Output

<?xml version="1.0" encoding="UTF-8"?><response> <result>1</result> <errors/> <availableinventorynumbers> <number>19999999995</number> <number>19999999994</number> <number>19999999993</number> <number>19999999992</number> <number>19999999991</number> </availableinventorynumbers></response>

availableinventorynumbers N* Y response Base XML tag for available inventory number list

number N* N availableinventorynumbers


Table 2-12 getAvailableInventoryNumbers — Output Parameters


Multiple Values?

Parent XML Tag

Description


OL-16960-01


updateCustomerUse the updateCustomer function to modify configuration data for an existing customer of a brand:

Note The updateCustomer function handles all customer configuration data except phone number provisioning. Phone number provisioning is managed using updateCustomerNumbers function (see updateCustomerNumbers, page 2-7).

• Either the Service Node-generated customer_id or the api_id (or both) can be used when updating a customer:

– The customer_id is used if both are specified.

– If both are specified, the api_id will be updated for the associated customer.

– If only the customer _id is specified when calling updateCustomer and the existing api_id associated with the customer is not specified, the existing api_id for customer will be removed.

• If needed, you can use the getCustomer function before calling updateCustomer to retrieve all of the required customer information from the database.

• When calling updateCustomer, you must specify all of the customer's information, replacing the current values with the new values.

Parameters that are not specified on update are removed from the configuration.

• When calling updateCustomer, make sure that:

– The number and type of slots and ports correspond to the customer’s hardware configuration and number of user licenses, as specified by the UC500 model and expansion slot type

– Phone numbers are appropriately mapped to extensions and exist in the numbers provisioned for the customer

– Phone numbers specified for inbound call routing match those assigned to the customer.

• Prior to the installation handshake, you can simply specify DHCP for the WAN connection.

Once the handshake completes, the customer’s account on the Service Node is updated with the actual settings entered during the installation handshake.

• You can set the maintenance window using updateCustomer.

• When the updateCustomer function is called, the customer account is immediately updated on the Service Node.

For Release 3.0, once the customer site is installed and the initial configuration is downloaded to the Cisco SBCS CPE, only the customer’s firmware can be upgraded through the maintenance window if software updates are allowed for the customer and the appropriate maintenance settings are configured.

• To initiate maintenance using the API, call updateCustomer as described below:

Caution The maintenance _submit parameter must only be specified after the customer has completed the initial installation handshake.

– Specify all of the customer’s information, as you normally would.

– Specify the maintenance_submit parameter and set its value to 1.

– Specify the maintenance_action parameter


OL-16960-01


See the “updateCustomer — Initiate Device Maintenance” section on page 2-54 for parameter descriptions.

Caution The customer’s IP address should only be updated in the event that the customer has defined a static IP address on the UC500 and that IP address is not being correctly updated.

• Specifying an incorrect IP address with updateCustomer can result in a service outage for the customer.

Input ParameterslTable 2-13 updateCustomer — Input Parameters


updateCustomer — API Access and Correlation


When updateCustomer is called with agent-level credentials, the customer_id or api_id specified must correspond to a customer that is associated with the agent.


api_action Y Case-sensitive.

Must be “updateCustomer”.

api_id N* * Required only if customer_id is not specified.

customer_id Y* * Not required if api_id is specified. If both customer_id and api_id are specified, customer_id is used.

In this case, the customer record would be updated with the new api_id value.

updateCustomer — General Information

businessname Y None


OL-16960-01


release_group Y Release group for this customer

The release group controls the equipment configuration selections that are available through the API and customer provisioning GUI and the configuration files and software that are downloaded to customer premises equipment during installation.

This parameter is case-sensitive and must be the name of a valid release group associated with the brand. Release groups are specified using the following format:

<product-set>, <release-group-ID>

For example: UC500, MYRELEASE_SN

Note When you update the customer’s release group, existing configuration may need to be updated or additional configuration settings may be required, depending on the content of the release. The Service Node will push the new configuration and files to the UC500 at the next maintenance window.

timezone Y Case sensitive. Must be a valid time zone. See the “Supported Timezones” section on page 2-74.

ip Y This parameter should contain the current DNS IP address for the customer obtained from getCustomer unless the customer’s IP address is being explicitly updated.

The customer’s IP address parameter should only be updated in the event that the customer has defined a static IP address on the UC500 and that IP address is not being correctly updated.

Caution Specifying an incorrect IP address with updateCustomer can result in service outage for the customer.

This parameter must contain a valid IP address for the customer.

agentname N Associates the specified agent with this customer

This value is case-sensitive and must be a valid agent name for this brand.

Table 2-13 updateCustomer — Input Parameters (continued)



OL-16960-01


allow_updates Y Specifies whether the customer is entitled to receive software updates (firmware upgrades)

• If Allow Software Updates is enabled at the brand level on the System > Settings page of the Brand Administration portal, this setting is ignored if it is specified through API. When getCustomer is called for customers of the brand, the output “yes, enabled at the System level” is displayed for this field.

• If Allow Software Updates is not enabled at the brand level, specify one of the following values:

– yes — Enable software updates for this customer. The customer’s CPE is assumed to be entitled to software upgrades through a SmartNET contract.

– no — Disable software updates for this customer.

updateCustomer — Service Address and Contact Information

service_address Y Customer service address (street)

service_city Y Customer service address (city)

service_state N Customer service address (state)

service_state is not required, as it is not needed for some international addresses.

service_postal Y Customer service address (postal code)

service_country Y Customer service address (country code)

Must be a valid ISO 3166-1 Alpha-2 country code. These are listed at www.iso.org.

service_firstname N* Customer service contact, first name

* If there is an existing value and this parameter is not specified in the updateCustomer call, the existing value is removed.

service_lastname N* Customer service contact, last name


service_email N* Customer service contact, e-mail address


service_phone1 N Customer service contact, primary phone number

service_phone2 N Customer service contact, secondary phone number




OL-16960-01


updateCustomer — Security Information (optional customer-specified password for handshake)

password N Customer-specified installation handshake password to be used in place of the Service Node-generated installation handshake password.

If specified, must be a 6-digit number, for example, 123456.

password_verify *N Second entry of customer-specified installation handshake password for verification.

* Required if password parameter is specified. If specified, must match the 6-digit password parameter.

updateCustomer — Billing Address and Contact Information

billing_address Y Customer billing address (street)

billing_city Y Customer billing address (city)

billing_state N Customer billing address (state)

billing_state is not required, as it is not needed for some international addresses.

billing_postal Y Customer billing address (postal code)

billing_country Y Customer billing address (country code)

Must be a valid ISO 3166-1 Alpha-2 country code. These are listed at www.iso.org.

billing_firstname N* Customer billing contact, first name

* If there is an existing value and this parameter is not specified in the updateCustomer call, the existing value will be removed.

billing_lastname N* Customer billing contact, last name


billing_email N* Customer billing contact e-mail address


billing_phone1 N Customer billing phone number (primary)

billing_phone2 N Customer billing phone number (secondary)




OL-16960-01


updateCustomer —UC500 Configuration Settings

uc500_description N Optional text description for the UC500 device for this customer, for example “ABC Dallas UC500”. Up to 45 characters can be entered.

uc500_model Y Model (part number) that corresponds to the configuration for the UC500 platform to be installed. The following configurations are supported for the current release:

• UC520-8U-4FXO-K9

• UC520W-8U-4FXO-K9

• UC520-8U-2BRI-K9

• UC520W-8U-2BRI-K9

• UC520-16U-4FXO-K9

• UC520W-16U-4FXO-K9

• UC520-16U-2BRI-K9

• UC520W-16U-2BRI-K9

• UC520-24U-8FXO-K9

• UC520-24U-4BRI-K9

• UC520-32U-8FXO-K9

• UC520-32U-4BRI-K9

• UC520-48U-12FXO-K9

• UC520-48U-6BRI-K9

• UC520-48U-T/E/F-K9

• UC520-48U-T/E/F-K9

• Custom — Specify “Custom” if the UC500 part number is not listed above or if you do not know the part number.

Refer to the documentation for the Cisco Unified Communications UC500 Series-UC520 for hardware descriptions of each of the supported part numbers.




OL-16960-01


uc500_expansionslot N Specify the part number that corresponds to the voice interface card installed in the expansion slot for the UC500 platform. The expansion slot is Slot 0/2.

Valid values for supported configurations are as follows and must be specified exactly as shown: VIC-4FXS/DID, VIC2-2FXO, VIC2-4FXO, VIC2-2BRI-NT/TE, VIC2-2FXS, VWIC2-1MFT-T1/E1.

These values correspond to the following configurations:

• ‘‘ (empty string) — None

• VIC-4FXS/DID — 4-port FXS voice/fax interface card.

• VIC2-2FXO — 2-port FXO voice/fax interface card.

• VIC2-4FXO — 4-port FXO voice/fax interface card.

• VIC2-2BRI-NT/TE — 2-port BRI voice/fax interface card.

• VIC2-2FXS — 2-port FXS voice interface card.

• VWIC2-1MFT-T1/E1 — Cisco 2nd Generation One Port T1/E1 Multiflex Trunk Voice WAN interface card.

uc500_fxsmode N* FXS mode

* Only required if the specified expansion slot has FXS-DID trunks

Valid values for this parameter are as follows and must be specified exactly as shown:

• fxs

• did

uc500_bri_switch_type N* BRI switch type.

* Only required if the specified uc500_model or expansion slot has BRI trunks.


• basic-5ess

• basic-dms100

• basic-ni

• ntt

• basic-1tr6

• basic-net3

• basic-ts013

• vn3

• basic-q1sig




OL-16960-01


uc500_pri_switch_type N* PRI switch type.

* Only required if the specified uc500_model or expansion slot has PRI trunks.


• primary-4ess

• primary-5ess

• primary-dms100

• primary-net5

• primary-ni

• primary-ni2c

• primary-ntt

• primary-qsig

• primary-ts014

uc500_pritype N* PRI line type



• t1

• e1

uc500_linecode N* PRI line code



• ami

• b8zs

• hdb3

uc500_framing N* PRI framing



• sf — SuperFrame

• esf — ExtendedSuperFrame




OL-16960-01


uc500_timeslots N* Timeslots used


Valid values for this parameter range from 1 to 22 for 8- and 16-user UC500 Series models and 24 (full T1) for 24-, 32-, and 48-user models.

Note For 8- and 16-user UC500 models, do not set Timeslots Used for ISDN PRI lines to a value greater than 15. This is to ensure that sufficient transcoding resources are available.

Switch types for ISDN BRI and PRI lines vary by country and service provider. The information required for these fields must be supplied by the customer’s PSTN provider.

uc500_voice_port_type-0-0




Y Specifies the voice port type for each voice slot (slot 0/0 through slot 0/3).

• Slot 0/0 is used for FXS ports.

• Slot 0/1 is variable (FXS, FXS-DID, FXO, BRI).

• Slot 0/3 and Slot 0/4 are used for expansion slots (FXS, FXS-DID, FXO, BRI). Slots 0/3 and 0/4 are only available with the 24, 32, and 48-user models.

Valid values are as follows and must be specified exactly as shown:

• FXS

• FXO

• BRI

• PRI

• FXSDID

uc500_number_of_voice_ports_0-0




Y Specifies the number of voice ports for each voice slot (slot 0/0 through 0/3)

Valid values are 0, 1, 2, 3, and 4.

• Slot 0/0 is used for FXS ports.

• Slot 0/1 is variable (FXS, FXS-DID, FXO, BRI).

• Slot 0/3 and Slot 0/4 are used for expansion slots (FXS, FXS-DID, FXO, BRI). Slots 0/3 and 0/4 are only available with the 24, 32, and 48-user models.




OL-16960-01


uc500_codecpref Y Specifies the order of preference for audio codec selection

Valid values are as follows and must be entered exactly as shown:

• G711ULAW, G711ALAW, G729R8

• G729R8, G711ULAW, G711ALAW

• G729R8

When calculating the maximum recommended number of channels, a value of 90 Kbps per call is used for G711ALAW and G711MULAW calls; a value of 30 Kbps per call is used for G729R8 calls.

uc500_uploadspeed Y Broadband upload speed for QoS (Quality of Service). Specify the value that most closely matches the broadband upload speed of the WAN connection at the customer premises.

Must be one of the following values: ignore, 128, 256, 384, 448, 512, 768, 1024, 2048, 2176, 1536, 4480, 5000, 10000 or 154400.

When 154400 is chosen for this field, Generic Traffic Shaping (GTS) is effectively disabled. This should only be configured when the upload access device provides the classification, prioritization, and queuing of the voice and data traffic.

This parameter corresponds to the broadband upload speed in Kbps that is specified in the GUI when adding a customer.

uc500_maxchannels Y Specifies the maximum number of concurrent calls allowed for the site, for call admission control

Set the value for uc500_maxchannels based on the values specified for uc500_codecpref and uc500_uploadspeed.

For example, if the audio codec preference is set to G711ULAW, G711ALAW, G729R8 and the broadband upload speed is 1.5 Mbps, the maximum recommended value for uc500_maxchannels is 17 (based on an estimate of 90 Kbps for each G711ALAW and G755ULAW call).

If the broadband upload speed is 1.5_Mbps, and the audio codec preference is set to G729R8, the maximum recommended value for uc500_maxchannels is 24 (based on an estimate of 30 Kbps for each G729R8 call).




OL-16960-01


uc500_vid N UC500 identifier that contains the MAC address returned during installation

On an update, set this parameter to 1 if you need to explicitly reset this field to the default. For example:

• When replacing a customer's UC500, uc500_mac must be set to “default” so that the MAC address of the SUC500 can be updated in the database at the next maintenance window.

• This parameter must also be set to “default” if the customer’s UC500 is reset to factory defaults or the account information is cleared.

The MAC address in the database can only be inserted or updated through the handshake with the Service Node, and this only occurs when uc500_mac is set to “default”.

There is no way to manually enter a MAC address into the database.

uc500_hostname N Host Name for the UC500 device.

By default, uc500_hostname is set to site-<customer ID number> (for example, site-99999).

This field can be edited if a different host name is desired. The hostname can contain up to 16 characters. Valid characters are letters, numbers, dash (-), underscore (_) and period (.).

uc500_enablepasswd Y Enable password for the UC500 device

This field is required; there is no default value.

updateCustomer — WAN Configuration Settings

wan_0_type N WAN connection type. Must be set to one of the following values: DHCP, DHCPDNS (DHCP with DNS), or STATICIP.

The default is DHCP. When DHCP is specified as the WAN connection type, no other WAN configuration parameters are needed (the UC500 obtains its IP address automatically through DHCP).

wan_staticip_0_ip N* Static IP address to use for this STATICIP WAN connection

Must be a valid IP address with a CIDR (classful inter-domain routing) mask, for example, 10.1.1.1/24. The CIDR must be in the range from 10 to 30, inclusive.

* Required if wan_0_type is STATICIP.

wan_staticip_0_gateway N* IP address of the gateway to use for this STATICIP WAN connection

Must be a valid IP address and must reside on the same subnet as wan_staticip_0_ip.

* Required if wan_0_type is STATICIP.

wan_staticip_0_dns1 N* IP address of the primary DNS server for this STATICIP WAN connection

* At least one DNS server IP address must be specified if wan_0_type is STATICIP.




OL-16960-01


wan_staticip_0_dns2 N* IP address of the secondary DNS server for this STATICIP WAN connection

* At least one DNS server IP address must be specified if wan_0_type is STATICIP.

wan_dhcpdns_0_dns1 N* IP address of the primary DNS server for this DHCPDNS WAN connection

* At least one DNS server IP address must be specified if wan_0_type is DHCPDNS.

wan_dhcpdns_0_dns1 N* IP address of the secondary DNS server for this DHCPDNS WAN connection

* At least one DNS server IP address must be specified if wan_0_type is DHCPDNS.

updateCustomer — Data and Voice LAN Settings

Note Do not specify 10.1.10 for either the Data or Voice LAN IP address. For compatibility with CCA, the 10.1.10 subnet is reserved for Cisco Unity Express (CUE).

UC500~SBCS:data_lan Y First three octets of the IP address for the customer’s data LAN

For example: 192.168.1

UC500~SBCS:voice_lan Y First three octets of the IP address for the customer’s voice LAN

For example: 10.1.1

updateCustomer — Extension Assignments

uc500_extensions_number_of_voip_extensions

N Number of VoIP extensions to configure

uc500_extensions_number_of_fxs_extensions

N Number of FXS extensions to configure

uc500extensions_vm-ext-num Y Extension to use for voice mail

All extensions must have the same number of digits.

For CCA compatibility:

• One (and only one) number must be mapped to the Auto Attendant.

• Optionally, one (and only one number) can be mapped to Voice Mail.

uc500extensions_aa-ext-num N Extension to use for Auto Attendant


For CCA compatibility:

• One (and only one) number must be mapped to the Auto Attendant.

• Optionally, one (and only one number) can be mapped to Voice Mail.

uc500extensions_voip-ext-N-num N For VoIP extensions numbered 1 through N, this parameter specifies the extension number.





OL-16960-01


uc500extensions_voip-ext-N-fname N For VoIP extensions numbered 1 through N, this parameter specifies the first name of the user associated with this extension.

Up to 20 alphabetic characters can be entered for the first name.

uc500extensions_voip-ext-N-lname N For VoIP extensions numbered 1 through N, this parameter specifies the last name of the user associated with this extension.

Up to 20 alphabetic characters can be entered for the last name.

uc500extensions_voip-ext-N-mac N* For VoIP extensions numbered 1 through N, this parameter specifies the hexadecimal MAC address of the Cisco IP phone associated with this extension.

The MAC must be formatted as AAAA.AAAA.AAAA, for example, 0055.CD11.AAFF.

* The MAC address is required only if you do not want to auto-assign phone numbers to CPE. If the MAC address is specified, then the uc500extensions_voip-ext-N-model parameter must also be specified.

uc500extensions_voip-ext-N-model N* For VoIP extensions numbered 1 through N, this parameter specifies the Cisco IP Phone model for the phone associated with this extension.

Valid values are CIPC (Cisco IP Communicator), 7906, 7960, and 7940.

* The field is required only if the MAC address is also specified and you do not want to auto-assign phone numbers to CPE.

uc500extensions_voip-ext-N-user N For VoIP extensions numbered 1 through N, this parameter specifies the username to associate with this extension.

The username and password specified here is the user’s login and password for configuration of voice mail and speed dials in CME and CUE user pages and for remote access through EZVPN.

Only alphabetic characters (a-z and A-Z) are allowed in the username.

uc500extensions_voip-ext-N-pass N For VoIP extensions numbered 1 through N, this parameter specifies the password to associate with this extension.

The username and password specified here is the user’s login and password for configuration of voice mail and speed dials on CME and CUE user pages and for remote access through EZVPN.

uc500extensions_fxs-ext-N-num N For FXS extensions numbered 1 through N, this parameter specifies the extension number.


uc500extensions_fxs-ext-N-fname N For FXS extensions numbered 1 through N, this parameter specifies the first name of the user associated with this extension. Up to 20 alphabetic characters can be entered for the first name.

uc500extensions_fxs-ext-N-lname N For FXS extensions numbered 1 through N, this parameter specifies the last name of the user associated with this extension. Up to 20 alphabetic characters can be entered for the last name.

updateCustomer —Inbound Call Routing (Maps Inbound Lines to Extensions)

uc500lines_lineN Y For each inbound IP trunk, numbered 1 through N, specify an IP trunk phone number using E.164 number formatting.




OL-16960-01


uc500lines_lineN-inbound N* For each inbound IP trunk, numbered 1 through N, specify the destination extension.

All extensions must be have the same number of digits.

The specified extension must be one of the extensions specified in the extensions assignments section of the call to updateCustomer. See the “updateCustomer — Extension Assignments” section on page 2-51.

uc500lines_fxoN N For each inbound FXO trunk numbered 1 through N, specify the local trunk number using E.164 number formatting.

Note The given number is used only for the port description.

uc500lines_fxoN-inbound N For each inbound FXO trunk numbered 1 through N, specify the destination extension.

All extensions must be have the same number of digits.

The specified extension must be one of the extensions specified in the extensions assignments section of the call to updateCustomer. See the “updateCustomer — Extension Assignments” section on page 2-51.

updateCustomer—Dialplan Settings

uc500~DIALPLAN:phone_number_size

N Specifies the number of digits to use for local dialing

For North American Dial Plan (NADP) customers, valid values are 7 or 10.

uc500~DIALPLAN:area_code N* 3-digit area code for US customers using the North American Dial Plan

* Required if phone_number_size is set to 7.

Note If 7-digit dialing is selected for the customer and you do not specify a 3-digit area code, the customer will not be able to make calls.

uc500~DIALPLAN:secondary_dialtone_access_code

N For IP trunks, access code for external dialing

Valid values are 0 through 9.

uc500~DIALPLAN:<parameters> N Additional, custom, country-specific dial plan parameters, if defined.

updateCustomer — User Permissions

N/A N/A For the current release, the user permissions configuration page is used only for the archive user account permissions.

The user permissions configuration output is, however, viewable through the getCustomer function.

The archive account password can be reset through the Brand Administration portal GUI, but not through the API.




OL-16960-01


updateCustomer — Set Maintenance Window

MAINTWINDOW:timeslot Y Local start time (hour) for daily device maintenance window.

• Specify a value of “never” to disable daily maintenance.

• Specify a 2-character value from 00 through 23, where 00 is 12:00 midnight, local time and 23 is 11:00 PM. For example, when MAINTWINDOW:timeslot = “03”, daily maintenance begins at 3:00 AM, local time.

MAINTWINDOW:firmware_update

Y Enable or disable firmware updates during the daily device maintenance window or when initiating routine maintenance.

Specify one of the following values:

• none — Disable firmware updates during daily maintenance

• upgrade — If firmware updates are allowed for this customer and updates are available, upgrade firmware during the daily maintenance window.

updateCustomer — Initiate Device Maintenance

maintenance_submit N Set the maintenance_submit parameter to “1‘” to initiate the specified maintenance action on the customer CPE.

Omit this parameter if you do not want to initiate maintenance when updating the customer.

Caution The maintenance _submit parameter must only be specified after the customer has completed the initial installation handshake.

maintenance_action N* Maintenance action. Specify one of the following values as the action:

• inventory — Refresh CPE site inventory on the Service Node. This action only updates the Service Node. Inventory reports cannot be retrieved through the API.

• routine — Perform maintenance tasks specified in the maintenance settings for the customer site.

• overwrite — Replace site configuration and/or firmware, if either has been modified on the Service Node. Local changes to site configuration are overwritten.

• install — Replace site configuration, firmware, and other files and re-install CUE. Local changes to configuration are overwritten, CUE voice mail boxes are deleted, and CUE is re-installed.

• cleanslate — Reformat site. Reformat flash on the UC500 and completely replace the configuration, firmware, and files on the UC500, including Cisco IOS and CUE. All local changes to site configuration are overwritten, CUE voice mail boxes are deleted, and CUE is reinstalled.

* Required if maintenance_action is set to 1.




OL-16960-01


Output Parameters

Sample XML Output



Multiple Values?

Parent XML Tag

Description



“0” = Failure





OL-16960-01


shutdownCustomerUse the shutdownCustomer function to delete a customer. When a customer is shut down, all phone numbers from inventory that are associated with the customer are released and placed back into the pool of available inventory numbers, and the customer is marked as “shut down.” Certain aspects of the customer's account will remain in the system database but are not accessible from either the API or GUI. This action cannot be undone.

Either the Service Node-generated customer_id or the api_id (or both) can be used when calling shutdownCustomer. The customer_id is used if both are specified.

Input Parameters

Output Parameters

Table 2-14 shutdown Customer — Input Parameters

Parameter Name Required?Multiple Values? Constraints

api_username Y N Must be a valid brand administrator, brand user or agent ID.

When shutdownCustomer is called with agent-level credentials, the customer_id or api_id specified must correspond to a customer that is associated with that agent.


api_action Y N Case-sensitive

Must be “shutdownCustomer”


customer_id Y* N * Not required if api_id is specified. If both customer_id and api_id are specified, customer_id is used.

Table 2-15 shutdownCustomer — Output Parameters


Multiple Values?

Parent XML Tag

Description



“0” = Failure.





OL-16960-01


Sample XML Output



OL-16960-01


suspendCustomerUse the suspendCustomer function to temporarily suspend a customer (for example, in the case of non-payment). When a customer is suspended, the customer is marked as “suspended” and the timestamp for the suspension (that is, the time the suspension was processed on the Service Node) is recorded in the database.

If the Block Suspended setting on the brand proxy routlet is set to true, a suspended customer will not be able to place outgoing calls, except for emergency services calls. Internal dialing is not affected, and the customer can still receive incoming calls.

The customer's data remains in the system and remains associated with the customer. The customer can be reinstated using the unsuspendCustomer function.

Either the Service Node-generated customer_id or the api_id (or both) can be used when calling suspendCustomer. The customer_id is used if both are specified.

Input Parameters

Output Parameters

Table 2-16 suspendCustomer — Input Parameters

Parameter Name Required? Multiple Values?

Constraints


When suspendCustomer is called with agent-level credentials, the customer_id or api_id specified must correspond to a customer that is associated with that agent.



Must be set to “suspendCustomer”.


customer_id Y* N * Not required if api_id is specified.


Table 2-17 suspendCustomer — Output Parameters


Multiple Values?




“0” = Failure.





OL-16960-01


Sample XML Output



OL-16960-01


unsuspendCustomerUse the unsuspendCustomer function to reinstate a customer that has been suspended. When a customer is re-instated, the customer status is changed to active, the suspended field is cleared, and the customer can place calls.

Either the Service Node-generated customer_id or the api_id (or both) can be used when calling unsuspendCustomer. The customer_id is used if both are specified.

Input Parameters

Output Parameters

Table 2-18 unSuspendCustomer — Input Parameters

Parameter Name Required? Multiple Values?

Constraints


When unsuspendCustomer is called with agent-level credentials, the customer_id or api_id specified must correspond to a customer that is associated with that agent.



Must be “unsuspendCustomer”.


customer_id Y* N * Not required if api_id is specified. If both customer_id and api_id are specified, customer_id is used.

Table 2-19 unSuspendCustomer — Output Parameters


Multiple Values?




“0” = Failure.


error N* * Only present when result = 0.



OL-16960-01


Sample XML Output



OL-16960-01

Chapter 2 Provisioning API Function Reference Agent Management Functions

Agent Management FunctionsThis section of the function reference covers the following topics related to agent management:

• Calling API Functions at the Agent Level, page 2-62

• addAgent, page 2-63

• getAgent, page 2-65

• getAgentList, page 2-67

• updateAgent, page 2-69

• deleteAgent, page 2-72

Calling API Functions at the Agent LevelThe following table shows what each function returns when it is called with an agent-level API username and password.

Table 2-20 Calling Functions at the Agent Level

When this API function is called... With an agent as the API username and password...

addCustomer Creates a customer account for the agent specified by agent_id

updateCustomerNumbers Adds or updates phone numbers and/or carrier settings for a single customer managed by an agent, depending on the action specified

getCustomer Returns customer information for a single customer managed by an agent

getCustomerAlerts Returns customer alerts and errors for a single customer managed by an agent

getCustomerList Returns a list of customers that are managed by an agent

updateCustomer Modifies customer information for a single customer managed by an agent

suspendCustomer Suspends a single customer managed by an agent

shutdownCustomer Shuts down the account of a single customer managed by an agent

getAgent Returns the agent’s information, if the agent API username and password correspond to the agent_id for that agent

updateAgent Updates the agent’s information, if the agent API username and password corresponds to the agent_id for that agent

getAvailableInventoryNumbers Lists available phone numbers from inventory on the Service Node for the specified carrier

updateCustomerNumbers Provision phone numbers for the customer account


OL-16960-01


addAgentUse the addAgent function to add an agent to manage customers for a brand. The addAgent function must be called with a brand-level API username and password for authentication.

Agents can add, get, update, list, and delete only their own customers. Brand administrators and brand account users have access to all customers of all agents, so when an agent is deleted, their customer’s accounts can still be accessed at the brand level.

Note The agent icon, agenturl, agentphone, agentemail, and agentsnmp parameters are not currently used by SBCS CPE.

The following guidelines apply to adding a support icon graphic for an agent of a Linksys One brand:

• The support icon graphic must be no larger than 160 pixels x 48 pixels and must be of type JPEG.

• When setting up the HTTP POST, the Content-Type in the header must be set to a value that allows binary data, such as “multipart/form-data” or “form-data”. The exact Content-Type setting depends on the programming language or libraries used with the API.

Input Parameters

Table 2-21 addAgent — Input Parameters


api_username Y Must be a valid brand administrator or brand user ID.

api_password Y Brand administrator or brand account user for the specified api_username


Must be “addAgent”.

agent_id Y Agent ID

The agent ID must begin with a lowercase character and can contain only letters and numbers.

The agent ID cannot be modified once it is created.

name Y Agent name

Must not contain angle brackets <>

timezone Y Time zone for his agent. Must be a valid time zone as described in the “Supported Timezones” section on page 2-74.

password Y Agent password

password_verify Y Re-specify agent password for verification

agentemail N Agent e-mail address

Must be a valid email address, in the format [email protected].

This parameter is not currently used by SBCS CPE.

agentphone N This field is not validated by the API, but should contain a valid phone number. Separators can be used to format the number for readability (for example, 214-555-8888).



OL-16960-01


Output Parameters

Sample XML Output


agenturl N This field is not validated by the API, but should contain a valid URL.


agentsnmp N Must be a valid email address in the format [email protected].


agenticon N Must be of type JPEG and no larger than 160 pixels (width) x 48 pixels (height).


See the “addAgent and getAgent Example” section on page 10 for an example showing how to specify the agenticon for the addAgent function.

Table 2-22 addAgent — Output Parameters


Multiple Values?




“0” = Failure.




Table 2-21 addAgent — Input Parameters



OL-16960-01


getAgentUse the getAgent function to retrieve information for a specific agent of a brand.

Note The agent icon, agenturl, agentphone, agentemail, and agentsnmp parameters are not currently used by SBCS CPE.

• When getAgent is called with a brand-level API username and password, any agent’s information can be retrieved.

• When getAgent is called with an agent-level API username and password, only that agent’s own information can be retrieved, and the api_username must correspond to the agent ID.

If an agent icon has been specified for an agent of a Linksys One brand, the icon is returned as a base 64-encoded string.

Input Parameters

Output Parameters

Table 2-23 getAgent — Input Parameters



When getAgent is called with agent-level credentials, only that agent’s own information can be retrieved, and the api_username must correspond to the specified agent_id.



Must be “getAgent”.

agent_id Y Agent ID

The agent ID must begin with a lowercase character and contain only letters and numbers.

Table 2-24 getAgent —Output Parameters


Multiple Values?




“0” = Failure.




agent Y N response XML container tag for agent information


OL-16960-01


Sample XML Output

<?xml version="1.0" encoding="UTF-8"?><response> <result>1</result> <errors/> <agent> <id>jsmith00537.mybrand.com</id> <name>John Smith</name> <timezone>America/Chicago</timezone> <email>[email protected]</email> <phone>2145551212</phone> <url></url> <alarm_email></alarm_email> <icon></icon> </agent></response>

id Y N agent Agent ID

name Y N agent Agent name

timezone Y N agent Agent local timezone

email N N agent Agent e-mail address


phone N N agent Agent phone number


URL N N agent Agent URL


alarm_email N N agent Agent SNMP address for alarm e-mails


icon N N agent Agent icon graphic. The icon is returned as base 64-encoded string.


See “addAgent and getAgent Example” in Chapter 3, “Provisioning API Programming Examples.”

Table 2-24 getAgent —Output Parameters


Multiple Values?



OL-16960-01


getAgentListUse the getAgentList function to list agents for a brand.

• The getAgentList function must be called with a brand-level API username and password for authentication.

• The entire agent list is always returned, sorted by agent ID.

• There are no sort or search specifiers for this function.

Input Parameters

Output Parameters

Table 2-25 getAgentList —Output Parameters


api_username Y Must be a valid brand administrator or brand account user ID.

api_password Y Brand administrator or brand account user password for the specified api_username


Must be set to “getAgentList”.

Table 2-26 getAgentList — Output Parameters


Multiple Values?




“0” = Failure.




agentlist Y N response XML container tag for the agent list

agent Y* Y agentlist XML container tag for each agent’s information

id Y* Y agent Agent ID

*Present if result=1 and there are agents in the list.

name Y* Y agent Agent name

*Present if result=1 and there are agents in the list.


OL-16960-01


Sample XML Output

<?xml version="1.0" encoding="UTF-8"?><response> <result>1</result> <errors/> <agentlist> <agent> <id>jsmith00537.mybrand.com</id> <name>John Smith</name> </agent> <agent> <id>asmith00538.mybrand.com</id> <name>Ann Smith</name> </agent> <agent> <id>jbrown00539.mybrand.com</id> <name>Jane Brown</name> </agent> </agentlist></response>


OL-16960-01


updateAgentUse the updateAgent function to modify an agent’s settings.

Note The agent icon, agenturl, agentphone, agentemail, and agentsnmp parameters for the updateAgent function are not currently used by SBCS CPE.

• When updateAgent is called with an agent-level API username and password, only that agent’s settings are modified. The agent_id must correspond to that agent’s username and password.

• When updateAgent is called with a brand-level API username and password, any agent’s settings can be modified.

When updating an agent:

• If the password and password_verify fields are not specified, the existing password will be retained.

• If the agentemail, agenturl, agentphone, or agentsnmp are not specified, these fields are cleared.

• The agent_id cannot be modified.

• The following guidelines apply to the agent icon graphic for an agent of a Linksys One brand:

– If the agenticon field is not specified during an update, the existing icon graphic will be used, if it was previously set.

– Specifying an icon image with the agenticon field will replace the current graphic.

– The agent icon cannot be removed through the API, only replaced.

– The support icon graphic must be no larger than 160 pixels x 48 pixels and must be of type JPEG.

– When setting up the HTTP POST, the Content-Type in the header must be set to a value that allows binary data, such as “multipart/form-data” or “form-data”. The exact Content-Type setting depends on the programming language or libraries used with the API.

Input Parameters

Table 2-27 updateAgent — Input Parameters



When updateAgent is called with agent-level credentials, the agent_id specified must correspond to that agent.



Must be “updateAgent”.

agent_id Y Agent ID of the agent to be updated, in the format <AgentID>.<brand-domain>

For example: jsmith0579.docs-brand.mynode.com

The agent ID can only contain letters and numbers, and it cannot be modified once it is created.


OL-16960-01


name Y Agent name

Must not contain angle brackets (<, >).

timezone Y Agent local timezone

Must be a valid timezone in the format Area/Location (for example, America/Chicago.

See the “Supported Timezones” section on page 2-74.

password N* Agent password

Must not contain white space or angle brackets (<, >).

If an agent password is not specified, the existing password is retained.

password_verify N* Re-specify agent password for verification.

* Required if agent password is specified.

agentemail N Must be a valid email address, in the format [email protected]. If agentemail is not specified, any existing value is deleted.


agentphone N This field is not validated by the API, but should contain a valid phone number. Separators can be used to format the number for readability (for example, 214-555-8888).

If agentphone is not specified, any existing value is deleted.


agenturl N This field is not validated by the API, but should contain a valid URL.

If agenturl is not specified, any existing value is deleted.


agentsnmp N Must be a valid email address, in the format [email protected].

If agentsnmp is not specified, any existing value is deleted.


agenticon N Must be of type JPEG and no larger than 160 pixels (width) x 48 pixels (height).

See the “addAgent and getAgent Example” section on page 3-10 for an example of how to specify the agenticon for the addAgent function.

If a new agenticon is specified, it replaces the existing agent support icon.

If agenticon is not specified, the current agent icon graphic is used, if it exists. The agent support icon cannot be deleted using the API.


Table 2-27 updateAgent — Input Parameters



OL-16960-01


Output Parameters

Sample XML Output


Table 2-28 updateAgent — Output Parameters

updateAgent — Output Parameters


Multiple Values?

Parent XML Tag

Description



“0” = Failure





OL-16960-01


deleteAgentUse the deleteAgent function to remove an agent from a brand. The deleteAgent function must be called with a brand-level API username and password for authentication.

When an agent is deleted, their customer’s accounts can still be accessed at the brand level.

Input Parameters

Output Parameters

Sample XML Output


Table 2-29 deleteAgent — Input Parameters


api_username Y Must be a valid brand administrator or brand account user ID.

api_password Y Brand administrator or brand account user password for the specified api_username


Must be “deleteAgent”.

agent_id Y Agent ID of the agent to be deleted

For example: agent04.docs-brand.mynode.com.

Table 2-30 deleteAgent — Output Parameters


Multiple Values?




“0” = Failure.





OL-16960-01

Chapter 2 Provisioning API Function Reference Connecting to the API

Connecting to the APIAn HTTP POST request over a Secure Sockets Layer (SSL) connection should be made to the brand's back office web application on the Service Node using the following URL as a template for the endpoint:

https://adm.<brand-domain>/brandapi.html

All API calls must be run under a brand and require a brand administrator, brand user, or agent username and password to run successfully.

Note SSL support is required for accessing URIs that use the HTTPS protocol.

Example:

https://adm.mybrand.com/brandapi.html

This endpoint should be used for all documented functions.

Error MessagesIn the event that an API call can not be completed, one or more error messages will be generated detailing the reason for the failure. Possible messages are as follows:

• Required field missing: [field name]

• Invalid format: [field name]

• Bad value: [field name]

• Already exists: [api_id]

• Invalid username and/or password

• Customer account not found

• An error occurred while trying to perform this action: [raw error text]

• Number is not available: [number]

• An error occurred while trying to perform this action: Consumer CPE not configured or handshake complete (existing Linksys One deployments only)

This message is returned by the getCustomerConfig function. Since this function is intended to be used to record customer site configuration for new Linksys One installations using a USB install key, it returns this error if the Linksys One Services Router has already completed the installation handshake.


OL-16960-01

Chapter 2 Provisioning API Function Reference Supported Timezones

Supported TimezonesThe Service Node uses the zoneinfo database (also known as the tz database) for time zone information. The tz database is used by many Unix operating systems, including FreeBSD, which is the operating system on the Service Node servers.

The time zones in the database are given uniform names, such as “America/Chicago.” These names are all of the form Area/Location, where Area is the name of a continent or ocean and Location is the name of a specific location within that region, usually cities or small islands. The set of areas currently includes: Africa, America (encompasses both North and South), Antarctica, Arctic, Asia, Atlantic, Australia, Europe, Indian, and Pacific. Additionally a special area of Etc is used for some administrative zones, particularly for “Etc./UTC.”

Examples of valid timezone values for the Service Node API include the following:

• America/Chicago

• Australia/Sydney

• Europe/Oslo

• Pacific/Aukland

Specifying Custom Provisioning Parameters using the APIThe XML files for a given release include a set of XML files (referred to as “feature widgets”) that define the input parameters and GUI presentation of the customer provisioning pages. Also included in the release is a FEATURESUITE file that lists all XML feature widgets that are valid for the release.

Since feature widgets can be customized for a particular brand, the API programmer will need to examine the HTML source for any customized configuration widgets to determine the input parameter name and value to use with the API.

See the Service Node Administration Guide for additional information on dial plan management on the Service Node and dial plan parameter specifications.


OL-16960-01

OL-16960-01

C H A P T E R 3
Provisioning API Programming Examples
This section provides simple guidelines and programming examples that show how to use the Service Node provisioning API. The following topics are covered:

• Overview, page 3-1

• addCustomer Example, page 3-2

• updateCustomerNumbers Example, page 3-4

• updateCustomer Example, page 3-6

• addAgent and getAgent Example, page 3-10

OverviewThe programming examples in this section are very simple Perl programs that show how to retrieve customer information, add a customer, create an agent, and retrieve agent information. The examples call the API functions with the required fields, perform basic error checking, parse the XML output for success or failure, print the results in XML, and print any error messages.

Although the sample programs are written in Perl, you can use the API with almost any programming language (such as C, C#, C++, or Java). Most programming languages provide libraries to arbitrarily attach name-value pairs to any HTTP POST request.

The sample Perl code for these examples is intended solely to illustrate API usage and will not run “as is.” For example, you would need to:

• Replace the endpoint URL for connecting with the API (https://adm.mybrand.com/brandapi.html in the example) with a valid brand domain and password.

• Replace the api_username and api_password with valid values for an existing brand.

• Replace other values as needed, such as:

– Service Node-generated customer_id

– Service Node carrier ID for phone numbers

– References to the brand domain

– Actual phone numbers for calling updateCustomerNumbers

– CPE configuration options


Chapter 3 Provisioning API Programming Examples addCustomer Example

Note The sample has been successfully tested on with ActivePerl 5.8.8 on Windows with OpenSSL, SSLeay, XML::Simple, and LWP installed.

As noted in the comments for the examples:

• The examples use LWP (Library for WWW in Perl) modules for out-of-band HTTP request/responses. LWP is a group of Perl modules for accessing data on the Web.

• The examples assume that prior to the API invocation, all necessary customer data for the function has been assembled through a Web application, database or other mechanism.

• The sample code simply checks for successful execution and displays error messages; your application can log the output and messages to an external database, log file or do something else entirely.

Code for calling each of the API functions will be very similar, except that the action and input parameters specified for the LWP post() function will be different.

addCustomer ExampleThe following example illustrates an API call for adding a customer. In Release 3.0, addCustomer creates the customer account, specifying only the customer service contact and billing information, release group, and whether or not software updates are allowed for the customer.

The call to addCustomer is followed by calls to updateCustomerNumbers and updateCustomer to add phone numbers and configure equipment to complete the provisioning process.

#!/usr/local/perl/bin/perl -w# This example uses Perl's LWP Module for out-of-band HTTP request/responsesuse LWP 5.64;

# This example uses Perl's XML::Simple module for parsing the API XML responseuse XML::Simple;

use strict;

my $lwp_ua = LWP::UserAgent->new;my $xml_parser = new XML::Simple(suppressempty => '');

# Prior to the actual call, all necessary customer data should be assembled# either via a web application, database or some other mechanism.

# The addCustomer API call with sample data.my $api = $lwp_ua->post( "https://adm.mybrand.com/brandapi.html", [ 'api_username' => 'mybrand.com', 'api_password' => 'password', 'api_action' => 'addCustomer', 'api_id' => '555444123', 'businessname' => 'Test (API)', 'timezone' => 'America/Chicago', 'agent_id' => 'agent001.mybrand.com',

‘release_group’ => ‘UC500, MY_BRAND_RELEASE_SN’,‘allow_updates’ => ‘yes’,

'service_address' => '123 Somesuch Ln.', 'service_city' => 'Chicago',


OL-16960-01

Chapter 3 Provisioning API Programming Examples addCustomer Example

'service_state' => 'IL', 'service_postal' => '60606', 'service_country' => 'us', 'service_firstname' => 'Jane', 'service_lastname' => 'Smith', 'service_email' => '[email protected]',

'service_phone1' => '13128880000','service_phone2' => '13128880001','billing_address' => '123 Somesuch Ln.',

'billing_city' => 'Chicago', 'billing_state' => 'IL', 'billing_postal' => '60606', 'billing_country' => 'us', 'billing_firstname' => 'John', 'billing_lastname' => 'Smith', 'billing_email' => '[email protected]',

'billing_phone1' => '13129999999','billing_phone2' => '13129999998','password' => '111111',

'password_verify' => '111111',]

);# Show an error if we could not reach the APIdie print "Could not connect to the Service Node API." unless $api->is_success;# Show an error if the API returns anything other than XMLdie print "The Service Node API response was not XML." unless $api->content_type eq 'text/xml';

# Get the results of the API call and run it through our XML parsermy $response = $xml_parser->XMLin($api->content, forcearray => ['error']);

# If the result of the API call is successful then this example prints a message# saying as much. Others may wish to log this information to an external # database, log file or do something else entirely.if ($response->{result} eq '1'){ print "Customer successfully added via the Service Node API. \n" . "The Service Node customer id is: $response->{customer}->{id}";}# If the result of the API call is unsuccessful, this example prints out a list of# the errors that were returned from the API. Others may wish to trap out the errors# returned by the API and display their own set of error messages to users and/or# write these messages to an external database, log file or other destination.else{ print "The Service Node API call failed. Please correct the following" . " error(s): \n -"; print join(" \n -", @{$response->{errors}->{error}} );}


OL-16960-01

Chapter 3 Provisioning API Programming Examples updateCustomerNumbers Example

updateCustomerNumbers ExampleThe example in this section show how to use the updateCustomerNumbers function to add and delete phone numbers, save carrier settings, delete settings for a single carrier, and delete all carriers and phone numbers.

Only one number_action (save_number, save_carrier, delete_number, delete_carrier, or delete_all) can be specified per call.

For more information, see the “updateCustomerNumbers” section on page 2-7.

#!/usr/bin/perl -w

# This example uses Perl's LWP Module for out-of-band HTTP request/responsesuse LWP 5.64;

# This example uses Perl's XML::Simple module for parsing the API XML responseuse XML::Simple;

use Data::Dumper;

use strict;



# The API call with sample data.my $api = $lwp_ua->post( "https://adm.docs-brand.mynode.com/brandapi.html",

[###################################################### Required for all calls to updateCustomerNumbers####################################################

'api_username' => 'docs-brand.mynode.com','api_password' => 'S3cr3T','api_action' => 'updateCustomerNumbers','customer_id' => '99999.docs-brand.mynode.com',

'carrier' => 'ca-01.rg1.mynode.com',

###################################################### Uncomment to add a range of numbers####################################################

#'number_action' => 'save_number',#'ca-01.rg1.mynode.com:number' => '12145558888',#'ca-01.rg1.mynode.com:count' => '5',#'ca-01.rg1.mynode.com:carrier' => 'ca-01.rg1.mynode.com',#'ca-01.rg1.mynode.com:customer_id' => '99999.docs-brand.mynode.com'


OL-16960-01

Chapter 3 Provisioning API Programming Examples updateCustomerNumbers Example

###################################################### Uncomment to save carrier settings####################################################

#'number_action' => 'save_carrier',#'ca-01.rg1_mynode.com:username' => '123456',#'ca-01.rg1_mynode.com:password' => 'abcdef',#'ca-01.rg1.mynode.com:parent_number' => '12145558888',#'ca-0l.rg1.mynode.com:emergency_number' => '12145558888',#'ca-01.rg1.mynode.com:carrier' => 'ca-01.rg1.mynode.com',#'ca-01.rg1.mynode.com:customer_id' => '99999.docs-brand.mynode.com'

###################################################### Uncomment to delete a single number####################################################

#'number_action' => 'delete_number',#'ca-01.rg1.mynode.com:number' => '12145558890',#'ca-01.rg1.mynode.com:carrier' => 'ca-01.rg1.mynode.com',#'ca-01.rg1.mynode.com:customer_id' => '99999.docs-brand.mynode.com'

###################################################### Uncomment to delete settings for a single carrier####################################################

#'number_action' => 'delete_carrier'#'ca-01.rg1.mynode.com:carrier' => 'ca-01.rg1.mynode.com',

###################################################### Uncomment to delete all carriers and numbers####################################################

#'number_action' => 'delete_all'

],);

# This example will render the results in the form of html#print "Content-type:text/html\n\n";#print "Content-type:text/xml\n\n";

# Show an error if we could not reach the APIdie print "Could not connect to the Service Node API."

unless $api->is_success;

print $api->content;exit;

# Show an error if the API returns anything other than XMLdie print "The Service Node API response was not XML."

unless $api->content_type eq 'text/xml';

# Get the results of the API call and run it through our XML parsermy $response = $xml_parser->XMLin($api->content, forcearray => ['error', 'number']);


OL-16960-01

Chapter 3 Provisioning API Programming Examples updateCustomer Example

# If the result of the API call is successful then this example prints a message# saying as much. Others may wish to log this information to an external# database, log file or do something else entirely.if ($response->{result} eq '1'){

# do something}# If the result of the API call is unsuccessful then this example prints out a# list of the errors that were returned from the API. Others may wish to trap# out the errors returned by the API and display their own set of error messages# to their users and/or write these messages to an external database, log file# or some other mechanism.else{

print "The Service Node API call failed. Please correct the following" . " error(s): \n -";print join(" \n -", @{$response->{errors}->{error}} );

}

updateCustomer ExampleOnce the customer as been added and phone numbers have been provisioned, the updateCustomer function can be called to configure the customer’s CPE and complete the provisioning process. The following simple example illustrates a call to the updateCustomer function followed by a call to getCustomer to display the new configuration.

#!/usr/bin/perl -w

# This example uses Perl's LWP Module for out-of-band HTTP request/responsesuse LWP 5.64;use Data::Dumper;

# This example uses Perl's XML::Simple module for parsing the API XML responseuse XML::Simple;use strict;

use CGI qw(:standard);


my $brand = 'docs-brand.mynode.com';my $passw = 'S3cr3T';

my $cust_id = '99999.docs-brand.mynode.com';

if ($cust_id ne ''){


# The API call with sample data.my $api = $lwp_ua->post( "https://adm.$brand/brandapi.html",

['api_username' => $brand,'api_password' => $passw,


OL-16960-01


'api_action' => 'updateCustomer','customer_id' => $cust_id,#'api_id' => '555444321','businessname' => 'Test Customer 01','release_group' => 'UC500, GENERAL_SN','timezone' => 'America/Chicago','agent_id' => 'agent04.docs-brand.mynode.com','service_address' => '123 Main Street.','service_city' => 'Dallas','service_state' => 'TX','service_postal' => '75201','service_country' => 'us','service_firstname' => 'Thomas','service_lastname' => 'Smith','service_email' => '[email protected]',‘service_phone1’ => ‘13128880000’,‘service_phone2’ => ‘13128880001’,'billing_address' => '123 Main Street.','billing_city' => 'Dallas','billing_state' => 'TX','billing_postal' => '75201','billing_country' => 'us','billing_firstname' => 'Thomas','billing_lastname' => 'Smith','billing_email' => '[email protected]',‘billing_phone1’ => ‘13129999999’,‘billing_phone2’ => ‘13129999999’,'password' => '123123','password_verify' => '123123','ip' => '0.0.0.0',

################################################## The following are required for an acct################################################

### UC500 Equipment Settings'uc500_description' => 'Test Customer 01 Dallas UC500','uc500_model' => 'UC520W-8U-4FXO-K9','uc500_expansionslot' => '',

'uc500_voice-port-type-0-0' => 'FXS','uc500_number-of-voice-ports-0-0' => '4','uc500_voice-port-type-0-1' => 'FXO','uc500_number-of-voice-ports-0-1' => '4',

'uc500_codecpref'=> 'G729R8','uc500_uploadspeed'=> '1.5 Mbps','uc500_maxchannels'=> '24','uc500_vid '=> 'default','uc500_hostname'=> "site-4802",'uc500_enablepasswd'=> '123123',

### WAN Configuration'wan_0_type' => 'DHCP',

### Data and Voice LAN'UC500~SBCS_LAN:data_lan' => '192.168.10',


OL-16960-01


'UC500~SBCS_LAN:voice_lan' => '10.1.1',

### Extension Assignments

'uc500extensions_number-of-voip-ext' => '4','uc500extensions_number-of-fxs-ext' => '4','uc500extensions_vm-ext-num' => '299','uc500extensions_aa-ext-num' => '298',

'uc500extensions_voip-ext-1-num' => '201','uc500extensions_voip-ext-1-fname' => 'User','uc500extensions_voip-ext-1-lname' => 'One','uc500extensions_voip-ext-1-mac' => '','uc500extensions_voip-ext-1-model' => '7960','uc500extensions_voip-ext-1-user' => 'jjones','uc500extensions_voip-ext-1-pass' => '123123',

'uc500extensions_voip-ext-2-num' => '202','uc500extensions_voip-ext-2-fname' => 'User','uc500extensions_voip-ext-2-lname' => 'Two','uc500extensions_voip-ext-2-mac' => '','uc500extensions_voip-ext-2-model' => '7960','uc500extensions_voip-ext-2-user' => 'jsmith','uc500extensions_voip-ext-2-pass' => '123123',

'uc500extensions_voip-ext-3-num' => '203','uc500extensions_voip-ext-3-fname' => 'User','uc500extensions_voip-ext-3-lname' => 'Three','uc500extensions_voip-ext-3-mac' => '','uc500extensions_voip-ext-3-model' => '7960','uc500extensions_voip-ext-3-user' => 'jroberts','uc500extensions_voip-ext-3-pass' => '123123',

'uc500extensions_voip-ext-4-num' => '204','uc500extensions_voip-ext-4-fname' => 'User','uc500extensions_voip-ext-4-lname' => 'Four','uc500extensions_voip-ext-4-mac' => '','uc500extensions_voip-ext-4-model' => '7960','uc500extensions_voip-ext-4-user' => 'jhill','uc500extensions_voip-ext-4-pass' => '123123',

'uc500extensions_fxs-ext-1-num' => '281','uc500extensions_fxs-ext-1-fname' => 'FXS','uc500extensions_fxs-ext-1-lname' => 'NAME',




### Call Routing - Inbound Lines'uc500lines_line1'=> '15559990000','uc500lines_line1-inbound'=> '998',

'uc500lines_line2'=> '15559990001','uc500lines_line2-inbound'=> '999',


OL-16960-01


'uc500lines_line3'=> '15559990002','uc500lines_line3-inbound' => '201',

'uc500lines_line4' => '15559990003','uc500lines_line4-inbound' => '202',

'uc500lines_fxo1'=> '14449990000', 'uc500lines_fxo1-inbound'=> '281',




### Dial Plan Settings'UC500~DIALPLAN:phone_number_size' => '10','UC500~DIALPLAN:secondary_dialtone_access_code' => '9',

### Maintenance Window settings'MAINTWINDOW:timeslot' => '03','MAINTWINDOW:firmware_update' => 'none',

]);

# This example will render the results in the form of html#print "Content-type:text/html\n\n";#print "Content-type:text/xml\n\n";

print $api->content;

#print Dumper($api->content);

# Show an error if we could not reach the APIdie print "Could not connect to the Linksys One API during Customer Add."

unless $api->is_success;

# Show an error if the API returns anything other than XMLdie print "The Linksys One API response was not XML during Customer Add."

unless $api->content_type eq 'text/xml';


# If the result of the API call is successful then this example prints a message# saying as much. Others may wish to log this information to an external# database, log file or do something else entirely.if ($response->{result} eq '1'){

my $api2 = $lwp_ua->post( "https://adm.$brand/brandapi.html",[

'api_username' => $brand,'api_password' => $passw,'api_action' => 'getCustomer','customer_id' => $cust_id

]);

# Show an error if we could not reach the API


OL-16960-01

Chapter 3 Provisioning API Programming Examples addAgent and getAgent Example

die print "Could not connect to the Linksys One API during Customer Get."unless $api2->is_success;

# Show an error if the API returns anything other than XMLdie print "The Linksys One API response was not XML during Customer Get."

unless $api2->content_type eq 'text/xml';

print $api2->content;}# If the result of the API call is unsuccessful then this example prints out a# list of the errors that were returned from the API. Others may wish to trap# out the errors returned by the API and display their own set of error messages# to their users and/or write these messages to an external database, log file# or some other mechanism.else{

print $api->content;}

}else{

print "Content-type:text/html\n\n";print "Missing id parameter";

}

addAgent and getAgent ExampleThis section provides an example that shows how to add an agent and retrieve that agent’s information through the provisioning API.

Note For the current release, the agent URL, e-mail, phone number, graphic icon for phone desktop branding, and support e-mail address (agentsnmp) can be specified the agent account but are not displayed on phones or CPE.

The following information is specific to using the agent management functions of the API:

• The agenticon image is passed in the HTML header as binary data. The method for passing the data is implementation dependent. In the following example, which uses Perl 5.64, LWP, and SSLeay libraries, the agenticon graphic is passed as shown below:

'agenticon' => ['./my_agent.jpg']

• The Content-Type for the HTML header must be set to a type that supports binary data, such as form-data or multipart/form-data, depending on the implementation. For example:

'Content-Type' => 'form-data'

• The agenticon graphic is returned by the getAgent function as a base 64-encoded string.


OL-16960-01


addAgent and getAgent ExampleThe example in this section:

• Calls the addAgent function with brand administrator credentials to add an agent (jsmith00540.mybrand.com)

• Displays the result of the addAgent API call and stores it

• Calls the getAgent function to display information for the newly added agent and displays the result

• Decodes the agenticon graphic returned by getAgent (Linksys One brands only) and writes it to a file named fetched_agenticon.jpg in the current directory

my $decoded = decode_base64($response2->{agent}->{icon});open MY_OUTPUT, "> ./fetched_agenticon.jpg";print MY_OUTPUT $decoded;close MY_OUTPUT;

#!/usr/bin/perl -w

# This example uses Perl's LWP Module for out-of-band HTTP request/responsesuse LWP 5.64;

# This example uses Perl's XML::Simple module for parsing the API XML responseuse XML::Simple;use URI::Escape;use MIME::Base64;

use strict;


my $brand = 'mybrand.com';my $passw = 'abcde';

my $lower=1000;my $upper=10000;my $random = int(rand( $upper-$lower+1 ) ) + $lower;


# The API call with sample data.my $api = $lwp_ua->post( "https://adm.$brand/brandapi.html", [ 'api_username’ => $brand, 'api_password' => $passw, 'api_action' => 'addAgent', 'agent_id’ => 'jsmith00540.mybrand.com', 'name' => 'John Smith',

'timezone' => 'America/Chicago', 'password' => 'S3cr3t', 'password_verify' => 'S3cr3t', 'agentemail' => '[email protected]', 'agentphone' => '214-555-1212', 'agenturl' => 'www.company.com/support', 'agentsnmp' => '[email protected]', 'agenticon' => ['./my_agent.jpg'] ],

'Content-Type' => 'form-data'


OL-16960-01


);

# This example will render the results in the form of htmlprint "Content-type:text/xml\n\n";

print $api->content;

# Show an error if we could not reach the APIdie print "Could not connect to the Service Node API during Customer Add." unless $api->is_success;

# Show an error if the API returns anything other than XMLdie print "The Service Node API response was not XML during Agent Add." unless $api->content_type eq 'text/xml';


# If the result of the API call is successful then this example prints a message# saying as much. Others may wish to log this information to an external# database, log file or do something else entirely.if ($response->{result} eq '1'){ my $api2 = $lwp_ua->post( "https://adm.$brand/brandapi.html", [ 'api_username' => 'mybrand.com', 'api_password' => 'abcde', 'api_action' => 'getAgent', 'agent_id' => 'jsmith00540.mybrand.com' ] );

# Show an error if we could not reach the API die print "Could not connect to the Service Node API during Customer Get." unless $api2->is_success;

# Show an error if the API returns anything other than XML die print "The Service Node API response was not XML during Customer Get." unless $api2->content_type eq 'text/xml';

print $api2->content;

my $response2 = $xml_parser->XMLin($api2->content, forcearray => ['error']);

my $decoded = decode_base64($response2->{agent}->{icon}); open MY_OUTPUT, "> ./fetched_agenticon.jpg"; print MY_OUTPUT $decoded; close MY_OUTPUT;}# If the result of the API call is unsuccessful then this example prints out a# list of the errors that were returned from the API. Others may wish to trap# out the errors returned by the API and display their own set of error messages# to their users and/or write these messages to an external database, log file# or some other mechanism.else{ print $api->content;}


OL-16960-01

OL-16960-01

C H A P T E R 4
Call Detail Records
This section describes the mechanism for retrieving call detail records (CDRs) from the Cisco Service Node, including the following topics:

• Using the API to Retrieve CDRs, page 4-2

• CDR Format Specification, page 4-5

• Sample CDRs, page 4-9

• Frequently Asked Questions about Service Node CDRs, page 4-12

The following diagram shows the CDR retrieval interface on the Service Node.

Figure 4-1 CDR Retrieval Interface on the Service Node

Note CDR information is generated for brands deployed with integrated call routing only. To generate this information, call logging must also be enabled for the associated carrier routlet. For more information about enabling and disabling call logging, see the Service Node Administration Guide.

CDR records can be retrieved from the Service Node at either the node or brand level. At the brand level, only the CDRs for a particular brand or its customers are retrieved; at the node level, all CDRs for all brands and customers can be retrieved.

2717

49

MediationDevice

Rating andBilling Device

SN

ServiceNode

BillPresentment

HTTPS Get

CDR Retrieval

4-1Service Node OSS/BSS Integration Guide

Chapter 4 Call Detail Records Using the API to Retrieve CDRs

Using the API to Retrieve CDRsThe API allows you to retrieve CDRs at the node or brand level through a secure HTTP GET. The data is returned in IPDR format (an XML format that corresponds to the IPDR specification) or a basic tab-separated format with or without extended information. You can use the API with almost any programming language (such as Perl, C, C#, C++, or Java). Secure SSL support is required for retrieving data from the Service Node.

A typical application for retrieving CDRs will open a secure HTTP connection, request the data by passing parameters using an HTTP GET request (for example, using wget, CURL or some other Web content retrieval tool), collect and parse the XML data (for example, to filter the data for a specific customer) and pass it to a back-end application, such as a 3rd-party billing or mediation device, for processing.

Tip Avoid pulling this type of information while the Service Node is under heavy system load.

Use the basic or extended basic CDR retrieval format instead of the default IPDR format if simplified tab-separated CDR output is sufficient and you want to increase the speed of retrieval and minimize load on the Service Node being queried.

Syntax for Retrieving CDRs To retrieve CDRs from the Service Node database, construct a URL using the syntax and parameters described in the following table. You can retrieve CDRs for all brands on a node, a single brand, or a specific customer of a brand.

CDR Retrieval URL Syntax: https://bo.<domain>/cdr.html?[age=N or &start_time=<UTC_time>&end_time=<UTC_time>][&consumer=<customerID>.<brand-domain>]&loginpass=<password>&loginuser=<userid>[&style=<CDR_Format>][&timefmt=time_tm]

Specifier Description

https://bo.<domain>/cdr.html? Required.

<domain> specifies whether CDRs are retrieved at the node or brand level:

Use the node domain (for example, mynode.com) to retrieve CDRs for the entire Service Node or a specific customer of a brand on the node.

Use the brand domain (for example, mybrand.com) to retrieve CDRs for all customers of a brand.

age=N Either age or a start_time/end_time range is required.

• N is specified as a non-negative integer:

• age=0 returns all records for the current month.

• age=1 returns all records for the previous month, and so on.

For example, if the current month is May, specify age=4 to retrieve all records from January of the same year.


OL-16960-01


start_time=<UTC_time>

end_time=<UTC_time>

Either age or a start_time/end_time range is required.

Specify a start_time and end_time instead of age to retrieve a range of CDRs.

start_time and end_time must be specified using Unix time format (seconds elapsed since January 1, 1970 UTC).

loginuser=<userid>

loginpass=<password>

Required authentication credentials.

Use the node-level administration user ID and password when retrieving CDRs for all brands on a node or CDRs for a specific customer of a brand on the node.

Use either the brand administrator user ID and password or a valid brand user account ID and password when retrieving CDRs for all customers of a brand.

&style=<CDR_format>

where

<CDR_format> can be ipdr, basic or basicx.

Optional CDR format specifier.

&style=ipdr displays CDRs in IPDR format. This is the default format if you do not specify a style. A time format specifier is not required when using IPDR format, because the specification exactly defines the required format. If a timefmt parameter is specified with the ipdr formatting style, it is ignored. See the “IPDR Format Example” section on page 4-9.

&style=basic displays basic CDR information in a tab-separated format. See the “Basic CDR Format Example” section on page 4-9.

&style=basicx displays basic plus Service Node-specific extended CDR information in a tab-separated format. See the “Extended Basic CDR Format” section on page 4-11

Use the basic or basicx CDR retrieval format if simplified tab-separated CDR output is sufficient and you want to increase the speed of retrieval and minimize load on the Service Node being queried.

&timefmt=time_tm Optional time format specifier for use with basic and basicx CDR format styles.

Use &timefmt=time_tm to output the time in decimal seconds since Jan 1, 1970 UTC to millisecond accuracy (for example, 1165165061.472).

If timefmt is omitted, standard Unix time_t time format is used, without the milliseconds (for example, 1165165061).

&consumer=<customerID>.<brand-domain>

Optional.

A node administrator can retrieve CDRs for a specific customer by adding a consumer parameter to a node-level query.

For example: &consumer=99999.mybrand.com

CDR Retrieval URL Syntax: (continued)https://bo.<domain>/cdr.html?[age=N or &start_time=<UTC_time>&end_time=<UTC_time>][&consumer=<customerID>.<brand-domain>]&loginpass=<password>&loginuser=<userid>[&style=<CDR_Format>][&timefmt=time_tm]

Specifier Description


OL-16960-01


Examples

Retrieving CDRs for a Node:

Construct a URL similar to the following to retrieve all of the current month’s CDRs for a node using the default IPDR format:

https://bo.mynode.com/cdr.html?age=0&loginpass=nodepass&loginuser=mynode.com

Retrieving CDRs for a Brand:

Construct a URL similar to the following to retrieve the current month’s CDRs for a brand using the basic CDR format:

https://bo.mynode.com/cdr.html?age=0&loginpass=brandpasswd&loginuser=mybrand.com&style=basic

The login and password can either be the brand administrator login and password or a brand user account login and password.

Retrieving CDRs for a Customer:

To construct a URL for retrieving CDRs for a specific customer on the Service Node, add a consumer parameter to a node-level query:

https://bo.mynode.com/cdr.html?age=0&loginpass=nodepasswd&loginuser=mynode.com&consumer=9999.mybrand.com.

Retrieving a Range of CDRs:

To construct a URL for retrieving a range CDR records for a node, specify a start_time and end_time using Unix time format (seconds elapsed since January 1, 1970 UTC):

https://bo.mynode.com/cdr.html?start_time=1138137824&end_time=1138224197&loginpass=abc1234&loginuser=mynode.com

CDR Retrieval Example Using the wget CommandThe following command line shows an example of how to retrieve CDRs using the Unix wget command.

wget --no-check-certificate -nv -T 0 -t 1 -O t1.xml ‘https://bo.mybrand.com/cdr.html?age=0&loginpass=1234&loginuser=mybrand.com’

In the above command-line example:

• --no-check-certificate disables the SSL certificate check. Brand and Node web servers typically have self-signed certificates which can't be validated against a well-known certificate authority. The --no-check-certificate option is only in newer versions of wget.

• -nv is the short form of --no-verbose, which runs wget in non-verbose mode to reduce status output messages.

• -T 0 is the short form of --timeout=<sec>; it disables timeout by setting seconds to zero.

• -t 1 is the short form of --tries=<integer>; it sets tries to 1 (no retry).

• -O t1.xml is the short form of --output=<filename>; it sends the output to a file named t1.xml in the current directory.


OL-16960-01

Chapter 4 Call Detail Records CDR Format Specification

• ‘https://bo.mybrand.com/cdr.html?age=0&loginuser=mybrand.com’ is the URL that for the HTTP/S GET request. The parameters used in the request retrieve the current month’s CDRs in the default IPDR format.

See the documentation for the wget command on your system for additional options.

CDR Format SpecificationBy default, Call Detail Records presented in IPDR format, according to the IPDR Service Specification, VoIP Version 3.5-A.0.1, which is available at http://www.ipdr.org/. The CDR retrieval mechanism on the Service Node has the following characteristics:

• Information required to generate call records is stored in the central database when call logging is enabled and the brand is deployed with integrated call routing.

• Records can be retrieved at either the node or brand level, based on the login credentials.

• CDRs can be presented in IPDR, basic format, or extended basic format and are transported over HTTPS:

– IPDR records are in XML format. See <Hot Link>”IPDR XML Schema,” on page 5. The IPDR format includes Service Node-specific fields. See the “Additional Service Node-Specific Output Fields Supported” section on page 4-5.

– The “basic” CDR format is a text-based format with records terminated by a newline and fields separated by tabs. See the “Basic CDR Format Example” section on page 4-9.

– The “extended basic” CDR format is the same as the basic CDR format, but also includes Service Node-specific fields. See the “Extended Basic CDR Format” section on page 4-11.

Additional Service Node-Specific Output Fields SupportedThe following Service Node-specific fields are present in the output:

• ax_SubscriberNumber—Customer’s local phone number.

• ax_AgentId—Service Node agent ID. This field is not present in output if an Agent is not assigned to this customer.

• ax_ApiId — Service Node API ID. This field is only present if the customer was added through the Service Node provisioning API and assigned an api_id for correlation with a Managed Services Provider’s back-end system.

IPDR XML SchemaRefer to the IPDR Service Specification, VoIP Version 3.5-A.0.1, available at http://www.ipdr.org, for a complete listing of the IPDR XML Schema.

Supported Fields from the IPDR Specification

The following table:

• Lists basic flow usage attributes from the IPDR XML schema

• Indicates which fields are required by the specification and which are optional or conditional


OL-16960-01


• Indicates which fields are currently supported on the Service Node

Currently, all required elements are supported, as well as the optional elements pin, serviceConsumerType, and callDuration.

Table 4-1 Supported Fields from the IPDR Specification

IPDR Attribute Name

Presence (R)equired/ (C)onditional/(O) Optional)

Supported (Yes/No)

Description/Service Node Usage (for supported attributes)

startTime R Y Time call was answered, in ISO 8601 format.

For example,

2006-09-01T01:30:59.143Z

Z = Zulu (Greenwich Mean Time, GMT).

endTime R Y Time call was ended/hung up, in ISO 8601 format.

For example:

2006-09-01T01:30:59.143Z

Z = Zulu (Greenwich Mean Time, GMT).

timeZoneOffset R Y Time offset, in minutes, of local time zone referenced to GMT. The local time zone is always that of the Service Node customer, regardless of the call direction (that is, inbound or outbound).

callCompletionCode R Y Valid values are as follows:

• CC — Call completed normally.

• CIP — Call in progress

originalDestinationId R Y Called-party number for direct calls.

For example: 12145551212

hostName R Y Name of call management server controlling call processing.

This is the brand domain (for example, mybrand.com).

subscriberId R Y Unique ID within the HSP network. This value is the Service Node-generated customer ID in the format NNNNN.<brand-domain.

For example, 11001.mybrand.com.

uniqueCallID R Y Unique Call ID to identify that different IPDRs generated by different elements are for the same call.

ipAddress C N

imsiIngress C N

esnIngress C N

callProgressState C N

disconnetReason C N

destinationID C N


OL-16960-01


thirdPartyID C N

ani O Y Automatic Number Identification (Calling party number identification).

For example: 12145551212

The "ani" is provided, if it is available, along with a Service Node-specific “ax_SubscriberNumber” field that contains the phone number of the customer. This allows the call to be related to a specific phone number for the customer.

oLIiiDigit O N

dnis O N

pin O Y Personal Identification Number. This is the Service Node-generated customer number (a positive integer greater than or equal to 1000).

serviceConsumerType O Y Valid values include:

EU (end user) — Outbound call.

NE (network element) — Inbound call originating from an ITSP.

NK (network partner) — Inbound call originating from another party on the Service Node.

startAccessTime O N

endAccessTime O N

callSetupDuration O N

callDuration O Y Value, in milliseconds, excluding all call set-up procedures.

Calculated from endTime and startTime.

totalDuration O N

tearDownDuration O N

averagePacketLatency O N

type O N

paymentType O N

feature O N

incomingCodec O N

outgoingCodec O N

silenceCompressionMode O N

modem O N


IPDR Attribute Name


Supported (Yes/No)



OL-16960-01


supplementaryService O N

extendedReasonCode O N

disconnectLocation O N

proprietaryErrorCode O N

unitsConsumed O N

inboundByteCount O N

outboundByteCount O N

inboundPacketCount O N

outboundPacketCount O N

inboundLostPacketCount O N

outboundLostPacketCount O N

inboundRxmtPacketCount O N

outboundRxmtPacketCount O N

subscribedQoSClasses O N

callClarityIndex O N

voiceQualityIndex O N

transmissionRatingRFactor O N

userPerceivedRFactor O N

faxPerfomanceMetric O N

faxPageTransmittedCount O N

faxPageReceivedCount O N

packetLossPercentage O N

outOfSequencePackets O N

correctSequencePackets O N

packetDelayVariation O N

ipAddressIngressDevice O N

ipAddressEgressDevice O N

portNumber O N

imsiEgress O N

esnEgress O N

homeLocationIdIngress O N

homeLocationIdEgress O N


IPDR Attribute Name


Supported (Yes/No)



OL-16960-01

Chapter 4 Call Detail Records Sample CDRs

Sample CDRsThe examples in this section provide a description and sample output for each of the supported CDR format styles: IPDR, basic and extended basic.

IPDR Format ExampleA sample CDR in IPDR format is shown below. This is the default CDR format.

<?xml version="1.0" encoding="UTF-8"?><IPDRDoc xmlns="http://www.ipdr.org/namespaces/ipdr" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" IPDRRecorderInfo="domain.com" xsi:schemaLocation="http://www.ipdr.org/public/VoIP3.5-A.0.xsd" version="3.5-A.0"><IPDR> <seqNum>1</seqNum> <IPDRCreationTime>2006-09-14T19:42:58.744Z</IPDRCreationTime> <pin>1013</pin> <startTime>2006-09-01T01:30:59.143Z</startTime> <endTime>2006-09-01T01:31:05.019Z</endTime> <timeZoneOffset>-240</timeZoneOffset> <callDuration>5876</callDuration> <callCompletionCode>CC</callCompletionCode> <originalDestinationId>12145551234</originalDestinationId> <hostName>domain.com</hostName> <uniqueCallId>f85b5b70f9c8c68d4f42e0d0f3dd6f08</uniqueCallId> <serviceConsumerType>NE</serviceConsumerType> <ani>18175551234</ani> <subscriberId>1013.domain.com</subscriberId> <ax_SubscriberNumber>12145551234</ax_SubscriberNumber> <ax_AgentId>demo.domain.com</ax_AgentId> <ax_ApiId>1383</ax_ApiId></IPDR></IPDRDoc>

Basic CDR Format ExampleThe “basic” CDR format is a text-based format with records terminated by a newline and fields separated by tabs. The first field in every record is a single character describing the type of data:

• Q — Query sets in this sequence. For CDRs there is exactly one query set, so the results will always have "Q \t 0 \t 1 \n" as the first record, and "Q \t 1 \t 1 \n" as the last record. The first number is “queries so far completed” and the second is “total queries,” such as “0 of 1 complete” and “1 of 1 completed”.

• N — Remaining fields in this row are the names of the columns in this query set.

• T — Remaining fields in this row are the types of the columns in this query set.

• D — Remaining fields in this row are data items (the actual CDR information).


OL-16960-01

Chapter 4 Call Detail Records Sample CDRs

The column data comes directly from the Service Node database using a high-performance query path without significant data translation, which results in a faster query. The columns in the output are described in the following table.

The following example shows a CDR in basic format.

Q 0 1N ac_ca ac_call_tag ac_b ac_c ac_n ac_remote_num ac_direction ac_call_start ac_call_end ac_error_code ac_error_textT text text text text text text text float8 float8 int4 textD [email protected] 475.5884-10.1.5175255C-2036 ib-3.com 1259.ib-3.com 19727283743 19722355930 in 1164931368 1164931421 D [email protected] 517A923C-25BE. 922.5905-10.1 ib-3.com 1259.ib-3.com 19727283743 19722355930 in 1164931724 1164931834 D 276-1062729191939 465.5920-10.1.678.9455-10.1 ib-3.com 1253.ib-3.com 19727283730 19727283743 sipf 1164931750 0 D 276-1062729191939 465.5920-10.1.678.9455-10.1.r ib-3.com 1259.ib-3.com 19727283743 19727283730 sipr 1164931750 0 D [email protected] 301.5963-10.1.517E3640-166D ib-3.com 1259.ib-3.com 19727283743 19722355930 in 1164931963 1164932068 D 279-1062729191960 530.5978-10.1.702.9485-10.1 ib-3.com 1253.ib-3.com 19727283730 19727283743 sipf 1164931989 0 D 279-1062729191960 530.5978-10.1.702.9485-10.1.r ib-3.com 1259.ib-3.com 19727283743 19727283730 sipr 1164931989 0 D 13-1062729196366 278.142-10.1.5189DD9C-1137 ib-3.com 1252.ib-3.com 19727283733 00 out 1164932723 1164932723 404 Not Found

Column Name Type Description

ac_ca text Unique Call ID (call ID reported by a SIP device with a timestamp prepended).

ac_call_tag text Call tag derived from the “from” and “to” tag of the SIP dialog. Tags are recorded in alphabetical order with a single period separator.

ac_b text Brand domain, for example, mybrand.com.

ac_c text Subscriber ID, which is the Service Node-generated customer ID (NNNN.<brand-domain>)

ac_n text Customer’s voice device number or calling number for sip/sip calls.

ac_remote_num text Called party number. Remote voice device number or called number for sip/sip calls, if known.

ac_direction text Call direction.

Valid values are in (inbound call to a customer), out (outbound call from a customer), sipf (SIP forward entry) and sipr (SIP reverse entry).

ac_call_start float8 Start time (time call was answered) in UTC format.

ac_call_end float8 End time (time call was hung up) in UTC format.

ac_error_code int4 SIP error code. Expected values are NULL for successful calls, zero (0) for failed calls with an unknown error, and 300 through 599 according to normal SIP rules for failed calls with known errors. This field is only updated when an error occurs.

ac_error_text text SIP error text. The error text message associated with the SIP error code, if available.


OL-16960-01

Chapter 4 Call Detail Records Purging Call Records (ap_purgecalls)

D 13-1062729196751 282.98-10.1.5B86AD24-CC8 ib-3.com 1252.ib-3.com 19727283733 12106510466 out 1165100290 1165100323 Q 1 1

Extended Basic CDR FormatThe extended basic format (shown in the following example) is identical to the basic CDR format, but has three additional Service Node-specific fields:

• ac_r — Consumer's agent_id (blank if none).

• ac_api_id — API ID for the customer (blank if none).

• ac_timezone — Customer's time zone name in "Continent/City" format (for example, America/Chicago).

Q 0 1N ac_ca ac_call_tag ac_b ac_c ac_n ac_remote_num ac_direction ac_call_start ac_call_end ac_error_code ac_error_text ac_r ac_api_id ac_timezoneT text text text text text text text float8 float8 int4 textD [email protected] 475.5884-10.1.5175255C-2036 ib-3.com 1259.ib-3.com 19727283743 19722355930 in 1164931368 1164931421 America/ChicagoD [email protected] 517A923C-25BE.922.5905-10.1 ib-3.com 1259.ib-3.com 19727283743 19722355930 in 1164931724 1164931834 America/ChicagoD 276-1062729191939 465.5920-10.1.678.9455-10.1 ib-3.com 1253.ib-3.com 19727283730 19727283743 sipf 1164931750 0 America/ChicagoD 276-1062729191939 465.5920-10.1.678.9455-10.1.r ib-3.com 1259.ib-3.com 19727283743 19727283730 sipr 1164931750 0 America/ChicagoD 13-1062729196751 282.98-10.1.5B86AD24-CC8 ib-3.com 1252.ib-3.com 19727283733 12106510466 out 1165100290 1165100323 America/ChicagoQ 1 1

Purging Call Records (ap_purgecalls)Use the ap_purgecalls utility, located in /home/cvs/dev/bin, to remove old call records from the database to recover disk space. The program reports the actual number of calls purged. This command should be run from the sn-db1 server.

The recommended maximum number of call records supported is 3 million records.

Note Call data is not archived. If call history must be retained, Service Node operators must either ensure that database backups are kept or that call detail records have been loaded to another system via CDR reporting.

For example, if your call volume on the Service Node is approximately 1 million calls per day, you could run the ap_purgecalls daily with the number of days set to 3 to purge all calls older than 3 days ago to ensure the number of call records stays below 3 million.

sn-db1: ap_purgecalls -days 3


OL-16960-01

Chapter 4 Call Detail Records Frequently Asked Questions about Service Node CDRs

ap_purgecalls Syntax and UsageThe following table describes syntax, usage and parameters for the ap_purgecalls command.

You can also specify the -help parameter with ap_purgecalls to display this information.

Frequently Asked Questions about Service Node CDRsThis section provides answers to frequently asked questions for Service Node CDRs.

Q. How often are CDRs generated?

A. Currently, CDRs are completely live, as they are dynamically generated from the database on the Service Node. A CDR query by age will pull all matching CDRs right up to the current time.

Note Under heavy load, CDR posting can lag call routing. Currently, a heavy load is considered to be approximately 20 calls/sec.

Q. What is the storage capacity for CDRs?

A. CDR storage capacity is approximately 3 million call records.

Table 4-2 ap_purgecalls Syntax and Usage

ap_purgecalls [-verbose] [-dryrun] [-dbname name] [-dbuser user] [-dbhost host] [-dbport port] -days D | -weeks W | -months M | -date 'yyyy-mm-dd [hh:mm[:ss]] [UTC]'

Parameter Description

-verbose Optional. Reports internal operations.

-dryrun Optional. Determine the number of affected calls without actually purging them.

-dbname name

-dbuser user

-dbhost host

-dbport port

Optional. These are internal options for specifying the database name, user, host and port. By default, these are defined in ap_sql.pl rules.

Always use the default for these options.

Time period is required; specify one of the following: days, weeks, months, or date.

Note Relative dates are calculated using the same method as Postgres. In particular, “months ago” is determined as the same numeric day of the month unless the prior month had no such day, in which case the last day of that month is used.

-days D Purge all records older than D days ago, measured from the current time.

-weeks W Purge all records older than W weeks ago, measured from the current time.

-months M Purge all records older than M months ago, measured from the current time.

-date 'yyyy-mm-dd [hh:mm[:ss]][UTC]'

Purge all records older than the specified date. This can be any valid Postgres date specification, but this is the recommended format.


OL-16960-01


Q. How are CDRs backed up? How is availability handled?

A. For increased availability, the master database, which includes all the information required to generate CDRs, is replicated in near real-time to a repository on the slave database server. A full database backup is performed every 24 hours on the master database server and copied to RAID-protected storage on the slave database server.

Q. On which servers are the CDRs generated and stored?

A. sn-db1 is the primary database server. sn-db1 is backed up and replicated onto sn-db2 (on the SN-100 and SN-XA) or sn-br1 (on the SN-10).

Q. When is a CDR match/merge required?

A. Any CIP (call in progress) is a candidate for some kind of merge. The callCompletionCode can have a value of “CC” (call completed) or “CIP” (call in progress). However, a CIP can indicate a Call in Progress or it could indicate a hung call. Currently the Service Node does not have any mechanism for detecting hung calls. A hung calls occur if one the two endpoints go offline without sending a BYE.

Q. How long are CDR XML flat files saved on the Service Node?

A. There are no CDR files. CDRs are generated dynamically from the database on the Service Node where the query is run.

Q. Are there timeouts and date ranges on certain pulls for CDR retrieval?

A. Currently there are no required ranges on input.

Q. What is the expected frequency for pulling CDRs?

A. Currently, the expectation is that there will be a daily pull for that day's activities and then a monthly pull of the full month's traffic for billing purposes. It is possible that there may be demand for more frequent pulls (for example, every 5 minutes) for online status displays, or even on-demand pulls (for example, a consumer connects to a vendor's website and the vendor's system pulls CDRs for that consumer), but this is not currently supported.

Q. How can I identify inbound and outbound calls?

A. When IPDR format is used, an outbound call has a serviceConsumerType of “EU” for end-user. An inbound call originating from an ITSP has “NE” for network-element, and one originating from another party on the Service Node has “NK” for network partner. The “ani” is provided, if it is available, along with a Service Node-specific “ax_SubscriberNumber” field that contains the phone number of the hosted customer. That allows the call to be related to a specific phone number for the customer.

When basic or extended basic fast-query CDR format is used, the ac_direction column contains the call direction (in=inbound, out=outbound, sipf=SIP forward entry and sipr=SIP reverse entry).

Q. Is there a way to get a flat file with delimiters? Typically, mediation devices pull using an FTP transport with an inherent trust relationship between the file folder and the mediation device.

A. This is not currently supported.


OL-16960-01



OL-16960-01

CiscOL-16960-01

A
P P E N D I X A Where to Go From Here
Cisco Service Node Resources and DocumentationTo view product resources and documentation for the Cisco Service Node on Cisco.com, go to:

http://www.cisco.com/go/servicenode

Document Description Audience

Design and Deployment Guides

Cisco Service Node Managed Services Provider Design Guide

Describes target market and business models, hardware and software architecture and components, architecture for managed services, IP addressing requirements, telephony architecture, security, administration hierarchy, scalability, and design considerations for the Cisco Service Node.

Cisco Service Node Managed Services Providers (MSPs)

Cisco Service Node Managed SBCS Deployment Guide

Describes the Service Node managed SBCS solution for the reseller, discusses site planning and requirements, and provides procedures for provisioning the customer, performing the initial installation, and post-installation administration for a Service Node managed Cisco SBCS.

Cisco Service Node Managed Solution Providers and Qualified Value-Added Resellers (VARs)

Installation and Upgrade Guides

SN-XA Installation Guide

Documents all aspects of planning, building, racking, cabling, installing and configuring a new Cisco Service Node Model SN-XA installation for all supported configurations. It also covers procedures for SN-XA expansion (for example, adding servers or optional VPN hardware or adding redundancy).

Managed Solution Provider technical staff responsible for planning and performing the installation of a Cisco Service Node.

A-1o Service Node OSS/BSS Integration Guide

Appendix A Where to Go From Here Cisco SBCS Resources

Cisco SBCS ResourcesCisco provides a wide range of resources to help you and your customer obtain the full benefits of the Cisco Smart Business Communications System.

Service Node Software Upgrade Guide

Documents procedures for upgrading node-level software on the Cisco Service Node.

Managed Solution Provider technical staff responsible for maintaining and upgrading the Cisco Service Node.

Service Node Release Notes

Covers new and updated features for the current release, known issues, limitations, and CPE firmware version compatibility for the Cisco Service Node.

Managed Solution Provider IT staff.

Maintenance and Administration

Service Node Administration Guide

Documents node, brand and agent administration interfaces and procedures for administering and troubleshooting all models of the Cisco Service Node.

Managed Solution Provider technical staff responsible for administering a Cisco Service Node

Service Node Recover and Restore Guide

Documents procedures for recovering and restoring hardware and software components for all models of the Cisco Service Node for Linksys One, including the Service Node database.

Managed Solution Provider technical staff responsible for maintaining the Cisco Service Node

OSS/BSS Integration

Service Node OSS/BSS Integration Guide

Documents the implementation strategy and application programming interface for integrating MSP operations and business support systems (OSS/BSS) with the Cisco Service Node. Provides detailed descriptions of all provisioning API functions and parameters, Call Detail Record (CDR) format, and CDR retrieval.

Managed Solution Provider technical staff responsible for integrating Service Node provisioning and CDR retrieval with operations and back-office support systems.

Document Description Audience

Products Location

Cisco Smart Business Communications System http://www.cisco.com/go/sbcs

Cisco Unified Communications UC500 Series http://www.cisco.com/go/uc500

Cisco Unified Communications Manager Express and Cisco Unity Express

http://www.cisco.com/go/ccmecue

Cisco Unified Communications CE500 Series Switches

http://www.cisco.com/go/ce500

Cisco Unified IP Phones www.cisco.com/en/US/products/hw/phones/ index.html

Cisco Configuration Assistant http://www.cisco.com/go/cca

A-2Cisco Service Node OSS/BSS Integration Guide

OL-16960-01


Cisco Monitor Director http://www.cisco.com/go/cmd

Support Location

Cisco SBCS Support Wiki http://supportwiki.cisco.com/sbcs/

Cisco Support website http://www.cisco.com/en/US/support/index.html

Cisco Smart Business Communications System Teleworker Setup document

http://www.cisco.com/en/US/products/ps7293/prod_installation_guides_list.html

Additional Resources Location

Cisco Partners http://www.cisco.com/web/partners/index.html

Cisco Marketplace http://www.cisco.com/go/marketplace/

Cisco Press http://www.ciscopress.com

Products Location


OL-16960-01



OL-16960-01

OL-16960-01

I N D E X

A

addAgent function 2-63

input parameters 2-63

output parameters 2-64

sample XML output 2-64

addCustomer function 2-3


output parameters 2-5, 2-12

ap_purgecalls utility 4-11

API vs. Web GUI provisioning 1-3

C

CDRs

back-up 4-12

format

basic extended example 4-11

basic format example 4-9

IPDR example 4-9

format specification 4-5

generation 4-12

IPDR XML schema 4-5

supported fields 4-5

purging old call records 4-11

retrieving 4-2

example URLs 4-4

example using wget 4-4

for a brand 4-4

for a customer 4-4

for a node 4-4

specifying a range 4-4

syntax 4-2

Service Node-specific extended fields 4-5

storage 4-12

connecting to the API 2-73

D

deleteAgent function 2-72



documentation, related A-1

E

error handling 1-3

error messages 2-73

example program 3-1

F

functions 2-1

addAgent 2-63

addCustomer 2-3

deleteAgent 2-72

getAgent 2-65

getAgentList 2-67

getAvailableInventoryNumbers 2-38

getCustomer 2-13

getCustomerAlerts 2-32

getCustomerList 2-34

shutdownCustomer 2-56

suspendCustomer 2-58

unsuspendCustomer 2-60

updateAgent 2-69

IN-1Service Node OSS/BSS Integration Guide

Index

updateCustomer 2-40

updateCustomerNumbers 2-7

G

getAgent function 2-65



getAgentList function 2-67



getAvailableInventoryNumbers function 2-38



getCustomerAlerts function 2-32

getCustomer function 2-13

input parameters 2-8, 2-14, 2-38

output parameters 2-14, 2-32, 2-35

getCustomerList function 2-34

input parameters 2-32, 2-34

output parameters 2-32, 2-35

I

implementation overview 1-2

O

overview 1-1

P

programming example 3-1

R

references 1-4

results 1-3

IN-2Service Node OSS/BSS Integration Guide

S

shutdownCustomer function 2-56

input parameters 2-56, 2-58, 2-60

output parameters 2-56, 2-58, 2-60

suspendCustomer function 2-58



T

timezone field, supported values 2-74

U

unsuspendCustomer function 2-60



updateAgent function 2-69



updateCustomer function 2-40



updateCustomerNumbers function 2-7



V

validation 1-3

OL-16960-01