Transaction SPI_TOOLS

The central transaction to reach all the SPI related tools is SPI_TOOLS.
From there you can access:

• Metadata Browser – to visualize the metadata of your application
• Service Provider Browser – to execute/test your SP via a generic UI
• Activation of Runtime Checks – to activate additional SPI runtime checks (on system/ABBID/user level) to identify inconsistencies/errors within your application (recommended during the whole development and test phase)

SPI Metadata Browser

The transaction code of the SPI Metadata Browser is MDB

The main target of it is to visualize the SPI metadata model of applications in a comprehensible way and to analyze them for completeness and reasonableness.

The user interface of the browser looks like the following:

At the top of the screen an input field (A) enables the user to choose an ABBID for building up its metadata structure inside the tree area on the left hand side of the screen (C). The detail area (D) is for displaying the corresponding metadata attributes. With the two navigation buttons (B) the user is able to switch between two different views: The 'Attribute View' (shown above) and the 'Metadata Inspector View' for displaying results of various checks (shown below).

How to Use the SPI Metadata Browser

1. Insert one ABBID into the considering input field (A) or use button 'Multiple ABBID selection' next to the input field to select more than one ABBID at the same time.
   Use Button 'Execute' or press F8 to start with building up the tree structure.
2. Inside the tree area (C) expanding and collapsing nodes is possible via the toolbar buttons or single click on nodes. The tree displays nodes, sub nodes, actions and queries. The root node is the ABBID itself.
3. Select a desired node from the tree and press button 'Details' at the tree toolbar. The node and all its subordinate nodes will be loaded into the detail area (D). Now the metadata attributes are visible. At the bottom part of the detail area you can switch between actions, queries and initialization operations via button (The buttons are only active if queries or initialization operations are available for the nodes).
   All underlined fields (links) allow forward navigation e.g. to have a look at structure and table type definitions or class definitions. Grey fields give a hint that the attribute isn't available for the version of the metadata provider (The version can be found on the top list under 'ABBID Attributes').
4. Check if errors, warnings or information are available for the metadata of the chosen ABBID.
   The icon of navigation button 'Metadata Inspector' refers to the checks results.
5. Press button 'Metadata Inspector'.
   The various checks are divided in different categories. Incorrect nodes or nodes with warnings and information are added to the corresponding check category. The colored columns give information about the number of available errors. The user has the possibility to get information of the check results by using the 'Information' icon. In fields of column 'ABBID' and 'Node' forward navigation to the Metadata Provider class is available.
   Below you see a screenshot of the Metadata Inspector:

SPI Browser

The transaction code of the Service Provider Infrastructure Browser is SPB.

The main target of this browser is to provide an application independent test interface for Service Providers.
Thereby it helps to speed up the backend implementation because it simplifies the testing of new backend functionality.
Additionally it helps to identify gaps or issues which might not become visible by using an application specific UI. Thereby the SPB supports in building a backend that is really decoupled from the UI.

The user interface of the browser looks like the following:

At the top of the screen the Application Building Block ID (ABBID) input field (A) enables the user to choose an ABBID for building up its hierarchical metadata node model inside the tree area on the left hand side of the screen (B). Once the tree area is loaded, the transactional operation controls (C) appear, allowing the user to call SAVE, CHECK_BEFORE_SAVE and CLEAN_UP methods. In the main ALV area (E) the result set of the executed operation is displayed, if available. Using the Exporting Parameters Bar (D) further information can be acquired regarding the operation processed. The Log Area (F) contains messages from the Service Provider class and the SPI Browser.

How to Use the SPI Browser

1. Insert an ABBID existing in the current system into the corresponding field either manually, or the F4 help can be used to obtain information about the possible input values. Press Enter, or double click on the text appearing in the input field.
2. Select a node operation by right clicking on the node in the tree, and choosing an item from the context menu.
   

