AdapterforVantiveUserGuide

Transcription

1 IBM WebSphere Business Integration Adapters AdapterforVantieUserGuide V3.6.x

2

3 IBM WebSphere Business Integration Adapters AdapterforVantieUserGuide V3.6.x

4 Note! Before using this information and the product it supports, read the information in Notices on page April2003 This edition of this document applies to connector ersion 3.6.x and to all subsequent releases and modifications until otherwise indicated in new editions. To send us your comments about this document, We look forward to hearing from you. When you send information to IBM, you grant IBM a nonexclusie right to use or distribute the information in any way it beliees appropriate without incurring any obligation to you. Copyright International Business Machines Corporation All rights resered. US Goernment Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

5 Integration broker compatibility Supported on IBM WebSphere Business Integration Adapter Framework ersion 2.2.0, IBM CrossWorlds Infrastructure ersion and 4.2 (if the enironment uses ISO Latin-1 data only), WebSphere MQ Integrator ersion 2.1.0, and WebSphere MQ Integrator Broker, ersion See Release Notes for any exceptions. Copyright IBM Corp iii

6 i Adapter for Vantie User Guide

7 Contents Integration broker compatibility iii About this document ii Audience ii Related documents ii Typographic conentions ii New in this release ix New in release 3.6.x ix New in release 3.5.x ix Chapter 1. Oeriew of the adapter The adapter for Vantie How the adapter works Chapter 2. Installing and configuring the adapter Prerequisites Installing the adapter Enabling the Vantie application for the adapter Configuring the adapter Starting the adapter If the Vantie installation has been modified Chapter 3. Deeloping business objects for the adapter Vantie application background Business object naming conentions Business object structure Business object attributes Application-specific text Writing VBA scripts for new business objects Chapter 4. Troubleshooting Start-up problems Eent processing Mapping (ICS Integration Broker only) Vantie_Customer business object with multiple addresses Different users of the Vantie client and adapter Appendix A. Standard configuration properties for adapters New and deleted properties Configuring standard connector properties for WebSphere InterChange Serer Configuring standard connector properties for WebSphere MQ Integrator Appendix B. Connector Configurator Using Connector Configurator in an internationalized enironment Starting Connector Configurator Choosing your broker Using a connector-specific property template Using Connector Configurator with ICS as the broker Setting the configuration file properties (ICS) Setting the configuration file properties (WebSphere MQ Integrator Broker) Using standard and connector-specific properties with Connector Configurator Completing the configuration Copyright IBM Corp. 2003

8 Appendix C. Adapter feature list Business object request handling features Eent notification features General features Notices Programming interface information Trademarks and serice marks i Adapter for Vantie User Guide

