Business Add-Ins

Business add-ins are enhancements to the standard version of the system. They can be inserted into the SAP System to accommodate user requirements too specific to be included in the standard delivery. Since specific industries often require special functions, SAP allows you to predefine these points in your software. As with customer exits, two different views are available:

1. In the definition view, an application programmer defines exit points in a source that allow specific industry sectors, partners, and customers to attach additional coding to standard SAP source code, without having to modify the original object. 2. In the implementation view, the users of Business Add-Ins can customize the logic they need or use a standard solution, if one is available. In contrast to customer exits, Business Add-Ins no longer assume a two-level infrastructure (SAP and customer solutions), but instead allow for a multi-level system landscape (SAP, country-specific versions, industry solutions, partner, customer, and so on). You can create definitions and implementations of Business Add-Ins at any level of the system landscape. SAP guarantees the upward compatibility of all Business Add-In interfaces. Release upgrades do not affect enhancement calls from within the standard software nor do they affect the validity of call interfaces. You do not have to register Business Add-Ins in SSCR. The Business Add-In enhancement technique differentiates between enhancements that can only be implemented once and enhancements that can be used actively by any number of customers at the same time. In addition, Business Add-Ins can be defined according to filter values. This allows you to differentiate between Add-In implementations using the filter Country or other criteria. The enhancement technique is set up in such a way that it is possible to define interfaces for ABAP soure code, screens, GUI interfaces, and tables. These allow customers to include their own enhancements in the standard. A single Business Add-In contains all of the interfaces necessary to implement a specific task. The actual program code is enhanced using ABAP Objects. In order to better understand the enhancement technique behind the Business Add, we recommend reading the section ABAP Objects. For more information, refer to the following sections:

Architecture of the Enhancement Technique Compare with Existing Techniques Definition of a Business Add-In Calling a Business Add-In in the Application Program Implementing a Business Add-In Filter-Dependent Business Add-Ins Multiple Use Business Add-Ins Menu Enhancements Screen Enhancements Procedure for Importing Business Add-Ins

Architecture of the Enhancement Technique

In order to enhance a program, you must first define a Business Add-In. The application developer creates an interface for the add-in. From this, enhancement management creates an adapter class that implements the interface and thus provides the interface for implementation by the customer, partner, and so on. The developer then creates an instance of the adapter class in the application program and calls the corresponding method at the appropriate time.

For each Business Add-In you have one interface and an adapter class that implements this. The interface is implemented by the user. The generated class (Add-In adapter) has the following tasks:
Control The adapter class calls the active implementations. 1. Filtering If a Business Add-In is to be executed only under certain conditions, the adapter class ensures that only certain implementations will be executed.

This concept ensures mutlple use. Any Business Add-In that has been implemented once already can be implemented again by those groups listed to the right of the software chain shown in the above graphic. Customers can find the enhancements in their system in the Implementation Guide (IMG) and in the component hierarchy. If a customer wishes to use a Business Add-In, he or she first creates an implementation. The customer must implement the methods and the enhancements, and afterwards activate the implementation of the enhancement. The enhancement's active components are then called at runtime. Normally, a Business Add-In contains an interface and other additional components such as function codes for menu enhancements. In some cases, Business Add-Ins also include enhancements for screens. The enhancement, interface, and generated classes are all

located in the appropriate application development namespace. Business Add-In implementations are created in the respective implementation namespace. The following sections contain examples of program, menu, and screen enhancements.

A Comparison of Different Enhancement Techniques

Due to the necessity of adjusting R/3 to meet the specific needs of a variety of customers, several different enhancement techniques were developed in the past. A short description of each of the various enhancement techniques follows. Business Transaction Events (Open FI) The Open FI enhancement technique was developed in the Financial Accounting component. Open FI is based upon the following principles: Application developers must define their interface in a function module, an assignment table is read in the accompanying (generated) code, and the customer modules assigned are called dynamically. This technique differentiates between enhancements that are only allowed to have one implementation and enhancements that can call multiple implementations in any sequence desired. Both industry-specific and country-specific enhancements may be defined. The concepts behind the Business Add-Ins enhancement technique and Open FI are basically the same. However, the two enhancement techniques do differ from each other in the following points:
1. Open FI can only be used to make program enhancements, that is, you can only enhance source code using Open FI. You cannot enhance user interface elements with Open FI like you can with Business Add-Ins. Open FI assumes that enhancement will only take place on three levels (SAP - partners customers), whereas with Business Add-Ins you can create and implement enhancements in as many software layers as you like. Open FI uses function modules for program enhancements. With Business Add-Ins, ABAP Objects is used to enhance programs.

1.

2.

Enhancements in Transactions SMOD/CMOD

Making enhancements using the transactions disadvantages:

