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

Introduction

The Collector is a central SPI component that is responsible for collecting all information beyond the data flow.
This includes:

  • Messages
  • Field Properties
  • Operation Properties
  • Invalid Nodes (~Change Pointer)
  • Key Replacements

This data is provided by the application (~Service Provider) via the Collector input interface.
This interface instance is provided by SPI upon instantiation of the Service Provider.
The Collector input interface is typically used only by the SP of an application.

Additional services of the Collector:

All collected data can be consumed via a specific Collector output interface.
This interface instance is provided by SPI upon instantiation of the Connector.

FPM SPI Integration (FSI) Handles Complete Collector Data

When using the FPM SPI Integration (FSI) the Collector output interface is accessed only internally by the FSI and all provided data is automatically processed by it.

The Collector is not a Singleton

Each SP instance has its own Collector instance that is passed by the SPI to the SP during its initialization.
Therefore it is very important that a Service Provider always buffers/uses the related Collector instance correctly.

Input Interface / Data Supply

The input interface of the Collector is /PLMB/IF_SPI_COLLECTOR.
It provides the following functionality:

Add Messages

One of the main purposes of the Collector is to collect messages in the backend and provide them to the consumer (e.g. frontend / user interface).
Along with the actual message information also the context of the message (so called reference data) can be passed to the Collector which allows the consumer of the messages to link them to the respective data record the message belongs to.

Usage of Reference Data

Typically the reference data of a message is a node ID. This makes sense whenever the message belongs to a record that already has a node ID assigned, as it is normally the case.
There are however some use-cases where messages refer to a record which has no node ID assigned yet e.g. during a failing INSERT call where no node ID was passed to the SP as an input.
In such a case the error message cannot refer to a node ID, since no node ID exists yet. To still be able to link such a message to the data record of the INSERT which caused the problem, we allow also to pass the complete (transient) data record as reference data (via the ..._ENH message methods of the Collector).

Duplicate Messages are Filtered

The Collector automatically filters duplicate messages. A message is considered as duplicate if all parts of the message (ID, type, number and variables) match in the context of the referenced node and data (e.g. node ID).

The relevant message methods are:

ADD_SYSTEM_MESSAGE

This method adds a single message from the system fields (SY/SYST) directly to the Collector.

Method signature:

Parameter

Data Type

Description

IV_NODE_NAME

/PLMB/SPI_NODE_NAME

Node name the message refers to

IS_NODE_ID

ANY

Node ID the message refers to

IV_NODE_FIELD

FIELDNAME

Field in the node data structure the message refers to

ADD_MESSAGE

This method adds a single message (in the format of system messages) to the Collector.

Method signature:

Parameter

Data Type

Description

IS_MSG

SYMSG

Message structure (mandatory)

IV_NODE_NAME

/PLMB/SPI_NODE_NAME

Node name the message refers to

IS_NODE_ID

/PLMB/SPI_NODE_NAME

Node ID the message refers to

IV_NODE_FIELD

FIELDNAME

Field in the node data structure the message refers to

ADD_MESSAGE_FREE_TEXT

This method adds a single free text message (string) to the Collector.

Method signature:

Parameter

Data Type

Description

IV_MSG_TEXT

/PLMB/SPI_MSG_FREE_TEXT

Message text (mandatory)

IV_MSG_TYPE

SYMSGTY

Message type (mandatory)

IV_NODE_NAME

/PLMB/SPI_NODE_NAME

Node name the message refers to

IS_NODE_ID

ANY

Node ID the message refers to

IV_NODE_FIELD

FIELDNAME

Field in the node data structure the message refers to

ADD_EXCEPTION

This method converts the given exception (and all previous exceptions) to a message and adds it to the Collector.
To make the conversion work the exception class needs to implement the interface IF_T100_MESSAGE.

Method signature:

Parameter

Data Type

Description

IO_EXCEPTION

CX_ROOT

Exception (mandatory)

IV_NODE_NAME

/PLMB/SPI_NODE_NAME

Node name the exception refers to

IS_NODE_ID

ANY

Node ID the exception refers to

IV_NODE_FIELD

FIELDNAME

Field in the node data structure the exception refers to

ADD_MESSAGE_TAB

This method adds a table of messages (SPI message format) to the Collector.

