Page tree
Skip to end of metadata
Go to start of metadata

Introduction

A Metadata Provider (MP) describes the complete node model of a Service Provider Infrastructure (SPI) application. This includes for example the data type of nodes as well as available actions and queries that can be executed on those nodes. Beyond the definitions that are required from a technical perspective by application consumers, also attributes are contained that have a declarative/explaining character; i.e. to allow a consumer to understand what is possible with this application.

Technically a Metadata Provider is an ABAP OO class implementing the interface /PLMB/IF_SPI_METADATA_BASE. The instantiation of this class is done by SPI (one Metadata Provider instance per Service Provider instance) based on the Application Building Block ID (ABBID) definition.

The main purpose of the metadata is the description/definition of:

The SPI offers huge flexibility in the definition of metadata: 

  • The metadata is provided via coding and therefore allows e.g. also the consumption of an already existing metadata model. Also the correction of coding via note is more convenient than the adjustment of customizing entries.
  • The complete data type definition can be done dynamically i.e. without a DDIC representation. This allows for example to build up the node's attributes based on customizing entries or maybe even a combination of different DDIC structures.
  • The metadata of a node can be modified at runtime (invalidation and re-reading), i.e. based on runtime data the metadata of a node can be changed (e.g. side-effect s or data type of a node).
 

Enhancement Possibilities provided by SPI

Metadata has to be Maintained Completely

It is important that the metadata is always maintained completely. This means that all Service Provider functionalities (e.g. all actions, queries ...) and all types of the generic parameters (e.g. NODE_ID, NODE_DATA, ACTION->IS_PARAM ...) are defined in the metadata. Any gap in the metadata will lead to issues (e.g. when new functionality is implemented that requires this information or when a customer enhances the application logic).

Tutorial Available

A tutorial on how to create a Metadata Provider can be found in the tutorials section.

Implementation of a Metadata Provider

An application´s Metadata Provider has to implement the interface /PLMB/IF_SPI_METADATA_BASE which offers method GET_NODE_DEFINITION as well as attribute GV_VERSION defining the version of the implementation.

Method GET_NODE_DEFINITION has the following parameters:

Parameter

Data Type

Description

ES_METADATA_ABBID

/PLMB/S_SPI_METADATA_ABBID

Metadata on Application Building Block level

ET_METADATA_NODE

/PLMB/T_SPI_METADATA_NODE

Metadata on node level

MP Instantiation by SPI Must be Possible

The Metadata Provider is instantiated by the SPI. Therefore a public instantiation of the Metadata Provider class must be possible. If a constructor is defined it must not have any parameters. The definition of a constructor is optional. If a constructor is used it must not contain any mandatory import parameters.

Metadata Version

With SAP_BS_FND 731 a version indicator is introduced for Metadata Providers. This version states according to which metadata definition (~Enhancement Package) the Metadata Provider (MP) is implemented. With SAP_BS_FND 731 many new metadata attributes were introduced which of course are not supplied by previously implemented MPs. For downwards compatibility the default value of the version indicates an implementation state before SAP_BS_FND 731.
The version is a binding statement that the Metadata Provider fulfills the metadata definition as available with this version. If e.g. a MP sets the version to SAP_BS_FND 731 it is required to completely maintain all mandatory metadata attributes that are available for this version. Other way round if new attributes of SAP_BS_FND 731 are used also the version has to be maintained accordingly. The version will be evaluated at runtime by SPI to check the validity of calls (provisioning of parameters, type of supplied parameters...).

The version indicator is an attribute (GV_VERSION) on the metadata base interface /PLMB/IF_SPI_METADATA_BASE. The value can be maintained via coding (e.g. CONSTRUCTOR or method GET_NODE_DEFINITION) or directly by setting an initial value for the interface attribute on the MP class.

Constants for Version

Following constant values are available at /PLMB/IF_MDP_C=>GS_C_VERSION:

  • VERSION_702: Metadata definition as available up to SAP_BS_FND 702
  • VERSION_703: Metadata definition as available from SAP_BS_FND 731

Migration from Metadata Version 702 to 703

Following steps are required to migrate an existing metadata model based on version 702 to the new version 703. A migration is mandatory if an application wants to use new features that are dependent on the new version.

  1. Updating the Metadata definition
    1. Maintain the Metadata Version
    2. Maintain the Metadata on ABB level
    3. Maintain the new Metadata on node level, e.g. supported operations
  2. Adjusting the Service Provider implementation
    1. Implement the new SPI interface for Service Provider instantiation
    2. Remove or adjust the Constructor (there must be no import parameters!) of the Service Provider

Metadata on Application Building Block Level

This defines metadata which is valid for the complete Application Building Block (ABB), i.e. cross-node metadata.

Definition structure /PLMB/S_SPI_METADATA_ABBID contains the following settings:

Component

Data Type

Description

PULL_PROPERTIES

/PLMB/SPI_PULL_IND

Pull Indicator: identifies whether the application works with a pull or push properties mechanism

INIT_OPERATIONS

/PLMB/T_SPI_INIT_OPERATION

Initialization Operations: Operations that need to be executed before the ABB is ready to use

MODIFICATION_ALLOWED

BOOLE_D

Indicator that runtime modification of the metadata of this ABB is allowed

No Modification Allowed by Default

By default you should set the modification allowed flag to ABAP_FALSE. In this case SPI will only create one instance of the Metadata Provider class which saves performance.
So only in case you actually need to dynamically change your metadata at runtime after the Metadata has been initialized already you should set this flag to ABAP_TRUE.

Pull Indicator

The parameter PULL_PROPERTIES defines if the Service Provider has implemented a pull mechanism for the properties control or if it works with a push mechanism.

Mixing Push and Pull is Forbidden

The SPI forbids a mixture of push and pull since it is not meaningful

Initialization Operations

The initialization operations are used to declare prerequisite operations of the Application Building Block (ABB), i.e. operations that must be performed before this ABB can be accessed properly. Ideally an ABB should be capable of being accessed directly to guarantee an easy reusability and consumability of the Service Provider. If however this is not possible the declaration of initialization operations is important so that any consumer of a Service Provider can understand how he has to access this layer.

A prerequisite could be an initialization action that sets certain parameters for the complete application. For example a backend can handle several different application types and therefore needs to be initialized with the application type to be used for the current session. Since operations are executed for a certain node, the node name of the operation must be declared as well. Multiple initialization operations on different nodes with (or without) a specific sequence are possible.

Definition of initialization operations (structure /PLMB/S_SPI_INIT_OPERATION):

Component

Data Type

Description

NODE_NAME

/PLMB/SPI_NODE_NAME

Node name

OPERATION_TYPE

/PLMB/SPI_OPERATION_TYPE

Operation type (constants are defined by /PLMB/IF_MDP_C=>GS_C_OPERATION_TYPE-...

ACTION_NAME

/PLMB/SPI_OPERATION_NAME

Operation name (only if the operation type is ACTION)

SEQUENCE

/PLMB/SPI_SEQUENCE

Sequence in which the operation has to be performed

Metadata on Node Level

The node metadata describes the complete node model of the application. The line type of the definition table is /PLMB/S_SPI_METADATA_NODE and consists of following components:

Component

Data Type

Description

NAME

/PLMB/SPI_NODE_NAME

Name of the node (must be unique within the node model of one Application Building Block (ABB)) (mandatory)

NODE_DESCRIPTION

/PLMB/SPI_NODE_DESCRIPTION

Description text of the node

NAME_PARENT

/PLMB/SPI_NODE_NAME

Name of the superior node

CARDINALITY

/PLMB/SPI_CARDINALITY

Cardinality of the relation between the parent node and the node itself (Constants: /PLMB/IF_MDP_C=>GS_C_CARDINALITY) (mandatory if a parent node exists)

TRANSIENT

/PLMB/SPI_TRANSIENT

Indicator that any changes/calls to the node are not save-relevant

UPDATE_RELEVANT

/PLMB/SPI_UPDATE_RELEVANT

Defines the update behavior of the node (on structure/attribute level)
(Constants: /PLMB/IF_MDP_C=>GS_C_UPDATE_RELEVANT) (mandatory if update is supported)

ID_STRUC

TYPENAME

Name of the node ID DDIC structure (mandatory if ID_TABLE_TYPE/ID_DESCRIPTION is not used)

ID_TABLE_TYPE

TYPENAME

Name of the node ID DDIC table type (mandatory if ID_STRUC/ID_DESCRIPTION is not used)

ID_DESCRIPTION

/PLMB/S_SPI_TABLE_DESCRIPTION

Dynamic definition of the node ID data type (mandatory if ID_STRUC/ID_TABLE_TYPE is not used)

DATA_STRUC

TYPENAME

Name of the node data DDIC structure (mandatory if DATA_TABLE_TYPE/DATA_DESCRIPTION is not used)

DATA_TABLE_TYPE

TYPENAME

Name of the node data DDIC table type (mandatory if DATA_STRUC/DATA_DESCRIPTION is not used)

DATA_DESCRIPTION

/PLMB/S_SPI_TABLE_DESCRIPTION

Dynamic definition of the node data type (mandatory if DATA_STRUC/DATA_TABLE_TYPE is not used)

INSERT_STRUC

TYPENAME

Name of the DDIC structure used for the import parameter IS_PARAM of the INSERT SP method

INSERT_STRUC_DESCRIPTION

/PLMB/S_SPI_STRUCT_DESCRIPTION

Dynamic data type definition of the import parameter IS_PARAM of the INSERT SP method

ACTIONS

/PLMB/T_SPI_METADATA_ACTION

Available actions of the node

QUERIES

/PLMB/S_SPI_QUERY

Available queries of this node

SUPPORTED_OPERATION_GROUP

/PLMB/SPI_OPERATION_GROUP

Defines which operations are supported by the node (e.g. delete, retrieve, retrieve by association...)
(Constants: /PLMB/IF_MDP_C=>GS_C_OPERATION_GROUP) (mandatory if metadata version > 702)

INIT_OPERATIONS

/PLMB/T_SPI_INIT_OPERATION

Initialization operations of the node

UPDATE_SIDEEFFECT

/PLMB/SPI_SIDEEFFECT

Side-effect applicable for UPDATEs
(Constants: /PLMB/IF_MDP_C=>GS_C_SIDEEFFECT)

INSERT_SIDEEFFECT

/PLMB/SPI_SIDEEFFECT

Side-effect applicable for INSERTs
(Constants: /PLMB/IF_MDP_C=>GS_C_SIDEEFFECT)

DELETE_SIDEEFFECT

/PLMB/SPI_SIDEEFFECT

Side-effect applicable for DELETEs
(Constants: /PLMB/IF_MDP_C=>GS_C_SIDEEFFECT)

MODIFICATION_DEFINITION

/PLMB/S_SPI_NODE_MODIFICATION

Defines the runtime modification capabilities of this node

DEPENDENT_NODES

/PLMB/T_SPI_NODE_NAME

Defines dependencies between nodes

SUPPORTED_PROPERTIES

/PLMB/S_SPI_SUPPORTED_PROPERTY

Defines which field/operation properties are supported by the node (mandatory if metadata version > 702)

RETRIEVE_DETAILS

/PLMB/S_SPI_RETRIEVE_DETAILS

Definition of the RETRIEVE SP method

Constants for Metadata

The interface /PLMB/IF_MDP_C provides all metadata related constants

Cardinality

The cardinality defines how many node data records can exist that have a relation to one data record of the parent node.
The following settings for the cardinality are available:

  • ZERO_TO_ONE: For each parent there is either no or one child (1 : 0..1)
  • ONE: For each parent there is always exactly one child (1 : 1)
  • ZERO_TO_MANY: For one parent there can be an arbitrary number of children, which also includes the possibility of having no children (1 : 0..N)
  • MANY: For each parent there is minimum one child but also more than one possible (1 : 1..N)

Constants for Cardinality

Constants are available at /PLMB/IF_MDP_C=>GS_C_CARDINALITY

Save Relevance

Per default a node and its actions are save relevant.
This means that after successfully calling either INSERT, UPDATE, DELETE or ACTION of this node a SAVE is needed to persist the result.

This default can be adjusted on node level via field TRANSIENT (i.e. not save relevant) and on ACTION level via field NOT_SAVE_REL (i.e. not save relevant).

FPM SPI Integration (FSI) Evaluates Save Relevance

When using the Application Model of the FPM SPI Integration it will automatically evaluate the save relevance of any performed operations and according to that e.g. a data loss popup will be displayed if the user tries to exit the UI without saving

Update Relevance

The update relevance (field UPDATE_RELEVANT) defines the behavior of the UPDATE of the node.
The following settings exist:

  • FIELDS_OR_STRUCTURE (recommended): when IT_CHANGED_FIELDS is filled it will be considered, otherwise the whole structure will be updated
  • FIELDS_ONLY: only the fields that are provided via import parameter IT_CHANGED_FIELDS will be considered as changed, the rest will be ignored
  • STRUCTURE_ONLY: the whole content of the structure that is provided will be considered as changed

Constants for Update Relevance

Constants are available at /PLMB/IF_MDP_C=>GS_C_UPDATE_RELEVANT

Node ID and Node Data Type

An essential part of the metadata is the type definition of the node's ID and data. Whenever a node specific method is called that has e.g. the parameters IT_NODE_ID or IT_NODE_DATA those data types are expected. The node ID parameter is used when it is sufficient to identify a certain record (e.g. for the DELETE) and the node data parameter is used when the complete attributes of the node are required (e.g. for the UPDATE).

Therefore the metadata node components ID_STRUC and DATA_STRUC should contain the respective DDIC structure names of the node.
In most cases using those two components for defining the structure of the node data and ID is sufficient. Only in case the node ID or node data tables shall have a primary or secondary key it is mandatory to provide ID_TABLE_TYPE or DATA_TABLE_TYPE.

We recommend to always using fix DDIC structures/table types whenever possible, since it results in better readability and also less complex coding compared to the dynamic data type definition.

Node ID Definition Guide

The node ID must contain only the fields that are required to uniquely identify one node data record.
You must avoid adding any fields that are not required for this purpose.
Since the backend must anyhow be able to provide in a fast way the attributes to a node ID, it is not required to include additional attributes to the node ID structure.
In most cases it is an indicator for bad modeling when the same DDIC structure is used for node ID and data.

Dynamic Data Type Definition of a Node

If no fixed DDIC structure is available or feasible for a node, the definition of the node ID and the node data structure & table types can be done dynamically via ID_DESCRIPTION and DATA_DESCRIPTION respectively. Both have the same structure (/PLMB/S_SPI_TABLE_DESCRIPTION) with three components:

Component

Data Type

Description

COMPONENTS

/PLMB/T_SPI_COMPONENT_DESCR

Contains all the components and their data type to be used for the node ID/data

COMPONENT_DETAILS

/PLMB/T_SPI_COMPONENT_DETAILS

Detail information of a component, like description texts and search help to be used

KEYS

/PLMB/T_SPI_TABLE_KEYDESCR

Describes the key fields and key type of the ID/data table types

A component can be described either by name and DDIC type (TYPE) or by name and an elementary description of the component (DATA_TYPE, LENGTH, DECIMALS):

Component

Data Type

Description

NAME

NAME_KOMP

Component name

TYPE

KOMP_TYPE

Component type (DDIC), e.g. data element or structure name

AS_INCLUDE

BOOLE_D

Flag: embed defined component as include (component name is set to .INCLUDE)

DATA_TYPE

DATATYPE_D

Elementary data type, e.g. C, N, P...

LENGTH

DDLENG

Length of the field (only applicable for DATA_TYPE = P, C, N, X)

DECIMALS

DECIMALS

Number of decimals (only applicable for DATA_TYPE = P)

Usage of Structures

To include a DDIC structure the type name needs to be provided via the TYPE component, AS_INCLUDE needs to be set to ABAP_TRUE and optionally a group name can be defined via the component NAME.
When the AS_INCLUDE flag is not set, a deep structure will be created which is not a problem for SPI but reduces the reusability of the node (e.g. direct usage of such a node in the UI might be restricted)

The component details that can be defined are the following:

Component

Data Type

Description

NAME

NAME_KOMP

Component name

DESCRIPTION_S

SCRTEXT_S

Parameter description (short)

DESCRIPTION_M

SCRTEXT_M

Parameter description (medium)

DESCRIPTION_L

SCRTEXT_L

Parameter description (long)

SEARCHHELP

SHLPNAME

Search help name

This table can be filled optionally. Its content overrules the information that is provided by the data elements. In case of elementary type description this is the only possibility to provide description texts and search helps.

More than one key can be defined for a table type, e.g. a primary key and multiple secondary keys.
DDIC structure /PLMB/S_SPI_TABLE_KEYDESCR describes a key:

Component

Data Type

Description

COMPONENTS

/PLMB/T_SPI_KEY_COMPONENT

Table of the key fields, these must be part of the defined components table (only relevant for key kind user defined)

NAME

SECKEYNAME

Name of the key (only relevant for secondary keys)

IS_PRIMARY

BOOLE_D

Indicator that this is the primary table key

ACCESS_KIND

/PLMB/SPI_TABLE_KIND

Key access: standard or sorted table (no hashed)
(Constants: /PLMB/IF_MDP_C=>GS_C_TABLE_KIND)

IS_UNIQUE

BOOLE_D

Indicator that the key is unique

KEY_KIND

/PLMB/SPI_KEY_KIND

Defines the table key kind: default key, table-line as key or user defined key
(Constants: /PLMB/IF_MDP_C=>GS_C_KEY_KIND)

Actions

The ACTION method can be used whenever the other standard methods (UPDATE, INSERT, DELETE, RETRIEVE, QUERY) are not applicable. For example a validation could be implemented as ACTION.

All available actions of the application have to be defined via the ACTIONS table of the node metadata, which has the following components:

Component

Data Type

Description

NAME

/PLMB/SPI_ACTION_NAME

Name of the ACTION (must be unique within the node) (mandatory)

ACTION_DESCRIPTION

/PLMB/SPI_ACTION_DESCRIPTION

Description text of the ACTION

STRUCTURE

TYPENAME

Name of the DDIC used for the ACTION import parameter IS_PARAM

STRUCTURE_DESCRIPTION

/PLMB/S_SPI_STRUCT_DESCRIPTION

Dynamic data type definition of the import parameter IS_PARAM of the ACTION

SIDEEFFECT

/PLMB/SPI_SIDEEFFECT

Side-effect of the action (optional)

NOT_SAVE_REL

/PLMB/SPI_NOT_SAVE_RELEVANT

Indicator that this action is not save-relevant i.e. doesn't change any data that needs to be saved (mandatory if action has no save-relevance or whole node is transient)

STRUCTURE_EXPORT

TYPENAME

Name of the DDIC used for the action export parameter EG_PARAM

STRUCTURE_EXPORT_DESCRIPTION

/PLMB/S_SPI_STRUCT_DESCRIPTION

Dynamic data type definition of the export parameter EG_PARAM of the ACTION

NODE_ID_RELEVANCE

/PLMB/SPI_ACTION_ID_RELEVANCE

Relevance of Node IDs for the ACTION (e.g. node IDs are optional, mandatory or not supported). Find according constants at /PLMB/IF_MDP_C=>GS_C_ACTION_ID_RELEVANCE

Type Definition Mandatory When Using Generic Parameters

If the parameters IS_PARAM and/or EG_PARAM are used, their data types must be defined in the action metadata.

Queries

Queries are there to read node data/IDs via search criteria.
The SPI allows definition of three different types of queries:

  • Service Provider queries: queries that are implemented by the Service Provider itself (executed via the QUERY method)
  • DDIC Search Helps: allows usage of DDIC search helps for automatic query execution by SPI (via a generic adapter, no application coding required)
  • Enterprise Search: allows definition of Enterprise Search queries that are used for automatic query execution by SPI (via a generic adapter, no application coding required)

All three query types can be used at the same time, e.g. a node could support 2 SP queries, 3 DDIC Search Help queries and 1 Enterprise Search query at the same time.

Queries are defined via the QUERY component of the node metadata, which contains for every query type one component:

Component

Data Type

Description

SP

/PLMB/T_SPI_SP_QUERY

Service Provider queries

F4

/PLMB/T_SPI_F4_QUERY

DDIC Search Help queries

ES

/PLMB/T_SPI_ES_QUERY

Enterprise Search queries

The data type of the QUERY result (ET_NODE_DATA) is derived from the QUERY metadata and can therefore deviate from the regular node data type. This is e.g. normally the case for Enterprise Search and DDIC Search Help queries but also for SP queries a different data type can be defined.
A QUERY result table should always be of table type standard even though the interface parameter ET_NODE_DATA is typed as INDEX TABLE and therefore also allows SORTED tables as well. However since a QUERY allows (via the import structure IS_OPTIONS) backend sorting a sorted table would not be meaningful.

Query Name Must be Unique

Each QUERY is identified by its name, which therefore needs to be unique within one node. Since queries are defined in query type specific tables this cannot be ensured solely by using sorted tables with a unique key for the QUERY name.

Service Provider Queries

One node can support multiple Service Provider queries. Therefore each QUERY needs to be described in the metadata via a unique QUERY name, the supported selection criteria and the returned data set. In addition controlling flags are available which indicate whether certain functionality, like paging, is supported by this QUERY.

The following table shows the deep structure of the Service Provider QUERY metadata /PLMB/S_SPI_SP_QUERY:

Component

Data Type

Description

QUERY_NAME

/PLMB/SPI_QUERY_NAME

Unique Identifier of the QUERY (mandatory)

QUERY_DESCRIPTION

/PLMB/SPI_QUERY_DESCRIPTION

Description text of the QUERY

RESULT_STRUCTURE

TYPENAME

Result DDIC Structure (Line Type of ET_NODE_DATA)

RESULT_TABLE_TYPE

TYPENAME

Result DDIC Table Type (Type of ET_NODE_DATA)

DEFINITION

/PLMB/S_SPI_QUERY_DEF

Definition of the QUERY

CRITERIA

/PLMB/S_SPI_CRITERIA_DEF

Criteria Definition (IT_SEL_PARAM)

COMPONENTS

/PLMB/T_SPI_COMPONENT_DESCR

QUERY Criteria (mandatory)

COMPONENT_DETAILS

/PLMB/T_SPI_CRITERIA_DETAILS

Details for QUERY Criteria (Supported Options/Signs...) (mandatory)

RESULT

/PLMB/S_SPI_RESULT_DEF

Result Definition (Type of ET_NODE_DATA)

COMPONENTS

/PLMB/T_SPI_COMPONENT_DESCR

QUERY Result Components

COMPONENT_DETAILS

/PLMB/T_SPI_RESULT_DETAILS

Details for QUERY Result (Description)

KEYS

/PLMB/T_SPI_TABLE_KEYDESCR

Result Table Keys

FILTER_NODE_ID_SUPPORTED

BOOLE_D

Indicator: Filtering is Supported (IT_FILTER_NODE_ID)

PAGING_SUPPORTED

BOOLE_D

Indicator: Paging is Supported (IS_OPTIONS-START_ROW-NUMBER_OF_ROWS)

SORTING_SUPPORTED

BOOLE_D

Indicator: Sorting is Supported (IS_OPTIONS-SORTORDER-STABLE_SORTING)

CRITERIA_GROUPING_SUPPORTED

BOOLE_D

Indicator: Grouping of QUERY Criteria is Supported (IT_SEL_PARAM-GROUP_ID)

REQUESTED_FIELDS_SUPPORTED

BOOLE_D

Indicator: Definition of the requested fields that are provided via the QUERY result (ET_NODE_DATA) is supported

Query Criteria Definition

The QUERY criteria are defined by a table of components and their data types (DEFINITION-CRITERIA-COMPONENTS), just like the dynamic node data type definition.

Query Criteria does not Support Deep Structures

The structure of the QUERY criteria must not be a deep structure i.e. its components must consist of data elements/elementary data types only.


For every criterion it is mandatory to provide an entry in the details table (DEFINITION-CRITERIA-COMPONENT_DETAILS), since there also essential information (like supported options) is defined.
The criteria details consist of:

Component

Data Type

Description

NAME

NAME_KOMP

Search criterion name (mandatory)

DESCRIPTION_S

SCRTEXT_S

Parameter description (short)

DESCRIPTION_M

SCRTEXT_M

Parameter description (medium)

DESCRIPTION_L

SCRTEXT_L

Parameter description (long)

SEARCHHELP

SHLPNAME

Search help to be used for this attribute (only required if not attached to the DDIC)

OPTIONS

/PLMB/T_SPI_QUERY_OPTION

List of supported options of a search criterion, e.g. EQ, LT... (mandatory) (Constants: /PLMB/IF_MDP_C=>GS_C_OPTION)

SUPPORTED_SIGN

/PLMB/SPI_SUPPORTED_SIGN

Defines which signs are supported: I (include), E (exclude) or both (Constants: /PLMB/IF_MDP_C=>GS_C_SUPPORTED_SIGN)

SUPPORTED_ENTRY_KIND

/PLMB/SPI_CRITERIA_ENTRY_KIND

Defines how multiple values for the same search criterion have to be treated: the default would be that an OR operator is applied by the backend, but it is also possible to define an AND conjunction or to mark a criterion as 'singleton', i.e. only one value must be given for this criterion. (Constants: /PLMB/IF_MDP_C=>GS_C_CRITERIA_ENTRY_KIND)

Grouping of Query Criteria

Via CRITERIA_GROUPING_SUPPORTED a QUERY can be enabled for criteria grouping.
When calling such a QUERY, criteria groups can be defined in the select options table.
Without the groups all values for the same criterion are combined by 'OR' per default (e.g. Product = 'ABC', Product = 'DEF'), while different criteria (e.g. Plant = 0001, Customer = 'XY') are normally combined by 'AND'.

The grouping definition allows a more complex logic, because a group works as a bracket around a set of search criteria. Groups are always combined by 'OR'.
Example: (Product = 'ABC' AND Plant = '0001') OR (Product = 'DEF' AND Plant = '0002').

Query Result Definition

When the QUERY result data type (ET_NODE_DATA) matches the node data type, the result definition fields of the QUERY metadata can be left empty and the SPI will automatically use the node data type also for the QUERY result data.
If however the QUERY result data type doesn't match the node data type, the QUERY result data type can either be defined statically, giving the respective DDIC names via RESULT_STRUCTURE or RESULT_TABLE_TYPE or dynamically using a table of components and their data types (DEFINITION-RESULT-COMPONENTS), just like it is done with the dynamic node data type definition.

When following the dynamic approach, you can optionally define table keys using field DEFINITION-RESULT-KEYS.
The result key definition matches the one of the dynamic node data key definition.


Furthermore you can optionally fill the result details table for every component of the result structure:

Component

Data Type

Description

NAME

NAME_KOMP

Attribute/component name

DESCRIPTION_S

SCRTEXT_S

Parameter description (short)

DESCRIPTION_M

SCRTEXT_M

Parameter description (medium)

DESCRIPTION_L

SCRTEXT_L

Parameter description (long)

DDIC Search Help Queries

SPI allows using DDIC search helps as data provider for a QUERY via an SPI-internal adapter.
The application Service Provider is not called at all when calling such a QUERY.
This mechanism therefore is a convenient way to enable the backend for queries.

The only necessary step to do so is to define in the node metadata a QUERY name along with the search help name.
In case the names of the DDIC Search Help export parameters and node ID fields do not match, a mapping needs to be defined. This allows the adapter to automatically fill the ET_NODE_ID export parameter of the QUERY.

Of course an arbitrary number of DDIC Search Help queries can be defined per node name via deep structure /PLMB/S_SPI_F4_QUERY:

Component

Data Type

Description

QUERY_NAME

/PLMB/SPI_QUERY_NAME

Unique identifier for the QUERY (mandatory)

QUERY_DESCRIPTION

/PLMB/SPI_QUERY_DESCRIPTION

Description text of the QUERY

DEFINITION

/PLMB/S_SPI_F4_DEFINITION

Definition of the QUERY

SEARCHHELP

SHLPNAME

Search Help Name (mandatory)

MAPPING

/PLMB/T_SPI_F4_PARAM_MAP

Mapping between QUERY export node ID and DDIC Search Help export parameters

SP_NODE_FIELD

FIELDNAME

Node ID component name

F4_PARAMETER

SHLPFIELD

DDIC Search Help parameter name

QUERY Service Class

  • When using a collective search help it is required to have a QUERY for each needed elementary search help. The class /PLMB/CL_SPI_QUERY_UTIL offers the method EXPAND_SHLP_METADATA to do the expansion of the metadata defined for a collective search help. The call control step 'SELONE' is performed if a search help exit for the collective search help is defined.
  • It is recommended to use the EXPAND_SHLP_METADATA also for elementary search helps to avoid future conflicts if an elementary search help is changed to a collective search help.

DDIC Search Help does not Support all QUERY Parameters

The DDIC Search Help does not support all parameters that are available by the SPI QUERY method, following parameters are ignored by the adapter:

  • IT_FILTER_NODE_ID
  • IT_REQUESTED_FIELD

Enterprise Search Queries

SPI allows using Enterprise Search models as data provider for a SPI via an SPI-internal adapter.
The application Service Provider is not called at all when calling such a QUERY.

The only necessary step to do so is to define in the node metadata a QUERY name along with the identifiers of an Enterprise Search model.
In case the names of the Enterprise Search export parameters and node ID fields do not match, a mapping needs to be defined. This allows the adapter to automatically fill the ET_NODE_ID export parameter of the QUERY.

Enterprise Search based queries are defined in deep structure /PLMB/S_SPI_ES_QUERY:

Component

Data Type

Description

QUERY_NAME

/PLMB/SPI_QUERY_NAME

Unique identifier for the QUERY (mandatory)

QUERY_DESCRIPTION

/PLMB/SPI_QUERY_DESCRIPTION

Description text of the QUERY

DEFINITION

/PLMB/S_SPI_ES_DEFINITION

Definition of the QUERY

TEMPLATE_ID

ESH_E_IF_TEMPLATE_ID

Enterprise Search Connector Template ID (mandatory)

RELATION_TYPE

ESH_E_IF_RELATION_TYPE

Enterprise Search Relation Type (mandatory)

REQUEST_TYPE_ID

ESH_E_OM_REQUEST

Enterprise Search Request Type ID (mandatory)

MAPPING

/PLMB/T_SPI_ES_ATTR_MAP

Mapping between QUERY export node ID and Enterprise Search export parameters

SP_NODE_FIELD

FIELDNAME

Node ID component name

ES_ATTRIBUTE

NAME_KOMP

Enterprise Search attribute name

Enterprise Search does not Support all Query Parameters

The Enterprise Search does not support all parameters that are available by the SPI QUERY method, following parameters are ignored by the adapter:

  • IT_FILTER_NODE_ID
  • IT_REQUESTED_FIELD

Side-Effects

Side-effects define which nodes become invalid after a successful (or partially successful) Service Provider call. A call is considered to be (partly) successful if the export parameter EV_FAILED is not set to true and if at least one of the import node IDs/data did not fail according to export parameter ET_INDEX_FAILED.
When a node becomes invalid, this means that all previously read data is outdated and needs to be read again (e.g. via retrieve).

Side-effects are rough: they are defined per level of nodes and not per node name. In combination with node dependencies a more fine grained invalidation can be achieved. The advantage of this approach, to model the dependencies at design time, is that the maintenance efforts are low and the logic is simple and easy to understand.
However if performance is an issue we also support to invalidate the node data at runtime in a very fine grained way, using the node invalidation of the Collector.

Side-effects are defined on metadata node level for following SP methods:

  • DELETE
  • INSERT
  • UPDATE
  • ACTION (per action name)

FPM SPI Integration (FSI) Evaluates Invalid Nodes

When using the FPM SPI Integration (FSI), all invalid nodes are automatically applied by the FSI to the internal retrieve filter of the Application Model (avoidance of unnecessary data retrieval).
The side-effects are applied globally. A node can even be contained multiple times in different views of the UI.

Side-effects Must Reflect Backend Logic

  • The side-effects always need to be defined from a backend point of view. If the side-effects are defined only considering the current UI layout, it will lead to issues as soon as the UI layout is changed e.g. by customizing.
  • Side-effects are evaluated based on the metadata node model definition not on the UI node hierarchy (the UI node model and/or hierarchy can deviate from the metadata definition).

Flavors

In total 6 side-effect flavors exist, which can be combined as required, therefore 32 combinations are possible:

  • MYSELF – invalidates the node for which the SP was called
    Example: An ACTION is called passing one node ID via the respective import parameter. If this action now only affects this single data record it would be sufficient to just return the new data via the export parameter ET_NODE_DATA. However if more data records of the same node are affected and need to be refreshed, the side-effect MYSELF should be defined for this action.
  • PARENT – invalidates all parent nodes
    Example: A node displays aggregated data from its child node (e.g. a header contains the total number of items), when a DELETE call is executed successfully for one or several items it is required to refresh the header node (= parent node).
  • CHILD – invalidates all child nodes
    Example: Changes on a header (e.g. status update) need to be propagated to the items.
  • SIBLING – invalidates sibling nodes and their respective child nodes
    Example: A node model has the three nodes A, B and C on one hierarchy level. Nodes A and B provide homogeneous data and node C provides the heterogeneous data of A and B combined. Therefore if data of node A or B is modified, node C (sibling) needs to be refreshed as well.
  • ALL – invalidates all nodes of the own Application Building Block (combines all the above side-effects; does not include side-effect OTHERS)
  • OTHERS – invalidates all nodes of other Application Building Blocks

Constants for the Side-effects

Constants are available at /PLMB/IF_MDP_C=>GS_C_SIDEEFFECT, e.g. /PLMB/IF_MDP_C=>GS_C_SIDEEFFECT-CHILD_SIBLING that combines the two flavors CHILD and SIBLING.

Supported Operation Group

The supported operation group identifies which operations (e.g. retrieve, retrieve by association, insert...) are supported by this node. This is important for the consumer of the Service Provider so that he knows what functionality is provided by the node.

Following five granular operations are declared via the operations group:

  • Retrieve
  • Retrieve by association
  • Update
  • Insert
  • Delete

Queries and actions are not part of the group since they are declared explicitly via own tables in the node metadata.

Constants for Operation Group

Constants are available at /PLMB/IF_MDP_C=>GS_C_OPERATION_GROUP, e.g. /PLMB/IF_MDP_C=>GS_C_OPERATION_GROUP-RTR_RBA_INS indicates that the node supports Retrieve, Retrieve by association and Insert.

Initialization Operations

The definition and purpose of the initialization operations on node level matches exactly the one on Application Building Block level .
The only difference is that the initialization operations on node level refer to the node and therefore indicate which operations need to be executed before the node can be accessed properly.

Supported Properties

The supported properties structure /PLMB/S_SPI_SUPPORTED_PROPERTY contains flags that indicate which kind of property control is supported by the node:

Field Properties (FIELDS – /PLMB/S_SPI_SUPPORT_FLD_PRPTY)

Component

Description

Reference Data

Typical Usage in UI

NODE

Properties that apply for the whole node (most general properties)

none

Gets applied to all rows of the UI table

DATA_RECORDS_BY_ASSOCIATION

Properties that apply for all data records that refer to a specific parent data record

Parent Node ID

Gets applied to all rows that refer to a certain parent node ID

DATA_RECORD

Properties that apply for specific node data records

Node ID

Gets applied to the row that matches the node ID

TRANSIENT_DATA_RECORD

Properties that apply for transient data records, i.e. data that is not known yet or not accepted by the backend, e.g. failed INSERT data (node data will be provided along with the properties)

Node Data

Gets applied to a row (which was not provided by the backend) that matches the node data

INSERT

Properties that apply when creating a new data record for this node

none

Gets applied to all empty/default rows

INSERT_BY_ASSOCIATION

Properties that apply when creating a new data record for this node that refers to a specific parent data record

Parent Node ID

Gets applied to all empty/default rows that refer to the parent node ID

Operation Properties (OPERATIONS – /PLMB/S_SPI_SUPPORT_OPR_PRPTY)

Component

Description

Reference Data

Typical Usage in UI

NODE

Operation Properties that apply for the whole node (most general properties)

none

Gets applied to a toolbar button

DATA_RECORD

Operation Properties that apply for specific node data records

Node ID

Gets applied to buttons that are part of a table row that matches the node ID

DATA_RECORDS_BY_ASSOCIATION

Operation Properties that apply for all data records that refer to a specific parent data record

Parent Node ID

Gets applied to a toolbar button of a table which displays data that refers to a certain parent node ID

Node Dependencies

The node dependencies are evaluated by SPI in the context of side-effects and node invalidation: e.g. if a dependency between node A and node B is modeled and at runtime node A is invalidated via side-effect or node invalidation, automatically node B gets invalidated as well. Therefore the node dependencies are a good mechanism to enhance side-effects and node invalidation while being more fine-grained compared to using only side-effects.

How are Node Dependencies Interpreted

To avoid high complexity in maintenance and to avoid recursions SPI considers only the directly specified dependencies of a node.
Example: Node B is a dependent node of node A and node C is a dependent node of node B. If node A is becomes invalid at runtime only node B is invalidated as well. Node C is not affected. Node C becomes only invalid if node B is directly invalidated. So in a scenario where node B and node C should be invalidated upon invalidation of node A, then both nodes must be maintained as dependent nodes of node A.

Modification of Node Metadata at Runtime

A node's metadata can be re-defined at runtime nearly without restrictions. The only settings that cannot be changed are the node's name (NAME) and the parent node name (PARENT_NAME), in other words: the structural information within the node model has to remain stable. All others parameters – like the node data type, side-effects or available actions and queries – can be completely exchanged.

Following steps have to be done to enable runtime metadata modification:

  1. Set the flag on ABBID metadata level MODIFICATION_ALLOWED, thus qualifying this node model as eligible for runtime node modification.
  2. Set the flag MODIFICATION_DEFINITION-ALLOWED on node metadata level. Additionally a DDIC type can be specified which at runtime carries required information for re-reading the node metadata in field MODIFICATION_DEFINITION-PARAMETER_TYPIZATION. This is required when upon re-reading of the node's metadata additional information is required that has to be provided by the SP.
  3. The Metadata Provider class needs to implement the method GET_NEW_NODE_DEFINITION of interface /PLMB/IF_SPI_METADATA_BASE_DYN (This interface is purely optional and only needs to be assigned to a metadata provider if runtime modification is used).
    Method signature:

    Parameter

    Data Type

    Description

    IV_NODE_NAME

    /PLMB/SPI_NODE_NAME

    Node name for which the metadata is re-read

    IG_PARAM (opt.)

    ANY

    Contains runtime information provided by the SP. If this parameter is used the data type of it must be defined on node metadata level in field MODIFICATION_DEFINITION-PARAMETER_TYPIZATION.

    ES_METDATA_NODE

    /PLMB/S_SPI_METADATA_NODE

    Contains the new metadata of the node

  4. At runtime the modification of the metadata is triggered by calling the method CHANGE_NODE_DEFINITION of the corresponding Metadata Provider instance that was passed to the SP upon its instantiation.
    This method offers two import parameters:

    Parameter

    Data Type

    Description

    IV_NODE_NAME

    /PLMB/SPI_NODE_NAME

    Node name for which the metadata has to be re-read

    IG_PARAM

    ANY

    Information required for re-reading the metadata (see description in the step before)

How To Modify Metadata at Runtime

Re-reading metadata can be triggered only by the Service Provider itself, which receives the metadata instance upon instantiation. If the SP wants to allow its consumer to trigger the metadata modification from the 'outside' the SP can offer certain methods (e.g. ACTIONs) that fulfill this purpose.
Each Service Provider instance has its own Metadata Provider instance: this means if for the same ABBID several instances of a Service Provider are created then the corresponding Metadata Provider instances are independent from each other. Modifying of a node's metadata for one Service Provider instance does not affect the metadata definition of other existing Service Provider instances. By doing so the same node could for example be displayed several times in one UI but could have a completely different data type/metadata definition per instance.

Metadata Consumption

The SPI provides two interfaces for metadata consumption. One is the output interface /PLMB/IF_SPI_METADATA_OUTPUT which serves the purpose of reading and evaluating the defined metadata of an Application Building Block (ABB). This interface is returned as export parameter of the Connector instantiation method CREATE_INSTANCE and can be used by the consumer of the SP.

The second interface /PLMB/IF_SPI_METADATA is handed over to the Service Provider during its instantiation. This interface includes the output interface and allows in addition manipulating the metadata at runtime, so it is supposed to be used by the SP only.

The metadata output interface /PLMB/IF_SPI_METADATA_OUTPUT offers following methods:

Method

Description

CHECK_NODE_RELATION

This method evaluates whether two given nodes are related to each other, i.e. if they are in the same branch.
Example: Node A is parent of node B, node B is parent of node C and node D. Node A and B are in the same branch and node A and C as well, however C and D are not in the same branch.

GET_ABBID

Returns the Application Building Block ID (ABBID)

GET_ABBID_DETAILS

Returns the metadata on Application Building Block level

GET_ACTIONS

Returns all actions of a node and their metadata details

GET_ACTION_DETAILS

Returns the metadata details of a specific action

GET_ACTION_NAMES

Returns the names of all action of one node

GET_NODE_DETAILS

Returns the metadata details of a node

GET_NODE_METADATA

Returns a node specific metadata output interface

GET_NODE_METADATA_ITERATOR

Returns an iterator to loop over all node specific metadata output interfaces

GET_NODE_NAMES

Returns all node names and their respective parent node names of the Application Building Block

GET_QUERIES

Returns all queries of a node and their metadata details

GET_QUERY_DETAILS

Returns the metadata details of a QUERY

GET_QUERY_NAMES

Returns the names of all queries of a node

GET_SIDEEFFECT

Returns the side-effect of an operation (update, specific action...) of a node

GET_SUPERIOR_BRANCHNODES

Returns the parent node path for a node

GET_TOP_NODES_METADATA

Returns node specific metadata output interfaces for all root nodes (nodes without a parent node)

GET_VERSION

Returns the version of the Metadata Provider

The metadata input interface /PLMB/IF_SPI_METADATA offers in addition to the above methods of the output interface the following:

Method

Description

CHANGE_NODE_DEFINITION

Triggers a re-reading of the node's metadata

When the metadata of a specific node is required, a node specific metadata output interface (/PLMB/IF_SPI_METADATA_NODE) can be obtained via method GET_NODE_METADATA of interface /PLMB/IF_SPI_METADATA_OUPUT.

The node specific metadata output interface /PLMB/IF_SPI_METADATA_NODE offers the following methods:

Method

Description

CHECK_IF_NODE_IS_SUPERIOR

If the provided node is superior ABAP_TRUE is returned

COMPARE_WITH_NODE

Compares the metadata of the node with the metadata of the provided node.

GET_ABBID

Returns the Application Building Block ID (ABBID) of the node

GET_ACTION_DETAILS

Provides details about a certain action of the node

GET_ACTION_NAMES

Returns the names of all actions of the node

GET_CHILDREN

Returns all node metadata instances of the (direct) children

GET_DATA_CONTAINER

Provides a data reference for the node data structure and node data table type

GET_DATA_RTTI

Provides runtime type information concerning the node data type: a structure and table description instance, as well as a table with explicit component details, like the search help and field labels

GET_DELETE_DETAILS

Provides details about the delete operation

GET_DEPENDENT_NODES

Provides the node dependencies

GET_ID_CONTAINER

Provides a data reference for the node ID structure and node ID table type

GET_ID_RTTI

Provides runtime type information concerning the node ID data type: a structure and table description instance, as well as a table with explicit component details, like the search help and field labels

GET_INIT_OPERATIONS

Returns the initialization operations of the node

GET_INSERT_DETAILS

Provides details about the insert operation

GET_NAME

Returns the node name

GET_PARENT

Returns a node metadata instance of the parent node (if a parent exists)

GET_PATH

Returns the path from the root node to the node itself

GET_QUERY_DETAILS

Provides details about a certain QUERY of the node

GET_QUERY_NAMES

Returns the names of all queries of the node

GET_SUPPORTED_OPERATIONS

Returns the supported operations

GET_SUPPORTED_PROPERTIES

Returns the supported properties

GET_UPDATE_DETAILS

Provides details about the update operation

GET_UPDATE_RELEVANCE

Returns the update relevance indicator

IS_ROOT

Returns ABAP_TRUE if the node is a root node

IS_TRANSIENT

Returns ABAP_TRUE if the node is transient i.e. not save-relevant

To loop over all node specific metadata output interfaces an iterator of type /PLMB/IF_SPI_METADATA_NODE_ITR can be created via method GET_NODE_METADATA_ITERATOR of interface /PLMB/IF_SPI_METADATA_OUPUT:

Method

Description

HAS_NEXT

Returns ABAP_TRUE if after the current iteration further nodes exist

NEXT

Provides the 'next' node specific metadata output interface.
When called for the first time, one of the root nodes is returned and then a branch is processed completely before the next branch is started.
Example: Node A has to child nodes B and C. Node B has the child node D. At first node A is returned, then node B, then D and lastly node C.