3. A popup opens up with the title of the selected operation. Enter input data to the popup ALV.
   Table lines can be inserted and removed using the standard ALV toolbar (default number of lines is 10).
   Press Execute at the bottom of the modal window.

   How To Set Additional Parameters

   • Retrieve and Retrieve by Association operations also have a locking indicator (IV_LOCK) that can be set using the checkbox below the ALV.
   • In case of the ACTION, if an action structure is defined in the metadata provider, the button  appears next to the execute button. By clicking on it, in a modal window the action parameters can be set.
4. The result set is displayed in the main ALV area (E). The main ALV toolbar consists of dynamic buttons, with the names of the supported operations, actions and queries on the specific node. If lines are selected when selecting an operation from the toolbar, the selected data is transmitted to the popup.
   The status icon (green light) in the Exporting Parameters Bar (D) indicates the general outcome of the called operation (EV_FAILED). If further parameters are available as well, the corresponding buttons become active. Clicking on them provides the information in a modal window.
   

SP Service Classes

The ABAP class /PLMB/CL_SPI_APPL_ACCESS_UTILS and /PLMB/CL_SPI_QUERY_UTIL offers reusable services (mainly relevant for backend implementations). This page gives an overview about the most used methods. For a complete overview please have a look at the classes itself.

SP Factory /PLMB/CL_SPI_REUSE_SP

SPI offers a reusable Service Provider that eases and standardizes Service Provider implementation. This service consists of two main parts:

• An abstract Service Provider implementation (class /PLMB/CL_SPI_REUSE_SP) from which the application specific Service Provider has to inherit and
• A node access interface (/PLMB/IF_SPI_NODE_ACCESS) which is implemented per node of the metadata model (reuse and inheritance concepts are of course possible and often advisable)

The idea of this approach is to separate a Service Provider implementation into two parts. Transactional methods (e.g. SAVE and CLEAN_UP) are implemented in the application's Service Provider (by implementing the foreseen abstract methods of the reusable Service Provider), while the node specific methods (e.g. RETRIEVE and UPDATE) are implemented in node specific classes implementing the node access interface. This results into a clean structuring of coding and proper delegation of responsibilities. SPI handles the administration of the various node instances (= factory) and also ensures e.g. that each node instance use its correct Collector instance, which is especially important if nodes are instantiated multiple times.

Provided functionality:

• Node Factory – no instance handling and management required on application side anymore
• Forwarding of messages to the correct Collector instance
• Calculation and population of export parameters of the application access interface /PLMB/IF_SPI_APPL_ACCESS, like EV_FAILED and ET_INDEX_FAILED based on the provided messages

Note: usage of this concept does not have an impact on the implementation of the Metadata Provider

Implementation Guide

Implement the Node Access Interface /PLMB/IF_SPI_NODE_ACCESS

Different approaches are possible – also depending on the complexity of the application's node model (see Metadata Provider):

• For each node separate classes are created, each implementing the node access interface
• One node super class is defined that implements the node access interface and all node implementations inherit from this class
• The method signature of the node access interface is very similar to the application access interface /PLMB/IF_SPI_APPL_ACCESS, only small deviations exist:
  • The node name is not part of the method signature, since one node class implementation represents already a specific node
  • The methods RETRIEVE and INSERT provide an optional import parameter IV_PARENT_NODE_NAME to identify whether an INSERT/RETRIEVE by association is required, rather than having two parameters IV_NODE_NAME and IV_TARGET_NODE_NAME
  • The method INITIALIZE provides the Collector and Metadata Provider instances, as well as the node name for which this class is called (the latter is only relevant in exceptional cases where e.g. a node implementation handles multiple nodes or in very generic implementations)

Implement the Application's Service Provider

