Creating Metadata Extensions

Objective

After completing this lesson, you will be able to extend views using CDS metadata extensions

Metadata Extensions

In the last section, you saw how to add completely new elements to the element list of a CDS view using CDS view extensions. However, when you want to add annotations to existing elements or overwrite annotation values, creating a CDS view extension is not the right approach. To add and overwrite annotations, you have to create a CDS metadata extension. The definition of a CDS metadata extension begins with keyword ANNOTATE VIEW followed by the name of the target entity.

Let us have a look at an example: CDS view entity /DMO/C_AgencyTP on the left, defines, among others, an element AgencyID.

The CDS metadata extension on the right, repeats this element name AgencyID in its element list, that is, inside the pair of curly brackets, and adds annotation @EnduserText.label: 'Customer Text'in front of it.

The following restrictions apply for metadata extensions:

  • It is not possible to define new elements in metadata extensions. You can only address existing elements of the target entity and add annotations to them.
  • Not all annotations are supported in metadata extensions. the list of allowed annotations contains mostly framework-specific annotations related to UI development, analytics, and search functionality.

As a prerequisite for creating a CDS metadata extension the owner of target entity has explicitly allow this by adding @Metadata.allowExtensions: true to the definition.

Inside a metadata extension, it is mandatory to specify a value for annotation @Metadata.layer. This annotation makes it possible to create several metadata extensions for the same CDS entity. It is used to control the priority, in case the annotation values of the different metadata extensions contradict each other. Let us have a closer look.

When there are more than one metadata extensions for the same CDS entity, the syntax check makes sure they contain different values for annotation @Metadata.layer. In other words, because five different values are supported at the moment, you can define a maximum of five metadata extensions for the same base entity. The priority is as follows:

  • #CUSTOMER overwrites all other layers.
  • #PARTNER overwrites all other layers except for #CUSTOMER.
  • #INDUSTRY overwrites #LOCALIZATION and #CORE.
  • #LOCALIZATION overwrites only #CORE and
  • #CORE has the lowest priority. The metadata on layer #CORE can be overwritten in any other metadata extension.

Note

In the ABAP RESTful application programming model, it is a best practice to place the UI-related metadata in a metadata extension of layer #CORE. This opens up an elegant way for industry solutions, partners, and customers to adjust (overwrite) the UI configuration to their needs.

Metadata Extension Creation

CDS metadata extensions are development objects of their own. They are not defined in CDS data definitions.

To define a CDS metadata extension, proceed as follows:

  1. In the project explorer, locate the data definition of the CDS entity that you want to extend.
  2. Right-click the data definition and choose New Metadata Extension.
  3. Adjust the package if necessary, and enter a name and a description for the new object. Then choose Next.
  4. Enter a transport request and choose Next.
  5. From the list of templates, choose Annotate View and chooseFinish.

    Note

    There is also a template Annotate Entity. This template uses keyword ANNOTATE ENTITY rather than ANNOTATE VIEW. ANNOTATE ENTITY can be used for any kind of CDS entity, but the set of available annotations is smaller. We recommend that you use ANNOTATE VIEW when you create your metadata extension for a CDS view and not for one of the other CDS objects.

Create CDS Metadata Extensions

You want to extend the metadata of one of your view entities. In a first step, you outsource existing annotations into a CDS metadata extension. You then create a second metadata extension to add more annotations and overwrite existing ones.

Template:

  • n.a.

Solution:

  • /LRN/C_EMPLOYEE_MDX (Data Definition)
  • /LRN/C_EMPLOYEE_MDX (Metadata Extension)
  • /LRN/C_EMPLOYEE_MDX2 (Metadata Extension)

Prerequisites

