Using an Object Discovery Agent to create a business object definition

This section describes how to use an Object Discovery Agent (ODA) to generate business object definitions for application-specific business objects. An ODA is an optional component of an adapter. When you install a pre-defined adapter that has an ODA, its ODA is installed automatically. If you are developing a custom adapter and you want to use an ODA to create business object definitions, you can use the Object Discovery Agent Development Kit (ODK) to develop one. For more information about developing a custom ODA, see Developing an Object Discovery Agent.

To configure and run the ODA, use the Business Object Wizard in Business Object Designer. Business Object Wizard is a graphical user interface to ODAs that manages the discovery and content-generation process. This section provides the following information:

Before using an ODA

Before you run an ODA, verify that the following steps have occurred:

System startup files

For the ODA to start, you need to verify that your system has the required files for the ODA. When you install a pre-defined adapter that has an ODA, these ODA system startup files should be installed automatically. If you are developing a custom adapter with a custom ODA, these ODA system startup files should be created as part of the ODA development process. However, IBM recommends that you confirm that the startup script exists and is correct for your ODA:

Each ODA requires a startup script, which begins execution of the ODA. Before you start an ODA for the first time, you must make sure that the variables are correctly set within the startup script. Open for editing the shell (start_ODAname.sh) or batch (start_ODAname.bat) file and confirm that the values described in Table 12 are correct.

Table 12. ODA shell and batch file configuration variables

Variable Explanation Example
set AGENTNAME Name of the ODA set AGENTNAME=ODAname
set AGENT Name of the ODA's jar file

UNIX: set AGENT = ${ProductDir}/ODA/srcDataName/ODAname.jar

WINDOWS: set AGENT = %ProductDir%\ODA\srcDataName\ODAname.jar

set AGENTCLASS Name of the ODA's Java class set AGENTCLASS=com.ibm.oda.srcDataName.ODAname

For information on the ODA name (ODAname) and its source-data name (srcDataName), see Naming the ODA.

Starting the ODA

You can start an ODA with the startup script appropriate for your operating system.

UNIX

start_srcDataNameODA.sh
Windows

start_srcDataNameODA.bat

You configure and run the ODA using the Business Object Wizard in Business Object Designer. Business Object Wizard locates each ODA by the name specified in the AGENTNAME variable of each script or batch file.

Note:
For information on how to start multiple instances of the ODA, see Using multiple ODAs simultaneously.

Starting Business Object Designer

Once you start the ODA, you must open Business Object Designer to configure and run it. For information on the ways to open Business Object Designer, see Starting Business Object Designer. To run an ODA, Business Object Designer provides Business Object Wizard, which guides you through each step.

To start Business Object Wizard, do the following:

  1. Open Business Object Designer using one of the methods listed in Table 11.
  2. Click File > New Using ODA.

Business Object Wizard begins displays the first dialog box in the wizard, Select Agent. Table 13 summarizes the steps of Business Object Wizard.


Table 13. Steps of Business Object Wizard

Task Step in Business Object Wizard
1. Select the desired ODA Step 1: Select Agent
2. Obtain the configuration properties, including those that describe the data source to open. Step 2: Configure Agent
3. Obtain the source data for which the ODA generates the content. Step 3: Select Source
4. Confirm that the selected source nodes are those desired for content generation. Step 4: Confirm Source Nodes
5. Initiate the content-generation process. Step 5: Generating Business Objects


Business Object Properties
6. Save the business object definitions in a user-specified format. Step 6: Save Business Objects

For an example of how Business Object Wizard runs an ODA, see Using the sample ODA.

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

Table 14. 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 15. 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 15. 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 11.
  2. Click File > New Using ODA.

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

    Figure 36. Select Agent dialog box

    The figure shows the first dialog in the business object wizard as described in the task description.

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

    Figure 37. 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 38. This dialog box displays the ODA configuration properties required to access the data source and initialize the ODA.

    Figure 38. 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 39. 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 39. 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 39 shows the single top-level source node for the Roman general specified for the Army general configuration property (see Figure 38).

  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 40, several source nodes have been expanded and three source nodes (which correspond to XML objects) have been selected.

    Figure 40. 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 41. 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 42. This dialog box allows you to confirm your selection of source nodes. Selected source nodes are displayed in a bold font. In Figure 42, the source nodes for Cordius, Cicero, and Vulso are selected.

    Figure 42. 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 43. This screen informs you that the ODA is generating the business object definitions.

    Figure 43. 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 44. 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 44. 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.

Entering values and saving a profile

