Connector for SAP Business Suite - API description - Developer's manual part 3 - Implementing custom processing modules

1. Overview of required API methods

The following table should provide a brief overview of which API functions need to be implemented to achieve a certain amount of external functionality.

RequirementDatahandlerget_DataObjectsget_MetaInfoget_Listget_Detailmodifydeleteupdate_temp_key
Display internal tablesGENERIC_VIEW OXX
Search help functionsGENERIC_VIEW OXX
Functional callsGENERIC_FUNCTION X
Trigger function with data storage in the external systemGENERIC_FUNCTION X
Data modelling externally, data storage in SAPGENERIC_STORE XXXXX
Trigger function with data storage in SAPDEVELOPER_API OXXXO
Make SAP business objects (e.g. Customer) availableDEVELOPER_API OXXXO

2. Inherited attributes of the root object

The following table contains attributes that are defined during the instancing of the processing modules. These can be used within the API methods.

AttributeApplicationMore information
CURRENT_API_FUNCTIONCurrently called function of the RFC APIAPI RFC functions
CURRENT_LOG_GUIDGUID within the LOG tableLogging
CUST_GLOBALGlobal customizingBasic settings
CUST_OBJECTCustomizing of the processing moduleRegistering processing modules
CUST_MAPPINGCustomizing of the findingMapping external data groups to processing modules
IX_CONTROLExternal control structureControl structure
KEY_SEPARATORSeparator for compound table keysKey information
PARAMETERSIdentified parameters by priority: Object -> Mapping -> External parametersLogging

3. Inherited methods of the root object

The following table contains methods that are implemented in the root object and used by the framework. The implementation examples from the 4th part of the API description - Example codings - contain, to some extent, ABAP coding that demonstrate the invoking of these methods. By redefining existing methods within custom processing modules, you can encroach on the standard processing considerably (e.g. converting data types).

MethodApplicationMore information
Z_IF_IA_IXA_INTREXX_API*API methodsAPI interface
CHECK_BAPIRET2Checking of BAPIRET2 structures for errors and message attachments
GET_FIELDIdentify the single value from a table with incoming dataData exchange
GET_FIELD_WITH_X_FLAGLike GET_FIELD with update information for BAPI callsData exchange
GET_FIELDS_FROM_STRUCTransfer incoming data to a transfer structureData exchange
GET_NEW_NUMBER_KEYSimple number sequencingNumber sequencing
GET_SERVER_CONFIGIdentify value from an external configuration valueControl structure
LOCKING*Modelling of locking conceptLocking concept
MAP_BAPIRET2_TAB_TO_IXA_MSGMapping of BAPI messages to an internal format
MAP_FIELDVALUE*Convert values from an internal to external presentation (and vise versa) depending on the data typeConversion - Internal vs external
MAP_INTREXX_LANGUAGE_TO_SAPMapping of the portal language from Intrexx to SAP
MAP_IXA_MESSAGE_TO_BAL_LOGMapping of the internal messages to the the format of the application logExpanded message logging
MSG_APPENDAppend a message for the external callerMessages
SET_FIELDTransfer a single value to the exportData exchange
SET_RESULTS_FROM_STRUCTransfer a transfer structure to the exportData exchange

4. Checklist: Create a new processing module

Create a class

Each processing module consists of an ABAP object's class that is inherited from a root class of the portal framework.. To do this start the transaction SE80 for example. You can create a new ABAP class via the Context menu (right-mouse button).



Provide the new class with a technical name (perhaps based on your internal naming conventions) and a label.



Afterwards, an additional edit field will open via the highlighted button where you can specify which existing class the new class should inherit its properties from. Specify a class from the framework.

Example:


If you have not assigned the new class to the local packet $TMP, a popup will open for the transport request after you have confirmed your entry with Save. The new class has been created and can now be activated. The activation can be started via the button , for example.



A selection of the objects to be activated will then open.



After confirming here, the new class is activated and can be used.

Redefining the API methods

The extension concept of the portal framework means that the identified processing modules overwrite the corresponding API methods of the API interface. Here, for example, the API method "GET_DETAIL" is redefined. To do that, position the cursor over the API method and click on the button .



Subsequently, the ABAP workbench generates an inheritance of the selected method with a coding suggestion for calling the same-named method of the parent object.



It makes sense here to open the inherited method of the parent object and add custom coding before or after it. In many cases however, the entire method must be reimplemented. The basic framework for such a reimplementation could be used as shown in the following coding:
method Z_IF_IA_IXA_INTREXX_API~GET_DETAIL.

				* -------------- init
				  cv_processed = 'X'.  
				  ev_error     = 'X'.

				* -------------- get inbound parameters

				* -------------- initial check routines

				* -------------- process

				* -------------- fill outbound parameters

				* -------------- finally set no error  
				  ev_error    = ' '.

				endmethod.
This suggestion assumes that the method can be exited in the case of errors at any time using the ABAP command "EXIT". The error flag is only deleted at the end.

Create a transfer structure