1. 2.

SMOD/CMOD has the following

This enhancement technique assumes a two-tiered system infrastructure (SAP customers). The naming conventions in effect do not tolerate name extension.

Conclusion: None of the techniques mentioned above can easily be extended to fulfill the requirements of a system infrastructure containing country versions, industry solutions, partners, and customers. Business Add-Ins should be considered generalized Business Transaction Events that can be used to bundle program, menu and screen enhancements into a single add-in. Business Add-Ins can be created and employed in each of the various software levels.

Defining a Business Add-In

Use
An application developer who wishes to have a Business Add-In in a particular program defines the interface for an enhancement in the Business Add-In Builder. In the following step, he or she programs the interface call in the application program at the appropriate place. Customers can then select the add-in and implement it according to their needs.

Procedure
1. ... 1. 1. From the SAP menu, choose Tools ABAP Workbench Utilities Business Add-Ins (transaction SE18).
We would like to explain the procedures using an application program as an example. There is a string conversion in the program. You want the add-in users to determine themselves how their strings are to be converted. The application developer defines an enhancement. It consists of an interface with a method. A changing parameter is used to pass on the string.

2.

2. Enter a name with a maximum of 20 characters for the Business Add-In.

3. 4.

3. Choose Create. 4. On the following screen, enter a short text as the description for the Business Add-In.
In this example, we are dealing with a simple enhancement. Option: Within SAP Meaning: If the customer selects this option for an Add-In, he or she has no option for creating his or her own implementations for this Business Add-In or for using them. In the input help, Business Add-Ins with this flag are not displayed. For more information on the checkbox Within SAP, refer to the section Definition of a Business Add-In in the Enterprise Core. The Business Add-In can be set for multiple use. For more information, refer to the section Multiple-Use Business Add-Ins. The implementation of a Business Add-In is dependent on a particular filter value. For more information, refer to the section Multiple-Use Business Add-Ins.

Multiple Use Filter-Dependent

None of the above options is selected.

5.

5. Choose the Interface tab. The interface name is generated automatically and can be changed here.

Under the FCodes tab, you can create Menu Enhancements, and under the Subscreens tab you can create Screen Enhancements.

6.

6. Double-click the interface name field. The system branches to the Class Builder. 7. 7. Confirm that you want to save the entries you have made. Assign a package to the Business Add-In. 8. 8. Use the Class Builder to assign a method to the interface.

9.

9. Now define a parameter with the following attributes:

10. 10. Save and activate your entries. Use the pushbutton Back to navigate back to the Business Add-In definition.
You can now continue with the definition of the Business Add-In by executing activation in the Class Builder. A table control now appears on the definition screen for the Business Add-In. It displays the method you have created for the interface. When you maintain the interface methods, the corresponding executing class is generated. The generated code cannot be altered in the initial expansion phase.

11. 11. Save your entries and use the Documentation pushbutton to create a description for your new Business Add-In. Remember that this documentation is very important for users to be able to understand the purpose behind the Add-In. For more information, read the section Documentation of a Business Add-In. Choose Goto Default Coding / Sample Coding if you wish to create default coding and/ or sample coding for the Business Add-In. The default implementation is executed only if no other active implementation is available. This applies also to filter-dependent Business Add-Ins.

When you create default or sample coding, do not forget to save your entries. In this way, the connection between the class and the implementation is set up.

2.

...

See also: Changes to Business Add-In Definitions

Changes to BadI Definitions

You are allowed to change:
The filter type 1. 2. The definition of multiple use The internal flag selection

If implementations already exist for a BadI definition, these can be rendered syntactically incorrect by changes made to the interface. If changes to the interface are unavoidable and they pertain to deleting, renaming, or creating a method, clean up the method includes in the current development system for all classes that are used for the BAdI implementations. In the BAdi Builder, call up transaction SE19 and choose the tab Interface. Afterwards, choose the field Name of Implementing Class. Double click to navigate to the Class Builder. Choose Utilities Clean Up Method Includes. Whenever methods are deleted, this will have the effect that the corresponding includes are also deleted in the implementing classes. Renaming is also the same as deleting. If an interface change of the type mentioned above reaches a system by means of system transport or delivery, this clean-up is automatically executed after the import phase. If interface changes refer to parameters, remember that creating parameters is possible without any problem. Changing parameter types or deleting parameters can cause syntax errors or possibly also termination at runtime.

Calling a Business Add-In in the Application Program

