Skip to Content
Product Information
Author's profile photo Mariana Naboka

Maintaining annotations in CAP CDS projects becomes easier  with new LSP features 

Those who develop applications with the SAP Cloud Application Programming model (aka CAP) sometimes get stuck when it comes to maintaining annotations for SAP Fiori apps. Which annotations do I use? What do they look like in CAP CDS (core data services) syntax? How can I make sure I defined them correctly with no typographical errors that will break my UI (user interface)? And, if I do have a typo, how can I quickly find and fix it? In short, when will I have language server protocol (LSP) support for annotations in my CDS projects? 

Ever since we released the XML annotation LSP as part of SAP Fiori tools, we often receive questions from the CAP and SAP Fiori development communities on whether similar functionality will be provided for CAP core data services (aka CDS).   

The good news is that  SAP CDS language support plugin is now enhanced with a new module that helps you add and edit OData annotations applied to CDS models more efficiently.  

It provides the basic LSP features for OData annotations such as code completion, diagnostics, navigation to the referenced annotations, preview of vocabulary information and basic i18n support. 

Annotation%20LSP%20for%20CAP%20CDS 

Annotation LSP for CAP CDS

Let’s look deeper into the enhancements provided by this module to see how you can speed up the definition of annotations used in Fiori UIs while working in CAP CDS projects. 

From the functional perspective, it is very similar to XML annotation LSP extension provided as part of SAP Fiori tools. The main difference is that it works with the OData annotations in .cds files rather than in xml annotation files.  

 

Code Completion 

 

When you need to define annotations serving Fiori UIs in your .cds files, you can use the code completion for adding and editing annotations applied to service entities and elements. Just use CTRL + Space on Windows or CMD + Space on Mac in your annotate directive or next to your entity definition and choose from the list of applicable annotations to add. You can also choose to add just a vocabulary alias and then add several annotations from that vocabulary to the same annotate directive in the next steps. 

Code%20Completion%20for%20Annotations%20in%20CAP%20CDS

Code completion for OData annotations in SAP CAP CDS

Due to the built-in micro-snippets, the annotations are added along with the basic structure, so you do not need to remember and add it manually. Then, you can use the code completion again to define a qualifier and move with the Tab along the tab stops within the annotation body. Code completion can be used at each tab stop to add annotation records and properties, You can also select values for these properties, be they entity elements, Boolean or enumeration values, or even references to other annotations provided in the same file or underlying ones. 

Referencing%20annotations%20with%20code%20completion%20in%20CAP%20CDS

Referencing annotations with code completion in .cds files

You can check the vocabulary definition of the annotations and their elements while hovering over the annotation in the file or in the code completion lists. 

Viewing%20annotation%20definitions%20on%20hover

Viewing annotation definitions on hover

 

Diagnostics 

 

Every time you open or modify the .cds files, all OData annotations it contains are validated against the OData vocabularies and service metadata. If the annotation structure or any of its elements does not match the definition in the OData vocabulary, the respective part is highlighted and accompanied with a warning or error message. The same is true for the values you use in annotation properties, e.g. if you reference a path to a non-existing entity element or not yet defined annotation.  

Validating%20OData%20annotations%20in%20.cds%20files

Validating OData annotations in .cds files

 

 

Internationalization (i18n) Support 

 

Additional diagnostics are triggered when you define the labels for language-dependent texts. If it is a hard-coded string value, it gets highlighted with a warning. You can then use a recommended Quick Fix action to replace the hard-coded text with a reference to the auto-generated text key/value pair in the i18n file. Yes, all this in just one click! 

Quick%20fixes%20for%20language%20dependent%20texts

Quick fixes for language dependent texts

 

 

Viewing /Modifying Referenced Annotations 

 

With the built in Go to Definition and Pick Definition support, you can view the source of the referenced annotations and, if desired, update its definition. 

Viewing%20referenced%20annotations

Viewing referenced annotations

If you are as excited to try the OData annotation support as our beta customers and partners are, you can download the SAP CDS language support plugin version 3.0 from the Visual Studio Code marketplace. It will then automatically get the CDS OData Language Server module for annotations from npmjs.com.   

If you use SAP Business Application Studio, you can find it in the SAP Cloud Business Application dev space since November 08, 2020. Nothing to download or configure; everything is pre-installed. 

 

More information on OData annotation support in CAP CDS

 