Method signature:

Parameter

Data Type

Description

IT_MSG

/PLMB/T_SPI_MSG

Table of messages (mandatory: standard message data; optional: message index and fieldname)

IV_NODE_NAME

/PLMB/SPI_NODE_NAME

Node name the message refers to

IT_NODE_REF

INDEX TABLE

Either a table of node IDs or node data. The Collector will assign the relevant node IDs to the message via the message index of IT_MSG.

If the message table contains message indices then the import parameters IV_NODE_NAME and IT_NODE_REF need to be supplied as well.

ADD_MESSAGE_TAB_FREE_TEXT

This method adds a table of messages (with message type and free text) to the Collector.

Method signature:

Parameter

Data Type

Description

IT_MSG_FREE_TEXT

/PLMB/T_SPI_COLL_MSG_FREE_TEXT

Table of messages (mandatory: message text and message type; optional: message index and fieldname)

IV_NODE_NAME

/PLMB/SPI_NODE_NAME

Node name the message refers to

IT_NODE_REF

INDEX TABLE

Either a table of node IDs or node data. The Collector will assign the relevant node IDs to the message via the message index of IT_MSG_FREE_TEXT.

If the message table contains message indices then the import parameters IV_NODE_NAME and IT_NODE_REF need to be supplied as well.

ADD_MESSAGE_ENH

This method adds a table of messages to the Collector.

Method signature:

Parameter

Data Type

Description

IT_MSG

/PLMB/T_SPI_MSG

Table of messages (mandatory: standard message data; optional: message index and fieldname)

IV_NODE_NAME

/PLMB/SPI_NODE_NAME

Node name the message refers to

IV_REFERENCE_TYPE

ANY

Provides the context of the message in combination with the reference data. (mandatory)

IG_REFERENCE_DATA

/PLMB/SPI_MSG_REF_TYPE

Contains either a table or structure of reference data. The Collector will extract the reference data via the message index of IT_MSG and assign it to the message.

If the message table contains message indices then the import parameters IV_NODE_NAME and IG_REFERENCE_DATA need to be supplied as well.

Following reference types are available:

Reference Type

Description

Reference Data

Typical Usage in UI

ABB

The message refers to the whole Application Building Block

none

a message will be displayed without a link

NODE

The message refers to a node

none

a message will be displayed without a link

DATA_RECORD

The message refers to a certain data record of a node

Node ID

an error message will be linked to a row whose UPDATE failed

TRANSIENT_DATA_RECORD

The message refers to a transient data record (i.e. data record which is not yet created)

Node data

an error message will be linked to a row whose INSERT failed

Constants for Message Reference Type

Constants are available at /PLMB/IF_SPI_C=>GS_C_MSG_REF_TYPE

ADD_MESSAGE_FREE_TEXT_ENH

This method adds a table of free text messages to the Collector.

Method signature:

Parameter

Data Type

Description

IT_MSG

/PLMB/T_SPI_COLL_MSG_FREE_TEXT

Table of messages (mandatory: message text and message type; optional: message index and fieldname)

IV_NODE_NAME

/PLMB/SPI_NODE_NAME

Node name the message refers to

IV_REFERENCE_TYPE

ANY

Reference type

IG_REFERENCE_DATA

/PLMB/SPI_MSG_REF_TYPE

Reference data the message refers to

Since the import parameters match the ones of method ADD_MESSAGE_ENH, please refer to the description of this method for more details.

Set Field and Operation Properties

The Collector is the channel to transport field properties (which can be used e.g. to control input fields or checkboxes on a UI) and operation properties (which can be used e.g. to control push buttons on a UI) from the backend to the consumer (e.g. to the FPM SPI Integration (FSI) which automatically applies this info to the UI).

Field properties focus on attributes/fields of a node: it allows setting them to editable, mandatory, read-only, inactive or invisible.
Properties are defined via profiles: for field properties a profile consists of the field name and an option (e.g. read-only).

Operation properties focus on controlling node operations like delete or actions: they can be set to enabled, disabled and invisible.
An operation control profile consists of an operation type (e.g. action or delete), an operation name (only relevant for operation type action or query) and the option (e.g. active).