For this exercise, you need the view entity with parameters for employee data (suggested name was: Z##_C_EmployeeQueryP) . If you have not finished the related exercises, create a copy of data definition /LRN/C_EMPLOYEE_EXT.

Task 1: Extract a Metadata Extension

Adjust the definition of your view entity with parameters for employee data (suggested name was: Z##_C_EmployeeQueryP) and extract all annotations for which this is allowed into a new metadata extension of the lowest layer. Use the same name for the data definition and the metadata extension. After the extraction, use a quick fix to allow the extension of the view entity.

Steps

  1. Open the definition of your view entity with parameters for employee data and make sure it is active.

    1. Press Ctrl + Shift + A.

    2. In the search field, enter Z##_C_, where ## is your group number.

    3. From the list of matching items, select entry Z##_C_EmployeeQueryP and choose OK.

    4. Press Ctrl + F3 to activate the development object.

  2. Using a refactoring tool, extract all available annotations into a new metadata extension.

    1. From the Eclipse menu, choose Source CodeExtract Metadata Extension.

    2. In the Extended Entity field, enter Z##_C, press Ctrl + Space and choose the name of the CDS view entity that you want to extend (Z##_C_EmployeeQueryP).

    3. Copy that name from the Extended Entity field to the Name field.

    4. Enter a description (for example Employee Query (Metadata)) and choose Next.

    5. Confirm the transport request and choose Next.

    6. Choose Expand All on the right-hand side and analyze the annotations that can be extracted.

    7. Choose Select All on the right-hand side and Finish on the bottom.

  3. Use code-completion to set the layer of your metadata extension to the value with the lowest priority.

    1. In the @Metadata.layer annotation, remove placeholder layer.

    2. Press Ctrl + Space to invoke code-completion.

    3. From the suggestion list, choose value #CORE as this layer has the lowest priority.

  4. Use a quick fix to adjust the annotated view entity so that it allows metadata extensions.

    1. Place the cursor in the code row starting with annotate view and press Ctrl + 1 to invoke the quickfix. Alternatively, you can choose the error icon with light bulb next to this code row.

    2. From the list of available quickfixes, choose Add annotation 'Metadata.allowExtensions' to base view.

  5. Activate the metadata extension and the annotated view entity.

    1. Press Ctrl + Shift + F3 to activate all inactive development objects.

    2. Choose Select All and OK.

    3. Choose Select All and Activate.

  6. Open the annotated view entity in the Active Annotations tool and verify that some of the annotations now come from the metadata extension.

    1. Right-click anywhere in the source code and choose Open WithActive Annotations.

      Result

      For some of the annotations, column Origin Data Source should contain your metadata extension.

Task 2: Create a Metadata Extension

Based on an appropriate template, create a second metadata extension for the same view entity as before (suggested name: Z##_C_EMPLOYEE_QUERYP2) . Choose the metadata layer with the highest priority, overwrite the label for the P_DATE parameter and add a label for the AssistantName view element.

Steps

  1. In the Project Explorer, locate the definition of the view entity that you extended in the previous task.

    1. For example, expand the Core Data ServicesData Definitions subnode of your package ZS4D430_##.

  2. For this view entity, create a new CDS metadata extension based on the Annotate View with Parameters template.

    1. Right-click the data definition name to open the context menu and choose New Metadata Extension.

    2. Copy the value from the Extended Entity field to the Name field and add character 2 to distinguish it from the already existing metadata extension.

    3. Enter a description (for example Employee Query (Final Metadata)) and choose Next.

    4. Confirm the transport request and choose Next.

    5. From the list of available templates select Annotate View with Parameters and choose Finish.

  3. Use code-completion to set the layer of your metadata extension to the value with the highest priority.

    1. In the @Metadata.layer annotation, remove placeholder layer.

    2. Press Ctrl + Space to invoke code-completion.

    3. From the suggestion list, choose value #CUSTOMER as this layer has the highest priority.

  4. Replace placeholder parameter_name with p_date and add a new label for this parameter, for example, Currency Conversion Date.

    1. Adjust the code as follows:

      Code Snippet
      1234567891011
      @Metadata.layer: #CUSTOMER annotate view Z##_C_EmployeeQueryP with parameters @EndUserText.label: 'Currency Conversion Date' p_date { element_name; }
  5. Replace the placeholder element_name with AssistantName and add a label for this view element, for example, Department Assistant.

    1. Adjust the code as follows:

      Code Snippet
      1234567891011
      @Metadata.layer: #CUSTOMER annotate view Z##_C_EmployeeQueryP with parameters @EndUserText.label: 'Currency Conversion Date' p_date { @EndUserText.label: 'Department Assistant' AssistantName; }
  6. Activate the new metadata extension.

    1. Press Ctrl + F3 to activate the development object.

  7. Open the annotated view entity in the Active Annotations tool and verify that the label for the p_date parameter comes from the new metadata extension.

    1. Right-click anywhere in the source code and choose Open WithActive Annotations.

Log in to track your progress & complete quizzes