Using the sample ODA

IBM provides a sample Object Discovery Agent that converts Roman-army soldiers (in XML format) to business object definitions. To familiarize you with using an ODA, the following step-by-step description of generating business object definitions uses this sample ODA.

Note:
For information on the location and files of this sample ODA, see Development support for ODAs.

This section includes the following tasks:

Starting the sample ODA

If you have installed the Adapter Development Kit (ADK), the sample ODA and the file to run it are located in the DevelopmentKits\Odk\Samples directory in the product directory. The file to run the sample ODA depends on your operating-system environment, as Table 12 shows.

Table 12. Startup script for a sample Roman Army ODA

Operating system Startup script
Windows start_Agent4.bat
Note:
The sample Roman Army ODA provides five versions to illustrate various features of an ODA. This section runs the fourth version of this sample ODA, which uses the start_Agent4 startup script and the ArmyAgent4 class file.

Because the sample Roman Army ODA provides five versions of itself, all startup scripts call one common startup script called start_AgentX, passing it the name of the ODA class (which is assigned to the AGENTCLASS configuration variable in start_AgentX). Therefore, the start_Agent4 startup script should contain a call to start_AgentX, passing it the following path as the name of the ODA class:

com.ibm.btools.ODK2.RomanArmy.ArmyAgent4
 

To verify configuration variables for this sample ODA, check the start_AgentX batch or script file to confirm that your confirmation variables match those in Table 13. If you move any of the files that version 4 of the sample Roman Army ODA uses, make sure you change the corresponding configuration variable.

Table 13. Configuration variables for the sample Roman Army ODA

Variable Value for sample Roman Army ODA
AGENTNAME set AGENTNAME=Roman
AGENT

UNIX: set AGENT = ${ProductDir}/DevelopmentKits/Odk/Samples/RomanArmy/ArmyODA.jar

WINDOWS: set AGENT = %ProductDir%\DevelopmentKits\Odk\Samples\RomanArmy\ArmyODA.jar

FILE_LOCATION

UNIX: set FILE_LOCATION = ${ProductDir}/DevelopmentKits/Samples/Odk/RomanArmy/RomanArmy.xml

WINDOWS: set FILE_LOCATION = %ProductDir%\DevelopmentKits\Samples\Odk\RomanArmy\RomanArmy.xml

Important

You must start the sample ODA before you try to connect to it through Business Object Wizard. Business Object Wizard can only locate those ODAs that have been started.

Using the ODA to create business object definitions