Properties and Operation Properties can be supplied in two different ways to the Collector: either by push mechanism or by pull mechanism.
If the Pull Mechanism shall be used for a Service Provider the metadata definition on Application Building Block (ABB) level has to be maintained accordingly.

For all new applications we strongly recommend to use the pull mechanism for the properties since it offers the following benefits:

  • Easier to consume
  • More transparent/no implicit mechanism
  • Better performance, since properties are only returned and calculated if requested (enables paging)

The pull of properties was introduced with SAP_BS_FND 731. Service Provider implemented based on an older version have to use the push mechanism.

Constants for Properties

Field Property Options: /PLMB/IF_SPI_C=>GS_C_PROPERTY
Operation Property Options: /PLMB/IF_SPI_C=>GS_C_OPERATION_PROPERTY
Operation Type: /PLMB/IF_MDP_C=>GS_C_OPERATION_TYPE

Merging Properties

If during one SPI call (e.g. RETRIEVE) multiple property profiles are supplied with the same reference (e.g. for the same node ID), the Collector will merge them property by property whereas the more restrictive properties win. This means for field properties changeable < mandatory < read-only < inactive < invisible, which results in the matrix shown below:

*

Changeable

Mandatory

Read-Only

Inactive

Invisible

Changeable

Changeable

Mandatory

Read-Only

Inactive

Invisible

Mandatory

Mandatory

Mandatory

Read-Only

Inactive

Invisible

Read-Only

Read-Only

Read-Only

Read-Only

Inactive

Invisible

Inactive

Inactive

Inactive

Inactive

Inactive

Invisible

Invisible

Invisible

Invisible

Invisible

Invisible

Invisible

For operation properties the order is active < inactive < invisible, which allows deriving the following matrix:

*

Active

Inactive

Invisible

Active

Active

Inactive

Invisible

Inactive

Inactive

Inactive

Invisible

Invisible

Invisible

Invisible

Invisible

For example during a RETRIEVE call the Service Provider calls the Collector twice, handing over the following two sets of field properties:

NODE_FIELD

A

B

C

D

E

F

G

OPTION

Mandatory

Changeable

Read-Only

Changeable

Changeable

Inactive

Read-Only

NODE_FIELD

A

B

E

G

OPTION

Read-Only

Mandatory

Read-Only

Invisible

The resulting profile that will be stored in the Collector is the following:

NODE_FIELD

A

B

C

D

E

F

G

OPTION

Read-Only

Mandatory

Read-Only

Changeable

Read-Only

Inactive

Invisible

From a performance point of view it may be better in some cases to do the merging inside the SP itself.
Therefore the SPI offers following static service methods at class /PLMB/CL_SPI_COLLECTOR:

  • MERGE_PRPTY_PROFILES: merges one property profile into another; if a field is supplied multiple times with different options the most restrictive option wins according to the above rule.
  • MERGE_OPERATION_PRPTY_PROFILES: merges one operation property profile into another; as for field properties the most restrictive option wins.

Properties are Only Merged Within One SPI Call

As described above properties are merged within a single SPI call.
However if a second call happens that provides new properties, those properties are not merged with any old properties of previous calls.
Instead the new properties simply overwrite the old properties.
This also makes sense because otherwise it would not be possible to change a field e.g. from read-only to changeable ever again.

Recommendation on Property Implementation

The property merging capabilities of the Collector allow handling the properties in a very efficient way.
The basic idea when defining the property profiles is to define per node one – or if required more, maybe based on a certain node attribute, e.g. material type – base profile that contains the softest state of all fields. In addition a set of so called delta profiles are defined, which are in most cases slimmer than the base profile. Those delta profiles restrict the base profile based on ID specific information, like e.g. the status of an object, authorizations or field dependencies. This approach allows reducing the complexity of the property profiles.
So when for example a RETRIEVE by association is called, the Service Provider can return property information which is valid for the whole node and in addition it can add per node ID additional property information that 'fine tunes' the rough node properties, if required.

Properties Have a Great Impact on Performance

Defining the field control profiles is one of the most critical tasks during development of an application! Bad design/implementation can lead to performance issues, unnecessary huge profiles (as well in number and in width) making future extensibility cumbersome and ineffective.

Pull Field and Operation Properties

