Basics of Fiori Elements: Annotations for Analytical cards on Overview Page
Fiori Elements is a very convenient tool to generate simple UIs without lots of effort. If the goal is a basic UI to display data this tool can generate it automatically based on so-called Annotations.
In many cases we need only simple functions, and you should implement them time-to time just for different data sets. This time can be saved with the tool. See further details about the technology here.
Fiori Elements offers a tool called Overview Page to create dashboards, overview about business processes. The Overview Page contains cards to display set of data. One type of card is Analytical card.
Creating the necessary annotations is not easy, because the documentation is hard to understand for beginners. Therefore, I’ve thought a step-by-step guide would be useful.
For me it was especially hard to display the first graph on an analytical card. I could not magage it without help of the colleagues. I hope others can follow this guide and reach Quick success.
Fiori Elements applications (like Fiori applications in general) uses OData services as data sources. The OData Service what we would like to use in the application must be ready and tested.
Usually a CDS View is the source behind the OData Service. This is one point where the Annotations (The metadata which is used for the UI generation) can be placed. It is working well with the List Report apps, and the Table Cards of the Overview Page, but (at the moment at least) it’s not compatible with Analytical Cards. Don’t forget to set the destination to the backend System where the OData Service is running.
Another thing what you should create in advance is an Overview Page with the wizard. It’s easy and no need to further explanation.
So as prerequisite a CDS view without any annotations is needed, which is reachable via an OData service, and an Overview Page Project.
Creating the annotations
What I’m usually doing is create first a Table card to display the data in the card, then convert it manually to analytical card. Let’s follow this way.
If you follow the steps below you Will be able to create your own analytical card.
1) Open New Card Wizard
Right click on project title, select New / Card
2) Select Table card type
We Will use it to import the required service, if it’s not yet added. And check, whether the data appears.
To create an analytical card some annotation is needed. But these annotations can be set in the local annotation file, which is not exist before we import the service. The Table card haven’t got such a deadlock situation, and it can be used for service import to the project.
3) Select Datasource
If you haven’t added any card yet you can use the default data source. But if you need another one select the “Select new Datasource” option and add the details in the same way as you did it during project creation.
During the creation of the project an OData service was added, I Will use this one to display data. Please note, this is a custom one, don’t try to search for it in your local environment.
If the need for an analytical card appeared it is possible, that the service is already available.
4) Add basic details
Enter the Card title and select the proper Entity Set for the card. These data Will be used in the analytical card as well, so please enter here the final values.
5) Set table size
You can enter here any values, we won’t use them later.
6) Confirm the new project
Click on the Finish button. The new project is created.
7) Test the new application
Right click on the application, and follow the path: Run -> Run as SAP Fiori Launchpad Sandbox
The result will be the following (if there is no annotations in the backend side):
Only a header is visible due to the lack of annotations. If you are using an OData service, which has annotations on the backend side the card may appear.
8) Create local annotation file
I’ve tried several times to find the proper annotations in my CDS view to create the Analytical view, but I failed. I was told that the trick is using local annotations.
Right click on the webapp folder, then select New -> Annotation file.
9) Select target of the annotation file
Your project can use multiple OData sources. When You create a local annotation file you should select the OData Service, which Will be annotated by the file.
Enter a valid file name. I put the OData Service name as prefix, and “_annotation” as postfix.
Warning: Don’t name the file using simply the Service name! It may overwrite the Model file!
10) Confirm file creation
The last thing of annotation file creation is click on Finish button in the confirmation step.
11) Open the newly created file
You can find your annotation file in the webapp folder. In the background the file was registered in the manifest.json file, this is the place where the used resources are listed -among our new file.
Click on it to open the file.
12) Switch to Annotation Modeler view
This is how an empty annotation file looks like. In the Reference field you can see the name of the OData service where the file points to.
Switch to tab Annotation Modeler.
And don’t forget to save during editing this file!
13) Add Chart annotation to the file
There is a + button at the end of the Local Annotations row. Click on it and select the Chart annotation. This will add the Chart entry to the XML file, which helps us to describe what we want to see in the card.
14) Select Bar type from the dropdown
With the UI.Chart annotation a sub entry appeared called Chart Type. In th dropdown list you can select the entry called Bar.
15) Add Chart properties
We need two more properties under UI.Chart. Click on the + button next to the UI.Chart label. Make sure you select the right button. In the popup window select the MeasureAttributes and DimensionAttributes properties. Click OK.
16) Add ChartMeasureAttributeType proerty to MeasureAttributes.
These subentries needs further properties. First let’s take Measure Attributes. Click on the + button at the end of the line. There is only one property: ChartMeasureAttributeType. Select it, and add it to the annotation file.
17) Add properties to ChartMeasureAttributeType
Click on the appropriate + button and select the first two items: Measure and Role.
18) Configure measure parameters
Here you can configure which OData property Will be used to display the bars. This Will control the size of them. In my case it called counter. It Will be used as Axis1.
19) Add ChartDimensionAttributeType to DimensionAttributes
Then we Will repeat the previous steps for the DimensionAttributes. Please make sure you select the right + button. The property is called ChartDimensionAttributeType.
20) Add attributes to ChartDimensionAttributeType
This property also needs the same two properties Dimension and Role.
21) Select dimension type
Select the OData property in the Dimension field which contains data for the other axis. In my case it is called type. The Role Will be Series.
Now we defined every annotation for the analytical card. But after save if we test the application again in the previously presented way we won’t see anything.
22) The original Card description in the manifest.json
Because the manifest.json configuration file contains description of a table card. See the template field. This Will be replaced by the analytical card template.
23) Modify card description
Replace template with “sap.ovp.card.charts.analytical“. Delete the unnecessary fields in the settings area. Add the ChartAnnotationPath as displayed below. Save the changes.
24) Test the result
If you test the application now, you Will get this beautiful graph on your screen. Enjoy!
The information about the how-to is available on the pages of SAP. I’ve just collected them and transformed it to an easy to understand format.
The Local Annotations are the key of the analytical card. It provides much more oppurtunities, you can play around with them. If the basics are clear it is much more easier to understand the documentations.