Business Object Types and their Key Fields (SAP Library - BAPI Programming Guide Reference (CA-BFA))

Business Object Types and their Key Fields

Each business object type has one or more key fields. Each instance has a unique combination of values in the key fields and is identified by the specific values in the key fields. This makes it possible to access a specific instance of a business object type via the values in the key fields. The key fields are an important design consideration for a business object.

Example of Key Fields:

Business Object Type	Key Field	Example
SalesOrder	SalesDocument	102
AccountingDocument	CompanyCode FiscalYear DocumentNumber	0001 1998 23

In object-oriented programming languages, an object (instance) is normally identified by a technical ID. In the BOR, the concept of key fields permits the SAP business objects to be linked with the underlying relational database.

In most cases, the key fields of an object type are also the key fields in the table containing the header data of the business object type. Since BOR runtime objects are client-independent, the client should not be used as a key field.

Object-Oriented Method Call

Class methods are distinguished from instance methods as concerns a method call in object-oriented programming languages. Class methods do not require an actual instance to exist, and implement functionality across all instances (for example, GetList). An instance method always relates to only one actual instance for which it is executed (for example, GetDetail for the instance 102 of SalesOrder). In this case, first a runtime instance is generated in the system. Any number of instance methods can then be executed for this instance.

This call model is also used by an external client, for example, to access the SAP business object types with Java or Visual Basic via appropriate middleware. In the first step, an actual runtine instance is created that is identified by its key combination (for example, SalesOrder 102). Since the call of an instance method relates to precisely this instance, the parameters (key fields) that identify the instance need not be transferred anew. For this reason, the key fields are not explicitly listed as parameters for instance methods in the BOR.

Consequences for the BAPI Interface

The function module implementing the BAPI is functional and cannot make this distinction. Consequently, in the case of instance-dependent BAPIs the key fields must be listed as import parameters in the BAPI function modules.

"Create" methods (for example, create a new SalesOrder) play an additional special role. Since create methods always relate to entities that do not yet exist in the system, they are class methods. After the create BAPI has executed, a runtime instance of this entity is supplied to the calling program. The calling program then continues processing with this instance. For this reason, in the case of create BAPIs, the key is contained in the Export parameters of the function module, but is not listed as a parameter in the BAPI itself (in the BOR).

In general, you need only adhere to the guidelines for key fields in the function module interface, since the other rules are automatically complied with when you use the BOR/BAPI wizard for defining methods in the BOR. The table below recapitulates the conventions applicable to key fields:

	With instance methods, all the BOR key fields are mandatory Import parameters in the function module. BOR key fields must not be defined as an Export parameter in the function module. Key fields are not defined as Import or Export parameters in the BOR method.
	With class methods, BOR key fields must not be defined as Export parameters in the function module (exception: create methods). Neither are BOR key fields allowed to be defined as Import parameters in the function module. Key fields are not defined as Import or Export parameters in the BOR method.
	With create methods, all the BOR key fields of the method are defined as Export parameters in the function module. BOR key fields must not be defined as Import parameters in the function module (this applies to all class methods). Key fields are not defined as Import or Export parameters in the BOR method.

If, in accordance with the above guidelines, key fields are defined as parameters in the function module, the conventions below apply:

	The fully defined key is used and not a partial key.
	There is a parameter in the function module for each key field of the business object type.
	The parameter in the function module and the BOR key field have the same name.

Remark : In the above explanation, a key field means a parameter that is used to identify a runtime instance (in the OO sense) and that has the same name as the key field of the business object type. It is of course possible to use other parameters to provide the required business information represented by the key.

In accordance with the above guidelines, a Create BAPI of the business object type CompanyCode (key CompanyCodeID) must not have an import parameter CompanyCodeID. The name of the company code to be created could instead be transferred, for example, as field ID in the parameter CompanyCodeData.