You can save a particular set of ODA configuration values in a profile so that they can be available for future uses of the ODA. To save a profile:

  1. On the Step 2, Configure Agent dialog box of the Business Object Wizard, click the New button under Profiles.
    Note:
    To base a profile on an existing one, locate the desired profile in the profile drop-down list. Do not click the New button.
  2. Enter a name for the profile in the Current list (see Figure 38 for an illustration).
    Note:
    If you are basing a profile on an existing one, overwrite the name of the existing profile in the profile drop-down list.
  3. Enter the desired configuration values in the Configure Agent table.
  4. Click the Save button.

    Business Object Wizard saves the profile under the following directory:

    C:\Documents and Settings\All Users\Application Data\CrossWorlds\
       BusObjDesigner\profiles.bod
    

Setting up logging and tracing

As part of the configuration of the ODA, you must set up the logging and tracing. You specify the logging and tracing information for an ODA in the Configure Agent dialog box of Business Object Wizard. Business Object Wizard always provides the standard configuration properties (shown in Table 16) for an ODA.

Table 16. Standard ODA configuration properties.

Property name Property type Description
TraceFileName
String Specifies the file into which the ODA writes trace information. For more information, see "Specifying the trace file and trace level".
TraceLevel


Integer Trace level enabled for the ODA. For more information, see "Specifying the trace file and trace level".
MessageFile
String Name of the ODA's error and message file. Use this property to verify or specify an existing file. For more information, see "Specifying the ODA message file".

Note:
The default values displayed in Business Object Designer for these properties come from the ODA deployment descriptor file. See Working with error and trace message files for more information.

This section provides the following information:

Specifying the trace file and trace level

Figure 45 shows the Configure Agent dialog box in Business Object Wizard, in which you specify the name of the trace file and the trace level.

Figure 45. Specifying tracing information

The figure highlights the tracefilename row and the tracelevel row in the configure agent dialog of the business object wizard.

Specifying a trace file

The TraceFileName configuration property specifies the name of the ODA's

trace file. This file is the destination for all trace and error messages that the ODA logs. By default, the ODA run time names the trace file according to the following naming convention:

ODAnametrace.txt

In the preceding line, ODAname is the name that uniquely identifies the ODA. For more information, see Naming the ODA. For example, if the ODA is named HTMLODA, it generates a trace file named HTMLODAtrace.txt.

Note:
Because the ODK API provides one method to log both trace and error messages, an ODA has only one file to hold both these kinds of messages. Therefore, although this file is called a trace file, it also contains any error messages that the ODA generates.

If the specified trace file does not exist, the ODA creates it in the ODA's runtime directory, which is the ODA\srcDataName subdirectory of the product directory. If the specified trace file already exists, the ODA appends to it. When configuring the ODA, you can use specify a different name for the trace file by resetting the TraceFileName property.

Setting the trace level

The TraceLevel configuration property specifies the ODA's system trace level. The ODA's trace method sends the specified message to the trace file when the message's trace level is less than or equal to this system trace level. Therefore, the system trace level determines the level of detail that the trace messages provide. Table 17 lists trace levels and their associated behavior.

Table 17.

Trace levels
Level Behavior
0 Writes error messages to the specified trace file.
1 Traces whenever a method is entered--useful for status messages and key information for each business object definition.
2 Traces the agent properties and the values received.
3
  • Traces the names of the business object.
  • Traces the business object properties and the values received.

4
  • Traces the spawning of all threads.
  • Traces a message whenever a method is entered and exited.

5
  • Indicates the initialization of the Object Discovery Agent and log the values retrieved for all the Object Discovery Agent properties.
  • Traces detailed status of each thread spawned by the Object Discovery Agent.
  • Traces the business object definition dump.

For information on how to generate trace messages within the ODA, see Handling trace and error messages.

Specifying the ODA message file

The MessageFile configuration property specifies the name of the ODA's message file. An ODA can store its error and trace messages in this ODA message file. It can then retrieve these messages by message number, instead of creating the message text itself. Isolating messages into the message file provides an easy way for ODA messages to be translated into the languages of the different locales the ODA can run in.

By default, the ODA run time names this message file according to the following naming convention:

ODAnameAgent.txt

In the preceding line, ODAname is the name that uniquely identifies the ODA. For more information, see Naming the ODA. For example, if the ODA is named HTMLODA, the value of the MessageFile property defaults to HTMLODAAgent.txt. The message file must reside in the following message-file directory:

ProductDir\ODA\messages
Important

