Service Portal Development Guidelines

[Eliza]

At its core working with Service Portal is a front-end development project. You weave together the HTML, CSS, and AngularJS to result in a beautiful, actionable surface for your users to interact with.

While the result may be impressive, it is important to ensure that the foundations are sound also. Following the guidelines in this article whilst developing your Service Portal will benefit your implementation in four key areas:

• Maintainability
• Flexibility
• Reusability
• Performance

Guidelines

1. Always examine existing widgets and community solutions before building from scratch
   • Service Portal has a lot of great developers, and leveraging their code can save you both time and energy.
     
     
2. Make use of script includes and build everything as an API
   • Take data related activities out of the server script and instead place them in a script include with a clear, meaningful name.
   • This results in:
     • A simplified, self-documenting Server Script
     • Makes the code within the script includes reusable across multiple widgets (and scripted REST endpoints)
     • A single place to update code if the data model changes
       
       

3. Give CSS classes specific names
   • It is important to note that a widget’s CSS can never affect another widget. This is because the CSS ServiceNow sends to be rendered actually adds “.v” + the widget’s sysID to each class name for the widget. For example, you may have a widget that looks like this:

3. • The widget uses the class named “alert” to style it. However, what is actually rendered is below:

• This doesn’t mean you are free to name widget CSS anything – you are still subject to inheritance. If a parent CSS record (e.g. in a theme or external CSS library) contains a class named “alert”, your widget may use those styles and end up with an interesting look and feel.
• See below for an example of specific names for an alert box:

4. Use SASS variables to define consistent variables
   • SASS variables are variables that you can define and use anywhere in your CSS.
   • This works well for maintaining things like padding values, colours, font sizes and other items that are shared across multiple components.
   • Using SASS variables will result in the creation of truly reusable widgets – you can then share your widget across multiple portals with only values in the portal’s theme having to be updated.
   • It is important to note that it works based on specificity – the more “specific” definition will be used. Noting the graphic below, an overlapping variable declared at the page level will take precedent of one defined at the theme level.

• Note: You can use SASS !default values to define default stylings for particular items. This means that we are allowing for the value to get set anywhere higher up the hierarchy, but if it doesn’t get set we apply the default value.

5. Use Demo Data and the Previewer to test your widget
   • This feature is available within the Service Portal Designer and can be used to expedite the widget creation and testing process.
   • To use, open your widget in the Widget Editor tool then:
     1. Select the hamburger menu
     2. Select “Enable Preview"
     3. Click on the eye icon
     4. Select “Demo Data (JSON)” and populate the tab that opens

Example:

6. Avoid accessing “Globals”
   • Avoid using global JavaScript objects such as setTimeout, setInterval, window.location etc as this makes maintaining and debugging difficult due to their mutability.
   • Angular uses dependency injection to remove the need to rely on Globals.
   • If there’s one not available, wrap it in a service layer.
   • Note the below dependencies injected through the Client script’s parameters.

7. Link vs Controller

• The Client Script (our controller) can occasionally run before the widget is loaded on the page, so if you try to use it to manipulate the DOM within this script you may face issues.
• Due to this, it is best practice to:

1.      Write business logic in the Client Script (controller)
2.      Perform your DOM manipulation within the Link function

• Listen for scope values to change in the Link function
• The Link function doesn’t implicitly get dependencies, so you can use $injector.get() to fetch any dependencies you require e.g. var $document = $injector.get(‘$document’);
  
  

8. Keep a separate application for the user interface
   • Keep your Service Portal within its own application scope as it decouples it from other applications, making it easier to publish changes.
   • One caveat is that this may increase the difficulty of managing embedded widgets due to cross-scope permissions.
   • An example that follows this guideline is the CSM Service Portal.
     
     
9. Use gs.getProperty() for configuration values
   • Using gs.getProperty() allows for you to set a default value in the case that the configuration values you are trying to get doesn’t exist, or has changed.
   • You can only use this call within the Server Script, but can pass the value to the Client Script via the data object.

10. Use getDisplayValue() to get field values
    • When dot-walking to get a value from a field, consider using getDisplayValue(). This function retrieves the value of whatever is defined as the display value and reduces the number of database queries required, thus improving the performance of your page load.
      
      
11. If custom styling is required, explore embedding your widget within another
    • In order for widgets to receive updates from ServiceNow, they must remain Out of the Box (OOTB), i.e., the code should not be changed, which is why they are made to be “read only”. You can configure them by setting widget options, but nothing else.
    • To enable you to adjust the styling of your widget, you can embed them within another widget that contains your custom styling. The widget within will inherit that styling, but will maintain OOTB status and thus can still be updated.
    • Note that this method cannot be used to update any functionality within your widget – for that you will have to create a clone of the OOTB widget and customize it.
    • Alternatively, one can also individually style their widget by using instance level CSS.
      
      
12. Use Event Services to broadcast events
    • If you need to communicate that something has occurred, use AngularJS’s event services to broadcast the fact. If you need to transmit data with the event, investigate using an Angular Provider (service) instead.
    • This can be used to communicate with other widgets on the page.
      
      
13. Employ tactics to make your custom widgets easily configurable
    • Define widget options using  the widget editor – they allow for low/no-code admins to edit the widget, but you are limited to simple field types. An example of widget options is seen below:

• You can also expand upon this by extending the SP instance table and setting it up so that each time your custom widget is added to a page it creates a record in your new table. The benefits of this is that you can:

1. Add fields that use the ServiceNow field types
2. Incorporate UI Policies
3. Perform data validation on fields
4. Use client scripts

• Once the extended table is created, you then navigate to the widget record itself and select the data table to be your new table, and then which fields are to be presented as widget options:

14. Use $location.search() to change pages
    • Service Portal is a single page app, which means if you use $window.location.href, the entire page will reload and users may see a loading screen.
    • If using $location.search(), only the parts of the page that have changed should be loaded in – e.g. your header and footer shouldn’t be reloaded each time someone navigates to a new page.
    • Example: $location.search({

id: ‘ticket’

});

15. Use one-time bindings by default
    • Angular sets up “watchers” for each occurrence of data binding to a variable on the $scope object, which can cause performance issues.
    • Examples of when a “watcher” is created are when you call <h1> {{c.incident.number}}</h1> or $scope.$watch().
    • To remedy this, use one-time bindings where data doesn’t need to be dynamically updated: <h1> {{::c.incident.number}}</h1>
      
      
16. Use Content Publishing to deliver relevant content to users
    • Note: this feature is only available to those with an Employee Center Pro license
    • You can target the delivery of content to particular users using the Content Publishing plugin.
    • It is a no-code experience so that non-technical users can deliver content to their audiences without involving a developer.
      
      
17. Use Visual Studio Code
    • We have an integration with Visual Studio Code (VS Code) that allows for developers to edit code within their integrated development environment (IDE).
    • Can improve code hygiene with the various plugins available for VS Code.
    • The tabbed layout makes it easier for developers to work with multiple files e.g. a widget’s server script and the script include it calls.
    • You can also create and run background scripts within VS Code directly.
18. Follow a mobile-first approach
    • Design for a mobile device first, then add media queries and overrides for larger screens afterwards.
    • Code for larger screens is typically more complex, so focusing on mobile devices as a foundation generally results in simpler code.