web methods broad vision adapter user guide v1

webMethods BroadVision Adapter User Guide VERSION 1.2� � � 1

C H A P T E R

Introduct ion

Welcome!.....................................................................................2

Typographical Conventions .........................................................2

Related Documentation ...............................................................4

Viewing this Document ................................................................4

Printing this Document.................................................................5

C H A P T E R 1 I n t r o d u c t i o n

2 � � � webMethods BroadVision Adapter User Guide VERSION 1.2

Welcome! This guide describes how to configure and use the webMethods BroadVision Adapter. It contains information for administrators who configure and manage a webMethods Integration system and for application developers who want to create services that exchange data with BroadVision systems. In particular, this adapter works with the BroadVision One-To-One Enterprise application platform.

To use this guide effectively, you should:

�� Understand the basic concepts described in the webMethods Administrator’s Guide and the webMethods Developer User’s Guide.

�� Know how to create flow, Java, and/or C/C++ services.

�� Be familiar with the BroadVision One-To-One Enterprise application server.

Typographica l Convent ions This document uses the following typographical conventions:

Convention Example

Procedures are highlighted by a blue box in the left column. Procedures are described as a series of numbered steps.

Procedure Title

1. Select the File command from the Activity menu.

Characters that you must type exactly are shown in a typewriter (courier) font.

Type: setup and then press ENTER.

Variable information that you must type based on your specific situation or environment is shown in italics.

Type: ServerDirectory\setup and then press ENTER.

Keyboard keys are shown in uppercase. Press ENTER; then press TAB.

Keys that you must press simultaneously are joined with the “+” symbol.

Press CTRL+ALT+M.

Directory paths are shown with the “\” directory delimiter unless the subject is UNIX-specific. In these cases, the “/” is used. If you are working in a UNIX environment, substitute a “/” for the “\” shown in the procedures in this book.

ServerDirectory\packages\Default

T y p o g r a p h i c a l C o n v e n t i o n s


Convention Example

Information that you must read before beginning a procedure or that alerts you to negative consequences of certain actions is denoted with this special symbol.

Caution: If the folder is not already open in the Document Browser, open it before you start the following procedure.

Notes that provide related, but non-critical, information are denoted with this special symbol.

Note: When you start the webMethods Developer, you will be asked to log on to a webMethods Integration Server.

Program Code Conventions For programming code and command syntax, this document uses the following typographical conventions:

Convention Example

Keywords and values that you must type exactly as printed are shown in typewriter (courier) font.

%CoSymbol%

Variable values or parameters that you must supply are shown in italics.

%VarName%

Keywords or values that are optional are enclosed in [ ]. Do not type the [ ] symbols in your own code.

%loop LoopVar [null=NullValue]%

C H A P T E R 1 I n t r o d u c t i o n


Related Documentat ion The following documents are useful companions to this guide. Some documents are in PDF format and others are in HTML.

Refer to this book… For…

webMethods Administrator’s Guide

Information about using the webMethods Administrator to configure, monitor, and control the webMethods Integration Server. This book is for server administrators. You will find this book at: ServerDirectory\doc\ISAdministratorsGuide.pdf

webMethods Developer User’s Guide

Information about creating and testing services and client applications. This book for application developers. You will find this book at: ServerDirectory\doc\ISIntegratorsGuide.pdf

webMethods Integration Server Clustering Guide

Information about installing and configuring the Integration Server Clustering feature. It also contains information for administrators who configure and manage a webMethods Integration Server system and for application developers who want to create services that interact directly with the Integration Server Cluster Store.

You will find this book at:

ServerDirectory\doc\ISClusteringGuide.pdf

webMethods Integration Server Java API Reference

Descriptions of the Java classes you use to create services. This reference is for developers who build services using Java. You will find this book at: ServerDirectory\doc\API\Java\index.html

webMethods Developer Online Reference

Information about the controls in the webMethods Developer application windows and step-by-step procedures describing how to perform tasks with the webMethods Developer. You can access the online reference by clicking Help in an application window or dialog box.

Viewing this Document To view this document, which is in PDF format, you must have Acrobat® Reader 4.0 or later installed on your computer. If you have an earlier version of Acrobat Reader, you will receive the following error message when you open this document and Acrobat Reader will not display the images in this document:

R e l a t e d D o c u m e n t a t i o n


Could not find the ColorSpace named ‘Cs8.’

If you do not have Acrobat Reader, or you do not have the correct version, you can download a copy from www.adobe.com/products/acrobat/readermain.html.

Printing this Document To produce a hard copy of this guide, print this document from Acrobat Reader. You will find the document’s title page and table of contents at the end of the printed copy. To create a traditional, paper-based manual, simply move these pages to the front of the document after it is printed.


C H A P T E R

Product Overview

What is the BroadVision Adapter?...............................................8

C H A P T E R 2 P r o d u c t O v e r v i e w


What is the BroadVis ion Adapter? The webMethods BroadVision Adapter provides an easy way to create services that interact with a BroadVision One-to-One server. The webMethods BroadVision package includes an inbound adapter and an outbound adapter.

What is the Inbound Adapter? You use the inbound adapter (Integration Server-to-BroadVision) to enable other organizations to access and manipulate data contained in your BroadVision system. There are two ways in which you can enable them to do this:

�� Via calling the existing CORBA servers in your BroadVision system.

�� Via calling a session portal interface, which executes your existing JavaScript pages in your BroadVision Interaction Manager’s JavaScript engine, without going through a web server.

