Using the i2 ODA in Business Object Designer

This section describes how to use the i2 ODA in Business Object Designer to generate business objects. For information on launching Business Object Designer, see the IBM WebSphere Business Integration Adapters Business Object Development Guide.

After you launch an ODA, you must launch Business Object Designer to configure and run it. Business Object Designer provides a wizard that guides you through six steps to generate a business object definition using an ODA. The six steps are as follows:

  1. Select the agent.
  2. Configure the agent properties.
  3. Expand the nodes and select the port types, operations, and input/output types.
  4. Confirm the selection, generate the wrapper business objects, and save.
  5. Complete the business object and generate the business objects for the types.
  6. Save the business object files.

Details for each step follow.

Steps for using the i2 ODA

Before you begin: You need to start the i2 Business Object Designer wizard.

  1. Open Business Object Designer.
  2. From the File menu, select New Using ODA....

    Result: Business Object Designer displays the first window in the wizard, named Select Agent.

Perform the following steps:

Select the agent

To select the ODA:

  1. Click Find Agents to display all registered or currently running ODAs in the Located agents field.
  2. Select the desired ODA from the displayed list.
    Note:
    The ODA for i2 has a default name of i2ODA. The agent name depends on the value of the i2 variable in the start_i2ODA.bat or start_i2ODA.sh file.

    Recommendation: When you run multiple instances of the ODA utility, you should change the default name by creating a separate batch file for each instance or by specifying a unique name in the AGENTNAME variable of each batch file.

    When multiple instances of the ODA are running on different machines, they are visible in the Business Object Designer by their i2 ODA values. If two ODAs have the same i2 value, then either of the ODAs can be used, with possibly undesirable results. You can assign unique names to such ODAs by prefixing the i2 name with the host machine name, or by using an ORB finder (for example, osfind) to locate existing CORBA object names on your network.

    Result: Business Object Designer displays your selected agent in the Agent's name field.

Configure agent properties

The first time Business Object Designer communicates with the i2 ODA, it prompts you to enter a set of initialization properties. You can save these properties in a named profile so that you do not need to re-enter them each time you use the i2 ODA. For information on specifying an ODA profile, see the Business Object Development Guide.

In addition to configuring these one-time properties, you need to configure properties to connect to the CIS agent and to define the tree nodes.

The following table describes the properties to configure.

Row number Property name Property type Description
1 DefaultBOPrefix String Text that is prepended to the name of the business object to make it unique.
Example: i2_BO
2 SchemaFileLocation String Path where the generated.xsd files are stored. This is mandatory; you must specify the path to store the schema files.
3 MessageFile String Path to the error and message file. If the file is not specified, the error messages from the ODA are not displayed. The i2 ODA displays the file name according to the naming convention.
Example: If the agent is named i2ODA, the value of the
message file property displays as i2ODAAgent.txt.
4 CISAgentHostName String Host name of the CIS agent, it is specified if the CIS agent is running on a remote machine.

You can also configure several optional parameters for the agent when it starts up.



Expand nodes and select port types, operations, and input/output types/formats

The i2 ODA uses the properties you configured in the preceding step to connect to the specified i2 application. Business Object Designer displays the metadata information about the registered ports, operations for each port, and the input and output types for each operation as a tree structure. You can expand the tree nodes for the ports and operations by right-clicking on a node. The type node is the leaf node of the tree, so it is not expandable.

A distinction is made between "Types" and "Formats" when dealing with the input and output values for an operation. When displaying the input and output business objects for an operation, if it is a "Format" that will be displayed instead of a "Type," it will display as "Output Format" instead of "Output Type".

Note:
In this document, when we say "Type" we mean "Type" or "Format".

The following diagram shows a tree view with expanded nodes.



Result: The i2 ODA will create the schema file for the chosen type. The schema files form the input for the XML schema ODA to generate the corresponding business objects. The XML schema file name follows the naming convention, input/output_operation_type.

Example: For the persistOrder operation, both the input type and output type is Order, but the formats for the two are different. The i2 ODA validates these and generates different schema files for the input and output types:

The schema files are stored in the directory specified by the SchemaFileLocation property for the ODA. The i2 ODA checks the schema location for the existence of the schema prior to creating the new one. If there already exists an xsd for the type, the i2 ODA does not duplicate the schema.

Confirm selection, generate wrapper business object, and save

  1. Confirm the operations you have selected for the i2 ODA to generate wrapper business objects.

    Result: The i2 ODA creates a wrapper business object to represent the operation with the chosen port type. Each operation has one wrapper business object. The input and output types of the operation form the attributes of this wrapper business object, with the operation as the verb. The port type becomes the application-specific information for this business object.

    The name of the wrapper business object is DefaultBOPrefix_operation. The wrapper business object contains:

    Example: The wrapper BO for the operation persistOrder is i2BO_persistOrder.



  2. Save the wrapper business object to a file. Saving it to the InterChange Server will fail because the corresponding dependent attribute business objects have not yet been created by the XML ODA schema.

    Guideline: When you save the business objects into a file in this step, the current Business Object Designer wizard looks at the machine where the agent is running. Another pop-up window prompts you for a location to save the generated wrapper business objects.

Complete the business object and generate the business objects for the types

  1. Check the property values that Business Object Designer displays in the BO Properties window. If you are satisfied with the value you previously entered in the Configure Agent window (for example, for DefaultBOPrefix), you do not need to change the value here.

  2. Be sure the XML schema ODA agent is running.
    1. The XML schema ODA reads the schema files previously saved to the SchemaFileLocation and generates the business objects for the input and output types.

    2. Save these business objects to the same directory as the wrapper business objects.

      Guideline: Remember to run the XML ODA on the schema files in the directory you specified when running the ODA. This will generate the child business objects for the wrapper business object that you generated. When generating child objects from the schema, use the following values for the XML ODA properties:

      • BOPrefix--This should be the same prefix used during the wrapper business object generation.
      • TopLevel--This should be prefix_in/out_operation_type.
      • Root--This should always default to CISDocument.

      BOPrefix for the XML schema ODA should be the same as the BOPrefix for the i2 ODA.

      The following diagram shows the business object that the XML schema ODA generates for i2_order.xsd. The XML data handler uses the combination of the element next to CISDocument and BOPrefix to get the business object name.



Note:
The inclusion of an <xsd:any minOccurs="0" maxOccurs="unbounded" namespace="##any" processContents=skip"/> tag, will no longer cause the business object generation to fail. For more information see the Data Handler Guide.

Save the business object files

Now that all the required business objects are generated, you need to save them to the InterChange Server for use by the collaborations. Use the Business Object Designer utility to copy the business objects to the server. You can concatenate the files together into a single file and copy them to the server.

Guideline: Be sure to run the XML schema ODA prior to saving the wrapper business objects to the server.

Example:

Property Value
FileName D:\i2\odaschema\i2persist_in_persistOrder_Order_Order.xsd
Root CISDocument
TopLevel in_persistOrder_Order
BOSelection false
BOPrefix i2persist
Doctypeor SchemaLocation true
TraceFileName XMLODAtrace.txt
TraceLevel 5
MessageFile XMLODAAgent.txt

At this stage, you can decide whether to run different operations on different instances. You can clone the MO_Instance and set a default value for the instanceId on these. You will need to replace the default MO_Instance with the newly created ones in the wrapper business objects for the operations.

Copyright IBM Corp. 1997, 2003