Nortel NN42020-123 User manual

NN42020-123
Multimedia Communication Portfolio
Multimedia Communication
Server
Open Provisioning Interface
MCS 5100 3.5 Standard 4.0 January 2006

Open Provisioning Interface Reference Guide
Copyright © Nortel Networks Limited 2006
Finding the latest updates on the Nortel Web site
The content of this documentation was current at the time the product was released. To
check for updates to the latest documentation and software for MCS 5100, click one of
the following links:
Link to Takes you directly to the
Latest Software Nortel page for MCS 5100 software located at
www130.nortelnetworks.com/cgi-bin/eserv/cs/
main.jsp?cscat=SOFTWARE&resetFilter=1&tranProduct=124
82
Latest Documentation Nortel page for MCS 5100 documentation located at
www130.nortelnetworks.com/cgi-bin/eserv/cs/
main.jsp?cscat=DOCUMENTATION&resetFilter=1&tranProdu
ct=12482

NN42020-123 MCS 5100 3.5 Standard 4.0 4.0 January 2006
4
Copyright © Nortel Networks Limited 2006

Open Provisioning Interface Reference Guide
Copyright © Nortel Networks Limited 2006
How to get help
This section explains how to get help for Nortel products and services.
Getting help from the Nortel web site
The best way to get technical support for Nortel products is from the Nortel Technical Support
web site:
www.nortel.com/support
This site provides quick access to software, documentation, bulletins, and tools to address
issues with Nortel products. From this site, you can:
• download software, documentation, and product bulletins
• search the Technical Support Web site and the Nortel Knowledge Base for answers
to technical issues
• sign up for automatic notification of new software and documentation for Nortel
equipment
• open and manage technical support cases
Getting help over the phone from a Nortel Solutions Center
If you do not find the information you require on the Nortel Technical Support web site, and
you have a Nortel support contract, you can also get help over the phone from a Nortel Solu-
tions Center.
In North America, call 1-800-4NORTEL (1-800-466-7835).
Outside North America, go to the following web site to obtain the phone number for your
region:
www.nortel.com/callus

NN42020-123 MCS 5100 3.5 Standard 4.0 4.0 January 2006
6
Copyright © Nortel Networks Limited 2006
Getting help from a specialist by using an Express Routing Code
To access some Nortel Technical Solutions Centers, you can use an Express Routing Code
(ERC) to quickly route your call to a specialist in your Nortel product or service. To locate the
ERC for your product or service, go to:
www.nortel.com/erc
Getting help through a Nortel distributor or reseller
If you purchased a service contract for your Nortel product from a distributor or authorized
reseller, contact the technical support staff for that distributor or reseller.

Open Provisioning Interface Reference Guide
Copyright © Nortel Networks Limited 2006
Open Provisioning Interface
Topics in this chapter
•Open Provisioning Interface introduction
•Third party client development
•Authentication and authorization
•Provisioning Interface
•Deprecated methods and method fields
Open Provisioning Interface introduction
The Open Provisioning Interface (OPI) is used to remotely provision the
Multimedia Communication Server (MCS) system. OPI is based on the
Simple Object Access Protocol (SOAP) 1.1 and the emerging web
services standard. SOAP is a cross-platform, cross-language text
based protocol utilizing the benefits of XML (extensible Markup
Language). SOAP is commonly used as a tool in distributed
applications named web services. While SOAP in itself is not transport
dependent, OPI relies on HTTP (Hyper Text Transfer Protocol) as its
transport.
OPI gives the service provider the means to integrate MCS provisioning
with their own applications by allowing:
• Machine-to-machine interface for provisioning tasks
• Pass-through provisioning from existing provisioning systems
• Support for the Bulk Provisioning Tool
For information on the BPT, refer to the Bulk Provisioning Tool
Reference Guide.
Web Services Description Language (WSDL) 1.1
OPI supports the industry standard Web Services Description
Language (WSDL) 1.1. WSDL allows the service provider to provision
their MCS system with existing and custom applications. By supporting
the WSDL standard, service providers can rapidly develop client side
code with standard toolsets.