Enabl ing Access to BroadVis ion Data v ia CORBA Servers The inbound adapter provides a user interface that you use to generate flow services that call your existing CORBA interface methods. This user interface provides a list of all CORBA servers that exist in your BroadVision Names Server. From this list, you select the CORBA server interface methods that you want to expose to the adapter—that is, you select the methods that you want to make available to your requestors. Your system administrator controls which CORBA servers you can select, by putting the IDL files of those servers into your Interface Repository (IFR). After you select a CORBA server interface method, you generate it to produce a flow service to represent the method. When requestors execute the flow service from their Integration Servers, this service acts as a dynamic CORBA client. The service connects to the appropriate CORBA server in your BroadVision system and returns the result to the requestor. To display the results, the requestor must create his or her own presentation layer, such as a dynamic server page (dsp) or a JavaScript page (jsp).

The following figure shows the run-time architecture of an inbound adapter that enables access via CORBA servers.

W h a t i s t h e B r o a d V i s i o n A d a p t e r ?


Step Description

1 Company A executes your adapter-generated flow service to request information.

2 The inbound adapter passes the request to the Naming Service.

3 The Naming Service returns a reference to the requested object to the requesting flow service. The flow service executes the methods on the obtained object, which is passed to the appropriate CORBA server through the ORB.

4 – 5 The CORBA server performs operations on data in the back-end systems and receives the result.

6 The CORBA server passes the result back to the flow service.

7 The inbound adapter passes the result (as a Values Object) back to Company A’s Integration Server.

See “Implementing the Inbound Adapter” on page 15 for more information.

3

BroadVision Server

CORBA Servers

Orbix NamingService

IFR

Inbound Adapter

Integration Server

6

2

8

7

Back-end Systems

4 5

1

INTERNET

IntegrationServer

IntegrationServer

Company A

3

BroadVision Server

CORBA ServersCORBA Servers

Orbix NamingService

IFR

Inbound Adapter

Integration Server

6

2

8

7

Back-end Systems

4 54 5

1

INTERNET

INTERNET

IntegrationServer

IntegrationServer

Company A



Enabl ing Access to BroadVis ion Data v ia Session Porta l In terfaces Running a session portal interface provides a way to call JavaScript pages directly from a C++ program running outside the Interaction Manager instead of calling them through the HTTP server. A session portal interface gets a handle to the Interaction Manager and executes your JavaScript pages in the Interaction Manager. By having your requestors run a session portal interface, you can take advantage of the Interaction Manager’s ability to keep track of session information and to cache session data. A session portal interface returns the result to the requestor in an HTML page.

The inbound adapter provides the following components to help you implement a session portal interface:

�� A C++ session portal library (libwmSessionPortal.so for Solaris, libwmSessionPortal.sl for HP-UX, or wmSessionPortal.dll for Windows NT or 2000) that is wrapped in Java code using JNI.

�� A predefined flow service—ExecuteJSP—that executes your existing BroadVision JavaScript pages in the Interaction Manager. Your requestors will invoke this service remotely, by running their own flow services on their Integration Servers.

Note: Do not confuse BroadVision JavaScript page files (.jsp files) with Java Server Pages, which have the same file extension.

To implement a session portal interface, you do the following:

�� Modify your library path to include the appropriate session portal interface library— libwmSessionPortal.so (for Solaris) or libwmSessionPortal.sl (for HP-UX), or wmSessionPortal.dll (or Windows NT or 2000). See the webMethods BroadVision Adapter Installation Guide for the procedure to do this.

�� Provide your requestors with the parameters for invoking the ExecuteJSP service. To invoke ExecuteJSP, a requestor must create and run a flow service that specifies your BroadVision application name, the appropriate JavaScript file to invoke, and an input string specifying the input accepted by the JavaScripts.

The following figure shows the run-time architecture of an inbound adapter that enables access via a session portal interface.



Step Description

1 To request the execution of a JavaScript, Company A executes a service to invoke the adapter’s predefined service ExecuteJSP.

2 The ExecuteJSP service passes the request to the webMethods session portal library, which passes the request to the Interaction Manager.

3 – 6 The Interaction Manager uses the BV Component to pass the request to the appropriate CORBA server, which accesses the requested data from the back-end systems.

7 – 9 The CORBA server returns the result to the Interaction Manager, which returns the result to the ExecuteJSP service.

10 The ExecuteJSP service returns the result to Company A’s Integration Server.

See “Implementing the Inbound Adapter” on page 15 for more information.

Inbound Adapter

Integration Server

8

CORBA Servers

Orbix/IFR Layer

9 2

1

INTERNET

IntegrationServer

IntegrationServer

Company A

6 3

BroadVision Server

BV Component

JavaScript Engine

Interaction Manager

libwmSessionPortal.so

ExecuteJSP Service

Service toremotely invokeExecute JSP

Back-end Systems

3

47

56

10

Inbound Adapter

Integration Server

8

CORBA ServersCORBA Servers

Orbix/IFR Layer

9 2

1

INTERNET

INTERNET

IntegrationServer

IntegrationServer

Company A

IntegrationServer

IntegrationServer

Company A

6 3

BroadVision Server

BV Component

JavaScript Engine

Interaction Manager

BroadVision Server

BV Component

JavaScript Engine

Interaction Manager

libwmSessionPortal.so

ExecuteJSP Service

Service toremotely invokeExecute JSP

Back-end Systems

3

47

56

10



What is the Outbound Adapter? You use the outbound adapter (BroadVision-to-Integration Server) to request data (via flow services) from the external systems to which your Integration Server provides access.

The outbound adapter provides the following components to help you implement this functionality:

�� The webMethods Server Library Component (libwmservercomponents.so for Solaris, libwmservercomponents.sl for HP-UX, or libwmservercomponents.dll for Windows 2000).

�� The webMethods CORBA Server (wmCorba_srv.jar).

