10.3    Extending Fact Sheet Apps

You can extend a fact sheet when a standard fact sheet app delivered by SAP doesn’t meet your requirements. The following are scenarios in which you can extend a specific layer of a system landscape for fact sheet apps:

• You can extend a search model when you want to add fields to the fact sheet app that aren’t available in the search model.
• You can extend the UI layer if the back-end logic and the content required for the app extension are present in the SAP Gateway layer, but it’s not exposed to the UI layer.

We’ll use an example based on the Sales Order fact sheet app in this section. We’ll walk you through extending both a search model and the UI layer by adding the new Risk Category field to the Sales Order app.

10.3.1    Extend the Search Model

The first step in the extension process is to extend the search model. From the SAP Fiori apps reference library, search for the Sales Order fact sheet app, and navigate to the Configuration section. Go to the Search Connector section to see a list of connectors for the Sales Order fact sheet app (see Figure 10.33). In Chapter 5, Section 5.4, we discussed how to create a connector on a search model and how to enable an app using these connectors. In this section, we’ll show you how to extend a search model by adding a field.

Figure 10.33    Search Models

Search Models and Connectors

To get the complete list of search models and connectors for all SAP Fiori fact sheet apps, refer to SAP Note 1861013.

To extend a model, we use the search and analytics modeler, which is a component of SAP Enterprise Search. This tool allows developers to create or change models for search object connectors. You need to have extensive knowledge of the SAP Business Suite back-end technology to create or change any search model.

SAP Enterprise Search and the search and analytics modeler tool are big topics. In this chapter, we’ll cover a very basic example, explaining how to enhance a search model by added a field to it. The sections that follow walk through the different steps for extending the search model.

Enhance the Model

In this section, we’ll begin by enhancing our data model. As previously mentioned, most of the steps are similar when creating or enhancing a search object connector. In both scenarios, you’ll follow the same sequence of screens:

1. Expand the SD-SLS component, then select SALES_ORDER_H.
2. Click Edit (see Figure 10.34).
   

   Figure 10.34    Editing Data Model

3. Click Yes to confirm the model enhancements, as shown in Figure 10.35.
   

   Figure 10.35    Enhance Model Confirmation Pop-up

4. Next, you’ll be working through the roadmap steps. In the first step (Model Properties), the properties of the search object connector model are defined (i.e., the Model Type and the component properties). Click Next (see Figure 10.36).
   

   Figure 10.36    Model Properties

5. In the second step (Model Nodes), you create or modify nodes and assign node names and node attributes. From the List of Nodes of ’SALES_ORDER_H’ section, select SO_VBAK (see Figure 10.37).
   

   Figure 10.37    Model Nodes: Select Node

6. Scroll down to the Details Attributes section, and select the CTLPC (Risk category) attribute by checking the Select for Node checkbox. Click Next (see Figure 10.38).
   

   Figure 10.38    Selecting New Field

7. In the third step (Node Relations), all the nodes you selected in the previous steps and their relations are listed. Click Next (see Figure 10.39).
   

   Figure 10.39    Node Relations

8. Now, you’ll define the attributes and the search pattern or queries. After the attributes are selected, the system generates a default query with all the selected response attributes. In this step, you need to add “Risk category” as an attribute and define the query. Under the Request Attributes tab, click Add, then select Attributes/Group from Node (see Figure 10.40).
   

   Figure 10.40    Adding Attributes

9. Select CTLPC from the Details Attribute of Node, then click Select. Click Next (see Figure 10.41).
   

   Figure 10.41    Selecting New Field

10. Finally, you’ll define the optional settings for the search object model. In this step, you’ll add CTLPC as a response attribute and define the properties. Under the Request Attributes tab, click Add, then select Attributes/Groups from Node (see Figure 10.42).
    

    Figure 10.42    Adding Attribute

11. Select CTLPC from Details Attributes of Node, then click Select (see Figure 10.43).
    

    Figure 10.43    Selecting New Field