• Create a class inheriting from the SPI reuse Service Provider /PLMB/CL_SPI_REUSE_SP
• Implement the three (transactional) methods CLEAN_UP, CHECK_BEFORE_SAVE and SAVE provided by the super class; note: relevant are the 'protected abstract' methods and not the ones part of the application access interface /PLMB/IF_SPI_APPL_ACCESS that are also visible in the application Service Provider, these methods are all implemented 'final' by the reuse SP
• Implement the method DEFINE_NODE_CLASS_ASSIGNMENT: this method returns the (node) class names per metadata node name, e.g. if the metadata node "CARRIER" is implemented by class CL_ND_CARRIER than this combination must be returned by the method (for all nodes); note: if the data is returned incomplete, e.g. a node is missing, this results in an exception
• Maintain your Service Provider class name in the ABBID table

Class /PLMB/CL_SPI_APPL_ACCESS_UTILS

Message Handling

EVALUATE_MESSAGES

This method allows filling the SPI parameter EV_FAILED (failed indicator) and ET_INDEX_FAILED (both e.g. available in the SP Update and Delete methods...) based on a message table.
The logic is as follows: if the message table contains at least one error message without a message index (field MSG_INDEX) the failed indicator is set. For error messages with message index an entry is written to the index failed table.
This method is very helpful in Service Provider implementations to supply the export parameters of the interface methods based on the message table received from the backend (e.g. BO) call.

Method signature:

EVALUATE_MESSAGES_RETRIEVE

This method fulfills the same purpose as EVALUATE_MESSAGES but is specialized for the RETRIEVE call. A RETRIEVE call can typically cause messages due to lock errors (if the lock flag was set) or due to data read errors. This method converts both message tables into the SPI specific index failed table type (reason code and index, not only index!) of the RETRIEVE method.

Method signature:

ADD_MESSAGES

Adds an import table of messages to a given changing table of existing message with following (optional) additional functionality:

• Filtering of messages based on a given message severity, e.g. all messages "below" error are ignored
• Adjustment of the message index
• Adding a field name as message reference
• Calculation of the new overall severity

Use case: within one method you call several other methods that return messages. Those have to be added to an overall message table.

Method signature:

ADD_SYST_MESSAGE

This method adds a message that is contained in the SY fields to a table of messages and adjusts the severity if needed.

Method signature:

SET_MESSAGE

This method offers a subset of the functionality that is covered by method ADD_SYST_MESSAGE.

CONVERT_SYMSG

This method offers a subset of the functionality that is covered by method ADD_SYST_MESSAGE.

COMBINE_MESSAGE_TABLES

This method combines two message tables (source and target). For the source table an index needs to be supplied with which the messages are added to the target table. Note: initial indices of source messages are respected and not overwritten by IV_INDEX_TARGET.

Method signature:

CONVERT_BAPIRET

This method converts a message table in the BAPIRET format to the SPI message format.

Method signature:

CONVERT_EXCEPTION_TO_MSG

This method converts an exception (CX_ROOT or inherited) in to the SPI message format (table of message type /PLMB/T_SPI_MSG).

Method signature:

CHANGE_MESSAGE_TYPE

This method allows changing message types in a message table. For example error messages should be "downgraded" to warning messages. As default the "from" message type is preset with 'E' (error message) and the "to" message type with 'W' (warning message).

Method signature:

SET_MSG_INDEX

This method allows setting a new message index to a given message table.

Method signature:

GET_SEVERITY

This method calculates the overall severity of a message table, the "highest" message type wins: S < I < W < E < A/X.

Method signature:

ADJUST_MESSAGE_SEVERITY

This method updates a given message severity based on a second one (the "higher" message severity wins: S < I < W < E < A/X)

Use case: within one method you call several other methods that return a message severity. At the end of this method an aggregated message severity (based on all calls) needs to be returned.

Method signature:

CALC_RELEVANT_SEVERITY_LEVEL

This method calculates the severity level for a given message type/severity, e.g. the severity level for message type 'W' would be 'SIW'.

Method signature:

ADD_INSERT_MSG_TO_COLLECTOR

This method adds messages that occurred during an insert via method ADD_MESSAGE_ENH to the given Collector while using the appropriate reference type.

Method signature:

