Show TOC

Preparing UI AnnotationsLocate this document in the navigation structure

Vocabularies and annotations allow you to extend OData services by adding information about how to interpret the OData service and its data. For a general introduction to vocabularies and annotations, see the following links:

On the SAP Gateway front-end server, you can find SAP-specific vocabularies in the SAP Gateway Service Builder (transaction SEGW) under Start of the navigation path Extras Next navigation step Vocabulary Repository End of the navigation path.

The following types of vocabulary-based annotations are available:
  • In-place: They are part of the metadata document of the service.

  • Ex-place: They are composed of an Annotation Provider Class (APC) outside the metadata document. The APC is bound to the service using a registration in transaction /IWBEP/REG_VOCAN.

These annotations are available using a query to the SAP Gateway catalog service, /sap/opu/odata/IWFND/CATALOGSERVICE;v=2/. Entity Set: ‚Annotations‘.

Reusability
If the OData service is editable instead of read-only, annotation elements must be added as required to activate or control the draft infrastructure. Existing read-only OData services that are annotated, for example fact sheets, are reusable for the list report and object page templates under the following circumstances:
  • The annotations should be stored in the back-end system and have the life cycle of the data model in the back-end system except in the case of the definition of facet texts which must take place in a front-end file after generation.

  • The OData service model (entity sets and entity types) are derived from CDS views. The CDS entities are the primary artifact for the data model. Based on annotations the transactional runtime model (based on the BOPF) is generated.

  • The UI annotations are attached to CDS views using the tags as defined by the SAP - ABAP Programming Model for SAP Fiori.
  • In the front end, CDS UI annotations are exposed generically and dynamically through SAP Gateway APIs (APC) as separately addressable OData Version 4.0 annotation documents.
  • Although you can use any source of annotations, the recommended way is to use CDS annotations at CDS consumption views, and to expose them using SAP Gateway and SADL. The exposure will then generate OData annotations (XML format) from the CDS annotations. In the following sections we will explain which OData annotation is controlling each UI element.

    For more information, see also the SAP - ABAP Programming Model for SAP Fiori.

Actions

General actions are available for draft-enabled documents (edit, save, cancel/discard), and you can also define additional actions using annotations.

The draft-handling actions are handled by the Business Object Processing Framework (BOPF ), whereas you must back up the application-specific actions using an implementation in the OData service. For more information about setting up application-specific actions in your annotations, see Actions in List Report View and Actions in Object Page Header.

Each action corresponds to an OData function import.

Field Control

You can use field control to display a UI field as a mandatory input, a read-only field, or to hide the field. The field control information is based on is partly static and valid for all business document instances. However, most use cases are dynamic and reflect the state of the UI application, business document, or user context and must be controlled by the business logic.

As business logic is implemented in the OData service, the OData service also has to provide the relevant field control information. This is valid for static information, which is contained in the service metadata, as well as for dynamic information, which is part of the entity data. There is a specification for an SAP extension of the OData protocol based on annotations for OData Version 2.0, which covers also field control. For more information, see SAP Annotations for OData Version 2.0Information published on SAP site.

The controls interpret and apply field control information provided by the OData service automatically. When using a smart field it is sufficient to bind the control’s value-Property to a property in the OData model in order to achieve field control as defined by the OData service. Field control of the OData service may be overruled by setting more restrictive properties for the smart field.

Sample Code Snippet of XML-View definition
... 

<!-- Field-control as defined in OData service -->   

<SmartField value="{Description}" />

     

<!-- Overrule field-control of OData service - read-only here -->    

<SmartField value="{Name}" editable="false" />

...