To implement the outbound adapter, you create a JavaScript front end in your BroadVision server. In this front end, you include methods and attributes provided by the webMethods Server Library Component to connect your BroadVision server to your Integration Server, and to invoke flow services in the Integration Server.

When you submit the JavaScripts to your web server, the web server transmits the JavaScripts to the JavaScript engine embedded in your BroadVision Interaction Manager. The Interaction Manager uses the webMethods Server Library Component to call the webMethods CORBA Server, which establishes a connection to the Integration Server and executes the services on the Integration Server.

Finally, the webMethods CORBA Server forwards the results of the flow service executions back to the webMethods Server Library Component, which marshals the results and presents them to the JavaScript engine.

The following figure illustrates the run-time architecture of the outbound adapter.



Step Description

1 The front end JavaScript sends a request (including flow service invocations) to the Interaction Manager, which forwards the request to the JavaScript engine.

2 – 4 The webMethods Server Library Component calls the webMethods CORBA Server, which establishes a connection to the Integration Server and executes the flow service invocations included in the request.

5 The Integration Server sends the request to Company A’s Integration Server.

6 Company A’s Integration Server processes the request and passes the result back to your Integration Server.

7 – 9 Your Integration Server passes the result back to the webMethods Server Library Component, which marshals the results and presents them to the JavaScript engine.

10 The JavaScript engine passes the results back to the front end.

See “Implementing the Outbound Adapter” on page 25 for more information.

5

4

2

1

INTERNET Integration

ServerIntegration

Server

3

Back-end Systems

BroadVision Server

Orbix/IFR Layer

JavaScript Engine

Interaction Manager

CORBA ServerswmCorba_srv.jar

Company A

IntegrationServer

IntegrationServer

libwmservercomponent.so

9

7

8

10

6

55

44

22

11

INTERNET

INTERNET Integration

ServerIntegration

Server

33

Back-end Systems

BroadVision Server

Orbix/IFR LayerOrbix/IFR Layer

JavaScript Engine

Interaction Manager



Company A

IntegrationServer

IntegrationServer

libwmservercomponent.so

99

77

88

1010

66


C H A P T E R

Implementing the Inbound Adapter

Introduction..................................................................................................16

Specifying Aliases for BroadVision Servers.................................................16

Implementing Inbound Adapters that Expose CORBA Servers ...................18

Testing Inbound Session Portal Interfaces ..................................................22

C H A P T E R 3 I m p l e m e n t i n g t h e I n b o u n d A d a p t e r


In t roduct ion This chapter describes how to implement the inbound adapter.

Before you can use the inbound adapter, you must provide information about your BroadVision server. For each BroadVision server that you will use, you must specify alias settings that identify your BroadVision server to the webMethods Integration Server. For information about this task, see “Specifying Aliases for BroadVision Servers” on page16.

To enable the inbound adapter to access your BroadVision system via your existing CORBA servers, you perform the following tasks:

�� Ensure that your system administrator has enabled your BroadVision Interface Repository (IFR) and has added the IDL files associated with your CORBA servers to the IFR. For information about this task, see “Adding IDL Files to the Interface Repository” on page 18.

�� Select the BroadVision system’s CORBA interface methods that you want to expose to the adapter and generate flow services that represent those methods. For information about this task, see “Generating Flow Services for the Inbound Adapter” on page 19.

Alternatively, if you plan to use the adapter to enable access via session portal interfaces, you should test the session portal interfaces. The inbound adapter provides a user interface that enables you to do this. For information about this task, see “Testing Inbound Session Portal Interfaces” on page 22.

Speci fy ing Al iases for BroadVis ion Servers When you create services that interact with the BroadVision server, you specify aliases that the webMethods Integration Server uses to open a session to a BroadVision Names Server. Aliases are named collections of parameters that you build using the webMethods Administrator. They encompass the specific connection values—the Names Server host name, port number, and so forth—necessary to establish a connection with a particular BroadVision server.

How Does a Service Use the Aliases? At run time, a service locates the named set of server settings assigned to it. webMethods uses the parameters in the named set to open a connection to the BroadVision server. The aliases specify:

�� Which server the service will open a connection to.

�� The way in which the connection will be made.

S p e c i f y i n g A l i a s e s f o r B r o a d V i s i o n S e r v e r s


Defining Aliases The procedure in this section describes how to create aliases. When you define aliases, keep the following points in mind:

�� If webMethods will interact with multiple BroadVision servers, define an alias for each one.

�� A single alias can be referenced by more than one service. If several services access the same BroadVision server with the same connection attributes, they should all reference the same alias. This way, if network changes occur (for example, the BroadVision server moves to another host machine or one BroadVision server replaces another), you only need to make changes to one alias.

Caution: You must have administrator privileges on the webMethods Integration Server to execute the following procedure.

To define an alias

1. Start the webMethods Administrator. See the webMethods Administrator’s Guide for the procedure to do this.

2. In the Adapters menu in the navigation area, select BroadVision55. The BroadVision55 child window is displayed.

3. In the BroadVision55 menu in the navigation area, select Alias Settings. The Alias Settings window is displayed.

4. Click the Add Alias Settings button. The Add Alias Settings window is displayed.

5. Complete the following fields. You will need the information supplied by your BroadVision server administrator to complete some of these fields. For more information about these settings, see the following BroadVision configuration files:

/opt/bv1to1/orbix/config/orbixnames3.cfg /opt/bv1to1/orbix/config/common.cfg

In this field… Specify…

Alias Name A unique name for this alias. (This is the name by which services will reference this alias.) Do not use the following characters in the name: % # ? & + < > ’



Description Text that describes the alias. Optional.

IT_NAMES_SERVER_HOST

The machine on which you want to connect to the NamingService when you call resolve_initial_references.