Assigned Tags

      21 Comments
      You must be Logged on to comment or reply to a post.
      Author's profile photo Mariana Naboka
      Mariana Naboka
      Blog Post Author

      Please note that updating SAP Business Application Studio with OData annotation support is planned for 08.11.2020.

      Edit: updated the planned date, sorry for inconvenience

      Author's profile photo Mariana Naboka
      Mariana Naboka
      Blog Post Author

      OData annotation support will be available in the SAP Cloud Business Application dev spaces of SAP Business Application Studio on November 8, 2020

      Edit: updated the planned date, sorry for the inconvenience

      Author's profile photo David LAPOINTE
      David LAPOINTE

      Hi Mariana,

      Is the support available on the SAP Business Application Studio on the trial landscape?

      Ctrl+Space does not seems to trigger the code completion in .cds files.

      I'm looking forward to use it.

      Thanks and great work!!!

      David

      Author's profile photo Mariana Naboka
      Mariana Naboka
      Blog Post Author

      Hi David LAPOINTE 

      Are you on Mac OS?

      Author's profile photo David LAPOINTE
      David LAPOINTE

      No. Windows.

      Author's profile photo Mariana Naboka
      Mariana Naboka
      Blog Post Author

      Thanks for the info.

      Could you please check the version of vscode-cds installed in your dev space?

      View->Plugins, then use the browser search for cds and manually scroll down the list. The min. version containing this feature is 3.0.0

       

       

      Author's profile photo David LAPOINTE
      David LAPOINTE

      Thanks for the quick reply.

      It looks like it's version 2.1.4

       

      I'm guessing that it can be upgraded but sorry, I'm fairly new to npm. Can I do it manually or it has to be done on the platform?

      Thanks again,

      David

      Author's profile photo Mariana Naboka
      Mariana Naboka
      Blog Post Author

      David LAPOINTE

      Thanks for checking, I’m afraid there is nothing you can do to update it right now in App Studio.

      I already informed the colleagues responsible for App Studio updates, need to check whether the trial has a different update schedule.

      I will get back to you on this soon.

      In the time being you can try this feature in Visual Studio Code with SAP Cloud Platform core data services plug-in for Visual Studio Code V 3.0 is available there already

      Author's profile photo David LAPOINTE
      David LAPOINTE

      Great. No problem if it's not present right now. Will check later when it's updated as this look like a great new feature.

      Thank you very much for you time. Business Application Studio looks like a great tool.

      Author's profile photo Mariana Naboka
      Mariana Naboka
      Blog Post Author

      David LAPOINTE

      I've checked with the colleagues -  the update is scheduled for November 8th, 2020 sorry for inconvenience. I will update my comment with this updated info

      Thanks for your understanding,

      Author's profile photo Mariana Naboka
      Mariana Naboka
      Blog Post Author

      Hi David LAPOINTE

      The LSP support for OData annotations is now finally available on SAP Business Application Studio (also on Trial). So you can try it out in your SAP Cloud Business Application dev space.

      Looking forward to your feedback.

      Mariana

      Author's profile photo David LAPOINTE
      David LAPOINTE

      Hi Mariana,

      I confirm that everything works now. What a great new feature. Keep on the good work.

      David

      Author's profile photo Volker Buzek
      Volker Buzek

      yes yeS yES YES ?

      finally, CDS OData annotations via LSP. aiding us devs in CAP apps, reducing the amount of trial'n'error of "where in the code to use what annotation“

      i wish you could see the virtual tear of joy rolling down my cheeks ?

      now still keeping on hoping for that annotations playground similar to UI5 cards ?

       

      Author's profile photo Sumit Kumar Kundu
      Sumit Kumar Kundu

      This will be real help. Looking forward to use it in BAS.

      Author's profile photo Mariana Naboka
      Mariana Naboka
      Blog Post Author

      Hi Sumit Kumar Kundu

      The LSP support for OData annotations is now finally available at SAP Business Application Studio. So you can try it out in your SAP Cloud Business Application dev space.

      Looking forward to your feedback.

      Mariana

      Author's profile photo Sumit Kumar Kundu
      Sumit Kumar Kundu

      Thanks for the update!

      Best regards,

      Sumit

      Author's profile photo Sumit Kumar Kundu
      Sumit Kumar Kundu

      Code completion and inline documentation (hovering on the annotation) are working like a charm.. saving me from switching between documentation and editor 🙂

      Author's profile photo Mariana Naboka
      Mariana Naboka
      Blog Post Author

      Thanks for your feedback!

      I'm glad you like it. Please let me know if you have the improvement proposals

      Author's profile photo Mariana Naboka
      Mariana Naboka
      Blog Post Author

      Please note that   SAP Cloud Platform core data services plug-in for Visual Studio Code is now renamed to SAP CDS Language Support but it still provides the annotation LSP features described in this post

      Author's profile photo Ahmed Ali Khan
      Ahmed Ali Khan

      how to add annotations for value help, I didn't find any example till now, Can you suggest, please.

      Author's profile photo Mariana Naboka
      Mariana Naboka
      Blog Post Author

      Hello Ahmed Ali Khan

      if you need it for the application based on the Fiori elements List Report/Object Page (OData v 4), the easiest way would be to use the Application Modeler extension of SAP Fiori Tools. It is available for both SAP Business Application Studio and Visual studio code.

      Just open a Page Map for your project and choose to edit the page you want to add it to. Then click on the node representing the field you want to update with the value help.

      As an example, I here chose the List Report page, expanded the Filter Fields and chose Agency ID.

      In the Properties Pane. find the Display Type property and choose the Value Help option. In the pop-up, choose the Value Source Entity (entity containing acceptable values for the field, in my case TravelAgency) and Value Source Property (an element of that entity to be used for input, usually a code or id,  in my case Agency ID). This would be a minimum required configuration.

      Additionally, you can choose the descriptive text and how this text should be arranged with the code.

      Finally, you decide if you want to display it as a drop-down or a Value Help dialog.

      When you click Apply, annotations for the value help will be auto-generated. You can always see the generated code by clicking on the Go to code button next to the Value help in the properties pane (it appears on hover.

      Hope you find it helpful.

      If you want to define it manually you can use my code code snippet below and adjust it based on your service and needs. Using annotation LSP (Ctrl/CMD+Space) will help you to choose the values based on your service

      Please let me know if you need further help.

      Best Regards,

      Mariana

      annotate service.Travel with {
          to_Agency @(Common.ValueList : {
                  $Type : 'Common.ValueListType',
                  CollectionPath : 'TravelAgency',
                  Parameters : [
                      {
                          $Type : 'Common.ValueListParameterInOut',
                          LocalDataProperty : to_Agency_AgencyID,
                          ValueListProperty : 'AgencyID',
                      },
                  ],
              },
              Common.ValueListWithFixedValues : true
      )};
      annotate service.TravelAgency with {
          AgencyID @Common.Text : {
              $value : Name,
              ![@UI.TextArrangement] : #TextOnly,
          }
      };