SAP Cloud Platform Backend service: Tutorial [4]: CDS : how to define associations (2)

Phew…
The previous tutorial was kind of dry material and exhausting reading….
Agreed, but in this tutorial we’ll skip those lengthy explanations, just show how it needs to be done.
To be done? What needs to be done?
Ah, you’re right, almost forgot the intro…

Intro

This blog is part of a series of tutorials for beginners, to get started with SAP Cloud Platform Backend service
With the Backend service, you can create an API without code, only with a data model, e.g. CDS model
In the previous tutorial we discussed how to define unmanaged one-to-one association
In the present tutorial, we’re going to learn how CDS (Core Data and Services) helps to define managed associations.
CDS helps?
Yes, I really mean it. It helps: it manages.
ehmmm, but mangers are not really known to be…
Sorry, just continue reading

Part I: managed one-to-one association

Please read the previous tutorial in order to see the difference between unmanaged and managed

The Model

For better comparison and easier understanding, I thought of reusing the model of previous tutorial, but modified such that we can leverage the power of CDS’s managed association

service ProductService {

    // Managed 1:1 relation 
    entity CustomerEntity{
        key customerID : Integer;
        companyName : String;
                            // no foreign key here anymore
        linkToContact :  Association to ContactEntity; // no condition anymore
    }

    entity ContactEntity{
        key contactID : Integer;
        contactName : String;
        contactPhone : String;
    }
}

If you compare this model to the previous one, you’ll notice 2 differences:

The 2 differences:

1. In CustomerEntity, we don’t need the foreign key property anymore (it was called contactProperty)
2. The association doesn’t have an “on” condition anymore

Now let’s create an API based on this model (see here for instructions)
Afterwards, check the metadata of the generated OData service:

<EntityType Name="CustomerEntity">
   <Key>
      <PropertyRef Name="customerID" />
   </Key>
   <Property Name="customerID" Type="Edm.Int32" Nullable="false" />
   <Property Name="companyName" Type="Edm.String" />
   <Property Name="linkToContact_contactID" Type="Edm.Int32" />
   <NavigationProperty Name="linkToContact" Type="ProductService.ContactEntity">
      <ReferentialConstraint Property="linkToContact_contactID" ReferencedProperty="contactID" />
   </NavigationProperty>
</EntityType>

Interesting to observe:

1. In the OData EntityType “CustomerEntity” there’s a property which we didn’t define in the CDS-entity
   It is called linkToContact_contactID
   This has been magically added by CDS
2. In the OData NavigationProperty, there’s a ReferentialConstraint which we didn’t define in the CDS association
   It defines a constraint on the key property of the target entity and the magic-property
   This has been magically added by CDS

See below for direct comparison:

Test it

Since we haven’t changed any property names, we can proceed same way like described in the previous tutorial.

The navigation should work in the same way like in the previous tutorial.

https://…/DEFAULT/PRODUCTSERVICE;v=3/CustomerEntity(1)/linkToContact

PART II : Managed one-to-many association

Now we’re going to have a look at a different example :
Managed one-to-many association and the corresponding backlink

The model

Let’s use the same scenario, with a little change
We assume that a customer/company can have multiple contact persons.
And that a contact person is responsible for one company only, as such we can navigate from a contact back to the company

service ProductService {

    // managed association: 1 to many
    entity CustomerEntity{
        key customerID : Integer;
        companyName : String;
        linkToContacts :  Association to many ContactEntity
                         on linkToContacts.linkToCustomer = $self; 
    }

    // managed association: one to one
    entity ContactEntity{
        key contactID : Integer;
        contactName : String;
        linkToCustomer : Association to CustomerEntity;
    }
}

The corresponding metadata of the OData service:

<EntityType Name="CustomerEntity">
   <Key>
      <PropertyRef Name="customerID" />
   </Key>
   <Property Name="customerID" Type="Edm.Int32"/>
   <Property Name="companyName" Type="Edm.String" />
   <NavigationProperty Name="linkToContacts" Type="Collection(ProductService.ContactEntity)" Partner="linkToCustomer" />
</EntityType>
<EntityType Name="ContactEntity">
   <Key>
      <PropertyRef Name="contactID" />
   </Key>
   <Property Name="contactID" Type="Edm.Int32"/>
   <Property Name="contactName" Type="Edm.String" />
   <Property Name="linkToCustomer_customerID" Type="Edm.Int32" />
   <NavigationProperty Name="linkToCustomer" Type="ProductService.CustomerEntity" Partner="linkToContacts">
      <ReferentialConstraint Property="linkToCustomer_customerID" ReferencedProperty="customerID" />
   </NavigationProperty>
</EntityType>

One interesting detail could be the “Partner” attribute in the NavigationProperty tag. It makes clear that we have defined a bi-directional association.

Test

After creating the API, we create some sample data
In order to test the to-many association, we need to create several ContactEntity for one Customer

The result of navigating from a CustomerEntity to the contacts is a collection

https://…/DEFAULT/PRODUCTSERVICE;v=4/CustomerEntity(1)/linkToContacts

Summary

In this tutorial we’ve learned how to define managed associations in CDS
The previous tutorial covered the unmanaged association, along with detailed explanations

Links

Preparation and configuration for using SAP Cloud Platform Backend Service

Tools for modelling (typing) CDS

First tutorial:
https://blogs.sap.com/2019/01/25/sap-cloud-platform-backend-service-tutorial-1-easy-api-creation/comment-page-1/#comment-451005

Previous tutorial:
https://blogs.sap.com/2019/02/20/sap-cloud-platform-backend-service-tutorial-3-cds-how-to-define-associations-1/

Next tutorial:
https://blogs.sap.com/2019/02/28/sap-cloud-platform-backend-service-tutorial-5-cds-using-property-facets/

The tutorial overview page

CDS docu on associations:
https://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/Cloud/en-US/9ead8e4701d04848a6fdc84356723a52.html

OData specification:
NavigationProperty section

Appendix: the data model

service ProductService {

    // managed association: 1 to many
    entity CustomerEntity{
        key customerID : Integer;
        companyName : String;
        linkToContacts :  Association to many ContactEntity
                         on linkToContacts.linkToCustomer = $self; 
    }

    // managed association: one to one
    entity ContactEntity{
        key contactID : Integer;
        contactName : String;
        linkToCustomer : Association to CustomerEntity;
    }
}