[[{“value”:”
Introduction
Do you know in which roles a specific app is used in your SAP Build Work Zone, standard edition site? And which apps are not assigned to any role at all?
In the Content Manager you can open a role and see the apps, catalogs, groups and spaces in it. The other direction is a lot harder: starting from an app and finding all the roles, pages, spaces, catalogs and groups that contain it. On a small site you can click through it, on a site with hundreds of apps this is not an option anymore.
In this blog post, I’ll show you the where-used app I built for this with CAP and Fiori elements, how it works under the hood and how you can run it yourself.
Problem
The Content Manager is great for building content top down: you create a role, assign apps, add a space with pages. What was missing for me is the view from the bottom up.
You need to be able to:
- Find all roles that give access to an app, directly or through a catalog, group, space or page
- See the path of that assignment, for example
Catalog > RoleorPage > Space > Role - Find the content that is not in any role, so you can clean it up
- Jump from one object to the related one without searching over again
An app is often assigned in more than one way. It can be in a catalog that is in a role, on a page of a space that is in another role and assigned directly to a third one. That’s exactly the information you need before you remove or change something.
Solution
So I built one: a CAP Node.js service with a Fiori elements List Report and Object Page on top of it, deployed to the HTML5 Application Repository so it can run as a tile in Work Zone itself.
My first idea was to read the content live. The Content Manager uses a GraphQL API (/semantic/graphql) for this, but that one is internal, not documented and it only answers on the Work Zone admin host. Not something I want to build an app on. So I went for a simpler approach: the app works on an export of the content which you upload in the app.
This has a downside, the data is only as fresh as your last import. Nevertheless, it also has an advantage: you can keep an export of each subaccount next to each other as a snapshot and compare dev with production.
The best analogy in the SAP world: it’s like the where-used list in the ABAP Workbench, but for launchpad content.
How it works
Before starting on the details, an overview of what happens:
- You export the content in Work Zone
- You upload the zip in the app and give it a snapshot name
- The CAP service reads all content items in the zip and the relations between them
- It calculates for every item where it is used (directly and indirectly) and stores this in the database
- The Fiori elements app shows the result
The project is small, these are the files that matter:
Type File Description
| Data model | db/schema.cds |
Snapshots, content items and usages |
| Service | srv/where-used-service.cds |
Read-only entities and the import action |
| Handler | srv/where-used-service.js |
Runs the import and replaces an existing snapshot |
| Parser | srv/lib/cdm-index.js |
Reads the export and builds the where-used index |
| UI | app/whereused/annotations.cds |
Fiori elements annotations for the list and the object page |
| UI | app/whereused/webapp/ext/ImportAction.js |
The upload dialog |
| UI | app/whereused/webapp/ext/ObjectPageExt.controller.js |
Navigation from a row to the related object |
Step 1: Export the content
Make an export in the site directory from a specific site to have the full content to look into:
This will result in a zip file which contains the content items as JSON documents.
Step 2: Import the export
In the app, I added a button “Import Export File” on top of the list. This opens a dialog where you select the zip and provide a snapshot name, for example the name of the subaccount:
Importing again with the same snapshot name replaces that snapshot, with another name you get a second one next to it.
Once imported, the app shows a message with what it found. For the demo content in this blog post it looks like this:
24 entities read, 24 items indexed, 29 relations, 66 where-used entries
Check this message on your first import, it tells you immediately if the parser understood your file.
Step 3: Search
The list shows every content item with its type, its ID and the number of roles it ends up in:
You can search on title and ID and filter on type, snapshot and number of roles. The red ones are the items that are not in any role. With the filter “Not in any role” you get your cleanup list:
In this example the old catalog and the app in it are not used anymore, together with a forgotten PoC app.
Step 4: Where is it used?
Selecting an item opens the detail page. This one has a table for each type of object the item is used in: roles, pages, spaces, catalogs and groups.
The “Customer Overview” app in this example is in two roles, but in three different ways for each of them: through the catalog “Sales Apps” and through two pages in the space “Sales”. The column “Path” shows how the app ends up in the role and “Assignment” tells if it is assigned directly or not.
Selecting a row brings you to the detail page of that object. So from the app I can open the space, which shows me in the “Contains” table the pages in it:
From there you can continue to a page, to a role and so on. The back button brings you back step by step.
Under the hood
Let’s have a look at the three parts that do the real work.
The parser
The export format is not documented, so I made the parser as generic as possible. It reads every JSON file in the zip (also zips in the zip) and picks up every object that looks like a CDM entity, which means it has an identification with an id and an entityType:
const ident = node.identification;
if (ident && typeof ident === 'object' && ident.id && ident.entityType) {
const key = keyOf(ident.entityType, ident.id);
const prev = found.get(key);
// keep the richest version if an entity occurs more than once
if (!prev || JSON.stringify(node).length > JSON.stringify(prev).length) found.set(key, node);
}
The relations between the items come from the relations of each entity. A role has relations to its apps, catalogs, groups and spaces, a space has relations to its pages. The relation of an app to its base app is skipped, that one is not a usage.
Pages are a special case. A page doesn’t always store its tiles as relations, they are somewhere in the layout of the page. For this, I scan the payload of every page for the IDs of the known apps. Not the most elegant solution, but it works.
Once all relations are known, the parser walks from every item upwards to its parents, the parents of the parents and so on. Every object it passes is stored as a usage together with the path to get there.
The data model
In the data model, every usage is a record “item is used in another item”. The trick to get a table for each type on the object page is a set of associations with a filter in the on condition:
entity ContentItems : cuid {
snapshot : Association to Snapshots;
itemId : String(255);
itemType : String(30);
title : String(255);
description : String(1000);
providerId : String(255);
roleCount : Integer default 0;
isOrphan : Boolean default false;
usages : Association to many Usages on usages.item = $self;
roles : Association to many Usages on roles.item = $self and roles.usedInType = 'role';
catalogs : Association to many Usages on catalogs.item = $self and catalogs.usedInType = 'catalog';
groups : Association to many Usages on groups.item = $self and groups.usedInType = 'group';
spaces : Association to many Usages on spaces.item = $self and spaces.usedInType = 'space';
pages : Association to many Usages on pages.item = $self and (pages.usedInType = 'workpage' or pages.usedInType = 'page');
contains : Association to many Usages on contains.usedIn = $self and contains.direct = true;
}
Each of these associations is a facet on the object page. No custom code required for the tables. Just annotations.
The navigation
Fiori elements wants to navigate from a table row to a detail page of that row, which would be the usage record. That’s not what I want, I want to open the role or the space behind it. This can be done with a controller extension on the object page that overrides onBeforeNavigation:
onBeforeNavigation: function (parameters) {
var context = parameters && parameters.bindingContext;
var path = context && context.getPath();
if (!path || !//(roles|pages|spaces|catalogs|groups|contains)(/.test(path)) return false;
var targetProperty = path.indexOf("/contains(") > -1 ? "item_ID" : "usedIn_ID";
context.requestProperty(targetProperty).then(function (id) {
// a plain hash change adds a browser history entry, so Back returns to the item you came from
if (id) HashChanger.getInstance().setHash("ContentItems(" + id + ")");
});
return true; // the default navigation is replaced
}
My first version used navigateToRoute of the Fiori elements extension API. The navigation worked, but the back button brought me to the list instead of the previous object. So I changed it to a plain hash change and now the back button behaves as expected 😊
Getting It Up and Running
Run it locally
- Clone the repository and install the dependencies:
git clone https://github.com/lemaiwo/wz-where-used.git
cd wz-where-used
npm i && (cd app/whereused && npm i)
- Start the CAP server:
cds watch
This also serves the UI thanks to the cds-plugin-ui5, you don’t need to start a second server for it. Open http://localhost:4004/be.lemtech.wz.whereused/index.html and log in with the mock user admin / admin (or viewer / viewer for read only).
- You can validate if everything works by running the unit tests of the parser:
npm test
Deploy to BTP
The project contains an mta.yaml for Cloud Foundry with XSUAA, HANA Cloud (HDI container) and the HTML5 Application Repository:
mbt build && cf deploy mta_archives/wz-where-used_1.0.0.mtar
Once deployed, your subaccount contains two new role collections:
WhereUsedViewer (...): search and displayWhereUsedAdmin (...): import and delete snapshots as well
Next, refresh the HTML5 Apps channel in the Channel Manager of Work Zone and add the app “Work Zone Where-Used” to a role. This makes it available as a tile in your site.
Limitations
A few things you should know before using it:
- Snapshot only: the data is as fresh as your last import
- Page placement is not visibility: a path
Page > Space > Rolemeans the tile is on a page of that role. A user only sees the tile if the app is also assigned to the role - Role collections are not in the export: Work Zone generates a role collection with the same name as the role, so the role name is your link to the users
- Titles: in my first real export some apps showed their ID instead of their title, the parser doesn’t resolve all title formats yet
- Undocumented format: the parser is based on what I found in my own exports. If your export looks different, let me know!
Conclusion
With one upload I now get an answer on “where is this app used?” and “what is not used anymore?” for a complete Work Zone site, without clicking through every role in the Content Manager. CAP and Fiori elements made this a small project: most of the UI is annotations, the only real logic is the parser.
Feel free to try it on your own site and let me know what it finds 😉
Contributions and feedback are welcome! The full source code is available on GitHub: https://github.com/lemaiwo/wz-where-used
“}]]
Read More Technology Blog Posts by Members articles
#abap