Technical Articles
Fiori Elements – How to develop a List Report – Basic Approach
Latest Update November 2020: THIS POST IS NOW RETIRED – Please go directly to SAP Community topic for Fiori elements
It’s hard to believe that 4 years have passed since I first started blogging on SAP Fiori elements.
Since then it has grown from strength to strength. SAP Fiori elements apps are now the:
- Preferred choice for SAP Fiori apps delivered for SAP S/4HANA
- As at November 2020 nearly 900 of the more than 2K apps available are SAP Fiori elements app
- Preferred and recommended choice for efficient development of your own custom-built apps
- Preferred build approach for many of our customers… see the SAP TechEd 2020 session: Yorkshire Water uses SAP Fiori Elements to build Fiori apps quickly
The tooling has also changed from SAP Web IDE on SAP Cloud Platform Neo, to the next generation tooling SAP Fiori Tools. SAP Fiori Tools are an extension of SAP Business Application Studio on SAP Cloud Platform Cloud Foundry that guide you through creating your own SAP Fiori elements apps – and they can be run offline on VSCode too.
So it’s time for this blog post to step gracefully aside and instead refer you to the current best resources for Fiori elements, including:
- SAP Community topic for Fiori elements – get the latest resources, ask questions, and swap experiences with other customers, partners, independents, and SAP employees
- The official documentation on SAP Help Portal: Developing Apps with SAP Fiori elements
- You can also find this documentation via the SAPUI5 SDK at https://ui5.sap.com > Documentation > Developing Apps with SAP Fiori elements
- The video playlist on Youtube: Getting started with SAP Fiori elements playlist
- The Tutorials for SAP Fiori Tools on https://developers.sap.com
One last big hint: One of the most beneficial additions to the official documentation is the SAP Fiori elements feature map which explains what is available per floorplan for your SAPUI5 version – definitely worth a read!
But hey, all knowledge has value so if you want to read how this used to work in the SAP Web IDE… read on!
*****
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.
What if…
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
Really nice blog, have done the same in hands-on sessions at TechEd Barcelona last week. As a follow-up question regarding system landscape: could I actually do this on the NetWeaver AS ABAP Developer Edition offered at https://tools.eu1.hana.ondemand.com/#abap, connected to my HCP trial account via local Cloud Connector?
Hi Alexander,
yes this is possible - feedback how it worked for you is also highly appreciated.
Cheers
Jens
Hi Jocelyn,
If we need to provide a range of values in the filter then what should we do, for example we need multiple company codes in filter criteria or a date range to be entered as input, in this case what should we do, Please advice.
Regards
Ik
Hi Ik
The list report uses a fully functioning Smart Filter bar.
Ranges work in the filter criteria as do date ranges for input in date fields.... with the usual provisos about checking for SAP Notes first as there were some early issues with dates in the filter bar.
So once you click into the filter field you can create all sorts of conditions.
There's an example of the Smart Filter Bar in the SAPUI5 Explored library.
The Fiscal Year filter shows you the default behaviour of filter fields.
https://sapui5.hana.ondemand.com/explored.html#/sample/sap.ui.comp.sample.smartfilterbar/preview
Rgds
Jocelyn
Hi Jocelyn,
Do you have the full source code for the CDS shown with annotations in this blog.
https://blogs.sap.com/2016/11/16/fiori-elements-how-to-develop-a-list-report-basic-approach/
Thanks,
Subba
Thanks for the clarification jocelyn. but for the normal case in a CDS the range input parameter is still not supported(with parameters option), please correct me if i am wrong.
Perhaps we are talking about different things IK?
You can certainly enter a range in a filter parameter in the Smart Filter Bar of a Fiori Element List Report e.g. Company code between 1000 and 1100.
However your response sounds like you may be talking about parameters directly in the CDS definition itself. Please note that the CDS definition itself is not the focus of this blog. If you need confirmation of CDS functionality that would be best handled as an ABAP question perhaps.
Hello Jocelyn,
Very nice blog.
With more Fiori elements on their way (i.e. no more SAPUI5 development for most of the use cases), what role UX developers will play?
Hi Vinod,
Don't worry! There's no intention to replace UX developers by covering all use cases with Fiori Elements. We just want to cover the most common repeatable pattern - the stuff that should be pretty boring to a developer.
For a good UX developer there's always a use case - especially for tasks tailored to the mental model of a specific user group or business role.
Rgds,
Jocelyn
Hi Jocelyn! I followed the link you posted to the wiki, very useful page, thanks! I have used another blog post in the past to setup an Elements app. I tried to edit the wiki page, but either I don't have access, or possibly I just can't find the edit action. Can you please add this to the list of how to guides:
How to use Smart Templates with SAP Web IDE
Also, I am looking forward to more blog posts and information on using Fiori Elements. There does not seem to be much documentation on the subject as of yet. We started to build an app using Elements, then ran into some roadblocks and restarted from scratch. Namely, we could not figure out how to navigate to other custom pages that weren't using the builtin ObjectPage and ListReport templates. As an example, we wanted to link to a page which we could control the view to switch between an add/edit function. Either we did not set something up properly, or there just isn't enough documentation or examples on how to do this. Because there is no routing and targets in the Elements app, we were not able to wrap our heads around how to get that part working. Time also became an issue, as it ended up being quicker for us to just create an app from scratch then spend a bunch more time digging through documentation, blog posts and Q/A to figure out what we wanted to do.
Hopefully there is more detailed documentation released on how to customize the Fiori Elements apps. There is also this link:
Sample Applications
Is there any way to download these sample apps so we can see how all of this is done? These sample apps look very well put together, and would be useful to have as an example when creating a new Elements app.
Thanks for you contributions!
Cheers,
Tim
Hi Tim Molloy ,
Thank you everyone for all the information on the blog. In response to your response, did you find a way to download it from sample applications?
Regards,
Özlem
HI Jocelyn,
Really like it, it helps a lot to clarify what the list report really is as the concept is actually not clearly described in the "Official Online Help".
Looking forward to your further blogs on this series.
Regards,
Marvin
Thanks Marvin. Still planning to get back into this series soon ...
Hi Jocelyn,
Really nice blog. You have written it in a way that made it really easy to understand for me.
I tried it out myself and it works well.
I have one question though:
I have followed your blog and created a simple sales order CDS model. I have created three CDS views.
I have navigation defined to and fro between SO <-> BP and SO <-> SI.
I used the List report template as illustrated by you. It works fine.
But I created a second project using List report template and this time in the 'Template Customizing' screen, instead of choosing 'Sales Order' entity set I choose 'Business Partner' entity set. I wanted to start the app with BP List and then navigate to the associated Sales order from there. This time the application ended up in error when I hit the search button on the List view initial screen.
I get the following error in my browser debugger console.
"Draft 2.0 object CDS_C_ZKU_SALESORDERTP_SADL_XA_X~C_Zku_So_BPTP requires selection condition on IsActiveEntity","propertyref":"","severity":"error","target":""
Question: Does this mean List Report template only work when data binding is done with the OData Entity Set corresponding to the CDS Root View(SO in my example)?
Thank you!
Best regards,
Krishnan
Hi Krishnan,
Ok based on your error message that isn't the problem you are experiencing. I take it you applied Draft Handling as per the ABAP Programming Model for Fiori - well done!
Once you apply Draft Handling the IsActivityEntity parameter is a mandatory parameter of the OData Service - so you have to provide it always.
As far as using a non root entity goes - you need to be able to access the entityset directly from the OData Service. So test your OData Service first to see if you have written your CDS View in a way that lets you access the BusinessPartner collection without first accessing the Sales Order collection
Hope that helps
Jocelyn
Hi Jocelyn,
I am using same example for CDS-BOPF, but our UI/UX is not UI5/FIORI but its different, so I thought instead of using annotation Odata:publish: true I opt for data reference as cds.
So metadata is coming fine for me, but while retrieving Salesorder or Item I am getting same error as Krishnan was getting--
Draft 2.0 object Z_BOPF~ZC_SALESORDERSHEAD requires selection condition on IsActiveEntity
I am not getting where I have to pass IsActivityEntity , do i need to change in MPC class or any alter in URL
I am using the URL like this
/sap/opu/odata/SAP/Z_BOPF_SRV/ZC_SalesOrdersHead
Please guide on on this issue.
Regards,
Abhijeet kankani
I got the solution for this.
As application using drafts the entity keys become composite, it will include one more key called “IsActiveEntity”, so while passing key fields one have to pass one more key
IsActiveEntity=true in URL and it start working.
Regards,
Abhijeet Kankani
Hi Kankani
I faced the same issue of “IsActiveEntity”.
But i change the url to /sap/opu/odata/sap/ZSD_SOHEADER_C_CDS/ZSD_SOHEADER_C?IsActiveEntity=true
the issue is persist
Could you give me some advice of this issue.
Thanks.
It is oData syntax
?$filter=IsActiveEntity%20eq%20true
Hi Jocelyn,
Really nice blog, it helped me a lot .
Is there also a documentation how to publish these apps to the Fiori GUI in an ABAP Backend server
or as stand alone app ?
Because we don’t have a Hana Cloud Fiori subscription and don't want it just to run in the WebIDE
Regards,
Thomas
Hi Thomas
You deploy your app to your runtime environment - whether that's an on-premise ABAP Gateway server or a Cloud Portal or Fiori Cloud edition or some other server - just like any other custom built Fiori app. That's a standard feature of the Web IDE - the help is here.
Rgds
Jocelyn
Hi Jocelyn,
Could you please help me understand if the future model for fiori apps in s/4 is going to be based on SADL with ABAP CDS annotations, BOPF and OData ?
So is it going to be completely template driven. Also the youtube videos on ABAP programming model for s/4 isn't helpful to me. Can we have short tutorials and most importantly good easy to understand documentation on CDS annotations.
Regards,
Prasenjit
Hi Prasenjit
The ABAP Programming Model for Fiori is the recommended approach when developing Fiori apps on NetWeaver ABAP servers.
However there is some flexibility and alternatives within it. For instance, we don't ever expect that it will be *completely* template driven - more that we try to cover as many common use cases as we can with templates.
This minimizes when you need to do full freestyle development - although of course you can develop the underlying OData Service in the same way even for freestyle apps.
Thanks for your feedback re the videos - I'm guessing you were looking at the 1-2 hour Teched replays. We are getting more information out there.. at SAP Inside Tracks and CodeJams. We also have more information explaining the approach being released as part of the Beacon project https://experience.sap.com/beacon/ and keep checking SAP HANA Academy as well for tutorials and other material
Jocelyn
Hi Jocelyn,
Really nice blog, its useful for me .
But i have a doubt do i need to write OPA integration test and qunit test ?
If yes how should i write this test code ?
Regards,
Anjan.
Hi Anjan, You'll notice the test folder is still there so yes you should still do OPA and Qunit tests just the same as any other app
Rgds
Jocelyn
Hello, Jocelyn.
Very nice blog, but i have a question.
I've create ListReport using CDS + annotations+ SEGW. And now i need to add my own selection field on listReport without reference to CDS field.Can I do this with local annotation or abap code in *_MPC_EXT class?
Two things...
One.
How to populate PARAMETERS on a CDS view? I have a TABLE FUNCTION which requires parameters, and I can't figure out how to make that work. Code commented that did not work, so I hardcoded for Question 2.
TWO
How are you populating _item. The code above with hardcoded parameters to Table Function works, but the navigation to _item brings up an empty table.
FYI... the parameters, and navigation work fine in Eclipse. Argh.
Thanks,
Tim
Full View definition above
Thanks, Timothy.
I can’t figure out how to make work cds table function in ListReport too.
Maybe Jocelyn can help us ?
Hi folks, CDS Views with Parameters are not currently supported by Fiori elements. CDS Views with parameters are mainly used with analytical apps such as Smart Business tiles.
With a Fiori element we want the filters exposed as selection options for the user to determine. If you are wanting to default values for them then consider using User Defaults if this is a S/4HANA environment
https://blogs.sap.com/2017/09/14/applying-user-defaults-in-sap-s4hana/
Otherwise please look at the options for passing parameters to the app via external inbound navigation https://sapui5.hana.ondemand.com/#/topic/1d4a0f94bfee48d1b50ca8084a76beec
If you have further question please make sure you raise them as question on answers.sap.com. Blog comments are not the proper place to resolve specific issues.
Jocelyn
Thanks, Jocelyn.
Hi Jocelyn - From what SAP UI5 version Fiori Elements is the CDS views with parameters supported from? It seems to work on version:
SAPUI5 Distribution 1.78.2 (built at 2020-06-03T15:27)
But at my client, we have:
SAPUI5-on-ABAP 1.52.41
And it does not work there.
Not sure how to proceed. I can have the client upgrade to 1.78.2 or try a work around but I am not sure.
Thanks,
Jay
When I run a List Report App works on SAP Web IDE but when using the SAP Web IDE Full-Stack and I run the app is blank nothing is showed.
There are some settings that has to be done when using SAP Web IDE Full Stack ?
Hi Rodrigo, No there isn't anything extra - they should work the same.
Just make sure you are starting your test by running it from the Component.js file.
Personally I have been finding a few problems with the Full Stack Web IDE recently so if that doesn't work it may be a bug. If you think it is that please raise an incident and perhaps send a tweet to @SAPCP
Rgds
Jocelyn
Yeah, was a general problem that occurred with all testing in SAP Web IDE Full Stack Trials accounts.
Thanks for the summary Jocelyn. Very helpful. Been watching this space for a while but we're just late on getting serious with the 'Fiori' journey with the team. I'm looking forward to reading all your 'back-blogs'. I'm finding that the configuration / Fiori elements approach eases some of the transition issues from older UI approaches. Some of the basic concepts easily maps/translates from ALV or FPM/UIBB. 🙂
Hi Wilbert, If you are attending or have a colleague attending Teched 2018 it's worth going to/getting the presentation from: sessions CNA215 and CNA216 - which put all of this into perspective for now vs. future. And for hands on workshops get to CNA379 or CNA381. 🙂
And CNA205 What's new in Fiori elements... a WYSYWIG editor coming at last !!!
Hi Jocelyn,
Im using datafieldwithURL in list report , but it doesnt render as a URL please help
Hi Jocelyn
A little list report related question:
I added some Actions (Function Imports) to the list report. No matter what I do, error messages from the backend are not displayed in the list report. I see the correct messages from BOPF action in the response header however.
Any hints on this?
@ Jocelyn Dart ,
I have a CDS view which has a date type field (ABAP.DATS), when I run in RSRT (since its a analytical view) or any multidimensional report date comes fine but when I see the same using List Report it comes in a different format
For Example - 10 Jan 2020 comes as -
Posting Date - 01/10/2020 (Jan 10 2020).
I have tried changing the metadata.xml file .. sap:display-format="Date" but it didn't work.
Can you please give some pointers ?
Best Regards,
Mayank Jaiswal