Business object structure

The connector assumes that every individual business object is represented by one or more database tables, and that each simple attribute (that is, an attribute that represents a single value, such as a String or Integer or Date) within the business object is represented by a column in one of those tables. The following situations are valid:

WebSphere business objects for SAP can be flat or hierarchical. All the attributes of a flat business object are simple and represent a single value.

A hierarchical business object has attributes that represent a single child business object, an array of child business objects, or a combination of both. In turn, each child business object can contain a single child business object or an array of business objects, and so on.

Business object relationships

The Cardinality property of the attribute that represents the child or array determines the type of relationship between parent and child:

The connector does not process a single-cardinality relationship differently from a multiple-cardinality relationship. However, there is a structural difference in foreign-key relationships when database tables have single-cardinality or multiple-cardinality relationships. This difference is important when Advanced Outbound Wizard generates a business object definition from an SAP Display Transaction:

In each case, the foreign-key relationship between the parent and child business objects is specified by the application-specific information of the key attributes of the child business object. For more information, see "Business object attribute properties" and "Application-specific information for simple attributes".

The next sections describe the following relationships among business objects:

Single-cardinality relationship example

Figure 32 provides an example of a simple WebSphere business object developed to process customer objects in SAP. This example SAP_Customer has a single-cardinality relationship to the example address object that it contains (the addr_data[1] attribute has cardinality 1). The primary key attribute (address_id) in the child business object references a non-primary key (address_id) in the parent business object.

Figure 32. Example customer and address relationship

The following SELECT statements and their output illustrate retrieval of data from the tables represented by the business objects above:

SELECT * FROM KNA1
  
 KUNNR          NAME1          ADRNR
 -----          -------------  ----------
 10254          JOE'S PIZZA          2208
 10255          LARRY'S HARDWARE     2209
  
 SELECT * FROM ADRC
  
 ADDRNUMBER          CITY1          REGION
 ----------          ----           -----
 2208                BURLINGAME     CA
 2209                SAN FRANCISCO  CA
 

In the example above, each customer (Joe's Pizza and Larry's Hardware) has a single address. If the KUNNR and ADDRNUMBER columns are defined as primary key constraints for their respective tables, the above structure ensures that each customer can have only one associated address.

Note:
For the sake of simplicity, the illustrations in this document do not display the application-specific information used by the connector to determine the tables and fields in the SAP application's database.

Multiple-cardinality relationship example

Figure 33 illustrates a multiple-cardinality relationship. In the example, ID=ABC is the simple attribute with the parent's primary key, and child[n] is the attribute that represents the array of child business objects.

Figure 33. Multiple-cardinality business object relationship

Figure 34 provides an example of a different WebSphere business object developed to process customer objects in SAP. This example SAP_Customer has a multiple-cardinality relationship to the example sales view object that it contains (the sales_view_data[n] attribute has cardinality n). The primary key attribute (customer_id) in the child business object references the primary key (customer_id) in the parent business object.

Figure 34. Example customer and sales view relationship

The following SELECT statements and their output illustrate retrieval of data from each of these tables:

SELECT * FROM KNA1
  
 KUNNR          NAME1
 -----          -------------
 10254          JOE'S PIZZA
 10255          LARRY'S HARDWARE
  
 SELECT * FROM KNVV
  
 KUNNR          VKORG          VTWEG          SPART
 ----------     -----          -----          -----
 10254          EURP          01             12
 10255          EURP          01             09
 10255          USA           01             13
 10255          USA           01             14
 

In this example, Joe's Pizza has one associated sales view record, whereas Larry's Hardware has three associated sales view records. The above structure allows each customer to have zero or more associated sales view records.

Handling long data rows

SAP's RFC_READ_TABLE function limits data retrieval to 512 bytes per row of data. Many SAP tables have more than 512 bytes of data per row. However, most business objects represent a small subset of all the database fields. Therefore, the total length of all attributes in a business object rarely exceeds the 512 byte maximum.