IT_NS_PORT The port number at which the Names Server can be contacted.

IT_NAMES_SERVER The name with which the Names Server is registered in the Implementation repository. This name is usually NS.

IT_LOCAL_DOMAIN The local DNS domain name. Optional.

IT_DAEMON_PORT The port number for the Orbix daemon.

6. Click Save. The webMethods Administrator saves the values to the Repository under the specified alias name. The Alias Settings window is re-displayed, showing the alias name you created. Using this window, you can edit, test, or delete the alias. If you receive an error message when you click Save, verify that the settings you specified are correct.

7. Test the alias by clicking the Test icon next to the alias name.

Implement ing Inbound Adapters that Expose CORBA Servers To implement an inbound adapter that exposes the CORBA servers in your BroadVision system, you perform the following tasks:

�� Add IDL files to your Interface Repository, in order to make your CORBA servers available to the adapter.

�� Select the CORBA server interface methods that you want to expose to the adapter and generate them to produce flow services that represent the methods.

Adding IDL Files to the Interface Repository To make your CORBA servers available to the inbound adapter, you must add the servers’ IDL files to your Interface Repository (IFR). If you fail to do this, you will not be able to select CORBA servers from the adapter’s user interface.

Note: Before you add IDL files to your IFR, ensure that your system administrator has enabled your IFR, as described in the webMethods BroadVision Adapter Installation Guide.

To add the CORBA servers’ IDL files to the Interface Repository

1. Run the following Orbix command:

I m p l e m e n t i n g I n b o u n d A d a p t e r s t h a t E x p o s e C O R B A S e r v e r s


putidl –I IDLincludePath IDLfilePath Where IDLincludePath is the full path of your include / idl directory, and IDLfilePath is the full path of the IDL file to add to the IFR. For example: putidl –I /opt/bv1to1/include/idl/ /opt/bv1to1/include/idl/bv/cmsdb.idl

2. Run the following Orbix command to give the client “invoke and launch” permissions to the IFR: chmodit IFR l+all

Generating Flow Services for the Inbound Adapter The BroadVision Adapter provides a list of all CORBA servers that exist in your BroadVision naming service. From this list, you select the CORBA server interface methods that you want to expose to the adapter.

After your system administrator installs the adapter, he or she should put the IDL files of selected CORBA servers into your Interface Repository (IFR). These CORBA servers will appear in the list as hyperlinks. You may select only from these servers. After you select a CORBA server interface method, you generate it to produce a flow service to represent the method. When requestors execute the flow service from their Integration Servers, this service acts as a dynamic CORBA client. The service connects to the appropriate CORBA server in your BroadVision system and returns the result to the requestor.

The adapter translates the IDL return types of CORBA methods as follows:

IDL Return Type Corresponding Flow Service Return Type

any A record with the following fields: The type of the any (a string value) The value of the any (an object)

array array

sequence array

struct record

union A record with the following fields: The discriminator (a string value) The value of the union (an object)



unsigned long See “How to Deal with the Data Type Unsigned Long” on page 21.

All others string

To generate a flow service for a CORBA interface method

1. In the BroadVision55 menu in the navigation area, select CORBA Servers. The Select Alias window is displayed.

2. Select an alias name from the Select an alias field’s drop-down list and click the Continue button. The BroadVision CORBA Servers from the Names Server window is displayed. This window displays all CORBA servers that exist in your BroadVision naming service.

3. Select a CORBA server name. The list of the server’s interfaces is displayed.

Note: You can select a name only if it appears as a hyperlink. To make other servers available to you, your system administrator must put the IDL files of those servers into your Interface Repository (IFR), as described in “Adding IDL Files to the Interface Repository” on page 18.

4. Select an interface from the list.

A list of the interface’s methods and their return types are displayed.

5. Select a method from the list. The method’s parameters are displayed along with flow information fields.

6. Complete the following flow information fields to specify where to store the flow service that you will generate for the CORBA method:

In this field… Specify…

Encoding The character encoding expected by the BroadVision server. For the Latin-1 alphabet character set (ISO-8859_1), leave this field blank. Other valid values include:

Arabic—ISO8859_6 or Cp1256

Chinese, Traditional—BIG5

Chinese, Simplified—GBK or GB2312

I m p l e m e n t i n g I n b o u n d A d a p t e r s t h a t E x p o s e C O R B A S e r v e r s


Central Europe—ISO8859_2 or Cp1250

Hebrew—ISO8859_8 or Cp1255

Japan—EUC_JP or SJIS

Korea—EUC_KR

Turkish—ISO8859_9 or Cp1254

For information about the adapter’s international support, see International Support in the BroadVision Adapter readme file.

Package The package in which to store the generated flow service.

Folder The folder in which to store the generated flow service.

Service The flow service name. Default: The CORBA method name.

Description Text that describes the flow service. Optional.

7. Click the Register Service button. The adapter generates the flow service and stores it in the location you specified.

How to Deal wi th the Data Type Unsigned Long CORBA defines unsigned long as a 32 bit number which has no sign. That means that it is always positive and the range is from 0 to 2 32 –1. In C or C++, ulong maps into unsigned int, which is defined as 32 bit number with no sign.

But, in Java there are “unsigned” numbers. So, the CORBA ulong maps to int, which is also 32 bit number, but signed. The range of int in Java is –2 31 to 2 31-1. So, if we need to pass an unsigned 32 bit number to a CORBA server which accepts ulong, we need to convert the unsigned number into an integer which would have the same bits, but it represents a different number as an integer. A little more than half of them are negative. When we receive a ulong from a CORBA server, it will be in the integer representation, which could be negative also. So, in this case also we need to convert the integer into a long, which is the same sequence of 32 bits, but could be an entirely different number in the unsigned long world.