NN42020-123 MCS 5100 3.5 Standard 4.0 4.0 January 2006
8
Copyright © Nortel Networks Limited 2006
WSDL is an XML language that contains information about the
interface, semantics and administration of a call to a web service. A
detail description of the WSDL standard is available online at the W3C
(World Wide Web Consortium) web site at the following URL:
www.w3.org/TR/wsdl
Third party client development
The goal of OPI is to allow customer third party applications to interface
with the MCS provisioning system. Once developed, the third party
application will pass an object to a generated stub. The stub will
translate the object into a SOAP message and pass it along to the
skeleton in the Provisioning Module. The skeleton translates the SOAP
message back to an object, and sends it to the Provisioning Module
data store processes. The data store then interfaces with the Oracle
Database. The translations happen in reverse from the Database to the
third party application.
Figure 1 Logical view of OPI interactions
The development of third party provisioning clients involves the
following steps:
• Get the WSDL
• Generate Stub using supported toolkit that supports complex type
• Implement interface to access stubs
• Access stubs from the third party application
Skeleton
Provisioning Module
Oracle
Database
3rd party
application
Stub
Data Store
WSDL
file

Open Provisioning Interface Reference Guide
9
Copyright © Nortel Networks Limited 2006
Get the WSDL
The WSDL file for MCS is stored on the server hosting the Provisioning
Module. You can view and download the WSDL using a web browser.
Note: By definition, all the OPI commands (methods) are listed in
the WSDL.
From a workstation
1Open a web browser
2To display the WSDL in the web browser, navigate to the
following URL
http://<provclientIP>/prov/services/OPI?WSDL
Where:
<provclientIP> is the IP address used by the Provisioning Client
3Download the WSDL file
Generate stubs
The stub is basically a translator. It takes the “user” object (whatever
type of object) from the interface and converts it to a SOAP message
and sends it to the Provisioning Module. Likewise, a SOAP message
from the Provisioning Module is translated back to the object. HTTP is
used as the transport for OPI. The Provisioning Module listens on port
80 for the SOAP over HTTP messages.
Figure 2 Interactions of the stub
Stubs are generated using a supported toolset. Currently, only the
Apache AXIS 1.0 (Apache extensible Interaction System
http://ws.apache.org/axis) toolset has been tested and approved. AXIS
is Java specific and creates a Java stub. The OPI WSDL may work with
other toolsets, but thorough testing has not yet been completed. Other
Stub
Provisioning
Module
Third Party
Application
object
SOAP over HTTP port 80

NN42020-123 MCS 5100 3.5 Standard 4.0 4.0 January 2006
10
Copyright © Nortel Networks Limited 2006
toolsets may be supported in subsequent releases once testing has
been completed.
Refer to the chapter Building OPI clients for an example of generating
a Java stub.
Implement interface accessing stubs
An interface must be developed that will access the stubs. The interface
must support authentication on each OPI request.
If the credentials are not present, or fail validation, a SOAP fault will be
sent back indicating the failure and the action will not be performed.
Refer to Error codes and messages on page 29 for a complete list of
error messages.
Access stubs from the third-party application
When the interface accesses/invokes the stubs, the stub will generate
a SOAP message that will be sent to the Provisioning Module on port
80. The stub is basically a translator. It takes the “user” object (whatever
type of object) from the interface and converts it to a SOAP message
and sends it to the Provisioning Module. The skeleton on the server
with the Provisioning Module does the reverse. It takes the SOAP
message and translates it back to a “user” object (whatever type of
object) and sends it to the Provisioning Module’s Data Store that stores
it in the database.
Authentication and authorization
Authentication and authorization of OPI requests are briefly described
in the following sections:
•Authentication
•Authorization
For more information on this topic, please refer to the Provisioning
Client User Guide.
Authentication
Each OPI request is authenticated using HTTP basic authentication.
Each request is required to pass a username and password before
gaining access to the interface. Therefore, there is no login/logout
interface as the request is authenticated on each request. If the
credentials are not present, or fail validation, a SOAP fault will be sent
back indicating the failure and the action will not be performed. The
credentials are verified against any active administrator in the MCS

Open Provisioning Interface Reference Guide
11
Copyright © Nortel Networks Limited 2006
system. These administrators can be added/modified through both the
Provisioning Client and the OPI itself.
Utilizing, the standard HTTP basic authentication enables OPI to be
interoperable with the common web services toolsets. Typically, the
toolsets allow for simple inclusion of username and password adhering
to this standard. Within the MCS system the authentication is
performed locally in memory to alleviate the reoccurring authentication.
In addition, the authentication and authorization are kept in
synchronization with the Provisioning Client, so changes to the
administrator profile from either the Provisioning Client or the OPI are
immediately effective.
Authorization
Authentication is the first step in processing the incoming request. Once
the request has been authenticated, the administrator must clear
authorization before performing the action. The authorization includes
both domain-level authorization and provisioning-level authorization. If
either fails validation, a SOAP fault is send back indicating the reason
for failure, and the action will not be preformed.
Domain-level authorization
Each administrator is assigned one or more domains for access and
control (this can be overridden by the "All domain access" in role
creation). For instance, the MCS system might consist of three
separate domains, Widget.com, Gadget.com, and Sprocket.com. An
administrator, WidgetAdmin, can be created with only Widget.com in
the list of "provisionable domains". This limits WidgetAdmin to
provisioning activities inside of this domain only, and will not permit
access to the other domains. Therefore, if a request from WidgetAdmin
comes in to modify a user outside of his domain, it will be rejected
having failed authorization. In addition, attempts to list domain
information will only return Widget.com information.
Provisioning-Level authorization
The provisioning module of the MCS system is broken into various
major categories (Domains, Users, Telephony Routes, etc.). The
provisioning system allows for various administrator roles to be created
across these categories. Upon creation, the administrator is assigned
to a particular role. This allows the service provider to create various
administrator roles to suit their specific needs. In each category the role
can have any combination of the following rights: Read, Write, and
Delete. For example, a "user admin role" could be created which only
had the ability to read domain info, and read, modify, and delete user
information. The administrators given this role will not be able to
manipulate the telephony routes, or other areas of the MCS system.

NN42020-123 MCS 5100 3.5 Standard 4.0 4.0 January 2006
12
Copyright © Nortel Networks Limited 2006
OPI authorizes each request to verify the incoming credentials have the
appropriate role to perform the given action.
Provisioning Interface
The following list is a summary of the provisioning object types
contained within the WSDL. Detailed information on the provisioning
objects and their types can be found in the WSDL file.
• Simple Types:
— Boolean
— Byte
— Double
—Float
— Integer
— Long
—Short
—String
• Complex types (Domain, User, Route, etc..)
• "Type[] = Array of Type (i.e. String[] = Array of Strings)
• Method summaries consist of method description with return type
• Return type of void implies no response
This document does not cover the various actions that can be
performed through the OPI interface. Nor is it intended to cover in detail
what affect these changes make to the MCS system, but rather to give
an overview of the OPI the interface. The Provisioning Client User
Guide (NN42020-105) details provisionable entities and their role in the
MCS system. In addition, the MCS Bulk Provisioning Tool Reference
Guide (NN42020-501) lists the provisioning methods available using
the Bulk Provisioning Tool (BPT) command line. The BPT also uses the
OPI interface.
Success indication on remove methods
Some OPI Interface methods, that provide the ability to remove data,
return indication of success even though the data did not pre-exist in the
database. This mirrors the functionality of the database. Basically, a
success indication for a "remove" OPI Interface method indicates that
the associated data no longer exists in the database.
When possible, OPI Interface methods provide additional indication (in
the form of an error message) regarding specific data elements

Open Provisioning Interface Reference Guide
13
Copyright © Nortel Networks Limited 2006
(domain and devices) that are not pre-existing in the database when the
remove method is invoked.
Example
An invocation of "removeUser using ([email protected])" will return
an error indication, "Invalid Data: Domain Not found 'nn.com'", since
the domain is not valid.
But if the domain is valid and the user is not pre-existing, then a success
indication will be returned since the user is not provisioned on the
system.
Provisioning data visibility
Provisioning data added via the OPI is immediately available to other
provisioning clients connected to the same instance of the Provisioning
Module. However, it may take up to 5 minutes before the same data is
visible to clients connected to a second instance of a provisioning
module running in the system.
PROV606 logs
PROV606 logs capture all provisioning activity performed using the
OPI, including the administrator performing the task. The logs
generated by OPI clients display the request type OPI. The logs are
viewed in the System Management Console’s log browser and are
described in the Provisioning Module Basics (NN10274-111) guide.
Deprecated methods and method fields
Methods and their associated parameters (elements) defined in the
WSDL change as features and services are added and improved. With
each release, new methods are may be added, and others may
deprecated. Deprecated methods are being removed, but are
supported in the current release.
New methods can be found through a comparison of the WSDL of this
release with the WSDL of a previous release. Deprecated methods and
method parameters are more difficult to find, as they are still supported,
and therefore still in the WSDL. The following tables identify the
deprecated methods for this release.
Table 1 Deprecated methods
Deprecated methods
addPooledResource
deletePooledResource

NN42020-123 MCS 5100 3.5 Standard 4.0 4.0 January 2006
14
Copyright © Nortel Networks Limited 2006
The following table lists deprecated elements. These correspond to
fields in the Provisioning Client, and method parameters in the BPT.
getAllPooledResources
getAllPooledResourceTypes
getAllRoutingAlgorithms
getIPCMCapacityByDomain
getPooledResource
modifyPooledResource
modifyServiceParm
setServiceParmAsDefault
Table 2 Deprecated method elements (Sheet 1 of 2)
Affected method Deprecated method element
addDevice activeProxy
defaultProxyHost
defaultProxyPort
ipcm
rtpPort
addDevices activeProxy
defaultProxyHost
defaultProxyPort
ipcm
rtpPort
modifyDevice activeProxy
defaultProxyHost
defaultProxyPort
ipcm
rtpPort
Note: The elements voiceMail, routes, and blendedAliases have
been added as methods associated with user operations.
Table 1 Deprecated methods
Deprecated methods

Open Provisioning Interface Reference Guide
15
Copyright © Nortel Networks Limited 2006
addUser
(see note)
voiceMail
voiceMailServer
chargeId
vpn
blendedAliases
routes
ipcmProperties
addUsersToDomain
(see note)
voiceMail
voiceMailServer
chargeId
vpn
blendedAliases
routes
ipcmProperties
modifyUser
(see note)
voiceMail
voiceMailServer
chargeId
vpn
blendedAliases
routes
ipcmProperties
Table 2 Deprecated method elements (Sheet 2 of 2)
Affected method Deprecated method element
Note: The elements voiceMail, routes, and blendedAliases have
been added as methods associated with user operations.

NN42020-123 MCS 5100 3.5 Standard 4.0 4.0 January 2006
16
Copyright © Nortel Networks Limited 2006

Open Provisioning Interface Reference Guide
Copyright © Nortel Networks Limited 2006
Building OPI clients
Topics in this chapter
•Building OPI Stubs Clients
•Writing a client to perform some specific OPI operations
•Two examples
•A special note on .NET authentication headers
Building OPI Stubs Clients
The following sections describes the requirements and steps tasks
performed to generate Open Provisioning Interface (OPI) client stubs.
The process is based on using the Axis toolkit.
•Requirements
•Downloading the AXIS toolkit
•Setting the Classpath
•Downloading the WSDL file
•Compiling the stubs
Requirements
The following are required for performing the steps in this examples
• working knowledge of Java application development
• comfortable with using DOS commands
• JDK (Java Developer Kit) 1.3 or higher
• Java executable available in the system path
• Axis toolkit version 1.1 final
Downloading the AXIS toolkit
The steps in this chapter use the AXIS toolkit 1.1 final version. The
AXIS toolkit is a free download from the Apache Web Site.

NN42020-123 MCS 5100 3.5 Standard 4.0 4.0 January 2006
18
Copyright © Nortel Networks Limited 2006
Procedure 1 Downloading the AXIS toolkit
On the PC
1In your web browser, navigate to the Axis toolkit page on the
Apache web site.
ws.apache.org/axis
The 1.1 final version is recommended.
2Download the 1.1 final version file, axis-1_1.zip, to your PC.
3Unzip the files to a drive on the PC. In this example, we use Axis
files extracted to folder D:\axis-1_1.
Setting the Classpath
The classpath needs to be set for specific jar files that are part of the
Axis toolkit.
Procedure 2 Setting the Classpath
On the PC
1Open a command prompt in the DOS window
2Set the classpath for all the jar files found in the directory
D:\axis-1_1\webapps\axis\WEB-INF\lib.
set CLASSPATH= D:\axis-1_1\webapps\axis\WEB-INF
\lib\axis.jar;D:\axis-1_1\webapps\axis\WEB-INF
\lib\axis-ant.jar;D:\axis-1_1\webapps\axis\WEB
-INF\lib\commons-discovery.jar;D:\axis-1_1\web
apps\axis\WEB-INF\lib\commons-logging.jar;D:\a
xis-1_1\webapps\axis\WEB-INF\lib\jaxrpc.jar;D:
\axis-1_1\webapps\axis\WEB-INF\lib\log4j-1.2.8
.jar;D:\axis-1_1\webapps\axis\WEB-INF\lib\saaj
.jar;D:\axis-1_1\webapps\axis\WEB-INF\lib\wsdl
4j.jar
3Create a folder for the generated client stubs. In this example, we
use the folder D:\opiclient.

Open Provisioning Interface Reference Guide
19
Copyright © Nortel Networks Limited 2006
Downloading the WSDL file
Download the Web Server Description Language (WSDL) from the
Provisioning Server.
Procedure 3 Downloadin the WSDL file
On the PC
1In your web browser, navigate to the URL:
http://<web-server-host-ip>/prov/services/OPI?wsdl
where
<web-server-host-ip> is the IP address of the Provisioning
Server. This is same IP address used by the Provisioning Client.
2Download the WSDL file to the folder created for the OPI clients.
In our example, the file is named opi.wsdl and it is
downloaded to the folder D:\opiclient.
Compiling the stubs
Procedure 4 Compiling the stubs
On the PC
1Open a command prompt and navigate to the directory to the
one containing the downloaded WSDL file (D:\opiclient).
2Run the WSDL2JAVA tool on the WSDL file. For Example
java org.apache.axis.wsdl.WSDL2Java -O -1 -d
Session -Nurn:OPI com.client.opi.service
opi.wsdl

NN42020-123 MCS 5100 3.5 Standard 4.0 4.0 January 2006
20
Copyright © Nortel Networks Limited 2006
This creates the client stubs under
d:\opiclient\com\client\opi\service
and the client data objects (beans) under
d:\opiclient\com\nortelnetworks\ims\opi.
The namespace mapping from OPI to com.client.opi.service can
be changed to another mapping of choice.
Note: The OPISoapBindingStub.java that is generated
under com\client\opi\service will have a large static
block that will not compile. This file must be edited by hand to
split the large static block into two to three smaller ones so that
it compiles. This is a known issue due to the fact that the code
is auto generated.
3Compile the files that were generated in the above step using
either command line ’javac’ or an IDE like netbeans or eclipse,
and put them into a separate folder.
In the example javac is used (shown in the following
screenshot). A folder called classes was created in this
example, and the generated class files put into it.