For the tabular transfer of data via the API to an external caller a transfer structure is implemented. The external caller identifies the setup of this structure (e.g. field name and technical properties of these fields) via the API method GET_METAINFO. Experience shows that it is a good idea to define this transfer structure as a structure in the ABAP dictionary. You can then treat this structure, for example, as a table and use the API methods for the registered processing module of the datahandler "GENERIC_VIEW" (e.g. "GET_METAINFO"). In the following, the creation of such a transfer structure will be described as an example. Transfer structures usually contain a subset of actually available SAP tables or views, or rather fields from BAPI structures. If possible, you should use the same field names here that the actual SAP processing functions (e.g. BAPI functional modules) use. Transferring data can then be achieved in a time-saving manner via the ABAP command "MOVE-CORRESPONDING". Transfer structures can defined SAP data in a table row that actually is not available or is not identifiable via joins. Examples of this are: The invoking API method is responsible that all necessary conversions take place before the data is added to the exit parameter of the API methods. A transfer structure is created either via transaction SE11 or once more in the ABAP workbench SE80.



The technical name of the new structure is requested in a popup.



You then define the field names and data elements of your transfer structure in the structure maintenance. The transfer structure should contain all key fields needed for the identification later.



Activate the structure.

Registering the processing module

The newly created class must be registered for the processing module in the customizing. The following screenshot demonstrates the registration of the previously created processing class that only refers to the transfer structure "YIXAPI_DEMO" with the key field "PARTNER".



Alternatively, it is also possible to implement generic processing modules without a specific reference to a transfer structure. In this case, the actual transfer structure is identified from other parameters generically (e.g. from the externally used data group name). As a naming convention for the required technical name "OBJECTTYPE", the following prefixes are recommended: Otherwise, the technical names should contain references to internal projects and provide an explanation of the expected function (e.g. "*ORDER*").

Finding the processing module

The processing module that was just registered is not yet found by the framework. The Customizing of the finding needs to be adjusted to do this. The following screenshot demonstrates this for the explained example.



In the future, the new processing module can be accessed via the datahandler "DEVELOPER_API" and the external data group "YIXAPI_DEMO".

5. Testing and debugging

This section describes the options as to how new processing modules, and their finding, can be tested and debugged.

Test the finding via the RFC API

The externally called RFC functions of the RFC API are listed in the chapter API RFC functions. Each of these RFC functions can be tested and debugged internally via the transaction "SE37 ABAP". The following example demonstrates this by using the implemented API method "GET_DETAIL" of the process module from the chapter Checklist: Create a new processing module. The externally called RFC functional module for the API method "GET_DETAIL" is "Z_IA_IXA_API_GET_DETAIL". This is now started with SE37.



A window with the functional module interface will open.



The parameter IS_CONTROL plays an important role in the finding of the processing module. The parameter can be edited by clicking on .



An optically improved view is created by clicking on . Filling in the fields "IX_DATAGROUP" and "IX_DATAHANDLER" is enough for the test. The values need to be the same as those entered in the finding.



After confirming and returning to the interface view, the RFC functional module can be started with the F8 key or by clicking on the button. Depending on the implemented API module, other parameters may need to be populated.



After the start, the interface view contains the return values.



An initial export parameter "EV_ERROR" is a good sign that a processing module with these parameters was found and executed. To find out whether the correct processing module was started, a breakpoint can be added to the corresponding API method of the processing module.

Debugging within the SAP system

This section describes a debugging option without an external call. With this, the ABAP developer can test the basic functionality of a processing module before an external user calls the RFC API functions remotely. To do this, a breakpoint needs to be placed in the ABAP coding (e.g. at the start of the API method) with Ctrl + Shift + F12 or by clicking on the button.



In newer releases (Basis SAP Gateway >6.10), a window can now be opened to select the type of breakpoint to be created. In this case, a "Session Breakpoint" should be selected.



The breakpoint is shown in the coding.



Afterwards, the test via the call of the responsible RFC functional module should be repeated. The transaction SE37 must be restarted for this. The debugger will open when the breakpoint is reached.



The ABAP develop can now test in debug mode and find errors as usual.

External debugging

External debugging enables troubleshooting and testing of ABAP coding that is invoked externally (e.g. via RFC from the portal). In doing so, errors can be found that originate from the externally calling parameter populating in a different manner than what is expected. This option is available in SAP systems that use an ABAP Basis >= 6.10. The external debugging must be activated in the settings of the ABAP Workbench (Transaction SE80, Menu "Help / Settings").



It's also possible to debug users that deviate from the ABAP developer or login names. In this way, you can monitor, for example, the technical user that the external caller uses to log in to the RFC API. Please make sure that the user entered here has sufficient permissions (e.g. debugging, ABAP development) and is categorized as a dialog user (e.g. even if only temporarily during the test phase). When the popup for selecting the type of breakpoint appears, please select "External breakpoint".



So that the breakpoint is effective for the external caller, the external system must potentially log in once more. If the debugger is not opened after the API function's call, even though the internal test works, the SAP documentation about Externally activated debugging contains additional support for the troubleshooting. In most cases, you will find what you're looking for in the *.TRC files of the remotely used RFC API.

6. Externally activated debugging

Another method for activating the debug mode is made available by the externally used SAP RFC SDK. This makes it possible, for example when using the SAP Java Connector, to activate the debug mode externally (see documentation on SAP Java Connector). External callers that use the SAP Java Connector may provide parameters that remove this behavior. A limitation of this method is that this only functions stabily on MS Windows and an SAPGUI needs to be installed on the external caller's computer. This usually excludes this alternative because the server in the data center should not be used for development and tests.

7. More information

API description - Developer's manual part 4 - Coding examples