From 0cb7349e6262b2c9f3e22e753c49d096c3f0a8cf Mon Sep 17 00:00:00 2001
From: Daniel <daniel.hutzel@sap.com>
Date: Tue, 15 Jun 2021 12:57:42 +0200
Subject: [PATCH] Cosmetics -> for docs

---
 suppliers/srv/mashup.cds | 72 +++++++++++++++++++++++++---------------
 1 file changed, 46 insertions(+), 26 deletions(-)

diff --git a/suppliers/srv/mashup.cds b/suppliers/srv/mashup.cds
index 5ca632ce..c1aa3c0a 100644
--- a/suppliers/srv/mashup.cds
+++ b/suppliers/srv/mashup.cds
@@ -1,23 +1,35 @@
-/*
-  Optionally add projections to external entities, to capture what
-  you actually want to use from there.
- */
-
-using { sap.capire.bookshop as bookshop } from '@capire/bookshop';
 using { API_BUSINESS_PARTNER as S4 } from './external/API_BUSINESS_PARTNER.csn';
+using { CatalogService, sap.capire.bookshop.Books } from '@capire/bookshop';
+namespace sap.capire.bookshop;
 
-@cds.autoexpose // or expose explicitly in Catalog and AdminService
-@cds.persistence: {table,skip:false} // add persistency
-@readonly
-entity sap.capire.bookshop.Suppliers as projection on S4.A_BusinessPartner {
+
+/**
+  Add projections to external entities to capture the subset of fields we're
+  actually interested in. This fosters both: (a) minimized network traffic as
+  well as (b) options to dynamically add extension fields by SaaS tenants.
+ */
+entity Suppliers as projection on S4.A_BusinessPartner {
     key BusinessPartner as ID,
-    BusinessPartnerFullName as name
+    BusinessPartnerFullName as name,
+    // to_BusinessPartnerAddress[1: ValidityStartDate <= $now and $now < ValidityEndDate].CityName,
+    // to_BusinessPartnerAddress[1: ValidityStartDate <= $now and $now < ValidityEndDate].Country,
 }
 
+
+/**
+  We can mashup entities from external services, or projections thereof, with
+  our project's own entities, e.g. by adding relationships as below.
+ */
+extend Books with {
+  supplier : Association to Suppliers;
+}
+
+
 /*
-  You can also expose external entities through your own services
-  For this to work, you need to delegate the respective calls
-  addressed to your services into calls to the external service.
+  Optionally expose external entities through own services, e.g. for Value Helps,
+  or to display details fetched on demand.
+  For this to work, we need to delegate the respective calls addressed to our
+  services into calls to the external service.
  */
 extend service AdminService with {
   entity Suppliers as projection on bookshop.Suppliers;
@@ -25,27 +37,35 @@ extend service AdminService with {
 
 
 /*
-  You can mashup entities from external services, or projections
-  thereof, with your project's own entities
+  Optionally add local persistency to replicate data for fast access,
+  e.g. to display lists containing remote data.
  */
-using { sap.capire.bookshop.Books, CatalogService } from '@capire/bookshop';
-extend Books with {
-  supplier : Association to bookshop.Suppliers;
-}
+annotate Suppliers with @cds.persistence: {table,skip:false};
+
 
 /**
-  Having locally cached replicas also allows us to display supplier
-  data in lists of books, which otherwise would generate unwanted
-  traffic on S4 backends.
+  Having locally cached replicas also allows to display supplier data in lists
+  of books, which otherwise would generate unwanted traffic on S4 backends.
  */
 extend projection CatalogService.ListOfBooks with {
   supplier.name as supplier
 }
 
-// Extend S4 service with an event (events are not included in EDMX files)
+
+/**
+  Optionally declare events emitted from the source, but not included in
+  imported APIs (e.g. as in case of EDMXes from API Hub).
+
+  This allows CAP's advanced support for events and messaging to kick in,
+  e.g. to automatically emit to and subscribe to events from message brokers
+  behind the scenes.
+
+  Note: as sync and async APIs from S/4 sources are not correlated, we have
+  to specify the event type names, e.g. as be found at:
+  https://api.sap.com/event/SAPS4HANACloudBusinessEvents_BusinessPartner/resource
+ */
 extend service S4 {
-  @type: 'sap.s4.beh.businesspartner.v1.BusinessPartner.Changed.v1'
-  event BusinessPartner.Changed {
+  event BusinessPartner.Changed @(type: 'sap.s4.beh.businesspartner.v1.BusinessPartner.Changed.v1') {
     BusinessPartner: S4.A_BusinessPartner:BusinessPartner;
   }
 }