How to Create Alternative Keys with BOBX
Summary
Beside the database key a node has normally business
identifiers. They may be unique or not; they have in
common that they are often referenced in other objects. We
call them alternative keys. This tutorial shows how to create
and work with alternative keys using Business Object
Builder eXpert.
Level of complexity:
Time required for completion:
Author:
Company:
Created on:
Beginner
30 min.
Thea Hillenbrand
SAP AG
July 25, 2014
Getting Started with - (Title Via Document Properties)
TABLE OF CONTENTS
BEFORE YOU START ...................................................................................................................................... 3
Objectives ......................................................................................................................................................... 3
Prerequisites ...................................................................................................................................................... 4
Systems, releases, and authorizations .............................................................................................................. 4
Knowledge ......................................................................................................................................................... 4
GROUNDWORK ............................................................................................................................................... 4
ROOT Node Data Structure............................................................................................................................... 4
Result ................................................................................................................................................................ 4
DEFINE ALTERNATIVE KEY ........................................................................................................................... 4
Create Alternative Key .................................................................................................................................... 5
Define the Uniqueness Type .......................................................................................................................... 6
Create the table type ....................................................................................................................................... 6
Activate the Uniqueness Check ..................................................................................................................... 8
Result .............................................................................................................................................................. 10
TEST THE ALTERNATIVE KEY ..................................................................................................................... 10
Result .............................................................................................................................................................. 11
CREATE DATABASE INDEX ON CLASSICAL DATABASES ..................................................................... 11
Result .............................................................................................................................................................. 14
CONSUMPTION OF ALTERNATIVE KEYS................................................................................................... 14
SUMMARY ...................................................................................................................................................... 15
2
Getting Started with - (Title Via Document Properties)
BEFORE YOU START
The BOPF Framework is using technical keys (GUIDS) for the instances of a business object node. These
keys are not human readable and hard to reference. Normally a document has at least one human readable
identifier – like the sales quote ID in our example. These identifiers may be a single attribute or composed
out of multiple attributes. They are used to create references between documents or as human readable
identifiers. So BOPF provides support for these ‘business’ identifiers of a document and calls them
Alternative Keys.
It is not required that alternative keys are unique. If you think about an Employee BO for example: the names
of the employee could be modelled as a composed and non-unique alternative key.
Objectives
By the end of this tutorial, you will
 Be able to create Alternative Keys with BOBX
 Understand the advantages of using Alternative Keys
 Be able to work with Alternative Keys
The tutorial uses the same example like in the tutorial Getting Started with Business Object Processing
Framework.
Fig. 1: Business Object Structure
The SALES_QUOTE BO consists of the ROOT and ITEM nodes, the ROOT node containing header data
like the sales quote id, the related business partner, status, total amount and administrative data. The ITEM
node contains position data like product id, quantity and amounts.
We will introduce an Alternative Key for the Sales Quote ID. As this key should be unique we will add a
validation to check the uniqueness.
3
Getting Started with - (Title Via Document Properties)
Alternative keys are supposed to be typical selection criteria for the business object. So it is advised to
create a data base index in systems which are based on classical databases to speed up performance.
Prerequisites
In order to be able to perform the tutorial, the following prerequisites have to be fulfilled.
Systems, releases, and authorizations
 BOBX is part of the Business Suite Foundation Layer and, therefore, included in the following SAP
Business Suite releases:
 SAP Business Suite EHP6, all SP
 SAP Business Suite EHP7, all SP
 To implement this example, your SAP user requires the developer authorization profile (S_DEVELOP
authorization object)
Knowledge