The normal use case for pulling properties is that the consumer has the node ID(s) of the relevant data and pulls via this information the related properties. The backend receives those node IDs and can read from its buffer the required data information for calculating the properties. For a consumer it must be sufficient to supply only node IDs (less data traffic, better performance, no additional unnecessary data reads on consumer side), the backend has all relevant information anyhow accessible.
The Pull mechanism is realized via an explicit interface (/PLMB/IF_SPI_PROPERTIES_ACCESS) that defines two methods for retrieving the Field Properties and Operation Properties. The interface has to be implemented by the Service Provider if it wants to support the pull-mechanism.

Avoid Dependencies in Property Logic

Field and operation properties can also be requested from SPI explicitly without using any of the application access methods (RETRIEVE, INSERT...), therefore it is important that a Service Provider never tries to implement the pull properties dependent on other SP calls.

GET_PROPERTIES

Via this method of interface /PLMB/IF_SPI_PROPERTIES_ACCESS the SPI pulls the field properties from the SP and fills the result into the Collector.

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

IV_REFERENCE_TYPE

/PLMB/SPI_PRPTY_REF_TYPE

Provides the context of the properties in combination with the reference data (mandatory)

IG_REFERENCE_DATA

ANY

Reference data

IT_REQUESTED_FIELD

/PLMB/T_SPI_REQUESTED_FIELD

Requested field property fields

ET_PROPERTIES_SINGLE_IDX

/PLMB/T_SPI_INDEXED_PROPERTY

Properties with an index that identifies the referencing line in IG_REFERENCE_DATA

ET_PROPERTIES_MULTI_IDX

/PLMB/T_SPI_INDEXED_PRP_MULTI

Properties with a set of indices identifying the referencing lines in IG_REFERENCE_DATA

ET_PROPERTIES

/PLMB/T_SPI_PROPERTIES

Properties which apply for all given records or, if no records are supplied, that fit to the given reference type

The usage of ET_PROPERTIES_SINGLE_IDX and ET_PROPERTIES_MULTI_IDX and ET_PROPERTIES can be combined without restrictions: one can use either one of those parameters or an arbitrary combination for optimized properties definition. The SPI will internally merge the given properties.

The reference type (IV_REFERENCE_TYPE) specifies what kind of properties is requested and which data is provided via IG_REFERENCE_DATA. Following reference types are available:

Reference Type

Description

Reference Data

Typical Usage in UI

NODE

The field properties refer to all data records of a node

none

Gets applied to all rows of the UI table

DATA_RECORDS_BY_ASSOCIATION

The field properties refer to all data records with a certain parent data record (IV_NODE_NAME contains the parent node name and IV_TARGET_NODE_NAME the actual node name)

Parent Node ID

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

DATA_RECORD

The field properties refer to a specific data record of the node

Node ID

Gets applied to the row that matches the node ID

INSERT

The field properties refer to all data records of a node that were not inserted yet

none

Gets applied to all empty/default rows

INSERT_BY_ASSOCIATION

The field properties refer to all data records of a node that were not inserted yet and refer to a certain parent data record

Parent node ID

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

TRANSIENT_DATA_RECORD

The field properties refers to a transient data record (i.e. data record which is not yet created)

Node data

Gets applied to a row (which was not provided by the backend) that matches the node data e.g. a row whose INSERT failed

Constants for Field Property Reference Type

Constants are available at /PLMB/IF_SPI_C=>GS_C_PRPTY_REF_TYPE

GET_OPERATION_PROPERTIES

Via this method of interface /PLMB/IF_SPI_PROPERTIES_ACCESS the SPI pulls the operation properties from the SP and fills the result into the Collector.

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

IV_REFERENCE_TYPE

/PLMB/SPI_OPR_PRPTY_REF_TYPE

Provides the context of the properties in combination with the reference data (mandatory)

IG_REFERENCE_DATA

ANY

Reference data

ET_OPR_PROPERTIES_SINGLE_IDX

/PLMB/T_SPI_INDEXED_OPR_PRPTY

Properties with an index that identifies the referencing line in IG_REFERENCE_DATA

ET_OPR_PROPERTIES_MULTI_IDX

/PLMB/T_SPI_NDX_OPR_PRPTY_MULT

Properties with a set of indices identifying the referencing lines in IG_REFERENCE_DATA