To start Business Object Wizard, do the following:

  1. Open Business Object Designer using a method listed in Table 9.
  2. Click File -> New Using ODA.

    Business Object Wizard displays the first dialog box, Select Agent, shown in Figure 34..

    Figure 34. Select Agent dialog box

  3. To select the ODA to which Business Object Wizard connects:
    1. Click the Find Agents button to display ODAs that are currently running (those that have been started with their startup scripts) in the Located agents list.
      Note:
      If Business Object Wizard does not locate your desired ODA, check the startup of the ODA.

      Business Object Wizard identifies each running ODA by the name specified for the AGENTNAME variable of its startup script or batch file. This sample ODA is named Roman.

    2. Select the desired ODA from the Located agents list. Business Object Wizard displays your selection as Agent's name. Alternatively, you can find the ODA by specifying its host name and port number.
  4. Click Next. Business Object Wizard attempts to connect to the specified ODA. If the ODA has been started, Business Object Wizard displays a status window as it connects to the ODA, as Figure 35 shows.

    Figure 35. Connecting to an ODA.

  5. After Business Object Wizard is connected to the ODA, it displays the second wizard dialog box, Configure Agent, which is shown in Figure 36. This dialog box displays the ODA configuration properties required to access the data source and initialize the ODA.

    Figure 36. Configure Agent dialog box

  6. Specify ODA configuration values or select a profile to display previously saved values. One of the required configuration areas for the ODA is to set up the logging and tracing. For more information, see Setting up logging and tracing.

    The first time you use a particular ODA, you specify values for each of its configuration properties. After doing so, you can save the property values in a named profile by clicking the Save button. The next time you use the same ODA, you can select the saved profile from the Select profile box. For more information, see "Entering values and saving a profile".

  7. Click Next. Business Object Wizard displays the third wizard dialog box, Select Source, which is shown in Figure 37. The Select Source dialog box displays the source-node hierarchy, which is a tree structure with the top-level objects at the top and child objects underneath. In the initial display, the Select Source dialog box usually displays only the top-level source nodes.
    Important

    If the ODA is unable to proceed when you click Next, verify that the ODA message file you have specified for the MessageFile configuration property exists in the ProgramDir\ODA\messages directory. For this sample ODA, the default name of this message file is RomanAgent.txt. For more information, see Specifying the ODA message file.

    Figure 37. Initial Select Source dialog box

    The nodes of the source-node hierarchy can be table names, business object names, schema, or functions, depending on the ODA's data source. This sample ODA generates nodes from objects within an XML file called RomanArmy.xml. Figure 37 shows the single top-level source node for the Roman general specified for the Army general configuration property (see Figure 36).

  8. Select objects in the source-code hierarchy for which you want the ODA to generate business object definitions. To select one source node, click on the node name. To select additional nodes, use the Ctrl key. In Figure 38, several source nodes have been expanded and three source nodes (which correspond to XML objects) have been selected.

    Figure 38. Select Source dialog box with source nodes expanded and selected

    To expand a source node to display its child nodes, do either of the following:

    Figure 39. Right-clicking a node

    Note:
    Business Object Wizard provides several other mechanisms to move through the nodes of the source-node hierarchy. For more information, see Moving through the source-node hierarchy.
  9. After you select the source nodes for which business object definitions are to be generated, click Next. Business Object Wizard displays the fourth wizard dialog box, Confirm Source, which is shown in Figure 40. This dialog box allows you to confirm your selection of source nodes. Selected source nodes are displayed in a bold font. In Figure 40, the source nodes for Cordius, Cicero, and Vulso are selected.

    Figure 40. Confirming the objects for which to generate business object definitions

    If your selection is not correct, click Back to return to the previous dialog box and make the necessary changes.

  10. When your selection is correct, click Next. Business Object Wizard displays the wizard's fifth screen, Generating Business Objects, which is shown in Figure 41. This screen informs you that the ODA is generating the business object definitions.

    Figure 41. Generating the definitions

    If the ODA needs additional information, Business Object Wizard prompts you for this information by displaying the BO Properties dialog box. However, this sample ODA does not require additional information. For more information about the BO Properties dialog box, see Providing additional information.

  11. After the ODA completes the generation of business object definitions, Business Object Wizard displays the final dialog box in the wizard, Save Business Objects, shown in Figure 42. This dialog box offers the following options to save the business object definitions that the ODA has generated:
    Important

    If the ODA generates a business object definition from a data-source object that does not identify a key element, this business object definition will not have a key attribute. Every business object must have at least one key. If the ODA might have generated business object definitions that do not include keys, you might want to choose the "Open the new BOs in separate windows" option instead of saving the business object definitions. Within Business Object Designer, you can verify that each business object definition has a key attribute, adding one if none exists. Business Object Designer does not allow you to save any business object definition that does not include a key.

    Figure 42. Saving the business object definition

    Click Finish to save the business object definitions or Cancel to exit without saving these definitions. In either case, Business Object Wizard disconnects from the ODA. This dialog box also provides the option to have Business Object Wizard shut down the ODA after it disconnects. If you no longer need to use the ODA, select this option.

    After you click Finish, if you have selected the option to save the business object definitions to a file, a browse window opens and allows you to specify the name of this file, where to save it, and what format to use (text file or ICS-specific format).

You have now successfully created business object definitions using an Object Discovery Agent.

Copyright IBM Corp. 1997, 2003