Basic knowledge in ABAP OO
A good knowledge of DDIC tools – especially index definition for database tables
Experience with some of the BOB tutorials
Experience with the tutorial Getting started with BOBX
Optional: Creating and Implementing Validations in Business Object Builder
GROUNDWORK
To create an alternative key we need a business objects which you can create using the tutorial Getting
started with BOBX as template. It is sufficient to create only the ROOT node without any action. It is also
possible to create the BO with the transaction BOB – but the first tutorial describes the mechanics of the
BOBX tool, so that you are already familiar with the tool when starting creating the Alternative Key.
ROOT Node Data Structure
The following table describes the data structure of the ROOT node of the Sales Quote BO. Create the BO
and some test data.
Component
Typing
Method
Component Type
Data
Type
QUOTE_ID
Types
/BOBF/EPM_SQ_ID
CHAR
10
0
QUOTE_STATUS
Types
/BOBF/EPM_SQ_STATUS
CHAR
2
0
BP_ID
Types
/BOBF/EPM_BP_ID
CHAR
10
0
Length
Decimals
Result
You have created the BOs and test data and we can start our actual tasks. In the next step we will create an
alternative key.
DEFINE ALTERNATIVE KEY
Technically, an alternative key is an attribute or a combination of attributes of the persistent structure of a
node. The binding of the alternative key attributes to the persistent structure attributes of the node happens
implicitly via names. We are going to define an Alternative Key for the sales quote id – thus a simple
Alternative Key.
4
Getting Started with - (Title Via Document Properties)
Create Alternative Key
Launch the transaction BOBX and open the Business Object Detail Browser for the BO SALES_QUOTE.
Switch to the edit mode with the toggle button in the toolbar. As we want to create an Alternative Key on the
ROOT node, we open the Node Elements folder for the ROOT node and select the function Create
Alternative Key in the right mouse menu.
Fig. 2: Create Alternative Key in the right mouse menu
The Alternative Key for the sales quote consists only of one attribute, thus the name of the Alternative Key
must be the same as the referenced attribute in the persistent structure. In our case the name is QUOTE_ID.
So enter QUOTE_ID as Alternative Key name. The data type must be the same as the one of the referenced
attribute. So enter the name of the data element of the sales quote id: /BOBF/EPM_SQ_ID.
Fig. 3: Enter the name and data type of the alternative key
Note: if the semantical identifier consists of more than one attribute create a structure containing the
attributes of the alternative key. Take care to use the same names and data types for the attributes as in
the persistent structure. The name of the Alternative Key must be different of the names of the node
5
Getting Started with - (Title Via Document Properties)
attributes. To get a proposal for the key structure you can use the Propose Repository Names feature in the
Extras menue.
Define the Uniqueness Type
In this step you have to care for the tye of the key. Very often the Alternative Key is really a unique identifier
like the sales quote id or the product id. But in the employee example, the combination of first and last
names is not unique. Nevertheless the name is somehow an identifier which is often used – even if the result
is not unique.
The sales quote id is supposed to be unique. In our demo application we do not use internal numbering. So
the user has to input the sales quote id manually. We want the framework to check the uniqueness only after
the user having entered a value. So select the type Unique, if not initial. Now the framework allows initial
values.
Fig. 4: Select Unique, if not initial
Note: at the end, the user has to enter an identifier. You have different means to care for data consistency.
Either you set the property of the QUOTE_ID to mandatory or if you want to allow more flexibility on the UI
you can create an action validation and check if the user has entered a value only when he wants to publish
the sales quote for example.
Create the table type
For mass processing we need a table type for the alternative key. You can use the Propose Repository
Names feature in the Extras menu to create a name. The name of the data type is only proposed if you
didn’t already enter a name manually.
6
Getting Started with - (Title Via Document Properties)
Fig. 5: Propose Repository Names
Fig. 6: The name of the table type is proposed
Last but not least the table type has to be created in the Data Dictionary. Use the Generate Dictionary
Objects in the Extras menu to generate the table type.
7
Getting Started with - (Title Via Document Properties)
Fig. 7: Generate the key table type
Generate the BO definition. This function will update the constants interface with constant for the alternative
key.
Activate the Uniqueness Check
The BOPF framework provides a library function which checks the uniqueness of the alternative key. We
have to create an Action Validation to call the library function. Once the validation is defined on a node, all
Alternative Keys on this node are checked accordingly to the respective uniqueness settings of the different
Alternative Keys.
Open the Node Elements and the ROOT folder. Select the function Create Action Validation in the right
mouse menu.
8
Getting Started with - (Title Via Document Properties)
Fig. 8: Create Action Validation
Enter the validation name CHECK_ALTKEY_UNIQUENESS and the BOPF library class
/BOBF/CL_LIB_V_ALT_KEY.
Fig. 9: Enter the library class
In the last step configure the validation triggers. Select the tab Trigger Actions. The tab displays all implicit
actions and the ones you defined on the BO. The uniqueness check shall be triggered when the ROOT node
is created or changed. Thus select the checkboxes CREATE_ROOT and UPDATE_ROOT.
Fig. 10: Select the trigger actions
9
Getting Started with - (Title Via Document Properties)
Result
We are done with the definition of the alternative key and the uniqueness check and as the next step we are
going to test the alternative key.
TEST THE ALTERNATIVE KEY
Launch the BOPF test tool either by pressing the test button in the BO editor or using the transaction BOBT.
If you open the folder menu, you will recognize that the tool offers now the possibility to retrieve sales quotes
using the alternative key.
Fig. 11: Alternative key can be used to query the object
Create a new sales quote and save it without entering the sales quote id. Accordingly to the definition, the
sales quote can be saved.
Fig. 12: Save a sales quote without entering a quote id
Create a sales quote and enter an id. Then create another one and enter the same quote id. Press enter.
10
Getting Started with - (Title Via Document Properties)
Fig. 13: create two sales quote with an identical id
The action validation rejects the input with an error message.
Fig. 14: Error message due to the uniqueness check
Result
The test has shown that we cannot enter duplicate keys. It has also shown that the check does not care for
initial values. To close this gap, we need further configurations either in making the quote id mandatory or in
creating a second action validation which checks that the sales quote id is entered at a certain time during
the processing.
As the Alternative Keys are typically used for accessing the data we have to care for performance. In
systems based on classical databases it is recommended to create an index on the database to achieve a
good performance.
CREATE DATABASE INDEX ON CLASSICAL DATABASES
This step is obsolete on HANA based systems. For classical databases we have to create a database index
on the table of the ROOT node for performance reasons. Go to the ROOT node and navigate to the
database table via double click.
Select the function Indexes in the table editor. You do not have to switch to edit mode.
11
Getting Started with - (Title Via Document Properties)
Fig. 15: Select the function Indexes
Select the create button on the following popup.
Fig. 16: Select the create button
Enter the index name. The name length is restricted to 3 characters. Confirm the popup.
Fig. 17: Enter the index name
On the following popup we configure the index. Choose the fields composing the index. In our example we
chose the QUOTE_ID.
Now we care for the uniqueness of the index. As we want to accept initial values for the sales quote id we
cannot create a unique index. Anyway, as it is not possible to exclude HANA for unique indexes, we have to
select this attribute also for technical reasons.
12
Getting Started with - (Title Via Document Properties)
Fig. 18: Define the index
Select the Database Systems button (yellow arrow) to exclude HANA as database from the index
generation.
Select Exclusion list on the following popup and enter HDB. Confirm the popup.
Fig. 19: Exclude HANA from the index generation
Back on the configuration popup, you will recognize that the Database Systems button has a decorator to
mark that the database list has been configured.
13
Getting Started with - (Title Via Document Properties)
Fig. 20: Database Systems button has changed
Last but not least activate the index definition.
Result
We are done with the definition of the Alternative Key and the corresponding database index. In the next
step we show how to use Alternative Keys programmatically.
CONSUMPTION OF ALTERNATIVE KEYS
Alternative keys can be used by generic frameworks to query the object, as we have seen in the test tool.
Alternative keys can be target of foreign key associations. How to create associations will be described in a
further tutorial. And last but not least you can work with alternative keys programmatically. The core service
CONVERT_ALTERN_KEY converts a set of alternative keys to the keys or to another alternative key. The
following program shows how to retrieve data using the alternative key of the sales quote.
We create a Service Manager instance to work with the Sales Quote BO. Then we collect the Alternative
Keys in an internal table typed with the table type of the Alternative Key of the sales quote id. As the retrieve
method accepts only db keys, we convert the alternative key using the method CONVERT_ALTERN_KEY of
the service manager. Finally we retrieve the data using the converted keys and print out the result.
PROGRAM ztest_alternative_key.
PARAMETERS p_quote TYPE /bobf/epm_sq_id DEFAULT 'Z000000002'.
DATA
DATA
DATA
DATA
lo_sm
lt_alt_key
lt_root
lt_key
TYPE
TYPE
TYPE
TYPE
REF TO /bobf/if_tra_service_manager.
/bobf/t_epm_k_sq_id. “table type of the alt key
/bobf/t_epm_sq_root. “table type of the root node
/bobf/t_frw_key.
“BOPF table type for keys
" Get Service Manager for Sales Quote BO
lo_sm = /bobf/cl_tra_serv_mgr_factory=>get_service_manager(
iv_bo_key = /bobf/if_epm_sales_quote_c=>sc_bo_key ).
14
Getting Started with - (Title Via Document Properties)
" Convert alternative key to db key
INSERT p_quote INTO TABLE lt_alt_key.
lo_sm->convert_altern_key(
EXPORTING
iv_node_key
= /bobf/if_epm_sales_quote_c=>sc_node-root
iv_altkey_key = /bobf/if_epm_sales_quote_c=>sc_alternative_key-root-quote_id
it_key
= lt_alt_key
IMPORTING
et_key
= lt_key ).
" Retrieve data
lo_sm->retrieve(
EXPORTING
iv_node_key
= /bobf/if_epm_sales_quote_c=>sc_node-root
it_key
= lt_key
IMPORTING
et_data
= lt_root ).
LOOP AT lt_root ASSIGNING FIELD-SYMBOL(<r>).
WRITE: / <r>-quote_id, <r>-bp_id, <r>-currency_code, <r>-total_gross_amount.
ENDLOOP.
SUMMARY
This tutorial has shown how to create Alternative Keys, how to test them and how to use them
programmatically. If you are interested to see how they can be used in foreign key associations please see
the tutorial “Defining Associations with Business Object Builder eXpert”).
15
www.sap.com
© 2014 SAP SE. All rights reserved.
SAP, R/3, SAP NetWeaver, Duet, PartnerEdge, ByDesign, SAP
BusinessObjects Explorer, StreamWork, SAP HANA, and other SAP
products and services mentioned herein as well as their respective
logos are trademarks or registered trademarks of SAP SE in Germany
and other countries.
Business Objects and the Business Objects logo, BusinessObjects,
Crystal Reports, Crystal Decisions, Web Intelligence, Xcelsius, and
other Business Objects products and services mentioned herein as
well as their respective logos are trademarks or registered trademarks
of Business Objects Software Ltd. Business Objects is an SAP
company.
Sybase and Adaptive Server, iAnywhere, Sybase 365, SQL
Anywhere, and other Sybase products and services mentioned herein
as well as their respective logos are trademarks or registered
trademarks of Sybase Inc. Sybase is an SAP company.
Crossgate, m@gic EDDY, B2B 360°, and B2B 360° Services are
registered trademarks of Crossgate AG in Germany and other
countries. Crossgate is an SAP company.
All other product and service names mentioned are the trademarks of
their respective companies. Data contained in this document serves
informational purposes only. National product specifications may vary.
These materials are subject to change without notice. These materials
are provided by SAP SE and its affiliated companies ("SAP Group")
for informational purposes only, without representation or warranty of
any kind, and SAP Group shall not be liable for errors or omissions
with respect to the materials. The only warranties for SAP Group
products and services are those that are set forth in the express
warranty statements accompanying such products and services, if
any. Nothing herein should be construed as constituting an additional
warranty.