If the specified message file does not exist or does not exist in the message-file directory, the ODA generates a runtime exception. You must ensure that the message file (which MessageFile specifies) exists before you continue with the execution of the ODA.

If the ODA uses a different message file, set the MessageFile property to specify a different name for the trace file.

If you are using a non-US English locale, Business Object Wizard automatically looks for an ODA message file that includes the name of the locale in the file name, as follows:

ODAnameAgent_locale.txt

where locale has the format "ll_TT", with ll as the two-character language name (in lowercase) and TT as the two-character country or territory name (in uppercase). For example, if the ODA named HTMLODA has its message file localized to the Japanese locale, its message file would have the name:

HTMLODAAgent_ja_JP.txt

Note:
When you are logged into a non-US English locale, you do not have to specify the non-US English name in the MessageFile property. For example, if you are using the HTML ODA, you set MessageFile to the US English file name (HTMLODAAgent.txt). If you are logged into a Japanese local, Business Object Wizard locates the correct message file for the Japanese locale: HTMLODAAgent_ja_JP.txt.

If you create multiple instances of the ODA script or batch file and provide a unique name for each represented ODA, you can have a message file for each ODA instance. For more information, see Using multiple ODAs simultaneously.

Moving through the source-node hierarchy

The Business Select Source dialog box in Business Object Wizard provides the following mechanisms for moving through the nodes of the source-node hierarchy:

Limiting display of child nodes

The ways to expand a source node given in step 8 describe how to display all child nodes of an expandable node. To limit which objects are displayed, you can use either of the following menu items when right-clicking a node name (see Figure 41):

Using a filter

The Apply Filter menu item allows you to specify a filter, which can limit which of the currently selected source nodes opens. When you click this menu item, Business Object Wizard displays the Apply filter to node dialog box, as shown in Figure 46.

Figure 46. Specifying a filter to limit results


In the filter text, you can use the asterisk (*) character as a wildcard (to represent zero or more matching characters). This wildcard character can appear in any position and in as many positions as required. For example, SAP*, *SAP, *SAP*, or *S*AP*.

When you click OK, Business Object Wizard searches the currently retrieved child nodes of the parent node for those whose names match the filter text. When it expands this parent node, it displays only those child nodes whose names match this text.

Important:
When Business Object Wizard receives a filter, it searches for matching child nodes of the parent node in the currently retrieved source node; that is, it does not search the data source for matching child nodes. To have Business Object Wizard search the data source, you can specify a search pattern. For more information, see Specifying a search pattern.

For example, in the sample Roman ODA, the Uulius node has four child nodes: Ares, Cronus, Atlas, and Metis. If you apply the filter in Figure 46 to the Uulius node ("A*"), Business Object Wizard displays this node as shown in Figure 47 when you expand the node.

Figure 47. Filtered node after expansion

The figure shows the hierarchy under Uulius expanded only showing Ares and Atlas.

If you specify a filter at the top of a node and then expand the node, you can apply the same filter to child objects by right-clicking on the node and clicking Apply parent's filter. If you click Retrieve all items menu item, the parent node filter is applied to all elements.

Specifying a search pattern

The Search for items menu item allows you to specify a search pattern, which can limit which source nodes Business Object Wizard selects from the data source. When you click Search for items, Business Object Wizard displays the Enter a Search Pattern dialog box. Figure 48 illustrates this dialog box.

Note:
An ODA must support the search-pattern feature for the Search for items menu item to be enabled. If this menu item is not available, the ODA does not support search patterns.

Figure 48. Specifying a search pattern to limit retrieval results


The Enter a Search Pattern dialog box provides a description of the search criteria that your search pattern can use. In Figure 48, the text in this dialog box specifies that the search pattern can consist of one letter. The ODA provides a customized description of the search criteria. Make sure that the search pattern you enter follows the described search criteria. Otherwise, the ODA throws an exception.

When you click OK, Business Object Wizard searches the data source for child nodes of the parent node whose names match the search pattern. When it expands this parent node, it displays only those child nodes whose names match this pattern.

Important:
When Business Object Wizard receives a search pattern, it searches for matching child nodes of the parent node in the data source; that is, it retrieves a new tree node from the data source. It does not simply search the currently retrieved tree node for matching child nodes. To have Business Object Wizard search the currently retrieved tree node, you can specify a filter. For more information, see Using a filter.

Specifying an object path

Instead of moving through the source-node hierarchy, you can specify an exact path for the desired object. To do so, click Use this object instead, at the upper right of the Select Source dialog box. Business Object Wizard displays the Object Path dialog box, shown in Figure 49, in which you specify the path.