ET_OPERATION_PROPERTIES

/PLMB/T_SPI_OPERATION_PRPTY

Properties which apply for all given records or, if no records are supplied, that fit to the given reference type

The signature and usage of this method is nearly identical to GET_PROPERTIES as described above. The main difference is that a different set of reference types is available:

Reference Type

Description

Reference Data

Typical Usage in UI

NODE

The operation properties refer to all data records of a node

none

Gets applied to a toolbar button

DATA_RECORDS_BY_ASSOCIATION

The operation properties refer to all data records with a certain parent data record
(IV_NODE_NAME contains the parent node name and IV_TARGET_NODE_NAME the actual node name)

Parent Node ID

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

DATA_RECORD

The operation properties refer to a specific data record of the node

Node ID

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

Constants for Operation Property Reference Type

Constants are available at /PLMB/IF_SPI_C=>GS_C_OPR_PRPTY_REF_TYPE-...

Push Field and Operation Properties

When using this approach it is strongly recommended that the Service Provider always returns field control information for the data it returns. In other words: as a consumer of a Service Provider (independent if this is the FPM SPI Integration (FSI) or another consumer) it is expected that the Collector instance is supplied with the field control information for the returned data (parameter ET_NODE_DATA).

Field Properties

For supplying properties different methods depending on the required use case exist:

SET_PROPERTIES

This method allows setting the field properties either of the whole node or of a distinct data record which is identified via its node ID.

Method signature:

Parameter

Data Type

Description

IV_NODE_NAME

/PLMB/SPI_NODE_NAME

Node name (mandatory)

IS_NODE_ID

ANY

Node ID

IT_PROFILE

/PLMB/T_SPI_PRPTY_PROFILE

List of properties (mandatory)

It is mandatory to specify for which node field control information (= profile) is provided. Optionally an ID can be specified. If no node ID is provided the field control is understood as 'default field control' for the whole node. From a UI perspective this would mean that all columns of a table can be set e.g. to read-only or changeable. If an ID is provided the supplied profile information is only applied to the data set matching the ID.

Use Mass-Enabled Method Whenever Possible

In many cases properties are identical for a list of node IDs, e.g. all 20 items of a list have the same editable fields (key fields read-only, descriptions editable...). In this case the method SET_PROPERTIES_MULTI can be used to achieve a better performance.

SET_PROPERTIES_MULTI

In many cases field properties are identical for a list of node IDs. In this case this method should be used.

Method signature:

Parameter

Data Type

Description

IV_NODE_NAME

/PLMB/SPI_NODE_NAME

Node name (mandatory)

IT_NODE_ID

INDEX TABLE

Node IDs

IT_PROFILE

/PLMB/T_SPI_PRPTY_PROFILE

List of properties (mandatory)

SET_PROPERTIES_ENH

This method is the most powerful option to supply field properties. It covers all possible use cases.

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

IV_REFERENCE_TYPE

/PLMB/SPI_PRPTY_REF_TYPE

Provides the context of the properties in combination with the reference data (mandatory)

IG_REFERENCE_DATA

ANY

Reference data

IT_PROPERTIES_SINGLE_IDX

/PLMB/T_SPI_INDEXED_PROPERTY

Properties with an index that identifies the referencing line in IG_REFERENCE_DATA

IT_PROPERTIES_MULTI_IDX

/PLMB/T_SPI_INDEXED_PRP_MULTI

Properties with a set of indices identifying the referencing lines in IG_REFERENCE_DATA

IT_PROPERTIES

/PLMB/T_SPI_PROPERTIES

Properties which apply for all given records or (if no records are supplied) that fit to the given reference type

The usage of the parameters is identical to GET_PROPERTIES as described in the pull chapter.

SET_PROPERTIES_FOR_NODE

If for a complete node (i.e. all fields) the same property should be applied, this method can be used.

Method signature:

Parameter

Data Type

Description

IV_NODE_NAME

/PLMB/SPI_NODE_NAME

Node name (mandatory)

IV_OPTION

/PLMB/SPI_PRPTY_OPTION

Option to be applied e.g. editable (mandatory)

SET_PROPERTIES_WITH_MERGE

This is another service routine to supply properties. It allows handing over multiple property profiles that are internally merged by the Collector.

