Service Portal Stories: Tips for Success (part 2)
Today I’m going to continue our conversation on some best practices for writing agile stories to cover the design and development of Service Portals on the ServiceNow platform. In part one, we looked at some general areas to cover when gathering requirements for Service Portal projects and what information to include in your stories. In part two, we’ll take a look at the art of dividing up the work.
General Guidelines
Just as we do with all other stories used to guide implementations in a ServiceNow instance, Service Portal work should be divided to ensure continuous progress. In general, I follow these four guidelines:
Ever heard the phrase “Too many cooks in the kitchen?” Keep your “kitchen staff” focused. Changes to any given record, be it the theme, a widget, or a page, is confined to the lowest number of update sets possible, to avoid conflicts in migration. For example, try to avoid multiple stories that make changes to a single widget or even page.
Ensure the work is specific enough to be completed. Your assigned team member should be able to reasonably estimate the level of effort for the work contained in the story. If the requirements are too vague to evaluate, you run risk that the work will not be completed on time or missing some important details.
Don’t bite off more than you can chew. Properly size the work requirements in a single story to ensure that the work can reasonably be completed within a two-week sprint. In the past I’ve seen stories that are meant to encompass all work on the Service Portal, with little to no details regarding actual changes and requirements. Don’t do that. Whether the requirements are functional or visual, details should be clear and reasonably contained.
Each story should be distinct and substantial. The work requirements in a single story should not be so small that it can reasonably be included as a part of a larger story’s requirements. For example, I was once given a story that required that all buttons be a given color in the portal. This requirement should be implemented as a part of a theming story rather than as a standalone effort.
Generally, I find that breaking up the work in this manner keeps things well organized. This approach will serve you well when setting up stories for both design and development activities. Best practices here tend to be situational, but most projects that are not completely custom solutions tend to break down into some fairly predictable areas.
Stories for Design Activities
Development on the portal can’t (or shouldn’t at least) begin in earnest until the developers have stakeholder-approved design guidelines to follow, so the first stories you write should capture the requirements for the designer’s work. I divide stories for design activities into three categories:
Wireframes
Mock-ups
Theme / style guide
The first two items will make up the bulk of the stories you create for the design work. Ideally, your designer has the project time to engage your stakeholders for both wireframes and mock-ups, with time for at least one round of revisions at each stage (as always, it depends on your project scope and time allotted as to how much your designer will be able to do).
At the beginning of each of these phases, have stories that will collectively cover all of the design work done. You will want a separate set of stories for both wireframes and mock-ups. For revisions, while you can have separate stories, I usually just add revisions as feedback provided in the main wireframe or mock-up stories (using the worknotes feature provides a great record of suggested changes). This way, you can easily track the progress of design work the same way you track development.
Within each set of stories, I usually divide up the work to broadly follow the guidelines above. In general, one story should cover one page of content in the portal. For example, if your project scope is pretty standard, you may have the following stories for an Employee Center implementation:
Wireframes: Homepage
Wireframes: Topic page
Wireframes: KB Article view page
Wireframes: Standard Ticket page
Mock-ups: Homepage
Mock-ups: Topic page
Mock-ups: KB Article page
Mock-ups: Standard Ticket page.
Each of these stories should note any requirements related to the page that can be depicted visually, including information to be displayed, use cases and dynamic states, as well as visual design. I like to include notes in my mock-ups pointing out particular design choices to my developers (in addition to placing these in the story as well), such as hover states, SCSS variables used, animations, etc.
If your project includes custom functionality, make sure there are mock-ups to reflect that work as well. This may be included in the above stories (if say, there’s a custom widget placed on the homepage), but you want to be extra careful to ensure the design reflects all of the possible use cases and requirements expected. Some widgets or applications requiring extensive mock-ups to cover use cases, views, and other “moving parts” might be better served with their own story, in keeping with the idea that individual stories need to be appropriately sized.
Notice above that I didn’t include stories for every single page that can be accessed by the user. You want to focus your designer’s efforts on the pages that will require configuration by your development team. For example, if you confirmed during your workshops that the portal will use the out-of-box login page, there may be no need to provide a full mock-up. So then, how do we ensure that all of these standard pages are properly configured to align with the overall design? In addition to your stories regarding the specific pages, I recommend your designer put together a theme or style guide for the portal. This can be as extensive or simple as time and requirements demand. At a minimum though, make sure the designer lays out standard styles for links, buttons, panels, colors, and assignment of colors to common SCSS variables. Depending on the project needs, they may also need to provide standardized guidance on tabs, lists, carousels, accordions, and other common elements.
After your designs have been fully approved by project stakeholders, ensure all of the relevant development stories include the requirements laid out in the mock-ups / design as well as either attached PDFs of the design, or (even better) active links to the design files. Your architect may have already fleshed out some of the technical details and even a technical approach to complete the work, but may need to refine the details of the story to include any particular information coming from the established design.
Development & Configuration Stories
At this point in the game, you have designs approved, requirements gathered, and now you have to prepare stories so your developers can DO THE THING. I will note that every project is different, and every development team is different. So while I won’t call this the gospel truth, here’s how I like to see Service Portal work divided up:
Core configuration
This story or set of stories should be completed early, if not first. From here, the development team should be able to set up the main portal data so that all other portal development can be executed without issue.
There are two main ways you can tackle core configuration stories. One, is to have the stories handle creation of related items, such as new custom pages for the settings in the portal record. In this case, those related items you created can still be configured and refined in separate stories. The second (and honestly my preferred method), is to assume that certain core configurations will pass through multiple hands (for instance, there’s no telling when you’ll have to go back and tweak some code in the theme). Either way, managing the order of your updates for these records has to be handled precisely, else you risk overriding one developer’s work with another. The best way I’ve found to handle this is to batch the update sets related to portal work, ensuring all updates to those core records are implemented in order.
For core configuration, my story list tends to include the following:
Portal record configuration:
Set all main pages for the portal if different from default. If custom pages need to be created, this can be the story that covers creation (NOT configuration or customization) of those pages so they can be set properly for the portal. See above.
Set URL slug
Set logo / favicon (you did get these assets from the client, didn’t you?)
Set and configure search sources. If your portal includes more extensive or specific updates to AI Search or integration of custom search sources (like SharePoint), you may want to split this one off into its own story.
Set menu
Set other fields: any other fields or configurations that need to be made here
Theme and branding:
This is where the rubber meets the road for the visual design. Put your most CSS-savvy developer on this story, and let them take the reins for setting up the majority of the styles used throughout the portal:
Theme record: Assign a theme to the portal record, using an existing theme or creating your own.
Header & Footer: Assign a header and footer to the theme.
SCSS variables: Set up or adjust the SCSS variables your team will use throughout the portal.
Fonts: If custom fonts will be used, create the CSS includes and CSS styles to set up the theme’s typography.
Custom styles and functionality: Use CSS and JavaScript includes to set up thematic styles, such as for hover effects, links, buttons, breadcrumbs, etc.
Portal Content Configuration
Once the core configuration is in place, your developers can get to work implementing the rest of the content and functionality needed for your Service Portal. Note that some of these stories will require touching core configuration records, so again, be careful about how you order those update sets.
The below list are stories I typically use to divide up work, with the objective of allowing developers to work independently and concurrently as much as possible, so as not to bottleneck the workload.
Search sources and AI Search configuration:
Whether you’re using AI Search or the legacy search sources, this story can include setup of integrated external sources, configuration of the search results page facets and templates, icons assigned to search sources, and internal sources your users have access to. This could be considered a part of core configuration, but this can be completed independently without interfering with other development efforts.
Header: If there are any customizations to the header, set this aside in a separate story. Header development is murder and deserves it’s own tracked effort apart from the taxonomy and menus.
Footer: This should include the configuration of an employee center footer or creation of a custom footer.
Menus and Navigation: This includes the set up of the Service Portal navigation menu. This should not include the set up of the Unified Taxonomy, but any other menu items needed, including information about where the link opens, role restrictions to access or viewership of this link, order in the menu, etc. (Note: With the release of Advanced Portal Navigation, we now have way more flexibility as to how the taxonomy menu is ordered alongside other menu items.)
Unified Taxonomy: If you’re building an Employee Center portal, it’s important to separate the building of the taxonomy from other work. The story should dictate to the developer how they should set up the taxonomy with a complete list of topics, sub, topics, descriptions, images, and icons. This story should only cover the creation of the taxonomy, topics, and subtopics, not the addition of Connected Content.
Taxonomy Connected Content: Moving connected content from one instance to another is an annoying, messy process. Content should be added only after all edits to the included SC and KB items have been made, so make this one of the last stories completed. If changes are made to the content item after the item is added to the taxonomy, the connected content could override those additional changes.
Virtual Agent branding: Branding for the Virtual Agent is handled in a completely different place than most branding in the Service Portal, and deserves its own separate story.
Tours: These are especially useful when introducing your end users to a new portal experience or even new features for the first time.
Service Portal pages:
Many of your stories will fall under this category, as a whole page or part of one.
Simple pages: Stories of this type capture the requirements needed on an entire page, when the page in question has minimal changes to make. For example, if you’re using the OOB profile page, and only need to tweak the thematic styles to ensure the UI falls in line with the design intent, one story can encapsulate this effort. At the very least, each page visible to the end user should have a story like this, to ensure the UI is properly aligned to the design intent; this shows the stakeholders that each page in the portal has been given due consideration during implementation.
Complex pages: Some pages will require substantial effort that may need to be further broken down. The homepage is a good example of this. In this case, I tend to break up a portal page into stories according to the following:
Page creation and layout: Includes creation of the page, setup of containers, columns & rows, and placement of OOB widgets that require little to no individual configuration or styling.
Individual widgets / sections: For every widget or section that will require moderate to substantial configuration, set up a separate story. The “My Items” widget in the EC Portal is a great example of this, as the configurations for this widget can sometimes get pretty involved.
To get you started on page stories, here’s a list of pages I typically add to my story list:
Complex pages:
Homepage (complexity dependent on use of non-OOB widgets and configurations needed)
EC Topics (this may be multiple stories depending on differing topic templates / setups)
My Tasks (configurations and custom widgets for different task types can make this page more complex)
Simple pages:
SC Item View
Service Catalog Browse
User Profile
My Favorites
My Requests (though, I do see a number of clients requesting additions to this page to showcase different types of information)
Service Catalog Home
KB Home
Knowledge Base Category / Browse
Knowledge Base Article View
Conclusion
I hope this two-part series has been helpful in getting you started in writing stories specific to Service Portal. Many times, even as a regular developer, I’ve had to help write, or write entirely, the stories from which I would work, and these two articles contain many of my “lessons learned”. The work can be handily divided up into meaningful stories that accurately capture the requirements and track the work needed for implementation, ensuring a smooth development cycle for your team.