Data Conversion

CONVERT_DATA_TO_XSTRING

This method converts the given data to an X-String.
This is needed to be able to use a common format whenever the data type cannot be set statically.
To extract the data again method CONVERT_XSTRING_TO_DATA can be used.

Example: The SPI uses the X-String conversion when combining the node ID with the message information. The data type of the message is known at design time but the node ID has a dynamic type, so therefore to fill both information into one structure an X-String component is used for the node ID.

Method signature:

CONVERT_XSTRING_TO_DATA

This method extracts the data that was converted to an X-String via method CONVERT_DATA_TO_XSTRING.

Method signature:

CONVERT_STRUCTURE_TO_XSTRING

This method offers the same functionality as method CONVERT_DATA_TO_XSTRING.

CONVERT_XSTRING_TO_STRUCTURE

This method offers the same functionality as method CONVERT_XSTRING_TO_DATA.

CNV_SEL_OPTIONS_TO_STRUCTURE

This method provides a simple conversion of QUERY select options to a data structure, which only supports sign 'I' and option 'EQ'.
The select options are filled into the according fields of the data structure.
When a duplicate select option is handed over or one that is not supported a message type 'X' is returned.

Method signature:

CNV_STRUCTURE_TO_SEL_OPTIONS

This method provides a simple conversion of a data structure to QUERY select options.
All fields of the structure that are not blank are added to the select options using sign 'I' and option 'EQ'.

Method signature:

Metadata Related

GET_COMPONENT_DETAILS

This method provides to a given RTTI structure description object the component details that are for example used in the Metadata Provider.

Method signature:

GET_OPERATION_CATEGORY

This method provides a set of flags that indicate the supported operations which are defined via the given operation group.

Method signature:

SET_OPERATION_CATEGORY

This method returns an operation group according to the given set of flags that indicate the supported operations.

Method signature:

GET_SIDEEFFECT_CATEGORY

This method provides to a given side-effect all affected groups of nodes that will be invalidated.

Method signature:

SET_SIDEEFFECT_CATEGORY

This method provides the according side-effect to the given invalidation requirements.

Method signature:

GOS Related

PERS_AREA_SET

This method triggers writing of services data.

Method signature:

PERS_AREA_DELETE

This method deletes services data. The parameters match the ones of method PERS_AREA_SET.

GET_URL_FOR_ICON

This method provides a URL to the given icon.

Method signature:

ADD_GOS_MESSAGES

This method offers the same functionality as method ADD_MESSAGES described above. The only difference is that the import table refers to GOS conversion messages. The changing table however is a regular SPI message table.
This method is very helpful if messages from a GOS conversion call need to be added to a "standard" SPI table.

GET_GOS_SEVERITY

This method calculates the overall severity of a GOS conversion message table, the "highest" message type wins: S < I < W < E < A/X.

Method signature:

Miscellaneous

GET_USER_TEXT

This method provides user details like first name and last name for a list of users.

Method signature:

IS_ABB_EXISTENT

This method checks if a certain Application Building Block ID (ABBID) exists.

Method signature:

Class /PLMB/CL_SPI_QUERY_UTIL

FILL_RESULT

This method processes a query result and enables self-programmed SP queries with standard functions:

• Extract node IDs from query result data
• Build relation between node ID records and result records (needed if node IDs retrieved with a sorted table)
• Do mapping if fieldnames of the ID structure are different to the fieldnames of the result structure
• Sort of result data
• Paging

Method signature:

EXPAND_SHLP_METADATA

This method creates the metadata according to a given DDIC search help while expanding collective search helps.

Method signature:

Constants

All fixed values that are used within the area of the SPI are defined at ABAP OO constant interfaces.

Metadata Related Constants – /PLMB/IF_MDP_C

This interface offers constants that are needed when defining or consuming metadata.

Service Provider Related Constants – /PLMB/IF_SPI_C

This interface offers constants that are used within the Service Provider or when calling it.