Nortel AS 5300 User guide

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
Copyright © 2008 Nortel Networks
All Rights Reserved.
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.
.

3
.
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
Why use the Bulk Provisioning Tool 10
Bulk Provisioning Tool requirements 11
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
Files 16
Scripts 17
BPT conventions and examples 17
Method and file syntax conventions 17
Create and manage provisioning roles using the BPT 21
BPT Help option 24
BPT limitations 25
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 AS 5300
Nortel Application Server 5300 Application Programming Interfaces Reference
NN42040-110 01.01 Standard
11 June 2008
Copyright © 2008 Nortel Networks
.

4
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 AS 5300
Nortel Application Server 5300 Application Programming Interfaces Reference
NN42040-110 01.01 Standard
11 June 2008
Copyright © 2008 Nortel Networks
.

5
.
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 AS 5300
Nortel Application Server 5300 Application Programming Interfaces Reference
NN42040-110 01.01 Standard
11 June 2008
Copyright © 2008 Nortel Networks
.

6New in this release
Nortel AS 5300
Nortel Application Server 5300 Application Programming Interfaces Reference
NN42040-110 01.01 Standard
11 June 2008
Copyright © 2008 Nortel Networks
.

7
.
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 AS 5300
Nortel Application Server 5300 Application Programming Interfaces Reference
NN42040-110 01.01 Standard
11 June 2008
Copyright © 2008 Nortel Networks
.

8Introduction
Nortel AS 5300
Nortel Application Server 5300 Application Programming Interfaces Reference
NN42040-110 01.01 Standard
11 June 2008
Copyright © 2008 Nortel Networks
.

9
.
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 AS 5300
Nortel Application Server 5300 Application Programming Interfaces Reference
NN42040-110 01.01 Standard
11 June 2008
Copyright © 2008 Nortel Networks
.

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 www.w3.org/TR/wsdl.
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.
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 AS 5300
Nortel Application Server 5300 Application Programming Interfaces Reference
NN42040-110 01.01 Standard
11 June 2008
Copyright © 2008 Nortel Networks
.

Bulk Provisioning Tool fundamentals 11
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
Minimum PC or terminal
requirements Java 1.6 + JRE in the system classpath
For telnet remote access Compatible (tested) telnet terminals:
•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 AS 5300
Nortel Application Server 5300 Application Programming Interfaces Reference
NN42040-110 01.01 Standard
11 June 2008
Copyright © 2008 Nortel Networks
.

12 Application Programming Interface fundamentals
Nortel AS 5300
Nortel Application Server 5300 Application Programming Interfaces Reference
NN42040-110 01.01 Standard
11 June 2008
Copyright © 2008 Nortel Networks
.

13
.
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 AS 5300
Nortel Application Server 5300 Application Programming Interfaces Reference
NN42040-110 01.01 Standard
11 June 2008
Copyright © 2008 Nortel Networks
.

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 1and
press Enter. The BPT displays the Domain Operations submenu.
Figure 2
Accessing the Domain Operations submenu
Nortel AS 5300
Nortel Application Server 5300 Application Programming Interfaces Reference
NN42040-110 01.01 Standard
11 June 2008
Copyright © 2008 Nortel Networks
.

BPT main menu 15
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
Command Description
0Return to the previous menu.
1-97 Execute the given method or continue to a submenu.
98 <file name> Execute all methods inside the specified file. Each line in
the file must be a method in a valid format.
99 Exit the BPT.
quit Exit the BPT.
help Display this list of commands.
help <method name> Display the usage for a given method.
<method name> using (<parm a>,
<parm b>) 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.
<method name> using file <file
name> 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.
<method name> using * into
<file name> 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 AS 5300
Nortel Application Server 5300 Application Programming Interfaces Reference
NN42040-110 01.01 Standard
11 June 2008
Copyright © 2008 Nortel Networks
.

16 Using the Bulk Provisioning Tool
Table 3
BPT main menu commands (cont’d.)
Command Description
execute <file name> Execute all the methods contained in the specified file.
Each line in the file must be a method in the valid format.
execute <file name> into <file
name> 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.
For information about BPT command syntax conventions and examples, see "BPT
conventions and examples" (page 17).
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 files 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 AS 5300
Nortel Application Server 5300 Application Programming Interfaces Reference
NN42040-110 01.01 Standard
11 June 2008
Copyright © 2008 Nortel Networks
.

BPT conventions and examples 17
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)).
ScriptsA 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.
Navigation
•"Method and file syntax conventions" (page 17)
•"Create and manage provisioning roles using the BPT" (page 21)
Method and file 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 AS 5300
Nortel Application Server 5300 Application Programming Interfaces Reference
NN42040-110 01.01 Standard
11 June 2008
Copyright © 2008 Nortel Networks
.

