Connector for SAP Business Suite - API Description Part 2 - SAP Portal Plugin

Development aims

The following development aims are in the foreground when implementing the SAP Portal Plugin:

  • No JAVA adaptations for requirements 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 enhancement concept was implemented within SAP ABAP and that the interface between the systems remained rigid.

  • Use of 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 BAPI) are sufficient. from the release) are usually not sufficient, are implemented incompletely or partially incorrectly 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 straightforward 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

Further details on the RFC API can be found here.

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.

Finding a suitable SAP system has already been 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

The ABAP Objects concept was used for the processing modules in order to exploit advantages during implementation (primarily through inheritance). 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. The requirement for read access to tables and views can therefore be solved more easily via a general processing module (e.g. "GENERIC_VIEW") than write access to SAP data objects. Requirements such as blocking concepts, test logics, etc. must be met here. must be observed. 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 data handler is always used if no other data handler is 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. This can be done, for example, by using the classification or similar. Functions can be achieved.

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 set is forwarded to the "modify" API method.

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 developments (also known as development classes in earlier releases of SAP Basis) for the RFC API can be found in the "ZIA_INTREXX_API" package in the "ZIA_IXA_API" function group. To use the SAP Plugin's functionality externally, you only have to allow the external access for this function group. Further information on the authorization concept can be found here.

Used structures

a) Control structure

The control structure (technically "ZIA_IXA_API_INTREXX_CONTROL") is used as the import parameter "IS_CONTROL" of each API RFC function block to make certain external parameters available.

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

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). Further information can be found here. 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. The variant of the data handler can, for example, control the behavior of the processing module (default 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

Possible data objects of the processing module can be determined within the API function "get_DataObjects". The technical names and a description are returned there 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 via a table with a fixed structure (technical name "ZIA_IXA_API_INTREXX_FIELDS"), which 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

The structure for the exchange of key information (technical name "ZIA_IXA_API_INTREXX_KEYS") is directly related to the structure for data exchange. This structure is primarily required within the "get_Detail" API method in order to assign a unique key to each data record within the structure for data exchange, identified via the "LIST_RECORD" field.

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 "PARTNER" field in the previous example is a unique key, the table for the key information should look as follows:

As it is possible within the SAP system to uniquely identify a data record using a combination of fields, a special procedure must be checked here in the processing modules in order to uniquely identify data records that were read with "get_List" 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. For example, the procedure of writing all actual key fields of the SAP table (but without the client) into the "LIST_KEY" field separated by a separator has proven to be suitable. 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, characters other than "~" can also be used as separators. A character should be used that does not appear in the table's key fields. If it cannot be ruled out that the selected separator occurs in key fields, a mapping can also be mapped using a GUID function. GUIDs (globally unique ID) can be generated within the SAP system using the "GUID_CREATE" function module.

e) Messages

Messages that can be generated in SAP (e.g. warning or error messages) can also be important for the external calling system. It is therefore generally possible to transmit 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 structure used is similar to the familiar "BAPIRET2" structure 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. Issue a warning message if necessary.

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 - such as those used when selecting data in the "get_List" API method - are transferred 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 (s. 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

in the interval from <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. Depending on the actual procedure, this may then have to be mapped to the character %, which is standard for databases.

g) Requested data fields

In some functions, a table (technical name of the structure "ZIA_IXA_API_INTREXX_RQ_FLDS") is transferred with the field names that are to be transferred. The background to this functionality: only the information which can be processed (e.g. displayed) by the external invoking system is transferred. For example, the leading SAP table contains more than 80 possible columns for the business partner (table "BUT000"). 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 this table is empty, everything is transferred.

h) Sorting instructions

The sorted selection of data requires statements that 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:
A - ascending
D - descending

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 determine the processing module.

ET_MESSAGES

Contains messages of the structure

EV_ERROR

Contains "X" if the API method call was terminated with errors. This parameter is not filled if there are no errors. The "ET_MESSAGES" parameter contains any error messages that may be present.

a) get_DataObjects

The API method "get_DataObjects" determines the possible data objects of a processing module. The RFC function module "Z_IA_IXA_API_GET_DATA_OBJECTS" is called externally for this purpose.

            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 restriction via wildcards (parameter "IV_WILDCARD"; wildcard character *) must be enabled. For performance reasons, the maximum number of hits can be restricted using the "IV_MAX_ROWS" parameter. The values 0 or <0 mean that no hit restriction is active. The available data objects are transferred to the calling system in the "ET_DATA_OBJECTS" parameter.

b) Get_MetaInfo

The API method get_MetaInfo determines the technical properties of a data object. The RFC function module "Z_IA_IXA_API_GET_METAINFO" is called externally for this purpose.

            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" (further information under Data exchange and key information). As opposed to the population regulation modelled there, a deviating data transfer is modelled here. The basis for the transfer is information in the "DFIES" structure. These are determined using the SAP function module "DDIF_FIELDINFO_GET", for example. The external calling system decides for itself which information from the "DFIES" structure it uses for its own purposes. It is certain that the "FIELDNAME" field will be fundamental for external mapping. The following two models demonstrated the necessary transformation of the technical information in the export parameter. The "ET_RESULT_KEYS" table contains the field names of the data object, "ET_RESULT_KEYS" contains further details on the field.