12. Select the CTLPC attribute, and define the response attributes. Check the Details and Fact Sheet checkboxes (see Figure 10.44).
    

    Figure 10.44    Selecting UI Area Assignment

13. Click Save, then click Finish.

You’ve successfully enhanced the search model by adding a new field and setting its properties.

Create the Search Connector

Next, you’ll create the search connector on the new search model.

Important!

You need to follow the same steps as you followed to create a new fact sheet app.

Follow these steps:

1. From the list of available models, navigate to and select the SALES_ORDER_H search object.
2. Select Actions, then click Create Connector (see Figure 10.45).
3. The system creates a job in the background to create search object connectors. You can monitor the job in Transaction SE38, and the job name is ESH_<Client>_C_<Unique Code>.

Figure 10.45    Creating New Connector

Schedule Indexing

Now that you’ve enhanced the model and created the search connector successfully, you must schedule indexing for the sales order search model, which is handled in the connector administration cockpit. The status of the newly created connector will be set to Prepared, so you need to schedule this connector to change its status to Active.

Important!

You need to follow the same steps as you followed to create a new fact sheet app.

Follow these steps:

1. Run Transaction ESH_COCKPIT.
2. Select Sales Order.
3. Click Actions, and select Schedule Indexing (see Figure 10.46).
4. To make the business objects fully searchable, you need to index SAPScript longtexts and select the Start Immediately checkboxes for both ESH_SAPSCRIPT_TEXT and USER_AUTHORITY (see Figure 10.47).
5. Click OK.
   

   Figure 10.46    Schedule Indexing

   

   Figure 10.47    Starting Indexing

6. The system creates a job in the background to index search models. You can monitor the job in Transaction SE38. The job name is ESH_<Client>IX_<System ID + Client>_<Unique Code>.
7. After the index is started, the status of the connectors will change to Indexing; after the job is completed, the status will change to Active (see Figure 10.48).
   

   Figure 10.48    Connector Status

Test Embedded Search

After the status is changed to Active, you can test the embedded search via the Web Dynpro UI. You need to follow the same steps as you followed to create a new SAP Fiori fact sheet app:

1. Launch embedded search by running Transaction ESH_SEARCH from the ABAP system.
2. Enter “Sales Orders” in the Search For field, then click Search (see Figure 10.49).
   

   Figure 10.49    Embedded Search

3. Click Details to view the details of a sales order.

You should now see the Risk category field in the details view, with the data populated (see Figure 10.50).

Figure 10.50    New Field

Test the OData Service

In this step, you need to check whether the OData service of the Sales Order fact sheet app is displaying the new field. You need to follow the same steps as you followed to create a new SAP Fiori fact sheet app:

1. Run Transaction /IWFND/MAINT_SERVICE.
2. Select ZCB_SALES_ORDER_SRV, then click Gateway Client (see Figure 10.51).
   

   Figure 10.51    Activate and Maintain Services

3. In the Request URI field, enter “/sap/opu/odata/sap/CB_SALES_ORDER_SRV/$metadata” (see Figure 10.52).
4. Click Execute.
5. Under Sales Order Entity Type, you should now see the new property, CTLPC.

Figure 10.52    Testing OData Service

You’ve successfully completed the first part of the extension process by extending the sales order search model and adding the Risk category field. Next, we’ll explore the UI layer of the Sales Order fact sheet app.

10.3.2    Extend the UI Layer

The next step in the process is to extend the UI layer. You can extend the UI layer when the back-end logic and content exist in the SAP Gateway layer, but aren’t exposed to the UI layer. In our example, we have the risk category added to the search model and to the OData service; however, it’s not added to the UI layer.

You have two options to extend a UI layer of a fact sheet app:

1. Extend a fact sheet app with SAP Web IDE.
2. Extend a fact sheet app manually.

The next two sections walk through these options.

Extend the UI Layer with SAP Web IDE

The SAP Web IDE fact sheet editor app allows developers to create fact sheets from scratch and extend existing fact sheets (refer to Section 10.1). The beauty of SAP Web IDE is that you can connect to the ABAP system and preview the fact sheet. In this section, you’ll extend the fact sheet app with SAP Web IDE by following detailed steps.