18 Using the Bulk Provisioning Tool
Optional syntax
In BPT provisioning method syntax, the word [optional] indicates that what
follows is optional and is not needed to invoke the method. Typically,
the option is the writing of the returned values to a text file. You do not
include [optional] when entering the syntax. For example, the following is
the complete syntax for the getSysRoles method:
getSysRoles [optional] into <file name>
To write the returned information to the screen, you use the syntax:
getSysRoles. To write the returned information to a file named
roles.txt, you use the syntax: getSysRoles into roles.txt. The
system creates the file with the name entered in the BPT command line.
When a get* command is not limited to a specific instance (for example,
getSysRoles or getAllRights), you cannot use the shortcut number
(BPT main menu option) when writing to a file. You must enter the BPT
provisioning method syntax on the BPT command line. If you use the
shortcut number, the returned information is written to the screen by
default.
Brackets
Brackets () are required around the parameters when shown in the BPT
provisioning method syntax. For example, the following is the syntax for
the getRole provisioning method:
getRole using (Role name) | file <file name> [optional] into
<file name>
With this provisioning method, brackets are required around the
provisioning Role name. For example, to retrieve the definition for the
configured SuperUser role, you use the following syntax: getRole
using (SuperUser).
Angle brackets
Angle brackets (<>) in the syntax indicate a variable. You replace the
variable name and angle brackets with the specific variable when you
invoke the provisioning method. For example, the following is the syntax
for the getSysRoles provisioning method:
getSysRoles [optional] into <file name>
With this provisioning method, the angle brackets indicate that file name
is a variable, replaced when using the provisioning method. For example,
if you want to write the returned values to a file name called roles.txt,
you use the syntax: getSysRoles into roles.txt.
Nortel AS 5300
Nortel Application Server 5300 Application Programming Interfaces Reference
NN42040-110 01.01 Standard
11 June 2008
Copyright © 2008 Nortel Networks
.

BPT conventions and examples 19
Square brackets
Square brackets ([ ]) in the syntax indicate a string of variables, separated
by commas. The square brackets must be included when shown in the
BPT provisioning method syntax. For example, the following is the syntax
for the addRole provisioning method:
addRole using ([Name of the Provisioning Role,Description
of the Role,[[The Provisioning Right Type,The Read
privilege,The write privilege,The delete privilege], ..
,[The Provisioning Right Type,The Read privilege,The write
privilege,The delete privilege]]]) | file <file name>
[optional] into <file name>
With this provisioning method, the square brackets separate fields
of the role description being added. For example, if you are adding
a role called AddExample, the syntax looks like: addRole using
([AddExample,BPT add example,[[Domain Management,
true,true,false],[Device Management,true,false,
false],[Admin,true,true,true]]]).
Bar
A bar (|) in the syntax means that there are two ways of entering the
required provisioning method information. Typically, the bar is used for the
data entry option—entering the data in the command line or using data in a
file. For example, the following is the syntax for the getRole provisioning
method:
getRole using (Role name) | file <file name> [optional] into
<file name>
With this provisioning method, you can enter the Role name in the BPT
command line, or enter it using a file. For example, the following is the
syntax for invoking the provisioning method on the BPT command line for
the Superuser role: getRole using (SuperUser).
Optionally, you can invoke the provisioning method using the Role name
listed in a file. For example, the following is the syntax to invoke the
provisioning method using a file (containing the Superuser role) called
SuperUser_role.txt:getRole using file SuperUser_role.txt.
The contents of the file must be in the correct format. Use the help
command to display the BPT required file format. Note in the above
example, that the role name in the file is not enclosed in brackets as it is if
this method is invoked from the BPT command line.
Nortel AS 5300
Nortel Application Server 5300 Application Programming Interfaces Reference
NN42040-110 01.01 Standard
11 June 2008
Copyright © 2008 Nortel Networks
.

20 Using the Bulk Provisioning Tool
Comma separated strings
Provisioning method syntax can include a string of comma-separated
variables. For example, the following is the syntax for the addAdmin
provisioning method:
addAdmin using ([The Admin user name,Password,Admin
First Name,Admin Last Name,Admin Status,Admin Email
Address,Office Phone Number,Home Phone Number,Cell Phone
Number,Pager Number,Fax Number,Voicemail Number,VPN
Number,System defined role,Time Zone,Locale,Provisioning
Role,[The list of Domains that he is assigned to, .. ,The
list of Domains that he is assigned to]]) | file <file name>
[optional] into <file name>
Follow the required format when invoking the provisioning method
from the BPT command line or using a file. If nothing appears
between two commas, the associated field in the database is
not updated. For example, the following addAdmin provisioning
method contains minimal administrator information, but still
requires the commas to denote the blank fields: addAdmin using
([newguy,mysecret,John,Edwards,Active,,,, ,,,,,Default
Admin,,English,Devices only,[yourcompany.com]]).
Fully qualified user name
Some methods require a fully qualified user name—a user name that is
complete with the domain name (for example, [email protected]). This
information is available in the Provisioning Client field descriptions.
Success indication on remove methods
Some BPT provisioning methods can remove data, and return an
indication of success even if the data did not preexist in the database. This
mirrors the functionality of the database. A success indication for a remove
provisioning method, indicates that the associated data no longer exists
in the database.
When possible, BPT provisioning methods provide additional indication (in
the form of an error message) regarding specific data elements (domain
and devices) that are not preexisting in the database when the remove
method is invoked. These messages appear on the BPT screen.
For example, if the domain nn.com does not exist, an invocation of
removeUser using ([email protected]) returns an error indication of
Invalid Data: Domain Not found ’nn.com’, because the domain
is not valid.
If the domain is valid and the user is not preexisting, then a success
indication is returned, because the user is not configured on the system.
Nortel AS 5300
Nortel Application Server 5300 Application Programming Interfaces Reference
NN42040-110 01.01 Standard
11 June 2008
Copyright © 2008 Nortel Networks
.