Development aims
The following development aims are in the foreground when implementing the SAP Portal Plugin:
-
No JAVA modifications for requests from the SAP environment
When implementing portal processes in the SAP environment, you want to keep the time and effort required for creating surfaces, portal applications and permission concepts bearable. However the clarification of functionalities (functional specification) and the analysis of how implementable the existing SAP functions are is vital. The most leading SAP system determines the data model and the functionalities that can be implemented. When designing the plugin, it was therefore important that the expansion concept was achieved within SAP ABAP and the interface between the systems remained rigid.
-
Use functions that are not available as BAPI/RFC
SAP provides numerous functions via BAPIs and RFC-enabled functional components which can be used by external systems. Especially the BAPIs are intepreted as business object oriented and should meet the requirements of a universal connector. However, a large number of the available BAPIs (depending on the release) is usually not sufficient, are incompletely or partially incorrectly implemented, and each BAPI reacts differently. When designing the plugin, the way of a few less API methods, which can be addressed via RFC, was therefore chose. These call-ups are then forwarded to other functions that can meet the external requests. These call-ups are then forwarded to other functions that can meet the external requests.
-
Defined and manangeable RFC API
The approach discussed here primarily enables you to keep the target for the SAP system as small as possible. Uncontrolled growth of RFC functions is avoided. It is easier to implement the permissions concept because all external call-ups come through a mutual entrance.
API concept
Based on the development aims, a small RFC-enabled API proceeded which principally implements the following functions:
-
Get_MetaInfo
-
Get_List
-
Get_Detail
-
Modify
-
Delete
Click here for more information about RFC API.
The call-up of the RFC API takes place over an external system (e.g. portal software Intrexx) from the business logic of said system via the SAP Java Connector.
The finding concept for the suitable SAP system was already described in Part 1 of the API documentation. Within the SAP system, a corresponding processing module is identified from the combination of an external datahandler and table name.
Expansion concept: Processing modules
For the Processing modules, the ABAP object concept was used to take advantage of benefits when implementing (especially using the inherit function). Every call-up of an API method identifies an ABAP object class to which the external request is forwarded as a method. Implementing generic processing modules is facilitated using the inherit function. For example, the same programming steps are always required for read access to SAP tables and views. Only the technical name of the table and/or view and the information (varying table structures, meta information) are what change. It is therefore easier to request read access to tables and views via a general processing module (e.g. "GENERIC_VIEW") than write access to SAP data objects. Requests such as a locking concept, verification logics (among others) need to be considered here. Implementing write access can therefore hardly be modelled generically because the object-specific API components (e.g. BAPI) should be used here. The graphic represents the cooperation between the system (shown by the external caller), datahandler and data object. The lower area especially demonstrates the finding of the ABAP object class and the call-up of the API method implemented there.
The data flow as well as the finding of the processing routines in cooperation with the external caller (Intrexx here) and the SAP Portal Plugin is shown in the following graphic.
Datahandler
In the external system, various datahandlers are required in order to separate the possible data objects from one another. The following datahandlers are predefined by the SAP Portal Plugin and can be used by external systems:
|
Datahandler |
Use |
|---|---|
|
GENERIC_VIEW |
Generic read access for physically available tables and views. This datahandler is only used if another datahandler is not explicitly specified. |
|
GENERIC_REPORT |
Generic read access for SAP reports (SE38). Enables the starting of (simple) reports with parameter transfers and returns the results in a table structure. |
|
GENERIC_STORE |
Enables the storage of data in table-like structues in the SAP system. Here, generic means that time and effort for development is not required despite the data's physical storage in the SAP system. These can, for example, be reached by using classification or similar functions. |
|
GENERIC_FUNCTION |
Enables functional call-ups in the SAP system and EXIT functionality with which SAP can verfiy the data entered externally. The data is stored in the external system. Saving an external data record is forwarded to the API method "modify". |
|
GENERIC_BAPI |
This datahandler could be used to implement generic access to SAP business objects and their BAPI methods. |
|
DEVELOPER_API |
Datahandler for all nongeneric processing modules that model one part or the entire API. |
The datahandlers listed here are primarily used for the finding of the correct processing modules. These datahandlers are not to be confused with additional processing modules. These are usually created in relation to the datahandler DEVELOPER_API.
RFC API
Development objects
The development objects (also known as development classes in earlier releases of SAP basis) for RFC API can be found in the package "ZIA_INTREXX_API" in the function group "ZIA_IXA_API". To use the SAP Plugin's functionality externally, you only have to allow the external access for this function group. Click here for more information about the permissions concept.
Used structures
a) Control structure
The control structure (technical name: "ZIA_IXA_API_INTREXX_CONTROL") is used as the import parameter "IS_CONTROL" of every API RFC functional component to provide certain external parameters.
|
No. |
Field name |
Data element |
Data type |
Size |
Description |
|---|---|---|---|---|---|
|
1 |
IX_DATAGROUP |
ZIA_IXA_DATAGROUP |
CHAR |
30 |
Name of the external Data group |
|
2 |
IX_DATARANGE |
ZIA_IXA_DATARANGE |
CHAR |
30 |
If need be, data groups can be used in different views. This field contains the technical name of the calling system's view. |
|
3 |
IX_DATAGROUP_EXT |
ZIA_IXA_DATAGROUP_EXTERN |
CHAR |
30 |
This field contains the name of a data group from the calling system (SAP external) that corresponds to the data group specified in field (1). This field is rarely used and as an example, contains the value from (1). |
|
4 |
IX_SESSION |
ZIA_IXA_SESSION |
CHAR |
40 |
Contains the external session ID in the internet and can be used to identify interrelated call-ups. |
|
5 |
IX_USER |
ZIA_IXA_USER |
CHAR |
30 |
Contains the username within the external system. |
|
6 |
IX_USERGROUP |
ZIA_IXA_USERGROUP |
CHAR |
30 |
Contains the user group of the external system. |
|
7 |
IX_LANGUAGE |
ZIA_IXA_LANGUAGE |
CHAR |
2 |
Contains the currently used language of the external system. |
|
8 |
IX_SAPINSTANCE |
ZIA_IXA_SAP_INSTANCE |
CHAR |
20 |
Name of the current system's data source in the external calling system. |
|
9 |
IX_SAPID |
ZIA_IXA_SAPID |
CHAR |
20 |
Installation number of the SAP system. |
|
10 |
IX_SYSID |
SYSYSID |
CHAR |
8 |
SID of the SAP system. |
|
11 |
IX_CLIENT |
SYMANDT |
CLNT |
3 |
Client of the SAP system. |
|
12 |
IX_PRODUCTIVE |
ZIA_IXA_PRODUCTIVE |
CHAR |
1 |
Tag: Live system. |
|
13 |
IX_LICENSE |
ZIA_IXA_LICENSE |
CHAR |
60 |
License key. |
|
14 |
IX_SRVCFG |
ZIA_IXA_SRVCFG |
CHAR |
255 |
Server configuration. |
|
15 |
IX_DATAHANDLER |
ZIA_IXA_DATAHANDLER |
CHAR |
20 |
External datahandler. |
|
16 |
IX_DHNDL_VAR |
ZIA_IXA_DATAHANDLER_VARIANT |
CHAR |
30 |
Alternative for the external datahandler (e.g. default). |
|
17 |
PARAMETERS_1 |
ZIA_IXA_PARAMETER |
CHAR |
50 |
Externally managed parameter (1). |
|
18 |
PARAMETERS_2 |
ZIA_IXA_PARAMETER |
CHAR |
50 |
Externally managed parameter (2). |
|
19 |
PARAMETERS_3 |
ZIA_IXA_PARAMETER |
CHAR |
50 |
Externally managed parameter (3). |
|
20 |
PARAMETERS_4 |
ZIA_IXA_PARAMETER |
CHAR |
50 |
Externally managed parameter (4). |
|
21 |
PARAMETERS_5 |
ZIA_IXA_PARAMETER |
CHAR |
50 |
Externally managed parameter (5). |
Fields 1, 2 and 15 are used for the finding of the actual processing modules (object-oriented ABAP object instances). Click here for more information. Fields 3-8 are purely information about the calling system but they can be relevant within the processing modules (e.g. when analysing the external language). Calling the wrong SAP system (e.g. incorrect client, live system) can be prevented by using fields 9-14. A license model can also be generated using these fields. Fields 15-16 contain information about externally used datahandlers. Here, an alternative datahandler could, for example, control the behavior of the processing module (suggested value "default"). Field 16 has no effect on the finding of the processing module. The behavior of the processing module can be controlled further using up to a maximum of 5 parameters (fields 17-21).
b) Data objects
Within the API function "get_DataObjects", possible data objects of the processing module can be identified. The technical names and an description are returned as a table (technical name of the structure "ZIA_IXA_API_INTREXX_DATAOBJ") to the external calling system.
|
No. |
Field name |
Data element |
Data type |
Size |
Description |
|---|---|---|---|---|---|
|
1 |
DATAOBJECT |
ZIA_IXA_DATA_OBJECT |
CHAR |
40 |
Technical name of the data object |
|
2 |
DESCRIPTION |
ZIA_IXA_DATA_OBJECT_TEXT |
CHAR |
79 |
Description of the data object |
c) Data exchange
The data exchange between the external calling system and the SAP system takes place in both directions using a table with a specific structure (technical name: "ZIA_IXA_API_INTREXX_FIELDS"); this is independent of the data objects to be transferred.
|
No. |
Field name |
Data element |
Data type |
Size |
Description |
|---|---|---|---|---|---|
|
1 |
LIST_RECORD |
ZIA_IXA_RECORDNUMBER |
INT4 |
10 |
Data record number |
|
2 |
STRUC_NAME |
ZIA_IXA_STRUCTURE |
CHAR |
30 |
Structure name |
|
3 |
STRUC_RECORD |
ZIA_IXA_RECORDNUMBER |
INT4 |
10 |
Record number within the structure |
|
4 |
FIELD_NAME |
ZIA_IXA_FIELDNAME |
CHAR |
30 |
Field name |
|
5 |
FIELD_VALUE |
ZIA_IXA_FIELDVALUE |
CHAR |
255 |
Field value |
With this structure, every SAP internal table structure (e.g. an internal table) can be modelled without the API having to be modified. Complex structures that incorporate tables or references are an exception to this. Field (1) always contains the number of the transferred data record and can be depicted easily using the SY-TABIX of the table to be transferred. Field (4) contains the name of the column (or field name of the structure) and field (5) contains the actual value. Fields (2) and (3) are intended to record substructures (e.g. when transferring assignments with positions). To do that, the calling system must be able to process the dependent data within a call. For the regular call without dependent data, the fields are populated as follows:
-
STRUC_NAME = "DEFAULT"
-
STRUC_RECORD = "0"
The following example demonstrates the transformation of an internal SAP table into the API transfer table for the data exchange.
d) Key information
Key information The structure for exchanging key information (technical name: "ZIA_IXA_API_INTREXX_KEYS") directly relates to the structure for the data exchange. This structure is especially required within the API method "get_Detail" in order to assign a unique key to every data record within the structure for the data exchange - denoted by the field "LIST_RECORD".
|
No. |
Field name |
Data element |
Data type |
Size |
Description |
|---|---|---|---|---|---|
|
1 |
LIST_RECORD |
ZIA_IXA_RECORDNUMBER |
INT4 |
10 |
Data record number |
|
2 |
LIST_KEY |
ZIA_IXA_KEYFIELD |
CHAR |
128 |
Key field value |
Assuming that the field "PARTNER", from our previous example, is a unique key, the table for the key information would have to look like this:
Because you have the ability within the SAP system to uniquely denote a data record using a combination of fields, a special procedure in the processing modules must be verified so that data records, which are read using "get_List", can also be identified uniquely in the other API methods (e.g. "get_Detail"). Because of the client concept, there is already a primary key for most of the SAP tables; this primary key is formed from at least two database fields. In the context of an external call, the client field can be disregarded, because the login already takes place on a client. It is vital that access to other clients or to client-dependent data is checked. An example of an approach that has proven itself is to write all of the actual key fields of the SAP table (however without the clients) with a separator in the "LIST_KEY" field. The following ABAP coding could, for example, be used to generate a unique key consisting of three table fields:
concatenate lv_key1
lv_key2
lv_key3< into lv_key_extern
separated by '~'.
The opposite way can be implemented
split lv_key_extern
at '~'
lv_key3
into lv_key1
lv_key2
lv_key3
using Of course, other characters apart from "~" can be used as the separator. A character should be used that does not appear in the table's key fields. If it cannot be avoided, that the selected separator appears in key fields, a mapping can also be created using a GUID function. GUIDs (Global Unique ID) can be generated with the SAP system using the functional module "GUID_CREATE".
e) Messages
Messages which can be generated in the SAP system (e.g. warning or error messages) can also be important for the external invoking system. Therefore, it is usually possible to transfer messages to the external system in a message table (technical name "ZIA_IXA_API_INTREXX_MESSAGES").
|
No. |
Field name |
Data element |
Data type |
Size |
Description |
|---|---|---|---|---|---|
|
1 |
TYPE |
BAPI_MTYPE |
CHAR |
1 |
Message type |
|
2 |
MESSAGE |
BAPI_MSG |
CHAR |
220 |
Message text |
|
3 |
TECH_ID |
SYMSGID |
CHAR |
20 |
Message class |
|
4 |
TECH_NO |
SYMSGNO |
NUMC |
3 |
Message number |
The used structure is similar to the structure "BAPIRET2" known from the BAPIs. The more technical information is admittedly foregone because the external systems generally cannot process this information. In this environement, only fields 1-2 are relevant which containt the message type and its text. Fields 3-4 are specific to SAP and are only suitable for helping developers/administrators, who have SAP access, find errors. The message type from field 1 determines the success of an action. The external system should interpret the transferred values as follows:
|
Message type |
Meaning in SAP |
External meaning for the invoking system |
|---|---|---|
|
E |
Errors have occurred. |
Display error message(s). |
|
A |
The function had to be cancelled. |
Display error message(s). |
|
X |
A fatal exception has occurred. |
Display error message(s). |
|
W |
The function ended with warnings. |
Function successful. Possibly Issue warning message. |
|
I |
The function was completed successfully. Messages with information for the user is available. |
Function successful. |
|
S |
The function was completed successfully. Status messages are available. |
Function successful. |
f) Filter criteria
Filter criteria – as used, for example, when selecting data in the API method "get_List" – are passed in tabular form within the API (technical name of the structure: "ZIA_IXA_API_INTREXX_FILTER").
|
No. |
Field name |
Data element |
Data type |
Size |
Description |
|---|---|---|---|---|---|
|
1 |
SELPOS |
NUMC |
4 |
Postition of the filter row. Used for the sorting. |
|
|
2 |
COMBINE |
CHAR |
5 |
Combination type with the previous row. Possible values: <AND|OR>. This does not affect the first filter row and will not be evaluated. Despite that, it is populated with AND. |
|
|
3 |
LPARENTHESIS |
INT1 |
3 |
Number of opening parentheses |
|
|
4 |
FIELD_NAME |
CHAR |
30 |
Field name of the filtered data objects. |
|
|
5 |
OPERAND |
CHAR |
2 |
Operand (see possible values) |
|
|
6 |
VALUE_LOW |
CHAR |
70 |
Field value |
|
|
7 |
VALUE_HIGH |
CHAR |
70 |
Field value 2 for interval operands |
|
|
8 |
LPARENTHESIS |
INT1 |
3 |
Number of closing parentheses |
Possible operandens (field 5):
|
Operand |
Meaning |
|
|---|---|---|
|
EQ |
= |
Equal to |
|
NE |
<> |
Unequal |
|
LE |
<= |
Less than or equal to |
|
GE |
>= |
Greater than or equal to |
|
LT |
< |
Less than |
|
GT |
> |
greater than |
|
BT |
between |
Between <value_low> and <value_high> |
|
CP |
like |
Corresponds to the sample |
With this table, even comple WHERE clauses with staplings can be transferred. The example
WHERE ( FIELDNAME1 = 'HAMBURG' OR FIELDNAME1 LIKE '*dorf' ) AND ( FIELDNAME2 = 1 OR FIELDNAME2 = 2 )
is modelled as follows:
As a wildcard, the character * can be used. If required and depending on the procedure, this must be mapped using the usual character for databases %.
g) Requested data fields
In some functions, a table (technical name of the structure: "ZIA_IXA_API_INTREXX_RQ_FLDS") is delivered with the field names which should be transferred. The background to this functionality: only the information which can be processed (e.g. displayed) by the external invoking system is transferred. The leasing SAP table contains, for example for the business partner (Table "BUT000"), more than 80 possible columns. In many scenarios, only approx. 10 columns are actually needed. Without this functionality, 8 times the fields required are transferred. With large selections, these unnecessary data transfers lead to performance problems. The table only contains one column which is populated with the field names of the required fields. If the table is empty, everything is transferred.
h) Sorting instructions
Instructions are required for the sorted selection of data. These instructions are transferred in a table (technical name of the structure "ZIA_IXA_API_INTREXX_ORDERBY").
|
No. |
Field name |
Data element |
Data type |
Size |
Description |
|---|---|---|---|---|---|
|
1 |
ORDERPOS |
NUMC |
4 |
Position within the table |
|
|
2 |
FIELD_NAME |
ZIA_IXA_FIELDNAME |
CHAR |
30 |
Field name |
|
3 |
ORDERTYPE |
ZIA_IXA_ORDERBY_ORDER |
CHAR |
1 |
Sorting; possible values: |
API RFC functions
This section describes the externally invoked API functional modules. Certain parameters, which are common to all, are used in all functions which will not be explained in detail later.
|
Parameters |
Meaning |
|---|---|
|
IX_CONTROL |
Control structure; contains information about the caller and is used to identify the processing module. |
|
ET_MESSAGES |
Contains Messages from the structure |
|
EV_ERROR |
Contains "X", if the API method call terminated with errors. If no errors occurred, then this parameter remains empty. The parameter "ET_MESSAGES" contains potentially present error messages. |
a) get_DataObjects
The API method"get_DataObjects" identifies the possible data objects of a processing module. Externally, the RFC functional module "Z_IA_IXA_API_GET_DATA_OBJECTS" will be called up to do that.
FUNCTION z_ia_ixa_api_get_data_objects.
*"----------------------------------------------------------------------
*"*"Lokale Schnittstelle:
*" IMPORTING
*" VALUE(IS_CONTROL) TYPE ZIA_IXA_API_INTREXX_CONTROL
*" VALUE(IV_MAX_ROWS) TYPE SYTABIX DEFAULT 100
*" VALUE(IV_WILDCARD) TYPE ZIA_IXA_FIELDVALUE OPTIONAL
*" EXPORTING
*" VALUE(EV_ERROR) TYPE XFELD
*" TABLES
*" ET_MESSAGES STRUCTURE ZIA_IXA_API_INTREXX_MESSAGES OPTIONAL
*" ET_DATA_OBJECTS STRUCTURE ZIA_IXA_API_INTREXX_DATAOBJ OPTIONAL
*"----------------------------------------------------------------------
A limitation using wildcards (parameter "IV_WILDCARD";; Wildcard character *) should be enabled. For performance reasons, the maximum number of results can be limited using the parameter "IV_MAX_ROWS". The values 0 or <0 mean that a limitation of results is not active. The available Data objects are delivered to the invoking system in the parameter "ET_DATA_OBJECTS".
b) Get_MetaInfo
The API method "get_MetaInfo" identifies the technical properties of a data object. Externally, the RFC functional module "Z_IA_IXA_API_GET_METAINFO" will be called up to do that.
FUNCTION Z_IA_IXA_API_GET_METAINFO
*"----------------------------------------------------------------------
*"*"Lokale Schnittstelle:
*" IMPORTING
*" VALUE(IS_CONTROL) TYPE ZIA_IXA_API_INTREXX_CONTROL
*" EXPORTING
*" VALUE(EV_ERROR) TYPE XFELD
*" TABLES
*" ET_MESSAGES STRUCTURE ZIA_IXA_API_INTREXX_MESSAGES OPTIONAL
*" ET_RESULT_VALUES STRUCTURE ZIA_IXA_API_INTREXX_FIELDS OPTIONAL
*" ET_RESULT_KEYS STRUCTURE ZIA_IXA_API_INTREXX_KEYS OPTIONAL
*"----------------------------------------------------------------------
The technical properties are transferred in the parameters "ET_RESULT_VALUES" and "ET_RESULT_KEYS" (More information is available here: Data exchange and Key information). As opposed to the population regulation modelled there, a deviating data transfer is modelled here. The basis for this transfer is information in the structure "DFIES". These are, for example, identified using the SAP functional module "DDIF_FIELDINFO_GET". The external, invoking system decides for itself which of the information from the structure "DFIES" it will use for its purposes. What's definite is that the field "FIELDNAME" will be foundational for the external modelling. The following two models demonstrated the necessary transformation of the technical information in the export parameter. The table "ET_RESULT_VALUES" contains the field names of the data object, "ET_RESULT_KEYS" contains more information about the field.
c) get_List
The API method "get_List" identifies data records from a data object. Externally, the RFC functional module "Z_IA_IXA_API_GET_LIST" will be called up to do that.
FUNCTION z_ia_ixa_api_get_list
*"----------------------------------------------------------------------
*"*"Lokale Schnittstelle:
*" IMPORTING
*" VALUE(IS_CONTROL) TYPE ZIA_IXA_API_INTREXX_CONTROL
*" VALUE(IV_MAX_ROWS) TYPE SYTABIX DEFAULT 100
*" VALUE(IV_START_ROW) TYPE SYTABIX DEFAULT 0
*" VALUE(IV_ORDERBY) TYPE ZIA_IXA_FIELDNAME OPTIONAL
*" VALUE(IV_CHECK_LANGUAGE) TYPE XFELD DEFAULT ' '
*" EXPORTING
*" VALUE(EV_ERROR) TYPE XFELD
*" VALUE(EV_COUNT) TYPE ZIA_IXA_LIST_COUNT
*" TABLES
*" IT_FIELDS STRUCTURE ZIA_IXA_API_INTREXX_FIELDS OPTIONAL
*" ET_MESSAGES STRUCTURE ZIA_IXA_API_INTREXX_MESSAGES OPTIONAL
*" ET_RESULT_VALUES STRUCTURE ZIA_IXA_API_INTREXX_FIELDS OPTIONAL
*" ET_RESULT_KEYS STRUCTURE ZIA_IXA_API_INTREXX_KEYS OPTIONAL
*" IT_FILTER STRUCTURE ZIA_IXA_API_INTREXX_FILTER OPTIONAL
*" IT_REQUESTED STRUCTURE ZIA_IXA_API_INTREXX_RQ_FLDS OPTIONAL
*" IT_ORDERBY STRUCTURE ZIA_IXA_API_INTREXX_ORDERBY OPTIONAL
*"----------------------------------------------------------------------
The limiting properties are transferred in the parameter "IT_FILTER" (cf. Filter criteria). As an alternative, the option to implement a simple selection form using the fields "IT_FIELDS" (cf. Data exchange) was created. The table "IT_FIELDS" would then contain field names and the desired values (also with wildcards) that should be used for selecting. Which of the two selection options should be used is determined by the external calling system and the identified processing module. If possible, the alternative via "IT_FILTER" should be implemented. The number of identified data records is transferred in the parameter "EV_COUNT". For performance reasons, offset access to the data has been made possible using the parameters "IV_MAX_ROWS" and "IV_START_ROW". An external browsing of very large data volumes can be enabled by doing this by transferring only "<IV_MAX_ROWS>" data records starting from the data record "<IV_START_ROW>". This function is deactivated if the value 0 is found in the parameter "IV_START_ROW". If the external calling system requires a sorting of the data, it can make this known using the parameter "IT_ORDERBY" (cf. sorting instructions) or "IV_ORDERBY". Sorting the data at the caller does not make sense because this only works if all of the data is transferred. A sorting is almost impossible for large data volumes, which can only be processed meaningfully via offset access. The parameter "IT_ORDERBY" has priority over "IV_ORDERBY". If the table is populated, the sorting instruction will be processed. The parameter "IV_CHECK_LANGUAGE" controls the evaluation of the language of external login. Especially when selecting language-dependent customizing tables, this parameter can (activate by "X") control the filtering of all data records that do not correspond to the external language. The identified data records are prepared in the parameters "ET_RESULT_VALUES" and "ET_RESULT_KEYS". Populating this results table is described in detail in the chapters Data exchange and Key information. The parameter "IT_REQUESTED" (cf. Requested data fields) contains the data fields that are explicitly requested by the caller. This can also help improve performance when making a selection because the data fields that are not requested are not transferred. If this parameter is not populated, every data field is transferred.
d) get_Detail
The API method "get_Detail" identifies the details of a data record which is uniquely identified using the transferred key. Externally, the RFC functional module "Z_IA_IXA_API_GET_DETAIL" will be called up to do that.
FUNCTION z_ia_ixa_api_get_detail
*"----------------------------------------------------------------------
*"*"Lokale Schnittstelle:
*" IMPORTING
*" VALUE(IS_CONTROL) TYPE ZIA_IXA_API_INTREXX_CONTROL
*" VALUE(IV_KEY) TYPE ZIA_IXA_FIELDVALUE
*" EXPORTING
*" VALUE(EV_ERROR) TYPE XFELD
*" TABLES
*" ET_MESSAGES STRUCTURE ZIA_IXA_API_INTREXX_MESSAGES OPTIONAL
*" ET_RESULT_VALUES STRUCTURE ZIA_IXA_API_INTREXX_FIELDS OPTIONAL
*" IT_REQUESTED STRUCTURE ZIA_IXA_API_INTREXX_RQ_FLDS OPTIONAL
*"----------------------------------------------------------------------
The parameter "IV_KEY" contains the key of the data record just like, for example, when it is identified using the API method "get_List" (cf. Key information). The results are transferred to the parameter "ET_RESULT_VALUES". Populating this table is described in the chapter Data exchange. Because it can only concern one data record, the following constants are presupposed:
-
LISTRECORD = "1"
-
STRUC_NAME = "DEFAULT"
-
STRUC_RECORD = "0"
The amount of data can be limited using the parameter "IT_REQUESTED" (cf. Requested data fields).
e) modify
The API method "modify" allows the addition of new or editing of existing data records. Externally, the RFC functional module "Z_IA_IXA_API_MODIFY" will be called up to do that.
FUNCTION z_ia_ixa_api_modify
*"----------------------------------------------------------------------
*"*"Lokale Schnittstelle:
*" IMPORTING
*" VALUE(IS_CONTROL) TYPE ZIA_IXA_API_INTREXX_CONTROL
*" VALUE(IV_KEY) TYPE ZIA_IXA_FIELDVALUE OPTIONAL
*" EXPORTING
*" VALUE(EV_ERROR) TYPE XFELD
*" VALUE(EV_KEY) TYPE ZIA_IXA_FIELDVALUE
*" TABLES
*" ET_MESSAGES STRUCTURE ZIA_IXA_API_INTREXX_MESSAGES OPTIONAL
*" ET_FIELDS STRUCTURE ZIA_IXA_API_INTREXX_FIELDS OPTIONAL
*" IT_FIELDS STRUCTURE ZIA_IXA_API_INTREXX_FIELDS OPTIONAL
*"----------------------------------------------------------------------
The parameter IV_KEY contains the key of an existing data record (cf. Key information). A value of -1 or an unpopulated parameter "IV_KEY" denote a new data record. The data fields are transferred in the parameter "IT_FIELDS" (cf. Data exchange). Old and new keys (for new data records) are expected in the parameter "EV_KEY". In principle, requirements can be satisfied that individual data fields should be modified within the processing module. Therefore, the actual values must be returned to the caller in the parameter "ET_FIELDS". This can be simplifed by generating "ET_FIELDS" as a copy of "IT_FIELDS". The API method "modify" can contain an exception for the datahandler "GENERIC_STORE". This handler enables - according to the definition from the chapter Data handler - data groups to be modeled in external calls and the data to be saved in SAP. To do this, the SAP system must receive information about the state of the arriving data of the external system. This was solved in the reference implementations with Intrexx, in the parameter "IT_FIELDS" information about the meta information was exchanged ("STRUC_NAME = "TRANSFER"") in addition to the data fields ("STRUC_NAME = "DEFAULT""). The following screenshot shows the function in debug mode.
f) delete
The API method Delete allows the deletion of existing data records from the data record. Externally, the RFC functional module "Z_IA_IXA_API_DELETE" will be called up to do that.
FUNCTION z_ia_ixa_api_modify
*"----------------------------------------------------------------------
*"*"Lokale Schnittstelle:
*" IMPORTING
*" VALUE(IS_CONTROL) TYPE ZIA_IXA_API_INTREXX_CONTROL
*" VALUE(IV_KEY) TYPE ZIA_IXA_FIELDVALUE OPTIONAL
*" EXPORTING
*" VALUE(EV_ERROR) TYPE XFELD
*" TABLES
*" ET_MESSAGES STRUCTURE ZIA_IXA_API_INTREXX_MESSAGES OPTIONAL
*" ET_FIELDS STRUCTURE ZIA_IXA_API_INTREXX_FIELDS OPTIONAL
*"----------------------------------------------------------------------
The data record that should be deleted is identified via the parameter "IV_KEY" (cf. Key information). The parameter "ET_FIELDS" (cf. Data exchange) contains the data fields of the deleted data record.
g) update_temp_key
The API method "update_temp_key" allows the data to be stored in the external system and in SAP at the same time. Externally, the RFC functional module "Z_IA_IXA_API_UPDATE_TEMP_KEY" will be called up to do that.
FUNCTION z_ia_ixa_api_update_temp_key
*"----------------------------------------------------------------------
*"*"Lokale Schnittstelle:
*" IMPORTING
*" VALUE(IS_CONTROL) TYPE ZIA_IXA_API_INTREXX_CONTROL
*" VALUE(IV_KEY) TYPE ZIA_IXA_FIELDVALUE OPTIONAL
*" VALUE(IV_KEY_NEW) TYPE ZIA_IXA_FIELDVALUE OPTIONAL
*" EXPORTING
*" VALUE(EV_ERROR) TYPE XFELD
*" VALUE(EV_KEY) TYPE ZIA_IXA_FIELDVALUE
*" TABLES
*" ET_MESSAGES STRUCTURE ZIA_IXA_API_INTREXX_MESSAGES OPTIONAL
With this API method, scenarios can be modelled where the externally created data is initially checked by the SAP system (API method "modify"). In SAP, the data is given a temporary key (e.g. GUID). The external data is only saved when the test in SAP returns no errors. The key assigned there is then sent once more to SAP to maintain the relationship between the data. The parameter "IV_KEY" contains the temporary key, "IV_KEY_NEW" the key from the external system. "EV_KEY" contains the key that can be used to identify the data record in SAP in the future. This should contain the value from "IV_KEY_NEW". The behavior during such scenarios is dependent in particular on the collaboration between the external caller and the SAP-internal processing module.
Processing modules
Processing modules ABAP object classes, which receive and process calls from the RFC API after the object generation, are referred to as processing modules.
API Interface
API interface The API methods of the processing modules are implemented in the "Z_IF_IA_IXA_INTREXX_API" interface.
Each API method from the RFC API has an equivalent in the interface. There are two additional interface methods available:
|
Method |
Meaning |
|---|---|
|
INITIALIZE |
Is called immediately after the create object within the RFC API. Can be used to initialize default values and the like. |
|
PREPARE_USAGE_AFTER_CREATION |
The call takes place before the call of the actual API method. This method is suitable for creating dynamic data structures or for setting parameters. |
The API methods of the interface depict the parameters of the RFC API 1:1. The following example demonstrates the API method "get_List" in the interface.
The parameter "IS_CONTROL" is not found in any interface method. This is available as the attribute "ME->IX_CONTROL" of the object instance (cf. Root object). Additionally, the parameter "CV_PROCESSED" is included in every API method. Using this parameter, the RFC API can recognize whether the called API method is available using the processing module. In this way, a recognition is made in the external calling system that, for example, a processing module does not make a "modify" available.
Every implemenation must set this parameter CV_PROCESSED to "X", regardless of whether the method is processed with or without errors.
To report errors, the parameter "EV_ERROR" is available in the context of the report table "ET_MESSAGES" (cf. API RFC functions).
Root object
Root object The class "Z_CL_IA_IXA_ROOT" is used as the mother of all processing modules. Every processing module must be inheirited from this class or one of its descendants. This root object is rather abstract, but implements the API interface from Api-Interface and some attributes and methods. The following figure depicts the root object with its own sample implementations for processing modules as descendants, like they are available for SAP NetWeaver systems as well as (backwards compatible) for SAP systems with the basis system 4.6.
Registering processing modules
New processing modules can be created easily by inheriting from existing classes from the CORE API Root object or from custom processing modules that were already inherited. Creating new processing modules is described in the chapter Implementing custom processing modules. Every processing module needs to be registered before it can be used. This is done by using a customizing table and is documented in the chapter Customizing - Finding processing modules.
Finding processing module
Information about the invoking external data group is available from the external system (e.g. Intrexx). In every case, these are the datahandler and a unique identifier of the data object. This and additional information is available via the Control structure.
Using this information, a processing module is identified via a customizing table (desribed in the chapter Mapping external data groups to processing modules). If it is not possible to identify a suitable entry using the mapping modelled there between external data groups and SAP-internal processing modules, the processing module will be used that is configured as the preset at 0. Usually, this will be the processing module for the datahandler "GENERIC_VIEW", because an access to an SAP tables and views is most probable.
Customizing
Customizing The customizing tables of the SAP portal plugin were created to some extent without table maintenance to be backwards compatible up to 4.6 Basis. Therefore, the tables are maintainable either using transaction SM30 or SE16. In the following sections, all screenshots were created using transaction SE16. The views can vary depending on the system version and maintenance transaction.
Basic settings
Basic settings The customizing table "ZIAC_IXACONFIG" contains the basic settings of the SAP portal plugin.
The field's meanings are as follows:
|
Field |
Meaning |
|---|---|
|
DEFOBJECT |
Determines the processing module that is used if this is not already predefined by other settings. The processing module "GENERIC_VIEW" is the preset. |
|
LOG_ACTIVE |
Activates the logging of all API actions. |
|
BALLOG_ACTIVE |
Activates the logging of all messages (cf. Messages and logging). |
|
NEWDGREGISTER |
Name of the functional component that registers previously unknown external data groups for the datahandler "GENERIC_STORE". |
Finding processing module
The following customizing tables are responsible for finding processing modules.
a) Registering processing modules
The table "ZIAC_IXAOBJECTS" registered processing modules. Above all, the ABAP object's classes are stored here.
|
Field |
Meaning |
|---|---|
|
OBJECTTYPE |
Unique name for the processing module. Naming conventions have not been defined. Up until now, "GENERIC*" was used for generic processing modules and "BAPI*" for BAPI-relevant business objects. |
|
CLASS |
The name of the processing class (an inheritor of the root object or a descendant). |
|
STRUC_TRANSFER |
The name of a DDIC structure that is used for the data exchange with the external caller. If this value is populated, the API method "get_MetaInfo" can refer to this value and does not need to be redefined. |
|
STRUC_DATA |
Can be used to generate internal data structures generically. |
|
MASTER_TAB |
Can be used to implement generic select statements. |
|
CUSTOMIZING_TAB |
Can be used to enable generic accesses to customizing tables. |
|
FIELD_KEY |
Name of the field within the <MASTER_TAB> which contains the unique key. |
|
PARAMETERS* |
Can be used as additional customizing to enable various behaviors with a processing class, for example. These parameters are available within the processing class (cf. "Inherited attributes of the root object"). |
The maintenance of "<OBJECTTYPE>" and "<CLASS>" is imperative. If "<STRUC_TRANSFER>" is maintained and the processing module is a descendent of the "GENERIC_VIEW" processing module, the method "get_MetaInfo" implemented there can be used.
b) Mapping external data groups to processing modules
The table "ZIAC_IXAMAPOBJ" contains information about which external data group is mapped to which processing module.
|
Field |
Meaning |
|---|---|
|
DATAHANDLER |
Determines the externally used datahandler. |
|
IX_DATAGROUP |
Externally used data group (e.g. table name). |
|
IX_DATARANGE |
Additional, optional limitation of a view for a data group (usually empty). |
|
IX_OBJECTTYPE |
Determines which processing module should be used for the combination of DATAHANDLER + IX_DATAGROUP [+ IX_DATARANGE]. |
|
PARAMETERS* |
The parameters can be used within the processing module as an additional controlling parameter. |
|
IX_LOCKING |
Activate the locking concept (= X). |
|
IX_TIMEOUT |
Timeout parameter for the locking concept. |
|
EXIT_FUNCTION |
This parameter contains the name of a functional component that can be used as an Exit within the processing module. Whether this Exit is used depends on the processing module. |
|
MAPPED_DATAGROUP |
If this parameter is populated, the parameter "IX_DATAGROUP" is handled as an alias. The parameter "<MAPPED_DATAGROUP>" is then used for the processing. This option can be useful if the same data group (e.g. SAP customizing table) is to be processed with the same processing module (e.g. "GENERIC_VIEW") in different ways (e.g. variant 1: as a real table; variant 2: as a text table for reading customizing data) |
|
TRACE_ACTIVE |
If this parameter is set (= X), messages for this data group will also be logged. |
Permissions concept
Access to SAP data objects is protected in the SAP portal plugin using the permissions objects:
-
ZIA_IXA_AC
-
ZIA_PISAP
Additionally, even more permissions are required to enable external access via RFC. More specifically this concerns the following permissions that need to made available to the service user for the portal access as a minimum:
|
Permissions object |
Permissions |
Value |
|---|---|---|
|
ZIA_IXA_AC |
Activity |
01, 02, 03, 06, 16 |
|
IXA: Function of the Intrexx API |
delete, getdataobj, getdetail, getlist, getmeta, modify, update_k |
|
|
ZIA_PISAP |
ESB: API function |
GETDATA, GETDATAOBJ, GETDIST, GETF4, GETMETA |
|
ESB: ID of a data source |
* |
|
|
S_RFC |
Activity |
16 |
|
Name of RFC object to be protected |
RFC1, SDIFRUNTIME, SLCH, SLST, SYST, SYSU, ZIA_IXA_API |
|
|
Type of RFC object to be protected |
ID |
|
|
ESB: ID of a data source |
FUGR |
|
|
S_TABU_DIS |
Activity |
02 |
|
Permissions group |
&NC& |
If you provide the service user with "SAP_ALL", please consider that this profile also has to initially be generated again to accept the new permissions object from the SAP portal plugin. This can be achieved with transaction "SU28", for example. Should permission problems occur, or you would like to add another limitation, you can use the permissions trace (ST05) to determine the used values.
Misc. framework functions
Logging
a) Logging of all API accesses
The table "ZIAM_IXALOG" contains information about every access to the RFC API, if the logging was activated ("Flag LOG_ACTIVE") in the customizing (cf. Basic settings).
The data records contain information for the execution as well as information from the external caller.
Using the transaction "ZIA_IXA_LOG", this information can be analyzed using a report.
Expanded message logging
Another option for logging, and especially well-suited for finding errors, is the application log (transaction SLG1). This is activated with the flag BALLOG_ACTIVE (cf. Basic settings). If both loggings are activated, all error messages from the API parameter "ET_MESSAGES" (cf. Messages) are written to the application log and can be analyzed with the transaction SLG1.
The session GUID from the chapter Control structure is used as the external identifier here. Typically, this contains the identification of an internet session.
Using the session GUID, the data records from the log table "ZIAM_IXALOG" can be linked to one another once more. The message contains the SAP message class and message number (if available) in brackets. The cause of the message can then potentially be identified using transaction SE91 and the cross-reference. Furthermore, troubleshooting is potentially possible in the OSS if the messages come from BAPI functions.
Trace mode for troubleshooting
For troubleshooting processing modules, this logging can be expanded to message that are not error messages. This enables, for example, the output of warning and status messages when invoking BAPI functions. The trace mode is activated with the flag "TRACE_ACTIVE" in the finding of the processing modules (cf. Mapping external data groups to processing modules).
Locking concept
A simple locking concept has been prepared in the SAP portal plugin which is best suited for use in the internet environment without statuses. Within the RFC API, every access to an object can be monitored. This means that multiple internet users can access one SAP data record at the same time and even switch to the editing mode without locking one another out. Only the first write access is however allowed. All later write accesses will be prohibited. The following graphic demonstrates this behavior.
The API accesses are cancelled when errors occur. The reason is transferred to the invoking system in the parameter "ET_MESSAGES".
An additional lock can be integrated when the processing modules model the SAP-typical locking logic internally. However, this does not make a lot of sense for read accesses because external callers could potentially lock SAP transactions. In general, checking the SAP locks at the time of change should be sufficient. If BAPI calls are used, SAP uses this procedure in the exact same way - the lock is intitially used at the time of writing.
The locking concept described above is activated in the processing modules (Flag "IX_LOCKING"). With the timeout parameter "IX_TIMEOUT""; (specified in seconds), the write accesses can also be parameterized. The screenshot shows this setting for the example from the chapter Processing modules. Here, the locking concept of the SAP portal plugin as well as the SAP-typical locks of the business partner are used.
You can test this logic with parallel change accesses via external access and simultaneous editing of the SAP business partner in transaction BP.
EXIT functions
Conceptionally, the use of EXIT functions has been provided, these are called in the respective processing modules. The assignment is possible in the customizing of the finding of a processing modules. The actual call is a matter for the process module. The interface of the functional component can orientate itself by the template "Z_IA_IXA_API_EXIT_TEMPLATE". Using this is especially well suited within the API function "modify" to check and/or modify data.
Number sequencing
Using the method "GET_NEW_NUMBER_KEY", a simple number sequencing is available that identifies an incremental integer value as a key. The number sequencing can manage without an SAP sequencing object and are administrated for each external data group.
Conversion - Internal vs external
In general, external systems use a different presentation of data types than SAP. The data type "Date" will serve as an example. Here SAP uses the format "<YEAR><MONTH><DAY>" internally (e.g. "20070626"). Externally, "2007-06-26" is commonly used. The root object uses both of the following methods internally:
-
MAP_FIELDVALUE_IX_TO_SAP - Maps the external presentation to the internal
-
MAP_FIELDVALUE_SAP_TO_IX - Maps the internal presentation to the external
Custom conversions can be implemented using inheritance.
10. External use of the SAP portal plugin
The plugin described here was primarily developed for external use by non-SAP systems. To use the functionality described here, the API functions must be available in the desired external programming language. The connectors (https://service.sap.com/connectors) provided by SAP AG are particularly well-suited for this - With the SAP Java Connector (SAP JCo) and the .Net-Connector. leading the way. Both of these come with generation tools that create proxy modules in the respective programming environment for a complex SAP RFC API. The SAP Enterprise Connector is suited for Java, and this is available in the SAP NetWeaver Developer Studio.
More information
SAP Trust Manager SSO configuration
API description Part 1 - Overview
API description Part 3 - Implementing custom processing modules
API description Part 4 - Sample coding
Developer's Manual Part 2 - Integration scenario, SAP external data group
Developer's Manual Part 3 - Scripting integration scenario
Developer's Manual Part 4 - Personalized SAP Access / Single Sign On (SSO)
Email us