Skip to Content

Create Standalone Annotation using SAP Gateway Service Builder

In my previous blog on Annotation, I explained the process to create Annotation from service builder using Vocabulary. But this annotation is very specific to the service and you can not reuse this annotation for other services.

Standalone annotation feature of SAP Gateway enables you to create an annotation model that will be independent in nature and can be assigned to any number of relevant OData services. The advantage you are getting out of this feature is following

  • You will be able to create reusable annotation.
  • You can annotate an existing service externally.

Service Builder tool will help you create an annotation model and assign a service to it. In principle, it is possible to assign mutiple services to an annotation model but service builder supports only one service assignment to an Annotation Model.

This blog will explain how you can create annotation model by referring an existing service and assign this Annotation model to the same referenced service using SAP NetWeaver Gateway Service Builder tool.

This feature is available from SAP Gateway IWBEP SP09.


Step-by-Step Procedure

Following are steps which you need to follow

  • Upload Vocabularies into the Vocabulary Repository
  • Create a Project
  • Import a service for reference
  • Import a vocabulary file
  • Create Annotation
  • Generate Runtime Artifact
  • Access Annotation File

Upload Vocabularies into the Vocabulary Repository

Start the Service Builder by using the transaction SEGW.

To upload a vocabulary file into the Vocabulary Repository in the Service Builder, proceed as follows:

  1. From menu bar choose Extras ->Vocabulary Repository . The central Vocabulary Repository opens and shows a table for displaying the vocabulary ID, version, namespace, and description. Any previously uploaded vocabulary files are displayed here, otherwise the table is empty.UploadVocabulary.png
  2. Change to edit mode and choose Append Row to add a new row to the table.
  3. Enter a unique vocabulary ID for the vocabulary file you want to upload. Version 1 is assigned automatically to the first version of
    the vocabulary file you upload.
  4. Click the Upload icon in the Upload Vocabulary Content column to navigate to the vocabulary file you want to upload. The namespace of the vocabulary file is entered automatically.
  5. Enter a description for the newly uploaded vocabulary file.
  6. Save the changes and choose Enter.

Create a Project

  1. Create a New Project by clicking on /wp-content/uploads/2014/08/4_516913.jpg

  2. Select Service with Annotation Model for Referenced Service in order to create standalone annotation model.


Import a service for reference

The Service Reference option provided in the project type “Annotation Model for Referenced Service” helps you to reference a service registered in local BEP registry, so that the data model can be annotated.

  1. Right click of Data Model
  2. Select Import->Service Reference


  3.  In first screen of wizard,  enter technical name and version of  the service.


  4.  On click of ‘Next button, it will show th preview of OData elements this service is having

  5.  ClickFinish to import OData elements in Data Model.

Note: The OData artifacts imported in the project are non-editable because the project is only intended to create annotations.

Import a vocabulary file

  • In the edit mode, right click on the Data Model, choose Import->Vocabulary in the resulting menu.
  • The Vocabulary Repository window appears.
  • Select the required vocabulary(s) and click continue.


  • In the Tree view a new folder with the name Vocabularies will be created under the Data Model
    and the vocabularies imported into this folder.

Create Annotation

  1. Select OData element which you want to annotate
  2. Enter term value.


     3.   Click on ‘Save’ button

Generate Runtime Artifact

  • Click Generate Generate.PNGbutton.

          It will open a dialog box with prefilled values for Annotation provider class(APC) and Annotation Model. These are editable fields and you can change the name.


  • On click of Ok button, APC classes and Annotation Model will get created that you can see in Runtime Artifacts Folder and finally the referenced service will be assigned to the created Annotation Model .
  • APC Code: You can check annotation related code in method DEFINE_VOCAB_ANNOTATIONS( ) of generated APC.APC_class.PNG
  • Maintain Annotation Model: You can see Assignment of the Referenced Service to Annotation Model using transaction /iwbep/reg_vocan.


NOTE: You can reference only one service via Service Builder. However, using the transaction /IWBEP/REG_VOCAN multiple services can be assigned to the annotation model, but this causes an inconsistency as the services referenced via the transaction does not reflect in Service Builder.

Access Annotation File

  • Register the referenced service with Gateway Hub(If not registered). You can use Service maintenance feature of service builder for registration.
  • Load Metadata of the service. For this, click Maintainmaintain.PNGthat will take you to ‘Active and Maintain Services’ view of Gateway Hub where you can load metadata by clicking LoadMetadata.PNG.
  • Finally you can access annotation file through catalog service using below URL. Gateway  ClientGatewayclient.PNGbutton of service builder will take you to Gateway Client tool having request URI populated. Execute this URL to get annotation.


Note: Annotation file contains reference Uri of all the assigned services.


1.      Similarly if you want to get the reference Uri of annotation file in metadata of the service, it will only be available if you create the reference in the MPC of the service, e.g.

  lo_reference = vocab_anno_model->create_annotation_reference(
= ‘0001’).

c  Hope this helps you understand and create standalone annotation using service builder. I look forward to your feedback.
You must be Logged on to comment or reply to a post.
    • Hi Krishna,


           In general, annotation is used to provide additional information for OData elements(EntityType, EntitySet, Property, Association etc.) and application developer can use these information while developing applications.

      Suppose there is an OData service(e.g. EPM Service) without any annotation and has been shipped to customer. Customer wants to annotate this service but without changing MPC code so that their application developer can use it. This can be achieved with this new feature.

      Please feel free to ask me if you have any other questions regarding this 🙂

      Regards, Ashish.

      • Hi Ashish,

                     Can you please tell me the use of annotation and steps to use it in the existing service.

        Kindly help us, we just stuck to show the table content in front end.

  • Hi Ashish,

    step 'Access Annotation File' is unclear for me.

    How can I register the referenced service with Gateway Hub(If not registered).

    What do you mean with 'Service maintenance feature of service builder'.

    How can run this feature? What input is necessary?



  • Hi Ashish,

    first thank you for the detailed guide. Really helpful, and saves effort with reusage of annotations. I've technical question on this topic. Is it possible to annotate a project of type 1- Service with SAP Annotations externally with  type 3 - Service with SAP annotations using this technique?

    Thanks, Attila

  • Hi Ashish

    First congratulations on the article is very good. I have a question , after all activated and registered. When the original service is called with the parameter $metadata , The annotations created should not also appear ?


    Jam Carlos

  • Hi Ashish,

    Thanks for the good documentation. I got a question about the Annotations Target element, that it does not contains the schema name of the target. i.e. <Annotations Target="BusinessPartner/Address">. And it seems NOT compliant to the OData V4 standard.
    For this reason, it seems the UI5 side cannot consume this annotation successfully. Any idea about this?


  • Hi!, I have a problem , I updated my OData Service with a new entity but the annotation referenced model isn’t getting my new entity.

    There are any way to update my annotation without lost all work that I have done on it?