Originally from earlduque/ServiceNow-Developer-Training. Thanks Earl!

Developer Mindset Standards #

  • Do debugging and research when something in your application or program is not working, and if debugging assistance is still needed, contact IET SM for help
    • Take advantage of ServiceNow's debugging tools such as User Criteria Diagnostics, Debug Security Rules, JavaScript debugger
    • Research your issue using sites like ServiceNow community forms or ServicePortal.io
  • Be wary of directly copy-pasting code found online into your programs. Read through it first and understand what you are copying
  • Try new coding ideas or concepts in Sand first, before implementing it in Dev
  • Reference good documentation
  • Do not write hundreds of lines of code in one sitting. Instead, write a few lines of code at at time, and test as you go to ensure it works as expected
  • Reference https://stackoverflow.com/help/how-to-ask when asking other development teams for assistance, rather than asking "this doesn't work, why?"
  • Write/provide good documentation for the things you make

Script Include Standards #

  • Generally speaking, create new script includes for individual applications, catalogs items, or functions.
    • As opposed to one script include for several catalog items, which may cause problems with delegated develpment.
  • Only return information that the calling script will need
  • Use JSON.stringify and JSON.parse instead of JSON.encode and JSON.decode
  • Use Script Includes instead of Global Business Rules
  • Use existing script includes when possible
  • Avoid hardcoding values by using System Properties and Messages
  • Remove logging and temporary comments before moving to production.
  • Copy out-of-box script includes and edit the copy instead of editing the original.

Workflow Standards #

A ServiceNow workflow is used to automate processes. A workflow is a sequence of activities, such as generating records, notifying users of pending approvals, or running scripts. Workflows contain activities that are a set of instructions, including but not limited to approvals, scripting, timers, and email notifications.

General #

  • Include the Workflow: Standard Open Message at the beginning of the item workflow.
  • Include the Workflow: Standard Close Message at the end of the item workflow.
  • When possible, notifications should be created via the Create Event activity which then triggers a notification. Notification activities are also acceptable but Create Event is preferred. Do not send notifications via a Run Script activity.
  • All activities should lead to the End activity.
  • Any workflow section that is repeatable should be made into its own workflow so that it can be used as a sub-workflow in other workflows.

Good Practices for Workflow Design #

  • Use the workflow validation tool provided by ServiceNow.
  • Use the workflow scratchpad. Pass data between workflow activities.
  • Use else/catch-all logic to handle exceptions
  • It is preferred that approval requirements are handled at the start of a workflow.
  • Tasks that the user cancels or skips should avoid canceling the entire Request or downstream tasks in separate and independent request items.
  • Split large or complex workflows into smaller sub-flows.
  • Using sub-flows enables unit testing and reuse.
  • Data can be passed between sub-flows using workflow inputs and return values

Workflow States #

  • All RITM (Request Item) workflows should have a beginning state and an end state even if completely automated.
  • Set the RITM state to “Work in Progress” at the beginning of the workflow.
  • Set the RITM assignment group to the relevant group at the beginning of the workflow.
  • At the end of a workflow, set the RITM state to “Closed Complete.”
  • At the end of the workflow's failure path (if there is one), set the RITM state to “Closed Incomplete.”
  • “Closed Skipped” is rarely used in RITM workflows, as it means there is no work to be done. The standard is to set the RITM state to “Closed Incomplete” instead.
  • Failure paths should never cause a RITM state of “Closed Complete.”

