DIY Home Page Card

[VishnAndr]

In this blog, we will talk about Home Page Card. It supposed to be about Home Page Tile, however, in 1902 SAP introduced Home Page Cards. Tiles are staying till 1905 according to the recent release preview information.

From the perspective of the current blog, cards are the same as tiles. They are just rendered differently.

In 1811 release SAP introduced very nice thing as HTML or URL mashup tiles. Quite a powerful extension to the options we have to customize Home Page. But the topic I'd like to talk about is still not covered by SAP standard delivery.
This blog describes the solution to the question I raised myself quite some time back ago and which was not answered till recently: Custom Tile on Home page. Can we make a selection through parameters?

There are quite a few standard cards available to bring them on the home page. They are all under Filters group when we would go and use "Add Existing Cards".

But how about our very own custom filter?
Since it's not yet possible out of the box, I decided to go with DIY (do it yourself) approach. Long story short, I succeeded. And here I'd like to share with the Community step-by-step guide and walk through it.

How to create a custom card (aka custom tile) which would navigate a user to some OWL and apply any predefined selection (DefaultSet) immediately?

Let's say I created a new query via master layout change in the Visits search page. I wanted it to be "My Visits Today In Progress". I did it as Administrator user so the query is available to any user.
I assume the Reader is familiar with the process so far and we created the query successfully.

Creating a custom card for home page the standard way we can select Type as Floorplan. We need to give a title and a path.



We will use this Floorplan type of cards. But we need to properly compose the path and do one more trick.
The path needs to be in the following format:

$root-<WorkCenterPath>-<WorkCenterViewName>-<OWLName>::<Inport>::<DefaultSetName>

Let's figure out where to get all those parameters from.
Some of these parameters need to be obtained with the help of our fellow developer.

<WorkCenterPath>

The developer needs to look into SDK UI Designer and find the Work Center you'd like to navigate to. In my case, it's Visits Work Center.
The developer should provide you with the attribute of this Work Center called "Unique Id" or right click Work Center in Configuration Explorer and press "Copy ID". And this is going to be our <WorkCenterPath> which for my case is /BYD_COD/SalesOnDemand/Visit/COD_Visit_WCF.WCF.uiwoc


or



<WorkCenterViewName>

Being in the same Work Center the developer needs to navigate to Work Center View we need. For example, clicking on WorkCenterView Path link or via Configuration Explorer. There we need to get "Name" of Work Center View.



<OWLName>

Staying in the same Work Center View, the developer needs to open OWL component embedded into this view and give you its name.



<InportName>

This is a bit tricky. We need to find which inport in OWL component will suit our needs. Usually, it would be some inport with the name like FromCODHomePage. I checked and OWLs used in Visits, Accounts, Appointments, E-mails, Phone Calls, Tasks, Leads, Tickets all have such an inport with the same name.

However, if it's not there in your particular case, the inport we're interested in would have one parameter with the binding to a data model field which in turn is used in "Active DefaultSet Binding". Or alternatively, an event handler should be assigned to the inport which would also execute the passed defaultset somehow. In short, a bit of exploration might be required here. In the end, we should find the existing inport to pass default set to.
Here the example from Visits OWL.





We're almost done with the Path. The last parameter left is

<DefaultSetName>

If we were after any standard DefaultSet (or DefaultSet created in UI Designer because the approach works for custom OWLs as well), we would grab DefaultSet name straight from UI Designer.

However, we're after the DefaultSet (aka Query) created via master layout. Since anything created in master layout change mode is not reflected in SDK UI Designer, we're leaving UI Designer aside.
Here we need to launch C4C UI in debug mode. How to do it? Please have a look at my other blog post: SAPUI5 and C4C. My (un)expected journey. Preparation.
Having UI running in debug mode (remember - we need some patience here because it may take some time to load), we need to navigate to our Visits Work Center then View. Being there we need to press Ctrl+click on the dropdown where we select any of predefined query to open Client Inspector. In the end, we need to get Client Inspector showing us AdvancedListPane (Control) in Control Tree as the first element.



Scroll down the control tree in Client Inspector till we see DefaultSets. DefaultSets with Stable Anchor are usually those which are coming from UI Designer. We're looking for those DefaultSets which are without Stable Anchors. One of such DefaultSets is most likely to be the one we're looking for. Once we select the DefaultSet in the control tree, on the right-hand side we'll see its attributes. We're looking for its "defaultSetName".
DefaultSets created in the master layout have names which start with "$PersonalizedDefaultSet-".



But how to identify exactly which is ours since there might be many custom queries created?

For this, switch to "Component Model XML" tab in Client Inspector and search for your query description. Then locate the name attribute in the DefaultSet tag where we found our description. In my case the default set name is $PersonalizedDefaultSet-MyTodayVisits-9b1b



