Nortel Networks AS 5300 User Manual 2

Nortel AS 5300

Nortel Application Server 5300 Application Programming Interfaces Reference

Release: 1.0 Document Revision: 01.01

www.nortel.com

NN42040-110

Nortel AS 5300 Release: 1.0 Publication: NN42040-110 Document status: Standard Document release date: 11 June 2008

Sourced in Canada

LEGAL NOTICE

While the information in this document is believed to be accurate and reliable, except as otherwise expressly agreed to in writing NORTEL PROVIDES THIS DOCUMENT "AS IS" WITHOUT WARRANTY OR CONDITION OF ANY KIND, EITHER EXPRESS OR IMPLIED. The information and/or products described in this document are subject to change without notice.

Nortel, the Nortel logo, and the Globemark are trademarks of Nortel Networks.

All other trademarks are the property of their respective owners.

Contents

New in this release 5

Other changes 5

Introduction 7

Audience 7 Related documents 7

Application Programming Interface fundamentals 9

Open Provisioning Interface fundamentals 9 Bulk Provisioning Tool fundamentals 10

Using the Bulk Provisioning Tool 13

Install and launch the BPT 13 BPT main menu 13 BPT provisioning methods 16 BPT files and scripts 16

BPT conventions and examples 17

BPT Help option 24 BPT limitations 25

Why use the Bulk Provisioning Tool 10 Bulk Provisioning Tool requirements 11

Files 16 Scripts 17

Method and file syntax conventions 17 Create and manage provisioning roles using the BPT 21

BPT mapping to the Provisioning Client 25 Batch processing 26 Resource use 26 Provisioning data visibility 27

Using the Open Provisioning Interface 29

Security, authentication, and authorization 29

Security 29 Authentication 30 Authorization 32

Third-party client development 33

Nortel Application Server 5300 Application Programming Interfaces Reference

Nortel AS 5300

NN42040-110 01.01 Standard

11 June 2008

Get the WSDL 33 Generate stubs 33 Implement interface accessing stubs 34 Access stubs from the third-party application 34

Starting the Bulk Provisioning Tool 35

Downloading the Bulk Provisioning Tool to a workstation 36 Launching the BPT on a workstation 36

Creating Open Provisioning Interface clients 39

Downloading the Axis toolkit 41 Retrieving the error codes 41 Configuring the class path 41 Downloading the WSDL file 42 Compiling the client stubs 42 Writing a client to perform some specific OPI operations 43

Accessing the OPI Java docs 47 Importing a CA Certificate into the BPT 51

Nortel Application Server 5300 Application Programming Interfaces Reference

Nortel AS 5300

NN42040-110 01.01 Standard

11 June 2008

New in this release

This chapter details what’s new in Nortel AS 5300 Application Programming Interface Reference, NN42040-110 for Nortel Application

Server (AS) 5300 Release 1.0. This document is new for Nortel AS 5300 Release 1.0.

Other changes

Table 1 Revision history

June 11, 2008 Standard 01.01. This document is new for Nortel AS 5300 Release 1.0.

Nortel Application Server 5300 Application Programming Interfaces Reference

Nortel AS 5300

NN42040-110 01.01 Standard

11 June 2008

6 New in this release

Nortel Application Server 5300 Application Programming Interfaces Reference

Nortel AS 5300

NN42040-110 01.01 Standard

11 June 2008

Introduction

This document discusses the Nortel Application Server (AS) 5300 Application Programming Interface (API) available to third party clients for provisioning and administering the AS 5300 system from a remote workstation.

Attention: Some services/features referred to in this document are not supported in AS 5300 Release 1.0. For more information about what services/features are supported in AS 5300 Release 1.0, see Nortel Application Server 5300 Overview, (NN42040-100).

Navigation

•

"Application Programming Interface fundamentals" (page 9)

•

"Using the Bulk Provisioning Tool" (page 13)

•