Workflow Stages #

  • If there is an Approval request, set the stage title to “Waiting for Approval.” at a minimum, it is preferred that you customize this stage to say “Waiting for approval from [group]”
  • If there is a Catalog Task, set stage names to “Fulfillment.” Use “Fulfillment” instead of “Delivery” unless both are being used. As with Approval, it is preferred that you make the stage name more descriptive.
  • Do not use the "Request Approved" stage (this pertains to the Request Item (RITM), not the approval request.
  • Completion Paths
  • Set the last activity before End activity to “Completed” stage

Failure Paths #

  • When a Catalog Task completion path exists, set the failure path to the “Request Cancelled” stage.
  • Only use the “Request Cancelled” stage for a path with no Catalog Tasks or Approvals (e.g., checking to see if the submitter of the item is authorized to submit the item).
  • Do not set additional stages for more than one failure path.

Render stages from a workflow-driven method. #

  • The Stage order should be Computed.
  • Stage values and their corresponding display values must be the same.
  • Ensure that the “End” activity can never be reached earlier than any other intended activity on the workflow, as this will cause the workflow to end regardless of anything else still in progress on the workflow.
  • Ensure workflows that are completed have been published
  • In approval activities that have group approvals, utilize the “Approval - User” activity instead of the “Approval - Group” activity unless you understand the differences and need the exact functionality of the latter.
  • Wait for condition activities should wait for changes to the exact record being watched
  • It is preferred that workflows eventually reach the end activity.

Workflow Notifications #

  • Minimize the number of notifications sent to users.
  • Do not send redundant or duplicate notifications.
    • Example: Approvals generate notifications automatically from notifications configured on the approval table. Your workflow does not need to send a notification letting a user know if it has been approved or rejected.
  • Avoid hardcoding notifications. Use independent notifications.

Update Sets #

Update Set Naming Conventions #

Use a consistent naming convention for update sets.

  • Create at least one local update set and switch from the Global update set to the local one before beginning work.
  • At a minimum, update sets must have a unique name that identifies the originating campus organization, concise description, and implementation sequence. A reference to the project requirement is also recommended to ensure traceability to customer requirements such as:
    • org: Primary developer organizational acronym
    • reference: External reference number
    • desc: Short description
    • seq/date: (optional) Sequence number or version or date
    • Example: IET STRY0001234 Incident Hotfix 3 2020.01.12
  • The standard date format is YYYY. MM. DD.
  • Do not use the word “default” anywhere in your update set name

Good Practices for Update Sets #

  • Never delete an Update Set.
  • Never re-open previously completed update sets. Create new ones instead.
  • Never manually merge update sets. Utilize batch functionality instead.
  • Before completing an update set, review the update set to ensure that the only updates included pertain to the desired work.
  • Preview update sets before committing them.
  • Identify dependencies between update sets. Follow naming conventions standards to specify the correct order for migrating them to the next instance.
  • Remove all debugging scripts and system properties before marking an update set as Complete.
  • In the dev instance, completed update sets should never be placed into a batch after it has been completed
  • Do not transfer updates between update sets manually. Seek administrative assistance when update sets contain incorrect updates.
  • Test your work before you complete your update set.

Instance Administrators #

  • When preparing for production release, batch all updates for that release together
  • When pulling to production, delete all irrelevant update sets from the loaded table

UI Policies Standards #

  • When possible, use a UI Policy to set field attributes to mandatory, read-only, or visible rather than a Client Script
  • Avoid adding the same variable to multiple UI Policies
  • Do not make a hidden variable mandatory

UI Actions Standards #

  • Use a distinctive name to distinguish from other UI Actions
  • Use buttons, menus, and links appropriately in forms and lists. For example, do not clutter a form with too many buttons.
  • Avoid putting all necessary logic in the UI Action, it is preferred to leverage Business Rules or Script Includes instead
  • Do not modify commonly used UI Actions such as Save or Delete
  • Add role restrictions to buttons you do not want accidentally pressed

Scripting Standards #

GlideRecords #

  • Do not name your GlideRecord instantiations as simply gr as this may conflict with other running GlideRecords.
  • Instead, name them something like table_gr or function_gr
  • Remove logging and unnecessary comments prior to promoting toward production
  • Do not use client-side GlideRecords, instead use GlideAjax
  • For complex GlideRecord queries, it is preferred to generate encoded query strings through the list filter and using that with addEncodedQuery, rather than using a series of addQuery and addOrCondition.

GlideAjax #

  • Only return information that is going to be used by the client.

General #

  • Avoid naming globally used variables as i as that may conflict with other scripts running.
  • Make code easy to read with appropriate white-space, indentation, and comments
  • When appropriate, verify that variables and fields have a value before using them
  • Avoid using hard-coded values

Roles Standards #

  • Roles should never be assigned directly to users
    • Assign roles to groups then assign members to that group
    • If needed for deployment, utilize the Add to update set tool installed in development to add any record relevant to group/role membership:
      • sys_user_group
      • sys_user_grmember
      • sys_group_has_role
      • sys_user_has_role
      • sys_user
      • sys_user_role
  • Do not use application roles as a way to be able to edit configurations in production. Files typically included in update sets should follow a developement process (dev to test to production).
  • Do not assign roles that would grant configuration access in the production environment unless it is agreed upon that the receiving group and users should have the access.
  • Do not add new role inclusions to existing out-of-box roles if those roles are already being utilized elsewhere.
  • It is preferred that new roles are created within scoped applications (not Global).
  • Do not ever include the admin or security admin role in a group
  • Do not grant admin access to other users. A rule is in place for IET Service Management to be notified every time this happens.
  • New ROLE groups for granting access to new roles should be requested from IET Service Management.

Service Portal Standards #

Aka Widgets, Pages, and the front-end.

Portals #

  • New portals should be vetted by the TAG or IET Service Management as they may be granting access or read access to items/records that are not intended for the public
  • Follow campus design standards (eg. common footer, color schemes, font-families, etc.)

Widgets #

  • Do not display restricted information unless the user is logged in and is supposed to be able to see such information.
  • Design widgets to be re-usable
  • Do not edit other application widgets without permission
  • Copy out-of-box widgets and edit the copy instead of editing the original.
  • Be aware of how many libraries you import as it can impact performance.

Pages #

  • If using role restrictions, evoke CAS for users not logged in first.

Plugins, ServiceNow Store, and External Update Sets Standards #

Plugins #

  • Generally speaking, since some plugins affect other parts of the instance and some plugins will completely change the architecture of the instance, IET Service Management should be contacted to activate plugins in the Development, Test, and Production instances.
  • Plugins are typically not reversable once installed, so use caution and review the dependencies before activating.
  • Plugin activations in sub-production instances can be requested here https://ucdavisit.service-now.com/servicehub/?id=ucd_cat_item&sys_id=296c901d134b6b003527bd122244b087

ServiceNow Store #

  • Only users with ServiceNow HI accounts are able to request entitlements from the ServiceNow Store.
  • If your department does not have a HI representive, contact IET Service Management for assistance.

External Update Sets #

  • The UC Davis ServiceNow instances contain sensitive information and therefore external update sets should be implemented with caution.
  • Fully review every update within the update set to ensure that the intended functionality and only the intended functionality is part of the update.
  • Do not implement external update sets if they look like they may affect other developers work negatively or if they would turn off functionality that is currently in-use in some way by another area in the instance.
  • Do not implement update sets that requires outside connections to unknown sources.

Glide Method usages #

GlideRecord #

  • Use when attempting to get information from specific records
  • Don't use for attempting to do calculations on groups of records, use GlideAggregate instead
  • Only use on server scripts (usable in client scripts but do not do this, opt for GlideAjax instead)

GlideAggregate #

  • Use when doing calculations on groups of records
  • Only use on server scripts

GlideAjax #

  • Use when you need information from the server after the client has finished loading the page
  • Only use on client scripts

GlideElement #

  • Used to operate on fields of the currently selected GlideRecord
  • Only use on server scripts

GlideSystem #

  • Use to get information from the system
  • Only use on server scripts

GlideDateTime #

  • Use to perform date-time operations
  • Only use on server scripts

GlideUser #

  • Use when getting session infromation about the current logged-in user
  • Only use on client scripts

General instance restrictions #

  • Do not promote update sets, install plugins, install applications, update applications, or change system properties during business hours as it automatically evokes a cache flush.
  • Do not edit functionality for an application owned by another group without express permission from the TAG or IET Service Management.
  • Do not export restricted information to external systems or instances.
  • Do not impersonate other admin accounts to create updates.
  • Do not grant admin access to other users. A rule is in place for IET Service Management to be notified every time this happens.
  • Do not share admin credentials
  • Do not use admin accounts to look at restricted records. All record views are recorded in the database.
  • Report vulnerabilities found to IET Service Management.

Flow Designer Standards #

  • Since flows are not tied to tables/records like workflows are, they can be easily configured to run in any situation. That being said, always approach flow triggers with the perspective of "do not allow this to run unless absolutely needed" or else many flow contexts will accidentally be created.
  • Do not edit base system actions and flows. Editing these will cause them to not immediately receive future updates from ServiceNow.
  • Flows should be within scoped applications whenever possible (not Global).
  • When possible use IntegrationHub to handle authentications instead of recreating your own
  • Never test flows in a production environment
  • Never develop flows in a production environment
  • Do not create conflicting logic with already active business rules and workflows

Documentation Standards #

  • For scripts
    • Comment code as if the original author will not be around anymore
    • Comment on functions with full parameter and return descriptions
  • For others
    • Determine if a KB article is necessary
    • Otherwise provide a good description in the description field
  • Keep comments/documentation as accurate and updated as possible
  • Ensure documentation is well-written, clear, and meaningful
  • Do not be verbose and unnecessary with your comments. For example, commenting about initializing a GlideRecord or variable.

Client Script Standards #

  • Use Client Scripts to validate user input
  • When possible, use a UI Policy to set field attributes to mandatory, read-only, or visible rather than a Client Script
  • Do not create Global Client Scripts, instead create them on Base Tables that can be inherited for all child/extending tables
  • If possible, avoid DOM Manipulation
  • Do not use GlideRecord in Client Scripts, use GlideAjax instead
  • Always remove console logging and alerts prior to completion
  • If creating Client Scripts for Catalog Items, ensure that it works in the Service Portal

Catalog Item Standards #

Request catalogs and their catalog items (forms) are used to describe, support, and request services from service providers.

Catalog Item Style Guide #

  • Use the standard style guide to design catalog items.
  • The catalog request item style guide is maintained on the ServiceNow in knowledge article KB0000991. Printed copies are considered drafts.

Request Catalog Style Guide #

This style guide is a set of standards to help the information technology community develop ServiceNow Request Catalog items.

This style guide follows:

  • The Associated Press (AP) style guide and The Chicago Manual of Style, which UC Davis Strategic Communication follows
  • ServiceNow product documentation

Audience #

  • Staff who have oversight and content management responsibilities for ServiceNow
  • IT community developers who work on ServiceNow modules, applications, and system components utilizing the Item Designer

Purpose #

The Request Catalog is for service offerings. Services offerings may include both products and services.

Request Item Writing Tips #

  • Avoid capitalizing every word in a header, question or phrase. The first letter of the first word of variables in a catalog item should be capitalized (i.e. Phone number). Capitalize professional titles, organizations, and other proper nouns, but in general, avoid the use of caps.
  • Avoid the use of acronyms. If an acronym is required, the full name should be written out the first time it is used with its corresponding acronym in parenthesis (i.e. Information and Educational Technology (IET)).
  • Use clear and concise language. For variable questions, typically verbs are not necessary. (i.e. “Requestor’s job title” rather than “Enter the requestor’s job title.”)

General Formatting #

A cascading style sheet (CSS) has been created that adheres to University guidelines. This style sheet applies standard formatting to all aspects of the Service Hub, including the public-facing Knowledge Base.

  • Font Tags - Do not change or insert Font Tags into any allowable HTML field. This erroneous code diminishes the set standards. Bold or italic may be used for impact on the content it references.
  • Phone numbers - Use the traditional formatting convention for phone numbers:
    • Area code followed by 7 digits; (NPA) NXX-XXXX where NPA is the area code and NXX-XXXX is the subscriber number
    • Area code wrapped in parentheses "( )"
    • The subscriber number is separated by a hyphen ("-")
  • Dates - Use International Organization for Standardization (ISO) format:
    • Four-digit year first, followed by month, then day: YYYY-MM-DD
    • With each separated by a hyphen ("-")
    • Numbers less than 10 preceded by a leading zero
    • Years expressed as "0" prior to year 1 and as "-1" for the year prior to year 0 (and so forth)

Form Design Guidelines #

  1. Standard content blocks. All request forms should maintain the three content block standard.
    1. Customer Information – This section captures the customer's details including contact method, department, and any relevant authorization information. This serves as validation of who is entering information into the form. There are two variable sets available for this block, one with Request on behalf of, and one without. This section includes the following standard fields.
      1. Primary Contact - UI policy to auto-populate with CAS authentication
      2. Email – auto-populates
      3. Telephone – auto-populates
      4. Request on behalf of – optional field
    2. Request Information – This is the body of the form. The variables in this block must be held in containers. The number of questions in this block is determined by the requirements of the request.
    3. Additional Information – This content block is for supplemental information such as attachments or additional information that are not captured in the body of the form. There are two variable sets available, Include Billing and Exclude Billing. Do not use the Additional Information variable set if the RITM workflow is completely automated. The customer may assume that information entered will be reviewed.
  2. Variable sets. Variable sets are standard sets of fields that can be used across multiple forms. Using variable sets keep forms standardized and make for a consistent user experience. They should be used whenever possible.
  3. Agreement checkbox. Include this checkbox on impactful items that deal with matters such as account cancellation or finances. A script has been developed and is available which inactivates the "Submit" button unless the agreement is checked/acknowledged.
  4. Columns. Column usage will be up to the form designer's discretion, but here are some general guidelines:
    1. Fields that trigger/reveal other fields should generally be two columns, revealing the other field either below or to the right of the first field.
    2. Most multi line text fields should be one column spanning the width of the page.
    3. Single line text fields will generally be one column, spanning half the page.
  5. Drop downs. If a drop down field is mandatory, it should default to "None" so the requester must choose one of the options before submission is allowed. If a drop down field is not mandatory, a "None" option is not needed.
  6. Multi line vs Single line Question dependent, but multi lines should only be used for lengthy questions such as asking for additional detail.

Guide to Usability #

  • Tooltips (rollover or hover functionality) are the primary method used for "help text." The majority of variables in a form will require a tooltip; the exception to this standard is when the variable name is its definition.
  • More information should be used sparingly in support of more complicated content within the variable. This is a secondary solution to the tooltip. More information appears in grey under the input field. Do not include information directed to an individual or group, requirements, or terms and conditions.
  • Common variables used in form design:
    • Select Box - drop down menu item to be used in cases of a single item needing to be selected from a list of items.
    • Yes / No - a select box variable type used for questions with a Yes or No answer.
    • Check Boxes - individual options that are true or false. These should be used in a vertical alignment.
    • Radio buttons - should be used in cases where one of four options, or less, need to be selected. Best practice is to use this when all options need to visible on the form.
    • Submit button - located in the lower left corner for web submission forms.

A complete list of variable types can found here.

Business Rules Standards #

  • If possible, use conditions in Business Rules
  • Do not use current.update() in a Business Rule script
  • Just like current.update(), do not script a Business Rule that may accidentally activate itself again upon running
  • Do not create Global Business Rules, it is preferred to use Script Includes instead.
  • Understand if you intend for other Business Rules to run due to the running of this Business Rule. If not, ensure that you set .setWorkflow to false
  • Use Business Rules to validate input on top of Client Scripts/UI Policies since fields can be editable outside of fields.

API Usage Standards #

Outbound #

  • Outbound calls to external APIs via REST, SOAP, or other methods are allowed.
  • Do not store API keys in plain-text on scriptstable records, instead put them in system properties.
  • Intentionally rate limit outbound calls that occur rapidly (several per second). Make sure these calls are condition-based for when they occur instead of timer based.
  • Do not use ServiceNow to call an external API to check for updates rapidly. If you need live updates, attempt to create an inbound integration that is triggered by the external system, instead of polling for updates.
  • Prefer creating outbound service records that are called in script rather than creating an entire outbound call in individual scripts.

Inbound #

  • Do NOT create an unauthenticated API for inbound calls
  • Always prefer to use a more secure authentication method like OAuth 2.0 over a simple username/password authentication
  • Do not store API keys in plain-text on scripts or table records, instead put them in system properties.
  • Do not create or configure table APIs for campus-used tables unless approved by the campus TAG or IET Service Management (eg. the incident table).
  • Some tables have ACLs or Business Rules that intend to restrict some information that is accessible (eg. incident, sc_req_item, sysapproval_approver, sc_task, x_uocd2_business_m_case, etc.). Always use discretion when divulging information on these tables for an API. Always program to satisfy that these ACLs and rules are not broken.

ACL standards #

  • Understand how ACLs are evaluated and in what order they are run before attempting to configure ACLs
  • Never leave anything in the script field if the ACL's advanced field is false.
  • Understand that ACLs impact instance performance, the more complex the query and the more that are running, the slower the interaction will be.
  • Whenever possible, a matching Before Business Rule Query should be created for every ACL that is designed to remove records from a person's view.