Ok, we have all parameters and my path for custom card looks like:

$root-/BYD_COD/SalesOnDemand/Visit/COD_Visit_WCF.WCF.uiwoc-COD_Visit_WCVIEW-COD_Visit_OWL::FromCODHomePage::$PersonalizedDefaultSet-MyTodayVisits-9b1b

If you went and created a custom card right here with type Floorplan, providing Title and the Path similar to the above one, you would get an exception when trying to press such card. That's because we haven't finished yet.

Now here comes the trickiest part.
Out of the box, Floorplan card works only with a path to open a certain Work Center View. For example, the path below doesn't produce an exception but opens Visits search page with default query.
/BYD_COD/SalesOnDemand/Visit/VisitExecution/COD_Visit_WCVIEW.WCVIEW.uiwocview (this is the Unique ID of the Visits Work Center View)

However, we want to open our exact query.
For this, we need to start to create a custom card, select the type as Floorplan, provide Title and the path with the DefaultSet we want to open. But don't press Save yet!!



Then we need to open developer tools. I prefer to use Chrome Developer tools but it's your choice. Remember, it's important to be in UI debug mode (or in SAPUI5 debug mode with sap-ui-debug=true parameter in URL when launching UI). This has made the source code be loaded in an uncompressed format.
We search for _createNewTileCatalogObject in all files ( Ctrl+Shift+F will open the search view if it's hidden). The result hopefully is like the below. Click the highlighted entry in PersonalizationPage-dbg.js and it will open us the source code. This is the function where a new tile object is created once we click Save.



We put a breakpoint right after the oCat object created (on oCat.ANY_DATA ....).



Now we hit Save button on "Create Custom Card" screen. The debugger is stopped at our breakpoint.
All we need to do here is to change oCat.NAV_OBJ_TYPE from FLOORPLAN to OWL_INPORT.



Notice that I did it in Scope-Local on the right-hand side rather than in Console. It's not the part of this blog, but the change made in Console doesn't work.

And then continue script execution with F8.

We're all done! Publish the change to the Home Page and we're good to go and test.



Now we have our DIY custom card which once pressed navigates us to the Visits Work Center View with configured predefined query created via master layout. And it's available to any user. You as Administrator just need to assign the card to any business role and publish the home page changes.



Luckily, I don't have any visits in progress for today. Yay!

If you want to show the number of found entries on such DIY card as it's shown, for example, on "My Open Tasks" or "My Visits Today" cards, I have bad news for you. Currently, it's not possible. SAP executes some backend services to get totals only for very limited predefined queries. Such as "My open tasks". And unfortunately, there is no way to enhance this place as of now.

 

UPD 28/04/2019: In 1905 SAP introduced "My Filters" home page card. This card shows all current users's saved queries.



 

UPD 10/05/2019: Troubleshooting tips

Since there were a few questions when something is not working in this approach, I thought it'd be good to provide some troubleshooting tips.

• Tickets' "Path" should look like:

$root-/BYD_COD/ServiceOnDemand/AgentQueue/COD_SEOD_AGENT_QUEUE_WCF.WCF.uiwoc-SEOD_Ticket_MD_SADL_WCVIEW-SEOD_Ticket_SADL_OWL::FromCODHomePage::<DefaultSetName>

• Authorization

Please check if the Work Centre / Work Centre View is assigned to your business role. For example, there are 2 work centre views available for Tickets. The content of those work centre views is identical. But still, they are two different Work Centre Views and you need access to the one you're trying to open.

• You're getting an exception, which (in its details) says "Error: Http Status Code: 404: in $root-/BYD_COD/...."

The root cause for this message: most likely you haven't changed NAV_OBJ_TYPE for your card from FLOORPLAN to OWL_INPORT during the creation.

Solution: please recreate the card changing NAV_OBJ_TYPE as described in the blog.

• You're still getting an exception or you'd like to know more about the root cause of the above "404" exception.

In the Developer Tools search for NavigationHandler.navigate (it is in NavigationHandler-dbg.js file) and place a break-point towards the end of the function on the line:

} else if (mNavigationForObjType.hasOwnProperty(oCatalogItem.NAV_OBJ_TYPE)) {

Click your card on Home Page, stop at the break-point and check what you have in:

oCatalogItem.NAV_OBJ_TYPE (it needs to be OWL_INPORT)

oCatalogItem.NAV_OBJECT_ID (it is your Path)



You can press F10 then F11 and then you should be in NavigationHandler._openWCV function. This proves you're on the right track. If any other function is called, then you have the wrong NAV_OBJ_TYPE. From NavigationHandler._openWCV you can continue debugging to find out how the navigation works in details.