The general concept used here is, using the signed bit of an integer as the 32nd bit, so that the negative integers would represent numbers higher than Integer.MAX_VALUE.

So, we have provided the following two utility routines, which perform this kind of conversion:

�� wm.broadvision55.corba.UlongToInteger Use this service to insert a ulong to a CORBA server. This service takes a positive long number (there can be no unsigned in Java) and gets the integer representation that could be passed to a CORBA server.



Example 1: Let’s assume you want to pass the number 3167989637, which is a 32 bit number so it can be passed as an unsigned long. But this number exceeds the range of an integer. So, we need to get the integer value of this 32 bit number, which would be –1126977659, so it can be passed to a CORBA server that accepts a ulong. Example 2: Let’s say you want to pass the number 4294967295, which is 32 bit (actually its bit representation would be 32 1s), but not an integer. Using the utility service, it would get the integer –1 which is also 32 1s.

�� wm.broadvision55.corba.IntegerToUlong Use this service to get a ulong from a CORBA server. When a CORBA server returns a ulong to a Java client, it appears as an integer, which could be negative. So, we need to convert it into an unsigned number to perform further operations. Long can hold an unsigned value of an integer. This service takes an integer and returns the unsigned value represented as a long. Example: Assume you got the integer –2 from a CORBA server as an ulong. -2 is signed, but is 32 bit. So, we need to get the unsigned representation of this number. Using the utility service, we get the value 4294967294, which is also 32 bit. The end user can use this value and perform any operations on it.

Test ing Inbound Sess ion Por ta l In ter faces Instead of enabling access to BroadVision data via its CORBA servers, you can enable access via a session portal interface. Recall that running a session portal interface executes your existing JavaScript pages in your BroadVision Interaction Manager’s JavaScript engine, without going through a web server.

The inbound adapter provides a user interface that lets you test session portal interfaces. To use this test facility, you provide the parameters of the JavaScripts that you want to test, and execute the predefined service ExecuteJSP. The inbound adapter returns a message indicating the status of the test.

After you test a session portal interface successfully, you should provide your requestors with the parameters for invoking the ExecuteJSP service.

To support session portal interfaces, the adapter provides one of the following libraries in your Integration Server’s lib directory. When you installed the inbound adapter, the installation program automatically added the appropriate library in your library path. You should ensure that the appropriate environment variable points to the appropriate library, as follows:

Platform Library Environment Variable

T e s t i n g I n b o u n d S e s s i o n P o r t a l I n t e r f a c e s


Solaris libwmSessionPortal.so LD_LIBRARY_PATH

HP-UX libwmSessionPortal.sl SHLIB_PATH

Windows wmSessionPortal.dll PATH

To test a session portal

1. In the BroadVision55 menu in the navigation area, select Session Portal. The Execute JavaScript Page window is displayed.

2. Complete the following fields to provide the parameters for the session portal interface.

Field Description

BroadVision Application Name

The name of your BroadVision application.

JavaScript File The name of the JavaScript file, starting with the directory relative to the script root defined in your BroadVision installation. This name should be a .jsp file found in your application’s script root directory.

Input String The values to input to your JavaScripts.

Size of the Output Specify a size of the result, if you expect to receive a result. Default: 0.

3. Click the Execute JSP button. The ExecuteJSP service executes your JavaScript page in the Interaction Manager and returns a status message.


C H A P T E R

Implementing the Outbound Adapter

Introduction....................................................................................... 26

What is the webMethods Server Library Component? ..................... 26

The wmServer.jsi File ....................................................................... 28

The webMethods CORBA Server IDL File........................................ 29

C H A P T E R 4 I m p l e m e n t i n g t h e O u t b o u n d A d a p t e r


In t roduct ion This chapter describes how to implement the outbound adapter to request data (via flow services) from the external systems to which your Integration Server provides access.

To do this, you create a JavaScript front end in your BroadVision server to connect your BroadVision server to your Integration Server, and to invoke flow services in the Integration Server. As mentioned in “What is the Outbound Adapter?” on page 12, the adapter’s webMethods Server Library Component provides the methods and attributes that you use in your front end to do this. The webMethods CORBA Server automatically manages the connection between your BroadVision system and your Integration Server.

What is the webMethods Server L ibrary Component? The adapter installs the library component (libwmservercomponents.so for Solaris, libwmservercomponents.sl for HP-UX, or libwmservercomponents.dll for Windows 2000) in your BroadVision Interaction Manager. It contains methods and attributes that you use in your front end to connect your BroadVision server to your Integration Server, and to execute services in the Integration Server. The component consists of a JavaScript layer, a Reference layer, and an Implementation layer, as shown in the following figure.

Back-end Systems

IntegrationServer

IntegrationServer

CORBA Servers

wmCorba_srv.jar

JavaScript Layer

Reference Layer

Implementation Layer

Back-end Systems

IntegrationServer

IntegrationServer

CORBA Servers

wmCorba_srv.jar

CORBA Servers

wmCorba_srv.jar

JavaScript Layer

Reference Layer

Implementation Layer

W h a t i s t h e w e b M e t h o d s S e r v e r L i b r a r y C o m p o n e n t ?


�� The JavaScript layer This layer exposes a JavaScript Interface file (which is equivalent to a CORBA IDL file) to the BroadVision architecture. This file is named wmServer.jsi. You should use the following methods and attributes defined in this .jsi file to write the JavaScript files for your outbound adapter’s front end:

Class Method Attribute

BVI_WMServerManager connect_m createSvr invokeService disconnect_m

BVI_WMValues BVI_StringList key BVI_ValueList value