When you define a Business Add-In, enhancement management generates a class that implements your interface. The application developer uses a factory method to create an instance of this adapter class in the application program and calls the corresponding method, if necessary. The adapter class method generated by add-in management decides whether one or several active implementations should be called. If necessary, these implementations are subsequently executed. The application program ensures only that the adapter class method is called. The application program does not know which implementations are called. Example: Having created a string conversion Business Add-In, you would program the call of the Business Add-In into your ABAP source code as follows: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 Report businessaddin. class cl_exithandler definition load. "Declaration data exit type ref to if_ex_businessaddin. "Interface reference data word(15) type c value 'Business Add-in'. "String to change start-of-selection. call method cl_exithandler=>get_instance "Factory method call exporting exit name =BUSINESSADDIN null instance accepted =X changing instance = exit. write:/'Please click here'. at line-selection. write:/ 'Original word: ',word. if not exit is initial. call method exit->method changing parameter = word. endif. write:/ 'Original word: ',word. "Add-In call

"Method

In order to be able to call static methods, you must declare the corresponding class in ABAP Objects. This is why the class definition load statement is necessary for the factory class.

A variable for object reference is also necessary when calling the method. Use data to create it and type it to the interface. During initialization (line 6), the application developer creates an adapter class instance using the factory method. The instance methods are then called at the time specified. To improve performance during creation of the instances, you should specify additional parameters for the call in the method GET_INSTANCE of the class CL_EXITHANDLER. EXIT_NAME: The name of the BAdI definition is assigned to this parameter. NULL_INSTANCE_ACCEPTED: Whenever the value X is assigned to this parameter, no instance is created if there are no active implementations for this BAdI definition. In this case, the INSTANCE parameter has the value NULL. Using this parameter implies that the method calls of this BAdI may only be called under the condition that this instance is not NULL. The query if not <badi instance> is initial. is necessary in this case.

Notes on Usage
The instance generated through the factory method should be declared as globally as possible or generally be passed as a parameter to ensure that the initialization process must be run as rarely as possible just once would be best. In no case should you discard the instance as soon as it is generated or repeatedly run the initialization process in a loop.

Within the adapter class interface, required database accesses are buffered locally, so that each access is executed once only. However, repeated initialization makes the buffer useless and dramatically reduces performance.

Due to the local buffering, you can call Business-Add-In methods without having to expect considerable performance restrictions, even if no active implementations exist. Also, if the definition of the Business-Add-In is filter-dependent, a single instance is sufficient. However, you should not do without initialization altogether. Even if you could call static methods of the implementing class of the Business-Add-In implementation without an instance, you would lose the benefit of performance improvement through the BusinessAdd-Ins and the possibility of multiple use. If you switch the method type in the interface from the static method to the instance method at any time in the future, many code adjustments are required. In addition, you can no longer use default code that is provided.

Implementing a Business Add-In

A list of the Business Add-Ins available in your system can be found either in the SAP Reference Implementation Guide (IMG) or in the component hierarchy. BAdI definitions are included in the IMG so that the customer/partner can create suitable, companyspecific implementations.

In the SAP Reference IMG, BAdI implementations - in addition to BAdI definitions can be provided. This would be suitable in cases where you can see in advance which functions are required by the customer. Using a BAdI implementation, the customer/partner can simply switch the delivered implementations on or off, as required. In the SAP Reference IMG, choose Execute in front of the name of the BAdI implementation. The icon serves as a switch for activating and deactivating the implementation.

Starting from the name and the documentation of the enhancement, you can create an implementation. During the implementation, the system creates a class that implements the enhancements interface. The implementation is a separate transport object and lies within the namespace of the person or organization implementing it. For the example given here, you are to create an implementation for the string conversion. You need to program the interface method in such a way that, when the addin is called from the application program, the string is actually converted in the way the add-in user wants it. To create an implementation, proceed as follows: 1. ... 1. 1. In the SAP menu, choose ABAP Workbench Utilities Business Add-Ins (transaction SE19) or double-click the corresponding activity in the Implementation Guide (IMG). 2. 2. Enter a name for the implementation and then click the Create pushbutton. 3. 3. Enter the name of the add-in for which you want to create an implementation for in the dialog box that appears.

4. 5. 6.

4. Enter a short text describing your implementation on the following screen. 5. Choose the Interface tab. 6. Choose ABAP Code as the implementation type.
In addition to ABAP Code, there is also the Formula option. If you choose Formula, the content of a method is determined using the Formula Builder. For more information on this, refer to the section Implementing Methods Using the Formula Builder.

7.

7. Navigate to the Class Builder by double-clicking the method. You must first enter a package before the Class Builder is displayed. 8. 8. Insert the desired source code for the implementation between the method if_ex_businessaddin~method. and endmethod. statements that already exist.
In our particular example, you could enter the statement translate parameter to upper case.

