Ok so the suspense is over. Having talked about what Fiori Elements are, how to design a list report, and having confirmed that a List Report is what you want, we move on to actually creating our first List Report… which will look just like the one above.
Tip: You can find this and previous blogs on Fiori Elements on the Fiori Elements wiki.
There are a few different ways of creating a List Report. We are going to start with the simplest approach to show how simple it really can be. By looking at the simplest approach we’ll:
- Gain a general understanding of how to work with Fiori Elements
- Understand the pre-requisites
- Delve underneath to see how Fiori Elements impacts the underlying SAPUI5 architecture
The use case we’ll focus on in this blog is:
- We have identified we want a new list report
- We have time to plan the list report
- We have decided to create a new data extract (as a ABAP CDS view) for the list report
- We will expose this ABAP CDS view as an OData Service
- Since the ABAP CDS view will be created specifically for this list report, we have decided to put all the annotations that will drive the Fiori Elements into the ABAP CDS view itself
What we won’t do in this blog is look in detail at the underlying annotations (remember these are like formal comments) in detail. We’ll do that in the next blog of this series as we look at an alternative way of working with Fiori Elements using something called a local annotations file.
Tip: You’ll need to know the alternate approach particularly if your OData service comes from an ABAP system lower than NetWeaver 7.4 SP05 or from a non-SAP system.
Of course like all Fiori app frameworks there are extension options we can use to take our list report that little bit further…but that’s getting ahead of ourselves, so let’s come back to basics.
The 3 essential steps to creating a Fiori Element List Report are:
- Prepare the OData service
- Prepare the UI Annotations
- Create a Fiori App using the Fiori Elements List Report template
Note that the easiest way to create the Fiori App is by using the SAP HCP Web IDE (or Personal Web IDE) and the List Report (formerly Smart Template) Application wizard. However it is possible to create your UI application manually in any text editor once you know what’s required.
We’ll look at each of these steps in turn but let’s start by confirming the pre-requisites for Fiori Elements generally.
Pre-requisites for Fiori Elements
The pre-requisites are simple.
- A web browser that can run a Fiori app, e.g. Microsoft Internet Explorer 11, Google Chrome, Firefox, etc.
- A frontend server that provides a SAPUI5 version capable of supporting the Fiori Elements (formerly known as Smart Templates) we want to use.
- If you are running an On-Premise Gateway system that means you need NetWeaver 7.50 SP1 or above. Naturally the higher the release, the more Fiori Elements and Fiori Elements features available.
- An OData Service to provide the data for the Fiori Element, e.g. to provide the data for the List Report.
Note also that currently Fiori Elements support OData version 2.0 using vocabulary-based annotations. Annotations are a standard but optional part of the OData paradigm.
One thing to notice right away is that the backend system or database which holds our data is not a limitation. We don’t need our backend system to be on a specific ABAP release or even S/4HANA, and we don’t need our data to be on a HANA database.
That said, if we are using a backend ABAP system of NetWeaver 7.4 SP05 or above or a S/4HANA system, the backend system provides some features that make it easier to create both the annotations and the OData Service. That makes building our List Report easier, which is why our first use case uses a S/4HANA system for the example.
Similarly a HANA database is not necessary, but if we have a HANA database underlying our backend system the performance is improved, especially when we want to include analytics or do keyword text searches.
Prepare the OData Service
First and foremost we prepare the OData service that will extract data from our backend system to be displayed in our List Report app.
When developing a List Report it is important our OData service supports the following OData features:
- $count – This will be used to show a count of items in the list
- $filter – This will be used to filter our list
- And of course as it’s a list, the usual paging features such as $top, $skip, etc.
Tip: When designing the OData service it’s worth considering what features we want to support in our List Report. Is it just a read-only list or should we include some CRUD (Create, Read, Update, Delete) features? Do we want to support Draft document handling? If so the OData service needs to support these.
Of course there are several ways to create an OData service. As this blog is focussed on a simple example, we use the quickest way to create an OData service that’s available in the latest ABAP and S/4HANA systems, which is:
- Define a ABAP CDS View to extract the data for the List Report
- Tip: ABAP Development Tools for Eclipse are needed to do this.
- The latest ADT can be found here http://go.sap.com/community/topic/abap.html
- Note that if you are on NetWeaver 7.51, the ADT has been recently updated to ADT Version 2.68
- Test the CDS View using the Data Preview Tool in the ADT to check the data is returned correctly
- Expose the ABAP CDS View as an OData service using the annotation @OData.publish: true
- Activate the OData service in the SAP Gateway so that it can be consumed by an OData client, such as our Fiori app
- Test the OData service in an OData Client (a web browser will do at a pinch) to check it returns the expected data
If you have never used CDS views before, then now’s the time to learn it! CDS views underly all the latest Fiori frameworks.
Creating CDS views has already been covered in the NetWeaver help for About ABAP Programming Model for SAP Fiori in section Define a Data Model Based on CDS Views
Similarly exposing a CDS view as an OData Service has been covered in the NetWeaver help section for About ABAP Programming Model for SAP Fiori in Expose CDS View as an OData Service
You can also find more on this topic in the SAPUI5 SDK > Developing apps with Fiori Elements (Smart Templates) > Preparing OData Services.
The example we are using was prepared for the Teched 2016 workshop DEV268 Building an End-to-End SAP Fiori App Based on SAP S/4HANA and ABAP. I was privileged to assist some of the team with the workshop – Jens Weiler, Ingo Braeuninger, and Chris Swanepoel – at the Las Vegas session.
Prepare the UI Annotations
Given we have created a CDS View to specifically support our List Report, we can add the annotations directly to the CDS View, that will look something like this… I’ve highlighted where the annotations are applied.
Whether placing the annotations directly into the CDS view definition is a good idea from an architecting standpoint as you scale UX is debatable. Mixing the annotations directly in with the CDS view raises some Separation of Concerns issues, and it can be rather annoying if we later want to reuse the same CDS View for a different Fiori Elements app.
Fortunately as of NetWeaver 7.51 that’s no longer a problem as explained in these blogs:
ABAP News Release 7.51 Meta Data Extensions ABAP CDS
Modularizing CDS Annotations
We’ll talk more about annotations in the next blog.
Create a Fiori App using the List Report template
So finally we are ready to create our app based on Fiori Elements. The simplest way to do this is to generate the app using the List Report Application wizard in the SAP HCP Web IDE.
As usual, we use the menu option File > New > Project from Template to access the app generation wizards.
On the Template Selection tab, we select the List Report Application (previously Smart Template Application) wizard.
On the Basic Information tab, we enter the Basic Information of our app – Project Name and Title. We can add a namespace as well if you wish.
On the Data Connection tab, we select our OData service as usual.
On the Annotation Selection tab, any annotation files sourced from the OData service are listed. Typically if we are using a SAP Gateway hosted OData service this includes:
- A service metadata xml generated by SAP Gateway
- The annotations assigned to the OData Service itself
On the Template Customization tab, we select the OData Collection (i.e. entity set) on which we want the list report to be based. If there are associated navigations then these can optionally be selected also.
Tip: These associated navigations are useful for displaying additional information when navigating from the List Report to the related Object Page and to subsequent Object Pages. We’ll get to the Object Page in a future blog.
Press Finish and our app is generated.
Provided our OData Service contains all the annotations needed to create a basic List Report … we can run our fully functioning app straight away!
Filters, grouping, sorting, multi-item selection, button and link navigation, and even the totals bar are all working immediately. We can even go further than that and add rating starts, progress bars, and charts… and we’ll get to those in a future blog.
Taking a Quick Look Under the Covers
So how does a Fiori Element app work? We can see some clues by taking a look at the structure of our generated app.
If you’ve created some custom apps before or implemented some SAP delivered Fiori apps, you’ll notice the app is structured a little differently from the SAPUI5 apps you are used to. There are no view, controller, or model folders and files. That’s because these will all be handled by the Fiori Element templates themselves.
Instead of view, control, and model folders and files, we see an annotations folder and annotation.xml file. This annotation.xml file is the local annotations file which we will look at more closely in the next blog. There are also several i18n property files.
Taking a close look also at the manifest.json file…. We see the annotations files have been added as “data sources”. As usual the i18n properties files are listed as “models”.
The real magic of a Fiori Element app is in the “sap.ui.generic.app” section (which you will find after the “sap.ui5” section).
This is where the List Report and Object Page dynamic templates are applied to our app. At runtime, the app applies these dynamic templates to the annotations in our project (including the ones we inherited from our OData Service) to generate a working, high quality, production-ready, SAPUI5 app.
So by now a few questions may be coming to mind:
- What happens if the OData Service doesn’t have annotations? (Remember annotations are an optional part of the OData paradigm)
- Where do we find a list of all the annotations?
- How does the List Report user interface map to the annotations?
- What features does the List Report provide and how can they be controlled by annotations?
And that’s what we’ll start to look at in the next blog as we delve into the local annotations file.
Screenshots shown on:
- ABAP Development Tools on Eclipse Mars
- Web IDE Version: 161103
- SAPUI5 version 1.40.12