Application StandardsIssue Contents Application Standards Design principlesDesign guidanceCoding standards Design principles Be consistentDo more with lessIterate Design guidance Home Page Widgets Application Bar ApplicationsModules Lists List widthColumn headersField sizesItems to Note Forms Overall design processPerformanceGeneral organizationGeneral usabilitySectionsLabelsText fieldsMultiple select inputsCheck BoxesChoice MenusText area fieldsRelated linksRelated lists Global Interactions Action ButtonsLinksContext actionsSyspopupsHintsAlerts and Messages UI Pages Coding StandardsTables and Columns DeliveryNaming Conventions TablesFieldsDictionary Files Field and Table Attributes Labels Styles Choices Other Noteworthy Attributes Structural Conventions StringsNumbersDates and Times Forms and Lists FormsLists Debugging Application Standards One of the primary benefits of the Service-now.com application suite is the integrated nature of the applications themselves. Incident management feeds into problem management which, in turn, can trigger a change. All three rely on the underlying data in the Configuration Management database (CMDB). However, these applications and many others have been written by different teams, at different times, and sometimes even at different locations. Application design standards exist so that all of these applications, and anything developed in the future, have a predictable look, feel, and set of expected behaviors for the end users. This document has three major sections. Design principles The general philosophy of how to approach designing for the ServiceNow platform. Refer to these before building and maintaining your applications. Design guidance Specific details on how to obtain maximum performance and usability, broken down by platform components and features. Coding standards How to write the code underlying the applications, including both hard and fast rules and good practices. Design principles Be consistent The single most important thing you can do to make your applications easy to use is to conform to what your users expect. When they learn how to use one application, that knowledge should carry through to all the others that they use. Less training required: Users leverage all the knowledge they gain in previous applications, reducing learning time.Fewer errors: The human attention span is limited. Usability studies show users make more mistakes when the interface requires extra effort that isn't directly related to the task at hand. Arbitrary inconsistencies create that overhead.Happier employees: They will feel better using something if it conforms to their expectations, rather than continually being frustrated or annoyed. Do more with less You should aim to make simple tools that handle tasks with the fewest possible functions, fields, words, and lines of code. This has many benefits. Ease of maintenance: There is less code to maintain, fewer features to update, and fewer things to document.Ease of use: People can only handle so much information at any one time. The more you cram into one place, the more likely it is someone will miss something important and make a costly mistake.Speed: Smaller pages mean faster loading, faster rendering, and better use of server resources. Iterate A good practice is to do two rounds of prototypes and validate them with users before committing anything to code. Hash out your ideas cheaply and quickly, and ensure that you are solving problems for your users rather than just assuming you are. Sketch on paper or whiteboard: Make the first pass at low fidelity and run those ideas by people not affiliated with the project. Getting something out of your head and on paper lets you evaluate the core of your idea objectively and quickly.Prototype in a computer program: Mock it up in medium to high fidelity. Walk a few customers through the end-to-end experience to give you constructive feedback—you will avoid many costly pitfalls that way. Be sure to get a representative enough sample, and read between the lines to determine any possible unmet needs, rather than just giving customers what they ask for.)Do the final iteration in code: Begin building when the only items left to implement are small, completely designed details that are working in other applications. Design guidance Home Page Widgets Be careful with home page widgets—they pull a lot of data and require a lot of resources to render and work. They can wreak absolute havoc on performance over the entire instance. Imagine what your server has to deal with when everyone starts up their web browsers at 9:00am every morning.It's better to create several home pages with a few widgets each rather than one with many widgets.Try to focus the different home pages on a single task with a set of coherent widgets. Application Bar Applications Group applications together by roles of the people who use them so they have access to all their tools in one place.Order them to match the sequence people use to do their jobs, from top to bottom.Name them to be as concise and functionally accurate as possible. Here are some good rules to follow: Fit on one line at the default screen size.Don't abbreviate. Full words are easier to find and remember.Use the most familiar terms for application names to make filtering and searching easier.Pick a naming convention and stick to it. Always enter an application hint. These show up when the user points to the application name.Follow all the editorial guidance in the Hints section below. When customizing label colors, always consider usability. Use high contrast. For best results, stick to very dark text on light colors.Use relatively mellow, unsaturated colors. Super bright yellow with black text is visible, but it can overwhelm the information in graphs, forms, and alert messages in the rest of the screen.Make sure the labels are different enough from each other and that they are easily distinguishable at a glance. The idea is to help users decide between their choices easily. If this is new to you, use a tool like the online Color Scheme Designer and choose colors from a Tetrad color scheme. Modules Group modules together by roles of the people who use them so they have access to all their tools in one place.Order them to match the sequence people use to do their jobs, from top to bottom.Name them to be as concise and accurate as possible. Here are some good rules to follow: Fit on one line at the default screen size.Don't abbreviate. Full words are easier to find and remember.Use the most familiar terms for application names to make filtering and searching easier.Pick a naming convention and stick to it. Group modules into sections that allow people to collapse the ones they only rarely interact with. A good guideline is to keep sections down to five to seven modules at most, which is the optimal size for usability.Caution: separators are not 'seen' by the filter, so create meaningful words within the names of the apps and modules themselves. Always enter a module hint. These show up when users point to the application name.Follow all the editorial guidance in the Hints section below. Lists List width Make your lists fit comfortably in the default layout of the instance without horizontal scrolling. If a list needs to be longer for a task, like batch editing from the list view, then make sure the people using it that way are familiar with the UI11 ServiceNow interface and know how to collapse the left pane to create more room. Column headers Use sentence case (only capitalize the first word) for column headers. Field sizes Make the text field size conform to the content that it is being displayed. Text fields truncate to 40 characters by default. That can be overridden with the dictionary entry for a field.Be mindful of why you are overriding-–displaying too little information can be worse than not including the column in the first place because it takes room away from others.Note: Field wrapping is off by default, but can be overridden by a user preference, so be aware that things can and will display differently sometimes. Items to Note The first field of a list or related list should never be a reference field. The system automatically creates a link to the record on the first available display field. If you use a reference field first, then the link will be in the second column, which is confusing and inconsistent. Don't list columns that are predominately blank if you can avoid it.Don't use journal, muli-line text, or html fields in lists. Those styles of fields act strangely in list layouts and fail in various ways that hurt usability or even the visibility of the content. Stick to the other types for maximum compatibility and robustness of the information display. Forms Overall design process Understand your users and build the apps around them. It's easy to build tools that people don't actually find useful. Avoid this by paying attention to your users' needs. Structure forms for best performance. Subtle design decisions can result in vast differences in speed, bandwidth use, and user productivity. Design forms to optimize usability. Pay attention to all the details—field arrangement, labels, naming conventions, and overall consistency. Performance The form should load in under one second, if possible. Human factors research shows that anything over that has a substantial impact on usability—including in task completion, error rates, and overall user satisfaction. Create form views optimized for each role. Only show the fields they really need. The more you cut, the faster your overall ServiceNow performance. Be careful with how you use client scripts. For information processing, favor server processing with AJAX calls over intense client-side processing.For user interface, use designated client-side Application Programming Interfaces (APIs) and minimize the use of client scripts that rely on specific HTML/CSS details. Minimize the use of UI policies. If you find yourself needing to show/hide large chunks, create separate form views for the different roles. Be careful about how many related lists you attach. Long lists create a lot of additional latency in the form load. Do not use synchronous calls back to the server on a form load. Those multiply the effects of any natural latency in the dependencies being touched when the form loads. When sensible, use session caching to speed up form reloads. This creates security issues, so be careful what content you use it on. General organization Group related fields together. People should be able to accomplish a given task within one section rather than skipping around. Arrange fields in order of importance. Stack closely related fields vertically so that it is easy to scan and tab through. Keep fields in the same location across forms. Keep them in the same column, whether left or right, in the same general position or section on the form, and in sections with the same name.The more widely used the field, the more important this rule becomes. For example, in an Information Technology Infrastructure Library (ITIL) application, the Number, Name, and Assigned To fields should be in the top left on every form. Balance columns so that there are an equal number of fields on each column. Exception: If the entire form is visible on a user's monitor when it is set to the default screen resolution, then you can put them in one column. General usability Group related fields together. Make it so people can glance at one place to ascertain the status of a certain type of work. Group mandatory fields together when possible. Keep them together so a user doesn't have to scroll off screen or dig around in multiple seconds to perform a mandatory task. Minimize mandatory fields. Every single one adds to a minimum amount of overhead to complete a task. Past a certain point, the overhead can be so much that users will actually avoid filling out the form in the first place. You need to balance your need for information integrity with ease of use. Minimize the number of fields overall. A shorter form is easier to learn, easier to use, and has faster performance in every way. The more fields you have, the more you risk fields having overlapping meanings or functions, which increases user mistakes. Sections Cluster associated fields into sections. The best way to use them is to break the screen up into subheads that allow people to scan the form quickly and zero in on the type of information they need to fill in quickly.Ideally, each section should represent a stage in the life of a task that the form represents, so that it's easy to see what needs to be done next at a glance. Name and order your sections consistently across forms. Again, consistency creates repetition, which creates ease of use. Labels Labels should be terse and meaningful. This helps with usability and use of space.Cut redundant words—instead of Update Form, just use Update since you are already on a form.Cut definite articles like the. For example, instead of Accept the Solution, use Accept Solution. Labels should not wrap at the minimum screen size. For long individual labels, try pulling some of the information into a hint.For sets of labels with long, duplicated content, try pulling those labels into their own section and making the shared words part of the subhead.If they still wrap, they will be workable, but it creates noise and hinders scannability. Use sentence case for label text. Capitalize only the first letter in the label.Make exceptions for proper nouns and the like. Labels should be consistent across all forms, applications, and platforms. Standardize: Your users will navigate your applications much more quickly if the same type of information is managed the same way everywhere. Text fields Text field lengths should match the length of the data entered. Highly variable information—names, addresses, and the like—should get a full row.Shorter, predictable data, such as zip codes or states, should have fields sized exactly to fit.Long entries of information, such as work notes, should be sized generously so that users have plenty of room to write. Text field lengths should be consistent across all forms, applications, and platforms. Standardize: For example, in the case of zip codes, use the same field length and strategy for handling Zip+4 everywhere. It creates more regular data and a better user experience. Multiple select inputs Multiple select fields are useful to gather data that will be more powerful later on if it's captured in a predictable form. For example, Priority can be reasonably assumed to have High, Moderate, and Low values. By creating standardized fields like this, you are able to extract metrics in a meaningful way. Radio buttons are good in that they expose all the information needed to make a decision in a readable format. Stack them vertically when the decision between two or three paths requires a significant amount of content that needs to be clarified.Format them inline for Yes/No style choices, especially in long lists like a survey. Choice list menus are useful mostly for saving space. Use them when exposing the entire list would take up too much screen space, especially if it helps you better organize the form.Be careful not to make them too long. If a list is so long that it goes off the bottom of the screen, it will make frequently-used choice lists incredibly slow and difficult to use. Find another way to handle the problem, such as breaking the list up into different widgets. Check Boxes Keep these together in one column. This allows users to visually scan all the choices quickly and easily. When possible, keep check box fields in the right column. This is a purely visual design suggestion. Check boxes take up less space and carry less visual weight than a full field. The form looks better if all the check boxes are on the right and there is not a significant gap of white space between the columns. Choice Menus Use title case—Every Significant Word is Capitalized.Be mindful of the default state of input menus. Generally, it is good practice to make the default choice in a menu the none value, so that if it is missed, saving the form won't automatically enter bad data.In that case, use Choose… as the default text. The ellipsis (…) indicates that there is more information to be found afterwards and is standard on operating system menus.If a menu defaults to data, be sure that you are making that choice in a way that minimizes the user's work if they proceed with the default. Size the menus to fit the data. Never truncate the text of menu choices. Make sure the menu is sized appropriately. Text area fields Group these together at the end of the other entry fields when possible. These are for long content entry, so they need to be sized generously. Give them the full width of the form in most cases. For these types of inputs, too big is better than too small. Size them in consistent multiples of lines. For example, if you must make them different sizes, use a consistent pattern like 2 lines, 4 lines, 6 lines. This creates a more predictable and aesthetic layout. Place text area fields into full-width columns. You can put them into half-width columns, but this tends to create other problems.For example, resizing one doesn't resize the other one automatically, causing the look and feel to be inconsistent.Additionally, many web browsers, like Safari and Chrome, offer the ability to resize text area fields, which overrides any controls we provide. Users could conceivably make the field in the left hand column so wide, it pushes around the content in the other columns. It is best to avoid the issue entirely and give them full columns. Related links Keep this area organized for the best usability. It has no innate structure, so take the time to make one and stick to it across different forms. A good practice is to keep the same order as default lists whenever possible, which lets users leverage their previous knowledge and familiarity with the system.Group like items together when possible. Keep link names short and to the point. Like button names, take out as many words as possible.Use sentence case, but don't use sentence punctuation. Keep related links consistent across forms and applications. Related lists Keep this area small for the best performance. Use as few entries and columns as possible. When the form loads, it needs to retrieve all related lists, and this process can add so much latency that the form can become unresponsive and appear to freeze for several seconds. The first field of a list or related list should never be a reference field. If you use a reference field first, then the link to the actual record will be in the second or even another column, which is confusing and inconsistent with the way lists usually work. Keep the record as the first link. When replicating lists found elsewhere, replicate them faithfully. Keep the same column order, number of columns, etc. so users' memory and recognition help them parse the information quickly. When using a list to showcase a different form of data, eliminate all unnecessary columns. For example, if you want to highlight only the P1/2/3 status of the records, don't hesitate to eliminate all other columns.This will increase performance on the back end and in the user interface because there is less extraneous information to wade through. Keep the order of these lists consistent across forms and applications. Pick a sorting scheme and stick to it across your entire instance. The more predictable and familiar to users it is, the better. Global Interactions Action Buttons Use buttons for things that actually change the state or data in the form. These indicate work was done, such as changing the owner, editing, closing, etc. Keep the number of actions on each form down to a reasonable number. Three to four actions are best from a usability perspective. Aim for five at a maximum.Any more than that and it gets much harder to find and remember them. Use title case.Make the names as short and meaningful as possible. This helps with user-friendliness and use of space.Cut redundant words. Instead of Update Form, just use Update since you are already on a form.Cut definite articles like the. Links Use links to navigate to supplemental content that exists outside the form or content that you are working in now. Links from or to applications, such as lists or forms, should pop into new web browser windows, so that the state of the form is not lost.Links inside content sites, such as Wiki or Knowledge articles, should link within the same window. Context actions Use context actions to perform more advanced filtering, sorting, or other actions that drill down into the information that is currently selected.Use as few context actions as possible. Currently, context actions are difficult to find. We are investigating methods for making them more visible, but until then, make those commands always-visible whenever possible. Syspopups Use Syspopups to provide contextual form data that would otherwise demand a full round-trip to another form. Edit the popup to show the minimum necessary information.The default is identical to the current view.Smaller views load and display faster. Hints Use them to provide contextual help for the type of information users need to provide. Don't just repeat the label—give them information they wouldn't know otherwise.Field-level hints are mandatory.Application and module hints are optional, but should always be used. Keep them short and essential. They work best as short declarative statements—they don't need to be full sentences.Do not use punctuation at the end of a single sentence. The exception is when there are multiple sentences, but that typically indicates redundancy and should be avoided. Use sentence case. Capitalize only the first word or proper nouns within the phrase.Don't make them full sentences. The extra words and puncutuation aren't necessary. Keep them consistent. Pay attention to the length, voice, tone, and word choice across all the notes.Keep the hints for similar labels the same across forms and applications. Do not use a definite or indefinite article as the first word: A DNS name of this device, if resolvable (Incorrect)DNS name of this device, if resolvable (Correct) Alerts and Messages Keep them short and essential. They work best as short declarative statements—they don't need to be full sentences.Do not use punctuation at the end of a single sentence. The exception is when there are multiple sentences, but that typically indicates redundancy and should be avoided. Use sentence case. Capitalize only the first word or proper nouns within the phrase. Do not start messages with Please.Use {0}, {1}, etc. replacements in the messages to ensure that proper translation is possible. UI Pages UI Pages are basically a blank slate that allow you to completely change the user interface to whatever you want.Since there are no specifics built in already, the only design advice we can use is to not use them unless you have exhausted all other options within the ServiceNow platform. Here's why: Updates can break things, sometimes badly. Whenever ServiceNow rolls out a new update, apps built with the platform update automatically. One-off features built using other technology do not update automatically, which can break it completely until you perform extensive work. Maintenance time and cost increases. Even if nothing breaks outright, ServiceNow may make improvements that don't propagate. For example, in a new UI, ServiceNow refreshes the visual style, which means that you will have to implement those improvements to your apps separately. There may also be improvements to our widgets that you won't get at all. For example, much better type-ahead prediction in search fields. Inconsistencies creep into the user experience. When building something with the ServiceNow platform, a given widget has a lot of extra capabilities that go along with it. If you add a widget with another technology that looks the same, it won't necessarily have those benefits, so if you don't take the time to make them work the same way, you'll have similar looking controls that do different things depending on where the user is. Those problems degrade usability and ultimately erode a user's trust and confidence. You may duplicate work that is being launched in the next release. Sometimes, the platform gets you 80% of the way there, and by building an interface using UI pages, you get exactly what you want. However, you may invest a lot of time and hours to build it, only for ServiceNow to release the exact same functionality in the next version. There's no easy answer to this one, because it comes down to a cost/benefit analysis—just be wary of spending a lot of time on an incremental improvement. UI pages are there for a reason—sometimes it's necessary to integrate new tools in ways the platform doesn't support. ServiceNow advises that you make make sure you need them before you build them. Use UI pages for focused, lasting departures from the platform. Creating radically different information visualization. For example, one Innovator of the Year award was given to a customer that mapped their assets onto a fully interactive, browse-able floor plan. It provides functionality in a way that's a major enhancement over and above what ServiceNow currently offers, and isn't likely to be obsoleted soon.Creating an industry-specific interface. The current ServiceNow interface, driven by forms and lists, can solve a great many problems, but you may be able to complete a common task much more efficiently with a radically different front end. In that case, it can be worth the ongoing investment. Coding Standards Tables and Columns Delivery Tables are to be distributed as .xml files in a plugin directory. Naming Conventions Tables A table name should not exceed 30 characters.Table names are defined in all lower case with '_' instead of spaces. For example, my_table_name.Tables with a common purpose should share a common prefix. The following prefixes are reserved: sys_ -> system tablessys -> deprecated for use in system tables. Use sys_.cmn_ -> common tables like cmn_company or cmn_departmentu_ -> user tables. No ServiceNow table should ever ship with this prefix. Fields Field names should not exceed 30 characters.Field names are defined in all lower case with '_' instead of spaces. For example, my_field_name.Field names should represent their purpose. For example, caller_id or assigned_to are appropriate—user1 and user2 are not.When using a common logical field, use the appropriate field name. name—name of a thingdescription—description of sameorder—sequence of thingscomments—comments or self documentation on a table Dictionary Files A table is distributed in an .xml file with the same name as the table. For example, my_new_table -> my_new_table.xml.Only one table per .xml file. Field and Table Attributes Labels By default, the label for a field specified in a table's XML will be generated based on its name. The label is generated by replacing underscores with spaces and formatting the words in sentence case. For example, a name of incident_state would lead to a label of Incident state. Use the label attribute only when necessary. Below, the desired label for num_chunks and num_consistent_chunks did not match the name. <?xml version="1.0" encoding="UTF-8"?> <database> <element label="Table Check" name="sys_table_check" type="collection"> <element name="table_name" /> <element label="Master chunks" name="num_chunks" type="integer" /> <element label="Consistent chunks" name="num_consistent_chunks" type="integer" /> <element name="target_database" reference="sys_ha_database" type="reference"/> Styles Field styles should be specified within the element definition in the table's .xml. Note that light green and tomato are the preferred replacements for green and red, respectively. See below for syntax. <element name="state" choice="1" default_value="1"> <choice> <element value="awaiting_master_check" sequence="1" label="Awaiting Master Check" /> <element value="checking_master" sequence="2" label="Checking Master" /> <element value="waiting_on_replicator" sequence="3" label="Waiting On Replicator" /> <element value="checking_replica" sequence="4" label="Checking Replica" /> <element value="consistent" sequence="5" label="Consistent" /> <element value="inconsistent" sequence="6" label="Inconsistent" /> </choice> <style> <element value="consistent" style="background-color:lightgreen"/> <element value="inconsistent" style="background-color:tomato"/> </style> </element> Choices Choices for fields should be specified directly in the table definition. See example syntax below: <element name="state" choice="1" default_value="1"> <choice> <element value="awaiting_master_check" sequence="1" label="Awaiting Master Check" /> <element value="checking_master" sequence="2" label="Checking Master" /> <element value="waiting_on_replicator" sequence="3" label="Waiting On Replicator" /> <element value="checking_replica" sequence="4" label="Checking Replica" /> <element value="consistent" sequence="5" label="Consistent" /> <element value="inconsistent" sequence="6" label="Inconsistent" /> </choice> </element> Other Noteworthy Attributes Unless blindingly obvious, all fields need a hint attribute.The use of calculated fields is highly discouraged.The choice attribute for choice fields should be set to one of the following: choice="1" (Dropdown without—None—(must specify a default value))choice="2" (Suggestion)choice="3" (Dropdown with—None—) Structural Conventions Do not replicate core fields. There is already a sys_created_on field. Do not add your own timestamp.Use the appropriate type for storage. A date can be stored in a string field, but it ought not to be, nor should a number. Strings Unless there's a compelling reason, such as storing 2-letter state codes, all string fields must have a length of either: 40—system default80—long single line text255—small multi-line field4000—medium multi-line fieldxxlarge—large (Character Large Object (CLOB)) fields Numbers Use the simplest number type possible for a particular data field. If integer will work, use it instead of decimal. Dates and Times glide_date_time—a timestamp e.g. 12:34:56 on December 25, 2010glide_date—a date e.g. July 4glide_time—a time of day e.g. 4:00 PMglide_duration—a span of time e.g. 4 hours Forms and Lists Forms Every table needs default form, even if there's no direct link to it on the UI. Lists Every table needs a default list, even if there's no direct link to it on the UI. Debugging Use properties to control debug features. This prevents users from having to modify a script to enable debugging. //get debug state from property var debug = gs.getProperty("com.snc.my_app.debug", false); if (debug) gs.print("My app just did this"); If you plan on having a lot of debug output, only write to the console, not the log table. Advise users to run the Debug Log module to see the output.