Retrieve the BSP Application and Annotation File

Before we take a deep dive into this process, let’s first get the details of the BSP application and the annotation file details of the Sales Order fact sheet app. Search for “Sales Orders” in the SAP Fiori apps reference library at https://fioriappslibrary.hana.ondemand.com/sap/fix/externalViewer/index.html, then navigate to the Extensibility section (see Figure 10.53).

Figure 10.53    Sales Order Fact Sheet Technical Names

Select a Template

The next step is to extend the UI layer of the app using a standard SAP fact sheet app template. Follow these steps:

1. Log in to SAP Web IDE and click New Project from Template (see Figure 10.54).
   

   Figure 10.54    Creating New Project from Template

2. You’ll see three templates to create or enhance a fact sheet app (see Figure 10.55):
   • Existing Fact Sheet Application
     Use this template when you want to extend an existing fact sheet app. You can either deploy the app as a new application or overwrite the existing application.
   • Modification Free Fact Sheet Application
     Use this template when you want to extend an existing fact sheet app in the modification-free mode. After you change the XSL file and upload it to the back-end server, the fact sheet app will contain the changes from both the annotation file and XSL file you created using this template.
   • New Fact Sheet Application
     Use this template if you want to create a fact sheet app from scratch.
   

   Figure 10.55    Fact Sheet Application Templates

Templates

You can use either the Existing Fact Sheet Application or New Fact Sheet Application template to create a fact sheet app.

In our example, we’ll use the existing Sales Order fact sheet app and enhance it with the new field.

When extending a fact sheet app, you can use either the Existing Fact Sheet Application option or the Modification Free Fact Sheet Application option. Let’s begin by using the Existing Fact Sheet Application template:

1. Select Existing Fact Sheet Application, then click Next (see Figure 10.56).
   

   Figure 10.56    Existing Fact Sheet Application

2. Enter a Project Name, and click Next (see Figure 10.57).
   

   Figure 10.57    Project Details

3. Select your ABAP system (refer to Chapter 8 to add a connection) from the dropdown list, then enter “Sales Orders Fact Sheet” in the Search field to search for the Sales Order fact sheet app.

   Note

   If you don’t see the list of fact sheet apps, you may not have added the WebIDEUsage bsp_execute_abap property in the connection. Refer to Chapter 8 to review how to add properties in the connection.

4. Select Sales Order Fact Sheet and click Next (see Figure 10.58).
   

   Figure 10.58    Selecting Existing Fact Sheet Application

5. Click Finish to confirm.

Now that we’ve looked at how to use existing fact sheet app templates, we’ll move to the second template: Modification Free Fact Sheet Application.

You can use this template when you want to extend an existing fact sheet app without modifying it; that is, you don’t want to change the XML code in the original file, but you still want to add new fields in the fact sheet app. Most of the steps are like those we’ve already discussed in this chapter; you’ll just notice new files created, compared to app creation with the first template.

In this example, you’ll use the same search model you enhanced by adding a new field (Risk Category) and will create a new modification-free fact sheet app. We’ll just add screens that are specific to this template. If you get stuck while working on this extension, refer to the previous section; the process is similar between all the templates, although the initial screens look different. Follow these steps:

1. Log in to SAP Web IDE, and from the menu bar, select File • New • Project from Template (see Figure 10.59).
   

   Figure 10.59    Creating New Project from Template

2. Select Modification Free Fact Sheet Application, then click Next (see Figure 10.60).
3. Enter a name in the Project Name field and click Next.
4. Select your ABAP system from the dropdown list, then search for the Sales Order fact sheet app by entering “Sales Orders Fact Sheet” in the Search field.
5. Select Sales Order Fact Sheet and click Next.
6. Click Finish to confirm.
   

   Figure 10.60    Modification-Free Fact Sheet Application

7. You should now see the annotation file under the new project folder (see Figure 10.61).
   

   Figure 10.61    Editing Annotation File

