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 20 illustrates the structure of a WebSphere business object for the ALE Module.

Figure 20. 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_BasicIDocType
Note:
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 IDocFieldName or IDoc Field Description

When generating the BOs, the user has the choice to either choose IDoc segment field names or field descriptions as the BO attribute names.

Component names in the WebSphere business integration system support only alphanumeric characters and the underscore character (_). Therefore, when naming components in a generated business object definition, SAPODA replaces special characters in the IDoc segment field descriptions or field names with underscore characters. 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 descriptions, then SAPODA adds a counter suffix to the generated attribute name.

When naming an attribute, SAPODA prepends a string to the attribute name when the changed attribute name:

Important:
You can modify attribute names at any time after you generate the business object. However, when you modify an attribute name, do not modify its application-specific information. The connector uses this text to identify the IDoc field to which the business object attribute corresponds. For more information, see Application-specific information: Data record business object.

Naming conventions for IDoc extensions

When SAPODA generates a business object definition based on an IDoc extension, it uses slightly different naming conventions than those described in Business object naming conventions. In this case, it includes the extension name as described in Table 24.

Table 24. Naming Conventions for Idoc extensions

IBM WebSphere business object or attribute Name Type
Parent wrapper business object BOprefix_BasicIDocType_ExtensionName 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_ ExtensionName_IDocSegmentName BOprefix_BasicIDocType_ ExtensionName_IDocSegmentName
Data Record attribute IDocFieldText or IDocFieldName String

For the syntax of AppSpecificInfo property that specifies the extension, see Parent wrapper business object.

Important:
When InterChange System is the integration broker, be careful when you load 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. 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 value in the TransactionId attribute determines whether the connector manages TIDs when processing service call requests. If you do not want TID management for request processing, do not set the value for the TransactionID attribute.

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 [,Ext=ExtensionName
 [,Pn=PartnerNumberOfRecipient [,Pt=
 PartnerTypeOfRecipient[,Pf=PartnerFunctionOfRecipient
 ]]
 

Explanation of syntax

BasicIDocType
Specifies the basic IDoc type
Ext
Specifies the extension 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 the IBM WebShpere InterChange Server is the integration broker, you can use the repos_copy command.

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

Table 25. 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:
When an attribute's value is set to either CxIgnore or CxBlank in the control record business object, the connector sets the value to 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.

Generating an IDoc from the system using SAPODA creates the data record object and its child business objects by making calls into the SAP system itself. Fields from an IDoc definition file are used in this section to help illustrate how different properties of a business object are set. Generating an IDoc from the system uses corresponding fields from the calls made into the SAP system.

This section describes:

Attributes: Data record business object

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

Table 26. Simple attributes: data record business object

Property name Description
Name The value of the Name property is the modified value of the NAME or 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: Data record business object.
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 27 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 27. Attributes that represent child business objects

Property name Description
Name SAPODA sets the value to BOprefix_BasicIDocTypeIdocSegmentName; for example, SAP_E2ALER1001
Type SAPODA sets the value 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 business-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 21 illustrates the relationship between the WebSphere data record business object and the IDoc definition from an SAP application.

Figure 21. Relationship Between data record business object and IDoc Definition fields


Copyright IBM Corp. 1997, 2004