Best Practices for developing Service Portal in Service now

avinash kumar · ‎12-12-2018

Best Practices for developing Service Portal in Service now

Functional Design Best Practices

A portal should be simple, beautiful, competitive, predictive and leading.
Involve customers from the start
Give the customer what they want to get what IT needs
Commit to Customer centric design principles. The theme , logo , css and other specs related to the view must be aligned with the company/customer’s theme and therefore it is best to involve the company internal designer for these
If it is a new organization, never start building the portal straightaway rather analyze the data and items which are most used.
Paper is cheap, so design all the visual end to end flow on a paper taking the customer’s input.

The most important reason for the portal failure is Poor Navigation. This can be eradicated only when we know the usage and what customer’s need.

Never try to put too many categories or information on single page. Rather the design should be to lead people to things they need.
In each page, we must have the breadcrumb to navigate back to any previous page.
Each page must have a search which would act as a global search. In second phase of the portal development, these searches can be made more specific to the current page. There are multiple types of OOTB widgets available to cater to different searching needs.
The classification of things/ services should be from general to specific leading people to what they would normally need.
We must define a service taxonomy. So if a user is a Non-IT Employee, he would need IT Customer Services. If the user is an IT Employee, he would need IT Internal Services. Similarly, for all the employees there would be shared services. For customer/partners, we would need Line of Business Services.
If a customer needs to order some service or item, he is redirected to the catalog and the interface should always have the option to see the entire catalog on each of the page, unless the customer has reached the desired item.

Technical Design Best Practices:

Basic set-up

Stay closer to OOTB widgets yet little far

When starting a new portal, we should look at the OOTB portal called sp. We must never update anything that is being used inside this portal as any widgets or internal components used inside these will not be upgraded. We need the OOTB features to be upgraded every time to get the best of the latest features and fixes.
So staying little far means that we must clone each of the widgets used inside this portal and append them with the company initial or by any standard naming convention being followed.

Another school of thought recently developing is to make a balance between cloning the OOTB widgets and embedding widgets and use reusable components. These details can be found at the end of the document under developing widgets.

Next step is to create a new portal by cloning the OOTB sp portal. All the changes we apply to this would never be upgraded if we use the cloned widgets.
Now check all the pages which are being rendered by this portal by navigating to each possible links. All these pages are OOTB and need not be touched. Rather, we would create a copy of these pages and use the instances of the cloned widgets on each of these pages.

The problem with cloning the OOTB pages and then editing them is that in many pages the links to other pages are hardcoded, with Kingston release, this has been sorted with the Page Route Map.

Now we also need to apply the company specific CSS. This can be done by applying a CSS include in the Theme being used for the portal. Other than this CSS can be applied at the CSS variables under the theme. Next each page has a page specific CSS. On a more granular level, the widget instances also have the CSS field. Next each widget has the CSS part. And even more, while defining the HTML part of the widget, we can have CSS for every components defined inline. So it is a complete bottom up design and this must be considered for beautiful Portal.
We can use the announcement feature available now to broadcast important announcements. This is available post Kingston.
Redirection and login page configuration can be changed in SPEntryPage script include. There are system properties under this script include which needs to be set properly.
The client script type should be changed to All or Mobile/Portal.

There are many unsupported features with respect to scripting which needs to be checked for and removed or replaced.

Service Portal and client scripts.

Build widgets to replace UI Macros and other unsupported scripts. If using a UI Macro in a catalog item form and referencing values on the form, you can use the following workaround instead.

Replace a Service Catalog form script with a widget.

Simplify any complex forms used in your Service Catalog to fit the Service Portal two-column form layout
Consider which release supports the required functionality. You may want to upgrade your instance before transitioning to ensure that you have the required base system features.
If using CMS previously, we would need to replace the components which are not supported by service portal:

Details are here.

In general, UI Macro, Data lookup, Client side UI Actions, and UI actions with setRedirectURL, Synchronous javascript call like getXMLWait is not supported. Scripted UI policy can only use the supported API for service portal.

UI Page if used inside service catalog variables are not supported.

Expanding and collapsing help text is not supported.

List collector is not shown as slushbucket rather as choice list.

Large Order guides cause performance issues, rather they should be split into multiple smaller order guides.
Make sure to test all the record producers in service portal to ensure that they are working fine.
For shopping cart, the system has an OOTB Shopping cart widget.

The shopping cart is managed by the sc-shopping-cart widget and the angular providers there. Best recommendation is to clone these two as well and replace the instance of them under the cloned page for ‘sc_cart’.

Define your search sources properly to include items that you would need.
If you want users to land to form view instead of the ticket view, check each of the pages like xxx_sc_cat_item and change the line of code in the cloned widget to point to xxx_form page. This can be achived by navigating through all the possible links and checking which widgets are linking to which page.

Besides this, we should use the route-maps. Route maps ensure that even if the url contains a reference to the OOTB page, the system would still open the customized page and widgets and acts as a good fallback technique.

While designing the service catalog form, think mobile first
Service portal renders in 2 column layout and therefore the form view would look different. So while designing the catalog items this must be considered.
We can render a complex form using iframe but this is not advisable.
Domain Separation is not currently fully supported in service portal however the data can be separated and using this the portal can be made look distinct.
Please check the list of all the unsupported features here.
If you want your client script to be compatible with both desktop and mobile, but include behavior that depends on the runtime. You can use this script:

if (window === null)

// Write your mobile compatible code here

else

// Write your desktop compatible code here

For client script check :

Supported client script types and APIs

Unsupported Client script features

User input validation for different types of fields have few changes
If we ever need to create a new widget, we must first search the widget Library. More often than not, we will find some widget which does the work real close and we need to clone the widget and use the cloned one.
In widget, we should use the instance options as much as possible.
If using SSO, we should check not to include login widget on the landing page, otherwise this leads to the loop in redirection.
Search related widgets have been improved and so many old widgets become legacy with each upgrade. We must try to check for all the widgets used and see if there are any better replacements available with newer releases and leverage them.
Logging to console in a widget:

The $scope.data object passes data from the server to the client side controller. Instead of adding console.log messages or alerts into the controller code, you can just log the $scope.data object to the browser console and view the data there.

$scope :

Similar to the $scope.data object, except it logs everything in $scope to the console.

Global Objects in widget

This is a must visit page for developing a widget and understanding the core concepts.

Recommendation for creating a new widget

marcelorsc_1970 · ‎01-19-2023

Thanks for taking the time writing this great article. One thing that is not clear to me is whether or not we should clone the Themes. I see (at least in San Diego), UI Actions for cloning Widgets and Pages but I do not see the same for Themes (not sure if it is intentional or not).

In my own case, it is very likely that I need to add CSS variables to La Jolla based on requirements I am hearing. I am not sure if I should do that directly within the La Jolla Theme record or if the best practice in that case would be to copy the Theme and modify my own copy, this is not very clear for Themes.

Any feedback would be greatly appreciated.