8. Double-click the BSCBN_SALES_ORDER_SRV_ANNO.anno file to open it in the SAP Web IDE fact sheet editor app.
9. Drag and drop the CTLPC field to the Facet Section/General Information section.
10. Save the project by clicking the Save button. SAP Web IDE automatically generates the files required for the extension process (see Figure 10.62).
    Table 10.1 shows the list of files or folders generated when you use the Modification Free Fact Sheet Application template in SAP Web IDE.
    

    Figure 10.62    New Files and Folders

    File/Folder	Description
    data	This folder contains the original annotation file.
    Original.xsl	This file contains the XSLT template that is generated exactly the like the original ANNO file. This file is used to track the changes that a user makes to the annotation file.
    Work.xsl	This file contains all the changes made by a user in the design view. In our example, we added the Risk Category field, and that change will be captured in this file.
    .project.json	This service file with .project.jso extension contains the service URL details and the main entity sets.
    .anno	This is the original fact sheet annotation file.
    .otr	This service file contains the Online Text Repository (OTR) aliases, with the labels and back-end availability status.
    .xml	This service file contains the ABAP code for the OTR.
    .xsl	This file with .xsl extension is used in the back-end system to apply changes to the matching fact sheet.
    Preview.xml	The result of the XSL file and the original.anno file is saved in this preview.xml file.
    neo-app.json	This service file contains settings to preview the fact sheet in SAP Fiori launchpad.

    Table 10.1    Project Files

11. Test the extended fact sheet by right-clicking the ANNO file and navigating to Run • Run Fact Sheet.
12. Upload the XSL file to the back-end server to deploy the changes to the ABAP system.

The next time the user runs the Sales Order fact sheet app, it will contain both the changes from the annotation file and the XSL file changes you created using this template in SAP Web IDE.

Extension Project Properties

You’ve successfully created a project in SAP Web IDE using an existing template for the Sales Order fact sheet app. Before we show you how to enhance the UI layer, we’ll show you some basic properties and components of an extension project.

You should see the annotation file under the new project folder (see Figure 10.63).

Figure 10.63    Fact Sheet Annotation File

The new project folder contains the following files:

• project.json
  This file contains the OData service URL and the entity set details of the fact sheet.
• ANNO
  This is the annotation file that you’ll be working on to extend the fact sheet.
• neo-app.json
  This file contains settings to preview the fact sheet app.

Template Files/Folders

If you’re using a different template—that is, Modification Free Fact Sheet Application or New Fact Sheet Application (refer to Figure 10.55)—you’ll see a different set of files/folders under the main project folder.

Double-click the BSCBN_SALES_ORDER_SRV_ANNO.anno file to open it in the SAP Web IDE fact sheet editor app. On the next screen, you can switch between Design editor and Source Code editor (see Figure 10.64). Depending on your programing skills, you can decide the type of editor you want to use; for example, a nondeveloper can use the design editor to edit the annotation file.

Figure 10.64    Annotation File Editors

The fact sheet app design editor contains three tabs on the right side of the screen:

• Available Fields
  This tab displays all the fields provided by the OData service, and you can drag and drop these fields into your fact sheet to enhance it (see Figure 10.65).

Figure 10.65    List of Available Fields

• Properties
  Upon clicking any of the fact sheet fields, facets, or key facts in the Design editor, you can view their properties on the right side. Figure 10.66 shows the properties of a fact sheet field.

Figure 10.66    Fact Sheet Properties

The following fields are found under the Properties tab:

• Label
  This is the label of the field displayed in the fact sheet app.
• Field
  This is the back-end field provided by the OData service that you want to display.
• Priority
  This is the importance level of the fields, determining how they display on different devices or at different screen resolutions:
  • High: These fields are shown on the General Information section of the fact sheet overview page on all devices.
  • Medium: These fields are shown on the General Information section of the fact sheet only on larger devices.
  • Low: These fields are shown only on the Details page.
• Navigation Target
  This field defines the target object. When the user clicks on this field, it will navigate the user to the target location specified here.