Method signature:

Parameter

Data Type

Description

IV_NODE_NAME

/PLMB/SPI_NODE_NAME

Node name (mandatory)

IS_NODE_ID

ANY

Node ID

IT_PROFILES

/PLMB/T_SPI_PROFILE_DEF

Properties to be merged and applied (mandatory)

Operation Properties

For supplying operation properties different methods depending on the required use case exist:

SET_OPERATION_PROPERTIES

This method allows setting the operation properties either of the whole node or of a distinct data record which is identified via its node ID.

Method signature:

Parameter

Data Type

Description

IV_NODE_NAME

/PLMB/SPI_NODE_NAME

Node name (mandatory)

IS_NODE_ID

ANY

Node ID

IT_PROFILE

/PLMB/T_SPI_OPERATION_PRPTY

List of operation properties (mandatory)

Use Mass-Enabled Method Whenever Possible

In many cases properties are identical for a list of node IDs. In this case the method SET_OPERATION_PROPERTIES_MULTI can be used to achieve a better performance.

SET_OPERATION_PROPERTIES_MULTI

In many cases operation properties are identical for a list of node IDs. In this case this method should be used.

Method signature:

Parameter

Data Type

Description

IV_NODE_NAME

/PLMB/SPI_NODE_NAME

Node name (mandatory)

IT_NODE_ID

INDEX TABLE

Node IDs

IT_PROFILE

/PLMB/T_SPI_OPERATION_PRPTY

List of operation properties (mandatory)

SET_OPERATION_PROPERTIES_ENH

This method is the most powerful option to supply operation properties. It covers all possible use cases.

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

IV_REFERENCE_TYPE

/PLMB/SPI_OPR_PRPTY_REF_TYPE

Provides the context of the properties in combination with the reference data (mandatory)

IG_REFERENCE_DATA

ANY

Reference data

IT_OPR_PROPERTIES_SINGLE_IDX

/PLMB/T_SPI_INDEXED_OPR_PRPTY

Properties with an index that identifies the referencing line in IG_REFERENCE_DATA

IT_OPR_PROPERTIES_MULTI_IDX

/PLMB/T_SPI_NDX_OPR_PRPTY_MULT

Properties with a set of indices identifying the referencing lines in IG_REFERENCE_DATA

IT_OPERATION_PROPERTIES

/PLMB/T_SPI_OPERATION_PRPTY

Properties which apply for all given records or (if no records are supplied) that fit to the given reference type

The usage of the parameters is identical to GET_OPERATION_PROPERTIES as described in the pull chapter.

Replace Node IDs / Late Numbering

Some applications offer internal numbering, meaning the key is taken from an (internal) number range, rather than being specified by the user explicitly (external numbering). In internal numbering two concepts exist: an early numbering whereas the internal key is directly assigned upon object creation and a late numbering whereas the application works with a temporary key (e.g. $00000001) until the object is saved.
In this case the backend needs to inform its consumers about the new keys and the consumer can then update its data accordingly (e.g. the FPM SPI Integration updates all administered context nodes).

For this purpose the Collector offers the method SET_NEW_NODE_ID:

Parameter

Data Type

Description

IV_NODE_NAME

/PLMB/SPI_NODE_NAME

Node name for which IDs are replaced (mandatory)

IT_OLD_NODE_ID

INDEX TABLE

Old node IDs (mandatory)

IT_NEW_NODE_ID

INDEX TABLE

New node IDs (mandatory)

IT_NODE_ID_REL

/PLMB/T_SPI_NODE_REL

Relationship between rows of IT_OLD_NODE_ID and IT_NEW_NODE_ID

How To

It is important to know that if your node model contains multiple nodes that offer different views on the same data records, you need to exchange the IDs not only for one of those nodes but for all of them.
Example: Your node model contains a node 'HEADER' and a node 'INIT' which is only used to enter the application and both nodes refer in the backend to the same record i.e. both nodes have the same node ID as well. If you would now replace only the IDs for node 'HEADER', the data of the node 'INIT' would still remain outdated which might result in inconsistencies on the consumer side e.g. in the UI some data might be displayed incorrectly or errors might occur. In other words your Service Provider would have to trigger an ID replacement for the node 'HEADER' as well as for the node 'INIT' in case the underlying key changes.