c) get_List

The API method "get_List" determines data records for a data object. The RFC function module "Z_IA_IXA_API_GET_LIST" is called externally for this purpose.

            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 restrictive characteristics are transferred in the "IT_FILTER" parameter (see filter criteria). Alternatively, it is possible to implement a simple selection mask using the IT_FIELDS fields (see Data exchange). The "IT_FIELDS" table would then contain field names and the desired values (also with wildcards) to be used for selection. 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 should be implemented via "IT_FILTER". The number of data records determined is transferred in the "EV_COUNT" parameter. For performance reasons, offset access to the data was enabled via the parameters "IV_MAX_ROWS" and "IV_START_ROW". This enables external scrolling in very large data sets by only transferring "<IV_MAX_ROWS>" data sets from the "<IV_START_ROW>" data set. The value 0 in the "IV_START_ROW" parameter deactivates this function. If the external calling system requires the data to be sorted, it can indicate this using the parameter "IT_ORDERBY" (see sorting instructions) or "IV_ORDERBY". Sorting the data at the caller is not useful, as this only works if all data is transferred. A sorting is almost impossible for large data volumes, which can only be processed meaningfully via offset access. The "IT_ORDERBY" parameter has priority over "IV_ORDERBY". If the table is filled, this sort instruction is processed. The "IV_CHECK_LANGUAGE" parameter controls the evaluation of the external logon language. Especially when selecting language-dependent customizing tables, this parameter (activated by "X") can control the filtering of all data records that do not correspond to the external language. The data records determined are provided in the "ET_RESULT_VALUES" and "ET_RESULT_KEYS" parameters. The filling of these result tables is described in detail in the chapter Data exchange and key information. The "IT_REQUESTED parameterr (see 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 filled, all data fields are transferred.

d) get_Detail

This method determines details of a data set that is uniquely identified by the transferred key. The RFC function module "Z_IA_IXA_API_GET_DETAIL" is called externally for this purpose.

            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 "IV_KEY" parameter contains the key of the data set, as determined by the "get_List" API method, for example (see Key information). The results are transferred in the "ET_RESULT_VALUES" parameter. The chapter on data exchange describes how to fill this table. 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 via the "IT_REQUESTED" parameter (see Requested data fields), if filled.

e) modify

The "modify" API method allows you to insert new data records or change existing ones. The RFC function module "Z_IA_IXA_API_MODIFY" is called externally for this purpose.

            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 (see Key information). A value of -1 or an unfilled parameter "IV_KEY" indicates a new data record. The data fields are transferred in the "IT_FIELDS" parameter (see data exchange). Old and new keys (for new data records) are expected in the "EV_KEY" parameter. 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 "ET_FIELDS" parameter. To simplify matters, "ET_FIELDS" can be created as a copy of "IT_FIELDS". The API method "modify" can contain a special feature for the data handler "GENERIC_STORE". This handler enables the modeling of data groups in the external caller and the storage of data in SAP - as defined in the Data handler chapter. 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 by exchanging information about the meta information ("STRUC_NAME = "TRANSFER"") in the "IT_FIELDS" parameter in addition to the data fields ("STRUC_NAME = "DEFAULT""). The following screenshot shows the function in debug mode.

f) delete

The "delete" API method enables existing data records to be removed from the data object. The RFC function module "Z_IA_IXA_API_DELETE" is called externally for this purpose.

            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 to be deleted is identified via the "IV_KEY" parameter (see key information). The "ET_FIELDS" parameter (see Data exchange) contains the data fields of the deleted data record.

g) update_temp_key

The API method "update_temp_key" enables data to be held simultaneously in the external system and in SAP. The RFC function module "Z_IA_IXA_API_UPDATE_TEMP_KEY" is called externally for this purpose.

            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

This API method can be used to map scenarios in which the externally entered data is first checked by the SAP system ("modify" API method). 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" contains the key from the external system. "EV_KEY" contains the key under which the data record can be identified 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

ABAP Objects classes that receive and process the calls from the RFC API after object creation are referred to here as processing modules.

API Interface

The API methods of the processing modules are implemented in the "Z_IF_IA_IXA_INTREXX_API" interface.

Each API method from 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, etc. can be used.

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 map the parameters of the RFC API 1:1. The following example shows the API method "get_List" in the interface.

The parameter "IS_CONTROL" is missing in every interface method. This is available as the "ME->IX_CONTROL" attribute of the object instance (see Root object). In addition, the parameter "CV_PROCESSED" is contained in every API method of the interface. The RFC API can use this parameter to recognize whether the called API method is available through the processing module. In this way, for example, it is recognized in the external calling system that a processing module does not provide a "modify".

Each implementation must set this parameter CV_PROCESSED to "X", regardless of whether the method was processed without errors or with errors.

