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 for the following reasons:

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

Single-cardinality relationship example

Figure 60 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 60. 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 61 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 61. Multiple-cardinality business object relationship

Figure 62 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 62. 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.

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:

    • If the SELECT statement returns one record, the connector continues processing the children and returns VALCHANGE (regardless of whether any attribute changed value).
    • If the SELECT statement returns no records, indicating that the top-level business object does not exist in the database, the connector returns BO_DOES_NOT_EXIST.
    • If the SELECT statement returns more than one record, the connector continues processing the children and returns VALCHANGE.
  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:

    • If the business object's definition specifies that the child is required, the retrieval must return a record. If not, the connector returns FAIL.
    • If the child is not required and the retrieval returns no records, indicating that the child does not exist in the application, the connector leaves the parent's attribute empty.

    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 Corporation 1997, 2004. All Rights Reserved.