BVI_WMStringTable long append(BVI_StringList stringList) BVI_StringList getRow(long index)

Read only attributes: long sizex long sizey

BVI_WMValuesList BVI-WMValues get(long index) long append(BVI_WMValues value)

long cursor

To view the wmServer.jsi file, see “The wmServer.jsi File” on page 28.

�� The Reference layer This layer, written in C++, is transparent to the developer. Essentially, it performs memory management and passes the information in your JavaScripts to the underlying Implementation layer.

�� The Implementation layer This layer, also written in C++, marshals the data it receives from the Reference layer and invokes the corresponding method on the webMethods CORBA server (wmCorba_srv.jar), which establishes a connection to the Integration Server and executes the services on the Integration Server. To view the webMethods CORBA server’s associated IDL file, see “The webMethods CORBA Server IDL File” on page 29.

C H A P T E R 4 I m p l e m e n t i n g t h e O u t b o u n d A d a p t e r


The wmServer . js i F i le This file is located in /opt/bv1to1_var/script_root/adapter/scripts. implementation { include "wmSvr_i.hh" } interface BVI_WMStringTable { implementation { implementation_type = BVC_WMStringTable; } creator(); long append(BVI_StringList stringList); BVI_StringList getRow(long index); readonly attribute long sizex; readonly attribute long sizey; } interface BVI_WMValues { implementation { implementation_type = BVC_WMValues; } creator(); attribute BVI_StringList key; attribute BVI_ValueList value; } interface BVI_WMValuesList { implementation { implementation_type = BVC_WMValuesList; } readonly attribute long length; creator(); creator( long expectedLength ); attribute long cursor; BVI_WMValues get( long index ); long append( BVI_WMValues value ); } interface BVI_WMServerManager { implementation { implementation_type = BVC_WMServerManager; } creator(); long initialize(); long createSvr(string server, long port, string user, string passwd);

T h e w e b M e t h o d s C O R B A S e r v e r I D L F i l e


long connect_m(string server, long port, string user); BVI_WMValues invokeService(string server, long port,string user,string ifcName, string svcName, BVI_WMValues inVal); long disconnect_m(string server, long port, string user); }

The webMethods CORBA Server IDL F i le This file is the IDL file associated with the wmCorba_srv.jar file. This IDL file is located in /opt/bv1to1_var/script_root/adapter/scripts. #ifndef _WMSVR_IDL #define _WMSVR_IDL typedef string stringInf; typedef sequence<string> stringSeq; typedef sequence<stringSeq> stringTable; typedef sequence<any> anySequence; typedef struct myValues { sequence<string> key; anySequence value; } xx; typedef sequence<myValues> myValuesSeq; typedef struct myServer { stringInf server; long port; stringInf user; stringInf passwd; } yy; interface BV_WMServerMgr { exception cannotConnect {string msg;}; exception cannotInvoke{ string msg;}; exception cannotDisconnect{ string msg;}; long createSvr(in string svr, in long port, in string user, in string pwd, out myServer svrInfo); long connect_m(in myServer svr) raises (cannotConnect); long invokeService(in myServer svr,in string ifcName, in string svcName, in myValues inValues, out myValues outValues) raises (cannotInvoke); long disconnect_m(in string svrName, in long port, in string user) raises (cannotDisconnect); }; #endif


C H A P T E R

Administrat ion

Administrative Tasks..................................................................32

Configuring How the BroadVision Adapter Maintains its Log.....33

Viewing the Contents of the Log File .........................................35

A P P E N D I X E A d m i n i s t r a t i o n


Admin ist ra t ive Tasks This chapter describes procedures you use to configure and monitor the BroadVision Adapter.

To use the procedures in this section, you must have administrator privileges on the webMethods Integration Server.

Starting the BroadVision Adapter The BroadVision Adapter loads automatically when you start the webMethods Integration Server.

To verify that the BroadVision Adapter is available for use, use the webMethods Administrator to display the Packages screen and verify that the BroadVision55 package is loaded and enabled. See the webMethods Administrator’s Guide for procedures for loading and enabling packages.

Stopping the BroadVision Adapter You can shut off access to the BroadVision Adapter by shutting down the webMethods Integration Server or by disabling the BroadVision55 package. See the webMethods Administrator’s Guide for procedures.

Defining a Connection to a BroadVision Server For each BroadVision server that you will use, you must define an alias. Aliases are used to establish a connection with BroadVision’s Orbix daemon server. You must create at least one alias for each BroadVision server that you will use.

For more information about aliases, including procedures for creating them, see “Specifying Aliases for BroadVision Servers” on page 16.

Viewing/Editing Aliases Use the following procedure to view or edit aliases that have been defined on your webMethods Integration Server.

Caution: Make sure your BroadVision server is available before you start the following procedure. As part of this procedure, the BroadVision Adapter connects to the BroadVision server to verify that the revised parameters are valid. If a connection cannot be made, the BroadVision Adapter will not save your changes.

To view or edit the connection settings for a BroadVision server


C o n f i g u r i n g H o w t h e B r o a d V i s i o n A d a p t e r M a i n t a i n s i t s L o g



3. In the BroadVision55 menu in the navigation area, select Alias Settings.

4. Click the name of the alias you want to view or edit.

5. If you want to edit these settings, click Edit.

6. On the Edit Alias Settings page, make the changes you need and then click Save. If you receive an error message when you click Save, verify that all settings on the Edit Alias Settings page are correct.

Testing Aliases Use the following procedure to test a set of aliases that reside on the webMethods server.

To test alias settings



3. In the BroadVision55 menu in the navigation area, select Alias Settings.

4. Locate the name of the server settings you want to test in the Test

column and click to establish a connection.

