Business object structure

The WebSphere business object for SAP for the ALE Module is made up of a top-level parent wrapper object and two child objects: the control record object and the data record object. This section describes the following:

Illustration of business object structure

Figure 18 illustrates the structure of a WebSphere business object for the ALE Module.

Figure 18. Relationship of WebSphere business objects for SAP and an IDoc


Business object naming conventions

This section describes the following:

Standard naming conventions

The ALE Module requires its business objects to follow the naming conventions described in Table 23. SAPODA, which generates all but the control record business object, derives the business object and attribute names from the IDoc definition in accordance with these conventions.

Table 23. IBM WebSphere SAP business object naming conventions

IBM WebSphere Business Object or Attribute Name Type
Parent wrapper business object BOprefix_BasicIDocTypeNote: The illustrations in this chapter use SAP_ or sap_ as the business object prefix. You can specify your own meaningful prefix when you create your business object definitions. n/a
Control Record business object Control_record sap_idoccontrol
Data Record business object Data_record BOprefix_BasicIDocType_cwdata
Data Record child business object BOprefix_BasicIDocType_IDocSegmentName BOprefix_BasicIDocType_IDocSegmentName
Data Record attribute IDocFieldText String

Because WebSphere business integration system component names support only alphanumeric characters and the underscore character (_), SAPODA replaces special characters in the IDoc segment field descriptions with underscore characters in the business object definition. For example, SAPODA changes the spaces, parentheses, and periods in the following SAP description to underscores in the corresponding attribute name:

Partner function (e.g. sold-to party, ship-to party)

SAPODA represents the above description in the generated business object definition as:

Partner_function__e_g__sold_to_party__ship_to_party__ 

SAPODA guarantees that all attribute names in the business object definition are unique. If an IDoc has multiple fields with the same field name, then SAPODA adds a counter suffix to the generated attribute name.

You can modify attribute names at any time after you generate the business object. However, when you modify an attribute name, ensure that you do not modify its application-specific information. The connector uses this text to identify the IDoc attribute to which the attribute corresponds. For more information, see "Application-Specific Information in Simple Attributes".

Using IDoc extensions/types

You can generate a business object definition based on a custom IDoc type that has been created from the combination of a basic IDoc type and an Extension type. SAPODA names the parent wrapper business object that it generates in the following format:

sap_IDocType

Important:
When loading a business object definition for an IDoc extension into the repository, you might encounter conflicts if a business object definition for the basic IDoc Type already exists in the repository and its name matches the basic IDoc Type plus extension. You must manually resolve these conflicts.

Parent wrapper business object

The name of the parent wrapper business object is the basic IDoc type prefixed by a user-defined prefix followed by an underscore (_), for example sap_. The parent wrapper business object contains four attributes: Dummy_key, Control_record, Data_record, and TransactionId.

The Control_record and Data_record attributes represent single-cardinality child business objects.

The Type of the Control_record attribute is sap_idoccontrol, and this business object definition is provided with the ALE Module.

The Type of the Data_record attribute is BOprefix_BasicIDocType_cwdata. This business object definition contains one or more child business objects, depending on the IDoc segment definition of a basic IDoc type from the SAP application.

The existence of the TransactionId attribute determines whether the connector manages TIDs when processing service call requests. If you do not want TID management for request processing, you must manually remove this attribute from the generated business object.

The application-specific information of the parent wrapper business object indicates:

Syntax

The AppSpecificInfo property of the parent wrapper object has the following syntax:

BasicIDocType[,Pn=PartnerNumberOfRecipient[,Pt=PartnerTypeOfRecipient[,Pf=PartnerFunctionOfRecipient]]

Explanation of syntax

BasicIDocType
Specifies the basic IDoc type

Pn
Specifies the Partner number of the recipient

Pt
Specifies the Partner type of the recipient

Pf
Specifies the Partner function of the recipient

Example

AppSpecificInfo = ALEREQ01,Pn=ALESYS2,Pt=LS,Pf=EL

Control record business object

The ALE Module uses a generic control record business object definition for all IDocs. It contains a superset of attributes that are present in the 3.x version (SAP structure EDI_DC) and the 4.x version (SAP structure EDI_DC40) of the control record. The control record business object definition is provided with the ALE Module, and must be loaded into the business object repository. Use Business Object Designer to load the business object into the repository.

Note:
Alternatively, if InterChange Server (ICS) is the integration broker, you can use the repos_copy command. For more information on repos_copy, see the IBM CrossWorlds System Administration Guide.

Table 24 lists the simple attribute properties of the control record business object.

Table 24. Properties of simple attributes in the control record business object

Property name Description
Name The value of the Name property is the modified value of the TEXT field in the IDoc definition. SAPODA replaces special characters (such as periods, slashes, and spaces) with underscores so that the name contains only alphanumeric characters and the underscore character (_), as described in "Business object naming conventions"
Type Specifies the type of data. SAPODA sets the value to String.
MaxLength SAPODA derives the value of MaxLength from the LENGTH field in the IDoc definition.
IsKey SAPODA sets this property to true on the first attribute of a business object.
IsForeignKey SAPODA sets the value to false.
IsRequired The IsRequired property specifies whether an attribute must contain a value. SAPODA set this property to true only on the Name_of_table_structure attribute in the control record object.
AppSpecificInfo SAPODA derives the value from the NAME field in the IDoc definition.
DefaultValue Specifies the value to assign to this attribute if there is no run-time value. SAPODA does not set a value for this property.

Important:
Attributes set to either CxIgnore or CxBlank in the control record business object are interpreted as a blank space for the IDoc control record.

Data record business object

An IDoc definition file has information about the structure of the IDoc, the IDoc segment hierarchy, and the fields that make up the segments. SAPODA uses the IDoc as input to generate the data record business object and its child business objects. The number of children depends on the IDoc segment definition of the basic IDoc type from the SAP application.

The top level of the data record business object corresponds to the basic IDoc type. This top-level business object contains an attribute that represents a child business object or an array of child business objects (one for each IDoc segment). The structure and hierarchy of the child business objects match that of the IDoc segments in the basic IDoc type.

The cardinality of the attribute that represents child business objects depends on the value of the LOOPMAX field in the IDoc definition:

This section describes:

Attributes: Data record business object

Table 25 describes the properties of each simple attribute in the data record business object. SAPODA generates the properties described below.

Table 25. Simple attributes: Data record business object

Property name Description
Name The value of the Name property is the modified value of the TEXT field in the IDoc definition. SAPODA replaces special characters (such as periods, slashes, and spaces) with underscores so that the name contains only alphanumeric characters and the underscore character (_), as described in "Business object naming conventions".
Type Specifies the type of data. SAPODA sets the value to String.
MaxLength SAPODA derives the value of MaxLength from the LENGTH field in the IDoc definition.
IsKey SAPODA sets this property to true on the first attribute in each business object. For every other attribute, SAPODA sets the value to false.
IsForeignKey SAPODA sets the value to false.
IsRequired Specifies whether an attribute must contain a value. SAPODA sets the value to false.
AppSpecificInfo SAPODA sets the value of the AppSpecificInfo property to the value of the Name field in the IDoc definition prepended by the offset value and the + character; for example, for a segment field named SIGN with an offset of 40, it sets the following value for AppSpecificInfo: 40+SIGNFor more information, see "Application-Specific Information in Simple Attributes".
DefaultValue Specifies the value to assign to this attribute if there is no run-time value. SAPODA does not set a value for this property.

Important:
Simple attributes in the data record business object can have two special values: CxIgnore and CxBlank. Simple attributes set to CxIgnore or CxBlank are represented by blank spaces in the segment data string. SAP processes these attributes by placing one space character in the application field.

Table 26 describes the properties of each attribute in the data record business object that represents a child or array of child business objects. SAPODA generates the properties described below

Table 26. Attributes that represent child business objects

Property name Description
Name SAPODA sets the value of the name property to BOprefix_BasicIDocTypeIdocSegmentName; for example, SAP_E2ALER1001
Type SAPODA sets the value is the type of child business object to: BOprefix_BasicIDocTypeIdocSegmentName
ContainedObjectVersion SAPODA sets the value to 1.0.0.
Relationship SAPODA sets the value to containment.
IsKey SAPODA sets the value to false.
IsForeignKey SAPODA sets the value to false.
IsRequired The IsRequired property specifies whether a child business object must exist. SAPODA sets the value to false if the value of the STATUS field for the corresponding segment in the IDoc definition has a value of OPTIONAL. SAPODA sets this property to true if the STATUS field in the IDoc definition has a value of MANDATORY.
AppSpecificInfo The AppSpecificInfo property contains information on the hierarchy level and minimum and maximum number of allowed occurrences of a segment. For more information, see "Application-Specific Information in Attributes That Represent Children".
Cardinality If the value of the LOOPMAX field in the IDoc definition is 1, SAPODA sets the value to 1. If the value of LOOPMAX is greater than 1, SAPODA sets the value to n.

Application-specific information: Data record business object

This section describes how connector uses the value of the AppSpecificInfo property:

Application-specific information at the bhusiness-object level

The connector uses the value of the AppSpecificInfo property at the business-object level of the data record and each of its children to obtain the name of the associated Idoc and its segments:

Application-Specific Information in Simple Attributes

The connector uses the value of the AppSpecificInfo property of simple attributes to obtain the field name in SAP and its position (offset) in the data string.

The offset value is the position of the first character of the attribute value in the data string. The offset value is calculated by subtracting the value in the BYTE_FIRST value of the first field in the IDoc definition from the BYTE_FIRST value of the given attribute. This value is used with the MaxLength property to build the data string for the IDoc segment.

The syntax of the AppSpecificInfo property of simple attributes is:

OffsetNumber+IDocFieldName

For example, a segment field named SIGN with an offset of 40 has the following value for AppSpecificInfo:

40+SIGN

Application-Specific Information in Attributes That Represent Children

The connector uses the value of the AppSpecificInfo property of attributes that represent a child or array of child business objects to obtain information on the hierarchy level and minimum and maximum number of allowed occurrences of a segment. SAPODA sets the AppSpecificInfo property for these attributes by obtaining information from the LEVEL, LOOPMIN and LOOPMAX fields in the IDoc definition.

Illustration of the relationship between business object and IDoc

Figure 19 illustrates the relationship between the WebSphere data record business object and the IDoc definition from an SAP application.

Figure 19. Relationship between data record business object and IDoc definition Fields


Copyright IBM Corp. 1997, 2003