Figure 49. Specifying an object's path.


You specify the object path as the fully qualified path of the source node (from the top-level parent node down to the desired node). Node names within this path are separated with a colon (:).

Associating an operating-system file

To associate an operating-system file with the current node of the source-node hierarchy, right-click on a node and click Associate files (see Figure 50). When you associate a file with a source node, the ODA uses the file as the source for that source node's data (instead of using the ODA's data source).

Note:
An ODA must support the associate-files feature for the Associate files menu item to be enabled. If this menu item is not available, the ODA does not support associating files with the current source node.

Figure 50. Associating a file with a source node

The figure shows the select source dialog of the business object wizard with the drop-down menu that results when you righ click on a source node.

When you click the Associate files menu item, Business Object Wizard displays the Open window shown in Figure 51. From this window, you can browse the file structure and choose the file to associate with the current node.

Figure 51. Open window for selecting the file to associate


After you have selected the file to associate with the source node, click Open. When Business Object Wizard returns control to the Select Source dialog box, the file you selected is displayed under the source node with which it is associated, as Figure 52 shows.

Figure 52. File associated with a source node


Providing additional information

In Step 5, Generating Business Objects, if the ODA needs additional information, the BO Properties dialog box opens, as shown in Figure 53..

Figure 53. Providing additional information.


Note:
If a cell in the BO Properties dialog box has multiple values, it appears to be empty when the dialog box first opens. Click the cell for a list of its values.

After you provide all required information in the BO Properties dialog box, click OK. The ODA continues with its generation of business object definitions.

Using multiple ODAs simultaneously

You can run multiple instances of an ODA either on the local host machine or a remote host machine. Each instance runs on a unique port. You can specify this port number when you start each ODA from within Business Object Wizard.

To run multiple Object Discovery Agents simultaneously in Business Object Designer, do the following:

  1. Start each Object Discovery Agent by running its start_ODAname.bat or start_ODAname.sh files.
  2. Open Business Object Designer.
  3. Click File > New Using ODA.

    The first dialog box in the Business Object Wizard, Select Agent, opens (see Figure 36).

  4. Click the Find Agents button to display currently running ODAs in the Located agents list. You can also find the ODA using its host name and port number.
  5. Select the first ODA from the displayed list. Your selection is listed as Agent's name.
  6. Click File > New Using ODA again.
  7. Click the Find Agents button to display currently running ODAs in the Located agents list, or find the ODA using its host name and port number.
  8. Select the second ODA from the displayed list.
  9. Proceed with the configuration of each ODA as described in step 4 of Using the ODA to create business object definitions.

If you create multiple instances of the ODA script or batch file and provide a unique name for each represented ODA, you can have a message file for each ODA instance. Alternatively, you can have differently named ODAs use the same message file. There are two ways to specify a valid message file:

Working with error and trace message files

By default, error and trace message files are located in the \ODA\messages, subdirectory under the product directory. These files use the following naming convention:

AgentNameAgent.txt

Where AgentName is the ODA to which the file belongs.

If you create multiple instances of the ODA script or batch file and provide a unique name for each represented ODA, you can have those instances use the same message file. Alternatively, you can specify different message files for each ODA instance by specifying file names in odk.dd.AgentName, which is the ODA deployment descriptor file installed with the ODA.

WBI Adapters contain a master ODA deployment descriptor located in \ODA\odk.dd.xml, that specifies the default message and trace file values. To specify different message files for different ODA instances, you can copy the master ODA deployment descriptor file to the ODA's directory and rename it to oda.dd.xml (for example, \ODA\XMLODA\oda.dd.xml). Edit this file to change the messagefile, tracefile, and tracelevel values accordingly. The master ODA deployment descriptor has the following format and default values:

<odk>
   <startup>
      <messagefile usestandard="true"></messagefile>
   </startup>
   <diagnostics>
      <tracefile usestandard="true"></tracefile>
      <tracelevel canoverride="true">1</tracelevel>
   </diagnostics>
</odk>

Business Object Designer assumes you name each file according to the naming convention. For example, if the AGENTNAME variable specifies XMLODA1, the tool assumes that the name of the associated message file is XMLODA1Agent.txt. Therefore, when Business Object Designer provides the file name for verification as part of ODA configuration, the file name is based on the ODA name. Verify that the default message file is named correctly, and correct it as necessary.

Important:
Failing to correctly specify the message file's name when you configure the ODA causes it to run without messages. For more information on specifying the message file name, see Specifying the ODA message file.

During the configuration process you specify:

Copyright IBM Corp. 1997, 2004