Application Standards


Description

Contents
  1. Application Standards
    1. Design principles
    2. Design guidance
    3. Coding standards
  2. Design principles
    1. Be consistent
    2. Do more with less
    3. Iterate
  3. Design guidance
    1. Home Page
      1. Widgets
    2. Application Bar
      1. Applications
      2. Modules
    3. Lists
      1. List width
      2. Column headers
      3. Field sizes
      4. Items to Note
    4. Forms
      1. Overall design process
      2. Performance
      3. General organization
      4. General usability
      5. Sections
      6. Labels
      7. Text fields
      8. Multiple select inputs
      9. Check Boxes
      10. Choice Menus
      11. Text area fields
      12. Related links
      13. Related lists
    5. Global Interactions
      1. Action Buttons
      2. Links
      3. Context actions
      4. Syspopups
      5. Hints
      6. Alerts and Messages
      7. UI Pages
  4. Coding Standards
  5. Tables and Columns
    1. Delivery
    2. Naming Conventions
      1. Tables
      2. Fields
      3. Dictionary Files
    3. Field and Table Attributes
      1. Labels
      2. Styles
      3. Choices
      4. Other Noteworthy Attributes
    4. Structural Conventions
      1. Strings
      2. Numbers
      3. Dates and Times
  6. Forms and Lists
    1. Forms
    2. Lists
  7. 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.

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.

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.

Design guidance

Home Page

Widgets

Application Bar

Applications

Modules

Lists

List width

Column headers

Use sentence case (only capitalize the first word) for column headers.

Field sizes

Items to Note

Forms

Overall design process

Performance

General organization

General usability

Sections

Name and order your sections consistently across forms.

Labels

Text fields

Text field lengths should match the length of the data entered.

Text field lengths should be consistent across all forms, applications, and platforms.

Multiple select inputs

Check Boxes

Choice Menus

Text area fields

Related links

Related lists

Global Interactions

Action Buttons

Links

Context actions

Syspopups

Hints

Alerts and Messages

UI Pages

Coding Standards

Tables and Columns

Delivery

Tables are to be distributed as .xml files in a plugin directory.

Naming Conventions

Tables

  1. A table name should not exceed 30 characters.
  2. Table names are defined in all lower case with '_' instead of spaces. For example, my_table_name.
  3. Tables with a common purpose should share a common prefix.

The following prefixes are reserved:

Fields

  1. Field names should not exceed 30 characters.
  2. Field names are defined in all lower case with '_' instead of spaces. For example, my_field_name.
  3. Field names should represent their purpose. For example, caller_id or assigned_to are appropriate—user1 and user2 are not.
  4. When using a common logical field, use the appropriate field name.

Dictionary Files

  1. A table is distributed in an .xml file with the same name as the table. For example, my_new_table -> my_new_table.xml.
  2. 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

Structural Conventions

  1. Do not replicate core fields. There is already a sys_created_on field. Do not add your own timestamp.
  2. 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:

  1. 40—system default
  2. 80—long single line text
  3. 255—small multi-line field
  4. 4000—medium multi-line field
  5. xxlarge—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

  1. glide_date_time—a timestamp e.g. 12:34:56 on December 25, 2010
  2. glide_date—a date e.g. July 4
  3. glide_time—a time of day e.g. 4:00 PM
  4. glide_duration—a span of time e.g. 4 hours

Forms and Lists

Forms

  1. Every table needs default form, even if there's no direct link to it on the UI.

Lists

  1. Every table needs a default list, even if there's no direct link to it on the UI.

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");