This section describes how to use SAPODA in Business Object Designer to generate business object definitions. For information on launching Business Object Designer, see the IBM WebSphere InterChange Server Business Object Development Guide.
After you launch an ODA, you must launch Business Object Designer to configure and run it. There are six steps in Business Object Designer to generate a business object definition using an ODA. Business Object Designer provides a wizard that guides you through each of these steps.
After starting the ODA, do the following to start the wizard:
Business Object Designer displays the first window in the wizard, named Select Agent. Figure 5 illustrates this window.
To select, configure, and run the ODA, follow these steps:
Figure 5 illustrates the first dialog box in Business Object Designer's six-step wizard. From this window, select the ODA to run.
To select the ODA:
The first time Business Object Designer communicates with SAPODA, it prompts you to enter a set of initialization properties as shown in Figure 6. You can save these properties in a named profile so that you do not need to re-enter them each time you use SAPODA. For information on specifying an ODA profile, see the IBM WebSphere Business Object Development Guide.
Figure 6. Configuring agent properties
Configure the SAPODA properties described in Table 5..
Property name | Property type | Description |
---|---|---|
UserName | String |
SAP logon user name (not required when generating a definition only from an
extracted IDoc definition file)
|
Password | String |
SAP logon password (not required when generating a definition only from an
extracted IDoc definition file)
|
Client | String |
SAP logon client number (not required when generating a definition only
from an extracted IDoc definition file)
|
Language | String |
SAP logon language (not required when generating a definition only from an
extracted IDoc definition file). Default is E for
English.
|
SystemNumber | String |
SAP system number (not required when generating a definition only from an
extracted IDoc definition file)
|
ASHostName | String |
Host name of the SAP application server (not required when generating a
definition only from an extracted IDoc definition file)
|
RFCTrace | True/False boolean |
RFC tracing for the SAP system. The default value is
False.
|
DefaultBOPrefix | String | Text that is prepended to the name of the business object to make it
unique. sap_ is the default value.
You can change this later, if required, when Business Object Designer
prompts you for business object specific properties.
|
MaximumHits | String | Maximum number of objects returned during a node search. For more
information, see Expand nodes and select objects.
The possible values that you can select from the drop-down list are
100 (default) and 50.
|
TraceFileName | String | Name of the trace file. If the file does not exist, SAPODA creates
it in the \ODA\SAP directory. If the file already exists,
SAPODA appends to it.
SAPODA names the file according to the naming convention. For example, if the agent is named SAPODA, it generates a trace file named SAPODAtrace.txt. Use this property to specify a different name for this file. Note: The Configure Agent screen does not display this
property if you use the deployment descriptor odk_dd.xml
file
that exists in the ODA root directory.
|
TraceLevel | Integer | Level of tracing enabled for SAPODA.
For more information on tracing, see Working with error and trace message files. Note: The Configure Agent screen does not display this
property if you use the deployment descriptor odk_dd.xml
file that exists in the ODA root directory.
|
MessageFile | String | Name of the error and message file.
SAPODA names the file according to the naming convention. For example, if the agent is named SAPODA, it names the message file SAPODAAgent.txt. For more information, see Working with error and trace message files. Important: The error and message file must be located in the \ODA\messages directory. Use this property to verify or specify an existing file. Note: The Configure Agent screen does not display this
property if you use the deployment descriptor odk_dd.xml
file that exists in the ODA root directory.
|
ResultSet | True/False boolean | When set to True, SAPODA generates a wrapper business object
for Information Integrator support.
If you do not want to generate ResultSet objects, set to the default value of False. |
File destination | Directory | Directory where ODA-generated files (business objects and class files)
are stored. Note that you can explicitly save business objects to a
different directory after the objects have been generated and placed in this
directory.
The default is the Windows default system temp directory. It is recommended that you change the default setting to the \connectors\SAP\utilities\generatedfiles directory. Note: If running SAPODA on the same machine as Business
Object Designer, do not use the directory ODA\SAP as your File
destination. Business Object Designer uses this directory as a
temporary location for remote ODAs.
|
After you configure all properties for SAPODA, Business Object Designer displays a tree with the following the initial nodes:
The nodes whose names are preceded by a plus sign (+) are expandable. Click on them to display more nodes or leaves. SAPODA generates business object definitions only from leaves.
Figure 7 illustrates this dialog box as originally displayed and with some nodes expanded.
Figure 7. Tree with expanded nodes
When a leaf's name is displayed in bold type, you can select the leaf as the basis for its business object to be generated. Use standard Windows procedures to select multiple leaves. In other words, depress the CTRL key while you use the mouse to select multiple leaves.
SAPODA uses a polymorphic node type that allows you to associate a flat file with a node. Initially the node displays without any leaves. You can browse a file system and select files to add to that node. The node is called polymorphic because its nature changes from a leaf to a branch when you associate it to one or more files.
Note that if you expand the RFC node, the following message (Figure 8) appears indicating that search results in RFC nodes are cached . This caching service provides a smaller number of leaf nodes, depending on the search criteria, and thus enables SAPODA to generate ResultSet and BAPI transaction business objects more efficiently. Search results are sorted and then displayed. The caching service runs in the background whenever you start SAPODA and the cached searches are purged when you end the session. The number of search results that can be cached is determined by the value of the MaximumHits property set in the Configure agent properties window, shown in Figure 6.
Figure 8. Caching notification
Figure 9 illustrates two ways of limiting the number of leaves that Business Object Designer returns:
After you have selected all desired leaves for object generation, click the Next button. For information on how to filter the objects returned, see the Business Object Development Guide.
After you identify all the objects to be associated with generated business object definitions, Business Object Designer displays the dialog box with only the selected leaves and their node paths. Figure 10 illustrates this dialog box.
Figure 10. Confirming selection of nodes and leaves
This window provides the following options:
After you confirm the selected objects, the next dialog box informs you that Business Object Designer is generating the definitions.
Figure 11 illustrates this dialog box.
Figure 11. Generating the definition
SAPODA prompts for additional information. The type of the top-level node (IDoc types, BOR, RFC, or Dynamic Definitions) determines:
SAPODA displays the BO Properties window to enable you to specify information required for business objects based on IDoc types. The properties displayed in this window differ depending on the source of the IDoc (an extracted file or a definition in the SAP system) and whether the definition is being defined for the ABAP Extension Module. This section describes the following topics:
Regardless of whether SAPODA is generating the business object definition from an IDoc file or an IDoc defined in the SAP system, the BO Properties window for an IDoc type allows you to specify or change:
The prefix is text prepended to the name of the business object to make it unique. If you are satisfied with the value you entered for the DefaultBOPrefix property in the Configure Agent window (Figure 6), you do not need to change the value here.
The module type choices are ALE or Extension. Because the ALE and the ABAP Extension Modules have different requirements for their business object definitions, it is important to specify which module will be using the business object.
Generate the attribute name from either the SAP field name or the SAP field description, the default being the SAP field description.
In addition to the prefix and module properties, the BO properties window representing an IDoc defined in the SAP system also displays the Release property. You can use this property to identify an earlier version of the IDoc type.
Figure 12 illustrates the two versions of the BO properties window, one for an extracted IDoc Type definition file and one for an IDoc defined in the SAP system.
Figure 12. Providing additional information for an IDoc type business object
If you select Extension as the module type, SAPODA prompts whether you want to enter function module names for any of the default verbs.
By default, when generating a definition for the ABAP Extension Module, SAPODA specifies the following text for verb application-specific information at the business object level of the top-level business object:
:/CWLD/IDOC_HANDLER
If you already know the function module names to pass to the ABAP handler, select Yes at this prompt. SAPODA displays the window illustrated in Figure 13..
Figure 13. Specifying function modules for the ABAP handler
Figure 13 illustrates a BO Properties window in which two function modules have been specified.
After you save the business object definition, the General tab in Business Object Designer displays the required application-specific information at the business object level of the topmost business object. Figure 14 illustrates such a window with the two specified function modules.
Figure 14. Specifying the ABAP handler in Business Object Designer
For more information about the ABAP handler, see Business object data routing to ABAP handlers.. For more information about application-specific information required by the ABAP Extension Module, see Developing business object definitions using SAPODA..
SAPODA creates the following types of objects:
When the ResultSet property on the Configure Agent window is set to False, as illustrated in Figure 6, you can use SAPODA to create a single BAPI transaction business objects or a BAPI transaction business object that contains multiple BAPI calls. This section provides details about business objects for Single BAPI calls.
For details about creating business objects for BAPI transactions, see BAPI transaction business objects. For details about creating business objects for ResultSets, see ResultSet business objects.
There are two BO Properties windows for a single BAPI object of BOR or RFC type. The properties displayed in the first window allow you to specify or change:
After you click OK to move forward from the first BO Properties window, SAPODA gives you the opportunity to reduce the size of the generated definition. You are prompted whether you want to remove from the definition any attributes that represent optional parameters. This prompt displays only if there are optional parameters to remove. Reducing the size of the definition can enhance performance later when the connector processes instances of the business object.
Figure 15 illustrates the properties displayed for a BOR or RFC-type object and the prompt that displays after you click OK. Note that this prompt appears for as many individual BAPI calls you select to create single BAPI call objects.
Figure 15. Providing additional information for BOR or RFC business objects
If you click Yes in the prompt illustrated above, the second BO Properties window displays. You can specify removal of each optional parameter of a BAPI/RFC interface by changing its Value from Yes (include a corresponding attribute in the generated definition) to No (do not include an attribute).
If you click No in the prompt illustrated above, the final wizard displays. For more information, see Save the definition.
Figure 16 Illustrates the second BO properties window.
Figure 16. Specifying attributes for removal from the definition
In addition to the specifications you provide in SAPODA, when you create a definition for the RFC Server Module, you may want to modify application-specific information after you save the business object definition. For more information, see Developing business objects for the RFC Server Module.
When the ResultSet property on the Configure Agent window is set to False, as illustrated in Figure 6, you can use SAPODA to create BAPI transaction business objects. BAPI transaction business objects contain multiple BAPI business objects.
With the ResultSet property on the Configure Agent window set to False, click Next on this window to proceed to the caching notification window (Figure 27) and then click OK.
Figure 17. Caching notification
Figure 18 illustrates the next window that appears, which allows you to specify the criteria that SAPODA will use to search for and display BAPI calls. For the example used in this section, the criteria is all BAPI calls starting with the text "BAPI_SALESORDER."
Figure 18. Enter a Search Pattern
After you specify the search criteria on the Enter a Search Pattern window, click OK to set the criteria. Figure 29 illustrates the search results tree with the RFC node expanded. On this window, select the BAPI calls that SAPODA will use to create the attributes of the BAPI transaction business object. In this example, the BAPI calls selected are BAPI_SALESORDER_CHANGE and BAPI_SALESORDER_CONFIRMDELVRY.
Figure 19. Search results tree expanded for RFC node
Click Next to proceed to the confirmation window, illustrated in Figure 20. The two BAPI calls selected in Figure 19 are listed.
Figure 20. Confirm source nodes for BAPI calls in the transaction
Click Next on this screen. A message window appears notifying you that you have selected more than one BAPI call. Click Yes to indicate that your intention is to create a BAPI transaction business object from these multiple BAPI calls.
Figure 21. Multiple BAPI call selection message
The next screen allows you to apply a prefix and a name to the BAPI transaction object. In this example, the prefix entered is sap_, and the name for the transaction object is salesorder_txn. The UseFieldName property determines whether the attribute name will be generated using the field name in SAP or the field description.
Figure 22. Assign a prefix and business object name to the transaction
Next, indicate the order in which the selected BAPI calls should be executed when the transaction object is processed. In this example, the BAPI_SALESORDER_CHANGE call is executed first, followed by the BAPI_SALESORDER_CONFIRMDELVRY call. You can apply a COMMITafter any BAPI you wish to commit within the transaction. SAPODA assumes a COMMIT as the final step of the transaction.
Figure 23. Assign a BAPI call sequence within the BAPI transaction object
The following message appears for each BAPI call in the sequence that has optional parameters. Figure 24 illustrates this message for the first BAPI call in the sequence (BAPI_SALESORDER_CHANGE).
Figure 24. Optional BAPI call parameters message
Click Yes to pick and choose which optional parameters you want to add as attributes of the individual BAPI business object that will be contained within the BAPI transaction object. If you click No, all the optional parameters will be applied as attributes of the individual BAPI object within the BAPI transaction object.
After you have created BAPI object attributes for each BAPI call within the BAPI transaction object, the Business Object wizard displays the object tree of the BAPI transaction object. Figure 25 illustrates the Attributes tab for the sap_salesorder_txn business object created in this example.
Figure 25. Attributes tab for the sap_salesorder_txn business object
Notice the two BAPI call attributes: sap_salesorder_change_txn and sap_salesorder_confirmdelvry_txn. Each of these attributes contains a single BAPI call object within the BAPI transaction object wrapper. The sap_salesorder_change_txn attribute contains a business object that corresponds to the BAPI_SALESORDER_CHANGE call, which is executed first in the transaction flow (as specified in Figure 23). The sap_salesorder_confirmdelvry_txn attribute contains a business object that corresponds to the BAPI_SALESORDER_CONFIRMDELVRY BAPI call. Notice that the attributes have the suffix _txn, added by SAPODA. This suffix ensures that business objects created in previous versions of the connector are not overwritten by new business objects that might have the same name.
When the ResultSet property on the Configure Agent window is set to True, as illustrated in Figure 26, SAPODA creates top-level ResultSet business objects. ResultSet business objects enable Information Integrator support for DB2.
Figure 26. Configure Agent window with ResultSet property set to True
Click Next on the Configure Agent window and then click OK on the caching notification window (Figure 27).
Figure 27. Caching notification
The next window in the wizard allows you to specify the criteria that SAPODA will use to search for and display BAPI calls. In this example, the asterisk, which is a wildcard, indicates that the criteria is all BAPI calls starting with the text "BAPI_CUSTOMER_GET."
Figure 28. Search criteria for ResultSets
Click OK to set the criteria. Figure 29 illustrates the search results tree with the RFC node expanded. On this window, select the BAPI calls that SAPODA will use to create the attributes of the ResultSet business object.
Figure 29. Search results tree expanded for RFC node
A ResultSet object has two attributes: Query (of type query object), and Result (of type result object). The Query attribute is typically generated from the GETLIST BAPI call, while the Result attribute is generated from GETDETAIL BAPI call.
Therefore, as Figure 29 illustrates, you select the corresponding BAPI calls, in this case BAPI_CUSTOMER_GETDETAIL and BAPI_CUSTOMER_GETLIST, from the expanded RFC node. Since the ResultSet property on the Configure Agent window is set to True, as illustrated in Figure 26, you are only permitted to select two BAPI calls.
Click Next to proceed to the confirmation window, illustrated in Figure 30, which allows you to confirm the source BAPI calls for the business object's attributes.
Figure 30. Confirm source nodes for attributes
As Figure 31 illustrates, the Business Object wizard requires you to specify the business object name prefix (in this example, sap_) and the name of the BAPI ResultSet object (in this example, customer_rs) that SAPODA will apply to the business object. The UseFieldName property determines whether the attribute name will be generated using the field name in SAP or the field description.
Figure 31. Provide business object name information
The Business Object wizard also requires you to indicate which BAPI call that you selected in Figure 29 should be used for the Query attribute. From the drop-down list, select the GETLIST BAPI call, as illustrated in Figure 32. SAPODA automatically treats the other selected call as the Result attribute of the ResultSet object.
Figure 32. Specify the Query attribute of the business object
Click OK to proceed to the next window, on which you specify the Query parameter (primary key) of the Query BAPI you selected in Figure 32. In this example, the BAPI call is GETLIST.
Figure 33. Select the primary key
If on the previous window, you chose a value that is a table/structure (identified by T|S), the window that appears next allows you to select a specific field on the table/structure as the primary key. In this example, the field selected is CUSTOMER.
Figure 34. Select a field on the table/structure
A message window appears indicating the full path of the Query parameter, as illustrated in Figure 35. The path includes the BAPI call parameters selected in the previous two windows, in this example BAPICUSTOMER_ADDRESSDATA and CUSTOMER.
Figure 35. Notification of Query attribute name
You must also specify the foreign key for the ResultSet object, as illustrated in Figure 36. The foreign key establishes the relationship between the Query attribute and Result attribute of the ResultSet object.
Figure 36. Select the foreign key
The Business Object wizard provides a message confirming the full path to the foreign key, in this case BAPI_CUSTOMER_GETDETAIL.CUSTOMERNO, as illustrated in Figure 37.
Figure 37. Foreign key path confirmation
The following window indicates that the GETLIST BAPI has optional parameters and that you can pick and choose from these optional parameters to create corresponding attributes on the business object. Choosing No, as in this example, means that the wizard generates business object attributes for all the parameters.
Figure 38. Optional parameters notification for the GETLIST BAPI
The following screen, illustrated in Figure 39, allows you to set property values for the ResultSet object.
Figure 39. Set property values for the ResultSet object.
The following window indicates that the GETDETAIL BAPI has optional parameters and that you can pick and choose from these optional parameters to create corresponding attributes on the business object. Choosing No, as in this example, means that the wizard generates business object attributes for all the parameters.
Figure 40. Optional parameters notification for the GETDETAIL BAPI
Figure 41 illustrates the Attributes tab in Business Object Designer, which lists the two attributes, BAPI_Query and BAPI_Result, of the ResultSet business object. You can expand the business object tree to display the hierarchy of each attribute. Notice that the attributes have the suffix _rs, added by SAPODA. This suffix ensures that business objects created in previous versions of the connector are not overwritten by new business objects that might have the same name.
Figure 41. Attributes tab of the ResultSet object
There are two BO Properties window for an HDR table-based object. The property displayed in the first window allows you to specify or change the business object's prefix. If you are satisfied with the value you entered for the DefaultBOPrefix property in the Configure Agent window (Figure 6), you do not need to change the value here.
Figure 42 Illustrates this window.
Figure 42. Providing additional information for an HDR business object
In addition, only 512 bytes of information from a table can be
returned. When a table returns more than 512 bytes, you will be
presented with the dialog found in Figure 43.. Answering "No" returns attributes
(column descriptions) from the beginning of the table until the 512 byte
maximum is reached.
Answering "Yes" displays the second BO properties windows noted in Figure 44.. The length in bytes for each attribute is provided in the window description. You can specific the inclusion or exclusion of an attribute for the business object by toggling its value between "Yes" and "No."
Figure 44. Size and type of BO properties for an HDR business object
After you provide all required information in the BO Properties dialog box and click OK, Business Object Designer displays the final dialog box in the wizard. Here, you can save the definition to the server or to a file, or you can open the definition for editing in Business Object Designer. For more information, and to make further modifications, see the Business Object Development Guide.
Figure 45 Illustrates this dialog box.