"Using the Open Provisioning Interface" (page 29)

•

"Starting the Bulk Provisioning Tool" (page 35)

•

"Creating Open Provisioning Interface clients" (page 39)

•

"Accessing the OPI Java docs" (page 47)

•

"Importing a CA Certificate into the BPT" (page 51)

Audience

This document is for programmers and administrators, and assumes that the reader is familiar with object-oriented programming.

Related documents

The following AS 5300 documents contain related material:

• Personal Agent User Guide, NN42040-105

• Alarm and Log Reference, NN42040-701

Nortel Application Server 5300 Application Programming Interfaces Reference

Nortel AS 5300

NN42040-110 01.01 Standard

11 June 2008

8 Introduction

Nortel Application Server 5300 Application Programming Interfaces Reference

Nortel AS 5300

NN42040-110 01.01 Standard

11 June 2008

Application Programming Interface fundamentals

The Application Server (AS) 5300 provides Application Programming Interface (API) support for third-party client applications. This support consists of one main API and one tool:

•

Open Provisioning Interface (OPI)

• Bulk Provisioning Tool (BPT)

Open Provisioning Interface (OPI) is an API for third-party client applications, and is the foundation for the Bulk Provisioning Tool (BPT). The BPT facilitates the provisioning of the AS 5300 system with large (bulk) amounts of data. It also retrieves large (bulk) amounts of data from the AS 5300 system.

Navigation

•

"Open Provisioning Interface fundamentals" (page 9)

•

"Bulk Provisioning Tool fundamentals" (page 10)

Open Provisioning Interface fundamentals

The OPI is used to remotely provision the AS 5300 system. OPI is based on version 1.1 of the Simple Object Access Protocol (SOAP) and the emerging Web services standard. SOAP is a cross-platform, cross-language, text-based protocol, utilizing the benefits of Extensible Markup Language (XML). SOAP is commonly used as a tool in distributed applications named Web services. SOAP is not transport dependent, therefore OPI uses Hyper Text Transfer Protocol (HTTP) as a transport protocol.

OPI supports version 1.1 of the industry-standard Web Services Description Language (WSDL). WSDL is an XML language that contains information about the interface, semantics, and administration of a call to a Web service. WSDL enables service providers to provision their AS 5300 system with existing and custom applications. By supporting the WSDL

Nortel Application Server 5300 Application Programming Interfaces Reference

NN42040-110 01.01 Standard

Nortel AS 5300

11 June 2008

10 Application Programming Interface fundamentals

standard, service providers rapidly develop client-side code with standard toolsets. A detailed description of the WSDL standard is available online at the World Wide Web Consortium (W3C) web site at w

The goal of OPI is to allow customer-specific applications to interface with the AS provisioning system. Once developed, the application passes an object to a generated stub. The stub translates the object into a SOAP message and passes it along to the skeleton in the Provisioning Manager. The skeleton translates the SOAP message back to an object, and sends it to the Provisioning Manager data access processes. The data access processes the interface with the Oracle Database. The translations happen in reverse from the database to the customer application.

Bulk Provisioning Tool fundamentals

The Bulk Provisioning Tool (BPT) enables administrators to provision Application Server (AS) 5300 services from outside the Provisioning Client. It enables both bulk transactions and individual requests. The BPT is built on the Open Provisioning Interface (OPI), and accesses all the commands available through the OPI.

ww.w3.org/TR/wsdl.

Communications between the BPT and the Provisioning server use the OPI. OPI itself is the Simple Object Access Protocol (SOAP) over HTTP.

Attention: Do not use the BPT for large transactions during regular business hours. In deployments where the BPT uses the same network (LAN) as the LAN processing sessions, large BPT transactions may impact network performance.

Why use the Bulk Provisioning Tool

The BPT is extremely useful for provisioning systems with numerous subscribers. Some of the scenarios where administrators benefit from using the BPT are:

• adding a large number of subscribersThe BPT provides bulk imports of

provisioning data from text files. The files can be generated from other applications.

• exporting provisioning dataThe BPT provides bulk exports of

provisioning data, writing it to files. The files can then be used with other applications.

• modifying a large number of subscribersThe BPT enables bulk

modifications, such as modifying subscriber service packages when new features are added.

• extracting information from the database for reporting purposesFor

example, a list of provisioned subscribers can be extracted from the

Nortel Application Server 5300 Application Programming Interfaces Reference

Nortel AS 5300

NN42040-110 01.01 Standard

11 June 2008

database with the BPT and compared against active subscribers listed in the Internet Protocol Detail Record (IPDR) accounting records. As another example, a list of gateways can be extracted and imported into a downstream billing application.

Bulk Provisioning Tool requirements

The following table lists the requirements to run the BPT.

Table 2 Bulk Provisioning Tool requirements

Bulk Provisioning Tool fundamentals 11

Minimum PC or terminal requirements

For telnet remote access Compatible (tested) telnet terminals:

Java 1.6 + JRE in the system classpath

•

Windows Telnet client

• Putty

•

Hummingbird Telnet

•

KevTerm

Noncompatible telnet terminals:

• CRT

Log on requirement To begin a BPT session, the administrator needs to be, at minimum,

a provisioned general administrator.

Nortel Application Server 5300 Application Programming Interfaces Reference

Nortel AS 5300

NN42040-110 01.01 Standard

11 June 2008

12 Application Programming Interface fundamentals

Nortel Application Server 5300 Application Programming Interfaces Reference

Nortel AS 5300

NN42040-110 01.01 Standard

11 June 2008

Using the Bulk Provisioning Tool

This chapter contains all of the information you need to use the AS 5300 Bulk Provisioning Tool (BPT).

Navigation

•

"Install and launch the BPT" (page 13)

• "BPT main menu" (page 13)

• "BPT provisioning methods" (page 16)

• "BPT files and scripts" (page 16)

• "BPT conventions and examples" (page 17)

•

"BPT Help option" (page 24)

•

"BPT limitations" (page 25)

Install and launch the BPT

For procedures on downloading, installing, and launching the BPT, see

"Starting the Bulk Provisioning Tool" (page 35).

BPT main menu

The BPT main menu lists the various categories of available BPT provisioning methods.

After successfully logging on to the workstation, the BPT main menu appears.

Nortel Application Server 5300 Application Programming Interfaces Reference

Nortel AS 5300

NN42040-110 01.01 Standard

11 June 2008

14 Using the Bulk Provisioning Tool

Figure 1 BPT main menu

An arrow following a menu item indicates a submenu. Choose the submenu by entering the menu item number at the prompt.

For example, to access the Domain Operations submenu, type 1 and press Enter. The BPT displays the Domain Operations submenu.

Figure 2 Accessing the Domain Operations submenu

Nortel Application Server 5300 Application Programming Interfaces Reference

Nortel AS 5300

NN42040-110 01.01 Standard

11 June 2008

Entering 0 (zero) returns you to the parent of a submenu. The provisioning method name appears inside the parentheses that follow

the provisioning method description in the menu. The menu structure is only for usability. Any provisioning method can be entered at the prompt, regardless of the menu opened.

For example, if you want to execute the getRootDomain provisioning method, you do not need to be in the Domain Operations menu.

The following table lists the available BPT main menu commands.

Table 3 BPT main menu commands

BPT main menu 15

Command

0 1-97 98 <file name>

99 quit help help <method name> <method name> using (<parm a>,

<parm b>)

<method name> using file <file name>

<method name> using * into <file name>

Description

Return to the previous menu. Execute the given method or continue to a submenu. Execute all methods inside the specified file. Each line in

the file must be a method in a valid format. Exit the BPT. Exit the BPT. Display this list of commands. Display the usage for a given method. Execute the given method with the required parameters.