The "EV_ERROR" parameter is available for reporting errors in connection with the "ET_MESSAGES" message table (see API RFC functions).

Root object

The "Z_CL_IA_IXA_ROOT" class 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 simply by inheriting existing classes from the CORE API (see Root object) or already inherited own processing modules. The creation of new processing modules is described in the chapter Implementing your own processing modules. Every processing module needs to be registered before it can be used. This is done using a customizing table and is documented in the section Customizing - Determining processing modules.

Finding processing module

Information about the invoking external data group is available from the external system (e.g. Intrexx). In each case, this is the data handler and a unique identifier for the data object. This information and more is available via the control structure.

This information is used to determine a processing module via a customizing table (described in chapter Mapping external data groups to processing modules). If it is not possible to determine a suitable entry using the mapping between external data groups and SAP-internal processing modules shown there, the processing module that was configured as the default setting under 0 is used. In most cases, this will be the processing module for the data handler "GENERIC_VIEW", as access to SAP tables and views is most likely.

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

The customizing table "ZIAC_IXACONFIG" contains basic settings of the SAP Portal Plugin.

The field's meanings are as follows:

Field

Meaning

DEFOBJECT

Specifies the processing module that is used if this is not already specified by other settings. The default setting is the "GENERIC_VIEW" processing module.

LOG_ACTIVE

Activates the logging of all API actions.

BALLOG_ACTIVE

Activates the logging of all messages (see 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 "ZIAC_IXAOBJECTS" table contains 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. Previously, "GENERIC*" was used for generic processing modules and "BAPI*" for BAPI-related 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 filled, the API method "get_MetaInfo" can access 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> that 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 (see "Inherited attributes of the root object").

It is essential to maintain the "<OBJECTTYPE>" and "< CLASS>". If "<STRUC_TRANSFER>" is maintained and the processing module is a descendant of the "GENERIC_VIEW" processing module, the "get_MetaInfo" method implemented there can be used.

b) Mapping external data groups to processing modules

The "ZIAC_IXAMAPOBJ" table contains information about which external data group is mapped to which processing module.

Field

Meaning

DATAHANDLER

Determines the externally used data handler.

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

Specifies which processing module is to be used for this 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 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 filled, the parameter "IX_DATAGROUP" is treated as an alias. The parameter "<MAPPED_DATAGROUP>" is then used during 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 the parameter is set (= X), messages for this data group are also logged.

Permissions concept

Access to SAP data objects is protected in the SAP portal plugin using the permissions objects:

  • ZIA_IXA_AC

  • ZIA_PISAP

protected. 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 datasource

*

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 datasource

FUGR

S_TABU_DIS

Activity

02

Permissions group

&NC&

If you equip the service user with "SAP_ALL", please remember that this profile must also first be regenerated in order to accept the new authorization objects from the SAP Portal Plugin. This can be done 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 "ZIAM_IXALOG" table contains information about every access to the RFC API if logging has been activated in Customizing (see Basic settings) ("LOG_ACTIVE" flag).

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 via the BALLOG_ACTIVE flag (see Basic settings). If both loggings are activated, all error messages of the API parameter "ET_MESSAGES" (see messages) are written to the application log and can be evaluated with transaction SLG1.

The session GUID from the Control structure section is used as the external identifier. Typically, this contains the identification of an internet session.

The data records in the "ZIAM_IXALOG" log table can be linked again using the session GUID. 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. It may also be possible to search for errors in the OSS if the messages originate 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 via the "TRACE_ACTIVE" flag in the determination of the processing modules (see 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 communicated to the calling system in the "ET_MESSAGES" parameter.

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 applies this procedure in the same way - the lock is only used at the time of writing.

The locking concept described above is activated when the processing modules are determined ("IX_LOCKING" flag). The timeout parameter "IX_TIMEOUT" (in seconds) can also be used to parameterize write accesses. The screenshot shows this setting for the sample example from the Processing modules chapter. 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 customizing the determination of a processing module. The actual call is a matter for the process module. The interface of the function module can be based on the "Z_IA_IXA_API_EXIT_TEMPLATE" template. It is particularly suitable for use within the "MODIFY" API function to check or adjust data.

Number sequencing

The "GET_NEW_NUMBER_KEY" method provides a simple number range management function that determines an incrementing integer value as the 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 "Date" data type is used as an example. Here SAP uses the internal representation "<YEAR><MONTH><DAY>" (e.g. "20070626"). Externally, "2007-06-26" is often 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 supplied by SAP AG(https://service.sap.com/connectors) are particularly suitable here. 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

General

Installation

Create connection

Integration in applications

SAP Script Generator

SAP Trust Manager SSO configuration

API Description Part 1 - Overview

API description part 3 - Implementation of own processing modules

API description part 4 - sample coding

Developer manual part 1

Developer's Guide Part 2 - Integration scenario SAP external data group

Developer's Guide Part 3 - Scripting integration scenario

Developer Manual Part 4 - Personalized SAP Access / Single Sign On (SSO)

Developer's Guide Part 5 - Addons

Developer manual Appendix

Developer manual - Sample coding