In those cases that require the connector to retrieve more than 512 bytes of data from a single database table, the additional fields must be represented in separate single-cardinality child business objects. For example, if a business object must represent 1500 bytes of data from a single table, the top-level business object contains at least two single-cardinality child business objects. Neither the parent nor either child has attributes whose total length (that is, the sum of their maximum length) exceeds 512 bytes.

Note:
If a business object represents more than one database table, the total length of the values in the attributes that represent each table cannot exceed 512 bytes. However, this limit does not pertain to the total length of the values of all attributes. For example, if a business object represents data from the tables that store information about Customers and CustomerPartners, the value of those attributes representing Customers cannot exceed 512 bytes, and the value of those attributes representing CustomerPartners cannot exceed 512 bytes, but the combined value of these attributes can exceed 512 bytes.
Important:
When you use Advanced Outbound Wizard to create business object definitions, and it encounters an object that represents more than 512 bytes of data from a single table, it stops adding attributes to the child business object when the length exceeds 512 bytes. If your business processing requires a business object to represent more than 512 bytes of data from a single table, you must manually create the additional child business objects.

Business object verb processing

This section outlines the steps the connector takes to handle a business object request with the Retrieve verb. The connector processes hierarchical business objects recursively; that is, it performs the same steps for each child business object until it has processed all individual business objects.

Business object comparison

When processing a retrieval request from the integration broker, the connector tries to return a business object that matches the current database representation of that object. In other words:

Therefore, when the Hierarchical Dynamic Retrieve module receives a business object request with the Retrieve verb, it creates a response business object by recursively descending the entire object in the application and retrieving the current database representation. To perform the retrieval, the connector uses the specified key values in the top-level request business object. Therefore, the response business object, which contains all the children of that top-level parent, may have different values for simple attributes and different child business objects from the request business object.

For example, assume the integration broker passed the following SAP_Customer business object to the Hierarchical Dynamic Retrieve module:

If, in the current database representation, the array of SAP_SalesView child business objects contained by SAP_Customer 2345 does not include sales_org A, the connector's response business object does not contain that child. Moreover, if the current database representation of SAP_Customer 2345 includes sales_org D and sales_org E, the connector includes those children in the response business object. The business object that the SAP Hierarchical Dynamic Retrieve module returns to the integration broker at the end of retrieval is:

Note:
If the connector reads from multiple tables when creating a particular response business object, the business object does not match a single database object. Instead, it matches selected fields from the specified tables.

Retrieve operation

When retrieving a business object, the connector returns a status of either VALCHANGE if the operation was successful (regardless of whether the operation caused changes to the business object), or FAIL if the operation failed.

The connector performs the following steps when retrieving a hierarchical business object:

  1. Removes all child business objects from the top-level business object that it received from the integration broker.
  2. Calls the RFC_READ_TABLE function to retrieve the top-level business object from the database.

    The connector uses key values in the request business object to build the SELECT statement's WHERE clause. The result of the retrieval causes one of the following actions:

  3. Recursively retrieves all child business objects (single-cardinality and multiple-cardinality).

    The connector calls the RFC_READ_TABLE function, which uses the appropriate foreign-key values to build the SELECT statement's WHERE clause. The connector handles attributes marked as required in the following way:

    For each record returned, the connector performs the following actions:

    1. Creates a new individual business object of the correct type.
    2. Sets all of the current business object's attributes based on the values in the returned row.
    3. Recursively retrieves all of the current business object's children.

      Attention: If the retrieval of a single-cardinality child returns more than one record, the connector returns only the first record.

    4. Inserts the current business object with all of its children into the appropriate single-cardinality attribute or array attribute of the parent.
Note:
A business object can have attributes that do not correspond to any database column, such as placeholder attributes. During retrieval, the connector does not change such attributes in the top-level business object; they remain set to the values received from the integration broker. The application-specific information for these attributes must be blank.

Copyright IBM Corp. 1997, 2004