Conf igur ing How the BroadVis ion Adapter Main ta ins i ts Log The BroadVision Adapter can maintain a log of events that occur in the system. You configure whether you want the BroadVision Adapter to maintain a log. If you have the BroadVision Adapter maintain a log, you configure where you want the log maintained—on the console or in a file. In addition, you configure the types of messages (or the level of detail) you want the BroadVision Adapter to record in the log.

Caution: When using a clustered environment, the administrator should be aware that each host in the cluster maintains its own log file of the activity on that host. If a request is made to a particular host and then is redirected to a different host because of load balancing or failover, that request will only be logged by the host that eventually accepts the request and not the host to which the request was originally directed.



To configure how the BroadVision Adapter maintains its log, perform the following procedure.

To configure how the BroadVision Adapter maintains its log



3. In the BroadVision55 menu in the navigation area, select Logging.

4. Select one of the following from the drop-down list in the Output To field.

Select… To…

Off Turn logging off. The BroadVision Adapter does not log any messages.

If you make this selection, skip the following steps and click the Submit Changes button.

Console Turn logging on. The BroadVision Adapter displays the log messages on the webMethods Integration Server’s console.

File Turn logging on. The BroadVision Adapter records the log messages to the file: ServerDirectory\packages\BroadVision55\log\logfile.txt

All Turn logging on. The BroadVision Adapter displays the log messages on the webMethods Integration Server’s console and records the log messages to the file: ServerDirectory\packages\BroadVision55\log\logfile.txt

5. Make a selection from the drop-down list in the Logging Level field to configure the type of messages that you want the BroadVision Adapter to record in its log. Be aware that when you select a level, the BroadVision Adapter records messages associated with the level you select and all previous levels. For example, if you select to record critical-level messages, the BroadVision Adapter records critical-, alert-, and emergency-level messages.

Logging level Description of level

Emergency The BroadVision Adapter issues emergency-level messages for unrecoverable catastrophic failures that prevent the adapter from continuing to run.

Alert The BroadVision Adapter issues alert-level messages for errors that require Administrator actions, but do not prevent the adapter from running.

V i e w i n g t h e C o n t e n t s o f t h e L o g F i l e


Logging level Description of level

Critical The BroadVision Adapter issues critical-level messages for unexpected user-level errors that might not be recoverable.

Error The BroadVision Adapter issues error-level messages for unexpected user-level errors that are recoverable, for example, if a connection is dropped by the BroadVision Adapter.

Warn The BroadVision Adapter issues warn-level messages for conditions that do not prevent the action from continuing, but might cause some unpredictable behavior.

Notice Notice-level messages are informational messages, for example, recording events such as startup and shutdown. This is the tersest level that includes informational-level messages.

Info Info-level messages are additional informational messages. This level might be useful for an end-user that is developing applications that use the adapter. Typically, logging should not be set at this level in a production environment.

Debug Debug-level messages are for debugging purposes. This level might be useful to provide information for technical support. The messages at this level allow you to follow the flow of execution. The messages include class name and method name where the message occurred.

6. Click the Submit Changes button.

Viewing the Contents o f the Log F i le If you configured the BroadVision Adapter to maintain a log, you can view the contents of the log file by taking one of the following actions:

�� View the webMethods Integration Server’s console if you configured the BroadVision Adapter to display the log on the console.

�� View the contents of the following file if you configured the BroadVision Adapter to record the log messages in a file. ServerDirectory\packages\BroadVision55\log\logfile.txt

�� Perform the following procedure to view the log using the BroadVision Adapter’s Logging Console screen.

Caution: If your log is large, view it on the server’s console or view the contents of the file instead of using the BroadVision Adapter’s Logging Console screen. Increasingly large files take a long time to display on the Logging Console screen.



To view the BroadVision Adapter’s log



3. In the BroadVision55 menu in the navigation area, select Logging. The BroadVision Adapter displays its log in the Contents of log file section of the screen.

I N D E X


I N D E X

A administrative tasks

configuring how BroadVision Adapter maintains its log 33

defining a connection to BroadVision server 32 editing a connection to BroadVision server 32 shutting down the BroadVision Adapter 32 starting the BroadVision Adapter 32 testing alias settings 33 viewing BroadVision Adapter log 35

alert-level messages 34 Alias Name parameter for alias settings 17 alias settings

alias name 17 defining 17, 32 displaying 32 editing 32 IT_DAEMON PORT 18 IT_LOCAL_DOMAIN 18 IT_NAMES_SERVER 18 IT_NAMES_SERVER_HOST 18 IT_NS_PORT 18 testing 33

aliases defining 17, 32 defining, overview of 16 displaying 32 editing 32 testing 33 use by multiple services 17

audit information for BroadVision Adapter 33, 35

B BroadVision server

defining connection to 17, 32 defining connection to, overview of 16 using more than one 17

C character encoding 20 clustered environment

configuring logging in 33 command syntax

conventions used 3 connections to BroadVision servers

defining 17, 32 console, recording log to 34 conventions

program codes 3 used in this document 2

CORBA server methods generating to produce flow services 19 selecting to expose to adapter 19

CORBA servers accessing via inbound adapter 8, 16 implementing access via inbound adapter 18 webMethods CORBA Server 12, 29

critical-level messages 35

D debug-level messages 35 documentation

conventions used in 2 printing 5 related manuals 4 using effectively 2 viewing 4

E emergency-level messages 34 encoding, character 20 error handling

configuring 33 viewing log 35

error-level messages 35 ExecuteJSP service 10, 23

F flow services

generating 19

G generating flow services 19

I IDL files

adding to the IFR 18 IDL return types

translation to flow service return types 19 unsigned long, considerations for using 21

IFR adding IDL files to 18