9 About this document IBM(R) WebSphere(R) Business Integration Adapters supply integration connectiity for leading e-business technologies and enterprise applications. This document describes the installation, configuration, and business object deelopment for the adapter for Vantie. Audience This document is for consultants, deelopers, and system administrators who use the adapter at customer sites. Related documents Typographic conentions The WebSphere business integration system documentation describes the features and components common to all installations, and includes reference material on specific collaborations and adapters. This document contains many references to two other documents: the System Installation Guide for Windows or for UNIX and the System Implementation Guide for WebSphere InterChange Serer. If you choose to print this document, you may want to print these documents as well. To access the documentation, go to the directory where you installed the product and open the documentation subdirectory. If a welcome.html file is present, open it for hyperlinked access to all documentation. If no documentation is present, you can install it or read it directly online at one of the following sites: If you are using WebSphere MQ Integrator Broker as your integration broker: If you are using InterChange Serer as your integration broker: The documentation set consists primarily of Portable Document Format (PDF) files, with some additional files in HTML format. To read it, you need an HTML browser such as Netscape Naigator or Internet Explorer, and Adobe Acrobat Reader or higher. For the latest ersion of Adobe Acrobat Reader for your platform, go to the Adobe website ( This document uses the following conentions: courier font bold italic, italic blue text Indicates a literal alue, such as a command name, file name, information that you type, or information that the system prints on the screen. Indicates a new term the first time that it appears. Indicates a ariable name or a cross-reference. Blue text, which is isible only when you iew the manual online, indicates a cross-reference hyperlink. Click any blue text to jump to the object of the reference. Copyright IBM Corp ii

10 ProductDir Product family is WBIA: Represents the directory where the IBM WebSphere Business Integration Adapters product is installed. The CROSSWORLDS enironment ariable contains the ProductDir directory path, which is IBM\WebSphereAdapters by default. { } In a syntax line, curly braces surround a set of options from which you must choose one and only one. In a syntax line, a pipe separates a set of options from which you must choose one and only one. [] In a syntax line, square brackets surround an optional parameter.... In a syntax line, ellipses indicate a repetition of the preious parameter. For example, option[,...] means that you can enter multiple, comma-separated options. <> Angle brackets surround indiidual elements of a name to distinguish them from each other, as in <serer_name><connector_name>tmp.log. iii Adapter for Vantie User Guide

11 New in this release New in release 3.6.x Updated in March, The CrossWorlds name is no longer used to describe an entire system or to modify the names of components or tools, which are otherwise mostly the same as before. For example CrossWorlds System Manager is now System Manager, and CrossWorlds InterChange Serer is now WebSphere InterChange Serer. The IBM WebSphere Business Integration Adapter for Vantie includes the connector for Vantie. This connector supports two integration brokers: InterChange Serer (ICS) and WebSphere MQ Integrator Broker. An integration broker is an application that performs integration of heterogeneous sets of applications; it proides serices such as data routing. The IBM WebSphere Business Integration Adapter for Vantie includes the following: An application component specific to Vantie A sample business object (located in the \connectors\vantie\samples directory) IBM WebSphere Adapter Framework, which consists of the following: Connector Framework Deelopment tools (including Business Object Designer and Connector Configurator) APIs (including ODK, JCDK, and CDK) This manual proides information about using the connector with both the ICS and WebSphere MQ Integrator Broker integration brokers. Important Because the connector has not been internationalized, do not run it against InterChange Serer ersion if you cannot guarantee that only ISO Latin-1 data will be processed. New in release 3.5.x This release of this document contains the following new or changed information. Business object naming conentions The naming conentions for business objects for Vantie hae changed. For information, see Chapter 3, Deeloping business objects for the adapter, on page 21. Document reisions This document has been restructured and rewritten. Copyright IBM Corp ix

12 x Adapter for Vantie User Guide

13 Chapter 1. Oeriew of the adapter The adapter for Vantie Adapters consist of two parts: the connector framework and the application-specific component. The connector framework, whose code is common to all adapters, acts as an intermediary between the integration broker and the application-specific component. The application-specific component contains code tailored to a particular application or technology (in this case, Vanite). The connector framework proides the following serices between the integration broker and the application-specific component: Receies and sends business objects Manages the exchange of startup and administratie messages This chapter describes the adapter component of the IBM WebSphere Business Integration Adapter for Vantie. It contains the following sections: The adapter for Vantie How the adapter works on page 2 Note that this document contains information about both the connector framework and the application-specific component. It refers to both of these as the adapter. For more information about the relationship of the integration broker to the adapter, see the IBM WebSphere InterChange Serer System Administration Guide, or the IBM WebSphere Business Integration Implementation Guide for WebSphere MQ Integrator Broker The IBM WebSphere Business Integration Adapter for Vantie enables your integration broker to exchange business objects with Vantie 7.0 and 8.0 applications. The adapter implements business object handling, eent polling, and eent notification. The application-specific component of the adapter generates business objects that it sends to the integration broker; it also responds to business object requests from the integration broker. It generates logging and tracing messages that it writes to a file or the adapter console, or sends to the integration broker. Figure 1 illustrates the architecture of the adapter and its eent mechanism, as seen in an enironment where InterChange Serer is used as the integration broker. Copyright IBM Corp

14 Vantie Client Vantie basic scripts on form eents Inbox Polling InterChange Serer connector controller VanAPI Connector Internal Jaa component Vantie Serer Eent notification Global functions Business object requests Application database Business object operations Figure 1. Architecture of the adapter in an InterChange Serer enironment How the adapter works The following sections describe how the adapter processes business object requests and eent notifications. Business object processing To process business object requests, such as Create, Retriee, Update, and Delete operations, the adapter uses the Vantie API to communicate with the Vantie application. The Vantie API hides the database schema and database transactions from the adapter. The Vantie API enables the adapter to log in to the application using a special WebSphere Business Integration Adapter account. During installation, a connection is established between the adapter and the Vantie serer through which all the API commands are executed. There is only one connection open per process at a time; therefore, the adapter is single threaded at the point of connection. The business logic of the adapter has been implemented in specific business object handlers. For example, the business logic specific to RMA has been isolated in the V_RMAHandler module. Create operations To perform a Create operation, the adapter first processes the parent form, and then processes the child forms, if any child objects are present in the incoming object. To perform Creates, the adapter: 1. Attempts to retriee the parent record using the key alue passed in by the business process. This is to determine whether the record already exists. 2. If the retriee is successful, the adapter calls the Update routine. 2 Adapter for Vantie User Guide

15 3. If the retriee is not successful, the adapter creates the parent form and saes the child object forms. Note that in order for this approach to work correctly, deelopers must ensure that primary key attributes in the parent and child objects are cross-referenced correctly for Create operations. Note: The adapter will cause a Create operation to fail if a business object does not hae a alid alue or a default alue for a Required attribute. Update operations When performing an Update operation, the adapter first retriees a copy of the object passed to it by the business process (the inbound object) from the Vantie database using the primary key alues of the object. This copy (the current object) is an accurate representation of the current state of the object in Vantie. This object is compared to the inbound object to determine what changes need to be applied to Vantie during the update. The adapter first updates the parent form then recursiely updates all children of the parent object, as follows: If the child is present in both the inbound object and the current object, it is recursiely updated. Note that in this case, the inbound child and the current child must match. If the child is present in the inbound object but not in the current object, it is recursiely created. If the child is present in the current object but not in the inbound object, the adapter does nothing. Note that it is up to the business process to ensure that objects within cardinality n containers in the inbound object are unique. If duplicates of an object exist in the inbound container, they are processed twice, with possibly undefined results. Delete operations The adapter performs hard deletes, where information is physically deleted from Vantie. The adapter recursiely deletes all children and then deletes the parent. When the adapter is passed a hierarchical business object for a Delete operation, the adapter assumes that the inbound business object exactly matches the current Vantie representation of that object. The business process is responsible for ensuring that this is the case. If, for example, the inbound object does not contain children that exist in the Vantie representation of the object, those children will not be deleted. Likewise, if the inbound object contains children that do not exist in the Vantie representation of the object, the delete will fail, as the adapter cannot delete business objects that do not exist in Vantie. Business object retrieal When the adapter retriees a business object, it uses the primary key alues in the top-leel indiidual business object passed to it by the business process to recursiely descend through the business object. At each leel, it modifies the business object passed to it by the business process so that it accurately reflects the current Vantie representation of the object. It is important to realize that this modification may not only entail changing simple attributes of indiidual business objects, but may also entail adding or remoing child indiidual business objects. If the RetrieeAll adapter configuration property is true, the adapter retriees the parent business object and all child objects. If the property is false, the adapter Chapter 1. Oeriew of the adapter 3

16 retriees only the parent business object and newly created or modified child objects. The RetrieeAll operation is based on the keys of the parent business object and the child business objects. A business object may hae certain attributes that do not correspond to any Vantie column (for example, placeholder attributes). During retrieal, such attributes in the top-leel business object are unchanged and remain set to the alues passed in by the business process. For child business objects, those attributes are set to their default alues during retrieal. Eent notification The eent notification mechanism uses Vantie Basic (VBA) scripts and Vantie s Inbox notification system to detect and store eents. When an eent occurs in the application, Vantie Basic scripts populate the Inbox. The adapter polls the Inbox at a configurable interal, processes eents sequentially, and then remoes them from the Inbox. Eent triggering Vantie has a built-in eent notification system called the Inbox. During installation, an Inbox is created for WebSphere Business Integration Adapter, and this Inbox is populated using Vantie Basic scripts on form eents. The adapter includes a set of Vantie Basic scripts that generate Inbox records for eents on main objects, subforms, or related objects. When an eent occurs in the application, notification rules in the Vantie Basic scripts are inoked, and a record of the eent is stored in the Inbox. Create and Update eent records are generated by the VBA scripts independently of the database on which the Vantie application is running. Delete eents are dependent on additional stored procedures that are inserted into the underlying database during adapter installation. Eent detection The adapter interacts with the application through the WebSphere Business Integration Adapter Inbox. The adapter checks the Inbox for new eents at the interal defined by the PollFrequency configuration property. When the adapter sees a new eent, it retriees the eent. Eent retrieal To retriee eents, the adapter uses the VanAPI VanFetchRecord call to retriee records from the Inbox. In one polling interal, the adapter retriees the MaxEents number of records from the Inbox. The adapter then loops through each eent and processes it. The adapter retriees and processes eents as follows: 1. The adapter uses the session handler with the Vantie serer to retriee eents from the Inbox. 2. The adapter calls VanCreateInboxForm to open the Inbox form. 3. The adapter calls VanOpenCursor to open a cursor on the Inbox form. 4. The adapter calls VanFetchRecord to fetch the records from the open cursor. The adapter retriees the number of eents specified by the MaxEents adapter configuration property. For each record, the adapter does the following: a. Determines object type and erb. b. Checks if the eent is subscribed. 4 Adapter for Vantie User Guide

17 If the erb is Delete, creates an Object instance with the Id of the object. If the erb is other than Delete, checks whether the retriee is for a modified record or for the whole object. If it is for a modified record, retriees that record. Otherwise, it retriees the record and all associated child objects. Remoes the record from the Inbox after sending it to the integration broker. c. If the eent is not subscribed, it is left in the Inbox. Note: For subscription information specific to your integration broker, refer to the broker s implementation guide. Archiing The adapter has not implemented eent archiing. If an eent is not subscribed or is not successfully picked up and sent to the integration broker, it remains in the Inbox. For subscription information specific to your integration broker, refer to the broker s implementation guide. Chapter 1. Oeriew of the adapter 5

18 6 Adapter for Vantie User Guide

19 Chapter 2. Installing and configuring the adapter Prerequisites This chapter describes how to install and configure the adapter. It contains the following sections: Prerequisites Installing the adapter Enabling the Vantie application for the adapter on page 8 Configuring the adapter on page 16 Starting the adapter on page 18 If the Vantie installation has been modified on page 18 Note: Before beginning the installation, determine whether the application has been customized. Existing application customization may affect how you enable the application for the adapter; for more information, see page 18. In addition, since the adapter setup requires the installation of VBA scripts and stored procedures on database tables, determine whether the releant tables hae existing scripts, and make sure that WebSphere Business Integration Adapter-specific scripts do not oerwrite the existing scripts. Installed location of the VanAPI DLLs When Vantie Client is installed, the anapi32.dll file gets copied under the C:\Winnt\System32 directory. When Vantie Serer or Client is installed, the anapi32.dll also gets copied onto the VanAPI directory under the Vantie Serer or Client installation. Check the enironment ariables to ensure that the PATH includes C:\Winnt\System32 (for Vantie Client installation) or the VanAPI directory under the Vantie Serer or Client Installation. Database support The adapter supports Vantie 7.0 and 8.0 running on Microsoft SQL Serer or Oracle. If you are running Vantie on another database, you will need to rewrite the WebSphere Business Integration Adapter-supplied scripts to be compatible with the database. Installing the adapter To install the adapter, run the Installer for IBM WebSphere Business Integration Adapter and select the IBM WebSphere Business Integration Adapter for Vantie. All standard files associated with the adapter are installed. Table 1 describes the file structure for the adapter. Table 1. Installed file structure for the adapter Directory Description \connectors\vantie Contains the adapter DLL. \connectors\vantie\dependencies Contains the Vantie Basic scripts and stored procedures required for eent triggering. \connectors\messages Contains the VantieConnector.txt file. Copyright IBM Corp

20 Installer adds an icon for the adapter file to the IBM WebSphere Business Integration Adapters menu. For a fast way to start the adapter, create a shortcut to this file on the desktop. For more information on installing the adapter component, refer to one of the following guides, depending on the integration broker you are using: IBM WebSphere InterChange Serer System Installation Guide for Windows (when ICS is used as the integration broker) IBM WebSphere Business Integration Adapters Implementation Guide for WebSphere MQ Integrator Broker (when WebSphere MQ Integrator Broker is used as the integration broker) Configuring the adapter as a serice The adapter can be configured to run as a Windows Serice. As a Serice, the adapter starts automatically upon restart of the Windows system. For instructions, refer to the System Installation Guide for UNIX or for Windows. When the adapter for Vantie starts as a Windows Serice, it tries to log into the application using the system account, and not the user account. Use the following steps to configure the adapter to log in as the user: 1. From the Start menu, select Settings >Control Pane >Serices. 2. Select the adapter for Vantie. 3. Click the Startup button. 4. Select This Account in the Log On As window and specify the account that the Vantie Client is installed under. Enabling the Vantie application for the adapter Before you can use the adapter to process application eents and send eent notification business objects to the integration broker, you must set up the eent notification mechanism. To do this, you must create the Inbox that stores eent records and set up eent triggering. These tasks are described in the sections that follow. Note: If you are not familiar with the Vantie application, enabling the Vantie application to work with the adapter may be difficult. In this case, it is recommended that you work with an application expert. For information on Vantie concepts or tools, consult the Vantie documentation. Setting up the eent inbox To set up an Inbox for eent notification, perform the tasks below using Vantie Tools and Vantie Forms Designer. Vantie Tools should be set to the Vantie Applications Database. Note: The adapter polls the eent Inbox and expects this inbox to contain only eents created by Vantie Basic (VBA) triggers. This inbox should not be used for other business processes or users. Inalid data in this inbox can hae detrimental effects on the performance of the system. 8 Adapter for Vantie User Guide

21 Setting up a WebSphere Business Integration Adapter user account and inbox Use Vantie Tools. 1. Select File >New >User. The Inbox form is displayed. 2. For User Login Name, enter any alid Vantie user name. 3. For Group Name, select Enterprise Admin from the drop down list, or enter Enterprise Admin. 4. For Default Inbox, enter the name you hae chosen for the WebSphere Business Integration Adapter Inbox. This should match the name that you set for the InboxName adapter configuration parameter. For example, enter XRD. 5. In the locator that appears for the Inbox, click New. 6. In the New Inbox form, the new inbox name is displayed. If not, enter the name of the WebSphere Business Integration Adapter Inbox for the Inbox Name. 7. Sae and close the Inbox form. 8. Sae and close the User form. Creating the default inbox form for WebSphere Business Integration Adapter Make the XRD Inbox the default Inbox for WebSphere Business Integration Adapter. Use Vantie Forms Designer. 1. Select File >Form Explorer >SW_ACTION_LOG >Inbox. 2. Double click swinboxscr to open the form. 3. Lock the form. 4. Select File >Sae Copy. 5. In New Form Name, key in swxrdinboxscr for the name of the new form and click OK. The new form is displayed 6. In the Order By field on the new form, the following rule is displayed: SW_ACTION_LOG.swDateReceied To sort the inbox eents in ascending order by date receied and action, change the rule to read: SW_ACTION_LOG.swDateReceied ASC, SW_ACTION.swAction ASC 7. Make sure that the Primary button is selected. 8. Select the Fields tab. 9. Select the Object Type row. 10. In the Column Path box, moe to the end of the text string and replace swlabel with swobjecttype. 11. Click Replace. 12. In the Fields form, click New. 13. For the Field Label, enter Note to create a note field in the inbox. 14. For the Column Path select swnote. 15. For the Display Width enter Click Add. 17. Sae the form and close. Seting the default inbox for WebSphere Business Integration Adapter Use Vantie Tools. 1. Select File >Open >Inbox. Chapter 2. Installing and configuring the adapter 9

22 2. In the Inbox locator window, use Search to find the name of the WebSphere Business Integration Adapter Inbox that you created in the steps aboe. Double click the Inbox name or type the name into the InboxName field. 3. In the Inbox form, for User, enter the WebSphere Business Integration Adapter account user name or use the drop down menu to select the user name. 4. For Display Form, select swxrdinboxscr from the drop down menu or enter the name. The Inbox name and WebSphere Business Integration Adapter user are now linked. 5. Sae and Close. Setting up eent triggering To set up Vantie objects so that they trigger eents, perform the following tasks using Vantie Tools and Vantie Forms Designer. Vantie Tools should be set to the Vantie Applications Database. Identifying the main forms used by Vantie objects For each Vantie object that will be the source for eents sent into the WebSphere Business Integration Adapter system, identify the Main Info form used by the object. Use Vantie Tools to create a list of the Main Info forms for the objects; you will need the form names in subsequent procedures. 1. Select File >Open >Group. 2. Search for the Enterprise Admin group and select it from the list of groups. 3. Click the Forms tab. 4. Find the Form Name for <object> Main Info, where <object> is the Vantie object type whose main form you are identifying, such as CUSTOMER. For example, to find the main form for the CUSTOMER object, find Company Main Info; the main form is SwCustomerScr. 5. Write down the name of the Main Info form. Repeat for eery group affected by the adapter. Adding triggers on the main forms For each Vantie object, add triggers to create the form eents for the main forms. A main form has a Main Info form. Use Vantie Forms Designer. 1. Select File >Form Explorer >SW_<object> >Main Info. 2. Select the name of the Main Info form for an object supported by the adapter. Use the list of Main Info forms that you created in the preious procedure. 3. Lock the form. 4. Double click on the form to display the properties dialog box. 5. Click the Eents tab. 6. To create form eents for main forms for Delete and Update operations, follow the steps below the table. Use the table eent names (i) and procedure calls (j) to complete the steps. i PreDelete Record PostDelete Record PostUpdateRecord j PreDelObject PostDelObject PostUpdateObject 10 Adapter for Vantie User Guide

23 For each eent: a. Click New. b. Select a table eent name listed in column (i) for Eent. c. Select Client Basic Function for Procedure Type. d. Enter a corresponding procedure name from column (j) for Procedure Call. Make sure that the Procedure Call is Primary. e. Click Add. To continue adding eents to a form, click New and repeat the steps. f. When you hae finished adding eents to a form, click Apply and sae. g. Click OK. h. Sae the form. 7. To create form eents that will execute on Create operations, use the following data for i and j, and use the instructions for creating Update and Delete eents in the preious step. Howeer, before beginning note that where you add the form eent for Creates differs, as follows: If the object is not a hierarchical object, the Create eent is added to the main form. An eent is stored in the Inbox when the main form is saed. If the object is hierarchical but does not require a child object, the Create eent is added to both the main form and the subform. In this case, an eent is stored in the Inbox when either the main form or subform is saed. For hierarchical objects that require at least one child object, the Create eent is added to the subform instead of the main form. When the subform is saed, the parent object (with the child object) is sent to the Inbox, and the adapter can pick up the eent. i PostInsertRecord j PostCreateObject Use Business Object Designer to determine whether a business object is hierarchical, and use the application-specific business object documentation to determine whether a business object has required child objects. For example, Vantie_Customer is hierarchical and requires at least one child object, so the create eent is added to the subform. Adding triggers on subforms In the Vantie application, a WebSphere Business Integration Adapter Vantie application-specific child business object may be represented by a subform or by a related object. Subforms hae Child Detail forms but no Main Info forms. For the subforms in each group, you need add triggers to create the form eents for each subform. Use Vantie Forms Designer. 1. Select File >Form Explorer >SW_<object> >Main Info. 2. Select the name of the Main Info form for an object supported by the adapter. 3. Click on the Subform label tab. For example, for the Addresses subform, click on the Addresses tab. 4. Double click in the area below the summary table. The Field Properties box displays the subform name under Screen Name. Record the subform name. 5. Return to the forms list under File >Form Explorer. 6. Select SW_<child object> >Child Detail. 7. Lock the form. Chapter 2. Installing and configuring the adapter 11

24 8. Select <Subform name>. The child form is displayed. 9. Double click on the form to display the properties dialog box. 10. Click the Eents tab. 11. To create form eents for subforms, follow the subprocedure below the table. Use the table eent names (i) and procedure calls (j) to complete the steps. i PreDeleteRecord PostDeleteRecord PostInsertRecord PostUpdateRecord j PreDelSubform PostDelSubform PostInsertSubform PostUpdateSubform For each eent: a. Click New. b. Enter a table eent name from column (i) for Eent. c. Enter Client Basic Function for Procedure Type. d. Enter a procedure name from column (j) for Procedure Call. Make sure that the Procedure Call is Primary. e. Click Add. To continue adding eents to a form, click New and repeat the steps. f. When you hae finished adding eents to a form, click Apply and sae. g. Click Apply and sae. h. Click OK. i. Sae the form. Adding triggers on related objects In the Vantie application, a WebSphere Business Integration Adapter Vantie application-specific child business object may be represented by a subform or by a related object. Related objects are Vantie objects that hae Main Info forms. The relationship is not hierarchical in the Vantie application, but the form is represented by a child object in the WebSphere Business Integration Adapter Vantie application-specific business object. For related objects, you need to add triggers to create the form eents for each related object. Use Vantie Forms Designer. 1. Select File >Form Explorer >SW_<object> >Main Info. 2. Select the name of the Main Info form for the related object. 3. Lock the form. 4. Double click on the form to display the properties dialog box. 5. Click the Eents tab. 6. To create form eents related objects, follow the subprocedure below the following table. Use the table eent names (i) and procedure calls (j) to complete the steps. 7. To create form eents for subforms or subobjects, follow the subprocedure below the table. Use the table eent names (i) and procedure calls (j) to complete the steps. 12 Adapter for Vantie User Guide

25 i PreDeleteRecord PostDeleteRecord PostInsertRecord PostUpdateRecord j PreDelSubObject PostDelSubObject PostCreateSubObject PostUpdateSubObject For each eent: a. Click New. b. Enter a table eent name from column (i) for Eent. c. Enter Client Basic Function for Procedure Type. d. Enter a procedure name from column (j) for Procedure Call. Make sure that the Procedure Call is Primary. e. Click Add. To continue adding eents to a form, click New and repeat the steps. f. When you hae finished adding eents to a form, click Apply and sae. g. Click Apply and sae. h. Click OK. i. Sae the form. Copying and compiling VBA scripts Use Vantie Forms Designer to add VBA scripts from %ProductDir%\connectors\Vantie\dependencies to Vantie. For Oracle, use the VBA scripts in VBAOracle.doc. For Microsoft SQL Serer, use the scripts in VBA.doc. The VBA scripts are: XrdCreateObject XrdCreateSubObject XrdCreateUpdateSubform XrdUpdateObject XrdUpdateSubform XrdUpdateSubObject XrdDeleteObject XrdDeleteSubform XrdDeleteSubObject Repeat the steps below for each VBA script. 1. Select File > Script Explorer. 2. Select File > New > Script. 3. Type in the name of the script and click OK. 4. Copy the script into Script Text. 5. Click Compile to compile the script. 6. Sae the script. Continue copying and compiling the scripts until complete. 7. Close. Copying and executing stored procedures The appropriate flaor of the stored procedures Xrd_Delete, Xrd_Obj_Delete, and Xrd_Insert_User must be inserted into the database on which the Vantie system runs. The Xrd_Delete and Xrd_Obj_Delete stored procedures enable eent notification for Delete eents. They store the ID of a record so that when the record Chapter 2. Installing and configuring the adapter 13

26 is deleted from the database, an eent notification containing the Id can be written to the eent table. The Xrd_Insert_User is proided to add existing users to the Inbox recipient list. This stored procedure must be called from an external program in a loop, passing the Inbox name and the user name to the Inbox. Note: If your business objects are named according to the new standards described in Business object naming conentions on page 21, you must edit seeral of the stored procedures. See Specifying business object names in stored procedures for information. If your business objects are named according to the old rules for business objects for Vantie, you do not need to edit the stored procedures. The stored procedures are located in %ProductDir%\connectors\Vantie\dependencies. For Oracle, the file containing the stored procedures is Oracle.sql; for Microsoft SQL Serer, the file is Mssql.sql. To insert the stored procedures, use an SQL processing tool. For example, for Oracle, use SQL Worksheet or SQL Plus; for Microsoft SQL Serer, use isql. 1. Copy the following stored procedures into the database on which Vantie runs: Xrd_Delete Xrd_Obj_Delete Xrd_Insert_User 2. If necessary, grant the swb user execute permission on these procedures. Specifying business object names in stored procedures: If your business objects for Vantie are named according to current WebSphere Business Integration Adapter naming conentions rather than the preious business object naming conentions, you must edit the following VBA scripts: PostDelObject PostDelSubObject PostDelSubform In these scripts, find the line: attrval(0)=objecttype and edit it to specify the business object name instead of the Vantie object type. For example, if the object type is CUSTOMER, but the business object name is Vantie_Customer, edit the line as follows: if (objecttype= CUSTOMER ) attrval(0)= Vantie_Customer end if This enables the script to add the name of the business object to the eent table instead of the Vantie object name. In this way, the adapter will be able to create the correct WebSphere Business Integration Adapter business object for the eent. For information on business object naming conentions, see Business object naming conentions on page 21. Setting the priority leel For each object, set the priority leel by executing one of the following SQL commands in the Vantie database. Substitute the Vantie object type for <object> for the first parameter in the alues clause. To find the Vantie object type, use Vantie Tools File >Open >Object. 14 Adapter for Vantie User Guide

27 For Microsoft SQL Serer, execute this command: insert into SW_VAL_ACT_PRI alues ( <Vantie object>, XrdPriority, 1, null, saint, getdate(), null) For Oracle, execute this command: insert into SW_VAL_ACT_PRI alues ( <Vantie object>, XrdPriority, 1, NULL, saint, SYSDATE, NULL) For example, to set the priority leel for the CUSTOMER object in SQL Serer, the command would be: insert into SW_VAL_ACT_PRI alues ( CUSTOMER, XrdPriority, 1, null, saint, getdate(), null) Enabling the utility menu command For each object, use Vantie Tools to enable the Utility Menu Command Send: 1. Select File >Open >Object. 2. Click Search to display a list of the objects. 3. Double click on the object to bring up a Dialog Box. 4. Click the Utility Menu Commands tab. 5. In the Utility Menu Commands form, click New. 6. Select Send for the Menu Command. 7. Sae and Close. 8. Exit Vantie Tools to display the new objects. Setting the action request codes For each object, use Vantie Tools to set the Action Request Codes for the Create, Update, and Delete erbs. You will need to restart Vantie Tools. 1. Select File >Action Request Code > <object label>, where <object label> is the object for which you are setting the action request codes. 2. For each erb on the object, do the following: a. For New Value, enter the name of the erb, such as Create. b. Click Sae. c. Highlight the erb name. d. Change Priority to XrdPriority. e. Make sure that the Confirmation and Required checkboxes are clear. 3. Sae and close. Repeat steps 2 through 6 substituting other erb names in steps 2 and 3. Setting up business object processing To set up Vantie as the destination application for integration broker requests, you must ensure that ID fields for the Vantie subforms that a business object points to are present on the subforms. If an ID field is missing from a subform, the adapter will not be able to open the form and process the business object. To rectify this, add missing Ids as hidden fields on subforms. Note that non-id fields that are present in a business object but are not on related forms will be logged as warnings and ignored. To add a missing ID to a subform as a hidden field, use Vantie Forms Designer and follow these steps: 1. Select File >Form Explorer >SW_<object>. For example, select SW_ADDRESS. Chapter 2. Installing and configuring the adapter 15

28 Configuring the adapter 2. Double click on the Child Detail form. 3. Double click on the required subform to open it. For SW_ADDRESS, click on swaddresssupu. 4. From the main menu, select Fields > Hidden Field and drop the hidden field on the form. 5. Double click the Hidden Field to bring up the Field Properties Dialog. 6. On the Data tab for Column Path select the necessary subform ID, such as SWADDRESSID, click Apply, and click OK. 7. Sae and close the subform. You must set the adapter s standard and adapter-specific configuration properties before you can run it. Use one of the following tools to set a adapter s configuration properties: Connector Configurator (if ICS is the integration broker)--access this tool from the System Manager. Connector Configurator (if WebSphere MQ Integrator Broker is the integration broker)--access this tool from the IBM WebSphere Business Integration Adapter program folder. For more information about Connector Configurator, see Appendix B, Connector Configurator, on page 59 Standard adapter properties Standard configuration properties proide information that all adapters use. See Appendix A, Standard configuration properties for adapters, on page 37 for detailed information about these properties. Note: This adapter is single threaded. Therefore, it cannot use the AgentConnections property. Important Because the connector for Vantie supports both the ICS and WebSphere MQ Integrator Broker integration brokers, configuration properties for both brokers are releant to the connector. Adapter-specific properties Adapter-specific configuration properties proide information needed by the adapter at runtime. Adapter-specific properties also proide a way of changing static information or logic within the adapter without haing to recode and rebuild it. Table 2 lists the adapter-specific configuration properties for the adapter. See the sections that follow for explanations of the properties. 16 Adapter for Vantie User Guide

29 Table 2. Adapter-specific configuration properties Name Possible alues Default alue Required ApplicationUserName Name of user account xwrlds Yes ApplicationPassword Password for user account antie Yes InboxName Name of WebSphere Business XRD Yes Integration Adapter Inbox MaxEents Number of eents the adapter picks 25 No up in one poll. RetrieeAll true or false true No SererName Name of the serer running Vantie antie Yes SererPort Port of the serer running Vantie 1540 Yes UseDefaults true or false false No UseOldStyle true or false false No ApplicationUserName Name of the adapter s user account. ApplicationPassword Password for the adapter s user account. InboxName Name of WebSphere Business Integration Adapter Inbox in Vantie. MaxEents Number of eents to retriee per poll. The adapter poll method retriees the specified number of eent records and processes them in a single poll. Processing multiple eents per poll can improe performance when the application generates large numbers of eents. Howeer, since integration broker requests are blocked while the poll method is processing eents, be sure not to set the number of eents too high. RetrieeAll Use this property to specify RetrieeAll functionality for all business objects processed by the adapter. If set to true, the adapter retriees the parent business object and all child objects on a Retriee operation. If set to false, the adapter retriees the parent business object and only newly created or modified child objects. If any child objects hae been deleted and RetrieeAll is false, the Retriee operation returns the IDs for the deleted child objects. You can specify RetrieeAll functionality for indiidual business objects. To do this, use the application-specific text for the Retriee erb. Verb application-specific text format on page 32. SererName Name of the serer running Vantie. SererPort Port of the serer running Vantie UseDefaults This property ensures that required business object attributes hae alues before a Create operation is performed in an application database. When UseDefaults is set to true, the connector framework looks at eery attribute in all leels of a a business object and processes the attributes as follows: 1. Attributes that are not set and that hae a default alue specified in the Default Value business object attribute property are set to the default alue. Chapter 2. Installing and configuring the adapter 17

30 Starting the adapter 2. Any attribute marked as Required and that is still not set after processing for default alues will cause the adapter to return BON_FAIL. When UseDefaults is set to false and attributes are not set, a NULL alue is set in the application. To implement this property, the adapter s business objects must be designed so that the Required property is set to true for required attributes and that required attributes hae default alues specified in the Default Value property. UseOldStyle Specifies whether the adapter processes business objects named according to preious business object naming rules. When UseOldStyle is set to true, the adapter processes only business objects with old style names. If it is set to false, the adapter processes only business objects with application-specific text that defines the Main Form and child subform at the business object leel; see Chapter 3, Deeloping business objects for the adapter, on page 21 for information on this application-specific text. If set to true and all business objects hae the required application-specific text, the adapter will process business objects with both old-style and new-style names. For information on starting and stopping a adapter, see one of the following documents, depending on the integration broker you are using: IBM WebSphere Business Integration Adapters Implementation Guide for WebSphere MQ Integrator Broker (WebSphere MQ Integrator Broker as the integration broker) IBM WebSphere InterChange Serer System Administration Guide (ICS as the integration broker) If the Vantie installation has been modified If you are installing the adapter into a modified Vantie application installation, you may need to modify the installation procedures for the adapter. This section describes modifications that you may need to make. If a Vantie object has been renamed If Vantie forms hae changed on page 19 If delete operations need to be synchronized across applications on page 19 If a Vantie object has been renamed If the name of a Vantie object has been changed from what the adapter expects, do the following: If the adapter configuration property UseOldStyle is set to true, the adapter expects old-style business object naming conentions. In this case, if a Vantie object has been renamed, you need to change the name of the Vantie application-specific business object to the new name of the Vantie object. For example, if the Vantie CUSTOMER object has been renamed to PARTY, the Vantie_CUSTOMER business object must be renamed to Vantie_PARTY. If, howeer, you are using the new business object naming conentions and the name of a Vantie object has changed, the application-specific text must be changed to reflect the new name of the Vantie object. Using the example aboe, 18 Adapter for Vantie User Guide

31 application-specific text at the object leel must be set to MF=PARTY. For information on this application-specific text, see Object application-specific text format on page 27. Edit the adapter s list of supported business objects to add the renamed business object. Change the map references to refer to the new name of the application-specific business object (releant only if ICS is the integration broker). For eent notification business objects sent to the integration broker, you need to modify the WebSphere Business Integration Adapter-proided VBA scripts to ensure that the names of any Vantie objects hardcoded in the VBA scripts match the names of the Vantie objects in your system. The WebSphere Business Integration Adapter VBA scripts are located in %ProductDir%\Vantie\dependencies. If a Vantie object has been renamed, but the object s forms and fields hae not been modified, your task is complete. Howeer, you may also want to confirm that the fields of the Vantie object match the attributes in the WebSphere Business Integration Adapter application-specific business object. If you find that a form s fields no longer match a business object s attributes, continue with the next section. If Vantie forms hae changed If the fields on any form that an application-specific business object points to hae been modified such that they no longer match the attributes in the application-specific business object, do the following: Change the attributes in the application-specific business object to match the modified forms. Change the maps to map the new attributes from the application-specific business object to the generic business object and ice ersa. Then recompile the maps and moe them to the appropriate directory (releant only if ICS is the integration broker). Change the contents and format of the business object application-specific text so that it is correct for the new attributes. For information on the format of application-specific information for business objects, see Application-specific text on page 27. Make sure that the Vantie forms hae all the required fields. If required Id fields are not present, add the missing fields as hidden fields on those forms. See Setting up business object processing on page 15 for information on adding Ids as hidden fields. If delete operations need to be synchronized across applications If the Vantie SW_ACTION and the SW_ACTION_LOG tables on which the WebSphere Business Integration Adapter Inbox is based hae been renamed or changed, and business objects will be used to send notification of Delete operations, then you need to modify the SQL scripts that create the stored procedures. These scripts hae hardcoded references to the SW_ACTION and SW_ACTION_LOG tables. The SQL scripts are located in the files Oracle.sql or Mssql.sql in the directory %ProductDir%\Vantie\dependencies. In addition, depending on the extent of the modifications, you might want to check the VBA scripts that call these procedures and modify the scripts as necessary. The VBA scripts that call the stored procedures are: PreDelSubform Chapter 2. Installing and configuring the adapter 19