Configuring External Navigation

Objective

After completing this lesson, you will be able to Configure the navigation to another application.

Configuration of External Navigation

To configure navigation between two apps, you need to set up navigation targets and configure the navigation in the source app (outbound navigation).

There are several options how you can configure the navigation from a source app.

  1. As a button in the table tool bar. To do this, add an @UI.DataFieldForIntentBasedNavigation annotation containing a combination of a semantic object and action.
  2. You can replace the standard internal navigation to the object or subobject page in manifest.json. For more information, see Changing Navigation to Object Page.
  3. You can configure links both in forms and tables (in the list report and on the object page). To do this, you can use the @Common.SemanticObject annotation.

    For more information, see Navigation from an App (Outbound Navigation).

  4. In SAP Fiori elements for OData V4 apps, you can configure external navigation from the header facet title of an object page. For more information, see Navigation from Header Facet Title.

Transition of the Navigation Context to the Target App

The navigation context of the source app is passed to the target app.

For example, if a user has selected some values in the filter bar and then navigates to the target app, the values in the filter bar will be passed to the target app and they will be displayed in its filter bar (if it exists in the target app). If the navigation context matches several items of the target app, the list report is displayed. If the unique object of the target app can be identified (that is, all the values of key fields are provided in the navigation context), the object or subobject page of the target app is displayed.

SAP Fiori launchpad can also pass other values to the target app, such as FLP target mapping default values. For more information, see Navigation to an App (Inbound Navigation).

Navigate to the Display Customers App from the Manage Travels App by Pressing the Toolbar Button

You want to provide the ability to navigate from your Manage Travels app to the detailed customer page, which is another app called Display Customers.

Task Flow

You will first open the apps in the local sandbox environment. Then, you will add the button and check the results.

Prerequisites

You have completed the exercise Add a Custom Micro Chart to the Object Page Header of the Display Customers App in the unit Discovering the Flexible Programming Model of SAP Fiori Elements for OData V4 (lesson: Adding a Custom Micro Chart). Alternatively, you can check out its solution branch: solution/add-custom-micro-chart-to-object-page-header.

Watch the Simulation and Perform the Steps

This exercise contains a simulation displaying all the steps. You can follow the simulation with your own trial account.

ExerciseStart Exercise

Steps

  1. Open the sandbox environment.

    1. Execute cds watch and navigate to the Welcome page of the @sap/cds server. In the production environment, the app should run within the SAP Fiori launchpad. In this exercise, we will use the sandbox environment to simulate it.

    2. Add /sandbox/index.html to the URL of the current page to open the sandbox environment.

    3. You can see the simulated SAP Fiori launchpad with two tiles representing the apps.

    4. Select the Travels tile. You have opened the Manage Travels app in the sandbox environment.

  2. Add a navigation button to the Manage Travels app.

    1. Open layouts.cds in SAP Business Application Studio and add the following record to the @UI.LineItem annotation for the Travel entity:

      Code Snippet
      Copy code
      Switch to dark mode
      1234567891011121314
               {
            $Type              : 'UI.DataFieldForIntentBasedNavigation',
            SemanticObject     : 'Customer',
            Action             : 'display',
            Label              : '{i18n>DisplayCustomers}',
            RequiresContext    : false,
            Mapping : [
                {
                    $Type : 'Common.SemanticObjectMappingType',
                    LocalProperty : to_Customer_CustomerID,
                    SemanticObjectProperty : 'CustomerID',
                }
            ]
        }

      You have added an annotation of type UI.DataFieldForIntentBasedNavigation. You have declared the semantic object 'Customer' and the action 'display'. The combination of the semantic object and action is the intent which will be the target of this navigation.

    2. Open the manifest.json file of the Display Customers app. You can see that the semantic object 'Customer' and the action 'display' are defined for the inbound navigation of the Display Customers app.

    3. Open the i18n.properties file and add the new UI text for the DisplayCustomers button.

      Code Snippet
      Copy code
      Switch to dark mode
      1
      DisplayCustomers=Display Customers

    4. Note that the UI.DataFieldForIntentBasedNavigation record contains a mapping property. It is used to map the key property CustomerID of the target entity (Passenger) to the foreign key property to_Customer_CustomerID of the source entity (Travel).

  3. Check the results.

    1. Open the Manage Travels app. You can see the Display Customers button has been added to the tool bar on top of the Travels table.

    2. Select the Display Customers button. You have navigated to the list report of the Display Customers app.

    3. Check the customer list and navigate back.

    4. Now select a travel and then select Display Customers. You have navigated directly to the object page for the selected customer.

Result

In this lesson you have learned how to configure external navigation via a list report tool bar button.

Note

Note

  • You can also skip the Mapping property of the @UI.DataFieldForIntentBasedNavigation annotation.
  • You can find the solution branch without the Mapping property on: GitHub.
  • You can find the link with the comparison of the solution branch without the Mapping property and the solution branch containing the Mapping property on GitHub.

Next Steps

For more information, see:

Associations in CAP

In this section you will learn the difference between managed and unmanaged associations in CAP CDS. This information will help you better understand the annotation syntax in the exercise which follows.

In the database model, associations need to be mapped to foreign-key relationships. CAP CDS supports both unmanaged and managed associations.