inbound adapter adding IDL files to the IFR 18 defining BroadVision server aliases for 16 enabling access via CORBA servers 8, 16 enabling access via session portals 10 implementing access via CORBA servers 18 implementing access via session portals 22 overview of 8

info-level messages 35

I N D E X


Interface Repository, see IFR 18 interfaces, CORBA server

selecting to expose to adapter 19 introduction to BroadVision Adapter 8 IT_DAEMON_PORT parameter for alias settings 18 IT_LOCAL_DOMAIN parameter for alias settings 18 IT_NAMES_SERVER parameter for alias settings 18 IT_NAMES_SERVER_HOST parameter for alias

settings 18 IT_NS_PORT parameter for alias settings 18

L library path

adding session portal library to 10 libwmservercomponents.dll file 12, 26 libwmservercomponents.so file 12, 26 libwmSessionPortal.sl library 10

in your library path 22 location of 22

libwmSessionPortal.so library 10 in your library path 22 location of 22

log configuring to maintain a log 34 configuring to maintain on console 34 configuring to not maintain a log 34 configuring to record to a file 34 configuring to record to a file and on console 34 configuring type of messages to record 34 viewing 35

logfile.txt file location of 34 purpose of 34

logging alert-level messages 34 BroadVision Adapter activity 33 critical-level messages 35 debug-level messages 35 emergency-level messages 34 error-level messages 35 info-level messages 35 notice-level messages 35 warn-level messages 35

Logging Level field Alert 34 Critical 35 Debug 35 description of levels 34 Emergency 34 Error 35 Info 35 Notice 35 Warn 35

M messages

alert-level 34 critical-level 35 debug-level 35 emergency-level 34 error-level 35 info-level 35 notice-level 35 warn-level 35

methods, CORBA generating to produce flow services 19 selecting to expose to adapter 19

N notice-level messages 35

O outbound adapter

components of 12 implementing 26 overview of 12 webMethods CORBA Server 12, 29 webMethods Server Library Component 12, 26 writing .jsp files for 27, 28

P printing this document 5 program code

conventions used 3

S Server

shutting down 32 session portals

ExecuteJSP service for running 10, 23 implementing access to BroadVision via 22 running via inbound adapter 10 session portal library 10, 22 session portal library, in library path 10 specifying parameters of 23

shutting down BroadVision Adapter 32 Server 32

starting the BroadVision Adapter 32

T typographical conventions 2

U unsigned long data type, considerations for using 21

I N D E X


V viewing

BroadVision Adapter log 35 documentation in PDF format 4

W warn-level messages 35 webMethods CORBA Server 12, 29 webMethods Server Library Component 12, 26 wmCorba_srv.jar file 12, 29 wmServer.jsi file 27, 28 wmSessionPortal.dll file 10

in your library path 22 location of 22

webMethods BroadVision Adapter User Guide

V E R S I O N 1 . 2

webMethods, Inc. 3930 Pender Drive Fairfax, VA 22030 USA 703.460.2500 http://www.webMethods.com

webMethods for Trading Networks, webMethods for Partners, webMethods Developer, webMethods Integration Server, webMethods EDI Adapter, webMethods Enterprise Integrator, webMethods Enterprise Server, and the webMethods logo are trademarks of webMethods, Inc. “webMethods” is a registered trademark of webMethods, Inc. All other marks are the property of their respective owners. The software described in this manual contains encryption software from RSA Data Security, Inc.

Copyright © 2001 by webMethods, Inc. All rights reserved including the right of reproduction in whole or in part in any form. The software described in this manual contains International Components for Unicode (ICU4J) software. Copyright © 1995-2001 by International Business Machines Corporation and others. All rights reserved. webM-BroadVision-UG-20010719

iii

C O N T E N T S

Introduction...............................................................................................................................1 Welcome! ........................................................................................................................................................ 2 Typographical Conventions............................................................................................................................. 2

Program Code Conventions..................................................................................................................... 3 Related Documentation................................................................................................................................... 4

Viewing this Document............................................................................................................................. 4 Printing this Document ............................................................................................................................. 5

Product Overview .....................................................................................................................7 What is the BroadVision Adapter? .................................................................................................................. 8

What is the Inbound Adapter?.................................................................................................................. 8 What is the Outbound Adapter? ............................................................................................................. 12

Implementing the Inbound Adapter ......................................................................................15 Introduction.................................................................................................................................................... 16 Specifying Aliases for BroadVision Servers .................................................................................................. 16

How Does a Service Use the Aliases?................................................................................................... 16 Defining Aliases ..................................................................................................................................... 17

Implementing Inbound Adapters that Expose CORBA Servers..................................................................... 18 Adding IDL Files to the Interface Repository.......................................................................................... 18 Generating Flow Services for the Inbound Adapter................................................................................ 19

Testing Inbound Session Portal Interfaces.................................................................................................... 22

Implementing the Outbound Adapter....................................................................................25 Introduction.................................................................................................................................................... 26 What is the webMethods Server Library Component? .................................................................................. 26 The wmServer.jsi File.................................................................................................................................... 28 The webMethods CORBA Server IDL File .................................................................................................... 29

Administration ........................................................................................................................31 Administrative Tasks ..................................................................................................................................... 32

Starting the BroadVision Adapter ........................................................................................................... 32 Stopping the BroadVision Adapter ......................................................................................................... 32 Defining a Connection to a BroadVision Server ..................................................................................... 32

iv

Viewing/Editing Aliases...........................................................................................................................32 Testing Aliases .......................................................................................................................................33

Configuring How the BroadVision Adapter Maintains its Log.........................................................................33 Viewing the Contents of the Log File .............................................................................................................35

web methods broad vision adapter user guide v1

Documents