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.
. Contents New in this release Other changes 5 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
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 Downloading the Bulk Provisioning Tool to a workstation Launching the BPT on a workstation 36 35 36 Creating Open Provisioning Interface clients 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 operat
. 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.
New 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 .
. 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).
Introduction Nortel AS 5300 Nortel Application Server 5300 Application Programming Interfaces Reference NN42040-110 01.01 Standard 11 June 2008 Copyright © 2008 Nortel Networks .
. 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).
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.
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.
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 .
. Using the Bulk Provisioning Tool This chapter contains all of the information you need to use the AS 5300 Bulk Provisioning Tool (BPT).
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 AS 5300 Nortel Application Server 5300 Application Programming Interfaces Reference NN42040-110 01.
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.
Using the Bulk Provisioning Tool Table 3 BPT main menu commands (cont’d.) Command Description execute Execute all the methods contained in the specified file. Each line in the file must be a method in the valid format. execute into 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 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)). 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.
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.
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], ..
Using the Bulk Provisioning Tool Comma separated strings Provisioning method syntax can include a string of comma-separated variables.
BPT conventions and examples 21 Unknown error messages If an unknown error occurs when invoking a method, the BPT prompts the administrator to check the logs for more information. The logs are not accessible to the BPT user. If you see this error message and cannot proceed with the BPT provisioning task, contact your next level of support. Create and manage provisioning roles using the BPT This section describes how to create and manage a provisioning role using the Bulk Provisioning Tool (BPT).
Using the Bulk Provisioning Tool Add the new provisioning role To add the new role, enter the following in the BPT command line: addRole using file D:\prov\addexample.txt The BPT indicates whether the provisioning method succeeded or failed, as shown in the following figure.
BPT conventions and examples 23 Figure 4 getRole method invoked in the BPT The BPT returns the following information: [AddExample,BPT add example,[[Domain Management,true,true ,false],[Device Management,true,false,false],[Admin,tr ue,true,true]]] The information is identical to the file contents used to create the new role (see "Define the new provisioning role" (page 21)).
Using the Bulk Provisioning Tool Figure 5 removeRole method invoked on the BPT BPT Help option BPT provisioning methods are identical to OPI provisioning methods. The BPT Help option enables you to view the required syntax for a BPT (OPI) provisioning method and its associated text file.
BPT limitations 25 Figure 6 Invoking a help command in the BPT Attention: The BPT Help function only contains the syntax of the BPT (OPI) provisioning methods and associated file contents. For more information about the parameters available for each OPI provisioning method, see AS 5300 Provisioning Client Help, NN42040-502. BPT limitations The following sections describe certain limitations that you must be aware of when using the Bulk Provisioning Tool.
Using the Bulk Provisioning Tool In most cases, variables and properties used by the BPT provisioning methods map to fields in the Provisioning Client. For Provisioning Client field descriptions, see AS 5300 Provisioning Client Help, NN42040-502. For example, the addRole provisioning method maps to the Add a New Role window of the Provisioning Client (Admins > Add Roles). Batch processing A maximum of 1000 entries are processed together at a time. All bulk processing is on an all-or-none basis.
BPT limitations Provisioning data visibility Provisioning data added using the BPT is immediately available to other provisioning clients connected to the same instance of the Provisioning Manager. However, it can take up to five minutes before the same data is visible to clients connected to a second instance of a Provisioning Manager running in the system. Nortel AS 5300 Nortel Application Server 5300 Application Programming Interfaces Reference NN42040-110 01.
Using the Bulk Provisioning Tool Nortel AS 5300 Nortel Application Server 5300 Application Programming Interfaces Reference NN42040-110 01.01 Standard 11 June 2008 Copyright © 2008 Nortel Networks .
. Using the Open Provisioning Interface This chapter contains all of the information you need to use the Open Provisioning Interface. Navigation • • "Security, authentication, and authorization" (page 29) "Third-party client development" (page 33) Security, authentication, and authorization The following sections describe the security, authentication, and authorization considerations for using the Open Provisioning Interface.
Using the Open Provisioning Interface Authentication The Provisioning Server authenticates each request to ensure that the request is received from a valid client application. The client application needs to provide a user identity (user name) and authentication information (password) in the HTTP/SOAP request. The supported authentication mechanisms are HTTP Basic Authentication – Onboard Authentication and WS-Security UsernameToken.
Security, authentication, and authorization 31 Figure 8 Sample WS-Security header/SOAP message A special note for .NET authentication headers The authentication headers for AXIS toolkit-generated stubs are set on the client stub as described in the preceding example. In that scenario, the client stub is cast down to a org.apache.axis.client.Stub object. In the case of a .NET client, this must be done differently.
Using the Open Provisioning Interface Figure 9 Setting authentication headers Authorization After the OPI request is authenticated, you must be authorized before performing the action. The authorization includes both domain-level authorization and provisioning-level authorization. If either authorization fails, a SOAP fault is sent back, indicating the reason for failure, and the action is not performed.
Third-party client development 33 across these categories. Upon creation, the administrator is assigned to a particular role. This enables the service provider to create various administrator roles to suit 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 can be created which gives the ability to read domain information, and to read, modify, and delete user information.
Using the Open Provisioning Interface Figure 10 Interactions of the stub You generate stubs using a supported toolset. Currently, only the 1.3 Final version of the Apache Axis (Apache Extensible Interaction System ws.apache.org/axis) toolsets are 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 been completed. For instructions to download the Axis toolset, see "Downloading the Axis toolkit" (page 41).
. Starting the Bulk Provisioning Tool This chapter contains the procedures necessary to start the Bulk Provisioning Tool (BPT) on a remote workstation. This facilitates the use of files and scripts without affecting the performance of the server hosting the Provisioning Manager. Starting the Bulk Provisioning Tool Nortel AS 5300 Nortel Application Server 5300 Application Programming Interfaces Reference NN42040-110 01.01 Standard 11 June 2008 Copyright © 2008 Nortel Networks .
Starting the Bulk Provisioning Tool Navigation • • "Downloading the Bulk Provisioning Tool to a workstation" (page 36) "Launching the BPT on a workstation" (page 36) Downloading the Bulk Provisioning Tool to a workstation Use this procedure to download the BPT to a workstation. Procedure Steps Step Action 1 Log on to the Provisioning Client. 2 Open the System folder. 3 Click Tools. The BPT download window appears.
Launching the BPT on a workstation The BPT application launches. 2 Enter your administrator username and password. The Bulk Provisioning Tool main menu appears. See Figure 1 "BPT main menu" (page 14) . --End-- Nortel AS 5300 Nortel Application Server 5300 Application Programming Interfaces Reference NN42040-110 01.01 Standard 11 June 2008 Copyright © 2008 Nortel Networks .
Starting the Bulk Provisioning Tool Nortel AS 5300 Nortel Application Server 5300 Application Programming Interfaces Reference NN42040-110 01.01 Standard 11 June 2008 Copyright © 2008 Nortel Networks .
. Creating Open Provisioning Interface clients This chapter describes the steps necessary to create Open Provisioning Interface (OPI) clients and provides an example of how to write a client to perform specific OPI provisioning methods. Prerequisites for creating OPI clients You must: • • • • • have a working knowledge of Java application development. be comfortable using DOS commands. have the Java Developer Kit (JDK) 1.6. have the Java executable available in the system path.
Creating Open Provisioning Interface clients Figure 12 Task flow for creating OPI clients Navigation • • • • • • "Downloading the Axis toolkit" (page 41) "Retrieving the error codes" (page 41) "Configuring the class path" (page 41) "Downloading the WSDL file" (page 42) "Compiling the client stubs" (page 42) "Writing a client to perform some specific OPI operations" (page 43) Nortel AS 5300 Nortel Application Server 5300 Application Programming Interfaces Reference NN42040-110 01.
Configuring the class path 41 Downloading the Axis toolkit Use this procedure to download the AXIS toolkit version 1.3 Final. The Axis 1.3 Final toolkit is a free download from the Apache Web site. Procedure Steps Step Action 1 Navigate to the AXIS toolkit page on the Apache web site. http://ws.apache.org/axis Nortel recommends version 1.4 Final (Latest). 2 Download the 1.3 Final version zip file (axis-bin-1_4.zip) to a drive on your PC. 3 Unzip the axis-bin-1_4.
Creating Open Provisioning Interface clients set CLASSPATH= D:\axis-1_4\webapps\axis\WEB-INF\ lib\axis.jar;D:\axis-1_4\webapps\axis\WEB-INF\l ib\axis-ant.jar;D:\axis-1_4\webapps\axis\WEB-IN F\lib\commons-discovery-0.2.jar;D:\axis-1_4\web apps\axis\WEB-INF\lib\commons-logging-1.0.4.jar ;D:\axis-1_4\webapps\axis\WEB-INF\lib\jaxrpc.ja r;D:\axis-1_4\webapps\axis\WEB-INF\lib\log4j-1. 2.8.jar;D:\axis-1_4\webapps\axis\WEB-INF\lib\sa aj.jar;D:\axis-1_4\webapps\axis\WEB-INF\lib\wsd l4j-1.5.1.
Writing a client to perform some specific OPI operations 43 This creates the client stubs under D:\opiclient\com\clien t\opi\service The stubs contain all the provisioning methods that are exposed by the OPI web service, and the same methods that can be seen in the WSDL. The arguments provided to these provisioning methods are generated in the directory D:\opiclient\com\nortelnet works\ims\opi.
Creating Open Provisioning Interface clients 2 Instantiate a URL object that will point to the Provisioning Server location and the OPI web service running on it. 3 Invoke the getOPI call on the OPIServiceLocator instance with the URL. This action will result in an instance of the OPI object, which can be used to make OPI provisioning method calls. 4 Set the authentication information on the OPI object. Perform this action by downcasting the OPI object as a org.apache.axis.client.Stub object.
Writing a client to perform some specific OPI operations 45 The client class can be compiled similarly to the compilation of the OPI Stubs, and executed. The OPI Stub classes and AXIS toolkit jars must be present in the classpath during execution, as demonstrated in the following figure. Nortel AS 5300 Nortel Application Server 5300 Application Programming Interfaces Reference NN42040-110 01.01 Standard 11 June 2008 Copyright © 2008 Nortel Networks .
Creating Open Provisioning Interface clients Figure 13 Compiling the client class Nortel AS 5300 Nortel Application Server 5300 Application Programming Interfaces Reference NN42040-110 01.01 Standard 11 June 2008 Copyright © 2008 Nortel Networks .
. Accessing the OPI Java docs This procedure describes how to access the Open Provisioning Interface (OPI) Java docs. These Java docs represent the various categories of OPI web services available. Each OPI web service category contains a description of the OPI web service in general, and descriptions of each associated provisioning operation (OPI provisioning method) and bean objects. WSVersionOPI is a special OPI web service that provides the current Web Services Description Language (WSDL) version.
Accessing the OPI Java docs Figure 14 OPIJavadocs file unzipped 2 Click on the subfolder for the OPI web service category you wish to query or use. For example, if you wish to query or use the AdminAuthe ntication OPI web service, navigate to and click on the AdminAuthentication subfolder in the OPI Java Docs folder. A list of sub-folders and files related to the AdminAuthentica tion OPI web service opens.
Writing a client to perform some specific OPI operations 49 Figure 15 Accessing the javadocs for the AdminAuthentication OPI web service 3 Double-click on the index.html file in the AdminAuthentica tion OPI Web service folder. The javadoc for the AdminAuthentication OPI Web service opens in the browser. You can go through the various links available in the javadoc to get a description of the AdminAuthentication Web service, the associated OPI provisioning methods, and the bean objects.
Accessing the OPI Java docs Nortel AS 5300 Nortel Application Server 5300 Application Programming Interfaces Reference NN42040-110 01.01 Standard 11 June 2008 Copyright © 2008 Nortel Networks .
. Importing a CA Certificate into the BPT Use this procedure to import a Certificate Authority (CA) certificate into the opitruststore. Procedure Steps Step Action 1 Copy the NorlockPKI.cer certificate file to the D:\temp folder. 2 Open a command prompt in the DOS window. 3 Enter the following command (on one line): keytool -import -alias NorlockPKI -file D:\temp\NorlockPKI.
Importing a CA Certificate into the BPT Nortel AS 5300 Nortel Application Server 5300 Application Programming Interfaces Reference NN42040-110 01.01 Standard 11 June 2008 Copyright © 2008 Nortel Networks .
Nortel AS 5300 Nortel Application Server 5300 Application Programming Interfaces Reference Copyright © 2008 Nortel Networks All Rights Reserved. Release: 1.0 Publication: NN42040-110 Document status: Standard Document revision: 01.01 Document release date: 11 June 2008 To provide feedback or to report a problem in this document, go to www.nortel.com/documentfeedback. www.nortel.