In the Key Fact Section, select the Net Value key fact to display the following properties (see Figure 10.67):

• Label
  This is the label of the field displayed in the fact sheet app.
• Field
  This is the back-end field provided by the OData service that you want to display.
• Type
  This is the key fact type.
• Number of Fractional Digits
  This is the number of decimals you want to display for this key fact.

Figure 10.67    Key Fact Properties

In Facet Section, select the General Information facets to display the following properties (see Figure 10.68):

• Title
  This is the title of the facet.
• Navigation Path
  This is the navigation path of the facet.
• Entity Type
  This is the main entity type of the OData service.

Figure 10.68    General Information Properties

• Contents
  You can get the structure of the fact sheet from the Contents tab (see Figure 10.69).

Figure 10.69    Contents Tab

In addition, you can design a fact sheet app directly by using the Source Code editor tab (see Figure 10.70).

Figure 10.70    Source Code Editor

Getting back to the extension process, you can extend three sections in the Design view (see Figure 10.71):

• Header Section
  This section contains the Fact Sheet Name and Additional Name.
• Key Facts Section
  This section contains the Key Facts about central objects used in your business operations.
• Facet Section
  This section shows the general information and other facets:
  • General Information
    These pages are the detail pages with the facet information; you can view them from the Contents tab.
  

  Figure 10.71    Annotation Sections

Figure 10.72 shows the same sections in the actual Sales Order fact sheet app.

Figure 10.72    Sections in the Fact Sheet

Add the Risk Category

By now, you should be familiar with the SAP Web IDE fact sheet editor app options. Next, you’ll add the Risk Category field to the Facet Section and then preview it. Follow these steps:

1. Drag and drop the CTLPC field to the Facet Section/General Information section (see Figure 10.73).
   

   Figure 10.73    Adding New Field

2. Save the project by clicking the Save button.
3. Run the fact sheet app by right-clicking the ANNO file and navigating to Run • Run Fact Sheet (see Figure 10.74). Alternatively, you can use select Run • Run Fact Sheet from the menu bar.

You should now see the new fields in the General Information section (see Figure 10.75).

You’ve now enhanced the data model and the UI layer. In the next section, we’ll look at the option for manually extending the UI layer.

Figure 10.74    Running Fact Sheet App

Figure 10.75    Risk Category Field

Extend the UI Layer Manually

In the previous section, we covered how to extend the UI layer using SAP Web IDE. Now, we’ll discuss the manual extension process. You can extend the UI layer manually when you want to add more complex elements (e.g., Google Maps) to your fact sheet that can’t be added via SAP Web IDE.

You have two options to extend the fact sheet manually:

1. Directly edit the SAP-delivered annotation files. In the previous section we copied the XML code generated in SAP Web IDE, in this scenario, we’ll add our own code.
2. Create XSL Transformation (XSLT) documents to work in conjunction with the original SAP-delivered annotation files. The original annotation file remains unchanged, and you can include all the fact sheet changes to the XSLT document and then upload it to the back-end. When the user runs the fact sheet, the XSLT document generates a new temporary annotation file, and the rendered fact sheet is based on the transformed annotation file.

In the next section, we’ll deploy the extended fact sheet app to the ABAP back-end server.

10.3.3    Deploy the Fact Sheet App

To deploy or make changes to the original annotation file in the ABAP system, follow these steps:

1. From SAP Web IDE, double-click _ANNO.XML in the project folder, then copy all the XML code (see Figure 10.76).
   

   Figure 10.76    Copying XML Code

2. Run Transaction SE80 from your ABAP system.
3. Enter the BSP application name “BSCBN_ANF_SDSLS” and press (Enter).
4. Right-click the Sales Order fact sheet annotation file and select Change (see Figure 10.77).
   

   Figure 10.77    Editing Annotation File

5. Paste the code that you copied in Step 1, click Save , then click the Activate icon .

You’ve successfully extended the app by adding a new field and deploying the Sales Order fact sheet app.