Complex OData Annotation Editing using CDS Graphical Modeler

[Xiao-fei_Song]

In this blog post, we will demonstrate how to annotate CDS models with OData annotations using the CDS Graphical Modeler.

Complex OData Annotation Editing using CDS Graphical Modeler

In this blog post, we will show you how to create complex OData annotations for CDS projections in a separate app/annotations.cds file using the CDS Graphical Modeler so that as a user you don't need to remember the complex details of the OData annotation terms.

Let's say we have an ESPM model and we have a service model defined in a service CDS file that defined all the projections:

and we can open the ESPM service model using the CDS modeler:

and we want to annotate the projections and manage the annotations in a separate CDS file, for example, app/annotations.cds.

First create app/annotations.cds and open the file using the CDS modeler, and you will see an empty CDS model because the CDS file doesn't contain any CDS objects:

Now let's import the service model to the annotations.cds file. Click "Import" -> "External File" from the toolbar:

In the file selection dialog, select srv/cat-service.cds which is your service CDS file:

After the import is complete, the modeler will show the details of the imported service:

Let's say we want to annotate the service entity "Customers" in the service, we click the entity "Customers" in the canvas and select "Pin to the Main Namespace" context menu. By doing so, CDS modeler will place the imported entity "Customers" to the main namespace so that we can directly operate on it:

After the "pin" is done, you will be able to see the entity "Customers" from the CatalogService directly in the main canvas in annotations.cds, just like any other regular entities:

Now since we want to annotate this entity, we click "Manage Annotation" context menu as shown in the above screenshot and the annotation dialog shows up:

And you can see both entity/projection as well as its properties are shown in the annotation editor, and you would be able to annotate both the entity and the properties directly from the app/annotations.cds file.

Now let's show how to create complex OData annotations for this projection. First click "+" button and show all the annotation terms in the list for you to choose:

Let's try to add term @ApplySupported from the Aggregation vocabulary defined in https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Aggregation.V1.html:

and try to provide the values for @Aggregation.ApplySupported term:

Please note that the annotation editor will take care of all the OData annotation schema itself and facilitate the user as much as possible, and the use just need to pick up the value from the list and doesn't need to remember the details of the term definition.

Click "Update" button to close the dialog, and we can now check the app/annotations.cds:

You will see that this complex annotation "@Aggregation.ApplySupported" has been created successfully in the CDS file.

Now let's reopen the annotation editor and choose "@Capabilities.ChangeTracking" for this entity:

Now provide values for this term:

until we get below:

and the app/annotations.cds:

You can see we can generate very complex OData annotations very easily in the annotations.cds file.

In addition to annotating the entity, we can also annotate its properties using either OData annotations or CAP annotations:

and app/annotations.cds has:

Conclusion

In this blog post, we demonstrated how to create complex OData annotations for an imported projection in a separate annotations.cds file.

References

https://cap.cloud.sap/docs/advanced/odata#annotations