Usage Restrictions

This method can only be called during the SAVE.

Invalidate Node Data

The Collector offers a mechanism to invalidate complete Application Building Blocks, specific nodes and even distinct node IDs at runtime. This information is supplied by the Service Provider based on runtime information, e.g. data updates. The consumer can evaluate this information to trigger data refreshes (RETRIEVE method). The FPM SPI Integration (FSI) for example uses this information to initialize the internal node ID buffers that prevent unnecessary data retrievals.

Scope of Invalidation

If only a few records were changed it is advisable not to invalidate the whole node or ABB, instead the invalidation should take place on node ID level to avoid unnecessary data retrievals which reduce the performance of any consumer e.g. the UI.

The Collector Input interface offers three simple methods for the different scopes of node invalidation:

Invalidation of a complete Application Building Block

When reusing another Application Building Block (ABB) it can be necessary that the other ABB needs to be refreshed completely due to data changes in the own ABB. In most reuse scenarios the metadata model of the reuse component is not known – or not wanted to be known because node models can change. Only the ABBID might be a reliable anchor. In such cases the method INVALIDATE_ABB can be used to invalidate all nodes of the other application.

Method signature:

Parameter

Data Type

Description

IV_ABBID

/PLMB/SPI_ABBID

Application Building Block ID (mandatory)

Invalidation of nodes

Method INVALIDATE_NODES can be used to invalidate a set of nodes. If the nodes do not belong to a different Application Building Block (ABB) than the own, it is necessary to specify this ABB with the import parameter IV_ABBID. If the nodes are located in the own metadata node model the parameter does not need to be supplied.

Method signature:

Parameter

Data Type

Description

IV_ABBID

/PLMB/SPI_ABBID

Application Building Block ID

IT_NODE_NAME

/PLMB/T_SPI_NODE_NAME

Nodes to be invalidated (mandatory)

IV_REASON

/PLMB/SPI_INVALIDATION_REASON

Reason for the invalidation

The parameter IV_REASON allows specifying the reason for the node invalidation which allows the consumer of the node invalidation information to react according to the reason.
E.g. when the reason is "lock" only records which were not locked before need to be RETRIEVED again, which allows avoiding unnecessary backend calls.

Following reason values are possible:

  • LOCK: A record has been locked (i.e. data which was read before without lock may be outdated)
  • INSERT: A new record has been inserted
  • UPDATE: A record has been updated
  • DELETE: A record has been deleted

Constants for Invalidation Reason

Constants are available at /PLMB/IF_MDP_C=>GS_C_INVALIDATION_REASON

Invalidation of Node IDs

The most fine granular way of invalidating node data is an invalidation on node ID level via method INVALIDATE_NODE_IDS. In that case only specific data records will be refreshed.

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 invalidated (mandatory)

IV_SCOPE

/PLMB/SPI_INVALIDATION_SCOPE

Scope of the invalidation

IV_REASON

/PLMB/SPI_INVALIDATION_REASON

Reason for the invalidation

The parameter IV_REASON which is also available at method INVALIDATE_NODES is described above.

The usage of the parameter IV_SCOPE only makes sense if the data records of one node have certain interdependencies as it is the case with hierarchical data for example.
In such a case the scope allows to inform the consumer that also (or only) dependent data records are invalidated. To avoid confusion with the term node dependencies: a dependent node ID in this case only means interdependencies of data records of a single node.

Following scope values are possible:

  • ID_ONLY: only the specified ID(s) are invalidated
  • DEPENDENT_ID_ONLY: only dependent ID(s) are invalidated (e.g. child elements in a tree)
  • ID_AND_DEPENDENT_ID: the specified ID(s) and dependent ID(s) are invalidate

Constants for Invalidation Scope

Constants are available at /PLMB/IF_MDP_C=>GS_C_INVALIDATION_SCOPE

Output Interface / Data Consumption

The output interface of the Collector is /PLMB/IF_SPI_COLLECTOR_OUTPUT.

Usage of Collector Output

When using the Application Model of the FPM SPI Integration (FSI) the Collector output interface is accessed only internally by the FSI and all provided data is automatically processed by it. Also all Collector buffers will get cleared immediately after every SP call.