The parameter list must be separated by commas and must adhere to the order presented in the syntax description. If no parameters are required, this can be left blank.

Execute the given method with the parameters contained in the specified file. This command is useful for bulk additions (for example, users, telephones), allowing the separation of the definition and execution of the method.

Execute the given method (using either command line options or parameters from a file) and insert the returned value into the specified file. This is useful when exporting bulk data, such as 1000 users, and you want to save the output.

For information about BPT command syntax conventions and examples, see "BPT

conventions and examples" (page 17).

Nortel Application Server 5300 Application Programming Interfaces Reference

NN42040-110 01.01 Standard

Nortel AS 5300

11 June 2008

16 Using the Bulk Provisioning Tool

Table 3 BPT main menu commands (cont’d.)

Command

execute <file name>

execute <file name> into <file name>

For information about BPT command syntax conventions and examples, see "BPT

conventions and examples" (page 17).

Description

Execute all the methods contained in the specified file. Each line in the file must be a method in the valid format.

Execute all the methods contained in the specified file and writes the output to a second file instead of writing the output to the screen. Each line in the input file must be a method in the valid format.

BPT provisioning methods

The BPT provisioning methods are the same as the Open Provisioning Interface (OPI) provisioning methods. OPI provisioning methods are a collection of Web services that you use to provision subscribers, and service data for the subscribers. The detailed documentation for each of the OPI Web services is available in a zip file (OPIJavaDocs.zip) included on the AS 5300 Documentation CD.

To access the OPI Web services documentation, see "Accessing the OPI

Java docs" (page 47).

BPT ﬁles and scripts

Files and scripts are important when performing bulk provisioning transactions. Files enable the import and export of many database entries. Scripts enable administrators to execute multiple BPT provisioning methods in one step.

This section describes the role of files and scripts in the Bulk Provisioning Tool.

Navigation

• "Files" (page 16)

• "Scripts" (page 17)

Files

Most of the BPT provisioning methods have the option of using text files. Provisioning data can be imported from a file and put into the database, or exported from the database and written to text files.

Text file (*.txt) contents use the comma separated value (CSV) format. By using this format, files can be generated by, or imported into, third-party applications that recognize the CSV file content.

Nortel Application Server 5300 Application Programming Interfaces Reference

Nortel AS 5300

NN42040-110 01.01 Standard

11 June 2008

Files must use a specific syntax for a BPT provisioning method to be invoked successfully on the Provisioning Server. You can view the required file syntax by using the BPT Help option ("BPT Help option" (page

24)).

Scripts

A script is basically a text file, where each line of the file consists of a single provisioning method. When executed, each provisioning method in the script is invoked sequentially and can reference a separate file for importing or exporting data. Each provisioning method and its referenced file must use the correct syntax for the script to be executed successfully.

An exclamation mark (!) is used at the start of a line to add a comment line in the script file (for example: ! - script updated 2008.04.01)

BPT conventions and examples

This section describes the command syntax and usage conventions for Bulk Provisioning Tool (BPT) provisioning methods and an example of a provisioning method.

BPT conventions and examples 17

Navigation

• "Method and file syntax conventions" (page 17)

•

"Create and manage provisioning roles using the BPT" (page 21)

Method and ﬁle syntax conventions

This section describes the command syntax that must be used for executing BPT provisioning methods from the BPT command line and BPT input files.

Navigation

• "Optional syntax" (page 18)

•

"Brackets" (page 18)

•

"Angle brackets" (page 18)

• "Square brackets" (page 19)

• "Bar" (page 19)

• "Comma separated strings" (page 20)

• "Fully qualified user name" (page 20)

• "Success indication on remove methods" (page 20)

• "Unknown error messages" (page 21)

Nortel Application Server 5300 Application Programming Interfaces Reference

Nortel AS 5300

NN42040-110 01.01 Standard

11 June 2008

+ 37 hidden pages