Help with creating custom Root UI / App Shell (left nav + header) for Portal experience

[bishalsharm]

Hi all,

I’m trying to build a custom frame (Root UI / App Shell) for a Portal‑style experience in UI Builder and I’m stuck with a blank screen.

What I want

• A custom “root shell” page that provides:

  • A left vertical navigation bar (my own menu items, not the classic filter navigator)

  • A header that stays consistent across the whole experience

• My portal pages should load inside this frame.

• A custom theme should be applied via a UX Parent App.

What I’ve done so far

1. Created a UX Parent App (sys_ux_app):

   • App Shell Root UI: set to “My Custom Root Shell” (a sys_ux_macroponent record)

   • Base theme: my custom theme

2. Created a Portal experience (Sample Portal):

   • URL path: /sample_portal

   • Parent App: Customized Parent App

   • I have tried both:

     • App Shell UI = Portal App Shell

     • App Shell UI = My Custom Root Shell

3. Created a macroponent (sys_ux_macroponent) called “My Custom Root Shell” with:

   • Category = Page

   • Filled out style_config, layout, composition, data, internal_event_mappings

   • Composition references sn-side-nav and sn-header-toolbar and later I even reduced it to the minimal test:

     json

     { "tree": { "component": "now-viewport", "props": {}, "slots": { "content": { "id": "test-box", "component": "now-text", "props": { "value": "Root shell is working" } } } } }

4. Added UX Page Properties (sys_ux_page_property) for the side nav and header (names like ux_root_side_nav, ux_root_header).

The problem

• When I access the portal URL:
  /now/sample_portal/homepage
  I get a completely blank white screen.

• DevTools console shows no hard errors, just preload warnings.

• If I switch back to Portal App Shell + standard Parent App, I see the normal classic‑style left navigator and header, so routing works.

• As soon as I wire in My Custom Root Shell via the Parent App / App Shell UI, the experience goes blank, even with the very simple now-viewport + now-text composition above.

My questions

1. For Zurich  UI Builder, what is the correct, minimal JSON structure for a macroponent that is intended to be used as:

   • a) App Shell Root UI (shell_root on sys_ux_app), and/or

   • b) App Shell UI on the experience record?

2. Are there any required fields or conventions (root element definition, specific component names, required layout structure) for a macroponent to be recognized as a shell and not cause a blank page?

3. For a Portal experience, is a custom App Shell Root UI actually honored, or is Unified Navigation forced and custom root shells only supported for workspaces?

4. Given my goal (custom left nav + header that wrap a portal experience), what is the recommended pattern:

   • Custom Root UI wrapping the OOB Portal App Shell, or

   • Custom App Shell replacing Portal App Shell, or

   • Something else?

Any working example JSON for a minimal custom shell (header + left nav + content slot) wired to a Parent App would be hugely appreciated.

Thanks in advance!