Nortel Networks NN42020-123 User Manual

NN42020-123

Multimedia Communication Portfolio

Multimedia Communication Server

Open Provisioning Interface

MCS 5100 3.5 Standard 4.0 January 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

Latest Software Nortel page for MCS 5100 software located at

Latest Documentation Nortel page for MCS 5100 documentation located at

Takes you directly to the

www130.nortelnetworks.com/cgi-bin/eserv/cs/ main.jsp?cscat=SOFTWARE&resetFilter=1&tranProduct=124 82

www130.nortelnetworks.com/cgi-bin/eserv/cs/ main.jsp?cscat=DOCUMENTATION&resetFilter=1&tranProdu ct=12482

Open Provisioning Interface Reference Guide

NN42020-123 MCS 5100 3.5 Standard 4.0 4.0 January 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 Solutions 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

Open Provisioning Interface Reference Guide

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.

NN42020-123 MCS 5100 3.5 Standard 4.0 4.0 January 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.

Open Provisioning Interface Reference Guide

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

Provisioning Module

Stub

Skeleton

Oracle

Data Store

Database

3rd party application

WSDL file

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

NN42020-123 MCS 5100 3.5 Standard 4.0 4.0 January 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

1 Open a web browser

2 To 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

3 Download 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

Third Party Application

object

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

Open Provisioning Interface Reference Guide

SOAP over HTTP

Provisioning Module

port 80

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 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.

on page 29 for a complete list of

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

NN42020-123 MCS 5100 3.5 Standard 4.0 4.0 January 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.

Open Provisioning Interface Reference Guide

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

NN42020-123 MCS 5100 3.5 Standard 4.0 4.0 January 2006

(domain and devices) that are not pre-existing in the database when the remove method is invoked.

Example

An invocation of "removeUser using (jimbob@nn.com)" 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

Open Provisioning Interface Reference Guide

Table 1 Deprecated methods

Deprecated methods

getAllPooledResources

getAllPooledResourceTypes

getAllRoutingAlgorithms

getIPCMCapacityByDomain

getPooledResource

modifyPooledResource

modifyServiceParm

setServiceParmAsDefault

The following table lists deprecated elements. These correspond to fields in the Provisioning Client, and method parameters in the BPT.

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.

NN42020-123 MCS 5100 3.5 Standard 4.0 4.0 January 2006

Table 2 Deprecated method elements (Sheet 2 of 2)

Affected method Deprecated method element

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

Note: The elements voiceMail, routes, and blendedAliases have been added as methods associated with user operations.

Open Provisioning Interface Reference Guide

NN42020-123 MCS 5100 3.5 Standard 4.0 4.0 January 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.

Open Provisioning Interface Reference Guide

Procedure 1 Downloading the AXIS toolkit

On the PC

1 In 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.

2 Download the 1.1 final version file, axis-1_1.zip, to your PC.

3 Unzip 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

1 Open a command prompt in the DOS window

2 Set 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

3 Create a folder for the generated client stubs. In this example, we

use the folder D:\opiclient.

NN42020-123 MCS 5100 3.5 Standard 4.0 4.0 January 2006

+ 40 hidden pages