It's a new year which means it's time for some new content. I really enjoyed diving into different topics in 2021 and look forward to putting out more posts for 2022. I mentioned in my previous post Exploring the Import Set API that I will be narrowing down the focus of this blog. To provide some context in January 2022 I joined ServiceNow as an Outbound Product Manager for the Platform UX team, which means I'm mainly focused on UI Builder and the Now Experience Framework. I'm sure posts about related functionalities will make their way in as we all know that many ServiceNow products are interwoven with one another.
For the first post of 2022, I want to start at the foundation of UI Builder and discuss what an experience is as well as the different app shells that are provided when launching an experience. The goal of this post is to clarify how to create an experience and the differences in creating an experience via Studio versus App Engine Studio. I do want to note that the functionality I discuss in my posts will reflect what is currently available in a PDI at the time and I will not be posting any forward looking content. As of this post, the functionality discussed is for the Rome release.
I'll start with a quick definition of what an experience is and how it applies to development work within ServiceNow. Think of an experience as a bundle of different pages that users can interact with for any given application. Most web sites utilize the same elements across each page in the site such as a header, footer, etc.
At the moment ServiceNow ships with two baseline experience types which is defined by the app shell used. I'm going to go off the beaten path on the documentation and state there are actually three baseline app shells and include the option to use a blank app shell.
Agent Workspace App Shell
Portal App Shell
UXR Blank AppShell
As a developer and experience designer, this will be the first question you ask. Which app shell should I use for my experience? This will really depend on how the user will interact with your experience. If you're looking at building a more end-user focused self-service experience and want a standard header and footer the Portal App Shell would be the pick for this. If users will be interacting with a variety of tasks and need a more multi-tasking experience with tabs then the Workspace App Shell would be suited for this. If neither of these app shells fit the purpose for the experience then the UXR Blank App Shell can be used. One thing to note on using the UXR Blank App Shell is that common elements such as headers would need to be created on each page if they are needed.
As of the Rome release there are four ways that an Experience can be created, I do want to mention the use of App Engine Studio does require licensing and costs should be discussed with an account representative, you can however play freely with App Engine Studio in a Personal Developer Instance. I'll go into detail more on these methods after discussing App shells.
App Engine Studio
Now Experience Framework Module
An experience consists of the following records:
UX Application (sys_ux_page_registry) is a top level record which houses which app shell the experience uses and other application properties.
UX App Configuration (sys_ux_app_config) is a collection of pages and themes for the experience.
If you're using App Engine Studio to create an experience, you may not see these records right away and may never need to work directly with them. If creating an experience with the other methods, you'll have to initially create these records, but again may not touch them again after creation as most work is done in UI Builder.
As mentioned above, web sites use common elements across each page and as of the Rome release of ServiceNow there are two baseline app shells: Portal App Shell and Agent Workspace App Shell as well as the option to utilize the UXR Blank App Shell. A great example of using the UXR Blank App Shell is the NeedIt experience in the UI Builder course on the Developer site. Note: While the App Shell UI field on an UX Application record is not a required field, the experience will not show in UI Builder without this field populated.
App shells are useful in providing a consistent look and feel across the experience and theming can be configured to provide branding and customization across different experiences utilizing the same app shell. App shells are also very helpful in enhancing the performance of a web site or experience, as the app shell itself is cached with the dynamic content within the shell itself loaded for each page in the experience. There's more documentation out there on the App Shell Model if you want to go down the wormhole on this subject.
If you navigate to Now Experience Framework > App Shell UIs, you'll notice there are multiple app shells for things such as AES, Decision Builder, Catalog Builder, etc. These shells pertain more so to what ServiceNow has implemented them for, but if you're in a PDI you can always poke around and see how these differ, especially if you're wanting to learn more about how app shells are made. In looking at an App shell record, or UX Macroponent (sys_ux_macroponent) you'll notice that the record itself is a JSON object. ServiceNow Developer MVP Andrew Pischulin has some great articles on Experiences and App Shells and Routing if you're wanting to dive deeper on this topic.
Creating an Experience
App Engine Studio
When creating an application in App Engine Studio there is the option to add one or more experiences to the application. To demonstrate what is shipped out of the box with each experience I created an application without any additional tables, flows, etc. and launched a Portal and Workspace experience.
When creating a Portal Experience in App Engine Studio you'll see it's automatically configured with a header, footer, and some default pages. The menu in the header has also been automatically configured. Developers have access to the UX Application records to view how these experiences are created, which can be very useful as a guide if creating an experience from other methods.
In looking at the UX Application record for the portal experience there are pre-defined UX Page Properties that have been created. The UX Page Property records (sys_ux_page_property) contain and allow for the configuration of common elements such as the header, footer, and menu.
When creating a Workspace Experience in App Engine Studio, it's configured automatically with a header, sidebar, and default pages. The header contains the user profile, search, and notifications. The sidebar ships with the Home page, Lists page, and Analytics center page which can be configured in the Experience settings.
In looking at the UX Application record for the workspace experience there are pre-defined UX Page Properties that have been created. The UX Page Property records (sys_ux_page_property) contain and allow for the configuration of common elements such as the header, tabs, and sidebar.
When creating an experience with any of these records the steps are exactly the same as the creation start with the UX Application record and then with the UX App Config record.
The UX Application record has the App Shell UI field is set to Portal App Shell. The Admin panel field holds the UX App Configuration record created. Both of these records are needed for an experience to be visible in UI Builder. Note: UX Page Property records are not created automatically when utilizing this method until the settings have toggled in Experience settings in UI Builder, and even then the JSON object has to be defined.
No pages are shipped with this method, I've created a page to display the experience. The header is visible, but no menu items have been configured. The experience settings allow for the toggling of a Navigation Menu, Primary Footer, and Secondary Footer but these records will need to be configured as well. The NinjaBytes blog has a great walkthrough of how to configure a portal experience to display how to configure these records as well as a very helpful cheatsheet that displays how UX Page Property records correlate to an experience.
The UX Application record has the App Shell UI field is set to Agent Workspace App Shell. The Admin panel field holds the UX App Configuration record created. Both of these records are needed for an experience to be visible in UI Builder. Note: UX Page Property records are not created automatically when utilizing this method until the settings have toggled in Experience settings in UI Builder, and even then the JSON object has to be defined with the exception of the chrome_toolbar UX Page Property.
No pages are shipped with this method, I've created a page to display the experience. The header is visible, but the sidebar and menu items have not yet been configured.
Note: The chrome_toolbar UX Page Property is shipped with the Workspace experience and is visible after the sidebar has been configured Experience settings in UI Builder. For some reason it's configured as type string out-of-the-box which causes it not to render correctly. To fix this, change the type to json. Here's what the experience looks like after fixing the UX Page Property record for chrome_toolbar:
UX Page Properties
I've mentioned these records in the sections above, and wanted to provide a quick summary one the most common ones that developers may need to configure or create. Note: UX Page Properties can be global or page specific, global properties appear on all pages in the experience.
chrome_header: Portal and Workspace, JSON will differ for each.
chrome_toolbar: Workspace Left Navigation/Sidebar
chrome_tab: Workspace Tab Configuration, this is where the record types are defined when creating new records with the +.
chrome_footer: Portal, defines footer items.
chrome_menu: Portal, houses menu items under the header.
There's a lot of terminology out there at the moment regarding what an experience is and how to create one. The Developer site and NowLearning course linked below are excellent resources for anyone starting out with UI Builder, or even those who have been using it in order to gain a better understanding of the architecture. As of the Rome release, there are multiple ways to create an experience and some methods may provide more of a template to work with than others, i.e. App Engine Studio versus Studio. App Engine Studio can be utilized in a PDI for free for those wanting to see what an out-of-the-box experience is shipped with and I recommend launching some of the template apps as well as there is different theming, pages, and event configurations supplied with them.