9. 9. Save your entries and return to the Change Implementation screen. 10. 10. Choose Activate. You may now use this implementation when the application program is executed.
Several implementations may exist for a Business Add-In that is not used on a multiple basis. However, only one implementation can be active at any one time. What is also important is that you must declare the instance generation of the implementing class (Attributes tab) as public and not as private, protected, or even abstract. If you do this, the system will return short dumps at runtime.

See also: Calling Implementations Through Filter Mechanisms

Implementing Methods Using the Formula Builder

Use
You can use the Formula Builder to implement methods for Business Add-Ins without writing a single line of ABAP code. The methods are implemented by means of socalled formulas. This type of implementation does not require you to have programming knowledge. However, the functions it offers are more restricted than if you implement a method by writing ABAP code. If the range of functions provided by the Formula Builder is not sufficient, you can change the implementation type of the method at any time.

Features
A formula can consist of the following steps: Condition You define a Boolean formula expression whose result can be true or false. This formula expression is a logical condition based on the importing and changing parameters of the method. Depending on whether the condition is true or false, the system triggers different steps. If you do not specify a dependent step for one of these two possibilities, the system continues with the next superior step. Substitution The system replaces the value of a specific parameter with another value which you define as a constant value or by means of a mathematic formula. Substitution is only possible if the method contains changing, exporting or returning parameters. Message The system issues a message. All messages issued are collected in a log table. You define the message variables as constant values or by means of mathematic formulas. The system can only issue a message if you created a log table during method definition. Exception The system exits the method. No further steps are executed, and the application program continues in accordance with the exception defined. You can additionally display a message whose variables you define as constant values or by means of mathematic formulas. An exception can only be triggered if the method contains exceptions.

A formula editor is available which you can use to enter formula expressions. After starting the formula editor, you can display information on how to use it by choosing the pushbutton next to the status display (traffic light).

Activities
You implement the method using the BAdI Builder. For information on this topic, see Implementing Business Add-Ins. To implement a method as a formula, choose the Formula implementation type on the Interface tab. Double-clicking the method name takes to to the Formula Builder: BadI Implementation screen.

You can change the implementation type of the method on the Interface tab. You can implement a method both using a formula and using ABAP code. At the runtime of the application program, the system executes the implementation type currently chosen. You create the necessary steps in the left section of the screen. To do this, choose and then select the appropriate step type from the dropdown list. Using the other icons available or the context menu (which you can call by clicking the right mouse button), you then determine the arrangement and the descriptions of the steps. You can also copy steps to use them as templates for other steps, or you can delete individual steps. To specify the parameters for the individual steps, double-click the corresponding entry in the left section of the screen. You then enter the data required in the right section of the screen.

Formulas are transported automatically.

Menu Enhancements
Menu enhancements with function codes are provided for in the user interfaces. These function codes must adhere to the form /namensraum/+<...>, just like in the enhancement technique SMOD/CMOD. These function codes are assigned to an enhancement. Only when there is an active implementation of the assignment do they appear in the menu. The application developer reserves specific function codes for customers when defining a Business Add-In and assigns them in the Menu Painter in the appropriate menu lists. The application developer must also ensure that these menu options are queried in the application program and that the corresponding add-in method is also called. Customers can take advantage of menu enhancements by creating a new implementation, choosing a text for the menu option, and then programming the method used to determine what action is performed when the menu enhancement is called.

Menu enhancements can only be used for single-use add-ins (not multiple-use addins) that are not filter-dependent. Currently, menu enhancements can only be created in conjunction with program enhancements (interfaces).

To create a menu enhancement, proceed as follows: 11. 12. 13. 2. ... 1. Create the definition of an add-in and define its interface. 2. Choose the FCodes tab. 3. Enter the name of your program, the function code, and a description.

14.

4. Call the Menu Painter or double-click on the program name or function code to navigate to user interface maintenance in the Menu Painter. Enter the function code in the appropriate menu list. If you have accessed the Menu Painter directly during addin definition, you can call the menu lists by choosing Goto Object Lists Menu Lists.

Calling a Menu Enhancement from the Application Program

The application program should look like this:
() case fcode. when 'SAP'. () when '+CUS' call method

Implementing a Menu Enhancement

To create the implementation of a menu enhancement, proceed as follows: 15. 3. eine Implementierung an und whlen Sie den Registerindex Fcodes 1. Create an implementation and choose the FCodes tab. All data adopted from your Business Add-In's definition is displayed here. You can make entries for the implementation on the right. You can also double-click the first input field. The following dialog box appears:

Here you may enter a text for your function code, the name of an icon, a text for the icon, and a short description. The actions that you want the system to perform after the pushbutton is chosen must be programmed in the appropriate method, either manually or using a default source code that has been provided for this purpose. Menu enhancements only become visible after the implementation has been activated and the application program that calls the Business Add-In has been executed.