Convenience Features

The SAP Gateway Foundation framework can automatically add an F4 style value help to certain primitive properties of a "parent" OData version 4 (V4) service.

Such an F4 help for a primitive property consists of the following:

Annotations that are added to the metadata of the parent OData V4 service
A separate F4 help service with one entity set

Annotation

Here you can find an example of annotations for an F4 help of a primitive property CURR_CODE of entity type SEARCHHELPENTITY.

Sample Code

<Annotations Target="SAP__self.SearchHelpEntity/CURR_CODE">
  <Annotation Term="SAP__common.ValueList">
    <Record>
      <PropertyValue String="../../../../f4/sap/tcurc-ct/0001;ps='default-
                      *iwbep*tea_tech-0001'" Property="CollectionRoot"/>
      <PropertyValue String="ValueList" Property="CollectionPath"/>
      <PropertyValue Property="SearchSupported" Bool="false"/>
      <PropertyValue Property="Parameters">
        <Collection>
          <Record Type="SAP__common.ValueListParameterDisplayOnly"
            <PropertyValue String="WAERS"
                            Property="ValueListProperty"/>
          </Record>
          <Record Type="SAP__common.ValueListParameterDisplayOnly">
            <PropertyValue String="LTEXT" 
                           Property="ValueListProperty"/>
          </Record>
        </Collection>
      </PropertyValue>
    </Record>
  </Annotation>
</Annotations>

The property "Collection Root" describes the relative path to the F4 help service. In this example ../../../../f4/sap/tcurc-ct/0001;ps='default-*iwbep*tea_tech-0001'.

The property "Collection Path" is the name of the entity set that contains the corresponding values.

F4 Help Service

Every service group contains (virtually) every F4 help service of any of the parent OData V4 services that have been assigned to the group explicitly.

A request for an F4 help service only works in the context of a service group (like any other request). First the framework does the standard authorization, so that the user has the start authorization for that group. Then it is validated that the service is (virtually) part of the service group.

The request for the F4 help service is then processed by the SAP Gateway Foundation framework.

Comments

The configuration (routing, start authorization, publication) for an OData V4 service is done on a service group level (and not per service). Therefore, an F4 help service "inherits" this configuration from the service group and does not need its own configuration.

Consequently, the routing of an F4 help service points to the same backend system as the routing of the parent OData V4 service that contains the F4 help service. And a user who has access to the parent OData V4 service can access every F4 help services the parent service contains.

How to Add an F4 Help Service to Your OData V4 Service

An F4 help is added to primitive properties if the following applies:

The property has an ABAP Dictionary reference. This is possible via the following methods:
- /IWBEP/IF_V4_MED_MODEL->CREATE_COMPLEX_TYPE_BY_STRUCT
- /IWBEP/IF_V4_MED_MODEL->CREATE_ENTITY_TYPE_BY_STRUCT
- /IWBEP/IF_V4_MED_CPLX_TYPE->CREATE_PRIM_PROPERTY_BY_ELEM
- /IWBEP/IF_V4_MED_ENTITY_TYPE->CREATE_PRIM_PROPERTY_BY_ELEM
The ABAP Dictionary reference contains F4 help information. That is, if one of the following applies:
- The data element contains a search help.
- The domain of the data element has fixed values.
- The domain of the data element has an assigned check table (value table).
The F4 help is explicitly requested for the primitive property.

This can be done on property level via method /IWBEP/IF_V4_MED_PRIM_PROP->SET_ADD_F4_HELP. This can be done via parameter IV_ADD_F4_HELP_TO_PRIM_PROPS of the methods /IWBEP/IF_V4_MED_MODEL->CREATE_COMPLEX_TYPE_BY_STRUCT or /IWBEP/IF_V4_MED_MODEL->CREATE_ENTITY_TYPE_BY_STRUCT.

Constraints

The type-ahead processor requires the select options (derived from $filter) in a specific external format while the framework delivers the information in an ABAP format after applying conversions. Therefore, certain data types (dates etc.) are not supported in F4 help filters at the moment.

It is important to note that the relative URI pointing to the F4 help service (that is, the value of the connection root annotation) might change in the future. Hence a client must not make any assumption about the structure of that URI and must not try to edit this URI.

If a primitive property of the parent service has a conversion that is not based on the underlying domain (that is, any other kind of conversion) an F4 help is currently not supported.

The combination of F4 helps and the metadata caching has certain restrictions. After changes to the parent service you need to clear the metadata cache for it to make sure that these changes are reflected for the corresponding F4 help services.