The Collector output interface offers following functionality:

Get Messages

Via method GET_MESSAGES or GET_MESSAGES_ENH all available messages can be retrieved, optionally a node name can be specified as a filter criterion.

Get Field and Operation Properties

Via methods GET_PROPERTIES/GET_PROPERTIES_ENH and GET_OPERATION_PROPERTIES/GET_OPERATION_PROPERTIES_ENH all available properties can be obtained.
The signature of those methods is identical with the methods of interface /PLMB/IF_SPI_PROPERTIES_ACCESS which is described above.

If the Service Provider supports the pull mechanism and a certain set of properties is requested, which is not already contained in the Collector, the SPI actively pulls the properties from the Service Provider.
Furthermore every application that support the pull mechanism can setup an automatism that pulls the properties after every (at least partly) successful SP call.
Therefore the methods ADD_PRPTY_PULL_OPTIONS, REMOVE_PRPTY_PULL_OPTIONS and GET_PRPTY_PULL_OPTIONS are available, which allow defining removing and reading the options for the automatic pulling of properties.

Get Replaced Node IDs / Late Numbering

Method GET_LINK_TO_NEW_NODE_ID returns all exchanged node IDs (late numbering).

Get Invalidated Node Data

All invalidated ABBs, nodes and node IDs are provided when calling method GET_INVALID_NODES.
This includes not only the node invalidation information that was actively handed over to the Collector by the SP but also any side-effect which has occurred in the meantime. After every (at least partly) successful SP call, the SPI internally evaluates the maintained side-effects and node dependencies of the metadata definition to identify all invalidated nodes and fills them into the Collector.

Buffer Initialization

The method INIT_BUFFER initializes the buffer of the Collector instance. The import parameter IV_TARGET controls which buffer is affected, following options are possible via constant /PLMB/IF_SPI_C=>GS_C_TARGET-

  • MESSAGE – messages
  • PROPERTY – field properties
  • OPERATION_PROPERTY – operation properties
  • NODE_ID_MAP – exchanged node IDs
  • INVALID_NODES – invalid nodes
  • ALL – all buffers

FSI Initializes Buffers Immediately

When using the Application Model of the FSI the Collector data will be processed and all buffers will be cleared immediately after every SP call.

  • No labels

6 Comments

  1. Former Member

    Hello Mr. Maximilian Schneider ,

      Can we influence field properties using BADI implementation ?

      I have  implemented BADI /PLMB/EX_SPI_APPL_ACCESS and method AFTER_RETRIEVE and tried to change field properities using Method SET_PROPERTIES of Collector instance and I would like to change to more Restrictive option ( Read only ) than  from Standard SAP Solution ( Changeable ). But stil I see Changeable is the outcome..

     Any clues..?

     

    Thanking you,

     

    Regards,

     Satya

     

    1. Hello Satya,

      It may be the case that your field properties are overwritten by a subsequent SPI call.
      I added some more details to the enhancement chapter about how to avoid such issues.

      Best regards,
      Maximilian Schneider 

  2. Former Member

     

    Hello Mr. Maximilian Schneider ,

      Thankyou for update. According to your updated Notes , I have enhanced rest of  'AFTER' methods with similar logic. Still  I do not have luck.

    Do we need to add some other setting as well.

    Thanking you,

    Regards,

      Satya

     

     

    1. Hello Satya,

      there can be several reasons why this is not working. Maybe the BAdI is not invoked or the field in the UI is not bound to the properties of the context element (as described here). If you are still struggling with this enhancement I suggest that you contact our support via component CA-EPT-SPI.

      Best regards,
      Maximilian Schneider

      1. Former Member

        Hello Mr. Schneider ,

          Thanking you. Now it works. I have observed small problem with my BADI implementation . Strangly it works even if I do not apply my implementations to in other methods of Interface.

          Regards,

            Satya

         

  3. Former Member

     

    Hello Mr. Maximilian Schneider ,

      BAdi is triggering. Because I see it through debugging.

      Field in UI is bound in my opinion as my change in debugging is really effecting how UI looks like. I tried to manipulate where  SAP Standard is trying to change field properties and I can see effect in output.

    I will try to see , if I can crack it. If not I will try to connect with your support.

    Thanks alot .

     Regarads,

      Satya