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 an ODA, see Developing an Object Discovery Agent.
To configure and run the ODA, use Business Object Wizard within Business Object Designer. Business Object Wizard is a graphical user inferface to ODAs, as well as managing the discovery and content-generation process. This section provides the following information:
Before you run an ODA, verify that the following steps have occurred:
For the ODA to launch, 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 launch 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 10 are correct.
Table 10. 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.
You can launch 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 Business Object Wizard within Business Object Designer. Business Object Wizard locates each ODA by the name specified in the AGENTNAME variable of each script or batch file.
Once you launch the ODA, you must launch Business Object Designer to configure and run it. For information on the ways to launch Business Object Designer, see Launching 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:
Business Object Wizard begins execution with Step 1 and displays the first
dialog in the wizard,
Select Agent. Table 11 summarizes the steps of Business Object Wizard.
Table 11. Steps of Business Object Wizard
Execution 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.
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 using this sample ODA.
This section includes the following tasks:
The sample ODA and the file to run it are located in the
DevelopmentKits\Odk\Samples directory under 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 |
---|---|
UNIX, AIX | start_Agent4.sh |
Windows | start_Agent4.bat |
Because the sample Roman Army ODA provides five versions of itself, all startup scripts call a single 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 launch 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 launched. |
To start Business Object Wizard, do the following:
Business Object Designer invokes Business Object Wizard, which displays the first dialog in the wizard, Select Agent, which is shown in Figure 37.
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.
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".
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 40. Initial Select Source dialog.
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 40 shows the single top-level source node for the Roman general specified for the Army general configuration property (see Figure 39).
Figure 41. Select Source dialog with source nodes expanded and selected.
To expand a source node to display its children, do either of the following:
Figure 42. Context Menu for a node.
To expand the selected node, click the "Retrieve all items" menu item. Business Object Wizard displays the next level of source nodes: the child nodes for the expanded parent node. To open lower levels, repeat this process.
Figure 43. Confirming the objects for which to generate business object definitions.
If your selection is not correct, click Back to return to the previous dialog and make the necessary changes.
Figure 44. Generating the definitions.
If the ODA needs additional information, Business Object Wizard prompts you for this information by displaying the BO Properties dialog. However, this sample ODA does not require additional information. Therefore, this dialog does not display. For more information about the BO Properties dialog, see Providing additional information.
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 45. 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 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, click this option.
After you click Finish, if you have told Business Object Wizard to save the business object definitions to a file, Business Object Wizard provides a browse window that 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.
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:
Business Object Wizard saves the profile under the following directory:
C:\Documents and Settings\All Users\Application Data\CrossWorlds\ BusObjDesigner\profiles.bod
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 of Business Object Wizard. Business Object
Wizard always provides the standard
configuration properties (shown in Table 14) for an ODA.
Table 14. 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". |
This section provides the following information:
Figure 46 shows the Configure Agent dialog in Business Object Wizard, in which you specify the name of the trace file and the trace level.
Figure 46. Specifying tracing information.
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 runtime 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.
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.
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 15 lists trace levels and their associated behavior.
For information on how to generate trace messages within the ODA, see Handling trace and error messages.
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 might run in.
By default, the ODA runtime 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
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.
Within the Select Source dialog, Business Object Wizard provides the following mechanisms for moving through the nodes of the source-node hierarchy:
The ways to expand a source node given in step 8 describe how to display all children of an expandable node. To limit which objects are displayed, you can use either of the following options from the context menu for a node name (see Figure 42):
The Apply Filter menu item allows you to specify a filter, which can limit which of the currently selected source nodes displays. When you click this menu item, Business Object Wizard displays the " Apply filter to node" dialog, as shown in Figure 47.
Figure 47. 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 children of the parent node for those whose names match the filter text. When it expands this parent node, it displays only those children whose names match this text.
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 47 to the Uulius node ("A*"), Business Object Wizard displays this node as shown in Figure 48 when you expand the node.
Figure 48. Filtered node after expansion
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 clicking the "Apply parent's filter" menu item from the node's context menu. If you used the "Retrieve all items" menu item, the parent's filter is applied to all elements.
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 the "Search for items" menu item, Business Object Wizard displays the " Enter a Search Pattern" dialog. Figure 49 illustrates this dialog.
Figure 49. Specifying a search pattern to limit retrieval results
The Enter a Search Pattern dialog provides a description of the search criteria that your search pattern can use. In Figure 49, the text in this dialog 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 children of the parent node whose names match the search pattern. When it expands this parent node, it displays only those children whose names match this pattern.
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. Business Object Wizard displays the Object Path dialog, shown in Figure 50, in which you specify the path.
Figure 50. Specifying an object's path.
You specify the object path as the fully qualified path of the source node (from the top-level parent down to the desired node). Node names within this path are separated with a colon (:).
To associate an operating-system file with the current node of the source-node hierarchy, click the "Associate files" menu item from the context menu for a node name (see Figure 51). 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).
Figure 51. Associating a file with a source node
When you click the "Associate files" menu item, Business Object Wizard displays the Open window shown in Figure 52. From this window, you can browse the file structure and choose the file to associate with the current node.
Figure 52. Open window for selecting the file to associate
Once you have selected the file to associate with the source node, click Open. When Business Object Wizard returns control to the Select Source dialog, the file you selected now displays under the source node with which it is associated, as Figure 53 shows.
Figure 53. File associated with a source node
In Step 5, Generating Business Objects, if the ODA needs additional information, Business Object Wizard prompts you for this information by displaying the BO Properties dialog, as shown in Figure 54.
Figure 54. Providing additional information.
After you provide all required information in the BO Properties dialog, click OK. The ODA continues with its generation of business object definitions.
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 launch each ODA from within Business Object Wizard.
To run multiple Object Discovery Agents simultaneously in Business Object Designer, do the following:
Business Object Designer invokes Business Object Wizard, which displays the first dialog in the wizard, Select Agent (see Figure 37).
Business Object Wizard displays a second instance of the Select Agent dialog.
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: