Registration

Dear SAP Community Member,
In order to fully benefit from what the SAP Community has to offer, please register at:
http://scn.sap.com
Thank you,
The SAP Community team.
Skip to end of metadata
Go to start of metadata

 

Introduction

The Service Provider (SP) functions as interface between the Service Provider Infrastructure (SPI) and the application's backend. Its main responsibility is providing access to the application data and handling requests for creating, changing or deleting the data.

Technically a SP is an ABAP OO class that implements the application access interface /PLMB/IF_SPI_APPL_ACCESS that consists of six node specific methods and three transactional (node-independent) methods. Additional information that is not returned via the access interface methods such as messages and field properties are handed over by the SP to the Collector. Furthermore the SP needs to implement the initialization interface /PLMB/IF_SPI_APPL_ACCESS_INIT.

Although it is possible that the Service Provider itself is the backend, we recommend in our guidelines to limit the contained logic of a Service Provider to the bare minimum and implement the backend logic e.g. within a business object class that is then called by the SP. The advantage of this approach is that the business object class can offer distinct methods for its functionality with parameters that have a static DDIC data type instead of having an all-generic backend.

Enhancement possibilities provided by SPI

 

Tutorial Available

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

Instantiation

The Service Providers are instantiated centrally by SPI and initialized via interface /PLMB/IF_SPI_APPL_ACCESS_INIT that the SP needs to implement. The interface provides method INITIALIZE which offers the import parameter IS_OPTIONS with the following fields:

  • COLLECTOR – for supplying messages, field properties, etc. to SPI
  • METADATA – for accessing metadata information

It is important to know that for every Connector instance there will be one SP instance. This means that at runtime it is very likely that the same SP class will be instantiated multiple times, which needs to be taken into account when considering the backend implementation, e.g. buffering. So if the same buffer needs to be accessed from within those multiple SP instances e.g. a singleton Business Object could be used.

Those multiple SP instances are necessary to be able to separate the provided Collector data like messages and field properties and to support a more complex backend which wants to modify the metadata on SP instance level at runtime.

Please note that older SP implementations, where no explicit interface for instantiation was available (Version < 731), needed to implement a public CONSTRUCTOR with one import parameter IO_COLLECTOR of type /PLMB/IF_SPI_COLLECTOR.

Node Specific SP Methods

There are six node specific methods which are there to read/modify the node data.
Those methods are:

INSERT

The INSERT is used to create new node data.
It can be instrumented in two ways:

  • Direct Insert – data records that belong to the given node are created
  • Insert by Association – data records that belong to the given target node and that have an association to the given parent key (IS_NODE_ID) are created

Method signature:

Parameter

Data Type

Description

IV_NODE_NAME

/PLMB/SPI_NODE_NAME

Node name (mandatory)

IV_TARGET_NODE_NAME

/PLMB/SPI_NODE_NAME

Target node name

IS_NODE_ID

ANY

Node ID of the parent node

IT_NODE_DATA

INDEX TABLE

New node data (mandatory)

IS_PARAM

ANY

Free defined import parameter

EV_FAILED

/PLMB/SPI_FAILED_IND

Failed indicator

ET_INDEX_FAILED

/PLMB/T_SPI_INDEX_FAILED

Table with failed indices of IT_NODE_DATA

ET_NODE_DATA

INDEX TABLE

Result node data

ET_NODE_ID_REL

/PLMB/T_SPI_NODE_REL

Relation between rows of IT_NODE_DATA and ET_NODE_DATA

Type Definition Mandatory When Using Generic Parameters

If the parameter IS_PARAM is used, its data type must be defined via field INSERT_STRUC in the node metadata.

Detailed Parameter Description

  • During a direct insert IV_NODE_NAME contains the node name for which the node data is to be created, in case of an insert by association the parent node name is contained.
  • IV_TARGET_NODE_NAME is only used for an insert by association and provides the node name for which the data record is to be created.
  • IT_NODE_DATA contains the node data to be created. The number of lines must reflect the number of items to be created, e.g. if three new/blank items should be created and the backend would not even need node specific data (maybe only the IDs are determined by internal numbering...), than still three lines need to be supplied. IT_NODE_DATA can contain already node data and even node IDs entered/provided by the caller. Of course the node ID is optional and could be determined by the backend.
    The data type of the import node data needs to match the metadata definition.
  • IS_NODE_ID is only relevant for an insert by association. In this case it must contain the ID of the parent data record.
    The data type of this parameter needs to match the metadata definition of the parent node IDs.
  • IS_PARAM is an optional parameter structure with the data type as defined via field INSERT_STRUC of the node metadata. It can be used to supply data for the backend that is not part of the actual node data, i.e. data that cannot be supplied via IT_NODE_DATA, an example would be template data (e.g. template material number when creating a new material).
  • The failed indicator EV_FAILED should be set if an error in the backend has occurred that is not directly related a specific row of the provided node data, e.g. an exception is raised by the backend that prevents any kind of data insertion.
  • The index failed table ET_INDEX_FAILED has to be filled if an error occurred that is related to one of the provided node data rows.
    Example: IT_NODE_DATA contained three lines to be inserted but only the second one could be inserted in the backend successfully: in this case the index failed table has to be filled with two lines (index 1 and index 3).
  • ET_NODE_DATA contains the resulting node data for the successfully inserted lines.
    The data type of the export node data needs to match the metadata definition.
  • The table ET_NODE_ID_REL contains the index mapping of input table IT_NODE_DATA to output table ET_NODE_DATA. This is especially relevant if the node ID is filled or completed by the backend.
    It is recommended to always fill this table, even if the IDs that were supplied in IT_NODE_DATA match the ones in ET_NODE_DATA, since it eases the assignment of import to export data for the caller of the method.

UPDATE

The UPDATE method changes existing node data.

Method signature:

Parameter

Data Type

Description

IV_NODE_NAME

/PLMB/SPI_NODE_NAME

Node name (mandatory)

IT_NODE_DATA

INDEX TABLE

Updated node data (mandatory)

IT_CHANGED_FIELD

/PLMB/T_SPI_CHANGED_FIELD

List of changed fields

EV_FAILED

/PLMB/SPI_FAILED_IND

Failed indicator

ET_INDEX_FAILED

/PLMB/T_SPI_INDEX_FAILED

Table with failed indices of IT_NODE_DATA

ET_NODE_DATA

INDEX TABLE

Result node data

ET_NODE_ID_REL

/PLMB/T_SPI_NODE_REL

Relation between rows of IT_NODE_ID and ET_NODE_DATA

Detailed Parameter Description

  • IV_NODE_NAME contains the name of the node whose data shall be changed.
  • IT_NODE_DATA contains the changed data records.
    The data type of the import node data needs to match the metadata definition.
  • IT_CHANGED_FIELD contains a list of changed fields per row of IT_NODE_DATA.
    Ideally when there is no entry for a row of IT_NODE_DATA this row shall be considered to be changed completely, otherwise only the list of given fields should be considered for the update. So when using this parameter an update is executed on attribute level, otherwise on structure level.
    It is possible to define in the metadata via field UPDATE_RELEVANT whether – and to which extend – this parameter is supported.
  • The failed indicator EV_FAILED should be set if an error in the backend has occurred that is not directly related a specific row of the provided node, e.g. an exception is raised by the backend that prevents any kind of data update.
  • The index failed table ET_INDEX_FAILED has to be filled if an error occurred that is related to one of the provided node data rows.
    Example: IT_NODE_DATA contained three lines to be updated but only the second one could be updated in the backend successfully: in this case the index failed table has to be filled with two lines (index 1 and index 3).
  • ET_NODE_DATA contains the resulting node data for the successfully updated lines.
    The data type of the export node data needs to match the metadata definition.
  • The ID relation table ET_NODE_ID_REL contains the index mapping of input table IT_NODE_DATA to output table ET_NODE_DATA.
    It is recommended to always fill this table, even if the IDs that were supplied in IT_NODE_DATA match the ones in ET_NODE_DATA, since it eases the assignment of import to export data for the caller of the method.

DELETE

The DELETE method removes node data via ID(s).

Method signature:

Parameter

Data Type

Description

IV_NODE_NAME

/PLMB/SPI_NODE_NAME

Node name (mandatory)

IT_NODE_ID

INDEX TABLE

Node IDs to be deleted (mandatory)

EV_FAILED

/PLMB/SPI_FAILED_IND

Failed indicator

ET_INDEX_FAILED

/PLMB/T_SPI_INDEX_FAILED

Table with failed indices of IT_NODE_ID

Detailed Parameter Description

  • IV_NODE_NAME contains the name of the node whose data shall be removed.
  • Via IT_NODE_ID the node IDs relevant for deletion are defined.
    The data type of the node IDs needs to match the metadata definition.
  • The failed indicator EV_FAILED should be used if an error in the backend has occurred that is not directly related to the provided node IDs, e.g. an exception is raised by the backend that prevents any kind of data deletion.
  • The index failed table ET_INDEX_FAILED has to be filled if an ID specific error occurred.
    Example: IT_NODE_ID contained three IDs but only the second one was deleted in the backend successfully: in this case the index failed table has to be filled with two lines (index 1 and index 3).

ACTION

The ACTION method can be used whenever the standard methods (UPDATE, INSERT, DELETE, RETRIEVE, QUERY) are not applicable.
For example an object validation could be implemented as action.
The available actions of a node have to be defined in the metadata.

Method signature:

Parameter

Data Type

Description

IV_NODE_NAME

/PLMB/SPI_NODE_NAME

Node name (mandatory)

IV_ACTION_NAME

/PLMB/SPI_ACTION_NAME

Action name (mandatory)

IT_NODE_ID

INDEX TABLE

Node IDs

IS_PARAM

ANY

Free defined import parameter

EV_FAILED

/PLMB/SPI_FAILED_IND

Failed indicator

ET_INDEX_FAILED

/PLMB/T_SPI_INDEX_FAILED

Table with failed indices of IT_NODE_ID

ET_NODE_DATA

INDEX TABLE

Result node data

EG_PARAM

ANY

Free defined export parameter

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.

Detailed Parameter Description

  • IV_NODE_NAME contains the name of the node for which the action is performed.
  • IV_ACTION_NAME identifies the action that is called.
  • IS_PARAM is an optional parameter that can be used to supply additional required data to the backend.
    It has to follow the data type defined via field STRUCTURE of the action metadata.
    Example of usage: For three objects a certain status shall be set, therefore IT_NODE_ID would contain the three node IDs of those objects and the parameter structure would contain the new status.
  • IT_NODE_ID is an optional parameter which allows performing an action with respect to certain data records.
    For example a 'global' validation action would not require any ID information, while the example above enforces IDs.
    The data type of the node IDs needs to match the metadata definition.
  • The failed indicator EV_FAILED should be used if an error in the backend has occurred that is not directly related to one of the provided node IDs, e.g. an exception is raised by the backend that prevents any processing of such an action.
  • The index failed table ET_INDEX_FAILED has to be filled if an ID specific error occurred.
    Example: IT_NODE_ID contained three lines but only for the second one the ACTION could be executed successfully. In this case the index failed table has to be filled with two lines (index 1 and index 3).
  • ET_NODE_DATA contains the node data of the node IDs which were successfully processed by the action.
    The data type of the export node data needs to match the metadata definition.
  • EG_PARAM can be used optionally to provide additional data that is not part of the node data export table.
    It has to follow the data type defined via field STRUCTURE_EXPORT of the action metadata.

Usage of IS_PARAM and EG_PARAM

The generic parameters IS_PARAM and EG_PARAM have the purpose of transporting small amounts of data that are needed on top of the node data, like a status field for example. They must not be used for providing great amount of data e.g. that could have been returned by an own SP node.
Those parameters needs to be used carefully, they allow great flexibility but at the same time bears the risk – upon wrong usage – of a semantically wrong or very limited reusable SP implementation.

RETRIEVE

The RETRIEVE reads node data via ID(s).
It can be instrumented in two ways:

  • Direct Retrieve – data records that belong to the given node are read via their own keys (per valid key exactly one record must be returned)
  • Retrieve by Association – data records that belong to the given target node and that have an association to the given keys are read (per valid parent key no, one or multiple records can be returned – depending on the cardinality)

Method signature:

Parameter

Data Type

Description

IV_NODE_NAME

/PLMB/SPI_NODE_NAME

Node name (mandatory)

IV_TARGET_NODE_NAME

/PLMB/SPI_NODE_NAME

Target node name

IT_NODE_ID

INDEX TABLE

Requested node IDs (mandatory)

IT_REQUESTED_FIELD

/PLMB/T_SPI_REQUESTED_FIELD

Requested fields of ET_NODE_DATA

IV_LOCK

/PLMB/SPI_LOCK_IND

Lock indicator / read for update

EV_FAILED

/PLMB/SPI_FAILED_IND

Failed indicator

ET_INDEX_FAILED

/PLMB/T_SPI_RTR_INDEX_FAILED

Table with failed indices of IT_NODE_ID (lock errors and read errors)

ET_NODE_DATA

INDEX TABLE

Result node data

ET_NODE_ID_REL

/PLMB/T_SPI_NODE_REL

Relation between rows of IT_NODE_ID and ET_NODE_DATA

Detailed Parameter Description

  • During a direct retrieve IV_NODE_NAME contains the node name for which the node data is to be read, in case of a retrieve by association the parent node name is contained.
  • IV_TARGET_NODE_NAME is only used for a retrieve by association and provides the node name for which the data record is to be read.
  • IT_NODE_ID provides the node IDs whose data is to be read in case of a direct retrieve and whose child data is to be read in case of a retrieve by association.
    The data type of the node IDs always needs to match the metadata definition of the node specified via IV_NODE_NAME.
  • When only a subset of the node fields are required by the caller, the table IT_REQUESTED_FIELD can be used to specify this subset. The SP should then only fill those fields of the export parameter ET_NODE_DATA. Whether or not this feature is supported by the SP should be defined in the metadata of the respective node.
  • To lock data directly upon data reading the parameter IV_LOCK needs to be set
  • The failed indicator EV_FAILED should be set if an error in the backend has occurred that is not directly related to the requested node IDs, e.g. an exception is raised by the backend that prevents any kind of data retrieval.
  • The index failed table ET_INDEX_FAILED has to be filled if errors occurred upon reading and/or locking of a specific data record.
    The table consists of two components: the INDEX the error relates to and the REASON_CODE of the error (lock error or read error).
    For the reason code following constants are available: /PLMB/IF_SPI_C=>GS_C_REASON_CODE-LOCKED and /PLMB/IF_SPI_C=>GS_C_REASON_CODE-KEY_NOT_FOUND
  • The read data is returned via ET_NODE_DATA.
    The data type of the export node data needs to match the metadata definition of the node specified via IV_NODE_NAME (in case of a direct retrieve) or of the node provided by IV_TARGET_NODE_NAME (in case of a retrieve by association).
  • The ID relation table ET_NODE_ID_REL contains the index mapping of input table IT_NODE_ID to output table ET_NODE_DATA, this allows e.g. identifying to which parent node IDs the returned child data belongs (retrieve by association with multiple parents).
    It is recommended to fill this table always, even for direct retrieves, since it eases the assignment of import to export data for the caller of the method.

QUERY

The QUERY allows reading node data/IDs via selection criteria.
The available queries have to be defined in the metadata.

Method signature:

Parameter

Data Type

Description

IV_NODE_NAME

/PLMB/SPI_NODE_NAME

Node name (mandatory)

IV_QUERY_NAME

/PLMB/SPI_QUERY_NAME

Query name (mandatory if metadata version > 702)

IT_SEL_PARAM

/PLMB/T_SPI_SELECTION_PARAM

Search Criteria

IS_OPTIONS

/PLMB/S_SPI_QUERY_OPTIONS

Additional query options

IV_KEYS_ONLY

/PLMB/SPI_KEYS_ONLY_IND

Indicator: Return only node IDs

IT_FILTER_NODE_ID

INDEX TABLE

List of node IDs to which the result will be restricted

IT_REQUESTED_FIELD

/PLMB/T_SPI_REQUESTED_FIELD

Requested fields of ET_NODE_DATA

EV_FAILED

/PLMB/SPI_FAILED_IND

Failed indicator

ET_NODE_ID

INDEX TABLE

Result node IDs

ET_NODE_DATA

INDEX TABLE

Result node data

ET_NODE_ID_REL

/PLMB/T_SPI_NODE_REL

Relation between rows of ET_NODE_ID and ET_NODE_DATA

Detailed Parameter Description

  • IV_NODE_NAME specifies the node for which the query is called
  • IV_QUERY_NAME identifies the query to be executed.
  • IS_OPTIONS can be used to supply controlling options for the query, these are:
    • START_ROW – Start row (first row) to be returned by the query
    • NUMBER_OF_ROWS – Specifies the maximum number of rows to be returned by the query
    • NAVI (DEPRECATED) – Page navigation parameter (Use START_ROW/NUMBER_OF_ROWS instead!)
    • STABLE_SORTING – Indicates usage of stable sorting
    • SORTORDER – Sort order definition (by fieldnames, ascending...)
  • IT_SEL_PARAM contains a table of query criteria following the definition in the metadata
    • FIELDNAME – Name of the query criterion
    • SIGN – Sign of the value: Included/Excluded (Constants are available at: /PLMB/IF_SPI_C=>GS_C_SIGN)
    • OPTION – Search option like EQUAL_TO, CONTAINS_PATTERN, ... (Constants are available at: /PLMB/IF_MDP_C=>GS_C_OPTION)
    • LOW – Low value of search options that refer to ranges (e.g. is between) or single value of search options like EQUAL_TO
    • HIGH – High value of search options that refer to ranges (e.g. is between)
    • GROUP_ID – Groups a set of search criteria to support a more complex search logic; it needs to be defined in the query metadata if the SP supports criteria grouping
  • IV_KEYS_ONLY indicates if the SP shall return only the result node IDs via ET_NODE_ID and no node data itself
  • Via the ID filter table IT_FILTER_NODE_ID the query result can be restricted to the specified IDs, i.e. the query result must contain a subset of the set of records provided via this parameter.
    The data type of the filter node IDs needs to match the metadata definition of the node IDs.
  • When only a subset of the node fields are required by the caller, the table IT_REQUESTED_FIELD can be used to specify this subset. This is currently only supported by the SP QUERY. The SP should then only fill those fields of the export parameter ET_NODE_DATA. Whether or not this feature is supported by the SP should be defined in the query metadata.
  • The failed indicator EV_FAILED should be used if an error in the backend occurred that prevented the query from execution.
  • Export table ET_NODE_ID contains the IDs of the query result.
    The data type of the result node IDs needs to match the metadata definition of the node IDs.
  • The query result data is returned via ET_NODE_DATA.
    The data type of the query result needs to follow per default the metadata definition of the node data but can be overruled by a query specific result data type definition.
  • ET_NODE_ID_REL contains the index mapping between the node IDs (ET_NODE_ID ~source) and the node data (ET_NODE_DATA ~target). This mapping is relevant if the sorting of both tables is not identical.

Transactional SP Methods

SPI offers three transactional methods: CHECK_BEFORE_SAVE, SAVE and CLEAN_UP. Whenever saving is triggered first the CHECK_BEFORE_SAVE method has to be called. If this call was successful the SAVE can be triggered and at the end the CLEAN_UP is supposed to be called. The Service Provider Infrastructure internally dispatches those calls to all Service Providers which participate in the current LUW.

Even though the transactional methods are defined as instance methods they are invoked only once per Application Building Block, so their implementation must act in a static way.

FPM SPI Integration Handles Transactional Logic Automatically

When using the FPM SPI Integration, the transactional logic is automatically handled by the FSI, so the application UI doesn't need to call any of those transactional Service Provider methods.

Application Must Never COMMIT or ROLLBACK

COMMIT WORK AND WAIT and ROLLBACK WORK are handled centrally by the Service Provider Infrastructure based on the result of the SAVE call. An application must never commit or rollback data by itself, this would potentially lead to data inconsistencies and data loss.

CHECK_BEFORE_SAVE

The method CHECK_BEFORE_SAVE validates the complete application buffer regarding consistency, across all nodes and for all data records.
Within this method the application has to execute all possible checks, so that a later call of the SAVE method does not fail, since at this point of time the SAVE chain can be cancelled without any data loss.
If errors occur during the actual SAVE the SPI will trigger a ROLLBACK WORK. Therefore it is essential to check data consistency as far as possible at this point of time.

Method signature:

Parameter

Data Type

Description

EV_FAILED

/PLMB/SPI_FAILED_IND

Failed indicator

Detailed Parameter Description

  • The failed indicator EV_FAILED has to be set if an error/inconsistency in the buffer was found that needs to be resolved before the actual save.
    If EV_FAILED is set the SAVE chain needs to be cancelled, i.e. the method SAVE is not called for any of the involved Service Providers.
    By doing so the consumer is able to correct the errors and start the SAVE chain again.

SAVE

The SAVE method saves the complete application buffer (all nodes and all data records).
If the SAVE call was successful for all participating Service Providers, SPI will execute a COMMIT WORK AND WAIT.
However if the save call of one of the Service Providers fails, the SPI executes a ROLLBACK WORK. This is required since multiple Service Providers might be participating within a save chain and therefore Service Providers that were called previously via SAVE might have already called e.g. function modules in update task. Therefore ROLLBACK WORK is the only way to avoid data inconsistencies.

Method signature:

Parameter

Data Type

Description

EV_FAILED

/PLMB/SPI_FAILED_IND

Failed indicator

Detailed Parameter Description

  • The failed indicator EV_FAILED has to be set if an error during the save process has occurred.

Failure of Save Needs to be Avoided

After a failed SAVE a ROLLBACK WORK is triggered and all unsaved data will be lost. Therefore it is essential to include all checks that are performed in the SAVE also in the CHECK_BEFORE_SAVE to reduce the chance of a SAVE failure to a minimum. When using the FPM SPI Integration, a failed save will result in a navigation to the error page which doesn't allow any further processing in the UI.

CLEAN_UP

The CLEAN_UP method refreshes the complete application buffer and releases all locks.
This method can also be called independently from the save chain.

Method signature:

Parameter

Data Type

Description

IV_REASON

/PLMB/SPI_CLEAN_UP_REASON

Reason code for cleanup call

Detailed Parameter Description

  • IV_REASON specifies the context in which the CLEANUP was triggered, following values are possible:
    • Buffer Refresh
    • Commit Work
    • Rollback Work

Constants for Clean Up Reason

Constants are available at /PLMB/IF_SPI_C=>GS_C_CLEANUP_REASON.