How to Create Alternative Keys with BOBX - Archive

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.

Author: Thea Hillenbrand Company: SAP AG Created on: July 25, 2014

Level of complexity: Beginner Time required for completion: 30 min.

Getting Started with - (Title Via Document Properties)

2

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


3

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.

http://scn.sap.com/docs/DOC-45703

http://scn.sap.com/docs/DOC-45703


4

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

Length Decimals

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

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.


5

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


6

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.


7

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.


8

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.


9

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


10

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.


11

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.


12

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.


13

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.


14

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 lo_sm TYPE REF TO /bobf/if_tra_service_manager.

DATA lt_alt_key TYPE /bobf/t_epm_k_sq_id. “table type of the alt key

DATA lt_root TYPE /bobf/t_epm_sq_root. “table type of the root node

DATA lt_key TYPE /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 ).


15

" 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”).

© 2014 SAP SE. All rights reserved.

SAP, R/3, SAP NetWeaver, Duet, PartnerEdge, ByDesign, SAPBusinessObjects Explorer, StreamWork, SAP HANA, and other SAPproducts and services mentioned herein as well as their respectivelogos are trademarks or registered trademarks of SAP SE in Germanyand other countries.

Business Objects and the Business Objects logo, BusinessObjects,Crystal Reports, Crystal Decisions, Web Intelligence, Xcelsius, andother Business Objects products and services mentioned herein aswell as their respective logos are trademarks or registered trademarksof Business Objects Software Ltd. Business Objects is an SAPcompany.

Sybase and Adaptive Server, iAnywhere, Sybase 365, SQLAnywhere, and other Sybase products and services mentioned hereinas well as their respective logos are trademarks or registeredtrademarks of Sybase Inc. Sybase is an SAP company.

Crossgate, m@gic EDDY, B2B 360°, and B2B 360° Services areregistered trademarks of Crossgate AG in Germany and othercountries. Crossgate is an SAP company.

All other product and service names mentioned are the trademarks oftheir respective companies. Data contained in this document servesinformational purposes only. National product specifications may vary.

These materials are subject to change without notice. These materialsare provided by SAP SE and its affiliated companies ("SAP Group")for informational purposes only, without representation or warranty ofany kind, and SAP Group shall not be liable for errors or omissionswith respect to the materials. The only warranties for SAP Groupproducts and services are those that are set forth in the expresswarranty statements accompanying such products and services, ifany. Nothing herein should be construed as constituting an additionalwarranty.

www.sap.com

Documents

How to Create Alternative Keys with BOBX - Archive