Unmanaged associations have to use the existing properties of the source and target entity. In this case, CAP does not generate any properties, and it's not possible to use other associations. The ON clause may contain any kind of join conditions referring to available foreign key properties. The following example demonstrates how you can associate the entity Customer with the key property CustomerID to the entity Booking with the foreign key property to_Customer_CustomerID:

Code Snippet
Copy code
Switch to dark mode
1234
entity Booking { ...
  to_Customer_CustomerID : String(6);
  to_Customer        : Association to Passenger on to_Customer.CustomerID = to_Customer_CustomerID;
}

For managed associations, a foreign key constraint is automatically generated. That constraint ties the foreign key properties of the source entity (automatically added for a managed association) to the respective primary key properties of the target entity (already given):

Code Snippet
Copy code
Switch to dark mode
123
entity Booking { ...
  to_Customer: Association to Passenger;
}

When you compare managed association to unmanaged, you can find two convenient shortcuts:

  1. The Booking entity no longer has the foreign key property that was named to_Customer_CustomerID
  2. The association to_Customer no longer has an ON clause

When CAP generates the OData metadata document at runtime, you'll see that the API still contains both a referential constraint representing the ON clause and the foreign key property to_Customer_CustomerID:

Code Snippet
Copy code
Switch to dark mode
1234567891011
<EntityType Name="Booking">
    <Key>
        <PropertyRef Name="BookingUUID"/>
        <PropertyRef Name="IsActiveEntity"/>
    </Key>
    ...
    <NavigationProperty Name="to_Customer" Type="TravelService.Passenger">
        <ReferentialConstraint Property="to_Customer_CustomerID" ReferencedProperty="CustomerID"/>
    </NavigationProperty>
    <Property Name="to_Customer_CustomerID" Type="Edm.String" MaxLength="6"/>
</EntityType>

Keep in mind the difference between the managed and unmanaged associations and what is generated at runtime. In particular, you'll find that a few annotations which you would expect at foreign key property level, need to be maintained at association level. For managed associations foreign key properties are only available at runtime. The example below shows annotating the to_Customer_CustomerID field of the entity Booking with the text LastName of the associated customer when using a managed association:

Code Snippet
Copy code
Switch to dark mode
123
annotate Booking with { ...
  to_Customer @Common.Text: to_Customer.LastName;
}

When using an unmanaged association, the foreign key property is already available at the source entity at the design time:

Code Snippet
Copy code
Switch to dark mode
123
annotate Booking with { ...
  to_Customer_CustomerID @Common.Text: to_Customer.LastName;
}

Next Steps

For more information, see:

Navigate to the Display Customers App from the Manage Travels App via a Link

You may want to display customer names in the list report table as links. The links should trigger the external navigation to the corresponding object page of the customer app displaying the customer's details.

Task Flow

You will first open the apps in the local sandbox environment. Then, you will add the links and check the results.

Prerequisites

You have completed the exercise Navigate to the Display Customers App from the Manage Travels App by Pressing the Toolbar Button in the unit Illustrating the Navigation Concept in SAP Fiori Elements for OData V4 (lesson: Configuring External Navigation). Alternatively, you can check out its solution branch: solution/add-toolbar-button-to-navigate-to-customer-app.

Watch the Simulation and Perform the Steps

This exercise contains a simulation displaying all the steps. You can follow the simulation with your own trial account.

ExerciseStart Exercise

Steps

  1. Open the app.

    1. Add /sandbox/index.html to the end of the URL of the sap/cds server welcome page. This opens local sandbox environment that simulates SAP Fiori launchpad for testing the external navigation.

    2. Select the Travels tile to open the Manage Travels app.

  2. Add the links.

    1. You will add links to the customer names. These links will trigger navigation to the Display Customers app, showing the corresponding object page.

    2. Open layouts.cds in the SAP Business Application Studio.

    3. Add the following code snippet:

      Code Snippet
      Copy code
      Switch to dark mode
      1234567891011
      annotate TravelService.Travel with {
    @(Common: {
        SemanticObject: 'Customer',
        SemanticObjectMapping: [
            {
                LocalProperty : to_Customer_CustomerID,
                SemanticObjectProperty: 'CustomerID'
            }
        ]})
        to_Customer
    };

      You have added the @Common.Semantic Object and @Common.SemanticObjectMapping annotations to the association to_Customer. Note that this is a managed association that represents the local foreign key property to_Customer_CustomerID.

  3. Check the results.

    1. Open manifest.json. You can see the Customer semantic object in the crossNavigation/inbounds section. It is used by the local sandbox environment.

    2. Switch to the application window. You can see the list report of the Manage Travels app. It is running in the local sandbox environment simulating SAP Fiori launchpad. You can see that the customers' names are displayed as links now.

Result

In this lesson you learned how to easily configure table cells to be displayed as links which trigger external navigation to another app.

Note

Note

  • You can also skip the @Common.SemanticObjectMapping annotation.
  • You can find the solution branch without the @Common.SemanticObjectMapping annotation on: GitHub.
  • You can find the link with the comparison of the solution branch without the @Common.SemanticObjectMapping annotation and the solution branch containing the @Common.SemanticObjectMapping annotation on GitHub.

Next Steps

For more information, see Navigation from an App (Outbound Navigation).

Log in to track your progress & complete quizzes